fix: skip framework build caches in archetype detection

[PrzemekGalarowicz]

Summary

• Archetype file-tree walk now skips framework/build/deploy caches (.next, out, coverage, .turbo, .vercel, .nuxt, .svelte-kit, .astro, .cache, .parcel-cache, storybook-static) so a large cache cannot exhaust the walk budget and hide real source (e.g. .next sorting before src and detecting as lib instead of spa).
• Skipped dirs still cost zero budget (continue before budget -= 1); failure mode is a lost signal only, never a false one.
• Pins every SKIP_DIRS member for skip behavior (including case-insensitive) and classification neutrality; updates docs/commands/init.md and CHANGELOG.md.

Test plan

• npm test — especially tests/detect-archetype.test.ts
• Confirm a project with a large .next/ and src/App.tsx (no framework dep in package.json) detects as spa, not lib
• Confirm existing skips (node_modules, .git, dist, build) still work
• Skim CI gates (format, lint, typecheck, test, build)

Made with Cursor

Summary by CodeRabbit

• New Features

  • Expanded archetype detection to skip additional framework, build, cache, deployment, coverage, and dependency directories.
  • Skipped directories no longer consume the traversal budget, helping source files remain discoverable.
  • Directory matching now handles case variations consistently.

• Documentation

  • Updated the changelog and initialization documentation to describe excluded directories and detection tradeoffs.

• Tests

  • Added coverage confirming skipped directories and their contents are ignored while equivalent files elsewhere remain detectable.
  • Verification and regression checks passed.

[coderabbitai]

📝 Walkthrough

Walkthrough

The archetype detector now skips fifteen cache and build directories before classification and budget accounting. Tests cover neutrality, nested paths, positive controls, and case-insensitive names. Documentation and verification artifacts describe the behavior and recorded gate results.

Changes

Framework cache skip detection

Layer / File(s)	Summary
Skip-set contract and detection behavior .dev/features/detect-skip-framework-caches/PLAN.md, src/lib/detect-archetype.ts	The plan defines the expanded ReadonlySet<string> contract. SKIP_DIRS is exported and skipped before traversal-budget accounting.
Classification neutrality tests tests/detect-archetype.test.ts	Tests cover every configured directory across path contexts, ignored signals inside skipped directories, equivalent files outside them, and case-insensitive names.
Documentation and verification records .dev/features/detect-skip-framework-caches/*, .pharn/*, CHANGELOG.md, docs/commands/init.md	Documentation lists the excluded directory classes. Reports record review, regression, verification, ship, and scope results.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• pharn-dev/pharn-cli#21: Extends the same SKIP_DIRS file-tree exclusion behavior.
• pharn-dev/pharn-cli#30: Extends archetype detection and classifyEntry skip-path neutrality.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: skipping framework build caches during archetype detection.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/skip-framework-build-caches

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

tests/detect-archetype.test.ts (1)

560-595: 🚀 Performance & Scalability | 🔵 Trivial | 🏗️ Heavy lift

Pin the zero-budget behavior in CI.

The tests verify classification neutrality, but they do not verify that skipped directories avoid budget -= 1. They would pass if the decrement moved before the skip, even though that would reintroduce the bounded-walk regression. Add a focused test with a mocked directory listing or a narrow test-only budget seam.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/detect-archetype.test.ts` around lines 560 - 595, Add a focused test
for the skipped-directory traversal in detectArchetypesFromProject that
constrains the walk budget and mocks or otherwise controls directory listings,
asserting skipped entries do not consume budget and traversal still reaches the
intended signal. Keep the existing classification tests unchanged and use the
narrowest test-only budget seam available.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/commands/init.md`:
- Line 86: Update the documentation around the detected-tree walk to state that
directory matching is case-insensitive and that the zero-cost/zero-budget
guarantee applies only to the explicitly listed skipped directories; clarify
that unlisted caches may consume the bounded walk budget. Ensure the documented
behavior matches the implementation, marking any unsupported behavior as Coming
soon or linking to docs/roadmap.md.

---

Nitpick comments:
In `@tests/detect-archetype.test.ts`:
- Around line 560-595: Add a focused test for the skipped-directory traversal in
detectArchetypesFromProject that constrains the walk budget and mocks or
otherwise controls directory listings, asserting skipped entries do not consume
budget and traversal still reaches the intended signal. Keep the existing
classification tests unchanged and use the narrowest test-only budget seam
available.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0fae1f48-ac3e-44a5-87ea-477002165378

📥 Commits

Reviewing files that changed from the base of the PR and between 4d24ad4 and 6851c3b.

📒 Files selected for processing (15)

• .dev/features/detect-skip-framework-caches/GRILL.md
• .dev/features/detect-skip-framework-caches/PLAN.md
• .dev/features/detect-skip-framework-caches/REGRESSION.md
• .dev/features/detect-skip-framework-caches/REVIEW.md
• .dev/features/detect-skip-framework-caches/SHIP.md
• .dev/features/detect-skip-framework-caches/VERIFY.md
• .dev/features/detect-skip-framework-caches/regression-report.json
• .dev/features/detect-skip-framework-caches/verify-report.json
• .pharn/pharn-dev-regress/base-results.json
• .pharn/pharn-dev-regress/head-results.json
• .pharn/writes-scope.json
• CHANGELOG.md
• docs/commands/init.md
• src/lib/detect-archetype.ts
• tests/detect-archetype.test.ts

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Scope and complete the documented skip contract.

Line 86 should state that directory matching is case-insensitive. It should also limit the zero-budget guarantee to the listed directories, because an unlisted cache can still consume the bounded walk budget.

As per coding guidelines, docs/**/*.md must keep user-facing documentation synchronized with code; undocumented or unimplemented behavior must be marked Coming soon or linked to docs/roadmap.md.

