Updated documentation and dependency updates

README.md

@@ -25,50 +25,39 @@ Enable the plugin and include `solid_lints` in your project's top-level `analysi
 include: package:solid_lints/analysis_options.yaml
 
 plugins:
-  solid_lints:
+  solid_lints: <INSERT LATEST VERSION>
 ```
 
 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
 include: package:solid_lints/analysis_options_test.yaml
+
+plugins:
+  solid_lints: <INSERT LATEST VERSION>
 ```
 
 Then you can see suggestions in your IDE or you can run checks manually:
 
 ```bash
-dart analyze;
+dart analyze
 ```
 
 # Configuration
 
-You can customize individual rule settings in your `analysis_options.yaml`.
-
-### Option 1: Inside the `plugins` block (Recommended)
+You can customize individual rule settings in your `analysis_options.yaml`:
 
 ```yaml
 plugins:
   solid_lints:
+    version: <INSERT LATEST VERSION>
     diagnostics:
       cyclomatic_complexity:
         max_complexity: 10
       avoid_non_null_assertion: true
 ```
 
-### Option 2: Separate top-level `solid_lints` block
-
-```yaml
-plugins:
-  solid_lints:
-
-solid_lints:
-  diagnostics:
-    cyclomatic_complexity:
-      max_complexity: 10
-    avoid_non_null_assertion: true
-```
-
 # Badge
 
 To indicate that your project is using Solid Lints, you can use the following badge:

example/analysis_options.yaml

@@ -2,28 +2,29 @@ include: package:solid_lints/analysis_options.yaml
 
 plugins:
   solid_lints:
-
-solid_lints:
-  diagnostics:
-    cyclomatic_complexity:
-      max_complexity: 4
-    number_of_parameters:
-      max_parameters: 2
-    function_lines_of_code:
-      max_lines: 50
-    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
-          identifier: wait
-          source: dart:async
-          reason: "Future.wait should be avoided because it looses type safety for the results. Use a Record's `wait` method instead."
-          severity: warning
+    path: ../
+    diagnostics:
+      cyclomatic_complexity:
+        max_complexity: 4
+      number_of_parameters:
+        max_parameters: 2
+      function_lines_of_code:
+        max_lines: 50
+      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
+            identifier: wait
+            source: dart:async
+            reason: >-
+              Future.wait should be avoided because it loses type safety for
+              the results. Use a Record's `wait` method instead.
+            severity: warning

lib/src/utils/docs_parser/output_formatters/docusaurus_formatter.dart

@@ -4,6 +4,7 @@ import 'package:path/path.dart';
 import 'package:solid_lints/src/utils/docs_parser/models/rule_doc.dart';
 import 'package:solid_lints/src/utils/docs_parser/output_formatters/markdown_formatter.dart';
 import 'package:solid_lints/src/utils/docs_parser/output_formatters/rules_documentation_formatter.dart';
