From 6dd970d5bc18bec16ab6b7b66ed41b807669284c Mon Sep 17 00:00:00 2001 From: saagpatel <269905221+saagpatel@users.noreply.github.com> Date: Sat, 3 Oct 2026 00:38:33 -0700 Subject: [PATCH] docs: clarify safe local verification commands --- AGENTS.md | 20 ++++++++--- CHANGELOG.md | 2 ++ CONTRIBUTING.md | 96 ++++++++++++++++++++++++++++--------------------- README.md | 29 ++++----------- 4 files changed, 80 insertions(+), 67 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 5897b7d..f98c2e8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,7 +18,16 @@ The current machine-readable truth surface is `output/portfolio-truth-latest.jso ## How To Run -Refresh and verify the local portfolio truth snapshot: +For repository verification, start with the credential-free fixture commands in +[CONTRIBUTING.md](CONTRIBUTING.md). That guide is authoritative for environment +extras, focused/broader tests and conditional browser checks. The full semantic +lane and operator workflows are separate from the lightweight fixture baseline. + +The following commands are deliberate operator work: they scan the configured +local projects workspace and regenerate canonical/compatibility outputs. Do not +use them as a smoke test or run them to verify documentation changes. + +Refresh and verify the local portfolio truth snapshot only when requested: ```sh uv run python -m github_repo_auditor.cli report saagpatel --portfolio-truth @@ -26,14 +35,15 @@ jq '{generated_at,total:(.projects|length),counts:.source_summary.attention_stat uv run operator-os-seam-linter --truth output/portfolio-truth-latest.json --json ``` -Useful checks for repo changes: +For a focused repository check, use the locked fixture baseline: ```sh -uv run ruff check . -uv run pytest -q +uv run --locked --extra dev ruff check src/ tests/ +uv run --locked --extra dev --extra serve --extra config pytest tests/test_scorer.py -q -p no:cacheprovider ``` -Use narrower tests when the change is scoped and the full suite would be disproportionate. +Select the focused test file for the changed module; use CONTRIBUTING.md for +broader checks and the optional semantic environment that full CI requires. The seam-linter checks truth freshness, schema pinning, and generated Markdown provenance markers. Its identity-resolution check is opt-in: diff --git a/CHANGELOG.md b/CHANGELOG.md index 81a91dd..9ac1cda 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,8 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) ## [Unreleased] +- Clarify locked contributor setup, optional test dependencies, and credential-free fixture verification without workstation discovery. + ### Added - Added the local-only `audit pr-evidence ` operator path with strict `PRHeadEvidenceV1` input validation and deterministic diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 636aa5a..1744624 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,74 +2,90 @@ Thank you for your interest in contributing. This guide covers how to set up a local development environment, run tests, follow coding conventions, add a new analyzer, and submit a pull request. -## Prerequisites +## Prerequisites and local setup -- **Python 3.11 or later** — the codebase uses `match` statements, `X | Y` union syntax, and other 3.11+ features. -- **A GitHub Personal Access Token** — optional for public-only audits, but useful for private repos, organization metadata, and higher rate limits. Create one at with the narrowest scopes needed for the audit you plan to run. -- **Git** — standard installation, used for shallow cloning during audits. - -## Local Setup +Use Git, `uv`, and Python 3.11 or later. The checked-in `.python-version` selects +3.11.15 for the locked local/Cloud environment. Run commands from the repository +root; `uv` creates a project virtual environment and can download the selected +interpreter and dependencies during setup. No GitHub, Anthropic, or Notion token +is needed for the fixture checks below. Do not copy credential-bearing `.env` +files into a verification checkout. ```bash -# Clone the repo git clone https://github.com//GithubRepoAuditor.git cd GithubRepoAuditor - -# Install all runtime + dev dependencies -make install-dev - -# Copy the environment template if you need authenticated audit runs -cp .env.example .env -# Edit .env and set GITHUB_TOKEN= +uv sync --locked --extra dev --extra serve --extra config ``` -If you do not use `make`, the equivalent pip command is: - -```bash -python3 -m pip install -e ".[dev,config]" -``` +The `serve` extra is needed by web-route tests. `semantic` adds heavyweight ML +and SQLite vector dependencies and remains opt-in for routine local checks. +The older `make install-dev` / pip equivalent installs only `dev,config`, so it +does not provision the full CI test environment. -## Running Tests +## Safe smoke and focused tests ```bash -make test +uv run --locked python -m github_repo_auditor.cli --help +uv run --locked --extra dev --extra serve --extra config pytest tests/test_scorer.py -q -p no:cacheprovider ``` -This runs the full test suite under `tests/` with verbose output. The suite covers all 12 analyzers, the scorer, the report generator, the GitHub API client, and the CLI integration. +The scorer tests use synthetic metadata and block live scorecard lookup. Replace +the test path with the focused fixture tests for your changed module after +checking their prerequisites. CLI help is not a live audit. -To run a single test file: +For report/export changes, generate the committed demo in a disposable checkout: ```bash -python3 -m pytest tests/test_scorer.py -v +uv run --locked --extra config python scripts/build_demo_artifacts.py ``` -To run tests matching a pattern: +This uses `fixtures/demo/sample-report.json` and regenerates only `output/demo/`, +including replacement of older demo artifacts. It does not audit the workstation +or contact provider accounts. Live `audit run`, portfolio-truth regeneration, +seam identity-resolution, writeback, and deployment commands belong to explicit +operator tasks, not a fixture verification pass. -```bash -python3 -m pytest tests/ -k "readme" -v -``` +## Broader checks and optional lanes -## Linting and Formatting +The lightweight local/Cloud suite excludes the optional semantic-index module: ```bash -# Check for lint errors (does not modify files) -make lint - -# Auto-format source and test files -make format +uv run --locked --extra dev --extra serve --extra config pytest tests/ -q -p no:cacheprovider -k 'not semantic_index' +uv run --locked --extra dev ruff check src/ tests/ +uv run --locked --extra dev ruff format --check src/ tests/ ``` -Both commands target `src/` and `tests/`. The project uses [Ruff](https://docs.astral.sh/ruff/) configured in `pyproject.toml` with `target-version = "py311"` and `line-length = 100`. Rules `E`, `F`, and `I` (errors, pyflakes, isort) are enabled. - -CI will reject PRs that fail `ruff check`. Run `make lint` before opening a PR. +`ruff format --check` is read-only; omit `--check` only when deliberately +formatting source. Ruff's actual settings are in `pyproject.toml`. -## Type Checking +[GitHub CI](.github/workflows/ci.yml) runs the full suite with `dev,serve,semantic` +on Python 3.11 and 3.12. To reproduce that lane locally, include the semantic +extra explicitly: ```bash -make type-check +uv run --locked --extra dev --extra serve --extra semantic --extra config pytest tests/ -q -p no:cacheprovider ``` -This runs `mypy src/ --ignore-missing-imports`. All new functions must have complete type annotations — no `Any` usage, no untyped parameters. +CI type-checks the operator-trend modules listed in that workflow. The broader +`make type-check` target runs `mypy src/ --ignore-missing-imports`; it is a +separate whole-source diagnostic, not a claim that CI checks every module. +For wheel/sdist packaging, install the `build` extra and run +`uv run --locked --extra build python -m build`; this writes local `dist/` +artifacts and does not publish them. Mutation testing, workbook checks and +release-specific prerequisites remain in +[docs/release-gates.md](docs/release-gates.md), including the mutation lane's +Python 3.13 requirement. + +## Conditional UI and report verification + +When HTML/report presentation changes, open the generated +`output/demo/dashboard-*.html` and inspect the changed views with synthetic data. +For serve changes, run the fixture route tests in `tests/test_serve.py` with the +`serve` extra and follow [the web UI guide](docs/audit-serve.md) using +`output/demo/`. Do not start a live audit or submit provider/writeback actions to +check a UI change. Browser checks are conditional on changed presentation or +interaction; a documentation-only PR does not require them. Synthetic output +and route tests do not establish production or human acceptance. ## Coding Conventions diff --git a/README.md b/README.md index 9e92eeb..86069b2 100644 --- a/README.md +++ b/README.md @@ -324,31 +324,16 @@ For a full description of all flags grouped by workflow, see ### Run tests -```bash -pytest -``` +Use the [contributor verification lanes](CONTRIBUTING.md#safe-smoke-and-focused-tests) +for the focused fixture check and broader suites with their required extras. ## Development -For local development, clone the repo and install with the dev + config extras: - -```bash -git clone https://github.com/saagpatel/GithubRepoAuditor.git -cd GithubRepoAuditor -pip install -e ".[dev,serve,semantic,config]" -``` - -Common dev commands: - -```bash -python3 -m pytest -q -p no:cacheprovider # full test suite -python3 -m ruff check src/ tests/ # lint -python3 -m ruff format src/ tests/ # format -make workbook-gate # workbook invariant check -make release-gate # mutation testing gate -``` - -See [docs/release-gates.md](docs/release-gates.md) for the full gate checklist. +See [CONTRIBUTING.md](CONTRIBUTING.md) for the locked local environment, safe +fixture smoke, focused and broader test lanes, lint/format/typecheck/build +commands, optional semantic prerequisites, and conditional UI/report checks. +Live audits and portfolio-truth regeneration are operator workflows, not test +smokes. [docs/release-gates.md](docs/release-gates.md) retains the release gates. ## Tech Stack