codetrellis 0.0.0-stage → 0.3.0

package/src/shared/lib/signal-words.js

@@ -0,0 +1,172 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var signal_words_exports = {};
+__export(signal_words_exports, {
+  briefLine: () => briefLine,
+  kindWords: () => kindWords,
+  sideRootsOf: () => sideRootsOf,
+  sideWords: () => sideWords
+});
+module.exports = __toCommonJS(signal_words_exports);
+function kindWords(s) {
+  if (s.kind === "version-split") return "Different versions";
+  if (s.kind === "state-split") return s.subject.said?.some((c) => c.forged) ? "A record in someone else's name" : "Set two ways at once";
+  if (s.subject.material) {
+    if (s.kind === "contract") return "Changed material";
+    if (s.kind === "stale-base") return "Material changed";
+    if (s.kind === "collision") return "Same output";
+    if (s.kind === "drift") return "Outside its brief";
+  }
+  if (s.kind === "stale-base") return "Behind main";
+  if (s.kind === "rule") return "Breaks a rule";
+  if (s.kind === "drift") return "Outside its scope";
+  if (s.kind === "contract") return s.subject.change === "removed" ? "Removed export" : "Changed signature";
+  const declared = s.subject.intended?.length ? " \xB7 declared" : "";
+  return (s.subject.symbol ? "Same function" : "Same file") + declared;
+}
+function sideRootsOf(s) {
+  return (s.kind === "contract" || s.kind === "drift" && s.subject.material) && s.subject.by ? [s.subject.by, ...s.workstreams.filter((r) => r !== s.subject.by)] : [...s.workstreams];
+}
+const count = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+const STATUS_WORDS = { pending: "not started", assigned: "assigned", in_progress: "in progress", blocked: "blocked", done: "done", skipped: "skipped" };
+const statusWords = (status) => STATUS_WORDS[status ?? "pending"] ?? "not started";
+function about(s) {
+  if (s.subject.file && s.subject.symbol) return `${s.subject.symbol} in ${s.subject.file}`;
+  return s.subject.file ?? (s.subject.files ?? []).join(", ");
+}
+function sideWords(s, label) {
+  if (s.kind === "state-split") {
+    const root = s.workstreams[0];
+    const task = s.subject.labels?.[root] ?? label(root);
+    return (s.subject.said ?? []).map((c) => ({
+      root,
+      name: c.name,
+      words: c.forged ? `A record claiming to be ${c.name}'s sets \u201C${task}\u201D to ${statusWords(c.status)}; another record claims to be the same change.` : `${c.name} set \u201C${task}\u201D to ${statusWords(c.status)}, without having seen the other change.`
+    }));
+  }
+  const roots = sideRootsOf(s);
+  return roots.map((root, i) => {
+    const name = s.subject.labels?.[root] ?? label(root);
+    if (s.subject.material) return { root, name, words: materialWords(s, root, name) };
+    const declared = s.subject.intended?.includes(root);
+    if (s.kind === "contract") {
+      if (i === 0) {
+        if (s.subject.change === "removed") return { root, name, words: `${name} removed ${s.subject.symbol ?? "an export"} from ${s.subject.file ?? "a shared file"}.` };
+        const sig = s.subject.signature;
+        const change = sig ? `: ${s.subject.symbol}${sig.before} is now ${s.subject.symbol}${sig.after}` : "";
+        return { root, name, words: `${name} changed ${s.subject.symbol ?? "an export"}'s signature in ${s.subject.file ?? "a shared file"}${change}.` };
+      }
+      const importers = s.subject.importers ?? [];
+      const where = importers.length ? `, in ${count(importers.length, "file")}: ${importers.slice(0, 3).join(", ")}${importers.length > 3 ? " and more" : ""}` : "";
+      return { root, name, words: `${name} ${s.subject.possibly ? "possibly imports" : "imports"} it${where}.` };
+    }
+    if (s.kind === "drift") {
+      const files = s.subject.files ?? [];
+      return { root, name, words: `${name} changes ${count(files.length, "file")} outside the task it claimed: ${files.slice(0, 3).join(", ")}${files.length > 3 ? " and more" : ""}.` };
+    }
+    if (s.kind === "stale-base") {
+      return { root, name, words: `main changed ${about(s)} since ${name} branched, and ${name} changes it too.` };
+    }
+    if (s.kind === "rule") {
+      const edges = s.subject.edges ?? [];
+      const shown = edges.slice(0, 3).map((e) => `${e.from} \u2192 ${e.to}`).join(", ") + (edges.length > 3 ? " and more" : "");
+      const rule = s.subject.rule;
+      return { root, name, words: `${name} adds ${count(edges.length, "import")} the rule \u201C${rule?.words ?? "an architecture rule"}\u201D forbids${rule?.because ? ` (${rule.because})` : ""}: ${shown}.` };
+    }
+    return { root, name, words: `${name} ${declared ? "has said it will change" : "changes"} ${about(s)}.` };
+  });
+}
+function materialWords(s, root, task) {
+  const m = s.subject.material;
+  const who = s.subject.readBy?.[root];
+  const name = who ? `${task} (${who})` : task;
+  switch (s.kind) {
+    case "contract": {
+      if (!s.subject.citedBy?.includes(root)) return `${name} uses ${m}.`;
+      const parts = s.subject.parts ?? [];
+      const what = parts.length ? `${parts.slice(0, 3).join(", ")}${parts.length > 3 ? " and more" : ""} of ${m}` : m;
+      const signed = s.subject.signedOff?.includes(root) ? ", and a person already signed that off" : "";
+      return `${name} cites ${what}, as it was before it changed${signed}.`;
+    }
+    case "version-split":
+      return s.subject.readVersions?.[root] === "current" ? `${name} read the current version of ${m}.` : `${name} read an earlier version of ${m}.`;
+    case "stale-base":
+      return `${name} read ${m} before it changed, and has not read it since.`;
+    case "collision":
+      return `${name} records ${m} as its output.`;
+    case "drift": {
+      if (root !== s.subject.by) return `${name} was given it.`;
+      const files = s.subject.files ?? [m];
+      return `${name} read ${files.slice(0, 3).join(", ")}${files.length > 3 ? " and more" : ""}, which its brief does not include.`;
+    }
+    default:
+      return `${name} uses ${m}.`;
+  }
+}
+const namesOf = (s, ids) => {
+  const names = ids.map((id) => `\u201C${s.subject.labels?.[id] ?? id}\u201D${s.subject.readBy?.[id] ? ` (${s.subject.readBy[id]})` : ""}`);
+  return names.length <= 2 ? names.join(" and ") : `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
+};
+function briefLine(s, root, opts = {}) {
+  const name = opts.file ?? ((p) => p);
+  const m = name(s.subject.material ?? s.subject.file ?? "a file");
+  const others = s.workstreams.filter((w) => w !== root);
+  const verb = (ids, one, many) => ids.length === 1 ? one : many;
+  switch (s.kind) {
+    case "contract": {
+      const citers = s.subject.citedBy ?? [];
+      const parts = (s.subject.parts ?? []).join(", ") || "it";
+      const signed = s.subject.signedOff ?? [];
+      const mine = citers.includes(root);
+      const otherCiters = citers.filter((c) => c !== root);
+      const head = mine ? `${m} changed since this task cited ${parts}.` : `${m} changed since ${namesOf(s, otherCiters)} cited ${parts}.`;
+      const signedWords = signed.length === 0 ? "" : signed.includes(root) ? " A person had already signed this task's citation off." : ` ${namesOf(s, signed)} had already been signed off.`;
+      const also = mine ? others.length ? ` ${namesOf(s, others)} ${verb(others, "uses", "use")} it too.` : "" : " This task uses it too.";
+      return `${head}${signedWords}${also}`;
+    }
+    case "version-split": {
+      const versions = s.subject.readVersions ?? {};
+      const current = others.filter((o) => versions[o] === "current");
+      const earlier = others.filter((o) => versions[o] !== "current");
+      if (versions[root] === "current") {
+        return `This task read the current ${m}; ${namesOf(s, earlier)} worked from an earlier version.`;
+      }
+      return current.length ? `This task worked from an earlier version of ${m}; ${namesOf(s, current)} ${verb(current, "has", "have")} the current one.` : `This task and ${namesOf(s, others)} worked from different earlier versions of ${m}; it has changed since.`;
+    }
+    case "stale-base":
+      return `${m} changed after this task and ${namesOf(s, others)} read it.`;
+    case "state-split":
+      return (s.subject.said ?? []).map((c) => `${c.name}${c.forged ? " (claimed)" : ""} set this task to ${statusWords(c.status)}`).join("; ") + ", at once.";
+    case "collision":
+      return `This task and ${namesOf(s, others)} both record ${m} as their output.`;
+    case "drift": {
+      const files = (s.subject.files ?? [s.subject.material ?? m]).map(name).join(", ");
+      if (s.subject.by === root) return `This task read ${files}, which ${namesOf(s, others)} ${verb(others, "was", "were")} given, not this task.`;
+      return `${namesOf(s, s.subject.by ? [s.subject.by] : others)} read ${m}, which this task was given.`;
+    }
+    default:
+      return `${m} is used by this task and ${namesOf(s, others)}.`;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  briefLine,
+  kindWords,
+  sideRootsOf,
+  sideWords
+});

package/src/shared/lib/signoff.js

@@ -0,0 +1,56 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var signoff_exports = {};
+__export(signoff_exports, {
+  decisionWords: () => decisionWords,
+  evidenceWords: () => evidenceWords,
+  stateWords: () => stateWords
+});
+module.exports = __toCommonJS(signoff_exports);
+function stateWords(row) {
+  switch (row.state) {
+    case "met":
+      return row.selfApproved ? "met (agent-checked)" : row.unverified ? "met (unverified)" : "met";
+    case "submitted":
+      return "waiting for sign-off";
+    case "sent_back":
+      return "sent back";
+    case "stale":
+      return "changed since approved";
+    default:
+      return "not started";
+  }
+}
+const date = (ms) => new Date(ms).toISOString().slice(0, 16).replace("T", " ") + " UTC";
+function decisionWords(row) {
+  const d = row.decision;
+  if (!d) return "\u2014";
+  const verb = d.decision === "approved" ? row.selfApproved ? "self-approved by" : "approved by" : "sent back by";
+  const how = d.channel === "mcp" ? "over MCP" : d.channel === "local-api" ? "through the local API (unverified: not the app or a paired phone)" : `on the ${d.channel}${d.device ? ` (${d.device})` : ""}`;
+  return `${verb} ${d.actor} ${how}, ${date(d.at)}`;
+}
+function evidenceWords(row) {
+  if (row.evidence.length === 0) return "\u2014";
+  return row.evidence.map((e) => e.path ? `${e.path.split("/").pop()}${e.where ? ` (${e.where})` : ""}` : "note").join("; ");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  decisionWords,
+  evidenceWords,
+  stateWords
+});

package/src/shared/lib/skills-note.js

@@ -0,0 +1,60 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var skills_note_exports = {};
+__export(skills_note_exports, {
+  agentSkillsOf: () => agentSkillsOf,
+  skillsNote: () => skillsNote
+});
+module.exports = __toCommonJS(skills_note_exports);
+function whereText(w) {
+  switch (w.kind) {
+    case "repo":
+      return `\`${w.path}\``;
+    case "plugin":
+      return `the ${w.name} plugin`;
+    case "mcp":
+      return `the ${w.server} MCP server's tools`;
+    case "playbook":
+      return `CodeTrellis playbook ${w.uid}`;
+  }
+}
+function skillsNote(skills) {
+  if (skills.length === 0) return null;
+  const parts = skills.map((s) => {
+    let t = `${s.use === "required" ? "required: " : "use "}**${s.name}**`;
+    if (s.where) t += ` (${whereText(s.where)})`;
+    if (s.why) t += `, because ${s.why.replace(/^because\s+/i, "").replace(/\.$/, "")}`;
+    if (s.missing) t += ` (missing: ${s.missing})`;
+    return t;
+  });
+  return `Skills for this task: ${parts.join("; ")}.`;
+}
+function agentSkillsOf(skills) {
+  return skills.filter((s) => s.required || s.use === "recommended").map((s) => ({
+    name: s.name,
+    use: s.required ? "required" : "recommended",
+    why: s.why ?? null,
+    where: s.where && s.where.kind !== "link" ? s.where : null,
+    missing: null
+  }));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  agentSkillsOf,
+  skillsNote
+});

