feat(please-plugins): add monorepo workspace dependency scanning (#133)

amondnet · web-flow · commit 3d824e104082 · 2026-03-29T16:53:17.000+09:00
* docs(track): add setup-monorepo-scan-20260329 * chore(track): setup-monorepo-scan-20260329 start implementation * feat(please-plugins): add monorepo workspace dependency scanning Add resolveWorkspacePackages() and collectAllDependencies() to scan workspace package.json files in monorepos. Supports npm/yarn/Bun workspaces field and pnpm-workspace.yaml. Integrates into both scanForSetup() and detectForEvent() with workspace-aware source tracking (e.g., "apps/web: @nuxt/ui"). Closes #132 * refactor(please-plugins): extract workspace resolver to separate module Move resolveWorkspacePackages, collectAllDependencies, and resolveGlobPatterns to workspace-resolver.ts to keep check-dependencies.ts under 500 LOC guideline. * docs(track): add retrospective for setup-monorepo-scan-20260329 * chore: apply AI code review suggestions - Replace custom glob resolver with Bun.Glob for accurate multi-segment pattern matching (fixes patterns like "apps/*/src" truncation bug) - Deduplicate resolved workspace paths to avoid duplicate entries when npm workspaces and pnpm-workspace.yaml share the same patterns - Improve pnpm-workspace.yaml parsing to handle inline comments and more robust top-level key detection - Tighten test assertions for deduplication (exact length 1) and negation patterns (exact length 2 with both expected dirs)
diff --git a/.please/docs/tracks/active/setup-monorepo-scan-20260329/metadata.json b/.please/docs/tracks/active/setup-monorepo-scan-20260329/metadata.json
@@ -0,0 +1,10 @@
+{
+  "track_id": "setup-monorepo-scan-20260329",
+  "type": "feature",
+  "status": "in_progress",
+  "created_at": "2026-03-29T16:03:23+09:00",
+  "updated_at": "2026-03-29T16:06:00+09:00",
+  "issue": "#132",
+  "pr": "",
+  "project": ""
+}
diff --git a/.please/docs/tracks/active/setup-monorepo-scan-20260329/plan.md b/.please/docs/tracks/active/setup-monorepo-scan-20260329/plan.md
@@ -0,0 +1,112 @@
+# Plan: Monorepo Workspace Dependency Scanning
+
+> Track: setup-monorepo-scan-20260329
+> Spec: [spec.md](./spec.md)
+
+## Overview
+
+- **Source**: [spec.md](./spec.md)
+- **Issue**: #132
+- **Created**: 2026-03-29
+- **Approach**: Pragmatic
+
+## Purpose
+
+After this change, users running `/please-plugins:setup` in a monorepo project will see plugin recommendations based on dependencies from all workspace packages, not just the root. They can verify it works by running the setup command in a monorepo and confirming that dependencies from sub-packages (e.g., `apps/web/package.json`) trigger the correct plugin recommendations.
+
+## Context
+
+The `check-dependencies.ts` hook currently reads only the root `package.json` to detect dependencies that match plugin mappings. In monorepo projects using npm/yarn/Bun workspaces or pnpm workspaces, the root `package.json` often contains only shared dev dependencies (e.g., `vitest`, `eslint`), while framework-specific packages (e.g., `@nuxt/ui`, `vue`, `prisma`) live in workspace packages like `apps/web/package.json` or `packages/api/package.json`.
+
+This means the plugin recommender misses most relevant plugins in monorepo setups. The fix requires resolving workspace package paths from the root configuration, reading each workspace `package.json`, and merging all dependencies before running detection.
+
+Key constraints:
+- Must support npm/yarn/Bun `workspaces` field (array of glob patterns) and `pnpm-workspace.yaml`
+- Must use synchronous fs + glob only (no child processes) to keep hook latency low
+- Must gracefully skip missing or malformed workspace `package.json` files
+- Must not break non-monorepo projects (backward compatible)
+
+Non-goals: nested workspace resolution, per-package detection reporting, Yarn PnP.
+
+## Architecture Decision
+
+The approach adds workspace resolution as a layer between `loadPackageJson()` and the existing detection functions. A new `resolveWorkspacePackages(cwd, rootPkg)` function resolves glob patterns from the `workspaces` field or `pnpm-workspace.yaml` into concrete directory paths. A new `collectAllDependencies(cwd)` function calls `loadPackageJson()` for each workspace package and merges all `dependencies` + `devDependencies` into a single record, tagging each entry with its source path for later source attribution.
+
+This is minimally invasive: `detectPackages()` continues to receive a flat deps record, `scanForSetup()` and `detectForEvent()` simply call `collectAllDependencies()` instead of `loadPackageJson()`. Source tracking is enhanced to show `apps/web: @nuxt/ui` when a dependency was found in a workspace package.
+
+Bun's built-in `Bun.Glob` provides synchronous, fast glob resolution without adding dependencies.
+
+## Tasks
+
+- [x] T001 Add workspace resolution function `resolveWorkspacePackages` (file: plugins/please-plugins/hooks/check-dependencies.ts)
+- [x] T002 Add dependency aggregation function `collectAllDependencies` (file: plugins/please-plugins/hooks/check-dependencies.ts) (depends on T001)
+- [x] T003 Integrate workspace scanning into `scanForSetup` and `detectForEvent` (file: plugins/please-plugins/hooks/check-dependencies.ts) (depends on T002)
+- [x] T004 Enhance source tracking for workspace-origin dependencies (file: plugins/please-plugins/hooks/check-dependencies.ts) (depends on T003)
+
+## Key Files
+
+### Modify
+
+- `plugins/please-plugins/hooks/check-dependencies.ts` — Main scanner; add `resolveWorkspacePackages()`, `collectAllDependencies()`, update `scanForSetup()`, `detectForEvent()`, `resolvePackageSource()`
+- `plugins/please-plugins/hooks/check-dependencies.test.ts` — Add tests for workspace resolution, aggregation, and integration
+
+### Reuse
+
+- `plugins/please-plugins/hooks/plugin-mappings.json` — Existing package-to-plugin mappings (unchanged)
+- `plugins/please-plugins/hooks/tooling-mappings.json` — Existing tooling mappings (unchanged)
+
+## Verification
+
+### Automated Tests
+
+- [ ] `resolveWorkspacePackages` resolves npm/yarn/Bun `workspaces` glob patterns to directory paths
+- [ ] `resolveWorkspacePackages` resolves `pnpm-workspace.yaml` patterns to directory paths
+- [ ] `resolveWorkspacePackages` returns empty array when no workspaces configured
+- [ ] `collectAllDependencies` merges deps from root + workspace packages
+- [ ] `collectAllDependencies` skips missing/malformed workspace package.json
+- [ ] `scanForSetup` detects plugins from workspace dependencies
+- [ ] `detectForEvent` (SessionStart) detects workspace dependencies
+- [ ] Source field shows workspace path prefix for workspace-origin deps
+- [ ] Non-monorepo projects continue to work unchanged
+
+### Observable Outcomes
+
+- Running `bun run plugins/please-plugins/hooks/check-dependencies.ts --setup` in this repo detects dependencies from `apps/web/package.json` (e.g., `@nuxt/ui`, `@nuxt/content`)
+- Running the same in a non-monorepo project produces identical output as before
+
+### Acceptance Criteria Check
+
+- [ ] AC-1: Dependencies from `apps/web/package.json` detected in a monorepo with `workspaces`
+- [ ] AC-2: Dependencies detected from `pnpm-workspace.yaml` projects
+- [ ] AC-3: SessionStart hook scans workspace packages
+- [ ] AC-4: `--setup` mode aggregates all workspace dependencies
+- [ ] AC-5: Non-monorepo projects unchanged
+
+## Decision Log
+
+- Decision: Use `Bun.Glob` for workspace pattern resolution
+  Rationale: Built-in, synchronous, no additional dependencies, fast
+  Date/Author: 2026-03-29 / Claude
+
+- Decision: Merge all workspace deps into a single flat record rather than per-package detection
+  Rationale: Simpler implementation, aligns with user preference from spec, `detectPackages()` API unchanged
+  Date/Author: 2026-03-29 / Claude
+
+## Outcomes & Retrospective
+
+### What Was Shipped
+- Workspace resolution for npm/yarn/Bun `workspaces` and `pnpm-workspace.yaml`
+- Dependency aggregation across all workspace packages
+- Workspace-aware source tracking (e.g., `apps/web: @nuxt/ui`)
+- Extracted `workspace-resolver.ts` module to maintain file size guideline
+
+### What Went Well
+- Existing test infrastructure made TDD straightforward
+- Clean extraction of workspace logic into separate module during review
+- All 62 tests passing with zero regressions
+
+### What Could Improve
+- Initial implementation exceeded 500 LOC guideline; caught during review phase
+
+### Tech Debt Created
+- None
diff --git a/.please/docs/tracks/active/setup-monorepo-scan-20260329/spec.md b/.please/docs/tracks/active/setup-monorepo-scan-20260329/spec.md
@@ -0,0 +1,43 @@
+# Monorepo Workspace Dependency Scanning for Setup Command
+
+> Track: setup-monorepo-scan-20260329
+
+## Overview
+
+Enhance the `please-plugins` dependency scanner (`check-dependencies.ts`) to discover and aggregate dependencies from all workspace packages in monorepo projects. Currently, only the root `package.json` is read, which misses dependencies declared in workspace packages (e.g., `apps/web/package.json`, `packages/shared/package.json`).
+
+## Requirements
+
+### Functional Requirements
+
+- [ ] FR-1: Resolve workspace package paths from the root `package.json` `workspaces` field (npm/yarn/Bun format — array of glob patterns)
+- [ ] FR-2: Resolve workspace package paths from `pnpm-workspace.yaml` (`packages` field — array of glob patterns)
+- [ ] FR-3: Read `package.json` from each resolved workspace directory and merge all `dependencies` + `devDependencies` into a single aggregated set
+- [ ] FR-4: Use the aggregated dependency set for plugin detection in both `scanForSetup()` and `detectForEvent()` (SessionStart hook)
+- [ ] FR-5: When a plugin is detected from a workspace package (not root), include the workspace path in the `source` field (e.g., `apps/web: @nuxt/ui`)
+
+### Non-functional Requirements
+
+- [ ] NFR-1: Workspace resolution must not significantly increase hook latency — use synchronous `fs` and `glob` only, no external processes
+- [ ] NFR-2: Gracefully handle missing or malformed workspace package.json files (skip with no error)
+
+## Acceptance Criteria
+
+- [ ] AC-1: In a monorepo with `workspaces: ["apps/*", "packages/*"]`, dependencies from `apps/web/package.json` are detected by the scanner
+- [ ] AC-2: In a monorepo with `pnpm-workspace.yaml`, workspace packages are resolved and scanned
+- [ ] AC-3: The SessionStart hook detects workspace dependencies, not just root dependencies
+- [ ] AC-4: The `--setup` mode aggregates all workspace dependencies for plugin detection
+- [ ] AC-5: Non-monorepo projects (no `workspaces` field, no `pnpm-workspace.yaml`) continue to work unchanged
+
+## Out of Scope
+
+- Nested workspace resolution (monorepo within a monorepo)
+- Per-package detection reporting (we merge all deps, not per-package)
+- Yarn PnP resolution or Yarn Berry-specific behaviors
+- Workspace dependency graph analysis
+
+## Assumptions
+
+- Glob resolution for workspace patterns uses `Bun.glob` or Node.js `glob` with synchronous API
+- The root `package.json` is always the entry point; workspace files are additive
+- Duplicate dependencies across workspaces are deduplicated naturally (merged into a single key set)
diff --git a/.please/docs/tracks/index.md b/.please/docs/tracks/index.md
@@ -12,6 +12,7 @@
 | [hooks-if-field-20260328](active/hooks-if-field-20260328/) | Add `if` field to hooks | feature | — | 2026-03-28 | planned |
 | [web-nuxt-update-20260328](active/web-nuxt-update-20260328/plan.md) | Web App Dependency Update | chore | #126 | 2026-03-28 | in_progress |
 | [fix-setup-glob-pattern-20260329](active/fix-setup-glob-pattern-20260329/plan.md) | Fix setup command package.json discovery | bugfix | #129 | 2026-03-29 | in_progress |
+| [setup-monorepo-scan-20260329](active/setup-monorepo-scan-20260329/plan.md) | Monorepo Workspace Dependency Scanning | feature | #132 | 2026-03-29 | in_progress |
 
 ## Recently Completed
 
diff --git a/plugins/please-plugins/hooks/check-dependencies.test.ts b/plugins/please-plugins/hooks/check-dependencies.test.ts
@@ -4,10 +4,12 @@ import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import {
   buildOutput,
+  collectAllDependencies,
   detectPackages,
   detectTooling,
   extractPackagesFromCommand,
   filterInstalledPlugins,
+  resolveWorkspacePackages,
   scanForSetup,
   type DetectedPlugin,
   type PluginMapping,
@@ -381,4 +383,207 @@ describe('scanForSetup', () => {
     const pnpmResults = result.detected.filter(d => d.pluginName === 'pnpm')
     expect(pnpmResults).toHaveLength(1)
   })
+
+  test('detects plugins from workspace packages', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'setup-'))
+    // Root package.json with workspaces but no matching deps
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({
+      workspaces: ['apps/*'],
+      devDependencies: { 'typescript': '^5.0.0' },
+    }))
+    // Workspace package with matching deps
+    mkdirSync(join(dir, 'apps', 'web'), { recursive: true })
+    writeFileSync(join(dir, 'apps', 'web', 'package.json'), JSON.stringify({
+      dependencies: { '@nuxt/ui': '^3.0.0' },
+    }))
+    const result = scanForSetup(dir)
+    expect(result.detected).toContainEqual({ pluginName: 'nuxt-ui', source: 'apps/web: @nuxt/ui' })
+  })
+
+  test('detects plugins from pnpm workspace packages', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'setup-'))
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'root' }))
+    writeFileSync(join(dir, 'pnpm-workspace.yaml'), 'packages:\n  - "packages/*"\n')
+    mkdirSync(join(dir, 'packages', 'api'), { recursive: true })
+    writeFileSync(join(dir, 'packages', 'api', 'package.json'), JSON.stringify({
+      dependencies: { '@prisma/client': '^5.0.0' },
+    }))
+    const result = scanForSetup(dir)
+    expect(result.detected).toContainEqual({ pluginName: 'prisma', source: 'packages/api: @prisma/client' })
+  })
+
+  test('merges root and workspace deps without duplicates', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'setup-'))
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({
+      workspaces: ['apps/*'],
+      devDependencies: { 'vitest': '^4.0.0' },
+    }))
+    mkdirSync(join(dir, 'apps', 'web'), { recursive: true })
+    writeFileSync(join(dir, 'apps', 'web', 'package.json'), JSON.stringify({
+      dependencies: { '@nuxt/ui': '^3.0.0', 'vitest': '^4.0.0' },
+    }))
+    const result = scanForSetup(dir)
+    const pluginNames = result.detected.map(d => d.pluginName)
+    // vitest detected from root (no workspace prefix), nuxt-ui from workspace
+    expect(pluginNames).toContain('vitest')
+    expect(pluginNames).toContain('nuxt-ui')
+    const vitestResult = result.detected.find(d => d.pluginName === 'vitest')
+    expect(vitestResult?.source).toBe('vitest') // root, no prefix
+  })
+})
+
+describe('resolveWorkspacePackages', () => {
+  test('resolves npm workspaces glob patterns', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ws-'))
+    const pkg = { workspaces: ['apps/*', 'packages/*'] }
+    mkdirSync(join(dir, 'apps', 'web'), { recursive: true })
+    writeFileSync(join(dir, 'apps', 'web', 'package.json'), '{}')
+    mkdirSync(join(dir, 'packages', 'shared'), { recursive: true })
+    writeFileSync(join(dir, 'packages', 'shared', 'package.json'), '{}')
+    const result = resolveWorkspacePackages(dir, pkg)
+    expect(result).toHaveLength(2)
+    expect(result).toContainEqual(join(dir, 'apps', 'web'))
+    expect(result).toContainEqual(join(dir, 'packages', 'shared'))
+  })
+
+  test('resolves pnpm-workspace.yaml patterns', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ws-'))
+    writeFileSync(join(dir, 'pnpm-workspace.yaml'), 'packages:\n  - "apps/*"\n  - "packages/*"\n')
+    mkdirSync(join(dir, 'apps', 'web'), { recursive: true })
+    writeFileSync(join(dir, 'apps', 'web', 'package.json'), '{}')
+    const result = resolveWorkspacePackages(dir, null)
+    expect(result).toHaveLength(1)
+    expect(result).toContainEqual(join(dir, 'apps', 'web'))
+  })
+
+  test('returns empty array when no workspaces configured', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ws-'))
+    const result = resolveWorkspacePackages(dir, { name: 'test' })
+    expect(result).toHaveLength(0)
+  })
+
+  test('skips directories without package.json', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ws-'))
+    const pkg = { workspaces: ['apps/*'] }
+    mkdirSync(join(dir, 'apps', 'web'), { recursive: true })
+    // No package.json in apps/web
+    mkdirSync(join(dir, 'apps', 'api'), { recursive: true })
+    writeFileSync(join(dir, 'apps', 'api', 'package.json'), '{}')
+    const result = resolveWorkspacePackages(dir, pkg)
+    expect(result).toHaveLength(1)
+    expect(result).toContainEqual(join(dir, 'apps', 'api'))
+  })
+
+  test('handles yarn workspaces { packages: [...] } format', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ws-'))
+    const pkg = { workspaces: { packages: ['apps/*'] } }
+    mkdirSync(join(dir, 'apps', 'web'), { recursive: true })
+    writeFileSync(join(dir, 'apps', 'web', 'package.json'), '{}')
+    const result = resolveWorkspacePackages(dir, pkg)
+    expect(result).toHaveLength(1)
+  })
+
+  test('merges npm workspaces and pnpm-workspace.yaml without duplicates', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ws-'))
+    const pkg = { workspaces: ['apps/*'] }
+    writeFileSync(join(dir, 'pnpm-workspace.yaml'), 'packages:\n  - "apps/*"\n')
+    mkdirSync(join(dir, 'apps', 'web'), { recursive: true })
+    writeFileSync(join(dir, 'apps', 'web', 'package.json'), '{}')
+    const result = resolveWorkspacePackages(dir, pkg)
+    // Both sources resolve to the same directory; deduplication ensures exactly one entry
+    expect(result).toHaveLength(1)
+    expect(result).toContainEqual(join(dir, 'apps', 'web'))
+  })
+
+  test('handles exact directory paths (no globs)', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ws-'))
+    const pkg = { workspaces: ['tools/cli'] }
+    mkdirSync(join(dir, 'tools', 'cli'), { recursive: true })
+    writeFileSync(join(dir, 'tools', 'cli', 'package.json'), '{}')
+    const result = resolveWorkspacePackages(dir, pkg)
+    expect(result).toHaveLength(1)
+    expect(result).toContainEqual(join(dir, 'tools', 'cli'))
+  })
+
+  test('skips negation patterns', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ws-'))
+    const pkg = { workspaces: ['packages/*', '!packages/internal'] }
+    mkdirSync(join(dir, 'packages', 'shared'), { recursive: true })
+    writeFileSync(join(dir, 'packages', 'shared', 'package.json'), '{}')
+    mkdirSync(join(dir, 'packages', 'internal'), { recursive: true })
+    writeFileSync(join(dir, 'packages', 'internal', 'package.json'), '{}')
+    const result = resolveWorkspacePackages(dir, pkg)
+    // Negation patterns are skipped (not filtered), so internal still appears from "packages/*"
+    // This is a known limitation — true negation filtering is out of scope
+    // Both shared and internal match the "packages/*" glob, so we expect exactly 2 results
+    expect(result).toHaveLength(2)
+    expect(result).toContainEqual(join(dir, 'packages', 'shared'))
+    expect(result).toContainEqual(join(dir, 'packages', 'internal'))
+  })
+})
+
+describe('collectAllDependencies', () => {
+  test('merges root and workspace deps', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'collect-'))
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({
+      workspaces: ['apps/*'],
+      dependencies: { 'express': '^4.0.0' },
+    }))
+    mkdirSync(join(dir, 'apps', 'web'), { recursive: true })
+    writeFileSync(join(dir, 'apps', 'web', 'package.json'), JSON.stringify({
+      dependencies: { '@nuxt/ui': '^3.0.0' },
+    }))
+    const result = collectAllDependencies(dir)
+    expect(result.deps).toHaveProperty('express')
+    expect(result.deps).toHaveProperty('@nuxt/ui')
+    expect(result.sources).not.toHaveProperty('express') // root dep, no source entry
+    expect(result.sources['@nuxt/ui']).toBe('apps/web')
+  })
+
+  test('root deps take priority over workspace deps', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'collect-'))
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({
+      workspaces: ['apps/*'],
+      devDependencies: { 'vitest': '^4.0.0' },
+    }))
+    mkdirSync(join(dir, 'apps', 'web'), { recursive: true })
+    writeFileSync(join(dir, 'apps', 'web', 'package.json'), JSON.stringify({
+      devDependencies: { 'vitest': '^3.0.0' },
+    }))
+    const result = collectAllDependencies(dir)
+    expect(result.deps['vitest']).toBe('^4.0.0') // root version wins
+    expect(result.sources).not.toHaveProperty('vitest') // no workspace source for root dep
+  })
+
+  test('skips malformed workspace package.json', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'collect-'))
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({
+      workspaces: ['apps/*'],
+    }))
+    mkdirSync(join(dir, 'apps', 'broken'), { recursive: true })
+    writeFileSync(join(dir, 'apps', 'broken', 'package.json'), 'not valid json')
+    mkdirSync(join(dir, 'apps', 'good'), { recursive: true })
+    writeFileSync(join(dir, 'apps', 'good', 'package.json'), JSON.stringify({
+      dependencies: { 'pinia': '^2.0.0' },
+    }))
+    const result = collectAllDependencies(dir)
+    expect(result.deps).toHaveProperty('pinia')
+  })
+
+  test('returns empty deps when no package.json', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'collect-'))
+    const result = collectAllDependencies(dir)
+    expect(Object.keys(result.deps)).toHaveLength(0)
+    expect(Object.keys(result.sources)).toHaveLength(0)
+  })
+
+  test('works with non-monorepo (no workspaces)', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'collect-'))
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({
+      dependencies: { 'express': '^4.0.0' },
+    }))
+    const result = collectAllDependencies(dir)
+    expect(result.deps).toHaveProperty('express')
+    expect(Object.keys(result.sources)).toHaveLength(0)
+  })
 })
diff --git a/plugins/please-plugins/hooks/check-dependencies.ts b/plugins/please-plugins/hooks/check-dependencies.ts
diff --git a/plugins/please-plugins/hooks/workspace-resolver.ts b/plugins/please-plugins/hooks/workspace-resolver.ts
