@printpractical/cruze 0.0.9 → 0.0.11

package/src/domain/status/next_step.ts

@@ -1,4 +1,5 @@
-import { evaluateApproval } from "../approvals/evaluate.ts";
+import { evaluateApproval, type ApprovalStatus } from "../approvals/evaluate.ts";
+import { rebaseNeeded } from "../approvals/rebase.ts";
 import { PATHS } from "../project/layout.ts";
 import { isPlanned, readChangesTable } from "../project/plan_parts.ts";
 import { readProgress } from "../project/progress.ts";
@@ -7,6 +8,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 { pendingReason, pendingRethinks } from "./pending_rethink.ts";
 import { awaitsRethink, isVerified } from "./verification.ts";
 import { activeChange } from "./work_status.ts";
 
@@ -112,7 +114,9 @@ function itemSteps(view: ProjectView, item: WorkItem, branch: string | null): Ne
   const state = evaluateApproval(view, item.path);
   if (readChangesTable(item.doc).length === 0) return [{ step: "architect", target: item.ref, reason: "the feature has no design or changes yet" }];
   if (state.state === "unapproved") return [{ step: "architect", target: item.ref, reason: "review the feature's design and approve it" }];
-  if (state.state !== "approved") return [{ step: "rethink", target: item.ref, reason: `the feature changed since its approval${state.changed.length > 0 ? ` (${state.changed.join(", ")})` : ""}` }];
+  if (state.state !== "approved") return [{ step: "rethink", target: item.ref, reason: staleReason(view, item, "the feature", state) }];
+  const pending = pendingRethinks(view.journal, item);
+  if (pending.length > 0) return [{ step: "rethink", target: item.ref, reason: pendingReason(item, pending) }];
   const changes = changesOf(view.items, item);
   const landed = new Set(changes.filter((c) => readProgress(c.doc).landed !== undefined).map((c) => c.folderName));
   const steps: NextStep[] = [];
@@ -131,14 +135,17 @@ function changeStep(view: ProjectView, change: WorkItem, branch: string | null):
   const feature = featureOf(view.items, change);
   const featureState = feature === undefined ? undefined : evaluateApproval(view, feature.path);
   if (feature !== undefined && featureState !== undefined && featureState.state !== "approved") {
-    const why = featureState.changed.length > 0 ? ` (${featureState.changed.join(", ")})` : "";
-    return { step: "rethink", target: feature.ref, reason: `the feature of ${change.ref} changed since its approval${why}` };
+    return { step: "rethink", target: feature.ref, reason: staleReason(view, feature, `the feature of ${change.ref}`, featureState) };
+  }
+  for (const part of [feature, change]) {
+    const pending = part === undefined ? [] : pendingRethinks(view.journal, part);
+    if (part !== undefined && pending.length > 0) return { step: "rethink", target: part.ref, reason: pendingReason(part, pending) };
   }
   const bound = readProgress(change.doc).branch;
   const state = evaluateApproval(view, change.path);
   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 (state.state !== "approved") return { step: "rethink", target: change.ref, reason: staleReason(view, change, "the change", state) };
   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);
@@ -147,6 +154,21 @@ function changeStep(view: ProjectView, change: WorkItem, branch: string | null):
   return { step: "land", target: change.ref, reason: "the change is verified and accepted" };
 }
 
