feat: richer symbol metadata — signatures, JSDoc, type members, call graph (#19)

* feat: richer symbol metadata — generics, return types, enum members

Signatures now include generic type parameters (`<T extends Base>`),
return type annotations (`: Promise<void>`), and class/interface
heritage (`extends`, `implements`). Enum members are extracted into a
new `members TEXT` column as JSON.

Benchmarked on a 1,653-file React/TS codebase: 973 functions gain
return types, 873 symbols gain generics, 291 enum member values
captured across 50 enums. Index time +7% (negligible), DB size
unchanged.

* feat: JSDoc extraction and type_members table

Add doc_comment column to symbols (3,084 documented symbols on benchmark
repo) and new type_members table for interface/type-alias properties
(12,052 members extracted). Agents can now query type shapes and symbol
documentation without reading files.

SCHEMA_VERSION bumped to 2.

* feat: extract const literal values into symbols.value

Captures string, number, boolean, null, negative numbers, `as const`,
and simple template literals. 615 values extracted on benchmark repo.

* feat: symbol nesting via parent_name + class member extraction

Adds parent_name column to symbols for scope tracking. A visitor stack
assigns parent context to nested functions/consts (10,202 nested symbols
on benchmark). Class methods, properties, and getters/setters are now
extracted as individual symbols with parent_name pointing to the class.

* feat: call graph extraction — function-scoped, deduped per file

New `calls` table tracks which functions call which. Edges are deduped
per file and limited to function-scoped calls (module-level excluded).

Benchmark (merchant-dashboard-v2): 13,804 edges, 2,700 callers,
5,310 callees. Index time unchanged, DB +5MB (23→28MB).

* chore: add changeset for richer symbol metadata

* fix: call graph improvements — qualified scope, this.method(), multi-declarator scope fix

- Add caller_scope column to calls table (dot-joined scope path, e.g.
  UserService.run) so same-named methods across classes are no longer
  conflated. Dedup key now uses full scope path.
- Handle this.foo() calls in CallExpression (emitted as this.methodName).
- Fix multi-declarator scope corruption: VariableDeclaration:exit now
  iterates in reverse so const a = () => {}, b = () => {} correctly
  pops both scopes.
- Document new class-member kind values (method, property, getter,
  setter) in architecture.md.
- Sync template SKILL.md with authoring skill query examples.

* perf: reduce allocations and redundant I/O in parser and index engine

- Cache scopeStack.join(".") via scopePush/scopePop helpers
- Hoist hot-path regex literals (RE_COMPONENT, RE_HOOK) to module scope
- Replace findJsDoc gap regex with charCodeAt loop (no .slice())
- Cache getProjectRoot() in getChangedFiles, insertParsedResults, indexFiles
- Eliminate redundant getAllFileHashes call in incremental path
- Batch DELETE for deleted files (single IN() vs N separate DELETEs)
- Hoist fileURLToPath and getProjectRoot() in worker-pool spawn loop
- Increase BATCH_SIZE 100→500 for fewer INSERT round-trips
- Zero-alloc isPathExcluded via charCodeAt segment scan
- Update docs: schema version 1→2, batch size references

* docs: fix stale schema comment, add caller_scope index, expand parser checklist

- Update SCHEMA_VERSION comment to reflect current bump-on-change policy
- Add idx_calls_scope covering index for caller_scope queries
- Expand parser extraction checklist in architecture.md with JSDoc,
  const values, type members, call graph, and symbol nesting

Author: SutuSebastian

.agents/rules/codemap.mdc

@@ -56,6 +56,9 @@ If the question looks like any of these → use the index:
 | "How many files/symbols/components are there?" | any table with `COUNT(*)` |
 | "What are the CSS classes in X?" | `css_classes` |
 | "What keyframe animations exist?" | `css_keyframes` |
+| "What fields does interface/type X have?" | `type_members` |
+| "Is symbol X deprecated?" / "What does X do?" | `symbols` (`doc_comment`) |
+| "Who calls X?" / "What does X call?" | `calls` |
 
 ## When Grep / Read IS appropriate
 
@@ -93,6 +96,15 @@ bun src/index.ts query --json "<SQL>"
 | CSS design tokens | `SELECT name, value, scope FROM css_variables WHERE name LIKE '--%...'` |
 | CSS module classes | `SELECT name, file_path FROM css_classes WHERE is_module = 1` |
 | CSS keyframes | `SELECT name, file_path FROM css_keyframes` |
+| Type/interface shape | `SELECT name, type, is_optional, is_readonly FROM type_members WHERE symbol_name = '...'` |
+| Deprecated symbols | `SELECT name, kind, file_path, doc_comment FROM symbols WHERE doc_comment LIKE '%@deprecated%'` |
+| Symbol docs | `SELECT name, signature, doc_comment FROM symbols WHERE name = '...' AND doc_comment IS NOT NULL` |
+| Const values | `SELECT name, value, file_path FROM symbols WHERE kind = 'const' AND value IS NOT NULL AND name LIKE '%...'` |
+| Class members | `SELECT name, kind, signature FROM symbols WHERE parent_name = '...'` |
+| Top-level only | `SELECT name, kind, signature FROM symbols WHERE parent_name IS NULL AND file_path LIKE '%...'` |
+| Who calls X? | `SELECT DISTINCT caller_name, file_path FROM calls WHERE callee_name = '...'` |
+| What does X call? | `SELECT DISTINCT callee_name FROM calls WHERE caller_name = '...'` |
+| Call hotspots | `SELECT callee_name, COUNT(*) as fan_in FROM calls GROUP BY callee_name ORDER BY fan_in DESC LIMIT 10` |
 
 **Use `DISTINCT`** on dependency and import queries — a file importing multiple specifiers from the same module produces duplicate rows.
 

.agents/skills/codemap/SKILL.md

@@ -85,9 +85,35 @@ LIMIT 10
 | kind              | TEXT       | `function`, `class`, `type`, `interface`, `enum`, `const` |
 | line_start        | INTEGER    | Start line (1-based)                                      |
 | line_end          | INTEGER    | End line (1-based)                                        |
-| signature         | TEXT       | e.g. `createHandler()`, `type UserProps`                  |
+| signature         | TEXT       | Reconstructed signature with generics and return types    |
 | is_exported       | INTEGER    | 1 if exported                                             |
 | is_default_export | INTEGER    | 1 if default export                                       |
+| members           | TEXT       | JSON enum members (NULL for non-enums)                    |
+| doc_comment       | TEXT       | Leading JSDoc text (cleaned), NULL when absent            |
+| value             | TEXT       | Literal value for consts (`"ok"`, `42`, `true`, `null`)   |
+| parent_name       | TEXT       | Enclosing symbol name (class/function), NULL = top-level  |
+
+### `calls` — Function-scoped call edges (deduped per file)
+
+| Column       | Type       | Description                                     |
+| ------------ | ---------- | ----------------------------------------------- |
+| id           | INTEGER PK | Auto-increment ID                               |
+| file_path    | TEXT FK    | References `files(path)`                        |
+| caller_name  | TEXT       | Calling function/method name                    |
+| caller_scope | TEXT       | Dot-joined scope path (e.g. `MyClass.run`)      |
+| callee_name  | TEXT       | Called function, `obj.method`, or `this.method` |
+
+### `type_members` — Properties of interfaces and object-literal type aliases
+
+| Column      | Type       | Description                                        |
+| ----------- | ---------- | -------------------------------------------------- |
+| id          | INTEGER PK | Auto-increment ID                                  |
+| file_path   | TEXT FK    | References `files(path)`                           |
+| symbol_name | TEXT       | Parent interface / type alias name                 |
+| name        | TEXT       | Property or method name                            |
+| type        | TEXT       | Type annotation (e.g. `string`, `(key) => number`) |
+| is_optional | INTEGER    | 1 if `?` modifier                                  |
+| is_readonly | INTEGER    | 1 if `readonly` modifier                           |
 
 ### `imports` — Import statements
 
@@ -190,6 +216,46 @@ FROM symbols WHERE name LIKE '%Config%' ORDER BY name;
 SELECT name, kind, signature
 FROM symbols WHERE file_path LIKE '%settings-provider%' AND is_exported = 1;
 
+-- Enum values (what are the valid members of an enum?)
+SELECT name, members FROM symbols
+WHERE kind = 'enum' AND name = 'TransactionStatus';
+
+-- Interface / type shape (what fields does a type have?)
+SELECT name, type, is_optional, is_readonly FROM type_members
+WHERE symbol_name = 'UserSession';
+
+-- Deprecated symbols (find @deprecated via JSDoc)
+SELECT name, kind, file_path, doc_comment FROM symbols
+WHERE doc_comment LIKE '%@deprecated%';
+
+-- Symbol documentation
+SELECT name, signature, doc_comment FROM symbols
+WHERE name = 'formatCurrency' AND doc_comment IS NOT NULL;
+
+-- Const values (config flags, magic strings)
+SELECT name, value, file_path FROM symbols
+WHERE kind = 'const' AND value IS NOT NULL AND name LIKE '%URL%';
+
+-- Class methods (what does class X expose?)
+SELECT name, kind, signature FROM symbols
+WHERE parent_name = 'UserService' ORDER BY name;
+
+-- Top-level symbols only (skip nested helpers)
+SELECT name, kind, signature FROM symbols
+WHERE parent_name IS NULL AND file_path LIKE '%utils%';
+
+-- Who calls function X? (fan-in)
+SELECT DISTINCT caller_name, file_path FROM calls
+WHERE callee_name = 'fetchUser';
+
+-- What does function X call? (fan-out)
+SELECT DISTINCT callee_name FROM calls
+WHERE caller_name = 'processUser';
+
+-- Most-called functions (hotspots)
+SELECT callee_name, COUNT(*) as fan_in FROM calls
+GROUP BY callee_name ORDER BY fan_in DESC LIMIT 10;
+
 -- File overview (imports + exports)
 SELECT 'import' as dir, source as name, specifiers as detail
 FROM imports WHERE file_path LIKE '%OrderRow%'

.changeset/richer-symbol-metadata.md

@@ -0,0 +1,15 @@
+---
+"@stainless-code/codemap": minor
+---
+
+Richer symbol metadata: generics, return types, JSDoc, type members, const values, symbol nesting, call graph
+
+- Signatures now include generic type parameters, return type annotations, and heritage clauses (extends/implements)
+- New `doc_comment` column on symbols extracts leading JSDoc comments
+- New `type_members` table indexes properties and methods of interfaces and object-literal types
+- New `value` column on symbols captures const literal values (strings, numbers, booleans, null)
+- New `parent_name` column on symbols tracks scope nesting; class methods/properties/getters extracted as individual symbols
+- New `calls` table tracks function-scoped call edges with `caller_scope` for qualified disambiguation (deduped per file)
+- Enum members extracted into `members` column as JSON
+- Performance: cached scope strings, hoisted hot-path regex, batch deletes, reduced redundant I/O, BATCH_SIZE 100→500
+- SCHEMA_VERSION bumped to 2