feat(recipes): type-ancestors and type-descendants

[SutuSebastian]

Summary

• Add type-ancestors and type-descendants bundled recipes for walking class/interface heritage via recursive CTEs on symbols.signature (extends / implements clauses).
• Add fixtures/minimal/src/types/hierarchy.ts (Animal → Mammal → Dog + Pet implements) with four golden-query scenarios.
• Mark call-path-type-hierarchy-recipes plan shipped and prune the item from roadmap / agent-surface P2 table.

Heritage is signature-derived (no new schema columns). Recipe docs note parsing limits (qualified extends, commas in generics).

Test plan

• bun run test:golden --update then bun run test:golden
• Manual: CODEMAP_ROOT=fixtures/minimal bun src/index.ts query --recipe type-ancestors --params symbol_name=Dog --json
• Manual: CODEMAP_ROOT=fixtures/minimal bun src/index.ts query --recipe type-descendants --params symbol_name=Animal --json

Summary by CodeRabbit

• New Features

  • Added type-ancestors query to trace type inheritance and implementation chains for symbols
  • Added type-descendants query to find types that extend or implement a given symbol

• Documentation

  • Added comprehensive documentation with examples for type hierarchy queries

• Chores

  • Removed outdated strategic planning documentation

[changeset-bot]

🦋 Changeset detected

Latest commit: 32cad9c

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]

Warning

Review limit reached

@SutuSebastian, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 45 minutes and 34 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: acdb0b40-486c-44fc-828b-736fd265b6e3

📥 Commits

Reviewing files that changed from the base of the PR and between 0cecdc3 and 32cad9c.

📒 Files selected for processing (11)

• .changeset/type-hierarchy-recipes.md
• docs/plans/agent-surface-delivery.md
• fixtures/golden/minimal/files-hashes.json
• fixtures/golden/minimal/files-largest.json
• fixtures/golden/minimal/type-descendants-homonym-empty.json
• fixtures/golden/minimal/type-descendants-homonym-scoped.json
• fixtures/golden/minimal/type-descendants-unknown.json
• fixtures/golden/scenarios.json
• templates/agent-content/mcp-instructions.md
• templates/recipes/type-descendants.md
• templates/recipes/type-descendants.sql

📝 Walkthrough

Walkthrough

This PR implements type-ancestors and type-descendants SQL recipe queries for Codemap. It adds recursive CTE-based queries that compute transitive type inheritance relationships from parsed symbol signatures, includes TypeScript test fixtures demonstrating various inheritance patterns, and provides comprehensive golden fixtures validating expected query outputs.

Changes

Type-hierarchy recipes

Layer / File(s)	Summary
Type-ancestors recipe implementation templates/recipes-fragments/heritage-edges.sql, templates/recipes/type-ancestors.sql, templates/recipes/type-ancestors.md	Introduces heritage-edges SQL fragment that parses extends/implements clauses from symbol signatures, splits comma-separated parents, and normalizes base type names by stripping generic arguments. The type-ancestors query recursively traverses extends links from a specified symbol, detects cycles, limits depth, and adds direct implements targets at depth 1, with documentation covering parameters, semantics, and output fields.
Type-descendants recipe implementation templates/recipes/type-descendants.sql, templates/recipes/type-descendants.md	Implements transitive descendant computation using recursive CTEs to walk extends relationships with cycle prevention and depth limiting. Resolves parent type names, initializes descendants from matching base symbols, and recursively expands extends edges while tracking visited nodes and respecting max_depth. Includes documentation for parameters, traversal scoping, and return field contracts.
Type hierarchy test fixtures fixtures/minimal/src/types/hierarchy.ts, fixtures/minimal/src/types/homonym-mammal.ts, fixtures/minimal/src/types/type-cycle.ts, fixtures/minimal/README.md	Defines TypeScript fixtures: Animal interface, Mammal extending Animal, Pet interface, Both combining both via multi-base extension, and Dog class extending Mammal and implementing Pet. Adds Mammal homonym in separate file to test name collision handling. Introduces CycleA and CycleB interfaces extending each other for cycle detection testing. Updates fixture README to document type-ancestors and type-descendants coverage.
Golden test fixtures and scenario configuration fixtures/golden/minimal/type-ancestors-*.json, fixtures/golden/minimal/type-descendants-*.json, fixtures/golden/scenarios.json, fixtures/golden/minimal/barrel-files.json, fixtures/golden/minimal/files-*.json, fixtures/golden/minimal/refactor-risk-ranking.json, fixtures/golden/minimal/unimported-exports.json, fixtures/golden/minimal/unused-type-members.json	Adds golden JSON fixtures validating type-ancestors query outputs for Dog (extends + implements case), homonym disambiguation via file_path, max-depth truncation, kind filtering, unknown symbols (empty result), and cycle handling. Adds type-descendants fixtures for Animal and Pet, max-depth variants, and class filtering. Defines comprehensive test scenarios covering all query parameter combinations. Updates all fixture metadata: file/symbol counts (27→30 files, 75→84 symbols), content hashes, barrel export counts, risk rankings, unimported/unused member listings.
Planning document cleanup docs/plans/agent-surface-and-ops.md, docs/roadmap.md	Removes call-path-type-hierarchy-recipes entry from P2 strategic bets table and removes "Call path + type hierarchy recipes" backlog item from roadmap, reflecting that the type-ancestors and type-descendants recipes are now implemented.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Suggested labels

