@maverickcer/env-cap 0.7.3 → 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 +23 -0
- package/CODE_REVIEW.md +69 -173
- package/CONTRIBUTING.md +57 -74
- package/GUIDE.md +393 -872
- package/README.md +82 -77
- 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 +0 -14
- 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-LFHPVDQL.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-ZW3BLAPD.js → chunk-HAGMVMN5.js} +2 -2
- package/dist/cli/index.js +3 -3
- package/dist/eslint-plugin/index.cjs +8 -5
- package/dist/eslint-plugin/index.cjs.map +1 -1
- package/dist/eslint-plugin/index.js +8 -5
- 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 +37 -6
- 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-LFHPVDQL.js.map +0 -1
- /package/dist/{chunk-ZW3BLAPD.js.map → chunk-HAGMVMN5.js.map} +0 -0
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
import type { CompatibilityIssue } from "./compatibility.js";
|
|
2
|
+
import type { EvidenceModel } from "./evidence-model.js";
|
|
3
|
+
import type { Finding, FindingFamily } from "./finding-model.js";
|
|
4
|
+
import type { DocumentationComputation, GenerateDocumentationOptions, GenerateDocumentationResult } from "./generate-documentation.js";
|
|
5
|
+
import type { GenerateEnvManifestOptions, GenerateEnvManifestResult, ManifestComputation } from "./generate-manifest.js";
|
|
6
|
+
import type { GenerateUsageReportOptions, GenerateUsageReportResult, UsageComputation } from "./generate-usage.js";
|
|
7
|
+
import type { DiscoveredContract } from "./link.js";
|
|
8
|
+
import type { LiveExpirationDates } from "./live-expirations.js";
|
|
9
|
+
import type { ParseWarning } from "./parse.js";
|
|
10
|
+
import type { BuildFileSystem } from "./types.js";
|
|
11
|
+
/** Options for {@link generateEnvArtifacts}. */
|
|
12
|
+
export interface GenerateEnvArtifactsOptions {
|
|
13
|
+
/** The filesystem capability, shared across every requested pass -- `./build` never imports `node:fs` (ADR 0040). */
|
|
14
|
+
fs: BuildFileSystem;
|
|
15
|
+
/** Directory glob patterns are resolved against, shared across every requested pass. Defaults to `process.cwd()`. */
|
|
16
|
+
root?: string | undefined;
|
|
17
|
+
/** Shared schema-discovery glob for the contract graph. Defaults to `["**\/env.schema.ts"]`. */
|
|
18
|
+
include?: string[] | undefined;
|
|
19
|
+
/** Glob patterns to exclude, shared across every requested pass. Defaults to node_modules/dist/.git. */
|
|
20
|
+
exclude?: string[] | undefined;
|
|
21
|
+
/** See `GenerateEnvManifestOptions.packages`; shared across every requested pass. See ADR 0014. */
|
|
22
|
+
packages?: readonly string[] | undefined;
|
|
23
|
+
/** See `GenerateEnvManifestOptions.tsconfig`; shared across every requested pass. See ADR 0023. */
|
|
24
|
+
tsconfig?: string | false | undefined;
|
|
25
|
+
/** Manifest pass options, or `false` to skip it entirely. */
|
|
26
|
+
manifest?: Omit<GenerateEnvManifestOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig"> | false | undefined;
|
|
27
|
+
/** Docs pass options, or `false` to skip it entirely. */
|
|
28
|
+
docs?: Omit<GenerateDocumentationOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig" | "liveExpirationDates"> | false | undefined;
|
|
29
|
+
/** Usage-report pass options, or `false` to skip it entirely. */
|
|
30
|
+
usage?: Omit<GenerateUsageReportOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig"> | false | undefined;
|
|
31
|
+
/**
|
|
32
|
+
* Where to write the persisted evidence artifact (the full, literal
|
|
33
|
+
* `EvidenceModel`, plus a paired `.fingerprint` sidecar -- see
|
|
34
|
+
* `evidence-cache.ts`), e.g. `docs/env.evidence.json`, relative to `root`.
|
|
35
|
+
* Independent of `manifest.location` -- requesting this needs no other
|
|
36
|
+
* pass, and generating a manifest never requires it. `EvidenceModel`
|
|
37
|
+
* itself is always computed regardless of this option (ADR 0038, "free to
|
|
38
|
+
* compute, always real") and always returned as `result.evidence`; this
|
|
39
|
+
* option controls only whether it's also written to disk. Omitted:
|
|
40
|
+
* nothing is written, `result.evidence` is still populated.
|
|
41
|
+
*/
|
|
42
|
+
evidence?: {
|
|
43
|
+
location: string;
|
|
44
|
+
} | false | undefined;
|
|
45
|
+
/**
|
|
46
|
+
* Escalates every warning-severity `"documentation"`-family finding
|
|
47
|
+
* (undocumented contracts/variables, stale doc entries, expiring/expired
|
|
48
|
+
* entries, unresolvable `documentEnv()` links) into a blocking error, so a
|
|
49
|
+
* run with any of them writes nothing and throws. Defaults to `"warn"` --
|
|
50
|
+
* ADR 0038's stance, unchanged: documentation gaps never block by default.
|
|
51
|
+
*
|
|
52
|
+
* @remarks
|
|
53
|
+
* Scoped deliberately narrowly, unlike `manifest.onIncompatibility`, which
|
|
54
|
+
* gates only the compatibility family. `"info"`-severity findings are never
|
|
55
|
+
* escalated by either -- see `Finding.severity`.
|
|
56
|
+
*/
|
|
57
|
+
onUndocumented?: "warn" | "throw" | undefined;
|
|
58
|
+
/**
|
|
59
|
+
* Escalates every warning-severity `"ownership"`-family finding (abandoned
|
|
60
|
+
* contracts, unresolved consumers, unconsumed owned variables,
|
|
61
|
+
* indeterminate ownership, stale/missing `dynamicAccess` citations) into a
|
|
62
|
+
* blocking error. Defaults to `"warn"` -- see {@link onUndocumented}.
|
|
63
|
+
*/
|
|
64
|
+
onOwnershipIssue?: "warn" | "throw" | undefined;
|
|
65
|
+
/**
|
|
66
|
+
* Supplies expiration metadata from a live source (a secrets manager, an
|
|
67
|
+
* internal inventory API, ...) as a post-discovery override applied only to
|
|
68
|
+
* the docs pass. Invoked at most once, only when a `docs` pass is actually
|
|
69
|
+
* requested, with every discovered variable name across all passes' shared
|
|
70
|
+
* contract graph. See `live-expirations.ts` and ADR 0012. Omitted: behavior
|
|
71
|
+
* is unchanged from a purely static `expiresAt`.
|
|
72
|
+
*/
|
|
73
|
+
liveExpirationDates?: LiveExpirationDates | undefined;
|
|
74
|
+
}
|
|
75
|
+
/** The result of a completed {@link generateEnvArtifacts} run. */
|
|
76
|
+
export interface GenerateEnvArtifactsResult {
|
|
77
|
+
/** Set only when `options.manifest` wasn't `false`. */
|
|
78
|
+
readonly manifest: GenerateEnvManifestResult | undefined;
|
|
79
|
+
/** Set only when `options.docs` wasn't `false`. */
|
|
80
|
+
readonly docs: GenerateDocumentationResult | undefined;
|
|
81
|
+
/** Set only when `options.usage` wasn't `false`. */
|
|
82
|
+
readonly usage: GenerateUsageReportResult | undefined;
|
|
83
|
+
/** Always populated, regardless of `options.evidence` -- see that option's own doc comment. */
|
|
84
|
+
readonly evidence: EvidenceModel;
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* Every intermediate value both the write path (`generateEnvArtifacts()`
|
|
88
|
+
* below) and the drift-check path (`checkEnvArtifacts()` in
|
|
89
|
+
* `check-artifacts.ts`) need, computed exactly once. Internal/Private tier
|
|
90
|
+
* per `VERSIONING.md` -- not re-exported from `./index.ts`.
|
|
91
|
+
*/
|
|
92
|
+
export interface ComputeArtifactsResult {
|
|
93
|
+
readonly root: string;
|
|
94
|
+
/** Set only when a manifest pass was requested. */
|
|
95
|
+
readonly manifest: {
|
|
96
|
+
readonly options: Omit<GenerateEnvManifestOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig">;
|
|
97
|
+
readonly outputPath: string;
|
|
98
|
+
readonly computed: ManifestComputation;
|
|
99
|
+
} | undefined;
|
|
100
|
+
/** Set only when a docs pass was requested; `envExamplePath` only when it also asked for an example file. */
|
|
101
|
+
readonly docs: {
|
|
102
|
+
readonly options: Omit<GenerateDocumentationOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig" | "liveExpirationDates">;
|
|
103
|
+
readonly path: string;
|
|
104
|
+
readonly envExamplePath: string | undefined;
|
|
105
|
+
} | undefined;
|
|
106
|
+
/** Always computed -- Finding Model needs it regardless of whether a `docs` pass was itself requested. See ADR 0038. */
|
|
107
|
+
readonly docsComputed: DocumentationComputation;
|
|
108
|
+
readonly docsContracts: readonly DiscoveredContract[];
|
|
109
|
+
/** Set only when a usage pass was requested; `reportPath` only when it also asked for a report file. */
|
|
110
|
+
readonly usage: {
|
|
111
|
+
readonly options: Omit<GenerateUsageReportOptions, "fs" | "root" | "include" | "exclude" | "packages" | "tsconfig">;
|
|
112
|
+
readonly reportPath: string | undefined;
|
|
113
|
+
} | undefined;
|
|
114
|
+
/** Always computed -- Finding Model needs it regardless of whether a `usage` pass was itself requested. See ADR 0038. */
|
|
115
|
+
readonly usageComputed: UsageComputation;
|
|
116
|
+
readonly evidencePath: string | undefined;
|
|
117
|
+
readonly evidence: EvidenceModel;
|
|
118
|
+
readonly blocking: readonly CompatibilityIssue[];
|
|
119
|
+
readonly packageWarnings: readonly ParseWarning[];
|
|
120
|
+
readonly linkWarnings: readonly ParseWarning[];
|
|
121
|
+
/** Single timestamp shared by every pass' own time-sensitive computation (`expiringSoon`, `EvidenceModel.provenance.generatedAt`), so all of them agree on exactly the same instant. */
|
|
122
|
+
readonly generatedAt: Date;
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* Adapts every warning-severity finding of one family into the
|
|
126
|
+
* `CompatibilityIssue` shape `blocking`/`EnvProjectGenerationError` speak, so
|
|
127
|
+
* `--strict-docs`/`--strict-ownership` fail through exactly the same path
|
|
128
|
+
* `--strict` already does rather than inventing a second failure mode.
|
|
129
|
+
*
|
|
130
|
+
* @remarks
|
|
131
|
+
* `"info"` findings are filtered out unconditionally and can never be
|
|
132
|
+
* escalated by any flag -- they're observations, not gaps (see
|
|
133
|
+
* `Finding.severity`). `"error"` findings are excluded too: those already
|
|
134
|
+
* block on their own, via the manifest pass, and re-adding them here would
|
|
135
|
+
* report the same violation twice in one error message. `code` is left unset
|
|
136
|
+
* -- `CompatibilityIssueCode` is that check family's own closed vocabulary,
|
|
137
|
+
* and a `FindingCode` from another family is not a member of it.
|
|
138
|
+
*/
|
|
139
|
+
/** @internal Exported for direct unit coverage -- reached through `generateEnvArtifacts()`'s `--strict-docs`/`--strict-ownership` flags in production, but its filter/mapping logic isn't independently observable through that path alone (every mutant on it still needs a real `computeArtifacts()` call, discovery included, to reach it). */
|
|
140
|
+
export declare function escalatedFindings(findings: readonly Finding[], family: FindingFamily): CompatibilityIssue[];
|
|
141
|
+
/** The variable a finding is about, or a `"(contract) <name>"` label when it's contract-level -- matching `CompatibilityIssue.variable`'s own documented convention.
|
|
142
|
+
* @internal Exported for direct unit coverage -- see {@link escalatedFindings}'s own doc comment for why. */
|
|
143
|
+
export declare function findingSubject(finding: Finding): string;
|
|
144
|
+
/** Every file a finding names, as `CompatibilityIssue.files` -- empty when its location carries none (an ownership finding about a variable, which names no single file).
|
|
145
|
+
* @internal Exported for direct unit coverage -- see {@link escalatedFindings}'s own doc comment for why. */
|
|
146
|
+
export declare function findingFiles(finding: Finding): string[];
|
|
147
|
+
/**
|
|
148
|
+
* A pass's options, or `undefined` when the pass is not requested: `false` skips a pass entirely,
|
|
149
|
+
* exactly as omitting it does.
|
|
150
|
+
* @internal Exported for direct unit coverage.
|
|
151
|
+
*/
|
|
152
|
+
export declare function requestedPass<T extends object>(option: T | false | undefined): T | undefined;
|
|
153
|
+
/**
|
|
154
|
+
* Runs schema discovery, linking, and every requested pass's pure `compute*()`
|
|
155
|
+
* step -- but never writes anything to disk. Throws `EnvProjectGenerationError`
|
|
156
|
+
* immediately if any requested output location escapes `root` (same
|
|
157
|
+
* fail-fast-before-any-work guarantee `generateEnvArtifacts()` has always
|
|
158
|
+
* given); otherwise returns every intermediate value without itself checking
|
|
159
|
+
* `blocking` findings, so callers (the write path below, and `--check`'s
|
|
160
|
+
* `checkEnvArtifacts()`) each decide when to throw on those.
|
|
161
|
+
*
|
|
162
|
+
* @remarks
|
|
163
|
+
* The six canonical fact models (Contract/Dependency/Ownership/Lifecycle/
|
|
164
|
+
* Finding/Change -> `EvidenceModel`) are composed on every call,
|
|
165
|
+
* unconditionally, reusing the exact same builders `generateEvidenceModel()`
|
|
166
|
+
* calls -- not a second implementation of the same assembly. See ADR 0038.
|
|
167
|
+
*/
|
|
168
|
+
export declare function computeArtifacts(options: GenerateEnvArtifactsOptions): Promise<ComputeArtifactsResult>;
|
|
169
|
+
/**
|
|
170
|
+
* Orchestrates {@link generateEnvManifest}/{@link generateDocumentation}/
|
|
171
|
+
* {@link generateUsageReport}, plus the persisted evidence artifact, by
|
|
172
|
+
* composing their shared private compute/write pipeline directly, running
|
|
173
|
+
* schema discovery+linking exactly once regardless of how many outputs are
|
|
174
|
+
* requested -- an orchestrator, not a new analysis engine (see ADR 0011).
|
|
175
|
+
*
|
|
176
|
+
* @remarks
|
|
177
|
+
* Two distinct atomicity guarantees, not one:
|
|
178
|
+
* - **Compute atomicity (guaranteed)**: every requested pass's blocking
|
|
179
|
+
* findings are checked, across all passes, before any pass writes
|
|
180
|
+
* anything.
|
|
181
|
+
* - **Write atomicity (NOT guaranteed, and not attempted)**: once writes
|
|
182
|
+
* begin, each `fs.writeFile` is independent. A real I/O failure partway
|
|
183
|
+
* through (disk full, permissions changed mid-run) can leave some
|
|
184
|
+
* artifacts on disk and not others. Transactional (temp-file + rename)
|
|
185
|
+
* writes across all three artifacts were considered and rejected as
|
|
186
|
+
* disproportionate machinery for a rare failure mode -- see ADR 0011.
|
|
187
|
+
*
|
|
188
|
+
* @throws {EnvProjectGenerationError} If any requested output location escapes `root`, or if any requested pass reports a blocking finding.
|
|
189
|
+
*/
|
|
190
|
+
export declare function generateEnvArtifacts(options: GenerateEnvArtifactsOptions): Promise<GenerateEnvArtifactsResult>;
|
|
191
|
+
//# sourceMappingURL=generate-env-artifacts.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"generate-env-artifacts.d.ts","sourceRoot":"","sources":["../../../src/build/generate-env-artifacts.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
import type { EvidenceModel } from "./evidence-model.js";
|
|
2
|
+
import type { LiveExpirationDates } from "./live-expirations.js";
|
|
3
|
+
import type { BuildFileSystem } from "./types.js";
|
|
4
|
+
/** Options for {@link generateEvidenceModel}. */
|
|
5
|
+
export interface GenerateEvidenceModelOptions {
|
|
6
|
+
/** The filesystem capability -- `./build` never imports `node:fs` (ADR 0040). */
|
|
7
|
+
fs: BuildFileSystem;
|
|
8
|
+
/** Directory glob patterns are resolved against. Defaults to `process.cwd()`. */
|
|
9
|
+
root?: string | undefined;
|
|
10
|
+
/** Schema-discovery glob for the contract graph. Defaults to `["**\/env.schema.ts"]`. */
|
|
11
|
+
include?: string[] | undefined;
|
|
12
|
+
/** Glob patterns to exclude, shared across every pass. Defaults to node_modules/dist/.git. */
|
|
13
|
+
exclude?: string[] | undefined;
|
|
14
|
+
/** See `GenerateEnvManifestOptions.packages`. See ADR 0014. */
|
|
15
|
+
packages?: readonly string[] | undefined;
|
|
16
|
+
/** See `GenerateEnvManifestOptions.tsconfig`. See ADR 0023. */
|
|
17
|
+
tsconfig?: string | false | undefined;
|
|
18
|
+
/**
|
|
19
|
+
* Where a previously-persisted evidence artifact lives, relative to
|
|
20
|
+
* `root` -- read (never written) as the baseline Change Model diffs
|
|
21
|
+
* against and dynamic-access citation freshness (ADR 0037) compares
|
|
22
|
+
* content hashes to. Independent of any `.ts` manifest a project may or
|
|
23
|
+
* may not also generate -- there is no derivation from a manifest's own
|
|
24
|
+
* location. Omitted: treated as the normal first-run state (everything
|
|
25
|
+
* reads as added, no citation-freshness baseline to compare against),
|
|
26
|
+
* never an error.
|
|
27
|
+
*/
|
|
28
|
+
previousSnapshotLocation?: string | undefined;
|
|
29
|
+
/** Feeds Lifecycle Model's `expiring` list. Defaults to 30. */
|
|
30
|
+
expiringWithinDays?: number | undefined;
|
|
31
|
+
/**
|
|
32
|
+
* Supplies expiration metadata from a live source as a post-discovery
|
|
33
|
+
* override, applied to Lifecycle Model's (and Finding Model's
|
|
34
|
+
* `expiring-soon` findings') data only -- Contract Model still reflects the
|
|
35
|
+
* schema's own static `expiresAt`. See `live-expirations.ts` and ADR 0012.
|
|
36
|
+
*/
|
|
37
|
+
liveExpirationDates?: LiveExpirationDates | undefined;
|
|
38
|
+
/**
|
|
39
|
+
* Resolves the commit SHA to stamp onto `EvidenceModel.provenance.commit`.
|
|
40
|
+
* Invoked at most once, after discovery/linking completes. env-cap never
|
|
41
|
+
* shells out to `git` itself -- see ADR 0012's callback precedent. Omitted:
|
|
42
|
+
* `commit` is `undefined`.
|
|
43
|
+
*/
|
|
44
|
+
commit?: (() => Promise<string | undefined>) | undefined;
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* Node-only assembly orchestrator (ADR 0024, ADR 0031): runs schema
|
|
48
|
+
* discovery and linking once (via `assembleProject()`, shared with
|
|
49
|
+
* `computeArtifacts()`), then builds all seven canonical fact models by
|
|
50
|
+
* calling each model's own public builder directly -- this function
|
|
51
|
+
* introduces no derivation logic of its own, only sequencing and the shared
|
|
52
|
+
* discovery/linking every builder needs. The result is `deepFreeze()`-d
|
|
53
|
+
* before being returned.
|
|
54
|
+
*
|
|
55
|
+
* @remarks
|
|
56
|
+
* Deliberately never throws on a data-quality finding (a compatibility
|
|
57
|
+
* issue, an undocumented variable, an abandoned contract, ...) -- every one
|
|
58
|
+
* of those becomes a `Finding` in the returned model's `finding` field
|
|
59
|
+
* instead. This is a real difference from `generateEnvManifest()`, which
|
|
60
|
+
* throws by default: that's a "should I write this artifact" gate, while
|
|
61
|
+
* Evidence Model assembly is a read-only snapshot whose entire purpose is
|
|
62
|
+
* representing such issues as data for a consumer's own projection to act
|
|
63
|
+
* on (see ADR 0024's mission statement). It still throws
|
|
64
|
+
* `EnvProjectGenerationError` for a genuine configuration error --
|
|
65
|
+
* `previousSnapshotLocation` escaping `root`.
|
|
66
|
+
*
|
|
67
|
+
* The dependency-graph scan underlying Dependency Model (via
|
|
68
|
+
* `buildDependencyModel()`) and the one underlying Finding Model's
|
|
69
|
+
* ownership-related findings (via `computeUsage()`) each run their own,
|
|
70
|
+
* independent pass over the repository -- a real, accepted cost of calling
|
|
71
|
+
* each half's already-tested public building block directly rather than
|
|
72
|
+
* hand-deriving a second copy of either's logic here. Both are Node-only,
|
|
73
|
+
* dev/CI-time-only work (never a runtime hot path), so the redundant I/O is
|
|
74
|
+
* an honest tradeoff, not an oversight.
|
|
75
|
+
*/
|
|
76
|
+
export declare function generateEvidenceModel(options: GenerateEvidenceModelOptions): Promise<EvidenceModel>;
|
|
77
|
+
//# sourceMappingURL=generate-evidence.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"generate-evidence.d.ts","sourceRoot":"","sources":["../../../src/build/generate-evidence.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAYxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAEhE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,iDAAiD;AACjD,MAAM,WAAW,4BAA4B;IAC3C,iFAAiF;IACjF,EAAE,EAAE,eAAe,CAAA;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,yFAAyF;IACzF,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;IACrC;;;;;;;;;OASG;IACH,wBAAwB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7C,+DAA+D;IAC/D,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAA;IACrD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,CAAA;CACzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,aAAa,CAAC,CAyHxB"}
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
import type { BuildFileSystem } from "./types.js";
|
|
2
|
+
import type { CompatibilityIssue } from "./compatibility.js";
|
|
3
|
+
import { type DiscoveredContract, type DiscoveredContractSummary, type LinkResult } from "./link.js";
|
|
4
|
+
import type { ParseWarning } from "./parse.js";
|
|
5
|
+
/** Options for {@link generateEnvManifest}. */
|
|
6
|
+
export interface GenerateEnvManifestOptions {
|
|
7
|
+
/** The filesystem capability -- `./build` never imports `node:fs` (ADR 0040). */
|
|
8
|
+
fs: BuildFileSystem;
|
|
9
|
+
/** Directory glob patterns are resolved against. Defaults to `process.cwd()`. */
|
|
10
|
+
root?: string | undefined;
|
|
11
|
+
/** Output path for the generated manifest, relative to `root` (e.g. "src/generated/env.manifest.ts"). */
|
|
12
|
+
location: string;
|
|
13
|
+
/** Glob patterns for schema files. Defaults to `["**\/env.schema.ts"]`. */
|
|
14
|
+
include?: string[] | undefined;
|
|
15
|
+
/** Glob patterns to exclude. Defaults to node_modules/dist/.git. */
|
|
16
|
+
exclude?: string[] | undefined;
|
|
17
|
+
/**
|
|
18
|
+
* Explicit allowlist of installed
|
|
19
|
+
* package names whose declared `"envCap": { "schema": "<path>" }` entry
|
|
20
|
+
* point should also be discovered, so a contract that ships as its own
|
|
21
|
+
* separately-published package (no monorepo required) can be included in
|
|
22
|
+
* the manifest. Opt-in only: a package is never considered unless its
|
|
23
|
+
* exact name appears here. See ADR 0014.
|
|
24
|
+
*/
|
|
25
|
+
packages?: readonly string[] | undefined;
|
|
26
|
+
/**
|
|
27
|
+
* Path to a tsconfig.json (relative to `root`)
|
|
28
|
+
* whose `compilerOptions.paths`/`baseUrl` resolve aliased import specifiers (e.g.
|
|
29
|
+
* `"@/lib/env.schema.js"`) encountered during static analysis, so a contract or consumer
|
|
30
|
+
* reached only through an alias isn't misreported as abandoned/unresolved. Defaults to
|
|
31
|
+
* `"tsconfig.json"` at `root` -- on automatically, no opt-in required, since (unlike
|
|
32
|
+
* `packages`) this never crosses a trust/versioning boundary: every resolved file is
|
|
33
|
+
* already local, already-trusted project source. Pass `false` to disable entirely. See
|
|
34
|
+
* ADR 0023.
|
|
35
|
+
*/
|
|
36
|
+
tsconfig?: string | false | undefined;
|
|
37
|
+
/**
|
|
38
|
+
* "warn" (default): only provable incompatibilities (conflicting explicit processor
|
|
39
|
+
* return type annotations) block generation; everything else is reported as a warning.
|
|
40
|
+
* "throw": warnings are escalated to hard errors too, for stricter CI gates.
|
|
41
|
+
*/
|
|
42
|
+
onIncompatibility?: "warn" | "throw" | undefined;
|
|
43
|
+
}
|
|
44
|
+
/** The result of a completed {@link generateEnvManifest} run. */
|
|
45
|
+
export interface GenerateEnvManifestResult {
|
|
46
|
+
/** Absolute path the manifest file was written to. */
|
|
47
|
+
readonly outputPath: string;
|
|
48
|
+
/** Root-relative summary of every discovered contract, active or not. */
|
|
49
|
+
readonly contracts: readonly DiscoveredContractSummary[];
|
|
50
|
+
/** Non-blocking compatibility/exclusive-group issues (severity `"warning"`). */
|
|
51
|
+
readonly warnings: readonly CompatibilityIssue[];
|
|
52
|
+
/** Parse-time warnings collected across every analyzed file (including allow-listed package resolution). */
|
|
53
|
+
readonly parseWarnings: readonly ParseWarning[];
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Default value for {@link GenerateEnvManifestOptions.include}. A function
|
|
57
|
+
* (not a bare module-level `const`) so every call gets its own fresh array
|
|
58
|
+
* -- a shared literal used from many files (`evidence-cache.ts`,
|
|
59
|
+
* `generate-documentation.ts`, `generate-evidence.ts`,
|
|
60
|
+
* `generate-env-artifacts.ts`, `generate-usage.ts`) is a covered-static
|
|
61
|
+
* mutant magnet under Stryker's `coverageAnalysis: perTest` +
|
|
62
|
+
* `ignoreStatic: true` (a mutant on module-load code that's still referenced
|
|
63
|
+
* by a test is run anyway and falsely reported "Survived") -- see this
|
|
64
|
+
* drive's memory for the fully-documented limitation.
|
|
65
|
+
*/
|
|
66
|
+
export declare function defaultInclude(): string[];
|
|
67
|
+
/** Default value for {@link GenerateEnvManifestOptions.exclude}. Same reasoning as {@link defaultInclude}. */
|
|
68
|
+
export declare function defaultExclude(): string[];
|
|
69
|
+
export interface ManifestComputation {
|
|
70
|
+
readonly activeContracts: readonly DiscoveredContract[];
|
|
71
|
+
readonly contractSummaries: readonly DiscoveredContractSummary[];
|
|
72
|
+
readonly warnings: readonly CompatibilityIssue[];
|
|
73
|
+
readonly blocking: readonly CompatibilityIssue[];
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Pure -- no I/O. Runs compatibility (0005) and exclusive-group (0009,
|
|
77
|
+
* always-error, never gated by `onIncompatibility`) checks against an
|
|
78
|
+
* already-discovered contract graph and applies the `onIncompatibility` gate.
|
|
79
|
+
* Shared by the standalone `generateEnvManifest()` (which discovers its own
|
|
80
|
+
* graph) and `generate-env-artifacts.ts` (which discovers once and reuses it across
|
|
81
|
+
* manifest/docs/usage) -- see ADR 0011.
|
|
82
|
+
*/
|
|
83
|
+
export declare function computeManifest(root: string, linkResult: LinkResult, onIncompatibility: "warn" | "throw" | undefined): ManifestComputation;
|
|
84
|
+
/** Writes the manifest file. Callers must have already confirmed `outputPath` is safe and nothing is blocking. */
|
|
85
|
+
export declare function writeManifest(outputPath: string, activeContracts: readonly DiscoveredContract[], fs: BuildFileSystem): Promise<void>;
|
|
86
|
+
/**
|
|
87
|
+
* Build-time only. Discovers `env.schema.ts` files, statically analyzes them
|
|
88
|
+
* (never executes them) to link `createEnv()`/`documentEnv()` calls, checks
|
|
89
|
+
* for provable incompatibilities between duplicate variable declarations,
|
|
90
|
+
* and writes a deterministic manifest file that re-exports every discovered
|
|
91
|
+
* active contract.
|
|
92
|
+
*
|
|
93
|
+
* @remarks
|
|
94
|
+
* Never call this at application startup or import it from
|
|
95
|
+
* runtime code -- wire it into an npm script, a bundler plugin, or a CI
|
|
96
|
+
* step instead.
|
|
97
|
+
*
|
|
98
|
+
* @throws {EnvManifestGenerationError} If `location` escapes `root`, or if a blocking compatibility/exclusive-group issue is found.
|
|
99
|
+
*/
|
|
100
|
+
export declare function generateEnvManifest(options: GenerateEnvManifestOptions): Promise<GenerateEnvManifestResult>;
|
|
101
|
+
//# sourceMappingURL=generate-manifest.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"generate-manifest.d.ts","sourceRoot":"","sources":["../../../src/build/generate-manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAG5D,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,UAAU,EAChB,MAAM,WAAW,CAAA;AAElB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAG9C,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC,iFAAiF;IACjF,EAAE,EAAE,eAAe,CAAA;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,yGAAyG;IACzG,QAAQ,EAAE,MAAM,CAAA;IAChB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;IACrC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAA;CACjD;AAED,iEAAiE;AACjE,MAAM,WAAW,yBAAyB;IACxC,sDAAsD;IACtD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,SAAS,yBAAyB,EAAE,CAAA;IACxD,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAChD,4GAA4G;IAC5G,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAA;CAChD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC;AACD,8GAA8G;AAC9G,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAczC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,eAAe,EAAE,SAAS,kBAAkB,EAAE,CAAA;IACvD,QAAQ,CAAC,iBAAiB,EAAE,SAAS,yBAAyB,EAAE,CAAA;IAChE,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAChD,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAA;CACjD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,EACtB,iBAAiB,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAC9C,mBAAmB,CAwBrB;AAED,kHAAkH;AAClH,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,SAAS,kBAAkB,EAAE,EAC9C,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,yBAAyB,CAAC,CAoCpC"}
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
import type { BuildFileSystem } from "./types.js";
|
|
2
|
+
import type { DependencyGraph, ScannedSurface } from "./dependency-graph.js";
|
|
3
|
+
import type { DiscoveredContract } from "./link.js";
|
|
4
|
+
import type { ImportResolutionContext } from "./resolution/resolve-import.js";
|
|
5
|
+
import type { PackageOrigin } from "./resolution/resolve-package-schema.js";
|
|
6
|
+
import type { DynamicAccessAssertion } from "./source-position.js";
|
|
7
|
+
import { type RenderUsageReportOptions } from "./usage-report.js";
|
|
8
|
+
/**
|
|
9
|
+
* Computes the full usage-scan surface: the local project root, plus (ADR
|
|
10
|
+
* 0036) each allow-listed `packages` (ADR 0014) name whose schema was
|
|
11
|
+
* successfully resolved -- reusing `origins`' already-resolved
|
|
12
|
+
* `packageDir` (from `resolveAllowlistedPackages()`, already computed by
|
|
13
|
+
* the caller for contract discovery, not re-resolved here) as a bounded
|
|
14
|
+
* scan root, walked with the exact same `discoverFiles()` +
|
|
15
|
+
* `SCAN_INCLUDE`/`defaultExclude()` policy the local root already uses --
|
|
16
|
+
* never a naive, unbounded walk of the package's whole directory. Shared by
|
|
17
|
+
* `generateUsageReport()` and `generateEvidenceModel()` so both agree on
|
|
18
|
+
* exactly the same scanned surface.
|
|
19
|
+
*/
|
|
20
|
+
export declare function computeScanSurface(root: string, exclude: readonly string[], origins: ReadonlyMap<string, PackageOrigin>, fs: BuildFileSystem): Promise<{
|
|
21
|
+
scanFiles: string[];
|
|
22
|
+
scannedSurfaces: ScannedSurface[];
|
|
23
|
+
}>;
|
|
24
|
+
/** Options for {@link generateUsageReport}. */
|
|
25
|
+
export interface GenerateUsageReportOptions {
|
|
26
|
+
/** The filesystem capability -- `./build` never imports `node:fs` (ADR 0040). */
|
|
27
|
+
fs: BuildFileSystem;
|
|
28
|
+
/** Directory glob patterns are resolved against. Defaults to `process.cwd()`. */
|
|
29
|
+
root?: string | undefined;
|
|
30
|
+
/** Schema-discovery glob, for the contract graph -- self-sufficient like the other two generator functions. */
|
|
31
|
+
include?: string[] | undefined;
|
|
32
|
+
/** Glob patterns to exclude, for both schema discovery and the usage scan. Defaults to node_modules/dist/.git. */
|
|
33
|
+
exclude?: string[] | undefined;
|
|
34
|
+
/** See `GenerateEnvManifestOptions.packages`; see ADR 0014. */
|
|
35
|
+
packages?: readonly string[] | undefined;
|
|
36
|
+
/** See `GenerateEnvManifestOptions.tsconfig`; see ADR 0023. */
|
|
37
|
+
tsconfig?: string | false | undefined;
|
|
38
|
+
/** Also write the rendered Markdown report to this path, relative to `root`. Omitted: the report is only returned, not written. */
|
|
39
|
+
report?: {
|
|
40
|
+
/** Output path for the report, relative to `root`. */
|
|
41
|
+
location: string;
|
|
42
|
+
} | undefined;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Public result of {@link generateUsageReport}.
|
|
46
|
+
*
|
|
47
|
+
* @remarks
|
|
48
|
+
* Composed from the building-block types `usage-report.ts` (the renderer) owns, the same way
|
|
49
|
+
* `GenerateDocumentationResult` composes from `docs.ts`'s `CatalogContract` --
|
|
50
|
+
* keeps the renderer importable without its orchestrator (see
|
|
51
|
+
* `RenderUsageReportOptions`'s own doc comment).
|
|
52
|
+
*/
|
|
53
|
+
export interface GenerateUsageReportResult extends RenderUsageReportOptions {
|
|
54
|
+
/** Absolute path the report was written to, or `undefined` if `options.report` wasn't passed. */
|
|
55
|
+
readonly reportPath: string | undefined;
|
|
56
|
+
}
|
|
57
|
+
export interface UsageComputation {
|
|
58
|
+
readonly graph: DependencyGraph;
|
|
59
|
+
/** Everything the report renders except `parseWarnings`, which the caller owns (it comes from discovery, not from this analysis). */
|
|
60
|
+
readonly result: Omit<RenderUsageReportOptions, "parseWarnings">;
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* Builds the dependency graph and maps it into the public, ownership-framed
|
|
64
|
+
* result. Never blocks -- see `RenderUsageReportOptions`'s finding fields'
|
|
65
|
+
* own doc comments; a team that wants to gate CI on an ownership issue reads
|
|
66
|
+
* `Finding[]` (the "ownership" family) from the persisted evidence artifact
|
|
67
|
+
* and decides for itself. See ADR 0038.
|
|
68
|
+
*
|
|
69
|
+
* @remarks
|
|
70
|
+
* This mapping is the actual API boundary: internal AST vocabulary
|
|
71
|
+
* ("member accessed", "dynamic") becomes ownership vocabulary ("who owns
|
|
72
|
+
* it", "who consumes it", "abandoned", "unresolved"). The result is a
|
|
73
|
+
* renderer-agnostic domain model -- the same computed data a future JSON or
|
|
74
|
+
* SARIF exporter would consume, not something coupled to the Markdown
|
|
75
|
+
* renderer.
|
|
76
|
+
*/
|
|
77
|
+
export declare function computeUsage(root: string, contracts: readonly DiscoveredContract[], scanFiles: readonly string[], readFile: (filePath: string) => Promise<string>, context: ImportResolutionContext, scannedSurfaces?: readonly ScannedSurface[], dynamicAccessAcknowledgments?: ReadonlyMap<string, readonly DynamicAccessAssertion[]>): Promise<UsageComputation>;
|
|
78
|
+
/** Writes the Dependency & Ownership Report. Callers must have already confirmed `reportPath` is safe and nothing is blocking. */
|
|
79
|
+
export declare function writeUsageReport(reportPath: string, computed: Omit<GenerateUsageReportResult, "reportPath">, fs: BuildFileSystem): Promise<void>;
|
|
80
|
+
/**
|
|
81
|
+
* Build-time only. Answers who owns each contract, which features depend on
|
|
82
|
+
* it, and what the blast radius is if it changes -- the mirror image of
|
|
83
|
+
* {@link generateEnvManifest}'s "safer migrations" story: a schema that was never
|
|
84
|
+
* wired up, or was abandoned mid-removal, shows up here instead of sitting
|
|
85
|
+
* unnoticed.
|
|
86
|
+
*
|
|
87
|
+
* @remarks
|
|
88
|
+
* This is an additional, separate artifact, not a replacement for
|
|
89
|
+
* {@link generateDocumentation}'s Catalog -- the two serve different audiences
|
|
90
|
+
* (see ADR 0010).
|
|
91
|
+
*
|
|
92
|
+
* @throws {EnvUsageAnalysisError} If `report.location` escapes `root`.
|
|
93
|
+
*/
|
|
94
|
+
export declare function generateUsageReport(options: GenerateUsageReportOptions): Promise<GenerateUsageReportResult>;
|
|
95
|
+
//# sourceMappingURL=generate-usage.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"generate-usage.d.ts","sourceRoot":"","sources":["../../../src/build/generate-usage.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAS5E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAA;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAA;AAE3E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAClE,OAAO,EAML,KAAK,wBAAwB,EAG9B,MAAM,mBAAmB,CAAA;AAE1B;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,EAC3C,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IAAC,eAAe,EAAE,cAAc,EAAE,CAAA;CAAE,CAAC,CAmCrE;AAED,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC,iFAAiF;IACjF,EAAE,EAAE,eAAe,CAAA;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,+GAA+G;IAC/G,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,kHAAkH;IAClH,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IACxC,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;IACrC,mIAAmI;IACnI,MAAM,CAAC,EACH;QACE,sDAAsD;QACtD,QAAQ,EAAE,MAAM,CAAA;KACjB,GACD,SAAS,CAAA;CACd;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,yBAA0B,SAAQ,wBAAwB;IACzE,iGAAiG;IACjG,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CACxC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;IAC/B,qIAAqI;IACrI,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,wBAAwB,EAAE,eAAe,CAAC,CAAA;CACjE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,EAC/C,OAAO,EAAE,uBAAuB,EAChC,eAAe,CAAC,EAAE,SAAS,cAAc,EAAE,EAC3C,4BAA4B,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC,GACpF,OAAO,CAAC,gBAAgB,CAAC,CAsI3B;AAED,kIAAkI;AAClI,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,IAAI,CAAC,yBAAyB,EAAE,YAAY,CAAC,EACvD,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,yBAAyB,CAAC,CAkDpC"}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Regeneration instruction for a report the CLI does not write (ADR 0046) -- it is produced by the project's own
|
|
3
|
+
* script calling the `@maverickcer/env-cap/build` generators, so naming `npx env-cap` there would send a reader to a command that
|
|
4
|
+
* cannot regenerate it.
|
|
5
|
+
* @returns The instruction, as a sentence.
|
|
6
|
+
*/
|
|
7
|
+
export declare function reportRegenerateHint(): string;
|
|
8
|
+
/**
|
|
9
|
+
* Renders the "do not edit by hand" marker in the given comment syntax.
|
|
10
|
+
* @param format - Comment syntax to render in.
|
|
11
|
+
* @param regenerate - How to regenerate; defaults to the CLI, which writes the manifest.
|
|
12
|
+
* @returns The comment line.
|
|
13
|
+
*/
|
|
14
|
+
export declare function generatedBanner(format?: "ts" | "markdown", regenerate?: string): string;
|
|
15
|
+
/**
|
|
16
|
+
* Whether `content` carries a {@link generatedBanner}-produced marker, in either format.
|
|
17
|
+
*
|
|
18
|
+
* @remarks
|
|
19
|
+
* Deliberately not a bare `content.startsWith(generatedBanner(...))`: a shebang, a `"use strict"` pragma, or a
|
|
20
|
+
* license header pushes a real banner off line one, and a stricter check would then read a genuinely
|
|
21
|
+
* generated file as hand-written, which the dependency scan would take as "a real consumer imports this" and
|
|
22
|
+
* so permanently mask an abandoned one. The marker is looked for across the first 20 non-empty lines instead,
|
|
23
|
+
* which clears every realistic preamble without scanning a whole file.
|
|
24
|
+
* @param content - A file's text.
|
|
25
|
+
* @returns `true` when the file is generated.
|
|
26
|
+
*/
|
|
27
|
+
export declare function isGeneratedFile(content: string): boolean;
|
|
28
|
+
/**
|
|
29
|
+
* Short disclaimer stamped into every artifact that renders sensitivity, ownership or expiry claims. Never omit
|
|
30
|
+
* it from an artifact that renders such metadata: it is what keeps "documented" from being misread as
|
|
31
|
+
* "verified" or "compliant". Every fact in those artifacts is either a statically-provable code fact or an
|
|
32
|
+
* author's own declaration; env-cap never validates a declaration against reality.
|
|
33
|
+
* @returns The disclaimer.
|
|
34
|
+
*/
|
|
35
|
+
export declare function evidenceDisclaimer(): string;
|
|
36
|
+
/**
|
|
37
|
+
* States, by concept, that an artifact is a projection of env-cap's Evidence Model, and by path when one is known.
|
|
38
|
+
* It never hardcodes a path, because the evidence file only exists on a run that passed `--evidence`.
|
|
39
|
+
* @param evidencePath - The path the evidence was also written to, when this run wrote it.
|
|
40
|
+
* @returns The note.
|
|
41
|
+
*/
|
|
42
|
+
export declare function evidenceProjectionNote(evidencePath?: string): string;
|
|
43
|
+
//# sourceMappingURL=generated-banner.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"generated-banner.d.ts","sourceRoot":"","sources":["../../../src/build/generated-banner.ts"],"names":[],"mappings":"AAwBA;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,IAAI,GAAG,UAAU,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpE"}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Glob-to-RegExp conversion for discovery. The behavior lives in `../_ipc/glob.ts`, a managed copy of
|
|
3
|
+
* internal-package-contract's `runtime/glob.ts`. Not re-exported from `./index.js`: Private tier per `VERSIONING.md`.
|
|
4
|
+
*/
|
|
5
|
+
export { globToRegExp } from "../_ipc/glob.js";
|
|
6
|
+
//# sourceMappingURL=glob.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../../src/build/glob.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA"}
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The declared governance-metadata field set every pipeline-stage contract and
|
|
3
|
+
* variable type carries -- `owner` through `metadata`. The field names and types
|
|
4
|
+
* are identical at every stage (parse -> link -> contract-model -> docs); only
|
|
5
|
+
* the surrounding context differs (a `parse`-stage value is "statically resolved
|
|
6
|
+
* from a string literal, or `undefined`"; a `link`/`contract-model`-stage value
|
|
7
|
+
* is "from the linked `documentEnv()` call, or `undefined`"). This is the single
|
|
8
|
+
* source of truth for the shape; each stage interface `extends` it.
|
|
9
|
+
*
|
|
10
|
+
* `metadata` is the open bag for keys `env-cap` has no named concept for (ADR
|
|
11
|
+
* 0037); `dataResidency`/`auditRequired`/`legalBasis`/`purpose`/`retention` are
|
|
12
|
+
* presence-only governance facts, never verified.
|
|
13
|
+
*
|
|
14
|
+
* Internal -- not re-exported from the public `.` barrel.
|
|
15
|
+
*/
|
|
16
|
+
export interface EnvGovernanceFields {
|
|
17
|
+
readonly owner: string | undefined;
|
|
18
|
+
readonly sensitivity: string | undefined;
|
|
19
|
+
readonly expiresAt: string | undefined;
|
|
20
|
+
readonly purpose: string | undefined;
|
|
21
|
+
readonly legalBasis: string | undefined;
|
|
22
|
+
readonly retention: string | undefined;
|
|
23
|
+
readonly dataResidency: string | readonly string[] | undefined;
|
|
24
|
+
readonly auditRequired: boolean | undefined;
|
|
25
|
+
readonly metadata: Readonly<Record<string, unknown>> | undefined;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Copies exactly the `EnvGovernanceFields` out of a value that carries
|
|
29
|
+
* them -- for projecting one pipeline stage's contract/variable into the next
|
|
30
|
+
* (`link` -> `contract-model` -> `docs` catalog, ...) without re-listing all
|
|
31
|
+
* nine fields at every hop.
|
|
32
|
+
*/
|
|
33
|
+
export declare function governanceFieldsOf(source: EnvGovernanceFields): EnvGovernanceFields;
|
|
34
|
+
//# sourceMappingURL=governance-fields.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"governance-fields.d.ts","sourceRoot":"","sources":["../../../src/build/governance-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IAC9D,QAAQ,CAAC,aAAa,EAAE,OAAO,GAAG,SAAS,CAAA;IAC3C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAA;CACjE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,mBAAmB,GAAG,mBAAmB,CAYnF"}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Formats a metadata key for display in generated docs/examples:
|
|
3
|
+
* "lastRotation" -> "Last Rotation". Shared by `docs.ts` and `env-example.ts`
|
|
4
|
+
* so both generated artifacts label metadata the same way.
|
|
5
|
+
*/
|
|
6
|
+
export declare function humanizeKey(key: string): string;
|
|
7
|
+
/**
|
|
8
|
+
* Formats a `metadata`/`dataResidency` value for display in generated docs/examples -- a string
|
|
9
|
+
* renders as-is; anything else (ADR 0035 widened `metadata` to any value) renders as its JSON
|
|
10
|
+
* text, so an object/array value never prints `[object Object]`. Shared by `docs.ts` and
|
|
11
|
+
* `env-example.ts`, same rationale as {@link humanizeKey}.
|
|
12
|
+
*/
|
|
13
|
+
export declare function renderMetadataValue(value: unknown): string;
|
|
14
|
+
//# sourceMappingURL=humanize-key.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"humanize-key.d.ts","sourceRoot":"","sources":["../../../src/build/humanize-key.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQ/C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE1D"}
|