@maverickcer/env-cap 0.6.0 → 0.7.0

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 (136) hide show
  1. package/ADOPTION.md +144 -0
  2. package/AGENTS.md +146 -0
  3. package/CHANGELOG.md +438 -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 +34 -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/link.d.ts.map +1 -1
  45. package/dist/.dts/build/merge-documentation.d.ts +35 -0
  46. package/dist/.dts/build/merge-documentation.d.ts.map +1 -0
  47. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +11 -112
  48. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
  49. package/dist/.dts/build/types.d.ts +4 -53
  50. package/dist/.dts/build/types.d.ts.map +1 -1
  51. package/dist/.dts/build/typescript.d.ts +3 -17
  52. package/dist/.dts/build/typescript.d.ts.map +1 -1
  53. package/dist/.dts/eslint-plugin/glob.d.ts +4 -15
  54. package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -1
  55. package/dist/.dts/eslint-plugin/index.d.ts +1 -1
  56. package/dist/.dts/eslint-plugin/no-node-fs.d.ts +8 -18
  57. package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -1
  58. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -1
  59. package/dist/{build-H4KFV44Z.js → build-WKDIAWF7.js} +198 -60
  60. package/dist/build-WKDIAWF7.js.map +1 -0
  61. package/dist/build.cjs +194 -56
  62. package/dist/build.cjs.map +1 -1
  63. package/dist/build.js +194 -56
  64. package/dist/build.js.map +1 -1
  65. package/dist/{chunk-7GVPOHDU.js → chunk-KEGYUHBU.js} +2 -2
  66. package/dist/cli/index.js +36 -29
  67. package/dist/cli/index.js.map +1 -1
  68. package/dist/eslint-plugin/index.cjs +84 -54
  69. package/dist/eslint-plugin/index.cjs.map +1 -1
  70. package/dist/eslint-plugin/index.js +83 -53
  71. package/dist/eslint-plugin/index.js.map +1 -1
  72. package/examples/README.md +95 -0
  73. package/package.json +48 -14
  74. package/skills/env-cap/SKILL.md +91 -0
  75. package/skills/env-cap/references/api.md +220 -0
  76. package/specs/architecture.md +634 -0
  77. package/specs/decisions/0001-runtime-documentation-separation.md +197 -0
  78. package/specs/decisions/0002-static-analysis-never-execution.md +233 -0
  79. package/specs/decisions/0003-no-global-env-object.md +172 -0
  80. package/specs/decisions/0004-no-client-server-package-split.md +116 -0
  81. package/specs/decisions/0005-warn-not-throw-by-default.md +93 -0
  82. package/specs/decisions/0006-self-redacting-contracts.md +124 -0
  83. package/specs/decisions/0007-processor-not-transformer.md +109 -0
  84. package/specs/decisions/0008-gzip-size-budget.md +173 -0
  85. package/specs/decisions/0009-exclusive-groups-are-always-errors.md +139 -0
  86. package/specs/decisions/0010-dependency-ownership-engine-scope-boundary.md +100 -0
  87. package/specs/decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md +104 -0
  88. package/specs/decisions/0012-live-expiration-overrides-not-ast-functions.md +145 -0
  89. package/specs/decisions/0013-json-output-is-a-versioned-mirror.md +136 -0
  90. package/specs/decisions/0014-cross-package-schema-discovery.md +206 -0
  91. package/specs/decisions/0015-security-backport-window.md +60 -0
  92. package/specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md +113 -0
  93. package/specs/decisions/0017-eslint-plugin-entry-point.md +113 -0
  94. package/specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md +104 -0
  95. package/specs/decisions/0019-published-json-schema-generated-from-types.md +100 -0
  96. package/specs/decisions/0020-declaration-maps-via-separate-tsc-pass.md +101 -0
  97. package/specs/decisions/0021-manifest-change-report-persisted-snapshot.md +177 -0
  98. package/specs/decisions/0022-validation-contexts.md +267 -0
  99. package/specs/decisions/0023-tsconfig-path-alias-resolution.md +182 -0
  100. package/specs/decisions/0024-fact-model-architecture.md +144 -0
  101. package/specs/decisions/0025-contract-model-json-projection.md +105 -0
  102. package/specs/decisions/0026-finding-model-unifies-four-families.md +109 -0
  103. package/specs/decisions/0027-dependency-model-fact-shape-not-engine-access.md +98 -0
  104. package/specs/decisions/0028-ownership-model-shared-effective-owner.md +85 -0
  105. package/specs/decisions/0029-lifecycle-model-deprecation-rename-fields.md +98 -0
  106. package/specs/decisions/0030-change-model-wraps-manifest-change-report.md +97 -0
  107. package/specs/decisions/0031-evidence-entry-point.md +85 -0
  108. package/specs/decisions/0032-evidence-projection-provenance-mechanism.md +120 -0
  109. package/specs/decisions/0033-reference-projections-live-in-examples.md +81 -0
  110. package/specs/decisions/0034-three-tier-examples-restructuring.md +85 -0
  111. package/specs/decisions/0035-documentenv-metadata-generalization-and-compliance-fields.md +85 -0
  112. package/specs/decisions/0036-exact-source-position-evidence.md +122 -0
  113. package/specs/decisions/0037-developer-declared-dynamic-access-citations.md +114 -0
  114. package/specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md +244 -0
  115. package/specs/decisions/0039-scanner-local-dataflow-boundary.md +160 -0
  116. package/specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md +156 -0
  117. package/specs/decisions/0041-dual-package-hazard-checked-documented.md +75 -0
  118. package/specs/decisions/0042-init-cli-subcommand-scaffolds-only.md +95 -0
  119. package/specs/decisions/0043-env-cap-resolver-relocated-and-duplicated.md +71 -0
  120. package/specs/decisions/0044-strict-escalates-every-warning-family.md +88 -0
  121. package/specs/decisions/0045-promote-experimental-surfaces-to-stable.md +103 -0
  122. package/specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md +177 -0
  123. package/specs/decisions/0047-supported-toolchain-node-22-and-typescript-5-6.md +30 -0
  124. package/specs/decisions/0048-eslint-plugin-does-not-vendor-typescript-eslint.md +25 -0
  125. package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +87 -0
  126. package/specs/decisions/0050-a-variable-declared-twice-is-documented-once.md +55 -0
  127. package/specs/generated-artifacts.md +104 -0
  128. package/specs/migrations/README.md +30 -0
  129. package/specs/migrations/from-centralized-schema.md +503 -0
  130. package/specs/migrations/from-dotenv.md +352 -0
  131. package/specs/migrations/from-envalid.md +482 -0
  132. package/specs/migrations/from-process-env.md +398 -0
  133. package/specs/migrations/from-t3-env.md +416 -0
  134. package/specs/migrations/from-zod.md +303 -0
  135. package/dist/build-H4KFV44Z.js.map +0 -1
  136. /package/dist/{chunk-7GVPOHDU.js.map → chunk-KEGYUHBU.js.map} +0 -0
