Linking SQL DDL and GraphQL Schemas Directly to Code Entities in TokenCap

AI coding assistants frequently write SQL or ORM queries that look plausible but fail at runtime because a column was renamed from created_at to createdAt or a field is non-nullable.

To prevent schema-to-code drift, TokenCap implements schema linking in src/schema/schemaGraph.js.

How Schema Intelligence Works

1. DDL Parsing: Scans .sql migrations and Prisma/Drizzle schema files for CREATE TABLE statements, extracting column names, types, primary keys, and foreign keys.
2. GraphQL Schema Parsing: Extracts types, queries, and mutations from .graphql files.
3. Code Entity Linking: Maps extracted schema entities to corresponding backend model classes, Prisma calls, or repository queries.

Generated Graph Intelligence

When TokenCap compiles .tokencap/snapshot.md:

### Schema Entity: users (Table)
- Defined in: migrations/20260401_init_users.sql
- Columns:
  - id: UUID (Primary Key, NOT NULL)
  - email: VARCHAR(255) (UNIQUE, NOT NULL)
  - tier: VARCHAR(50) (DEFAULT 'free')
  - metadata: JSONB (NULLABLE)
- Referenced By Code:
  - src/models/User.js: User schema definition
  - src/services/auth.js: findByEmail
  - src/services/billing.js: updateSubscriptionTier

When an agent needs to add a column or modify a query, it knows the exact database constraints without asking you to upload database dumps.

Learn more at tokencap.vansharora.app