Contributing

Contributing

Setup

git clone https://github.com/Arham-Qureshi/codebase-vis
cd codebase-vis
npm install

You'll need a C++ compiler toolchain for tree-sitter native module compilation. See Installation for platform-specific instructions.

Project Structure

codebase-vis/
├── bin/codebase-vis.js     # CLI entry
├── src/
│   ├── cli/               # Command handlers
│   │   ├── shared.js      # Shared utilities
│   │   └── commands/      # 8 command modules
│   ├── parser/            # AST parsing
│   │   ├── index.js       # Orchestrator
│   │   ├── languages.js   # Language metadata
│   │   ├── parse-worker.js# Forked worker
│   │   └── {lang}.js      # Per-language parsers
│   ├── graph/             # Graph construction
│   │   ├── builder.js     # Build + dependency resolution
│   │   ├── enricher.js    # Louvain + visual attrs
│   │   ├── formatter.js   # JSON export
│   │   └── cycle-detector.js
│   ├── utils/             # Infrastructure
│   │   ├── file-system.js # Sandboxed I/O
│   │   ├── traversal.js   # File discovery
│   │   ├── cache.js       # Incremental cache
│   │   └── worker-pool.js # Fork pool
│   └── templates/
│       ├── graph-template.js
│       └── graph.html     # Visualizer
└── test/                  # Node.js test runner

Running Tests

npm test

Tests use Node.js built-in node --test runner (no Jest/Mocha needed). Run individual test files:

npx node --test test/parser/javascript.test.js

Code Style

• ESM only — all files use import/export. No CommonJS.
• No JSDoc — prefer descriptive variable names over documentation comments
• picocolors for terminal colors (not chalk)
• @clack/prompts for interactive prompts (not inquirer)
• No try-catch wrappers around validation — let meaningful errors surface
• Descriptive variable names over abbreviations

Adding a Language

1. Create src/parser/{language}.js
   • Export { grammar, extractDependencies, extractEntities }
   • Supply tree-sitter S-expression queries for imports and entities
2. Register it in src/parser/index.js:
   • Add to GRAMMAR_MAP
   • Ensure KNOWN_EXTENSIONS covers your extensions
3. Add language metadata in src/parser/languages.js:
   • Add entry to LANGUAGES array
   • Update STACK_MARKERS if relevant (for init)
4. Create test in test/parser/{language}.test.js
5. Add fixture files if needed
6. Update the Supported Languages table in README.md

Pull Request Guidelines

• One feature per PR
• Keep the visualizer self-contained (no external dependencies beyond vis-network CDN)
• Don't change package-lock.json unless adding/modifying a dependency
• Update tests for any behavior changes

Release Process

npm version patch  # or minor / major
git push --follow-tags

Then create a GitHub Release — the publish workflow automatically publishes to npm.