Skip to content

Graphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.

feat(bench): add deterministic large-repo scale reports

KumamuKumac5e482f41dee
diff --git a/docs/benchmarks/large-repo-report-1.0.0.schema.json b/docs/benchmarks/large-repo-report-1.0.0.schema.json
new file mode 100644
index 00000000..8ebbfeba
--- /dev/null
+++ b/docs/benchmarks/large-repo-report-1.0.0.schema.json
@@ -0,0 +1,575 @@
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": "https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/docs/benchmarks/large-repo-report-1.0.0.schema.json",
+ "title": "Understand Anything deterministic large-repository benchmark report",
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "schemaUrl",
+ "schemaVersion",
+ "status",
+ "mode",
+ "run",
+ "tool",
+ "subject",
+ "environment",
+ "configuration",
+ "scale",
+ "stages",
+ "integrity",
+ "determinism",
+ "llm",
+ "warnings",
+ "error"
+ ],
+ "properties": {
+ "schemaUrl": {
+ "const": "https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/docs/benchmarks/large-repo-report-1.0.0.schema.json"
+ },
+ "schemaVersion": { "const": "1.0.0" },
+ "status": { "enum": ["ok", "degraded", "failed"] },
+ "mode": { "const": "deterministic" },
+ "run": { "$ref": "#/$defs/run" },
+ "tool": { "$ref": "#/$defs/tool" },
+ "subject": { "$ref": "#/$defs/subject" },
+ "environment": { "$ref": "#/$defs/environment" },
+ "configuration": { "$ref": "#/$defs/configuration" },
+ "scale": {
+ "oneOf": [
+ { "$ref": "#/$defs/scale" },
+ { "type": "null" }
+ ]
+ },
+ "stages": { "$ref": "#/$defs/stages" },
+ "integrity": {
+ "oneOf": [
+ { "$ref": "#/$defs/integrity" },
+ { "type": "null" }
+ ]
+ },
+ "determinism": {
+ "oneOf": [
+ { "$ref": "#/$defs/determinism" },
+ { "type": "null" }
+ ]
+ },
+ "llm": { "$ref": "#/$defs/llm" },
+ "warnings": {
+ "type": "array",
+ "items": { "$ref": "#/$defs/warning" }
+ },
+ "error": { "type": ["string", "null"] }
+ },
+ "allOf": [
+ {
+ "if": {
+ "properties": { "status": { "enum": ["ok", "degraded"] } },
+ "required": ["status"]
+ },
+ "then": {
+ "properties": {
+ "scale": { "$ref": "#/$defs/scale" },
+ "stages": {
+ "type": "object",
+ "required": ["scan", "imports", "batching", "structure"],
+ "properties": {
+ "scan": {
+ "type": "object",
+ "properties": { "status": { "const": "ok" } }
+ },
+ "imports": {
+ "type": "object",
+ "properties": { "status": { "const": "ok" } }
+ },
+ "batching": {
+ "type": "object",
+ "properties": { "status": { "const": "ok" } }
+ },
+ "structure": {
+ "type": "object",
+ "properties": { "status": { "const": "ok" } }
+ }
+ }
+ },
+ "integrity": { "$ref": "#/$defs/successIntegrity" },
+ "determinism": { "$ref": "#/$defs/determinism" },
+ "error": { "type": "null" }
+ }
+ }
+ },
+ {
+ "if": {
+ "properties": { "status": { "const": "ok" } },
+ "required": ["status"]
+ },
+ "then": {
+ "properties": {
+ "warnings": { "type": "array", "maxItems": 0 },
+ "integrity": {
+ "type": "object",
+ "properties": { "filesSkipped": { "const": 0 } }
+ },
+ "stages": {
+ "type": "object",
+ "properties": {
+ "scan": { "$ref": "#/$defs/noWarningsStage" },
+ "imports": { "$ref": "#/$defs/noWarningsStage" },
+ "batching": { "$ref": "#/$defs/noWarningsStage" },
+ "structure": {
+ "allOf": [
+ { "$ref": "#/$defs/noWarningsStage" },
+ {
+ "type": "object",
+ "properties": { "filesSkipped": { "const": 0 } }
+ }
+ ]
+ }
+ }
+ }
+ }
+ }
+ },
+ {
+ "if": {
+ "properties": { "status": { "const": "failed" } },
+ "required": ["status"]
+ },
+ "then": {
+ "properties": {
+ "error": { "type": "string", "minLength": 1 }
+ }
+ }
+ }
+ ],
+ "$defs": {
+ "nullableString": { "type": ["string", "null"] },
+ "nullableBoolean": { "type": ["boolean", "null"] },
+ "nullableNumber": { "type": ["number", "null"], "minimum": 0 },
+ "count": { "type": "integer", "minimum": 0 },
+ "status": { "enum": ["ok", "failed"] },
+ "noWarningsStage": {
+ "type": "object",
+ "properties": {
+ "warningCount": { "const": 0 },
+ "warningMessages": { "type": "array", "maxItems": 0 },
+ "warningMessagesTruncated": { "const": false }
+ }
+ },
+ "run": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["startedAt", "finishedAt", "durationMs"],
+ "properties": {
+ "startedAt": { "type": "string", "format": "date-time" },
+ "finishedAt": { "type": ["string", "null"], "format": "date-time" },
+ "durationMs": { "$ref": "#/$defs/nullableNumber" }
+ }
+ },
+ "tool": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["commit", "dirty", "packageVersion"],
+ "properties": {
+ "commit": { "$ref": "#/$defs/nullableString" },
+ "dirty": { "$ref": "#/$defs/nullableBoolean" },
+ "packageVersion": { "type": "string" }
+ }
+ },
+ "subject": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["label", "commit", "dirty"],
+ "properties": {
+ "label": { "type": "string" },
+ "commit": { "$ref": "#/$defs/nullableString" },
+ "dirty": { "$ref": "#/$defs/nullableBoolean" }
+ }
+ },
+ "environment": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "platform",
+ "release",
+ "arch",
+ "nodeVersion",
+ "cpuModel",
+ "logicalCores",
+ "totalMemoryBytes"
+ ],
+ "properties": {
+ "platform": { "type": "string" },
+ "release": { "type": "string" },
+ "arch": { "type": "string" },
+ "nodeVersion": { "type": "string" },
+ "cpuModel": { "type": "string" },
+ "logicalCores": { "type": "integer", "minimum": 1 },
+ "totalMemoryBytes": { "type": "integer", "minimum": 0 }
+ }
+ },
+ "configuration": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["concurrency", "stages"],
+ "properties": {
+ "concurrency": { "type": "integer", "minimum": 1, "maximum": 32 },
+ "stages": {
+ "const": ["scan", "imports", "batching", "structure"]
+ }
+ }
+ },
+ "stringCountMap": {
+ "type": "object",
+ "additionalProperties": { "$ref": "#/$defs/count" }
+ },
+ "scale": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "files",
+ "lines",
+ "bytes",
+ "missingFiles",
+ "filteredByUserIgnore",
+ "byCategory",
+ "byLanguage"
+ ],
+ "properties": {
+ "files": { "$ref": "#/$defs/count" },
+ "lines": { "$ref": "#/$defs/count" },
+ "bytes": { "$ref": "#/$defs/count" },
+ "missingFiles": { "$ref": "#/$defs/count" },
+ "filteredByUserIgnore": { "$ref": "#/$defs/count" },
+ "byCategory": { "$ref": "#/$defs/stringCountMap" },
+ "byLanguage": { "$ref": "#/$defs/stringCountMap" }
+ }
+ },
+ "scanStage": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "status",
+ "durationMs",
+ "peakRssBytes",
+ "userCpuTimeMicros",
+ "systemCpuTimeMicros",
+ "warningCount",
+ "warningMessages",
+ "warningMessagesTruncated",
+ "stdoutTruncated",
+ "stderrTruncated",
+ "outputBytes"
+ ],
+ "properties": {
+ "status": { "$ref": "#/$defs/status" },
+ "durationMs": { "type": "number", "minimum": 0 },
+ "peakRssBytes": { "$ref": "#/$defs/nullableNumber" },
+ "userCpuTimeMicros": { "$ref": "#/$defs/nullableNumber" },
+ "systemCpuTimeMicros": { "$ref": "#/$defs/nullableNumber" },
+ "warningCount": { "$ref": "#/$defs/count" },
+ "warningMessages": { "$ref": "#/$defs/warningMessages" },
+ "warningMessagesTruncated": { "type": "boolean" },
+ "stdoutTruncated": { "type": "boolean" },
+ "stderrTruncated": { "type": "boolean" },
+ "outputBytes": { "$ref": "#/$defs/count" },
+ "files": { "$ref": "#/$defs/count" },
+ "lines": { "$ref": "#/$defs/count" },
+ "bytes": { "$ref": "#/$defs/count" },
+ "filteredByUserIgnore": { "$ref": "#/$defs/count" }
+ },
+ "allOf": [
+ {
+ "if": {
+ "properties": { "status": { "const": "ok" } },
+ "required": ["status"]
+ },
+ "then": {
+ "required": [
+ "files",
+ "lines",
+ "bytes",
+ "filteredByUserIgnore"
+ ]
+ }
+ }
+ ]
+ },
+ "importsStage": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "status",
+ "durationMs",
+ "peakRssBytes",
+ "userCpuTimeMicros",
+ "systemCpuTimeMicros",
+ "warningCount",
+ "warningMessages",
+ "warningMessagesTruncated",
+ "stdoutTruncated",
+ "stderrTruncated",
+ "outputBytes"
+ ],
+ "properties": {
+ "status": { "$ref": "#/$defs/status" },
+ "durationMs": { "type": "number", "minimum": 0 },
+ "peakRssBytes": { "$ref": "#/$defs/nullableNumber" },
+ "userCpuTimeMicros": { "$ref": "#/$defs/nullableNumber" },
+ "systemCpuTimeMicros": { "$ref": "#/$defs/nullableNumber" },
+ "warningCount": { "$ref": "#/$defs/count" },
+ "warningMessages": { "$ref": "#/$defs/warningMessages" },
+ "warningMessagesTruncated": { "type": "boolean" },
+ "stdoutTruncated": { "type": "boolean" },
+ "stderrTruncated": { "type": "boolean" },
+ "outputBytes": { "$ref": "#/$defs/count" },
+ "filesScanned": { "$ref": "#/$defs/count" },
+ "filesWithImports": { "$ref": "#/$defs/count" },
+ "edges": { "$ref": "#/$defs/count" }
+ },
+ "allOf": [
+ {
+ "if": {
+ "properties": { "status": { "const": "ok" } },
+ "required": ["status"]
+ },
+ "then": {
+ "required": ["filesScanned", "filesWithImports", "edges"]
+ }
+ }
+ ]
+ },
+ "distribution": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["min", "p50", "p95", "max", "mean"],
+ "properties": {
+ "min": { "type": "number", "minimum": 0 },
+ "p50": { "type": "number", "minimum": 0 },
+ "p95": { "type": "number", "minimum": 0 },
+ "max": { "type": "number", "minimum": 0 },
+ "mean": { "type": "number", "minimum": 0 }
+ }
+ },
+ "batchingStage": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "status",
+ "durationMs",
+ "peakRssBytes",
+ "userCpuTimeMicros",
+ "systemCpuTimeMicros",
+ "warningCount",
+ "warningMessages",
+ "warningMessagesTruncated",
+ "stdoutTruncated",
+ "stderrTruncated",
+ "outputBytes"
+ ],
+ "properties": {
+ "status": { "$ref": "#/$defs/status" },
+ "durationMs": { "type": "number", "minimum": 0 },
+ "peakRssBytes": { "$ref": "#/$defs/nullableNumber" },
+ "userCpuTimeMicros": { "$ref": "#/$defs/nullableNumber" },
+ "systemCpuTimeMicros": { "$ref": "#/$defs/nullableNumber" },
+ "warningCount": { "$ref": "#/$defs/count" },
+ "warningMessages": { "$ref": "#/$defs/warningMessages" },
+ "warningMessagesTruncated": { "type": "boolean" },
+ "stdoutTruncated": { "type": "boolean" },
+ "stderrTruncated": { "type": "boolean" },
+ "outputBytes": { "$ref": "#/$defs/count" },
+ "algorithm": { "type": "string" },
+ "totalBatches": { "$ref": "#/$defs/count" },
+ "batchSizes": { "$ref": "#/$defs/distribution" },
+ "estimatedAgentInputBytes": { "$ref": "#/$defs/count" }
+ },
+ "allOf": [
+ {
+ "if": {
+ "properties": { "status": { "const": "ok" } },
+ "required": ["status"]
+ },
+ "then": {
+ "required": [
+ "algorithm",
+ "totalBatches",
+ "batchSizes",
+ "estimatedAgentInputBytes"
+ ]
+ }
+ }
+ ]
+ },
+ "entities": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "functions",
+ "classes",
+ "exports",
+ "callGraph",
+ "definitions",
+ "services",
+ "endpoints",
+ "steps",
+ "resources"
+ ],
+ "properties": {
+ "functions": { "$ref": "#/$defs/count" },
+ "classes": { "$ref": "#/$defs/count" },
+ "exports": { "$ref": "#/$defs/count" },
+ "callGraph": { "$ref": "#/$defs/count" },
+ "definitions": { "$ref": "#/$defs/count" },
+ "services": { "$ref": "#/$defs/count" },
+ "endpoints": { "$ref": "#/$defs/count" },
+ "steps": { "$ref": "#/$defs/count" },
+ "resources": { "$ref": "#/$defs/count" }
+ }
+ },
+ "structureStage": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "status",
+ "durationMs",
+ "maxWorkerPeakRssBytes",
+ "userCpuTimeMicros",
+ "systemCpuTimeMicros",
+ "warningCount",
+ "warningMessages",
+ "warningMessagesTruncated",
+ "outputBytes"
+ ],
+ "properties": {
+ "status": { "$ref": "#/$defs/status" },
+ "durationMs": { "type": "number", "minimum": 0 },
+ "maxWorkerPeakRssBytes": { "$ref": "#/$defs/nullableNumber" },
+ "userCpuTimeMicros": { "$ref": "#/$defs/nullableNumber" },
+ "systemCpuTimeMicros": { "$ref": "#/$defs/nullableNumber" },
+ "warningCount": { "$ref": "#/$defs/count" },
+ "warningMessages": { "$ref": "#/$defs/warningMessages" },
+ "warningMessagesTruncated": { "type": "boolean" },
+ "outputBytes": { "$ref": "#/$defs/count" },
+ "batchesSucceeded": { "$ref": "#/$defs/count" },
+ "batchesFailed": { "$ref": "#/$defs/count" },
+ "filesAnalyzed": { "$ref": "#/$defs/count" },
+ "filesSkipped": { "$ref": "#/$defs/count" },
+ "entities": { "$ref": "#/$defs/entities" },
+ "batchDurationMs": { "$ref": "#/$defs/distribution" }
+ },
+ "allOf": [
+ {
+ "if": {
+ "properties": { "status": { "const": "ok" } },
+ "required": ["status"]
+ },
+ "then": {
+ "required": [
+ "batchesSucceeded",
+ "batchesFailed",
+ "filesAnalyzed",
+ "filesSkipped",
+ "entities",
+ "batchDurationMs"
+ ]
+ }
+ }
+ ]
+ },
+ "stages": {
+ "type": "object",
+ "additionalProperties": false,
+ "properties": {
+ "scan": { "$ref": "#/$defs/scanStage" },
+ "imports": { "$ref": "#/$defs/importsStage" },
+ "batching": { "$ref": "#/$defs/batchingStage" },
+ "structure": { "$ref": "#/$defs/structureStage" }
+ }
+ },
+ "integrity": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "allScannedFilesBatched",
+ "missingBatchFiles",
+ "duplicateBatchFiles",
+ "unexpectedBatchFiles",
+ "missingImportTargets",
+ "structureCoverage",
+ "filesSkipped",
+ "failedBatches",
+ "missingStructurePaths",
+ "duplicateStructurePaths",
+ "unexpectedStructurePaths",
+ "malformedStructureBatches"
+ ],
+ "properties": {
+ "allScannedFilesBatched": { "type": "boolean" },
+ "missingBatchFiles": { "$ref": "#/$defs/count" },
+ "duplicateBatchFiles": { "$ref": "#/$defs/count" },
+ "unexpectedBatchFiles": { "$ref": "#/$defs/count" },
+ "missingImportTargets": { "$ref": "#/$defs/count" },
+ "structureCoverage": { "type": "number", "minimum": 0, "maximum": 1 },
+ "filesSkipped": { "$ref": "#/$defs/count" },
+ "failedBatches": { "$ref": "#/$defs/count" },
+ "missingStructurePaths": { "$ref": "#/$defs/count" },
+ "duplicateStructurePaths": { "$ref": "#/$defs/count" },
+ "unexpectedStructurePaths": { "$ref": "#/$defs/count" },
+ "malformedStructureBatches": { "$ref": "#/$defs/count" }
+ }
+ },
+ "successIntegrity": {
+ "type": "object",
+ "properties": {
+ "allScannedFilesBatched": { "const": true },
+ "missingBatchFiles": { "const": 0 },
+ "duplicateBatchFiles": { "const": 0 },
+ "unexpectedBatchFiles": { "const": 0 },
+ "missingImportTargets": { "const": 0 },
+ "structureCoverage": { "const": 1 },
+ "failedBatches": { "const": 0 },
+ "missingStructurePaths": { "const": 0 },
+ "duplicateStructurePaths": { "const": 0 },
+ "unexpectedStructurePaths": { "const": 0 },
+ "malformedStructureBatches": { "const": 0 }
+ }
+ },
+ "determinism": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["algorithm", "inputDigest", "outputDigest"],
+ "properties": {
+ "algorithm": { "const": "sha256" },
+ "inputDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+ "outputDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+ }
+ },
+ "llm": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["invoked", "inputTokens", "outputTokens", "costUsd"],
+ "properties": {
+ "invoked": { "const": false },
+ "inputTokens": { "type": "null" },
+ "outputTokens": { "type": "null" },
+ "costUsd": { "type": "null" }
+ }
+ },
+ "warning": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["stage", "count", "messages", "truncated"],
+ "properties": {
+ "stage": { "enum": ["scan", "imports", "batching", "structure"] },
+ "count": { "$ref": "#/$defs/count" },
+ "messages": { "$ref": "#/$defs/warningMessages" },
+ "truncated": { "type": "boolean" }
+ }
+ },
+ "warningMessages": {
+ "type": "array",
+ "maxItems": 5,
+ "items": { "type": "string" }
+ }
+ }
+}
diff --git a/package.json b/package.json
index c1f805f7..9beba876 100644
--- a/package.json
+++ b/package.json
@@ -30,11 +30,13 @@
"prepare": "pnpm --filter @understand-anything/core build",
"build": "pnpm -r build",
"test": "vitest run",
+ "benchmark:large-repo": "node scripts/benchmark-large-repo.mjs",
"dev:dashboard": "pnpm --filter @understand-anything/dashboard dev",
"lint": "eslint ."
},
"devDependencies": {
"@eslint/js": "^9.0.0",
+ "ajv": "8.17.1",
"eslint": "^9.0.0",
"globals": "^17.6.0",
"typescript": "^5.7.0",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e3eac16a..a8d1b343 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -11,6 +11,9 @@ importers:
'@eslint/js':
specifier: ^9.0.0
version: 9.39.4
+ ajv:
+ specifier: 8.17.1
+ version: 8.17.1
eslint:
specifier: ^9.0.0
version: 9.39.4([email protected])
@@ -1363,6 +1366,9 @@ packages:
resolution: {integrity: sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw==}
+ resolution: {integrity: sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==}
+
resolution: {integrity: sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==}
engines: {node: '>=8'}
@@ -1794,6 +1800,9 @@ packages:
resolution: {integrity: sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==}
+ resolution: {integrity: sha512-i70LwGWUduXqzicKXWshooq+sWL1K3WUU5rKZNG/0i3a1OSoX3HqhH5WbWwTmqWfor4urUakGPiRQcleRZTwOg==}
+
resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==}
engines: {node: '>=12.0.0'}
@@ -2075,6 +2084,9 @@ packages:
resolution: {integrity: sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==}
+ resolution: {integrity: sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==}
+
resolution: {integrity: sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==}
@@ -2667,6 +2679,10 @@ packages:
resolution: {integrity: sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw==}
+ resolution: {integrity: sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==}
+ engines: {node: '>=0.10.0'}
+
resolution: {integrity: sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g==}
engines: {node: '>=4'}
@@ -4405,6 +4421,13 @@ snapshots:
json-schema-traverse: 0.4.1
uri-js: 4.4.1
+ dependencies:
+ fast-deep-equal: 3.1.3
+ fast-uri: 3.1.3
+ json-schema-traverse: 1.0.0
+ require-from-string: 2.0.2
+
@@ -4928,6 +4951,8 @@ snapshots:
+
optionalDependencies:
picomatch: 4.0.3
@@ -5256,6 +5281,8 @@ snapshots:
+
@@ -6047,6 +6074,8 @@ snapshots:
mdast-util-to-markdown: 2.1.2
unified: 11.0.5
+
diff --git a/scripts/benchmark-large-repo.mjs b/scripts/benchmark-large-repo.mjs
new file mode 100644
index 00000000..5e3f345a
--- /dev/null
+++ b/scripts/benchmark-large-repo.mjs
@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+import {
+ BenchmarkArtifactCleanupError,
+ BenchmarkReportWriteError,
+ CliUsageError,
+ helpText,
+ parseArgs,
+ runBenchmark,
+} from './lib/large-repo-benchmark.mjs';
+
+async function main() {
+ let options;
+ try {
+ options = parseArgs(process.argv.slice(2));
+ } catch (error) {
+ if (error instanceof CliUsageError) {
+ process.stderr.write(`Error: ${error.message}\n\n${helpText()}`);
+ process.exitCode = 2;
+ return;
+ }
+ throw error;
+ }
+
+ if (options.help) {
+ process.stdout.write(helpText());
+ return;
+ }
+
+ let result;
+ try {
+ result = await runBenchmark(options, {
+ onProgress(stage) {
+ process.stderr.write(`[benchmark] ${stage}\n`);
+ },
+ onBatchProgress(completed, total) {
+ process.stderr.write(`[benchmark] structure ${completed}/${total}\n`);
+ },
+ });
+ } catch (error) {
+ if (error instanceof BenchmarkArtifactCleanupError) {
+ process.stderr.write(`Error: ${error.message}\n`);
+ process.exitCode = 1;
+ return;
+ }
+ if (error instanceof BenchmarkReportWriteError) {
+ process.stderr.write(`Error: ${error.message}\n`);
+ process.exitCode = 1;
+ return;
+ }
+ throw error;
+ }
+
+ process.stdout.write(
+ `Benchmark ${result.report.status}. JSON report: ${options.outputPath}\n` +
+ `Markdown report: ${options.markdownPath}\n`,
+ );
+ if (result.artifactRoot) {
+ process.stdout.write(`Artifacts preserved at: ${result.artifactRoot}\n`);
+ }
+ process.exitCode = result.exitCode;
+}
+
+await main();
diff --git a/scripts/lib/benchmark-stage-worker.mjs b/scripts/lib/benchmark-stage-worker.mjs
new file mode 100644
index 00000000..1f92256d
--- /dev/null
+++ b/scripts/lib/benchmark-stage-worker.mjs
@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+import { performance } from 'node:perf_hooks';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export const STAGE_METRICS_PREFIX = '__UA_BENCHMARK_METRICS__';
+
+const [scriptPath, ...scriptArgs] = process.argv.slice(2);
+if (!scriptPath) {
+ process.stderr.write('benchmark-stage-worker: missing script path\n');
+ process.exit(2);
+}
+
+const resolvedScript = resolve(scriptPath);
+const startedAt = performance.now();
+const usageBefore = process.resourceUsage();
+let failure = null;
+
+try {
+ // The deterministic helpers use process.argv to identify their CLI entry
+ // point. Recreate the argv shape they receive when launched directly, then
+ // import them in this process so resourceUsage() measures the real stage.
+ process.argv = [process.execPath, resolvedScript, ...scriptArgs];
+ await import(pathToFileURL(resolvedScript).href);
+} catch (error) {
+ failure = error instanceof Error ? error : new Error(String(error));
+ process.stderr.write(`${failure.stack ?? failure.message}\n`);
+}
+
+const usageAfter = process.resourceUsage();
+const metrics = {
+ durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
+ // Node reports maxRSS in KiB on every supported platform.
+ peakRssBytes: usageAfter.maxRSS * 1024,
+ userCpuTimeMicros: usageAfter.userCPUTime - usageBefore.userCPUTime,
+ systemCpuTimeMicros: usageAfter.systemCPUTime - usageBefore.systemCPUTime,
+};
+
+process.stderr.write(`${STAGE_METRICS_PREFIX}${JSON.stringify(metrics)}\n`);
+if (failure) process.exitCode = 1;
diff --git a/scripts/lib/large-repo-benchmark.mjs b/scripts/lib/large-repo-benchmark.mjs
new file mode 100644
index 00000000..8041abf0
--- /dev/null
+++ b/scripts/lib/large-repo-benchmark.mjs
@@ -0,0 +1,1620 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import {
+ closeSync,
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ openSync,
+ readFileSync,
+ realpathSync,
+ renameSync,
+ rmSync,
+ statSync,
+ writeFileSync,
+} from 'node:fs';
+import {
+ arch,
+ cpus,
+ platform,
+ release,
+ tmpdir,
+ totalmem,
+} from 'node:os';
+import {
+ basename,
+ dirname,
+ isAbsolute,
+ join,
+ relative,
+ resolve,
+ sep,
+} from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { StringDecoder } from 'node:string_decoder';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export const REPO_ROOT = resolve(__dirname, '../..');
+export const REPORT_SCHEMA_VERSION = '1.0.0';
+export const REPORT_SCHEMA_URL =
+ 'https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/docs/benchmarks/large-repo-report-1.0.0.schema.json';
+
+const WORKER = resolve(__dirname, 'benchmark-stage-worker.mjs');
+const SCAN_SCRIPT = resolve(
+ REPO_ROOT,
+ 'understand-anything-plugin/skills/understand/scan-project.mjs',
+);
+const IMPORT_SCRIPT = resolve(
+ REPO_ROOT,
+ 'understand-anything-plugin/skills/understand/extract-import-map.mjs',
+);
+const BATCH_SCRIPT = resolve(
+ REPO_ROOT,
+ 'understand-anything-plugin/skills/understand/compute-batches.mjs',
+);
+const STRUCTURE_SCRIPT = resolve(
+ REPO_ROOT,
+ 'understand-anything-plugin/skills/understand/extract-structure.mjs',
+);
+
+export const STAGE_METRICS_PREFIX = '__UA_BENCHMARK_METRICS__';
+const DEFAULT_CONCURRENCY = 5;
+export const GIT_METADATA_MAX_BUFFER = 64 * 1024;
+// Child helpers can be noisy on large repositories. Retain at most 128 KiB
+// from each stream while continuing to drain and inspect all child output.
+export const STAGE_OUTPUT_MAX_BYTES = 128 * 1024;
+export const WARNING_SAMPLE_LIMIT = 5;
+const ENTITY_FIELDS = [
+ 'functions',
+ 'classes',
+ 'exports',
+ 'callGraph',
+ 'definitions',
+ 'services',
+ 'endpoints',
+ 'steps',
+ 'resources',
+];
+
+export class CliUsageError extends Error {
+ constructor(message) {
+ super(message);
+ this.name = 'CliUsageError';
+ }
+}
+
+export class BenchmarkStageError extends Error {
+ constructor(stage) {
+ super(`Benchmark stage failed: ${stage.name}`);
+ this.name = 'BenchmarkStageError';
+ this.stage = stage;
+ }
+}
+
+export class BenchmarkReportWriteError extends Error {
+ constructor(artifactRoot = null) {
+ super('Unable to write benchmark report files');
+ this.name = 'BenchmarkReportWriteError';
+ this.artifactRoot = artifactRoot;
+ }
+}
+
+export class BenchmarkArtifactCleanupError extends Error {
+ constructor() {
+ super('Unable to remove temporary benchmark artifacts');
+ this.name = 'BenchmarkArtifactCleanupError';
+ }
+}
+
+export function cleanupBenchmarkArtifacts(artifactRoot, operations = {}) {
+ const remove = operations.rmSync ?? rmSync;
+ try {
+ remove(artifactRoot, { recursive: true, force: true });
+ } catch {
+ throw new BenchmarkArtifactCleanupError();
+ }
+}
+
+function takeValue(argv, index, flag) {
+ const value = argv[index + 1];
+ if (!value || value.startsWith('--')) {
+ throw new CliUsageError(`${flag} requires a value`);
+ }
+ return value;
+}
+
+function parseConcurrency(value) {
+ return /^[0-9]+$/.test(value) ? Number(value) : Number.NaN;
+}
+
+function canonicalizePhysicalPath(pathValue) {
+ const lexicalPath = resolve(withoutExtendedWindowsPrefix(pathValue));
+ const missingComponents = [];
+ let existingAncestor = lexicalPath;
+ let ancestorExists = existsSync(existingAncestor);
+
+ while (!ancestorExists) {
+ const parent = dirname(existingAncestor);
+ if (parent === existingAncestor) break;
+ missingComponents.unshift(basename(existingAncestor));
+ existingAncestor = parent;
+ ancestorExists = existsSync(existingAncestor);
+ }
+
+ let physicalAncestor = existingAncestor;
+ if (ancestorExists) {
+ try {
+ const nativeRealpath = realpathSync.native ?? realpathSync;
+ physicalAncestor = nativeRealpath(existingAncestor);
+ } catch {
+ // Fall back to the resolved lexical ancestor if metadata becomes unavailable.
+ }
+ }
+ return resolve(
+ withoutExtendedWindowsPrefix(physicalAncestor),
+ ...missingComponents,
+ );
+}
+
+export function isPathInsideOrEqual(rootPath, candidatePath) {
+ const relationship = relative(
+ canonicalizePhysicalPath(rootPath),
+ canonicalizePhysicalPath(candidatePath),
+ );
+ return (
+ relationship === '' ||
+ (relationship !== '..' &&
+ !relationship.startsWith(`..${sep}`) &&
+ !isAbsolute(relationship))
+ );
+}
+
+export function parseArgs(argv, cwd = process.cwd()) {
+ let repoValue = null;
+ let outputValue = null;
+ let label = null;
+ let concurrency = DEFAULT_CONCURRENCY;
+ let keepArtifacts = false;
+ let help = false;
+
+ for (let i = 0; i < argv.length; i += 1) {
+ const arg = argv[i];
+ if (arg === '--help' || arg === '-h') {
+ help = true;
+ continue;
+ }
+ if (arg === '--keep-artifacts') {
+ keepArtifacts = true;
+ continue;
+ }
+ if (arg === '--repo') {
+ repoValue = takeValue(argv, i, '--repo');
+ i += 1;
+ continue;
+ }
+ if (arg.startsWith('--repo=')) {
+ repoValue = arg.slice('--repo='.length);
+ continue;
+ }
+ if (arg === '--output' || arg === '-o') {
+ outputValue = takeValue(argv, i, arg);
+ i += 1;
+ continue;
+ }
+ if (arg.startsWith('--output=')) {
+ outputValue = arg.slice('--output='.length);
+ continue;
+ }
+ if (arg === '--label') {
+ label = takeValue(argv, i, '--label');
+ i += 1;
+ continue;
+ }
+ if (arg.startsWith('--label=')) {
+ label = arg.slice('--label='.length);
+ continue;
+ }
+ if (arg === '--concurrency') {
+ const raw = takeValue(argv, i, '--concurrency');
+ concurrency = parseConcurrency(raw);
+ i += 1;
+ continue;
+ }
+ if (arg.startsWith('--concurrency=')) {
+ concurrency = parseConcurrency(arg.slice('--concurrency='.length));
+ continue;
+ }
+ if (arg.startsWith('-')) {
+ throw new CliUsageError(`Unknown option: ${arg}`);
+ }
+ if (repoValue) {
+ throw new CliUsageError(`Unexpected positional argument: ${arg}`);
+ }
+ repoValue = arg;
+ }
+
+ if (help) return { help: true };
+ if (!repoValue) throw new CliUsageError('A repository path is required');
+ if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 32) {
+ throw new CliUsageError('--concurrency must be an integer between 1 and 32');
+ }
+
+ const repoRoot = resolve(cwd, repoValue);
+ if (!existsSync(repoRoot)) {
+ throw new CliUsageError(`Repository path does not exist: ${repoValue}`);
+ }
+ if (!statSync(repoRoot).isDirectory()) {
+ throw new CliUsageError(`Repository path is not a directory: ${repoValue}`);
+ }
+
+ const outputPath = resolve(
+ cwd,
+ outputValue ?? join('benchmark-results', 'large-repo-report.json'),
+ );
+ const markdownPath = resolve(
+ cwd,
+ outputPath.toLowerCase().endsWith('.json')
+ ? `${outputPath.slice(0, -'.json'.length)}.md`
+ : `${outputPath}.md`,
+ );
+ if (isPathInsideOrEqual(repoRoot, outputPath)) {
+ throw new CliUsageError('--output must be outside the subject repository');
+ }
+ if (isPathInsideOrEqual(repoRoot, markdownPath)) {
+ throw new CliUsageError('Markdown report path must be outside the subject repository');
+ }
+
+ return {
+ help: false,
+ repoRoot,
+ outputPath,
+ markdownPath,
+ label: label || basename(repoRoot),
+ concurrency,
+ keepArtifacts,
+ };
+}
+
+export function helpText() {
+ return `Usage:
+ node scripts/benchmark-large-repo.mjs <repo-path> [options]
+ node scripts/benchmark-large-repo.mjs --repo <repo-path> [options]
+
+Options:
+ -o, --output <path> JSON report path
+ --label <name> Public label for the subject repository
+ --concurrency <1-32> Structural extraction workers (default: 5)
+ --keep-artifacts Preserve temporary deterministic outputs
+ -h, --help Show this help
+
+This v1 runner measures deterministic helpers only. It does not invoke an LLM
+and keeps all intermediate artifacts outside the subject repository.
+`;
+}
+
+function gitProbe(directory, args) {
+ return spawnSync(
+ 'git',
+ ['-c', 'core.optionalLocks=false', '-C', directory, ...args],
+ {
+ encoding: 'utf-8',
+ env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' },
+ maxBuffer: GIT_METADATA_MAX_BUFFER,
+ windowsHide: true,
+ },
+ );
+}
+
+export function gitMetadata(directory) {
+ const commit = gitProbe(directory, ['rev-parse', 'HEAD']);
+ if (commit.status !== 0) return { commit: null, dirty: null };
+
+ const status = gitProbe(directory, ['status', '--porcelain']);
+ return {
+ commit: commit.stdout.trim() || null,
+ dirty:
+ status.error?.code === 'ENOBUFS'
+ ? true
+ : status.status === 0
+ ? status.stdout.trim().length > 0
+ : null,
+ };
+}
+
+function environmentMetadata() {
+ const processors = cpus();
+ return {
+ platform: platform(),
+ release: release(),
+ arch: arch(),
+ nodeVersion: process.version,
+ cpuModel: processors[0]?.model ?? 'unknown',
+ logicalCores: processors.length,
+ totalMemoryBytes: totalmem(),
+ };
+}
+
+function packageVersion() {
+ const packageJson = JSON.parse(
+ readFileSync(resolve(REPO_ROOT, 'understand-anything-plugin/package.json'), 'utf-8'),
+ );
+ return packageJson.version;
+}
+
+function withoutExtendedWindowsPrefix(pathValue) {
+ const extendedUncPrefix = pathValue.match(/^[\\/]{2}\?[\\/]unc[\\/]/i)?.[0];
+ if (extendedUncPrefix) {
+ return `\\\\${pathValue
+ .slice(extendedUncPrefix.length)
+ .replaceAll('/', '\\')}`;
+ }
+ const extendedPrefix = pathValue.match(/^[\\/]{2}\?[\\/]/)?.[0];
+ if (extendedPrefix) {
+ return pathValue.slice(extendedPrefix.length);
+ }
+ return pathValue;
+}
+
+function extendedWindowsPath(pathValue) {
+ const windowsPath = pathValue.replaceAll('/', '\\');
+ if (windowsPath.startsWith('\\\\?\\')) return windowsPath;
+ if (/^[A-Za-z]:\\/.test(windowsPath)) return `\\\\?\\${windowsPath}`;
+ if (windowsPath.startsWith('\\\\')) {
+ return `\\\\?\\UNC\\${windowsPath.slice(2)}`;
+ }
+ return null;
+}
+
+function addRootAliases(aliases, root, replacement) {
+ if (!root) return;
+ const resolvedRoot = resolve(root);
+ const resolvedAliases = new Set([resolvedRoot]);
+ try {
+ const nativeRealpath = realpathSync.native ?? realpathSync;
+ resolvedAliases.add(nativeRealpath(resolvedRoot));
+ } catch {
+ // Missing or inaccessible roots still retain their lexical aliases.
+ }
+
+ for (const resolvedAlias of resolvedAliases) {
+ const plainAlias = withoutExtendedWindowsPrefix(resolvedAlias);
+ const pathAliases = new Set([resolvedAlias, plainAlias]);
+ for (const pathAlias of pathAliases) {
+ aliases.push([pathAlias, replacement]);
+ aliases.push([pathAlias.replaceAll('\\', '/'), replacement]);
+ aliases.push([pathAlias.replaceAll('/', '\\'), replacement]);
+ const extendedAlias = extendedWindowsPath(pathAlias);
+ if (extendedAlias) aliases.push([extendedAlias, replacement]);
+ try {
+ aliases.push([pathToFileURL(pathAlias).href, replacement]);
+ } catch {
+ // Non-file path aliases are already represented in native forms.
+ }
+ }
+ }
+}
+
+function hasPathBoundary(text, index) {
+ if (index >= text.length) return true;
+ return text[index] === '/' || text[index] === '\\';
+}
+
+function replacePathAlias(text, alias, replacement, caseInsensitive) {
+ const haystack = caseInsensitive ? text.toLowerCase() : text;
+ const needle = caseInsensitive ? alias.toLowerCase() : alias;
+ let emittedUntil = 0;
+ let searchFrom = 0;
+ let result = '';
+
+ while (searchFrom < haystack.length) {
+ const index = haystack.indexOf(needle, searchFrom);
+ if (index === -1) break;
+ const end = index + needle.length;
+ if (hasPathBoundary(text, end)) {
+ result += text.slice(emittedUntil, index) + replacement;
+ emittedUntil = end;
+ searchFrom = end;
+ } else {
+ searchFrom = index + 1;
+ }
+ }
+ return result + text.slice(emittedUntil);
+}
+
+export function redactPaths(text, roots) {
+ const aliases = [];
+ for (const [root, replacement] of roots) {
+ addRootAliases(aliases, root, replacement);
+ }
+ const caseInsensitive = process.platform === 'win32';
+ const uniqueAliases = new Map();
+ for (const [alias, replacement] of aliases) {
+ const key = caseInsensitive ? alias.toLowerCase() : alias;
+ if (alias && !uniqueAliases.has(key)) {
+ uniqueAliases.set(key, [alias, replacement]);
+ }
+ }
+
+ let redacted = text;
+ for (const [alias, replacement] of [...uniqueAliases.values()].sort(
+ ([left], [right]) => right.length - left.length,
+ )) {
+ redacted = replacePathAlias(
+ redacted,
+ alias,
+ replacement,
+ caseInsensitive,
+ );
+ }
+ return redacted;
+}
+
+function createBoundedByteCollector(maxBytes = STAGE_OUTPUT_MAX_BYTES) {
+ const buffer = Buffer.allocUnsafe(maxBytes);
+ let length = 0;
+ let truncated = false;
+
+ return {
+ append(value) {
+ const source = Buffer.isBuffer(value) ? value : Buffer.from(value);
+ const copyLength = Math.min(source.length, maxBytes - length);
+ if (copyLength > 0) {
+ source.copy(buffer, length, 0, copyLength);
+ length += copyLength;
+ }
+ if (copyLength < source.length) truncated = true;
+ },
+ text() {
+ return buffer.subarray(0, length).toString('utf-8');
+ },
+ get truncated() {
+ return truncated;
+ },
+ };
+}
+
+function boundUtf8(text, maxBytes = STAGE_OUTPUT_MAX_BYTES) {
+ const bytes = Buffer.from(text);
+ if (bytes.length <= maxBytes) return { text, truncated: false };
+ const decoder = new StringDecoder('utf8');
+ return {
+ text: decoder.write(bytes.subarray(0, maxBytes)),
+ truncated: true,
+ };
+}
+
+function sanitizeBounded(text, redactionRoots) {
+ return boundUtf8(redactPaths(text, redactionRoots));
+}
+
+function createStderrInspector() {
+ const decoder = new StringDecoder('utf8');
+ const retained = createBoundedByteCollector();
+ const rawWarningMessages = [];
+ let warningCount = 0;
+ let warningMessageTruncated = false;
+ let metrics = null;
+ let lineKind = 'probing';
+ let lineProbe = '';
+ let lineCollector = null;
+
+ function classifyProbe() {
+ if (lineProbe === STAGE_METRICS_PREFIX) {
+ lineKind = 'metrics';
+ lineCollector = createBoundedByteCollector();
+ return;
+ }
+ if (lineProbe === 'Warning:') {
+ lineKind = 'warning';
+ retained.append(lineProbe);
+ if (rawWarningMessages.length < WARNING_SAMPLE_LIMIT) {
+ lineCollector = createBoundedByteCollector();
+ lineCollector.append(lineProbe);
+ }
+ return;
+ }
+ if (
+ STAGE_METRICS_PREFIX.startsWith(lineProbe) ||
+ 'Warning:'.startsWith(lineProbe)
+ ) {
+ return;
+ }
+ lineKind = 'ordinary';
+ retained.append(lineProbe);
+ }
+
+ function processFragment(fragment) {
+ let offset = 0;
+ while (lineKind === 'probing' && offset < fragment.length) {
+ lineProbe += fragment[offset];
+ offset += 1;
+ classifyProbe();
+ }
+ if (offset >= fragment.length) return;
+ const remainder = fragment.slice(offset);
+ if (lineKind === 'metrics') {
+ lineCollector.append(remainder);
+ } else {
+ retained.append(remainder);
+ if (lineKind === 'warning' && lineCollector) {
+ lineCollector.append(remainder);
+ }
+ }
+ }
+
+ function finishLine(retainNewline) {
+ if (lineKind === 'probing') retained.append(lineProbe);
+ if (lineKind === 'metrics') {
+ try {
+ metrics = JSON.parse(lineCollector.text().replace(/\r$/, ''));
+ } catch {
+ // A malformed or oversized marker means telemetry is unavailable;
+ // child exit status and parent wall clock remain authoritative.
+ }
+ } else {
+ if (lineKind === 'warning') {
+ warningCount += 1;
+ if (lineCollector) {
+ rawWarningMessages.push(lineCollector.text().replace(/\r$/, ''));
+ warningMessageTruncated ||= lineCollector.truncated;
+ }
+ }
+ if (retainNewline) retained.append('\n');
+ }
+ lineKind = 'probing';
+ lineProbe = '';
+ lineCollector = null;
+ }
+
+ function processText(text) {
+ let offset = 0;
+ while (offset < text.length) {
+ const newline = text.indexOf('\n', offset);
+ if (newline === -1) {
+ processFragment(text.slice(offset));
+ return;
+ }
+ processFragment(text.slice(offset, newline));
+ finishLine(true);
+ offset = newline + 1;
+ }
+ }
+
+ return {
+ write(chunk) {
+ processText(decoder.write(chunk));
+ },
+ finish(redactionRoots) {
+ processText(decoder.end());
+ if (lineKind !== 'probing' || lineProbe.length > 0) finishLine(false);
+ const retainedStderr = retained.text().replace(/[\r\n]+$/, '');
+ const safeStderr = sanitizeBounded(retainedStderr, redactionRoots);
+ const warningMessages = rawWarningMessages.map((message) =>
+ sanitizeBounded(message, redactionRoots),
+ );
+ return {
+ metrics,
+ stderr: safeStderr.text,
+ stderrTruncated: retained.truncated || safeStderr.truncated,
+ warningCount,
+ warningMessages: warningMessages.map((message) => message.text),
+ warningMessagesTruncated:
+ warningCount > warningMessages.length ||
+ warningMessageTruncated ||
+ warningMessages.some((message) => message.truncated),
+ };
+ },
+ };
+}
+
+export function runNodeStage(name, scriptPath, args, redactionRoots = []) {
+ const startedAt = performance.now();
+ return new Promise((resolveStage) => {
+ const child = spawn(
+ process.execPath,
+ [WORKER, scriptPath, ...args],
+ { cwd: REPO_ROOT, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] },
+ );
+ const stdoutCollector = createBoundedByteCollector();
+ const stderrInspector = createStderrInspector();
+ let settled = false;
+
+ child.stdout.on('data', (chunk) => stdoutCollector.append(chunk));
+ child.stderr.on('data', (chunk) => stderrInspector.write(chunk));
+ child.on('error', (error) => {
+ if (settled) return;
+ settled = true;
+ const durationMs = Math.round((performance.now() - startedAt) * 100) / 100;
+ const safeError = sanitizeBounded(error.message, redactionRoots);
+ resolveStage({
+ name,
+ status: 'failed',
+ exitCode: null,
+ durationMs,
+ peakRssBytes: null,
+ userCpuTimeMicros: null,
+ systemCpuTimeMicros: null,
+ warningCount: 0,
+ warningMessages: [],
+ warningMessagesTruncated: false,
+ stdout: '',
+ stderr: safeError.text,
+ stdoutTruncated: false,
+ stderrTruncated: safeError.truncated,
+ });
+ });
+ child.on('close', (code) => {
+ if (settled) return;
+ settled = true;
+ const durationMs = Math.round((performance.now() - startedAt) * 100) / 100;
+ const safeStdout = sanitizeBounded(stdoutCollector.text(), redactionRoots);
+ const inspectedStderr = stderrInspector.finish(redactionRoots);
+ const { metrics } = inspectedStderr;
+ resolveStage({
+ name,
+ status: code === 0 ? 'ok' : 'failed',
+ exitCode: code,
+ durationMs,
+ peakRssBytes: metrics?.peakRssBytes ?? null,
+ userCpuTimeMicros: metrics?.userCpuTimeMicros ?? null,
+ systemCpuTimeMicros: metrics?.systemCpuTimeMicros ?? null,
+ warningCount: inspectedStderr.warningCount,
+ warningMessages: inspectedStderr.warningMessages,
+ warningMessagesTruncated: inspectedStderr.warningMessagesTruncated,
+ stdout: safeStdout.text,
+ stderr: inspectedStderr.stderr,
+ stdoutTruncated: stdoutCollector.truncated || safeStdout.truncated,
+ stderrTruncated: inspectedStderr.stderrTruncated,
+ });
+ });
+ });
+}
+
+function readJson(path) {
+ return JSON.parse(readFileSync(path, 'utf-8'));
+}
+
+function fileSizeOrZero(path) {
+ try {
+ return statSync(path).size;
+ } catch {
+ return 0;
+ }
+}
+
+function writeJson(path, value) {
+ mkdirSync(dirname(path), { recursive: true });
+ writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+}
+
+function preflightReportTargets(paths, fileSystem) {
+ for (const path of paths) {
+ if (fileSystem.existsSync(path) && fileSystem.statSync(path).isDirectory()) {
+ throw new Error('A benchmark report target is a directory');
+ }
+ }
+}
+
+function bestEffortRemove(path, fileSystem) {
+ try {
+ fileSystem.rmSync(path, { force: true });
+ } catch {
+ // Transaction cleanup must never mask the primary delivery failure.
+ }
+}
+
+function rollbackReportEntry(entry, fileSystem) {
+ if (entry.backupMoved) {
+ bestEffortRemove(entry.targetPath, fileSystem);
+ try {
+ fileSystem.renameSync(entry.backupPath, entry.targetPath);
+ } catch {
+ // Leave an unrestored backup in place rather than delete original data.
+ }
+ } else if (!entry.hadOriginal && entry.installAttempted) {
+ bestEffortRemove(entry.targetPath, fileSystem);
+ }
+}
+
+function stageReportEntry(entry, fileSystem) {
+ let descriptor;
+ let stageError = null;
+ try {
+ descriptor = fileSystem.openSync(entry.tempPath, 'wx');
+ entry.tempCreated = true;
+ fileSystem.writeFileSync(descriptor, entry.contents, {
+ encoding: 'utf-8',
+ });
+ } catch (error) {
+ stageError = error;
+ } finally {
+ if (descriptor !== undefined) {
+ try {
+ fileSystem.closeSync(descriptor);
+ } catch (error) {
+ stageError ??= error;
+ }
+ }
+ }
+ if (stageError) throw stageError;
+}
+
+export function deliverBenchmarkReports(reportFiles, operations = {}) {
+ const fileSystem = {
+ closeSync: operations.closeSync ?? closeSync,
+ existsSync: operations.existsSync ?? existsSync,
+ mkdirSync: operations.mkdirSync ?? mkdirSync,
+ openSync: operations.openSync ?? openSync,
+ renameSync: operations.renameSync ?? renameSync,
+ rmSync: operations.rmSync ?? rmSync,
+ statSync: operations.statSync ?? statSync,
+ writeFileSync: operations.writeFileSync ?? writeFileSync,
+ };
+ const transactionId = randomUUID();
+ const entries = [
+ [reportFiles.outputPath, reportFiles.jsonContents],
+ [reportFiles.markdownPath, reportFiles.markdownContents],
+ ].map(([targetPath, contents]) => ({
+ targetPath,
+ contents,
+ tempPath: join(
+ dirname(targetPath),
+ `.${basename(targetPath)}.ua-report-${transactionId}.tmp`,
+ ),
+ backupPath: join(
+ dirname(targetPath),
+ `.${basename(targetPath)}.ua-report-${transactionId}.backup`,
+ ),
+ hadOriginal: false,
+ tempCreated: false,
+ backupMoved: false,
+ installAttempted: false,
+ }));
+
+ try {
+ for (const entry of entries) {
+ fileSystem.mkdirSync(dirname(entry.targetPath), { recursive: true });
+ }
+ preflightReportTargets(
+ entries.map((entry) => entry.targetPath),
+ fileSystem,
+ );
+ for (const entry of entries) {
+ if (
+ fileSystem.existsSync(entry.tempPath) ||
+ fileSystem.existsSync(entry.backupPath)
+ ) {
+ throw new Error('A report transaction path already exists');
+ }
+ entry.hadOriginal = fileSystem.existsSync(entry.targetPath);
+ stageReportEntry(entry, fileSystem);
+ }
+ for (const entry of entries) {
+ if (entry.hadOriginal) {
+ fileSystem.renameSync(entry.targetPath, entry.backupPath);
+ entry.backupMoved = true;
+ }
+ }
+ for (const entry of entries) {
+ entry.installAttempted = true;
+ fileSystem.renameSync(entry.tempPath, entry.targetPath);
+ }
+ for (const entry of entries) {
+ if (entry.backupMoved) {
+ bestEffortRemove(entry.backupPath, fileSystem);
+ }
+ }
+ } catch {
+ for (const entry of [...entries].reverse()) {
+ rollbackReportEntry(entry, fileSystem);
+ }
+ throw new BenchmarkReportWriteError();
+ } finally {
+ for (const entry of entries) {
+ if (entry.tempCreated) {
+ bestEffortRemove(entry.tempPath, fileSystem);
+ }
+ }
+ }
+}
+
+function markdownValue(value) {
+ if (value === null || value === undefined) return 'n/a';
+ return String(value).replaceAll('|', '\\|').replaceAll(/\r?\n/g, ' ');
+}
+
+function metricRow(label, value) {
+ return `| ${label} | ${markdownValue(value)} |`;
+}
+
+function duration(value) {
+ return value === null || value === undefined ? 'n/a' : `${value} ms`;
+}
+
+function bytes(value) {
+ return value === null || value === undefined
+ ? 'n/a'
+ : new Intl.NumberFormat('en-US').format(value);
+}
+
+export function renderMarkdownReport(report) {
+ const scale = report.scale ?? {};
+ const integrity = report.integrity ?? {};
+ const stageRows = Object.entries(report.stages)
+ .map(([name, stage]) =>
+ `| ${markdownValue(name)} | ${markdownValue(stage.status)} | ${duration(
+ stage.durationMs,
+ )} | ${bytes(
+ stage.maxWorkerPeakRssBytes ?? stage.peakRssBytes,
+ )} | ${bytes(stage.userCpuTimeMicros)} | ${bytes(
+ stage.systemCpuTimeMicros,
+ )} | ${bytes(stage.outputBytes)} |`,
+ )
+ .join('\n');
+
+ const lines = [
+ '# Large Repository Benchmark Report',
+ '',
+ 'This report covers deterministic static-analysis stages only. It does not include LLM inference or dashboard generation.',
+ '',
+ '## Run',
+ '',
+ '| Metric | Value |',
+ '| --- | --- |',
+ metricRow('Status', report.status),
+ metricRow('Subject', report.subject.label),
+ metricRow('Subject commit', report.subject.commit),
+ metricRow('Tool commit', report.tool.commit),
+ metricRow('Tool version', report.tool.packageVersion),
+ metricRow('Started (UTC)', report.run.startedAt),
+ metricRow('Total duration', duration(report.run.durationMs)),
+ metricRow('Concurrency', report.configuration.concurrency),
+ metricRow('LLM invoked', report.llm.invoked ? 'Yes' : 'No'),
+ '',
+ '## Scale',
+ '',
+ '| Metric | Value |',
+ '| --- | --- |',
+ metricRow('Files', scale.files),
+ metricRow('Lines', scale.lines),
+ metricRow('Source bytes', scale.bytes),
+ metricRow('Filtered by user ignore', scale.filteredByUserIgnore),
+ metricRow('Missing during measurement', scale.missingFiles),
+ '',
+ '## Stages',
+ '',
+ '| Stage | Status | Duration | Peak / max worker RSS (bytes) | User CPU (micros) | System CPU (micros) | Output (bytes) |',
+ '| --- | --- | ---: | ---: | ---: | ---: | ---: |',
+ stageRows || '| n/a | n/a | n/a | n/a | n/a | n/a | n/a |',
+ '',
+ '## Integrity and reproducibility',
+ '',
+ '| Metric | Value |',
+ '| --- | --- |',
+ metricRow('All scanned files batched', integrity.allScannedFilesBatched),
+ metricRow('Structure coverage', integrity.structureCoverage),
+ metricRow('Files skipped', integrity.filesSkipped),
+ metricRow('Failed batches', integrity.failedBatches),
+ metricRow('Missing structure paths', integrity.missingStructurePaths),
+ metricRow('Duplicate structure paths', integrity.duplicateStructurePaths),
+ metricRow('Unexpected structure paths', integrity.unexpectedStructurePaths),
+ metricRow('Malformed structure batches', integrity.malformedStructureBatches),
+ metricRow('Input digest (SHA-256)', report.determinism?.inputDigest),
+ metricRow('Output digest (SHA-256)', report.determinism?.outputDigest),
+ metricRow('Schema version', report.schemaVersion),
+ '',
+ '## Environment',
+ '',
+ '| Metric | Value |',
+ '| --- | --- |',
+ metricRow('Platform', report.environment.platform),
+ metricRow('OS release', report.environment.release),
+ metricRow('Architecture', report.environment.arch),
+ metricRow('Node.js', report.environment.nodeVersion),
+ metricRow('CPU', report.environment.cpuModel),
+ metricRow('Logical cores', report.environment.logicalCores),
+ metricRow('Memory (bytes)', report.environment.totalMemoryBytes),
+ ];
+
+ if (report.warnings.length > 0) {
+ lines.push('', '## Warnings', '');
+ for (const warning of report.warnings) {
+ lines.push(`- ${markdownValue(warning.stage)}: ${warning.count}`);
+ }
+ }
+ if (report.error) {
+ lines.push('', '## Error', '', markdownValue(report.error));
+ }
+ lines.push('');
+ return lines.join('\n');
+}
+
+function updateCanonicalHash(hash, value) {
+ if (Array.isArray(value)) {
+ hash.update('[');
+ for (let index = 0; index < value.length; index += 1) {
+ if (index > 0) hash.update(',');
+ updateCanonicalHash(hash, value[index]);
+ }
+ hash.update(']');
+ return;
+ }
+ if (value && typeof value === 'object') {
+ hash.update('{');
+ const keys = Object.keys(value).sort();
+ for (let index = 0; index < keys.length; index += 1) {
+ if (index > 0) hash.update(',');
+ const key = keys[index];
+ hash.update(JSON.stringify(key));
+ hash.update(':');
+ updateCanonicalHash(hash, value[key]);
+ }
+ hash.update('}');
+ return;
+ }
+ const encoded = JSON.stringify(value);
+ if (encoded === undefined) {
+ throw new TypeError(`Unsupported canonical JSON value: ${typeof value}`);
+ }
+ hash.update(encoded);
+}
+
+export function canonicalSha256(value) {
+ const hash = createHash('sha256');
+ updateCanonicalHash(hash, value);
+ return hash.digest('hex');
+}
+
+export function buildOutputDigest(importMap, batches, structureSummaries) {
+ const digestByBatchIndex = new Map(
+ structureSummaries.map((summary) => [summary.batchIndex, summary.digest]),
+ );
+ const structureBatchDigests = batches.batches.map((batch) => ({
+ batchIndex: batch.batchIndex,
+ digest: digestByBatchIndex.get(batch.batchIndex) ?? null,
+ }));
+ return canonicalSha256({
+ importMapDigest: canonicalSha256(importMap),
+ batchesDigest: canonicalSha256(batches),
+ structureBatchDigests,
+ });
+}
+
+function percentile(values, percentileValue) {
+ if (values.length === 0) return 0;
+ const sorted = [...values].sort((left, right) => left - right);
+ const index = Math.max(
+ 0,
+ Math.min(sorted.length - 1, Math.ceil((percentileValue / 100) * sorted.length) - 1),
+ );
+ return sorted[index];
+}
+
+function distribution(values) {
+ if (values.length === 0) {
+ return { min: 0, p50: 0, p95: 0, max: 0, mean: 0 };
+ }
+ const total = values.reduce((sum, value) => sum + value, 0);
+ return {
+ min: Math.min(...values),
+ p50: percentile(values, 50),
+ p95: percentile(values, 95),
+ max: Math.max(...values),
+ mean: Math.round((total / values.length) * 100) / 100,
+ };
+}
+
+async function mapWithConcurrency(items, concurrency, worker) {
+ const results = new Array(items.length);
+ let nextIndex = 0;
+
+ async function consume() {
+ while (nextIndex < items.length) {
+ const index = nextIndex;
+ nextIndex += 1;
+ results[index] = await worker(items[index], index);
+ }
+ }
+
+ const workers = Array.from(
+ { length: Math.min(concurrency, Math.max(1, items.length)) },
+ () => consume(),
+ );
+ await Promise.all(workers);
+ return results;
+}
+
+function emptyEntityCounts() {
+ return Object.fromEntries(ENTITY_FIELDS.map((field) => [field, 0]));
+}
+
+export function aggregateStructureSummaries(structureSummaries) {
+ const aggregate = {
+ filesAnalyzed: 0,
+ filesSkipped: 0,
+ entities: emptyEntityCounts(),
+ };
+ for (const summary of structureSummaries) {
+ aggregate.filesAnalyzed += summary.filesAnalyzed;
+ aggregate.filesSkipped += summary.filesSkipped;
+ for (const field of ENTITY_FIELDS) {
+ aggregate.entities[field] += summary.entities[field];
+ }
+ }
+ return aggregate;
+}
+
+export function summarizeStructureOutput(batch, output) {
+ const expectedPaths = new Set(batch.files.map((file) => file.path));
+ const results = Array.isArray(output?.results) ? output.results : [];
+ const skippedPaths = Array.isArray(output?.filesSkipped)
+ ? output.filesSkipped
+ : [];
+ let malformed =
+ !output ||
+ typeof output !== 'object' ||
+ Array.isArray(output) ||
+ output.scriptCompleted !== true ||
+ !Array.isArray(output.results) ||
+ !Array.isArray(output.filesSkipped) ||
+ !Number.isInteger(output.filesAnalyzed) ||
+ output.filesAnalyzed !== results.length;
+
+ const pathCounts = new Map();
+ const entities = emptyEntityCounts();
+ for (const result of results) {
+ if (!result || typeof result !== 'object' || Array.isArray(result)) {
+ malformed = true;
+ continue;
+ }
+ if (typeof result.path !== 'string' || result.path.length === 0) {
+ malformed = true;
+ } else {
+ pathCounts.set(result.path, (pathCounts.get(result.path) ?? 0) + 1);
+ }
+ for (const field of ENTITY_FIELDS) {
+ entities[field] += Array.isArray(result[field]) ? result[field].length : 0;
+ }
+ }
+ for (const path of skippedPaths) {
+ if (typeof path !== 'string' || path.length === 0) {
+ malformed = true;
+ continue;
+ }
+ pathCounts.set(path, (pathCounts.get(path) ?? 0) + 1);
+ }
+
+ const accountedExpectedPaths = [...expectedPaths].filter((path) =>
+ pathCounts.has(path),
+ ).length;
+ const missingStructurePaths = expectedPaths.size - accountedExpectedPaths;
+ const duplicateStructurePaths = [...pathCounts.values()].filter(
+ (count) => count > 1,
+ ).length;
+ const unexpectedStructurePaths = [...pathCounts.keys()].filter(
+ (path) => !expectedPaths.has(path),
+ ).length;
+
+ return {
+ batchIndex: batch.batchIndex,
+ digest: canonicalSha256(output),
+ complete:
+ !malformed &&
+ missingStructurePaths === 0 &&
+ duplicateStructurePaths === 0 &&
+ unexpectedStructurePaths === 0,
+ malformed,
+ expectedFiles: expectedPaths.size,
+ accountedExpectedPaths,
+ filesAnalyzed: results.length,
+ filesSkipped: skippedPaths.length,
+ missingStructurePaths,
+ duplicateStructurePaths,
+ unexpectedStructurePaths,
+ entities,
+ };
+}
+
+export function aggregateStructureResources(stages) {
+ if (stages.length === 0) {
+ return {
+ maxWorkerPeakRssBytes: null,
+ userCpuTimeMicros: null,
+ systemCpuTimeMicros: null,
+ };
+ }
+ const values = (field) => stages.map((stage) => stage[field]);
+ const peakRssValues = values('peakRssBytes');
+ const userCpuValues = values('userCpuTimeMicros');
+ const systemCpuValues = values('systemCpuTimeMicros');
+ const allNumbers = (items) => items.every((value) => Number.isFinite(value));
+ const sum = (items) => items.reduce((total, value) => total + value, 0);
+ return {
+ maxWorkerPeakRssBytes: allNumbers(peakRssValues)
+ ? Math.max(...peakRssValues)
+ : null,
+ userCpuTimeMicros: allNumbers(userCpuValues) ? sum(userCpuValues) : null,
+ systemCpuTimeMicros: allNumbers(systemCpuValues)
+ ? sum(systemCpuValues)
+ : null,
+ };
+}
+
+function summarizeStage(stage, outputBytes, extra = {}) {
+ return {
+ status: stage.status,
+ durationMs: stage.durationMs,
+ peakRssBytes: stage.peakRssBytes,
+ userCpuTimeMicros: stage.userCpuTimeMicros,
+ systemCpuTimeMicros: stage.systemCpuTimeMicros,
+ warningCount: stage.warningCount,
+ warningMessages: stage.warningMessages,
+ warningMessagesTruncated: stage.warningMessagesTruncated,
+ stdoutTruncated: stage.stdoutTruncated,
+ stderrTruncated: stage.stderrTruncated,
+ outputBytes,
+ ...extra,
+ };
+}
+
+function subjectScale(repoRoot, scan) {
+ let bytes = 0;
+ let missingFiles = 0;
+ for (const file of scan.files) {
+ try {
+ bytes += statSync(resolve(repoRoot, file.path)).size;
+ } catch {
+ missingFiles += 1;
+ }
+ }
+ return {
+ files: scan.totalFiles,
+ lines: scan.files.reduce((sum, file) => sum + (file.sizeLines ?? 0), 0),
+ bytes,
+ missingFiles,
+ filteredByUserIgnore: scan.filteredByIgnore ?? 0,
+ byCategory: scan.stats?.byCategory ?? {},
+ byLanguage: scan.stats?.byLanguage ?? {},
+ };
+}
+
+export function buildBenchmarkIntegrity(
+ scan,
+ importMap,
+ batches,
+ structureSummaries,
+ failedBatches,
+) {
+ const scannedPaths = new Set(scan.files.map((file) => file.path));
+ const counts = new Map();
+ for (const batch of batches.batches) {
+ for (const file of batch.files) {
+ counts.set(file.path, (counts.get(file.path) ?? 0) + 1);
+ }
+ }
+ const missingBatchFiles = [...scannedPaths].filter((path) => !counts.has(path));
+ const duplicateBatchFiles = [...counts.values()].filter((count) => count > 1).length;
+ const unexpectedBatchFiles = [...counts.keys()].filter((path) => !scannedPaths.has(path));
+ let missingImportTargets = 0;
+ for (const targets of Object.values(importMap)) {
+ for (const target of targets) {
+ if (!scannedPaths.has(target)) missingImportTargets += 1;
+ }
+ }
+
+ const accountedExpectedPaths = structureSummaries.reduce(
+ (sum, summary) => sum + summary.accountedExpectedPaths,
+ 0,
+ );
+ const filesSkipped = structureSummaries.reduce(
+ (sum, summary) => sum + summary.filesSkipped,
+ 0,
+ );
+ const missingStructurePaths = structureSummaries.reduce(
+ (sum, summary) => sum + summary.missingStructurePaths,
+ 0,
+ );
+ const duplicateStructurePaths = structureSummaries.reduce(
+ (sum, summary) => sum + summary.duplicateStructurePaths,
+ 0,
+ );
+ const unexpectedStructurePaths = structureSummaries.reduce(
+ (sum, summary) => sum + summary.unexpectedStructurePaths,
+ 0,
+ );
+ const malformedStructureBatches = structureSummaries.filter(
+ (summary) => summary.malformed,
+ ).length;
+ return {
+ allScannedFilesBatched:
+ missingBatchFiles.length === 0 &&
+ duplicateBatchFiles === 0 &&
+ unexpectedBatchFiles.length === 0,
+ missingBatchFiles: missingBatchFiles.length,
+ duplicateBatchFiles,
+ unexpectedBatchFiles: unexpectedBatchFiles.length,
+ missingImportTargets,
+ structureCoverage:
+ scan.totalFiles === 0
+ ? 1
+ : Math.round((accountedExpectedPaths / scan.totalFiles) * 10000) / 10000,
+ filesSkipped,
+ failedBatches,
+ missingStructurePaths,
+ duplicateStructurePaths,
+ unexpectedStructurePaths,
+ malformedStructureBatches,
+ };
+}
+
+export function hasFailedIntegrity(integrity) {
+ return (
+ !integrity.allScannedFilesBatched ||
+ integrity.missingImportTargets > 0 ||
+ integrity.structureCoverage !== 1 ||
+ integrity.failedBatches > 0 ||
+ integrity.missingStructurePaths > 0 ||
+ integrity.duplicateStructurePaths > 0 ||
+ integrity.unexpectedStructurePaths > 0 ||
+ integrity.malformedStructureBatches > 0
+ );
+}
+
+export function aggregateStageWarnings(stages) {
+ let warningCount = 0;
+ const warningMessages = [];
+ let warningMessagesTruncated = false;
+
+ for (const stage of stages) {
+ const stageCount = stage.warningCount ?? 0;
+ const stageMessages = stage.warningMessages ?? [];
+ warningCount += stageCount;
+ for (const message of stageMessages) {
+ if (warningMessages.length < WARNING_SAMPLE_LIMIT) {
+ warningMessages.push(message);
+ } else {
+ warningMessagesTruncated = true;
+ }
+ }
+ if (
+ stage.warningMessagesTruncated ||
+ stageCount > stageMessages.length
+ ) {
+ warningMessagesTruncated = true;
+ }
+ }
+
+ return {
+ warningCount,
+ warningMessages,
+ warningMessagesTruncated,
+ };
+}
+
+export function warningSummary(stageResults) {
+ return stageResults
+ .filter((stage) => stage.warningCount > 0)
+ .map((stage) => {
+ const warnings = aggregateStageWarnings([stage]);
+ return {
+ stage: stage.name,
+ count: warnings.warningCount,
+ messages: warnings.warningMessages,
+ truncated: warnings.warningMessagesTruncated,
+ };
+ });
+}
+
+export async function runBenchmark(options, hooks = {}) {
+ const startedAt = new Date();
+ const overallStart = performance.now();
+ const artifactRoot = mkdtempSync(join(tmpdir(), 'ua-large-bench-'));
+ const redactionRoots = [
+ [options.repoRoot, '<subject>'],
+ [REPO_ROOT, '<tool>'],
+ [artifactRoot, '<artifacts>'],
+ ];
+ const onProgress = hooks.onProgress ?? (() => {});
+ const toolGit = gitMetadata(REPO_ROOT);
+ const subjectGit = gitMetadata(options.repoRoot);
+ const stageResults = [];
+
+ const report = {
+ schemaUrl: REPORT_SCHEMA_URL,
+ schemaVersion: REPORT_SCHEMA_VERSION,
+ status: 'failed',
+ mode: 'deterministic',
+ run: {
+ startedAt: startedAt.toISOString(),
+ finishedAt: null,
+ durationMs: null,
+ },
+ tool: {
+ commit: toolGit.commit,
+ dirty: toolGit.dirty,
+ packageVersion: packageVersion(),
+ },
+ subject: {
+ label: options.label,
+ commit: subjectGit.commit,
+ dirty: subjectGit.dirty,
+ },
+ environment: environmentMetadata(),
+ configuration: {
+ concurrency: options.concurrency,
+ stages: ['scan', 'imports', 'batching', 'structure'],
+ },
+ scale: null,
+ stages: {},
+ integrity: null,
+ determinism: null,
+ llm: {
+ invoked: false,
+ inputTokens: null,
+ outputTokens: null,
+ costUsd: null,
+ },
+ warnings: [],
+ error: null,
+ };
+
+ let exitCode = 1;
+ try {
+ const scanPath = join(artifactRoot, 'scan-result.json');
+ onProgress('scan');
+ const scanStage = await runNodeStage(
+ 'scan',
+ SCAN_SCRIPT,
+ [options.repoRoot, scanPath, '--exclude-analysis-data'],
+ redactionRoots,
+ );
+ stageResults.push(scanStage);
+ report.stages.scan = summarizeStage(
+ scanStage,
+ fileSizeOrZero(scanPath),
+ );
+ if (scanStage.status === 'failed') throw new BenchmarkStageError(scanStage);
+ const scan = readJson(scanPath);
+ report.scale = subjectScale(options.repoRoot, scan);
+ report.stages.scan = summarizeStage(scanStage, fileSizeOrZero(scanPath), {
+ files: scan.totalFiles,
+ lines: report.scale.lines,
+ bytes: report.scale.bytes,
+ filteredByUserIgnore: scan.filteredByIgnore ?? 0,
+ });
+
+ const importInputPath = join(artifactRoot, 'import-input.json');
+ const importOutputPath = join(artifactRoot, 'import-map.json');
+ writeJson(importInputPath, {
+ projectRoot: options.repoRoot,
+ files: scan.files,
+ });
+ onProgress('imports');
+ const importStage = await runNodeStage(
+ 'imports',
+ IMPORT_SCRIPT,
+ [importInputPath, importOutputPath],
+ redactionRoots,
+ );
+ stageResults.push(importStage);
+ report.stages.imports = summarizeStage(
+ importStage,
+ fileSizeOrZero(importOutputPath),
+ );
+ if (importStage.status === 'failed') throw new BenchmarkStageError(importStage);
+ const imports = readJson(importOutputPath);
+ report.stages.imports = summarizeStage(
+ importStage,
+ fileSizeOrZero(importOutputPath),
+ {
+ filesScanned: imports.stats?.filesScanned ?? 0,
+ filesWithImports: imports.stats?.filesWithImports ?? 0,
+ edges: imports.stats?.totalEdges ?? 0,
+ },
+ );
+
+ const enrichedScanPath = join(artifactRoot, 'scan-result-with-imports.json');
+ const batchesPath = join(artifactRoot, 'batches.json');
+ const enrichedScan = { ...scan, importMap: imports.importMap };
+ writeJson(enrichedScanPath, enrichedScan);
+ onProgress('batching');
+ const batchStage = await runNodeStage(
+ 'batching',
+ BATCH_SCRIPT,
+ [
+ options.repoRoot,
+ `--scan-result=${enrichedScanPath}`,
+ `--output=${batchesPath}`,
+ ],
+ redactionRoots,
+ );
+ stageResults.push(batchStage);
+ report.stages.batching = summarizeStage(
+ batchStage,
+ fileSizeOrZero(batchesPath),
+ );
+ if (batchStage.status === 'failed') throw new BenchmarkStageError(batchStage);
+ const batches = readJson(batchesPath);
+ const batchSizes = batches.batches.map((batch) => batch.files.length);
+ const estimatedAgentInputBytes = batches.batches.reduce(
+ (sum, batch) =>
+ sum +
+ Buffer.byteLength(
+ JSON.stringify({
+ files: batch.files,
+ batchImportData: batch.batchImportData,
+ neighborMap: batch.neighborMap,
+ }),
+ ),
+ 0,
+ );
+ report.stages.batching = summarizeStage(
+ batchStage,
+ fileSizeOrZero(batchesPath),
+ {
+ algorithm: batches.algorithm,
+ totalBatches: batches.totalBatches,
+ batchSizes: distribution(batchSizes),
+ estimatedAgentInputBytes,
+ },
+ );
+
+ onProgress('structure');
+ const structureStart = performance.now();
+ let completedBatches = 0;
+ const structureRuns = await mapWithConcurrency(
+ batches.batches,
+ options.concurrency,
+ async (batch) => {
+ const inputPath = join(artifactRoot, `structure-input-${batch.batchIndex}.json`);
+ const outputPath = join(artifactRoot, `structure-output-${batch.batchIndex}.json`);
+ writeJson(inputPath, {
+ projectRoot: options.repoRoot,
+ batchFiles: batch.files,
+ batchImportData: batch.batchImportData,
+ });
+ const stage = await runNodeStage(
+ `structure:${batch.batchIndex}`,
+ STRUCTURE_SCRIPT,
+ [inputPath, outputPath],
+ redactionRoots,
+ );
+ completedBatches += 1;
+ hooks.onBatchProgress?.(completedBatches, batches.totalBatches);
+ let summary = null;
+ if (stage.status === 'ok') {
+ try {
+ const output = readJson(outputPath);
+ summary = summarizeStructureOutput(batch, output);
+ } catch (error) {
+ stage.status = 'failed';
+ stage.stderr = redactPaths(
+ error instanceof Error ? error.message : String(error),
+ redactionRoots,
+ );
+ }
+ }
+ return {
+ stage,
+ summary,
+ outputBytes: fileSizeOrZero(outputPath),
+ };
+ },
+ );
+
+ const structureSummaries = structureRuns
+ .filter((run) => run.summary)
+ .map((run) => run.summary);
+ const structureAggregate = aggregateStructureSummaries(structureSummaries);
+ const failedBatches = structureRuns.filter(
+ (run) => run.stage.status === 'failed',
+ ).length;
+ const structureDurationMs =
+ Math.round((performance.now() - structureStart) * 100) / 100;
+ const structureWarnings = aggregateStageWarnings(
+ structureRuns.map((run) => run.stage),
+ );
+ const structureResources = aggregateStructureResources(
+ structureRuns.map((run) => run.stage),
+ );
+ const structureSummaryStage = {
+ name: 'structure',
+ status: failedBatches === 0 ? 'ok' : 'failed',
+ durationMs: structureDurationMs,
+ peakRssBytes: structureResources.maxWorkerPeakRssBytes,
+ userCpuTimeMicros: structureResources.userCpuTimeMicros,
+ systemCpuTimeMicros: structureResources.systemCpuTimeMicros,
+ ...structureWarnings,
+ };
+ stageResults.push(structureSummaryStage);
+ report.stages.structure = {
+ status: structureSummaryStage.status,
+ durationMs: structureDurationMs,
+ maxWorkerPeakRssBytes: structureResources.maxWorkerPeakRssBytes,
+ userCpuTimeMicros: structureResources.userCpuTimeMicros,
+ systemCpuTimeMicros: structureResources.systemCpuTimeMicros,
+ ...structureWarnings,
+ outputBytes: structureRuns.reduce((sum, run) => sum + run.outputBytes, 0),
+ batchesSucceeded: structureRuns.length - failedBatches,
+ batchesFailed: failedBatches,
+ filesAnalyzed: structureAggregate.filesAnalyzed,
+ filesSkipped: structureAggregate.filesSkipped,
+ entities: structureAggregate.entities,
+ batchDurationMs: distribution(
+ structureRuns.map((run) => run.stage.durationMs),
+ ),
+ };
+
+ report.integrity = buildBenchmarkIntegrity(
+ scan,
+ imports.importMap,
+ batches,
+ structureSummaries,
+ failedBatches,
+ );
+ report.determinism = {
+ algorithm: 'sha256',
+ inputDigest: scan.contentDigest,
+ outputDigest: buildOutputDigest(
+ imports.importMap,
+ batches,
+ structureSummaries,
+ ),
+ };
+ report.warnings = warningSummary(stageResults);
+
+ if (hasFailedIntegrity(report.integrity)) {
+ report.status = 'failed';
+ report.error = 'One or more deterministic integrity checks failed';
+ exitCode = 1;
+ } else if (
+ report.warnings.length > 0 ||
+ report.integrity.filesSkipped > 0
+ ) {
+ report.status = 'degraded';
+ exitCode = 0;
+ } else {
+ report.status = 'ok';
+ exitCode = 0;
+ }
+ } catch (error) {
+ report.status = 'failed';
+ report.warnings = warningSummary(stageResults);
+ const rawMessage =
+ error instanceof BenchmarkStageError
+ ? error.stage.stderr || error.message
+ : error instanceof Error
+ ? error.message
+ : String(error);
+ report.error = redactPaths(rawMessage, redactionRoots);
+ exitCode = 1;
+ } finally {
+ report.run.finishedAt = new Date().toISOString();
+ report.run.durationMs =
+ Math.round((performance.now() - overallStart) * 100) / 100;
+ }
+
+ if (!options.keepArtifacts) {
+ cleanupBenchmarkArtifacts(artifactRoot);
+ }
+
+ try {
+ deliverBenchmarkReports({
+ outputPath: options.outputPath,
+ markdownPath: options.markdownPath,
+ jsonContents: `${JSON.stringify(report, null, 2)}\n`,
+ markdownContents: renderMarkdownReport(report),
+ });
+ } catch {
+ throw new BenchmarkReportWriteError(
+ options.keepArtifacts ? artifactRoot : null,
+ );
+ }
+
+ return {
+ report,
+ exitCode,
+ artifactRoot: options.keepArtifacts ? artifactRoot : null,
+ };
+}
diff --git a/tests/benchmark/test_large_repo_benchmark.test.mjs b/tests/benchmark/test_large_repo_benchmark.test.mjs
new file mode 100644
index 00000000..221d7c41
--- /dev/null
+++ b/tests/benchmark/test_large_repo_benchmark.test.mjs
@@ -0,0 +1,1522 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ realpathSync,
+ readdirSync,
+ renameSync,
+ rmSync,
+ symlinkSync,
+ writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import * as benchmark from '../../scripts/lib/large-repo-benchmark.mjs';
+
+const { CliUsageError, parseArgs } = benchmark;
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCRIPT = resolve(__dirname, '../../scripts/benchmark-large-repo.mjs');
+const REPORT_SCHEMA = resolve(
+ __dirname,
+ '../../docs/benchmarks/large-repo-report-1.0.0.schema.json',
+);
+const reportSchema = JSON.parse(readFileSync(REPORT_SCHEMA, 'utf-8'));
+const validateReport = new Ajv2020({
+ allErrors: true,
+ formats: { 'date-time': true },
+}).compile(reportSchema);
+
+function expectValidReport(report) {
+ expect(
+ validateReport(report),
+ JSON.stringify(validateReport.errors, null, 2),
+ ).toBe(true);
+}
+
+function makeSubject() {
+ const root = mkdtempSync(join(tmpdir(), 'ua benchmark subject-'));
+ const subject = join(root, '项目 with spaces');
+ mkdirSync(join(subject, 'src'), { recursive: true });
+ writeFileSync(
+ join(subject, 'src', 'math.ts'),
+ 'export function add(a: number, b: number) { return a + b; }\n',
+ );
+ writeFileSync(
+ join(subject, 'src', 'index.ts'),
+ 'import { add } from "./math";\nexport const answer = add(20, 22);\n',
+ );
+ writeFileSync(
+ join(subject, 'README.md'),
+ '# Mini repository\n\nA deterministic benchmark fixture.\n',
+ );
+ return { root, subject };
+}
+
+function snapshotTree(root) {
+ const entries = [];
+
+ function visit(directory, relativeDirectory = '') {
+ for (const entry of readdirSync(directory, { withFileTypes: true }).sort(
+ (left, right) => left.name.localeCompare(right.name),
+ )) {
+ const relativePath = join(relativeDirectory, entry.name).replaceAll('\\', '/');
+ const absolutePath = join(directory, entry.name);
+ if (entry.isDirectory()) {
+ entries.push([relativePath, 'directory']);
+ visit(absolutePath, relativePath);
+ } else {
+ entries.push([
+ relativePath,
+ 'file',
+ readFileSync(absolutePath).toString('base64'),
+ ]);
+ }
+ }
+ }
+
+ visit(root);
+ return entries;
+}
+
+function runCli(args, options = {}) {
+ return spawnSync(process.execPath, [SCRIPT, ...args], {
+ encoding: 'utf-8',
+ timeout: 60_000,
+ ...options,
+ });
+}
+
+function benchmarkArtifactEntries() {
+ return readdirSync(tmpdir(), { withFileTypes: true })
+ .filter(
+ (entry) =>
+ entry.isDirectory() && entry.name.startsWith('ua-large-bench-'),
+ )
+ .map((entry) => entry.name)
+ .sort();
+}
+
+function expectSafeReportWriteFailure(result, sensitivePaths) {
+ expect(result.status).toBe(1);
+ expect(result.stdout).toBe('');
+ expect(result.stderr).toMatch(
+ /^(?:\[benchmark\] [^\r\n]+\r?\n)*Error: Unable to write benchmark report files\r?\n$/,
+ );
+ expect(result.stderr).not.toMatch(
+ /UnhandledPromiseRejection|node:fs:|(?:^|\r?\n)\s*at\s|\bError: EISDIR\b/,
+ );
+ for (const sensitivePath of sensitivePaths) {
+ for (const alias of new Set([
+ sensitivePath,
+ sensitivePath.replaceAll('\\', '/'),
+ sensitivePath.replaceAll('/', '\\'),
+ ])) {
+ expect(result.stderr).not.toContain(alias);
+ }
+ }
+ expect(result.stderr).not.toContain('ua-large-bench-');
+}
+
+function runGit(directory, args) {
+ const result = spawnSync('git', ['-C', directory, ...args], {
+ encoding: 'utf-8',
+ windowsHide: true,
+ });
+ if (result.status !== 0) {
+ throw new Error(result.stderr || `git ${args.join(' ')} failed`);
+ }
+ return result.stdout.trim();
+}
+
+function makeGitSubject() {
+ const root = mkdtempSync(join(tmpdir(), 'ua benchmark git-'));
+ const subject = join(root, 'subject repo');
+ mkdirSync(subject);
+ runGit(subject, ['init', '--quiet']);
+ writeFileSync(join(subject, 'tracked.txt'), 'clean\n');
+ runGit(subject, ['add', 'tracked.txt']);
+ runGit(subject, [
+ '-c',
+ 'user.name=Benchmark Test',
+ '-c',
+ 'commit',
+ '--quiet',
+ '-m',
+ 'initial',
+ ]);
+ return { root, subject };
+}
+
+describe('bounded benchmark stage output', () => {
+ const cleanup = [];
+
+ afterEach(() => {
+ for (const path of cleanup.splice(0)) {
+ rmSync(path, { recursive: true, force: true });
+ }
+ });
+
+ it('bounds retained streams while parsing late metrics and all warnings', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'ua benchmark noisy-stage-'));
+ cleanup.push(root);
+ const subject = join(root, 'private subject');
+ const artifacts = join(root, 'private artifacts');
+ mkdirSync(subject);
+ mkdirSync(artifacts);
+ const helperPath = join(root, 'noisy-helper.mjs');
+ writeFileSync(
+ helperPath,
+ `
+const [subject, tool, artifacts, cap] = process.argv.slice(2);
+process.stdout.write(\`stdout roots: \${subject}/out.txt \${tool}/worker.mjs \${artifacts}/out.json\\n\`);
+process.stdout.write('s'.repeat(Number(cap) * 2));
+process.stderr.write(\`stderr roots: \${subject}/error.txt \${tool}/worker.mjs \${artifacts}/error.json\\n\`);
+process.stderr.write('n'.repeat(Number(cap) * 2));
+process.stderr.write('\\n');
+for (let index = 0; index < 12; index += 1) {
+ const root = [subject, tool, artifacts][index % 3];
+ const warning = Buffer.from(\`Warning: \${String(index).padStart(2, '0')} \\u{1F9EA} \${root}/warning.txt\\n\`);
+ if (index === 0) {
+ for (const byte of warning) process.stderr.write(Buffer.from([byte]));
+ } else {
+ process.stderr.write(warning);
+ }
+}
+throw new Error(\`helper failed below \${subject}/failed.txt\`);
+`,
+ );
+ const redactionRoots = [
+ [subject, '<subject>'],
+ [benchmark.REPO_ROOT, '<tool>'],
+ [artifacts, '<artifacts>'],
+ ];
+
+ const stage = await benchmark.runNodeStage(
+ 'noisy',
+ helperPath,
+ [
+ subject,
+ benchmark.REPO_ROOT,
+ artifacts,
+ String(benchmark.STAGE_OUTPUT_MAX_BYTES),
+ ],
+ redactionRoots,
+ );
+
+ expect(benchmark.STAGE_OUTPUT_MAX_BYTES).toBe(128 * 1024);
+ expect(benchmark.WARNING_SAMPLE_LIMIT).toBe(5);
+ expect(stage.status).toBe('failed');
+ expect(stage.stdoutTruncated).toBe(true);
+ expect(stage.stderrTruncated).toBe(true);
+ expect(Buffer.byteLength(stage.stdout)).toBeLessThanOrEqual(
+ benchmark.STAGE_OUTPUT_MAX_BYTES,
+ );
+ expect(Buffer.byteLength(stage.stderr)).toBeLessThanOrEqual(
+ benchmark.STAGE_OUTPUT_MAX_BYTES,
+ );
+ expect(stage.warningCount).toBe(12);
+ expect(stage.warningMessages).toHaveLength(benchmark.WARNING_SAMPLE_LIMIT);
+ expect(stage.warningMessagesTruncated).toBe(true);
+ expect(stage.warningMessages.map((message) => message.slice(0, 11))).toEqual([
+ 'Warning: 00',
+ 'Warning: 01',
+ 'Warning: 02',
+ 'Warning: 03',
+ 'Warning: 04',
+ ]);
+ expect(
+ stage.warningMessages.every(
+ (message) =>
+ Buffer.byteLength(message) <= benchmark.STAGE_OUTPUT_MAX_BYTES,
+ ),
+ ).toBe(true);
+ expect(stage.peakRssBytes).toBeGreaterThan(0);
+ expect(stage.userCpuTimeMicros).toBeGreaterThanOrEqual(0);
+ expect(stage.systemCpuTimeMicros).toBeGreaterThanOrEqual(0);
+ const retained = [stage.stdout, stage.stderr, ...stage.warningMessages].join(
+ '\n',
+ );
+ expect(retained).toContain('<subject>');
+ expect(retained).toContain('<tool>');
+ expect(retained).toContain('<artifacts>');
+ expect(retained).not.toContain('__UA_BENCHMARK_METRICS__');
+ expect(retained).not.toContain(subject);
+ expect(retained).not.toContain(benchmark.REPO_ROOT);
+ expect(retained).not.toContain(artifacts);
+ });
+
+ it('parses a final metrics marker without a newline', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'ua benchmark eof-metrics-'));
+ cleanup.push(root);
+ const helperPath = join(root, 'eof-metrics-helper.mjs');
+ const metrics = {
+ peakRssBytes: 123456,
+ userCpuTimeMicros: 234,
+ systemCpuTimeMicros: 345,
+ };
+ writeFileSync(
+ helperPath,
+ `
+import { writeSync } from 'node:fs';
+writeSync(2, ${JSON.stringify(
+ `${benchmark.STAGE_METRICS_PREFIX}${JSON.stringify(metrics)}`,
+ )});
+process.exit(0);
+`,
+ );
+
+ const stage = await benchmark.runNodeStage('eof-metrics', helperPath, []);
+
+ expect(stage.status).toBe('ok');
+ expect(stage.peakRssBytes).toBe(metrics.peakRssBytes);
+ expect(stage.userCpuTimeMicros).toBe(metrics.userCpuTimeMicros);
+ expect(stage.systemCpuTimeMicros).toBe(metrics.systemCpuTimeMicros);
+ expect(stage.stderr).toBe('');
+ expect(stage.warningCount).toBe(0);
+ });
+
+ it('counts and samples a final warning without a newline', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'ua benchmark eof-warning-'));
+ cleanup.push(root);
+ const subject = join(root, 'private subject');
+ mkdirSync(subject);
+ const helperPath = join(root, 'eof-warning-helper.mjs');
+ writeFileSync(
+ helperPath,
+ `
+import { writeSync } from 'node:fs';
+writeSync(2, \`Warning: final \${process.argv[2]}/file.ts\`);
+process.exit(0);
+`,
+ );
+
+ const stage = await benchmark.runNodeStage(
+ 'eof-warning',
+ helperPath,
+ [subject],
+ [[subject, '<subject>']],
+ );
+
+ expect(stage.status).toBe('ok');
+ expect(stage.warningCount).toBe(1);
+ expect(stage.warningMessages).toEqual([
+ 'Warning: final <subject>/file.ts',
+ ]);
+ expect(stage.warningMessagesTruncated).toBe(false);
+ expect(stage.stderr).toBe('Warning: final <subject>/file.ts');
+ expect(stage.stderr.endsWith('\n')).toBe(false);
+ expect(stage.peakRssBytes).toBeNull();
+ });
+});
+
+describe('benchmark warning aggregation', () => {
+ it('samples structure warnings in deterministic batch input order', () => {
+ const warnings = benchmark.aggregateStageWarnings([
+ {
+ warningCount: 3,
+ warningMessages: [
+ 'Warning: batch-0 first',
+ 'Warning: batch-0 second',
+ 'Warning: batch-0 third',
+ ],
+ warningMessagesTruncated: false,
+ },
+ {
+ warningCount: 4,
+ warningMessages: [
+ 'Warning: batch-1 first',
+ 'Warning: batch-1 second',
+ 'Warning: batch-1 third',
+ 'Warning: batch-1 fourth',
+ ],
+ warningMessagesTruncated: false,
+ },
+ ]);
+
+ expect(warnings).toEqual({
+ warningCount: 7,
+ warningMessages: [
+ 'Warning: batch-0 first',
+ 'Warning: batch-0 second',
+ 'Warning: batch-0 third',
+ 'Warning: batch-1 first',
+ 'Warning: batch-1 second',
+ ],
+ warningMessagesTruncated: true,
+ });
+ expect(
+ benchmark.warningSummary([{ name: 'structure', ...warnings }]),
+ ).toEqual([
+ {
+ stage: 'structure',
+ count: 7,
+ messages: warnings.warningMessages,
+ truncated: true,
+ },
+ ]);
+ });
+});
+
+describe('canonical benchmark digests', () => {
+ it('sorts object keys while preserving array order', () => {
+ expect(benchmark.canonicalSha256).toBeTypeOf('function');
+ const value = { z: 1, nested: { b: null, a: true }, a: [3, 2, 1] };
+ const canonicalJson = '{"a":[3,2,1],"nested":{"a":true,"b":null},"z":1}';
+ const expected = createHash('sha256').update(canonicalJson).digest('hex');
+
+ expect(benchmark.canonicalSha256(value)).toBe(expected);
+ expect(
+ benchmark.canonicalSha256({ a: [3, 2, 1], nested: { a: true, b: null }, z: 1 }),
+ ).toBe(expected);
+ expect(benchmark.canonicalSha256({ ...value, a: [1, 2, 3] })).not.toBe(
+ expected,
+ );
+ });
+
+ it('combines structure digests in deterministic batch input order', () => {
+ expect(benchmark.buildOutputDigest).toBeTypeOf('function');
+ const batches = {
+ batches: [{ batchIndex: 1 }, { batchIndex: 2 }],
+ };
+ const first = { batchIndex: 1, digest: 'a'.repeat(64) };
+ const second = { batchIndex: 2, digest: 'b'.repeat(64) };
+
+ const ordered = benchmark.buildOutputDigest({}, batches, [first, second]);
+ expect(benchmark.buildOutputDigest({}, batches, [second, first])).toBe(
+ ordered,
+ );
+ expect(
+ benchmark.buildOutputDigest({}, batches, [
+ first,
+ { ...second, digest: 'c'.repeat(64) },
+ ]),
+ ).not.toBe(ordered);
+ });
+});
+
+describe('structure output summaries', () => {
+ const batch = {
+ batchIndex: 7,
+ files: [
+ { path: 'src/a.ts' },
+ { path: 'src/b.ts' },
+ { path: 'src/c.ts' },
+ ],
+ };
+
+ it('accepts the exact union of analyzed and skipped paths', () => {
+ expect(benchmark.summarizeStructureOutput).toBeTypeOf('function');
+ const output = {
+ scriptCompleted: true,
+ filesAnalyzed: 2,
+ filesSkipped: ['src/b.ts'],
+ results: [
+ { path: 'src/a.ts', functions: [{ name: 'a' }], exports: ['a'] },
+ { path: 'src/c.ts', classes: [{ name: 'C' }] },
+ ],
+ };
+
+ expect(benchmark.summarizeStructureOutput(batch, output)).toEqual({
+ batchIndex: 7,
+ digest: benchmark.canonicalSha256(output),
+ complete: true,
+ malformed: false,
+ expectedFiles: 3,
+ accountedExpectedPaths: 3,
+ filesAnalyzed: 2,
+ filesSkipped: 1,
+ missingStructurePaths: 0,
+ duplicateStructurePaths: 0,
+ unexpectedStructurePaths: 0,
+ entities: {
+ functions: 1,
+ classes: 1,
+ exports: 1,
+ callGraph: 0,
+ definitions: 0,
+ services: 0,
+ endpoints: 0,
+ steps: 0,
+ resources: 0,
+ },
+ });
+ });
+
+ it('reports missing, duplicate, and unexpected paths', () => {
+ expect(benchmark.summarizeStructureOutput).toBeTypeOf('function');
+ const summary = benchmark.summarizeStructureOutput(batch, {
+ scriptCompleted: true,
+ filesAnalyzed: 3,
+ filesSkipped: ['src/b.ts'],
+ results: [
+ { path: 'src/a.ts' },
+ { path: 'src/a.ts' },
+ { path: 'src/unexpected.ts' },
+ ],
+ });
+
+ expect(summary).toMatchObject({
+ complete: false,
+ malformed: false,
+ accountedExpectedPaths: 2,
+ missingStructurePaths: 1,
+ duplicateStructurePaths: 1,
+ unexpectedStructurePaths: 1,
+ });
+ });
+
+ it('treats an object without the required output shape as malformed', () => {
+ expect(benchmark.summarizeStructureOutput).toBeTypeOf('function');
+ expect(benchmark.summarizeStructureOutput(batch, {})).toMatchObject({
+ complete: false,
+ malformed: true,
+ accountedExpectedPaths: 0,
+ missingStructurePaths: 3,
+ });
+ });
+
+ it('aggregates file and entity counts from compact summaries', () => {
+ expect(benchmark.aggregateStructureSummaries).toBeTypeOf('function');
+ const first = benchmark.summarizeStructureOutput(batch, {
+ scriptCompleted: true,
+ filesAnalyzed: 2,
+ filesSkipped: ['src/b.ts'],
+ results: [
+ { path: 'src/a.ts', functions: [{ name: 'a' }] },
+ { path: 'src/c.ts', classes: [{ name: 'C' }] },
+ ],
+ });
+ const secondBatch = {
+ batchIndex: 8,
+ files: [{ path: 'src/d.ts' }],
+ };
+ const second = benchmark.summarizeStructureOutput(secondBatch, {
+ scriptCompleted: true,
+ filesAnalyzed: 1,
+ filesSkipped: [],
+ results: [{ path: 'src/d.ts', functions: [{}, {}], exports: [{}] }],
+ });
+
+ expect(benchmark.aggregateStructureSummaries([first, second])).toEqual({
+ filesAnalyzed: 3,
+ filesSkipped: 1,
+ entities: {
+ functions: 3,
+ classes: 1,
+ exports: 1,
+ callGraph: 0,
+ definitions: 0,
+ services: 0,
+ endpoints: 0,
+ steps: 0,
+ resources: 0,
+ },
+ });
+ expect(first).not.toHaveProperty('results');
+ expect(second).not.toHaveProperty('results');
+ });
+});
+
+describe('structure resource aggregation', () => {
+ it('sums worker CPU while retaining only the maximum worker RSS', () => {
+ expect(benchmark.aggregateStructureResources).toBeTypeOf('function');
+ expect(
+ benchmark.aggregateStructureResources([
+ {
+ peakRssBytes: 100,
+ userCpuTimeMicros: 20,
+ systemCpuTimeMicros: 4,
+ },
+ {
+ peakRssBytes: 250,
+ userCpuTimeMicros: 30,
+ systemCpuTimeMicros: 6,
+ },
+ ]),
+ ).toEqual({
+ maxWorkerPeakRssBytes: 250,
+ userCpuTimeMicros: 50,
+ systemCpuTimeMicros: 10,
+ });
+ expect(benchmark.aggregateStructureResources([])).toEqual({
+ maxWorkerPeakRssBytes: null,
+ userCpuTimeMicros: null,
+ systemCpuTimeMicros: null,
+ });
+ });
+
+ it('renders the structure worker maximum and summed CPU values', () => {
+ expect(benchmark.renderMarkdownReport).toBeTypeOf('function');
+ const markdown = benchmark.renderMarkdownReport({
+ schemaVersion: '1.0.0',
+ status: 'ok',
+ subject: { label: 'fixture', commit: null },
+ tool: { commit: null, packageVersion: '0.0.0' },
+ run: { startedAt: '2026-01-01T00:00:00.000Z', durationMs: 12 },
+ configuration: { concurrency: 2 },
+ llm: { invoked: false },
+ scale: {},
+ stages: {
+ structure: {
+ status: 'ok',
+ durationMs: 12,
+ maxWorkerPeakRssBytes: 250,
+ userCpuTimeMicros: 50,
+ systemCpuTimeMicros: 10,
+ outputBytes: 99,
+ },
+ },
+ integrity: {},
+ determinism: {},
+ environment: {
+ platform: 'test',
+ release: 'test',
+ arch: 'test',
+ nodeVersion: 'test',
+ cpuModel: 'test',
+ logicalCores: 1,
+ totalMemoryBytes: 1,
+ },
+ warnings: [],
+ error: null,
+ });
+
+ expect(markdown).toContain(
+ '| Stage | Status | Duration | Peak / max worker RSS (bytes) | User CPU (micros) | System CPU (micros) | Output (bytes) |',
+ );
+ expect(markdown).toContain('| structure | ok | 12 ms | 250 | 50 | 10 | 99 |');
+ });
+});
+
+describe('benchmark integrity aggregation', () => {
+ const scan = {
+ totalFiles: 3,
+ files: [
+ { path: 'src/a.ts' },
+ { path: 'src/b.ts' },
+ { path: 'src/c.ts' },
+ ],
+ };
+ const batch = {
+ batchIndex: 1,
+ files: scan.files,
+ };
+ const batches = { batches: [batch] };
+
+ it('keeps exact skipped-path accounting complete but degraded-capable', () => {
+ expect(benchmark.buildBenchmarkIntegrity).toBeTypeOf('function');
+ expect(benchmark.hasFailedIntegrity).toBeTypeOf('function');
+ const summary = benchmark.summarizeStructureOutput(batch, {
+ scriptCompleted: true,
+ filesAnalyzed: 2,
+ filesSkipped: ['src/b.ts'],
+ results: [{ path: 'src/a.ts' }, { path: 'src/c.ts' }],
+ });
+ const integrity = benchmark.buildBenchmarkIntegrity(
+ scan,
+ {},
+ batches,
+ [summary],
+ 0,
+ );
+
+ expect(integrity).toMatchObject({
+ structureCoverage: 1,
+ filesSkipped: 1,
+ missingStructurePaths: 0,
+ duplicateStructurePaths: 0,
+ unexpectedStructurePaths: 0,
+ malformedStructureBatches: 0,
+ });
+ expect(benchmark.hasFailedIntegrity(integrity)).toBe(false);
+ });
+
+ it('fails incomplete and conflicting structure path accounting', () => {
+ expect(benchmark.buildBenchmarkIntegrity).toBeTypeOf('function');
+ expect(benchmark.hasFailedIntegrity).toBeTypeOf('function');
+ const summary = benchmark.summarizeStructureOutput(batch, {
+ scriptCompleted: true,
+ filesAnalyzed: 3,
+ filesSkipped: ['src/b.ts'],
+ results: [
+ { path: 'src/a.ts' },
+ { path: 'src/a.ts' },
+ { path: 'src/unexpected.ts' },
+ ],
+ });
+ const integrity = benchmark.buildBenchmarkIntegrity(
+ scan,
+ {},
+ batches,
+ [summary],
+ 1,
+ );
+
+ expect(integrity).toMatchObject({
+ structureCoverage: 0.6667,
+ missingStructurePaths: 1,
+ duplicateStructurePaths: 1,
+ unexpectedStructurePaths: 1,
+ failedBatches: 1,
+ });
+ expect(benchmark.hasFailedIntegrity(integrity)).toBe(true);
+ });
+
+ it('rejects malformed output even when the expected path set is empty', () => {
+ const emptyScan = { totalFiles: 0, files: [] };
+ const emptyBatch = { batchIndex: 1, files: [] };
+ const summary = benchmark.summarizeStructureOutput(emptyBatch, {});
+ const integrity = benchmark.buildBenchmarkIntegrity(
+ emptyScan,
+ {},
+ { batches: [emptyBatch] },
+ [summary],
+ 0,
+ );
+
+ expect(integrity).toMatchObject({
+ structureCoverage: 1,
+ missingStructurePaths: 0,
+ malformedStructureBatches: 1,
+ });
+ expect(benchmark.hasFailedIntegrity(integrity)).toBe(true);
+ });
+
+ it.each([
+ ['missing paths', { structureCoverage: 0.5, missingStructurePaths: 1 }],
+ ['duplicate paths', { duplicateStructurePaths: 1 }],
+ ['unexpected paths', { unexpectedStructurePaths: 1 }],
+ ['malformed output', { malformedStructureBatches: 1 }],
+ ['failed batches', { failedBatches: 1 }],
+ ])('rejects %s independently', (_label, overrides) => {
+ const completeIntegrity = {
+ allScannedFilesBatched: true,
+ missingImportTargets: 0,
+ structureCoverage: 1,
+ failedBatches: 0,
+ missingStructurePaths: 0,
+ duplicateStructurePaths: 0,
+ unexpectedStructurePaths: 0,
+ malformedStructureBatches: 0,
+ };
+
+ expect(
+ benchmark.hasFailedIntegrity({ ...completeIntegrity, ...overrides }),
+ ).toBe(true);
+ });
+});
+
+describe('path redaction', () => {
+ const cleanup = [];
+
+ afterEach(() => {
+ for (const path of cleanup.splice(0)) {
+ rmSync(path, { recursive: true, force: true });
+ }
+ });
+
+ it('redacts native, separator, file URL, and Windows aliases', () => {
+ const root = mkdtempSync(join(tmpdir(), 'ua benchmark redact-'));
+ cleanup.push(root);
+ const subject = join(root, 'subject root');
+ const tool = join(root, 'tool root');
+ const artifacts = join(root, 'artifact root');
+ mkdirSync(subject);
+ mkdirSync(tool);
+ mkdirSync(artifacts);
+
+ const slashSubject = subject.replaceAll('\\', '/');
+ const backslashSubject = subject.replaceAll('/', '\\');
+ const messages = [
+ `native ${join(subject, 'src', 'file.ts')}`,
+ `slash ${slashSubject}/src/file.ts`,
+ `backslash ${backslashSubject}\\src\\file.ts`,
+ `url ${pathToFileURL(subject).href}/src/file%20name.ts`,
+ `tool ${join(tool, 'worker.mjs')}`,
+ `artifacts ${join(artifacts, 'result.json')}`,
+ ];
+ if (process.platform === 'win32') {
+ messages.push(`extended \\\\?\\${backslashSubject}\\src\\file.ts`);
+ messages.push(`case ${subject.toUpperCase()}\\SRC\\FILE.TS`);
+ }
+
+ expect(benchmark.redactPaths).toBeTypeOf('function');
+ const redacted = benchmark.redactPaths(messages.join('\n'), [
+ [subject, '<subject>'],
+ [tool, '<tool>'],
+ [artifacts, '<artifacts>'],
+ ]);
+
+ expect(redacted).toContain('native <subject>');
+ expect(redacted).toContain('slash <subject>/src/file.ts');
+ expect(redacted).toContain('backslash <subject>\\src\\file.ts');
+ expect(redacted).toContain('url <subject>/src/file%20name.ts');
+ expect(redacted).toContain('tool <tool>');
+ expect(redacted).toContain('artifacts <artifacts>');
+ for (const privateRoot of [
+ subject,
+ slashSubject,
+ backslashSubject,
+ pathToFileURL(subject).href,
+ tool,
+ artifacts,
+ ]) {
+ expect(redacted).not.toContain(privateRoot);
+ }
+ if (process.platform === 'win32') {
+ expect(redacted).toContain('extended <subject>\\src\\file.ts');
+ expect(redacted).toContain('case <subject>\\SRC\\FILE.TS');
+ }
+ });
+
+ it('uses the longest realpath alias and preserves sibling prefixes', () => {
+ const root = mkdtempSync(join(tmpdir(), 'ua benchmark aliases-'));
+ cleanup.push(root);
+ const physicalSubject = join(root, 'physical subject');
+ const lexicalSubject = join(root, 'subject');
+ mkdirSync(physicalSubject);
+ symlinkSync(
+ physicalSubject,
+ lexicalSubject,
+ process.platform === 'win32' ? 'junction' : 'dir',
+ );
+ const realSubject = realpathSync.native(lexicalSubject);
+ const sibling = `${lexicalSubject}-copy`;
+
+ expect(benchmark.redactPaths).toBeTypeOf('function');
+ const redacted = benchmark.redactPaths(
+ [
+ join(lexicalSubject, 'lexical.txt'),
+ join(realSubject, 'physical.txt'),
+ join(sibling, 'public.txt'),
+ ].join('\n'),
+ [
+ [root, '<tool>'],
+ [lexicalSubject, '<subject>'],
+ ],
+ );
+
+ expect(redacted).toContain(join('<subject>', 'lexical.txt'));
+ expect(redacted).toContain(join('<subject>', 'physical.txt'));
+ expect(redacted).toContain(join('<tool>', 'subject-copy', 'public.txt'));
+ expect(redacted).not.toContain(join('<subject>-copy', 'public.txt'));
+ expect(redacted).not.toContain(join('<tool>', 'subject', 'lexical.txt'));
+ });
+
+ it.runIf(process.platform === 'win32')(
+ 'redacts mixed-case extended UNC roots through ordinary aliases',
+ () => {
+ const extendedRoot = '\\\\?\\uNc\\localhost\\missing-share\\Repo Root';
+ const ordinaryRoot = '\\\\localhost\\missing-share\\Repo Root';
+ const redacted = benchmark.redactPaths(
+ [
+ `${extendedRoot}\\extended.txt`,
+ `${ordinaryRoot}\\ordinary.txt`,
+ ].join('\n'),
+ [[extendedRoot, '<subject>']],
+ );
+
+ expect(redacted).toBe(
+ ['<subject>\\extended.txt', '<subject>\\ordinary.txt'].join('\n'),
+ );
+ },
+ );
+
+ it('does not treat a terminal dot as a path boundary', () => {
+ const root = mkdtempSync(join(tmpdir(), 'ua benchmark dot-'));
+ cleanup.push(root);
+ const subject = join(root, 'repo');
+ mkdirSync(subject);
+ const sibling = `${subject.replaceAll('\\', '/')}.`;
+
+ expect(benchmark.redactPaths(sibling, [[subject, '<subject>']])).toBe(
+ sibling,
+ );
+ });
+
+ it('redacts exact roots and descendants without rewriting real siblings', () => {
+ const root = mkdtempSync(join(tmpdir(), 'ua benchmark boundary-'));
+ cleanup.push(root);
+ const subject = join(root, 'repo');
+ const descendant = join(subject, 'src', 'private.txt');
+ const spacedSibling = join(`${subject} copy`, 'public.txt');
+ const punctuatedSibling = join(`${subject},copy`, 'public.txt');
+ mkdirSync(dirname(descendant), { recursive: true });
+ mkdirSync(dirname(spacedSibling), { recursive: true });
+ mkdirSync(dirname(punctuatedSibling), { recursive: true });
+ writeFileSync(descendant, 'private\n');
+ writeFileSync(spacedSibling, 'public\n');
+ writeFileSync(punctuatedSibling, 'public\n');
+ const roots = [[subject, '<subject>']];
+
+ expect(benchmark.redactPaths(subject, roots)).toBe('<subject>');
+ expect(benchmark.redactPaths(descendant, roots)).toBe(
+ join('<subject>', 'src', 'private.txt'),
+ );
+ expect(benchmark.redactPaths(spacedSibling, roots)).toBe(spacedSibling);
+ expect(benchmark.redactPaths(punctuatedSibling, roots)).toBe(
+ punctuatedSibling,
+ );
+ });
+
+ it.runIf(process.platform !== 'win32')(
+ 'preserves a valid POSIX terminal-dot sibling',
+ () => {
+ const root = mkdtempSync(join(tmpdir(), 'ua benchmark posix-dot-'));
+ cleanup.push(root);
+ const subject = join(root, 'repo');
+ mkdirSync(subject);
+ const sibling = `${subject}.`;
+
+ expect(benchmark.redactPaths(sibling, [[subject, '<subject>']])).toBe(
+ sibling,
+ );
+ },
+ );
+});
+
+describe('Git metadata probes', () => {
+ const cleanup = [];
+
+ afterEach(() => {
+ for (const path of cleanup.splice(0)) {
+ rmSync(path, { recursive: true, force: true });
+ }
+ });
+
+ it('reports ordinary clean and dirty repositories', () => {
+ const { root, subject } = makeGitSubject();
+ cleanup.push(root);
+ const commit = runGit(subject, ['rev-parse', 'HEAD']);
+
+ expect(benchmark.gitMetadata).toBeTypeOf('function');
+ expect(benchmark.gitMetadata(subject)).toEqual({ commit, dirty: false });
+
+ writeFileSync(join(subject, 'tracked.txt'), 'dirty\n');
+ expect(benchmark.gitMetadata(subject)).toEqual({ commit, dirty: true });
+ });
+
+ it('conservatively reports dirty when porcelain output exceeds its cap', () => {
+ const { root, subject } = makeGitSubject();
+ cleanup.push(root);
+
+ expect(benchmark.GIT_METADATA_MAX_BUFFER).toBeGreaterThan(0);
+ const fileCount =
+ Math.ceil(benchmark.GIT_METADATA_MAX_BUFFER / 60) + 200;
+ for (let index = 0; index < fileCount; index += 1) {
+ writeFileSync(
+ join(
+ subject,
+ `overflow-${String(index).padStart(5, '0')}-${'x'.repeat(40)}.txt`,
+ ),
+ '',
+ );
+ }
+
+ const boundedStatus = spawnSync(
+ 'git',
+ ['-C', subject, 'status', '--porcelain'],
+ {
+ encoding: 'utf-8',
+ maxBuffer: benchmark.GIT_METADATA_MAX_BUFFER,
+ windowsHide: true,
+ },
+ );
+ expect(boundedStatus.error?.code).toBe('ENOBUFS');
+ expect(benchmark.gitMetadata(subject).dirty).toBe(true);
+ });
+});
+
+describe('large repository benchmark CLI', () => {
+ const cleanup = [];
+
+ afterEach(() => {
+ for (const path of cleanup.splice(0)) {
+ rmSync(path, { recursive: true, force: true });
+ }
+ });
+
+ it('parses a positional repository and validates concurrency', () => {
+ const { root, subject } = makeSubject();
+ cleanup.push(root);
+
+ const options = parseArgs(
+ [subject, '--concurrency', '3', '--label', 'polyglot-mini'],
+ root,
+ );
+ expect(options.repoRoot).toBe(subject);
+ expect(options.concurrency).toBe(3);
+ expect(options.label).toBe('polyglot-mini');
+ expect(options.markdownPath).toBe(
+ join(root, 'benchmark-results', 'large-repo-report.md'),
+ );
+ expect(() => parseArgs([subject, '--concurrency', '0'], root)).toThrow(
+ CliUsageError,
+ );
+ });
+
+ it.each(['2.5', '3junk', '1e1', ''])(
+ 'rejects malformed concurrency %j in split and equals forms',
+ (rawConcurrency) => {
+ const { root, subject } = makeSubject();
+ cleanup.push(root);
+
+ expect(() =>
+ parseArgs([subject, '--concurrency', rawConcurrency], root),
+ ).toThrow(CliUsageError);
+ expect(() =>
+ parseArgs([subject, `--concurrency=${rawConcurrency}`], root),
+ ).toThrow(CliUsageError);
+ },
+ );
+
+ it('rejects report output paths equal to or inside the subject repository', () => {
+ const { root, subject } = makeSubject();
+ cleanup.push(root);
+
+ expect(() => parseArgs([subject, '--output', subject], root)).toThrow(
+ CliUsageError,
+ );
+ expect(() =>
+ parseArgs([subject, `--output=${join(subject, 'reports', 'result.json')}`], root),
+ ).toThrow(CliUsageError);
+ expect(() => parseArgs([subject], subject)).toThrow(CliUsageError);
+ });
+
+ it('rejects an outside JSON path whose derived Markdown path is the subject', () => {
+ const root = mkdtempSync(join(tmpdir(), 'ua benchmark output-'));
+ cleanup.push(root);
+ const subject = join(root, 'subject.md');
+ mkdirSync(subject);
+
+ expect(() =>
+ parseArgs([subject, '--output', join(root, 'subject.json')], root),
+ ).toThrow(CliUsageError);
+ });
+
+ it('accepts report paths under an outside sibling-prefix directory', () => {
+ const root = mkdtempSync(join(tmpdir(), 'ua benchmark sibling-'));
+ cleanup.push(root);
+ const subject = join(root, 'repo');
+ const outputPath = join(root, 'repo-copy', 'result.json');
+ mkdirSync(subject);
+
+ const options = parseArgs([subject, '--output', outputPath], root);
+
+ expect(options.outputPath).toBe(outputPath);
+ expect(options.markdownPath).toBe(join(root, 'repo-copy', 'result.md'));
+ });
+
+ it('rejects a non-existing report path through a physical repository alias', () => {
+ const root = mkdtempSync(join(tmpdir(), 'ua benchmark containment-'));
+ cleanup.push(root);
+ const subject = join(root, 'physical repo');
+ const subjectAlias = join(root, 'repo alias');
+ mkdirSync(subject);
+ symlinkSync(
+ subject,
+ subjectAlias,
+ process.platform === 'win32' ? 'junction' : 'dir',
+ );
+ const reportPath = join(subjectAlias, 'missing', 'report.json');
+
+ expect(() =>
+ parseArgs([subject, '--output', reportPath], root),
+ ).toThrow(CliUsageError);
+ expect(
+ benchmark.isPathInsideOrEqual(
+ subjectAlias,
+ join(subject, 'missing', 'report.json'),
+ ),
+ ).toBe(true);
+ });
+
+ it.runIf(process.platform === 'win32')(
+ 'normalizes extended drive and UNC namespaces for containment',
+ () => {
+ const lexicalRoot = join(tmpdir(), 'ua namespace repo');
+ const extendedRoot = `\\\\?\\${lexicalRoot}`;
+ const ordinaryUncRoot = '\\\\localhost\\missing-share\\repo';
+ const extendedUncOutput =
+ '\\\\?\\UNC\\localhost\\missing-share\\repo\\report.json';
+
+ expect(
+ benchmark.isPathInsideOrEqual(
+ extendedRoot,
+ join(lexicalRoot, 'report.json'),
+ ),
+ ).toBe(true);
+ expect(
+ benchmark.isPathInsideOrEqual(ordinaryUncRoot, extendedUncOutput),
+ ).toBe(true);
+ },
+ );
+
+ it('records failed scan telemetry before writing the failed report', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'ua failed scan benchmark-'));
+ cleanup.push(root);
+ const subject = join(root, 'not-a-directory.txt');
+ const outputPath = join(root, 'reports', 'failed.json');
+ const markdownPath = join(root, 'reports', 'failed.md');
+ writeFileSync(subject, 'not a repository directory\n');
+
+ const result = await benchmark.runBenchmark({
+ repoRoot: subject,
+ outputPath,
+ markdownPath,
+ label: 'invalid-subject',
+ concurrency: 1,
+ keepArtifacts: false,
+ });
+
+ expect(result.exitCode).toBe(1);
+ expect(result.report.status).toBe('failed');
+ expectValidReport(result.report);
+ expect(result.report.stages.scan).toMatchObject({
+ status: 'failed',
+ outputBytes: 0,
+ warningCount: 0,
+ warningMessages: [],
+ warningMessagesTruncated: false,
+ });
+ expect(result.report.stages.scan.durationMs).toBeGreaterThanOrEqual(0);
+ expect(result.report.stages.scan).toHaveProperty('peakRssBytes');
+ expect(result.report.stages.scan).toHaveProperty('userCpuTimeMicros');
+ expect(result.report.stages.scan).toHaveProperty('systemCpuTimeMicros');
+ expect(existsSync(outputPath)).toBe(true);
+ expect(existsSync(markdownPath)).toBe(true);
+ const serialized = readFileSync(outputPath, 'utf-8');
+ const persisted = JSON.parse(serialized);
+ expect(persisted.stages.scan.status).toBe('failed');
+ expect(persisted.error).not.toContain(subject);
+ expect(persisted.error).not.toContain(benchmark.REPO_ROOT);
+ expect(readFileSync(markdownPath, 'utf-8')).not.toContain(subject);
+ });
+
+ it('wraps cleanup operation failures without exposing artifact paths', () => {
+ const artifactRoot = join(tmpdir(), 'ua-large-bench-private-cleanup');
+ let cleanupError;
+
+ try {
+ benchmark.cleanupBenchmarkArtifacts(artifactRoot, {
+ rmSync() {
+ throw new Error(`EPERM while removing ${artifactRoot}`);
+ },
+ });
+ } catch (error) {
+ cleanupError = error;
+ }
+
+ expect(cleanupError).toBeInstanceOf(benchmark.BenchmarkArtifactCleanupError);
+ expect(cleanupError).toMatchObject({
+ message: 'Unable to remove temporary benchmark artifacts',
+ name: 'BenchmarkArtifactCleanupError',
+ });
+ expect(cleanupError).not.toHaveProperty('artifactRoot');
+ expect(cleanupError).not.toHaveProperty('cause');
+ expect(cleanupError.message).not.toContain(artifactRoot);
+ expect(cleanupError.message).not.toContain('EPERM');
+ });
+
+ it('rolls back both reports when the second report commit fails', () => {
+ const root = mkdtempSync(join(tmpdir(), 'ua report transaction-'));
+ cleanup.push(root);
+ const reportsDirectory = join(root, 'reports');
+ const outputPath = join(reportsDirectory, 'result.json');
+ const markdownPath = join(reportsDirectory, 'result.md');
+ const sentinelPath = join(reportsDirectory, 'sentinel.txt');
+ mkdirSync(reportsDirectory);
+ writeFileSync(outputPath, 'old json\n');
+ writeFileSync(markdownPath, 'old markdown\n');
+ writeFileSync(sentinelPath, 'unrelated\n');
+ const entriesBefore = readdirSync(reportsDirectory).sort();
+ let failedSecondCommit = false;
+ let deliveryError;
+
+ try {
+ benchmark.deliverBenchmarkReports(
+ {
+ outputPath,
+ markdownPath,
+ jsonContents: 'new json\n',
+ markdownContents: 'new markdown\n',
+ },
+ {
+ renameSync(source, destination) {
+ if (destination === markdownPath && source.endsWith('.tmp')) {
+ failedSecondCommit = true;
+ throw new Error(`EPERM renaming ${source} to ${destination}`);
+ }
+ renameSync(source, destination);
+ },
+ },
+ );
+ } catch (error) {
+ deliveryError = error;
+ }
+
+ expect(failedSecondCommit).toBe(true);
+ expect(deliveryError).toBeInstanceOf(benchmark.BenchmarkReportWriteError);
+ expect(deliveryError).toMatchObject({
+ message: 'Unable to write benchmark report files',
+ name: 'BenchmarkReportWriteError',
+ });
+ expect(deliveryError).not.toHaveProperty('cause');
+ expect(deliveryError.message).not.toContain(root);
+ expect(deliveryError.message).not.toContain('EPERM');
+ expect(readFileSync(outputPath, 'utf-8')).toBe('old json\n');
+ expect(readFileSync(markdownPath, 'utf-8')).toBe('old markdown\n');
+ expect(readFileSync(sentinelPath, 'utf-8')).toBe('unrelated\n');
+ expect(readdirSync(reportsDirectory).sort()).toEqual(entriesBefore);
+ });
+
+ it('removes an owned partial temp when a staging write fails', () => {
+ const root = mkdtempSync(join(tmpdir(), 'ua report partial write-'));
+ cleanup.push(root);
+ const reportsDirectory = join(root, 'reports');
+ const outputPath = join(reportsDirectory, 'result.json');
+ const markdownPath = join(reportsDirectory, 'result.md');
+ mkdirSync(reportsDirectory);
+ writeFileSync(outputPath, 'old json\n');
+ writeFileSync(markdownPath, 'old markdown\n');
+ const entriesBefore = readdirSync(reportsDirectory).sort();
+ let injectedFailure = false;
+ let deliveryError;
+
+ try {
+ benchmark.deliverBenchmarkReports(
+ {
+ outputPath,
+ markdownPath,
+ jsonContents: 'new json\n',
+ markdownContents: 'new markdown\n',
+ },
+ {
+ writeFileSync(path, contents, options) {
+ writeFileSync(path, contents.slice(0, 1), options);
+ injectedFailure = true;
+ throw new Error(`ENOSPC while writing ${path}`);
+ },
+ },
+ );
+ } catch (error) {
+ deliveryError = error;
+ }
+
+ expect(injectedFailure).toBe(true);
+ expect(deliveryError).toBeInstanceOf(benchmark.BenchmarkReportWriteError);
+ expect(deliveryError).not.toHaveProperty('cause');
+ expect(deliveryError.message).not.toContain(root);
+ expect(deliveryError.message).not.toContain('ENOSPC');
+ expect(readFileSync(outputPath, 'utf-8')).toBe('old json\n');
+ expect(readFileSync(markdownPath, 'utf-8')).toBe('old markdown\n');
+ expect(readdirSync(reportsDirectory).sort()).toEqual(entriesBefore);
+ });
+
+ it('handles an existing directory at the JSON report path without leaking artifacts', () => {
+ const { root, subject } = makeSubject();
+ cleanup.push(root);
+ const reportPath = join(root, 'reports', 'result.json');
+ const sentinelPath = join(reportPath, 'sentinel.txt');
+ mkdirSync(reportPath, { recursive: true });
+ writeFileSync(sentinelPath, 'keep me\n');
+ const artifactsBefore = benchmarkArtifactEntries();
+
+ const result = runCli([subject, '--output', reportPath]);
+
+ expectSafeReportWriteFailure(result, [
+ subject,
+ benchmark.REPO_ROOT,
+ reportPath,
+ ]);
+ expect(benchmarkArtifactEntries()).toEqual(artifactsBefore);
+ expect(readFileSync(sentinelPath, 'utf-8')).toBe('keep me\n');
+ }, 70_000);
+
+ it('preflights an existing Markdown directory before writing the JSON report', () => {
+ const { root, subject } = makeSubject();
+ cleanup.push(root);
+ const reportPath = join(root, 'reports', 'result.json');
+ const markdownPath = join(root, 'reports', 'result.md');
+ const sentinelPath = join(markdownPath, 'sentinel.txt');
+ mkdirSync(markdownPath, { recursive: true });
+ writeFileSync(sentinelPath, 'keep me too\n');
+ const artifactsBefore = benchmarkArtifactEntries();
+
+ const result = runCli([subject, '--output', reportPath]);
+
+ expectSafeReportWriteFailure(result, [
+ subject,
+ benchmark.REPO_ROOT,
+ reportPath,
+ markdownPath,
+ ]);
+ expect(benchmarkArtifactEntries()).toEqual(artifactsBefore);
+ expect(existsSync(reportPath)).toBe(false);
+ expect(readFileSync(sentinelPath, 'utf-8')).toBe('keep me too\n');
+ }, 70_000);
+
+ it('preserves but does not print artifacts when report delivery fails with keep-artifacts', () => {
+ const { root, subject } = makeSubject();
+ cleanup.push(root);
+ const reportPath = join(root, 'reports', 'result.json');
+ mkdirSync(reportPath, { recursive: true });
+ const artifactsBefore = benchmarkArtifactEntries();
+
+ const result = runCli([
+ subject,
+ '--output',
+ reportPath,
+ '--keep-artifacts',
+ ]);
+ const newArtifactEntries = benchmarkArtifactEntries().filter(
+ (entry) => !artifactsBefore.includes(entry),
+ );
+ for (const entry of newArtifactEntries) {
+ cleanup.push(join(tmpdir(), entry));
+ }
+
+ expectSafeReportWriteFailure(result, [
+ subject,
+ benchmark.REPO_ROOT,
+ reportPath,
+ ]);
+ expect(newArtifactEntries).toHaveLength(1);
+ expect(existsSync(join(tmpdir(), newArtifactEntries[0]))).toBe(true);
+ }, 70_000);
+
+ it('exposes a preserved artifact root as report delivery error metadata', async () => {
+ const { root, subject } = makeSubject();
+ cleanup.push(root);
+ const reportPath = join(root, 'reports', 'result.json');
+ mkdirSync(reportPath, { recursive: true });
+ const options = parseArgs(
+ [subject, '--output', reportPath, '--keep-artifacts'],
+ root,
+ );
+ const artifactsBefore = benchmarkArtifactEntries();
+ let deliveryError;
+
+ try {
+ await benchmark.runBenchmark(options);
+ } catch (error) {
+ deliveryError = error;
+ }
+ const newArtifactEntries = benchmarkArtifactEntries().filter(
+ (entry) => !artifactsBefore.includes(entry),
+ );
+ for (const entry of newArtifactEntries) {
+ cleanup.push(join(tmpdir(), entry));
+ }
+
+ expect(deliveryError).toBeInstanceOf(benchmark.BenchmarkReportWriteError);
+ expect(newArtifactEntries).toHaveLength(1);
+ expect(deliveryError).toMatchObject({
+ message: 'Unable to write benchmark report files',
+ artifactRoot: join(tmpdir(), newArtifactEntries[0]),
+ });
+ expect(existsSync(deliveryError.artifactRoot)).toBe(true);
+ }, 70_000);
+
+ it('runs all deterministic stages without writing into the subject repo', () => {
+ const { root, subject } = makeSubject();
+ cleanup.push(root);
+ const reportPath = join(root, 'reports', 'result.json');
+ const markdownPath = join(root, 'reports', 'result.md');
+ const secondReportPath = join(root, 'reports', 'result-second.json');
+ mkdirSync(join(subject, '.ua'), { recursive: true });
+ mkdirSync(join(subject, '.understand-anything'), { recursive: true });
+ writeFileSync(join(subject, '.ua', 'sentinel.txt'), 'keep me\n');
+ writeFileSync(
+ join(subject, '.understand-anything', 'sentinel.txt'),
+ 'keep me too\n',
+ );
+ const before = snapshotTree(subject);
+
+ const result = runCli(
+ [
+ subject,
+ '--output',
+ reportPath,
+ '--label',
+ 'polyglot-mini',
+ '--concurrency',
+ '2',
+ ],
+ );
+
+ expect(result.status, result.stderr).toBe(0);
+ expect(existsSync(reportPath)).toBe(true);
+ expect(existsSync(markdownPath)).toBe(true);
+ expect(snapshotTree(subject)).toEqual(before);
+
+ const report = JSON.parse(readFileSync(reportPath, 'utf-8'));
+ const schema = JSON.parse(readFileSync(REPORT_SCHEMA, 'utf-8'));
+ const markdown = readFileSync(markdownPath, 'utf-8');
+ expectValidReport(report);
+ expect(report.schemaUrl).toBe(schema.$id);
+ expect(report.schemaVersion).toBe('1.0.0');
+ expect(report.status).toBe('ok');
+ expect(report.mode).toBe('deterministic');
+ expect(report.subject).toEqual({
+ label: 'polyglot-mini',
+ commit: null,
+ dirty: null,
+ });
+ expect(report.scale.files).toBe(3);
+ expect(report.scale.lines).toBeGreaterThan(0);
+ expect(report.stages.scan.status).toBe('ok');
+ expect(report.stages.imports.edges).toBe(1);
+ expect(report.stages.batching.totalBatches).toBeGreaterThan(0);
+ expect(report.stages.structure.filesAnalyzed).toBe(3);
+ expect(report.stages.structure.maxWorkerPeakRssBytes).toBeGreaterThan(0);
+ expect(report.stages.structure.userCpuTimeMicros).toBeGreaterThanOrEqual(0);
+ expect(report.stages.structure.systemCpuTimeMicros).toBeGreaterThanOrEqual(0);
+ expect(report.stages.structure).not.toHaveProperty('peakRssBytes');
+ expect(report.integrity.allScannedFilesBatched).toBe(true);
+ expect(report.integrity.structureCoverage).toBe(1);
+ expect(report.llm.invoked).toBe(false);
+ expect(report.determinism.inputDigest).toMatch(/^[a-f0-9]{64}$/);
+ expect(report.determinism.outputDigest).toMatch(/^[a-f0-9]{64}$/);
+ expect(JSON.stringify(report)).not.toContain(subject);
+ expect(markdown).toContain('# Large Repository Benchmark Report');
+ expect(markdown).toContain('| Files | 3 |');
+ expect(markdown).toContain('| LLM invoked | No |');
+ expect(markdown).toContain('Peak / max worker RSS (bytes)');
+ expect(markdown).not.toContain(subject);
+
+ const secondResult = runCli([
+ subject,
+ '--output',
+ secondReportPath,
+ '--label',
+ 'polyglot-mini',
+ '--concurrency',
+ '1',
+ ]);
+ expect(secondResult.status, secondResult.stderr).toBe(0);
+ expect(snapshotTree(subject)).toEqual(before);
+ const secondReport = JSON.parse(readFileSync(secondReportPath, 'utf-8'));
+ expect(report.configuration.concurrency).toBe(2);
+ expect(secondReport.configuration.concurrency).toBe(1);
+ expect(secondReport.scale).toEqual(report.scale);
+ expect(secondReport.integrity).toEqual(report.integrity);
+ expect(secondReport.determinism).toEqual(report.determinism);
+ expect(secondReport.stages.batching.batchSizes).toEqual(
+ report.stages.batching.batchSizes,
+ );
+ }, 70_000);
+
+ it('handles an empty repository as a valid deterministic run', () => {
+ const root = mkdtempSync(join(tmpdir(), 'ua empty benchmark-'));
+ cleanup.push(root);
+ const subject = join(root, 'empty subject');
+ const reportPath = join(root, 'empty.json');
+ mkdirSync(subject);
+
+ const result = runCli([subject, '--output', reportPath]);
+
+ expect(result.status, result.stderr).toBe(0);
+ const report = JSON.parse(readFileSync(reportPath, 'utf-8'));
+ expectValidReport(report);
+ expect(report.status).toBe('ok');
+ expect(report.scale.files).toBe(0);
+ expect(report.stages.batching.totalBatches).toBe(0);
+ expect(report.stages.structure.batchesSucceeded).toBe(0);
+ expect(report.integrity.structureCoverage).toBe(1);
+ }, 70_000);
+
+ it('degrades for an accounted skip and uses the scan content digest', async () => {
+ const { root, subject } = makeSubject();
+ cleanup.push(root);
+ const reportPath = join(root, 'reports', 'degraded.json');
+ const options = parseArgs(
+ [subject, '--output', reportPath, '--keep-artifacts'],
+ root,
+ );
+ let removedAtStructure = false;
+
+ const result = await benchmark.runBenchmark(options, {
+ onProgress(stage) {
+ if (stage === 'structure') {
+ rmSync(join(subject, 'src', 'math.ts'));
+ removedAtStructure = true;
+ }
+ },
+ });
+ cleanup.push(result.artifactRoot);
+ const scan = JSON.parse(
+ readFileSync(join(result.artifactRoot, 'scan-result.json'), 'utf-8'),
+ );
+
+ expect(removedAtStructure).toBe(true);
+ expect(result.exitCode).toBe(0);
+ expect(result.report.status).toBe('degraded');
+ expectValidReport(result.report);
+ expect(result.report.integrity).toMatchObject({
+ structureCoverage: 1,
+ filesSkipped: 1,
+ failedBatches: 0,
+ missingStructurePaths: 0,
+ duplicateStructurePaths: 0,
+ unexpectedStructurePaths: 0,
+ malformedStructureBatches: 0,
+ });
+ expect(result.report.determinism.inputDigest).toBe(scan.contentDigest);
+ }, 70_000);
+
+ it('changes the input digest when source bytes change but scan counts do not', () => {
+ const { root, subject } = makeSubject();
+ cleanup.push(root);
+ const firstReportPath = join(root, 'digest-first.json');
+ const secondReportPath = join(root, 'digest-second.json');
+
+ const firstResult = runCli([subject, '--output', firstReportPath]);
+ expect(firstResult.status, firstResult.stderr).toBe(0);
+ const firstReport = JSON.parse(readFileSync(firstReportPath, 'utf-8'));
+
+ writeFileSync(
+ join(subject, 'src', 'math.ts'),
+ 'export function add(a: number, b: number) { return a - b; }\n',
+ );
+ const secondResult = runCli([subject, '--output', secondReportPath]);
+ expect(secondResult.status, secondResult.stderr).toBe(0);
+ const secondReport = JSON.parse(readFileSync(secondReportPath, 'utf-8'));
+
+ expect(secondReport.scale.files).toBe(firstReport.scale.files);
+ expect(secondReport.scale.lines).toBe(firstReport.scale.lines);
+ expect(secondReport.scale.bytes).toBe(firstReport.scale.bytes);
+ expect(secondReport.determinism.inputDigest).not.toBe(
+ firstReport.determinism.inputDigest,
+ );
+ }, 70_000);
+
+ it('returns usage errors without creating reports', () => {
+ const root = mkdtempSync(join(tmpdir(), 'ua benchmark usage-'));
+ cleanup.push(root);
+ const reportPath = join(root, 'should-not-exist.json');
+
+ const help = runCli(['--help']);
+ expect(help.status).toBe(0);
+ expect(help.stdout).toContain('Usage:');
+
+ const invalid = runCli([
+ '--repo',
+ join(root, 'missing'),
+ '--output',
+ reportPath,
+ ]);
+ expect(invalid.status).toBe(2);
+ expect(invalid.stderr).toContain('Repository path does not exist');
+ expect(existsSync(reportPath)).toBe(false);
+ });
+});
diff --git a/tests/benchmark/test_large_repo_report_schema.test.mjs b/tests/benchmark/test_large_repo_report_schema.test.mjs
new file mode 100644
index 00000000..2355f90c
--- /dev/null
+++ b/tests/benchmark/test_large_repo_report_schema.test.mjs
@@ -0,0 +1,263 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
+import { describe, expect, it } from 'vitest';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const schemaPath = resolve(
+ __dirname,
+ '../../docs/benchmarks/large-repo-report-1.0.0.schema.json',
+);
+const schema = JSON.parse(readFileSync(schemaPath, 'utf-8'));
+const validateReport = new Ajv2020({
+ allErrors: true,
+ formats: { 'date-time': true },
+}).compile(schema);
+
+function expectValid(report) {
+ expect(
+ validateReport(report),
+ JSON.stringify(validateReport.errors, null, 2),
+ ).toBe(true);
+}
+
+function expectInvalid(report) {
+ expect(validateReport(report)).toBe(false);
+}
+
+function regularStage(overrides = {}) {
+ return {
+ status: 'ok',
+ durationMs: 1,
+ peakRssBytes: 1024,
+ userCpuTimeMicros: 10,
+ systemCpuTimeMicros: 5,
+ warningCount: 0,
+ warningMessages: [],
+ warningMessagesTruncated: false,
+ stdoutTruncated: false,
+ stderrTruncated: false,
+ outputBytes: 128,
+ ...overrides,
+ };
+}
+
+function validReport() {
+ return {
+ schemaUrl: schema.$id,
+ schemaVersion: '1.0.0',
+ status: 'ok',
+ mode: 'deterministic',
+ run: {
+ startedAt: '2026-01-01T00:00:00.000Z',
+ finishedAt: '2026-01-01T00:00:01.000Z',
+ durationMs: 1000,
+ },
+ tool: {
+ commit: null,
+ dirty: null,
+ packageVersion: '0.1.0',
+ },
+ subject: {
+ label: 'fixture',
+ commit: null,
+ dirty: null,
+ },
+ environment: {
+ platform: 'linux',
+ release: 'test',
+ arch: 'x64',
+ nodeVersion: 'v22.0.0',
+ cpuModel: 'test',
+ logicalCores: 1,
+ totalMemoryBytes: 1024,
+ },
+ configuration: {
+ concurrency: 1,
+ stages: ['scan', 'imports', 'batching', 'structure'],
+ },
+ scale: {
+ files: 1,
+ lines: 1,
+ bytes: 1,
+ missingFiles: 0,
+ filteredByUserIgnore: 0,
+ byCategory: { code: 1 },
+ byLanguage: { JavaScript: 1 },
+ },
+ stages: {
+ scan: regularStage({
+ files: 1,
+ lines: 1,
+ bytes: 1,
+ filteredByUserIgnore: 0,
+ }),
+ imports: regularStage({
+ filesScanned: 1,
+ filesWithImports: 0,
+ edges: 0,
+ }),
+ batching: regularStage({
+ algorithm: 'semantic-v1',
+ totalBatches: 1,
+ batchSizes: { min: 1, p50: 1, p95: 1, max: 1, mean: 1 },
+ estimatedAgentInputBytes: 1,
+ }),
+ structure: {
+ status: 'ok',
+ durationMs: 1,
+ maxWorkerPeakRssBytes: 1024,
+ userCpuTimeMicros: 10,
+ systemCpuTimeMicros: 5,
+ warningCount: 0,
+ warningMessages: [],
+ warningMessagesTruncated: false,
+ outputBytes: 128,
+ batchesSucceeded: 1,
+ batchesFailed: 0,
+ filesAnalyzed: 1,
+ filesSkipped: 0,
+ entities: {
+ functions: 0,
+ classes: 0,
+ exports: 0,
+ callGraph: 0,
+ definitions: 0,
+ services: 0,
+ endpoints: 0,
+ steps: 0,
+ resources: 0,
+ },
+ batchDurationMs: { min: 1, p50: 1, p95: 1, max: 1, mean: 1 },
+ },
+ },
+ integrity: {
+ allScannedFilesBatched: true,
+ missingBatchFiles: 0,
+ duplicateBatchFiles: 0,
+ unexpectedBatchFiles: 0,
+ missingImportTargets: 0,
+ structureCoverage: 1,
+ filesSkipped: 0,
+ failedBatches: 0,
+ missingStructurePaths: 0,
+ duplicateStructurePaths: 0,
+ unexpectedStructurePaths: 0,
+ malformedStructureBatches: 0,
+ },
+ determinism: {
+ algorithm: 'sha256',
+ inputDigest: '0'.repeat(64),
+ outputDigest: '1'.repeat(64),
+ },
+ llm: {
+ invoked: false,
+ inputTokens: null,
+ outputTokens: null,
+ costUsd: null,
+ },
+ warnings: [],
+ error: null,
+ };
+}
+
+describe('large repository report schema 1.0.0', () => {
+ it('accepts a complete ok report and a derived valid degraded report', () => {
+ const ok = validReport();
+ const degraded = structuredClone(ok);
+ degraded.status = 'degraded';
+ degraded.stages.structure.filesAnalyzed = 0;
+ degraded.stages.structure.filesSkipped = 1;
+ degraded.integrity.filesSkipped = 1;
+
+ expectValid(ok);
+ expectValid(degraded);
+ });
+
+ it.each([
+ [
+ 'an incomplete ok report',
+ (report) => {
+ delete report.stages.structure;
+ },
+ ],
+ [
+ 'the old warning shape',
+ (report) => {
+ report.status = 'degraded';
+ report.warnings = [{ stage: 'scan', count: 1 }];
+ },
+ ],
+ [
+ 'the old structure memory field',
+ (report) => {
+ report.stages.structure.peakRssBytes =
+ report.stages.structure.maxWorkerPeakRssBytes;
+ delete report.stages.structure.maxWorkerPeakRssBytes;
+ },
+ ],
+ [
+ 'a failed report with a null error',
+ (report) => {
+ report.status = 'failed';
+ },
+ ],
+ ])('rejects %s', (_name, mutate) => {
+ const report = validReport();
+ mutate(report);
+ expectInvalid(report);
+ });
+
+ it.each([
+ [
+ 'warnings',
+ (report) => {
+ report.warnings = [
+ { stage: 'scan', count: 1, messages: ['warning'], truncated: false },
+ ];
+ },
+ ],
+ [
+ 'skipped files',
+ (report) => {
+ report.integrity.filesSkipped = 1;
+ },
+ ],
+ [
+ 'a stage warning',
+ (report) => {
+ report.stages.scan.warningCount = 1;
+ report.stages.scan.warningMessages = ['warning'];
+ },
+ ],
+ [
+ 'a stage-level skipped file',
+ (report) => {
+ report.stages.structure.filesSkipped = 1;
+ },
+ ],
+ ])('rejects ok status with %s', (_name, mutate) => {
+ const report = validReport();
+ mutate(report);
+ expectInvalid(report);
+ });
+
+ it.each([
+ ['allScannedFilesBatched', false],
+ ['missingBatchFiles', 1],
+ ['duplicateBatchFiles', 1],
+ ['unexpectedBatchFiles', 1],
+ ['missingImportTargets', 1],
+ ['structureCoverage', 0.5],
+ ['failedBatches', 1],
+ ['missingStructurePaths', 1],
+ ['duplicateStructurePaths', 1],
+ ['unexpectedStructurePaths', 1],
+ ['malformedStructureBatches', 1],
+ ])('rejects successful status with failing integrity %s', (field, value) => {
+ const report = validReport();
+ report.integrity[field] = value;
+ expectInvalid(report);
+ });
+});