{"id":35377648,"url":"https://github.com/gqfx/fnmap","last_synced_at":"2026-01-13T19:30:21.106Z","repository":{"id":331313468,"uuid":"1126131166","full_name":"gqfx/fnmap","owner":"gqfx","description":"AI code indexing tool for analyzing JS/TS code structure and generating structured code maps","archived":false,"fork":false,"pushed_at":"2026-01-03T02:54:02.000Z","size":529,"stargazers_count":14,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-06T03:55:25.839Z","etag":null,"topics":["ai","ai-assistant","context-engineering"],"latest_commit_sha":null,"homepage":"https://fnmap.vdiff.dev/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gqfx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-01T07:22:49.000Z","updated_at":"2026-01-04T04:51:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gqfx/fnmap","commit_stats":null,"previous_names":["gqfx/fnmap"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/gqfx/fnmap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gqfx%2Ffnmap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gqfx%2Ffnmap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gqfx%2Ffnmap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gqfx%2Ffnmap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gqfx","download_url":"https://codeload.github.com/gqfx/fnmap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gqfx%2Ffnmap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28397826,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-assistant","context-engineering"],"created_at":"2026-01-02T04:50:03.151Z","updated_at":"2026-01-13T19:30:21.100Z","avatar_url":"https://github.com/gqfx.png","language":"TypeScript","readme":"# fnmap\n\n[![npm version](https://img.shields.io/npm/v/@didnhdj/fnmap.svg)](https://www.npmjs.com/package/@didnhdj/fnmap)\n[![npm downloads](https://img.shields.io/npm/dm/@didnhdj/fnmap.svg)](https://www.npmjs.com/package/@didnhdj/fnmap)\n\n\u003e AI code indexing tool for analyzing JS/TS code structure and generating structured code maps\n\n[中文文档](./README_CN.md)\n\n## Features\n\n- 🚀 **Fast Analysis**: Quickly analyze JavaScript/TypeScript code structure using AST\n- 📊 **Structured Output**: Generate `.fnmap` index files with imports, functions, classes, and constants\n- 🔗 **Call Graph**: Track function call relationships and dependencies\n- 🎯 **Git Integration**: Process only changed files for efficient workflows\n- ⚙️ **Flexible Configuration**: Support for multiple configuration methods\n- 🔌 **Pre-commit Hook**: Integrate seamlessly with git hooks\n- 📦 **Programmatic API**: Use as a library to process code strings directly\n- 🎨 **Smart Filtering**: Automatically skip type definition files and type-only files\n- 🌍 **Cross-Platform**: Normalized path handling for Windows, macOS, and Linux\n\n## Installation\n\n```bash\nnpm install -g @didnhdj/fnmap\n```\n\nOr use in your project:\n\n```bash\nnpm install --save-dev @didnhdj/fnmap\n```\n\n## Quick Start\n\n### Initialize Configuration\n\n```bash\nfnmap --init\n```\n\nThis interactive command will:\n1. Create a `.fnmaprc` configuration file in your project root\n2. Add fnmap-generated files to `.gitignore` (optional)\n3. Automatically append fnmap format documentation to:\n   - `CLAUDE.md` (project-level instructions for Claude AI)\n   - `~/.claude/CLAUDE.md` (user-level global instructions)\n   - `AGENTS.md` (project-level agent instructions)\n   - Or any custom file path you specify\n\nThe appended documentation helps AI assistants (like Claude) understand the `.fnmap` format, enabling them to:\n- Quickly navigate your codebase using the index\n- Locate functions and classes by line number\n- Understand code structure and call graphs\n- Make more informed code suggestions\n\n### Basic Usage\n\n```bash\n# Process files based on configuration\nfnmap\n\n# Process specific directory\nfnmap --dir src\n\n# Process specific files\nfnmap --files index.js,utils.js\n\n# Process git changed files\nfnmap --changed\n\n# Process git staged files (for pre-commit hook)\nfnmap --staged\n\n# Show detailed processing logs\nfnmap --log --dir src\n\n# Clear generated files\nfnmap --clear\n```\n\n## Configuration\n\nfnmap supports multiple configuration methods (in priority order):\n\n1. `.fnmaprc` - JSON configuration file\n2. `.fnmaprc.json` - JSON configuration file\n3. `package.json#fnmap` - fnmap field in package.json\n\n### Configuration Example\n\n**.fnmaprc**\n```json\n{\n  \"enable\": true,\n  \"include\": [\n    \"src/**/*.js\",\n    \"src/**/*.ts\",\n    \"src/**/*.jsx\",\n    \"src/**/*.tsx\"\n  ],\n  \"exclude\": [\n    \"node_modules\",\n    \"dist\",\n    \"build\"\n  ]\n}\n```\n\n**package.json**\n```json\n{\n  \"fnmap\": {\n    \"enable\": true,\n    \"include\": [\"src/**/*.js\", \"src/**/*.ts\"],\n    \"exclude\": [\"dist\"]\n  }\n}\n```\n\n## Output Files\n\n### .fnmap Index File\n\nThe `.fnmap` file contains structured information about your code:\n\n```\n@FNMAP src/\n#utils.js Utility functions\n  \u003cfs:readFileSync,writeFileSync\n  \u003cpath:join,resolve\n  readConfig(filePath) 10-25 Read configuration file\n  parseData(data) 27-40 Parse data →JSON.parse\n  saveFile(path,content) 42-50 Save file →fs.writeFileSync,path.join\n@FNMAP\n```\n\n**Format Description:**\n- `#filename` - File name and description\n- `\u003cmodule:members` - Imported modules and members\n- `functionName(params) startLine-endLine description →calls` - Function information with call graph\n- `ClassName:SuperClass startLine-endLine` - Class information\n- `  .methodName(params) line description →calls` - Instance method\n- `  +methodName(params) line description →calls` - Static method\n- `$constName line description` - Constant definition (`$` prefix)\n- `\u003eexport1,export2,default` - Exports (`\u003e` prefix, supports `default`, `type:Name`)\n\n## CLI Options\n\n```\nUsage: fnmap [options] [files...]\n\nOptions:\n  -v, --version          Show version number\n  -f, --files \u003cfiles\u003e    Process specified files (comma-separated)\n  -d, --dir \u003cdir\u003e        Process all code files in directory\n  -p, --project \u003cdir\u003e    Specify project root directory (default: current directory)\n  -c, --changed          Process only git changed files (staged + modified + untracked)\n  -s, --staged           Process only git staged files (for pre-commit hook)\n  -m, --mermaid [mode]   Generate Mermaid call graph (file=file-level, project=project-level)\n  -l, --log              Show detailed processing logs\n  --init                 Create default config file and setup project (interactive)\n  --clear                Clear generated files (.fnmap, *.fnmap, *.mermaid)\n  -h, --help             Display help information\n```\n\n## Programmatic API\n\nfnmap can be used as a library in your Node.js applications.\n\n### Processing Code Strings\n\n```typescript\nimport { processCode } from '@didnhdj/fnmap';\n\nconst code = `\n  export function hello(name) {\n    console.log('Hello, ' + name);\n  }\n`;\n\nconst result = processCode(code, { filePath: 'example.js' });\n\nif (result.success) {\n  console.log('Functions:', result.info.functions);\n  console.log('Imports:', result.info.imports);\n  console.log('Call Graph:', result.info.callGraph);\n} else {\n  console.error('Parse error:', result.error);\n}\n```\n\n### Processing Files\n\n```typescript\nimport { processFile } from '@didnhdj/fnmap';\n\nconst result = processFile('./src/utils.js');\n\nif (result.success) {\n  console.log('Analysis result:', result.info);\n}\n```\n\n### API Types\n\n```typescript\n// Process result type\ntype ProcessResult = ProcessSuccess | ProcessFailure;\n\ninterface ProcessSuccess {\n  success: true;\n  info: FileInfo;\n}\n\ninterface ProcessFailure {\n  success: false;\n  error: string;\n  errorType: ErrorType;\n  loc?: { line: number; column: number };\n}\n\n// File info structure\ninterface FileInfo {\n  imports: ImportInfo[];\n  functions: FunctionInfo[];\n  classes: ClassInfo[];\n  constants: ConstantInfo[];\n  callGraph: CallGraph;\n  isPureTypeFile: boolean;  // Whether file only contains type definitions\n}\n```\n\n## Use Cases\n\n### 1. AI Assistant Integration\n\nfnmap is designed to help AI coding assistants understand your codebase better:\n\n```bash\n# Initialize and setup AI documentation\nfnmap --init\n\n# Generate code index for your project\nfnmap --dir src\n```\n\nThe `.fnmap` files help AI assistants:\n- Navigate large codebases efficiently\n- Find specific functions/classes by name and line number\n- Understand module dependencies and call graphs\n- Provide context-aware code suggestions\n\n**Recommended workflow with Claude Code or similar AI tools:**\n1. Run `fnmap --init` to add format documentation to `CLAUDE.md`\n2. Generate index files with `fnmap --dir src`\n3. AI assistants will automatically read `.fnmap` files for context\n4. Update index when code changes with `fnmap --changed`\n\n### 2. Pre-commit Hook\n\nAdd to `.husky/pre-commit` or `.git/hooks/pre-commit`:\n\n```bash\n#!/bin/sh\nfnmap --staged\ngit add .fnmap\n```\n\nThis automatically updates the `.fnmap` index when committing code.\n\n### 3. CI/CD Integration\n\n```yaml\n# .github/workflows/ci.yml\n- name: Generate Code Index\n  run: |\n    npm install -g @didnhdj/fnmap\n    fnmap --dir src\n    git diff --exit-code .fnmap || echo \"Code index updated\"\n```\n\n### 4. Code Review\n\n```bash\n# Generate index for changed files\nfnmap --changed\n\n# Show detailed logs during analysis\nfnmap --log --changed\n```\n\n## Supported File Types\n\n- `.js` - JavaScript\n- `.ts` - TypeScript\n- `.jsx` - React JSX\n- `.tsx` - React TypeScript\n- `.mjs` - ES Modules\n\n**Auto-filtered files:**\n- `.d.ts`, `.d.tsx`, `.d.mts` - Type definition files\n- Files containing only `type` or `interface` declarations (pure type files)\n\n## Limitations\n\nTo ensure performance and safety, fnmap has the following default limits:\n- **File Size**: Maximum 10MB per file\n- **Directory Depth**: Maximum recursion depth of 50 levels\n\n## How It Works\n\n1. **AST Parsing**: Uses `@babel/parser` to parse code into Abstract Syntax Tree\n2. **Structure Analysis**: Traverses AST to extract imports, functions, classes, constants\n3. **Call Graph**: Tracks function call relationships and dependencies\n4. **Index Generation**: Generates compact `.fnmap` files with structured information\n\n## Examples\n\n### Example 1: Analyze Single File\n\n```bash\nfnmap --files src/utils.js\n```\n\nOutput:\n```\n==================================================\nfnmap - AI Code Indexing Tool\n==================================================\n\nAnalyzing: src/utils.js\n✓ Imports: 3, Functions: 5, Classes: 0, Constants: 2\n\nGenerating .fnmap index...\n✓ src/utils.fnmap\n\n==================================================\nComplete! Analyzed: 1, Failed: 0\n==================================================\n```\n\n### Example 2: Analyze Directory\n\n```bash\nfnmap --dir src\n```\n\nGenerates:\n- `src/.fnmap` - Code index for all files in src directory\n\n### Example 3: Git Workflow\n\n```bash\n# Make changes to code\ngit add .\n\n# Generate index for staged files\nfnmap --staged\n\n# Add updated index\ngit add .fnmap\n\n# Commit\ngit commit -m \"Update feature\"\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT\n\n## Related Projects\n\n- [@babel/parser](https://babeljs.io/docs/en/babel-parser) - JavaScript parser\n- [@babel/traverse](https://babeljs.io/docs/en/babel-traverse) - AST traversal\n- [Mermaid](https://mermaid-js.github.io/) - Diagram generation\n\n## Support\n\n- 🐛 [Report Issues](https://github.com/gqfx/fnmap/issues)\n- 💡 [Feature Requests](https://github.com/gqfx/fnmap/issues)\n- 📖 [Documentation](https://github.com/gqfx/fnmap)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgqfx%2Ffnmap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgqfx%2Ffnmap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgqfx%2Ffnmap/lists"}