Skip to content

docs: clarify repository reviewer entry #77

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
stacknil merged 1 commit into from
May 26, 2026
Merged

docs: clarify repository reviewer entry #77

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,11 @@ For the clearest reviewer route, start with the
it separates orientation, artifact inspection, local reproduction, and release
evidence.

For a repository-level reviewer overview, use the
[root reviewer brief](docs/reviewer-brief.md). It distinguishes the flagship
SBOM tool from the supporting diagnostics projects and points reviewers to
the right evidence path.

## Supporting Diagnostics Projects

These projects are internal supporting material for reviewer depth. They are
Expand Down Expand Up @@ -64,6 +69,7 @@ evidence.

Useful entry points:

- [Root reviewer brief](docs/reviewer-brief.md)
- [`sbom-diff-and-risk` README](tools/sbom-diff-and-risk/README.md)
- [Reviewer path](tools/sbom-diff-and-risk/docs/reviewer-path.md)
- [Reviewer brief](tools/sbom-diff-and-risk/docs/reviewer-brief.md)
Expand Down
169 changes: 108 additions & 61 deletions docs/reviewer-brief.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,65 +1,112 @@
# Reviewer brief

## Problem

Scientific and security-oriented review work often needs small deterministic tools, not vague platforms. Reviewers need evidence that inputs, outputs, and claims stay inspectable.

## What it does

`scientific-computing-toolkit` is a portfolio repository for scientific-computing infrastructure and supply-chain review work.

The current flagship project is `tools/sbom-diff-and-risk`, a local CLI for comparing two SBOMs or dependency manifests and producing deterministic JSON, Markdown, SARIF, and policy sidecar artifacts.

## Reviewer Evidence

- Reproducible command: `sbom-diff-risk compare --before examples/cdx_before.json --after examples/cdx_after.json --format auto --out-json outputs/report.json --summary-json outputs/summary.json --out-md outputs/report.md`
- Deterministic outputs: JSON reports, Markdown reports, summary sidecars, policy sidecars, SARIF, and checked-in example artifacts.
- Tests / CI: local pytest coverage and reviewer evidence docs for regenerating sample artifacts and verification paths.
- Release evidence: `sbom-diff-and-risk` release notes, GitHub release verification docs, TestPyPI Trusted Publishing dry-run notes, and intentionally deferred production PyPI decision docs.
- Non-goals: vulnerability scanning, CVE resolution, exploitability scoring, package safety verdicts, hidden enrichment, or production PyPI claims.
# Reviewer brief

## Problem

Scientific and security-oriented review work often needs small deterministic
tools, not vague platforms. Reviewers need evidence that inputs, outputs, and
claims stay inspectable.

## What it does

`scientific-computing-toolkit` is a portfolio repository for
scientific-computing infrastructure and supply-chain review work.

The current flagship project is
[`tools/sbom-diff-and-risk`](../tools/sbom-diff-and-risk/README.md), a local
CLI for comparing two SBOMs or dependency manifests and producing
deterministic JSON, Markdown, SARIF, and policy sidecar artifacts.

The precipitation and weather diagnostics projects are supporting
scientific-data projects. They demonstrate public-safe reproducible analysis
workflows, but they are not part of the `sbom-diff-and-risk` release surface.

## How to review this repository

| Review question | Start here | Stop when |
| --- | --- | --- |
| What is the repository shape? | This brief and the root [README](../README.md). | You can distinguish the flagship SBOM tool from the supporting diagnostics projects. |
| What should I review for the SBOM tool? | The SBOM [reviewer path](../tools/sbom-diff-and-risk/docs/reviewer-path.md). | You have chosen the right 30-second, 5-minute, 15-minute, release, or deep-review route. |
| Can the SBOM examples be reproduced? | The SBOM [example artifact regeneration guide](../tools/sbom-diff-and-risk/docs/example-artifact-regeneration.md). | `python scripts/regenerate-example-artifacts.py --check` passes. |
| Can the released SBOM artifacts be verified? | The SBOM [verification guide](../tools/sbom-diff-and-risk/docs/verification.md). | You know whether to use checksums, release verification, or workflow artifact attestations. |
| What are the supporting diagnostics projects? | The supporting project entry points below and the root [README](../README.md). | You can state their data-policy boundaries and that they are separate from the SBOM release surface. |

## Supporting diagnostics entry points

