@xlameiro/env-typegen 0.1.2 → 0.1.3

package/dist/index.d.cts

@@ -28,6 +28,20 @@ type ParsedEnvVar = {
     group?: string;
     /** 1-based line number of the KEY=VALUE line in the source file */
     lineNumber: number;
+    /** Allowed literal values from a `@enum` annotation (e.g. `["development", "staging", "production"]`). */
+    enumValues?: string[];
+    /** Numeric range constraints from `@min` / `@max` annotations. */
+    constraints?: {
+        min?: number;
+        max?: number;
+    };
+    /** Runtime scope from a `@runtime` annotation (`server` | `client` | `edge`). */
+    runtime?: "server" | "client" | "edge";
+    /**
+     * When true, the variable's value must never appear in reports or generated
+     * output — declared via a `@secret` annotation.
+     */
+    isSecret?: boolean;
 };
 /**
  * The complete result of parsing a single .env.example file.
@@ -61,6 +75,17 @@ type CommentAnnotations = {
     description?: string;
     /** true when the `@required` annotation is present in the comment block */
     isRequired: boolean;
+    /** Allowed literal values from a `@enum` annotation (comma-separated list) */
+    enumValues?: string[];
+    /** Numeric range constraints from `@min` and/or `@max` annotations */
+    constraints?: {
+        min?: number;
+        max?: number;
+    };
+    /** Runtime scope from a `@runtime` annotation (`server` | `client` | `edge`) */
+    runtime?: "server" | "client" | "edge";
+    /** true when the `@secret` annotation is present — value must never appear in reports */
+    isSecret?: boolean;
 };
 /**
  * Parse a block of consecutive comment lines (each starting with `#`) and
@@ -71,6 +96,11 @@ type CommentAnnotations = {
  * - `@required`           — marks the variable as required regardless of value
  * - `@optional`           — informational (isRequired stays false)
  * - `@type <EnvVarType>`  — overrides the inferred type
+ * - `@enum val1,val2,...` — declares allowed literal values (comma-separated)
+ * - `@min <number>`       — declares a numeric minimum constraint
+ * - `@max <number>`       — declares a numeric maximum constraint
+ * - `@runtime <scope>`    — declares runtime scope: `server` | `client` | `edge`
+ * - `@secret`             — marks the value as sensitive (never logged or reported)
  *
  * Non-annotation comment lines act as a fallback description when no
  * `@description` annotation is present (first non-empty line wins).
@@ -235,6 +265,337 @@ declare function generateDeclaration(parsed: ParsedEnvFile): string;
  */
 declare function generateT3Env(parsed: ParsedEnvFile): string;
 
