peaks-loop 4.1.1 → 4.1.3

package/dist/services/codegraph/codegraph-upstream-layout.js

@@ -0,0 +1,85 @@
+// src/services/codegraph/codegraph-upstream-layout.ts
+//
+// ONE answer to "where did the installed `@colbymchenry/codegraph` put its
+// files", for the four places peaks-loop reaches into the package.
+//
+// WHY THIS EXISTS (the 1.6.2 upgrade). Before it, one rule covered all four
+// sites: join `dist/…` onto whatever directory upstream's `package.json`
+// sits in. That rule is false from 1.6.x. The main package there is TYPE
+// DEFINITIONS ONLY — `find dist -name '*.js' | wc -l` is 0 — and the runtime
+// moved into a per-platform optionalDependency
+// (`@colbymchenry/codegraph-<platform>-<arch>`), whose own `lib/dist/` holds
+// the entry AND the modules. Every one of the four joins therefore resolved
+// to a path that does not exist, so the binary could not be spawned and the
+// two oracles could not be loaded.
+//
+// The fix is a PROBE, not a version check: the candidates are ordered
+// newest-layout-first (per-platform bundle, then the main package's own
+// `dist/`) and the first one whose `dist/bin/codegraph.js` actually exists
+// wins. So a 0.7.x install still resolves, a future release that moves the
+// files again is found without an edit here, and nothing is decided by a
+// version string that can drift from the filesystem.
+//
+// This module is separate from `codegraph-service.ts` rather than a few more
+// functions inside it, because that file sits under eslint's `max-lines` cap
+// and the resolver does not fit. It has no dependency on the service, so the
+// two oracles can import it without pulling in the service's session and
+// process-runner imports.
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+const CODEGRAPH_PACKAGE_NAME = '@colbymchenry/codegraph';
+/** The directory a 1.6.x per-platform bundle keeps its `dist/` under. */
+const CODEGRAPH_BUNDLE_LIB_DIR = 'lib';
+/**
+ * Directories a `dist/` might hang off, newest layout first.
+ *
+ * The platform bundle is resolved through a require anchored AT the main
+ * package's own `package.json`, never at this module: the bundle is a
+ * dependency OF the main package, so under pnpm's isolated layout it is
+ * linked into the MAIN package's `node_modules/` and is invisible to a
+ * require anchored here. A missing bundle (0.7.x, or a registry mirror that
+ * skipped the optionalDependency) is not an error — the main package's own
+ * `dist/` is the next candidate.
+ */
+function upstreamDistRoots(packageJsonPath) {
+    const bundlePackageName = `${CODEGRAPH_PACKAGE_NAME}-${process.platform}-${process.arch}`;
+    let bundleDir = null;
+    try {
+        const require = createRequire(packageJsonPath);
+        const bundlePackageJson = require.resolve(`${bundlePackageName}/package.json`);
+        bundleDir = dirname(bundlePackageJson);
+    }
+    catch {
+        // A missing bundle is an EXPECTED state, not a swallow: 0.7.x has none,
+        // and a registry mirror that did not mirror the optionalDependency
+        // leaves the install without one. It is reported by the assignment —
+        // the caller below then has exactly one candidate root instead of two.
+        bundleDir = null;
+    }
+    const roots = bundleDir === null ? [] : [join(bundleDir, CODEGRAPH_BUNDLE_LIB_DIR)];
+    roots.push(dirname(packageJsonPath));
+    return roots;
+}
+/**
+ * Resolve upstream's layout for one `package.json` path.
+ *
+ * `packageJsonPath` is a parameter rather than a lookup because the doctor's
+ * yarn-pnp fallback reaches the same package by a filesystem walk and needs
+ * the layout for THAT path, not for whatever `createRequire` finds.
+ */
+export function codegraphUpstreamLayoutFor(packageJsonPath) {
+    const distDirs = upstreamDistRoots(packageJsonPath).map((root) => join(root, 'dist'));
+    const probed = distDirs.find((dir) => existsSync(join(dir, 'bin', 'codegraph.js')));
+    const moduleDir = probed ?? distDirs[0] ?? '';
+    return {
+        binaryPath: moduleDir === '' ? '' : join(moduleDir, 'bin', 'codegraph.js'),
+        moduleDir
+    };
+}
+/** `codegraphUpstreamLayoutFor` for whichever install this process runs against. */
+export function resolveCodegraphUpstreamLayout() {
+    const require = createRequire(import.meta.url);
+    const packageJsonPath = require.resolve(`${CODEGRAPH_PACKAGE_NAME}/package.json`);
+    return codegraphUpstreamLayoutFor(packageJsonPath);
+}

