@comity-dev/validate 0.1.0

package/dist/engines/eslint.js

@@ -0,0 +1,170 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { resolve, relative } 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`;
+    // Use absolute paths to the plugin's dist output so Node can resolve
+    // them from the temp config's location (anywhere in the repo).
+    // The plugin is a workspace dep of this validate package; we resolve
+    // its dist via the validate package's own node_modules.
+    const pluginEntry = resolve(resolve(binDir, "..", "..", "node_modules", "@comity-dev", "eslint-plugin"), "dist", "index.js");
+    const recommendedEntry = resolve(resolve(binDir, "..", "..", "node_modules", "@comity-dev", "eslint-plugin"), "dist", "recommended.js");
+    // Resolve the @typescript-eslint/parser from validate's workspace
+    // node_modules; ESLint 9 flat-config needs an explicit parser for TS.
+    const tsParserEntry = resolve(resolve(binDir, "..", "..", "node_modules", "@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(pluginEntry)};
+import { recommended } from ${JSON.stringify(recommendedEntry)};
+import tsParser from ${JSON.stringify(tsParserEntry)};
+export default [
+  // Explicitly override ESLint's auto-detected ignores. The temp config
+  // is created at runtime, far from any .gitignore / eslintrc that the
+  // consumer repo might ship.
+  { ignores: ["**/node_modules/**", "**/dist/**"] },
+  {
+    files: ["**/*.{ts,tsx,js,jsx}"],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: { ecmaVersion: "latest", sourceType: "module" },
+    },
+    plugins: { "@comity-dev": comityPlugin },
+    rules: recommended.rules,
+  },
+];
+`;
+    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.
+    // The temp config uses absolute imports for the shared plugin, so
+    // workspace layout is irrelevant to module resolution. We pass the
+    // target directories and let ESLint auto-discover the files; the
+    // config's `files` pattern filters by extension.
+    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.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.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;

package/dist/engines/schema.js

@@ -0,0 +1,48 @@
+import { comityConfigSchema, createAjvInstance, packageMetadataSchema, } from "@comity-dev/schemas";
+export function runSchema(repo) {
+    const start = Date.now();
+    const findings = [];
+    const ajv = createAjvInstance();
+    // Per-package metadata
+    const validateMeta = ajv.compile(packageMetadataSchema);
+    for (const pkg of repo.packages) {
+        const valid = validateMeta(pkg.manifest);
+        if (!valid) {
+            for (const err of validateMeta.errors ?? []) {
+                findings.push({
+                    tool: "schema",
+                    rule: "package-metadata",
+                    package: pkg.name,
+                    path: err.instancePath,
+                    message: err.message ?? "schema violation",
+                    keyword: err.keyword,
+                    severity: "error",
+                });
+            }
+        }
+    }
+    // Repository config
+    const validateConfig = ajv.compile(comityConfigSchema);
+    const configValid = validateConfig(repo.config);
+    if (!configValid) {
+        for (const err of validateConfig.errors ?? []) {
+            findings.push({
+                tool: "schema",
+                rule: "comity-config",
+                path: err.instancePath,
+                message: err.message ?? "schema violation",
+                keyword: err.keyword,
+                severity: "error",
+            });
+        }
+    }
+    return {
+        executed: true,
+        exitCode: 0,
+        passed: findings.length === 0,
+        findings,
+        duration: Date.now() - start,
+        status: findings.length === 0 ? "PASS" : "FAIL",
+        tool: "schema",
+    };
+}

package/dist/engines/semgrep.d.ts

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

package/dist/engines/semgrep.js

