agent-doc-system 0.0.0-stage → 1.0.0

package/core/contracts.mjs

@@ -0,0 +1,121 @@
+// Contract validation and indexing.
+//
+// Every durable cross-component boundary should have exactly one canonical
+// machine-readable contract, and the Catalog points at it rather than
+// duplicating it. The default dialect is OpenAPI 3.1 for JSON HTTP, but a
+// protocol's native schema is equally valid: OIDC discovery, GraphQL SDL,
+// protobuf, AsyncAPI.
+import { parseYamlDocuments } from "./yaml.mjs";
+import { AgentDocError, CODES } from "./codes.mjs";
+
+const CONTRACTS = {
+  openapi: {
+    validate(text, fail) {
+      let root = null;
+      try {
+        const docs = parseYamlDocuments(text, "");
+        root = docs[0] && docs[0].doc;
+      } catch {
+        try {
+          root = JSON.parse(text);
+        } catch {
+          fail("not parseable as YAML or JSON");
+          return null;
+        }
+      }
+      if (!root || typeof root !== "object") { fail("root is not a mapping"); return null; }
+      if (typeof root.openapi !== "string") fail("missing 'openapi' version field");
+      else if (!/^3\.[01]/.test(root.openapi)) fail("openapi must be 3.0 or 3.1, got " + root.openapi);
+      if (!root.paths || typeof root.paths !== "object") fail("missing 'paths' object");
+      if (root.components === undefined) fail("missing 'components' object");
+      if (typeof root.info?.title !== "string") fail("missing 'info.title'");
+      return { openapi: root.openapi, title: root.info?.title || null, operations: countOps(root.paths) };
+    },
+    defRe: /\.(openapi)\.(ya?ml|json)$/,
+  },
+  asyncapi: {
+    validate(text, fail) {
+      let root = null;
+      try {
+        const docs = parseYamlDocuments(text, "");
+        root = docs[0] && docs[0].doc;
+      } catch {
+        try { root = JSON.parse(text); } catch { fail("not parseable as YAML or JSON"); return null; }
+      }
+      if (!root || root.asyncapi === undefined) { fail("missing 'asyncapi' field"); return null; }
+      if (!root.channels || typeof root.channels !== "object") fail("missing 'channels' object");
+      return { asyncapi: root.asyncapi, title: root.info?.title || null, channels: Object.keys(root.channels).length };
+    },
+    defRe: /\.(asyncapi)\.(ya?ml|json)$/,
+  },
+  protobuf: {
+    validate(text, fail) {
+      if (!/^\s*(syntax|edition)\s*=/m.test(text)) { fail("missing syntax or edition declaration"); return null; }
+      const services = [...text.matchAll(/^\s*service\s+([A-Za-z0-9_]+)/gm)].map((m) => m[1]);
+      if (!services.length) fail("no service definitions found");
+      return { services };
+    },
+    defRe: /\.proto$/,
+  },
+  graphql: {
+    validate(text, fail) {
+      if (!/(type|schema|interface|input|enum|scalar)\s+[A-Za-z_]/.test(text)) { fail("no GraphQL type definitions found"); return null; }
+      return { types: [...text.matchAll(/^\s*(?:type|interface|input|enum)\s+([A-Za-z_][A-Za-z0-9_]*)/gm)].map((m) => m[1]) };
+    },
+    defRe: /\.graphqls?$/,
+  },
+  "graphql-sdl": {
+    validate(text, fail) {
+      if (!/(type|schema|interface|input|enum|scalar)\s+[A-Za-z_]/.test(text)) { fail("no GraphQL type definitions found"); return null; }
+      return null;
+    },
+    defRe: /\.graphqls?$/,
+  },
+};
+
+function countOps(paths) {
+  let n = 0;
+  for (const v of Object.values(paths || {})) {
+    if (v && typeof v === "object") n += Object.keys(v).filter((k) => ["get", "put", "post", "delete", "options", "head", "patch", "trace"].includes(k)).length;
+  }
+  return n;
+}
+
+export function validateContractFile(repo, bundle, api) {
+  const type = api.doc.spec.type;
+  const ref = api.doc.spec.contract?.ref;
+  if (!ref) return;
+  if (type === "oidc") return; // the canonical authority is the published standard, not a file
+  const spec = CONTRACTS[type];
+  const text = repo.readText(ref);
+  const fail = (msg) => {
+    throw new AgentDocError(
+      CODES.CONTRACT_SYNTAX,
+      "contract " + ref + " is not a valid " + type + " definition: " + msg,
+      { path: ref, ref: api.ref }
+    );
+  };
+  if (!spec) throw new AgentDocError(CODES.CONTRACT_FORM, "unsupported contract type " + type, { path: ref, ref: api.ref });
+  const summary = spec.validate(text, fail);
+  void bundle;
+  api.contractSummary = summary;
+}
+
+export function contractDefRegex() {
+  const res = [];
+  for (const s of new Set(Object.values(CONTRACTS).map((c) => c.defRe.source))) res.push(s);
+  return new RegExp("(" + res.join("|") + ")");
+}
+
+// Contract files matching a declared type. Used by the audit to point at
+// contract-shaped files that no API claims.
+export function classifyContractFile(rel) {
+  for (const [type, spec] of Object.entries(CONTRACTS)) {
+    if (spec.defRe.test(rel)) return type;
+  }
+  return null;
+}
+
+export function contractTypes() {
+  return Object.keys(CONTRACTS);
+}

package/core/derive.mjs

