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 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/_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.md b/doc/docusaurus/docs/3_other_notable_packages/code_duplication.md similarity index 57% rename from doc/docusaurus/docs/3_other_notable_packages.md rename to doc/docusaurus/docs/3_other_notable_packages/code_duplication.md index db0a8b94..60fa8572 100644 --- a/doc/docusaurus/docs/3_other_notable_packages.md +++ b/doc/docusaurus/docs/3_other_notable_packages/code_duplication.md @@ -1,43 +1,13 @@ --- -sidebar_label: Other notable packages -sidebar_position: 3 +sidebar_label: Code duplication +sidebar_position: 2 +description: Detect duplicate code clones. --- -# Other Notable Packages +# Code Duplication -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) - ---- +Tools and engines for detecting copy-pasted fragments and structural clones +across Dart and Flutter codebases. ## [dedupe](https://pub.dev/packages/dedupe) @@ -52,9 +22,9 @@ 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` +## Comparison: [`avoid_duplicate_code`](../2_custom_lints/avoid_duplicate_code.md) vs `dedupe` -| Feature / Scenario | `avoid_duplicate_code` | `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 | @@ -68,6 +38,3 @@ across files and packages with fast incremental analysis. > **💡 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..e36d7f18 --- /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 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/leancodepl/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 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** | + +### 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. 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; + } +}