Skip to content

About

Turn repository maintenance into an actionable plan. Local-first CLI + browser workbench for docs, testing gaps, change impact and CI readiness. Zero dependencies.

Topics

Resources

Contributing

Security policy

Stars

154 stars

Watchers

2 watching

Forks

Latest commit

 

History

10 Commits

Folders and files

Repository files navigation

RepoRelief

Less upkeep. More shipping.

Turn repository maintenance into an evidence-based action plan.

CI Pages Node License: MIT Support

Open the workbench · Quick start · Contribute

Animated sample maintenance plan

The work everyone postpones

Documentation drifts. Tests get deferred. Legacy modules grow. Reviewing a change starts with reconstructing context.

RepoRelief turns visible repository signals into a prioritized queue with file-level evidence and a practical next step. Use the same dependency-free engine in your terminal or browser.

Friction What RepoRelief does
“I'll write the docs later” Finds missing setup, usage and testing sections
“Where does this documentation link go?” Resolves relative Markdown links and reports missing targets with source lines
“Where should I add tests?” Flags modules without matching test filenames
“I'm afraid to touch this file” Highlights large modules and suggests characterization tests
“What do I review?” Builds a change checklist and lists matching tests from a Git diff
“Checks only run on my machine” Detects missing GitHub Actions workflows
“Can we reuse this?” Detects a missing root license

Inspect a real finding before running anything

Browse the tiny fixture repository and its generated Markdown report.

The fixture intentionally contains a broken link on line 4 of docs/guide.md:

docs/guide.md:4: ./setup.md -> docs/setup.md

Fix it by restoring docs/setup.md or updating the link from the guide's directory.

node bin/reporelief.js examples/neglected-repo

Relative inline links, images and defined reference links are checked against the local path inventory. Query strings and fragments are stripped for path lookup; URL-encoded filenames are decoded. Directories count as existing targets. External URLs, root-relative paths, anchors, HTML links and fenced/inline code examples are not validated. This is a bounded Markdown heuristic, not a full CommonMark parser. Excluded files and directories can appear missing; no instruction correctness is inferred.

Quick start

Requires Node.js 22 or later and Git. No npm installation, API key or account required.

git clone https://github.com/brunnojob/reporelief.git
cd reporelief
node bin/reporelief.js /path/to/your/project
# Structured output for your own tools
node bin/reporelief.js /path/to/project --json

# Save an actionable Markdown plan
node bin/reporelief.js /path/to/project > maintenance-plan.md

# Compare committed changes with a base revision (run inside the tool checkout)
node bin/reporelief.js /path/to/project --changed main

--changed uses git diff BASE...HEAD. It requires the base revision in the target repository and excludes uncommitted changes. A comparison against the current branch produces no changed files.

Explore an example finding
{
  "id": "docs.testing",
  "priority": "medium",
  "title": "Document testing",
  "evidence": ["README.md"],
  "action": "Add a testing section with commands verified by a maintainer."
}

Every finding provides a rule identifier, priority, evidence and a suggested action. There is no invented quality score.

Use it in your GitHub Actions pipeline

After checking out your project and setting up Node.js 22:

- uses: actions/checkout@v4
  with:
    repository: brunnojob/reporelief
    path: .tools/reporelief
- name: Generate maintenance plan
  run: node .tools/reporelief/bin/reporelief.js . > maintenance-plan.md
- uses: actions/upload-artifact@v4
  with:
    name: maintenance-plan
    path: maintenance-plan.md

For reproducible integrations, pin the tool checkout to a reviewed commit SHA. Keep the tool checkout outside your scan root where practical; otherwise its files are included in the audit. Findings are advisory and do not fail CI.

Browser workbench

Launch the live workbench. Choose English or PT-BR; the interface, findings, recommendations, messages and Markdown export follow the selected language. The preference is saved in your browser.

Start with Run sample audit before selecting a folder. Inspect fictional files with line numbers, apply five in-memory example changes, and watch the same audit engine recalculate the findings. Restore documentation, add a matching test file, add CI and a license, or track a maintenance marker. Restart the example at any time. Sample files are displayed as original English source and are never executed. A disappearing signal demonstrates a rule, not proof of correctness, working CI or measured test coverage.

Then select a local folder, filter by priority, rerun its audit or export the plan. Selected files are processed in the browser without uploading them. Directory selection works in browsers supporting webkitdirectory.

GitHub READMEs do not run JavaScript or arbitrary iframe embeds, so the README embeds the animated preview and live workflow badges; the interactive tool lives on Pages.

Honest boundaries

This release uses static text and filename heuristics. It does not measure test coverage, prove correctness, generate tests, build a semantic call graph or rewrite source code. README keywords and test-name matches can produce false positives or miss unconventional structures.

The CLI skips symlinks, environment files, common generated directories, binary files and files over 512 KB. Scans are capped at 20 MB of text and 10,000 files. Only scanned files contribute to findings. Exclusions are not a secret scanner; inspect exports before sharing them.

Development and testing

npm test
npm run check
npm run audit

Node's built-in test runner covers missing repository essentials, matching tests, path normalization and legacy-module signals. CI runs Node.js 22 and 24 on Linux and Windows and checks that the browser and CLI engines stay identical.

Contributions are welcome: see CONTRIBUTING.md. Suggested starter tasks include Python test-name conventions, more language fixtures and accessibility improvements. Feature requests should include a concrete input and expected finding.

Support the project

If RepoRelief saves you maintenance time, buy brunnodev a coffee.

MIT · Built by brunnodev.store

About

Turn repository maintenance into an actionable plan. Local-first CLI + browser workbench for docs, testing gaps, change impact and CI readiness. Zero dependencies.

Topics

Resources

Contributing

Security policy

Stars

154 stars

Watchers

2 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages