@maverickcer/env-cap 0.6.0 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. package/ADOPTION.md +144 -0
  2. package/AGENTS.md +146 -0
  3. package/CHANGELOG.md +449 -0
  4. package/CODE_OF_CONDUCT.md +124 -0
  5. package/CODE_REVIEW.md +200 -0
  6. package/CONTRIBUTING.md +131 -0
  7. package/GUIDE.md +1214 -0
  8. package/PROMPT.md +89 -0
  9. package/README.md +92 -200
  10. package/RELEASING.md +160 -0
  11. package/SECURITY.md +270 -0
  12. package/SUPPORT.md +76 -0
  13. package/VERSIONING.md +118 -0
  14. package/benchmarks/READING-BENCHMARKS.md +197 -0
  15. package/benchmarks/README.md +126 -0
  16. package/benchmarks/WRITING-BENCHMARKS.md +252 -0
  17. package/benchmarks/performance-buildtime/BENCHMARKS.md +889 -0
  18. package/benchmarks/performance-runtime/BENCHMARKS.md +1988 -0
  19. package/dist/.dts/_ipc/build-fs.d.ts +53 -0
  20. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -0
  21. package/dist/.dts/_ipc/compiler-api.d.ts +17 -0
  22. package/dist/.dts/_ipc/compiler-api.d.ts.map +1 -0
  23. package/dist/.dts/_ipc/display-path.d.ts +27 -0
  24. package/dist/.dts/_ipc/display-path.d.ts.map +1 -0
  25. package/dist/.dts/_ipc/generated-banner.d.ts +58 -0
  26. package/dist/.dts/_ipc/generated-banner.d.ts.map +1 -0
  27. package/dist/.dts/_ipc/glob.d.ts +22 -0
  28. package/dist/.dts/_ipc/glob.d.ts.map +1 -0
  29. package/dist/.dts/_ipc/no-node-fs.d.ts +35 -0
  30. package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -0
  31. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +134 -0
  32. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
  33. package/dist/.dts/_ipc/typescript.d.ts +20 -0
  34. package/dist/.dts/_ipc/typescript.d.ts.map +1 -0
  35. package/dist/.dts/build/compatibility.d.ts.map +1 -1
  36. package/dist/.dts/build/compiler-api.d.ts +3 -6
  37. package/dist/.dts/build/compiler-api.d.ts.map +1 -1
  38. package/dist/.dts/build/display-path.d.ts +3 -21
  39. package/dist/.dts/build/display-path.d.ts.map +1 -1
  40. package/dist/.dts/build/generated-banner.d.ts +21 -42
  41. package/dist/.dts/build/generated-banner.d.ts.map +1 -1
  42. package/dist/.dts/build/glob.d.ts +3 -15
  43. package/dist/.dts/build/glob.d.ts.map +1 -1
  44. package/dist/.dts/build/index.d.ts +3 -3
  45. package/dist/.dts/build/link.d.ts.map +1 -1
  46. package/dist/.dts/build/merge-documentation.d.ts +35 -0
  47. package/dist/.dts/build/merge-documentation.d.ts.map +1 -0
  48. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +11 -112
  49. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
  50. package/dist/.dts/build/types.d.ts +4 -53
  51. package/dist/.dts/build/types.d.ts.map +1 -1
  52. package/dist/.dts/build/typescript.d.ts +3 -17
  53. package/dist/.dts/build/typescript.d.ts.map +1 -1
  54. package/dist/.dts/eslint-plugin/glob.d.ts +4 -15
  55. package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -1
  56. package/dist/.dts/eslint-plugin/index.d.ts +1 -1
  57. package/dist/.dts/eslint-plugin/no-node-fs.d.ts +8 -18
  58. package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -1
  59. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -1
  60. package/dist/{build-H4KFV44Z.js → build-F3RQS7VE.js} +218 -63
  61. package/dist/build-F3RQS7VE.js.map +1 -0
  62. package/dist/build.cjs +257 -102
  63. package/dist/build.cjs.map +1 -1
  64. package/dist/build.js +256 -101
  65. package/dist/build.js.map +1 -1
  66. package/dist/{chunk-7GVPOHDU.js → chunk-QKIQ3LZP.js} +2 -2
  67. package/dist/cli/index.js +36 -29
  68. package/dist/cli/index.js.map +1 -1
  69. package/dist/eslint-plugin/index.cjs +95 -54
  70. package/dist/eslint-plugin/index.cjs.map +1 -1
  71. package/dist/eslint-plugin/index.js +94 -53
  72. package/dist/eslint-plugin/index.js.map +1 -1
  73. package/examples/README.md +95 -0
  74. package/package.json +53 -19
  75. package/skills/env-cap/SKILL.md +91 -0
  76. package/skills/env-cap/references/api.md +220 -0
  77. package/specs/architecture.md +634 -0
  78. package/specs/decisions/0001-runtime-documentation-separation.md +197 -0
  79. package/specs/decisions/0002-static-analysis-never-execution.md +233 -0
  80. package/specs/decisions/0003-no-global-env-object.md +172 -0
  81. package/specs/decisions/0004-no-client-server-package-split.md +116 -0
  82. package/specs/decisions/0005-warn-not-throw-by-default.md +93 -0
  83. package/specs/decisions/0006-self-redacting-contracts.md +124 -0
  84. package/specs/decisions/0007-processor-not-transformer.md +109 -0
  85. package/specs/decisions/0008-gzip-size-budget.md +173 -0
  86. package/specs/decisions/0009-exclusive-groups-are-always-errors.md +139 -0
  87. package/specs/decisions/0010-dependency-ownership-engine-scope-boundary.md +100 -0
  88. package/specs/decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md +104 -0
  89. package/specs/decisions/0012-live-expiration-overrides-not-ast-functions.md +145 -0
  90. package/specs/decisions/0013-json-output-is-a-versioned-mirror.md +136 -0
  91. package/specs/decisions/0014-cross-package-schema-discovery.md +206 -0
  92. package/specs/decisions/0015-security-backport-window.md +60 -0
  93. package/specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md +113 -0
  94. package/specs/decisions/0017-eslint-plugin-entry-point.md +113 -0
  95. package/specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md +104 -0
  96. package/specs/decisions/0019-published-json-schema-generated-from-types.md +100 -0
  97. package/specs/decisions/0020-declaration-maps-via-separate-tsc-pass.md +101 -0
  98. package/specs/decisions/0021-manifest-change-report-persisted-snapshot.md +177 -0
  99. package/specs/decisions/0022-validation-contexts.md +267 -0
  100. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +182 -0
  101. package/specs/decisions/0024-fact-model-architecture.md +144 -0
  102. package/specs/decisions/0025-contract-model-json-projection.md +105 -0
  103. package/specs/decisions/0026-finding-model-unifies-four-families.md +109 -0
  104. package/specs/decisions/0027-dependency-model-fact-shape-not-engine-access.md +98 -0
  105. package/specs/decisions/0028-ownership-model-shared-effective-owner.md +85 -0
  106. package/specs/decisions/0029-lifecycle-model-deprecation-rename-fields.md +98 -0
  107. package/specs/decisions/0030-change-model-wraps-manifest-change-report.md +97 -0
  108. package/specs/decisions/0031-evidence-entry-point.md +85 -0
  109. package/specs/decisions/0032-evidence-projection-provenance-mechanism.md +120 -0
  110. package/specs/decisions/0033-reference-projections-live-in-examples.md +81 -0
  111. package/specs/decisions/0034-three-tier-examples-restructuring.md +85 -0
  112. package/specs/decisions/0035-documentenv-metadata-generalization-and-compliance-fields.md +85 -0
  113. package/specs/decisions/0036-exact-source-position-evidence.md +122 -0
  114. package/specs/decisions/0037-developer-declared-dynamic-access-citations.md +114 -0
  115. package/specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md +244 -0
  116. package/specs/decisions/0039-scanner-local-dataflow-boundary.md +160 -0
  117. package/specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md +156 -0
  118. package/specs/decisions/0041-dual-package-hazard-checked-documented.md +75 -0
  119. package/specs/decisions/0042-init-cli-subcommand-scaffolds-only.md +95 -0
  120. package/specs/decisions/0043-env-cap-resolver-relocated-and-duplicated.md +71 -0
  121. package/specs/decisions/0044-strict-escalates-every-warning-family.md +88 -0
  122. package/specs/decisions/0045-promote-experimental-surfaces-to-stable.md +103 -0
  123. package/specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md +177 -0
  124. package/specs/decisions/0047-supported-toolchain-node-22-and-typescript-5-6.md +30 -0
  125. package/specs/decisions/0048-eslint-plugin-does-not-vendor-typescript-eslint.md +25 -0
  126. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +87 -0
  127. package/specs/decisions/0050-a-variable-declared-twice-is-documented-once.md +55 -0
  128. package/specs/generated-artifacts.md +104 -0
  129. package/specs/migrations/README.md +30 -0
  130. package/specs/migrations/from-centralized-schema.md +503 -0
  131. package/specs/migrations/from-dotenv.md +352 -0
  132. package/specs/migrations/from-envalid.md +482 -0
  133. package/specs/migrations/from-process-env.md +398 -0
  134. package/specs/migrations/from-t3-env.md +416 -0
  135. package/specs/migrations/from-zod.md +303 -0
  136. package/dist/build-H4KFV44Z.js.map +0 -1
  137. /package/dist/{chunk-7GVPOHDU.js.map → chunk-QKIQ3LZP.js.map} +0 -0
