ai-codebase-registry 1.0.0

package/bin/query.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * @ai-meta
+ * @id module:ai-agent-infra:cli-query
+ * @domain ai-agent-infra
+ * @type module
+ * @side-effects none
+ * @stability medium
+ * @complexity moderate
+ * @token-budget 100
+ * @purpose CLI command: query registry data
+ *
+ * @filechangelog
+ * @changelog 2026-02-22T14:00 [feat] [Claude Opus 4.6] Created query CLI command
+ */
+
+import { resolve } from 'path';
+import { Registry } from '../lib/core/registry.mjs';
+import { executeQuery } from '../lib/query/engine.mjs';
+
+function parseArgs(argv) {
+  const args = {};
+  const raw = argv.slice(2);
+  for (let i = 0; i < raw.length; i++) {
+    const arg = raw[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      // Boolean flags
+      if (['json', 'help', 'orphaned-routes', 'coverage'].includes(key)) {
+        args[key] = true;
+      } else if (i + 1 < raw.length && !raw[i + 1].startsWith('--')) {
+        args[key] = raw[++i];
+      } else {
+        args[key] = true;
+      }
+    }
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv);
+const registryDir = resolve(args['registry-dir'] || '_registry');
+
+const registry = Registry.load(registryDir);
+
+const query = {
+  domain: args.domain,
+  type: args.type,
+  id: args.id,
+  consumers: args.consumers,
+  deps: args.deps,
+  impact: args.impact,
+  sideEffects: args['side-effects'],
+  complexity: args.complexity,
+  orphanedRoutes: args['orphaned-routes'],
+  coverage: args.coverage,
+  help: args.help,
+};
+
+const options = { json: args.json };
+const { output } = executeQuery(registry, query, options);
+console.log(output);

package/bin/validate.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * @ai-meta
+ * @id module:ai-agent-infra:cli-validate
+ * @domain ai-agent-infra
+ * @type module
+ * @side-effects none
+ * @stability medium
+ * @complexity moderate
+ * @token-budget 120
+ * @purpose CLI command: validate @ai-meta coverage and report gaps
+ *
+ * @filechangelog
+ * @changelog 2026-02-22T14:00 [feat] [Claude Opus 4.6] Created validate CLI command
+ */
+
+import { resolve } from 'path';
+import { Registry } from '../lib/core/registry.mjs';
+
+const C = {
+  reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+  green: '\x1b[32m', yellow: '\x1b[33m', red: '\x1b[31m', cyan: '\x1b[36m',
+};
+
+function parseArgs(argv) {
+  const args = {};
+  const raw = argv.slice(2);
+  for (let i = 0; i < raw.length; i++) {
+    const arg = raw[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      if (['json', 'strict'].includes(key)) {
+        args[key] = true;
+      } else if (i + 1 < raw.length && !raw[i + 1].startsWith('--')) {
+        args[key] = raw[++i];
+      } else {
+        args[key] = true;
+      }
+    }
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv);
+const registryDir = resolve(args['registry-dir'] || '_registry');
+const registry = Registry.load(registryDir);
+const coverage = registry.coverage();
+
+if (args.json) {
+  console.log(JSON.stringify(coverage, null, 2));
+  process.exit(coverage.missingId.length > 0 ? 1 : 0);
+}
+
+console.log(`\n${C.bold}Registry Validation${C.reset}`);
+console.log('='.repeat(40));
+
+const checks = [
+  {
+    label: '@id coverage',
+    count: coverage.withId.count,
+    total: coverage.totalFiles,
+    pct: coverage.withId.pct,
+    missing: coverage.missingId,
+  },
+  {
+    label: '@side-effects coverage',
+    count: coverage.withSideEffects.count,
+    total: coverage.totalFiles,
+    pct: coverage.withSideEffects.pct,
+    missing: coverage.missingSideEffects,
+  },
+  {
+    label: '@purpose coverage',
+    count: coverage.withPurpose.count,
+    total: coverage.totalFiles,
+    pct: coverage.withPurpose.pct,
+    missing: [],
+  },
+];
+
+let hasFailures = false;
+
+for (const check of checks) {
+  const pct = parseFloat(check.pct);
+  const icon = pct === 100 ? `${C.green}PASS${C.reset}` : pct >= 95 ? `${C.yellow}WARN${C.reset}` : `${C.red}FAIL${C.reset}`;
+  console.log(`\n  ${icon}  ${check.label}: ${check.count}/${check.total} (${check.pct}%)`);
+
+  if (check.missing.length > 0) {
+    hasFailures = true;
+    const shown = check.missing.slice(0, 10);
+    for (const p of shown) console.log(`        ${C.dim}${p}${C.reset}`);
+    if (check.missing.length > 10) {
+      console.log(`        ${C.dim}... and ${check.missing.length - 10} more${C.reset}`);
+    }
+  }
+}
+
+console.log(`\n${C.bold}Summary:${C.reset} ${coverage.totalFiles} files, ${hasFailures ? `${C.red}gaps found${C.reset}` : `${C.green}100% coverage${C.reset}`}\n`);
+
+if (args.strict && hasFailures) {
+  process.exit(1);
+}

package/lib/core/ai-meta-parser.mjs

@@ -0,0 +1,196 @@
+/**
+ * @ai-meta
+ * @id module:ai-agent-infra:ai-meta-parser
+ * @domain ai-agent-infra
+ * @type module
+ * @side-effects none
+ * @stability high
+ * @complexity moderate
+ * @token-budget 200
+ * @purpose Parses @ai-meta headers from source files — supports JSDoc, triple-slash (Swift), and line-comment styles
+ *
+ * @filechangelog
+ * @changelog 2026-02-23T10:00 [feat] [Claude Opus 4.6] Add triple-slash + line-comment parsing, fieldMap normalization for multi-language support
+ * @changelog 2026-02-22T14:00 [feat] [Claude Opus 4.6] Extracted from generate-registry.mjs
+ */
+
+const FIELDS = [
+  'domain', 'type', 'purpose', 'depends-on', 'firestore',
+  'id', 'side-effects', 'stability', 'complexity', 'token-budget', 'nav-entry',
+  'mutations', 'dependencies',
+];
+const SINGLE_TOKEN_FIELDS = new Set(['domain', 'type', 'id', 'stability', 'complexity']);
+
+/**
+ * Extract @ai-meta block from JSDoc comment (/** ... * /).
+ * @param {string} content
+ * @returns {string[]|null} Lines of the block, or null
+ */
+function extractJsDocBlock(content) {
+  const match = content.match(/\/\*\*[\s\S]*?@ai-meta[\s\S]*?\*\//);
+  if (!match) return null;
+  return match[0].split('\n');
+}
+
+/**
+ * Extract @ai-meta block from consecutive triple-slash comments (/// ...).
+ * Used by Swift files. Block must start within the first 10 lines.
+ * @param {string} content
+ * @returns {string[]|null} Lines of the block, or null
+ */
+function extractTripleSlashBlock(content) {
+  const lines = content.split('\n');
+  let inBlock = false;
+  const blockLines = [];
+
+  for (let i = 0; i < lines.length && i < 50; i++) {
+    const trimmed = lines[i].trim();
+    if (trimmed.startsWith('///')) {
+      const inner = trimmed.slice(3).trim();
+      if (inner === '@ai-meta' || inner.startsWith('@ai-meta')) {
+        inBlock = true;
+        blockLines.push(inner);
+        continue;
+      }
+      if (inBlock) {
+        blockLines.push(inner);
+      }
+    } else if (inBlock) {
+      break; // Non-/// line ends the block
+    }
+  }
+
+  return inBlock && blockLines.length > 1 ? blockLines : null;
+}
+
+/**
+ * Extract @ai-meta block from consecutive line comments (// ...).
+ * For Kotlin/Go/future languages. Block must start within first 10 lines.
+ * @param {string} content
+ * @returns {string[]|null} Lines of the block, or null
+ */
+function extractLineCommentBlock(content) {
+  const lines = content.split('\n');
+  let inBlock = false;
+  const blockLines = [];
+
+  for (let i = 0; i < lines.length && i < 50; i++) {
+    const trimmed = lines[i].trim();
+    if (trimmed.startsWith('//') && !trimmed.startsWith('///')) {
+      const inner = trimmed.slice(2).trim();
+      if (inner === '@ai-meta' || inner.startsWith('@ai-meta')) {
+        inBlock = true;
+        blockLines.push(inner);
+        continue;
+      }
+      if (inBlock) {
+        blockLines.push(inner);
+      }
+    } else if (inBlock) {
+      break;
+    }
+  }
+
+  return inBlock && blockLines.length > 1 ? blockLines : null;
+}
+
+/**
+ * Parse a single line for a field value, supporting both `@field value` and `field: value` syntax.
+ * @param {string} line
+ * @param {string} fieldPattern - Regex alternation of field names
+ * @returns {{ field: string, value: string }|null}
+ */
+function parseFieldLine(line, fieldPattern) {
+  // Try @field value syntax (JSDoc style)
+  let match = line.match(new RegExp(`@(${fieldPattern})\\s+(.+)`));
+  if (match) {
+    return { field: match[1], value: match[2] };
+  }
+
+  // Try field: value syntax (Swift/YAML style)
+  match = line.match(new RegExp(`^(${fieldPattern}):\\s*(.+)`));
+  if (match) {
+    return { field: match[1], value: match[2] };
+  }
+
+  return null;
+}
+
+/**
+ * Parse @ai-meta header from file content.
+ * Returns an object with extracted fields, or null if no @ai-meta block found.
+ *
+ * Supports three comment styles:
+ * - JSDoc: /** @ai-meta ... * / (TypeScript/JavaScript)
+ * - Triple-slash: /// @ai-meta ... (Swift)
+ * - Line-comment: // @ai-meta ... (Kotlin/Go)
+ *
+ * Supports two field syntaxes:
+ * - @field value (JSDoc style)
+ * - field: value (YAML-like style)
+ *
+ * @param {string} content - File content to parse
+ * @param {object} [options]
+ * @param {object} [options.fieldMap] - Map of source field names to canonical names (e.g., { mutations: 'side-effects' })
+ * @returns {object|null} Parsed metadata or null
+ */
+export function parseAiMeta(content, options = {}) {
+  const { fieldMap = {} } = options;
+
+  // Try extraction strategies in order: JSDoc → triple-slash → line-comment
+  const blockLines = extractJsDocBlock(content)
+    || extractTripleSlashBlock(content)
+    || extractLineCommentBlock(content);
+
+  if (!blockLines) return null;
+
+  const result = {};
+  const fieldPattern = FIELDS.join('|');
+
+  for (const line of blockLines) {
+    // Clean JSDoc artifacts (* at start/end of line)
+    const cleaned = line.replace(/^\s*\*\s?/, '').replace(/\s*\*\/?$/, '').trim();
+
+    const parsed = parseFieldLine(cleaned, fieldPattern);
+    if (!parsed) continue;
+
+    let { field, value } = parsed;
+
+    // Clean trailing JSDoc artifacts and em-dash descriptions
+    value = value
+      .replace(/\s*\*\/?$/, '')
+      .replace(/\s*—\s*.*$/, '')
+      .trim();
+
+    // Apply field name normalization
+    if (fieldMap[field]) {
+      field = fieldMap[field];
+    }
+
+    if (SINGLE_TOKEN_FIELDS.has(field)) {
+      value = value.split(/\s+/)[0];
+    }
+
+    if (value) {
+      result[field] = value;
+    }
+  }
+
+  return Object.keys(result).length > 0 ? result : null;
+}
+
+/** Non-canonical @type values that should map to canonical types */
+const TYPE_NORMALIZATION = {
+  card: 'component', modal: 'component', sheet: 'component', form: 'component',
+  skeleton: 'component', banner: 'component', dialog: 'component',
+  panel: 'component', section: 'component', barrel: 'index',
+};
+
+/**
+ * Normalize a @type value to a canonical type.
+ * @param {string} type - Raw type value
+ * @returns {string} Canonical type
+ */
+export function normalizeType(type) {
+  return TYPE_NORMALIZATION[type] || type;
+}

package/lib/core/config-loader.mjs

@@ -0,0 +1,85 @@
+/**
+ * @ai-meta
+ * @id module:ai-agent-infra:config-loader
+ * @domain ai-agent-infra
+ * @type module
+ * @side-effects none
+ * @stability high
+ * @complexity moderate
+ * @token-budget 200
+ * @purpose Loads and validates ai-codebase-registry project config from ai-registry.config.mjs
+ *
+ * @filechangelog
+ * @changelog 2026-02-23T10:00 [feat] [Claude Opus 4.6] Add language, fieldMap, generators defaults for multi-language support
+ * @changelog 2026-02-22T14:00 [feat] [Claude Opus 4.6] Created config loader with defaults and validation
+ */
+
+import { existsSync } from 'fs';
+import { join, resolve } from 'path';
+import { pathToFileURL } from 'url';
+
+/** Default configuration — merged with user config */
+const DEFAULTS = {
+  name: 'my-project',
+  description: '',
+  scanDirs: [{ dir: 'src', prefix: 'src' }],
+  extensions: ['.ts', '.tsx'],
+  skipDirs: ['node_modules', 'dist', '.next', 'coverage', '__tests__', '__mocks__'],
+  aliases: {},
+  language: 'typescript',  // 'typescript' | 'swift' | 'kotlin' | 'python'
+  fieldMap: {},            // field name normalization (e.g., { mutations: 'side-effects' })
+  generators: null,        // null = all, or ['manifest', 'semantic-ids', 'deps', 'side-effects', 'features']
+  router: 'none',
+  routerEntryFile: null,
+  routeBuilderFile: null,
+  dataStore: 'none',
+  registryDir: '_registry',
+  agent: 'claude-code',
+  claudemd: true,
+  rulesFile: null,
+  patternsFile: null,
+};
+
+/**
+ * Load project configuration from `ai-registry.config.mjs` in the given root directory.
+ * Falls back to defaults for any missing fields.
+ *
+ * @param {string} rootDir - Project root directory
+ * @returns {Promise<object>} Merged configuration
+ */
+export async function loadConfig(rootDir) {
+  const configPath = join(rootDir, 'ai-registry.config.mjs');
+  let userConfig = {};
+
+  if (existsSync(configPath)) {
+    const configUrl = pathToFileURL(resolve(configPath)).href;
+    const mod = await import(configUrl);
+    userConfig = mod.default || mod;
+  }
+
+  const config = { ...DEFAULTS, ...userConfig };
+
+  // Resolve relative paths
+  config.scanDirs = config.scanDirs.map(entry => ({
+    dir: resolve(rootDir, entry.dir),
+    prefix: entry.prefix || entry.dir,
+  }));
+  config.registryDir = resolve(rootDir, config.registryDir);
+  config.rootDir = rootDir;
+
+  if (config.routerEntryFile) {
+    config.routerEntryFile = resolve(rootDir, config.routerEntryFile);
+  }
+  if (config.routeBuilderFile) {
+    config.routeBuilderFile = resolve(rootDir, config.routeBuilderFile);
+  }
+
+  // Validate required fields
+  if (!config.scanDirs.length) {
+    throw new Error('ai-registry.config.mjs: scanDirs must have at least one entry');
+  }
+
+  return config;
+}
+
+export { DEFAULTS };

package/lib/core/domain-detector.mjs

@@ -0,0 +1,79 @@
+/**
+ * @ai-meta
+ * @id module:ai-agent-infra:domain-detector
+ * @domain ai-agent-infra
+ * @type module
+ * @side-effects none
+ * @stability high
+ * @complexity moderate
+ * @token-budget 150
+ * @purpose Detects domain from file path using configurable pattern rules
+ *
+ * @filechangelog
+ * @changelog 2026-02-22T14:00 [feat] [Claude Opus 4.6] Extracted from generate-registry.mjs, made configurable
+ */
+
+/**
+ * Default domain detection rules.
+ * Each rule is a { pattern: RegExp, group: number } that extracts a domain from a path.
+ * Rules are tried in order — first match wins.
+ */
+const DEFAULT_RULES = [
+  // Backend domain directories: functions/src/domains/{domain}/
+  { pattern: /^functions\/src\/domains\/([^/]+)\//, group: 1 },
+  // Frontend domain directories: apps/web/{components|hooks|pages|utils|types}/{domain}/
+  { pattern: /^apps\/web\/(?:components|hooks|pages|utils|types)\/([^/]+)\//, group: 1 },
+  // Context files: apps/web/contexts/{Name}Context.tsx
+  { pattern: /^apps\/web\/contexts\/([A-Z]\w+?)Context\.tsx$/, group: 1, transform: 'lowercase' },
+  // Service files by name: apps/web/services/.../{Name}Service.ts
+  { pattern: /^apps\/web\/services\/(?:[^/]+\/)?(\w+?)Service\.ts$/, group: 1, transform: 'lowercase' },
+  // Service directories: apps/web/services/{domain}/
+  { pattern: /^apps\/web\/services\/([^/]+)\//, group: 1, exclude: '_shared' },
+  // Feature directories: apps/web/features/{domain}/
+  { pattern: /^apps\/web\/features\/([^/]+)\//, group: 1 },
+];
+
+/** Static path-prefix → domain mappings */
+const DEFAULT_PREFIX_MAP = {
+  'packages/shared-types/': 'shared-types',
+  'packages/shared-constants/': 'shared-constants',
+  'packages/shared-schemas/': 'shared-schemas',
+  'apps/web/': 'core',
+  'functions/src/': 'backend-core',
+  'scripts/': 'infrastructure',
+};
+
+/**
+ * Create a domain detector with custom rules and prefix map.
+ *
+ * @param {object} [options]
+ * @param {Array} [options.rules] - Custom detection rules
+ * @param {object} [options.prefixMap] - Custom prefix → domain mapping
+ * @returns {(relPath: string) => string}
+ */
+export function createDomainDetector(options = {}) {
+  const rules = options.rules || DEFAULT_RULES;
+  const prefixMap = options.prefixMap || DEFAULT_PREFIX_MAP;
+
+  return function detectDomain(relPath) {
+    // Try pattern rules first
+    for (const rule of rules) {
+      const match = relPath.match(rule.pattern);
+      if (match) {
+        const value = match[rule.group];
+        if (rule.exclude && value === rule.exclude) continue;
+        return rule.transform === 'lowercase' ? value.toLowerCase() : value;
+      }
+    }
+
+    // Try prefix map
+    for (const [prefix, domain] of Object.entries(prefixMap)) {
+      if (relPath.startsWith(prefix)) return domain;
+    }
+
+    return 'unknown';
+  };
+}
+
+/** Default domain detector (BellyFun-style paths) */
+export const detectDomain = createDomainDetector();

package/lib/core/file-discovery.mjs

@@ -0,0 +1,60 @@
+/**
+ * @ai-meta
+ * @id module:ai-agent-infra:file-discovery
+ * @domain ai-agent-infra
+ * @type module
+ * @side-effects none
+ * @stability high
+ * @complexity moderate
+ * @token-budget 120
+ * @purpose Recursively discovers source files in configured directories, respecting skip rules
+ *
+ * @filechangelog
+ * @changelog 2026-02-22T16:00 [feat] [Claude Opus 4.6] Add excludePatterns option for .d.ts filtering
+ * @changelog 2026-02-22T14:00 [feat] [Claude Opus 4.6] Extracted from generate-registry.mjs
+ */
+
+import { readdirSync } from 'fs';
+import { join, relative, extname } from 'path';
+
+/**
+ * Recursively collect files under a directory, skipping excluded dirs.
+ *
+ * @param {string} dir - Absolute directory path to scan
+ * @param {string} prefix - Logical prefix for relative paths
+ * @param {{ extensions: Set<string>, skipDirs: Set<string>, excludePatterns?: string[] }} options
+ * @returns {{ fullPath: string, relPath: string }[]}
+ */
+export function collectFiles(dir, prefix, options) {
+  const { extensions, skipDirs, excludePatterns = [] } = options;
+  const results = [];
+
+  function walk(currentDir) {
+    let entries;
+    try {
+      entries = readdirSync(currentDir, { withFileTypes: true });
+    } catch (err) {
+      console.warn(`  Warning: Cannot read directory: ${currentDir} (${err.code || err.message})`);
+      return;
+    }
+
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+      const fullPath = join(currentDir, entry.name);
+
+      if (entry.isDirectory()) {
+        if (!skipDirs.has(entry.name)) {
+          walk(fullPath);
+        }
+      } else if (entry.isFile() && extensions.has(extname(entry.name))) {
+        if (excludePatterns.some(p => entry.name.endsWith(p))) continue;
+        const relFromScanDir = relative(dir, fullPath);
+        const relFromRoot = join(prefix, relFromScanDir);
+        results.push({ fullPath, relPath: relFromRoot });
+      }
+    }
+  }
+
+  walk(dir);
+  return results;
+}