@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.cjs CHANGED
@@ -12,9 +12,10 @@ var crypto__default = /*#__PURE__*/_interopDefault(crypto);
12
12
  // node_modules/tsup/assets/cjs_shims.js
13
13
  var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
14
14
  var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
15
- function displayPath(root, absolutePath) {
16
- const relative = path6__default.default.relative(root, absolutePath);
17
- if (relative.startsWith("..") || path6__default.default.isAbsolute(relative)) return absolutePath;
15
+ function displayPath(root, filePath) {
16
+ if (!path6__default.default.isAbsolute(filePath)) return filePath.split(path6__default.default.sep).join("/");
17
+ const relative = path6__default.default.relative(root, filePath);
18
+ if (relative.startsWith("..") || path6__default.default.isAbsolute(relative)) return filePath;
18
19
  return relative.split(path6__default.default.sep).join("/");
19
20
  }
20
21
 
@@ -340,7 +341,7 @@ async function computeEvidenceChanges(root, snapshotPath, activeContracts, curre
340
341
  };
341
342
  }
342
343
 
343
- // src/build/glob.ts
344
+ // src/_ipc/glob.ts
344
345
  function globToRegExp(pattern) {
345
346
  let out = "";
346
347
  let resume = 0;
@@ -436,14 +437,19 @@ function pickCompiler(load) {
436
437
  }
437
438
  var ts = pickCompiler(module$1.createRequire(importMetaUrl));
438
439
 
439
- // src/build/compiler-api.ts
440
- function assertCompilerApi(compiler) {
440
+ // src/_ipc/compiler-api.ts
441
+ function assertCompilerApi(product, compiler) {
441
442
  if (typeof compiler.createSourceFile === "function") return;
442
443
  throw new Error(
443
- `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'.`
444
+ `${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'.`
444
445
  );
445
446
  }
446
447
 
448
+ // src/build/compiler-api.ts
449
+ function assertCompilerApi2(compiler) {
450
+ assertCompilerApi("env-cap", compiler);
451
+ }
452
+
447
453
  // src/build/literal-eval.ts
448
454
  function evaluateLiteral(node) {
449
455
  if (ts.isStringLiteralLike(node)) return { ok: true, value: node.text };
@@ -488,7 +494,7 @@ function getStaticPropertyName(name) {
488
494
 
489
495
  // src/build/parse.ts
490
496
  function parseSchemaFile(filePath, sourceText) {
491
- assertCompilerApi(ts);
497
+ assertCompilerApi2(ts);
492
498
  const sourceFile = ts.createSourceFile(
493
499
  filePath,
494
500
  sourceText,
@@ -1014,6 +1020,93 @@ function mustGet(map, key) {
1014
1020
  throw new Error(`Internal error: expected key "${String(key)}" to be present in map.`);
1015
1021
  return value;
1016
1022
  }
1023
+
1024
+ // src/build/merge-documentation.ts
1025
+ var VALUE_FIELDS = [
1026
+ "description",
1027
+ "owner",
1028
+ "sensitivity",
1029
+ "expiresAt",
1030
+ "refreshInstructions",
1031
+ "authenticatorType",
1032
+ "rotationPeriod",
1033
+ "lastRotatedAt",
1034
+ "rotationTriggerEvents",
1035
+ "setupInstructions",
1036
+ "required",
1037
+ "deprecated",
1038
+ "deprecatedReason",
1039
+ "removeBy",
1040
+ "renamedFrom",
1041
+ "purpose",
1042
+ "legalBasis",
1043
+ "retention",
1044
+ "dataResidency",
1045
+ "auditRequired"
1046
+ ];
1047
+ function mergeSharedDocumentation(contracts) {
1048
+ const declarationsByKey = /* @__PURE__ */ new Map();
1049
+ for (const contract of contracts) {
1050
+ for (const variable of contract.variables) {
1051
+ const declarations = declarationsByKey.get(variable.key);
1052
+ if (declarations === void 0) declarationsByKey.set(variable.key, [{ contract, variable }]);
1053
+ else declarations.push({ contract, variable });
1054
+ }
1055
+ }
1056
+ return contracts.map((contract) => ({
1057
+ ...contract,
1058
+ variables: contract.variables.map((variable) => {
1059
+ const fromPackages = [];
1060
+ const fromApplication = [];
1061
+ for (const declaration of mustGet(declarationsByKey, variable.key)) {
1062
+ if (declaration.variable === variable) continue;
1063
+ const fromPackage = declaration.contract.packageOrigin !== void 0;
1064
+ if (!fromPackage && contract.packageOrigin === void 0) continue;
1065
+ (fromPackage ? fromPackages : fromApplication).push(declaration);
1066
+ }
1067
+ return fromPackages.length + fromApplication.length === 0 ? variable : filled(variable, fromPackages, fromApplication);
1068
+ })
1069
+ }));
1070
+ }
1071
+ function donated(read, fromPackages, fromApplication) {
1072
+ const fromPackage = fromPackages.find(({ variable }) => read(variable) !== void 0);
1073
+ if (fromPackage !== void 0) return read(fromPackage.variable);
1074
+ const values = fromApplication.map(({ variable }) => read(variable)).filter((v) => v !== void 0);
1075
+ return values.every((value) => deepEqual(value, values[0])) ? values[0] : void 0;
1076
+ }
1077
+ function filled(variable, fromPackages, fromApplication) {
1078
+ const donors = [...fromPackages, ...fromApplication];
1079
+ const merged = { ...variable };
1080
+ for (const field of VALUE_FIELDS) {
1081
+ if (variable[field] !== void 0) continue;
1082
+ merged[field] = donated((other) => other[field], fromPackages, fromApplication);
1083
+ }
1084
+ const metadata = {};
1085
+ for (const key of new Set(
1086
+ donors.flatMap(({ variable: other }) => Object.keys(other.metadata ?? {}))
1087
+ )) {
1088
+ const value = donated((other) => other.metadata?.[key], fromPackages, fromApplication);
1089
+ if (value !== void 0) metadata[key] = value;
1090
+ }
1091
+ Object.assign(metadata, variable.metadata);
1092
+ const result = {
1093
+ ...merged,
1094
+ metadata: Object.keys(metadata).length === 0 ? variable.metadata : metadata,
1095
+ documented: variable.documented || donors.some(({ variable: other }) => other.documented)
1096
+ };
1097
+ DONATED.set(
1098
+ result,
1099
+ /* @__PURE__ */ new Set([
1100
+ ...VALUE_FIELDS.filter((field) => result[field] !== variable[field]),
1101
+ ...Object.keys(metadata).filter((key) => metadata[key] !== variable.metadata?.[key]).map((key) => `metadata.${key}`)
1102
+ ])
1103
+ );
1104
+ return result;
1105
+ }
1106
+ var DONATED = /* @__PURE__ */ new WeakMap();
1107
+ function donatedTo(variable) {
1108
+ return DONATED.get(variable) ?? /* @__PURE__ */ new Set();
1109
+ }
1017
1110
  function isWithinDirectory(baseDir, targetPath) {
1018
1111
  const relative = path6__default.default.relative(baseDir, targetPath);
1019
1112
  return relative !== ".." && !relative.startsWith(`..${path6__default.default.sep}`) && !path6__default.default.isAbsolute(relative);
@@ -1243,7 +1336,10 @@ async function fileExists(filePath, fs) {
1243
1336
  }
1244
1337
  return false;
1245
1338
  }
1246
- async function loadTsconfigPaths(root, tsconfigOption, fs) {
1339
+ function typescriptPath(file, separator) {
1340
+ return file.split(separator).join("/");
1341
+ }
1342
+ async function loadTsconfigPaths(product, root, tsconfigOption, fs) {
1247
1343
  if (tsconfigOption === false) return { resolution: void 0, warning: void 0 };
1248
1344
  const isExplicit = tsconfigOption !== void 0;
1249
1345
  const configFile = path6__default.default.resolve(root, tsconfigOption ?? "tsconfig.json");
@@ -1257,8 +1353,11 @@ async function loadTsconfigPaths(root, tsconfigOption, fs) {
1257
1353
  }
1258
1354
  };
1259
1355
  }
1260
- assertCompilerApi(ts);
1261
- const readResult = ts.readConfigFile(configFile, (p) => ts.sys.readFile(p));
1356
+ assertCompilerApi(product, ts);
1357
+ const readResult = ts.readConfigFile(
1358
+ typescriptPath(configFile, path6__default.default.sep),
1359
+ (p) => ts.sys.readFile(p)
1360
+ );
1262
1361
  if (readResult.error) {
1263
1362
  const detail = ts.flattenDiagnosticMessageText(readResult.error.messageText, ts.sys.newLine);
1264
1363
  return {
@@ -1293,6 +1392,11 @@ function resolveAliasImport(specifier, importingFile, resolution, cache) {
1293
1392
  return resolved;
1294
1393
  }
1295
1394
 
1395
+ // src/build/resolution/resolve-tsconfig-paths.ts
1396
+ function loadTsconfigPaths2(root, tsconfigOption, fs) {
1397
+ return loadTsconfigPaths("env-cap", root, tsconfigOption, fs);
1398
+ }
1399
+
1296
1400
  // src/build/resolution/resolve-import.ts
1297
1401
  async function resolveRelativeImport(importingFile, specifier, fs) {
1298
1402
  if (!specifier.startsWith("./") && !specifier.startsWith("../")) return void 0;
@@ -1451,7 +1555,6 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1451
1555
  }
1452
1556
  const contracts = [];
1453
1557
  const undocumentedContracts = [];
1454
- const undocumentedVariables = [];
1455
1558
  const staleDocEntries = [];
1456
1559
  for (const entry of createEnvEntries) {
1457
1560
  const linked = documentEnvByIdentity.get(entry.identity);
@@ -1461,10 +1564,6 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1461
1564
  }
1462
1565
  const schemaKeys = new Set(entry.variables.map((v) => v.key));
1463
1566
  const docsVariables = docs?.variables ?? /* @__PURE__ */ new Map();
1464
- for (const key of schemaKeys) {
1465
- if (!docsVariables.has(key))
1466
- undocumentedVariables.push({ file: entry.file, exportName: entry.exportName, key });
1467
- }
1468
1567
  for (const key of docsVariables.keys()) {
1469
1568
  if (!schemaKeys.has(key))
1470
1569
  staleDocEntries.push({ file: entry.file, exportName: entry.exportName, key });
@@ -1526,12 +1625,17 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1526
1625
  for (const analysis of analysisCache.values()) {
1527
1626
  warnings.push(...analysis.warnings);
1528
1627
  }
1628
+ const merged = mergeSharedDocumentation(contracts);
1529
1629
  return {
1530
- contracts,
1630
+ contracts: merged,
1531
1631
  warnings,
1532
1632
  unresolvedLinks,
1633
+ // Judged after the merge: a variable a package's contract documents is documented for the application that
1634
+ // declares it again.
1635
+ undocumentedVariables: merged.flatMap(
1636
+ ({ file, exportName, variables }) => variables.filter(({ documented }) => !documented).map(({ key }) => ({ file, exportName, key }))
1637
+ ),
1533
1638
  undocumentedContracts,
1534
- undocumentedVariables,
1535
1639
  staleDocEntries
1536
1640
  };
1537
1641
  }
@@ -1591,7 +1695,7 @@ async function assembleProject(options) {
1591
1695
  packageFiles.map((f) => f.file),
1592
1696
  fs
1593
1697
  );
1594
- const { resolution: tsconfigPaths, warning: tsconfigWarning } = await loadTsconfigPaths(
1698
+ const { resolution: tsconfigPaths, warning: tsconfigWarning } = await loadTsconfigPaths2(
1595
1699
  root,
1596
1700
  tsconfig,
1597
1701
  fs
@@ -1656,24 +1760,20 @@ function buildChangeModel(manifest, currentContracts, root) {
1656
1760
  }
1657
1761
 
1658
1762
  // src/build/compatibility.ts
1659
- var DOCUMENTATION_COMPARISON_FIELDS = [
1660
- "description",
1661
- "owner",
1662
- "sensitivity",
1663
- "expiresAt",
1664
- "refreshInstructions",
1665
- "setupInstructions",
1666
- "required"
1667
- ];
1668
1763
  function documentationDivergences(a, b) {
1669
1764
  const divergences = [];
1670
- for (const field of DOCUMENTATION_COMPARISON_FIELDS) {
1671
- if (a[field] !== b[field]) divergences.push(field);
1765
+ const given = /* @__PURE__ */ new Set([...donatedTo(a), ...donatedTo(b)]);
1766
+ for (const field of VALUE_FIELDS) {
1767
+ if (!given.has(field) && a[field] !== void 0 && b[field] !== void 0 && !deepEqual(a[field], b[field])) {
1768
+ divergences.push(field);
1769
+ }
1672
1770
  }
1673
1771
  const aMetadata = a.metadata ?? {};
1674
1772
  const bMetadata = b.metadata ?? {};
1675
- for (const key of /* @__PURE__ */ new Set([...Object.keys(aMetadata), ...Object.keys(bMetadata)])) {
1676
- if (!deepEqual(aMetadata[key], bMetadata[key])) divergences.push(`metadata.${key}`);
1773
+ for (const key of Object.keys(aMetadata)) {
1774
+ if (!given.has(`metadata.${key}`) && key in bMetadata && !deepEqual(aMetadata[key], bMetadata[key])) {
1775
+ divergences.push(`metadata.${key}`);
1776
+ }
1677
1777
  }
1678
1778
  return divergences;
1679
1779
  }
@@ -1720,17 +1820,15 @@ function detectCompatibilityIssues(contracts) {
1720
1820
  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.`
1721
1821
  });
1722
1822
  }
1723
- if (a.variable.documented && b.variable.documented) {
1724
- const divergences = documentationDivergences(a.variable, b.variable);
1725
- if (divergences.length > 0) {
1726
- issues.push({
1727
- severity: "warning",
1728
- variable: key,
1729
- files: [a.file, b.file],
1730
- code: "DUPLICATE_VARIABLE_DOCUMENTATION",
1731
- 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.`
1732
- });
1733
- }
1823
+ const divergences = documentationDivergences(a.variable, b.variable);
1824
+ if (divergences.length > 0) {
1825
+ issues.push({
1826
+ severity: "warning",
1827
+ variable: key,
1828
+ files: [a.file, b.file],
1829
+ code: "DUPLICATE_VARIABLE_DOCUMENTATION",
1830
+ 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.`
1831
+ });
1734
1832
  }
1735
1833
  }
1736
1834
  }
@@ -1998,7 +2096,7 @@ function bindingElementKey(element) {
1998
2096
  return element.propertyName;
1999
2097
  }
2000
2098
  function scanFileForDependencies(filePath, sourceText) {
2001
- assertCompilerApi(ts);
2099
+ assertCompilerApi2(ts);
2002
2100
  const scriptKind = filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
2003
2101
  const sourceFile = ts.createSourceFile(
2004
2102
  filePath,
@@ -2109,27 +2207,67 @@ function scanFileForDependencies(filePath, sourceText) {
2109
2207
  return { file: filePath, imports, accessesByLocalName: accesses, hasWildcardReExport };
2110
2208
  }
2111
2209
 
2210
+ // src/_ipc/generated-banner.ts
2211
+ function marker() {
2212
+ return "GENERATED FILE -- do not edit by hand";
2213
+ }
2214
+ function createGeneratedBanner(describe) {
2215
+ return {
2216
+ reportRegenerateHint: () => describe().reportRegenerateHint,
2217
+ generatedBanner: (format = "ts", regenerate = `Run \`${describe().cliCommand}\` to regenerate.`) => {
2218
+ const text = `${marker()}. ${regenerate}`;
2219
+ return { ts: `// ${text}`, markdown: `<!-- ${text} -->` }[format];
2220
+ },
2221
+ // Not a bare `startsWith`: a shebang, a `"use strict"` pragma or a license header pushes a real marker
2222
+ // off line one, and a stricter check would read a genuinely generated file as hand-written, which a
2223
+ // dependency scan would take as "a real consumer imports this" and so permanently mask an abandoned
2224
+ // contract. The first 20 non-empty lines clear every realistic preamble without scanning a whole file.
2225
+ // A line counts only when the marker opens a comment, as `generatedBanner` writes it, so code or prose that
2226
+ // merely quotes the marker is not mistaken for a generated file.
2227
+ isGeneratedFile: (content) => {
2228
+ let seen = 0;
2229
+ for (const [line] of content.matchAll(/[^\n]*/g)) {
2230
+ const text = line.trimStart();
2231
+ if (text === "") continue;
2232
+ if (text.startsWith(`// ${marker()}`) || text.startsWith(`<!-- ${marker()}`)) return true;
2233
+ seen += 1;
2234
+ if (seen === 20) break;
2235
+ }
2236
+ return false;
2237
+ },
2238
+ 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.",
2239
+ evidenceProjectionNote: (evidencePath) => {
2240
+ const { product, guideUrl } = describe();
2241
+ const concept = `Projected from ${product}'s Evidence Model (${guideUrl}), the same source every other generated artifact draws from.`;
2242
+ return evidencePath === void 0 ? concept : `${concept} This run also wrote it to \`${evidencePath}\`.`;
2243
+ }
2244
+ };
2245
+ }
2246
+
2112
2247
  // src/build/generated-banner.ts
2113
- function generatedFileMarker() {
2114
- return "GENERATED FILE";
2248
+ function envCap() {
2249
+ return {
2250
+ product: "env-cap",
2251
+ guideUrl: "https://github.com/MaverickCER/env-cap/blob/main/GUIDE.md",
2252
+ cliCommand: "npx env-cap",
2253
+ reportRegenerateHint: "Regenerate it by re-running the script that calls `generateDocumentation()` / `generateUsageReport()` from `@maverickcer/env-cap/build`."
2254
+ };
2115
2255
  }
2256
+ var banner = createGeneratedBanner(envCap);
2116
2257
  function reportRegenerateHint() {
2117
- return "Regenerate it by re-running the script that calls `generateDocumentation()` / `generateUsageReport()` from `@maverickcer/env-cap/build`.";
2258
+ return banner.reportRegenerateHint();
2118
2259
  }
2119
- function generatedBanner(format = "ts", regenerate = "Run `npx env-cap` to regenerate.") {
2120
- const text = `${generatedFileMarker()} -- do not edit by hand. ${regenerate}`;
2121
- return { ts: `// ${text}`, markdown: `<!-- ${text} -->` }[format];
2260
+ function generatedBanner(format, regenerate) {
2261
+ return banner.generatedBanner(format, regenerate);
2122
2262
  }
2123
2263
  function isGeneratedFile(content) {
2124
- const nonEmptyLines = content.split("\n").filter((line) => line.trim().length > 0);
2125
- return nonEmptyLines.slice(0, 20).some((line) => line.includes(generatedFileMarker()));
2264
+ return banner.isGeneratedFile(content);
2126
2265
  }
2127
2266
  function evidenceDisclaimer() {
2128
- 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.";
2267
+ return banner.evidenceDisclaimer();
2129
2268
  }
2130
2269
  function evidenceProjectionNote(evidencePath) {
2131
- 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.";
2132
- return evidencePath === void 0 ? concept : `${concept} This run also wrote it to \`${evidencePath}\`.`;
2270
+ return banner.evidenceProjectionNote(evidencePath);
2133
2271
  }
2134
2272
 
2135
2273
  // src/build/dependency-graph.ts
@@ -4346,7 +4484,7 @@ function buildOwnershipModel(contracts, root) {
4346
4484
 
4347
4485
  // src/build/tool-version.ts
4348
4486
  function readToolVersion() {
4349
- return "0.6.0";
4487
+ return "0.7.0";
4350
4488
  }
4351
4489
 
4352
4490
  // src/build/generate-evidence.ts