@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.js
CHANGED
|
@@ -3,9 +3,10 @@ import crypto from 'crypto';
|
|
|
3
3
|
import { createRequire } from 'module';
|
|
4
4
|
|
|
5
5
|
// src/build/evidence-snapshot.ts
|
|
6
|
-
function displayPath(root,
|
|
7
|
-
|
|
8
|
-
|
|
6
|
+
function displayPath(root, filePath) {
|
|
7
|
+
if (!path6.isAbsolute(filePath)) return filePath.split(path6.sep).join("/");
|
|
8
|
+
const relative = path6.relative(root, filePath);
|
|
9
|
+
if (relative.startsWith("..") || path6.isAbsolute(relative)) return filePath;
|
|
9
10
|
return relative.split(path6.sep).join("/");
|
|
10
11
|
}
|
|
11
12
|
|
|
@@ -331,7 +332,7 @@ async function computeEvidenceChanges(root, snapshotPath, activeContracts, curre
|
|
|
331
332
|
};
|
|
332
333
|
}
|
|
333
334
|
|
|
334
|
-
// src/
|
|
335
|
+
// src/_ipc/glob.ts
|
|
335
336
|
function globToRegExp(pattern) {
|
|
336
337
|
let out = "";
|
|
337
338
|
let resume = 0;
|
|
@@ -427,14 +428,19 @@ function pickCompiler(load) {
|
|
|
427
428
|
}
|
|
428
429
|
var ts = pickCompiler(createRequire(import.meta.url));
|
|
429
430
|
|
|
430
|
-
// src/
|
|
431
|
-
function assertCompilerApi(compiler) {
|
|
431
|
+
// src/_ipc/compiler-api.ts
|
|
432
|
+
function assertCompilerApi(product, compiler) {
|
|
432
433
|
if (typeof compiler.createSourceFile === "function") return;
|
|
433
434
|
throw new Error(
|
|
434
|
-
|
|
435
|
+
`${product}'s build-time scanner needs TypeScript's classic compiler API (typescript ^5 || ^6), but the installed typescript${compiler.version === void 0 ? "" : ` ${compiler.version}`} does not expose it and the bundled @typescript/typescript6 could not be loaded. Reinstall ${product} with its dependencies, or provide a TypeScript 6 compiler: npm install --save-dev typescript@npm:@typescript/typescript6 (this swaps your \`tsc\` for \`tsc6\`; to keep TypeScript 7's \`tsc\`, also add @typescript/native@npm:typescript@^7). See VERSIONING.md, 'Supported toolchain'.`
|
|
435
436
|
);
|
|
436
437
|
}
|
|
437
438
|
|
|
439
|
+
// src/build/compiler-api.ts
|
|
440
|
+
function assertCompilerApi2(compiler) {
|
|
441
|
+
assertCompilerApi("env-cap", compiler);
|
|
442
|
+
}
|
|
443
|
+
|
|
438
444
|
// src/build/literal-eval.ts
|
|
439
445
|
function evaluateLiteral(node) {
|
|
440
446
|
if (ts.isStringLiteralLike(node)) return { ok: true, value: node.text };
|
|
@@ -479,7 +485,7 @@ function getStaticPropertyName(name) {
|
|
|
479
485
|
|
|
480
486
|
// src/build/parse.ts
|
|
481
487
|
function parseSchemaFile(filePath, sourceText) {
|
|
482
|
-
|
|
488
|
+
assertCompilerApi2(ts);
|
|
483
489
|
const sourceFile = ts.createSourceFile(
|
|
484
490
|
filePath,
|
|
485
491
|
sourceText,
|
|
@@ -1005,6 +1011,93 @@ function mustGet(map, key) {
|
|
|
1005
1011
|
throw new Error(`Internal error: expected key "${String(key)}" to be present in map.`);
|
|
1006
1012
|
return value;
|
|
1007
1013
|
}
|
|
1014
|
+
|
|
1015
|
+
// src/build/merge-documentation.ts
|
|
1016
|
+
var VALUE_FIELDS = [
|
|
1017
|
+
"description",
|
|
1018
|
+
"owner",
|
|
1019
|
+
"sensitivity",
|
|
1020
|
+
"expiresAt",
|
|
1021
|
+
"refreshInstructions",
|
|
1022
|
+
"authenticatorType",
|
|
1023
|
+
"rotationPeriod",
|
|
1024
|
+
"lastRotatedAt",
|
|
1025
|
+
"rotationTriggerEvents",
|
|
1026
|
+
"setupInstructions",
|
|
1027
|
+
"required",
|
|
1028
|
+
"deprecated",
|
|
1029
|
+
"deprecatedReason",
|
|
1030
|
+
"removeBy",
|
|
1031
|
+
"renamedFrom",
|
|
1032
|
+
"purpose",
|
|
1033
|
+
"legalBasis",
|
|
1034
|
+
"retention",
|
|
1035
|
+
"dataResidency",
|
|
1036
|
+
"auditRequired"
|
|
1037
|
+
];
|
|
1038
|
+
function mergeSharedDocumentation(contracts) {
|
|
1039
|
+
const declarationsByKey = /* @__PURE__ */ new Map();
|
|
1040
|
+
for (const contract of contracts) {
|
|
1041
|
+
for (const variable of contract.variables) {
|
|
1042
|
+
const declarations = declarationsByKey.get(variable.key);
|
|
1043
|
+
if (declarations === void 0) declarationsByKey.set(variable.key, [{ contract, variable }]);
|
|
1044
|
+
else declarations.push({ contract, variable });
|
|
1045
|
+
}
|
|
1046
|
+
}
|
|
1047
|
+
return contracts.map((contract) => ({
|
|
1048
|
+
...contract,
|
|
1049
|
+
variables: contract.variables.map((variable) => {
|
|
1050
|
+
const fromPackages = [];
|
|
1051
|
+
const fromApplication = [];
|
|
1052
|
+
for (const declaration of mustGet(declarationsByKey, variable.key)) {
|
|
1053
|
+
if (declaration.variable === variable) continue;
|
|
1054
|
+
const fromPackage = declaration.contract.packageOrigin !== void 0;
|
|
1055
|
+
if (!fromPackage && contract.packageOrigin === void 0) continue;
|
|
1056
|
+
(fromPackage ? fromPackages : fromApplication).push(declaration);
|
|
1057
|
+
}
|
|
1058
|
+
return fromPackages.length + fromApplication.length === 0 ? variable : filled(variable, fromPackages, fromApplication);
|
|
1059
|
+
})
|
|
1060
|
+
}));
|
|
1061
|
+
}
|
|
1062
|
+
function donated(read, fromPackages, fromApplication) {
|
|
1063
|
+
const fromPackage = fromPackages.find(({ variable }) => read(variable) !== void 0);
|
|
1064
|
+
if (fromPackage !== void 0) return read(fromPackage.variable);
|
|
1065
|
+
const values = fromApplication.map(({ variable }) => read(variable)).filter((v) => v !== void 0);
|
|
1066
|
+
return values.every((value) => deepEqual(value, values[0])) ? values[0] : void 0;
|
|
1067
|
+
}
|
|
1068
|
+
function filled(variable, fromPackages, fromApplication) {
|
|
1069
|
+
const donors = [...fromPackages, ...fromApplication];
|
|
1070
|
+
const merged = { ...variable };
|
|
1071
|
+
for (const field of VALUE_FIELDS) {
|
|
1072
|
+
if (variable[field] !== void 0) continue;
|
|
1073
|
+
merged[field] = donated((other) => other[field], fromPackages, fromApplication);
|
|
1074
|
+
}
|
|
1075
|
+
const metadata = {};
|
|
1076
|
+
for (const key of new Set(
|
|
1077
|
+
donors.flatMap(({ variable: other }) => Object.keys(other.metadata ?? {}))
|
|
1078
|
+
)) {
|
|
1079
|
+
const value = donated((other) => other.metadata?.[key], fromPackages, fromApplication);
|
|
1080
|
+
if (value !== void 0) metadata[key] = value;
|
|
1081
|
+
}
|
|
1082
|
+
Object.assign(metadata, variable.metadata);
|
|
1083
|
+
const result = {
|
|
1084
|
+
...merged,
|
|
1085
|
+
metadata: Object.keys(metadata).length === 0 ? variable.metadata : metadata,
|
|
1086
|
+
documented: variable.documented || donors.some(({ variable: other }) => other.documented)
|
|
1087
|
+
};
|
|
1088
|
+
DONATED.set(
|
|
1089
|
+
result,
|
|
1090
|
+
/* @__PURE__ */ new Set([
|
|
1091
|
+
...VALUE_FIELDS.filter((field) => result[field] !== variable[field]),
|
|
1092
|
+
...Object.keys(metadata).filter((key) => metadata[key] !== variable.metadata?.[key]).map((key) => `metadata.${key}`)
|
|
1093
|
+
])
|
|
1094
|
+
);
|
|
1095
|
+
return result;
|
|
1096
|
+
}
|
|
1097
|
+
var DONATED = /* @__PURE__ */ new WeakMap();
|
|
1098
|
+
function donatedTo(variable) {
|
|
1099
|
+
return DONATED.get(variable) ?? /* @__PURE__ */ new Set();
|
|
1100
|
+
}
|
|
1008
1101
|
function isWithinDirectory(baseDir, targetPath) {
|
|
1009
1102
|
const relative = path6.relative(baseDir, targetPath);
|
|
1010
1103
|
return relative !== ".." && !relative.startsWith(`..${path6.sep}`) && !path6.isAbsolute(relative);
|
|
@@ -1234,7 +1327,10 @@ async function fileExists(filePath, fs) {
|
|
|
1234
1327
|
}
|
|
1235
1328
|
return false;
|
|
1236
1329
|
}
|
|
1237
|
-
|
|
1330
|
+
function typescriptPath(file, separator) {
|
|
1331
|
+
return file.split(separator).join("/");
|
|
1332
|
+
}
|
|
1333
|
+
async function loadTsconfigPaths(product, root, tsconfigOption, fs) {
|
|
1238
1334
|
if (tsconfigOption === false) return { resolution: void 0, warning: void 0 };
|
|
1239
1335
|
const isExplicit = tsconfigOption !== void 0;
|
|
1240
1336
|
const configFile = path6.resolve(root, tsconfigOption ?? "tsconfig.json");
|
|
@@ -1248,8 +1344,11 @@ async function loadTsconfigPaths(root, tsconfigOption, fs) {
|
|
|
1248
1344
|
}
|
|
1249
1345
|
};
|
|
1250
1346
|
}
|
|
1251
|
-
assertCompilerApi(ts);
|
|
1252
|
-
const readResult = ts.readConfigFile(
|
|
1347
|
+
assertCompilerApi(product, ts);
|
|
1348
|
+
const readResult = ts.readConfigFile(
|
|
1349
|
+
typescriptPath(configFile, path6.sep),
|
|
1350
|
+
(p) => ts.sys.readFile(p)
|
|
1351
|
+
);
|
|
1253
1352
|
if (readResult.error) {
|
|
1254
1353
|
const detail = ts.flattenDiagnosticMessageText(readResult.error.messageText, ts.sys.newLine);
|
|
1255
1354
|
return {
|
|
@@ -1284,6 +1383,11 @@ function resolveAliasImport(specifier, importingFile, resolution, cache) {
|
|
|
1284
1383
|
return resolved;
|
|
1285
1384
|
}
|
|
1286
1385
|
|
|
1386
|
+
// src/build/resolution/resolve-tsconfig-paths.ts
|
|
1387
|
+
function loadTsconfigPaths2(root, tsconfigOption, fs) {
|
|
1388
|
+
return loadTsconfigPaths("env-cap", root, tsconfigOption, fs);
|
|
1389
|
+
}
|
|
1390
|
+
|
|
1287
1391
|
// src/build/resolution/resolve-import.ts
|
|
1288
1392
|
async function resolveRelativeImport(importingFile, specifier, fs) {
|
|
1289
1393
|
if (!specifier.startsWith("./") && !specifier.startsWith("../")) return void 0;
|
|
@@ -1442,7 +1546,6 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
|
|
|
1442
1546
|
}
|
|
1443
1547
|
const contracts = [];
|
|
1444
1548
|
const undocumentedContracts = [];
|
|
1445
|
-
const undocumentedVariables = [];
|
|
1446
1549
|
const staleDocEntries = [];
|
|
1447
1550
|
for (const entry of createEnvEntries) {
|
|
1448
1551
|
const linked = documentEnvByIdentity.get(entry.identity);
|
|
@@ -1452,10 +1555,6 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
|
|
|
1452
1555
|
}
|
|
1453
1556
|
const schemaKeys = new Set(entry.variables.map((v) => v.key));
|
|
1454
1557
|
const docsVariables = docs?.variables ?? /* @__PURE__ */ new Map();
|
|
1455
|
-
for (const key of schemaKeys) {
|
|
1456
|
-
if (!docsVariables.has(key))
|
|
1457
|
-
undocumentedVariables.push({ file: entry.file, exportName: entry.exportName, key });
|
|
1458
|
-
}
|
|
1459
1558
|
for (const key of docsVariables.keys()) {
|
|
1460
1559
|
if (!schemaKeys.has(key))
|
|
1461
1560
|
staleDocEntries.push({ file: entry.file, exportName: entry.exportName, key });
|
|
@@ -1517,12 +1616,17 @@ async function linkFiles(discoveredFiles, readFile, context, packageOrigins = /*
|
|
|
1517
1616
|
for (const analysis of analysisCache.values()) {
|
|
1518
1617
|
warnings.push(...analysis.warnings);
|
|
1519
1618
|
}
|
|
1619
|
+
const merged = mergeSharedDocumentation(contracts);
|
|
1520
1620
|
return {
|
|
1521
|
-
contracts,
|
|
1621
|
+
contracts: merged,
|
|
1522
1622
|
warnings,
|
|
1523
1623
|
unresolvedLinks,
|
|
1624
|
+
// Judged after the merge: a variable a package's contract documents is documented for the application that
|
|
1625
|
+
// declares it again.
|
|
1626
|
+
undocumentedVariables: merged.flatMap(
|
|
1627
|
+
({ file, exportName, variables }) => variables.filter(({ documented }) => !documented).map(({ key }) => ({ file, exportName, key }))
|
|
1628
|
+
),
|
|
1524
1629
|
undocumentedContracts,
|
|
1525
|
-
undocumentedVariables,
|
|
1526
1630
|
staleDocEntries
|
|
1527
1631
|
};
|
|
1528
1632
|
}
|
|
@@ -1582,7 +1686,7 @@ async function assembleProject(options) {
|
|
|
1582
1686
|
packageFiles.map((f) => f.file),
|
|
1583
1687
|
fs
|
|
1584
1688
|
);
|
|
1585
|
-
const { resolution: tsconfigPaths, warning: tsconfigWarning } = await
|
|
1689
|
+
const { resolution: tsconfigPaths, warning: tsconfigWarning } = await loadTsconfigPaths2(
|
|
1586
1690
|
root,
|
|
1587
1691
|
tsconfig,
|
|
1588
1692
|
fs
|
|
@@ -1647,24 +1751,20 @@ function buildChangeModel(manifest, currentContracts, root) {
|
|
|
1647
1751
|
}
|
|
1648
1752
|
|
|
1649
1753
|
// src/build/compatibility.ts
|
|
1650
|
-
var DOCUMENTATION_COMPARISON_FIELDS = [
|
|
1651
|
-
"description",
|
|
1652
|
-
"owner",
|
|
1653
|
-
"sensitivity",
|
|
1654
|
-
"expiresAt",
|
|
1655
|
-
"refreshInstructions",
|
|
1656
|
-
"setupInstructions",
|
|
1657
|
-
"required"
|
|
1658
|
-
];
|
|
1659
1754
|
function documentationDivergences(a, b) {
|
|
1660
1755
|
const divergences = [];
|
|
1661
|
-
|
|
1662
|
-
|
|
1756
|
+
const given = /* @__PURE__ */ new Set([...donatedTo(a), ...donatedTo(b)]);
|
|
1757
|
+
for (const field of VALUE_FIELDS) {
|
|
1758
|
+
if (!given.has(field) && a[field] !== void 0 && b[field] !== void 0 && !deepEqual(a[field], b[field])) {
|
|
1759
|
+
divergences.push(field);
|
|
1760
|
+
}
|
|
1663
1761
|
}
|
|
1664
1762
|
const aMetadata = a.metadata ?? {};
|
|
1665
1763
|
const bMetadata = b.metadata ?? {};
|
|
1666
|
-
for (const key of
|
|
1667
|
-
if (!deepEqual(aMetadata[key], bMetadata[key]))
|
|
1764
|
+
for (const key of Object.keys(aMetadata)) {
|
|
1765
|
+
if (!given.has(`metadata.${key}`) && key in bMetadata && !deepEqual(aMetadata[key], bMetadata[key])) {
|
|
1766
|
+
divergences.push(`metadata.${key}`);
|
|
1767
|
+
}
|
|
1668
1768
|
}
|
|
1669
1769
|
return divergences;
|
|
1670
1770
|
}
|
|
@@ -1711,17 +1811,15 @@ function detectCompatibilityIssues(contracts) {
|
|
|
1711
1811
|
reason: `"${a.contractName}" and "${b.contractName}" both declare a validator for this variable with different implementations. Validator logic cannot be statically compared -- confirm they enforce compatible rules.`
|
|
1712
1812
|
});
|
|
1713
1813
|
}
|
|
1714
|
-
|
|
1715
|
-
|
|
1716
|
-
|
|
1717
|
-
|
|
1718
|
-
|
|
1719
|
-
|
|
1720
|
-
|
|
1721
|
-
|
|
1722
|
-
|
|
1723
|
-
});
|
|
1724
|
-
}
|
|
1814
|
+
const divergences = documentationDivergences(a.variable, b.variable);
|
|
1815
|
+
if (divergences.length > 0) {
|
|
1816
|
+
issues.push({
|
|
1817
|
+
severity: "warning",
|
|
1818
|
+
variable: key,
|
|
1819
|
+
files: [a.file, b.file],
|
|
1820
|
+
code: "DUPLICATE_VARIABLE_DOCUMENTATION",
|
|
1821
|
+
reason: `"${a.contractName}" and "${b.contractName}" both document this variable, but disagree on: ${divergences.join(", ")}. Confirm they're still meant to be the same variable and align the documentation, or document them separately if they're not.`
|
|
1822
|
+
});
|
|
1725
1823
|
}
|
|
1726
1824
|
}
|
|
1727
1825
|
}
|
|
@@ -1989,7 +2087,7 @@ function bindingElementKey(element) {
|
|
|
1989
2087
|
return element.propertyName;
|
|
1990
2088
|
}
|
|
1991
2089
|
function scanFileForDependencies(filePath, sourceText) {
|
|
1992
|
-
|
|
2090
|
+
assertCompilerApi2(ts);
|
|
1993
2091
|
const scriptKind = filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
|
|
1994
2092
|
const sourceFile = ts.createSourceFile(
|
|
1995
2093
|
filePath,
|
|
@@ -2100,27 +2198,67 @@ function scanFileForDependencies(filePath, sourceText) {
|
|
|
2100
2198
|
return { file: filePath, imports, accessesByLocalName: accesses, hasWildcardReExport };
|
|
2101
2199
|
}
|
|
2102
2200
|
|
|
2201
|
+
// src/_ipc/generated-banner.ts
|
|
2202
|
+
function marker() {
|
|
2203
|
+
return "GENERATED FILE -- do not edit by hand";
|
|
2204
|
+
}
|
|
2205
|
+
function createGeneratedBanner(describe) {
|
|
2206
|
+
return {
|
|
2207
|
+
reportRegenerateHint: () => describe().reportRegenerateHint,
|
|
2208
|
+
generatedBanner: (format = "ts", regenerate = `Run \`${describe().cliCommand}\` to regenerate.`) => {
|
|
2209
|
+
const text = `${marker()}. ${regenerate}`;
|
|
2210
|
+
return { ts: `// ${text}`, markdown: `<!-- ${text} -->` }[format];
|
|
2211
|
+
},
|
|
2212
|
+
// Not a bare `startsWith`: a shebang, a `"use strict"` pragma or a license header pushes a real marker
|
|
2213
|
+
// off line one, and a stricter check would read a genuinely generated file as hand-written, which a
|
|
2214
|
+
// dependency scan would take as "a real consumer imports this" and so permanently mask an abandoned
|
|
2215
|
+
// contract. The first 20 non-empty lines clear every realistic preamble without scanning a whole file.
|
|
2216
|
+
// A line counts only when the marker opens a comment, as `generatedBanner` writes it, so code or prose that
|
|
2217
|
+
// merely quotes the marker is not mistaken for a generated file.
|
|
2218
|
+
isGeneratedFile: (content) => {
|
|
2219
|
+
let seen = 0;
|
|
2220
|
+
for (const [line] of content.matchAll(/[^\n]*/g)) {
|
|
2221
|
+
const text = line.trimStart();
|
|
2222
|
+
if (text === "") continue;
|
|
2223
|
+
if (text.startsWith(`// ${marker()}`) || text.startsWith(`<!-- ${marker()}`)) return true;
|
|
2224
|
+
seen += 1;
|
|
2225
|
+
if (seen === 20) break;
|
|
2226
|
+
}
|
|
2227
|
+
return false;
|
|
2228
|
+
},
|
|
2229
|
+
evidenceDisclaimer: () => "Machine-generated engineering artifact assembled from statically-provable code facts and author-declared documentation. It can support a security, privacy, or compliance review. It does not itself establish compliance with any standard.",
|
|
2230
|
+
evidenceProjectionNote: (evidencePath) => {
|
|
2231
|
+
const { product, guideUrl } = describe();
|
|
2232
|
+
const concept = `Projected from ${product}'s Evidence Model (${guideUrl}), the same source every other generated artifact draws from.`;
|
|
2233
|
+
return evidencePath === void 0 ? concept : `${concept} This run also wrote it to \`${evidencePath}\`.`;
|
|
2234
|
+
}
|
|
2235
|
+
};
|
|
2236
|
+
}
|
|
2237
|
+
|
|
2103
2238
|
// src/build/generated-banner.ts
|
|
2104
|
-
function
|
|
2105
|
-
return
|
|
2239
|
+
function envCap() {
|
|
2240
|
+
return {
|
|
2241
|
+
product: "env-cap",
|
|
2242
|
+
guideUrl: "https://github.com/MaverickCER/env-cap/blob/main/GUIDE.md",
|
|
2243
|
+
cliCommand: "npx env-cap",
|
|
2244
|
+
reportRegenerateHint: "Regenerate it by re-running the script that calls `generateDocumentation()` / `generateUsageReport()` from `@maverickcer/env-cap/build`."
|
|
2245
|
+
};
|
|
2106
2246
|
}
|
|
2247
|
+
var banner = createGeneratedBanner(envCap);
|
|
2107
2248
|
function reportRegenerateHint() {
|
|
2108
|
-
return
|
|
2249
|
+
return banner.reportRegenerateHint();
|
|
2109
2250
|
}
|
|
2110
|
-
function generatedBanner(format
|
|
2111
|
-
|
|
2112
|
-
return { ts: `// ${text}`, markdown: `<!-- ${text} -->` }[format];
|
|
2251
|
+
function generatedBanner(format, regenerate) {
|
|
2252
|
+
return banner.generatedBanner(format, regenerate);
|
|
2113
2253
|
}
|
|
2114
2254
|
function isGeneratedFile(content) {
|
|
2115
|
-
|
|
2116
|
-
return nonEmptyLines.slice(0, 20).some((line) => line.includes(generatedFileMarker()));
|
|
2255
|
+
return banner.isGeneratedFile(content);
|
|
2117
2256
|
}
|
|
2118
2257
|
function evidenceDisclaimer() {
|
|
2119
|
-
return
|
|
2258
|
+
return banner.evidenceDisclaimer();
|
|
2120
2259
|
}
|
|
2121
2260
|
function evidenceProjectionNote(evidencePath) {
|
|
2122
|
-
|
|
2123
|
-
return evidencePath === void 0 ? concept : `${concept} This run also wrote it to \`${evidencePath}\`.`;
|
|
2261
|
+
return banner.evidenceProjectionNote(evidencePath);
|
|
2124
2262
|
}
|
|
2125
2263
|
|
|
2126
2264
|
// src/build/dependency-graph.ts
|
|
@@ -4337,7 +4475,7 @@ function buildOwnershipModel(contracts, root) {
|
|
|
4337
4475
|
|
|
4338
4476
|
// src/build/tool-version.ts
|
|
4339
4477
|
function readToolVersion() {
|
|
4340
|
-
return "0.
|
|
4478
|
+
return "0.7.0";
|
|
4341
4479
|
}
|
|
4342
4480
|
|
|
4343
4481
|
// src/build/generate-evidence.ts
|