@maverickcer/env-cap 0.2.0

package/package.json

@@ -0,0 +1,183 @@
+{
+  "name": "@maverickcer/env-cap",
+  "version": "0.2.0",
+  "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.",
+  "keywords": [
+    "environment",
+    "env",
+    "config",
+    "configuration",
+    "documentation",
+    "validation",
+    "typescript",
+    "schema",
+    "secrets",
+    "dotenv"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maverickcer/env-cap.git"
+  },
+  "homepage": "https://github.com/maverickcer/env-cap#readme",
+  "bugs": {
+    "url": "https://github.com/maverickcer/env-cap/issues"
+  },
+  "author": "MaverickCER",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./build": {
+      "import": {
+        "types": "./dist/build.d.ts",
+        "default": "./dist/build.js"
+      },
+      "require": {
+        "types": "./dist/build.d.cts",
+        "default": "./dist/build.cjs"
+      }
+    },
+    "./helpers": {
+      "import": {
+        "types": "./dist/helpers.d.ts",
+        "default": "./dist/helpers.js"
+      },
+      "require": {
+        "types": "./dist/helpers.d.cts",
+        "default": "./dist/helpers.cjs"
+      }
+    },
+    "./node": {
+      "import": {
+        "types": "./dist/node.d.ts",
+        "default": "./dist/node.js"
+      },
+      "require": {
+        "types": "./dist/node.d.cts",
+        "default": "./dist/node.cjs"
+      }
+    },
+    "./evidence": {
+      "import": {
+        "types": "./dist/evidence.d.ts",
+        "default": "./dist/evidence.js"
+      },
+      "require": {
+        "types": "./dist/evidence.d.cts",
+        "default": "./dist/evidence.cjs"
+      }
+    },
+    "./eslint-plugin": {
+      "import": {
+        "types": "./dist/eslint-plugin/index.d.ts",
+        "default": "./dist/eslint-plugin/index.js"
+      },
+      "require": {
+        "types": "./dist/eslint-plugin/index.d.cts",
+        "default": "./dist/eslint-plugin/index.cjs"
+      }
+    },
+    "./schema": "./schemas/env-cap-report.schema.json",
+    "./schema/*": "./schemas/*.schema.json",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "env-cap": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json && node scripts/emit-dts-shims.mjs && node scripts/fix-eslint-plugin-cjs-interop.mjs",
+    "prepare": "npm run build",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "contract": "internal-package-contract",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "setup": "npm install && npm run build && npm run schema",
+    "size": "node scripts/check-size.mjs",
+    "verify:no-ambient-fs": "node scripts/verify-no-ambient-fs.mjs",
+    "schema": "node scripts/generate-json-schema.mjs",
+    "examples:update-golden": "node scripts/update-example-goldens.mjs",
+    "benchmark": "node scripts/run-benchmarks.mjs",
+    "docs:api": "typedoc",
+    "docs:api:report": "typedoc --options typedoc.markdown.json",
+    "docs:api:report:check": "node scripts/check-api-report.mjs",
+    "stage": "npm run typecheck && npm run build && npm run test && npm run size",
+    "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",
+    "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",
+    "prepublishOnly": "npm run verify",
+    "version": "changeset version",
+    "release": "changeset publish"
+  },
+  "peerDependencies": {
+    "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    },
+    "eslint": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.31.1",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^18.0.0",
+    "@typescript-eslint/types": "^8.65.0",
+    "@typescript-eslint/utils": "^8.65.0",
+    "@vitest/coverage-v8": "^3.2.7",
+    "ajv": "^8.20.0",
+    "esbuild": "^0.28.1",
+    "eslint": "^10.8.0",
+    "eslint-config-prettier": "10.1.8",
+    "globals": "^17.9.0",
+    "internal-package-contract": "git+https://github.com/MaverickCER/internal-package-contract.git#main",
+    "prettier": "3.9.6",
+    "ts-json-schema-generator": "^2.9.0",
+    "tsup": "^8.0.0",
+    "typedoc": "^0.28.20",
+    "typedoc-plugin-markdown": "4.13.0",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.65.0",
+    "vitest": "^3.2.7"
+  },
+  "overrides": {
+    "esbuild": "^0.28.1",
+    "fast-uri": "^3.1.6",
+    "nanoid": "^3.3.18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "allowScripts": {
+    "esbuild@0.28.1": true,
+    "fsevents@2.3.3": true
+  }
+}

