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

package/dist/chunk-2BF2EYJV.js

@@ -0,0 +1,174 @@
+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 {
+  waitingQuestions
+} from "./chunk-L6SGQIR3.js";
+import {
+  gitUser
+} from "./chunk-EFHQ3TWP.js";
+import {
+  QuestionError,
+  QuestionScopeLevel,
+  QuestionState,
+  answerQuestion,
+  answerWords,
+  changesDirOf,
+  listQuestions,
+  questionsRelOf
+} from "./chunk-S2A7YC3Q.js";
+import "./chunk-D3PO4DOZ.js";
+import "./chunk-TV45EUGM.js";
+
+// packages/cli/dist/question-commands.js
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+var plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+var sentence = (s) => /[.!?]$/.test(s.trim()) ? s.trim() : `${s.trim()}.`;
+function scopeWords(s, short = false, change = false) {
+  const what = change ? "this change" : "this repo";
+  if (s.level === "repo")
+    return short ? what : `${what} (${s.id})`;
+  return `every repo of type ${s.id}`;
+}
+async function isChange(root, id) {
+  return stat(join(changesDirOf(root), id, "change.yaml")).then(() => true, () => false);
+}
+function questionLines(q, o = {}) {
+  const lines = [
+    `${q.id}  ${q.state}  ${q.repo}  (asked by ${q.askedBy.command} on ${q.askedBy.at.slice(0, 10)})`,
+    `  ${q.question}`,
+    ...q.options.map((o2, i) => `  ${i + 1}. ${o2.label}: ${sentence(o2.means)} It would change: ${sentence(o2.changes)}`),
+    `  Evidence: ${q.evidence.join(", ")}`
+  ];
+  if (q.answer)
+    lines.push(`  Answered by ${q.answer.by} on ${q.answer.at.slice(0, 10)}: ${answerWords(q)} (${scopeWords(q.answer.scope, true, o.change)})`);
+  else if (q.state === "open")
+    lines.push(`  Proposed scope: ${scopeWords(q.scope, false, o.change)}`, `  Answer: atticus questions answer ${q.id}${q.options.length ? " --option <n>, or" : ""} --text "your own words"`);
+  return lines;
+}
+async function questionsFiles(root, argv, io, deps = {}) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    strict: false,
+    options: {
+      root: { type: "string" },
+      json: { type: "boolean" },
+      state: { type: "string" },
+      option: { type: "string" },
+      text: { type: "string" },
+      scope: { type: "string" },
+      type: { type: "string" },
+      by: { type: "string" }
+    }
+  });
+  const str = (v) => typeof v === "string" ? v : void 0;
+  const [, command, id] = positionals;
+  if (command === "list") {
+    const state = str(values.state);
+    if (state !== void 0 && !QuestionState.safeParse(state).success) {
+      io.err("--state is open, answered or retired.");
+      return 2;
+    }
+    const r = await listQuestions(root, state ? { state } : {});
+    for (const p of r.problems)
+      io.err(`${p.file} isn't a valid question: ${p.message}`);
+    const waiting = !state || state === "open" ? await waitingQuestions(root) : [];
+    if (values.json === true) {
+      io.out(JSON.stringify({ ...r, waiting }, null, 2));
+      return r.problems.length ? 1 : 0;
+    }
+    const changes = /* @__PURE__ */ new Set();
+    for (const q of r.questions)
+      if (await isChange(root, q.repo))
+        changes.add(q.repo);
+    for (const q of r.questions)
+      for (const l of questionLines(q, { change: changes.has(q.repo) }))
+        io.out(l);
+    const what = state ?? "";
+    io.out(r.questions.length ? `${plural(r.questions.length, `${what ? `${what} ` : ""}question`)}.` : `No ${what ? `${what} ` : ""}questions.`);
+    if (waiting.length) {
+      io.out(`${plural(waiting.length, "more question")} ${waiting.length === 1 ? "waits" : "wait"}, asked once the open ones are answered:`);
+      for (const w of waiting)
+        io.out(`  ${w.change}, ${w.stage} stage: ${w.question}${w.evidence.length ? ` (${w.evidence.join(", ")})` : ""}`);
+      for (const rerun of [...new Set(waiting.map((w) => w.rerun))])
+        io.out(`Run the stage again after answering: ${rerun}`);
+    }
+    return r.problems.length ? 1 : 0;
+  }
+  if (command === "show") {
+    if (!id) {
+      io.err("questions show needs a question id, for example: atticus questions show q-1a2b3c4d5e6f");
+      return 2;
+    }
+    const q = (await listQuestions(root)).questions.find((x) => x.id === id);
+    if (!q) {
+      io.err(`No question ${id}: atticus questions list shows them.`);
+      return 1;
+    }
+    if (values.json === true)
+      io.out(JSON.stringify(q, null, 2));
+    else
+      for (const l of questionLines(q, { change: await isChange(root, q.repo) }))
+        io.out(l);
+    return 0;
+  }
+  if (command === "answer") {
+    if (!id) {
+      io.err("questions answer needs a question id, for example: atticus questions answer q-1a2b3c4d5e6f --option 1");
+      return 2;
+    }
+    const opt = str(values.option);
+    const text = str(values.text)?.trim() || void 0;
+    if (opt === void 0 === (text === void 0)) {
+      io.err('Answer with --option <n> or --text "your own words", one of the two.');
+      return 2;
+    }
+    const option = opt === void 0 ? void 0 : Number(opt);
+    if (option !== void 0 && (!Number.isInteger(option) || option < 1)) {
+      io.err("--option is the number of an option, counting from 1.");
+      return 2;
+    }
+    const scope = str(values.scope);
+    if (scope !== void 0 && !QuestionScopeLevel.safeParse(scope).success) {
+      io.err("--scope is repo (this repo only) or repo-type (every repo of its type).");
+      return 2;
+    }
+    try {
+      const by = str(values.by)?.trim() || (await gitUser(root)).handle;
+      const r = await answerQuestion(root, id, {
+        ...option !== void 0 ? { option } : {},
+        ...text !== void 0 ? { text } : {},
+        ...scope ? { scope } : {},
+        ...str(values.type) ? { repoType: str(values.type) } : {},
+        by,
+        at: (deps.now ?? /* @__PURE__ */ new Date()).toISOString()
+      });
+      const q = r.question;
+      io.out(`Answered ${q.id}: ${answerWords(q)} (for ${q.answer.scope.level === "repo" ? `${await isChange(root, q.repo) ? "this change" : "this repo"}, ${q.repo}` : scopeWords(q.answer.scope)}). Wrote ${questionsRelOf(root)}/${q.id}.yaml; commit it for review.`);
+      if (r.skill)
+        io.out(r.skill.written ? `Also wrote it under Answers in ${r.skill.path}; review it in the same pull request.` : `${r.skill.path} isn't there yet, so the answer is kept in the question file, with that path.`);
+      if (r.hosts)
+        io.out(r.hosts.added ? `Wrote ${r.hosts.host} under hosts for ${r.hosts.repo} in ${r.hosts.manifest}; review it in the same pull request.` : `${r.hosts.repo} already lists ${r.hosts.host} under hosts in ${r.hosts.manifest}.`);
+      io.out(`Next: ${q.rerun}`);
+      return 0;
+    } catch (e) {
+      if (!(e instanceof QuestionError))
+        throw e;
+      io.err(e.message);
+      return e.code === "bad-answer" ? 2 : 1;
+    }
+  }
+  io.err(`atticus questions ${command ?? ""} isn't a command: it is questions list, show or answer (atticus questions alone lists the knowledge gaps).`);
+  io.err('Usage: atticus questions list [--state open|answered|retired] [--json], atticus questions show <id> [--json], or atticus questions answer <id> --option <n> | --text "..." [--scope repo|repo-type] [--type <repo type>]');
+  return 2;
+}
+export {
+  questionLines,
+  questionsFiles,
+  scopeWords
+};

