refactor(evidence): extract TypeScript lifecycle (#32)

2026-08-24 02:50:56 +02:00
parent 840848df94
commit f375515dc0
8 changed files with 432 additions and 135 deletions
@@ -0,0 +1,34 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+import { expect, test } from "vitest";
+
+const evidenceRoot = fileURLToPath(new URL("../../../src/workspaces/evidence/", import.meta.url));
+const coreInfrastructure = new Set([
+  "preprocessing-service",
+  "qdrant-collection",
+  "registry",
+]);
+
+test("Evidence modules do not import core-owned registry or Qdrant lifecycle", () => {
+  const violations: Array<{ file: string; dependency: string }> = [];
+  for (const file of readdirSync(evidenceRoot).filter((name) => name.endsWith(".ts"))) {
+    const source = ts.createSourceFile(
+      file,
+      readFileSync(join(evidenceRoot, file), "utf8"),
+      ts.ScriptTarget.Latest,
+      true,
+      ts.ScriptKind.TS,
+    );
+    for (const statement of source.statements) {
+      if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) {
+        continue;
+      }
+      const dependency = basename(statement.moduleSpecifier.text).replace(/\.js$/, "");
+      if (coreInfrastructure.has(dependency)) violations.push({ file, dependency });
+    }
+  }
+
+  expect(violations).toEqual([]);
+});
@@ -0,0 +1,134 @@
+import { execFile } from "node:child_process";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { afterEach, expect, test } from "vitest";
+import { GitWorkspaceRepository } from "../../../src/workspaces/git-repository.js";
+import { materializeEvidenceTree } from "../../../src/workspaces/evidence/materialization.js";
+import type { WorkspaceRegistryConfig } from "../../../src/workspaces/types.js";
+
+const runFile = promisify(execFile);
+const temporaryRoots: string[] = [];
+
+afterEach(() => {
+  temporaryRoots.splice(0).forEach((root) => rmSync(root, { recursive: true, force: true }));
+});
+
+async function git(cwd: string, args: string[]): Promise<string> {
+  const { stdout } = await runFile("git", args, { cwd });
+  return stdout.trim();
+}
+
+function config(root: string, remoteUrl: string): WorkspaceRegistryConfig {
+  return {
+    root,
+    remoteUrl,
+    branch: "main",
+    gitAuthorName: "Evidence Materializer Test",
+    gitAuthorEmail: "evidence-materializer@example.invalid",
+    installationId: "test",
+    secretRoots: [],
+    maxImportBytes: 1024,
+    maxImportEntries: 1,
+  };
+}
+
+async function fixture(): Promise<{ root: string; remote: string; commit: string }> {
+  const root = mkdtempSync(join(tmpdir(), "thoth-evidence-materializer-"));
+  temporaryRoots.push(root);
+  const remote = join(root, "remote.git");
+  const source = join(root, "source");
+  await git(root, ["init", "--bare", "--initial-branch=main", remote]);
+  mkdirSync(source);
+  await git(source, ["init", "--initial-branch=main"]);
+  await git(source, ["config", "user.name", "Evidence Materializer Test"]);
+  await git(source, ["config", "user.email", "evidence-materializer@example.invalid"]);
+  writeFileSync(join(source, "thoth-workspaces.yaml"), "schema_version: 1\nworkspaces: [{id: research, name: Research}]\n");
+  mkdirSync(join(source, "research", "evidence", "nested"), { recursive: true });
+  writeFileSync(join(source, "research", "workspace.yaml"), "workspace:\n  schema_version: 3\n  id: research\n");
+  writeFileSync(join(source, "research", "evidence", "guide.md"), "# guide\n");
+  writeFileSync(join(source, "research", "evidence", "nested", "deep.md"), "# deep\n");
+  await git(source, ["add", "-A"]);
+  await git(source, ["commit", "-m", "initial"]);
+  await git(source, ["remote", "add", "origin", remote]);
+  await git(source, ["push", "origin", "main"]);
+  const commit = await git(source, ["rev-parse", "HEAD"]);
+  return { root, remote, commit };
+}
+
+async function repo(fixture: { root: string; remote: string }): Promise<GitWorkspaceRepository> {
+  const repository = new GitWorkspaceRepository(config(join(fixture.root, "registry"), fixture.remote));
+  await repository.bootstrap();
+  return repository;
+}
+
+test("materializes the tree, hashes every file, and writes a bounded manifest", async () => {
+  const fixtureValue = await fixture();
+  const repository = await repo(fixtureValue);
+  const target = mkdtempSync(join(tmpdir(), "thoth-evidence-target-"));
+  temporaryRoots.push(target);
+
+  const result = await materializeEvidenceTree({
+    repository,
+    revision: fixtureValue.commit,
+    id: "research",
+    targetDirectory: target,
+  });
+
+  expect(readFileSync(join(result.root, "guide.md"), "utf8")).toBe("# guide\n");
+  expect(readFileSync(join(result.root, "nested", "deep.md"), "utf8")).toBe("# deep\n");
+  expect(result.manifest).toMatchObject({
+    schemaVersion: 1,
+    workspace: "research",
+    commit: fixtureValue.commit,
+    entryCount: 2,
+  });
+  expect(Object.keys(result.manifest.files).sort()).toEqual(["guide.md", "nested/deep.md"]);
+  expect(result.manifest.files["guide.md"]!.digest).toMatch(/^sha256:[0-9a-f]{64}$/);
+  expect(result.manifestDigest).toMatch(/^[0-9a-f]{64}$/);
+  expect(readFileSync(result.manifestPath, "utf8")).toContain('"entryCount":2');
+});
+
+test("refuses symlink-containing trees and bound violations without publishing", async () => {
+  const root = mkdtempSync(join(tmpdir(), "thoth-evidence-unsafe-"));
+  temporaryRoots.push(root);
+  const remote = join(root, "remote.git");
+  const source = join(root, "source");
+  await git(root, ["init", "--bare", "--initial-branch=main", remote]);
+  mkdirSync(source);
+  await git(source, ["init", "--initial-branch=main"]);
+  await git(source, ["config", "user.name", "E"]);
+  await git(source, ["config", "user.email", "e@e.invalid"]);
+  writeFileSync(join(source, "thoth-workspaces.yaml"), "schema_version: 1\nworkspaces: [{id: research, name: Research}]\n");
+  mkdirSync(join(source, "research", "evidence"), { recursive: true });
+  writeFileSync(join(source, "research", "workspace.yaml"), "workspace:\n  schema_version: 3\n  id: research\n");
+  writeFileSync(join(source, "research", "outside.md"), "# outside\n");
+  symlinkSync("../outside.md", join(source, "research", "evidence", "link.md"));
+  await git(source, ["add", "-A"]);
+  await git(source, ["commit", "-m", "symlink"]);
+  await git(source, ["remote", "add", "origin", remote]);
+  await git(source, ["push", "origin", "main"]);
+  const commit = await git(source, ["rev-parse", "HEAD"]);
+  const repository = await repo({ root, remote });
+  const target = mkdtempSync(join(tmpdir(), "thoth-evidence-unsafe-target-"));
+  temporaryRoots.push(target);
+
+  await expect(materializeEvidenceTree({ repository, revision: commit, id: "research", targetDirectory: target }))
+    .rejects.toThrow();
+  expect(readdirSync(target)).toEqual([]);
+
+  // A valid tree but a per-file bound of 1 byte must also refuse.
+  const fixtureValue = await fixture();
+  const repository2 = await repo(fixtureValue);
+  const target2 = mkdtempSync(join(tmpdir(), "thoth-evidence-bound-target-"));
+  temporaryRoots.push(target2);
+  await expect(materializeEvidenceTree({
+    repository: repository2,
+    revision: fixtureValue.commit,
+    id: "research",
+    targetDirectory: target2,
+    limits: { maxFileBytes: 1 },
+  })).rejects.toThrow();
+  expect(readdirSync(target2)).toEqual([]);
+});
@@ -0,0 +1,161 @@
+import { expect, test, vi } from "vitest";
+import {
+  continueEvidencePreprocessing,
+  preprocessEvidence,
+  type EvidenceJobState,
+  type EvidencePreprocessingDependencies,
+} from "../../../src/workspaces/evidence/preprocessing.js";
+import type { WorkspaceDescriptor } from "../../../src/workspaces/schema.js";
+
+type EvidenceConfig = NonNullable<WorkspaceDescriptor["evidence"]>;
+
+const filesystemEvidence = {
+  source: { type: "filesystem", uri: "research/evidence" },
+} as EvidenceConfig;
+
+const privateHttpEvidence = {
+  source: {
+    type: "http",
+    uris: ["http://127.0.0.1/private.md"],
+    authentication: "none",
+    connect_timeout_ms: 1000,
+    read_timeout_ms: 2000,
+    max_bytes: 100,
+    max_redirects: 0,
+    allow_private_hosts: true,
+    max_cache_bytes: 100,
+  },
+} as EvidenceConfig;
+
+function job(overrides: Partial<EvidenceJobState> = {}): EvidenceJobState {
+  return {
+    runId: "a".repeat(32),
+    childRuns: {},
+    completedStages: [],
+    ...overrides,
+  };
+}
+
+function dependencies(payload: Record<string, unknown> = {}): EvidencePreprocessingDependencies & {
+  runStage: ReturnType<typeof vi.fn>;
+  persistJob: ReturnType<typeof vi.fn>;
+  semanticPreflight: ReturnType<typeof vi.fn>;
+} {
+  return {
+    runStage: vi.fn(async () => payload),
+    persistJob: vi.fn(),
+    semanticPreflight: vi.fn(async () => ({ ok: true as const })),
+    requireRunId(value) {
+      if (typeof value !== "string" || !/^[0-9a-f]{32}$/.test(value)) {
+        throw new Error("child run id is invalid");
+      }
+      return value;
+    },
+    numberRecord(value) {
+      if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+      return Object.fromEntries(
+        Object.entries(value as Record<string, unknown>).map(([key, nested]) => [key, Number(nested)]),
+      );
+    },
+  };
+}
+
+test("owns the standalone Evidence stage argv and mutation order", async () => {
+  const state = job({ childRuns: { evidence: "b".repeat(32) } });
+  const deps = dependencies({ run_id: "c".repeat(32), counts: { added: 2 } });
+
+  const result = await preprocessEvidence(
+    { evidence: filesystemEvidence, job: state, dryRun: false },
+    deps,
+  );
+
+  expect(deps.semanticPreflight).toHaveBeenCalledOnce();
+  expect(deps.runStage).toHaveBeenCalledWith([
+    "preprocess", "evidence", "--resume", "b".repeat(32), "--json", "-c", "/dev/fd/3",
+  ]);
+  expect(deps.persistJob).toHaveBeenCalledOnce();
+  expect(state).toMatchObject({
+    childRuns: { evidence: "c".repeat(32) },
+    completedStages: ["evidence"],
+  });
+  expect(result).toEqual({
+    status: "succeeded",
+    code: "ok",
+    runId: "a".repeat(32),
+    childRuns: { evidence: "c".repeat(32) },
+    completedStages: ["evidence"],
+    counts: { added: 2 },
+  });
+});
+
+test("owns Evidence egress refusal before shared semantic infrastructure", async () => {
+  const deps = dependencies();
+
+  const result = await preprocessEvidence(
+    {
+      evidence: privateHttpEvidence,
+      job: job(),
+      httpPrivateHostAllowlist: ["metadata.internal"],
+    },
+    deps,
+  );
+
+  expect(result).toEqual({ status: "failed", code: "egress_policy_refused" });
+  expect(deps.semanticPreflight).not.toHaveBeenCalled();
+  expect(deps.runStage).not.toHaveBeenCalled();
+  expect(deps.persistJob).not.toHaveBeenCalled();
+});
+
+test("projects aggregate no-Evidence and completed-stage outcomes without rerunning", async () => {
+  const deps = dependencies();
+  const noEvidence = await continueEvidencePreprocessing(
+    {
+      evidence: undefined,
+      job: job({ completedStages: ["dwh", "schema_index"] }),
+      priorCounts: { added: 2 },
+    },
+    deps,
+  );
+  const completed = await continueEvidencePreprocessing(
+    {
+      evidence: filesystemEvidence,
+      job: job({ completedStages: ["dwh", "schema_index", "evidence"] }),
+    },
+    deps,
+  );
+
+  expect(noEvidence).toMatchObject({
+    status: "succeeded",
+    code: "ok",
+    warnings: ["workspace has no Evidence source"],
+    counts: { added: 2 },
+  });
+  expect(completed).toMatchObject({
+    status: "unchanged",
+    code: "ok",
+    completedStages: ["dwh", "schema_index", "evidence"],
+  });
+  expect(deps.runStage).not.toHaveBeenCalled();
+  expect(deps.persistJob).not.toHaveBeenCalled();
+});
+
+test("preserves the narrow standalone projection for an already completed Evidence stage", async () => {
+  const deps = dependencies();
+
+  const result = await preprocessEvidence(
+    {
+      evidence: filesystemEvidence,
+      job: job({ childRuns: { evidence: "b".repeat(32) }, completedStages: ["evidence"] }),
+    },
+    deps,
+  );
+
+  expect(result).toEqual({
+    status: "unchanged",
+    code: "ok",
+    runId: "a".repeat(32),
+    completedStages: ["evidence"],
+  });
+  expect(deps.runStage).not.toHaveBeenCalled();
+  expect(deps.persistJob).not.toHaveBeenCalled();
+});