+/**
+ * Why work went stale, and what the rethink will take: a rebase when its delta still changes an
+ * element whose living text moved, or only a check of the diff and a re-stamp when nothing it cites
+ * asks anything of its own text. One project expected a re-stamp and met rebase-required.
+ */
+function staleReason(view: ProjectView, item: WorkItem, label: string, state: ApprovalStatus): string {
+  if (state.state === "edited") return `${label} changed since its approval`;
+  const changed = state.changed.join(", ");
+  const rebase = rebaseNeeded(view, item);
+  const then = rebase.length > 0
+    ? `its delta changes ${rebase.join(", ")}, so rebase it, as cruze diff ${item.ref} shows`
+    : `read cruze diff ${item.ref}, and re-stamp it when the work still holds`;
+  return `something ${label} cites changed since its approval (${changed}); ${then}`;
+}
+
 /** The first roadmap item that hasn't started and whose blockers have all landed. */
 function roadmapStep(view: ProjectView): NextStep | null {
   const text = view.snapshot.get(PATHS.roadmap);

package/src/domain/status/pending_rethink.ts

@@ -0,0 +1,22 @@
+import type { JournalEntry } from "../journal.ts";
+import type { WorkItem } from "../project/work_items.ts";
+
+/**
+ * Findings decided `rethink` for a feature or change that no rethink of it has followed yet.
+ * One project's realign recorded seven design findings on a feature as fixed "by a rethink before
+ * its next change is planned"; nothing showed them, and they surfaced only in a commit message.
+ */
+export function pendingRethinks(journal: JournalEntry[], item: WorkItem): JournalEntry[] {
+  const lastRethink = journal
+    .filter((e) => e.event === "rethink" && e["item"] === item.ref)
+    .map((e) => e.at)
+    .sort()
+    .at(-1);
+  return journal.filter((e) => e.event === "disposition" && e["disposition"] === "rethink" && e["item"] === item.ref && (lastRethink === undefined || e.at > lastRethink));
+}
+
+/** Why work waits on a rethink, naming the first finding. */
+export function pendingReason(item: WorkItem, pending: JournalEntry[]): string {
+  const more = pending.length > 1 ? ` and ${pending.length - 1} more` : "";
+  return `${pending.length} finding(s) on ${item.ref} were decided for a rethink that hasn't happened yet: ${String(pending[0]?.["finding"] ?? "")}${more}`;
+}

package/src/domain/status/work_status.ts

@@ -5,6 +5,7 @@ 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";
+import { pendingReason, pendingRethinks } from "./pending_rethink.ts";
 
 export interface ChangeStatus {
   ref: string;
@@ -15,6 +16,8 @@ export interface ChangeStatus {
   tasksTotal: number;
   /** When and in which commit the change landed, once it has. */
   landed?: string;
+  /** Findings decided for a rethink of this change that hasn't happened yet. */
+  rethinkPending?: string[];
 }
 
 export interface FeatureStatus {
@@ -22,6 +25,8 @@ export interface FeatureStatus {
   path: string;
   approval: ApprovalStatus;
   changes: ChangeStatus[];
+  /** Findings decided for a rethink of this feature that hasn't happened yet. */
+  rethinkPending?: string[];
 }
 
 export interface ProjectStatus {
@@ -42,6 +47,7 @@ export function projectStatus(view: ProjectView, branch: string | null): Project
       path: feature.path,
       approval: evaluateApproval(view, feature.path),
       changes: changesOf(view.items, feature).map((change) => changeStatus(view, change)),
+      ...withPending(view, feature),
     }));
   const standalone = active.filter((item) => item.kind === "standalone").map((change) => changeStatus(view, change));
   const status: ProjectStatus = { documents, features, standalone };
@@ -69,7 +75,12 @@ function changeStatus(view: ProjectView, change: WorkItem): ChangeStatus {
   };
   if (progress.branch !== undefined) status.branch = progress.branch;
   if (progress.landed !== undefined) status.landed = progress.landed;
-  return status;
+  return { ...status, ...withPending(view, change) };
+}
+
+function withPending(view: ProjectView, item: WorkItem): { rethinkPending?: string[] } {
+  const pending = pendingRethinks(view.journal, item);
+  return pending.length === 0 ? {} : { rethinkPending: pending.map((e) => String(e["finding"] ?? "")) };
 }
 
 /** Why building may not start on this branch; empty when the build gate passes. */
@@ -86,7 +97,11 @@ export function buildGateReasons(view: ProjectView, branch: string | null): stri
     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)];
