GitHub: issue reads and writes through the gh CLI

.dw/config.yml

@@ -0,0 +1,9 @@
+# softfac (the Rust factory) reads this block from the default branch on every pass.
+# Design and plan: factory/docs/design.md once issue #1 lands; issues #1 to #21.
+factory:
+  instructors: [tomkaczocha, rawphp]
+  base: main
+  provision: [vp i]
+  gate: [factory/scripts/check.sh]
+  limits: { gate_retries: 2 }
+  autonomy: pr

.github/workflows/factory-ci.yml

@@ -0,0 +1,44 @@
+name: Factory CI
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: factory-ci-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+# This is the fork's own workflow. Upstream's workflows are disabled on this repo.
+jobs:
+  check:
+    name: Check
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
+
+      - name: Setup Vite+
+        uses: voidzero-dev/setup-vp@v1
+        with:
+          node-version-file: package.json
+          cache: true
+          run-install: true
+
+      - name: Install
+        run: vp i
+
+      - name: Check
+        run: factory/scripts/check.sh

apps/server/src/factory/boundary.test.ts

@@ -0,0 +1,157 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import * as NodeFS from "node:fs";
+import * as NodePath from "node:path";
+
+import { describe, expect, it } from "vite-plus/test";
+
+interface SourceFile {
+  /** Relative to apps/server/src, with `/` separators. */
+  readonly path: string;
+  readonly imports: ReadonlyArray<string>;
+}
+
+const resolveRelative = (file: string, specifier: string) =>
+  NodePath.posix.normalize(NodePath.posix.join(NodePath.posix.dirname(file), specifier));
+
+const packageName = (specifier: string) =>
+  specifier
+    .split("/")
+    .slice(0, specifier.startsWith("@") ? 2 : 1)
+    .join("/");
+
+/**
+ * Factory code (except factory/t3/) may not import T3 code: neither relative paths outside
+ * factory/ nor the server's workspace packages. Nothing outside factory/ may import it,
+ * except server.ts.
+ */
+export const findBoundaryViolations = (
+  files: ReadonlyArray<SourceFile>,
+  workspacePackages: ReadonlySet<string>,
+): Array<string> => {
+  const violations: Array<string> = [];
+  for (const file of files) {
+    const relative = file.imports.filter((specifier) => specifier.startsWith("."));
+    if (file.path.startsWith("factory/")) {
+      if (file.path.startsWith("factory/t3/")) continue;
+      for (const specifier of relative) {
+        if (!resolveRelative(file.path, specifier).startsWith("factory/")) {
+          violations.push(`${file.path} imports ${specifier} from outside factory/`);
+        }
+      }
+      for (const specifier of file.imports) {
+        if (workspacePackages.has(packageName(specifier))) {
+          violations.push(`${file.path} imports ${specifier}, a T3 package`);
+        }
+      }
+    } else if (file.path !== "server.ts") {
+      for (const specifier of relative) {
+        if (resolveRelative(file.path, specifier).startsWith("factory/")) {
+          violations.push(`${file.path} imports ${specifier} from factory/`);
+        }
+      }
+    }
+  }
+  return violations;
+};
+
+const IMPORT_PATTERNS = [
+  /\bfrom\s*"([^"]+)"/g,
+  /\bfrom\s*'([^']+)'/g,
+  /\bimport\s*"([^"]+)"/g,
+  /\bimport\s*'([^']+)'/g,
+  /\bimport\(\s*"([^"]+)"\s*\)/g,
+  /\bimport\(\s*'([^']+)'\s*\)/g,
+];
+
+const extractImports = (source: string): Array<string> =>
+  IMPORT_PATTERNS.flatMap((pattern) => Array.from(source.matchAll(pattern), (match) => match[1]!));
+
+const srcRoot = NodePath.resolve(import.meta.dirname, "..");
+
+/** The server's `workspace:` dependencies, which are T3 code. */
+const readWorkspacePackages = (): ReadonlySet<string> => {
+  const manifest = JSON.parse(
+    NodeFS.readFileSync(NodePath.resolve(srcRoot, "../package.json"), "utf8"),
+  ) as Record<string, Record<string, string> | undefined>;
+  return new Set(
+    [manifest.dependencies, manifest.devDependencies].flatMap((deps) =>
+      Object.entries(deps ?? {})
+        .filter(([, version]) => version.startsWith("workspace:"))
+        .map(([name]) => name),
+    ),
+  );
+};
+
+const listSourceFiles = (dir: string): Array<string> =>
+  NodeFS.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    if (entry.name === "node_modules") return [];
+    const full = NodePath.join(dir, entry.name);
+    if (entry.isDirectory()) return listSourceFiles(full);
+    return /\.tsx?$/.test(entry.name) ? [full] : [];
+  });
+
+describe("factory boundary", () => {
+  it("holds for the real tree", () => {
+    const files = listSourceFiles(srcRoot).map((full) => ({
+      path: NodePath.relative(srcRoot, full).split(NodePath.sep).join("/"),
+      imports: extractImports(NodeFS.readFileSync(full, "utf8")),
+    }));
+    expect(files.some((file) => file.path === "factory/index.ts")).toBe(true);
+    expect(files.find((file) => file.path === "server.ts")?.imports).toContain(
+      "./factory/index.ts",
+    );
+    const workspacePackages = readWorkspacePackages();
+    expect(workspacePackages.has("@t3tools/contracts")).toBe(true);
+    expect(findBoundaryViolations(files, workspacePackages)).toEqual([]);
+  });
+
+  it("flags factory code importing from outside factory/, except under factory/t3/", () => {
+    const violations = findBoundaryViolations(
+      [
+        { path: "factory/foo.ts", imports: ["../config.ts", "effect/Effect", "./bar.ts"] },
+        { path: "factory/t3/paths.ts", imports: ["../../config.ts"] },
+      ],
+      new Set(),
+    );
+    expect(violations).toHaveLength(1);
+    expect(violations[0]).toContain("factory/foo.ts");
+    expect(violations[0]).toContain("../config.ts");
+  });
+
+  it("flags factory code importing T3 workspace packages, except under factory/t3/", () => {
+    const violations = findBoundaryViolations(
+      [
+        {
+          path: "factory/domain/lifecycle.ts",
+          imports: ["@t3tools/contracts", "@t3tools/shared/git", "effect/Effect", "node:fs"],
+        },
+        { path: "factory/t3/threads.ts", imports: ["@t3tools/contracts"] },
+      ],
+      new Set(["@t3tools/contracts", "@t3tools/shared"]),
+    );
+    expect(violations).toEqual([
+      "factory/domain/lifecycle.ts imports @t3tools/contracts, a T3 package",
+      "factory/domain/lifecycle.ts imports @t3tools/shared/git, a T3 package",
+    ]);
+  });
+
+  it("flags code outside factory/ importing the factory, except server.ts", () => {
+    const violations = findBoundaryViolations(
+      [
+        { path: "orchestration-v2/x.ts", imports: ["../factory/index.ts"] },
+        { path: "server.ts", imports: ["./factory/index.ts"] },
+      ],
+      new Set(),
+    );
+    expect(violations).toHaveLength(1);
+    expect(violations[0]).toContain("orchestration-v2/x.ts");
+  });
+
+  it("extracts static, side-effect and dynamic imports", () => {
+    expect(
+      extractImports(
+        `import a from "./a.ts";\nimport 'b';\nexport * from './c.ts';\nconst d = await import("./d.ts");`,
+      ).toSorted(),
+    ).toEqual(["./a.ts", "./c.ts", "./d.ts", "b"]);
+  });
+});

