@comity-dev/validate 0.2.3 → 0.4.0

package/README.md

@@ -2,9 +2,10 @@
 
 ## 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.
+Thin orchestrator over Comity shared validation tooling. Discovers a repository, invokes the specialized engines (schema, dependency-cruiser, ESLint, Semgrep, adapter-peers, declarations), and returns a normalized result.
 
-This package is intentionally small. It does **not** implement any rule. Its only responsibilities are:
+This package is intentionally small. It does **not** implement source-code rules; the in-process declaration engine
+implements the rules in ADR-035. Its only responsibilities are:
 
 1. Discover repository configuration (`comity.config.json`).
 2. Discover packages.
@@ -23,6 +24,8 @@ The engines wrap shared Development-owned tooling:
 | `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.                          |
+| `declarations`  | in-process + TypeScript                 | Published declaration dependency contract (ADR-035).       |
+| `packed-surface` | in-process + `pnpm pack` + system `tar` | Packed tarball surface: rules `ARCH-PACK-001…006` (ADR-035 stage 2). |
 
 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.
 
@@ -47,7 +50,7 @@ import {
 ```bash
 comity-validate --repo /path/to/repo
 comity-validate --only=schema        # one engine only
-comity-validate --only=eslint --verbose
+comity-validate --only=declarations
 ```
 
 `--only <category>` runs a single engine. Policies owned by another engine are
@@ -55,11 +58,27 @@ not evaluated: `--only semgrep` does not check ESLint-owned policy, including
 the required `@internal` marker rule (`@comity-dev/require-internal-marker`).
 Use the default run (no `--only`) for full policy coverage.
 
+### `packed-surface` (ADR-035 stage 2)
+
+`--only=packed-surface` packs every publishable package with `pnpm pack`, reads the resulting tarball (file list,
+contents and packed `package.json`) with the system `tar`, and applies `ARCH-PACK-001…006`. It never reads the
+workspace `dist`, so it observes the effect of the `files` field, `exports` and `workspace:` rewriting — which stage 1
+cannot see.
+
+It is deliberately **not part of the default run**: it packs every package (slower) and it runs in the producer
+repository after `pnpm build` and before publication. Both release workflows run it after `Build` and before the
+Changesets `Release` step.
+
+**Enforcement is gated.** The release-workflow step blocks publication only when the repository variable
+`COMITY_PACKED_SURFACE_ENFORCEMENT` is `true`. It must stay unset until **WP-A1** (Community `workspace:*` migration),
+**WP-A4** (Development `@comity-dev/*` migration) and **WP-B** formal ratification are complete, because `pnpm pack`
+rewrites `workspace:*` to an exact pin and `ARCH-PACK-005` reports those pins.
+
 Exit codes:
 
 - `0` — validation passed
 - `1` — validation failed (violations found)
-- `2` — configuration / discovery error
+- `2` — configuration / discovery error (may co-occur with findings)
 - `3` — required tool not installed
 
 ## Environment

package/dist/bin/comity-validate.d.ts

@@ -10,7 +10,7 @@
  *   --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)
+ *                        (schema | metadata | config | dependencies | eslint | semgrep | adapter-peers | declarations | declaration-dependencies | packed-surface)
  *                        Default: run all categories.
  *
  * Exit codes:

package/dist/bin/comity-validate.js

@@ -10,7 +10,7 @@
  *   --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)
+ *                        (schema | metadata | config | dependencies | eslint | semgrep | adapter-peers | declarations | declaration-dependencies | packed-surface)
  *                        Default: run all categories.
  *
  * Exit codes:
@@ -62,7 +62,7 @@ Options:
   --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)
+                       (schema | metadata | config | dependencies | eslint | semgrep | adapter-peers | declarations | declaration-dependencies | packed-surface)
 
 Exit codes:
   0  validation passed
@@ -83,15 +83,20 @@ async function main() {
             verbose: args.verbose,
             only: args.only,
         });
+        const exitCode = exitCodeForResult(result);
         console.log(formatSummary(result));
-        if (!result.passed && args.verbose) {
+        if (result.violations.length > 0) {
             console.log("");
             console.log(formatViolations(result.violations));
         }
+        if (exitCode === ExitCode.CONFIG_ERROR && result.violations.length > 0) {
+            console.log("");
+            console.log("Configuration error(s) took precedence over validation findings (exit code 2).");
+        }
         // A required tool that could not run must never surface as PASS:
         // report it with the documented TOOL_MISSING exit code instead of
         // fabricating a passing result.
-        process.exit(exitCodeForResult(result));
+        process.exit(exitCode);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);

package/dist/discover.d.ts

@@ -39,3 +39,31 @@ export interface DiscoverOptions {
  * package roots, and produce a normalized Repository handle.
  */
 export declare function discoverRepository({ root, }: DiscoverOptions): Promise<Repository>;
+export interface ExcludedPackage {
+    /** The absolute path of the excluded package directory. */
+    path: string;
+    /** The package's `name` field, when it has a readable string name. */
+    name: string | null;
+    /** Why this package is not publishable. */
+    reason: string;
+}
+export interface PublishableDiscovery {
+    /** The configured package roots, relative to the repository root. */
+    roots: string[];
+    /** Whether the default root was used because no explicit roots were configured. */
+    usedDefaultRoots: boolean;
+    /** Every discovered package with a readable manifest and a string name, including private packages. */
+    allPackages: PackageRecord[];
+    /** Packages that participate in stage 1 declaration validation. */
+    publishable: PackageRecord[];
+    /** Packages excluded from validation, with the reason recorded. */
+    excluded: ExcludedPackage[];
+}
+/**
+ * Discover every package under the configured roots, with no namespace filter.
+ *
+ * This is the discovery used by the stage 1 and stage 2 engines. It deliberately
+ * does not change `discoverRepository`, whose existing engines still use the
+ * legacy name-based classification.
+ */
+export declare function discoverPublishablePackages(root: string): PublishableDiscovery;