+  const rethinks = [feature, change].flatMap((part) => {
+    const pending = part === undefined ? [] : pendingRethinks(view.journal, part);
+    return part === undefined || pending.length === 0 ? [] : [`${pendingReason(part, pending)}; run rethink`];
+  });
+  return [...approvals, ...rethinks, ...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. */

package/src/domain/validation/decision_rules.ts

@@ -0,0 +1,76 @@
+import { definedDecisions, findDecisionCitations, workItemSlugs, type DecisionCitation } from "../decision_citations.ts";
+import type { Element } from "../elements.ts";
+import { findSection, type MarkdownDoc } from "../markdown.ts";
+import { readDelta } from "../project/deltas.ts";
+import { PATHS } from "../project/layout.ts";
+import type { ProjectView } from "../project/project_view.ts";
+import type { WorkItem } from "../project/work_items.ts";
+import { warning, type Problem } from "./problem.ts";
+
+const INSTEAD = "write what it decided into this text, or cite the ADR that records it";
+
+/**
+ * The architecture cites only the decisions its own `## Decisions` defines. The other living docs
+ * cite none by number, and no living doc cites a feature's or change's, which is archived when it finishes.
+ */
+export function livingDecisionProblems(view: ProjectView): Problem[] {
+  const slugs = slugsOf(view);
+  const project = projectDecisions(view);
+  const problems: Problem[] = [];
+  for (const [path, doc] of view.living.docs) {
+    for (const citation of citationsIn(doc, slugs)) {
+      if (citation.qualifier !== undefined) {
+        problems.push(warning(path, citation.line, "decision-citation", `cites ${citation.text}, a decision of ${citation.qualifier}, which the living docs don't hold; ${INSTEAD}`));
+      } else if (path !== PATHS.architecture) {
+        problems.push(warning(path, citation.line, "decision-citation", `cites ${citation.text}, but only the architecture cites decisions by number, its own; ${INSTEAD}`));
+      } else {
+        const unknown = citation.numbers.filter((n) => !project.has(n));
+        if (unknown.length > 0) {
+          problems.push(warning(path, citation.line, "decision-citation", `cites ${unknown.map((n) => `D${n}`).join(", ")}, which "## Decisions" doesn't define; ${INSTEAD}`));
+        }
+      }
+    }
+  }
+  return problems;
+}
+
+/**
+ * A delta's elements merge into the living docs, where the work's own decisions don't follow them.
+ * They may cite a project decision the work doesn't renumber, or one the living element already cites.
+ */
+export function deltaDecisionProblems(view: ProjectView, item: WorkItem): Problem[] {
+  const slugs = slugsOf(view);
+  const project = projectDecisions(view);
+  const local = definedDecisions(sectionLines(item.doc, "Settled decisions"));
+  const problems: Problem[] = [];
+  for (const { element } of readDelta(item.doc).entries) {
+    const living = view.living.elements.get(element.id);
+    const carried = new Set(living === undefined ? [] : citationsIn(living.doc, slugs, living.element).flatMap((c) => (c.qualifier === undefined ? c.numbers : [])));
+    const allowed = (n: number): boolean => project.has(n) && (!local.has(n) || carried.has(n));
+    for (const citation of citationsIn(item.doc, slugs, element)) {
+      if (citation.qualifier === undefined && citation.numbers.every(allowed)) continue;
+      problems.push(warning(item.path, citation.line, "decision-citation", `${element.id} cites ${citation.text}, which won't mean the same in the living docs once this delta merges; ${INSTEAD}`));
+    }
+  }
+  return problems;
+}
+
+function citationsIn(doc: MarkdownDoc, slugs: Set<string>, element?: Element): DecisionCitation[] {
+  const from = element === undefined ? doc.bodyStart : element.start + 1;
+  const to = element === undefined ? doc.lines.length : element.end;
+  return findDecisionCitations(doc.lines, slugs, (line) => line < from || line >= to || doc.inFence[line] === true || doc.inManaged[line] === true);
+}
+
+function projectDecisions(view: ProjectView): Set<number> {
+  const architecture = view.living.docs.get(PATHS.architecture);
+  return architecture === undefined ? new Set() : definedDecisions(sectionLines(architecture, "Decisions"));
+}
+
+function sectionLines(doc: MarkdownDoc, title: string): string[] {
+  const range = findSection(doc, title);
+  return range === null ? [] : doc.lines.slice(range.start, range.end);
+}
+
+function slugsOf(view: ProjectView): Set<string> {
+  return workItemSlugs(view.items.map((item) => item.folderName));
+}

package/src/domain/validation/delta_rules.ts

@@ -4,6 +4,7 @@ import { specPath } from "../project/layout.ts";
 import { orphanDeltaElements, readDelta, type Delta } from "../project/deltas.ts";
 import type { ProjectView } from "../project/project_view.ts";
 import type { WorkItem } from "../project/work_items.ts";
+import { deltaDecisionProblems } from "./decision_rules.ts";
 import { elementProblems } from "./element_rules.ts";
 import { error, type Problem } from "./problem.ts";
 
@@ -44,6 +45,7 @@ export function deltaProblems(view: ProjectView, item: WorkItem): Problem[] {
       problems.push(error(path, op.start, "capability-exists", `capability ${op.capability} already has ${specPath(op.capability)}`));
     }
   }
