RepoStem CLI

A command-line interface for architectural drift and blast-radius tracking for JavaScript/TypeScript repositories. RepoStem models repositories as dependency graphs and tracks how their architecture evolves over time, surfacing structural risk, blast radius, circular dependencies, and emerging hotspots.

🚀 Features

• Structural Analysis: Complete repository-wide dependency graph analysis
• Risk Scoring: File-level risk metrics (centrality, coupling, churn, circular dependencies)
• Impact Analysis: Understand the transitive impact of modifying any file
• Circular Dependency Detection: Identify and visualize dependency cycles
• Snapshot Persistence: Store and retrieve architectural snapshots over time
• Architectural Drift Detection: Compare snapshots to identify structural changes
• Hotspot Identification: Find files with high risk and impact that need attention
• Trend Tracking: Monitor how hotspots evolve across snapshots
• Branch Filtering: Analyze snapshots by branch for multi-branch workflows
• AI-Powered Insights: Get natural language explanations (risk, impact, trend, drift, hotspot queries)
• Multiple Output Formats: Text, JSON, and table output options
• Database Migrations: Manage storage backend schema updates

📦 Installation

Global Installation

npm install -g @repostem/cli

Local Installation

npm install @repostem/cli

Development Installation

git clone https://github.com/your-org/repostem.git
cd repostem
pnpm install
pnpm build

🎯 Quick Start

Analyze a Repository

# Analyze current directory
repostem analyze

# Analyze specific repository
repostem analyze -r /path/to/your/repo

# Output as JSON
repostem analyze -r ./my-repo -o json

Check File Risk

# Check risk for a specific file
repostem risk src/utils/helpers.js

# Check risk in a different repository
repostem risk src/components/Button.tsx -r /path/to/repo

Analyze Impact

# See what would be affected by changing a file
repostem impact src/core/engine.js

# Impact analysis with JSON output
repostem impact src/api/client.ts -o json

Detect Circular Dependencies

# Find all circular dependency cycles
repostem cycles

# Cycles in specific repository
repostem cycles -r /path/to/repo

View Snapshot History

# Show persisted analysis history for the current repository
repostem history

# History for a specific branch
repostem history -b main

# History with JSON output
repostem history -o json

Identify Architectural Hotspots

# Show current architectural hotspots
repostem hotspot

# Hotspots for a specific repository
repostem hotspot -r /path/to/repo

# Hotspots with JSON output
repostem hotspot -o json

# Show hotspot trends over time
repostem hotspot --trend

# Compare hotspots with a specific snapshot
repostem hotspot --trend --since <snapshot-id>

Detect Architectural Drift

# Compare the two most recent snapshots
repostem drift

# Compare current snapshot with a specific baseline
repostem drift --since <snapshot-id>

# Drift for a specific repository
repostem drift -r /path/to/repo

Ask AI Questions

# Get AI explanations about structural metrics
repostem ask "What are the risks in src/utils.js?"
repostem ask "What would break if I change src/components/Button.tsx?"
repostem ask "Is src/api/client.js fragile?"

📋 Commands

init

Initialize repository for snapshot persistence with SQLite or PostgreSQL.

repostem init [options]

Options:

• -r, --repo <path>: Path to repository (default: current directory)
• -s, --storage <type>: Storage type - sqlite or postgresql (default: prompt)
• -p, --db-path <path>: Database path for SQLite or connection string for PostgreSQL

Reconfiguration: If you run repostem init on an already initialized repository, you'll see options:

• Reconfigure storage backend - Change storage type/path while preserving repo_id
• Reset persistence - Delete all snapshots but keep repo record
• Cancel - Exit without changes

Example:

# Interactive mode
repostem init

# With flags
repostem init --storage sqlite --db-path .repostem.db
repostem init --storage postgresql --db-path postgresql://user:pass@localhost/db

migrate

Run database migrations for the storage backend. Useful for updating the database schema when RepoStem is upgraded.

repostem migrate [options]

Options:

• -r, --repo <path>: Path to repository (default: current directory)
• --status: Show migration status without running migrations

Example:

# Run migrations
repostem migrate

# Check migration status
repostem migrate --status

analyze

Run full structural analysis on the repository and print project-level structural summary.

If the repository has been initialized with repostem init, the analysis snapshot will be automatically persisted to the configured storage.

repostem analyze [options]

Options:

• -r, --repo <path>: Path to repository (default: current directory)
• -o, --output <format>: Output format - text, json, table (default: text)

Example:

repostem analyze -r ./my-project -o table

risk

Compute structural risk for a specific file.

repostem risk <filePath> [options]

Arguments:

• filePath: File path to analyze

Options:

• -r, --repo <path>: Path to repository (default: current directory)
• -o, --output <format>: Output format - text, json, table (default: text)

