code-standards 8.147.21__tar.gz → 8.151.0__tar.gz

{code_standards-8.147.21 → code_standards-8.151.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: code-standards
-Version: 8.147.21
+Version: 8.151.0
 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/
@@ -30,10 +30,10 @@ Requires-Dist: pyyaml==6.0.3
 Requires-Dist: referencing==0.37.0
 Requires-Dist: repo-standards==6.14.0
 Requires-Dist: ruff==0.17.2
-Requires-Dist: sarj-iac-lint==0.30.3
-Requires-Dist: sarj-python-lint==1.84.0
-Requires-Dist: sarj-rule-contracts==0.4.2
-Requires-Dist: sarj-sql-lint==0.30.1
+Requires-Dist: sarj-iac-lint==0.31.0
+Requires-Dist: sarj-python-lint==1.88.0
+Requires-Dist: sarj-rule-contracts==0.5.0
+Requires-Dist: sarj-sql-lint==0.33.0
 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.3
 Description-Content-Type: text/markdown
@@ -105,6 +105,8 @@ Unused private Python test helpers require `reportUnusedFunction` set to `warnin
 
 `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.
 
+Public Python suggested edits retain `expected_source_hash`, the lowercase SHA-256 digest of the exact captured source bytes, alongside `expected_text_hash` for the replaced slice. Use `to_json(report, include_fix_source_hashes=True)` or the same keyword on report, diagnostic, fix or edit `as_dict` to emit `expectedSourceHash`. The default JSON output is unchanged. Opted-in JSON requires the updated bundled `analysis.schema.json`; older strict v1 schemas reject the added field. This provenance does not apply edits or validate a current file, and SARIF output is unchanged.
+
 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 YAML and JSON for unique IDs, ordered step dependencies, script/argv exclusivity and untrusted substitutions in shell source; pass substitutions as quoted arguments to external scripts. JSON configs are discovered in operational directories or with `cloudbuild` in their filename; JSON syntax must be strict, with unique keys and finite numbers. Files named with `cloudbuild`, and Build-shaped files under a `cloudbuild` directory, use the bundled, digest-verified Google Build v1 field schema for field names, types, enums and protobuf durations/integers. The offline schema rejects output-only fields; trigger expansion, resource access and hosted admission require the deployment environment.
 
 The source gate uses pinned actionlint, shared ShellCheck, offline Zizmor, Hadolint and Skaffold v4beta7 schema validation. Every selected `action.yml`/`action.yaml` uses GitHub's pinned action parser and converter offline, including composite steps, expression syntax and available contexts, runtime requirements, step IDs and action-reference forms. This uses the core Node runtime and needs no referencing workflow, consumer npm setup or security capability. 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. Declare `compose_projects = [["base.yaml", "overlays/production.yaml"]]` in `[devops]` to validate custom filenames and overlays in invocation order. Selecting any member checks the whole project; declared fragments are not checked independently. Undeclared conventional filenames remain standalone projects. Missing inputs and native field errors fail coverage. Source checks use Compose's partially resolved model; full consistency requires the actual deployment environment.

{code_standards-8.147.21 → code_standards-8.151.0}/README.md

@@ -65,6 +65,8 @@ Unused private Python test helpers require `reportUnusedFunction` set to `warnin
 
 `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.
 
+Public Python suggested edits retain `expected_source_hash`, the lowercase SHA-256 digest of the exact captured source bytes, alongside `expected_text_hash` for the replaced slice. Use `to_json(report, include_fix_source_hashes=True)` or the same keyword on report, diagnostic, fix or edit `as_dict` to emit `expectedSourceHash`. The default JSON output is unchanged. Opted-in JSON requires the updated bundled `analysis.schema.json`; older strict v1 schemas reject the added field. This provenance does not apply edits or validate a current file, and SARIF output is unchanged.
+
 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 YAML and JSON for unique IDs, ordered step dependencies, script/argv exclusivity and untrusted substitutions in shell source; pass substitutions as quoted arguments to external scripts. JSON configs are discovered in operational directories or with `cloudbuild` in their filename; JSON syntax must be strict, with unique keys and finite numbers. Files named with `cloudbuild`, and Build-shaped files under a `cloudbuild` directory, use the bundled, digest-verified Google Build v1 field schema for field names, types, enums and protobuf durations/integers. The offline schema rejects output-only fields; trigger expansion, resource access and hosted admission require the deployment environment.
 
 The source gate uses pinned actionlint, shared ShellCheck, offline Zizmor, Hadolint and Skaffold v4beta7 schema validation. Every selected `action.yml`/`action.yaml` uses GitHub's pinned action parser and converter offline, including composite steps, expression syntax and available contexts, runtime requirements, step IDs and action-reference forms. This uses the core Node runtime and needs no referencing workflow, consumer npm setup or security capability. 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. Declare `compose_projects = [["base.yaml", "overlays/production.yaml"]]` in `[devops]` to validate custom filenames and overlays in invocation order. Selecting any member checks the whole project; declared fragments are not checked independently. Undeclared conventional filenames remain standalone projects. Missing inputs and native field errors fail coverage. Source checks use Compose's partially resolved model; full consistency requires the actual deployment environment.

{code_standards-8.147.21 → code_standards-8.151.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "code-standards"
-version = "8.147.21"
+version = "8.151.0"
 description = "One deterministic quality gate for Sarj Python, TypeScript, Swift, Kotlin, shell, SQL, IaC, and repository policy."
 readme = "README.md"
 requires-python = ">=3.14"
@@ -17,7 +17,7 @@ classifiers = [
   "Topic :: Software Development :: Quality Assurance",
 ]
 dependencies = [
-  "sarj-rule-contracts==0.4.2",
+  "sarj-rule-contracts==0.5.0",
   "pathspec==1.1.1",
   "basedpyright==1.40.2",
   "deptry==0.25.1",
@@ -31,9 +31,9 @@ dependencies = [
   "repo-standards==6.14.0",
   "ruff==0.17.2",
   "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')",
-  "sarj-iac-lint==0.30.3",
-  "sarj-python-lint==1.84.0",
-  "sarj-sql-lint==0.30.1",
+  "sarj-iac-lint==0.31.0",
+  "sarj-python-lint==1.88.0",
+  "sarj-sql-lint==0.33.0",
   "typer==0.27.3",
 ]
 

{code_standards-8.147.21 → code_standards-8.151.0}/src/sarj_standards/api.py

@@ -56,6 +56,7 @@ from .libs.diagnostics import (
 from .libs.filesystem import is_link_like
 from .libs.linting.analysis import analyze as analyze_paths, report_from_tools
 from .libs.linting.complexity_baseline import ComplexityBaselineResolver
+from .libs.linting.execution_plan import analysis_jobs
 from .libs.linting.external import UpstreamESLintRules, analyze_external
 from .libs.linting.library_policy import (
     ManifestPolicyError,
@@ -137,6 +138,17 @@ class Result:
     changes: tuple[Change, ...] = ()
     exit_code: int = 0
 
+    def __post_init__(self) -> None:
+        if type(self.status) is not Status:
+            msg = "result status must be a Status"
+            raise TypeError(msg)
+        if isinstance(self.exit_code, bool) or not isinstance(self.exit_code, int):  # pyright: ignore[reportUnnecessaryIsInstance] -- validate untyped public constructor and dataclass replacement calls as well as typed callers.
+            msg = "result exit code must be an integer"
+            raise TypeError(msg)
+        if (self.status in {Status.OK, Status.CHANGED}) != (self.exit_code == 0):
+            msg = "result status and exit code must agree on success"
+            raise ValueError(msg)
+
     @property
     def ok(self) -> bool:
         return self.exit_code == 0
@@ -269,10 +281,9 @@ class Standards:
     ) -> AnalysisReport:
         try:
             import_context = initial_import.load(self.root, staged=staged)
+            analysis_jobs(jobs)
         except ValueError as exc:
             return _failed_analysis(self.root, "invalid-input", str(exc))
-        if jobs not in {1, 2}:
-            return _failed_analysis(self.root, "invalid-input", "analysis jobs must be 1 or 2")
         external = external or bool(upstream_rules.ids)
         try:
             normalized_trust = TrustMode(trust)
@@ -300,7 +311,7 @@ class Standards:
         try:
             selection_policy = _selection_policy(self.root, adopted, normalized_mode)
             rule_selection = _rule_selection(rules)
-            selected = _analysis_inputs(self.root, paths, mode=normalized_mode)
+            selected = _analysis_inputs(self.root, paths, adopted=adopted, mode=normalized_mode)
         except (OSError, TypeError, ValueError) as exc:
             return _failed_analysis(self.root, "invalid-input", str(exc))
         try:
@@ -512,7 +523,8 @@ class Standards:
             )
             return Result(Status.FAILED, findings=(finding,), exit_code=1)
         finding = Finding("update.latest.failed", "error", output or "latest standards update failed")
-        return Result(Status.FAILED, findings=(finding,), exit_code=completed.returncode)
+        status = Status.INTERRUPTED if completed.returncode == _INTERRUPTED_EXIT else Status.FAILED
+        return Result(status, findings=(finding,), exit_code=completed.returncode)
 
     def inspect(self) -> Inspection:
         return inspect(self.root)
@@ -823,13 +835,14 @@ def _with_coverage(report: AnalysisReport, coverage: Sequence[CoverageNotice]) -
     return AnalysisReport(report.root, completion, conclusion, report.tools, notices)
 
 
-def _analysis_inputs(root: Path, paths: Sequence[str] | None, *, mode: AnalysisMode = AnalysisMode.POLICY) -> list[str]:
+def _analysis_inputs(
+    root: Path, paths: Sequence[str] | None, *, adopted: Manifest | None, mode: AnalysisMode
+) -> list[str]:
     if paths is not None:
         selected = _contained_paths(root, paths)
         return selected if mode is AnalysisMode.RAW else _with_tracked_terraform_tests(root, selected)
     if mode is AnalysisMode.RAW:
         return [str(root)]
-    adopted = load_manifest(root)
     verify_paths = adopted.verify_paths if adopted is not None else (".",)
     return _with_tracked_terraform_tests(root, [str(root / path) for path in verify_paths])
 

{code_standards-8.147.21 → code_standards-8.151.0}/src/sarj_standards/configs/cli-reference.v1.json

@@ -3316,6 +3316,6 @@
   },
   "program": "code-standards",
   "schemaVersion": 1,
-  "summary": "Adopt, check, fix, diagnose, and update sarj-ai standards (v8.147.21).",
-  "version": "8.147.21"
+  "summary": "Adopt, check, fix, diagnose, and update sarj-ai standards (v8.151.0).",
+  "version": "8.151.0"
 }

{code_standards-8.147.21 → code_standards-8.151.0}/src/sarj_standards/configs/rule-calibration-campaign.v1.json

@@ -2949,6 +2949,102 @@
       "state": "pending",
       "evidence": "Known Any/object/JsonValue string mappings, unchecked JSON, local returns, aliases and chained reads have paired controls. Precise maps, TypedDicts, raw normalization callbacks and unproven receivers retain their documented boundaries. The pinned pre-integration record packages/python/benchmarks/typed-python-boundaries.json covers five affected rules with 111 valid labeled cases (51 TP, 60 TN, zero inspected FP/FN) and three explicit malformed-source rejections. Its repeated cold/warm measurements retain their historical source frame; they are not fleet-recall or combined-current-engine performance claims. Private source and identifying pins remain private. Broader field calibration remains pending.",
       "outcome": "Ship SARJ535 at WARNING without autofix. Validate external data into named models and use precise trusted internal contracts. Preserve typed get calls and review missing-field/default behavior manually; field calibration remains pending."
+    },
+    {
+      "task": "rule-audit/python/prefer-optional-composite",
+      "family": "python",
+      "ruleId": "prefer-optional-composite",
+      "state": "pending",
+      "evidence": "2026-10-28 bounded SQL/model review. Focused examples and regressions cover explicitly nullable field groups, annotation ownership, aliases, overlapping prefixes, and valid independent state. The shared immutable 35-file comparison against published 8.147.0 reports 71 reviewed additions, zero removals or duplicates, and six repaired false-positive controls clear across the affected owners. These aggregate observations are not per-rule precision or recall estimates. Broader field calibration remains pending.",
+      "outcome": "SARJ541: Stage at WARNING without autofix. Review an optional composite without inferring joint presence from a name prefix; preserve public wire/schema contracts and independent nullability. Full campaign completion is not claimed."
+    },
+    {
+      "task": "rule-audit/python/no-custom-control-flow-exception",
+      "family": "python",
+      "ruleId": "no-custom-control-flow-exception",
+      "state": "pending",
+      "evidence": "2026-10-28 bounded SQL/model review. Focused examples and regressions cover directly raised name-only local exceptions, stable identities, payload-bearing exceptions, validator protocols, and exact suppressions. The shared immutable 35-file comparison against published 8.147.0 reports 71 reviewed additions, zero removals or duplicates, and six repaired false-positive controls clear across the affected owners. These aggregate observations are not per-rule precision or recall estimates. Broader field calibration remains pending.",
+      "outcome": "SARJ542: Stage at WARNING without autofix. Consider typed outcomes for expected domain failures while preserving framework validation, cancellation, unwinding, and genuine exceptional protocols. Full campaign completion is not claimed."
+    },
+    {
+      "task": "rule-audit/python/no-redundant-sql-alias",
+      "family": "python",
+      "ruleId": "no-redundant-sql-alias",
+      "state": "pending",
+      "evidence": "2026-10-28 bounded SQL/model review. Focused examples and regressions cover direct same-name SQL aliases, quoted identifiers, recoverable Psycopg SQL, namespace mutations, and exact suppressions. The shared immutable 35-file comparison against published 8.147.0 reports 71 reviewed additions, zero removals or duplicates, and six repaired false-positive controls clear across the affected owners. These aggregate observations are not per-rule precision or recall estimates. Broader field calibration remains pending.",
+      "outcome": "SARJ543: Stage at WARNING without autofix. Review only proven redundant projection or table aliases; preserve different output names, unresolved expressions, and dynamic SQL identities. Full campaign completion is not claimed."
+    },
+    {
+      "task": "rule-audit/python/no-recording-store",
+      "family": "python",
+      "ruleId": "no-recording-store",
+      "state": "pending",
+      "evidence": "2026-10-28 bounded SQL/model review. Focused examples and regressions cover source-visible get/upsert contracts, recording implementations, value construction, delegated spies, unknown effects, and exact suppressions. The shared immutable 35-file comparison against published 8.147.0 reports 71 reviewed additions, zero removals or duplicates, and six repaired false-positive controls clear across the affected owners. These aggregate observations are not per-rule precision or recall estimates. Broader field calibration remains pending.",
+      "outcome": "SARJ544: Stage at WARNING without autofix. Prefer isolated PostgreSQL fixtures for recording-only persistence doubles; preserve real delegation, SQL-backed stores, and unsupported contracts. Full campaign completion is not claimed."
+    },
+    {
+      "task": "rule-audit/python/prefer-application-model-joins",
+      "family": "python",
+      "ruleId": "prefer-application-model-joins",
+      "state": "pending",
+      "evidence": "2026-10-28 bounded SQL/model review. Focused examples and regressions cover distinct concrete relations, same-relation joins, query ownership, unresolved fragments, lock-sensitive shapes, and exact suppressions. The shared immutable 35-file comparison against published 8.147.0 reports 71 reviewed additions, zero removals or duplicates, and six repaired false-positive controls clear across the affected owners. These aggregate observations are not per-rule precision or recall estimates. Broader field calibration remains pending.",
+      "outcome": "SARJ545: Stage at WARNING without autofix. Treat distinct-relation joins as architecture review candidates; preserve atomicity, consistency, lock scope, and justified database joins. Full campaign completion is not claimed."
+    },
+    {
+      "task": "rule-audit/python/store-mutation-command-fanout",
+      "family": "python",
+      "ruleId": "store-mutation-command-fanout",
+      "state": "pending",
+      "evidence": "2026-10-28 bounded SQL/model review. Focused examples and regressions cover model write commands beside mutation-method fanout, delegation, distinct contracts, unsupported method shapes, and exact suppressions. The shared immutable 35-file comparison against published 8.147.0 reports 71 reviewed additions, zero removals or duplicates, and six repaired false-positive controls clear across the affected owners. These aggregate observations are not per-rule precision or recall estimates. Broader field calibration remains pending.",
+      "outcome": "SARJ546: Stage at WARNING without autofix. Review consolidation around the existing model write command while preserving update-only, partial-update, concurrency, and distinct command semantics. Full campaign completion is not claimed."
+    },
+    {
+      "task": "rule-audit/python/store-insert-requires-explicit-conflict-policy",
+      "family": "python",
+      "ruleId": "store-insert-requires-explicit-conflict-policy",
+      "state": "pending",
+      "evidence": "2026-10-28 bounded SQL/model review. Focused examples and regressions cover store INSERTs without SQL ON CONFLICT, supported query wrappers, insert-select shapes, explicit policies, and exact suppressions. The shared immutable 35-file comparison against published 8.147.0 reports 71 reviewed additions, zero removals or duplicates, and six repaired false-positive controls clear across the affected owners. These aggregate observations are not per-rule precision or recall estimates. Broader field calibration remains pending.",
+      "outcome": "SARJ547: Stage at WARNING without autofix. Require review of missing SQL ON CONFLICT regardless of the Python method name; choose conflict targets and duplicate behavior explicitly. Full campaign completion is not claimed."
+    },
+    {
+      "task": "rule-audit/python/no-discarded-tagged-outcome",
+      "family": "python",
+      "ruleId": "no-discarded-tagged-outcome",
+      "state": "pending",
+      "evidence": "2026-10-28 bounded SQL/model review. Focused examples and regressions cover discarded module-function outcomes, string-tagged record proofs, prepared imports, rebinding, class shadows, async calls, and consumed values. The shared immutable 35-file comparison against published 8.147.0 reports 71 reviewed additions, zero removals or duplicates, and six repaired false-positive controls clear across the affected owners. These aggregate observations are not per-rule precision or recall estimates. Broader field calibration remains pending.",
+      "outcome": "SARJ548: Stage at WARNING without autofix. Use or forward source-proven tagged outcomes; consuming a value does not prove exhaustive handling. Preserve unknown methods, generic contracts, and unresolved providers. Full campaign completion is not claimed."
+    },
+    {
+      "task": "rule-audit/sql/combine-alter-table",
+      "family": "sql",
+      "ruleId": "combine-alter-table",
+      "state": "pending",
+      "evidence": "2026-10-28 bounded SQL/model review. Focused examples and regressions cover adjacent compatible ALTER actions, exact relation identity, transaction/section boundaries, modifiers, dependencies, and exact suppressions. The shared immutable 35-file comparison against published 8.147.0 reports 71 reviewed additions, zero removals or duplicates, and six repaired false-positive controls clear across the affected owners. These aggregate observations are not per-rule precision or recall estimates. Broader field calibration remains pending.",
+      "outcome": "SARJ123: Retain the explicitly approved ERROR policy without autofix. Combine only proven compatible adjacent ALTER TABLE statements; preserve command, migration, relation, and dependency boundaries. Full campaign completion is not claimed."
+    },
+    {
+      "task": "rule-audit/sql/no-null-comparison",
+      "family": "sql",
+      "ruleId": "no-null-comparison",
+      "state": "pending",
+      "evidence": "2026-10-28 bounded SQL/model review. Focused examples and regressions cover ordinary NULL comparisons, NULL-bearing scalar NOT IN lists, valid row cases, parser boundaries, and exact suppressions. The shared immutable 35-file comparison against published 8.147.0 reports 71 reviewed additions, zero removals or duplicates, and six repaired false-positive controls clear across the affected owners. These aggregate observations are not per-rule precision or recall estimates. Broader field calibration remains pending.",
+      "outcome": "SARJ124: Stage at WARNING without autofix. Review explicit NULL intent while preserving PostgreSQL three-valued logic, row semantics, and unsupported expression boundaries. Full campaign completion is not claimed."
+    },
+    {
+      "task": "rule-audit/sql/invalid-concurrent-ddl",
+      "family": "sql",
+      "ruleId": "invalid-concurrent-ddl",
+      "state": "pending",
+      "evidence": "2026-10-28 bounded SQL/model review. Focused examples and regressions cover complete concurrent DDL forms, explicit transaction contexts, multiple-index restrictions, valid options, and exact suppressions. The shared immutable 35-file comparison against published 8.147.0 reports 71 reviewed additions, zero removals or duplicates, and six repaired false-positive controls clear across the affected owners. These aggregate observations are not per-rule precision or recall estimates. Broader field calibration remains pending.",
+      "outcome": "SARJ125: Stage at WARNING without autofix. Report source-proven invalid concurrent DDL contexts/options; preserve valid PostgreSQL forms and unknown caller or migration-runner contexts. Full campaign completion is not claimed."
+    },
+    {
+      "task": "rule-audit/sql/invalid-postgres-ddl",
+      "family": "sql",
+      "ruleId": "invalid-postgres-ddl",
+      "state": "pending",
+      "evidence": "2026-10-28 bounded SQL/model review. Focused examples and regressions cover known invalid PostgreSQL index/constraint combinations, valid neighboring forms, unsupported syntax, and exact suppressions. The shared immutable 35-file comparison against published 8.147.0 reports 71 reviewed additions, zero removals or duplicates, and six repaired false-positive controls clear across the affected owners. These aggregate observations are not per-rule precision or recall estimates. Broader field calibration remains pending.",
+      "outcome": "SARJ126: Stage at WARNING without autofix. Review only supported invalid PostgreSQL forms; preserve valid index/constraint options and avoid inventing an automatic schema rewrite. Full campaign completion is not claimed."
     }
   ]
 }