package/schemas/contract-model.schema.json

@@ -0,0 +1,321 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://maverickcer.github.io/env-cap/schema/contract-model.schema.json",
+  "title": "env-cap Contract Model",
+  "description": "Canonical, versioned projection of every declared environment-variable contract, active or not (see ADR 0024, ADR 0025). Generated from src/build/contract-model.ts's ContractModel type -- never hand-authored.",
+  "$ref": "#/definitions/ContractModel",
+  "definitions": {
+    "ContractModel": {
+      "type": "object",
+      "properties": {
+        "schemaVersion": {
+          "type": "number",
+          "const": 3
+        },
+        "contracts": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/ContractModelContract"
+          }
+        }
+      },
+      "required": [
+        "schemaVersion",
+        "contracts"
+      ],
+      "additionalProperties": false
+    },
+    "ContractModelContract": {
+      "type": "object",
+      "properties": {
+        "owner": {
+          "type": "string"
+        },
+        "sensitivity": {
+          "type": "string"
+        },
+        "expiresAt": {
+          "type": "string"
+        },
+        "purpose": {
+          "type": "string"
+        },
+        "legalBasis": {
+          "type": "string"
+        },
+        "retention": {
+          "type": "string"
+        },
+        "dataResidency": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ]
+        },
+        "auditRequired": {
+          "type": "boolean"
+        },
+        "metadata": {
+          "type": "object",
+          "additionalProperties": {}
+        },
+        "file": {
+          "type": "string",
+          "description": "Root-relative, POSIX-separated -- matches `DiscoveredContractSummary.file`."
+        },
+        "exportName": {
+          "type": "string"
+        },
+        "contractName": {
+          "type": "string"
+        },
+        "active": {
+          "type": "boolean"
+        },
+        "category": {
+          "type": "string"
+        },
+        "exclusiveGroup": {
+          "type": "string"
+        },
+        "variables": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/ContractModelVariable"
+          }
+        },
+        "documented": {
+          "type": "boolean"
+        },
+        "packageOrigin": {
+          "$ref": "#/definitions/PackageOrigin"
+        },
+        "declaration": {
+          "$ref": "#/definitions/SourcePosition",
+          "description": "Where this contract's `createEnv(...)` call is declared. Always present. See ADR 0036."
+        },
+        "documentation": {
+          "$ref": "#/definitions/SourcePosition",
+          "description": "Where this contract's `documentEnv(...)` call is declared, if one exists. See ADR 0036."
+        }
+      },
+      "required": [
+        "file",
+        "exportName",
+        "contractName",
+        "active",
+        "variables",
+        "documented",
+        "declaration"
+      ],
+      "additionalProperties": false,
+      "description": "One `createEnv()` contract's full statically-discoverable contract, active or not."
+    },
+    "ContractModelVariable": {
+      "type": "object",
+      "properties": {
+        "owner": {
+          "type": "string"
+        },
+        "sensitivity": {
+          "type": "string"
+        },
+        "expiresAt": {
+          "type": "string"
+        },
+        "purpose": {
+          "type": "string"
+        },
+        "legalBasis": {
+          "type": "string"
+        },
+        "retention": {
+          "type": "string"
+        },
+        "dataResidency": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ]
+        },
+        "auditRequired": {
+          "type": "boolean"
+        },
+        "metadata": {
+          "type": "object",
+          "additionalProperties": {}
+        },
+        "key": {
+          "type": "string"
+        },
+        "hasDefault": {
+          "type": "boolean"
+        },
+        "defaultValue": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "ok": {
+                  "type": "boolean",
+                  "const": true
+                },
+                "value": {}
+              },
+              "required": [
+                "ok",
+                "value"
+              ],
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "ok": {
+                  "type": "boolean",
+                  "const": false
+                }
+              },
+              "required": [
+                "ok"
+              ],
+              "additionalProperties": false
+            }
+          ]
+        },
+        "hasProcessor": {
+          "type": "boolean"
+        },
+        "processorSource": {
+          "type": "string"
+        },
+        "processorReturnType": {
+          "type": "string"
+        },
+        "hasValidator": {
+          "type": "boolean"
+        },
+        "validatorSource": {
+          "type": "string"
+        },
+        "context": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "refreshInstructions": {
+          "type": "string"
+        },
+        "setupInstructions": {
+          "type": "string"
+        },
+        "required": {
+          "type": "boolean"
+        },
+        "documented": {
+          "type": "boolean"
+        },
+        "evidence": {
+          "$ref": "#/definitions/DiscoveredVariableEvidence",
+          "description": "The `evidence` sub-object from this variable's linked documentation -- re-verified every run, unlike every declared-only field above. See runtime.VariableEvidenceDocs and ADR 0037."
+        },
+        "declaration": {
+          "$ref": "#/definitions/SourcePosition",
+          "description": "Where this variable's own schema property is declared. See ADR 0036."
+        }
+      },
+      "required": [
+        "key",
+        "hasDefault",
+        "hasProcessor",
+        "hasValidator",
+        "documented",
+        "declaration"
+      ],
+      "additionalProperties": false,
+      "description": "One variable's full statically-discoverable contract: schema-shaped facts plus linked documentation."
+    },
+    "DiscoveredVariableEvidence": {
+      "type": "object",
+      "properties": {
+        "dynamicAccess": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Well-formed `\"path:line:column\"` entries from `evidence.dynamicAccess`, if set to an array of string literals -- a malformed entry warns and is dropped, never included here. See ADR 0037."
+        }
+      },
+      "additionalProperties": false,
+      "description": "The statically-extracted contents of one variable's `evidence` sub-object. See runtime.VariableEvidenceDocs."
+    },
+    "SourcePosition": {
+      "type": "object",
+      "properties": {
+        "file": {
+          "type": "string",
+          "description": "Root-relative, POSIX-separated."
+        },
+        "line": {
+          "type": "number",
+          "description": "1-indexed line number."
+        },
+        "column": {
+          "type": "number",
+          "description": "1-indexed column number."
+        }
+      },
+      "required": [
+        "file",
+        "line",
+        "column"
+      ],
+      "additionalProperties": false,
+      "description": "A precise pointer into a source file -- the shared shape every exact-position fact in the build pipeline (declaration sites, usage sites, dynamic-access sites) uses, so a consumer never has to reconcile three ad hoc `{ file; line; column }` shapes that happen to mean the same thing. See ADR 0036."
+    },
+    "PackageOrigin": {
+      "type": "object",
+      "properties": {
+        "packageName": {
+          "type": "string",
+          "description": "The allow-listed package name that declared this schema."
+        },
+        "declaredField": {
+          "type": "string",
+          "description": "The `\"envCap.schema\"` value exactly as the package author wrote it."
+        },
+        "resolvedFile": {
+          "type": "string",
+          "description": "Absolute, realpath-canonicalized path to the resolved schema file."
+        },
+        "packageDir": {
+          "type": "string",
+          "description": "Absolute, realpath-canonicalized path to the package's own directory."
+        }
+      },
+      "required": [
+        "packageName",
+        "declaredField",
+        "resolvedFile",
+        "packageDir"
+      ],
+      "additionalProperties": false,
+      "description": "Both the authored and resolved forms are kept -- diagnostics benefit from showing exactly what a package author wrote versus what it resolved to."
+    }
+  }
+}