Example:

repostem risk src/core/engine.ts -r ./my-project

impact

Show transitive impact of a file - what other files would be affected by changes.

repostem impact <filePath> [options]

Arguments:

• filePath: File path to analyze

Options:

• -r, --repo <path>: Path to repository (default: current directory)
• -o, --output <format>: Output format - text, json, table (default: text)

Example:

repostem impact src/utils/helpers.js

cycles

List circular dependency groups in the repository.

repostem cycles [options]

Options:

• -r, --repo <path>: Path to repository (default: current directory)
• -o, --output <format>: Output format - text, json, table (default: text)

Example:

repostem cycles -r ./my-project -o json

drift

Detect architectural drift between snapshots. Compares structural metrics across snapshots to identify risk changes, impact changes, new cycles, and hotspot evolution.

repostem drift [options]

Options:

• -r, --repo <path>: Path to repository (default: current directory)
• -b, --branch <name>: Filter by branch (defaults to the current Git branch when in a Git repo)
• --no-branch-filter: Show snapshots from every branch (overrides branch detection)
• --since <id>: Snapshot ID to compare against (from history)
• -o, --output <format>: Output format - text, json (default: text)

Example:

# Compare the two most recent snapshots
repostem drift

# Compare current snapshot with a specific baseline
repostem drift --since 69b34f51-0ece-4072-b943-83f27328be84

# Drift analysis with JSON output
repostem drift -o json

history

Display persisted snapshot history for the current repository. Requires the repository to be initialized with repostem init.

repostem history [options]

Options:

• -r, --repo <path>: Path to repository (default: current directory)
• -b, --branch <name>: Filter by branch (defaults to the current Git branch when in a Git repo)
• --no-branch-filter: Show snapshots from every branch (overrides branch detection)
• -o, --output <format>: Output format - text, json, table (default: table)

Example:

repostem history
repostem history -b main -o json
repostem history --no-branch-filter

hotspot

Identify architectural hotspots - files with high structural risk and impact that warrant attention.

repostem hotspot [options]

Options:

• -r, --repo <path>: Path to repository (default: current directory)
• -o, --output <format>: Output format - text, json (default: text)
• --trend: Show hotspot evolution over time (requires at least 2 snapshots)
• --since <snapshotId>: Compare with specific snapshot (only with --trend)
• --branch <name>: Filter snapshots by branch (only with --trend)
• --no-branch-filter: Disable branch filtering (only with --trend)

Output includes:

• Risk score with classification (Low/Medium/High)
• Impact ratio as percentage
• Churn score with classification
• Circular dependency indicator
• Overall hotspot score with classification

Trend output includes:

• Previous and current risk scores with delta
• Previous and current impact ratios with delta
• Trend score with classification (Low/Medium/High)

Example:

# Show current hotspots
repostem hotspot

# Hotspots for a specific repository
repostem hotspot -r /path/to/repo

# JSON output for integration
repostem hotspot -o json

# Show hotspot trends over time
repostem hotspot --trend

# Compare hotspots with a specific snapshot
repostem hotspot --trend --since 69b34f51-0ece-4072-b943-83f27328be84

# Trend analysis for a specific branch
repostem hotspot --trend --branch main

# Trend analysis across all branches
repostem hotspot --trend --no-branch-filter

ask

AI explanation of file-level structural metrics and architectural questions.

repostem ask <question> [options]

Arguments:

• question: Question about a specific file or architectural concern

Options:

• -r, --repo <path>: Repository path (default: current directory)
• -o, --output <format>: Output format - text, json, table (default: text)
• -b, --branch <name>: Filter by branch (defaults to the current Git branch when in a Git repo)
• --no-branch-filter: Show snapshots from every branch (overrides branch detection)
• --since <id>: Snapshot ID to compare against (from history)

Supported Question Types:

The ask command now supports multiple types of questions:

Risk-related questions (requires file path):

• Keywords: risk, risks, threat, threats, danger, hazard, fragile
• Example: repostem ask "What are the risks in src/utils.js?"

Impact-related questions (requires file path):

• Keywords: impact, impacts, consequence, consequences, effect, effects, result, results
• Example: repostem ask "What would be the impact of changing src/core/engine.ts?"

Trend questions (no file path required):

• Keywords: trend, getting worse, increasing, decreasing, evolving, evolution
• Example: repostem ask "What is the trend of hotspots?"
• Example: repostem ask "Is the architecture getting worse?"
• Options: Supports --branch, --no-branch-filter, --since for snapshot filtering

Drift questions (no file path required):

• Keywords: drift, changed, changes, difference, compare
• Example: repostem ask "What has changed in the architecture?"
• Example: repostem ask "What is the drift between snapshots?"
• Options: Supports --branch, --no-branch-filter, --since for snapshot filtering

