@oxog/codemap

AST-based codebase structure extractor for token-efficient LLM navigation.

Scans your codebase and produces a compact structural map — function signatures, class hierarchies, type definitions, dependency graphs — that fits into an LLM's context window at 10-25x fewer tokens than reading raw source files.

v0.2.0 adds 4 new languages (Kotlin, Swift, Ruby, Dart), improves all 7 existing parsers with modern language features, and includes deep code analysis (reverse deps, circular deps, orphans, unused exports).

Install

npm install @oxog/codemap

Quick Start

import { scan } from '@oxog/codemap';

const map = await scan('./src');
console.log(map.output);
// # CODEMAP — ./src
// ## FILES
// ━━ services/user.ts (120L) [~340T]
//   ◆ UserService ← BaseService
//     .async getById(id: string) → Promise<User>
//   ◇ User { id: string, name: string }
//
// ## REVERSE DEPS (who imports me?)
//   services/user.ts ← routes/api.ts, controllers/auth.ts
//
// ## UNUSED EXPORTS
//   ⚠ utils/legacy.ts: oldHelper, deprecatedFn

Features

• 11 Languages — TypeScript/JavaScript, Go, Python, Rust, PHP, Java, C#, Kotlin, Swift, Ruby, Dart
• 4 Output Formats — Compact (default), JSON, Markdown, llms.txt
• Zero Dependencies — Everything built from scratch
• Plugin Architecture — Micro-kernel with auto-detection
• Watch Mode — Auto-regenerate on file changes
• Incremental Scanning — Git diff-based selective re-parsing
• Monorepo Support — pnpm/yarn/npm/turborepo workspaces
• CLAUDE.md Integration — Auto-inject map for AI coding assistants
• Git Hooks — Pre-commit auto-generation
• Complexity Scoring — Cyclomatic complexity per file

Code Analysis (v0.1.0)

• Reverse Dependencies — See who imports each file (kernel.ts ← builder.ts, cli.ts)
• Circular Dependencies — Detect dependency cycles (A → B → C → A)
• Orphan Files — Find dead modules not imported by anyone
• Unused Exports — Find exported symbols never imported in the project
• Entry Points — Auto-detect from package.json (main, bin, exports)

Usage

Simple API

import { scan } from '@oxog/codemap';

// Basic scan
const map = await scan('./src');

// With options
const map = await scan('./src', {
  format: 'json',
  incremental: true,
  complexity: true,
});

// Access analysis results
if (map.analysis) {
  console.log('Circular deps:', map.analysis.circularDeps);
  console.log('Orphan files:', map.analysis.orphanFiles);
  console.log('Unused exports:', map.analysis.unusedExports);
}

Builder API

import { codemap } from '@oxog/codemap';

const map = await codemap()
  .root('./src')
  .format('compact')
  .ignore('**/*.test.ts', '**/*.spec.ts')
  .languages(['typescript', 'go'])
  .incremental()
  .withComplexity()
  .withTokenCounts()
  .scan();

Watch Mode

import { codemap } from '@oxog/codemap';

const watcher = codemap()
  .root('./src')
  .debounce(300)
  .watch();

watcher.on('change', (event) => {
  console.log(`Updated: ${event.changedFiles.length} files`);
  console.log(`Tokens: ~${event.map.stats.totalTokens}`);
});

process.on('SIGINT', () => watcher.close());

CLI

# Basic scan
npx @oxog/codemap

# Custom root and format
npx @oxog/codemap ./lib --format=json

# Watch mode
npx @oxog/codemap --watch --debounce=500

# Incremental scan
npx @oxog/codemap --incremental

# Enable complexity scoring
npx @oxog/codemap --complexity

# Inject into CLAUDE.md
npx @oxog/codemap inject

# Git hooks
npx @oxog/codemap hook install
npx @oxog/codemap hook uninstall

# Initialize config
npx @oxog/codemap init

# Show stats
npx @oxog/codemap stats

