peaks-loop 4.0.51 → 4.0.52

package/dist/services/codegraph/codegraph-exclude-repair.d.ts

@@ -1,68 +1,79 @@
 import { type CodegraphProcessRunner } from './codegraph-service.js';
-/** Suffix of the byte-exact pre-repair copy kept next to the config. */
-export declare const CODEGRAPH_CONFIG_BACKUP_SUFFIX = ".bak";
-export type CodegraphExcludeRepairPlan = {
-    /** True when at least one rule would actually be dropped. */
-    readonly changed: boolean;
-    /** The `exclude` array after the removal. */
-    readonly exclude: readonly string[];
-    /** Rules actually present in `exclude` and dropped, in config order. */
-    readonly removedRules: readonly string[];
-};
-/**
- * Pure: given the current `exclude` list and the rules to drop, return
- * the new list. No fs, no clock, no serialization.
- *
- * A rule named in `rulesToRemove` but absent from `exclude` is NOT
- * invented — the result is a subset of the input, so a caller can
- * never add a rule by accident. Removing an already-absent rule is a
- * no-op, which is what makes the whole repair idempotent: feeding the
- * repaired list back in yields `changed: false`.
- */
-export declare function repairCodegraphExclude(input: {
-    readonly exclude: readonly string[];
-    readonly rulesToRemove: readonly string[];
-}): CodegraphExcludeRepairPlan;
-export type CodegraphExcludeRepairOutcome = {
-    readonly applied: false;
-    readonly reason: 'no-rules-to-remove';
-    readonly removedRules: readonly string[];
-} | {
-    readonly applied: true;
-    readonly configPath: string;
-    readonly backupPath: string;
-    readonly removedRules: readonly string[];
-    readonly excludeCountBefore: number;
-    readonly excludeCountAfter: number;
-};
-/**
- * Apply the repair to `<projectRoot>/.codegraph/config.json`.
- *
- * No-op (and no write, no mtime change, no backup) when
- * `rulesToRemove` is empty. Otherwise: back up the original bytes to
- * `config.json.bak`, then rewrite the file with `exclude` reduced by
- * exactly the rules that were both requested and present.
- *
- * Throws only on real fs/parse failures — the caller decides whether
- * that is fatal (`repair-exclude` → non-zero exit) or a surfaced
- * warning (`init` → keep going, the init itself already succeeded).
- */
-export declare function applyCodegraphExcludeRepair(projectRoot: string, rulesToRemove: readonly string[]): CodegraphExcludeRepairOutcome;
+import { applyCodegraphConfigRepair, CODEGRAPH_CONFIG_BACKUP_SUFFIX, repairCodegraphExclude, repairCodegraphInclude, type CodegraphConfigRepairOutcome, type CodegraphConfigRepairPlan, type CodegraphExcludeRepairPlan } from './codegraph-config-repair-writer.js';
+export { applyCodegraphConfigRepair, CODEGRAPH_CONFIG_BACKUP_SUFFIX, repairCodegraphExclude, repairCodegraphInclude };
+export type { CodegraphConfigRepairOutcome, CodegraphConfigRepairPlan, CodegraphExcludeRepairPlan };
 export type CodegraphExcludeRepairReport = {
     /** True when the config was actually rewritten. */
     readonly applied: boolean;
     /** Rules dropped from `exclude`. */
     readonly rulesRemoved: readonly string[];
+    /**
+     * Patterns appended to `include` (slice-002). Always a subset of the
+     * include reconciler's candidates that were not already admitted.
+     */
+    readonly includePatternsAdded: readonly string[];
     /** Distinct tracked source files the dropped rules had been hiding. */
     readonly filesRecovered: number;
-    /** Tracked files the config's `include` filter admits at all. */
+    /**
+     * Distinct tracked source files the WIDENED `include` list newly admits —
+     * the INCLUDE axis' counterpart of `filesRecovered`, and a DIFFERENT
+     * number on purpose.
+     *
+     * `filesRecovered` counts the exclude axis only. Before this field
+     * existed, `appliedRepairNote` printed `filesRecovered` inside a sentence
+     * whose subject was both axes, so the measured run that added 5 include
+     * patterns for 31 tracked `.mjs`/`.cjs` files reported "removed 0 exclude
+     * rule(s), recovering 0 tracked source file(s)" — a true statement about
+     * one axis read as a verdict on both (defect A1 of
+     * `2026-09-17-codegraph-msg-and-refresh`).
+     *
+     * It is a measured DELTA, not a re-report of an absolute count:
+     * `includeAdmittedAfter` minus the same admission measurement taken over
+     * the ON-DISK include list. Reporting `includeAdmittedAfter` itself as
+     * "recovered" would be the tautology slice-002 removed from the
+     * coverage ratio (an absolute count says nothing about what changed).
+     *
+     * Zero by construction when the include plan did not change — the
+     * normalized list IS the on-disk list then — which is also why the extra
+     * admission pass is gated on `includePlan.changed`: the no-op path (every
+     * automatic seam, every re-run) pays nothing for it, unlike the pass
+     * slice-002 removed (that one ran on ALL seams, including no-ops).
+     */
+    readonly includeFilesRecovered: number;
+    /**
+     * Tracked files the normalized `include` list admits — the NUMERATOR of
+     * the coverage ratio. Identical to
+     * `reconcileCodegraphExclude`'s `trackedSourceCount` for the normalized
+     * list, so it costs no second filtering pass.
+     */
+    readonly includeAdmittedAfter: number;
+    /**
+     * Tracked files upstream's extractor would ingest (any supported
+     * extension) — the DENOMINATOR, and the same quantity the index axis
+     * reports under this same field name (`CodegraphIndexIntegrityReport`).
+     *
+     * It is measured independently of `includeAdmittedAfter` (an extension
+     * decision per tracked file, not a glob match), so the two CAN differ and
+     * the ratio can report a shortfall. The field used to be fed from the
+     * reconciler's admitted count, i.e. the numerator again, which made every
+     * "N of N" the consumers printed a tautology.
+     */
     readonly trackedSourceCount: number;
-    /** Absolute path of the rewritten config (empty when nothing was written). */
+    /**
+     * Absolute path of the rewritten config. Empty when nothing was written
+     * AND the reads failed (there is no config to name).
+     */
     readonly configPath: string;
     /** Byte-exact rollback copy (null when nothing was written). */
     readonly backupPath: string | null;
     /** True when the post-repair `codegraph index` finished successfully. */
     readonly reindexed: boolean;
+    /**
+     * True when the follow-up index was run with upstream's `--force`, i.e.
+     * as a full rebuild that drops rows for files that no longer exist. An
+     * incremental index cannot do that — see `CodegraphExcludeRepairOptions`.
+     */
+    readonly forcedRebuild: boolean;
     /**
      * Non-null when the step could not run to completion (no git repo,
      * missing config, malformed config, upstream index failure, …).
@@ -80,13 +91,56 @@ export type CodegraphExcludeRepairOptions = {
      * step: the pre-dispatch preflight and the post-slice autorefresh
      * both call `init` → `index`, and an index is expensive enough
      * (5-30 s on this repo) that a fresh init must not pay for it twice.
+     *
+     * When `'force'`, run `codegraph index --force` instead: upstream's
+     * `--force` is `clear()` + full re-index, and it is the ONLY documented
+     * way to drop rows for files deleted in an earlier commit. Verified in
+     * the installed upstream source (0.7.10):
+     *
+     *   - `dist/bin/codegraph.js` → `index --force` calls `cg.clear()` then
+     *     `cg.indexAll()`;
+     *   - `dist/db/queries.js` `clear()` deletes unresolved_refs, edges,
+     *     nodes and files;
+     *   - plain `indexAll()` (`dist/extraction/index.js`) scans and upserts
+     *     every file but never removes a row, so an incremental index keeps
+     *     rows for paths that are gone;
+     *   - `codegraph sync` DOES delete them, but only for the deletions
+     *     `git status --porcelain` reports in the WORKING TREE. Measured on
+     *     this repo: all four dead rows are committed deletions, invisible to
+     *     `git status`, so `sync` would purge none of them.
+     *
+     * Cost note. The PARSE half of the old claim here was exactly true and
+     * is kept: plain `indexAll()` already re-reads and re-parses EVERY file
+     * (its only skip is `maxFileSize`). The PRICE half was wrong and is
+     * corrected to the perf audit's measurements, because it is the sentence
+     * a future reader would quote: `storeExtractionResult`
+     * (`dist/extraction/index.js`) hash-skips all WRITES for unchanged files
+     * in a plain `index`, so `--force` additionally pays a full re-insert of
+     * every node and edge after `clear()`. Executed with the real binary on a
+     * 2,100-file fixture, paired 5 runs: plain median 3,810 ms vs forced
+     * 5,400 ms = +1,590 ms (+42 %), positive 5/5; on a copy of this repo's db,
+     * `clear()` alone is 414/462/537 ms while clear+reinsert is 2.7-6.2 s.
+     * "Forced" is a real cost, not a rounding error.
+     *
+     * That does NOT change the policy: the reason the automatic seams do not
+     * force is policy, not cost. The advisory-by-default decision (user option
+     * C) exists so that upgrading peaks-loop cannot change a downstream
+     * project's cost profile, and purging dead rows is the caller's explicit
+     * request instead.
      */
-    readonly reindex?: boolean;
+    readonly reindex?: boolean | 'force';
 };
 /**
- * Reconcile `projectRoot`'s exclude list, drop the rules that block
- * tracked source files, and rebuild the index so the recovered files
- * actually land in it.
+ * Reconcile `projectRoot`'s config against its tracked files — normalize
+ * `include`, then drop the `exclude` rules that block tracked source files
+ * — and rebuild the index so the recovered files actually land in it.
+ *
+ * ORDER IS LOAD-BEARING. `exclude` is reconciled against the NORMALIZED
+ * include list, never the on-disk one: an `exclude` rule that blocks only a
+ * file `include` drops reconciles clean today and starts biting the moment
+ * `include` is widened, so reconciling before normalizing would let this
+ * run report success over a config it had just made worse. See the module
+ * header.
  *
  * This is the ONE shared "after upstream init" self-heal: the CLI's
  * fresh `peaks codegraph init`, the pre-dispatch preflight and the