@event4u/agent-config 14.22.0 → 15.0.0

package/src/scripts/code_graph/detect.ts

@@ -184,3 +184,41 @@ export function computeVerdict(root: string, nativeCache: string): VerdictJSON {
         sources,
     };
 }
+
+/** Cache path a repository root's native graph lives at, repo-relative. */
+export const NATIVE_CACHE_REL = path.join('agents', 'runtime', 'state', 'code-graph-v1.json');
+
+/**
+ * The three-state staleness token every consumer of the graph reports.
+ *
+ * Lives HERE rather than in the PreToolUse hook that first needed it
+ * (`hooks/code_graph_context_hook.ts`, step 1.2). Phase 3's verbs must each
+ * print the staleness state, and an engine module importing a hook module to
+ * learn it would invert the dependency direction D9 measures — the hook imports
+ * the engine, never the other way round. The hook re-exports this so its own
+ * consumers are unaffected.
+ */
+export type GraphState = 'absent' | 'fresh' | `behind:${number}`;
+
+/**
+ * Resolve the graph's state for `root`.
+ *
+ * `absent` means no source at all — the silent case. A picked source whose
+ * staleness is UNKNOWN reads as `fresh`, mirroring {@link computeVerdict}'s own
+ * `picked.stale ? STALE : FRESH`: unknown is not treated as stale, because
+ * inventing a commit count would be worse than reporting none.
+ *
+ * `nativeCache` overrides where the native graph is looked for. It exists
+ * because a verb invoked with an explicit `--graph <path>` would otherwise
+ * report `absent` while answering from that very file — the state of a cache
+ * nobody asked about. Passing the graph the verb is actually reading makes the
+ * printed staleness a statement about the answer rather than about a
+ * convention.
+ */
+export function graphState(root: string, nativeCache?: string): GraphState {
+    const picked = pickSource(detectSources(root, nativeCache ?? path.join(root, NATIVE_CACHE_REL)));
+    if (!picked) return 'absent';
+    if (picked.stale !== true) return 'fresh';
+    const behind = picked.commits_behind;
+    return `behind:${typeof behind === 'number' ? behind : 0}`;
+}

package/src/scripts/code_graph/query.ts

