opencode-diane 0.0.5

package/dist/ingest/cross-refs.d.ts

@@ -0,0 +1,59 @@
+/**
+ * cross-refs.ts — grammar-agnostic edge discovery between files.
+ *
+ * The hard part isn't finding connections; the hard part is finding
+ * them with FEW false positives. Single-signal heuristics (regex
+ * "import" detection, free-text identifier mentions) all have
+ * meaningful FP rates that mislead the agent's navigation. This
+ * ingester uses MULTI-SIGNAL CORROBORATION:
+ *
+ *   - Filesystem-grounded signals (path-resolves-to-existing-file)
+ *     emit edges alone — the disk grounds them.
+ *   - Lexical signals (identifier mention) only emit edges when
+ *     corroborated by a SECOND orthogonal signal (rarity + import-
+ *     line context, OR rarity + filename-class coupling).
+ *
+ * Four passes:
+ *
+ *   1. Definition extraction (language-keyed regex). Builds a map
+ *      `identifier → Set<defining-file>`.
+ *   2. Import-path resolution. For each file, find import-like lines,
+ *      try to resolve the named module/path to an actual file under
+ *      the project root. Existing → edge.
+ *   3. Config path-strings. For .json/.yaml/.toml, walk string values
+ *      and try to resolve them as relative file paths. Existing → edge.
+ *   4. Corroborated identifier mentions. Tokenise each file line by
+ *      line; for tokens that are defined elsewhere AND rarity-gated,
+ *      emit an edge only when *also* corroborated by either an
+ *      import-line context or filename-class coupling.
+ *
+ * Edges with the same (source, target) pair are merged; the evidence
+ * list grows but only one memory is written per edge.
+ *
+ * **What this catches that code-map doesn't:** any cross-file
+ * connection in a language tree-sitter doesn't have a grammar for
+ * (Ruby, Pascal, Perl, Lua, Elixir, Erlang, Tcl, Nim, Zig, Swift,
+ * Kotlin, Scala, Haskell, OCaml, F#, Clojure, Pascal, VB, …), plus
+ * config-style cross-references in JSON/YAML/TOML files.
+ *
+ * **What it doesn't catch:** dynamic loads (`require(varName)`),
+ * reflection-based dispatch, anything where the connection only
+ * exists at runtime. Those are out of scope for any static technique.
+ */
+import type { MemoryRepository } from "../store/repository.js";
+export interface CrossRefsIngestResult {
+    filesWalked: number;
+    definitionsExtracted: number;
+    edgesEmitted: number;
+    /** Breakdown by primary evidence type — for the analyse-logs view. */
+    byEvidence: Record<string, number>;
+}
+export interface CrossRefsOptions {
+    /** See `UserConfig.crossRefsRarityThreshold`. Defaults to 3. */
+    rarityThreshold?: number;
+    /** See `UserConfig.crossRefsMaxFiles`. Defaults to 2000. */
+    maxFiles?: number;
+    /** See `UserConfig.crossRefsMaxEdges`. Defaults to 10 000. */
+    maxEdges?: number;
+}
+export declare function ingestCrossRefs(repo: MemoryRepository, root: string, opts?: CrossRefsOptions): Promise<CrossRefsIngestResult>;