@printpractical/cruze 0.0.1

package/dist/app/use_cases/new_project_doc.js

@@ -0,0 +1,40 @@
+import { CruzeError } from "../../domain/cruze_error.js";
+import { PATHS } from "../../domain/project/layout.js";
+import { requireSlug } from "../../domain/project/new_items.js";
+import { renderTemplate } from "../../domain/scaffold.js";
+import { appendJournal, loadView,                  } from "../project_context.js";
+
+                                                                                
+
+export const PROJECT_DOC_KINDS                            = ["vision", "glossary", "architecture", "roadmap"];
+
+                               
+                                
+               
+ 
+
+/** Creates one of the project's living documents from its template, named for the project. */
+export async function createProjectDoc(deps             , kind                )                        {
+  const view = await loadView(deps.files);
+  const path = PATHS[kind];
+  if (view.snapshot.has(path)) throw new CruzeError("exists", `${path} already exists`);
+  const project = view.config?.config?.project ?? "";
+  if (project === "") throw new CruzeError("no-config", `${PATHS.config} is missing or has no project name; run cruze init first`);
+  const values = { project_name: project, id: "", title: "", date: deps.clock.today() };
+  await deps.files.writeText(path, renderTemplate(await deps.bundle.formatTemplate(`${kind}.md`), values));
+  await appendJournal(deps, ".cruze", "new", { kind, ref: path });
+  return { kind, path };
+}
+
+/** Creates a dated note in `.cruze/notes/`, such as a captured explore session or research evidence. */
+export async function createNote(deps             , slug        , title        )                        {
+  requireSlug(slug);
+  if (title.trim() === "") throw new CruzeError("missing-title", "a title is required");
+  const view = await loadView(deps.files);
+  const date = deps.clock.today();
+  const base = `${PATHS.notesDir}/${date}-${slug}`;
+  let path = `${base}.md`;
+  for (let n = 2; view.snapshot.has(path); n++) path = `${base}-${n}.md`;
+  await deps.files.writeText(path, `# ${title}\n\n- Date: ${date}\n\n`);
+  return { kind: "note", path };
+}

package/dist/app/use_cases/new_work_item.js

