zodrift 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 greyllmmoder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# zodrift
+
+[![npm version](https://img.shields.io/npm/v/zodrift.svg)](https://www.npmjs.com/package/zodrift)
+[![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.
+
+```ts
+import { z } from "zod";
+
+export interface User {
+  name: string;
+  email?: string;
+  age: number;
+}
+
+export const UserSchema = z.object({
+  name: z.string(),
+  email: z.string(),
+  age: z.string(),
+  role: z.string(),
+});
+```
+
+```bash
+npx zodrift check
+```
+
+![zodrift terminal output](./assets/hero.svg)
+
+What it catches:
+- missing fields
+- extra fields
+- required vs optional mismatch
+- basic type mismatch
+
+Roadmap:
+- nested support
+- arrays
+- unions
+- JSON output
+- GitHub Action

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { runCheckCommand } from "./commands/check.js";
+import { runCodegenCommand } from "./commands/codegen.js";
+import { runFixCommand } from "./commands/fix.js";
+import { runFormsCommand } from "./commands/forms.js";
+import { runOpenApiCommand } from "./commands/openapi.js";
+import { parseArgs } from "./utils/args.js";
+function printHelp() {
+    process.stdout.write(`zodrift
+
+Usage:
+  zodrift check [--pattern <glob>] [--format pretty|json|sarif] [--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>]
+  zodrift forms [--pattern <glob>] [--out <file>]
+
+Examples:
+  npx zodrift check
+  npx zodrift check --pattern "examples/**/*.ts"
+  npx zodrift check --format json --out reports/zodrift.json
+  npx zodrift fix --pattern "src/**/*.ts" --dry-run
+`);
+}
+function main() {
+    const parsed = parseArgs(process.argv.slice(2));
+    const command = parsed.command;
+    if (!command || command === "help" || command === "--help" || command === "-h") {
+        printHelp();
+        return 0;
+    }
+    switch (command) {
+        case "check":
+            return runCheckCommand(parsed.flags);
+        case "fix":
+            return runFixCommand(parsed.flags);
+        case "codegen":
+            return runCodegenCommand(parsed.flags);
+        case "openapi":
+            return runOpenApiCommand(parsed.flags);
+        case "forms":
+            return runFormsCommand(parsed.flags);
+        default:
+            process.stderr.write(`Unknown command: ${command}\n\n`);
+            printHelp();
+            return 2;
+    }
+}
+const exitCode = main();
+process.exit(exitCode);

package/dist/commands/check.d.ts

@@ -0,0 +1 @@
+export declare function runCheckCommand(flags: Map<string, string | boolean>): number;

package/dist/commands/check.js

@@ -0,0 +1,52 @@
+import fs from "node:fs";
+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";
+export function runCheckCommand(flags) {
+    const cwd = process.cwd();
+    const pattern = flagString(flags, "pattern", "**/*.{ts,tsx}");
+    const format = flagString(flags, "format", "pretty");
+    const maxIssues = flagNumber(flags, "max-issues");
+    const changedOnly = flagBoolean(flags, "changed", false);
+    const result = runCheck({
+        cwd,
+        pattern,
+        format,
+        maxIssues,
+        changedOnly,
+    });
+    const rendered = renderOutput(format, {
+        result,
+        cwd,
+    });
+    const outFile = flagString(flags, "out", "").trim();
+    if (outFile) {
+        const resolvedOut = path.resolve(cwd, outFile);
+        fs.mkdirSync(path.dirname(resolvedOut), { recursive: true });
+        fs.writeFileSync(resolvedOut, rendered, "utf8");
+        if (format === "pretty") {
+            process.stdout.write(`${rendered}\n`);
+        }
+        process.stdout.write(`Saved ${format} report to ${resolvedOut}\n`);
+    }
+    else {
+        process.stdout.write(`${rendered}\n`);
+    }
+    const failOn = flagString(flags, "fail-on", "all");
+    const hasErrors = result.errors.length > 0;
+    const hasDrift = result.totalIssues > 0;
+    if (hasErrors) {
+        return 2;
+    }
+    if (failOn === "drift" && hasDrift) {
+        return 1;
+    }
+    if (failOn === "error") {
+        return 0;
+    }
+    if (failOn === "all" && (hasDrift || hasErrors)) {
+        return hasDrift ? 1 : 2;
+    }
+    return hasDrift ? 1 : 0;
+}

package/dist/commands/codegen.d.ts

@@ -0,0 +1 @@
+export declare function runCodegenCommand(flags: Map<string, string | boolean>): number;

package/dist/commands/codegen.js

@@ -0,0 +1,63 @@
+import fs from "node:fs";
+import path from "node:path";
+import { discoverSourceFiles } from "../core/file-discovery.js";
+import { typeNodeToTs, typeNodeToZod } from "../core/emit.js";
+import { parseTypeDeclarations } from "../core/ts-parser.js";
+import { parseSchemaDeclarations } from "../core/zod-parser.js";
+import { flagBoolean, flagString } from "../utils/args.js";
+export function runCodegenCommand(flags) {
+    const cwd = process.cwd();
+    const pattern = flagString(flags, "pattern", "**/*.{ts,tsx}");
+    const from = flagString(flags, "from", "ts");
+    const write = flagBoolean(flags, "write", false);
+    const outDir = path.resolve(cwd, flagString(flags, "out-dir", "generated"));
+    const files = discoverSourceFiles({
+        cwd,
+        pattern,
+        changedOnly: false,
+    });
+    let output = "";
+    if (from === "ts") {
+        const parsed = parseTypeDeclarations(files);
+        if (parsed.errors.length > 0) {
+            process.stdout.write(`${parsed.errors.join("\n")}\n`);
+            return 2;
+        }
+        output = [
+            'import { z } from "zod";',
+            "",
+            ...parsed.declarations.map((declaration) => `export const ${declaration.name}Schema = ${typeNodeToZod(declaration.node)};`),
+            "",
+        ].join("\n");
+    }
+    else if (from === "zod") {
+        const parsed = parseSchemaDeclarations(files);
+        if (parsed.errors.length > 0) {
+            process.stdout.write(`${parsed.errors.join("\n")}\n`);
+            return 2;
+        }
+        output = [
+            ...parsed.declarations.map((declaration) => {
+                const name = declaration.name.endsWith("Schema")
+                    ? declaration.name.slice(0, -"Schema".length)
+                    : declaration.name;
+                return `export type ${name} = ${typeNodeToTs(declaration.node)};`;
+            }),
+            "",
+        ].join("\n");
+    }
+    else {
+        process.stdout.write("Invalid --from value. Use --from ts or --from zod.\n");
+        return 2;
+    }
+    const outputFile = path.join(outDir, from === "ts" ? "schemas.ts" : "types.ts");
+    if (!write) {
+        process.stdout.write(output);
+        process.stdout.write(`\nDry run only. Re-run with --write to save ${path.relative(cwd, outputFile)}\n`);
+        return 0;
+    }
+    fs.mkdirSync(outDir, { recursive: true });
+    fs.writeFileSync(outputFile, output, "utf8");
+    process.stdout.write(`Generated ${path.relative(cwd, outputFile)}\n`);
+    return 0;
+}

package/dist/commands/fix.d.ts

@@ -0,0 +1 @@
+export declare function runFixCommand(flags: Map<string, string | boolean>): number;

package/dist/commands/fix.js

@@ -0,0 +1,113 @@
+import fs from "node:fs";
+import path from "node:path";
+import { runCheck } from "../core/checker.js";
+import { flagBoolean, flagString } from "../utils/args.js";
+const PRIMITIVE_METHODS = new Set(["string", "number", "boolean", "unknown", "any"]);
+function addOptional(line) {
+    if (line.includes(".optional()")) {
+        return line;
+    }
+    return line.replace(/(z\.[A-Za-z_$][A-Za-z0-9_$]*\([^\n]*\))(?!\s*\.optional\(\))/, "$1.optional()");
+}
+function removeOptional(line) {
+    return line.replace(/\.optional\(\)/, "");
+}
+function swapPrimitive(line, from, to) {
+    const pattern = new RegExp(`\\bz\\.${from}\\s*\\(`);
+    return line.replace(pattern, `z.${to}(`);
+}
+export function runFixCommand(flags) {
+    const cwd = process.cwd();
+    const pattern = flagString(flags, "pattern", "**/*.{ts,tsx}");
+    const write = flagBoolean(flags, "write", false);
+    const dryRun = flagBoolean(flags, "dry-run", !write);
+    const target = flagString(flags, "target", "schema");
+    if (target !== "schema") {
+        process.stdout.write("Only --target schema is supported in this version.\n");
+        return 2;
+    }
+    const result = runCheck({
+        cwd,
+        pattern,
+        format: "pretty",
+        changedOnly: false,
+    });
+    const fileLines = new Map();
+    const edits = [];
+    function loadLines(filePath) {
+        const abs = path.resolve(filePath);
+        const cached = fileLines.get(abs);
+        if (cached) {
+            return cached;
+        }
+        const lines = fs.readFileSync(abs, "utf8").split(/\r?\n/);
+        fileLines.set(abs, lines);
+        return lines;
+    }
+    for (const pair of result.pairs) {
+        for (const issue of pair.issues) {
+            const location = issue.schemaLocation;
+            if (!location) {
+                continue;
+            }
+            const lines = loadLines(location.filePath);
+            const lineIndex = location.line - 1;
+            if (lineIndex < 0 || lineIndex >= lines.length) {
+                continue;
+            }
+            const original = lines[lineIndex];
+            let updated = original;
+            let reason = "";
+            if (issue.kind === "optional_mismatch" &&
+                issue.typeValue === "optional" &&
+                issue.schemaValue === "required") {
+                updated = addOptional(original);
+                reason = "add optional() to match TypeScript optional field";
+            }
+            else if (issue.kind === "optional_mismatch" &&
+                issue.typeValue === "required" &&
+                issue.schemaValue === "optional") {
+                updated = removeOptional(original);
+                reason = "remove optional() to match TypeScript required field";
+            }
+            else if (issue.kind === "type_mismatch" &&
+                issue.typeValue &&
+                issue.schemaValue &&
+                PRIMITIVE_METHODS.has(issue.typeValue) &&
+                PRIMITIVE_METHODS.has(issue.schemaValue)) {
+                updated = swapPrimitive(original, issue.schemaValue, issue.typeValue);
+                reason = `replace z.${issue.schemaValue} with z.${issue.typeValue}`;
+            }
+            if (!reason || updated === original) {
+                continue;
+            }
+            lines[lineIndex] = updated;
+            edits.push({
+                filePath: location.filePath,
+                line: location.line,
+                reason,
+                before: original,
+                after: updated,
+            });
+        }
+    }
+    if (edits.length === 0) {
+        process.stdout.write("No safe autofixes available for the current drift set.\n");
+        return 0;
+    }
+    for (const edit of edits) {
+        process.stdout.write(`- ${edit.filePath}:${edit.line} ${edit.reason}\n`);
+        process.stdout.write(`  before: ${edit.before.trim()}\n`);
+        process.stdout.write(`  after : ${edit.after.trim()}\n`);
+    }
+    if (dryRun || !write) {
+        process.stdout.write(`\nDry run complete. ${edits.length} safe edits proposed.\n`);
+        process.stdout.write("Re-run with --write to apply changes.\n");
+        return 0;
+    }
+    for (const [filePath, lines] of fileLines.entries()) {
+        fs.writeFileSync(filePath, `${lines.join("\n")}\n`, "utf8");
+    }
+    process.stdout.write(`\nApplied ${edits.length} edits.\n`);
+    return 0;
+}

package/dist/commands/forms.d.ts

@@ -0,0 +1 @@
+export declare function runFormsCommand(flags: Map<string, string | boolean>): number;

package/dist/commands/forms.js

@@ -0,0 +1,41 @@
+import fs from "node:fs";
+import path from "node:path";
+import { discoverSourceFiles } from "../core/file-discovery.js";
+import { typeNodeToFormFields } from "../core/emit.js";
+import { parseSchemaDeclarations } from "../core/zod-parser.js";
+import { flagString } from "../utils/args.js";
+export function runFormsCommand(flags) {
+    const cwd = process.cwd();
+    const pattern = flagString(flags, "pattern", "**/*.{ts,tsx}");
+    const outFile = flagString(flags, "out", "").trim();
+    const files = discoverSourceFiles({
+        cwd,
+        pattern,
+        changedOnly: false,
+    });
+    const parsed = parseSchemaDeclarations(files);
+    if (parsed.errors.length > 0) {
+        process.stdout.write(`${parsed.errors.join("\n")}\n`);
+        return 2;
+    }
+    const forms = {};
+    for (const schema of parsed.declarations) {
+        const name = schema.name.endsWith("Schema")
+            ? schema.name.slice(0, -"Schema".length)
+            : schema.name;
+        forms[name] = {
+            schema: schema.name,
+            fields: typeNodeToFormFields(schema.node),
+        };
+    }
+    const content = `${JSON.stringify({ forms }, null, 2)}\n`;
+    if (!outFile) {
+        process.stdout.write(content);
+        return 0;
+    }
+    const resolvedOut = path.resolve(cwd, outFile);
+    fs.mkdirSync(path.dirname(resolvedOut), { recursive: true });
+    fs.writeFileSync(resolvedOut, content, "utf8");
+    process.stdout.write(`Wrote forms metadata to ${resolvedOut}\n`);
+    return 0;
+}

package/dist/commands/openapi.d.ts

@@ -0,0 +1 @@
+export declare function runOpenApiCommand(flags: Map<string, string | boolean>): number;

package/dist/commands/openapi.js

@@ -0,0 +1,49 @@
+import fs from "node:fs";
+import path from "node:path";
+import { discoverSourceFiles } from "../core/file-discovery.js";
+import { typeNodeToOpenApi } from "../core/emit.js";
+import { parseSchemaDeclarations } from "../core/zod-parser.js";
+import { flagString } from "../utils/args.js";
+export function runOpenApiCommand(flags) {
+    const cwd = process.cwd();
+    const pattern = flagString(flags, "pattern", "**/*.{ts,tsx}");
+    const outFile = flagString(flags, "out", "").trim();
+    const files = discoverSourceFiles({
+        cwd,
+        pattern,
+        changedOnly: false,
+    });
+    const parsed = parseSchemaDeclarations(files);
+    if (parsed.errors.length > 0) {
+        process.stdout.write(`${parsed.errors.join("\n")}\n`);
+        return 2;
+    }
+    const components = {};
+    for (const schema of parsed.declarations) {
+        const name = schema.name.endsWith("Schema")
+            ? schema.name.slice(0, -"Schema".length)
+            : schema.name;
+        components[name] = typeNodeToOpenApi(schema.node);
+    }
+    const payload = {
+        openapi: "3.1.0",
+        info: {
+            title: "zodrift generated spec",
+            version: "0.1.0",
+        },
+        paths: {},
+        components: {
+            schemas: components,
+        },
+    };
+    const content = `${JSON.stringify(payload, null, 2)}\n`;
+    if (!outFile) {
+        process.stdout.write(content);
+        return 0;
+    }
+    const resolvedOut = path.resolve(cwd, outFile);
+    fs.mkdirSync(path.dirname(resolvedOut), { recursive: true });
+    fs.writeFileSync(resolvedOut, content, "utf8");
+    process.stdout.write(`Wrote OpenAPI spec to ${resolvedOut}\n`);
+    return 0;
+}

package/dist/core/checker.d.ts

@@ -0,0 +1,2 @@
+import type { CheckOptions, CheckResult } from "./types.js";
+export declare function runCheck(options: CheckOptions): CheckResult;

package/dist/core/checker.js

@@ -0,0 +1,39 @@
+import { comparePair } from "./compare.js";
+import { discoverSourceFiles } from "./file-discovery.js";
+import { pairTypesWithSchemas } from "./pairing.js";
+import { parseTypeDeclarations } from "./ts-parser.js";
+import { parseSchemaDeclarations } from "./zod-parser.js";
+export function runCheck(options) {
+    const files = discoverSourceFiles({
+        cwd: options.cwd,
+        pattern: options.pattern,
+        changedOnly: options.changedOnly,
+    });
+    const typeParsed = parseTypeDeclarations(files);
+    const schemaParsed = parseSchemaDeclarations(files);
+    const paired = pairTypesWithSchemas(typeParsed.declarations, schemaParsed.declarations);
+    const pairs = [];
+    let totalIssues = 0;
+    for (const pair of paired.pairs) {
+        const issues = comparePair(pair);
+        const cappedIssues = options.maxIssues && options.maxIssues > 0
+            ? issues.slice(0, options.maxIssues)
+            : issues;
+        totalIssues += cappedIssues.length;
+        pairs.push({
+            typeName: pair.typeDecl.name,
+            schemaName: pair.schemaDecl.name,
+            typeDecl: pair.typeDecl,
+            schemaDecl: pair.schemaDecl,
+            issues: cappedIssues,
+        });
+    }
+    return {
+        pairs,
+        totalIssues,
+        checkedPairs: pairs.length,
+        unmatchedTypes: paired.unmatchedTypes,
+        unmatchedSchemas: paired.unmatchedSchemas,
+        errors: [...typeParsed.errors, ...schemaParsed.errors],
+    };
+}

package/dist/core/compare.d.ts

@@ -0,0 +1,2 @@
+import type { DriftIssue, Pairing } from "./types.js";
+export declare function comparePair(pair: Pairing): DriftIssue[];