{"_id":"@arch-engine/adapter-yarn-pnp","name":"@arch-engine/adapter-yarn-pnp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@arch-engine/adapter-yarn-pnp","version":"0.1.0","description":"Safe, package.json-shape-based workspace topology extraction adapter for Yarn Berry / Plug'n'Play repositories. Does not execute .pnp.cjs.","license":"MIT","type":"module","sideEffects":false,"repository":{"type":"git","url":"git+https://github.com/tharcyn/arch-engine.git","directory":"packages/adapter-yarn-pnp"},"homepage":"https://github.com/tharcyn/arch-engine","bugs":{"url":"https://github.com/tharcyn/arch-engine/issues"},"keywords":["adapter","yarn","yarn-berry","yarn-pnp","pnp","plug-n-play","monorepo","workspace","topology","extraction","arch-engine"],"engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"main":"./dist/index.js","types":"./dist/index.d.ts","scripts":{"build":"tsup && tsc --emitDeclarationOnly --declaration --outDir dist -p tsconfig.json"},"devDependencies":{"tsup":"^8.0.0","typescript":"^5.0.0"},"gitHead":"bc4dec8b5217ec260e7955a36aacc5609f67923c","_id":"@arch-engine/adapter-yarn-pnp@0.1.0","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-CkxKloPNhPvw9Bw8jD0P0XuvL6JbK7uHGZf8uwjyYMBAuGg0xyN48SQOB4epxLMbnXp3j7sNIgwjNY26ba62TQ==","shasum":"72a990e4a6ab18da4dd508aeb9a24030f10842a7","tarball":"https://registry.npmjs.org/@arch-engine/adapter-yarn-pnp/-/adapter-yarn-pnp-0.1.0.tgz","fileCount":8,"unpackedSize":60474,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICgdFeL0rpIqLDRNGq3E+xv/eYoPl7DK4X1nXA+xC8iBAiA+dBVy9EM53st6N65FYenZlHJTxQvbqUJWljoKRrydIA=="}]},"_npmUser":{"name":"tharcyn","email":"thaasyn@gmail.com"},"directories":{},"maintainers":[{"name":"tharcyn","email":"thaasyn@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/adapter-yarn-pnp_0.1.0_1778659760341_0.8757925415153376"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-13T08:09:20.235Z","0.1.0":"2026-05-13T08:09:20.525Z","modified":"2026-05-13T08:09:20.752Z"},"maintainers":[{"name":"tharcyn","email":"thaasyn@gmail.com"}],"description":"Safe, package.json-shape-based workspace topology extraction adapter for Yarn Berry / Plug'n'Play repositories. Does not execute .pnp.cjs.","homepage":"https://github.com/tharcyn/arch-engine","keywords":["adapter","yarn","yarn-berry","yarn-pnp","pnp","plug-n-play","monorepo","workspace","topology","extraction","arch-engine"],"repository":{"type":"git","url":"git+https://github.com/tharcyn/arch-engine.git","directory":"packages/adapter-yarn-pnp"},"bugs":{"url":"https://github.com/tharcyn/arch-engine/issues"},"license":"MIT","readme":"# @arch-engine/adapter-yarn-pnp\n\nSafe, deterministic workspace-topology extraction adapter for Yarn Berry / Plug'n'Play (PnP) repositories.\n\n## Purpose\n\nThis package teaches Arch-Engine to recognise Yarn Berry workspaces that ship with `.pnp.cjs` or `.pnp.loader.mjs`. It conforms to the internal `ArchitectureAdapter` contract introduced in Pass 1 (`docs/adapters/multi-adapter-surface-spec.md` §6).\n\nThe CLI's adapter registry consumes the adapter structurally — this package has no runtime dependency on `@arch-engine/cli`.\n\n## Installation\n\n```bash\nnpm install --save-dev @arch-engine/cli @arch-engine/adapter-yarn-pnp\n```\n\nThe CLI dynamically resolves this package at runtime when `.pnp.cjs` or `.pnp.loader.mjs` is present at the repository root. When it is not installed, the CLI falls back to `@arch-engine/adapter-monorepo` (which handles `package.json#workspaces` as a plain yarn-classic workspace).\n\n## MVP scope (v0.1.0)\n\nThe v0.1.0 release is a **safe, package.json-shape extractor** — no PnP runtime parity. Specifically:\n\n- **Detection** keys off file presence only:\n  - `.pnp.cjs` — yarn-berry default\n  - `.pnp.loader.mjs` — yarn-berry esm loader\n  - `.yarnrc.yml` — optionally parsed for `nodeLinker: pnp`\n- **Topology extraction** reads `package.json#workspaces` and the workspace package `package.json` files. Supported `workspaces` shapes:\n  - Array form: `\"workspaces\": [\"packages/*\", \"apps/*\"]`\n  - Object form: `\"workspaces\": { \"packages\": [\"packages/*\"] }`\n- **Dependency protocols** classified into `workspace`, `portal`, `link`, or `semver`:\n  - `workspace:*`, `workspace:^`, `workspace:~`, `workspace:<version>` — resolved as internal workspace edges.\n  - `portal:<path>` / `link:<path>` — resolved as internal edges *only* when the target path is a known workspace package; otherwise the dependency is treated as external and `ARCH_ENGINE_PNP_RESOLUTION_DEFERRED` is surfaced.\n  - Anything else (`^1.0.0`, etc.) is treated as opaque semver and does not materialise into an internal edge.\n- `ARCH_ENGINE_PNP_RESOLUTION_DEFERRED` is **always** emitted (INFO severity) whenever a PnP file is present. The diagnostic explains that the v0.1.0 adapter intentionally does not execute `.pnp.cjs` for resolver parity. The diagnostic does not block extraction and does not affect exit codes.\n\n## Determinism / safety invariants\n\nThe v0.1.0 adapter **never**:\n\n- executes `.pnp.cjs` or `.pnp.loader.mjs` (no `require()`, no `import()`)\n- invokes `yarn` or any other package-manager binary\n- opens network sockets\n- reads `node_modules/`, `.yarn/cache`, `.yarn/unplugged`, or `.yarn/install-state.gz`\n- mutates the user's repository\n- emits absolute paths or wall-clock-derived data\n\nThese properties are pinned by tests under `tests/yarn-pnp-adapter.test.ts` and in the CLI's `packages/cli/tests/adapters/` suite.\n\n## JSON v2 metadata shape\n\nWhen the CLI selects this adapter, the JSON v2 `data.adapter` block carries:\n\n```jsonc\n{\n  \"name\": \"@arch-engine/adapter-yarn-pnp\",\n  \"version\": \"0.1.0\",\n  \"packageManager\": \"yarn\",\n  \"workspaceKind\": \"yarn-pnp\",\n  \"confidence\": \"HIGH\",\n  \"reasons\": [\n    \".pnp.cjs present\",\n    \".yarnrc.yml present\",\n    \".yarnrc.yml#nodeLinker is pnp\",\n    \"package.json#packageManager identifies yarn\",\n    \"package.json#workspaces is set\"\n  ],\n  \"warnings\": [],\n  \"alsoDetected\": [],\n  \"metadata\": {\n    \"yarnPnp\": {\n      \"packageManagerVersion\": \"4.0.2\",\n      \"pnpFilePresent\": true,\n      \"pnpLoaderPresent\": false,\n      \"yarnrcPresent\": true,\n      \"nodeLinker\": \"pnp\",\n      \"workspacesPresent\": true,\n      \"workspacesObjectForm\": false,\n      \"rawGlobs\": [\"apps/*\", \"packages/*\"],\n      \"excludedGlobs\": [],\n      \"matchedGlobs\": [\"apps/api\", \"apps/web\", \"packages/shared\"]\n    },\n    \"edges\": {\n      \"e_<hex8>\": { \"kind\": \"dependency\", \"protocol\": \"workspace\" }\n    }\n  }\n}\n```\n\n`packageManagerVersion` is always present:\n- the bare version string when `package.json#packageManager` is `yarn@<x.y.z>` (Corepack `+<sha>` integrity suffix is stripped)\n- `null` when the field is absent or does not identify yarn\n\n## Known limitations\n\n- No full PnP resolver. External `node:` requires that go through `.pnp.cjs` at runtime are not modelled.\n- No `nohoist` semantics (PnP makes hoisting moot anyway).\n- No brace expansion (`{a,b}`) or `**` globs.\n- Catalog-style `catalog:` / `catalogs:` protocols are pnpm-specific and ignored here.\n\nThese deferrals are intentional and tested. Future minor releases may extend support without breaking the v0.1.0 metadata shape.\n\n## Adapter precedence\n\n| # | Adapter | Wins when |\n| --- | --- | --- |\n| 2 | `@arch-engine/adapter-pnpm` | `pnpm-workspace.yaml` is present |\n| 3 | `@arch-engine/adapter-yarn-pnp` | `.pnp.cjs` or `.pnp.loader.mjs` is present (and no `pnpm-workspace.yaml`) |\n| 4 | `@arch-engine/adapter-monorepo` | Fallback — npm/yarn-classic workspaces, single-package, or one of the above when the dedicated adapter isn't installed |\n\nThe cache-hint protocol documented in `docs/adapters/multi-adapter-surface-spec.md` §11.4 prevents conflict diagnostics when more than one adapter could plausibly claim a repository.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-a04de68c10c1ba027acebbcbfa3134f1"}