build-fix 0.1.3

Auto-repair TypeScript/JS build errors: duplicates, missing exports, spelling typos, unused imports.

build-fix

Built by the Nometria team. We help developers take apps built with AI tools (Lovable, Bolt, Base44, Replit) to production - handling deployment to AWS, security, scaling, and giving you full code ownership. Learn more →

Auto-repair TypeScript / JavaScript build errors in one command.

Parses your build log and surgically patches source files. Zero config, zero dependencies.

---

Quick start

# Clone and install
git clone https://github.com/nometria/build-fix-agents
cd build-fix-agents
pip install -e .

# Scan current directory and apply fixes (verifies with npm run build)
build-fix .

# Provide a captured build log for more accurate fixes
npm run build 2>&1 | tee build.log
build-fix . --log build.log

# Run tests
pytest tests/ -v

---

What it fixes

Agent	Trigger	Fix
unused_import	Import name never referenced in file	Removes entire line or individual names
duplicate_var	const X / function X declared twice	Renames second occurrence to X_2
missing_export	Build log: X is not exported	Adds export to const/let/var/function/class/interface/type/enum
export_spelling	Build log: expected X, found Y	Fixes typo using Levenshtein distance ≤ 2
implicit_any	Build log: TS7006 implicitly has 'any' type	Adds : any annotation to parameters
missing_return_type	Build log: TS7010 lacks return-type annotation	Adds : void return type

Safety: applies at most 5 edits per file and 10 edits total. Reverts everything if the build still fails after patching.

---

Benchmark Results

Tested against 24 synthetic TypeScript/JS files with known build errors. Each agent is measured for detection accuracy (does it find the error?), fix correctness (does the fix resolve it?), and speed.

Agent	Cases	Detection	Fix Accuracy	Avg Speed
unused_import	5	100%	100%	0.3 ms
duplicate_var	4	100%	100%	0.2 ms
missing_export	7	100%	100%	0.4 ms
export_spelling	3	100%	100%	0.2 ms
implicit_any	3	100%	100%	0.2 ms
missing_return_type	2	100%	100%	0.2 ms
Overall	24	100%	100%	0.3 ms

Zero false positives - clean files are left untouched. All fixes verified against expected output.

Run benchmarks yourself:

python benchmarks/run_benchmarks.py
python benchmarks/ts_error_coverage.py
python benchmarks/real_world_errors.py

---

Industry Benchmark Context

Top 10 TypeScript Compiler Errors and Our Coverage

Rank	Error Code	Description	Freq%	Covered	Agent
1	TS2304	Cannot find name 'X'	12.5%	No	-
2	TS2339	Property 'X' does not exist on type 'Y'	11.2%	No	-
3	TS2345	Argument type mismatch	9.8%	No	-
4	TS7006	Parameter implicitly has 'any' type	7.3%	Yes	implicit_any
5	TS2305	Module has no exported member	6.1%	Yes	missing_export
6	TS6133	Declared but never read	5.8%	Yes	unused_import
7	TS7010	Lacks return-type annotation	4.5%	Yes	missing_return_type
8	TS2322	Type not assignable	4.2%	No	-
9	TS2554	Wrong number of arguments	3.9%	No	-
10	TS1005	Syntax error	3.5%	No	-

Coverage: 9 of the top 20 tsc error codes (45%), covering 33.2% of all TypeScript compiler errors by frequency.

SWE-bench Reference

Multi-SWE-bench includes TypeScript/JavaScript among 1,632 validated GitHub issues across 7 languages. SWE-bench Pro extends to 1,865 tasks across 41 repos in Python, Go, TypeScript, and JavaScript. TS/JS tasks have 0-30% resolution rates for LLM-based tools, significantly lower than Python tasks.

Our tool targets the most common deterministic fix patterns at 100% accuracy on covered error codes. This is complementary to LLM-based tools: we handle mechanical patterns (unused imports, missing exports, implicit any, duplicate declarations) that don't require semantic understanding, while LLMs handle complex type errors and logic bugs that require deeper reasoning.

Real-World Multi-File Benchmark

Beyond isolated single-file tests, we test against a realistic 6-file TypeScript project with interconnected errors across modules (unused imports spanning files, missing exports between modules, duplicate declarations, export typos, implicit any parameters, missing return types). The full pipeline achieves 100% fix accuracy on this multi-file scenario.

---

Install

pip install build-fix

# or via npx (installs Python package automatically):
npx build-fix .

# or run from source:
git clone https://github.com/nometria/build-fix-agents
cd build-fix-agents
pip install -e .

---

Usage

# Scan current directory, apply fixes, verify with `npm run build`
build-fix .

# Provide a captured build log for more accurate fixes
npm run build 2>&1 | tee build.log
build-fix . --log build.log

# Custom build command
build-fix . --cmd "pnpm build"

# Apply without running build verification
build-fix . --no-verify

# JSON output (for CI integration)
build-fix . --json

