@fatagnus/convex-sync-check 0.1.1

package/bin/convex-sync-check.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import("../dist/cli.js").then((m) => m.main()).catch((err) => {
+  console.error("Unexpected error:", err.message);
+  process.exit(2);
+});

package/dist/chunk-HARLMPMI.js

@@ -0,0 +1,222 @@
+// src/scanner/backend.ts
+import { readdirSync, readFileSync, statSync } from "fs";
+import { join, relative, sep } from "path";
+var BUILTIN_PUBLIC = /* @__PURE__ */ new Set(["query", "mutation", "action"]);
+var BUILTIN_INTERNAL = /* @__PURE__ */ new Set([
+  "internalQuery",
+  "internalMutation",
+  "internalAction"
+]);
+var SKIP_DIRS = /* @__PURE__ */ new Set(["_generated", "node_modules"]);
+var SKIP_FILE_PATTERNS = [/\.test\.ts$/, /\.spec\.ts$/];
+function scanBackend(convexDir, functionWrappers) {
+  const files = collectTsFiles(convexDir);
+  const defs = [];
+  const allPublic = new Set(BUILTIN_PUBLIC);
+  const allInternal = new Set(BUILTIN_INTERNAL);
+  if (functionWrappers) {
+    for (const [name, visibility] of Object.entries(functionWrappers)) {
+      if (visibility === "public") allPublic.add(name);
+      else allInternal.add(name);
+    }
+  }
+  const typePattern = [...allPublic, ...allInternal].map((t) => escapeRegex(t)).join("|");
+  const regex = new RegExp(
+    `^export\\s+const\\s+(\\w+)\\s*=\\s*(${typePattern})\\s*\\(`,
+    "gm"
+  );
+  for (const file of files) {
+    const content = readFileSync(file, "utf-8");
+    const relPath = relative(convexDir, file);
+    const modulePath = relPath.replace(/\.ts$/, "").split(sep).join(".");
+    let match;
+    regex.lastIndex = 0;
+    while ((match = regex.exec(content)) !== null) {
+      const name = match[1];
+      const fnType = match[2];
+      if (fnType === "httpAction") continue;
+      const line = content.substring(0, match.index).split("\n").length;
+      defs.push({
+        name,
+        apiPath: `${modulePath}.${name}`,
+        type: fnType,
+        isInternal: allInternal.has(fnType),
+        file,
+        line
+      });
+    }
+  }
+  return defs;
+}
+function collectTsFiles(dir) {
+  const results = [];
+  function walk(current) {
+    const entries = readdirSync(current);
+    for (const entry of entries) {
+      const fullPath = join(current, entry);
+      const stat = statSync(fullPath);
+      if (stat.isDirectory()) {
+        if (!SKIP_DIRS.has(entry)) walk(fullPath);
+      } else if (entry.endsWith(".ts") && !SKIP_FILE_PATTERNS.some((p) => p.test(entry))) {
+        results.push(fullPath);
+      }
+    }
+  }
+  walk(dir);
+  return results;
+}
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// src/scanner/frontend.ts
+import { readdirSync as readdirSync2, readFileSync as readFileSync2, statSync as statSync2 } from "fs";
+import { join as join2 } from "path";
+var EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx"]);
+var SKIP_DIRS2 = /* @__PURE__ */ new Set(["node_modules", "__tests__", "_generated"]);
+var SKIP_FILE_PATTERNS2 = [/\.test\.\w+$/, /\.spec\.\w+$/];
+var API_PATTERN = /\bapi\.([a-zA-Z_]\w*(?:\.[a-zA-Z_]\w*)+)/g;
+function scanFrontend(frontendDirs) {
+  const refs = [];
+  for (const dir of frontendDirs) {
+    const files = collectSourceFiles(dir);
+    for (const file of files) {
+      const content = readFileSync2(file, "utf-8");
+      const lines = content.split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*")) {
+          continue;
+        }
+        const stripped = line.replace(/\/\/.*$/, "").replace(/\/\*.*?\*\//g, "");
+        let match;
+        API_PATTERN.lastIndex = 0;
+        while ((match = API_PATTERN.exec(stripped)) !== null) {
+          refs.push({
+            apiPath: match[1],
+            file,
+            line: i + 1
+          });
+        }
+      }
+    }
+  }
+  return refs;
+}
+function collectSourceFiles(dir) {
+  const results = [];
+  function walk(current) {
+    let entries;
+    try {
+      entries = readdirSync2(current);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = join2(current, entry);
+      let stat;
+      try {
+        stat = statSync2(fullPath);
+      } catch {
+        continue;
+      }
+      if (stat.isDirectory()) {
+        if (!SKIP_DIRS2.has(entry)) walk(fullPath);
+      } else {
+        const ext = entry.slice(entry.lastIndexOf("."));
+        if (EXTENSIONS.has(ext) && !SKIP_FILE_PATTERNS2.some((p) => p.test(entry))) {
+          results.push(fullPath);
+        }
+      }
+    }
+  }
+  walk(dir);
+  return results;
+}
+
+// src/analyzer.ts
+function analyze(defs, refs) {
+  const defMap = /* @__PURE__ */ new Map();
+  for (const def of defs) {
+    defMap.set(def.apiPath, def);
+  }
+  const refGroups = /* @__PURE__ */ new Map();
+  for (const ref of refs) {
+    const group = refGroups.get(ref.apiPath) ?? [];
+    group.push({ file: ref.file, line: ref.line });
+    refGroups.set(ref.apiPath, group);
+  }
+  const errors = [];
+  for (const [apiPath, locations] of refGroups) {
+    const def = defMap.get(apiPath);
+    if (!def) {
+      errors.push({
+        type: "MISSING_DEFINITION",
+        apiPath,
+        locations
+      });
+    } else if (def.isInternal) {
+      errors.push({
+        type: "INTERNAL_CALLED_FROM_FRONTEND",
+        apiPath,
+        locations
+      });
+    }
+  }
+  const warnings = [];
+  for (const def of defs) {
+    if (!def.isInternal && !refGroups.has(def.apiPath)) {
+      warnings.push({
+        type: "UNREFERENCED",
+        apiPath: def.apiPath,
+        definition: {
+          type: def.type,
+          file: def.file,
+          line: def.line
+        }
+      });
+    }
+  }
+  return {
+    errors,
+    warnings,
+    passed: errors.length === 0
+  };
+}
+
+// src/index.ts
+function checkConvexSync(options) {
+  const defs = scanBackend(options.convexDir, options.functionWrappers);
+  const refs = scanFrontend(options.frontendDirs);
+  const { errors, warnings, passed } = analyze(defs, refs);
+  const publicFunctions = defs.filter((d) => !d.isInternal).length;
+  const internalFunctions = defs.filter((d) => d.isInternal).length;
+  const uniqueRefs = new Set(refs.map((r) => r.apiPath));
+  const uniqueModules = new Set(
+    defs.map((d) => {
+      const parts = d.apiPath.split(".");
+      return parts.slice(0, -1).join(".");
+    })
+  );
+  const filteredWarnings = options.suppressWarnings ? warnings.filter((w) => !options.suppressWarnings.includes(w.type)) : warnings;
+  return {
+    project: "",
+    convexDir: options.convexDir,
+    frontendDirs: options.frontendDirs,
+    stats: {
+      definedFunctions: defs.length,
+      publicFunctions,
+      internalFunctions,
+      frontendRefs: uniqueRefs.size,
+      backendModules: uniqueModules.size
+    },
+    errors,
+    warnings: filteredWarnings,
+    passed
+  };
+}
+
+export {
+  checkConvexSync
+};

