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

package/dist/chunk-BQNEHB5U.js

@@ -0,0 +1,212 @@
+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 {
+  candidateAnnotations,
+  dialectFilePath,
+  exportKit,
+  formatGrade,
+  gradeDialect,
+  loadDialectFile,
+  runDialectOnRepo,
+  scaffoldDialect,
+  surveyRepos,
+  testDialect
+} from "./chunk-XKJRPVJO.js";
+import "./chunk-IILZ7J3L.js";
+import "./chunk-TEBBD4XH.js";
+import "./chunk-XPWSNKF3.js";
+import "./chunk-WIMOJMAK.js";
+import "./chunk-5V5BJACL.js";
+import {
+  SYNTAX_LANGUAGES,
+  syntaxLanguageOf,
+  syntaxOutline
+} from "./chunk-GVFUEGGM.js";
+import "./chunk-XZJE6WIT.js";
+import "./chunk-FMRMTI7W.js";
+import "./chunk-BKFGGJKA.js";
+import {
+  RecordId,
+  orgPackDirOf,
+  require_dist
+} from "./chunk-JMOLB347.js";
+import "./chunk-MMB2OHUY.js";
+import {
+  __toESM
+} from "./chunk-TV45EUGM.js";
+
+// packages/cli/dist/dialect-commands.js
+var import_yaml = __toESM(require_dist(), 1);
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+var plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+var shown = (root, file) => relative(root, file).split(sep).join("/");
+var isDir = (p) => stat(p).then((s) => s.isDirectory()).catch(() => false);
+async function dialectNew(root, name, repoDirs, io) {
+  if (!RecordId.safeParse(name).success) {
+    io.err('A dialect name is a lowercase slug (a-z, 0-9, ".", "_" and "-"), for example: forge-messaging');
+    return 2;
+  }
+  if (repoDirs.length === 0) {
+    io.err("dialect new needs at least one repo folder, for example: atticus dialect new house --from repos/a repos/b");
+    return 2;
+  }
+  const dirs = repoDirs.map((d) => resolve(d));
+  for (const d of dirs) {
+    if (!await isDir(d)) {
+      io.err(`${d} is not a folder.`);
+      return 2;
+    }
+  }
+  const file = join(orgPackDirOf(root), "dialects", `${name}.yaml`);
+  const existing = await dialectFilePath(join(orgPackDirOf(root)), name);
+  if (existing) {
+    io.err(`${shown(root, existing)} already exists; it was left as it is. Choose another name or edit that file.`);
+    return 1;
+  }
+  const survey = await surveyRepos(dirs);
+  await mkdir(join(orgPackDirOf(root), "dialects"), { recursive: true });
+  await writeFile(file, scaffoldDialect(name, survey), { encoding: "utf8", flag: "wx" });
+  const house = survey.annotations.filter((a) => !a.known).length;
+  io.out(`Wrote ${shown(root, file)} from ${plural(survey.repos.length, "repo")}: ${survey.marker ? `marker ${survey.marker}` : "no marker every repo has"}, ${plural(house, "framework annotation")}, ${plural(candidateAnnotations(survey).length, "candidate rule")}, ${plural(survey.configKeys.length, "config key")}.`);
+  io.out(`Next: finish the rules and write tests, then run atticus dialect test ${name}.`);
+  return 0;
+}
+async function load(root, name, io, allowNoTests) {
+  const file = await dialectFilePath(join(orgPackDirOf(root)), name);
+  if (!file) {
+    io.err(`No dialect file org-pack/dialects/${name}.yaml. Create one with: atticus dialect new ${name} --from <repo>...`);
+    return void 0;
+  }
+  const loaded = await loadDialectFile(file, { allowNoTests, checkFileName: true });
+  if (!loaded.dialect) {
+    const yamlProblem = loaded.problems.find((p) => p.path === "" && p.message.startsWith("not valid YAML"));
+    if (yamlProblem)
+      io.err(`${shown(root, file)} is ${yamlProblem.message}`);
+    else {
+      io.err(`${shown(root, file)} is not a valid dialect (contract C2):`);
+      for (const p of loaded.problems)
+        io.err(`  ${p.path ? `${p.path}: ` : ""}${p.message}`);
+    }
+    return void 0;
+  }
+  return loaded;
+}
+async function dialectTest(root, name, io) {
+  const loaded = await load(root, name, io, false);
+  if (!loaded)
+    return 1;
+  const d = loaded.dialect;
+  io.out(`Testing dialect ${d.name} ${d.version}: ${plural(d.rules.length, "rule")}, ${plural(d.tests.length, "test")}`);
+  const results = await testDialect(d, loaded.dir, loaded.parents);
+  for (const r of results) {
+    io.out(`  ${r.passed ? "pass" : "FAIL"}  ${r.name}`);
+    for (const f of r.failures)
+      io.out(`          ${f}`);
+  }
+  const failed = results.filter((r) => !r.passed).length;
+  if (failed === 0) {
+    io.out(`${plural(results.length, "test")} passed.`);
+    return 0;
+  }
+  io.out(`${failed} of ${plural(results.length, "test")} failed. To see what the rules produce from a repo: atticus dialect run ${d.name} <repo>`);
+  return 1;
+}
+function shownFields(record) {
+  const out = {
+    kind: record.kind,
+    id: record.id,
+    confidence: record.confidence
+  };
+  for (const [k, v] of Object.entries(record)) {
+    if (["kind", "id", "confidence", "schemaVersion", "status", "evidence"].includes(k))
+      continue;
+    if (Array.isArray(v) && v.length === 0)
+      continue;
+    if (v && typeof v === "object" && !Array.isArray(v) && Object.keys(v).length === 0)
+      continue;
+    out[k] = v;
+  }
+  return out;
+}
+async function dialectRun(root, name, repoDir, o, io) {
+  const dir = resolve(repoDir);
+  if (!await isDir(dir)) {
+    io.err(`${dir} is not a folder.`);
+    return 2;
+  }
+  const loaded = await load(root, name, io, true);
+  if (!loaded)
+    return 1;
+  const d = loaded.dialect;
+  const run = await runDialectOnRepo(d, loaded.parents, dir);
+  if (o.json) {
+    io.out(JSON.stringify({
+      applies: run.applies,
+      records: run.records.map((r) => r.record),
+      warnings: run.warnings,
+      rejected: run.rejected,
+      ...run.error ? { error: run.error } : {}
+    }, null, 2));
+    return run.rejected.length > 0 || run.error ? 1 : 0;
+  }
+  if (!run.applies) {
+    io.out(`The marker ${d.appliesTo.marker} is not in ${run.repo}, so the dialect does not apply there. 0 records.`);
+    return 0;
+  }
+  if (run.error)
+    io.err(`The dialect failed: ${run.error}`);
+  for (const { record, rule } of run.records) {
+    const fields = shownFields(record);
+    const lines = (0, import_yaml.stringify)([fields], { lineWidth: 0 }).trimEnd().split("\n");
+    for (const l of lines)
+      io.out(l);
+    const ev = record.evidence[0];
+    io.out(`  # from ${ev?.path ?? "?"}:${ev?.line ?? "?"}${rule ? ` (rule ${rule})` : ""}`);
+  }
+  for (const w of run.warnings)
+    io.out(`warning: ${w.message}${w.path ? ` (${w.path})` : ""}`);
+  for (const r of run.rejected) {
+    const rec = r.record;
+    const at = rec.evidence?.[0];
+    io.out(`invalid: ${rec.kind ?? "?"} ${rec.id ?? "?"} from ${at?.path ?? "?"}:${at?.line ?? "?"}: ${r.issues.map((i) => `${i.path ? `${i.path}: ` : ""}${i.message}`).join("; ")}`);
+  }
+  io.out(`${plural(run.records.length, "record")} from ${run.repo}.${loaded.noTests ? " This dialect has no tests yet; atticus dialect test fails until it has one." : ""}`);
+  return run.rejected.length > 0 || run.error ? 1 : 0;
+}
+async function dialectKit(outDir, io) {
+  const files = await exportKit(outDir);
+  io.out(`Wrote the dialect build kit (${files.length} files) to ${outDir}`);
+  return 0;
+}
+async function dialectGrade(file, evalDir, io) {
+  const g = await gradeDialect(resolve(file), resolve(evalDir));
+  for (const l of formatGrade(g))
+    io.out(l);
+  return g.pass ? 0 : 1;
+}
+async function dialectTree(file, o, io) {
+  const lang = o.language ?? syntaxLanguageOf(file);
+  if (!lang || !SYNTAX_LANGUAGES.includes(lang)) {
+    io.err(`No grammar for ${file}${o.language ? ` (${o.language})` : ""}. Grammars: ${SYNTAX_LANGUAGES.join(", ")}.`);
+    return 2;
+  }
+  const text = await readFile(resolve(file), "utf8").catch(() => void 0);
+  if (text === void 0) {
+    io.err(`${file} can't be read.`);
+    return 2;
+  }
+  io.out(await syntaxOutline(lang, text, Number.MAX_SAFE_INTEGER));
+  return 0;
+}
+export {
+  dialectGrade,
+  dialectKit,
+  dialectNew,
+  dialectRun,
+  dialectTest,
+  dialectTree
+};

