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

package/dist/chunk-GR6YKM55.js

@@ -0,0 +1,480 @@
+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 {
+  routeQuestions
+} from "./chunk-B7434AE2.js";
+import {
+  waitingQuestions
+} from "./chunk-RK6MKKKP.js";
+import {
+  gitUser
+} from "./chunk-PGKHJYOB.js";
+import {
+  HOSTS_STEP,
+  QuestionError,
+  QuestionScopeLevel,
+  QuestionState,
+  TARGETS_STEP_ID,
+  acceptProposal,
+  answerQuestion,
+  answerWords,
+  changesDirOf,
+  checkedProposals,
+  external_exports,
+  listQuestions,
+  proposalOf,
+  proposalsRelOf,
+  questionsRelOf,
+  readQuestion,
+  require_dist
+} from "./chunk-577AJVRS.js";
+import {
+  writeFileAtomic
+} from "./chunk-D3PO4DOZ.js";
+import {
+  __toESM
+} from "./chunk-TV45EUGM.js";
+
+// packages/cli/dist/question-commands.js
+import { readFile, stat } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+
+// packages/cli/dist/question-sheet.js
+var import_yaml = __toESM(require_dist(), 1);
+import { createHash } from "node:crypto";
+var SHEET_VERSION = 1;
+function askedFingerprint(q) {
+  const key = JSON.stringify([
+    q.question.trim(),
+    q.options.map((o) => [o.label, o.means, o.changes]),
+    [...q.evidence].sort(),
+    q.scope,
+    q.state
+  ]);
+  return createHash("sha256").update(key).digest("hex").slice(0, 16);
+}
+var RULE_STEPS = /* @__PURE__ */ new Set([TARGETS_STEP_ID, HOSTS_STEP]);
+var sentence = (s) => /[.!?]$/.test(s.trim()) ? s.trim() : `${s.trim()}.`;
+function answerSheet(questions, at) {
+  const open = questions.filter((q) => q.state === "open");
+  const doc = {
+    schemaVersion: SHEET_VERSION,
+    written: at,
+    questions: open.map((q) => ({
+      id: q.id,
+      repo: q.repo,
+      question: q.question.trim(),
+      ...q.options.length ? {
+        options: q.options.map((o, i) => `${i + 1}. ${o.label}: ${sentence(o.means)} It would change: ${sentence(o.changes)}`)
+      } : {},
+      evidence: q.evidence,
+      scope: q.scope.level === "repo" ? "repo" : `repo-type ${q.scope.id}`,
+      asked: askedFingerprint(q),
+      answer: null,
+      ...RULE_STEPS.has(q.askedBy.step) ? { match: null } : {}
+    }))
+  };
+  return [
+    "# Atticus answer sheet (ADR 0153): every open question, to answer in one sitting.",
+    "# Fill in answer: with an option's number, or your own words in quotes. Leave it empty to skip.",
+    "# Optional per entry: scope: repo | repo-type (with type: <repo type>), and for a target or",
+    '# hosts question match: "<host pattern or /path/**>" so one answer covers every call it matches.',
+    "# Then: atticus questions sheet --apply <this file>. It answers as you, through the question files;",
+    "# this sheet is a working file: don't commit it.",
+    (0, import_yaml.stringify)(doc, { lineWidth: 0 })
+  ].join("\n");
+}
+var Entry = external_exports.object({
+  id: external_exports.string(),
+  asked: external_exports.string().optional(),
+  answer: external_exports.union([external_exports.number(), external_exports.string(), external_exports.null()]).optional(),
+  scope: external_exports.string().nullable().optional(),
+  type: external_exports.string().nullable().optional(),
+  match: external_exports.string().nullable().optional()
+});
+var Sheet = external_exports.object({
+  schemaVersion: external_exports.literal(SHEET_VERSION),
+  questions: external_exports.array(external_exports.unknown())
+});
+async function applySheet(root, text, o) {
+  let data;
+  try {
+    data = (0, import_yaml.parse)(text);
+  } catch (e) {
+    return { outcomes: [], problem: `It doesn't read: ${e.message.split("\n")[0]}` };
+  }
+  const sheet = Sheet.safeParse(data);
+  if (!sheet.success)
+    return {
+      outcomes: [],
+      problem: "It isn't an answer sheet Atticus wrote (schemaVersion 1, with questions): write one with atticus questions sheet."
+    };
+  const outcomes = [];
+  for (const [i, raw] of sheet.data.questions.entries()) {
+    const e = Entry.safeParse(raw);
+    if (!e.success) {
+      outcomes.push({
+        id: `entry ${i + 1}`,
+        status: "refused",
+        why: "it has no question id; leave the sheet's ids as they were written"
+      });
+      continue;
+    }
+    const { id } = e.data;
+    const given = e.data.answer;
+    if (given === void 0 || given === null || typeof given === "string" && !given.trim()) {
+      outcomes.push({ id, status: "skipped", why: "left blank" });
+      continue;
+    }
+    const q = await readQuestion(root, id).catch(() => void 0);
+    if (!q) {
+      outcomes.push({ id, status: "refused", why: `there is no question ${id}` });
+      continue;
+    }
+    if (q.state !== "open") {
+      outcomes.push({
+        id,
+        status: "skipped",
+        why: `it is ${q.state} already${q.answer ? ` (${answerWords(q)}, by ${q.answer.by})` : ""}`
+      });
+      continue;
+    }
+    if (e.data.asked !== askedFingerprint(q)) {
+      outcomes.push({
+        id,
+        status: "refused",
+        why: "the question changed since the sheet was written (its words, options or evidence): write a new sheet and read it again"
+      });
+      continue;
+    }
+    const scope = e.data.scope?.trim().split(/\s+/)[0];
+    if (scope && !QuestionScopeLevel.safeParse(scope).success) {
+      outcomes.push({
+        id,
+        status: "refused",
+        why: "scope is repo (this repo only) or repo-type (every repo of its type)"
+      });
+      continue;
+    }
+    const option = typeof given === "number" ? given : /^\s*\d+\s*$/.test(given) ? Number(given) : void 0;
+    const typeFromScope = e.data.scope?.trim().split(/\s+/)[1];
+    const repoType = e.data.type?.trim() || typeFromScope;
+    const match = e.data.match?.trim() || void 0;
+    try {
+      const r = await answerQuestion(root, id, {
+        ...option !== void 0 ? { option } : { text: String(given) },
+        ...scope ? { scope } : {},
+        ...repoType ? { repoType } : {},
+        ...match ? { match } : {},
+        by: o.by,
+        at: o.at
+      });
+      outcomes.push({
+        id,
+        status: "answered",
+        answer: answerWords(r.question) ?? "",
+        question: r.question,
+        rerun: r.question.rerun
+      });
+    } catch (x) {
+      if (!(x instanceof QuestionError))
+        throw x;
+      outcomes.push({ id, status: "refused", why: x.message });
+    }
+  }
+  return { outcomes };
+}
+
+// packages/cli/dist/question-commands.js
+var RULE_STEPS2 = /* @__PURE__ */ new Set([TARGETS_STEP_ID, HOSTS_STEP]);
+var plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+var sentence2 = (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 aboutLines(about) {
+  if (!about)
+    return [];
+  const o = about.owner;
+  return [
+    "team" in o ? `  Owner: ${o.team}${o.name ? ` (${o.name})` : ""}` : "change" in o ? `  Owner: the people of ${o.change}: ${o.people.join(", ")}` : `  Owner: none (${o.none})`,
+    ...about.restsOn.length ? [
+      `  Ask it first: ${about.restsOn.join(", ")} ${about.restsOn.length === 1 ? "is a change in flight that rests" : "are changes in flight that rest"} on it.`
+    ] : [],
+    ...about.joins ? [`  Its answer joins ${plural(about.joins, "call")}.`] : []
+  ];
+}
+function proposalLines(q, p) {
+  const what = p.answer.option !== void 0 ? `option ${p.answer.option}, ${q.options[p.answer.option - 1]?.label ?? "?"}` : `"${p.answer.text}"`;
+  return [
+    `  Proposed by ${p.by} (not answered yet): ${what}. ${sentence2(p.why)}`,
+    ...p.cites.map((c) => `    Cites ${c.repo ?? q.repo} ${c.file}:${c.line}: "${c.quote}" (checked: it is on that line)`),
+    `  Accept it as your answer: atticus questions answer ${q.id} --accept-proposal`
+  ];
+}
+function ruleLine(q, change = false) {
+  const a = q.answer;
+  const where = a.scope.level === "repo" ? `${change ? "this change" : "this repo"}, ${a.scope.id}` : scopeWords(a.scope);
+  const what = a.match.startsWith("/") ? `whose path is under ${a.match}` : `on a host matching ${a.match}`;
+  return `It answers by rule: every call ${what}, in ${where}, reads this answer, the calls found later too.`;
+}
+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}`,
+    ...aboutLines(o.about),
+    ...q.options.map((o2, i) => `  ${i + 1}. ${o2.label}: ${sentence2(o2.means)} It would change: ${sentence2(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)})${q.answer.match ? `, by rule: ${q.answer.match}` : ""}`, ...q.answer.proposal ? [
+      `  It was ${q.answer.proposal.by}'s proposal (${q.answer.proposal.at.slice(0, 10)}), confirmed by ${q.answer.by}; it cited ${q.answer.proposal.cites.map((c) => `${c.repo ?? q.repo} ${c.file}:${c.line}`).join(", ")}.`
+    ] : []);
+  else if (q.state === "open")
+    lines.push(...o.about?.proposal ? proposalLines(q, o.about.proposal) : [], `  Proposed scope: ${scopeWords(q.scope, false, o.change)}`, `  Answer: atticus questions answer ${q.id}${q.options.length ? " --option <n>, or" : ""} --text "your own words"${RULE_STEPS2.has(q.askedBy.step) ? ' (add --match "<host pattern or /path/**>" for every call it covers)' : ""}`);
+  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" },
+      mine: { type: "boolean" },
+      "accept-proposal": { type: "boolean" },
+      match: { type: "string" },
+      apply: { type: "string" },
+      out: { 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 listed = await listQuestions(root, state ? { state } : {});
+    for (const p of listed.problems)
+      io.err(`${p.file} isn't a valid question: ${p.message}`);
+    const mine = values.mine === true ? str(values.by)?.trim() || (await gitUser(root)).handle : void 0;
+    const routed = await routeQuestions(root, listed.questions, mine ? { mine } : {});
+    for (const p of routed.problems)
+      io.err(`${p.file}: ${p.message}`);
+    const r = { ...listed, questions: routed.questions };
+    const waiting = !state || state === "open" ? await waitingQuestions(root) : [];
+    if (values.json === true) {
+      io.out(JSON.stringify({ ...r, about: routed.about, ...routed.me ? { me: routed.me } : {}, waiting }, null, 2));
+      return r.problems.length ? 1 : 0;
+    }
+    if (routed.me)
+      io.out(routed.me.teams.length ? `The questions for ${routed.me.handle}'s ${routed.me.teams.length === 1 ? "team" : "teams"}: ${routed.me.teams.map((t) => t.name ? `${t.id} (${t.name})` : t.id).join(", ")}.` : r.questions.length ? `The questions of the changes that name ${routed.me.handle} under owners in change.yaml; ${routed.me.handle} is on no team in org-pack/roles.yaml.` : `${routed.me.handle} is on no team in org-pack/roles.yaml and no change names them under owners, so no question is theirs: add them under a team's people (roles.yaml schemaVersion 2), or list every question without --mine.`);
+    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), about: routed.about[q.id] }))
+        io.out(l);
+    const what = state ? `${state} ` : "";
+    const yours = routed.me ? " for your teams" : "";
+    io.out(r.questions.length ? `${plural(r.questions.length, `${what}question`)}${yours}.` : `No ${what}questions${yours}.`);
+    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;
+    }
+    const p = q.state === "open" ? await proposalOf(root, q.id) : void 0;
+    const proposal = p?.ok && p.proposal ? { ...p.proposal, file: p.file } : void 0;
+    if (values.json === true)
+      io.out(JSON.stringify(proposal ? { ...q, proposal } : q, null, 2));
+    else {
+      const routed = await routeQuestions(root, [q]);
+      const about = routed.about[q.id];
+      for (const l of questionLines(q, {
+        change: await isChange(root, q.repo),
+        ...about ? { about: { ...about, ...proposal ? { proposal } : {} } } : {}
+      }))
+        io.out(l);
+      if (p && !p.ok && !p.stale)
+        io.out(`  A proposed answer is on file (${p.file}) but doesn't check, so it isn't shown: ${p.problems.join(" ")}`);
+    }
+    return 0;
+  }
+  if (command === "proposed") {
+    const all = await checkedProposals(root);
+    const dir = `${proposalsRelOf(root)}/questions`;
+    if (values.json === true) {
+      io.out(JSON.stringify({ dir, proposals: all }, null, 2));
+      return all.some((p) => !p.ok && !p.stale) ? 1 : 0;
+    }
+    if (!all.length) {
+      io.out(`No proposed answers yet. /atticus-propose writes one per open question to ${dir}/<question id>.yaml.`);
+      return 0;
+    }
+    for (const p of all) {
+      if (p.ok)
+        io.out(`${p.id}  checked: every line it cites says what it quotes (${p.file}).`);
+      else if (p.stale)
+        io.out(`${p.id}  nothing to propose: ${p.problems.join(" ")}`);
+      else {
+        io.out(`${p.id}  doesn't check, so nobody sees it (${p.file}):`);
+        for (const x of p.problems)
+          io.out(`  ${x}`);
+      }
+    }
+    const bad = all.filter((p) => !p.ok && !p.stale).length;
+    const ok = all.filter((p) => p.ok).length;
+    io.out(bad ? `${plural(bad, "proposal")} ${bad === 1 ? "doesn't" : "don't"} check: fix each citation from the file's line, or remove the proposal.` : `${plural(ok, "proposal")} checked. A person accepts each with atticus questions answer <id> --accept-proposal, or on the Questions page.`);
+    return bad ? 1 : 0;
+  }
+  if (command === "sheet") {
+    const at = (deps.now ?? /* @__PURE__ */ new Date()).toISOString();
+    const apply = str(values.apply);
+    if (apply !== void 0) {
+      const file2 = isAbsolute(apply) ? apply : resolve(apply);
+      const text = await readFile(file2, "utf8").catch(() => void 0);
+      if (text === void 0) {
+        io.err(`There is no answer sheet at ${apply}: write one with atticus questions sheet.`);
+        return 1;
+      }
+      const by = str(values.by)?.trim() || (await gitUser(root)).handle;
+      const r = await applySheet(root, text, { by, at });
+      if (r.problem) {
+        io.err(`${apply} can't be applied: ${r.problem}`);
+        return 2;
+      }
+      if (values.json === true) {
+        io.out(JSON.stringify(r, null, 2));
+        return r.outcomes.some((x) => x.status === "refused") ? 1 : 0;
+      }
+      for (const x of r.outcomes)
+        io.out(x.status === "answered" ? `Answered ${x.id}: ${x.answer} (as ${by}${x.question.answer?.match ? `, by rule: ${x.question.answer.match}` : ""}).` : x.status === "skipped" ? `Skipped ${x.id}: ${x.why}.` : `Refused ${x.id}: ${sentence2(x.why)}`);
+      const done = r.outcomes.filter((x) => x.status === "answered");
+      const refused = r.outcomes.filter((x) => x.status === "refused").length;
+      const skipped = r.outcomes.filter((x) => x.status === "skipped").length;
+      io.out(`${plural(done.length, "question")} answered, ${skipped} skipped, ${refused} refused. Wrote each answer to ${questionsRelOf(root)}/<id>.yaml; commit them for review.`);
+      const reruns = [...new Set(done.map((x) => x.status === "answered" ? x.rerun : ""))].filter(Boolean);
+      for (const rerun of reruns)
+        io.out(`Next: ${rerun}`);
+      return refused ? 1 : 0;
+    }
+    const open = (await listQuestions(root, { state: "open" })).questions;
+    const routed = await routeQuestions(root, open);
+    const out = str(values.out) ?? "questions-sheet.yaml";
+    const file = isAbsolute(out) ? out : join(root, out);
+    await writeFileAtomic(file, answerSheet(routed.questions, at));
+    io.out(open.length ? `Wrote ${plural(open.length, "open question")} to ${out}, in the order to ask them. Fill in the answers you know, leave the rest empty, then run: atticus questions sheet --apply ${out}` : `No open questions: wrote an empty sheet to ${out}.`);
+    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;
+    const accept = values["accept-proposal"] === true;
+    if (accept && (opt !== void 0 || text !== void 0)) {
+      io.err("--accept-proposal takes the proposed answer: give it alone, or answer with --option or --text instead.");
+      return 2;
+    }
+    if (!accept && 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 at = (deps.now ?? /* @__PURE__ */ new Date()).toISOString();
+      const match = str(values.match)?.trim() || void 0;
+      const scoped = {
+        ...scope ? { scope } : {},
+        ...str(values.type) ? { repoType: str(values.type) } : {},
+        // ADR 0153 (Q2): the rule the answer covers, for a target or hosts question.
+        ...match ? { match } : {}
+      };
+      const r = accept ? await acceptProposal(root, id, { ...scoped, by, at }) : await answerQuestion(root, id, {
+        ...option !== void 0 ? { option } : {},
+        ...text !== void 0 ? { text } : {},
+        ...scoped,
+        by,
+        at
+      });
+      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 (accept)
+        io.out(`It was the assistant's proposal; you accepted it, so it is recorded as answered by ${q.answer.by}, with the proposal it came from.`);
+      if (q.answer.match)
+        io.out(ruleLine(q, await isChange(root, q.repo)));
+      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}${r.hosts.basePath ? `, with basePath ${r.hosts.basePath},` : ""} 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}.`);
+      if (r.covered?.length)
+        io.out(`The rule answers ${plural(r.covered.length, "more open question")} too, retired as answered by it: ${r.covered.join(", ")}.`);
+      if (r.system)
+        io.out(r.system.added ? `Wrote the system ${r.system.id} (boundary ${r.system.boundary}, alias ${r.system.host}) into ${r.system.profile}, so the calls to ${r.system.host} go to it; review it in the same pull request, and give it a better name and an owner there if you like.` : `${r.system.profile} already has ${r.system.id}, which names ${r.system.host}.`);
+      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, proposed, answer or sheet (atticus questions alone lists the knowledge gaps).`);
+  io.err('Usage: atticus questions list [--state open|answered|retired] [--mine] [--json], atticus questions show <id> [--json], atticus questions proposed [--json], or atticus questions answer <id> --option <n> | --text "..." | --accept-proposal [--scope repo|repo-type] [--type <repo type>] [--match <host pattern or /path/**>], or atticus questions sheet [--out <file>] | --apply <file>');
+  return 2;
+}
+export {
+  aboutLines,
+  proposalLines,
+  questionLines,
+  questionsFiles,
+  ruleLine,
+  scopeWords
+};