enhancement, documentation

---

🐰 A rabbit's ode to hierarchies so true,
Where ancestors dance and descendants pursue,
With extends and implements, cycles contained,
Type relationships mapped and charmingly chained!
From golden test fixtures, we hop forward with glee,
The recipe's complete—now symbols run free! 🌿

🚥 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 PR title clearly summarizes the main changes: addition of two new recipes (type-ancestors and type-descendants) to the codebase.
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/type-hierarchy-recipes

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@templates/recipes/type-descendants.sql`:
- Around line 132-158: The JOIN in the descendants CTE currently uses only
he.base_name = bs.name which pulls heritage edges from homonymous bases in other
files; update the JOIN between base_symbols bs and heritage_edges he inside the
descendants CTE to also constrain the base file path so the first-level
expansion respects params.file_path (e.g. JOIN heritage_edges he ON he.base_name
= bs.name AND (bs.file_path IS NULL OR bs.file_path = '' OR he.base_file_path =
bs.file_path)); keep the rest of the descendant columns/visited construction the
same so deeper recursion still works.

🪄 Autofix (Beta)

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

Run ID: 7e060a8a-0c95-4014-bfa8-22c2c3b8eced

📥 Commits

Reviewing files that changed from the base of the PR and between ee9f6b2 and 0cecdc3.

📒 Files selected for processing (30)

• docs/plans/agent-surface-and-ops.md
• docs/plans/call-path-type-hierarchy-recipes.md
• docs/roadmap.md
• fixtures/golden/minimal/barrel-files.json
• fixtures/golden/minimal/files-count.json
• fixtures/golden/minimal/files-hashes.json
• fixtures/golden/minimal/files-largest.json
• fixtures/golden/minimal/index-summary.json
• fixtures/golden/minimal/refactor-risk-ranking.json
• fixtures/golden/minimal/type-ancestors-cycle.json
• fixtures/golden/minimal/type-ancestors-dog.json
• fixtures/golden/minimal/type-ancestors-homonym.json
• fixtures/golden/minimal/type-ancestors-kind-filter.json
• fixtures/golden/minimal/type-ancestors-max-depth.json
• fixtures/golden/minimal/type-ancestors-unknown.json
• fixtures/golden/minimal/type-descendants-animal.json
• fixtures/golden/minimal/type-descendants-max-depth.json
• fixtures/golden/minimal/type-descendants-pet-class.json
• fixtures/golden/minimal/unimported-exports.json
• fixtures/golden/minimal/unused-type-members.json
• fixtures/golden/scenarios.json
• fixtures/minimal/README.md
• fixtures/minimal/src/types/hierarchy.ts
• fixtures/minimal/src/types/homonym-mammal.ts
• fixtures/minimal/src/types/type-cycle.ts
• templates/recipes-fragments/heritage-edges.sql
• templates/recipes/type-ancestors.md
• templates/recipes/type-ancestors.sql
• templates/recipes/type-descendants.md
• templates/recipes/type-descendants.sql

💤 Files with no reviewable changes (2)

• docs/plans/call-path-type-hierarchy-recipes.md
• docs/roadmap.md