@davesheffer/hunch 1.31.0 → 1.32.0

package/dist/extractors/git.js

@@ -2,9 +2,9 @@
  *  No LLM here — just parsing what git already knows. */
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { devNull } from "node:os";
+import { devNull, tmpdir } from "node:os";
 import { isAbsolute, resolve, join, basename, dirname, relative, sep } from "node:path";
-import { mkdirSync, rmSync, statSync, lstatSync, realpathSync, readFileSync, renameSync, readdirSync } from "node:fs";
+import { mkdtempSync, openSync, closeSync, readSync, mkdirSync, rmSync, statSync, lstatSync, realpathSync, readFileSync, renameSync, readdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { MEMLOG_FORMAT } from "../core/memorylog.js";
 import { hunchAttributesAreSafe, hunchTreeAttributesAreSafe, safeOverlayTree } from "../core/overlaySafety.js";
@@ -496,6 +496,12 @@ export function stableRepositoryName(root) {
         return `git:${roots.join("+")}`;
     return basename(mainWorktreeRoot(root));
 }
+function observeGit(observer, event) {
+    try {
+        observer?.(event);
+    }
+    catch { /* observation cannot change a Git outcome */ }
+}
 const CAPTURE_REMOTE_TIMEOUT_MS = 15_000;
 const READ_REMOTE_TIMEOUT_MS = 5_000;
 // A capture can spend roughly 90s in commit + bounded merge/push/retry seams.
@@ -698,6 +704,11 @@ export function commitAndPushHunch(hunchDir, message, opts) {
         }
         if (!committed)
             return null;
+        if (opts.observe) {
+            const commitSha = headShaWithEnv(hunchDir, env);
+            if (/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(commitSha))
+                observeGit(opts.observe, { kind: "committed", commitSha });
+        }
         if (opts.push !== false) {
             // The overlay remote is mutable process state. Re-prove the publication
             // boundary after the local commit and BEFORE pull: hooks or another
@@ -715,7 +726,7 @@ export function commitAndPushHunch(hunchDir, message, opts) {
             // proof immediately before its push seam. Repeating the same expensive proof
             // twice here adds no intervening mutation boundary and materially slows large
             // graph refreshes on process-spawn-sensitive platforms such as Windows.
-            if (pushWithOneRemoteAdvanceRetry(hunchDir, env, opts.protectedRepoRoot, CAPTURE_REMOTE_TIMEOUT_MS, opts.remote))
+            if (pushWithOneRemoteAdvanceRetry(hunchDir, env, opts.protectedRepoRoot, CAPTURE_REMOTE_TIMEOUT_MS, opts.remote, opts.observe))
                 return "pushed";
         }
         return "committed";
@@ -828,7 +839,13 @@ function isDerivedStoreArtifact(relativeName) {
         // `hunch serve` flushes INSIDE its cross-process write lock, so the lock file is always
         // staged alongside the record; treating it as a violation made every served write skip
         // the commit quietly and report durability "local" forever (1.26.0/1.26.1).
-        || relativeName === "write.lock";
+        || relativeName === "write.lock"
+        // The post-merge hook's detected-but-unconfirmed repair queue and its
+        // rejected-match tombstones (repairqueue.ts): clone-local scratch, never a
+        // memory record — must never ride a public flush's `git add .` or an
+        // overlay's force-add allowlist into shared/pushed memory.
+        || relativeName === "pending-commit-repairs.json"
+        || relativeName === "dropped-commit-repairs.json";
 }
 /** Enumerate ordinary JSON files already contained under an overlay. Push-capable
  * stores force-add this exact allowlist so remote .gitignore, info/exclude, or an
@@ -1328,7 +1345,91 @@ function upstreamSha(hunchDir, env) {
         return "";
     }
 }
-function tryPush(hunchDir, env, timeoutMs, contract) {
+/** Keep observation output limits out of the primary Git process. A bounded
+ * exec pipe can terminate an otherwise successful multi-ref push on overflow.
+ * Spool privately for the duration of the command, read at most 1 MB afterward,
+ * and discard oversized/unavailable output without changing its exit result. */
+function runObservedPush(args, env, timeoutMs, observe) {
+    if (!observe) {
+        execFileSync("git", args, { stdio: "ignore", env, timeout: timeoutMs });
+        return null;
+    }
+    let directory, descriptor;
+    try {
+        directory = mkdtempSync(join(tmpdir(), "hunch-push-observation-"));
+        descriptor = openSync(join(directory, "stdout"), "wx+", 0o600);
+    }
+    catch {
+        if (directory) {
+            try {
+                rmSync(directory, { recursive: true, force: true });
+            }
+            catch { }
+        }
+        execFileSync("git", args, { stdio: "ignore", env, timeout: timeoutMs });
+        return null;
+    }
+    try {
+        execFileSync("git", args, { stdio: ["ignore", descriptor, "ignore"], env, timeout: timeoutMs });
+        try {
+            const buffer = Buffer.alloc(1_000_001);
+            const bytes = readSync(descriptor, buffer, 0, buffer.length, 0);
+            return bytes <= 1_000_000 ? buffer.subarray(0, bytes).toString("utf8") : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    finally {
+        if (descriptor !== undefined) {
+            try {
+                closeSync(descriptor);
+            }
+            catch { }
+        }
+        try {
+            rmSync(directory, { recursive: true, force: true });
+        }
+        catch { /* no effect on the Git outcome */ }
+    }
+}
+/** Porcelain identifies the destination Git actually used, preserving legacy
+ * push refspecs. New/up-to-date refs lack an OID, so confirm that exact remote
+ * ref with a bounded read. Never infer publication from a post-push local HEAD. */
+function observePushResult(hunchDir, env, output, observer) {
+    let destination = "", count = 0;
+    const deadline = Date.now() + 2_000;
+    for (const line of output.split("\n")) {
+        if (line.startsWith("To ")) {
+            destination = line.slice(3);
+            continue;
+        }
+        const status = /^([ *+=])\t[^\t]+:(refs\/[^\t]+)\t(.+)$/.exec(line);
+        if (!status || ++count > 32)
+            continue;
+        const ref = status[2];
+        if (/[\x00-\x20\x7f]/.test(ref))
+            continue;
+        const range = /^(?:[a-f0-9]{40}|[a-f0-9]{64})\.{2,3}([a-f0-9]{40}|[a-f0-9]{64})(?: |$)/.exec(status[3]);
+        if (range) {
+            observeGit(observer, { kind: "published", commitSha: range[1], ref, basis: "push-status" });
+            continue;
+        }
+        if (!destination || /[\x00-\x1f\x7f]/.test(destination) || Date.now() >= deadline)
+            continue;
+        try {
+            const result = execFileSync("git", ["-C", hunchDir, "ls-remote", "--refs", "--exit-code", "--", destination, ref], {
+                env, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: Math.max(1, deadline - Date.now()), maxBuffer: 16_384,
+            }).trim();
+            const rows = result.split("\n").filter(row => row.split("\t")[1] === ref);
+            const commitSha = rows.length === 1 ? rows[0].split("\t")[0] : "";
+            if (/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(commitSha))
+                observeGit(observer, { kind: "published", commitSha, ref, basis: "remote-ref-confirmed" });
+        }
+        catch { /* no exact publication proof; the original push outcome stands */ }
+    }
+}
+function tryPush(hunchDir, env, timeoutMs, contract, observe) {
     if (!contractReady(contract))
         return false;
     const hooksDir = disabledHooksDir(hunchDir);
@@ -1337,11 +1438,17 @@ function tryPush(hunchDir, env, timeoutMs, contract) {
     try {
         if (contract && !setContractUpstream(hunchDir, contract, env))
             return false;
+        const observeArgs = observe ? ["-c", "core.abbrev=no"] : [];
+        const porcelain = observe ? ["--porcelain"] : [];
         const args = contract
-            ? ["-C", hunchDir, "-c", `core.hooksPath=${hooksDir}`, "push", "--receive-pack=git-receive-pack", contract.pushUrl, `HEAD:${contract.ref}`]
-            : ["-C", hunchDir, "-c", `core.hooksPath=${hooksDir}`, "push"];
-        execFileSync("git", args, { stdio: "ignore", env: contract ? boundedTeamEnv(env) : env, timeout: timeoutMs });
-        return contractReady(contract);
+            ? ["-C", hunchDir, "-c", `core.hooksPath=${hooksDir}`, ...observeArgs, "push", ...porcelain, "--receive-pack=git-receive-pack", contract.pushUrl, `HEAD:${contract.ref}`]
+            : ["-C", hunchDir, "-c", `core.hooksPath=${hooksDir}`, ...observeArgs, "push", ...porcelain];
+        const output = runObservedPush(args, contract ? boundedTeamEnv(env) : env, timeoutMs, !!observe);
+        if (!contractReady(contract))
+            return false;
+        if (observe && output !== null)
+            observePushResult(hunchDir, contract ? boundedTeamEnv(env) : env, output, observe);
+        return true;
     }
     catch {
         return false;
@@ -1353,7 +1460,7 @@ function tryPush(hunchDir, env, timeoutMs, contract) {
  *  remote), proves that remote has no refs, snapshots its identity across the
  *  network check, and uses a non-force push so a concurrent first writer wins
  *  safely instead of being overwritten. */
-function establishEmptyRemoteUpstream(hunchDir, env, protectedRepoRoot, timeoutMs, contract) {
+function establishEmptyRemoteUpstream(hunchDir, env, protectedRepoRoot, timeoutMs, contract, observe) {
     if (unsafeOverlayPublication(hunchDir, protectedRepoRoot)
         || !hunchWorktreeClean(hunchDir, env)
         || !contractReady(contract))
@@ -1365,7 +1472,7 @@ function establishEmptyRemoteUpstream(hunchDir, env, protectedRepoRoot, timeoutM
         // Exact URL + exact canonical ref + non-force push. If another teammate wins
         // the first-writer race after the empty proof, Git rejects this safely and the
         // bounded retry path fetches/merges that winner.
-        return tryPush(hunchDir, env, timeoutMs, contract);
+        return tryPush(hunchDir, env, timeoutMs, contract, observe);
     }
     let branch = "";
     let remotes = [];
@@ -1424,11 +1531,9 @@ function establishEmptyRemoteUpstream(hunchDir, env, protectedRepoRoot, timeoutM
         const hooksDir = disabledHooksDir(hunchDir);
         if (!hooksDir)
             return false;
-        execFileSync("git", ["-C", hunchDir, "-c", `core.hooksPath=${hooksDir}`, "push", "--set-upstream", remote, `HEAD:refs/heads/${branch}`], {
-            stdio: "ignore",
-            env,
-            timeout: timeoutMs,
-        });
+        const output = runObservedPush(["-C", hunchDir, "-c", `core.hooksPath=${hooksDir}`, ...(observe ? ["-c", "core.abbrev=no"] : []), "push", ...(observe ? ["--porcelain"] : []), "--set-upstream", remote, `HEAD:refs/heads/${branch}`], env, timeoutMs, !!observe);
+        if (observe && output !== null)
+            observePushResult(hunchDir, env, output, observe);
         return true;
     }
     catch {
@@ -1438,15 +1543,15 @@ function establishEmptyRemoteUpstream(hunchDir, env, protectedRepoRoot, timeoutM
 /** Push once, then retry exactly once only when a bounded pull proves the upstream
  *  advanced during the first push seam. Offline/auth/hook failures with an unchanged
  *  upstream never loop, and every remote mutation re-proves the publication boundary. */
-function pushWithOneRemoteAdvanceRetry(hunchDir, env, protectedRepoRoot, timeoutMs, contract) {
+function pushWithOneRemoteAdvanceRetry(hunchDir, env, protectedRepoRoot, timeoutMs, contract, observe) {
     if (unsafeOverlayPublication(hunchDir, protectedRepoRoot) || !contractReady(contract))
         return false;
     const before = contract
         ? gitSafeWithEnv(["rev-parse", "--verify", TEAM_FETCH_REF], hunchDir, env)
         : upstreamSha(hunchDir, env);
     if (!before)
-        return establishEmptyRemoteUpstream(hunchDir, env, protectedRepoRoot, timeoutMs, contract);
-    if (tryPush(hunchDir, env, timeoutMs, contract))
+        return establishEmptyRemoteUpstream(hunchDir, env, protectedRepoRoot, timeoutMs, contract, observe);
+    if (tryPush(hunchDir, env, timeoutMs, contract, observe))
         return true;
     if (unsafeOverlayPublication(hunchDir, protectedRepoRoot) || !contractReady(contract))
         return false;
@@ -1458,7 +1563,7 @@ function pushWithOneRemoteAdvanceRetry(hunchDir, env, protectedRepoRoot, timeout
         return false;
     if (unsafeOverlayPublication(hunchDir, protectedRepoRoot) || !contractReady(contract))
         return false;
-    return tryPush(hunchDir, env, timeoutMs, contract);
+    return tryPush(hunchDir, env, timeoutMs, contract, observe);
 }
 export function pullHunchStatus(hunchDir, opts = {}) {
     const env = foreignRepoEnv({
@@ -2068,6 +2173,89 @@ export function commitChanges(sha, cwd) {
     }
     return out;
 }
+/** Default cap on how many commits mergeRangeChanges will inspect. A `git
+ *  pull` bringing in an unusually large number of commits (hundreds) would
+ *  otherwise spawn one `diff-tree` per commit with no bound — cheap insurance
+ *  against an unbounded background hook run, not a hard product limit. */
+const DEFAULT_MERGE_RANGE_CAP = 500;
+/** Every commit newly reachable in `oldRef..newRef` (capped to the most
+ *  recent `maxCount`), with the files each one changed (rename-aware, via
+ *  commitChanges). Used to find the commit a squash-merge produced from a
+ *  set of now-orphaned source-branch commits. */
+export function mergeRangeChanges(oldRef, newRef, cwd, maxCount = DEFAULT_MERGE_RANGE_CAP) {
+    const shas = gitSafe(["rev-list", "--abbrev-commit", `--max-count=${maxCount}`, `${oldRef}..${newRef}`], cwd).split("\n").filter(Boolean).reverse();
+    return shas.map((sha) => ({
+        sha,
+        // A deletion is never a sensible repair target — a decision's provenance
+        // should never resolve to the commit that removed the file it's about.
+        files: commitChanges(sha, cwd).filter((c) => c.status !== "deleted").map((c) => c.after ?? c.before).filter((f) => !!f),
+    }));
+}
+/** Batched existence check for many commit shas at once — one `git cat-file
+ *  --batch-check` process instead of one `rev-parse --verify` per sha. Used
+ *  by drift.ts's default commitResolvable so hunch drift/heal/doctor spawn a
+ *  single git process regardless of how many decisions carry a commit, not
+ *  one per decision. Returns the subset of `shas` that resolve to a real
+ *  commit object, or `null` if the check itself failed to run (not a git
+ *  repo, git missing, timeout) — distinct from an empty set, which means
+ *  "checked, and none of them resolve." A caller that collapsed those two
+ *  would flag every commit as unresolvable on a transient environment error
+ *  instead of failing open. */
+export function commitsExist(shas, cwd) {
+    const resolvable = new Set();
+    if (!shas.length)
+        return resolvable;
+    // Same shape guard as commitRepairStatus. Without it, a malformed value
+    // embedding its own newline would count as more input lines than entries
+    // in `shas`, shifting every later sha's output line and misclassifying it.
+    const valid = shas.filter((sha) => /^[0-9a-f]{7,64}$/i.test(sha));
+    if (!valid.length)
+        return resolvable;
+    let raw;
+    try {
+        raw = execFileSync("git", ["-C", cwd, "cat-file", "--batch-check"], {
+            encoding: "utf8",
+            input: valid.map((sha) => `${sha}^{commit}\n`).join(""),
+            stdio: ["pipe", "pipe", "ignore"],
+            timeout: 10_000,
+        });
+    }
+    catch {
+        return null;
+    }
+    const lines = raw.split("\n").filter(Boolean);
+    for (let i = 0; i < valid.length && i < lines.length; i++) {
+        if (!lines[i].endsWith(" missing"))
+            resolvable.add(valid[i]);
+    }
+    return resolvable;
+}
+/** Classifies `commit` relative to `ref` for squash-merge repair eligibility.
+ *  "orphaned" (exists in this repo, but is not an ancestor of `ref`) is the
+ *  ONLY status planCommitRepair should ever act on. "unresolvable" (the
+ *  commit doesn't exist here at all) is explicitly out of repair scope —
+ *  drift.ts's commit-unresolvable kind is what flags that case, because
+ *  there's no reliable signal left to match a replacement against. "unknown"
+ *  (the git command itself failed to run — timeout, git missing) must never
+ *  be treated as repair-eligible; collapsing "false" and "error" into one
+ *  boolean is exactly the bug this type exists to prevent. */
+export function commitRepairStatus(commit, ref, cwd) {
+    if (!/^[0-9a-f]{7,64}$/i.test(commit))
+        return "unresolvable";
+    try {
+        execFileSync("git", ["-C", cwd, "rev-parse", "--verify", "--quiet", `${commit}^{commit}`], { stdio: "ignore", timeout: 5_000 });
+    }
+    catch (e) {
+        return typeof e.status === "number" ? "unresolvable" : "unknown";
+    }
+    try {
+        execFileSync("git", ["-C", cwd, "merge-base", "--is-ancestor", commit, ref], { stdio: "ignore", timeout: 5_000 });
+        return "current";
+    }
+    catch (e) {
+        return e.status === 1 ? "orphaned" : "unknown";
+    }
+}
 /** Machine-generated paths that carry no design "why" — lockfiles, build output,
  *  vendored deps, snapshots, source maps. Excluded from synthesis diffs via git
  *  pathspec BEFORE git assembles/orders the patch: a huge lockfile sorts ahead of

package/dist/extractors/helm.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Deterministic text scan for Helm's `define`/`include`/`template` Go-template
+ * actions — NOT a Go-template parser, and NOT a tree-sitter query. tree-sitter-yaml
+ * has no notion of `{{ }}` content: parsing `{{ include "x" . }}` inside a real
+ * YAML mapping value produces only stray `{` flow-mapping-open tokens, with the
+ * enclosed text lost to ERROR recovery (verified directly against this repo's
+ * tree-sitter-yaml bundle). There is nothing for a tree-sitter query to capture,
+ * so this runs as a sidecar text scan over the raw source — invoked only for
+ * files under a Helm chart (indexer.ts's chart-root detection), never for
+ * arbitrary YAML.
+ *
+ * Known bounded limitation: this is a token scan, not a full parser. A literal
+ * `}}` inside a quoted argument, or an include/define-shaped string inside a
+ * `{{/* comment *}}`, can misattribute a byte range or produce a phantom call.
+ * Both are bounded failure modes (a stray reference to a real symbol name, or a
+ * slightly-long symbol range) — the same class of accepted limitation
+ * `toleratedErrorScopes` documents for the tree-sitter grammars, not a silent gap.
+ * The chart-wide `importedFiles` widening this module's output flows through
+ * (indexer.ts) also lets a YAML alias resolve to an anchor in a sibling chart
+ * file, even though YAML anchors are properly document-scoped; this only fires
+ * when the alias has no matching anchor in its own file (i.e. only on input
+ * that's already invalid YAML on its own terms), so it's bounded, but it's a
+ * real, disclosed side effect of the chart-scoping mechanism, not something to
+ * silently rely on.
+ */
+import { type ParsedSymbol, type ParsedCall } from "./parse.js";
+export interface HelmExtraction {
+    symbols: ParsedSymbol[];
+    calls: ParsedCall[];
+}
+export declare function extractHelmDirectives(source: string): HelmExtraction;

package/dist/extractors/indexer.d.ts

@@ -0,0 +1,55 @@
+import type { HunchStore } from "../store/hunchStore.js";
+import { type Symbol, type Edge, type Component } from "../core/types.js";
+import { type RepoScanSource, type RepoScanSourceIdentity, type RepoSourceIssue } from "./repoSource.js";
+export interface IndexResult {
+    files: number;
+    symbols: number;
+    edges: number;
+    components: number;
+    /** Files that could not be parsed (read error / oversized / extraction error). */
+    skipped: number;
+    coverage: Array<{
+        language: string;
+        eligible: number;
+        parsed: number;
+        skipped: number;
+        reasons: Record<string, number>;
+    }>;
+}
+export interface RepoScan {
+    result: IndexResult;
+    symbols: Symbol[];
+    edges: Edge[];
+    components: Component[];
+    source: RepoScanSourceIdentity & {
+        content_hash: string;
+    };
+    issues: RepoSourceIssue[];
+}
+export interface ScanRepoOptions {
+    churn?: boolean;
+    source?: RepoScanSource;
+}
+export interface IndexRepoOptions {
+    churn?: boolean;
+    /** Explicit immutable source for setup paths that must never persist checkout
+     * bytes. Normal durable refreshes should use requireClean instead. */
+    source?: RepoScanSource;
+    /** Production publication paths set this to prove graph bytes came only from
+     * committed code. Library fixtures and disposable replay checkouts opt in. */
+    requireClean?: boolean;
+    /** Authoritative replay/proof paths cannot represent a partial graph. Reject
+     * every read, path, mode, or parse issue before writing derived JSON. */
+    requireComplete?: boolean;
+}
+/** Read-only policy evaluators must never turn an omitted source file into a
+ * false satisfied receipt. Call this after scanRepo when the consumer cannot
+ * represent partial-graph uncertainty directly. */
+export declare function assertCompleteRepoScan(scan: RepoScan): void;
+/** Derive the current repository graph without writing JSON or rebuilding SQLite.
+ * Read-only gates use this so checking changed code can never rewrite or publish
+ * the durable graph merely by inspecting it. Existing public graph records remain
+ * inputs for the same churn/component enrichment semantics as a persisted index. */
+export declare function scanRepo(store: HunchStore, root: string, opts?: ScanRepoOptions): RepoScan;
+/** Persist one pure scan into the Git-native source of truth. */
+export declare function indexRepo(store: HunchStore, root: string, opts?: IndexRepoOptions): IndexResult;

package/dist/extractors/landscapeDiscovery.d.ts

@@ -0,0 +1,41 @@
+import { type Edge, type Resource } from "../core/types.js";
+export declare const LANDSCAPE_DISCOVERY_SCHEMA_VERSION: "hunch.landscape-discovery/1";
+export declare const LANDSCAPE_CANDIDATE_SCHEMA_VERSION: "hunch.landscape-candidate/1";
+export type LandscapeEvidenceKind = "package_manifest" | "git_remote" | "git_history" | "submodule_declaration" | "mcp_declaration" | "ci_declaration" | "deployment_declaration" | "api_declaration" | "migration_declaration" | "ownership_declaration" | "operations_declaration" | "dashboard_declaration" | "slo_declaration";
+export interface LandscapeCandidateEvidence {
+    kind: LandscapeEvidenceKind;
+    sourcePath: string;
+    sourceField: string;
+    sourceRevision: string;
+    sourceContentHash: string;
+}
+export interface LandscapeCandidate<T extends Resource | Edge> {
+    schema: typeof LANDSCAPE_CANDIDATE_SCHEMA_VERSION;
+    authority: "candidate";
+    record: T;
+    evidence: LandscapeCandidateEvidence[];
+    candidateHash: string;
+}
+export type LandscapeDiscoveryIssueCode = "manifest_missing" | "manifest_invalid" | "manifest_oversized" | "manifest_mode" | "manifest_path" | "manifest_limit" | "workspace_pattern_invalid" | "package_name_missing" | "package_name_invalid" | "package_identity_conflict" | "package_dependency_invalid" | "package_dependency_limit" | "repository_identity_conflict" | "submodule_declaration_invalid" | "submodule_declaration_oversized" | "submodule_declaration_mode" | "submodule_declaration_limit" | "mcp_config_invalid" | "mcp_config_oversized" | "mcp_config_mode" | "mcp_server_name_invalid" | "mcp_declaration_invalid" | "mcp_declaration_conflict" | "mcp_declaration_limit" | "delivery_declaration_invalid" | "delivery_declaration_oversized" | "delivery_declaration_mode" | "delivery_declaration_path" | "delivery_declaration_limit" | "delivery_declaration_conflict" | "api_declaration_invalid" | "api_declaration_oversized" | "api_declaration_mode" | "api_declaration_path" | "api_declaration_limit" | "migration_declaration_invalid" | "migration_declaration_oversized" | "migration_declaration_mode" | "migration_declaration_path" | "migration_declaration_limit" | "ownership_declaration_invalid" | "ownership_declaration_oversized" | "ownership_declaration_mode" | "ownership_declaration_limit" | "operations_declaration_invalid" | "operations_declaration_oversized" | "operations_declaration_mode" | "operations_declaration_path" | "operations_declaration_limit" | "dashboard_declaration_invalid" | "dashboard_declaration_oversized" | "dashboard_declaration_mode" | "dashboard_declaration_path" | "dashboard_declaration_limit" | "slo_declaration_invalid" | "slo_declaration_oversized" | "slo_declaration_mode" | "slo_declaration_path" | "slo_declaration_limit";
+export interface LandscapeDiscoveryIssue {
+    code: LandscapeDiscoveryIssueCode;
+    sourcePath: string;
+    sourceField: string;
+    detail: string;
+}
+export interface LandscapeDiscoveryResult {
+    schema: typeof LANDSCAPE_DISCOVERY_SCHEMA_VERSION;
+    authority: "candidate";
+    sourceRevision: string;
+    repositoryRootIdentity: string;
+    resources: Array<LandscapeCandidate<Resource>>;
+    relationships: Array<LandscapeCandidate<Edge>>;
+    issues: LandscapeDiscoveryIssue[];
+    discoveryHash: string;
+}
+/** Canonical content identity shared by discovery and its review/adoption seam. */
+export declare function landscapeContentHash(value: unknown): string;
+/** Discover an exact, reviewable repository candidate fragment. This function
+ * never writes Hunch graph state: candidate authority remains explicit until a
+ * normal review/capture path accepts the records. */
+export declare function discoverRepositoryLandscape(root: string, ref?: string): LandscapeDiscoveryResult;

package/dist/extractors/languages.d.ts

@@ -0,0 +1,77 @@
+import type { Edge } from "../core/types.js";
+export type ParsedSymbolKind = "function" | "method" | "class" | "interface" | "trait" | "enum" | "type" | "variable" | "file";
+export interface LanguageSpec {
+    /** Stable id, also used as the grammar-bundle cache key by parse.ts. */
+    id: string;
+    extensions: string[];
+    /** Cache key parse.ts's bundleFor() uses (one grammar+query pair may serve
+     *  several extensions, e.g. tsx serves both .tsx and .jsx). */
+    grammarKey: string;
+    /** Lazily returns the tree-sitter Language object for this spec. */
+    loadGrammar(): unknown;
+    /** Tree-sitter query source capturing every construct this language cares about. */
+    query: string;
+    /** Node types ascendToDef() walks up to when resolving a name capture's enclosing def. */
+    defNodeTypes: Set<string>;
+    /** Query capture-name (ending in ".def") -> the ParsedSymbolKind it represents. */
+    defKindOf: Record<string, ParsedSymbolKind>;
+    /** Query capture-name (ending in ".name") -> the matching ".def" capture-name. */
+    nameToDef: Record<string, string>;
+    /** Optional semantic relationship captures. The generic parser/indexer emit
+     * these through the normal graph path; languages only describe syntax. */
+    relationKindOf?: Record<string, {
+        edgeType: Edge["type"];
+        label: string;
+    }>;
+    /** Common builtin/stdlib method names. Member calls to these (e.g. `arr.map(...)`)
+     *  must NOT create call edges to unrelated repo symbols that happen to share the
+     *  name (DESIGN: keep the graph clean). */
+    builtinMethods: Set<string>;
+    /** Direct-call builtins for languages such as PHP. These never become repo
+     * call edges merely because a project symbol shares the runtime name. */
+    builtinFunctions?: Set<string>;
+    /** Edge type emitted for this language's calls-list entries (e.g. YAML's
+     *  alias->anchor references aren't function calls). Defaults to "calls"
+     *  when omitted — every language before YAML. */
+    referenceEdgeType?: Edge["type"];
+    /** Fallback name for a ".def" capture with no paired ".name" capture (e.g.
+     *  a whole-file root symbol with no natural identifier of its own). Omit
+     *  for a language where every ".def" always has a name capture — parse.ts
+     *  then keeps dropping unnamed defs, the current behavior for TS/Python. */
+    fallbackDefName?: (file: string) => string;
+    /** Ancestor shapes in which an ERROR node is a known limitation of THIS grammar
+     *  rather than a real syntax error. parse.ts forgives an error only when some
+     *  ancestor has type `node` AND that ancestor's own parent has type `parentIs` —
+     *  the pair is what keeps the tolerance narrow. Omit for a language with no known
+     *  grammar false positives; that spec then stays strictly fail-closed. */
+    toleratedErrorScopes?: ReadonlyArray<{
+        readonly node: string;
+        readonly parentIs: string;
+    }>;
+    /** Patterns whose presence anywhere in the source mean "this isn't actually
+     *  {id} text yet — it's a template that renders to {id} later" (Go/Jinja/Helm
+     *  delimiters in a .yaml file, e.g.). parse.ts still runs the real parse — a
+     *  genuine anchor/symbol elsewhere in the file is still extracted, same as any
+     *  other {id} file — but no longer lets the resulting ERROR nodes fail-close
+     *  the whole-repo scan completeness gate the way toleratedErrorScopes protects
+     *  narrower, per-grammar false positives (issue #33). Keep these narrow: a
+     *  pattern that also matches ordinary, always-valid {id} syntax (e.g. GitHub
+     *  Actions' `${{ }}` expressions) would silently disable the fail-closed
+     *  guarantee for files that were never templated at all. */
+    templatingMarkers?: readonly RegExp[];
+    /** Extensions within this language where EVERY file is inherently a template
+     *  regardless of content — unlike templatingMarkers, this never content-sniffs.
+     *  The extension alone means "this file is a template, parseable must never
+     *  become false for it," matching Helm's `_helpers.tpl` convention where the
+     *  file may be pure Go-template text with no YAML structure of its own at all. */
+    alwaysTemplatedExtensions?: readonly string[];
+}
+export declare const LANGUAGES: LanguageSpec[];
+export declare const CODE_EXTENSIONS: string[];
+export declare function languageFor(file: string): LanguageSpec | null;
+/** Prose formats worth drafting a decision from even though no LanguageSpec parses
+ *  them — no grammar, no symbols/edges, just eligible input to synthesis (issue #12). */
+export declare const PROSE_EXTENSIONS: string[];
+/** Broader than languageFor: "is this worth reasoning about" (synthesis input)
+ *  rather than "can tree-sitter parse this" (symbol/dependency extraction). */
+export declare function isSubstantive(file: string): boolean;

package/dist/extractors/nativeTreeSitter.d.ts

@@ -0,0 +1,16 @@
+import type TreeSitterParser from "tree-sitter";
+export interface NativeTreeSitterRuntime {
+    Parser: typeof TreeSitterParser;
+    typescript: unknown;
+    tsx: unknown;
+    python: unknown;
+    go: unknown;
+    php: unknown;
+    yaml: unknown;
+}
+/** Load all native tree-sitter addons (the parser runtime + every grammar) from
+ * process-owned temp copies. Windows keeps loaded `.node` files locked for the
+ * process lifetime; redirecting the upstream loaders means npm can replace the
+ * installed package during an active MCP session without killing that session
+ * or falling back to a stale binary. */
+export declare function loadNativeTreeSitter(): NativeTreeSitterRuntime;

package/dist/extractors/parse.d.ts

@@ -0,0 +1,54 @@
+import type { Edge } from "../core/types.js";
+import { type ParsedSymbolKind } from "./languages.js";
+export type { ParsedSymbolKind } from "./languages.js";
+export interface ParsedSymbol {
+    name: string;
+    kind: ParsedSymbolKind;
+    startByte: number;
+    endByte: number;
+    loc: number;
+    bodyText: string;
+}
+export interface ParsedCall {
+    callee: string;
+    atByte: number;
+    endByte: number;
+    /** true for `x.foo()` (property access), false for a direct `foo()` call. */
+    member: boolean;
+}
+export interface ParsedRelation {
+    target: string;
+    atByte: number;
+    endByte: number;
+    edgeType: Edge["type"];
+    label: string;
+}
+export interface ParsedFile {
+    symbols: ParsedSymbol[];
+    imports: string[];
+    calls: ParsedCall[];
+    relations: ParsedRelation[];
+    namespace: string | null;
+    parseable: boolean;
+}
+/** Cap on a stored symbol's bodyText — large enough for review context, small
+ *  enough that a huge function/file doesn't bloat every JSON symbol record. */
+export declare const MAX_BODY_TEXT_CHARS = 4000;
+export declare function parseSource(file: string, source: string): ParsedFile | null;
+/** Map each call site to the innermost symbol whose byte-range contains it.
+ *  Keyed by the symbol's position (index) in `parsed.symbols` — NOT its
+ *  startByte, which is not a reliable per-symbol identity: a language whose
+ *  extractor merges a synthetic whole-file symbol with independently-derived
+ *  symbols (e.g. YAML's fallback-root synthetic symbol alongside Helm's
+ *  regex-derived `define` blocks) can produce two distinct symbols that both
+ *  start at byte 0. Indexing by array position is unique by construction,
+ *  regardless of byte overlap — the caller must consume the exact same
+ *  `parsed.symbols` array (or an equivalently-ordered copy) to look up a
+ *  symbol by the index this function returns. The value maps callee name ->
+ *  `memberOnly` (true iff every occurrence was a `x.foo()` member call, never
+ *  a direct `foo()`), so the indexer can resolve member calls conservatively. */
+export declare function attributeCalls(parsed: ParsedFile): Map<number, Map<string, boolean>>;
+/** Map static semantic relationships (extends/implements/trait use) to the
+ * innermost enclosing declaration using the same stable symbol-index identity
+ * as call attribution. */
+export declare function attributeRelations(parsed: ParsedFile): Map<number, ParsedRelation[]>;

package/dist/extractors/php.d.ts

@@ -0,0 +1,26 @@
+export interface PhpPsr4Mapping {
+    prefix: string;
+    directories: string[];
+}
+export interface PhpUseImport {
+    fqn: string;
+    alias: string;
+}
+/** Extract bounded, repository-relative PSR-4 mappings from composer.json.
+ * autoload-dev is included because test symbols and changed-file history are
+ * first-class graph inputs. Unsafe/absolute mapping roots are ignored. */
+export declare function composerPsr4Mappings(value: unknown): PhpPsr4Mapping[];
+/** Parse ordinary, aliased, comma-separated, function/const, and grouped PHP
+ * namespace-use declarations. Dynamic namespace expressions do not exist in
+ * this syntax, so every returned import is exact. */
+export declare function parsePhpUseDeclaration(raw: string): PhpUseImport[];
+export interface PhpResolvedReference {
+    symbolName: string;
+    files: string[];
+}
+export declare function resolvePhpReference(reference: string, namespace: string | null, useDeclarations: readonly string[], mappings: readonly PhpPsr4Mapping[], files: ReadonlySet<string>): PhpResolvedReference;
+/** Resolve one parser import capture. A namespace-use declaration can map to
+ * multiple local files; object/static class references map through aliases and
+ * current namespace; static include/require paths stay fail-closed. */
+export declare function resolvePhpImportTargets(fromFile: string, capture: string, namespace: string | null, useDeclarations: readonly string[], mappings: readonly PhpPsr4Mapping[], files: ReadonlySet<string>): string[];
+export declare function phpExternalSpecifier(capture: string): string | null;