viberails 0.6.11 → 0.6.13

package/README.md

@@ -0,0 +1,140 @@
+# viberails
+
+Guardrails for vibe coding.
+
+viberails scans your existing JavaScript/TypeScript project, detects the conventions you're already following, and enforces them with file-level feedback during AI edits and structured enforcement at commit and PR time. Rules are derived from your actual codebase, not a template.
+
+## Why
+
+AI coding tools are fast but inconsistent. They'll use camelCase in one file and kebab-case in another, create 500-line files, and ignore your project's import boundaries. viberails catches this by learning your conventions and enforcing them where it matters: file-level checks surface naming and size issues immediately during AI edits, while commit hooks and CI enforce naming, file-size, missing-test, and boundary rules. Coverage enforcement runs via `viberails check` (full mode).
+
+## Quick Start
+
+```bash
+cd your-project
+npx viberails
+```
+
+The interactive wizard scans your project, shows what it found with confidence levels, and lets you customize rules before generating config. It also sets up pre-commit hooks and Claude Code integration.
+If a config already exists, re-running `viberails` lets you edit it, replace it with a fresh scan, or cancel. `viberails config` remains available as a shortcut for direct rule editing.
+
+## What It Does
+
+**Scans** your codebase to detect framework, language, styling, tooling, directory structure, and naming conventions, each scored by consistency across your files.
+
+**Enforces** four rules:
+- **File size** — files over 300 lines (configurable) are flagged
+- **Naming conventions** — detects your naming style (kebab-case, camelCase, PascalCase, snake_case) and enforces it
+- **Missing tests** — source files must have corresponding test files
+- **Import boundaries** — prevents packages from importing where they shouldn't (monorepos)
+
+**Fixes** violations automatically:
+- Renames files to match your convention and updates relative imports via AST rewriting (aliased imports like `@/...` require manual updates)
+- Generates test stubs for missing test files
+
+## What It Generates
+
+| File | Purpose |
+|------|---------|
+| `viberails.config.json` | Detected stack, conventions, boundary rules, and thresholds |
+| `.viberails/context.md` | Enforced rules in natural language for AI tools to follow |
+| `.viberails/scan-result.json` | Raw scan data (gitignored) |
+
+The generated `context.md` is designed to be referenced from your `CLAUDE.md`, `.cursorrules`, or similar AI context files so that AI tools automatically follow your project's conventions.
+
+## Commands
+
+### `npx viberails` / `viberails init`
+
+Scans your project and walks you through setup. If a config already exists, the same command lets you edit the current setup or replace it with a fresh scan.
+
+| Flag | Effect |
+|------|--------|
+| `--yes` / `-y` | Non-interactive. Uses defaults, keeps high-confidence conventions, and auto-sets up integrations. |
+| `--force` / `-f` | Re-initialize from scratch, replacing existing config without the edit/replace chooser. |
+
+### `viberails check`
+
+Validates your project against configured rules.
+
+| Flag | Effect |
+|------|--------|
+| `--staged` | Check only git-staged files (used by pre-commit hook). |
+| `--files <paths>` | Check specific files. |
+| `--format json` | Machine-readable output for tool integration. |
+| `--quiet` | Summary only. |
+| `--enforce` | Return exit code 1 when violations are found (CI mode). |
+| `--diff-base <ref>` | Check only files changed since a git ref (useful in CI). |
+| `--hook` | Output via stdin/stderr for Claude Code hook integration. |
+
+### `viberails fix`
+
+Auto-fixes naming violations and generates missing test stubs.
+
+| Flag | Effect |
+|------|--------|
+| `--dry-run` | Preview changes without applying them. |
+| `--rule <name>` | Fix only `file-naming` or `missing-test`. |
+| `--yes` / `-y` | Apply fixes without confirmation. |
+
+### `viberails config`
+
+Interactively edit existing config rules without re-initializing. Opens the same rule menu used during `init` with your current values pre-filled. Most users can simply re-run `viberails`; this command is the direct shortcut.
+
+| Flag | Effect |
+|------|--------|
+| `--rescan` | Re-scan the project first, picking up new packages and stack changes. |
+
+### `viberails sync`
+
+Re-scans and regenerates context files. Preserves manual edits to `viberails.config.json` and reports what changed.
+
+| Flag | Effect |
+|------|--------|
+| `--interactive` / `-i` | Review changes before writing. Choose to accept, customize rules, or cancel. |
+
+### `viberails boundaries`
+
+Displays boundary rules and violations. Use `--infer` to re-infer rules from your current import graph.
+
+## Hooks
+
+During `viberails init`, you can set up automatic enforcement:
+
+### Pre-commit hook
+
+Detects your hook manager (Lefthook, Husky, or bare git) and adds `viberails check --staged`. Violations warn by default. Use `viberails check --enforce` (for CI) to make violations fail with exit code 1.
+
+### Claude Code hook
+
+Adds a PostToolUse hook to `.claude/settings.json` that runs fast file-scoped checks after every edit, surfacing naming and file-size issues immediately. Repository-level checks like missing tests and boundaries are enforced at commit and PR time via staged checks and CI. Coverage enforcement runs via `viberails check` (full mode) or your existing CI test pipeline.
+
+### GitHub Actions
+
+Generates a `.github/workflows/viberails.yml` workflow that runs `viberails check --enforce --diff-base` on pull requests, checking only files changed in the PR.
+
+### Typecheck & lint hooks
+
+Optionally adds `tsc --noEmit` and your linter (Biome, ESLint) as pre-commit checks during `viberails init`.
+
+## Confidence Model
+
+Not all conventions are equally consistent in a codebase. viberails scores each detection:
+
+| Level | Consistency | Behavior |
+|-------|-------------|----------|
+| **High** | >= 90% | Enforced by default |
+| **Medium** | 70-89% | Included in config, not enforced |
+| **Low** | < 70% | Omitted entirely |
+
+In `--yes` mode, only high-confidence conventions are included.
+
+## Monorepo Support
+
+viberails detects workspaces (pnpm, npm, yarn), scans each package independently, and infers import boundaries from your existing dependency graph. Packages that don't import from each other get automatic deny rules, preventing accidental coupling before it starts.
+
+Per-package convention overrides are detected and displayed during setup.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -99,8 +99,8 @@ var FILE_NAMING_OPTIONS = [
   { value: "snake_case", label: "snake_case" }
 ];
 var COMPONENT_NAMING_OPTIONS = [
-  { value: "PascalCase", label: "PascalCase", hint: "MyComponent.tsx" },
-  { value: "camelCase", label: "camelCase", hint: "myComponent.tsx" }
+  { value: "PascalCase", label: "PascalCase", hint: "e.g. MyComponent, UserProfile" },
+  { value: "camelCase", label: "camelCase", hint: "e.g. myComponent, userProfile" }
 ];
 var HOOK_NAMING_OPTIONS = [
   { value: "useXxx", label: "useXxx", hint: "useAuth, useFormData" },
@@ -3008,7 +3008,169 @@ var clack11 = __toESM(require("@clack/prompts"), 1);
 
 // src/utils/prompt-main-menu-handlers.ts
 var clack10 = __toESM(require("@clack/prompts"), 1);
+var import_chalk13 = __toESM(require("chalk"), 1);
+
+// src/utils/prompt-main-menu-hints.ts
 var import_chalk12 = __toESM(require("chalk"), 1);
+function fileLimitsHint(config) {
+  const max = config.rules.maxFileLines;
+  const test = config.rules.maxTestFileLines;
+  return test > 0 ? `${max} lines, tests ${test}` : `${max} lines`;
+}
+function getEffectiveFileNaming(config) {
+  const rootPkg = getRootPackage(config.packages);
+  if (rootPkg.conventions?.fileNaming) {
+    return { naming: rootPkg.conventions.fileNaming, source: "root" };
+  }
+  if (config.packages.length > 1) {
+    const namingValues = config.packages.map((p) => p.conventions?.fileNaming).filter((n) => !!n);
+    if (namingValues.length > 0 && new Set(namingValues).size === 1) {
+      return { naming: namingValues[0], source: "consensus" };
+    }
+  }
+  return void 0;
+}
+function fileNamingHint(config, scanResult) {
+  if (!config.rules.enforceNaming) return "not enforced";
+  const effective = getEffectiveFileNaming(config);
+  if (effective) {
+    const detected = scanResult.packages.some(
+      (p) => p.conventions.fileNaming?.value === effective.naming && p.conventions.fileNaming.confidence !== "low"
+    );
+    return detected ? `${effective.naming} (detected)` : effective.naming;
+  }
+  return "not set \u2014 select to configure";
+}
+function fileNamingStatus(config) {
+  if (!config.rules.enforceNaming) return "unconfigured";
+  return getEffectiveFileNaming(config) ? "ok" : "needs-input";
+}
+function missingTestsHint(config) {
+  if (!config.rules.enforceMissingTests) return "not enforced";
+  const rootPkg = getRootPackage(config.packages);
+  const pattern = rootPkg.structure?.testPattern;
+  return pattern ? `enforced (${pattern})` : "enforced";
+}
+function coverageHint(config, hasTestRunner) {
+  if (config.rules.testCoverage === 0) return "disabled";
+  if (!hasTestRunner)
+    return `${config.rules.testCoverage}% target (inactive \u2014 no test runner)`;
+  const isMonorepo = config.packages.length > 1;
+  if (isMonorepo) {
+    const withCov = config.packages.filter(
+      (p) => (p.rules?.testCoverage ?? config.rules.testCoverage) > 0
+    );
+    const exempt = config.packages.length - withCov.length;
+    return exempt > 0 ? `${config.rules.testCoverage}% (${withCov.length}/${config.packages.length} packages, ${exempt} exempt)` : `${config.rules.testCoverage}%`;
+  }
+  return `${config.rules.testCoverage}%`;
+}
+function aiContextHint(config) {
+  const rootPkg = getRootPackage(config.packages);
+  const count = [
+    rootPkg.conventions?.componentNaming,
+    rootPkg.conventions?.hookNaming,
+    rootPkg.conventions?.importAlias
+  ].filter(Boolean).length;
+  if (count === 3) return "all set";
+  if (count > 0) return `${count} of 3 conventions`;
+  return "none set \u2014 optional AI guidelines";
+}
+function aiContextStatus(config) {
+  const rootPkg = getRootPackage(config.packages);
+  const count = [
+    rootPkg.conventions?.componentNaming,
+    rootPkg.conventions?.hookNaming,
+    rootPkg.conventions?.importAlias
+  ].filter(Boolean).length;
+  if (count === 3) return "ok";
+  if (count > 0) return "partial";
+  return "unconfigured";
+}
+function packageOverridesHint(config) {
+  const rootNaming = getRootPackage(config.packages).conventions?.fileNaming;
+  const editable = config.packages.filter((p) => p.path !== ".");
+  const customized = editable.filter(
+    (p) => p.rules || p.coverage || p.conventions?.fileNaming !== void 0 && p.conventions.fileNaming !== rootNaming
+  ).length;
+  return customized > 0 ? `${editable.length} packages (${customized} customized)` : `${editable.length} packages`;
+}
+function boundariesHint(config, state) {
+  if (!state.visited.boundaries || !config.rules.enforceBoundaries) return "not enabled";
+  const deny = config.boundaries?.deny;
+  if (!deny) return "enabled";
+  const ruleCount = Object.values(deny).reduce((s, a) => s + a.length, 0);
+  const pkgCount = Object.keys(deny).length;
+  return `${ruleCount} rules across ${pkgCount} packages`;
+}
+function packageOverridesStatus(config) {
+  const rootNaming = getRootPackage(config.packages).conventions?.fileNaming;
+  const editable = config.packages.filter((p) => p.path !== ".");
+  const customized = editable.some(
+    (p) => p.rules || p.coverage || p.conventions?.fileNaming !== void 0 && p.conventions.fileNaming !== rootNaming
+  );
+  return customized ? "ok" : "unconfigured";
+}
+function statusIcon(status) {
+  if (status === "ok") return import_chalk12.default.green("\u2713");
+  if (status === "needs-input") return import_chalk12.default.yellow("?");
+  if (status === "unconfigured") return import_chalk12.default.dim("-");
+  return import_chalk12.default.yellow("~");
+}
+function buildMainMenuOptions(config, scanResult, state) {
+  const namingStatus = fileNamingStatus(config);
+  const coverageStatus = config.rules.testCoverage === 0 ? "unconfigured" : !state.hasTestRunner ? "partial" : "ok";
+  const missingTestsStatus = config.rules.enforceMissingTests ? "ok" : "unconfigured";
+  const options = [
+    {
+      value: "fileLimits",
+      label: `${statusIcon("ok")} Max file size`,
+      hint: fileLimitsHint(config)
+    },
+    {
+      value: "fileNaming",
+      label: `${statusIcon(namingStatus)} File naming`,
+      hint: fileNamingHint(config, scanResult)
+    },
+    {
+      value: "missingTests",
+      label: `${statusIcon(missingTestsStatus)} Missing tests`,
+      hint: missingTestsHint(config)
+    },
+    {
+      value: "coverage",
+      label: `${statusIcon(coverageStatus)} Coverage`,
+      hint: coverageHint(config, state.hasTestRunner)
+    },
+    {
+      value: "aiContext",
+      label: `${statusIcon(aiContextStatus(config))} AI context`,
+      hint: aiContextHint(config)
+    }
+  ];
+  if (config.packages.length > 1) {
+    const bIcon = statusIcon(
+      state.visited.boundaries && config.rules.enforceBoundaries ? "ok" : "unconfigured"
+    );
+    const poIcon = statusIcon(packageOverridesStatus(config));
+    options.push(
+      {
+        value: "packageOverrides",
+        label: `${poIcon} Per-package overrides`,
+        hint: packageOverridesHint(config)
+      },
+      { value: "boundaries", label: `${bIcon} Boundaries`, hint: boundariesHint(config, state) }
+    );
+  }
+  options.push(
+    { value: "reset", label: "  Reset all to defaults" },
+    { value: "review", label: "  Review scan details", hint: "detected stack & conventions" },
+    { value: "done", label: "  Done \u2014 write config" }
+  );
+  return options;
+}
+
+// src/utils/prompt-main-menu-handlers.ts
 async function handleFileNaming(config, scanResult) {
   const isMonorepo = config.packages.length > 1;
   if (isMonorepo) {
@@ -3032,10 +3194,11 @@ async function handleFileNaming(config, scanResult) {
     return { value: opt.value, label: opt.label };
   });
   const rootPkg = getRootPackage(config.packages);
+  const effective = getEffectiveFileNaming(config);
   const selected = await clack10.select({
     message: isMonorepo ? "Default file naming convention" : "File naming convention",
     options: [...namingOptions, { value: SENTINEL_SKIP, label: "Don't enforce" }],
-    initialValue: rootPkg.conventions?.fileNaming ?? SENTINEL_SKIP
+    initialValue: effective?.naming ?? SENTINEL_SKIP
   });
   if (isCancelled(selected)) return;
   if (selected === SENTINEL_SKIP) {
@@ -3152,8 +3315,8 @@ async function handleAiContext(config) {
   const rootPkg = getRootPackage(config.packages);
   rootPkg.conventions = rootPkg.conventions ?? {};
   while (true) {
-    const ok = import_chalk12.default.green("\u2713");
-    const unset = import_chalk12.default.dim("-");
+    const ok = import_chalk13.default.green("\u2713");
+    const unset = import_chalk13.default.dim("-");
     const options = [
       {
         value: "componentNaming",
@@ -3235,155 +3398,6 @@ async function handleAiContext(config) {
   }
 }
 
-// src/utils/prompt-main-menu-hints.ts
-var import_chalk13 = __toESM(require("chalk"), 1);
-function fileLimitsHint(config) {
-  const max = config.rules.maxFileLines;
-  const test = config.rules.maxTestFileLines;
-  return test > 0 ? `${max} lines, tests ${test}` : `${max} lines`;
-}
-function fileNamingHint(config, scanResult) {
-  const rootPkg = getRootPackage(config.packages);
-  const naming = rootPkg.conventions?.fileNaming;
-  if (!config.rules.enforceNaming) return "not enforced";
-  if (naming) {
-    const detected = scanResult.packages.some(
-      (p) => p.conventions.fileNaming?.value === naming && p.conventions.fileNaming.confidence === "high"
-    );
-    return detected ? `${naming} (detected)` : naming;
-  }
-  return "not set \u2014 select to configure";
-}
-function fileNamingStatus(config) {
-  if (!config.rules.enforceNaming) return "unconfigured";
-  const rootPkg = getRootPackage(config.packages);
-  return rootPkg.conventions?.fileNaming ? "ok" : "needs-input";
-}
-function missingTestsHint(config) {
-  if (!config.rules.enforceMissingTests) return "not enforced";
-  const rootPkg = getRootPackage(config.packages);
-  const pattern = rootPkg.structure?.testPattern;
-  return pattern ? `enforced (${pattern})` : "enforced";
-}
-function coverageHint(config, hasTestRunner) {
-  if (config.rules.testCoverage === 0) return "disabled";
-  if (!hasTestRunner)
-    return `${config.rules.testCoverage}% target (inactive \u2014 no test runner)`;
-  const isMonorepo = config.packages.length > 1;
-  if (isMonorepo) {
-    const withCov = config.packages.filter(
-      (p) => (p.rules?.testCoverage ?? config.rules.testCoverage) > 0
-    );
-    const exempt = config.packages.length - withCov.length;
-    return exempt > 0 ? `${config.rules.testCoverage}% (${withCov.length}/${config.packages.length} packages, ${exempt} exempt)` : `${config.rules.testCoverage}%`;
-  }
-  return `${config.rules.testCoverage}%`;
-}
-function aiContextHint(config) {
-  const rootPkg = getRootPackage(config.packages);
-  const count = [
-    rootPkg.conventions?.componentNaming,
-    rootPkg.conventions?.hookNaming,
-    rootPkg.conventions?.importAlias
-  ].filter(Boolean).length;
-  if (count === 3) return "all set";
-  if (count > 0) return `${count} of 3 conventions`;
-  return "none set \u2014 optional AI guidelines";
-}
-function aiContextStatus(config) {
-  const rootPkg = getRootPackage(config.packages);
-  const count = [
-    rootPkg.conventions?.componentNaming,
-    rootPkg.conventions?.hookNaming,
-    rootPkg.conventions?.importAlias
-  ].filter(Boolean).length;
-  if (count === 3) return "ok";
-  if (count > 0) return "partial";
-  return "unconfigured";
-}
-function packageOverridesHint(config) {
-  const rootNaming = getRootPackage(config.packages).conventions?.fileNaming;
-  const editable = config.packages.filter((p) => p.path !== ".");
-  const customized = editable.filter(
-    (p) => p.rules || p.coverage || p.conventions?.fileNaming !== void 0 && p.conventions.fileNaming !== rootNaming
-  ).length;
-  return customized > 0 ? `${editable.length} packages (${customized} customized)` : `${editable.length} packages`;
-}
-function boundariesHint(config, state) {
-  if (!state.visited.boundaries || !config.rules.enforceBoundaries) return "not enabled";
-  const deny = config.boundaries?.deny;
-  if (!deny) return "enabled";
-  const ruleCount = Object.values(deny).reduce((s, a) => s + a.length, 0);
-  const pkgCount = Object.keys(deny).length;
-  return `${ruleCount} rules across ${pkgCount} packages`;
-}
-function packageOverridesStatus(config) {
-  const rootNaming = getRootPackage(config.packages).conventions?.fileNaming;
-  const editable = config.packages.filter((p) => p.path !== ".");
-  const customized = editable.some(
-    (p) => p.rules || p.coverage || p.conventions?.fileNaming !== void 0 && p.conventions.fileNaming !== rootNaming
-  );
-  return customized ? "ok" : "unconfigured";
-}
-function statusIcon(status) {
-  if (status === "ok") return import_chalk13.default.green("\u2713");
-  if (status === "needs-input") return import_chalk13.default.yellow("?");
-  if (status === "unconfigured") return import_chalk13.default.dim("-");
-  return import_chalk13.default.yellow("~");
-}
-function buildMainMenuOptions(config, scanResult, state) {
-  const namingStatus = fileNamingStatus(config);
-  const coverageStatus = config.rules.testCoverage === 0 ? "unconfigured" : !state.hasTestRunner ? "partial" : "ok";
-  const missingTestsStatus = config.rules.enforceMissingTests ? "ok" : "unconfigured";
-  const options = [
-    {
-      value: "fileLimits",
-      label: `${statusIcon("ok")} Max file size`,
-      hint: fileLimitsHint(config)
-    },
-    {
-      value: "fileNaming",
-      label: `${statusIcon(namingStatus)} File naming`,
-      hint: fileNamingHint(config, scanResult)
-    },
-    {
-      value: "missingTests",
-      label: `${statusIcon(missingTestsStatus)} Missing tests`,
-      hint: missingTestsHint(config)
-    },
-    {
-      value: "coverage",
-      label: `${statusIcon(coverageStatus)} Coverage`,
-      hint: coverageHint(config, state.hasTestRunner)
-    },
-    {
-      value: "aiContext",
-      label: `${statusIcon(aiContextStatus(config))} AI context`,
-      hint: aiContextHint(config)
-    }
-  ];
-  if (config.packages.length > 1) {
-    const bIcon = statusIcon(
-      state.visited.boundaries && config.rules.enforceBoundaries ? "ok" : "unconfigured"
-    );
-    const poIcon = statusIcon(packageOverridesStatus(config));
-    options.push(
-      {
-        value: "packageOverrides",
-        label: `${poIcon} Per-package overrides`,
-        hint: packageOverridesHint(config)
-      },
-      { value: "boundaries", label: `${bIcon} Boundaries`, hint: boundariesHint(config, state) }
-    );
-  }
-  options.push(
-    { value: "reset", label: "  Reset all to defaults" },
-    { value: "review", label: "  Review scan details", hint: "detected stack & conventions" },
-    { value: "done", label: "  Done \u2014 write config" }
-  );
-  return options;
-}
-
 // src/utils/prompt-main-menu.ts
 async function promptMainMenu(config, scanResult, opts) {
   const originalConfig = structuredClone(config);
@@ -4325,7 +4339,7 @@ ${import_chalk19.default.bold("Synced:")}`);
 }
 
 // src/index.ts
-var VERSION = "0.6.11";
+var VERSION = "0.6.13";
 var program = new import_commander.Command();
 program.name("viberails").description("Guardrails for vibe coding").version(VERSION);
 program.command("init", { isDefault: true }).description("Scan your project and set up enforcement guardrails").option("-y, --yes", "Non-interactive mode (use defaults, high-confidence only)").option("-f, --force", "Re-initialize, replacing existing config").action(async (options) => {