Custom Plugin

import { codemap, createPlugin } from '@oxog/codemap';

const kotlinPlugin = createPlugin({
  name: 'kotlin',
  version: '1.0.0',
  install(kernel) {
    kernel.registerParser({
      name: 'kotlin',
      extensions: ['.kt', '.kts'],
      parse(content, filePath) {
        // Parse Kotlin source files
        return { /* FileAnalysis */ };
      },
    });
  },
});

const map = await codemap().use(kotlinPlugin).scan();

Output Example

# CODEMAP — ./src
# Generated: 2026-03-14 | Files: 39 | LOC: 6,869 | ~73,615 tokens

## EXTERNAL DEPS
  node:path: resolve, join, extname, relative
  node:fs: existsSync, readFileSync, writeFileSync, ...

## FILES

━━ kernel.ts (247L) [~2,667T]
  ƒ createKernel(config: CodemapConfig) → Kernel
  ƒ setupKernel(config: CodemapConfig, extraPlugins?: readonly CodemapPlugin[]) → Kernel
  ◆ Kernel ⊳ CodemapKernel<CodemapContext> (295L)
    .use(plugin: CodemapPlugin)
    .async scan() → Promise<ScanResult>
    .registerParser(parser: LanguageParser)
    .getFormatter(name: string) → OutputFormatter | undefined

━━ scanner.ts (111L) [~1,204T]
  ƒ scanDirectory() → ScannedFile[]
  ƒ readIgnoreFile(dir: string) → string[]

## DEPENDENCY GRAPH
  kernel.ts → ./errors.js, ./scanner.js, ./token-estimator.js
  scanner.ts → ./utils/glob-matcher.js, ./language-map.js

## ENTRY POINTS
  ▶ index.ts
  ▶ cli.ts

## REVERSE DEPS (who imports me?)
  kernel.ts ← builder.ts, cli.ts, index.ts, watcher.ts
  scanner.ts ← kernel.ts, plugins/optional/ignore.ts
  types.ts ← builder.ts, cli.ts, config.ts, kernel.ts, ...

## CIRCULAR DEPS
  ⟳ a.ts → b.ts → c.ts → a.ts

## ORPHAN FILES (not imported by anyone)
  ⚠ utils/deprecated.ts

## UNUSED EXPORTS (exported but never imported)
  ⚠ utils/helpers.ts: oldFunction, legacyHelper

Output Formats

| Format | Use Case | Token Efficiency | |--------|----------|-----------------| | compact | LLM context injection (default) | Best | | json | Programmatic consumption | Good | | markdown | Human reading, GitHub | Good | | llms-txt | llms.txt spec compliance | Good |

Symbol Legend

ƒ Function       ◆ Class         ◇ Interface
τ Type alias      ε Enum          κ Constant
⚛ Component      🪝 Hook          ✦ Struct
Δ Trait           λ Method         ∂ Decorator
← extends         ⊳ implements    ↗ Re-export
▶ Entry point     ⟳ Circular dep  ⚠ Warning

Configuration

// codemap.config.ts
import { defineConfig } from '@oxog/codemap';

export default defineConfig({
  root: './src',
  output: '.codemap',
  format: ['compact', 'json'],
  ignore: ['**/*.test.ts'],
  incremental: true,
  complexity: true,
  tokenCounts: true,
  monorepo: true,
});

Supported Languages

| Language | Extensions | Accuracy | |----------|-----------|----------| | TypeScript/JavaScript | .ts .tsx .js .jsx .mjs .mts | ~90% | | Go | .go | ~85% | | Python | .py | ~85% | | Rust | .rs | ~85% | | PHP | .php | ~85% | | Java | .java | ~85% | | C# | .cs | ~85% | | Kotlin | .kt .kts | ~85% | | Swift | .swift | ~85% | | Ruby | .rb | ~85% | | Dart | .dart | ~85% |

Links

• Documentation
• GitHub
• npm

License

MIT - Ersin KOC