package/dist/cli.d.ts

@@ -0,0 +1,16 @@
+interface CliArgs {
+    convexDir?: string;
+    frontendDir?: string;
+    deployed: boolean;
+    json: boolean;
+    noWarnings: boolean;
+    ignore?: string;
+    config?: string;
+    verbose: boolean;
+    version: boolean;
+    help: boolean;
+}
+declare function parseCliArgs(argv: string[]): CliArgs;
+declare function main(): Promise<void>;
+
+export { main, parseCliArgs };

package/dist/cli.js

@@ -0,0 +1,286 @@
+import {
+  checkConvexSync
+} from "./chunk-HARLMPMI.js";
+
+// src/cli.ts
+import { parseArgs } from "util";
+import { resolve } from "path";
+import { existsSync as existsSync3 } from "fs";
+
+// src/config.ts
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+var DEFAULT_CONFIG_NAME = ".convex-sync-check.json";
+function loadConfig(cwd, configPath) {
+  const path = configPath ?? join(cwd, DEFAULT_CONFIG_NAME);
+  if (!existsSync(path)) {
+    return {};
+  }
+  try {
+    const content = readFileSync(path, "utf-8");
+    return JSON.parse(content);
+  } catch (err) {
+    throw new Error(`Failed to parse config file ${path}: ${err.message}`);
+  }
+}
+
+// src/detector.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2, readdirSync, statSync } from "fs";
+import { join as join2, basename } from "path";
+var FRONTEND_DIRS = ["src", "app", "pages"];
+function detectLayout(cwd) {
+  const project = getProjectName(cwd);
+  const convexDir = findConvexDir(cwd);
+  const frontendDirs = findFrontendDirs(cwd);
+  return { project, convexDir, frontendDirs };
+}
+function getProjectName(cwd) {
+  const pkgPath = join2(cwd, "package.json");
+  if (existsSync2(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync2(pkgPath, "utf-8"));
+      if (pkg.name) return pkg.name;
+    } catch {
+    }
+  }
+  return basename(cwd);
+}
+function findConvexDir(cwd) {
+  const candidate = join2(cwd, "convex");
+  if (existsSync2(candidate) && statSync(candidate).isDirectory() && existsSync2(join2(candidate, "_generated"))) {
+    return candidate;
+  }
+  return null;
+}
+function findFrontendDirs(cwd) {
+  const dirs = [];
+  for (const name of FRONTEND_DIRS) {
+    const candidate = join2(cwd, name);
+    if (existsSync2(candidate) && statSync(candidate).isDirectory()) {
+      if (containsSourceFiles(candidate)) {
+        dirs.push(candidate);
+      }
+    }
+  }
+  return dirs;
+}
+function containsSourceFiles(dir) {
+  try {
+    const entries = readdirSync(dir);
+    for (const entry of entries) {
+      if (/\.(tsx?|jsx?)$/.test(entry)) return true;
+      const full = join2(dir, entry);
+      if (statSync(full).isDirectory() && entry !== "node_modules") {
+        if (containsSourceFiles(full)) return true;
+      }
+    }
+  } catch {
+  }
+  return false;
+}
+
+// src/reporter/human.ts
+function formatHuman(result) {
+  const lines = [];
+  lines.push("");
+  lines.push("\u2550\u2550\u2550 Convex Function Sync Check \u2550\u2550\u2550");
+  lines.push("");
+  lines.push(`  Project:           ${result.project}`);
+  lines.push(`  Convex dir:        ${result.convexDir}`);
+  lines.push(`  Frontend dir:      ${result.frontendDirs.join(", ")}`);
+  lines.push(
+    `  Defined functions: ${result.stats.definedFunctions} (${result.stats.publicFunctions} public, ${result.stats.internalFunctions} internal)`
+  );
+  lines.push(`  Frontend refs:     ${result.stats.frontendRefs} unique api paths`);
+  lines.push(`  Backend modules:   ${result.stats.backendModules}`);
+  lines.push("");
+  const missingDefs = result.errors.filter(
+    (e) => e.type === "MISSING_DEFINITION"
+  );
+  const internalLeaks = result.errors.filter(
+    (e) => e.type === "INTERNAL_CALLED_FROM_FRONTEND"
+  );
+  const notDeployed = result.errors.filter(
+    (e) => e.type === "NOT_DEPLOYED"
+  );
+  if (missingDefs.length > 0) {
+    lines.push(
+      `\u2717 ${missingDefs.length} function(s) referenced but NOT defined:`
+    );
+    lines.push("");
+    for (const err of missingDefs) {
+      lines.push(`  \u2717 api.${err.apiPath}`);
+      for (const loc of err.locations) {
+        lines.push(`    \u2192 ${loc.file}:${loc.line}`);
+      }
+      lines.push("");
+    }
+  }
+  if (internalLeaks.length > 0) {
+    lines.push(
+      `\u2717 ${internalLeaks.length} internal function(s) called from frontend:`
+    );
+    lines.push("");
+    for (const err of internalLeaks) {
+      lines.push(`  \u2717 api.${err.apiPath} (internal \u2014 should not be called from frontend)`);
+      for (const loc of err.locations) {
+        lines.push(`    \u2192 ${loc.file}:${loc.line}`);
+      }
+      lines.push("");
+    }
+  }
+  if (notDeployed.length > 0) {
+    lines.push(
+      `\u2717 ${notDeployed.length} function(s) defined but NOT deployed:`
+    );
+    lines.push("");
+    for (const err of notDeployed) {
+      lines.push(`  \u2717 api.${err.apiPath}`);
+      for (const loc of err.locations) {
+        lines.push(`    \u2192 ${loc.file}:${loc.line}`);
+      }
+      lines.push("");
+    }
+  }
+  if (result.warnings.length > 0) {
+    lines.push(
+      `\u26A0 ${result.warnings.length} public function(s) defined but not referenced from frontend:`
+    );
+    lines.push("");
+    for (const warn of result.warnings) {
+      lines.push(`  \u25CB api.${warn.apiPath} (${warn.definition.type})`);
+      lines.push(`    ${warn.definition.file}:${warn.definition.line}`);
+    }
+    lines.push("");
+  }
+  if (result.passed) {
+    lines.push("PASS \u2014 All Convex function references are in sync.");
+  } else {
+    lines.push("FAIL \u2014 Convex function sync issues found.");
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+// src/reporter/json.ts
+function formatJson(result) {
+  return JSON.stringify(result, null, 2);
+}
+
+// src/cli.ts
+function parseCliArgs(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      "convex-dir": { type: "string" },
+      "frontend-dir": { type: "string" },
+      deployed: { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+      "no-warnings": { type: "boolean", default: false },
+      ignore: { type: "string" },
+      config: { type: "string" },
+      verbose: { type: "boolean", short: "v", default: false },
+      version: { type: "boolean", default: false },
+      help: { type: "boolean", default: false }
+    },
+    strict: true
+  });
+  return {
+    convexDir: values["convex-dir"],
+    frontendDir: values["frontend-dir"],
+    deployed: values.deployed,
+    json: values.json,
+    noWarnings: values["no-warnings"],
+    ignore: values.ignore,
+    config: values.config,
+    verbose: values.verbose,
+    version: values.version,
+    help: values.help
+  };
+}
+var HELP_TEXT = `
+Usage: convex-sync-check [options]
+
+Options:
+  --convex-dir <path>     Path to convex/ directory (auto-detected if omitted)
+  --frontend-dir <path>   Path to frontend source directory (auto-detected if omitted)
+  --deployed              Also check deployed functions via \`npx convex functions\`
+  --json                  Output as JSON (for programmatic consumption)
+  --no-warnings           Suppress unreferenced function warnings
+  --ignore <patterns>     Comma-separated glob patterns to ignore
+  --config <path>         Path to config file (default: .convex-sync-check.json)
+  -v, --verbose           Show detailed scan progress
+  --version               Show version
+  --help                  Show help
+`.trim();
+async function main() {
+  const args = parseCliArgs(process.argv.slice(2));
+  if (args.help) {
+    console.log(HELP_TEXT);
+    process.exit(0);
+  }
+  if (args.version) {
+    const { readFileSync: readFileSync3 } = await import("fs");
+    const { fileURLToPath } = await import("url");
+    const { join: join3, dirname } = await import("path");
+    const pkgPath = join3(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+    const pkg = JSON.parse(readFileSync3(pkgPath, "utf-8"));
+    console.log(pkg.version);
+    process.exit(0);
+  }
+  const cwd = process.cwd();
+  const config = loadConfig(cwd, args.config);
+  const layout = detectLayout(cwd);
+  const convexDir = resolve(
+    cwd,
+    args.convexDir ?? config.convexDir ?? (layout.convexDir ?? "")
+  );
+  if (!convexDir || !existsSync3(convexDir)) {
+    console.error(
+      "Error: Could not find convex/ directory. Use --convex-dir to specify."
+    );
+    process.exit(2);
+  }
+  const frontendDirs = args.frontendDir ? [resolve(cwd, args.frontendDir)] : (config.frontendDirs ?? []).length > 0 ? config.frontendDirs.map((d) => resolve(cwd, d)) : layout.frontendDirs;
+  if (frontendDirs.length === 0) {
+    console.error(
+      "Error: Could not find frontend source directory. Use --frontend-dir to specify."
+    );
+    process.exit(2);
+  }
+  const functionWrappers = {
+    ...config.functionWrappers
+  };
+  const suppressWarnings = args.noWarnings ? ["UNREFERENCED"] : config.suppressWarnings;
+  if (args.verbose) {
+    console.log(`Scanning backend: ${convexDir}`);
+    console.log(`Scanning frontend: ${frontendDirs.join(", ")}`);
+  }
+  const result = checkConvexSync({
+    convexDir,
+    frontendDirs,
+    functionWrappers: Object.keys(functionWrappers).length > 0 ? functionWrappers : void 0,
+    suppressWarnings,
+    verbose: args.verbose
+  });
+  result.project = layout.project;
+  result.convexDir = convexDir;
+  result.frontendDirs = frontendDirs;
+  if (args.json) {
+    console.log(formatJson(result));
+  } else {
+    console.log(formatHuman(result));
+  }
+  process.exit(result.passed ? 0 : 1);
+}
+var isDirectRun = typeof process !== "undefined" && process.argv[1] && (process.argv[1].endsWith("/cli.js") || process.argv[1].endsWith("/convex-sync-check.mjs"));
+if (isDirectRun) {
+  main().catch((err) => {
+    console.error("Unexpected error:", err.message);
+    process.exit(2);
+  });
+}
+export {
+  main,
+  parseCliArgs
+};

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+type ErrorType = "MISSING_DEFINITION" | "INTERNAL_CALLED_FROM_FRONTEND" | "NOT_DEPLOYED";
+type WarningType = "UNREFERENCED";
+interface SyncError {
+    type: ErrorType;
+    apiPath: string;
+    locations: Array<{
+        file: string;
+        line: number;
+    }>;
+}
+interface SyncWarning {
+    type: WarningType;
+    apiPath: string;
+    definition: {
+        type: string;
+        file: string;
+        line: number;
+    };
+}
+interface ScanStats {
+    definedFunctions: number;
+    publicFunctions: number;
+    internalFunctions: number;
+    frontendRefs: number;
+    backendModules: number;
+}
+interface CheckResult {
+    project: string;
+    convexDir: string;
+    frontendDirs: string[];
+    stats: ScanStats;
+    errors: SyncError[];
+    warnings: SyncWarning[];
+    passed: boolean;
+}
+interface CheckOptions {
+    convexDir?: string;
+    frontendDirs?: string[];
+    functionWrappers?: Record<string, "public" | "internal">;
+    ignore?: {
+        backend?: string[];
+        frontend?: string[];
+    };
+    suppressWarnings?: WarningType[];
+    deployed?: boolean;
+    verbose?: boolean;
+}
+
+declare function checkConvexSync(options: CheckOptions & {
+    convexDir: string;
+    frontendDirs: string[];
+}): CheckResult;
+
+export { type CheckOptions, type CheckResult, checkConvexSync };

package/dist/index.js

@@ -0,0 +1,6 @@
+import {
+  checkConvexSync
+} from "./chunk-HARLMPMI.js";
+export {
+  checkConvexSync
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@fatagnus/convex-sync-check",
+  "version": "0.1.1",
+  "description": "Zero-config CLI to check Convex frontend/backend function sync",
+  "type": "module",
+  "bin": {
+    "convex-sync-check": "./bin/convex-sync-check.mjs"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "convex",
+    "sync",
+    "check",
+    "lint",
+    "static-analysis"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.3.2",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}