@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.
- package/ADOPTION.md +144 -0
- package/AGENTS.md +146 -0
- package/CHANGELOG.md +438 -0
- package/CODE_OF_CONDUCT.md +124 -0
- package/CODE_REVIEW.md +200 -0
- package/CONTRIBUTING.md +131 -0
- package/GUIDE.md +1214 -0
- package/PROMPT.md +89 -0
- package/README.md +92 -200
- package/RELEASING.md +160 -0
- package/SECURITY.md +270 -0
- package/SUPPORT.md +76 -0
- package/VERSIONING.md +118 -0
- package/benchmarks/READING-BENCHMARKS.md +197 -0
- package/benchmarks/README.md +126 -0
- package/benchmarks/WRITING-BENCHMARKS.md +252 -0
- package/benchmarks/performance-buildtime/BENCHMARKS.md +889 -0
- package/benchmarks/performance-runtime/BENCHMARKS.md +1988 -0
- package/dist/.dts/_ipc/build-fs.d.ts +53 -0
- package/dist/.dts/_ipc/build-fs.d.ts.map +1 -0
- package/dist/.dts/_ipc/compiler-api.d.ts +17 -0
- package/dist/.dts/_ipc/compiler-api.d.ts.map +1 -0
- package/dist/.dts/_ipc/display-path.d.ts +27 -0
- package/dist/.dts/_ipc/display-path.d.ts.map +1 -0
- package/dist/.dts/_ipc/generated-banner.d.ts +58 -0
- package/dist/.dts/_ipc/generated-banner.d.ts.map +1 -0
- package/dist/.dts/_ipc/glob.d.ts +22 -0
- package/dist/.dts/_ipc/glob.d.ts.map +1 -0
- package/dist/.dts/_ipc/no-node-fs.d.ts +34 -0
- package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -0
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +134 -0
- package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts/_ipc/typescript.d.ts +20 -0
- package/dist/.dts/_ipc/typescript.d.ts.map +1 -0
- package/dist/.dts/build/compatibility.d.ts.map +1 -1
- package/dist/.dts/build/compiler-api.d.ts +3 -6
- package/dist/.dts/build/compiler-api.d.ts.map +1 -1
- package/dist/.dts/build/display-path.d.ts +3 -21
- package/dist/.dts/build/display-path.d.ts.map +1 -1
- package/dist/.dts/build/generated-banner.d.ts +21 -42
- package/dist/.dts/build/generated-banner.d.ts.map +1 -1
- package/dist/.dts/build/glob.d.ts +3 -15
- package/dist/.dts/build/glob.d.ts.map +1 -1
- package/dist/.dts/build/link.d.ts.map +1 -1
- package/dist/.dts/build/merge-documentation.d.ts +35 -0
- package/dist/.dts/build/merge-documentation.d.ts.map +1 -0
- package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +11 -112
- package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
- package/dist/.dts/build/types.d.ts +4 -53
- package/dist/.dts/build/types.d.ts.map +1 -1
- package/dist/.dts/build/typescript.d.ts +3 -17
- package/dist/.dts/build/typescript.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/glob.d.ts +4 -15
- package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/index.d.ts +1 -1
- package/dist/.dts/eslint-plugin/no-node-fs.d.ts +8 -18
- package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -1
- package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -1
- package/dist/{build-H4KFV44Z.js → build-WKDIAWF7.js} +198 -60
- package/dist/build-WKDIAWF7.js.map +1 -0
- package/dist/build.cjs +194 -56
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +194 -56
- package/dist/build.js.map +1 -1
- package/dist/{chunk-7GVPOHDU.js → chunk-KEGYUHBU.js} +2 -2
- package/dist/cli/index.js +36 -29
- package/dist/cli/index.js.map +1 -1
- package/dist/eslint-plugin/index.cjs +84 -54
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js +83 -53
- package/dist/eslint-plugin/index.js.map +1 -1
- package/examples/README.md +95 -0
- package/package.json +48 -14
- package/skills/env-cap/SKILL.md +91 -0
- package/skills/env-cap/references/api.md +220 -0
- package/specs/architecture.md +634 -0
- package/specs/decisions/0001-runtime-documentation-separation.md +197 -0
- package/specs/decisions/0002-static-analysis-never-execution.md +233 -0
- package/specs/decisions/0003-no-global-env-object.md +172 -0
- package/specs/decisions/0004-no-client-server-package-split.md +116 -0
- package/specs/decisions/0005-warn-not-throw-by-default.md +93 -0
- package/specs/decisions/0006-self-redacting-contracts.md +124 -0
- package/specs/decisions/0007-processor-not-transformer.md +109 -0
- package/specs/decisions/0008-gzip-size-budget.md +173 -0
- package/specs/decisions/0009-exclusive-groups-are-always-errors.md +139 -0
- package/specs/decisions/0010-dependency-ownership-engine-scope-boundary.md +100 -0
- package/specs/decisions/0011-shared-discovery-compute-atomic-write-non-atomic.md +104 -0
- package/specs/decisions/0012-live-expiration-overrides-not-ast-functions.md +145 -0
- package/specs/decisions/0013-json-output-is-a-versioned-mirror.md +136 -0
- package/specs/decisions/0014-cross-package-schema-discovery.md +206 -0
- package/specs/decisions/0015-security-backport-window.md +60 -0
- package/specs/decisions/0016-check-mode-compute-before-compare-never-partial-write.md +113 -0
- package/specs/decisions/0017-eslint-plugin-entry-point.md +113 -0
- package/specs/decisions/0018-rotation-alert-issue-on-non-pr-runs.md +104 -0
- package/specs/decisions/0019-published-json-schema-generated-from-types.md +100 -0
- package/specs/decisions/0020-declaration-maps-via-separate-tsc-pass.md +101 -0
- package/specs/decisions/0021-manifest-change-report-persisted-snapshot.md +177 -0
- package/specs/decisions/0022-validation-contexts.md +267 -0
- package/specs/decisions/0023-tsconfig-path-alias-resolution.md +182 -0
- package/specs/decisions/0024-fact-model-architecture.md +144 -0
- package/specs/decisions/0025-contract-model-json-projection.md +105 -0
- package/specs/decisions/0026-finding-model-unifies-four-families.md +109 -0
- package/specs/decisions/0027-dependency-model-fact-shape-not-engine-access.md +98 -0
- package/specs/decisions/0028-ownership-model-shared-effective-owner.md +85 -0
- package/specs/decisions/0029-lifecycle-model-deprecation-rename-fields.md +98 -0
- package/specs/decisions/0030-change-model-wraps-manifest-change-report.md +97 -0
- package/specs/decisions/0031-evidence-entry-point.md +85 -0
- package/specs/decisions/0032-evidence-projection-provenance-mechanism.md +120 -0
- package/specs/decisions/0033-reference-projections-live-in-examples.md +81 -0
- package/specs/decisions/0034-three-tier-examples-restructuring.md +85 -0
- package/specs/decisions/0035-documentenv-metadata-generalization-and-compliance-fields.md +85 -0
- package/specs/decisions/0036-exact-source-position-evidence.md +122 -0
- package/specs/decisions/0037-developer-declared-dynamic-access-citations.md +114 -0
- package/specs/decisions/0038-always-computed-evidence-model-backs-generate-check-docs.md +244 -0
- package/specs/decisions/0039-scanner-local-dataflow-boundary.md +160 -0
- package/specs/decisions/0040-library-surfaces-do-not-acquire-node-fs.md +156 -0
- package/specs/decisions/0041-dual-package-hazard-checked-documented.md +75 -0
- package/specs/decisions/0042-init-cli-subcommand-scaffolds-only.md +95 -0
- package/specs/decisions/0043-env-cap-resolver-relocated-and-duplicated.md +71 -0
- package/specs/decisions/0044-strict-escalates-every-warning-family.md +88 -0
- package/specs/decisions/0045-promote-experimental-surfaces-to-stable.md +103 -0
- package/specs/decisions/0046-cli-restricted-to-runtime-and-evidence-output.md +177 -0
- package/specs/decisions/0047-supported-toolchain-node-22-and-typescript-5-6.md +30 -0
- package/specs/decisions/0048-eslint-plugin-does-not-vendor-typescript-eslint.md +25 -0
- package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +87 -0
- package/specs/decisions/0050-a-variable-declared-twice-is-documented-once.md +55 -0
- package/specs/generated-artifacts.md +104 -0
- package/specs/migrations/README.md +30 -0
- package/specs/migrations/from-centralized-schema.md +503 -0
- package/specs/migrations/from-dotenv.md +352 -0
- package/specs/migrations/from-envalid.md +482 -0
- package/specs/migrations/from-process-env.md +398 -0
- package/specs/migrations/from-t3-env.md +416 -0
- package/specs/migrations/from-zod.md +303 -0
- package/dist/build-H4KFV44Z.js.map +0 -1
- /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,
|
|
16
|
-
|
|
17
|
-
|
|
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/
|
|
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/
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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(
|
|
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
|
|
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
|
-
|
|
1671
|
-
|
|
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
|
|
1676
|
-
if (!deepEqual(aMetadata[key], bMetadata[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
|
-
|
|
1724
|
-
|
|
1725
|
-
|
|
1726
|
-
|
|
1727
|
-
|
|
1728
|
-
|
|
1729
|
-
|
|
1730
|
-
|
|
1731
|
-
|
|
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
|
-
|
|
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
|
|
2114
|
-
return
|
|
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
|
|
2258
|
+
return banner.reportRegenerateHint();
|
|
2118
2259
|
}
|
|
2119
|
-
function generatedBanner(format
|
|
2120
|
-
|
|
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
|
-
|
|
2125
|
-
return nonEmptyLines.slice(0, 20).some((line) => line.includes(generatedFileMarker()));
|
|
2264
|
+
return banner.isGeneratedFile(content);
|
|
2126
2265
|
}
|
|
2127
2266
|
function evidenceDisclaimer() {
|
|
2128
|
-
return
|
|
2267
|
+
return banner.evidenceDisclaimer();
|
|
2129
2268
|
}
|
|
2130
2269
|
function evidenceProjectionNote(evidencePath) {
|
|
2131
|
-
|
|
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.
|
|
4487
|
+
return "0.7.0";
|
|
4350
4488
|
}
|
|
4351
4489
|
|
|
4352
4490
|
// src/build/generate-evidence.ts
|