+/**
+ * Machine-readable CI contract types for env-typegen V1 JSON output.
+ *
+ * Stable JSON schema emitted by `env-typegen check --json` and consumed by
+ * CI pipelines, dashboards, and automation tools.
+ *
+ * Property order on {@link CiReport} is intentional and stable:
+ * `schemaVersion` → `status` → `summary` → `issues` → `meta`
+ *
+ * @module
+ */
+/**
+ * Stable machine-readable issue category code.
+ * Used in {@link Issue.code} to enable programmatic filtering and alerting.
+ *
+ * - `ENV_MISSING`        — a required variable is absent from the env file
+ * - `ENV_EXTRA`          — a variable exists in the env file but not in the contract
+ * - `ENV_INVALID_TYPE`   — the value cannot be coerced to the declared type
+ * - `ENV_INVALID_VALUE`  — the value fails a constraint (enum, min, max)
+ * - `ENV_CONFLICT`       — the variable has inconsistent values across environments
+ * - `ENV_SECRET_EXPOSED` — a secret variable has a non-empty value in a public file
+ *
+ * @public
+ */
+type IssueCode$1 = "ENV_MISSING" | "ENV_EXTRA" | "ENV_INVALID_TYPE" | "ENV_INVALID_VALUE" | "ENV_CONFLICT" | "ENV_SECRET_EXPOSED";
+/**
+ * The expected shape of an environment variable, expressed as a discriminated
+ * union on `type`. Used in {@link Issue.expected} to communicate the declared
+ * expectation when a validation failure occurs.
+ *
+ * @public
+ */
+type Expected$1 = {
+    type: "string";
+} | {
+    type: "number";
+    min?: number;
+    max?: number;
+} | {
+    type: "boolean";
+} | {
+    type: "enum";
+    values: string[];
+} | {
+    type: "url";
+} | {
+    type: "email";
+} | {
+    type: "json";
+} | {
+    type: "semver";
+} | {
+    type: "unknown";
+};
+/**
+ * Deployment environment against which a check was run.
+ *
+ * @public
+ */
+type Environment = "local" | "example" | "production" | "preview" | "test" | "cloud";
+/**
+ * Whether a validation issue is blocking (`error`) or advisory (`warning`).
+ *
+ * @public
+ */
+type IssueSeverity$1 = "error" | "warning";
+/**
+ * Overall check result: `"ok"` when no errors; `"fail"` when at least one
+ * error-severity issue exists.
+ *
+ * @public
+ */
+type ReportStatus = "ok" | "fail";
+/**
+ * A single validation issue found during `env-typegen check`.
+ *
+ * @public
+ */
+type Issue = {
+    /** Stable machine-readable category code. Use this for programmatic filtering. */
+    code: IssueCode$1;
+    /** Human-readable description of the issue category (maps 1-to-1 with `code`). */
+    type: string;
+    /** The environment variable key that caused the issue. */
+    key: string;
+    /** What the contract declared was expected for this variable. */
+    expected: Expected$1;
+    /** The raw received value when applicable and not a secret. Absent otherwise. */
+    received?: string;
+    /** The environment context where this issue was detected. */
+    environment: Environment;
+    /** Whether this issue blocks deployment (`error`) or is advisory (`warning`). */
+    severity: IssueSeverity$1;
+    /**
+     * Always `null` in V1 JSON output.
+     *
+     * Prevents accidental secret exposure in machine-readable reports stored in
+     * CI artefacts, logs, or dashboards. Use `--debug-values` for human-readable
+     * output that shows the actual value for non-secret variables.
+     */
+    value: null;
+};
+/**
+ * Top-level V1 JSON report emitted by `env-typegen check --json`.
+ *
+ * The property order is stable and intentional:
+ * `schemaVersion` → `status` → `summary` → `issues` → `meta`
+ *
+ * When `schemaVersion` is incremented, it indicates a breaking change to this
+ * type shape. Consumers should guard on `schemaVersion === 1` before reading.
+ *
+ * @public
+ */
+type CiReport = {
+    /** Integer schema version. Incremented on breaking changes to this type shape. */
+    schemaVersion: 1;
+    /** `"ok"` when no errors were found; `"fail"` when at least one error-severity issue exists. */
+    status: ReportStatus;
+    /** Issue counts by severity. */
+    summary: {
+        errors: number;
+        warnings: number;
+    };
+    /** All issues found during the check, in source order. */
+    issues: Issue[];
+    /** Execution context: which env file was checked and when. */
+    meta: {
+        env: string;
+        timestamp: string;
+    };
+};
+
+/**
+ * Runtime scope for an environment variable.
+ * Controls which part of the application has access to the variable.
+ *
+ * - `"server"` — accessible only in server-side code (Node.js process)
+ * - `"client"` — accessible in browser code (must be safe to expose publicly)
+ * - `"edge"`   — accessible in Edge runtime (limited Node.js API surface)
+ *
+ * @public
+ */
+type EnvVarRuntime = "server" | "client" | "edge";
+/**
+ * A single entry in the env contract: the canonical, authoritative declaration
+ * for one environment variable.
+ *
+ * In contract-first mode (`schemaMode: "contract-first"`) this is the source of
+ * truth. The inference engine acts only as a fallback when no contract entry
+ * exists for a given variable.
+ *
+ * @public
+ */
+type EnvContractEntry = {
+    /** The environment variable name as it appears in the env file (e.g. `DATABASE_URL`). */
+    name: string;
+    /** The expected TypeScript type for this variable's runtime value. */
+    expectedType: EnvVarType;
+    /** Whether this variable must be present. Overrides inference-based required detection. */
+    required: boolean;
+    /** Static default value used when the variable is absent from the env file. */
+    default?: string;
+    /** Allowed literal values for `enum`-typed variables (e.g. `["development", "staging", "production"]`). */
+    enumValues?: string[];
+    /** Numeric range constraints for `number`-typed variables. */
+    constraints?: {
+        min?: number;
+        max?: number;
+    };
+    /** Which runtime this variable is available to. Used to enforce NEXT_PUBLIC_ boundaries. */
+    runtime?: EnvVarRuntime;
+    /**
+     * When true, the variable's value is never included in reports, logs, or
+     * generated type file comments — it is treated as a secret.
+     */
+    isSecret?: boolean;
+    /** Human-readable description used in documentation generation and error messages. */
+    description?: string;
+};
+/**
+ * The full environment contract — a collection of all declared variables
+ * and their expected shape.
+ *
+ * Used as the source of truth in contract-first mode (`schemaMode: "contract-first"`).
+ * Create a contract file at `env.contract.ts` and define this with {@link defineContract}
+ * from the schema loader for type safety.
+ *
+ * @public
+ */
+type EnvContract$1 = {
+    /** All declared environment variable contracts, in declaration order. */
+    vars: EnvContractEntry[];
+};
+
+/**
+ * Contract file names searched in order when calling {@link loadContract}.
+ * Mirrors the search strategy used by `loadConfig` in `config.ts`.
+ */
+declare const CONTRACT_FILE_NAMES: readonly ["env.contract.ts", "env.contract.mjs", "env.contract.js"];
+/**
+ * Type-safe contract factory. Returns the contract object unchanged — exists
+ * purely for IDE autocompletion and compile-time validation of the contract shape.
+ *
+ * Use this in your `env.contract.ts` file:
+ *
+ * @example
+ * ```ts
+ * // env.contract.ts
+ * import { defineContract } from "@xlameiro/env-typegen";
+ *
+ * export default defineContract({
+ *   vars: [
+ *     { name: "DATABASE_URL", expectedType: "url", required: true, isSecret: true },
+ *     { name: "PORT", expectedType: "number", required: false, default: "3000" },
+ *     {
+ *       name: "NODE_ENV",
+ *       expectedType: "string",
+ *       required: true,
+ *       enumValues: ["development", "staging", "production"],
+ *     },
+ *   ],
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function defineContract(contract: EnvContract$1): EnvContract$1;
+/**
+ * Loads an env contract by searching for a contract file starting from `cwd`.
+ *
+ * Search order: `env.contract.ts` → `env.contract.mjs` → `env.contract.js`
+ *
+ * Returns `undefined` when no contract file is found. The contract file must
+ * use a default export of an {@link EnvContract} object, typically produced
+ * by {@link defineContract}.
+ *
+ * @param cwd - Directory to start searching from. Defaults to `process.cwd()`.
+ *
+ * @public
+ */
+declare function loadContract(cwd?: string): Promise<EnvContract$1 | undefined>;
+
+type Expected = {
+    type: "string";
+} | {
+    type: "number";
+    min?: number;
+    max?: number;
+} | {
+    type: "boolean";
+} | {
+    type: "enum";
+    values: string[];
+} | {
+    type: "url";
+} | {
+    type: "email";
+} | {
+    type: "json";
+} | {
+    type: "semver";
+} | {
+    type: "unknown";
+};
+type EnvContractVariable = {
+    expected: Expected;
+    required: boolean;
+    clientSide: boolean;
+    description?: string;
+    secret?: boolean;
+};
+type EnvContract = {
+    schemaVersion: 1;
+    variables: Record<string, EnvContractVariable>;
+};
+type IssueCode = "ENV_MISSING" | "ENV_EXTRA" | "ENV_INVALID_TYPE" | "ENV_INVALID_VALUE" | "ENV_CONFLICT" | "ENV_SECRET_EXPOSED";
+type IssueType = "missing" | "extra" | "invalid_type" | "invalid_value" | "conflict" | "secret_exposed";
+type IssueSeverity = "error" | "warning";
+type ValidationIssue$1 = {
+    code: IssueCode;
+    type: IssueType;
+    severity: IssueSeverity;
+    key: string;
+    environment: string;
+    message: string;
+    expected?: Expected;
+    receivedType?: string;
+    value: string | null;
+};
+type ValidationSummary = {
+    errors: number;
+    warnings: number;
+    total: number;
+};
+type ValidationStatus = "ok" | "fail";
+type ValidationMeta = {
+    env: string;
+    timestamp: string;
+};
+type ValidationReport = {
+    schemaVersion: 1;
+    status: ValidationStatus;
+    summary: ValidationSummary;
+    issues: ValidationIssue$1[];
+    meta: ValidationMeta;
+    recommendations?: string[];
+};
+
+type EnvTypegenPlugin = {
+    name: string;
+    transformContract?: (contract: EnvContract) => EnvContract;
+    transformSource?: (input: {
+        environment: string;
+        values: Record<string, string>;
+    }) => Record<string, string>;
+    transformReport?: (report: ValidationReport) => ValidationReport;
+};
+type PluginReference = string | EnvTypegenPlugin;
+type LoadPluginsOptions = {
+    pluginPaths: string[];
+    configPlugins?: PluginReference[];
+    cwd?: string;
+};
+declare function loadPlugins(options: LoadPluginsOptions): Promise<EnvTypegenPlugin[]>;
+declare function applyContractPlugins(contract: EnvContract, plugins: readonly EnvTypegenPlugin[]): EnvContract;
+declare function applySourcePlugins(params: {
+    environment: string;
+    values: Record<string, string>;
+}, plugins: readonly EnvTypegenPlugin[]): Record<string, string>;
+declare function applyReportPlugins(report: ValidationReport, plugins: readonly EnvTypegenPlugin[]): ValidationReport;
+
 /** Generator identifiers supported by env-typegen. */
 type GeneratorName = "typescript" | "zod" | "t3" | "declaration";
 /** Configuration shape accepted by env-typegen's CLI and programmatic API. */
