@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
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  import {
3
3
  readToolVersion
4
- } from "./chunk-7GVPOHDU.js";
4
+ } from "./chunk-KEGYUHBU.js";
5
5
 
6
6
  // src/build/evidence-snapshot.ts
7
7
  import path3 from "path";
@@ -10,11 +10,12 @@ import path3 from "path";
10
10
  import crypto from "crypto";
11
11
  import path2 from "path";
12
12
 
13
- // src/build/display-path.ts
13
+ // src/_ipc/display-path.ts
14
14
  import path from "path";
15
- function displayPath(root, absolutePath) {
16
- const relative = path.relative(root, absolutePath);
17
- if (relative.startsWith("..") || path.isAbsolute(relative)) return absolutePath;
15
+ function displayPath(root, filePath) {
16
+ if (!path.isAbsolute(filePath)) return filePath.split(path.sep).join("/");
17
+ const relative = path.relative(root, filePath);
18
+ if (relative.startsWith("..") || path.isAbsolute(relative)) return filePath;
18
19
  return relative.split(path.sep).join("/");
19
20
  }
20
21
 
@@ -346,7 +347,7 @@ import path17 from "path";
346
347
  // src/build/discover.ts
347
348
  import path4 from "path";
348
349
 
349
- // src/build/glob.ts
350
+ // src/_ipc/glob.ts
350
351
  function globToRegExp(pattern) {
351
352
  let out = "";
352
353
  let resume = 0;
@@ -421,7 +422,7 @@ function matchesAnyPattern(filePath, patterns) {
421
422
  // src/build/link.ts
422
423
  import path9 from "path";
423
424
 
424
- // src/build/typescript.ts
425
+ // src/_ipc/typescript.ts
425
426
  import { createRequire } from "module";
426
427
  function hasClassicApi(candidate) {
427
428
  return typeof candidate?.createSourceFile === "function";
@@ -448,14 +449,19 @@ function pickCompiler(load) {
448
449
  }
449
450
  var ts = pickCompiler(createRequire(import.meta.url));
450
451
 
451
- // src/build/compiler-api.ts
452
- function assertCompilerApi(compiler) {
452
+ // src/_ipc/compiler-api.ts
453
+ function assertCompilerApi(product, compiler) {
453
454
  if (typeof compiler.createSourceFile === "function") return;
454
455
  throw new Error(
455
- `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'.`
456
+ `${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'.`
456
457
  );
457
458
  }
458
459
 
460
+ // src/build/compiler-api.ts
461
+ function assertCompilerApi2(compiler) {
462
+ assertCompilerApi("env-cap", compiler);
463
+ }
464
+
459
465
  // src/build/literal-eval.ts
460
466
  function evaluateLiteral(node) {
461
467
  if (ts.isStringLiteralLike(node)) return { ok: true, value: node.text };
@@ -500,7 +506,7 @@ function getStaticPropertyName(name) {
500
506
 
501
507
  // src/build/parse.ts
502
508
  function parseSchemaFile(filePath, sourceText) {
503
- assertCompilerApi(ts);
509
+ assertCompilerApi2(ts);
504
510
  const sourceFile = ts.createSourceFile(
505
511
  filePath,
506
512
  sourceText,
@@ -1027,6 +1033,93 @@ function mustGet(map, key) {
1027
1033
  return value;
1028
1034
  }
1029
1035
 
1036
+ // src/build/merge-documentation.ts
1037
+ var VALUE_FIELDS = [
1038
+ "description",
1039
+ "owner",
1040
+ "sensitivity",
1041
+ "expiresAt",
1042
+ "refreshInstructions",
1043
+ "authenticatorType",
1044
+ "rotationPeriod",
1045
+ "lastRotatedAt",
1046
+ "rotationTriggerEvents",
1047
+ "setupInstructions",
1048
+ "required",
1049
+ "deprecated",
1050
+ "deprecatedReason",
1051
+ "removeBy",
1052
+ "renamedFrom",
1053
+ "purpose",
1054
+ "legalBasis",
1055
+ "retention",
1056
+ "dataResidency",
1057
+ "auditRequired"
1058
+ ];
1059
+ function mergeSharedDocumentation(contracts) {
1060
+ const declarationsByKey = /* @__PURE__ */ new Map();
1061
+ for (const contract of contracts) {
1062
+ for (const variable of contract.variables) {
1063
+ const declarations = declarationsByKey.get(variable.key);
1064
+ if (declarations === void 0) declarationsByKey.set(variable.key, [{ contract, variable }]);
1065
+ else declarations.push({ contract, variable });
1066
+ }
1067
+ }
1068
+ return contracts.map((contract) => ({
1069
+ ...contract,
1070
+ variables: contract.variables.map((variable) => {
1071
+ const fromPackages = [];
1072
+ const fromApplication = [];
1073
+ for (const declaration of mustGet(declarationsByKey, variable.key)) {
1074
+ if (declaration.variable === variable) continue;
1075
+ const fromPackage = declaration.contract.packageOrigin !== void 0;
1076
+ if (!fromPackage && contract.packageOrigin === void 0) continue;
1077
+ (fromPackage ? fromPackages : fromApplication).push(declaration);
1078
+ }
1079
+ return fromPackages.length + fromApplication.length === 0 ? variable : filled(variable, fromPackages, fromApplication);
1080
+ })
1081
+ }));
1082
+ }
1083
+ function donated(read, fromPackages, fromApplication) {
1084
+ const fromPackage = fromPackages.find(({ variable }) => read(variable) !== void 0);
1085
+ if (fromPackage !== void 0) return read(fromPackage.variable);
1086
+ const values = fromApplication.map(({ variable }) => read(variable)).filter((v) => v !== void 0);
1087
+ return values.every((value) => deepEqual(value, values[0])) ? values[0] : void 0;
1088
+ }
1089
+ function filled(variable, fromPackages, fromApplication) {
1090
+ const donors = [...fromPackages, ...fromApplication];
1091
+ const merged = { ...variable };
1092
+ for (const field of VALUE_FIELDS) {
1093
+ if (variable[field] !== void 0) continue;
1094
+ merged[field] = donated((other) => other[field], fromPackages, fromApplication);
1095
+ }
1096
+ const metadata = {};
1097
+ for (const key of new Set(
1098
+ donors.flatMap(({ variable: other }) => Object.keys(other.metadata ?? {}))
1099
+ )) {
1100
+ const value = donated((other) => other.metadata?.[key], fromPackages, fromApplication);
1101
+ if (value !== void 0) metadata[key] = value;
1102
+ }
1103
+ Object.assign(metadata, variable.metadata);
1104
+ const result = {
1105
+ ...merged,
1106
+ metadata: Object.keys(metadata).length === 0 ? variable.metadata : metadata,
1107
+ documented: variable.documented || donors.some(({ variable: other }) => other.documented)
1108
+ };
1109
+ DONATED.set(
1110
+ result,
1111
+ /* @__PURE__ */ new Set([
1112
+ ...VALUE_FIELDS.filter((field) => result[field] !== variable[field]),
1113
+ ...Object.keys(metadata).filter((key) => metadata[key] !== variable.metadata?.[key]).map((key) => `metadata.${key}`)
1114
+ ])
1115
+ );
1116
+ return result;
1117
+ }
1118
+ var DONATED = /* @__PURE__ */ new WeakMap();
1119
+ function donatedTo(variable) {
1120
+ return DONATED.get(variable) ?? /* @__PURE__ */ new Set();
1121
+ }
1122
+
1030
1123
  // src/build/resolution/resolve-import.ts
1031
1124
  import path8 from "path";
1032
1125
 
@@ -1253,7 +1346,7 @@ async function resolvePackageImport(specifier, allowedPackages, root, cache, fs)
1253
1346
  return result.ok ? result.origin.resolvedFile : void 0;
1254
1347
  }
1255
1348
 
1256
- // src/build/resolution/resolve-tsconfig-paths.ts
1349
+ // src/_ipc/resolve-tsconfig-paths.ts
1257
1350
  import path7 from "path";
1258
1351
  function pathMappingOptions(options) {
1259
1352
  return options;
@@ -1268,7 +1361,10 @@ async function fileExists(filePath, fs) {
1268
1361
  }
1269
1362
  return false;
1270
1363
  }
1271
- async function loadTsconfigPaths(root, tsconfigOption, fs) {
1364
+ function typescriptPath(file, separator) {
1365
+ return file.split(separator).join("/");
1366
+ }
1367
+ async function loadTsconfigPaths(product, root, tsconfigOption, fs) {
1272
1368
  if (tsconfigOption === false) return { resolution: void 0, warning: void 0 };
1273
1369
  const isExplicit = tsconfigOption !== void 0;
1274
1370
  const configFile = path7.resolve(root, tsconfigOption ?? "tsconfig.json");
@@ -1282,8 +1378,11 @@ async function loadTsconfigPaths(root, tsconfigOption, fs) {
1282
1378
  }
1283
1379
  };
1284
1380
  }
1285
- assertCompilerApi(ts);
1286
- const readResult = ts.readConfigFile(configFile, (p) => ts.sys.readFile(p));
1381
+ assertCompilerApi(product, ts);
1382
+ const readResult = ts.readConfigFile(
1383
+ typescriptPath(configFile, path7.sep),
1384
+ (p) => ts.sys.readFile(p)
1385
+ );
1287
1386
  if (readResult.error) {
1288
1387
  const detail = ts.flattenDiagnosticMessageText(readResult.error.messageText, ts.sys.newLine);
1289
1388
  return {
@@ -1318,6 +1417,11 @@ function resolveAliasImport(specifier, importingFile, resolution, cache) {
1318
1417
  return resolved;
1319
1418
  }
1320
1419
 
1420
+ // src/build/resolution/resolve-tsconfig-paths.ts
1421
+ function loadTsconfigPaths2(root, tsconfigOption, fs) {
1422
+ return loadTsconfigPaths("env-cap", root, tsconfigOption, fs);
1423
+ }
1424
+
1321
1425
  // src/build/resolution/resolve-import.ts
1322
1426
  async function resolveRelativeImport(importingFile, specifier, fs) {
1323
1427
  if (!specifier.startsWith("./") && !specifier.startsWith("../")) return void 0;
@@ -1476,7 +1580,6 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1476
1580
  }
1477
1581
  const contracts = [];
1478
1582
  const undocumentedContracts = [];
1479
- const undocumentedVariables = [];
1480
1583
  const staleDocEntries = [];
1481
1584
  for (const entry of createEnvEntries) {
1482
1585
  const linked = documentEnvByIdentity.get(entry.identity);
@@ -1486,10 +1589,6 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1486
1589
  }
1487
1590
  const schemaKeys = new Set(entry.variables.map((v) => v.key));
1488
1591
  const docsVariables = docs?.variables ?? /* @__PURE__ */ new Map();
1489
- for (const key of schemaKeys) {
1490
- if (!docsVariables.has(key))
1491
- undocumentedVariables.push({ file: entry.file, exportName: entry.exportName, key });
1492
- }
1493
1592
  for (const key of docsVariables.keys()) {
1494
1593
  if (!schemaKeys.has(key))
1495
1594
  staleDocEntries.push({ file: entry.file, exportName: entry.exportName, key });
@@ -1551,12 +1650,17 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1551
1650
  for (const analysis of analysisCache.values()) {
1552
1651
  warnings.push(...analysis.warnings);
1553
1652
  }
1653
+ const merged = mergeSharedDocumentation(contracts);
1554
1654
  return {
1555
- contracts,
1655
+ contracts: merged,
1556
1656
  warnings,
1557
1657
  unresolvedLinks,
1658
+ // Judged after the merge: a variable a package's contract documents is documented for the application that
1659
+ // declares it again.
1660
+ undocumentedVariables: merged.flatMap(
1661
+ ({ file, exportName, variables }) => variables.filter(({ documented }) => !documented).map(({ key }) => ({ file, exportName, key }))
1662
+ ),
1558
1663
  undocumentedContracts,
1559
- undocumentedVariables,
1560
1664
  staleDocEntries
1561
1665
  };
1562
1666
  }
@@ -1616,7 +1720,7 @@ async function assembleProject(options) {
1616
1720
  packageFiles.map((f) => f.file),
1617
1721
  fs
1618
1722
  );
1619
- const { resolution: tsconfigPaths, warning: tsconfigWarning } = await loadTsconfigPaths(
1723
+ const { resolution: tsconfigPaths, warning: tsconfigWarning } = await loadTsconfigPaths2(
1620
1724
  root,
1621
1725
  tsconfig,
1622
1726
  fs
@@ -1681,24 +1785,20 @@ function buildChangeModel(manifest, currentContracts, root) {
1681
1785
  }
1682
1786
 
1683
1787
  // src/build/compatibility.ts
1684
- var DOCUMENTATION_COMPARISON_FIELDS = [
1685
- "description",
1686
- "owner",
1687
- "sensitivity",
1688
- "expiresAt",
1689
- "refreshInstructions",
1690
- "setupInstructions",
1691
- "required"
1692
- ];
1693
1788
  function documentationDivergences(a, b) {
1694
1789
  const divergences = [];
1695
- for (const field of DOCUMENTATION_COMPARISON_FIELDS) {
1696
- if (a[field] !== b[field]) divergences.push(field);
1790
+ const given = /* @__PURE__ */ new Set([...donatedTo(a), ...donatedTo(b)]);
1791
+ for (const field of VALUE_FIELDS) {
1792
+ if (!given.has(field) && a[field] !== void 0 && b[field] !== void 0 && !deepEqual(a[field], b[field])) {
1793
+ divergences.push(field);
1794
+ }
1697
1795
  }
1698
1796
  const aMetadata = a.metadata ?? {};
1699
1797
  const bMetadata = b.metadata ?? {};
1700
- for (const key of /* @__PURE__ */ new Set([...Object.keys(aMetadata), ...Object.keys(bMetadata)])) {
1701
- if (!deepEqual(aMetadata[key], bMetadata[key])) divergences.push(`metadata.${key}`);
1798
+ for (const key of Object.keys(aMetadata)) {
1799
+ if (!given.has(`metadata.${key}`) && key in bMetadata && !deepEqual(aMetadata[key], bMetadata[key])) {
1800
+ divergences.push(`metadata.${key}`);
1801
+ }
1702
1802
  }
1703
1803
  return divergences;
1704
1804
  }
@@ -1745,17 +1845,15 @@ function detectCompatibilityIssues(contracts) {
1745
1845
  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.`
1746
1846
  });
1747
1847
  }
1748
- if (a.variable.documented && b.variable.documented) {
1749
- const divergences = documentationDivergences(a.variable, b.variable);
1750
- if (divergences.length > 0) {
1751
- issues.push({
1752
- severity: "warning",
1753
- variable: key,
1754
- files: [a.file, b.file],
1755
- code: "DUPLICATE_VARIABLE_DOCUMENTATION",
1756
- 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.`
1757
- });
1758
- }
1848
+ const divergences = documentationDivergences(a.variable, b.variable);
1849
+ if (divergences.length > 0) {
1850
+ issues.push({
1851
+ severity: "warning",
1852
+ variable: key,
1853
+ files: [a.file, b.file],
1854
+ code: "DUPLICATE_VARIABLE_DOCUMENTATION",
1855
+ 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.`
1856
+ });
1759
1857
  }
1760
1858
  }
1761
1859
  }
@@ -2023,7 +2121,7 @@ function bindingElementKey(element) {
2023
2121
  return element.propertyName;
2024
2122
  }
2025
2123
  function scanFileForDependencies(filePath, sourceText) {
2026
- assertCompilerApi(ts);
2124
+ assertCompilerApi2(ts);
2027
2125
  const scriptKind = filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
2028
2126
  const sourceFile = ts.createSourceFile(
2029
2127
  filePath,
@@ -2134,27 +2232,67 @@ function scanFileForDependencies(filePath, sourceText) {
2134
2232
  return { file: filePath, imports, accessesByLocalName: accesses, hasWildcardReExport };
2135
2233
  }
2136
2234
 
2235
+ // src/_ipc/generated-banner.ts
2236
+ function marker() {
2237
+ return "GENERATED FILE -- do not edit by hand";
2238
+ }
2239
+ function createGeneratedBanner(describe) {
2240
+ return {
2241
+ reportRegenerateHint: () => describe().reportRegenerateHint,
2242
+ generatedBanner: (format = "ts", regenerate = `Run \`${describe().cliCommand}\` to regenerate.`) => {
2243
+ const text = `${marker()}. ${regenerate}`;
2244
+ return { ts: `// ${text}`, markdown: `<!-- ${text} -->` }[format];
2245
+ },
2246
+ // Not a bare `startsWith`: a shebang, a `"use strict"` pragma or a license header pushes a real marker
2247
+ // off line one, and a stricter check would read a genuinely generated file as hand-written, which a
2248
+ // dependency scan would take as "a real consumer imports this" and so permanently mask an abandoned
2249
+ // contract. The first 20 non-empty lines clear every realistic preamble without scanning a whole file.
2250
+ // A line counts only when the marker opens a comment, as `generatedBanner` writes it, so code or prose that
2251
+ // merely quotes the marker is not mistaken for a generated file.
2252
+ isGeneratedFile: (content) => {
2253
+ let seen = 0;
2254
+ for (const [line] of content.matchAll(/[^\n]*/g)) {
2255
+ const text = line.trimStart();
2256
+ if (text === "") continue;
2257
+ if (text.startsWith(`// ${marker()}`) || text.startsWith(`<!-- ${marker()}`)) return true;
2258
+ seen += 1;
2259
+ if (seen === 20) break;
2260
+ }
2261
+ return false;
2262
+ },
2263
+ 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.",
2264
+ evidenceProjectionNote: (evidencePath) => {
2265
+ const { product, guideUrl } = describe();
2266
+ const concept = `Projected from ${product}'s Evidence Model (${guideUrl}), the same source every other generated artifact draws from.`;
2267
+ return evidencePath === void 0 ? concept : `${concept} This run also wrote it to \`${evidencePath}\`.`;
2268
+ }
2269
+ };
2270
+ }
2271
+
2137
2272
  // src/build/generated-banner.ts
2138
- function generatedFileMarker() {
2139
- return "GENERATED FILE";
2273
+ function envCap() {
2274
+ return {
2275
+ product: "env-cap",
2276
+ guideUrl: "https://github.com/MaverickCER/env-cap/blob/main/GUIDE.md",
2277
+ cliCommand: "npx env-cap",
2278
+ reportRegenerateHint: "Regenerate it by re-running the script that calls `generateDocumentation()` / `generateUsageReport()` from `@maverickcer/env-cap/build`."
2279
+ };
2140
2280
  }
2281
+ var banner = createGeneratedBanner(envCap);
2141
2282
  function reportRegenerateHint() {
2142
- return "Regenerate it by re-running the script that calls `generateDocumentation()` / `generateUsageReport()` from `@maverickcer/env-cap/build`.";
2283
+ return banner.reportRegenerateHint();
2143
2284
  }
2144
- function generatedBanner(format = "ts", regenerate = "Run `npx env-cap` to regenerate.") {
2145
- const text = `${generatedFileMarker()} -- do not edit by hand. ${regenerate}`;
2146
- return { ts: `// ${text}`, markdown: `<!-- ${text} -->` }[format];
2285
+ function generatedBanner(format, regenerate) {
2286
+ return banner.generatedBanner(format, regenerate);
2147
2287
  }
2148
2288
  function isGeneratedFile(content) {
2149
- const nonEmptyLines = content.split("\n").filter((line) => line.trim().length > 0);
2150
- return nonEmptyLines.slice(0, 20).some((line) => line.includes(generatedFileMarker()));
2289
+ return banner.isGeneratedFile(content);
2151
2290
  }
2152
2291
  function evidenceDisclaimer() {
2153
- 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.";
2292
+ return banner.evidenceDisclaimer();
2154
2293
  }
2155
2294
  function evidenceProjectionNote(evidencePath) {
2156
- 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.";
2157
- return evidencePath === void 0 ? concept : `${concept} This run also wrote it to \`${evidencePath}\`.`;
2295
+ return banner.evidenceProjectionNote(evidencePath);
2158
2296
  }
2159
2297
 
2160
2298
  // src/build/dependency-graph.ts
@@ -5047,4 +5185,4 @@ export {
5047
5185
  resolveRelativeImport,
5048
5186
  writeEnvExample
5049
5187
  };
5050
- //# sourceMappingURL=build-H4KFV44Z.js.map
5188
+ //# sourceMappingURL=build-WKDIAWF7.js.map