BBC2-34 enforce layered import rule via bun test

Three tests, one per layer. Each walks `src/` and asserts every file
in its layer respects the dependency rule:

  - `src/commands/**` may import from `src/backend/**` and `src/shared/**`.
  - `src/backend/<slice>/**` may import from `src/shared/**` and from
    the same slice. No cross-slice backend imports, no `src/commands/**`.
  - `src/shared/**` may import only from `src/shared/**`.

Parses imports with a single regex that covers `import ... from`,
side-effect `import "..."`, dynamic `import(...)`, and re-exports.
Good enough for this codebase's consistent style; we'd reach for a
proper AST parser only if imports grew beyond what the regex handles.

Exemptions: `*.test.ts` files (tests may reach across layers) and
`src/shared/bitbucket-http/generated.d.ts` (auto-generated). Non-
relative imports (node modules, `msw`, `commander`, …) are always
allowed.

Author: b2l

src/test/architecture.test.ts

@@ -0,0 +1,116 @@
+import { test, expect, describe } from "bun:test";
+import { dirname, relative, resolve } from "node:path";
+
+/**
+ * Layering rule, enforced as a unit test so CI catches violations:
+ *
+ *   - `src/commands/**` may import from `src/backend/**` and `src/shared/**`.
+ *   - `src/backend/<slice>/**` may import from `src/shared/**` and from the
+ *     SAME slice. Cross-slice backend imports and imports from
+ *     `src/commands/**` are forbidden.
+ *   - `src/shared/<area>/**` may import only from `src/shared/**`. Imports
+ *     from `src/backend/**` or `src/commands/**` are forbidden.
+ *
+ * Non-relative imports (node modules, built-ins, `msw`, `commander`, …) are
+ * always allowed. Test files (`*.test.ts`) are exempt so they can reach
+ * across layers freely. The generated Bitbucket types file is excluded.
+ *
+ * Parsing: a single regex covers `import ... from "..."`, `import "..."`,
+ * `import("...")`, and `export ... from "..."`. Good enough for this
+ * codebase; we'd reach for a proper AST parser only if we grew imports the
+ * regex can't handle (none so far).
+ */
+
+type Layered = {
+  kind: "commands" | "backend" | "shared";
+  slice: string;
+};
+
+type Classification = Layered | { kind: "other" };
+
+const IMPORT_RE = /(?:from|import)\s*\(?\s*["']([^"']+)["']/gs;
+
+function classify(path: string): Classification {
+  const parts = path.split("/");
+  if (parts[0] !== "src" || parts.length < 3) return { kind: "other" };
+  const layer = parts[1];
+  const slice = parts[2]!;
+  if (layer === "commands" || layer === "backend" || layer === "shared") {
+    return { kind: layer, slice };
+  }
+  return { kind: "other" };
+}
+
+function isSkipped(file: string): boolean {
+  if (file.endsWith(".test.ts")) return true;
+  if (file === "src/shared/bitbucket-http/generated.d.ts") return true;
+  return false;
+}
+
+function ruleViolation(from: Layered, to: Classification): string | null {
+  if (to.kind === "other") return null;
+
+  if (from.kind === "commands") return null;
+
+  if (from.kind === "backend") {
+    if (to.kind === "shared") return null;
+    if (to.kind === "backend" && to.slice === from.slice) return null;
+    if (to.kind === "backend") {
+      return `backend slice '${from.slice}' imports from backend slice '${to.slice}'`;
+    }
+    return `backend imports from commands`;
+  }
+
+  // from.kind === "shared"
+  if (to.kind === "shared") return null;
+  return `shared imports from ${to.kind}`;
+}
+
+async function violationsFor(
+  layer: "commands" | "backend" | "shared",
+): Promise<string[]> {
+  const glob = new Bun.Glob("**/*.ts");
+  const violations: string[] = [];
+
+  for await (const relPath of glob.scan("src")) {
+    const file = `src/${relPath}`;
+    if (isSkipped(file)) continue;
+
+    const fromC = classify(file);
+    if (fromC.kind !== layer) continue;
+
+    const content = await Bun.file(file).text();
+
+    for (const match of content.matchAll(IMPORT_RE)) {
+      const spec = match[1]!;
+      if (!spec.startsWith("./") && !spec.startsWith("../")) continue;
+
+      const absolute = resolve(dirname(file), spec);
+      const normalized = relative(process.cwd(), absolute).replace(/\\/g, "/");
+      const toC = classify(normalized);
+
+      const reason = ruleViolation(fromC, toC);
+      if (reason) {
+        violations.push(
+          `${file} imports ${normalized}, which violates the commands→backend→shared rule (${reason})`,
+        );
+      }
+    }
+  }
+
+  return violations;
+}
+
+describe("architecture layering", () => {
+  test("commands layer follows the rule", async () => {
+    expect(await violationsFor("commands")).toEqual([]);
+  });
+
+  test("backend layer follows the rule", async () => {
+    expect(await violationsFor("backend")).toEqual([]);
+  });
+
+  test("shared layer follows the rule", async () => {
+    expect(await violationsFor("shared")).toEqual([]);
+  });
+});