@@ -252,6 +613,27 @@ type EnvTypegenConfig = {
      * Rules are matched in ascending priority order; lower numbers win.
      */
     inferenceRules?: InferenceRule[];
+    /**
+     * Path to the contract file (`env.contract.ts`).
+     * When provided, the contract is the authoritative source of type information.
+     * Relative to the config file directory or `process.cwd()`.
+     */
+    schemaFile?: string;
+    /**
+     * When `true`, variables absent from the contract emit errors rather than warnings.
+     * Defaults to `true`.
+     */
+    strict?: boolean;
+    /**
+     * Resolution strategy for type information.
+     * - `"legacy"` (default): inference-first; annotations override inferred types.
+     * - `"contract-first"`: contract is authoritative; inference is a fallback only.
+     */
+    schemaMode?: "legacy" | "contract-first";
+    /** Default target files for `env-typegen diff` when --targets is omitted. */
+    diffTargets?: string[];
+    /** Plugin references (module paths or plugin objects). */
+    plugins?: PluginReference[];
 };
 /**
  * Type-safe config helper.
@@ -286,4 +668,158 @@ type RunGenerateOptions = {
  */
 declare function runGenerate(options: RunGenerateOptions): Promise<void>;
 
-export { type CommentAnnotations, type EnvTypegenConfig, type EnvVarType, type GeneratorName, type InferenceRule, type ParsedEnvFile, type ParsedEnvVar, type RunGenerateOptions, defineConfig, generateDeclaration, generateEnvValidation, generateT3Env, generateTypeScriptTypes, generateZodSchema, inferType, inferTypesFromParsedVars as inferTypes, inferenceRules, loadConfig, parseCommentBlock, parseEnvFile, parseEnvFileContent, runGenerate };
+/**
+ * Options controlling how `validateContract` handles edge cases.
+ *
+ * @internal
+ */
+type ValidateContractOptions = {
+    /**
+     * The deployment environment under validation.
+     * Defaults to `"local"` when not specified.
+     */
+    environment?: Environment;
+    /**
+     * When true, variables not declared in the contract are treated as errors
+     * instead of warnings. Matches the `strict` option in `EnvTypegenConfig`.
+     *
+     * Defaults to `true` (strict by default in V1).
+     */
+    strict?: boolean;
+};
+/**
+ * A single found validation issue, as produced by the validator engine.
+ * Used internally before being converted to a {@link CiReport} via the reporter.
+ *
+ * @internal
+ */
+type ValidationIssue = {
+    code: IssueCode$1;
+    key: string;
+    expected: Expected$1;
+    received?: string;
+    environment: Environment;
+    severity: IssueSeverity$1;
+};
+/**
+ * The full result of running `validateContract` against a parsed env file.
+ *
+ * @internal
+ */
+type ValidationResult = {
+    issues: ValidationIssue[];
+};
+
+/**
+ * Validate a parsed env file against a contract definition.
+ *
+ * Produces a {@link ValidationResult} containing all discovered issues.
+ * Does not throw — every problem becomes a typed {@link ValidationIssue}.
+ *
+ * Issue codes checked:
+ * - `ENV_MISSING`        — required contract var absent from env file
+ * - `ENV_EXTRA`          — env file var not declared in contract
+ * - `ENV_INVALID_TYPE`   — value cannot be coerced to declared type
+ * - `ENV_INVALID_VALUE`  — enum or min/max constraint violated
+ * - `ENV_SECRET_EXPOSED` — secret var has non-empty value in env file
+ *
+ * Note: `ENV_CONFLICT` is not emitted in V1 (requires multi-file comparison
+ * which belongs to the `diff` command, Phase 4).
+ *
+ * @param parsed   — result of `parseEnvFile` for the env file under check
+ * @param contract — the authoritative contract to validate against
+ * @param opts     — optional check configuration (environment, strict mode)
+ * @returns        — `{ issues: ValidationIssue[] }` — empty when all checks pass
+ *
+ * @public
+ */
+declare function validateContract(parsed: ParsedEnvFile, contract: EnvContract$1, opts?: ValidateContractOptions): ValidationResult;
+
+/**
+ * Build and format the V1 JSON report for `env-typegen check --json`.
+ *
+ * @module
+ */
+
+/**
+ * Options for {@link formatCiReport}.
+ *
+ * @public
+ */
+type FormatCiReportOptions = {
+    /** When `true`, the output is pretty-printed with 2-space indentation. */
+    pretty?: boolean;
+};
+/**
+ * Convert a {@link ValidationResult} into a stable V1 {@link CiReport}.
+ *
+ * The returned object's property order is canonical:
+ * `schemaVersion` → `status` → `summary` → `issues` → `meta`
+ *
+ * @public
+ */
+declare function buildCiReport(result: ValidationResult, meta: {
+    env: string;
+    timestamp: string;
+}): CiReport;
+/**
+ * Serialise a {@link CiReport} to JSON.
+ *
+ * @param report   The report produced by {@link buildCiReport}.
+ * @param opts     Optional formatting options.
+ * @returns        JSON string. Compact by default; pretty-printed when `opts.pretty === true`.
+ *
+ * @public
+ */
+declare function formatCiReport(report: CiReport, opts?: FormatCiReportOptions): string;
+
+/**
+ * Options for {@link runCheck}.
+ *
+ * @public
+ */
+type RunCheckOptions = {
+    /** Path to the env file to validate (e.g. `.env.local`). */
+    input: string;
+    /** Explicit path to the contract file. Relative to `cwd` when set. */
+    contract?: string;
+    /** Working directory for contract auto-discovery. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Environment label attached to validation issues. */
+    environment?: Environment;
+    /**
+     * When `true` (default), undeclared variables are treated as errors.
+     * When `false`, they become warnings.
+     */
+    strict?: boolean;
+    /** Emit machine-readable JSON to stdout instead of human-readable lines. */
+    json?: boolean;
+    /** Pretty-print the JSON output when `json: true`. */
+    pretty?: boolean;
+    /** Suppress all output (status is still returned). */
+    silent?: boolean;
+};
+/**
+ * Programmatic entry point for the `env-typegen check` command.
+ *
+ * Loads the contract, parses the env file, runs validation, and outputs results.
+ * Returns `"ok"` when there are no errors, `"fail"` when there are.
+ *
+ * @public
+ */
+declare function runCheck(opts: RunCheckOptions): Promise<ReportStatus>;
+
+type ValidationCommand = "check" | "diff" | "doctor";
+declare function runValidationCommand(params: {
+    command: ValidationCommand;
+    argv: string[];
+}): Promise<number>;
+
+type CloudProvider = "vercel" | "cloudflare" | "aws";
+type CloudConnectorLoadOptions = {
+    provider: CloudProvider;
+    filePath: string;
+};
+declare function loadCloudSource(options: CloudConnectorLoadOptions): Promise<Record<string, string>>;
+
+export { CONTRACT_FILE_NAMES, type CiReport, type CloudProvider, type CommentAnnotations, type EnvContract$1 as EnvContract, type EnvContractEntry, type EnvTypegenConfig, type EnvTypegenPlugin, type EnvVarRuntime, type EnvVarType, type Environment, type Expected$1 as Expected, type FormatCiReportOptions, type GeneratorName, type InferenceRule, type Issue, type IssueCode$1 as IssueCode, type IssueSeverity$1 as IssueSeverity, type ParsedEnvFile, type ParsedEnvVar, type PluginReference, type ReportStatus, type RunCheckOptions, type RunGenerateOptions, type ValidateContractOptions, type ValidationIssue, type ValidationResult, applyContractPlugins, applyReportPlugins, applySourcePlugins, buildCiReport, defineConfig, defineContract, formatCiReport, generateDeclaration, generateEnvValidation, generateT3Env, generateTypeScriptTypes, generateZodSchema, inferType, inferTypesFromParsedVars as inferTypes, inferenceRules, loadCloudSource, loadConfig, loadContract, loadPlugins, parseCommentBlock, parseEnvFile, parseEnvFileContent, runCheck, runGenerate, runValidationCommand, validateContract };