package/dist/services/comments/comment-audit.d.ts

@@ -5,7 +5,9 @@
  * workspace package's `src`, as `.husky/lint-scope.mjs` defines it — rather than
  * a second definition of "product code" written here. Two names for one rule is
  * the failure the parity test in `tests/unit/comments/citation-parity.test.ts`
- * exists to prevent.
+ * exists to prevent, and the parity that second name actually caused is pinned by
+ * `tests/unit/comments/comment-audit.test.ts`, which requires this walk to read the
+ * same number of files the artifact records the ratchet measuring.
  *
  * This is the read side only. Nothing here writes a file: the counts it produces
  * are the numbers a ratchet would start from, and a ratchet seeded from a scan
@@ -13,8 +15,18 @@
  * refuses a legitimate change.
  */
 import { type CommentFileSummary, type CommentFinding, type CommentFindingKind } from './comment-hygiene.js';
-/** Product-code directories, in report order. */
-export declare const COMMENT_SCAN_SCOPE: string[];
+/**
+ * Product-code directories, in report order: `src`, then every package under
+ * `packages/` that has a `src`.
+ *
+ * Derived from the rule rather than enumerated, because `.husky/lint-scope.mjs` says a
+ * new `packages/<anything>/src` joins the enforced scope BY EXISTING. The first version
+ * of this list spelled it `['src', 'packages/peaks-loop-mut/src']`, which was the second
+ * definition of "product code" this file's header claims not to be: the ratchet measures
+ * 953 files and the worklist read 926, so 14 gated narrative rows lived in three
+ * packages no `peaks comments audit` would show and no `prune` could clear.
+ */
+export declare function commentScanScope(projectRoot: string): string[];
 /**
  * Every source file under one scope dir, repo-relative, sorted.
  *
@@ -49,7 +61,6 @@ export type CommentAuditOptions = {
      * misses tracked files the disk dropped, so a row measured over a walk can move
      * while nobody edits source. `git ls-files` filtered by the published scope rule is
      * that population — the same list the eslint, prettier and silent-warning legs
-     * share (rid `2026-10-03-silent-warning-scope`).
      */
     readonly files?: readonly string[];
 };

package/dist/services/comments/comment-audit.js

@@ -5,7 +5,9 @@
  * workspace package's `src`, as `.husky/lint-scope.mjs` defines it — rather than
  * a second definition of "product code" written here. Two names for one rule is
  * the failure the parity test in `tests/unit/comments/citation-parity.test.ts`
- * exists to prevent.
+ * exists to prevent, and the parity that second name actually caused is pinned by
+ * `tests/unit/comments/comment-audit.test.ts`, which requires this walk to read the
+ * same number of files the artifact records the ratchet measuring.
  *
  * This is the read side only. Nothing here writes a file: the counts it produces
  * are the numbers a ratchet would start from, and a ratchet seeded from a scan
@@ -16,8 +18,27 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 import { scanComments, summarize } from './comment-hygiene.js';
 import { createFsProbe, createRepoProbe } from './repo-path-probe.js';
