@maverickcer/env-cap 0.3.1 → 0.5.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.
Files changed (88) hide show
  1. package/README.md +37 -17
  2. package/dist/.dts/build/change-model.d.ts +1 -0
  3. package/dist/.dts/build/change-model.d.ts.map +1 -1
  4. package/dist/.dts/build/check-artifacts.d.ts.map +1 -1
  5. package/dist/.dts/build/compatibility.d.ts +8 -1
  6. package/dist/.dts/build/compatibility.d.ts.map +1 -1
  7. package/dist/.dts/build/contract-model.d.ts +1 -0
  8. package/dist/.dts/build/contract-model.d.ts.map +1 -1
  9. package/dist/.dts/build/dependency-model.d.ts +2 -0
  10. package/dist/.dts/build/dependency-model.d.ts.map +1 -1
  11. package/dist/.dts/build/discover.d.ts.map +1 -1
  12. package/dist/.dts/build/docs.d.ts.map +1 -1
  13. package/dist/.dts/build/env-example.d.ts.map +1 -1
  14. package/dist/.dts/build/exclusive-group.d.ts.map +1 -1
  15. package/dist/.dts/build/finding-model.d.ts +1 -0
  16. package/dist/.dts/build/finding-model.d.ts.map +1 -1
  17. package/dist/.dts/build/generate-documentation.d.ts +2 -2
  18. package/dist/.dts/build/generate-documentation.d.ts.map +1 -1
  19. package/dist/.dts/build/generate-env-artifacts.d.ts +2 -2
  20. package/dist/.dts/build/generate-env-artifacts.d.ts.map +1 -1
  21. package/dist/.dts/build/generate-evidence.d.ts +2 -2
  22. package/dist/.dts/build/generate-evidence.d.ts.map +1 -1
  23. package/dist/.dts/build/generate-manifest.d.ts +2 -2
  24. package/dist/.dts/build/generate-usage.d.ts +2 -2
  25. package/dist/.dts/build/generate-usage.d.ts.map +1 -1
  26. package/dist/.dts/build/glob.d.ts.map +1 -1
  27. package/dist/.dts/build/governance-fields.d.ts +1 -1
  28. package/dist/.dts/build/index.d.ts +17 -19
  29. package/dist/.dts/build/index.d.ts.map +1 -1
  30. package/dist/.dts/build/lifecycle-model.d.ts +112 -2
  31. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
  32. package/dist/.dts/build/link.d.ts +10 -2
  33. package/dist/.dts/build/link.d.ts.map +1 -1
  34. package/dist/.dts/build/live-expirations.d.ts.map +1 -1
  35. package/dist/.dts/build/manifest.d.ts.map +1 -1
  36. package/dist/.dts/build/ownership-model.d.ts +2 -0
  37. package/dist/.dts/build/ownership-model.d.ts.map +1 -1
  38. package/dist/.dts/build/parse.d.ts +10 -2
  39. package/dist/.dts/build/parse.d.ts.map +1 -1
  40. package/dist/.dts/build/resolution/resolve-package-schema.d.ts.map +1 -1
  41. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts +1 -1
  42. package/dist/.dts/build/resolution/resolve-tsconfig-paths.d.ts.map +1 -1
  43. package/dist/.dts/build/sarif.d.ts.map +1 -1
  44. package/dist/.dts/build/source-position.d.ts +2 -2
  45. package/dist/.dts/build/types.d.ts +3 -0
  46. package/dist/.dts/build/types.d.ts.map +1 -1
  47. package/dist/.dts/eslint-plugin/glob.d.ts.map +1 -1
  48. package/dist/.dts/evidence/define-projection.d.ts +1 -0
  49. package/dist/.dts/evidence/define-projection.d.ts.map +1 -1
  50. package/dist/.dts/helpers/validators.d.ts.map +1 -1
  51. package/dist/.dts/runtime/document.d.ts +41 -2
  52. package/dist/.dts/runtime/document.d.ts.map +1 -1
  53. package/dist/.dts/runtime/index.d.ts +1 -1
  54. package/dist/.dts/runtime/index.d.ts.map +1 -1
  55. package/dist/.dts/runtime/validate.d.ts.map +1 -1
  56. package/dist/build-4SFAWO5Y.js +5148 -0
  57. package/dist/build-4SFAWO5Y.js.map +1 -0
  58. package/dist/build.cjs +5022 -6
  59. package/dist/build.cjs.map +1 -1
  60. package/dist/build.js +5020 -7
  61. package/dist/build.js.map +1 -1
  62. package/dist/chunk-BV5OERR3.js +11 -0
  63. package/dist/chunk-BV5OERR3.js.map +1 -0
  64. package/dist/cli/index.js +584 -51
  65. package/dist/cli/index.js.map +1 -1
  66. package/dist/eslint-plugin/index.cjs +701 -1
  67. package/dist/eslint-plugin/index.cjs.map +1 -1
  68. package/dist/eslint-plugin/index.js +701 -1
  69. package/dist/eslint-plugin/index.js.map +1 -1
  70. package/dist/evidence.cjs +59 -1
  71. package/dist/evidence.cjs.map +1 -1
  72. package/dist/evidence.js +59 -1
  73. package/dist/evidence.js.map +1 -1
  74. package/dist/helpers.cjs +379 -1
  75. package/dist/helpers.cjs.map +1 -1
  76. package/dist/helpers.js +379 -1
  77. package/dist/helpers.js.map +1 -1
  78. package/dist/index.cjs +249 -2
  79. package/dist/index.cjs.map +1 -1
  80. package/dist/index.js +249 -2
  81. package/dist/index.js.map +1 -1
  82. package/dist/node.cjs +27 -1
  83. package/dist/node.cjs.map +1 -1
  84. package/dist/node.js +27 -1
  85. package/dist/node.js.map +1 -1
  86. package/package.json +15 -11
  87. package/schemas/contract-model.schema.json +2 -1
  88. package/schemas/env-cap-report.schema.json +57 -14
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@maverickcer/env-cap",
3
- "version": "0.3.1",
3
+ "version": "0.5.0",
4
4
  "description": "Secure, type-safe, framework-agnostic environment contracts. Contracts own the environment variables they consume; the package provides runtime validation and build-time contract discovery.",
