Metadata-Version: 2.5
Name: code-standards
Version: 8.47.5
Summary: One deterministic quality gate for Sarj Python, TypeScript, Swift, Kotlin, shell, SQL, IaC, and repository policy.
Project-URL: Homepage, https://code-standards.sarj.ai/
Project-URL: Documentation, https://code-standards.sarj.ai/cli/
Project-URL: Changelog, https://github.com/sarj-ai/code-standards/releases
Project-URL: Repository, https://github.com/sarj-ai/code-standards
Project-URL: Issues, https://github.com/sarj-ai/code-standards/issues
Author: sarj-ai
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.14
Requires-Dist: basedpyright==1.40.1
Requires-Dist: deptry==0.25.1
Requires-Dist: jsonschema==4.25.1
Requires-Dist: lefthook==2.1.14
Requires-Dist: packaging==26.3
Requires-Dist: pathspec==1.1.1
Requires-Dist: pre-commit==4.6.2
Requires-Dist: pydantic==2.14.0
Requires-Dist: pyyaml==6.0.3
Requires-Dist: referencing==0.37.0
Requires-Dist: repo-standards==6.4.2
Requires-Dist: ruff==0.16.10
Requires-Dist: sarj-iac-lint==0.19.3
Requires-Dist: sarj-python-lint==1.28.2
Requires-Dist: sarj-rule-contracts==0.2.2
Requires-Dist: sarj-sql-lint==0.18.16
Requires-Dist: shellcheck-py==0.11.0.1; (sys_platform == 'darwin' and platform_machine == 'arm64') or (sys_platform == 'darwin' and platform_machine == 'x86_64') or (sys_platform == 'linux' and platform_machine == 'x86_64') or (sys_platform == 'win32' and platform_machine == 'AMD64')
Requires-Dist: typer==0.27.2
Description-Content-Type: text/markdown

<!-- Generated by `code-standards maintain docs sync`; do not edit. -->

# code-standards

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

```bash
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.

```bash
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.

Terraform, Kubernetes, and GitHub Actions adoption adds isolated Checkov 3.3.20 and zizmor 1.30.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. 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. 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, 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 3.19.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.

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.

[Documentation](https://code-standards.sarj.ai/) · [Source](https://github.com/sarj-ai/code-standards)
