docs: improve avoid_duplicate_code rule and parameter documentation

[solid-illiaaihistov]

Summary by CodeRabbit

• Documentation
  • Expanded guidance for duplicate-code detection, including clone classification, token-based analysis, nested clone suppression, best-effort cross-file scanning, on-disk caching, and false-positive avoidance strategies.
  • Clarified duplicate-code configuration options (token thresholds, identifier/literal ignoring, and block checking) with improved explanations and examples.
  • Refreshed the avoid_duplicate_code example configuration: updated minTokens, enabled checkBlocks, and revised exclude entries.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 980a7433-8cf4-4ab1-800e-ebe22d34e386

📥 Commits

Reviewing files that changed from the base of the PR and between 901fb40 and c4e4409.

📒 Files selected for processing (1)

• lib/src/lints/avoid_duplicate_code/models/avoid_duplicate_code_parameters.dart

🚧 Files skipped from review as they are similar to previous changes (1)

• lib/src/lints/avoid_duplicate_code/models/avoid_duplicate_code_parameters.dart

---

📝 Walkthrough

Walkthrough

Expanded documentation for duplicate-code detection and its configuration parameters, including examples and updated sample settings. No rule logic, public API signatures, parsing, serialization, or equality behavior changed.

Changes

Duplicate Code Documentation

Layer / File(s)	Summary
Detection overview and configuration lib/src/lints/avoid_duplicate_code/avoid_duplicate_code_rule.dart	Documents clone classification, variable indexing, structural hashing, nested suppression, caching, false-positive handling, and updated configuration examples.
Configuration parameter reference lib/src/lints/avoid_duplicate_code/models/avoid_duplicate_code_parameters.dart	Expands documentation for token thresholds, literal and identifier handling, block checking, and exclusions without changing parameter declarations or wiring.

Estimated code review effort: 1 (Trivial) | ~5 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the doc-only updates to the avoid_duplicate_code rule and its parameter documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 7

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@lib/src/lints/avoid_duplicate_code/avoid_duplicate_code_rule.dart`:
- Around line 8-13: Qualify the documentation in the avoid_duplicate_code rule
comment to state that it reports all currently known copies, rather than
implying every cross-file copy is always reported. Update the wording near the
rule description and the related explanation around the first-file/deferred
analysis behavior, without changing detection logic.
- Around line 18-23: Update the Type 2 clones documentation in the avoid
duplicate code rule to state that literal values are normalized only when
ignore_literals is enabled, while local variables and formal parameters are
normalized only when ignore_identifiers is enabled; avoid implying these
differences are always ignored.
- Around line 57-61: Update the Persistent Disk Cache documentation to describe
the stored data accurately as candidate hash entries and metadata, including
modification stamps and HashEntry details such as hashes, offsets, lengths, and
token counts; remove the claim that AST block structures are persisted.
- Around line 75-80: Update the inline analysis-ignore example in the
documentation for avoid_duplicate_code so the myBoilerplateMethod declaration
contains syntactically valid Dart, using a real method body rather than the
invalid `{ ... }` placeholder; keep the surrounding ignore-comment guidance
unchanged.
- Around line 35-39: Update the Structural Hashing documentation comment near
the avoid-duplicate-code rule to remove the PMD CPD and SonarQube attribution,
leaving only accurate description of the Bob Jenkins one-at-a-time hash
algorithm and its use for AST subtree fingerprints.

In
`@lib/src/lints/avoid_duplicate_code/models/avoid_duplicate_code_parameters.dart`:
- Around line 104-131: The checkBlocks documentation example must align with the
default minTokens threshold and actual traversal behavior. Update the example so
the duplicated block body contains at least 30 tokens, and revise the
check_blocks false description to state that nested `{ ... }` Block bodies are
skipped while expression-bodied functions remain checked; preserve the
documented duplicate outcome.
- Around line 20-28: Update the documentation comparison table in
AvoidDuplicateCodeParameters to use accurate DCM and SonarQube defaults,
distinguishing SonarQube’s Java statement threshold from its non-Java token/line
thresholds; otherwise remove those rows if equivalent defaults cannot be
represented consistently.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 403c864a-72fc-41c6-a6b0-1168f5e4cf3f

📥 Commits

Reviewing files that changed from the base of the PR and between ebfd8f2 and e1c61ae.

📒 Files selected for processing (2)

• lib/src/lints/avoid_duplicate_code/avoid_duplicate_code_rule.dart
• lib/src/lints/avoid_duplicate_code/models/avoid_duplicate_code_parameters.dart

[illia-romanenko]

I don't like this reference, it's not as informative and feels a bit biased? We should link to research or wikipedia.

[solid-illiaaihistov]

Updated:

/// * **Coincidental Duplication:** Not all duplication is harmful. If two
///   identical code blocks serve completely distinct business purposes, merging
///   them creates a forced dependency. This can lead to
///   [hasty abstractions][aha] and [tight coupling][coupling].
///
/// :::
///
/// [aha]: https://en.wikipedia.org/wiki/Don't_repeat_yourself#AHA
/// [coupling]: https://en.wikipedia.org/wiki/Coupling_(computer_programming)

https://en.wikipedia.org/wiki/Don't_repeat_yourself#AHA