@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
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  import {
3
3
  readToolVersion
4
- } from "./chunk-7GVPOHDU.js";
4
+ } from "./chunk-QKIQ3LZP.js";
5
5
 
6
6
  // src/build/evidence-snapshot.ts
7
7
  import path3 from "path";
@@ -10,11 +10,13 @@ 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 === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
19
+ return filePath;
18
20
  return relative.split(path.sep).join("/");
19
21
  }
20
22
 
@@ -346,7 +348,7 @@ import path17 from "path";
346
348
  // src/build/discover.ts
347
349
  import path4 from "path";
348
350
 
349
- // src/build/glob.ts
351
+ // src/_ipc/glob.ts
350
352
  function globToRegExp(pattern) {
351
353
  let out = "";
352
354
  let resume = 0;
@@ -421,7 +423,7 @@ function matchesAnyPattern(filePath, patterns) {
421
423
  // src/build/link.ts
422
424
  import path9 from "path";
423
425
 
424
- // src/build/typescript.ts
426
+ // src/_ipc/typescript.ts
425
427
  import { createRequire } from "module";
426
428
  function hasClassicApi(candidate) {
427
429
  return typeof candidate?.createSourceFile === "function";
@@ -448,14 +450,19 @@ function pickCompiler(load) {
448
450
  }
449
451
  var ts = pickCompiler(createRequire(import.meta.url));
450
452
 
451
- // src/build/compiler-api.ts
452
- function assertCompilerApi(compiler) {
453
+ // src/_ipc/compiler-api.ts
454
+ function assertCompilerApi(product, compiler) {
453
455
  if (typeof compiler.createSourceFile === "function") return;
454
456
  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'.`
457
+ `${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
458
  );
457
459
  }
458
460
 
461
+ // src/build/compiler-api.ts
462
+ function assertCompilerApi2(compiler) {
463
+ assertCompilerApi("env-cap", compiler);
464
+ }
465
+
459
466
  // src/build/literal-eval.ts
460
467
  function evaluateLiteral(node) {
461
468
  if (ts.isStringLiteralLike(node)) return { ok: true, value: node.text };
@@ -500,7 +507,7 @@ function getStaticPropertyName(name) {
500
507
 
501
508
  // src/build/parse.ts
502
509
  function parseSchemaFile(filePath, sourceText) {
503
- assertCompilerApi(ts);
510
+ assertCompilerApi2(ts);
504
511
  const sourceFile = ts.createSourceFile(
505
512
  filePath,
506
513
  sourceText,
@@ -1027,6 +1034,93 @@ function mustGet(map, key) {
1027
1034
  return value;
1028
1035
  }
1029
1036
 
1037
+ // src/build/merge-documentation.ts
1038
+ var VALUE_FIELDS = [
1039
+ "description",
1040
+ "owner",
1041
+ "sensitivity",
1042
+ "expiresAt",
1043
+ "refreshInstructions",
1044
+ "authenticatorType",
1045
+ "rotationPeriod",
1046
+ "lastRotatedAt",
1047
+ "rotationTriggerEvents",
1048
+ "setupInstructions",
1049
+ "required",
1050
+ "deprecated",
1051
+ "deprecatedReason",
1052
+ "removeBy",
1053
+ "renamedFrom",
1054
+ "purpose",
1055
+ "legalBasis",
1056
+ "retention",
1057
+ "dataResidency",
1058
+ "auditRequired"
1059
+ ];
1060
+ function mergeSharedDocumentation(contracts) {
1061
+ const declarationsByKey = /* @__PURE__ */ new Map();
1062
+ for (const contract of contracts) {
1063
+ for (const variable of contract.variables) {
1064
+ const declarations = declarationsByKey.get(variable.key);
1065
+ if (declarations === void 0) declarationsByKey.set(variable.key, [{ contract, variable }]);
1066
+ else declarations.push({ contract, variable });
1067
+ }
1068
+ }
1069
+ return contracts.map((contract) => ({
1070
+ ...contract,
1071
+ variables: contract.variables.map((variable) => {
1072
+ const fromPackages = [];
1073
+ const fromApplication = [];
1074
+ for (const declaration of mustGet(declarationsByKey, variable.key)) {
1075
+ if (declaration.variable === variable) continue;
1076
+ const fromPackage = declaration.contract.packageOrigin !== void 0;
1077
+ if (!fromPackage && contract.packageOrigin === void 0) continue;
1078
+ (fromPackage ? fromPackages : fromApplication).push(declaration);
1079
+ }
1080
+ return fromPackages.length + fromApplication.length === 0 ? variable : filled(variable, fromPackages, fromApplication);
1081
+ })
1082
+ }));
1083
+ }
1084
+ function donated(read, fromPackages, fromApplication) {
1085
+ const fromPackage = fromPackages.find(({ variable }) => read(variable) !== void 0);
1086
+ if (fromPackage !== void 0) return read(fromPackage.variable);
1087
+ const values = fromApplication.map(({ variable }) => read(variable)).filter((v) => v !== void 0);
1088
+ return values.every((value) => deepEqual(value, values[0])) ? values[0] : void 0;
1089
+ }
1090
+ function filled(variable, fromPackages, fromApplication) {
1091
+ const donors = [...fromPackages, ...fromApplication];
1092
+ const merged = { ...variable };
1093
+ for (const field of VALUE_FIELDS) {
1094
+ if (variable[field] !== void 0) continue;
1095
+ merged[field] = donated((other) => other[field], fromPackages, fromApplication);
1096
+ }
1097
+ const metadata = {};
1098
+ for (const key of new Set(
1099
+ donors.flatMap(({ variable: other }) => Object.keys(other.metadata ?? {}))
1100
+ )) {
1101
+ const value = donated((other) => other.metadata?.[key], fromPackages, fromApplication);
1102
+ if (value !== void 0) metadata[key] = value;
1103
+ }
1104
+ Object.assign(metadata, variable.metadata);
1105
+ const result = {
1106
+ ...merged,
1107
+ metadata: Object.keys(metadata).length === 0 ? variable.metadata : metadata,
1108
+ documented: variable.documented || donors.some(({ variable: other }) => other.documented)
1109
+ };
1110
+ DONATED.set(
1111
+ result,
1112
+ /* @__PURE__ */ new Set([
1113
+ ...VALUE_FIELDS.filter((field) => result[field] !== variable[field]),
1114
+ ...Object.keys(metadata).filter((key) => metadata[key] !== variable.metadata?.[key]).map((key) => `metadata.${key}`)
1115
+ ])
1116
+ );
1117
+ return result;
1118
+ }
1119
+ var DONATED = /* @__PURE__ */ new WeakMap();
1120
+ function donatedTo(variable) {
1121
+ return DONATED.get(variable) ?? /* @__PURE__ */ new Set();
1122
+ }
1123
+
1030
1124
  // src/build/resolution/resolve-import.ts
1031
1125
  import path8 from "path";
1032
1126
 
@@ -1253,7 +1347,7 @@ async function resolvePackageImport(specifier, allowedPackages, root, cache, fs)
1253
1347
  return result.ok ? result.origin.resolvedFile : void 0;
1254
1348
  }
1255
1349
 
1256
- // src/build/resolution/resolve-tsconfig-paths.ts
1350
+ // src/_ipc/resolve-tsconfig-paths.ts
1257
1351
  import path7 from "path";
1258
1352
  function pathMappingOptions(options) {
1259
1353
  return options;
@@ -1268,7 +1362,10 @@ async function fileExists(filePath, fs) {
1268
1362
  }
1269
1363
  return false;
1270
1364
  }
1271
- async function loadTsconfigPaths(root, tsconfigOption, fs) {
1365
+ function typescriptPath(file, separator) {
1366
+ return file.split(separator).join("/");
1367
+ }
1368
+ async function loadTsconfigPaths(product, root, tsconfigOption, fs) {
1272
1369
  if (tsconfigOption === false) return { resolution: void 0, warning: void 0 };
1273
1370
  const isExplicit = tsconfigOption !== void 0;
1274
1371
  const configFile = path7.resolve(root, tsconfigOption ?? "tsconfig.json");
@@ -1282,8 +1379,20 @@ async function loadTsconfigPaths(root, tsconfigOption, fs) {
1282
1379
  }
1283
1380
  };
1284
1381
  }
1285
- assertCompilerApi(ts);
1286
- const readResult = ts.readConfigFile(configFile, (p) => ts.sys.readFile(p));
1382
+ assertCompilerApi(product, ts);
1383
+ let text;
1384
+ try {
1385
+ text = await fs.readFile(configFile, "utf8");
1386
+ } catch (error) {
1387
+ return {
1388
+ resolution: void 0,
1389
+ warning: {
1390
+ file: configFile,
1391
+ message: `Could not read "${configFile}": ${error.message}`
1392
+ }
1393
+ };
1394
+ }
1395
+ const readResult = ts.parseConfigFileTextToJson(typescriptPath(configFile, path7.sep), text);
1287
1396
  if (readResult.error) {
1288
1397
  const detail = ts.flattenDiagnosticMessageText(readResult.error.messageText, ts.sys.newLine);
1289
1398
  return {
@@ -1295,12 +1404,19 @@ async function loadTsconfigPaths(root, tsconfigOption, fs) {
1295
1404
  };
1296
1405
  }
1297
1406
  const parsed = ts.parseJsonConfigFileContent(readResult.config, ts.sys, path7.dirname(configFile));
1407
+ const problems = parsed.errors.filter((diagnostic) => diagnostic.code !== 18003);
1408
+ const warning = problems.length === 0 ? void 0 : {
1409
+ file: configFile,
1410
+ message: `"${configFile}" has problems the compiler reported: ${problems.map(
1411
+ (diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, ts.sys.newLine)
1412
+ ).join("; ")}`
1413
+ };
1298
1414
  const { paths, baseUrl } = pathMappingOptions(parsed.options);
1299
1415
  const hasPaths = paths !== void 0 && Object.keys(paths).length > 0;
1300
1416
  if (!hasPaths && baseUrl === void 0) {
1301
- return { resolution: void 0, warning: void 0 };
1417
+ return { resolution: void 0, warning };
1302
1418
  }
1303
- return { resolution: { compilerOptions: parsed.options, configFile }, warning: void 0 };
1419
+ return { resolution: { compilerOptions: parsed.options, configFile }, warning };
1304
1420
  }
1305
1421
  function resolveAliasImport(specifier, importingFile, resolution, cache) {
1306
1422
  const cacheKey = `${importingFile}\0${specifier}`;
@@ -1318,6 +1434,11 @@ function resolveAliasImport(specifier, importingFile, resolution, cache) {
1318
1434
  return resolved;
1319
1435
  }
1320
1436
 
1437
+ // src/build/resolution/resolve-tsconfig-paths.ts
1438
+ function loadTsconfigPaths2(root, tsconfigOption, fs) {
1439
+ return loadTsconfigPaths("env-cap", root, tsconfigOption, fs);
1440
+ }
1441
+
1321
1442
  // src/build/resolution/resolve-import.ts
1322
1443
  async function resolveRelativeImport(importingFile, specifier, fs) {
1323
1444
  if (!specifier.startsWith("./") && !specifier.startsWith("../")) return void 0;
@@ -1476,7 +1597,6 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1476
1597
  }
1477
1598
  const contracts = [];
1478
1599
  const undocumentedContracts = [];
1479
- const undocumentedVariables = [];
1480
1600
  const staleDocEntries = [];
1481
1601
  for (const entry of createEnvEntries) {
1482
1602
  const linked = documentEnvByIdentity.get(entry.identity);
@@ -1486,10 +1606,6 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1486
1606
  }
1487
1607
  const schemaKeys = new Set(entry.variables.map((v) => v.key));
1488
1608
  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
1609
  for (const key of docsVariables.keys()) {
1494
1610
  if (!schemaKeys.has(key))
1495
1611
  staleDocEntries.push({ file: entry.file, exportName: entry.exportName, key });
@@ -1551,12 +1667,17 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
1551
1667
  for (const analysis of analysisCache.values()) {
1552
1668
  warnings.push(...analysis.warnings);
1553
1669
  }
1670
+ const merged = mergeSharedDocumentation(contracts);
1554
1671
  return {
1555
- contracts,
1672
+ contracts: merged,
1556
1673
  warnings,
1557
1674
  unresolvedLinks,
1675
+ // Judged after the merge: a variable a package's contract documents is documented for the application that
1676
+ // declares it again.
1677
+ undocumentedVariables: merged.flatMap(
1678
+ ({ file, exportName, variables }) => variables.filter(({ documented }) => !documented).map(({ key }) => ({ file, exportName, key }))
1679
+ ),
1558
1680
  undocumentedContracts,
1559
- undocumentedVariables,
1560
1681
  staleDocEntries
1561
1682
  };
1562
1683
  }
@@ -1616,7 +1737,7 @@ async function assembleProject(options) {
1616
1737
  packageFiles.map((f) => f.file),
1617
1738
  fs
1618
1739
  );
1619
- const { resolution: tsconfigPaths, warning: tsconfigWarning } = await loadTsconfigPaths(
1740
+ const { resolution: tsconfigPaths, warning: tsconfigWarning } = await loadTsconfigPaths2(
1620
1741
  root,
1621
1742
  tsconfig,
1622
1743
  fs
@@ -1681,24 +1802,20 @@ function buildChangeModel(manifest, currentContracts, root) {
1681
1802
  }
1682
1803
 
1683
1804
  // 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
1805
  function documentationDivergences(a, b) {
1694
1806
  const divergences = [];
1695
- for (const field of DOCUMENTATION_COMPARISON_FIELDS) {
1696
- if (a[field] !== b[field]) divergences.push(field);
1807
+ const given = /* @__PURE__ */ new Set([...donatedTo(a), ...donatedTo(b)]);
1808
+ for (const field of VALUE_FIELDS) {
1809
+ if (!given.has(field) && a[field] !== void 0 && b[field] !== void 0 && !deepEqual(a[field], b[field])) {
1810
+ divergences.push(field);
1811
+ }
1697
1812
  }
1698
1813
  const aMetadata = a.metadata ?? {};
1699
1814
  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}`);
1815
+ for (const key of Object.keys(aMetadata)) {
1816
+ if (!given.has(`metadata.${key}`) && key in bMetadata && !deepEqual(aMetadata[key], bMetadata[key])) {
1817
+ divergences.push(`metadata.${key}`);
1818
+ }
1702
1819
  }
1703
1820
  return divergences;
1704
1821
  }
@@ -1745,17 +1862,15 @@ function detectCompatibilityIssues(contracts) {
1745
1862
  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
1863
  });
1747
1864
  }
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
- }
1865
+ const divergences = documentationDivergences(a.variable, b.variable);
1866
+ if (divergences.length > 0) {
1867
+ issues.push({
1868
+ severity: "warning",
1869
+ variable: key,
1870
+ files: [a.file, b.file],
1871
+ code: "DUPLICATE_VARIABLE_DOCUMENTATION",
1872
+ 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.`
1873
+ });
1759
1874
  }
1760
1875
  }
1761
1876
  }
@@ -2023,7 +2138,7 @@ function bindingElementKey(element) {
2023
2138
  return element.propertyName;
2024
2139
  }
2025
2140
  function scanFileForDependencies(filePath, sourceText) {
2026
- assertCompilerApi(ts);
2141
+ assertCompilerApi2(ts);
2027
2142
  const scriptKind = filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
2028
2143
  const sourceFile = ts.createSourceFile(
2029
2144
  filePath,
@@ -2134,27 +2249,67 @@ function scanFileForDependencies(filePath, sourceText) {
2134
2249
  return { file: filePath, imports, accessesByLocalName: accesses, hasWildcardReExport };
2135
2250
  }
2136
2251
 
2252
+ // src/_ipc/generated-banner.ts
2253
+ function marker() {
2254
+ return "GENERATED FILE -- do not edit by hand";
2255
+ }
2256
+ function createGeneratedBanner(describe) {
2257
+ return {
2258
+ reportRegenerateHint: () => describe().reportRegenerateHint,
2259
+ generatedBanner: (format = "ts", regenerate = `Run \`${describe().cliCommand}\` to regenerate.`) => {
2260
+ const text = `${marker()}. ${regenerate}`;
2261
+ return { ts: `// ${text}`, markdown: `<!-- ${text} -->` }[format];
2262
+ },
2263
+ // Not a bare `startsWith`: a shebang, a `"use strict"` pragma or a license header pushes a real marker
2264
+ // off line one, and a stricter check would read a genuinely generated file as hand-written, which a
2265
+ // dependency scan would take as "a real consumer imports this" and so permanently mask an abandoned
2266
+ // contract. The first 20 non-empty lines clear every realistic preamble without scanning a whole file.
2267
+ // A line counts only when the marker opens a comment, as `generatedBanner` writes it, so code or prose that
2268
+ // merely quotes the marker is not mistaken for a generated file.
2269
+ isGeneratedFile: (content) => {
2270
+ let seen = 0;
2271
+ for (const [line] of content.matchAll(/[^\n]*/g)) {
2272
+ const text = line.trimStart();
2273
+ if (text === "") continue;
2274
+ if (text.startsWith(`// ${marker()}`) || text.startsWith(`<!-- ${marker()}`)) return true;
2275
+ seen += 1;
2276
+ if (seen === 20) break;
2277
+ }
2278
+ return false;
2279
+ },
2280
+ 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.",
2281
+ evidenceProjectionNote: (evidencePath) => {
2282
+ const { product, guideUrl } = describe();
2283
+ const concept = `Projected from ${product}'s Evidence Model (${guideUrl}), the same source every other generated artifact draws from.`;
2284
+ return evidencePath === void 0 ? concept : `${concept} This run also wrote it to \`${evidencePath}\`.`;
2285
+ }
2286
+ };
2287
+ }
2288
+
2137
2289
  // src/build/generated-banner.ts
