Code Standards

One deterministic quality gate for Sarj Python, TypeScript, Swift, Kotlin, shell, SQL, IaC, and repository policy.

Every repository receives one complete policy, including all 42 library policies. There is no standard/application selection. Legacy profile fields and preset filenames remain read-compatible aliases; newly written manifests omit the profile field. Warning-stage rules retain their reviewed severity. Rules requiring repository-specific boundaries still require those explicit options.

Adopt the complete policy, local hooks, and CI with one command:

uvx --no-config --isolated --python 3.15 --from code-standards code-standards setup

The canonical staged check includes semantic lint and repository policy; do not install a second Repo Standards hook.

Contributing

Install uv 0.13.5, Python 3.15, Node 24.22, and GNU Make. Then bootstrap a fresh checkout:

make setup
make verify

Run independent package suites with make test -j4, or focus on the fresh Standards wheel with make test-standards PYTEST_ARGS='-k release'. TEST_JOBS=1 serializes wheel tests (default: 4, maximum: 16). Python dogfood also uses TEST_JOBS, capped at two workers; TEST_JOBS=1 keeps it serial. Wheel tests build local exact sibling versions in a temporary wheelhouse and leave existing distribution output intact. Use make release-status COMMIT=origin/main to inspect exact-revision checks, publication, tagging, and rollout with queue and job durations. Preview affected test files with make test-plan BASE=origin/main, then run them against fresh local wheels with make test-standards-changed BASE=origin/main. Ordinary PR and main CI select affected packages and test cohorts; shared code, dependencies, workflows, missing comparisons, unknown paths, and uncertified comparison bases fall back to full coverage. Manual and weekly CI run every package and test. Test plans record selected files, fallback reasons, and elapsed time in the job summary.

On main, CI can reuse successful own-repository PR validation only when the checked Git tree and comparison base are identical. The verifier requires the latest successful CI run, matching run attempt, successful job, immutable artifact digest, and checked-tree certificate less than 24 hours old. It preserves the tested wheel bytes and submits reviewed CodeQL results for the actual main commit. Documentation source checks can be reused, while main builds and deploys the site afresh. Missing, expired, malformed, forked, changed or uncertified proofs fall back to fresh checks; PR, weekly and manual runs always perform fresh validation. The job summary links the source CI and explains reuse or fallback.

Publication reuses the successful exact-main CI artifact after checking its repository, event, commit, job result, and archive digest; missing/expired artifacts receive a fresh build and full wheel suite. Consumer portability repeats when shared runtime code can be affected. CLI smoke tests and a fresh revision-local pre-commit installation run concurrently; either failure blocks publication, and a second hook run must reuse its environment. Reproduce both lanes with make release-portability; CI retains separate logs and timings. Release detection uses the exact source-owned bootstrap pins without installing lint engines. Documentation deployment uses a separate locked Wrangler toolchain; reproduce its dry run with make docs-deploy-check after building the site. The underlying maintain release status --commit REV --format json command provides JSON. Release builds and portability checks overlap safety checks; publication still requires every check, exact public sibling version, verified artifact digest, and trusted-publisher attestation.

Create a rule with maintain rules new ENGINE:ID --category CATEGORY --summary TEXT --apply. Without --apply, the command shows its plan. Creation writes the detector and executable test, registers the rule, and reserves its identifier atomically. New rules default to warning. Run authoring commands through uv run --project packages/standards --frozen code-standards to use the source and dependencies of the checkout being edited. Implement the detector and replace the example placeholders, then verify and prepare it:

code-standards --root . maintain rules verify python:no-string-concat-in-loop
code-standards --root . maintain rules prepare python:no-string-concat-in-loop
code-standards --root . maintain rules evaluate --rule python:no-string-concat-in-loop --scope corpus
make verify

For reproducible multi-repository calibration, use an immutable public manifest and an optional owner-readable private overlay:

code-standards --root . maintain rules evaluate --rule python:no-string-concat-in-loop --corpus-manifest corpora.toml --private-overlay private-corpora.toml

After committing the resulting changes, review the complete rule diff:

code-standards --root . maintain rules changes --before origin/main --after HEAD

Rule comparison reads immutable Git blobs and fingerprints explicit local runtime imports from source and test modules. Type-only imports and data-only registry member edges are excluded; computed imports and TypeScript path aliases are not resolved. For TypeScript-bearing revisions, run make setup first to prepare the pinned Node and locked compiler in the authoring repository. Comparison never installs tools or falls back to text matching. Python-only revisions do not require Node.

Fleet calibration and downstream PR creation run automatically after review and release.

Fleet rollout

Copy .sarj-standards-rollout.example.toml to the ignored .sarj-standards-rollout.toml and register authorized consumers. Use an exact published bundle version:

