@comity-dev/validate 0.1.0 → 0.1.1

package/dist/engines/schema.js

@@ -1,48 +0,0 @@
-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

@@ -1,3 +0,0 @@
-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

@@ -1,252 +0,0 @@
-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

@@ -1,25 +0,0 @@
-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

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

package/dist/exit-codes.d.ts

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

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

@@ -1,33 +0,0 @@
-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

@@ -1,76 +0,0 @@
-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

@@ -1,9 +0,0 @@
-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

@@ -1,4 +0,0 @@
-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

@@ -1,56 +0,0 @@
-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>;