{"_id":"@davidwang1231/repo-doctor","name":"@davidwang1231/repo-doctor","dist-tags":{"latest":"0.4.3"},"versions":{"0.4.3":{"name":"@davidwang1231/repo-doctor","version":"0.4.3","description":"Evidence-based repository health checks for real-world codebases.","type":"module","bin":{"repo-doctor":"src/cli.js"},"scripts":{"lint":"node scripts/lint.mjs","scan":"node ./src/cli.js scan .","one-click":"node ./src/one-click.js","web":"node ./src/web-server.js","test":"node --test","doctor":"node ./src/cli.js scan . --out examples/self-scan","prepublishOnly":"npm run lint && npm test"},"keywords":["repository-health","code-quality","github-action","software-engineering","ai-ready","repository-scanner","github"],"author":{"name":"David Wang"},"license":"MIT","homepage":"https://github.com/DavidWang1231/repo-doctor#readme","repository":{"type":"git","url":"git+https://github.com/DavidWang1231/repo-doctor.git"},"bugs":{"url":"https://github.com/DavidWang1231/repo-doctor/issues"},"engines":{"node":">=20"},"gitHead":"fdd98a0424cdddc725becf5894c2438e222ff72e","_id":"@davidwang1231/repo-doctor@0.4.3","_nodeVersion":"26.4.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-QcmEKT9/V7VnmskRQ96eEtQY11YAimbEmdM37+Z81kNYfXzUyJLdVUekSHdPxyLIbVIhn6rwg2T8eWPZ36SmLQ==","shasum":"db8df9c9597c5d694ab843e49b1b06ed75bedb49","tarball":"https://registry.npmjs.org/@davidwang1231/repo-doctor/-/repo-doctor-0.4.3.tgz","fileCount":29,"unpackedSize":136708,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBjOG9CShJeqLyRyKCcf2NvKF8gelvulK4289hL2G4P2AiAQVJvQN7UOF9hbq5yW0SAcGShcTTNbImjkL5BrXvznug=="}]},"_npmUser":{"name":"davidwang1231","email":"wangjiacheng1231@gmail.com"},"directories":{},"maintainers":[{"name":"davidwang1231","email":"wangjiacheng1231@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/repo-doctor_0.4.3_1784259116531_0.5768138363682056"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-17T03:31:56.367Z","0.4.3":"2026-07-17T03:31:56.668Z","modified":"2026-07-17T03:31:56.917Z"},"maintainers":[{"name":"davidwang1231","email":"wangjiacheng1231@gmail.com"}],"description":"Evidence-based repository health checks for real-world codebases.","homepage":"https://github.com/DavidWang1231/repo-doctor#readme","keywords":["repository-health","code-quality","github-action","software-engineering","ai-ready","repository-scanner","github"],"repository":{"type":"git","url":"git+https://github.com/DavidWang1231/repo-doctor.git"},"author":{"name":"David Wang"},"bugs":{"url":"https://github.com/DavidWang1231/repo-doctor/issues"},"license":"MIT","readme":"# Repo Doctor\n\nEvidence-based repository health checks for real-world codebases.\n\nRepo Doctor scans a local repository and produces a prioritized health report covering documentation, testing, CI, maintainability, security hygiene, and open-source readiness. It is designed to feel like a practical reviewer, not another dashboard full of raw metrics.\n\n![Repo Doctor report preview](docs/assets/report-preview.svg)\n\nCurrent v0.4 runs without runtime dependencies. The scanner is deterministic first, AI-ready second: every finding is backed by structured evidence in `report.json`, so summaries can explain and prioritize issues without inventing facts.\n\nLive demo page: https://davidwang1231.github.io/repo-doctor/\n\nRepo Doctor now detects project profiles before scoring. A static game is not graded like an npm library, and skipped checks are explained in the report.\n\n## Why This Exists\n\nExisting tools are excellent at deep slices of repository quality:\n\n- OpenSSF Scorecard evaluates open-source security posture.\n- SonarQube performs deep static analysis and quality inspection.\n- CHAOSS tools such as GrimoireLab and Augur/Aveloxis collect and analyze open-source community metrics.\n\nRepo Doctor takes a smaller, sharper wedge: can a maintainer or contributor quickly understand, run, test, and safely modify this repository?\n\n## Quick Start\n\n### Installation\n\nInstall from npm:\n\n```bash\nnpm install -g @davidwang1231/repo-doctor\n```\n\nThen run:\n\n```bash\nrepo-doctor scan https://github.com/owner/repo\n```\n\nYou can also clone or download the repository from GitHub and run it directly from source.\n\n### Web Mode\n\nStart the local web scanner:\n\n```bash\nrepo-doctor web\n```\n\nOr from source:\n\n```bash\nnpm run web\n```\n\nThis opens a browser page where you can paste a local project path or a public GitHub URL, run a scan, and download:\n\n- `report.html`\n- `report.md`\n- `report.json`\n- `summary.md`\n- `fix-prompt.md`\n\nOn macOS, you can also double-click:\n\n```text\nRepo Doctor Web.command\n```\n\nOn Windows, double-click:\n\n```text\nRepo Doctor Web.cmd\n```\n\nWeb mode runs on your own machine by default at `127.0.0.1`. It is a local UI over the same scanner used by the CLI.\n\n### One-Click Mode\n\nOn macOS, double-click:\n\n```text\nRepo Doctor.command\n```\n\nOn Windows, double-click:\n\n```text\nRepo Doctor.cmd\n```\n\nThen drag a project folder into the terminal window, paste a GitHub URL, or press Enter to scan Repo Doctor itself.\n\nOne-click mode will:\n\n- scan the project\n- generate HTML, Markdown, JSON, and summary reports\n- open the HTML report automatically\n- avoid changing the scanned project\n\nReports are saved under:\n\n```text\nrepo-doctor-runs/\n```\n\n### Command Mode\n\nRun a scan from the terminal:\n\n```bash\nnode ./src/cli.js scan .\n```\n\nScan a public GitHub repository URL:\n\n```bash\nnode ./src/cli.js scan https://github.com/owner/repo\n```\n\nThe default output directory is `repo-doctor-report/`:\n\n```text\nrepo-doctor-report/\n  report.html\n  report.json\n  report.md\n```\n\nUse a custom output directory:\n\n```bash\nnode ./src/cli.js scan ../my-project --out doctor-report\n```\n\nFail CI when the score is below a threshold:\n\n```bash\nnode ./src/cli.js scan . --fail-under 75\n```\n\nGenerate a priority summary from the structured report:\n\n```bash\nnode ./src/cli.js summarize repo-doctor-report/report.json\n```\n\nExport a prompt for an AI coding assistant:\n\n```bash\nnode ./src/cli.js prompt repo-doctor-report/report.json\n```\n\nOverride project type when automatic detection is wrong:\n\n```bash\nnode ./src/cli.js scan . --profile static-game\n```\n\nPreview low-risk fixes:\n\n```bash\nnode ./src/cli.js fix .\n```\n\nCreate the missing low-risk files:\n\n```bash\nnode ./src/cli.js fix . --write\n```\n\n## What It Checks\n\n- README presence, onboarding sections, and package script mismatches\n- test files and standard test commands\n- GitHub Actions workflows and pull request validation\n- license, contribution guide, security policy, and `.gitignore`\n- committed `.env` files and missing `.env.example`\n- possible hard-coded secrets and dynamic execution patterns\n- very large files that also show signals of mixed responsibilities, plus TODO/FIXME debt\n- Docker local workflow hints\n- TypeScript configuration basics\n\n## Project Profiles\n\nRepo Doctor first identifies the kind of repository it is looking at, then applies rules that fit that profile.\n\nCurrent profiles include:\n\n- `static-game`: a browser game or GitHub Pages demo built around `index.html`, canvas, and browser game-loop signals\n- `static-site`: a simple static website\n- `cli-tool`: a package with a command-line entry point\n- `web-app`: a frontend app with build or dev scripts\n- `backend-service`: an API or server-side service\n- `library`: a reusable package with exports, main, module, or type entry points\n- `python-project`: a Python repository\n- `docs-only`: a documentation-heavy repository\n- `generic`: fallback when no stronger profile is detected\n\nRules adapt to the profile. For example, a static game is not penalized for missing unit tests, `SECURITY.md`, or `CONTRIBUTING.md` when those checks do not fit the project. Instead, Repo Doctor focuses on things that matter for that repository type, such as playable documentation, GitHub Pages safety, syntax checks, and `.gitignore`.\n\n## Low-Risk Fixes\n\n`repo-doctor fix` only creates missing files. It does not overwrite existing files.\n\nCurrent fixers can create:\n\n- `.env.example` from environment variable references\n- `.github/pull_request_template.md`\n- `.github/ISSUE_TEMPLATE/bug_report.md`\n- `.github/workflows/ci.yml` from Node package scripts\n\n## Priority Summary\n\n`repo-doctor summarize` reads `report.json` and writes `summary.md`, a compact repair plan that stays grounded in file and line evidence. It also includes an AI handoff prompt for turning the structured report into a narrative plan without inventing facts.\n\n## Example Output\n\n```text\nRepo Doctor scanned repo-doctor\nHealth score: 86/100\nFindings: 0 critical, 2 warnings, 5 total\nOutputs:\n- repo-doctor-report/report.json\n- repo-doctor-report/report.md\n- repo-doctor-report/report.html\n```\n\nEach finding includes evidence:\n\n```text\n[warning] README references package scripts that do not exist\nEvidence:\n- README.md:42\n- package.json:8\n```\n\nThe AI fix prompt is designed for handing the report to another coding agent. It tells the agent to use only Repo Doctor evidence, inspect referenced files first, skip checks that are not relevant for the detected project type, and make small reviewable fixes.\n\n## GitHub Action\n\nUse it in another repository:\n\n```yaml\nname: Repo Doctor\n\non:\n  pull_request:\n  push:\n    branches:\n      - main\n\npermissions:\n  contents: read\n  pull-requests: write\n\njobs:\n  repo-doctor:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: DavidWang1231/repo-doctor@v0.4.3\n        with:\n          path: \".\"\n          output: \"repo-doctor-report\"\n          fail-under: \"75\"\n          comment: \"true\"\n          github-token: ${{ secrets.GITHUB_TOKEN }}\n```\n\n## Configuration\n\nv0.4 intentionally has no configuration file. The rule set is fixed while the project proves the core workflow. If auto-detection gets the project type wrong, use `--profile <id>` or the Web Mode project-type dropdown.\n\nPlanned configuration support:\n\n```json\n{\n  \"failUnder\": 75,\n  \"ignore\": [\"docs/generated/**\"],\n  \"rules\": {\n    \"large-source-files\": \"warning\",\n    \"security-policy-missing\": \"off\"\n  }\n}\n```\n\n## Development\n\nRun syntax checks:\n\n```bash\nnpm run lint\n```\n\nRun tests:\n\n```bash\nnpm test\n```\n\nScan this repository:\n\n```bash\nnpm run doctor\n```\n\nBuild the priority summary:\n\n```bash\nnode ./src/cli.js summarize examples/self-scan/report.json --out examples/self-scan/summary.md\n```\n\n## Design Principles\n\n- Evidence before opinion.\n- Deterministic checks before AI interpretation.\n- Reports should be useful in a terminal, a pull request, and a browser.\n- Findings should point to a next action, not just a score.\n- The tool should stay easy to run in a fresh repository.\n\n## Roadmap\n\nSee [docs/ROADMAP.md](docs/ROADMAP.md).\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-5ea54a217946980b5eca620dc9f5ba33"}