validate-pins.ts

/**
 * Pin Validator (showcase-internal)
 *
 * Enforces showcase-internal pin discipline. The historical mode that
 * compared `showcase/integrations/<slug>` against the external
 * `examples/integrations/<source>` Dojo has been REMOVED: showcase and
 * the external Dojo are intentionally divergent products on independent
 * release cadences and a cross-product pin-parity gate was backwards.
 *
 * For each showcase package at `showcase/integrations/<slug>/`:
 *   1. Read its dependency files (`package.json`, `requirements.txt`,
 *      `pyproject.toml`).
 *   2. Every `@copilotkit/*` dep must pin to the canonical version
 *      declared in `showcase/scripts/showcase-canonical-pins.json`
 *      (`canonicalCopilotKitVersion`), OR to the per-slug per-dep value
 *      listed under `overrides[slug]`.
 *   3. Every other framework / SDK dep (the FRAMEWORK_PATTERNS set —
 *      mastra, langchain, langgraph, crewai, agno, llama-index, etc.)
 *      must be an EXACT pin (no `^`/`~`/`>=`/`latest`/`next`/dist-tags/
 *      `workspace:*`/URLs).
 *   4. Emit `[FAIL] <slug>: <dep> ...` for each violation.
 *
 * Definition of "exact pin":
 *   - npm: bare semver (`1.2.3`, `1.2.3-beta.1`). NO `^`, `~`, `>=`, `*`,
 *          `latest`, `next`, `workspace:*`, URLs, or git refs.
 *   - Python: `==<version>`. NO `>=`, `~=`, `*`, or unpinned names.
 *
 * Usage:
 *   npx tsx showcase/scripts/validate-pins.ts
 *
 * Exit codes:
 *   0 — no FAIL violations (WARN/SKIP are non-fatal)
 *   1 — one or more FAIL violations (pin drift detected)
 *   2 — internal error (crash, unexpected exception). Distinct from 1 so
 *       CI callers can distinguish "pin drift" from "validator broken".
 *       Note: validate-parity.ts uses a different exit-code taxonomy
 *       (2=invalid-input, 3=unreadable, 4=internal); the tools are
 *       intentionally not aligned on code 2.
 *   3 — unreadable input (e.g. VALIDATE_PINS_REPO_ROOT points at a
 *       non-directory or a path the process cannot access). Distinct from
 *       2 so CI callers can route permissions/misconfig alerts separately
 *       from true crashes.
 *
 * Output routing:
 *   - [OK] and [SKIP] lines go to stdout.
 *   - [FAIL] and [WARN] lines go to stderr (per Unix convention).
 *
 * --- NOTE: SLUG_MAP / examples helpers ---
 *
 * The slug-map tables (`SLUG_MAP`, `FALLBACK_MAP`, `BORN_IN_SHOWCASE`)
 * and the `resolveExampleDir` / `collectDojoDeps` helpers are NO LONGER
 * USED by `validateAll` — the new invariant is showcase-internal. They
 * are still EXPORTED so other consumers (audit.ts provenance, tests,
 * future tooling that wants to peek at the live external Dojo) can
 * import them. Removing those exports is out of scope for Phase 1.
 */

import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";
import { BORN_IN_SHOWCASE, FALLBACK_MAP, SLUG_MAP } from "./lib/slug-map.js";

// SLUG_MAP / FALLBACK_MAP / BORN_IN_SHOWCASE are the single source of
// truth shared by audit.ts, validate-parity.ts, and this file. Re-exported
// at the bottom of this file so tests importing from "../validate-pins.js"
// see the same frozen tables.

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// Exit-code constants. See the module docstring for the full taxonomy.
// `as const` narrows each to its literal numeric type; `PinsExitCode` is
// the closed union so callers (and `process.exitCode` assignments in
// this file) cannot accidentally drift to an unrelated number. Adding
// a new exit code is a deliberate edit to both the constant and the
// union — a pure `const X = 4` cannot participate in the union.
const EXIT_OK = 0 as const;
const EXIT_DRIFT = 1 as const;
const EXIT_INTERNAL = 2 as const;
const EXIT_UNREADABLE = 3 as const;
type PinsExitCode =
  | typeof EXIT_OK
  | typeof EXIT_DRIFT
  | typeof EXIT_INTERNAL
  | typeof EXIT_UNREADABLE;

/**
 * Thrown when the repo-root input is present but unreadable or
 * structurally wrong (e.g. points at a file, EACCES, ENOTDIR). The
 * top-level catch uses `instanceof` to route these to EXIT_UNREADABLE
 * instead of EXIT_INTERNAL so CI callers can distinguish a permissions
 * misconfig from a true validator crash.
 */
class UnreadableInputError extends Error {
  /**
   * Optionally carries the partial report built up to the point the
   * infra error was observed. The top-level catch uses this to print
   * the FAIL/WARN/SKIP lines for slugs processed before the error so
   * operators don't lose diagnostic output when a single slug has an
   * infra problem mid-run. undefined for infra errors raised before
   * the slug loop started (e.g. bad VALIDATE_PINS_REPO_ROOT, missing
   * packages dir) where no report exists yet.
   */
  readonly partialReport?: Report;
  constructor(message: string, partialReport?: Report) {
    super(message);
    this.name = "UnreadableInputError";
    this.partialReport = partialReport;
  }
}

// REPO_ROOT resolution allows tests to override via env var. The override
// must be an absolute path pointing at an existing directory; a relative
// or non-existent override silently yielding an empty scan would turn a
// misconfiguration into a false green.
//
// Implementation note: `fs.existsSync` collapses ENOENT (does not
// exist) with EACCES (exists but unreadable by the current process)
// into a single false result, which produces a misleading "does not
// exist" error when the real problem is a permissions gap. Use
// `fs.statSync` with errno inspection so the message names the right
// failure mode.
function computeRepoRoot(): string {
  const override = process.env.VALIDATE_PINS_REPO_ROOT;
  if (override) {
    if (!path.isAbsolute(override)) {
      throw new Error(
        `VALIDATE_PINS_REPO_ROOT must be an absolute path; got: ${override}`,
      );
    }
    let st: fs.Stats;
    try {
      st = fs.statSync(override);
    } catch (e) {
      const err = e as NodeJS.ErrnoException;
      if (err && err.code === "ENOENT") {
        // ENOENT on the override is a bad-input/configuration error,
        // not a validator crash — route to EXIT_UNREADABLE (3) so CI
        // callers can distinguish misconfig from true internal errors.
        throw new UnreadableInputError(
          `VALIDATE_PINS_REPO_ROOT does not exist on disk: ${override}`,
        );
      }
      if (err && err.code === "EACCES") {
        throw new UnreadableInputError(
          `VALIDATE_PINS_REPO_ROOT exists but is not readable (permission denied): ${override}`,
        );
      }
      if (err && err.code === "ENOTDIR") {
        throw new UnreadableInputError(
          `VALIDATE_PINS_REPO_ROOT path component is not a directory: ${override}`,
        );
      }
      // Surface the underlying error message so the caller sees the
      // actual failure rather than a generic wrapper. Any stat failure
      // on the override path is an infra-class problem (the caller
      // configured a path we can't access), so route through
      // UnreadableInputError → EXIT_UNREADABLE (3) instead of letting
      // a plain Error misroute to EXIT_INTERNAL (2).
      const msg = err && err.message ? err.message : String(e);
      throw new UnreadableInputError(
        `VALIDATE_PINS_REPO_ROOT stat failed: ${override}: ${msg}`,
      );
    }
    // Override must be a directory — a file override would let the
    // rest of the validator run with a bogus REPO_ROOT and produce
    // misleading "nothing found" output rather than an immediate error.
    if (!st.isDirectory()) {
      throw new UnreadableInputError(
        `VALIDATE_PINS_REPO_ROOT is not a directory: ${override}`,
      );
    }
    return override;
  }
  return path.resolve(__dirname, "..", "..");
}

function paths() {
  const repoRoot = computeRepoRoot();
  return {
    REPO_ROOT: repoRoot,
    // EXAMPLES_DIR is retained for the legacy `resolveExampleDir` /
    // `collectDojoDeps` helpers (still exported for non-validateAll
    // consumers). validateAll no longer reads it.
    EXAMPLES_DIR: path.join(repoRoot, "examples", "integrations"),
    PACKAGES_DIR: path.join(repoRoot, "showcase", "integrations"),
    CANONICAL_PINS_FILE: path.join(
      repoRoot,
      "showcase",
      "scripts",
      "showcase-canonical-pins.json",
    ),
  };
}

// ---------------------------------------------------------------------------
// Canonical pins config
// ---------------------------------------------------------------------------

/**
 * Schema for `showcase/scripts/showcase-canonical-pins.json`:
 *   {
 *     "canonicalCopilotKitVersion": "1.59.2",
 *     "overrides": {
 *       "<slug>": { "<dep-name>": "<allowed-spec>" }
 *     }
 *   }
 *
 * `canonicalCopilotKitVersion` is the canonical pin for every
 * `@copilotkit/*` dep across all showcase integrations. `overrides[slug]`
 * is a per-slug map of dep-name → allowed verbatim spec used when a
 * specific integration legitimately deviates (e.g. a `pkg.pr.new` URL
 * during a runtime upgrade, or a legacy stable for a harness fixture).
 */
export interface CanonicalPins {
  canonicalCopilotKitVersion: string;
  overrides: Readonly<Record<string, Readonly<Record<string, string>>>>;
}

class CanonicalPinsError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "CanonicalPinsError";
  }
}

export function loadCanonicalPins(file: string): CanonicalPins {
  let raw: string;
  try {
    raw = fs.readFileSync(file, "utf-8");
  } catch (e) {
    const err = e as NodeJS.ErrnoException;
    if (err && err.code === "ENOENT") {
      throw new UnreadableInputError(
        `canonical pins file not found at ${file}`,
      );
    }
    const msg = err && err.message ? err.message : String(e);
    throw new UnreadableInputError(
      `canonical pins file read failed (${err?.code ?? "unknown"}): ${file}: ${msg}`,
    );
  }
  let parsed: unknown;
  try {
    parsed = JSON.parse(raw);
  } catch (e) {
    const msg = e instanceof Error ? e.message : String(e);
    throw new CanonicalPinsError(`${file}: JSON syntax error: ${msg}`);
  }
  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
    throw new CanonicalPinsError(`${file}: expected top-level object`);
  }
  const obj = parsed as Record<string, unknown>;
  const ver = obj.canonicalCopilotKitVersion;
  if (typeof ver !== "string" || ver.length === 0) {
    throw new CanonicalPinsError(
      `${file}: 'canonicalCopilotKitVersion' must be a non-empty string`,
    );
  }
  if (!isExactSpec(ver)) {
    throw new CanonicalPinsError(
      `${file}: 'canonicalCopilotKitVersion' must itself be an exact pin (got ${JSON.stringify(ver)})`,
    );
  }
  const ovRaw = obj.overrides;
  const overrides: Record<string, Record<string, string>> = {};
  if (ovRaw !== undefined) {
    if (typeof ovRaw !== "object" || ovRaw === null || Array.isArray(ovRaw)) {
      throw new CanonicalPinsError(`${file}: 'overrides' must be an object`);
    }
    for (const [slug, depsRaw] of Object.entries(ovRaw)) {
      if (
        typeof depsRaw !== "object" ||
        depsRaw === null ||
        Array.isArray(depsRaw)
      ) {
        throw new CanonicalPinsError(
          `${file}: 'overrides.${slug}' must be an object`,
        );
      }
      const inner: Record<string, string> = {};
      for (const [dep, spec] of Object.entries(depsRaw)) {
        if (typeof spec !== "string" || spec.length === 0) {
          throw new CanonicalPinsError(
            `${file}: 'overrides.${slug}.${dep}' must be a non-empty string`,
          );
        }
        inner[dep] = spec;
      }
      overrides[slug] = Object.freeze(inner);
    }
  }
  return Object.freeze({
    canonicalCopilotKitVersion: ver,
    overrides: Object.freeze(overrides),
  });
}

