AI code indexing tool for analyzing JS/TS code structure and generating structured code maps to help AI understand code quickly
npm install @didnhdj/fnmap

> AI code indexing tool for analyzing JS/TS code structure and generating structured code maps
- π Fast Analysis: Quickly analyze JavaScript/TypeScript code structure using AST
- π Structured Output: Generate .fnmap index files with imports, functions, classes, and constants
- π Call Graph: Track function call relationships and dependencies
- π― Git Integration: Process only changed files for efficient workflows
- βοΈ Flexible Configuration: Support for multiple configuration methods
- π Pre-commit Hook: Integrate seamlessly with git hooks
- π¦ Programmatic API: Use as a library to process code strings directly
- π¨ Smart Filtering: Automatically skip type definition files and type-only files
- π Cross-Platform: Normalized path handling for Windows, macOS, and Linux
``bash`
npm install -g @didnhdj/fnmap
Or use in your project:
`bash`
npm install --save-dev @didnhdj/fnmap
`bash`
fnmap --init
This interactive command will:
1. Create a .fnmaprc configuration file in your project root.gitignore
2. Add fnmap-generated files to (optional)CLAUDE.md
3. Automatically append fnmap format documentation to:
- (project-level instructions for Claude AI)~/.claude/CLAUDE.md
- (user-level global instructions)AGENTS.md
- (project-level agent instructions)
- Or any custom file path you specify
The appended documentation helps AI assistants (like Claude) understand the .fnmap format, enabling them to:
- Quickly navigate your codebase using the index
- Locate functions and classes by line number
- Understand code structure and call graphs
- Make more informed code suggestions
`bashProcess files based on configuration
fnmap
Configuration
fnmap supports multiple configuration methods (in priority order):
1.
.fnmaprc - JSON configuration file
2. .fnmaprc.json - JSON configuration file
3. package.json#fnmap - fnmap field in package.json$3
.fnmaprc
`json
{
"enable": true,
"include": [
"src/*/.js",
"src/*/.ts",
"src/*/.jsx",
"src/*/.tsx"
],
"exclude": [
"node_modules",
"dist",
"build"
]
}
`package.json
`json
{
"fnmap": {
"enable": true,
"include": ["src//.js", "src//.ts"],
"exclude": ["dist"]
}
}
`Output Files
$3
The
.fnmap file contains structured information about your code:`
@FNMAP src/
#utils.js Utility functions
readConfig(filePath) 10-25 Read configuration file
parseData(data) 27-40 Parse data βJSON.parse
saveFile(path,content) 42-50 Save file βfs.writeFileSync,path.join
@FNMAP
`Format Description:
-
#filename - File name and description
- - Function information with call graph
- ClassName:SuperClass startLine-endLine - Class information
- .methodName(params) line description βcalls - Instance method
- +methodName(params) line description βcalls - Static method
- $constName line description - Constant definition ($ prefix)
- >export1,export2,default - Exports (> prefix, supports default, type:Name)CLI Options
`
Usage: fnmap [options] [files...]Options:
-v, --version Show version number
-f, --files Process specified files (comma-separated)
-d, --dir Process all code files in directory
-p, --project Specify project root directory (default: current directory)
-c, --changed Process only git changed files (staged + modified + untracked)
-s, --staged Process only git staged files (for pre-commit hook)
-m, --mermaid [mode] Generate Mermaid call graph (file=file-level, project=project-level)
-l, --log Show detailed processing logs
--init Create default config file and setup project (interactive)
--clear Clear generated files (.fnmap, .fnmap, .mermaid)
-h, --help Display help information
`Programmatic API
fnmap can be used as a library in your Node.js applications.
$3
`typescript
import { processCode } from '@didnhdj/fnmap';const code =
;const result = processCode(code, { filePath: 'example.js' });
if (result.success) {
console.log('Functions:', result.info.functions);
console.log('Imports:', result.info.imports);
console.log('Call Graph:', result.info.callGraph);
} else {
console.error('Parse error:', result.error);
}
`$3
`typescript
import { processFile } from '@didnhdj/fnmap';const result = processFile('./src/utils.js');
if (result.success) {
console.log('Analysis result:', result.info);
}
`$3
`typescript
// Process result type
type ProcessResult = ProcessSuccess | ProcessFailure;interface ProcessSuccess {
success: true;
info: FileInfo;
}
interface ProcessFailure {
success: false;
error: string;
errorType: ErrorType;
loc?: { line: number; column: number };
}
// File info structure
interface FileInfo {
imports: ImportInfo[];
functions: FunctionInfo[];
classes: ClassInfo[];
constants: ConstantInfo[];
callGraph: CallGraph;
isPureTypeFile: boolean; // Whether file only contains type definitions
}
`Use Cases
$3
fnmap is designed to help AI coding assistants understand your codebase better:
`bash
Initialize and setup AI documentation
fnmap --initGenerate code index for your project
fnmap --dir src
`The
.fnmap files help AI assistants:
- Navigate large codebases efficiently
- Find specific functions/classes by name and line number
- Understand module dependencies and call graphs
- Provide context-aware code suggestionsRecommended workflow with Claude Code or similar AI tools:
1. Run
fnmap --init to add format documentation to CLAUDE.md
2. Generate index files with fnmap --dir src
3. AI assistants will automatically read .fnmap files for context
4. Update index when code changes with fnmap --changed$3
Add to
.husky/pre-commit or .git/hooks/pre-commit:`bash
#!/bin/sh
fnmap --staged
git add .fnmap
`This automatically updates the
.fnmap index when committing code.$3
`yaml
.github/workflows/ci.yml
- name: Generate Code Index
run: |
npm install -g @didnhdj/fnmap
fnmap --dir src
git diff --exit-code .fnmap || echo "Code index updated"
`$3
`bash
Generate index for changed files
fnmap --changedShow detailed logs during analysis
fnmap --log --changed
`Supported File Types
-
.js - JavaScript
- .ts - TypeScript
- .jsx - React JSX
- .tsx - React TypeScript
- .mjs - ES ModulesAuto-filtered files:
-
.d.ts, .d.tsx, .d.mts - Type definition files
- Files containing only type or interface declarations (pure type files)Limitations
To ensure performance and safety, fnmap has the following default limits:
- File Size: Maximum 10MB per file
- Directory Depth: Maximum recursion depth of 50 levels
How It Works
1. AST Parsing: Uses
@babel/parser to parse code into Abstract Syntax Tree
2. Structure Analysis: Traverses AST to extract imports, functions, classes, constants
3. Call Graph: Tracks function call relationships and dependencies
4. Index Generation: Generates compact .fnmap files with structured informationExamples
$3
`bash
fnmap --files src/utils.js
`Output:
`
==================================================
fnmap - AI Code Indexing Tool
==================================================Analyzing: src/utils.js
β Imports: 3, Functions: 5, Classes: 0, Constants: 2
Generating .fnmap index...
β src/utils.fnmap
==================================================
Complete! Analyzed: 1, Failed: 0
==================================================
`$3
`bash
fnmap --dir src
`Generates:
-
src/.fnmap - Code index for all files in src directory$3
`bash
Make changes to code
git add .Generate index for staged files
fnmap --stagedAdd updated index
git add .fnmapCommit
git commit -m "Update feature"
``Contributions are welcome! Please feel free to submit a Pull Request.
MIT
- @babel/parser - JavaScript parser
- @babel/traverse - AST traversal
- Mermaid - Diagram generation
- π Report Issues
- π‘ Feature Requests
- π Documentation