@printpractical/cruze 0.0.1 → 0.0.3

package/src/domain/status/next_step.ts

@@ -5,12 +5,14 @@ import { readProgress } from "../project/progress.ts";
 import type { ProjectView } from "../project/project_view.ts";
 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 { activeChange } from "./work_status.ts";
 
 /** The Cruze step to run next, computed from the project's state and the current branch. */
 
-export type Step = "envision" | "architect" | "roadmap" | "plan" | "build" | "verify" | "land" | "rethink" | "switch-branch";
+export type Step = "envision" | "architect" | "roadmap" | "plan" | "build" | "verify" | "land" | "rethink" | "realign" | "switch-branch";
 
 export interface NextStep {
   step: Step;
@@ -31,12 +33,27 @@ export function nextSteps(view: ProjectView, branch: string | null): NextReport
   const active = activeChange(view, branch);
   const inFlight = view.items.filter((item) => !item.archived && item.kind !== "change").flatMap((item) => itemSteps(view, item, branch));
   const roadmap = roadmapStep(view);
-  const candidates = [...(active === undefined ? [] : [changeStep(view, active, branch)]), ...inFlight, ...(roadmap === null ? [] : [roadmap])];
+  const realign = realignStep(view);
+  const candidates = [
+    ...(active === undefined ? [] : [changeStep(view, active, branch)]),
+    ...inFlight,
+    ...(roadmap === null ? [] : [roadmap]),
+    ...(realign === null ? [] : [realign]),
+  ];
   const unique = candidates.filter((c, i) => candidates.findIndex((o) => o.step === c.step && o.target === c.target) === i);
   const [next, ...also] = unique;
   return { next: next ?? { step: "roadmap", reason: "every item on the roadmap has landed; close the release and plan the next" }, also };
 }
 
