agent-doc-system 0.0.0-stage → 1.1.0

package/adapters/typescript.mjs

@@ -0,0 +1,85 @@
+// TypeScript adapter.
+//
+// Owns tsconfig.json as an importability marker, project references as a build
+// relation source, and the framework route conventions that are genuinely
+// TypeScript-ecosystem facts rather than project conventions.
+import path from "node:path";
+import { Adapter } from "./registry.mjs";
+import { parseYamlDocuments } from "../core/yaml.mjs";
+
+export class TypeScriptAdapter extends Adapter {
+  static adapterName = "typescript";
+  constructor() {
+    super({ name: "typescript", version: "1.0.0", kind: "unit-marker" });
+  }
+  detect(ctx, root) {
+    const p = root + "/tsconfig.json";
+    if (!ctx.repo.exists(p)) return null;
+    return { path: p, shape: "importable" };
+  }
+  extract(ctx, unit) {
+    const { repo, prov, compRef } = ctx;
+    const p = unit.root + "/tsconfig.json";
+    if (!repo.exists(p)) return {};
+    const derived = { languages: new Set(["typescript"]), runtimes: new Set(["node"]) };
+    let ts;
+    try {
+      ts = parseTsconfig(repo, p);
+    } catch {
+      ts = {};
+    }
+    const pr = prov.add("observed", p, "tsconfig-extractor", ["der:" + compRef + ":/languages", "rel:pending"]);
+
+    // Project references: an explicit build-time dependency between units.
+    for (const refPath of (ts.references || [])) {
+      const targetDir = path.posix.normalize(path.posix.join(unit.root, refPath));
+      const target = ctx.unitForRoot(targetDir);
+      if (!target || !target.component) continue;
+      ctx.addEdge("buildDependsOn", compRef, target.component.ref, { via: "tsconfig-references" }, [pr], "DERIVED");
+    }
+    derived.tsconfig = { composite: Boolean(ts.compilerOptions?.composite), references: (ts.references || []).length };
+
+    // Route conventions of the file-based router ecosystem: a route file is a
+    // real HTTP surface and must be visible to the query surface.
+    const routes = [];
+    for (const base of ["src/app", "app", "src/pages", "pages"]) {
+      if (!repo.isDir(unit.root + "/" + base)) continue;
+      for (const f of repo.walk(unit.root + "/" + base)) {
+        const routePath = routeFor(unit.root, base, f);
+        if (!routePath) continue;
+        const rpr = prov.add("observed", f, "route-extractor", ["der:" + compRef + ":/routes"]);
+        routes.push({ path: f, route: routePath, provenanceIds: null, _provs: new Set([rpr]) });
+      }
+    }
+    if (routes.length) {
+      routes.sort((a, b) => (a.route < b.route ? -1 : 1));
+      derived.routes = routes;
+      // Published on the unit so other adapters can resolve a scheduled
+      // trigger to the component that actually serves the route.
+      unit.routes = routes;
+    }
+    return derived;
+  }
+}
+
+function routeFor(root, base, file) {
+  const rel = file.slice((root + "/" + base).length + 1);
+  if (base.endsWith("app")) {
+    if (!rel.endsWith("/route.ts") && !rel.endsWith("/route.tsx") && !rel.endsWith("/route.js")) return null;
+    const segs = rel.split("/").slice(0, -1);
+    if (!segs.length) return "/";
+    return "/" + segs.map((s) => (s.startsWith("(") && s.endsWith(")") ? "" : s.replace(/^\[\.\.\.(.+)\]$/, ":$1*").replace(/^\[(.+)\]$/, ":$1"))).join("/");
+  }
+  if (!rel.startsWith("api/") || !rel.endsWith(".ts")) return null;
+  return "/" + rel.slice(4).replace(/\.ts$/, "");
+}
+
+// tsconfig allows comments and trailing commas; strip them before JSON.parse.
+function parseTsconfig(repo, p) {
+  let text = repo.readText(p);
+  text = text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:"'\\])\/\/.*$/gm, "$1");
+  text = text.replace(/,(\s*[}\]])/g, "$1");
+  return JSON.parse(text);
+}
+
+export { parseYamlDocuments };

package/adapters/wrangler.mjs