5
5
  "keywords": [
6
6
  "environment",
@@ -19,7 +19,7 @@
19
19
  "type": "git",
20
20
  "url": "git+https://github.com/MaverickCER/env-cap.git"
21
21
  },
22
- "homepage": "https://github.com/MaverickCER/env-cap#readme",
22
+ "homepage": "https://maverickcer.github.io/env-cap/",
23
23
  "bugs": {
24
24
  "url": "https://github.com/MaverickCER/env-cap/issues"
25
25
  },
@@ -27,7 +27,7 @@
27
27
  "type": "module",
28
28
  "sideEffects": false,
29
29
  "engines": {
30
- "node": ">=18.0.0"
30
+ "node": ">=20.0.0"
31
31
  },
32
32
  "exports": {
33
33
  ".": {
@@ -114,25 +114,29 @@
114
114
  "test": "vitest run",
115
115
  "test:coverage": "vitest run --coverage",
116
116
  "test:watch": "vitest",
117
- "contract": "internal-package-contract",
117
+ "contract": "npm run docs:benchmarks && internal-package-contract",
118
118
  "lint": "eslint .",
119
119
  "format": "prettier --write .",
120
120
  "format:check": "prettier --check .",
121
121
  "setup": "npm install && npm run build && npm run schema",
122
122
  "size": "node scripts/check-size.mjs",
123
123
  "verify:no-ambient-fs": "node scripts/verify-no-ambient-fs.mjs",
124
+ "verify:no-ambient-child-process": "node scripts/verify-no-ambient-child-process.mjs",
124
125
  "schema": "node scripts/generate-json-schema.mjs",
125
126
  "examples:update-golden": "node scripts/update-example-goldens.mjs",
126
127
  "benchmark": "node scripts/run-benchmarks.mjs",
127
128
  "docs:api": "typedoc",
128
129
  "docs:api:report": "typedoc --options typedoc.markdown.json",
129
130
  "docs:api:report:check": "node scripts/check-api-report.mjs",
131
+ "docs:benchmarks": "node node_modules/internal-package-contract/scripts/benchmark/render-page.mjs --out docs/benchmarks/index.html --readme https://github.com/maverickcer/env-cap/blob/main/benchmarks/README.md --history \"Runtime|benchmarks/history/runtime.json\" --history \"Build-time|benchmarks/history/buildtime.json\"",
132
+ "verify:readme-example": "node scripts/check-readme-example-fresh.mjs",
130
133
  "stage": "npm run typecheck && npm run build && npm run test && npm run size",
131
- "precommit": "npm run typecheck && npm run lint && npm run format && npm run build && npm run schema && npm run test:coverage && npm run size && npm run verify:no-ambient-fs && npm run docs:api:report:check",
132
- "verify": "npm run typecheck && npm run lint && npm run format:check && npm run build && npm run schema && npm run test:coverage && npm run size && npm run verify:no-ambient-fs && npm run docs:api:report:check",
134
+ "precommit": "npm run typecheck && npm run lint && npm run format && npm run build && npm run schema && npm run test:coverage && npm run size && npm run verify:no-ambient-fs && npm run verify:no-ambient-child-process && npm run docs:api:report:check && npm run verify:readme-example",
135
+ "verify": "npm run typecheck && npm run lint && npm run format:check && npm run build && npm run schema && npm run test:coverage && npm run size && npm run verify:no-ambient-fs && npm run verify:no-ambient-child-process && npm run docs:api:report:check && npm run verify:readme-example",
133
136
  "prepublishOnly": "npm run verify",
134
- "version": "changeset version",
135
- "release": "changeset publish"
137
+ "version": "changeset version && npm run build && npm run examples:update-golden",
138
+ "release": "changeset publish",
139
+ "benchmark:check": "node scripts/run-benchmarks.mjs --check"
136
140
  },
137
141
  "peerDependencies": {
138
142
  "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0",
@@ -152,10 +156,10 @@
152
156
  "@types/node": "^20.19.0",
153
157
  "@typescript-eslint/types": "^8.65.0",
154
158
  "@typescript-eslint/utils": "^8.65.0",
155
- "@vitest/coverage-v8": "^3.2.7",
159
+ "@vitest/coverage-v8": "^4.1.11",
156
160
  "ajv": "^8.20.0",
157
161
  "esbuild": "^0.28.1",
158
- "eslint": "^10.8.0",
162
+ "eslint": "^10.9.0",
159
163
  "eslint-config-prettier": "10.1.8",
160
164
  "globals": "^17.9.0",
161
165
  "internal-package-contract": "github:MaverickCER/internal-package-contract#main",
@@ -166,7 +170,7 @@
166
170
  "typedoc-plugin-markdown": "4.13.0",
167
171
  "typescript": "^5.0.0",
168
172
  "typescript-eslint": "^8.65.0",
169
- "vitest": "^3.2.7"
173
+ "vitest": "^4.1.11"
170
174
  },
171
175
  "overrides": {
172
176
  "esbuild": "^0.28.1",
@@ -23,7 +23,8 @@
23
23
  "schemaVersion",
24
24
  "contracts"
25
25
  ],
26
- "additionalProperties": false
26
+ "additionalProperties": false,
27
+ "description": "The versioned, JSON-serializable root of the Contract Model -- every discovered `createEnv()` contract (active or not), each with its own full statically-discoverable shape. See ContractModelContract."
27
28
  },
