@printpractical/cruze 0.0.3 → 0.0.5

package/src/app/use_cases/record_progress.ts

@@ -58,6 +58,23 @@ export async function addFutureFeature(deps: ProjectDeps, slug: string, summary:
   return { feature: slug };
 }
 
+/**
+ * Replaces a feature's summary on the feature map, in the future list or the implemented list,
+ * when a decision changed what the feature delivers. Its goals or release stay as they are.
+ */
+export async function updateFeatureSummary(deps: ProjectDeps, slug: string, summary: string): Promise<{ feature: string; list: "Future" | "Implemented" }> {
+  if (summary.trim() === "") throw new CruzeError("missing-summary", "a feature needs a summary");
+  const vision = await requireVision(deps);
+  const future = readRows(vision, "Future").find((row) => row[0] === slug);
+  const implemented = readRows(vision, "Implemented").find((row) => row[0] === slug);
+  if (future === undefined && implemented === undefined) throw new CruzeError("not-found", `${slug} is not on the feature map`);
+  const list = future !== undefined ? "Future" : "Implemented";
+  const cells = future !== undefined ? [slug, summary.trim(), future[2] ?? ""] : [slug, implemented?.[1] ?? "", summary.trim()];
+  await deps.files.writeText(PATHS.vision, upsertRow(vision, list, cells));
+  await appendJournal(deps, ".cruze", "feature-map", { action: "update", feature: slug, summary: summary.trim() });
+  return { feature: slug, list };
+}
+
 export async function dropFutureFeature(deps: ProjectDeps, slug: string, reason: string): Promise<{ feature: string }> {
   const vision = await requireVision(deps);
   const { text, removed } = removeRow(vision, "Future", slug);

package/src/domain/approvals/agent_approval.ts

@@ -0,0 +1,68 @@
+import { CruzeError } from "../cruze_error.ts";
+import type { JournalEntry } from "../journal.ts";
+import type { WorkItem } from "../project/work_items.ts";
+import type { ApprovalStatus } from "./evaluate.ts";
+
+/**
+ * Why an approval was given without the user: a plan whose review closed, or work that a
+ * rethink left unchanged while something it cites moved. The user can still object, and
+ * editing the document makes the approval stale as usual.
+ */
+export type AgentBasis = "plan-review" | "rethink";
+
+const byTime = (a: JournalEntry, b: JournalEntry): number => a.at.localeCompare(b.at);
+
+/**
+ * A feature's change may be approved by the agent once its plan review has closed: a review
+ * recorded since the change was last approved, no blocker left open in its last round, and a
+ * disposition for every finding of its first round. The feature's design, and a standalone
+ * change's, stay the user's to approve.
+ */
+export function requirePlanReviewClosed(journal: JournalEntry[], item: WorkItem): void {
+  if (item.kind !== "change") {
+    throw new CruzeError("needs-user", `${item.ref} carries design, so the user approves it; only a feature's change can be approved after its plan review`);
+  }
+  const entries = journal.filter((e) => e["item"] === item.ref || e["artifact"] === item.path).sort(byTime);
+  const lastApproval = entries.filter((e) => e.event === "approve").at(-1);
+  const reviews = entries.filter((e) => e.event === "review" && e["review"] === "plan" && (lastApproval === undefined || e.at > lastApproval.at));
+  const last = reviews.at(-1);
+  if (last === undefined) {
+    const since = lastApproval === undefined ? "" : " since the change was last approved";
+    throw new CruzeError("plan-review-open", `no plan review is recorded for ${item.ref}${since}; run the plan review first`);
+  }
+  const blockers = Number(last["blockers"] ?? 0);
+  if (blockers > 0 && Number(last["round"]) === 1) {
+    throw new CruzeError("plan-review-open", `the plan review's round 1 found ${blockers} blocker(s); check their fixes in round 2`);
+  }
+  if (blockers > 0) {
+    throw new CruzeError("plan-review-open", `round 2 left ${blockers} blocker(s) open; the user decides them and approves the plan`);
+  }
+  const first = reviews.filter((e) => Number(e["round"]) === 1).at(-1) ?? last;
+  const findings = Number(first["blockers"] ?? 0) + Number(first["concerns"] ?? 0);
+  const decided = entries.filter((e) => e.event === "disposition" && e["review"] === "plan" && e.at > first.at).length;
+  if (decided < findings) {
+    throw new CruzeError("plan-review-open", `the plan review raised ${findings} finding(s) but ${decided} have a disposition; record one for each`);
+  }
+}
+
+/**
+ * A rethink may re-approve, for the user, a feature or change it didn't edit: one whose own
+ * design is unchanged and that is stale only because something it cites changed. A change
+ * with a task reopened since its approval goes back to the user.
+ */
+export function requireUnchangedSinceApproval(journal: JournalEntry[], item: WorkItem | undefined, path: string, status: ApprovalStatus): void {
+  if (item === undefined) {
+    throw new CruzeError("needs-user", `${path} is a project document, so the user re-approves it; a rethink re-stamps only features and changes`);
+  }
+  if (status.state === "edited") {
+    throw new CruzeError("needs-user", `${item.ref} itself changed since its approval, so the user re-approves it`);
+  }
+  if (status.state !== "upstream-changed") {
+    throw new CruzeError("not-stale", `${item.ref} is ${status.state}; only work whose upstream changed can be re-stamped`);
+  }
+  const approvedAt = journal.filter((e) => e.event === "approve" && e["artifact"] === path).sort(byTime).at(-1)?.at ?? "";
+  const reopened = journal.filter((e) => e.event === "reopen" && e["change"] === item.ref && e.at > approvedAt).map((e) => String(e["task"]));
+  if (reopened.length > 0) {
+    throw new CruzeError("needs-user", `${item.ref} had ${reopened.join(", ")} reopened since its approval, so the user re-approves it`);
+  }
+}

package/src/domain/config.ts

@@ -23,9 +23,25 @@ export interface CruzeConfig {
    * How `cruze review` starts an agent in a fresh context: the program and its arguments.
    * Without one, the calling agent runs the role's prompt in a helper of its own.
    */
-  review: { command?: string[] };
+  review: { command?: string[]; decide: ReviewDecide };
+  /** The size band of a change, so each one is worth its own plan, review and verify. */
+  changes: ChangeLimits;
 }
 
+/** Which review findings the user decides: only the exceptions, or every one. */
+export type ReviewDecide = "exceptions" | "all";
+
+export interface ChangeLimits {
+  /** A feature's change building fewer elements than this merges into a neighbour. */
+  minBuilds: number;
+  /** A change delivering more scenarios than this splits. */
+  maxScenarios: number;
+  /** A plan with more tasks than this splits. */
+  maxTasks: number;
+}
+
+export const DEFAULT_CHANGE_LIMITS: ChangeLimits = { minBuilds: 3, maxScenarios: 30, maxTasks: 25 };
+
 export interface Layer {
   name: string;
   paths: string[];
@@ -97,6 +113,14 @@ export function parseConfig(text: string): ConfigResult {
   const review = asRecord(root["review"]) ?? {};
   const reviewCommand = review["command"] === undefined ? undefined : stringList(review["command"], "review.command", problems);
   if (reviewCommand?.length === 0) problems.push("review.command needs at least the program to run");
+  const decide = review["decide"] ?? "exceptions";
+  if (decide !== "exceptions" && decide !== "all") problems.push("review.decide must be exceptions or all");
+  const limits = asRecord(root["changes"]) ?? {};
+  const changes: ChangeLimits = {
+    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,
+  };
 
   const config: CruzeConfig = {
     version: 1,
@@ -109,7 +133,11 @@ export function parseConfig(text: string): ConfigResult {
     check: { maxLines: maxLines ?? 250, maxTypes: maxTypes ?? 5, exceptions },
     layers,
     commands,
-    review: reviewCommand === undefined || reviewCommand.length === 0 ? {} : { command: reviewCommand },
+    review: {
+      ...(reviewCommand === undefined || reviewCommand.length === 0 ? {} : { command: reviewCommand }),
+      decide: decide === "all" ? "all" : "exceptions",
+    },
+    changes,
   };
   return { config, problems };
 }

package/src/domain/journal.ts

@@ -21,6 +21,7 @@ export const RECORDED_EVENTS: Record<string, string[]> = {
 const OPTIONAL_FIELDS: Record<string, string[]> = {
   rethink: ["missed_by"],
   review: ["nits"],
+  disposition: ["decided"],
 };
 
 /** The workflow steps and checks that find or miss a problem, so a retro can count them. */
@@ -30,6 +31,7 @@ export const FIELD_VALUES: Record<string, string[]> = {
   level: ["task", "change", "feature", "architecture", "vision"],
   kind: ["defect", "discovery"],
   disposition: ["fixed", "waived", "deferred", "rejected"],
+  decided: ["agent", "user"],
   review: ["design", "plan", "code", "realign"],
   result: ["accepted", "sent-back"],
   found_by: STEPS,
@@ -77,6 +79,9 @@ export function recordedEventProblems(event: string, fields: Record<string, stri
     if (allowed !== undefined && !allowed.includes(value)) problems.push(`${field} must be one of ${allowed.join(", ")}`);
     if (COUNT_FIELDS.includes(field) && !/^\d+$/.test(value)) problems.push(`${field} must be a whole number`);
   }
+  if (event === "disposition" && fields["decided"] === "agent" && fields["disposition"] !== "fixed") {
+    problems.push("the agent decides only fixes; the user waives, defers or rejects a finding (decided=user)");
+  }
   return problems;
 }
 

package/src/domain/status/verification.ts

@@ -4,13 +4,14 @@ import type { WorkItem } from "../project/work_items.ts";
 /**
  * Whether the user accepted a change at verify. The latest verification recorded for the change
  * counts. A later approval keeps it only when the change's own design is unchanged, as when it is
- * re-approved because something upstream moved; a changed plan means verifying again.
+ * re-approved because something upstream moved; a changed plan means verifying again. Land's
+ * re-stamps don't count, since they follow the merge; an approval the agent gave does.
  */
 export function isVerified(journal: JournalEntry[], change: WorkItem): boolean {
   const byTime = (a: JournalEntry, b: JournalEntry): number => a.at.localeCompare(b.at);
   const verification = journal.filter((e) => e.event === "verification" && e["item"] === change.ref).sort(byTime).at(-1);
   if (verification?.["result"] !== "accepted") return false;
-  const approvals = journal.filter((e) => e.event === "approve" && e["artifact"] === change.path && e["basis"] === undefined).sort(byTime);
+  const approvals = journal.filter((e) => e.event === "approve" && e["artifact"] === change.path && !String(e["basis"] ?? "").startsWith("land ")).sort(byTime);
   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);
 }

package/src/domain/status/work_status.ts

@@ -1,5 +1,4 @@
 import { evaluateApproval, type ApprovalStatus } from "../approvals/evaluate.ts";
-import { findIds } from "../ids.ts";
 import { PATHS } from "../project/layout.ts";
 import { readDelta } from "../project/deltas.ts";
 import { readScope } from "../project/plan_parts.ts";
@@ -89,13 +88,12 @@ export function buildGateReasons(view: ProjectView, branch: string | null): stri
   });
 }
 
