From e5b82917897d9da4a3b4f97e3cb13b7f09ad10a6 Mon Sep 17 00:00:00 2001 From: Really Him Date: Mon, 16 Nov 2026 02:56:35 -0500 Subject: [PATCH] feat(badge-buddy)!: use MCP for BadgeApp interactions --- README.md | 5 +- docs/criteria-maintenance.md | 2 +- docs/planning/badge-buddy-mcp-migration.md | 34 + plugins/badge-buddy/.mcp.json | 8 + plugins/badge-buddy/README.md | 37 +- plugins/badge-buddy/scripts/ossf.py | 1000 --------- .../scripts/ossf_review/__init__.py | 6 +- .../scripts/ossf_review/remotes.py | 65 + .../scripts/ossf_review/storage.py | 531 ----- .../scripts/ossf_review/submission.py | 325 --- .../badge-buddy/scripts/ossf_review/sync.py | 529 ----- plugins/badge-buddy/scripts/review_board.py | 84 + plugins/badge-buddy/scripts/scorecard.py | 252 ++- .../skills/ossf-bp-badges/README.md | 2 +- .../skills/ossf-bp-badges/SKILL.md | 84 +- .../ossf-bp-badges/references/application.md | 128 +- .../ossf-bp-badges/references/baseline.md | 10 +- .../badge-progress/.claude-plugin/plugin.json | 8 +- plugins/badge-progress/README.md | 24 +- plugins/badge-progress/hooks/parse.ts | 115 -- plugins/badge-progress/hooks/register.tsx | 226 +- .../badge-progress/tests/progress.test.tsx | 204 +- plugins/badge-progress/types/index.d.ts | 36 - tests/badge-buddy/test_baseline_aliases.py | 277 +-- .../test_documentation_integrity.py | 77 +- tests/badge-buddy/test_ossf_cli.py | 1819 ----------------- tests/badge-buddy/test_remotes.py | 48 + tests/badge-buddy/test_review_board_cli.py | 143 ++ tests/badge-buddy/test_storage.py | 281 --- tests/badge-buddy/test_sync.py | 569 ------ 30 files changed, 753 insertions(+), 6176 deletions(-) create mode 100644 docs/planning/badge-buddy-mcp-migration.md create mode 100644 plugins/badge-buddy/.mcp.json delete mode 100755 plugins/badge-buddy/scripts/ossf.py create mode 100644 plugins/badge-buddy/scripts/ossf_review/remotes.py delete mode 100644 plugins/badge-buddy/scripts/ossf_review/storage.py delete mode 100644 plugins/badge-buddy/scripts/ossf_review/submission.py delete mode 100644 plugins/badge-buddy/scripts/ossf_review/sync.py create mode 100755 plugins/badge-buddy/scripts/review_board.py delete mode 100644 plugins/badge-progress/hooks/parse.ts delete mode 100644 plugins/badge-progress/types/index.d.ts delete mode 100644 tests/badge-buddy/test_ossf_cli.py create mode 100644 tests/badge-buddy/test_remotes.py create mode 100644 tests/badge-buddy/test_review_board_cli.py delete mode 100644 tests/badge-buddy/test_storage.py delete mode 100644 tests/badge-buddy/test_sync.py diff --git a/README.md b/README.md index 03f3a6a..e190f63 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ Plugins to help open source projects grow and maintain: quickstart a repo with c | **badge-buddy** | Helps projects of any size achieve meaningful open source badges. An unofficial guide and implementation assistant for the OpenSSF Best Practices badges (Passing, Silver, Gold), the Security Baseline, and Scorecard. Set up useful coverage and analysis badges, improve testing, and maintain secure GitHub workflows. | [plugins/badge-buddy](plugins/badge-buddy/README.md) | | **starter-buddy** | Quickstart a GitHub repository with key community-files, issue templates, and other sensible defaults, to save you time setting up any project. | [plugins/starter-buddy](plugins/starter-buddy/README.md) | | **release-buddy** | Versioning and changelog guidance, plus signed source tags and immutable GitHub releases with optional build provenance and scoped dependency evidence. | [plugins/release-buddy](plugins/release-buddy/README.md) | -| **badge-progress** | A mod for Badge Buddy users: a pane with each badge section's answer counts, and a progress bar above the prompt while Claude records answers. | [plugins/badge-progress](plugins/badge-progress/README.md) | +| **badge-progress** | Progress tracking is paused during the MCP migration; its pane explains the transition and points users to Badge Buddy’s retained local preview board. | [plugins/badge-progress](plugins/badge-progress/README.md) | | **workflow-guard** | A mod that stops Claude from adding unpinned actions or broad top-level token permissions to GitHub Actions workflows. | [plugins/workflow-guard](plugins/workflow-guard/README.md) | ## Install @@ -62,6 +62,7 @@ hidden = [".github", ".gitignore", ".nvmrc", ".pre-commit-config.yaml", ".pretti │ │ │ ├── ossf-bp-badges/ │ │ │ ├── ossf-scorecard/ │ │ │ └── static-analysis/ +│ │ ├── .mcp.json │ │ └── README.md │ ├── badge-progress/ │ ├── release-buddy/ @@ -94,7 +95,7 @@ make plugin-validate # validate each plugin's structure (needs the Claude Code make mod-test # run the mods' tests (needs the Claude Code CLI) ``` -The runtime uses only the Python standard library; the local `venv` holds the development dependencies. `make check` runs the plugin and maintenance suites in separate processes and compiles the Python sources. Continuous integration runs the same target on every push and pull request. See [criteria maintenance](docs/criteria-maintenance.md) for catalog updates and [plugin releases](docs/releases.md) for how to release a plugin: merge its version and reviewed notes, review the checks and OSV report, then approve publication in GitHub. The workflow tags the checked commit and publishes an immutable release. See [Verifying a plugin release](VERIFYING.md) to check its source and attachments; marketplace installation does not automatically pin or verify a release. +Local Python helpers use the standard library; Badge Buddy’s BadgeApp operations use the separately installed `best-practices-mcp` package. The local `venv` holds development dependencies. `make check` runs the plugin and maintenance suites in separate processes and compiles the Python sources. Continuous integration runs the same target on every push and pull request. See [criteria maintenance](docs/criteria-maintenance.md) for catalog updates and [plugin releases](docs/releases.md) for how to release a plugin: merge its version and reviewed notes, review the checks and OSV report, then approve publication in GitHub. The workflow tags the checked commit and publishes an immutable release. See [Verifying a plugin release](VERIFYING.md) to check its source and attachments; marketplace installation does not automatically pin or verify a release. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to file issues and propose changes. diff --git a/docs/criteria-maintenance.md b/docs/criteria-maintenance.md index c2fefb1..5e47775 100644 --- a/docs/criteria-maintenance.md +++ b/docs/criteria-maintenance.md @@ -1,6 +1,6 @@ # Criteria maintenance -Badge Buddy ships a local criteria catalog with each plugin version. Its guidance and preview aim to match the wording and presentation of the public bestpractices.dev application. Ordinary plugin use reads this catalog without downloading criterion pages; assessment synchronization separately fetches public project answers through the API. +Badge Buddy ships a local criteria catalog with each plugin version. Its guidance and preview aim to match the wording and presentation of the public bestpractices.dev application. The local preview board reads this catalog without downloading criterion pages. Application work uses the MCP server’s own pinned criteria catalog and public project-read tools; compare any observed wording differences rather than assuming both packaged snapshots are identical. The catalog is generated from a pinned [BadgeApp](https://github.com/ossf/best-practices-badge) checkout and its English translations. Before accepting an update, maintainer tooling compares it with the public application pages for Passing, Silver, Gold, and Baseline levels 1–3. The comparison covers criterion identifiers, order, descriptions, details, links, and the requirement markings visible on those pages. Submission flags not exposed in the downloaded HTML remain repository-derived. diff --git a/docs/planning/badge-buddy-mcp-migration.md b/docs/planning/badge-buddy-mcp-migration.md new file mode 100644 index 0000000..f11fb54 --- /dev/null +++ b/docs/planning/badge-buddy-mcp-migration.md @@ -0,0 +1,34 @@ +# Badge Buddy MCP migration + +Date: 2026-11-16. Implementation branch: `codex/badge-buddy-mcp`, based on `origin/main`. The existing code-scanning/release work branch is preserved separately. + +## Plan and review + +Replace Badge Buddy's duplicate BadgeApp transport and draft controller with the published `best-practices-mcp==0.5.0` stdio server. The plugin remains responsible for advisory material, interpretation, user interaction, peer review, project improvements, and the passive local preview board. The MCP owns project discovery, public reads, mechanical document checks, optional server drafts, and proposal URL generation. Browser review and saving remain user-controlled. + +The plan was reviewed before implementation. Review retained the following boundaries: + +1. Register the pinned server in the plugin and document `uvx` and Python prerequisites. Use discovered MCP tool names; do not assume identical prefixes across hosts. +2. Make caller-owned explicit documents the ordinary workflow. Server-managed drafts remain optional, and no plugin path is silently repurposed as the MCP data directory. +3. Remove the BadgeApp CLI, local synchronization engine, proposal implementation, and console-fill generator. Preserve Scorecard by extracting its shared GitHub remote normalizer. +4. Retain all advisory reference documents, the bundled display catalog and examples, and the local board assets. Add a small offline renderer accepting an explicit assessment file, output path and section; exercise every badge level. +5. Explain how to reuse existing assessments without automatic migration or silent conflict resolution. Preserve source files and existing answers, including unknown and empty values. +6. Update relevant tests and installation/application documentation. Retire tests for the deleted implementation; retain board, catalog, alias, Scorecard and maintenance coverage. + +No release is published by this migration. The current plugin manifest version is left for the maintainer's release decision. The independently released MCP dependency is pinned to 0.5.0. + +## Expected review and verification + +Run the offline plugin and maintenance suites, source compilation, JSON/Markdown checks, README tree validation and plugin manifest validation. Exercise the board entry point across all six levels and inspect that no CLI BadgeApp network or console-script transfer path remains. A host installation/reload is still needed to qualify automatic MCP registration in a real host; offline configuration checks do not establish that result. + +## Dependent progress mod + +Review found that `badge-progress` consumed the deleted controller's Bash output and restored cached counts. Its tracking is explicitly suspended in this migration: the pane shows a transition notice, and old counts are neither restored nor displayed. The local board remains available. A future adapter needs documented host MCP events, project-bound state, catalog-aware counts, separate saved/draft semantics, and a defined strategy for patch-only update results. This is preferable to a silent regression or an invented fallback to the removed CLI. + +## Verification record + +The offline `make check` run passed 180 tests across badge-buddy (72), starter-buddy (17), release-buddy (1), and maintenance (90), then compiled the Python sources. The board CLI tests cover all six levels and preserve the input file. Both badge-progress suspension tests passed, including a check that persisted counts are not read. `claude plugin validate` passes for badge-buddy and badge-progress, with existing missing-icon warnings; the paused mod also receives advice about an omitted install example. Formatting hooks and the README tree check pass. The pinned command reports `bestpractices-mcp 0.5.0` after refreshing uv's package index cache. + +The Scorecard helper's only semantic change is importing the extracted remote normalizer; the repository's required formatter also reformats the existing file. No criteria text, board assets or other advisory skill functionality was removed. The deleted tests exercised the retired duplicate BadgeApp implementation; retained behavior has board, alias, Scorecard, catalog and integration/configuration coverage. + +Independent implementation review caught a numeric board label that could disagree with the draft’s `id`. The renderer now rejects mismatches before creating or replacing HTML; tests cover mismatches, matching IDs, id-less drafts and explicit local labels. diff --git a/plugins/badge-buddy/.mcp.json b/plugins/badge-buddy/.mcp.json new file mode 100644 index 0000000..a9a93a5 --- /dev/null +++ b/plugins/badge-buddy/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "bestpractices": { + "command": "uvx", + "args": ["--from", "best-practices-mcp==0.5.0", "bestpractices-mcp"] + } + } +} diff --git a/plugins/badge-buddy/README.md b/plugins/badge-buddy/README.md index b6f6c0c..d7d40e3 100644 --- a/plugins/badge-buddy/README.md +++ b/plugins/badge-buddy/README.md @@ -12,7 +12,7 @@ Badge Buddy helps maintainers work through the [OpenSSF Best Practices](https:// ## Get started -The command-line helpers require Python 3.11 or newer, available as `python3` on your PATH. They use only the Python standard library. +Install [uv](https://docs.astral.sh/uv/getting-started/installation/) so `uvx` is available to your host, and use Python 3.11 or newer. The plugin registers the published `best-practices-mcp==0.5.0` stdio server for BadgeApp operations. The separate Scorecard helper and local board renderer use Python’s standard library. Add the marketplace and install the plugin in Claude Code: @@ -30,7 +30,7 @@ Ask for the help you need: Badge Buddy covers Passing, Silver, Gold, and Security Baseline levels 1–3. You can ask questions, prepare answers, or work on the project as the conversation develops. For a new application, [register your project](https://www.bestpractices.dev/projects/new) on the badge website. Registration is not needed for explanations or implementation help, and you can ask to prepare answers before registering. -The current version primarily supports projects hosted on GitHub. Guidance about the criteria is useful on other forges, but synchronized assessments require a GitHub repository. +Reload the plugin or restart the host after installation, then check that its `bestpractices` MCP server is connected. The server runs `uvx --from best-practices-mcp==0.5.0 bestpractices-mcp`; it requires no BadgeApp credentials. Other MCP hosts can register that command manually if they do not load plugin MCP configuration. Tool prefixes vary by host. If connection fails, restore the MCP connection before application operations rather than falling back to the retired BadgeApp CLI. ## Preparing answers @@ -48,13 +48,13 @@ For the Metal badges, a response and its effect on badge progress are distinct: ## Saving and reviewing progress -Claude saves answers in `.bestpractices.json` in private plugin storage by default. This lets you resume later without adding files to your repository. An existing repository assessment or an established storage preference takes precedence. +Claude can keep a caller-owned JSON draft and pass it explicitly to the MCP, or use its optional server-managed draft storage. Explicit documents are the normal workflow and need no server storage. Existing repository files and your established storage preference take precedence. Old plugin assessments remain readable JSON; see [migration guidance](skills/ossf-bp-badges/references/application.md#existing-plugin-drafts) before reusing them. No files are moved automatically. If you keep `.bestpractices.json` in your repository, Claude normally prepares changes in a temporary copy. You review those changes before they are written back, and Claude checks for intervening edits to the repository file. You can ask it to edit that file directly instead. Temporary work is applied or discarded with you at session end. Tracking the file in Git is your choice. Ask to preview your answers to open a local board. It shows the official criteria, your answers and justifications, and evidence links. Each board covers one badge section. You can read all criteria together or choose a response category such as Unmet. A table of contents helps you move through the list. -The board refreshes as Claude updates your assessment. Reading or navigating it does not change an answer. Discuss revisions in the conversation. During an interactive revision, Claude updates the justification first and keeps the response unchanged while you review the wording. After you approve it, Claude updates the response. Initial drafts can include both together. +The board is a local plugin feature outside the MCP’s scope. Claude rerenders it after draft changes; the open HTML refreshes automatically to show the regenerated snapshot. Reading or navigating it does not change an answer. Discuss revisions in the conversation. During an interactive revision, Claude updates the justification first and keeps the response unchanged while you review the wording. After you approve it, Claude updates the response. Initial drafts can include both together. ## Submitting answers @@ -62,9 +62,8 @@ Claude offers the available submission paths and follows your preference: - **Proposal URLs:** open your proposed answers in the official edit form, with changes highlighted for review. Nothing is saved by opening a link. - **A repository `.bestpractices.json`:** commit the exported file so the badge site can read it as automated-tool input. The site fills blanks and flags differences for review without overwriting answers a person has already recorded. -- **A console fill script:** paste the generated script into your browser's console on the edit page. This is useful for wording-only edits, long answers, or a selected group of fields. The script fills the form without saving it. -You review and save the website form. Claude may help with login or saving only when you explicitly ask it to perform that action. The plugin's controller does not authenticate or write to the badge site. See the [submission guide](skills/ossf-bp-badges/references/application.md#website-transfers) for details. +You review and save the website form. Claude may help with login or saving only when you explicitly ask it to perform that action. The MCP server does not authenticate or write to the badge site. Console-fill scripts are no longer provided. See the [submission guide](skills/ossf-bp-badges/references/application.md#website-transfers) for details. ## OpenSSF Scorecard @@ -110,30 +109,20 @@ make check make plugin-validate ``` -The runtime uses only the Python standard library. The root Makefile runs all plugin and maintenance tests, then compiles the Python sources. Plugin validation requires the Claude Code CLI. See the repository [README](../../README.md) for the layout. +The local board and Scorecard helper use only the Python standard library; BadgeApp operations use the separately installed MCP package. The root Makefile runs all plugin and maintenance tests, then compiles the Python sources. Plugin validation requires the Claude Code CLI. See the repository [README](../../README.md) for the layout. -The badge controller provides these commands: +The plugin’s [`.mcp.json`](.mcp.json) registers the pinned server. Discovery, criteria, public progress, draft construction/checks and proposal URLs use its tools. Optional `read_draft` and `update_draft` calls use server-managed storage; they are not required for caller-owned documents. See the [application guide](skills/ossf-bp-badges/references/application.md) for the mapping and host responsibilities. -| Command | Purpose | -| --------------------------------- | ----------------------------------------------------------------------------------------------------- | -| `status` | Synchronize and report registration, differences, counts, and answers. | -| `apply --section
` | Validate and record updates for a badge section. | -| `review --section
` | Open the section's board; add `--view all` to show all criteria. | -| `export --output ` | Write the assessment to an explicit path. | -| `propose --section
` | Generate official proposal URLs. | -| `fill-script --section
` | Generate a script for wording changes; use `--criteria` for a subset or `--all` for the full section. | - -For direct controller use, provide the repository and private data paths. When using a repository assessment or a temporary copy, select the existing working file explicitly: +The standalone board renderer accepts explicit files and never contacts BadgeApp: ```bash -venv/bin/python plugins/badge-buddy/scripts/ossf.py \ - --repo /path/to/project \ - --data-dir /path/to/private/plugin-data \ - --assessment-file /tmp/assessment-session.json \ - review --view all --section passing +venv/bin/python plugins/badge-buddy/scripts/review_board.py \ + --input /path/to/draft.json \ + --output /path/to/board.html \ + --project-id 16754 --section baseline-1 --view all ``` -`--assessment-file` must point to an existing flat JSON object. All operations use that file directly. Omit it to use private storage when the repository has no assessment file. Run `status` online once at the start of each Claude Code session to verify the repository/project association and reconcile saved website answers with local answers. Subsequent edits, previews, and transfers use that saved public snapshot without fetching again. Rerun online status if the repository or project ID changes. Run `status` again after saving website changes, or use `status --offline` to inspect local progress. Public synchronization uses GET requests and needs no GitHub credentials; `status --project-id ` selects a known badge entry. See the [application guide](skills/ossf-bp-badges/references/application.md#start-or-resume) for storage and synchronization details. +It reports a local HTML URL; add `--open` to open it directly. It supports all six badge sections. Rerun it after editing the input JSON. The board displays a snapshot using the bundled catalog and does not compare saved and proposed values automatically. The Scorecard controller supports `fetch --repo owner/repo --output `, `explain --input `, and `diff --before --after `. It preserves published results and compares them without recomputing the upstream score. diff --git a/plugins/badge-buddy/scripts/ossf.py b/plugins/badge-buddy/scripts/ossf.py deleted file mode 100755 index ec719da..0000000 --- a/plugins/badge-buddy/scripts/ossf.py +++ /dev/null @@ -1,1000 +0,0 @@ -#!/usr/bin/env python3 -"""Operate an OpenSSF Best Practices assessment without exposing storage paths.""" - -from __future__ import annotations - -import sys - -if sys.version_info < (3, 11): - sys.exit( - "Badge Buddy requires Python 3.11 or newer; " - f"this command is running Python {sys.version_info[0]}.{sys.version_info[1]}. " - "Run it with Python 3.11+ or put that interpreter first on PATH as python3." - ) - -import argparse -from collections.abc import Callable, Mapping, Sequence -import json -import os -from pathlib import Path -import re -from typing import Any -from urllib.parse import urlparse -import webbrowser - - -from ossf_review.board import board_refresh_lock, review_path, write_board -from ossf_review.criteria import CriteriaCatalog, Criterion, SECTION_NAMES -from ossf_review.fields import normalize_assessment_fields -from ossf_review.storage import DataStore -from ossf_review.submission import ( - ALLOWED_BASE_URLS, - DEFAULT_MAX_URL_BYTES, - PRODUCTION_BASE_URL, - STAGING_BASE_URL, - build_fill_script, - build_proposal_urls, - validate_base_url, - wording_only_criteria, -) -from ossf_review.sync import ( - BestPracticesClient, - PROJECT_METADATA_FIELDS, - ProjectResolutionError, - SyncConflict, - SyncResult, - UnregisteredProjectError, - discover_repository, - handoff_local_assessment, - synchronize_project, - write_assessment_file, -) - - -REGISTRATION_URL = "https://www.bestpractices.dev/projects/new" -VALID_STATUSES = {"Met", "Unmet", "N/A", "?"} - -# Advisory only: a justification is public form text in the project's own -# voice. These phrases indicate assessment narration leaking into the form -# (see skills/ossf-bp-badges/references/justification-style.md). Patterns are -# deliberately narrow — criteria themselves legitimately use words such as -# "review" and "unreviewable". -_STYLE_PATTERNS: tuple[tuple[re.Pattern[str], str], ...] = tuple( - (re.compile(expression, re.IGNORECASE), reason) - for expression, reason in ( - ( - r"\bmaintainer\s+(?:says|said|states|stated|confirms|confirmed|reports|reported|asserts|asserted)\b", - "the project authors the form; state the fact without sourcing narration", - ), - ( - r"\b(?:per|according\s+to)\s+the\s+maintainer\b", - "the project authors the form; state the fact without sourcing narration", - ), - ( - r"\bthe\s+user\s+(?:says|said|states|stated|confirms|confirmed)\b", - "the project authors the form; state the fact without sourcing narration", - ), - (r"\bthis\s+(?:session|conversation)\b", "process history does not belong on the form"), - (r"\bclaude\b", "the assistant is not part of the public record"), - (r"\bcorrected\s+after\b", "process history does not belong on the form"), - ( - r"\b(?:first|second|third|prior|previous)\s+review\b", - "review-round history does not belong on the form", - ), - (r"\breview\s+round\b", "review-round history does not belong on the form"), - ( - r"\bno\s+direct\s+evidence\b", - "if evidence is insufficient, leave the status '?' instead of hedging", - ), - ( - r"\bcould\s+not\s+(?:be\s+)?verif\w+\b", - "if evidence is insufficient, leave the status '?' instead of hedging", - ), - (r"\bevidence\s+plane\b", "plane classification lives in the conversation, not the form"), - ( - r"\bcorrects?\s+(?:a|the|our)\s+(?:previous|earlier|prior)\b", - "the form states current truth; correction history does not belong on it", - ), - ( - r"\b(?:previously|earlier)\s+(?:stated|recorded|marked|listed|answered)\b", - "the form states current truth; correction history does not belong on it", - ), - ( - r"\bupdated\s+to\s+reflect\b", - "the form states current truth; correction history does not belong on it", - ), - ( - r"\bhas\s+been\s+(?:revised|corrected)\b", - "the form states current truth; correction history does not belong on it", - ), - ) -) -_STYLE_LENGTH_LIMIT = 700 - - -def _style_warnings(updates: Mapping[str, Any]) -> list[dict[str, str]]: - """Flag justification text that reads as assessment narration.""" - - warnings: list[dict[str, str]] = [] - for field, value in updates.items(): - if not field.endswith("_justification") or not isinstance(value, str): - continue - for pattern, reason in _STYLE_PATTERNS: - match = pattern.search(value) - if match: - warnings.append( - {"field": field, "matched": match.group(0), "reason": reason} - ) - if len(value) > _STYLE_LENGTH_LIMIT: - warnings.append( - { - "field": field, - "matched": f"{len(value)} characters", - "reason": ( - "very long for form text; state the conclusion and the " - "decisive evidence, keep the analysis in the conversation" - ), - } - ) - return warnings - - -class CommandError(RuntimeError): - """A deterministic, user-facing command failure.""" - - -def _assert_badge_site_url(url: str) -> None: - """Refuse to hand the browser anything but an https badge-site URL. - - The base URL is validated when the plan is built; this re-check guards the - exact string that reaches ``webbrowser.open`` so no later transformation - can widen it. - """ - - parsed = urlparse(url) - origin = f"{parsed.scheme}://{parsed.netloc}" - if parsed.scheme != "https" or origin not in ALLOWED_BASE_URLS: - raise CommandError(f"refusing to open a URL outside the badge site: {url}") - - -def _path_from_argument_or_environment( - explicit: Path | None, - environment_name: str, - *, - fallback: Path | None = None, -) -> Path: - if explicit is not None: - selected = explicit - else: - configured = os.environ.get(environment_name) - if configured: - selected = Path(configured) - elif fallback is not None: - selected = fallback - else: - raise CommandError( - f"{environment_name} is unavailable; pass the corresponding command option" - ) - if environment_name == "CLAUDE_PLUGIN_DATA" and selected.expanduser().resolve( - strict=False - ) == Path.cwd().resolve(strict=False): - raise CommandError( - "private plugin data must not resolve to the current working directory" - ) - return selected - - -def _add_resolution_arguments(parser: argparse.ArgumentParser) -> None: - parser.add_argument( - "--project-id", help="numeric badge id to verify with online status, or reuse locally" - ) - parser.add_argument( - "--offline", - action="store_true", - help="use the selected working assessment without reading the public API", - ) - parser.add_argument( - "--allow-unregistered", - action="store_true", - help="use a local-only record after the maintainer explicitly defers registration", - ) - - -def build_parser() -> argparse.ArgumentParser: - parser = argparse.ArgumentParser(description=__doc__) - parser.add_argument( - "--repo", - type=Path, - help="project repository (default: CLAUDE_PROJECT_DIR or current directory)", - ) - parser.add_argument( - "--data-dir", - type=Path, - help="private plugin state root (default: CLAUDE_PLUGIN_DATA)", - ) - parser.add_argument( - "--assessment-file", - type=Path, - help="existing working assessment file (required when the repository has an assessment)", - ) - commands = parser.add_subparsers(dest="command", required=True) - - status = commands.add_parser( - "status", - help="refresh the public snapshot and report project status (use at session start)", - ) - _add_resolution_arguments(status) - - apply_updates = commands.add_parser( - "apply", - help="apply confirmed fields to the working assessment", - ) - _add_resolution_arguments(apply_updates) - apply_updates.add_argument( - "--section", - choices=SECTION_NAMES, - required=True, - help="criteria section whose requirements validate this update", - ) - apply_updates.add_argument( - "--review-response", - choices=sorted(VALID_STATUSES), - help="validate justification-only preview edits for this response without setting it", - ) - input_group = apply_updates.add_mutually_exclusive_group(required=True) - input_group.add_argument( - "--input", - metavar="PATH", - help="JSON object to apply, or - to read it from standard input", - ) - input_group.add_argument( - "--json", - dest="json_object", - help="JSON object to apply directly", - ) - - review = commands.add_parser( - "review", - help="open a passive local review record", - ) - _add_resolution_arguments(review) - review.add_argument("--section", choices=SECTION_NAMES, default="passing") - review.add_argument("--view", choices=("overview", "all"), default="overview") - review.add_argument("--no-browser", action="store_true") - - export = commands.add_parser( - "export", - help="write the working assessment to an explicit path", - ) - _add_resolution_arguments(export) - export.add_argument("--output", type=Path, required=True) - - propose = commands.add_parser( - "propose", - help=( - "emit official automation-proposal URL(s) that the " - "user reviews and saves on bestpractices.dev" - ), - ) - _add_resolution_arguments(propose) - propose.add_argument("--section", choices=SECTION_NAMES, required=True) - propose.add_argument( - "--overrides", - help=( - "forwarded verbatim to the badge site's overrides parameter " - "(comma-separated fnmatch globs the SITE may apply over existing " - "answers); it does not filter which fields are proposed locally" - ), - ) - propose.add_argument( - "--reanalyze", - action="store_true", - help="also re-run the badge site's own detectives on page load", - ) - propose.add_argument( - "--base-url", - default=PRODUCTION_BASE_URL, - help=( - "badge site base URL; only the production and staging badge " - "sites are accepted" - ), - ) - propose.add_argument( - "--staging", - action="store_true", - help=f"shortcut for --base-url {STAGING_BASE_URL}", - ) - propose.add_argument( - "--max-url-bytes", - type=int, - default=DEFAULT_MAX_URL_BYTES, - help="practical chunking threshold; upstream documents no limit", - ) - propose.add_argument( - "--open", - dest="open_first", - action="store_true", - help="open the first proposal URL in the browser", - ) - - fill_script = commands.add_parser( - "fill-script", - help=( - "write a console script that fills the edit form " - "for one section without saving it" - ), - ) - _add_resolution_arguments(fill_script) - fill_script.add_argument("--section", choices=SECTION_NAMES, required=True) - fill_script.add_argument("--output", type=Path, required=True) - scope = fill_script.add_mutually_exclusive_group() - scope.add_argument( - "--changed-only", - action="store_true", - help=( - "emit only fields whose wording differs from the saved public snapshot " - "while the status matches (default; run status first)" - ), - ) - scope.add_argument( - "--criteria", - metavar="IDS", - help=( - "comma-separated criterion ids (or display ids) to include, " - "validated against --section" - ), - ) - scope.add_argument( - "--all", - dest="all_fields", - action="store_true", - help="emit every answered criterion in the section", - ) - return parser - - -def _runtime_paths(args: argparse.Namespace) -> tuple[Path, Path]: - repository = _path_from_argument_or_environment( - args.repo, - "CLAUDE_PROJECT_DIR", - fallback=Path.cwd(), - ) - data_dir = _path_from_argument_or_environment( - args.data_dir, - "CLAUDE_PLUGIN_DATA", - ) - return repository, data_dir - - -def _synchronize( - args: argparse.Namespace, - *, - store_factory: Callable[[Path], Any], - client_factory: Callable[[], Any], -) -> tuple[Any, SyncResult, Path]: - repository, data_dir = _runtime_paths(args) - store = store_factory(data_dir) - if args.assessment_file is not None: - store.use_assessment_file(args.assessment_file) - client = client_factory() if args.command == "status" and not args.offline else None - result = synchronize_project( - store, - repository, - project_id=args.project_id, - client=client, - allow_unregistered=args.allow_unregistered, - ) - return store, result, data_dir - - -def _status_counts( - catalog: CriteriaCatalog, - assessment: Mapping[str, Any], -) -> dict[str, dict[str, int]]: - classified = catalog.classify_flat(assessment) - result: dict[str, dict[str, int]] = {} - for section in SECTION_NAMES: - counts = { - "total": 0, - "met": 0, - "unmet": 0, - "not_applicable": 0, - "unknown": 0, - "evidence_gaps": 0, - } - answers = classified[section] - for criterion in catalog.section(section): - counts["total"] += 1 - answer = answers.get(criterion.id, {}) - status = answer.get("status", "?") - if status == "Met": - counts["met"] += 1 - justification = answer.get("justification") - if criterion.met_justification_required and not _has_required_justification( - justification - ): - counts["evidence_gaps"] += 1 - elif criterion.met_url_required and not _has_evidence_url( - justification - ): - counts["evidence_gaps"] += 1 - elif status == "Unmet": - counts["unmet"] += 1 - elif status == "N/A": - counts["not_applicable"] += 1 - if criterion.na_justification_required and not _has_required_justification( - answer.get("justification") - ): - counts["evidence_gaps"] += 1 - else: - counts["unknown"] += 1 - decided = counts["total"] - counts["unknown"] - counts["decided"] = decided - counts["decided_percent"] = int(round(100 * decided / counts["total"], 1)) - result[section] = counts - return result - - -def _has_required_justification(value: Any) -> bool: - # Match justification_good? in the catalog's pinned BadgeApp project.rb: - # count characters without stripping; only the exact '// ' prefix is a comment. - return isinstance(value, str) and not value.startswith("// ") and len(value) >= 5 - - -def _has_evidence_url(value: Any) -> bool: - # Match contains_url?'s deliberately permissive rule, not URL reachability. - return ( - isinstance(value, str) - and not value.startswith("// ") - and re.search(r"https?://[^/. ]+\.[^ ]", value) is not None - ) - - -def _conflict_record(conflict: SyncConflict) -> dict[str, Any]: - source = { - "public API": "public_api", "local_draft": "local_draft", - }.get(conflict.source, "repository") - return { - "field": conflict.field, - "preserved": conflict.preserved, - "incoming": conflict.incoming, - "source": source, - } - - -def _public_snapshot_metadata(result: SyncResult) -> dict[str, Any]: - return { - "source": "live" if result.public_loaded else ( - "cached" if result.public_fetched_at else "none" - ), - "fetched_at": result.public_fetched_at, - } - - -def _status_payload( - result: SyncResult, - catalog: CriteriaCatalog, -) -> dict[str, Any]: - resolution = result.resolution - return { - "schema_version": 1, - "state": "registered" if resolution.registered else "unregistered", - "project": { - "identifier": resolution.identifier, - "project_id": resolution.project_id, - "registered": resolution.registered, - "remote": resolution.repository.remote, - "repository_url": resolution.repository.url, - "name": resolution.repository.project_name, - }, - "sources": { - "public_loaded": result.public_loaded, - "public_snapshot": _public_snapshot_metadata(result), - "repository_backed": result.repository_file is not None, - }, - "conflicts": [_conflict_record(item) for item in result.conflicts], - "sections": _status_counts(catalog, result.assessment), - "wording_only_updates": _wording_only_by_section(result, catalog), - "assessment": result.assessment, - } - - -def _wording_only_by_section( - result: SyncResult, - catalog: CriteriaCatalog, -) -> dict[str, list[str]]: - """Sections where the public snapshot matches statuses but wording differs. - - Show edits that can use a fill script, or a proposal URL with overrides - when replacing existing wording. - """ - - if not result.public_document: - return {} - updates: dict[str, list[str]] = {} - for section in SECTION_NAMES: - identifiers = wording_only_criteria( - result.assessment, - catalog, - section=section, - public_document=result.public_document, - ) - if identifiers: - updates[section] = list(identifiers) - return updates - - -def _registration_payload(repository: Path, *, offline: bool) -> dict[str, Any]: - identity = discover_repository(repository) - return { - "schema_version": 1, - "state": "registry_miss" if offline else "registration_required", - "project": { - "identifier": None, - "project_id": None, - "registered": False, - "remote": identity.remote, - "repository_url": identity.url, - "name": identity.project_name, - }, - "registration_url": REGISTRATION_URL, - "unregistered_available": True, - "next_step": ( - "Run status online to look up and verify the project; " - "supply --project-id on that command if known." - if offline else "Register the project, or use --allow-unregistered." - ), - } - - -def _load_updates(args: argparse.Namespace) -> dict[str, Any]: - if args.json_object is not None: - source = args.json_object - label = "--json" - elif args.input == "-": - source = sys.stdin.read() - label = "standard input" - else: - path = Path(args.input) - try: - source = path.read_text(encoding="utf-8") - except (OSError, UnicodeDecodeError) as error: - raise CommandError( - f"could not read update input {path}: {error}" - ) from error - label = str(path) - try: - value = json.loads(source) - except json.JSONDecodeError as error: - raise CommandError(f"invalid JSON from {label}: {error}") from error - if not isinstance(value, dict): - raise CommandError("assessment updates must be one flat JSON object") - return value - - -def _canonical_update_key( - catalog: CriteriaCatalog, - field: str, - section: str, -) -> tuple[str, Criterion]: - classified = catalog.classify_flat({field: None}) - suffix = "status" if field.endswith("_status") else "justification" - criterion_ids = set(classified[section]) - if not criterion_ids: - if not any(classified.values()): - raise CommandError(f"unknown assessment field: {field}") - raise CommandError(f"assessment field {field!r} is not in section {section!r}") - if len(criterion_ids) != 1: - raise CommandError(f"ambiguous assessment field in section {section!r}: {field}") - criterion_id = next(iter(criterion_ids)) - return f"{criterion_id}_{suffix}", catalog.get(criterion_id, section) - - -def _validated_updates( - catalog: CriteriaCatalog, - current: Mapping[str, Any], - proposed: Mapping[str, Any], - *, - section: str, - review_response: str | None = None, -) -> dict[str, Any]: - normalized: dict[str, Any] = {} - affected: dict[str, Criterion] = {} - for raw_field, value in proposed.items(): - if not isinstance(raw_field, str): - raise CommandError("assessment field names must be strings") - if review_response is not None and not raw_field.endswith("_justification"): - raise CommandError("--review-response accepts only justification fields") - if raw_field in PROJECT_METADATA_FIELDS: - if not isinstance(value, str): - raise CommandError(f"{raw_field} must be a string") - normalized[raw_field] = value - continue - if not (raw_field.endswith("_status") or raw_field.endswith("_justification")): - raise CommandError(f"unknown assessment field: {raw_field}") - field, criterion = _canonical_update_key(catalog, raw_field, section) - if field.endswith("_justification") and not isinstance(value, str): - raise CommandError(f"{field} must be a string") - if field in normalized and normalized[field] != value: - raise CommandError(f"conflicting aliases were supplied for {field}") - normalized[field] = value - affected.setdefault(criterion.id, criterion) - - effective = normalize_assessment_fields(current) - effective.update(normalized) - for criterion_id, criterion in affected.items(): - status_field = f"{criterion_id}_status" - status = review_response if review_response is not None else effective.get(status_field) - justification = effective.get(f"{criterion_id}_justification") - valid_status = isinstance(status, str) and status in VALID_STATUSES - if status_field in normalized and not valid_status: - choices = ", ".join(sorted(VALID_STATUSES)) - raise CommandError(f"{status_field} must be one of: {choices}") - if not valid_status: - continue - if status == "N/A" and not criterion.na_allowed: - raise CommandError(f"{status_field} does not allow N/A") - if ( - status == "N/A" - and criterion.na_justification_required - and not _has_required_justification(justification) - ): - raise CommandError(f"{status_field} requires an N/A justification") - if ( - status == "Met" - and criterion.met_justification_required - and not _has_required_justification(justification) - ): - raise CommandError( - f"{status_field} requires evidence or a justification" - ) - if ( - status == "Met" - and criterion.met_url_required - and not _has_evidence_url(justification) - ): - raise CommandError(f"{status_field} requires a public evidence URL") - return normalized - - -def _print_json(payload: Mapping[str, Any]) -> None: - print(json.dumps(dict(payload), ensure_ascii=False, indent=2, sort_keys=True)) - - -def _refresh_open_boards( - store: Any, - result: SyncResult, - catalog: CriteriaCatalog, - data_dir: Path, -) -> None: - """Best-effort refresh existing boards from the latest canonical state.""" - - identifier = result.resolution.identifier - try: - with board_refresh_lock(data_dir, identifier): - assessment = store.load_assessment(identifier) - for section in SECTION_NAMES: - output = review_path(data_dir, identifier, section) - if output.exists(): - write_board( - assessment, - output, - project_id=identifier, - section=section, - catalog=catalog, - ) - except Exception as error: # The passive projection is never canonical. - print(f"warning: passive review board refresh failed: {error}", file=sys.stderr) - - -def _open_review( - result: SyncResult, - catalog: CriteriaCatalog, - data_dir: Path, - section: str, - browser_open: Callable[[str], Any], - *, - view: str, - no_browser: bool, -) -> str: - output = review_path(data_dir, result.resolution.identifier, section) - write_board( - result.assessment, - output, - project_id=result.resolution.identifier, - section=section, - catalog=catalog, - ) - url = output.as_uri() - if view == "all": - url += "#view=all" - if not no_browser: - browser_open(url) - return url - - -def main( - argv: Sequence[str] | None = None, - *, - store_factory: Callable[[Path], Any] = DataStore, - client_factory: Callable[[], Any] = BestPracticesClient, - catalog_factory: Callable[[], CriteriaCatalog] = CriteriaCatalog, - browser_open: Callable[[str], Any] = webbrowser.open, -) -> int: - parser = build_parser() - args = parser.parse_args(argv) - output = None - try: - repository, data_dir = _runtime_paths(args) - catalog = catalog_factory() - try: - store, result, _data_dir = _synchronize( - args, - store_factory=store_factory, - client_factory=client_factory, - ) - except UnregisteredProjectError: - payload = _registration_payload( - repository, offline=args.offline or args.command != "status", - ) - _print_json(payload) - return 0 if args.command == "status" else 3 - - if args.command == "status": - _refresh_open_boards(store, result, catalog, data_dir) - _print_json(_status_payload(result, catalog)) - return 0 - - if args.command == "apply": - proposed = _load_updates(args) - updates = _validated_updates( - catalog, - result.assessment, - proposed, - section=args.section, - review_response=args.review_response, - ) - assessment = store.update_assessment( - result.resolution.identifier, - updates, - ) - updated_fields = set(updates) - conflicts = result.conflicts - if result.resolution.registered: - assessment, local_conflicts = handoff_local_assessment( - store, result.resolution, resolved_fields=updated_fields, - ) - conflicts = tuple( - item for item in conflicts if item.source != "local_draft" - ) + local_conflicts - result = SyncResult( - resolution=result.resolution, - assessment=assessment, - conflicts=tuple( - item - for item in conflicts - if item.source == "local_draft" or item.field not in updated_fields - ), - repository_file=result.repository_file, - public_loaded=result.public_loaded, - public_document=result.public_document, - public_fetched_at=result.public_fetched_at, - ) - _refresh_open_boards(store, result, catalog, data_dir) - payload = _status_payload(result, catalog) - payload["style_warnings"] = _style_warnings(updates) - _print_json(payload) - return 0 - - conflict_records = [_conflict_record(item) for item in result.conflicts] - - if args.command == "review": - url = _open_review( - result, - catalog, - data_dir, - args.section, - browser_open, - view=args.view, - no_browser=args.no_browser, - ) - _print_json( - { - "schema_version": 1, - "state": "review_written", - "conflicts": conflict_records, - "project_id": result.resolution.project_id, - "section": args.section, - "url": url, - } - ) - return 0 - - if args.command in {"export", "fill-script"}: - output = args.output.expanduser().resolve(strict=False) - private_root = data_dir.expanduser().resolve(strict=False) - if output == private_root or private_root in output.parents: - raise CommandError( - f"{args.command} output must be outside CLAUDE_PLUGIN_DATA" - ) - - if args.command == "export": - assert output is not None - _refresh_open_boards(store, result, catalog, data_dir) - write_assessment_file(output, result.assessment) - _print_json( - { - "schema_version": 1, - "state": "assessment_exported", - "conflicts": conflict_records, - "output": str(output), - "project_id": result.resolution.project_id, - } - ) - return 0 - if args.command == "propose": - if result.resolution.project_id is None: - raise CommandError( - "propose requires a registered bestpractices.dev project; " - "register the project or pass --project-id" - ) - try: - base_url = validate_base_url( - STAGING_BASE_URL if args.staging else args.base_url - ) - except ValueError as error: - raise CommandError(str(error)) from error - plan = build_proposal_urls( - result.assessment, - catalog, - section=args.section, - project_id=result.resolution.project_id, - base_url=base_url, - overrides=args.overrides, - reanalyze=args.reanalyze, - max_url_bytes=args.max_url_bytes, - public_document=result.public_document, - ) - notes = [ - "Proposals are one-shot: nothing is stored until the " - "form is saved. Review the highlighted fields, then save or " - "explicitly ask the assistant to click Save." - ] - if args.overrides: - notes.append( - "The site decides which overrides match. To replace existing wording, " - "match its justification field or paired status field; an emitted " - "URL does not confirm that the site will apply every field." - ) - if len(plan.urls) > 1: - notes.append( - "Multiple URLs: open URL 1, review, click 'Save (and " - "continue)', then open the next URL; unsaved proposals " - "are lost." - ) - if plan.dropped_justification_only: - notes.append( - "Existing wording is preserved by default when the status matches. " - "Use fill-script for these edits, or --overrides with the site's " - "field-matching rules and review the result." - ) - if plan.oversize: - notes.append( - "Some justifications exceed --max-url-bytes even in a " - "URL of their own and were not emitted; shorten the " - "wording, or send them via fill-script --criteria." - ) - if args.open_first and plan.urls: - _assert_badge_site_url(plan.urls[0]) - browser_open(plan.urls[0]) - _print_json( - { - "schema_version": 1, - "state": "proposals_ready", - "public_snapshot": _public_snapshot_metadata(result), - "conflicts": conflict_records, - "section": args.section, - "project_id": result.resolution.project_id, - "urls": list(plan.urls), - "proposed": list(plan.proposed), - "skipped_unknown": list(plan.skipped_unknown), - "dropped_no_op": list(plan.dropped_no_op), - "dropped_justification_only": list( - plan.dropped_justification_only - ), - "oversize": list(plan.oversize), - "notes": notes, - } - ) - return 0 - if args.command == "fill-script": - assert output is not None - selected: list[str] | None - if args.criteria: - requested = [ - item.strip() for item in args.criteria.split(",") if item.strip() - ] - if not requested: - raise CommandError("--criteria was supplied without ids") - selected = [] - for raw_id in requested: - try: - criterion = catalog.get(raw_id, args.section) - except KeyError as error: - raise CommandError( - f"--criteria: {error.args[0]}" - ) from error - selected.append(criterion.id) - scope_mode = "criteria" - elif args.all_fields: - selected = None - scope_mode = "all" - else: - # Changed-only needs a saved comparison; never silently widen it. - if not result.public_document: - raise CommandError( - "no public snapshot is available, so --changed-only cannot compute the " - "wording-only set; run status online, or pass --criteria or --all to " - "choose fields explicitly" - ) - selected = list( - wording_only_criteria( - result.assessment, - catalog, - section=args.section, - public_document=result.public_document, - ) - ) - scope_mode = "changed-only" - if not selected: - _print_json( - { - "schema_version": 1, - "state": "fill_script_not_needed", - "public_snapshot": _public_snapshot_metadata(result), - "conflicts": conflict_records, - "section": args.section, - "scope": scope_mode, - "criteria": [], - "notes": [ - "No wording-only changes relative to the saved public " - "snapshot; status changes may still need a proposal." - ], - } - ) - return 0 - script, filled = build_fill_script( - result.assessment, - catalog, - section=args.section, - criteria=selected, - ) - output.parent.mkdir(parents=True, exist_ok=True) - output.write_text(script, encoding="utf-8") - _print_json( - { - "schema_version": 1, - "state": "fill_script_written", - "public_snapshot": _public_snapshot_metadata(result), - "conflicts": conflict_records, - "section": args.section, - "scope": scope_mode, - "output": str(output), - "criteria": list(filled), - "notes": [ - "Paste the script into the browser console on the " - "project's EDIT page for this section; it fills the " - "form fields and never saves. The user can save, or " - "explicitly ask the assistant to click Save." - ], - } - ) - return 0 - raise AssertionError(f"unhandled command: {args.command}") - except (CommandError, ProjectResolutionError, OSError, ValueError) as error: - print(f"error: {error}", file=sys.stderr) - return 2 - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/plugins/badge-buddy/scripts/ossf_review/__init__.py b/plugins/badge-buddy/scripts/ossf_review/__init__.py index 9a0fd50..4491d02 100644 --- a/plugins/badge-buddy/scripts/ossf_review/__init__.py +++ b/plugins/badge-buddy/scripts/ossf_review/__init__.py @@ -1,5 +1 @@ -"""Assessment storage and read-only presentation for the OpenSSF badge skill.""" - -from .storage import DataStore, normalize_github_remote - -__all__ = ["DataStore", "normalize_github_remote"] +"""Offline assessment presentation and shared Scorecard utilities.""" diff --git a/plugins/badge-buddy/scripts/ossf_review/remotes.py b/plugins/badge-buddy/scripts/ossf_review/remotes.py new file mode 100644 index 0000000..6e86af0 --- /dev/null +++ b/plugins/badge-buddy/scripts/ossf_review/remotes.py @@ -0,0 +1,65 @@ +"""Normalize GitHub repository identifiers for the Scorecard helper.""" + +import re +from urllib.parse import urlsplit + +_SCP_REMOTE = re.compile( + r"^(?:git@)?github\.com:(?P[^?#]+)$", flags=re.IGNORECASE +) + + +def normalize_github_remote(remote: str) -> str: + """Return a lowercase ``github.com/owner/repo`` comparison and registry key. + + This is not GitHub's repository ID or the repository's display name. + Use ``github_repository_url`` when the owner/repository spelling matters. + """ + + return github_repository_url(remote).removeprefix("https://").lower() + + +def github_repository_url(remote: str) -> str: + """Convert a supported GitHub remote to HTTPS, preserving owner/repo case.""" + + if not isinstance(remote, str): + raise TypeError("GitHub remote must be a string") + + value = remote.strip() + if not value: + raise ValueError("GitHub remote must not be empty") + + repository_path = _github_remote_path(value).strip().strip("/") + if repository_path.lower().endswith(".git"): + repository_path = repository_path[:-4] + repository_path = repository_path.rstrip("/") + + parts = repository_path.split("/") + if ( + len(parts) != 2 + or not all(parts) + or any(part in {".", ".."} for part in parts) + or any(character.isspace() for character in repository_path) + ): + raise ValueError("GitHub remote must identify exactly one owner/repository") + + owner, repository = parts + return f"https://github.com/{owner}/{repository}" + + +def _github_remote_path(value: str) -> str: + match = _SCP_REMOTE.fullmatch(value) + if match: + return match.group("path") + if "://" in value: + parsed = urlsplit(value) + if parsed.scheme.lower() not in {"http", "https", "ssh", "git"}: + raise ValueError(f"unsupported GitHub remote scheme: {parsed.scheme!r}") + if (parsed.hostname or "").lower() != "github.com": + raise ValueError("remote host must be github.com") + if parsed.query or parsed.fragment: + raise ValueError("GitHub remote must not contain a query or fragment") + return parsed.path + prefix = "github.com/" + if not value.lower().startswith(prefix): + raise ValueError("remote must be an HTTP(S), SSH, git@, or github.com remote") + return value[len(prefix) :] diff --git a/plugins/badge-buddy/scripts/ossf_review/storage.py b/plugins/badge-buddy/scripts/ossf_review/storage.py deleted file mode 100644 index 7d7b2d9..0000000 --- a/plugins/badge-buddy/scripts/ossf_review/storage.py +++ /dev/null @@ -1,531 +0,0 @@ -"""Small, durable JSON store for OpenSSF badge assessments.""" - -from __future__ import annotations - -from collections.abc import Mapping -from contextlib import contextmanager -from datetime import datetime, timezone -import copy -import json -import os -from pathlib import Path -import re -import stat -import tempfile -import threading -from typing import Any, Callable, Iterator -from urllib.parse import urlsplit - -from .fields import normalize_assessment_fields - -try: # ``fcntl`` supplies cross-process locking on supported POSIX hosts. - import fcntl -except ImportError: # pragma: no cover - exercised only on non-POSIX hosts. - fcntl = None # type: ignore[assignment] - - -SCHEMA_VERSION = 1 -REGISTRY_FILENAME = "registry.json" -ASSESSMENT_FILENAME = ".bestpractices.json" -UNREGISTERED_PREFIX = "unregistered:" - -_SCP_REMOTE = re.compile( - r"^(?:git@)?github\.com:(?P[^?#]+)$", - flags=re.IGNORECASE, -) -_THREAD_LOCKS: dict[str, threading.RLock] = {} -_THREAD_LOCKS_GUARD = threading.Lock() -_SAFE_KEY_CHARACTER = re.compile(r"[^a-z0-9._-]+") -_SAFE_KEY = re.compile(r"^[a-z0-9][a-z0-9._-]*$") - - -def normalize_github_remote(remote: str) -> str: - """Return a lowercase ``github.com/owner/repo`` comparison and registry key. - - This is not GitHub's repository ID or the repository's display name. - Use ``github_repository_url`` when the owner/repository spelling matters. - """ - - return github_repository_url(remote).removeprefix("https://").lower() - - -def github_repository_url(remote: str) -> str: - """Convert a supported GitHub remote to HTTPS, preserving owner/repo case.""" - - if not isinstance(remote, str): - raise TypeError("GitHub remote must be a string") - - value = remote.strip() - if not value: - raise ValueError("GitHub remote must not be empty") - - repository_path = _github_remote_path(value).strip().strip("/") - if repository_path.lower().endswith(".git"): - repository_path = repository_path[:-4] - repository_path = repository_path.rstrip("/") - - parts = repository_path.split("/") - if ( - len(parts) != 2 - or not all(parts) - or any(part in {".", ".."} for part in parts) - or any(character.isspace() for character in repository_path) - ): - raise ValueError("GitHub remote must identify exactly one owner/repository") - - owner, repository = parts - return f"https://github.com/{owner}/{repository}" - - -def _github_remote_path(value: str) -> str: - match = _SCP_REMOTE.fullmatch(value) - if match: - return match.group("path") - if "://" in value: - parsed = urlsplit(value) - if parsed.scheme.lower() not in {"http", "https", "ssh", "git"}: - raise ValueError(f"unsupported GitHub remote scheme: {parsed.scheme!r}") - if (parsed.hostname or "").lower() != "github.com": - raise ValueError("remote host must be github.com") - if parsed.query or parsed.fragment: - raise ValueError("GitHub remote must not contain a query or fragment") - return parsed.path - prefix = "github.com/" - if not value.lower().startswith(prefix): - raise ValueError("remote must be an HTTP(S), SSH, git@, or github.com remote") - return value[len(prefix) :] - - -def _thread_lock(path: Path) -> threading.RLock: - key = str(path.absolute()) - with _THREAD_LOCKS_GUARD: - return _THREAD_LOCKS.setdefault(key, threading.RLock()) - - -@contextmanager -def _exclusive_lock(path: Path) -> Iterator[None]: - """Serialize read-modify-write operations across threads and processes.""" - - lock = _thread_lock(path) - with lock: - path.parent.mkdir(parents=True, exist_ok=True) - with path.open("a+b") as lock_file: - if fcntl is not None: - fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX) - try: - yield - finally: - if fcntl is not None: - fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN) - - -def _atomic_write_json(path: Path, value: Mapping[str, Any]) -> None: - """Write a JSON object using a same-directory atomic replacement.""" - - serialized = ( - json.dumps( - value, - ensure_ascii=False, - indent=2, - sort_keys=True, - ) - + "\n" - ) - path.parent.mkdir(parents=True, exist_ok=True) - descriptor, temporary_name = tempfile.mkstemp( - dir=path.parent, - prefix=f".{path.name}.", - suffix=".tmp", - ) - temporary_path = Path(temporary_name) - try: - if path.exists(): - os.fchmod(descriptor, stat.S_IMODE(path.stat().st_mode)) - with os.fdopen(descriptor, "w", encoding="utf-8") as temporary_file: - temporary_file.write(serialized) - temporary_file.flush() - os.fsync(temporary_file.fileno()) - os.replace(temporary_path, path) - except BaseException: - temporary_path.unlink(missing_ok=True) - raise - - -def _load_json_object(path: Path) -> dict[str, Any]: - try: - value = json.loads(path.read_text(encoding="utf-8")) - except json.JSONDecodeError as error: - raise ValueError(f"invalid JSON in {path}: {error}") from error - if not isinstance(value, dict): - raise ValueError(f"expected a JSON object in {path}") - return value - - -def normalize_project_id(value: int | str) -> str: - """Validate and normalize a numeric badge ID without changing storage.""" - - if isinstance(value, bool): - raise ValueError("project id must be numeric") - text = str(value).strip() - if not text.isdecimal(): - raise ValueError("project id must be numeric") - return str(int(text)) - - -def _load_assessment(path: Path) -> dict[str, Any]: - return normalize_assessment_fields(_load_json_object(path)) - - -def _safe_local_key(local_directory: str) -> str: - basename = Path(local_directory).name.lower() - key = _SAFE_KEY_CHARACTER.sub("-", basename).strip("-._") - return key or "project" - - -def _unregistered_key(value: str) -> str | None: - if not value.startswith(UNREGISTERED_PREFIX): - return None - key = value.removeprefix(UNREGISTERED_PREFIX) - if not key or not _SAFE_KEY.fullmatch(key): - raise ValueError("invalid unregistered project identifier") - return key - - -def _merge_objects(current: dict[str, Any], updates: Mapping[str, Any]) -> None: - for key, new_value in updates.items(): - old_value = current.get(key) - if isinstance(old_value, dict) and isinstance(new_value, Mapping): - _merge_objects(old_value, new_value) - else: - current[key] = copy.deepcopy(new_value) - - -def answer_groups(document: Mapping[str, Any]) -> dict[tuple[str, str], dict[str, Any]]: - groups: dict[tuple[str, str], dict[str, Any]] = {} - for field, value in document.items(): - if field.endswith(("_status", "_justification")): - key = ("criterion", field.rpartition("_")[0]) - else: - key = ("metadata", field) - groups.setdefault(key, {})[field] = value - return groups - - -def _merge_local_draft( - current: dict[str, Any], draft: Mapping[str, Any], resolved_fields: set[str], -) -> tuple[dict[str, Any], dict[str, tuple[Any, Any]]]: - """Keep conflicting answer pairs together until explicitly resolved.""" - existing_groups = answer_groups(current) - pending: dict[str, Any] = {} - conflicts: dict[str, tuple[Any, Any]] = {} - for key, answer in answer_groups(draft).items(): - existing = existing_groups.get(key, {}) - differences = { - field: (existing.get(field), value) - for field, value in answer.items() - if field not in existing or existing[field] != value - } - if differences.keys() <= resolved_fields: - continue - if existing.keys() & differences.keys(): - pending.update(answer) - conflicts.update(differences) - else: - current.update(answer) - return pending, conflicts - - -class DataStore: - """Persistent registry and canonical assessment storage. - - A single lock serializes registry and assessment read-modify-write cycles. - Atomic replacement prevents readers from observing partially written JSON; - locking additionally prevents concurrent unrelated updates from being lost. - """ - - def __init__(self, data_dir: str | os.PathLike[str]) -> None: - self.data_dir = Path(data_dir).expanduser().resolve(strict=False) - self.registry_path = self.data_dir / REGISTRY_FILENAME - self.projects_dir = self.data_dir / "projects" - self._lock_path = self.data_dir / ".storage.lock" - self.assessment_file: Path | None = None - - self.data_dir.mkdir(parents=True, exist_ok=True) - with _exclusive_lock(self._lock_path): - if not self.registry_path.exists(): - _atomic_write_json(self.registry_path, self._empty_registry()) - else: - self._read_registry_unlocked() - - @staticmethod - def _empty_registry() -> dict[str, Any]: - return { - "schema_version": SCHEMA_VERSION, - "by_id": {}, - "by_remote": {}, - "unregistered": {}, - } - - def _read_registry_unlocked(self) -> dict[str, Any]: - registry = _load_json_object(self.registry_path) - if registry.get("schema_version") != SCHEMA_VERSION: - raise ValueError( - f"unsupported registry schema_version: " - f"{registry.get('schema_version')!r}" - ) - for key in ("by_id", "by_remote", "unregistered"): - if not isinstance(registry.get(key), dict): - raise ValueError(f"registry field {key!r} must be an object") - return registry - - def use_assessment_file(self, path: str | os.PathLike[str]) -> None: - """Use this existing working file for this invocation's assessment operations.""" - selected = Path(path).expanduser().resolve(strict=True) - _load_assessment(selected) - self.assessment_file = selected - - def _assessment_path(self, project_id: int | str) -> Path: - if self.assessment_file is not None: - return self.assessment_file - if isinstance(project_id, str): - key = _unregistered_key(project_id) - if key is not None: - return self.data_dir / "unregistered" / key / ASSESSMENT_FILENAME - return self.projects_dir / normalize_project_id(project_id) / ASSESSMENT_FILENAME - - def save_public_snapshot( - self, project_id: int | str, remote: str, document: Mapping[str, Any], - ) -> dict[str, Any]: - """Save website data separately from the selected working assessment.""" - identifier = normalize_project_id(project_id) - snapshot = { - "project_id": identifier, - "remote": normalize_github_remote(remote), - "fetched_at": datetime.now(timezone.utc).isoformat(), - "document": dict(document), - } - path = self.projects_dir / identifier / "public.json" - with _exclusive_lock(self._lock_path): - _atomic_write_json(path, snapshot) - return snapshot - - def load_public_snapshot( - self, project_id: int | str, remote: str, - ) -> dict[str, Any] | None: - """Read the last successful fetch, only for the same project and origin.""" - identifier = normalize_project_id(project_id) - path = self.projects_dir / identifier / "public.json" - with _exclusive_lock(self._lock_path): - if not path.exists(): - return None - snapshot = _load_json_object(path) - if ( - snapshot.get("project_id") != identifier - or snapshot.get("remote") != normalize_github_remote(remote) - ): - return None - if not isinstance(snapshot.get("document"), dict) or not isinstance( - snapshot.get("fetched_at"), str - ): - raise ValueError("invalid public snapshot; run status to refresh it") - return snapshot - - def register_project(self, project_id: int | str, remote: str) -> str: - """Register or update a bijective numeric-id-to-remote mapping.""" - - identifier = normalize_project_id(project_id) - normalized_remote = normalize_github_remote(remote) - with _exclusive_lock(self._lock_path): - registry = self._read_registry_unlocked() - - previous_remote = registry["by_id"].get(identifier) - if previous_remote and previous_remote != normalized_remote: - registry["by_remote"].pop(previous_remote, None) - - previous_identifier = registry["by_remote"].get(normalized_remote) - if previous_identifier and previous_identifier != identifier: - registry["by_id"].pop(previous_identifier, None) - - registry["by_id"][identifier] = normalized_remote - registry["by_remote"][normalized_remote] = identifier - _atomic_write_json(self.registry_path, registry) - - assessment_path = self._assessment_path(identifier) - if not assessment_path.exists(): - _atomic_write_json(assessment_path, {}) - return identifier - - def resolve_project_id(self, remote: str) -> str | None: - """Resolve any supported GitHub remote spelling to a registered id.""" - - normalized_remote = normalize_github_remote(remote) - with _exclusive_lock(self._lock_path): - registry = self._read_registry_unlocked() - identifier = registry["by_remote"].get(normalized_remote) - return str(identifier) if identifier is not None else None - - def load_assessment(self, project_id: int | str) -> dict[str, Any]: - """Load a registered project's canonical assessment object.""" - - path = self._assessment_path(project_id) - with _exclusive_lock(self._lock_path): - if not path.exists(): - return {} - return _load_assessment(path) - - def save_assessment( - self, - project_id: int | str, - assessment: Mapping[str, Any], - ) -> None: - """Replace a project's canonical assessment atomically.""" - - if not isinstance(assessment, Mapping): - raise TypeError("assessment must be a mapping") - path = self._assessment_path(project_id) - with _exclusive_lock(self._lock_path): - _atomic_write_json(path, copy.deepcopy(normalize_assessment_fields(assessment))) - - def update_assessment( - self, - project_id: int | str, - updates: Mapping[str, Any], - ) -> dict[str, Any]: - """Merge criterion updates without losing concurrent unrelated fields.""" - - if not isinstance(updates, Mapping): - raise TypeError("updates must be a mapping") - path = self._assessment_path(project_id) - with _exclusive_lock(self._lock_path): - current = _load_assessment(path) if path.exists() else {} - _merge_objects(current, normalize_assessment_fields(updates)) - _atomic_write_json(path, current) - return copy.deepcopy(current) - - def transform_assessment( - self, - project_id: int | str, - transform: Callable[[dict[str, Any]], Mapping[str, Any]], - ) -> dict[str, Any]: - """Atomically transform the latest assessment under the store lock.""" - - if not callable(transform): - raise TypeError("transform must be callable") - path = self._assessment_path(project_id) - with _exclusive_lock(self._lock_path): - current = _load_assessment(path) if path.exists() else {} - transformed = transform(copy.deepcopy(current)) - if not isinstance(transformed, Mapping): - raise TypeError("assessment transform must return a mapping") - result = copy.deepcopy(normalize_assessment_fields(transformed)) - _atomic_write_json(path, result) - return copy.deepcopy(result) - - def create_unregistered( - self, - local_project_directory: str | os.PathLike[str], - remote: str | None = None, - project_name: str | None = None, - ) -> dict[str, str | None]: - """Create or replace a minimal record for a project with no badge id.""" - - local_directory = str( - Path(local_project_directory).expanduser().resolve(strict=False) - ) - with _exclusive_lock(self._lock_path): - registry = self._read_registry_unlocked() - existing = registry["unregistered"].get(local_directory) - if isinstance(existing, Mapping) and isinstance( - existing.get("storage_key"), str - ): - storage_key = existing["storage_key"] - else: - base_key = _safe_local_key(local_directory) - occupied = { - item.get("storage_key") - for item in registry["unregistered"].values() - if isinstance(item, Mapping) - } - storage_key = base_key - counter = 2 - while storage_key in occupied: - storage_key = f"{base_key}-{counter}" - counter += 1 - - record: dict[str, str | None] = { - "local_project_directory": local_directory, - "remote": normalize_github_remote(remote) if remote else None, - "project_name": project_name or Path(local_directory).name, - "storage_key": storage_key, - } - registry["unregistered"][local_directory] = record - _atomic_write_json(self.registry_path, registry) - assessment_path = self._assessment_path(f"{UNREGISTERED_PREFIX}{storage_key}") - if not assessment_path.exists(): - _atomic_write_json(assessment_path, {}) - return copy.deepcopy(record) - - def load_unregistered( - self, - local_project_directory: str | os.PathLike[str], - ) -> dict[str, str | None] | None: - """Load a minimal unregistered-project record by local directory.""" - - local_directory = str( - Path(local_project_directory).expanduser().resolve(strict=False) - ) - with _exclusive_lock(self._lock_path): - registry = self._read_registry_unlocked() - record = registry["unregistered"].get(local_directory) - return copy.deepcopy(record) if record is not None else None - - def handoff_unregistered( - self, - local_project_directory: str | os.PathLike[str], - project_id: int | str, - *, - resolved_fields: set[str] | None = None, - ) -> tuple[dict[str, Any], dict[str, tuple[Any, Any]]]: - """Transfer a local draft; retain disagreements for an explicit apply. - - Acknowledgements must follow a successful write of those fields. Write - the destination before pruning the draft so interrupted handoffs can retry. - """ - if self.assessment_file is not None: - return self.load_assessment(project_id), {} - local_directory = str(Path(local_project_directory).expanduser().resolve()) - identifier = normalize_project_id(project_id) - with _exclusive_lock(self._lock_path): - registry = self._read_registry_unlocked() - destination = self._assessment_path(identifier) - current = _load_assessment(destination) if destination.exists() else {} - record = registry["unregistered"].get(local_directory) - if record is None: - return current, {} - if record.get("remote") != registry["by_id"].get(identifier): - raise ValueError("local assessment remote does not match the registered project") - source = self._assessment_path(f"{UNREGISTERED_PREFIX}{record['storage_key']}") - draft = _load_assessment(source) if source.exists() else {} - pending, conflicts = _merge_local_draft(current, draft, resolved_fields or set()) - _atomic_write_json(destination, current) - if pending: - _atomic_write_json(source, pending) - else: - source.unlink(missing_ok=True) - del registry["unregistered"][local_directory] - _atomic_write_json(self.registry_path, registry) - return current, conflicts - - def unregistered_identifier( - self, - local_project_directory: str | os.PathLike[str], - ) -> str | None: - """Return the server/storage identifier for an unregistered record.""" - - record = self.load_unregistered(local_project_directory) - if record is None: - return None - storage_key = record.get("storage_key") - if not isinstance(storage_key, str) or not _SAFE_KEY.fullmatch(storage_key): - raise ValueError("unregistered record has an invalid storage_key") - return f"{UNREGISTERED_PREFIX}{storage_key}" diff --git a/plugins/badge-buddy/scripts/ossf_review/submission.py b/plugins/badge-buddy/scripts/ossf_review/submission.py deleted file mode 100644 index b81ba00..0000000 --- a/plugins/badge-buddy/scripts/ossf_review/submission.py +++ /dev/null @@ -1,325 +0,0 @@ -"""Build human-review submission artifacts from the canonical assessment. - -Both builders encode the BadgeApp automation semantics distilled in -the ossf-bp-badges skill's ``references/application.md``: proposal URLs are upstream's -primary automation path (one-shot, section-isolated; the logged-in human reviews the -highlighted proposals and saves). Proposal URLs can fill blank justifications -or replace existing wording with matching overrides. The console fill script -offers another way to transfer wording changes or answers too long for a URL. - -Neither artifact writes to bestpractices.dev. A proposal URL renders -highlights in the edit form until the human saves; the fill script fills form -fields in the user's own browser session and never submits. -""" - -from __future__ import annotations - -from collections.abc import Mapping, Sequence -from dataclasses import dataclass -import json -from typing import Any -from urllib.parse import urlencode - -from .criteria import CriteriaCatalog, Criterion - - -PRODUCTION_BASE_URL = "https://www.bestpractices.dev" -STAGING_BASE_URL = "https://staging.bestpractices.dev" -# Proposal URLs carry criterion justifications in their query string and may -# be opened in the user's browser, so their origin is restricted to the sites -# the badge authority operates. Nothing else is accepted, at any layer. -ALLOWED_BASE_URLS: tuple[str, ...] = (PRODUCTION_BASE_URL, STAGING_BASE_URL) -# Upstream documents no URL length limit, but real hosting/CDN stacks reject -# request lines around 8 KB, and a URL near that size failed in field use. -# 6,000 bytes leaves headroom for the request line and proxy quirks. -DEFAULT_MAX_URL_BYTES = 6000 -# Upstream silently ignores an overrides parameter beyond these caps. -OVERRIDES_MAX_CHARS = 10_000 -OVERRIDES_MAX_PATTERNS = 1_000 - -_PROPOSABLE_STATUSES = frozenset({"Met", "Unmet", "N/A"}) - - -@dataclass(frozen=True, slots=True) -class ProposalPlan: - """Proposal URLs plus an account of every answer that was not proposed.""" - - urls: tuple[str, ...] - proposed: tuple[str, ...] - skipped_unknown: tuple[str, ...] - dropped_no_op: tuple[str, ...] - dropped_justification_only: tuple[str, ...] - oversize: tuple[str, ...] = () - - -def _justification_text(value: Any) -> str: - """Preserve Markdown-significant whitespace in comparisons and submissions.""" - - return value if isinstance(value, str) else "" - - -def _section_answers( - assessment: Mapping[str, Any], - catalog: CriteriaCatalog, - section: str, -) -> list[tuple[Criterion, dict[str, Any]]]: - answers = catalog.classify_flat(assessment)[section] - return [ - (criterion, answers[criterion.id]) - for criterion in catalog.section(section) - if criterion.id in answers - ] - - -def _live_value( - public_document: Mapping[str, Any], - criterion: Criterion, - suffix: str, -) -> Any: - """Read a live field tolerating the baseline display-id readback form.""" - - for key in (f"{criterion.id}_{suffix}", f"{criterion.display_id}_{suffix}"): - if key in public_document: - return public_document[key] - return None - - -def wording_only_criteria( - assessment: Mapping[str, Any], - catalog: CriteriaCatalog, - *, - section: str, - public_document: Mapping[str, Any], -) -> tuple[str, ...]: - """Criteria whose live status matches but whose wording differs. - - This is the fill script's default scope. Proposal URLs can also carry - these changes, with matching overrides when replacing existing wording. - The badge site's own detectives commonly produce these entries: - matching statuses with thin justifications that omit evidence URLs. - """ - - answers = catalog.classify_flat(assessment)[section] - selected: list[str] = [] - for criterion in catalog.section(section): - answer = answers.get(criterion.id, {}) - status = answer.get("status") - if not isinstance(status, str) or status not in _PROPOSABLE_STATUSES: - continue - live_status = _live_value(public_document, criterion, "status") - if not (isinstance(live_status, str) and live_status.strip() == status): - continue - justification = _justification_text(answer.get("justification")) - live_justification = _justification_text( - _live_value(public_document, criterion, "justification") - ) - if "justification" in answer and justification != live_justification: - selected.append(criterion.id) - return tuple(selected) - - -def validate_overrides(overrides: str) -> None: - """Reject overrides values upstream would silently ignore.""" - - if len(overrides) > OVERRIDES_MAX_CHARS: - raise ValueError( - "overrides exceeds upstream's 10,000-character cap and would be " - "silently ignored" - ) - if overrides.count(",") + 1 > OVERRIDES_MAX_PATTERNS: - raise ValueError( - "overrides exceeds upstream's 1,000-pattern cap and would be " - "silently ignored" - ) - - -def validate_base_url(value: str) -> str: - """Return the normalized badge-site base URL, or raise ``ValueError``. - - Only the production and staging badge sites are accepted; a trailing - slash is tolerated, any other scheme, host, path, or port is not. - """ - - candidate = value.strip().rstrip("/") - if candidate in ALLOWED_BASE_URLS: - return candidate - raise ValueError( - "base URL must be one of " - + ", ".join(ALLOWED_BASE_URLS) - + f"; got {value!r}" - ) - - -def build_proposal_urls( - assessment: Mapping[str, Any], - catalog: CriteriaCatalog, - *, - section: str, - project_id: str, - base_url: str = PRODUCTION_BASE_URL, - overrides: str | None = None, - reanalyze: bool = False, - max_url_bytes: int = DEFAULT_MAX_URL_BYTES, - public_document: Mapping[str, Any] | None = None, -) -> ProposalPlan: - """Build official automation-proposal URL(s) for one section. - - ``?`` and missing statuses are never emitted. The checked upstream - controller ignores unknown URL statuses, despite older documentation - describing them as resets. - - When the public document is available, unchanged answers are omitted. - Wording-only changes can fill blank text; replacing existing text needs - an override. Without overrides those changes are reported separately. - Supplied override patterns are passed through for the site to match; - inclusion in ``proposed`` means encoded in a URL, not applied by the site. - """ - - if not project_id: - raise ValueError("project_id is required") - if overrides: - validate_overrides(overrides) - - base = validate_base_url(base_url) - prefix = f"{base}/en/projects/{int(project_id)}/{section}/edit?" - - common: list[tuple[str, str]] = [] - if overrides: - common.append(("overrides", overrides)) - if reanalyze: - common.append(("reanalyze", "1")) - - proposed: list[str] = [] - skipped_unknown: list[str] = [] - dropped_no_op: list[str] = [] - dropped_justification_only: list[str] = [] - oversize: list[str] = [] - live = public_document or {} - # Each entry keeps one criterion's status and justification together: - # upstream couples the pair, so chunking must never split them. - criterion_pairs: list[tuple[str, list[tuple[str, str]]]] = [] - - answers = catalog.classify_flat(assessment)[section] - for criterion in catalog.section(section): - answer = answers.get(criterion.id, {}) - status = answer.get("status") - if not isinstance(status, str) or status not in _PROPOSABLE_STATUSES: - skipped_unknown.append(criterion.id) - continue - justification = _justification_text(answer.get("justification")) - - live_status = _live_value(live, criterion, "status") - if isinstance(live_status, str) and live_status.strip() == status: - live_justification = _justification_text( - _live_value(live, criterion, "justification") - ) - if "justification" not in answer or justification == live_justification: - dropped_no_op.append(criterion.id) - continue - if live_justification.strip() and not overrides: - dropped_justification_only.append(criterion.id) - continue - - pairs = [(f"{criterion.id}_status", status)] - if "justification" in answer: - pairs.append((f"{criterion.id}_justification", justification)) - criterion_pairs.append((criterion.id, pairs)) - - urls: list[str] = [] - batch: list[tuple[str, str]] = [] - - def flush() -> None: - if batch: - urls.append(prefix + urlencode(common + batch)) - batch.clear() - - for criterion_id, pairs in criterion_pairs: - alone = prefix + urlencode(common + pairs) - if len(alone.encode("utf-8")) > max_url_bytes: - # Never emit an oversize URL: the coupled pair cannot be split, - # so the justification must shrink or travel by fill script. - oversize.append(criterion_id) - continue - candidate = prefix + urlencode(common + batch + pairs) - if batch and len(candidate.encode("utf-8")) > max_url_bytes: - flush() - batch.extend(pairs) - proposed.append(criterion_id) - flush() - - return ProposalPlan( - urls=tuple(urls), - proposed=tuple(proposed), - skipped_unknown=tuple(skipped_unknown), - dropped_no_op=tuple(dropped_no_op), - dropped_justification_only=tuple(dropped_justification_only), - oversize=tuple(oversize), - ) - - -def build_fill_script( - assessment: Mapping[str, Any], - catalog: CriteriaCatalog, - *, - section: str, - criteria: Sequence[str] | None = None, -) -> tuple[str, tuple[str, ...]]: - """Emit a console script that fills the edit form without saving it. - - The script targets the project EDIT page for *section*, sets each status - radio and justification textarea, dispatches change/input events so the - live percentage updates, and returns a JSON report - ``{filled, missingStatus, missingJustification}``. Saving remains a - deliberate, human action; the script has no submit behavior. - - When *criteria* is given, only those criterion ids are emitted; the - write's blast radius is exactly the requested subset. ``None`` means - every answered criterion in the section. - """ - - selected = None if criteria is None else set(criteria) - answers: dict[str, dict[str, str]] = {} - for criterion, answer in _section_answers(assessment, catalog, section): - if selected is not None and criterion.id not in selected: - continue - status = answer.get("status") - if not isinstance(status, str) or status not in _PROPOSABLE_STATUSES: - continue - answers[criterion.id] = {"status": status} - if "justification" in answer: - answers[criterion.id]["justification"] = _justification_text( - answer["justification"] - ) - - payload = json.dumps(answers, indent=2, ensure_ascii=False, sort_keys=True) - script = ( - "(() => {\n" - f" const answers = {payload};\n" - " const report = { filled: [], missingStatus: []," - " missingJustification: [] };\n" - " const fire = (el, type) =>" - " el.dispatchEvent(new Event(type, { bubbles: true }));\n" - " for (const [cid, a] of Object.entries(answers)) {\n" - " const radios = document.querySelectorAll(\n" - " `input[type=radio][name=\"project[${cid}_status]\"]`);\n" - " let hit = false;\n" - " for (const r of radios) {\n" - " if (r.value === a.status ||\n" - " r.value.toLowerCase() === a.status.toLowerCase()) {\n" - " r.checked = true; fire(r, 'click'); fire(r, 'change');" - " hit = true;\n" - " }\n" - " }\n" - " if (hit) report.filled.push(cid);\n" - " else report.missingStatus.push(`${cid}=${a.status}`);\n" - " if (!Object.hasOwn(a, 'justification')) continue;\n" - " const ta = document.querySelector(\n" - " `textarea[name=\"project[${cid}_justification]\"]`);\n" - " if (ta) { ta.value = a.justification; fire(ta, 'input');" - " fire(ta, 'change'); }\n" - " else report.missingJustification.push(cid);\n" - " }\n" - " return report;\n" - "})()\n" - ) - return script, tuple(sorted(answers)) diff --git a/plugins/badge-buddy/scripts/ossf_review/sync.py b/plugins/badge-buddy/scripts/ossf_review/sync.py deleted file mode 100644 index 98dd8ba..0000000 --- a/plugins/badge-buddy/scripts/ossf_review/sync.py +++ /dev/null @@ -1,529 +0,0 @@ -"""Resolve projects and synchronize read-only OpenSSF assessment sources.""" - -from __future__ import annotations - -from collections.abc import Callable, Iterator, Mapping -from dataclasses import dataclass, field -import json -import os -from pathlib import Path -import stat -import subprocess -import tempfile -import time -from typing import Any -from urllib.error import HTTPError, URLError -from urllib.parse import urlencode -from urllib.request import Request, urlopen - -from .fields import normalize_assessment_fields - -from .storage import ( - DataStore, answer_groups, github_repository_url, normalize_github_remote, normalize_project_id, -) - - -DEFAULT_BASE_URL = "https://www.bestpractices.dev" -DEFAULT_USER_AGENT = "badge-buddy/1 (+https://github.com/reponomics/plugins)" -MAX_RESPONSE_BYTES = 5_000_000 -MAX_LOOKUP_PAGES = 10 -PROJECT_METADATA_FIELDS = { - "name", - "description", - "license", - "implementation_languages", -} - - -class ProjectResolutionError(RuntimeError): - """Raised when a repository cannot be resolved safely.""" - - -class UnregisteredProjectError(ProjectResolutionError): - """Raised when no badge entry exists and explicit opt-in was not given.""" - - -@dataclass(frozen=True, slots=True) -class RepositoryIdentity: - root: Path - remote: str - project_name: str - url: str - - -@dataclass(frozen=True, slots=True) -class ProjectResolution: - identifier: str - project_id: str | None - registered: bool - repository: RepositoryIdentity - - -@dataclass(frozen=True, slots=True) -class SyncConflict: - field: str - preserved: Any - incoming: Any - source: str - - -@dataclass(frozen=True, slots=True) -class SyncResult: - resolution: ProjectResolution - assessment: dict[str, Any] - conflicts: tuple[SyncConflict, ...] - repository_file: Path | None - public_loaded: bool - public_document: Mapping[str, Any] = field(default_factory=dict) - public_fetched_at: str | None = None - - -def write_assessment_file(path: Path, assessment: Mapping[str, Any]) -> None: - """Atomically export an assessment to an explicitly selected path.""" - - serialized = ( - json.dumps( - dict(assessment), - ensure_ascii=False, - indent=2, - sort_keys=True, - ) - + "\n" - ) - if path.exists() and path.is_dir(): - raise IsADirectoryError(path) - if not path.parent.is_dir(): - raise FileNotFoundError(path.parent) - mode = stat.S_IMODE(path.stat().st_mode) if path.exists() else 0o644 - descriptor, temporary_name = tempfile.mkstemp( - dir=path.parent, - prefix=f".{path.name}.", - suffix=".tmp", - ) - temporary_path = Path(temporary_name) - try: - os.fchmod(descriptor, mode) - with os.fdopen(descriptor, "w", encoding="utf-8") as temporary_file: - temporary_file.write(serialized) - temporary_file.flush() - os.fsync(temporary_file.fileno()) - os.replace(temporary_path, path) - except BaseException: - temporary_path.unlink(missing_ok=True) - raise - - -def _git_value( - repository: Path, - *arguments: str, - runner: Callable[..., subprocess.CompletedProcess[str]] = subprocess.run, -) -> str: - command = ["git", "-C", str(repository), *arguments] - try: - completed = runner( - command, - check=False, - capture_output=True, - text=True, - timeout=15, - ) - except (OSError, subprocess.SubprocessError) as error: - raise ProjectResolutionError( - f"could not run {' '.join(command)}: {error}" - ) from error - if completed.returncode != 0: - detail = completed.stderr.strip() or completed.stdout.strip() or "git failed" - raise ProjectResolutionError(f"{' '.join(command)}: {detail}") - value = completed.stdout.strip() - if not value: - raise ProjectResolutionError(f"{' '.join(command)} returned no value") - return value - - -def discover_repository( - repository: str | Path, - *, - runner: Callable[..., subprocess.CompletedProcess[str]] = subprocess.run, -) -> RepositoryIdentity: - """Derive repository root and normalized origin using ``git -C``.""" - - requested = Path(repository).expanduser().resolve(strict=False) - root = Path( - _git_value(requested, "rev-parse", "--show-toplevel", runner=runner) - ).resolve(strict=False) - origin = _git_value(root, "remote", "get-url", "origin", runner=runner) - try: - normalized_remote = normalize_github_remote(origin) - except (TypeError, ValueError) as error: - raise ProjectResolutionError( - f"unsupported origin remote {origin!r}: {error}" - ) from error - return RepositoryIdentity( - root=root, - remote=normalized_remote, - project_name=root.name, - url=github_repository_url(origin), - ) - - -class BestPracticesClient: - """Polite sequential client for public bestpractices.dev JSON reads.""" - - def __init__( - self, - *, - base_url: str = DEFAULT_BASE_URL, - user_agent: str = DEFAULT_USER_AGENT, - minimum_interval: float = 1.0, - timeout: float = 20.0, - opener: Callable[..., Any] = urlopen, - clock: Callable[[], float] = time.monotonic, - sleeper: Callable[[float], None] = time.sleep, - ) -> None: - if minimum_interval < 0: - raise ValueError("minimum_interval must not be negative") - self.base_url = base_url.rstrip("/") - self.user_agent = user_agent - self.minimum_interval = minimum_interval - self.timeout = timeout - self._opener = opener - self._clock = clock - self._sleeper = sleeper - self._last_request_started: float | None = None - - def _wait(self) -> None: - if self._last_request_started is None: - return - remaining = self.minimum_interval - (self._clock() - self._last_request_started) - if remaining > 0: - self._sleeper(remaining) - - def _get_json(self, path: str, query: Mapping[str, str] | None = None) -> Any: - suffix = f"?{urlencode(query)}" if query else "" - request = Request( - f"{self.base_url}{path}{suffix}", - headers={"User-Agent": self.user_agent, "Accept": "application/json"}, - method="GET", - ) - self._wait() - self._last_request_started = self._clock() - try: - with self._opener(request, timeout=self.timeout) as response: - payload = response.read(MAX_RESPONSE_BYTES + 1) - except (HTTPError, URLError, TimeoutError, OSError) as error: - raise ProjectResolutionError( - f"public API read failed for {request.full_url}: {error}" - ) from error - if len(payload) > MAX_RESPONSE_BYTES: - raise ProjectResolutionError("public API response exceeded the size limit") - try: - return json.loads(payload.decode("utf-8")) - except (UnicodeDecodeError, json.JSONDecodeError) as error: - raise ProjectResolutionError( - f"public API returned invalid JSON for {request.full_url}" - ) from error - - def lookup_project_id(self, remote: str) -> str | None: - """Find one exact GitHub repository match using case-insensitive search. - - BadgeApp's ``url`` query is case-sensitive; ``pq`` retrieves a wider - case-insensitive candidate set. Inspect all pages and verify repository - keys locally before accepting a unique numeric BadgeApp project ID. - """ - - repository_url = github_repository_url(remote) - normalized_remote = normalize_github_remote(remote) - identifiers: set[str] = set() - # Older badge entries may store an HTTP URL for the same GitHub repo. - for prefix in (repository_url, repository_url.replace("https://", "http://", 1)): - for candidate in self._lookup_candidates(prefix): - identifier = _matching_project_id(candidate, normalized_remote) - if identifier is not None: - identifiers.add(identifier) - - if len(identifiers) > 1: - choices = ", ".join(sorted(identifiers, key=int)) - raise ProjectResolutionError( - f"repository lookup returned multiple project ids: {choices}; " - "pass --project-id to select the intended entry" - ) - return next(iter(identifiers), None) - - def _lookup_candidates(self, prefix: str) -> Iterator[Any]: - for page in range(1, MAX_LOOKUP_PAGES + 1): - payload = self._get_json( - "/projects.json", - {"pq": prefix, "sort": "id", "sort_direction": "asc", "page": str(page)}, - ) - if not isinstance(payload, list): - raise ProjectResolutionError("project lookup did not return a JSON array") - if not payload: - return - yield from payload - raise ProjectResolutionError( - "repository lookup is incomplete: search page limit reached; " - "pass --project-id to select the known badge entry" - ) - - def fetch_project(self, project_id: int | str) -> dict[str, Any]: - """Read one project's public JSON representation.""" - - identifier = str(project_id) - if not identifier.isdecimal(): - raise ValueError("public project id must be numeric") - payload = self._get_json(f"/projects/{int(identifier)}.json") - if not isinstance(payload, dict): - raise ProjectResolutionError( - "public project response was not a JSON object" - ) - return payload - - -def _matching_project_id(candidate: Any, normalized_remote: str) -> str | None: - if not isinstance(candidate, Mapping): - raise ProjectResolutionError("project lookup contains a non-object entry") - # A matching homepage must not override a different repository URL. - remote = candidate.get("repo_url") or candidate.get("homepage_url") - if not _remote_matches(remote, normalized_remote): - return None - identifier = candidate.get("id") - if isinstance(identifier, bool) or not str(identifier).isdecimal(): - raise ProjectResolutionError("matching badge entry has an invalid project id") - return str(int(identifier)) - - -def _remote_matches(value: Any, normalized_remote: str) -> bool: - if not isinstance(value, str) or not value: - return False - try: - return normalize_github_remote(value) == normalized_remote - except (TypeError, ValueError): - return False - - -def resolve_project( - store: DataStore, - repository: str | Path, - *, - project_id: int | str | None = None, - client: BestPracticesClient | None = None, - allow_unregistered: bool = False, -) -> ProjectResolution: - """Reuse a verified association or select an online candidate to validate.""" - - identity = discover_repository(repository) - registered_id = store.resolve_project_id(identity.remote) - identifier: str | None - if project_id is not None: - identifier = normalize_project_id(project_id) - if client is None and identifier != registered_id: - raise ProjectResolutionError( - "project id is not verified for this repository; run status online " - f"with --project-id {identifier} before using local commands" - ) - else: - identifier = registered_id - if identifier is None and client is not None: - identifier = client.lookup_project_id(identity.url) - - if identifier is not None: - identifier = normalize_project_id(identifier) - return ProjectResolution( - identifier=identifier, - project_id=identifier, - registered=True, - repository=identity, - ) - - if not allow_unregistered: - raise UnregisteredProjectError( - "no exact bestpractices.dev project entry was found; register the " - "project or explicitly pass --allow-unregistered for a local-only review" - ) - - store.create_unregistered( - identity.root, - remote=identity.remote, - project_name=identity.project_name, - ) - unregistered_identifier = store.unregistered_identifier(identity.root) - if unregistered_identifier is None: # Defensive: creation must establish it. - raise ProjectResolutionError("failed to create the unregistered project record") - return ProjectResolution( - identifier=unregistered_identifier, - project_id=None, - registered=False, - repository=identity, - ) - - -def load_repository_assessment( - repository_root: str | Path, -) -> tuple[Path | None, dict[str, Any]]: - """Load the first supported repository assessment location, if present.""" - - root = Path(repository_root) - for candidate in ( - root / ".bestpractices.json", - root / ".project.d" / "bestpractices.json", - ): - if not candidate.exists(): - continue - try: - payload = json.loads(candidate.read_text(encoding="utf-8")) - except (OSError, UnicodeDecodeError, json.JSONDecodeError) as error: - raise ProjectResolutionError( - f"invalid repository assessment {candidate}: {error}" - ) from error - if not isinstance(payload, dict): - raise ProjectResolutionError( - f"repository assessment {candidate} must contain a JSON object" - ) - return candidate, payload - return None, {} - - -def _assessment_fields(document: Mapping[str, Any]) -> dict[str, Any]: - selected: dict[str, Any] = {} - for key, value in normalize_assessment_fields(document).items(): - if ( - key in PROJECT_METADATA_FIELDS - or key.endswith("_status") - or key.endswith("_justification") - ): - selected[key] = value - return selected - - -def _observe_source( - current: dict[str, Any], - incoming_document: Mapping[str, Any], - source: str, - conflicts: list[SyncConflict], -) -> None: - """Initialize absent answers; report differences without changing existing ones.""" - existing_groups = answer_groups(current) - for key, incoming in answer_groups(_assessment_fields(incoming_document)).items(): - if key not in existing_groups: - current.update(incoming) - continue - existing = existing_groups[key] - for field, value in incoming.items(): - if field not in existing or existing[field] != value: - conflicts.append(SyncConflict(field, existing.get(field), value, source)) - - -def handoff_local_assessment( - store: DataStore, - resolution: ProjectResolution, - *, - resolved_fields: set[str] | None = None, -) -> tuple[dict[str, Any], tuple[SyncConflict, ...]]: - assessment, conflicts = store.handoff_unregistered( - resolution.repository.root, resolution.identifier, resolved_fields=resolved_fields, - ) - return assessment, tuple( - SyncConflict(field, preserved, incoming, "local_draft") - for field, (preserved, incoming) in sorted(conflicts.items()) - ) - - -def _public_snapshot( - store: DataStore, - resolution: ProjectResolution, - public_document: Mapping[str, Any], - *, - refreshed: bool, -) -> dict[str, Any] | None: - if not resolution.registered: - return None - if refreshed: - return store.save_public_snapshot( - resolution.identifier, resolution.repository.remote, public_document, - ) - return store.load_public_snapshot( - resolution.identifier, resolution.repository.remote, - ) - - -def synchronize_project( - store: DataStore, - repository: str | Path, - *, - project_id: int | str | None = None, - client: BestPracticesClient | None = None, - allow_unregistered: bool = False, - user_updates: Mapping[str, Any] | None = None, -) -> SyncResult: - """Read external sources without replacing existing local answers. - - Public data initialize wholly absent answers in the selected working file. Existing - status/justification pairs remain intact, including question marks and empty - wording. Differences are returned for the main agent to reconcile. Explicit - current-session ``user_updates`` are applied last. Without a client, the saved - public snapshot is returned for comparisons but never merged again. - """ - - repository_file, _ = load_repository_assessment(discover_repository(repository).root) - if repository_file is not None and store.assessment_file is None: - raise ProjectResolutionError( - "the repository has an assessment; select --assessment-file with a " - "temporary working copy, or the repository file for authorized direct edits" - ) - - resolution = resolve_project( - store, - repository, - project_id=project_id, - client=client, - allow_unregistered=allow_unregistered, - ) - public_document: dict[str, Any] = {} - if resolution.registered and client is not None: - public_document = client.fetch_project(resolution.project_id or "") - # Match lookup's homepage fallback without allowing it to override a - # populated repository URL. Missing identity cannot verify an entry. - remote = public_document.get("repo_url") or public_document.get("homepage_url") - if not _remote_matches(remote, resolution.repository.remote): - raise ProjectResolutionError( - "public project repository identity does not match the repository origin; " - "the entry must identify this repository in repo_url or, when absent, homepage_url" - ) - store.register_project(resolution.identifier, resolution.repository.remote) - - conflicts: list[SyncConflict] = [] - if resolution.registered: - _, local_conflicts = handoff_local_assessment(store, resolution) - conflicts.extend(local_conflicts) - - def observe_latest(current: dict[str, Any]) -> dict[str, Any]: - if public_document: - _observe_source(current, public_document, "public API", conflicts) - return current - - assessment = store.transform_assessment(resolution.identifier, observe_latest) - if user_updates: - assessment = store.update_assessment(resolution.identifier, user_updates) - if resolution.registered: - assessment, local_conflicts = handoff_local_assessment( - store, resolution, resolved_fields=set(user_updates), - ) - conflicts = [item for item in conflicts if item.source != "local_draft"] - conflicts.extend(local_conflicts) - # Cached website data supports comparisons but must not reintroduce conflicts - # for answers deliberately edited since the last online status command. - public_loaded = client is not None and resolution.registered - snapshot = _public_snapshot( - store, resolution, public_document, refreshed=public_loaded, - ) - if snapshot is not None: - public_document = snapshot["document"] - return SyncResult( - resolution=resolution, - assessment=assessment, - conflicts=tuple(conflicts), - repository_file=repository_file, - public_loaded=public_loaded, - public_document=public_document, - public_fetched_at=snapshot["fetched_at"] if snapshot else None, - ) diff --git a/plugins/badge-buddy/scripts/review_board.py b/plugins/badge-buddy/scripts/review_board.py new file mode 100755 index 0000000..4c74334 --- /dev/null +++ b/plugins/badge-buddy/scripts/review_board.py @@ -0,0 +1,84 @@ +#!/usr/bin/env python3 +"""Render an explicit draft as a passive local board, without BadgeApp access.""" + +from __future__ import annotations + +import argparse +import json +from pathlib import Path +import sys +import webbrowser + +from ossf_review.board import write_board +from ossf_review.criteria import CriteriaCatalog, SECTION_NAMES + + +def build_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument( + "--input", type=Path, required=True, help="existing flat draft JSON" + ) + parser.add_argument( + "--output", type=Path, required=True, help="local HTML destination" + ) + parser.add_argument( + "--project-id", + required=True, + help="selected BadgeApp project ID or local label", + ) + parser.add_argument("--section", choices=SECTION_NAMES, required=True) + parser.add_argument("--view", choices=("overview", "all"), default="all") + parser.add_argument( + "--open", action="store_true", help="open the local board in a browser" + ) + return parser + + +def _check_project_identity(document: dict, project_id: str) -> None: + """Do not label a registered project's draft as another numeric project.""" + recorded = document.get("id") + if not project_id.isdecimal() or recorded is None: + return + if ( + isinstance(recorded, bool) + or not isinstance(recorded, (str, int)) + or not str(recorded).isdecimal() + or int(recorded) != int(project_id) + ): + raise ValueError("The draft id does not match the selected project ID.") + + +def main(argv: list[str] | None = None) -> int: + args = build_parser().parse_args(argv) + try: + source = args.input.resolve() + destination = args.output.resolve() + if source == destination: + raise ValueError("The board output must not replace the input draft.") + document = json.loads(source.read_text(encoding="utf-8")) + if not isinstance(document, dict): + raise ValueError("The input draft must be a JSON object.") + _check_project_identity(document, args.project_id) + write_board( + document, + destination, + project_id=args.project_id, + section=args.section, + catalog=CriteriaCatalog(), + ) + url = destination.as_uri() + f"#view={args.view}" + if args.open: + webbrowser.open(url) + print( + json.dumps( + {"output": str(destination), "url": url, "section": args.section} + ) + ) + return 0 + except (OSError, ValueError, KeyError) as exc: + print(f"Could not render review board: {exc}", file=sys.stderr) + return 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/plugins/badge-buddy/scripts/scorecard.py b/plugins/badge-buddy/scripts/scorecard.py index ec29449..8362319 100755 --- a/plugins/badge-buddy/scripts/scorecard.py +++ b/plugins/badge-buddy/scripts/scorecard.py @@ -29,7 +29,7 @@ import urllib.parse import urllib.request -from ossf_review.storage import normalize_github_remote +from ossf_review.remotes import normalize_github_remote PUBLIC_API_BASE = "https://api.scorecard.dev/projects" @@ -79,7 +79,9 @@ def reported_score(value: Any) -> float | None: if value == -1: return None if not 0 <= value <= 10: - raise CommandError("reported score must be between 0 and 10, or -1 for inconclusive") + raise CommandError( + "reported score must be between 0 and 10, or -1 for inconclusive" + ) return float(value) @@ -89,7 +91,9 @@ def parse_date(value: str) -> datetime | None: try: date = datetime.fromisoformat(value.replace("Z", "+00:00")) except ValueError as error: - raise CommandError("result date must be an ISO 8601 date or timestamp") from error + raise CommandError( + "result date must be an ISO 8601 date or timestamp" + ) from error return date.replace(tzinfo=date.tzinfo or timezone.utc) @@ -111,7 +115,9 @@ def parse(cls, value: Any) -> CheckResult: score = entry.get("score") if type(score) is not int or not -1 <= score <= 10: raise CommandError(f"{name}: score must be an integer from -1 to 10") - documentation = optional_object(entry.get("documentation"), f"{name} documentation") + documentation = optional_object( + entry.get("documentation"), f"{name} documentation" + ) return cls( name=name, score=score, @@ -167,11 +173,15 @@ def parse(cls, value: Any, *, provenance: Mapping[str, Any]) -> Result: engine = optional_object(document.get("scorecard"), "result scorecard") entries = document.get("checks") if not isinstance(entries, list) or not entries: - raise CommandError("Scorecard result must contain a non-empty checks array; import Scorecard JSON, not SARIF") - checks = tuple(sorted( - (CheckResult.parse(entry) for entry in entries), - key=lambda check: check.name, - )) + raise CommandError( + "Scorecard result must contain a non-empty checks array; import Scorecard JSON, not SARIF" + ) + checks = tuple( + sorted( + (CheckResult.parse(entry) for entry in entries), + key=lambda check: check.name, + ) + ) if len({check.name for check in checks}) != len(checks): raise CommandError("Scorecard result contains duplicate check names") date = optional_text(document.get("date"), "result date") @@ -180,8 +190,12 @@ def parse(cls, value: Any, *, provenance: Mapping[str, Any]) -> Result: repo=name, commit=optional_text(repo.get("commit"), "result repo.commit"), date=date, - scorecard_version=optional_text(engine.get("version"), "result scorecard.version"), - scorecard_commit=optional_text(engine.get("commit"), "result scorecard.commit"), + scorecard_version=optional_text( + engine.get("version"), "result scorecard.version" + ), + scorecard_commit=optional_text( + engine.get("commit"), "result scorecard.commit" + ), checks=checks, reported_score=reported_score(document.get("score")), document=document, @@ -216,15 +230,23 @@ def coverage_notes(result: Result) -> list[str]: "acquisition conditions are unknown; use the API to verify a published badge." ] if result.repo.startswith("file://") or result.provenance.get("mode") == "local": - notes.append("Local checkout analysis has limited coverage and is not comparable to a published repository scan.") + notes.append( + "Local checkout analysis has limited coverage and is not comparable to a published repository scan." + ) if result.provenance.get("checks_requested"): notes.append("Only a subset of checks was requested for this imported result.") if not result.date or not result.commit: - notes.append("The scan date or repository commit is missing; freshness cannot be verified from this result alone.") + notes.append( + "The scan date or repository commit is missing; freshness cannot be verified from this result alone." + ) if result.reported_score is None: - notes.append("Upstream supplied no conclusive aggregate score; none is calculated here.") + notes.append( + "Upstream supplied no conclusive aggregate score; none is calculated here." + ) if any(check.score < 0 for check in result.checks): - notes.append("Inconclusive checks are unscored, not zero. A change in scored coverage can change the reported aggregate.") + notes.append( + "Inconclusive checks are unscored, not zero. A change in scored coverage can change the reported aggregate." + ) return notes @@ -239,14 +261,21 @@ def api_coverage_notes(repo: str) -> list[str]: f"guidance is limited to GitHub. For GitLab diagnostics, consult {GITLAB_GUIDANCE}." ) else: - notes.append("For GitHub, verify the Action publishing run and its resulting API record.") + notes.append( + "For GitHub, verify the Action publishing run and its resulting API record." + ) return notes def saved_provenance(value: Any) -> dict[str, Any]: metadata = object_field(value, "_ossf_scorecard metadata") - if type(metadata.get("schema_version")) is not int or metadata["schema_version"] != 1: - raise CommandError("invalid _ossf_scorecard metadata: expected schema_version 1") + if ( + type(metadata.get("schema_version")) is not int + or metadata["schema_version"] != 1 + ): + raise CommandError( + "invalid _ossf_scorecard metadata: expected schema_version 1" + ) provenance = object_field(metadata.get("provenance"), "_ossf_scorecard provenance") if provenance.get("source") not in ("api", "file", "cli"): raise CommandError("invalid _ossf_scorecard provenance source") @@ -260,10 +289,16 @@ def saved_provenance(value: Any) -> dict[str, Any]: def read_result_file(path: str) -> Result: origin = "" if path == "-" else str(Path(path).expanduser()) try: - raw = sys.stdin.read() if path == "-" else Path(origin).read_text(encoding="utf-8") + raw = ( + sys.stdin.read() + if path == "-" + else Path(origin).read_text(encoding="utf-8") + ) document = json.loads(raw) except (OSError, ValueError) as error: - raise CommandError(f"could not read Scorecard JSON from {origin}: {error}") from error + raise CommandError( + f"could not read Scorecard JSON from {origin}: {error}" + ) from error provenance: dict[str, Any] = {"source": "file", "origin": origin} if isinstance(document, Mapping) and "_ossf_scorecard" in document: provenance = saved_provenance(document["_ossf_scorecard"]) @@ -281,9 +316,16 @@ def parse_repository_url(repo: str) -> urllib.parse.SplitResult: trimmed = repo.strip().rstrip("/") if trimmed.count("/") == 1 and ":" not in trimmed: trimmed = f"github.com/{trimmed}" - parsed = urllib.parse.urlsplit(trimmed if "://" in trimmed else f"https://{trimmed}") - if parsed.scheme not in ("http", "https") or parsed.netloc.lower() not in ("github.com", "gitlab.com"): - raise CommandError("use owner/repo or a public github.com or gitlab.com repository URL") + parsed = urllib.parse.urlsplit( + trimmed if "://" in trimmed else f"https://{trimmed}" + ) + if parsed.scheme not in ("http", "https") or parsed.netloc.lower() not in ( + "github.com", + "gitlab.com", + ): + raise CommandError( + "use owner/repo or a public github.com or gitlab.com repository URL" + ) if parsed.query or parsed.fragment or "?" in trimmed or "#" in trimmed: raise CommandError("repository URLs must not contain a query or fragment") return parsed._replace( @@ -299,8 +341,13 @@ def repository_path_parts(parsed: urllib.parse.SplitResult) -> list[str]: if parsed.netloc.lower() == "gitlab.com" and "-" in parts: raise CommandError("use a GitLab repository URL, not a UI route containing /-/") parts[-1] = parts[-1].removesuffix(".git") - if any(part in (".", "..") or not re.fullmatch(r"[A-Za-z0-9_.-]+", part) for part in parts): - raise CommandError("repository path contains an invalid owner, group, or repository name") + if any( + part in (".", "..") or not re.fullmatch(r"[A-Za-z0-9_.-]+", part) + for part in parts + ): + raise CommandError( + "repository path contains an invalid owner, group, or repository name" + ) return parts @@ -309,13 +356,15 @@ def missing_publication_message(repo: str) -> str: message = f"{parsed.netloc}{parsed.path} has no published Scorecard result at this endpoint. " if parsed.hostname == "gitlab.com": return ( - message + "V1 supports reading existing GitLab API results, but implementation " + message + + "V1 supports reading existing GitLab API results, but implementation " "and publication setup guidance is limited to GitHub. You can import upstream " f"diagnostic JSON; consult {GITLAB_GUIDANCE} for GitLab scanning guidance. " "A diagnostic scan alone does not establish public publication." ) return ( - message + "Inspect the official Scorecard Action workflow and publish_results setting. " + message + + "Inspect the official Scorecard Action workflow and publish_results setting. " "If publication is authorized, configure it or check the publishing run and allow for ingestion. " "A diagnostic scan alone does not publish results." ) @@ -324,7 +373,11 @@ def missing_publication_message(repo: str) -> str: def fetch_public_api(repo: str, *, opener: Any = urllib.request.urlopen) -> Result: normalized = normalize_repo(repo) url = f"{PUBLIC_API_BASE}/{normalized}" - request = urllib.request.Request(url, headers={"Accept": "application/json", "User-Agent": USER_AGENT}, method="GET") + request = urllib.request.Request( + url, + headers={"Accept": "application/json", "User-Agent": USER_AGENT}, + method="GET", + ) try: with opener(request, timeout=API_TIMEOUT_SECONDS) as response: document = json.loads(response.read().decode("utf-8")) @@ -332,24 +385,47 @@ def fetch_public_api(repo: str, *, opener: Any = urllib.request.urlopen) -> Resu if error.code == 404: raise CommandError(missing_publication_message(repo)) from error if error.code == 429: - raise CommandError("public Scorecard API is rate-limited (429); wait before retrying") from error - raise CommandError(f"public Scorecard API returned HTTP {error.code}; this does not establish a missing result") from error + raise CommandError( + "public Scorecard API is rate-limited (429); wait before retrying" + ) from error + raise CommandError( + f"public Scorecard API returned HTTP {error.code}; this does not establish a missing result" + ) from error except (urllib.error.URLError, OSError) as error: - raise CommandError(f"could not reach the public Scorecard API: {error}") from error + raise CommandError( + f"could not reach the public Scorecard API: {error}" + ) from error except ValueError as error: - raise CommandError(f"public Scorecard API returned invalid JSON: {error}") from error - result = Result.parse(document, provenance={"source": "api", "origin": url, "viewer": f"{VIEWER_BASE}{normalized}"}) + raise CommandError( + f"public Scorecard API returned invalid JSON: {error}" + ) from error + result = Result.parse( + document, + provenance={ + "source": "api", + "origin": url, + "viewer": f"{VIEWER_BASE}{normalized}", + }, + ) if normalize_repo(result.repo).casefold() != normalized.casefold(): - raise CommandError(f"public Scorecard API returned a result for {result.repo}, not {normalized}") + raise CommandError( + f"public Scorecard API returned a result for {result.repo}, not {normalized}" + ) return result def write_snapshot(result: Result, destination: Path) -> None: document = dict(result.document) - document["_ossf_scorecard"] = {"schema_version": 1, "provenance": dict(result.provenance)} + document["_ossf_scorecard"] = { + "schema_version": 1, + "provenance": dict(result.provenance), + } path = destination.expanduser() path.parent.mkdir(parents=True, exist_ok=True) - path.write_text(json.dumps(document, ensure_ascii=False, indent=2, allow_nan=False) + "\n", encoding="utf-8") + path.write_text( + json.dumps(document, ensure_ascii=False, indent=2, allow_nan=False) + "\n", + encoding="utf-8", + ) def engine_comparable(before: Result, after: Result) -> bool: @@ -375,15 +451,23 @@ def comparison_repo_identity(repo: str) -> str: def comparison_barriers(before: Result, after: Result) -> list[str]: barriers = [] if comparison_repo_identity(before.repo) != comparison_repo_identity(after.repo): - barriers.append("Repository identity differs; these results cannot verify a change to one project.") + barriers.append( + "Repository identity differs; these results cannot verify a change to one project." + ) if not engine_comparable(before, after): - barriers.append("Scorecard version or engine commit differs or is unknown; scoring behavior may differ.") + barriers.append( + "Scorecard version or engine commit differs or is unknown; scoring behavior may differ." + ) if before.source != after.source: - barriers.append("A published API snapshot and an imported diagnostic have different acquisition sources.") + barriers.append( + "A published API snapshot and an imported diagnostic have different acquisition sources." + ) barriers.extend(coverage_barriers(before, after)) before_date, after_date = parse_date(before.date), parse_date(after.date) if before_date and after_date and after_date < before_date: - barriers.append("The after result is older than the before result; it cannot verify newer publication.") + barriers.append( + "The after result is older than the before result; it cannot verify newer publication." + ) return barriers @@ -392,15 +476,21 @@ def coverage_barriers(before: Result, after: Result) -> list[str]: before_names = {check.name for check in before.checks} after_names = {check.name for check in after.checks} if before_names != after_names: - barriers.append("The check set differs; aggregate scores cover different checks.") + barriers.append( + "The check set differs; aggregate scores cover different checks." + ) before_scored = {check.name for check in before.checks if check.score >= 0} after_scored = {check.name for check in after.checks if check.score >= 0} if before_scored != after_scored: - barriers.append("Scored coverage changed: checks entered or left the inconclusive set.") + barriers.append( + "Scored coverage changed: checks entered or left the inconclusive set." + ) return barriers -def check_change(name: str, old: CheckResult | None, new: CheckResult | None) -> dict[str, Any]: +def check_change( + name: str, old: CheckResult | None, new: CheckResult | None +) -> dict[str, Any]: old_score, new_score = old.value if old else None, new.value if new else None return { "check": name, @@ -408,7 +498,9 @@ def check_change(name: str, old: CheckResult | None, new: CheckResult | None) -> "after": new_score, "before_state": old.state if old else "absent", "after_state": new.state if new else "absent", - "delta": new_score - old_score if old_score is not None and new_score is not None else None, + "delta": new_score - old_score + if old_score is not None and new_score is not None + else None, "reason_after": new.reason if new else "check absent from the later run", "details_after": list(new.details) if new else [], "documentation_after": dict(new.documentation) if new else {}, @@ -419,13 +511,21 @@ def check_change(name: str, old: CheckResult | None, new: CheckResult | None) -> def comparison_notes(before: Result, after: Result, barriers: list[str]) -> list[str]: notes = list(barriers) if before.source == "import" or after.source == "import": - notes.append("Imported credentials and acquisition conditions are unverified; matching structure alone does not prove equivalent scans.") + notes.append( + "Imported credentials and acquisition conditions are unverified; matching structure alone does not prove equivalent scans." + ) if before.commit == after.commit and before.date == after.date: - notes.append("Both results identify the same snapshot; this does not verify a newer publishing run.") + notes.append( + "Both results identify the same snapshot; this does not verify a newer publishing run." + ) if barriers: - notes.append("The aggregate delta is withheld; inspect individual check changes and both reported scores.") + notes.append( + "The aggregate delta is withheld; inspect individual check changes and both reported scores." + ) else: - notes.append("Matching repository, engine and coverage permit a reported-score comparison; they do not prove the edits caused a change.") + notes.append( + "Matching repository, engine and coverage permit a reported-score comparison; they do not prove the edits caused a change." + ) return notes @@ -435,7 +535,11 @@ def compare(before: Result, after: Result) -> dict[str, Any]: old = {check.name: check for check in before.checks} new = {check.name: check for check in after.checks} score_delta = None - if not barriers and before.reported_score is not None and after.reported_score is not None: + if ( + not barriers + and before.reported_score is not None + and after.reported_score is not None + ): score_delta = round(after.reported_score - before.reported_score, 10) return { "before": before.summary(), @@ -452,15 +556,35 @@ def compare(before: Result, after: Result) -> dict[str, Any]: def build_parser() -> argparse.ArgumentParser: - parser = argparse.ArgumentParser(description="Retrieve and inspect upstream OpenSSF Scorecard results.") + parser = argparse.ArgumentParser( + description="Retrieve and inspect upstream OpenSSF Scorecard results." + ) commands = parser.add_subparsers(dest="command", required=True) - fetch = commands.add_parser("fetch", help="read the latest published API result; does not run a scan") - fetch.add_argument("--repo", required=True, help="owner/repo or public GitHub/GitLab repository URL") - fetch.add_argument("--output", type=Path, help="save the upstream JSON with acquisition metadata for later use") - explain = commands.add_parser("explain", help="inspect findings in upstream JSON or a saved API snapshot") - explain.add_argument("--input", required=True, help="Scorecard JSON file, or - for standard input") - diff = commands.add_parser("diff", help="compare checks and reported scores in two saved results") - diff.add_argument("--before", required=True, help="earlier Scorecard JSON file, or -") + fetch = commands.add_parser( + "fetch", help="read the latest published API result; does not run a scan" + ) + fetch.add_argument( + "--repo", + required=True, + help="owner/repo or public GitHub/GitLab repository URL", + ) + fetch.add_argument( + "--output", + type=Path, + help="save the upstream JSON with acquisition metadata for later use", + ) + explain = commands.add_parser( + "explain", help="inspect findings in upstream JSON or a saved API snapshot" + ) + explain.add_argument( + "--input", required=True, help="Scorecard JSON file, or - for standard input" + ) + diff = commands.add_parser( + "diff", help="compare checks and reported scores in two saved results" + ) + diff.add_argument( + "--before", required=True, help="earlier Scorecard JSON file, or -" + ) diff.add_argument("--after", required=True, help="later Scorecard JSON file, or -") return parser @@ -476,7 +600,9 @@ def result_payload(result: Result, state: str) -> dict[str, Any]: def execute_command(args: argparse.Namespace, *, opener: Any) -> dict[str, Any]: if args.command == "diff": if args.before == "-" and args.after == "-": - raise CommandError("only one of --before and --after may read standard input") + raise CommandError( + "only one of --before and --after may read standard input" + ) payload = compare(read_result_file(args.before), read_result_file(args.after)) return {**payload, "state": "diff_computed"} if args.command == "explain": @@ -489,12 +615,18 @@ def execute_command(args: argparse.Namespace, *, opener: Any) -> dict[str, Any]: return payload -def main(argv: Sequence[str] | None = None, *, opener: Any = urllib.request.urlopen) -> int: +def main( + argv: Sequence[str] | None = None, *, opener: Any = urllib.request.urlopen +) -> int: args = build_parser().parse_args(argv) try: payload = execute_command(args, opener=opener) payload["schema_version"] = 1 - print(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True, allow_nan=False)) + print( + json.dumps( + payload, ensure_ascii=False, indent=2, sort_keys=True, allow_nan=False + ) + ) return 0 except (CommandError, OSError, ValueError) as error: print(f"error: {error}", file=sys.stderr) diff --git a/plugins/badge-buddy/skills/ossf-bp-badges/README.md b/plugins/badge-buddy/skills/ossf-bp-badges/README.md index ffe306f..e8b764e 100644 --- a/plugins/badge-buddy/skills/ossf-bp-badges/README.md +++ b/plugins/badge-buddy/skills/ossf-bp-badges/README.md @@ -8,7 +8,7 @@ A second agent reviews Claude's contribution before Claude presents drafted answ - [Peer review](references/peer-review.md): how a second agent reviews the drafting agent's work. - [Writing justifications](references/justification-style.md): clear wording for the application. -- [Application guide](references/application.md): working files, synchronization, previews, and website transfers. +- [Application guide](references/application.md): MCP tools, working documents, local previews, and website transfers. - [BadgeApp's worked example](references/badgeapp-example.md): selected answers from a public application. - Badge guidance: [Passing](references/passing.md), [Silver](references/silver.md), [Gold](references/gold.md), and [Security Baseline](references/baseline.md). diff --git a/plugins/badge-buddy/skills/ossf-bp-badges/SKILL.md b/plugins/badge-buddy/skills/ossf-bp-badges/SKILL.md index 70d6544..c65ae7d 100644 --- a/plugins/badge-buddy/skills/ossf-bp-badges/SKILL.md +++ b/plugins/badge-buddy/skills/ossf-bp-badges/SKILL.md @@ -1,7 +1,6 @@ --- name: ossf-bp-badges description: Use when the user mentions badges in relation to OpenSSF, OSSF, open source security, Best Practices, CII, bestpractices.dev, Security Baseline, OSPS, or Baseline levels 1-3. Help explain criteria, complete badge applications, and implement project improvements. -allowed-tools: Bash("${CLAUDE_PLUGIN_ROOT}/scripts/ossf.py" *), Bash(${CLAUDE_PLUGIN_ROOT}/scripts/ossf.py *) license: MIT (See ${CLAUDE_PLUGIN_ROOT}/THIRD_PARTY_NOTICES.md for attribution regarding OpenSSF) metadata: author: Reponomics @@ -19,11 +18,11 @@ Preserve the distinction between current practices, plans, and history: a newly Honor the user's choice or resume their existing work. For a new application, suggest Passing for Metal or the lowest unfinished Security Baseline level. The tracks are parallel; users may work on later levels before earning earlier badges. Ask which section they want only if the task requires that choice and it remains unclear. -| Badge | Catalog section | Reference | -| --- | --- | --- | -| Passing | `passing` | [Passing](references/passing.md) | -| Silver | `silver` | [Silver](references/silver.md) | -| Gold | `gold` | [Gold](references/gold.md) | +| Badge | Catalog section | Reference | +| ------------------------ | ---------------------------------------- | ---------------------------------- | +| Passing | `passing` | [Passing](references/passing.md) | +| Silver | `silver` | [Silver](references/silver.md) | +| Gold | `gold` | [Gold](references/gold.md) | | OSPS / Security Baseline | `baseline-1`, `baseline-2`, `baseline-3` | [Baseline](references/baseline.md) | When beginning a level or explaining its prerequisites and completion, read that reference's Scope section. For an individual criterion, read its entry and applicable section notes. Follow a thematic link only when its stated question arises. Reuse guidance and criterion records already read during the session. @@ -36,12 +35,12 @@ For implementation work, use [coverage-baseline](../coverage-baseline/SKILL.md) Retrieve the complete record for the selected section and criterion using the lookup below, then read its entry in the badge reference. Include description, details, applicability, and required justification or URL fields in the interpretation. Repeated Metal identifiers share stored answers but can have different requirements at each level; reassess an inherited answer against the selected level before relying on it. -| Answer | Meaning | -| --- | --- | -| `Met` | The project implements the required practice. A file or tool alone may not establish its use, measured results, or history. | -| `Unmet` | An applicable practice is not satisfied. Offer help with useful improvements. | -| `?` | The answer is unknown. A limited search that finds nothing does not establish absence. | -| `N/A` | The criterion permits it and its applicability conditions are absent. Include the required explanation. | +| Answer | Meaning | +| ------- | --------------------------------------------------------------------------------------------------------------------------- | +| `Met` | The project implements the required practice. A file or tool alone may not establish its use, measured results, or history. | +| `Unmet` | An applicable practice is not satisfied. Offer help with useful improvements. | +| `?` | The answer is unknown. A limited search that finds nothing does not establish absence. | +| `N/A` | The criterion permits it and its applicability conditions are absent. Include the required explanation. | For Metal badges, every applicable MUST or MUST NOT must be satisfied. A SHOULD practice that the project has chosen not to adopt is `Unmet`, but can count toward the badge with a justification explaining the decision and its implications. A SUGGESTED practice counts as complete with either `Met` or `Unmet`. Preserve these distinctions; raw answer counts are not badge percentages. @@ -49,28 +48,9 @@ For a full section, collect shared project information once and reuse it across ### Look up selected criteria -Resolve the [bundled catalog](../../assets/criteria/criteria.json) relative to this skill. With Python 3.11+, the following command returns only the requested records, accepting form IDs or Baseline display IDs. Replace the path, section, and IDs for the current task; several IDs from one section can be retrieved together. No registration or application setup is needed. - -```bash -python3 - "" passing dynamic_analysis <<'PY' -import json -import sys -from pathlib import Path - -catalog_path, section, *criterion_ids = sys.argv[1:] -sections = json.loads(Path(catalog_path).read_text(encoding="utf-8"))["sections"] -if section not in sections or not criterion_ids: - raise SystemExit("Supply a valid section and at least one criterion ID") -for criterion_id in criterion_ids: - matches = [record for record in sections[section] - if criterion_id in (record["id"], record.get("display_id"))] - if len(matches) != 1: - raise SystemExit(f"Expected one criterion for {section}/{criterion_id}; found {len(matches)}") - print(json.dumps({"section": section, "criterion": matches[0]}, ensure_ascii=False, indent=2)) -PY -``` - -Use the bundled criteria during ordinary application work. If the user reports a difference or the form shows different wording, compare that specific criterion and follow the current form's requirement. +Use the registered `bestpractices` MCP server's `get_criteria(level, criterion_ids)` tool to retrieve complete records. Tool prefixes vary by host: discover the available tools and use their published schemas rather than guessing a fully qualified name. `get_criteria` works offline and needs no project registration. + +The MCP catalog is pinned, not necessarily the live site's current wording. The plugin retains a [bundled display catalog](../../assets/criteria/criteria.json) for its local board and advisory references. If the user reports a difference or the form shows different wording, compare that criterion and follow the current form's requirement. Report catalog differences rather than silently treating either snapshot as live. ## Draft and review @@ -80,29 +60,23 @@ When the requested draft is ready, ask a second agent to review your work: your ## Work with the application -Before the first application operation, resolve the [invocation paths](#invocation-paths), then read [Start or resume](references/application.md#start-or-resume) and select the working assessment. After startup, read only the section for the current task: - -| Task | Instructions and purpose | -| --- | --- | -| Start or resume | [Start or resume](references/application.md#start-or-resume): choose the working file, resolve the project, and synchronize once | -| Use a repository assessment | [Repository assessments](references/application.md#repository-assessments): select a working copy and preserve changes on writeback | -| Record agreed answers | [Record answers](references/application.md#record-answers): apply status and wording changes | -| Show answers or preview a revision | [Preview](references/application.md#preview): open the board or isolate undecided wording | -| Export JSON | [Export](references/application.md#export): write the selected assessment to a file | -| Update the badge website or explain a transfer | [Website transfers](references/application.md#website-transfers): choose or use the requested transfer method | -| Explain an API or field-format issue | [API](references/application.md#api): request formats and field-name differences | -| End the session | [Stop](references/application.md#stop): retain saved work and dispose of unfinished previews | - -Questions and project improvements do not require registration. The controller supports GitHub-hosted projects; for other forges, explain criteria and draft answers without invoking it or claiming synchronized status. +Before the first application operation, discover the `bestpractices` MCP tools, read [Start or resume](references/application.md#start-or-resume), and explicitly select the existing BadgeApp project. The plugin registers `best-practices-mcp==0.5.0`; it does not provide a parallel BadgeApp CLI. If the MCP is unavailable, explain the connection problem and help restore it. Continue advisory work if useful, but do not silently replace MCP operations with shell requests or browser automation. -### Invocation paths +| Task | Instructions and purpose | +| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | +| Start or resume | [Start or resume](references/application.md#start-or-resume): select the project, read saved answers, and choose a draft | +| Use a repository assessment | [Repository assessments](references/application.md#repository-assessments): select a working copy and preserve changes on writeback | +| Record agreed answers | [Record answers](references/application.md#record-answers): use explicit document tools or optional server storage | +| Show answers or preview a revision | [Preview](references/application.md#preview): render the passive local board | +| Export JSON | [Export](references/application.md#export): write the selected assessment through host file tools | +| Update the badge website | [Website transfers](references/application.md#website-transfers): prepare a proposal URL or repository import | +| Explain an API or field-format issue | [API](references/application.md#api): supported tool boundaries and field names | +| End the session | [Stop](references/application.md#stop): retain drafts and dispose of unfinished previews | -Resolve [the controller](../../scripts/ossf.py) relative to this skill and retain its absolute path. Other bundled links are relative to their containing document. Select the repository from the user's request and session context; `git rev-parse --show-toplevel` supplies the current checkout's root. +Questions and project improvements do not require registration. Unregistered projects can keep caller-owned draft notes; project-bound MCP application operations require an explicitly selected existing entry. Register through the site when the user is ready, then resolve and select the new entry. -Claude Code substitutes `${CLAUDE_PLUGIN_DATA}` with the plugin's persistent data directory. Use that value for `--data-dir`. This is the command template for the single startup operation described in the application guide: +### Local preview paths -```bash -"" --repo "" --data-dir "${CLAUDE_PLUGIN_DATA}" status -``` +Resolve [the board renderer](../../scripts/review_board.py) relative to this skill and retain its absolute path. It is a local plugin feature, outside the MCP's scope, and performs no BadgeApp operations. Resolve other bundled links relative to their containing document. -Replace placeholders with concrete absolute paths and quote shell arguments. Retain these paths for subsequent commands and delegated work. When using a selected assessment file, add `--assessment-file ""` to every operation. Keep each repository's answers separate. +Use a selected caller-owned working JSON file for the renderer. If using optional MCP storage, obtain the draft with `read_draft` and write a separate host-owned preview copy; do not infer or directly edit the server's storage path. Put board HTML in session scratch storage or an existing ignored directory. Quote concrete absolute paths in shell commands and keep each project's documents separate. diff --git a/plugins/badge-buddy/skills/ossf-bp-badges/references/application.md b/plugins/badge-buddy/skills/ossf-bp-badges/references/application.md index 47b73ae..f599ad7 100644 --- a/plugins/badge-buddy/skills/ossf-bp-badges/references/application.md +++ b/plugins/badge-buddy/skills/ossf-bp-badges/references/application.md @@ -1,141 +1,89 @@ -# Working with the badge application +# Working with the BadgeApp application -Read the section for the operation requested. Commands below follow the controller path and `--repo` / `--data-dir` arguments resolved at skill startup. Retain any selected `--assessment-file` on every operation. The controller supports GitHub-hosted projects; for other forges, help draft answers without claiming synchronization. +Use the plugin's registered `bestpractices` MCP server for BadgeApp discovery, reads, document checks, optional draft persistence and proposal generation. Use host file tools for caller-owned drafts and the separate local renderer for previews. The server does not authenticate to BadgeApp or save website changes. ## Start or resume -Use one flat `.bestpractices.json` assessment for all badge sections. Default to private plugin storage and briefly tell the user where progress is saved. If they already maintain an assessment in the repository or request that location, use [Repository assessments](#repository-assessments) to select the working file before continuing. +1. Resolve the repository from the user's request and session context. Call `find_project(query=)`, inspect the candidates and explicitly select the intended existing project. Do not silently choose among ambiguous matches. No matching entry means registration is needed for project-bound application work; registration itself happens on the website. +2. Call `get_project_progress(project_id, level)` for the selected section's saved answers and `get_criteria(level)` for its complete criteria. Keep source/fetch metadata with the working context. The criteria catalog is pinned; it is not a live scrape. +3. Choose the working draft. Prefer an existing user-selected assessment, including a repository file. Otherwise initialize a caller-owned flat document from the saved `answers`, adding the selected project's `id` and verified `repo_url` as provenance. `build_draft(draft=, changes=)` creates or revises an explicit document without writing files. Follow the discovered schema for exact argument names and result fields. +4. Compare saved answers with an existing draft before reconciling differences. Preserve intentional local values, including `?` and empty justifications. Explain substantive differences and resolve them with the user's instructions; fetching a project does not automatically merge or persist anything. -Run `status` online once at the start of each Claude Code session to verify the repository's badge entry and synchronize saved website answers: +Refresh saved progress after a website save, when the project changes, or when intervening website edits matter. Keep the selected project ID in each project-bound call. Preparing a proposal is not a save, and validation does not establish the truth of a claim. -```bash -"" --repo "" --data-dir "" status -``` - -Include `--assessment-file ` when using a selected assessment. Use the returned `assessment` and handle the registration state: +### Existing plugin drafts -- `registered`: continue with the returned project ID. -- `registration_required`: link to [registration](https://www.bestpractices.dev/projects/new), or use `--allow-unregistered` if the user chooses to defer it. -- `unregistered`: continue the deferred-registration work without asking again. -- `registry_miss`: rerun online before concluding that registration is absent. +The retired controller stored assessments at `projects//.bestpractices.json` beneath the host's plugin-data directory, or in a user-selected repository file. Those files remain usable as caller-owned documents. Locate them from the established session/host configuration, read the selected file, confirm its project association, and pass its contents explicitly to the MCP. Do not delete the old files, copy the old registry into MCP storage, or silently merge them with a newly fetched project. -Use `status --project-id ` when the numeric ID is known. Retain the verified repository/project association for subsequent local commands; rerun online status if either changes. Incomplete or ambiguous lookups do not establish that the project is unregistered. +### Optional MCP storage -`status` initializes wholly absent answers and preserves existing status/justification pairs, including `?` and empty wording. It reports differences as `conflicts`; resolve them using the user's current answers, asking only about differences that remain unclear. A `wording_only_updates` result means the saved website answer has the same status but different wording; keep the intended wording for a later transfer. +Only `update_draft` creates or patches server-managed files. Use `read_draft` to resume an existing stored document. An explicit `draft`, including `{}`, bypasses storage for validation and proposal generation; omitting it reads the selected project's stored draft. The storage root belongs to the server's filesystem and is configured through `BESTPRACTICES_DATA_DIR`; do not assume it is the plugin-data directory. Follow the server's documentation for platform defaults and overrides. Avoid concurrent writers; after an uncertain update, read before retrying. -`status` synchronizes answers and reports counts; it does not validate every saved field or establish that the project meets each criterion. `apply` validates changed answers against the selected section's field requirements, not the project's implementation of the practice. - -The public data contains only saved answers. If a section has never been saved, explain that its edit-page suggestions and percentage are not visible to the controller, and suggest saving that page once before refreshing. Site-generated suggestions may have incomplete justifications even when their status is correct. - -The controller retains the public snapshot for comparison. Subsequent `apply`, `review`, `export`, `propose`, and `fill-script` operations are local; assume no outside edits during the session. Refresh with `status` after website changes are saved or when requested. Use `status --offline` to inspect local progress without refreshing. A failed refresh leaves the previous snapshot available but does not establish current website state. +Explicit documents are sufficient for the entire normal workflow. Do not require optional server storage merely to use the skill or preview a board. ## Repository assessments -Use this section when working from `.bestpractices.json` or `.project.d/bestpractices.json` in the repository, or when the user requests repository storage. - -Copy the existing assessment to a temporary working file and retain the original bytes or digest for writeback. For a new assessment, start with a temporary file containing `{}`. Pass `--assessment-file ` on every operation, including previews and transfers. The file must exist and contain a flat JSON object. If direct edits are already authorized, use the repository file itself. - -Without `--assessment-file`, the controller stores answers privately. Repository-backed work has no additional private assessment copy. Both modes keep a separate public snapshot; use the controller's responses rather than editing its registry or sidecars. - -Before writing a temporary assessment back to the repository, show the changes or preview and obtain agreement unless already authorized. Compare the destination with the retained original; for a new file, check that the destination has not appeared. Reconcile any intervening changes rather than overwriting them. Copy the agreed assessment. Tracking a new file in Git is a separate user choice. +Check for an existing `.bestpractices.json` or `.project.d/bestpractices.json` only in the selected project. Prefer the user's established file and instructions. Normally work on a temporary copy so the user can review changes before repository writeback; direct edits are appropriate when requested. Remember the original contents and check for intervening edits before applying the chosen changes back. Never overwrite unrelated fields or a changed file blindly. ## Record answers -Help the user carry their decisions into the form. Here, confirmed changes are changes the user has requested or agreed to; they do not need the assistant's certification. If field validation rejects a change, explain the specific format or required-detail issue and help resolve it without adding a separate compliance audit. - -Send confirmed flat-field changes through `apply --section
--input -`. Always supply the section: reused Metal identifiers can have different requirements. Apply status and justification together when both change; a wording-only update may contain just `_justification`. Inspect advisory `style_warnings` for useful corrections. +Read the justification-style guide and complete the requested peer review before presenting drafted application text. Use `build_draft` with explicit draft and changes documents, then save the returned document using host file tools. If the user chose server-managed persistence, use `update_draft(project_id, changes=)` instead. Preserve omitted fields; use the tools' documented patch semantics rather than inferring deletion behavior. -An open preview does not add an approval step for an exact change the user has already requested. Apply it to the working assessment. Use a separate preview revision only when the user wants to consider wording before adopting it. +Call `validate_draft(project_id, level, draft=)` to check mechanical requirements for the selected section. Explain useful findings and correct accidental mistakes. Validation is advisory: the user controls their answers, and the validator cannot assess whether a project practice or explanation is true. Unknown answers can remain unknown. ## Preview -Offer once to open the board when starting or resuming application work. Use `review --section
` for Overview, or `review --section
--view all` to show current answers. Add `--no-browser` to generate without opening. The `review_written` response supplies the file URL. +The local board remains a plugin feature, not an MCP tool. It renders caller-owned JSON without fetching, changing answers, or saving to BadgeApp. Resolve the renderer path from the skill and run it with Python 3.11 or newer: -Generate one board per requested section; the command otherwise defaults to Passing. The board refreshes within five seconds of an update and retains its selected view. It displays official criterion text and stable section numbering, so filtered lists may have gaps. Browsing neither approves answers nor copies them into the repository. - -When the user requests a preview of wording they have not adopted: +```bash +python3 "" --input "" --output "" --project-id "" --section baseline-1 --view all +``` -1. Copy the controller-returned flat `assessment` into a temporary revision file and use `--assessment-file ` for that revision and its board. -2. Update only `_justification` with `apply --section
--review-response --input -`. This checks wording against the intended response while leaving the current status and board category unchanged; explain that distinction once. -3. When the user approves the wording and response, apply `_status` to the revision, then apply the exact approved status/justification pair to the normal working file. The board category updates in place. -4. On cancellation, pause, or transfer preparation, discard unfinished revisions and regenerate the board from the normal working file. +The command reports the local HTML URL. Open it with the host's normal browser/file capability when the user requests a preview, or add `--open` when appropriate for that host. Use `passing`, `silver`, `gold`, or `baseline-1` through `baseline-3` as the section. `--view overview` opens the category view; `--view all` opens all criteria. For pre-registration advisory work, a local label can replace the project ID in the board only. -Initial drafts can apply status and justification together. Wording-only revisions keep the same status. Never export unfinished preview wording. +Rerun the renderer after a draft changes. The open HTML refreshes every five seconds, but it does not watch the JSON file or fetch server storage. It displays a draft snapshot, not a saved-versus-proposed diff, and uses the plugin's bundled display catalog. Keep undecided wording in a separate preview copy when useful. Reading or navigating the board never changes a response. ## Export -For a local JSON export, use `export --output ` with the selected working-file options. This exports the assessment without fetching website data. To place it in the repository, export to a temporary path and follow [Repository assessments](#repository-assessments) for writeback. Website transfer instructions are needed only if the user wants the site to import it. +Write the selected flat draft document to the user's requested destination with host file tools. The MCP does not provide an export-to-path tool. Preserve the selected project's identity and all intended fields, inspect the resulting JSON, and avoid overwriting an existing destination without following the user's instructions. A repository import file should contain only the intended public application data; working analysis and private notes belong elsewhere. ## Website transfers -Use the normal working assessment and resolved numeric project ID. Finish or discard outstanding preview revisions first. Mention unanswered criteria and unresolved synchronization differences without requiring a completed badge or another assessment. Offer an All criteria preview if the user has not already reviewed the answers being transferred. +Use the requested path, or explain these two choices when a choice is needed: -When the user has chosen a method, read its section below. Otherwise offer these choices: - -| Method | Use it for | -| --- | --- | -| [Proposal URLs](#proposal-urls) | Highlighting proposed changes in the official form, without publishing a repository file. | -| [Repository import](#repository-import) | Sharing durable answers in the repository; this cannot force replacements of existing website answers. | -| [Fill script](#fill-script) | Long answers or selected form edits, including wording replacements. | - -All methods prepare changes for review; none saves the form. After filling it, follow [Saving on the website](#saving-on-the-website) to explain the save action and refresh the local snapshot afterward. +| Path | Appropriate use | +| --------------- | ------------------------------------------------------------------------------------------------- | +| Proposal URL | Review proposed answers in the official edit form, including replacements with explicit overrides | +| Repository JSON | Publish a `.bestpractices.json` file for the site's automated-tool import | ### Proposal URLs -Run `propose --section
--overrides '*_status,*_justification'` after resolving synchronization differences. Overrides affect only fields included in the URL; the controller omits answers already matching saved site data. If the user prefers a website value, adopt it in the assessment before generating the proposal. Site-generated suggestions need not displace answers the user has approved. - -The form applies proposals as follows: +Use `prepare_update_url(project_id, level, draft=)`. Select only the intended fields when preparing a partial update; the tool reports included and excluded fields and does not save anything. Inspect the returned outcome, notes and artifact before opening it. A complete result means generation succeeded, not that the website accepted or saved every field. -| Existing value | Proposal | Result | -| --- | --- | --- | -| Blank or unknown status | Known status | Applied, highlighted yellow. | -| Known status | Different status without a matching override | Retained; difference highlighted blue. | -| Known status | Different status with a matching override | Replaced, highlighted orange. | -| Matching status, blank justification | New justification | Applied. | -| Matching status, existing justification | New wording without a matching override | Existing wording retained. | -| Matching status, existing justification | New wording with a matching override | Wording replaced. | -| Any status | `?` | Status proposal ignored. | +To replace existing answers or wording, pass the specific intended field names in `override_fields`, for example `osps_ac_01_01_justification`. The current MCP accepts explicit fields rather than the old controller's wildcard string. Keep each criterion's status and justification together where their relationship matters. Do not broaden overrides merely to make a proposal appear successful. -For a narrower override, supply a comma-separated list of Ruby `File.fnmatch` field patterns, such as `--overrides contribution_justification`. Forcing a status also forces its justification. A blocked status change blocks its accompanying justification even if that justification has a separate override. The site matches the patterns; generating a URL does not establish that an override matched or that the form was saved. +If the result is too large or otherwise incomplete, report that result and reduce the requested scope or shorten text with the user. Do not invent URL chunking behavior or fall back to browser-console scripts. For multiple separately prepared proposals, review and save each before the next and refresh the saved state between them. -Relay the controller's proposed, skipped, and dropped notes. Without overrides, it reports replacements of existing wording separately for the fill-script path. It rejects override lists above 10,000 characters or 1,000 patterns, which the site otherwise silently ignores. Its practical URL limit is 6,000 bytes; use a fill script for answer pairs too large for one URL. Keep each criterion's status and justification together, and save each page before opening the next when several URLs are returned. - -Proposals survive login redirects and apply after initial site suggestions, but a draft recovered after login takes precedence. Revisiting a URL reapplies its proposals. The site trims surrounding whitespace from proposed justifications. If the form behaves differently, use direct form editing or a fill script for the requested changes. +The site can retain existing answers or apply its own automation. Opening a proposal does not establish persistence. Review the actual form and its notices. After the user saves, use `get_project_progress` to confirm the saved result; compare the intended fields rather than relying only on the percentage. ### Repository import -Use [Export](#export) to prepare `.bestpractices.json` at the repository root or `.project.d/bestpractices.json`; the site checks them in that order. The file must be available on the remote repository for the site to read it. It fills blanks and shows differences but cannot force an existing answer to change. - -The site reads the file when editing an unsaved section, on `reanalyze=1`, and on **Save (and continue)**. **Submit (and exit)** does not normally reread it. Changing the repository URL also triggers full analysis on save. - -Use a flat JSON object within the 100,000-byte limit. Fields use lowercase IDs followed by `_status` or `_justification`; Baseline fields look like `osps_ac_01_01_status`. The site validates field names, types, and justification length. General fields such as `name` and `license` are also accepted. Unknown or invalid statuses—including `?`—are ignored, but an accompanying or standalone justification can still be processed. +Use [Export](#export) to prepare `.bestpractices.json` at the repository root or `.project.d/bestpractices.json`; the site checks them in that order. Publish the file only within the user's authorized repository workflow. The site fills blanks and shows differences but does not force existing answers to change. -The site also reads `security-insights.yml`; that format has its own specification, so do not infer its mappings from this JSON format. - -### Fill script - -Run `fill-script --section
--output ` to produce a console script for the user's section edit page. It changes radio buttons and justification fields without saving or proposal-style highlighting. By default, `--changed-only` selects only wording differences from the saved public snapshot. Use `--criteria ` for an explicit subset or `--all` for every answered criterion; retain the user's chosen scope. - -The script can replace statuses and wording without URL override rules. It omits `?` statuses; reset an answer to unknown directly in the form. Site automation still runs when the form is saved. +The site reads the file when editing an unsaved section, on reanalysis, and on **Save (and continue)**. **Submit (and exit)** does not normally reread it. Changing the repository URL also triggers full analysis on save. The public file must use the site's flat field format and limits; consult the current BadgeApp automation-proposal documentation when diagnosing import behavior. The site also reads `security-insights.yml`, which has its own specification; do not infer mappings from the JSON format. ### Saving on the website -Explain that both **Save (and continue)** and **Submit (and exit)** save the entry; the latter simply leaves edit mode. There is no irreversible completion step: entries are public from registration and remain editable. Repository import specifically needs **Save (and continue)** to reread the file. +Both **Save (and continue)** and **Submit (and exit)** save the entry; the latter leaves edit mode. Entries remain editable. The user reviews and saves, or explicitly asks the host to help with that browser action. The MCP neither authenticates nor performs the save. Saving can reapply high-confidence automated answers, and URL overrides do not disable that behavior. If a value changes again, inspect the site's explanation and help address the relevant project condition. -The user reviews and saves the form, or explicitly asks Claude to log in or save it; carry out that request when given. The controller neither authenticates nor writes to BadgeApp. Saving can reapply the site's high-confidence automated answers, and URL overrides do not disable this. If an answer changes again, inspect the site's explanation and help address the relevant project condition. Run `status` after saved changes to refresh the comparison snapshot; preparing or opening a transfer does not refresh it. - -If the user asks about the license of their BadgeApp entry data, consult “Privacy and legal issues” on the [site's front page](https://www.bestpractices.dev/en), because the terms depend on when the entry was last edited. +If asked about licensing of BadgeApp entry data, consult “Privacy and legal issues” on the [site's front page](https://www.bestpractices.dev/en), because terms depend on when the entry was last edited. ## API -Use this section only when explaining or diagnosing an API or field-format issue; ordinary application operations use the controller. - -Read a project with `GET /projects/.json`, using the `.json` suffix rather than the `Accept` header. Limit non-badge requests to one per second. `GET /projects.json?url=` matches homepage or repository URLs, ignoring trailing slashes and spaces. Zero or multiple matches require project selection. Public JSON may return Baseline display fields such as `OSPS-AC-01.01_status`; the controller normalizes them for form fields, URLs, and repository JSON. - -Proposal URLs use `/(:locale/)projects/:id/:section/edit?KEY=VALUE&...`, with URL-encoded values. Fields outside the edited section are ignored; `name`, `description`, `license`, and `implementation_languages` are accepted in any section. Known status values are `Met`, `Unmet`, and permitted `N/A`. +Ordinary application operations use the MCP tools, not direct shell HTTP calls. The MCP normalizes supported Baseline display IDs to form IDs such as `osps_ac_01_01_status`. Use the selected level's catalog and published tool schema for field eligibility and types. Public reads return provenance; inspect and retain relevant attribution when reusing upstream material. -The upstream API supports authenticated writes but recommends proposals or repository JSON instead. The plugin has no authenticated API write path. +The MCP supports public BadgeApp reads and generated review URLs, not project registration or authenticated writes. `get_project_badge_status` provides a compact badge-family observation; `get_project_badge_svg` provides SVG and a dynamic Markdown embed. Neither is a replacement for saved criterion answers from `get_project_progress`. ## Stop -Discard unfinished preview revisions and distinguish durable answers from repository work awaiting writeback. Apply or discard that work according to the user's instructions, then remove session scratch files. Resume from the durable assessment next time. +Retain the agreed caller-owned or server-stored draft for resumption. Distinguish it from unsaved website proposals and repository work awaiting writeback. Apply or discard unfinished preview revisions and repository changes according to the user's instructions, then remove disposable session scratch files. Do not delete durable drafts merely because the session ends. diff --git a/plugins/badge-buddy/skills/ossf-bp-badges/references/baseline.md b/plugins/badge-buddy/skills/ossf-bp-badges/references/baseline.md index 9591d2d..d1cda25 100644 --- a/plugins/badge-buddy/skills/ossf-bp-badges/references/baseline.md +++ b/plugins/badge-buddy/skills/ossf-bp-badges/references/baseline.md @@ -6,7 +6,7 @@ Use `baseline-1`, `baseline-2`, or `baseline-3`. These sections contain 24, 19, Every control is mandatory and permits `N/A` with a written justification when its triggering condition is absent. Recommendations in a control's details remain recommendations. -Use lowercase underscore IDs such as `osps_ac_01_01` in application fields. The public API may return display IDs such as `OSPS-AC-01.01`; the controller handles that mapping during synchronization. +Use lowercase underscore IDs such as `osps_ac_01_01` in application fields. The public API may return display IDs such as `OSPS-AC-01.01`; the MCP normalizes that mapping for application operations, and the local board accepts both forms. ## AC — Access Control (organization and repository settings) @@ -106,8 +106,8 @@ Reuse the project's existing security contacts, reporting channels, and policy U When reusing an existing Metal answer, read the matching row to identify the additional condition Baseline requires. Reuse relevant facts and URLs without assuming the status carries over: -| Related criteria | Additional distinction to resolve | -| --- | --- | +| Related criteria | Additional distinction to resolve | +| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Passing `vulnerability_report_response` → Baseline `osps_vm_01_01` | Passing requires initial responses within 14 days for reports received in the last six months, and allows `N/A` if there were none. Baseline requires a published CVD policy with a clear response timeframe regardless of report history; it does not prescribe that Passing timeframe. Reuse the reporting information and ask only for the policy commitment if it is missing. | -| Gold `two_person_review` → Baseline `osps_qa_07_01` | Gold requires another person's review of at least 50% of proposed modifications before release, assessing their suitability and known issues. Baseline requires VCS-enforced non-author human approval before every primary-branch merge. A Gold `Met` answer alone establishes neither Baseline's coverage nor its enforcement. | -| Passing `test` → Baseline `osps_qa_06_01` | Passing requires a publicly released automated FLOSS test suite and clear instructions or configuration for running it. Baseline requires CI to execute a suite before accepting a commit; its details also recommend contributor-visible results. Reuse the suite description and ask only about missing CI details, preserving that distinction in requirement strength. | +| Gold `two_person_review` → Baseline `osps_qa_07_01` | Gold requires another person's review of at least 50% of proposed modifications before release, assessing their suitability and known issues. Baseline requires VCS-enforced non-author human approval before every primary-branch merge. A Gold `Met` answer alone establishes neither Baseline's coverage nor its enforcement. | +| Passing `test` → Baseline `osps_qa_06_01` | Passing requires a publicly released automated FLOSS test suite and clear instructions or configuration for running it. Baseline requires CI to execute a suite before accepting a commit; its details also recommend contributor-visible results. Reuse the suite description and ask only about missing CI details, preserving that distinction in requirement strength. | diff --git a/plugins/badge-progress/.claude-plugin/plugin.json b/plugins/badge-progress/.claude-plugin/plugin.json index 995aee9..8e6e89f 100644 --- a/plugins/badge-progress/.claude-plugin/plugin.json +++ b/plugins/badge-progress/.claude-plugin/plugin.json @@ -2,9 +2,11 @@ "name": "badge-progress", "version": "0.3.0-beta.1", "description": "A pane and progress band for Badge Buddy's OpenSSF Best Practices applications", - "author": { "name": "Reponomics", "url": "https://github.com/reponomics" }, + "author": { + "name": "Reponomics", + "url": "https://github.com/reponomics" + }, "homepage": "https://github.com/reponomics/plugins", "repository": "https://github.com/reponomics/plugins", - "license": "MIT", - "types": "./types/index.d.ts" + "license": "MIT" } diff --git a/plugins/badge-progress/README.md b/plugins/badge-progress/README.md index 6df1326..75be4f0 100644 --- a/plugins/badge-progress/README.md +++ b/plugins/badge-progress/README.md @@ -5,29 +5,15 @@ Badge Progress: See your badge work take shape -Badge Progress shows how far along your OpenSSF Best Practices application is while you work on it with [Badge Buddy](../badge-buddy/README.md). It adds a pane to Claude Code with the answer counts for each badge section, and a progress bar above the prompt while Claude records answers. +Badge Progress tracking is paused while [Badge Buddy](../badge-buddy/README.md) migrates from its old BadgeApp CLI to best-practices-mcp. The `/badge-progress` pane now shows a transition notice instead of restoring potentially stale controller counts. It does not intercept MCP calls or resume the removed CLI. -It is a mod: a plugin that changes Claude Code's interface through function hooks rather than adding skills. It reads the results of the Badge Buddy commands Claude already runs, so it needs no setup and makes no network requests of its own. +Ask Badge Buddy to open its local preview board to review answers. That board remains available for Passing, Silver, Gold and Baseline levels 1–3. -## Get started +## Follow-up work -```sh -claude plugin marketplace add reponomics/plugins -claude plugin install badge-buddy@reponomics -claude plugin install badge-progress@reponomics -``` - -Start or resume badge work as usual, for example "Help me with the OpenSSF Best Practices Passing badge." The pane opens the first time Claude checks the application's status. Open it again at any time with `/badge-progress`. - -## What it shows - -- **The pane** lists each started section (Passing, Silver, Gold, Baseline 1–3) with a bar of answered criteria, the Met / Unmet / N/A / `?` breakdown, answers still missing a required justification or URL, and any differences from the saved website entry that need resolving. -- **The progress band** appears above the prompt while a turn is recording answers for a section, with the running count and how many were answered during the turn. -- **A short notice** at the end of that turn summarizes the change. - -"Answered" means any status other than `?`, as Badge Buddy counts it. The counts describe what is recorded in the working assessment. They are not a badge percentage, and they do not mean the website entry has been saved. +An MCP-aware progress pane needs a separately reviewed event adapter. It must use the host's documented MCP tool-result events, bind state to the selected BadgeApp project, distinguish saved website observations from caller-owned drafts, and derive counts from the appropriate catalog. `build_draft` has no selected badge level, while `update_draft` returns a patch rather than a complete document; neither can safely be treated as the old controller's full assessment snapshot. Evidence-gap checks and website/draft differences also need explicit semantics. -The last counts are kept per project directory, so the pane shows them at the start of the next session until Claude refreshes the status. +This suspension avoids presenting stale counts as current progress. Existing persisted state is left untouched but is not read or displayed. No progress band or completion toast is emitted. ## Development diff --git a/plugins/badge-progress/hooks/parse.ts b/plugins/badge-progress/hooks/parse.ts deleted file mode 100644 index 1c6830c..0000000 --- a/plugins/badge-progress/hooks/parse.ts +++ /dev/null @@ -1,115 +0,0 @@ -// Reads Badge Buddy controller (ossf.py) commands and their JSON output. -// Pure functions, so they can be tested without the engine. - -import type { SectionCounts, Snapshot } from "../types"; - -export const SECTIONS = [ - "passing", - "silver", - "gold", - "baseline-1", - "baseline-2", - "baseline-3", -] as const; - -const LABELS: Record = { - passing: "Passing", - silver: "Silver", - gold: "Gold", - "baseline-1": "Baseline 1", - "baseline-2": "Baseline 2", - "baseline-3": "Baseline 3", -}; - -export const sectionLabel = (section: string): string => - LABELS[section] ?? section; - -export type ControllerCommand = "status" | "apply" | "other"; - -// The part of a shell command before any heredoc body, which may hold -// arbitrary JSON (apply --input - <<'JSON' ...). -const head = (command: string): string => command.split("<<")[0] ?? command; - -/** Which controller command a Bash command runs, or null when it runs none. */ -export function controllerCommand(command: string): ControllerCommand | null { - const text = head(command); - if (!/ossf\.py\b/.test(text)) return null; - const match = /ossf\.py['"]?\s(?:[^\n]*?\s)?(status|apply)(?=\s|$)/.exec( - text, - ); - return (match?.[1] as ControllerCommand | undefined) ?? "other"; -} - -/** The value of `--section`, when the command names one. */ -export function sectionArgument(command: string): string | null { - const match = /--section(?:=|\s+)['"]?([a-z0-9-]+)/.exec(head(command)); - return match?.[1] ?? null; -} - -const count = (value: unknown): number => - typeof value === "number" && Number.isFinite(value) ? value : 0; - -/** - * The counts from a status or apply payload, or null when the text is not - * one. Warnings on stderr may precede the JSON object. - */ -export function parsePayload( - text: string, - source: Snapshot["source"], - at: number, -): Snapshot | null { - const start = text.indexOf("{"); - const end = text.lastIndexOf("}"); - if (start < 0 || end <= start) return null; - let payload: unknown; - try { - payload = JSON.parse(text.slice(start, end + 1)); - } catch { - return null; - } - if (typeof payload !== "object" || payload === null) return null; - const record = payload as Record; - const raw = record.sections; - if (typeof raw !== "object" || raw === null) return null; - - const sections: Record = {}; - for (const section of SECTIONS) { - const entry = (raw as Record)[section]; - if (typeof entry !== "object" || entry === null) continue; - const c = entry as Record; - const total = count(c.total); - const unknown = count(c.unknown); - sections[section] = { - total, - met: count(c.met), - unmet: count(c.unmet), - notApplicable: count(c.not_applicable), - unknown, - decided: typeof c.decided === "number" ? c.decided : total - unknown, - evidenceGaps: count(c.evidence_gaps), - }; - } - if (sections.passing === undefined) return null; - - const project = (record.project ?? {}) as Record; - return { - project: typeof project.name === "string" ? project.name : null, - projectId: - typeof project.project_id === "number" ? project.project_id : null, - sections, - conflicts: Array.isArray(record.conflicts) ? record.conflicts.length : 0, - source, - at, - }; -} - -/** A text progress bar `width` cells wide, split into filled and empty runs. */ -export function bar( - done: number, - total: number, - width: number, -): [string, string] { - const cells = Math.max(1, Math.floor(width)); - const filled = total > 0 ? Math.round((done / total) * cells) : 0; - return ["█".repeat(filled), "░".repeat(cells - filled)]; -} diff --git a/plugins/badge-progress/hooks/register.tsx b/plugins/badge-progress/hooks/register.tsx index cff0b97..b7a159e 100644 --- a/plugins/badge-progress/hooks/register.tsx +++ b/plugins/badge-progress/hooks/register.tsx @@ -1,237 +1,25 @@ -import { atom, read, update } from "claude-code"; import type { Register } from "claude-code"; -import type { Filling, SectionCounts, Snapshot } from "../types"; -import { - SECTIONS, - bar, - controllerCommand, - parsePayload, - sectionArgument, - sectionLabel, -} from "./parse"; - const PANE = "badge-progress"; -const TITLE = "Badge progress"; - -// Change a tag when the stored shape changes, so values an earlier version -// stored are read as the initial value instead. -const snapshot = atom( - { plugin: "badge-progress", key: "snapshot" } as const, - null, - { shape: "snapshot-1" }, -); -const filling = atom( - { plugin: "badge-progress", key: "filling" } as const, - null, - { shape: "filling-1" }, -); -const autoOpened = atom( - { plugin: "badge-progress", key: "autoOpened" } as const, - false, -); - -// The last snapshot is kept per project directory, so the pane has -// something to show at the start of the next session. -const storeKey = (cwd: string) => `snapshot:${cwd}`; - -const pad = (text: string, width: number) => - text.length >= width ? text : text + " ".repeat(width - text.length); - -const clock = (at: number) => { - const date = new Date(at); - const two = (n: number) => String(n).padStart(2, "0"); - return `${two(date.getHours())}:${two(date.getMinutes())}`; -}; +const NOTICE = + "Badge Progress tracking is paused while Badge Buddy moves to best-practices-mcp. Ask Badge Buddy to open its local preview board. Previous controller counts are not displayed because they may be stale."; export const register: Register = (on) => { on("session.start", async ($, e, next) => { await $.command.register({ name: "badge-progress", - description: "Show OpenSSF badge application progress in a pane", + description: "Show the Badge Progress MCP migration notice", }); - const current = await read($, snapshot); - if (current === null) { - const saved = await $.store.get(storeKey(e.cwd)); - if (saved && typeof saved === "object") { - await update($, snapshot, () => saved as Snapshot); - } - } return next(e); }); on("command.run", { command: "badge-progress" }, async ($) => { - await $.ui.open({ id: PANE, title: TITLE }); - return { text: "Badge progress pane opened." }; - }); - - on("tool.call", { tool: "Bash" }, async ($, e, next) => { - const ran = await next(e); - const kind = controllerCommand(e.command); - if (kind !== "status" && kind !== "apply") return ran; - if (ran.deny !== undefined || ran.isError) return ran; - - const now = await $.clock.now(); - const latest = parsePayload(ran.text ?? "", kind, now); - if (latest === null) return ran; - - const previous = await read($, snapshot); - await update($, snapshot, () => latest); - await $.store.set(storeKey(await $.session.cwd()), latest); - - const section = kind === "apply" ? sectionArgument(e.command) : null; - const counts = section === null ? undefined : latest.sections[section]; - if (section !== null && counts !== undefined) { - const before = previous?.sections[section]?.decided ?? counts.decided; - await update($, filling, (current) => - current !== null && current.section === section - ? { ...current, applies: current.applies + 1 } - : { section, startDecided: before, applies: 1 }, - ); - } - - if (!(await read($, autoOpened))) { - await update($, autoOpened, () => true); - void $.ui.open({ id: PANE, title: TITLE }); - } - return ran; - }).catch(($, e, next) => next(e)); - - on("turn.complete", async ($, e, next) => { - const result = await next(e); - if (e.agentId !== undefined) return result; - const current = await read($, filling); - if (current === null) return result; - await update($, filling, () => null); - - const counts = (await read($, snapshot))?.sections[current.section]; - if (counts !== undefined) { - const delta = counts.decided - current.startDecided; - const change = - delta === 0 ? "no change" : `${delta > 0 ? "+" : ""}${delta}`; - $.ui.toast( - `${sectionLabel(current.section)}: ${counts.decided}/${counts.total} answered (${change} this turn)`, - ); - } - return result; - }); - - // The progress band, shown while a turn is recording answers. - on("ui.render", { component: "AbovePrompt" }, async ($, e, next) => { - if (e.props.hasSurvey || !e.props.isWorking) return next(e); - const current: Filling | null = await read($, filling); - if (current === null) return next(e); - const counts = (await read($, snapshot))?.sections[current.section]; - if (counts === undefined) return next(e); - - const { Box, Text } = $.ui.resolve(e); - const label = `Filling ${sectionLabel(current.section)} `; - const tail = ` ${counts.decided}/${counts.total} answered`; - const delta = counts.decided - current.startDecided; - const note = delta > 0 ? ` · +${delta} this turn` : ""; - const room = e.props.bodyColumns - label.length - tail.length - note.length; - const [filled, empty] = bar( - counts.decided, - counts.total, - Math.min(30, room), - ); - - return ( - - {label} - {filled} - {empty} - {tail} - {note} - - ); + await $.ui.open({ id: PANE, title: "Badge progress" }); + return { text: NOTICE }; }); on("ui.render", { component: "Pane", requestId: PANE }, async ($, e) => { - const { Box, Text } = $.ui.resolve(e); - const latest = await read($, snapshot); - if (latest === null) { - return ( - - No Badge Buddy results yet. They appear once Claude runs the badge - controller's status or apply command. - - ); - } - const current = await read($, filling); - const columns = e.props.bodyColumns; - const barWidth = Math.max(6, Math.min(30, columns - 22)); - - const started: [string, SectionCounts][] = []; - const notStarted: string[] = []; - for (const section of SECTIONS) { - const counts = latest.sections[section]; - if (counts === undefined) continue; - if ( - counts.decided > 0 || - section === current?.section || - section === "passing" - ) { - started.push([section, counts]); - } else { - notStarted.push(sectionLabel(section)); - } - } - - const heading = - latest.projectId !== null - ? `${latest.project ?? "Project"} · bestpractices.dev #${latest.projectId}` - : `${latest.project ?? "Project"} · not registered`; - - return ( - - {heading} - - Updated {clock(latest.at)} from {latest.source} - - - {started.map(([section, counts]) => { - const isActive = section === current?.section; - const [filled, empty] = bar(counts.decided, counts.total, barWidth); - return ( - - - - {isActive ? "▸ " : " "} - {pad(sectionLabel(section), 11)} - - {filled} - {empty} - - {" "} - {counts.decided}/{counts.total} - - - - {" "}Met {counts.met} · Unmet {counts.unmet} · N/A{" "} - {counts.notApplicable} · ? {counts.unknown} - - {counts.evidenceGaps > 0 && ( - - {" "} - {counts.evidenceGaps} answer - {counts.evidenceGaps === 1 ? "" : "s"} missing required - evidence - - )} - - ); - })} - {notStarted.length > 0 && ( - Not started: {notStarted.join(", ")} - )} - {latest.conflicts > 0 && ( - - {latest.conflicts} difference{latest.conflicts === 1 ? "" : "s"}{" "} - with the website to resolve - - )} - - ); + const { Text } = $.ui.resolve(e); + return {NOTICE}; }); }; diff --git a/plugins/badge-progress/tests/progress.test.tsx b/plugins/badge-progress/tests/progress.test.tsx index 26d3ee0..a77812c 100644 --- a/plugins/badge-progress/tests/progress.test.tsx +++ b/plugins/badge-progress/tests/progress.test.tsx @@ -1,62 +1,11 @@ -import { expect, mock, test } from "claude-code/testing"; +import { expect, test } from "claude-code/testing"; import type { On } from "claude-code"; -import { - controllerCommand, - parsePayload, - sectionArgument, -} from "../hooks/parse"; - -const CONTROLLER = '"/plugins/badge-buddy/scripts/ossf.py" --repo "/work/demo"'; - -// The shape ossf.py prints for status and apply (abridged). -function payload(passing: { decided: number; total: number }) { - return JSON.stringify({ - schema_version: 1, - state: "registered", - project: { name: "demo", project_id: 1234 }, - conflicts: [], - sections: { - passing: { - total: passing.total, - met: passing.decided - 2, - unmet: 1, - not_applicable: 1, - unknown: passing.total - passing.decided, - decided: passing.decided, - evidence_gaps: 1, - }, - silver: { - total: 55, - met: 0, - unmet: 0, - not_applicable: 0, - unknown: 55, - decided: 0, - evidence_gaps: 0, - }, - }, - }); -} - -// Stands for the engine beneath the plugin: Bash answers with `output`. -function engine(on: On, outputs: string[], toasts: string[] = []) { - mock.store(on); - mock.clock(on); - on("session.cwd", () => ({ value: "/work/demo" })); +function engine(on: On) { on("command.register", () => ({ value: { command: "badge-progress" } })); on("ui.open", () => ({ value: { isPlaced: true } })); - on("ui.toast", (_, e) => { - toasts.push(e.text); - return { value: undefined }; - }); on("session.start", (_, e) => ({ cwd: e.cwd })); - on("turn.complete", () => ({ text: "" })); - on("tool.call", () => ({ result: {}, text: outputs.shift() ?? "" })); - on("ui.render", ($, e) => { - const { Text } = $.ui.resolve(e); - return engine; - }); + on("tool.call", () => ({ result: {}, text: "legacy counts" })); } const PANE = { @@ -73,143 +22,28 @@ const PANE = { }, } as const; -const BAND = { - plugin: "badge-progress", - component: "AbovePrompt", - props: { - hasSurvey: false, - isWorking: true, - maxRows: 10, - bodyColumns: 80, - scroll: { offset: 0, bodyRows: 10 }, - view: {}, - }, -} as const; - -const TURN_END = { - answer: "", - durationMs: 1000, - isAborted: false, - turnId: "t1", - reason: "answer", -} as const; - -test("reads controller commands and their output", async () => { - expect(controllerCommand(`${CONTROLLER} status`)).toBe("status"); - expect( - controllerCommand( - `${CONTROLLER} apply --section silver --input - <<'JSON'\n{}\nJSON`, - ), - ).toBe("apply"); - expect(controllerCommand(`${CONTROLLER} review --section passing`)).toBe( - "other", - ); - expect(controllerCommand("python3 other.py status")).toBe(null); - expect( - sectionArgument(`${CONTROLLER} apply --section baseline-2 --input -`), - ).toBe("baseline-2"); - expect( - sectionArgument(`${CONTROLLER} apply --input - <<'X'\n--section gold\nX`), - ).toBe(null); - - const parsed = parsePayload( - `warning: board refresh failed\n${payload({ decided: 40, total: 67 })}`, - "status", - 0, - ); - expect(parsed?.sections.passing?.decided).toBe(40); - expect(parsed?.projectId).toBe(1234); - expect(parsePayload("not json", "status", 0)).toBe(null); - expect(parsePayload('{"sections": {}}', "status", 0)).toBe(null); -}); - -test("the pane shows the counts the controller reported, on every surface", async ($, on) => { - engine(on, [payload({ decided: 40, total: 67 })]); - await $.session.start({ - cwd: "/work/demo", - surface: "terminal", - isInteractive: true, +test("shows the migration notice instead of persisted controller counts", async ($, on) => { + engine(on); + let reads = 0; + on("store.get", () => { + reads += 1; + return { value: { project: "stale project", sections: { passing: { decided: 67, total: 67 } } } }; }); - await $.tool.call({ tool: "Bash", command: `${CONTROLLER} status` }); - + await $.session.start({ cwd: "/work/demo", surface: "terminal", isInteractive: true }); for (const surface of ["terminal", "desktop", "vscode", "mobile"] as const) { const ui = await $.ui.mount({ ...PANE, surface }); - expect((await ui.find({ type: "Text", text: /#1234/ }))?.text).toContain( - "demo", - ); - expect(await ui.find({ type: "Text", text: /40\/67/ })).toBeDefined(); - expect( - await ui.find({ type: "Text", text: /missing required evidence/ }), - ).toBeDefined(); - expect( - await ui.find({ type: "Text", text: /Not started: Silver/ }), - ).toBeDefined(); + expect(await ui.find({ type: "Text", text: /tracking is paused/ })).toBeDefined(); + expect(await ui.find({ type: "Text", text: /stale project/ })).toBeUndefined(); await ui.unmount(); } + expect(reads).toBe(0); }); -test("the band tracks a turn of apply calls, then a toast sums it up", async ($, on) => { - const toasts: string[] = []; - engine( - on, - [ - payload({ decided: 40, total: 67 }), - payload({ decided: 43, total: 67 }), - payload({ decided: 45, total: 67 }), - ], - toasts, - ); - await $.session.start({ - cwd: "/work/demo", - surface: "terminal", - isInteractive: true, - }); - await $.tool.call({ tool: "Bash", command: `${CONTROLLER} status` }); - await $.tool.call({ - tool: "Bash", - command: `${CONTROLLER} apply --section passing --input -`, - }); - await $.tool.call({ - tool: "Bash", - command: `${CONTROLLER} apply --section passing --input -`, - }); - - const band = await $.ui.mount({ ...BAND, surface: "terminal" }); - expect( - await band.find({ type: "Text", text: /Filling Passing/ }), - ).toBeDefined(); - expect( - await band.find({ type: "Text", text: /45\/67 answered/ }), - ).toBeDefined(); - expect( - await band.find({ type: "Text", text: /\+5 this turn/ }), - ).toBeDefined(); - await band.unmount(); - - await $.turn.complete(TURN_END); - expect(toasts).toEqual(["Passing: 45/67 answered (+5 this turn)"]); - - const after = await $.ui.mount({ ...BAND, surface: "terminal" }); - expect(await after.find({ type: "Text", text: /Filling/ })).toBeUndefined(); - expect(await after.find({ type: "Text", text: /engine/ })).toBeDefined(); - await after.unmount(); -}); - -test("other commands and failed calls leave the counts alone", async ($, on) => { - engine(on, [ - '{"sections": {"passing": {"total": 1}}}', - payload({ decided: 1, total: 67 }), - ]); - await $.session.start({ - cwd: "/work/demo", - surface: "terminal", - isInteractive: true, - }); - await $.tool.call({ tool: "Bash", command: "cat sections.json" }); - - const ui = await $.ui.mount({ ...PANE, surface: "desktop" }); - expect( - await ui.find({ type: "Text", text: /No Badge Buddy results yet/ }), - ).toBeDefined(); +test("ordinary tools do not reopen legacy tracking", async ($, on) => { + engine(on); + await $.session.start({ cwd: "/work/demo", surface: "terminal", isInteractive: true }); + await $.tool.call({ tool: "Bash", command: "echo legacy" }); + const ui = await $.ui.mount({ ...PANE, surface: "terminal" }); + expect(await ui.find({ type: "Text", text: /local preview board/ })).toBeDefined(); await ui.unmount(); }); diff --git a/plugins/badge-progress/types/index.d.ts b/plugins/badge-progress/types/index.d.ts deleted file mode 100644 index aeeb80b..0000000 --- a/plugins/badge-progress/types/index.d.ts +++ /dev/null @@ -1,36 +0,0 @@ -export type SectionCounts = { - total: number; - met: number; - unmet: number; - notApplicable: number; - unknown: number; - decided: number; - evidenceGaps: number; -}; - -/** The latest per-section counts Badge Buddy's controller reported. */ -export type Snapshot = { - project: string | null; - projectId: number | null; - sections: Record; - conflicts: number; - source: "status" | "apply"; - at: number; -}; - -/** A section Claude is recording answers for during the current turn. */ -export type Filling = { - section: string; - startDecided: number; - applies: number; -}; - -declare module "claude-code" { - interface PluginState { - "badge-progress": { - snapshot: Shaped; - filling: Shaped; - autoOpened: boolean; - }; - } -} diff --git a/tests/badge-buddy/test_baseline_aliases.py b/tests/badge-buddy/test_baseline_aliases.py index 42b4744..96082c9 100644 --- a/tests/badge-buddy/test_baseline_aliases.py +++ b/tests/badge-buddy/test_baseline_aliases.py @@ -1,265 +1,42 @@ -"""Regression checks for preserving answers across Baseline field spellings.""" +"""Keep Baseline display-ID imports compatible with the passive preview board.""" -import contextlib -from io import StringIO -import json from pathlib import Path -import subprocess import sys -import tempfile import unittest -from unittest.mock import Mock -from urllib.parse import parse_qs, urlsplit - -SCRIPTS = Path(__file__).resolve().parents[2] / "plugins/badge-buddy/scripts" -sys.path.insert(0, str(SCRIPTS)) - -import ossf +sys.path.insert( + 0, str(Path(__file__).resolve().parents[2] / "plugins/badge-buddy/scripts") +) from ossf_review.board import build_board_payload from ossf_review.criteria import CriteriaCatalog -from ossf_review.storage import DataStore -from ossf_review.submission import build_fill_script, build_proposal_urls -from ossf_review.sync import synchronize_project - - -DISPLAY = "OSPS-AC-01.01" -CANONICAL = "osps_ac_01_01" -REMOTE = "https://github.com/example/project" +from ossf_review.fields import normalize_assessment_fields class BaselineAliasesTest(unittest.TestCase): - def setUp(self): - directory = tempfile.TemporaryDirectory() - self.addCleanup(directory.cleanup) - self.root = Path(directory.name) - self.repo = self.root / "repo" - subprocess.run( - ["git", "init", "-q", str(self.repo)], check=True, capture_output=True - ) - subprocess.run( - ["git", "-C", str(self.repo), "remote", "add", "origin", REMOTE], - check=True, - capture_output=True, - ) - self.store = DataStore(self.root / "data") - self.store.register_project("31", REMOTE) - self.catalog = CriteriaCatalog() - - def seed(self, document, *, repository_backed=False): - # Model existing files, including ones saved before normalization existed. - path = ( - self.root / "working.json" - if repository_backed - else self.root / "data/projects/31/.bestpractices.json" - ) - path.write_text(json.dumps(document)) - if repository_backed: - self.store.use_assessment_file(path) - return path - - def client(self, fields): - return Mock( - fetch_project=Mock(return_value={"id": 31, "repo_url": REMOTE, **fields}) - ) - - def test_refresh_preserves_display_answers_and_reports_canonical_conflicts(self): - for repository_backed in (False, True): - with self.subTest(repository_backed=repository_backed): - local = { - f"{DISPLAY}_status": "Unmet", - f"{DISPLAY}_justification": "Deliberate local answer", - "name": "Keep metadata", - } - path = self.seed(local, repository_backed=repository_backed) - result = synchronize_project( - self.store, - self.repo, - project_id="31", - client=self.client( - { - f"{DISPLAY}_status": "Met", - f"{DISPLAY}_justification": "Website answer", - } - ), - ) - self.assertEqual("Unmet", result.assessment[f"{CANONICAL}_status"]) - self.assertEqual( - "Deliberate local answer", - result.assessment[f"{CANONICAL}_justification"], + def test_display_and_canonical_fields_render_identically(self): + catalog = CriteriaCatalog() + for level in ("baseline-1", "baseline-2", "baseline-3"): + criterion = catalog.section(level)[0] + canonical = { + f"{criterion.id}_status": "Met", + f"{criterion.id}_justification": "Project explanation", + } + display = { + f"{criterion.display_id}_status": "Met", + f"{criterion.display_id}_justification": "Project explanation", + } + with self.subTest(level=level): + self.assertEqual(canonical, normalize_assessment_fields(display)) + board = build_board_payload( + display, project_id="31", section=level, catalog=catalog ) - self.assertEqual("Keep metadata", result.assessment["name"]) self.assertEqual( - {f"{CANONICAL}_status", f"{CANONICAL}_justification"}, - {item.field for item in result.conflicts}, + {"status": "Met", "justification": "Project explanation"}, + board["answers"][criterion.id], ) - self.assertEqual(result.assessment, json.loads(path.read_text())) - self.assertNotIn(f"{DISPLAY}_status", result.assessment) - - def test_unknown_and_empty_wording_are_not_initialized_from_website(self): - self.seed({f"{DISPLAY}_status": "?", f"{DISPLAY}_justification": ""}) - result = synchronize_project( - self.store, - self.repo, - client=self.client( - { - f"{CANONICAL}_status": "Met", - f"{CANONICAL}_justification": "Website answer", - } - ), - ) - self.assertEqual( - {f"{CANONICAL}_status": "?", f"{CANONICAL}_justification": ""}, - result.assessment, - ) - self.assertEqual(2, len(result.conflicts)) - def test_justification_only_apply_cannot_clear_required_na_wording(self): - path = self.seed( - { - f"{DISPLAY}_status": "N/A", - f"{DISPLAY}_justification": "Not applicable here", - }, - repository_backed=True, - ) - output, errors = StringIO(), StringIO() - with contextlib.redirect_stdout(output), contextlib.redirect_stderr(errors): - code = ossf.main( - [ - "--repo", - str(self.repo), - "--data-dir", - str(self.root / "data"), - "--assessment-file", - str(path), - "apply", - "--section", - "baseline-1", - "--json", - json.dumps({f"{CANONICAL}_justification": ""}), - ] + def test_conflicting_aliases_are_not_silently_chosen(self): + with self.assertRaises(ValueError): + normalize_assessment_fields( + {"OSPS-AC-01.01_status": "Met", "osps_ac_01_01_status": "?"} ) - self.assertNotEqual(0, code) - self.assertIn("requires an N/A justification", errors.getvalue()) - self.assertEqual( - "Not applicable here", - self.store.load_assessment("31")[f"{CANONICAL}_justification"], - ) - - def test_canonical_update_replaces_display_answer_without_resurrecting_it(self): - path = self.seed( - {f"{DISPLAY}_status": "Unmet", f"{DISPLAY}_justification": "Old wording"} - ) - result = self.store.update_assessment( - "31", {f"{CANONICAL}_status": "?", f"{CANONICAL}_justification": ""} - ) - expected = {f"{CANONICAL}_status": "?", f"{CANONICAL}_justification": ""} - self.assertEqual(expected, result) - self.assertEqual(expected, json.loads(path.read_text())) - - def test_conflicting_aliases_fail_without_overwriting_input_in_either_order(self): - pairs = [(f"{DISPLAY}_status", "Unmet"), (f"{CANONICAL}_status", "Met")] - for entries in (pairs, list(reversed(pairs))): - with self.subTest(entries=entries): - path = self.seed(dict(entries)) - before = path.read_bytes() - with self.assertRaisesRegex(ValueError, "conflicting aliases"): - synchronize_project(self.store, self.repo, client=self.client({})) - self.assertEqual(before, path.read_bytes()) - with self.assertRaisesRegex(ValueError, "conflicting aliases"): - self.catalog.classify_flat(dict(entries)) - - def test_conflicting_website_aliases_leave_assessment_and_snapshot_unchanged(self): - path = self.seed({f"{CANONICAL}_status": "Unmet"}) - snapshot = self.store.save_public_snapshot( - "31", REMOTE, {f"{CANONICAL}_status": "Unmet"} - ) - before = path.read_bytes() - with self.assertRaisesRegex(ValueError, "conflicting aliases"): - synchronize_project( - self.store, - self.repo, - client=self.client( - { - f"{DISPLAY}_status": "Unmet", - f"{CANONICAL}_status": "Met", - } - ), - ) - self.assertEqual(before, path.read_bytes()) - self.assertEqual(snapshot, self.store.load_public_snapshot("31", REMOTE)) - - def test_equal_aliases_collapse_and_metadata_survives(self): - self.seed( - { - f"{DISPLAY}_status": "Met", - f"{CANONICAL}_status": "Met", - "custom": {"keep": True}, - } - ) - result = self.store.transform_assessment("31", lambda current: current) - self.assertEqual( - {f"{CANONICAL}_status": "Met", "custom": {"keep": True}}, result - ) - - def test_local_draft_handoff_recognizes_same_answer_across_aliases(self): - record = self.store.create_unregistered(self.repo, remote=REMOTE) - draft_path = ( - self.root - / "data/unregistered" - / record["storage_key"] - / ".bestpractices.json" - ) - draft_path.write_text( - json.dumps( - { - f"{DISPLAY}_status": "Unmet", - f"{DISPLAY}_justification": "Local draft", - } - ) - ) - self.seed( - { - f"{CANONICAL}_status": "Met", - f"{CANONICAL}_justification": "Registered answer", - } - ) - assessment, conflicts = self.store.handoff_unregistered(self.repo, "31") - self.assertEqual("Met", assessment[f"{CANONICAL}_status"]) - self.assertIn(f"{CANONICAL}_status", conflicts) - self.assertEqual( - "Unmet", json.loads(draft_path.read_text())[f"{CANONICAL}_status"] - ) - - def test_display_answers_use_canonical_fields_in_both_transfer_methods_and_board( - self, - ): - document = { - f"{DISPLAY}_status": "Met", - f"{DISPLAY}_justification": "MFA enabled", - } - plan = build_proposal_urls( - document, self.catalog, section="baseline-1", project_id="31" - ) - self.assertEqual( - { - f"{CANONICAL}_status": ["Met"], - f"{CANONICAL}_justification": ["MFA enabled"], - }, - parse_qs(urlsplit(plan.urls[0]).query), - ) - script, ids = build_fill_script(document, self.catalog, section="baseline-1") - self.assertEqual((CANONICAL,), ids) - self.assertIn(f'"{CANONICAL}"', script) - self.assertNotIn(DISPLAY, script) - board = build_board_payload( - document, project_id="31", section="baseline-1", catalog=self.catalog - ) - self.assertEqual( - {"status": "Met", "justification": "MFA enabled"}, - board["answers"][CANONICAL], - ) - - -if __name__ == "__main__": - unittest.main() diff --git a/tests/badge-buddy/test_documentation_integrity.py b/tests/badge-buddy/test_documentation_integrity.py index b2bed68..7eb5d1b 100644 --- a/tests/badge-buddy/test_documentation_integrity.py +++ b/tests/badge-buddy/test_documentation_integrity.py @@ -4,19 +4,16 @@ from pathlib import Path import json -import os import re import shlex -import shutil -import subprocess import sys -import tempfile import unittest PLUGIN_ROOT = Path(__file__).resolve().parents[2] / "plugins" / "badge-buddy" SKILLS_ROOT = PLUGIN_ROOT / "skills" + class DocumentationIntegrityTest(unittest.TestCase): def test_raw_references_do_not_require_claude_substitution(self) -> None: for path in SKILLS_ROOT.glob("*/references/**/*.md"): @@ -48,54 +45,30 @@ def test_scorecard_documented_commands_parse(self) -> None: with self.subTest(path=path.name, command=line): parser.parse_args(shlex.split(line)[1:]) - def test_documented_status_works_without_claude_shell_variables(self) -> None: - with tempfile.TemporaryDirectory(prefix="badge paths ") as directory: - root = Path(directory) - installed = root / "plugin cache" / "badge-buddy" / "test version" - shutil.copytree(PLUGIN_ROOT, installed, ignore=shutil.ignore_patterns("__pycache__")) - repository = root / "user project" - data_dir = root / "private plugin data" - subprocess.run(["git", "init", "-q", str(repository)], check=True, capture_output=True) - subprocess.run( - ["git", "-C", str(repository), "remote", "add", "origin", "https://github.com/example/review.git"], - check=True, capture_output=True, - ) - # Seed the association from a prior online session without network access. - data_dir.mkdir() - (data_dir / "registry.json").write_text(json.dumps({ - "schema_version": 1, - "by_id": {"31": "github.com/example/review"}, - "by_remote": {"github.com/example/review": "31"}, - "unregistered": {}, - })) - skill = installed / "skills/ossf-bp-badges/SKILL.md" - # Model the documented host substitution in SKILL.md only. The - # subsequent reference read and Bash process get no such expansion. - rendered = skill.read_text().replace("${CLAUDE_PLUGIN_DATA}", str(data_dir)) - controller_link = re.search(r"\[the controller\]\(([^)]+)\)", rendered) - self.assertIsNotNone(controller_link) - controller = (skill.parent / controller_link[1]).resolve() - status_line = next(line for line in rendered.splitlines() if line.startswith('""')) - reference = skill.parent / "references/application.md" - reference_line = next(line for line in reference.read_text().splitlines() if line.startswith('""')) - environment = {key: value for key, value in os.environ.items() if not key.startswith("CLAUDE_")} - # Run the entrypoint, then resume using the raw reference template. - for line in (status_line, reference_line): - substitutions = { - "": str(controller), - "": str(repository), - "": str(data_dir), - } - arguments = [substitutions.get(arg, arg) for arg in shlex.split(line)] - command = shlex.join([*arguments, "--project-id", "31", "--offline"]) - result = subprocess.run( - ["bash", "-c", command], cwd=repository, env=environment, - capture_output=True, text=True, check=True, - ) - self.assertEqual("registered", json.loads(result.stdout)["state"]) - self.assertTrue((data_dir / "registry.json").is_file()) - self.assertFalse((repository / "registry.json").exists()) - self.assertFalse((installed / "registry.json").exists()) + def test_registered_mcp_is_pinned_and_uses_stdio(self) -> None: + config = json.loads((PLUGIN_ROOT / ".mcp.json").read_text()) + server = config["mcpServers"]["bestpractices"] + self.assertEqual("uvx", server["command"]) + self.assertEqual( + ["--from", "best-practices-mcp==0.5.0", "bestpractices-mcp"], server["args"] + ) + self.assertNotIn("env", server) + + def test_board_documented_command_parses(self) -> None: + scripts = str(PLUGIN_ROOT / "scripts") + sys.path.insert(0, scripts) + self.addCleanup(sys.path.remove, scripts) + import review_board + + guide = SKILLS_ROOT / "ossf-bp-badges/references/application.md" + example = next( + line + for line in guide.read_text().splitlines() + if line.startswith('python3 ""') + ) + args = review_board.build_parser().parse_args(shlex.split(example)[2:]) + self.assertEqual("baseline-1", args.section) + self.assertEqual("all", args.view) if __name__ == "__main__": diff --git a/tests/badge-buddy/test_ossf_cli.py b/tests/badge-buddy/test_ossf_cli.py deleted file mode 100644 index b06efbd..0000000 --- a/tests/badge-buddy/test_ossf_cli.py +++ /dev/null @@ -1,1819 +0,0 @@ -"""Tests for the shared OpenSSF plugin command boundary.""" - -from __future__ import annotations - -import contextlib -from io import StringIO -import json -import os -from pathlib import Path -import subprocess -import sys -import tempfile -import unittest -from unittest.mock import patch -from urllib.parse import parse_qs, unquote, urlparse - - -REPOSITORY_ROOT = Path(__file__).resolve().parents[2] / "plugins" / "badge-buddy" -sys.path.insert(0, str(REPOSITORY_ROOT / "scripts")) - -import ossf # noqa: E402 -from ossf_review.criteria import CriteriaCatalog # noqa: E402 -from ossf_review.storage import DataStore # noqa: E402 -from ossf_review.submission import ( # noqa: E402 - build_fill_script, - build_proposal_urls, - validate_base_url, - wording_only_criteria, -) -from spec_pins import EXPECTED_SECTION_TOTALS # noqa: E402 - - -class MissingProjectClient: - def lookup_project_id(self, remote: str) -> None: - self.remote = remote - return None - - -class PublicProjectClient: - """Serve a canned public project document for synchronization.""" - - def __init__(self, document: dict[str, object]) -> None: - document.setdefault("repo_url", "https://github.com/example/review") - self.document = document - - def lookup_project_id(self, remote: str) -> str: - return "31" - - def fetch_project(self, project_id: object) -> dict[str, object]: - return dict(self.document) - - -class OssfCommandTest(unittest.TestCase): - def setUp(self) -> None: - self.temporary_directory = tempfile.TemporaryDirectory() - self.addCleanup(self.temporary_directory.cleanup) - self.root = Path(self.temporary_directory.name) - self.repository = self.root / "repo" - self.data_dir = self.root / "plugin-data" - subprocess.run( - ["git", "init", "-q", str(self.repository)], - check=True, - capture_output=True, - ) - subprocess.run( - [ - "git", - "-C", - str(self.repository), - "remote", - "add", - "origin", - "https://github.com/example/review.git", - ], - check=True, - capture_output=True, - ) - - def run_command( - self, - *arguments: str, - client_factory=MissingProjectClient, - stdin: str | None = None, - browser_open=None, - ) -> tuple[int, str, str]: - stdout = StringIO() - stderr = StringIO() - input_stream = StringIO(stdin) if stdin is not None else None - stdin_context = ( - patch.object(sys, "stdin", input_stream) - if input_stream is not None - else contextlib.nullcontext() - ) - with ( - contextlib.redirect_stdout(stdout), - contextlib.redirect_stderr(stderr), - stdin_context, - ): - result = ossf.main( - [ - "--repo", - str(self.repository), - "--data-dir", - str(self.data_dir), - *arguments, - ], - client_factory=client_factory, - **({"browser_open": browser_open} if browser_open is not None else {}), - ) - return result, stdout.getvalue(), stderr.getvalue() - - def register_verified_project(self) -> None: - """Seed the association established by a prior successful online status.""" - DataStore(self.data_dir).register_project("31", "github.com/example/review") - - def test_session_commands_use_saved_snapshot_without_network(self) -> None: - document = { - "repo_url": "https://github.com/example/review", - "description_good_status": "Met", - "description_good_justification": "Original description.", - } - client = PublicProjectClient(document) - with patch.object(client, "fetch_project", wraps=client.fetch_project) as fetch: - code, stdout, error = self.run_command("status", client_factory=lambda: client) - self.assertEqual((0, ""), (code, error)) - fetch.assert_called_once_with("31") - initial = json.loads(stdout) - baseline = initial["sources"]["public_snapshot"] - self.assertEqual("live", baseline["source"]) - self.assertIsNotNone(baseline["fetched_at"]) - updates = {"description_good_justification": "Revised description."} - commands = ( - ("apply", "--section", "passing", "--json", json.dumps(updates)), - ("review", "--no-browser"), - ("export", "--output", str(self.root / "export.json")), - ("propose", "--section", "passing"), - ("fill-script", "--section", "passing", "--output", str(self.root / "fill.js")), - ) - def no_client(): - self.fail("Only status should create a network client") - # Each command constructs a new DataStore, as separate CLI processes do. - for command in commands: - with self.subTest(command=command[0]): - code, stdout, error = self.run_command(*command, client_factory=no_client) - self.assertEqual((0, ""), (code, error)) - payload = json.loads(stdout) - self.assertEqual([], payload["conflicts"]) - if command[0] == "apply": - cached = payload["sources"]["public_snapshot"] - elif command[0] in ("propose", "fill-script"): - cached = payload["public_snapshot"] - else: - continue - self.assertEqual({**baseline, "source": "cached"}, cached) - self.assertEqual(["description_good"], payload["criteria"]) - self.assertEqual("Revised description.", json.loads( - (self.root / "export.json").read_text() - )["description_good_justification"]) - - document["description_good_justification"] = "Updated on the website." - code, stdout, error = self.run_command("status", client_factory=lambda: client) - self.assertEqual((0, ""), (code, error)) - refreshed = json.loads(stdout) - self.assertEqual("Revised description.", refreshed["assessment"][ - "description_good_justification" - ]) - self.assertEqual("Updated on the website.", refreshed["conflicts"][0]["incoming"]) - self.assertEqual("live", refreshed["sources"]["public_snapshot"]["source"]) - snapshot = DataStore(self.data_dir).load_public_snapshot( - "31", "https://github.com/example/review" - ) - self.assertEqual(document, snapshot["document"]) - - def test_local_registry_miss_requests_status_without_network(self) -> None: - def no_client(): - self.fail("Local commands must not look up a project") - code, stdout, error = self.run_command( - "apply", "--section", "passing", "--json", "{}", client_factory=no_client, - ) - self.assertEqual((3, ""), (code, error)) - payload = json.loads(stdout) - self.assertEqual("registry_miss", payload["state"]) - self.assertIn("Run status", payload["next_step"]) - - def test_explicit_offline_id_cannot_establish_a_repository_association(self) -> None: - code, stdout, error = self.run_command("status", "--offline", "--project-id", "31") - self.assertEqual((2, ""), (code, stdout)) - self.assertIn("run status online", error) - self.assertIsNone(DataStore(self.data_dir).resolve_project_id("github.com/example/review")) - self.assertEqual([], list(self.data_dir.rglob(".bestpractices.json"))) - - def test_local_commands_cannot_rebind_a_verified_project(self) -> None: - self.register_verified_project() - store = DataStore(self.data_dir) - store.register_project("32", "github.com/example/other") - store.save_assessment("32", {"description_good_status": "Met"}) - before = {path: path.read_bytes() for path in self.data_dir.rglob("*.json")} - output = self.root / "should-not-exist.json" - commands = ( - ("status", "--offline"), - ("apply", "--section", "passing", "--json", '{"description_good_status":"Unmet"}'), - ("review", "--no-browser"), - ("export", "--output", str(output)), - ("propose", "--section", "passing"), - ("fill-script", "--section", "passing", "--all", "--output", str(output)), - ) - for command in commands: - with self.subTest(command=command[0]): - code, stdout, error = self.run_command( - *command, "--project-id", "32", - client_factory=lambda: self.fail("local commands must not access the network"), - ) - self.assertEqual((2, ""), (code, stdout)) - self.assertIn("run status online", error) - self.assertEqual(before, { - path: path.read_bytes() for path in self.data_dir.rglob("*.json") - }) - self.assertFalse(output.exists()) - - def test_status_is_machine_readable_and_does_not_expose_private_paths(self) -> None: - self.register_verified_project() - result, stdout, stderr = self.run_command( - "status", - "--project-id", - "31", - "--offline", - ) - - payload = json.loads(stdout) - self.assertEqual(0, result) - self.assertEqual("", stderr) - self.assertEqual("registered", payload["state"]) - self.assertEqual("31", payload["project"]["project_id"]) - self.assertEqual( - EXPECTED_SECTION_TOTALS["passing"], - payload["sections"]["passing"]["total"], - ) - self.assertEqual( - EXPECTED_SECTION_TOTALS["passing"], - payload["sections"]["passing"]["unknown"], - ) - self.assertEqual({}, payload["assessment"]) - self.assertNotIn(str(self.data_dir), stdout) - self.assertNotIn(str(self.repository), stdout) - - def test_environment_paths_support_installed_plugin_invocation(self) -> None: - self.register_verified_project() - with patch.dict( - os.environ, - { - "CLAUDE_PLUGIN_DATA": str(self.data_dir), - "CLAUDE_PROJECT_DIR": str(self.repository), - }, - clear=False, - ): - stdout = StringIO() - with contextlib.redirect_stdout(stdout): - result = ossf.main(["status", "--project-id", "31", "--offline"]) - - self.assertEqual(0, result) - self.assertEqual("31", json.loads(stdout.getvalue())["project"]["project_id"]) - - def test_missing_plugin_data_fails_instead_of_creating_a_second_store(self) -> None: - with patch.dict(os.environ, {}, clear=True): - stderr = StringIO() - with contextlib.redirect_stderr(stderr): - result = ossf.main( - [ - "--repo", - str(self.repository), - "status", - "--project-id", - "31", - "--offline", - ] - ) - - self.assertEqual(2, result) - self.assertIn("CLAUDE_PLUGIN_DATA is unavailable", stderr.getvalue()) - - def test_registry_miss_reports_registration_without_creating_a_sidecar( - self, - ) -> None: - client = MissingProjectClient() - result, stdout, stderr = self.run_command( - "status", - client_factory=lambda: client, - ) - - payload = json.loads(stdout) - self.assertEqual(0, result) - self.assertEqual("", stderr) - self.assertEqual("registration_required", payload["state"]) - self.assertEqual( - "github.com/example/review", - payload["project"]["remote"], - ) - self.assertEqual(ossf.REGISTRATION_URL, payload["registration_url"]) - self.assertFalse((self.data_dir / "unregistered").exists()) - - def test_offline_registry_miss_is_not_claimed_as_absent_registration(self) -> None: - result, stdout, _stderr = self.run_command("status", "--offline") - - self.assertEqual(0, result) - self.assertEqual("registry_miss", json.loads(stdout)["state"]) - - def test_unregistered_sidecar_requires_explicit_command_opt_in(self) -> None: - result, stdout, stderr = self.run_command( - "status", - "--allow-unregistered", - client_factory=MissingProjectClient, - ) - - payload = json.loads(stdout) - self.assertEqual(0, result) - self.assertEqual("", stderr) - self.assertEqual("unregistered", payload["state"]) - self.assertIsNone(payload["project"]["project_id"]) - self.assertTrue((self.data_dir / "unregistered").is_dir()) - - def test_local_handoff_conflicts_are_resolved_by_explicit_apply(self) -> None: - draft_answer = { - "description_good_status": "Met", - "description_good_justification": "Local description evidence.", - } - for chosen_status, include_justification in (("Met", False), ("Met", True), ("Unmet", True)): - with self.subTest(chosen_status=chosen_status, include_justification=include_justification): - store = DataStore(self.data_dir) - store.create_unregistered(self.repository, remote="github.com/example/review") - local_id = store.unregistered_identifier(self.repository) - store.save_assessment(local_id, { - **draft_answer, - "contribution_status": "?", - "contribution_justification": "Unfinished contribution notes.", - }) - store.register_project("31", "github.com/example/review") - store.save_assessment("31", {"description_good_status": "Unmet"}) - code, stdout, stderr = self.run_command("status", "--offline") - self.assertEqual(0, code, stderr) - result = json.loads(stdout) - self.assertEqual("Unmet", result["assessment"]["description_good_status"]) - self.assertNotIn("description_good_justification", result["assessment"]) - self.assertEqual("Unfinished contribution notes.", - result["assessment"]["contribution_justification"]) - self.assertEqual(draft_answer, store.load_assessment(local_id)) - self.assertEqual({ - ("description_good_status", "Unmet", "Met", "local_draft"), - ("description_good_justification", None, "Local description evidence.", "local_draft"), - }, {(c["field"], c["preserved"], c["incoming"], c["source"]) - for c in result["conflicts"]}) - selected = {"description_good_status": chosen_status} - if include_justification: - selected["description_good_justification"] = "User-selected explanation." - code, stdout, stderr = self.run_command( - "apply", "--section", "passing", "--offline", "--json", json.dumps(selected), - ) - self.assertEqual(0, code, stderr) - self.assertEqual([], json.loads(stdout)["conflicts"]) - self.assertIsNone(store.load_unregistered(self.repository)) - self.assertEqual({}, store.load_assessment(local_id)) - code, stdout, stderr = self.run_command("status", "--offline") - self.assertEqual(0, code, stderr) - result = json.loads(stdout) - self.assertEqual([], result["conflicts"]) - for field, value in selected.items(): - self.assertEqual(value, result["assessment"][field]) - - # When statuses agree, choosing the registered justification alone - # resolves the disagreement; repeating the status is unnecessary. - store.create_unregistered(self.repository, remote="github.com/example/review") - local_id = store.unregistered_identifier(self.repository) - store.save_assessment(local_id, { - "description_good_status": "Unmet", - "description_good_justification": "Different local explanation.", - }) - code, stdout, stderr = self.run_command( - "apply", "--section", "passing", "--offline", "--json", - json.dumps({"description_good_justification": "User-selected explanation."}), - ) - self.assertEqual(0, code, stderr) - self.assertEqual([], json.loads(stdout)["conflicts"]) - self.assertIsNone(store.load_unregistered(self.repository)) - self.assertEqual({}, store.load_assessment(local_id)) - - def test_selected_file_drives_updates_and_outputs_without_a_private_answer_copy(self) -> None: - repository_file = self.repository / ".bestpractices.json" - original = {"description_good_status": "Unmet", "interact_status": "N/A"} - repository_file.write_text(json.dumps(original)) - repository_file.chmod(0o644) - original_bytes = repository_file.read_bytes() - working = self.root / "working.json" - working.write_bytes(original_bytes) - prefix = ("--assessment-file", str(working)) - code, _, error = self.run_command(*prefix, "status", "--allow-unregistered", "--offline") - self.assertEqual((0, ""), (code, error)) - self.assertEqual([], list(self.data_dir.rglob(".bestpractices.json"))) - code, _, error = self.run_command( - *prefix, "status", "--project-id", "31", - client_factory=lambda: PublicProjectClient({}), - ) - self.assertEqual((0, ""), (code, error)) - code, stdout, error = self.run_command( - *prefix, "review", "--section", "passing", "--project-id", "31", - "--view", "all", "--offline", "--no-browser", - ) - self.assertEqual((0, ""), (code, error)) - board_url = urlparse(json.loads(stdout)["url"]) - self.assertEqual("view=all", board_url.fragment) - board_path = Path(unquote(board_url.path)) - self.addCleanup(board_path.unlink, missing_ok=True) - self.assertIn('"description_good":{"status":"Unmet"', board_path.read_text()) - self.assertEqual(original_bytes, repository_file.read_bytes()) - self.assertEqual([], list(self.data_dir.rglob(".bestpractices.json"))) - code, stdout, error = self.run_command( - *prefix, "apply", "--section", "passing", "--offline", "--json", - json.dumps({"description_good_status": "Met"}), - ) - self.assertEqual((0, ""), (code, error)) - expected = {**original, "description_good_status": "Met"} - self.assertEqual(expected, json.loads(stdout)["assessment"]) - self.assertEqual(expected, json.loads(working.read_text())) - self.assertIn('"description_good":{"status":"Met"', board_path.read_text()) - - exported = self.root / "export.json" - script = self.root / "fill.js" - for command in (("status",), ("export", "--output", str(exported)), - ("propose", "--section", "passing"), - ("fill-script", "--section", "passing", "--all", "--output", str(script))): - with self.subTest(command=command[0]): - code, stdout, error = self.run_command(*prefix, *command, "--offline") - self.assertEqual((0, ""), (code, error)) - payload = json.loads(stdout) - if command[0] == "status": - self.assertEqual(expected, payload["assessment"]) - elif command[0] == "propose": - query = parse_qs(urlparse(payload["urls"][0]).query) - self.assertEqual(["Met"], query["description_good_status"]) - self.assertEqual(expected, json.loads(exported.read_text())) - answers, _ = json.JSONDecoder().raw_decode(script.read_text().split("const answers = ", 1)[1]) - self.assertEqual("Met", answers["description_good"]["status"]) - self.assertEqual(original_bytes, repository_file.read_bytes()) - self.assertEqual([], list(self.data_dir.rglob(".bestpractices.json"))) - - # Supplying the repository path explicitly supports authorized direct edits. - code, _, error = self.run_command( - "--assessment-file", str(repository_file), "apply", "--section", "passing", - "--offline", "--json", json.dumps({"description_good_status": "Met"}), - ) - self.assertEqual((0, ""), (code, error)) - self.assertEqual(expected, json.loads(repository_file.read_text())) - self.assertEqual(0o644, repository_file.stat().st_mode & 0o777) - self.assertEqual([], list(self.data_dir.rglob(".bestpractices.json"))) - - def test_apply_reads_stdin_and_normalizes_baseline_display_fields(self) -> None: - self.register_verified_project() - result, stdout, stderr = self.run_command( - "apply", - "--section", - "baseline-1", - "--project-id", - "31", - "--offline", - "--input", - "-", - stdin=json.dumps({"OSPS-AC-01.01_status": "Unmet"}), - ) - - assessment = json.loads(stdout)["assessment"] - self.assertEqual(0, result) - self.assertEqual("", stderr) - self.assertEqual("Unmet", assessment["osps_ac_01_01_status"]) - self.assertNotIn("OSPS-AC-01.01_status", assessment) - - def test_apply_rejects_unknown_fields_and_missing_required_evidence(self) -> None: - self.register_verified_project() - result, _stdout, stderr = self.run_command( - "apply", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--json", - json.dumps({"invented_status": "Met"}), - ) - self.assertEqual(2, result) - self.assertIn("unknown assessment field", stderr) - - result, _stdout, stderr = self.run_command( - "apply", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--json", - json.dumps({"contribution_status": "Met"}), - ) - self.assertEqual(2, result) - self.assertIn("requires a public evidence URL", stderr) - - result, stdout, stderr = self.run_command( - "apply", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--json", - json.dumps( - { - "contribution_status": "Met", - "contribution_justification": "https://example.com/contributing", - } - ), - ) - self.assertEqual(0, result) - self.assertEqual("", stderr) - self.assertEqual("Met", json.loads(stdout)["assessment"]["contribution_status"]) - - def test_required_evidence_matches_upstream_for_apply_and_status(self) -> None: - # BadgeApp project.rb: justification_good? and contains_url?. Exercise - # real commands, including insufficient evidence loaded from storage. - text_cases = ( - ("", False), - ("yes", False), - ("abcd", False), - ("abcde", True), - ("\u00e9\u00e9\u00e9\u00e9", False), - ("\u00e9\u00e9\u00e9\u00e9\u00e9", True), - ("// Pending confirmation", False), - ("//note", True), # Only the exact '// ' prefix is a comment. - ("Tool runs before release.", True), - ) - url_cases = ( - ("https://", False), - ("https://localhost/guide", False), - ("https://example.", False), - ("// https://example.com/guide", False), - ("See https://example.com/guide.", True), - ("", True), - ("[guide](http://example.com/guide)", True), - ) - store = DataStore(self.data_dir) - store.register_project("31", "github.com/example/review") - for section, criterion, status, cases in ( - ("passing", "static_analysis", "Met", text_cases), - ("gold", "dynamic_analysis", "N/A", text_cases), - ("passing", "contribution", "Met", url_cases), - ("passing", "description_good", "Met", (("yes", True),)), - ("passing", "static_analysis", "Unmet", (("", True),)), - ): - for justification, sufficient in cases: - with self.subTest(criterion=criterion, status=status, text=justification): - assessment = { - f"{criterion}_status": status, - f"{criterion}_justification": justification, - } - store.save_assessment("31", assessment) - code, stdout, stderr = self.run_command("status", "--offline") - self.assertEqual(0, code, stderr) - self.assertEqual( - 0 if sufficient else 1, - json.loads(stdout)["sections"][section]["evidence_gaps"], - ) - - store.save_assessment("31", {}) - code, stdout, stderr = self.run_command( - "apply", "--section", section, "--offline", - "--json", json.dumps(assessment), - ) - self.assertEqual(0 if sufficient else 2, code, stderr) - self.assertEqual( - assessment if sufficient else {}, store.load_assessment("31") - ) - - def test_apply_validates_repeated_fields_against_the_selected_section(self) -> None: - self.register_verified_project() - result, stdout, stderr = self.run_command( - "apply", - "--section", - "gold", - "--project-id", - "31", - "--offline", - "--json", - json.dumps( - { - "dynamic_analysis_status": "N/A", - "dynamic_analysis_justification": "No major production releases.", - } - ), - ) - - self.assertEqual(0, result) - self.assertEqual("", stderr) - self.assertEqual("N/A", json.loads(stdout)["assessment"]["dynamic_analysis_status"]) - - result, _stdout, stderr = self.run_command( - "apply", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--json", - json.dumps({"dynamic_analysis_status": "N/A"}), - ) - - self.assertEqual(2, result) - self.assertIn("does not allow N/A", stderr) - - result, stdout, stderr = self.run_command( - "apply", - "--section", - "silver", - "--project-id", - "31", - "--offline", - "--json", - json.dumps( - { - "hardening_status": "Met", - "hardening_justification": "Confirmed hardening mechanisms.", - } - ), - ) - - self.assertEqual(0, result) - self.assertEqual("", stderr) - self.assertEqual("Met", json.loads(stdout)["assessment"]["hardening_status"]) - - def test_preview_revision_keeps_response_until_wording_is_approved(self) -> None: - store = DataStore(self.data_dir) - store.register_project("31", "github.com/example/review") - original = { - "release_notes_status": "Met", - "release_notes_justification": "See https://example.com/releases.", - } - store.save_assessment("31", original) - working = self.root / "preview.json" - working.write_text(json.dumps(original), encoding="utf-8") - wording = {"release_notes_justification": "No releases have been published."} - arguments = ("--assessment-file", str(working), "apply", "--section", "passing", "--offline") - - code, _stdout, stderr = self.run_command(*arguments, "--json", json.dumps(wording)) - self.assertEqual(2, code) - self.assertIn("requires a public evidence URL", stderr) - self.assertEqual(original, json.loads(working.read_text(encoding="utf-8"))) - - code, stdout, stderr = self.run_command( - *arguments, "--review-response", "N/A", "--json", json.dumps(wording), - ) - self.assertEqual(0, code, stderr) - provisional = original | wording - self.assertEqual(provisional, json.loads(stdout)["assessment"]) - self.assertEqual(provisional, json.loads(working.read_text(encoding="utf-8"))) - self.assertEqual(original, store.load_assessment("31")) - - code, _stdout, stderr = self.run_command( - *arguments, "--json", json.dumps({"release_notes_status": "Met"}), - ) - self.assertEqual(2, code) - self.assertIn("requires a public evidence URL", stderr) - code, stdout, stderr = self.run_command( - *arguments, "--json", json.dumps({"release_notes_status": "N/A"}), - ) - self.assertEqual(0, code, stderr) - approved = provisional | {"release_notes_status": "N/A"} - self.assertEqual(approved, json.loads(stdout)["assessment"]) - self.assertEqual(original, store.load_assessment("31")) - - code, stdout, stderr = self.run_command( - "apply", "--section", "passing", "--offline", "--json", json.dumps(approved), - ) - self.assertEqual(0, code, stderr) - self.assertEqual(approved, store.load_assessment("31")) - - def test_cancel_preview_revision_restores_board_and_export_uses_settled_answers(self) -> None: - original = { - "release_notes_status": "Met", - "release_notes_justification": "See https://example.com/releases.", - } - provisional = original | {"release_notes_justification": "No releases have been published."} - store = DataStore(self.data_dir) - store.register_project("31", "github.com/example/review") - store.save_assessment("31", original) - working = self.root / "preview.json" - working.write_text(json.dumps(provisional), encoding="utf-8") - exported = self.root / "export.json" - code, _stdout, stderr = self.run_command( - "export", "--offline", "--output", str(exported), - ) - self.assertEqual(0, code, stderr) - self.assertEqual(original, json.loads(exported.read_text(encoding="utf-8"))) - self.assertEqual(provisional, json.loads(working.read_text(encoding="utf-8"))) - - review = ("review", "--section", "passing", "--offline", "--no-browser") - code, stdout, stderr = self.run_command("--assessment-file", str(working), *review) - self.assertEqual(0, code, stderr) - url = json.loads(stdout)["url"] - board_path = Path(unquote(urlparse(url).path)) - self.addCleanup(board_path.unlink, missing_ok=True) - - def displayed_answer() -> dict[str, str]: - markup = board_path.read_text(encoding="utf-8") - embedded = markup.split('", 1)[0])["answers"]["release_notes"] - - self.assertEqual( - {"status": "Met", "justification": provisional["release_notes_justification"]}, - displayed_answer(), - ) - working.unlink() - code, stdout, stderr = self.run_command(*review) - self.assertEqual(0, code, stderr) - self.assertEqual(url, json.loads(stdout)["url"]) - self.assertEqual( - {"status": "Met", "justification": original["release_notes_justification"]}, - displayed_answer(), - ) - - def test_preview_revision_rejects_status_fields_and_invalid_destination_wording(self) -> None: - self.register_verified_project() - for proposed, response, error in ( - ({"release_notes_status": "N/A"}, "N/A", "only justification fields"), - ({"name": "Example"}, "N/A", "only justification fields"), - ({"release_notes_justification": ""}, "N/A", "requires an N/A justification"), - ({"release_notes_justification": "No releases yet."}, "Met", "requires a public evidence URL"), - ({"contribution_justification": "No contributions."}, "N/A", "does not allow N/A"), - ({"release_notes_justification": 5}, "N/A", "must be a string"), - ({"invented_justification": "No releases yet."}, "N/A", "unknown assessment field"), - ): - with self.subTest(proposed=proposed, response=response): - code, _stdout, stderr = self.run_command( - "apply", "--section", "passing", "--project-id", "31", "--offline", - "--review-response", response, "--json", json.dumps(proposed), - ) - self.assertEqual(2, code) - self.assertIn(error, stderr) - self.assertEqual({}, DataStore(self.data_dir).load_assessment("31")) - - def test_apply_rejects_a_field_outside_the_selected_section(self) -> None: - self.register_verified_project() - result, _stdout, stderr = self.run_command( - "apply", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--json", - json.dumps({"achieve_silver_status": "Met"}), - ) - - self.assertEqual(2, result) - self.assertIn("is not in section 'passing'", stderr) - - def test_repository_assessment_requires_working_file_selection_before_writes(self) -> None: - repository_file = self.repository / ".bestpractices.json" - original = '{"description_good_status": "Unmet"}\n' - repository_file.write_text(original) - code, _, error = self.run_command("status", "--project-id", "31", "--offline") - self.assertEqual(2, code) - self.assertIn("--assessment-file", error) - self.assertEqual(original, repository_file.read_text()) - store = DataStore(self.data_dir) - self.assertIsNone(store.resolve_project_id("github.com/example/review")) - self.assertEqual([], list(self.data_dir.rglob(".bestpractices.json"))) - for name, content in (("missing.json", None), ("invalid.json", "[]")): - with self.subTest(name=name): - working = self.root / name - if content is not None: - working.write_text(content) - code, _, _ = self.run_command( - "--assessment-file", str(working), "status", "--project-id", "31", "--offline", - ) - self.assertEqual(2, code) - self.assertEqual(original, repository_file.read_text()) - self.assertEqual([], list(self.data_dir.rglob(".bestpractices.json"))) - - def test_export_writes_the_canonical_document_to_an_explicit_path(self) -> None: - self.register_verified_project() - self.run_command( - "apply", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--json", - json.dumps({"description_good_status": "Met"}), - ) - output = self.repository / ".bestpractices.json" - - result, stdout, stderr = self.run_command( - "export", - "--project-id", - "31", - "--offline", - "--output", - str(output), - ) - - self.assertEqual(0, result) - self.assertEqual("", stderr) - self.assertEqual("assessment_exported", json.loads(stdout)["state"]) - self.assertEqual( - {"description_good_status": "Met"}, - json.loads(output.read_text(encoding="utf-8")), - ) - - def test_review_writes_a_board_and_apply_refreshes_it(self) -> None: - self.register_verified_project() - result, stdout, stderr = self.run_command( - "review", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--no-browser", - ) - - payload = json.loads(stdout) - board_path = Path(unquote(urlparse(payload["url"]).path)) - self.addCleanup(board_path.unlink, missing_ok=True) - self.assertTrue(board_path.is_file()) - self.assertEqual(0, result) - self.assertEqual("", stderr) - self.assertEqual("review_written", payload["state"]) - self.assertEqual("", urlparse(payload["url"]).fragment) - - result, _stdout, stderr = self.run_command( - "apply", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--json", - json.dumps({"description_good_status": "Met"}), - ) - - refreshed_markup = board_path.read_text(encoding="utf-8") - self.assertEqual(0, result) - self.assertEqual("", stderr) - self.assertIn( - '"description_good":{"status":"Met"', - refreshed_markup, - ) - - def test_apply_succeeds_when_passive_board_refresh_fails(self) -> None: - self.register_verified_project() - result, stdout, _stderr = self.run_command( - "review", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--no-browser", - ) - board_path = Path(unquote(urlparse(json.loads(stdout)["url"]).path)) - self.addCleanup(board_path.unlink, missing_ok=True) - self.assertEqual(0, result) - - with patch.object(ossf, "write_board", side_effect=OSError("display unavailable")): - result, stdout, stderr = self.run_command( - "apply", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--json", - json.dumps({"description_good_status": "Met"}), - ) - - self.assertEqual(0, result) - self.assertEqual("Met", json.loads(stdout)["assessment"]["description_good_status"]) - self.assertIn("warning: passive review board refresh failed", stderr) - - result, stdout, stderr = self.run_command( - "status", - "--project-id", - "31", - "--offline", - ) - self.assertEqual(0, result) - self.assertEqual("", stderr) - self.assertEqual("Met", json.loads(stdout)["assessment"]["description_good_status"]) - - def test_board_refresh_reloads_canonical_state_instead_of_stale_sync(self) -> None: - self.register_verified_project() - result, stdout, _stderr = self.run_command( - "review", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--no-browser", - ) - payload = json.loads(stdout) - board_path = Path(unquote(urlparse(payload["url"]).path)) - self.addCleanup(board_path.unlink, missing_ok=True) - self.assertEqual(0, result) - - store = DataStore(self.data_dir) - stale_result = ossf._synchronize( - ossf.build_parser().parse_args( - [ - "--repo", - str(self.repository), - "--data-dir", - str(self.data_dir), - "status", - "--project-id", - "31", - "--offline", - ] - ), - store_factory=DataStore, - client_factory=MissingProjectClient, - )[1] - store.update_assessment("31", {"description_good_status": "Met"}) - - ossf._refresh_open_boards( - store, - stale_result, - ossf.CriteriaCatalog(), - self.data_dir, - ) - - self.assertIn( - '"description_good":{"status":"Met"', - board_path.read_text(encoding="utf-8"), - ) - - def test_apply_flags_assessment_narration_in_justifications(self) -> None: - self.register_verified_project() - result, stdout, stderr = self.run_command( - "apply", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--json", - json.dumps( - { - "contribution_status": "Met", - "contribution_justification": ( - "There is no direct evidence for this, but the " - "maintainer says the process is followed; this " - "corrects a previous statement: " - "https://example.com/contributing" - ), - } - ), - ) - - payload = json.loads(stdout) - self.assertEqual(0, result) - self.assertEqual("", stderr) - # Advisory only: the update is applied despite the warnings. - self.assertEqual("Met", payload["assessment"]["contribution_status"]) - warned_fields = {item["field"] for item in payload["style_warnings"]} - self.assertEqual({"contribution_justification"}, warned_fields) - matched = {item["matched"].lower() for item in payload["style_warnings"]} - self.assertIn("no direct evidence", matched) - self.assertIn("maintainer says", matched) - self.assertIn("corrects a previous", matched) - - def test_apply_does_not_flag_form_voice_or_criterion_vocabulary(self) -> None: - self.register_verified_project() - result, stdout, _stderr = self.run_command( - "apply", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--json", - json.dumps( - { - "contribution_status": "Met", - "contribution_justification": ( - # "unreviewable"/"review" are legitimate criterion - # vocabulary and must not trip the narration patterns. - "Contribution instructions require review of any " - "unreviewable artifacts: https://example.com/contributing" - ), - } - ), - ) - - payload = json.loads(stdout) - self.assertEqual(0, result) - self.assertEqual([], payload["style_warnings"]) - - def test_apply_flags_overlong_justifications_without_blocking(self) -> None: - self.register_verified_project() - result, stdout, _stderr = self.run_command( - "apply", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--json", - json.dumps( - { - "contribution_status": "Met", - "contribution_justification": ( - "https://example.com/contributing " + "detail " * 150 - ), - } - ), - ) - - payload = json.loads(stdout) - self.assertEqual(0, result) - self.assertEqual("Met", payload["assessment"]["contribution_status"]) - reasons = " ".join(item["reason"] for item in payload["style_warnings"]) - self.assertIn("very long", reasons) - - def test_propose_emits_reviewable_urls_and_skips_unknown_statuses(self) -> None: - self.register_verified_project() - self.run_command( - "apply", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--json", - json.dumps( - { - "description_good_status": "Met", - "contribution_status": "Met", - "contribution_justification": "https://example.com/contributing", - } - ), - ) - - result, stdout, stderr = self.run_command( - "propose", - "--section", - "passing", - "--project-id", - "31", - "--offline", - ) - - payload = json.loads(stdout) - self.assertEqual(0, result) - self.assertEqual("", stderr) - self.assertEqual("proposals_ready", payload["state"]) - self.assertEqual(1, len(payload["urls"])) - url = payload["urls"][0] - self.assertTrue( - url.startswith("https://www.bestpractices.dev/en/projects/31/passing/edit?") - ) - self.assertIn("description_good_status=Met", url) - self.assertIn("contribution_status=Met", url) - self.assertIn("contribution_justification=https%3A%2F%2F", url) - self.assertEqual( - ["contribution", "description_good"], - sorted(payload["proposed"]), - ) - # Unknown statuses offer no answer for the proposal URL to transfer. - self.assertNotIn("interact_status", url) - self.assertIn("interact", payload["skipped_unknown"]) - - def test_submission_preserves_markdown_and_detects_formatting_changes(self) -> None: - justification = ( - "The project uses [documented practices][guide].\n\n" - "[guide]: https://example.com/guide\n\n" - "- Build the project.\n- Run the checks.\n\n" - " make check\n\n" - "Results are published. \nSee the guide.\n" - ) - assessment = { - "description_good_status": "Met", - "description_good_justification": justification, - } - catalog = CriteriaCatalog() - plan = build_proposal_urls( - assessment, catalog, section="passing", project_id="31" - ) - query = parse_qs(urlparse(plan.urls[0]).query) - self.assertEqual([justification], query["description_good_justification"]) - - live = dict(assessment) - live["description_good_justification"] = " ".join(justification.split()) - selected = wording_only_criteria( - assessment, catalog, section="passing", public_document=live - ) - self.assertEqual(("description_good",), selected) - plan = build_proposal_urls( - assessment, catalog, section="passing", project_id="31", public_document=live - ) - self.assertEqual(selected, plan.dropped_justification_only) - self.assertEqual((), plan.dropped_no_op) - - script, included = build_fill_script( - assessment, catalog, section="passing", criteria=selected - ) - self.assertEqual(selected, included) - payload, _ = json.JSONDecoder().raw_decode(script.split("const answers = ", 1)[1]) - self.assertEqual(justification, payload["description_good"]["justification"]) - - def test_proposal_fills_blank_justification_without_changing_status(self) -> None: - assessment = { - "description_good_status": "Met", - "description_good_justification": "README describes the project.", - } - for blank in (None, "", " \n"): - with self.subTest(blank=blank): - plan = build_proposal_urls( - assessment, CriteriaCatalog(), section="passing", project_id="31", - public_document={ - "description_good_status": "Met", - "description_good_justification": blank, - }, - ) - self.assertEqual(("description_good",), plan.proposed) - self.assertEqual((), plan.dropped_justification_only) - query = parse_qs(urlparse(plan.urls[0]).query) - self.assertEqual(["Met"], query["description_good_status"]) - self.assertEqual( - [assessment["description_good_justification"]], - query["description_good_justification"], - ) - self.assertNotIn("overrides", query) - - def test_wording_proposals_leave_override_matching_to_the_site(self) -> None: - live = { - "description_good_status": "Met", - "description_good_justification": "Old wording.", - } - for overrides in ( - "description_good_justification", "description_good_status", "*", - "description_*", "unrelated_*", - ): - for wording in ("New wording.", ""): - with self.subTest(overrides=overrides, wording=wording): - plan = build_proposal_urls( - {**live, "description_good_justification": wording}, - CriteriaCatalog(), section="passing", project_id="31", - public_document=live, overrides=overrides, - ) - self.assertEqual(("description_good",), plan.proposed) - self.assertEqual((), plan.dropped_justification_only) - query = parse_qs(urlparse(plan.urls[0]).query, keep_blank_values=True) - self.assertEqual([overrides], query["overrides"]) - self.assertEqual(["Met"], query["description_good_status"]) - self.assertEqual([wording], query["description_good_justification"]) - - def test_overrides_do_not_emit_unchanged_answers_or_unknown_statuses(self) -> None: - assessment = { - "description_good_status": "Met", - "description_good_justification": "Existing wording.", - "interact_status": "?", - "interact_justification": "Unfinished wording.", - } - plan = build_proposal_urls( - assessment, CriteriaCatalog(), section="passing", project_id="31", - public_document=assessment, overrides="*", - ) - self.assertEqual((), plan.urls) - self.assertEqual(("description_good",), plan.dropped_no_op) - self.assertIn("interact", plan.skipped_unknown) - - def test_submission_distinguishes_cleared_and_omitted_justifications(self) -> None: - catalog = CriteriaCatalog() - assessment = { - "description_good_status": "Met", - "description_good_justification": "", - "interact_status": "Met", - "contribution_status": "?", - "contribution_justification": "Work in progress.", - } - live = { - "description_good_status": "Met", - "description_good_justification": "Old description.", - "interact_status": "Met", - "interact_justification": "Keep this explanation.", - "contribution_status": "Met", - } - selected = wording_only_criteria( - assessment, catalog, section="passing", public_document=live - ) - self.assertEqual(("description_good",), selected) - plan = build_proposal_urls( - assessment, catalog, section="passing", project_id="31", public_document=live - ) - self.assertEqual(selected, plan.dropped_justification_only) - self.assertEqual(("interact",), plan.dropped_no_op) - self.assertIn("contribution", plan.skipped_unknown) - self.assertEqual((), plan.urls) - - plan = build_proposal_urls( - assessment, catalog, section="passing", project_id="31" - ) - query = parse_qs(urlparse(plan.urls[0]).query, keep_blank_values=True) - self.assertEqual([""], query["description_good_justification"]) - self.assertNotIn("interact_justification", query) - self.assertNotIn("contribution_status", query) - - script, included = build_fill_script(assessment, catalog, section="passing") - payload, _ = json.JSONDecoder().raw_decode(script.split("const answers = ", 1)[1]) - self.assertEqual(("description_good", "interact"), included) - self.assertEqual( - { - "description_good": {"status": "Met", "justification": ""}, - "interact": {"status": "Met"}, - }, - payload, - ) - - # Exercise separate controller invocations against unchanged public data. - client_factory = lambda: PublicProjectClient(live) - self.run_command("status", client_factory=client_factory) - code, _, error = self.run_command( - "apply", "--section", "passing", "--input", "-", - stdin=json.dumps({"description_good_justification": ""}), - client_factory=client_factory, - ) - self.assertEqual((0, ""), (code, error)) - output = self.root / "clear-wording.js" - for command in (("status",), ("propose", "--section", "passing"), - ("fill-script", "--section", "passing", "--output", str(output))): - with self.subTest(command=command[0]): - code, stdout, error = self.run_command(*command, client_factory=client_factory) - self.assertEqual((0, ""), (code, error)) - response = json.loads(stdout) - if command[0] == "status": - self.assertIn({ - "field": "description_good_justification", "preserved": "", - "incoming": live["description_good_justification"], "source": "public_api", - }, response["conflicts"]) - else: - self.assertEqual([], response["conflicts"]) - self.assertEqual(["description_good"], response["criteria"]) - payload, _ = json.JSONDecoder().raw_decode( - output.read_text().split("const answers = ", 1)[1] - ) - self.assertEqual({"description_good": {"status": "Met", "justification": ""}}, payload) - - def test_propose_requires_a_registered_project(self) -> None: - result, _stdout, stderr = self.run_command( - "propose", - "--section", - "passing", - "--offline", - "--allow-unregistered", - ) - - self.assertEqual(2, result) - self.assertIn("requires a registered", stderr) - - def _record_one_answer(self) -> None: - self.run_command( - "apply", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--json", - json.dumps({"description_good_status": "Met"}), - ) - - def test_propose_rejects_a_base_url_outside_the_badge_site(self) -> None: - self.register_verified_project() - self._record_one_answer() - for hostile in ( - "https://attacker.example", - "https://www.bestpractices.dev.attacker.example", - "http://www.bestpractices.dev", - "https://www.bestpractices.dev:8443", - "https://www.bestpractices.dev/evil", - "file:///tmp", - ): - with self.subTest(base_url=hostile): - result, stdout, stderr = self.run_command( - "propose", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--base-url", - hostile, - ) - self.assertEqual(2, result) - self.assertEqual("", stdout) - self.assertIn("base URL must be one of", stderr) - self.assertIn("https://www.bestpractices.dev", stderr) - - def test_propose_accepts_the_staging_site_with_a_trailing_slash(self) -> None: - self.register_verified_project() - self._record_one_answer() - result, stdout, _stderr = self.run_command( - "propose", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--base-url", - "https://staging.bestpractices.dev/", - ) - self.assertEqual(0, result) - payload = json.loads(stdout) - self.assertTrue( - payload["urls"][0].startswith( - "https://staging.bestpractices.dev/en/projects/31/passing/edit?" - ) - ) - - def test_propose_open_hands_the_browser_only_badge_site_urls(self) -> None: - self.register_verified_project() - self._record_one_answer() - opened: list[str] = [] - result, stdout, _stderr = self.run_command( - "propose", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--open", - browser_open=opened.append, - ) - self.assertEqual(0, result) - payload = json.loads(stdout) - self.assertEqual([payload["urls"][0]], opened) - self.assertTrue( - opened[0].startswith("https://www.bestpractices.dev/en/projects/31/") - ) - - def test_browser_guard_refuses_anything_but_https_badge_site_urls(self) -> None: - ossf._assert_badge_site_url("https://www.bestpractices.dev/en/projects/31/passing/edit?x=1") - ossf._assert_badge_site_url("https://staging.bestpractices.dev/en/projects/31/silver/edit?") - for url in ( - "http://www.bestpractices.dev/en/projects/31/passing/edit?", - "https://attacker.example/en/projects/31/passing/edit?", - "https://www.bestpractices.dev@attacker.example/", - "file:///tmp/edit.html", - ): - with self.subTest(url=url), self.assertRaises(ossf.CommandError): - ossf._assert_badge_site_url(url) - - def test_validate_base_url_normalizes_only_the_allowed_sites(self) -> None: - self.assertEqual( - "https://www.bestpractices.dev", validate_base_url("https://www.bestpractices.dev/") - ) - self.assertEqual( - "https://staging.bestpractices.dev", - validate_base_url(" https://staging.bestpractices.dev "), - ) - with self.assertRaises(ValueError): - validate_base_url("https://bestpractices.dev") - - def test_propose_drops_no_ops_and_reports_justification_only_changes( - self, - ) -> None: - client = PublicProjectClient( - { - "repo_url": "https://github.com/example/review", - "description_good_status": "Met", - "description_good_justification": "README opening paragraph.", - "interact_status": "Met", - "interact_justification": "README covers interaction.", - } - ) - self.run_command("status", client_factory=lambda: client) - self.run_command( - "apply", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--json", - json.dumps( - { - "description_good_status": "Met", - "description_good_justification": "A better wording.", - "maintained_status": "Met", - } - ), - ) - - result, stdout, stderr = self.run_command( - "propose", - "--section", - "passing", - "--project-id", - "31", - client_factory=lambda: client, - ) - - payload = json.loads(stdout) - self.assertEqual(0, result) - self.assertEqual("", stderr) - self.assertEqual(["maintained"], payload["proposed"]) - self.assertEqual(["interact"], payload["dropped_no_op"]) - self.assertEqual( - ["description_good"], - payload["dropped_justification_only"], - ) - self.assertTrue( - any("fill-script" in note for note in payload["notes"]) - ) - - def test_propose_chunks_urls_without_splitting_a_criterion(self) -> None: - self.register_verified_project() - justification = "https://example.com/evidence " + "x" * 120 - self.run_command( - "apply", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--json", - json.dumps( - { - "description_good_status": "Met", - "description_good_justification": justification, - "interact_status": "Met", - "interact_justification": justification, - "maintained_status": "Met", - "maintained_justification": justification, - } - ), - ) - - result, stdout, _stderr = self.run_command( - "propose", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--max-url-bytes", - "300", - ) - - payload = json.loads(stdout) - self.assertEqual(0, result) - self.assertGreater(len(payload["urls"]), 1) - for url in payload["urls"]: - # A criterion's status and justification are coupled upstream and - # must always travel in the same URL. - for criterion in ("description_good", "interact", "maintained"): - has_status = f"{criterion}_status=" in url - has_justification = f"{criterion}_justification=" in url - self.assertEqual(has_status, has_justification) - self.assertTrue(any("Save (and" in note for note in payload["notes"])) - - def test_propose_reports_oversize_criteria_instead_of_emitting_them( - self, - ) -> None: - self.register_verified_project() - long_justification = "https://example.com/evidence " + "detail " * 60 - self.run_command( - "apply", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--json", - json.dumps( - { - "description_good_status": "Met", - "description_good_justification": long_justification, - "interact_status": "Met", - } - ), - ) - - result, stdout, _stderr = self.run_command( - "propose", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--max-url-bytes", - "300", - ) - - payload = json.loads(stdout) - self.assertEqual(0, result) - self.assertEqual(["description_good"], payload["oversize"]) - self.assertEqual(["interact"], payload["proposed"]) - for url in payload["urls"]: - self.assertNotIn("description_good", url) - self.assertLessEqual(len(url.encode("utf-8")), 300) - self.assertTrue( - any("fill-script --criteria" in note for note in payload["notes"]) - ) - - def test_propose_rejects_overrides_upstream_would_ignore(self) -> None: - self.register_verified_project() - result, _stdout, stderr = self.run_command( - "propose", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--overrides", - "x" * 10_001, - ) - - self.assertEqual(2, result) - self.assertIn("overrides", stderr) - - def test_fill_script_writes_selected_answers_and_refuses_private_storage( - self, - ) -> None: - self.register_verified_project() - self.run_command( - "apply", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--json", - json.dumps( - { - "description_good_status": "Met", - "description_good_justification": "README opening paragraph.", - } - ), - ) - output = self.root / "fill.js" - - result, stdout, stderr = self.run_command( - "fill-script", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--all", - "--output", - str(output), - ) - - payload = json.loads(stdout) - script = output.read_text(encoding="utf-8") - self.assertEqual(0, result) - self.assertEqual("", stderr) - self.assertEqual("fill_script_written", payload["state"]) - self.assertEqual("all", payload["scope"]) - self.assertEqual(["description_good"], payload["criteria"]) - self.assertIn("description_good", script) - - result, _stdout, stderr = self.run_command( - "fill-script", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--all", - "--output", - str(self.data_dir / "fill.js"), - ) - self.assertEqual(2, result) - self.assertIn("outside CLAUDE_PLUGIN_DATA", stderr) - - def test_fill_script_changed_only_is_default_and_requires_live_entry( - self, - ) -> None: - self.register_verified_project() - result, _stdout, stderr = self.run_command( - "fill-script", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--output", - str(self.root / "fill.js"), - ) - - self.assertEqual(2, result) - self.assertIn("--changed-only cannot compute", stderr) - self.assertIn("--criteria", stderr) - self.assertIn("--all", stderr) - self.assertFalse((self.root / "fill.js").exists()) - - def test_fill_script_changed_only_targets_wording_diffs_only(self) -> None: - client = PublicProjectClient( - { - "repo_url": "https://github.com/example/review", - "description_good_status": "Met", - "description_good_justification": "Same wording.", - "interact_status": "Met", - "interact_justification": "Thin bot wording without a URL.", - "maintained_status": "Unmet", - } - ) - self.run_command("status", client_factory=lambda: client) - self.run_command( - "apply", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--json", - json.dumps( - { - "description_good_status": "Met", - "description_good_justification": "Same wording.", - "interact_status": "Met", - "interact_justification": ( - "Obtain, feedback, and contribution paths are in the " - "README: https://example.com#readme" - ), - "maintained_status": "Met", - } - ), - ) - output = self.root / "fill.js" - - result, stdout, stderr = self.run_command( - "fill-script", - "--section", - "passing", - "--project-id", - "31", - "--output", - str(output), - client_factory=lambda: client, - ) - - payload = json.loads(stdout) - script = output.read_text(encoding="utf-8") - self.assertEqual(0, result) - self.assertEqual("", stderr) - self.assertEqual("changed-only", payload["scope"]) - # Only the wording-only diff: not the in-sync criterion, and not the - # status-divergent one (that belongs to propose, or to a deliberate - # --criteria choice — never to a silent full-section write). - self.assertEqual(["interact"], payload["criteria"]) - self.assertIn("interact", script) - self.assertNotIn("maintained", script) - self.assertNotIn("description_good", script) - - def test_fill_script_criteria_selects_an_explicit_validated_subset( - self, - ) -> None: - self.register_verified_project() - self.run_command( - "apply", - "--section", - "baseline-1", - "--project-id", - "31", - "--offline", - "--json", - json.dumps( - { - "osps_ac_01_01_status": "Unmet", - "osps_ac_01_01_justification": "MFA is not yet enforced.", - "osps_vm_02_01_status": "Met", - "osps_vm_02_01_justification": ( - "Security contacts are in SECURITY.md: " - "https://example.com/SECURITY.md" - ), - } - ), - ) - output = self.root / "fill.js" - - result, stdout, _stderr = self.run_command( - "fill-script", - "--section", - "baseline-1", - "--project-id", - "31", - "--offline", - "--criteria", - "OSPS-AC-01.01", - "--output", - str(output), - ) - - payload = json.loads(stdout) - script = output.read_text(encoding="utf-8") - self.assertEqual(0, result) - self.assertEqual("criteria", payload["scope"]) - self.assertEqual(["osps_ac_01_01"], payload["criteria"]) - self.assertIn("osps_ac_01_01", script) - self.assertNotIn("osps_vm_02_01", script) - - result, _stdout, stderr = self.run_command( - "fill-script", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--criteria", - "achieve_silver", - "--output", - str(output), - ) - self.assertEqual(2, result) - self.assertIn("--criteria", stderr) - - def test_status_reports_wording_only_updates_against_live_entry(self) -> None: - self.register_verified_project() - client = PublicProjectClient( - { - "repo_url": "https://github.com/example/review", - "interact_status": "Met", - "interact_justification": "Thin bot wording without a URL.", - } - ) - self.run_command( - "apply", - "--section", - "passing", - "--project-id", - "31", - "--offline", - "--json", - json.dumps( - { - "interact_status": "Met", - "interact_justification": ( - "Obtain, feedback, and contribution paths are in the " - "README: https://example.com#readme" - ), - } - ), - ) - - result, stdout, _stderr = self.run_command( - "status", - "--project-id", - "31", - client_factory=lambda: client, - ) - payload = json.loads(stdout) - self.assertEqual(0, result) - self.assertEqual({"passing": ["interact"]}, payload["wording_only_updates"]) - - result, stdout, _stderr = self.run_command( - "status", - "--project-id", - "31", - "--offline", - ) - self.assertEqual(0, result) - payload = json.loads(stdout) - self.assertEqual({"passing": ["interact"]}, payload["wording_only_updates"]) - self.assertEqual("cached", payload["sources"]["public_snapshot"]["source"]) - self.assertFalse(payload["sources"]["public_loaded"]) - - def test_review_opens_only_the_generated_file_url(self) -> None: - self.register_verified_project() - for view, fragment in ((None, ""), ("overview", ""), ("all", "view=all")): - for no_browser in (False, True): - with self.subTest(view=view, no_browser=no_browser): - opened: list[str] = [] - arguments = [] if view is None else ["--view", view] - if no_browser: - arguments.append("--no-browser") - result, stdout, stderr = self.run_command( - "review", - "--section", - "silver", - "--project-id", - "31", - "--offline", - *arguments, - browser_open=opened.append, - ) - - payload = json.loads(stdout) - board_url = urlparse(payload["url"]) - board_path = Path(unquote(board_url.path)) - self.addCleanup(board_path.unlink, missing_ok=True) - self.assertEqual((0, ""), (result, stderr)) - self.assertEqual("review_written", payload["state"]) - self.assertEqual([] if no_browser else [payload["url"]], opened) - self.assertEqual("file", board_url.scheme) - self.assertEqual(fragment, board_url.fragment) - self.assertEqual("silver", payload["section"]) - self.assertTrue(board_path.is_file()) - - def test_review_rejects_unknown_views_and_retired_preview_command(self) -> None: - for arguments in (("review", "--view", "missing"), ("preview",)): - with self.subTest(arguments=arguments): - with ( - contextlib.redirect_stderr(StringIO()), - self.assertRaises(SystemExit) as raised, - ): - ossf.build_parser().parse_args(arguments) - self.assertEqual(2, raised.exception.code) - - -if __name__ == "__main__": - unittest.main() diff --git a/tests/badge-buddy/test_remotes.py b/tests/badge-buddy/test_remotes.py new file mode 100644 index 0000000..7e33520 --- /dev/null +++ b/tests/badge-buddy/test_remotes.py @@ -0,0 +1,48 @@ +"""Remote normalization retained for Scorecard.""" + +from pathlib import Path +import sys +import unittest + +sys.path.insert( + 0, str(Path(__file__).resolve().parents[2] / "plugins/badge-buddy/scripts") +) +from ossf_review.remotes import github_repository_url, normalize_github_remote + + +class NormalizeGithubRemoteTest(unittest.TestCase): + def test_supported_spellings_have_one_identity(self) -> None: + remotes = ( + "https://github.com/OpenSSF/Best-Practices-Badge.git", + "https://github.com/OpenSSF/Best-Practices-Badge/", + "http://github.com/OpenSSF/Best-Practices-Badge/", + "ssh://git@github.com/OpenSSF/Best-Practices-Badge.git", + "git@github.com:OpenSSF/Best-Practices-Badge.git", + "github.com/OpenSSF/Best-Practices-Badge", + ) + + identities = {normalize_github_remote(remote) for remote in remotes} + + self.assertEqual( + {"github.com/openssf/best-practices-badge"}, + identities, + ) + self.assertEqual( + {"https://github.com/OpenSSF/Best-Practices-Badge"}, + {github_repository_url(remote) for remote in remotes}, + ) + + def test_preserved_url_and_lowercase_key_remain_distinct(self) -> None: + remote = "ssh://git@GitHub.com/Reponomics/PolicyChecks.git" + self.assertEqual( + "https://github.com/Reponomics/PolicyChecks", github_repository_url(remote) + ) + self.assertEqual( + "github.com/reponomics/policychecks", normalize_github_remote(remote) + ) + + def test_non_repository_remote_is_rejected(self) -> None: + with self.assertRaises(ValueError): + normalize_github_remote("https://gitlab.com/OpenSSF/project") + with self.assertRaises(ValueError): + normalize_github_remote("https://github.com/OpenSSF/project/issues") diff --git a/tests/badge-buddy/test_review_board_cli.py b/tests/badge-buddy/test_review_board_cli.py new file mode 100644 index 0000000..65cc8bf --- /dev/null +++ b/tests/badge-buddy/test_review_board_cli.py @@ -0,0 +1,143 @@ +"""Exercise the standalone offline board entry point through real files.""" + +import json +from pathlib import Path +import subprocess +import sys +import tempfile +import unittest + +ROOT = Path(__file__).resolve().parents[2] +SCRIPT = ROOT / "plugins/badge-buddy/scripts/review_board.py" + + +class ReviewBoardCliTest(unittest.TestCase): + def test_all_six_levels_render_without_modifying_input(self): + with tempfile.TemporaryDirectory(prefix="badge board ") as directory: + root = Path(directory) + draft = root / "draft.json" + original = ( + '{"description_good_status":"Met","OSPS-AC-01.01_status":"Met"}\n' + ) + draft.write_text(original) + for level in ( + "passing", + "silver", + "gold", + "baseline-1", + "baseline-2", + "baseline-3", + ): + with self.subTest(level=level): + output = root / f"{level}.html" + result = subprocess.run( + [ + sys.executable, + str(SCRIPT), + "--input", + str(draft), + "--output", + str(output), + "--project-id", + "31", + "--section", + level, + ], + text=True, + capture_output=True, + check=True, + ) + self.assertEqual( + output.resolve().as_uri() + "#view=all", + json.loads(result.stdout)["url"], + ) + self.assertIn(f'"section":"{level}"', output.read_text()) + self.assertEqual(original, draft.read_text()) + + def test_invalid_input_and_same_destination_fail_without_overwrite(self): + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + source = root / "draft.json" + for contents, output in ( + ("[]", root / "board.html"), + ("{}", source), + ("bad json", root / "board.html"), + ): + with self.subTest(contents=contents): + source.write_text(contents) + result = subprocess.run( + [ + sys.executable, + str(SCRIPT), + "--input", + str(source), + "--output", + str(output), + "--project-id", + "31", + "--section", + "baseline-1", + ], + text=True, + capture_output=True, + ) + self.assertEqual(1, result.returncode) + self.assertEqual(contents, source.read_text()) + if output != source: + self.assertFalse(output.exists()) + + def test_project_mismatch_does_not_create_or_replace_board(self): + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + source = root / "draft.json" + source.write_text('{"id": 32, "description_good_status": "Met"}') + output = root / "board.html" + for existing in (False, True): + if existing: + output.write_text("previous preview") + result = subprocess.run( + [ + sys.executable, + str(SCRIPT), + "--input", + str(source), + "--output", + str(output), + "--project-id", + "31", + "--section", + "passing", + ], + text=True, + capture_output=True, + ) + self.assertEqual(1, result.returncode) + self.assertIn("does not match", result.stderr) + if existing: + self.assertEqual("previous preview", output.read_text()) + else: + self.assertFalse(output.exists()) + + def test_matching_numeric_id_and_local_label_can_render(self): + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + source = root / "draft.json" + source.write_text('{"id": 31}') + for selected in ("31", "Local draft"): + result = subprocess.run( + [ + sys.executable, + str(SCRIPT), + "--input", + str(source), + "--output", + str(root / "board.html"), + "--project-id", + selected, + "--section", + "passing", + ], + text=True, + capture_output=True, + ) + self.assertEqual(0, result.returncode, result.stderr) diff --git a/tests/badge-buddy/test_storage.py b/tests/badge-buddy/test_storage.py deleted file mode 100644 index 7e429a6..0000000 --- a/tests/badge-buddy/test_storage.py +++ /dev/null @@ -1,281 +0,0 @@ -"""Tests for the OpenSSF review persistent storage layer.""" - -from __future__ import annotations - -from concurrent.futures import ThreadPoolExecutor -import json -from pathlib import Path -import sys -import tempfile -import unittest -from unittest.mock import patch - - -SCRIPTS_DIR = Path(__file__).resolve().parents[2] / "plugins" / "badge-buddy" / "scripts" -sys.path.insert(0, str(SCRIPTS_DIR)) - -from ossf_review.storage import ( # noqa: E402 - DataStore, - github_repository_url, - normalize_github_remote, -) -from ossf_review import storage # noqa: E402 - - -class NormalizeGithubRemoteTest(unittest.TestCase): - def test_supported_spellings_have_one_identity(self) -> None: - remotes = ( - "https://github.com/OpenSSF/Best-Practices-Badge.git", - "https://github.com/OpenSSF/Best-Practices-Badge/", - "http://github.com/OpenSSF/Best-Practices-Badge/", - "ssh://git@github.com/OpenSSF/Best-Practices-Badge.git", - "git@github.com:OpenSSF/Best-Practices-Badge.git", - "github.com/OpenSSF/Best-Practices-Badge", - ) - - identities = {normalize_github_remote(remote) for remote in remotes} - - self.assertEqual( - {"github.com/openssf/best-practices-badge"}, - identities, - ) - self.assertEqual( - {"https://github.com/OpenSSF/Best-Practices-Badge"}, - {github_repository_url(remote) for remote in remotes}, - ) - - def test_preserved_url_and_lowercase_key_remain_distinct(self) -> None: - remote = "ssh://git@GitHub.com/Reponomics/PolicyChecks.git" - self.assertEqual( - "https://github.com/Reponomics/PolicyChecks", github_repository_url(remote) - ) - self.assertEqual("github.com/reponomics/policychecks", normalize_github_remote(remote)) - - def test_non_repository_remote_is_rejected(self) -> None: - with self.assertRaises(ValueError): - normalize_github_remote("https://gitlab.com/OpenSSF/project") - with self.assertRaises(ValueError): - normalize_github_remote("https://github.com/OpenSSF/project/issues") - - -class DataStoreTest(unittest.TestCase): - def setUp(self) -> None: - self.temporary_directory = tempfile.TemporaryDirectory() - self.addCleanup(self.temporary_directory.cleanup) - self.data_dir = Path(self.temporary_directory.name) / "review-data" - self.store = DataStore(self.data_dir) - - def test_public_snapshot_is_separate_from_selected_assessment_and_bound_to_origin(self) -> None: - working = self.data_dir / "working.json" - working.write_text('{"description_good_justification": "Private draft"}') - self.store.use_assessment_file(working) - document = {"description_good_status": "Met"} - snapshot = self.store.save_public_snapshot(31, "git@github.com:Example/Project.git", document) - reloaded = DataStore(self.data_dir) - self.assertEqual(snapshot, reloaded.load_public_snapshot( - 31, "https://github.com/example/project" - )) - self.assertIsNone(reloaded.load_public_snapshot(31, "https://github.com/example/other")) - self.assertIsNone(reloaded.load_public_snapshot(32, "https://github.com/example/project")) - self.assertEqual({"description_good_justification": "Private draft"}, json.loads(working.read_text())) - self.assertFalse((self.data_dir / "projects/31/.bestpractices.json").exists()) - - def test_registry_roundtrip_and_reverse_lookup(self) -> None: - identifier = self.store.register_project( - 14356, - "git@github.com:Reponomics/PolicyChecks.git", - ) - - self.assertEqual("14356", identifier) - self.assertEqual( - "14356", - self.store.resolve_project_id( - "https://github.com/reponomics/policychecks/" - ), - ) - registry = json.loads( - (self.data_dir / "registry.json").read_text(encoding="utf-8") - ) - self.assertEqual(1, registry["schema_version"]) - self.assertEqual( - "github.com/reponomics/policychecks", - registry["by_id"]["14356"], - ) - self.assertEqual( - "14356", - registry["by_remote"]["github.com/reponomics/policychecks"], - ) - self.assertEqual({}, registry["unregistered"]) - self.assertEqual( - {}, - json.loads( - ( - self.data_dir / "projects" / "14356" / ".bestpractices.json" - ).read_text(encoding="utf-8") - ), - ) - - def test_updating_mapping_removes_stale_forward_and_reverse_entries(self) -> None: - self.store.register_project(1, "https://github.com/example/old") - self.store.register_project(1, "https://github.com/example/new") - - self.assertIsNone( - self.store.resolve_project_id("https://github.com/example/old") - ) - self.assertEqual( - "1", - self.store.resolve_project_id("git@github.com:example/new.git"), - ) - - def test_assessment_save_and_nested_merge(self) -> None: - self.store.register_project(7, "https://github.com/example/project") - self.store.save_assessment( - 7, - { - "description_good_status": "Met", - "criteria": { - "description_good": { - "status": "Met", - "justification": "README", - } - }, - }, - ) - - result = self.store.update_assessment( - 7, - { - "contribution_status": "Unmet", - "criteria": {"description_good": {"status": "Unmet"}}, - }, - ) - - self.assertEqual("Met", result["description_good_status"]) - self.assertEqual("Unmet", result["contribution_status"]) - self.assertEqual( - { - "status": "Unmet", - "justification": "README", - }, - result["criteria"]["description_good"], - ) - self.assertEqual(result, self.store.load_assessment(7)) - - def test_concurrent_unrelated_updates_are_merged(self) -> None: - self.store.register_project(9, "https://github.com/example/concurrent") - stores = [DataStore(self.data_dir) for _ in range(8)] - - with ThreadPoolExecutor(max_workers=len(stores)) as executor: - futures = [ - executor.submit( - store.update_assessment, - 9, - {f"criterion_{index}_status": "Met"}, - ) - for index, store in enumerate(stores) - ] - for future in futures: - future.result() - - assessment = self.store.load_assessment(9) - self.assertEqual( - {f"criterion_{index}_status" for index in range(len(stores))}, - set(assessment), - ) - - def test_unregistered_record_roundtrip(self) -> None: - local_project = Path(self.temporary_directory.name) / "local-project" - - record = self.store.create_unregistered( - local_project, - remote="ssh://git@github.com/Example/Local.git", - project_name="Local Project", - ) - - self.assertEqual( - str(local_project.resolve()), record["local_project_directory"] - ) - self.assertEqual("github.com/example/local", record["remote"]) - self.assertEqual("Local Project", record["project_name"]) - self.assertEqual("local-project", record["storage_key"]) - self.assertEqual(record, self.store.load_unregistered(local_project)) - identifier = self.store.unregistered_identifier(local_project) - self.assertEqual("unregistered:local-project", identifier) - self.assertEqual({}, self.store.load_assessment(identifier)) - self.store.update_assessment( - identifier, - {"description_good_status": "Met"}, - ) - self.assertEqual( - {"description_good_status": "Met"}, - json.loads( - ( - self.data_dir - / "unregistered" - / "local-project" - / ".bestpractices.json" - ).read_text(encoding="utf-8") - ), - ) - self.assertIsNone( - self.store.load_unregistered( - Path(self.temporary_directory.name) / "unknown" - ) - ) - - def test_unregistered_safe_keys_avoid_local_name_collisions(self) -> None: - first = Path(self.temporary_directory.name) / "one" / "same name" - second = Path(self.temporary_directory.name) / "two" / "same name" - - first_record = self.store.create_unregistered(first) - second_record = self.store.create_unregistered(second) - - self.assertEqual("same-name", first_record["storage_key"]) - self.assertEqual("same-name-2", second_record["storage_key"]) - - def test_local_handoff_retries_after_destination_or_registry_write_failure(self) -> None: - local_directory = Path(self.temporary_directory.name) / "local-project" - draft = {"description_good_status": "?", "description_good_justification": "Partial notes."} - original_write = storage._atomic_write_json - for fail_registry in (False, True): - with self.subTest(fail_registry=fail_registry): - store = DataStore(self.data_dir / str(fail_registry)) - store.create_unregistered(local_directory, remote="github.com/example/project") - local_id = store.unregistered_identifier(local_directory) - store.save_assessment(local_id, draft) - store.register_project("31", "github.com/example/project") - failed_path = (store.registry_path if fail_registry else - store.projects_dir / "31" / storage.ASSESSMENT_FILENAME) - - def fail_write(path, value): - if path == failed_path: - raise OSError("simulated write failure") - original_write(path, value) - - with patch.object(storage, "_atomic_write_json", side_effect=fail_write): - with self.assertRaises(OSError): - store.handoff_unregistered(local_directory, "31") - preserved_id = "31" if fail_registry else local_id - self.assertEqual(draft, store.load_assessment(preserved_id)) - self.assertIsNotNone(store.load_unregistered(local_directory)) - self.assertEqual((draft, {}), store.handoff_unregistered(local_directory, "31")) - self.assertIsNone(store.load_unregistered(local_directory)) - self.assertEqual({}, store.load_assessment(local_id)) - - def test_transform_assessment_receives_current_values(self) -> None: - self.store.register_project(11, "https://github.com/example/transform") - self.store.save_assessment(11, {"one_status": "Met"}) - - result = self.store.transform_assessment( - 11, - lambda current: {**current, "two_status": "Unmet"}, - ) - - self.assertEqual( - {"one_status": "Met", "two_status": "Unmet"}, - result, - ) - - -if __name__ == "__main__": - unittest.main() diff --git a/tests/badge-buddy/test_sync.py b/tests/badge-buddy/test_sync.py deleted file mode 100644 index 4442b0f..0000000 --- a/tests/badge-buddy/test_sync.py +++ /dev/null @@ -1,569 +0,0 @@ -"""Tests for project resolution and read-only assessment synchronization.""" - -from __future__ import annotations - -from io import BytesIO -import json -from pathlib import Path -import subprocess -import sys -import tempfile -import unittest -from unittest.mock import Mock, patch -from urllib.error import URLError -from urllib.parse import parse_qs, urlsplit - - -SCRIPTS_DIR = Path(__file__).resolve().parents[2] / "plugins" / "badge-buddy" / "scripts" -sys.path.insert(0, str(SCRIPTS_DIR)) - -from ossf_review.storage import DataStore # noqa: E402 -from ossf_review.sync import ( # noqa: E402 - BestPracticesClient, - ProjectResolutionError, - UnregisteredProjectError, - discover_repository, - load_repository_assessment, - resolve_project, - SyncConflict, - synchronize_project, -) - - -class FakeResponse: - def __init__(self, payload: object) -> None: - self._stream = BytesIO(json.dumps(payload).encode("utf-8")) - - def __enter__(self) -> "FakeResponse": - return self - - def __exit__(self, *unused: object) -> None: - return None - - def read(self, size: int = -1) -> bytes: - return self._stream.read(size) - - -class FakePublicClient: - def __init__( - self, - *, - project_id: str | None = None, - project: dict[str, object] | None = None, - ) -> None: - self.project_id = project_id - self.project = project or {} - self.lookup_calls: list[str] = [] - self.fetch_calls: list[str] = [] - - def lookup_project_id(self, remote: str) -> str | None: - self.lookup_calls.append(remote) - return self.project_id - - def fetch_project(self, project_id: str) -> dict[str, object]: - self.fetch_calls.append(project_id) - return dict(self.project) - - -class SyncTest(unittest.TestCase): - def setUp(self) -> None: - self.temporary_directory = tempfile.TemporaryDirectory() - self.addCleanup(self.temporary_directory.cleanup) - self.root = Path(self.temporary_directory.name) - self.repository = self.root / "repo" - subprocess.run( - ["git", "init", "-q", str(self.repository)], - check=True, - capture_output=True, - ) - subprocess.run( - [ - "git", - "-C", - str(self.repository), - "remote", - "add", - "origin", - "git@github.com:Example/Project.git", - ], - check=True, - capture_output=True, - ) - self.store = DataStore(self.root / "data") - - def test_invalid_refresh_preserves_snapshot_and_local_answers(self) -> None: - document = {"repo_url": "https://github.com/example/project", "interact_status": "Met"} - client = FakePublicClient(project_id="31", project=document) - synchronize_project(self.store, self.repository, client=client) - original = self.store.load_public_snapshot("31", "https://github.com/example/project") - self.store.update_assessment("31", {"interact_status": "?"}) - client.project = {"repo_url": "https://github.com/example/other"} - with self.assertRaises(ProjectResolutionError): - synchronize_project(self.store, self.repository, client=client) - self.assertEqual(original, self.store.load_public_snapshot( - "31", "https://github.com/example/project" - )) - with patch.object(client, "fetch_project", side_effect=ProjectResolutionError("unavailable")): - with self.assertRaises(ProjectResolutionError): - synchronize_project(self.store, self.repository, client=client) - offline = synchronize_project(DataStore(self.root / "data"), self.repository) - self.assertEqual(document, offline.public_document) - self.assertEqual("?", offline.assessment["interact_status"]) - self.assertEqual((), offline.conflicts) - self.assertFalse(offline.public_loaded) - self.assertEqual(original["fetched_at"], offline.public_fetched_at) - - def test_discovers_root_and_normalizes_origin_via_git_c(self) -> None: - nested = self.repository / "nested" - nested.mkdir() - - identity = discover_repository(nested) - - self.assertEqual(self.repository.resolve(), identity.root) - self.assertEqual("github.com/example/project", identity.remote) - self.assertEqual("https://github.com/Example/Project", identity.url) - self.assertEqual("repo", identity.project_name) - - def test_registry_is_consulted_before_public_lookup(self) -> None: - self.store.register_project(42, "https://github.com/example/project") - client = FakePublicClient(project_id="99") - - resolution = resolve_project(self.store, self.repository, client=client) - - self.assertEqual("42", resolution.identifier) - self.assertEqual([], client.lookup_calls) - - def test_public_lookup_is_registered_only_after_synchronization_validates_it(self) -> None: - client = FakePublicClient( - project_id="77", project={"repo_url": "https://github.com/Example/Project"}, - ) - - resolution = resolve_project(self.store, self.repository, client=client) - - self.assertTrue(resolution.registered) - self.assertEqual("77", resolution.project_id) - self.assertEqual(["https://github.com/Example/Project"], client.lookup_calls) - self.assertIsNone(self.store.resolve_project_id("github.com/example/project")) - result = synchronize_project(self.store, self.repository, client=client) - self.assertEqual("77", result.resolution.project_id) - self.assertEqual( - "77", - self.store.resolve_project_id("https://github.com/example/project"), - ) - - def test_rejected_project_selection_preserves_mappings_and_assessments(self) -> None: - bad_identity = { - "mismatch": {"repo_url": "https://github.com/example/other"}, - "homepage_mismatch": {"repo_url": "", "homepage_url": "https://github.com/example/other"}, - "homepage_cannot_override_repo": { - "repo_url": "https://github.com/example/other", - "homepage_url": "https://github.com/example/project", - }, - "missing_identity": {}, - "unverifiable_identity": {"homepage_url": "https://example.org"}, - } - for failure in (*bad_identity, "fetch", "discovery"): - with self.subTest(failure=failure): - store = DataStore(self.root / failure) - first_remote = ("github.com/example/old" if failure == "discovery" - else "github.com/example/project") - store.register_project("1", first_remote) - store.register_project("2", "github.com/example/other") - for identifier, status in (("1", "Met"), ("2", "Unmet")): - store.save_assessment(identifier, {"description_good_status": status}) - original_registry = store.registry_path.read_bytes() - client = FakePublicClient( - project_id="2", project=bad_identity.get(failure, bad_identity["mismatch"]), - ) - if failure == "fetch": - client.fetch_project = Mock( - side_effect=ProjectResolutionError("public fetch failed") - ) - with self.assertRaises(ProjectResolutionError): - synchronize_project( - store, self.repository, client=client, - project_id=None if failure == "discovery" else "2", - ) - self.assertEqual(original_registry, store.registry_path.read_bytes()) - self.assertEqual("1", store.resolve_project_id(first_remote)) - self.assertEqual("2", store.resolve_project_id("github.com/example/other")) - self.assertEqual({"description_good_status": "Met"}, store.load_assessment("1")) - self.assertEqual({"description_good_status": "Unmet"}, store.load_assessment("2")) - - # A verified selection can still deliberately replace a mapping. - verified = FakePublicClient(project={"repo_url": "https://github.com/Example/Project"}) - result = synchronize_project(store, self.repository, project_id="2", client=verified) - self.assertEqual("2", result.resolution.project_id) - self.assertEqual("2", store.resolve_project_id("github.com/example/project")) - self.assertIsNone(store.resolve_project_id("github.com/example/other")) - self.assertEqual({"description_good_status": "Unmet"}, result.assessment) - - def test_online_status_accepts_matching_homepage_only_identity(self) -> None: - client = FakePublicClient(project_id="77", project={ - "repo_url": "", "homepage_url": "https://github.com/EXAMPLE/Project", - }) - result = synchronize_project(self.store, self.repository, client=client) - self.assertEqual("77", result.resolution.project_id) - self.assertEqual("77", self.store.resolve_project_id("github.com/example/project")) - self.assertEqual(["77"], client.fetch_calls) - - def test_unregistered_requires_explicit_opt_in_and_gets_own_file(self) -> None: - with self.assertRaises(UnregisteredProjectError): - resolve_project(self.store, self.repository) - - resolution = resolve_project( - self.store, - self.repository, - allow_unregistered=True, - ) - - self.assertFalse(resolution.registered) - self.assertTrue(resolution.identifier.startswith("unregistered:")) - record = self.store.load_unregistered(self.repository) - self.assertIsNotNone(record) - assessment_path = ( - self.root - / "data" - / "unregistered" - / str(record["storage_key"]) - / ".bestpractices.json" - ) - self.assertTrue(assessment_path.is_file()) - - def test_case_variant_discovery_syncs_once_and_reuses_numeric_registration(self) -> None: - document = { - "id": 14356, - "repo_url": "https://github.com/EXAMPLE/Project", - "description_good_status": "Met", - } - responses = iter(([document], [], [], document)) - urls = [] - - def opener(request: object, *, timeout: float) -> FakeResponse: - urls.append(request.full_url) - return FakeResponse(next(responses)) - - client = BestPracticesClient(opener=opener, minimum_interval=0) - result = synchronize_project(self.store, self.repository, client=client) - self.assertEqual("14356", result.resolution.project_id) - self.assertEqual("Met", result.assessment["description_good_status"]) - self.assertEqual("https://github.com/Example/Project", result.resolution.repository.url) - self.assertEqual("14356", self.store.resolve_project_id("github.com/example/project")) - self.assertEqual(4, len(urls)) - - cached = FakePublicClient(project=document) - repeated = synchronize_project(self.store, self.repository, client=cached) - self.assertEqual("14356", repeated.resolution.project_id) - self.assertEqual([], cached.lookup_calls) - self.assertEqual(["14356"], cached.fetch_calls) - - def test_registration_carries_local_answers_and_partial_evidence(self) -> None: - draft = { - "description_good_status": "Met", - "description_good_justification": "First paragraph.\n\nSecond paragraph.\n", - "contribution_status": "?", - "contribution_justification": "Draft instructions, still investigating.", - "sites_https_justification": "", - } - for route in ("discovery", "explicit", "cached"): - with self.subTest(route=route): - store = DataStore(self.root / route) - local = resolve_project(store, self.repository, allow_unregistered=True) - store.save_assessment(local.identifier, draft) - if route == "cached": - store.register_project("77", "github.com/example/project") - store.save_assessment("77", {"maintained_status": "Met"}) - client = FakePublicClient(project_id="77", project={ - "repo_url": "https://github.com/example/project", - "description_good_status": "?", - "interact_status": "Met", - }) - result = synchronize_project( - store, self.repository, client=client, - project_id="77" if route == "explicit" else None, - ) - expected = {**draft, "interact_status": "Met"} - if route == "cached": - expected["maintained_status"] = "Met" - self.assertEqual(expected, result.assessment) - self.assertEqual((SyncConflict( - "description_good_status", "Met", "?", "public API", - ),), result.conflicts) - self.assertIsNone(store.load_unregistered(self.repository)) - self.assertEqual({}, store.load_assessment(local.identifier)) - self.assertEqual(expected, synchronize_project( - store, self.repository, client=client, - ).assessment) - - def test_failed_public_validation_leaves_local_draft_available(self) -> None: - local = resolve_project(self.store, self.repository, allow_unregistered=True) - draft = {"description_good_status": "Met"} - self.store.save_assessment(local.identifier, draft) - client = FakePublicClient(project={"repo_url": "https://github.com/other/repo"}) - with self.assertRaises(ProjectResolutionError): - synchronize_project(self.store, self.repository, project_id="77", client=client) - self.assertEqual(draft, self.store.load_assessment(local.identifier)) - self.assertIsNotNone(self.store.load_unregistered(self.repository)) - - def test_root_repository_assessment_wins_location_selection(self) -> None: - root_file = self.repository / ".bestpractices.json" - root_file.write_text('{"root_status": "Met"}', encoding="utf-8") - fallback = self.repository / ".project.d" / "bestpractices.json" - fallback.parent.mkdir() - fallback.write_text('{"fallback_status": "Met"}', encoding="utf-8") - - selected, assessment = load_repository_assessment(self.repository) - - self.assertEqual(root_file, selected) - self.assertEqual({"root_status": "Met"}, assessment) - - def test_sync_preserves_real_plugin_values_and_reports_conflicts(self) -> None: - self.store.register_project(8, "https://github.com/example/project") - self.store.save_assessment( - 8, - { - "description_good_status": "Met", - "description_good_justification": "Current user evidence", - }, - ) - client = FakePublicClient( - project={ - "repo_url": "https://github.com/example/project", - "description_good_status": "Unmet", - "description_good_justification": "Public explanation", - "contribution_status": "Met", - "OSPS-AC-01.01_status": "Met", - "badge_percentage_0": 99, - } - ) - - result = synchronize_project(self.store, self.repository, client=client) - - self.assertEqual("Met", result.assessment["description_good_status"]) - self.assertEqual( - "Current user evidence", - result.assessment["description_good_justification"], - ) - self.assertEqual("Met", result.assessment["contribution_status"]) - self.assertEqual("Met", result.assessment["osps_ac_01_01_status"]) - self.assertNotIn("badge_percentage_0", result.assessment) - self.assertEqual(( - SyncConflict("description_good_status", "Met", "Unmet", "public API"), - SyncConflict("description_good_justification", "Current user evidence", - "Public explanation", "public API"), - ), result.conflicts) - - def test_cleared_answers_survive_later_reads_until_explicitly_reconciled(self) -> None: - public = { - "description_good_status": "Met", - "description_good_justification": "Previous explanation", - } - client = FakePublicClient(project_id="12", project={ - "repo_url": "https://github.com/example/project", **public, - }) - synchronize_project(self.store, self.repository, client=client) - correction = { - "description_good_status": "?", - "description_good_justification": "", - } - self.store.update_assessment("12", correction) - result = synchronize_project(self.store, self.repository, client=client) - self.assertEqual(correction, result.assessment) - self.assertEqual(correction, self.store.load_assessment("12")) - self.assertEqual(tuple( - SyncConflict(field, correction[field], value, "public API") - for field, value in public.items() - ), result.conflicts) - - synchronize_project(self.store, self.repository, client=client, user_updates=public) - reconciled = synchronize_project(self.store, self.repository, client=client) - self.assertEqual(public, reconciled.assessment) - self.assertEqual((), reconciled.conflicts) - - def test_import_initializes_absent_answers_without_combining_partial_answers(self) -> None: - self.store.register_project("12", "github.com/example/project") - local = {"description_good_justification": "Local unfinished explanation"} - self.store.save_assessment("12", local) - new_answer = { - "contribution_status": "?", - "contribution_justification": "Public unfinished explanation", - } - client = FakePublicClient(project={ - "repo_url": "https://github.com/example/project", - **new_answer, - "description_good_status": "Met", - "description_good_justification": "", - }) - result = synchronize_project(self.store, self.repository, client=client) - self.assertEqual({**local, **new_answer}, result.assessment) - self.assertEqual(( - SyncConflict("description_good_status", None, "Met", "public API"), - SyncConflict("description_good_justification", local["description_good_justification"], - "", "public API"), - ), result.conflicts) - - def test_current_session_user_updates_always_win(self) -> None: - self.store.register_project(12, "https://github.com/example/project") - repository_file = self.repository / ".bestpractices.json" - repository_file.write_text( - json.dumps({"description_good_status": "Met"}), - encoding="utf-8", - ) - self.store.use_assessment_file(repository_file) - client = FakePublicClient( - project={ - "repo_url": "https://github.com/example/project", - "description_good_status": "Unmet", - } - ) - - result = synchronize_project( - self.store, - self.repository, - client=client, - user_updates={ - "description_good_status": "Unmet", - "description_good_justification": "User corrected this now", - }, - ) - - self.assertEqual("Unmet", result.assessment["description_good_status"]) - self.assertEqual( - "User corrected this now", - result.assessment["description_good_justification"], - ) - self.assertEqual( - result.assessment, - json.loads(repository_file.read_text(encoding="utf-8")), - ) - - -class BestPracticesClientTest(unittest.TestCase): - def lookup_client(self, responses: list[object]): - pending = iter(responses) - requests = [] - - def opener(request: object, *, timeout: float) -> FakeResponse: - requests.append(parse_qs(urlsplit(request.full_url).query)) - response = next(pending) - if isinstance(response, Exception): - raise response - return FakeResponse(response) - - return BestPracticesClient(opener=opener, minimum_interval=0), requests - - def test_filtered_lookup_and_fetch_are_sequential_and_identified(self) -> None: - requests = [] - responses = iter( - ( - [ - { - "id": 5, - "repo_url": "https://github.com/Example/Project.git", - }, - {"id": 9, "repo_url": "https://github.com/other/project"}, - ], - [], - [], - {"id": 5, "description_good_status": "Met"}, - ) - ) - sleeps: list[float] = [] - - def opener(request: object, *, timeout: float) -> FakeResponse: - requests.append((request, timeout)) - return FakeResponse(next(responses)) - - client = BestPracticesClient( - opener=opener, - clock=lambda: 0.0, - sleeper=sleeps.append, - ) - - identifier = client.lookup_project_id("github.com/example/project") - project = client.fetch_project(identifier or "") - - self.assertEqual("5", identifier) - self.assertEqual("Met", project["description_good_status"]) - self.assertEqual([1.0, 1.0, 1.0], sleeps) - self.assertEqual(4, len(requests)) - first_request = requests[0][0] - self.assertEqual("GET", first_request.get_method()) - self.assertIn( - "pq=https%3A%2F%2Fgithub.com%2Fexample%2Fproject", first_request.full_url - ) - self.assertEqual( - "badge-buddy/1 (+https://github.com/reponomics/plugins)", - first_request.get_header("User-agent"), - ) - - def test_case_insensitive_candidates_are_exactly_filtered_across_pages(self) -> None: - stored = "https://github.com/Reponomics/PolicyChecks" - client, requests = self.lookup_client([ - [ - {"id": 10, "repo_url": stored + "-tools"}, - {"id": 11, "homepage_url": stored, "repo_url": "https://github.com/other/repo"}, - ], - [{"id": 14356, "repo_url": stored}], - [{"id": "14356", "repo_url": stored + ".git"}], - [], - [], - ]) - self.assertEqual("14356", client.lookup_project_id("git@github.com:reponomics/policychecks.git")) - self.assertEqual(["1", "2", "3", "4", "1"], [q["page"][0] for q in requests]) - self.assertEqual("https://github.com/reponomics/policychecks", requests[0]["pq"][0]) - self.assertTrue(all(q["sort"] == ["id"] and q["sort_direction"] == ["asc"] for q in requests)) - - def test_different_case_entries_are_ambiguous_even_on_later_pages(self) -> None: - client, _ = self.lookup_client([ - [{"id": 1, "repo_url": "https://github.com/example/project"}], - [{"id": 2, "repo_url": "https://github.com/Example/Project"}], - [], [], - ]) - with self.assertRaisesRegex(ProjectResolutionError, "multiple project ids: 1, 2"): - client.lookup_project_id("github.com/example/project") - - def test_http_entry_is_found_without_contacting_the_repository(self) -> None: - client, requests = self.lookup_client([ - [], [{"id": 1, "repo_url": "http://github.com/Example/Project"}], [], - ]) - self.assertEqual("1", client.lookup_project_id("github.com/example/project")) - self.assertEqual("http://github.com/example/project", requests[1]["pq"][0]) - - def test_homepage_only_registration_is_supported(self) -> None: - client, _ = self.lookup_client([ - [{"id": 1, "repo_url": "", "homepage_url": "https://github.com/Example/Project"}], [], [], - ]) - self.assertEqual("1", client.lookup_project_id("github.com/example/project")) - - def test_complete_empty_search_returns_no_match(self) -> None: - client, requests = self.lookup_client([[], []]) - self.assertIsNone(client.lookup_project_id("github.com/example/project")) - self.assertEqual(2, len(requests)) - - def test_page_limit_never_accepts_a_partial_unique_match(self) -> None: - client, _ = self.lookup_client([ - [{"id": 1, "repo_url": "https://github.com/example/project"}], - [{"id": 2, "repo_url": "https://github.com/example/project-tools"}], - ]) - with patch("ossf_review.sync.MAX_LOOKUP_PAGES", 2): - with self.assertRaisesRegex(ProjectResolutionError, "incomplete.*--project-id"): - client.lookup_project_id("github.com/example/project") - - def test_failed_later_page_is_not_a_successful_or_empty_lookup(self) -> None: - client, _ = self.lookup_client([ - [{"id": 1, "repo_url": "https://github.com/example/project"}], URLError("offline"), - ]) - with self.assertRaisesRegex(ProjectResolutionError, "public API read failed"): - client.lookup_project_id("github.com/example/project") - - def test_malformed_results_do_not_become_registration_absence(self) -> None: - for payload in ({"error": "bad response"}, ["invalid"], [{"id": True, "repo_url": "https://github.com/example/project"}]): - with self.subTest(payload=payload): - client, _ = self.lookup_client([payload]) - with self.assertRaises(ProjectResolutionError): - client.lookup_project_id("github.com/example/project") - - -if __name__ == "__main__": - unittest.main()