28
29
  "ContractModelContract": {
29
30
  "type": "object",
@@ -183,7 +183,7 @@
183
183
  "items": {
184
184
  "type": "string"
185
185
  },
186
- "description": "Every file declaring a conflicting definition."
186
+ "description": "Every file declaring a conflicting definition. A pairwise comparison (compatibility.ts, exclusive-group.ts) always produces exactly two; a finding escalated from another family (generate-env-artifacts.ts's `escalatedFindings()`, via `findingFiles()`) can produce zero, one, or two, depending on what location information that finding actually carries -- genuinely variable arity, not a tuple."
187
187
  },
188
188
  "reason": {
189
189
  "type": "string",
@@ -1053,7 +1053,7 @@
1053
1053
  "line"
1054
1054
  ],
1055
1055
  "additionalProperties": false,
1056
- "description": "One developer-declared runtime.VariableDocs.dynamicAccess citation's current acknowledgment state -- a claim, never an observation. Kept fully separate from `VariableAccessStatus` (which stays exactly 3-valued and purely AST-derived) so a developer's assertion can never make env-cap claim it observed something it didn't. See `evidence-snapshot.ts`'s `computeDynamicAccessAcknowledgments()` (where this is computed) and ADR 0037."
1056
+ "description": "One developer-declared runtime.VariableEvidenceDocs.dynamicAccess citation's current acknowledgment state -- a claim, never an observation. Kept fully separate from `VariableAccessStatus` (which stays exactly 3-valued and purely AST-derived) so a developer's assertion can never make env-cap claim it observed something it didn't. See `evidence-snapshot.ts`'s `computeDynamicAccessAcknowledgments()` (where this is computed) and ADR 0037."
1057
1057
  },
