Setup

Install once, set up the repository, verify it, then run the full check.

uv tool install --python 3.14 code-standards
code-standards setup
code-standards doctor
code-standards check

Run once

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

1. setupInstall the shared configuration and repository hooks.
2. doctorCheck the installation and repair configuration drift.
3. checkRun the same standards locally and in CI.
4. fixApply safe automated fixes, then report what remains.

One Standards version in TOML

Generated hooks and CI invoke uvx --no-config --isolated --python 3.14 --from sarj-standards-bootstrap code-standards. uvx installs and caches the lightweight bootstrap, which reads the exact bundle version from .sarj-standards.toml. No mise integration or repository-local launcher script is needed.

Run uvx --no-config --isolated --python 3.14 --from sarj-standards-bootstrap code-standards doctor --repair to migrate older managed launchers and reconcile configuration and hooks. The bootstrap is intentionally unpinned; the linting release remains exactly pinned in the manifest.

A cold cache resolves and installs the bootstrap; subsequent invocations reuse it without requesting a refresh on every hook. Offline execution requires the bootstrap, the selected bundle, their Python runtime, and dependencies to be cached already.

A directly installed repo-standards dependency belongs in pyproject.toml and its resolved lockfile, not in repeated shell commands. Lockfile entries and generated provenance are reproducibility records, not additional versions to maintain by hand.

Mobile projects

Swift and Kotlin checks are fail-closed and opt in only when setup finds a real Apple mobile project (iOS, tvOS, watchOS, or visionOS) or an applied Android/Kotlin Multiplatform mobile plugin. Server-side Swift, JVM-only Kotlin, unused version-catalog entries, dependency trees, and generated output do not activate the mobile baseline.

The generated pre-commit or Lefthook command checks staged .swift, .kt, and .kts files inside the recorded mobile destination. Swift runs SwiftFormat, SwiftLint, and the MobSF security rules; Kotlin runs ktlint, Detekt, and the same security layer. Multiple independent mobile roots fail setup until one reviewed owner is selected with --swift-dest or --kotlin-dest.

Swift checks require macOS and Xcode command-line tools. Kotlin checks require Java. The first run downloads version-, commit-, and checksum-pinned tools plus 51 checksum-pinned MobSF rules and may take several minutes; generated mobile CI allows 60 minutes. Later runs reuse the managed cache. Semgrep parse warnings and incomplete file coverage fail the security check instead of being reported as clean.

The fast Detekt pre-commit tier is source-only. Projects that use Compose, public-ABI, or type-resolution Detekt plugins should keep their Gradle detektMain and Android Lint tasks as an additional CI gate; Standards does not claim those project-aware checks ran from a standalone file invocation.

Generated analysis inputs

When lint configuration imports ignored build or code-generation output, declare the exact preparation commands in .sarj-standards.toml. show ci emits them after dependency installation and before analysis; Standards never guesses a repository build script.

[ci]
bootstrap = ["yarn generate", "uv run --project python generate-api"]

commit-messagedoctorsetupcheckvalidate-slack-automationsobservefixupdatebaselineratchetexcludeshow

Global options

-h, --help

Show this message and exit.

--root DEST

repository root shared by the selected command (default: current directory)

--version

code-standards commit-message

enforce [(i/N) ][TICKET] type(scope)!: description with safe mechanical fixes

Usage

code-standards commit-message [-h] COMMIT_MSG_FILE

Options (1)

COMMIT_MSG_FILE

Git commit-message file supplied by the commit-msg hook

code-standards doctor

diagnose adoption health and optionally repair safe drift

Usage

code-standards doctor [-h] [--format OUTPUT_FORMAT] [--repair] [--no-install]

Options (3)

--format OUTPUT_FORMAT

output format (default: text) Choices: text, json

--repair

transactionally repair safe drift with the executing bundle, then re-diagnose

--no-install

with --repair, update configuration without installing dependencies or hooks

code-standards setup

adopt or converge the repository in one idempotent operation

Usage

code-standards setup [-h] [--hooks HOOKS] [--python-dest PYTHON_DEST] [--typescript-dest TYPESCRIPT_DEST] [--swift-dest SWIFT_DEST] [--kotlin-dest KOTLIN_DEST] [--dry-run] [--force] [--no-install] [--commit-policy-only] [--config ONLY ...]

