structra-cli

AI-powered dependency graph analyzer and auto-fixer for TypeScript and JavaScript projects.

Structra scans your codebase for dependency issues — circular dependencies, god files, layer violations, high out-degree files — and uses Claude AI to automatically fix them.

Install

npm install -g structra-cli

Requires Node.js 18+.

Quick Start

# 1. Log in with GitHub
structra login

# 2. Scan your project
structra scan ./src

# 3. Interactively fix issues
structra fix ./src

Commands

structra scan <path>

Analyzes your source directory and reports all dependency issues.

structra scan ./src

What it detects:

• 🔴 Circular dependencies — files that import each other in a cycle (A → B → C → A)
• 🟡 God files — files imported by too many others (default threshold: 10)
• 🟡 High out-degree files — files that import too many others (default threshold: 15)
• 🟡 Misplaced files — files in the wrong directory based on their name/content
• 🟣 Layer violations — files importing from the wrong architectural layer

structra fix <path>

Interactively fix issues with AI assistance. Previews every change before applying.

structra fix ./src

# Fix only a specific issue type
structra fix ./src --type circular
structra fix ./src --type godfile
structra fix ./src --type outdegree
structra fix ./src --type layer
structra fix ./src --type misplaced

# Preview without applying changes
structra fix ./src --dry-run

# Fix all issues without prompting
structra fix ./src --all

structra report <path>

Export the scan results as an HTML or JSON report.

# HTML report (default)
structra report ./src

# JSON report
structra report ./src --format json

# Custom output path
structra report ./src --output my-report.html

structra status

Check your current plan and remaining fix quota.

structra status

structra login / structra logout

Authenticate with GitHub to enable AI-powered fixes.

structra login
structra logout

CI Mode

Use --ci to integrate with GitHub Actions or other CI pipelines. Exits with code 1 if any issues are found and outputs JSON instead of colored text.

structra scan ./src --ci

Example GitHub Actions workflow (.github/workflows/structra.yml):

name: Dependency Check
on: [push, pull_request]

jobs:
  structra:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install -g structra-cli
      - run: structra scan ./src --ci

Config File (.structrarc)

Create a .structrarc file in your project root to customize thresholds and settings. This file is committed to git so your whole team uses the same rules.

{
  "godFileThreshold": 10,
  "outDegreeThreshold": 15,
  "layers": ["controllers", "services", "repositories", "models"],
  "exclude": ["**/*.test.ts", "**/generated/**"]
}

Pricing

| Plan | Price | Fixes | | |------|-------|-------|-| | Free | $0 | 1 fix | | | Pro | $15/month | 300 fixes/month | Upgrade → |

To upgrade, visit the link above or run structra status after logging in.

License

MIT