trickle-cli 0.1.0

package/dist/commands/check.js

@@ -0,0 +1,408 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkCommand = checkCommand;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const api_client_1 = require("../api-client");
+/**
+ * Recursively diff two type nodes and classify changes as breaking or non-breaking.
+ *
+ * Breaking changes (for responses):
+ * - Field removed from response object
+ * - Field type changed in response
+ * - Array element type changed
+ *
+ * Non-breaking changes (for responses):
+ * - Field added to response object
+ *
+ * Breaking changes (for requests/args):
+ * - New required field added to request body
+ * - Field type changed in request
+ *
+ * Non-breaking changes (for requests/args):
+ * - Field removed from request (server no longer requires it)
+ */
+function classifyChanges(baseline, current, basePath, context) {
+    const changes = [];
+    const b = baseline;
+    const c = current;
+    if (!b || !c)
+        return changes;
+    // Different kinds
+    if (b.kind !== c.kind) {
+        changes.push({
+            functionName: "",
+            severity: "breaking",
+            description: `Type changed from ${b.kind} to ${c.kind}`,
+            path: basePath || "(root)",
+        });
+        return changes;
+    }
+    switch (b.kind) {
+        case "primitive": {
+            if (b.name !== c.name) {
+                changes.push({
+                    functionName: "",
+                    severity: "breaking",
+                    description: `Type changed from ${b.name} to ${c.name}`,
+                    path: basePath || "(root)",
+                });
+            }
+            break;
+        }
+        case "object": {
+            const bProps = b.properties;
+            const cProps = c.properties;
+            const bKeys = new Set(Object.keys(bProps || {}));
+            const cKeys = new Set(Object.keys(cProps || {}));
+            // Fields in baseline but not in current
+            for (const key of bKeys) {
+                const childPath = basePath ? `${basePath}.${key}` : key;
+                if (!cKeys.has(key)) {
+                    if (context === "response") {
+                        // Removing a response field is breaking (clients may depend on it)
+                        changes.push({
+                            functionName: "",
+                            severity: "breaking",
+                            description: `Field removed from response`,
+                            path: childPath,
+                        });
+                    }
+                    else {
+                        // Removing a request field is non-breaking (server no longer needs it)
+                        changes.push({
+                            functionName: "",
+                            severity: "non-breaking",
+                            description: `Field removed from request (no longer required)`,
+                            path: childPath,
+                        });
+                    }
+                }
+                else {
+                    // Recursively check
+                    changes.push(...classifyChanges(bProps[key], cProps[key], childPath, context));
+                }
+            }
+            // Fields in current but not in baseline
+            for (const key of cKeys) {
+                if (!bKeys.has(key)) {
+                    const childPath = basePath ? `${basePath}.${key}` : key;
+                    if (context === "response") {
+                        // Adding a response field is non-breaking
+                        changes.push({
+                            functionName: "",
+                            severity: "non-breaking",
+                            description: `Field added to response`,
+                            path: childPath,
+                        });
+                    }
+                    else {
+                        // Adding a request field is breaking (callers don't send it yet)
+                        changes.push({
+                            functionName: "",
+                            severity: "breaking",
+                            description: `New required field added to request`,
+                            path: childPath,
+                        });
+                    }
+                }
+            }
+            break;
+        }
+        case "array": {
+            const bEl = b.element;
+            const cEl = c.element;
+            changes.push(...classifyChanges(bEl, cEl, `${basePath || "(root)"}[]`, context));
+            break;
+        }
+        case "tuple": {
+            const bEls = b.elements;
+            const cEls = c.elements;
+            const maxLen = Math.max(bEls?.length || 0, cEls?.length || 0);
+            for (let i = 0; i < maxLen; i++) {
+                const elPath = `${basePath || "(root)"}[${i}]`;
+                if (i >= (bEls?.length || 0)) {
+                    changes.push({
+                        functionName: "",
+                        severity: context === "response" ? "non-breaking" : "breaking",
+                        description: `Element added`,
+                        path: elPath,
+                    });
+                }
+                else if (i >= (cEls?.length || 0)) {
+                    changes.push({
+                        functionName: "",
+                        severity: "breaking",
+                        description: `Element removed`,
+                        path: elPath,
+                    });
+                }
+                else {
+                    changes.push(...classifyChanges(bEls[i], cEls[i], elPath, context));
+                }
+            }
+            break;
+        }
+        case "union": {
+            const bMembers = b.members.map((m) => JSON.stringify(m));
+            const cMembers = c.members.map((m) => JSON.stringify(m));
+            const bSet = new Set(bMembers);
+            const cSet = new Set(cMembers);
+            for (const m of bMembers) {
+                if (!cSet.has(m)) {
+                    changes.push({
+                        functionName: "",
+                        severity: "breaking",
+                        description: `Union member removed`,
+                        path: basePath || "(root)",
+                    });
+                }
+            }
+            for (const m of cMembers) {
+                if (!bSet.has(m)) {
+                    changes.push({
+                        functionName: "",
+                        severity: "non-breaking",
+                        description: `Union member added`,
+                        path: basePath || "(root)",
+                    });
+                }
+            }
+            break;
+        }
+        case "map": {
+            changes.push(...classifyChanges(b.value, c.value, `${basePath}<value>`, context));
+            break;
+        }
+        case "set": {
+            changes.push(...classifyChanges(b.element, c.element, `${basePath}<element>`, context));
+            break;
+        }
+        case "promise": {
+            changes.push(...classifyChanges(b.resolved, c.resolved, basePath, context));
+            break;
+        }
+        // unknown, function — no deep diff
+    }
+    return changes;
+}
+async function checkCommand(opts) {
+    try {
+        // Mode 1: Save current snapshot
+        if (opts.save) {
+            const snapshot = await (0, api_client_1.fetchSnapshot)({ env: opts.env });
+            if (snapshot.functions.length === 0) {
+                console.error(chalk_1.default.yellow("\n  No functions observed yet. Run your app first to populate types.\n"));
+                process.exit(1);
+            }
+            const outPath = path.resolve(opts.save);
+            const dir = path.dirname(outPath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            fs.writeFileSync(outPath, JSON.stringify(snapshot, null, 2) + "\n", "utf-8");
+            console.log("");
+            console.log(chalk_1.default.green(`  Baseline saved to ${chalk_1.default.bold(opts.save)}`));
+            console.log(chalk_1.default.gray(`  ${snapshot.functions.length} function${snapshot.functions.length !== 1 ? "s" : ""} captured at ${snapshot.createdAt}`));
+            console.log("");
+            return;
+        }
+        // Mode 2: Check against baseline
+        if (opts.against) {
+            const baselinePath = path.resolve(opts.against);
+            if (!fs.existsSync(baselinePath)) {
+                console.error(chalk_1.default.red(`\n  Baseline file not found: ${opts.against}\n`));
+                process.exit(1);
+            }
+            let baseline;
+            try {
+                baseline = JSON.parse(fs.readFileSync(baselinePath, "utf-8"));
+            }
+            catch {
+                console.error(chalk_1.default.red(`\n  Invalid baseline file: ${opts.against}\n`));
+                process.exit(1);
+                return; // unreachable but satisfies TS
+            }
+            const current = await (0, api_client_1.fetchSnapshot)({ env: opts.env });
+            if (current.functions.length === 0) {
+                console.error(chalk_1.default.yellow("\n  No functions observed yet. Run your app first to populate types.\n"));
+                process.exit(1);
+            }
+            console.log("");
+            console.log(chalk_1.default.white.bold("  trickle check"));
+            console.log(chalk_1.default.gray(`  Baseline: ${opts.against} (${baseline.createdAt})`));
+            console.log(chalk_1.default.gray(`  Current: ${current.functions.length} functions observed`));
+            console.log(chalk_1.default.gray("  " + "─".repeat(50)));
+            // Build lookup maps
+            const baselineMap = new Map();
+            for (const fn of baseline.functions) {
+                baselineMap.set(fn.name, fn);
+            }
+            const currentMap = new Map();
+            for (const fn of current.functions) {
+                currentMap.set(fn.name, fn);
+            }
+            const allChanges = [];
+            const removedFunctions = [];
+            const addedFunctions = [];
+            // Check for removed functions
+            for (const [name] of baselineMap) {
+                if (!currentMap.has(name)) {
+                    removedFunctions.push(name);
+                    allChanges.push({
+                        functionName: name,
+                        severity: "breaking",
+                        description: "Function/route removed entirely",
+                        path: "(function)",
+                    });
+                }
+            }
+            // Check for added functions
+            for (const [name] of currentMap) {
+                if (!baselineMap.has(name)) {
+                    addedFunctions.push(name);
+                    allChanges.push({
+                        functionName: name,
+                        severity: "non-breaking",
+                        description: "New function/route added",
+                        path: "(function)",
+                    });
+                }
+            }
+            // Check for type changes in existing functions
+            for (const [name, baselineFn] of baselineMap) {
+                const currentFn = currentMap.get(name);
+                if (!currentFn)
+                    continue;
+                // Compare return types (response)
+                const returnChanges = classifyChanges(baselineFn.returnType, currentFn.returnType, "response", "response");
+                for (const change of returnChanges) {
+                    change.functionName = name;
+                    allChanges.push(change);
+                }
+                // Compare args types (request)
+                const argsChanges = classifyChanges(baselineFn.argsType, currentFn.argsType, "request", "request");
+                for (const change of argsChanges) {
+                    change.functionName = name;
+                    allChanges.push(change);
+                }
+            }
+            // Separate breaking vs non-breaking
+            const breaking = allChanges.filter((c) => c.severity === "breaking");
+            const nonBreaking = allChanges.filter((c) => c.severity === "non-breaking");
+            // Display results
+            if (breaking.length === 0 && nonBreaking.length === 0) {
+                console.log("");
+                console.log(chalk_1.default.green("  No type changes detected. API is compatible with baseline."));
+                console.log("");
+                return;
+            }
+            if (breaking.length > 0) {
+                console.log("");
+                console.log(chalk_1.default.red.bold(`  ${breaking.length} BREAKING CHANGE${breaking.length !== 1 ? "S" : ""}`));
+                console.log("");
+                // Group by function
+                const grouped = new Map();
+                for (const change of breaking) {
+                    const list = grouped.get(change.functionName) || [];
+                    list.push(change);
+                    grouped.set(change.functionName, list);
+                }
+                for (const [fnName, changes] of grouped) {
+                    console.log(chalk_1.default.white(`  ${fnName}`));
+                    for (const change of changes) {
+                        console.log(chalk_1.default.red("    ✗ ") +
+                            chalk_1.default.gray(change.path) +
+                            chalk_1.default.red(` — ${change.description}`));
+                    }
+                }
+            }
+            if (nonBreaking.length > 0) {
+                console.log("");
+                console.log(chalk_1.default.yellow(`  ${nonBreaking.length} non-breaking change${nonBreaking.length !== 1 ? "s" : ""}`));
+                console.log("");
+                const grouped = new Map();
+                for (const change of nonBreaking) {
+                    const list = grouped.get(change.functionName) || [];
+                    list.push(change);
+                    grouped.set(change.functionName, list);
+                }
+                for (const [fnName, changes] of grouped) {
+                    console.log(chalk_1.default.white(`  ${fnName}`));
+                    for (const change of changes) {
+                        console.log(chalk_1.default.green("    + ") +
+                            chalk_1.default.gray(change.path) +
+                            chalk_1.default.gray(` — ${change.description}`));
+                    }
+                }
+            }
+            console.log("");
+            // Summary
+            if (breaking.length > 0) {
+                console.log(chalk_1.default.red.bold("  FAIL") + chalk_1.default.red(` — ${breaking.length} breaking change${breaking.length !== 1 ? "s" : ""} detected`));
+                console.log("");
+                process.exit(1);
+            }
+            else {
+                console.log(chalk_1.default.green.bold("  PASS") + chalk_1.default.green(` — ${nonBreaking.length} non-breaking change${nonBreaking.length !== 1 ? "s" : ""}, no breaking changes`));
+                console.log("");
+            }
+            return;
+        }
+        // No flags — show usage
+        console.log("");
+        console.log(chalk_1.default.white.bold("  trickle check") + chalk_1.default.gray(" — detect breaking API changes"));
+        console.log("");
+        console.log(chalk_1.default.white("  Save a baseline:"));
+        console.log(chalk_1.default.cyan("    trickle check --save baseline.json"));
+        console.log("");
+        console.log(chalk_1.default.white("  Check against baseline:"));
+        console.log(chalk_1.default.cyan("    trickle check --against baseline.json"));
+        console.log("");
+        console.log(chalk_1.default.gray("  Exit code 0 = compatible, exit code 1 = breaking changes"));
+        console.log("");
+    }
+    catch (err) {
+        if (err instanceof Error) {
+            console.error(chalk_1.default.red(`\n  Error: ${err.message}\n`));
+        }
+        process.exit(1);
+    }
+}

package/dist/commands/codegen.d.ts

@@ -0,0 +1,21 @@
+export interface CodegenOptions {
+    out?: string;
+    env?: string;
+    python?: boolean;
+    client?: boolean;
+    handlers?: boolean;
+    zod?: boolean;
+    reactQuery?: boolean;
+    guards?: boolean;
+    middleware?: boolean;
+    msw?: boolean;
+    jsonSchema?: boolean;
+    swr?: boolean;
+    pydantic?: boolean;
+    classValidator?: boolean;
+    graphql?: boolean;
+    trpc?: boolean;
+    axios?: boolean;
+    watch?: boolean;
+}
+export declare function codegenCommand(functionName: string | undefined, opts: CodegenOptions): Promise<void>;

package/dist/commands/codegen.js

@@ -0,0 +1,129 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.codegenCommand = codegenCommand;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const api_client_1 = require("../api-client");
+async function codegenCommand(functionName, opts) {
+    const language = opts.python ? "python" : undefined;
+    const format = opts.axios ? "axios" : opts.trpc ? "trpc" : opts.graphql ? "graphql" : opts.classValidator ? "class-validator" : opts.pydantic ? "pydantic" : opts.swr ? "swr" : opts.jsonSchema ? "json-schema" : opts.msw ? "msw" : opts.middleware ? "middleware" : opts.guards ? "guards" : opts.reactQuery ? "react-query" : opts.zod ? "zod" : opts.handlers ? "handlers" : opts.client ? "client" : undefined;
+    async function generate() {
+        const result = await (0, api_client_1.fetchCodegen)({
+            functionName,
+            env: opts.env,
+            language,
+            format,
+        });
+        return result.types;
+    }
+    if (opts.watch) {
+        console.log(chalk_1.default.gray("\n  Watching for type changes (polling every 5s)...\n"));
+        console.log(chalk_1.default.gray("  Press Ctrl+C to stop.\n"));
+        let lastOutput = "";
+        const poll = async () => {
+            try {
+                const types = await generate();
+                if (types !== lastOutput) {
+                    lastOutput = types;
+                    if (opts.out) {
+                        writeToFile(opts.out, types, opts.python);
+                        console.log(chalk_1.default.green(`  Updated ${chalk_1.default.bold(opts.out)}`) +
+                            chalk_1.default.gray(` at ${new Date().toLocaleTimeString()}`));
+                    }
+                    else {
+                        console.clear();
+                        console.log(types);
+                    }
+                }
+            }
+            catch (err) {
+                if (err instanceof Error) {
+                    console.error(chalk_1.default.red(`  Error: ${err.message}`));
+                }
+            }
+        };
+        await poll();
+        const interval = setInterval(poll, 5000);
+        // Keep process alive until Ctrl+C
+        process.on("SIGINT", () => {
+            clearInterval(interval);
+            console.log(chalk_1.default.gray("\n  Stopped watching.\n"));
+            process.exit(0);
+        });
+        // Prevent the process from exiting
+        await new Promise(() => { });
+        return;
+    }
+    // One-shot generation
+    try {
+        const types = await generate();
+        if (opts.out) {
+            writeToFile(opts.out, types, opts.python);
+            const ext = opts.python ? ".pyi" : ".d.ts";
+            console.log("");
+            console.log(chalk_1.default.green(`  Types written to ${chalk_1.default.bold(opts.out)}`));
+            console.log(chalk_1.default.gray(`  ${countInterfaces(types)} type definitions generated.`));
+            console.log("");
+        }
+        else {
+            console.log("");
+            console.log(types);
+        }
+    }
+    catch (err) {
+        if (err instanceof Error) {
+            console.error(chalk_1.default.red(`\n  Error: ${err.message}\n`));
+        }
+        process.exit(1);
+    }
+}
+function writeToFile(filePath, content, _python) {
+    const resolvedPath = path.resolve(filePath);
+    const dir = path.dirname(resolvedPath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(resolvedPath, content, "utf-8");
+}
+function countInterfaces(types) {
+    const tsMatches = types.match(/export (interface|type) /g);
+    const pyMatches = types.match(/class \w+\(TypedDict\)/g);
+    return (tsMatches?.length ?? 0) + (pyMatches?.length ?? 0);
+}

package/dist/commands/coverage.d.ts

@@ -0,0 +1,13 @@
+export interface CoverageOptions {
+    env?: string;
+    json?: boolean;
+    failUnder?: string;
+    staleHours?: string;
+}
+/**
+ * `trickle coverage` — Type observation health report.
+ *
+ * Shows per-function type coverage, staleness, variant counts,
+ * error counts, and an overall health score. Useful for CI gates.
+ */
+export declare function coverageCommand(opts: CoverageOptions): Promise<void>;