@printpractical/cruze 0.0.13 → 0.0.14

package/src/domain/validation/work_item_rules.ts

@@ -1,175 +0,0 @@
-import { isUnbuilt } from "../elements.ts";
-import { findIds, kindOf } from "../ids.ts";
-import { elementHash } from "../hashing.ts";
-import { findSection, type MarkdownDoc } from "../markdown.ts";
-import { readDelta, type Delta } from "../project/deltas.ts";
-import { readChangesTable, readScope } from "../project/plan_parts.ts";
-import { readProgress } from "../project/progress.ts";
-import type { ProjectView } from "../project/project_view.ts";
-import { changesOf, featureOf, type WorkItem } from "../project/work_items.ts";
-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, sizeAccepted } from "./size_rules.ts";
-
-const REQUIRED_SECTIONS: Record<WorkItem["kind"], string[]> = {
-  feature: ["Intent", "Spec delta", "Architecture delta", "Changes"],
-  change: ["Scope", "Test plan", "Tasks"],
-  standalone: ["Intent", "Spec delta", "Architecture delta", "Scope", "Test plan", "Tasks"],
-};
-
-/** Rules for every active feature and change. Archived work is history and is not checked. */
-export function workItemProblems(view: ProjectView): Problem[] {
-  return view.items.filter((item) => !item.archived).flatMap((item) => itemProblems(view, item));
-}
-
-function itemProblems(view: ProjectView, item: WorkItem): Problem[] {
-  const { path, doc } = item;
-  const problems: Problem[] = [...malformedIdHeadings(path, doc)];
-  const id = doc.frontmatter?.["id"];
-  if (id !== item.folderName) problems.push(error(path, 0, "frontmatter", `frontmatter id must be "${item.folderName}", the folder name`));
-  const title = doc.frontmatter?.["title"];
-  if (typeof title !== "string" || title.trim() === "") problems.push(error(path, 0, "frontmatter", "frontmatter needs a title"));
-  for (const section of REQUIRED_SECTIONS[item.kind]) {
-    if (findSection(doc, section) === null) problems.push(error(path, undefined, "missing-section", `missing "## ${section}"`));
-  }
-
-  const feature = item.kind === "change" ? featureOf(view.items, item) : undefined;
-  if (item.kind === "change" && feature === undefined) problems.push(error(path, undefined, "orphan-change", "the change's feature.md is missing"));
-  const deltaSource = item.kind === "change" ? feature : item;
-  const delta = deltaSource === undefined ? readDelta(doc) : readDelta(deltaSource.doc);
-  const available = new Set([...view.living.elements.keys(), ...delta.ids]);
-
-  const text = doc.lines.join("\n");
-  for (const cited of findIds(text).filter((cited) => !available.has(cited))) {
-    problems.push(error(path, lineOf(text, cited), "unknown-id", `${cited} is cited but defined neither in the living docs nor in this work's deltas`));
-  }
-  const dropped = droppedScenarios(view, delta);
-  for (const cited of findIds(text).filter((cited) => dropped.has(cited))) {
-    problems.push(error(path, lineOf(text, cited), "cites-dropped", `${cited} is cited, but ${dropped.get(cited)} in this work's delta leaves it out, so it won't exist once the work lands; describe it in words instead`));
-  }
-  if (item.kind !== "change") problems.push(...deltaProblems(view, item));
-  if (item.kind === "feature") problems.push(...featureScopeProblems(view, item, delta));
-  // A landed change is history: its scope named what it built, which is now built.
-  const landed = item.kind !== "feature" && readProgress(doc).landed !== undefined;
-  if (item.kind !== "feature" && deltaSource !== undefined && !landed) {
-    problems.push(...changePlanProblems(view, path, doc, { delta, doc: deltaSource.doc }, available));
-  }
-  if (item.kind === "standalone") problems.push(...coverageProblems(view, path, delta, doc, [{ name: "this change", ids: scopeIds(item) }]));
-  return problems;
-}
-
-/** 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")];
-  const problems: Problem[] = [];
-  const landedChanges = new Set(
-    [...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 && !sizeAccepted(view, feature.ref)) {
-    problems.push(warning(feature.path, extra.line, "feature-size", `the feature has ${rows.length} changes, over ${MAX_CHANGES}; split it into features a single design review can hold`));
-  }
-  problems.push(...changeRowSizeProblems(view, feature, 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`));
-    for (const dependency of row.dependsOn) {
-      const at = names.indexOf(dependency);
-      if (at === -1 || at >= names.indexOf(row.change)) problems.push(error(feature.path, row.line, "change-order", `${row.change} depends on ${dependency}, which must be an earlier change`));
-    }
-    for (const id of landedChanges.has(row.change) ? [] : [...row.delivers, ...row.builds]) {
-      const living = view.living.elements.get(id);
-      const planned = living !== undefined && isUnbuilt(living.doc, living.element);
-      if (!delta.ids.has(id) && !planned) problems.push(error(feature.path, row.line, "scope-not-planned", `${id} must come from this feature's deltas or be planned in the living docs`));
-    }
-  }
-  problems.push(...coverageProblems(view, feature.path, delta, feature.doc, rows.map((row) => ({ name: row.change, ids: [...row.delivers, ...row.builds, ...row.removes], landed: landedChanges.has(row.change) }))));
-
-  for (const change of changesOf(view.items, feature)) {
-    const row = rows.find((r) => r.change === change.folderName);
-    if (row === undefined) {
-      problems.push(error(change.path, undefined, "change-not-listed", `${change.folderName} is not in the feature's Changes table`));
-      continue;
-    }
-    const expected = new Set([...row.delivers, ...row.builds, ...row.removes]);
-    const actual = new Set(scopeIds(change));
-    const differ = [...expected].filter((id) => !actual.has(id)).concat([...actual].filter((id) => !expected.has(id)));
-    if (differ.length > 0) problems.push(error(change.path, readScope(change.doc)?.line, "scope-mismatch", `Scope differs from the feature's Changes row: ${differ.join(", ")}`));
-  }
-  return problems;
-}
-
-/**
- * Every delta ID lands exactly once. A requirement is covered by its own ID or one of its
- * scenarios. A scenario must be covered when it is new or its text changed; an unchanged
- * scenario kept by a MODIFIED requirement may be left out.
- */
-function coverageProblems(
-  view: ProjectView,
-  path: string,
-  delta: Delta,
-  deltaDoc: MarkdownDoc,
-  groups: Array<{ name: string; ids: string[]; landed?: boolean }>,
-): Problem[] {
-  const coveredBy = new Map<string, string[]>();
-  const pendingBy = new Map<string, string[]>();
-  for (const group of groups) {
-    for (const id of group.ids) {
-      coveredBy.set(id, [...(coveredBy.get(id) ?? []), group.name]);
-      if (group.landed !== true) pendingBy.set(id, [...(pendingBy.get(id) ?? []), group.name]);
-    }
-  }
-  const problems: Problem[] = [];
-  // A change that already landed may be followed by one that rebuilds the same element after a rethink.
-  const once = (id: string, line: number, required: boolean): void => {
-    const pending = pendingBy.get(id) ?? [];
-    if (required && (coveredBy.get(id) ?? []).length === 0) problems.push(error(path, line, "uncovered", `${id} is not in any change's scope`));
-    if (pending.length > 1) problems.push(error(path, line, "covered-twice", `${id} is in the scope of ${pending.join(" and ")}; it must land exactly once`));
-  };
-  for (const { element, scenarios } of delta.entries) {
-    if (kindOf(element.id) !== "REQ") {
-      once(element.id, element.start, true);
-      continue;
-    }
-    once(element.id, element.start, false);
-    if (![element.id, ...scenarios.map((s) => s.id)].some((id) => coveredBy.has(id))) {
-      problems.push(error(path, element.start, "uncovered", `${element.id} is not delivered by any change`));
-    }
-    for (const scenario of scenarios) {
-      const living = view.living.elements.get(scenario.id);
-      const changed = living === undefined || elementHash(living.doc, living.element) !== elementHash(deltaDoc, scenario);
-      once(scenario.id, scenario.start, element.op !== "REMOVED" && changed);
-    }
-  }
-  return problems;
-}
-
-function scopeIds(item: WorkItem): string[] {
-  const scope = readScope(item.doc);
-  return scope === null ? [] : [...scope.delivers, ...scope.builds, ...scope.removes];
-}
-
-/**
- * Living scenarios that a MODIFIED requirement in the delta leaves out, each with that requirement.
- * Land drops them, so a citation of one passes validation now and breaks only at land.
- */
-function droppedScenarios(view: ProjectView, delta: Delta): Map<string, string> {
-  const dropped = new Map<string, string>();
-  for (const entry of delta.entries.filter((e) => e.element.op === "MODIFIED" && kindOf(e.element.id) === "REQ")) {
-    const living = view.living.elements.get(entry.element.id);
-    if (living === undefined) continue;
-    const kept = new Set(entry.scenarios.map((s) => s.id));
-    for (const scenario of view.living.elements.values()) {
-      const nested = scenario.doc === living.doc && scenario.element.start > living.element.start && scenario.element.start < living.element.end;
-      if (nested && kindOf(scenario.id) === "SCN" && !kept.has(scenario.id) && !delta.ids.has(scenario.id)) dropped.set(scenario.id, entry.element.id);
-    }
-  }
-  return dropped;
-}

package/src/domain/versions/realign_notes.ts

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

@@ -1,29 +0,0 @@
-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",
-  "validate:change-too-small": "0.0.5",
-  "validate:change-too-large": "0.0.5",
-  "validate:plan-too-large": "0.0.5",
-  "validate:module-path-glob": "0.0.8",
-  "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`. */
-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

@@ -1,41 +0,0 @@
-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/gitattributes

@@ -1,2 +0,0 @@
-# Cruze journals are append-only, so parallel branches merge them by keeping every line.
-**/journal.jsonl merge=union