Docs/website

examples/data_rules/.dart_tool/package_config.json

@@ -386,7 +386,7 @@
       "languageVersion": "2.17"
     }
   ],
-  "generated": "2023-01-13T14:36:21.478334Z",
+  "generated": "2023-01-14T21:01:26.976686Z",
   "generator": "pub",
   "generatorVersion": "2.17.6"
-}
+}

packages/sidecar_lints/example/analysis_options.yaml

@@ -2,4 +2,4 @@ include: package:lints/recommended.yaml
 
 analyzer:
   plugins:
-    - sidecar
+    # - sidecar

website/sidecar/.dart_tool/package_config.json

@@ -139,6 +139,12 @@
       "packageUri": "lib/",
       "languageVersion": "2.17"
     },
+    {
+      "name": "design_system_lints",
+      "rootUri": "file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/design_system_lints-0.1.0-dev.11",
+      "packageUri": "lib/",
+      "languageVersion": "2.17"
+    },
     {
       "name": "file",
       "rootUri": "file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/file-6.1.4",
@@ -321,7 +327,7 @@
     },
     {
       "name": "sidecar",
-      "rootUri": "../../../packages/sidecar",
+      "rootUri": "file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/sidecar-0.1.0-dev.21",
       "packageUri": "lib/",
       "languageVersion": "2.17"
     },
@@ -331,12 +337,6 @@
       "packageUri": "lib/",
       "languageVersion": "2.12"
     },
-    {
-      "name": "sidecar_package_utilities",
-      "rootUri": "file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/sidecar_package_utilities-0.1.0-dev.7",
-      "packageUri": "lib/",
-      "languageVersion": "2.12"
-    },
     {
       "name": "source_gen",
       "rootUri": "file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/source_gen-1.2.6",
@@ -476,7 +476,7 @@
       "languageVersion": "2.17"
     }
   ],
-  "generated": "2023-01-09T06:26:19.624577Z",
+  "generated": "2023-01-23T16:33:20.511367Z",
   "generator": "pub",
   "generatorVersion": "2.17.6"
 }

website/sidecar/.packages

@@ -3,7 +3,7 @@
 # 
 # For more info see: https://dart.dev/go/dot-packages-deprecation
 # 
-# Generated by pub on 2023-01-09 01:26:19.616588.
+# Generated by pub on 2023-01-23 11:33:20.502685.
 _fe_analyzer_shared:file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/_fe_analyzer_shared-47.0.0/lib/
 analyzer:file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/analyzer-4.7.0/lib/
 analyzer_plugin:file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/analyzer_plugin-0.11.1/lib/
@@ -27,6 +27,7 @@ convert:file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/convert-3.1.
 coverage:file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/coverage-1.6.1/lib/
 crypto:file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/crypto-3.0.2/lib/
 dart_style:file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/dart_style-2.2.4/lib/
+design_system_lints:file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/design_system_lints-0.1.0-dev.11/lib/
 file:file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/file-6.1.4/lib/
 fixnum:file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/fixnum-1.0.1/lib/
 freezed:file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/freezed-2.2.0/lib/
@@ -57,9 +58,8 @@ shelf:file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/shelf-1.4.0/li
 shelf_packages_handler:file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/shelf_packages_handler-3.0.1/lib/
 shelf_static:file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/shelf_static-1.1.1/lib/
 shelf_web_socket:file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/shelf_web_socket-1.0.3/lib/
-sidecar:../../packages/sidecar/lib/
+sidecar:file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/sidecar-0.1.0-dev.21/lib/
 sidecar_annotations:file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/sidecar_annotations-0.1.0-dev.1/lib/
-sidecar_package_utilities:file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/sidecar_package_utilities-0.1.0-dev.7/lib/
 source_gen:file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/source_gen-1.2.6/lib/
 source_helper:file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/source_helper-1.3.3/lib/
 source_map_stack_trace:file:///Users/pattobrien/.pub-cache/hosted/pub.dartlang.org/source_map_stack_trace-2.1.1/lib/

website/sidecar/.vscode/launch.json

@@ -0,0 +1,49 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "sidecar",
+            "request": "launch",
+            "type": "dart"
+        },
+        {
+            "name": "snippets",
+            "cwd": "docs/usage/snippets",
+            "request": "launch",
+            "type": "dart"
+        },
+        {
+            "name": "snippets (profile mode)",
+            "cwd": "docs/usage/snippets",
+            "request": "launch",
+            "type": "dart",
+            "flutterMode": "profile"
+        },
+        {
+            "name": "snippets (release mode)",
+            "cwd": "docs/usage/snippets",
+            "request": "launch",
+            "type": "dart",
+            "flutterMode": "release"
+        },
+        {
+            "name": "bloc_feature_structure",
+            "program": "lib/src/tutorials/bloc_feature_structure/example/.dart_tool/sidecar/debug.dart",
+            "request": "launch",
+            "type": "dart",
+            "args": [
+                "--enable-vm-service",
+                "--debug",
+            ]
+        },
+        {
+            "name": "hello_world",
+            "cwd": "lib/src/tutorials/hello_world",
+            "request": "launch",
+            "type": "dart"
+        }
+    ]
+}

