You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@shardingsphere.apache.org by zh...@apache.org on 2026/09/06 10:56:07 UTC

(shardingsphere) branch master updated: Add Java precondition coding standards (#39755)

This is an automated email from the ASF dual-hosted git repository.

terrymanu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/shardingsphere.git


The following commit(s) were added to refs/heads/master by this push:
     new b0844ec5ec3 Add Java precondition coding standards (#39755)
b0844ec5ec3 is described below

commit b0844ec5ec3d9d6322f88137e877507bacb8dfb3
Author: Liang Zhang <zh...@apache.org>
AuthorDate: Sun Sep 6 18:56:00 2026 +0800

    Add Java precondition coding standards (#39755)
---
 .codex/harness/agents/cases.toml                   | 41 ++++++++++++++++-
 .codex/harness/agents/policy-sources.toml          | 23 ++++++----
 .codex/skills/coding-standards/SKILL.md            |  3 ++
 .../references/rules/defensive-code.md             |  3 +-
 .../references/rules/java-preconditions.md         | 52 ++++++++++++++++++++++
 5 files changed, 111 insertions(+), 11 deletions(-)

diff --git a/.codex/harness/agents/cases.toml b/.codex/harness/agents/cases.toml
index 95c427c5854..47efc4df511 100644
--- a/.codex/harness/agents/cases.toml
+++ b/.codex/harness/agents/cases.toml
@@ -877,7 +877,7 @@ allowed_actions = ["inspect_local", "edit_code", "keep_manual_throw", "run_local
 forbidden_actions = ["mutate_git", "mutate_remote"]
 required_reasons = ["exception_contract", "local_code_authorized", "pre_handoff_review_required"]
 policy_binding_profile = "code-write"
-policy_assertions = [{source = "defensive-code", statements = ["Keep a manual throw when the module cannot depend on `infra/exception`, the code is inside `ShardingSpherePreconditions`, a caller-facing exception contract requires it, or a precondition wrapper would obscure necessary control flow.", "Do not replace manual throws mechanically, and record the concrete reason for keeping one."]}]
+policy_assertions = [{source = "java-preconditions", statements = ["Keep a manual throw when the module cannot depend on `infra/exception`, the code is inside `ShardingSpherePreconditions`, a caller-facing exception contract requires it, or a precondition wrapper would obscure necessary control flow.", "Do not replace manual throws mechanically, and record the concrete reason for keeping one."]}]
 critical = true
 
 [[cases]]
@@ -2245,3 +2245,42 @@ forbidden_summary_terms = ["git commit"]
 policy_binding_profile = "review-pr"
 policy_assertions = [{source = "agents", statements = ["Complete reviews or recommendations use Formal Review with `### Result`, one `Review Result`, `### Evidence`, and `### Coverage`; Coverage identifies local-only changes."]}, {source = "review-pr", statements = ["For a standalone local candidate, use the active task's original working-tree baseline plus only its attributed local commits, index changes, and working-tree changes as the effective candidate.", "Use the frozen task bounda [...]
 critical = true
+
+[[cases]]
+id = "java_preconditions_use_specialized_methods"
+group = "coding / regular"
+description = "Uses ShardingSpherePreconditions and its specialized methods without replacing exception flows that are not preconditions."
+phase = "coding-standards final check and ordinary completion loop"
+ordinary_loop = true
+profile = "code-write"
+semantic_policy_assertions = true
+prompt = "Continue an authorized in-scope Java implementation. In modules that already use `infra/exception`, `Ready` has a guard-only throw for `!ready`, `Config` uses `checkState(null != config, supplier)`, `Name` uses `checkState(!Strings.isNullOrEmpty(name), supplier)`, and `Items` uses `checkState(!items.isEmpty(), supplier)`. `Translator` wraps a caught `SQLException` and preserves its cause, while `Fixture` throws `SQLException` from a test double. Report `Ready` as `checkState`,  [...]
+decision = "proceed"
+required_actions = ["edit_code", "keep_manual_throw", "run_local_checks", "run_pre_handoff_review"]
+allowed_actions = ["inspect_local", "edit_code", "keep_manual_throw", "run_local_checks", "wrap_high_output", "run_pre_handoff_review", "fix_review_findings"]
+forbidden_actions = ["edit_non_code", "edit_unrelated_changes", "propose_commit_message", "mutate_git", "mutate_remote"]
+required_reasons = ["pre_handoff_review_required"]
+required_summary_terms = ["Ready", "Config", "Name", "Items", "Translator", "Fixture", "checkState", "checkNotNull", "checkNotEmpty", "preserve"]
+policy_binding_profile = "code-write"
+policy_assertions = [{source = "coding-standards", statements = ["Before adding or changing a Java `throw` statement, a conditional branch that throws, a validation or precondition call, or a call to `ShardingSpherePreconditions`, read the [Java precondition rules](references/rules/java-preconditions.md) through EOF and add each applicable rule to the checklist."]}, {source = "java-preconditions", statements = ["When a conditional branch does nothing except construct and throw an excepti [...]
+critical = true
+
+[[cases]]
+id = "standalone_coding_standards_audits_java_preconditions"
+group = "policy routing"
+description = "Audits generic preconditions and conditional throws while preserving justified direct exception flows."
+phase = "standalone coding-standards audit"
+ordinary_loop = false
+profile = "coding-standards-audit"
+semantic_policy_assertions = true
+prompt = "Audit the complete current-working-tree file `module-a/src/main/java/example/Preconditions.java` without editing it. The module already uses `infra/exception`. The file has a guard-only throw for `!ready`; generic `checkState` calls for `values.isEmpty()`, `values.contains(element)`, `!values.contains(element)`, and `map.containsKey(key)`; an unconditional unsupported-operation throw; and a catch block that wraps the caught cause. Report `Non-compliant`, give `checkState`, `che [...]
+decision = "proceed"
+required_actions = ["inspect_local"]
+allowed_actions = ["inspect_local"]
+forbidden_actions = ["edit_code", "edit_non_code", "run_local_checks", "run_pre_handoff_review", "propose_commit_message", "mutate_git", "mutate_remote"]
+required_reasons = ["read_only_request"]
+required_summary_terms = ["Non-compliant", "checkState", "checkMustEmpty", "checkContains", "checkNotContains", "checkContainsKey", "unconditional", "wrap", "allowed"]
+forbidden_summary_terms = ["Strictly compliant"]
+policy_binding_profile = "coding-standards-audit"
+policy_assertions = [{source = "coding-standards", statements = ["When the scope contains Java `throw` statements, conditional exception paths, validation or precondition calls, or calls to `ShardingSpherePreconditions`, read the [Java precondition rules](references/rules/java-preconditions.md) through EOF.", "Remain read-only throughout the audit.", "Check every constrained file and every physical line in scope without sampling."]}, {source = "standalone-audit", statements = ["An existi [...]
+critical = true
diff --git a/.codex/harness/agents/policy-sources.toml b/.codex/harness/agents/policy-sources.toml
index ebe3790fef6..e66c13ecd74 100644
--- a/.codex/harness/agents/policy-sources.toml
+++ b/.codex/harness/agents/policy-sources.toml
@@ -18,16 +18,16 @@ root_max_bytes = 26000
 
 [profiles]
 root = ["agents"]
-code-write = ["agents", "code-of-conduct", "code-implementation", "coding-standards", "java-naming", "java-types", "java-constructors", "java-collections", "java-expressions", "java-line-wrapping", "java-testing", "defensive-code", "implementation-rules", "testing-rules", "contracts-and-removal", "non-regression", "code-verification", "change-completion"]
-test-write = ["agents", "code-of-conduct", "code-implementation", "coding-standards", "java-naming", "java-types", "java-constructors", "java-collections", "java-expressions", "java-line-wrapping", "java-testing", "defensive-code", "implementation-rules", "testing-rules", "contracts-and-removal", "non-regression", "code-verification", "change-completion"]
-code-review = ["agents", "code-of-conduct", "coding-standards", "java-naming", "java-types", "java-constructors", "java-collections", "java-expressions", "java-line-wrapping", "java-testing", "defensive-code", "implementation-rules", "testing-rules", "contracts-and-removal", "non-regression", "code-verification"]
+code-write = ["agents", "code-of-conduct", "code-implementation", "coding-standards", "java-naming", "java-types", "java-constructors", "java-preconditions", "java-collections", "java-expressions", "java-line-wrapping", "java-testing", "defensive-code", "implementation-rules", "testing-rules", "contracts-and-removal", "non-regression", "code-verification", "change-completion"]
+test-write = ["agents", "code-of-conduct", "code-implementation", "coding-standards", "java-naming", "java-types", "java-constructors", "java-preconditions", "java-collections", "java-expressions", "java-line-wrapping", "java-testing", "defensive-code", "implementation-rules", "testing-rules", "contracts-and-removal", "non-regression", "code-verification", "change-completion"]
+code-review = ["agents", "code-of-conduct", "coding-standards", "java-naming", "java-types", "java-constructors", "java-preconditions", "java-collections", "java-expressions", "java-line-wrapping", "java-testing", "defensive-code", "implementation-rules", "testing-rules", "contracts-and-removal", "non-regression", "code-verification"]
 code-design = ["agents", "implementation-rules", "java-collections", "testing-rules", "contracts-and-removal", "cross-cutting-skills"]
-coding-standards-audit = ["agents", "code-of-conduct", "coding-standards", "standalone-audit", "java-naming", "java-types", "java-constructors", "java-collections", "java-expressions", "java-line-wrapping", "java-testing", "defensive-code"]
+coding-standards-audit = ["agents", "code-of-conduct", "coding-standards", "standalone-audit", "java-naming", "java-types", "java-constructors", "java-preconditions", "java-collections", "java-expressions", "java-line-wrapping", "java-testing", "defensive-code"]
 runtime-diagnosis = ["agents", "runtime-triage", "code-verification"]
 command-execution = ["agents", "token-efficiency", "code-verification"]
 cross-cutting = ["agents", "cross-cutting-skills"]
-gen-ut = ["agents", "code-of-conduct", "code-implementation", "coding-standards", "java-naming", "java-types", "java-constructors", "java-collections", "java-expressions", "java-line-wrapping", "java-testing", "defensive-code", "implementation-rules", "testing-rules", "contracts-and-removal", "non-regression", "code-verification", "gen-ut", "gen-ut-verification", "change-completion"]
-review-pr = ["agents", "code-of-conduct", "coding-standards", "java-naming", "java-types", "java-constructors", "java-collections", "java-expressions", "java-line-wrapping", "java-testing", "defensive-code", "implementation-rules", "testing-rules", "contracts-and-removal", "non-regression", "code-verification", "review-pr", "review-pr-evidence", "review-pr-high-risk", "review-pr-sql-parser", "review-pr-corrections"]
+gen-ut = ["agents", "code-of-conduct", "code-implementation", "coding-standards", "java-naming", "java-types", "java-constructors", "java-preconditions", "java-collections", "java-expressions", "java-line-wrapping", "java-testing", "defensive-code", "implementation-rules", "testing-rules", "contracts-and-removal", "non-regression", "code-verification", "gen-ut", "gen-ut-verification", "change-completion"]
+review-pr = ["agents", "code-of-conduct", "coding-standards", "java-naming", "java-types", "java-constructors", "java-preconditions", "java-collections", "java-expressions", "java-line-wrapping", "java-testing", "defensive-code", "implementation-rules", "testing-rules", "contracts-and-removal", "non-regression", "code-verification", "review-pr", "review-pr-evidence", "review-pr-high-risk", "review-pr-sql-parser", "review-pr-corrections"]
 policy-maintenance = ["agents", "policy-maintenance", "policy-source-manifest"]
 
 [[sources]]
@@ -126,7 +126,7 @@ id = "coding-standards"
 path = ".codex/skills/coding-standards/SKILL.md"
 kind = "skill"
 semantic = true
-references = ["AGENTS.md", "CODE_OF_CONDUCT.md", ".codex/skills/coding-standards/references/standalone-audit.md", ".codex/skills/coding-standards/references/rules/java-naming.md", ".codex/skills/coding-standards/references/rules/java-types.md", ".codex/skills/coding-standards/references/rules/java-constructors.md", ".codex/skills/coding-standards/references/rules/java-collections.md", ".codex/skills/coding-standards/references/rules/java-expressions.md", ".codex/skills/coding-standards/r [...]
+references = ["AGENTS.md", "CODE_OF_CONDUCT.md", ".codex/skills/coding-standards/references/standalone-audit.md", ".codex/skills/coding-standards/references/rules/java-naming.md", ".codex/skills/coding-standards/references/rules/java-types.md", ".codex/skills/coding-standards/references/rules/java-constructors.md", ".codex/skills/coding-standards/references/rules/java-preconditions.md", ".codex/skills/coding-standards/references/rules/java-collections.md", ".codex/skills/coding-standards [...]
 
 [[sources]]
 id = "coding-standards-metadata"
@@ -163,6 +163,13 @@ kind = "rules"
 semantic = true
 references = []
 
+[[sources]]
+id = "java-preconditions"
+path = ".codex/skills/coding-standards/references/rules/java-preconditions.md"
+kind = "rules"
+semantic = true
+references = []
+
 [[sources]]
 id = "java-collections"
 path = ".codex/skills/coding-standards/references/rules/java-collections.md"
@@ -196,7 +203,7 @@ id = "defensive-code"
 path = ".codex/skills/coding-standards/references/rules/defensive-code.md"
 kind = "rules"
 semantic = true
-references = []
+references = [".codex/skills/coding-standards/references/rules/java-preconditions.md"]
 
 [[sources]]
 id = "implementation-rules"
diff --git a/.codex/skills/coding-standards/SKILL.md b/.codex/skills/coding-standards/SKILL.md
index 7d887e3b9f9..4157ab8e3d9 100644
--- a/.codex/skills/coding-standards/SKILL.md
+++ b/.codex/skills/coding-standards/SKILL.md
@@ -39,6 +39,7 @@ Use this mode when implementing, fixing, refactoring, or reviewing code unless t
 - For every affected Java file, read the [Java naming rules](references/rules/java-naming.md) through EOF and add each applicable rule to the checklist.
 - Before adding or changing a Java type declaration or its type-level annotations, read the [Java type rules](references/rules/java-types.md) through EOF and add each applicable rule to the checklist.
 - Before adding, changing, or removing an explicit or generated constructor, or changing an instance field that may alter a generated constructor's signature or behavior, read the [Java constructor rules](references/rules/java-constructors.md) through EOF and add each applicable rule to the checklist.
+- Before adding or changing a Java `throw` statement, a conditional branch that throws, a validation or precondition call, or a call to `ShardingSpherePreconditions`, read the [Java precondition rules](references/rules/java-preconditions.md) through EOF and add each applicable rule to the checklist.
 - Before adding or changing a Java declaration whose type is a `java.util.Collection` interface or implementation, read the [Java collection declaration rules](references/rules/java-collections.md) through EOF and add each applicable rule to the checklist.
 - For every affected Java file, read the [Java expression rules](references/rules/java-expressions.md) through EOF and add each applicable rule to the checklist.
 - For every affected Java file, read the [Java line-wrapping rules](references/rules/java-line-wrapping.md) through EOF and add each applicable rule to the checklist.
@@ -51,6 +52,7 @@ Use this mode when implementing, fixing, refactoring, or reviewing code unless t
 - For Java, explicitly verify every applicable Java naming rule against the effective task delta and the surrounding declarations needed to resolve semantic applicability.
 - For Java, explicitly verify every applicable Java type rule against each type declaration and type-level annotation added or modified by the task.
 - For Java, explicitly verify every applicable Java constructor rule against each explicit or generated constructor added, modified, removed, or affected by an instance-field change in the task.
+- For Java, explicitly verify every applicable Java precondition rule against each added or modified exception-throwing condition and precondition call, including whether a specialized `ShardingSpherePreconditions` method can express the condition without changing exception or control-flow semantics.
 - For Java, explicitly verify every applicable Java collection declaration rule against the effective task delta and the operations, callers, callees, overrides, and contracts needed to determine the least-specific required declaration type.
 - For Java, explicitly verify every applicable Java expression rule against the effective task delta and the declarations needed to resolve named constants.
 - For Java, explicitly verify every applicable Java line-wrapping rule against each declaration header, statement, and expression added or modified by the task.
@@ -77,6 +79,7 @@ Use this mode only when the user explicitly asks to audit, check, or report codi
 - When the scope contains Java, read the [Java naming rules](references/rules/java-naming.md) through EOF.
 - When the scope contains Java, read the [Java type rules](references/rules/java-types.md) through EOF.
 - When the scope contains Java, read the [Java constructor rules](references/rules/java-constructors.md) through EOF.
+- When the scope contains Java `throw` statements, conditional exception paths, validation or precondition calls, or calls to `ShardingSpherePreconditions`, read the [Java precondition rules](references/rules/java-preconditions.md) through EOF.
 - When the scope contains Java collection declarations, read the [Java collection declaration rules](references/rules/java-collections.md) through EOF.
 - When the scope contains Java, read the [Java expression rules](references/rules/java-expressions.md) through EOF.
 - When the scope contains Java, read the [Java line-wrapping rules](references/rules/java-line-wrapping.md) through EOF.
diff --git a/.codex/skills/coding-standards/references/rules/defensive-code.md b/.codex/skills/coding-standards/references/rules/defensive-code.md
index 10195b5ca36..de814df1031 100644
--- a/.codex/skills/coding-standards/references/rules/defensive-code.md
+++ b/.codex/skills/coding-standards/references/rules/defensive-code.md
@@ -38,8 +38,7 @@ Defensive code is a guard, repeated validation, copy, wrapper, fallback, default
 - Do not add or retain a null guard, `Objects.requireNonNull`, `Optional.ofNullable`, null fallback, or null-triggered early return when supported callers and upstream contracts already guarantee a non-null value and no explicit existing boundary or diagnostic contract requires local validation.
 - Do not repeat empty collection, empty string, range, type, capability, or state checks whose invariants are guaranteed by supported callers, parsers, constructors, frameworks, or state machines unless an explicit existing boundary or diagnostic contract requires local validation.
 - Add runtime validation only when the defensive-code evidence gate proves that it is required at a real external, public, persisted, parsed, SPI, reflection, shared-state, or asynchronous boundary to preserve an existing contract or provide a concrete diagnostic for a condition that can occur there. Do not recheck invariants guaranteed by callers or upstream contracts.
-- Prefer `ShardingSpherePreconditions` with lazy exception suppliers when the module can use it and the resulting control flow preserves the required exception type, message, timing, and cause.
-- Keep a manual throw when the module cannot depend on `infra/exception`, the code is inside `ShardingSpherePreconditions`, a caller-facing exception contract requires it, or a precondition wrapper would obscure necessary control flow. Do not replace manual throws mechanically, and record the concrete reason for keeping one.
+- After the evidence gate establishes that validation is required, follow `.codex/skills/coding-standards/references/rules/java-preconditions.md` for exception-throwing conditions and precondition method selection.
 
 ## Collection Copies and Mutation Restrictions
 
diff --git a/.codex/skills/coding-standards/references/rules/java-preconditions.md b/.codex/skills/coding-standards/references/rules/java-preconditions.md
new file mode 100644
index 00000000000..1b09cff7c04
--- /dev/null
+++ b/.codex/skills/coding-standards/references/rules/java-preconditions.md
@@ -0,0 +1,52 @@
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You under the Apache License, Version 2.0
+  (the "License"); you may not use this file except in compliance with
+  the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+
+# Java Precondition Rules
+
+Apply these rules to Java `throw` statements, conditional exception paths, validation or precondition calls, and calls to `ShardingSpherePreconditions`.
+
+## Preconditions and Direct Throws
+
+- When a conditional branch does nothing except construct and throw an exception because a required condition is false, replace the branch with the equivalent `ShardingSpherePreconditions` call if the module can use `infra/exception` and the replacement preserves behavior.
+- Prefer `ShardingSpherePreconditions` with lazy exception suppliers when the module can use it and the resulting control flow preserves the required exception type, message, timing, and cause.
+- Supply the exception lazily with a constructor reference or a lambda such as `ExceptionType::new` or `() -> new ExceptionType(arguments)`.
+- Use `checkState` for a required boolean condition only when no specialized `ShardingSpherePreconditions` method expresses the complete condition.
+
+## Specialized Methods
+
+- Replace `checkState(null != value, supplier)` with `checkNotNull(value, supplier)`.
+- Replace `checkState(!Strings.isNullOrEmpty(value), supplier)` with `checkNotEmpty(value, supplier)`; this rejects null and empty strings but does not reject a non-empty whitespace-only string.
+- Replace `checkState(!values.isEmpty(), supplier)` and `checkState(!map.isEmpty(), supplier)` with the applicable `checkNotEmpty` overload.
+- Replace `checkState(values.isEmpty(), supplier)` and `checkState(map.isEmpty(), supplier)` with the applicable `checkMustEmpty` overload.
+- Replace `checkState(values.contains(element), supplier)` with `checkContains(values, element, supplier)`.
+- Replace `checkState(!values.contains(element), supplier)` with `checkNotContains(values, element, supplier)`.
+- Replace `checkState(map.containsKey(key), supplier)` with `checkContainsKey(map, key, supplier)`.
+- Apply a specialized-method replacement only when the matched predicate is the complete expected expression; inspect a compound expression instead of mechanically splitting or rewriting it.
+
+## Semantic Preservation and Exceptions
+
+- Preserve the exception type, message, cause, construction timing, condition evaluation order, short-circuit behavior, and surrounding control flow.
+- Keep a manual throw when the module cannot depend on `infra/exception`, the code is inside `ShardingSpherePreconditions`, a caller-facing exception contract requires it, or a precondition wrapper would obscure necessary control flow.
+- Keep a direct throw for an unconditional failure, exception translation, exception wrapping, rethrowing, or a test double or fixture that deliberately simulates a failure.
+- Do not add or widen a module dependency solely to replace a manual throw with `ShardingSpherePreconditions`.
+- Do not replace manual throws mechanically, and record the concrete reason for keeping one.
+
+## Semantic Verification
+
+- Before changing or reporting a candidate, inspect the module dependencies, complete condition, branch contents, surrounding control flow, exception contract, supplier evaluation, receiver types, overload resolution, and test purpose.
+- Treat searches for `throw new`, `ShardingSpherePreconditions.checkState`, `null !=`, `Strings.isNullOrEmpty`, `isEmpty`, `contains`, and `containsKey` as candidate discovery only.
+- When outcome-sensitive behavior or a required contract cannot be determined, preserve the existing code in implementation mode and mark the affected check as blocked in standalone audit mode.