+/** 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;
+  if (config?.cruze === undefined) return null;
+  const standards = config.standards ?? FIRST_RELEASE;
+  if (compareVersions(standards, config.cruze) >= 0) return null;
+  return { step: "realign", target: config.cruze, reason: `the code meets Cruze ${standards}'s expectations, and the installed skills are ${config.cruze}` };
+}
+
 /** The project documents come first: nothing else can proceed without them. */
 function projectStep(view: ProjectView): NextStep | null {
   const docs: Array<{ path: string; missing: NextStep; unapproved: NextStep; changed: NextStep }> = [

package/src/domain/validation/plan_rules.ts

@@ -1,8 +1,10 @@
+import { insideModuleMap } from "../check/check_source.ts";
 import { factsOf, isUnbuilt } from "../elements.ts";
+import { matchesAny } from "../glob.ts";
 import { findIds, kindOf } from "../ids.ts";
 import type { MarkdownDoc } from "../markdown.ts";
 import type { Delta } from "../project/deltas.ts";
-import { isPlanned, readScope, readTasks, readTestPlan, type Scope } from "../project/plan_parts.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";
 
@@ -37,6 +39,7 @@ export function changePlanProblems(
       problems.push(error(path, task.line, "unknown-id", `${task.number} proves ${id}, which is not defined`));
     }
   }
+  problems.push(...outsideModuleMap(view, path, tasks, delta));
   for (const id of [...scope.delivers, ...scope.builds]) {
     if (kindOf(id) === "MOD") {
       const modulePaths = modulePathsOf(view, delta.doc, delta.delta, id);
@@ -103,3 +106,17 @@ function factsOfScoped(view: ProjectView, doc: MarkdownDoc, delta: Delta, id: st
 function modulePathsOf(view: ProjectView, doc: MarkdownDoc, delta: Delta, id: string): string[] {
   return (factsOfScoped(view, doc, delta, id).get("Path") ?? []).flatMap((value) => [...value.matchAll(/`([^`]+)`/g)].map((m) => m[1] ?? "")).filter((p) => p !== "");
 }
+
+/** Task paths that `cruze check` would report as outside every module, caught while the plan can still fix the module map. */
+function outsideModuleMap(view: ProjectView, path: string, tasks: Task[], delta: { delta: Delta; doc: MarkdownDoc }): Problem[] {
+  const source = view.config?.config?.source ?? [];
+  const removed = new Set(delta.delta.entries.filter((e) => e.element.op === "REMOVED").map((e) => e.element.id));
+  const modules = new Set([...view.living.elements.keys(), ...delta.delta.entries.map((e) => e.element.id)].filter((id) => kindOf(id) === "MOD" && !removed.has(id)));
+  const modulePaths = [...modules].flatMap((id) => modulePathsOf(view, delta.doc, delta.delta, id));
+  if (modulePaths.length === 0) return [];
+  return tasks.flatMap((task) =>
+    task.paths
+      .filter((file) => matchesAny(file, source) && !insideModuleMap(file, modulePaths))
+      .map((file) => warning(path, task.line, "outside-module-map", `${task.number} writes ${file}, which no module's Path covers; add it to a module's Path or move the file`)),
+  );
+}

package/src/domain/validation/project_rules.ts

@@ -7,7 +7,7 @@ import { readRoadmapItems } from "../project/roadmap.ts";
 import type { ProjectView } from "../project/project_view.ts";
 import { error, warning, type Problem } from "./problem.ts";
 
-/** Rules that span the project: leftover template guides, the roadmap and the config. */
+/** Rules that span the project: leftover template guides, the roadmap, the config and the README. */
 
 const GUIDE = /(?<!`)<(?!!--|\/|https?:|br\b)[A-Za-z][^<>\n]*>(?!`)/;
 const PLACEHOLDER = /\{\{[a-z_]+\}\}/;
@@ -97,3 +97,19 @@ export function configProblems(view: ProjectView): Problem[] {
 function modulePaths(doc: MarkdownDoc, element: Parameters<typeof factsOf>[1]): string[] {
   return (factsOf(doc, element).get("Path") ?? []).flatMap((value) => [...value.matchAll(/`([^`]+)`/g)].map((m) => m[1] ?? ""));
 }
+
+/**
+ * Once the vision is approved, the README says what the project is under its title.
+ * Images, badges and HTML lines don't count as that overview.
+ */
+export function readmeProblems(view: ProjectView): Problem[] {
+  const text = view.snapshot.get(PATHS.readme);
+  const visionApproved = [...view.approvals.values()].some((file) => file.approvals.some((record) => record.artifact === PATHS.vision));
+  if (text === undefined || !visionApproved) return [];
+  const doc = parseMarkdown(text);
+  const title = doc.lines.findIndex((line) => /^# /.test(line));
+  const next = doc.lines.findIndex((line, i) => i > title && /^#{1,6} /.test(line));
+  const intro = doc.lines.slice(title + 1, next === -1 ? undefined : next);
+  const overview = intro.some((line, i) => !doc.inFence[title + 1 + i] && line.trim() !== "" && !/^\s*(!\[|\[!\[|<)/.test(line));
+  return overview ? [] : [warning(PATHS.readme, Math.max(title, 0), "readme-overview", "add a paragraph under the title saying what the project is, who it is for and why, from docs/vision.md")];
+}

package/src/domain/validation/validate_project.ts

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

package/src/domain/validation/work_item_rules.ts

@@ -56,6 +56,9 @@ function itemProblems(view: ProjectView, item: WorkItem): Problem[] {
 }
 
 /** A feature's Changes table covers its deltas, and each change folder agrees with its row. */
+/** More changes than this, and one design review can't hold the whole feature: contradictions slip through to plan. */
+const MAX_CHANGES = 6;
+
 function featureScopeProblems(view: ProjectView, feature: WorkItem, delta: Delta): Problem[] {
   const rows = readChangesTable(feature.doc);
   if (rows.length === 0) return [warning(feature.path, undefined, "not-designed", "the feature has no changes yet; architect designs and splits it")];
@@ -64,6 +67,10 @@ function featureScopeProblems(view: ProjectView, feature: WorkItem, delta: Delta
     [...readProgress(feature.doc).changes].filter(([, state]) => state === "landed").map(([change]) => change),
   );
   const names = rows.map((row) => row.change);
+  const extra = rows[MAX_CHANGES];
+  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`));
+  }
   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/ci_pin.ts

@@ -0,0 +1,40 @@
+/** The Cruze package CI runs through `npx --package=<spec>`, kept at the version the project installed. */
+
+export interface Repin {
+  text: string;
+  /** Each spec that now names the new version, as it reads after the edit. */
+  repinned: string[];
+  /** Specs Cruze doesn't know how to move, such as a branch or a local path, left as they were. */
+  unrecognised: string[];
+}
+
+const FORMS: Array<(spec: string, version: string) => string | null> = [
+  // The npm package: @printpractical/cruze@0.0.1
+  (spec, version) => (/^@printpractical\/cruze@[^/\s]+$/.test(spec) ? `@printpractical/cruze@${version}` : null),
+  // The release tarball: .../releases/download/v0.0.1/printpractical-cruze-0.0.1.tgz
+  (spec, version) => {
+    const m = /^(.*\/releases\/download\/)v[^/]+\/printpractical-cruze-[^/]+\.tgz$/.exec(spec);
+    return m === null ? null : `${m[1]}v${version}/printpractical-cruze-${version}.tgz`;
+  },
+  // The git repository at a release tag: github:PrintPractical/cruze#v0.0.1
+  (spec, version) => {
+    const m = /^(.*cruze(?:\.git)?)#v\d[^\s]*$/.exec(spec);
+    return m === null ? null : `${m[1]}#v${version}`;
+  },
+];
+
+/** Moves every `--package=<spec>` that runs Cruze in a CI workflow to the version. */
+export function repinCruze(ciText: string, version: string): Repin {
+  const repinned: string[] = [];
+  const unrecognised: string[] = [];
+  const text = ciText.replace(/--package=(\S+)(?=\s+cruze\b)/g, (whole, spec: string) => {
+    const moved = FORMS.map((form) => form(spec, version)).find((result) => result !== null);
+    if (moved === undefined || moved === null) {
+      if (!unrecognised.includes(spec)) unrecognised.push(spec);
+      return whole;
+    }
+    if (!repinned.includes(moved)) repinned.push(moved);
+    return `--package=${moved}`;
+  });
+  return { text, repinned, unrecognised };
+}

package/src/domain/versions/cruze_version.ts

@@ -0,0 +1,51 @@
+/** Which Cruze a project runs: recorded in `.cruze/config.yaml` by `cruze install`, compared with the CLI. */
+
+/** Orders two versions such as `0.0.1` and `0.1.0` by their numeric parts; a pre-release tag is ignored. */
+export function compareVersions(a: string, b: string): number {
+  const parts = (v: string): number[] => (v.split("-")[0] ?? "").split(".").map((p) => Number.parseInt(p, 10) || 0);
+  const [x, y] = [parts(a), parts(b)];
+  for (let i = 0; i < Math.max(x.length, y.length); i++) {
+    const diff = (x[i] ?? 0) - (y[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+export type VersionSkew =
+  | { kind: "unrecorded"; message: string }
+  | { kind: "skills-older"; recorded: string; message: string }
+  | { kind: "cli-older"; recorded: string; message: string };
+
+/** How the project's recorded Cruze differs from the CLI running now, or undefined when they match. */
+export function versionSkew(cli: string, recorded: string | undefined): VersionSkew | undefined {
+  if (recorded === undefined) {
+    return { kind: "unrecorded", message: `the project doesn't record which Cruze its skills came from; run \`cruze install\` to install the skills of this CLI (${cli}) and record it` };
+  }
+  const order = compareVersions(recorded, cli);
+  if (order < 0) {
+    return { kind: "skills-older", recorded, message: `the project's skills are from Cruze ${recorded}, older than this CLI (${cli}); run \`cruze install\` to update them and the CI pin` };
+  }
+  if (order > 0) {
+    return { kind: "cli-older", recorded, message: `the project uses Cruze ${recorded}, newer than this CLI (${cli}); upgrade the CLI as the README's "Upgrading" section says` };
+  }
+  return undefined;
+}
+
+/**
+ * The config text with `cruze:` set to the version. The line is replaced in place, or added
+ * after `version:`, so the file's comments and layout survive.
+ */
+export function withRecordedVersion(configText: string, version: string): string {
+  return withVersionLine(configText, "cruze", version);
+}
+
+/** The config text with a top-level version key, such as `cruze:` or `standards:`, set in place. */
+export function withVersionLine(configText: string, key: "cruze" | "standards", version: string): string {
+  const line = `${key}: ${JSON.stringify(version)}`;
+  const existing = new RegExp(`^${key}:.*$`, "m");
+  if (existing.test(configText)) return configText.replace(existing, line);
+  const anchor = key === "standards" ? /^cruze:.*$/m.exec(configText) ?? /^version:.*$/m.exec(configText) : /^version:.*$/m.exec(configText);
+  if (anchor === null) return `${line}\n${configText}`;
+  const end = anchor.index + anchor[0].length;
+  return `${configText.slice(0, end)}\n${line}${configText.slice(end)}`;
+}

package/src/domain/versions/realign_notes.ts

@@ -0,0 +1,72 @@
+import { compareVersions } from "./cruze_version.ts";
+
+/**
+ * A realign note: one change in what Cruze expects of a project, shipped in
+ * `skills/realign/notes/<version>.md` so `realign` can bring existing code up to it.
+ */
+export interface RealignNote {
+  id: string;
+  title: string;
+  version: string;
+  /** Whether existing code and documents must change, or only new work follows it. */
+  appliesTo: "existing" | "new";
+  /** Where the rule lives, such as a skill file and its heading. */
+  rule: string;
+  /** A CLI rule that finds it mechanically, as `<command>:<rule>`. */
+  detect?: string;
+  /** The question an auditor answers when no CLI rule can. */
+  ask?: string;
+  migrate?: string;
+}
+
+export interface ParsedNotes {
+  notes: RealignNote[];
+  problems: string[];
+}
+
+const APPLIES: Record<string, RealignNote["appliesTo"]> = { "existing code": "existing", "new work only": "new" };
+
+/** Parses one version's notes file. Each note is a `### <id>: <title>` heading with facts under it. */
+export function parseRealignNotes(version: string, text: string): ParsedNotes {
+  const notes: RealignNote[] = [];
+  const problems: string[] = [];
+  const sections = text.split(/^### /m).slice(1);
+  for (const section of sections) {
+    const [heading = "", ...body] = section.split("\n");
+    const match = /^([a-z0-9]+(?:-[a-z0-9]+)*): (.+)$/.exec(heading.trim());
+    if (match === null) {
+      problems.push(`${version}: "### ${heading.trim()}" must read "### <id>: <title>"`);
+      continue;
+    }
+    const [, id = "", title = ""] = match;
+    const fact = (key: string): string | undefined => body.map((line) => new RegExp(`^- ${key}: (.+)$`).exec(line)?.[1]?.trim()).find((v) => v !== undefined);
+    const applies = APPLIES[fact("Applies to") ?? ""];
+    const rule = fact("Rule");
+    const detect = fact("Detect")?.replace(/`/g, "");
+    const ask = fact("Ask");
+    const migrate = fact("Migrate");
+    if (applies === undefined) problems.push(`${version} ${id}: "- Applies to:" must be "existing code" or "new work only"`);
+    if (rule === undefined) problems.push(`${version} ${id}: needs "- Rule:"`);
+    if (detect !== undefined && !/^(check|validate):[a-z-]+$/.test(detect)) problems.push(`${version} ${id}: "- Detect:" names a rule as check:<rule> or validate:<rule>`);
+    if (applies === "existing" && detect === undefined && ask === undefined) problems.push(`${version} ${id}: a note for existing code needs "- Detect:" or "- Ask:"`);
+    if (applies === "existing" && migrate === undefined) problems.push(`${version} ${id}: a note for existing code needs "- Migrate:"`);
+    notes.push({
+      id,
+      title,
+      version,
+      appliesTo: applies ?? "new",
+      rule: rule ?? "",
+      ...(detect === undefined ? {} : { detect }),
+      ...(ask === undefined ? {} : { ask }),
+      ...(migrate === undefined ? {} : { migrate }),
+    });
+  }
+  const ids = notes.map((n) => n.id);
+  ids.filter((id, i) => ids.indexOf(id) !== i).forEach((id) => problems.push(`${version}: note ${id} appears twice`));
+  return { notes, problems };
+}
+
+/** Notes after the version the code meets, up to and including the version installed. */
+export function notesBetween(notes: RealignNote[], standards: string, target: string): RealignNote[] {
+  return notes.filter((n) => compareVersions(n.version, standards) > 0 && compareVersions(n.version, target) <= 0);
+}

package/src/domain/versions/rule_versions.ts

@@ -0,0 +1,22 @@
+import { compareVersions } from "./cruze_version.ts";
+
+/** The first release of Cruze. A project that records no `standards:` meets its expectations. */
+export const FIRST_RELEASE = "0.0.1";
+
+/**
+ * The release that introduced each rule reporting on existing code, keyed as `<command>:<rule>`.
+ * A rule newer than the project's `standards:` still reports, but can't fail CI until the project realigns.
+ * Every entry needs a realign note in `skills/realign/notes/<version>.md`; the bundle lint checks it.
+ */
+export const RULE_SINCE: Record<string, string> = {
+  "check:test-placement": "0.0.2",
+  "validate:outside-module-map": "0.0.2",
+  "validate:readme-overview": "0.0.2",
+  "validate:feature-size": "0.0.2",
+};
+
+/** Whether a rule arrived after the version the project's code meets, so it waits for `realign`. */
+export function isPending(command: "check" | "validate", rule: string, standards: string): boolean {
+  const since = RULE_SINCE[`${command}:${rule}`];
+  return since !== undefined && compareVersions(since, standards) > 0;
+}

package/src/domain/versions/scheduled_exceptions.ts

@@ -0,0 +1,41 @@
+import { parseDocument, type Document } from "yaml";
+
+/**
+ * `check.exceptions` entries that `realign` adds for findings a prefactor change will fix,
+ * and that landing that change removes. Edited through the YAML document, so comments survive.
+ */
+
+export interface Scheduled {
+  path: string;
+  note: string;
+}
+
+const scheduledReason = (version: string, note: string, ref: string): string => `realign ${version} (${note}): scheduled in ${ref}`;
+
+/** The config text with an exception for each finding, naming the change that will fix it. */
+export function withScheduledExceptions(configText: string, version: string, ref: string, findings: Scheduled[]): string {
+  if (findings.length === 0) return configText;
+  const doc = parseDocument(configText);
+  const listed = new Set(((doc.getIn(["check", "exceptions"]) as { toJSON(): Array<{ path?: string }> } | undefined)?.toJSON() ?? []).map((e) => e.path));
+  for (const finding of findings.filter((f, i) => !listed.has(f.path) && findings.findIndex((o) => o.path === f.path) === i)) {
+    doc.addIn(["check", "exceptions"], doc.createNode({ path: finding.path, reason: scheduledReason(version, finding.note, ref) }));
+  }
+  return render(doc);
+}
+
+/** The config text without the exceptions scheduled in a change, once it lands; unchanged when it had none. */
+export function withoutScheduledExceptions(configText: string, ref: string): { text: string; removed: string[] } {
+  const doc = parseDocument(configText);
+  const exceptions = doc.getIn(["check", "exceptions"]) as { items: Array<{ toJSON(): { path?: string; reason?: string } }> } | undefined;
+  if (exceptions === undefined || !Array.isArray(exceptions.items)) return { text: configText, removed: [] };
+  const suffix = `: scheduled in ${ref}`;
+  const removed = exceptions.items.map((item) => item.toJSON()).filter((e) => e.reason?.endsWith(suffix)).map((e) => e.path ?? "");
+  if (removed.length === 0) return { text: configText, removed: [] };
+  exceptions.items = exceptions.items.filter((item) => !(item.toJSON().reason ?? "").endsWith(suffix));
+  return { text: render(doc), removed };
+}
+
+/** Renders without wrapping long lines or padding flow lists, so an edit changes only what it touches. */
+function render(doc: Document): string {
+  return doc.toString({ lineWidth: 0, flowCollectionPadding: false });
+}

package/templates/init/config.yaml

@@ -1,6 +1,10 @@
 # Cruze project configuration, created by cruze {{cruze_version}}.
 # The format is described in .agents/skills/cruze-formats/reference/config.md.
 version: 1
+# The Cruze whose skills this project installed. `cruze install` keeps it current.
+cruze: "{{cruze_version}}"
+# The Cruze whose expectations the code meets. `realign` moves it forward.
+standards: "{{cruze_version}}"
 project: {{project_name_quoted}}
 
 # Where work items are tracked. V1 supports markdown in the repository only.
@@ -25,9 +29,4 @@ layers: []
 # walking-skeleton change fills them in; `cruze land` copies them into AGENTS.md.
 commands: {}
 
-# How `cruze review` starts an agent in a fresh context to run a role, with the
-# prompt on standard input. The default lets Claude Code read the project and run
-# git and cruze. The verifier runs the system, so add the project's build and run
-# commands, such as "Bash(cargo:*)". For Codex, use ["codex", "exec", "-"].
-review:
-  command: ["claude", "-p", "--allowedTools", "Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git show:*) Bash(cruze:*)"]
+{{review_setting}}

package/templates/init/review/claude.yaml

@@ -0,0 +1,7 @@
+# How `cruze review` starts an agent in a fresh context to run a role, with the
+# prompt on standard input. This lets Claude Code read the project and run git
+# and cruze. The verifier runs the system, so add the project's build and run
+# commands, such as "Bash(cargo:*)". Without review.command, your agent runs each
+# role in a helper of its own.
+review:
+  command: ["claude", "-p", "--allowedTools", "Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git show:*) Bash(cruze:*)"]

package/templates/init/review/other.yaml

@@ -0,0 +1,7 @@
+# How `cruze review` starts an agent in a fresh context to run a role, with the
+# prompt on standard input. Without it, your agent runs each role in a helper
+# of its own. To have cruze review start one instead, set the command, such as
+# ["codex", "exec", "-"] for Codex or ["opencode", "run", "--agent", "plan"] for
+# OpenCode.
+# review:
+#   command: ["codex", "exec", "-"]

package/templates/init/CLAUDE.md

@@ -1 +0,0 @@
-@AGENTS.md