@printpractical/cruze 0.0.8 → 0.0.9

package/src/domain/edits/agents_file.ts

@@ -19,9 +19,14 @@ export function renderAgentsFile(text: string, view: ProjectView): string {
   return next;
 }
 
+/**
+ * The modules whose code exists: those built, and those a land built before a rethink set them
+ * back to `planned` for a change to rebuild, since their directories are still there.
+ */
 function builtModules(view: ProjectView): string[] {
+  const everBuilt = new Set(view.journal.filter((e) => e.event === "land").flatMap((e) => (Array.isArray(e["built"]) ? (e["built"] as unknown[]).map(String) : [])));
   return [...view.living.elements.values()]
-    .filter(({ element, doc }) => element.kind === "MOD" && statusOf(doc, element) === "built")
+    .filter(({ element, doc }) => element.kind === "MOD" && (statusOf(doc, element) === "built" || everBuilt.has(element.id)))
     .map(({ element, doc }) => {
       const facts = factsOf(doc, element);
       const paths = (facts.get("Path") ?? []).flatMap((value) => [...value.matchAll(/`([^`]+)`/g)].map((m) => `\`${m[1] ?? ""}\``));

package/src/domain/journal.ts

@@ -23,6 +23,7 @@ const OPTIONAL_FIELDS: Record<string, string[]> = {
   rethink: ["missed_by"],
   review: ["nits", "checked_by"],
   disposition: ["decided"],
+  verification: ["back_to"],
 };
 
 /** The workflow steps and checks that find or miss a problem, so a retro can count them. */
@@ -35,11 +36,21 @@ export const FIELD_VALUES: Record<string, string[]> = {
   decided: ["agent", "user"],
   review: ["design", "plan", "code", "realign", "improve"],
   result: ["accepted", "sent-back"],
+  back_to: ["build", "rethink"],
   checked_by: ["agent", "reviewer"],
   found_by: STEPS,
   missed_by: STEPS,
 };
 
+/** A defect rethink must say which step missed it, and a sent-back verification where the change goes back to. */
+function conditionallyRequired(event: string, fields: Record<string, string>): string[] {
+  if (event === "rethink" && fields["kind"] === "defect") return ["missed_by"];
+  if (event === "verification" && fields["result"] === "sent-back") return ["back_to"];
+  return [];
+}
+
+const CONDITION_NOTES: Record<string, string> = { missed_by: " for a defect", back_to: " when the change is sent back" };
+
 /** Fields recorded as numbers rather than text. */
 const COUNT_FIELDS = ["round", "blockers", "concerns", "nits"];
 
@@ -71,8 +82,8 @@ export function serializeEntry(entry: JournalEntry): string {
 export function recordedEventProblems(event: string, fields: Record<string, string>): string[] {
   const required = RECORDED_EVENTS[event];
   if (required === undefined) return [`unknown event "${event}"; recordable events: ${Object.keys(RECORDED_EVENTS).join(", ")}`];
-  const needed = event === "rethink" && fields["kind"] === "defect" ? [...required, "missed_by"] : required;
-  const problems = needed.filter((field) => (fields[field] ?? "").trim() === "").map((field) => `${event} needs ${field}${field === "missed_by" ? " for a defect" : ""}`);
+  const needed = [...required, ...conditionallyRequired(event, fields)];
+  const problems = needed.filter((field) => (fields[field] ?? "").trim() === "").map((field) => `${event} needs ${field}${CONDITION_NOTES[field] ?? ""}`);
   const known = [...required, ...(OPTIONAL_FIELDS[event] ?? [])];
   for (const field of known) {
     const value = fields[field];

package/src/domain/project/scope_view.ts

@@ -36,8 +36,10 @@ export interface ScopeView {
   scenarios: ShownElement[];
   /** Elements the shown bodies cite but don't include, with where to read them. */
   cited: CitedElement[];
-  /** The settled decisions of the feature, then of the change. */
+  /** The settled decisions of the feature, or of a standalone change. */
   decisions: string[];
+  /** A feature's change's own settled decisions, numbered apart from the feature's. */
+  changeDecisions: string[];
   /** Scope IDs defined nowhere: the delta, the living docs or the archive. */
   missing: string[];
 }
@@ -66,7 +68,7 @@ export function scopeView(view: ProjectView, item: WorkItem): ScopeView {
       return [shown];
     });
   const elements = show(wanted.elements);
-  const scenarios = show(wanted.scenarios);
+  const scenarios = withoutRepeatedScenarios(show(wanted.scenarios));
   const shownIds = new Set([...elements, ...scenarios].map((e) => e.id));
   const cited = [...new Set([...elements, ...scenarios].flatMap((e) => findIds(e.body.join("\n"))))]
     .filter((id) => !shownIds.has(id))
@@ -74,12 +76,26 @@ export function scopeView(view: ProjectView, item: WorkItem): ScopeView {
       const found = locate(id);
       return found === undefined ? [] : [{ id, title: found.element.title, source: `${found.path}:${found.element.start + 1}` }];
     });
-  const decisions = feature === undefined ? decisionLines(item.doc) : [...decisionLines(feature.doc), ...decisionLines(item.doc)];
-  const result: ScopeView = { ref: item.ref, kind: item.kind, elements, scenarios, cited, decisions, missing };
+  const decisions = decisionLines((feature ?? item).doc);
+  const changeDecisions = feature === undefined ? [] : decisionLines(item.doc);
+  const result: ScopeView = { ref: item.ref, kind: item.kind, elements, scenarios, cited, decisions, changeDecisions, missing };
   if (feature !== undefined) result.feature = feature.ref;
   return result;
 }
 
+/**
+ * A requirement shown beside its own scenarios keeps only its own text: its body would repeat
+ * each of them, which made up a third of one change's output.
+ */
+function withoutRepeatedScenarios(shown: ShownElement[]): ShownElement[] {
+  const ids = new Set(shown.map((e) => e.id));
+  return shown.map((element) => {
+    if (!element.id.startsWith("REQ-")) return element;
+    const first = element.body.findIndex((line, i) => i > 0 && /^#{2,6} /.test(line) && findIds(line).some((id) => ids.has(id)));
+    return first === -1 ? element : { ...element, body: element.body.slice(0, first) };
+  });
+}
+
 /** A change shows what its scope builds, removes and delivers. */
 function changeIds(change: WorkItem): { elements: string[]; scenarios: string[] } {
   const scope = readScope(change.doc);

package/src/domain/status/next_step.ts

@@ -7,7 +7,7 @@ import { readRoadmapItems, readRoadmapStatus } from "../project/roadmap.ts";
 import { changesOf, featureOf, type WorkItem } from "../project/work_items.ts";
 import { compareVersions } from "../versions/cruze_version.ts";
 import { FIRST_RELEASE } from "../versions/rule_versions.ts";
-import { isVerified } from "./verification.ts";
+import { awaitsRethink, isVerified } from "./verification.ts";
 import { activeChange } from "./work_status.ts";
 
 /** The Cruze step to run next, computed from the project's state and the current branch. */
@@ -31,7 +31,7 @@ export function nextSteps(view: ProjectView, branch: string | null): NextReport
   const project = projectStep(view);
   if (project !== null) return { next: project, also: [] };
   const active = activeChange(view, branch);
-  const inFlight = view.items.filter((item) => !item.archived && item.kind !== "change").flatMap((item) => itemSteps(view, item, branch));
+  const inFlight = inRoadmapOrder(view, view.items.filter((item) => !item.archived && item.kind !== "change")).flatMap((item) => itemSteps(view, item, branch));
   const roadmap = roadmapStep(view);
   const realign = realignStep(view);
   const candidates = [
@@ -45,6 +45,28 @@ export function nextSteps(view: ProjectView, branch: string | null): NextReport
   return { next: next ?? { step: "roadmap", reason: "every item on the roadmap has landed; close the release and plan the next" }, also };
 }
 
+/**
+ * Work in flight in the roadmap's order, with items whose roadmap blockers haven't all landed
+ * last: a feature designed early still waits for the prefactors the user put before it.
+ */
+function inRoadmapOrder(view: ProjectView, items: WorkItem[]): WorkItem[] {
+  const text = view.snapshot.get(PATHS.roadmap);
+  if (text === undefined) return items;
+  const rows = readRoadmapStatus(text);
+  const state = new Map(rows.map((row) => [row.slug, row.state]));
+  const slugOf = new Map(rows.map((row) => [row.id, row.slug]));
+  const roadmap = readRoadmapItems(text);
+  const rank = (item: WorkItem): [number, number] => {
+    const at = roadmap.findIndex((r) => r.slug === slugOf.get(item.ref));
+    const blocked = at !== -1 && (roadmap[at]?.blockedBy ?? []).some((b) => state.get(b) !== "landed");
+    return [blocked ? 1 : 0, at === -1 ? roadmap.length : at];
+  };
+  return items
+    .map((item, i) => ({ item, key: [...rank(item), i] }))
+    .sort((a, b) => (a.key[0] ?? 0) - (b.key[0] ?? 0) || (a.key[1] ?? 0) - (b.key[1] ?? 0) || (a.key[2] ?? 0) - (b.key[2] ?? 0))
+    .map(({ item }) => item);
+}
+
 /** Realign comes when nothing else is due: the installed skills expect more than the code meets. */
 function realignStep(view: ProjectView): NextStep | null {
   const config = view.config?.config;
@@ -117,6 +139,7 @@ function changeStep(view: ProjectView, change: WorkItem, branch: string | null):
   if (!isPlanned(change.doc)) return { step: "plan", target: change.ref, reason: "the change is designed but has no test plan or tasks yet" };
   if (state.state === "unapproved") return { step: "plan", target: change.ref, reason: "review the plan and approve it on the branch that will build it" };
   if (state.state !== "approved") return { step: "rethink", target: change.ref, reason: `the change or something it cites changed since its approval${state.changed.length > 0 ? ` (${state.changed.join(", ")})` : ""}` };
+  if (awaitsRethink(view.journal, change, feature)) return { step: "rethink", target: feature?.ref ?? change.ref, reason: `verify sent ${change.ref} back for a design change` };
   if (bound !== undefined && bound !== branch) return { step: "switch-branch", target: bound, reason: `${change.ref} is built on branch ${bound}` };
   const progress = readProgress(change.doc);
   if ([...progress.tasks.values()].some((commit) => commit === null)) return { step: "build", target: change.ref, reason: "the change has open tasks" };

package/src/domain/status/verification.ts

@@ -15,3 +15,15 @@ export function isVerified(journal: JournalEntry[], change: WorkItem): boolean {
   const verifiedHash = approvals.filter((e) => e.at < verification.at).at(-1)?.["hash"];
   return approvals.filter((e) => e.at > verification.at).every((e) => e["hash"] === verifiedHash);
 }
+
+/**
+ * Whether verify sent the change back for a rethink that hasn't been recorded yet. Tasks the
+ * agent reopens at verify would otherwise make the change look ready to build again.
+ */
+export function awaitsRethink(journal: JournalEntry[], change: WorkItem, feature: WorkItem | undefined): boolean {
+  const verification = journal.filter((e) => e.event === "verification" && e["item"] === change.ref).sort((a, b) => a.at.localeCompare(b.at)).at(-1);
+  if (verification?.["result"] !== "sent-back" || verification["back_to"] !== "rethink") return false;
+  // An architecture-level rethink records no item, and counts too.
+  const refs = new Set([change.ref, feature?.ref, undefined]);
+  return !journal.some((e) => e.event === "rethink" && e.at > verification.at && refs.has(e["item"] as string | undefined));
+}

package/src/domain/validation/plan_rules.ts

@@ -46,7 +46,7 @@ export function changePlanProblems(
     if (kindOf(id) === "MOD") {
       const modulePaths = modulePathsOf(view, delta.doc, delta.delta, id);
       if (!taskPaths.some((p) => modulePaths.some((m) => p.startsWith(m)))) {
-        problems.push(error(path, scope.line, "unproved-scope", `${id} is in scope but no task writes inside ${modulePaths.join(" or ") || "its path"}`));
+        problems.push(error(path, scope.line, "unproved-scope", `${id} is in scope but no task writes inside ${modulePaths.join(" or ") || "its path"}; a module that owns other files, such as a build script, lists each under its Path`));
       }
     } else if (kindOf(id) === "REQ") {
       const scenarios = delta.delta.entries.find((e) => e.element.id === id)?.scenarios.map((s) => s.id) ?? [];

package/src/main.ts

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 // Composition root: the only place that constructs adapters.
-import { basename } from "node:path";
+import { basename, relative } from "node:path";
 import { runCli } from "./adapters/inbound/cli/run_cli.ts";
 import { GitRepository } from "./adapters/outbound/git_repository.ts";
 import { NodeProjectFiles } from "./adapters/outbound/node_project_files.ts";
 import { PackageBundle } from "./adapters/outbound/package_bundle.ts";
+import { findProjectRoot } from "./adapters/outbound/project_root.ts";
 import { ProcessAgentRunner } from "./adapters/outbound/process_agent_runner.ts";
 import { SystemClock } from "./adapters/outbound/system_clock.ts";
 import { DefaultAnswerPrompter, TerminalPrompter } from "./adapters/outbound/terminal_prompter.ts";
@@ -16,18 +17,21 @@ process.stdout.on("error", (error: NodeJS.ErrnoException) => {
 });
 
 const cwd = process.cwd();
+// Every command but init works on the project that holds the working directory, so it runs from any subdirectory.
+const root = process.argv[2] === "init" ? cwd : (findProjectRoot(cwd) ?? cwd);
 const exitCode = await runCli(
   process.argv.slice(2),
   {
-    files: new NodeProjectFiles(cwd),
+    files: new NodeProjectFiles(root),
     bundle: await PackageBundle.locate(),
     clock: new SystemClock(),
-    repository: new GitRepository(cwd),
+    repository: new GitRepository(root),
     interactivePrompter: new TerminalPrompter(),
     unattendedPrompter: new DefaultAnswerPrompter(),
-    runner: new ProcessAgentRunner(cwd),
+    runner: new ProcessAgentRunner(root),
     interactive: process.stdin.isTTY === true,
     directoryName: basename(cwd),
+    workingDirectory: relative(root, cwd).split("\\").join("/"),
   },
   {
     stdout: (text) => process.stdout.write(`${text}\n`),

package/templates/init/config.yaml

@@ -15,11 +15,12 @@ tracker: markdown
 source: []
 tests: []
 
-# Budgets enforced by `cruze check`. List a file under exceptions, with a
-# reason, to allow it past a budget.
+# Budgets enforced by `cruze check`: a backstop against a file that has
+# outgrown one responsibility, not a size to design to. List a file under
+# exceptions, with a reason, to allow it past a budget.
 check:
-  max_lines: 250
-  max_types: 5
+  max_lines: 600
+  max_types: 12
   exceptions: []
 
 # Layer rules, written by project-scope architecture design from the module map.