@comity-dev/validate 0.1.1 → 0.2.0

package/README.md

@@ -57,6 +57,32 @@ Exit codes:
 - `2` — configuration / discovery error
 - `3` — required tool not installed
 
+## Environment
+
+The Semgrep engine shells out to a local Semgrep installation:
+
+| Variable         | Purpose                                                                                          |
+| ---------------- | ------------------------------------------------------------------------------------------------ |
+| `SEMGREP_BIN`    | Path to the `semgrep` executable. Used as-is when it exists; otherwise resolved from PATH.       |
+| `SEMGREP_PYTHON` | Path to the Python interpreter that ships the `semgrep` module. The scan is executed with it.    |
+
+Rules:
+
+- An explicit `SEMGREP_PYTHON` always wins and is never silently overridden.
+- A set-but-missing `SEMGREP_PYTHON` is invalid configuration: the engine
+  reports `TOOL-UNAVAILABLE` naming the variable instead of falling back to
+  another interpreter.
+- When `SEMGREP_PYTHON` is unset, the previous resolution applies
+  (`/usr/bin/python3`, `/usr/local/bin/python3`, `/opt/homebrew/bin/python3`,
+  then `python3` on PATH).
+- The scan `PATH` is prefixed with the directories of the resolved
+  `SEMGREP_BIN` and interpreter so Semgrep finds its sibling `pysemgrep`.
+
+```bash
+SEMGREP_BIN=~/.local/bin/semgrep SEMGREP_PYTHON=/opt/homebrew/bin/python3 \
+  comity-validate --repo /path/to/repo
+```
+
 ## Negative fixtures
 
 The `src/__fixtures__/third-repo/` directory contains a deliberately invalid repository used by the package's own integration tests. It is **not** scanned by the canonical validate run (the engine excludes `__fixtures__/**`); it is asserted against failure by `src/__tests__/integration.test.ts`.

package/dist/bin/comity-validate.d.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * comity-validate — thin orchestrator over Comity shared validation tooling.
+ *
+ * Usage:
+ *   comity-validate [options]
+ *
+ * Options:
+ *   --help, -h           Show this help
+ *   --verbose, -v        Print underlying tool output
+ *   --repo <path>        Repository root (default: cwd)
+ *   --only <category>    Only run a single category
+ *                        (schema | metadata | config | dependencies | eslint | semgrep | adapter-peers)
+ *                        Default: run all categories.
+ *
+ * Exit codes:
+ *   0  validation passed
+ *   1  validation failed (violations found)
+ *   2  configuration / discovery error
+ *   3  required tool not installed
+ *
+ * The TypeScript source for this binary lives at
+ * `src/bin/comity-validate.ts` and is compiled to
+ * `dist/bin/comity-validate.js` by `tsc -p tsconfig.json`.
+ */
+export {};

package/dist/bin/comity-validate.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * comity-validate — thin orchestrator over Comity shared validation tooling.
+ *
+ * Usage:
+ *   comity-validate [options]
+ *
+ * Options:
+ *   --help, -h           Show this help
+ *   --verbose, -v        Print underlying tool output
+ *   --repo <path>        Repository root (default: cwd)
+ *   --only <category>    Only run a single category
+ *                        (schema | metadata | config | dependencies | eslint | semgrep | adapter-peers)
+ *                        Default: run all categories.
+ *
+ * Exit codes:
+ *   0  validation passed
+ *   1  validation failed (violations found)
+ *   2  configuration / discovery error
+ *   3  required tool not installed
+ *
+ * The TypeScript source for this binary lives at
+ * `src/bin/comity-validate.ts` and is compiled to
+ * `dist/bin/comity-validate.js` by `tsc -p tsconfig.json`.
+ */
+import { resolve } from "node:path";
+import { ExitCode } from "../exit-codes.js";
+import { formatSummary, formatViolations } from "../format.js";
+import { runValidation } from "../run.js";
+function parseArgs(argv) {
+    const args = {
+        root: process.cwd(),
+        verbose: false,
+        only: null,
+        help: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--help" || arg === "-h")
+            args.help = true;
+        else if (arg === "--verbose" || arg === "-v")
+            args.verbose = true;
+        else if (arg === "--repo")
+            args.root = resolve(argv[++i] ?? "");
+        else if (arg?.startsWith("--repo="))
+            args.root = resolve(arg.slice("--repo=".length));
+        else if (arg === "--only")
+            args.only = argv[++i] ?? null;
+        else if (arg?.startsWith("--only="))
+            args.only = arg.slice("--only=".length);
+    }
+    return args;
+}
+function printHelp() {
+    console.log(`comity-validate — thin orchestrator over Comity shared validation tooling
+
+Usage:
+  comity-validate [options]
+
+Options:
+  --help, -h           Show this help
+  --verbose, -v        Print underlying tool output
+  --repo <path>        Repository root (default: cwd)
+  --only <category>    Only run a single category
+                       (schema | metadata | config | dependencies | eslint | semgrep | adapter-peers)
+
+Exit codes:
+  0  validation passed
+  1  validation failed
+  2  configuration / discovery error
+  3  required tool not installed
+`);
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+        printHelp();
+        process.exit(ExitCode.PASS);
+    }
+    try {
+        const result = await runValidation({
+            root: args.root,
+            verbose: args.verbose,
+            only: args.only,
+        });
+        console.log(formatSummary(result));
+        if (!result.passed && args.verbose) {
+            console.log("");
+            console.log(formatViolations(result.violations));
+        }
+        process.exit(result.passed ? ExitCode.PASS : ExitCode.FAIL);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error("comity-validate: configuration error:", message);
+        process.exit(ExitCode.CONFIG_ERROR);
+    }
+}
+main();

