@comity-dev/validate 0.1.1 → 0.2.0

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,18 @@
+import type { Repository } from "../discover.js";
+import type { EngineResult } from "./types.js";
+/**
+ * Discover the Python interpreter that ships the `semgrep` module.
+ *
+ * Selection order:
+ * 1. `SEMGREP_PYTHON` when set to an existing path — explicit operator
+ *    configuration always wins and is never silently overridden.
+ * 2. Well-known absolute paths, then `python3` on PATH (historic default).
+ *
+ * @param env - Environment to read. Defaults to the process environment.
+ *
+ * @returns The selected interpreter path, or `null` when none is available.
+ * A set-but-missing `SEMGREP_PYTHON` also yields `null` so the caller can
+ * report it as invalid configuration rather than falling back silently.
+ */
+export declare function resolvePythonForSemgrep(env?: NodeJS.ProcessEnv): string | null;
+export declare function runSemgrep(repo: Repository): Promise<EngineResult>;

package/dist/engines/semgrep.js

@@ -0,0 +1,281 @@
+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.
+ *
+ * Selection order:
+ * 1. `SEMGREP_PYTHON` when set to an existing path — explicit operator
+ *    configuration always wins and is never silently overridden.
+ * 2. Well-known absolute paths, then `python3` on PATH (historic default).
+ *
+ * @param env - Environment to read. Defaults to the process environment.
+ *
+ * @returns The selected interpreter path, or `null` when none is available.
+ * A set-but-missing `SEMGREP_PYTHON` also yields `null` so the caller can
+ * report it as invalid configuration rather than falling back silently.
+ */
+export function resolvePythonForSemgrep(env = process.env) {
+    const explicit = env["SEMGREP_PYTHON"];
+    if (explicit) {
+        return existsSync(explicit) ? explicit : null;
+    }
+    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",
+        env: { ...env, PATH: env["PATH"] ?? "" },
+    });
+    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.
+    // An explicit SEMGREP_PYTHON is honored as-is; a set-but-missing value
+    // is invalid configuration, never a reason to silently fall back.
+    const pythonBin = resolvePythonForSemgrep();
+    if (!pythonBin) {
+        cleanup();
+        const explicitPython = process.env["SEMGREP_PYTHON"];
+        return {
+            executed: false,
+            exitCode: null,
+            passed: false,
+            findings: [],
+            duration: Date.now() - start,
+            status: "TOOL-UNAVAILABLE",
+            tool: "semgrep",
+            reason: explicitPython
+                ? `SEMGREP_PYTHON is set to "${explicitPython}" but that path does not exist; set SEMGREP_PYTHON to a Python interpreter that ships the semgrep module`
+                : "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). Directories of the
+    // explicitly configured SEMGREP_BIN and resolved interpreter come first
+    // so a locally installed Semgrep resolves its own sibling scripts
+    // instead of whatever happens to be on PATH.
+    const configuredDirs = [semgrepBin, pythonBin]
+        .map((p) => p.slice(0, Math.max(0, p.lastIndexOf("/"))))
+        .filter((d) => d.length > 0);
+    const envPath = [
+        ...new Set(configuredDirs),
+        ...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";

package/dist/run.d.ts

@@ -0,0 +1,56 @@
+import type { EngineResult, Finding } from "./engines/types.js";
+export interface RunOptions {
+    /** The root directory of the repository to validate */
+    root: string;
+    /** If specified, only run the given category of validation */
+    only?: string | null;
+    /** If true, print verbose output to stdout */
+    verbose?: boolean;
+}
+export interface CategoryResult {
+    /** The status of the engine for this category */
+    status: EngineResult["status"];
+    /** Whether the engine was executed or skipped */
+    executed: boolean;
+    /** The exit code of the engine process, if applicable */
+    exitCode: number | null;
+    /** Whether the engine passed or failed */
+    passed: boolean;
+    /** The number of findings produced by the engine */
+    findings: number;
+    /** The tool that produced this result, if applicable */
+    tool?: string | undefined;
+    /** The reason for the engine's status, if applicable */
+    reason?: string | undefined;
+}
+export interface RunResult {
+    /** 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;
+    };
+}
+/**
+ * Run validation against a repository. Returns a normalized result.
+ *
+ * Every category reports either an executed engine with its real exit
+ * code, or an explicit NOT-RUN / TOOL-UNAVAILABLE / CONFIGURATION-ERROR
+ * state. PASS without execution is impossible.
+ */
+export declare function runValidation(options: RunOptions): Promise<RunResult>;