@comity-dev/validate 0.2.2 → 0.3.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,7 @@ 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).       |
 
 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 +49,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
@@ -59,7 +61,7 @@ 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)
  *                        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)
  *                        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)
 
 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,3 @@
+import type { Repository } from "../discover.js";
+import type { EngineResult } from "./types.js";
+export declare function runDeclarationDependencies(repo: Repository): EngineResult;

package/dist/engines/declaration-dependencies.js

@@ -0,0 +1,437 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { builtinModules } from "node:module";
+import { dirname, join, relative, resolve } from "node:path";
+import ts from "typescript";
+import { discoverPublishablePackages } from "../discover.js";
+const SOURCE = "ADR-035";
+const BUILTINS = new Set(builtinModules);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringSet(value) {
+    if (!isRecord(value))
+        return new Set();
+    return new Set(Object.keys(value));
+}
+function dependencySets(manifest) {
+    const peers = stringSet(manifest["peerDependencies"]);
+    const meta = isRecord(manifest["peerDependenciesMeta"])
+        ? manifest["peerDependenciesMeta"]
+        : {};
+    return {
+        dependencies: stringSet(manifest["dependencies"]),
+        peers,
+        optionalPeers: new Set([...peers].filter((name) => {
+            const entry = meta[name];
+            return isRecord(entry) && entry["optional"] === true;
+        })),
+        dev: stringSet(manifest["devDependencies"]),
+        optional: stringSet(manifest["optionalDependencies"]),
+        exports: isRecord(manifest["exports"]) ? Object.keys(manifest["exports"]) : [],
+    };
+}
+function isDeclarationFile(path) {
+    return /\.d\.(?:ts|mts|cts)$/.test(path);
+}
+function collectDeclarationTargets(pkg) {
+    const targets = new Map();
+    const add = (entry, value) => {
+        if (value.includes("*") || !isDeclarationFile(value))
+            return;
+        const absolute = resolve(pkg.path, value);
+        const files = targets.get(entry) ?? new Set();
+        files.add(absolute);
+        targets.set(entry, files);
+    };
+    const walk = (entry, value) => {
+        if (typeof value === "string") {
+            add(entry, value);
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value)
+                walk(entry, item);
+            return;
+        }
+        if (isRecord(value)) {
+            for (const item of Object.values(value))
+                walk(entry, item);
+        }
+    };
+    const exportsField = pkg.manifest["exports"];
+    if (typeof exportsField === "string") {
+        walk(".", exportsField);
+    }
+    else if (isRecord(exportsField)) {
+        for (const [entry, value] of Object.entries(exportsField))
+            walk(entry, value);
+    }
+    const types = pkg.manifest["types"];
+    if (typeof types === "string")
+        add(".", types);
+    const typesVersions = pkg.manifest["typesVersions"];
+    if (isRecord(typesVersions)) {
+        for (const mapping of Object.values(typesVersions)) {
+            if (!isRecord(mapping))
+                continue;
+            for (const [subpath, value] of Object.entries(mapping)) {
+                const entry = subpath.startsWith(".")
+                    ? subpath
+                    : subpath === "*"
+                        ? "*"
+                        : `./${subpath}`;
+                walk(entry, value);
+            }
+        }
+    }
+    return targets;
+}
+function parseDeclaration(file) {
+    const text = readFileSync(file, "utf8");
+    const sourceFile = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+    const relativeSpecifiers = new Set();
+    const externalSpecifiers = new Set();
+    const isModule = ts.isExternalModule(sourceFile);
+    const add = (specifier) => {
+        if (specifier.startsWith("."))
+            relativeSpecifiers.add(specifier);
+        else
+            externalSpecifiers.add(specifier);
+    };
+    const visit = (node) => {
+        if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) {
+            if (node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+                add(node.moduleSpecifier.text);
+            }
+        }
+        else if (ts.isImportEqualsDeclaration(node)) {
+            const reference = node.moduleReference;
+            if (ts.isExternalModuleReference(reference) &&
+                reference.expression &&
+                ts.isStringLiteral(reference.expression)) {
+                add(reference.expression.text);
+            }
+        }
+        else if (ts.isImportTypeNode(node)) {
+            const argument = node.argument;
+            if (ts.isLiteralTypeNode(argument) && ts.isStringLiteral(argument.literal)) {
+                add(argument.literal.text);
+            }
+        }
+        else if (isModule &&
+            ts.isModuleDeclaration(node) &&
+            ts.isStringLiteral(node.name)) {
+            add(node.name.text);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    for (const reference of sourceFile.referencedFiles)
+        add(reference.fileName);
+    for (const reference of sourceFile.typeReferenceDirectives) {
+        externalSpecifiers.add(reference.fileName);
+    }
+    return {
+        relative: [...relativeSpecifiers],
+        external: [...externalSpecifiers],
+    };
+}
+function resolveRelative(specifier, fromFile) {
+    const base = resolve(dirname(fromFile), specifier);
+    const candidates = [];
+    if (base.endsWith(".js"))
+        candidates.push(`${base.slice(0, -3)}.d.ts`);
+    else if (base.endsWith(".mjs"))
+        candidates.push(`${base.slice(0, -4)}.d.mts`);
+    else if (base.endsWith(".cjs"))
+        candidates.push(`${base.slice(0, -4)}.d.cts`);
+    else if (isDeclarationFile(base))
+        candidates.push(base);
+    candidates.push(`${base}.d.ts`, join(base, "index.d.ts"));
+    return candidates.find((candidate) => {
+        return existsSync(candidate) && statSync(candidate).isFile();
+    }) ?? null;
+}
+function packageNameOf(specifier) {
+    const parts = specifier.split("/");
+    return specifier.startsWith("@")
+        ? parts.slice(0, 2).join("/")
+        : (parts[0] ?? specifier);
+}
+function subpathOf(specifier, owner) {
+    if (specifier === owner)
+        return "";
+    return specifier.startsWith(`${owner}/`)
+        ? `.${specifier.slice(owner.length)}`
+        : "";
+}
+function typesPackageName(owner) {
+    if (!owner.startsWith("@"))
+        return `@types/${owner}`;
+    const [scope, name] = owner.split("/");
+    return `@types/${scope?.slice(1) ?? ""}__${name ?? ""}`;
+}
+function matchesSubpath(exportKeys, subpath) {
+    return exportKeys.some((key) => {
+        if (key === subpath)
+            return true;
+        if (!key.includes("*"))
+            return false;
+        const pattern = key
+            .split("*")
+            .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+            .join(".*");
+        return new RegExp(`^${pattern}$`).test(subpath);
+    });
+}
+function isBuiltin(specifier) {
+    return specifier.startsWith("node:") || BUILTINS.has(specifier);
+}
+function finding(context, rule, specifier, file, message, remediation) {
+    return {
+        tool: "declarations",
+        rule,
+        package: context.packageRecord.name,
+        file,
+        keyword: specifier,
+        severity: "error",
+        source: SOURCE,
+        message,
+        remediation,
+    };
+}
+function classifyExternal(specifier, file, context) {
+    const owner = packageNameOf(specifier);
+    if (isBuiltin(specifier))
+        return null;
+    const { packageRecord, sets } = context;
+    const subpath = subpathOf(specifier, owner);
+    if (owner === packageRecord.name) {
+        if (subpath && !matchesSubpath(sets.exports, subpath)) {
+            return finding(context, "ARCH-DECL-DEP-004", specifier, file, `Package "${packageRecord.name}" exposes "${specifier}" in published declarations (${file}, via entry "${context.entry}") but references a subpath that is not exported by the package`, "Export the subpath or fix the reference.");
+        }
+        return null;
+    }
+    const typesOwner = typesPackageName(owner);
+    const declared = sets.dependencies.has(owner) ||
+        sets.peers.has(owner) ||
+        sets.dependencies.has(typesOwner) ||
+        sets.peers.has(typesOwner);
+    if (declared) {
+        const optionalPeer = sets.optionalPeers.has(owner) && !sets.dependencies.has(owner);
+        if (optionalPeer && context.rootReached) {
+            return finding(context, "ARCH-DECL-DEP-003", specifier, file, `Package "${packageRecord.name}" exposes optional peer "${owner}" in published declarations (${file}, via entry "${context.entry}") reachable from the root entry "."; consumers without it get unresolved types`, "Make the peer required, or move the reference behind an opt-in subpath.");
+        }
+        const sibling = context.packages.get(owner);
+        if (subpath && sibling) {
+            const siblingSets = dependencySets(sibling.manifest);
+            if (!matchesSubpath(siblingSets.exports, subpath)) {
+                return finding(context, "ARCH-DECL-DEP-005", specifier, file, `Package "${packageRecord.name}" exposes "${specifier}" in published declarations (${file}, via entry "${context.entry}") but "${subpath}" is not an exported subpath of "${owner}"`, "Import an exported subpath.");
+            }
+        }
+        return null;
+    }
+    const devOwner = sets.dev.has(owner)
+        ? owner
+        : sets.dev.has(typesOwner)
+            ? typesOwner
+            : null;
+    if (devOwner) {
+        return finding(context, "ARCH-DECL-DEP-002", specifier, file, `Package "${packageRecord.name}" exposes "${specifier}" in published declarations (${file}, via entry "${context.entry}") but "${devOwner}" is only a devDependency; consumers get TS2307, or "any" under skipLibCheck`, `Move or add "${devOwner}" to peerDependencies or dependencies.`);
+    }
+    if (sets.optional.has(owner) || sets.optional.has(typesOwner)) {
+        const optionalOwner = sets.optional.has(owner) ? owner : typesOwner;
+        return finding(context, "ARCH-DECL-DEP-001", specifier, file, `Package "${packageRecord.name}" exposes "${specifier}" in published declarations (${file}, via entry "${context.entry}") but declares "${optionalOwner}" only in optionalDependencies; optional dependencies are not guaranteed to be installed for consumers`, `Move or add "${optionalOwner}" to peerDependencies or dependencies.`);
+    }
+    return finding(context, "ARCH-DECL-DEP-001", specifier, file, `Package "${packageRecord.name}" exposes "${specifier}" in published declarations (${file}, via entry "${context.entry}") but declares "${owner}" in neither dependencies nor peerDependencies`, `Add "${owner}" as a peerDependency (nominal or shared types) or a dependency (private structural types).`);
+}
+function countDeclarationFiles(directory) {
+    let count = 0;
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        if (entry.name === "node_modules" || entry.name === ".turbo")
+            continue;
+        const path = join(directory, entry.name);
+        if (entry.isDirectory())
+            count += countDeclarationFiles(path);
+        else if (entry.isFile() && isDeclarationFile(entry.name))
+            count += 1;
+    }
+    return count;
+}
+function sortFindings(findings) {
+    findings.sort((a, b) => {
+        return ((a.package ?? "").localeCompare(b.package ?? "") ||
+            (a.file ?? "").localeCompare(b.file ?? "") ||
+            (a.keyword ?? "").localeCompare(b.keyword ?? "") ||
+            a.rule.localeCompare(b.rule));
+    });
+}
+export function runDeclarationDependencies(repo) {
+    const start = Date.now();
+    const discovery = discoverPublishablePackages(repo.root);
+    if (discovery.publishable.length === 0) {
+        if (discovery.allPackages.length === 0) {
+            const defaultNote = discovery.usedDefaultRoots
+                ? " The default package root was used."
+                : "";
+            const excludedNote = discovery.excluded.length > 0
+                ? ` Excluded package directories: ${discovery.excluded.map((pkg) => pkg.path).join(", ")}.`
+                : "";
+            return {
+                executed: false,
+                exitCode: null,
+                passed: false,
+                findings: [],
+                duration: Date.now() - start,
+                status: "CONFIGURATION-ERROR",
+                tool: "declarations",
+                reason: `No package directory with a readable package.json was found under root(s): ${discovery.roots.join(", ")}.${defaultNote}${excludedNote}`,
+            };
+        }
+        const privatePackages = discovery.excluded
+            .filter((pkg) => pkg.reason === "private package")
+            .map((pkg) => pkg.name ?? pkg.path);
+        return {
+            executed: false,
+            exitCode: null,
+            passed: false,
+            findings: [],
+            duration: Date.now() - start,
+            status: "NOT-APPLICABLE",
+            tool: "declarations",
+            reason: `All discovered packages are private: ${privatePackages.join(", ")}.`,
+        };
+    }
+    const allPackages = new Map(discovery.allPackages.map((pkg) => [pkg.name, pkg]));
+    const findings = [];
+    let totalDeclarationFiles = 0;
+    let reachableDeclarationFiles = 0;
+    let externalReferenceCount = 0;
+    const configurationErrors = [];
+    for (const pkg of discovery.publishable) {
+        totalDeclarationFiles += countDeclarationFiles(pkg.path);
+        const targets = collectDeclarationTargets(pkg);
+        if (targets.size === 0)
+            continue;
+        const entries = [...targets.entries()].sort(([a], [b]) => a.localeCompare(b));
+        const missingTarget = [...targets.values()]
+            .flatMap((files) => [...files])
+            .sort()
+            .find((file) => !existsSync(file) || !statSync(file).isFile());
+        if (missingTarget) {
+            configurationErrors.push(`Package "${pkg.name}" declares a missing declaration target: ${relative(pkg.path, missingTarget).split("\\").join("/")}`);
+            continue;
+        }
+        const parsed = new Map();
+        const entryKeysByFile = new Map();
+        const unresolvedRelative = new Map();
+        const queue = [];
+        for (const [entry, files] of entries) {
+            for (const file of [...files].sort()) {
+                queue.push({ file, entry });
+            }
+        }
+        for (let index = 0; index < queue.length; index += 1) {
+            const item = queue[index];
+            if (!item)
+                continue;
+            const keys = entryKeysByFile.get(item.file) ?? new Set();
+            if (keys.has(item.entry))
+                continue;
+            keys.add(item.entry);
+            entryKeysByFile.set(item.file, keys);
+            let declaration = parsed.get(item.file);
+            if (!declaration) {
+                declaration = parseDeclaration(item.file);
+                parsed.set(item.file, declaration);
+            }
+            for (const specifier of declaration.relative) {
+                const resolved = resolveRelative(specifier, item.file);
+                if (resolved) {
+                    queue.push({ file: resolved, entry: item.entry });
+                }
+                else {
+                    const entriesForFile = unresolvedRelative.get(`${item.file}\0${specifier}`) ??
+                        new Set();
+                    entriesForFile.add(item.entry);
+                    unresolvedRelative.set(`${item.file}\0${specifier}`, entriesForFile);
+                }
+            }
+        }
+        reachableDeclarationFiles += entryKeysByFile.size;
+        for (const [key, entryKeys] of unresolvedRelative) {
+            const [file, specifier] = key.split("\0");
+            if (!file || !specifier)
+                continue;
+            const entry = [...entryKeys].sort()[0] ?? "?";
+            findings.push({
+                tool: "declarations",
+                rule: "ARCH-DECL-DEP-000",
+                package: pkg.name,
+                file: relative(pkg.path, file).split("\\").join("/"),
+                keyword: specifier,
+                severity: "error",
+                source: SOURCE,
+                message: `Package "${pkg.name}" has an unresolvable relative reference "${specifier}" in declaration "${relative(pkg.path, file).split("\\").join("/")}" (reached via entry "${entry}"); the built declaration graph is broken`,
+                remediation: "Rebuild the package, or fix the relative import so it resolves to an emitted declaration.",
+            });
+        }
+        for (const [file, entryKeys] of entryKeysByFile) {
+            const declaration = parsed.get(file);
+            if (!declaration)
+                continue;
+            const entry = [...entryKeys].sort()[0] ?? "?";
+            const rootReached = entryKeys.has(".");
+            const sets = dependencySets(pkg.manifest);
+            const context = {
+                packageRecord: pkg,
+                sets,
+                packages: allPackages,
+                rootReached,
+                entry,
+            };
+            for (const specifier of [...declaration.external].sort()) {
+                externalReferenceCount += 1;
+                const result = classifyExternal(specifier, relative(pkg.path, file).split("\\").join("/"), context);
+                if (result)
+                    findings.push(result);
+            }
+        }
+    }
+    if (configurationErrors.length > 0) {
+        return {
+            executed: false,
+            exitCode: null,
+            passed: false,
+            findings: [],
+            duration: Date.now() - start,
+            status: "CONFIGURATION-ERROR",
+            tool: "declarations",
+            reason: configurationErrors.join("; "),
+        };
+    }
+    sortFindings(findings);
+    const excludedNotes = discovery.excluded.map((pkg) => {
+        return `${pkg.name ?? pkg.path} (${pkg.reason})`;
+    });
+    const notes = [
+        `${discovery.publishable.length} publishable package(s)`,
+        `${totalDeclarationFiles} declaration file(s) (${reachableDeclarationFiles} entry-reachable)`,
+        `${externalReferenceCount} external reference(s)`,
+    ];
+    if (discovery.usedDefaultRoots)
+        notes.push("default package root was used");
+    if (excludedNotes.length > 0) {
+        notes.push(`excluded: ${excludedNotes.join(", ")}`);
+    }
+    return {
+        executed: true,
+        exitCode: 0,
+        passed: findings.length === 0,
+        findings,
+        duration: Date.now() - start,
+        status: findings.length === 0 ? "PASS" : "FAIL",
+        tool: "declarations",
+        reason: notes.join("; "),
+    };
+}