package/dist/chunk-2BFCZ3RK.js

@@ -0,0 +1,315 @@
+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 "./chunk-GLUX4EEP.js";
+import {
+  loadCatalog
+} from "./chunk-FITWGOJ2.js";
+import {
+  repoFor
+} from "./chunk-O3WI5KWW.js";
+import "./chunk-KEM4SDDP.js";
+import {
+  askHosts
+} from "./chunk-RVH5SUW5.js";
+import "./chunk-ZVM6AKKM.js";
+import {
+  estateFlow,
+  estateStepKey,
+  fieldLineage,
+  joinEstate
+} from "./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 {
+  fsRepo
+} from "./chunk-GQ4N4WKF.js";
+import "./chunk-CNUKCS2T.js";
+import {
+  listQuestions,
+  loadOrgPack,
+  orgPackDirOf,
+  questionId,
+  raiseQuestions,
+  readEstateJoins,
+  readRepoSpec,
+  slugify,
+  specRepos,
+  specsRelOf,
+  templateRef,
+  writeEstateJoins
+} from "./chunk-S2A7YC3Q.js";
+import "./chunk-D3PO4DOZ.js";
+import "./chunk-TV45EUGM.js";
+
+// packages/cli/dist/estate-commands.js
+var plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+var HOW = {
+  interface: "through the Interface",
+  endpoint: "to the entry point it names",
+  path: "by method and path"
+};
+var REASON = {
+  "no-target": "no target",
+  "no-flow": "no flow",
+  "no-citation": "no citation",
+  "family-mismatch": "a wrong family"
+};
+var ESTATE_TARGETS_STEP = "estate-targets";
+var ESTATE_TARGETS_NONE = "None of these";
+function estateAskDraft(a) {
+  return {
+    question: `Which component answers ${a.what}, which ${a.caller} calls?`,
+    options: [
+      ...a.candidates.map((c) => ({
+        label: c,
+        means: `${c} answers ${a.what}`,
+        changes: `The call-out joins ${c}'s flow at the next atticus estate join`
+      })),
+      {
+        label: ESTATE_TARGETS_NONE,
+        means: "None of these components answers it",
+        changes: "The call-out stays unjoined, and this isn't asked again"
+      }
+    ],
+    evidence: a.from.evidence ? [a.from.evidence] : [],
+    scope: "repo"
+  };
+}
+function estateAskId(a) {
+  const d = estateAskDraft(a);
+  return questionId({
+    step: ESTATE_TARGETS_STEP,
+    repo: a.from.repo,
+    question: d.question,
+    evidence: d.evidence
+  });
+}
+async function readSpecs(root, io, templates) {
+  const out = [];
+  for (const repo of await specRepos(root)) {
+    const s = await readRepoSpec(root, repo, { cacheRoot: root });
+    for (const p of s.problems)
+      io.err(`${p.file}: ${p.message}`);
+    if (s.flows.length)
+      out.push({ repo, flows: s.flows });
+    if (templates && s.header?.template)
+      templates[repo] = s.header.template;
+  }
+  return out;
+}
+async function specTemplates(root, refs) {
+  const op = await loadOrgPack(orgPackDirOf(root)).catch(() => void 0);
+  const out = {};
+  for (const [repo, ref] of Object.entries(refs)) {
+    const t = op?.specTemplates.find((x) => templateRef(x) === ref);
+    if (t)
+      out[repo] = t;
+  }
+  return out;
+}
+async function estateJoin(root, o, io) {
+  const refs = {};
+  const specs = await readSpecs(root, io, refs);
+  if (specs.length === 0) {
+    io.err(`There are no repo specs in ${specsRelOf(root)}/ yet. Draft them first: atticus spec draft <repo>.`);
+    return 2;
+  }
+  const { records } = await loadCatalog(root, { out: () => {
+  }, err: (l) => io.err(l) });
+  const templates = await specTemplates(root, refs);
+  const clones = /* @__PURE__ */ new Map();
+  const unchecked = /* @__PURE__ */ new Set();
+  const cited = async (repo, path, line) => {
+    if (!clones.has(repo)) {
+      const r2 = await repoFor(root, repo);
+      clones.set(repo, r2 ? { dir: r2.dir, lines: /* @__PURE__ */ new Map() } : null);
+      if (!r2)
+        unchecked.add(repo);
+    }
+    const c = clones.get(repo);
+    if (!c)
+      return true;
+    if (!c.lines.has(path)) {
+      const t = await fsRepo(repo, c.dir, "0".repeat(40)).readText(path).catch(() => void 0);
+      c.lines.set(path, t === void 0 ? 0 : t.replace(/\r\n?/g, "\n").replace(/\n$/, "").split("\n").length);
+    }
+    return line >= 1 && line <= c.lines.get(path);
+  };
+  const first = await joinEstate({ specs, records, cited, templates });
+  const askedBefore = new Map((await listQuestions(root, { step: ESTATE_TARGETS_STEP })).questions.map((q) => [q.id, q]));
+  const targets = {};
+  for (const a of first.asks) {
+    const q = askedBefore.get(estateAskId(a));
+    if (q?.state !== "answered" || !q.answer)
+      continue;
+    const label = q.answer.option !== void 0 ? q.options[q.answer.option - 1]?.label : q.answer.text;
+    if (label && label !== ESTATE_TARGETS_NONE)
+      targets[estateStepKey(a.from.flow, a.from.step)] = slugify(label);
+  }
+  const r = Object.keys(targets).length ? await joinEstate({ specs, records, cited, templates, targets }) : first;
+  const at = (o.now ?? /* @__PURE__ */ new Date()).toISOString();
+  const asked = [];
+  for (const a of r.asks) {
+    if (!a.from.evidence)
+      continue;
+    const before = askedBefore.get(estateAskId(a));
+    if (before) {
+      if (before.state === "open")
+        asked.push({ q: before, raised: false });
+      continue;
+    }
+    const raised = await raiseQuestions(root, [estateAskDraft(a)], {
+      step: ESTATE_TARGETS_STEP,
+      repo: a.from.repo,
+      command: "atticus estate join",
+      rerun: "atticus estate join",
+      at
+    });
+    const q = raised.of[0];
+    if (q?.state === "open")
+      asked.push({ q, raised: raised.raised.some((x) => x.id === q.id) });
+  }
+  const inferred = new Set(r.inferred.map((x) => estateStepKey(x.from.flow, x.from.step)));
+  const file = {
+    schemaVersion: 1,
+    joinedAt: (o.now ?? /* @__PURE__ */ new Date()).toISOString(),
+    repos: specs.map((s) => s.repo),
+    joins: r.joins,
+    unmatched: r.unmatched
+  };
+  const rel = await writeEstateJoins(root, file);
+  const hosts = await askHosts(root, records, {
+    command: "atticus estate join",
+    ...o.now ? { now: o.now } : {}
+  });
+  if (o.json) {
+    io.out(JSON.stringify({
+      ...file,
+      file: rel,
+      unchecked: [...unchecked].sort(),
+      inferred: r.inferred,
+      asks: r.asks,
+      questions: [...hosts.raised, ...hosts.open, ...asked.map((x) => x.q)].map((q) => q.id)
+    }, null, 2));
+    return 0;
+  }
+  const total = r.joins.length + r.unmatched.length;
+  io.out(`Joined ${r.joins.length} of ${plural(total, "call-out")} across ${plural(specs.length, "repo")} (${file.repos.join(", ")}); written to ${rel}.`);
+  for (const j of r.joins)
+    io.out(`  ${j.from.flow} step ${j.from.step} \u2192 ${j.to.flow} (${HOW[j.how]}${j.interface ? ` ${j.interface}` : ""}${inferred.has(estateStepKey(j.from.flow, j.from.step)) ? ", inferred" : ""})`);
+  if (r.unmatched.length) {
+    io.out(`${plural(r.unmatched.length, "call-out")} ${r.unmatched.length === 1 ? "isn't" : "aren't"} joined:`);
+    for (const u of r.unmatched)
+      io.out(`  ${u.from.flow} step ${u.from.step} (${REASON[u.reason]}): ${u.message}`);
+  }
+  if (unchecked.size)
+    io.out(`Cited lines of ${[...unchecked].sort().join(", ")} weren't checked: there is no clone of ${unchecked.size === 1 ? "it" : "them"} here.`);
+  if (r.inferred.length)
+    io.out(`${plural(r.inferred.length, "join is", "joins are")} inferred: ${r.inferred.length === 1 ? "its" : "their"} step names a target that isn't a component in the catalog (a relative call's guessed name, or none), so ${r.inferred.length === 1 ? "it" : "each"} joined the only entry point that serves its method and path, the caller's own repo first. When the repo is next read, a relative call leaves \`to\` out or names the component that serves it.`);
+  for (const { q, raised } of asked)
+    io.out(raised ? `Two or more components answer a call-out: asked ${q.id}: ${q.question} Answer it: atticus questions answer ${q.id} --option <n>, then atticus estate join.` : `Still open: ${q.question} Answer it: atticus questions answer ${q.id} --option <n>, then atticus estate join.`);
+  for (const l of hosts.lines)
+    io.out(l);
+  io.out("Next: atticus estate flow <flow-id> follows a flow across repos.");
+  return 0;
+}
+async function loadJoined(root, flowId, depth, io) {
+  const joins = await readEstateJoins(root);
+  if (!joins) {
+    io.err(`There is no ${specsRelOf(root)}/estate.yaml yet. Join the repos' flows first: atticus estate join.`);
+    return void 0;
+  }
+  const f = estateFlow({
+    flow: flowId,
+    specs: await readSpecs(root, io),
+    joins,
+    ...depth !== void 0 ? { depth } : {}
+  });
+  if (!f)
+    io.err(`There is no flow ${flowId} in ${specsRelOf(root)}/.`);
+  return f;
+}
+var cite = (s) => {
+  const e = s.step.evidence[0];
+  return e?.path ? `  [${e.repo ?? s.repo}:${e.path}${e.line !== void 0 ? `:${e.line}` : ""}]` : "";
+};
+var list = (xs) => xs.length ? xs.join(", ") : "nothing named";
+function render(f, indent, out) {
+  for (const s of f.steps) {
+    out.push(`${indent}${s.n} ${s.step.kind}: ${s.step.what}${cite(s)}`);
+    const c = s.call;
+    if (!c)
+      continue;
+    const pad = `${indent}  `;
+    if (c.join) {
+      const callee = c.callee?.flow;
+      out.push(`${pad}\u2192 ${c.join.to.flow}${callee ? `: ${callee.name}` : ""} (${c.join.to.repo}), ${HOW[c.join.how]}${c.join.interface ? ` ${c.join.interface}` : ""}`);
+      const x = c.crossing;
+      out.push(`${pad}  sends ${list(x.sends)}; the callee takes ${list(x.receives)}; returns ${list(x.returns)}`);
+      for (const m of x.objects)
+        out.push(`${pad}  ${m.sent} carries the callee's ${m.fields.join(", ")}`);
+      if (x.unused.length)
+        out.push(`${pad}  sent but not used by the callee: ${x.unused.join(", ")}`);
+      if (c.callee)
+        render(c.callee, pad, out);
+      else if (c.stopped === "cycle")
+        out.push(`${pad}  (not followed: ${c.join.to.flow} is already on the path)`);
+      else if (c.stopped === "depth")
+        out.push(`${pad}  (not followed: the depth limit; raise --depth)`);
+    } else if (c.unmatched)
+      out.push(`${pad}\u2717 not joined (${REASON[c.unmatched.reason]}): ${c.unmatched.message}`);
+    else
+      out.push(`${pad}\u2717 not joined yet: the specs changed since atticus estate join ran`);
+  }
+}
+async function estateFlowCommand(root, flowId, o, io) {
+  const f = await loadJoined(root, flowId, o.depth, io);
+  if (!f)
+    return 2;
+  if (o.json) {
+    io.out(JSON.stringify(f, null, 2));
+    return 0;
+  }
+  const t = f.flow.trigger;
+  const e = t.evidence[0];
+  const out = [
+    `${f.flow.id}: ${f.flow.name} (${f.repo})`,
+    `Trigger (${t.kind}): ${t.what}${e?.path ? `  [${e.repo ?? f.repo}:${e.path}${e.line !== void 0 ? `:${e.line}` : ""}]` : ""}`
+  ];
+  render(f, "", out);
+  for (const l of out)
+    io.out(l);
+  return 0;
+}
+async function estateLineage(root, flowId, field, o, io) {
+  const f = await loadJoined(root, flowId, o.depth, io);
+  if (!f)
+    return 2;
+  const l = fieldLineage(f, field);
+  if (o.json) {
+    io.out(JSON.stringify(l, null, 2));
+    return l.stored ? 0 : 1;
+  }
+  io.out(`${field} along ${flowId}:`);
+  for (const k of l.links)
+    io.out(`  ${k.n} ${k.kind}, ${k.as} ${k.field}: ${k.what}${k.evidence ? `  [${k.evidence}]` : ""}`);
+  io.out(l.stored ? `${field} is stored in ${l.stored.table}.${l.stored.column}.` : `The chain breaks: ${l.breaks.message}`);
+  return l.stored ? 0 : 1;
+}
+export {
+  ESTATE_TARGETS_NONE,
+  ESTATE_TARGETS_STEP,
+  estateAskDraft,
+  estateAskId,
+  estateFlowCommand,
+  estateJoin,
+  estateLineage
+};