peaks-loop 4.1.0 → 4.1.2

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

@@ -0,0 +1,196 @@
+/**
+ * Remove the comments the scan says are debt — and prove nothing else moved.
+ *
+ * The actuator is the dangerous half of this feature: a classifier that is 86%
+ * precise only misinforms, but a pruner that is 86% precise deletes. So the
+ * deliverable here is not the deletion, it is the PROOF, and the proof is a
+ * structural check run on every file before it is written:
+ *
+ *   - the diff is computed line-by-line against the plan, so a changed line that
+ *     the scan never named is a violation, not a surprise;
+ *   - every removed line must be a comment line, and a stripped trailing comment
+ *     must leave its code byte-identical;
+ *   - a line that carries a block-comment delimiter opening or closing ELSEWHERE
+ *     is never removed, because deleting it would turn the rest of the comment into
+ *     code — the one failure mode that makes this a compile error rather than a
+ *     lost sentence;
+ *   - a file whose line endings are mixed is left alone, since re-joining it would
+ *     rewrite every line and the proof would stop meaning anything.
+ *
+ * Anything that fails the check is reported and NOT written. The ledger records
+ * every line removed, with the rule that fired, so a prune is reviewable after the
+ * fact instead of only before it.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getSessionDir } from '../session/getSessionDir.js';
+import { getSessionId } from '../session/session-manager.js';
+import { auditComments } from './comment-audit.js';
+import { commentLines } from './comment-citations.js';
+import { actionsByFile, executePlan, readFileSafe, splitLines } from './prune-apply.js';
+const FULL_LINE_PREFIXES = ['//', '/*', '/**', '*'];
+function isFullLineComment(text) {
+    const trimmed = text.trim();
+    return FULL_LINE_PREFIXES.some((prefix) => trimmed.startsWith(prefix));
+}
+/**
+ * Can this line be deleted without breaking the syntax around it?
+ *
+ * A line that OPENS a block (`/* …` with no close on the same line) or CLOSES one
+ * (a bare `* /`) is load-bearing for the comment's extent, not for its prose.
+ * Removing it leaves the remainder of the block as code — a compile error is the
+ * mildest thing that follows. Checked for both modes, because the strip below also
+ * cuts text out of a line: a code line carrying an unterminated `/*` would have its
+ * "trailing comment" extracted from inside the block, and cutting there is a syntax
+ * edit, not a comment edit.
+ */
+function removalWouldBreakTheComment(text) {
+    const opens = text.includes('/*');
+    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,
+        line: finding.line,
+        kind: finding.kind,
+        matched: finding.matched,
+        mode: isFullLineComment(text) ? 'drop-line' : 'strip-trailing',
+        lineText: text,
+        comment
+    };
+}
+function skipFor(finding, reason) {
+    return { file: finding.file, line: finding.line, reason, text: finding.text };
+}
+/**
+ * Decide the fate of every finding.
+ *
+ * The line is re-read here and passed back through `commentLines`, the scan's own
+ * extractor, rather than compared against the whole line: a trailing comment's
+ * recorded text is the comment, not the code before it, and an equality test on the
+ * raw line would reject every one of them. Re-using the extractor is what makes the
+ * plan and the scan agree BY CONSTRUCTION instead of by two copies of a rule — the
+ * defect class this whole feature is a reply to.
+ */
+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 view = viewFor(finding.file);
+        if (view === null) {
+            skips.push(skipFor(finding, 'file-not-readable'));
+            continue;
+        }
+        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;
+        }
+        if (removalWouldBreakTheComment(text)) {
+            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 };
+}
+function ledgerPathFor(projectRoot, stamp) {
+    const sessionId = getSessionId(projectRoot) ?? '_nonsession';
+    const dir = join(getSessionDir(projectRoot, sessionId), 'comments');
+    mkdirSync(dir, { recursive: true });
+    return join(dir, `prune-${stamp}.json`);
+}
+/**
+ * Plan, prove, and (on `apply`) write.
+ *
+ * The scan runs through `auditComments`, so a pruned line is one the worklist
+ * already showed a human; the pruner adds no rule of its own about what counts as
+ * debt.
+ */
+export function pruneComments(options) {
+    const kinds = options.kinds ?? ['dead-reference', 'narrative'];
+    const audit = auditComments({ projectRoot: options.projectRoot });
+    const inScope = audit.findings.filter((finding) => kinds.includes(finding.kind) &&
+        (options.onlyFile === undefined || finding.file === options.onlyFile));
+    const { actions, skips } = planPrune(options, inScope);
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const ledgerPath = ledgerPathFor(options.projectRoot, stamp);
+    const outcome = executePlan(options.projectRoot, actionsByFile(actions), options.apply === true);
+    const skipsAll = [...skips, ...outcome.fileSkips];
+    // Written on a dry run too: the plan IS the reviewable artifact, and a reviewer
+    // who only sees stdout has nothing to diff a later apply against.
+    writeFileSync(ledgerPath, `${JSON.stringify({
+        projectRoot: options.projectRoot,
+        at: new Date().toISOString(),
+        applied: options.apply === true,
+        kinds,
+        onlyFile: options.onlyFile ?? null,
+        removed: actions,
+        skipped: skipsAll,
+        touchedFiles: outcome.touched,
+        notWritten: outcome.notWritten
+    }, null, 2)}\n`);
+    return {
+        scannedFiles: audit.scannedFiles,
+        planned: actions.length,
+        dropped: actions.filter((action) => action.mode === 'drop-line').length,
+        stripped: actions.filter((action) => action.mode === 'strip-trailing').length,
+        skipped: skipsAll.length,
+        touchedFiles: outcome.touched,
+        notWritten: outcome.notWritten,
+        ledgerPath,
+        actions,
+        skips: skipsAll,
+        applied: options.apply === true
+    };
+}

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;

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