Hotspot questions (no file path required):

• Keywords: hotspot, biggest problem, problematic, worst, most critical
• Example: repostem ask "What are the hotspots?"
• Example: repostem ask "What is the biggest problem in the codebase?"

Examples:

# Risk analysis questions
repostem ask "What are the risks in src/utils.js?"
repostem ask "Is src/api/client.js fragile?"
repostem ask "What threats exist in src/components/Button.tsx?"

# Impact analysis questions
repostem ask "What would be the impact of changing src/core/engine.ts?"
repostem ask "What are the consequences of modifying src/utils/helpers.js?"
repostem ask "Show me the effects of updating src/api/client.ts"

# Trend analysis questions
repostem ask "What is the trend of hotspots?"
repostem ask "Is the architecture getting worse?"
repostem ask "What is the evolution of risk?"

# Trend analysis with options
repostem ask "What is the trend of hotspots?" --branch main
repostem ask "What is the trend of hotspots?" --since <snapshot-id>
repostem ask "What is the trend of hotspots?" --no-branch-filter

# Drift analysis questions
repostem ask "What has changed in the architecture?"
repostem ask "What is the drift between snapshots?"
repostem ask "Compare the current state with previous"

# Drift analysis with options
repostem ask "What has changed?" --branch main
repostem ask "What has changed?" --since <snapshot-id>
repostem ask "What has changed?" --no-branch-filter

# Hotspot analysis questions
repostem ask "What are the hotspots?"
repostem ask "What is the biggest problem in the codebase?"
repostem ask "Which files are most problematic?"

Note: Risk and impact questions require a file path in the question. Trend, drift, and hotspot questions do not require a file path. The --branch, --no-branch-filter, and --since options only apply to trend and drift questions.

📊 Risk Metrics

RepoStem computes four key structural metrics, all normalized to 0.0-1.0 range:

Centrality (Weight: 40%)

Measures how many files depend on a given file.

• Formula: inDegree(F) / (totalFiles - 1)
• High values: Critical files that many others depend on

Coupling (Weight: 30%)

Measures structural connectivity (both incoming and outgoing dependencies).

• Formula: (inDegree + outDegree) / (2 * (totalFiles - 1))
• High values: Highly connected files with many dependencies

Churn (Weight: 20%)

Measures historical volatility from git commit frequency.

• Formula: commitCount(F) / maxCommits
• High values: Frequently changed files that may be unstable

Circular Dependency (Weight: 10%)

Binary penalty for files involved in circular dependencies.

• Values: 0 (no cycles) or 1 (part of a cycle)
• Impact: Files in cycles are inherently fragile

Risk Score Formula

risk = 0.4*centrality + 0.3*coupling + 0.2*churn + 0.1*circularPenalty

Interpretation:

• 0.0-0.3: Low structural risk
• 0.3-0.6: Moderate structural risk
• 0.6-1.0: High structural risk

🔧 Configuration

Environment Variables

• OPENAI_API_KEY: Required for AI-powered ask command

Supported Languages

• JavaScript (.js, .jsx)
• TypeScript (.ts, .tsx)

.gitignore Integration

By default (respectGitignore: true), RepoStem respects your .gitignore patterns. Set to false to analyze gitignored files.

📝 Output Formats

Text Format

Human-readable output with colors and formatting:

repostem analyze -o text

JSON Format

Machine-readable JSON for integration with other tools:

repostem analyze -o json

Table Format

Structured tabular output for quick scanning:

repostem analyze -o table

🎯 Use Cases

Code Review

# Before merging changes
repostem risk src/components/NewFeature.tsx
repostem impact src/components/NewFeature.tsx

Refactoring Planning

# Identify risky files to refactor
repostem analyze
repostem cycles

Architecture Documentation

# Generate architectural insights
repostem ask "What are the most critical files in this codebase?"
repostem ask "Which files have the highest coupling?"

Technical Debt Assessment

# Identify technical debt hotspots
repostem analyze -o json | jq '.files[] | select(.risk > 0.6)'

🚨 Limitations

• File-level analysis: Currently analyzes at file level, not function level
• JavaScript/TypeScript only: Supports JS/TS repositories in v0.1
• Git history required: Churn analysis requires git repository
• Heuristic risk scores: Risk scores are heuristic-based, not statistically validated
• OpenAI dependency: AI features require OpenAI API key

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/your-org/repostem.git
cd repostem
pnpm install
pnpm build

Running Tests

pnpm test

Building CLI

cd apps/cli
pnpm build

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• RepoStem Documentation
• Core Engine
• Examples
• Issues

🆘 Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions

RepoStem - AI-powered structural risk analysis for healthier codebases.