RepoMetro

See your repository, not just your files.

Zero-cost, no-AI repository analysis for GitHub. RepoMetro is a GitHub Action that scans a repository and generates a structured map — JSON, Markdown, and SVG — entirely from file metadata and git history.

No AI. No paid APIs. No external services. No CLI. No web app. It is a GitHub Action, and only a GitHub Action.

---

What RepoMetro Does

RepoMetro analyzes a GitHub repository and produces:

Output	File	Description
JSON map	repometro.json	Machine-readable structured repository data
Markdown report	repometro.md	Human-readable summary with tables and file tree
Tree SVG	repometro-tree.svg	Repository directory tree visualization
Languages SVG	repometro-languages.svg	Language distribution bar chart
Treemap SVG	repometro-treemap.svg	File size treemap visualization

It also posts a comment on pull requests summarizing the changes.

---

How It Works

Repository files
       ↓
   Scanner (traverse, filter, classify)
       ↓
   Analyzers (languages, stats, tests, deps, git, security)
       ↓
   RepoMetroData (structured JSON)
       ↓
   Generators (JSON, Markdown, SVG)
       ↓
   Artifacts / PR comments

1. Scanner — Walks the file system, respects .gitignore, detects binary files, counts lines.
2. Analyzers — Eight modular analyzers run on the scanned files:
   • Filesystem — Builds the file tree
   • Languages — Detects 25+ programming languages by extension
   • Statistics — File counts, sizes, largest files and directories
   • Tests — Detects test files and frameworks
   • Dependencies — Parses package manifests (package.json, requirements.txt, Cargo.toml, go.mod, etc.)
   • Git — Branch, commits, contributors, recent activity
   • Important Files — README, LICENSE, configs, GitHub files
   • Security — Filters sensitive files (.env, .key, .pem, credentials)
3. Generators — Convert the structured data into JSON, Markdown, and SVG outputs.
4. PR Comment — On pull requests, posts a summary of changed files, additions, deletions, and categories.

Security

RepoMetro never includes file contents. It only analyzes metadata: file names, paths, sizes, line counts, language (by extension), and dependency counts. Sensitive files are detected and excluded.

---

Using the GitHub Action

Add RepoMetro to any repository by creating a workflow file.

Quick Start

Create .github/workflows/repometro.yml in your repository:

name: RepoMetro

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read
  pull-requests: write

jobs:
  repometro:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: kirasync/repometro@v1

That's it. On every push to main and every pull request, RepoMetro will:

• Scan the repository
• Generate repometro.json, repometro.md, and SVG files
• Post a summary comment on pull requests
• Upload the output as a workflow artifact

Action Inputs

Input	Default	Description
output-dir	repometro-output	Directory for generated files
generate-json	true	Generate repometro.json
generate-markdown	true	Generate repometro.md
generate-svg	true	Generate SVG visualizations
pr-comment	true	Post a comment on pull requests
ignore	""	Comma-separated list of directories to ignore
max-file-size	10485760	Maximum file size to scan (bytes, default 10MB)

Action Outputs

Output	Description
json-path	Path to the generated repometro.json

Advanced Configuration

- uses: kirasync/repometro@v1
  with:
    output-dir: repometro-output
    generate-json: true
    generate-markdown: true
    generate-svg: true
    pr-comment: true
    ignore: node_modules,dist,build,coverage
    max-file-size: 10485760

Configuration File

You can also create a repometro.yml in your repository root:

version: 1

scan:
  hidden: false

output:
  json: true
  markdown: true
  svg: true

pullRequest:
  comment: true

ignore:
  - node_modules
  - dist
  - build
  - coverage
  - .git
  - .next
  - target

limits:
  maxFileSize: 10485760 # 10MB

Downloading Output Artifacts

The generated files are uploaded as a workflow artifact named repometro-data. You can download them from the Actions tab on GitHub, or use the actions/download-artifact action in a subsequent step:

- uses: actions/download-artifact@v4
  with:
    name: repometro-data
    path: repometro-output

---

Analysis Capabilities

Analyzer	What it detects
Filesystem	Complete file tree with metadata
Languages	25+ programming languages by extension
Statistics	File counts, sizes, largest files/dirs
Tests	Test files, directories, frameworks
Dependencies	package.json, requirements.txt, Cargo.toml, go.mod, etc.
Git	Branch, commits, contributors, recent activity
Important Files	README, LICENSE, configs, GitHub files
Security	Filters sensitive files (.env, .key, credentials)

---

Project Structure

repometro/
├── action.yml                # GitHub Action definition
├── publish.md                # How to publish the GitHub Action
├── package.json              # Root monorepo config (npm workspaces)
├── packages/
│   ├── core/                 # Analysis engine (scanner, analyzers, generators)
│   └── action/              # GitHub Action entry point
├── schemas/                  # JSON schema for repometro.json
├── examples/                 # Example configuration
├── tests/                    # Test suite
├── docs/                     # Documentation
└── .github/                  # Workflows, issue templates, PR template

---

Development

# Install dependencies
npm install

# Build all packages (core + action)
npm run build

# Run tests
npm test

Adding a New Analyzer

1. Create a file in packages/core/src/analyzers/
2. Implement the Analyzer interface:

   interface Analyzer {
     id: string;
     name: string;
     analyze(context: AnalysisContext): AnalysisResult;
   }

3. Register it in packages/core/src/index.ts
4. Add tests in tests/

See CONTRIBUTING.md for full guidelines.

---

Documentation

• Architecture — How RepoMetro is structured and how data flows
• Analyzers — What each analyzer detects
• JSON Schema — The structure of repometro.json
• Security — How RepoMetro keeps sensitive data safe
• Usage Guide — Full guide to using the GitHub Action

---

Publishing

See publish.md for step-by-step instructions on how to publish the GitHub Action.

---

License

MIT — see LICENSE.