2138
- function generatedFileMarker() {
2139
- return "GENERATED FILE";
2290
+ function envCap() {
2291
+ return {
2292
+ product: "env-cap",
2293
+ guideUrl: "https://github.com/MaverickCER/env-cap/blob/main/GUIDE.md",
2294
+ cliCommand: "npx env-cap",
2295
+ reportRegenerateHint: "Regenerate it by re-running the script that calls `generateDocumentation()` / `generateUsageReport()` from `@maverickcer/env-cap/build`."
2296
+ };
2140
2297
  }
2298
+ var banner = createGeneratedBanner(envCap);
2141
2299
  function reportRegenerateHint() {
2142
- return "Regenerate it by re-running the script that calls `generateDocumentation()` / `generateUsageReport()` from `@maverickcer/env-cap/build`.";
2300
+ return banner.reportRegenerateHint();
2143
2301
  }
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];
2302
+ function generatedBanner(format, regenerate) {
2303
+ return banner.generatedBanner(format, regenerate);
2147
2304
  }
2148
2305
  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()));
2306
+ return banner.isGeneratedFile(content);
2151
2307
  }
2152
2308
  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.";
2309
+ return banner.evidenceDisclaimer();
2154
2310
  }
2155
2311
  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}\`.`;
2312
+ return banner.evidenceProjectionNote(evidencePath);
2158
2313
  }
2159
2314
 
2160
2315
  // src/build/dependency-graph.ts
@@ -4957,7 +5112,7 @@ function sarifLocations(finding) {
4957
5112
  function buildSarifLog(findingModel) {
4958
5113
  const ruleIds = [...new Set(findingModel.findings.map((f) => f.code))].sort();
4959
5114
  return {
4960
- $schema: "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/Schemata/sarif-schema-2.1.0.json",
5115
+ $schema: "https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/schemas/sarif-schema-2.1.0.json",
4961
5116
  version: "2.1.0",
4962
5117
  runs: [
4963
5118
  {
@@ -5047,4 +5202,4 @@ export {
5047
5202
  resolveRelativeImport,
5048
5203
  writeEnvExample
5049
5204
  };
5050
- //# sourceMappingURL=build-H4KFV44Z.js.map
5205
+ //# sourceMappingURL=build-F3RQS7VE.js.map