repodd

Repository Due Diligence - is a utility for investors and software buyers to generate detailed report from any git based code repository.

repodd currentlly analyzes git repositiries across several categories: Team; Codebase; Engineering; Architecture; Investment Risks; Community Engagement. It extracts raw metrics, evaluates them against a configurable rules set, and generates nicely formatted reports with the help of LLM-powered narratives and summaries.

Quick Start

Clone and build

The best way to get started with repodd at this time, is to clone this repository and build the utility. It's straignt forward.

git clone https://github.com/intelligexhq/repodd
cd repodd
go build -o repodd ./cmd/repodd
# run the utility
./repodd --version

Once you have a utility, here are some starting tips.

# Initialize config (optional, creates a default .repodd.yaml config file)
repodd init

# Create full due diligence report (default Markdown, for HTML see .repodd.yaml config)
# This will automatically run repodd scan & repodd score beforehand.
repodd report /path/to/repo

# If you need scan or score steps separatly use the below
# Scan a local repo — raw metrics as JSON
repodd scan /path/to/repo

# Score against methodology rules
repodd score /path/to/repo

# Report with LLM narrative and summary enrichment (requires API key for cloud LLMs or url for local LLM model)
# API key can be configured in .repodd.yaml or env variable REPODD_LLM_API_KEY or --llm-api-key flag
repodd report /path/to/repo --llm-provider openrouter --llm-api-key xxx -o report.md

Remote repos:

repodd report https://github.com/user/repo.git

Commands

Command	Description
scan	Extract raw metrics from a repo (git history, codebase stats, infra signals, remote data)
score	Run the rule engine — evaluate metrics against methodology rules and compute weighted scores
report	Generate a full due diligence report in Markdown or HTML, enriched by an LLM summary if choosen
init	Create a .repodd.yaml config file in the current directory
rules	List all available rules with their descriptions, scoring types, and weights

Command Details

repodd scan <repo>

Outputs a JSON document with:

• git — commits, authors, contributors, bus factor, ownership concentration, commit frequency
• codebase — total files, languages, documentation checks (readme, license, changelog, etc.), source/test directory detection
• infrastructure — CI/CD, test framework, Dockerfile, linting config, docs directory, dependency files
• remote — stars, forks, open issues, health ratio (if remote access is enabled)

repodd score <repo>

Runs all applicable rules against the scanned metrics and produces a scorecard with weighted category scores (0.0–1.0) and an overall score.

repodd report <repo>

Generates a human-readable report. Options:

• -f, --format — markdown (default) or html
• -o, --output — output file path (prints to stdout if omitted)
• --llm-provider — local, openrouter, or a base URL for narrative enrichment
• --llm-base-url — OpenAI-compatible base URL, overrides the provider default (or set REPODD_LLM_BASE_URL)
• --llm-model — model name (e.g. google/gemini-2.0-flash-lite, openai/gpt-4o-mini, qwen3-coder)
• --llm-api-key — API key (or set REPODD_LLM_API_KEY env var)

repodd init

Creates a .repodd.yaml in the current directory with default configuration.

repodd rules

Prints all loaded rules grouped by category: team, codebase, engineering, risk, community.

How It Works

                          ┌──────────────────┐
                          │  Repository       │
                          │  (local or URL)   │
                          └────────┬─────────┘
                                   │
                                   ▼
  ┌──────────────────────────────────────────────────┐
  │  Scanner Layer                                   │
  │  ───────────────                                 │
  │  • GitScanner — commits, authors, contributors   │
  │  • CodebaseScanner — files, languages, docs      │
  │  • InfraScanner — CI, tests, deps, docker        │
  │  • RemoteScanner — stars, forks, issues          │
  └──────────────────────┬───────────────────────────┘
                         │ raw metrics
                         ▼
  ┌──────────────────────────────────────────────────┐
  │  Rule Engine                                     │
  │  ───────────                                     │
  │  • 32 rules across 5 categories                  │
  │  • Scoring operators: binary, inverse_binary,    │
  │    linear, decay                                 │
  │  • Condition operators: gt, lt, gte, lte, eq,    │
  │    exists, between, contains                     │
  └──────────────────────┬───────────────────────────┘
                         │ rule scores
                         ▼
  ┌──────────────────────────────────────────────────┐
  │  Score Calculator                                │
  │  ─────────────────                                │
  │  • Weighted category averages                    │
  │  • Overall composite score (0.0–1.0)            │
  └──────────────────────┬───────────────────────────┘
                         │ scorecard
                         ▼
  ┌──────────────────────────────────────────────────┐
  │  Report Renderer                                 │
  │  ────────────────                                 │
  │  • MarkdownReporter — formatted .md files        │
  │  • HTMLReporter — styled .html files             │
  │  • Optional LLM narrative enrichment             │
  └──────────────────────────────────────────────────┘