// ---------------------------------------------------------------------------
// Slug resolution
// ---------------------------------------------------------------------------

// Reverse of SLUG_MAP: showcase slug → examples dir name(s).
// Precomputed at module load so each slug lookup is O(1) rather than
// a linear scan of SLUG_MAP. Frozen so runtime mutation attempts throw
// — the tables are meant to be effectively constant.
const REVERSE_MAP: Readonly<Record<string, readonly string[]>> = (() => {
  const reverse: Record<string, string[]> = {};
  for (const [example, slug] of SLUG_MAP) {
    if (!reverse[slug]) reverse[slug] = [];
    reverse[slug].push(example);
  }
  // Freeze inner arrays first, then outer record.
  for (const k of Object.keys(reverse)) Object.freeze(reverse[k]);
  return Object.freeze(reverse);
})();

export interface ResolveResult {
  exampleDir: string | null;
  // If a FALLBACK_MAP entry existed but pointed to a missing dir, the
  // caller should emit a distinct WARN with this path for diagnostics.
  missingFallbackTarget?: string;
}

function resolveExampleDirDetailed(
  showcaseSlug: string,
  pathsOverride?: ReturnType<typeof paths>,
): ResolveResult {
  if (BORN_IN_SHOWCASE.has(showcaseSlug)) return { exampleDir: null };

  // Accept an optional pre-computed `paths()` so validateAll can
  // compute it ONCE per run rather than re-validating
  // VALIDATE_PINS_REPO_ROOT per slug. Direct callers (tests, ad-hoc
  // use) may omit it and pay the per-call cost.
  const { EXAMPLES_DIR, REPO_ROOT } = pathsOverride ?? paths();

  // Strategy: explicit-fallback > reverse-SLUG_MAP > direct-name-match.
  // Each strategy can "fall through" if its candidate dir does not
  // exist on disk, so that a stale FALLBACK_MAP entry doesn't block a
  // later strategy from resolving correctly.
  //
  // Use `fs.statSync` + catch-ENOENT rather than `fs.existsSync` so
  // that a permission error (EACCES) does not silently collapse to the
  // "not present" branch. EACCES means "there is something there, but
  // this process can't read it" — treating it as "absent" hides real
  // misconfiguration. Other errors re-throw so they're surfaced at the
  // top level rather than quietly skipped.
  const existsAsDir = (p: string): boolean => {
    try {
      return fs.statSync(p).isDirectory();
    } catch (e) {
      const err = e as NodeJS.ErrnoException;
      if (err && err.code === "ENOENT") return false;
      // EACCES / ENOTDIR / EIO / ELOOP / etc. mean "there is something
      // at this path, but we can't read it". Route through
      // UnreadableInputError so the top-level catch maps this to
      // EXIT_UNREADABLE (3) — a permissions/infra misconfig — rather
      // than EXIT_INTERNAL (2) which signals a validator crash.
      const code = err && err.code ? err.code : "unknown";
      const msg = err && err.message ? err.message : String(e);
      throw new UnreadableInputError(
        `cannot stat candidate example dir (${code}): ${p}: ${msg}`,
      );
    }
  };

  // Strategy 1 — explicit fallback (documents SLUG_MAP staleness).
  const fallback = FALLBACK_MAP[showcaseSlug];
  let missingFallbackTarget: string | undefined;
  if (fallback) {
    const dir = path.join(EXAMPLES_DIR, fallback);
    if (existsAsDir(dir)) return { exampleDir: dir };
    // Display relative to REPO_ROOT so the WARN line reads
    // `examples/integrations/<name>` rather than the ambiguous
    // `integrations/<name>` (which hides where the missing dir is).
    missingFallbackTarget = path.relative(REPO_ROOT, dir);
  }

  // Strategy 2 — reverse-map lookup from SLUG_MAP.
  const candidates = REVERSE_MAP[showcaseSlug] || [];
  for (const cand of candidates) {
    const dir = path.join(EXAMPLES_DIR, cand);
    if (existsAsDir(dir)) return { exampleDir: dir, missingFallbackTarget };
  }

  // Strategy 3 — direct name match (common case: showcase slug ===
  // examples dir name).
  const direct = path.join(EXAMPLES_DIR, showcaseSlug);
  if (existsAsDir(direct)) return { exampleDir: direct, missingFallbackTarget };

  return { exampleDir: null, missingFallbackTarget };
}

function resolveExampleDir(showcaseSlug: string): string | null {
  return resolveExampleDirDetailed(showcaseSlug).exampleDir;
}

// ---------------------------------------------------------------------------
// Dependency extraction
// ---------------------------------------------------------------------------

// Heuristic: what counts as an agent framework / SDK that must be pinned.
// Applied as regex match (mostly anchored) against dependency NAMES only;
// versions are compared via exact string match per the
// INTEGRATION-CHECKLIST rule.
//
// Expected match set (non-exhaustive sanity list, with concrete examples
// rather than glob-like notation): @copilotkit/<anything>, copilotkit,
// @ag-ui/<anything>, ag-ui-<anything>, ag_ui_<anything>,
// @langchain/<anything>, langchain, langchain-<anything>, langgraph,
// langgraph-<anything>, langsmith, @mastra/<anything>, mastra, crewai,
// crewai-<anything>, pydantic-ai, pydantic-ai-<anything>, agno,
// llama-index, llama-index-<anything>, llama_index, llama_index_<anything>,
// llamaindex, google-adk, google-genai, strands-agents,
// strands-agents-<anything>, agent-framework, agent-framework-<anything>,
// @ai-sdk/<anything>, ai, @hashbrownai/<anything>, @anthropic-ai/<anything>,
// anthropic, openai, ag2, langroid, spring-ai, spring-ai-<anything>, and
// Spring's Maven coordinate form `org.springframework.ai:<artifact>` which
// appears in Java manifests as a colon-delimited group:artifact string.
const FRAMEWORK_PATTERNS: Array<RegExp> = [
  // CopilotKit SDK
  /^@copilotkit\//,
  /^copilotkit$/,
  // AG-UI
  /^@ag-ui\//,
  /^ag-ui[-_]/,
  /^ag_ui[-_]/,
  // LangChain / LangGraph
  /^@langchain\//,
  /^langchain$/,
  /^langchain-/,
  /^langgraph$/,
  /^langgraph-/,
  /^langgraph_/,
  /^langsmith$/,
  // Mastra
  /^@mastra\//,
  /^mastra$/,
  // CrewAI
  /^crewai$/,
  /^crewai-/,
  // Pydantic AI
  /^pydantic-ai$/,
  /^pydantic-ai-/,
  // Agno
  /^agno$/,
  // LlamaIndex (dash and underscore forms)
  /^llama-index$/,
  /^llama-index-/,
  /^llama_index$/,
  /^llama_index_/,
  /^llamaindex$/,
  // Google ADK / GenAI
  /^google-adk$/,
  /^google-genai$/,
  // Strands
  /^strands-agents$/,
  /^strands-agents-/,
  // Microsoft Agent Framework
  /^agent-framework$/,
  /^agent-framework-/,
  // AI SDK (Vercel)
  /^@ai-sdk\//,
  /^ai$/,
  // Hashbrown / A2UI renderers travel with CopilotKit
  /^@hashbrownai\//,
  // Anthropic / OpenAI SDKs used directly by agents
  /^@anthropic-ai\//,
  /^anthropic$/,
  /^openai$/,
  // Other frameworks that show up in born-in-showcase packages
  /^ag2$/,
  /^ag2-/,
  /^langroid$/,
  /^langroid-/,
  // Spring AI (Java coordinates appear with these prefixes)
  /^spring-ai$/,
  /^spring-ai-/,
  // Maven coordinate form for Spring AI: `group:artifact` with group
  // prefix `org.springframework.ai`. Matches `org.springframework.ai:foo`
  // for any artifact `foo`.
  /^org\.springframework\.ai:/,
];

function isFrameworkDep(name: string): boolean {
  return FRAMEWORK_PATTERNS.some((re) => re.test(name));
}

export interface DepMap {
  [name: string]: string; // name -> raw version specifier string
}

/**
 * Extended parse result: includes the DepMap plus advisory diagnostics.
 * Callers use these to surface WARN lines even when the parse did not
 * outright fail. Tests still assert against the returned DepMap shape.
 */
export interface ParseResult {
  deps: DepMap;
  /**
   * Entries the parser intentionally skipped (e.g. Poetry git-only deps,
   * inline tables with no `version`, malformed requirements.txt lines).
   * Non-fatal but surface as [WARN] in validateAll so CI has a paper
   * trail.
   */
  skipped: Array<{ name: string; reason: string }>;
  /**
   * Fully unparseable lines we dropped from requirements.txt. One entry
   * per dropped line.
   */
  dropped: string[];
}

/**
 * Parse a package.json into a DepMap. May throw on I/O failure or
 * malformed JSON; callers that tolerate partial failure should catch
 * and record the error. Runtime validates the parsed JSON is a plain
 * object (not null / array / scalar) before property access, and that
 * each entry in `dependencies` / `devDependencies` / `peerDependencies`
 * is a string. Non-string dep values throw.
 *
 * Note: dep values are validated as strings, but the shape of each
 * individual key (semver validity, registry name validity, etc.) is
 * NOT validated here — that is the caller's responsibility.
 *
 * @throws Error on fs.readFileSync / JSON.parse failure, when the
 *         parsed value is not a plain object, or when any declared
 *         dep value is not a string.
 */