@@ -0,0 +1,252 @@
+import { buildSemgrepConfig } from "@comity-dev/semgrep-rules";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { relative, resolve } from "node:path";
+/**
+ * Discover the Python interpreter that ships the `semgrep` module.
+ * We try well-known absolute paths first, then fall back to PATH.
+ */
+function resolvePythonForSemgrep() {
+    const candidates = [
+        "/usr/bin/python3",
+        "/usr/local/bin/python3",
+        "/opt/homebrew/bin/python3",
+    ];
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    const probe = spawnSync("which", ["python3"], { encoding: "utf8" });
+    if (probe.status === 0 && probe.stdout?.trim())
+        return probe.stdout.trim();
+    return null;
+}
+function findSemgrepBin(fallbackDirs) {
+    const explicitBin = process.env["SEMGREP_BIN"];
+    if (explicitBin && existsSync(explicitBin))
+        return explicitBin;
+    const probe = spawnSync("which", ["semgrep"], {
+        encoding: "utf8",
+        env: {
+            ...process.env,
+            PATH: `${fallbackDirs.join(":")}:${process.env["PATH"] ?? ""}`,
+        },
+    });
+    if (probe.status === 0 && probe.stdout?.trim()) {
+        return probe.stdout.trim();
+    }
+    const absoluteCandidates = [
+        "/usr/bin/semgrep",
+        "/usr/local/bin/semgrep",
+        "/opt/homebrew/bin/semgrep",
+    ];
+    for (const c of absoluteCandidates) {
+        if (existsSync(c))
+            return c;
+    }
+    return null;
+}
+/**
+ * Returns the set of package directory names that should be excluded
+ * from Semgrep scanning. The Development-owned runtime rule set
+ * (`@comity-dev/semgrep-rules`) targets Comity Core Modules and
+ * Adapters; it MUST NOT fire on Development tooling packages
+ * (`comity.layer: "dev-tooling"`) because those packages legitimately
+ * use Node APIs, `process.env`, and other patterns the rules forbid
+ * for runtime Core Modules.
+ */
+function devToolingPackageDirs(repo) {
+    const dirs = [];
+    for (const pkg of repo.packages) {
+        if (pkg.layer === "dev-tooling") {
+            const rel = relative(repo.root, pkg.path);
+            const top = rel.split("/")[0];
+            if (top)
+                dirs.push(top);
+        }
+    }
+    return [...new Set(dirs)];
+}
+function buildSemgrepArgs(configPath, target, excludedDirs) {
+    const args = [
+        "-c",
+        "from semgrep.console_scripts.entrypoint import main; main()",
+        "scan",
+        "--config",
+        configPath,
+        "--json",
+        "--quiet",
+        "--error",
+        target,
+    ];
+    // Exclude dev-tooling package directories by both path-pattern
+    // (via --exclude) and directory name (via --exclude-dir) so semgrep
+    // does not scan them at all. The runtime rule set is not designed
+    // for development-tooling source.
+    for (const d of excludedDirs) {
+        args.push("--exclude", `**/packages/${d}/**`);
+        args.push("--exclude-dir", d);
+    }
+    return args;
+}
+export async function runSemgrep(repo) {
+    const start = Date.now();
+    // Build the combined Semgrep config. Semgrep's CLI accepts a single
+    // --config path, so we concatenate all canonical rule files into one
+    // synthesized config.
+    const configYaml = await buildSemgrepConfig();
+    const tmpDir = mkdtempSync("/tmp/comity-validate-semgrep-");
+    const configPath = `${tmpDir}/semgrep-config.yaml`;
+    writeFileSync(configPath, configYaml);
+    const pathDirs = (process.env["PATH"] ?? "").split(":").filter(Boolean);
+    const fallbackDirs = ["/usr/local/bin", "/opt/homebrew/bin"];
+    const candidateDirs = [...new Set([...pathDirs, ...fallbackDirs])];
+    const cleanup = () => {
+        try {
+            rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch {
+            // ignore
+        }
+    };
+    const semgrepBin = findSemgrepBin(fallbackDirs);
+    if (!semgrepBin) {
+        cleanup();
+        return {
+            executed: false,
+            exitCode: null,
+            passed: false,
+            findings: [],
+            duration: Date.now() - start,
+            status: "TOOL-UNAVAILABLE",
+            tool: "semgrep",
+            reason: "semgrep binary not found on PATH; install semgrep or set SEMGREP_BIN",
+        };
+    }
+    // Locate the Python interpreter that ships the semgrep module.
+    const pythonBin = resolvePythonForSemgrep();
+    if (!pythonBin) {
+        cleanup();
+        return {
+            executed: false,
+            exitCode: null,
+            passed: false,
+            findings: [],
+            duration: Date.now() - start,
+            status: "TOOL-UNAVAILABLE",
+            tool: "semgrep",
+            reason: "Python interpreter not found; semgrep requires Python on PATH",
+        };
+    }
+    // Augment PATH so the inner Python process can find semgrep's
+    // sibling `pysemgrep` script (semgrep's `subprocess.run` does an
+    // `execvp("pysemgrep")` lookup against this PATH).
+    const envPath = [
+        ...candidateDirs,
+        "/Users/filippo/Library/Python/3.14/bin",
+        "/Users/filippo/Library/Python/3.13/bin",
+        "/Users/filippo/Library/Python/3.12/bin",
+        process.env["PATH"] ?? "",
+        "/usr/bin",
+        "/bin",
+    ].join(":");
+    const target = resolve(repo.root, "packages");
+    const excludedDirs = devToolingPackageDirs(repo);
+    // If every discovered package is dev-tooling, the runtime rule
+    // set is not applicable to this repository. Report NOT-APPLICABLE
+    // rather than running semgrep against an empty target.
+    const runtimePackages = repo.packages.filter((p) => p.layer !== "dev-tooling");
+    if (runtimePackages.length === 0) {
+        cleanup();
+        return {
+            executed: false,
+            exitCode: null,
+            passed: true,
+            findings: [],
+            duration: Date.now() - start,
+            status: "NOT-APPLICABLE",
+            tool: "semgrep",
+            reason: "Repository contains no runtime packages; the @comity-dev/semgrep-rules rule set targets Comity Core Modules and Adapters and is not applicable to development-tooling-only repositories.",
+        };
+    }
+    const args = buildSemgrepArgs(configPath, target, excludedDirs);
+    const proc = spawnSync(pythonBin, args, {
+        cwd: repo.root,
+        env: { ...process.env, PATH: envPath },
+        maxBuffer: 16 * 1024 * 1024,
+        encoding: "utf8",
+    });
+    cleanup();
+    const stdout = proc.stdout ?? "";
+    const stderr = proc.stderr ?? "";
+    const findings = parseSemgrepOutput(stdout, stderr);
+    // If semgrep exited non-zero but produced no parseable findings, this
+    // is an EXECUTION-ERROR (configuration, rule-parse, internal crash),
+    // not a policy violation.
+    if (proc.status !== null && proc.status !== 0 && findings.length === 0) {
+        const stderrHead = stderr.split("\n")[0] ?? "";
+        const stdoutHead = stdout.slice(0, 500);
+        findings.push({
+            tool: "semgrep",
+            rule: "SEM-CRASH",
+            message: `semgrep exited with code ${proc.status}; stderr: ${stderrHead}; stdout (first 500): ${stdoutHead}`,
+            severity: "error",
+        });
+        return {
+            executed: true,
+            exitCode: proc.status,
+            passed: false,
+            findings,
+            duration: Date.now() - start,
+            status: "EXECUTION-ERROR",
+            tool: "semgrep",
+        };
+    }
+    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: "semgrep",
+    };
+}
+function parseSemgrepOutput(stdout, stderr) {
+    const out = stdout ?? stderr ?? "";
+    if (!out.trim())
+        return [];
+    let parsed = null;
+    try {
+        parsed = JSON.parse(out);
+    }
+    catch {
+        return [];
+    }
+    const findings = [];
+    for (const e of parsed?.errors ?? []) {
+        if (e.level === "error") {
+            findings.push({
+                tool: "semgrep",
+                rule: `SEM-PARSE-${e.rule_id ?? "UNKNOWN"}`,
+                message: e.message ?? "semgrep rule parse error",
+                severity: "error",
+            });
+        }
+    }
+    const results = parsed?.results ?? [];
+    for (const r of results) {
+        const start = r["start"];
+        const extra = r["extra"];
+        findings.push({
+            tool: "semgrep",
+            rule: `SEM-${String(r["check_id"] ?? "UNKNOWN")}`,
+            message: extra?.message ?? "Semgrep rule violation",
+            file: typeof r["path"] === "string" ? r["path"] : undefined,
+            line: start?.line,
+            column: start?.col,
+            severity: extra?.severity === "ERROR" ? "error" : "warning",
+        });
+    }
+    return findings;
+}

