@printpractical/cruze 0.0.7 → 0.0.8

package/src/domain/check/budget_text.ts

@@ -0,0 +1,24 @@
+/**
+ * The part of a source file its budgets measure. Budgets apply to source, not tests, so a Rust
+ * file's `#[cfg(test)]` modules are left out: rustfmt closes a top-level module with `}` in column 0.
+ */
+export function budgetedText(path: string, text: string): string {
+  if (!path.endsWith(".rs")) return text;
+  const lines = text.split("\n");
+  const kept: string[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const item = lines[i + 1] ?? "";
+    if (lines[i]?.trim() !== "#[cfg(test)]" || !/^(?:pub(?:\([^)]*\))?\s+)?mod\s+\w+\s*[{;]/.test(item)) {
+      kept.push(lines[i] ?? "");
+      continue;
+    }
+    if (item.trimEnd().endsWith(";")) {
+      i += 1;
+      continue;
+    }
+    let end = i + 2;
+    while (end < lines.length && lines[end] !== "}") end++;
+    i = end;
+  }
+  return kept.join("\n");
+}

package/src/domain/check/check_source.ts

@@ -1,5 +1,6 @@
 import type { CruzeConfig, Layer } from "../config.ts";
 import { matchesAny } from "../glob.ts";
+import { budgetedText } from "./budget_text.ts";
 import { importsOf, resolveImport } from "./imports.ts";
 import { countTypes } from "./type_count.ts";
 
@@ -50,11 +51,13 @@ export function checkSource(input: CheckInput): CheckFinding[] {
       }
     }
     const excepted = config.check.exceptions.some((exception) => exception.path === path);
-    const lines = text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
+    const budgeted = budgetedText(path, text);
+    const lines = budgeted.split("\n").length - (budgeted.endsWith("\n") ? 1 : 0);
     if (!excepted && lines > config.check.maxLines) {
-      findings.push({ path, rule: "max-lines", severity: "warning", message: `${lines} lines, over the budget of ${config.check.maxLines}; split it by responsibility` });
+      const measured = budgeted === text ? "" : ", not counting its inline tests";
+      findings.push({ path, rule: "max-lines", severity: "warning", message: `${lines} lines${measured}, over the budget of ${config.check.maxLines}; split it by responsibility` });
     }
-    const types = countTypes(path, text);
+    const types = countTypes(path, budgeted);
     if (!excepted && types !== null && types > config.check.maxTypes) {
       findings.push({ path, rule: "max-types", severity: "warning", message: `${types} top-level types, over the budget of ${config.check.maxTypes}` });
     }

package/src/domain/config.ts

@@ -38,9 +38,11 @@ export interface ChangeLimits {
   maxScenarios: number;
   /** A plan with more tasks than this splits. */
   maxTasks: number;
+  /** Features and changes the user accepted outside the band, by ref, each with the reason. */
+  exceptions: Array<{ item: string; reason: string }>;
 }
 