+import 'package:yaml/yaml.dart';
 
 /// Formatter that generates markdown files for every separate rule
 class DocusaurusFormatter implements RulesDocumentationFormatter<void> {
@@ -15,41 +16,58 @@ sidebar_position: 0
 
 
 ''';
+  static const _latestVersionPlaceholder = '<INSERT LATEST VERSION>';
   static final _markdownFormatter = MarkdownFormatter();
 
   final Directory _outputDirectory;
   final File _readmeFile;
+  final File _pubspecFile;
 
   /// DocusaurusFormatter
   DocusaurusFormatter({
     required String docusaurusDocsDirPath,
     required String readmePath,
+    required String pubspecPath,
   }) : _outputDirectory = Directory(docusaurusDocsDirPath),
-       _readmeFile = File(readmePath);
+       _readmeFile = File(readmePath),
+       _pubspecFile = File(pubspecPath);
 
   @override
   void format(List<RuleDoc> rules) {
     if (!_outputDirectory.existsSync()) {
       _outputDirectory.createSync(recursive: true);
     }
 
-    File(join(_outputDirectory.parent.path, 'intro.md'))
-      ..createSync()
-      ..writeAsStringSync(_introFileMetadata + _readmeFile.readAsStringSync());
+    final stableVersion = _extractStableVersion();
+    final readmeContent = _readmeFile.readAsStringSync().replaceAll(
+      _latestVersionPlaceholder,
+      stableVersion ?? _latestVersionPlaceholder,
+    );
+
+    File(
+      join(_outputDirectory.parent.path, 'intro.md'),
+    ).writeAsStringSync('$_introFileMetadata$readmeContent');
 
     rules.forEach(_createMarkdownFileForRule);
   }
 
+  String? _extractStableVersion() {
+    if (!_pubspecFile.existsSync()) return null;
+    try {
+      final yaml = loadYaml(_pubspecFile.readAsStringSync());
+      if (yaml case {'version': final String rawVersion}) {
+        return '^${rawVersion.split(RegExp('[-+]')).first}';
+      }
+    } catch (_) {}
+    return null;
+  }
+
   void _createMarkdownFileForRule(RuleDoc rule) =>
-      File(
-          join(_outputDirectory.path, '${rule.name}.md'),
-        )
-        ..createSync()
-        ..writeAsString(
-          _markdownFormatter.formatRuleToMarkdown(
-            rule,
-            includeName: false,
-            parametersAsList: false,
-          ),
-        );
+      File(join(_outputDirectory.path, '${rule.name}.md')).writeAsStringSync(
+        _markdownFormatter.formatRuleToMarkdown(
+          rule,
+          includeName: false,
+          parametersAsList: false,
+        ),
+      );
 }

pubspec.yaml

@@ -15,7 +15,7 @@ dependencies:
   # More details: https://github.com/dart-lang/sdk/issues/61821
   analyzer_plugin: ^0.14.2
   analyzer: ^10.0.1
-  collection: ^1.19.0
+  collection: ^1.19.1
   analysis_server_plugin: ^0.3.3
   equatable: ^2.1.0
   glob: ^2.1.3
@@ -25,9 +25,9 @@ dependencies:
   test: ^1.25.14
 
 dev_dependencies:
-  args: ^2.6.0
+  args: ^2.7.0
   analyzer_testing: ^0.1.9
-  test_reflective_loader: ^0.3.0
+  test_reflective_loader: ^0.4.0
 
 plugin:
   platforms:

tool/generate_web_docs_content.dart

@@ -6,13 +6,16 @@ import 'package:solid_lints/src/utils/docs_parser/output_formatters/docusaurus_f
 import 'package:solid_lints/src/utils/docs_parser/parsers/docs_parser.dart';
 
 void main(List<String> rawArgs) async {
-  final readmeDefaultPath = join(Directory.current.parent.path, 'README.md');
+  final projectRoot = File.fromUri(Platform.script).parent.parent.path;
+
+  final readmeDefaultPath = join(projectRoot, 'README.md');
+  final pubspecDefaultPath = join(projectRoot, 'pubspec.yaml');
   final docusaurusDefaultPath = join(
-    Directory.current.parent.path,
+    projectRoot,
     'doc',
     'docusaurus',
     'docs',
-    'Lints Documentation',
+    '2_custom_lints',
   );
 
   final argsParser = ArgParser()
@@ -38,6 +41,11 @@ void main(List<String> rawArgs) async {
           ' copied as docusaurus intro.md',
       defaultsTo: readmeDefaultPath,
     )
+    ..addOption(
+      'pubspec',
+      help: 'Path to the pubspec.yaml file',
+      defaultsTo: pubspecDefaultPath,
+    )
     ..addMultiOption(
       'suffixes',
       help: 'Filename suffixes that should be parsed',
@@ -55,6 +63,7 @@ void main(List<String> rawArgs) async {
     formatter: DocusaurusFormatter(
       docusaurusDocsDirPath: args['docs-dir'],
       readmePath: args['readme'],
+      pubspecPath: args['pubspec'],
     ),
     ruleFileSuffixes: args['suffixes'],
   ).parse(Directory(path));