function parsePackageJson(file: string): DepMap {
  const raw = fs.readFileSync(file, "utf-8");
  const parsed: unknown = JSON.parse(raw);
  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
    throw new Error(
      `expected JSON object at top level, got ${
        parsed === null
          ? "null"
          : Array.isArray(parsed)
            ? "array"
            : typeof parsed
      }`,
    );
  }
  // After the guard above we know `parsed` is a plain (non-null,
  // non-array) object. Treat it as `Record<string, unknown>` so every
  // bucket lookup is typed as `unknown` and MUST be shape-checked by
  // validateBucket below. Casting to a specific shape
  // (`{ dependencies?: Record<string, unknown>; … }`) would imply
  // pre-validated shape and invite callers to trust the cast without
  // runtime checks.
  const pkg: Record<string, unknown> = parsed as Record<string, unknown>;

  // Validate inner dep values are strings. A package.json with
  // non-string dep values (objects, numbers, nulls) is structurally
  // invalid per the npm schema; the JS spread below would otherwise
  // silently admit them into the DepMap and downstream comparisons
  // would throw or misbehave.
  const validateBucket = (
    bucket: unknown,
    bucketName: string,
  ): Record<string, string> | undefined => {
    if (bucket === undefined) return undefined;
    if (
      typeof bucket !== "object" ||
      bucket === null ||
      Array.isArray(bucket)
    ) {
      throw new Error(
        `expected '${bucketName}' to be an object of name→string, got ${
          bucket === null
            ? "null"
            : Array.isArray(bucket)
              ? "array"
              : typeof bucket
        }`,
      );
    }
    const ok: Record<string, string> = {};
    for (const [k, v] of Object.entries(bucket)) {
      if (typeof v !== "string") {
        throw new Error(
          `expected '${bucketName}.${k}' to be a string, got ${typeof v}`,
        );
      }
      ok[k] = v;
    }
    return ok;
  };

  const deps = validateBucket(pkg.dependencies, "dependencies");
  const peerDeps = validateBucket(pkg.peerDependencies, "peerDependencies");
  const devDeps = validateBucket(pkg.devDependencies, "devDependencies");

  // Merge dependencies, devDependencies, and peerDependencies. Frameworks
  // in JS apps often live in devDeps (e.g. Next.js starters), and pinning
  // rules apply to them all. On overlap, later spread wins: dev > peer >
  // runtime. That's fine because (a) the caller applies first-writer-wins
  // at the FILE level, and (b) in practice these rarely overlap within
  // one file.
  return {
    ...deps,
    ...peerDeps,
    ...devDeps,
  };
}

/**
 * PEP 503 name normalization: lowercase, collapse runs of `-`, `_`, `.`
 * into a single `-`. Used to compare Python dep names across underscore /
 * hyphen spellings (e.g. `langgraph_checkpoint` vs `langgraph-checkpoint`).
 */
function canonicalizePythonName(name: string): string {
  return name.toLowerCase().replace(/[-_.]+/g, "-");
}

/**
 * Returns true iff `spec` is a monorepo workspace reference that the
 * validator intentionally does NOT pin-check. Workspace refs (e.g.
 * `workspace:*`, `workspace:^`, `workspace:1.2.3`) are resolved by the
 * package manager against the local monorepo, not published — there is
 * no "pin" semantics to check. Handled out-of-band from isExactSpec
 * because isExactSpec merely classifies, while this classifies AND
 * indicates the caller should emit a [SKIP] rather than a [FAIL].
 */
function isWorkspaceRef(spec: string): boolean {
  if (!spec) return false;
  return /^workspace:/.test(spec.trim());
}

/**
 * Returns true iff `spec` is an EXACT pin per the INTEGRATION-CHECKLIST rule.
 *
 * Accepts:
 *   - Bare semver-ish strings: "1.2.3", "0.2.14", "1.0.0-beta.1"
 *   - PEP 440 forms: "1.2.3.post1", "1.2.3.dev1", "1.2.3rc1", "1.2.3a1",
 *                    "1.2.3b2"
 *   - Python exact specs: "==1.2.3", "===1.2.3", "==0.2.14", "==1.2.3rc1"
 *
 * Rejects:
 *   - Range operators: ^, ~, >=, <=, >, <, ~=, !=
 *   - X-ranges / wildcards: "1.x", "1.2.x", "1.2.*", "*", "X.X.X"
 *   - Dist-tags: "latest", "next", "" (empty)
 *   - Workspace/monorepo refs: "workspace:*", "workspace:^", "file:"
 *   - URLs / git refs / paths
 *   - Malformed Python `==` bodies without a full MAJOR.MINOR (e.g. `==0`).
 */
function isExactSpec(spec: string): boolean {
  if (!spec) return false;
  const trimmed = spec.trim();
  if (!trimmed) return false;

  // Reject any wildcard marker anywhere in the string. `*`, `x`, or `X`
  // appearing as a version component (e.g. "1.x", "1.2.*") is never exact.
  // The Python `==` form also cannot contain wildcards.
  if (/(^|[.\-_+])[xX*]([.\-_+]|$)/.test(trimmed)) return false;
  if (/\*/.test(trimmed)) return false;

  // Python == / === exact form.
  // Body must match MAJOR.MINOR with optional numeric sub-segments,
  // an optional PEP 440 pre-release tag (`a1`, `b2`, `rc3`, etc.)
  // directly attached, an optional `.postN` / `.devN` segment, an
  // optional `-pre` / `+local` suffix. The regex is anchored end-to-end
  // so degenerate bodies like `==1.2.foo` (dotted letter segment that
  // is not a recognized PEP 440 keyword) or `==1.2abc!` (illegal
  // trailing punctuation) are rejected — a non-anchored `^\d+\.\d+`
  // or a too-permissive tail like `(?:[-+.A-Za-z0-9]+)*` would accept
  // those and mis-classify them as exact pins.
  const pyMatch = trimmed.match(/^={2,3}\s*(\S+)$/);
  if (pyMatch) {
    return /^\d+\.\d+(?:\.\d+)*(?:[A-Za-z]+\d*)?(?:\.(?:post|dev)\d*)?(?:-[A-Za-z0-9.-]+)?(?:\+[A-Za-z0-9.-]+)?$/.test(
      pyMatch[1],
    );
  }

  // Anything starting with a range operator is NOT exact.
  if (/^[\^~<>!]/.test(trimmed)) return false;
  if (/^(>=|<=|==|~=|!=)/.test(trimmed)) return false;

  // Tags, workspace refs, URLs, paths.
  if (/^[A-Za-z]/.test(trimmed)) {
    // Starts with a letter: dist-tag like "latest" or "next", or
    // "workspace:*", "file:...", "github:user/repo", etc.
    return false;
  }

  // Bare version must start with a digit and contain no ranges/spaces.
  if (!/^\d/.test(trimmed)) return false;
  if (/\s/.test(trimmed)) return false;
  if (/[|]{1,2}/.test(trimmed)) return false; // "1.2.3 || 2.0.0"
  // Comma-joined ranges (Poetry / PEP 440): "1.2.3,>=1.0" is composed
  // of two constraints and cannot be a single exact pin.
  if (/,/.test(trimmed)) return false;

  // Bare version shape: MAJOR.MINOR[.PATCH] with an optional
  // pre-release / build / PEP 440 suffix. Enforced by a concrete
  // semver-shape regex so only digit-dotted-digit forms (plus
  // permitted suffixes) pass, rejecting exotic bare-letter tails
  // like `1x`, `2X`, and `1e2`.
  //
  // MAJOR.MINOR is required for bare versions so bare-spec acceptance
  // is symmetric with the Python `==` form above (which rejects `==1`).
  // MAJOR-only like `"1"` is rejected on both paths, keeping
  // drift-report behavior consistent across ecosystems.
  if (!/^\d+\.\d+(?:\.\d+)?(?:[-+.][A-Za-z0-9.-]+)*$/.test(trimmed)) {
    return false;
  }

  return true;
}

// Parse a requirements.txt line. Strip comments, extras, env markers,
// pip hash flags, index-url flags, and `--find-links` flags.
//
// Returns:
//   - `[name, versionSpec]` on a valid `name<spec>` form; `versionSpec`
//     MAY be an empty string when the line is name-only (e.g.
//     `langgraph`). The file-level walker is responsible for surfacing
//     these as `skipped[]` since an empty spec is not a pin.
//   - `null` when the line is unparseable (editable install, URL-only,
//     operator-leading, pure flag line, etc.).
function parseRequirementsLine(line: string): [string, string] | null {
  // Strip trailing comments.
  const stripped = line.replace(/#.*$/, "").trim();
  if (!stripped) return null;
  // Editable installs / URLs — not supported.
  if (/^-e\b/.test(stripped) || /^(https?|git\+)/.test(stripped)) return null;

  // Split on environment marker (;) and take the LHS.
  const lhs = stripped.split(";")[0].trim();

  // Strip pip-install flags attached to a single line:
  //   `--hash=sha256:...`, `--index-url=...`, `--extra-index-url=...`,
  //   `--find-links=...`. These appear AFTER the spec. Single-pass
  //   alternation avoids order-dependency between sequential replaces
  //   (e.g. a `--extra-index-url=...` substring being partially consumed
  //   by a naïve `--index-url=\S+` regex run first).
  const flagsStripped = lhs
    .replace(/\s+--(?:hash|index-url|extra-index-url|find-links)=\S+/g, "")
    .trim();

  // Match: name [extras] version-spec
  // name characters: letters, digits, -, _, .
  const match = flagsStripped.match(
    /^([A-Za-z0-9][A-Za-z0-9._-]*)(?:\[[^\]]*\])?\s*(.*)$/,
  );
  if (!match) return null;
  const name = match[1];
  const spec = (match[2] || "").trim();
  return [name, spec];
}

/**
 * Parse a requirements.txt file into a DepMap. Returns a ParseResult
 * with the DepMap plus:
 *   - `skipped`: name-only requirements (e.g. `langgraph` with no
 *     version spec) that the parser intentionally did NOT admit to the
 *     DepMap. The file-level walker surfaces these as [WARN] so
 *     operators see the manifest has an unpinned dep rather than the
 *     entry being silently dropped.
 *   - `dropped`: fully unparseable lines — caller surfaces as [WARN].
 *
 * @throws Error on fs.readFileSync failure.
 */
