forgefix 0.1.1

One command to set up, health-check, and repair any open-source project.

Install · Docs · Demo · Contributing

Demo

What you are watching:

1. forgefix doctor on a deliberately broken repo — an app.py and a pyproject.toml, but no README, no lockfile, no CI, no security policy. Score: 42/100.
2. forgefix report — the same findings as markdown, with the highest-value fixes first.
3. forgefix up --apply — creates the missing setup files, makes .venv, installs the project, writes requirements.lock, and runs the test suite.
4. forgefix doctor again — the same repo now scores 91/100.

Still frame: demo/demo-thumb.png · MP4 for social: demo/demo.mp4

The problem

Cloning a new repository usually starts a scavenger hunt. There is no lockfile, so the install is not reproducible. The README says "install dependencies" without saying how. There is no CI, so nobody knows whether main even passes its own tests. There is no security policy, so vulnerability reports arrive as public issues.

$ git clone https://github.com/example/project && cd project
$ make dev
make: *** No rule to make target 'dev'.  Stop.
$ pip install -r requirements.txt
ERROR: Could not open requirements file: [Errno 2] No such file or directory: 'requirements.txt'

Every one of those gaps is visible in file names and metadata alone. ForgeFix reads that metadata, scores the gaps, and fixes the ones it can fix.

What ForgeFix does

forgefix doctor checks a repository against a fixed set of onboarding rules and prints a pass/warn/fail table with a concrete fix for each gap. forgefix up performs the bring-up: stack detection, create-if-missing repairs, virtual environment, dependencies, tests. Scans are read-only and never execute repository code.

doctor also emits --json for machines. up never overwrites an existing file and never invents a LICENSE for you.

How the score works

Every rule carries two fixed weights: the points lost when the check fails, and the points lost when it only warns. The score starts at 100, subtracts every deduction, and stays in the 0–100 range. No heuristics and no network calls — the same repository always scores the same, and unit tests pin the exact numbers.

Plugins add checks with their own weights — the bundled example checks for an .editorconfig at 3 fail / 1 warn points in the polish category.

A real report from the broken fixture, abridged:

# ForgeFix health report

- Repository: `demo-scratch`
- Health score: **42/100** (critical)
- Checks: 0 pass, 5 warn, 6 fail, 0 skip

## Category breakdown

| Category | Points lost |
| --- | --- |
| automation | 9 |
| deps | 5 |
| docs | 22 |
| environment | 7 |
| legal | 6 |
| polish | 1 |
| security | 8 |

## Top fixes

1. **README present** (-12): Add a README.md with a one-line pitch and a getting-started section.
2. **One-command install line** (-8): Add a copy-pasteable install command (pip install / npm install / make setup).
3. **CI workflow** (-8): Add a CI workflow under .github/workflows/ that runs lint and tests.

The check table above it lists all 11 findings (for example: FAIL | CI workflow | automation | no CI workflow found).

What it checks

Ten built-in rules. A scan reads file names and text only - nothing is executed, downloaded, or copied:

Each rule maps 1:1 to the weight table above. Disable rules per repository with .forgefix.yml (forgefix init).

Quickstart

pipx install forgefix    # from PyPI once published
# or straight from the repository:
pip install "git+https://github.com/BistaDinesh03/forgefix"
cd your-repo
forgefix doctor

To auto-fix what doctor found:

forgefix up --apply

Try the bundled fixtures right now: forgefix doctor --path tests/fixtures/broken_repo scores 42, --path tests/fixtures/minimal_repo scores 100.

What it is NOT

Compared by category, not by name:

What ForgeFix is not:

• Not a security scanner. It checks whether a security policy exists, not for vulnerabilities.
• Not a package manager. It never resolves, pins, or vendors dependencies for you.
• Not a linter replacement. Keep ruff, eslint, and their friends; they work inside files.
• Not a bot. It never opens pull requests and never pushes to your repository.

Plugins

A plugin is a class with a name and a check(root) method that returns Finding objects. This is the bundled example, verbatim from forgefix/plugins/example.py:

from pathlib import Path

from forgefix.core.rules import Finding


class ExamplePlugin:
    """Bundled example plugin registered under the ``forgefix.plugins`` group."""

    name = "example"

    def check(self, root: Path) -> list[Finding]:
        """Report whether the repository ships an .editorconfig."""
        present = (root / ".editorconfig").is_file()
        return [
            Finding(
                rule_id="editorconfig",
                category="polish",
                title="EditorConfig present",
                status="pass" if present else "warn",
                detail=(
                    ".editorconfig found"
                    if present
                    else "no .editorconfig (indentation and charset may drift between editors)"
                ),
                suggestion=(
                    "Add an .editorconfig with basic indentation, charset, and newline rules."
                ),
                weight=3,
                warn_weight=1,
                source="plugin:example",
            )
        ]

Register it under the forgefix.plugins entry-point group and ForgeFix discovers it automatically. A broken plugin is logged and skipped; it cannot break a scan. Details in docs/plugins.md.

HTTP API

forgefix serve                       # http://127.0.0.1:8000

$ curl http://127.0.0.1:8000/health
{"status":"ok","version":"0.1.1"}

$ curl "http://127.0.0.1:8000/doctor?path=."
{"path": "...", "score": {"total": 42, ...}, "findings": [...], "plugins": [...]}

$ curl "http://127.0.0.1:8000/report?path=."
{"path": "...", "score": 42, "markdown": "# ForgeFix health report ..."}

The API is the same scanner as the CLI: same weights, same score, same findings.

Use it as a CI gate

forgefix doctor exits with code 2 when the score is below --min-score, so one pipeline step can fail a pull request that drops the health score:

- name: ForgeFix health gate
  run: |
    pipx install "git+https://github.com/BistaDinesh03/forgefix"
    forgefix doctor --path . --min-score 80 --json

Run forgefix init first to store the threshold in .forgefix.yml (min_score); the file's value applies whenever the flag is absent. --json prints the score and every finding for downstream steps.

Roadmap

Contributing

• Setup: make setup — editable install plus pre-commit hooks.
• Tests: make test — the 85% coverage gate is enforced in pyproject.toml.
• Lint: make lint (ruff check + format) and make type (mypy).
• Pull requests: focused changes, tests included, CHANGELOG entry, no secrets.

Full guidelines in CONTRIBUTING.md.

License

MIT © ForgeFix contributors. Original code; repository metadata reads only, nothing is copied from inspected projects.

Built with Typer, FastAPI, and Pydantic. Demo recorded with VHS.

Made by @BistaDinesh03