package/dist/engines/types.d.ts

@@ -0,0 +1,25 @@
+export type EngineStatus = "PASS" | "FAIL" | "NOT-RUN" | "TOOL-UNAVAILABLE" | "CONFIGURATION-ERROR" | "EXECUTION-ERROR" | "NOT-APPLICABLE";
+export interface Finding {
+    tool: string;
+    rule: string;
+    package?: string | undefined;
+    path?: string | undefined;
+    message: string;
+    severity: "error" | "warning";
+    file?: string | undefined;
+    line?: number | undefined;
+    column?: number | undefined;
+    keyword?: string | undefined;
+    source?: string | undefined;
+    remediation?: string | undefined;
+}
+export interface EngineResult {
+    executed: boolean;
+    exitCode: number | null;
+    passed: boolean;
+    findings: Finding[];
+    duration: number;
+    status: EngineStatus;
+    tool?: string | undefined;
+    reason?: string | undefined;
+}

package/dist/engines/types.js

@@ -0,0 +1 @@
+export {};

package/dist/exit-codes.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Canonical exit codes for `comity validate`.
+ *
+ *   0 = validation passed
+ *   1 = validation failed (violations found)
+ *   2 = configuration / discovery error (cannot run)
+ *   3 = tool not installed (e.g. dependency-cruiser missing)
+ */
+export declare const ExitCode: Readonly<{
+    readonly PASS: 0;
+    readonly FAIL: 1;
+    readonly CONFIG_ERROR: 2;
+    readonly TOOL_MISSING: 3;
+}>;
+export type ExitCodeValue = (typeof ExitCode)[keyof typeof ExitCode];

