@comity-dev/validate 0.3.0 → 0.4.0

package/README.md

@@ -25,6 +25,7 @@ The engines wrap shared Development-owned tooling:
 | `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.
 
@@ -57,6 +58,22 @@ 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

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 | declarations | declaration-dependencies)
+ *                        (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 | declarations | declaration-dependencies)
+ *                        (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 | declarations | declaration-dependencies)
+                       (schema | metadata | config | dependencies | eslint | semgrep | adapter-peers | declarations | declaration-dependencies | packed-surface)
 
 Exit codes:
   0  validation passed

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

@@ -1,3 +1,29 @@
-import type { Repository } from "../discover.js";
-import type { EngineResult } from "./types.js";
+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 {};

package/dist/engines/declaration-dependencies.js

@@ -13,7 +13,7 @@ function stringSet(value) {
         return new Set();
     return new Set(Object.keys(value));
 }
-function dependencySets(manifest) {
+export function dependencySets(manifest) {
     const peers = stringSet(manifest["peerDependencies"]);
     const meta = isRecord(manifest["peerDependenciesMeta"])
         ? manifest["peerDependenciesMeta"]
@@ -30,7 +30,7 @@ function dependencySets(manifest) {
         exports: isRecord(manifest["exports"]) ? Object.keys(manifest["exports"]) : [],
     };
 }
-function isDeclarationFile(path) {
+export function isDeclarationFile(path) {
     return /\.d\.(?:ts|mts|cts)$/.test(path);
 }
 function collectDeclarationTargets(pkg) {
@@ -86,8 +86,7 @@ function collectDeclarationTargets(pkg) {
     }
     return targets;
 }
-function parseDeclaration(file) {
-    const text = readFileSync(file, "utf8");
+export function parseDeclarationText(file, text) {
     const sourceFile = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
     const relativeSpecifiers = new Set();
     const externalSpecifiers = new Set();
@@ -136,6 +135,9 @@ function parseDeclaration(file) {
         external: [...externalSpecifiers],
     };
 }
+function parseDeclaration(file) {
+    return parseDeclarationText(file, readFileSync(file, "utf8"));
+}
 function resolveRelative(specifier, fromFile) {
     const base = resolve(dirname(fromFile), specifier);
     const candidates = [];
@@ -189,7 +191,7 @@ function isBuiltin(specifier) {
 }
 function finding(context, rule, specifier, file, message, remediation) {
     return {
-        tool: "declarations",
+        tool: context.tool ?? "declarations",
         rule,
         package: context.packageRecord.name,
         file,
@@ -200,7 +202,7 @@ function finding(context, rule, specifier, file, message, remediation) {
         remediation,
     };
 }
-function classifyExternal(specifier, file, context) {
+export function classifyExternal(specifier, file, context) {
     const owner = packageNameOf(specifier);
     if (isBuiltin(specifier))
         return null;
@@ -258,7 +260,7 @@ function countDeclarationFiles(directory) {
     }
     return count;
 }
-function sortFindings(findings) {
+export function sortFindings(findings) {
     findings.sort((a, b) => {
         return ((a.package ?? "").localeCompare(b.package ?? "") ||
             (a.file ?? "").localeCompare(b.file ?? "") ||

package/dist/engines/packed-surface.d.ts

@@ -0,0 +1,22 @@
+import type { PackageRecord, Repository } from "../discover.js";
+import type { EngineResult, Finding } from "./types.js";
+interface TarPackage {
+    files: string[];
+    fileSet: Set<string>;
+    read(file: string): string;
+}
+declare function readTarball(tarballPath: string): TarPackage;
+/**
+ * Rules `ARCH-PACK-004` (unrewritten `workspace:`/`file:`/`link:` specifiers)
+ * and `ARCH-PACK-005` (exact sibling pins without a recorded ADR-033 exception),
+ * evaluated against the **packed** manifest.
+ *
+ * Exported so the `workspace:` branch of `ARCH-PACK-004` has direct test
+ * coverage: a real `pnpm pack` always rewrites `workspace:` protocols (and fails
+ * outright when it cannot resolve them), so a published tarball carrying a
+ * `workspace:` specifier can only come from a broken publish path, never from
+ * the packer this engine invokes.
+ */
+export declare function packedDependencySpecifierFindings(pkg: Pick<PackageRecord, "name" | "path">, manifest: Record<string, unknown>, siblingNames: ReadonlySet<string>): Finding[];
+export declare function runPackedSurface(repo: Repository): EngineResult;
+export { readTarball };

package/dist/engines/packed-surface.js

@@ -0,0 +1,654 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, matchesGlob, posix } from "node:path";
+import { classifyExternal, dependencySets, isDeclarationFile, parseDeclarationText, sortFindings, } from "./declaration-dependencies.js";
+import { discoverPublishablePackages } from "../discover.js";
+const SOURCE = "ADR-035";
+const DEPENDENCY_FIELDS = [
+    "dependencies",
+    "devDependencies",
+    "peerDependencies",
+    "optionalDependencies",
+];
+const EXACT_VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const IMPORT_CONDITIONS = new Set(["node", "import", "default"]);
+const REQUIRE_CONDITIONS = new Set(["node", "require", "default"]);
+class ToolUnavailableError extends Error {
+}
+class PackedConfigurationError extends Error {
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function run(command, args, cwd, timeout) {
+    const result = spawnSync(command, args, {
+        cwd,
+        encoding: "utf8",
+        env: process.env,
+        maxBuffer: 64 * 1024 * 1024,
+        timeout,
+    });
+    if (result.error) {
+        const code = result.error.code;
+        if (code === "ENOENT") {
+            throw new ToolUnavailableError(`Required tool "${command}" was not found on PATH`);
+        }
+        throw new PackedConfigurationError(`Failed to execute "${command} ${args.join(" ")}": ${result.error.message}`);
+    }
+    return {
+        status: result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+    };
+}
+function normalizeTarPath(raw) {
+    if (raw.startsWith("/") || raw.includes("\0")) {
+        throw new PackedConfigurationError(`Unsafe absolute path in tarball: ${raw}`);
+    }
+    const normalized = posix.normalize(raw).replace(/^\.\//, "");
+    if (normalized === ".." ||
+        normalized.startsWith("../") ||
+        normalized.includes("/../")) {
+        throw new PackedConfigurationError(`Unsafe path traversal entry in tarball: ${raw}`);
+    }
+    if (!normalized.startsWith("package/")) {
+        throw new PackedConfigurationError(`Tarball entry is not under the "package/" prefix: ${raw}`);
+    }
+    return normalized.slice("package/".length);
+}
+function readTarball(tarballPath) {
+    const listing = run("tar", ["-tzf", tarballPath], process.cwd(), 60_000);
+    if (listing.status !== 0) {
+        throw new PackedConfigurationError(`Cannot read tarball ${tarballPath}: ${listing.stderr.trim() || `tar exited ${listing.status}`}`);
+    }
+    const files = listing.stdout
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .map(normalizeTarPath)
+        .filter((file) => file.length > 0 && !file.endsWith("/"))
+        .sort();
+    const fileSet = new Set(files);
+    const cache = new Map();
+    return {
+        files,
+        fileSet,
+        read(file) {
+            const cached = cache.get(file);
+            if (cached !== undefined)
+                return cached;
+            if (!fileSet.has(file)) {
+                throw new PackedConfigurationError(`Tarball entry is missing: package/${file}`);
+            }
+            const extracted = run("tar", ["-xOf", tarballPath, `package/${file}`], process.cwd(), 60_000);
+            if (extracted.status !== 0) {
+                throw new PackedConfigurationError(`Cannot read package/${file} from ${tarballPath}: ${extracted.stderr.trim() || `tar exited ${extracted.status}`}`);
+            }
+            cache.set(file, extracted.stdout);
+            return extracted.stdout;
+        },
+    };
+}
+function readPackedManifest(tar) {
+    const parsed = JSON.parse(tar.read("package.json"));
+    if (!isRecord(parsed)) {
+        throw new PackedConfigurationError("Packed package.json is not a JSON object");
+    }
+    return parsed;
+}
+function packPackage(pkg, destination) {
+    const result = run("pnpm", ["pack", "--pack-destination", destination, "--silent"], pkg.path, 120_000);
+    if (result.status !== 0) {
+        throw new PackedConfigurationError(`pnpm pack failed for "${pkg.name}": ${result.stderr.trim() || `pnpm exited ${result.status}`}`);
+    }
+    const tarballs = readdirSync(destination)
+        .filter((file) => file.endsWith(".tgz"))
+        .sort();
+    if (tarballs.length !== 1) {
+        throw new PackedConfigurationError(`pnpm pack for "${pkg.name}" produced ${tarballs.length} tarball(s) in ${destination}`);
+    }
+    const tarball = tarballs[0];
+    if (!tarball) {
+        throw new PackedConfigurationError(`pnpm pack for "${pkg.name}" produced no tarball`);
+    }
+    return join(destination, tarball);
+}
+function normalizeTarget(value) {
+    const normalized = value.replace(/\\/g, "/").replace(/^\.\//, "");
+    return posix.normalize(normalized);
+}
+function isSafeRelativeTarget(target) {
+    return (target.length > 0 &&
+        !target.startsWith("/") &&
+        target !== ".." &&
+        !target.startsWith("../"));
+}
+function addTarget(targets, field, value, entry) {
+    const target = normalizeTarget(value);
+    if (!isSafeRelativeTarget(target))
+        return;
+    targets.push({ field, target, entry });
+}
+function walkExportValue(targets, field, entry, value) {
+    if (typeof value === "string") {
+        addTarget(targets, field, value, entry);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            walkExportValue(targets, field, entry, item);
+        return;
+    }
+    if (!isRecord(value))
+        return;
+    for (const [key, child] of Object.entries(value)) {
+        walkExportValue(targets, field, key.startsWith(".") ? key : entry, child);
+    }
+}
+function collectManifestTargets(manifest) {
+    const targets = [];
+    const exportsField = manifest["exports"];
+    if (typeof exportsField === "string") {
+        addTarget(targets, "exports", exportsField, ".");
+    }
+    else if (isRecord(exportsField)) {
+        const hasSubpaths = Object.keys(exportsField).some((key) => key.startsWith("."));
+        if (hasSubpaths) {
+            for (const [key, value] of Object.entries(exportsField)) {
+                if (key.startsWith(".")) {
+                    walkExportValue(targets, `exports["${key}"]`, key, value);
+                }
+            }
+        }
+        else {
+            walkExportValue(targets, "exports", ".", exportsField);
+        }
+    }
+    for (const field of ["main", "module", "types"]) {
+        const value = manifest[field];
+        if (typeof value === "string")
+            addTarget(targets, field, value, ".");
+    }
+    const bin = manifest["bin"];
+    if (typeof bin === "string") {
+        addTarget(targets, "bin", bin, null);
+    }
+    else if (isRecord(bin)) {
+        for (const value of Object.values(bin)) {
+            if (typeof value === "string")
+                addTarget(targets, "bin", value, null);
+        }
+    }
+    const typesVersions = 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}`;
+                if (typeof value === "string") {
+                    addTarget(targets, "typesVersions", value, entry);
+                }
+                else if (Array.isArray(value)) {
+                    for (const item of value) {
+                        if (typeof item === "string") {
+                            addTarget(targets, "typesVersions", item, entry);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return targets;
+}
+function targetFiles(tar, target) {
+    if (target.includes("*")) {
+        return tar.files.filter((file) => matchesGlob(file, target));
+    }
+    return tar.fileSet.has(target) ? [target] : [];
+}
+function relativeCandidates(specifier, fromFile) {
+    const base = posix.normalize(posix.join(posix.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`, posix.join(base, "index.d.ts"));
+    return candidates;
+}
+/**
+ * A recorded ARCH-PACK-005 exception (ADR-033 §4): a line in the package's
+ * `docs/conventions.md` that names the sibling and records the exception or
+ * its justification. ADR-033 does not prescribe a machine format, so the check
+ * stays deliberately permissive: the sibling must be named on the same line as
+ * the exception or justification wording.
+ */
+function exactPinException(packagePath, sibling) {
+    const convention = join(packagePath, "docs", "conventions.md");
+    if (!existsSync(convention))
+        return false;
+    try {
+        return readFileSync(convention, "utf8")
+            .split(/\r?\n/)
+            .some((line) => line.includes(sibling) &&
+            /exception|justification/i.test(line) &&
+            !/\bno\s+(?:recorded\s+)?exceptions?\b/i.test(line));
+    }
+    catch {
+        return false;
+    }
+}
+function finding(pkg, rule, message, remediation, options = {}) {
+    return {
+        tool: "packed-surface",
+        rule,
+        package: pkg,
+        file: options.file,
+        keyword: options.keyword,
+        severity: "error",
+        source: SOURCE,
+        message,
+        remediation,
+    };
+}
+function dedupeFindings(findings) {
+    const seen = new Set();
+    const unique = [];
+    for (const item of findings) {
+        const key = [
+            item.package ?? "",
+            item.rule,
+            item.file ?? "",
+            item.keyword ?? "",
+            item.message,
+        ].join("\0");
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        unique.push(item);
+    }
+    return unique;
+}
+function resolveRuntimeTarget(value, conditions) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const resolved = resolveRuntimeTarget(item, conditions);
+            if (resolved)
+                return resolved;
+        }
+        return null;
+    }
+    if (!isRecord(value))
+        return null;
+    for (const [key, child] of Object.entries(value)) {
+        if (key === "types")
+            continue;
+        if (key !== "default" && !conditions.has(key))
+            continue;
+        const resolved = resolveRuntimeTarget(child, conditions);
+        if (resolved)
+            return resolved;
+    }
+    return null;
+}
+function runtimeExports(manifest) {
+    const exportsField = manifest["exports"];
+    if (typeof exportsField === "string") {
+        return [{ key: ".", value: exportsField }];
+    }
+    if (!isRecord(exportsField))
+        return [];
+    const hasSubpaths = Object.keys(exportsField).some((key) => key.startsWith("."));
+    if (!hasSubpaths)
+        return [{ key: ".", value: exportsField }];
+    return Object.entries(exportsField)
+        .filter(([key]) => key.startsWith("."))
+        .map(([key, value]) => ({ key, value }));
+}
+/**
+ * Rules `ARCH-PACK-004` (unrewritten `workspace:`/`file:`/`link:` specifiers)
+ * and `ARCH-PACK-005` (exact sibling pins without a recorded ADR-033 exception),
+ * evaluated against the **packed** manifest.
+ *
+ * Exported so the `workspace:` branch of `ARCH-PACK-004` has direct test
+ * coverage: a real `pnpm pack` always rewrites `workspace:` protocols (and fails
+ * outright when it cannot resolve them), so a published tarball carrying a
+ * `workspace:` specifier can only come from a broken publish path, never from
+ * the packer this engine invokes.
+ */
+export function packedDependencySpecifierFindings(pkg, manifest, siblingNames) {
+    const findings = [];
+    for (const field of DEPENDENCY_FIELDS) {
+        const values = manifest[field];
+        if (!isRecord(values))
+            continue;
+        for (const [name, value] of Object.entries(values)) {
+            if (typeof value !== "string")
+                continue;
+            if (!/^(?:workspace:|file:|link:)/.test(value))
+                continue;
+            findings.push(finding(pkg.name, "ARCH-PACK-004", `Package "${pkg.name}" ships "${name}": "${value}" in ${field}; published manifests must not contain workspace:, file: or link: specifiers`, "Rewrite the dependency as a published semver range.", { file: "package.json", keyword: name }));
+        }
+    }
+    for (const field of ["dependencies", "peerDependencies"]) {
+        const values = manifest[field];
+        if (!isRecord(values))
+            continue;
+        for (const [name, value] of Object.entries(values)) {
+            if (typeof value !== "string" ||
+                !siblingNames.has(name) ||
+                !EXACT_VERSION.test(value) ||
+                exactPinException(pkg.path, name)) {
+                continue;
+            }
+            findings.push(finding(pkg.name, "ARCH-PACK-005", `Package "${pkg.name}" pins sibling "${name}" to exact version "${value}" in ${field} without a recorded exception in docs/conventions.md`, `Use a caret range (workspace:^ publishes as ^${value}) or record the exception in docs/conventions.md.`, { file: "package.json", keyword: name }));
+        }
+    }
+    return findings;
+}
+function checkPackedPackage(packed, packages, siblingNames) {
+    const findings = [];
+    const pkg = packed.packageRecord;
+    const manifest = packed.manifest;
+    const targets = collectManifestTargets(manifest);
+    const entries = new Map();
+    let externalReferences = 0;
+    for (const target of targets) {
+        const matches = targetFiles(packed.tar, target.target);
+        if (matches.length === 0) {
+            findings.push(finding(pkg.name, "ARCH-PACK-001", `Package "${pkg.name}" declares ${target.field} target "${target.target}" but the tarball does not contain it`, "Include the target in the package files field, or correct the manifest target.", { file: target.target, keyword: target.target }));
+            continue;
+        }
+        if (target.entry === null)
+            continue;
+        for (const file of matches) {
+            if (!isDeclarationFile(file))
+                continue;
+            const keys = entries.get(file) ?? new Set();
+            keys.add(target.entry);
+            entries.set(file, keys);
+        }
+    }
+    const parsed = new Map();
+    const entryKeysByFile = new Map();
+    const unresolved = new Map();
+    const queue = [];
+    for (const [file, keys] of [...entries.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        for (const entry of [...keys].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 = parseDeclarationText(item.file, packed.tar.read(item.file));
+            parsed.set(item.file, declaration);
+        }
+        for (const specifier of declaration.relative) {
+            const resolved = relativeCandidates(specifier, item.file).find((file) => packed.tar.fileSet.has(file));
+            if (resolved) {
+                queue.push({ file: resolved, entry: item.entry });
+            }
+            else {
+                const key = `${item.file}\0${specifier}`;
+                const entryKeys = unresolved.get(key) ?? new Set();
+                entryKeys.add(item.entry);
+                unresolved.set(key, entryKeys);
+            }
+        }
+    }
+    for (const [key, entryKeys] of unresolved) {
+        const [file, specifier] = key.split("\0");
+        if (!file || !specifier)
+            continue;
+        const entry = [...entryKeys].sort()[0] ?? "?";
+        findings.push(finding(pkg.name, "ARCH-PACK-002", `Package "${pkg.name}" publishes entry "${entry}" whose declaration "${file}" references "${specifier}", but the resolved declaration is absent from the tarball`, "Include the emitted declaration in the package files field, or fix the relative reference.", { file, keyword: specifier }));
+    }
+    if (entryKeysByFile.size === 0 && targets.some((target) => target.entry !== null)) {
+        findings.push(finding(pkg.name, "ARCH-PACK-002", `Package "${pkg.name}" declares declaration entry points but the tarball contains no reachable declaration file`, "Include the emitted declarations in the package files field."));
+    }
+    const sets = dependencySets(manifest);
+    const packedPackages = new Map(packages);
+    for (const [file, entryKeys] of [...entryKeysByFile.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        const declaration = parsed.get(file);
+        if (!declaration)
+            continue;
+        const entry = [...entryKeys].sort()[0] ?? "?";
+        const context = {
+            packageRecord: pkg,
+            sets,
+            packages: packedPackages,
+            rootReached: entryKeys.has("."),
+            entry,
+            tool: "packed-surface",
+        };
+        for (const specifier of [...declaration.external].sort()) {
+            externalReferences += 1;
+            const result = classifyExternal(specifier, file, context);
+            if (result)
+                findings.push(result);
+        }
+    }
+    findings.push(...packedDependencySpecifierFindings({ name: pkg.name, path: packed.workspacePath }, manifest, siblingNames));
+    const cjs = packed.tar.files.filter((file) => file === "dist/cjs" || file.startsWith("dist/cjs/"));
+    if (cjs.length > 0) {
+        findings.push(finding(pkg.name, "ARCH-PACK-006", `Package "${pkg.name}" ships ${cjs.length} file(s) under dist/cjs/; Comity publishes a single ESM distribution`, "Remove the CommonJS build from the package outputs.", { file: "dist/cjs", keyword: "dist/cjs" }));
+    }
+    for (const entry of runtimeExports(manifest)) {
+        const importTarget = resolveRuntimeTarget(entry.value, IMPORT_CONDITIONS);
+        const requireTarget = resolveRuntimeTarget(entry.value, REQUIRE_CONDITIONS);
+        if (!importTarget || !requireTarget) {
+            findings.push(finding(pkg.name, "ARCH-PACK-006", `Package "${pkg.name}" exports "${entry.key}" but does not resolve for both import and require consumers`, "Add a default (or matching import/require) condition that resolves to the ESM artifact.", { file: "package.json", keyword: entry.key }));
+            continue;
+        }
+        if (importTarget !== requireTarget) {
+            findings.push(finding(pkg.name, "ARCH-PACK-006", `Package "${pkg.name}" exports "${entry.key}" with import "${importTarget}" and require "${requireTarget}"; both must resolve to the same ESM artifact`, "Point import and require at the same ESM file.", { file: "package.json", keyword: entry.key }));
+            continue;
+        }
+        if (/\.(?:cjs|cts)$/.test(importTarget)) {
+            findings.push(finding(pkg.name, "ARCH-PACK-006", `Package "${pkg.name}" exports "${entry.key}" to a CommonJS artifact "${importTarget}"`, "Publish the ESM artifact for this export.", { file: importTarget, keyword: entry.key }));
+        }
+    }
+    return {
+        findings: dedupeFindings(findings),
+        declarationFiles: entryKeysByFile.size,
+        externalReferences,
+    };
+}
+export function runPackedSurface(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: "packed-surface",
+                reason: `No package directory with a readable package.json was found under root(s): ${discovery.roots.join(", ")}.${defaultNote}${excludedNote}`,
+            };
+        }
+        return {
+            executed: false,
+            exitCode: null,
+            passed: false,
+            findings: [],
+            duration: Date.now() - start,
+            status: "NOT-APPLICABLE",
+            tool: "packed-surface",
+            reason: `All discovered packages are private: ${discovery.excluded
+                .filter((pkg) => pkg.reason === "private package")
+                .map((pkg) => pkg.name ?? pkg.path)
+                .join(", ")}.`,
+        };
+    }
+    const tempRoot = mkdtempSync(join(tmpdir(), "comity-packed-surface-"));
+    const packed = [];
+    const configurationErrors = [];
+    try {
+        for (const [index, pkg] of discovery.publishable.entries()) {
+            const destination = join(tempRoot, `pack-${index}`);
+            mkdirSync(destination, { recursive: true });
+            try {
+                const tarballPath = packPackage(pkg, destination);
+                const tar = readTarball(tarballPath);
+                const manifest = readPackedManifest(tar);
+                packed.push({
+                    packageRecord: { ...pkg, manifest },
+                    workspacePath: pkg.path,
+                    tarballPath,
+                    tar,
+                    manifest,
+                });
+            }
+            catch (error) {
+                if (error instanceof ToolUnavailableError)
+                    throw error;
+                configurationErrors.push(error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
+    catch (error) {
+        rmSync(tempRoot, { recursive: true, force: true });
+        if (error instanceof ToolUnavailableError) {
+            return {
+                executed: false,
+                exitCode: null,
+                passed: false,
+                findings: [],
+                duration: Date.now() - start,
+                status: "TOOL-UNAVAILABLE",
+                tool: "packed-surface",
+                reason: error.message,
+            };
+        }
+        return {
+            executed: false,
+            exitCode: null,
+            passed: false,
+            findings: [],
+            duration: Date.now() - start,
+            status: "CONFIGURATION-ERROR",
+            tool: "packed-surface",
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+    try {
+        const siblingNames = new Set(discovery.allPackages.map((pkg) => pkg.name));
+        const packedByName = new Map(packed.map((item) => [item.packageRecord.name, item]));
+        const packages = new Map();
+        for (const pkg of discovery.allPackages) {
+            const item = packedByName.get(pkg.name);
+            packages.set(pkg.name, item
+                ? { ...pkg, manifest: item.manifest }
+                : pkg);
+        }
+        const findings = [];
+        let declarationFiles = 0;
+        let externalReferences = 0;
+        for (const item of packed) {
+            try {
+                const result = checkPackedPackage(item, packages, siblingNames);
+                findings.push(...result.findings);
+                declarationFiles += result.declarationFiles;
+                externalReferences += result.externalReferences;
+            }
+            catch (error) {
+                if (error instanceof ToolUnavailableError)
+                    throw error;
+                configurationErrors.push(`${item.packageRecord.name}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        sortFindings(findings);
+        if (configurationErrors.length > 0) {
+            return {
+                executed: false,
+                exitCode: null,
+                passed: false,
+                findings,
+                duration: Date.now() - start,
+                status: "CONFIGURATION-ERROR",
+                tool: "packed-surface",
+                reason: configurationErrors.join("; "),
+            };
+        }
+        const excludedNotes = discovery.excluded.map((pkg) => `${pkg.name ?? pkg.path} (${pkg.reason})`);
+        const notes = [
+            `${packed.length} publishable package(s)`,
+            `${declarationFiles} reachable declaration file(s)`,
+            `${externalReferences} external reference(s)`,
+            "external references evaluated against the packed manifests (ARCH-PACK-003 umbrella; violations are reported as ARCH-DECL-DEP-001…005)",
+        ];
+        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: "packed-surface",
+            reason: notes.join("; "),
+        };
+    }
+    catch (error) {
+        if (error instanceof ToolUnavailableError) {
+            return {
+                executed: false,
+                exitCode: null,
+                passed: false,
+                findings: [],
+                duration: Date.now() - start,
+                status: "TOOL-UNAVAILABLE",
+                tool: "packed-surface",
+                reason: error.message,
+            };
+        }
+        return {
+            executed: false,
+            exitCode: null,
+            passed: false,
+            findings: [],
+            duration: Date.now() - start,
+            status: "CONFIGURATION-ERROR",
+            tool: "packed-surface",
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+    finally {
+        rmSync(tempRoot, { recursive: true, force: true });
+    }
+}
+export { readTarball };

package/dist/format.d.ts

@@ -23,6 +23,8 @@ export interface FormatInput {
         adapterPeers: CategoryResult;
         /** Published declaration dependency validation results */
         declarations: CategoryResult;
+        /** Packed-surface tarball validation results */
+        packedSurface: CategoryResult;
     };
 }
 /**

package/dist/format.js

@@ -7,6 +7,7 @@ const CATEGORY_LABELS = {
     semgrep: "Structural patterns (Semgrep)",
     adapterPeers: "Adapter peers",
     declarations: "Declarations",
+    packedSurface: "Packed surface",
 };
 function statusBadge(cat) {
     switch (cat.status) {

package/dist/run.d.ts

@@ -47,6 +47,8 @@ export interface RunResult {
         adapterPeers: CategoryResult;
         /** Published declaration dependency validation results */
         declarations: CategoryResult;
+        /** Packed-surface tarball validation results */
+        packedSurface: CategoryResult;
     };
 }
 /**

package/dist/run.js

@@ -5,6 +5,7 @@ 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 { runPackedSurface } from "./engines/packed-surface.js";
 import { runSchema } from "./engines/schema.js";
 import { runSemgrep } from "./engines/semgrep.js";
 import { ExitCode } from "./exit-codes.js";
@@ -125,6 +126,15 @@ export async function runValidation(options) {
     else {
         declarationResult = emptyEngineResult("declarations engine skipped");
     }
+    let packedSurfaceResult;
+    if (only === "packed-surface") {
+        packedSurfaceResult = runPackedSurface(repo);
+    }
+    else {
+        packedSurfaceResult = emptyEngineResult(only
+            ? "packed-surface engine skipped"
+            : "packed-surface engine requires explicit --only=packed-surface");
+    }
     const violations = [];
     for (const r of [
         schemaResult,
@@ -133,6 +143,7 @@ export async function runValidation(options) {
         semgrepResult,
         adapterResult,
         declarationResult,
+        packedSurfaceResult,
     ]) {
         if (Array.isArray(r.findings)) {
             violations.push(...r.findings);
@@ -144,6 +155,7 @@ export async function runValidation(options) {
         semgrepResult,
         adapterResult,
         declarationResult,
+        packedSurfaceResult,
     ];
     const allPassed = allExecuted.every(categoryIsAcceptable) &&
         categoryIsAcceptable(metaResult) &&
@@ -160,6 +172,7 @@ export async function runValidation(options) {
             semgrep: categoryOf(semgrepResult),
             adapterPeers: categoryOf(adapterResult),
             declarations: categoryOf(declarationResult),
+            packedSurface: categoryOf(packedSurfaceResult),
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comity-dev/validate",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Thin orchestrator over Comity shared validation tooling. Development tooling.",
   "type": "module",
   "private": false,