@bemedev/codebase

A powerful CLI to generate and analyze your TypeScript/JavaScript codebase. This tool allows partial importing of libraries and generates comprehensive analyses of your source code.

🚀 Main Features

• 📊 Codebase analysis: Full analysis of imports, exports and dependencies
• 🔧 Automatic generation: Creates detailed JSON analysis files
• ⚡ Intuitive CLI: Simple and effective command-line interface
• 📦 Partial import: Selective import of library parts
• 🎯 Flexible exclusion: Ability to exclude specific files
• 📈 Statistics: Detailed reports about your codebase
• 🧹 Code pruning: Automatic removal of unused declarations, empty files, and empty folders in target directories

📋 Prerequisites

• Node.js ≥ 24.0.0
• pnpm (recommended) or npm/yarn

🛠️ Installation

Global installation (recommended)

pnpm add -g @bemedev/codebase

Local installation

pnpm add @bemedev/codebase

Development installation

pnpm add -D @bemedev/codebase

🎯 Usage

CLI

Generate a codebase analysis

# Basic analysis - generates a codebase.json file
codebase

# Specify a custom output file
codebase --output my-analysis.json

# Exclude specific files
codebase --exclude node_modules dist lib build

# Use short options
codebase -o output.json node_modules dist

Available options

• -o, --output <file> : Output file (default: codebase.json)
• [excludes...] : List of files/folders to exclude

Programmatic API

Analyzing and generating the codebase JSON

import { generate, analyze } from '@bemedev/codebase';

// Analyze the codebase
const analysis = analyze({ src: 'src' });

// Generate an analysis file
await generate({
  output: 'my-codebase.json',
  excludes: ['node_modules', 'dist'],
});

Managing dependencies programmatically

You can also use the programmatic API to initialize workspace configurations and selectively add/remove files using their regular slash-separated paths (instead of dot-parsed notation).

import {
  init,
  softInit,
  add,
  remove,
  cleanup,
} from '@bemedev/codebase';
import analysis from './codebase.json';

// Initialize the project workspace
init(analysis.CODEBASE_ANALYSIS, {
  root: 'my-project-src',
  json: '.project-codebase.json',
});

// Rebuild types and imports structure if configuration already exists
softInit(analysis.CODEBASE_ANALYSIS, {
  root: 'my-project-src',
  json: '.project-codebase.json',
});

// Add files dynamically using regular slash-separated paths
add(
  analysis.CODEBASE_ANALYSIS,
  '.project-codebase.json',
  'nested/Tooltip',
);

// Remove files dynamically using regular slash-separated paths
remove(
  analysis.CODEBASE_ANALYSIS,
  '.project-codebase.json',
  'nested/Tooltip',
);

// Reset target folder files list configuration to an empty array
cleanup.files('.project-codebase.json');

// Delete the generated target directory
cleanup('my-project-src');

// Delete the target directory and remove the configuration JSON file
cleanup.all('my-project-src', '.project-codebase.json');

Pruning unused code programmatically

You can use the lift function to prune unused declarations (references, types, variables, classes, functions, or enums) and clean up imports within a target folder, automatically deleting files and folders that become empty.

import { lift, LiftOutput } from '@bemedev/codebase';
import { Project } from 'ts-morph';
import analysis from './codebase.json';

// Prune unused code and perform tree shaking using the codebase configuration path and optional exceptions
// It returns a detailed report of deleted elements
const result: LiftOutput = lift(
  analysis.CODEBASE_ANALYSIS,
  '.project-codebase.json',
  'exceptionVar1',
  'exceptionVar2',
);

/*
result is of type:
{
  tokens: string[];      // Names of deleted unused tokens
  imports: string[];     // Text of removed imports
  files: string[];       // Paths of deleted empty files
  directories: string[]; // Paths of deleted empty directories
}
*/

// Optionally pass an existing ts-morph Project instance to reuse
const project = new Project({ tsConfigFilePath: 'tsconfig.json' });
const result2 = lift(
  analysis.CODEBASE_ANALYSIS,
  '.project-codebase.json',
  'exceptionVar1',
  project,
);

Helper utilities

You can also use helper utilities exported from the library:

import { hasNoDeclarations } from '@bemedev/codebase';
import { Project } from 'ts-morph';

const project = new Project();
const sf = project.createSourceFile('test.ts', 'export const a = 1;');

// Check if a source file contains no declarations (types, variables, classes, functions, enums, interfaces, namespaces)
// Also considers files with live re-exports as non-empty
console.log(hasNoDeclarations(sf)); // false

📊 Output format

The generated JSON file contains:

{
  "STATS": {
    "files": 42,
    "imports": 156,
    "exports": 89
  },
  "CODEBASE_ANALYSIS": {
    "src/index.ts": {
      "imports": ["./functions", "./types"],
      "relativePath": "src/index.ts",
      "text": "export * from './functions';"
    }
  }
}

🏗️ Project structure

src/
├── cli/           # CLI interface
├── functions/     # Core functions
│   ├── add.ts     # Add dependencies
│   ├── generate.ts # Generate analysis
│   ├── init.ts    # Initialization
│   ├── lift.ts    # Code pruning/tree shaking
│   ├── remove.ts  # Removal
│   └── softInit.ts # Soft initialization helper
├── analyse.ts     # Analysis engine
├── types.ts       # TypeScript definitions
└── constants.ts   # Global constants

🧪 Development scripts

# Run tests
pnpm test

# Linting
pnpm lint

# Build
pnpm build

# Development mode with watch
pnpm dev

🎨 Examples

Analyze a React project

codebase -o react-analysis.json node_modules public build

Analyze a Node.js project

codebase -o backend-analysis.json node_modules dist coverage

Integrate into an NPM script

{
  "scripts": {
    "analyze": "codebase -o analysis/codebase.json",
    "analyze:clean": "codebase -o analysis/clean.json node_modules dist lib build"
  }
}

🤝 Contribution

Contributions are welcome! How to contribute:

1. Fork the project
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Contribution guidelines

• Follow commit conventions (Conventional Commits)
• Add tests for new features
• Update documentation when necessary
• Respect existing code style

🐛 Report a bug

If you find a bug, please open an issue with:

• A clear description of the problem
• Steps to reproduce the bug
• Your environment (OS, Node.js version, etc.)
• Error logs if available

License (MIT)

CHANGELOG

Author

chlbri, my github

Links

• Documentation