Your First Analysis¶

This guide walks you through a complete analysis of a real Go project, explains the two analysis modes, shows you how to interpret results, and covers every output format.

Two Modes of Analysis¶

Codefang has two fundamentally different analysis engines. Understanding when to use each one is key to getting the most out of the tool.

graph LR
    A[Source files] --> B[UAST Parser<br/>Tree-sitter]
    B --> C[Unified AST]
    C --> D[Static Analyzers]
    D --> E[Report]

graph LR
    A[Git Repository] --> B[libgit2<br/>Commit Walker]
    B --> C[Diff Pipeline]
    C --> D[History Analyzers]
    D --> E[Report]

Step-by-Step: Analyzing a Go Project¶

Let's analyze the Codefang repository itself. Clone it if you have not already:

git clone https://github.com/Sumatoshi-tech/codefang.git
cd codefang

Step 1 -- Static Complexity Analysis¶

Start with a complexity scan to find the most complex functions:

codefang run -a static/complexity --format text .

Codefang -- Code Analysis Report
===============================

static/complexity:
  pkg/framework/runner.go
    Function RunPipeline            -- Cyclomatic: 12  Cognitive: 8
    Function buildPipeline          -- Cyclomatic: 7   Cognitive: 5
    Function initWorkers            -- Cyclomatic: 4   Cognitive: 3
  cmd/codefang/commands/run.go
    Function run                    -- Cyclomatic: 9   Cognitive: 7
    Function runDirect              -- Cyclomatic: 6   Cognitive: 4
  pkg/uast/parser.go
    Function Parse                  -- Cyclomatic: 6   Cognitive: 5
    Function detectLanguage         -- Cyclomatic: 5   Cognitive: 3

How to interpret: Functions with cyclomatic complexity above 10 are candidates for refactoring. Cognitive complexity captures nesting depth and control-flow breaks that make code hard for humans to understand.

Step 2 -- Halstead Metrics¶

Measure the information-theoretic complexity of your modules:

codefang run -a static/halstead --format text .

static/halstead:
  pkg/framework/runner.go
    Vocabulary: 142   Length: 389   Volume: 2776.4
    Difficulty: 28.3  Effort: 78572  Est. Bugs: 0.93
  pkg/uast/parser.go
    Vocabulary: 98    Length: 241   Volume: 1598.2
    Difficulty: 19.7  Effort: 31485  Est. Bugs: 0.53

How to interpret: High difficulty values indicate dense, hard-to-maintain code. The estimated bugs metric (Volume / 3000) gives a rough defect prediction.

Step 3 -- Burndown History¶

Now switch to history analysis. The burndown analyzer shows how code ages:

codefang run -a history/burndown --format yaml .

Step 4 -- Combine Static and History¶

Run both engines in a single invocation:

codefang run -a static/complexity,history/burndown --format json .

Codefang automatically splits the selected analyzers into static and history groups, runs each pipeline, and merges the output.

Understanding Output Formats¶

The --format flag controls how results are rendered. Every analyzer supports the universal formats; some also support format-specific extras.

Universal Formats¶

Static-Only Formats¶

Format Examples¶

codefang run -a static/complexity --format json .

{
  "static/complexity": {
    "files": {
      "pkg/framework/runner.go": {
        "functions": [
          {
            "name": "RunPipeline",
            "cyclomatic": 12,
            "cognitive": 8,
            "line_start": 45,
            "line_end": 102
          }
        ]
      }
    }
  }
}

codefang run -a static/complexity --format text .

Codefang -- Code Analysis Report
===============================

static/complexity:
  pkg/framework/runner.go
    Function RunPipeline        -- Cyclomatic: 12  Cognitive: 8

codefang run -a static/complexity --format compact .

complexity  pkg/framework/runner.go  RunPipeline  cyc=12  cog=8
complexity  pkg/uast/parser.go       Parse        cyc=6   cog=5

codefang run -a history/burndown --format yaml .

burndown:
  granularity: 30
  sampling: 30
  project:
    - [0, 1200, 1100, 980]
  ticks:
    - "2024-06-01"
    - "2024-07-01"
    - "2024-08-01"

codefang run -a history/burndown --format plot . > report.html

codefang run -a history/burndown,history/devs --format timeseries .

[
  {
    "tick": "2024-06-01",
    "burndown": { "surviving_lines": 1200 },
    "devs": { "active_developers": 3 }
  },
  {
    "tick": "2024-07-01",
    "burndown": { "surviving_lines": 1100 },
    "devs": { "active_developers": 4 }
  }
]

Configuration File¶

Instead of passing flags every time, create a .codefang.yaml file in your repository root (or $HOME):

# Analyzers to run by default (empty = all registered).
analyzers:
  - static/complexity
  - static/halstead
  - history/burndown

# Pipeline resource tuning.
pipeline:
  workers: 4              # parallel workers (0 = auto)
  memory_budget: "4GiB"   # auto-tune caches to fit this budget
  blob_cache_size: "512MiB"

# History analyzer settings.
history:
  burndown:
    granularity: 30       # days per time bucket
    sampling: 30
    track_files: false
    track_people: false
  devs:
    anonymize: false
  sentiment:
    min_comment_length: 20
    gap: 0.5

# Checkpoint for crash recovery on large repos.
checkpoint:
  enabled: true
  resume: true

CODEFANG_PIPELINE_WORKERS=8 codefang run -a history/burndown .

Useful Flags for History Analysis¶

Converting Between Formats¶

You can convert an existing report to a different format without re-running the analysis:

# Run once and save as binary
codefang run -a history/burndown --format bin . > report.bin

# Convert to YAML later
codefang run --input report.bin --format yaml

# Convert to an HTML plot
codefang run --input report.bin --format plot > dashboard.html

Next Steps¶

You now know how to run both analysis engines, interpret their output, and control the output format. Continue exploring:

• CLI Reference -- every flag and subcommand
• Configuration -- full .codefang.yaml schema
• Analyzers Overview -- deep dives into each analyzer
• MCP Integration -- connect Codefang to AI agents