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.

Author: SutuSebastian

.agents/skills/codemap/SKILL.md

@@ -190,6 +190,10 @@ 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';
+
 -- File overview (imports + exports)
 SELECT 'import' as dir, source as name, specifiers as detail
 FROM imports WHERE file_path LIKE '%OrderRow%'

docs/architecture.md

@@ -173,17 +173,18 @@ All tables use `STRICT` mode. Tables marked with `WITHOUT ROWID` store data dire
 
 ### `symbols` — Functions, constants, classes, interfaces, types, enums (`STRICT`)
 
-| Column            | Type       | Description                                                           |
-| ----------------- | ---------- | --------------------------------------------------------------------- |
-| id                | INTEGER PK | Auto-increment row id                                                 |
-| file_path         | TEXT FK    | References `files(path)` ON DELETE CASCADE                            |
-| name              | TEXT       | Symbol name                                                           |
-| kind              | TEXT       | `function`, `const`, `class`, `interface`, `type`, `enum`             |
-| line_start        | INTEGER    | Start line (1-based)                                                  |
-| line_end          | INTEGER    | End line                                                              |
-| signature         | TEXT       | Reconstructed signature (e.g. `usePermissions(): PermissionsContext`) |
-| is_exported       | INTEGER    | 1 if exported                                                         |
-| is_default_export | INTEGER    | 1 if default export                                                   |
+| Column            | Type       | Description                                                                                                                                                                         |
+| ----------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| id                | INTEGER PK | Auto-increment row id                                                                                                                                                               |
+| file_path         | TEXT FK    | References `files(path)` ON DELETE CASCADE                                                                                                                                          |
+| name              | TEXT       | Symbol name                                                                                                                                                                         |
+| kind              | TEXT       | `function`, `const`, `class`, `interface`, `type`, `enum`                                                                                                                           |
+| line_start        | INTEGER    | Start line (1-based)                                                                                                                                                                |
+| line_end          | INTEGER    | End line                                                                                                                                                                            |
+| signature         | TEXT       | Reconstructed signature with generics and return types (e.g. `identity<T>(val): T`, `interface Repo<T> extends Iterable<T>`, `class Store<T> extends Base<T> implements IStore<T>`) |
+| is_exported       | INTEGER    | 1 if exported                                                                                                                                                                       |
+| is_default_export | INTEGER    | 1 if default export                                                                                                                                                                 |
+| members           | TEXT       | JSON array of enum members (NULL for non-enums). Each entry: `{"name":"…","value":"…"}` (value omitted for implicit-value enums)                                                    |
 
 ### `imports` — Import statements (`STRICT`)
 
