@maverickcer/env-cap 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +279 -0
- package/dist/.dts/build/assemble-project.d.ts +47 -0
- package/dist/.dts/build/assemble-project.d.ts.map +1 -0
- package/dist/.dts/build/change-model.d.ts +62 -0
- package/dist/.dts/build/change-model.d.ts.map +1 -0
- package/dist/.dts/build/check-artifacts.d.ts +48 -0
- package/dist/.dts/build/check-artifacts.d.ts.map +1 -0
- package/dist/.dts/build/citation-verification.d.ts +62 -0
- package/dist/.dts/build/citation-verification.d.ts.map +1 -0
- package/dist/.dts/build/compatibility.d.ts +76 -0
- package/dist/.dts/build/compatibility.d.ts.map +1 -0
- package/dist/.dts/build/contract-model.d.ts +92 -0
- package/dist/.dts/build/contract-model.d.ts.map +1 -0
- package/dist/.dts/build/deep-equal.d.ts +9 -0
- package/dist/.dts/build/deep-equal.d.ts.map +1 -0
- package/dist/.dts/build/deep-freeze.d.ts +20 -0
- package/dist/.dts/build/deep-freeze.d.ts.map +1 -0
- package/dist/.dts/build/dependency-graph.d.ts +168 -0
- package/dist/.dts/build/dependency-graph.d.ts.map +1 -0
- package/dist/.dts/build/dependency-model.d.ts +79 -0
- package/dist/.dts/build/dependency-model.d.ts.map +1 -0
- package/dist/.dts/build/discover.d.ts +25 -0
- package/dist/.dts/build/discover.d.ts.map +1 -0
- package/dist/.dts/build/display-path.d.ts +24 -0
- package/dist/.dts/build/display-path.d.ts.map +1 -0
- package/dist/.dts/build/docs.d.ts +176 -0
- package/dist/.dts/build/docs.d.ts.map +1 -0
- package/dist/.dts/build/env-example.d.ts +85 -0
- package/dist/.dts/build/env-example.d.ts.map +1 -0
- package/dist/.dts/build/errors.d.ts +78 -0
- package/dist/.dts/build/errors.d.ts.map +1 -0
- package/dist/.dts/build/evidence-cache.d.ts +74 -0
- package/dist/.dts/build/evidence-cache.d.ts.map +1 -0
- package/dist/.dts/build/evidence-model.d.ts +50 -0
- package/dist/.dts/build/evidence-model.d.ts.map +1 -0
- package/dist/.dts/build/evidence-reference.d.ts +67 -0
- package/dist/.dts/build/evidence-reference.d.ts.map +1 -0
- package/dist/.dts/build/evidence-snapshot.d.ts +123 -0
- package/dist/.dts/build/evidence-snapshot.d.ts.map +1 -0
- package/dist/.dts/build/exclusive-group.d.ts +19 -0
- package/dist/.dts/build/exclusive-group.d.ts.map +1 -0
- package/dist/.dts/build/finding-model.d.ts +79 -0
- package/dist/.dts/build/finding-model.d.ts.map +1 -0
- package/dist/.dts/build/generate-documentation.d.ts +176 -0
- package/dist/.dts/build/generate-documentation.d.ts.map +1 -0
- package/dist/.dts/build/generate-env-artifacts.d.ts +176 -0
- package/dist/.dts/build/generate-env-artifacts.d.ts.map +1 -0
- package/dist/.dts/build/generate-evidence.d.ts +77 -0
- package/dist/.dts/build/generate-evidence.d.ts.map +1 -0
- package/dist/.dts/build/generate-manifest.d.ts +101 -0
- package/dist/.dts/build/generate-manifest.d.ts.map +1 -0
- package/dist/.dts/build/generate-usage.d.ts +95 -0
- package/dist/.dts/build/generate-usage.d.ts.map +1 -0
- package/dist/.dts/build/generated-banner.d.ts +52 -0
- package/dist/.dts/build/generated-banner.d.ts.map +1 -0
- package/dist/.dts/build/glob.d.ts +18 -0
- package/dist/.dts/build/glob.d.ts.map +1 -0
- package/dist/.dts/build/governance-fields.d.ts +34 -0
- package/dist/.dts/build/governance-fields.d.ts.map +1 -0
- package/dist/.dts/build/humanize-key.d.ts +14 -0
- package/dist/.dts/build/humanize-key.d.ts.map +1 -0
- package/dist/.dts/build/index.d.ts +107 -0
- package/dist/.dts/build/index.d.ts.map +1 -0
- package/dist/.dts/build/lifecycle-model.d.ts +64 -0
- package/dist/.dts/build/lifecycle-model.d.ts.map +1 -0
- package/dist/.dts/build/link.d.ts +215 -0
- package/dist/.dts/build/link.d.ts.map +1 -0
- package/dist/.dts/build/literal-eval.d.ts +23 -0
- package/dist/.dts/build/literal-eval.d.ts.map +1 -0
- package/dist/.dts/build/live-expirations.d.ts +47 -0
- package/dist/.dts/build/live-expirations.d.ts.map +1 -0
- package/dist/.dts/build/manifest-snapshot.d.ts +229 -0
- package/dist/.dts/build/manifest-snapshot.d.ts.map +1 -0
- package/dist/.dts/build/manifest.d.ts +31 -0
- package/dist/.dts/build/manifest.d.ts.map +1 -0
- package/dist/.dts/build/map-utils.d.ts +8 -0
- package/dist/.dts/build/map-utils.d.ts.map +1 -0
- package/dist/.dts/build/ownership-model.d.ts +57 -0
- package/dist/.dts/build/ownership-model.d.ts.map +1 -0
- package/dist/.dts/build/parse.d.ts +199 -0
- package/dist/.dts/build/parse.d.ts.map +1 -0
- package/dist/.dts/build/reference-projections.d.ts +156 -0
- package/dist/.dts/build/reference-projections.d.ts.map +1 -0
- package/dist/.dts/build/resolution/resolve-import.d.ts +53 -0
- package/dist/.dts/build/resolution/resolve-import.d.ts.map +1 -0
- package/dist/.dts/build/resolution/resolve-package-schema.d.ts +83 -0
- package/dist/.dts/build/resolution/resolve-package-schema.d.ts.map +1 -0
- package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +101 -0
- package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts/build/resolution/resolve-within-root.d.ts +35 -0
- package/dist/.dts/build/resolution/resolve-within-root.d.ts.map +1 -0
- package/dist/.dts/build/resolve-import.d.ts +50 -0
- package/dist/.dts/build/resolve-import.d.ts.map +1 -0
- package/dist/.dts/build/resolve-package-schema.d.ts +99 -0
- package/dist/.dts/build/resolve-package-schema.d.ts.map +1 -0
- package/dist/.dts/build/resolve-tsconfig-paths.d.ts +100 -0
- package/dist/.dts/build/resolve-tsconfig-paths.d.ts.map +1 -0
- package/dist/.dts/build/resolve-within-root.d.ts +35 -0
- package/dist/.dts/build/resolve-within-root.d.ts.map +1 -0
- package/dist/.dts/build/sarif.d.ts +66 -0
- package/dist/.dts/build/sarif.d.ts.map +1 -0
- package/dist/.dts/build/scan-dependencies.d.ts +47 -0
- package/dist/.dts/build/scan-dependencies.d.ts.map +1 -0
- package/dist/.dts/build/sort-by-identity.d.ts +14 -0
- package/dist/.dts/build/sort-by-identity.d.ts.map +1 -0
- package/dist/.dts/build/source-position.d.ts +69 -0
- package/dist/.dts/build/source-position.d.ts.map +1 -0
- package/dist/.dts/build/tool-version.d.ts +8 -0
- package/dist/.dts/build/tool-version.d.ts.map +1 -0
- package/dist/.dts/build/types.d.ts +53 -0
- package/dist/.dts/build/types.d.ts.map +1 -0
- package/dist/.dts/build/usage-report.d.ts +124 -0
- package/dist/.dts/build/usage-report.d.ts.map +1 -0
- package/dist/.dts/cli/filesystem.d.ts +3 -0
- package/dist/.dts/cli/filesystem.d.ts.map +1 -0
- package/dist/.dts/eslint-plugin/glob.d.ts +18 -0
- package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -0
- package/dist/.dts/eslint-plugin/index.d.ts +27 -0
- package/dist/.dts/eslint-plugin/index.d.ts.map +1 -0
- package/dist/.dts/eslint-plugin/no-node-fs.d.ts +25 -0
- package/dist/.dts/eslint-plugin/no-node-fs.d.ts.map +1 -0
- package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts +23 -0
- package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts.map +1 -0
- package/dist/.dts/evidence/define-projection.d.ts +51 -0
- package/dist/.dts/evidence/define-projection.d.ts.map +1 -0
- package/dist/.dts/evidence/index.d.ts +23 -0
- package/dist/.dts/evidence/index.d.ts.map +1 -0
- package/dist/.dts/helpers/index.d.ts +135 -0
- package/dist/.dts/helpers/index.d.ts.map +1 -0
- package/dist/.dts/helpers/processors.d.ts +32 -0
- package/dist/.dts/helpers/processors.d.ts.map +1 -0
- package/dist/.dts/helpers/validators.d.ts +68 -0
- package/dist/.dts/helpers/validators.d.ts.map +1 -0
- package/dist/.dts/node/index.d.ts +2 -0
- package/dist/.dts/node/index.d.ts.map +1 -0
- package/dist/.dts/runtime/cache.d.ts +20 -0
- package/dist/.dts/runtime/cache.d.ts.map +1 -0
- package/dist/.dts/runtime/create.d.ts +20 -0
- package/dist/.dts/runtime/create.d.ts.map +1 -0
- package/dist/.dts/runtime/document.d.ts +181 -0
- package/dist/.dts/runtime/document.d.ts.map +1 -0
- package/dist/.dts/runtime/errors.d.ts +55 -0
- package/dist/.dts/runtime/errors.d.ts.map +1 -0
- package/dist/.dts/runtime/index.d.ts +24 -0
- package/dist/.dts/runtime/index.d.ts.map +1 -0
- package/dist/.dts/runtime/registry.d.ts +12 -0
- package/dist/.dts/runtime/registry.d.ts.map +1 -0
- package/dist/.dts/runtime/reset.d.ts +8 -0
- package/dist/.dts/runtime/reset.d.ts.map +1 -0
- package/dist/.dts/runtime/types.d.ts +175 -0
- package/dist/.dts/runtime/types.d.ts.map +1 -0
- package/dist/.dts/runtime/validate.d.ts +14 -0
- package/dist/.dts/runtime/validate.d.ts.map +1 -0
- package/dist/build.cjs +83 -0
- package/dist/build.cjs.map +1 -0
- package/dist/build.d.cts +1 -0
- package/dist/build.d.ts +1 -0
- package/dist/build.js +19 -0
- package/dist/build.js.map +1 -0
- package/dist/cli/index.js +134 -0
- package/dist/cli/index.js.map +1 -0
- package/dist/eslint-plugin/index.cjs +12 -0
- package/dist/eslint-plugin/index.cjs.map +1 -0
- package/dist/eslint-plugin/index.d.cts +1 -0
- package/dist/eslint-plugin/index.d.ts +1 -0
- package/dist/eslint-plugin/index.js +5 -0
- package/dist/eslint-plugin/index.js.map +1 -0
- package/dist/evidence.cjs +7 -0
- package/dist/evidence.cjs.map +1 -0
- package/dist/evidence.d.cts +1 -0
- package/dist/evidence.d.ts +1 -0
- package/dist/evidence.js +5 -0
- package/dist/evidence.js.map +1 -0
- package/dist/helpers.cjs +8 -0
- package/dist/helpers.cjs.map +1 -0
- package/dist/helpers.d.cts +1 -0
- package/dist/helpers.d.ts +1 -0
- package/dist/helpers.js +5 -0
- package/dist/helpers.js.map +1 -0
- package/dist/index.cjs +15 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +1 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +7 -0
- package/dist/index.js.map +1 -0
- package/dist/node.cjs +13 -0
- package/dist/node.cjs.map +1 -0
- package/dist/node.d.cts +1 -0
- package/dist/node.d.ts +1 -0
- package/dist/node.js +7 -0
- package/dist/node.js.map +1 -0
- package/package.json +183 -0
- package/schemas/contract-model.schema.json +321 -0
- package/schemas/env-cap-report.schema.json +2369 -0
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
import type ts from "typescript";
|
|
2
|
+
/**
|
|
3
|
+
* A precise pointer into a source file -- the shared shape every exact-position fact in the
|
|
4
|
+
* build pipeline (declaration sites, usage sites, dynamic-access sites) uses, so a consumer never
|
|
5
|
+
* has to reconcile three ad hoc `{ file; line; column }` shapes that happen to mean the same
|
|
6
|
+
* thing. See ADR 0036.
|
|
7
|
+
*/
|
|
8
|
+
export interface SourcePosition {
|
|
9
|
+
/** Root-relative, POSIX-separated. */
|
|
10
|
+
readonly file: string;
|
|
11
|
+
/** 1-indexed line number. */
|
|
12
|
+
readonly line: number;
|
|
13
|
+
/** 1-indexed column number. */
|
|
14
|
+
readonly column: number;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* `node`'s starting line/column within `sourceFile`, both 1-indexed -- TypeScript's own
|
|
18
|
+
* `getLineAndCharacterOfPosition()` returns 0-indexed values for both. Callers combine this with
|
|
19
|
+
* the file path they already have in scope to build a full {@link SourcePosition}; this returns
|
|
20
|
+
* only the two numbers so it's usable identically whether the caller's `file` is already
|
|
21
|
+
* root-relative or still absolute.
|
|
22
|
+
*/
|
|
23
|
+
export declare function positionOf(sourceFile: ts.SourceFile, node: ts.Node): {
|
|
24
|
+
line: number;
|
|
25
|
+
column: number;
|
|
26
|
+
};
|
|
27
|
+
/**
|
|
28
|
+
* Parses a developer-supplied `"<relative-path>:<line>:<column>"` citation
|
|
29
|
+
* (a {@link runtime.VariableDocs.dynamicAccess} entry) into a
|
|
30
|
+
* {@link SourcePosition}. Splits on the *last* two colons so a path
|
|
31
|
+
* containing colons of its own (rare, but not impossible) still parses --
|
|
32
|
+
* only the trailing `:<line>:<column>` is treated as position syntax.
|
|
33
|
+
* Returns `undefined` for anything that isn't exactly that shape (missing
|
|
34
|
+
* segments, a non-positive-integer line/column, an empty path) -- callers
|
|
35
|
+
* treat that as a malformed citation, never a thrown error. See ADR 0037.
|
|
36
|
+
*/
|
|
37
|
+
export declare function parsePositionCitation(citation: string): SourcePosition | undefined;
|
|
38
|
+
/**
|
|
39
|
+
* One developer-declared {@link runtime.VariableDocs.dynamicAccess} citation's
|
|
40
|
+
* current acknowledgment state -- a claim, never an observation. Kept fully
|
|
41
|
+
* separate from `VariableAccessStatus` (which stays exactly 3-valued and
|
|
42
|
+
* purely AST-derived) so a developer's assertion can never make env-cap
|
|
43
|
+
* claim it observed something it didn't. See
|
|
44
|
+
* `evidence-snapshot.ts`'s `computeDynamicAccessAcknowledgments()` (where
|
|
45
|
+
* this is computed) and ADR 0037.
|
|
46
|
+
*/
|
|
47
|
+
export interface DynamicAccessAssertion extends SourcePosition {
|
|
48
|
+
/**
|
|
49
|
+
* `"fresh"` -- the cited file currently exists and either matches the
|
|
50
|
+
* committed baseline hash or has no baseline yet (a brand-new citation,
|
|
51
|
+
* nothing to contradict it yet). `"stale"` -- the cited file exists but its
|
|
52
|
+
* content has changed since the committed baseline. `"missing"` -- the
|
|
53
|
+
* cited file no longer exists at all. Re-derived from scratch every run;
|
|
54
|
+
* never cached across runs.
|
|
55
|
+
*/
|
|
56
|
+
readonly acknowledgment: "fresh" | "stale" | "missing";
|
|
57
|
+
/**
|
|
58
|
+
* SHA-256 hex digest of the cited file's content *as observed this run* --
|
|
59
|
+
* `undefined` iff `acknowledgment === "missing"` (nothing to hash). This is
|
|
60
|
+
* the one field that makes freshness checking possible without a
|
|
61
|
+
* snapshot-only shadow type: the live `EvidenceModel.dependency` a caller
|
|
62
|
+
* gets back and the persisted evidence snapshot a later run reads back as
|
|
63
|
+
* its baseline are the exact same shape -- this run's `contentHash` becomes
|
|
64
|
+
* next run's comparison target directly. See `evidence-snapshot.ts` and
|
|
65
|
+
* ADR 0037.
|
|
66
|
+
*/
|
|
67
|
+
readonly contentHash: string | undefined;
|
|
68
|
+
}
|
|
69
|
+
//# sourceMappingURL=source-position.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"source-position.d.ts","sourceRoot":"","sources":["../../../src/build/source-position.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAA;AAEhC;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,IAAI,EAAE,EAAE,CAAC,IAAI,GACZ;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAGlC;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAQlF;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAuB,SAAQ,cAAc;IAC5D;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAAA;IACtD;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;CACzC"}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* env-cap's own installed version -- stamped onto
|
|
3
|
+
* `EvidenceModel.provenance.toolVersion` and mixed into
|
|
4
|
+
* `computeSourceFingerprint()`. `./build` never reads its own manifest from
|
|
5
|
+
* disk (ADR 0040).
|
|
6
|
+
*/
|
|
7
|
+
export declare function readToolVersion(): string;
|
|
8
|
+
//# sourceMappingURL=tool-version.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"tool-version.d.ts","sourceRoot":"","sources":["../../../src/build/tool-version.ts"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC"}
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The filesystem capability `env-cap/build` requires from its caller.
|
|
3
|
+
*
|
|
4
|
+
* `./build` is a **library surface**: it must not acquire filesystem access
|
|
5
|
+
* implicitly (no `node:fs` import anywhere under `src/` outside `src/cli/`).
|
|
6
|
+
* Every public options object in `build/index.ts` carries a required `fs`
|
|
7
|
+
* field of this type, and the caller supplies a concrete adapter -- the
|
|
8
|
+
* `env-cap` CLI builds one over `node:fs/promises` (`src/cli/filesystem.ts`);
|
|
9
|
+
* a test builds either that same real adapter or an in-memory fake. See ADR
|
|
10
|
+
* 0040.
|
|
11
|
+
*
|
|
12
|
+
* "Ambient-fs-free" means specifically: `./build` never reaches for
|
|
13
|
+
* `node:fs` itself. It still performs real filesystem operations -- the
|
|
14
|
+
* capability is always handed in.
|
|
15
|
+
*
|
|
16
|
+
* The shape is modeled on `node:fs/promises`'s own signatures so a thin
|
|
17
|
+
* adapter is a drop-in value, but uses minimal structural types
|
|
18
|
+
* ({@link BuildDirent}/{@link BuildStats}) rather than Node's `Dirent`/
|
|
19
|
+
* `Stats` -- the capability boundary shouldn't leak Node's type surface just
|
|
20
|
+
* because the concrete adapter happens to be Node-backed. Only the
|
|
21
|
+
* operations `src/build/**` actually calls are here.
|
|
22
|
+
*/
|
|
23
|
+
export interface BuildFileSystem {
|
|
24
|
+
/** Read a UTF-8 text file. Rejects if the path doesn't exist or isn't readable. */
|
|
25
|
+
readonly readFile: (path: string, encoding: "utf8") => Promise<string>;
|
|
26
|
+
/** Write a UTF-8 text file, creating or truncating it. The parent directory must already exist. */
|
|
27
|
+
readonly writeFile: (path: string, data: string, encoding: "utf8") => Promise<void>;
|
|
28
|
+
/** Create a directory and every missing parent. A no-op if it already exists. */
|
|
29
|
+
readonly mkdir: (path: string, options: {
|
|
30
|
+
readonly recursive: true;
|
|
31
|
+
}) => Promise<void>;
|
|
32
|
+
/** List a directory's entries with their file-type info. */
|
|
33
|
+
readonly readdir: (path: string, options: {
|
|
34
|
+
readonly withFileTypes: true;
|
|
35
|
+
}) => Promise<readonly BuildDirent[]>;
|
|
36
|
+
/** Stat a path (following symlinks). Rejects if the path doesn't exist. */
|
|
37
|
+
readonly stat: (path: string) => Promise<BuildStats>;
|
|
38
|
+
/** Resolve a path to its canonical, symlink-free absolute form. */
|
|
39
|
+
readonly realpath: (path: string) => Promise<string>;
|
|
40
|
+
}
|
|
41
|
+
/** One directory entry from {@link BuildFileSystem.readdir} -- the subset of Node's `Dirent` `src/build/**` reads. */
|
|
42
|
+
export interface BuildDirent {
|
|
43
|
+
readonly name: string;
|
|
44
|
+
readonly isDirectory: () => boolean;
|
|
45
|
+
readonly isFile: () => boolean;
|
|
46
|
+
}
|
|
47
|
+
/** A path's stat info from {@link BuildFileSystem.stat} -- the subset of Node's `Stats` `src/build/**` reads. */
|
|
48
|
+
export interface BuildStats {
|
|
49
|
+
readonly isFile: () => boolean;
|
|
50
|
+
/** Size in bytes -- read by the package-schema resolver to enforce a size ceiling. */
|
|
51
|
+
readonly size: number;
|
|
52
|
+
}
|
|
53
|
+
//# sourceMappingURL=types.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/build/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IACtE,mGAAmG;IACnG,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnF,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACtF,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,CAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,QAAQ,CAAC,aAAa,EAAE,IAAI,CAAA;KAAE,KACtC,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAA;IACpC,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;IACpD,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CACrD;AAED,sHAAsH;AACtH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,OAAO,CAAA;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAA;CAC/B;AAED,iHAAiH;AACjH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAA;IAC9B,sFAAsF;IACtF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB"}
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
import type { ScannedSurface } from "./dependency-graph.js";
|
|
2
|
+
import type { DynamicAccessCitationProblem } from "./citation-verification.js";
|
|
3
|
+
import type { ParseWarning } from "./parse.js";
|
|
4
|
+
import type { DynamicAccessAssertion, SourcePosition } from "./source-position.js";
|
|
5
|
+
/** One contract's dependency-ownership summary: who owns it, and who depends on it. */
|
|
6
|
+
export interface OwnershipDependencyEntry {
|
|
7
|
+
/** Resolved display name (see {@link DiscoveredContract.contractName}). */
|
|
8
|
+
readonly contractName: string;
|
|
9
|
+
/** Root-relative path of the file declaring the contract. */
|
|
10
|
+
readonly file: string;
|
|
11
|
+
/** Contract-level default owner, if set. */
|
|
12
|
+
readonly owner: string | undefined;
|
|
13
|
+
/** Number of variables declared in this contract's schema. */
|
|
14
|
+
readonly variableCount: number;
|
|
15
|
+
/** Files coupled to this contract (imported it, referenced it, or read a
|
|
16
|
+
* member from it) -- contract-level "who depends on this," NOT proof any
|
|
17
|
+
* specific variable was read. Blast radius if this contract changes is
|
|
18
|
+
* `consumers.length`, computed by callers/renderers on demand rather than
|
|
19
|
+
* stored redundantly here. */
|
|
20
|
+
readonly consumers: readonly string[];
|
|
21
|
+
}
|
|
22
|
+
/** A contract never imported anywhere in the scanned repository. */
|
|
23
|
+
export interface AbandonedContractFinding {
|
|
24
|
+
/** Resolved display name (see {@link DiscoveredContract.contractName}). */
|
|
25
|
+
readonly contractName: string;
|
|
26
|
+
/** Root-relative path of the file declaring the contract. */
|
|
27
|
+
readonly file: string;
|
|
28
|
+
/** Contract-level default owner, if set. */
|
|
29
|
+
readonly owner: string | undefined;
|
|
30
|
+
}
|
|
31
|
+
/** A contract reachable only through an unresolved barrel re-export -- can't be proven abandoned or consumed. */
|
|
32
|
+
export interface UnresolvedConsumerFinding {
|
|
33
|
+
/** Resolved display name (see {@link DiscoveredContract.contractName}). */
|
|
34
|
+
readonly contractName: string;
|
|
35
|
+
/** Root-relative path of the file declaring the contract. */
|
|
36
|
+
readonly file: string;
|
|
37
|
+
/** Human-readable explanation of why usage couldn't be resolved. */
|
|
38
|
+
readonly reason: string;
|
|
39
|
+
}
|
|
40
|
+
/** An owned variable with no consumer found in the scanned repository. */
|
|
41
|
+
export interface UnconsumedOwnedVariableFinding {
|
|
42
|
+
/** Resolved display name (see {@link DiscoveredContract.contractName}). */
|
|
43
|
+
readonly contractName: string;
|
|
44
|
+
/** The owning contract's default owner, if set. */
|
|
45
|
+
readonly owner: string | undefined;
|
|
46
|
+
/** The unconsumed environment variable name. */
|
|
47
|
+
readonly key: string;
|
|
48
|
+
/**
|
|
49
|
+
* Every `dynamicAccess` citation for this variable that's currently
|
|
50
|
+
* `"stale"` or `"missing"` (empty when none exist -- see ADR 0037).
|
|
51
|
+
* Empty is the *strongest* "looks genuinely unused" signal: no developer
|
|
52
|
+
* has ever claimed otherwise. A non-empty list means someone specifically
|
|
53
|
+
* claimed dynamic access here once and that claim can no longer be
|
|
54
|
+
* verified -- worth a human check before deleting, not a stronger reason
|
|
55
|
+
* to trust "unconsumed." Exposed as the raw citations, not a collapsed
|
|
56
|
+
* `high`/`low` label, matching this codebase's "show the receipt" pattern
|
|
57
|
+
* (ADR 0036/0037) -- a reader can judge confidence from the actual
|
|
58
|
+
* evidence rather than trusting a derived summary. See ADR 0038.
|
|
59
|
+
*/
|
|
60
|
+
readonly staleOrMissingCitations: readonly DynamicAccessCitationProblem[];
|
|
61
|
+
}
|
|
62
|
+
/** A variable accessed only via dynamic (computed) property access -- usage cannot be determined statically. */
|
|
63
|
+
export interface IndeterminateOwnershipFinding {
|
|
64
|
+
/** Resolved display name (see {@link DiscoveredContract.contractName}). */
|
|
65
|
+
readonly contractName: string;
|
|
66
|
+
/** The environment variable name. */
|
|
67
|
+
readonly key: string;
|
|
68
|
+
/** Human-readable explanation of why usage couldn't be determined. */
|
|
69
|
+
readonly reason: string;
|
|
70
|
+
/** Every AST-observed dynamic-access site backing `reason`, structured -- see ADR 0036. */
|
|
71
|
+
readonly dynamicAccessSites: readonly SourcePosition[];
|
|
72
|
+
/** See {@link UnconsumedOwnedVariableFinding.staleOrMissingCitations}. */
|
|
73
|
+
readonly staleOrMissingCitations: readonly DynamicAccessCitationProblem[];
|
|
74
|
+
}
|
|
75
|
+
/** A variable that would otherwise be reported `unconsumedOwnedVariables`/`indeterminate`, but has at least one `"fresh"` developer-declared `dynamicAccess` citation -- the raw static status is always shown alongside the assertion, never replaced by it. See ADR 0037. */
|
|
76
|
+
export interface AssertedDynamicAccessFinding {
|
|
77
|
+
/** Resolved display name (see {@link DiscoveredContract.contractName}). */
|
|
78
|
+
readonly contractName: string;
|
|
79
|
+
/** The environment variable name. */
|
|
80
|
+
readonly key: string;
|
|
81
|
+
/** What this variable's status would be without the fresh assertion. */
|
|
82
|
+
readonly wouldBeStatus: "unconsumed" | "indeterminate";
|
|
83
|
+
/** Every citation covering this variable, each with its own current freshness. */
|
|
84
|
+
readonly dynamicAccessAssertions: readonly DynamicAccessAssertion[];
|
|
85
|
+
}
|
|
86
|
+
/** Everything {@link renderUsageReport} needs to render the Dependency &
|
|
87
|
+
* Ownership Report -- deliberately independent of (not derived from)
|
|
88
|
+
* `GenerateUsageReportResult` in `generate-usage.js`, the same way
|
|
89
|
+
* `RenderDocsOptions` in `docs.ts` doesn't derive from
|
|
90
|
+
* `GenerateDocumentationResult`. `generate-usage.ts` composes its own
|
|
91
|
+
* public result type from these building blocks instead, keeping this
|
|
92
|
+
* renderer module importable without its orchestrator. */
|
|
93
|
+
export interface RenderUsageReportOptions {
|
|
94
|
+
/** Every contract's ownership/dependency summary. */
|
|
95
|
+
readonly dependencyOwnership: readonly OwnershipDependencyEntry[];
|
|
96
|
+
/** Contracts never imported anywhere in the scanned repository. */
|
|
97
|
+
readonly abandonedContracts: readonly AbandonedContractFinding[];
|
|
98
|
+
/** Advisory only, never gates `onOwnershipIssue` -- a contract only
|
|
99
|
+
* reaches here when an ambiguous barrel re-export makes "abandoned" or
|
|
100
|
+
* "consumed" both unprovable. */
|
|
101
|
+
readonly unresolvedConsumers: readonly UnresolvedConsumerFinding[];
|
|
102
|
+
/** Owned variables with no consumer found in the scanned repository. */
|
|
103
|
+
readonly unconsumedOwnedVariables: readonly UnconsumedOwnedVariableFinding[];
|
|
104
|
+
/** Variables accessed only via dynamic (computed) property access. */
|
|
105
|
+
readonly indeterminate: readonly IndeterminateOwnershipFinding[];
|
|
106
|
+
/** Variables a developer has re-acknowledged via `dynamicAccess`, freshly -- see ADR 0037. */
|
|
107
|
+
readonly asserted: readonly AssertedDynamicAccessFinding[];
|
|
108
|
+
/** Schema-discovery parse warnings plus, since ADR 0014, any `packages`
|
|
109
|
+
* resolution failures -- surfaced here too (not just from
|
|
110
|
+
* `generateEnvManifest`/`generateDocumentation`) so a team relying only
|
|
111
|
+
* on `--ownership` output still learns when a cross-package contract
|
|
112
|
+
* failed to resolve. */
|
|
113
|
+
readonly parseWarnings: readonly ParseWarning[];
|
|
114
|
+
/** Every surface actually scanned for usage -- see ADR 0036. Named explicitly next to `unconsumedOwnedVariables` so "no consumer found" is never read as a stronger claim than what was actually searched. */
|
|
115
|
+
readonly scannedSurfaces: readonly ScannedSurface[];
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* Renders the Dependency & Ownership Report: who owns each variable, which
|
|
119
|
+
* features consume each contract, and what the blast radius is if it
|
|
120
|
+
* changes -- structured around exactly those three questions, never generic
|
|
121
|
+
* "dead code"/"unused symbol" language.
|
|
122
|
+
*/
|
|
123
|
+
export declare function renderUsageReport(computed: RenderUsageReportOptions): string;
|
|
124
|
+
//# sourceMappingURL=usage-report.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"usage-report.d.ts","sourceRoot":"","sources":["../../../src/build/usage-report.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"filesystem.d.ts","sourceRoot":"","sources":["../../../src/cli/filesystem.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAe,eAAe,EAAc,MAAM,mBAAmB,CAAA;AAwDjF,eAAO,MAAM,mBAAmB,EAAE,eAOjC,CAAA"}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Converts one glob pattern to a RegExp. Handles `**` as "any number of path
|
|
3
|
+
* segments, including zero" (so `**\/node_modules/**` matches a root-level
|
|
4
|
+
* `node_modules`, and `**\/env.schema.ts` matches a root-level file, not just
|
|
5
|
+
* nested ones) -- a plain `**` -> `.*` substitution gets both of those wrong.
|
|
6
|
+
*
|
|
7
|
+
* Used by no-raw-process-env.ts's `allow` option.
|
|
8
|
+
*
|
|
9
|
+
* Deliberately duplicated (not shared) with
|
|
10
|
+
* src/build/glob.ts, which needs the exact same matching behavior for its
|
|
11
|
+
* own schema-discovery walk -- keeps this eslint-plugin-only module free of
|
|
12
|
+
* any import reaching outside src/eslint-plugin, so `src/eslint-plugin`
|
|
13
|
+
* stays independently splittable into its own package with zero
|
|
14
|
+
* source-level cross-folder dependency. Not re-exported from `./index.js` --
|
|
15
|
+
* Private tier per VERSIONING.md.
|
|
16
|
+
*/
|
|
17
|
+
export declare function globToRegExp(pattern: string): RegExp;
|
|
18
|
+
//# sourceMappingURL=glob.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../../src/eslint-plugin/glob.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAyBpD"}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import { noNodeFs } from "./no-node-fs.js";
|
|
2
|
+
import { noRawProcessEnv } from "./no-raw-process-env.js";
|
|
3
|
+
/**
|
|
4
|
+
* `env-cap/eslint-plugin` -- a flat-config-shaped plugin object
|
|
5
|
+
* ({ rules: { ... } }), consumed as:
|
|
6
|
+
*
|
|
7
|
+
* import envCapPlugin from "env-cap/eslint-plugin";
|
|
8
|
+
* export default [{ plugins: { "env-cap": envCapPlugin }, rules: { "env-cap/no-raw-process-env": "error" } }];
|
|
9
|
+
*
|
|
10
|
+
* A 4th public entry point alongside `.`, `./build`, `./helpers` -- see ADR 0017.
|
|
11
|
+
*/
|
|
12
|
+
declare const plugin: {
|
|
13
|
+
/** Every rule this plugin ships, keyed by its flat-config rule name. */
|
|
14
|
+
rules: {
|
|
15
|
+
/** See {@link noRawProcessEnv}. */
|
|
16
|
+
"no-raw-process-env": import("@typescript-eslint/utils/ts-eslint").RuleModule<"noRawProcessEnv", [import("./no-raw-process-env.js").RuleOptions], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
|
|
17
|
+
name: string;
|
|
18
|
+
};
|
|
19
|
+
/** See {@link noNodeFs}. */
|
|
20
|
+
"no-node-fs": import("@typescript-eslint/utils/ts-eslint").RuleModule<"noNodeFs", [import("./no-node-fs.js").RuleOptions], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
|
|
21
|
+
name: string;
|
|
22
|
+
};
|
|
23
|
+
};
|
|
24
|
+
};
|
|
25
|
+
export default plugin;
|
|
26
|
+
export { noNodeFs, noRawProcessEnv };
|
|
27
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/eslint-plugin/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAEzD;;;;;;;;GAQG;AACH,QAAA,MAAM,MAAM;IACV,wEAAwE;;QAEtE,mCAAmC;;;;QAEnC,4BAA4B;;;;;CAG/B,CAAA;AACD,eAAe,MAAM,CAAA;AACrB,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,CAAA"}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
export interface RuleOptions {
|
|
2
|
+
/** Glob-array of files this rule doesn't apply to -- a project's own
|
|
3
|
+
* executable entry points (a CLI, a script) that legitimately construct
|
|
4
|
+
* the concrete filesystem adapter. Empty by default -- populate it
|
|
5
|
+
* explicitly; the rule never guesses at what counts as an executable
|
|
6
|
+
* capability boundary. */
|
|
7
|
+
allow?: string[];
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* Flags any `import`/`require`/dynamic `import()` of `node:fs` in library
|
|
11
|
+
* code, so a library surface acquires its filesystem capability from the
|
|
12
|
+
* caller instead of reaching for `node:fs` itself (the same discipline
|
|
13
|
+
* `repo-contract`'s ADR-0011 established for `child_process`/`process.env`).
|
|
14
|
+
* See ADR 0040.
|
|
15
|
+
*
|
|
16
|
+
* @remarks
|
|
17
|
+
* Nothing is exempt by default. env-cap's own config allows `src/cli/**`
|
|
18
|
+
* (the executable capability boundary that builds the `node:fs/promises`
|
|
19
|
+
* adapter); a consuming project sets its own `allow` for its own entry
|
|
20
|
+
* points.
|
|
21
|
+
*/
|
|
22
|
+
export declare const noNodeFs: import("@typescript-eslint/utils/ts-eslint").RuleModule<"noNodeFs", [RuleOptions], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
|
|
23
|
+
name: string;
|
|
24
|
+
};
|
|
25
|
+
//# sourceMappingURL=no-node-fs.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"no-node-fs.d.ts","sourceRoot":"","sources":["../../../src/eslint-plugin/no-node-fs.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,WAAW;IAC1B;;;;+BAI2B;IAC3B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CACjB;AAmBD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,QAAQ;;CAsEnB,CAAA"}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
export interface RuleOptions {
|
|
2
|
+
/** Glob-array of files this rule doesn't apply to, beyond the built-in
|
|
3
|
+
* env.schema.ts allowance below -- for a consuming project's own
|
|
4
|
+
* Node-only, build-time bootstrap code (see the README section this
|
|
5
|
+
* rule ships with for the canonical worked example: a live-expiration
|
|
6
|
+
* resolver authenticating to a secrets manager). Empty by default --
|
|
7
|
+
* MUST be populated explicitly by the consuming project; env-cap never
|
|
8
|
+
* guesses at what counts as "trusted bootstrap code." */
|
|
9
|
+
allow?: string[];
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* Flags any direct `process.env.X`/`process.env["X"]` read in application code, so environment
|
|
13
|
+
* access always goes through a capability's own `createEnv()` contract instead.
|
|
14
|
+
*
|
|
15
|
+
* @remarks
|
|
16
|
+
* `env.schema.ts`/`env.schema.tsx` files are always exempt (that's where `createEnv()` itself
|
|
17
|
+
* reads `process.env`); the rule's `allow` option extends that exemption to a consuming
|
|
18
|
+
* project's own trusted bootstrap code.
|
|
19
|
+
*/
|
|
20
|
+
export declare const noRawProcessEnv: import("@typescript-eslint/utils/ts-eslint").RuleModule<"noRawProcessEnv", [RuleOptions], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
|
|
21
|
+
name: string;
|
|
22
|
+
};
|
|
23
|
+
//# sourceMappingURL=no-raw-process-env.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"no-raw-process-env.d.ts","sourceRoot":"","sources":["../../../src/eslint-plugin/no-raw-process-env.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,WAAW;IAC1B;;;;;;8DAM0D;IAC1D,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CACjB;AAID;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe;;CA8D1B,CAAA"}
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
import type { EvidenceModel } from "../build/evidence-model.js";
|
|
2
|
+
/**
|
|
3
|
+
* A pure function from the full Evidence Model to one field of a
|
|
4
|
+
* projection's output shape. Must not mutate `evidence` -- the membrane
|
|
5
|
+
* `defineEvidenceProjection()` wraps it in enforces that at runtime, see
|
|
6
|
+
* `createTrackingProxy()` below -- and must not perform I/O; env-cap can
|
|
7
|
+
* enforce the read-only half of purity but not the "no side effects" half.
|
|
8
|
+
*/
|
|
9
|
+
export type EvidenceProjector<T> = (evidence: EvidenceModel) => T;
|
|
10
|
+
/** One independent, pure projector function per key of the projection's output shape `T`. */
|
|
11
|
+
export type EvidenceProjectionSchema<T extends Record<string, unknown>> = {
|
|
12
|
+
readonly [K in keyof T]: EvidenceProjector<T[K]>;
|
|
13
|
+
};
|
|
14
|
+
/** `project()`'s return shape: the computed output, plus which `EvidenceModel` field paths fed each output key. */
|
|
15
|
+
export interface EvidenceProjectionResult<T extends Record<string, unknown>> {
|
|
16
|
+
readonly value: T;
|
|
17
|
+
readonly sources: Readonly<Record<keyof T, readonly string[]>>;
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* The function `defineEvidenceProjection()` returns. Callable directly for
|
|
21
|
+
* the common case (`projection(evidence)` -> `T`); `.project()` returns the
|
|
22
|
+
* same value alongside automatic provenance -- see ADR 0032.
|
|
23
|
+
*/
|
|
24
|
+
export interface EvidenceProjection<T extends Record<string, unknown>> {
|
|
25
|
+
(evidence: EvidenceModel): T;
|
|
26
|
+
project(evidence: EvidenceModel): EvidenceProjectionResult<T>;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Declares a projection: a named, pure transform from the immutable
|
|
30
|
+
* `EvidenceModel` to any consumer-defined output shape, built entirely from
|
|
31
|
+
* `schema`'s independent per-field projector functions -- see ADR 0031/0032.
|
|
32
|
+
*
|
|
33
|
+
* env-cap's own reference projections (`.env.example`, Environment
|
|
34
|
+
* Configuration Reference, Configuration Ownership, etc.) are built through
|
|
35
|
+
* this exact function, with no privileged internal path -- a consumer's own
|
|
36
|
+
* projection is a first-class citizen, not a lesser one.
|
|
37
|
+
*/
|
|
38
|
+
export declare function defineEvidenceProjection<T extends Record<string, unknown>>(schema: EvidenceProjectionSchema<T>): EvidenceProjection<T>;
|
|
39
|
+
/**
|
|
40
|
+
* The error every membrane write-trap below throws. A function, not a
|
|
41
|
+
* module-level `const` -- a `const` string's mutants are evaluated once at
|
|
42
|
+
* module load and can't be attributed to a covering test under Stryker's
|
|
43
|
+
* `perTest` coverage analysis (a documented false-Survivor, not a real
|
|
44
|
+
* gap); exported so a test can pin the exact message directly, the same way
|
|
45
|
+
* every membrane trap's own `.toThrow(...)` can't (a `TypeError` from a
|
|
46
|
+
* Proxy invariant violation is thrown either way a trap's body is mutated,
|
|
47
|
+
* so `.toThrow(TypeError)` alone doesn't distinguish "our message" from
|
|
48
|
+
* "the engine's own invariant-violation message").
|
|
49
|
+
*/
|
|
50
|
+
export declare function readOnlyMembraneError(): TypeError;
|
|
51
|
+
//# sourceMappingURL=define-projection.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"define-projection.d.ts","sourceRoot":"","sources":["../../../src/evidence/define-projection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAE/D;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,aAAa,KAAK,CAAC,CAAA;AAEjE,6FAA6F;AAC7F,MAAM,MAAM,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IACxE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACjD,CAAA;AAED,mHAAmH;AACnH,MAAM,WAAW,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACzE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;IACjB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAA;CAC/D;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACnE,CAAC,QAAQ,EAAE,aAAa,GAAG,CAAC,CAAA;IAC5B,OAAO,CAAC,QAAQ,EAAE,aAAa,GAAG,wBAAwB,CAAC,CAAC,CAAC,CAAA;CAC9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxE,MAAM,EAAE,wBAAwB,CAAC,CAAC,CAAC,GAClC,kBAAkB,CAAC,CAAC,CAAC,CAkBvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,IAAI,SAAS,CAIjD"}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* env-cap Evidence Model entry point (`env-cap/evidence`).
|
|
3
|
+
*
|
|
4
|
+
* `defineEvidenceProjection()` is the extensibility mechanism the seven
|
|
5
|
+
* canonical fact models (ADR 0024) exist to serve. A projection is a named,
|
|
6
|
+
* pure transform from the immutable `EvidenceModel` -- assembled at build
|
|
7
|
+
* time by `generateEvidenceModel()`, `env-cap/build` -- to any
|
|
8
|
+
* consumer-defined output shape, with automatic read-only enforcement and
|
|
9
|
+
* field-level provenance. See ADR 0031 (why a 5th entry point) and ADR 0032
|
|
10
|
+
* (the Proxy-based mechanism itself).
|
|
11
|
+
*
|
|
12
|
+
* This module is deliberately isomorphic: no `node:fs`, no `typescript`, no
|
|
13
|
+
* knowledge of how an `EvidenceModel` gets built -- it only imports that
|
|
14
|
+
* shape as a type (erased at compile time, mirroring `helpers`' one
|
|
15
|
+
* sanctioned cross-folder edge onto `runtime` -- see
|
|
16
|
+
* `specs/architecture.md`). A dashboard backend, an edge function, or a CI
|
|
17
|
+
* step can run a projection over a previously-generated,
|
|
18
|
+
* JSON-deserialized `EvidenceModel` with zero Node dependency.
|
|
19
|
+
*/
|
|
20
|
+
export type { EvidenceModel, EvidenceProvenance } from "../build/evidence-model.js";
|
|
21
|
+
export { defineEvidenceProjection } from "./define-projection.js";
|
|
22
|
+
export type { EvidenceProjection, EvidenceProjectionResult, EvidenceProjectionSchema, EvidenceProjector, } from "./define-projection.js";
|
|
23
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/evidence/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AACnF,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAA;AACjE,YAAY,EACV,kBAAkB,EAClB,wBAAwB,EACxB,wBAAwB,EACxB,iBAAiB,GAClB,MAAM,wBAAwB,CAAA"}
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Optional convenience helpers for common processor/validator patterns.
|
|
3
|
+
* Entirely separate from the core runtime -- `defineEnv`/`validateEnv` have
|
|
4
|
+
* no knowledge of this module and work identically without it.
|
|
5
|
+
*
|
|
6
|
+
* Usage: `processors.toNumber()`, `validators.range(1, 65535)`.
|
|
7
|
+
*
|
|
8
|
+
* Deliberately built from explicit named imports assembled into plain object
|
|
9
|
+
* literals, not `export * as processors from "./processors.js"`. A bundler
|
|
10
|
+
* (tsup/esbuild) lowers that `export * as` form into a namespace-construction
|
|
11
|
+
* helper call it can't prove side-effect-free, which defeats tree-shaking in
|
|
12
|
+
* a *second*, downstream bundling pass (a consumer's own bundler bundling
|
|
13
|
+
* this already-bundled package): importing only `processors` would still
|
|
14
|
+
* ship all of `validators`' code. A plain object literal of already-imported
|
|
15
|
+
* bindings has no such call in the way, so `import { processors } from
|
|
16
|
+
* "env-cap/helpers"` alone drops `validators` entirely.
|
|
17
|
+
*/
|
|
18
|
+
import { base64, parseJSON, split, toArray, toBigInt, toBoolean, toDate, toInteger, toLowerCase, toNumber, toRegExp, toString, toURL, toUpperCase, trim } from "./processors.js";
|
|
19
|
+
import { after, all, any, before, custom, email, endsWith, finite, future, includes, integer as integerValidator, length, matches, max, maxItems, maxLength, min, minItems, minLength, negative, not, oneOf, optional, past, positive, range, refine, required, safeInteger, unique, url as urlValidator, uuid, uuidVersion } from "./validators.js";
|
|
20
|
+
/**
|
|
21
|
+
* Convenience {@link runtime.Processor} implementations for common coercion
|
|
22
|
+
* patterns (e.g. `processors.toNumber()`).
|
|
23
|
+
*
|
|
24
|
+
* @remarks
|
|
25
|
+
* Naming matches `@maverickcer/data-cap`'s `helpers.processors` -- but these
|
|
26
|
+
* throw with a formatted `Error` message on invalid input, where data-cap's
|
|
27
|
+
* silently return `undefined`. Do not assume the same failure mode when
|
|
28
|
+
* moving between packages.
|
|
29
|
+
*/
|
|
30
|
+
export declare const processors: {
|
|
31
|
+
/** Decodes a base64 string into a `Buffer`. */
|
|
32
|
+
base64: typeof base64;
|
|
33
|
+
/** Parses a JSON string; passes non-string values through unchanged. */
|
|
34
|
+
parseJSON: typeof parseJSON;
|
|
35
|
+
/** Splits a string on `separator` into a trimmed string array; returns `[]` for non-string input. */
|
|
36
|
+
split: typeof split;
|
|
37
|
+
/** Splits a delimited string (or passes through an array) into items, running each through `processors` in order. */
|
|
38
|
+
toArray: typeof toArray;
|
|
39
|
+
/** Coerces a value to a `bigint`. */
|
|
40
|
+
toBigInt: typeof toBigInt;
|
|
41
|
+
/** Coerces common boolean-like strings (`true`/`1`/`yes`/`on`, and their opposites) into a real boolean. */
|
|
42
|
+
toBoolean: typeof toBoolean;
|
|
43
|
+
/** Parses a value into a `Date`. */
|
|
44
|
+
toDate: typeof toDate;
|
|
45
|
+
/** Coerces a value to a number and requires it to be an integer. */
|
|
46
|
+
toInteger: typeof toInteger;
|
|
47
|
+
/** Lowercases a string (coercing nullish values to `""` first). */
|
|
48
|
+
toLowerCase: typeof toLowerCase;
|
|
49
|
+
/** Coerces a value to a number, rejecting empty/whitespace-only strings instead of silently resolving to `0`. */
|
|
50
|
+
toNumber: typeof toNumber;
|
|
51
|
+
/** Compiles a value into a `RegExp`. */
|
|
52
|
+
toRegExp: typeof toRegExp;
|
|
53
|
+
/** Coerces a value to a string, treating nullish values as `""`. */
|
|
54
|
+
toString: typeof toString;
|
|
55
|
+
/** Parses a value into a `URL`, treating nullish values as `""` first. */
|
|
56
|
+
toURL: typeof toURL;
|
|
57
|
+
/** Uppercases a string (coercing nullish values to `""` first). */
|
|
58
|
+
toUpperCase: typeof toUpperCase;
|
|
59
|
+
/** Trims surrounding whitespace from a string (coercing nullish values to `""` first). */
|
|
60
|
+
trim: typeof trim;
|
|
61
|
+
};
|
|
62
|
+
/** Convenience {@link runtime.Validator} implementations for common validation patterns (e.g. `validators.range(1, 65535)`). */
|
|
63
|
+
export declare const validators: {
|
|
64
|
+
/** Passes when the date value is strictly after `date`. */
|
|
65
|
+
after: typeof after;
|
|
66
|
+
/** Passes only when every wrapped validator passes; returns the first failing message. */
|
|
67
|
+
all: typeof all;
|
|
68
|
+
/** Passes when at least one wrapped validator passes. */
|
|
69
|
+
any: typeof any;
|
|
70
|
+
/** Passes when the date value is strictly before `date`. */
|
|
71
|
+
before: typeof before;
|
|
72
|
+
/** Identity wrapper for a hand-written `Validator<T>` -- no behavior change, just a fluent entry point alongside the other helpers. */
|
|
73
|
+
custom: typeof custom;
|
|
74
|
+
/** Passes for a plausibly-shaped email address (`local@domain`). */
|
|
75
|
+
email: typeof email;
|
|
76
|
+
/** Passes when the string ends with `suffix`. */
|
|
77
|
+
endsWith: typeof endsWith;
|
|
78
|
+
/** Alias for `oneOf` -- passes when the value is one of the `allowed` values. */
|
|
79
|
+
enum: typeof oneOf;
|
|
80
|
+
/** Passes when the number is finite (rejects `Infinity`/`-Infinity`/`NaN`). */
|
|
81
|
+
finite: typeof finite;
|
|
82
|
+
/** Passes when the date is strictly after the current time. */
|
|
83
|
+
future: typeof future;
|
|
84
|
+
/** Passes when the string contains `text` as a substring. */
|
|
85
|
+
includes: typeof includes;
|
|
86
|
+
/** Passes when the number is an integer. */
|
|
87
|
+
integer: typeof integerValidator;
|
|
88
|
+
/** Passes when the string's length is exactly `expected`. */
|
|
89
|
+
length: typeof length;
|
|
90
|
+
/** Passes when the string matches `pattern`; `message` overrides the default failure text. */
|
|
91
|
+
matches: typeof matches;
|
|
92
|
+
/** Passes when the number is less than or equal to `maximum`. */
|
|
93
|
+
max: typeof max;
|
|
94
|
+
/** Passes when the array has at most `maximum` items. */
|
|
95
|
+
maxItems: typeof maxItems;
|
|
96
|
+
/** Passes when the string's length is at most `length`. */
|
|
97
|
+
maxLength: typeof maxLength;
|
|
98
|
+
/** Passes when the number is greater than or equal to `minimum`. */
|
|
99
|
+
min: typeof min;
|
|
100
|
+
/** Passes when the array has at least `minimum` items. */
|
|
101
|
+
minItems: typeof minItems;
|
|
102
|
+
/** Passes when the string's length is at least `length`. */
|
|
103
|
+
minLength: typeof minLength;
|
|
104
|
+
/** Passes when the number is strictly negative. */
|
|
105
|
+
negative: typeof negative;
|
|
106
|
+
/** Inverts a validator: passes when the wrapped validator fails, and vice versa. */
|
|
107
|
+
not: typeof not;
|
|
108
|
+
/** Passes when the value is one of the `allowed` values. */
|
|
109
|
+
oneOf: typeof oneOf;
|
|
110
|
+
/** Passes when the value is undefined, otherwise delegates to the provided validator. */
|
|
111
|
+
optional: typeof optional;
|
|
112
|
+
/** Passes when the date is strictly before the current time. */
|
|
113
|
+
past: typeof past;
|
|
114
|
+
/** Passes when the number is strictly positive. */
|
|
115
|
+
positive: typeof positive;
|
|
116
|
+
/** Passes when the number is within `[minimum, maximum]` inclusive. */
|
|
117
|
+
range: typeof range;
|
|
118
|
+
/** Runs the wrapped validator but replaces its failure message with `message`. */
|
|
119
|
+
refine: typeof refine;
|
|
120
|
+
/** Alias for `matches` -- passes when the string matches `pattern`. */
|
|
121
|
+
regex: typeof matches;
|
|
122
|
+
/** Passes when the value is defined and, unless `allowEmptyString` is set, non-empty. */
|
|
123
|
+
required: typeof required;
|
|
124
|
+
/** Passes when the number is a safe integer (`Number.isSafeInteger`). */
|
|
125
|
+
safeInteger: typeof safeInteger;
|
|
126
|
+
/** Passes when every item in the array is unique. */
|
|
127
|
+
unique: typeof unique;
|
|
128
|
+
/** Passes when the string is a valid absolute URL. */
|
|
129
|
+
url: typeof urlValidator;
|
|
130
|
+
/** Passes when the string is a valid UUID of one of the given `versions` (default: any of 1-8). */
|
|
131
|
+
uuid: typeof uuid;
|
|
132
|
+
/** Shorthand for `uuid([version])` -- passes only for that exact UUID version. */
|
|
133
|
+
uuidVersion: typeof uuidVersion;
|
|
134
|
+
};
|
|
135
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/helpers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EACL,MAAM,EACN,SAAS,EACT,KAAK,EACL,OAAO,EACP,QAAQ,EACR,SAAS,EACT,MAAM,EACN,SAAS,EACT,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,KAAK,EACL,WAAW,EACX,IAAI,EACL,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,KAAK,EACL,GAAG,EACH,GAAG,EACH,MAAM,EACN,MAAM,EACN,KAAK,EACL,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,OAAO,IAAI,gBAAgB,EAC3B,MAAM,EACN,OAAO,EACP,GAAG,EACH,QAAQ,EACR,SAAS,EACT,GAAG,EACH,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,GAAG,EACH,KAAK,EACL,QAAQ,EACR,IAAI,EACJ,QAAQ,EACR,KAAK,EACL,MAAM,EACN,QAAQ,EACR,WAAW,EACX,MAAM,EACN,GAAG,IAAI,YAAY,EACnB,IAAI,EACJ,WAAW,EACZ,MAAM,iBAAiB,CAAA;AAExB;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU;IACrB,+CAA+C;;IAE/C,wEAAwE;;IAExE,qGAAqG;;IAErG,qHAAqH;;IAErH,qCAAqC;;IAErC,4GAA4G;;IAE5G,oCAAoC;;IAEpC,oEAAoE;;IAEpE,mEAAmE;;IAEnE,iHAAiH;;IAEjH,wCAAwC;;IAExC,oEAAoE;;IAEpE,0EAA0E;;IAE1E,mEAAmE;;IAEnE,0FAA0F;;CAE3F,CAAA;AACD,gIAAgI;AAChI,eAAO,MAAM,UAAU;IACrB,2DAA2D;;IAE3D,0FAA0F;;IAE1F,yDAAyD;;IAEzD,4DAA4D;;IAE5D,uIAAuI;;IAEvI,oEAAoE;;IAEpE,iDAAiD;;IAEjD,iFAAiF;;IAEjF,+EAA+E;;IAE/E,+DAA+D;;IAE/D,6DAA6D;;IAE7D,4CAA4C;;IAE5C,6DAA6D;;IAE7D,8FAA8F;;IAE9F,iEAAiE;;IAEjE,yDAAyD;;IAEzD,2DAA2D;;IAE3D,oEAAoE;;IAEpE,0DAA0D;;IAE1D,4DAA4D;;IAE5D,mDAAmD;;IAEnD,oFAAoF;;IAEpF,4DAA4D;;IAE5D,yFAAyF;;IAEzF,gEAAgE;;IAEhE,mDAAmD;;IAEnD,uEAAuE;;IAEvE,kFAAkF;;IAElF,uEAAuE;;IAEvE,yFAAyF;;IAEzF,yEAAyE;;IAEzE,qDAAqD;;IAErD,sDAAsD;;IAEtD,mGAAmG;;IAEnG,kFAAkF;;CAEnF,CAAA"}
|