package/dist/chunk-BUWSOQLU.js

@@ -0,0 +1,131 @@
+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 {
+  readCatalog
+} from "./chunk-IILZ7J3L.js";
+import {
+  VIEW_NAMES,
+  ViewError,
+  buildView,
+  shapeLibrary,
+  toDrawio,
+  toMermaid,
+  viewFromDiagram
+} from "./chunk-XPWSNKF3.js";
+import {
+  readDrawio
+} from "./chunk-5V5BJACL.js";
+import {
+  loadOrgPack,
+  orgPackDirOf
+} from "./chunk-JMOLB347.js";
+
+// packages/cli/dist/diagram-commands.js
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+async function loadCatalog(root, io) {
+  const op = await loadOrgPack(join(orgPackDirOf(root)));
+  const catalogDir = join(root, op.sources.layout.catalog);
+  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 legend = op.profiles[0]?.profile?.legend;
+  return {
+    records: [...generated.records, ...curated.records],
+    generated: generated.records.length,
+    ...legend ? { legend } : {}
+  };
+}
+async function emit(root, text, out, io) {
+  if (!out) {
+    io.out(text.replace(/\n$/, ""));
+    return;
+  }
+  const full = resolve(root, out);
+  await mkdir(dirname(full), { recursive: true });
+  await writeFile(full, text, "utf8");
+  io.out(`Wrote ${relative(root, full).split(sep).join("/")}.`);
+}
+async function diagramRender(root, o, io) {
+  const format = o.format ?? "mermaid";
+  if (format !== "mermaid" && format !== "drawio" && format !== "json") {
+    io.err(`Unknown format "${format}": use mermaid, drawio or json.`);
+    return 2;
+  }
+  if (/\.drawio(\.xml)?$/i.test(o.view)) {
+    if (format !== "mermaid") {
+      io.err("A diagram file renders as Mermaid only.");
+      return 2;
+    }
+    const full = resolve(root, o.view);
+    let xml;
+    try {
+      xml = await readFile(full, "utf8");
+    } catch {
+      io.err(`Can't read ${o.view}`);
+      return 2;
+    }
+    const op = await loadOrgPack(join(orgPackDirOf(root)));
+    const diagram = readDrawio(xml, op.profiles[0]?.profile?.legend);
+    for (const p of diagram.problems)
+      io.err(`cell ${p.cell}: ${p.message}`);
+    const view2 = viewFromDiagram(diagram, relative(root, full).split(sep).join("/"));
+    await emit(root, toMermaid(view2), o.out, io);
+    return 0;
+  }
+  if (!VIEW_NAMES.includes(o.view)) {
+    io.err(`Unknown view "${o.view}": use ${VIEW_NAMES.join(", ")}, or name a .drawio file to show it as Mermaid.`);
+    return 2;
+  }
+  const name = o.view;
+  if ((name === "container" || name === "sequence") && !o.focus) {
+    io.err(name === "container" ? "A container view needs a system: --focus <system>." : "A sequence view needs record ids in order: --focus <id>,<id>,...");
+    return 2;
+  }
+  if (name === "sequence" && format !== "mermaid") {
+    io.err("A sequence view renders as Mermaid only.");
+    return 2;
+  }
+  const { records, generated } = await loadCatalog(root, io);
+  if (generated === 0) {
+    io.err("The catalog is empty: read the repos first (atticus map <repo>, then atticus verify <repo> --write).");
+    return 1;
+  }
+  let view;
+  try {
+    view = buildView(records, name, o.focus);
+  } catch (e) {
+    if (e instanceof ViewError) {
+      io.err(e.message);
+      return 1;
+    }
+    throw e;
+  }
+  if (view.type !== "sequence" && view.nodes.length === 0) {
+    io.err(`Nothing to draw: the catalog has nothing for the ${name} view${o.focus ? ` of ${o.focus}` : ""}.`);
+    return 1;
+  }
+  if (format === "json" && view.type !== "sequence") {
+    await emit(root, JSON.stringify(view), o.out, io);
+    return 0;
+  }
+  await emit(root, view.type !== "sequence" && format === "drawio" ? toDrawio(view) : toMermaid(view), o.out, io);
+  return 0;
+}
+async function diagramLibrary(out, io) {
+  const full = resolve(out);
+  await mkdir(dirname(full), { recursive: true });
+  await writeFile(full, shapeLibrary(), "utf8");
+  io.out(`Wrote ${out}. In draw.io, open it with File > Open Library from > Device.`);
+  return 0;
+}
+
+export {
+  loadCatalog,
+  diagramRender,
+  diagramLibrary
+};