package/src/shared/lib/spec-sections.js

@@ -0,0 +1,78 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var spec_sections_exports = {};
+__export(spec_sections_exports, {
+  findSection: () => findSection,
+  headingSlug: () => headingSlug,
+  sectionText: () => sectionText,
+  specSections: () => specSections,
+  withSectionText: () => withSectionText
+});
+module.exports = __toCommonJS(spec_sections_exports);
+function headingSlug(text) {
+  return text.toLowerCase().replace(/[`*_~[\]()<>]/g, " ").replace(/[^\p{L}\p{N}\s-]/gu, "").trim().replace(/[\s-]+/g, "-");
+}
+function specSections(body) {
+  const lines = (body ?? "").split("\n");
+  const found = [];
+  let fence = null;
+  lines.forEach((line, i) => {
+    const f = /^\s{0,3}(`{3,}|~{3,})/.exec(line);
+    if (f) {
+      if (!fence) fence = f[1][0];
+      else if (f[1][0] === fence) fence = null;
+      return;
+    }
+    if (fence) return;
+    const h = /^\s{0,3}(#{1,6})\s+(.+?)\s*#*\s*$/.exec(line);
+    if (h) found.push({ title: h[2].trim(), level: h[1].length, line: i, base: headingSlug(h[2]) });
+  });
+  const seen = /* @__PURE__ */ new Map();
+  return found.map((h, k) => {
+    const n = (seen.get(h.base) ?? 0) + 1;
+    seen.set(h.base, n);
+    const next = found.slice(k + 1).find((o) => o.level <= h.level);
+    return { slug: n === 1 ? h.base : `${h.base}-${n}`, title: h.title, level: h.level, line: h.line, end: next ? next.line : lines.length };
+  });
+}
+function findSection(body, slug) {
+  return specSections(body).find((s) => s.slug === slug);
+}
+function sectionText(body, slug) {
+  const s = findSection(body, slug);
+  if (!s) return void 0;
+  return (body ?? "").split("\n").slice(s.line, s.end).join("\n");
+}
+function withSectionText(body, slug, text) {
+  if (!slug) return text;
+  const s = findSection(body, slug);
+  if (!s) return void 0;
+  const lines = (body ?? "").split("\n");
+  const replacement = text.replace(/\n+$/, "").split("\n");
+  const hadGap = s.end < lines.length && lines[s.end - 1] === "";
+  const tail = hadGap && replacement[replacement.length - 1] !== "" ? [""] : [];
+  return [...lines.slice(0, s.line), ...replacement, ...tail, ...lines.slice(s.end)].join("\n");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  findSection,
+  headingSlug,
+  sectionText,
+  specSections,
+  withSectionText
+});