make rollout-plan VERSION=<published-version>
make rollout-check VERSION=<published-version>
make rollout VERSION=<published-version>
make rollout-status VERSION=<published-version>

Add CONSUMER=owner/repository@branch to inspect or retry one consumer, DRY_RUN=1 to preview an apply, and JOBS=1 to serialize local work (default: 4). make rollout-reconcile resolves the latest published bundle when VERSION is omitted. make rollout-check verifies the published CLI and immutable source tag without a consumer registry. Consumer installs refresh only Code Standards metadata and retry a newly published version's index visibility with up to six 10-second waits; other install errors fail immediately. The planner briefly waits for a new tag to become visible after PyPI publication. Canary, early, and stable waves advance only after earlier waves merge; targeted retries retain that gate. The apply command reports PR creation independently of adoption.

Hosted reconciliation runs every 15 minutes and starts jobs only for consumers requiring work. Open verified PRs wait for their existing approvals. Pending adoption appears as pending in the durable issue; verification and transport failures still fail the workflow. Status exits 0 for complete adoption, 1 for pending adoption, and 2 for blocked or failed reads. Progress goes to stderr; stdout stays JSON with elapsedSeconds per consumer. The controller accepts --jobs (1 to 16) and --command-timeout (seconds, default: 900) before its subcommand. Registry consumers may opt into partial_clone = true when verification uses the checkout and its base. Full clones remain the default for verification that reads arbitrary history.

On POSIX hosts, preparation and verification check the remote base every 10 seconds with a bounded read. Confirmed movement cancels the candidate's dependency update, baseline, bootstrap, or verification processes, preserves their log tails, and leaves that consumer pending for reconciliation from the new base. Unavailable remote evidence does not cancel consumer work. Stable candidates still run every registered check, and independent base checks remain required before publication. Other hosts retain the existing verification runner and base checks. Bounded structured timings from consumer verifiers appear in progress logs so slow phases can be measured without changing test coverage.

Rule implementation

sarj-rule-contracts owns immutable metadata and executable example contracts. Each rule owns its documentation and positive/negative examples; generated catalogs and docs consume those declarations. Verification executes all examples, including private and multi-file cases, with the owning engine and runs the focused test file. A detector that always reports or never reports fails. TypeScript examples can also verify fixes and a clean second pass. Examples for opt-in rules declare fixture-specific ruleOptions, preserving consumer defaults. External declarations use installedDependencies with exact package names and versions. Run make setup first; the repository verifier supplies the installed TypeScript package root. Standalone verifyRuleExamples callers supply { installedDependencyRoot } for such examples. Verification installs nothing and fails for missing packages or identity/version drift.

Python rules implement check_context(context: PythonFileContext). The context shares parsing, breadth-first node indexing, parent lookup, import resolution, and generated-file detection across rules for one file. Use context.parents.get(node) to find a node's parent without rebuilding a map. Project discovery belongs to the analysis session; file facts expire after that file. The existing check(path, source) entrypoint delegates through a fresh context. SQL, IaC, and text retain their own parsers and diagnostics.

Native Python directory inputs prune dependency and cache trees before scanning them, and return files in sorted order. Explicit file arguments retain their supplied order.

Measure native Python analysis and diagnostic stability with:

code-standards --root . maintain rules bench packages/python/src --repeats 5

The JSON report includes file and byte counts, source and diagnostic digests, per-run timings, and process peak memory. Native timings exclude interpreter startup. Peak memory covers the current process's lifetime, including imports and earlier work, and excludes child processes; unsupported platforms report no memory measurement.

packages/python/benchmarks/compare.py alternates fresh baseline and candidate workers over the same baseline Python corpus. It reports native and startup-inclusive timings; operating-system caches remain untouched. Its default five-run medians do not establish tail latency, statistical confidence, or warm-cache edit performance. Implementation identities cover Python and contracts sources, selected local native/build artifacts, and selected build, dependency, and version inputs. Selected symlinks and unreadable inputs fail qualification. Installed dependencies and compiler caches excluded from these identities require separate environment qualification. Process peaks do not measure aggregate worker memory or establish an analysis-only memory improvement.

Rule artifact provenance

• Each rule's source-owned default_level is lifecycle policy. Severity is a reviewed decision, not something inferred from current findings.
• rule-inventory.v1.json and rule-catalog.v1.json are committed package/runtime projections of live registries and source-owned documentation. Check or regenerate them with maintain rules check|sync and maintain catalog check|sync.
• rule-ledger.json combines generated live identifiers with curated rename and retirement history; synchronize it with maintain sync-ledger.
• rule-calibration-campaign.v1.json is curated review evidence, not generated configuration.
• cli-reference.v1.json is generated from the parser graph with maintain cli-reference check|sync.

Documentation · Source