code-standards
One deterministic quality gate for Sarj Python, TypeScript, Swift, Kotlin, shell, SQL, IaC, and repository policy.
uv tool install --python 3.15 code-standards
Adopt the repository once with code-standards setup. It installs one canonical staged gate that includes semantic lint and repository policy, plus commit-message and pull-request history enforcement. Do not install Repo Standards separately.
The pre-commit gate runs once on every commit and discovers paths directly from the Git index, including mixed file types and deletion-only commits. The shared dispatcher selects applicable rules and retains type analysis, repository policy, exclusions and suppression accountability. Errors and incomplete analysis block the commit; warning-stage findings stay visible even when the hook passes. Agents should address the diagnostics, run code-standards fix --staged for safe mechanical fixes, review and stage intended edits, then retry. Staged fixes never fall back to the whole repository and refuse files with unstaged changes.
Setup installs the selected hook manager. In a fresh checkout, run code-standards doctor --repair before committing; doctor checks installation and the exact unconditional command. Conditional Lefthook jobs must be moved to an unconditional job without changing unrelated hooks. Git can bypass local hooks with --no-verify; the canonical CI gate independently enforces policy.
code-standards setup
code-standards check
code-standards check --rule python:no-excessive-cognitive-complexity src/
code-standards fix
code-standards doctor
code-standards update
Use repeatable check --rule ENGINE:ID selectors to select native rules, ESLint rules, or managed security audits. Exclusions, baselines, and severities still apply; Ruff selectors are not supported. Native linters and ESLint execute only selected rules. ESLint retains configured parsers, options, severities, and suppression directives.
Selected ESLint checks apply live inline suppressions and validate selected bulk suppression counts. The complete lint gate owns unused inline-directive and inline-configuration checks: a partial run cannot establish whether an unselected rule's directive is needed.
The complete Standards gate enforces Ruff's ban on typing.cast and typing_extensions.cast even when source comments, consumer Ruff configuration or manifest rule exceptions suppress banned-api; these cast findings cannot enter or consume the diagnostic baseline. Wildcard imports and literal getattr access to a proven typing module retain the same ban. Other banned APIs retain their existing exception policy. Prefer discriminated unions, explicit narrowing and typed contracts. The warning python:no-dual-shape-model-field-reader (SARJ522) identifies private helpers that read the same declared Pydantic fields through model getattr and mapping lookup branches, returning object or Any. Normalize raw input once and read typed attributes. Opaque inputs, raw validators and genuinely dynamic reflection remain supported. Review changes to missing-field handling, coercion, generated defaults and validation errors; there is no autofix.
Python boolean traps are owned by Ruff FBT001, FBT002 and FBT003: positional boolean annotations, defaults and literal arguments are checked; keyword-only inputs, named arguments and the existing test exemptions remain allowed. The typed ESLint policy uses @sarj/no-boolean-selector-parameter at warning severity. This adapter retains maintained SonarJS S2301 detection and adds concise-arrow conditional dispatch. Prefer separate intention-revealing operations or an explicit string-literal mode. Boolean data, syntactic value mappings, stable same-operation data choices, setters and independently declared callback or inherited contracts remain allowed. Independent JSX helpers are checked; types and references establish callback contracts. It requires type information and a direct broad-boolean parameter condition. Multi-statement bodies, short-circuit guards, nullable or literal-only inputs and indirect predicates remain outside its scope. The inherited upstream block-body onX property exemption remains a documented blind spot. Use code-standards check --rule eslint:no-boolean-selector-parameter to inspect it. Noncomputed property reads count as data without proving getter effects; computed reads, including literal keys, remain outside that exemption. API changes require manual review; the rule provides no automatic rewrite.
The shared ESLint policy also warns on unparenthesized assignments in returned expressions through native no-return-assign. Review whether the assignment should be a comparison or a separate state change; there is no automatic intent-changing fix. The native except-parens option accepts individually grouped assignments and common lazy memoization. Parentheses mark syntactic visibility, not proven intent: formatters can add or remove them without changing behavior. A chained assignment can still warn after formatting even when its outer expression is grouped. For an intentional local-variable chain, use separate assignment statements followed by return. Upstream may report several writes at the same return location. This rule does not prohibit all returned mutations or prove command/query separation. Existing typed void-return and Promise checks retain their own boundaries; an executor's returned expression alone does not prove a broken Promise.
The shared ESLint policy includes @shadcn/lint design-system guidance at warning severity. It runs where upstream discovery finds components.json or a Tailwind theme, or where the consumer explicitly declares settings.shadcn.ui or componentImports. Ordinary CSS projects receive no Tailwind-specific findings. Component layout classes and arbitrary layout measurements remain allowed; appearance overrides and off-token appearance values receive guidance. Discovered component implementation files are exempt from restyling, arbitrary-value and static-class checks, while inline-style and unknown-class checks remain active. Raw colors remain owned by @sarj/prefer-semantic-colors.
Use code-standards check --rule eslint:shadcn/no-restyle to inspect one upstream rule. Declare shared-package imports and custom class helpers in settings.shadcn, scoped to each application's files in the consumer's ESLint configuration. Add reviewed component contracts or exact class/property allowances through the upstream rule options; do not replace every warning with a global error. Tailwind theme-loading warnings indicate grammar fallback with reduced coverage. The project-discovery API is experimental and is protected by an exact dependency pin and executable integration tests.
Terraform, Kubernetes, and GitHub Actions adoption adds isolated Checkov 3.3.28 and zizmor 1.31.1 runtimes. Setup and generated CI prewarm these tools; checks run offline with packaged policy. Use --rule checkov:CKV_GCP_95 or --rule zizmor:template-injection to select upstream audits. Their findings start as warnings, use the canonical diagnostic baseline, and retain upstream IDs. Checkov honors its inline suppression directives; zizmor ignore comments are disabled. Explicit zizmor selectors include auditor-persona checks; online-only audits cannot run offline. Parsing or execution failures leave the analysis incomplete. Image digest evidence for source templates is deferred to their rendered deployment artifacts.
The opt-in jscpd capability runs the jscpd 5.4.0 copy-paste detector, which setup installs through mise. Setup and upgrades list it in [capabilities].disable; remove it there to enable it. Each check scans Python, TypeScript, Swift and Kotlin source outside test directories, because a copy can only be found by comparing it with the whole tree. Every repeated block of at least 50 tokens is a jscpd:duplicate-code warning on its own lines that names the other copies, so the changed-line baseline reports it when either side is edited. The repository's own jscpd configuration is ignored.
The shfmt capability checks shell files, including extensionless shebang entrypoints, with shfmt 3.14.1 using two-space indentation and indented case clauses. Explicit, staged and PR-selected files must be formatted in full; full scans report existing drift as warnings. Formatting errors on selected files cannot be hidden by a diagnostic baseline. code-standards fix formats selected files safely, preserving executable permissions; generated Gradle launchers are excluded. Shebangs determine the shell before filename suffixes, including supported shells at custom absolute paths. Bats files use the upstream Bats formatter dialect. Zsh formatting does not provide ShellCheck coverage: its unsupported dialect remains an explicit coverage failure. Ambient editor settings cannot change the canonical style, and simplification is disabled.
Shell libraries with a shell suffix or no suffix can declare their dialect with a top-level # shellcheck shell=bash header before executable source. Quoted dialect values and preceding directive fields are supported. An executable shebang remains authoritative. Generated Gradle exclusions require the exact generator comment in the source header; mentions in strings, heredocs and ordinary prose do not exempt authored scripts. Automatic fixes refuse native formatter output that removes carriage-return bytes, so literal data and line endings need manual review in those cases.
ShellCheck and shfmt also inspect executable shell fields in workflows, composite actions, Cloud Build, Make and Mise using the same policy as shell files. Analysis follows the configured interpreter, including inherited Actions shells and Cloud Build shebangs, and reports positions in the authored configuration. Actions expressions are masked for native parsing with their quoted string boundaries preserved, and actionlint retains workflow validation while shared ShellCheck supplies shell findings once. Docker shell semantics remain owned by Hadolint. Fixes can format verified literal YAML blocks while preserving scalar headers, newlines and decoded execution source. Folded scalars, aliases, templates, argv, Make and Mise remain check-only; extract complex programs to shell files for independently linted execution.
The shared argv parser records effective errexit and pipefail options in order, including later +e and +o disables. Interpreter option operands and arguments after the script or command payload do not activate runtime checks.
The shared ShellCheck policy enables check-set-e-suppressed alongside the existing check-extra-masked-returns. SC2310 and SC2311 warn when function calls suppress set -e, including conditional calls and command substitutions. Review intentional predicates and use justified native ShellCheck suppressions where appropriate; these findings have no automatic semantic fix. SC2312 remains enabled to detect masked exit status. The repository shell gate prints the new warnings without failing for them and retains its existing blocking checks. The managed .shellcheckrc retains the existing native gate checks; Standards enables these advisory checks explicitly because direct ShellCheck exits nonzero for informational findings.
For concise Bash, preserve arguments with quoted expansions and command arrays, use a literal printf format, and handle fallible commands explicitly. Built-in lookup and parameter expansion can replace external commands when their lookup, output and exit-status contracts agree. These choices use existing upstream checks; intentional stream contracts and predicates require review rather than automatic semantic rewrites.
The opt-in knip capability uses Knip 6.41.0 production mode. Remove it from [capabilities].disable and declare application = true under [knip] to enable advisory knip:files evidence. Version one supports a single private application with entry and project arrays containing production patterns ending in ! in knip.json or .knip.json. Native aliases and framework entries remain authoritative; unresolved imports, configuration diagnostics, workspaces and dynamic configuration make the graph inconclusive. Review runtime and public owners before deleting a module. No automatic fixes or application inference are performed.
Unused private Python test helpers require reportUnusedFunction set to warning in the consumer's existing BasedPyright test execution environments. This bundle preserves native configuration and bounds test warnings to authored, undecorated module-level private helpers in conventional test paths. Decorated fixtures, methods and production callbacks are excluded; no consumer diagnostic setting is enabled automatically. Existing production diagnostics are preserved.
check --jobs 2 overlaps native analysis with the external-tool pipeline. The default is --jobs 1; external tools remain sequential and report ordering is deterministic.
DevOps execution blocks may sequence existing commands without helper scripts. Keep interpreter source, control flow, logical chains, pipelines and substitutions in independently linted files; Python -m and script paths, and jq/awk -f files remain supported. SARJ310 is an error, including short inline programs. Cloud Build SARJ315 checks unique IDs, ordered step dependencies, script/argv exclusivity and rejects untrusted substitutions in shell source; pass substitutions as quoted arguments to external scripts.
The source gate uses pinned actionlint, shared ShellCheck, offline Zizmor, Hadolint and Skaffold v4beta7 schema validation. Cloud Deploy validation is a documented partial structural contract. Terraform validation and TFLint require explicit repository trust and prepared local providers; analysis never initializes or downloads them. Compose requires an exact consumer [devops].compose_version; its source check does not resolve environment inputs.
Release gates use code-standards analyze --prepared-only --prepared-devops prepared.json --prepared-target TARGET_ID. Declare exact prepared_targets under [devops] with an authored source path. Version-one receipts bind target IDs, authored input hashes, staged chart archives, ordered values, typed set arguments, manifests and a hashed local schema closure. Helm 4.3.0 strict lint and stage-specific rendering feed kubeconform 0.8.0 and kube-linter 0.8.3. Missing tools, schemas, targets and invalid receipts fail the gate. Prepared-only findings bypass source debt baselines; container exceptions require exact target, GVK, namespace, object, check, container kind, container name and a reason, and stale exceptions fail.
Prepared YAML rejects duplicate parsed keys and cyclic aliases. Each document must stay below depth 64 and at or below 100,000 expanded nodes, including repeated aliases.
Source-only checks report prepared validation as deferred. They do not certify generated manifests or replace Cloud Deploy, Cloud Build or Kubernetes admission validation. Run setup --tools-only in CI after installing the bundle and the pinned mise bootstrap. It requires an existing manifest, installs and attests the applicable native tools, and preserves repository wiring. Release analysis consumes prepared bytes without pulling charts.
1 maintainer
Metadata
1 maintainer
Release files for code-standards 8.102.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| code_standards-8.102.0.tar.gz | 925.5 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| code_standards-8.102.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.9 MB
Release files / code_standards-8.102.0.tar.gz
| Download URL | code_standards-8.102.0.tar.gz |
|---|---|
| Size | 925.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
39dc34c7634027a54ecf25517e2e30190004e6fe46f22e34716312eb9e7d00c7
|
|
BLAKE2b-256 checksum How to use checksums |
460331bc001d1f1de2dfe9354159fe7cf4eceb7a7fea83f8cbc99995744852c6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logRelease files / code_standards-8.102.0-py3-none-any.whl
| Download URL | code_standards-8.102.0-py3-none-any.whl |
|---|---|
| Size | 1.0 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d0867ef4774bfbedc0b4ba5835967ac49bfca0bb390e3b72c948bac9aba9ead9
|
|
BLAKE2b-256 checksum How to use checksums |
602bd458be9b0ca0ad7a4db537d46c6e3f720d2f3cf918f0d61b8c01ada0e10c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logSecurity for code-standards 8.102.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for code_standards-8.102.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