package/dist/exit-codes.js

@@ -0,0 +1,14 @@
+/**
+ * Canonical exit codes for `comity validate`.
+ *
+ *   0 = validation passed
+ *   1 = validation failed (violations found)
+ *   2 = configuration / discovery error (cannot run)
+ *   3 = tool not installed (e.g. dependency-cruiser missing)
+ */
+export const ExitCode = Object.freeze({
+    PASS: 0,
+    FAIL: 1,
+    CONFIG_ERROR: 2,
+    TOOL_MISSING: 3,
+});

package/dist/format.d.ts

@@ -0,0 +1,33 @@
+import type { Finding } from "./engines/types.js";
+import type { CategoryResult } from "./run.js";
+export interface FormatInput {
+    /** Whether the overall validation passed or failed */
+    passed: boolean;
+    /** The list of all findings across all categories */
+    violations: Finding[];
+    /** The results of each validation category */
+    categories: {
+        /** Schema validation results */
+        schema: CategoryResult;
+        /** Package metadata validation results */
+        metadata: CategoryResult;
+        /** Comity config validation results */
+        config: CategoryResult;
+        /** Dependency validation results */
+        dependencies: CategoryResult;
+        /** ESLint validation results */
+        eslint: CategoryResult;
+        /** Semgrep validation results */
+        semgrep: CategoryResult;
+        /** Adapter peers validation results */
+        adapterPeers: CategoryResult;
+    };
+}
+/**
+ * Format a unified summary for the terminal.
+ */
+export declare function formatSummary(result: FormatInput): string;
+/**
+ * Format detailed violations for debugging.
+ */
+export declare function formatViolations(violations: Finding[]): string;

