@comity-dev/validate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Filippo Bovo and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# @comity-dev/validate
+
+## Purpose
+
+Thin orchestrator over Comity shared validation tooling. Discovers a repository, invokes the specialized engines (schema, dependency-cruiser, ESLint, Semgrep, adapter-peers), and returns a normalized result.
+
+This package is intentionally small. It does **not** implement any rule. Its only responsibilities are:
+
+1. Discover repository configuration (`comity.config.json`).
+2. Discover packages.
+3. Invoke specialized engines.
+4. Collect and normalize results.
+5. Present a unified summary.
+
+## Scope
+
+The engines wrap shared Development-owned tooling:
+
+| Engine          | Tool                                    | Concern                                                    |
+| --------------- | --------------------------------------- | ---------------------------------------------------------- |
+| `schema`        | `@comity-dev/schemas` (Ajv)             | JSON Schema for package metadata and `comity.config.json`. |
+| `depcruise`     | `dependency-cruiser`                    | Dependency graph layering.                                 |
+| `eslint`        | ESLint + `@comity-dev/eslint-plugin`    | Source-code lint policy.                                   |
+| `semgrep`       | `semgrep` + `@comity-dev/semgrep-rules` | Structural source patterns.                                |
+| `adapter-peers` | in-process                              | Adapter peer-dependency contract.                          |
+
+Engines report one of `PASS` / `FAIL` / `NOT-RUN` / `TOOL-UNAVAILABLE` / `CONFIGURATION-ERROR` / `EXECUTION-ERROR` / `NOT-APPLICABLE`. `PASS` is only reported when the engine actually executed.
+
+## Ownership
+
+Owned by `comity-development`. Consumed by Comity repositories via the `comity-validate` CLI.
+
+## Public API
+
+```ts
+import {
+  runValidation,
+  discoverRepository,
+  formatSummary,
+  formatViolations,
+  ExitCode,
+} from "@comity-dev/validate";
+```
+
+## CLI
+
+```bash
+comity-validate --repo /path/to/repo
+comity-validate --only=schema        # one engine only
+comity-validate --only=eslint --verbose
+```
+
+Exit codes:
+
+- `0` — validation passed
+- `1` — validation failed (violations found)
+- `2` — configuration / discovery error
+- `3` — required tool not installed
+
+## 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`.
+
+## Development
+
+```bash
+pnpm build
+pnpm test
+```
+
+## Relationship to Comity Standards
+
+- `layering-policy.md`
+- `architecture-validation.md`
+- `ADR-008`, `ADR-026`
+- `adapters.md` §13 (adapter-peer engine)

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 { runValidation } from "../run.js";
+import { formatSummary, formatViolations } from "../format.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,82 @@
+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 = [];
+    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 the technology-adapter does not declare peerDependencies on disallowed @comity/* packages
+        for (const peerDep of Object.keys(peerDeps)) {
+            if (!peerDep.startsWith("@comity/"))
+                continue;
+            const allowed = [coreModule, ...KERNEL_PACKAGES].includes(peerDep);
+            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 or a Kernel package`,
+                    package: pkg.name,
+                    severity: "error",
+                    source: SOURCE,
+                    remediation: `Remove "${peerDep}" from peerDependencies unless it is the implemented Core Module, a Kernel package, or a required technology dependency.`,
+                });
+            }
+        }
+    }
+    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;