website/sidecar/docs/concepts/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Core Concepts",
+  "position": 3,
+  "link": {
+    "type": "generated-index"
+  }
+}

website/sidecar/docs/concepts/integration_testing.mdx

@@ -0,0 +1,45 @@
+---
+title: Integration Testing
+sidebar_position: 3
+description: ""
+---
+
+import CodeBlock from '@theme/CodeBlock';
+import testing from "!!raw-loader!./snippets/testing.dart";
+import { 
+    trimSnippet,
+    generateSnippet,
+    CodeSnippet,
+} from "../../src/components/CodeSnippet";
+
+Sidecar ships with a series of test utilities that make it easy to write integration tests for Sidecar rules.
+
+When writing rule tests, we must create a string containing example code that we expect to trigger or not trigger a lint.
+
+The below snippet shows code that we would expect to show a lint for the `avoid_edge_insets_literal` rule from design_system_lints. The rule
+is expected to find values used in an `EdgeInsets` constructor, and show a lint if that value is not annotated
+with `@designSystem` (see [design_system_lints](https://pub.dev/packages/design_system_lints) for
+a full explanation of these rules).
+
+<CodeBlock language="dart">{generateSnippet(testing, ['Content2'])}</CodeBlock>
+
+In this example, we would expect a lint to be reported underneath the `2.0` value. We can easily test for this,
+by writing the following rule in the `test` directory of our rule package:
+
+<CodeBlock title="test/src/avoid_edge_insets_literal_test.dart"  language="dart">{generateSnippet(testing, ['StartTest', 'TestEnd', 'RuleTest2' ])}</CodeBlock>
+
+Before we can run any rule test, we must first use the `setUpRules` function with the particular rule we're looking to test (here, `AvoidEdgeInsetsLiteral`). 
+We can then use the `ExpectedText` test utility to check if a lint is found over the particular code `2.0`. We also make
+the test description `EdgeInsets.all`, as that's exactly the use case we're testing for.
+
+If we want to test that a lint is found when using a different instantiation of `EdgeInsets` (e.g. `EdgeInsets.only`),
+we can create another test that checks each of the parameters given to `EdgeInsets.only` (i.e. `left`, `right`, `top`, `bottom`) 
+by writing 4 different `ExpectedText` values and providing them to our `ruleTest`:
+
+<CodeBlock language="dart">{generateSnippet(testing, ['Imports', 'StartTest', 'TestEnd', 'RuleTest3', 'Content3'])}</CodeBlock>
+
+Finally, if we write a test where we expect no lints (such as when our `EdgeInset` values are annotated with `@designSystem`), 
+we simply simply leave the `ExpectedText` array empty for our `ruleTest`:
+
+<CodeBlock language="dart">{generateSnippet(testing, ['Imports', 'StartTest', 'TestEnd', 'RuleTest1', 'Content1'])}</CodeBlock>
+

website/sidecar/docs/concepts/rule_creation_checklist.mdx

@@ -0,0 +1,26 @@
+---
+title: Rule Creation Checklist
+sidebar_position: 1
+description: ""
+---
+
+import CodeBlock from '@theme/CodeBlock';
+import {
+  trimSnippet,
+  CodeSnippet,
+} from "../../src/components/CodeSnippet";
+
+If you're creating a new lint rule and lints are not appearing in the IDE of an example project,
+ you can follow this checklist for requirements.
+
+
+| Description                                 | Examples | Lints Available |
+|---------------------------------------------|---------|:----------------:|
+| Rule has a unique RuleCode ID in snake_case | `LintCode('avoid_edge_insets_literal')` | ✅ |
+| The Rule's ClassName is the PascalCase equivalent of the RuleCode ID | `class AvoidEdgeInsetsLiteral extends LintRule {...}` | ✅ |
+| The `code.package` value matches the name given to the rule package | `LintCode(..., package: 'design_system_lints')` | ✅ |
+| Lint Rule is exported from `lib/<package_name>.dart`  | | 🚧 |
+
+
+It's recommended that you use the lints included in [`package:sidecar_lints`](https://pub.dev/packages/sidecar_lints) to enforce the above rules
+on your Sidecar-based rule package.

website/sidecar/docs/concepts/snippets/testing.dart

@@ -0,0 +1,66 @@
+/* SNIP Imports */
+import 'package:design_system_lints/design_system_lints.dart';
+import 'package:sidecar/test.dart';
+import 'package:test/test.dart';
+
+/* SNIP Imports END */
+/* SNIP Content1 */
+const contentDesignSystem = '''
+import 'package:design_system_annotations/design_system_annotations.dart';
+import 'package:flutter/material.dart';
+@designSystem
+class DesignSystemX {
+  static const value = 3.1;
+}
+final edgeInsets = EdgeInsets.all(DesignSystemX.value);
+''';
+/* SNIP Content1 END */
+/* SNIP Content2 */
+const contentEdgeInsetsAll = '''
+import 'package:flutter/material.dart';
+class MyWidget extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return Container(
+      padding: EdgeInsets.all(2.0),
+    );
+  }
+}
+''';
+/* SNIP Content2 END */
+/* SNIP Content3 */
+const contentEdgeInsetsOnly = '''
+import 'package:flutter/material.dart';
+class MyWidget extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return Container(
+      padding: EdgeInsets.only(left: 1.1, right: 1.2, top: 1.3, bottom: 1.4),
+    );
+  }
+}
+''';
+/* SNIP Content3 END */
+/* SNIP StartTest */
+void main() {
+  group('avoid_edge_insets_literal:', () {
+    setUpRules([AvoidEdgeInsetsLiteral()]);
+/* SNIP StartTest END */
+/* SNIP RuleTest1 */
+    ruleTest('EdgeInsets using Design System', contentDesignSystem, []);
+/* SNIP RuleTest1 END */
+/* SNIP RuleTest2 */
+    ruleTest('EdgeInsets.all', contentEdgeInsetsAll, [ExpectedText('2.0')]);
+/* SNIP RuleTest2 END */
+/* SNIP RuleTest3 */
+    ruleTest('EdgeInsets.only', contentEdgeInsetsOnly, [
+      ExpectedText('1.1'),
+      ExpectedText('1.2'),
+      ExpectedText('1.3'),
+      ExpectedText('1.4'),
+    ]);
+/* SNIP RuleTest3 END */
+    /* SNIP TestEnd */
+  });
+}
+/* SNIP TestEnd END */

website/sidecar/docs/concepts/snippets/type_checking.dart

@@ -0,0 +1,44 @@
+import 'package:analyzer/dart/ast/ast.dart';
+import 'package:sidecar/sidecar.dart';
+
+/* SNIP TypeChecker */
+// 1. Create the TypeChecker
+const statelessWidget =
+    TypeChecker.fromPackage('StatelessWidget', package: 'flutter');
+
+/* SNIP TypeChecker END */
+/* SNIP ClassStart */
+class MyLint extends LintRule {
+/* SNIP ClassStart END */
+  @override
+  LintCode get code => throw UnimplementedError();
+
+  @override
+  void initializeVisitor(NodeRegistry registry) {
+    // TODO: implement initializeVisitor
+  }
+  /* SNIP VisitMethod */
+  @override
+  void visitInstanceCreationExpression(InstanceCreationExpression node) {
+    // 2. Use the TypeChecker to check the type of a particular AstNode
+    final returnType = node.constructorName.staticElement?.returnType;
+    if (statelessWidget.isAssignableFromType(returnType)) {
+      // do something
+    }
+  }
+  /* SNIP VisitMethod END */
+  /* SNIP ClassEnd */
+}
+/* SNIP ClassEnd END */
+
+/* SNIP DartType */
+@override
+void visitInstanceCreationExpression(InstanceCreationExpression node) {
+  // 2. Use the TypeChecker to check the type of a particular AstNode
+  const colorTypeChecker = TypeChecker.fromDart('Color', package: 'ui');
+  final returnType = node.constructorName.staticElement?.returnType;
+  if (colorTypeChecker.isAssignableFromType(returnType)) {
+    // do something
+  }
+}
+/* SNIP DartType END */

website/sidecar/docs/concepts/type_checking.mdx

@@ -0,0 +1,35 @@
+---
+title: Type Checking
+sidebar_position: 2
+description: ""
+---
+
+import CodeBlock from '@theme/CodeBlock';
+import dartTypeChecker from "!!raw-loader!./snippets/type_checking.dart";
+import {
+    generateSnippet,
+  CodeSnippet,
+} from "../../src/components/CodeSnippet";
+
+When creating a lint rule, you will often need to check if a node is of a certain type. 
+For example, you may want to find all class declarations which extend
+`StatelessWidget` in order to perform some analysis on them.
+
+Unfortunately, we cannot just use the `is` keyword to check if a node is of a certain type,
+because the analyzer can only provide us with `DartType` objects, which are not the same as
+the `Type` objects we'd typically use when checking types in Dart programs.
+
+Fortunately, Sidecar ships with its own `TypeChecker` utility, which provides an easy
+way for checking if an AstNode is of a certain type:
+
+<CodeBlock language="dart">{generateSnippet(dartTypeChecker, ['TypeChecker', 'ClassStart', 'ClassEnd', 'VisitMethod'])}</CodeBlock>
+
+There are two notable ways to create a TypeChecker:
+
+- `TypeChecker.fromName` - Used for non-Dart packages
+- `TypeChecker.fromDartType` - Used for `dart` packages like `dart:core` or `dart:async`
+
+
+<CodeBlock language="dart">{generateSnippet(dartTypeChecker, ['DartType'])}</CodeBlock>
+
+In both cases, the utility takes the name of the Type and the name of the Type's package.