@printpractical/cruze 0.0.13 → 0.0.14

package/src/domain/validation/delta_rules.ts

@@ -1,81 +0,0 @@
-import { ARCHITECTURE_KINDS } from "../architecture_sections.ts";
-import { scopeOf } from "../ids.ts";
-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";
-
-/** Merge records use this key for a spec file a delta created. */
-export function capabilityKey(capability: string): string {
-  return `CAPABILITY-${capability}`;
-}
-
-/** Marks an element a landed change removed. */
-export const REMOVED_MARK = "removed";
-
-/** Rules for the spec and architecture deltas of a feature or standalone change. */
-export function deltaProblems(view: ProjectView, item: WorkItem): Problem[] {
-  const { path, doc } = item;
-  const delta = readDelta(doc);
-  const merged = view.approvals.get(item.folder)?.merged ?? {};
-  const problems: Problem[] = [];
-
-  for (const orphan of orphanDeltaElements(doc)) {
-    problems.push(error(path, orphan.start, "delta-shape", `${orphan.id} must sit under an ADDED, MODIFIED or REMOVED requirement`));
-  }
-  for (const { element, section, scenarios } of delta.entries) {
-    const allowed = section === "spec" ? element.kind === "REQ" : ARCHITECTURE_KINDS.includes(element.kind);
-    if (!allowed) problems.push(error(path, element.start, "delta-shape", `${element.id} does not belong in the ${section} delta`));
-    problems.push(...elementProblems(path, doc, element));
-    for (const scenario of scenarios) {
-      problems.push(...elementProblems(path, doc, scenario));
-      if (scopeOf(scenario.id) !== scopeOf(element.id)) {
-        problems.push(error(path, scenario.start, "id-scope", `${scenario.id} must share its requirement's scope`));
-      }
-      problems.push(...opProblems(view, path, scenario.id, "ADDED", scenario.start, merged, element.op === "ADDED"));
-    }
-    problems.push(...opProblems(view, path, element.id, element.op ?? "ADDED", element.start, merged, false));
-    if (element.kind === "REQ" && element.op === "ADDED") problems.push(...capabilityProblems(view, item, delta, element.id, element.start));
-  }
-  for (const op of delta.capabilities) {
-    if (view.snapshot.has(specPath(op.capability)) && merged[capabilityKey(op.capability)] === undefined) {
-      problems.push(error(path, op.start, "capability-exists", `capability ${op.capability} already has ${specPath(op.capability)}`));
-    }
-  }
-  problems.push(...deltaDecisionProblems(view, item));
-  return problems;
-}
-
-function opProblems(
-  view: ProjectView,
-  path: string,
-  id: string,
-  op: "ADDED" | "MODIFIED" | "REMOVED",
-  line: number,
-  merged: Record<string, string>,
-  underAddedRequirement: boolean,
-): Problem[] {
-  const exists = view.living.elements.has(id);
-  const mergedHere = merged[id] !== undefined;
-  if (view.retired.has(id)) return [error(path, line, "retired-id", `${id} was removed earlier and can never be reused`)];
-  if (op === "ADDED" && exists && !mergedHere) {
-    // A scenario under a MODIFIED requirement may already exist; only a new requirement's scenarios must be new.
-    if (!id.startsWith("SCN-") || underAddedRequirement) return [error(path, line, "delta-op", `ADDED ${id} already exists in the living docs`)];
-  }
-  if ((op === "MODIFIED" || op === "REMOVED") && !exists && merged[id] !== REMOVED_MARK) {
-    return [error(path, line, "delta-op", `${op} ${id} does not exist in the living docs`)];
-  }
-  return [];
-}
-
-function capabilityProblems(view: ProjectView, item: WorkItem, delta: Delta, id: string, line: number): Problem[] {
-  const capability = scopeOf(id);
-  if (capability === undefined) return [];
-  const hasFile = view.snapshot.has(specPath(capability));
-  const addsFile = delta.capabilities.some((op) => op.capability === capability);
-  if (hasFile || addsFile) return [];
-  return [error(item.path, line, "capability-missing", `${id} needs ${specPath(capability)}, or an "ADDED CAPABILITY ${capability}" operation`)];
-}

package/src/domain/validation/element_rules.ts

