rrdoctor 0.2.1__tar.gz

rrdoctor-0.2.1/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @OWNER

rrdoctor-0.2.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,38 @@
+name: Bug report
+description: Report a scanner, CLI, or report-generation bug.
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Minimal reproduction
+      description: Include a tiny fixture or repository structure if possible.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Include rrdoctor version, Python version, OS, and command.
+    validations:
+      required: true
+  - type: checkboxes
+    id: safety
+    attributes:
+      label: Safety check
+      options:
+        - label: I removed real secrets, private data, and confidential repository content.
+          required: true

rrdoctor-0.2.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security reports
+    url: https://github.com/OWNER/research-repo-doctor/security/policy
+    about: Please report security concerns privately.

rrdoctor-0.2.1/.github/ISSUE_TEMPLATE/false_negative.yml

@@ -0,0 +1,37 @@
+name: False negative report
+description: Report a reproducibility risk that Research Repo Doctor missed.
+title: "[False negative]: "
+labels: ["false-negative", "rules"]
+body:
+  - type: textarea
+    id: missed-risk
+    attributes:
+      label: Missed reproducibility risk
+      description: What should rrdoctor have flagged?
+    validations:
+      required: true
+  - type: textarea
+    id: repository-shape
+    attributes:
+      label: Minimal repository shape
+      description: Share a sanitized tree, fixture, or public example.
+    validations:
+      required: true
+  - type: input
+    id: expected-rule
+    attributes:
+      label: Existing or proposed rule ID
+      placeholder: RRD043 or new rule
+  - type: textarea
+    id: expected-finding
+    attributes:
+      label: Expected finding and remediation
+    validations:
+      required: true
+  - type: checkboxes
+    id: safety
+    attributes:
+      label: Safety check
+      options:
+        - label: I removed real secrets, private data, and confidential repository content.
+          required: true

rrdoctor-0.2.1/.github/ISSUE_TEMPLATE/false_positive.yml

@@ -0,0 +1,40 @@
+name: False positive
+description: Report a rule that flagged acceptable repository content.
+title: "[False positive]: "
+labels: ["false-positive", "rules"]
+body:
+  - type: input
+    id: rule
+    attributes:
+      label: Rule ID
+      placeholder: RRD060
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Why this is a false positive
+      description: Explain why the finding is misleading for this repository.
+    validations:
+      required: true
+  - type: textarea
+    id: repository-shape
+    attributes:
+      label: Minimal repository shape
+      description: Share a sanitized tree, fixture, or public example.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: Should the rule be quiet, lower severity, or provide different guidance?
+    validations:
+      required: true
+  - type: checkboxes
+    id: safety
+    attributes:
+      label: Safety check
+      options:
+        - label: I removed real secrets, private data, and confidential repository content.
+          required: true

rrdoctor-0.2.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,11 @@
+name: Feature request
+description: Suggest a CLI, action, or reporting improvement.
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: feature
+    attributes:
+      label: Feature
+    validations:
+      required: true

rrdoctor-0.2.1/.github/ISSUE_TEMPLATE/rule_request.yml