@@ -47,6 +47,15 @@ export interface LoadedGraph {
      */
     graph: CodeGraph | null;
     source: string; // attribution path
+    /**
+     * The on-disk path the answer came from.
+     *
+     * Distinct from `source`, which is a display string (`native:relpath`) and
+     * cannot be handed to a freshness check. A verb that prints staleness has
+     * to describe THIS file, not a conventional cache path — see
+     * `cli.ts::stateOf`.
+     */
+    answeredBy: string;
     byId: NodeLookup;
     out: AdjacencyLookup;
     in: AdjacencyLookup;
@@ -54,6 +63,16 @@ export interface LoadedGraph {
     idsByLabel(label: string, limit: number): string[];
     /** Non-file nodes declared in any of `files`. */
     idsInFiles(files: readonly string[]): string[];
+    /**
+     * Every node id, sorted.
+     *
+     * A whole-table read, and unlike {@link LoadedGraph.lex} it is not lazy —
+     * because the one verb that calls it (`dead`, 3.3) is defined over every
+     * node by construction: "zero accepted in-edges" is not a question you can
+     * ask about a frontier. Nothing else may use it; a verb that walks from a
+     * seed has `idsByLabel` / `idsInFiles` for that.
+     */
+    allNodeIds(): string[];
     /**
      * BM25 fallback corpus, LAZY.
      *
@@ -78,7 +97,7 @@ export interface LoadedGraph {
  * same label repeatedly while rendering edge lines, and that repetition is
  * cheap to remove and expensive to leave.
  */
-function indexBackedGraph(index: GraphIndex, source: string): LoadedGraph {
+function indexBackedGraph(index: GraphIndex, source: string, answeredBy: string): LoadedGraph {
     const nodeCache = new Map<string, CodeNode | undefined>();
     const readNode = (id: string): CodeNode | undefined => {
         if (nodeCache.has(id)) return nodeCache.get(id);
@@ -90,11 +109,13 @@ function indexBackedGraph(index: GraphIndex, source: string): LoadedGraph {
     return {
         graph: null,
         source,
+        answeredBy,
         byId: { get: readNode, has: (id) => readNode(id) !== undefined },
         out: { get: (id) => index.edgesFrom(id) },
         in: { get: (id) => index.edgesTo(id) },
         idsByLabel: (labelText, limit) => index.idsByLabel(labelText, limit),
         idsInFiles: (files) => index.idsInFiles(files),
+        allNodeIds: () => index.allNodeIds(),
         lex: () => {
             lexical ??= new LexicalIndex(index.lexicalCorpus());
             return lexical;
@@ -111,7 +132,7 @@ export function loadGraph(graphPath: string, source = graphPath): LoadedGraph {
     // made it a cheaper blob transport rather than an index.
     const index = openGraphIndex(graphPath);
     if (index) {
-        if (index.edgeCount >= INDEXED_READ_MIN_EDGES) return indexBackedGraph(index, source);
+        if (index.edgeCount >= INDEXED_READ_MIN_EDGES) return indexBackedGraph(index, source, graphPath);
         // Small graph: the in-memory path is cheaper. Release the handle rather
         // than leaking a database for the life of the process.
         index.close();
@@ -146,6 +167,7 @@ export function loadGraph(graphPath: string, source = graphPath): LoadedGraph {
     return {
         graph,
         source,
+        answeredBy: graphPath,
         byId,
         out: outM,
         in: inM,
@@ -155,6 +177,7 @@ export function loadGraph(graphPath: string, source = graphPath): LoadedGraph {
             const set = new Set(files);
             return graph.nodes.filter((n) => set.has(n.source_file) && n.kind !== 'file').map((n) => n.id);
         },
+        allNodeIds: () => graph.nodes.map((n) => n.id).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)),
         lex: () => lex,
         close: () => {
             /* nothing held */

package/src/scripts/code_graph/sqlite_store.ts

@@ -45,8 +45,15 @@ import type { CodeEdge, CodeGraph, CodeNode } from './types.js';
  * fields existed — which reads back as a valid edge carrying a fabricated
  * mechanism. Refusing it costs nothing, because the twin is derived and the
  * next build re-emits it.
+ *
+ * 3 → 4 (3.2): the `Relation` union gained `tests`, so a v3 twin carries no
+ * `tests` rows for a graph whose JSON has them. No COLUMN changed, which is
+ * precisely why the bump is needed rather than optional: a v3 twin would read
+ * back cleanly, answer `tests-for` with the empty set, and the caller could not
+ * tell "nothing tests this" from "this twin predates the relation". An index
+ * that answers a question it cannot answer is worse than one that refuses.
  */
-export const GRAPH_STORE_VERSION = 3;
+export const GRAPH_STORE_VERSION = 4;
 
 /**
  * Edge count at or above which the indexed read path replaces the blob path.
@@ -227,6 +234,9 @@ export interface GraphIndex {
     idsByLabel(label: string, limit: number): string[];
     /** Non-file nodes declared in any of `files` — the changed-seed lookup. */
     idsInFiles(files: readonly string[]): string[];
+    /** Every node id, sorted. A whole-table read, for `dead` only — see
+     * `LoadedGraph.allNodeIds`. */
+    allNodeIds(): string[];
     /** Every node's id + searchable text. The ONLY whole-table read, and it
      * exists because a BM25 fallback genuinely needs the corpus. Callers reach
      * it only after an exact id AND an exact label both missed. */
@@ -373,6 +383,11 @@ export function openGraphIndex(jsonPath: string): GraphIndex | null {
                     }
                     return out;
                 },
+                allNodeIds() {
+                    return (db.prepare('SELECT id FROM nodes ORDER BY id').all() as { id: string }[]).map(
+                        (r) => r.id,
+                    );
+                },
                 lexicalCorpus() {
                     return (db.prepare('SELECT id, label FROM nodes').all() as { id: string; label: string }[]).map(
                         (r) => ({ id: r.id, text: `${r.label} ${r.id}` }),

package/src/scripts/code_graph/types.ts

@@ -14,8 +14,21 @@ export type Lang = 'php' | 'typescript' | 'javascript';
 /** Same scale as `discovery_graph.ts::EdgeConfidence` (reused, not forked). */
 export type EdgeConfidence = 'EXTRACTED' | 'INFERRED' | 'AMBIGUOUS';
 
-/** Relations the extractor emits. */
-export type Relation = 'calls' | 'imports' | 'uses' | 'inherits' | 'member';
+/**
+ * Relations the graph carries.
+ *
+ * `calls` / `imports` / `uses` / `inherits` / `member` come from the extractor.
+ * `tests` is DERIVED in the build pass (`road-to-a-graph-that-is-shipped` 3.2):
+ * a test file that imports an in-repo symbol from a non-test file is asserted
+ * to test it, `resolved_via: 'test-import'`, `confidence: 'INFERRED'`. The two
+ * halves of that are deliberately split across the two axes — the import is a
+ * syntactic fact, so it is EXTRACTED evidence, while "this test tests that
+ * subject" is an inference from a naming convention, which is what INFERRED
+ * says. Deriving it in `buildGraph` rather than in the extractor keeps the
+ * extractor per-file and pure: the predicate needs only the two paths, and no
+ * grammar can see whether a file is a test.
+ */
+export type Relation = 'calls' | 'imports' | 'uses' | 'inherits' | 'member' | 'tests';
 
 /**
  * HOW an edge's target was arrived at — the mechanism, not the confidence.
@@ -66,6 +79,33 @@ export type ResolvedVia =
  */
 export type EdgeProvider = 'native';
 
+/**
+ * The two mechanisms that are GUESSES rather than statements.
+ *
+ * `name-lookup` is the repo-wide same-name table (or a lookup that found
+ * nothing); `dynamic` is a receiver the extractor cannot type. Everything else
+ * names where the target came from.
+ *
+ * Declared HERE, beside `ResolvedVia`, rather than in the query tier that first
+ * needed it — because the BUILD pass needs it too, and the reason is a defect an
+ * independent review demonstrated: a derived edge stamped with a trustworthy
+ * mechanism while its own evidence was a guess LAUNDERS the guess. A PHP
+ * `use Two\Mailer` with no `composer.json` binds by base name, so the `imports`
+ * edge is `name-lookup` and may point at `One\Mailer`; deriving a `tests` edge
+ * from it and tagging that `test-import` made a wrong target trustworthy to
+ * every consumer of the filter. One set, two readers, and the build pass can no
+ * longer disagree with the query tier about what a guess is.
+ */
+export const GUESS_RESOLVED_VIA: ReadonlySet<ResolvedVia> = new Set<ResolvedVia>([
+    'name-lookup',
+    'dynamic',
+]);
+
+/** Does this edge's target rest on a stated fact rather than a guess? */
+export function isStatedResolution(resolved_via: ResolvedVia): boolean {
+    return !GUESS_RESOLVED_VIA.has(resolved_via);
+}
+
 export interface CodeNode {
     /** Path-qualified from day one: `<relpath>#<symbol>` (collision-free). */
     id: string;
@@ -162,6 +202,15 @@ export interface CodeGraph {
 }
 
 /**
+ * Bumped 3 → 4 by `road-to-a-graph-that-is-shipped` 3.2: the `Relation` union
+ * gained `tests`, and the build pass now derives those edges. A cached sidecar
+ * written at v3 carries per-file extracts that are still correct — `tests` is
+ * derived from `imports`, not extracted — but `readSidecar` refuses a version
+ * mismatch anyway, and that refusal is the right conservative default: the
+ * alternative is a version check that has to reason about WHICH schema changes
+ * a sidecar survives, which is a rule that rots silently the first time someone
+ * adds an extractor field. A full re-extraction is the cost of being sure.
+ *
  * Bumped 2 → 3 by `road-to-a-graph-that-is-shipped` 2.2: every `CodeEdge` now
  * carries `resolved_via` and `provider`. A cached sidecar written at v2 has
  * neither, so `--update` would reuse untagged edges beside tagged ones and
@@ -178,7 +227,7 @@ export interface CodeGraph {
  * file — a silently mixed graph. `readSidecar` refuses a version mismatch, so
  * the bump is what makes that impossible rather than merely unlikely.
  */
-export const SCHEMA_VERSION = 3;
+export const SCHEMA_VERSION = 4;
 
 /** Deterministic per-file byte cap — files above this become a SKIPPED node. */
 export const MAX_FILE_BYTES = 1_000_000;

package/src/scripts/code_graph/validate.ts

@@ -4,7 +4,9 @@
  */
 import type { CodeGraph } from './types.js';
 
-const RELATIONS = new Set(['calls', 'imports', 'uses', 'inherits', 'member']);
+/** Mirrors `Relation` in types.ts. `tests` is derived by the build pass (3.2),
+ * not extracted, and is validated on exactly the same terms as the rest. */
+const RELATIONS = new Set(['calls', 'imports', 'uses', 'inherits', 'member', 'tests']);
 const CONFIDENCES = new Set(['EXTRACTED', 'INFERRED', 'AMBIGUOUS']);
 /** Mirrors `ResolvedVia` in types.ts — the full union, including the four
  * values no build emits yet (2.3 and Phase 3 add them). */