feat(recipes): unimported-exports (research note § 1.2)

[SutuSebastian]

Summary

Ships unimported-exports recipe from research note § 1.2 — third bundled recipe from the capability inventory. XS effort, ships against existing substrate (exports, imports, imports.resolved_path, imports.specifiers JSON).

What it does

Surfaces exports that have no detectable import. Useful as a starting candidate list for "what's unused?" — explicitly NOT a "safe to delete" list.

WITH direct_uses AS (
  SELECT DISTINCT e.id FROM exports e
  JOIN imports i ON i.resolved_path = e.file_path
  CROSS JOIN json_each(i.specifiers) j
  WHERE j.value = e.name OR j.value = '*'
)
SELECT e.name, e.kind, e.file_path, e.is_default, e.re_export_source
FROM exports e
WHERE e.id NOT IN (SELECT id FROM direct_uses)
  AND e.is_default = 0
  AND e.kind != 're-export'
ORDER BY e.file_path, e.name
LIMIT 50

Action template: review-for-deletion (auto_fixable: false).

V1 limitations (documented in recipe .md)

Three known false-positive classes spelled out so agents don't blindly trust the output:

1. Re-export chains NOT followed — if src/index.ts re-exports bar from src/bar.ts and consumers import { bar } from '~/' (hitting the barrel), the recipe falsely flags bar in src/bar.ts. Tracked under research note § 1.2 caveat — future recipe with recursive CTE walking re_export_source closes the gap.
2. Unresolved imports ignored — imports.resolved_path IS NULL (tsconfig path aliases the resolver couldn't resolve, or external packages) — those rows don't count toward "used" matching. Codemap's resolver covers most TS/JS shapes; corner case for unusual config.
3. Default exports skipped — common framework entry points (Next.js page.tsx, Storybook stories, vite.config.ts) skipped to reduce noise. Drop the AND e.is_default = 0 clause in a project-local override to include them.

Doc-governance compliance

• Rule 10 lockstep — both templates/agents/ AND .agents/ codemap rule + skill gain a trigger-pattern row, quick-reference row, and recipe-id list update.
• Recipe-as-content registry (PR feat(recipes): recipes-as-content registry — bundled .md + project-local .codemap/recipes/ #37) — recipe ships as <id>.{sql,md} file pair; .md carries action template via YAML frontmatter + caveats / tuning axes in the body.
• Patch changeset — pre-v1 lesson; additive bundled recipe; no schema bump.

Test plan

• bun run check passes — format, lint, typecheck, all 23 golden queries
• Recipe loads cleanly via --recipes-json
• No regressions in existing recipes (golden queries all green)
• CodeRabbit review

Out of scope

• Re-export chain handling (recursive CTE walking re_export_source) — separate future PR; v1 caveat documented.
• Other research note § 1 candidates still parked: § 1.6 unused type members (advisory recipe; needs JSON-extraction predicate), § 1.8 MCP resources (needs handler code), § 1.9 recipe-recency (needs new table + reconciler).

Summary by CodeRabbit

• New Features

  • Introduced unimported-exports recipe to identify exports with no detectable direct imports, serving as an initial candidate list for investigating potentially unused exports.

• Documentation

  • Updated agent rules and skill documentation with CLI shortcuts and quick-reference queries for the new recipe.
  • Added recipe template documenting configuration options, known v1 limitations, and guidance for project-local customization.

[changeset-bot]

🦋 Changeset detected

Latest commit: 38cee5d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@stainless-code/codemap	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

The PR introduces a new unimported-exports recipe to the codemap tool, which identifies exports never directly imported. The recipe is defined via SQL and Markdown templates, integrated into agent documentation and skills, and announced in a changeset. No core logic is modified.

Changes

Unimported Exports Recipe

Layer / File(s)	Summary
Recipe Definition templates/recipes/unimported-exports.sql, templates/recipes/unimported-exports.md	SQL query joins exports to imports via resolved_path and json_each() to detect direct usage, excluding re-exports and default exports. Markdown template documents the action (review-for-deletion), v1 limitations (re-export chains, unresolved imports, default exports), and tuning guidance for project-local overrides.
Agent Rules & Skills templates/agents/rules/codemap.md, templates/agents/skills/codemap/SKILL.md, .agents/rules/codemap.md, .agents/skills/codemap/SKILL.md	Trigger pattern "Which exports has nobody imported?" and CLI shortcut --recipe unimported-exports are documented in agent rules and skills; CLI command reference added to quick-reference queries.
Release Notes .changeset/unimported-exports-recipe.md	Changeset announces patch release for @stainless-code/codemap with v1 limitations and action template details; notes agent rule/skill lockstep update per docs Rule 10.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

• chore: npm agent templates vs dev .agents, patch changeset #6: Updates codemap agent rules and skills documentation in both .agents/ and templates/agents/ directories, aligning with recipe and CLI-shortcut documentation patterns.

Poem

🐰 A recipe blooms, exports unused now shine,
No imports to claim them—a surplus divine!
We flag them with care (they might have a friend),
But candidates gleam from start to the end. ✨

🚥 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 summarizes the main change: introducing a new 'unimported-exports' recipe with the feature designation '§ 1.2'. It is specific, concise, and directly related to the changeset which adds this recipe across multiple files.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/unimported-exports-recipe

---

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

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

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