package/dist/discover.js

@@ -5,8 +5,9 @@
  * roots to produce a normalized Repository handle that the orchestrator
  * passes to specialized validators.
  */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { readdir, readFile, stat } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { join, matchesGlob, relative, resolve } from "node:path";
 /**
  * Discover a repository: load comity.config.json, walk the configured
  * package roots, and produce a normalized Repository handle.
@@ -72,3 +73,128 @@ export async function discoverRepository({ root, }) {
         config: config ?? {},
     };
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readConfig(root) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(root, "comity.config.json"), "utf8"));
+        return isRecord(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function configuredRoots(config) {
+    const packages = isRecord(config) && isRecord(config["packages"])
+        ? config["packages"]
+        : null;
+    const configured = packages?.["roots"];
+    const roots = Array.isArray(configured) &&
+        configured.length > 0 &&
+        configured.every((root) => typeof root === "string")
+        ? configured
+        : ["packages"];
+    const defaulted = !Array.isArray(configured) ||
+        configured.length === 0 ||
+        !configured.every((root) => typeof root === "string");
+    const excludeValue = packages?.["exclude"];
+    const exclude = Array.isArray(excludeValue)
+        ? excludeValue.filter((pattern) => typeof pattern === "string")
+        : [];
+    return { roots, usedDefaultRoots: defaulted, exclude };
+}
+function isExcluded(relativePath, patterns) {
+    return patterns.some((pattern) => matchesGlob(relativePath, pattern));
+}
+/**
+ * Discover every package under the configured roots, with no namespace filter.
+ *
+ * This is the discovery used by the stage 1 and stage 2 engines. It deliberately
+ * does not change `discoverRepository`, whose existing engines still use the
+ * legacy name-based classification.
+ */
+export function discoverPublishablePackages(root) {
+    const absRoot = resolve(root);
+    const config = readConfig(absRoot);
+    const { roots, usedDefaultRoots, exclude } = configuredRoots(config);
+    const allPackages = [];
+    const publishable = [];
+    const excluded = [];
+    for (const relRoot of roots) {
+        const dir = join(absRoot, relRoot);
+        if (!existsSync(dir) || !statSync(dir).isDirectory())
+            continue;
+        const entries = readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+            const pkgDir = join(dir, entry.name);
+            const manifestPath = join(pkgDir, "package.json");
+            if (!existsSync(manifestPath) || !statSync(manifestPath).isFile())
+                continue;
+            let manifest;
+            try {
+                const parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+                if (!isRecord(parsed)) {
+                    excluded.push({
+                        path: pkgDir,
+                        name: null,
+                        reason: "package.json is not a JSON object",
+                    });
+                    continue;
+                }
+                manifest = parsed;
+            }
+            catch {
+                excluded.push({
+                    path: pkgDir,
+                    name: null,
+                    reason: "package.json is not readable JSON",
+                });
+                continue;
+            }
+            const name = manifest["name"];
+            if (typeof name !== "string" || name.length === 0) {
+                excluded.push({
+                    path: pkgDir,
+                    name: null,
+                    reason: "package.json has no string name",
+                });
+                continue;
+            }
+            const relativePath = relative(absRoot, pkgDir).split("\\").join("/");
+            if (isExcluded(relativePath, exclude)) {
+                excluded.push({
+                    path: pkgDir,
+                    name,
+                    reason: "matched packages.exclude",
+                });
+                continue;
+            }
+            const comity = isRecord(manifest["comity"]) ? manifest["comity"] : null;
+            const layer = comity?.["layer"];
+            const record = {
+                name,
+                path: pkgDir,
+                layer: typeof layer === "string" ? layer : null,
+                manifest,
+            };
+            allPackages.push(record);
+            if (manifest["private"] === true) {
+                excluded.push({
+                    path: pkgDir,
+                    name,
+                    reason: "private package",
+                });
+            }
+            else {
+                publishable.push(record);
+            }
+        }
+    }
+    allPackages.sort((a, b) => a.path.localeCompare(b.path));
+    publishable.sort((a, b) => a.path.localeCompare(b.path));
+    excluded.sort((a, b) => a.path.localeCompare(b.path));
+    return { roots, usedDefaultRoots, allPackages, publishable, excluded };
+}

package/dist/engines/declaration-dependencies.d.ts

@@ -0,0 +1,29 @@
+import type { PackageRecord, Repository } from "../discover.js";
+import type { EngineResult, Finding } from "./types.js";
+interface DependencySets {
+    dependencies: Set<string>;
+    peers: Set<string>;
+    optionalPeers: Set<string>;
+    dev: Set<string>;
+    optional: Set<string>;
+    exports: string[];
+}
+interface ParsedDeclaration {
+    relative: string[];
+    external: string[];
+}
+export interface QueryContext {
+    packageRecord: PackageRecord;
+    sets: DependencySets;
+    packages: Map<string, PackageRecord>;
+    rootReached: boolean;
+    entry: string;
+    tool?: string | undefined;
+}
+export declare function dependencySets(manifest: Record<string, unknown>): DependencySets;
+export declare function isDeclarationFile(path: string): boolean;
+export declare function parseDeclarationText(file: string, text: string): ParsedDeclaration;
+export declare function classifyExternal(specifier: string, file: string, context: QueryContext): Finding | null;
+export declare function sortFindings(findings: Finding[]): void;
+export declare function runDeclarationDependencies(repo: Repository): EngineResult;
+export {};