zodrift 0.1.1 → 0.1.3

package/README.md

@@ -4,7 +4,9 @@
 [![CI](https://github.com/greyllmmoder/zodrift/actions/workflows/ci.yml/badge.svg)](https://github.com/greyllmmoder/zodrift/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Catch drift between your TypeScript types and Zod schemas.
+ESLint for TypeScript and Zod drift. Catch contract drift before it reaches runtime.
+
+Built for teams that already have TS types and Zod schemas and want CI to fail when they drift.
 
 ```ts
 import { z } from "zod";
@@ -27,13 +29,53 @@ export const UserSchema = z.object({
 npx zodrift check
 ```
 
-![zodrift terminal output](./assets/hero.svg)
+![zodrift terminal output](https://raw.githubusercontent.com/greyllmmoder/zodrift/main/assets/hero.svg)
+
+Example output:
+
+```text
+✗ User ↔ UserSchema
+  - optional mismatch for email: type=optional, schema=required
+  - type mismatch for age: type=number, schema=string
+  - extra in schema: role
+```
 
 What it catches:
 - missing fields
 - extra fields
 - required vs optional mismatch
 - basic type mismatch
+- semantic mismatch when your TS type is not assignable to `z.input<typeof Schema>` / `z.output<typeof Schema>` (optional mode)
+
+CI quick start:
+
+```yaml
+- run: npx zodrift check --pattern "src/**/*.{ts,tsx}" --semantics both
+```
+
+Exit codes:
+- `0`: no drift
+- `1`: drift found
+- `2`: parser/runtime error
+
+Useful commands:
+
+```bash
+# Check current project
+npx zodrift check --pattern "src/**/*.{ts,tsx}"
+
+# Add semantic compatibility checks for z.input/z.output
+npx zodrift check --pattern "src/**/*.{ts,tsx}" --semantics both
+
+# Machine-readable report for CI artifacts
+npx zodrift check --format json --out reports/zodrift.json
+
+# SARIF for GitHub code scanning
+npx zodrift check --format sarif --out reports/zodrift.sarif
+
+# Safe autofix pass (dry-run first)
+npx zodrift fix --pattern "src/**/*.ts" --dry-run
+```
 
 Roadmap:
 - nested support

package/dist/cli.js

@@ -9,7 +9,7 @@ function printHelp() {
     process.stdout.write(`zodrift
 
 Usage:
-  zodrift check [--pattern <glob>] [--format pretty|json|sarif] [--out <file>] [--changed]
+  zodrift check [--pattern <glob>] [--format pretty|json|sarif] [--semantics off|input|output|both] [--out <file>] [--changed]
   zodrift fix [--pattern <glob>] [--target schema] [--dry-run] [--write]
   zodrift codegen [--from ts|zod] [--pattern <glob>] [--out-dir <dir>] [--write]
   zodrift openapi [--pattern <glob>] [--out <file>]
@@ -18,6 +18,7 @@ Usage:
 Examples:
   npx zodrift check
   npx zodrift check --pattern "examples/**/*.ts"
+  npx zodrift check --semantics both
   npx zodrift check --format json --out reports/zodrift.json
   npx zodrift fix --pattern "src/**/*.ts" --dry-run
 `);

package/dist/commands/check.js

@@ -3,16 +3,29 @@ import path from "node:path";
 import { runCheck } from "../core/checker.js";
 import { renderOutput } from "../reporters/index.js";
 import { flagBoolean, flagNumber, flagString } from "../utils/args.js";
+function parseSemanticsMode(value) {
+    if (value === "off" || value === "input" || value === "output" || value === "both") {
+        return value;
+    }
+    return null;
+}
 export function runCheckCommand(flags) {
     const cwd = process.cwd();
     const pattern = flagString(flags, "pattern", "**/*.{ts,tsx}");
     const format = flagString(flags, "format", "pretty");
+    const semanticsRaw = flagString(flags, "semantics", "off");
+    const semantics = parseSemanticsMode(semanticsRaw);
+    if (!semantics) {
+        process.stderr.write(`Invalid --semantics value: ${semanticsRaw}. Use one of: off, input, output, both.\n`);
+        return 2;
+    }
     const maxIssues = flagNumber(flags, "max-issues");
     const changedOnly = flagBoolean(flags, "changed", false);
     const result = runCheck({
         cwd,
         pattern,
         format,
+        semantics,
         maxIssues,
         changedOnly,
     });

package/dist/commands/fix.js

@@ -30,6 +30,7 @@ export function runFixCommand(flags) {
         cwd,
         pattern,
         format: "pretty",
+        semantics: "off",
         changedOnly: false,
     });
     const fileLines = new Map();

package/dist/core/checker.js

@@ -1,6 +1,7 @@
 import { comparePair } from "./compare.js";
 import { discoverSourceFiles } from "./file-discovery.js";
 import { pairTypesWithSchemas } from "./pairing.js";
+import { collectSemanticIssues, pairKey } from "./semantic-checker.js";
 import { parseTypeDeclarations } from "./ts-parser.js";
 import { parseSchemaDeclarations } from "./zod-parser.js";
 export function runCheck(options) {
@@ -12,14 +13,23 @@ export function runCheck(options) {
     const typeParsed = parseTypeDeclarations(files);
     const schemaParsed = parseSchemaDeclarations(files);
     const paired = pairTypesWithSchemas(typeParsed.declarations, schemaParsed.declarations);
+    const semantic = collectSemanticIssues({
+        cwd: options.cwd,
+        pairs: paired.pairs,
+        semantics: options.semantics,
+    });
     const pairs = [];
     let totalIssues = 0;
+    let semanticIssueCount = 0;
     for (const pair of paired.pairs) {
-        const issues = comparePair(pair);
+        const structuralIssues = comparePair(pair);
+        const semanticIssues = semantic.issuesByPair.get(pairKey(pair)) ?? [];
+        const issues = [...structuralIssues, ...semanticIssues];
         const cappedIssues = options.maxIssues && options.maxIssues > 0
             ? issues.slice(0, options.maxIssues)
             : issues;
         totalIssues += cappedIssues.length;
+        semanticIssueCount += cappedIssues.filter((issue) => issue.kind === "semantic_mismatch").length;
         pairs.push({
             typeName: pair.typeDecl.name,
             schemaName: pair.schemaDecl.name,
@@ -34,6 +44,8 @@ export function runCheck(options) {
         checkedPairs: pairs.length,
         unmatchedTypes: paired.unmatchedTypes,
         unmatchedSchemas: paired.unmatchedSchemas,
-        errors: [...typeParsed.errors, ...schemaParsed.errors],
+        semanticsMode: options.semantics,
+        semanticIssueCount,
+        errors: [...typeParsed.errors, ...schemaParsed.errors, ...semantic.errors],
     };
 }

package/dist/core/semantic-checker.d.ts

@@ -0,0 +1,10 @@
+import type { DriftIssue, Pairing, SemanticsMode } from "./types.js";
+export declare function pairKey(pair: Pairing): string;
+export declare function collectSemanticIssues(options: {
+    cwd: string;
+    pairs: Pairing[];
+    semantics: SemanticsMode;
+}): {
+    issuesByPair: Map<string, DriftIssue[]>;
+    errors: string[];
+};

package/dist/core/semantic-checker.js

@@ -0,0 +1,190 @@
+import fs from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+const TYPE_ALIAS_NAME = "__ZodriftTypeAlias";
+const INPUT_ALIAS_NAME = "__ZodriftInputAlias";
+const OUTPUT_ALIAS_NAME = "__ZodriftOutputAlias";
+const TYPE_IMPORT_NAME = "__ZodriftType";
+const SCHEMA_IMPORT_NAME = "__ZodriftSchema";
+function pairName(pair) {
+    return `${pair.typeDecl.name} ↔ ${pair.schemaDecl.name}`;
+}
+export function pairKey(pair) {
+    return `${path.resolve(pair.typeDecl.sourceFilePath)}::${pair.typeDecl.name}::${path.resolve(pair.schemaDecl.sourceFilePath)}::${pair.schemaDecl.name}`;
+}
+function loadCompilerOptions(cwd) {
+    const fallback = {
+        target: ts.ScriptTarget.ES2022,
+        module: ts.ModuleKind.NodeNext,
+        moduleResolution: ts.ModuleResolutionKind.NodeNext,
+        jsx: ts.JsxEmit.Preserve,
+        allowJs: false,
+        skipLibCheck: true,
+        strict: true,
+        exactOptionalPropertyTypes: true,
+        noEmit: true,
+    };
+    const configPath = ts.findConfigFile(cwd, ts.sys.fileExists, "tsconfig.json");
+    if (!configPath) {
+        return fallback;
+    }
+    const read = ts.readConfigFile(configPath, ts.sys.readFile);
+    if (read.error) {
+        return fallback;
+    }
+    const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, path.dirname(configPath));
+    return {
+        ...parsed.options,
+        module: ts.ModuleKind.NodeNext,
+        moduleResolution: ts.ModuleResolutionKind.NodeNext,
+        jsx: parsed.options.jsx ?? ts.JsxEmit.Preserve,
+        rootDir: cwd,
+        strict: true,
+        exactOptionalPropertyTypes: true,
+        skipLibCheck: true,
+        noEmit: true,
+    };
+}
+function toImportSpecifier(fromFilePath, targetFilePath) {
+    const relative = path
+        .relative(path.dirname(fromFilePath), targetFilePath)
+        .split(path.sep)
+        .join("/");
+    const withDot = relative.startsWith(".") ? relative : `./${relative}`;
+    const withoutExt = withDot.replace(/\.[cm]?tsx?$/i, "");
+    return `${withoutExt}.js`;
+}
+function formatDiagnostic(diagnostic) {
+    const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
+    if (!diagnostic.file || typeof diagnostic.start !== "number") {
+        return message;
+    }
+    const pos = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start);
+    const filePath = path.resolve(diagnostic.file.fileName);
+    return `${filePath}:${pos.line + 1}:${pos.character + 1} ${message}`;
+}
+function typeText(checker, type) {
+    return checker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope);
+}
+function compareEquivalence(checker, left, right) {
+    return {
+        leftToRight: checker.isTypeAssignableTo(left, right),
+        rightToLeft: checker.isTypeAssignableTo(right, left),
+    };
+}
+function makeSemanticIssue(params) {
+    return {
+        kind: "semantic_mismatch",
+        pairName: pairName(params.pair),
+        path: `(semantic:${params.mode})`,
+        message: params.message,
+        typeValue: params.typeValue,
+        schemaValue: params.schemaValue,
+        typeLocation: params.pair.typeDecl.location,
+        schemaLocation: params.pair.schemaDecl.location,
+    };
+}
+function buildSemanticProbeContent(pair, probeFilePath) {
+    const typeSpecifier = toImportSpecifier(probeFilePath, pair.typeDecl.sourceFilePath);
+    const schemaSpecifier = toImportSpecifier(probeFilePath, pair.schemaDecl.sourceFilePath);
+    return `import { z } from "zod";
+import type { ${pair.typeDecl.name} as ${TYPE_IMPORT_NAME} } from "${typeSpecifier}";
+import { ${pair.schemaDecl.name} as ${SCHEMA_IMPORT_NAME} } from "${schemaSpecifier}";
+
+type ${TYPE_ALIAS_NAME} = ${TYPE_IMPORT_NAME};
+type ${INPUT_ALIAS_NAME} = z.input<typeof ${SCHEMA_IMPORT_NAME}>;
+type ${OUTPUT_ALIAS_NAME} = z.output<typeof ${SCHEMA_IMPORT_NAME}>;
+`;
+}
+function findAliasType(checker, sourceFile, aliasName) {
+    const alias = sourceFile.statements.find((statement) => ts.isTypeAliasDeclaration(statement) && statement.name.text === aliasName);
+    if (!alias) {
+        return undefined;
+    }
+    return checker.getTypeAtLocation(alias);
+}
+export function collectSemanticIssues(options) {
+    const issuesByPair = new Map();
+    const errors = [];
+    if (options.semantics === "off" || options.pairs.length === 0) {
+        return { issuesByPair, errors };
+    }
+    const compilerOptions = loadCompilerOptions(options.cwd);
+    const tempDir = fs.mkdtempSync(path.join(options.cwd, ".zodrift-semantic-"));
+    const runInput = options.semantics === "input" || options.semantics === "both";
+    const runOutput = options.semantics === "output" || options.semantics === "both";
+    try {
+        for (let index = 0; index < options.pairs.length; index += 1) {
+            const pair = options.pairs[index];
+            const pairIssues = [];
+            const probeFilePath = path.join(tempDir, `probe-${index}.ts`);
+            fs.writeFileSync(probeFilePath, buildSemanticProbeContent(pair, probeFilePath), "utf8");
+            const program = ts.createProgram([probeFilePath], compilerOptions);
+            const diagnostics = ts
+                .getPreEmitDiagnostics(program)
+                .filter((diag) => diag.category === ts.DiagnosticCategory.Error);
+            if (diagnostics.length > 0) {
+                const message = formatDiagnostic(diagnostics[0]);
+                pairIssues.push(makeSemanticIssue({
+                    pair,
+                    mode: runInput ? "input" : "output",
+                    message: `semantic check could not evaluate pair: ${message}`,
+                }));
+                issuesByPair.set(pairKey(pair), pairIssues);
+                continue;
+            }
+            const checker = program.getTypeChecker();
+            const probeSource = program.getSourceFile(probeFilePath);
+            if (!probeSource) {
+                pairIssues.push(makeSemanticIssue({
+                    pair,
+                    mode: runInput ? "input" : "output",
+                    message: "semantic check could not load probe source file",
+                }));
+                issuesByPair.set(pairKey(pair), pairIssues);
+                continue;
+            }
+            const typeType = findAliasType(checker, probeSource, TYPE_ALIAS_NAME);
+            const inputType = findAliasType(checker, probeSource, INPUT_ALIAS_NAME);
+            const outputType = findAliasType(checker, probeSource, OUTPUT_ALIAS_NAME);
+            if (!typeType || !inputType || !outputType) {
+                pairIssues.push(makeSemanticIssue({
+                    pair,
+                    mode: runInput ? "input" : "output",
+                    message: "semantic check could not infer probe alias types",
+                }));
+                issuesByPair.set(pairKey(pair), pairIssues);
+                continue;
+            }
+            const evaluate = (mode, schemaType) => {
+                const comparison = compareEquivalence(checker, typeType, schemaType);
+                if (comparison.leftToRight) {
+                    return;
+                }
+                pairIssues.push(makeSemanticIssue({
+                    pair,
+                    mode,
+                    message: `semantic mismatch (${mode}): ${pair.typeDecl.name} is not assignable to z.${mode}<typeof ${pair.schemaDecl.name}> (type->schema=${comparison.leftToRight}, schema->type=${comparison.rightToLeft})`,
+                    typeValue: typeText(checker, typeType),
+                    schemaValue: typeText(checker, schemaType),
+                }));
+            };
+            if (runInput) {
+                evaluate("input", inputType);
+            }
+            if (runOutput) {
+                evaluate("output", outputType);
+            }
+            if (pairIssues.length > 0) {
+                issuesByPair.set(pairKey(pair), pairIssues);
+            }
+        }
+    }
+    catch (error) {
+        errors.push(`Failed semantic check pass: ${String(error)}`);
+    }
+    finally {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+    return { issuesByPair, errors };
+}

package/dist/core/types.d.ts

@@ -65,7 +65,7 @@ export interface SchemaDeclaration {
     sourceFilePath: string;
     objectNodeText?: string;
 }
-export type DriftIssueKind = "missing_in_schema" | "extra_in_schema" | "optional_mismatch" | "type_mismatch";
+export type DriftIssueKind = "missing_in_schema" | "extra_in_schema" | "optional_mismatch" | "type_mismatch" | "semantic_mismatch";
 export interface DriftIssue {
     kind: DriftIssueKind;
     pairName: string;
@@ -89,6 +89,8 @@ export interface CheckResult {
     checkedPairs: number;
     unmatchedTypes: string[];
     unmatchedSchemas: string[];
+    semanticsMode: SemanticsMode;
+    semanticIssueCount: number;
     errors: string[];
 }
 export interface Pairing {
@@ -100,10 +102,12 @@ export interface ReporterPayload {
     cwd: string;
 }
 export type OutputFormat = "pretty" | "json" | "sarif";
+export type SemanticsMode = "off" | "input" | "output" | "both";
 export interface CheckOptions {
     cwd: string;
     pattern: string;
     format: OutputFormat;
+    semantics: SemanticsMode;
     maxIssues?: number;
     changedOnly: boolean;
 }

package/dist/reporters/json.js

@@ -3,6 +3,8 @@ export function renderJson(payload) {
         summary: {
             checkedPairs: payload.result.checkedPairs,
             totalIssues: payload.result.totalIssues,
+            semanticsMode: payload.result.semanticsMode,
+            semanticIssueCount: payload.result.semanticIssueCount,
             unmatchedTypes: payload.result.unmatchedTypes,
             unmatchedSchemas: payload.result.unmatchedSchemas,
             errors: payload.result.errors,

package/dist/reporters/pretty.js

@@ -31,5 +31,8 @@ export function renderPretty(payload) {
             .join(", ")}`);
     }
     lines.push(`Checked pairs: ${payload.result.checkedPairs} | Issues: ${payload.result.totalIssues}`);
+    if (payload.result.semanticsMode !== "off") {
+        lines.push(`Semantic mode: ${payload.result.semanticsMode} | Semantic issues: ${payload.result.semanticIssueCount}`);
+    }
     return lines.join("\n").trim();
 }

package/dist/reporters/sarif.js

@@ -3,6 +3,7 @@ function levelForIssue(kind) {
     switch (kind) {
         case "type_mismatch":
         case "optional_mismatch":
+        case "semantic_mismatch":
             return "error";
         default:
             return "warning";
@@ -18,6 +19,8 @@ function ruleName(kind) {
             return "optional-mismatch";
         case "type_mismatch":
             return "type-mismatch";
+        case "semantic_mismatch":
+            return "semantic-mismatch";
         default:
             return "drift";
     }
@@ -40,6 +43,10 @@ export function renderSarif(payload) {
             id: "type-mismatch",
             shortDescription: { text: "Type mismatch between TS and Zod" },
         },
+        {
+            id: "semantic-mismatch",
+            shortDescription: { text: "TypeScript semantic mismatch against z.input/z.output" },
+        },
     ];
     const results = payload.result.pairs.flatMap((pair) => pair.issues.map((issue) => {
         const location = issue.schemaLocation ?? issue.typeLocation;

package/package.json

@@ -1,7 +1,16 @@
 {
   "name": "zodrift",
-  "version": "0.1.1",
-  "description": "Catch drift between your TypeScript types and Zod schemas.",
+  "version": "0.1.3",
+  "description": "ESLint-style CI drift checker for TypeScript types and Zod schemas.",
+  "author": "greyllmmoder",
+  "homepage": "https://github.com/greyllmmoder/zodrift#readme",
+  "bugs": {
+    "url": "https://github.com/greyllmmoder/zodrift/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/greyllmmoder/zodrift.git"
+  },
   "type": "module",
   "license": "MIT",
   "bin": {
@@ -24,10 +33,17 @@
     "prepublishOnly": "npm run typecheck && npm run build && npm test"
   },
   "keywords": [
+    "zodrift",
+    "eslint-for-zod",
     "zod",
     "typescript",
     "schema",
     "drift",
+    "drift-detection",
+    "schema-validation",
+    "api-contracts",
+    "type-safety",
+    "ci",
     "cli"
   ],
   "devDependencies": {