refactor: update automatic documentation generation (#315)

* feat: handle docs parser structured parameters

* feat: implement macro and template support in documentation parser and update parameter metadata

* docs: update documentation and examples for analysis_server_plugin migration

* refactor: move and modularize documentation parsing utilities and improve rule parsing logic

* fix: handle null field types in parameters parser and refine macro circular dependency detection logic

* refactor: enhance documentation error reporting by including source context and specific field names

* refactor: use toSource for type parsing and improve file name suffix extraction logic

* refactor: extract parser extensions and optimize AST navigation and comment processing logic

* refactor: extract file reading logic into FileUtils and modernize ParserUtils implementation

---------

Co-authored-by: Illia Aihistov <illia.aihistov-us@solid.software>

Author: solid-illiaaihistov

README.md

@@ -19,13 +19,16 @@ dev_dependencies:
   solid_lints: <INSERT LATEST VERSION>
 ```
 
-And then include `solid_lints` into your project top-level `analysis_options.yaml`:
+Enable the plugin and include `solid_lints` in your project's top-level `analysis_options.yaml`:
 
 ```yaml
 include: package:solid_lints/analysis_options.yaml
+
+plugins:
+  solid_lints:
 ```
 
-Also you can use a specialized rule set designed for Dart tests.
+Also, you can use a specialized rule set designed for Dart tests.
 Add an `analysis_options.yaml` file under the `test/` directory, and include the ruleset:
 
 ```yaml
@@ -36,7 +39,18 @@ Then you can see suggestions in your IDE or you can run checks manually:
 
 ```bash
 dart analyze;
-dart run custom_lint;
+```
+
+# Configuration
+
+You can customize individual rule settings in your `analysis_options.yaml` under the `solid_lints` configuration block:
+
+```yaml
+solid_lints:
+  diagnostics:
+    cyclomatic_complexity:
+      max_complexity: 10
+    avoid_non_null_assertion: true
 ```
 
 # Badge

doc/docusaurus/docs/1_rulesets/test.md

@@ -65,6 +65,12 @@ Given the quite large threshold configured for this metric we considered extract
 
 Both options didn't look right, so we decided that tests are ok to be long.
 
+## cyclomatic_complexity
+
+State: **Disabled**.
+
+Since we're not using the `function_lines_of_code` rule, the `main()` function in tests can have high cyclomatic complexity. For the rationale against splitting up `main()` in tests, see the comments for `function_lines_of_code` above.
+
 ## prefer_match_file_name
 
 State: **Disabled**.

doc/docusaurus/package.json

@@ -16,8 +16,8 @@
     "typecheck": "tsc"
   },
   "dependencies": {
-    "@docusaurus/core": "^3.1.0",
-    "@docusaurus/preset-classic": "^3.1.0",
+    "@docusaurus/core": "^3.10.1",
+    "@docusaurus/preset-classic": "^3.10.1",
     "@easyops-cn/docusaurus-search-local": "^0.40.1",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.1.0",

doc/docusaurus/yarn.lock

@@ -1,26 +1,25 @@
 include: package:solid_lints/analysis_options.yaml
 
-analyzer:
-  plugins:
-    - custom_lint
+plugins:
+  solid_lints:
 
-custom_lint:
-  rules:
-    - cyclomatic_complexity:
+solid_lints:
+  diagnostics:
+    cyclomatic_complexity:
       max_complexity: 4
-    - number_of_parameters:
+    number_of_parameters:
       max_parameters: 2
-    - function_lines_of_code:
+    function_lines_of_code:
       max_lines: 50
-    - avoid_non_null_assertion
-    - avoid_late_keyword
-    - avoid_global_state
-    - avoid_returning_widgets
-    - avoid_unnecessary_setstate
-    - double_literal_format
-    - avoid_unnecessary_type_assertions
-    - avoid_debug_print_in_release
-    - avoid_using_api:
+    avoid_non_null_assertion: true
+    avoid_late_keyword: true
+    avoid_global_state: true
+    avoid_returning_widgets: true
+    avoid_unnecessary_setstate: true
+    double_literal_format: true
+    avoid_unnecessary_type_assertions: true
+    avoid_debug_print_in_release: true
+    avoid_using_api:
       severity: info
       entries:
         - class_name: Future

example/analysis_options.yaml

@@ -10,7 +10,6 @@ dependencies:
     sdk: flutter
 
 dev_dependencies:
-  custom_lint: ^0.8.1
   solid_lints:
     path: ../
   test: ^1.25.14

example/pubspec.yaml

@@ -1,6 +1,4 @@
 analyzer:
-  plugins:
-    - custom_lint
   exclude:
     # General generated files
     - "**/*.g.dart"

lib/analysis_options.yaml

@@ -3,6 +3,8 @@ import 'package:analyzer/dart/ast/ast.dart';
 /// A parameter model representing excluded annotations for linting.
 /// It defines class-level annotations that indicate when class members
 /// should be ignored during analysis.
+///
+/// @docType String | List<String>
 class ExcludedAnnotationsListParameter {
   /// The set of excluded annotation names.
   final Set<String> excludedAnnotations;

lib/src/common/parameters/excluded_annotations_list_parameter.dart

@@ -8,6 +8,8 @@ import 'package:analyzer/dart/ast/ast.dart';
 ///   - extension
 ///   - extension_type
 ///   - enum
+///
+/// @docType String | List<String>
 class ExcludedEntitiesListParameter {
   /// The parameter model
   final Set<String> excludedEntityNames;

lib/src/common/parameters/excluded_entities_list_parameter.dart

@@ -4,6 +4,8 @@ import 'package:solid_lints/src/common/parameters/excluded_identifier_parameter.
 
 /// A model representing "exclude" parameters for linting, defining
 /// identifiers (classes, methods, functions) to be ignored during analysis.
+///
+/// @docType String | Map | List<String | Map>
 class ExcludedIdentifiersListParameter {
   /// A list of identifiers (classes, methods, functions) that should be
   /// excluded from the lint.