vigiles 2.0.0 → 2.2.0

package/src/generate-types.ts

@@ -1,448 +0,0 @@
-/**
- * vigiles generate-types — emit .d.ts with type unions from actual project state.
- *
- * Scans linter configs, package.json, and filesystem to generate TypeScript
- * types that the compiler uses to PROVE references are valid at authoring time.
- *
- * Generated types:
- *   - EslintRule / StylelintRule / RuffRule / ... — enabled rules per linter
- *   - NpmScript — scripts from package.json
- *   - ProjectFile — files in the project (scoped to src/ by default)
- */
-
-import { existsSync, readFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { execSync } from "node:child_process";
-import { globSync } from "glob";
-
-// ---------------------------------------------------------------------------
-// Linter config detection
-// ---------------------------------------------------------------------------
-
-function fileContainsSection(filePath: string, section: string): boolean {
-  if (!existsSync(filePath)) return false;
-  try {
-    return readFileSync(filePath, "utf-8").includes(section);
-  } catch {
-    return false;
-  }
-}
-
-function hasRuffConfig(basePath: string): boolean {
-  return (
-    existsSync(resolve(basePath, "ruff.toml")) ||
-    existsSync(resolve(basePath, ".ruff.toml")) ||
-    fileContainsSection(resolve(basePath, "pyproject.toml"), "[tool.ruff")
-  );
-}
-
-function hasPylintConfig(basePath: string): boolean {
-  return (
-    existsSync(resolve(basePath, ".pylintrc")) ||
-    existsSync(resolve(basePath, "pylintrc")) ||
-    fileContainsSection(resolve(basePath, "pyproject.toml"), "[tool.pylint") ||
-    fileContainsSection(resolve(basePath, "setup.cfg"), "[pylint")
-  );
-}
-
-function hasRubocopConfig(basePath: string): boolean {
-  return existsSync(resolve(basePath, ".rubocop.yml"));
-}
-
-// ---------------------------------------------------------------------------
-// Linter rule discovery
-// ---------------------------------------------------------------------------
-
-interface DiscoveredRules {
-  linter: string;
-  rules: string[];
-  via: string;
-}
-
-function discoverEslintRules(basePath: string): DiscoveredRules | null {
-  try {
-    const script = `
-      const { loadESLint } = require("eslint");
-      (async () => {
-        try {
-          const ESLint = await loadESLint();
-          const eslint = new ESLint({ cwd: ${JSON.stringify(basePath)} });
-          const config = await eslint.calculateConfigForFile("dummy.js");
-          const enabled = Object.entries(config.rules || {})
-            .filter(([, v]) => {
-              const sev = Array.isArray(v) ? v[0] : v;
-              return sev !== 0 && sev !== "off";
-            })
-            .map(([k]) => k);
-          console.log(JSON.stringify(enabled));
-        } catch(e) {
-          console.log("[]");
-        }
-      })();
-    `;
-    const output = execSync(`node -e '${script.replace(/'/g, "'\\''")}'`, {
-      encoding: "utf-8",
-      cwd: basePath,
-      stdio: ["pipe", "pipe", "pipe"],
-      timeout: 15000,
-    });
-    const rules = JSON.parse(output.trim() || "[]") as string[];
-    if (rules.length === 0) return null;
-    return { linter: "eslint", rules, via: "flat config" };
-  } catch {
-    return null;
-  }
-}
-
-function discoverStylelintRules(basePath: string): DiscoveredRules | null {
-  try {
-    const script = `
-      const stylelint = require("stylelint");
-      (async () => {
-        try {
-          const linter = stylelint.createLinter({});
-          const result = await linter.getConfigForFile(${JSON.stringify(resolve(basePath, "dummy.css"))});
-          const enabled = Object.entries(result.config.rules || {})
-            .filter(([, v]) => v !== null && !(Array.isArray(v) && v[0] === null))
-            .map(([k]) => k);
-          console.log(JSON.stringify(enabled));
-        } catch(e) {
-          console.log("[]");
-        }
-      })();
-    `;
-    const output = execSync(`node -e '${script.replace(/'/g, "'\\''")}'`, {
-      encoding: "utf-8",
-      cwd: basePath,
-      stdio: ["pipe", "pipe", "pipe"],
-      timeout: 15000,
-    });
-    const rules = JSON.parse(output.trim() || "[]") as string[];
-    if (rules.length === 0) return null;
-    return { linter: "stylelint", rules, via: "config" };
-  } catch {
-    return null;
-  }
-}
-
-function discoverRuffRules(basePath: string): DiscoveredRules | null {
-  try {
-    if (!hasRuffConfig(basePath)) return null;
-    execSync("which ruff", { stdio: "ignore" });
-    const dummyPath = resolve(basePath, "dummy.py");
-    const output = execSync(`ruff check --show-settings ${dummyPath}`, {
-      encoding: "utf-8",
-      cwd: basePath,
-      stdio: ["pipe", "pipe", "pipe"],
-      timeout: 10000,
-    });
-    const enabledMatch = output.match(
-      /linter\.rules\.enabled\s*=\s*\[([\s\S]*?)\]/,
-    );
-    const rules: string[] = [];
-    if (enabledMatch?.[1]) {
-      const codeRe = /\(([A-Z]+\d*)\)/g;
-      let m: RegExpExecArray | null;
-      while ((m = codeRe.exec(enabledMatch[1])) !== null) {
-        rules.push(m[1]);
-      }
-    }
-    if (rules.length === 0) return null;
-    return { linter: "ruff", rules, via: "CLI" };
-  } catch {
-    return null;
-  }
-}
-
-function discoverPylintRules(basePath: string): DiscoveredRules | null {
-  try {
-    if (!hasPylintConfig(basePath)) return null;
-    execSync("which pylint", { stdio: "ignore" });
-    const output = execSync("pylint --list-msgs-enabled", {
-      encoding: "utf-8",
-      cwd: basePath,
-      stdio: ["pipe", "pipe", "pipe"],
-      timeout: 15000,
-    });
-    const disabledIdx = output.indexOf("Disabled messages:");
-    const enabledSection =
-      disabledIdx >= 0 ? output.substring(0, disabledIdx) : output;
-    // Extract rule IDs like (C0114), (W0611) etc.
-    const rules: string[] = [];
-    const idRe = /\(([A-Z]\d{4})\)/g;
-    let m: RegExpExecArray | null;
-    while ((m = idRe.exec(enabledSection)) !== null) {
-      rules.push(m[1]);
-    }
-    // Also extract symbolic names like "missing-module-docstring"
-    const nameRe = /^(\w[\w-]+)\s*\(/gm;
-    while ((m = nameRe.exec(enabledSection)) !== null) {
-      rules.push(m[1]);
-    }
-    if (rules.length === 0) return null;
-    return { linter: "pylint", rules, via: "CLI" };
-  } catch {
-    return null;
-  }
-}
-
-function discoverRubocopRules(basePath: string): DiscoveredRules | null {
-  try {
-    if (!hasRubocopConfig(basePath)) return null;
-    execSync("which rubocop", { stdio: "ignore" });
-    const output = execSync(
-      "rubocop --list-target-files --show-cops 2>/dev/null | head -500",
-      {
-        encoding: "utf-8",
-        cwd: basePath,
-        stdio: ["pipe", "pipe", "pipe"],
-        timeout: 15000,
-        shell: "/bin/sh",
-      },
-    );
-    const rules: string[] = [];
-    const copRe = /^(\w+\/\w+):/gm;
-    let m: RegExpExecArray | null;
-    while ((m = copRe.exec(output)) !== null) {
-      rules.push(m[1]);
-    }
-    if (rules.length === 0) return null;
-    return { linter: "rubocop", rules, via: "CLI" };
-  } catch {
-    return null;
-  }
-}
-
-function discoverClippyRules(basePath: string): DiscoveredRules | null {
-  try {
-    const cargoPath = resolve(basePath, "Cargo.toml");
-    if (!existsSync(cargoPath)) return null;
-    execSync("which cargo", { stdio: "ignore" });
-    // Clippy doesn't have a good "list enabled lints" command.
-    // We read Cargo.toml [lints.clippy] section for explicit config,
-    // and include default warn/deny lints from clippy -W clippy::all
-    const content = readFileSync(cargoPath, "utf-8");
-    const sectionMatch = content.match(/\[lints\.clippy\]([\s\S]*?)(?=\n\[|$)/);
-    const rules: string[] = [];
-    if (sectionMatch?.[1]) {
-      const ruleRe = /^(\w[\w-]+)\s*=\s*"(\w+)"/gm;
-      let m: RegExpExecArray | null;
-      while ((m = ruleRe.exec(sectionMatch[1])) !== null) {
-        if (m[2] !== "allow") {
-          rules.push(m[1]);
-        }
-      }
-    }
-    if (rules.length === 0) return null;
-    return { linter: "clippy", rules, via: "Cargo.toml" };
-  } catch {
-    return null;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// NPM script discovery
-// ---------------------------------------------------------------------------
-
-function discoverNpmScripts(basePath: string): string[] {
-  const pkgPath = resolve(basePath, "package.json");
-  if (!existsSync(pkgPath)) return [];
-  try {
-    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as {
-      scripts?: Record<string, string>;
-    };
-    return Object.keys(pkg.scripts ?? {});
-  } catch {
-    return [];
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Project file discovery
-// ---------------------------------------------------------------------------
-
-function discoverProjectFiles(
-  basePath: string,
-  globs: string[] = ["src/**/*"],
-): string[] {
-  const files: string[] = [];
-  for (const pattern of globs) {
-    const matches = globSync(pattern, {
-      cwd: basePath,
-      ignore: ["node_modules/**", "dist/**", ".git/**"],
-      nodir: true,
-    });
-    files.push(...matches);
-  }
-  return [...new Set(files)].sort();
-}
-
-// ---------------------------------------------------------------------------
-// Type generation
-// ---------------------------------------------------------------------------
-
-function escapeForUnion(s: string): string {
-  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-}
-
-function formatUnion(items: string[], indent: string = "  "): string {
-  if (items.length === 0) return "never";
-  if (items.length <= 3) {
-    return items.map((i) => `"${escapeForUnion(i)}"`).join(" | ");
-  }
-  return (
-    "\n" + items.map((i) => `${indent}| "${escapeForUnion(i)}"`).join("\n")
-  );
-}
-
-export interface GenerateTypesOptions {
-  basePath?: string;
-  fileGlobs?: string[];
-}
-
-export interface GenerateTypesResult {
-  dts: string;
-  linters: DiscoveredRules[];
-  scripts: string[];
-  files: string[];
-}
-
-/**
- * Generate .d.ts content with type unions from actual project state.
- *
- * Scans all available linters, package.json scripts, and project files.
- */
-export function generateTypes(
-  options: GenerateTypesOptions = {},
-): GenerateTypesResult {
-  const basePath = options.basePath ?? process.cwd();
-  const fileGlobs = options.fileGlobs ?? ["src/**/*"];
-
-  // Discover everything
-  const linters: DiscoveredRules[] = [];
-
-  const eslint = discoverEslintRules(basePath);
-  if (eslint) linters.push(eslint);
-
-  const stylelint = discoverStylelintRules(basePath);
-  if (stylelint) linters.push(stylelint);
-
-  const ruff = discoverRuffRules(basePath);
-  if (ruff) linters.push(ruff);
-
-  const pylint = discoverPylintRules(basePath);
-  if (pylint) linters.push(pylint);
-
-  const rubocop = discoverRubocopRules(basePath);
-  if (rubocop) linters.push(rubocop);
-
-  const clippy = discoverClippyRules(basePath);
-  if (clippy) linters.push(clippy);
-
-  const scripts = discoverNpmScripts(basePath);
-  const files = discoverProjectFiles(basePath, fileGlobs);
-
-  // Generate .d.ts
-  const sections: string[] = [];
-
-  sections.push(`/**`);
-  sections.push(` * Auto-generated by \`vigiles generate-types\`.`);
-  sections.push(
-    ` * DO NOT EDIT — re-run \`vigiles generate-types\` to update.`,
-  );
-  sections.push(` */`);
-  sections.push(``);
-  // ---------------------------------------------------------------------------
-  // vigiles/generated — standalone types for direct import
-  // ---------------------------------------------------------------------------
-
-  sections.push(`declare module "vigiles/generated" {`);
-
-  // Linter rules
-  for (const { linter, rules, via } of linters) {
-    const typeName =
-      linter.charAt(0).toUpperCase() +
-      linter.slice(1).replace(/-([a-z])/g, (_, c: string) => c.toUpperCase()) +
-      "Rule";
-    sections.push(``);
-    sections.push(
-      `  /** ${String(rules.length)} enabled ${linter} rules (via ${via}). */`,
-    );
-    sections.push(`  export type ${typeName} = ${formatUnion(rules, "    ")};`);
-  }
-
-  // Combined linter rule type
-  if (linters.length > 0) {
-    const allNames = linters.map(
-      (l) =>
-        l.linter.charAt(0).toUpperCase() +
-        l.linter
-          .slice(1)
-          .replace(/-([a-z])/g, (_, c: string) => c.toUpperCase()) +
-        "Rule",
-    );
-    sections.push(``);
-    sections.push(
-      `  /** All enabled linter rules across all detected linters. */`,
-    );
-    sections.push(`  export type LinterRule = ${allNames.join(" | ")};`);
-  }
-
-  // NPM scripts
-  if (scripts.length > 0) {
-    sections.push(``);
-    sections.push(
-      `  /** ${String(scripts.length)} npm scripts from package.json. */`,
-    );
-    sections.push(`  export type NpmScript = ${formatUnion(scripts, "    ")};`);
-  }
-
-  // Project files
-  if (files.length > 0) {
-    sections.push(``);
-    sections.push(`  /** ${String(files.length)} project files. */`);
-    sections.push(`  export type ProjectFile = ${formatUnion(files, "    ")};`);
-  }
-
-  sections.push(`}`);
-
-  // ---------------------------------------------------------------------------
-  // vigiles/spec augmentation — populates KnownLinterRules, KnownProjectFiles,
-  // KnownNpmScripts interfaces so enforce(), file(), cmd() narrow automatically.
-  // ---------------------------------------------------------------------------
-
-  sections.push(``);
-  sections.push(`declare module "vigiles/spec" {`);
-
-  if (linters.length > 0) {
-    sections.push(`  interface KnownLinterRules {`);
-    for (const { linter, rules } of linters) {
-      sections.push(
-        `    "${escapeForUnion(linter)}": ${formatUnion(rules, "      ")};`,
-      );
-    }
-    sections.push(`  }`);
-  }
-
-  if (files.length > 0) {
-    sections.push(`  interface KnownProjectFiles {`);
-    sections.push(`    files: ${formatUnion(files, "      ")};`);
-    sections.push(`  }`);
-  }
-
-  if (scripts.length > 0) {
-    sections.push(`  interface KnownNpmScripts {`);
-    sections.push(`    scripts: ${formatUnion(scripts, "      ")};`);
-    sections.push(`  }`);
-  }
-
-  sections.push(`}`);
-  sections.push(``);
-
-  return {
-    dts: sections.join("\n"),
-    linters,
-    scripts,
-    files,
-  };
-}

package/src/inline.test.ts

@@ -1,206 +0,0 @@
-/**
- * Tests for the inline-rule parser.
- */
-
-import { describe, it } from "node:test";
-import assert from "node:assert/strict";
-
-import { parseInlineRules, hasInlineRules } from "./inline.js";
-
-describe("parseInlineRules", () => {
-  it("extracts a single enforce comment", () => {
-    const { rules, errors } = parseInlineRules(
-      `# Project
-
-<!-- vigiles:enforce eslint/no-console "Use structured logger" -->
-
-## Logging
-
-All output through logger.ts.
-`,
-    );
-    assert.equal(errors.length, 0);
-    assert.equal(rules.length, 1);
-    assert.equal(rules[0].linterRule, "eslint/no-console");
-    assert.equal(rules[0].why, "Use structured logger");
-    assert.equal(rules[0].line, 3);
-  });
-
-  it("extracts multiple enforce comments and tracks line numbers", () => {
-    const content = `# Doc
-<!-- vigiles:enforce eslint/no-console "a" -->
-text
-<!-- vigiles:enforce ruff/F401 "b" -->
-`;
-    const { rules, errors } = parseInlineRules(content);
-    assert.equal(errors.length, 0);
-    assert.equal(rules.length, 2);
-    assert.equal(rules[0].linterRule, "eslint/no-console");
-    assert.equal(rules[0].line, 2);
-    assert.equal(rules[1].linterRule, "ruff/F401");
-    assert.equal(rules[1].line, 4);
-  });
-
-  it("supports plugin-scoped rule names with slashes", () => {
-    const { rules, errors } = parseInlineRules(
-      `<!-- vigiles:enforce eslint/@typescript-eslint/no-floating-promises "Await or void" -->`,
-    );
-    assert.equal(errors.length, 0);
-    assert.equal(rules.length, 1);
-    assert.equal(
-      rules[0].linterRule,
-      "eslint/@typescript-eslint/no-floating-promises",
-    );
-  });
-
-  it("reports malformed vigiles:enforce as a parse error", () => {
-    const { rules, errors } = parseInlineRules(
-      `<!-- vigiles:enforce eslint/no-console no quotes here -->`,
-    );
-    assert.equal(rules.length, 0);
-    assert.equal(errors.length, 1);
-    assert.match(errors[0].message, /Malformed vigiles:enforce/);
-  });
-
-  it("reports unknown vigiles markers", () => {
-    const { rules, errors } = parseInlineRules(
-      `<!-- vigiles:strengthen eslint/no-console -->`,
-    );
-    assert.equal(rules.length, 0);
-    assert.equal(errors.length, 1);
-    assert.match(errors[0].message, /Unknown vigiles marker "strengthen"/);
-  });
-
-  it("returns empty results for a file with no vigiles comments", () => {
-    const { rules, errors } = parseInlineRules(
-      `# Plain\n\nJust prose, no rules.\n`,
-    );
-    assert.equal(rules.length, 0);
-    assert.equal(errors.length, 0);
-  });
-
-  it("skips the compiled-file hash marker without reporting an error", () => {
-    const { rules, errors } = parseInlineRules(
-      `<!-- vigiles:sha256:abc123 compiled from CLAUDE.md.spec.ts -->
-# Project
-<!-- vigiles:enforce eslint/no-console "why" -->
-`,
-    );
-    assert.equal(errors.length, 0, JSON.stringify(errors));
-    assert.equal(rules.length, 1);
-  });
-
-  it("ignores vigiles:enforce markers inside fenced code blocks", () => {
-    // Illustrative example in docs/inline-mode.md would otherwise get
-    // picked up as a live rule.
-    const { rules, errors } = parseInlineRules(
-      `# Docs
-
-Example usage:
-
-\`\`\`md
-<!-- vigiles:enforce eslint/no-console "Use structured logger" -->
-<!-- vigiles:enforce ruff/F401 "No unused imports" -->
-\`\`\`
-
-And a real one outside the fence:
-
-<!-- vigiles:enforce eslint/no-eval "Never eval user input" -->
-`,
-    );
-    assert.equal(errors.length, 0, JSON.stringify(errors));
-    assert.equal(rules.length, 1);
-    assert.equal(rules[0].linterRule, "eslint/no-eval");
-  });
-
-  it("ignores markers inside tilde-fenced code blocks", () => {
-    const { rules } = parseInlineRules(
-      `~~~md
-<!-- vigiles:enforce eslint/no-console "inside fence" -->
-~~~
-<!-- vigiles:enforce eslint/no-eval "outside fence" -->
-`,
-    );
-    assert.equal(rules.length, 1);
-    assert.equal(rules[0].linterRule, "eslint/no-eval");
-  });
-
-  it("ignores markers inside inline code spans in prose", () => {
-    // Prose that describes the syntax with a backtick-wrapped example
-    // must not trigger "malformed vigiles:enforce".
-    const { rules, errors } = parseInlineRules(
-      `You add \`<!-- vigiles:enforce eslint/no-console "why" -->\` comments to adopt gradually.
-
-Real rule below:
-
-<!-- vigiles:enforce eslint/no-eval "Never eval" -->
-`,
-    );
-    assert.equal(errors.length, 0, JSON.stringify(errors));
-    assert.equal(rules.length, 1);
-    assert.equal(rules[0].linterRule, "eslint/no-eval");
-  });
-
-  it("ignores ellipsis placeholders inside inline code spans", () => {
-    const { rules, errors } = parseInlineRules(
-      `You add \`<!-- vigiles:enforce ... -->\` comments to adopt gradually.
-`,
-    );
-    assert.equal(errors.length, 0, JSON.stringify(errors));
-    assert.equal(rules.length, 0);
-  });
-
-  it("handles nested backtick fences of different lengths", () => {
-    // Opening with 4 backticks, closing with 3 inside should NOT close
-    // the outer block — only a 4+ backtick close matches.
-    const { rules } = parseInlineRules(
-      `\`\`\`\`md
-\`\`\`
-<!-- vigiles:enforce eslint/no-console "inside outer" -->
-\`\`\`
-\`\`\`\`
-<!-- vigiles:enforce eslint/no-eval "outside" -->
-`,
-    );
-    assert.equal(rules.length, 1);
-    assert.equal(rules[0].linterRule, "eslint/no-eval");
-  });
-});
-
-describe("hasInlineRules", () => {
-  it("returns true when a valid enforce comment exists", () => {
-    assert.equal(
-      hasInlineRules(`<!-- vigiles:enforce eslint/no-console "why" -->`),
-      true,
-    );
-  });
-
-  it("returns false for plain markdown", () => {
-    assert.equal(hasInlineRules(`# Title\n\nparagraph\n`), false);
-  });
-
-  it("returns false for a malformed marker", () => {
-    assert.equal(
-      hasInlineRules(`<!-- vigiles:enforce eslint/no-console no-quotes -->`),
-      false,
-    );
-  });
-
-  it("returns false for markers trapped inside fenced code blocks", () => {
-    assert.equal(
-      hasInlineRules(
-        `# Docs\n\n\`\`\`md\n<!-- vigiles:enforce eslint/no-console "x" -->\n\`\`\`\n`,
-      ),
-      false,
-    );
-  });
-
-  it("returns true only for parseable rules outside fences", () => {
-    assert.equal(
-      hasInlineRules(
-        `\`\`\`md\n<!-- vigiles:enforce eslint/no-console "inside" -->\n\`\`\`\n<!-- vigiles:enforce eslint/no-eval "outside" -->\n`,
-      ),
-      true,
-    );
-  });
-});