package/dist/discover.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @comity-dev/validate — repository discovery.
+ *
+ * Walks a repository's `comity.config.json` and the configured package
+ * roots to produce a normalized Repository handle that the orchestrator
+ * passes to specialized validators.
+ */
+export interface PackageRecord {
+    /** The package's `name` field from its `package.json`. */
+    name: string;
+    /** The absolute path of the package directory. */
+    path: string;
+    /** The package's `comity.layer` field from its `package.json`, or null if not set. */
+    layer: string | null;
+    /** The parsed contents of the package's `package.json`. */
+    manifest: Record<string, unknown>;
+}
+export interface Repository {
+    /** The absolute path of the repository root. */
+    root: string;
+    /** The parsed contents of the repository's `comity.config.json`. */
+    repository: {
+        name: string;
+        type: string;
+    };
+    /** The configured package roots, relative to the repository root. */
+    packageRoots: string[];
+    /** The discovered packages in the repository, sorted by name. */
+    packages: PackageRecord[];
+    /** The parsed contents of the repository's `comity.config.json`. */
+    config: Record<string, unknown>;
+}
+export interface DiscoverOptions {
+    /** The absolute path of the repository root. */
+    root: string;
+}
+/**
+ * Discover a repository: load comity.config.json, walk the configured
+ * package roots, and produce a normalized Repository handle.
+ */
+export declare function discoverRepository({ root, }: DiscoverOptions): Promise<Repository>;

package/dist/discover.js

@@ -0,0 +1,74 @@
+/**
+ * @comity-dev/validate — repository discovery.
+ *
+ * Walks a repository's `comity.config.json` and the configured package
+ * roots to produce a normalized Repository handle that the orchestrator
+ * passes to specialized validators.
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+/**
+ * Discover a repository: load comity.config.json, walk the configured
+ * package roots, and produce a normalized Repository handle.
+ */
+export async function discoverRepository({ root, }) {
+    const absRoot = resolve(root);
+    const configPath = join(absRoot, "comity.config.json");
+    let config = null;
+    try {
+        const text = await readFile(configPath, "utf8");
+        config = JSON.parse(text);
+    }
+    catch {
+        config = {
+            repository: { name: "unknown", type: "third-party" },
+            packages: { roots: ["packages"] },
+        };
+    }
+    const cfg = config;
+    const roots = cfg.packages?.roots ?? ["packages"];
+    const packages = [];
+    for (const rel of roots) {
+        const dir = join(absRoot, rel);
+        try {
+            await stat(dir);
+        }
+        catch {
+            continue;
+        }
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const pkgDir = join(dir, entry.name);
+            const manifestPath = join(pkgDir, "package.json");
+            let manifest = null;
+            try {
+                const text = await readFile(manifestPath, "utf8");
+                manifest = JSON.parse(text);
+            }
+            catch {
+                continue;
+            }
+            if (!manifest?.["name"] ||
+                (!String(manifest["name"]).startsWith("@comity/") &&
+                    !String(manifest["name"]).startsWith("@comity-dev/")))
+                continue;
+            const m = manifest;
+            packages.push({
+                name: m.name,
+                path: pkgDir,
+                layer: m.comity?.layer ?? null,
+                manifest,
+            });
+        }
+    }
+    packages.sort((a, b) => a.name.localeCompare(b.name));
+    return {
+        root: absRoot,
+        repository: cfg.repository ?? { name: "unknown", type: "third-party" },
+        packageRoots: roots,
+        packages,
+        config: config ?? {},
+    };
+}

