agent-doc-system 0.0.0-stage → 1.1.0

package/INSTALL_FOR_AGENTS.md

@@ -0,0 +1,60 @@
+# Install AgentDoc — instructions for an AI coding agent
+
+This document has exactly one job: get the `agentdoc` CLI installed and verified
+on the current machine. It is **not** a project workflow. Do not look for a
+project root, do not run `init`, `audit`, `scaffold`, or `check`, do not create
+`.agentdoc/` or `agentdoc/`, and do not modify any software project. The task
+ends when the CLI is installed and verified.
+
+## 1. Inspect the environment
+
+```bash
+uname -a            # OS and architecture
+echo "$SHELL"       # current shell
+node --version      # is Node present, and which major
+npm --version       # is npm present
+command -v git      # is git present (needed to install from GitHub)
+```
+
+## 2. Ensure a supported Node
+
+AgentDoc requires **Node 22 or newer** (22, 24 and 26 are the tested
+baselines). If `node` is missing or older than 22, install or switch to a
+supported release using whatever the machine already has — `nvm`, `fnm`,
+`mise`, `brew`, or the package manager — then re-check `node --version`.
+
+If no Node toolchain exists and none can be installed without a human (for
+example a managed machine), stop and report that prerequisite.
+
+## 3. Install or upgrade the CLI
+
+Canonical install, from the AgentDoc GitHub repository:
+
+```bash
+npm install -g github:lbframe/agent-doc-system
+```
+
+The command is idempotent: run it again to upgrade to the latest `main`.
+If a specific ref is required, append it: `github:lbframe/agent-doc-system#<ref>`.
+
+The package has zero runtime dependencies. If `npm install -g` fails on
+permissions, do **not** use `sudo`; fix the npm global prefix instead
+(`npm config set prefix ~/.npm-global` and add `~/.npm-global/bin` to `PATH`),
+or report the blocker.
+
+## 4. Verify the binary resolves
+
+```bash
+command -v agentdoc     # must print a path
+agentdoc --version      # must print a version
+agentdoc doctor         # machine self-check; must exit 0
+```
+
+`agentdoc doctor` reports the Node version, the schema bundle and the compiler
+version, and fails if the installation itself is unhealthy. It never requires a
+project — run it from anywhere.
+
+## 5. Report and stop
+
+Report the installed version and that `doctor` passed. The installation task is
+complete. Do not proceed into any repository, catalog, or migration work.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lbframe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# AgentDoc
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+![AgentDoc — Give coding agents the context they actually need](docs/assets/readme/agentdoc-hero.webp)
+
+**Give coding agents the context they actually need.**
+
+AgentDoc turns your codebase, docs, contracts, and runtime evidence into a context layer your coding agent can query before it changes anything.
+
+[![npm](https://img.shields.io/npm/v/agent-doc-system.svg)](https://www.npmjs.com/package/agent-doc-system) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![node](https://img.shields.io/badge/node-22%20%7C%2024%20%7C%2026-43853d.svg)](https://nodejs.org/)
+
+## Give this to your coding agent
+
+Paste this into your agent **from the repository you want to use AgentDoc on**:
+
+```text
+Set up AgentDoc for this repository and use it as the context layer for your work.
+
+AgentDoc: https://github.com/lbframe/agent-doc-system
+
+1. Read INSTALL_FOR_AGENTS.md and install or upgrade the AgentDoc CLI.
+2. Read skills/agent-doc-system/SKILL.md.
+3. Run agentdoc doctor --project and agentdoc audit.
+4. Use the appropriate CREATE or MIGRATE workflow for this repository.
+5. Do not invent ownership, architecture, authority rules, or product intent. Ask me only for decisions AgentDoc cannot safely derive.
+6. Finish setup with agentdoc validate, agentdoc compile, and agentdoc check.
+7. From now on, use agentdoc query and agentdoc impact before changes, then agentdoc check after changes.
+8. Report anything unresolved or conflicting instead of guessing.
+```
+
+That is the intended onboarding path: **give the prompt to the agent, let AgentDoc build the context layer, and keep using it during development.**
+
+## Why AgentDoc?
+
+Coding agents can read code. The hard part is knowing **what matters for this change**.
+
+Important context is scattered across code, documentation, API contracts, architectural decisions, CI rules, and production reality. Agents either load too much or miss something important.
+
+AgentDoc gives them a map.
+
+- **Query the right context** for a file or component.
+- **See the blast radius** before changing code.
+- **Detect drift** between code and documentation.
+- **Surface conflicts** instead of silently guessing.
+- **Verify constraints in CI** before stale knowledge becomes trusted context.
+
+![AgentDoc in action — query, impact, check](docs/assets/readme/agentdoc-in-action.webp)
+
+## Three commands, one workflow
+
+```bash
+agentdoc query src/payments/webhook.ts
+agentdoc impact src/payments/webhook.ts
+agentdoc check
+```
+
+`query` tells the agent what it needs to know. `impact` shows what the change can affect. `check` verifies that the repository still agrees with itself.
+
+## Why not just AGENTS.md or RAG?
+
+![Why AgentDoc](docs/assets/readme/why-agentdoc.webp)
+
+AgentDoc is not another documentation file and it is not just semantic search.
+
+It combines **authored intent**, **facts derived from code**, and **runtime observations** without pretending they are the same thing. When sources disagree, AgentDoc surfaces the conflict instead of choosing a convenient answer.
+
+## From repository knowledge to agent-ready context
+
+AgentDoc turns scattered repository knowledge into task-specific context your coding agent can query, verify, and act on.
+
+![How AgentDoc works](docs/assets/readme/how-agentdoc-works.webp)
+
+## Install manually
+
+Requires Node.js 22+.
+
+```bash
+npm install -g agent-doc-system
+agentdoc doctor
+```
+
+Then, inside a repository:
+
+```bash
+agentdoc audit
+```
+
+AgentDoc also ships with an Agent Skill at [`skills/agent-doc-system/`](skills/agent-doc-system/SKILL.md).
+
+## Documentation
+
+- [Getting started & migration](docs/MIGRATION.md)
+- [Authority & conflicts](docs/AUTHORITY.md)
+- [CI & verification](docs/CI.md)
+- [Specification](docs/SPEC.md)
+- [Agent Skill](skills/agent-doc-system/SKILL.md)
+
+## License
+
+[MIT](LICENSE) © 2026 lbframe

package/adapters/ansible.mjs

@@ -0,0 +1,306 @@
+// Ansible adapter: what host provisioning actually installs.
+//
+// Reads the playbooks under a unit root without running anything and without
+// evaluating a single Jinja expression. From every task reachable from a
+// playbook (plays, roles, includes, blocks) it records the host paths the
+// task creates and the services it manages. That inventory is the DERIVED side
+// of a normative requirement whose `satisfiedBy` names this adapter and whose
+// `expects` names a path or a service:
+//
+//   provided   a reachable, unconditional task installs it          deterministic
+//   absent     no reachable task does, and every task is transparent  deterministic
+//
+// Anything weaker is a candidate, which the authority engine never elects: a
+// matching task behind a `when`, or an absence claimed over a tree that holds
+// an opaque task (a shell command, a package install, a templated path, a role
+// that is not in the repository). An absence is only a fact when the adapter
+// could have seen the opposite.
+import { Adapter } from "./registry.mjs";
+import { parseYamlDocuments } from "../core/yaml.mjs";
+import { AgentDocError } from "../core/codes.mjs";
+
+// Modules that create the path they name, and the arguments naming it.
+const PATH_MODULES = {
+  copy: ["dest"],
+  template: ["dest"],
+  unarchive: ["dest", "creates"],
+  get_url: ["dest"],
+  git: ["dest"],
+  synchronize: ["dest"],
+  pip: ["virtualenv"],
+};
+// `file` creates only for these states; `lineinfile`/`blockinfile` only with
+// `create: true`.
+const FILE_CREATING_STATES = new Set(["directory", "touch", "link", "hard"]);
+const SERVICE_MODULES = new Set(["systemd", "systemd_service", "service"]);
+// Commands can do anything; their `creates` is the one thing they promise.
+const COMMAND_MODULES = new Set(["command", "shell", "script", "raw"]);
+// Modules that change no file the adapter would be asked about.
+const INERT_MODULES = new Set([
+  "debug", "set_fact", "assert", "fail", "meta", "pause", "wait_for", "stat", "ping", "setup",
+  "include_vars", "group_by", "add_host", "user", "group", "uri", "slurp", "fetch", "set_stats",
+]);
+// Task keywords, i.e. everything on a task that is not its module.
+const TASK_KEYWORDS = new Set([
+  "name", "when", "loop", "with_items", "with_dict", "with_fileglob", "loop_control", "register", "notify",
+  "become", "become_user", "become_method", "tags", "vars", "environment", "args", "ignore_errors", "changed_when",
+  "failed_when", "until", "retries", "delay", "no_log", "delegate_to", "run_once", "check_mode", "diff",
+  "listen", "timeout", "throttle", "any_errors_fatal", "module_defaults", "collections", "connection",
+]);
+const INCLUDES = new Set(["include_tasks", "import_tasks", "include"]);
+const ROLE_INCLUDES = new Set(["include_role", "import_role"]);
+
+export class AnsibleAdapter extends Adapter {
+  static adapterName = "ansible";
+  constructor() {
+    super({ name: "ansible", version: "1.0.0", kind: "source" });
+  }
+
+  // A unit that holds a playbook is a deployable infrastructure unit.
+  detect(ctx, root) {
+    const pb = playbooks(ctx.repo, root);
+    return pb.length ? { path: pb[0].path, shape: "deployable" } : null;
+  }
+
+  extract(ctx, unit) {
+    const inv = inventory(ctx.repo, unit.root);
+    if (!inv.files.length) return {};
+    for (const r of ctx.requirements || []) {
+      if (r.subject !== ctx.compRef || !r.satisfiedBy.includes("ansible") || !r.expects) continue;
+      const verdict = judge(inv, r.expects);
+      const files = verdict.files.length ? verdict.files : inv.files;
+      ctx.addFact(r.subject, r.key, verdict.value, {
+        evidenceClass: "DERIVED",
+        confidence: verdict.certain ? "deterministic" : "candidate",
+        provRecs: files.map((f) => ctx.prov.add("observed", f, "ansible-extractor", ["ass:pending"])),
+        semantics: "ansible: " + verdict.why,
+      });
+    }
+    return {
+      provisioning: {
+        installs: inv.installs.map((i) => ({ path: i.path, file: i.file, task: i.task, conditional: i.conditional })),
+        services: inv.services.map((s) => ({ name: s.name, file: s.file, task: s.task, conditional: s.conditional })),
+        opaque: inv.opaque,
+      },
+    };
+  }
+}
+
+function judge(inv, expects) {
+  const target = expects.installs || expects.service;
+  const what = expects.installs ? "path " + target : "service " + target;
+  const hits = expects.installs
+    ? inv.installs.filter((i) => i.path === target || i.path.startsWith(target + "/"))
+    : inv.services.filter((s) => s.name === target || s.name === target + ".service");
+  const sure = hits.filter((h) => !h.conditional);
+  if (sure.length) {
+    return { value: "provided", certain: true, files: uniq(sure.map((h) => h.file)), why: what + " installed by " + describe(sure[0]) };
+  }
+  if (hits.length) {
+    return { value: "provided", certain: false, files: uniq(hits.map((h) => h.file)), why: what + " installed only conditionally by " + describe(hits[0]) };
+  }
+  if (inv.opaque.length) {
+    return {
+      value: "absent", certain: false, files: [],
+      why: "no task installs " + what + ", but absence cannot be proven: " + inv.opaque.slice(0, 3).join("; ") +
+        (inv.opaque.length > 3 ? " (+" + (inv.opaque.length - 3) + " more)" : ""),
+    };
+  }
+  return { value: "absent", certain: true, files: [], why: "no reachable task installs " + what };
+}
+
+function describe(h) {
+  return h.file + (h.task ? " (" + h.task + ")" : "");
+}
+
+function uniq(a) {
+  return [...new Set(a)].sort();
+}
+
+function parse(repo, file) {
+  try {
+    return parseYamlDocuments(repo.readText(file), file, { allowSequenceRoot: true }).map((d) => d.doc);
+  } catch (e) {
+    if (e instanceof AgentDocError) return null;
+    throw e;
+  }
+}
+
+function isYaml(f) {
+  return /\.ya?ml$/.test(f);
+}
+
+function playbooks(repo, root) {
+  const out = [];
+  for (const f of repo.walk(root)) {
+    if (!isYaml(f) || /(^|\/)(tasks|handlers|vars|defaults|meta|group_vars|host_vars|templates|files)\//.test(f.slice(root.length))) continue;
+    const docs = parse(repo, f);
+    if (!docs) continue;
+    const plays = docs.flatMap((d) => (Array.isArray(d) ? d : []));
+    if (plays.length && plays.every((p) => p && typeof p === "object" && (p.hosts !== undefined || p.import_playbook !== undefined))) {
+      out.push({ path: f, plays });
+    }
+  }
+  return out.sort((a, b) => (a.path < b.path ? -1 : 1));
+}
+
+// Every task reachable from a playbook under `root`, walked in a fixed order.
+function inventory(repo, root) {
+  const inv = { files: new Set(), installs: [], services: [], opaque: [] };
+  const seen = new Set();
+  const opaque = (file, task, why) => inv.opaque.push(file + (task ? " (" + task + ")" : "") + ": " + why);
+
+  const dirOf = (p) => p.split("/").slice(0, -1).join("/");
+  const join = (dir, rel) => {
+    const parts = (dir ? dir.split("/") : []).concat(rel.split("/"));
+    const out = [];
+    for (const s of parts) {
+      if (s === "" || s === ".") continue;
+      if (s === "..") { if (!out.length) return null; out.pop(); } else out.push(s);
+    }
+    return out.join("/");
+  };
+  const templated = (v) => typeof v === "string" && /\{\{|\{%/.test(v);
+
+  const findRole = (name, fromDir) => {
+    for (const base of [fromDir, root]) {
+      for (const ext of ["yml", "yaml"]) {
+        const p = join(base, "roles/" + name + "/tasks/main." + ext);
+        if (p && repo.exists(p)) return p;
+      }
+    }
+    return null;
+  };
+
+  const walkFile = (file, conditional, kind) => {
+    const key = file + "|" + conditional + "|" + kind;
+    if (seen.has(key)) return;
+    seen.add(key);
+    inv.files.add(file);
+    const docs = parse(repo, file);
+    if (!docs) { opaque(file, null, "not parseable as YAML"); return; }
+    const list = docs.flatMap((d) => (Array.isArray(d) ? d : []));
+    if (kind === "playbook") for (const p of list) walkPlay(file, p, conditional);
+    else walkTasks(file, list, conditional);
+  };
+
+  const walkPlay = (file, play, conditional) => {
+    if (!play || typeof play !== "object") return;
+    if (play.import_playbook !== undefined) {
+      const ref = String(play.import_playbook);
+      const p = !templated(ref) && join(dirOf(file), ref);
+      if (p && repo.exists(p)) walkFile(p, conditional || play.when !== undefined, "playbook");
+      else opaque(file, null, "imported playbook not resolvable in the repository: " + ref);
+      return;
+    }
+    const cond = conditional || play.when !== undefined;
+    for (const section of ["pre_tasks", "roles", "tasks", "post_tasks", "handlers"]) {
+      const items = play[section];
+      if (!Array.isArray(items)) continue;
+      if (section === "roles") {
+        for (const r of items) {
+          const name = typeof r === "string" ? r : r && (r.role || r.name);
+          walkRole(file, String(name), cond || (r && typeof r === "object" && r.when !== undefined));
+        }
+      } else {
+        walkTasks(file, items, cond);
+      }
+    }
+  };
+
+  const walkRole = (file, name, conditional) => {
+    const main = !templated(name) && findRole(name, dirOf(file));
+    if (main) walkFile(main, conditional, "tasks");
+    else opaque(file, null, "role not found in the repository: " + name);
+  };
+
+  const walkTasks = (file, tasks, conditional) => {
+    for (const t of tasks) {
+      if (!t || typeof t !== "object" || Array.isArray(t)) continue;
+      const cond = conditional || t.when !== undefined;
+      const label = typeof t.name === "string" ? t.name : null;
+      if (Array.isArray(t.block)) {
+        walkTasks(file, t.block, cond);
+        // A rescue runs only when the block failed: never an unconditional install.
+        for (const k of ["rescue", "always"]) if (Array.isArray(t[k])) walkTasks(file, t[k], cond || k === "rescue");
+        continue;
+      }
+      const modKey = Object.keys(t).find((k) => !TASK_KEYWORDS.has(k));
+      if (!modKey) continue;
+      const mod = modKey.split(".").pop();
+      const raw = t[modKey];
+      const args = { ...parseFreeForm(raw), ...(t.args && typeof t.args === "object" ? t.args : {}) };
+      // A loop runs the module once per item with a templated argument; the
+      // adapter does not expand it.
+      const looped = t.loop !== undefined || Object.keys(t).some((k) => k.startsWith("with_"));
+
+      if (INCLUDES.has(mod)) {
+        const ref = typeof raw === "string" ? raw.split(/\s+/)[0] : args.file;
+        const p = ref && !templated(ref) && join(dirOf(file), String(ref));
+        if (p && repo.exists(p)) walkFile(p, cond, "tasks");
+        else opaque(file, label, "included task file not resolvable in the repository: " + ref);
+        continue;
+      }
+      if (ROLE_INCLUDES.has(mod)) {
+        walkRole(file, String(args.name), cond);
+        continue;
+      }
+      const record = (list, entry) => list.push({ ...entry, file, task: label, conditional: cond });
+      if (PATH_MODULES[mod] || mod === "file" || mod === "lineinfile" || mod === "blockinfile") {
+        let names = PATH_MODULES[mod] || ["path", "dest", "name"];
+        if (mod === "file" && !FILE_CREATING_STATES.has(String(args.state || "file"))) names = [];
+        if ((mod === "lineinfile" || mod === "blockinfile") && !isTrue(args.create)) names = [];
+        for (const n of names) {
+          const v = args[n];
+          if (v === undefined) continue;
+          if (templated(v) || looped) { opaque(file, label, mod + " " + n + " is templated: " + v); continue; }
+          record(inv.installs, { path: normalisePath(String(v)) });
+        }
+        continue;
+      }
+      if (SERVICE_MODULES.has(mod)) {
+        const n = args.name;
+        if (n === undefined) continue;
+        if (templated(n) || looped) opaque(file, label, mod + " name is templated: " + n);
+        else record(inv.services, { name: String(n) });
+        continue;
+      }
+      if (COMMAND_MODULES.has(mod)) {
+        if (args.creates !== undefined && !templated(args.creates) && !looped) {
+          record(inv.installs, { path: normalisePath(String(args.creates)) });
+        } else {
+          opaque(file, label, mod + " task without a literal `creates`");
+        }
+        continue;
+      }
+      if (INERT_MODULES.has(mod)) continue;
+      opaque(file, label, "module " + modKey + " is not modeled and may change the host");
+    }
+  };
+
+  for (const pb of playbooks(repo, root)) walkFile(pb.path, false, "playbook");
+  const byPath = (a, b) => (a.path + a.file < b.path + b.file ? -1 : a.path + a.file > b.path + b.file ? 1 : 0);
+  return {
+    files: [...inv.files].sort(),
+    installs: inv.installs.sort(byPath),
+    services: inv.services.sort((a, b) => (a.name + a.file < b.name + b.file ? -1 : 1)),
+    opaque: [...new Set(inv.opaque)].sort(),
+  };
+}
+
+// `file: path=/a state=directory` — the key=value shorthand.
+function parseFreeForm(raw) {
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) return raw;
+  if (typeof raw !== "string") return {};
+  const out = {};
+  for (const m of raw.matchAll(/(\w+)=("[^"]*"|'[^']*'|\S+)/g)) out[m[1]] = m[2].replace(/^["']|["']$/g, "");
+  return out;
+}
+
+function isTrue(v) {
+  return v === true || /^(yes|true)$/i.test(String(v));
+}
+
+function normalisePath(p) {
+  return p.length > 1 ? p.replace(/\/+$/, "") : p;
+}

package/adapters/cache.mjs

@@ -0,0 +1,27 @@
+// Cache adapter: Redis / in-memory cache client evidence as a derived binding.
+import { Adapter } from "./registry.mjs";
+
+const CACHE_HINT = /(@upstash\/redis|ioredis|redis|go-redis|redis\.go|valkey|memcache|@memcached)/i;
+
+export class CacheAdapter extends Adapter {
+  static adapterName = "cache";
+  constructor() {
+    super({ name: "cache", version: "1.0.0", kind: "source" });
+  }
+  extract(ctx, unit) {
+    const { repo, prov, compRef } = ctx;
+    const evFile = unit.goModule ? unit.root + "/go.mod" : unit.root + "/package.json";
+    if (!repo.exists(evFile)) return {};
+    const text = repo.readText(evFile);
+    if (!CACHE_HINT.test(text)) return {};
+    const pr = prov.add("observed", evFile, "binding-extractor", ["der:" + compRef + ":/bindings"]);
+    const resources = ctx.sources.entities.filter((e) => e.kind === "Resource" && e.doc.spec.type === "cache");
+    if (resources.length === 1) {
+      const client = ctx.clientKeyForResourceType("cache");
+      const attrs = client ? { via: "cache-client", client } : { via: "cache-client" };
+      ctx.addEdge("usesResource", compRef, resources[0].ref, attrs, [pr], "DERIVED");
+      return { bindings: [{ kind: "cache", logicalResourceRef: resources[0].ref, resolution: "resolved", provenanceIds: null, _provs: new Set([pr]) }] };
+    }
+    return { bindings: [{ kind: "cache", resolution: "resolved", provenanceIds: null, _provs: new Set([pr]) }] };
+  }
+}

package/adapters/contract-consumers.mjs

@@ -0,0 +1,56 @@
+// Shared contract-consumer resolution.
+//
+// A cross-component boundary is a contract plus its consumers. Consumers are
+// discovered deterministically: a unit that references the canonical contract
+// file from a source or build-configuration file, other than the provider's own
+// unit, consumes that contract. Documentation mentions are excluded so a doc
+// that quotes a contract path cannot manufacture a dependency edge.
+import path from "node:path";
+
+const CODE_EXT = /\.(ts|tsx|js|jsx|mts|cts|mjs|cjs|go|py|rb|java|kt|rs|ex|exs|cs|php|swift|gradle|proto|graphql|sql)$/;
+const CONFIG_NAMES = new Set([
+  "package.json", "go.mod", "buf.gen.yaml", "buf.yaml", "buf.work.yaml",
+  "codegen.yaml", "codegen.yml", "openapi-ts.config.ts", "openapi-ts.config.js",
+  "oapi-codegen.yaml", "oapi-codegen.yml", "turbo.json", "Makefile", "justfile",
+  "Taskfile.yml", "build.gradle", "build.gradle.kts", "pom.xml",
+]);
+const DOC_EXT = /\.(md|mdx|txt|adoc|rst)$/;
+
+export function contractReferenceSites(repo, unit) {
+  const out = new Map(); // file -> true
+  for (const f of repo.walk(unit.root)) {
+    const base = path.posix.basename(f);
+    if (DOC_EXT.test(f)) continue;
+    if (f.includes("/docs/") || f.startsWith("docs/")) continue;
+    if (!CODE_EXT.test(f) && !CONFIG_NAMES.has(base)) continue;
+    out.set(f, true);
+  }
+  return out;
+}
+
+// Resolve consumers for a contract file. Returns Map<componentRef, string[]>.
+// The per-unit file inventory is built once and cached on the context, so a
+// repository with many contracts does not re-walk every unit per contract.
+export function resolveContractConsumers(ctx, contractRef, providerRef) {
+  if (!ctx.referenceIndex) {
+    const perUnit = new Map();
+    for (const unit of ctx.discovery.eligible) {
+      if (!unit.component) continue;
+      perUnit.set(unit.component.ref, [...contractReferenceSites(ctx.repo, unit).keys()].sort());
+    }
+    ctx.referenceIndex = perUnit;
+  }
+  const out = new Map();
+  for (const [ref, files] of ctx.referenceIndex) {
+    if (ref === providerRef) continue;
+    const hits = files.filter((f) => ctx.repo.readText(f).includes(contractRef));
+    if (hits.length) out.set(ref, hits);
+  }
+  return out;
+}
+
+// A unit that names the contract in its own build config is a stronger signal
+// than a stray mention in source.
+export function isBuildConfig(file) {
+  return CONFIG_NAMES.has(path.posix.basename(file));
+}