Add lint usage examples (#505)

Author: PiotrRogulski

packages/leancode_lint/CHANGELOG.md

@@ -1,3 +1,7 @@
+# 20.0.1
+
+- Add the `example/` directory with default and custom configuration examples.
+
 # 20.0.0
 
 - **Breaking:** Migrate from custom_lint to the analysis server plugin.

packages/leancode_lint/README.md

@@ -50,6 +50,10 @@ analyzer:
     - '**/*.g.dart'
 ```
 
+> [!TIP]
+> See the [example/](./example) directory for complete, runnable examples
+> with both default and custom configuration.
+
 ## Configuration (custom plugin package)
 
 This section is optional. You only need it if you want to customize the
@@ -581,9 +585,9 @@ Assists are IDE refactorings not related to a particular issue. They can be trig
 
 See linked source code containing explanation in dart doc.
 
-- [Convert positional to named formal](./lib/assists/convert_positional_to_named_formal.dart)
-- [Convert record into nominal type](./lib/assists/convert_record_into_nominal_type.dart)
-- [Convert iterable map to collection-for](./lib/assists/convert_iterable_map_to_collection_for.dart)
+- [Convert positional to named formal](./lib/src/assists/convert_positional_to_named_formal.dart)
+- [Convert record into nominal type](./lib/src/assists/convert_record_into_nominal_type.dart)
+- [Convert iterable map to collection-for](./lib/src/assists/convert_iterable_map_to_collection_for.dart)
 
 [pub-badge]: https://img.shields.io/pub/v/leancode_lint
 [pub-badge-link]: https://pub.dev/packages/leancode_lint

packages/leancode_lint/example/custom/app/analysis_options.yaml

@@ -0,0 +1,5 @@
+include: package:leancode_lint/analysis_options.yaml
+
+plugins:
+  my_lints:
+    path: ../my_lints

packages/leancode_lint/example/custom/app/lib/design_system.dart

@@ -0,0 +1,31 @@
+import 'package:flutter/material.dart';
+
+/// Design system text widget.
+class AppText extends StatelessWidget {
+  const AppText(this.data, {super.key});
+
+  final String data;
+
+  @override
+  Widget build(BuildContext context) {
+    // When ignoring custom lints, use the prefix with the package name.
+    // If you provide a custom name to the `LeanCodeLintPlugin`, use it here:
+    // ignore: my_lints/use_design_system_item_AppText
+    return Text(data);
+  }
+}
+
+/// Design system scaffold widget.
+class AppScaffold extends StatelessWidget {
+  const AppScaffold({super.key, this.appBar, required this.body});
+
+  final PreferredSizeWidget? appBar;
+  final Widget body;
+
+  @override
+  Widget build(BuildContext context) {
+    // Ignores are case-insensitive:
+    // ignore: my_lints/use_design_system_item_appscaffold
+    return Scaffold(appBar: appBar, body: body);
+  }
+}

packages/leancode_lint/example/custom/app/lib/main.dart

@@ -0,0 +1,45 @@
+import 'package:flutter/material.dart';
+
+import 'design_system.dart';
+
+void main() {
+  runApp(const CustomExampleApp());
+}
+
+Future<void> fetchData() async {
+  try {
+    await Future<void>.delayed(const Duration(seconds: 1));
+  } catch (error, stackTrace) {
+    debugPrint('$error\n$stackTrace');
+  }
+}
+
+class CustomExampleApp extends StatelessWidget {
+  const CustomExampleApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      title: 'Custom Config Example',
+      theme: ThemeData(colorScheme: .fromSeed(seedColor: Colors.green)),
+      home: const CustomExampleHome(),
+    );
+  }
+}
+
+class CustomExampleHome extends StatelessWidget {
+  const CustomExampleHome({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return AppScaffold(
+      appBar: AppBar(title: const AppText('leancode_lint custom config')),
+      body: const Center(
+        child: ElevatedButton(
+          onPressed: fetchData,
+          child: AppText('Trigger try-catch'),
+        ),
+      ),
+    );
+  }
+}

packages/leancode_lint/example/custom/app/pubspec.yaml

@@ -0,0 +1,20 @@
+name: custom_example_app
+description: Example app using leancode_lint with custom configuration.
+publish_to: none
+
+environment:
+  sdk: '>=3.10.0 <4.0.0'
+
+dependency_overrides:
+  # Flutter pins meta to 1.17.0, but the plugin packages require 1.18.0
+  meta: ^1.18.0
+
+dependencies:
+  flutter:
+    sdk: flutter
+
+dev_dependencies:
+  flutter_test:
+    sdk: flutter
+  my_lints:
+    path: ../my_lints

packages/leancode_lint/example/custom/my_lints/lib/main.dart

@@ -0,0 +1,24 @@
+import 'package:leancode_lint/plugin.dart';
+
+/// Custom plugin with project-specific configuration.
+///
+/// - Uses `error` and `stackTrace` for catch parameters
+/// - Configures design system replacements (e.g. use AppText instead of Text)
+final plugin = LeanCodeLintPlugin(
+  name: 'my_lints',
+  config: const LeanCodeLintConfig(
+    catchParameterNames: CatchParameterNamesConfig(
+      exception: 'error',
+      stackTrace: 'stackTrace',
+    ),
+    designSystemItemReplacements: {
+      'AppText': [
+        DesignSystemForbiddenItem(name: 'Text', packageName: 'flutter'),
+        DesignSystemForbiddenItem(name: 'RichText', packageName: 'flutter'),
+      ],
+      'AppScaffold': [
+        DesignSystemForbiddenItem(name: 'Scaffold', packageName: 'flutter'),
+      ],
+    },
+  ),
+);

packages/leancode_lint/example/custom/my_lints/pubspec.yaml

@@ -0,0 +1,10 @@
+name: my_lints
+description: Custom analyzer plugin with leancode_lint configuration.
+publish_to: none
+
+environment:
+  sdk: '>=3.10.0 <4.0.0'
+
+dependencies:
+  leancode_lint:
+    path: ../../..

packages/leancode_lint/example/default/analysis_options.yaml

@@ -0,0 +1,5 @@
+include: package:leancode_lint/analysis_options.yaml
+
+plugins:
+  leancode_lint:
+    path: ../..

packages/leancode_lint/example/default/lib/main.dart

@@ -0,0 +1,43 @@
+import 'package:flutter/material.dart';
+
+void main() {
+  runApp(const DefaultExampleApp());
+}
+
+Future<void> fetchData() async {
+  try {
+    await Future<void>.delayed(const Duration(seconds: 1));
+  } catch (err, st) {
+    debugPrint('$err\n$st');
+  }
+}
+
+class DefaultExampleApp extends StatelessWidget {
+  const DefaultExampleApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      title: 'Default Config Example',
+      theme: ThemeData(colorScheme: .fromSeed(seedColor: Colors.blue)),
+      home: const DefaultExampleHome(),
+    );
+  }
+}
+
+class DefaultExampleHome extends StatelessWidget {
+  const DefaultExampleHome({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(title: const Text('leancode_lint default config')),
+      body: const Center(
+        child: ElevatedButton(
+          onPressed: fetchData,
+          child: Text('Trigger try-catch'),
+        ),
+      ),
+    );
+  }
+}