diff --git a/.agents/checks/sonarjs-lint.md b/.agents/checks/sonarjs-lint.md index daa54013..0f55ce2a 100644 --- a/.agents/checks/sonarjs-lint.md +++ b/.agents/checks/sonarjs-lint.md @@ -13,9 +13,30 @@ Run `eslint-plugin-sonarjs` on changed files for SonarQube-grade bug and code-sm If install fails, skip and report: "Skipped: could not install eslint/sonarjs." Restore `package-lock.json` afterward if the install touched it (`git checkout -- package-lock.json`). 4. Run (do not suppress stderr or discard the exit status — a failed lint run must not look like a clean pass). `--no-warn-ignored` is load-bearing, not cosmetic: see the non-vacuousness note below. ```bash + report="$(mktemp)" + trap 'rm -f "$report"' EXIT + selected_files=("$@") + if [ "${#selected_files[@]}" -eq 0 ]; then + echo "INDETERMINATE: no selected files" >&2 + exit 2 + fi + status=0 npx eslint --no-config-lookup --config .agents/checks/eslint.strict.config.js \ - --no-warn-ignored --format json ; echo "eslint exit: $?" + --no-warn-ignored --format json "${selected_files[@]}" >"$report" || status=$? + echo "eslint exit: $status" + parse_status=0 + node -e 'const fs=require("node:fs"); try { const result=JSON.parse(fs.readFileSync(process.argv[1], "utf8")); const selected=process.argv.slice(2); if (!Array.isArray(result) || result.length === 0) throw new Error("empty ESLint result"); if (result.some((row) => !row || typeof row !== "object" || !Array.isArray(row.messages))) throw new Error("malformed ESLint result row"); if (result.length !== selected.length) throw new Error(`ESLint reported ${result.length} of ${selected.length} selected files`); } catch (error) { console.error(`INDETERMINATE: ${error.message}`); process.exit(2); }' "$report" "${selected_files[@]}" || parse_status=$? + if [ "$parse_status" -ne 0 ]; then + exit 2 + fi + cat "$report" + exit "$status" ``` + The block reads its file selection from positional arguments; it does not + discover changed files itself. Save it to a temporary Bash script and pass + every selected path explicitly, preserving spaces with quotes, for example: + `bash /tmp/sonarjs-lint.sh file.ts 'path with spaces.ts'`. Remove the + temporary script after the run; no repository wrapper is needed. ESLint exits `1` when it reports problems and `2` on a config/execution error. Treat exit `2`, a parse error, or empty/no output as **indeterminate** (report the failure), never as "no issues found". 5. Parse the JSON. Map eslint `severity 2`→major, `severity 1`→minor. Categorize `sonarjs/no-*`→logic, `*cognitive-complexity*`→dx, others→style. 6. Report rule ID, `path:line`, message, and a fix suggestion. diff --git a/examples/dochost-poc/dochost-driver.mjs b/examples/dochost-poc/dochost-driver.mjs index 7f3bba85..7e95d6b6 100644 --- a/examples/dochost-poc/dochost-driver.mjs +++ b/examples/dochost-poc/dochost-driver.mjs @@ -19,9 +19,10 @@ * Run: node examples/dochost-poc/dochost-driver.mjs (dochost must be on :8095) */ import { readFileSync } from "node:fs"; +import { fileURLToPath } from "node:url"; const HOST = process.env.DOC_HOST || "http://127.0.0.1:8095"; -const CMP = process.env.CMP_PIN || new URL("../../", import.meta.url).pathname; // repo root +const CMP = process.env.CMP_PIN || fileURLToPath(new URL("../../", import.meta.url)); // repo root const catalog = JSON.parse(readFileSync(`${CMP}/fixtures/catalog.json`, "utf8")); // Real base workflow: the team-spike edit-heavy session's base graph. diff --git a/examples/dochost-poc/run.sh b/examples/dochost-poc/run.sh index 227e8c30..8556ec0b 100755 --- a/examples/dochost-poc/run.sh +++ b/examples/dochost-poc/run.sh @@ -26,9 +26,18 @@ echo "== 3/4 start sidecar on :$PORT ==" ( cd "$DOCHOST_SRC" && PORT="$PORT" node dist/server.js ) & SIDECAR=$! trap 'kill "$SIDECAR" 2>/dev/null || true' EXIT +ready=0 for _ in $(seq 1 30); do - curl -sf "http://127.0.0.1:$PORT/health" >/dev/null 2>&1 && break || sleep 0.3 + if curl -sf --connect-timeout 0.1 --max-time 0.2 "http://127.0.0.1:$PORT/health" >/dev/null 2>&1; then + ready=1 + break + fi + sleep 0.3 done +if [ "$ready" -ne 1 ]; then + echo "sidecar did not become healthy on :$PORT within 15s" >&2 + exit 1 +fi echo "== 4/4 drive it ==" DOC_HOST="http://127.0.0.1:$PORT" CMP_PIN="$REPO_ROOT" \ diff --git a/scripts/bench-read.mjs b/scripts/bench-read.mjs index e604ea30..a375a8e7 100644 --- a/scripts/bench-read.mjs +++ b/scripts/bench-read.mjs @@ -181,6 +181,7 @@ const rb = readGraphThenDerive(doc); const ok = ra.nodes.size === rb.nodes.size && ra.links.size === rb.links.size && - JSON.stringify([...ra.nodes.values()]) === JSON.stringify([...rb.nodes.values()]); + JSON.stringify([...ra.nodes.values()]) === JSON.stringify([...rb.nodes.values()]) && + JSON.stringify([...ra.links.values()]) === JSON.stringify([...rb.links.values()]); console.log(`\n readers agree: ${ok} (${ra.nodes.size} nodes, ${ra.links.size} links)`); if (!ok) process.exit(1); diff --git a/test/clock-matrix/clock-matrix.test.ts b/test/clock-matrix/clock-matrix.test.ts index aac16b75..da30eb8d 100644 --- a/test/clock-matrix/clock-matrix.test.ts +++ b/test/clock-matrix/clock-matrix.test.ts @@ -1,5 +1,5 @@ import { createHash } from "node:crypto"; -import { mkdirSync, writeFileSync } from "node:fs"; +import { readFileSync } from "node:fs"; import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; import * as Y from "yjs"; @@ -8,7 +8,7 @@ import { applyOps, mint, project, type Op, type WorkflowJSON, type WorkflowNode import { loadCatalog, loadSession, sessionFiles } from "../helpers.js"; const catalog = loadCatalog(); -const OUT_DIR = dirname(fileURLToPath(import.meta.url)); +const GOLDEN_DIR = dirname(fileURLToPath(import.meta.url)); const SCHEMES = ["base_version_actor", "lamport_doc_derived", "vector_reference"] as const; type Scheme = (typeof SCHEMES)[number]; @@ -171,16 +171,25 @@ function schemeStamp(item: LogicalOp, scheme: Scheme, order: LogicalOp[]): [numb return [order.indexOf(item) + 1, item.op.actor]; } +function stampedOps(caseData: MatrixCase, scheme: Scheme): Op[] { + const ordered = orderFor(caseData, scheme); + return ordered.map((item) => ({ ...item.op, stamp: schemeStamp(item, scheme, ordered) })) as Op[]; +} + function canonicalProjection(doc: Y.Doc): WorkflowJSON { const value = structuredClone(project(doc, catalog)); value.nodes.sort((a, b) => String(a.id).localeCompare(String(b.id))); - value.links.sort((a, b) => String(a[0]).localeCompare(String(b[0]))); + // `WorkflowJSON.links` is `unknown[]`; projection emits link tuples whose + // first element is the link id. This assertion is erased at runtime. + value.links.sort((a, b) => + String((a as unknown[])[0]).localeCompare(String((b as unknown[])[0])), + ); return value; } function replay(caseData: MatrixCase, scheme: Scheme): Omit { const ordered = orderFor(caseData, scheme); - const ops = ordered.map((item) => ({ ...item.op, stamp: schemeStamp(item, scheme, ordered) })) as Op[]; + const ops = stampedOps(caseData, scheme); const doc = mint(caseData.workflow, catalog); const result = applyOps(doc, ops, catalog); const projection = canonicalProjection(doc); @@ -359,9 +368,6 @@ function runMatrix() { session_corpus, cases: rows, }; - mkdirSync(OUT_DIR, { recursive: true }); - writeFileSync(join(OUT_DIR, "matrix.json"), `${JSON.stringify(matrix, null, 2)}\n`); - writeFileSync(join(OUT_DIR, "matrix.md"), renderMarkdown(matrix)); return matrix; } @@ -378,7 +384,47 @@ describe("clock shadow-comparison acceptance matrix", () => { for (const name of ["Agent adds node A, human observes it, then connects B to A", "Dependent producer edit-1 then edit-2 before shared revision advances", "Agent edits, reconnects after restart, observes the doc, and continues monotonically", "Stale-base human edit races after agent changed related state", "Human and agent independently change the same widget", "Human changes the agent value after seeing it", "Delete-versus-edit race on a related node", "Reconnect races on the same input register", "DQ-11 incarnation transition occurs mid-stream"]) expect(matrix.cases.some((row) => row.name === name)).toBe(true); expect(matrix.cases.find((row) => row.id === "agent-add-human-connect")?.vector_relations.ordered_pairs).toBe(1); expect(matrix.cases.find((row) => row.id === "same-widget-true-concurrency")?.vector_relations.concurrent_pairs).toBe(1); - expect(matrix.summary.divergent_rows).toBeGreaterThanOrEqual(0); expect(matrix.allowlist_firing).toEqual(ALLOWLIST_FIRING); + expect(`${JSON.stringify(matrix, null, 2)}\n`).toBe(readFileSync(join(GOLDEN_DIR, "matrix.json"), "utf8")); + expect(renderMarkdown(matrix)).toBe(readFileSync(join(GOLDEN_DIR, "matrix.md"), "utf8")); + }); + + it("converges for both legal arrival orders of immutable concurrent stamps", () => { + let streams = 0; + for (const caseData of allCases()) { + if (caseData.ops.length !== 2 || happensBefore(caseData.ops[0]!.vector, caseData.ops[1]!.vector) || happensBefore(caseData.ops[1]!.vector, caseData.ops[0]!.vector)) continue; + for (const scheme of SCHEMES) { + const snapshot = Y.encodeStateAsUpdate(mint(caseData.workflow, catalog)); + const fork = () => { const doc = new Y.Doc(); Y.applyUpdate(doc, snapshot); return doc; }; + const immutableOps = stampedOps(caseData, scheme); + const forward = fork(); + const reverse = fork(); + const forwardResult = applyOps(forward, immutableOps, catalog); + const reverseResult = applyOps(reverse, [...immutableOps].reverse(), catalog); + expect(forwardResult.outcomes.every((outcome) => outcome.outcome !== "rejected"), `${caseData.id}/${scheme}/forward`).toBe(true); + expect(reverseResult.outcomes.every((outcome) => outcome.outcome !== "rejected"), `${caseData.id}/${scheme}/reverse`).toBe(true); + expect(canonicalProjection(reverse), `${caseData.id}/${scheme}`).toEqual(canonicalProjection(forward)); + streams++; + } + } + // 304 two-op streams have no vector-clock edge; each runs under 3 schemes. + expect(streams).toBe(912); + }); + + it("makes duplicate replay of every fully accepted immutable stream byte-identical", () => { + let streams = 0; + for (const caseData of allCases()) for (const scheme of SCHEMES) { + const ops = stampedOps(caseData, scheme); + const doc = mint(caseData.workflow, catalog); + const first = applyOps(doc, ops, catalog); + if (first.outcomes.some((outcome) => outcome.outcome === "rejected")) continue; + const beforeReplay = Y.encodeStateAsUpdate(doc); + const replayed = applyOps(doc, ops, catalog); + expect(replayed.outcomes.every((outcome) => outcome.outcome === "no-op"), `${caseData.id}/${scheme}`).toBe(true); + expect(Y.encodeStateAsUpdate(doc), `${caseData.id}/${scheme}`).toEqual(beforeReplay); + streams++; + } + // Every one of the 414 matrix streams is accepted under all 3 schemes. + expect(streams).toBe(1_242); }); }); diff --git a/test/portable-harness.test.ts b/test/portable-harness.test.ts new file mode 100644 index 00000000..fb518989 --- /dev/null +++ b/test/portable-harness.test.ts @@ -0,0 +1,182 @@ +import { spawn, spawnSync } from "node:child_process"; +import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { runInNewContext } from "node:vm"; +import { afterEach, describe, expect, it } from "vitest"; + +const repoRoot = dirname(dirname(fileURLToPath(import.meta.url))); +const temporary: string[] = []; + +function temp(prefix: string) { + const path = mkdtempSync(join(tmpdir(), prefix)); + temporary.push(path); + return path; +} + +afterEach(() => { + for (const path of temporary.splice(0)) rmSync(path, { recursive: true, force: true }); +}); + +describe("portable harness regressions", () => { + it.each([ + { + name: "clean complete report", + eslintStatus: 0, + output: '[{"filePath":"fixture.ts","messages":[]},{"filePath":"path with spaces.ts","messages":[]}]', + expected: 0, + selectedFiles: ["fixture.ts", "path with spaces.ts"], + }, + { + name: "partial report", + eslintStatus: 0, + output: '[{"filePath":"fixture.ts","messages":[]}]', + expected: 2, + selectedFiles: ["fixture.ts", "path with spaces.ts"], + }, + { name: "omitted inputs", eslintStatus: 0, output: "", expected: 2, selectedFiles: [] }, + { + name: "findings", + eslintStatus: 1, + output: + '[{"filePath":"fixture.ts","messages":[{"severity":2,"ruleId":"sonarjs/no-identical-expressions","line":17,"message":"Correct one of the identical sub-expressions on both sides of operator."}]}]', + expected: 1, + }, + { name: "execution error", eslintStatus: 2, output: '[{"filePath":"fixture.ts","messages":[]}]', expected: 2 }, + { name: "malformed JSON", eslintStatus: 0, output: '{', expected: 2 }, + { name: "empty output", eslintStatus: 0, output: '', expected: 2 }, + { name: "malformed result row", eslintStatus: 0, output: '[{}]', expected: 2 }, + { + name: "non-array messages", + eslintStatus: 0, + output: '[{"filePath":"fixture.ts","messages":{}}]', + expected: 2, + }, + ])("the documented SonarJS command classifies $name", ({ name, eslintStatus, output, expected, selectedFiles = ["fixture.ts"] }) => { + const profile = readFileSync(join(repoRoot, ".agents/checks/sonarjs-lint.md"), "utf8"); + const command = [...profile.matchAll(/```bash\n([\s\S]*?)\n\s*```/g)] + .map((match) => match[1]) + .find((block) => block?.includes("npx eslint")); + expect(command).toBeDefined(); + expect(command).not.toContain("npm i"); + const bin = temp("sonar-command-"); + const ambientBin = temp("hostile-ambient-node-"); + writeFileSync(join(bin, "npx"), `#!/bin/sh\nprintf '%s\\n' "$@" > eslint-arguments\nprintf '%s' '${output}'\nexit ${eslintStatus}\n`); + symlinkSync(process.execPath, join(bin, "node")); + writeFileSync(join(ambientBin, "node"), "#!/bin/sh\necho hostile ambient node >&2\nexit 127\n"); + chmodSync(join(bin, "npx"), 0o755); + chmodSync(join(ambientBin, "node"), 0o755); + const run = spawnSync("bash", ["-c", command!, "sonarjs-lint-test", ...selectedFiles], { + encoding: "utf8", + cwd: bin, + env: { ...process.env, PATH: `${bin}:${ambientBin}:/usr/bin:/bin` }, + }); + expect(run.status, `documented command stderr:\n${run.stderr}`).toBe(expected); + if (selectedFiles.length > 0) expect(run.stdout).toContain(`eslint exit: ${eslintStatus}`); + else expect(run.stderr).toContain("INDETERMINATE: no selected files"); + expect(run.stderr).not.toContain("hostile ambient node"); + if (selectedFiles.length > 0) { + const eslintArguments = readFileSync(join(bin, "eslint-arguments"), "utf8").trimEnd().split("\n"); + expect(eslintArguments.slice(-selectedFiles.length)).toEqual(selectedFiles); + } + if (name === "findings") { + expect(run.stdout).toContain('"severity":2'); + expect(run.stdout).toContain('"ruleId":"sonarjs/no-identical-expressions"'); + expect(run.stdout).toContain('"line":17'); + expect(run.stdout).toContain('"message":"Correct one of the identical sub-expressions on both sides of operator."'); + } + }); + + it("the driver's root calculation decodes a URL-encoded checkout path", () => { + const checkout = join(temp("dochost path "), "repo root"); + const driver = join(checkout, "examples/dochost-poc/dochost-driver.mjs"); + mkdirSync(dirname(driver), { recursive: true }); + const source = readFileSync(join(repoRoot, "examples/dochost-poc/dochost-driver.mjs"), "utf8"); + // Run the actual setup, stopping before catalog I/O and network operations. + const boundary = source.indexOf("const catalog ="); + expect(boundary).toBeGreaterThan(0); + writeFileSync(driver, `${source.slice(0, boundary)}\nprocess.stdout.write(CMP);\n`); + const env = { ...process.env }; + delete env.CMP_PIN; + const converted = spawnSync(process.execPath, [driver], { encoding: "utf8", env }); + expect(converted.status).toBe(0); + expect(converted.stdout.trim()).toBe(`${checkout}/`); + }); + + for (const { name, expectedStatus, healthy } of [ + { name: "unhealthy", expectedStatus: 1, healthy: false }, + { name: "healthy", expectedStatus: 0, healthy: true }, + ]) { + it(`${name} sidecar controls whether the driver runs`, () => { + const root = temp("dochost-run-"); + const bin = join(root, "bin"); + const sidecar = join(root, "sidecar"); + mkdirSync(bin); + mkdirSync(sidecar); + writeFileSync(join(bin, "npm"), "#!/bin/sh\nexit 0\n"); + writeFileSync(join(bin, "seq"), "#!/bin/sh\necho 1\n"); + writeFileSync(join(bin, "sleep"), "#!/bin/sh\nexit 0\n"); + writeFileSync(join(bin, "curl"), `#!/bin/sh\nexit ${healthy ? 0 : 1}\n`); + writeFileSync( + join(bin, "node"), + "#!/bin/sh\ncase \"$1\" in *dist/server.js) while :; do /bin/sleep 1; done;; *) echo driver-ran; exit 0;; esac\n", + ); + for (const executable of ["npm", "seq", "sleep", "curl", "node"]) + chmodSync(join(bin, executable), 0o755); + const run = spawnSync("bash", [join(repoRoot, "examples/dochost-poc/run.sh")], { + encoding: "utf8", + env: { ...process.env, PATH: `${bin}:/usr/bin:/bin`, DOCHOST_SRC: sidecar }, + }); + expect(run.status).toBe(expectedStatus); + expect(run.stdout.includes("driver-ran")).toBe(healthy); + if (!healthy) expect(run.stderr).toContain("sidecar did not become healthy"); + }); + } + + it("bounds an actual stalled health request", async () => { + const root = temp("dochost-stalled-"); + const bin = join(root, "bin"); + const sidecar = join(root, "sidecar"); + mkdirSync(bin); + mkdirSync(sidecar); + writeFileSync(join(bin, "npm"), "#!/bin/sh\nexit 0\n"); + writeFileSync(join(bin, "seq"), "#!/bin/sh\necho 1\n"); + writeFileSync(join(bin, "sleep"), "#!/bin/sh\nexit 0\n"); + writeFileSync(join(bin, "node"), "#!/bin/sh\ncase \"$1\" in *dist/server.js) while :; do /bin/sleep 1; done;; *) exit 0;; esac\n"); + for (const executable of ["npm", "seq", "sleep", "node"]) chmodSync(join(bin, executable), 0o755); + + const serverFile = join(root, "stall.mjs"); + writeFileSync(serverFile, "import net from 'node:net'; net.createServer(() => {}).listen(0, '127.0.0.1', function () { console.log(this.address().port); });\n"); + const server = spawn(process.execPath, [serverFile], { stdio: ["ignore", "pipe", "inherit"] }); + const port = await new Promise((resolve, reject) => { + server.once("error", reject); + server.stdout.once("data", (chunk) => resolve(String(chunk).trim())); + }); + try { + const started = Date.now(); + const run = spawnSync("bash", [join(repoRoot, "examples/dochost-poc/run.sh")], { + encoding: "utf8", + timeout: 2_000, + env: { ...process.env, PATH: `${bin}:/usr/bin:/bin`, DOCHOST_SRC: sidecar, PORT: port }, + }); + expect(run.error).toBeUndefined(); + expect(run.status).toBe(1); + expect(Date.now() - started).toBeLessThan(1_500); + expect(run.stderr).toContain("within 15s"); + } finally { + server.kill(); + } + }); + + it("rejects equal-count readers with unequal link values", () => { + const source = readFileSync(join(repoRoot, "scripts/bench-read.mjs"), "utf8"); + const assertion = source.match(/const ok =([\s\S]*?);/)?.[1]; + expect(assertion).toBeDefined(); + const nodes = new Map([["1", { id: "1" }]]); + const left = { nodes, links: new Map([["7", { id: "7", targetId: "1" }]]) }; + const right = { nodes, links: new Map([["7", { id: "7", targetId: "2" }]]) }; + expect(runInNewContext(assertion!, { ra: left, rb: right })).toBe(false); + expect(runInNewContext(assertion!, { ra: left, rb: left })).toBe(true); + }); +}); diff --git a/tsconfig.test.json b/tsconfig.test.json index f2022dbe..8d2f3319 100644 --- a/tsconfig.test.json +++ b/tsconfig.test.json @@ -8,6 +8,6 @@ "sourceMap": false, "types": ["node", "vitest/globals"] }, - "include": ["src", "test/*.ts", "test/permutation/*.ts"], + "include": ["src", "test/**/*.ts"], "exclude": ["test/types"] }