-/** Product-code directories, in report order. */
-export const COMMENT_SCAN_SCOPE = ['src', join('packages', 'peaks-loop-mut', 'src')];
+/**
+ * Product-code directories, in report order: `src`, then every package under
+ * `packages/` that has a `src`.
+ *
+ * Derived from the rule rather than enumerated, because `.husky/lint-scope.mjs` says a
+ * new `packages/<anything>/src` joins the enforced scope BY EXISTING. The first version
+ * of this list spelled it `['src', 'packages/peaks-loop-mut/src']`, which was the second
+ * definition of "product code" this file's header claims not to be: the ratchet measures
+ * 953 files and the worklist read 926, so 14 gated narrative rows lived in three
+ * packages no `peaks comments audit` would show and no `prune` could clear.
+ */
+export function commentScanScope(projectRoot) {
+    const packagesDir = join(projectRoot, 'packages');
+    if (!existsSync(packagesDir))
+        return ['src'];
+    const names = readdirSync(packagesDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && existsSync(join(packagesDir, entry.name, 'src')))
+        .map((entry) => entry.name)
+        .sort();
+    return ['src', ...names.map((name) => join('packages', name, 'src'))];
+}
 const SOURCE_SUFFIXES = ['.ts', '.tsx', '.mts', '.cts'];
 function isSourceFile(name) {
     return SOURCE_SUFFIXES.some((suffix) => name.endsWith(suffix));
@@ -96,5 +117,5 @@ export function auditComments(options) {
 }
 /** The walked population, used only when a caller did not hand an explicit list. */
 function scopePopulation(projectRoot) {
-    return COMMENT_SCAN_SCOPE.flatMap((scopeDir) => scopeFiles(projectRoot, scopeDir));
+    return commentScanScope(projectRoot).flatMap((scopeDir) => scopeFiles(projectRoot, scopeDir));
 }

package/dist/services/comments/comment-citations.d.ts

@@ -9,8 +9,9 @@
  * Deliberately NOT `ts.getLeadingCommentRanges`:
  * `src/services/qa/bdd-test-style-verifier.ts` records that the API returns zero
  * ranges for comment-only blocks, which would silently read a header comment as no
- * comment at all. Line scanning preserves both order and line numbers, which the
- * worklist and the prune both need.
+ * comment at all. The spans come from `comment-spans.ts` instead, which keeps both
+ * order and line numbers — what the worklist and the prune both need — and knows
+ * what character it is inside, which a per-line rule cannot.
  */
 import { type Citation } from './citation-rules.js';
 /** One source line, with its 1-based number, as the classifier sees it. */
@@ -22,6 +23,11 @@ export type CommentLine = {
  * The comment lines of a file: full-line comments, plus the trailing comment of a
  * code line. Non-comment lines are omitted but their numbers survive, so a report
  * can point at the code a comment is attached to.
+ *
+ * Derived from `commentSpans`, which reads the text as a stream. The previous version
+ * decided per line and was wrong in both directions at once: a `//` inside a template
+ * literal became a comment (and then a deletion that cut the literal open), while a
+ * block comment's interior line that does not start with `*` was missed.
  */
 export declare function commentLines(source: string): CommentLine[];
 /**

package/dist/services/comments/comment-citations.js

@@ -9,58 +9,56 @@
  * Deliberately NOT `ts.getLeadingCommentRanges`:
  * `src/services/qa/bdd-test-style-verifier.ts` records that the API returns zero
  * ranges for comment-only blocks, which would silently read a header comment as no
- * comment at all. Line scanning preserves both order and line numbers, which the
- * worklist and the prune both need.
+ * comment at all. The spans come from `comment-spans.ts` instead, which keeps both
+ * order and line numbers — what the worklist and the prune both need — and knows
+ * what character it is inside, which a per-line rule cannot.
  */
 import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { LINE_SUFFIX, PATH_SHAPED, REPO_ANCHORS, SESSION_WORKSPACE_DIRS, SYNTHETIC_SEGMENT } from './citation-rules.js';
+import { commentSpans } from './comment-spans.js';
 /** Repo-relative paths are POSIX even on a Windows host, or every lookup below
  *  compares a `src\a.ts` against the forward-slash keys and the answer is always "no". */
 function toPosix(path) {
     return path.replace(/\\/g, '/');
 }
-/**
- * A `//` in a line of code is a trailing comment unless the text before it is
- * inside a string literal or a URL scheme. The second clause matters because
- * `"https://…"` is a line every repository writes, and reading it as a comment
- * invents a line the author never meant.
- */
-function trailingComment(raw) {
-    const at = raw.indexOf('//');
-    if (at <= 0)
-        return '';
-    const before = raw.slice(0, at);
-    if (before.endsWith(':'))
-        return '';
-    if ((before.match(/["']/g) ?? []).length % 2 !== 0)
-        return '';
-    return raw.slice(at);
-}
 /**
  * The comment lines of a file: full-line comments, plus the trailing comment of a
  * code line. Non-comment lines are omitted but their numbers survive, so a report
  * can point at the code a comment is attached to.
+ *
+ * Derived from `commentSpans`, which reads the text as a stream. The previous version
+ * decided per line and was wrong in both directions at once: a `//` inside a template
+ * literal became a comment (and then a deletion that cut the literal open), while a
+ * block comment's interior line that does not start with `*` was missed.
  */
 export function commentLines(source) {
     const out = [];
-    source.split(/\r?\n/).forEach((raw, index) => {
-        const line = index + 1;
-        const trimmed = raw.trim();
-        if (trimmed.startsWith('//') ||
-            trimmed.startsWith('/*') ||
-            trimmed.startsWith('/**') ||
-            trimmed.startsWith('*')) {
-            out.push({ line, text: raw });
-            return;
+    const rows = source.split(/\r?\n/);
+    for (const span of commentSpans(source)) {
+        for (let line = span.line; line <= span.endLine; line += 1) {
+            const row = rows[line - 1];
+            if (row === undefined)
+                continue;
+            // The first line of a block comment that opens mid-code keeps only its own tail,
+            // so a caller never reads the code before `/*` as part of the comment.
+            const from = line === span.line ? span.start - lineStart(source, line) : 0;
+            out.push({ line, text: row.slice(Math.max(0, from)) });
         }
-        const comment = trailingComment(raw);
-        if (comment.length > 0) {
-            out.push({ line, text: comment });
-        }
-    });
+    }
     return out;
 }
+/** The offset `source` has advanced by the start of 1-based `line`. */
+function lineStart(source, line) {
+    let at = 0;
+    for (let n = 1; n < line; n += 1) {
+        const next = source.indexOf('\n', at);
+        if (next < 0)
+            return source.length;
+        at = next + 1;
+    }
+    return at;
+}
 /**
  * The path-shaped backtick spans in a line, in order, with their bounds kept.
  *

package/dist/services/comments/comment-hygiene.d.ts

@@ -12,8 +12,6 @@
  *     current one, a reader took it as fact, and the fix was chased into
  *     `dist/` instead of the source.
  *   - `narrative` — the comment is about the work rather than the code: slice
- *     and rid identifiers, `AC-3`, "F2 of `rid-…`", "this used to claim", "the
- *     test named above was deleted". Legitimately valuable in a commit message
  *     or `.peaks/docs/backlog.md`; in a source file it is re-read by every
  *     later agent, at their token cost, and it rots silently the moment the
  *     history it summarises moves.
@@ -45,13 +43,41 @@ export type CommentFinding = {
  *
  * Order is significant and is the whole attribution: one line reports its FIRST
  * match, so a specific marker must precede the general one that also fits it.
- * `F2 of \`rid-…\`` is a finding reference, not a bare rid, and a list ordered
  * the other way round would blame the wrong rule for every such line.
  */
 export declare const NARRATIVE_MARKERS: ReadonlyArray<{
     name: string;
     pattern: RegExp;
 }>;
+/**
+ * Comments that are LOAD-BEARING: text some program parses as data, not prose it reads.
+ *
+ * These are exempt from BOTH kinds, because the prune acts on a finding of either kind and
+ * deleting any of them does not reduce debt — it removes an enforcement mechanism, or
+ * adds a finding to a gated row. Each shape names the reader that consumes it; a shape
+ * with no reader to point at is a guess, and guesses are what the 4.1.1 prune learned from
+ * `HARD_FLOOR_CATEGORIES` member in `src/services/code/mode-gate.ts`, which is the only
+ * thing backing this repo's one real layer-C promotion, and the gate-H backing check went
+ * red — `feedback-promotion-artifact.test.ts` AC5).
+ *
+ *   - `promotion-evidence` — `src/services/feedback/promotion-source-comments.ts:79`
+ *     (`citedMemories`) feeds `promotion-artifact-evidence.ts:214`, which decides whether a
+ *     promoted rule is actually backed.
+ *   - `grace-marker` — `scripts/lint/silent-warning-detector.mjs:149` subtracts a
+ *     silent-warning finding for any line the offending node spans that carries
+ *     `TODO(g2)`. Deleting the marker therefore RAISES `silentWarningCatchReturnNull` /
+ *     `…EmptyCatch`, both of which may only go down.
+ *   - `toolchain-directive` — `@ts-expect-error` and friends are read by the compiler (an
+ *     unused one is itself an error) and `eslint-disable` by the lint leg; a paired disable
+ *     like `src/services/compact-statusline/compact-statusline-cell-table.ts:72`+`:99`
+ *     must move as a pair or the file starts reporting.
+ */
+export declare const LOAD_BEARING_SHAPES: ReadonlyArray<{
+    name: string;
+    pattern: RegExp;
+}>;
+/** Is this comment text consumed by a program? */
+export declare function isLoadBearing(text: string): boolean;
 export type CommentScanInput = {
     /** Repo-relative path, e.g. `src/services/x/y.ts`. */
     readonly file: string;

package/dist/services/comments/comment-hygiene.js

@@ -12,8 +12,6 @@
  *     current one, a reader took it as fact, and the fix was chased into
  *     `dist/` instead of the source.
  *   - `narrative` — the comment is about the work rather than the code: slice
- *     and rid identifiers, `AC-3`, "F2 of `rid-…`", "this used to claim", "the
- *     test named above was deleted". Legitimately valuable in a commit message
  *     or `.peaks/docs/backlog.md`; in a source file it is re-read by every
  *     later agent, at their token cost, and it rots silently the moment the
  *     history it summarises moves.
@@ -37,7 +35,6 @@ import { isCitationCandidate } from './citation-rules.js';
  *
  * Order is significant and is the whole attribution: one line reports its FIRST
  * match, so a specific marker must precede the general one that also fits it.
- * `F2 of \`rid-…\`` is a finding reference, not a bare rid, and a list ordered
  * the other way round would blame the wrong rule for every such line.
  */
 export const NARRATIVE_MARKERS = [
@@ -59,6 +56,41 @@ export const NARRATIVE_MARKERS = [
         pattern: /\bthis (?:comment|header|paragraph|note) (?:says|claimed|documents|is )/i
     }
 ];
+/**
+ * Comments that are LOAD-BEARING: text some program parses as data, not prose it reads.
+ *
+ * These are exempt from BOTH kinds, because the prune acts on a finding of either kind and
+ * deleting any of them does not reduce debt — it removes an enforcement mechanism, or
+ * adds a finding to a gated row. Each shape names the reader that consumes it; a shape
+ * with no reader to point at is a guess, and guesses are what the 4.1.1 prune learned from
+ * `HARD_FLOOR_CATEGORIES` member in `src/services/code/mode-gate.ts`, which is the only
+ * thing backing this repo's one real layer-C promotion, and the gate-H backing check went
+ * red — `feedback-promotion-artifact.test.ts` AC5).
+ *
+ *   - `promotion-evidence` — `src/services/feedback/promotion-source-comments.ts:79`
+ *     (`citedMemories`) feeds `promotion-artifact-evidence.ts:214`, which decides whether a
+ *     promoted rule is actually backed.
+ *   - `grace-marker` — `scripts/lint/silent-warning-detector.mjs:149` subtracts a
+ *     silent-warning finding for any line the offending node spans that carries
+ *     `TODO(g2)`. Deleting the marker therefore RAISES `silentWarningCatchReturnNull` /
+ *     `…EmptyCatch`, both of which may only go down.
+ *   - `toolchain-directive` — `@ts-expect-error` and friends are read by the compiler (an
+ *     unused one is itself an error) and `eslint-disable` by the lint leg; a paired disable
+ *     like `src/services/compact-statusline/compact-statusline-cell-table.ts:72`+`:99`
+ *     must move as a pair or the file starts reporting.
+ */
+export const LOAD_BEARING_SHAPES = [
+    { name: 'promotion-evidence', pattern: /\.peaks\/memory\/[^\s`]+\.md/ },
+    { name: 'grace-marker', pattern: /\bTODO\(g2\)/ },
+    {
+        name: 'toolchain-directive',
+        pattern: /(?:eslint-disable|prettier-ignore|@ts-[a-z-]+|@type\b|@vitest-slow|@covers\b)/
+    }
+];
+/** Is this comment text consumed by a program? */
+export function isLoadBearing(text) {
+    return LOAD_BEARING_SHAPES.some((shape) => shape.pattern.test(text));
+}
 function deadReferenceFindings(entry, judge) {
     const ctx = { file: judge.file, dirExists: judge.dirExists };
     const out = [];
@@ -84,6 +116,11 @@ function deadReferenceFindings(entry, judge) {
  * a reader could not already see.
  */
 function classifyLine(entry, judge) {
+    // Before either kind: a load-bearing line is not debt under any reading, so it must not
+    // be reported as a dead reference either — the path it cites is evidence, not a claim
+    // about where a file lives.
+    if (isLoadBearing(entry.text))
+        return [];
     const out = judge.kinds.has('dead-reference')
         ? deadReferenceFindings(entry, judge)
         : [];

package/dist/services/comments/comment-prune.js

@@ -49,6 +49,30 @@ function removalWouldBreakTheComment(text) {
     const closes = text.includes('*/');
     return opens !== closes;
 }
+/**
+ * Does this line end BEFORE its text does?
+ *
+ * Two structural signals: an ODD number of backticks (the inline-code span this line opens
+ * is closed on a line BELOW) and a trailing `-` that is not `--` (a token the line width
+ * wrapped in half). They mean the same thing — the construct this line belongs to continues
+ * under it — and a line-at-a-time prune cuts that construct in half.
+ *
+ * Two applies of this pruner did exactly that to the same kind of text: a
+ * `.peaks/memory` citation written across two comment lines, where the FIRST line was debt
+ * and the second was not. Each left the survivor reading like
+ * ` * visibility-issue.md; well below the stale threshold.` — a sentence with its front cut
+ * off, which is worse than the debt that was removed. And the citation is destroyed either
+ * way: `citedMemories` in `../feedback/promotion-source-comments.ts` matches a path in ONE
+ * run of `[A-Za-z0-9._-]`, so a path that needs two lines is invisible to it before the cut
+ * and gone after it. Refused rather than guessed, the way the block delimiter is: the
+ * worklist still shows the row, and a human decides where the line break goes.
+ */
+function continuesIntoTheNextLine(comment) {
+    const trimmed = comment.trimEnd();
+    if ((trimmed.match(/`/g) ?? []).length % 2 === 1)
+        return true;
+    return trimmed.endsWith('-') && !trimmed.endsWith('--');
+}
 function actionFor(finding, text, comment) {
     return {
         file: finding.file,
@@ -76,14 +100,34 @@ function skipFor(finding, reason) {
 export function planPrune(options, findings) {
     const actions = [];
     const skips = [];
+    // One extractor run per FILE, keyed by path. `commentLines` is contextual now — it has
+    // not a comment at all — so asking it about a single line would skip every one of those
+    // findings. The old code could get away with it because the line-local heuristic agreed
+    // with itself by construction, which is not the same as being right.
+    const byFile = new Map();
+    const viewFor = (file) => {
+        const known = byFile.get(file);
+        if (known !== undefined)
+            return known;
+        const source = readFileSafe(options.projectRoot, file);
+        if (source === null)
+            return null;
+        const split = splitLines(source);
+        const comments = new Map();
+        for (const entry of commentLines(source))
+            comments.set(entry.line, entry.text);
+        const view = { lines: split.lines, comments };
+        byFile.set(file, view);
+        return view;
+    };
     for (const finding of findings) {
-        const source = readFileSafe(options.projectRoot, finding.file);
-        if (source === null) {
+        const view = viewFor(finding.file);
+        if (view === null) {
             skips.push(skipFor(finding, 'file-not-readable'));
             continue;
         }
-        const text = splitLines(source).lines[finding.line - 1] ?? '';
-        const comment = commentLines(text)[0]?.text ?? '';
+        const text = view.lines[finding.line - 1] ?? '';
+        const comment = view.comments.get(finding.line) ?? '';
         if (comment.trim() !== finding.text) {
             skips.push(skipFor(finding, 'line-moved-since-scan'));
             continue;
@@ -92,6 +136,10 @@ export function planPrune(options, findings) {
             skips.push(skipFor(finding, 'carries-a-block-delimiter'));
             continue;
         }
+        if (continuesIntoTheNextLine(comment)) {
+            skips.push(skipFor(finding, 'continues-into-the-next-line'));
+            continue;
+        }
         actions.push(actionFor(finding, text, comment));
     }
     return { actions, skips };

package/dist/services/comments/comment-spans.d.ts

@@ -0,0 +1,30 @@
+/** One comment in the file, in character offsets and in the lines it covers. */
+export type CommentSpan = {
+    /** Index of the slash that opens it. */
+    start: number;
+    /** One past the comment's last character, its closing delimiter included. */
+    end: number;
+    /** 1-based line the comment opens on. */
+    line: number;
+    /** 1-based line the comment ends on — equal to `line` unless it is a block comment. */
+    endLine: number;
+    /** The comment's own text, opening marker included. */
+    text: string;
+};
+/**
+ * Every comment in `source`, in order.
+ *
+ * `text` is sliced from the original so a caller can cut at `start` and keep the code
+ * that was already there — which is the operation the pruner must get exactly right.
+ */
+export declare function commentSpans(source: string): CommentSpan[];
+/**
+ * Does this code stop INSIDE something open?
+ *
+ * The question the comment-only proof had to learn to ask. `original.startsWith(kept)` is
+ * true of EVERY truncation, so it cannot tell a revealed comment from a string cut in
+ * half; a prefix that ends inside a quote, a template or a regex is a different program,
+ * whatever it starts with. This is what would have refused the write that left
+ * `snippet: \`` in `src/`.
+ */
+export declare function endsInsideLiteral(code: string): boolean;