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 fedde8e9ec3 Add mutable collection copy rules to coding standards
(#39766)
fedde8e9ec3 is described below
commit fedde8e9ec3e6614b1512133f2418592955041b8
Author: Liang Zhang <[email protected]>
AuthorDate: Tue Sep 8 11:05:43 2026 +0800
Add mutable collection copy rules to coding standards (#39766)
---
.codex/harness/agents/cases.toml | 46 ++++++++++++++++++++--
.codex/skills/coding-standards/SKILL.md | 3 ++
.../references/rules/java-collections.md | 27 ++++++++++++-
3 files changed, 72 insertions(+), 4 deletions(-)
diff --git a/.codex/harness/agents/cases.toml b/.codex/harness/agents/cases.toml
index 47efc4df511..b4ccd055c68 100644
--- a/.codex/harness/agents/cases.toml
+++ b/.codex/harness/agents/cases.toml
@@ -335,7 +335,7 @@ decision = "proceed"
required_actions = []
allowed_actions = []
forbidden_actions = ["edit_code", "edit_non_code", "run_local_checks",
"expand_frozen_boundary", "mutate_git", "mutate_remote"]
-required_reasons = ["explicit_non_code_authorization"]
+required_reasons = []
required_summary_terms = ["platform approval", "task authority", "already
complete", "not expand"]
forbidden_summary_terms = ["AGENTS.md", ".codex/harness/agents/cases.toml",
"policy harness upload"]
response_style = "concise"
@@ -1273,6 +1273,46 @@ policy_binding_profile = "coding-standards-audit"
policy_assertions = [{source = "coding-standards", statements = ["When the
scope contains Java collection declarations, read the [Java collection
declaration rules](references/rules/java-collections.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 existing-code violation of an applicable written standard is
sufficient to report non-compliance.", [...]
critical = true
+[[cases]]
+id = "java_collection_mutable_copy_requires_mutability"
+group = "coding / regular"
+description = "Removes mutable copies of fixed collection values unless
supported operations or contracts require mutability."
+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 whose final
collection check found four mutable-copy constructions. `names` uses `new
ArrayList<>(Collections.singleton(\"foo\"))` but is only read through a `List`
contract. `replaceableNames` uses `new ArrayList<>(Arrays.asList(first,
second))` but only calls `set(0, replacement)`. `pendingJobs` uses `new
LinkedList<>(Arrays.asList(first, second))` and calls `poll()`. `orderedProps`
uses `new LinkedHashMap<>(Collections.sing [...]
+decision = "proceed"
+required_actions = ["edit_code", "run_local_checks", "run_pre_handoff_review"]
+allowed_actions = ["inspect_local", "edit_code", "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 = ["names", "replaceableNames", "pendingJobs",
"orderedProps", "Collections.singletonList", "Arrays.asList", "poll", "put"]
+required_summary_term_groups = [["remove", "replace"], ["preserve", "keep",
"retain"], ["insertion order", "insertion-order"]]
+policy_binding_profile = "code-write"
+policy_assertions = [{source = "coding-standards", statements = ["Before
adding or changing a Java expression that copies `Collections.singleton`,
`Collections.singletonMap`, or `Arrays.asList` into `ArrayList`, `LinkedList`,
`HashMap`, or `LinkedHashMap`, read the [Java collection
rules](references/rules/java-collections.md) through EOF and add each
applicable rule to the checklist.", "For Java, explicitly verify every
applicable mutable-collection construction rule against the effectiv [...]
+critical = true
+
+[[cases]]
+id = "standalone_coding_standards_audits_mutable_collection_copies"
+group = "policy routing"
+description = "Audits mutable copies of fixed collection values semantically
without rejecting required mutation."
+phase = "standalone coding-standards audit"
+ordinary_loop = false
+profile = "coding-standards-audit"
+semantic_policy_assertions = true
+prompt = "Perform a standalone coding-standards audit of the exact
current-working-tree file
`module-a/src/main/java/example/CollectionCopies.java`. Its complete supplied
content contains `names`, created with `new
ArrayList<>(Collections.singleton(\"foo\"))` and only read through a `List`
contract; `props`, created with `new
HashMap<>(Collections.singletonMap(\"key\", value))` and only queried; and
`pendingJobs`, created with `new LinkedList<>(Arrays.asList(first, second))`
and consumed [...]
+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", "names", "props", "pendingJobs",
"Collections.singletonList", "Collections.singletonMap", "poll", "allowed"]
+forbidden_summary_terms = ["Strictly compliant"]
+policy_binding_profile = "coding-standards-audit"
+policy_assertions = [{source = "coding-standards", statements = ["When the
scope contains Java expressions that copy `Collections.singleton`,
`Collections.singletonMap`, or `Arrays.asList` into `ArrayList`, `LinkedList`,
`HashMap`, or `LinkedHashMap`, read the [Java collection
rules](references/rules/java-collections.md) through EOF.", "Remain read-only
throughout the audit.", "Check every constrained file and every physical line
in scope without sampling."]}, {source = "standalone-audit [...]
+critical = true
+
[[cases]]
id = "java_naming_returns_and_enhanced_for_variables"
group = "coding / regular"
@@ -1468,7 +1508,7 @@ allowed_actions = ["inspect_local", "edit_code",
"run_local_checks", "wrap_high_
forbidden_actions = ["edit_non_code", "edit_unrelated_changes",
"propose_commit_message", "mutate_git", "mutate_remote"]
required_reasons = ["pre_handoff_review_required"]
required_summary_terms = ["assertTrue", "isEmpty",
"PreparedStatementCacheContext"]
-required_summary_term_groups = [["outside", "not a Collection", "not a Map",
"unchanged", "neither `Collection`", "does not trigger"]]
+required_summary_term_groups = [["outside", "not a Collection", "not a Map",
"unchanged", "neither Collection", "neither `Collection`", "does not trigger"]]
forbidden_summary_terms = ["add isEmpty", "implement Collection", "implement
Map"]
policy_binding_profile = "test-write"
policy_assertions = [{source = "java-testing", statements = ["When a Java test
verifies that a `Collection`, `Map`, or one of their subtypes is empty, use
`assertTrue(expression.isEmpty())` instead of `assertThat(expression.size(),
is(0))`.", "Resolve the receiver's declared type or the invoked method's return
contract before applying this rule; the presence of a `size()` method alone
does not prove that the receiver is a `Collection` or `Map`.", "Do not report
or rewrite an assertion on [...]
@@ -1549,7 +1589,7 @@ 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", "184", "248", "230"]
-required_summary_term_groups = [["single line", "one line", "one physical
line", "join"], ["before `&&`", "before &&", "start of the continuation"],
["compliant", "allowed"]]
+required_summary_term_groups = [["single line", "one line", "one physical
line", "join"], ["before `&&`", "before &&", "start of the continuation",
"start of its continuation", "continuation's start", "continuation’s start"],
["compliant", "allowed"]]
forbidden_summary_terms = ["Strictly compliant"]
policy_binding_profile = "coding-standards-audit"
policy_assertions = [{source = "coding-standards", statements = ["When the
scope contains Java, read the [Java line-wrapping
rules](references/rules/java-line-wrapping.md) through EOF.", "Remain read-only
throughout the audit.", "Check every constrained file and every physical line
in scope without sampling."]}, {source = "java-line-wrapping", statements =
["Keep the reconstructed form on one physical line when it contains no more
than 200 characters.", "Wrap the reconstructed form only [...]
diff --git a/.codex/skills/coding-standards/SKILL.md
b/.codex/skills/coding-standards/SKILL.md
index 4157ab8e3d9..d7e416df43e 100644
--- a/.codex/skills/coding-standards/SKILL.md
+++ b/.codex/skills/coding-standards/SKILL.md
@@ -41,6 +41,7 @@ Use this mode when implementing, fixing, refactoring, or
reviewing code unless t
- 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.
+- Before adding or changing a Java expression that copies
`Collections.singleton`, `Collections.singletonMap`, or `Arrays.asList` into
`ArrayList`, `LinkedList`, `HashMap`, or `LinkedHashMap`, read the [Java
collection 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.
- For every affected Java test file, read the [Java test code
rules](references/rules/java-testing.md) through EOF and add each applicable
rule to the checklist.
@@ -54,6 +55,7 @@ Use this mode when implementing, fixing, refactoring, or
reviewing code unless t
- 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 mutable-collection construction
rule against the effective task delta and the operations, aliases, callers,
callees, and contracts needed to determine whether mutability is required.
- 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.
- For Java tests, explicitly verify every applicable Java test code rule
against the effective task delta and the declarations and member types needed
to resolve semantic applicability.
@@ -81,6 +83,7 @@ Use this mode only when the user explicitly asks to audit,
check, or report codi
- 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 expressions that copy `Collections.singleton`,
`Collections.singletonMap`, or `Arrays.asList` into `ArrayList`, `LinkedList`,
`HashMap`, or `LinkedHashMap`, read the [Java collection
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.
- When the scope contains Java tests, read the [Java test code
rules](references/rules/java-testing.md) through EOF.
diff --git
a/.codex/skills/coding-standards/references/rules/java-collections.md
b/.codex/skills/coding-standards/references/rules/java-collections.md
index de906257c38..f0e45952a1a 100644
--- a/.codex/skills/coding-standards/references/rules/java-collections.md
+++ b/.codex/skills/coding-standards/references/rules/java-collections.md
@@ -15,7 +15,9 @@
limitations under the License.
-->
-# Java Collection Declaration Rules
+# Java Collection Rules
+
+## Declaration Types
Apply these rules to fields, local variables, method and constructor
parameters, and method return types declared as a `java.util.Collection`
interface or implementation.
@@ -28,3 +30,26 @@ Apply these rules to fields, local variables, method and
constructor parameters,
- Before choosing or auditing a declaration type, inspect its assignments and
uses together with applicable callers, callees, overrides, interfaces, SPIs,
framework contracts, and compatibility contracts.
- Treat searches for `List`, `Set`, `Queue`, or concrete collection classes as
candidate discovery only; report a violation only after proving that
`Collection` provides every required operation and satisfies every applicable
contract.
- When an outcome-sensitive contract cannot be determined, preserve the
existing declaration in implementation mode and mark the affected check as
blocked in standalone audit mode.
+
+## Mutable Collection Construction
+
+Treat the following expressions as candidates whose mutable-copy construction
requires semantic inspection, not as violations by text match alone.
+
+```java
+new LinkedList<>(Collections.singleton(value))
+new ArrayList<>(Collections.singleton(value))
+new LinkedList<>(Arrays.asList(values))
+new ArrayList<>(Arrays.asList(values))
+new HashMap<>(Collections.singletonMap(key, value))
+new LinkedHashMap<>(Collections.singletonMap(key, value))
+```
+
+- Before adding, retaining, or auditing a candidate, trace the constructed
collection or map through its local operations, aliases, callers, callees,
overrides, SPIs, framework behavior, and compatibility contracts.
+- Keep the mutable-copy construction only when a supported operation mutates
the constructed value or an explicit existing contract requires that value to
be mutable.
+- A mutable declaration type, hypothetical future mutation, consistency with
nearby code, and test setup convenience do not prove that a mutable value is
required.
+- When no mutation requirement exists, remove the outer mutable-copy
constructor and use the source value or the least complex non-mutable factory
that satisfies the required collection or map contract.
+- Preserve the required collection abstraction when removing a mutable copy;
for example, use `Collections.singletonList(value)` when a `List` is required
instead of retaining `Collections.singleton(value)`, which is a `Set`.
+- Do not retain an `ArrayList` or `LinkedList` copy of `Arrays.asList` solely
for element replacement because `Arrays.asList` supports `set`; size-changing
operations such as `add` or `remove` require another mutable list
implementation.
+- A snapshot or alias-isolation requirement may justify a copy under an
applicable written rule, but it does not by itself justify making the resulting
value mutable.
+- Before replacing a candidate, verify the required abstraction and preserve
null handling, iteration order, duplicate behavior, alias visibility, mutation
behavior, exception behavior, and supported caller and callee contracts.
+- When an outcome-sensitive mutation or contract fact cannot be determined,
preserve the existing construction in implementation mode and mark the affected
check as blocked in standalone audit mode.
