Skip to content
Merged
23 changes: 22 additions & 1 deletion .agents/checks/sonarjs-lint.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <changed_files>; 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.
Expand Down
3 changes: 2 additions & 1 deletion examples/dochost-poc/dochost-driver.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
11 changes: 10 additions & 1 deletion examples/dochost-poc/run.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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" \
Expand Down
3 changes: 2 additions & 1 deletion scripts/bench-read.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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);
62 changes: 54 additions & 8 deletions test/clock-matrix/clock-matrix.test.ts
Original file line number Diff line number Diff line change
@@ -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";
Expand All @@ -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];

Expand Down Expand Up @@ -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<SchemeResult, "divergence_class"> {
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);
Expand Down Expand Up @@ -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;
}

Expand All @@ -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"));
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
});

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);
});
});
182 changes: 182 additions & 0 deletions test/portable-harness.test.ts
Original file line number Diff line number Diff line change
@@ -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<string>((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);
});
});
2 changes: 1 addition & 1 deletion tsconfig.test.json
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,6 @@
"sourceMap": false,
"types": ["node", "vitest/globals"]
},
"include": ["src", "test/*.ts", "test/permutation/*.ts"],
"include": ["src", "test/**/*.ts"],
"exclude": ["test/types"]
}