@comity-dev/validate 0.1.2 → 0.2.1

package/dist/run.d.ts

@@ -0,0 +1,66 @@
+import type { EngineResult, Finding } from "./engines/types.js";
+import type { ExitCodeValue } from "./exit-codes.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>;
+/**
+ * Map a validation result to the documented process exit code.
+ *
+ * A required tool that could not run must never surface as PASS: when
+ * every executed engine passed but at least one category reports
+ * `TOOL-UNAVAILABLE`, the result exits `TOOL_MISSING` (3) instead of
+ * fabricating a passing result.
+ */
+export declare function exitCodeForResult(result: RunResult): ExitCodeValue;

package/dist/run.js

@@ -0,0 +1,159 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { discoverRepository } from "./discover.js";
+import { runAdapterPeers } from "./engines/adapter-peers.js";
+import { runDepcruise } from "./engines/depcruise.js";
+import { runEslint } from "./engines/eslint.js";
+import { runSchema } from "./engines/schema.js";
+import { runSemgrep } from "./engines/semgrep.js";
+import { ExitCode } from "./exit-codes.js";
+function categoryOf(result) {
+    return {
+        status: result.status,
+        executed: result.executed,
+        exitCode: result.exitCode,
+        passed: result.passed,
+        findings: result.findings.length,
+        tool: result.tool,
+        reason: result.reason,
+    };
+}
+function emptyCategory(reason) {
+    return {
+        status: "NOT-RUN",
+        executed: false,
+        exitCode: null,
+        passed: false,
+        findings: 0,
+        reason,
+    };
+}
+function findBinDir() {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    // `__dirname` is the directory of the running module. Both the source
+    // `src/` and the built `dist/` are direct children of the package root,
+    // so the package's own `node_modules/.bin` is always exactly one level
+    // up from the running module.
+    return resolve(__dirname, "..", "node_modules", ".bin");
+}
+/**
+ * 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 async function runValidation(options) {
+    const only = options.only ?? null;
+    const repo = await discoverRepository({ root: options.root });
+    const binDir = findBinDir();
+    let schemaResult;
+    let metaResult;
+    let configResult;
+    if (!only || only === "metadata" || only === "config" || only === "schema") {
+        schemaResult = runSchema(repo);
+        const metaFindings = schemaResult.findings.filter((f) => f.rule === "package-metadata");
+        const configFindings = schemaResult.findings.filter((f) => f.rule === "comity-config");
+        metaResult = {
+            ...schemaResult,
+            findings: metaFindings,
+            passed: metaFindings.length === 0,
+            status: metaFindings.length === 0 ? "PASS" : "FAIL",
+        };
+        configResult = {
+            ...schemaResult,
+            findings: configFindings,
+            passed: configFindings.length === 0,
+            status: configFindings.length === 0 ? "PASS" : "FAIL",
+        };
+    }
+    else {
+        schemaResult = emptyEngineResult("schema engine skipped");
+        metaResult = emptyEngineResult("schema engine skipped");
+        configResult = emptyEngineResult("schema engine skipped");
+    }
+    let depResult;
+    if (!only || only === "dependencies" || only === "depcruise") {
+        depResult = runDepcruise(repo, binDir);
+    }
+    else {
+        depResult = emptyEngineResult("dependencies engine skipped");
+    }
+    let eslintResult;
+    if (!only || only === "eslint") {
+        eslintResult = runEslint(repo, binDir);
+    }
+    else {
+        eslintResult = emptyEngineResult("eslint engine skipped");
+    }
+    let semgrepResult;
+    if (!only || only === "semgrep") {
+        semgrepResult = await runSemgrep(repo);
+    }
+    else {
+        semgrepResult = emptyEngineResult("semgrep engine skipped");
+    }
+    let adapterResult;
+    if (!only || only === "adapter-peers") {
+        adapterResult = runAdapterPeers(repo);
+    }
+    else {
+        adapterResult = emptyEngineResult("adapter-peers engine skipped");
+    }
+    const violations = [];
+    for (const r of [
+        schemaResult,
+        depResult,
+        eslintResult,
+        semgrepResult,
+        adapterResult,
+    ]) {
+        if (Array.isArray(r.findings)) {
+            violations.push(...r.findings);
+        }
+    }
+    const allExecuted = [depResult, eslintResult, semgrepResult, adapterResult];
+    const allPassed = allExecuted.every((r) => (r.executed ? r.passed : r.status !== "FAIL")) &&
+        (metaResult.executed ? metaResult.passed : metaResult.status !== "FAIL") &&
+        (configResult.executed
+            ? configResult.passed
+            : configResult.status !== "FAIL");
+    return {
+        passed: allPassed,
+        violations,
+        categories: {
+            schema: categoryOf(schemaResult),
+            metadata: categoryOf(metaResult),
+            config: categoryOf(configResult),
+            dependencies: categoryOf(depResult),
+            eslint: categoryOf(eslintResult),
+            semgrep: categoryOf(semgrepResult),
+            adapterPeers: categoryOf(adapterResult),
+        },
+    };
+}
+function emptyEngineResult(reason) {
+    return {
+        executed: false,
+        exitCode: null,
+        passed: false,
+        findings: [],
+        duration: 0,
+        status: "NOT-RUN",
+        reason,
+    };
+}
+/**
+ * Map a validation result to the documented process exit code.
+ *
+ * A required tool that could not run must never surface as PASS: when
+ * every executed engine passed but at least one category reports
+ * `TOOL-UNAVAILABLE`, the result exits `TOOL_MISSING` (3) instead of
+ * fabricating a passing result.
+ */
+export function exitCodeForResult(result) {
+    if (!result.passed)
+        return ExitCode.FAIL;
+    const toolUnavailable = Object.values(result.categories).some((c) => c.status === "TOOL-UNAVAILABLE");
+    return toolUnavailable ? ExitCode.TOOL_MISSING : ExitCode.PASS;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comity-dev/validate",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Thin orchestrator over Comity shared validation tooling. Development tooling.",
   "type": "module",
   "private": false,
@@ -34,10 +34,10 @@
     "@typescript-eslint/parser": "^8.69.0",
     "dependency-cruiser": "^16.10.4",
     "eslint": "^9.39.5",
-    "@comity-dev/schemas": "0.1.1",
-    "@comity-dev/dependency-rules": "0.1.1",
-    "@comity-dev/eslint-plugin": "0.1.2",
-    "@comity-dev/semgrep-rules": "0.1.2"
+    "@comity-dev/schemas": "0.2.0",
+    "@comity-dev/dependency-rules": "0.2.0",
+    "@comity-dev/eslint-plugin": "0.2.0",
+    "@comity-dev/semgrep-rules": "0.2.1"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",