feat: report aggregate comment line stats

Author: aksOps

CHANGELOG.md

@@ -5,6 +5,7 @@
 - Parse `.gitignore`, `.ignore`, and `.git/info/exclude` during working-tree scans.
 - Add `--exclude-tests` to skip well-known test-case paths from aggregate scan analysis.
 - Replace the linear score deduction with a bounded issue-density curve so noisy large repositories do not collapse to zero.
+- Add aggregate commented-line statistics to scan and diff reports.
 
 ## 0.0.1 - 2026-06-30
 

README.md

@@ -95,6 +95,12 @@ code-signal detects and analyzes these languages with built-in lexical/parser ch
 
 Detection uses extensions, shebangs, and common manifests such as `go.mod`, `package.json`, `pyproject.toml`, `Cargo.toml`, `pom.xml`, Gradle files, `.csproj`, `.sln`, `composer.json`, `Gemfile`, `Dockerfile`, `Containerfile`, and `*.dockerfile`.
 
+## Aggregate line statistics
+
+Scan JSON includes `comment_lines` and `comment_density_percent` beside existing line totals. The same aggregate fields are reported for `totals`, `by_language`, and `by_module`; diff JSON includes before/after/delta values under `totals_delta`.
+
+Comment detection is lexical and language-aware: it recognizes `//`, `#`, and `/* ... */` style comments where those markers are valid, ignores markers inside quoted strings/raw strings, and never emits per-file locations or source snippets.
+
 ## Ignore files, test exclusion, and skip policy
 
 Working-tree scans parse `.gitignore`, `.ignore`, and `.git/info/exclude` using gitignore-style rules before reading candidate files.

internal/cli/cli.go

@@ -558,6 +558,8 @@ func printScan(stdout io.Writer, scanReport model.ScanReport) error {
 		scanReport.Totals.Issues, scanReport.Totals.Errors, scanReport.Totals.Warnings, scanReport.Totals.Info)
 	fmt.Fprintf(&builder, "Files scanned: %d | Lines scanned: %d | Files skipped: %d\n",
 		scanReport.Totals.FilesScanned, scanReport.Totals.LinesScanned, scanReport.Totals.FilesSkipped)
+	fmt.Fprintf(&builder, "Comment lines: %d (%.1f%%)\n",
+		scanReport.Totals.CommentLines, scanReport.Totals.CommentDensityPercent)
 	fmt.Fprintf(&builder, "Languages: %s | Modules: %d (%s)\n",
 		joinOrNone(scanLanguages(scanReport)), scanModuleCount(scanReport), moduleProfileText(scanReport))
 	printDuplicationSummary(&builder, scanReport.Duplication)

internal/delta/delta.go

@@ -25,13 +25,15 @@ func Compare(base, head model.ScanReport) model.DiffReport {
 
 func compareTotals(base, head model.ScanTotals) model.TotalsDelta {
 	return model.TotalsDelta{
-		FilesScanned: countDelta(base.FilesScanned, head.FilesScanned),
-		FilesSkipped: countDelta(base.FilesSkipped, head.FilesSkipped),
-		LinesScanned: countDelta(base.LinesScanned, head.LinesScanned),
-		Issues:       countDelta(base.Issues, head.Issues),
-		Errors:       countDelta(base.Errors, head.Errors),
-		Warnings:     countDelta(base.Warnings, head.Warnings),
-		Info:         countDelta(base.Info, head.Info),
+		FilesScanned:          countDelta(base.FilesScanned, head.FilesScanned),
+		FilesSkipped:          countDelta(base.FilesSkipped, head.FilesSkipped),
+		LinesScanned:          countDelta(base.LinesScanned, head.LinesScanned),
+		CommentLines:          countDelta(base.CommentLines, head.CommentLines),
+		CommentDensityPercent: percentDelta(base.CommentDensityPercent, head.CommentDensityPercent),
+		Issues:                countDelta(base.Issues, head.Issues),
+		Errors:                countDelta(base.Errors, head.Errors),
+		Warnings:              countDelta(base.Warnings, head.Warnings),
+		Info:                  countDelta(base.Info, head.Info),
 	}
 }
 
@@ -128,3 +130,9 @@ func countDelta(before, after int) model.CountDelta {
 		Delta:  after - before,
 	}
 }