package/dist/chunk-BX52REMA.js

@@ -0,0 +1,134 @@
+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 {
+  targetFlowsOf
+} from "./chunk-JEUXCIRD.js";
+import {
+  estimateChange,
+  loadRelease,
+  releaseForecast
+} from "./chunk-7A7IG7OA.js";
+import {
+  gateStatus,
+  reviewedGates
+} from "./chunk-T6ESD5KM.js";
+import {
+  detectConflicts,
+  outsideSystemsOf
+} from "./chunk-3LU6YCSQ.js";
+import {
+  loadEstimates,
+  loadOrgPack,
+  orgPackDirOf
+} from "./chunk-JMOLB347.js";
+
+// packages/cli/dist/change-estimate.js
+import { relative, sep } from "node:path";
+async function estimateOf(root, change, o = {}) {
+  const t = await targetFlowsOf(root, change);
+  if (!t)
+    return void 0;
+  const problems = [...t.problems];
+  const { estimates, problem } = await loadEstimates(orgPackDirOf(root));
+  if (problem)
+    problems.push(problem);
+  const systems = /* @__PURE__ */ new Map();
+  const systemOf = /* @__PURE__ */ new Map();
+  for (const r of t.records) {
+    if (r.kind === "System")
+      systems.set(r.id, r.boundary);
+    if (r.kind === "Component")
+      systemOf.set(r.id, r.system);
+  }
+  const boundaryOf = (c) => systems.get(systemOf.get(c) ?? c);
+  const op = await loadOrgPack(orgPackDirOf(root)).catch(() => void 0);
+  const outside = op ? outsideSystemsOf(op) : /* @__PURE__ */ new Map();
+  const otherTeam = (c) => boundaryOf(c) !== "vendor" && outside.get(systemOf.get(c) ?? c) === "other-team";
+  let openBlocking = 0;
+  for (const gate of await reviewedGates(root, change).catch(() => []))
+    openBlocking += await gateStatus(root, change, gate).then((s) => s.open.blocking, () => 0);
+  const conflicts = (await detectConflicts(root).catch(() => [])).filter((p) => p.changes.includes(change)).length;
+  let waitDays;
+  try {
+    const f = await releaseForecast(await loadRelease(root, change, o.now ? { now: o.now } : {}));
+    if (f.status !== "released")
+      waitDays = f.waitDays;
+  } catch (e2) {
+    problems.push(`The release forecast couldn't be worked out: ${e2.message.split("\n")[0]}`);
+  }
+  const flows = t.merged.map((m) => ({
+    flow: m.flow,
+    repo: m.repo,
+    change: m.change,
+    trigger: m.trigger.kind,
+    file: `${t.source}/${m.flow}.yaml`,
+    steps: m.steps.map((s) => ({
+      mark: s.mark,
+      kind: s.kind,
+      ...s.today !== void 0 ? { today: s.today } : {},
+      ...s.target !== void 0 ? { target: s.target } : {},
+      ...s.what ? { what: s.what } : {},
+      ...s.to ? { to: s.to } : {},
+      ...s.store ? { store: s.store } : {},
+      ...s.confirmedBy ? { confirmedBy: s.confirmedBy } : {}
+    }))
+  }));
+  const e = estimateChange({
+    change,
+    flows,
+    ...estimates ? { table: estimates } : {},
+    boundaryOf,
+    otherTeam,
+    openBlocking,
+    conflicts,
+    ...waitDays !== void 0 ? { waitDays } : {}
+  });
+  return {
+    ...e,
+    title: t.title,
+    source: t.source,
+    ...estimates ? { table: `${relative(root, orgPackDirOf(root)).split(sep).join("/")}/estimates.yaml` } : {},
+    problems
+  };
+}
+var units = (n) => `${n} unit${n === 1 ? "" : "s"} of work`;
+var range = (d) => `${d.p20}-${d.p80} days (p50 ${d.p50})`;
+async function changeEstimateCommand(root, change, o, io) {
+  const e = await estimateOf(root, change, o.now ? { now: o.now } : {});
+  if (!e) {
+    io.err(`There is no change ${change}.`);
+    return 2;
+  }
+  if (o.json) {
+    io.out(JSON.stringify(e, null, 2));
+    return 0;
+  }
+  for (const p of e.problems)
+    io.err(p);
+  if (!e.units.length) {
+    io.err(`${change} has no target flows yet, so there is nothing to size: the architecture stage writes them (atticus change architecture ${change}).`);
+    return 1;
+  }
+  io.out(`Estimate for ${change}: ${e.title}`);
+  io.out(e.effort ? `Effort: ${range(e.effort)}, from ${e.units.length - e.needsClass} of ${units(e.units.length)}.` : `Size: ${units(e.units.length)}. No days: ${e.table ? "no class in the org pack's estimates.yaml matches them" : "the org pack has no estimates.yaml"}.`);
+  if (e.calendar.waitDays !== void 0)
+    io.out(`Waiting (the release forecast): ${e.calendar.waitDays} working days${e.calendar.longer ? `; the ${e.calendar.longer} is longer` : ""}.`);
+  io.out(e.calibration.source ? `Not calibrated yet: the ranges are ${e.calibration.source}'s, from ${e.table}.` : "Not calibrated yet.");
+  if (e.drivers.length) {
+    io.out("Drivers:");
+    for (const d of e.drivers)
+      io.out(`  ${d.what}: ${d.count}${d.widens ? ` (widens the upper end by ${d.widens}x)` : ""}${d.source ? `  ${d.source}` : ""}`);
+  }
+  io.out("Work:");
+  for (const u of e.units)
+    io.out(`  ${u.repo}  ${u.flow}${u.step !== void 0 ? ` step ${u.step}` : ""}  ${u.class}  ${u.days ? range(u.days) : "needs a class"}  ${u.what}`);
+  return 0;
+}
+
+export {
+  estimateOf,
+  changeEstimateCommand
+};