Options (10)

--hooks HOOKS

hook manager (default: detect Lefthook, otherwise pre-commit) Choices: pre-commit, lefthook, none

--python-dest PYTHON_DEST

the directory that owns pyproject.toml (default: detected)

--typescript-dest TYPESCRIPT_DEST

the directory that owns the npm lockfile (default: detected)

--swift-dest SWIFT_DEST

the directory that owns one reviewed Swift project (default: mobile project detection)

--kotlin-dest KOTLIN_DEST

the directory that owns one reviewed Android/KMP project (default: detected)

--dry-run

print the complete plan without writing

--force

replace conflicting generated lint configuration after review

--no-install

write wiring without installing dependencies or hooks

--commit-policy-only

adopt only commit-message and PR-history policy without changing language tooling

--config ONLY

select one config explicitly (repeatable) Choices: detekt, eslint, ktlint, markdownlint, mobile-security, pyright, ruff, shellcheck, swiftformat, swiftlint, taplo, yamllint

code-standards check

run the complete quality gate or check selected paths or custom rules

Usage

code-standards check [-h] [--trust-repository-code] [--staged] [--rule SELECTED_RULES ...] [--format OUTPUT_FORMAT] [--output OUTPUT] [--max-annotations-per-level MAX_ANNOTATIONS_PER_LEVEL] [FILES ...]

Options (7)

--trust-repository-code

allow executable repository ESLint configuration (generated hooks and CI set this explicitly)

--staged

run custom rules on hook-supplied paths, or discover staged files when none are supplied

--rule SELECTED_RULES

check only this custom ENGINE:ID rule (repeatable)

--format OUTPUT_FORMAT

See command help. Choices: text, json, sarif, github

--output OUTPUT

write JSON or SARIF atomically to PATH

--max-annotations-per-level MAX_ANNOTATIONS_PER_LEVEL

See command help.

FILES

selected paths; when omitted, check the complete repository

code-standards validate-slack-automations

validate a versioned Slack automation catalog

Usage

code-standards validate-slack-automations [-h] PATH

Options (1)

PATH

See command help.

code-standards observe

report warning-stage findings with exit 0; invalid input or execution still exits 2

Usage

code-standards observe [-h] --rule SELECTED_RULES ... [--format OUTPUT_FORMAT] [--output OUTPUT] [--trust-repository-code] [--max-annotations-per-level MAX_ANNOTATIONS_PER_LEVEL] [FILES ...]

Options (6)

--rule SELECTED_RULES

canonical ENGINE:ID selector (repeatable)

--format OUTPUT_FORMAT

See command help. Choices: text, json, sarif, github

--output OUTPUT

See command help.

--trust-repository-code

allow repository ESLint configuration to execute

--max-annotations-per-level MAX_ANNOTATIONS_PER_LEVEL

See command help.

FILES

selected paths; defaults to adopted verification paths

code-standards fix

apply safe formatting and lint fixes

Usage

code-standards fix [-h] [--staged] [FILES ...]

Options (2)

--staged

fix only files staged in Git

FILES

selected paths; when omitted, fix the complete repository

code-standards update

upgrade to the latest published coherent Standards bundle

Usage

code-standards update [-h] [--check] [--offline] [--to VERSION] [--no-install]

Options (4)

--check

preview without writing; exit 1 when changes exist

--offline

reconverge the executing bundle and skip every network-dependent install; does not resolve latest

--to VERSION

resolve and apply exactly this immutable coherent bundle version

--no-install

do not install dependencies or hooks

code-standards baseline

grandfather today's findings so only new ones fail

Usage

code-standards baseline [-h] {init,update}

code-standards baseline init

record the first diagnostic baseline

Usage

code-standards baseline init [-h] [--output OUTPUT] [--trust-repository-code] [FILES ...]

Options (3)

--output OUTPUT

baseline JSON (default: diagnostic-baseline.json)

--trust-repository-code

run repository-local analyzers that execute project code

FILES

paths to analyze (default: the whole repository)

code-standards baseline update

re-record the diagnostic baseline after reviewed cleanup

Usage