@@ -0,0 +1,206 @@
+// Wrangler adapter (Cloudflare Workers / Pages).
+//
+// This adapter is where the most expensive lesson of the reference project
+// lives. A committed deployment manifest is a *declared* schedule and a
+// *declared* binding set. It is DERIVED evidence about what the repository
+// intends, and nothing more. If a live scheduler disagrees — an hourly trigger
+// with hour-3 gating where the manifest says "daily" — the disagreement has to
+// reach the graph as a conflict, which only happens if the manifest claim is
+// emitted as a fact on the same key the observation uses. So: no manifest value
+// is ever reported as deployed truth.
+import { Adapter } from "./registry.mjs";
+import { parse as parseToml } from "../core/toml.mjs";
+import { sourceFiles } from "../core/sourcescan.mjs";
+
+const MANIFESTS = ["wrangler.toml", "wrangler.json", "wrangler.jsonc"];
+
+export class WranglerAdapter extends Adapter {
+  static adapterName = "wrangler";
+  constructor() {
+    super({ name: "wrangler", version: "1.0.0", kind: "unit-marker" });
+  }
+  detect(ctx, root) {
+    for (const n of MANIFESTS) {
+      if (ctx.repo.exists(root + "/" + n)) return { path: root + "/" + n, shape: "deployable" };
+    }
+    return null;
+  }
+  extract(ctx, unit) {
+    const { repo, prov, compRef } = ctx;
+    const file = MANIFESTS.map((n) => unit.root + "/" + n).find((p) => repo.exists(p));
+    if (!file) return {};
+    let toml;
+    try {
+      toml = file.endsWith(".toml") ? parseToml(repo.readText(file), file) : stripJsonc(repo.readText(file));
+    } catch {
+      return {};
+    }
+    const derived = { runtimes: new Set(["cloudflare-workers"]) };
+    if (toml.name) unit.platformName = String(toml.name);
+    const pr = prov.add("observed", file, "platform-manifest-extractor", ["der:" + compRef + ":/runtimes", "der:" + compRef + ":/bindings"]);
+
+    const bindings = [];
+    // The manifest makes ONE claim about the binding set, so the graph records
+    // one fact. Emitting a fact per binding would make a manifest that declares
+    // two bindings look like a contradiction against a runtime that reports one.
+    const bindingKinds = new Set();
+    const bindingNames = new Set();
+    const pushBinding = (kind, locator) => {
+      bindingKinds.add(kind);
+      if (locator && locator.binding) bindingNames.add(locator.binding);
+      bindings.push({ kind, locator, resolution: "resolved", provenanceIds: null, _provs: new Set([pr]) });
+    };
+    for (const kv of toml.kv_namespaces || []) pushBinding("kv", { binding: String(kv.binding || "") });
+    for (const d1 of toml.d1_databases || []) pushBinding("d1", { binding: String(d1.binding || "") });
+    for (const r2 of toml.r2_buckets || []) pushBinding("r2", { binding: String(r2.binding || "") });
+    for (const dofs of toml.durable_objects?.bindings || []) pushBinding("durable-object", { binding: String(dofs.name || "") });
+    for (const em of toml.send_email || []) pushBinding("email-routing", { binding: String(em.name || em.binding || "") });
+    for (const q of toml.queues?.producers || []) pushBinding("queue-producer", { binding: String(q.binding || "") });
+    for (const q of toml.queues?.consumers || []) pushBinding("queue-consumer", { binding: String(q.queue || q.binding || "") });
+    if (bindings.length) derived.bindings = bindings;
+
+    // Service bindings: a platform-level runtime call. Resolved in a second
+    // pass once every unit's platform name is known.
+    const pending = [];
+    for (const svc of toml.services || []) {
+      pushBinding("service-binding", { binding: String(svc.binding || ""), service: String(svc.service || "") });
+      pending.push({ binding: String(svc.binding || ""), service: String(svc.service || "") });
+    }
+    if (pending.length) {
+      derived.serviceBindings = pending;
+      ctx.deferSecondPass((pass) => {
+        for (const sb of pending) {
+          const target = pass.byPlatformName.get(sb.service);
+          if (target && target.component) {
+            const epr = prov.add("observed", file, "service-binding-extractor", ["rel:pending"]);
+            ctx.addEdge("runtimeCalls", compRef, target.component.ref,
+              { transport: "service-binding", contractRef: file }, [epr], "DERIVED");
+          } else {
+            ctx.diagnostics.push({
+              severity: "warning",
+              code: "AGENTDOC_SERVICE_BINDING_UNRESOLVED",
+              subject: compRef,
+              refs: [compRef],
+              message: "service binding '" + sb.service + "' declared in " + file + " does not match any discovered component",
+              paths: [file],
+            });
+          }
+        }
+      });
+    }
+
+    if (bindingNames.size) {
+      ctx.addFact(compRef, "binding.declared", [...bindingNames].sort(), {
+        evidenceClass: "DERIVED", confidence: "deterministic", provRecs: [pr],
+        semantics: "the binding names the committed manifest declares for this component",
+      });
+    }
+    if (bindingKinds.size) {
+      ctx.addFact(compRef, "binding.kind", [...bindingKinds].sort(), {
+        evidenceClass: "DERIVED", confidence: "deterministic", provRecs: [pr],
+        semantics: "the kinds of platform binding the committed manifest declares for this component",
+      });
+    }
+
+    // Scheduled triggers. Emitted as a DERIVED fact on schedule.cron, which is
+    // the same key a scheduler observation uses, so the two can be compared.
+    const crons = ((toml.triggers && toml.triggers.crons) || []).map(String).sort();
+    if (crons.length) {
+      derived.schedules = crons;
+      ctx.addFact(compRef, "schedule.cron", crons.join(","), {
+        evidenceClass: "DERIVED", confidence: "deterministic", provRecs: [pr],
+        semantics: "cron expressions the committed deployment manifest declares for this component",
+      });
+      ctx.addFact(compRef, "schedule.enabled", true, {
+        evidenceClass: "DERIVED", confidence: "deterministic", provRecs: [pr],
+        semantics: "the manifest declares a trigger, i.e. the job is intended to be enabled",
+      });
+    }
+
+    // Job handlers: a cron URL variable names the endpoint a trigger calls.
+    // Again one claim, not one per variable.
+    const vars = toml.vars || {};
+    const declaredTargets = [];
+    for (const [varName, url] of Object.entries(vars)) {
+      if (typeof url !== "string") continue;
+      const m = /^https?:\/\/[^/]+(\/[^\s]*)$/.exec(url);
+      if (!m) continue;
+      declaredTargets.push({ var: varName, route: m[1] });
+    }
+    if (declaredTargets.length) {
+      derived.scheduleTargets = declaredTargets.slice().sort((a, b) => (a.route < b.route ? -1 : 1));
+      ctx.addFact(compRef, "schedule.target", [...new Set(declaredTargets.map((t) => t.route))].sort(), {
+        evidenceClass: "DERIVED", confidence: "deterministic", provRecs: [pr],
+        semantics: "endpoints the committed manifest points scheduled triggers at",
+      });
+      // A schedule that points at a route this repository implements is a
+      // `schedules` relation. Without it, "who does this trigger call?" has no
+      // answer and an agent debugging a missed job has nothing to follow.
+      for (const t of declaredTargets) {
+        ctx.deferSecondPass(() => {
+          const owner = findRouteOwner(ctx, t.route, compRef);
+          if (owner) {
+            const rpr = prov.add("observed", file, "schedule-extractor", ["rel:pending"]);
+            const tpr = prov.add("observed", owner.file, "schedule-extractor", ["rel:pending"]);
+            ctx.addEdge("schedules", compRef, owner.ref, { via: "declared-trigger-target", route: t.route }, [rpr, tpr], "DERIVED");
+          } else {
+            ctx.diagnostics.push({
+              severity: "warning",
+              code: "AGENTDOC_SCHEDULE_UNRESOLVED",
+              subject: compRef,
+              refs: [compRef],
+              message: "scheduled trigger target '" + t.route + "' declared in " + file + " does not resolve to a route in any discovered component",
+              paths: [file],
+            });
+          }
+        });
+      }
+    }
+    return derived;
+  }
+}
+
+// Resolve an absolute route path to the component that *serves* it.
+//
+// A route literal appears in more places than the component that owns it: every
+// generated OpenAPI client embeds the path it calls. So candidates are ranked
+// rather than counted, and only an unambiguous winner is used:
+//
+//   2  a file-based route whose path is this route
+//   1  a route literal in hand-written source
+//   0  a route literal in generated client code
+//
+// A tie at the top score is a genuine ambiguity and yields no relation.
+function findRouteOwner(ctx, route, selfRef) {
+  const generated = (ctx.cfg.discovery.generatedClientPatterns || ["/gen/", ".gen.", "/generated/", "/generated/"]).map(
+    (p) => new RegExp(escapeRe(p))
+  );
+  const isGenerated = (f) => generated.some((re) => re.test(f));
+  const candidates = [];
+  for (const unit of ctx.discovery.eligible) {
+    if (!unit.component || unit.component.ref === selfRef) continue;
+    const viaPath = (unit.routes || []).find((r) => r.route === route);
+    if (viaPath) { candidates.push({ ref: unit.component.ref, file: viaPath.path, score: 2 }); continue; }
+    for (const f of sourceFiles(ctx.repo, unit.root, { test: false })) {
+      const text = ctx.repo.readText(f);
+      if (!text.includes(route)) continue;
+      if (!new RegExp("[\"'\`]" + escapeRe(route) + "[\"'\`]").test(text)) continue;
+      candidates.push({ ref: unit.component.ref, file: f, score: isGenerated(f) ? 0 : 1 });
+      break;
+    }
+  }
+  if (!candidates.length) return null;
+  const best = Math.max(...candidates.map((c) => c.score));
+  const winners = candidates.filter((c) => c.score === best);
+  const distinct = new Set(winners.map((c) => c.ref));
+  if (distinct.size !== 1) return null;
+  return winners[0];
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function stripJsonc(text) {
+  return JSON.parse(text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:"'\\])\/\/.*$/gm, "$1").replace(/,(\s*[}\]])/g, "$1"));
+}