package/dist/chunk-BXBCMGIQ.js

@@ -0,0 +1,82 @@
+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));
+
+// packages/cli/dist/top-commands.js
+var TOP_WORDS = [
+  "init",
+  "map",
+  "verify",
+  "join",
+  "change",
+  "critic",
+  "stories",
+  "task",
+  "questions",
+  "knowledge",
+  "next",
+  "ui"
+];
+var TOP = new Set(TOP_WORDS);
+var isLegacy = (first) => !!first && !TOP.has(first) && first !== "legacy" && first !== "help";
+var TOP_HELP = `  atticus init <folder> --platform <p>  Start your team's metarepo (atticus adopt <path> uses Atticus inside one repo)
+  atticus map <repo>                    Your assistant reads a repo into facts, each citing its file and line (/atticus-map does it in one session)
+  atticus verify <repo> [--write]       Check the facts against the code; --write puts them in the catalog and renders the map
+  atticus join [--json]                 Follow flows from repo to repo through the calls the facts join; writes specs/estate.yaml
+  atticus change new "<title>"          Start a change; atticus help change lists its stages and the rest
+  atticus critic <change>               Review a change: rule checks, then four questions (is it true, complete, safe, can it ship)
+  atticus stories <change>              The stories stage: stories with acceptance criteria and tasks, from the design
+  atticus task <change> <task>          Run one task with your assistant: a plan, a draft or a pull request
+  atticus questions                     What Atticus needs a person to answer, and who can answer it
+  atticus knowledge scan                Read your wikis into patterns, standards, processes and decisions; atticus help knowledge lists the rest
+  atticus next                          The next step to take, its command and its slash command
+  atticus ui [--open]                   Open the app on this machine
+
+  atticus help <command>                What one command takes (atticus explain <command> says it in plain words)
+  atticus legacy                        Every other command (scan, plan, release, estate and more); each still runs by its own name
+  atticus help --all                    Every command, grouped by area`;
+function topHelp(versionLine) {
+  return [
+    versionLine,
+    "",
+    "Map a multi-repo estate from its code, then take each change from idea to code, with a person approving every gate.",
+    "",
+    TOP_HELP,
+    "",
+    "Every command also takes --root <dir> (the metarepo) and --by <handle> (who is acting)."
+  ].join("\n");
+}
+function aliasArgv(argv, positions) {
+  const out = [...argv];
+  let at = [...positions];
+  if (at.length > 1 && out[at[0]] === "legacy") {
+    out.splice(at[0], 1);
+    at = at.slice(1).map((i) => i - 1);
+  }
+  const first = at[0];
+  if (first === void 0)
+    return out;
+  const word = out[first];
+  const second = at[1] === void 0 ? void 0 : out[at[1]];
+  if (word === "join" && second === "measure")
+    out.splice(first, 2, "estate", "measure");
+  else if (word === "join" && second === "shared")
+    out.splice(first, 2, "estate", "shared");
+  else if (word === "join" && second === "contracts")
+    out.splice(first, 2, "estate", "contracts");
+  else if (word === "join")
+    out.splice(first, 1, "estate", "join");
+  else if (word === "stories")
+    out.splice(first, 1, "plan", "stories");
+  else if (word === "task" && second !== "run" && second !== "context")
+    out.splice(first + 1, 0, "run");
+  return out;
+}
+
+export {
+  isLegacy,
+  topHelp,
+  aliasArgv
+};