-export const DEFAULT_CHANGE_LIMITS: ChangeLimits = { minBuilds: 3, maxScenarios: 30, maxTasks: 25 };
+export const DEFAULT_CHANGE_LIMITS: ChangeLimits = { minBuilds: 3, maxScenarios: 30, maxTasks: 25, exceptions: [] };
 
 export interface Layer {
   name: string;
@@ -120,6 +122,14 @@ export function parseConfig(text: string): ConfigResult {
     minBuilds: positiveInt(limits["min_builds"], "changes.min_builds", problems) ?? DEFAULT_CHANGE_LIMITS.minBuilds,
     maxScenarios: positiveInt(limits["max_scenarios"], "changes.max_scenarios", problems) ?? DEFAULT_CHANGE_LIMITS.maxScenarios,
     maxTasks: positiveInt(limits["max_tasks"], "changes.max_tasks", problems) ?? DEFAULT_CHANGE_LIMITS.maxTasks,
+    exceptions: (Array.isArray(limits["exceptions"]) ? limits["exceptions"] : []).flatMap((entry: unknown, i: number) => {
+      const record = asRecord(entry);
+      if (typeof record?.["item"] !== "string" || typeof record["reason"] !== "string" || record["reason"].trim() === "") {
+        problems.push(`changes.exceptions[${i}] needs an item and a non-empty reason`);
+        return [];
+      }
+      return [{ item: record["item"], reason: record["reason"] }];
+    }),
   };
 
   const config: CruzeConfig = {

package/src/domain/project/scope_view.ts

@@ -0,0 +1,118 @@
+import { elementLines, type DeltaOp, type Element } from "../elements.ts";
+import { findIds } from "../ids.ts";
+import { findSection, type MarkdownDoc } from "../markdown.ts";
+import { readDelta } from "./deltas.ts";
+import { readScope } from "./plan_parts.ts";
+import type { ProjectView } from "./project_view.ts";
+import { featureOf, type WorkItem, type WorkItemKind } from "./work_items.ts";
+
+/**
+ * The design a piece of work builds, cut out of the documents that hold it, so a step reads
+ * the elements in its scope instead of the whole architecture and the whole feature.
+ */
+
+export interface ShownElement {
+  id: string;
+  title: string;
+  op?: DeltaOp;
+  /** Where the body comes from, as `<path>:<line>`. */
+  source: string;
+  body: string[];
+}
+
+export interface CitedElement {
+  id: string;
+  title: string;
+  source: string;
+}
+
+export interface ScopeView {
+  ref: string;
+  kind: WorkItemKind;
+  feature?: string;
+  /** The architecture elements the work builds or removes; for a feature, its whole architecture delta. */
+  elements: ShownElement[];
+  /** The scenarios and requirements the work delivers; for a feature, its whole spec delta. */
+  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. */
+  decisions: string[];
+  /** Scope IDs defined nowhere: the delta, the living docs or the archive. */
+  missing: string[];
+}
+
+interface Located {
+  doc: MarkdownDoc;
+  path: string;
+  element: Element;
+}
+
+export function scopeView(view: ProjectView, item: WorkItem): ScopeView {
+  const feature = featureOf(view.items, item);
+  const deltaItem = feature ?? item;
+  const locate = locator(view, deltaItem);
+  const wanted = item.kind === "change" || item.kind === "standalone" ? changeIds(item) : featureIds(deltaItem);
+  const missing: string[] = [];
+  const show = (ids: string[]): ShownElement[] =>
+    ids.flatMap((id) => {
+      const found = locate(id);
+      if (found === undefined) {
+        missing.push(id);
+        return [];
+      }
+      const shown: ShownElement = { id, title: found.element.title, source: `${found.path}:${found.element.start + 1}`, body: elementLines(found.doc, found.element) };
+      if (found.element.op !== undefined) shown.op = found.element.op;
+      return [shown];
+    });
+  const elements = show(wanted.elements);
+  const scenarios = 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))
+    .flatMap((id) => {
+      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 };
+  if (feature !== undefined) result.feature = feature.ref;
+  return result;
+}
+
+/** A change shows what its scope builds, removes and delivers. */
+function changeIds(change: WorkItem): { elements: string[]; scenarios: string[] } {
+  const scope = readScope(change.doc);
+  return { elements: [...(scope?.builds ?? []), ...(scope?.removes ?? [])], scenarios: scope?.delivers ?? [] };
+}
+
+/** A feature shows its whole delta: every operation, with a requirement's scenarios inside its body. */
+function featureIds(feature: WorkItem): { elements: string[]; scenarios: string[] } {
+  const entries = readDelta(feature.doc).entries;
+  return {
+    elements: entries.filter((e) => e.section === "architecture").map((e) => e.element.id),
+    scenarios: entries.filter((e) => e.section === "spec").map((e) => e.element.id),
+  };
+}
+
+/** Finds an element's body in the work's own delta first, since that is the text the work builds, then in the living docs. */
+function locator(view: ProjectView, deltaItem: WorkItem): (id: string) => Located | undefined {
+  const delta = readDelta(deltaItem.doc);
+  const inDelta = new Map<string, Element>();
+  for (const entry of delta.entries) {
+    inDelta.set(entry.element.id, entry.element);
+    for (const scenario of entry.scenarios) inDelta.set(scenario.id, scenario);
+  }
+  return (id) => {
+    const own = inDelta.get(id);
+    if (own !== undefined) return { doc: deltaItem.doc, path: deltaItem.path, element: own };
+    const living = view.living.elements.get(id);
+    return living === undefined ? undefined : { doc: living.doc, path: living.path, element: living.element };
+  };
+}
+
+function decisionLines(doc: MarkdownDoc): string[] {
+  const section = findSection(doc, "Settled decisions");
+  if (section === null) return [];
+  return doc.lines.slice(section.start, section.end).filter((line) => line.startsWith("- "));
+}

package/src/domain/status/work_status.ts

@@ -1,7 +1,7 @@
 import { evaluateApproval, type ApprovalStatus } from "../approvals/evaluate.ts";
 import { PATHS } from "../project/layout.ts";
 import { readDelta } from "../project/deltas.ts";
-import { readScope } from "../project/plan_parts.ts";
+import { readChangesTable, readScope } from "../project/plan_parts.ts";
 import { readProgress } from "../project/progress.ts";
 import type { ProjectView } from "../project/project_view.ts";
 import { changesOf, featureOf, type WorkItem } from "../project/work_items.ts";
@@ -80,12 +80,23 @@ export function buildGateReasons(view: ProjectView, branch: string | null): stri
   const feature = featureOf(view.items, change);
   if (feature !== undefined) required.push(feature.path);
   if (view.snapshot.has(PATHS.architecture)) required.push(PATHS.architecture);
-  return required.flatMap((path) => {
+  const approvals = required.flatMap((path) => {
     const status = evaluateApproval(view, path);
     if (status.state === "approved") return [];
     const detail = status.changed.length > 0 ? `: ${status.changed.join(", ")} changed` : status.unjournaled === true ? ": the approval has no journal entry" : "";
     return [`${path} is ${status.state}${detail}`];
   });
+  return [...approvals, ...unlandedDependencies(view, change, feature)];
+}
+
+/** The changes this change's row in its feature's Changes table depends on that haven't landed on this branch. */
+function unlandedDependencies(view: ProjectView, change: WorkItem, feature: WorkItem | undefined): string[] {
+  if (feature === undefined) return [];
+  const row = readChangesTable(feature.doc).find((r) => r.change === change.folderName);
+  const landed = new Set(changesOf(view.items, feature).filter((c) => readProgress(c.doc).landed !== undefined).map((c) => c.folderName));
+  return (row?.dependsOn ?? [])
+    .filter((dependency) => !landed.has(dependency))
+    .map((dependency) => `${change.ref} depends on ${dependency}, which hasn't landed here; land it, then merge main into this branch`);
 }
 
 /** The elements a change touches: its scope and its delta, not the elements it only cites, such as a test seam. */

package/src/domain/validation/element_rules.ts

@@ -41,6 +41,11 @@ export function elementProblems(path: string, doc: MarkdownDoc, element: Element
       problems.push(error(path, element.start, "fact-value", `${element.id} ${key} must be one of ${rule.values.join(", ")}`));
     }
   }
+  if (element.kind === "MOD") {
+    for (const glob of (facts.get("Path") ?? []).flatMap((value) => [...value.matchAll(/`([^`]+)`/g)].map((m) => m[1] ?? "")).filter((p) => /[*?[{]/.test(p))) {
+      problems.push(error(path, element.start, "module-path-glob", `${element.id} Path \`${glob}\` is a glob, which matches no file; name a directory ending in / or a single file, one per Path value`));
+    }
+  }
   const module = facts.get("Module")?.[0];
   if (module !== undefined && !findIds(module).some((id) => id.startsWith("MOD-"))) {
     problems.push(error(path, element.start, "fact-value", `${element.id} Module must name a MOD element`));

package/src/domain/validation/size_rules.ts

@@ -12,17 +12,25 @@ export function changeLimits(view: ProjectView): ChangeLimits {
   return view.config?.config?.changes ?? DEFAULT_CHANGE_LIMITS;
 }
 
+/** The rules a size warning comes from. An item stays outside the band only with the user's recorded acceptance. */
+export const SIZE_RULES = ["feature-size", "change-too-small", "change-too-large", "plan-too-large"];
+
+/** Whether the user accepted this feature or change outside the band, under `changes.exceptions`. */
+export function sizeAccepted(view: ProjectView, ref: string): boolean {
+  return changeLimits(view).exceptions.some((exception) => exception.item === ref);
+}
+
 /** A feature's changes not yet landed that fall outside the size band. A feature of one change has nothing to merge into. */
-export function changeRowSizeProblems(view: ProjectView, path: string, rows: ChangeRow[], landed: Set<string>): Problem[] {
+export function changeRowSizeProblems(view: ProjectView, feature: { path: string; ref: string }, rows: ChangeRow[], landed: Set<string>): Problem[] {
   const limits = changeLimits(view);
   const problems: Problem[] = [];
-  for (const row of rows.filter((r) => !landed.has(r.change))) {
+  for (const row of rows.filter((r) => !landed.has(r.change) && !sizeAccepted(view, `${feature.ref}/${r.change}`))) {
     if (rows.length > 1 && row.builds.length < limits.minBuilds) {
-      problems.push(warning(path, row.line, "change-too-small", `${row.change} builds ${row.builds.length} element(s), under ${limits.minBuilds}; merge it into the change it continues, since each change pays for its own plan, review and verify`));
+      problems.push(warning(feature.path, row.line, "change-too-small", `${row.change} builds ${row.builds.length} element(s), under ${limits.minBuilds}; merge it into the change it continues, since each change pays for its own plan, review and verify`));
     }
     const scenarios = row.delivers.filter((id) => kindOf(id) === "SCN").length;
     if (scenarios > limits.maxScenarios) {
-      problems.push(warning(path, row.line, "change-too-large", `${row.change} delivers ${scenarios} scenarios, over ${limits.maxScenarios}; split it, since one verifier run has to go through them all`));
+      problems.push(warning(feature.path, row.line, "change-too-large", `${row.change} delivers ${scenarios} scenarios, over ${limits.maxScenarios}; split it, since one verifier run has to go through them all`));
     }
   }
   return problems;
@@ -31,6 +39,7 @@ export function changeRowSizeProblems(view: ProjectView, path: string, rows: Cha
 /** A plan with more tasks than one code review and one verify can hold. */
 export function planSizeProblems(view: ProjectView, path: string, tasks: number): Problem[] {
   const { maxTasks } = changeLimits(view);
-  if (tasks <= maxTasks) return [];
+  const ref = view.items.find((item) => item.path === path)?.ref ?? path;
+  if (tasks <= maxTasks || sizeAccepted(view, ref)) return [];
   return [warning(path, undefined, "plan-too-large", `the plan has ${tasks} tasks, over ${maxTasks}; split the change through rethink at feature level`)];
 }

package/src/domain/validation/work_item_rules.ts

@@ -11,7 +11,7 @@ import { deltaProblems } from "./delta_rules.ts";
 import { malformedIdHeadings, lineOf } from "./living_rules.ts";
 import { changePlanProblems } from "./plan_rules.ts";
 import { error, warning, type Problem } from "./problem.ts";
-import { changeRowSizeProblems } from "./size_rules.ts";
+import { changeRowSizeProblems, sizeAccepted } from "./size_rules.ts";
 
 const REQUIRED_SECTIONS: Record<WorkItem["kind"], string[]> = {
   feature: ["Intent", "Spec delta", "Architecture delta", "Changes"],
@@ -45,6 +45,10 @@ function itemProblems(view: ProjectView, item: WorkItem): Problem[] {
   for (const cited of findIds(text).filter((cited) => !available.has(cited))) {
     problems.push(error(path, lineOf(text, cited), "unknown-id", `${cited} is cited but defined neither in the living docs nor in this work's deltas`));
   }
+  const dropped = droppedScenarios(view, delta);
+  for (const cited of findIds(text).filter((cited) => dropped.has(cited))) {
+    problems.push(error(path, lineOf(text, cited), "cites-dropped", `${cited} is cited, but ${dropped.get(cited)} in this work's delta leaves it out, so it won't exist once the work lands; describe it in words instead`));
+  }
   if (item.kind !== "change") problems.push(...deltaProblems(view, item));
   if (item.kind === "feature") problems.push(...featureScopeProblems(view, item, delta));
   // A landed change is history: its scope named what it built, which is now built.
@@ -69,10 +73,10 @@ function featureScopeProblems(view: ProjectView, feature: WorkItem, delta: Delta
   );
   const names = rows.map((row) => row.change);
   const extra = rows[MAX_CHANGES];
-  if (extra !== undefined) {
+  if (extra !== undefined && !sizeAccepted(view, feature.ref)) {
     problems.push(warning(feature.path, extra.line, "feature-size", `the feature has ${rows.length} changes, over ${MAX_CHANGES}; split it into features a single design review can hold`));
   }
-  problems.push(...changeRowSizeProblems(view, feature.path, rows, landedChanges));
+  problems.push(...changeRowSizeProblems(view, feature, rows, landedChanges));
   for (const row of rows) {
     if (!/^\d\d-[a-z0-9]+(?:-[a-z0-9]+)*$/.test(row.change)) problems.push(error(feature.path, row.line, "change-name", `change "${row.change}" must be named NN-slug`));
     if (names.indexOf(row.change) !== names.lastIndexOf(row.change)) problems.push(error(feature.path, row.line, "change-name", `change ${row.change} is listed twice`));
@@ -151,3 +155,21 @@ function scopeIds(item: WorkItem): string[] {
   const scope = readScope(item.doc);
   return scope === null ? [] : [...scope.delivers, ...scope.builds, ...scope.removes];
 }
+
+/**
+ * Living scenarios that a MODIFIED requirement in the delta leaves out, each with that requirement.
+ * Land drops them, so a citation of one passes validation now and breaks only at land.
+ */
+function droppedScenarios(view: ProjectView, delta: Delta): Map<string, string> {
+  const dropped = new Map<string, string>();
+  for (const entry of delta.entries.filter((e) => e.element.op === "MODIFIED" && kindOf(e.element.id) === "REQ")) {
+    const living = view.living.elements.get(entry.element.id);
+    if (living === undefined) continue;
+    const kept = new Set(entry.scenarios.map((s) => s.id));
+    for (const scenario of view.living.elements.values()) {
+      const nested = scenario.doc === living.doc && scenario.element.start > living.element.start && scenario.element.start < living.element.end;
+      if (nested && kindOf(scenario.id) === "SCN" && !kept.has(scenario.id) && !delta.ids.has(scenario.id)) dropped.set(scenario.id, entry.element.id);
+    }
+  }
+  return dropped;
+}

package/src/domain/versions/rule_versions.ts

@@ -16,6 +16,7 @@ export const RULE_SINCE: Record<string, string> = {
   "validate:change-too-small": "0.0.5",
   "validate:change-too-large": "0.0.5",
   "validate:plan-too-large": "0.0.5",
+  "validate:module-path-glob": "0.0.8",
 };
 
 /** Whether a rule arrived after the version the project's code meets, so it waits for `realign`. */

package/src/main.ts

@@ -9,6 +9,12 @@ 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";
 
+// A reader that stops early, such as `cruze journal list | head`, closes the pipe; that is not an error worth a stack trace.
+process.stdout.on("error", (error: NodeJS.ErrnoException) => {
+  if (error.code === "EPIPE") process.exit(0);
+  throw error;
+});
+
 const cwd = process.cwd();
 const exitCode = await runCli(
   process.argv.slice(2),

package/templates/init/AGENTS.md

@@ -4,7 +4,7 @@ Instructions for coding agents working in this repository. Cruze keeps the manag
 
 ## Workflow
 
-This project uses [Cruze](https://github.com/PrintPractical/cruze) for spec-driven development. Durable documents live in `docs/`: vision, glossary, architecture, ADRs, specs and roadmap. Work in progress lives in `.cruze/`. Read `docs/architecture.md` before changing code, once it exists. The Cruze skills run the `cruze` command; when it is missing, install it as https://github.com/PrintPractical/cruze#quick-start describes.
+This project uses [Cruze](https://github.com/PrintPractical/cruze) for spec-driven development. Durable documents live in `docs/`: vision, glossary, architecture, ADRs, specs and roadmap. Work in progress lives in `.cruze/`. Before changing code, read the design the change builds with `cruze show <change>`, once it exists. Each Cruze step runs in a new session, so its context holds what the step reads and nothing else. The Cruze skills run the `cruze` command; when it is missing, install it as https://github.com/PrintPractical/cruze#quick-start describes.
 
 ## Commands