@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.
- package/ADOPTION.md +144 -0
- package/AGENTS.md +146 -0
- package/CHANGELOG.md +449 -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 +35 -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/index.d.ts +3 -3
- 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-F3RQS7VE.js} +218 -63
- package/dist/build-F3RQS7VE.js.map +1 -0
- package/dist/build.cjs +257 -102
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +256 -101
- package/dist/build.js.map +1 -1
- package/dist/{chunk-7GVPOHDU.js → chunk-QKIQ3LZP.js} +2 -2
- package/dist/cli/index.js +36 -29
- package/dist/cli/index.js.map +1 -1
- package/dist/eslint-plugin/index.cjs +95 -54
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js +94 -53
- package/dist/eslint-plugin/index.js.map +1 -1
- package/examples/README.md +95 -0
- package/package.json +53 -19
- 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-QKIQ3LZP.js.map} +0 -0
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import {
|
|
3
3
|
readToolVersion
|
|
4
|
-
} from "./chunk-
|
|
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/
|
|
13
|
+
// src/_ipc/display-path.ts
|
|
14
14
|
import path from "path";
|
|
15
|
-
function displayPath(root,
|
|
16
|
-
|
|
17
|
-
|
|
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/
|
|
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/
|
|
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/
|
|
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
|
-
|
|
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
|
-
|
|
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/
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
1417
|
+
return { resolution: void 0, warning };
|
|
1302
1418
|
}
|
|
1303
|
-
return { resolution: { compilerOptions: parsed.options, configFile }, warning
|
|
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
|
|
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
|
-
|
|
1696
|
-
|
|
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
|
|
1701
|
-
if (!deepEqual(aMetadata[key], bMetadata[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
|
-
|
|
1749
|
-
|
|
1750
|
-
|
|
1751
|
-
|
|
1752
|
-
|
|
1753
|
-
|
|
1754
|
-
|
|
1755
|
-
|
|
1756
|
-
|
|
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
|
-
|
|
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
|
|
2139
|
-
return
|
|
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
|
|
2300
|
+
return banner.reportRegenerateHint();
|
|
2143
2301
|
}
|
|
2144
|
-
function generatedBanner(format
|
|
2145
|
-
|
|
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
|
-
|
|
2150
|
-
return nonEmptyLines.slice(0, 20).some((line) => line.includes(generatedFileMarker()));
|
|
2306
|
+
return banner.isGeneratedFile(content);
|
|
2151
2307
|
}
|
|
2152
2308
|
function evidenceDisclaimer() {
|
|
2153
|
-
return
|
|
2309
|
+
return banner.evidenceDisclaimer();
|
|
2154
2310
|
}
|
|
2155
2311
|
function evidenceProjectionNote(evidencePath) {
|
|
2156
|
-
|
|
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://
|
|
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-
|
|
5205
|
+
//# sourceMappingURL=build-F3RQS7VE.js.map
|