1058
1058
  "ScannedSurface": {
1059
1059
  "type": "object",
@@ -1183,7 +1183,8 @@
1183
1183
  "schemaVersion",
1184
1184
  "contracts"
1185
1185
  ],
1186
- "additionalProperties": false
1186
+ "additionalProperties": false,
1187
+ "description": "The versioned, JSON-serializable root of the Contract Model -- every discovered `createEnv()` contract (active or not), each with its own full statically-discoverable shape. See ContractModelContract."
1187
1188
  },
1188
1189
  "ContractModelContract": {
1189
1190
  "type": "object",
@@ -1480,7 +1481,8 @@
1480
1481
  "warnings",
1481
1482
  "scannedSurfaces"
1482
1483
  ],
1483
- "additionalProperties": false
1484
+ "additionalProperties": false,
1485
+ "description": "The versioned, JSON-serializable root of the Dependency Model -- see this module's own doc comment for the full picture."
1484
1486
  },
1485
1487
  "DependencyModelContract": {
1486
1488
  "type": "object",
@@ -1540,7 +1542,8 @@
1540
1542
  "ambiguousBarrelFiles",
1541
1543
  "dynamicAccessSites"
1542
1544
  ],
1543
- "additionalProperties": false
1545
+ "additionalProperties": false,
1546
+ "description": "One contract's dependency-ownership facts: which variables were accessed, which files consume it, and every dynamic/ambiguous access site found. See DependencyModelVariable for the per-variable breakdown."
1544
1547
  },
1545
1548
  "DependencyModelVariable": {
1546
1549
  "type": "object",
@@ -1662,7 +1665,8 @@
1662
1665
  "unownedContracts",
1663
1666
  "unownedVariables"
1664
1667
  ],
1665
- "additionalProperties": false
1668
+ "additionalProperties": false,
1669
+ "description": "The versioned, JSON-serializable root of the Ownership Model -- see this module's own doc comment for the full picture."
1666
1670
  },
1667
1671
  "OwnershipModelContract": {
1668
1672
  "type": "object",
@@ -1694,7 +1698,8 @@
1694
1698
  "contractName",
1695
1699
  "variables"
1696
1700
  ],
1697
- "additionalProperties": false
1701
+ "additionalProperties": false,
1702
+ "description": "One contract's own default owner plus every variable's effective owner. See OwnershipModelVariable for the per-variable shape."
1698
1703
  },
1699
1704
  "OwnershipModelVariable": {
1700
1705
  "type": "object",
@@ -1745,7 +1750,7 @@
1745
1750
  "properties": {
1746
1751
  "schemaVersion": {
1747
1752
  "type": "number",
1748
- "const": 2
1753
+ "const": 3
1749
1754
  },
1750
1755
  "contracts": {
1751
1756
  "type": "array",
@@ -1767,7 +1772,8 @@
1767
1772
  "contracts",
1768
1773
  "expiring"
1769
1774
  ],
1770
- "additionalProperties": false
1775
+ "additionalProperties": false,
1776
+ "description": "The versioned, JSON-serializable root of the Lifecycle Model -- see this module's own doc comment for the full picture."
1771
1777
  },
1772
1778
  "LifecycleModelContract": {
1773
1779
  "type": "object",
@@ -1800,7 +1806,7 @@
1800
1806
  "items": {
1801
1807
  "$ref": "#/definitions/LifecycleModelVariable"
1802
1808
  },
1803
- "description": "Only variables with at least one lifecycle field set (`expiresAt`, `refreshInstructions`, `deprecated`, `removeBy`, `renamedFrom`, `retention`) -- same \"only what's relevant\" scope `renderLifecycleReport()` already uses for its rows."
1809
+ "description": "Only variables with at least one lifecycle field set (`expiresAt`, `refreshInstructions`, `deprecated`, `removeBy`, `renamedFrom`, `retention`, `authenticatorType`, `rotationPeriod`, `lastRotatedAt`, `rotationTriggerEvents`) -- same \"only what's relevant\" scope `renderLifecycleReport()` already uses for its rows."
1804
1810
  }
1805
1811
  },