---

GitHub Action

Auto-fix build errors on failed CI and open a PR with the fixes.

Option A: Composite action (uses: nometria/build-fix-agents@v1)

Add this to your existing workflow after a failed build step:

# .github/workflows/build-fix.yml
name: Auto-fix build errors
on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

permissions:
  contents: write
  pull-requests: write

jobs:
  build-fix:
    runs-on: ubuntu-latest
    if: >
      github.event.workflow_run.conclusion == 'failure' &&
      github.event.workflow_run.event == 'push'
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.workflow_run.head_branch }}
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci

      - name: Capture build log
        continue-on-error: true
        run: npm run build 2>&1 | tee build.log

      - uses: nometria/build-fix-agents@v1
        with:
          project_path: '.'
          build_log: 'build.log'
          build_cmd: 'npm run build'
          auto_pr: 'true'

Action inputs

Input	Default	Description
project_path	.	Path to the project root
python_version	3.11	Python version for running build-fix
node_version	20	Node.js version (set to '' to skip Node setup)
auto_pr	true	Open a PR with fixes automatically
build_cmd	npm run build	Build command to verify fixes
build_log		Path to a captured build log file

Action outputs

Output	Description
fixed	true if fixes were applied
pr_url	URL of the opened PR (if auto_pr is true)
result_json	Full JSON result from build-fix

Option B: Reusable workflow (workflow_call)

Call the full auto-fix workflow from any repo. It handles checkout, dependency install, build, fix, and PR creation end-to-end:

# .github/workflows/auto-fix.yml (in YOUR repo)
name: Auto-fix on build failure
on:
  push:
    branches: [main]

jobs:
  auto-fix:
    uses: nometria/build-fix-agents/.github/workflows/auto-fix.yml@v1
    with:
      build_command: "npm run build"
      node_version: "20"
      python_version: "3.11"
      create_pr: true

Reusable workflow inputs

Input	Default	Description
build_command	npm run build	Build command to run
python_version	3.11	Python version for build-fix
node_version	20	Node.js version for the project build
create_pr	true	Create a PR with fixes

Reusable workflow outputs

Output	Description
fixed	true if fixes were applied
pr_url	URL of the opened PR

Manual trigger

The reusable workflow also supports workflow_dispatch, so you can trigger it manually from the Actions tab in the GitHub UI.

---

npx wrapper

Run build-fix without installing Python packages manually:

# Installs the Python package and runs build-fix
npx build-fix .

# All CLI flags work the same way
npx build-fix ./my-app --log build.log --cmd "pnpm build"
npx build-fix . --no-verify --json

Requires Python 3.9+ on the system. The wrapper script auto-installs the build-fix PyPI package if it is not already present.

---

Extend with custom agents

from build_fix.agents.base import BaseAgent, AgentEdit, AgentResult
from pathlib import Path

class MyAgent(BaseAgent):
    name = "my_agent"
    description = "Fix something custom"

    def run(self, project_root: Path, context=None) -> AgentResult:
        # Find files, propose edits
        return AgentResult(success=True, edits=[...])

Register in src/agents/__init__.py → get_all_agents().

---

Immediate next steps (to productionise)

1. Publish to PyPI: pip install build-fix Done
2. Publish to npm as a wrapper: npx build-fix . Done (package.json + bin/build-fix.sh)
3. Add a VS Code extension that runs on save-with-errors
4. Add GitHub Action: auto-runs on failed CI builds and opens a PR with fixes Done (action.yml)

---

Commercial viability

• VS Code extension marketplace: $5–9/mo subscription
• GitHub App: auto-fix PR on CI failure - charge per repo/seat
• Cursor / Windsurf plugin: native AI-fix integration

---

Example output

Running pytest tests/ -v:

============================= test session starts ==============================
platform darwin -- Python 3.13.9, pytest-9.0.2, pluggy-1.5.0
cachedir: .pytest_cache
rootdir: /tmp/ownmy-releases/build-fix-agents
configfile: pyproject.toml
plugins: anyio-4.12.1, cov-7.1.0
collecting ... collected 9 items

tests/test_agents.py::test_duplicate_var_detected PASSED                 [ 11%]
tests/test_agents.py::test_duplicate_var_no_false_positive PASSED        [ 22%]
tests/test_agents.py::test_missing_export_adds_keyword PASSED            [ 33%]
tests/test_agents.py::test_missing_export_skips_already_exported PASSED  [ 44%]
tests/test_agents.py::test_export_spelling_fixes_typo PASSED             [ 55%]
tests/test_agents.py::test_levenshtein_threshold PASSED                  [ 66%]
tests/test_agents.py::test_unused_import_whole_line_removed PASSED       [ 77%]
tests/test_agents.py::test_unused_import_partial_removal PASSED          [ 88%]
tests/test_agents.py::test_no_edits_on_clean_file PASSED                 [100%]

============================== 9 passed in 0.04s ===============================