mijo-codeflow

Analyze any codebase and produce a human-readable map of code flow — entry point → modules → function calls → features.

Install

npm install -g mijo-codeflow

Or use locally:

npm install --save-dev mijo-codeflow
npx mijo-codeflow .

CLI Usage

mijo-codeflow [path] [options]

Arguments:
  path          Path to analyze (default: current directory)

Options:
  -v, --version             Show version
  -h, --help                Show help
  -i, --interactive         Interactive accordion tree viewer
  -o, --out <path>          Write markdown report to file
  -e, --entry <path>        Entry file (auto-detected from package.json)
  --depth <n>               Max traversal depth (default: 10)
  --no-color                Disable ANSI colors
  --no-cache                Clear file cache

Examples

mijo-codeflow .                    # static dashboard for current dir
mijo-codeflow -i src/              # interactive tree for src/
mijo-codeflow -o flow.md .         # write markdown report
mijo-codeflow --depth 3 -i .       # limit depth to 3 levels
mijo-codeflow -e main.js .         # specify entry point
mijo-codeflow --no-color .         # plain text output

Static Dashboard

┌──────────────────────────────────────────────────────────────────┐
│  CODEFLOW ANALYZER v1.0.0     PROJECT: my-project                │
│  ENTRY: src/index.js     FILES SCANNED: 12                       │
│  STATUS: ● COMPLETE          DEPTH: 4 levels                     │
└──────────────────────────────────────────────────────────────────┘
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│  TOTAL FILES │ │   FEATURES   │ │ ENTRY POINTS │ │  DEAD FILES  │
│      12      │ │      5       │ │      1       │ │      0       │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
┌──────────────────────────────────┐  ┌────────────────────────────┐
│  📦 ENTRY: src/index.js          │  │ ● POST /login             │
│  ├─► src/routes/auth.js          │  │ ● POST /register          │
│  │ · POST /login → login         │  │ ● GET /                   │
│  │ · POST /register → register   │  │ ● DELETE /users/:id       │
│  │ └─► src/controllers/auth.js   │  └────────────────────────────┘
│  │   ├─► src/services/auth.js    │
│  │   │ └─► src/utils/jwt.js      │
│  │   └─► src/services/user.js    │
│  │     └─► src/db/models/User.js │
│  └─► src/routes/dashboard.js     │
│    · GET / → getData             │
└──────────────────────────────────┘

Interactive Tree Mode

┌──────────────────────────────────────────────────────────────────────────┐
│ MIJO-CODEFLOW  │  Entry: src/index.js  │  Depth: 5  │  Files: 10        │
├──────────────────────────────────────────────────────────────────────────┤
│▼ src/index.js                                                            │
│  ← authRouter from ./routes/auth                                         │
│  ← dashboardRouter from ./routes/dashboard                               │
│                                                                          │
│├─▶ src/routes/auth.js [1 imports, 2 routes]                              │
│└─▶ src/routes/dashboard.js [1 imports, 1 routes]                         │
│✦ Server started on PORT                                                  │
├──────────────────────────────────────────────────────────────────────────┤
│ src/index.js                                                             │
│ imports: authRouter ← ./routes/auth, dashboardRouter ← ./routes/dashboard│
│ imported by: (entry point)                                               │
└──────────────────────────────────────────────────────────────────────────┘

Navigate with arrow keys, expand/collapse with →/←, quit with q.

Programmatic API

import { analyze, formatDashboard, formatMarkdown } from 'mijo-codeflow'

const flowMap = analyze({
  cwd: process.cwd(),
  entry: 'src/index.js',
  maxDepth: 10,
  progress: (msg) => console.log(msg),
})

console.log(formatDashboard(flowMap, process.cwd()))

const markdown = formatMarkdown(flowMap, process.cwd())

Low-level parser utils

import { extractImports, detectExpressRoutes, detectServerStart } from 'mijo-codeflow'

const imports = extractImports('src/index.js')   // ImportInfo[]
const routes  = detectExpressRoutes(fileContent)  // RouteInfo[]
const server  = detectServerStart(fileContent)     // ServerInfo | null

How it works

1. Scans the entry file (auto-detected from package.json main field)
2. Parses AST with Babel to extract imports, Express routes, and server start
3. Recursively follows the import graph up to --depth levels
4. Detects dead files (files in src/ not reachable from the entry point)
5. Renders output as a terminal dashboard, interactive tree, or markdown

License

MIT