| Project | Role | Start here |
| --- | --- | --- |
| `precipitation-anomaly-diagnostics` | Compact reviewer-facing mini-lab | [README](../projects/precipitation-anomaly-diagnostics/README.md) |
| `precipitation-anomaly-diagnostics-lab` | Extended climate diagnostics lab | [README](../projects/precipitation-anomaly-diagnostics-lab/README.md) |
| `python-weather-diagnostics-toolkit` | Reusable weather-field diagnostics toolkit | [Reviewer path](../projects/python-weather-diagnostics-toolkit/docs/reviewer-path.md) |

## Reviewer evidence

- Reproducible command path: install the SBOM tool, run the bundled CycloneDX
example, and compare generated outputs with checked-in artifacts.
- Deterministic outputs: JSON reports, Markdown reports, summary sidecars,
policy sidecars, SARIF, and checked-in example artifacts.
- Tests / CI: local pytest coverage, example-artifact regeneration checks, and
reviewer evidence docs for verification paths.
- Release evidence: `sbom-diff-and-risk` release notes, GitHub release
verification docs, TestPyPI Trusted Publishing dry-run notes, and
intentionally deferred production PyPI decision docs.
- Non-goals: vulnerability scanning, CVE resolution, exploitability scoring,
package safety verdicts, hidden enrichment, or production PyPI claims.

## Quick run

From the repository root:

```bash
cd tools/sbom-diff-and-risk
python -m pip install -e ".[dev]"
sbom-diff-risk compare --before examples/cdx_before.json --after examples/cdx_after.json --format auto --out-json outputs/report.json --summary-json outputs/summary.json --out-md outputs/report.md
```

## Sample output

The flagship tool can emit:

- `report.json`
- `summary.json`
- `policy.json`
- `report.md`
- `report.sarif`

The checked-in examples and docs cover deterministic local output, optional policy decisions, and opt-in provenance or Scorecard evidence when explicit enrichment flags are enabled.

## What this proves

- deterministic supply-chain review tooling
- reviewer-oriented artifact design instead of black-box scoring
- careful separation between local default behavior and opt-in enrichment
- the ability to package a broader repo around one clear flagship tool

## Safety / boundaries

- local-file analysis is the default
- no hidden network enrichment
- not a vulnerability scanner or package reputation oracle
- production PyPI publishing remains intentionally deferred

## Limitations

- the root repo is currently flagship-led rather than evenly balanced across multiple finished tools
- heuristic risk buckets do not resolve CVEs or exploitability
- provenance and Scorecard evidence are advisory, not proof that a dependency is safe

## Next milestone

Keep strengthening the flagship reviewer route while adding the next finished tool or mini-lab at the same documentation and evidence standard.

```bash
cd tools/sbom-diff-and-risk
python -m pip install -e ".[dev]"
sbom-diff-risk compare \
--before examples/cdx_before.json \
--after examples/cdx_after.json \
--format auto \
--out-json outputs/report.json \
--summary-json outputs/summary.json \
--out-md outputs/report.md
```

## Sample output

The flagship tool can emit:

- [`report.json`](../tools/sbom-diff-and-risk/examples/sample-report.json)
- [`summary.json`](../tools/sbom-diff-and-risk/examples/sample-summary.json)
- [`policy.json`](../tools/sbom-diff-and-risk/examples/sample-policy.json)
- [`report.md`](../tools/sbom-diff-and-risk/examples/sample-report.md)
- [`report.sarif`](../tools/sbom-diff-and-risk/examples/sample-sarif.sarif)

The checked-in examples and docs cover deterministic local output, optional
policy decisions, and opt-in provenance or Scorecard evidence when explicit
enrichment flags are enabled.

## What this proves

- deterministic supply-chain review tooling
- reviewer-oriented artifact design instead of black-box scoring
- careful separation between local default behavior and opt-in enrichment
- the ability to package a broader repo around one clear flagship tool

## Safety / boundaries

- local-file analysis is the default
- no hidden network enrichment
- not a vulnerability scanner or package reputation oracle
- production PyPI publishing remains intentionally deferred
- supporting diagnostics projects use public-safe synthetic or derived example
artifacts and are separate from the SBOM release surface

## Limitations

- the root repo is currently flagship-led rather than evenly balanced across
multiple finished tools
- heuristic risk buckets do not resolve CVEs or exploitability
- provenance and Scorecard evidence are advisory, not proof that a dependency
is safe

## Next milestone

Keep strengthening the flagship reviewer route while adding the next finished
tool or mini-lab at the same documentation and evidence standard.