apps/server/src/factory/check.test.ts

@@ -0,0 +1,108 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import * as NodeChildProcess from "node:child_process";
+import * as NodeFS from "node:fs";
+import * as NodeOS from "node:os";
+import * as NodePath from "node:path";
+
+import { afterAll, beforeAll, describe, expect, it } from "vite-plus/test";
+
+const realScript = NodePath.resolve(import.meta.dirname, "../../../../factory/scripts/check.sh");
+
+const SEAMS = "seams";
+const TEST = "vp test run apps/server/src/factory";
+const SERVER_TYPECHECK = "vp run --filter t3 typecheck";
+const WEB_TYPECHECK = "vp run --filter @t3tools/web typecheck";
+
+// Both stubs append their invocation to $CHECK_TEST_LOG, then exit with the code
+// from $CHECK_TEST_FAIL ("<invocation>=<code>") when it names this invocation.
+const stub = (invocation: string) => `#!/usr/bin/env bash
+invocation=${invocation}
+echo "$invocation" >> "$CHECK_TEST_LOG"
+case "\${CHECK_TEST_FAIL:-}" in
+  "$invocation="*) exit "\${CHECK_TEST_FAIL##*=}" ;;
+esac
+exit 0
+`;
+
+let root: string;
+let script: string;
+
+const write = (file: string, content: string) => {
+  const full = NodePath.join(root, file);
+  NodeFS.mkdirSync(NodePath.dirname(full), { recursive: true });
+  NodeFS.writeFileSync(full, content, { mode: 0o755 });
+};
+
+let runs = 0;
+
+const run = (fail?: string, cwd = root) => {
+  const log = NodePath.join(root, `log-${runs++}`);
+  const result = NodeChildProcess.spawnSync("bash", [script], {
+    cwd,
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      PATH: `${NodePath.join(root, "bin")}:${process.env.PATH}`,
+      CHECK_TEST_LOG: log,
+      CHECK_TEST_FAIL: fail ?? "",
+    },
+  });
+  const calls = NodeFS.existsSync(log) ? NodeFS.readFileSync(log, "utf8").trim().split("\n") : [];
+  return { status: result.status, stdout: result.stdout, calls };
+};
+
+describe("check.sh", () => {
+  beforeAll(() => {
+    root = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "check-"));
+    script = NodePath.join(root, "factory/scripts/check.sh");
+    write("factory/scripts/check.sh", NodeFS.readFileSync(realScript, "utf8"));
+    write("factory/scripts/check-seams.sh", stub(SEAMS));
+    write(
+      "bin/vp",
+      `#!/usr/bin/env bash
+invocation="vp $*"
+echo "$invocation" >> "$CHECK_TEST_LOG"
+case "\${CHECK_TEST_FAIL:-}" in
+  "$invocation="*) exit "\${CHECK_TEST_FAIL##*=}" ;;
+esac
+exit 0
+`,
+    );
+  });
+
+  afterAll(() => {
+    NodeFS.rmSync(root, { recursive: true, force: true });
+  });
+
+  it("runs every step in order and exits 0", () => {
+    const { status, stdout, calls } = run();
+    expect(status).toBe(0);
+    expect(calls).toEqual([SEAMS, TEST, SERVER_TYPECHECK, WEB_TYPECHECK]);
+    const at = ["factory/scripts/check-seams.sh", TEST, SERVER_TYPECHECK, WEB_TYPECHECK].map(
+      (name) => stdout.indexOf(name),
+    );
+    expect(at[0]).toBeGreaterThanOrEqual(0);
+    expect(at).toEqual([...at].sort((a, b) => a - b));
+    expect(new Set(at).size).toBe(4);
+  });
+
+  it("runs from a subdirectory of the repo", () => {
+    const { status, calls } = run(undefined, NodePath.join(root, "bin"));
+    expect(status).toBe(0);
+    expect(calls).toEqual([SEAMS, TEST, SERVER_TYPECHECK, WEB_TYPECHECK]);
+  });
+
+  it("stops at the first failure with that command's exit code", () => {
+    const { status, stdout, calls } = run(`${SERVER_TYPECHECK}=3`);
+    expect(status).toBe(3);
+    expect(calls).toEqual([SEAMS, TEST, SERVER_TYPECHECK]);
+    expect(stdout).toContain(SERVER_TYPECHECK);
+    expect(stdout).not.toContain(WEB_TYPECHECK);
+  });
+
+  it("a failing seam check stops before any vp command", () => {
+    const { status, calls } = run(`${SEAMS}=2`);
+    expect(status).toBe(2);
+    expect(calls).toEqual([SEAMS]);
+  });
+});