+
+func percentDelta(before, after float64) model.PercentDelta {
+	before = roundTenth(before)
+	after = roundTenth(after)
+	return model.PercentDelta{Before: before, After: after, Delta: roundTenth(after - before)}
+}

internal/generic/generic.go

@@ -87,11 +87,13 @@ func AggregateSnapshot(entries []model.SnapshotEntry, facts map[model.BlobKey]mo
 
 		totals.FilesScanned++
 		totals.LinesScanned += blobFacts.Lines
+		totals.CommentLines += blobFacts.CommentLines
 		totals.Errors += blobFacts.Issues.Errors
 		totals.Warnings += blobFacts.Issues.Warnings
 		totals.Info += blobFacts.Issues.Info
 		totals.Issues += blobFacts.Issues.Errors + blobFacts.Issues.Warnings + blobFacts.Issues.Info
 	}
+	totals.CommentDensityPercent = model.LineDensityPercent(totals.CommentLines, totals.LinesScanned)
 	return totals
 }
 
@@ -181,8 +183,12 @@ func analyzeBlobLines(language string, data []byte, cfg Config, catalog rules.Ca
 		counts := countLineIssues(line, cfg, nesting, lane)
 		counts.mergeConflicts = mergeConflict.count(line)
 		mergeConflicts += counts.mergeConflicts
+		commentText, hasComment := comments.scan(line)
+		if hasComment {
+			facts.CommentLines++
+		}
 		if lane.todo {
-			counts.todos = comments.countTodoMarkers(line)
+			counts.todos = countTodoMarkers(commentText)
 		}
 		if lane.riskyShell {
 			counts.riskyShell = riskyShell.count(line)
@@ -1009,10 +1015,6 @@ func newCommentScanner(lane languageRuleLane) commentScanner {
 	}
 }
 
-func (scanner *commentScanner) countTodoMarkers(line string) int {
-	return countTodoMarkers(scanner.text(line))
-}
-
 func countTodoMarkers(line string) int {
 	count := 0
 	for _, marker := range []string{"TODO", "FIXME", "HACK"} {
@@ -1029,12 +1031,13 @@ type commentQuoteState struct {
 	escaped        bool
 }
 
-func (scanner *commentScanner) text(line string) string {
+func (scanner *commentScanner) scan(line string) (text string, hasComment bool) {
 	var comments []string
 	for i := 0; i < len(line); {
 		if scanner.inBlock {
 			text, next, closed := blockCommentSegment(line, i)
 			comments = append(comments, text)
+			hasComment = true
 			scanner.inBlock = !closed
 			i = next
 			continue
@@ -1045,19 +1048,21 @@ func (scanner *commentScanner) text(line string) string {
 		}
 		if marker, ok := matchingCommentMarker(line[i:], scanner.lineMarkers); ok {
 			comments = append(comments, line[i+len(marker):])
+			hasComment = true
 			break
 		}
 		if scanner.blockComments && strings.HasPrefix(line[i:], "/*") {
 			text, next, closed := blockCommentSegment(line, i+len("/*"))
 			comments = append(comments, text)
+			hasComment = true
 			scanner.inBlock = !closed
 			i = next
 			continue
 		}
 		i++
 	}
 	scanner.quoteState.finishLine()
-	return strings.Join(comments, "\n")
+	return strings.Join(comments, "\n"), hasComment
 }
 
 func blockCommentSegment(line string, start int) (text string, next int, closed bool) {

internal/generic/generic_test.go

@@ -108,6 +108,32 @@ func TestAnalyzeBlobCountsGenericRulesAggregately(t *testing.T) {
 	}
 }
 
+func TestAnalyzeBlobCountsCommentLinesAggregately(t *testing.T) {
+	data := strings.Join([]string{
+		"package main",
+		"const url = \"https://example.invalid/not-comment\"",
+		"// package comment",
+		"func main() { println(url) } // inline comment",
+		"/* block start",
+		"block middle",
+		"*/",
+		"const raw = `// not a comment`",
+	}, "\n") + "\n"
+
+	facts := AnalyzeBlob(testKeyForLanguage("comments", "go"), []byte(data), Config{}, rules.DefaultCatalog())
+	payload, err := json.Marshal(facts)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var decoded map[string]any
+	if err := json.Unmarshal(payload, &decoded); err != nil {
+		t.Fatalf("unmarshal facts JSON: %v", err)
+	}
+	if got := decoded["comment_lines"]; got != float64(5) {
+		t.Fatalf("comment_lines = %#v, want 5 in %s", got, payload)
+	}
+}
+
 func TestAnalyzeBlobSkipsGeneratedAndMinifiedContent(t *testing.T) {
 	catalog := rules.DefaultCatalog()
 	tests := []struct {

internal/model/model.go

@@ -85,33 +85,38 @@ type BlobKey struct {
 // BlobFacts stores aggregate facts for a single analyzed blob. It intentionally has
 // no file findings, snippets, or line/column locations.
 type BlobFacts struct {
-	Lines      int                      `json:"lines"`
-	Issues     IssueCounts              `json:"issues"`
-	ByCategory map[Category]IssueCounts `json:"by_category,omitempty"`
-	ByRule     map[string]RuleCount     `json:"by_rule,omitempty"`
-	Skipped    bool                     `json:"skipped,omitempty"`
-	SkipReason string                   `json:"skip_reason,omitempty"`
+	Lines        int                      `json:"lines"`
+	CommentLines int                      `json:"comment_lines,omitempty"`
+	Issues       IssueCounts              `json:"issues"`
+	ByCategory   map[Category]IssueCounts `json:"by_category,omitempty"`
+	ByRule       map[string]RuleCount     `json:"by_rule,omitempty"`
+	Skipped      bool                     `json:"skipped,omitempty"`
+	SkipReason   string                   `json:"skip_reason,omitempty"`
 }
 
 // ScanTotals stores top-level aggregate counters for one complete snapshot scan.
 type ScanTotals struct {
-	FilesScanned int `json:"files_scanned"`
-	FilesSkipped int `json:"files_skipped"`
-	LinesScanned int `json:"lines_scanned"`
-	Issues       int `json:"issues"`
-	Errors       int `json:"errors"`
-	Warnings     int `json:"warnings"`
-	Info         int `json:"info"`
+	FilesScanned          int     `json:"files_scanned"`
+	FilesSkipped          int     `json:"files_skipped"`
+	LinesScanned          int     `json:"lines_scanned"`
+	CommentLines          int     `json:"comment_lines"`
+	CommentDensityPercent float64 `json:"comment_density_percent"`
+	Issues                int     `json:"issues"`
+	Errors                int     `json:"errors"`
+	Warnings              int     `json:"warnings"`
+	Info                  int     `json:"info"`
 }
 
 // GroupCounts stores aggregate counters for a language or module grouping.
 type GroupCounts struct {
-	Files    int `json:"files"`
-	Lines    int `json:"lines"`
-	Issues   int `json:"issues"`
-	Errors   int `json:"errors"`
-	Warnings int `json:"warnings"`
-	Info     int `json:"info"`
+	Files                 int     `json:"files"`
+	Lines                 int     `json:"lines"`
+	CommentLines          int     `json:"comment_lines"`
+	CommentDensityPercent float64 `json:"comment_density_percent"`
+	Issues                int     `json:"issues"`
+	Errors                int     `json:"errors"`
+	Warnings              int     `json:"warnings"`
+	Info                  int     `json:"info"`
 }
 
 // ScanReport is the aggregate report for one complete snapshot scan.
@@ -135,15 +140,24 @@ type CountDelta struct {
 	Delta  int `json:"delta"`
 }
 
+// PercentDelta stores an aggregate before/after/delta percentage value.
+type PercentDelta struct {
+	Before float64 `json:"before"`
+	After  float64 `json:"after"`
+	Delta  float64 `json:"delta"`
+}
+
 // TotalsDelta stores top-level aggregate deltas between complete scans.
 type TotalsDelta struct {
-	FilesScanned CountDelta `json:"files_scanned"`
-	FilesSkipped CountDelta `json:"files_skipped"`
-	LinesScanned CountDelta `json:"lines_scanned"`
-	Issues       CountDelta `json:"issues"`
-	Errors       CountDelta `json:"errors"`
-	Warnings     CountDelta `json:"warnings"`
-	Info         CountDelta `json:"info"`
+	FilesScanned          CountDelta   `json:"files_scanned"`
+	FilesSkipped          CountDelta   `json:"files_skipped"`
+	LinesScanned          CountDelta   `json:"lines_scanned"`
+	CommentLines          CountDelta   `json:"comment_lines"`
+	CommentDensityPercent PercentDelta `json:"comment_density_percent"`
+	Issues                CountDelta   `json:"issues"`
+	Errors                CountDelta   `json:"errors"`
+	Warnings              CountDelta   `json:"warnings"`
+	Info                  CountDelta   `json:"info"`
 }
 
 // DiffReport is the aggregate comparison between two complete snapshot scans.
@@ -163,6 +177,14 @@ type DiffReport struct {
 	DuplicationDelta DuplicationDelta        `json:"duplication_delta,omitempty"`
 }
 
+// LineDensityPercent returns part/total as a percentage rounded to one decimal.
+func LineDensityPercent(part, total int) float64 {
+	if part <= 0 || total <= 0 {
+		return 0
+	}
+	return float64((int64(part)*1000+int64(total)/2)/int64(total)) / 10
+}
+
 // DetectedProject describes aggregate project detection results.
 type DetectedProject struct {
 	Root            string   `json:"root,omitempty"`

internal/report/report.go

@@ -18,6 +18,9 @@ func HumanDiff(diff model.DiffReport) string {
 	fmt.Fprintf(&b, "Files scanned: %d -> %d (%+d) | Lines scanned: %d -> %d (%+d)\n",
 		diff.TotalsDelta.FilesScanned.Before, diff.TotalsDelta.FilesScanned.After, diff.TotalsDelta.FilesScanned.Delta,
 		diff.TotalsDelta.LinesScanned.Before, diff.TotalsDelta.LinesScanned.After, diff.TotalsDelta.LinesScanned.Delta)
+	fmt.Fprintf(&b, "Comment lines: %d -> %d (%+d) | comment density %.1f%% -> %.1f%% (%+.1f%%)\n",
+		diff.TotalsDelta.CommentLines.Before, diff.TotalsDelta.CommentLines.After, diff.TotalsDelta.CommentLines.Delta,
+		diff.TotalsDelta.CommentDensityPercent.Before, diff.TotalsDelta.CommentDensityPercent.After, diff.TotalsDelta.CommentDensityPercent.Delta)
 	fmt.Fprintf(&b, "Languages: %s | Modules: %s\n", displayList(languageKeys(diff.LanguageDelta), displayLanguage), displayList(stringKeys(diff.ModuleDelta), identity))
 	fmt.Fprintf(&b, "Issues: %d -> %d (%+d) | Errors: %d -> %d (%+d) | Warnings: %d -> %d (%+d) | Info: %d -> %d (%+d)\n",
 		diff.TotalsDelta.Issues.Before, diff.TotalsDelta.Issues.After, diff.TotalsDelta.Issues.Delta,

internal/scan/scan.go

@@ -512,6 +512,7 @@ func buildReport(entries []model.SnapshotEntry, detection model.DetectedProject,
 		duplicateConfig(cfg),
 	)
 	addDuplicateSummary(&report, duplicateSummary)
+	finalizeCommentStats(&report)
 	scoreReport(&report, cfg)
 	return report
 }
@@ -666,6 +667,7 @@ func addFactToReport(report *model.ScanReport, entry model.SnapshotEntry, fact m
 	issues := issueTotal(fact.Issues)
 	report.Totals.FilesScanned++
 	report.Totals.LinesScanned += fact.Lines
+	report.Totals.CommentLines += fact.CommentLines
 	report.Totals.Errors += fact.Issues.Errors
 	report.Totals.Warnings += fact.Issues.Warnings
 	report.Totals.Info += fact.Issues.Info
@@ -707,12 +709,25 @@ func addFactToReport(report *model.ScanReport, entry model.SnapshotEntry, fact m
 func addGroupFact(group *model.GroupCounts, fact model.BlobFacts, issues int) {
 	group.Files++
 	group.Lines += fact.Lines
+	group.CommentLines += fact.CommentLines
 	group.Issues += issues
 	group.Errors += fact.Issues.Errors
 	group.Warnings += fact.Issues.Warnings
 	group.Info += fact.Issues.Info
 }
 
+func finalizeCommentStats(report *model.ScanReport) {
+	report.Totals.CommentDensityPercent = model.LineDensityPercent(report.Totals.CommentLines, report.Totals.LinesScanned)
+	for language, group := range report.ByLanguage {
+		group.CommentDensityPercent = model.LineDensityPercent(group.CommentLines, group.Lines)
+		report.ByLanguage[language] = group
+	}
+	for module, group := range report.ByModule {
+		group.CommentDensityPercent = model.LineDensityPercent(group.CommentLines, group.Lines)
+		report.ByModule[module] = group
+	}
+}
+
 func uniqueBlobKeys(groups [][]model.SnapshotEntry, cfg config.Config) []model.BlobKey {
 	seen := make(map[model.BlobKey]bool)
 	for _, entries := range groups {

internal/scan/scan_test.go

@@ -96,6 +96,37 @@ func TestScanPathReportsAggregateJSONParseErrors(t *testing.T) {
 	}
 }
 
+func TestScanPathReportsCommentLineStats(t *testing.T) {
+	root := t.TempDir()
+	writeRepoFile(t, root, "main.go", strings.Join([]string{
+		"package main",
+		"// file comment",
+		"func main() {",
+		"println(\"ok\") // inline comment",
+		"/* block comment */",
+		"}",
+	}, "\n")+"\n")
+
+	report, err := ScanPath(context.Background(), root, ScanOptions{})
+	if err != nil {
+		t.Fatalf("ScanPath() error = %v", err)
+	}
+	payload, err := json.Marshal(report)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var decoded map[string]any
+	if err := json.Unmarshal(payload, &decoded); err != nil {
+		t.Fatalf("unmarshal report JSON: %v", err)
+	}
+	assertJSONNumber(t, decoded, "totals.comment_lines", 3)
+	assertJSONNumber(t, decoded, "totals.comment_density_percent", 50)
+	assertJSONNumber(t, decoded, "by_language.go.comment_lines", 3)
+	assertJSONNumber(t, decoded, "by_language.go.comment_density_percent", 50)
+	assertJSONNumberPath(t, decoded, []string{"by_module", ".", "comment_lines"}, 3)
+	assertJSONNumberPath(t, decoded, []string{"by_module", ".", "comment_density_percent"}, 50)
+}
+
 func TestScanPathAggregatesGoParseAndComplexityAggregateOnly(t *testing.T) {
 	root := t.TempDir()
 	writeRepoFile(t, root, "services/api/go.mod", "module example.test/api\n\ngo 1.26\n")
@@ -544,6 +575,26 @@ func writeRepoFile(t *testing.T, repo, name, content string) {
 	}
 }
 
+func assertJSONNumber(t *testing.T, root map[string]any, dottedPath string, want float64) {
+	t.Helper()
+	assertJSONNumberPath(t, root, strings.Split(dottedPath, "."), want)
+}
+
+func assertJSONNumberPath(t *testing.T, root map[string]any, path []string, want float64) {
+	t.Helper()
+	var current any = root
+	for _, key := range path {
+		object, ok := current.(map[string]any)
+		if !ok {
+			t.Fatalf("%s parent = %#v, want object", strings.Join(path, "."), current)
+		}
+		current = object[key]
+	}
+	if current != want {
+		t.Fatalf("%s = %#v, want %.1f", strings.Join(path, "."), current, want)
+	}
+}
+
 func listenUnixSocket(t *testing.T, path string) net.Listener {
 	t.Helper()
 	listener, err := net.Listen("unix", path)