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