@maycombhq/atticus 0.0.0-stage → 2.0.0-beta.2

package/dist/chunk-LR3R6Z2A.js

@@ -0,0 +1,400 @@
+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 {
+  table
+} from "./chunk-VOGCSYOI.js";
+import {
+  storeSpecLookup
+} from "./chunk-XY3P7JW7.js";
+import {
+  createAdapters
+} from "./chunk-7JUKDRSZ.js";
+import {
+  readCatalog
+} from "./chunk-27NKUS3X.js";
+import {
+  FeatureError,
+  FlowGraph,
+  featureCoverage,
+  featureFlows,
+  featureLinkDecision,
+  featureMergeDecision,
+  featureNameDecision,
+  featureSplitDecisions,
+  featureTagDecision,
+  featureToSpec,
+  featuresForScan,
+  nameFeatures,
+  parseExternalRef,
+  parseFinishedNamingRun,
+  suggestFeatureLinks,
+  workItemsFromTracker,
+  writeNameProposals
+} from "./chunk-L24C55VN.js";
+import {
+  readWorkItemExports
+} from "./chunk-23W7VWKR.js";
+import {
+  applyCurated,
+  loadOrgPack,
+  migrateCatalog,
+  orgPackDirOf,
+  recordPath,
+  serializeRecord
+} from "./chunk-S2A7YC3Q.js";
+import {
+  SCHEMA_VERSION
+} from "./chunk-D3PO4DOZ.js";
+
+// packages/cli/dist/feature-commands.js
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { userInfo } from "node:os";
+import { dirname, join } from "node:path";
+async function load(root, io) {
+  const op = await loadOrgPack(join(orgPackDirOf(root)));
+  for (const p of op.problems)
+    io.err(`org-pack/${p.file}: ${p.path ? `${p.path}: ` : ""}${p.message}`);
+  const catalogRel = op.sources.layout.catalog;
+  const catalogDir = join(root, catalogRel);
+  const generated = await readCatalog(join(catalogDir, "generated"), { cacheRoot: root });
+  const curated = await readCatalog(join(catalogDir, "curated"), { cacheRoot: root });
+  for (const p of [...generated.problems, ...curated.problems])
+    io.err(`catalog ${p.file}: ${p.message}`);
+  const base = generated.records.filter((r) => r.kind !== "Capability");
+  const found = await featuresForScan({
+    records: base,
+    decisions: curated.records,
+    proposalsDir: join(catalogDir, "proposals")
+  });
+  for (const p of found.problems)
+    io.err(`${p.decision}: ${p.message}`);
+  const featureDecisions = curated.records.filter((d) => d.kind === "CuratedDecision" && d.target.startsWith("feature."));
+  const applied = applyCurated(found.features, featureDecisions);
+  for (const p of applied.problems)
+    io.err(`${p.decision}: ${p.message}`);
+  const features = applied.records.filter((r) => r.kind === "Capability");
+  return {
+    op,
+    catalogDir,
+    catalogRel,
+    records: [...base, ...features],
+    features,
+    decisions: curated.records
+  };
+}
+var featureId = (id) => id.startsWith("feature.") ? id : `feature.${id}`;
+function find(l, id, io) {
+  const f = l.features.find((x) => x.id === featureId(id));
+  if (!f)
+    io.err(`There is no feature ${featureId(id)}. List them with: atticus feature list`);
+  return f;
+}
+async function writeDecisions(l, root, ds) {
+  const out = [];
+  for (const d of ds) {
+    const rel = `${l.catalogRel}/curated/${recordPath(d)}`;
+    const full = join(root, ...rel.split("/"));
+    await mkdir(dirname(full), { recursive: true });
+    await writeFile(full, serializeRecord(d), "utf8");
+    out.push(rel);
+  }
+  return out;
+}
+async function decide(root, io, make, said) {
+  const l = await load(root, io);
+  let ds;
+  try {
+    ds = make(l);
+  } catch (e) {
+    if (e instanceof FeatureError) {
+      io.err(e.message);
+      return 2;
+    }
+    throw e;
+  }
+  if (!ds)
+    return 1;
+  const files = await writeDecisions(l, root, ds);
+  io.out(`Wrote ${files.join(" and ")}: ${said(files)}. Commit ${files.length > 1 ? "them" : "it"} so every scan keeps ${files.length > 1 ? "them" : "it"}.`);
+  return 0;
+}
+var by = (o) => o.by ?? userInfo().username;
+async function featureList(root, o, io) {
+  const l = await load(root, io);
+  if (l.records.length === 0) {
+    io.err("The catalog is empty: read the repos first (atticus map <repo>, then atticus verify <repo> --write).");
+    return 2;
+  }
+  const cov = featureCoverage(l.records);
+  if (o.json) {
+    io.out(JSON.stringify({ features: l.features, coverage: cov }, null, 2));
+    return 0;
+  }
+  if (l.features.length === 0)
+    io.out("No features found yet.");
+  else
+    for (const line of table(["ID", "NAME", "NAMED BY", "OWNER", "ENTRY POINTS", "LINKS"], l.features.map((f) => [
+      f.id,
+      f.name,
+      f.namedBy,
+      f.owner ?? "-",
+      String(f.entryPoints.length),
+      String(f.externalRefs.length)
+    ])))
+      io.out(line);
+  const n = l.features.length;
+  io.out(`${n} feature${n === 1 ? "" : "s"}: ${cov.confirmed.length} confirmed, ${cov.detectedOnly.length} detected only.${cov.unknown.length ? ` No feature covers ${cov.unknown.join(", ")}.` : ""}`);
+  return 0;
+}
+async function featureShow(root, id, o, io) {
+  const l = await load(root, io);
+  const f = find(l, id, io);
+  if (!f)
+    return 1;
+  const flows = featureFlows(l.records).find((x) => x.feature.id === f.id);
+  const looseEnds = flows?.looseEnds ?? [];
+  if (o.json) {
+    io.out(JSON.stringify({ feature: f, system: flows?.system, looseEnds }, null, 2));
+    return 0;
+  }
+  const g = new FlowGraph(l.records);
+  const what = (x) => {
+    const e = g.endpoints.get(x);
+    if (e)
+      return `${e.method ? `${e.method} ` : ""}${e.pathOrTopic} on ${e.component}`;
+    const i = g.interfaces.get(x);
+    if (i)
+      return i.sync === "async" ? `event ${i.normalizedPath} from ${i.from} to ${i.to}` : `call from ${i.from}: ${i.method ?? ""} ${i.normalizedPath}`.trim();
+    const s = g.settings.get(x);
+    if (s)
+      return `schedule ${s.valueOrRef} on ${s.component}`;
+    return g.components.has(x) ? `batch job ${x}` : x;
+  };
+  io.out(`${f.name} (${f.id})`);
+  io.out(`  named by: ${f.namedBy}, ${f.confidence}`);
+  io.out(`  owner: ${f.owner ?? "-"}`);
+  io.out(`  tags: ${f.tags.length ? f.tags.join(", ") : "-"}`);
+  io.out(`  links: ${f.externalRefs.length ? f.externalRefs.map((r) => `${r.system}:${r.id}`).join(", ") : "-"}`);
+  if (f.description)
+    io.out(`  ${f.description}`);
+  io.out("Entry points:");
+  for (const line of table(["", ""], f.entryPoints.map((e) => [e, what(e)])).slice(1))
+    io.out(`  ${line}`);
+  io.out("Spans:");
+  const byKind = /* @__PURE__ */ new Map();
+  for (const r of f.records) {
+    const kind = g.records.get(r)?.kind ?? "Unknown";
+    byKind.set(kind, [...byKind.get(kind) ?? [], r]);
+  }
+  for (const kind of [...byKind.keys()].sort())
+    io.out(`  ${kind}: ${byKind.get(kind).join(", ")}`);
+  if (looseEnds.length) {
+    io.out("Loose ends:");
+    for (const e of looseEnds)
+      io.out(`  ${e.text}`);
+  }
+  return 0;
+}
+async function featureName(root, id, name, o, io) {
+  return decide(root, io, (l) => {
+    const f = find(l, id, io);
+    return f ? [
+      featureNameDecision(f, {
+        name,
+        by: by(o),
+        ...o.description ? { description: o.description } : {},
+        ...o.owner ? { owner: o.owner } : {}
+      })
+    ] : void 0;
+  }, () => `${featureId(id)} is "${name.trim()}"`);
+}
+async function featureTag(root, id, tags, o, io) {
+  let set = [];
+  return decide(root, io, (l) => {
+    const f = find(l, id, io);
+    if (!f)
+      return void 0;
+    const d = featureTagDecision(f, tags, { by: by(o) });
+    set = d.value.tags;
+    return [d];
+  }, () => `${featureId(id)} is tagged ${set.length ? set.join(", ") : "with nothing"}`);
+}
+async function featureMerge(root, into, from, o, io) {
+  return decide(root, io, (l) => {
+    const target = find(l, into, io);
+    const others = from.map((x) => find(l, x, io));
+    if (!target || others.some((x) => !x))
+      return void 0;
+    return [featureMergeDecision(target, others, { by: by(o) })];
+  }, () => `${from.map(featureId).join(", ")} ${from.length === 1 ? "is" : "are"} now part of ${featureId(into)}`);
+}
+async function featureSplit(root, id, entryPoints, o, io) {
+  let into = "";
+  return decide(root, io, (l) => {
+    const f = find(l, id, io);
+    if (!f)
+      return void 0;
+    const ds = featureSplitDecisions(f, entryPoints, {
+      by: by(o),
+      records: l.records,
+      ...o.name ? { name: o.name } : {},
+      ...o.into ? { into: featureId(o.into) } : {}
+    });
+    into = ds[0].target;
+    if (l.features.some((x) => x.id === into))
+      throw new FeatureError(`${into} already exists; merge into it instead, or pick another name.`);
+    return ds;
+  }, () => `${entryPoints.join(", ")} now ${entryPoints.length === 1 ? "starts" : "start"} ${into}`);
+}
+async function featureLink(root, id, ref, o, io) {
+  let label = "";
+  return decide(root, io, (l) => {
+    const f = find(l, id, io);
+    if (!f)
+      return void 0;
+    const r = parseExternalRef(ref, o.title);
+    label = `${r.system} ${r.id}`;
+    return [featureLinkDecision(f, r, { by: by(o) })];
+  }, () => `${featureId(id)} is linked to ${label}`);
+}
+async function featureSuggestLinks(root, o, io) {
+  const l = await load(root, io);
+  const items = [];
+  let tracker = o.workTracker;
+  if (!tracker && l.op.runtime.adapters.workTracker) {
+    try {
+      tracker = createAdapters(l.op.runtime).workTracker;
+    } catch (e) {
+      io.err(`The work tracker can't be reached (${e.message}); using the work-item exports in inputs/ instead.`);
+    }
+  }
+  if (tracker) {
+    try {
+      items.push(...await workItemsFromTracker(tracker));
+    } catch (e) {
+      io.err(`The work tracker can't be reached (${e.message}); using the work-item exports in inputs/ instead.`);
+    }
+  }
+  const exported = await readWorkItemExports({ root });
+  for (const p of exported.problems)
+    io.err(`${p.path}: ${p.message}`);
+  const seen = new Set(items.map((i) => `${i.system ?? "ado"}|${i.id}`));
+  for (const i of exported.items)
+    if (!seen.has(`${i.system}|${i.id}`))
+      items.push(i);
+  const suggestions = suggestFeatureLinks({
+    features: l.features,
+    items,
+    records: l.records,
+    decisions: l.decisions
+  });
+  if (o.json) {
+    io.out(JSON.stringify({ items: suggestions }, null, 2));
+    return suggestions.length ? 1 : 0;
+  }
+  if (!suggestions.length) {
+    io.out(items.length ? "No links to suggest." : "No work items to compare: the tracker gave none and inputs/ has no work-item export.");
+    return 0;
+  }
+  io.out(`${suggestions.length} link${suggestions.length === 1 ? "" : "s"} to confirm.`);
+  for (const s of suggestions) {
+    const ref = s.options[0].decision.value.externalRefs.at(-1);
+    io.out("");
+    io.out(s.id);
+    io.out(`  ${s.summary}`);
+    io.out(`  at ${s.source.path}${s.source.line ? `:${s.source.line}` : ""}`);
+    io.out(`  \u2192 atticus feature link ${s.records[0]} ${ref.system}:${ref.id}`);
+  }
+  return 1;
+}
+async function featureSpec(root, id, io) {
+  const l = await load(root, io);
+  const f = find(l, id, io);
+  if (!f)
+    return 1;
+  let draft;
+  try {
+    draft = featureToSpec(f, l.records);
+  } catch (e) {
+    if (e instanceof FeatureError) {
+      io.err(e.message);
+      return 1;
+    }
+    throw e;
+  }
+  const rel = draft.path.replace(/^openspec\//, `${l.op.sources.layout.openspec}/`);
+  const full = join(root, ...rel.split("/"));
+  if (await readFile(full).then(() => true, () => false)) {
+    io.err(`${rel} already exists; Atticus never overwrites a spec.`);
+    return 1;
+  }
+  await mkdir(dirname(full), { recursive: true });
+  await writeFile(full, draft.text, { encoding: "utf8", flag: "wx" });
+  io.out(`Wrote ${rel}, a draft from ${f.id}: check its requirements, then commit it in a pull request.`);
+  for (const s of await storeSpecLookup(root, draft.capability))
+    io.out(`The OpenSpec store ${s.store} (read-only) has a ${s.id} spec too: ${s.file}${s.purpose ? ` ("${s.purpose}")` : ""}. Check the two agree before the draft is merged.`);
+  return 0;
+}
+async function featureSuggestNames(root, o, io) {
+  const l = await load(root, io);
+  const res = await nameFeatures(l.features, l.records, o.runtime, { orgPack: l.op });
+  const written = await writeNameProposals(join(l.catalogDir, "proposals"), res.proposals);
+  if (o.json) {
+    io.out(JSON.stringify({ ...res, written }, null, 2));
+  } else {
+    res.proposals.forEach((p, i) => io.out(`Wrote ${l.catalogRel}/proposals/${written[i]}: ${p.feature} could be called "${p.name}".`));
+    for (const d of res.discarded)
+      io.err(`Discarded${d.feature ? ` ${d.feature}` : ""}: ${d.reason}`);
+    for (const r of res.runs.filter((x) => x.state === "failed"))
+      io.err(`The ${r.agent} run failed: ${r.reason ?? "no reason given"}`);
+    for (const r of res.runs.filter((x) => x.state === "waiting"))
+      io.out(`Handed the names of ${r.features.length} feature${r.features.length === 1 ? "" : "s"} to your assistant. When it is done, run: atticus handoff done ${r.runId}`);
+    const n = res.proposals.length;
+    io.out(`${n} proposal${n === 1 ? "" : "s"} from ${res.runs[0]?.agent ?? "feature-namer"}; confirm one with: atticus feature name <feature> <name>`);
+  }
+  return res.runs.some((r) => r.state === "failed") ? 1 : 0;
+}
+async function completeFeatureNaming(root, run, io, o = {}) {
+  const l = await load(root, io);
+  const at = (o.now ?? /* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z");
+  const res = parseFinishedNamingRun(run, l.features, at);
+  const written = await writeNameProposals(join(l.catalogDir, "proposals"), res.proposals);
+  res.proposals.forEach((p, i) => io.out(`Wrote ${l.catalogRel}/proposals/${written[i]}: ${p.feature} could be called "${p.name}".`));
+  for (const d of res.discarded)
+    io.err(`Discarded${d.feature ? ` ${d.feature}` : ""}: ${d.reason}`);
+  const n = res.proposals.length;
+  io.out(`${n} proposal${n === 1 ? "" : "s"} from ${run.request.agent.id}; confirm one with: atticus feature name <feature> <name>`);
+  return 0;
+}
+async function catalogMigrate(root, io, o = {}) {
+  const op = await loadOrgPack(join(orgPackDirOf(root)));
+  const rel = op.sources.layout.catalog;
+  const res = await migrateCatalog(join(root, rel), o);
+  for (const f of res.migrated)
+    io.out(`  ${rel}/${f}`);
+  for (const p of res.problems)
+    io.err(`${rel}/${p.file}: ${p.message}`);
+  if (!res.migrated.length && !res.problems.length)
+    io.out(`Every catalog file is already at schema version ${SCHEMA_VERSION}.`);
+  else if (res.migrated.length)
+    io.out(`${o.dryRun ? "Would migrate" : "Migrated"} ${res.migrated.length} file${res.migrated.length === 1 ? "" : "s"} to catalog schema version ${SCHEMA_VERSION}; ${res.current.length} already current.${o.dryRun ? "" : " Commit the change."}`);
+  return res.problems.length ? 1 : 0;
+}
+
+export {
+  featureList,
+  featureShow,
+  featureName,
+  featureTag,
+  featureMerge,
+  featureSplit,
+  featureLink,
+  featureSuggestLinks,
+  featureSpec,
+  featureSuggestNames,
+  completeFeatureNaming,
+  catalogMigrate
+};

package/dist/chunk-M766ZJ6W.js

@@ -0,0 +1,119 @@
+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 {
+  estimateOf
+} from "./chunk-FHH4I4ZV.js";
+import {
+  changeMapBody,
+  changeMapOf
+} from "./chunk-TDD55CJH.js";
+import "./chunk-BOHJZTEQ.js";
+import "./chunk-MVZVGYXH.js";
+import "./chunk-FITWGOJ2.js";
+import "./chunk-2ANOROX3.js";
+import "./chunk-65NYPGRC.js";
+import {
+  knowledgeAppliesMarkdown,
+  readKnowledgeApplies
+} from "./chunk-CKSITVS4.js";
+import "./chunk-L6SGQIR3.js";
+import {
+  readRound,
+  reviewedGates,
+  roundsOf
+} from "./chunk-3HI6Z55Y.js";
+import "./chunk-XY3P7JW7.js";
+import "./chunk-4AK7IBVP.js";
+import "./chunk-7JUKDRSZ.js";
+import "./chunk-27NKUS3X.js";
+import "./chunk-L24C55VN.js";
+import "./chunk-PAMPPUR6.js";
+import "./chunk-23W7VWKR.js";
+import "./chunk-7EKXJZ2Y.js";
+import "./chunk-MC3H7736.js";
+import "./chunk-T6AIP7H5.js";
+import "./chunk-EFHQ3TWP.js";
+import "./chunk-GQ4N4WKF.js";
+import "./chunk-CNUKCS2T.js";
+import "./chunk-S2A7YC3Q.js";
+import "./chunk-D3PO4DOZ.js";
+import "./chunk-TV45EUGM.js";
+
+// packages/cli/dist/handoff-review.js
+var days = (d) => `${d.p20}\u2013${d.p80} days (most likely ${d.p50})`;
+async function handoffReview(root, change) {
+  const lines = [];
+  lines.push("### What it changes", "");
+  const map = await changeMapOf(root, change).catch(() => void 0);
+  if (map && map.flows > 0) {
+    lines.push("```mermaid", changeMapBody(change, map).mermaid.trimEnd(), "```", "");
+    lines.push(`From ${map.flows} target flow${map.flows === 1 ? "" : "s"} in ${map.source}.`, "");
+  } else
+    lines.push("No target flows yet: the architecture stage writes them.", "");
+  const applies = await readKnowledgeApplies(root, change).catch(() => void 0);
+  if (applies)
+    lines.push(knowledgeAppliesMarkdown(applies).trimEnd(), "");
+  lines.push("### Estimate", "");
+  const est = await estimateOf(root, change).catch(() => void 0);
+  if (est?.effort) {
+    lines.push(days(est.effort), "");
+    for (const d of est.drivers.filter((x) => x.count > 0).slice(0, 5))
+      lines.push(`- ${d.what}: ${d.count}`);
+    if (est.needsClass)
+      lines.push(`- ${est.needsClass} unit${est.needsClass === 1 ? "" : "s"} not sized yet`);
+    lines.push("");
+  } else
+    lines.push(est ? "Not sized yet: the org pack's estimates don't cover these units." : "Not sized yet.", "");
+  lines.push("### Since the last round", "");
+  const reviewed = await reviewedGates(root, change).catch(() => []);
+  const openIds = async (gate, n) => new Set((await readRound(root, change, gate, n)).findings.filter(({ finding: f }) => f.state === "open").map(({ finding: f }) => f.id));
+  const code = (ids) => ids.map((i) => `\`${i}\``).join(", ");
+  let any = false;
+  for (const gate of reviewed) {
+    const rounds = await roundsOf(root, change, gate);
+    if (!rounds.length)
+      continue;
+    any = true;
+    if (rounds.length === 1) {
+      lines.push(`- ${gate} gate: the first round.`);
+      continue;
+    }
+    const [before, now] = [rounds.at(-2), rounds.at(-1)];
+    const [was, is] = [await openIds(gate, before), await openIds(gate, now)];
+    const closed = [...was].filter((i) => !is.has(i)).sort();
+    const added = [...is].filter((i) => !was.has(i)).sort();
+    const still = [...is].filter((i) => was.has(i)).length;
+    lines.push(`- ${gate} gate, round ${now} against round ${before}: ${closed.length} closed${closed.length ? ` (${code(closed)})` : ""}, ${added.length} new${added.length ? ` (${code(added)})` : ""}, ${still} still open.`);
+  }
+  if (!any)
+    lines.push("No gate has been reviewed yet.");
+  lines.push("");
+  lines.push("### Findings still open", "");
+  const gates = await reviewedGates(root, change).catch(() => []);
+  const open = [];
+  for (const gate of gates) {
+    const rounds = await roundsOf(root, change, gate);
+    if (!rounds.length)
+      continue;
+    for (const { finding: f } of (await readRound(root, change, gate, rounds.at(-1))).findings)
+      if (f.state === "open")
+        open.push({ gate, severity: f.severity, summary: f.summary, id: f.id });
+  }
+  if (!gates.length)
+    lines.push("No gate has been reviewed yet.", "");
+  else if (!open.length)
+    lines.push("None open.", "");
+  else {
+    const order = ["blocking", "gap", "risk", "idea"];
+    for (const f of open.sort((a, b) => order.indexOf(a.severity) - order.indexOf(b.severity)))
+      lines.push(`- **${f.severity}** (${f.gate}): ${f.summary} \`${f.id}\``);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+export {
+  handoffReview
+};