Repository checks

Repository checks help maintainers detect changes that break source provenance, build and launch rules, dependency ownership, or maintained code conventions. They combine source inspection, tests of the detectors themselves, launcher fixtures, and observations of the checker container's own execution posture. Use this page to choose a check and understand a finding.

Choose the scope of the run

Run the focused target that covers the change. Use the full repository suite when changing shared checkers or source inventories, or when assessing the complete repository policy.

The targets launch the recorded checker image with networking disabled and selected source trees and Git data mounted read-only. The host launcher uses host Bash, Git and filesystem utilities to prepare metadata and scratch directories, then invokes the container engine. The supported checkout has an initialized upstream submodule and its Git object store under .git/modules/nmrnet. If required image or Git inputs are missing, follow the checker preparation instructions and checkout prerequisites. Checker Python and its tools run in the container; a host Python run is a different environment.

The launcher writes temporary metadata and inspection receipts under .work and creates a private engine-client directory under /tmp. It reads the checkout's Git metadata and writes a separate scaffold for the checker. Normal cleanup removes owned temporary directories after client retirement; failed admission or uncertain cleanup can retain evidence at the reported paths. The engine owns the checker container and its logs.

To inspect the declared launch command, use bash tools/container.sh --print test/repository. This preview uses a placeholder for the recorded checker image; actual image admission occurs when the checks run. Read-only mounts prevent container writes, but the host can still edit those files. Keep the inspected source stable during a run.

make test WHEELHOUSE=/path/to/shared-wheelhouse also runs unit tests and NMRNet consumer integration suites. The focused repository targets above do not include those other suites. Consult the package test guide for their purposes and the reproduction guide for numerical evidence.

What the checks examine

• Source and build inputs. Exact file inventories, declared upstream revisions, committed and materialized source bytes, build-context selection and the source actually granted to a container.
• Launch and configuration boundaries. Early container guards, explicit operator inputs, literal Make capture, engine environment handling and dependency boundaries. Runtime checks observe the checker container's effective user, capabilities, networking and resource limits.
• Code conventions and failure reporting. The pinned Ruff rules and formatting policy, plus source detectors for selected fallback, error-transparency, validation-guard and runtime-policy patterns.
• Scientific provenance. Selected source contracts, exact dependency intent and lock contents, artifact and fixture inventories, producer identities and preserved reference bytes.
• Maintained entry points. Test discovery, visible source roots, documentation links and a single maintained HTML prose collection.

Launcher fixtures execute copied scripts against a finite engine double and inspect its recorded calls. The checker-container observations concern that invocation; scientific-worker and service behavior have their own execution tests.

Each detector has a defined inventory and a limited set of patterns it can recognize. A pass establishes the assertions that ran against the inspected inputs. Numerical equivalence, chemical accuracy, real model capacity and deployed API behavior require their corresponding execution evidence. Documentation link checks inspect local HTML; published content and rendered behavior need separate observation.

Handle a finding by its meaning

1. Identify the blocked step. A missing image, unreadable source or failed checker launch means the run did not establish its checks. Resolve that prerequisite before interpreting the result as a code finding.
2. Read the reported location and rule. Trace the detected pattern to the requirement and its consumer. A syntax match can identify a concern without proving that every similar expression has the same meaning.
3. Choose the correction. Fix a real regression at its owner. Where a detector supports an annotation, a reviewed explanation can record an intentional local contract within that annotation's narrow scope. For a detector mistake, add a small counterexample and retain cases that must still fail.
4. Check the affected behavior. Run the relevant focused tests and the affected check again. Report what ran, what it established, and any remaining limit.

Preserve the requirement when revising a check. Removing a source path, skipping a failing assertion, or changing an independent numerical reference merely to obtain a pass changes the obligation. A check can also be revised or retired when its requirement no longer applies: explain the ownership or product change and preserve still-relevant coverage at its proper owner. The Use/Avoid criteria record the broader intent: scientific fidelity, explicit ownership, useful diagnostics and meaningful evidence.

Annotation syntax and placement belong to each detector. For example, Python silent-default contracts require a nonblank reason and cover specific expression boundaries; they do not grant a blanket exception to a function or permit fallback for environment or command-line inputs. The quality-check reference records those boundaries. Human review determines whether the explanation actually preserves the requirement.

Maintain the checks with the code

When adding an authored source root, update the source-inventory owner and its tests so the new tree is visible to the applicable scans and container grants. Keep the independently owned upstream submodule separate from local code conventions; scientific source checks verify its declared closure.

When changing a detector, preserve positive and negative examples of the actual requirement. When adapting a borrowed check, retain its exact source reference and explain the local ownership or semantic difference. The three crosswalks below record those decisions; historical import counts are not targets for the number of tests to run.

Implementation and port references

• Container and build checks — donor sources, retained obligations and local adaptations.
• Code-quality checks — detector provenance, inventories and annotation scope.
• Scientific checks — source closure, dependencies, artifacts and fixture evidence.

The command and execution descriptions above follow these source locations at revision 43b613ff36851a176184d57ae1af8a3d7607c431:

• Makefile — focused targets and the broader test composition.
• Repository branch of the container launcher — source grants, checker selection and suite selection.
• Git input preparation and engine-client configuration — host staging and cleanup ownership.
• Source inventory — discovery and its read-only-mount limitation.
• Checker runtime posture and operator-input fixtures — observed containment and recorded launcher calls.
• Lint and import-order checks — the pinned tool and selected authored roots.
• Documentation checks and discovery checks — their actual assertion scopes.