code-standards baseline update [-h] [--output OUTPUT] [--trust-repository-code] [--rule BASELINE_RULES ...] [FILES ...]

Options (4)

--output OUTPUT

baseline JSON (default: diagnostic-baseline.json)

--trust-repository-code

run repository-local analyzers that execute project code

--rule BASELINE_RULES

replace debt only for this newly promoted rule (repeatable; source:RULE is also accepted)

FILES

paths to analyze (default: the whole repository)

code-standards ratchet

keep the Python suppression budget from growing

Usage

code-standards ratchet [-h] {init,check,status,update}

code-standards ratchet init

create the first suppression budget

Usage

code-standards ratchet init [-h] [--baseline BASELINE] [--package PACKAGE ...] [--exclude-subtree EXCLUDE_SUBTREE ...]

Options (3)

--baseline BASELINE

budget JSON (default: suppression-baseline.json)

--package PACKAGE

Python package root (repeatable)

--exclude-subtree EXCLUDE_SUBTREE

generated or vendored subtree to persistently exclude (repeatable)

code-standards ratchet check

fail when suppression debt grows

Usage

code-standards ratchet check [-h] [--baseline BASELINE] [--package PACKAGE ...] [--exclude-subtree EXCLUDE_SUBTREE ...]

Options (3)

--baseline BASELINE

budget JSON (default: suppression-baseline.json)

--package PACKAGE

Python package root (repeatable)

--exclude-subtree EXCLUDE_SUBTREE

generated or vendored subtree to persistently exclude (repeatable)

code-standards ratchet status

show current suppression debt and available reductions

Usage

code-standards ratchet status [-h] [--baseline BASELINE] [--package PACKAGE ...] [--exclude-subtree EXCLUDE_SUBTREE ...]

Options (3)

--baseline BASELINE

budget JSON (default: suppression-baseline.json)

--package PACKAGE

Python package root (repeatable)

--exclude-subtree EXCLUDE_SUBTREE

generated or vendored subtree to persistently exclude (repeatable)

code-standards ratchet update

lock in reviewed suppression-budget changes

Usage

code-standards ratchet update [-h] [--baseline BASELINE] [--package PACKAGE ...] [--exclude-subtree EXCLUDE_SUBTREE ...] [--allow-increase]

Options (4)

--baseline BASELINE

budget JSON (default: suppression-baseline.json)

--package PACKAGE

Python package root (repeatable)

--exclude-subtree EXCLUDE_SUBTREE

generated or vendored subtree to persistently exclude (repeatable)

--allow-increase

permit a reviewed increase in suppression debt

code-standards exclude

inspect or change explicit path and rule exclusions

Usage

code-standards exclude [-h] {list,add,remove}

code-standards exclude list

list the complete denylist

Usage

code-standards exclude list [-h]

code-standards exclude add

add one exact denylist entry

Usage

code-standards exclude add [-h] {path,rule} VALUE

Options (2)

{path,rule}

See command help. Choices: path, rule

VALUE

repository-relative glob or canonical engine:rule selector

code-standards exclude remove

remove one exact denylist entry

Usage

code-standards exclude remove [-h] {path,rule} VALUE

Options (2)

{path,rule}

See command help. Choices: path, rule

VALUE

repository-relative glob or canonical engine:rule selector

code-standards show

print read-only package and adoption information

Usage

code-standards show [-h] {state,configs,config,peers,rules,ci}

code-standards show state

print detected adoption state as JSON

Usage

code-standards show state [-h]

code-standards show configs

list bundled configurations

Usage

code-standards show configs [-h]

code-standards show config

print one bundled configuration path

Usage

code-standards show config [-h] NAME

Options (1)

NAME

See command help. Choices: detekt, eslint, ktlint, markdownlint, mobile-security, pyright, ruff, shellcheck, swiftformat, swiftlint, taplo, yamllint

code-standards show peers

show tested ESLint peer dependencies and install command

Usage

code-standards show peers [-h]

code-standards show rules

print the machine-readable custom-rule inventory

Usage

code-standards show rules [-h]

code-standards show ci

print a complete versioned GitHub Actions standards workflow

Usage

code-standards show ci [-h] [--output OUTPUT]

Options (1)

--output OUTPUT

write a managed workflow inside the repository