vigiles 2.0.0

package/src/generate-types.ts

@@ -0,0 +1,448 @@
+/**
+ * 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

@@ -0,0 +1,206 @@
+/**
+ * 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,
+    );
+  });
+});