-/** The elements a change touches: its scope plus every ID its documents cite. */
+/** The elements a change touches: its scope and its delta, not the elements it only cites, such as a test seam. */
 export function touchedIds(view: ProjectView, change: WorkItem): Set<string> {
   const feature = featureOf(view.items, change);
   const scope = readScope(change.doc);
   const ids = new Set([...(scope?.delivers ?? []), ...(scope?.builds ?? []), ...(scope?.removes ?? [])]);
   const deltaDoc = feature?.doc ?? change.doc;
   for (const id of readDelta(deltaDoc).ids) ids.add(id);
-  for (const id of findIds(change.doc.lines.join("\n"))) ids.add(id);
   return new Set([...ids].filter((id) => !id.startsWith("RULE-")));
 }

package/src/domain/validation/plan_rules.ts

@@ -7,6 +7,7 @@ import type { Delta } from "../project/deltas.ts";
 import { isPlanned, readScope, readTasks, readTestPlan, type Scope, type Task } from "../project/plan_parts.ts";
 import type { ProjectView } from "../project/project_view.ts";
 import { error, warning, type Problem } from "./problem.ts";
+import { planSizeProblems } from "./size_rules.ts";
 
 const TEST_KINDS = ["behaviour", "contract", "domain", "smoke"];
 
