peaks-loop 4.0.51 → 4.0.52

package/dist/services/codegraph/codegraph-include-reconciler.js

@@ -0,0 +1,160 @@
+// src/services/codegraph/codegraph-include-reconciler.ts
+//
+// Slice-002 of `2026-09-16-codegraph-index-integrity` — the INCLUDE axis
+// of the config repair. It answers one question:
+//
+//   "Which extensions does upstream's extractor support but upstream's own
+//    default `include` template never names, and which of those does THIS
+//    project's `include` still not admit?"
+//
+// Why this exists (the real defect, measured): upstream
+// `@colbymchenry/codegraph` decides what to parse from its own
+// `EXTENSION_MAP` (37 extensions in 0.7.10), but `init` writes a 32-entry
+// `DEFAULT_CONFIG.include` template that names only 32 of them. Five
+// supported extensions are therefore absent from every fresh config:
+// `.mjs`, `.cjs`, `.pyw`, `.hxx`, `.rake`. Upstream's `mergeConfig` has no
+// separate override channel — `config.json`'s `include` replaces the
+// defaults wholesale — so a fresh clone indexes none of them while
+// `peaks codegraph status` still prints `[OK] Index is up to date`. On this
+// repo that was 31 tracked files (30 `.mjs` + 1 `.cjs`) absent from a
+// 1220-row index. It is the same class of defect as upstream's default
+// `exclude` template colliding with real source directories, which slice S2
+// of `2026-09-12-codegraph-exclude-integrity` already self-heals at the
+// `init` seam; the include axis was simply never reconciled.
+//
+// Genericity (binding — mirrors the exclude reconciler): no hardcoded
+// extension list, no hardcoded rule names, no project-specific paths. The
+// candidate set is COMPUTED from upstream's own two tables (`EXTENSION_MAP`
+// in `dist/extraction/grammars.js`, `DEFAULT_CONFIG` in `dist/types.js`),
+// and every candidate is confirmed against upstream's own decision pair
+// (`isLanguageSupported(detectLanguage(...))` — the same two functions
+// `extraction/index.js` calls). Upstream can add an extension tomorrow and
+// this module picks it up with no edit here; the "five" above is a
+// measurement, not a constant in the code.
+//
+// Additive, never clobbering: a project's `include` is append-only from
+// here. No user entry is removed, reordered or rewritten, and an extension
+// any existing entry already admits is left alone. Append-only is the same
+// posture `codegraph-exclude-repair.ts` takes toward a third-party config
+// file it edits.
+//
+// Scope: PURE (`normalizeCodegraphInclude`) plus ONE read-only adapter
+// (`upstreamIncludeCandidateExtensions`, which reads the installed upstream
+// package). Nothing in this module writes a file.
+//
+// NOTE FOR FUTURE EDITORS: glob literals contain the two-character
+// sequence that ends a block comment, so every comment in this file uses
+// `//` lines — INCLUDING the exported API documentation, which is why this
+// file has no `/** ... */` blocks. Do not convert them.
+import { createRequire } from 'node:module';
+import { dirname, extname, join } from 'node:path';
+import { compileCodegraphGlobs } from './codegraph-exclude-reconciler.js';
+// ─────────────────────────────────────────────────────────────────────
+// Which extensions does this project's `include` already admit?
+// ─────────────────────────────────────────────────────────────────────
+// The pattern upstream's own template uses for a bare extension: all 32
+// entries of `DEFAULT_CONFIG.include` have exactly this shape, and they are
+// matched with `picomatch(..., { dot: true })` — the same engine, and the
+// same options, that `matchesCodegraphGlob` delegates to. So an appended
+// pattern is indistinguishable in form from an upstream-authored one.
+function includePatternForExtension(extension) {
+    return `**/*${extension}`;
+}
+// A synthetic path used ONLY to ask "does any existing rule admit a file
+// with this extension". A root-level probe answers that question exactly
+// for every pattern shape upstream itself writes, because `picomatch`'s
+// trailing-slash-star-star prefix matches zero path segments (measured:
+// the `.mjs` pattern matches both `probe.mjs` and `a/b/probe.mjs`).
+//
+// KNOWN PROXY LIMIT, stated rather than hidden: a path-narrowed rule such as
+// a `src`-prefixed brace list of js/mjs does NOT match the root-level probe,
+// so an extension admitted only under a subdirectory is treated as
+// uncovered and the bare extension pattern is appended. That errs ADDITIVE —
+// the index admits more tracked files, never fewer — and it is pinned by a
+// test rather than left to be discovered. A false "already covered" cannot
+// occur for any pattern upstream's template can produce, and if it did its
+// only effect would be to leave the gap the inspector already reports.
+function extensionProbePath(extension) {
+    return `codegraph-include-probe${extension}`;
+}
+// Compiled ONCE per rule, never per (candidate x rule) pair — see
+// `compileCodegraphGlobs`. The `matchers` list is the include list the
+// candidate is tested against: the caller's entries first, then the
+// patterns this same pass has already decided to append, so a duplicate
+// candidate cannot append twice without re-parsing the list each time
+// (perf audit S10: the re-parse was 0.25 / 2.15 / 23.4 / 234.4 ms at
+// 32 / 320 / 3,200 / 32,000 rules, plus a spread array per candidate).
+function isExtensionAdmitted(extension, matchers) {
+    const probe = extensionProbePath(extension);
+    return matchers.some((matcher) => matcher.matchesAny(probe));
+}
+// Pure: given the current `include` list and the extensions upstream
+// supports but its own template omits, return the list with the uncovered
+// ones appended. No fs, no clock, no serialization.
+//
+// The result is always a SUPERSET of the input, in the input's order, so a
+// caller can never remove or reorder a user entry. Appending an extension
+// the list already admits is a no-op, which is what makes the whole
+// normalization idempotent: feeding the repaired list back in yields
+// `changed: false`.
+//
+// Candidates are de-duplicated by their EFFECT, not by string equality:
+// each candidate is tested against the input list PLUS the patterns this
+// call has already appended, so a duplicate candidate cannot append twice.
+export function normalizeCodegraphInclude(input) {
+    const addedPatterns = [];
+    // The include list as this pass sees it, compiled once. Appending a
+    // pattern extends the list by ONE compiled rule instead of re-parsing
+    // every entry on the next candidate (see `isExtensionAdmitted`).
+    const matchers = [compileCodegraphGlobs(input.include)];
+    for (const candidate of input.candidateExtensions) {
+        const extension = candidate.startsWith('.') ? candidate : `.${candidate}`;
+        if (isExtensionAdmitted(extension, matchers)) {
+            continue;
+        }
+        const pattern = includePatternForExtension(extension);
+        addedPatterns.push(pattern);
+        matchers.push(compileCodegraphGlobs([pattern]));
+    }
+    if (addedPatterns.length === 0) {
+        return { changed: false, include: input.include, addedPatterns: [] };
+    }
+    return {
+        changed: true,
+        include: [...input.include, ...addedPatterns],
+        addedPatterns
+    };
+}
+let cachedCandidateExtensions = null;
+// The extensions upstream's extractor supports but its own default
+// `include` template never names, as dotted extensions — measured against
+// the installed `@colbymchenry/codegraph` 0.7.10 as `.mjs`, `.cjs`,
+// `.pyw`, `.hxx`, `.rake`, in that order.
+//
+// Derived entirely from upstream's own data:
+//
+//   1. `EXTENSION_MAP` keys are the extension universe the extractor knows.
+//   2. The extensions upstream's template already names are read off
+//      `DEFAULT_CONFIG.include` — the entry's own extension, so the
+//      comparison is extension-to-extension and cannot be confused by a
+//      template that switches glob syntax.
+//   3. A candidate is kept only when upstream's own support decision
+//      accepts it, so a table entry with no grammar behind it is never
+//      repaired into the config.
+//
+// Returns the same array on every call (module-level cache); the two
+// modules only define tables and functions, so the load is cheap and
+// Node's `require` cache makes later calls free.
+export function upstreamUnnamedIncludeExtensions() {
+    if (cachedCandidateExtensions === null) {
+        const require = createRequire(import.meta.url);
+        const packageJsonPath = require.resolve('@colbymchenry/codegraph/package.json');
+        const distDir = join(dirname(packageJsonPath), 'dist');
+        const types = require(join(distDir, 'types.js'));
+        const grammars = require(join(distDir, 'extraction', 'grammars.js'));
+        const namedByTemplate = new Set(types.DEFAULT_CONFIG.include.map((entry) => extname(entry).toLowerCase()));
+        cachedCandidateExtensions = Object.keys(grammars.EXTENSION_MAP).filter((extension) => !namedByTemplate.has(extension.toLowerCase()) &&
+            grammars.isLanguageSupported(grammars.detectLanguage(`probe${extension}`)));
+    }
+    return cachedCandidateExtensions;
+}