package/src/shared/lib/symbol-entry.js

@@ -0,0 +1,60 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var symbol_entry_exports = {};
+__export(symbol_entry_exports, {
+  isSymbolEntry: () => isSymbolEntry,
+  splitSymbol: () => splitSymbol,
+  symbolEntry: () => symbolEntry,
+  symbolMatches: () => symbolMatches,
+  symbolProblem: () => symbolProblem
+});
+module.exports = __toCommonJS(symbol_entry_exports);
+const SYMBOL_RE = /^([^#\s]+)#([^#\s/]+)$/;
+function isSymbolEntry(s) {
+  return SYMBOL_RE.test(s) && !s.includes(":");
+}
+function symbolEntry(file, name) {
+  return `${file}#${name}`;
+}
+function splitSymbol(s) {
+  if (!isSymbolEntry(s)) return null;
+  const m = SYMBOL_RE.exec(s);
+  return { file: m[1], name: m[2] };
+}
+function symbolProblem(s) {
+  if (typeof s !== "string" || !isSymbolEntry(s.trim())) return "symbol must be a file and a name it exports, like src/payments/charge.ts#createCharge";
+  const { file, name } = splitSymbol(s.trim());
+  if (file.startsWith("/") || /^[a-zA-Z]:/.test(file) || file.includes("\\")) return "symbol must name a file relative to the project";
+  if (file.split("/").includes("..")) return "symbol may not climb out of the project";
+  if (name === "*") return "symbol must name one export, not the whole module";
+  return null;
+}
+function symbolMatches(ruleSymbol, entry) {
+  const rule = splitSymbol(ruleSymbol);
+  const got = splitSymbol(entry);
+  if (!rule || !got || rule.file !== got.file) return false;
+  return got.name === rule.name || got.name === "*";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  isSymbolEntry,
+  splitSymbol,
+  symbolEntry,
+  symbolMatches,
+  symbolProblem
+});