Proposed wording

- skipping dependencies, VCS metadata, and build/deploy caches —
+ skipping dependencies, VCS metadata, and build/deploy caches (matched case-insensitively) —
- Skipping those trees costs the walk nothing, so a large framework cache cannot exhaust its bound
+ Skipping these listed directories before budget accounting costs no walk budget, so a large cache inside one of them cannot exhaust the bound

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

Reads `package.json` dependency names and walks the project tree (bounded and symlink-safe, skipping dependencies, VCS metadata, and build/deploy caches — `node_modules`, `.git`, `dist`, `build`, `out`, `coverage`, `storybook-static`, `.next`, `.nuxt`, `.svelte-kit`, `.astro`, `.turbo`, `.vercel`, `.cache`, `.parcel-cache`) for structural signals, then reduces both to an `Archetype[]`. Skipping those trees costs the walk nothing, so a large framework cache cannot exhaust its bound and hide your real source; the tradeoff is that a signal file you hand-authored inside one of those directories is not seen. The detected set is shown in a "Detected archetypes" note. Only names are tested against fixed in-code allowlists — no discovered file body is read (other than `package.json`) and no untrusted value is executed, interpolated, or logged.

Reads `package.json` dependency names and walks the project tree (bounded and symlink-safe, skipping dependencies, VCS metadata, and build/deploy caches (matched case-insensitively) — `node_modules`, `.git`, `dist`, `build`, `out`, `coverage`, `storybook-static`, `.next`, `.nuxt`, `.svelte-kit`, `.astro`, `.turbo`, `.vercel`, `.cache`, `.parcel-cache`) for structural signals, then reduces both to an `Archetype[]`. Skipping these listed directories before budget accounting costs no walk budget, so a large cache inside one of them cannot exhaust the bound and hide your real source; the tradeoff is that a signal file you hand-authored inside one of those directories is not seen. The detected set is shown in a "Detected archetypes" note. Only names are tested against fixed in-code allowlists — no discovered file body is read (other than `package.json`) and no untrusted value is executed, interpolated, or logged.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/commands/init.md` at line 86, Update the documentation around the
detected-tree walk to state that directory matching is case-insensitive and that
the zero-cost/zero-budget guarantee applies only to the explicitly listed
skipped directories; clarify that unlisted caches may consume the bounded walk
budget. Ensure the documented behavior matches the implementation, marking any
unsupported behavior as Coming soon or linking to docs/roadmap.md.

Source: Coding guidelines