@@ -31,6 +32,7 @@ export function changePlanProblems(
     problems.push(error(path, line, "task-format", "task lines read: - T<n>: `<owner>` in `<path>`[, `<path>`], proves <ID>[, <ID>]"));
   }
   if (tasks.length === 0 && malformed.length === 0) problems.push(error(path, undefined, "missing-tasks", "the change has no tasks"));
+  problems.push(...planSizeProblems(view, path, tasks.length));
 
   const proved = new Set(tasks.flatMap((task) => task.proves));
   const taskPaths = tasks.flatMap((task) => task.paths);

package/src/domain/validation/size_rules.ts

@@ -0,0 +1,36 @@
+import { DEFAULT_CHANGE_LIMITS, type ChangeLimits } from "../config.ts";
+import { kindOf } from "../ids.ts";
+import type { ChangeRow } from "../project/plan_parts.ts";
+import type { ProjectView } from "../project/project_view.ts";
+import { warning, type Problem } from "./problem.ts";
+
+/**
+ * Every change pays for its own plan review, code review, verifier run and land, so a change
+ * should carry enough work to be worth them, and no more than one review and one run can hold.
+ */
+export function changeLimits(view: ProjectView): ChangeLimits {
+  return view.config?.config?.changes ?? DEFAULT_CHANGE_LIMITS;
+}
+
+/** 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[] {
+  const limits = changeLimits(view);
+  const problems: Problem[] = [];
+  for (const row of rows.filter((r) => !landed.has(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`));
+    }
+    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`));
+    }
+  }
+  return problems;
+}
+
+/** 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 [];
+  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,6 +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";
 
 const REQUIRED_SECTIONS: Record<WorkItem["kind"], string[]> = {
   feature: ["Intent", "Spec delta", "Architecture delta", "Changes"],
@@ -71,6 +72,7 @@ function featureScopeProblems(view: ProjectView, feature: WorkItem, delta: Delta
   if (extra !== undefined) {
     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));
   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`));

package/src/domain/versions/rule_versions.ts

@@ -13,6 +13,9 @@ export const RULE_SINCE: Record<string, string> = {
   "validate:outside-module-map": "0.0.2",
   "validate:readme-overview": "0.0.2",
   "validate:feature-size": "0.0.2",
+  "validate:change-too-small": "0.0.5",
+  "validate:change-too-large": "0.0.5",
+  "validate:plan-too-large": "0.0.5",
 };
 
 /** Whether a rule arrived after the version the project's code meets, so it waits for `realign`. */