@@ -0,0 +1,266 @@
+// src/services/comments/comment-spans.ts
+//
+// WHERE THE COMMENTS ACTUALLY ARE, read from the text the way a lexer reads it.
+//
+// version of this reader was line-local: a line was a comment if it began with `//`, a
+// block opener, or `*`, and a code line's trailing comment was `raw.indexOf('//')`
+// guarded by a quote-count parity check. Applying the pruner to the real tree then wrote
+// a corrupted file. `feedback-promotion-service.ts` holds a one-line template literal
+// whose CONTENT starts with a double slash — it is a snippet the CLI prints for users:
+//
+//     snippet: `// src/services/code/mode-gate.ts\n// 1. Add to HardFloorCategory union…`,
+//
+// The reader saw code + trailing comment, the pruner cut at the first double slash, and
+// the result was an unterminated template literal committed into `src/`. The quote parity
+// guard could not have caught it: the text before the cut contains NO quotes at all, so
+// its count is even, and "even" looked safe. Parity of a count is not the same as knowing
+// what character you are inside of.
+//
+// So this walks the file as ONE stream with an explicit notion of where it is: code, a
+// single- or double-quoted string, a template literal (whose `${ … }` re-enters code, so
+// a nested template, or a real comment, inside an interpolation follows the same rules),
+// a regex literal, a line comment, or a block comment.
+//
+// REGEX IS NOT OPTIONAL DETAIL, and finding that out is why this file is bigger than the
+// bug it fixes. `/https?:\/\//g` — a shape this repository has a hundred files of —
+// carries a real adjacent pair of slashes, made of an escaped one next to the closing
+// delimiter. A stream that does not know it is inside a regex reads that pair as a
+// comment and would cut code through it: the same accident as the template literal above,
+// reached from a different direction. Whether a `/` opens a regex or divides is decided by
+// what could end a value before it, which is the standard test; a word is only a value if
+// it is not `return`/`typeof`/`case`/…, because `return /x/` is the one place the naive
+// version of that test is wrong.
+//
+// ONE MACHINE, TWO QUESTIONS. `commentSpans` asks "where are the comments";
+// `endsInsideLiteral` asks "does this text stop inside something open". Both run the same
+// walk below, because two copies of a state machine is the defect class this repository
+// files most often — and the second question is the one the prune proof had to learn to
+// ask: `startsWith` is true of every truncation, so it cannot tell a revealed comment
+// from a string cut in half.
+//
+// A HANDLER PER REGION, not one function of nested ifs: the first working version was a
+// 126-line loop that both `max-lines-per-function` and `complexity` refused, and they were
+// right — `HANDLERS` below is the state diagram, where a single else-chain was not.
+//
+// NOT A PARSER, AND DELIBERATELY SO: `typescript` is a devDependency, so product code
+// cannot import it without handing the shipped CLI a runtime dependency. The parity
+// between this walk and the real TypeScript lexer is asserted in
+// `tests/unit/comments/comment-scan-parity.test.ts`, which MAY use `ts` — the check lives
+// where the dependency already is, instead of the dependency following the check into
+// every user's `node_modules`.
+/**
+ * Words after which a `/` is a regex, not division. `return /x/` is the case that makes
+ * "an identifier ends a value" wrong often enough to matter.
+ */
+const VALUE_ENDING_BEFORE_REGEX = /^(?:return|typeof|instanceof|in|of|new|delete|void|throw|case|do|else|yield|await)$/;
+const char = (w, offset = 0) => w.source.charAt(w.at + offset);
+/** Report the comment that opened at `spanStart`. */
+function emitSpan(w, end, endLine) {
+    w.emit({
+        start: w.spanStart,
+        end,
+        line: w.spanLine,
+        endLine,
+        text: w.source.slice(w.spanStart, end)
+    });
+}
+/** A finished word: only a non-keyword one can end a value. */
+function endWord(w) {
+    if (w.word === '')
+        return;
+    w.afterValue = !VALUE_ENDING_BEFORE_REGEX.test(w.word);
+    w.word = '';
+}
+function inLineComment(w) {
+    if (char(w) !== '\n')
+        return;
+    emitSpan(w, w.at, w.line - 1);
+    w.region = 'code';
+    w.afterValue = false;
+}
+function inBlockComment(w) {
+    if (char(w) !== '*' || char(w, 1) !== '/')
+        return;
+    emitSpan(w, w.at + 2, w.line);
+    w.at += 1;
+    w.region = 'code';
+    w.afterValue = false;
+}
+function inString(w) {
+    const c = char(w);
+    if (c === '\\')
+        w.at += 1;
+    else if (c === (w.region === 'single' ? "'" : '"')) {
+        w.region = 'code';
+        w.afterValue = true;
+    }
+    else if (c === '\n') {
+        // An unterminated string cannot survive to a newline in valid source. Resuming as
+        // code keeps one stray quote from deciding that the rest of the FILE is a string,
+        // which is the failure mode that turns every later comment invisible.
+        w.region = 'code';
+        w.afterValue = false;
+    }
+}
+function inTemplate(w) {
+    const c = char(w);
+    if (c === '\\')
+        w.at += 1;
+    else if (c === '`') {
+        w.region = 'code';
+        w.afterValue = true;
+    }
+    else if (c === '$' && char(w, 1) === '{') {
+        w.interpolations.push(w.at);
+        w.at += 1;
+        w.region = 'code';
+        w.afterValue = false;
+    }
+}
+/** A regex, or the inside of its `[…]` class where `/` is an ordinary character. */
+function inRegex(w) {
+    const c = char(w);
+    if (c === '\\')
+        w.at += 1;
+    else if (c === '[')
+        w.region = 'class';
+    else if (c === ']' && w.region === 'class')
+        w.region = 'regex';
+    else if (c === '/' && w.region === 'regex') {
+        w.region = 'code';
+        w.afterValue = true;
+    }
+    else if (c === '\n') {
+        // No regex crosses a line, so a newline means the `/` was division after all.
+        w.region = 'code';
+        w.afterValue = false;
+    }
+}
+/** A `}` in code: it closes the innermost open `${`, and only that one. */
+function closeInterpolation(w) {
+    w.afterValue = true;
+    if (w.interpolations.length === 0)
+        return;
+    w.interpolations.pop();
+    w.region = 'template';
+}
+/** Enter a string or template region, or report that this character starts none. */
+function enterLiteral(w, c) {
+    if (c !== "'" && c !== '"' && c !== '`')
+        return false;
+    w.region = c === "'" ? 'single' : c === '"' ? 'double' : 'template';
+    w.afterValue = false;
+    return true;
+}
+/**
+ * A slash in code. A comment opens on `//` or a block opener; a lone slash is a regex
+ * exactly where a value cannot have just ended, and division everywhere else.
+ */
+function readSlash(w, next) {
+    if (next === '/' || next === '*') {
+        w.region = next === '/' ? 'line' : 'block';
+        w.spanStart = w.at;
+        w.spanLine = w.line;
+        w.afterValue = false;
+        return;
+    }
+    w.region = w.afterValue ? 'code' : 'regex';
+    w.afterValue = false;
+}
+/**
+ * What each bracket says about "has a value just ended": an opener means the next slash
+ * cannot be division, a closer means it can. A table so `inCode` stays a reader's size.
+ */
+const BRACKET_ENDS_VALUE = {
+    '(': false,
+    '[': false,
+    ')': true,
+    ']': true
+};
+function inCode(w) {
+    const c = char(w);
+    if (/[A-Za-z0-9_$]/.test(c)) {
+        w.word += c;
+        return;
+    }
+    endWord(w);
+    if (enterLiteral(w, c))
+        return;
+    if (c === '{')
+        w.afterValue = false;
+    else if (c === '}')
+        closeInterpolation(w);
+    else if (c in BRACKET_ENDS_VALUE)
+        w.afterValue = BRACKET_ENDS_VALUE[c] ?? false;
+    else if (c === '/')
+        readSlash(w, char(w, 1));
+    else if (!/\s/.test(c))
+        w.afterValue = false;
+}
+/** One handler per state. THIS TABLE IS THE STATE DIAGRAM — read the regions off it. */
+const HANDLERS = {
+    code: inCode,
+    single: inString,
+    double: inString,
+    template: inTemplate,
+    regex: inRegex,
+    class: inRegex,
+    line: inLineComment,
+    block: inBlockComment
+};
+/**
+ * Walk `source`, report every comment, and return the region the text ENDED in.
+ *
+ * The return value is what makes `endsInsideLiteral` possible without a second machine: a
+ * caller that truncated some text wants to know whether the survivor is complete.
+ */
+function walkCode(source, onComment) {
+    const w = {
+        source,
+        at: 0,
+        line: 1,
+        region: 'code',
+        afterValue: false,
+        word: '',
+        interpolations: [],
+        spanStart: 0,
+        spanLine: 1,
+        emit: onComment
+    };
+    while (w.at < source.length) {
+        // Counted BEFORE dispatch, so a line comment closing on a newline reports the line
+        // it was written on, not the one after it. A handler that consumes a second character
+        // (an escape, a `*/`) advances `at` itself and the driver's step lands past it.
+        if (source.charAt(w.at) === '\n')
+            w.line += 1;
+        HANDLERS[w.region](w);
+        w.at += 1;
+    }
+    endWord(w);
+    if (w.region === 'block' || w.region === 'line')
+        emitSpan(w, source.length, w.line);
+    return w.region;
+}
+/**
+ * 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 function commentSpans(source) {
+    const spans = [];
+    walkCode(source, (span) => spans.push(span));
+    return spans;
+}
+/**
+ * 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 function endsInsideLiteral(code) {
+    return walkCode(code, () => { }) !== 'code';
+}

package/dist/services/comments/prune-apply.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The line mechanics of a comment prune, and the proof that gates every write.
+ *
+ * Split from `comment-prune.ts` because the two change for different reasons: that
+ * module decides WHAT is debt (and follows the classifier), this one decides how a
+ * line is removed from a file without damaging the file (and follows the language).
+ * Keeping them apart is also what lets the proof be tested on a text array, with no
+ * filesystem and no scan in the room.
+ */
+import type { PruneAction, PruneSkip } from './comment-prune.js';
+/** What the write phase decided, per file. */
+export type WriteOutcome = {
+    touched: string[];
+    notWritten: string[];
+    fileSkips: PruneSkip[];
+};
+/**
+ * Read a file, or report that it is not there — a prune never creates one.
+ *
+ * `existsSync` first, and NO catch: a `catch { return null }` answers "present but
+ * unreadable" (permissions, a locked handle, a directory named as a file) with the same
+ * `null` as "absent", and that conflation is the defect this repository already
+ * ratchets under `silentWarningCatchReturnNull` — this very helper was counted by it.
+ * An absent path is a state the caller handles; an unreadable one should be a crash an
+ * operator sees.
+ */
+export declare function readFileSafe(root: string, rel: string): string | null;
+/**
+ * Split a source into lines, remembering what separated them.
+ *
+ * `mixed` is the signal to leave a file alone rather than a detail to paper over: a
+ * file with both CRLF and LF endings cannot be re-joined from one delimiter without
+ * rewriting every line, and a rewrite of every line is not a comment edit — it would
+ * also make the proof below vacuous, because all the lines would differ.
+ */
+export declare function splitLines(source: string): {
+    lines: string[];
+    eol: string;
+    mixed: boolean;
+};
+/** Group a plan by file, in first-seen order. */
+export declare function actionsByFile(actions: readonly PruneAction[]): Map<string, PruneAction[]>;
+/**
+ * The proof, as data: compare kept lines against the original.
+ *
+ * One string per violation; empty means every difference between the two texts is a
+ * line this plan named, and every line it named that was kept is byte-identical to
+ * what was there before. This is computed whether or not the caller intends to write,
+ * so a dry run reports the refusals a real run would hit.
+ */
+export declare function proofViolations(before: readonly string[], after: readonly string[], actions: readonly PruneAction[]): string[];
+/**
+ * The blank lines a set of drops ORPHANS.
+ *
+ * A comment standing alone between two blanks is the only thing separating two blocks:
+ *
+ *     }
+ *                    ← blank
+ *                    ← blank
+ *     type AuditEnvelopeGuard<T> = …
+ *
+ * Deleting the comment joins the two blanks into a double blank, which is not what the
+ * file said before and not what any formatter will keep. So the drop owns that blank line
+ * — it is the residue of a comment removal, not an edit of someone's whitespace. Only a
+ * blank that becomes adjacent to another blank THROUGH a drop is claimed here: a double
+ * blank the repository already carries is left exactly where it is, because the pruner did
+ * not make it and has no business "fixing" it.
+ *
+ * ONE HELPER, BOTH CALLERS: `pruneFileLines` removes these and `proofViolations` allows
+ * them. A second copy of this rule is the defect class this whole feature answers, so the
+ * writer and the checker ask the same function the same question.
+ */
+export declare function orphanedBlanks(before: readonly string[], dropped: ReadonlySet<number>): Set<number>;
+/** Apply one file's actions to its lines, in the plan's own terms. */
+export declare function pruneFileLines(lines: readonly string[], actions: readonly PruneAction[]): string[];
+/**
+ * Run the proof on every planned file, and write only the files that passed it.
+ *
+ * A file that fails is reported and left alone — never written "mostly", because a
+ * partially-pruned file is exactly the state the proof exists to make unreachable.
+ */
+export declare function executePlan(projectRoot: string, byFile: Map<string, PruneAction[]>, apply: boolean): WriteOutcome;