@@ -283,7 +284,8 @@ All tables have covering indexes tuned for AI agent query patterns. See [Coverin
 
 Uses the Rust-based `oxc-parser` via NAPI bindings to parse TypeScript/TSX/JS/JSX files into an AST. Extracts:
 
-- **Symbols**: Functions, arrow functions, classes, interfaces, type aliases, enums — with reconstructed signatures
+- **Symbols**: Functions, arrow functions, classes, interfaces, type aliases, enums — with reconstructed signatures including generic type parameters (e.g. `<T extends Base>`), return type annotations (e.g. `: Promise<void>`), class/interface heritage (`extends`, `implements`)
+- **Enum members**: String and numeric values for each member, stored as JSON (e.g. `[{"name":"Active","value":"active"}]`)
 - **Imports**: All `import` statements with specifiers, source paths, and type-only flags
 - **Exports**: Named exports, default exports, re-exports
 - **Components**: React components detected via PascalCase name + (JSX return **or** hook usage). A PascalCase function in `.tsx`/`.jsx` that neither returns JSX nor calls hooks is indexed only as a symbol, not a component. Extracts props type and hooks used

src/db.ts

@@ -49,7 +49,8 @@ export function createTables(db: CodemapDatabase) {
       line_end INTEGER,
       signature TEXT,
       is_exported INTEGER DEFAULT 0,
-      is_default_export INTEGER DEFAULT 0
+      is_default_export INTEGER DEFAULT 0,
+      members TEXT
     ) STRICT;
 
     CREATE TABLE IF NOT EXISTS imports (
@@ -254,6 +255,7 @@ export interface SymbolRow {
   signature: string;
   is_exported: number;
   is_default_export: number;
+  members: string | null;
 }
 
 const BATCH_SIZE = 100;
@@ -286,8 +288,8 @@ export function insertSymbols(db: CodemapDatabase, symbols: SymbolRow[]) {
   batchInsert(
     db,
     symbols,
-    "INSERT INTO symbols (file_path, name, kind, line_start, line_end, signature, is_exported, is_default_export)",
-    "(?,?,?,?,?,?,?,?)",
+    "INSERT INTO symbols (file_path, name, kind, line_start, line_end, signature, is_exported, is_default_export, members)",
+    "(?,?,?,?,?,?,?,?,?)",
     (s, v) =>
       v.push(
         s.file_path,
@@ -298,6 +300,7 @@ export function insertSymbols(db: CodemapDatabase, symbols: SymbolRow[]) {
         s.signature,
         s.is_exported,
         s.is_default_export,
+        s.members,
       ),
   );
 }

src/parser.test.ts

@@ -41,6 +41,131 @@ describe("extractFileData", () => {
     });
   });
 
+  describe("signatures — generics and return types", () => {
+    it("includes return type annotation on functions", () => {
+      const src = `export function greet(name: string): string { return name; }\n`;
+      const d = extractFileData("/proj/x.ts", src, "x.ts");
+      const sig = d.symbols.find((s) => s.name === "greet")?.signature;
+      expect(sig).toBe("greet(name): string");
+    });
+
+    it("includes generic type params on functions", () => {
+      const src = `export function identity<T>(val: T): T { return val; }\n`;
+      const d = extractFileData("/proj/x.ts", src, "x.ts");
+      const sig = d.symbols.find((s) => s.name === "identity")?.signature;
+      expect(sig).toBe("identity<T>(val): T");
+    });
+
+    it("includes constrained generics", () => {
+      const src = `export function first<T extends string>(items: T[]): T { return items[0]; }\n`;
+      const d = extractFileData("/proj/x.ts", src, "x.ts");
+      const sig = d.symbols.find((s) => s.name === "first")?.signature;
+      expect(sig).toBe("first<T extends string>(items): T");
+    });
+
+    it("includes return type on arrow functions", () => {
+      const src = `export const add = (a: number, b: number): number => a + b;\n`;
+      const d = extractFileData("/proj/x.ts", src, "x.ts");
+      const sig = d.symbols.find((s) => s.name === "add")?.signature;
+      expect(sig).toBe("add(a, b): number");
+    });
+
+    it("includes generics on arrow functions", () => {
+      const src = `export const wrap = <T>(val: T): T[] => [val];\n`;
+      const d = extractFileData("/proj/x.ts", src, "x.ts");
+      const sig = d.symbols.find((s) => s.name === "wrap")?.signature;
+      expect(sig).toBe("wrap<T>(val): T[]");
+    });
+
+    it("includes generics on type aliases", () => {
+      const src = `export type Result<T, E = Error> = { ok: T } | { err: E };\n`;
+      const d = extractFileData("/proj/x.ts", src, "x.ts");
+      const sig = d.symbols.find((s) => s.name === "Result")?.signature;
+      expect(sig).toBe("type Result<T, E = Error>");
+    });
+
+    it("includes generics and extends on interfaces", () => {
+      const src = `export interface Repo<T> extends Iterable<T> { get(id: string): T; }\n`;
+      const d = extractFileData("/proj/x.ts", src, "x.ts");
+      const sig = d.symbols.find((s) => s.name === "Repo")?.signature;
+      expect(sig).toBe("interface Repo<T> extends Iterable<T>");
+    });
+
+    it("includes generics, extends, and implements on classes", () => {
+      const src = `export class Store<T> extends Base<T> implements IStore<T> {}\n`;
+      const d = extractFileData("/proj/x.ts", src, "x.ts");
+      const sig = d.symbols.find((s) => s.name === "Store")?.signature;
+      expect(sig).toBe("class Store<T> extends Base<T> implements IStore<T>");
+    });
+
+    it("handles union return types", () => {
+      const src = `export function parse(s: string): number | null { return null; }\n`;
+      const d = extractFileData("/proj/x.ts", src, "x.ts");
+      const sig = d.symbols.find((s) => s.name === "parse")?.signature;
+      expect(sig).toBe("parse(s): number | null");
+    });
+
+    it("handles Promise return type", () => {
+      const src = `export async function load(): Promise<void> {}\n`;
+      const d = extractFileData("/proj/x.ts", src, "x.ts");
+      const sig = d.symbols.find((s) => s.name === "load")?.signature;
+      expect(sig).toBe("load(): Promise<void>");
+    });
+
+    it("omits return type when unannotated", () => {
+      const src = `export function run() { return 1; }\n`;
+      const d = extractFileData("/proj/x.ts", src, "x.ts");
+      const sig = d.symbols.find((s) => s.name === "run")?.signature;
+      expect(sig).toBe("run()");
+    });
+  });
+
+  describe("enum members extraction", () => {
+    it("extracts string enum members with values", () => {
+      const src = `export enum Status { Active = "active", Inactive = "inactive" }\n`;
+      const d = extractFileData("/proj/x.ts", src, "x.ts");
+      const sym = d.symbols.find((s) => s.name === "Status");
+      expect(sym?.kind).toBe("enum");
+      const members = JSON.parse(sym!.members!);
+      expect(members).toEqual([
+        { name: "Active", value: "active" },
+        { name: "Inactive", value: "inactive" },
+      ]);
+    });
+
+    it("extracts numeric enum members", () => {
+      const src = `export enum Dir { Up = 0, Down = 1, Left = 2 }\n`;
+      const d = extractFileData("/proj/x.ts", src, "x.ts");
+      const members = JSON.parse(
+        d.symbols.find((s) => s.name === "Dir")!.members!,
+      );
+      expect(members).toEqual([
+        { name: "Up", value: 0 },
+        { name: "Down", value: 1 },
+        { name: "Left", value: 2 },
+      ]);
+    });
+
+    it("extracts implicit-value enum members (no initializer)", () => {
+      const src = `export enum Color { Red, Green, Blue }\n`;
+      const d = extractFileData("/proj/x.ts", src, "x.ts");
+      const members = JSON.parse(
+        d.symbols.find((s) => s.name === "Color")!.members!,
+      );
+      expect(members).toEqual([
+        { name: "Red" },
+        { name: "Green" },
+        { name: "Blue" },
+      ]);
+    });
+
+    it("returns null members for non-enum symbols", () => {
+      const src = `export function foo(): void {}\n`;
+      const d = extractFileData("/proj/x.ts", src, "x.ts");
+      expect(d.symbols.find((s) => s.name === "foo")?.members).toBeNull();
+    });
+  });
+
   describe("component detection heuristic", () => {
     it("detects components that return JSX", () => {
       const src = `export function Card() { return <div>card</div>; }\n`;