package/dist/format.js

@@ -0,0 +1,76 @@
+const CATEGORY_LABELS = {
+    schema: "Schema",
+    metadata: "Package metadata",
+    config: "Comity config",
+    dependencies: "Dependencies (depcruise)",
+    eslint: "Source rules (ESLint)",
+    semgrep: "Structural patterns (Semgrep)",
+    adapterPeers: "Adapter peers",
+};
+function statusBadge(cat) {
+    switch (cat.status) {
+        case "PASS":
+            return "PASS";
+        case "FAIL":
+            return "FAIL";
+        case "NOT-RUN":
+            return "NOT-RUN";
+        case "TOOL-UNAVAILABLE":
+            return "TOOL-UNAVAILABLE";
+        case "CONFIGURATION-ERROR":
+            return "CONFIG-ERROR";
+        case "EXECUTION-ERROR":
+            return "EXEC-ERROR";
+        case "NOT-APPLICABLE":
+            return "NOT-APPLICABLE";
+        default:
+            return cat.executed ? (cat.passed ? "PASS" : "FAIL") : "NOT-RUN";
+    }
+}
+/**
+ * Format a unified summary for the terminal.
+ */
+export function formatSummary(result) {
+    const lines = ["Comity validation", ""];
+    for (const [key, label] of Object.entries(CATEGORY_LABELS)) {
+        const cat = result.categories[key];
+        if (!cat)
+            continue;
+        const badge = statusBadge(cat);
+        const count = cat.findings > 0 ? ` (${cat.findings} findings)` : "";
+        const exit = cat.exitCode !== null && cat.exitCode !== 0
+            ? ` exit=${cat.exitCode}`
+            : "";
+        lines.push(`${badge.padEnd(18)}  ${label}${count}${exit}`);
+    }
+    lines.push("");
+    for (const [key, label] of Object.entries(CATEGORY_LABELS)) {
+        const cat = result.categories[key];
+        if (!cat)
+            continue;
+        if (cat.status === "TOOL-UNAVAILABLE" ||
+            cat.status === "CONFIGURATION-ERROR" ||
+            cat.status === "EXECUTION-ERROR" ||
+            cat.status === "NOT-APPLICABLE") {
+            lines.push(`  ${label}: ${cat.reason ?? cat.status}`);
+        }
+    }
+    lines.push("");
+    lines.push(`Result: ${result.passed ? "PASS" : "FAIL"}`);
+    return lines.join("\n");
+}
+/**
+ * Format detailed violations for debugging.
+ */
+export function formatViolations(violations) {
+    if (violations.length === 0)
+        return "";
+    const lines = [`${violations.length} violation(s):\n`];
+    for (const v of violations) {
+        const loc = v.file
+            ? ` ${v.file}${v.line ? `:${v.line}` : ""}${v.column ? `:${v.column}` : ""}`
+            : "";
+        lines.push(`[${v.tool}] ${v.rule} ${v.package ?? ""}${loc} — ${v.message}`);
+    }
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export type { DiscoverOptions, PackageRecord, Repository } from "./discover.js";
+export type { EngineResult, EngineStatus, Finding } from "./engines/types.js";
+export type { ExitCodeValue } from "./exit-codes.js";
+export type { FormatInput } from "./format.js";
+export type { CategoryResult, RunOptions, RunResult } from "./run.js";
+export { discoverRepository } from "./discover.js";
+export { ExitCode } from "./exit-codes.js";
+export { formatSummary, formatViolations } from "./format.js";
+export { runValidation } from "./run.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { discoverRepository } from "./discover.js";
+export { ExitCode } from "./exit-codes.js";
+export { formatSummary, formatViolations } from "./format.js";
+export { runValidation } from "./run.js";