@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,41 @@
|
|
|
1
|
+
import type { BuildFileSystem } from "./types.js";
|
|
2
|
+
/** Options for {@link discoverSchemaFiles}. */
|
|
3
|
+
export interface DiscoverOptions {
|
|
4
|
+
/** The filesystem capability -- `./build` never imports `node:fs` (ADR 0040). */
|
|
5
|
+
readonly fs: BuildFileSystem;
|
|
6
|
+
/** Absolute path to search under. */
|
|
7
|
+
readonly root: string;
|
|
8
|
+
/** Glob patterns (relative to `root`) a file must match at least one of to be included. */
|
|
9
|
+
readonly include: readonly string[];
|
|
10
|
+
/** Glob patterns (relative to `root`) that prune a file or directory regardless of `include`. */
|
|
11
|
+
readonly exclude: readonly string[];
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Finds every file matching `include`/`exclude` under `root`, returned as
|
|
15
|
+
* absolute paths in deterministic (alphabetically sorted) order. No count
|
|
16
|
+
* limit -- the usage scan walks every TypeScript source file, which a large
|
|
17
|
+
* project legitimately has thousands of; {@link discoverSchemaFiles} adds the
|
|
18
|
+
* schema-specific sanity limit on top.
|
|
19
|
+
*
|
|
20
|
+
* @remarks
|
|
21
|
+
* No external glob dependency: directories are pruned *during* the walk
|
|
22
|
+
* (both a hardcoded node_modules/.git skip and the caller's `exclude`
|
|
23
|
+
* patterns), rather than walked in full and filtered afterward -- walking an
|
|
24
|
+
* entire node_modules tree just to discard it is not acceptable for a tool
|
|
25
|
+
* meant to run against real projects.
|
|
26
|
+
*/
|
|
27
|
+
export declare function discoverFiles(options: DiscoverOptions): Promise<string[]>;
|
|
28
|
+
/**
|
|
29
|
+
* Finds every schema file matching `include`/`exclude` under `root`, returned
|
|
30
|
+
* as absolute paths in deterministic (alphabetically sorted) order -- the
|
|
31
|
+
* same walk as `discoverFiles`, plus a sanity limit on the count.
|
|
32
|
+
*
|
|
33
|
+
* @remarks
|
|
34
|
+
* No external glob dependency: directories are pruned *during* the walk
|
|
35
|
+
* (both a hardcoded node_modules/.git skip and the caller's `exclude`
|
|
36
|
+
* patterns), rather than walked in full and filtered afterward -- walking an
|
|
37
|
+
* entire node_modules tree just to discard it is not acceptable for a tool
|
|
38
|
+
* meant to run against real projects.
|
|
39
|
+
*/
|
|
40
|
+
export declare function discoverSchemaFiles(options: DiscoverOptions): Promise<string[]>;
|
|
41
|
+
//# sourceMappingURL=discover.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../../src/build/discover.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAA;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,iGAAiG;IACjG,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC;AAkBD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAa/E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAuBrF"}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Root-relative paths for published artifacts, bound to env-cap. The behavior lives in
|
|
3
|
+
* `../_ipc/display-path.ts`, a managed copy of internal-package-contract's `runtime/display-path.ts`.
|
|
4
|
+
*/
|
|
5
|
+
export { displayPath } from "../_ipc/display-path.js";
|
|
6
|
+
//# sourceMappingURL=display-path.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"display-path.d.ts","sourceRoot":"","sources":["../../../src/build/display-path.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA"}
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
import type { ContractModelContract } from "./contract-model.js";
|
|
2
|
+
import { type EnvGovernanceFields } from "./governance-fields.js";
|
|
3
|
+
import type { DiscoveredVariableEvidence } from "./parse.js";
|
|
4
|
+
/** Identifies a contract with no linked `documentEnv()` call at all. `file`'s absolute-vs-relative convention depends on where a given instance comes from -- see the specific field using this type (`DocumentationFindings.undocumentedContracts` is absolute; `RenderDocsOptions.undocumentedContracts` must be root-relative, matching the `ContractModel`-shaped `contracts` it's compared against). */
|
|
5
|
+
export interface UndocumentedContractRef {
|
|
6
|
+
readonly file: string;
|
|
7
|
+
/** The contract's exported binding name. */
|
|
8
|
+
readonly exportName: string;
|
|
9
|
+
}
|
|
10
|
+
/** Identifies a schema variable with no matching entry in its contract's linked documentation. See {@link UndocumentedContractRef}'s own note on `file`. */
|
|
11
|
+
export interface UndocumentedVariableRef {
|
|
12
|
+
readonly file: string;
|
|
13
|
+
/** The contract's exported binding name. */
|
|
14
|
+
readonly exportName: string;
|
|
15
|
+
/** The undocumented environment variable name. */
|
|
16
|
+
readonly key: string;
|
|
17
|
+
}
|
|
18
|
+
/** One contract- or variable-level `expiresAt` falling within the configured "expiring soon" window. */
|
|
19
|
+
export interface ExpiringEntry {
|
|
20
|
+
/** Absolute path of the file declaring the contract. */
|
|
21
|
+
readonly file: string;
|
|
22
|
+
/** The contract's exported binding name. */
|
|
23
|
+
readonly exportName: string;
|
|
24
|
+
/** `undefined` for a contract-level `expiresAt`, set for a per-variable one. */
|
|
25
|
+
readonly key: string | undefined;
|
|
26
|
+
/** The raw ISO date string, unparsed. */
|
|
27
|
+
readonly expiresAt: string;
|
|
28
|
+
/** Days from `now` until expiry; negative when already expired. */
|
|
29
|
+
readonly daysRemaining: number;
|
|
30
|
+
}
|
|
31
|
+
/** Options for {@link renderDocs}. */
|
|
32
|
+
export interface RenderDocsOptions {
|
|
33
|
+
/** How many days out counts as "expiring soon" in the lifecycle report and security review. */
|
|
34
|
+
readonly expiringWithinDays: number;
|
|
35
|
+
/** Contracts with no linked `documentEnv()` call at all. `file` must be root-relative, POSIX-separated -- matching `contracts`' own `ContractModel` convention, since this is matched against it by identity. */
|
|
36
|
+
readonly undocumentedContracts: readonly UndocumentedContractRef[];
|
|
37
|
+
/** Schema variables with no matching entry in their contract's linked documentation. Only how many there are is rendered (the security-review counter), so `file` is not matched against anything. */
|
|
38
|
+
readonly undocumentedVariables: readonly UndocumentedVariableRef[];
|
|
39
|
+
/** Timestamp rendered into the header and used for expiry/days-remaining math. */
|
|
40
|
+
readonly generatedAt: Date;
|
|
41
|
+
/** Content already at `docs.location`, if any -- used only for the "changes since last report" summary. */
|
|
42
|
+
readonly previousContent: string | undefined;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Parses `expiresAt` as a real date.
|
|
46
|
+
*
|
|
47
|
+
* @remarks
|
|
48
|
+
* Malformed strings are silently ignored (return `undefined`) rather than throwing -- same
|
|
49
|
+
* "warn/skip, never guess" policy as the rest of the generator. Exported so `live-expirations.ts`
|
|
50
|
+
* can validate live override values against the exact same rule used for static `expiresAt`.
|
|
51
|
+
*/
|
|
52
|
+
export declare function parseIsoDate(value: string): Date | undefined;
|
|
53
|
+
/** The minimal shape {@link computeExpiringEntries} needs -- structural, not pinned to `DiscoveredContract`, so the exact same rule serves both `LinkResult`'s absolute-path contracts (`generate-documentation.ts`'s `documentation.expiringSoon`, Stable tier) and `ContractModel`'s root-relative ones, whichever a caller already has on hand. */
|
|
54
|
+
interface ExpiryBearingContract {
|
|
55
|
+
readonly file: string;
|
|
56
|
+
readonly exportName: string;
|
|
57
|
+
readonly expiresAt: string | undefined;
|
|
58
|
+
readonly variables: readonly {
|
|
59
|
+
readonly key: string;
|
|
60
|
+
readonly expiresAt: string | undefined;
|
|
61
|
+
}[];
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* Computes every contract- or variable-level `expiresAt` within `expiringWithinDays` of `now`, sorted soonest-first.
|
|
65
|
+
*/
|
|
66
|
+
export declare function computeExpiringEntries(contracts: readonly ExpiryBearingContract[], expiringWithinDays: number, now: Date): ExpiringEntry[];
|
|
67
|
+
/**
|
|
68
|
+
* Same data `renderCatalog()` renders to Markdown for one variable, reshaped for JSON/
|
|
69
|
+
* programmatic consumers instead of prose.
|
|
70
|
+
*
|
|
71
|
+
* @see `ContractModelVariable` (`contract-model.ts`) -- this same declared variable's canonical
|
|
72
|
+
* starting point. Plain reference, not `{@link}`: this type is intentionally not part of the
|
|
73
|
+
* public surface (see `typedoc.json`'s `intentionallyNotExported`).
|
|
74
|
+
*/
|
|
75
|
+
interface CatalogVariable extends EnvGovernanceFields {
|
|
76
|
+
readonly description: string | undefined;
|
|
77
|
+
readonly refreshInstructions: string | undefined;
|
|
78
|
+
readonly setupInstructions: string | undefined;
|
|
79
|
+
readonly required: boolean | undefined;
|
|
80
|
+
readonly hasDefault: boolean;
|
|
81
|
+
readonly hasProcessor: boolean;
|
|
82
|
+
readonly processorReturnType: string | undefined;
|
|
83
|
+
readonly hasValidator: boolean;
|
|
84
|
+
readonly documented: boolean;
|
|
85
|
+
/** The variable's declared validation context, if any -- see ADR 0022. Participation data, not documentation: describes when `validateEnv()` processes this variable, not who may access it or what a bundler includes. */
|
|
86
|
+
readonly context: string | undefined;
|
|
87
|
+
/** The `evidence` sub-object from this variable's linked documentation -- re-verified every run, unlike every declared-only field above. See ADR 0037. */
|
|
88
|
+
readonly evidence: DiscoveredVariableEvidence | undefined;
|
|
89
|
+
}
|
|
90
|
+
export interface CatalogContract extends EnvGovernanceFields {
|
|
91
|
+
readonly file: string;
|
|
92
|
+
readonly exportName: string;
|
|
93
|
+
readonly contractName: string;
|
|
94
|
+
readonly active: boolean;
|
|
95
|
+
readonly documented: boolean;
|
|
96
|
+
readonly category: string | undefined;
|
|
97
|
+
readonly exclusiveGroup: string | undefined;
|
|
98
|
+
/** Keyed by variable name -- unique within one contract (a schema
|
|
99
|
+
* object-literal property name), unlike `contractName` at the top level. */
|
|
100
|
+
readonly variables: Readonly<Record<string, CatalogVariable>>;
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* Same data `renderCatalog()` renders to Markdown, reshaped for JSON/
|
|
104
|
+
* programmatic consumers instead of prose. See `GenerateDocumentationResult.catalog`.
|
|
105
|
+
*/
|
|
106
|
+
export declare function buildCatalog(contracts: readonly ContractModelContract[]): CatalogContract[];
|
|
107
|
+
/** Every variable key that appeared as a catalog heading in a previously-generated docs file. Exported for testing. */
|
|
108
|
+
export declare function extractPreviouslyDocumentedKeys(previousContent: string): Set<string>;
|
|
109
|
+
/**
|
|
110
|
+
* Every variable key that was documented under an *active* contract in a
|
|
111
|
+
* previously-generated docs file -- walks the same `- Active: yes/no`
|
|
112
|
+
* marker `renderCatalog` always emits immediately after each `## <contract>`
|
|
113
|
+
* heading, so a key already inactive last time (a permanently-dormant
|
|
114
|
+
* contract, e.g. behind an unused feature flag) is excluded even though it
|
|
115
|
+
* still appears as a `### \`KEY\`` heading. Exported for testing.
|
|
116
|
+
*/
|
|
117
|
+
export declare function extractPreviouslyActiveKeys(previousContent: string): Set<string>;
|
|
118
|
+
/** Every number the security review reports, as structured data instead of only rendered Markdown text. */
|
|
119
|
+
export interface SecurityReviewCounters {
|
|
120
|
+
readonly totalContracts: number;
|
|
121
|
+
readonly totalVariableDeclarations: number;
|
|
122
|
+
readonly activeVariableDeclarations: number;
|
|
123
|
+
readonly uniqueVariableNames: number;
|
|
124
|
+
readonly expiresAtSetCount: number;
|
|
125
|
+
readonly expiredCount: number;
|
|
126
|
+
readonly expiringSoonCount: number;
|
|
127
|
+
readonly requiredCount: number;
|
|
128
|
+
readonly refreshInstructionsCount: number;
|
|
129
|
+
readonly noOwnerCount: number;
|
|
130
|
+
readonly duplicateVariableNameCount: number;
|
|
131
|
+
readonly undocumentedContractCount: number;
|
|
132
|
+
readonly undocumentedVariableCount: number;
|
|
133
|
+
}
|
|
134
|
+
/**
|
|
135
|
+
* Computes every number `renderSecurityReview()` reports, as real data.
|
|
136
|
+
*
|
|
137
|
+
* @remarks
|
|
138
|
+
* Previously this arithmetic lived entirely inside the renderer as closure
|
|
139
|
+
* locals that only ever became interpolated Markdown text -- no exported
|
|
140
|
+
* type backed any of it, so nothing downstream (the `--json` envelope, a CI
|
|
141
|
+
* gate, a future Finding Model adapter) could consume it as data. Extracted
|
|
142
|
+
* so it can be reused wherever these facts are needed, not just prose.
|
|
143
|
+
*/
|
|
144
|
+
export declare function computeSecurityReviewCounters(contracts: readonly ContractModelContract[], expiringWithinDays: number, now: Date, undocumentedContractCount: number, undocumentedVariableCount: number): SecurityReviewCounters;
|
|
145
|
+
/**
|
|
146
|
+
* Renders the full docs artifact: header + change summary + table of
|
|
147
|
+
* contents, then the comprehensive catalog, ownership matrix (if used),
|
|
148
|
+
* dependency graph, lifecycle report, and a security review.
|
|
149
|
+
*
|
|
150
|
+
* @remarks
|
|
151
|
+
* Documents everything discovered, active or not, same scope as the catalog always
|
|
152
|
+
* had. Fully regenerated every run -- unlike `.env.example`, nothing here is
|
|
153
|
+
* meant to be hand-edited, so there's no "never overwrite" behavior.
|
|
154
|
+
*
|
|
155
|
+
* `contracts` is `ContractModel`'s own shape (`file` root-relative and
|
|
156
|
+
* POSIX-separated already, per that model's convention) -- there is no
|
|
157
|
+
* separate `root` parameter to resolve against, unlike this function's
|
|
158
|
+
* pre-ADR-0038 signature.
|
|
159
|
+
*/
|
|
160
|
+
export declare function renderDocs(contracts: readonly ContractModelContract[], options: RenderDocsOptions): string;
|
|
161
|
+
/**
|
|
162
|
+
* Normalizes every wall-clock-relative substring `renderDocs()` can produce
|
|
163
|
+
* -- not just the single `_Generated ..._` timestamp line, but also the
|
|
164
|
+
* lifecycle report's `(**Xd remaining**)`/`(**expired Xd ago**)` annotations
|
|
165
|
+
* and the security review's "Already expired"/"Expiring within N days"
|
|
166
|
+
* counts -- so two renders of the *same* input, taken on different days,
|
|
167
|
+
* compare equal. `check-artifacts.ts`'s drift comparison and the examples
|
|
168
|
+
* golden-file test harness (`test/support/example-runner.ts`) both need
|
|
169
|
+
* exactly this, not just the timestamp line alone: any contract with a near-term
|
|
170
|
+
* `expiresAt` renders day-relative text that would otherwise make `--check`
|
|
171
|
+
* (or a golden-file comparison) report false drift purely because real time
|
|
172
|
+
* passed between generation and comparison.
|
|
173
|
+
*/
|
|
174
|
+
export declare function normalizeDocsForComparison(content: string): string;
|
|
175
|
+
export {};
|
|
176
|
+
//# sourceMappingURL=docs.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../../src/build/docs.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
import type { DiscoveredContract } from "./link.js";
|
|
2
|
+
import type { BuildFileSystem } from "./types.js";
|
|
3
|
+
/**
|
|
4
|
+
* Controls what happens when a `.env.example` already exists at the target
|
|
5
|
+
* location. `"keep-sibling"` (default): never touch the existing file --
|
|
6
|
+
* write a timestamped sibling instead, for the developer to diff/merge
|
|
7
|
+
* manually. `"overwrite"`: replace the existing file with freshly rendered
|
|
8
|
+
* content directly. `"skip"`: write nothing at all.
|
|
9
|
+
*/
|
|
10
|
+
export type EnvExampleOnExisting = "keep-sibling" | "overwrite" | "skip";
|
|
11
|
+
/** The result of a completed {@link writeEnvExample} call. */
|
|
12
|
+
export interface EnvExampleResult {
|
|
13
|
+
/**
|
|
14
|
+
* Where the example file actually got written. `undefined` only when
|
|
15
|
+
* `onExisting: "skip"` left an existing file untouched and nothing was
|
|
16
|
+
* written.
|
|
17
|
+
*/
|
|
18
|
+
readonly writtenPath: string | undefined;
|
|
19
|
+
/**
|
|
20
|
+
* Set when a file already existed at the requested location and was left
|
|
21
|
+
* untouched: with the default `"keep-sibling"`, `writtenPath` is a fresh
|
|
22
|
+
* timestamped sibling instead; with `"skip"`, this is the only outcome and
|
|
23
|
+
* `writtenPath` is `undefined`. Always `undefined` with `"overwrite"`.
|
|
24
|
+
*/
|
|
25
|
+
readonly skippedExistingPath: string | undefined;
|
|
26
|
+
/** Variable names (live or already commented-out) in an existing example file that no discovered contract declares anymore. */
|
|
27
|
+
readonly staleVariables: readonly string[];
|
|
28
|
+
/** Variables live in an existing example file whose feature is no longer active, and that no other active feature still needs -- safe to comment out. */
|
|
29
|
+
readonly variablesToComment: readonly string[];
|
|
30
|
+
/** Variables the current (active) configuration requires that aren't yet a live entry in an existing example file. */
|
|
31
|
+
readonly variablesToAdd: readonly string[];
|
|
32
|
+
}
|
|
33
|
+
/** The result of {@link computeReconciliation}: an existing `.env.example` diffed against the current configuration. */
|
|
34
|
+
export interface Reconciliation {
|
|
35
|
+
/** Variable names (live or already commented-out) in an existing example file that no discovered contract declares anymore. */
|
|
36
|
+
readonly staleVariables: readonly string[];
|
|
37
|
+
/** Variables live in an existing example file whose feature is no longer active, and that no other active feature still needs -- safe to comment out. */
|
|
38
|
+
readonly variablesToComment: readonly string[];
|
|
39
|
+
/** Variables the current (active) configuration requires that aren't yet a live entry in an existing example file. */
|
|
40
|
+
readonly variablesToAdd: readonly string[];
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Renders a deterministic `.env.example`-style file scoped to the *current*
|
|
44
|
+
* configuration: every unique variable the active contracts require (one
|
|
45
|
+
* live entry per key, alphabetical; a key declared by more than one active
|
|
46
|
+
* contract renders once live and the rest commented-out with a pointer),
|
|
47
|
+
* followed by variables unique to disabled contracts (commented-out, for
|
|
48
|
+
* visibility -- a key already required by an active contract is not unique
|
|
49
|
+
* and never repeated here). `reconciliationHeader`, when non-empty, is
|
|
50
|
+
* spliced in right after the banner (see `computeReconciliation`).
|
|
51
|
+
*/
|
|
52
|
+
export declare function renderEnvExample(contracts: readonly DiscoveredContract[], reconciliationHeader?: readonly string[]): string;
|
|
53
|
+
/** Parses `KEY=value` lines out of an existing `.env`-style file, ignoring comments and blank lines. */
|
|
54
|
+
export declare function extractDeclaredVariables(source: string): string[];
|
|
55
|
+
/** Parses `# KEY=value` lines out of an existing `.env`-style file -- variables it already knows about but has turned off. */
|
|
56
|
+
export declare function extractCommentedVariables(source: string): string[];
|
|
57
|
+
/**
|
|
58
|
+
* Diffs an existing `.env.example` against the current configuration into
|
|
59
|
+
* three actionable sets. Pure and filesystem-independent -- `writeEnvExample`
|
|
60
|
+
* is the only caller that reads the file itself.
|
|
61
|
+
*/
|
|
62
|
+
export declare function computeReconciliation(contracts: readonly DiscoveredContract[], existingContent: string): Reconciliation;
|
|
63
|
+
/**
|
|
64
|
+
* Writes a rendered `.env.example` to `location`. Behavior when a file
|
|
65
|
+
* already exists there is governed by `options.onExisting` (default
|
|
66
|
+
* `"keep-sibling"`, see `EnvExampleOnExisting`):
|
|
67
|
+
* - `"keep-sibling"`: the existing file is left alone; freshly generated
|
|
68
|
+
* content is written to a timestamped sibling instead
|
|
69
|
+
* (`<location>.<epoch-ms>`), prefixed with a reconciliation header
|
|
70
|
+
* comparing it against the existing file (omitted when there's nothing
|
|
71
|
+
* to report).
|
|
72
|
+
* - `"overwrite"`: the existing file is replaced directly with freshly
|
|
73
|
+
* rendered content -- no reconciliation header (the changes it would
|
|
74
|
+
* describe are already applied).
|
|
75
|
+
* - `"skip"`: nothing is written.
|
|
76
|
+
* When no file exists yet at `location`, all three modes behave the same:
|
|
77
|
+
* write fresh content, nothing to reconcile against. `staleVariables`/
|
|
78
|
+
* `variablesToComment`/`variablesToAdd` are always computed and returned
|
|
79
|
+
* when a prior file existed, even under `"overwrite"`/`"skip"`, as a
|
|
80
|
+
* diagnostic -- independent of whether anything was actually written.
|
|
81
|
+
*/
|
|
82
|
+
export declare function writeEnvExample(contracts: readonly DiscoveredContract[], location: string, fs: BuildFileSystem, options?: {
|
|
83
|
+
onExisting?: EnvExampleOnExisting;
|
|
84
|
+
}): Promise<EnvExampleResult>;
|
|
85
|
+
//# sourceMappingURL=env-example.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"env-example.d.ts","sourceRoot":"","sources":["../../../src/build/env-example.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAsB,MAAM,WAAW,CAAA;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAGjD;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,cAAc,GAAG,WAAW,GAAG,MAAM,CAAA;AAExE,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAA;IAChD,+HAA+H;IAC/H,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,yJAAyJ;IACzJ,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9C,sHAAsH;IACtH,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3C;AAED,wHAAwH;AACxH,MAAM,WAAW,cAAc;IAC7B,+HAA+H;IAC/H,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,yJAAyJ;IACzJ,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9C,sHAAsH;IACtH,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3C;AAuED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,oBAAoB,GAAE,SAAS,MAAM,EAAO,GAC3C,MAAM,CAiDR;AAED,wGAAwG;AACxG,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAQjE;AAED,8HAA8H;AAC9H,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAQlE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,eAAe,EAAE,MAAM,GACtB,cAAc,CAkBhB;AAmBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,eAAe,EACnB,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,oBAAoB,CAAA;CAAO,GAClD,OAAO,CAAC,gBAAgB,CAAC,CA6D3B"}
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
import type { CompatibilityIssue } from "./compatibility.js";
|
|
2
|
+
/**
|
|
3
|
+
* Thrown by {@link generateEnvManifest} on a blocking compatibility/exclusive-group
|
|
4
|
+
* finding, or an output path escaping `root`.
|
|
5
|
+
*
|
|
6
|
+
* @remarks
|
|
7
|
+
* Nothing is written when this throws -- generation fails atomically, same as
|
|
8
|
+
* {@link runtime.validateEnv} fails atomically at runtime.
|
|
9
|
+
*
|
|
10
|
+
* `code` is a stable, Stable-tier discriminant for programmatic handling --
|
|
11
|
+
* prefer it over `.name`/`instanceof` when a message-independent switch is needed.
|
|
12
|
+
*/
|
|
13
|
+
export declare class EnvManifestGenerationError extends Error {
|
|
14
|
+
/** Stable discriminant for programmatic handling; always `"ENV_MANIFEST_GENERATION_FAILED"`. */
|
|
15
|
+
readonly code = "ENV_MANIFEST_GENERATION_FAILED";
|
|
16
|
+
/** Every blocking finding, aggregated. */
|
|
17
|
+
readonly issues: readonly CompatibilityIssue[];
|
|
18
|
+
constructor(issues: readonly CompatibilityIssue[]);
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Thrown by {@link generateDocumentation} on a blocking undocumented-contract/
|
|
22
|
+
* variable finding (when `onUndocumented: "throw"`), or an output path
|
|
23
|
+
* (`location`/`envExample.location`) escaping `root`. Nothing is written
|
|
24
|
+
* when this throws.
|
|
25
|
+
*
|
|
26
|
+
* @remarks
|
|
27
|
+
* `code` is a stable, Stable-tier discriminant for programmatic handling --
|
|
28
|
+
* prefer it over `.name`/`instanceof` when a message-independent switch is needed.
|
|
29
|
+
*/
|
|
30
|
+
export declare class EnvDocumentationGenerationError extends Error {
|
|
31
|
+
/** Stable discriminant for programmatic handling; always `"ENV_DOCUMENTATION_GENERATION_FAILED"`. */
|
|
32
|
+
readonly code = "ENV_DOCUMENTATION_GENERATION_FAILED";
|
|
33
|
+
/** Every blocking finding, aggregated. */
|
|
34
|
+
readonly issues: readonly CompatibilityIssue[];
|
|
35
|
+
constructor(issues: readonly CompatibilityIssue[]);
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Thrown by {@link generateUsageReport} on a blocking abandoned-contract/
|
|
39
|
+
* unconsumed-owned-variable finding (when `onOwnershipIssue: "throw"`), or an
|
|
40
|
+
* output path (`report.location`) escaping `root`.
|
|
41
|
+
*
|
|
42
|
+
* @remarks
|
|
43
|
+
* Never thrown for `unresolvedConsumers` or `indeterminate` findings -- both are "we don't
|
|
44
|
+
* know" states, and uncertainty is never promoted to a failure.
|
|
45
|
+
*
|
|
46
|
+
* `code` is a stable, Stable-tier discriminant for programmatic handling --
|
|
47
|
+
* prefer it over `.name`/`instanceof` when a message-independent switch is needed.
|
|
48
|
+
*/
|
|
49
|
+
export declare class EnvUsageAnalysisError extends Error {
|
|
50
|
+
/** Stable discriminant for programmatic handling; always `"ENV_USAGE_ANALYSIS_FAILED"`. */
|
|
51
|
+
readonly code = "ENV_USAGE_ANALYSIS_FAILED";
|
|
52
|
+
/** Every blocking finding, aggregated. */
|
|
53
|
+
readonly issues: readonly CompatibilityIssue[];
|
|
54
|
+
constructor(issues: readonly CompatibilityIssue[]);
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Thrown by {@link generateEnvArtifacts} when any requested pass (manifest/docs/usage)
|
|
58
|
+
* reports a blocking finding, aggregated across all requested passes into
|
|
59
|
+
* one error.
|
|
60
|
+
*
|
|
61
|
+
* @remarks
|
|
62
|
+
* Nothing from any pass is written when this throws -- see
|
|
63
|
+
* `generate-env-artifacts.ts`'s compute-atomic guarantee (ADR 0011). Write-phase failures
|
|
64
|
+
* (a real I/O error after all computes already passed) are NOT wrapped in
|
|
65
|
+
* this type -- they propagate as whatever `fs.writeFile` itself throws,
|
|
66
|
+
* since by that point some artifacts may already be on disk.
|
|
67
|
+
*
|
|
68
|
+
* `code` is a stable, Stable-tier discriminant for programmatic handling --
|
|
69
|
+
* prefer it over `.name`/`instanceof` when a message-independent switch is needed.
|
|
70
|
+
*/
|
|
71
|
+
export declare class EnvProjectGenerationError extends Error {
|
|
72
|
+
/** Stable discriminant for programmatic handling; always `"ENV_PROJECT_GENERATION_FAILED"`. */
|
|
73
|
+
readonly code = "ENV_PROJECT_GENERATION_FAILED";
|
|
74
|
+
/** Every blocking finding, aggregated across all requested passes. */
|
|
75
|
+
readonly issues: readonly CompatibilityIssue[];
|
|
76
|
+
constructor(issues: readonly CompatibilityIssue[]);
|
|
77
|
+
}
|
|
78
|
+
//# sourceMappingURL=errors.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/build/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAmB5D;;;;;;;;;;GAUG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,gGAAgG;IAChG,QAAQ,CAAC,IAAI,oCAAmC;IAChD,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAA;gBAElC,MAAM,EAAE,SAAS,kBAAkB,EAAE;CAelD;AAED;;;;;;;;;GASG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,qGAAqG;IACrG,QAAQ,CAAC,IAAI,yCAAwC;IACrD,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAA;gBAElC,MAAM,EAAE,SAAS,kBAAkB,EAAE;CAelD;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,2FAA2F;IAC3F,QAAQ,CAAC,IAAI,+BAA8B;IAC3C,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAA;gBAElC,MAAM,EAAE,SAAS,kBAAkB,EAAE;CAWlD;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,+FAA+F;IAC/F,QAAQ,CAAC,IAAI,mCAAkC;IAC/C,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAA;gBAElC,MAAM,EAAE,SAAS,kBAAkB,EAAE;CAQlD"}
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
import type { EvidenceModel } from "./evidence-model.js";
|
|
2
|
+
import type { GenerateEvidenceModelOptions } from "./generate-evidence.js";
|
|
3
|
+
import type { BuildFileSystem } from "./types.js";
|
|
4
|
+
/**
|
|
5
|
+
* A fast, honest read path for the persisted evidence artifact -- for a
|
|
6
|
+
* report/projection script, a CI step, or any consumer that just wants the
|
|
7
|
+
* current `EvidenceModel` without paying a full `generateEvidenceModel()`
|
|
8
|
+
* recompute (schema parsing, cross-file linking, the dependency-graph AST
|
|
9
|
+
* scan, all six model builds) on every single invocation, and without ever
|
|
10
|
+
* risking silently-stale data. The mechanism: a cheap content fingerprint,
|
|
11
|
+
* computed from raw file bytes with zero AST work, lets a caller cheaply
|
|
12
|
+
* prove "nothing relevant to evidence generation has changed since this file
|
|
13
|
+
* was last written" before trusting it.
|
|
14
|
+
*/
|
|
15
|
+
/** Options for {@link computeSourceFingerprint}. */
|
|
16
|
+
export interface ComputeSourceFingerprintOptions {
|
|
17
|
+
/** The filesystem capability -- `./build` never imports `node:fs` (ADR 0040). */
|
|
18
|
+
readonly fs: BuildFileSystem;
|
|
19
|
+
readonly root: string;
|
|
20
|
+
readonly include: readonly string[];
|
|
21
|
+
readonly exclude: readonly string[];
|
|
22
|
+
readonly packages?: readonly string[] | undefined;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* SHA-256 over the raw bytes of every schema file and every usage-scan-
|
|
26
|
+
* surface file (the same file sets `assembleProject()`/`computeScanSurface()`
|
|
27
|
+
* touch), plus env-cap's own installed version -- zero AST parsing or
|
|
28
|
+
* linking. Still requires the discovery/glob walk itself (fingerprinting has
|
|
29
|
+
* to know which files matter), but skips everything after it. Deterministic:
|
|
30
|
+
* file paths are deduplicated and sorted before hashing, so the result never
|
|
31
|
+
* depends on filesystem enumeration order.
|
|
32
|
+
*
|
|
33
|
+
* @remarks
|
|
34
|
+
* Not a timestamp, and never compared as one -- a fresh mtime doesn't prove
|
|
35
|
+
* content is unchanged (a checkout, a rebase, or a touch can all bump it
|
|
36
|
+
* with no real edit), and content is the only thing that actually
|
|
37
|
+
* invalidates a cached evidence artifact.
|
|
38
|
+
*/
|
|
39
|
+
export declare function computeSourceFingerprint(options: ComputeSourceFingerprintOptions): Promise<string>;
|
|
40
|
+
/** Writes `fingerprint`'s paired sidecar for `evidencePath` -- call immediately after writing the evidence artifact itself, so the two files always describe the same moment in the source tree's history. */
|
|
41
|
+
export declare function writeEvidenceFingerprint(evidencePath: string, fingerprint: string, fs: BuildFileSystem): Promise<void>;
|
|
42
|
+
/** Options for {@link getEvidenceModel} -- every `generateEvidenceModel()` option, plus where the cached artifact lives. */
|
|
43
|
+
export interface GetEvidenceModelOptions extends GenerateEvidenceModelOptions {
|
|
44
|
+
/** Where the cached evidence artifact (and its `.fingerprint` sidecar) live, e.g. `docs/env.evidence.json`, relative to `root`. Required -- there is no honest default env-cap could guess at for where a project keeps this. */
|
|
45
|
+
readonly location: string;
|
|
46
|
+
}
|
|
47
|
+
/** The result of {@link getEvidenceModel}. */
|
|
48
|
+
export interface GetEvidenceModelResult {
|
|
49
|
+
readonly evidence: EvidenceModel;
|
|
50
|
+
/** `"hit"` -- the committed evidence artifact's fingerprint matched current source; read from disk, no recompute. `"miss"` -- a real `generateEvidenceModel()` call ran. */
|
|
51
|
+
readonly source: "hit" | "miss";
|
|
52
|
+
/** Set only when `source === "miss"` -- why the cache wasn't trusted, for a caller that wants to log it. */
|
|
53
|
+
readonly missReason: string | undefined;
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Trusts the committed evidence artifact at `options.location` only when its
|
|
57
|
+
* paired `.fingerprint` sidecar matches a freshly (cheaply) computed
|
|
58
|
+
* {@link computeSourceFingerprint} -- never on file presence alone, never on
|
|
59
|
+
* a timestamp. On any mismatch (stale fingerprint, missing/corrupt evidence
|
|
60
|
+
* file, no fingerprint sidecar at all), falls back to a real
|
|
61
|
+
* `generateEvidenceModel()` call -- never hard-fails, never silently serves
|
|
62
|
+
* data that might be stale.
|
|
63
|
+
*
|
|
64
|
+
* @remarks
|
|
65
|
+
* Never writes anything. A cache miss here does not self-heal the cache --
|
|
66
|
+
* only an explicit write (`generateEnvArtifacts()`'s `evidence` option)
|
|
67
|
+
* refreshes the committed artifact and its fingerprint together, so "when
|
|
68
|
+
* was this last regenerated" stays under explicit control, never an
|
|
69
|
+
* implicit side effect of a read. Two independent callers hitting the same
|
|
70
|
+
* stale cache both recompute independently; neither one's recompute updates
|
|
71
|
+
* the file the other reads.
|
|
72
|
+
*/
|
|
73
|
+
export declare function getEvidenceModel(options: GetEvidenceModelOptions): Promise<GetEvidenceModelResult>;
|
|
74
|
+
//# sourceMappingURL=evidence-cache.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"evidence-cache.d.ts","sourceRoot":"","sources":["../../../src/build/evidence-cache.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAKxD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,wBAAwB,CAAA;AAO1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;;;;;;;;;GAUG;AAEH,oDAAoD;AACpD,MAAM,WAAW,+BAA+B;IAC9C,iFAAiF;IACjF,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;CAClD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,MAAM,CAAC,CA8CjB;AAMD,8MAA8M;AAC9M,wBAAsB,wBAAwB,CAC5C,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,eAAe,GAClB,OAAO,CAAC,IAAI,CAAC,CAMf;AAED,4HAA4H;AAC5H,MAAM,WAAW,uBAAwB,SAAQ,4BAA4B;IAC3E,iOAAiO;IACjO,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,8CAA8C;AAC9C,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;IAChC,4KAA4K;IAC5K,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAA;IAC/B,4GAA4G;IAC5G,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CACxC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAuDjC"}
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import type { ChangeModel } from "./change-model.js";
|
|
2
|
+
import type { ContractModel } from "./contract-model.js";
|
|
3
|
+
import type { DependencyModel } from "./dependency-model.js";
|
|
4
|
+
import type { FindingModel } from "./finding-model.js";
|
|
5
|
+
import type { LifecycleModel } from "./lifecycle-model.js";
|
|
6
|
+
import type { OwnershipModel } from "./ownership-model.js";
|
|
7
|
+
/**
|
|
8
|
+
* Bump only when a reader could misinterpret the new shape of `EvidenceModel`
|
|
9
|
+
* itself (not any one sub-model's own `<MODEL>_SCHEMA_VERSION`, which is
|
|
10
|
+
* versioned independently) -- same rule every other canonical model follows.
|
|
11
|
+
*/
|
|
12
|
+
export declare const EVIDENCE_MODEL_SCHEMA_VERSION = 1;
|
|
13
|
+
/**
|
|
14
|
+
* Who/when/what produced a given `EvidenceModel` instance. Caller-supplied,
|
|
15
|
+
* never ambient-detected -- `generateEvidenceModel()` never shells out to
|
|
16
|
+
* `git` itself, mirroring ADR 0012's live-expiration-callback precedent.
|
|
17
|
+
*/
|
|
18
|
+
export interface EvidenceProvenance {
|
|
19
|
+
readonly generatedAt: string;
|
|
20
|
+
readonly toolVersion: string;
|
|
21
|
+
readonly commit: string | undefined;
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* The seventh canonical fact model (ADR 0024): the assembled union of the
|
|
25
|
+
* other six, plus provenance, the immutable input every
|
|
26
|
+
* `defineEvidenceProjection()` projector runs over (`@maverickcer/env-cap/evidence`,
|
|
27
|
+
* ADR 0031).
|
|
28
|
+
*
|
|
29
|
+
* @remarks
|
|
30
|
+
* This type is the one intentional exception to `src/build/`'s zero-
|
|
31
|
+
* cross-folder-import rule: `src/evidence/` imports it with `import type`
|
|
32
|
+
* only (fully erased at compile time under `verbatimModuleSyntax`), the same
|
|
33
|
+
* shape as `helpers`' single sanctioned edge onto `runtime` -- see
|
|
34
|
+
* `specs/architecture.md`. `src/evidence/` never imports a *value* from
|
|
35
|
+
* here, only this shape, so it stays isomorphic and Node-free. An actual
|
|
36
|
+
* `EvidenceModel` instance is produced by {@link generateEvidenceModel}
|
|
37
|
+
* (`@maverickcer/env-cap/build`, Node-only), which runs discovery once,
|
|
38
|
+
* builds all six sub-models, and `deepFreeze()`s the result.
|
|
39
|
+
*/
|
|
40
|
+
export interface EvidenceModel {
|
|
41
|
+
readonly schemaVersion: typeof EVIDENCE_MODEL_SCHEMA_VERSION;
|
|
42
|
+
readonly provenance: EvidenceProvenance;
|
|
43
|
+
readonly contract: ContractModel;
|
|
44
|
+
readonly dependency: DependencyModel;
|
|
45
|
+
readonly ownership: OwnershipModel;
|
|
46
|
+
readonly lifecycle: LifecycleModel;
|
|
47
|
+
readonly finding: FindingModel;
|
|
48
|
+
readonly change: ChangeModel;
|
|
49
|
+
}
|
|
50
|
+
//# sourceMappingURL=evidence-model.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"evidence-model.d.ts","sourceRoot":"","sources":["../../../src/build/evidence-model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAE1D;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,IAAI,CAAA;AAE9C;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;CACpC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,aAAa,EAAE,OAAO,6BAA6B,CAAA;IAC5D,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAA;IACvC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;IAChC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAA;IACpC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;IAClC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;IAClC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;IAC9B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAC7B"}
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import type { SourcePosition } from "./source-position.js";
|
|
2
|
+
/**
|
|
3
|
+
* A structured pointer back to where a `Finding` (or, later, any other
|
|
4
|
+
* model's derived fact) came from -- never a formatted string. See ADR 0024
|
|
5
|
+
* and ADR 0026.
|
|
6
|
+
*
|
|
7
|
+
* @remarks
|
|
8
|
+
* Deliberately only as many `model` variants as something in this codebase
|
|
9
|
+
* actually needs to reference today (`"contract"`, `"ownership"`,
|
|
10
|
+
* `"change"`). This is an additive, growable union, not a speculative
|
|
11
|
+
* six-model union built ahead of a real consumer -- a later phase (e.g. the
|
|
12
|
+
* Dependency or Lifecycle Model) adds its own variant only once a finding
|
|
13
|
+
* or projector genuinely needs to point at it.
|
|
14
|
+
*/
|
|
15
|
+
export type EvidenceReference = ContractEvidenceReference | OwnershipEvidenceReference | ChangeEvidenceReference;
|
|
16
|
+
/**
|
|
17
|
+
* The one shape every model in this package uses to point at a declared
|
|
18
|
+
* contract: the file it's declared in, and the binding it's exported as.
|
|
19
|
+
* Nothing else -- see ADR 0039.
|
|
20
|
+
*
|
|
21
|
+
* @remarks
|
|
22
|
+
* Deliberately *not* carrying `contractName`. A display name is a rendering
|
|
23
|
+
* concern, resolved on demand from `ContractModel` (the one model that owns
|
|
24
|
+
* it) by whichever renderer actually needs prose; duplicating it onto every
|
|
25
|
+
* reference made it a second, independently-stale copy of a fact that can
|
|
26
|
+
* change under a `documentEnv()` edit. Deliberately not carrying a
|
|
27
|
+
* pre-formatted `identity` string either -- `${file}#${exportName}` is
|
|
28
|
+
* trivially derivable, and a stored copy is one more thing that can disagree
|
|
29
|
+
* with the two fields it was built from. Code that genuinely needs a map key
|
|
30
|
+
* builds that string locally, at the point of use.
|
|
31
|
+
*/
|
|
32
|
+
export interface ContractRef {
|
|
33
|
+
/** Root-relative, POSIX-separated path of the file declaring the contract -- see `displayPath()`. */
|
|
34
|
+
readonly file: string;
|
|
35
|
+
/** The binding name the `createEnv()` result is exported as. */
|
|
36
|
+
readonly exportName: string;
|
|
37
|
+
}
|
|
38
|
+
/** Points at a declared contract and, optionally, one of its variables -- the shape every `CompatibilityIssue`/documentation finding can be resolved to. Unlike {@link ContractRef}, both identity fields are optional here: a finding can legitimately know only the file (an unresolvable `documentEnv()` link) or neither. */
|
|
39
|
+
export interface ContractEvidenceReference {
|
|
40
|
+
readonly model: "contract";
|
|
41
|
+
/** Root-relative, POSIX-separated path of the file declaring the contract, when known -- see `displayPath()`. */
|
|
42
|
+
readonly file: string | undefined;
|
|
43
|
+
/** The contract's exported binding name, when known. */
|
|
44
|
+
readonly exportName: string | undefined;
|
|
45
|
+
/** The environment variable name, when the finding is variable-level rather than contract-level. */
|
|
46
|
+
readonly variable: string | undefined;
|
|
47
|
+
/** Exact file:line:column this finding is about -- the contract's `createEnv()` declaration, its `documentEnv()` declaration, or the specific variable's own declaration, whichever is most relevant to the finding. `undefined` only when no single position is more relevant than another (e.g. an `indeterminate-ownership` finding, which can have multiple candidate sites -- see `IndeterminateOwnershipFinding.dynamicAccessSites` for the full list instead). See ADR 0036. */
|
|
48
|
+
readonly position: SourcePosition | undefined;
|
|
49
|
+
}
|
|
50
|
+
/** Points at a contract by name for an ownership/usage finding -- `usage-report.ts`'s finding types don't consistently carry `file`/`exportName` together, only `contractName`. */
|
|
51
|
+
export interface OwnershipEvidenceReference {
|
|
52
|
+
readonly model: "ownership";
|
|
53
|
+
readonly contractName: string;
|
|
54
|
+
/** Root-relative path of the file declaring the contract, when the source finding carries one. */
|
|
55
|
+
readonly file: string | undefined;
|
|
56
|
+
/** The environment variable name, when the finding is variable-level rather than contract-level. */
|
|
57
|
+
readonly variable: string | undefined;
|
|
58
|
+
/** See {@link ContractEvidenceReference.position}. */
|
|
59
|
+
readonly position: SourcePosition | undefined;
|
|
60
|
+
}
|
|
61
|
+
/** Points at a generated artifact's path -- what `checkEnvArtifacts()`'s drift findings are about, not a declared contract or variable at all. */
|
|
62
|
+
export interface ChangeEvidenceReference {
|
|
63
|
+
readonly model: "change";
|
|
64
|
+
/** Absolute path of the generated artifact. */
|
|
65
|
+
readonly path: string;
|
|
66
|
+
}
|
|
67
|
+
//# sourceMappingURL=evidence-reference.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"evidence-reference.d.ts","sourceRoot":"","sources":["../../../src/build/evidence-reference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAE1D;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,iBAAiB,GAC3B,yBAAyB,GAAG,0BAA0B,GAAG,uBAAuB,CAAA;AAElF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,WAAW;IAC1B,qGAAqG;IACrG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,gEAAgE;IAChE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED,iUAAiU;AACjU,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,iHAAiH;IACjH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,wDAAwD;IACxD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,oGAAoG;IACpG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,udAAud;IACvd,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;CAC9C;AAED,mLAAmL;AACnL,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,kGAAkG;IAClG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,oGAAoG;IACpG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,CAAA;CAC9C;AAED,kJAAkJ;AAClJ,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB"}
|