ai-codebase-registry

Registry-driven AI-agent infrastructure for codebases. Auto-generates machine-readable metadata, dependency graphs, side-effects tracking, and query APIs for AI coding agents.

Supports TypeScript, Swift, Kotlin, and Python projects.

Installation

npm install --save-dev ai-codebase-registry

Quick Start

# Initialize config file
npx ai-registry init

# Generate registry from source
npx ai-registry generate

# Validate @ai-meta coverage
npx ai-registry validate

CLI Commands

| Command | Description | |---------|-------------| | ai-registry init | Scaffold ai-registry.config.mjs for a new project | | ai-registry generate | Rebuild all registry files from source | | ai-registry validate | Check @ai-meta coverage and report gaps | | ai-registry query | Query registry data (files, deps, impact, coverage) | | ai-registry add-headers | Auto-add @ai-meta headers to files missing them |

Configuration

Create ai-registry.config.mjs in your project root:

TypeScript / JavaScript

export default {
  name: 'my-project',
  scanDirs: [{ dir: 'src', prefix: 'src' }],
  extensions: ['.ts', '.tsx'],
  skipDirs: ['node_modules', 'dist'],
  aliases: { '@/': 'src/' },
  registryDir: '_registry',
};

Swift (iOS / macOS)

export default {
  name: 'my-ios-app',
  scanDirs: [
    { dir: 'Sources', prefix: 'Sources' },
    { dir: 'Tests', prefix: 'Tests' },
  ],
  extensions: ['.swift'],
  skipDirs: ['build', 'Pods', '.build', 'DerivedData'],
  language: 'swift',
  fieldMap: { mutations: 'side-effects', dependencies: 'depends-on' },
  generators: ['manifest', 'semantic-ids', 'side-effects', 'features'],
  registryDir: '_registry',
};

Config Reference

| Field | Type | Default | Description | |-------|------|---------|-------------| | name | string | 'my-project' | Project name | | description | string | '' | Project description | | scanDirs | array | [{ dir: 'src', prefix: 'src' }] | Directories to scan | | extensions | array | ['.ts', '.tsx'] | File extensions to include | | skipDirs | array | ['node_modules', ...] | Directories to skip | | language | string | 'typescript' | 'typescript' | 'swift' | 'kotlin' | 'python' | | fieldMap | object | {} | Field name normalization map | | generators | array|null | null (all) | Which generators to run | | aliases | object | {} | Import alias map (TS only) | | router | string | 'none' | Router type for route extraction | | dataStore | string | 'none' | Data store type | | registryDir | string | '_registry' | Output directory | | agent | string | 'claude-code' | Target AI agent | | claudemd | boolean | true | Generate CLAUDE.md references |

Multi-Language Support

The parser auto-detects the comment style from file content:

| Language | Comment Style | Field Syntax | |----------|--------------|--------------| | TypeScript/JS | /** @ai-meta ... */ | @field value | | Swift | /// @ai-meta ... | field: value | | Kotlin/Go | // @ai-meta ... | field: value or @field value |

Field Normalization

Use fieldMap to map project-specific field names to canonical ones:

fieldMap: {
  mutations: 'side-effects',    // Swift uses "mutations:", canonical is "side-effects"
  dependencies: 'depends-on',   // Swift uses "dependencies:", canonical is "depends-on"
}

Generated Registry Files

| File | Description | |------|-------------| | manifest.json | Every source file with domain, type, purpose, imports | | semantic-ids.json | Stable entity ID to file path mapping | | deps.json | Import dependency graph (TypeScript only) | | side-effects.json | Mutation/trigger to downstream effects graph | | features.json | Feature inventory by domain |

Deep Import Paths

| Import Path | Purpose | |-------------|---------| | ai-codebase-registry | Main entry (re-exports) | | ai-codebase-registry/core/file-discovery | Recursive file scanning | | ai-codebase-registry/core/ai-meta-parser | @ai-meta header parsing | | ai-codebase-registry/core/domain-detector | Domain detection from paths | | ai-codebase-registry/core/type-detector | File type detection | | ai-codebase-registry/core/semantic-id | Semantic ID generation | | ai-codebase-registry/parsers | Parser barrel export | | ai-codebase-registry/generators | Generator barrel export | | ai-codebase-registry/query | Registry query engine |

License

MIT