@@ -0,0 +1,36 @@
+name: New rule request
+description: Propose a deterministic reproducibility rule.
+title: "[Rule]: "
+labels: ["rule-request"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Reproducibility problem
+    validations:
+      required: true
+  - type: textarea
+    id: heuristic
+    attributes:
+      label: Proposed deterministic heuristic
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Evidence and files to inspect
+      description: What files, patterns, or metadata should the rule use?
+    validations:
+      required: true
+  - type: textarea
+    id: remediation
+    attributes:
+      label: Suggested remediation
+      description: What should maintainers do when the rule fires?
+    validations:
+      required: true
+  - type: textarea
+    id: false-positives
+    attributes:
+      label: Likely false positives
+      description: Describe cases where the rule should stay quiet or be configurable.

rrdoctor-0.2.1/.github/ISSUE_TEMPLATE/scan_case.yml

@@ -0,0 +1,32 @@
+name: Research repository scan case
+description: Share a public or sanitized repository scan case for rule evaluation.
+title: "[Scan case]: "
+labels: ["scan-case", "research-repo"]
+body:
+  - type: input
+    id: repo-type
+    attributes:
+      label: Repository type
+      placeholder: ML paper repo, bioinformatics pipeline, R analysis project
+    validations:
+      required: true
+  - type: textarea
+    id: public-link
+    attributes:
+      label: Public link or sanitized fixture
+      description: Use a public URL only if you have permission to share it.
+    validations:
+      required: true
+  - type: textarea
+    id: scan-summary
+    attributes:
+      label: Scan summary
+      description: Paste relevant rrdoctor findings or attach a report.
+    validations:
+      required: true
+  - type: textarea
+    id: maintainer-notes
+    attributes:
+      label: What should maintainers learn from this case?
+    validations:
+      required: true

rrdoctor-0.2.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,9 @@
+## Summary
+
+## Checklist
+
+- [ ] Tests or fixtures cover the change.
+- [ ] `ruff check .` passes.
+- [ ] `ruff format --check .` passes.
+- [ ] Rule docs were updated if rule behavior changed.
+- [ ] No network dependency was added to the core scanner.

rrdoctor-0.2.1/.github/workflows/action-smoke-test.yml

@@ -0,0 +1,25 @@
+name: Action smoke test
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  action-smoke-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./
+        with:
+          path: examples/minimal-research-project
+          profile: minimal
+          fail-on: none
+          output: rrdoctor-action-report.md
+          plan: "true"
+          comment-pr: "true"
+          step-summary: "true"

rrdoctor-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install -e ".[dev]"
+      - run: ruff format --check .
+      - run: ruff check .
+      - run: mypy src/rrdoctor
+      - run: pytest
+      - name: Self-scan
+        run: rrdoctor scan . --profile standard --format markdown --output rrdoctor-self-report.md --fail-on none
+      - name: Command smoke tests
+        run: |
+          rrdoctor fix .
+          rrdoctor plan . --output rrdoctor-plan.md
+          rrdoctor badge . --output rrdoctor-badge-check.json
+      - uses: actions/upload-artifact@v4
+        with:
+          name: rrdoctor-self-report-${{ matrix.python-version }}
+          path: |
+            rrdoctor-self-report.md
+            rrdoctor-plan.md

rrdoctor-0.2.1/.github/workflows/release.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build and publish distribution
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build frontend
+        run: python -m pip install --upgrade build
+      - name: Build distributions
+        run: python -m build
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

rrdoctor-0.2.1/.gitignore

@@ -0,0 +1,22 @@
+.DS_Store
+.env
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+build/
+*.egg-info/
+.coverage
+htmlcov/
+.ipynb_checkpoints/
+data/raw/
+outputs/
+checkpoints/
+wandb/
+mlruns/
+rrdoctor-report.md
+rrdoctor-self-report.md

rrdoctor-0.2.1/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.5.0
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+      - id: ruff-format

rrdoctor-0.2.1/.rrdoctor-badge.json

@@ -0,0 +1,6 @@
+{
+  "color": "brightgreen",
+  "label": "rrdoctor",
+  "message": "100/100",
+  "schemaVersion": 1
+}

rrdoctor-0.2.1/.rrdoctor.yml

@@ -0,0 +1,29 @@
+version: 1
+profile: standard
+paths:
+  include:
+    - "."
+  exclude:
+    - ".git"
+    - ".venv"
+    - "node_modules"
+    - "__pycache__"
+    - ".mypy_cache"
+    - ".pytest_cache"
+    - ".ruff_cache"
+    - "dist"
+    - "build"
+    - "tests/fixtures"
+    - "examples/reports"
+    - "rrdoctor-report.md"
+    - "rrdoctor-self-report.md"
+thresholds:
+  large_file_mb: 50
+  large_notebook_output_kb: 1024
+rules:
+  RRD032:
+    enabled: false
+fail_on: error
+report:
+  format: markdown
+  output: rrdoctor-report.md

rrdoctor-0.2.1/AGENTS.md

@@ -0,0 +1,71 @@
+# AGENTS.md
+
+## Mission
+
+Research Repo Doctor helps researchers and lab teams audit whether public research code is reproducible, reviewable, citable, and release-ready. The CLI must stay deterministic, local-first, and useful without any AI API key.
+
+## Setup
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Test commands
+
+```bash
+pytest
+python -m rrdoctor scan tests/fixtures/missing-basics-repo --format markdown --fail-on none
+python -m rrdoctor plan tests/fixtures/missing-basics-repo
+python -m rrdoctor fix tests/fixtures/missing-basics-repo   # dry-run; add --write to apply
+```
+
+## Lint commands
+
+```bash
+ruff check .
+ruff format --check .
+mypy src/rrdoctor
+```
+
+## Architecture
+
+- `src/rrdoctor/models.py`: typed report, rule, and fix-plan models.
+- `src/rrdoctor/config.py`: `.rrdoctor.yml` defaults and overrides.
+- `src/rrdoctor/scanner.py`: path traversal, exclude handling, rule execution.
+- `src/rrdoctor/rules/`: deterministic rule modules.
+- `src/rrdoctor/fixers.py`: deterministic, idempotent auto-fixers (scaffolding only).
+- `src/rrdoctor/baseline.py`: diff a scan against a stored baseline report.
+- `src/rrdoctor/reporting/`: Markdown, JSON, SARIF, agent-plan, and badge renderers.
+- `src/rrdoctor/cli.py`: Typer CLI (`scan`, `fix`, `plan`, `badge`, `init`, ...).
+
+## Rule authoring rules
+
+- Rules must be deterministic and not require network access.
+- Emit actionable findings with concise evidence and remediation.
+- Respect path excludes through the scan context.
+- Mask possible secrets in all evidence.
+- Add tests or fixtures for every new rule.
+- Update docs and rule tables.
+
+## Fixer authoring rules
+
+- Fixers must be deterministic and idempotent.
+- Never overwrite or delete existing files; create or safely append only.
+- Never execute code from the scanned repository and never make network calls.
+- Generated content may contain clearly marked placeholders for human review.
+- Anything requiring judgement belongs in the agent fix plan, not a fixer.
+
+## Style
+
+- Python 3.10 minimum.
+- Keep heuristics simple and readable.
+- Prefer small rule modules over hidden global behavior.
+- Add comments only when they clarify non-obvious logic.
+
+## Do not do
+
+- Do not add network calls to the core scanner.
+- Do not require a hosted-service API key.
+- Do not expose secrets in reports.
+- Do not fabricate adoption metrics.
+- Do not add vague automation features without deterministic fallback.

rrdoctor-0.2.1/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+## Unreleased (0.3.0)
+
+- Repositioned around conference Artifact Evaluation: README leads with an
+  "AE-ready before you submit" wedge and zero-clone `uvx`/`pipx` install commands.
+- Added `rrdoctor appendix`: generates an ACM-style Artifact Appendix skeleton and maps findings
+  to ACM badge tiers (Available / Functional / Reproduced) and the NeurIPS reproducibility checklist.
+- Added `rrdoctor verify`: an L1 (static) / L2 (environment build) / L3 (entrypoint run)
+  reproducibility ladder. With `--run` it actually resolves dependencies (`uv`/`pip`/`conda`/`Rscript`)
+  and executes a declared entrypoint under a `--timeout`. Static by default. Only `--run` trusted repos.
+- Added `rrdoctor mcp`: an MCP server exposing `scan`/`verify`/`appendix` as tools for coding
+  agents (optional extra: `pip install 'rrdoctor[mcp]'`).
+- Added submission profiles `ml-paper`, `neurips`, `icml`, `acm`, `fair4rs`, and `joss` with
+  tag-based inheritance from the base profiles.
+- Added rule `RRD034` (deptry-style import-vs-manifest cross-check) and `RRD054` (hardcoded
+  GPU/CUDA assumption without a documented requirement).
+- Broadened environment checks to R (`DESCRIPTION`, `install.R`) and Julia (`Project.toml`)
+  manifests and runtime-version hints.
+- The GitHub Action profile input now accepts the submission profiles.
+- Added `docs/launch-checklist.md` with the maintainer's manual release/outreach steps.
+
+## v0.2.0 - 2026-06-08
+
+- Added `rrdoctor fix`: deterministic, idempotent auto-fix that scaffolds common gaps
+  (LICENSE, CONTRIBUTING, SECURITY, CODE_OF_CONDUCT, AGENTS.md, CITATION.cff, DATA.md,
+  data/README.md, results/README.md, CHANGELOG.md, and .gitignore entries). Existing files
+  are never overwritten and no code from the scanned repository is executed.
+- Added `rrdoctor plan` and the `agent` report format: a tool-agnostic fix plan where each
+  task names the deterministic check that verifies it.
+- Added baseline comparison to `rrdoctor scan` via `--baseline` and `--fail-on-new`, so CI
+  can gate only on newly introduced findings.
+- Added `rrdoctor badge`: a Shields.io endpoint document or a self-contained SVG score badge.
+- Enhanced the GitHub Action with sticky pull request comments, job summaries, an optional
+  fix-plan artifact, baseline gating, and artifact upload, all using the built-in token.
+- Added rules: RRD014 (AGENTS.md task guide), RRD033 (unpinned dependencies), RRD065
+  (committed notebook checkpoints), and RRD082 (pre-commit configuration).
+- Added the `autofix_available` flag and a stable finding fingerprint to the report model.
+- Expanded documentation, examples, and tests; refreshed the self-scan report and badge.
+
+## v0.1.0 - 2026-06-03
+
+- Initial public-release-ready repository structure.
+- Added `rrdoctor scan`, `init`, `list-rules`, `explain`, and `doctor` commands.
+- Added deterministic rule engine with research reproducibility checks across documentation, data, environments, experiments, notebooks, citation, governance, testing, CI, security, release, and metadata.
+- Added Markdown, JSON, and experimental SARIF-compatible reports.
+- Added GitHub Action metadata and example workflows.
+- Added tests, fixtures, docs, issue templates, PR template, roadmap, security policy, citation metadata, and maintainer workflow notes.
+- Added example reports, including a self-scan report for release review.
+- Completed v0.1.0 release-readiness pass covering YAML validity, package metadata, docs consistency, local Markdown links, and refreshed self-scan output.

rrdoctor-0.2.1/CITATION.cff

@@ -0,0 +1,10 @@
+cff-version: 1.2.0
+message: "If Research Repo Doctor helps your research software release process, please cite it."
+title: "Research Repo Doctor"
+authors:
+  - family-names: "Maintainers"
+    given-names: "Research Repo Doctor"
+version: 0.2.0
+date-released: 2026-06-08
+license: MIT
+repository-code: "https://github.com/Tom409114/research-repo-doctor"

rrdoctor-0.2.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+# Code of Conduct
+
+This project follows the Contributor Covenant Code of Conduct, version 2.1.
+
+Participants are expected to be respectful, constructive, and mindful that research software contributors may be students, maintainers, reviewers, or lab staff working under different constraints.
+
+Unacceptable behavior includes harassment, personal attacks, sustained disruption, and publishing private information without consent.
+
+Report concerns to the maintainers through the private contact listed in `SECURITY.md` until a dedicated project contact is published.

rrdoctor-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+Thanks for helping improve Research Repo Doctor. The project is early, so small, well-tested contributions are especially valuable.
+
+## Setup
+
+```bash
+python -m pip install -e ".[dev]"
+pytest
+ruff check .
+ruff format --check .
+```
+
+## Good first contributions
+
+- Add R language environment detection.
+- Add Julia environment detection.
+- Improve notebook path detection.
+- Add Zenodo/DOI detection.
+- Add Snakemake/Nextflow workflow detection.
+- Add docs website deployment.
+
+## Rule contribution contract
+
+Rules must be deterministic, local-first, and explainable. A rule should emit concise evidence, avoid scanning binary content except for size checks, respect configured excludes, and never print full secrets.
+
+## Rule contribution process
+
+1. Open or link a rule request describing the reproducibility risk.
+2. Propose deterministic evidence and likely false-positive cases.
+3. Add rule metadata and implementation in `src/rrdoctor/rules/`.
+4. Add a focused fixture or unit test.
+5. Update `docs/checks.md` and `docs/rule-authoring.md` when behavior changes.
+6. Run `pytest`, `ruff check .`, and `ruff format --check .`.
+
+Every new rule should include rule metadata, tests, docs, and remediation text that a researcher can act on.
+
+## Review expectations
+
+Pull requests should keep the scanner understandable. Avoid broad rewrites unless they reduce real maintenance cost. If a rule is heuristic, say so in the rule description and tests.

rrdoctor-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Research Repo Doctor Maintainers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rrdoctor-0.2.1/Makefile

@@ -0,0 +1,16 @@
+.PHONY: install test lint format-check self-scan
+
+install:
+	python -m pip install -e ".[dev]"
+
+test:
+	pytest
+
+lint:
+	ruff check .
+
+format-check:
+	ruff format --check .
+
+self-scan:
+	rrdoctor scan . --profile standard --format markdown --output examples/reports/self-scan-report.md --fail-on none