@printpractical/cruze 0.0.1

package/src/app/use_cases/record_progress.ts

@@ -0,0 +1,101 @@
+import { CruzeError } from "../../domain/cruze_error.ts";
+import { readRows, removeRow, upsertRow } from "../../domain/edits/managed_tables.ts";
+import { updateProgress } from "../../domain/edits/progress_block.ts";
+import { resolveChange } from "../../domain/project/artifact_ref.ts";
+import { PATHS } from "../../domain/project/layout.ts";
+import { readTasks } from "../../domain/project/plan_parts.ts";
+import { requireSlug } from "../../domain/project/new_items.ts";
+import { activeChange } from "../../domain/status/work_status.ts";
+import type { WorkItem } from "../../domain/project/work_items.ts";
+import { appendJournal, loadView, type ProjectDeps } from "../project_context.ts";
+
+/** Commands that write the CLI-owned progress records: task ticks, deviations and the feature map. */
+
+export interface TaskReport {
+  change: string;
+  task: string;
+  done: number;
+  total: number;
+}
+
+/** Marks a task done, recording the commit that completed it (HEAD by default). */
+export async function completeTask(deps: ProjectDeps, task: string, options: { change?: string; commit?: string }): Promise<TaskReport> {
+  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: ProjectDeps, task: string, reason: string, options: { change?: string }): Promise<{ change: string; task: string }> {
+  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: ProjectDeps, task: string, text: string, options: { change?: string }): Promise<{ change: string; task: string }> {
+  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: ProjectDeps, slug: string, summary: string, goals: string[]): Promise<{ feature: string }> {
+  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: ProjectDeps, slug: string, reason: string): Promise<{ feature: string }> {
+  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: ProjectDeps): Promise<{ removed: string[] }> {
+  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: ProjectDeps, ref: string | undefined): Promise<WorkItem> {
+  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: WorkItem, task: string): void {
+  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: ProjectDeps): Promise<string> {
+  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/src/app/use_cases/run_review.ts

@@ -0,0 +1,71 @@
+import { CruzeError } from "../../domain/cruze_error.ts";
+import { resolveArtifact } from "../../domain/project/artifact_ref.ts";
+import { featureOf } from "../../domain/project/work_items.ts";
+import type { AgentRunner } from "../ports/agent_runner.ts";
+import { loadView, type ProjectDeps } from "../project_context.ts";
+
+export const ROLES = ["design-reviewer", "code-reviewer", "verifier", "researcher"] as const;
+export type Role = (typeof ROLES)[number];
+
+export interface ReviewRequest {
+  role: string;
+  /** The feature or change under review; omitted for project-scope documents. */
+  item?: string;
+  round?: number;
+  /** The round-1 blockers, for round 2. */
+  blockers?: string;
+  /** The commit the diff under review starts from. */
+  base?: string;
+}
+
+export interface ReviewReport {
+  role: Role;
+  item?: string;
+  command: string[];
+  report: string;
+}
+
+/**
+ * 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: ProjectDeps & { runner: AgentRunner }, request: ReviewRequest): Promise<ReviewReport> {
+  if (!(ROLES as readonly string[]).includes(request.role)) throw new CruzeError("unknown-role", `the roles are ${ROLES.join(", ")}`);
+  const role = request.role as 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: ReviewReport = { role, command, report: run.output.trim() };
+  if (request.item !== undefined) report.item = request.item;
+  return report;
+}
+
+async function bundledRole(deps: ProjectDeps, role: Role): Promise<string> {
+  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/src/app/use_cases/validate_project.ts

@@ -0,0 +1,22 @@
+import { hasErrors, validateProject } from "../../domain/validation/validate_project.ts";
+import type { Problem } from "../../domain/validation/problem.ts";
+import { loadView } from "../project_context.ts";
+import type { ProjectFiles } from "../ports/project_files.ts";
+
+export interface ValidateReport {
+  valid: boolean;
+  errors: number;
+  warnings: number;
+  problems: Problem[];
+}
+
+/** Checks every document in the project against the cruze-formats rules. */
+export async function validate(deps: { files: ProjectFiles }): Promise<ValidateReport> {
+  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/src/domain/agent_skill_homes.ts

@@ -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 interface AgentSkillHome {
+  agent: string;
+  skillsDir: string;
+  /** Paths whose presence shows the project uses this agent. */
+  markers: string[];
+}
+
+export const AGENT_SKILL_HOMES: readonly AgentSkillHome[] = [
+  { agent: "claude", skillsDir: ".claude/skills", markers: ["CLAUDE.md", ".claude"] },
+];
+
+export function knownAgents(): string[] {
+  return AGENT_SKILL_HOMES.map((home) => home.agent);
+}
+
+export function agentSkillHome(agent: string): AgentSkillHome | undefined {
+  return AGENT_SKILL_HOMES.find((home) => home.agent === agent);
+}

package/src/domain/approvals/evaluate.ts

@@ -0,0 +1,36 @@
+import { parseMarkdown } from "../markdown.ts";
+import { approvalFolder, type ProjectView } from "../project/project_view.ts";
+import { currentUpstreamHash, fingerprint } from "./fingerprint.ts";
+import { latestApproval, type ApprovalRecord } from "./records.ts";
+
+export type ApprovalState = "approved" | "edited" | "upstream-changed" | "unapproved";
+
+export interface ApprovalStatus {
+  artifact: string;
+  state: ApprovalState;
+  /** Upstream IDs or documents that changed or disappeared since approval. */
+  changed: string[];
+  record?: ApprovalRecord;
+  /** Set when an approval exists but the journal has no matching entry. */
+  unjournaled?: boolean;
+}
+
+/**
+ * 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: ProjectView, artifact: string): ApprovalStatus {
+  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/src/domain/approvals/fingerprint.ts

@@ -0,0 +1,52 @@
+import { headingElements, rowElements } from "../elements.ts";
+import { designHash, elementHash } from "../hashing.ts";
+import { findIds } from "../ids.ts";
+import type { MarkdownDoc } from "../markdown.ts";
+import { PATHS } from "../project/layout.ts";
+import type { ProjectView } from "../project/project_view.ts";
+import { featureOf } from "../project/work_items.ts";
+
+/** What an approval pins: the document's design hash and the hash of everything upstream it relies on. */
+export interface Fingerprint {
+  hash: string;
+  upstream: Record<string, string>;
+}
+
+/** Documents a person can approve. Specs, the glossary and ADRs change only through approved work. */
+export function isApprovable(view: ProjectView, path: string): boolean {
+  return [PATHS.vision, PATHS.architecture, PATHS.roadmap].includes(path as never) || view.items.some((i) => i.path === path && !i.archived);
+}
+
+export function fingerprint(view: ProjectView, path: string, doc: MarkdownDoc): Fingerprint {
+  const upstream: Record<string, string> = {};
+  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: ProjectView, key: string): string | undefined {
+  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/src/domain/approvals/records.ts

@@ -0,0 +1,50 @@
+/** What `approvals.json` holds. Only the CLI writes it. */
+
+export interface ApprovalRecord {
+  /** Path of the approved document. */
+  artifact: string;
+  /** Design hash of the document when approved. */
+  hash: string;
+  /** Hash of each upstream element or document the approval depends on, by ID or `doc:<path>`. */
+  upstream: Record<string, string>;
+  approvedAt: string;
+  by: string;
+  /** Why the approval exists when no person gave it, such as a merge by `land`. */
+  basis?: string;
+}
+
+export interface ApprovalsFile {
+  version: 1;
+  approvals: ApprovalRecord[];
+  /** For a feature or standalone change: hash of each living element it merged, by ID. */
+  merged: Record<string, string>;
+}
+
+export function emptyApprovals(): ApprovalsFile {
+  return { version: 1, approvals: [], merged: {} };
+}
+
+export function parseApprovals(text: string | undefined): { file: ApprovalsFile; problem?: string } {
+  if (text === undefined) return { file: emptyApprovals() };
+  try {
+    const raw = JSON.parse(text) as Partial<ApprovalsFile>;
+    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: ApprovalsFile): string {
+  return `${JSON.stringify(file, null, 2)}\n`;
+}
+
+/** The latest approval of an artifact, if any. */
+export function latestApproval(file: ApprovalsFile, artifact: string): ApprovalRecord | undefined {
+  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: ApprovalsFile, record: ApprovalRecord): ApprovalsFile {
+  return { ...file, approvals: [...file.approvals.filter((r) => r.artifact !== record.artifact), record] };
+}

package/src/domain/architecture_sections.ts

@@ -0,0 +1,23 @@
+import type { Kind } from "./ids.ts";
+
+/** The `##` sections of architecture.md, in order, and the element kind each holds. */
+export const ARCHITECTURE_SECTIONS: ReadonlyArray<{ title: string; kind: Kind | null }> = [
+  { 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: readonly Kind[] = ["VIEW", "CTX", "ENT", "UC", "PORT", "ADP", "FLOW", "MOD", "RULE", "XC"];
+export const SPEC_KINDS: readonly Kind[] = ["REQ", "SCN"];
+
+export function sectionForKind(kind: Kind): string | undefined {
+  return ARCHITECTURE_SECTIONS.find((section) => section.kind === kind)?.title;
+}

package/src/domain/check/check_source.ts

@@ -0,0 +1,64 @@
+import type { CruzeConfig, Layer } from "../config.ts";
+import { matchesAny } from "../glob.ts";
+import { importsOf, resolveImport } from "./imports.ts";
+import { countTypes } from "./type_count.ts";
+
+export interface CheckFinding {
+  path: string;
+  line?: number;
+  rule: "layer" | "max-lines" | "max-types" | "outside-module-map" | "no-layer";
+  message: string;
+  /** Layer violations always fail; the rest fail in CI unless excepted. */
+  severity: "error" | "warning";
+}
+
+export interface CheckInput {
+  config: CruzeConfig;
+  /** Every source file matched by config.source, by path. */
+  sources: ReadonlyMap<string, string>;
+  /** Paths of the MOD elements in the architecture; files outside all of them are flagged. */
+  modulePaths: string[];
+  /** Check only these files, when given; imports still resolve against every source. */
+  only?: string[];
+}
+
+/** Enforces the architecture's layer rules and the file budgets on source code. */
+export function checkSource(input: CheckInput): CheckFinding[] {
+  const { config, sources, modulePaths } = input;
+  const all = [...sources.keys()];
+  const targets = input.only ?? all;
+  const layerOf = (path: string): Layer | undefined => config.layers.find((layer) => matchesAny(path, layer.paths));
+  const findings: CheckFinding[] = [];
+
+  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;
+}

package/src/domain/check/imports.ts

@@ -0,0 +1,81 @@
+import { posix } from "node:path";
+import { rustImportCandidates } from "./rust_imports.ts";
+
+/** One import in a source file, with the project files it could refer to, most specific first. */
+export interface SourceImport {
+  line: number;
+  candidates: string[];
+  /** Match candidates against the end of project paths rather than exactly. */
+  bySuffix: boolean;
+}
+
+const JS = /\.(?:[cm]?[jt]sx?)$/;
+const JS_EXTENSIONS = ["", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", "/index.ts", "/index.js"];
+
+/** Imports that point inside the project. Imports of libraries and the standard library are left out. */
+export function importsOf(path: string, text: string): SourceImport[] {
+  if (JS.test(path)) return jsImports(path, text);
+  if (path.endsWith(".py")) return pythonImports(path, text);
+  if (path.endsWith(".rs")) return rustImportCandidates(path, text).map((i) => ({ ...i, bySuffix: false }));
+  if (/\.(?:c|h|cc|cpp|cxx|hh|hpp|hxx)$/.test(path)) return matches(text, /^\s*#\s*include\s+"([^"]+)"/gm, (target) => [target], true);
+  if (path.endsWith(".go")) return goImports(text);
+  if (/\.(?:java|kt)$/.test(path)) return matches(text, /^import\s+(?:static\s+)?([\w.]+)(?:\.\*)?;?\s*$/gm, (t) => [`${t.replace(/\./g, "/")}.java`, `${t.replace(/\./g, "/")}.kt`], true);
+  return [];
+}
+
+function jsImports(path: string, text: string): SourceImport[] {
+  const pattern = /(?:\bfrom\s*|\bimport\s*\(?\s*|\brequire\s*\(\s*)["']([^"']+)["']/g;
+  return matches(text, pattern, (target) => {
+    if (!target.startsWith(".")) return [];
+    const base = posix.normalize(posix.join(posix.dirname(path), target));
+    const stripped = base.replace(/\.[cm]?jsx?$/, "");
+    return [...new Set([...JS_EXTENSIONS.map((ext) => base + ext), ...JS_EXTENSIONS.map((ext) => stripped + ext)])];
+  }, false);
+}
+
+function pythonImports(path: string, text: string): SourceImport[] {
+  const results: SourceImport[] = [];
+  for (const match of text.matchAll(/^\s*(?:from\s+(\.*)([\w.]*)\s+import\s+([\w, ]+)|import\s+([\w.]+))/gm)) {
+    const line = text.slice(0, match.index).split("\n").length - 1;
+    const dots = match[1] ?? "";
+    const module = (match[2] ?? match[4] ?? "").split(".").filter((s) => s !== "");
+    const names = (match[3] ?? "").split(",").map((s) => s.trim().split(" ")[0] ?? "").filter((s) => s !== "");
+    const bases = dots === "" ? [module] : [[...posix.dirname(path).split("/").slice(0, dots.length === 1 ? undefined : -(dots.length - 1)), ...module]];
+    const candidates = bases.flatMap((segments) => [
+      ...names.map((name) => `${[...segments, name].join("/")}.py`),
+      `${segments.join("/")}.py`,
+      `${segments.join("/")}/__init__.py`,
+    ]);
+    results.push({ line, candidates, bySuffix: dots === "" });
+  }
+  return results;
+}
+
+function goImports(text: string): SourceImport[] {
+  const results: SourceImport[] = [];
+  for (const match of text.matchAll(/^\s*(?:import\s+)?(?:\w+\s+)?"([\w./-]+)"\s*$/gm)) {
+    const line = text.slice(0, match.index).split("\n").length - 1;
+    results.push({ line, candidates: [`${match[1] ?? ""}/`], bySuffix: true });
+  }
+  return results;
+}
+
+function matches(text: string, pattern: RegExp, candidates: (target: string) => string[], bySuffix: boolean): SourceImport[] {
+  return [...text.matchAll(pattern)]
+    .map((match) => ({ line: text.slice(0, match.index).split("\n").length - 1, candidates: candidates(match[1] ?? ""), bySuffix }))
+    .filter((found) => found.candidates.length > 0);
+}
+
+/** The project file an import refers to, or undefined when it points outside the project. */
+export function resolveImport(found: SourceImport, files: readonly string[]): string | undefined {
+  for (const candidate of found.candidates) {
+    if (candidate.endsWith("/")) {
+      const inDir = files.find((f) => (found.bySuffix ? `/${f}`.includes(`/${candidate}`) : f.startsWith(candidate)));
+      if (inDir !== undefined) return inDir;
+      continue;
+    }
+    const hit = found.bySuffix ? files.find((f) => f === candidate || f.endsWith(`/${candidate}`)) : files.find((f) => f === candidate);
+    if (hit !== undefined) return hit;
+  }
+  return undefined;
+}

package/src/domain/check/rust_imports.ts

@@ -0,0 +1,84 @@
+/** Resolves Rust `use` paths inside a crate to candidate source files. */
+
+/** Candidate files for each `use crate::…`, `use super::…` and `use self::…` path in a Rust file. */
+export function rustImportCandidates(path: string, text: string): Array<{ line: number; candidates: string[] }> {
+  const root = crateRoot(path);
+  if (root === null) return [];
+  const own = moduleSegments(path, root);
+  const results: Array<{ line: number; candidates: string[] }> = [];
+  const pattern = /^\s*(?:pub(?:\([^)]*\))?\s+)?use\s+([^;]+);/gms;
+  for (const match of text.matchAll(pattern)) {
+    const line = text.slice(0, match.index).split("\n").length - 1;
+    for (const segments of expandUse((match[1] ?? "").replace(/\s+/g, ""))) {
+      const absolute = absoluteSegments(segments, own);
+      if (absolute !== null) results.push({ line, candidates: candidatesFor(root, absolute) });
+    }
+  }
+  return results;
+}
+
+/** The directory holding the crate root: everything up to and including `src/`. */
+function crateRoot(path: string): string | null {
+  const index = path.lastIndexOf("src/");
+  return index === -1 ? null : path.slice(0, index + "src/".length);
+}
+
+/** The module path of a file: `src/a/b.rs` and `src/a/b/mod.rs` are both `a::b`. */
+function moduleSegments(path: string, root: string): string[] {
+  const rest = path.slice(root.length).replace(/\.rs$/, "");
+  const segments = rest.split("/");
+  const last = segments[segments.length - 1];
+  if (last === "mod" || (segments.length === 1 && (last === "lib" || last === "main"))) segments.pop();
+  return segments;
+}
+
+/** `a::{b, c::d}` becomes `[a, b]` and `[a, c, d]`. */
+function expandUse(tree: string): string[][] {
+  const brace = tree.indexOf("{");
+  if (brace === -1) return [tree.split("::").filter((s) => s !== "" && s !== "*").map((s) => s.split(" as ")[0] ?? s)];
+  const prefix = tree.slice(0, brace).split("::").filter((s) => s !== "");
+  const inner = tree.slice(brace + 1, tree.lastIndexOf("}"));
+  return splitTopLevel(inner).flatMap((part) => (part === "self" ? [prefix] : expandUse(part).map((rest) => [...prefix, ...rest])));
+}
+
+function splitTopLevel(inner: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let current = "";
+  for (const char of inner) {
+    if (char === "{") depth++;
+    if (char === "}") depth--;
+    if (char === "," && depth === 0) {
+      parts.push(current);
+      current = "";
+    } else current += char;
+  }
+  if (current !== "") parts.push(current);
+  return parts.filter((part) => part !== "");
+}
+
+function absoluteSegments(segments: string[], own: string[]): string[] | null {
+  const [head, ...rest] = segments;
+  if (head === "crate") return rest;
+  if (head === "self") return [...own, ...rest];
+  if (head === "super") {
+    let base = own.slice(0, -1);
+    let tail = rest;
+    while (tail[0] === "super") {
+      base = base.slice(0, -1);
+      tail = tail.slice(1);
+    }
+    return [...base, ...tail];
+  }
+  return null;
+}
+
+/** The longest module path first: an imported item may be a type inside a module file. */
+function candidatesFor(root: string, segments: string[]): string[] {
+  const candidates: string[] = [];
+  for (let n = segments.length; n > 0; n--) {
+    const module = segments.slice(0, n).join("/");
+    candidates.push(`${root}${module}.rs`, `${root}${module}/mod.rs`);
+  }
+  return candidates;
+}

package/src/domain/check/type_count.ts

@@ -0,0 +1,17 @@
+/** Counts top-level type declarations, by the file's language. */
+
+const PATTERNS: Array<{ extensions: RegExp; declaration: RegExp }> = [
+  { extensions: /\.(?:[cm]?[jt]sx?)$/, declaration: /^(?:export\s+)?(?:default\s+)?(?:declare\s+)?(?:abstract\s+)?(?:class|interface|enum|type)\s+[A-Za-z_]/ },
+  { extensions: /\.py$/, declaration: /^class\s+[A-Za-z_]/ },
+  { extensions: /\.rs$/, declaration: /^(?:pub(?:\([^)]*\))?\s+)?(?:struct|enum|trait|union|type)\s+[A-Za-z_]/ },
+  { extensions: /\.go$/, declaration: /^type\s+[A-Za-z_]/ },
+  { extensions: /\.(?:c|h|cc|cpp|cxx|hh|hpp|hxx)$/, declaration: /^(?:typedef\s+)?(?:struct|class|enum|union)\s+[A-Za-z_]\w*(?:\s*[:{].*)?$/ },
+  { extensions: /\.(?:java|kt|swift|scala)$/, declaration: /^(?:(?:public|private|internal|open|final|abstract|data|sealed|static)\s+)*(?:class|interface|enum|object|struct|protocol|record)\s+[A-Za-z_]/ },
+];
+
+/** Top-level type declarations in the file, or null when its language isn't recognised. */
+export function countTypes(path: string, text: string): number | null {
+  const pattern = PATTERNS.find((p) => p.extensions.test(path));
+  if (pattern === undefined) return null;
+  return text.split("\n").filter((line) => pattern.declaration.test(line)).length;
+}