1806
1812
  "required": [
@@ -1809,7 +1815,8 @@
1809
1815
  "contractName",
1810
1816
  "variables"
1811
1817
  ],
1812
- "additionalProperties": false
1818
+ "additionalProperties": false,
1819
+ "description": "One contract's own lifecycle data plus every variable of its that has at least one lifecycle field set. See LifecycleModelVariable for the per-variable shape."
1813
1820
  },
1814
1821
  "LifecycleModelVariable": {
1815
1822
  "type": "object",
@@ -1839,14 +1846,48 @@
1839
1846
  "retention": {
1840
1847
  "type": "string",
1841
1848
  "description": "Descriptive retention policy (e.g. \"delete after 90 days\") -- a policy statement, never computed or parsed, deliberately independent of `expiresAt`'s actual temporal constraint. See ADR 0035."
1849
+ },
1850
+ "authenticatorType": {
1851
+ "type": "string",
1852
+ "description": "See runtime.VariableDocs.authenticatorType."
1853
+ },
1854
+ "rotationPeriod": {
1855
+ "type": "string",
1856
+ "description": "See runtime.VariableDocs.rotationPeriod."
1857
+ },
1858
+ "lastRotatedAt": {
1859
+ "type": "string",
1860
+ "description": "See runtime.VariableDocs.lastRotatedAt."
1861
+ },
1862
+ "rotationTriggerEvents": {
1863
+ "type": "array",
1864
+ "items": {
1865
+ "type": "string"
1866
+ },
1867
+ "description": "See runtime.VariableDocs.rotationTriggerEvents."
1868
+ },
1869
+ "rotationStatus": {
1870
+ "$ref": "#/definitions/RotationComplianceStatus",
1871
+ "description": "Computed, not stored -- see RotationComplianceStatus and `computeRotationStatus()`."
1842
1872
  }
1843
1873
  },
1844
1874
  "required": [
1845
- "key"
1875
+ "key",
1876
+ "rotationStatus"
1846
1877
  ],
1847
1878
  "additionalProperties": false,
1848
1879
  "description": "One variable's lifecycle data (expiry, deprecation, rename correlation)."
1849
1880
  },
1881
+ "RotationComplianceStatus": {
1882
+ "type": "string",
1883
+ "enum": [
1884
+ "compliant",
1885
+ "overdue",
1886
+ "expired",
1887
+ "undeclared"
1888
+ ],
1889
+ "description": "One variable's computed NIST SP 800-53 IA-5 rotation-compliance status -- see `computeRotationStatus()` for exactly how it's derived. Always present on a `LifecycleModelVariable` (never `undefined`) since a variable with literally nothing lifecycle-relevant set never reaches this model at all (`hasLifecycleData()` below) -- `\"undeclared\"` is itself the honest value for \"reached this model for some other lifecycle reason (e.g. `deprecated`) but declares none of the four rotation-specific fields.\""
1890
+ },
1850
1891
  "FindingModel": {
1851
1892
  "type": "object",
1852
1893
  "properties": {
@@ -1865,7 +1906,8 @@
1865
1906
  "schemaVersion",
1866
1907
  "findings"
1867
1908
  ],
1868
- "additionalProperties": false
1909
+ "additionalProperties": false,
1910
+ "description": "The versioned, JSON-serializable root of the Finding Model -- every rule violation and derived risk signal from this run, unified behind Finding 's one shape. See this module's own doc comment for the full picture."
1869
1911
  },
1870
1912
  "Finding": {
1871
1913
  "type": "object",
@@ -2105,7 +2147,8 @@
2105
2147
  "manifest",
2106
2148
  "renamedVariables"
2107
2149
  ],
2108
- "additionalProperties": false
2150
+ "additionalProperties": false,
2151
+ "description": "The versioned, JSON-serializable root of the Change Model -- what changed since the last persisted evidence snapshot. See this module's own doc comment for the full picture."
2109
2152
  },
2110
2153
  "ManifestChangeReport": {
2111
2154
  "type": "object",