function parseRequirementsTxtDetailed(file: string): ParseResult {
  const raw = fs.readFileSync(file, "utf-8");
  const out: DepMap = {};
  const skipped: Array<{ name: string; reason: string }> = [];
  const dropped: string[] = [];
  for (const line of raw.split(/\r?\n/)) {
    // Empty and comment lines are legitimate — don't flag them as dropped.
    const stripped = line.replace(/#.*$/, "").trim();
    if (!stripped) continue;
    // Editable installs / URLs are valid requirements but we cannot
    // extract a pin from them; they're intentional non-deps, not drops.
    if (/^-e\b/.test(stripped) || /^(https?|git\+)/.test(stripped)) continue;
    const parsed = parseRequirementsLine(line);
    if (parsed) {
      // First-writer-wins within a file (a given dep may appear
      // multiple times with different pins; the earlier line wins).
      // NOTE: pip's own resolver does not define a "first vs last
      // writer" rule across identical lines — re-declaration within a
      // single requirements file is already ambiguous input, and real
      // installs are normally deduped upstream. We pick first-writer
      // here so the rule matches collectDepsFromDir's first-writer
      // file-level precedence (agent-scope wins over root-scope). If
      // a concrete case demands pip's actual semantics, replace this
      // block rather than layering an exception.
      const [name, spec] = parsed;
      if (!(name in out)) {
        if (!spec) {
          // Name-only line (e.g. `langgraph` with no spec): surface as
          // skipped since it's not pinning anything. See
          // INTEGRATION-CHECKLIST rule about exact pins.
          skipped.push({
            name,
            reason: "name-only requirement (no version)",
          });
        } else {
          out[name] = spec;
        }
      }
    } else {
      dropped.push(stripped);
    }
  }
  return { deps: out, skipped, dropped };
}

/**
 * Thin compatibility wrapper: returns a DepMap for callers that do not
 * care about dropped-line or skipped-line diagnostics. Internally
 * delegates to the detailed form.
 *
 * NOTE: This wrapper does NOT tolerate silent data loss. If the
 * underlying detailed parse produces any `skipped[]` or `dropped[]`
 * entries, this wrapper THROWS so the caller is forced to switch to
 * `parseRequirementsTxtDetailed` rather than quietly losing those
 * diagnostics. Callers that may legitimately encounter skipped/dropped
 * entries MUST call `parseRequirementsTxtDetailed` directly.
 *
 * @throws Error on fs.readFileSync failure.
 * @throws Error when the file contains skipped or dropped entries
 *         (use parseRequirementsTxtDetailed instead).
 */
function parseRequirementsTxt(file: string): DepMap {
  const detailed = parseRequirementsTxtDetailed(file);
  if (detailed.skipped.length > 0 || detailed.dropped.length > 0) {
    throw new Error(
      `parseRequirementsTxt: ${file} produced ${detailed.skipped.length} skipped and ` +
        `${detailed.dropped.length} dropped entries; use parseRequirementsTxtDetailed ` +
        `to access them instead of silently discarding.`,
    );
  }
  return detailed.deps;
}

/**
 * Scan `raw` starting at `openBracketIdx` (which must point at a `[`
 * character) and return the index of the matching closing `]`, skipping
 * over any `]` or `[` embedded in single- or double-quoted strings.
 * Returns -1 if no matching bracket is found before end-of-string OR
 * before a new TOML table header (`\n[...]` at column 0).
 *
 * This exists because the PEP 621 and PEP 621-extras arrays can legally
 * contain entries like `"langchain[all]==1.2.3"` where the bracket
 * character appears inside a quoted string. A non-greedy `[\s\S]*?\]`
 * regex silently truncates such arrays at the first `]` and drops
 * everything after — a silent miss that makes the validator emit [OK]
 * against incomplete dependency sets.
 *
 * The scanner handles:
 *   - Basic double-quoted strings: `"..."` (escape `\"` permitted).
 *   - Basic single-quoted strings: `'...'` (escape `\'` permitted).
 *   - TOML comments: `#` to end-of-line are ignored outside strings so
 *     a `]` that appears inside a comment does NOT satisfy the search.
 *   - Table header termination: a `\n[` at column 0 while still at
 *     depth > 0 means the array was never closed before the next
 *     table header — return -1 so the caller can throw.
 *
 * It does NOT handle TOML multi-line basic strings (`"""..."""`) or
 * nested arrays spanning multiple table bodies. A real TOML tokenizer
 * would be more correct; the tradeoff is accepted because our fixtures
 * are simple single-section arrays of strings.
 */
function findMatchingBracket(raw: string, openBracketIdx: number): number {
  let depth = 0;
  let i = openBracketIdx;
  while (i < raw.length) {
    const ch = raw[i];
    // A new TOML table header `\n[` at depth >= 1 means the current
    // array was never closed. The opening `[` of the header does NOT
    // count as a nested-array bump — it's a new section starting.
    // Only trigger this when we've already consumed the opening
    // bracket (i > openBracketIdx) and the next char is `[`.
    if (ch === "\n" && depth >= 1 && i + 1 < raw.length && raw[i + 1] === "[") {
      return -1;
    }
    if (ch === '"') {
      // Skip basic-string. Escapes: `\\` and `\"`.
      i += 1;
      while (i < raw.length) {
        const c = raw[i];
        if (c === "\\" && i + 1 < raw.length) {
          i += 2;
          continue;
        }
        if (c === '"') {
          i += 1;
          break;
        }
        i += 1;
      }
      continue;
    }
    if (ch === "'") {
      // Skip literal-string.
      i += 1;
      while (i < raw.length && raw[i] !== "'") i += 1;
      if (i < raw.length) i += 1;
      continue;
    }
    if (ch === "#") {
      // Skip to end-of-line. A `]` inside a comment must NOT close
      // the array.
      while (i < raw.length && raw[i] !== "\n") i += 1;
      continue;
    }
    if (ch === "[") {
      depth += 1;
      i += 1;
      continue;
    }
    if (ch === "]") {
      depth -= 1;
      if (depth === 0) return i;
      i += 1;
      continue;
    }
    i += 1;
  }
  return -1;
}

/**
 * Extract quoted-string entries out of a TOML array body (the text
 * between an opening `[` and its matching `]`), dispatching each entry
 * through `parseRequirementsLine` and merging into `out` (first-writer-
 * wins). Unparseable non-empty entries go into `dropped`.
 *
 * Name-only entries (e.g. bare `"langgraph"` in the array) are pushed
 * to `skipped[]` rather than silently admitted to `out` with an empty
 * spec. This mirrors `parseRequirementsTxtDetailed`'s file-level
 * handling so pyproject and requirements.txt report the same
 * diagnostics for the same input.
 */
function ingestArrayBody(
  body: string,
  out: DepMap,
  dropped: string[],
  skipped: Array<{ name: string; reason: string }>,
): void {
  const quoteRe = /"([^"\\]*(?:\\.[^"\\]*)*)"|'([^'\\]*(?:\\.[^'\\]*)*)'/g;
  let m: RegExpExecArray | null;
  while ((m = quoteRe.exec(body))) {
    const entry = m[1] ?? m[2] ?? "";
    const parsed = parseRequirementsLine(entry);
    if (parsed) {
      const [name, spec] = parsed;
      if (!(name in out)) {
        if (!spec) {
          // Name-only entry — not pinning anything. Surface as
          // skipped so a [WARN] is emitted, matching requirements.txt
          // handling. Without this, the DepMap silently gained an
          // entry with an empty spec and downstream error messages
          // read `(empty)` without explaining the cause.
          skipped.push({
            name,
            reason: "name-only requirement (no version)",
          });
        } else {
          out[name] = spec;
        }
      }
    } else if (entry.trim()) {
      dropped.push(entry);
    }
  }
}

/**
 * Extremely small pyproject.toml reader. Handles:
 *
 *   - Top-level `[project]` dependencies array (PEP 621).
 *   - Top-level `[project.optional-dependencies]` tables (PEP 621 extras)
 *     — every subkey's array is scanned.
 *   - Poetry `[tool.poetry.dependencies]` tables, including
 *     `[tool.poetry.group.<name>.dependencies]`.
 *
 * We avoid adding a full TOML dependency by using targeted regexes. The
 * parser stops at the NEXT TOP-LEVEL table header (e.g. `[tool.foo]`) —
 * crucially NOT at dotted subtables like `[project.optional-dependencies]`,
 * which are children of `[project]`.
 *
 * @throws Error on fs.readFileSync failure, or when a top-level
 *         `dependencies = [` array in `[project]` is opened but a
 *         matching `]` is never found by the quote-aware scanner.
 */
function parsePyprojectTomlDetailed(file: string): ParseResult {
  const raw = fs.readFileSync(file, "utf-8");
  const out: DepMap = {};
  const skipped: Array<{ name: string; reason: string }> = [];
  const dropped: string[] = [];

  // --- PEP 621: [project] table ---
  // Find the [project] section body, stopping at the next header of any
  // kind — whether a plain table like `[tool]` or a dotted table like
  // `[tool.poetry]` / `[project.optional-dependencies]`. Dotted
  // subtables under `[project]` (e.g. `[project.optional-dependencies]`)
  // are handled by separate scanners that run against the raw file, so
  // it is safe — and in fact required — to terminate [project] body at
  // the FIRST subsequent `[...]` header. Otherwise `dependencies = [`
  // keys inside Poetry group subtables can leak into PEP 621 parsing.
  const projectBodyRe =
    /(?:^|\n)\[project\][^\n]*\n([\s\S]*?)(?=\n\[[^\]\n]+\]|\n*$)/;
  const projectMatch = raw.match(projectBodyRe);
  if (projectMatch) {
    const section = projectMatch[1];

    // Find `dependencies = [` using a regex anchored to a line boundary
    // so we don't accidentally match `optional-dependencies = [` or
    // `dev-dependencies = [`. We need the POSITION of the opening `[`
    // so we can hand it to `findMatchingBracket`, which understands
    // quoted-string embedded brackets (e.g. `"langchain[all]==1.2.3"`).
    const depsKeyRe = /(?:^|\n)(dependencies\s*=\s*)\[/;
    const km = depsKeyRe.exec(section);
    if (km) {
      const bracketIdx = km.index + km[0].length - 1;
      const closeIdx = findMatchingBracket(section, bracketIdx);
      if (closeIdx < 0) {
        throw new Error(
          `malformed pyproject.toml: [project] 'dependencies = [' opened but never closed (missing matching ']')`,
        );
      }
      const body = section.slice(bracketIdx + 1, closeIdx);
      ingestArrayBody(body, out, dropped, skipped);
    }
  }

  // --- PEP 621: [project.optional-dependencies] subsections ---
  // Under PEP 621, optional dependencies are declared as:
  //   [project.optional-dependencies]
  //   extra_a = ["foo==1.0", "bar==2.0"]
  //   extra_b = ["baz==3.0"]
  // Each key's value is a string array; the array entries use the same
  // requirements.txt grammar as [project].dependencies. We scan each
  // key's array separately so optional-only framework deps are also
  // subject to pin drift checks.
  const optHeaderRe = /(?:^|\n)\[project\.optional-dependencies\][^\n]*\n/g;
  let optHdr: RegExpExecArray | null;
  while ((optHdr = optHeaderRe.exec(raw))) {
    const bodyStart = optHdr.index + optHdr[0].length;
    const rest = raw.slice(bodyStart);
    const nextHeader = rest.match(/\n\[/);
    const body = nextHeader ? rest.slice(0, nextHeader.index) : rest;
    // Walk subkey assignments `extra_name = [`. Use a regex to locate
    // each opening `[` but hand the closing-bracket search off to the
    // quote-aware scanner so embedded `]` characters (e.g. inside
    // `"langchain[all]==1.2.3"`) don't truncate the array and silently
    // drop subsequent entries.
    const subkeyKeyRe = /([A-Za-z0-9][A-Za-z0-9._-]*)\s*=\s*\[/g;
    let sm: RegExpExecArray | null;
    while ((sm = subkeyKeyRe.exec(body))) {
      const bracketIdx = sm.index + sm[0].length - 1;
      const closeIdx = findMatchingBracket(body, bracketIdx);
      if (closeIdx < 0) {
        // Unterminated extras array is genuinely malformed TOML — the
        // array's contents are truncated, so we cannot faithfully
        // report what was declared. Throw a parseError so the caller
        // surfaces a FAIL; downgrading to `dropped[]` (WARN) lets
        // silent data loss pass CI.
        throw new Error(
          `malformed pyproject.toml: [project.optional-dependencies].${sm[1]} opened '[' but never closed (missing ']')`,
        );
      }
      const arrBody = body.slice(bracketIdx + 1, closeIdx);
      ingestArrayBody(arrBody, out, dropped, skipped);
      // Advance past the close so the next subkey is found after it.
      subkeyKeyRe.lastIndex = closeIdx + 1;
    }
  }

  // --- Poetry: [tool.poetry.dependencies] AND
  //              [tool.poetry.group.<name>.dependencies] tables ---
  //
  // Poetry supports grouped dev/agent/etc. dependency sections under
  // `[tool.poetry.group.*.dependencies]`. Missing these sections causes the
  // validator to silently skip group-pinned frameworks, so we walk each
  // matching table header.
  //
  // Poetry version-string semantics: a bare version like `"1.2.3"` means
  // caret (`^1.2.3`) in Poetry — NOT an exact pin. We prefix such values
  // with `^` before storing so downstream `isExactSpec` correctly rejects
  // them. Tradeoff: the stored spec no longer textually matches the raw
  // pyproject.toml token, which is visible in FAIL messages that read
  // e.g. "pinned to ^1.2.3" when the file says `"1.2.3"`. This is
  // accurate (the effective spec IS `^1.2.3` per Poetry rules), but can
  // confuse an operator grepping the source — hence the explicit note.
  // Operator-prefixed strings (`^`, `~`, `>=`, `==`, ...) are stored
  // verbatim.
  const poetryHeaderRe =
    /(?:^|\n)\[tool\.poetry(?:\.group\.[A-Za-z0-9_-]+)?\.dependencies\][^\n]*\n/g;
  let headerMatch: RegExpExecArray | null;
  while ((headerMatch = poetryHeaderRe.exec(raw))) {
    const bodyStart = headerMatch.index + headerMatch[0].length;
    // Body ends at the next table header ([something]) or end of file.
    const rest = raw.slice(bodyStart);
    const nextHeader = rest.match(/\n\[/);
    const body = nextHeader ? rest.slice(0, nextHeader.index) : rest;

    for (const rawLine of body.split(/\r?\n/)) {
      const line = rawLine.replace(/#.*$/, "").trim();
      if (!line) continue;
      // key = value   (value may be a string or an inline table like
      // `{ version = "^1.0", extras = [...] }`)
      const kvMatch = line.match(/^([A-Za-z0-9][A-Za-z0-9._-]*)\s*=\s*(.*)$/);
      if (!kvMatch) continue;
      const name = kvMatch[1];
      // "python" is the interpreter constraint, not a dependency.
      if (name === "python") continue;
      let value = kvMatch[2].trim();

      let spec = "";
      if (value.startsWith("{")) {
        // Inline table. Pull `version = "..."` or `version = '...'` out
        // of it; if absent (e.g. git-only / path-only / branch-only),
        // record as skipped. TOML permits both single and double quotes
        // for basic strings and the stdlib / Poetry itself both accept
        // either form.
        const vm = value.match(/version\s*=\s*(?:"([^"]*)"|'([^']*)')/);
        if (vm) {
          spec = vm[1] ?? vm[2] ?? "";
        } else if (/\bgit\s*=/.test(value)) {
          skipped.push({
            name,
            reason: "Poetry git-only dep (no version)",
          });
          continue;
        } else if (/\bpath\s*=/.test(value)) {
          skipped.push({
            name,
            reason: "Poetry path-only dep (no version)",
          });
          continue;
        } else {
          skipped.push({
            name,
            reason: "Poetry inline table missing version",
          });
          continue;
        }
      } else if (value.startsWith("[")) {
        // Array-form Poetry dep: `foo = ["^1.0", "^2.0"]` expresses a
        // multi-constraint OR. There is no single "pinned version" for
        // such a declaration, so the validator cannot meaningfully
        // compare it to an exact Dojo pin. Surface as skipped so a
        // [WARN] is emitted — silently dropping these would let pin
        // drift slip through undetected.
        skipped.push({
          name,
          reason: "Poetry array-form dep (multi-constraint, not an exact pin)",
        });
        continue;
      } else if (value.startsWith('"') || value.startsWith("'")) {
        const q = value[0];
        const end = value.indexOf(q, 1);
        if (end > 0) {
          spec = value.slice(1, end);
        } else {
          // Opening quote but no matching closing quote before
          // end-of-line — the string is unterminated. Record as a
          // distinct `unterminated string` reason so the WARN line
          // names the actual fault rather than conflating with the
          // empty-version-string branch below.
          skipped.push({
            name,
            reason: "Poetry unterminated string value",
          });
          continue;
        }
      } else {
        // Not a string — skip (booleans, numbers, etc.). Record the
        // dep in `skipped[]` (rather than silently dropping) so
        // operators reading the WARN output see a malformed value
        // rather than a seemingly-clean file.
        const rawType = /^(true|false)\b/.test(value)
          ? "boolean"
          : /^-?\d/.test(value)
            ? "number"
            : value === "" || value.startsWith("\n")
              ? "empty"
              : typeof value;
        skipped.push({
          name,
          reason: `Poetry non-string dep value (got ${rawType})`,
        });
        continue;
      }

      // Trim at parse time so `isExactSpec` and downstream comparisons
      // don't have to worry about quoted whitespace (e.g. `" 1.2.3"`).
      spec = spec.trim();

      // Empty spec (e.g. `foo = ""`) is malformed — record as skipped
      // so the caller can surface a [WARN]. Without this, an empty
      // string silently stored would later be rendered as "(empty)"
      // in error messages without explaining WHY the spec was empty.
      if (!spec) {
        skipped.push({ name, reason: "Poetry empty version string" });
        continue;
      }

      // Poetry bare-version semantics: `"1.2.3"` means `^1.2.3`. Prefix
      // with `^` so it is correctly classified as non-exact by
      // `isExactSpec`. Anything already starting with an operator
      // character is stored verbatim.
      //
      // Caveat: a value that starts with a digit may still be a
      // composed range that Poetry stores in a single string — e.g.
      // `"1.2.3,>=1.0"` (comma-joined), `"1.2.3 || 2.0.0"` (pipe OR),
      // or a space-separated range. Prefixing any of these with `^`
      // produces a nonsense spec (e.g. `^1.2.3 || 2.0.0`). Only
      // prefix when the value is a lone bare version — no commas,
      // whitespace, `||` OR, or any range/PEP 440 operator character
      // (`<`, `>`, `~`, `^`, `!`). Everything else is stored
      // verbatim; `isExactSpec` will classify it correctly on the
      // range-operator / comma / whitespace / pipe paths.
      if (
        /^\d/.test(spec) &&
        !spec.includes(",") &&
        !spec.includes(" ") &&
        !spec.includes("||") &&
        !/[<>~^!]/.test(spec)
      ) {
        spec = "^" + spec;
      }

      // First-writer-wins within this file (top-level deps declared before
      // group deps keep their spec).
      if (!(name in out)) out[name] = spec;
    }
  }

  // Defensive guard: a file that *declares* a `dependencies = …` key
  // (under `[project]` or `[tool.poetry*]`) but produced ZERO extracted
  // entries AND no skipped/dropped diagnostics almost certainly means
  // the regex-based parser could not destructure that declaration —
  // e.g. `dependencies = "malformed-string"` (wrong TOML type), an
  // inline-table form we don't support, or some other shape the
  // targeted regexes miss. Silently accepting this produces a false-
  // clean [OK] for a file the validator never actually inspected, so
  // we throw to route the file to `parseErrors` → FAIL.
  //
  // IMPORTANT: we deliberately do NOT throw on files that merely lack
  // a `dependencies` declaration (tool-only configs like `[tool.black]`,
  // `[project]` metadata blocks with only `name`/`version`/`authors`,
  // hatch/uv/maturin configs without PEP 621 deps, etc.). Those produce
  // an empty DepMap as the correct, intended result.
  const declaresDependencies = /(?:^|\n)\s*dependencies\s*=/.test(raw);
  if (
    declaresDependencies &&
    Object.keys(out).length === 0 &&
    skipped.length === 0 &&
    dropped.length === 0
  ) {
    throw new Error(
      `pyproject.toml produced empty DepMap — a 'dependencies = …' key is declared but the regex parser could not extract any entries (likely malformed TOML or unsupported form).`,
    );
  }

  return { deps: out, skipped, dropped };
}

/**
 * Thin compatibility wrapper: returns a DepMap for callers that do not
 * care about skipped-dep diagnostics. Internally delegates to the
 * detailed form.
 *
 * NOTE: Like `parseRequirementsTxt`, this wrapper THROWS if the
 * underlying detailed parse produces any `skipped[]` or `dropped[]`
 * entries, so that silent data loss cannot occur via the wrapper path.
 * Callers that may legitimately encounter skipped/dropped entries MUST
 * call `parsePyprojectTomlDetailed` directly.
 *
 * @throws Error on fs.readFileSync failure, or on the specific narrow
 *         malformation: a top-level `[project] dependencies = [` array
 *         opened but never closed. This parser is NOT a general TOML
 *         validator — many other forms of malformed TOML will produce
 *         an empty DepMap rather than an exception.
 * @throws Error when the file contains skipped or dropped entries
 *         (use parsePyprojectTomlDetailed instead).
 */
function parsePyprojectToml(file: string): DepMap {
  const detailed = parsePyprojectTomlDetailed(file);
  if (detailed.skipped.length > 0 || detailed.dropped.length > 0) {
    throw new Error(
      `parsePyprojectToml: ${file} produced ${detailed.skipped.length} skipped and ` +
        `${detailed.dropped.length} dropped entries; use parsePyprojectTomlDetailed ` +
        `to access them instead of silently discarding.`,
    );
  }
  return detailed.deps;
}

// ---------------------------------------------------------------------------
// Find Dojo-side dependency files for a given example directory.
// ---------------------------------------------------------------------------

/**
 * Shape returned by `collectDepsFromDir` — used for both the Dojo side
 * (examples/integrations/<source>) and the showcase side
 * (showcase/integrations/<slug>). Both sides walk the same
 * DEP_FILE_CANDIDATES list; the structure of the result is identical.
 *
 * `DojoDepSources` and `ShowcaseDepSources` are exported as aliases for
 * call-site readability, but they are structurally the same type and
 * callers can freely pass one where the other is expected.
 */
export interface DepSources {
  // All absolute paths to dependency files that contributed deps.
  files: string[];
  // Invariant: there is no merged `deps` field. Callers that need a
  // cross-ecosystem view must compose it explicitly at the call site
  // (e.g. `{ ...pythonDeps, ...jsDeps }`) and pick a precedence that
  // matches their ecosystem. The comparator in `validateAll` reads
  // `jsDeps` and `pythonDeps` directly.
  //
  // JS deps only (from package.json files). Kept separate from
  // pythonDeps because npm names are case-sensitive and hyphen-
  // sensitive; applying PEP 503 canonicalization would merge distinct
  // npm packages. Keeping JS and Python in separate maps also
  // prevents a cross-ecosystem name collision (e.g. `openai` present
  // in both `package.json` and `requirements.txt`) from erasing one
  // side's spec in the comparator.
  jsDeps: DepMap;
  // Python deps only (from requirements.txt / pyproject.toml).
  // Subject to PEP 503 canonicalization (case-insensitive, with `-`,
  // `_`, `.` treated as equivalent).
  pythonDeps: DepMap;
  // Non-fatal parse errors accumulated during collection. Caller should
  // surface these rather than silently emit [OK].
  // `infra: true` means the error is a permissions/filesystem problem
  // (EACCES/ENOTDIR/EIO/…) rather than a content-parse failure. The
  // caller (validateAll) uses this to route infra errors through
  // UnreadableInputError → EXIT_UNREADABLE (3) instead of landing them
  // in report.fail as EXIT_DRIFT (1).
  parseErrors: Array<{ file: string; message: string; infra?: boolean }>;
  // Count of files this collector attempted to read — used to
  // distinguish "no files found" from "all files parse-errored".
  filesAttempted: number;
  // Dep diagnostics forwarded from parsers (git-only Poetry deps,
  // unparseable requirements lines).
  skipped: Array<{ file: string; name: string; reason: string }>;
  dropped: Array<{ file: string; line: string }>;
}
// Named aliases for call-site readability. Structurally identical to
// `DepSources`.
export type DojoDepSources = DepSources;

// Common candidate list for dep file discovery. Order IS precedence:
// earlier entries are walked first, and because `collectDepsFromDir`
// applies first-writer-wins at the file level, the earlier file's spec
// for a shared dep name beats any later file's spec for the same name.
//
// Explicit precedence order (most-specific → least-specific):
//   1. apps/agent/*   — agent-scope manifests win over anything else
//   2. agent/*        — short-form `agent/` variant
//   3. apps/web/*     — showcase packages that only ship a web app
//   4. apps/app/*     — starter layouts using `apps/app/`
//   5. <root>/*       — catch-all fallback
const DEP_FILE_CANDIDATES = [
  "apps/agent/package.json",
  "apps/agent/pyproject.toml",
  "apps/agent/requirements.txt",
  "agent/package.json",
  "agent/pyproject.toml",
  "agent/requirements.txt",
  "apps/web/package.json",
  "apps/web/pyproject.toml",
  "apps/web/requirements.txt",
  "apps/app/package.json",
  "apps/app/pyproject.toml",
  "apps/app/requirements.txt",
  // Root-level files fill in anything not declared above.
  "package.json",
  "requirements.txt",
  "pyproject.toml",
];

function isPythonManifest(abs: string): boolean {
  return abs.endsWith("requirements.txt") || abs.endsWith("pyproject.toml");
}

/**
 * Common collector used by both Dojo-side and showcase-side. Walks
 * DEP_FILE_CANDIDATES in order, applying first-writer-wins at the file
 * level. Parse errors are accumulated rather than thrown so one bad
 * sibling doesn't abort the whole run.
 *
 * @throws Error on an unrecognized dep file path. This should be
 *         unreachable because DEP_FILE_CANDIDATES is a closed list; the
 *         throw exists to catch programmer error if someone adds a new
 *         file to DEP_FILE_CANDIDATES without wiring up a parser here.
 */
function collectDepsFromDir(rootDir: string): DepSources {
  const result: DepSources = {
    files: [],
    jsDeps: {},
    pythonDeps: {},
    parseErrors: [],
    filesAttempted: 0,
    skipped: [],
    dropped: [],
  };
  for (const rel of DEP_FILE_CANDIDATES) {
    const abs = path.join(rootDir, rel);
    // Prefer fs.statSync so an EACCES (unreadable) candidate is
    // distinguished from ENOENT (not present). `fs.existsSync` returns
    // false in both cases, which silently ignores broken permissions
    // — a missing framework dep file would then never be flagged.
    try {
      fs.statSync(abs);
    } catch (e) {
      const err = e as NodeJS.ErrnoException;
      // A falsy throw (`throw null`, `throw undefined`, `throw ""`) carries
      // zero diagnostic info. Do not collapse into the ENOENT branch —
      // treat as unreadable so the caller routes through
      // UnreadableInputError → EXIT_UNREADABLE (3). Collapsing a falsy
      // throw into "candidate absent" would hide fs-layer failures and
      // produce a false green. Log a stderr breadcrumb AND classify as
      // infra so operators see what actually went wrong.
      if (!err) {
        console.error(
          `[validate-pins] statSync on ${abs} threw a falsy value (${String(e)}); treating as unreadable input`,
        );
        result.parseErrors.push({
          file: abs,
          message: `stat failed with falsy throw: ${String(e)}`,
          infra: true,
        });
        continue;
      }
      if (err.code === "ENOENT") continue;
      // EACCES / EIO / ELOOP / etc. — the candidate is "probably
      // there" but we can't read it. Surface as a parse error so the
      // caller emits a FAIL rather than silently passing over it.
      result.parseErrors.push({
        file: abs,
        message: `stat failed (${err.code ?? "unknown"}): ${err.message ?? String(e)}`,
        infra: true,
      });
      continue;
    }
    // Determine which parser to use BEFORE the try block so that an
    // unrecognized extension is treated as a programmer bug (throws out
    // of this function) rather than silently absorbed as a "successful
    // parse of empty deps". This is a closed-list guarantee: every
    // entry in DEP_FILE_CANDIDATES must have a parser here.
    let parser: "package.json" | "requirements.txt" | "pyproject.toml";
    if (abs.endsWith("package.json")) {
      parser = "package.json";
    } else if (abs.endsWith("requirements.txt")) {
      parser = "requirements.txt";
    } else if (abs.endsWith("pyproject.toml")) {
      parser = "pyproject.toml";
    } else {
      throw new Error(
        `collectDepsFromDir: no parser for dep file ${abs}. DEP_FILE_CANDIDATES and parser dispatch are out of sync.`,
      );
    }
    result.filesAttempted += 1;
    let parsed: DepMap = {};
    let skipped: Array<{ name: string; reason: string }> = [];
    let dropped: string[] = [];
    try {
      if (parser === "package.json") {
        parsed = parsePackageJson(abs);
      } else if (parser === "requirements.txt") {
        const detailed = parseRequirementsTxtDetailed(abs);
        parsed = detailed.deps;
        skipped = detailed.skipped;
        dropped = detailed.dropped;
      } else {
        const detailed = parsePyprojectTomlDetailed(abs);
        parsed = detailed.deps;
        skipped = detailed.skipped;
        dropped = detailed.dropped;
      }
    } catch (e) {
      const msg = e instanceof Error ? e.message : String(e);
      // Record only — a single downstream [FAIL] line per parse error is
      // emitted by validateAll with slug context. Immediate
      // console.error here would cause duplicate output.
      //
      // Detect infra errno codes bubbling up from readFileSync (which is
      // called unguarded inside parsePackageJson / parseRequirementsTxt /
      // parsePyprojectToml). Without this classification an EACCES on
      // the content-only read would be treated as a parse error →
      // report.fail → EXIT_DRIFT (1), but the correct routing is
      // UnreadableInputError → EXIT_UNREADABLE (3). The stat guard
      // above only catches errno at stat time; TOCTOU or a 0000-mode
      // file on a readable parent (owner can chmod but not read the
      // file content, e.g. group read on a file you don't own) slips
      // past stat and errors on read instead.
      const errno = (e as NodeJS.ErrnoException | undefined)?.code;
      const isInfra =
        errno === "EACCES" ||
        errno === "EIO" ||
        errno === "ENOTDIR" ||
        errno === "ELOOP" ||
        errno === "EPERM";
      result.parseErrors.push({
        file: abs,
        message: msg,
        ...(isInfra ? { infra: true } : {}),
      });
      continue;
    }
    result.files.push(abs);
    for (const s of skipped) {
      result.skipped.push({ file: abs, name: s.name, reason: s.reason });
    }
    for (const d of dropped) {
      result.dropped.push({ file: abs, line: d });
    }
    const fromPython = isPythonManifest(abs);
    for (const [name, spec] of Object.entries(parsed)) {
      // First-writer-wins: agent-side files (walked first) take precedence
      // over root files. This matches the intent documented above.
      // Track JS vs Python in separate maps at parse time so a
      // cross-ecosystem name collision (e.g. `openai` on both sides)
      // cannot obliterate one side's spec. A shared map would require
      // deriving JS deps via `diffMaps(deps, pythonDeps)`, which drops
      // the JS dep ENTIRELY whenever its name also appears in
      // `pythonDeps` — unacceptable because both sides must be
      // compared independently.
      if (fromPython) {
        if (!(name in result.pythonDeps)) {
          result.pythonDeps[name] = spec;
        }
      } else {
        if (!(name in result.jsDeps)) {
          result.jsDeps[name] = spec;
        }
      }
    }
  }
  return result;
}

// The Dojo examples have varied layouts. We walk app-specific paths FIRST
// so that their specs take precedence over the root package.json, which
// often pins older / generic versions. This implements first-writer-wins
// at the file level: the first file that declares a dep wins.
function collectDojoDeps(exampleDir: string): DojoDepSources {
  return collectDepsFromDir(exampleDir);
}

// ---------------------------------------------------------------------------
// Showcase-side dep collection
// ---------------------------------------------------------------------------

// Structurally identical to `DepSources` — kept as a named alias for
// readability at call sites so the showcase vs dojo side remains
// textually distinct.
export type ShowcaseDepSources = DepSources;

function collectShowcaseDeps(packageDir: string): ShowcaseDepSources {
  return collectDepsFromDir(packageDir);
}

/**
 * Build a canonicalized lookup for a DepMap. Keeps the original name for
 * error messages but keys by canonical name so `foo_bar` and `foo-bar`
 * collide.
 *
 * When two entries canonicalize to the same key with DIFFERENT specs
 * (e.g. `langgraph_checkpoint==1.0.0` alongside
 * `langgraph-checkpoint==2.0.0` in the same requirements.txt) the
 * first-writer's entry is retained for comparison and a warning is
 * surfaced so operators see the conflict rather than silently losing
 * one of the pins. Same-spec collisions are considered redundant and
 * dropped silently.
 */
interface CanonicalizeWarning {
  key: string;
  firstName: string;
  firstSpec: string;
  dupName: string;
  dupSpec: string;
}
function canonicalizeDepMap(
  deps: DepMap,
  isPython: boolean,
): {
  out: Record<string, { name: string; spec: string }>;
  warnings: CanonicalizeWarning[];
} {
  const out: Record<string, { name: string; spec: string }> = {};
  const warnings: CanonicalizeWarning[] = [];
  for (const [name, spec] of Object.entries(deps)) {
    const key = isPython ? canonicalizePythonName(name) : name;
    // First-writer-wins within this function too (keep name as it was
    // originally declared). If a later entry collides on the canonical
    // key with a DIFFERENT spec, surface it as a warning — a silent
    // drop would hide a real drift signal (two entries for the same
    // distribution, both pinned, to different versions).
    const prior = out[key];
    if (prior === undefined) {
      out[key] = { name, spec };
      continue;
    }
    if (prior.spec !== spec) {
      warnings.push({
        key,
        firstName: prior.name,
        firstSpec: prior.spec,
        dupName: name,
        dupSpec: spec,
      });
    }
  }
  return { out, warnings };
}

// ---------------------------------------------------------------------------
// Main
// ---------------------------------------------------------------------------

// The four buckets are appended-to only while building the report in
// validateAll(); nothing should mutate them once they're returned to
// the printer. Marking them readonly string[] prevents drive-by mutation
// at read sites without paying the cost of a full PackageIssue tagged
// union + renderer refactor (deferred — the buckets are stringly-typed
// but that is a self-contained simplification rather than a correctness
// issue today). The mutation sites inside validateAll type as
// `string[]` via the inner `ReportBuilder` so .push() still works.
interface Report {
  readonly fail: readonly string[];
  readonly warn: readonly string[];
  readonly skip: readonly string[];
  readonly ok: readonly string[];
}
// Internal mutable shape used only while building the Report.
// Narrowed to `Report` (readonly) on return.
interface ReportBuilder {
  fail: string[];
  warn: string[];
  skip: string[];
  ok: string[];
}

function validateAll(): Report {
  const report: ReportBuilder = { fail: [], warn: [], skip: [], ok: [] };
  // Compute paths ONCE per run. `paths()` re-validates the
  // VALIDATE_PINS_REPO_ROOT env var every call, so invoking it per
  // slug turns every iteration into an fs.statSync call that has
  // already been performed.
  const resolvedPaths = paths();
  const { PACKAGES_DIR, REPO_ROOT, CANONICAL_PINS_FILE } = resolvedPaths;

  // Load the canonical pins config FIRST so a misconfigured/missing
  // file fails loudly before we waste time scanning integrations.
  // loadCanonicalPins() throws UnreadableInputError on read errors
  // (missing file → EXIT_UNREADABLE) and CanonicalPinsError on
  // schema/syntax problems (top-level catch routes to EXIT_INTERNAL,
  // since a corrupt config is a validator-side bug not pin drift).
  const canonical = loadCanonicalPins(CANONICAL_PINS_FILE);

  // Missing packages dir must not produce a silent pass. If the validator
  // can't see any packages, it has nothing to check, which is almost
  // certainly a path misconfiguration. Route this as EXIT_UNREADABLE (3)
  // so it's classed with other repo-structure problems rather than with
  // real drift findings — mixing the two buckets makes CI triage harder.
  //
  // Use `fs.statSync` + catch-ENOENT rather than `fs.existsSync` so a
  // permission error (EACCES) is not silently collapsed into "not
  // present" and the packages dir not being a directory (i.e. it's a
  // file) is caught before readdirSync throws a less-obvious error.
  let packagesStat: fs.Stats;
  try {
    packagesStat = fs.statSync(PACKAGES_DIR);
  } catch (e) {
    const err = e as NodeJS.ErrnoException;
    if (err && err.code === "ENOENT") {
      throw new UnreadableInputError(
        `Packages dir not found at ${PACKAGES_DIR}`,
      );
    }
    // EACCES / ENOTDIR / EIO / etc. — packages dir exists but is
    // unreadable by this process. Route through UnreadableInputError
    // so the top-level catch maps this to EXIT_UNREADABLE (3)
    // rather than collapsing to EXIT_DRIFT (1) via report.fail.
    const msg = err && err.message ? err.message : String(e);
    throw new UnreadableInputError(
      `Packages dir stat failed (${err?.code ?? "unknown"}): ${PACKAGES_DIR}: ${msg}`,
    );
  }
  if (!packagesStat.isDirectory()) {
    throw new UnreadableInputError(
      `Packages dir is not a directory: ${PACKAGES_DIR}`,
    );
  }

  // readdirSync can fail independently of the statSync above (TOCTOU:
  // perms or mount state can change between the two calls, and EIO /
  // ENOTDIR / EACCES are all observable here). Without this wrapper the
  // error propagates to the top-level catch as a generic Error and is
  // misrouted to EXIT_INTERNAL (2). We convert infra-class errno codes
  // into UnreadableInputError so they route to EXIT_UNREADABLE (3),
  // preserving the same taxonomy as the statSync branch above.
  let slugs: string[];
  try {
    slugs = fs
      .readdirSync(PACKAGES_DIR, { withFileTypes: true })
      .filter((d) => d.isDirectory())
      .map((d) => d.name)
      .sort();
  } catch (e) {
    const err = e as NodeJS.ErrnoException;
    const code = err?.code ?? "unknown";
    const msg = err?.message ?? String(e);
    // All readdir failures here are infra-class (we already passed the
    // stat + isDirectory guard above, so the dir did exist and was a
    // directory). Route to EXIT_UNREADABLE (3) so CI distinguishes
    // perms/mount state from a validator crash.
    throw new UnreadableInputError(
      `Packages dir readdir failed (${code}): ${PACKAGES_DIR}: ${msg}`,
    );
  }

  // Empty packages dir is the same class of error as missing — the
  // validator produced no results, so we fail loudly rather than exit 0.
  // Class this as EXIT_UNREADABLE (3): it's a repo-structure /
  // configuration problem (wrong VALIDATE_PINS_REPO_ROOT, bad checkout),
  // not actual pin drift. Keeping it out of report.fail preserves the
  // contract that EXIT_DRIFT (1) means "real drift findings".
  if (slugs.length === 0) {
    throw new UnreadableInputError(
      `No showcase packages discovered under ${PACKAGES_DIR} — is VALIDATE_PINS_REPO_ROOT pointing at the right tree?`,
    );
  }

  // Accumulates the first infra-class parseError observed during the
  // slug loop. We deliberately do NOT throw mid-loop — doing so would
  // orphan the report entries for preceding slugs AND the remaining
  // content parseErrors for the current slug, which hides real drift
  // behind a single infra misconfig. Throw at the end instead, with
  // the partial report attached so the top-level catch can print it.
  let pendingInfraError: UnreadableInputError | undefined;

  for (const slug of slugs) {
    const pkgDir = path.join(PACKAGES_DIR, slug);

    const showcase = collectShowcaseDeps(pkgDir);
    const slugOverrides = canonical.overrides[slug] ?? {};

    // Parse errors: surface as FAIL so the process exits non-zero. A
    // silent WARN lets broken manifests slip through CI with [OK].
    //
    // EXCEPTION: infra errors (stat EACCES/ENOTDIR/…) are NOT drift —
    // they are permissions/filesystem misconfig. Route them through
    // UnreadableInputError so the top-level catch maps to
    // EXIT_UNREADABLE (3) rather than report.fail → EXIT_DRIFT (1).
    //
    // CRITICAL: do NOT throw mid-loop here. Accumulate the first infra
    // error into `pendingInfraError` and let the slug loop finish so
    // every OTHER slug still contributes to the report. The top-level
    // catch will print the (partial) report before setting
    // EXIT_UNREADABLE, so operators see the full FAIL/WARN/SKIP for
    // every slug that was processed. Content-parse errors for THIS
    // slug's remaining files still land in report.fail below.
    for (const pe of showcase.parseErrors) {
      if (pe.infra && pendingInfraError === undefined) {
        pendingInfraError = new UnreadableInputError(
          `${slug}: unreadable input at ${path.relative(REPO_ROOT, pe.file)}: ${pe.message}`,
        );
      }
    }
    // Skip content-parse fail emission for entries tagged as infra —
    // those are routed through pendingInfraError and the top-level
    // catch, not report.fail.
    for (const pe of showcase.parseErrors) {
      if (pe.infra) continue;
      report.fail.push(
        `[FAIL] ${slug}: parse error in ${path.relative(REPO_ROOT, pe.file)}: ${pe.message}`,
      );
    }
    // Pre-seed pkgHadViolation from parseErrors. Otherwise a slug with
    // a mix of valid + parse-errored files would have one or more
    // [FAIL] lines AND still receive an [OK] line at the end (because
    // `pkgHadViolation` was only set from the per-dep loop). A slug
    // must not appear in both report.ok and report.fail.
    let pkgHadParseError = false;
    if (showcase.parseErrors.length > 0) {
      pkgHadParseError = true;
    }

    // Skipped deps (e.g. Poetry git-only) — WARN only.
    for (const s of showcase.skipped) {
      report.warn.push(
        `[WARN] ${slug}: skipped ${s.name} in ${path.relative(REPO_ROOT, s.file)}: ${s.reason}`,
      );
    }
    // Dropped requirements.txt lines (unparseable but not fatal) — WARN.
    for (const d of showcase.dropped) {
      report.warn.push(
        `[WARN] ${slug}: dropped unparseable line '${d.line}' in ${path.relative(REPO_ROOT, d.file)}`,
      );
    }

    // Distinguish "genuinely no files" from "files existed but all
    // parse-errored". A showcase package with zero dep files is
    // structurally wrong — it cannot demonstrate a framework
    // integration without declared runtime dependencies. Emit [FAIL]
    // so CI catches it rather than silently marking the package OK.
    if (showcase.files.length === 0) {
      if (showcase.filesAttempted === 0) {
        report.fail.push(
          `[FAIL] ${slug}: no dependency files found in showcase package`,
        );
      }
      // else: all attempted files parse-errored; FAIL already emitted.
      continue;
    }

    // Canonicalize separately for JS and Python (npm names are
    // case-sensitive; PEP 503 normalization applies only to Python).
    const scPythonCanonResult = canonicalizeDepMap(
      showcase.pythonDeps,
      /* isPython */ true,
    );
    const scJsRawResult = canonicalizeDepMap(
      showcase.jsDeps,
      /* isPython */ false,
    );
    const scPythonCanon = scPythonCanonResult.out;
    const scJsRaw = scJsRawResult.out;

    // Surface canonical-key collisions with DIFFERENT specs as WARN —
    // two pinned entries for the same distribution at different versions
    // within one file is a real drift signal that must not be silently
    // dropped by first-writer-wins.
    const emitCanonicalWarnings = (warns: CanonicalizeWarning[]) => {
      for (const w of warns) {
        report.warn.push(
          `[WARN] ${slug}: duplicate entries for canonical key '${w.key}' with different specs ` +
            `(${w.firstName}=${w.firstSpec || "(empty)"} vs ${w.dupName}=${w.dupSpec || "(empty)"})`,
        );
      }
    };
    emitCanonicalWarnings(scPythonCanonResult.warnings);
    emitCanonicalWarnings(scJsRawResult.warnings);

    let pkgHadViolation = pkgHadParseError;

    // Build the iteration set (Python + JS) with the same shape so a
    // single loop applies the invariant. Sort within each ecosystem
    // for stable, hash-friendly FAIL output.
    const iterations: Array<{
      key: string;
      entry: { name: string; spec: string };
      isPython: boolean;
    }> = [];
    for (const key of Object.keys(scPythonCanon).sort()) {
      iterations.push({ key, entry: scPythonCanon[key], isPython: true });
    }
    for (const key of Object.keys(scJsRaw).sort()) {
      iterations.push({ key, entry: scJsRaw[key], isPython: false });
    }

    for (const { entry, isPython } of iterations) {
      const displayName = entry.name;
      const spec = entry.spec;

      // Per-slug override resolution is done by the raw declared dep
      // name (the way it appears in package.json / requirements.txt /
      // pyproject.toml), so overrides authors can read & write the
      // canonical-pins file directly. For Python, we ALSO match on the
      // PEP 503 canonicalized name so e.g. `langgraph_checkpoint` in
      // an override file aligns with a `langgraph-checkpoint` dep.
      const overrideSpec =
        slugOverrides[displayName] ??
        (isPython
          ? slugOverrides[canonicalizePythonName(displayName)]
          : undefined);

      // Workspace refs have no pin semantics — skip, don't FAIL. Mirror
      // the historical behavior so workspace-resolved deps in showcase
      // packages don't trip the validator.
      if (isWorkspaceRef(spec)) {
        report.skip.push(
          `[SKIP] ${slug}: ${displayName} workspace ref (${spec})`,
        );
        continue;
      }

      // @copilotkit/* canonical-version check. Applies to JS deps
      // only (the @-prefixed scope is npm-native; Python copilotkit
      // packages, if any, fall through to the framework-exact-pin
      // check below).
      if (!isPython && /^@copilotkit\//.test(displayName)) {
        if (overrideSpec !== undefined) {
          // Override accepts the spec verbatim — does NOT require it
          // to be an exact pin (this is how the `pkg.pr.new` URL
          // case is allowed for built-in-agent).
          if (spec !== overrideSpec) {
            report.fail.push(
              `[FAIL] ${slug}: ${displayName} pinned to ${spec || "(empty)"}, ` +
                `override expects ${overrideSpec}`,
            );
            pkgHadViolation = true;
          }
          continue;
        }
        if (spec !== canonical.canonicalCopilotKitVersion) {
          report.fail.push(
            `[FAIL] ${slug}: ${displayName} pinned to ${spec || "(empty)"}, ` +
              `canonical is ${canonical.canonicalCopilotKitVersion}`,
          );
          pkgHadViolation = true;
        }
        continue;
      }

      // Detect framework deps. For Python, canonicalize the name
      // before matching FRAMEWORK_PATTERNS so PEP 503 variants are
      // recognized.
      const detectionName = isPython
        ? canonicalizePythonName(displayName)
        : displayName;
      if (!isFrameworkDep(detectionName)) continue;

      // Non-@copilotkit framework dep: must be EXACTLY pinned (or
      // match a per-slug override verbatim). The override permits
      // non-semver values (URLs, dist-tags) where a deliberate
      // exception is documented; the canonical config schema requires
      // an explicit override entry per slug+dep, so this is not a
      // silent escape hatch.
      if (overrideSpec !== undefined) {
        if (spec !== overrideSpec) {
          report.fail.push(
            `[FAIL] ${slug}: ${displayName} pinned to ${spec || "(empty)"}, ` +
              `override expects ${overrideSpec}`,
          );
          pkgHadViolation = true;
        }
        continue;
      }
      if (!isExactSpec(spec)) {
        report.fail.push(
          `[FAIL] ${slug}: ${displayName} is not an exact pin ` +
            `(${spec || "(empty)"})`,
        );
        pkgHadViolation = true;
      }
    }

    if (!pkgHadViolation) {
      report.ok.push(`[OK] ${slug}`);
    }
  }

  // If an infra error was observed mid-loop, throw it NOW that the
  // slug loop has fully finished. Attach the partial report so the
  // top-level catch can print every FAIL/WARN/SKIP line for slugs
  // that completed, then exit 3 (EXIT_UNREADABLE). This preserves the
  // "infra error → exit 3" contract while no longer discarding drift
  // findings for unaffected slugs.
  if (pendingInfraError !== undefined) {
    // Rebuild a fresh UnreadableInputError carrying the final report
    // — the one we captured earlier was constructed before all slugs
    // had been processed, so its partialReport would be stale.
    throw new UnreadableInputError(pendingInfraError.message, report);
  }

  return report;
}

/**
 * Print a report. [OK] and [SKIP] go to stdout; [FAIL] and [WARN] go to
 * stderr per Unix convention so CI logs, grep `|`, and humans can
 * distinguish.
 */
function printReport(report: Report): void {
  for (const line of report.ok) console.log(line);
  for (const line of report.skip) console.log(line);
  for (const line of report.warn) console.error(line);
  for (const line of report.fail) console.error(line);

  const summary =
    `Summary: OK=${report.ok.length} ` +
    `SKIP=${report.skip.length} ` +
    `WARN=${report.warn.length} ` +
    `FAIL=${report.fail.length}`;
  // Summary to stdout — it's an informational line, not an error.
  console.log("");
  console.log(summary);
}

// Exit codes are set via `process.exitCode` rather than `process.exit(N)`
// so that stdout/stderr have time to drain before the process
// terminates. `process.exit` is synchronous and can truncate output —
// the hash-based ratchet in CI compares full summary/table output and a
// truncated line would silently change the hash. Mirrors the audit.ts
// pattern.
// Typed setter for `process.exitCode` — forces every exit-code
// assignment in this file through the closed `PinsExitCode` union, so
// a typo like `process.exitCode = 4` becomes a compile error.
function setExitCode(code: PinsExitCode): void {
  process.exitCode = code;
}

function main(): void {
  const report = validateAll();
  printReport(report);
  setExitCode(report.fail.length > 0 ? EXIT_DRIFT : EXIT_OK);
}

/**
 * Returns true iff `argv1` refers to the same file as `scriptPath`
 * (which should be the caller's `import.meta.url`-derived file path,
 * e.g. via `fileURLToPath(import.meta.url)`). Uses strict
 * resolve-then-equal instead of substring match, so paths that merely
 * contain "validate-pins" (test harnesses, worker processes) do NOT
 * trigger `main()` on import.
 *
 * On a `path.resolve` failure (bizarre non-string input) we log to
 * stderr and set `process.exitCode = 2` so the caller sees a non-zero
 * exit; we still return false so main() doesn't run. A bare `catch {}`
 * would silently skip main() AND exit 0, masking bugs.
 */
function isMainPath(argv1: string | undefined, scriptPath: string): boolean {
  if (!argv1) return false;
  try {
    return path.resolve(argv1) === path.resolve(scriptPath);
  } catch (e) {
    const msg = e instanceof Error ? e.message : String(e);
    console.error(`[isMainPath] path.resolve failed: ${msg}`);
    setExitCode(EXIT_INTERNAL);
    return false;
  }
}

// Only run main when invoked directly (not when imported for tests).
// Top-level try/catch distinguishes "pin drift" (exit 1, legitimate) from
// "validator crashed" (exit 2, needs investigation). validate-parity.ts
// shares the "top-level try/catch routes crashes to a distinct exit
// code" pattern, but its exit-code numbering differs — see the header
// docstring for details.
if (isMainPath(process.argv[1], __filename)) {
  try {
    main();
  } catch (e) {
    const msg = e instanceof Error ? e.stack || e.message : String(e);
    if (e instanceof UnreadableInputError) {
      // Print the partial report FIRST (if present) so operators see
      // FAIL/WARN/SKIP for every slug that was processed before the
      // infra error. Without this, a single infra error would orphan
      // all already-collected report entries and produce a bare error
      // line with no diagnostic context.
      if (e.partialReport) {
        printReport(e.partialReport);
      }
      console.error(`[UNREADABLE INPUT] validate-pins: ${msg}`);
      setExitCode(EXIT_UNREADABLE);
    } else {
      console.error(`[INTERNAL ERROR] validate-pins crashed: ${msg}`);
      setExitCode(EXIT_INTERNAL);
    }
  }
}

// Re-export the drift-comparison core so downstream consumers (the
// showcase-harness pin-drift probe driver, future CLI flags) can reach the
// ratchet logic through the same entry point as the rest of validate-pins.
// The core module is the single source of truth for the comparison that
// used to live only in `.github/workflows/showcase_validate.yml` shell.
export {
  computePinDrift,
  PinDriftBaselineError,
} from "./validate-pins-core.js";
export type {
  PinDriftInput,
  PinDriftResult,
  PinDriftStatus,
} from "./validate-pins-core.js";

export {
  resolveExampleDir,
  resolveExampleDirDetailed,
  collectShowcaseDeps,
  collectDojoDeps,
  parsePackageJson,
  parseRequirementsLine,
  parseRequirementsTxt,
  parseRequirementsTxtDetailed,
  parsePyprojectToml,
  parsePyprojectTomlDetailed,
  canonicalizePythonName,
  isExactSpec,
  isFrameworkDep,
  isMainPath,
  validateAll,
  printReport,
  FALLBACK_MAP,
  BORN_IN_SHOWCASE,
};