@maverickcer/env-cap 0.7.4 → 0.7.5
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 +106 -124
- package/AGENTS.md +14 -13
- package/CHANGELOG.md +15 -0
- package/CODE_REVIEW.md +69 -173
- package/CONTRIBUTING.md +57 -74
- package/GUIDE.md +393 -872
- package/README.md +81 -76
- package/RELEASING.md +17 -15
- package/SECURITY.md +76 -227
- package/SUPPORT.md +21 -45
- package/VERSIONING.md +68 -105
- package/benchmarks/READING-BENCHMARKS.md +13 -7
- package/benchmarks/WRITING-BENCHMARKS.md +1 -1
- package/dist/.dts/_ipc/build-fs.d.ts +9 -14
- package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
- package/dist/.dts/_ipc/compiler-api.d.ts +6 -6
- package/dist/.dts/_ipc/display-path.d.ts.map +1 -1
- package/dist/.dts/_ipc/generated-banner.d.ts +8 -8
- package/dist/.dts/_ipc/glob.d.ts +6 -6
- package/dist/.dts/_ipc/no-node-fs.d.ts.map +1 -1
- package/dist/.dts/build/lifecycle-model.d.ts +8 -3
- package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
- package/dist/.dts/build/sarif.d.ts.map +1 -1
- package/dist/.dts/helpers/index.d.ts +1 -1
- package/dist/.dts/runtime/create.d.ts +3 -0
- package/dist/.dts/runtime/create.d.ts.map +1 -1
- package/dist/.dts/runtime/document.d.ts +7 -4
- package/dist/.dts/runtime/document.d.ts.map +1 -1
- package/dist/.dts/runtime/index.d.ts +11 -10
- package/dist/.dts/runtime/index.d.ts.map +1 -1
- package/dist/.dts/runtime/types.d.ts +16 -0
- package/dist/.dts/runtime/types.d.ts.map +1 -1
- package/dist/.dts/runtime/validate.d.ts +14 -1
- package/dist/.dts/runtime/validate.d.ts.map +1 -1
- package/dist/.dts7/_ipc/build-fs.d.ts +48 -0
- package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -0
- package/dist/.dts7/_ipc/compiler-api.d.ts +17 -0
- package/dist/.dts7/_ipc/compiler-api.d.ts.map +1 -0
- package/dist/.dts7/_ipc/display-path.d.ts +27 -0
- package/dist/.dts7/_ipc/display-path.d.ts.map +1 -0
- package/dist/.dts7/_ipc/generated-banner.d.ts +58 -0
- package/dist/.dts7/_ipc/generated-banner.d.ts.map +1 -0
- package/dist/.dts7/_ipc/glob.d.ts +22 -0
- package/dist/.dts7/_ipc/glob.d.ts.map +1 -0
- package/dist/.dts7/_ipc/no-node-fs.d.ts +21 -0
- package/dist/.dts7/_ipc/no-node-fs.d.ts.map +1 -0
- package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +134 -0
- package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts7/_ipc/typescript.d.ts +20 -0
- package/dist/.dts7/_ipc/typescript.d.ts.map +1 -0
- package/dist/.dts7/build/assemble-project.d.ts +47 -0
- package/dist/.dts7/build/assemble-project.d.ts.map +1 -0
- package/dist/.dts7/build/change-model.d.ts +63 -0
- package/dist/.dts7/build/change-model.d.ts.map +1 -0
- package/dist/.dts7/build/check-artifacts.d.ts +48 -0
- package/dist/.dts7/build/check-artifacts.d.ts.map +1 -0
- package/dist/.dts7/build/citation-verification.d.ts +62 -0
- package/dist/.dts7/build/citation-verification.d.ts.map +1 -0
- package/dist/.dts7/build/compatibility.d.ts +83 -0
- package/dist/.dts7/build/compatibility.d.ts.map +1 -0
- package/dist/.dts7/build/compiler-api.d.ts +12 -0
- package/dist/.dts7/build/compiler-api.d.ts.map +1 -0
- package/dist/.dts7/build/contract-model.d.ts +93 -0
- package/dist/.dts7/build/contract-model.d.ts.map +1 -0
- package/dist/.dts7/build/deep-equal.d.ts +9 -0
- package/dist/.dts7/build/deep-equal.d.ts.map +1 -0
- package/dist/.dts7/build/deep-freeze.d.ts +20 -0
- package/dist/.dts7/build/deep-freeze.d.ts.map +1 -0
- package/dist/.dts7/build/dependency-graph.d.ts +170 -0
- package/dist/.dts7/build/dependency-graph.d.ts.map +1 -0
- package/dist/.dts7/build/dependency-model.d.ts +81 -0
- package/dist/.dts7/build/dependency-model.d.ts.map +1 -0
- package/dist/.dts7/build/discover.d.ts +41 -0
- package/dist/.dts7/build/discover.d.ts.map +1 -0
- package/dist/.dts7/build/display-path.d.ts +6 -0
- package/dist/.dts7/build/display-path.d.ts.map +1 -0
- package/dist/.dts7/build/docs.d.ts +176 -0
- package/dist/.dts7/build/docs.d.ts.map +1 -0
- package/dist/.dts7/build/env-example.d.ts +85 -0
- package/dist/.dts7/build/env-example.d.ts.map +1 -0
- package/dist/.dts7/build/errors.d.ts +78 -0
- package/dist/.dts7/build/errors.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-cache.d.ts +74 -0
- package/dist/.dts7/build/evidence-cache.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-model.d.ts +50 -0
- package/dist/.dts7/build/evidence-model.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-reference.d.ts +67 -0
- package/dist/.dts7/build/evidence-reference.d.ts.map +1 -0
- package/dist/.dts7/build/evidence-snapshot.d.ts +148 -0
- package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -0
- package/dist/.dts7/build/exclusive-group.d.ts +19 -0
- package/dist/.dts7/build/exclusive-group.d.ts.map +1 -0
- package/dist/.dts7/build/finding-model.d.ts +80 -0
- package/dist/.dts7/build/finding-model.d.ts.map +1 -0
- package/dist/.dts7/build/generate-documentation.d.ts +176 -0
- package/dist/.dts7/build/generate-documentation.d.ts.map +1 -0
- package/dist/.dts7/build/generate-env-artifacts.d.ts +191 -0
- package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -0
- package/dist/.dts7/build/generate-evidence.d.ts +77 -0
- package/dist/.dts7/build/generate-evidence.d.ts.map +1 -0
- package/dist/.dts7/build/generate-manifest.d.ts +101 -0
- package/dist/.dts7/build/generate-manifest.d.ts.map +1 -0
- package/dist/.dts7/build/generate-usage.d.ts +95 -0
- package/dist/.dts7/build/generate-usage.d.ts.map +1 -0
- package/dist/.dts7/build/generated-banner.d.ts +43 -0
- package/dist/.dts7/build/generated-banner.d.ts.map +1 -0
- package/dist/.dts7/build/glob.d.ts +6 -0
- package/dist/.dts7/build/glob.d.ts.map +1 -0
- package/dist/.dts7/build/governance-fields.d.ts +34 -0
- package/dist/.dts7/build/governance-fields.d.ts.map +1 -0
- package/dist/.dts7/build/humanize-key.d.ts +14 -0
- package/dist/.dts7/build/humanize-key.d.ts.map +1 -0
- package/dist/.dts7/build/index.d.ts +105 -0
- package/dist/.dts7/build/index.d.ts.map +1 -0
- package/dist/.dts7/build/lifecycle-model.d.ts +179 -0
- package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -0
- package/dist/.dts7/build/link.d.ts +223 -0
- package/dist/.dts7/build/link.d.ts.map +1 -0
- package/dist/.dts7/build/literal-eval.d.ts +24 -0
- package/dist/.dts7/build/literal-eval.d.ts.map +1 -0
- package/dist/.dts7/build/live-expirations.d.ts +47 -0
- package/dist/.dts7/build/live-expirations.d.ts.map +1 -0
- package/dist/.dts7/build/manifest.d.ts +31 -0
- package/dist/.dts7/build/manifest.d.ts.map +1 -0
- package/dist/.dts7/build/map-utils.d.ts +8 -0
- package/dist/.dts7/build/map-utils.d.ts.map +1 -0
- package/dist/.dts7/build/merge-documentation.d.ts +35 -0
- package/dist/.dts7/build/merge-documentation.d.ts.map +1 -0
- package/dist/.dts7/build/ownership-model.d.ts +59 -0
- package/dist/.dts7/build/ownership-model.d.ts.map +1 -0
- package/dist/.dts7/build/parse.d.ts +207 -0
- package/dist/.dts7/build/parse.d.ts.map +1 -0
- package/dist/.dts7/build/reference-projections.d.ts +170 -0
- package/dist/.dts7/build/reference-projections.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-import.d.ts +58 -0
- package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +83 -0
- package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts +18 -0
- package/dist/.dts7/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts7/build/resolution/resolve-within-root.d.ts +35 -0
- package/dist/.dts7/build/resolution/resolve-within-root.d.ts.map +1 -0
- package/dist/.dts7/build/sarif.d.ts +66 -0
- package/dist/.dts7/build/sarif.d.ts.map +1 -0
- package/dist/.dts7/build/scan-dependencies.d.ts +70 -0
- package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -0
- package/dist/.dts7/build/sort-by-identity.d.ts +14 -0
- package/dist/.dts7/build/sort-by-identity.d.ts.map +1 -0
- package/dist/.dts7/build/source-position.d.ts +69 -0
- package/dist/.dts7/build/source-position.d.ts.map +1 -0
- package/dist/.dts7/build/tool-version.d.ts +8 -0
- package/dist/.dts7/build/tool-version.d.ts.map +1 -0
- package/dist/.dts7/build/types.d.ts +7 -0
- package/dist/.dts7/build/types.d.ts.map +1 -0
- package/dist/.dts7/build/typescript.d.ts +6 -0
- package/dist/.dts7/build/typescript.d.ts.map +1 -0
- package/dist/.dts7/build/usage-report.d.ts +124 -0
- package/dist/.dts7/build/usage-report.d.ts.map +1 -0
- package/dist/.dts7/cli/filesystem.d.ts +7 -0
- package/dist/.dts7/cli/filesystem.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/glob.d.ts +7 -0
- package/dist/.dts7/eslint-plugin/glob.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/index.d.ts +27 -0
- package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/no-node-fs.d.ts +15 -0
- package/dist/.dts7/eslint-plugin/no-node-fs.d.ts.map +1 -0
- package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +23 -0
- package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts.map +1 -0
- package/dist/.dts7/evidence/define-projection.d.ts +52 -0
- package/dist/.dts7/evidence/define-projection.d.ts.map +1 -0
- package/dist/.dts7/evidence/index.d.ts +23 -0
- package/dist/.dts7/evidence/index.d.ts.map +1 -0
- package/dist/.dts7/helpers/index.d.ts +135 -0
- package/dist/.dts7/helpers/index.d.ts.map +1 -0
- package/dist/.dts7/helpers/processors.d.ts +32 -0
- package/dist/.dts7/helpers/processors.d.ts.map +1 -0
- package/dist/.dts7/helpers/validators.d.ts +68 -0
- package/dist/.dts7/helpers/validators.d.ts.map +1 -0
- package/dist/.dts7/node/index.d.ts +2 -0
- package/dist/.dts7/node/index.d.ts.map +1 -0
- package/dist/.dts7/runtime/cache.d.ts +17 -0
- package/dist/.dts7/runtime/cache.d.ts.map +1 -0
- package/dist/.dts7/runtime/create.d.ts +23 -0
- package/dist/.dts7/runtime/create.d.ts.map +1 -0
- package/dist/.dts7/runtime/document.d.ts +223 -0
- package/dist/.dts7/runtime/document.d.ts.map +1 -0
- package/dist/.dts7/runtime/errors.d.ts +55 -0
- package/dist/.dts7/runtime/errors.d.ts.map +1 -0
- package/dist/.dts7/runtime/index.d.ts +25 -0
- package/dist/.dts7/runtime/index.d.ts.map +1 -0
- package/dist/.dts7/runtime/registry.d.ts +12 -0
- package/dist/.dts7/runtime/registry.d.ts.map +1 -0
- package/dist/.dts7/runtime/reset.d.ts +8 -0
- package/dist/.dts7/runtime/reset.d.ts.map +1 -0
- package/dist/.dts7/runtime/types.d.ts +191 -0
- package/dist/.dts7/runtime/types.d.ts.map +1 -0
- package/dist/.dts7/runtime/validate.d.ts +27 -0
- package/dist/.dts7/runtime/validate.d.ts.map +1 -0
- package/dist/{build-6XFHJFQK.js → build-DNAYWD2B.js} +8 -5
- package/dist/build-DNAYWD2B.js.map +1 -0
- package/dist/build.cjs +7 -4
- package/dist/build.cjs.map +1 -1
- package/dist/build.js +7 -4
- package/dist/build.js.map +1 -1
- package/dist/build.ts7.d.cts +1 -0
- package/dist/build.ts7.d.ts +1 -0
- package/dist/{chunk-RL5KFVUT.js → chunk-HAGMVMN5.js} +2 -2
- package/dist/cli/index.js +3 -3
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js.map +1 -1
- package/dist/eslint-plugin/index.ts7.d.cts +1 -0
- package/dist/eslint-plugin/index.ts7.d.ts +1 -0
- package/dist/evidence.ts7.d.cts +1 -0
- package/dist/evidence.ts7.d.ts +1 -0
- package/dist/helpers.ts7.d.cts +1 -0
- package/dist/helpers.ts7.d.ts +1 -0
- package/dist/index.cjs.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/index.ts7.d.cts +1 -0
- package/dist/index.ts7.d.ts +1 -0
- package/dist/node.ts7.d.cts +1 -0
- package/dist/node.ts7.d.ts +1 -0
- package/examples/README.md +46 -80
- package/package.json +27 -4
- package/schemas/env-cap-report.schema.json +1 -1
- package/skills/env-cap/SKILL.md +1 -1
- package/skills/env-cap/references/api.md +1 -1
- package/specs/architecture.md +2 -2
- package/specs/decisions/0001-runtime-documentation-separation.md +1 -1
- package/specs/decisions/0014-cross-package-schema-discovery.md +4 -1
- package/specs/decisions/0023-tsconfig-path-alias-resolution.md +4 -1
- package/specs/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +13 -8
- package/specs/generated-artifacts.md +14 -2
- package/dist/build-6XFHJFQK.js.map +0 -1
- /package/dist/{chunk-RL5KFVUT.js.map → chunk-HAGMVMN5.js.map} +0 -0
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* env-cap build-time entry point (`@maverickcer/env-cap/build`).
|
|
3
|
+
*
|
|
4
|
+
* Discovery, static analysis, cross-file linking, and manifest/docs/
|
|
5
|
+
* ownership-report generation only -- this module imports `node:path` and
|
|
6
|
+
* (indirectly) `typescript`, and must never be imported from runtime/
|
|
7
|
+
* browser/edge code. It has no knowledge of `createEnv`/`documentEnv`/
|
|
8
|
+
* `validateEnv` and performs no environment validation, and never executes a
|
|
9
|
+
* discovered schema file.
|
|
10
|
+
*
|
|
11
|
+
* It never imports `node:fs` (ADR 0040): `./build` is a library surface, so
|
|
12
|
+
* the caller supplies the filesystem capability. Every public options object
|
|
13
|
+
* below carries a required `fs: BuildFileSystem` field; the `env-cap` CLI
|
|
14
|
+
* builds a concrete `node:fs/promises` adapter and hands it in. A consumer
|
|
15
|
+
* running these functions from their own Node build script imports the same
|
|
16
|
+
* adapter from `@maverickcer/env-cap/node` (`{ nodeBuildFileSystem }`).
|
|
17
|
+
*
|
|
18
|
+
* The public API is deliberately curated: four generator functions
|
|
19
|
+
* (`generateEnvManifest`, `generateDocumentation`, `generateUsageReport`,
|
|
20
|
+
* `generateEnvArtifacts`) plus the lower-level discovery/linking primitives,
|
|
21
|
+
* justified by real external use (custom CI scripts, bundler plugins) and
|
|
22
|
+
* promoted to Stable alongside the orchestrators per ADR 0045 -- see
|
|
23
|
+
* `VERSIONING.md`. The dependency-ownership engine's internals (scanning,
|
|
24
|
+
* graph-building, derivation) are intentionally NOT exported here -- see ADR
|
|
25
|
+
* 0010 and ADR 0011. `env-cap` answers ownership/visibility questions; it
|
|
26
|
+
* doesn't ship a general-purpose static-analysis toolkit. The scanner
|
|
27
|
+
* follows object-destructuring and one level of file-unique `const`
|
|
28
|
+
* aliasing, and records every other shape as an explicit `escape` (ADR
|
|
29
|
+
* 0039); a variable on an escaped contract is `indeterminate`, never a false
|
|
30
|
+
* `unconsumed`, and the finding's `reason` cites every escape site.
|
|
31
|
+
*
|
|
32
|
+
* Each generator also accepts a `packages` option (an explicit
|
|
33
|
+
* allowlist of installed package names) for discovering a schema that ships
|
|
34
|
+
* inside a separately-published dependency rather than the project's own
|
|
35
|
+
* source tree -- see ADR 0014 and `VERSIONING.md`.
|
|
36
|
+
*
|
|
37
|
+
* Each generator also accepts a `tsconfig` option for resolving
|
|
38
|
+
* import specifiers written as TypeScript path aliases (e.g. `"@/lib/env"`)
|
|
39
|
+
* against a project's own `tsconfig.json` `paths`/`baseUrl` during static
|
|
40
|
+
* analysis. Unlike `packages`, this is on by default (auto-detecting
|
|
41
|
+
* `tsconfig.json` at `root`) since it never crosses a trust/versioning
|
|
42
|
+
* boundary -- see ADR 0023 and `VERSIONING.md`.
|
|
43
|
+
*/
|
|
44
|
+
export { checkEnvArtifacts } from "./check-artifacts.js";
|
|
45
|
+
export type { ArtifactCheckFinding, CheckEnvArtifactsResult } from "./check-artifacts.js";
|
|
46
|
+
export { generateDocumentation } from "./generate-documentation.js";
|
|
47
|
+
export { STANDARD_SENSITIVITY_LEVELS, type DocumentationFindings, type GenerateDocumentationOptions, type GenerateDocumentationResult, type NonstandardSensitivityEntry, } from "./generate-documentation.js";
|
|
48
|
+
export { generateEnvArtifacts } from "./generate-env-artifacts.js";
|
|
49
|
+
export type { GenerateEnvArtifactsOptions, GenerateEnvArtifactsResult, } from "./generate-env-artifacts.js";
|
|
50
|
+
export { generateEnvManifest } from "./generate-manifest.js";
|
|
51
|
+
export type { GenerateEnvManifestOptions, GenerateEnvManifestResult } from "./generate-manifest.js";
|
|
52
|
+
export type { ManifestChangeReport, ManifestContractRef, ManifestContractUpdate, ManifestFieldChange, ManifestVariableRef, ManifestVariableUpdate, } from "./evidence-snapshot.js";
|
|
53
|
+
export { computeSourceFingerprint, getEvidenceModel } from "./evidence-cache.js";
|
|
54
|
+
export type { ComputeSourceFingerprintOptions, GetEvidenceModelOptions, GetEvidenceModelResult, } from "./evidence-cache.js";
|
|
55
|
+
export { generateUsageReport } from "./generate-usage.js";
|
|
56
|
+
export type { GenerateUsageReportOptions, GenerateUsageReportResult } from "./generate-usage.js";
|
|
57
|
+
export { renderUsageReport, type AbandonedContractFinding, type AssertedDynamicAccessFinding, type IndeterminateOwnershipFinding, type OwnershipDependencyEntry, type RenderUsageReportOptions, type UnconsumedOwnedVariableFinding, type UnresolvedConsumerFinding, } from "./usage-report.js";
|
|
58
|
+
export type { DynamicAccessCitationProblem } from "./citation-verification.js";
|
|
59
|
+
export type { CompatibilityIssue, CompatibilityIssueCode } from "./compatibility.js";
|
|
60
|
+
export { EnvDocumentationGenerationError, EnvManifestGenerationError, EnvProjectGenerationError, EnvUsageAnalysisError, } from "./errors.js";
|
|
61
|
+
export type { DiscoveredContractSummary } from "./link.js";
|
|
62
|
+
export { buildChangeModel, CHANGE_MODEL_SCHEMA_VERSION } from "./change-model.js";
|
|
63
|
+
export type { ChangeModel, RenamedVariable } from "./change-model.js";
|
|
64
|
+
export { detectCompatibilityIssues, detectDuplicateVariableShapes } from "./compatibility.js";
|
|
65
|
+
export { displayPath } from "./display-path.js";
|
|
66
|
+
export { buildSarifLog } from "./sarif.js";
|
|
67
|
+
export type { SarifLog } from "./sarif.js";
|
|
68
|
+
export { configurationReference, expiringSoonReport, groupVariablesByOwner, ownershipSummary, } from "./reference-projections.js";
|
|
69
|
+
export type { ConfigurationReference, ConfigurationReferenceEntry, ExpiringSoonEntry, ExpiringSoonReport, OwnerBearingContract, OwnershipSummary, OwnershipSummaryEntry, } from "./reference-projections.js";
|
|
70
|
+
export { buildContractModel, CONTRACT_MODEL_SCHEMA_VERSION } from "./contract-model.js";
|
|
71
|
+
export type { ContractModel, ContractModelContract, ContractModelVariable, } from "./contract-model.js";
|
|
72
|
+
export { deepFreeze } from "./deep-freeze.js";
|
|
73
|
+
export { buildDependencyModel, DEPENDENCY_MODEL_SCHEMA_VERSION } from "./dependency-model.js";
|
|
74
|
+
export type { DependencyModel, DependencyModelConsumer, DependencyModelContract, DependencyModelContractRef, DependencyModelVariable, } from "./dependency-model.js";
|
|
75
|
+
export type { ScannedSurface, VariableAccessStatus } from "./dependency-graph.js";
|
|
76
|
+
export { discoverSchemaFiles } from "./discover.js";
|
|
77
|
+
export { computeExpiringEntries, computeSecurityReviewCounters, extractPreviouslyDocumentedKeys, renderDocs, } from "./docs.js";
|
|
78
|
+
export type { ExpiringEntry, RenderDocsOptions, SecurityReviewCounters, UndocumentedContractRef, UndocumentedVariableRef, } from "./docs.js";
|
|
79
|
+
export { computeReconciliation, extractCommentedVariables, extractDeclaredVariables, renderEnvExample, writeEnvExample, } from "./env-example.js";
|
|
80
|
+
export type { EnvExampleOnExisting, EnvExampleResult, Reconciliation } from "./env-example.js";
|
|
81
|
+
export type { DynamicAccessAssertion, SourcePosition } from "./source-position.js";
|
|
82
|
+
export { EVIDENCE_MODEL_SCHEMA_VERSION } from "./evidence-model.js";
|
|
83
|
+
export type { EvidenceModel, EvidenceProvenance } from "./evidence-model.js";
|
|
84
|
+
export { generateEvidenceModel } from "./generate-evidence.js";
|
|
85
|
+
export type { GenerateEvidenceModelOptions } from "./generate-evidence.js";
|
|
86
|
+
export type { ChangeEvidenceReference, ContractEvidenceReference, ContractRef, EvidenceReference, OwnershipEvidenceReference, } from "./evidence-reference.js";
|
|
87
|
+
export { detectExclusiveGroupIssues } from "./exclusive-group.js";
|
|
88
|
+
export { buildFindingModel, FINDING_MODEL_SCHEMA_VERSION } from "./finding-model.js";
|
|
89
|
+
export type { BuildFindingModelInput, Finding, FindingCode, FindingFamily, FindingModel, } from "./finding-model.js";
|
|
90
|
+
export { buildLifecycleModel, computeRotationStatus, LIFECYCLE_MODEL_SCHEMA_VERSION, parseRotationPeriodDays, } from "./lifecycle-model.js";
|
|
91
|
+
export type { LifecycleModel, LifecycleModelContract, LifecycleModelVariable, RotationComplianceStatus, } from "./lifecycle-model.js";
|
|
92
|
+
export { effectiveOwner, linkFiles } from "./link.js";
|
|
93
|
+
export type { DiscoveredContract, DiscoveredVariable, LinkResult, UnresolvedLink } from "./link.js";
|
|
94
|
+
export { applyLiveExpirationOverrides, collectVariableNames, resolveLiveExpirationDates, } from "./live-expirations.js";
|
|
95
|
+
export type { LiveExpirationDates } from "./live-expirations.js";
|
|
96
|
+
export { renderManifest } from "./manifest.js";
|
|
97
|
+
export { buildOwnershipModel, OWNERSHIP_MODEL_SCHEMA_VERSION } from "./ownership-model.js";
|
|
98
|
+
export type { OwnershipModel, OwnershipModelContract, OwnershipModelContractRef, OwnershipModelVariable, OwnershipModelVariableRef, } from "./ownership-model.js";
|
|
99
|
+
export { extractContractDocs, extractSchemaVariables, parseSchemaFile } from "./parse.js";
|
|
100
|
+
export type { DiscoveredContractDocs, DiscoveredSchemaVariable, DiscoveredVariableDocs, DiscoveredVariableEvidence, FileParseResult, ImportBinding, ParseWarning, SchemaRef, } from "./parse.js";
|
|
101
|
+
export { resolveRelativeImport } from "./resolution/resolve-import.js";
|
|
102
|
+
export type { PackageOrigin } from "./resolution/resolve-package-schema.js";
|
|
103
|
+
export type { BuildDirent, BuildFileSystem, BuildStats } from "./types.js";
|
|
104
|
+
export { readToolVersion } from "./tool-version.js";
|
|
105
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/build/index.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
import type { ExpiringEntry } from "./docs.js";
|
|
2
|
+
import type { DiscoveredContract } from "./link.js";
|
|
3
|
+
/**
|
|
4
|
+
* The fifth of env-cap's seven canonical fact models (ADR 0024) -- every
|
|
5
|
+
* contract and variable's lifecycle data (expiry, deprecation, rename
|
|
6
|
+
* correlation), promoting `ExpiringEntry`/`computeExpiringEntries()`
|
|
7
|
+
* (already a good precedent -- real, exported, reused across `renderDocs()`
|
|
8
|
+
* and `generate-documentation.ts`) into a canonical, versioned shape
|
|
9
|
+
* alongside the new deprecation/rename fields. See ADR 0029.
|
|
10
|
+
*
|
|
11
|
+
* As of schema version 3, this also carries NIST SP 800-53 IA-5 rotation
|
|
12
|
+
* data (`authenticatorType`/`rotationPeriod`/`lastRotatedAt`/
|
|
13
|
+
* `rotationTriggerEvents`) and a computed `rotationStatus` per variable --
|
|
14
|
+
* see `computeRotationStatus()` below for the compliance-status judgment
|
|
15
|
+
* call, and the `rotation-log` example generator (peer to `generate-docs/`)
|
|
16
|
+
* for the first real consumer.
|
|
17
|
+
*/
|
|
18
|
+
/** Bump only when a reader could misinterpret the new shape -- same discipline every other canonical model's `schemaVersion` follows. */
|
|
19
|
+
export declare const LIFECYCLE_MODEL_SCHEMA_VERSION = 3;
|
|
20
|
+
/**
|
|
21
|
+
* One variable's computed NIST SP 800-53 IA-5 rotation status (a policy-window judgement) --
|
|
22
|
+
* see `computeRotationStatus()` for exactly how it's derived. Always present
|
|
23
|
+
* on a `LifecycleModelVariable` (never `undefined`) since a variable with
|
|
24
|
+
* literally nothing lifecycle-relevant set never reaches this model at all
|
|
25
|
+
* (`hasLifecycleData()` below) -- `"undeclared"` is itself the honest value
|
|
26
|
+
* for "reached this model for some other lifecycle reason (e.g. `deprecated`)
|
|
27
|
+
* but declares none of the four rotation-specific fields."
|
|
28
|
+
*
|
|
29
|
+
* This is a policy-window judgement from the declared metadata ("within the declared
|
|
30
|
+
* rotation period"), never a statement that any control is met or that a rotation
|
|
31
|
+
* happened; env-cap never checks a declaration against reality. The 1.0 release
|
|
32
|
+
* renames the value `"compliant"` to `"withinPolicy"` for that reason.
|
|
33
|
+
*/
|
|
34
|
+
export type RotationComplianceStatus = "compliant" | "overdue" | "expired" | "undeclared";
|
|
35
|
+
/**
|
|
36
|
+
* One variable's lifecycle data (expiry, deprecation, rename correlation).
|
|
37
|
+
*
|
|
38
|
+
* @see {@link ContractModelVariable} -- this same declared variable's canonical starting point.
|
|
39
|
+
*/
|
|
40
|
+
export interface LifecycleModelVariable {
|
|
41
|
+
readonly key: string;
|
|
42
|
+
readonly expiresAt: string | undefined;
|
|
43
|
+
readonly refreshInstructions: string | undefined;
|
|
44
|
+
readonly deprecated: boolean | undefined;
|
|
45
|
+
readonly deprecatedReason: string | undefined;
|
|
46
|
+
readonly removeBy: string | undefined;
|
|
47
|
+
/** The previous variable name this one renames, if set -- see `ManifestChangeReport`'s rename correlation (ADR 0029/0030). */
|
|
48
|
+
readonly renamedFrom: string | undefined;
|
|
49
|
+
/** Descriptive retention policy (e.g. "delete after 90 days") -- a policy statement, never computed or parsed, deliberately independent of `expiresAt`'s actual temporal constraint. See ADR 0035. */
|
|
50
|
+
readonly retention: string | undefined;
|
|
51
|
+
/** See {@link runtime.VariableDocs.authenticatorType}. */
|
|
52
|
+
readonly authenticatorType: string | undefined;
|
|
53
|
+
/** See {@link runtime.VariableDocs.rotationPeriod}. */
|
|
54
|
+
readonly rotationPeriod: string | undefined;
|
|
55
|
+
/** See {@link runtime.VariableDocs.lastRotatedAt}. */
|
|
56
|
+
readonly lastRotatedAt: string | undefined;
|
|
57
|
+
/** See {@link runtime.VariableDocs.rotationTriggerEvents}. */
|
|
58
|
+
readonly rotationTriggerEvents: readonly string[] | undefined;
|
|
59
|
+
/** Computed, not stored -- see {@link RotationComplianceStatus} and `computeRotationStatus()`. */
|
|
60
|
+
readonly rotationStatus: RotationComplianceStatus;
|
|
61
|
+
}
|
|
62
|
+
/** One contract's own lifecycle data plus every variable of its that has at least one lifecycle field set. See {@link LifecycleModelVariable} for the per-variable shape. */
|
|
63
|
+
export interface LifecycleModelContract {
|
|
64
|
+
/** Root-relative, POSIX-separated -- matches `ContractModelContract.file`. */
|
|
65
|
+
readonly file: string;
|
|
66
|
+
readonly exportName: string;
|
|
67
|
+
readonly contractName: string;
|
|
68
|
+
readonly expiresAt: string | undefined;
|
|
69
|
+
readonly deprecated: boolean | undefined;
|
|
70
|
+
readonly deprecatedReason: string | undefined;
|
|
71
|
+
/** See {@link LifecycleModelVariable.retention}. */
|
|
72
|
+
readonly retention: string | undefined;
|
|
73
|
+
/** Only variables with at least one lifecycle field set (`expiresAt`, `refreshInstructions`, `deprecated`, `removeBy`, `renamedFrom`, `retention`, `authenticatorType`, `rotationPeriod`, `lastRotatedAt`, `rotationTriggerEvents`) -- same "only what's relevant" scope `renderLifecycleReport()` already uses for its rows. */
|
|
74
|
+
readonly variables: readonly LifecycleModelVariable[];
|
|
75
|
+
}
|
|
76
|
+
/** The versioned, JSON-serializable root of the Lifecycle Model -- see this module's own doc comment for the full picture. */
|
|
77
|
+
export interface LifecycleModel {
|
|
78
|
+
readonly schemaVersion: typeof LIFECYCLE_MODEL_SCHEMA_VERSION;
|
|
79
|
+
/** Only contracts with at least one lifecycle-relevant field set, at the contract level or on at least one variable. */
|
|
80
|
+
readonly contracts: readonly LifecycleModelContract[];
|
|
81
|
+
/**
|
|
82
|
+
* Every contract-/variable-level `expiresAt` within the configured window,
|
|
83
|
+
* soonest-first -- see `computeExpiringEntries()`. `file` is root-relative
|
|
84
|
+
* and POSIX-separated here, matching `LifecycleModelContract.file`/every
|
|
85
|
+
* other canonical model -- unlike `ExpiringEntry`'s own doc comment, which
|
|
86
|
+
* describes its shape in `computeExpiringEntries()`'s other direct
|
|
87
|
+
* consumers (e.g. `DocumentationFindings.expiringSoon`), where `file`
|
|
88
|
+
* stays the absolute path `renderDocs()` itself expects.
|
|
89
|
+
*/
|
|
90
|
+
readonly expiring: readonly ExpiringEntry[];
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* Parses `rotationPeriod` (e.g. "90 days", "P90D", "6 months") into a whole number of days, or
|
|
94
|
+
* `undefined` when it isn't in either recognized grammar.
|
|
95
|
+
*
|
|
96
|
+
* @remarks
|
|
97
|
+
* `rotationPeriod` is documented (`runtime/document.ts`) as an organization-defined string much
|
|
98
|
+
* like `retention` -- but unlike `retention`, which is *never* parsed (a pure policy statement),
|
|
99
|
+
* `computeRotationStatus()` genuinely needs a numeric due date to compare against `now`. This
|
|
100
|
+
* function is the one place that tension is resolved: it recognizes two small, common, unambiguous
|
|
101
|
+
* grammars (a plain "<n> <unit>" -- singular/plural/abbreviated, case-insensitive, with or without
|
|
102
|
+
* a space, e.g. "90 days"/"90day"/"12weeks" -- and ISO 8601's calendar-duration form, date
|
|
103
|
+
* components only (`PnYnMnD`, no `T`/time-of-day component since a rotation period is never
|
|
104
|
+
* meaningfully finer than a day; bare `"P"` is not a duration) rather than attempting to parse
|
|
105
|
+
* arbitrary prose ("quarterly", "every other release", ...) -- an org whose policy string doesn't
|
|
106
|
+
* fit either grammar still has it stored and rendered verbatim everywhere else, it just can't feed
|
|
107
|
+
* a computed due date, and `computeRotationStatus()` fails closed (`"overdue"`) rather than
|
|
108
|
+
* guessing at one. Month/year are calendar approximations (30/365 days) -- acceptable for a
|
|
109
|
+
* rotation-window signal, not precise enough for anything billing/calendar-accurate.
|
|
110
|
+
*
|
|
111
|
+
* A computed total of zero days (e.g. "0 days", "P0D", "P0Y0M0D" -- the digit grammar can't
|
|
112
|
+
* produce a *negative* total, but zero is reachable) is treated the same as an unparseable
|
|
113
|
+
* string, not a real duration: it returns `undefined` rather than `0`, so `computeRotationStatus()`
|
|
114
|
+
* falls into its own "declared but unverifiable" fail-closed path (`"overdue"`) instead of computing
|
|
115
|
+
* a degenerate due date equal to `lastRotatedAt` itself -- a nonsensical "rotate every zero days"
|
|
116
|
+
* policy should read as un-computable, not silently produce a technically-correct-but-meaningless
|
|
117
|
+
* due date.
|
|
118
|
+
*
|
|
119
|
+
* Both patterns are inlined at their `.exec()` call site, deliberately not hoisted to a
|
|
120
|
+
* module-level `const` -- same precedent as `source-position.ts`'s `parsePositionCitation()`: a
|
|
121
|
+
* module-level regex literal is a load-time-only ("static") mutation target, which Stryker's own
|
|
122
|
+
* `perTest` coverage analysis can't attribute to a specific covering test (see this package's own
|
|
123
|
+
* `stryker.config.mjs`), while an inline literal is re-evaluated -- and so mutation-tested -- on
|
|
124
|
+
* every call.
|
|
125
|
+
*/
|
|
126
|
+
export declare function parseRotationPeriodDays(value: string): number | undefined;
|
|
127
|
+
/**
|
|
128
|
+
* Computes one variable's NIST SP 800-53 IA-5 rotation status (a policy-window judgement) from its lifecycle facts,
|
|
129
|
+
* relative to `now`.
|
|
130
|
+
*
|
|
131
|
+
* @remarks
|
|
132
|
+
* **The judgment call this function makes** (IA-5's main statement itself only says "change or
|
|
133
|
+
* refresh authenticators [by an organization-defined period] or when [organization-defined events]
|
|
134
|
+
* occur" -- it doesn't define how a *pre-existing* `expiresAt` and a *new* `rotationPeriod`/
|
|
135
|
+
* `lastRotatedAt` pair should interact when both are declared on the same variable):
|
|
136
|
+
*
|
|
137
|
+
* - No rotation field declared at all (`hasRotationData()` false) -> `"undeclared"`. Not an error --
|
|
138
|
+
* most variables aren't authenticators, and saying nothing about rotation is the common, correct
|
|
139
|
+
* case, not a violation to report.
|
|
140
|
+
* - `expiresAt` is treated as authoritative and checked first, independent of everything else: if
|
|
141
|
+
* it's a valid date already in the past, the status is `"expired"`, full stop. Rationale: `expiresAt`
|
|
142
|
+
* is a pre-existing, often externally-imposed hard deadline (an API key's own issuer-enforced
|
|
143
|
+
* expiry, a certificate's NotAfter) -- once that date passes, the value has *literally* stopped
|
|
144
|
+
* being valid, which is categorically worse than merely being overdue for an internal policy
|
|
145
|
+
* rotation, and no internal rotation record can retroactively un-expire it.
|
|
146
|
+
* - Otherwise, if `rotationPeriod` is declared, it's checked against `lastRotatedAt`: both present,
|
|
147
|
+
* both parseable (see `parseRotationPeriodDays()`), *and* `lastRotatedAt` no later than `now` ->
|
|
148
|
+
* compute `lastRotatedAt + rotationPeriod` and compare to `now` (`"overdue"` if that due date has
|
|
149
|
+
* passed, else `"compliant"`). Any other case with `rotationPeriod` declared -- `lastRotatedAt`
|
|
150
|
+
* missing, either value not statically parseable, or `lastRotatedAt` itself in the future (a
|
|
151
|
+
* rotation can't have happened yet, so trusting it would let a bad timestamp manufacture false
|
|
152
|
+
* compliance) -- fails closed to `"overdue"`: IA-5 asks for evidence a rotation actually happened
|
|
153
|
+
* on schedule, and a declared obligation that can't be shown to have been met is reported as
|
|
154
|
+
* non-compliant rather than silently passed as compliant.
|
|
155
|
+
* - Otherwise (rotation metadata declared -- `authenticatorType` and/or `lastRotatedAt` and/or
|
|
156
|
+
* `rotationTriggerEvents` -- but no `rotationPeriod` and no past-due `expiresAt`) -> `"compliant"`:
|
|
157
|
+
* nothing here states a time-based obligation this variable could be failing to meet.
|
|
158
|
+
*
|
|
159
|
+
* `rotationTriggerEvents` (the event-based trigger) deliberately never changes the returned status
|
|
160
|
+
* by itself: env-cap has no way to observe whether a listed event (a suspected compromise, a
|
|
161
|
+
* personnel change, ...) actually occurred, so treating its mere presence as either compliant or
|
|
162
|
+
* overdue would be fabricating a signal. It's presence-only evidence that the event-based half of
|
|
163
|
+
* IA-5's two-trigger model was at least *declared* -- a generator can and should still surface it,
|
|
164
|
+
* just never fold it into this computed status.
|
|
165
|
+
*/
|
|
166
|
+
export declare function computeRotationStatus(variable: {
|
|
167
|
+
readonly expiresAt: string | undefined;
|
|
168
|
+
readonly authenticatorType: string | undefined;
|
|
169
|
+
readonly rotationPeriod: string | undefined;
|
|
170
|
+
readonly lastRotatedAt: string | undefined;
|
|
171
|
+
readonly rotationTriggerEvents: readonly string[] | undefined;
|
|
172
|
+
}, now: Date): RotationComplianceStatus;
|
|
173
|
+
/**
|
|
174
|
+
* Projects every discovered contract with at least one lifecycle-relevant
|
|
175
|
+
* field set into the Lifecycle Model's versioned, JSON-serializable shape,
|
|
176
|
+
* plus the already-established `expiring` view.
|
|
177
|
+
*/
|
|
178
|
+
export declare function buildLifecycleModel(contracts: readonly DiscoveredContract[], expiringWithinDays: number, now: Date, root: string): LifecycleModel;
|
|
179
|
+
//# sourceMappingURL=lifecycle-model.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"lifecycle-model.d.ts","sourceRoot":"","sources":["../../../src/build/lifecycle-model.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
import type { DiscoveredSchemaVariable, DiscoveredVariableEvidence, ParseWarning } from "./parse.js";
|
|
2
|
+
import type { EnvGovernanceFields } from "./governance-fields.js";
|
|
3
|
+
import type { ImportResolutionContext } from "./resolution/resolve-import.js";
|
|
4
|
+
import type { PackageOrigin } from "./resolution/resolve-package-schema.js";
|
|
5
|
+
import type { SourcePosition } from "./source-position.js";
|
|
6
|
+
/** One schema variable, merged with its linked `documentEnv()` documentation (if any). */
|
|
7
|
+
/**
|
|
8
|
+
* One schema variable merged with its linked `documentEnv()` documentation. Its
|
|
9
|
+
* governance fields (`owner` .. `metadata`) are `EnvGovernanceFields` --
|
|
10
|
+
* each an individual-variable override of the contract's own value, from the
|
|
11
|
+
* linked `documentEnv()` call's matching `variables` entry, or `undefined`.
|
|
12
|
+
*/
|
|
13
|
+
export interface DiscoveredVariable extends DiscoveredSchemaVariable, EnvGovernanceFields {
|
|
14
|
+
/** From the linked `documentEnv()` call's matching `variables` entry, if any. */
|
|
15
|
+
readonly description: string | undefined;
|
|
16
|
+
/** From the linked `documentEnv()` call's matching `variables` entry, if any. */
|
|
17
|
+
readonly refreshInstructions: string | undefined;
|
|
18
|
+
/** From the linked `documentEnv()` call's matching `variables` entry, if any. */
|
|
19
|
+
readonly authenticatorType: string | undefined;
|
|
20
|
+
/** From the linked `documentEnv()` call's matching `variables` entry, if any. */
|
|
21
|
+
readonly rotationPeriod: string | undefined;
|
|
22
|
+
/** From the linked `documentEnv()` call's matching `variables` entry, if any. */
|
|
23
|
+
readonly lastRotatedAt: string | undefined;
|
|
24
|
+
/** From the linked `documentEnv()` call's matching `variables` entry, if any. */
|
|
25
|
+
readonly rotationTriggerEvents: readonly string[] | undefined;
|
|
26
|
+
/** From the linked `documentEnv()` call's matching `variables` entry, if any. */
|
|
27
|
+
readonly setupInstructions: string | undefined;
|
|
28
|
+
/** From the linked `documentEnv()` call's matching `variables` entry, if any. */
|
|
29
|
+
readonly required: boolean | undefined;
|
|
30
|
+
/** From the linked `documentEnv()` call's matching `variables` entry, if any. */
|
|
31
|
+
readonly deprecated: boolean | undefined;
|
|
32
|
+
/** From the linked `documentEnv()` call's matching `variables` entry, if any. */
|
|
33
|
+
readonly deprecatedReason: string | undefined;
|
|
34
|
+
/** From the linked `documentEnv()` call's matching `variables` entry, if any. */
|
|
35
|
+
readonly removeBy: string | undefined;
|
|
36
|
+
/** From the linked `documentEnv()` call's matching `variables` entry, if any -- the previous variable name this one renames, if this declaration is the result of a rename. */
|
|
37
|
+
readonly renamedFrom: string | undefined;
|
|
38
|
+
/** The linked `documentEnv()` entry's `evidence` sub-object -- the re-verified-every-run half of this variable's documentation, deliberately not flattened in alongside the declared-only fields above. See {@link runtime.VariableEvidenceDocs} and ADR 0037. */
|
|
39
|
+
readonly evidence: DiscoveredVariableEvidence | undefined;
|
|
40
|
+
/** Whether this specific key had a matching entry in the linked `documentEnv()` call, if any. */
|
|
41
|
+
readonly documented: boolean;
|
|
42
|
+
}
|
|
43
|
+
/** One `createEnv()` contract, merged with its linked `documentEnv()` documentation (if any). Its governance fields (`owner` .. `metadata`) are `EnvGovernanceFields` -- contract-level defaults that individual variables may override. */
|
|
44
|
+
export interface DiscoveredContract extends EnvGovernanceFields {
|
|
45
|
+
/** Absolute path of the file declaring the `createEnv()` call. */
|
|
46
|
+
readonly file: string;
|
|
47
|
+
/** The binding name the `createEnv()` result is exported as. */
|
|
48
|
+
readonly exportName: string;
|
|
49
|
+
/** Resolved display name: linked `documentEnv()`'s `name`, else `createEnv()`'s own `name` option, else `exportName`. */
|
|
50
|
+
readonly contractName: string;
|
|
51
|
+
/** From the linked `documentEnv()`'s `active` option. Defaults to `true` when omitted or undocumented. */
|
|
52
|
+
readonly active: boolean;
|
|
53
|
+
/** From the linked `documentEnv()` call, if any. */
|
|
54
|
+
readonly category: string | undefined;
|
|
55
|
+
/** From the linked `documentEnv()` call, if any -- see {@link runtime.ContractDocs.exclusiveGroup}. */
|
|
56
|
+
readonly exclusiveGroup: string | undefined;
|
|
57
|
+
/** From the linked `documentEnv()` call, if any. */
|
|
58
|
+
readonly deprecated: boolean | undefined;
|
|
59
|
+
/** From the linked `documentEnv()` call, if any. */
|
|
60
|
+
readonly deprecatedReason: string | undefined;
|
|
61
|
+
/** Every variable declared in the schema, merged with its linked documentation. */
|
|
62
|
+
readonly variables: readonly DiscoveredVariable[];
|
|
63
|
+
/** Whether *any* `documentEnv()` call is linked to this contract at all. */
|
|
64
|
+
readonly documented: boolean;
|
|
65
|
+
/** Set when this contract was discovered via an allow-listed package's
|
|
66
|
+
* declared schema entry point rather than local discovery -- the bare
|
|
67
|
+
* package name `renderManifest()` must import from instead of computing a
|
|
68
|
+
* relative path to the (analysis-only) resolved file. See ADR 0014. */
|
|
69
|
+
readonly packageOrigin: PackageOrigin | undefined;
|
|
70
|
+
/** Where this contract's `createEnv(...)` call is declared. Always present -- every discovered contract has one, by definition. See ADR 0036. */
|
|
71
|
+
readonly declaration: SourcePosition;
|
|
72
|
+
/** Where this contract's `documentEnv(...)` call is declared, if one exists. Undefined for a contract that's never been documented. See ADR 0036. */
|
|
73
|
+
readonly documentation: SourcePosition | undefined;
|
|
74
|
+
}
|
|
75
|
+
/** A `documentEnv()` call that could not be statically linked back to a `createEnv()` schema. */
|
|
76
|
+
export interface UnresolvedLink {
|
|
77
|
+
/** Absolute path of the file containing the unlinkable call. */
|
|
78
|
+
readonly file: string;
|
|
79
|
+
/** Human-readable explanation of why the link couldn't be resolved. */
|
|
80
|
+
readonly reason: string;
|
|
81
|
+
}
|
|
82
|
+
/** The full result of {@link linkFiles}: every linked contract, plus every category of thing that didn't link cleanly. */
|
|
83
|
+
export interface LinkResult {
|
|
84
|
+
/** Every `createEnv()` contract found, merged with its documentation. */
|
|
85
|
+
readonly contracts: readonly DiscoveredContract[];
|
|
86
|
+
/** Parse-time warnings collected across every analyzed file. */
|
|
87
|
+
readonly warnings: readonly ParseWarning[];
|
|
88
|
+
/** `documentEnv()` calls that couldn't be statically linked to a schema. */
|
|
89
|
+
readonly unresolvedLinks: readonly UnresolvedLink[];
|
|
90
|
+
/** Contracts with no linked `documentEnv()` call at all. */
|
|
91
|
+
readonly undocumentedContracts: readonly {
|
|
92
|
+
/** Absolute path of the file declaring the contract. */
|
|
93
|
+
readonly file: string;
|
|
94
|
+
/** The contract's exported binding name. */
|
|
95
|
+
readonly exportName: string;
|
|
96
|
+
}[];
|
|
97
|
+
/** Schema variables with no matching entry in their contract's linked documentation. */
|
|
98
|
+
readonly undocumentedVariables: readonly {
|
|
99
|
+
/** Absolute path of the file declaring the contract. */
|
|
100
|
+
readonly file: string;
|
|
101
|
+
/** The contract's exported binding name. */
|
|
102
|
+
readonly exportName: string;
|
|
103
|
+
/** The undocumented environment variable name. */
|
|
104
|
+
readonly key: string;
|
|
105
|
+
}[];
|
|
106
|
+
/** Documented variable entries with no matching schema variable (the schema key was removed or renamed). */
|
|
107
|
+
readonly staleDocEntries: readonly {
|
|
108
|
+
/** Absolute path of the file declaring the contract. */
|
|
109
|
+
readonly file: string;
|
|
110
|
+
/** The contract's exported binding name. */
|
|
111
|
+
readonly exportName: string;
|
|
112
|
+
/** The stale documented variable name. */
|
|
113
|
+
readonly key: string;
|
|
114
|
+
}[];
|
|
115
|
+
}
|
|
116
|
+
/**
|
|
117
|
+
* Parses every discovered file, then resolves and links `createEnv`/
|
|
118
|
+
* `documentEnv` calls into the merged, docs-enriched contract shape the rest
|
|
119
|
+
* of the generator (`compatibility.ts`, `exclusive-group.ts`, `manifest.ts`,
|
|
120
|
+
* `docs.ts`, `env-example.ts`) consumes.
|
|
121
|
+
*
|
|
122
|
+
* @remarks
|
|
123
|
+
* Cross-file linking is deliberately narrow (see `resolveImportSpecifier`):
|
|
124
|
+
* a `documentEnv()` call's schema reference resolves either to a `const` in
|
|
125
|
+
* its own file, to a directly-imported named export of another file's
|
|
126
|
+
* `const`, or (since ADR 0014) to an allow-listed package's declared schema
|
|
127
|
+
* entry point. Anything else -- a re-export barrel, a namespace import, an
|
|
128
|
+
* unlisted bare package specifier -- becomes an `unresolvedLinks` entry
|
|
129
|
+
* rather than a throw or a guess, exactly like every other static-analysis
|
|
130
|
+
* boundary in this codebase.
|
|
131
|
+
*
|
|
132
|
+
* `packageOrigins` (from `resolveAllowlistedPackages()`) tags any discovered
|
|
133
|
+
* contract whose `file` matches a package-resolved path with that package's
|
|
134
|
+
* origin -- purely a lookup; `discoveredFiles` must already include those
|
|
135
|
+
* files (merged in by the caller via `mergeLocalAndPackageFiles()`).
|
|
136
|
+
*
|
|
137
|
+
* @param context - See `ImportResolutionContext`; drives how a resolved import specifier maps back to a file on disk.
|
|
138
|
+
*/
|
|
139
|
+
export declare function linkFiles(discoveredFiles: readonly string[], readFile: (filePath: string) => Promise<string>, context: ImportResolutionContext, packageOrigins?: ReadonlyMap<string, PackageOrigin>): Promise<LinkResult>;
|
|
140
|
+
/** Root-relative projection of a {@link DiscoveredContract}, as returned by {@link generateEnvManifest}/{@link generateDocumentation}. */
|
|
141
|
+
export interface DiscoveredContractSummary {
|
|
142
|
+
/** Root-relative, POSIX-separated file path. */
|
|
143
|
+
readonly file: string;
|
|
144
|
+
/** The binding name the `createEnv()` result is exported as. */
|
|
145
|
+
readonly exportName: string;
|
|
146
|
+
/** Resolved display name (see {@link DiscoveredContract.contractName}). */
|
|
147
|
+
readonly contractName: string;
|
|
148
|
+
/** Number of variables declared in this contract's schema. */
|
|
149
|
+
readonly variableCount: number;
|
|
150
|
+
/** Whether this contract was included in the generated manifest (`active` defaults to true). */
|
|
151
|
+
readonly active: boolean;
|
|
152
|
+
/** Whether a `documentEnv()` call is linked to this contract. */
|
|
153
|
+
readonly documented: boolean;
|
|
154
|
+
}
|
|
155
|
+
/**
|
|
156
|
+
* Projects a {@link DiscoveredContract} (absolute `file`) into the root-relative
|
|
157
|
+
* summary shape returned by {@link generateEnvManifest}/{@link generateDocumentation}.
|
|
158
|
+
*
|
|
159
|
+
* @remarks
|
|
160
|
+
* Pulled out here, rather than duplicated in both, since it's a pure
|
|
161
|
+
* projection with no manifest- or docs-specific behavior.
|
|
162
|
+
*/
|
|
163
|
+
export declare function summarizeContract(contract: DiscoveredContract, root: string): DiscoveredContractSummary;
|
|
164
|
+
/**
|
|
165
|
+
* A variable's owner, falling back to its contract's default when the
|
|
166
|
+
* variable itself doesn't set one.
|
|
167
|
+
*
|
|
168
|
+
* @remarks
|
|
169
|
+
* The one place this resolution rule should live -- see ADR 0028. Every
|
|
170
|
+
* caller that needs "who owns this variable" (the docs Catalog/ownership
|
|
171
|
+
* matrix/security review, and, as of ADR 0028, the usage report's
|
|
172
|
+
* variable-level ownership findings) must go through this, not
|
|
173
|
+
* `variable.owner` or `contract.owner` alone, so two call sites can never
|
|
174
|
+
* again disagree about who owns a variable the way `docs.ts` and
|
|
175
|
+
* `usage-report.ts` once did.
|
|
176
|
+
*
|
|
177
|
+
* Structurally typed (not pinned to `DiscoveredContract`/`DiscoveredVariable`)
|
|
178
|
+
* so the same one resolution rule also serves `ContractModelContract`/
|
|
179
|
+
* `ContractModelVariable` (`contract-model.ts`) -- both shapes carry the same
|
|
180
|
+
* field, and this rule must never have two independent implementations.
|
|
181
|
+
*/
|
|
182
|
+
export declare function effectiveOwner(contract: {
|
|
183
|
+
readonly owner: string | undefined;
|
|
184
|
+
}, variable: {
|
|
185
|
+
readonly owner: string | undefined;
|
|
186
|
+
}): string | undefined;
|
|
187
|
+
/** A variable's sensitivity, falling back to its contract's default -- see {@link effectiveOwner}. */
|
|
188
|
+
export declare function effectiveSensitivity(contract: {
|
|
189
|
+
readonly sensitivity: string | undefined;
|
|
190
|
+
}, variable: {
|
|
191
|
+
readonly sensitivity: string | undefined;
|
|
192
|
+
}): string | undefined;
|
|
193
|
+
/** A variable's purpose, falling back to its contract's default -- see {@link effectiveOwner}. */
|
|
194
|
+
export declare function effectivePurpose(contract: {
|
|
195
|
+
readonly purpose: string | undefined;
|
|
196
|
+
}, variable: {
|
|
197
|
+
readonly purpose: string | undefined;
|
|
198
|
+
}): string | undefined;
|
|
199
|
+
/** A variable's legal basis, falling back to its contract's default -- see {@link effectiveOwner}. */
|
|
200
|
+
export declare function effectiveLegalBasis(contract: {
|
|
201
|
+
readonly legalBasis: string | undefined;
|
|
202
|
+
}, variable: {
|
|
203
|
+
readonly legalBasis: string | undefined;
|
|
204
|
+
}): string | undefined;
|
|
205
|
+
/** A variable's retention policy, falling back to its contract's default -- see {@link effectiveOwner}. */
|
|
206
|
+
export declare function effectiveRetention(contract: {
|
|
207
|
+
readonly retention: string | undefined;
|
|
208
|
+
}, variable: {
|
|
209
|
+
readonly retention: string | undefined;
|
|
210
|
+
}): string | undefined;
|
|
211
|
+
/** A variable's data residency, falling back to its contract's default -- see {@link effectiveOwner}. */
|
|
212
|
+
export declare function effectiveDataResidency(contract: {
|
|
213
|
+
readonly dataResidency: string | readonly string[] | undefined;
|
|
214
|
+
}, variable: {
|
|
215
|
+
readonly dataResidency: string | readonly string[] | undefined;
|
|
216
|
+
}): string | readonly string[] | undefined;
|
|
217
|
+
/** A variable's audit-required assertion, falling back to its contract's default -- see {@link effectiveOwner}. */
|
|
218
|
+
export declare function effectiveAuditRequired(contract: {
|
|
219
|
+
readonly auditRequired: boolean | undefined;
|
|
220
|
+
}, variable: {
|
|
221
|
+
readonly auditRequired: boolean | undefined;
|
|
222
|
+
}): boolean | undefined;
|
|
223
|
+
//# sourceMappingURL=link.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../../../src/build/link.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import type TS from "@typescript/typescript6";
|
|
2
|
+
/**
|
|
3
|
+
* The result of a literal evaluation: either a real JS value, or `{ ok: false }` when the AST
|
|
4
|
+
* expression wasn't a literal (or contained a non-literal element/property).
|
|
5
|
+
*/
|
|
6
|
+
export type LiteralEvalResult = {
|
|
7
|
+
ok: true;
|
|
8
|
+
value: unknown;
|
|
9
|
+
} | {
|
|
10
|
+
ok: false;
|
|
11
|
+
value?: undefined;
|
|
12
|
+
};
|
|
13
|
+
/**
|
|
14
|
+
* Structurally evaluates a *literal* AST expression (strings, numbers, booleans, null, arrays,
|
|
15
|
+
* and object literals of the same) into a real JS value -- without ever executing code.
|
|
16
|
+
*
|
|
17
|
+
* @remarks
|
|
18
|
+
* Anything that isn't a literal (identifiers, calls, imports, template expressions with
|
|
19
|
+
* interpolation) resolves to `{ ok: false }` rather than being guessed at.
|
|
20
|
+
*/
|
|
21
|
+
export declare function evaluateLiteral(node: TS.Expression): LiteralEvalResult;
|
|
22
|
+
/** Reads a property name statically (identifier, string literal, or numeric literal) -- a computed key (e.g. `[expr]`) resolves to `undefined` rather than being guessed at. */
|
|
23
|
+
export declare function getStaticPropertyName(name: TS.PropertyName): string | undefined;
|
|
24
|
+
//# sourceMappingURL=literal-eval.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"literal-eval.d.ts","sourceRoot":"","sources":["../../../src/build/literal-eval.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAA;AAEhC;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,CAAA;AAE/F;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,GAAG,iBAAiB,CA4CtE;AAED,gLAAgL;AAChL,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,GAAG,MAAM,GAAG,SAAS,CAK/E"}
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import type { DiscoveredContract } from "./link.js";
|
|
2
|
+
/**
|
|
3
|
+
* Supplies expiration metadata from a live source (a secrets manager, an
|
|
4
|
+
* internal inventory API, ...) as a post-discovery override -- the one
|
|
5
|
+
* sanctioned escape hatch from static-only `expiresAt`.
|
|
6
|
+
*
|
|
7
|
+
* @remarks
|
|
8
|
+
* Invoked exactly once per generation run, from the orchestration layer, after AST discovery/
|
|
9
|
+
* linking completes and before documentation is rendered. Never invoked
|
|
10
|
+
* during AST parsing or runtime validation -- see ADR 0012 for why a
|
|
11
|
+
* function embedded in a schema file itself was rejected instead.
|
|
12
|
+
*/
|
|
13
|
+
export type LiveExpirationDates = (variableNames: readonly string[]) => Promise<Readonly<Record<string, string>>>;
|
|
14
|
+
/**
|
|
15
|
+
* Every unique variable key across every linked contract's `variables`.
|
|
16
|
+
* Contract-level `expiresAt` is out of scope for override -- the callback is
|
|
17
|
+
* keyed by variable name, not contract name.
|
|
18
|
+
*/
|
|
19
|
+
export declare function collectVariableNames(contracts: readonly DiscoveredContract[]): string[];
|
|
20
|
+
/**
|
|
21
|
+
* Applies `overrides` onto a fresh copy of `contracts` -- every contract and
|
|
22
|
+
* every variable (and their nested `metadata`/`extra` records) is rebuilt
|
|
23
|
+
* into a new object, never the original reference, so the returned structure
|
|
24
|
+
* shares no mutable object identity with `contracts` at any depth.
|
|
25
|
+
*
|
|
26
|
+
* @remarks
|
|
27
|
+
* A key absent from `overrides`, or present but not a `parseIsoDate`-parseable
|
|
28
|
+
* ISO-8601 string, leaves that variable's static `expiresAt` untouched --
|
|
29
|
+
* same "warn/skip, never guess" policy the rest of the generator uses for
|
|
30
|
+
* malformed data. Contract-level `expiresAt` is never touched; only
|
|
31
|
+
* variable-level `expiresAt` is in scope for override.
|
|
32
|
+
*/
|
|
33
|
+
export declare function applyLiveExpirationOverrides(contracts: readonly DiscoveredContract[], overrides: Readonly<Record<string, string>>): readonly DiscoveredContract[];
|
|
34
|
+
/**
|
|
35
|
+
* Orchestration entry point -- the only place `liveExpirationDates` is ever invoked.
|
|
36
|
+
*
|
|
37
|
+
* @remarks
|
|
38
|
+
* No-ops (returns the exact same array reference, zero invocations)
|
|
39
|
+
* when `liveExpirationDates` is undefined, which is what guarantees "omitted ->
|
|
40
|
+
* behavior unchanged." Otherwise collects the unique discovered variable
|
|
41
|
+
* names, invokes the callback exactly once, applies the result, and
|
|
42
|
+
* deep-freezes the returned structure so it can never be mutated into
|
|
43
|
+
* affecting `contracts` (used elsewhere, e.g. by the manifest/usage passes in
|
|
44
|
+
* the same {@link generateEnvArtifacts} run) or anything else downstream.
|
|
45
|
+
*/
|
|
46
|
+
export declare function resolveLiveExpirationDates(contracts: readonly DiscoveredContract[], liveExpirationDates: LiveExpirationDates | undefined): Promise<readonly DiscoveredContract[]>;
|
|
47
|
+
//# sourceMappingURL=live-expirations.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"live-expirations.d.ts","sourceRoot":"","sources":["../../../src/build/live-expirations.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAsB,MAAM,WAAW,CAAA;AAEvE;;;;;;;;;;GAUG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAChC,aAAa,EAAE,SAAS,MAAM,EAAE,KAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;AAE9C;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,SAAS,kBAAkB,EAAE,GAAG,MAAM,EAAE,CAMvF;AAiBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAC1C,SAAS,kBAAkB,EAAE,CAM/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,0BAA0B,CAC9C,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,mBAAmB,EAAE,mBAAmB,GAAG,SAAS,GACnD,OAAO,CAAC,SAAS,kBAAkB,EAAE,CAAC,CAIxC"}
|