Scoring Categories

Category	Weight	What It Measures
Team	30%	Commits, author diversity, bus factor, contributor distribution
Codebase	25%	File count, language diversity, documentation quality, test/source structure
Engineering	20%	CI/CD, test framework, Docker support, linting, dependency management
Risk	15%	Bus factor, ownership concentration, stale branches, issues
Community	10%	Stars, forks, issue health, engagement signals

Scoring Operators

• binary — condition met = max_score, not met = min_score
• inverse_binary — condition met = min_score, not met = max_score
• linear — score proportional to metric value between min and max
• decay — score decays exponentially as metric increases past a threshold

Configuration

All configuration is optional — every field has a sensible default.

Config File Discovery

Config is loaded from the first match found by walking up from the current directory to root:

1. ./.repodd.yaml
2. ./.repodd.yml
3. ./.repodd/config.yaml

Create one with repodd init:

# LLM enrichment (optional)
llm_provider: local          # local, openrouter, or a base URL
# llm_base_url: http://localhost:11434/v1  # overrides the provider default
llm_model: qwen3-coder
# llm_api_key: ""            # required for openrouter; or set REPODD_LLM_API_KEY env var

# Reporting
report_format: markdown      # markdown or html

# Rules
rules_dir: rules             # directory containing methodology .yaml files

# Remote data (GitHub/GitLab)
remote_enabled: true         # fetch stars, forks, issues from remote API

Security: Add .repodd.yaml to .gitignore if it contains an API key. The init command's default output has the key field commented out.

Priority Order

Values are resolved with this precedence (highest wins):

1. CLI flags — e.g. --llm-provider openrouter --llm-api-key sk-...
2. Environment variables:
   • REPODD_LLM_API_KEY — API key for OpenRouter
   • REPODD_LLM_PROVIDER — provider name (local, openrouter, or a base URL)
   • REPODD_LLM_BASE_URL — OpenAI-compatible base URL override
   • REPODD_LLM_MODEL — model name
   • REPODD_VERBOSE — verbose logging (1, true, yes)
3. .repodd.yaml file values
4. Built-in defaults

LLM Setup

# OpenRouter (recommended)
export REPODD_LLM_API_KEY="sk-or-v1-..."
repodd report /path/to/repo --llm-provider openrouter --llm-model openai/gpt-4o-mini -o report.md

# Local, OpenAI-compatible runtime (Ollama, llama.cpp, LM Studio, vLLM) — no API key needed
# Defaults to Ollama's endpoint (http://localhost:11434/v1)
repodd report /path/to/repo --llm-provider local --llm-model qwen3-coder -o report.md

# Point at a different local runtime (e.g. llama.cpp / LM Studio on :8080)
repodd report /path/to/repo --llm-base-url http://localhost:8080/v1 --llm-model qwen3-coder -o report.md

Example Usage

Scan a local repo

