Below are the definitions for different stages of project setup and configuration:

Project Initialization

New Dart or Flutter project that does not yet have sidecar initialized.

• create a base plugin for project lints/edits to live in (inside directory)
• insert base plugin directory into project pubspec.yaml
• add watcher task (e.g. VSCode tasks)

Rebuild Project Plugin

• parse sidecar plugin configuration for declared lints/edits
• add plugin configuration lints/edits into project-plugin pubspec.yaml and run pub get
• generate bootstrap functions based on lint/fix configurations
• restart plugin

Watch Project Configuration Changes

e.g. on pubspec.yaml or analysis_options.yaml changes

• run sidecar rebuild on every config file change

Related issues:

• CLI doesn't output correct lint severity
• remove annotatedNodes from initialize function / SidecarBase

A lint rule should default to one of the following:

a) inherit the includes glob of the sidecar config, or
b) inherit the includes globs defined for the lint itself (in the projects yaml file), or
c) have a LintRule-specific default

The order of which the globs should be applied should be dependent on the following definition order:

Lint-Explicit > Lint-Default > Package-Explicit > Package-Default > Sidecar-Explicit > Sidecar-Default

abstract class LintRule {
  const LintRule([this.includesFromConfiguration]);
  final List<Glob>? includesFromConfiguration;
  ...

  List<Glob> get includes(String path) => includesFromConfiguration ?? [Glob('bin/**'), Glob('lib/**')];

}

During plugin initialization phase:

void init() {
  
  for (final lintBuilder in lintBuilders) {
    final packageConfig; // config comes from either a) project's sidecar.yaml OR b) the lint-package's definitions
    final lint = lintBuilder(packageConfig);
    allLints.add(lint);
  }

}

During handleAnalysis phase:

for (final lint in lints) {
  
  if (lint.includes.any((glob) => glob.matches(analysisFilePath))) {
    // lint is analyzed
  }

}

for a riverpod package version 2.0.0

utils package: riverpod_analyzer v2.0.0
lints package: riverpod_lints v0.1.0 (i.e. version doesnt need to match 2.0.0, we can version it independently of the actual package version)

• create a dart-based utility package
• create a flutter based utility package

example: riverpod_prefer_consumer_widget

The Analyzed and Reported AstNode should be the ClassDeclaration, but the highlighted node would be better served as the class name (i.e. Highlighted AstNode = SimpleIdentifier) or the extended superclass (i.e. Highlighted AstNode = Identifier).

We need to expose a separate method for the LintError class that allows subclasses to declare which node should be highlighted.

upon every new context collection creation:

• Parse sidecar configuration
• Calculate LintRule/CodeEdit glob includes

• CLI init function should use dart CLI to add plugin to pubspec (adding a string is too fragile, caused a single-event bug)
• Init function should add a default lint to the analysis_options file for better DX
• Write up explaining architecture
• Validate lints and code edits work in all appropriate scenarios to demonstrate functionality

Since the main objective of Sidecar was to have enhanced performance, it makes sense to solve the obvious quality-related performance issues before getting feedback - otherwise, users will be confused by the value proposition.

Runtime Enhancements:

• All files are attempted to be resolved before we check if the file is included in any globs; when we calculate "analyzedFiles" for a context, we should only look at folders/subfolders that are permitted by the globs (i.e. look at folders, not individual files)

We can use zones to control how printing is handled.

see this zone thread: https://twitter.com/rexthecoder/status/1585003704134299649?s=20&t=F33mFgvdpg6WB2K-tKHkZQ

This would be useful for the following reasons:

• being able to use log() (from developer package) would clean up a lot of the code throughout the project
• users would be able to use print or log to output to debugger

Log Zones

• ISOLATE
• MIDDLEMAN
• [RULE-ID]

Log Framework

• DateTime
• Zone
• Function
• Data/Message/etc.
• [error, stackTrace]

• Run plugin from within .dartServer directory
• Dependencies are set within pubspec.yaml
• determine sidecar dependencies that should be added to plugin rule constructors (similar to how build_runner handles this)

This would probably best be paired with eventual CLI functionality, to run a lint or code edit.

LintRule debugger

• Basic Lint debugger

Hot Reload

• Hot reload on LintRule or CodeEdit changes
• Hot reload on target source code changes

• Create a Code Edit class for declarations to extend
• Create bootstrapper that builds based off of analysis_options.yaml configuration

• Generate TypeChecker classes
• Relative file paths of generated package match file paths of package
• Generate type checkers via sidecar CLI

Dart CLI Example:

DCM CLI Example (source):

Use of histograms could utilize this package: https://github.com/dart-lang/sdk/tree/main/pkg/scrape

it's possible for there to be many varying and conflicting implementations of a certain lint name. For example, avoid_string_literals could be avoiding strings for any reason.

Instead of having lint/fix developers compete for lint names, or in lieu of arguing what the "proper definitions" of each lint could or should be, itd be much more reasonable to give lints and fixes namespace prefixes to avoid conflicts.

For example:

• riverpod::prefer_consumer_widget
• dart::prefer_adjacent_string_concatenation
• flutter::use_full_hex_values_for_flutter_colors