@@ -0,0 +1,102 @@
+// Generic derivation: per-unit facts that hold for any language or toolchain.
+//
+// Everything technology-specific is delegated to adapters. This file owns only
+// facts that can be read from a directory listing alone: the conventional docs
+// that exist, the unit's deployable/importable shape, and the ownership of the
+// source root itself.
+import path from "node:path";
+import { assertRepoPath } from "./fsx.mjs";
+import { CODES } from "./codes.mjs";
+
+const DEFAULT_DOC_CANDIDATES = ["README.md", "ARCHITECTURE.md", "AGENTS.md", "CONTRIBUTING.md", "DESIGN.md", "OVERVIEW.md"];
+const DEFAULT_CONSTRAINT_CANDIDATES = ["CONSTRAINTS.md", "INVARIANTS.md"];
+const DEFAULT_RUNBOOK_CANDIDATES = ["RUNBOOK.md", "OPERATIONS.md", "ONCALL.md"];
+
+export function genericFacts(ctx, unit) {
+  const { repo, cfg, prov, compRef } = ctx;
+  const root = unit.root;
+  const derived = { sourcePath: root };
+
+  // ── artifact shape ────────────────────────────────────────────────────────
+  const shapeProv = unit.markers.map((m) => prov.add("observed", m.path, "discovery:" + m.adapter, ["der:" + compRef + ":/artifact"]));
+  prov.add("observed", ctx.descriptorPath(unit), "descriptor-locator", ["der:" + compRef + ":/sourcePath"]);
+  if (shapeProv.length) {
+    ctx.addFact(compRef, "component.deployable", unit.deployable, { evidenceClass: "DERIVED", confidence: "deterministic", provRecs: shapeProv });
+    ctx.addFact(compRef, "component.importable", unit.importable, { evidenceClass: "DERIVED", confidence: "deterministic", provRecs: shapeProv });
+  }
+
+  // ── conventional docs ─────────────────────────────────────────────────────
+  const docNames = cfg.discovery.docCandidates || DEFAULT_DOC_CANDIDATES;
+  const constraintNames = cfg.discovery.constraintCandidates || DEFAULT_CONSTRAINT_CANDIDATES;
+  const runbookNames = cfg.discovery.runbookCandidates || DEFAULT_RUNBOOK_CANDIDATES;
+  const docs = [];
+  const constraints = [];
+  const runbooks = [];
+  for (const n of docNames) {
+    const p = root + "/" + n;
+    if (repo.exists(p)) { docs.push(p); prov.add("observed", p, "docs-extractor", ["der:" + compRef + ":/docs"]); }
+  }
+  for (const n of constraintNames) {
+    const p = root + "/" + n;
+    if (repo.exists(p)) { constraints.push(p); prov.add("observed", p, "docs-extractor", ["der:" + compRef + ":/constraints"]); }
+  }
+  for (const n of runbookNames) {
+    const p = root + "/" + n;
+    if (repo.exists(p)) { runbooks.push(p); prov.add("observed", p, "docs-extractor", ["der:" + compRef + ":/runbooks"]); }
+  }
+  const spec = ctx.componentEntity().doc.spec || {};
+  for (const p of spec.context?.docs || []) { docs.push(p); prov.add("declared", ctx.descriptorPath(unit), "descriptor-reader", ["der:" + compRef + ":/docs"]); }
+  for (const p of spec.context?.constraints || []) { constraints.push(p); prov.add("declared", ctx.descriptorPath(unit), "descriptor-reader", ["der:" + compRef + ":/constraints"]); }
+  for (const p of spec.context?.runbooks || []) { runbooks.push(p); prov.add("declared", ctx.descriptorPath(unit), "descriptor-reader", ["der:" + compRef + ":/runbooks"]); }
+
+  const uniq = (a) => [...new Set(a)].sort();
+  derived.docs = uniq(docs);
+  derived.constraints = uniq(constraints);
+  derived.runbooks = uniq(runbooks);
+  derived.markers = unit.markers.map((m) => ({ adapter: m.adapter, path: m.path })).sort((a, b) => (a.path < b.path ? -1 : 1));
+
+  return derived;
+}
+
+// The declared component type must be corroborated by the artifact shape the
+// repository actually shows. Preserved from the reference implementation: an
+// authored claim that a library is deployable is a documentation bug.
+const DEPLOYABLE_TYPES = ["service", "worker", "job", "web-app", "static-site", "infrastructure"];
+const IMPORTABLE_TYPES = ["library", "contract-library", "cli"];
+
+export function checkArtifactType(entity, unit) {
+  const t = entity.doc.spec.type;
+  const out = [];
+  if (DEPLOYABLE_TYPES.includes(t) && !unit.deployable) {
+    out.push({
+      severity: "error",
+      code: CODES.ARTIFACT_TYPE,
+      message: "component '" + entity.name + "' declares type '" + t + "' but no deployable artifact evidence was found in its source root",
+      refs: [entity.ref],
+      paths: [entity.file],
+    });
+  }
+  if (IMPORTABLE_TYPES.includes(t) && !unit.importable) {
+    out.push({
+      severity: "error",
+      code: CODES.ARTIFACT_TYPE,
+      message: "component '" + entity.name + "' declares type '" + t + "' but no importable artifact evidence was found in its source root",
+      refs: [entity.ref],
+      paths: [entity.file],
+    });
+  }
+  if (["library", "contract-library", "cli"].includes(t) && unit.deployable && !unit.importable) {
+    out.push({
+      severity: "warning",
+      code: CODES.ARTIFACT_TYPE,
+      message: "component '" + entity.name + "' declares a library type but the root also shows deployable evidence; verify the authored type",
+      refs: [entity.ref],
+      paths: [entity.file],
+    });
+  }
+  return out;
+}
+
+export function assertContextPaths(paths, file, ref) {
+  for (const p of paths) assertRepoPath(p, file);
+}