Skip to content

usage.md

Latest commit

 

History

History
285 lines (215 loc) · 6.02 KB

usage.md

File metadata and controls

285 lines (215 loc) · 6.02 KB
Raw

Usage Guide

This guide covers advanced usage patterns and features of DoCode.

Analyzing Different Project Types

Node.js/TypeScript Projects

cd docode/packages/core
node dist/index.js analyze --folder /path/to/node-project

DoCode automatically detects:

  • JavaScript/TypeScript files (.js, .ts, .jsx, .tsx)
  • Package dependencies (package.json)
  • Module imports/exports

Python Projects

node dist/index.js analyze --folder /path/to/python-project

Detects:

  • Python files (.py)
  • Classes, functions, methods
  • Import statements
  • Decorators

Monorepos (pnpm/npm/yarn workspaces)

node dist/index.js analyze --folder /path/to/monorepo

Handles:

  • Workspace packages
  • Cross-package dependencies
  • Shared configurations

Large Codebases (500+ files)

DoCode is optimized for speed:

  • 485 files analyzed in ~1 second
  • Cache key system avoids re-analysis
  • Progress indicators for long runs

Output Structure

After analysis, the target repository contains:

your-project/
├── .DoCode/
│   ├── knowledge-graph.json    # Structural graph (required)
│   ├── domain-graph.json       # Domain/business graph (optional)
│   ├── meta.json               # Analysis metadata
│   └── docs/                   # Generated docs (optional, future)
│       ├── README.md
│       ├── documentation-bundle.json
│       └── export-manifest.json

knowledge-graph.json

Contains the structural representation:

{
  "nodes": [
    {
      "id": "file:src/index.ts",
      "type": "file",
      "label": "index.ts",
      "path": "src/index.ts",
      "language": "typescript"
    },
    {
      "id": "func:main",
      "type": "function",
      "label": "main",
      "file": "src/index.ts",
      "line": 10
    }
  ],
  "edges": [
    {
      "source": "file:src/index.ts",
      "target": "func:main",
      "type": "defines"
    },
    {
      "source": "func:main",
      "target": "func:helper",
      "type": "calls"
    }
  ]
}

meta.json

Analysis metadata:

{
  "lastAnalyzedAt": "2026-04-20T06:10:41.234Z",
  "gitCommitHash": "7893c4df4dc3462ac45e2a11dfc7477415bcbd59",
  "version": "1.0.0-phase4",
  "analyzedFiles": 485,
  "analysisMode": "codebase",
  "sourceType": "folder"
}

Dashboard Features

Starting the Dashboard

# Set the graph directory
export GRAPH_DIR=/path/to/your-project/.DoCode

# Start development server
pnpm dev:dashboard

# Or in one line
GRAPH_DIR=/path/to/project/.DoCode pnpm dev:dashboard

Dashboard Navigation

Keyboard Shortcuts (from KeyboardShortcutsHelp.tsx):

  • Ctrl+F / Cmd+F: Open search
  • Escape: Close modals
  • ?: Show keyboard shortcuts help

Path Finder (from PathFinderModal.tsx):

  • Find shortest path between two code entities
  • Useful for understanding dependencies

Search Capabilities

The dashboard provides:

  • Full-text search across all nodes
  • Filter by type (file, function, class)
  • Navigate to definition with one click

Domain Graphs (Optional)

Domain graphs capture business logic and high-level flows:

# Enable domain graph generation (if supported)
node dist/index.js analyze --folder /path/to/project --include-domain

Domain graphs include:

  • User flows
  • Business logic relationships
  • High-level architecture patterns

Working with GitHub Repositories

Public Repositories

node dist/index.js analyze --github https://github.com/4shil/agent-sandbox

Private Repositories

For private repos, ensure you have:

  • GitHub CLI authenticated (gh auth login)
  • Or set GITHUB_TOKEN environment variable
export GITHUB_TOKEN=ghp_yourtokenhere
node dist/index.js analyze --github https://github.com/user/private-repo

Analyzing ZIP Archives

node dist/index.js analyze --zip /path/to/archive.zip

Useful for:

  • Analyzing code without cloning
  • Sharing analysis results
  • CI/CD integration

Continuous Integration (CI)

Add DoCode to your CI pipeline:

# .github/workflows/analyze.yml
name: Code Analysis
on: [push, pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm install -g pnpm
      - run: pnpm install
      - run: pnpm --filter @docode/core build
      - run: |
          cd docode/packages/core
          node dist/index.js analyze --folder .
      - uses: actions/upload-artifact@v3
        with:
          name: knowledge-graph
          path: .DoCode/

Performance Tips

Skip Re-analysis

DoCode uses a cache key system. If the code hasn't changed, it skips re-analysis:

// .DoCode/meta.json
{
  "cacheKey": "4c2e8780ef79d6eaf6a6a997c340b8435c9f3b68"
}

Analyze Specific Folders

For large monorepos, analyze only specific packages:

node dist/index.js analyze --folder ./packages/core

Exclude node_modules

DoCode automatically excludes:

  • node_modules/
  • .git/
  • dist/, build/, out/
  • Binary files

Troubleshooting

Analysis Takes Too Long

  • Check if cache is working (look for "cacheHit": true in meta.json)
  • Analyze smaller subdirectories first
  • Check for infinite loops in symlinks

Dashboard Shows No Data

  • Verify GRAPH_DIR points to a directory with knowledge-graph.json
  • Check browser console for errors
  • Ensure the JSON file is valid (use jq to validate)

Graph is Too Crowded

  • Use dashboard filters to hide certain node types
  • Zoom out to see the full structure
  • Use the path finder to focus on specific relationships

Advanced: Custom Analysis

If you need custom analysis logic, you can:

  1. Fork the core package
  2. Modify docode/packages/core/src/analyzer.ts
  3. Add custom node/edge types
  4. Rebuild: pnpm --filter @docode/core build

Next Steps