Open Questions:

• what should be the name of the package (with or without namespace)
• name of the LintError.code (with or without namespace)
• name of the lint in analysis file (with or without namespace)
• name of the defined Lint/Fix class (with or without namespace)

Proposed pubspec file format:

name: riverpod_avoid_stateful_widgets
publish_to: cloudsmith.io/riverpod
version: 0.1.0
micropub: sidecar

environment:
  sdk: ">=2.17.5 <3.0.0"

sidecar:
  type: lint

dependencies:
  riverpod_lint_utils: 0.1.0
  sidecar: ^0.1.0

It seems like the plugin properly shuts down (RAM usage halves, lints no longer update when source code is edited), however, the last lint state is left in the editor.

Lints are, however, removed from bootstrap function.

Included lints for Sidecar

• Code Assist to print AstNode info to code comment
• Highlight Yaml files that dont conform to a certain lints' specifications

Utilize pub's dependency checking abilities to figure out what version of sidecar_analyzer_plugin should be used as the base plugin. Also use this to determine lint/fix versions.

We should also include a way to override this path with a local path, to help with development.

To do:

• Break up sidecar_analyzer_plugin into 2 packages: 1 with only bootstrap functions, 1 with the rest of the implementations
• Read package_config.json file and extract the desired plugin version number

Note: this version may change at any time over the course of the project.

It's probably best that the implementation code of sidecar_analyzer_plugin is separated into another package, so that the copied package does not have to be updated as frequently. This second package can be a simple interface of the plugin package.

Some errors are missing, while some other errors may be not descriptive enough.

analysis_options.yaml errors:

• Lints: invalid 'severity' value (can only be 'warning', 'error', 'info'
• Lints/Edits includes: invalid glob
• Lints/Edits includes: invalid type (should be list of strings)
• 'sidecar' includes: invalid glob

UX:

• analysis_options.yaml errors should appear while typing (not just after saving file): unsaved file contents cannot be captured using file.readAsString(). Need to rethink how analysis option errors could be made visible.

Wont Do:

• lint package could not be downloaded (unnecessary now that we use pub)
• missing "sidecar" top level variable (highlight sidecar_analyzer_plugin under 'analyzer.plugin' section)

Currently plugin analyzes entire workspace.

We could utilize a feature like VSCode Hover to output the exact subclass of a particular AstNode at the cursor. This could seriously help development of lints / edits.

• SidecarInput annotation and package
• Subclasses of SidecarInput
• SidecarAnnotation model for carrying annotation info (e.g. sourceUrl, AstNode)

Working with Types

• TypeChecker (e.g. Widget, Color, Provider)

Users may want to create very project-specific lints or edits that wouldn't make sense to bundle up separately from the project itself. Therefore, defining lints/edits within the project directory is necessary to make defining project-specific rules as simple as possible.

Requirements:

• a way to define from-path plugin dependencies

Currently, flutter projects cannot use plugin because dart pub get fails for Flutter packages.

lint configurations:

• allow lints to specify a configuration
• rethink if lint configurations need to explicitly be under 'configuration' key

lint configuration errors:

• instead of killing entire plugin, a bad lint/edit configuration should throw an analysis_options error (should these errors be logged or show up visually in IDE?)
• Lints/Edits: invalid configuration (can we specify what's invalid about it?)

• Explicitly separate LintRule (configuration) from DetectedLint (instance)
• Restructure ErrorReporter to generate lints
• Move parse-based-on-file logic into LintRule class
• Add Yaml parse utilities for converting to source spans

LintRule/CodeEdits:

• Merge LintRule and CodeEdit into one class
• Merge CodeEdit/LintRule bootstrappers
• Create new CodeCorrection class for defining source changes
• Switch includes globs to excludes

Visitor:

• SidecarVisitor

CodeEdit debugger

• Can we send cursor location info to the debugger?
• All source changes if CodeEdit is triggered (e.g. previousText: "foo", changedText: "bar")

• Sidecar runs directly from pub cache (no external package needed)
• Sidecar entrypoint should be created in .dart_tool directory
• Sidecar can run directly from a lint package (i.e. sidecar doesnt need to be a direct dev-dependency)
• Configuration is defined in sidecar.yaml rather than analysis_options.config (due to plugin shutdown when the latter is edited)
• Move Analysis Error reporting to a separate provider
• Fix sidecar.yaml generic configuration errors
• Fix CLI reporting
• Combine middleman_plugin and server into one entity

Lint / fixes should be responsible for declaring their own configurations, by declaring it when extending LintError or QuickFix .

• optional config parameters
• required config parameters (causes error to appear in analysis options file)

Currently LinterVisitor and NodeLintRegistry are copied outside of Analyzer package. There should be a desire to depend explicitly on analyzer package, to prevent issues arising from future analyzer package updates.

Similar to CLI scripts, a user could run any sequence of CodeEdits from the CLI (including prompts for missing arguments). This would work similarly to dart fix.

For example, users installing the intl and flutter_localizations packages will need to follow a series of steps in order to use generated translations. Instead of following a guide step-by-step, a user could instead run a command from the CLI that guides them through the install process.