Executable line counting (exLOC) metrics: integrate into analyzer + context telemetry

[mojoatomic]

Summary
Implement executable line counting (exLOC) as the primary line metric for context-aware telemetry, while continuing to report physical lines for visibility. This aligns enforcement/assessment with real code changes and stops penalizing documentation.

Why

• Physical lines penalize comments/docs and misrepresent refactors.
• exLOC correlates better with complexity and health.

Prior Art

• Prototypes in /line_count (EXECUTABLE-LINES.md, line-counter.js, analyzer-enhanced.js, tests).

Scope

• Analyzer: compute and emit lines.physical, lines.executable, lines.comments, lines.commentRatio.
• Telemetry (context-aware output): print deltas for physical vs executable and add a short assessment.
• Configuration (.ai-coding-guide.json):
  • ratchet.lineCountMode: "executable" | "physical" (default: "executable" for telemetry; gating unaffected)
  • ratchet.metrics.trackPhysicalLines/trackExecutableLines/trackCommentRatio (booleans; default true)
• CI: keep non-blocking; no gating changes in this issue.
• Docs: add EXECUTABLE-LINES.md and a section in CONTEXT-AWARE-LINTING.md.
• Tests: unit for line counting; integration snapshot for telemetry output.

Non-Goals (here)

• Intent detection, domain-awareness, temporal trends (tracked separately; this lays the foundation).
• Changing ESLint rule thresholds (we already skip comments in limits).

Implementation Plan

• Create metrics/line-counter.js (production location) with removeComments/removeBlankLines/countExecutableLines/getLineMetrics.
• Wire into analyze pipeline (bin/cli.js analyze) to populate metrics in analysis-current.json.
• Update context-aware ratchet output to include Lines section with deltas (physical vs executable) and comment ratio.
• Config: read ratchet.lineCountMode + metrics flags from .ai-coding-guide.json (fallbacks safe).
• Unit tests for line-counter (ported from /line_count and aligned to production path).
• Integration test: run lint:json + analyze:current and snapshot Lines section.
• Docs: new docs/EXECUTABLE-LINES.md + link from CONTEXT-AWARE-LINTING.md.

Acceptance Criteria

• Analysis outputs lines.physical, lines.executable, lines.comments, lines.commentRatio.
• Context-aware run prints Lines block with deltas and clear assessment.
• Gating remains unchanged (traditional ratchet only) pending Health Gating Enforcement for Context-Aware Ratchet #203.
• Tests green; CI step non-blocking and visible.
• Docs published.

Cross-links

• Burn-in + promotion: Ratchet 2.0: context-aware code health, critical vs minor policy, weighted/density metrics, heuristics (Phase 2 next) #198
• Health gating: Health Gating Enforcement for Context-Aware Ratchet #203 (future: gate on exLOC-based density/health)
• Ongoing refactors: [Phase 3A] Reduce Cyclomatic Complexity (≥30% cut) across top hotspots #182/[Phase 3B] Architecture splits (>=30% reduction in max-lines/length warnings) #183 (this will provide better telemetry for them).

Notes

• Use /line_count prototypes as a starting point; refine regexes and edge cases over time.
• We can later add language-aware parsing if needed.

[mojoatomic]

Progress update + dogfood plan for executable lines (exLOC)

Status

• Prototypes exist in /line_count (counter, analyzer, tests)
• ESLint flat config updated to ignore /line_count during burn-in to avoid domain-term/architecture noise
• Issue scope + acceptance defined; no gating changes here

Dogfood plan (this repo)

• Productionize line-counter in lib/metrics/line-counter.js (API: removeComments, removeBlankLines, countExecutableLines, getLineMetrics)
• Wire into analyze path (bin/cli.js analyze) to emit lines.physical/executable/comments/commentRatio in analysis-current.json
• Context output: add a Lines section with physical vs executable deltas + short assessment
• Config: ratchet.lineCountMode (default: executable for telemetry), metrics flags (trackPhysicalLines, trackExecutableLines, trackCommentRatio)
• Unit tests ported from /line_count; integration snapshot of context Lines block
• Docs: docs/EXECUTABLE-LINES.md + link from CONTEXT-AWARE-LINTING.md
• CI: visible in non-blocking telemetry step (no gating)

Notes

• exLOC is telemetry-first; traditional ratchet unchanged and remains the gate until Health Gating Enforcement for Context-Aware Ratchet #203 promotion
• After a few PRs, we’ll calibrate thresholds and consider density/health using exLOC

Cross-links

• Ratchet 2.0: context-aware code health, critical vs minor policy, weighted/density metrics, heuristics (Phase 2 next) #198 burn-in/promotion
• Health Gating Enforcement for Context-Aware Ratchet #203 health gating (future: exLOC-based density/health)
• [Phase 3A] Reduce Cyclomatic Complexity (≥30% cut) across top hotspots #182/[Phase 3B] Architecture splits (>=30% reduction in max-lines/length warnings) #183 refactors will benefit from truer signals

[mojoatomic]

Opened PR #206 to integrate executable line metrics into analyzer + ratchet context.

Key points

• Analyzer now emits lines (physical, executable, comments, commentRatio) and meta.lineCountMode.
• Ratchet prints a non-blocking Lines section with deltas. Gate unchanged.
• Docs added: EXECUTABLE-LINES.md; linked from CONTEXT-AWARE-LINTING.md.
• Tests added for line-counter.
• ESLint excludes scripts/** from guardrail rules to avoid tooling noise.

Next

• After a few PRs, we can calibrate thresholds and consider gating health on exLOC-based density (Health Gating Enforcement for Context-Aware Ratchet #203).

[mojoatomic]

Merged PRs:

• Refactor: project-config read path (extract helpers, reduce complexity) #205 Refactor: project-config read path
• feat(exloc): analyzer + ratchet context telemetry for executable line metrics #206 exLOC telemetry integration

Follow-up PR incoming to add:

• Integration test asserting analysis JSON lines + meta.lineCountMode
• Ratchet FAIL-case “Lines” printing with assessment (executable ↑/↓, docs ↑/↓)
• Doc expansions with config example and output sample

Next steps:

• Dogfood across a few PRs to calibrate (no gating changes yet)
• Then consider health gating on exLOC-based density (tracked in Health Gating Enforcement for Context-Aware Ratchet #203)

[mojoatomic]

Opened follow-up PR #207 (exLOC polish):

• Tests for analyze JSON (lines + meta) and ratchet FAIL-case Lines + Assessment
• Ratchet prints Lines on OK and FAIL with brief assessment on FAIL
• Docs: config example + sample output
• ESLint ignores for sandbox/scripts tooling

Next: dogfood a few PRs, then calibrate thresholds; consider gating via #203 afterwards.