package/dist/engines/adapter-peers.d.ts

@@ -0,0 +1,3 @@
+import type { Repository } from "../discover.js";
+import type { EngineResult } from "./types.js";
+export declare function runAdapterPeers(repo: Repository): EngineResult;

package/dist/engines/adapter-peers.js

@@ -0,0 +1,120 @@
+const KERNEL_PACKAGES = new Set([
+    "@comity/primitives",
+    "@comity/kernel",
+    "@comity/composition",
+]);
+const SOURCE = "adapters.md §13 / architecture-validation.md §7.4 (docs/standards/)";
+export function runAdapterPeers(repo) {
+    const start = Date.now();
+    const findings = [];
+    // Authoritative layer lookup per ADR-026: each package's own manifest
+    // declares its layer. Used to distinguish consumed Core Modules (which
+    // §13 requires as peers) from kernel and other layers.
+    const layers = new Map(repo.packages.map((p) => [p.name, p.layer]));
+    for (const pkg of repo.packages) {
+        if (pkg.layer !== "technology-adapter")
+            continue;
+        const m = pkg.manifest;
+        const implementsMeta = m.comity?.implements;
+        // Validate that the technology-adapter declares its implemented Core Module in comity.implements
+        if (typeof implementsMeta !== "string" || !implementsMeta.trim()) {
+            findings.push({
+                tool: "schema",
+                rule: "ARCH-ADAPTER-PEER-005",
+                message: `Technology Adapter "${pkg.name}" cannot determine implemented Core Module (missing or invalid comity.implements)`,
+                package: pkg.name,
+                severity: "error",
+                source: SOURCE,
+                remediation: 'Ensure package.json has "comity.implements" set to a string Core Module package name.',
+            });
+            continue;
+        }
+        const coreModule = implementsMeta.trim();
+        const peerDeps = m.peerDependencies ?? {};
+        const deps = m.dependencies ?? {};
+        // Validate that the technology-adapter declares its implemented Core Module as a peerDependency
+        if (!peerDeps[coreModule]) {
+            findings.push({
+                tool: "schema",
+                rule: "ARCH-ADAPTER-PEER-001",
+                message: `Technology Adapter "${pkg.name}" implements "${coreModule}" but does not declare it as a peerDependency`,
+                package: pkg.name,
+                severity: "error",
+                source: SOURCE,
+                remediation: `Add "${coreModule}" to peerDependencies.`,
+            });
+        }
+        // Validate that the technology-adapter declares its implemented Core Module as a dependency
+        if (!deps[coreModule] && !peerDeps[coreModule]) {
+            findings.push({
+                tool: "schema",
+                rule: "ARCH-ADAPTER-PEER-002",
+                message: `Technology Adapter "${pkg.name}" implements "${coreModule}" but does not depend on it at all`,
+                package: pkg.name,
+                severity: "error",
+                source: SOURCE,
+                remediation: `Add "${coreModule}" to dependencies and peerDependencies.`,
+            });
+        }
+        // Validate that every consumed Core Module is declared as a
+        // peerDependency (adapters.md §13). "Consumed" is the manifest
+        // `dependencies` signal: npm runtime-requirement semantics, mirrored by
+        // the §13 examples and by every adapter in the monorepo. Transitive,
+        // lockfile-only, and dev dependencies are structurally excluded. The
+        // implemented module is covered by ARCH-ADAPTER-PEER-001 above and is
+        // skipped here to keep diagnostics singular.
+        for (const dep of Object.keys(deps)) {
+            if (!dep.startsWith("@comity/"))
+                continue;
+            if (dep === coreModule)
+                continue;
+            if (layers.get(dep) !== "core")
+                continue;
+            if (!peerDeps[dep]) {
+                findings.push({
+                    tool: "schema",
+                    rule: "ARCH-ADAPTER-PEER-003",
+                    message: `Technology Adapter "${pkg.name}" consumes Core Module "${dep}" but does not declare it as a peerDependency`,
+                    package: pkg.name,
+                    severity: "error",
+                    source: SOURCE,
+                    remediation: `Add "${dep}" to peerDependencies.`,
+                });
+            }
+        }
+        // Validate that the technology-adapter does not declare peerDependencies
+        // on unrelated @comity/* packages. Per §13, peers are allowed for the
+        // implemented Core Module, kernel packages, and consumed Core Modules.
+        // A matching `dependencies` entry is the authoritative consumption
+        // signal (npm runtime-requirement semantics, mirrored by the §13
+        // examples and every adapter in the monorepo), so it uniformly covers
+        // workspace and external packages. A peer with no dependency
+        // relationship expresses nothing real and is rejected. Adapter-to-
+        // adapter edges remain the depcruise L6 rule's responsibility.
+        for (const peerDep of Object.keys(peerDeps)) {
+            if (!peerDep.startsWith("@comity/"))
+                continue;
+            const allowed = [coreModule, ...KERNEL_PACKAGES].includes(peerDep) || peerDep in deps;
+            if (!allowed) {
+                findings.push({
+                    tool: "schema",
+                    rule: "ARCH-ADAPTER-PEER-004",
+                    message: `Technology Adapter "${pkg.name}" declares peerDependency on "${peerDep}" which is not the implemented Core Module, a Kernel package, or a consumed Core Module`,
+                    package: pkg.name,
+                    severity: "error",
+                    source: SOURCE,
+                    remediation: `Remove "${peerDep}" from peerDependencies unless it is the implemented Core Module, a Kernel package, or a consumed Core Module declared in dependencies.`,
+                });
+            }
+        }
+    }
+    return {
+        executed: true,
+        exitCode: 0,
+        passed: findings.length === 0,
+        findings,
+        duration: Date.now() - start,
+        status: findings.length === 0 ? "PASS" : "FAIL",
+        tool: "adapter-peers",
+    };
+}

