From a0af2d28962d9b46a1219f34ee9dc1d076ec0383 Mon Sep 17 00:00:00 2001 From: Illia Aihistov Date: Thu, 10 Sep 2026 09:35:03 +0300 Subject: [PATCH 1/4] docs: add ciach to Other Notable Packages --- .../3_other_notable_packages/_category_.json | 8 +++ .../code_complexity.md | 41 +++++++++++++ .../code_duplication.md | 40 ++++++++++++ .../3_other_notable_packages/dead_code.md | 61 +++++++++++++++++++ 4 files changed, 150 insertions(+) create mode 100644 doc/docusaurus/docs/3_other_notable_packages/_category_.json create mode 100644 doc/docusaurus/docs/3_other_notable_packages/code_complexity.md create mode 100644 doc/docusaurus/docs/3_other_notable_packages/code_duplication.md create mode 100644 doc/docusaurus/docs/3_other_notable_packages/dead_code.md diff --git a/doc/docusaurus/docs/3_other_notable_packages/_category_.json b/doc/docusaurus/docs/3_other_notable_packages/_category_.json new file mode 100644 index 00000000..056dfa1a --- /dev/null +++ b/doc/docusaurus/docs/3_other_notable_packages/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Other notable packages", + "position": 3, + "link": { + "type": "generated-index", + "description": "Tools complementing solid_lints." + } +} diff --git a/doc/docusaurus/docs/3_other_notable_packages/code_complexity.md b/doc/docusaurus/docs/3_other_notable_packages/code_complexity.md new file mode 100644 index 00000000..561c5720 --- /dev/null +++ b/doc/docusaurus/docs/3_other_notable_packages/code_complexity.md @@ -0,0 +1,41 @@ +--- +sidebar_label: Code complexity +sidebar_position: 3 +description: Measure and manage code complexity. +--- + +# Code Complexity + +Tools and metrics for analyzing algorithmic complexity and cognitive burden +in Dart and Flutter codebases. + +## [cognitive_complexity](https://pub.dev/packages/cognitive_complexity) + +[![pub package](https://img.shields.io/pub/v/cognitive_complexity.svg)](https://pub.dev/packages/cognitive_complexity) + +Algorithmic Cognitive Complexity calculation and Data-Flow analysis library and +CLI tools for Dart and Flutter. + +It implements the Cognitive Complexity principles articulated by SonarSource, +providing an objective way to find and fix overly complex logic and routines. + +- **Links**: [pub.dev](https://pub.dev/packages/cognitive_complexity) ยท + [GitHub](https://github.com/kevmoo/analytica.dart/tree/main/packages/cognitive_complexity) + +--- + +## Comparison: [`cyclomatic_complexity`](../2_custom_lints/cyclomatic_complexity.md) vs `cognitive_complexity` + +Both tools aim to alert you when code becomes too complex to maintain, but they +evaluate complexity from different angles: + +| | `cyclomatic_complexity` | `cognitive_complexity` | +| :--- | :--- | :--- | +| **Complexity angle** | **Structural:** Counts branches and execution paths | **Perceptual:** Evaluates mental effort and readability | +| **Nesting impact** | Treats all branches equally (+1 per branch) | Penalizes deeper nesting progressively | +| **When it flags** | Functions with too many execution paths | Functions that are hard for humans to follow | +| **Tool type** | Real-time IDE lint rule (`solid_lints`) | Standalone CLI tool & analysis library | + +> **๐Ÿ’ก Best Together:** Use `cyclomatic_complexity` in `solid_lints` to +> prevent sprawling branch counts, and `cognitive_complexity` to audit deeply +> nested routines that are hard to comprehend and maintain. diff --git a/doc/docusaurus/docs/3_other_notable_packages/code_duplication.md b/doc/docusaurus/docs/3_other_notable_packages/code_duplication.md new file mode 100644 index 00000000..60fa8572 --- /dev/null +++ b/doc/docusaurus/docs/3_other_notable_packages/code_duplication.md @@ -0,0 +1,40 @@ +--- +sidebar_label: Code duplication +sidebar_position: 2 +description: Detect duplicate code clones. +--- + +# Code Duplication + +Tools and engines for detecting copy-pasted fragments and structural clones +across Dart and Flutter codebases. + +## [dedupe](https://pub.dev/packages/dedupe) + +[![pub package](https://img.shields.io/pub/v/dedupe.svg)](https://pub.dev/packages/dedupe) + +High-performance code duplication and clone detection engine and CLI tool for +Dart and Flutter. + +It scans codebases to detect token-level, structural, and near-miss code clones +across files and packages with fast incremental analysis. + +- **Links**: [pub.dev](https://pub.dev/packages/dedupe) ยท + [GitHub](https://github.com/kevmoo/analytica.dart/tree/main/packages/dedupe) + +## Comparison: [`avoid_duplicate_code`](../2_custom_lints/avoid_duplicate_code.md) vs `dedupe` + +| | `avoid_duplicate_code` | `dedupe` | +| :--- | :--- | :--- | +| **Tool type** | Dart Analyzer / Linter plugin rule | Standalone CLI tool & Dart library/API | +| **Primary workflow** | Real-time in-IDE feedback and `dart analyze` | Repository auditing, CI/CD checks, PR gating, batch analysis | +| **Detection approach** | **Block-level (AST):** Analyzes complete syntactic structures (functions, methods, closures, `if`/`for` bodies) | **Sequence-level (Tokens):** Analyzes continuous sequences of code anywhere across files | +| **Whole functions & blocks**
*(e.g., duplicated methods with renamed variables)* | โœ… **Detected** | โœ… **Detected** | +| **Sub-method fragments**
*(e.g., 5โ€“10 copied lines inside a 50-line method)* | โŒ **Skipped** (only evaluates complete blocks/methods) | โœ… **Detected** (flags duplicate snippets regardless of block boundaries) | +| **Near-miss / modified clones**
*(e.g., copy-paste with an extra line or minor edit)* | โŒ **Skipped** (requires matching syntactic block structure) | โœ… **Detected** (fuzzy matching detects clones with insertions/deletions) | +| **Differing literals diffing** | โœ… **Detailed in-IDE diff** (pinpoints exact differing values, e.g. `'email'` vs `'sms'`) | โŒ **No per-value diff** (flags clone locations without a detailed literal breakdown) | +| **Reporting & diagnostics** | IDE Problems & Related Locations | Markdown, JSON, GitHub Actions annotations, % duplication metrics | +| **Disk cache usage** | โœ… | โœ… | + +> **๐Ÿ’ก Best Together:** Use `avoid_duplicate_code` for instant IDE feedback, +> and `dedupe` for CI/CD quality gates and repository-wide code clone audits. diff --git a/doc/docusaurus/docs/3_other_notable_packages/dead_code.md b/doc/docusaurus/docs/3_other_notable_packages/dead_code.md new file mode 100644 index 00000000..9feed20b --- /dev/null +++ b/doc/docusaurus/docs/3_other_notable_packages/dead_code.md @@ -0,0 +1,61 @@ +--- +sidebar_label: Dead code +sidebar_position: 1 +description: Find and remove unused code. +--- + +# Dead Code + +Tools for identifying, analyzing, and removing unreachable declarations, +forgotten APIs, and dead code across Dart and Flutter codebases. + +## [ciach](https://pub.dev/packages/ciach) + +[![pub package](https://img.shields.io/pub/v/ciach.svg)](https://pub.dev/packages/ciach) + +A command-line tool acting as a wrapper around the **Dart Analysis Server**. +It queries the analysis server for explicit references to every declaration in +the project. + +`ciach` excels at deep codebase cleanup, inspecting internal class members, +methods, constructors, extensions, and fields. + +- **Links**: [pub.dev](https://pub.dev/packages/ciach) ยท + [GitHub](https://github.com/maksimr/ciach) + +--- + +## [undead](https://pub.dev/packages/undead) + +[![pub package](https://img.shields.io/pub/v/undead.svg)](https://pub.dev/packages/undead) + +Deterministic reachability and dead/unused declaration analysis library and +CLI for Dart and Flutter packages. + +It performs whole-package AST analysis using `package:analyzer` to build a +reachability graph from known entrypoints to all internal declarations, +identifying unused top-level declarations, classes, functions, and variables. + +- **Links**: [pub.dev](https://pub.dev/packages/undead) ยท + [GitHub](https://github.com/kevmoo/analytica.dart/tree/main/packages/undead) + +--- + +## Comparison: `ciach` vs `undead` + +| | `ciach` | `undead` | +| :--- | :--- | :--- | +| **Detection Engine** | Queries the **Dart Analysis Server** for explicit references to declarations. | Parses AST and builds a **reachability graph** from known entrypoints. | +| **Analysis Depth** | **Deep:** Scans inside classes, including methods, constructors, extensions, and fields. | **Top-level:** Only identifies unused top-level declarations, classes, functions, and global variables. | +| **Test Handling** | Scans the entire workspace including `test/`. May flag reflection-invoked tests as dead code (requires `-e 'test/**'` exclusions). | Ignores `test/` by default in library mode. Focuses primarily on public API reachability. | +| **Suppressions / Ignores** | โŒ **No inline comments.** (Requires CLI exclusions like `-e 'file'` or `@pragma`) | โœ… **Granular inline comments.** (Via `// undead:ignore` & `_for_file`) | +| **Auto-Removal** | โœ… **Supported** (via `--remove` flag) | โŒ **Analysis only** | + +### Summary & Recommendations + +- **Use `ciach`** when you want to aggressively find and clean up unused + internal methods, fields, and members deep inside your application codebase, + and you want an automated way to delete them. +- **Use `undead`** when you are building a reusable package or library and + want to audit public API reachability, ensuring you don't expose forgotten + top-level declarations. From 72ab29cb51782b869358a4c47b477186f360d4f2 Mon Sep 17 00:00:00 2001 From: Illia Aihistov Date: Thu, 10 Sep 2026 09:38:18 +0300 Subject: [PATCH 2/4] docs: add index link and descriptions to rulesets documentation pages --- doc/docusaurus/docs/1_rulesets/_category_.json | 6 +++++- doc/docusaurus/docs/1_rulesets/main.md | 1 + doc/docusaurus/docs/1_rulesets/test.md | 1 + 3 files changed, 7 insertions(+), 1 deletion(-) diff --git a/doc/docusaurus/docs/1_rulesets/_category_.json b/doc/docusaurus/docs/1_rulesets/_category_.json index 65dfe4ef..01ee0b0d 100644 --- a/doc/docusaurus/docs/1_rulesets/_category_.json +++ b/doc/docusaurus/docs/1_rulesets/_category_.json @@ -1,4 +1,8 @@ { "label": "Pre-configured rule sets", - "position": 1 + "position": 1, + "link": { + "type": "generated-index", + "description": "Pre-configured rule sets for applications and tests." + } } diff --git a/doc/docusaurus/docs/1_rulesets/main.md b/doc/docusaurus/docs/1_rulesets/main.md index 0a3d8cf5..36e0624e 100644 --- a/doc/docusaurus/docs/1_rulesets/main.md +++ b/doc/docusaurus/docs/1_rulesets/main.md @@ -1,6 +1,7 @@ --- sidebar_label: Main sidebar_position: 1 +description: Static analysis for application code. --- # Main diff --git a/doc/docusaurus/docs/1_rulesets/test.md b/doc/docusaurus/docs/1_rulesets/test.md index 8120df3e..4a8d21c8 100644 --- a/doc/docusaurus/docs/1_rulesets/test.md +++ b/doc/docusaurus/docs/1_rulesets/test.md @@ -1,6 +1,7 @@ --- sidebar_label: Test sidebar_position: 2 +description: Static analysis for autotests. --- # Test From f61394418568f9fd5318d26d382d5090c1313a5d Mon Sep 17 00:00:00 2001 From: Illia Aihistov Date: Thu, 10 Sep 2026 12:02:26 +0300 Subject: [PATCH 3/4] docs: update custom lints category index, remove notable packages page, and add compact card styling --- .../docs/2_custom_lints/_category_.json | 6 ++- .../docs/3_other_notable_packages.md | 38 ------------------- doc/docusaurus/src/css/custom.css | 15 ++++++++ 3 files changed, 20 insertions(+), 39 deletions(-) delete mode 100644 doc/docusaurus/docs/3_other_notable_packages.md diff --git a/doc/docusaurus/docs/2_custom_lints/_category_.json b/doc/docusaurus/docs/2_custom_lints/_category_.json index 6dd52a9b..037b13a1 100644 --- a/doc/docusaurus/docs/2_custom_lints/_category_.json +++ b/doc/docusaurus/docs/2_custom_lints/_category_.json @@ -1,4 +1,8 @@ { "label": "Custom lints", - "position": 2 + "position": 2, + "link": { + "type": "generated-index", + "description": "Custom lint rules provided by solid_lints." + } } diff --git a/doc/docusaurus/docs/3_other_notable_packages.md b/doc/docusaurus/docs/3_other_notable_packages.md deleted file mode 100644 index a749d515..00000000 --- a/doc/docusaurus/docs/3_other_notable_packages.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -sidebar_label: Other notable packages -sidebar_position: 3 ---- - -# Other Notable Packages - -Notable third-party tools that complement `solid_lints` in keeping Dart and -Flutter codebases clean, robust, and maintainable. - -## [undead](https://pub.dev/packages/undead) - -[![pub package](https://img.shields.io/pub/v/undead.svg)](https://pub.dev/packages/undead) - -Deterministic reachability and dead/unused declaration analysis for Dart and -Flutter packages. - -It performs whole-package AST analysis using `package:analyzer` to build a -reachability graph from known entrypoints to all internal declarations, -identifying unused top-level declarations, classes, functions, and variables. - -- **Links**: [pub.dev](https://pub.dev/packages/undead) ยท - [GitHub](https://github.com/kevmoo/analytica.dart/tree/main/packages/undead) - ---- - -## [cognitive_complexity](https://pub.dev/packages/cognitive_complexity) - -[![pub package](https://img.shields.io/pub/v/cognitive_complexity.svg)](https://pub.dev/packages/cognitive_complexity) - -Algorithmic Cognitive Complexity calculation and Data-Flow analysis library and -CLI tools for Dart and Flutter. - -It implements the Cognitive Complexity principles articulated by SonarSource, -providing an objective way to find and fix overly complex logic and routines. - -- **Links**: [pub.dev](https://pub.dev/packages/cognitive_complexity) ยท - [GitHub](https://github.com/kevmoo/analytica.dart/tree/main/packages/cognitive_complexity) diff --git a/doc/docusaurus/src/css/custom.css b/doc/docusaurus/src/css/custom.css index cc597cdd..6602782b 100644 --- a/doc/docusaurus/src/css/custom.css +++ b/doc/docusaurus/src/css/custom.css @@ -52,3 +52,18 @@ .footer__links { margin: 0; } + +/* Custom Lints cards compact layout */ +a[href*='/custom_lints/'].theme-doc-card-container { + flex-direction: row !important; + padding: 12px 16px !important; + + .theme-doc-card-heading { + margin: 0 !important; + } + + .theme-doc-card-description, + .theme-doc-card-icon { + display: none !important; + } +} From 167d9df2d73addab8cbcb4c1cffab37974f1ee98 Mon Sep 17 00:00:00 2001 From: Illia Aihistov Date: Thu, 10 Sep 2026 12:23:15 +0300 Subject: [PATCH 4/4] docs: update ciach package description, GitHub link, and feature comparison table --- doc/docusaurus/docs/3_other_notable_packages/dead_code.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/docusaurus/docs/3_other_notable_packages/dead_code.md b/doc/docusaurus/docs/3_other_notable_packages/dead_code.md index 9feed20b..e36d7f18 100644 --- a/doc/docusaurus/docs/3_other_notable_packages/dead_code.md +++ b/doc/docusaurus/docs/3_other_notable_packages/dead_code.md @@ -14,14 +14,14 @@ forgotten APIs, and dead code across Dart and Flutter codebases. [![pub package](https://img.shields.io/pub/v/ciach.svg)](https://pub.dev/packages/ciach) A command-line tool acting as a wrapper around the **Dart Analysis Server**. -It queries the analysis server for explicit references to every declaration in +It queries the analysis server for explicit references to declarations in the project. `ciach` excels at deep codebase cleanup, inspecting internal class members, methods, constructors, extensions, and fields. - **Links**: [pub.dev](https://pub.dev/packages/ciach) ยท - [GitHub](https://github.com/maksimr/ciach) + [GitHub](https://github.com/leancodepl/ciach) --- @@ -47,7 +47,7 @@ identifying unused top-level declarations, classes, functions, and variables. | :--- | :--- | :--- | | **Detection Engine** | Queries the **Dart Analysis Server** for explicit references to declarations. | Parses AST and builds a **reachability graph** from known entrypoints. | | **Analysis Depth** | **Deep:** Scans inside classes, including methods, constructors, extensions, and fields. | **Top-level:** Only identifies unused top-level declarations, classes, functions, and global variables. | -| **Test Handling** | Scans the entire workspace including `test/`. May flag reflection-invoked tests as dead code (requires `-e 'test/**'` exclusions). | Ignores `test/` by default in library mode. Focuses primarily on public API reachability. | +| **Test Handling** | Scans the included workspace files, including `test/` unless excluded. May flag reflection-invoked tests as dead code. | Recognizes package test suites and test-runner entrypoints; library mode uses public `lib/**` exports as reachability roots. | | **Suppressions / Ignores** | โŒ **No inline comments.** (Requires CLI exclusions like `-e 'file'` or `@pragma`) | โœ… **Granular inline comments.** (Via `// undead:ignore` & `_for_file`) | | **Auto-Removal** | โœ… **Supported** (via `--remove` flag) | โŒ **Analysis only** |