package/dist/build.js CHANGED
@@ -3,9 +3,10 @@ import crypto from 'crypto';
3
3
  import { createRequire } from 'module';
4
4
 
5
5
  // src/build/evidence-snapshot.ts
6
- function displayPath(root, absolutePath) {
7
- const relative = path6.relative(root, absolutePath);
8
- if (relative.startsWith("..") || path6.isAbsolute(relative)) return absolutePath;
6
+ function displayPath(root, filePath) {
7
+ if (!path6.isAbsolute(filePath)) return filePath.split(path6.sep).join("/");
8
+ const relative = path6.relative(root, filePath);
9
+ if (relative.startsWith("..") || path6.isAbsolute(relative)) return filePath;
9
10
  return relative.split(path6.sep).join("/");
10
11
  }
11
12
 
@@ -331,7 +332,7 @@ async function computeEvidenceChanges(root, snapshotPath, activeContracts, curre
331
332
  };
332
333
  }
333
334
 
334
- // src/build/glob.ts
335
+ // src/_ipc/glob.ts
335
336
  function globToRegExp(pattern) {
336
337
  let out = "";
337
338
  let resume = 0;
@@ -427,14 +428,19 @@ function pickCompiler(load) {
427
428
  }
428
429
  var ts = pickCompiler(createRequire(import.meta.url));
429
430
 
430
- // src/build/compiler-api.ts
431
- function assertCompilerApi(compiler) {
431
+ // src/_ipc/compiler-api.ts
432
+ function assertCompilerApi(product, compiler) {
432
433
  if (typeof compiler.createSourceFile === "function") return;
433
434
  throw new Error(
434
- `env-cap's build-time scanner needs TypeScript's classic compiler API (typescript ^5 || ^6), but the installed typescript${compiler.version === void 0 ? "" : ` ${compiler.version}`} does not expose it and the bundled @typescript/typescript6 could not be loaded. Reinstall env-cap with its dependencies, or provide a TypeScript 6 compiler: npm install --save-dev typescript@npm:@typescript/typescript6 (this swaps your \`tsc\` for \`tsc6\`; to keep TypeScript 7's \`tsc\`, also add @typescript/native@npm:typescript@^7). See VERSIONING.md, 'Supported toolchain'.`
435
+ `${product}'s build-time scanner needs TypeScript's classic compiler API (typescript ^5 || ^6), but the installed typescript${compiler.version === void 0 ? "" : ` ${compiler.version}`} does not expose it and the bundled @typescript/typescript6 could not be loaded. Reinstall ${product} with its dependencies, or provide a TypeScript 6 compiler: npm install --save-dev typescript@npm:@typescript/typescript6 (this swaps your \`tsc\` for \`tsc6\`; to keep TypeScript 7's \`tsc\`, also add @typescript/native@npm:typescript@^7). See VERSIONING.md, 'Supported toolchain'.`
435
436
  );
436
437
  }
437
438
 
439
+ // src/build/compiler-api.ts
440
+ function assertCompilerApi2(compiler) {
441
+ assertCompilerApi("env-cap", compiler);
442
+ }
443
+
438
444
  // src/build/literal-eval.ts
439
445
  function evaluateLiteral(node) {
440
446
  if (ts.isStringLiteralLike(node)) return { ok: true, value: node.text };
@@ -479,7 +485,7 @@ function getStaticPropertyName(name) {
479
485
 
480
486
  // src/build/parse.ts
481
487
  function parseSchemaFile(filePath, sourceText) {
482
- assertCompilerApi(ts);
488
+ assertCompilerApi2(ts);
483
489
  const sourceFile = ts.createSourceFile(
484
490
  filePath,
485
491
  sourceText,
@@ -1005,6 +1011,93 @@ function mustGet(map, key) {
1005
1011
  throw new Error(`Internal error: expected key "${String(key)}" to be present in map.`);
1006
1012
  return value;
1007
1013
  }
1014
+
1015
+ // src/build/merge-documentation.ts
1016
+ var VALUE_FIELDS = [
1017
+ "description",
1018
+ "owner",
1019
+ "sensitivity",
1020
+ "expiresAt",
1021
+ "refreshInstructions",
1022
+ "authenticatorType",
1023
+ "rotationPeriod",
1024
+ "lastRotatedAt",
1025
+ "rotationTriggerEvents",
1026
+ "setupInstructions",
1027
+ "required",
1028
+ "deprecated",
1029
+ "deprecatedReason",
1030
+ "removeBy",
1031
+ "renamedFrom",
1032
+ "purpose",
1033
+ "legalBasis",
1034
+ "retention",
1035
+ "dataResidency",
1036
+ "auditRequired"
1037
+ ];
1038
+ function mergeSharedDocumentation(contracts) {
1039
+ const declarationsByKey = /* @__PURE__ */ new Map();
1040
+ for (const contract of contracts) {
1041
+ for (const variable of contract.variables) {
1042
+ const declarations = declarationsByKey.get(variable.key);
1043
+ if (declarations === void 0) declarationsByKey.set(variable.key, [{ contract, variable }]);
1044
+ else declarations.push({ contract, variable });
1045
+ }
1046
+ }
1047
+ return contracts.map((contract) => ({
1048
+ ...contract,
1049
+ variables: contract.variables.map((variable) => {
1050
+ const fromPackages = [];
1051
+ const fromApplication = [];
1052
+ for (const declaration of mustGet(declarationsByKey, variable.key)) {
1053
+ if (declaration.variable === variable) continue;
1054
+ const fromPackage = declaration.contract.packageOrigin !== void 0;
1055
+ if (!fromPackage && contract.packageOrigin === void 0) continue;
1056
+ (fromPackage ? fromPackages : fromApplication).push(declaration);
1057
+ }
1058
+ return fromPackages.length + fromApplication.length === 0 ? variable : filled(variable, fromPackages, fromApplication);
1059
+ })
1060
+ }));
1061
+ }
1062
+ function donated(read, fromPackages, fromApplication) {
1063
+ const fromPackage = fromPackages.find(({ variable }) => read(variable) !== void 0);
1064
+ if (fromPackage !== void 0) return read(fromPackage.variable);
1065
+ const values = fromApplication.map(({ variable }) => read(variable)).filter((v) => v !== void 0);
1066
+ return values.every((value) => deepEqual(value, values[0])) ? values[0] : void 0;
1067
+ }
1068
+ function filled(variable, fromPackages, fromApplication) {
1069
+ const donors = [...fromPackages, ...fromApplication];
1070
+ const merged = { ...variable };
1071
+ for (const field of VALUE_FIELDS) {
1072
+ if (variable[field] !== void 0) continue;
1073
+ merged[field] = donated((other) => other[field], fromPackages, fromApplication);
1074
+ }
1075
+ const metadata = {};
1076
+ for (const key of new Set(
1077
+ donors.flatMap(({ variable: other }) => Object.keys(other.metadata ?? {}))
1078
+ )) {
1079
+ const value = donated((other) => other.metadata?.[key], fromPackages, fromApplication);
1080
+ if (value !== void 0) metadata[key] = value;
1081
+ }
1082
+ Object.assign(metadata, variable.metadata);
1083
+ const result = {
1084
+ ...merged,
1085
+ metadata: Object.keys(metadata).length === 0 ? variable.metadata : metadata,
1086
+ documented: variable.documented || donors.some(({ variable: other }) => other.documented)
1087
+ };
1088
+ DONATED.set(
1089
+ result,
1090
+ /* @__PURE__ */ new Set([
1091
+ ...VALUE_FIELDS.filter((field) => result[field] !== variable[field]),
1092
+ ...Object.keys(metadata).filter((key) => metadata[key] !== variable.metadata?.[key]).map((key) => `metadata.${key}`)
1093
+ ])
1094
+ );
1095
+ return result;
1096
+ }
1097
+ var DONATED = /* @__PURE__ */ new WeakMap();
1098
+ function donatedTo(variable) {
1099
+ return DONATED.get(variable) ?? /* @__PURE__ */ new Set();
1100
+ }
1008
1101
  function isWithinDirectory(baseDir, targetPath) {
1009
1102
  const relative = path6.relative(baseDir, targetPath);
1010
1103
  return relative !== ".." && !relative.startsWith(`..${path6.sep}`) && !path6.isAbsolute(relative);
@@ -1234,7 +1327,10 @@ async function fileExists(filePath, fs) {
1234
1327
  }
1235
1328
  return false;
1236
1329
  }
1237
- async function loadTsconfigPaths(root, tsconfigOption, fs) {
1330
+ function typescriptPath(file, separator) {
1331
+ return file.split(separator).join("/");
1332
+ }
1333
+ async function loadTsconfigPaths(product, root, tsconfigOption, fs) {
1238
1334
  if (tsconfigOption === false) return { resolution: void 0, warning: void 0 };
1239
1335
  const isExplicit = tsconfigOption !== void 0;
1240
1336
  const configFile = path6.resolve(root, tsconfigOption ?? "tsconfig.json");
@@ -1248,8 +1344,11 @@ async function loadTsconfigPaths(root, tsconfigOption, fs) {
1248
1344
  }
1249
1345
  };
1250
1346
  }
1251
- assertCompilerApi(ts);
1252
- const readResult = ts.readConfigFile(configFile, (p) => ts.sys.readFile(p));
1347
+ assertCompilerApi(product, ts);
1348
+ const readResult = ts.readConfigFile(
1349
+ typescriptPath(configFile, path6.sep),
1350
+ (p) => ts.sys.readFile(p)
1351
+ );
1253
1352
  if (readResult.error) {
1254
1353
  const detail = ts.flattenDiagnosticMessageText(readResult.error.messageText, ts.sys.newLine);
1255
1354
  return {
@@ -1284,6 +1383,11 @@ function resolveAliasImport(specifier, importingFile, resolution, cache) {
1284
1383
  return resolved;
1285
1384
  }
1286
1385
 
1386
+ // src/build/resolution/resolve-tsconfig-paths.ts
1387
+ function loadTsconfigPaths2(root, tsconfigOption, fs) {
1388
+ return loadTsconfigPaths("env-cap", root, tsconfigOption, fs);
1389
+ }
1390
+
1287
1391
  // src/build/resolution/resolve-import.ts
1288
1392
  async function resolveRelativeImport(importingFile, specifier, fs) {
1289
1393
  if (!specifier.startsWith("./") && !specifier.startsWith("../")) return void 0;
@@ -1442,7 +1546,6 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1442
1546
  }
1443
1547
  const contracts = [];
1444
1548
  const undocumentedContracts = [];
1445
- const undocumentedVariables = [];
1446
1549
  const staleDocEntries = [];
1447
1550
  for (const entry of createEnvEntries) {
1448
1551
  const linked = documentEnvByIdentity.get(entry.identity);
@@ -1452,10 +1555,6 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1452
1555
  }
1453
1556
  const schemaKeys = new Set(entry.variables.map((v) => v.key));
1454
1557
  const docsVariables = docs?.variables ?? /* @__PURE__ */ new Map();
1455
- for (const key of schemaKeys) {
1456
- if (!docsVariables.has(key))
1457
- undocumentedVariables.push({ file: entry.file, exportName: entry.exportName, key });
1458
- }
1459
1558
  for (const key of docsVariables.keys()) {
1460
1559
  if (!schemaKeys.has(key))
1461
1560
  staleDocEntries.push({ file: entry.file, exportName: entry.exportName, key });
@@ -1517,12 +1616,17 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1517
1616
  for (const analysis of analysisCache.values()) {
1518
1617
  warnings.push(...analysis.warnings);
1519
1618
  }
1619
+ const merged = mergeSharedDocumentation(contracts);
1520
1620
  return {
1521
- contracts,
1621
+ contracts: merged,
1522
1622
  warnings,
1523
1623
  unresolvedLinks,
1624
+ // Judged after the merge: a variable a package's contract documents is documented for the application that
1625
+ // declares it again.
1626
+ undocumentedVariables: merged.flatMap(
1627
+ ({ file, exportName, variables }) => variables.filter(({ documented }) => !documented).map(({ key }) => ({ file, exportName, key }))
1628
+ ),
1524
1629
  undocumentedContracts,
1525
- undocumentedVariables,
1526
1630
  staleDocEntries
1527
1631
  };
1528
1632
  }
@@ -1582,7 +1686,7 @@ async function assembleProject(options) {
1582
1686
  packageFiles.map((f) => f.file),
1583
1687
  fs
1584
1688
  );
1585
- const { resolution: tsconfigPaths, warning: tsconfigWarning } = await loadTsconfigPaths(
1689
+ const { resolution: tsconfigPaths, warning: tsconfigWarning } = await loadTsconfigPaths2(
1586
1690
  root,
1587
1691
  tsconfig,
1588
1692
  fs
@@ -1647,24 +1751,20 @@ function buildChangeModel(manifest, currentContracts, root) {
1647
1751
  }
1648
1752
 
1649
1753
  // src/build/compatibility.ts
1650
- var DOCUMENTATION_COMPARISON_FIELDS = [
1651
- "description",
1652
- "owner",
1653
- "sensitivity",
1654
- "expiresAt",
1655
- "refreshInstructions",
1656
- "setupInstructions",
1657
- "required"
1658
- ];
1659
1754
  function documentationDivergences(a, b) {
1660
1755
  const divergences = [];
1661
- for (const field of DOCUMENTATION_COMPARISON_FIELDS) {
1662
- if (a[field] !== b[field]) divergences.push(field);
1756
+ const given = /* @__PURE__ */ new Set([...donatedTo(a), ...donatedTo(b)]);
1757
+ for (const field of VALUE_FIELDS) {
1758
+ if (!given.has(field) && a[field] !== void 0 && b[field] !== void 0 && !deepEqual(a[field], b[field])) {
1759
+ divergences.push(field);
1760
+ }
1663
1761
  }
1664
1762
  const aMetadata = a.metadata ?? {};
1665
1763
  const bMetadata = b.metadata ?? {};
1666
- for (const key of /* @__PURE__ */ new Set([...Object.keys(aMetadata), ...Object.keys(bMetadata)])) {
1667
- if (!deepEqual(aMetadata[key], bMetadata[key])) divergences.push(`metadata.${key}`);
1764
+ for (const key of Object.keys(aMetadata)) {
1765
+ if (!given.has(`metadata.${key}`) && key in bMetadata && !deepEqual(aMetadata[key], bMetadata[key])) {
1766
+ divergences.push(`metadata.${key}`);
1767
+ }
1668
1768
  }
1669
1769
  return divergences;
1670
1770
  }
@@ -1711,17 +1811,15 @@ function detectCompatibilityIssues(contracts) {
1711
1811
  reason: `"${a.contractName}" and "${b.contractName}" both declare a validator for this variable with different implementations. Validator logic cannot be statically compared -- confirm they enforce compatible rules.`
1712
1812
  });
1713
1813
  }
1714
- if (a.variable.documented && b.variable.documented) {
1715
- const divergences = documentationDivergences(a.variable, b.variable);
1716
- if (divergences.length > 0) {
1717
- issues.push({
1718
- severity: "warning",
1719
- variable: key,
1720
- files: [a.file, b.file],
1721
- code: "DUPLICATE_VARIABLE_DOCUMENTATION",
1722
- reason: `"${a.contractName}" and "${b.contractName}" both document this variable, but disagree on: ${divergences.join(", ")}. Confirm they're still meant to be the same variable and align the documentation, or document them separately if they're not.`
1723
- });
1724
- }
1814
+ const divergences = documentationDivergences(a.variable, b.variable);
1815
+ if (divergences.length > 0) {
1816
+ issues.push({
1817
+ severity: "warning",
1818
+ variable: key,
1819
+ files: [a.file, b.file],
1820
+ code: "DUPLICATE_VARIABLE_DOCUMENTATION",
1821
+ reason: `"${a.contractName}" and "${b.contractName}" both document this variable, but disagree on: ${divergences.join(", ")}. Confirm they're still meant to be the same variable and align the documentation, or document them separately if they're not.`
1822
+ });
1725
1823
  }
1726
1824
  }
1727
1825
  }
@@ -1989,7 +2087,7 @@ function bindingElementKey(element) {
1989
2087
  return element.propertyName;
1990
2088
  }
1991
2089
  function scanFileForDependencies(filePath, sourceText) {
1992
- assertCompilerApi(ts);
2090
+ assertCompilerApi2(ts);
1993
2091
  const scriptKind = filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
1994
2092
  const sourceFile = ts.createSourceFile(
1995
2093
  filePath,
@@ -2100,27 +2198,67 @@ function scanFileForDependencies(filePath, sourceText) {
2100
2198
  return { file: filePath, imports, accessesByLocalName: accesses, hasWildcardReExport };
2101
2199
  }
2102
2200
 
2201
+ // src/_ipc/generated-banner.ts
2202
+ function marker() {
2203
+ return "GENERATED FILE -- do not edit by hand";
2204
+ }
2205
+ function createGeneratedBanner(describe) {
2206
+ return {
2207
+ reportRegenerateHint: () => describe().reportRegenerateHint,
2208
+ generatedBanner: (format = "ts", regenerate = `Run \`${describe().cliCommand}\` to regenerate.`) => {
2209
+ const text = `${marker()}. ${regenerate}`;
2210
+ return { ts: `// ${text}`, markdown: `<!-- ${text} -->` }[format];
2211
+ },
2212
+ // Not a bare `startsWith`: a shebang, a `"use strict"` pragma or a license header pushes a real marker
2213
+ // off line one, and a stricter check would read a genuinely generated file as hand-written, which a
2214
+ // dependency scan would take as "a real consumer imports this" and so permanently mask an abandoned
2215
+ // contract. The first 20 non-empty lines clear every realistic preamble without scanning a whole file.
2216
+ // A line counts only when the marker opens a comment, as `generatedBanner` writes it, so code or prose that
2217
+ // merely quotes the marker is not mistaken for a generated file.
2218
+ isGeneratedFile: (content) => {
2219
+ let seen = 0;
2220
+ for (const [line] of content.matchAll(/[^\n]*/g)) {
2221
+ const text = line.trimStart();
2222
+ if (text === "") continue;
2223
+ if (text.startsWith(`// ${marker()}`) || text.startsWith(`<!-- ${marker()}`)) return true;
2224
+ seen += 1;
2225
+ if (seen === 20) break;
2226
+ }
2227
+ return false;
2228
+ },
2229
+ evidenceDisclaimer: () => "Machine-generated engineering artifact assembled from statically-provable code facts and author-declared documentation. It can support a security, privacy, or compliance review. It does not itself establish compliance with any standard.",
2230
+ evidenceProjectionNote: (evidencePath) => {
2231
+ const { product, guideUrl } = describe();
2232
+ const concept = `Projected from ${product}'s Evidence Model (${guideUrl}), the same source every other generated artifact draws from.`;
2233
+ return evidencePath === void 0 ? concept : `${concept} This run also wrote it to \`${evidencePath}\`.`;
2234
+ }
2235
+ };
2236
+ }
2237
+
2103
2238
  // src/build/generated-banner.ts
2104
- function generatedFileMarker() {
2105
- return "GENERATED FILE";
2239
+ function envCap() {
2240
+ return {
2241
+ product: "env-cap",
2242
+ guideUrl: "https://github.com/MaverickCER/env-cap/blob/main/GUIDE.md",
2243
+ cliCommand: "npx env-cap",
2244
+ reportRegenerateHint: "Regenerate it by re-running the script that calls `generateDocumentation()` / `generateUsageReport()` from `@maverickcer/env-cap/build`."
2245
+ };
2106
2246
  }
2247
+ var banner = createGeneratedBanner(envCap);
2107
2248
  function reportRegenerateHint() {
2108
- return "Regenerate it by re-running the script that calls `generateDocumentation()` / `generateUsageReport()` from `@maverickcer/env-cap/build`.";
2249
+ return banner.reportRegenerateHint();
2109
2250
  }
2110
- function generatedBanner(format = "ts", regenerate = "Run `npx env-cap` to regenerate.") {
2111
- const text = `${generatedFileMarker()} -- do not edit by hand. ${regenerate}`;
2112
- return { ts: `// ${text}`, markdown: `<!-- ${text} -->` }[format];
2251
+ function generatedBanner(format, regenerate) {
2252
+ return banner.generatedBanner(format, regenerate);
2113
2253
  }
2114
2254
  function isGeneratedFile(content) {
2115
- const nonEmptyLines = content.split("\n").filter((line) => line.trim().length > 0);
2116
- return nonEmptyLines.slice(0, 20).some((line) => line.includes(generatedFileMarker()));
2255
+ return banner.isGeneratedFile(content);
2117
2256
  }
2118
2257
  function evidenceDisclaimer() {
2119
- return "Machine-generated engineering artifact assembled from statically-provable code facts and author-declared documentation. It can support a security, privacy, or compliance review. It does not itself establish compliance with any standard.";
2258
+ return banner.evidenceDisclaimer();
2120
2259
  }
2121
2260
  function evidenceProjectionNote(evidencePath) {
2122
- const concept = "Projected from env-cap's Evidence Model (https://github.com/MaverickCER/env-cap/blob/main/GUIDE.md), the same source every other generated artifact draws from.";
2123
- return evidencePath === void 0 ? concept : `${concept} This run also wrote it to \`${evidencePath}\`.`;
2261
+ return banner.evidenceProjectionNote(evidencePath);
2124
2262
  }
2125
2263
 
2126
2264
  // src/build/dependency-graph.ts
@@ -4337,7 +4475,7 @@ function buildOwnershipModel(contracts, root) {
4337
4475
 
4338
4476
  // src/build/tool-version.ts
4339
4477
  function readToolVersion() {
4340
- return "0.6.0";
4478
+ return "0.7.0";
4341
4479
  }
4342
4480
 
4343
4481
  // src/build/generate-evidence.ts