Repository Metadata Manager v2.0

A modular repository health and compliance analysis tool. Runs offline against any local repository -- no GitHub token required for core checks. Extensible via a checker plugin architecture.

Installation

npm install -g @alteriom/repository-metadata-manager

Or as a dev dependency:

npm install --save-dev @alteriom/repository-metadata-manager

Quick Start

# Run health checks on the current repository
repo-manager check

# Output as JSON (for CI pipelines)
repo-manager check --format json

# Auto-fix detected issues (dry run)
repo-manager fix --dry-run

# Apply fixes
repo-manager fix

# Show loaded configuration
repo-manager config

CLI Commands

repo-manager check

Run all health checkers and display a scored report.

Flag	Description
-o, --only <checkers>	Comma-separated list of checkers to run
-f, --format <format>	Output format: cli (default) or json
--project <path>	Path to repository root (default: cwd)

repo-manager check --only documentation,security
repo-manager check --format json --project /path/to/repo

repo-manager fix

Auto-fix issues that have fixable remediation.

Flag	Description
--dry-run	Preview what would be fixed without writing
--project <path>	Path to repository root (default: cwd)

repo-manager config

Display the resolved configuration and detected project type.

Programmatic API

const { Engine } = require('@alteriom/repository-metadata-manager');

const engine = new Engine({ projectRoot: '/path/to/repo' });

// Run checks
const report = await engine.run();
console.log(report.score, report.grade);

// Run specific checkers
const partial = await engine.run(['documentation', 'security']);

// Fix issues
const { report: r, fixes } = await engine.fix({ dryRun: false });

Custom Checkers

const { Checker } = require('@alteriom/repository-metadata-manager');

class MyChecker extends Checker {
  constructor() {
    super({ name: 'my-check', version: '1.0.0', description: 'Custom check', defaultWeight: 10 });
  }

  async check(context) {
    const findings = [];
    if (!context.fileExists('CODEOWNERS')) {
      findings.push({
        id: 'missing-codeowners',
        severity: 'medium',
        message: 'No CODEOWNERS file',
        fixable: false,
        fix: null,
      });
    }
    return this.createResult(findings.length === 0 ? 100 : 60, findings);
  }
}

const engine = new Engine({ projectRoot: '.' });
engine.register(new MyChecker());
const report = await engine.run();

Configuration

Create .repo-manager.json in your repository root:

{
  "checkers": {
    "documentation": { "weight": 30 },
    "security": { "weight": 25 },
    "cicd": { "weight": 20 },
    "dependencies": { "weight": 15 },
    "branch-protection": { "weight": 10 },
    "iot": { "enabled": false }
  },
  "thresholds": {
    "fail": 50
  }
}

Built-in Checkers

Checker	Description
documentation	Checks for README, CHANGELOG, CONTRIBUTING, LICENSE, SECURITY.md
security	npm audit, .env exposure, SECURITY.md policy, secrets scanning
cicd	GitHub Actions workflows, test/lint/build steps, workflow quality
dependencies	Lock file presence, outdated deps, dependency count
branch-protection	CODEOWNERS, protected branch config, review requirements
iot	PlatformIO config, firmware structure (auto-skips non-IoT projects)

MCP Server

An MCP server is included for integration with AI assistants (Claude, GitHub Copilot).

cd mcp-server && npm install
node mcp-server/index.js

Exposes three tools: check, fix, and findings. See mcp-server/ for details.

CI Integration

name: Health Check
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      - run: npm install
      - run: npx repo-manager check --format json

License

MIT