Package Spelunker

Package Spelunker is a workspace-aware Node package investigation engine. It will resolve the exact package artifact and entry point used by a project, model its public TypeScript API, compare package versions, relate changes to local usages, and combine specialist diagnostics into one evidence-backed report.

The project is intentionally core-first: a normal TypeScript library owns the analysis, while the CLI and MCP server remain thin interfaces over the same contracts.

Status: Milestone 0 closure and Milestone 1 implementation. Versioned contracts, deterministic fixtures, safe snapshots, npm/pnpm importer-aware package selection, and snapshot-only Node runtime and isolated TypeScript declaration resolution are executable. Public-symbol analysis and applications remain planned.

Why This Exists

Understanding a dependency currently requires manual searches through node_modules, manifests, conditional exports, declaration re-exports, lockfiles, documentation, and package-quality tools. Those sources often inspect different versions or answer different questions.

Package Spelunker anchors an investigation to one immutable package snapshot and one importer context, then preserves evidence and authority as results move through the system.

Planned Capabilities

• Discover npm, pnpm, Yarn, and Bun workspace context.
• Resolve an installed package from an exact importer under Node and TypeScript semantics.
• Enumerate public entry points, exports, symbols, signatures, members, overloads, and JSDoc.
• Retrieve and verify exact registry artifacts without accepting Git, directory, file, or arbitrary URL package specifications.
• Compare normalized export maps, public APIs, manifests, runtime requirements, and diagnostics.
• Find affected local usages for package upgrades.
• Normalize optional publint, Are the Types Wrong, documentation, and package-health results.
• Expose the same engine through a CLI and an MCP server.

Non-Negotiable Principles

1. Never import, require, or execute inspected package code.
2. Tie every conclusion to an exact installed artifact or verified registry tarball.
3. Resolve from the actual importer and project configuration when answering project-specific questions.
4. Keep authoritative facts, diagnostics, enrichment, and heuristics visibly distinct.
5. Bound filesystem, archive, network, memory, worker, and output consumption.
6. Treat MCP as a transport, not the domain architecture.

Architecture at a Glance

CLI ───────┐
           ├── application service ── canonical snapshots and evidence
MCP ───────┘              │
                          ├── workspace and resolution engines
                          ├── TypeScript symbol and usage engines
                          ├── semantic API diff
                          └── isolated provider adapters
                              ├── pacote
                              ├── publint
                              ├── @arethetypeswrong/core
                              └── optional external enrichment

See Architecture, Security model, and Roadmap for the current design.

Repository Layout

apps/       Thin CLI and MCP process/transport packages
packages/   Domain contracts, engines, providers, and worker adapters
fixtures/   Deterministic compatibility and adversarial package fixtures
docs/       Product, architecture, decisions, research, and handoff context

Current Phase

The repository is at the boundary between architecture and implementation:

• the product brief, architecture, security model, roadmap, and five foundation ADRs are established;
• Node 22.22.1, pnpm 10.23.0, strict TypeScript, Biome, Vitest, and CI are configured;
• the GitHub remote, main default branch, initial commit, and clean-clone check are established;
• versioned result envelopes and the first-slice resource/fixture policy are accepted in ADRs 0003 and 0004;
• packages/contracts implements the installed-package v1 request/result schemas, schema-derived types, normalized validators, and first-slice resource vocabulary;
• golden and adversarial contract tests prove the current serialized boundary;
• packages/test-fixtures provides inert npm, pnpm, workspace-link, and generated security cases;
• packages/package-snapshot enforces approved/artifact-root containment, bounded descriptor reads, normalized manifests, and deterministic in-memory content identity without executing package code;
• packages/workspace-model validates safe package specifiers, discovers npm/pnpm importer and configuration context, and selects the exact importer-nearest installed or linked package root;
• packages/node-resolution resolves Node 22 export maps and legacy runtime targets from immutable snapshots under explicit import/require conditions, with bounded traces and no package execution;
• packages/typescript-resolution uses the pinned TypeScript 6 compiler to resolve declaration targets under Node16/NodeNext project configuration without ambient filesystem access;
• packages/worker-typescript runs that compiler in a bounded child and brokers immutable snapshot bytes plus memoized, contained workspace metadata for npm, pnpm, and linked packages;
• application composition and TypeScript public-symbol modeling remain planned;
• package scope, license, release intent, and supported platform matrix remain open.

The next implementation task is compiler-backed public TypeScript API modeling from the selected declaration target. The broader delivery target remains an installed-package CLI investigation: from an approved workspace, importer, and package specifier, identify the exact artifact, runtime target, declaration target, and public API with bounded evidence and without executing package code.

See the initial implementation plan for task order, acceptance criteria, decision checkpoints, and milestone gates.

Development Setup

Requirements:

• Node.js 22.22.1 or newer within Node 22
• pnpm 10.23.0

corepack enable
pnpm install
pnpm check

Common commands:

pnpm format
pnpm lint
pnpm typecheck
pnpm test
pnpm build

Documentation

• Product brief
• Architecture
• Security model
• Roadmap
• Initial implementation plan
• Current handoff
• Architecture decisions
• Initial ecosystem research

Relationship to inspect-node-package-api

The lightweight inspect-node-package-api skill in AI Central remains the small, dependency-free installed-package inspector. Package Spelunker is a separate product for importer-aware semantic analysis, registry snapshots, diagnostics, API comparison, and local usage impact. AI Central can eventually provide a thin skill that teaches agents when to use this CLI or MCP server.

License

No public license has been selected. The package is currently private and marked UNLICENSED.