package/dist/services/codegraph/codegraph-index-integrity.d.ts

@@ -0,0 +1,268 @@
+import { type ReadCodegraphExcludeConfig, type ReadTrackedFiles } from './codegraph-exclude-reconciler.js';
+/**
+ * Exit code `peaks codegraph status` uses when the index itself is
+ * incomplete or stale — distinct from `CODEGRAPH_INTEGRITY_EXIT_CODE` (74,
+ * the exclude-rule gate) and from `CODEGRAPH_INIT_CONFLICT_EXIT_CODE` (73).
+ *
+ * Why distinct rather than reusing 74: the two gates have different
+ * REMEDIATIONS. 74 means "these `exclude` rules must be dropped", and a CI
+ * job keyed on 74 already knows to run `repair-exclude`. 75 means "the
+ * index content does not match the repository — a supported tracked file
+ * is missing from it, or it holds rows for files that are gone". Folding
+ * that into 74 would silently re-point an existing consumer at a different
+ * fix. When BOTH gates fire, 74 wins (the exclude gap is the upstream
+ * cause; repairing it and rebuilding also clears staleness).
+ *
+ * NOTE (2026-09-16 policy change): 75 is only reachable in STRICT mode.
+ * See `isCodegraphIndexStrictMode`.
+ */
+export declare const CODEGRAPH_INDEX_INTEGRITY_EXIT_CODE = 75;
+/**
+ * Exit code for "the index axis could not be measured at all" — the db is
+ * present but unreadable, or its schema no longer has the `files` table
+ * (an upstream bump), or `git ls-files` / the config read failed.
+ *
+ * Distinct from BOTH 0 and 75 on purpose, and it applies in every mode
+ * including the advisory default:
+ *
+ *   - 0 would say "I checked and it is fine". It does not.
+ *   - 75 would say "I checked and the index does not cover the
+ *     repository", which asserts a measurement that never happened.
+ *
+ * Why it is not merely advisory (the user's option C covers `gap`, not
+ * this): option C exists so that upgrading peaks-loop cannot turn a
+ * *healthy* project red — the three downstream triggers it names (a
+ * tracked `.mjs`, an un-purged dead row, a deliberately narrowed
+ * `include`) are all `gap`-class. "Could not read my own input" is never a
+ * healthy-project condition: it requires `.codegraph/codegraph.db` to be
+ * present but unreadable, and `.codegraph/` is gitignored, so a downstream
+ * CI checkout normally has no index at all and reports `not-applicable`
+ * (exit 0, no output). This is the exact failure class
+ * `codegraph-exclude-reconciler.ts:76-82` documents as the reason that
+ * module exists.
+ */
+export declare const CODEGRAPH_INDEX_UNEVALUABLE_EXIT_CODE = 76;
+/**
+ * The one command that repairs what this axis detects (slice-002). Exported
+ * as a constant rather than spelled out at each site so the human line, the
+ * doctor message and the JSON `nextActions` cannot name three different
+ * things: the renderer below, the doctor check and the CLI envelope all
+ * interpolate this value.
+ *
+ * It repairs BOTH axes in one run — `include` normalization, `exclude` rule
+ * drops against the normalized include, then a FORCED index rebuild (the
+ * only upstream path that drops rows for files deleted in an earlier
+ * commit; see `CodegraphExcludeRepairOptions.reindex`).
+ */
+export declare const CODEGRAPH_REPAIR_INDEX_COMMAND = "peaks codegraph repair-index --project <root>";
+/**
+ * Opt-in switch for the user's option C decision (advisory by default,
+ * blocking on request). Set `PEAKS_CODEGRAPH_INDEX_STRICT=1` (or `true`)
+ * to make a detected index gap block: `status` exits 75 and the doctor
+ * check loses its `severity: 'warning'` tag and flips the doctor exit code.
+ *
+ * Why an environment variable rather than a config key or a CLI flag:
+ *
+ *   - ONE mechanism covers both consumers. `peaks codegraph status` and
+ *     `peaks doctor` are separate command surfaces; a CLI flag would have
+ *     to be threaded through the doctor's option plumbing as well, and the
+ *     default doctor probe takes no arguments.
+ *   - CI is where the need lives, and CI sets environment variables.
+ *   - A config key would have to live in the gitignored
+ *     `.codegraph/config.json` (upstream's file, which this slice must
+ *     never write) — so it would not survive a clone and could not
+ *     configure a CI job at all.
+ *   - It writes no state, so it does not weaken the read-only contract.
+ *
+ * Discoverability: the advisory warning text names this variable
+ * verbatim, so an operator who wants blocking is told how to get it at
+ * the moment they see the finding.
+ */
+export declare const CODEGRAPH_INDEX_STRICT_ENV_VAR = "PEAKS_CODEGRAPH_INDEX_STRICT";
+/** True when the project opted in to blocking index-gap verdicts. */
+export declare function isCodegraphIndexStrictMode(env?: Readonly<Record<string, string | undefined>>): boolean;
+/**
+ * The four outcomes of the index axis, kept apart so that no consumer
+ * that CAN carry four outcomes collapses two:
+ *
+ *   - `clean`         — measured, nothing wrong.
+ *   - `gap`           — measured, the index does not cover the repository.
+ *   - `not-evaluated` — the axis was attempted and FAILED (unreadable db,
+ *                       schema drift, no git work tree, malformed/missing
+ *                       config). The index is NOT known to be fine.
+ *   - `not-applicable`— there is no index here at all (no `codegraph.db`):
+ *                       the pre-init / dangling state, which is not a defect.
+ *
+ * `not-evaluated` and `not-applicable` both used to be `null` in the
+ * machine envelope, which is how "I could not check" came to be reported
+ * identically to "there is nothing to check".
+ *
+ * SCOPE OF THE CLAIM (narrowed under R12-2 — the earlier wording, "no
+ * consumer can collapse two of them", was overbroad). This module keeps
+ * all four apart, and so do `peaks codegraph status`'s two channels (the
+ * `[FAIL]`/`[WARN]` tags and `indexIntegrityVerdict` + the exit codes 0 /
+ * 75 / 76). The DOCTOR does not: its check shape is `{ok, severity?}`
+ * (legacy `DoctorCheck`, kept back-compatible on purpose), so
+ * `not-evaluated` and an advisory `gap` are BOTH `ok:false,
+ * severity:'warning'` and are told apart by message text alone — see
+ * `doctor-service/checks/codegraph-index-integrity.ts`. That collapse is
+ * recorded, not fixed: neither state reads as `ok:true`, so the invariant
+ * this axis exists for ("could not evaluate" must never pass as "verified
+ * clean") still holds there, and in the advisory default neither state
+ * moves the doctor exit code — so no exit-code consumer is misled by it.
+ * Under `PEAKS_CODEGRAPH_INDEX_STRICT=1` the two ARE separated in the
+ * machine fields (`severity` survives on `not-evaluated`, is dropped from
+ * `gap`), which is pinned by a test.
+ */
+export type CodegraphIndexIntegrityVerdict = 'clean' | 'gap' | 'not-evaluated' | 'not-applicable';
+/**
+ * Fold the inspected report (null when there is no index to inspect) and
+ * the caught failure (null when nothing threw) into one verdict. This is
+ * the single place the four outcomes are distinguished, so a caller
+ * cannot re-derive them differently.
+ */
+export declare function resolveCodegraphIndexIntegrityVerdict(report: CodegraphIndexIntegrityReport | null, warning: string | null): CodegraphIndexIntegrityVerdict;
+/**
+ * The exit code the index axis contributes, or `null` when it
+ * contributes none (clean / not-applicable → the caller's exit code is
+ * left alone).
+ */
+export declare function codegraphIndexIntegrityExitCode(verdict: CodegraphIndexIntegrityVerdict, strict: boolean): number | null;
+export type CodegraphIndexIntegrityReport = {
+    /** Absolute path of the inspected `.codegraph/config.json`. */
+    readonly configPath: string;
+    /** Absolute path of the inspected index database. */
+    readonly databasePath: string;
+    /** True when either axis is non-empty. `[OK]` must not be printed then. */
+    readonly gap: boolean;
+    /** Git-tracked files upstream's extractor would ingest (any extension). */
+    readonly trackedSourceCount: number;
+    /** Of those, the ones the config's `include` globs admit. */
+    readonly admittedTrackedCount: number;
+    /** Class ① — supported tracked files `include` does not admit. */
+    readonly includeGap: readonly string[];
+    /** Rows in the index's `files` table. */
+    readonly indexedFileCount: number;
+    /** Class ② — index rows whose path no longer exists on disk. */
+    readonly deadRows: readonly string[];
+};
+/**
+ * Everything `inspectCodegraphIndexIntegrityFrom` needs, already resolved.
+ * Pure input: no fs, no spawn, no clock — the adapters below supply it.
+ */
+export type CodegraphIndexIntegrityInput = {
+    readonly configPath: string;
+    readonly databasePath: string;
+    readonly trackedFiles: readonly string[];
+    readonly include: readonly string[];
+    /** Project-relative paths carried by the index's `files` table. */
+    readonly indexedPaths: readonly string[];
+    /** True when upstream's extractor supports `filePath`'s language. */
+    readonly supportsPath: (filePath: string) => boolean;
+    /** True when a project-relative index path still exists on disk. */
+    readonly pathExists: (projectRelativePath: string) => boolean;
+};
+/**
+ * Pure fold over already-resolved data. Both axes are set differences, so
+ * neither can be satisfied by a self-consistency assertion: axis ① compares
+ * git's tracked set against the `include` matcher, axis ② compares the
+ * index's own rows against the filesystem.
+ */
+export declare function inspectCodegraphIndexIntegrityFrom(input: CodegraphIndexIntegrityInput): CodegraphIndexIntegrityReport;
+/** The upstream decision, verbatim: detect the language, then ask if it has a grammar. */
+export declare function upstreamSupportsPath(filePath: string): boolean;
+/**
+ * Per-call, bounded replacement for the per-row `existsSync` above.
+ *
+ * WHY: the fold calls `pathExists` once per index row (`inspectCodegraph
+ * IndexIntegrityFrom`), so the gate is O(rows) full-path stats at ~13.5 µs
+ * each — 35 ms at 1.2k rows, 1,923 ms at 100x. It is unbounded in the size
+ * of the index. What is replaced is the COST, not the authority: a row is
+ * confirmed PRESENT by looking its basename up in one cached listing of its
+ * parent directory, so the number of filesystem calls is bounded by the
+ * number of DISTINCT DIRECTORIES the index names — which is bounded by the
+ * repository, not by the index.
+ *
+ * A listing may only answer `true`, and only for an entry whose dirent is
+ * positively a plain file or a plain directory. For exactly those entries,
+ * "the name is in `readdir`" and "`existsSync` on the joined path is true"
+ * cannot disagree. Everything else falls through to
+ * `codegraphIndexPathExists` — the old implementation, verbatim — so the
+ * classes this cache cannot decide are decided exactly as they always were:
+ *
+ *   - a symlink or junction entry (`isSymbolicLink()`, Windows included:
+ *     a junction reports `isDirectory() === false`), because a BROKEN link
+ *     is listed by `readdir` and is absent from disk;
+ *   - a case-differing path on a case-insensitive filesystem — the listing
+ *     carries the on-disk spelling, so `SRC/OK.TS` misses and the stat
+ *     decides (true on Windows, false on Linux, exactly as before);
+ *   - a path naming a directory, or any non-file special entry;
+ *   - a parent that is missing, unreadable, or not a directory at all
+ *     (`readdir` throws → `null`, memoized so the failure costs one call);
+ *   - a trailing-slash or empty row, and a project root that does not exist.
+ *
+ * The cache lives for ONE `inspectCodegraphIndexIntegrity` call, so a
+ * second command re-reads the tree and cannot be served a stale listing.
+ * Within a call, a listing taken before a concurrent delete is the only
+ * divergence from the old code — both implementations race the filesystem,
+ * and neither holds a snapshot.
+ */
+export declare function createCodegraphIndexPathExists(): (projectRoot: string, projectRelativePath: string) => boolean;
+/**
+ * Injection seam for `inspectCodegraphIndexIntegrity`.
+ *
+ * `trackedFiles` / `config` are the ALREADY-READ shared inputs (perf audit
+ * F1) — the CLI reads them once and hands the same values to both codegraph
+ * axes, so the `git ls-files` spawn, the config read and the `include`
+ * glob compilation happen once per command instead of twice. They are
+ * values, not reader functions, because that is what the caller has: the
+ * read has already happened by the time either axis runs.
+ *
+ * Both are READ-MARKED (code review R4-1): only a value returned by the
+ * readers is admissible. An explicit `[]` — which the seam used to accept
+ * and which silently meant "nothing is tracked", erasing every include-gap
+ * — is now a compile error and a run-time throw. `undefined`/omitted still
+ * means "read it yourself", exactly as before.
+ *
+ * The three remaining fields are genuine per-call adapters, used by tests
+ * to drive the fold without touching a real db or the real oracle.
+ */
+export type CodegraphIndexIntegrityDeps = {
+    readonly trackedFiles?: ReadTrackedFiles | undefined;
+    readonly config?: ReadCodegraphExcludeConfig | undefined;
+    readonly readIndexedPaths?: (projectRoot: string) => readonly string[];
+    readonly supportsPath?: (filePath: string) => boolean;
+    readonly pathExists?: (projectRoot: string, projectRelativePath: string) => boolean;
+};
+/**
+ * Read-only entry point: resolve git's tracked files, the config's
+ * `include` globs and the index's own rows from disk, then fold them into
+ * one report. Throws (never silently degrades) when the project is not a
+ * git work tree, the config is missing/malformed, or the index is absent —
+ * callers that must stay alive (`status`, doctor) catch and surface it.
+ */
+export declare function inspectCodegraphIndexIntegrity(projectRoot: string, deps?: CodegraphIndexIntegrityDeps): CodegraphIndexIntegrityReport;
+/**
+ * Human-readable detail lines for a gapped report, grouped by axis so an
+ * operator can tell which defect they have (and whether they have both).
+ *
+ * Returns an empty array for a clean report — the caller decides whether
+ * "clean" is worth printing at all.
+ *
+ * `blocking` is the user's option C switch, and it changes the TAG, not
+ * the finding: advisory (the default) prints `[WARN]` and the command
+ * exits 0; strict prints `[FAIL]` and the command exits 75. The verdict
+ * word is chosen here rather than by the caller so the two channels
+ * cannot disagree about the same report.
+ *
+ * The remediation sentence NAMES the real command (`peaks codegraph
+ * repair-index`). Slice-001 deliberately named none, because naming a
+ * command that does not exist yet reproduces the exact failure this gate
+ * exists to prevent (an operator following a hint into "command not
+ * found"). Slice-002 shipped that command, so the obligation recorded in
+ * slice-001's design decision 4 is discharged here — and the name is
+ * exported as a constant so the renderer, the doctor message and the
+ * error envelope cannot drift from the command that is actually
+ * registered.
+ */
+export declare function renderCodegraphIndexIntegrityLines(report: CodegraphIndexIntegrityReport, blocking: boolean): readonly string[];