agent-doc-system 0.0.0-stage → 1.1.0

package/adapters/database.mjs

@@ -0,0 +1,116 @@
+// Database adapter: migration and schema evidence.
+//
+// Two distinct outcomes, deliberately kept apart:
+//   - an authored logical-database Resource that matches → a resolved binding
+//     and a uses-resource relation;
+//   - no match → a *candidate* fact plus a warning. Migration authority alone
+//     does not establish database ownership, so the system refuses to invent
+//     the edge. This mirrors a real review in the reference project where a
+//     library shipped migrations but explicitly did not own a database.
+import { Adapter } from "./registry.mjs";
+import { firstExistingFile, findMigrationDirs } from "../core/sourcescan.mjs";
+
+const ORM_CONFIG = [
+  "drizzle.config.ts", "drizzle.config.js", "drizzle.config.mjs",
+  "prisma/schema.prisma", "schema.prisma",
+  "knexfile.js", "knexfile.ts", "sequelize.config.js", "ormconfig.json",
+];
+
+export class DatabaseAdapter extends Adapter {
+  static adapterName = "database";
+  constructor() {
+    super({ name: "database", version: "1.0.0", kind: "source" });
+  }
+  extract(ctx, unit) {
+    const { repo, prov, compRef } = ctx;
+    const root = unit.root;
+    const migrationDirs = findMigrationDirs(repo, root);
+    const ormConfig = firstExistingFile(repo, root, ORM_CONFIG);
+    if (!migrationDirs.length && !ormConfig) return {};
+
+    let evidencePath = ormConfig;
+    if (migrationDirs.length) {
+      evidencePath = repo.walk(migrationDirs[0])[0] || migrationDirs[0];
+    }
+    const pr = prov.add("observed", evidencePath, "migration-extractor", ["der:" + compRef + ":/bindings"]);
+
+    // A component that both migrates and opens a connection owns the database.
+    const opensConnection = hasConnectionEvidence(ctx, unit);
+    if (!opensConnection) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        code: "AGENTDOC_RESOURCE_CANDIDATE",
+        subject: compRef,
+        refs: [compRef],
+        message:
+          "migration or schema authority under '" + root + "' has no matching authored logical-database Resource, " +
+          "and no connection-pool evidence: migration authority alone does not establish database ownership",
+        paths: [evidencePath],
+      });
+      ctx.addFact(compRef, "resource.ownership", null, {
+        evidenceClass: "DERIVED", confidence: "candidate", provRecs: [pr],
+        semantics: "a schema exists here, but which component owns the logical database is unresolved",
+      });
+      return { migrationAuthority: evidencePath };
+    }
+
+    const name = compRef.split("/")[1];
+    const target = ctx.sources.byKindName.get("Resource/" + name + "-postgres")
+      || ctx.sources.byKindName.get("Resource/" + name + "-database")
+      || ctx.sources.byKindName.get("Resource/" + name + "-db")
+      || findDatabaseResource(ctx, name);
+    if (!target) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        code: "AGENTDOC_RESOURCE_CANDIDATE",
+        subject: compRef,
+        refs: [compRef],
+        message:
+          "component '" + name + "' has migration and connection authority but no authored logical-database Resource; " +
+          "declare one or record why the database is owned elsewhere",
+        paths: [evidencePath],
+      });
+      ctx.addFact(compRef, "resource.ownership", null, {
+        evidenceClass: "DERIVED", confidence: "candidate", provRecs: [pr],
+        semantics: "this component opens a database connection, but no authored Resource claims ownership",
+      });
+      return { migrationAuthority: evidencePath };
+    }
+    ctx.addFact(compRef, "resource.ownership", target.name, {
+      evidenceClass: "DERIVED", confidence: "deterministic", provRecs: [pr],
+      semantics: "migration and connection authority in this root resolve to the authored logical database",
+    });
+    // Migrations and a connection string are the same dependency a declared
+    // client matcher would find, so the edge carries the same instance key and
+    // the two routes merge into one fact.
+    const client = ctx.clientKeyForResourceType("logical-database");
+    const attrs = client ? { via: "migrations+connection", client } : { via: "migrations+connection" };
+    ctx.addEdge("usesResource", compRef, target.ref, attrs, [pr], "DERIVED");
+    return {
+      migrationAuthority: evidencePath,
+      bindings: [{ kind: "database", logicalResourceRef: target.ref, resolution: "resolved", provenanceIds: null, _provs: new Set([pr]) }],
+    };
+  }
+}
+
+const POOL_HINT = /(createPool|new Pool|pg\.Pool|psycopg2?\.connect|sql\.Open|mysql\.createConnection|Pool\(|DataSource|prisma\.(datasource|client)|DATABASE_URL|DB_DSN)/;
+
+function hasConnectionEvidence(ctx, unit) {
+  for (const f of ctx.repo.walk(unit.root)) {
+    if (/\.(ts|tsx|js|mjs|go|py|rb|java|kt|rs|ex|cs|php)$/.test(f)) {
+      if (/(^|\/)(tests?|__tests__)\//.test(f)) continue;
+      if (POOL_HINT.test(ctx.repo.readText(f))) return true;
+    }
+  }
+  return false;
+}
+
+// A Resource whose name starts with the component name and whose type is a
+// database. A deterministic naming convention, not a guess: an ambiguous match
+// is left unresolved.
+function findDatabaseResource(ctx, name) {
+  const cands = ctx.sources.entities.filter(
+    (e) => e.kind === "Resource" && e.doc.spec.type === "logical-database" && e.name.startsWith(name)
+  );
+  return cands.length === 1 ? cands[0] : null;
+}

package/adapters/deploy-config.mjs

@@ -0,0 +1,34 @@
+// Deployment-config adapter: platform manifests that make a root deployable.
+// Only the file's existence is treated as evidence; no value from these files
+// is ever reported as deployed state.
+import { Adapter } from "./registry.mjs";
+
+const DEPLOY_FILES = [
+  "fly.toml", "app.yaml", "render.yaml", "railway.json", "vercel.json",
+  "netlify.toml", "heroku.yml", "Procfile", "service.yaml", "k8s/deployment.yaml",
+  "chart/Chart.yaml", "serverless.yml", "serverless.yaml", "ansible.cfg",
+];
+
+export class DeployConfigAdapter extends Adapter {
+  static adapterName = "deploy-config";
+  constructor() {
+    super({ name: "deploy-config", version: "1.0.0", kind: "unit-marker" });
+  }
+  detect(ctx, root) {
+    for (const n of DEPLOY_FILES) {
+      if (ctx.repo.exists(root + "/" + n)) return { path: root + "/" + n, shape: "deployable" };
+    }
+    return null;
+  }
+  extract(ctx, unit) {
+    const { repo, prov, compRef } = ctx;
+    const out = { deployConfigs: [] };
+    for (const n of DEPLOY_FILES) {
+      const p = unit.root + "/" + n;
+      if (!repo.exists(p)) continue;
+      prov.add("observed", p, "deploy-extractor", ["der:" + compRef + ":/artifact"]);
+      out.deployConfigs.push(p);
+    }
+    return out;
+  }
+}

package/adapters/dockerfile.mjs

@@ -0,0 +1,26 @@
+// Dockerfile adapter: a Dockerfile is deployable-artifact evidence.
+import { Adapter } from "./registry.mjs";
+
+export class DockerfileAdapter extends Adapter {
+  static adapterName = "dockerfile";
+  constructor() {
+    super({ name: "dockerfile", version: "1.0.0", kind: "unit-marker" });
+  }
+  detect(ctx, root) {
+    for (const n of ["Dockerfile", "Dockerfile.prod", "Containerfile"]) {
+      if (ctx.repo.exists(root + "/" + n)) return { path: root + "/" + n, shape: "deployable" };
+    }
+    return null;
+  }
+  extract(ctx, unit) {
+    const { repo, prov, compRef } = ctx;
+    const out = { dockerfiles: [] };
+    for (const n of ["Dockerfile", "Dockerfile.prod", "Containerfile"]) {
+      const p = unit.root + "/" + n;
+      if (!repo.exists(p)) continue;
+      prov.add("observed", p, "deploy-extractor", ["der:" + compRef + ":/artifact"]);
+      out.dockerfiles.push(p);
+    }
+    return out;
+  }
+}

package/adapters/events.mjs

@@ -0,0 +1,145 @@
+// Event subject adapter.
+//
+// Discovers event subjects and their producers and consumers from source,
+// filtered by the project's declared event subject prefixes. Two things matter
+// here:
+//
+//   1. No hard-coded project vocabulary. Koda's `koda.` prefix became a
+//      configuration value; without prefixes the extractor falls back to a
+//      conservative three-or-more-segment shape, which is what subject-based
+//      brokers actually use.
+//   2. Producer and consumer roles are evidence, not assumption. A file that
+//      merely mentions a subject is neither.
+import { Adapter } from "./registry.mjs";
+import { sourceFiles as sourceFilesOf } from "../core/sourcescan.mjs";
+
+const SRC_EXT = /\.(ts|tsx|js|jsx|mts|cts|mjs|cjs|go|py|rb|java|kt|rs|ex|exs|cs|php)$/;
+const TEST_PATH = /(^|\/)(tests?|__tests__|spec)\//;
+const TEST_FILE = /\.(test|spec)\./;
+
+// A subject-shaped token: three or more dot-separated lowercase segments, with
+// optional trailing wildcards. Two-segment values are usually scopes, not
+// subjects, and are excluded for exactly that reason.
+// A subject is three or more dot-separated segments: `orders.created.v1`. A
+// declared family is two or more segments plus a wildcard: `orders.created.*`.
+// Both are real and both are indexed. A bare `orders.*` is NOT accepted: a
+// wildcard at the top level is a catch-all, not a subject, and letting it in
+// would fold every subject in the system into one meaningless family.
+const SUBJECT_TOKEN = /["'`]([a-z][a-z0-9_-]*(?:\.[a-z0-9_-]+)+(?:[.*>])?|[a-z][a-z0-9_-]*(?:\.[a-z0-9_-]+)+\.(?:\*|>))["'`]/g;
+// A named subject constant: its name is what a producer file actually mentions,
+// while the pattern lives in another unit. Resolving the name is what lets a
+// component that publishes "LESSON_PUBLISHED" be credited with producing the
+// subject the shared package defines.
+const SUBJECT_CONST = /\b([A-Z][A-Z0-9_]*_SUBJECT)\b\s*[=:]\s*["'`]([a-z][a-z0-9_-]*(?:\.[a-z0-9_-]+){2,}(?:[.*>])?)["'`]/g;
+// Any identifier bound to a subject literal, in any naming style. A producer
+// file usually references the constant by name; the literal itself lives in the
+// shared unit that defines the vocabulary.
+const SUBJECT_DECL = /\b([A-Za-z_$][\w$]*)\b\s*(?::\s*string\s*)?=\s*["'`]([a-z][a-z0-9_-]*(?:\.[a-z0-9_-]+){2,}(?:[.*>])?)["'`]/g;
+const CONST_REF = /\b([A-Za-z_$][\w$]*)\b/g;
+
+const PUBLISH_HINT = /\b(publish|emit|enqueue|produce|outbox|Publish\(|Emit\()/;
+const CONSUME_HINT = /\b(subscribe|consume|onMessage|handler|WithFilterSubject|FilterSubjects|busloop|subscriber|ProcessBatch|dlq|DLQ|ack|Nak\()/;
+
+export class EventsAdapter extends Adapter {
+  static adapterName = "events";
+  constructor() {
+    super({ name: "events", version: "1.0.0", kind: "source" });
+  }
+  extract(ctx, unit) {
+    const { repo, prov, compRef } = ctx;
+    const prefixes = (ctx.cfg.discovery.eventPatternPrefixes || []).filter(Boolean);
+    const contract = ctx.primaryEventContract();
+    if (!contract) return {};
+    // Constants declared anywhere in the repository, and which of those
+    // declarations this unit can actually see (itself plus what it depends on).
+    const consts = new Map();
+    const collectDecls = (root) => {
+      for (const f of sourceFilesOf(ctx.repo, root)) {
+        const text = ctx.repo.readText(f);
+        for (const m of text.matchAll(SUBJECT_DECL)) consts.set(m[1], m[2]);
+        for (const m of text.matchAll(SUBJECT_CONST)) consts.set(m[1], m[2]);
+      }
+    };
+    collectDecls(unit.root);
+    // A unit can only be credited with a subject it can see: its own sources,
+    // plus those of the units it declares a dependency on, transitively. The
+    // dependency map is built from manifests before extraction, so this does
+    // not depend on adapter execution order.
+    const visible = ctx.transitiveDependencies(compRef);
+    for (const other of ctx.discovery.eligible) {
+      if (other.component && visible.has(other.component.ref) && other.component.ref !== compRef) collectDecls(other.root);
+    }
+    const families = new Set();
+    for (const f of repo.walk(unit.root)) {
+      if (!SRC_EXT.test(f)) continue;
+      if (TEST_PATH.test(f) || TEST_FILE.test(f)) continue;
+      const text = repo.readText(f);
+      const publish = PUBLISH_HINT.test(text);
+      const consume = CONSUME_HINT.test(text);
+      if (!publish && !consume) continue;
+      const found = new Set();
+      for (const m of text.matchAll(SUBJECT_TOKEN)) {
+        const s = m[1];
+        if (prefixes.length && !prefixes.some((p) => s.startsWith(p))) continue;
+        found.add(s);
+      }
+      for (const m of text.matchAll(CONST_REF)) {
+        const pattern = consts.get(m[1]);
+        if (pattern && pattern !== m[0] && (!prefixes.length || prefixes.some((p) => pattern.startsWith(p)))) found.add(pattern);
+      }
+      for (const s of found) {
+        if (s.endsWith(".*") || s.endsWith(".>")) families.add(s);
+      }
+      for (const s of found) {
+        const pr = prov.add("observed", f, "event-extractor", ["evt:" + s]);
+        if (publish) ctx.addEvent(s, "producer", compRef, pr, contract);
+        if (consume) ctx.addEvent(s, "consumer", compRef, pr, contract);
+      }
+    }
+    // The family set is only needed to fold literals; the fold itself happens in
+    // the index builder, where the contract and the resolution state are known.
+    void families;
+    return {};
+  }
+  // A declared event catalog is a strong, human-maintained statement of which
+  // component subscribes to which subjects. The catalog file is the contract.
+  contracts(ctx) {
+    const out = [];
+    for (const ec of ctx.cfg.discovery.eventContracts || []) {
+      // A contract may be a file, a directory, or a module prefix.
+      const files = ctx.repo.filesWithPrefix(ec.path);
+      if (!files.length) {
+        ctx.errors.push({
+          code: "AGENTDOC_PATH_UNRESOLVED",
+          message: "declared event contract path does not resolve: " + ec.path,
+          path: ec.path,
+        });
+        continue;
+      }
+      const patterns = ec.format === "code" ? harvestFromCode(ctx, ec, files) : Object.keys(safeJson(ctx, ec));
+      // Provenance must name a real file; the contract may be a directory or a
+      // module prefix.
+      const evidenceFile = files.find((f) => SRC_EXT.test(f) && !/\.(test|spec)\./.test(f)) || files[0];
+      const pr = ctx.prov.add("declared", evidenceFile, "event-catalog-extractor", patterns.map((p) => "evt:" + p));
+      for (const p of patterns.sort()) ctx.addEvent(p, "consumer", ec.consumer, pr, { format: ec.format === "code" ? "code" : "declared-catalog", ref: ec.path });
+    }
+    return out;
+  }
+}
+
+function safeJson(ctx, ec) {
+  try {
+    return ctx.repo.readJson(ec.path);
+  } catch {
+    return {};
+  }
+}
+
+function harvestFromCode(ctx, ec, files) {
+  const out = new Set();
+  for (const f of files) {
+    if (!SRC_EXT.test(f)) continue;
+    for (const m of ctx.repo.readText(f).matchAll(SUBJECT_TOKEN)) out.add(m[1]);
+  }
+  return [...out];
+}

package/adapters/generic.mjs

@@ -0,0 +1,86 @@
+// Generic adapter: language- and toolchain-agnostic facts only.
+//
+// Nothing here knows a language, a package manager, a provider or a folder
+// name. It contributes the two things any repository can be said to have:
+// conventional documentation (handled in core/derive.mjs) and health contract
+// route literals found in source.
+import { Adapter } from "./registry.mjs";
+import { resolveClientResources } from "./resource-client.mjs";
+import { sourceFiles } from "../core/sourcescan.mjs";
+
+// Conservative: a health route is an absolute string literal that looks like a
+// liveness or readiness endpoint. Anything more specific belongs to a
+// framework adapter.
+const HEALTH_LITERAL = /["'`](\/(?:healthz|health|livez|readyz|ready|ping|status))["'`]/;
+
+export class GenericAdapter extends Adapter {
+  static adapterName = "generic";
+  constructor() {
+    super({ name: "generic", version: "1.0.0", kind: "source" });
+  }
+
+  extract(ctx, unit) {
+    const { repo, prov, compRef } = ctx;
+    const derived = { healthContracts: [] };
+    const seen = new Set();
+    const ports = new Set();
+    const portFiles = new Map();
+    const allSrc = sourceFiles(repo, unit.root, { test: false });
+    for (const f of allSrc) {
+      const text = repo.readText(f);
+      const pm = /ListenAndServe\(\s*":(\d{2,5})"|\bPORT\s*=\s*"?(\d{2,5})"?|\bport:\s*(\d{2,5})\b/.exec(text);
+      if (pm) {
+        const p = pm[1] || pm[2] || pm[3];
+        ports.add(p);
+        if (!portFiles.has(p)) portFiles.set(p, f);
+      }
+      const m = HEALTH_LITERAL.exec(text);
+      if (!m) continue;
+      const route = m[1];
+      if (seen.has(route)) continue;
+      seen.add(route);
+      const pr = prov.add("observed", f, "health-extractor", ["der:" + compRef + ":/healthContracts"]);
+      derived.healthContracts.push({ path: f, route, semantics: "liveness", provenanceIds: null, _provs: new Set([pr]) });
+    }
+    if (derived.healthContracts.length > 1) derived.healthContracts.sort((a, b) => (a.route < b.route ? -1 : 1));
+    // A port is only a fact when the source states exactly one. Two literals
+    // mean the component binds more than one, and a single number would be a
+    // confident half-truth.
+    // Declared external services front Resources; resolve those bindings.
+    // Provenance must name a file that exists. The dependency evidence is the
+    // manifest when there is one, and otherwise the unit's descriptor.
+    const manifest = ["package.json", "go.mod", "Cargo.toml", "pyproject.toml", "pom.xml"]
+      .map((n) => unit.root + "/" + n)
+      .find((p) => repo.exists(p)) || ctx.componentEntity().file;
+    const clientProv = prov.add("observed", manifest, "client-resolver", ["rel:pending", "der:" + compRef + ":/bindings"]);
+    resolveClientResources(ctx, unit, compRef, clientProv);
+
+    // Capability detectors are declared, not hard-coded: a manifest cannot tell
+    // you a component can use a browser API, but a source literal can.
+    for (const cap of (ctx.cfg.discovery.capabilities || [])) {
+      let re;
+      try {
+        re = new RegExp(cap.match);
+      } catch {
+        continue;
+      }
+      for (const f of allSrc) {
+        if (!re.test(repo.readText(f))) continue;
+        const cpr = prov.add("observed", f, "capability-extractor", ["cap:" + compRef + "|" + cap.name]);
+        ctx.addCapability(compRef, cap.name, cpr, "DERIVED");
+        break;
+      }
+    }
+
+    if (ports.size === 1) {
+      const p = [...ports][0];
+      const pr = prov.add("observed", portFiles.get(p) || ctx.componentEntity().file, "port-extractor", ["der:" + compRef + ":/port"]);
+      derived.port = Number(p);
+      ctx.addFact(compRef, "component.port", Number(p), {
+        evidenceClass: "DERIVED", confidence: "deterministic", provRecs: [pr],
+        semantics: "the single TCP port the source binds a listener to",
+      });
+    }
+    return derived;
+  }
+}

package/adapters/github-actions.mjs

@@ -0,0 +1,106 @@
+// GitHub Actions adapter.
+//
+// CI is a verification authority: a workflow that names a component's paths is
+// the check that must be run for that component. Recording the mapping means
+// an agent changing a component is told which gate covers it, instead of
+// guessing or running everything.
+import { Adapter } from "./registry.mjs";
+import { parseYamlDocuments } from "../core/yaml.mjs";
+
+export class GitHubActionsAdapter extends Adapter {
+  static adapterName = "github-actions";
+  constructor() {
+    super({ name: "github-actions", version: "1.0.0", kind: "ci" });
+  }
+  // No detect(): a workflow directory is not a unit marker. It is not evidence
+  // of an importable or deployable artifact, and a marker path is hashed as a
+  // file for provenance, so a directory marker can only fail. GitHub runs only
+  // the repository-root .github/workflows; a nested one (vendored upstream, a
+  // subtree) is inert and is ignored here too.
+  contracts(ctx) {
+    const dir = ".github/workflows";
+    if (!ctx.repo.isDir(dir)) return [];
+    const out = [];
+    const files = ctx.repo.walk(dir).filter((f) => /\.ya?ml$/.test(f)).sort();
+    const units = ctx.discovery.eligible.filter((u) => u.component);
+    for (const f of files) {
+      let text = "";
+      try {
+        text = ctx.repo.readText(f);
+      } catch {
+        continue;
+      }
+      let doc = null;
+      try {
+        doc = parseYamlDocuments(text, f)[0]?.doc;
+      } catch {
+        doc = null;
+      }
+      const steps = [];
+      if (doc && doc.jobs) {
+        for (const [jobName, job] of Object.entries(doc.jobs)) {
+          for (const step of (job && job.steps) || []) {
+            const run = [step.run, step.uses].filter(Boolean).join(" ");
+            if (!run) continue;
+            steps.push({ job: jobName, run: String(run) });
+          }
+        }
+      }
+      const covered = new Set();
+      for (const u of units) {
+        if (text.includes(u.root + "/") || (u.pkgName && text.includes(u.pkgName))) covered.add(u.component.ref);
+      }
+      const pr = ctx.prov.add("observed", f, "ci-extractor", []);
+      const subjects = [];
+      steps.forEach((s, i) => {
+        if (!/[a-z0-9]/i.test(s.run)) return;
+        const command = s.run.trim().slice(0, 600);
+        // A step that installs dependencies or checks out code is not a check.
+        // Recording it as one would bury the commands that actually gate.
+        const tier = ciTier(command);
+        if (!tier) return;
+        const id = "ci:" + f.replace(/[^A-Za-z0-9]+/g, "-") + ":" + s.job + ":" + i;
+        if (covered.size) {
+          ctx.addVerification({
+            id,
+            componentRefs: [...covered].sort(),
+            tier,
+            command,
+            configPaths: [f],
+            provRecs: [pr],
+          });
+          subjects.push("ver:" + id);
+        } else {
+          // A gate that names no component is repository-wide: it applies to
+          // everything, so it is recorded once as a gate rather than
+          // duplicated onto every component.
+          // The graph id must not itself start with the provenance prefix, or
+          // the subject key becomes ambiguous. "repo-gate:" is unambiguous.
+          const gid = "repo-gate:" + f.replace(/[^A-Za-z0-9]+/g, "-") + ":" + s.job + ":" + i;
+          ctx.addGate({ id: gid, tier: ciTier(command), command, configPaths: [f], provRecs: [pr] });
+          subjects.push("gate:" + gid);
+        }
+      });
+      for (const s of subjects) pr.subjects.add(s);
+      void steps;
+      void covered;
+    }
+    return out;
+  }
+}
+
+// Returns null for a step that is not a check. Install, checkout, cache and
+// upload steps gate nothing and would only add noise to a routing surface.
+const NOT_A_CHECK = /^\s*(?:-\s*)?(?:uses:\s*actions\/(?:checkout|cache|upload|download|setup-|artifact)|run:\s*(?:\w*\s*)?(?:pnpm|npm|yarn|bun)\s+(?:i|install|ci)\b)/i;
+
+function ciTier(run) {
+  if (NOT_A_CHECK.test(run.trim())) return null;
+  if (/^uses:/.test(run.trim()) && !/check|lint|test|build|audit|scan/i.test(run)) return null;
+  if (/e2e|playwright|cypress/.test(run)) return "e2e";
+  if (/contract|openapi|api:check|drift|catalog/.test(run)) return "contract";
+  if (/integration/.test(run)) return "integration";
+  if (/lint|typecheck|type-check|golangci|vet/.test(run)) return "static";
+  if (/\btest\b|pytest|vitest|jest|go test/.test(run)) return "unit";
+  if (/\bbuild\b|tsc|compile/.test(run)) return "build";
+  return null;
+}

package/adapters/go.mjs

@@ -0,0 +1,91 @@
+// Go adapter: go.mod / go.work as unit markers, module graph as build
+// relations, and the go toolchain's own verification commands.
+import { Adapter } from "./registry.mjs";
+
+export class GoAdapter extends Adapter {
+  static adapterName = "go";
+  constructor() {
+    super({ name: "go", version: "1.0.0", kind: "unit-marker" });
+  }
+  roots(ctx) {
+    const out = [];
+    const ws = "go.work";
+    if (!ctx.repo.exists(ws)) return out;
+    const text = ctx.repo.readText(ws);
+    const block = /use\s*\(([^)]*)\)/s.exec(text);
+    const candidates = block
+      ? block[1].split("\n").map((l) => l.replace(/\/\/.*$/, "").trim()).filter(Boolean)
+      : [...text.matchAll(/^\s*use\s+(\S+)/gm)].map((m) => m[1]);
+    for (const raw of candidates) {
+      const d = raw.replace(/^\.\//, "").replace(/\/$/, "");
+      if (!d || d.startsWith("//") || d.includes("..")) continue;
+      if (!ctx.repo.isDir(d)) continue;
+      if (!ctx.repo.exists(d + "/go.mod")) continue;
+      out.push({ root: d, deployable: ctx.repo.isDir(d + "/cmd"), importable: !ctx.repo.isDir(d + "/cmd") });
+    }
+    return out;
+  }
+  detect(ctx, root) {
+    const p = root + "/go.mod";
+    if (!ctx.repo.exists(p)) return null;
+    return { path: p, shape: ctx.repo.isDir(root + "/cmd") ? "deployable" : "importable" };
+  }
+  extract(ctx, unit) {
+    const { repo, prov, compRef } = ctx;
+    const p = unit.root + "/go.mod";
+    if (!repo.exists(p)) return {};
+    const derived = { languages: new Set(["go"]), runtimes: new Set(["go"]) };
+    const text = repo.readText(p);
+    const pr = prov.add("observed", p, "gomod-extractor", ["der:" + compRef + ":/runtimes", "der:" + compRef + ":/languages"]);
+
+    for (const m of text.matchAll(/^\s*(?:require\s+)?([a-z0-9.]+\.[a-z0-9./-]+)\s+v[0-9]/gm)) {
+      const mod = m[1];
+      const target = ctx.unitByGoModule.get(mod);
+      if (target && target.component && target.component.ref !== compRef) {
+        ctx.addEdge("buildDependsOn", compRef, target.component.ref, { via: "go-module" }, [pr], "DERIVED");
+      } else {
+        for (const x of ctx.externalMatchers()) {
+          if (!x.re.test(mod)) continue;
+          ctx.addExternal(compRef, x.name, x.mechanism, x.role, pr, "DERIVED");
+        }
+      }
+    }
+    // Workspace members depended on by import alone. A Go workspace member can
+    // have no require line at all, so the import graph is the only evidence.
+    for (const importPath of ctx.importIndex.goPathsByUnit.get(unit) || []) {
+      for (const [mod, target] of ctx.unitByGoModule) {
+        if (target === unit || !target.component) continue;
+        if (importPath !== mod && importPath.startsWith(mod + "/")) {
+          ctx.addEdge("buildDependsOn", compRef, target.component.ref, { via: "go-import" }, [pr], "DERIVED");
+        }
+      }
+    }
+
+    const hasTests = repo.walk(unit.root).some((f) => /_test\.go$/.test(f));
+    ctx.addVerification({
+      id: compRef + ":go-test",
+      componentRefs: [compRef],
+      tier: "unit",
+      command: "go test ./...",
+      configPaths: [p],
+      provRecs: [pr],
+    });
+    ctx.addVerification({
+      id: compRef + ":go-vet",
+      componentRefs: [compRef],
+      tier: "static",
+      command: "go vet ./...",
+      configPaths: [p],
+      provRecs: [pr],
+    });
+    if (hasTests) derived.hasTests = true;
+    derived.goModule = unit.goModule;
+    return derived;
+  }
+}
+
+export function goExternalName(mod) {
+  const parts = mod.split("/");
+  const tail = parts[parts.length - 1].replace(/\.v\d+$/, "");
+  return (tail || parts[0]).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "go-module";
+}

package/adapters/graphql.mjs

@@ -0,0 +1,28 @@
+// GraphQL adapter: SDL as the canonical contract plus deterministic consumer
+// resolution.
+import { Adapter } from "./registry.mjs";
+import { resolveContractConsumers, isBuildConfig } from "./contract-consumers.mjs";
+
+export class GraphQLAdapter extends Adapter {
+  static adapterName = "graphql";
+  constructor() {
+    super({ name: "graphql", version: "1.0.0", kind: "contract" });
+  }
+  contracts(ctx) {
+    const out = [];
+    for (const api of ctx.sources.entities.filter((e) => e.kind === "API" && ["graphql", "graphql-sdl"].includes(e.doc.spec.type))) {
+      const ref = api.doc.spec.contract.ref;
+      const text = ctx.repo.readText(ref);
+      const types = [...text.matchAll(/^\s*(?:type|interface|input|enum|scalar|union)\s+([A-Za-z_][A-Za-z0-9_]*)/gm)].map((m) => m[1]);
+      const queries = [...text.matchAll(/^\s*(?:extend\s+)?type\s+Query\s*\{([\s\S]*?)\n\}/gm)]
+        .flatMap((m) => [...m[1].matchAll(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*[(:]/gm)].map((x) => x[1]));
+      ctx.addContract({ apiRef: api.ref, ref, types: [...new Set(types)].sort(), queries: [...new Set(queries)].sort() });
+      const consumers = resolveContractConsumers(ctx, ref, api.doc.spec.provider);
+      for (const [consumerRef, files] of consumers) {
+        const provs = files.map((f) => ctx.prov.add(isBuildConfig(f) ? "validated" : "observed", f, "api-contract-extractor", ["rel:pending"]));
+        ctx.addEdge("consumesApi", consumerRef, api.ref, { via: files.some(isBuildConfig) ? "codegen" : "source-reference" }, provs, "DERIVED");
+      }
+    }
+    return out;
+  }
+}