@@ -1,104 +0,0 @@
-import { factsOf, type Element } from "../elements.ts";
-import { findIds, scopeOf, SCOPED_KINDS, type Kind } from "../ids.ts";
-import type { MarkdownDoc } from "../markdown.ts";
-import { error, type Problem } from "./problem.ts";
-
-/** Rules for a single element's body, shared by living documents and deltas. */
-
-const REQUIRED_FACTS: Partial<Record<Kind, string[]>> = {
-  CTX: ["Purpose"],
-  ENT: ["Kind", "Module", "File"],
-  UC: ["Input", "Output", "Errors", "Uses", "Module", "File"],
-  PORT: ["Direction", "Operations", "Module", "File"],
-  ADP: ["Technology", "Module", "File"],
-  FLOW: ["Elements"],
-  MOD: ["Path", "Layer"],
-};
-
-const ALLOWED_VALUES: Record<string, { kinds: Kind[]; values: string[] }> = {
-  Kind: { kinds: ["ENT"], values: ["aggregate", "entity", "value", "service", "policy", "event"] },
-  Direction: { kinds: ["PORT"], values: ["driven", "driving"] },
-  Layer: { kinds: ["MOD"], values: ["core", "domain", "application", "adapter", "composition"] },
-};
-
-export function elementProblems(path: string, doc: MarkdownDoc, element: Element): Problem[] {
-  const problems: Problem[] = [];
-  if (SCOPED_KINDS.includes(element.kind) && scopeOf(element.id) === undefined) {
-    problems.push(error(path, element.start, "id-scope", `${element.id} needs a scope: ${element.kind}-<scope>.<name>`));
-  }
-  if (element.op === "REMOVED") return [...problems, ...removedProblems(path, doc, element)];
-
-  const facts = factsOf(doc, element);
-  for (const key of REQUIRED_FACTS[element.kind] ?? []) {
-    if (!facts.has(key)) problems.push(error(path, element.start, "required-fact", `${element.id} is missing "- ${key}:"`));
-  }
-  if (element.kind === "ADP" && !facts.has("Implements") && !facts.has("Drives")) {
-    problems.push(error(path, element.start, "required-fact", `${element.id} needs "- Implements:" or "- Drives:"`));
-  }
-  for (const [key, rule] of Object.entries(ALLOWED_VALUES)) {
-    const value = facts.get(key)?.[0];
-    if (rule.kinds.includes(element.kind) && value !== undefined && !rule.values.includes(value)) {
-      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`));
-  }
-  if (element.kind === "FLOW" && !bodyText(doc, element).includes("sequenceDiagram")) {
-    problems.push(error(path, element.start, "flow-diagram", `${element.id} needs a Mermaid sequenceDiagram`));
-  }
-  if (element.kind === "REQ") problems.push(...requirementProblems(path, doc, element));
-  if (element.kind === "SCN") problems.push(...scenarioProblems(path, doc, element));
-  return problems;
-}
-
-function removedProblems(path: string, doc: MarkdownDoc, element: Element): Problem[] {
-  const facts = factsOf(doc, element);
-  const problems: Problem[] = [];
-  if (!facts.has("Reason")) problems.push(error(path, element.start, "removed-reason", `REMOVED ${element.id} needs "- Reason:"`));
-  if (element.kind === "REQ" && !facts.has("Migration")) {
-    problems.push(error(path, element.start, "removed-reason", `REMOVED ${element.id} needs "- Migration:"`));
-  }
-  return problems;
-}
-
-function requirementProblems(path: string, doc: MarkdownDoc, element: Element): Problem[] {
-  const problems: Problem[] = [];
-  const ownBody = ownLines(doc, element).join("\n");
-  if (!/\b(SHALL|MUST)\b/.test(ownBody)) problems.push(error(path, element.start, "req-keyword", `${element.id} must state SHALL or MUST`));
-  const hasScenario = doc.headings.some((h) => h.line > element.start && h.line < element.end && h.level === element.level + 1 && h.text.startsWith("SCN-"));
-  if (!hasScenario) problems.push(error(path, element.start, "req-scenario", `${element.id} needs at least one scenario`));
-  return problems;
-}
-
-function scenarioProblems(path: string, doc: MarkdownDoc, element: Element): Problem[] {
-  const steps = ownLines(doc, element)
-    .map((line) => /^- (GIVEN|WHEN|THEN|AND) /.exec(line)?.[1])
-    .filter((step) => step !== undefined);
-  const order = steps.filter((step) => step !== "AND").join(" ");
-  if (!/^(GIVEN )*WHEN( THEN)+$/.test(order)) {
-    return [error(path, element.start, "scenario-steps", `${element.id} needs GIVEN steps (optional), one WHEN, then one or more THEN`)];
-  }
-  if (steps[0] === "AND") return [error(path, element.start, "scenario-steps", `${element.id} cannot start with AND`)];
-  return [];
-}
-
-/** The element's lines before its first nested heading, without the heading itself. */
-function ownLines(doc: MarkdownDoc, element: Element): string[] {
-  const lines: string[] = [];
-  for (let i = element.start + 1; i < element.end; i++) {
-    if (!doc.inFence[i] && /^#{1,6} /.test(doc.lines[i] ?? "")) break;
-    lines.push(doc.lines[i] ?? "");
-  }
-  return lines;
-}
-
-function bodyText(doc: MarkdownDoc, element: Element): string {
-  return doc.lines.slice(element.start, element.end).join("\n");
-}

package/src/domain/validation/future_rules.ts

@@ -1,40 +0,0 @@
-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

@@ -1,99 +0,0 @@
-import { ARCHITECTURE_KINDS, sectionForKind } from "../architecture_sections.ts";
-import { headingElements, statusOf, type Element } from "../elements.ts";
-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";
-
-/** Rules for the living docs: vision, architecture, specs, ADRs and the IDs they cite. */
-export function livingProblems(view: ProjectView): Problem[] {
-  const problems: Problem[] = [];
-  for (const { id, places } of view.living.duplicates) {
-    problems.push(error(places[0]?.split(":")[0] ?? "", undefined, "duplicate-id", `${id} is defined more than once: ${places.join(", ")}`));
-  }
-  for (const [path, doc] of view.living.docs) {
-    problems.push(...malformedIdHeadings(path, doc));
-    if (path === PATHS.architecture) problems.push(...architectureProblems(path, doc, everApproved(view, path)));
-    else if (path.startsWith(`${PATHS.specsDir}/`)) problems.push(...specProblems(path, doc));
-    else if (path.startsWith(`${PATHS.adrDir}/`)) problems.push(...adrProblems(path, doc));
-  }
-  for (const path of [...view.living.docs.keys(), PATHS.roadmap]) {
-    const text = view.snapshot.get(path);
-    if (text === undefined) continue;
-    for (const id of findIds(text)) {
-      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;
-}
-
-/** A heading shaped like `<KIND>-...: Title` whose ID breaks the grammar. */
-export function malformedIdHeadings(path: string, doc: MarkdownDoc): Problem[] {
-  return doc.headings.flatMap((heading) => {
-    const match = /^(?:(?:ADDED|MODIFIED|REMOVED) )?([A-Z]{2,5}-\S*):\s/.exec(heading.text);
-    if (match?.[1] === undefined || findIds(match[1])[0] === match[1]) return [];
-    return [error(path, heading.line, "malformed-id", `"${match[1]}" is not a valid ID`)];
-  });
-}
-
-/** Statuses are stamped by the first approval, so their absence before it is expected. */
-function everApproved(view: ProjectView, path: string): boolean {
-  return [...view.approvals.values()].some((file) => file.approvals.some((record) => record.artifact === path));
-}
-
-function architectureProblems(path: string, doc: MarkdownDoc, approved: boolean): Problem[] {
-  const problems: Problem[] = [];
-  for (const element of headingElements(doc)) {
-    const section = [...doc.headings].reverse().find((h) => h.level === 2 && h.line < element.start);
-    if (!ARCHITECTURE_KINDS.includes(element.kind)) {
-      problems.push(error(path, element.start, "misplaced-element", `${element.id} does not belong in the architecture`));
-    } else if (element.kind !== "VIEW" && section?.text !== sectionForKind(element.kind)) {
-      problems.push(error(path, element.start, "misplaced-element", `${element.id} belongs under "## ${sectionForKind(element.kind)}"`));
-    }
-    problems.push(...elementProblems(path, doc, element), ...(approved ? statusProblems(path, doc, element) : []));
-  }
-  return problems;
-}
-
-function specProblems(path: string, doc: MarkdownDoc): Problem[] {
-  const capability = path.slice(path.lastIndexOf("/") + 1, -".md".length);
-  const problems: Problem[] = [];
-  const elements = headingElements(doc);
-  for (const element of elements) {
-    const expectedLevel = element.kind === "REQ" ? 2 : element.kind === "SCN" ? 3 : 0;
-    if (expectedLevel === 0) problems.push(error(path, element.start, "misplaced-element", `${element.id} does not belong in a spec`));
-    else if (element.level !== expectedLevel) problems.push(error(path, element.start, "heading-level", `${element.id} must be a level ${expectedLevel} heading`));
-    if (scopeOf(element.id) !== undefined && scopeOf(element.id) !== capability) {
-      problems.push(error(path, element.start, "id-scope", `${element.id} must use the scope "${capability}", the capability of this file`));
-    }
-    problems.push(...elementProblems(path, doc, element), ...statusProblems(path, doc, element));
-  }
-  return problems;
-}
-
-function adrProblems(path: string, doc: MarkdownDoc): Problem[] {
-  const text = doc.lines.join("\n");
-  return ["Status", "Date"]
-    .filter((key) => !new RegExp(`^- ${key}: `, "m").test(text))
-    .map((key) => error(path, undefined, "adr-fact", `the ADR is missing "- ${key}:"`));
-}
-
-function statusProblems(path: string, doc: MarkdownDoc, element: Element): Problem[] {
-  const status = statusOf(doc, element);
-  if (STATUS_KINDS.includes(element.kind) && status === undefined) {
-    return [warning(path, element.start, "missing-status", `${element.id} has no status yet; approving the document adds it`)];
-  }
-  if (!STATUS_KINDS.includes(element.kind) && status !== undefined) {
-    return [error(path, element.start, "unexpected-status", `${element.id} is not a kind that carries a status`)];
-  }
-  return [];
-}
-
-export function lineOf(text: string, needle: string): number | undefined {
-  const index = text.indexOf(needle);
-  return index === -1 ? undefined : text.slice(0, index).split("\n").length - 1;
-}

package/src/domain/validation/plan_rules.ts

@@ -1,124 +0,0 @@
-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, 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"];
-
-/**
- * Rules for one buildable change: its scope names only things that can be built. Once it is
- * planned, every scope ID is proved by a task, every delivered scenario has a behaviour test,
- * and every port a built adapter implements has a contract test.
- */
-export function changePlanProblems(
-  view: ProjectView,
-  path: string,
-  doc: MarkdownDoc,
-  delta: { delta: Delta; doc: MarkdownDoc },
-  available: Set<string>,
-): Problem[] {
-  const scope = readScope(doc);
-  if (scope === null) return [error(path, undefined, "missing-section", 'the change needs a "## Scope" section')];
-  const problems: Problem[] = [...scopeTargetProblems(view, path, scope, delta.delta)];
-  if (!isPlanned(doc)) return [...problems, warning(path, undefined, "not-planned", "the change has no test plan or tasks yet; plan fills them")];
-  const { tasks, malformed } = readTasks(doc);
-  for (const line of malformed) {
-    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);
-  for (const task of tasks) {
-    for (const id of task.proves.filter((id) => !available.has(id))) {
-      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);
-      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"}; 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) ?? [];
-      if (!proved.has(id) && !scenarios.some((s) => proved.has(s))) problems.push(error(path, scope.line, "unproved-scope", `no task proves ${id} or its scenarios`));
-    } else if (!proved.has(id)) {
-      problems.push(error(path, scope.line, "unproved-scope", `${id} is in scope but no task proves it`));
-    }
-  }
-
-  const rows = readTestPlan(doc);
-  for (const row of rows) {
-    if (!TEST_KINDS.includes(row.kind)) problems.push(error(path, row.line, "test-kind", `test kind must be one of ${TEST_KINDS.join(", ")}`));
-    const subject = findIds(row.subject)[0];
-    if (subject === undefined || !available.has(subject)) problems.push(error(path, row.line, "unknown-id", `test subject "${row.subject}" is not a defined ID`));
-    if (row.file === "") problems.push(error(path, row.line, "test-file", "every test plan row names its test file"));
-  }
-  for (const id of scope.delivers.filter((id) => kindOf(id) === "SCN")) {
-    if (!rows.some((row) => findIds(row.subject)[0] === id && row.kind === "behaviour")) {
-      problems.push(error(path, scope.line, "missing-behaviour-test", `${id} is delivered but has no behaviour row in the test plan`));
-    }
-  }
-  for (const adapter of scope.builds.filter((id) => kindOf(id) === "ADP")) {
-    const ports = (factsOfScoped(view, delta.doc, delta.delta, adapter).get("Implements") ?? []).flatMap(findIds).filter((id) => kindOf(id) === "PORT");
-    for (const port of ports.filter((p) => !rows.some((row) => findIds(row.subject)[0] === p && row.kind === "contract"))) {
-      problems.push(error(path, scope.line, "missing-contract-test", `${adapter} implements ${port} but the test plan has no contract row for ${port}`));
-    }
-  }
-  return problems;
-}
-
-/** Scope IDs must come from the item's deltas or be planned in the living docs. */
-function scopeTargetProblems(view: ProjectView, path: string, scope: Scope, delta: Delta): Problem[] {
-  const problems: Problem[] = [];
-  for (const id of [...scope.delivers, ...scope.builds]) {
-    if (delta.ids.has(id)) continue;
-    const living = view.living.elements.get(id);
-    if (living === undefined) problems.push(error(path, scope.line, "unknown-id", `${id} is in scope but defined nowhere`));
-    else if (!isUnbuilt(living.doc, living.element)) {
-      problems.push(error(path, scope.line, "scope-not-planned", `${id} is already built; change it through a MODIFIED operation in the delta`));
-    }
-  }
-  for (const id of scope.removes) {
-    const removal = delta.entries.find((e) => e.element.id === id && e.element.op === "REMOVED");
-    if (removal === undefined) problems.push(error(path, scope.line, "scope-removes", `${id} is in Removes but the delta has no REMOVED operation for it`));
-  }
-  if (scope.delivers.length + scope.builds.length + scope.removes.length === 0) {
-    problems.push(warning(path, scope.line, "empty-scope", "the scope delivers and builds nothing"));
-  }
-  return problems;
-}
-
-/** An element's facts as this item will build it: from its delta when it has one, else from the living docs. */
-function factsOfScoped(view: ProjectView, doc: MarkdownDoc, delta: Delta, id: string): Map<string, string[]> {
-  const fromDelta = delta.entries.find((e) => e.element.id === id);
-  const living = view.living.elements.get(id);
-  return fromDelta !== undefined ? factsOf(doc, fromDelta.element) : living !== undefined ? factsOf(living.doc, living.element) : new Map<string, string[]>();
-}
-
-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

@@ -1,115 +0,0 @@
-import { factsOf } from "../elements.ts";
-import { matchesAny } from "../glob.ts";
-import { findIds } from "../ids.ts";
-import { parseMarkdown, type MarkdownDoc } from "../markdown.ts";
-import { PATHS } from "../project/layout.ts";
-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, the config and the README. */
-
-const GUIDE = /(?<!`)<(?!!--|\/|https?:|br\b)[A-Za-z][^<>\n]*>(?!`)/;
-const PLACEHOLDER = /\{\{[a-z_]+\}\}/;
-
-/**
- * Unfilled `<guides>` and `{{placeholders}}` outside code, in living docs and active work.
- * Managed blocks are skipped: the CLI writes them, and they may quote text such as `<COMMAND>`.
- */
-export function templateLeftovers(view: ProjectView): Problem[] {
-  const paths = [...view.living.docs.keys(), PATHS.roadmap, PATHS.glossary, ...view.items.filter((i) => !i.archived).map((i) => i.path)];
-  return paths.flatMap((path) => {
-    const text = view.snapshot.get(path);
-    if (text === undefined) return [];
-    const doc = parseMarkdown(text);
-    return doc.lines.flatMap((line, i) => {
-      if (doc.inFence[i] || doc.inManaged[i]) return [];
-      const withoutCode = line.replace(/`[^`]*`/g, "");
-      if (GUIDE.test(withoutCode) || PLACEHOLDER.test(withoutCode)) {
-        return [error(path, i, "template-leftover", "replace the template guide or placeholder on this line")];
-      }
-      return [];
-    });
-  });
-}
-
-export function roadmapProblems(view: ProjectView): Problem[] {
-  const text = view.snapshot.get(PATHS.roadmap);
-  if (text === undefined) return [];
-  const doc = parseMarkdown(text);
-  const problems: Problem[] = [];
-  const items = new Map<string, { blockedBy: string[]; line: number }>();
-  for (const { slug: item, kind, blockedBy, line } of readRoadmapItems(text)) {
-    if (items.has(item)) problems.push(error(PATHS.roadmap, line, "roadmap-item", `item ${item} appears twice`));
-    if (!["feature", "change"].includes(kind)) problems.push(error(PATHS.roadmap, line, "roadmap-item", `item ${item} kind must be feature or change`));
-    items.set(item, { blockedBy, line });
-  }
-  for (const [item, { blockedBy, line }] of items) {
-    for (const blocker of blockedBy.filter((b) => !items.has(b))) problems.push(error(PATHS.roadmap, line, "roadmap-blocker", `${item} is blocked by unknown item ${blocker}`));
-  }
-  const cycle = findCycle(items);
-  if (cycle !== null) problems.push(error(PATHS.roadmap, undefined, "roadmap-cycle", `blocking cycle: ${cycle.join(" -> ")}`));
-  const coverage = doc.lines.join("\n").split(/^## Coverage$/m)[1] ?? "";
-  for (const goal of [...view.living.elements.keys()].filter((id) => id.startsWith("GOAL-"))) {
-    if (!findIds(coverage).includes(goal)) problems.push(warning(PATHS.roadmap, undefined, "goal-uncovered", `${goal} has no items in the coverage table`));
-  }
-  return problems;
-}
-
-function findCycle(items: Map<string, { blockedBy: string[] }>): string[] | null {
-  const state = new Map<string, "visiting" | "done">();
-  const visit = (item: string, path: string[]): string[] | null => {
-    if (state.get(item) === "done") return null;
-    if (state.get(item) === "visiting") return [...path.slice(path.indexOf(item)), item];
-    state.set(item, "visiting");
-    for (const next of items.get(item)?.blockedBy ?? []) {
-      const found = visit(next, [...path, item]);
-      if (found !== null) return found;
-    }
-    state.set(item, "done");
-    return null;
-  };
-  for (const item of items.keys()) {
-    const found = visit(item, []);
-    if (found !== null) return found;
-  }
-  return null;
-}
-
-export function configProblems(view: ProjectView): Problem[] {
-  if (view.config === null) return [error(PATHS.config, undefined, "config-missing", "the project has no .cruze/config.yaml; run cruze init")];
-  const problems = view.config.problems.map((message) => error(PATHS.config, undefined, "config", message));
-  const config = view.config.config;
-  const architecture = view.living.docs.get(PATHS.architecture);
-  if (config === null || architecture === undefined || config.layers.length === 0) return problems;
-  for (const { element } of [...view.living.elements.values()].filter((e) => e.id.startsWith("MOD-"))) {
-    for (const path of modulePaths(architecture, element)) {
-      const probe = path.endsWith("/") ? `${path}probe.file` : path;
-      const layers = config.layers.filter((layer) => matchesAny(probe, layer.paths));
-      if (layers.length !== 1) {
-        problems.push(warning(PATHS.config, undefined, "module-layer", `${element.id} path ${path} falls in ${layers.length} layers; it should fall in exactly one`));
-      }
-    }
-  }
-  return problems;
-}
-
-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/size_rules.ts

@@ -1,45 +0,0 @@
-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;
-}
-
-/** 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, 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) && !sizeAccepted(view, `${feature.ref}/${r.change}`))) {
-    if (rows.length > 1 && row.builds.length < limits.minBuilds) {
-      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(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;
-}
-
-/** 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);
-  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/vision_rules.ts

@@ -1,41 +0,0 @@
-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 [];
-  });
-}