package/dist/engines/depcruise.d.ts

@@ -0,0 +1,3 @@
+import type { Repository } from "../discover.js";
+import type { EngineResult } from "./types.js";
+export declare function runDepcruise(repo: Repository, binDir: string): EngineResult;

package/dist/engines/depcruise.js

@@ -0,0 +1,109 @@
+import { buildDependencyRulesForRoot, classifyByLayer, } from "@comity-dev/dependency-rules";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+export function runDepcruise(repo, binDir) {
+    const start = Date.now();
+    const classification = classifyByLayer(repo.packages.map((p) => ({ name: p.name, layer: p.layer })));
+    const depConfig = buildDependencyRulesForRoot(classification, repo.root);
+    // Write the generated config to an OS temp directory so the consumer
+    // repository is never mutated by the validator. The temp directory is
+    // unique per run and cleaned up after the engine returns.
+    const tmpDir = mkdtempSync("/tmp/comity-validate-depcruise-");
+    const configPath = `${tmpDir}/depcruise.json`;
+    writeFileSync(configPath, JSON.stringify(depConfig, null, 2));
+    const bin = resolve(binDir, "depcruise");
+    if (!existsSync(bin)) {
+        return {
+            executed: false,
+            exitCode: null,
+            passed: false,
+            findings: [],
+            duration: Date.now() - start,
+            status: "TOOL-UNAVAILABLE",
+            tool: "dependency-cruiser",
+            reason: `dependency-cruiser binary not found at ${bin}`,
+        };
+    }
+    // Build target paths from discovered package directories
+    // Use the repository's actual package directories, not a hardcoded "packages"
+    const packageDirs = repo.packages.map((p) => resolve(repo.root, p.path));
+    const targets = packageDirs.length > 0 ? packageDirs : [resolve(repo.root, "packages")];
+    // Run depcruise from the validate package's directory so it can resolve
+    // the shared @comity-dev/dependency-rules via workspace node_modules.
+    // The tsConfig.fileName path is resolved relative to this CWD; the
+    // generated config uses an absolute path so this is robust.
+    const engineCwd = resolve(binDir, "..", "..");
+    const proc = spawnSync(bin, ["--config", configPath, "--output-type", "json", ...targets], {
+        encoding: "utf8",
+        maxBuffer: 16 * 1024 * 1024,
+        cwd: engineCwd,
+        env: {
+            ...process.env,
+            TSCONFIG_PATH: resolve(repo.root, "tsconfig.json"),
+        },
+    });
+    const findings = parseDepcruiseOutput(proc.stdout, proc.stderr);
+    // Clean up the temp config directory.
+    try {
+        rmSync(tmpDir, { recursive: true, force: true });
+    }
+    catch {
+        // ignore
+    }
+    // If depcruise exited non-zero but produced no parseable JSON output,
+    // that is an EXECUTION-ERROR, not a policy violation. Surface stderr
+    // so the operator can diagnose, but mark status accordingly.
+    if (proc.status !== 0 && findings.length === 0) {
+        const stderrHead = (proc.stderr ?? "").split("\n")[0] ?? "";
+        findings.push({
+            tool: "dependency-cruiser",
+            rule: "DEP-CRASH",
+            message: `dependency-cruiser exited with code ${proc.status}; stderr: ${stderrHead}`,
+            severity: "error",
+        });
+        return {
+            executed: true,
+            exitCode: proc.status,
+            passed: false,
+            findings,
+            duration: Date.now() - start,
+            status: "EXECUTION-ERROR",
+            tool: "dependency-cruiser",
+        };
+    }
+    return {
+        executed: true,
+        exitCode: proc.status,
+        passed: proc.status === 0 && findings.length === 0,
+        findings,
+        duration: Date.now() - start,
+        status: proc.status === 0 ? "PASS" : "FAIL",
+        tool: "dependency-cruiser",
+    };
+}
+function parseDepcruiseOutput(stdout, stderr) {
+    const out = stdout ?? stderr ?? "";
+    if (!out.trim())
+        return [];
+    let parsed = null;
+    try {
+        parsed = JSON.parse(out);
+    }
+    catch {
+        return [];
+    }
+    const violations = parsed?.violations ?? [];
+    return violations.map((v) => {
+        const from = v["from"];
+        const rule = v["rule"];
+        return {
+            tool: "dependency-cruiser",
+            rule: `DEP-${rule?.name ?? "UNKNOWN"}`,
+            message: rule?.comment ?? "Dependency rule violation",
+            file: from?.file,
+            line: from?.line,
+            severity: "error",
+        };
+    });
+}