@@ -0,0 +1,889 @@
1
+ # env-cap: performance and cost report
2
+
3
+ What does adopting this package add to latency, CPU, memory and compute spend -- and how does that grow with workload? Three views, from the whole to the part: **(1)** the end-to-end total, **(2)** every function on its own, **(3)** which functions make up the total. New to benchmarks? Read [READING-BENCHMARKS.md](../READING-BENCHMARKS.md) first.
4
+
5
+ ## What adopting this package costs
6
+
7
+ For a typical workload of **640 variables** per operation, routing the work through `env-cap` adds **139 ms** per operation compared with a bare-minimum baseline (**20× the baseline**). Overall, it grows O(n) with workload size (measured exponent 0.90). At list prices that is on the order of **~$0.1 – $10 per million operations** of compute.
8
+
9
+ > The relative figure and the growth class are the steadier ones: both come from the same run, so they depend far less on the machine than a time does, though runtime behaviour and contention on the runner still move them. The growth class is an empirical fit to the sizes tested, not a proof of asymptotic complexity. Dollar figures are **order-of-magnitude** estimates from published list prices on shared hardware (see _Cost model_ below) -- good for comparing one package with another, not for budgeting.
10
+
11
+ | Cost | Typical (640 variables) | Largest (5120 variables) |
12
+ | --- | --- | --- |
13
+ | Added latency per operation | 139 ms | 1.08 s |
14
+ | Added latency, relative to baseline | 20× baseline | 19× baseline |
15
+ | Added CPU time per operation | 328 ms | 1.50 s |
16
+ | Added memory per operation (heap delta) | 9.4 MiB | 95.4 MiB |
17
+ | Compute cost per 1M operations (order of magnitude) | ~$0.1 – $10 | ~$1 – $10 |
18
+ | Single-core throughput ceiling of the overhead alone | 7 ops/s | 1 ops/s |
19
+ | Shipped code parsed at every cold start (gzip) | 42.4 KiB | 42.4 KiB |
20
+
21
+ ## 1. End-to-end: the package's total impact
22
+
23
+ Shows what a pipeline run or a developer pays to regenerate every env-cap artifact (manifest, documentation and usage report) for a project, compared with the bare minimum of just reading every schema file. The baseline is the unavoidable floor -- the files must at least be read -- so the difference is env-cap's parsing, linking and rendering. This is CI and development time, paid on every build, not request-time cost.
24
+
25
+ - **Baseline (no package):** Walk the project directory and read every schema file as text -- no env-cap.
26
+ - **With the package:** `generateEnvArtifacts` discovers, parses and links every schema once and writes the manifest, the documentation and the usage report.
27
+
28
+ Both sides use empty or minimal functions on purpose, so the difference is the package's own cost -- not the cost of the work an application would plug into it. Real applications add their own work on top; this is the floor the package imposes.
29
+
30
+ **Variables that could change this result**
31
+
32
+ | Variable | How it is handled | What it is |
33
+ | --- | --- | --- |
34
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
35
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
36
+ | filesystem | fixed at "local SSD through the Node adapter" | A network or virtual filesystem adds latency per file; not covered. |
37
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
38
+ | artifacts requested | fixed at "manifest + docs + usage report" | Requesting fewer artifacts costs less; each standalone generator is measured below. |
39
+ | cache state | fixed at "no incremental cache" | Every run parses from scratch; the tooling keeps no build cache. |
40
+
41
+ The baseline is an empty or minimal function, so it costs almost nothing and the _relative_ overhead can look enormous (shown as a multiple of the baseline). Read the absolute columns -- time, CPU and dollars added -- they are what a bill and a latency budget are made of.
42
+
43
+ | variables | Baseline | With package | Added | Added vs baseline | Added CPU | Est. $ / 1M ops |
44
+ | --- | --- | --- | --- | --- | --- | --- |
45
+ | 20 | 751 µs | 17.1 ms | 16.3 ms | 23× baseline | 48.9 ms | $0.034 – $0.549 |
46
+ | 40 | 1.03 ms | 24.3 ms | 23.3 ms | 24× baseline | 76.0 ms | $0.049 – $0.855 |
47
+ | 80 | 1.47 ms | 33.8 ms | 32.4 ms | 23× baseline | 120 ms | $0.067 – $1.35 |
48
+ | 160 | 2.39 ms | 60.2 ms | 57.8 ms | 25× baseline | 181 ms | $0.120 – $2.04 |
49
+ | 320 | 4.40 ms | 95.1 ms | 90.7 ms | 22× baseline | 266 ms | $0.189 – $2.99 |
50
+ | 640 | 7.41 ms | 147 ms | 139 ms | 20× baseline | 328 ms | $0.290 – $3.68 |
51
+ | 1280 | 15.2 ms | 270 ms | 255 ms | 18× baseline | 540 ms | $0.531 – $6.07 |
52
+ | 2560 | 31.2 ms | 513 ms | 482 ms | 16× baseline | 801 ms | $1.00 – $9.00 |
53
+ | 5120 | 61.5 ms | 1.14 s | 1.08 s | 19× baseline | 1.50 s | $2.26 – $16.83 |
54
+
55
+ **How the total grows:** O(n) (linear), exponent 0.90 over 9 sizes.
56
+
57
+ ## 2. Function by function
58
+
59
+ Every function the package exposes is measured on its own across the full size ladder, then its measured growth rate is compared with the big-O we documented for it. A function whose measured class **differs** from its documented one is the most useful thing in this report: either the documentation or the code is wrong.
60
+
61
+ | Function | Varies | Documented | Measured | Agreement | At 640 | At 5120 |
62
+ | --- | --- | --- | --- | --- | --- | --- |
63
+ | `discoverSchemaFiles` | variable | O(n) | O(n) | ✅ matches | 3.00 ms | 20.7 ms |
64
+ | `discoverSchemaFiles` | variables-per-contract | O(1) | n/a | ❔ not enough data | n/a | n/a |
65
+ | `generateEnvManifest` (all-contracts) | variable | O(n log n) | O(n) | 🟡 close (neighbouring class) | 79.0 ms | 533 ms |
66
+ | `generateEnvManifest` (all-contracts) | variables-per-contract | O(1) | n/a | ❔ not enough data | n/a | n/a |
67
+ | `generateEnvManifest` (one-contract-scoped) | variable | O(log n) | O(log n) | ✅ matches | 5.84 ms | 23.6 ms |
68
+ | `generateEnvManifest` (one-contract-scoped) | variables-per-contract | O(1) | n/a | ❔ not enough data | n/a | n/a |
69
+ | `generateDocumentation` (minimal-docs) | variable | O(n) | O(n) | ✅ matches | 84.1 ms | 377 ms |
70
+ | `generateDocumentation` (minimal-docs) | variables-per-contract | O(1) | n/a | ❔ not enough data | n/a | n/a |
71
+ | `generateDocumentation` (heavy-docs) | variable | O(n) | O(n) | ✅ matches | 87.3 ms | 454 ms |
72
+ | `generateDocumentation` (heavy-docs) | variables-per-contract | O(1) | n/a | ❔ not enough data | n/a | n/a |
73
+ | `generateUsageReport` | variable | O(n) | O(n) | ✅ matches | 108 ms | 534 ms |
74
+ | `generateUsageReport` | variables-per-contract | O(1) | n/a | ❔ not enough data | n/a | n/a |
75
+ | `generateEnvArtifacts` | variable | O(n) | O(n) | ✅ matches | 149 ms | 1.10 s |
76
+ | `generateEnvArtifacts` | variables-per-contract | O(1) | n/a | ❔ not enough data | n/a | n/a |
77
+ | `checkEnvArtifacts` | variable | O(n) | n/a | ❔ not enough data | n/a | n/a |
78
+ | `checkEnvArtifacts` | variables-per-contract | O(1) | n/a | ❔ not enough data | n/a | n/a |
79
+ | `computeSourceFingerprint` | variable | O(n) | n/a | ❔ not enough data | n/a | n/a |
80
+ | `computeSourceFingerprint` | variables-per-contract | O(1) | n/a | ❔ not enough data | n/a | n/a |
81
+ | `generateEvidenceModel` | variable | O(n) | O(n) | ✅ matches | 141 ms | 767 ms |
82
+ | `generateEvidenceModel` | variables-per-contract | O(1) | n/a | ❔ not enough data | n/a | n/a |
83
+ | `getEvidenceModel` (cache-hit) | variable | O(n) | n/a | ❔ not enough data | n/a | n/a |
84
+ | `getEvidenceModel` (cache-miss) | variable | O(n) | n/a | ❔ not enough data | n/a | n/a |
85
+ | `parseSchemaFile` | variable | O(n) | n/a | ❔ not enough data | n/a | n/a |
86
+ | `linkFiles` | variable | O(n) | n/a | ❔ not enough data | n/a | n/a |
87
+ | `buildContractModel` | variable | O(n) | n/a | ❔ not enough data | n/a | n/a |
88
+ | `buildOwnershipModel` | variable | O(n) | n/a | ❔ not enough data | n/a | n/a |
89
+ | `buildLifecycleModel` | variable | O(n) | n/a | ❔ not enough data | n/a | n/a |
90
+ | `computeExpiringEntries` | variable | O(n) | n/a | ❔ not enough data | n/a | n/a |
91
+ | `computeSecurityReviewCounters` | variable | O(n) | n/a | ❔ not enough data | n/a | n/a |
92
+ | `renderDocs` | variable | O(n) | n/a | ❔ not enough data | n/a | n/a |
93
+ | `renderManifest` | variable | O(n) | n/a | ❔ not enough data | n/a | n/a |
94
+ | `computeReconciliation` | variable | O(n) | n/a | ❔ not enough data | n/a | n/a |
95
+ | `renderEnvExample` | variable | O(n) | n/a | ❔ not enough data | n/a | n/a |
96
+ | `groupVariablesByOwner` | variable | O(n) | n/a | ❔ not enough data | n/a | n/a |
97
+ | `applyLiveExpirationOverrides` | variable | O(n) | n/a | ❔ not enough data | n/a | n/a |
98
+ | `resolveLiveExpirationDates` | variable | O(n) | n/a | ❔ not enough data | n/a | n/a |
99
+ | `configurationReference` | variable | O(n) | n/a | ❔ not enough data | n/a | n/a |
100
+ | `expiringSoonReport` | variable | O(n) | n/a | ❔ not enough data | n/a | n/a |
101
+ | `ownershipSummary` | variable | O(n) | n/a | ❔ not enough data | n/a | n/a |
102
+ | `buildSarifLog` | variable | O(n) | n/a | ❔ not enough data | n/a | n/a |
103
+ | `defineEvidenceProjection (project)` | variable | O(n) | O(n) | ✅ matches | 12.2 ms | 124 ms |
104
+
105
+ ### `discoverSchemaFiles`
106
+
107
+ **Why we benchmark it.** Every build-time command starts by finding the project's schema files, so its cost is paid first by every generator and every CI run.
108
+
109
+ **What poor performance would mean.** Every pipeline step that touches env-cap starts later, and a super-linear regression would slow monorepos with thousands of files before any real work begins.
110
+
111
+ **Expected growth: O(n).** It walks the directory tree once and tests each path against the include and exclude patterns, so cost is proportional to the number of files visited.
112
+
113
+ **Variables that could change its cost**
114
+
115
+ | Variable | How it is handled | What it is |
116
+ | --- | --- | --- |
117
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
118
+ | variables-per-contract | swept | How many variables each schema file declares (ten in the main sweep). With the total fixed, few large contracts or many small ones cost differently: per-file work (open, parse, link) against per-variable work. |
119
+ | filesystem | fixed at "local SSD through the Node adapter" | A network or virtual filesystem adds latency per file; not covered. |
120
+ | directory depth | fixed at "one level of contract folders" | Deeper trees add a directory read per level. |
121
+ | unrelated files | fixed at "none" | Real repositories hold many non-schema files that must also be walked; a pure schema tree is the best case. |
122
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
123
+
124
+ **In the end-to-end run:** Once at the start of every artifact generation.
125
+
126
+ **Measured: O(n)** (exponent 0.88, 9 sizes) -- ✅ matches.
127
+
128
+ | variables | Median | p95 | CPU (median) | Heap Δ | Ops/s |
129
+ | --- | --- | --- | --- | --- | --- |
130
+ | 20 | 370 µs | 389 µs | 996 µs | 53.2 KiB | 2,706 |
131
+ | 40 | 322 µs | 327 µs | 646 µs | 87.9 KiB | 3,105 |
132
+ | 80 | 635 µs | 833 µs | 1.39 ms | 161.9 KiB | 1,576 |
133
+ | 160 | 1.11 ms | 1.64 ms | 2.47 ms | 314.0 KiB | 898 |
134
+ | 320 | 1.84 ms | 4.18 ms | 4.00 ms | 608.9 KiB | 544 |
135
+ | 640 | 3.00 ms | 4.52 ms | 4.42 ms | 1.2 MiB | 334 |
136
+ | 1280 | 5.65 ms | 6.00 ms | 9.33 ms | 2.3 MiB | 177 |
137
+ | 2560 | 10.6 ms | 11.6 ms | 15.1 ms | 4.6 MiB | 95 |
138
+ | 5120 | 20.7 ms | 22.3 ms | 25.4 ms | 9.2 MiB | 48 |
139
+
140
+ ##### Varying `variables-per-contract`
141
+
142
+ How many variables each schema file declares (ten in the main sweep). With the total fixed, few large contracts or many small ones cost differently: per-file work (open, parse, link) against per-variable work.
143
+
144
+ **Expected: O(1).** The walk visits the same total number of schema files and folders however the variables are split across them, so the split does not change the cost.
145
+
146
+ ### `generateEnvManifest`
147
+
148
+ **Why we benchmark it.** Produces the manifest the application imports at runtime; it runs in every build that ships the application.
149
+
150
+ **What poor performance would mean.** Build time grows with the amount of configuration; a regression delays every deploy that regenerates the manifest.
151
+
152
+ **Expected growth: O(n).** It discovers the files, parses each with the TypeScript parser once and renders one manifest entry per contract, so cost is proportional to the source text parsed.
153
+
154
+ **Variables that could change its cost**
155
+
156
+ | Variable | How it is handled | What it is |
157
+ | --- | --- | --- |
158
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
159
+ | variables-per-contract | swept | How many variables each schema file declares (ten in the main sweep). With the total fixed, few large contracts or many small ones cost differently: per-file work (open, parse, link) against per-variable work. |
160
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
161
+ | filesystem | fixed at "local SSD through the Node adapter" | A network or virtual filesystem adds latency per file; not covered. |
162
+ | scope | variant | All contracts versus a single contract selected with `include`. |
163
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
164
+
165
+ **Deliberately not covered**
166
+
167
+ - **incompatible schemas** -- Files the parser cannot handle take a warning path; the benchmark uses only supported schemas.
168
+
169
+ #### Variant `all-contracts`
170
+
171
+ The manifest covers every schema file in the project.
172
+
173
+ **Expected for this variant: O(n log n).** Parsing and rendering are linear in the source text, but the model sorts every variable and declaration by key (contract-model.ts, compatibility.ts) so the manifest and the compatibility findings are stable, and that sort adds an n log n term that shows once the whole project is covered.
174
+
175
+ **Measured: O(n)** (exponent 0.89, 9 sizes) -- 🟡 close (neighbouring class).
176
+
177
+ | variables | Median | p95 | CPU (median) | Heap Δ | Ops/s |
178
+ | --- | --- | --- | --- | --- | --- |
179
+ | 20 | 5.01 ms | 8.86 ms | 12.9 ms | 1.1 MiB | 200 |
180
+ | 40 | 7.33 ms | 12.9 ms | 19.2 ms | 2.1 MiB | 136 |
181
+ | 80 | 14.2 ms | 18.2 ms | 41.5 ms | 3.6 MiB | 70 |
182
+ | 160 | 23.3 ms | 28.2 ms | 61.1 ms | 7.2 MiB | 43 |
183
+ | 320 | 41.6 ms | 45.6 ms | 113 ms | 4.3 MiB | 24 |
184
+ | 640 | 79.0 ms | 83.8 ms | 199 ms | 8.6 MiB | 13 |
185
+ | 1280 | 132 ms | 138 ms | 297 ms | 21.6 MiB | 8 |
186
+ | 2560 | 236 ms | 247 ms | 475 ms | 37.7 MiB | 4 |
187
+ | 5120 | 533 ms | 544 ms | 879 ms | 73.8 MiB | 2 |
188
+
189
+ ##### Varying `variables-per-contract`
190
+
191
+ How many variables each schema file declares (ten in the main sweep). With the total fixed, few large contracts or many small ones cost differently: per-file work (open, parse, link) against per-variable work.
192
+
193
+ **Expected: O(1).** The same total number of variables is parsed and rendered however they are split across files, so the split changes only the small per-file share of the work.
194
+
195
+ #### Variant `one-contract-scoped`
196
+
197
+ An `include` selects one schema file; discovery still walks the tree but only that file is parsed.
198
+
199
+ **Expected for this variant: O(log n).** Only the one selected file is parsed and rendered, but the directory walk that still happens grows with the tree. Across the measured sizes it is a small, sub-linear share of the cost, so the curve rises slowly without being flat.
200
+
201
+ **Measured: O(log n)** (exponent 0.62, 9 sizes) -- ✅ matches.
202
+
203
+ | variables | Median | p95 | CPU (median) | Heap Δ | Ops/s |
204
+ | --- | --- | --- | --- | --- | --- |
205
+ | 20 | 2.55 ms | 3.83 ms | 5.94 ms | 623.3 KiB | 391 |
206
+ | 40 | 2.65 ms | 3.71 ms | 7.22 ms | 662.5 KiB | 378 |
207
+ | 80 | 3.64 ms | 4.85 ms | 9.05 ms | 724.7 KiB | 275 |
208
+ | 160 | 4.58 ms | 5.49 ms | 11.0 ms | 851.7 KiB | 218 |
209
+ | 320 | 4.22 ms | 5.05 ms | 9.17 ms | 1.0 MiB | 237 |
210
+ | 640 | 5.84 ms | 8.31 ms | 12.6 ms | 1.5 MiB | 171 |
211
+ | 1280 | 7.69 ms | 9.93 ms | 11.9 ms | 2.4 MiB | 130 |
212
+ | 2560 | 13.7 ms | 14.9 ms | 24.9 ms | 4.2 MiB | 73 |
213
+ | 5120 | 23.6 ms | 25.4 ms | 41.8 ms | 7.9 MiB | 42 |
214
+
215
+ ##### Varying `variables-per-contract`
216
+
217
+ How many variables each schema file declares (ten in the main sweep). With the total fixed, few large contracts or many small ones cost differently: per-file work (open, parse, link) against per-variable work.
218
+
219
+ **Expected: O(1).** The same total number of variables is parsed and rendered however they are split across files, so the split changes only the small per-file share of the work.
220
+
221
+ ### `generateDocumentation`
222
+
223
+ **Why we benchmark it.** Renders the environment reference developers and auditors read; it runs wherever documentation is regenerated, often on every merge.
224
+
225
+ **What poor performance would mean.** Documentation builds slow down in proportion to configuration size and, when owners write long runbook text, to the volume of prose rendered.
226
+
227
+ **Expected growth: O(n).** It parses each schema once and renders one section per variable, so cost is proportional to the number of variables and the size of their documentation.
228
+
229
+ **Variables that could change its cost**
230
+
231
+ | Variable | How it is handled | What it is |
232
+ | --- | --- | --- |
233
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
234
+ | variables-per-contract | swept | How many variables each schema file declares (ten in the main sweep). With the total fixed, few large contracts or many small ones cost differently: per-file work (open, parse, link) against per-variable work. |
235
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
236
+ | filesystem | fixed at "local SSD through the Node adapter" | A network or virtual filesystem adds latency per file; not covered. |
237
+ | documentation volume | variant | One-line descriptions versus long multi-section runbook text per variable. |
238
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
239
+
240
+ **In the end-to-end run:** Not called by the end-to-end operation: generateEnvArtifacts renders the catalog from its shared parse, while this standalone generator parses again.
241
+
242
+ #### Variant `minimal-docs`
243
+
244
+ One short description per variable.
245
+
246
+ **Measured: O(n)** (exponent 0.73, 9 sizes) -- ✅ matches.
247
+
248
+ | variables | Median | p95 | CPU (median) | Heap Δ | Ops/s |
249
+ | --- | --- | --- | --- | --- | --- |
250
+ | 20 | 4.94 ms | 9.56 ms | 13.6 ms | 1.3 MiB | 202 |
251
+ | 40 | 9.52 ms | 11.8 ms | 24.8 ms | 2.5 MiB | 105 |
252
+ | 80 | 15.5 ms | 19.2 ms | 42.3 ms | 4.8 MiB | 64 |
253
+ | 160 | 24.0 ms | 29.4 ms | 63.3 ms | 8.5 MiB | 42 |
254
+ | 320 | 48.5 ms | 54.2 ms | 125 ms | 7.3 MiB | 21 |
255
+ | 640 | 84.1 ms | 88.1 ms | 212 ms | 18.3 MiB | 12 |
256
+ | 1280 | 129 ms | 133 ms | 302 ms | 30.3 MiB | 8 |
257
+ | 2560 | 212 ms | 221 ms | 433 ms | 50.6 MiB | 5 |
258
+ | 5120 | 377 ms | 386 ms | 706 ms | 97.5 MiB | 3 |
259
+
260
+ ##### Varying `variables-per-contract`
261
+
262
+ How many variables each schema file declares (ten in the main sweep). With the total fixed, few large contracts or many small ones cost differently: per-file work (open, parse, link) against per-variable work.
263
+
264
+ **Expected: O(1).** The same total number of variables is rendered however they are split across files; each file adds one heading and a small table header, a share that shrinks as files grow.
265
+
266
+ #### Variant `heavy-docs`
267
+
268
+ Long descriptions and extra documentation fields per variable (a heavily documented enterprise).
269
+
270
+ **Measured: O(n)** (exponent 0.76, 9 sizes) -- ✅ matches.
271
+
272
+ | variables | Median | p95 | CPU (median) | Heap Δ | Ops/s |
273
+ | --- | --- | --- | --- | --- | --- |
274
+ | 20 | 6.24 ms | 8.03 ms | 17.6 ms | 1.6 MiB | 160 |
275
+ | 40 | 11.1 ms | 13.1 ms | 30.9 ms | 3.0 MiB | 90 |
276
+ | 80 | 20.4 ms | 22.6 ms | 59.5 ms | 5.7 MiB | 49 |
277
+ | 160 | 24.9 ms | 33.9 ms | 60.0 ms | 10.2 MiB | 40 |
278
+ | 320 | 54.4 ms | 59.3 ms | 138 ms | 10.8 MiB | 18 |
279
+ | 640 | 87.3 ms | 101 ms | 225 ms | 21.0 MiB | 11 |
280
+ | 1280 | 149 ms | 157 ms | 347 ms | 27.6 MiB | 7 |
281
+ | 2560 | 251 ms | 252 ms | 507 ms | 66.5 MiB | 4 |
282
+ | 5120 | 454 ms | 466 ms | 800 ms | 140.6 MiB | 2 |
283
+
284
+ ##### Varying `variables-per-contract`
285
+
286
+ How many variables each schema file declares (ten in the main sweep). With the total fixed, few large contracts or many small ones cost differently: per-file work (open, parse, link) against per-variable work.
287
+
288
+ **Expected: O(1).** The same total number of variables is rendered however they are split across files; each file adds one heading and a small table header, a share that shrinks as files grow.
289
+
290
+ ### `generateUsageReport`
291
+
292
+ **Why we benchmark it.** Shows which owners and files consume which variables; it runs in compliance and ownership reviews and in pipelines that enforce them.
293
+
294
+ **What poor performance would mean.** Ownership checks slow down with configuration size, which tempts teams to skip them.
295
+
296
+ **Expected growth: O(n).** It parses the schemas and scans consuming files once, building one usage record per contract, so cost is proportional to the number of variables.
297
+
298
+ **Variables that could change its cost**
299
+
300
+ | Variable | How it is handled | What it is |
301
+ | --- | --- | --- |
302
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
303
+ | variables-per-contract | swept | How many variables each schema file declares (ten in the main sweep). With the total fixed, few large contracts or many small ones cost differently: per-file work (open, parse, link) against per-variable work. |
304
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
305
+ | filesystem | fixed at "local SSD through the Node adapter" | A network or virtual filesystem adds latency per file; not covered. |
306
+ | consuming files | fixed at "none beyond the schemas" | Real projects scan application code for usages; the fixtures contain only schema files, so this is the cheapest case. |
307
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
308
+
309
+ **In the end-to-end run:** Not called by the end-to-end operation: generateEnvArtifacts builds the usage report from its shared parse, while this standalone generator parses again.
310
+
311
+ **Measured: O(n)** (exponent 0.80, 9 sizes) -- ✅ matches.
312
+
313
+ | variables | Median | p95 | CPU (median) | Heap Δ | Ops/s |
314
+ | --- | --- | --- | --- | --- | --- |
315
+ | 20 | 7.79 ms | 12.7 ms | 22.7 ms | 1.6 MiB | 128 |
316
+ | 40 | 14.5 ms | 17.5 ms | 44.3 ms | 3.5 MiB | 69 |
317
+ | 80 | 25.9 ms | 30.3 ms | 74.8 ms | 6.1 MiB | 39 |
318
+ | 160 | 33.4 ms | 42.9 ms | 96.5 ms | 11.4 MiB | 30 |
319
+ | 320 | 55.9 ms | 93.0 ms | 146 ms | 4.7 MiB | 18 |
320
+ | 640 | 108 ms | 111 ms | 274 ms | 17.4 MiB | 9 |
321
+ | 1280 | 176 ms | 186 ms | 394 ms | 21.0 MiB | 6 |
322
+ | 2560 | 296 ms | 300 ms | 564 ms | 42.7 MiB | 3 |
323
+ | 5120 | 534 ms | 558 ms | 957 ms | 76.2 MiB | 2 |
324
+
325
+ ##### Varying `variables-per-contract`
326
+
327
+ How many variables each schema file declares (ten in the main sweep). With the total fixed, few large contracts or many small ones cost differently: per-file work (open, parse, link) against per-variable work.
328
+
329
+ **Expected: O(1).** The same total number of variables is reported however they are split across files; only the small per-file share of the work changes.
330
+
331
+ ### `generateEnvArtifacts`
332
+
333
+ **Why we benchmark it.** The combined entry point most pipelines call: it shares one discovery and parse across all three artifacts instead of repeating them.
334
+
335
+ **What poor performance would mean.** The shared pass is the whole saving over running the generators one by one; if it stopped being shared, every pipeline would pay roughly three times the parsing.
336
+
337
+ **Expected growth: O(n).** It discovers, parses and links once and renders each artifact from that single pass, so cost is proportional to the amount of configuration.
338
+
339
+ **Variables that could change its cost**
340
+
341
+ | Variable | How it is handled | What it is |
342
+ | --- | --- | --- |
343
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
344
+ | variables-per-contract | swept | How many variables each schema file declares (ten in the main sweep). With the total fixed, few large contracts or many small ones cost differently: per-file work (open, parse, link) against per-variable work. |
345
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
346
+ | filesystem | fixed at "local SSD through the Node adapter" | A network or virtual filesystem adds latency per file; not covered. |
347
+ | artifacts requested | fixed at "manifest + docs + usage report" | All three; fewer cost less. |
348
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
349
+
350
+ **In the end-to-end run:** This is the end-to-end operation itself.
351
+
352
+ **Measured: O(n)** (exponent 0.87, 9 sizes) -- ✅ matches.
353
+
354
+ | variables | Median | p95 | CPU (median) | Heap Δ | Ops/s |
355
+ | --- | --- | --- | --- | --- | --- |
356
+ | 20 | 13.9 ms | 15.0 ms | 46.6 ms | 3.3 MiB | 72 |
357
+ | 40 | 22.0 ms | 24.3 ms | 71.4 ms | 5.9 MiB | 45 |
358
+ | 80 | 34.9 ms | 42.1 ms | 110 ms | 11.2 MiB | 29 |
359
+ | 160 | 60.0 ms | 64.4 ms | 169 ms | 8.3 MiB | 17 |
360
+ | 320 | 98.1 ms | 105 ms | 259 ms | 8.0 MiB | 10 |
361
+ | 640 | 149 ms | 157 ms | 337 ms | 10.7 MiB | 7 |
362
+ | 1280 | 268 ms | 278 ms | 521 ms | 27.0 MiB | 4 |
363
+ | 2560 | 509 ms | 523 ms | 857 ms | 19.6 MiB | 2 |
364
+ | 5120 | 1.10 s | 1.13 s | 1.52 s | 104.2 MiB | 1 |
365
+
366
+ ##### Varying `variables-per-contract`
367
+
368
+ How many variables each schema file declares (ten in the main sweep). With the total fixed, few large contracts or many small ones cost differently: per-file work (open, parse, link) against per-variable work.
369
+
370
+ **Expected: O(1).** The same total number of variables is parsed and rendered three times over however they are split across files; only the small per-file share changes.
371
+
372
+ ### `checkEnvArtifacts`
373
+
374
+ **Why we benchmark it.** The CI gate that fails when a committed manifest, document or report is stale: it regenerates every requested artifact in memory and compares it with the file on disk.
375
+
376
+ **What poor performance would mean.** A slower gate on every pull request, which is the most frequent place build-time cost is paid.
377
+
378
+ **Expected growth: O(n).** It runs one shared discovery, parse and link, renders each requested artifact once and compares each with its file, so cost is proportional to the amount of configuration.
379
+
380
+ **Variables that could change its cost**
381
+
382
+ | Variable | How it is handled | What it is |
383
+ | --- | --- | --- |
384
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
385
+ | variables-per-contract | swept | How many variables each schema file declares (ten in the main sweep). With the total fixed, few large contracts or many small ones cost differently: per-file work (open, parse, link) against per-variable work. |
386
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
387
+ | filesystem | fixed at "local SSD through the Node adapter" | A network or virtual filesystem adds latency per file; not covered. |
388
+ | artifact state | fixed at "every artifact is current" | A stale artifact adds a finding to report and no more parsing. |
389
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
390
+
391
+ **In the end-to-end run:** A CI gate, not part of generating the artifacts.
392
+
393
+ ##### Varying `variables-per-contract`
394
+
395
+ How many variables each schema file declares (ten in the main sweep). With the total fixed, few large contracts or many small ones cost differently: per-file work (open, parse, link) against per-variable work.
396
+
397
+ **Expected: O(1).** The same total number of variables is rendered and compared however they are split across files; only the small per-file share changes.
398
+
399
+ ### `computeSourceFingerprint`
400
+
401
+ **Why we benchmark it.** It decides whether a cached evidence model is still current, so it runs before every cached read and must cost far less than the recompute it avoids.
402
+
403
+ **What poor performance would mean.** A cache that costs nearly as much as the recompute it saves, which makes every cached read pointless.
404
+
405
+ **Expected growth: O(n).** It walks the schema files and hashes each one's text once, with no parsing or linking, so cost is proportional to the bytes of source.
406
+
407
+ **Variables that could change its cost**
408
+
409
+ | Variable | How it is handled | What it is |
410
+ | --- | --- | --- |
411
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
412
+ | variables-per-contract | swept | How many variables each schema file declares (ten in the main sweep). With the total fixed, few large contracts or many small ones cost differently: per-file work (open, parse, link) against per-variable work. |
413
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
414
+ | filesystem | fixed at "local SSD through the Node adapter" | A network or virtual filesystem adds latency per file; not covered. |
415
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
416
+
417
+ **In the end-to-end run:** Run before a cached read, not while generating.
418
+
419
+ ##### Varying `variables-per-contract`
420
+
421
+ How many variables each schema file declares (ten in the main sweep). With the total fixed, few large contracts or many small ones cost differently: per-file work (open, parse, link) against per-variable work.
422
+
423
+ **Expected: O(1).** The same total bytes of source are hashed however they are split across files; only the per-file read overhead changes.
424
+
425
+ ### `generateEvidenceModel`
426
+
427
+ **Why we benchmark it.** Builds the six canonical fact models (contract, ownership, lifecycle, dependency, finding and more) that audits, dashboards and custom projections read.
428
+
429
+ **What poor performance would mean.** Compliance tooling that rebuilds evidence on every run gets slower with the size of the configuration, and an expensive model discourages using it at all.
430
+
431
+ **Expected growth: O(n).** It runs discovery and linking once and then derives each fact model from the same parse, so cost is proportional to the amount of configuration.
432
+
433
+ **Variables that could change its cost**
434
+
435
+ | Variable | How it is handled | What it is |
436
+ | --- | --- | --- |
437
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
438
+ | variables-per-contract | swept | How many variables each schema file declares (ten in the main sweep). With the total fixed, few large contracts or many small ones cost differently: per-file work (open, parse, link) against per-variable work. |
439
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
440
+ | filesystem | fixed at "local SSD through the Node adapter" | A network or virtual filesystem adds latency per file; not covered. |
441
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
442
+
443
+ **Measured: O(n)** (exponent 0.77, 9 sizes) -- ✅ matches.
444
+
445
+ | variables | Median | p95 | CPU (median) | Heap Δ | Ops/s |
446
+ | --- | --- | --- | --- | --- | --- |
447
+ | 20 | 8.52 ms | 10.9 ms | 23.7 ms | 2.3 MiB | 117 |
448
+ | 40 | 13.8 ms | 16.0 ms | 40.0 ms | 4.6 MiB | 72 |
449
+ | 80 | 24.1 ms | 28.8 ms | 70.4 ms | 9.0 MiB | 42 |
450
+ | 160 | 48.6 ms | 56.8 ms | 160 ms | 4.7 MiB | 21 |
451
+ | 320 | 89.2 ms | 95.9 ms | 241 ms | 15.2 MiB | 11 |
452
+ | 640 | 141 ms | 146 ms | 326 ms | 14.4 MiB | 7 |
453
+ | 1280 | 228 ms | 234 ms | 440 ms | 30.1 MiB | 4 |
454
+ | 2560 | 406 ms | 411 ms | 731 ms | 43.7 MiB | 2 |
455
+ | 5120 | 767 ms | 770 ms | 1.22 s | 87.6 MiB | 1 |
456
+
457
+ ##### Varying `variables-per-contract`
458
+
459
+ How many variables each schema file declares (ten in the main sweep). With the total fixed, few large contracts or many small ones cost differently: per-file work (open, parse, link) against per-variable work.
460
+
461
+ **Expected: O(1).** The same total number of variables is modelled however they are split across files; only the small per-file share changes.
462
+
463
+ ### `getEvidenceModel`
464
+
465
+ **Why we benchmark it.** The cached way to read the evidence model: it trusts a committed artifact only while the source fingerprint matches, and recomputes otherwise.
466
+
467
+ **What poor performance would mean.** A miss that costs more than a plain recompute, or a hit that costs nearly as much as one, would make the cache worse than not having it.
468
+
469
+ **Expected growth: O(n).** A hit fingerprints the source and reads one file; a miss does that and then rebuilds the model, so both grow with the amount of configuration.
470
+
471
+ **Variables that could change its cost**
472
+
473
+ | Variable | How it is handled | What it is |
474
+ | --- | --- | --- |
475
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
476
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
477
+ | filesystem | fixed at "local SSD through the Node adapter" | A network or virtual filesystem adds latency per file; not covered. |
478
+ | cache state | variant | A committed artifact whose fingerprint matches, or none. |
479
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
480
+
481
+ **In the end-to-end run:** A cached read, not part of generating the artifacts.
482
+
483
+ #### Variant `cache-hit`
484
+
485
+ The committed artifact is current: read from disk, no recompute.
486
+
487
+ **Expected for this variant: O(n).** The source is fingerprinted and the artifact read once, both proportional to the amount of configuration, with no parsing.
488
+
489
+ #### Variant `cache-miss`
490
+
491
+ No artifact exists: the model is rebuilt.
492
+
493
+ ### `parseSchemaFile`
494
+
495
+ **Why we benchmark it.** Every generator parses each schema file with the TypeScript parser, which is the largest single cost of a build-time run.
496
+
497
+ **What poor performance would mean.** Every build-time command slows in proportion to the source it parses, and a super-linear parse would punish the largest schema files first.
498
+
499
+ **Expected growth: O(n).** The text is parsed once by the TypeScript parser and the variables read from one syntax tree, so cost is proportional to the length of the source.
500
+
501
+ **Variables that could change its cost**
502
+
503
+ | Variable | How it is handled | What it is |
504
+ | --- | --- | --- |
505
+ | declared variables | swept | The tier axis: how many variables the one schema file declares. |
506
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
507
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
508
+
509
+ **In the end-to-end run:** Run once per schema file inside every generator; measured here on one file.
510
+
511
+ ### `linkFiles`
512
+
513
+ **Why we benchmark it.** It turns parsed schema files into linked contracts, following the imports between them, and runs once in every generator.
514
+
515
+ **What poor performance would mean.** Every build-time command slows in proportion to the number of schema files and the imports between them.
516
+
517
+ **Expected growth: O(n).** Each file is read and parsed once and each import resolved once, so cost is proportional to the number of files.
518
+
519
+ **Variables that could change its cost**
520
+
521
+ | Variable | How it is handled | What it is |
522
+ | --- | --- | --- |
523
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
524
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
525
+ | filesystem | fixed at "local SSD through the Node adapter" | A network or virtual filesystem adds latency per file; not covered. |
526
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
527
+
528
+ **Deliberately not covered**
529
+
530
+ - **aliased and package imports** -- Following a tsconfig alias or an allowlisted package adds a resolution per import; the fixtures import nothing.
531
+
532
+ **In the end-to-end run:** Run once inside every generator; measured on its own.
533
+
534
+ ### `buildContractModel`
535
+
536
+ **Why we benchmark it.** It derives the contract fact model (every contract, its variables and their documentation) that the other models and every projection build on.
537
+
538
+ **What poor performance would mean.** Every evidence build slows in proportion to the number of variables.
539
+
540
+ **Expected growth: O(n).** One entry is built for each contract and each variable, once, so cost is proportional to the number of variables.
541
+
542
+ **Variables that could change its cost**
543
+
544
+ | Variable | How it is handled | What it is |
545
+ | --- | --- | --- |
546
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
547
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
548
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
549
+
550
+ **In the end-to-end run:** Not part of the end-to-end operation, which calls the generators; measured on its own.
551
+
552
+ ### `buildOwnershipModel`
553
+
554
+ **Why we benchmark it.** It derives who owns each contract and variable, the model ownership reviews and the usage report read.
555
+
556
+ **What poor performance would mean.** Every evidence build slows in proportion to the number of variables.
557
+
558
+ **Expected growth: O(n).** Each variable's owner is resolved once from its own documentation and its contract's, so cost is proportional to the number of variables.
559
+
560
+ **Variables that could change its cost**
561
+
562
+ | Variable | How it is handled | What it is |
563
+ | --- | --- | --- |
564
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
565
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
566
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
567
+
568
+ **In the end-to-end run:** Not part of the end-to-end operation, which calls the generators; measured on its own.
569
+
570
+ ### `buildLifecycleModel`
571
+
572
+ **Why we benchmark it.** It derives the lifecycle fact model: what expires, what is due for rotation and what is deprecated, which the rotation reminders read.
573
+
574
+ **What poor performance would mean.** Every evidence build and every scheduled rotation check slows in proportion to the number of variables.
575
+
576
+ **Expected growth: O(n).** Each variable's dates are read and compared once, so cost is proportional to the number of variables.
577
+
578
+ **Variables that could change its cost**
579
+
580
+ | Variable | How it is handled | What it is |
581
+ | --- | --- | --- |
582
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
583
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
584
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
585
+
586
+ **In the end-to-end run:** Not part of the end-to-end operation, which calls the generators; measured on its own.
587
+
588
+ ### `computeExpiringEntries`
589
+
590
+ **Why we benchmark it.** It lists what expires within a window, once for every reminder and every report that shows expiries.
591
+
592
+ **What poor performance would mean.** A slower expiry reminder in proportion to the number of variables.
593
+
594
+ **Expected growth: O(n).** Each variable's expiry date is compared with the window once, so cost is proportional to the number of variables.
595
+
596
+ **Variables that could change its cost**
597
+
598
+ | Variable | How it is handled | What it is |
599
+ | --- | --- | --- |
600
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
601
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
602
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
603
+
604
+ **In the end-to-end run:** Not part of the end-to-end operation, which calls the generators; measured on its own.
605
+
606
+ ### `computeSecurityReviewCounters`
607
+
608
+ **Why we benchmark it.** It counts what a security review looks at (secrets, owners, expiries, undocumented variables), once per documentation render.
609
+
610
+ **What poor performance would mean.** Slower documentation in proportion to the number of variables.
611
+
612
+ **Expected growth: O(n).** Each variable is classified once into the counters, so cost is proportional to the number of variables.
613
+
614
+ **Variables that could change its cost**
615
+
616
+ | Variable | How it is handled | What it is |
617
+ | --- | --- | --- |
618
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
619
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
620
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
621
+
622
+ **In the end-to-end run:** Not part of the end-to-end operation, which calls the generators; measured on its own.
623
+
624
+ ### `renderDocs`
625
+
626
+ **Why we benchmark it.** It turns the contract model into the Markdown reference, the largest text env-cap renders.
627
+
628
+ **What poor performance would mean.** Documentation builds slow in proportion to the number of variables and the prose each carries.
629
+
630
+ **Expected growth: O(n).** One section is rendered for each contract and variable, once, so cost is proportional to the amount of documentation.
631
+
632
+ **Variables that could change its cost**
633
+
634
+ | Variable | How it is handled | What it is |
635
+ | --- | --- | --- |
636
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
637
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
638
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
639
+
640
+ **In the end-to-end run:** Not part of the end-to-end operation, which calls the generators; measured on its own.
641
+
642
+ ### `renderManifest`
643
+
644
+ **Why we benchmark it.** It renders the TypeScript manifest the application imports, in every build that ships the application.
645
+
646
+ **What poor performance would mean.** Slower builds in proportion to the number of variables.
647
+
648
+ **Expected growth: O(n).** One manifest entry is rendered for each variable, so cost is proportional to the number of variables.
649
+
650
+ **Variables that could change its cost**
651
+
652
+ | Variable | How it is handled | What it is |
653
+ | --- | --- | --- |
654
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
655
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
656
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
657
+
658
+ **In the end-to-end run:** Not part of the end-to-end operation, which calls the generators; measured on its own.
659
+
660
+ ### `computeReconciliation`
661
+
662
+ **Why we benchmark it.** It compares the variables the schemas declare with those in an existing `.env.example`, to say what to add and what is stale.
663
+
664
+ **What poor performance would mean.** A slower `.env.example` update in proportion to the number of variables and the size of the file.
665
+
666
+ **Expected growth: O(n).** The existing lines are indexed once and each declared variable looked up once, so cost is proportional to both.
667
+
668
+ **Variables that could change its cost**
669
+
670
+ | Variable | How it is handled | What it is |
671
+ | --- | --- | --- |
672
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
673
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
674
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
675
+
676
+ **In the end-to-end run:** Not part of the end-to-end operation, which calls the generators; measured on its own.
677
+
678
+ ### `renderEnvExample`
679
+
680
+ **Why we benchmark it.** It renders the `.env.example` file developers copy, from the same contracts as everything else.
681
+
682
+ **What poor performance would mean.** A slower `.env.example` update in proportion to the number of variables.
683
+
684
+ **Expected growth: O(n).** One line is rendered for each variable, so cost is proportional to the number of variables.
685
+
686
+ **Variables that could change its cost**
687
+
688
+ | Variable | How it is handled | What it is |
689
+ | --- | --- | --- |
690
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
691
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
692
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
693
+
694
+ **In the end-to-end run:** Not part of the end-to-end operation, which calls the generators; measured on its own.
695
+
696
+ ### `groupVariablesByOwner`
697
+
698
+ **Why we benchmark it.** It groups every variable under its owner, which the ownership summary and the usage report both print.
699
+
700
+ **What poor performance would mean.** A slower ownership report in proportion to the number of variables.
701
+
702
+ **Expected growth: O(n).** Each variable is placed in its owner's group once, so cost is proportional to the number of variables.
703
+
704
+ **Variables that could change its cost**
705
+
706
+ | Variable | How it is handled | What it is |
707
+ | --- | --- | --- |
708
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
709
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
710
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
711
+
712
+ **In the end-to-end run:** Not part of the end-to-end operation, which calls the generators; measured on its own.
713
+
714
+ ### `applyLiveExpirationOverrides`
715
+
716
+ **Why we benchmark it.** It replaces schema expiry dates with live ones (read from a secrets manager), once per run that uses a live source.
717
+
718
+ **What poor performance would mean.** A slower run for every project that tracks expiry in a live source, in proportion to the number of variables.
719
+
720
+ **Expected growth: O(n).** Each variable is looked up once in the map of overrides, so cost is proportional to the number of variables.
721
+
722
+ **Variables that could change its cost**
723
+
724
+ | Variable | How it is handled | What it is |
725
+ | --- | --- | --- |
726
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
727
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
728
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
729
+
730
+ **In the end-to-end run:** Not part of the end-to-end operation, which calls the generators; measured on its own.
731
+
732
+ ### `resolveLiveExpirationDates`
733
+
734
+ **Why we benchmark it.** It asks the caller's live source for the expiry of every variable once, then applies the answers.
735
+
736
+ **What poor performance would mean.** A slower run for every project that uses a live source, in proportion to the number of variables, on top of the lookup the caller pays for.
737
+
738
+ **Expected growth: O(n).** The variable names are collected once, handed to the caller's function once and the answers applied once, so cost is proportional to the number of variables.
739
+
740
+ **Variables that could change its cost**
741
+
742
+ | Variable | How it is handled | What it is |
743
+ | --- | --- | --- |
744
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
745
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
746
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
747
+
748
+ **In the end-to-end run:** Not part of the end-to-end operation, which calls the generators; measured on its own.
749
+
750
+ ### `configurationReference`
751
+
752
+ **Why we benchmark it.** It projects the evidence model into the flat configuration reference an operations team reads.
753
+
754
+ **What poor performance would mean.** A slower projection in proportion to the evidence model, which grows with the number of variables.
755
+
756
+ **Expected growth: O(n).** It reads the models once and builds one entry per variable, so cost is proportional to the number of variables.
757
+
758
+ **Variables that could change its cost**
759
+
760
+ | Variable | How it is handled | What it is |
761
+ | --- | --- | --- |
762
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
763
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
764
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
765
+
766
+ **In the end-to-end run:** Not part of the end-to-end operation, which calls the generators; measured on its own.
767
+
768
+ ### `expiringSoonReport`
769
+
770
+ **Why we benchmark it.** It projects the evidence model into the report of what expires soon, which the rotation reminders send.
771
+
772
+ **What poor performance would mean.** A slower reminder in proportion to the evidence model.
773
+
774
+ **Expected growth: O(n).** It reads the lifecycle and contract models once, so cost is proportional to the number of variables.
775
+
776
+ **Variables that could change its cost**
777
+
778
+ | Variable | How it is handled | What it is |
779
+ | --- | --- | --- |
780
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
781
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
782
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
783
+
784
+ **In the end-to-end run:** Not part of the end-to-end operation, which calls the generators; measured on its own.
785
+
786
+ ### `ownershipSummary`
787
+
788
+ **Why we benchmark it.** It projects the evidence model into the per-owner summary a review reads.
789
+
790
+ **What poor performance would mean.** A slower summary in proportion to the evidence model.
791
+
792
+ **Expected growth: O(n).** It groups every variable by owner once, so cost is proportional to the number of variables.
793
+
794
+ **Variables that could change its cost**
795
+
796
+ | Variable | How it is handled | What it is |
797
+ | --- | --- | --- |
798
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
799
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
800
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
801
+
802
+ **In the end-to-end run:** Not part of the end-to-end operation, which calls the generators; measured on its own.
803
+
804
+ ### `buildSarifLog`
805
+
806
+ **Why we benchmark it.** It converts the finding model into SARIF for code-scanning dashboards, in every pipeline that uploads findings.
807
+
808
+ **What poor performance would mean.** A slower upload step in proportion to the number of findings.
809
+
810
+ **Expected growth: O(n).** One SARIF result is built for each finding, so cost is proportional to the number of findings.
811
+
812
+ **Variables that could change its cost**
813
+
814
+ | Variable | How it is handled | What it is |
815
+ | --- | --- | --- |
816
+ | declared variables | swept | The tier axis here is findings, one for each of this many variables with a problem. |
817
+ | finding mix | fixed at "one error, one warning and one info in turn" | Severity only picks the SARIF level. |
818
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
819
+
820
+ **In the end-to-end run:** Not part of the end-to-end operation, which calls the generators; measured on its own.
821
+
822
+ ### `defineEvidenceProjection (project)`
823
+
824
+ **Why we benchmark it.** Turns the evidence model into a consumer-specific view (a report, an export); it runs in every pipeline that publishes one, on top of the model build.
825
+
826
+ **What poor performance would mean.** Custom reports slow in proportion to the model, and a copy-heavy implementation would make the projection cost more than building the evidence itself.
827
+
828
+ **Expected growth: O(n).** The projection copies the model once (`structuredClone`) and reads it through a tracking membrane, both proportional to the model's size, which grows with the number of variables.
829
+
830
+ **Variables that could change its cost**
831
+
832
+ | Variable | How it is handled | What it is |
833
+ | --- | --- | --- |
834
+ | declared variables | swept | The tier axis: how many environment variables are declared across the project (ten per schema file, so the file count grows with it). |
835
+ | schema content | fixed at "realistic generated TypeScript: JSON-credential processors, validators and documentEnv calls" | Parsing cost depends on source-text volume and variety; the fixtures are literal TypeScript source, never executed by the tooling. |
836
+ | projection shape | fixed at "five derived fields across all six fact models" | A projection that reads fewer fields still pays the clone; one that computes more adds proportional work. |
837
+ | runtime | fixed at "Node (V8)" | Measured on Node only. |
838
+
839
+ **Measured: O(n)** (exponent 1.07, 9 sizes) -- ✅ matches.
840
+
841
+ | variables | Median | p95 | CPU (median) | Heap Δ | Ops/s |
842
+ | --- | --- | --- | --- | --- | --- |
843
+ | 20 | 698 µs | 1.09 ms | 2.43 ms | 315.8 KiB | 1,433 |
844
+ | 40 | 1.05 ms | 1.44 ms | 2.76 ms | 559.7 KiB | 952 |
845
+ | 80 | 1.78 ms | 2.51 ms | 3.60 ms | 1.0 MiB | 561 |
846
+ | 160 | 3.27 ms | 4.18 ms | 6.08 ms | 2.0 MiB | 306 |
847
+ | 320 | 6.33 ms | 7.07 ms | 10.6 ms | 4.0 MiB | 158 |
848
+ | 640 | 12.2 ms | 12.8 ms | 15.9 ms | 8.1 MiB | 82 |
849
+ | 1280 | 26.2 ms | 27.1 ms | 32.6 ms | 4.6 MiB | 38 |
850
+ | 2560 | 53.2 ms | 55.9 ms | 62.6 ms | 9.8 MiB | 19 |
851
+ | 5120 | 124 ms | 129 ms | 170 ms | 41.8 MiB | 8 |
852
+
853
+ ## 3. What makes up one end-to-end operation
854
+
855
+ Each function's measured cost is multiplied by how many times one end-to-end operation calls it. A function measured on its own includes everything it calls, so where one attributed function calls another, the nested time is subtracted from the caller (its _exclusive_ time): every moment of the operation belongs to at most one row. Shares are measured against the whole operation with the package, a figure measured directly -- not against the _added_ time, which is the small difference of two noisy medians. They are estimates (each function was measured separately); the remainder is shown as _unattributed_.
856
+
857
+ **At 640 variables** (whole operation: 147 ms)
858
+
859
+ | Function | Calls / operation | Time if called that often | Exclusive time | Share of operation |
860
+ | --- | --- | --- | --- | --- |
861
+ | `generate-artifacts` | 1 | 149 ms | 146 ms | 99% |
862
+ | `discover-schema-files` | 1 | 3.00 ms | 3.00 ms | 2.0% |
863
+ | `generate-documentation` | 0 | 0 | 0 | 0.0% |
864
+ | `generate-usage-report` | 0 | 0 | 0 | 0.0% |
865
+ | _unattributed_ | | | 0 | 0.0% |
866
+
867
+ **At 5120 variables** (whole operation: 1.14 s)
868
+
869
+ | Function | Calls / operation | Time if called that often | Exclusive time | Share of operation |
870
+ | --- | --- | --- | --- | --- |
871
+ | `generate-artifacts` | 1 | 1.10 s | 1.08 s | 94% |
872
+ | `discover-schema-files` | 1 | 20.7 ms | 20.7 ms | 1.8% |
873
+ | `generate-documentation` | 0 | 0 | 0 | 0.0% |
874
+ | `generate-usage-report` | 0 | 0 | 0 | 0.0% |
875
+ | _unattributed_ | | | 47.9 ms | 4.2% |
876
+
877
+ ## Cost model
878
+
879
+ Estimates use two bracketing price shapes: **low** = CPU-priced compute ($0.040 per vCPU-hour, billed on CPU time) and **high** = duration-and-memory-priced functions ($0.000017 per GB-second, billed on wall time, at least 128 MB reserved). Both are rounded list prices and change over time; override them in `benchmark.config.json` → `costRates` to match your platform and negotiated pricing.
880
+
881
+ ## Environment and method
882
+
883
+ - Run: `2026-10-02T00:45:43.860Z` → `2026-10-02T00:46:55.879Z` (72 s), ci
884
+ - Machine: AMD EPYC 9V45 96-Core Processor, 4 logical core(s) (2 physical), 15990 MB RAM, linux/x64, Node v22.23.3, GitHub Actions
885
+ - Git: `77acd16d0d0b13e9c162061da6d6f7d739436547` on `chore/no-minify-no-dist-urls` (uncommitted changes)
886
+ - Sizes: 20, 40, 80, 160, 320, 640, 1280, 2560, 5120 variables -- One environment variable declared in a schema file. Schema files hold ten variables each, so 640 variables is 64 files -- a large monorepo's worth of configuration. The ladder stops at 5,120 variables (512 files) because `discoverSchemaFiles` refuses more than 1,000 files as a sanity limit, which 10,240 variables would exceed.
887
+
888
+ **Do not compare these numbers with another machine's, another day's, or another package's.** They exist to show how _this_ package's cost changes between runs on comparable hardware and how it scales with size. See [READING-BENCHMARKS.md](../READING-BENCHMARKS.md).
889
+