@maycombhq/atticus 2.0.0-beta.25 → 2.0.0-beta.27

package/dist/chunk-UWBODTY7.js

@@ -0,0 +1,514 @@
+import { createRequire as __atticusCreateRequire } from "node:module";
+import { fileURLToPath as __atticusFileURLToPath } from "node:url";
+var require = __atticusCreateRequire(import.meta.url);
+var __atticusUrl = (p) => new URL("./" + p, import.meta.url).href;
+var __atticusPath = (p) => __atticusFileURLToPath(__atticusUrl(p));
+import {
+  changesSince
+} from "./chunk-X5B7KYPD.js";
+import {
+  ContractsFile,
+  FACTS_SCHEMA_VERSION,
+  canonicalize,
+  catalogDirOf,
+  factsDirOf,
+  parseFacts,
+  parseRecord,
+  serializeFacts,
+  staleCite,
+  toCanonicalYaml
+} from "./chunk-WJWSB65O.js";
+import {
+  writeFileAtomic
+} from "./chunk-SMFFUFMN.js";
+import {
+  RecordId,
+  cmpText,
+  external_exports
+} from "./chunk-A3LVMCA5.js";
+import {
+  SCHEMA_VERSION
+} from "./chunk-NWMFVPEP.js";
+import {
+  require_dist
+} from "./chunk-BQGDB6ZL.js";
+import {
+  __toESM
+} from "./chunk-TV45EUGM.js";
+
+// packages/scanner/dist/slots.js
+var import_yaml = __toESM(require_dist(), 1);
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+var SLOT_VERSION = 1;
+var BUILD_MANIFEST_VERSION = 1;
+var BUILD_VERSION = "2.0.0-beta.27.2";
+var DISMISSALS_VERSION = 1;
+var SHA256 = external_exports.string().regex(/^[0-9a-f]{64}$/, "a SHA-256, 64 lowercase hex digits");
+var REPO = RecordId;
+var COMMIT = external_exports.string().min(1);
+var RECORD = external_exports.record(external_exports.string(), external_exports.unknown()).describe("A catalog record of contract C1 (schema/catalog/<kind>.json), checked as one");
+var PATH = external_exports.string().min(1).describe("A metarepo-relative path, '/'-separated");
+var ReadersSlot = external_exports.strictObject({
+  slotVersion: external_exports.literal(SLOT_VERSION),
+  kind: external_exports.literal("readers"),
+  repo: REPO,
+  commit: COMMIT,
+  /** `read`: a full read. `legacy`: adopted by `atticus upgrade`. There is no partial. */
+  status: external_exports.enum(["read", "legacy"]),
+  /** Each extractor that ran, sorted; none for a legacy slot (no reader ran). */
+  extractors: external_exports.array(external_exports.strictObject({ id: external_exports.string().min(1), version: external_exports.string().min(1) })),
+  /**
+   * A hash of what steered the readers: the repo's scan settings, the rule files, the plugins
+   * and their pins. Null for a legacy slot: nothing steered an adoption.
+   */
+  settings: SHA256.nullable(),
+  /** The repo's records as the readers produced them, before the merge, sorted by kind then id. */
+  records: external_exports.array(RECORD)
+}).refine((s) => s.status === "legacy" || s.commit !== "unknown", {
+  message: "a read slot names the commit it read",
+  path: ["commit"]
+}).refine((s) => s.status === "legacy" === (s.settings === null), {
+  message: "a read slot has a settings hash, and a legacy slot has none (null)",
+  path: ["settings"]
+}).refine((s) => s.status === "read" || s.extractors.length === 0, {
+  message: "a legacy slot lists no extractors: no reader ran",
+  path: ["extractors"]
+});
+var FactsSlotMeta = external_exports.strictObject({
+  slotVersion: external_exports.literal(SLOT_VERSION),
+  kind: external_exports.literal("facts"),
+  repo: REPO,
+  commit: COMMIT,
+  factsSchemaVersion: external_exports.number().int().positive(),
+  /** The SHA-256 of the snapshot's bytes (`<repo>.jsonl`). */
+  factsHash: SHA256,
+  /** The repo's `<repo>.contracts.yaml` as read at the facts' commit (ADR 0151), or null. */
+  contracts: ContractsFile.nullable(),
+  /**
+   * Beta.27.2 (ADR 0195 addendum "a legacy join its caller's facts place elsewhere"): verify's
+   * own verdict that the read is complete, every source file read or reviewed. Left out for a
+   * read in parts (never false), so a meta written before it reads as one.
+   */
+  readComplete: external_exports.literal(true).optional()
+});
+var LegacyJoinsSlot = external_exports.strictObject({
+  slotVersion: external_exports.literal(SLOT_VERSION),
+  kind: external_exports.literal("legacy-joins"),
+  status: external_exports.literal("legacy"),
+  /** Records with evidence from several repos, or none, adopted at the upgrade; by kind then id. */
+  records: external_exports.array(RECORD),
+  /** The hash of each slot and build input as it was at the upgrade, by its path. */
+  inputs: external_exports.record(PATH, SHA256)
+});
+var HASHED = external_exports.strictObject({ path: PATH, sha256: SHA256 });
+var BuildManifest = external_exports.strictObject({
+  version: external_exports.literal(BUILD_MANIFEST_VERSION),
+  /** The build that wrote it (`BUILD_VERSION`): a change of it explains a removal. */
+  buildVersion: external_exports.string().min(1),
+  /** Every file the last build wrote under catalog/generated/, with the sources it came from. */
+  files: external_exports.array(external_exports.strictObject({ path: PATH, sha256: SHA256, sources: external_exports.array(HASHED) }))
+});
+var CrossCheckDismissals = external_exports.strictObject({
+  version: external_exports.literal(DISMISSALS_VERSION),
+  /** Each dismissed cross-check item: its key, and the readers' value it was dismissed at. */
+  dismissed: external_exports.array(external_exports.strictObject({
+    key: external_exports.string().min(1),
+    // Required: the readers' value it was dismissed at (null when they found none).
+    readers: external_exports.unknown().refine((v) => v !== void 0, "the readers' value is required")
+  }))
+});
+var byKindThenId = (a, b) => a.kind === b.kind ? cmpText(a.id, b.id) : cmpText(a.kind, b.kind);
+function recordData(r) {
+  return canonicalize(r.kind === "Flow" ? r : { ...r, schemaVersion: SCHEMA_VERSION });
+}
+function json(value) {
+  return JSON.stringify(value, null, 2) + "\n";
+}
+var sortedRecords = (records) => [...records].sort(byKindThenId).map(recordData);
+function readersSlotOf(s) {
+  return {
+    ...s,
+    extractors: [...s.extractors].sort((a, b) => a.id === b.id ? cmpText(a.version, b.version) : cmpText(a.id, b.id)),
+    records: [...s.records].sort(byKindThenId)
+  };
+}
+function serializeReadersSlot(s) {
+  const x = readersSlotOf(s);
+  return json({
+    slotVersion: x.slotVersion,
+    kind: x.kind,
+    repo: x.repo,
+    commit: x.commit,
+    status: x.status,
+    extractors: x.extractors.map((e) => ({ id: e.id, version: e.version })),
+    settings: x.settings,
+    records: sortedRecords(x.records)
+  });
+}
+function serializeFactsSlotMeta(m) {
+  return json({
+    slotVersion: m.slotVersion,
+    kind: m.kind,
+    repo: m.repo,
+    commit: m.commit,
+    factsSchemaVersion: m.factsSchemaVersion,
+    factsHash: m.factsHash,
+    contracts: m.contracts === null ? null : canonicalize(m.contracts, ["schemaVersion"]),
+    ...m.readComplete ? { readComplete: true } : {}
+  });
+}
+function serializeFactsSnapshot(facts) {
+  return serializeFacts(facts);
+}
+function serializeLegacyJoins(s) {
+  return json({
+    slotVersion: s.slotVersion,
+    kind: s.kind,
+    status: s.status,
+    records: sortedRecords(s.records),
+    inputs: Object.fromEntries(Object.entries(s.inputs).sort(([a], [b]) => cmpText(a, b)))
+  });
+}
+function serializeBuildManifest(m) {
+  return json({
+    version: m.version,
+    buildVersion: m.buildVersion,
+    files: [...m.files].sort((a, b) => cmpText(a.path, b.path)).map((f) => ({
+      path: f.path,
+      sha256: f.sha256,
+      sources: [...f.sources].sort((a, b) => cmpText(a.path, b.path)).map((s) => ({ path: s.path, sha256: s.sha256 }))
+    }))
+  });
+}
+function serializeDismissals(d) {
+  return toCanonicalYaml({
+    version: d.version,
+    dismissed: [...d.dismissed].sort((a, b) => cmpText(a.key, b.key)).map((x) => ({ key: x.key, readers: x.readers }))
+  }, ["version", "key", "readers"]);
+}
+var zodIssues = (e) => e.issues.map((i) => ({ path: i.path.map(String).join("."), message: i.message }));
+function parseJson(text) {
+  try {
+    const t = text.charCodeAt(0) === 65279 ? text.slice(1) : text;
+    return { ok: true, value: JSON.parse(t.replace(/\r\n?/g, "\n")) };
+  } catch (e) {
+    return { ok: false, issues: [{ path: "", message: `not JSON: ${e.message}` }] };
+  }
+}
+function parseRecords(rows) {
+  const records = [];
+  const issues = [];
+  rows.forEach((row, i) => {
+    const p = parseRecord(row);
+    if (p.ok)
+      records.push(p.record);
+    else
+      for (const x of p.issues)
+        issues.push({ path: `records.${i}${x.path ? `.${x.path}` : ""}`, message: x.message });
+  });
+  return issues.length ? { ok: false, issues } : { ok: true, records };
+}
+function parseReadersSlot(text, repo) {
+  const j = parseJson(text);
+  if (!j.ok)
+    return j;
+  const s = ReadersSlot.safeParse(j.value);
+  if (!s.success)
+    return { ok: false, issues: zodIssues(s.error) };
+  const r = parseRecords(s.data.records);
+  if (!r.ok)
+    return r;
+  const issues = [];
+  if (repo !== void 0 && s.data.repo !== repo)
+    issues.push({ path: "repo", message: `names ${s.data.repo}, but the file is ${repo}'s` });
+  if (s.data.status === "read")
+    r.records.forEach((rec, i) => {
+      const other = rec.evidence.find((e) => e.repo !== void 0 && e.repo !== s.data.repo);
+      if (other)
+        issues.push({
+          path: `records.${i}.evidence`,
+          message: `cites ${other.repo}, not the slot's repo ${s.data.repo}`
+        });
+    });
+  return issues.length ? { ok: false, issues } : { ok: true, slot: { ...s.data, records: r.records } };
+}
+async function readReadersSlot(root, repo) {
+  const text = await readFile(readersSlotPath(root, repo), "utf8").catch(() => void 0);
+  return text === void 0 ? void 0 : parseReadersSlot(text, repo);
+}
+function parseFactsSlotMeta(text) {
+  const j = parseJson(text);
+  if (!j.ok)
+    return j;
+  const s = FactsSlotMeta.safeParse(j.value);
+  return s.success ? { ok: true, slot: s.data } : { ok: false, issues: zodIssues(s.error) };
+}
+function parseFactsSnapshot(text) {
+  const p = parseFacts(text.replace(/\r\n?/g, "\n"));
+  if (!p.ok)
+    return { ok: false, issues: p.issues.map((i) => ({ path: "", message: i.message })) };
+  if (p.newer?.length)
+    return {
+      ok: false,
+      issues: [{ path: "", message: "holds facts of a kind a newer Atticus wrote" }]
+    };
+  return { ok: true, facts: p.facts };
+}
+function parseLegacyJoins(text) {
+  const j = parseJson(text);
+  if (!j.ok)
+    return j;
+  const s = LegacyJoinsSlot.safeParse(j.value);
+  if (!s.success)
+    return { ok: false, issues: zodIssues(s.error) };
+  const r = parseRecords(s.data.records);
+  return r.ok ? { ok: true, slot: { ...s.data, records: r.records } } : r;
+}
+function parseBuildManifest(text) {
+  const j = parseJson(text);
+  if (!j.ok)
+    return j;
+  const s = BuildManifest.safeParse(j.value);
+  return s.success ? { ok: true, slot: s.data } : { ok: false, issues: zodIssues(s.error) };
+}
+function parseDismissals(text) {
+  let data;
+  try {
+    data = (0, import_yaml.parse)(text.replace(/\r\n?/g, "\n"));
+  } catch (e) {
+    return { ok: false, issues: [{ path: "", message: `not YAML: ${e.message}` }] };
+  }
+  const s = CrossCheckDismissals.safeParse(data);
+  return s.success ? { ok: true, slot: s.data } : { ok: false, issues: zodIssues(s.error) };
+}
+function slotJsonSchemas() {
+  const files = {
+    ReadersSlot,
+    FactsSlotMeta,
+    LegacyJoinsSlot,
+    BuildManifest,
+    CrossCheckDismissals
+  };
+  const out = {};
+  for (const [name, schema] of Object.entries(files))
+    out[name] = {
+      $id: `https://maycombhq.github.io/atticus/schema/sources/v1/${name}.json`,
+      title: name,
+      ...external_exports.toJSONSchema(schema, { io: "input", unrepresentable: "any" })
+    };
+  return out;
+}
+function sourcesRelOf(root) {
+  return [...relative(root, catalogDirOf(root)).split(sep), "sources"].filter(Boolean).join("/");
+}
+function sourcesDirOf(root) {
+  return join(catalogDirOf(root), "sources");
+}
+function readersSlotPath(root, repo) {
+  return join(sourcesDirOf(root), "readers", `${repo}.json`);
+}
+function factsSlotPaths(root, repo) {
+  return {
+    facts: join(sourcesDirOf(root), "facts", `${repo}.jsonl`),
+    meta: join(sourcesDirOf(root), "facts", `${repo}.meta.json`)
+  };
+}
+function legacyJoinsPath(root) {
+  return join(sourcesDirOf(root), "legacy", "joins.json");
+}
+function buildManifestPath(root) {
+  return join(sourcesDirOf(root), "build.json");
+}
+function dismissalsPath(root, repo) {
+  return join(factsDirOf(root), `${repo}.crosscheck.yaml`);
+}
+var sha256Of = (text) => createHash("sha256").update(text, "utf8").digest("hex");
+async function writeSlotFile(path, text) {
+  const current = await readFile(path, "utf8").catch(() => void 0);
+  if (current?.replace(/\r\n?/g, "\n") === text)
+    return "unchanged";
+  await writeFileAtomic(path, text);
+  return "written";
+}
+async function writeReadersSlots(root, observations, o = {}) {
+  const out = [];
+  for (const x of observations) {
+    const path = readersSlotPath(root, x.repo);
+    const onDisk = await readFile(path, "utf8").catch(() => void 0);
+    const kept = (reason, detail) => {
+      const p = onDisk === void 0 ? void 0 : parseReadersSlot(onDisk);
+      return {
+        repo: x.repo,
+        slot: onDisk === void 0 ? "none" : "kept-last-good",
+        ...p?.ok ? { commit: p.slot.commit } : {},
+        ...reason ? { reason } : {},
+        ...detail ? { detail } : {}
+      };
+    };
+    if (!x.full) {
+      out.push(kept(x.why, x.detail));
+      continue;
+    }
+    const text = serializeReadersSlot(x.slot);
+    const back = parseReadersSlot(text, x.repo);
+    if (!back.ok)
+      throw new Error(`The readers slot of ${x.repo} doesn't read back: ${back.issues.map((i) => `${i.path}: ${i.message}`).join("; ")}`);
+    if (onDisk?.replace(/\r\n?/g, "\n") === text) {
+      out.push({ repo: x.repo, slot: "unchanged", commit: x.slot.commit });
+      continue;
+    }
+    if (o.hold) {
+      out.push(kept(o.hold));
+      continue;
+    }
+    await writeFileAtomic(path, text);
+    out.push({ repo: x.repo, slot: "written", commit: x.slot.commit });
+  }
+  return out;
+}
+async function writeFactsSlot(root, s) {
+  const paths = factsSlotPaths(root, s.repo);
+  const text = serializeFactsSnapshot(s.facts);
+  const meta = serializeFactsSlotMeta({
+    slotVersion: SLOT_VERSION,
+    kind: "facts",
+    repo: s.repo,
+    commit: s.commit,
+    factsSchemaVersion: FACTS_SCHEMA_VERSION,
+    factsHash: sha256Of(text),
+    contracts: s.contracts,
+    ...s.readComplete ? { readComplete: true } : {}
+  });
+  const facts = await writeSlotFile(paths.facts, text);
+  return { facts, meta: await writeSlotFile(paths.meta, meta), count: s.facts.length };
+}
+async function readFactsSlot(root, repo) {
+  const paths = factsSlotPaths(root, repo);
+  const [text, metaText] = await Promise.all([
+    readFile(paths.facts, "utf8").catch(() => void 0),
+    readFile(paths.meta, "utf8").catch(() => void 0)
+  ]);
+  if (text === void 0 && metaText === void 0)
+    return void 0;
+  if (text === void 0 || metaText === void 0)
+    return {
+      ok: false,
+      problem: `has ${text === void 0 ? "a meta and no facts" : "facts and no meta"}`
+    };
+  const meta = parseFactsSlotMeta(metaText);
+  if (!meta.ok)
+    return {
+      ok: false,
+      problem: `its meta doesn't read (${meta.issues[0]?.message ?? "invalid"})`
+    };
+  if (meta.slot.repo !== repo)
+    return { ok: false, problem: `its meta names another repo (${meta.slot.repo})` };
+  if (meta.slot.factsSchemaVersion > FACTS_SCHEMA_VERSION)
+    return {
+      ok: false,
+      problem: `a newer Atticus wrote it (facts version ${meta.slot.factsSchemaVersion})`
+    };
+  if (sha256Of(text.replace(/\r\n?/g, "\n")) !== meta.slot.factsHash)
+    return { ok: false, problem: "its facts aren't the ones its meta hashed" };
+  const facts = parseFactsSnapshot(text);
+  if (!facts.ok)
+    return {
+      ok: false,
+      problem: `its facts don't read (${facts.issues[0]?.message ?? "invalid"})`
+    };
+  return { ok: true, meta: meta.slot, facts: facts.facts };
+}
+async function factsSlotStaleness(root, repo, at) {
+  const slot = await readFactsSlot(root, repo);
+  if (!slot)
+    return void 0;
+  const command = `atticus verify ${repo} --write`;
+  if (!slot.ok)
+    return {
+      repo,
+      commit: "unknown",
+      head: at.head,
+      files: [],
+      facts: 0,
+      unusable: slot.problem,
+      command
+    };
+  const commit = slot.meta.commit;
+  if (commit === at.head || at.head.startsWith(commit) || commit.startsWith(at.head))
+    return void 0;
+  const diff = commit === "unknown" ? { changes: {}, missing: [commit] } : await changesSince(at.dir, [commit], at.head, at.git).catch(() => ({
+    changes: {},
+    missing: [commit]
+  }));
+  if (diff.missing.length)
+    return { repo, commit, head: at.head, files: [], facts: 0, notComparable: true, command };
+  const changes = Object.values(diff.changes)[0] ?? [];
+  const byFile = /* @__PURE__ */ new Map();
+  let stale = 0;
+  for (const f of slot.facts) {
+    const s = staleCite(f, changes);
+    if (!s)
+      continue;
+    stale++;
+    const e = byFile.get(s.file) ?? {
+      path: s.file,
+      how: s.how,
+      ...s.to !== void 0 ? { to: s.to } : {},
+      facts: []
+    };
+    e.facts.push(f.id);
+    byFile.set(s.file, e);
+  }
+  if (!stale)
+    return void 0;
+  return {
+    repo,
+    commit,
+    head: at.head,
+    files: [...byFile.values()].sort((a, b) => cmpText(a.path, b.path)).map((e) => ({ ...e, facts: [...e.facts].sort(cmpText) })),
+    facts: stale,
+    command
+  };
+}
+
+export {
+  SLOT_VERSION,
+  BUILD_MANIFEST_VERSION,
+  BUILD_VERSION,
+  DISMISSALS_VERSION,
+  ReadersSlot,
+  FactsSlotMeta,
+  LegacyJoinsSlot,
+  BuildManifest,
+  CrossCheckDismissals,
+  readersSlotOf,
+  serializeReadersSlot,
+  serializeFactsSlotMeta,
+  serializeFactsSnapshot,
+  serializeLegacyJoins,
+  serializeBuildManifest,
+  serializeDismissals,
+  parseReadersSlot,
+  readReadersSlot,
+  parseFactsSlotMeta,
+  parseFactsSnapshot,
+  parseLegacyJoins,
+  parseBuildManifest,
+  parseDismissals,
+  slotJsonSchemas,
+  sourcesRelOf,
+  sourcesDirOf,
+  readersSlotPath,
+  factsSlotPaths,
+  legacyJoinsPath,
+  buildManifestPath,
+  dismissalsPath,
+  sha256Of,
+  writeSlotFile,
+  writeReadersSlots,
+  writeFactsSlot,
+  readFactsSlot,
+  factsSlotStaleness
+};