package/dist/exit-codes.d.ts

@@ -3,7 +3,7 @@
  *
  *   0 = validation passed
  *   1 = validation failed (violations found)
- *   2 = configuration / discovery error (cannot run)
+ *   2 = configuration / discovery error (cannot run; may co-occur with violations)
  *   3 = tool not installed (e.g. dependency-cruiser missing)
  */
 export declare const ExitCode: Readonly<{

package/dist/exit-codes.js

@@ -3,7 +3,7 @@
  *
  *   0 = validation passed
  *   1 = validation failed (violations found)
- *   2 = configuration / discovery error (cannot run)
+ *   2 = configuration / discovery error (cannot run; may co-occur with violations)
  *   3 = tool not installed (e.g. dependency-cruiser missing)
  */
 export const ExitCode = Object.freeze({

package/dist/format.d.ts

@@ -21,6 +21,8 @@ export interface FormatInput {
         semgrep: CategoryResult;
         /** Adapter peers validation results */
         adapterPeers: CategoryResult;
+        /** Published declaration dependency validation results */
+        declarations: CategoryResult;
     };
 }
 /**

package/dist/format.js

@@ -6,6 +6,7 @@ const CATEGORY_LABELS = {
     eslint: "Source rules (ESLint)",
     semgrep: "Structural patterns (Semgrep)",
     adapterPeers: "Adapter peers",
+    declarations: "Declarations",
 };
 function statusBadge(cat) {
     switch (cat.status) {
@@ -67,6 +68,9 @@ export function formatSummary(result) {
             cat.status === "NOT-APPLICABLE") {
             lines.push(`  ${label}: ${cat.reason ?? cat.status}`);
         }
+        else if (cat.status === "PASS" && cat.reason) {
+            lines.push(`  ${label}: ${cat.reason}`);
+        }
     }
     lines.push("");
     lines.push(`Result: ${overallResult(result)}`);

package/dist/run.d.ts

@@ -45,6 +45,8 @@ export interface RunResult {
         semgrep: CategoryResult;
         /** Adapter peers validation results */
         adapterPeers: CategoryResult;
+        /** Published declaration dependency validation results */
+        declarations: CategoryResult;
     };
 }
 /**

package/dist/run.js

@@ -2,6 +2,7 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { discoverRepository } from "./discover.js";
 import { runAdapterPeers } from "./engines/adapter-peers.js";
+import { runDeclarationDependencies } from "./engines/declaration-dependencies.js";
 import { runDepcruise } from "./engines/depcruise.js";
 import { runEslint } from "./engines/eslint.js";
 import { runSchema } from "./engines/schema.js";
@@ -115,6 +116,15 @@ export async function runValidation(options) {
     else {
         adapterResult = emptyEngineResult("adapter-peers engine skipped");
     }
+    let declarationResult;
+    if (!only ||
+        only === "declarations" ||
+        only === "declaration-dependencies") {
+        declarationResult = runDeclarationDependencies(repo);
+    }
+    else {
+        declarationResult = emptyEngineResult("declarations engine skipped");
+    }
     const violations = [];
     for (const r of [
         schemaResult,
@@ -122,12 +132,19 @@ export async function runValidation(options) {
         eslintResult,
         semgrepResult,
         adapterResult,
+        declarationResult,
     ]) {
         if (Array.isArray(r.findings)) {
             violations.push(...r.findings);
         }
     }
-    const allExecuted = [depResult, eslintResult, semgrepResult, adapterResult];
+    const allExecuted = [
+        depResult,
+        eslintResult,
+        semgrepResult,
+        adapterResult,
+        declarationResult,
+    ];
     const allPassed = allExecuted.every(categoryIsAcceptable) &&
         categoryIsAcceptable(metaResult) &&
         categoryIsAcceptable(configResult);
@@ -142,6 +159,7 @@ export async function runValidation(options) {
             eslint: categoryOf(eslintResult),
             semgrep: categoryOf(semgrepResult),
             adapterPeers: categoryOf(adapterResult),
+            declarations: categoryOf(declarationResult),
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comity-dev/validate",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Thin orchestrator over Comity shared validation tooling. Development tooling.",
   "type": "module",
   "private": false,
@@ -31,20 +31,20 @@
     "./dist"
   ],
   "dependencies": {
-    "@typescript-eslint/parser": "^8.69.0",
-    "dependency-cruiser": "^16.10.4",
-    "eslint": "^9.39.5",
     "@comity-dev/schemas": "0.2.0",
     "@comity-dev/dependency-rules": "0.2.0",
     "@comity-dev/eslint-plugin": "0.3.0",
-    "@comity-dev/semgrep-rules": "0.2.2"
+    "@comity-dev/semgrep-rules": "0.2.3",
+    "@typescript-eslint/parser": "^8.69.0",
+    "dependency-cruiser": "^16.10.4",
+    "eslint": "^9.39.5",
+    "typescript": "^5.9.3"
   },
   "devDependencies": {
-    "@types/node": "^24.13.3",
-    "typescript": "^5.9.3"
+    "@types/node": "^24.13.3"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "test": "vitest run"
   }
 }