package/dist/engines/eslint.d.ts

@@ -0,0 +1,3 @@
+import type { Repository } from "../discover.js";
+import type { EngineResult } from "./types.js";
+export declare function runEslint(repo: Repository, binDir: string): EngineResult;

package/dist/engines/eslint.js

@@ -0,0 +1,148 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { relative, resolve } from "node:path";
+export function runEslint(repo, binDir) {
+    const start = Date.now();
+    // Write the temp config to an OS temp directory so the consumer
+    // repository is never mutated by the validator.
+    const tmpDir = mkdtempSync("/tmp/comity-validate-eslint-");
+    const configPath = `${tmpDir}/eslint.config.mjs`;
+    // Resolve modules from the repository's node_modules, not from the validate
+    // package's node_modules. This ensures we use the repository's installed
+    // versions of the plugins and parser.
+    const repoNodeModules = resolve(repo.root, "node_modules");
+    const pluginPath = resolve(repoNodeModules, "@comity-dev", "eslint-plugin", "dist", "index.js");
+    const recommendedPath = resolve(repoNodeModules, "@comity-dev", "eslint-plugin", "dist", "recommended.js");
+    const tsParserPath = resolve(repoNodeModules, "@typescript-eslint", "parser", "dist", "index.js");
+    // Build target directories from discovered package roots
+    // Use the repository's actual package directories
+    const packageDirs = repo.packages.map((p) => resolve(repo.root, p.path));
+    // Compute relative paths from repo.root for ESLint target
+    const targets = packageDirs.length > 0
+        ? packageDirs.map((dir) => relative(repo.root, dir))
+        : ["packages"];
+    const configBody = `import comityPlugin from ${JSON.stringify(pluginPath)};\nimport { recommended } from ${JSON.stringify(recommendedPath)};\nimport tsParser from ${JSON.stringify(tsParserPath)};\nexport default [\n  // Explicitly override ESLint's auto-detected ignores. The temp config\n  // is created at runtime, far from any .gitignore / eslintrc that the\n  // consumer repo might ship.\n  { ignores: ["**/node_modules/**", "**/dist/**", "**/coverage/**", "**/*.test.ts", "**/*.spec.ts", "**/__tests__/**"] },\n  {\n    files: ["**/*.{ts,tsx,js,jsx}"],\n    languageOptions: {\n      parser: tsParser,\n      parserOptions: { ecmaVersion: "latest", sourceType: "module" },\n    },\n    plugins: { "@comity-dev": comityPlugin },\n    rules: recommended.rules,\n  },\n];\n`;
+    writeFileSync(configPath, configBody);
+    if (process.env["DEBUG_VALIDATE"]) {
+        console.error("[DEBUG] ESLint config written to:", configPath);
+        console.error("[DEBUG] Targets:", targets);
+    }
+    const bin = resolve(binDir, "eslint");
+    if (!existsSync(bin)) {
+        try {
+            rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch {
+            // ignore
+        }
+        return {
+            executed: false,
+            exitCode: null,
+            passed: false,
+            findings: [],
+            duration: Date.now() - start,
+            status: "TOOL-UNAVAILABLE",
+            tool: "eslint",
+            reason: `eslint binary not found at ${bin}`,
+        };
+    }
+    // Run ESLint with cwd = repo.root so its file-path resolution and
+    // ignore handling are anchored at the repository being validated.
+    const proc = spawnSync(bin, [
+        "--config",
+        configPath,
+        "--format",
+        "json",
+        "--no-config-lookup",
+        "--no-inline-config",
+        ...targets,
+    ], {
+        encoding: "utf8",
+        maxBuffer: 16 * 1024 * 1024,
+        cwd: repo.root,
+    });
+    const findings = parseEslintOutput(proc.stdout, proc.stderr);
+    // Clean up temp config (skip in debug mode for inspection)
+    if (!process.env["DEBUG_VALIDATE"]) {
+        try {
+            rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch {
+            // ignore
+        }
+    }
+    else {
+        console.error("[DEBUG] Temp config preserved at:", tmpDir);
+    }
+    // If ESLint exited non-zero but produced no parseable output, this is
+    // an EXECUTION-ERROR (config failure, missing plugin, etc.) not a
+    // policy violation. Surface stderr so the operator can diagnose.
+    if (proc.status !== 0 && findings.length === 0) {
+        const stderrHead = (proc.stderr ?? "").split("\n")[0] ?? "";
+        findings.push({
+            tool: "eslint",
+            rule: "ESLINT-CRASH",
+            message: `eslint exited with code ${proc.status}; stderr: ${stderrHead}`,
+            severity: "error",
+        });
+        return {
+            executed: true,
+            exitCode: proc.status,
+            passed: false,
+            findings,
+            duration: Date.now() - start,
+            status: "EXECUTION-ERROR",
+            tool: "eslint",
+        };
+    }
+    // Debug logging
+    if (process.env["DEBUG_VALIDATE"]) {
+        console.error("[DEBUG] ESLint result:", {
+            status: proc.status,
+            findingsCount: findings.length,
+            passed: proc.status === 0 &&
+                findings.filter((f) => f.severity === "error").length === 0,
+            stdout: proc.stdout?.slice(0, 500),
+            stderr: proc.stderr?.slice(0, 500),
+        });
+    }
+    return {
+        executed: true,
+        exitCode: proc.status,
+        passed: proc.status === 0 &&
+            findings.filter((f) => f.severity === "error").length === 0,
+        findings,
+        duration: Date.now() - start,
+        status: proc.status === 0 ? "PASS" : "FAIL",
+        tool: "eslint",
+    };
+}
+function parseEslintOutput(stdout, stderr) {
+    const out = stdout ?? stderr ?? "";
+    if (!out.trim())
+        return [];
+    let parsed = null;
+    try {
+        parsed = JSON.parse(out);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const findings = [];
+    for (const fileResult of parsed) {
+        for (const msg of fileResult.messages) {
+            findings.push({
+                tool: "eslint",
+                rule: msg.ruleId ?? "ESLINT",
+                message: msg.message,
+                file: fileResult.filePath,
+                line: msg.line,
+                column: msg.column,
+                severity: msg.severity === 2 ? "error" : "warning",
+            });
+        }
+    }
+    return findings;
+}

package/dist/engines/schema.d.ts

@@ -0,0 +1,3 @@
+import type { Repository } from "../discover.js";
+import type { EngineResult } from "./types.js";
+export declare function runSchema(repo: Repository): EngineResult;