+  problems.push(...deltaDecisionProblems(view, item));
   return problems;
 }
 

package/src/domain/validation/future_rules.ts

@@ -0,0 +1,40 @@
+import { factsOf, headingElements } from "../elements.ts";
+import { readRows } from "../edits/managed_tables.ts";
+import { findIds, kindOf } from "../ids.ts";
+import type { MarkdownDoc } from "../markdown.ts";
+import { PATHS } from "../project/layout.ts";
+import { readDelta } from "../project/deltas.ts";
+import type { ProjectView } from "../project/project_view.ts";
+import { readRoadmapItems } from "../project/roadmap.ts";
+import { warning, type Problem } from "./problem.ts";
+
+/**
+ * A `Future` fact keeps room for a need someone stated: a `LATER` capability of the vision, or a
+ * feature on the feature map or the roadmap. One that names neither reserves room for a need nobody
+ * stated, which the design reviewer treats as a finding; this makes it visible without a review.
+ */
+export function futureProblems(view: ProjectView): Problem[] {
+  const slugs = anchorSlugs(view);
+  const unanchored = (text: string): boolean =>
+    !findIds(text).some((id) => kindOf(id) === "LATER") && ![...slugs].some((slug) => new RegExp(`(^|[^a-z0-9-])${slug}([^a-z0-9-]|$)`).test(text));
+  const check = (path: string, doc: MarkdownDoc, from = 0, to = doc.lines.length): Problem[] =>
+    headingElements(doc, from, to).flatMap((element) =>
+      (factsOf(doc, element).get("Future") ?? [])
+        .filter(unanchored)
+        .map(() => warning(path, element.start, "future-unanchored", `${element.id} keeps room for a need its Future fact doesn't name; cite the LATER capability, or the feature on the map or roadmap, that it serves`)),
+    );
+  const living = view.living.docs.get(PATHS.architecture);
+  const deltas = view.items
+    .filter((item) => !item.archived && item.kind !== "change")
+    .flatMap((item) => readDelta(item.doc).entries.flatMap((entry) => check(item.path, item.doc, entry.element.start, entry.element.end)));
+  return [...(living === undefined ? [] : check(PATHS.architecture, living)), ...deltas];
+}
+
+/** Feature slugs a Future fact may name: the feature map's, implemented or future, and the roadmap's items. */
+function anchorSlugs(view: ProjectView): Set<string> {
+  const vision = view.snapshot.get(PATHS.vision) ?? "";
+  const roadmap = view.snapshot.get(PATHS.roadmap);
+  const mapped = ["Implemented", "Future"].flatMap((heading) => readRows(vision, heading).map((row) => row[0] ?? ""));
+  const planned = roadmap === undefined ? [] : readRoadmapItems(roadmap).map((item) => item.slug);
+  return new Set([...mapped, ...planned].map((slug) => slug.trim()).filter((slug) => /^[a-z0-9-]+$/.test(slug)));
+}

package/src/domain/validation/living_rules.ts

@@ -4,6 +4,7 @@ import { findIds, scopeOf, STATUS_KINDS } from "../ids.ts";
 import type { MarkdownDoc } from "../markdown.ts";
 import { PATHS } from "../project/layout.ts";
 import type { ProjectView } from "../project/project_view.ts";