$ repodd scan /path/to/repo
{
  "git": {
    "total_commits": 842,
    "total_authors": 23,
    "bus_factor": 3,
    "top2_ownership_pct": 0.45,
    "commit_frequency": 1.2
  },
  "codebase": {
    "total_files": 312,
    "languages": {"Go": 180, "TypeScript": 62, "YAML": 30},
    "has_readme": true,
    "has_license": true
  },
  "infra": {
    "has_ci": true,
    "ci_type": "github_actions",
    "has_tests": true,
    "has_dockerfile": true
  },
  "remote": {
    "stars": 1200,
    "forks": 85,
    "open_issues": 14
  }
}

Score a repo

$ repodd score /path/to/repo

Repo: my-project
Branch: main
Time: 1.23s

Overall Score: 0.68

Category        Score   Weighted Rules
--------------- ------- ------- -------------
team            0.72    0.22    5/5
codebase        0.65    0.16    6/7
engineering     0.80    0.16    7/7
risk            0.55    0.08    5/6
community       0.40    0.04    4/6

Generate a report

$ repodd report /path/to/repo -f markdown -o report.md
# Due Diligence Report: my-project
# Overall Score: 0.68
# ...

$ repodd report /path/to/repo -f html -o report.html
# Opens in browser — styled HTML with score breakdown and rule details

With LLM narrative

export REPODD_LLM_API_KEY="sk-or-v1-..."
repodd report /path/to/repo --llm-provider openrouter -o report.md

Custom Rules

Rules are YAML files in the rules/ directory. The engine loads all .yaml files and evaluates each rule against the scanned metrics.

Rule Anatomy

- id: team_commit_frequency       # unique identifier
  name: Commit Velocity            # human-readable name
  category: team                   # team, codebase, engineering, risk, community
  weight: 0.15                     # relative weight within category (0.0–1.0)
  description: Consistent commit activity
  metrics:                         # list of dotted metric paths used
    - git.commit_frequency
  evaluation:                      # condition(s) that gate the score
    type: threshold                # threshold = all must pass, any = at least one
    conditions:
      - metric: git.commit_frequency
        operator: gte              # gt, lt, gte, lte, eq, exists, between
        value: 1
  scoring:                         # how to compute the score
    type: linear                   # binary, inverse_binary, linear, decay
    max_score: 1.0
    min_score: 0.0
    params:                        # varies by scoring type
      optimal: 30
      min: 0
      max: 60

Scoring Types

Type	Behavior	Params
binary	Condition met → max_score, else min_score	none
inverse_binary	Condition met → min_score, else max_score	none
linear	Score scales linearly from min to optimal	optimal, min, max
decay	Exponential decay: start × 0.5^(value / half_life)	half_life, start

Condition Operators

Operator	Description
eq	Metric value equals expected value
gt / gte	Metric is greater than (or equal to) threshold
lt / lte	Metric is less than (or equal to) threshold
exists	Metric value is non-nil and non-empty
between	Metric is within [min, max] range (value is a list [min, max])

Evaluation Types

• threshold — all conditions must be satisfied (AND logic)
• any — at least one condition must be satisfied (OR logic)

Writing Your Own Rules

1. Create a .yaml file in your rules/ directory
2. Reference any dotted metric path (e.g. git.bus_factor, codebase.has_readme, infra.has_ci, remote.stars)
3. Pick the scoring type that matches the behavior you want
4. Run repodd rules -r rules/ to verify your rules load correctly

Available metric namespaces:

Namespace	Metrics
git.*	total_commits, total_authors, bus_factor, commit_frequency, days_since_last_commit, top2_ownership_pct, author_diversity_score
codebase.*	total_files, total_lines, languages, has_readme, has_license, has_changelog, has_contributing, has_code_of_conduct, src_dirs
infra.*	has_ci, ci_type, has_tests, test_framework, has_dockerfile, has_linting, has_docs_dir, deps_total
remote.*	stars, forks, open_issues, watchers, has_funding, has_governance

Development

git clone https://github.com/intelligexhq/repodd
cd repodd

# Build
go build -o repodd ./cmd/repodd

# Run
./repodd --help

# Format
gofmt -w .

# Vet
go vet ./...

# Test with coverage
go test ./... -cover

# Lint (requires golangci-lint)
golangci-lint run ./...

License

MIT