@@ -0,0 +1,75 @@
+import { CruzeError } from "../../domain/cruze_error.js";
+import { upsertRow } from "../../domain/edits/managed_tables.js";
+import { resolveArtifact } from "../../domain/project/artifact_ref.js";
+import { PATHS } from "../../domain/project/layout.js";
+import { allocateId, changeRow, fillTemplate, requireSlug } from "../../domain/project/new_items.js";
+import { renderTemplate } from "../../domain/scaffold.js";
+import { appendJournal, loadView,                  } from "../project_context.js";
+
+                                                   
+
+                             
+                
+               
+                
+                                                                                        
+                   
+                                                                                           
+                   
+ 
+
+                            
+                                                    
+              
+               
+ 
+
+/** Creates a feature, change or ADR from its template, with a fresh ID. */
+export async function createWorkItem(deps             , request            )                     {
+  const view = await loadView(deps.files);
+  const date = deps.clock.today();
+  const values = { id: "", title: request.title, date, project_name: "" };
+  if (request.title.trim() === "") throw new CruzeError("missing-title", "a title is required");
+
+  if (request.kind === "adr") {
+    requireSlug(request.slug);
+    const path = `${PATHS.adrDir}/${date}-${request.slug}.md`;
+    if (view.snapshot.has(path)) throw new CruzeError("exists", `${path} already exists`);
+    const text = renderTemplate(await deps.bundle.formatTemplate("adr.md"), values).replace(/^# .*$/m, `# ${request.title}`);
+    await deps.files.writeText(path, text);
+    await appendJournal(deps, ".cruze", "new", { kind: "adr", ref: path });
+    return { kind: "adr", ref: `ADR-${date}-${request.slug}`, path };
+  }
+
+  if (request.kind === "change" && request.feature !== undefined) {
+    const { item: feature } = resolveArtifact(view, request.feature);
+    if (feature === undefined || feature.kind !== "feature" || feature.archived) throw new CruzeError("not-a-feature", `"${request.feature}" is not an active feature`);
+    const row = changeRow(view, feature, request.slug);
+    const folder = `${feature.folder}/changes/${row.change}`;
+    const template = renderTemplate(await deps.bundle.formatTemplate("change.md"), { ...values, id: row.change });
+    await deps.files.writeText(`${folder}/change.md`, fillTemplate(template, { delivers: row.delivers, builds: [...row.builds, ...row.removes] }));
+    await appendJournal(deps, feature.folder, "new", { kind: "change", ref: `${feature.ref}/${row.change}` });
+    return { kind: "change", ref: `${feature.ref}/${row.change}`, path: `${folder}/change.md` };
+  }
+
+  const kind = request.kind === "feature" ? "feature" : "standalone";
+  const id = allocateId(view, date, request.slug);
+  const folder = `${kind === "feature" ? PATHS.featuresDir : PATHS.changesDir}/${id}`;
+  const roadmap = request.roadmap ?? (roadmapHasItem(view.snapshot.get(PATHS.roadmap), request.slug) ? request.slug : undefined);
+  const template = renderTemplate(await deps.bundle.formatTemplate(kind === "feature" ? "feature.md" : "standalone-change.md"), { ...values, id });
+  const path = `${folder}/${kind === "feature" ? "feature.md" : "change.md"}`;
+  await deps.files.writeText(path, fillTemplate(template, roadmap === undefined ? {} : { roadmap }));
+  const roadmapText = view.snapshot.get(PATHS.roadmap);
+  if (roadmap !== undefined && roadmapText !== undefined) {
+    await deps.files.writeText(PATHS.roadmap, upsertRow(roadmapText, "Status", [roadmap, id, "designing"]));
+  }
+  await appendJournal(deps, folder, "new", { kind, ref: id });
+  return { kind, ref: id, path };
+}
+
+/** Whether a roadmap phase lists this slug as an item. */
+function roadmapHasItem(roadmap                    , slug        )          {
+  if (roadmap === undefined) return false;
+  const phases = roadmap.split(/^## /m).find((section) => section.startsWith("Phases")) ?? "";
+  return phases.split("\n").some((line) => line.startsWith(`| ${slug} |`));
+}

package/dist/app/use_cases/project_status.js

@@ -0,0 +1,73 @@
+import { CruzeError } from "../../domain/cruze_error.js";
+import { readProgress } from "../../domain/project/progress.js";
+import { buildProjectView } from "../../domain/project/project_view.js";
+import { nextSteps,                 } from "../../domain/status/next_step.js";
+import { activeChange, buildGateReasons, projectStatus, touchedIds,                    } from "../../domain/status/work_status.js";
+import { appendJournal, loadView,                  } from "../project_context.js";
+
+                                                     
+                        
+ 
+
+export async function showStatus(deps             )                        {
+  const branch = await deps.repository.currentBranch();
+  return { branch, ...projectStatus(await loadView(deps.files), branch) };
+}
+
+/** The step to run next on this branch, and other work that could proceed. */
+export async function suggestNext(deps             )                                                  {
+  const branch = await deps.repository.currentBranch();
+  return { branch, ...nextSteps(await loadView(deps.files), branch) };
+}
+
+                             
+                
+                  
+                    
+                      
+ 
+
+/**
+ * The build gate: the change bound to this branch, its feature and the architecture are
+ * all approved and current. An override passes the gate and is journaled with its reason.
+ */
+export async function checkBuildGate(deps             , override         )                      {
+  const view = await loadView(deps.files);
+  const branch = await deps.repository.currentBranch();
+  const reasons = buildGateReasons(view, branch);
+  if (reasons.length === 0) return { gate: "build", passed: true, reasons, overridden: false };
+  if (override === undefined) return { gate: "build", passed: false, reasons, overridden: false };
+  if (override.trim() === "") throw new CruzeError("override-reason", "an override needs a reason");
+  const folder = activeChange(view, branch)?.folder ?? ".cruze";
+  await appendJournal(deps, folder, "override", { gate: "build", reason: override, blocked_by: reasons });
+  return { gate: "build", passed: true, reasons, overridden: true };
+}
+
+                          
+                 
+               
+                   
+ 
+
+/** In-flight work on other branches that touches the same elements as this branch's change. */
+export async function findOverlaps(deps             , ref         )                                                   {
+  const view = await loadView(deps.files);
+  const branch = await deps.repository.currentBranch();
+  const change = ref === undefined ? activeChange(view, branch) : view.items.find((item) => item.ref === ref);
+  if (change === undefined) throw new CruzeError("no-active-change", "no change is bound to this branch; name one with --change");
+  const mine = touchedIds(view, change);
+  const overlaps            = [];
+  for (const other of await deps.repository.otherBranches()) {
+    const theirs = buildProjectView(new Map([...view.snapshot].filter(([p]) => p.startsWith("docs/")).concat([...(await deps.repository.filesOnBranch(other, ".cruze"))])));
+    // Work in flight on a branch is the change bound to it.
+    const boundThere = theirs.items.filter((i) => {
+      const bound = readProgress(i.doc).branch;
+      return !i.archived && i.ref !== change.ref && bound !== undefined && (other === bound || other.endsWith(`/${bound}`));
+    });
+    for (const item of boundThere) {
+      const shared = [...touchedIds(theirs, item)].filter((id) => mine.has(id));
+      if (shared.length > 0) overlaps.push({ branch: other, item: item.ref, shared: shared.sort() });
+    }
+  }
+  return { change: change.ref, overlaps };
+}

package/dist/app/use_cases/record_progress.js

@@ -0,0 +1,101 @@
+import { CruzeError } from "../../domain/cruze_error.js";
+import { readRows, removeRow, upsertRow } from "../../domain/edits/managed_tables.js";
+import { updateProgress } from "../../domain/edits/progress_block.js";
+import { resolveChange } from "../../domain/project/artifact_ref.js";
+import { PATHS } from "../../domain/project/layout.js";
+import { readTasks } from "../../domain/project/plan_parts.js";
+import { requireSlug } from "../../domain/project/new_items.js";
+import { activeChange } from "../../domain/status/work_status.js";
+                                                                   
+import { appendJournal, loadView,                  } from "../project_context.js";
+
+/** Commands that write the CLI-owned progress records: task ticks, deviations and the feature map. */
+
+                             
+                 
+               
+               
+                
+ 
+
+/** Marks a task done, recording the commit that completed it (HEAD by default). */
+export async function completeTask(deps             , task        , options                                      )                      {
+  const change = await changeFor(deps, options.change);
+  requireTask(change, task);
+  const commit = options.commit ?? (await deps.repository.headCommit()) ?? "";
+  const text = updateProgress(change.doc.lines.join("\n"), (progress) => progress.tasks.set(task, commit));
+  await deps.files.writeText(change.path, text);
+  const ticks = [...text.matchAll(/^- \[([ x])\] T\d+/gm)];
+  return { change: change.ref, task, done: ticks.filter((m) => m[1] === "x").length, total: ticks.length };
+}
+
+/** Reopens a done task whose design a rethink changed, so build does it again. */
+export async function reopenTask(deps             , task        , reason        , options                     )                                            {
+  const change = await changeFor(deps, options.change);
+  requireTask(change, task);
+  if (reason.trim() === "") throw new CruzeError("missing-reason", "say why the task reopens");
+  await deps.files.writeText(change.path, updateProgress(change.doc.lines.join("\n"), (progress) => progress.tasks.set(task, null)));
+  await appendJournal(deps, change.folder, "reopen", { change: change.ref, task, reason: reason.trim() });
+  return { change: change.ref, task };
+}
+
+/** Records a task-level choice the agent made on its own. Anything larger is a rethink. */
+export async function recordDeviation(deps             , task        , text        , options                     )                                            {
+  const change = await changeFor(deps, options.change);
+  requireTask(change, task);
+  if (text.trim() === "") throw new CruzeError("missing-text", "describe the deviation");
+  await deps.files.writeText(change.path, updateProgress(change.doc.lines.join("\n"), (progress) => progress.deviations.push(`${task}: ${text.trim()}`)));
+  await appendJournal(deps, change.folder, "deviation", { change: change.ref, task, text: text.trim() });
+  return { change: change.ref, task };
+}
+
+/** Adds a feature to the future list of the feature map, or replaces its entry. */
+export async function addFutureFeature(deps             , slug        , summary        , goals          )                               {
+  requireSlug(slug);
+  const vision = await requireVision(deps);
+  await deps.files.writeText(PATHS.vision, upsertRow(vision, "Future", [slug, summary, goals.join(", ")]));
+  await appendJournal(deps, ".cruze", "feature-map", { action: "add", feature: slug, summary, goals });
+  return { feature: slug };
+}
+
+export async function dropFutureFeature(deps             , slug        , reason        )                               {
+  const vision = await requireVision(deps);
+  const { text, removed } = removeRow(vision, "Future", slug);
+  if (removed === null) throw new CruzeError("not-found", `${slug} is not on the future list`);
+  if (reason.trim() === "") throw new CruzeError("missing-reason", "dropping a feature needs a reason");
+  await deps.files.writeText(PATHS.vision, text);
+  await appendJournal(deps, ".cruze", "feature-map", { action: "drop", feature: slug, reason });
+  return { feature: slug };
+}
+
+/** Clears the landed rows from the roadmap's Status table, when a release closes. */
+export async function pruneRoadmap(deps             )                                 {
+  const roadmap = await deps.files.readText(PATHS.roadmap);
+  if (roadmap === undefined) throw new CruzeError("not-found", `${PATHS.roadmap} does not exist yet`);
+  const landed = readRows(roadmap, "Status").filter((row) => row[2] === "landed").map((row) => row[0] ?? "");
+  let text = roadmap;
+  for (const item of landed) text = removeRow(text, "Status", item).text;
+  if (landed.length > 0) {
+    await deps.files.writeText(PATHS.roadmap, text);
+    await appendJournal(deps, ".cruze", "roadmap-prune", { items: landed });
+  }
+  return { removed: landed };
+}
+
+async function changeFor(deps             , ref                    )                    {
+  const view = await loadView(deps.files);
+  if (ref !== undefined) return resolveChange(view, ref);
+  const change = activeChange(view, await deps.repository.currentBranch());
+  if (change === undefined) throw new CruzeError("no-active-change", "no change is bound to this branch; name one with --change");
+  return change;
+}
+
+function requireTask(change          , task        )       {
+  if (!readTasks(change.doc).tasks.some((t) => t.number === task)) throw new CruzeError("unknown-task", `${change.ref} has no task ${task}`);
+}
+
+async function requireVision(deps             )                  {
+  const vision = await deps.files.readText(PATHS.vision);
+  if (vision === undefined) throw new CruzeError("not-found", `${PATHS.vision} does not exist yet`);
+  return vision;
+}

package/dist/app/use_cases/run_review.js

@@ -0,0 +1,71 @@
+import { CruzeError } from "../../domain/cruze_error.js";
+import { resolveArtifact } from "../../domain/project/artifact_ref.js";
+import { featureOf } from "../../domain/project/work_items.js";
+                                                            
+import { loadView,                  } from "../project_context.js";
+
+export const ROLES = ["design-reviewer", "code-reviewer", "verifier", "researcher"]         ;
+                                          
+
+                                
+               
+                                                                                 
+                
+                 
+                                           
+                    
+                                                      
+                
+ 
+
+                               
+             
+                
+                    
+                 
+ 
+
+/**
+ * Runs a Cruze role in a fresh agent context: the role's prompt, what it reviews, and nothing
+ * from the conversation that produced the work. Returns the role's report as written.
+ */
+export async function runReview(deps                                       , request               )                        {
+  if (!(ROLES                     ).includes(request.role)) throw new CruzeError("unknown-role", `the roles are ${ROLES.join(", ")}`);
+  const role = request.role        ;
+  const view = await loadView(deps.files);
+  const roleText = (await deps.files.readText(`.agents/skills/cruze-roles/${role}.md`)) ?? (await bundledRole(deps, role));
+
+  const context = [`Round: ${request.round ?? 1}`];
+  if (request.item !== undefined) {
+    const { path, item } = resolveArtifact(view, request.item);
+    context.push(`Under review: ${item?.ref ?? path} (\`${path}\`)`);
+    const feature = item === undefined ? undefined : featureOf(view.items, item);
+    if (feature !== undefined) context.push(`Its feature: \`${feature.path}\``);
+    if (role === "design-reviewer" && item !== undefined && item.kind !== "feature") context.push("This is a change's plan: review it with the plan rubric.");
+  } else {
+    context.push("Under review: the project documents the role lists for project scope");
+  }
+  if (request.base !== undefined) context.push(`The changes under review: run \`git diff ${request.base}\`.`);
+  if (request.blockers !== undefined) context.push(`Round-1 blockers to check:\n\n${request.blockers}`);
+
+  const prompt = [
+    roleText.trim(),
+    "## This run",
+    "You are running the role above in a fresh context, in the project's repository. Read every input it lists from the files, and run the commands it names. Edit no files. End with the report the role describes.",
+    context.map((line) => `- ${line}`).join("\n"),
+  ].join("\n\n");
+
+  const command = view.config?.config?.review.command ?? [];
+  const run = await deps.runner.run(command, prompt);
+  if (run.exitCode !== 0) throw new CruzeError("review-failed", `${command.join(" ")} exited with ${run.exitCode}: ${run.error.trim() || run.output.trim()}`);
+  const report               = { role, command, report: run.output.trim() };
+  if (request.item !== undefined) report.item = request.item;
+  return report;
+}
+
+async function bundledRole(deps             , role      )                  {
+  const roles = (await deps.bundle.skills()).find((skill) => skill.folder === "roles");
+  const file = roles?.files.find((f) => f.path === `${role}.md`);
+  if (file === undefined) throw new CruzeError("role-missing", `the ${role} role is not installed; run cruze install`);
+  return file.text;
+}

package/dist/app/use_cases/validate_project.js

@@ -0,0 +1,22 @@
+import { hasErrors, validateProject } from "../../domain/validation/validate_project.js";
+                                                                  
+import { loadView } from "../project_context.js";
+                                                              
+
+                                 
+                 
+                 
+                   
+                      
+ 
+
+/** Checks every document in the project against the cruze-formats rules. */
+export async function validate(deps                         )                          {
+  const problems = validateProject(await loadView(deps.files));
+  return {
+    valid: !hasErrors(problems),
+    errors: problems.filter((p) => p.severity === "error").length,
+    warnings: problems.filter((p) => p.severity === "warning").length,
+    problems,
+  };
+}

package/dist/domain/agent_skill_homes.js

@@ -0,0 +1,25 @@
+/**
+ * Where agents look for skills. Skills are installed once into the shared
+ * Agent Skills directory; agents that don't read it get links in their own.
+ */
+
+export const SHARED_SKILLS_DIR = ".agents/skills";
+
+                                 
+                
+                    
+                                                                
+                    
+ 
+
+export const AGENT_SKILL_HOMES                            = [
+  { agent: "claude", skillsDir: ".claude/skills", markers: ["CLAUDE.md", ".claude"] },
+];
+
+export function knownAgents()           {
+  return AGENT_SKILL_HOMES.map((home) => home.agent);
+}
+
+export function agentSkillHome(agent        )                             {
+  return AGENT_SKILL_HOMES.find((home) => home.agent === agent);
+}

package/dist/domain/approvals/evaluate.js

@@ -0,0 +1,36 @@
+import { parseMarkdown } from "../markdown.js";
+import { approvalFolder,                  } from "../project/project_view.js";
+import { currentUpstreamHash, fingerprint } from "./fingerprint.js";
+import { latestApproval,                     } from "./records.js";
+
+                                                                                      
+
+                                 
+                   
+                       
+                                                                              
+                    
+                          
+                                                                           
+                        
+ 
+
+/**
+ * Computes an artifact's approval state from content, never from stored state:
+ * editing an upstream document is all it takes to make downstream work stale.
+ */
+export function evaluateApproval(view             , artifact        )                 {
+  const record = latestApproval(view.approvals.get(approvalFolder(view, artifact)) ?? { version: 1, approvals: [], merged: {} }, artifact);
+  if (record === undefined) return { artifact, state: "unapproved", changed: [] };
+  const journaled = view.journal.some((e) => e.event === "approve" && e.artifact === artifact && e.hash === record.hash);
+  if (!journaled) return { artifact, state: "unapproved", changed: [], record, unjournaled: true };
+
+  const text = view.snapshot.get(artifact);
+  if (text === undefined) return { artifact, state: "unapproved", changed: [], record };
+  const { hash } = fingerprint(view, artifact, parseMarkdown(text));
+  if (hash !== record.hash) return { artifact, state: "edited", changed: [], record };
+  const changed = Object.entries(record.upstream)
+    .filter(([key, pinned]) => currentUpstreamHash(view, key) !== pinned)
+    .map(([key]) => key);
+  return { artifact, state: changed.length > 0 ? "upstream-changed" : "approved", changed, record };
+}

package/dist/domain/approvals/fingerprint.js

@@ -0,0 +1,52 @@
+import { headingElements, rowElements } from "../elements.js";
+import { designHash, elementHash } from "../hashing.js";
+import { findIds } from "../ids.js";
+                                                  
+import { PATHS } from "../project/layout.js";
+                                                              
+import { featureOf } from "../project/work_items.js";
+
+/** What an approval pins: the document's design hash and the hash of everything upstream it relies on. */
+                              
+               
+                                   
+ 
+
+/** Documents a person can approve. Specs, the glossary and ADRs change only through approved work. */
+export function isApprovable(view             , path        )          {
+  return [PATHS.vision, PATHS.architecture, PATHS.roadmap].includes(path         ) || view.items.some((i) => i.path === path && !i.archived);
+}
+
+export function fingerprint(view             , path        , doc             )              {
+  const upstream                         = {};
+  const ownIds = new Set([...headingElements(doc), ...rowElements(doc)].filter((e) => e.op !== "ADDED").map((e) => e.id));
+  const isLivingDoc = !view.items.some((item) => item.path === path);
+  const designText = doc.lines.filter((_, i) => !doc.inManaged[i]).join("\n");
+
+  for (const id of findIds(designText)) {
+    if (isLivingDoc && ownIds.has(id)) continue;
+    const living = view.living.elements.get(id);
+    if (living !== undefined) upstream[id] = elementHash(living.doc, living.element);
+  }
+  const item = view.items.find((i) => i.path === path);
+  if (item !== undefined) {
+    // Work always depends on the dependency rules, cited or not.
+    for (const [id, living] of view.living.elements) {
+      if (id.startsWith("RULE-")) upstream[id] = elementHash(living.doc, living.element);
+    }
+    const feature = item.kind === "change" ? featureOf(view.items, item) : undefined;
+    if (feature !== undefined) upstream[`doc:${feature.path}`] = designHash(feature.doc);
+  }
+  return { hash: designHash(doc), upstream };
+}
+
+/** The current hash of one upstream key, or undefined when it no longer exists. */
+export function currentUpstreamHash(view             , key        )                     {
+  if (key.startsWith("doc:")) {
+    const path = key.slice("doc:".length);
+    const item = view.items.find((i) => i.path === path);
+    return item === undefined ? undefined : designHash(item.doc);
+  }
+  const living = view.living.elements.get(key);
+  return living === undefined ? undefined : elementHash(living.doc, living.element);
+}

package/dist/domain/approvals/records.js

@@ -0,0 +1,50 @@
+/** What `approvals.json` holds. Only the CLI writes it. */
+
+                                 
+                                       
+                   
+                                                   
+               
+                                                                                                  
+                                   
+                     
+             
+                                                                                   
+                 
+ 
+
+                                
+             
+                              
+                                                                                          
+                                 
+ 
+
+export function emptyApprovals()                {
+  return { version: 1, approvals: [], merged: {} };
+}
+
+export function parseApprovals(text                    )                                            {
+  if (text === undefined) return { file: emptyApprovals() };
+  try {
+    const raw = JSON.parse(text)                          ;
+    if (raw.version !== 1 || !Array.isArray(raw.approvals)) return { file: emptyApprovals(), problem: "approvals.json has an unknown format" };
+    return { file: { version: 1, approvals: raw.approvals, merged: raw.merged ?? {} } };
+  } catch {
+    return { file: emptyApprovals(), problem: "approvals.json is not valid JSON" };
+  }
+}
+
+export function serializeApprovals(file               )         {
+  return `${JSON.stringify(file, null, 2)}\n`;
+}
+
+/** The latest approval of an artifact, if any. */
+export function latestApproval(file               , artifact        )                             {
+  return file.approvals.filter((record) => record.artifact === artifact).at(-1);
+}
+
+/** Replaces the artifact's approval: one current approval per artifact; history lives in the journal. */
+export function withApproval(file               , record                )                {
+  return { ...file, approvals: [...file.approvals.filter((r) => r.artifact !== record.artifact), record] };
+}

package/dist/domain/architecture_sections.js

@@ -0,0 +1,23 @@
+                                     
+
+/** The `##` sections of architecture.md, in order, and the element kind each holds. */
+export const ARCHITECTURE_SECTIONS                                                      = [
+  { title: "Overview", kind: "VIEW" },
+  { title: "Bounded contexts", kind: "CTX" },
+  { title: "Domain model", kind: "ENT" },
+  { title: "Use cases", kind: "UC" },
+  { title: "Ports", kind: "PORT" },
+  { title: "Adapters", kind: "ADP" },
+  { title: "Flows", kind: "FLOW" },
+  { title: "Modules", kind: "MOD" },
+  { title: "Dependency rules", kind: "RULE" },
+  { title: "Cross-cutting concerns", kind: "XC" },
+  { title: "Decisions", kind: null },
+];
+
+export const ARCHITECTURE_KINDS                  = ["VIEW", "CTX", "ENT", "UC", "PORT", "ADP", "FLOW", "MOD", "RULE", "XC"];
+export const SPEC_KINDS                  = ["REQ", "SCN"];
+
+export function sectionForKind(kind      )                     {
+  return ARCHITECTURE_SECTIONS.find((section) => section.kind === kind)?.title;
+}

package/dist/domain/check/check_source.js

@@ -0,0 +1,64 @@
+                                                       
+import { matchesAny } from "../glob.js";
+import { importsOf, resolveImport } from "./imports.js";
+import { countTypes } from "./type_count.js";
+
+                               
+               
+                
+                                                                                
+                  
+                                                                           
+                                
+ 
+
+                             
+                      
+                                                             
+                                       
+                                                                                              
+                        
+                                                                                        
+                  
+ 
+
+/** Enforces the architecture's layer rules and the file budgets on source code. */
+export function checkSource(input            )                 {
+  const { config, sources, modulePaths } = input;
+  const all = [...sources.keys()];
+  const targets = input.only ?? all;
+  const layerOf = (path        )                    => config.layers.find((layer) => matchesAny(path, layer.paths));
+  const findings                 = [];
+
+  for (const path of targets) {
+    const text = sources.get(path);
+    if (text === undefined) continue;
+    const layer = layerOf(path);
+    if (config.layers.length > 0 && layer === undefined) {
+      findings.push({ path, rule: "no-layer", severity: "warning", message: "the file is in no layer, so its imports are unchecked" });
+    }
+    if (layer !== undefined) {
+      for (const found of importsOf(path, text)) {
+        const target = resolveImport(found, all);
+        const targetLayer = target === undefined ? undefined : layerOf(target);
+        if (target === undefined || targetLayer === undefined || targetLayer.name === layer.name) continue;
+        if (!layer.mayImport.includes(targetLayer.name)) {
+          findings.push({ path, line: found.line + 1, rule: "layer", severity: "error", message: `${layer.name} may not import ${targetLayer.name} (${target})` });
+        }
+      }
+    }
+    const excepted = config.check.exceptions.some((exception) => exception.path === path);
+    const lines = text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
+    if (!excepted && lines > config.check.maxLines) {
+      findings.push({ path, rule: "max-lines", severity: "warning", message: `${lines} lines, over the budget of ${config.check.maxLines}; split it by responsibility` });
+    }
+    const types = countTypes(path, text);
+    if (!excepted && types !== null && types > config.check.maxTypes) {
+      findings.push({ path, rule: "max-types", severity: "warning", message: `${types} top-level types, over the budget of ${config.check.maxTypes}` });
+    }
+    if (modulePaths.length > 0 && !modulePaths.some((module) => (module.endsWith("/") ? path.startsWith(module) : path === module))) {
+      findings.push({ path, rule: "outside-module-map", severity: "warning", message: "the file is outside every module in the architecture's module map" });
+    }
+  }
+  return findings;
+}