+import { livingDecisionProblems } from "./decision_rules.ts";
 import { elementProblems } from "./element_rules.ts";
 import { error, warning, type Problem } from "./problem.ts";
 
@@ -26,6 +27,7 @@ export function livingProblems(view: ProjectView): Problem[] {
       if (!view.living.elements.has(id)) problems.push(error(path, lineOf(text, id), "unknown-id", `${id} is cited but not defined in the living docs`));
     }
   }
+  problems.push(...livingDecisionProblems(view));
   return problems;
 }
 

package/src/domain/validation/validate_project.ts

@@ -1,7 +1,9 @@
 import type { ProjectView } from "../project/project_view.ts";
+import { futureProblems } from "./future_rules.ts";
 import { livingProblems } from "./living_rules.ts";
 import { error, sortProblems, type Problem } from "./problem.ts";
 import { configProblems, readmeProblems, roadmapProblems, templateLeftovers } from "./project_rules.ts";
+import { visionProblems } from "./vision_rules.ts";
 import { workItemProblems } from "./work_item_rules.ts";
 
 /** Every rule in the cruze-formats skill, applied to the whole project. */
@@ -13,6 +15,8 @@ export function validateProject(view: ProjectView): Problem[] {
   return sortProblems([
     ...configProblems(view),
     ...livingProblems(view),
+    ...visionProblems(view),
+    ...futureProblems(view),
     ...roadmapProblems(view),
     ...workItemProblems(view),
     ...templateLeftovers(view),

package/src/domain/validation/vision_rules.ts

@@ -0,0 +1,41 @@
+import { rowElements } from "../elements.ts";
+import { findSection } from "../markdown.ts";
+import { splitRow } from "../markdown_tables.ts";
+import { PATHS } from "../project/layout.ts";
+import type { ProjectView } from "../project/project_view.ts";
+import { error, type Problem } from "./problem.ts";
+
+/** The section and the cells after the ID that each long-term row of the vision holds. */
+const INTENT_ROWS: Record<string, { section: string; cells: string[] }> = {
+  PRINCIPLE: { section: "Principles", cells: ["Principle", "Why"] },
+  LATER: { section: "Must stay possible", cells: ["Capability", "Likelihood", "Why", "Leave room for"] },
+};
+
+export const LIKELIHOODS = ["likely", "possible"];
+
+/**
+ * The vision's principles and the capabilities that must stay possible are rows, so designs cite
+ * them and approvals pin them. One project kept its principles in a seed note and its long-term
+ * plans in the user's head: a feature reversed a principle unnoticed, and a later review proposed
+ * removing what those plans needed.
+ */
+export function visionProblems(view: ProjectView): Problem[] {
+  const doc = view.living.docs.get(PATHS.vision);
+  if (doc === undefined) return [];
+  return rowElements(doc).flatMap((row) => {
+    const shape = INTENT_ROWS[row.kind];
+    if (shape === undefined) return [];
+    const section = findSection(doc, shape.section);
+    if (section === null || row.start < section.start || row.start >= section.end) {
+      return [error(PATHS.vision, row.start, "vision-row", `${row.id} belongs in the table under ## ${shape.section}`)];
+    }
+    const cells = splitRow(doc.lines[row.start] ?? "").slice(1);
+    if (cells.length !== shape.cells.length || cells.some((cell) => cell === "")) {
+      return [error(PATHS.vision, row.start, "vision-row", `${row.id} needs ${shape.cells.join(", ")}, each filled`)];
+    }
+    if (row.kind === "LATER" && !LIKELIHOODS.includes(cells[1] ?? "")) {
+      return [error(PATHS.vision, row.start, "vision-row", `${row.id}'s likelihood must be ${LIKELIHOODS.join(" or ")}`)];
+    }
+    return [];
+  });
+}

package/src/domain/versions/rule_versions.ts

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

package/templates/init/AGENTS.md

@@ -25,4 +25,4 @@ Not defined yet. `cruze land` fills this in from the module map in `docs/archite
 
 ## Known pitfalls
 
-None recorded yet. `land` adds a line here when the same review finding or defect happens twice.
+None recorded yet. `land` adds a line here when the same review finding or defect about this project's code happens twice.