### Linter Rules Tooling Setup

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/CLAUDE.md

Installs dependencies for the linter rules tooling. Run from the tool/linter_rules directory.

```sh
cd tool/linter_rules
dart pub get

```

--------------------------------

### Example Rule Documentation URL

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/rules-reference.md

An example of how to access the documentation for a specific rule, 'prefer_const_constructors'.

```text
https://dart.dev/tools/linter-rules/prefer_const_constructors
```

--------------------------------

### Install Dependencies

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/CONTRIBUTING.md

Installs all project dependencies required for development and testing.

```bash
dart pub get
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/integration-guide.md

Steps to clone the Very Good Analysis repository and install its dependencies, including root, tool, and example Flutter dependencies. Navigate to the respective directories before running `dart pub get`.

```bash
# Clone the repo
git clone https://github.com/VeryGoodOpenSource/very_good_analysis.git
cd very_good_analysis

# Install root dependencies
dart pub get

# Install tool dependencies
cd tool/linter_rules
dart pub get

cd ../bump_version
dart pub get

cd ../..
cd example
flutter pub get

cd ..

```

--------------------------------

### Install Dependencies and Run Checks

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/CLAUDE.md

Install dependencies and perform formatting and static analysis checks. CI enforces these checks.

```sh
dart pub get

```

```sh
dart format --set-exit-if-changed lib example

```

```sh
dart analyze lib example

```

--------------------------------

### Example Configuration Consistency

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/configuration.md

Illustrates the consistency requirement between pubspec.yaml version, lib/analysis_options.yaml include, and the actual versioned file.

```text
pubspec.yaml:          version: 10.3.0
lib/analysis_options.yaml:  include: package:very_good_analysis/analysis_options.10.3.0.yaml
lib/analysis_options.10.3.0.yaml:  (must exist)
```

--------------------------------

### Bump Version Example

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/INDEX.md

Use the `bumpVersion` function to create a new versioned configuration file and update the main include. This example shows how to create a configuration file for version '10.4.0'.

```dart
bumpVersion('10.4.0');  // Creates lib/analysis_options.10.4.0.yaml
```

--------------------------------

### Static Analysis

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/overview.md

Perform static analysis on the lib and example directories using the configured lint rules.

```sh
dart analyze lib example
```

--------------------------------

### Install Tool Dependencies

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/overview.md

Install dependencies for the linter_rules tool package.

```sh
cd tool/linter_rules
dart pub get
```

--------------------------------

### Example success message from version verification

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/cli-tools.md

This message confirms that the version check passed, indicating that the `pubspec.yaml` version and the analysis configuration version are in sync.

```text
✅ Versions match: 10.3.0
```

--------------------------------

### Example Usage of LinterRulesReasons

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/types.md

Illustrates how to create and populate the LinterRulesReasons map with specific linter rules and their corresponding explanations.

```dart
const reasons = {
  'always_put_control_body_on_new_line': 'Can conflict with the Dart formatter',
  'avoid_classes_with_only_static_members': 'Not specified',
};
```

--------------------------------

### Conventional Commits Format Example

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/integration-guide.md

Illustrates the Conventional Commits format for commit messages, including types like `feat`, `fix`, `refactor`, etc., and provides examples for feature, fix, docs, and chore commits.

```bash
type: description

Optional detailed body explaining the why and how.

**Types**: `feat`, `fix`, `refactor`, `chore`, `docs`, `test`, `perf`, `ci`, `build`, `revert`

**Examples**:
```
feat: add three new linter rules for Dart 3.12
fix: remove deprecated rule from 10.3.0
docs: update configuration guide
chore: sync linter rules from upstream Dart SDK
```
```

--------------------------------

### Example Usage of ReadmeTag

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/types.md

Demonstrates creating a ReadmeTag tuple and using it to update content within a README file, likely for dynamic sections.

```dart
const myTag = ('<!-- start:section -->', '<!-- end:section -->');
await readme.updateTagContent(myTag, 'New section content');
```

--------------------------------

### Linter Rules Tooling Setup and Execution

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/AGENTS.md

Commands to set up dependencies and run various tools for maintaining linter rules. This includes regenerating exclusion tables, analyzing rules against Dart linters, and removing deprecated rules.

```sh
cd tool/linter_rules

```

```sh
dart pub get

```

```sh
dart lib/exclusion_reason_table.dart

```

```sh
dart bin/analyze.dart

```

```sh
dart bin/remove_deprecated_rules.dart

```

```sh
dart test

```

--------------------------------

### Example file changes after bumping version

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/cli-tools.md

Illustrates the state of analysis configuration files before and after running the `bump_version.dart` script, showing the updated include directive and the creation of a new versioned file.

```text
Before:
  lib/analysis_options.yaml
    → include: package:very_good_analysis/analysis_options.10.3.0.yaml
  lib/analysis_options.10.3.0.yaml (210 rules)
  lib/analysis_options.10.4.0.yaml (does not exist)

After:
  lib/analysis_options.yaml
    → include: package:very_good_analysis/analysis_options.10.4.0.yaml
  lib/analysis_options.10.3.0.yaml (210 rules - unchanged)
  lib/analysis_options.10.4.0.yaml (210 rules - copied from 10.3.0)
```

--------------------------------

### Example commands after bumping version

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/cli-tools.md

These commands show the next steps after running `bump_version.dart`: manually editing the new versioned YAML file and then regenerating the exclusion table.

```sh
# Edit to add/remove rules for the new version
vim lib/analysis_options.10.4.0.yaml

# Then regenerate the exclusion table
dart tool/linter_rules/lib/exclusion_reason_table.dart
```

--------------------------------

### Example of Automated Workflow

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/api-reference-bump-version.md

This snippet shows how `bumpVersion()` is called within an automated script to create a new minor version when removing deprecated linter rules.

```dart
// From tool/linter_rules/bin/remove_deprecated_rules.dart
final latestVersion = latestVgaVersion();
final parts = latestVersion.split('.');
final newVersion = '${parts[0]}.${int.parse(parts[1]) + 1}.0';
bumpVersion(newVersion, basePath: basePath);
```

--------------------------------

### Read Very Good Analysis configuration versions

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/integration-guide.md

Programmatically get the latest VGA version, read rules from a specific version, and compare rule sets between versions.

```dart
import 'package:linter_rules/linter_rules.dart';

void main() async {
  // Get the latest VGA version
  final version = latestVgaVersion();
  print('Latest version: $version');
  
  // Read rules from a specific version
  final rules = await allVeryGoodAnalysisRules(version: '10.3.0');
  print('VGA 10.3.0 has ${rules.length} rules');
  
  // Compare versions
  final v10_0 = (await allVeryGoodAnalysisRules(version: '10.0.0')).toSet();
  final v10_3 = (await allVeryGoodAnalysisRules(version: '10.3.0')).toSet();
  final added = v10_3.difference(v10_0);
  print('Added in 10.3.0: ${added.join(', ')}');
}
```

--------------------------------

### Example error messages from version verification

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/cli-tools.md

These messages indicate potential issues found during the version verification process, such as missing files, inability to parse versions, or a mismatch between the pubspec and configuration file versions.

```text
❌ pubspec.yaml not found.
❌ lib/analysis_options.yaml not found.
❌ Could not find a valid version in pubspec.yaml.
❌ lib/analysis_options.10.4.0.yaml not found.
❌ Could not find version in lib/analysis_options.yaml.
❌ Version mismatch:
- pubspec.yaml version: 10.4.0
- lib/analysis_options.yaml version: 10.3.0

Please update lib/analysis_options.yaml to match pubspec.yaml.
```

--------------------------------

### Example Workflow for Exclusion Table

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/cli-tools.md

A typical workflow involving version bumping, rule editing, and regenerating the exclusion table. Review changes using `git diff`.

```bash
# 1. Bump to a new version
dart tool/bump_version/lib/bump_version.dart 10.4.0

# 2. Edit lib/analysis_options.10.4.0.yaml to add/remove rules

# 3. Regenerate the exclusion table and reasons
dart tool/linter_rules/lib/exclusion_reason_table.dart

# 4. Review changes and commit
git diff README.md tool/linter_rules/exclusion_reasons.json
```

--------------------------------

### LinterRule fromJson Factory Constructor Example

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/types.md

Demonstrates how to deserialize a JSON object into a LinterRule instance using the `fromJson` factory constructor. Requires importing the linter_rules package.

```dart
import 'package:linter_rules/linter_rules.dart';

final json = {
  'name': 'prefer_const_constructors',
  'description': 'Prefer const constructors.',
  'details': 'DO use const constructors...',
  'categories': ['style'],
  'state': 'stable',
  'incompatible': [],
  'sets': ['core', 'recommended'],
  'fixStatus': 'hasFix',
  'sinceDartSdk': '2.1.0',
};

final rule = LinterRule.fromJson(json);
print('${rule.name}: ${rule.description}');
```

--------------------------------

### CI Integration for Deprecated Rules Check

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/cli-tools.md

Example of how to integrate the deprecated rules check into a GitHub Actions workflow to fail builds when deprecated rules are detected.

```yaml
# GitHub Actions example
- name: Check for deprecated linter rules
  run: dart tool/linter_rules/bin/analyze.dart --set-exit-if-changed
```

--------------------------------

### Format Code

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/overview.md

Check and format the code in the lib and example directories. The --set-exit-if-changed flag will cause the command to exit with a non-zero status code if any files were reformatted.

```sh
dart format --set-exit-if-changed lib example
```

--------------------------------

### Fetch All Available Linter Rules

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/api-reference-linter-rules.md

Retrieves all available linter rules, regardless of their state. Use this to get a comprehensive list.

```dart
// Fetch all available rules
final allRules = await allLinterRules();
```

--------------------------------

### Example output of remove_deprecated_rules.dart

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/cli-tools.md

This output shows the script's progress, including the number of rules fetched, the current and new versions, identified deprecated rules, and confirmation of file updates.

```text
Fetched 5 Dart deprecated linter rules

Latest Very Good Analysis version: 10.3.0

Fetched 210 Very Good Analysis linter rules

Found 1 deprecated Very Good Analysis rules:
  - avoid_null_checks_in_equality_operators

Updated the exclusion reasons file.

Bumped Very Good Analysis version to 10.4.0

Updated the README.md file with the excluded rules table.
```

--------------------------------

### Analyze Specific Version Rule Set

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/tool/linter_rules/README.md

Analyze a specific version of Very Good Analysis by providing the version number as an argument to the analyze script. For example, to analyze version 10.0.0.

```sh
dart bin/analyze.dart $version
```

--------------------------------

### Generate Exclusion Reason Table

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/tool/linter_rules/README.md

Run this command from `tool/linter_rules` to generate the exclusion reason table for rules not enabled by default. Ensure `dart pub get` has been run. The command updates the README table and `exclusion_reasons.json`.

```sh
dart lib/exclusion_reason_table.dart
```

--------------------------------

### Get Latest Very Good Analysis Version

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/api-reference-linter-rules.md

Retrieves the semantic version string of the latest Very Good Analysis configuration from the main analysis options file. This is useful for ensuring you are using the most up-to-date rules.

```dart
import 'package:linter_rules/linter_rules.dart';

final version = latestVgaVersion();
print('Latest VGA version: $version');
```

--------------------------------

### Automated Rule Removal and Version Update Workflow

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/integration-guide.md

A comprehensive script to identify deprecated Dart linter rules, find corresponding deprecated Very Good Analysis rules, bump the project version, update exclusion reasons, and regenerate the README table. Ensure necessary packages are installed.

```dart
import 'package:bump_version/bump_version.dart';
import 'package:linter_rules/linter_rules.dart';

Future<void> main() async {
  // Get all deprecated Dart linter rules
  final deprecatedRules = await allLinterRules(state: LinterRuleState.deprecated);
  print('Found ${deprecatedRules.length} deprecated Dart rules');
  
  // Get current VGA rules
  final version = latestVgaVersion();
  final vgaRules = (await allVeryGoodAnalysisRules(version: version)).toSet();
  
  // Find intersection
  final deprecatedVgaRules = deprecatedRules
      .where((r) => vgaRules.contains(r.name))
      .map((r) => r.name)
      .toList();
  
  if (deprecatedVgaRules.isEmpty) {
    print('No deprecated rules in VGA');
    return;
  }
  
  print('Found ${deprecatedVgaRules.length} deprecated rules in VGA:');
  for (final rule in deprecatedVgaRules) {
    print('  - $rule');
  }
  
  // Bump version
  final parts = version.split('.');
  final newVersion = '${parts[0]}.${int.parse(parts[1]) + 1}.0';
  bumpVersion(newVersion);
  print('Bumped to $newVersion');
  
  // Update exclusion reasons
  final reasons = await readExclusionReasons();
  for (final rule in deprecatedVgaRules) {
    reasons[rule] = 'Deprecated';
  }
  await writeExclusionReasons(reasons);
  
  // Regenerate README table
  final readme = Readme();
  final table = readme.generateExcludedRulesTable(
    reasons.keys,
    reasons,
  );
  await readme.updateTagContent(excludedRulesTableTag, '\n$table');
  
  print('Done!');
}
```

--------------------------------

### Excluded Rules Table Tags

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/api-reference-linter-rules.md

The start and end HTML comment tags delimiting the excluded rules section in README.md.

```dart
const excludedRulesTableTag = (
  '<!-- start:excluded_rules_table -->',
  '<!-- end:excluded_rules_table -->',
)
```

--------------------------------

### Generate New Version

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/CONTRIBUTING.md

Run this command to generate a new version file for analysis options. Choose the version according to Semantic Versioning guidelines.

```bash
dart tool/bump_version/lib/bump_version.dart <NEW_VERSION>
```

--------------------------------

### Run Dart tool to bump analysis options version

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/cli-tools.md

Execute this script from the project root, providing the target semantic version as an argument. It copies the current analysis options file to a new versioned file and updates the main include directive.

```sh
dart tool/bump_version/lib/bump_version.dart <new_version>
```

--------------------------------

### Local Development Configuration

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/configuration.md

Create a local analysis_options.yaml with relaxed rules for faster development iteration, while maintaining a strict version for CI.

```yaml
# Local (faster)
include: package:very_good_analysis/analysis_options.yaml

linter:
  rules:
    lines_longer_than_80_chars: false

# CI (strict - committed version)
# Same as above but without exceptions
```

--------------------------------

### Fetch Latest Rules Using Latest VGA Version

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/api-reference-linter-rules.md

Demonstrates how to use the `latestVgaVersion` function to dynamically fetch the linter rules for the most recent Very Good Analysis version. This ensures your analysis configuration is current.

```dart
// Use this version to fetch the latest rules
final rules = await allVeryGoodAnalysisRules(version: version);
```

--------------------------------

### ReadmeTag Type Alias

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/types.md

Defines a record (tuple) for storing start and end markdown tag delimiters. Used for updating specific sections within README files.

```dart
typedef ReadmeTag = (String, String)
```

--------------------------------

### Bump Version using CLI

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/api-reference-bump-version.md

Execute the bump_version script from the command line to update analysis options files. This is the standard method for version bumping.

```bash
dart tool/bump_version/lib/bump_version.dart 10.4.0
```

--------------------------------

### Run Code Formatting and Analysis Checks

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/integration-guide.md

Commands to perform code formatting checks and static analysis on the project. Ensure you are in the project's root directory before executing these commands.

```bash
# Format check
dart format --set-exit-if-changed lib example tool

# Analyze
dart analyze lib example

# Run linter_rules tests
cd tool/linter_rules
dart test

cd ../..

```

--------------------------------

### Update README Tag Content

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/api-reference-linter-rules.md

Replaces content within specified HTML comment tags in the README.md file. Ensure the start and end tags exist to avoid a StateError.

```dart
import 'package:linter_rules/linter_rules.dart';

final readme = Readme();
final tag = ('<!-- start:rules -->', '<!-- end:rules -->');
await readme.updateTagContent(tag, '
Updated rules list
');
```

--------------------------------

### GitHub Actions for analysis and formatting

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/integration-guide.md

CI workflow to analyze the project and check code formatting on push and pull requests.

```yaml
# .github/workflows/analyze.yml
name: Analyze
on: [push, pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: dart-lang/setup-dart@v1
        with:
          sdk: 3.12.0
      - run: dart pub get
      - run: dart analyze --fatal-infos
      - run: dart format --set-exit-if-changed .
```

--------------------------------

### Run Dart tool to verify pubspec and config versions

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/cli-tools.md

Execute this command to validate that the version in `pubspec.yaml` matches the version specified in the analysis options configuration. This is typically run in CI before publishing.

```sh
dart run tool/verify_version/main.dart
```

--------------------------------

### Analyze Latest Rule Set

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/tool/linter_rules/README.md

Use this script from `tool/linter_rules` to analyze the health of the latest rule set. It logs information about fetched, declared, and deprecated rules. Ensure `dart pub get` has been run.

```sh
# This will analyze the latest version of Very Good Analysis
dart bin/analyze.dart
```

--------------------------------

### Run Dart analysis

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/integration-guide.md

Execute the Dart analyzer to check the project for issues. Use `--fatal-infos` for CI.

```bash
# Analyze the project
dart analyze

# or with Flutter
flutter analyze

# or explicitly
dart analyze lib example
```

--------------------------------

### Very Good Analysis File Structure

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/INDEX.md

Overview of the directory structure for the very_good_analysis project, highlighting key files and directories for different components.

```plaintext
very_good_analysis/
├── lib/
│   ├── very_good_analysis.dart        (empty library export)
│   ├── analysis_options.yaml           (latest include directive)
│   └── analysis_options.*.yaml         (26 historical versions)
├── tool/
│   ├── linter_rules/
│   │   ├── lib/
│   │   │   ├── linter_rules.dart       (public export)
│   │   │   ├── src/                    (implementation)
│   │   │   └── exclusion_reason_table.dart (tool)
│   │   └── bin/
│   │       ├── analyze.dart            (deprecated rules check)
│   │       └── remove_deprecated_rules.dart (automation)
│   ├── bump_version/
│   │   └── lib/bump_version.dart       (public export)
│   └── verify_version/
│       └── main.dart                   (standalone tool)
├── example/                            (test package)
├── pubspec.yaml                        (package definition)
├── analysis_options.yaml               (self-application)
└── README.md                           (user documentation)
```

--------------------------------

### Bump Version Library Function

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/INDEX.md

Creates a new versioned configuration file and updates the main include file for version management.

```APIDOC
## Functions

### `bumpVersion(String version)`

**Description**: Create new versioned config file and update main include.

**Usage**:
```dart
bumpVersion('10.4.0');  // Creates lib/analysis_options.10.4.0.yaml
```
```

--------------------------------

### Remove Deprecated Rules

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/tool/linter_rules/README.md

Execute this script from `tool/linter_rules` to automatically handle deprecated linter rules. It fetches latest rules, identifies deprecated ones, removes them, creates a new minor version, and updates the exclusion table. Ensure `dart pub get` has been run.

```sh
dart bin/remove_deprecated_rules.dart
```

--------------------------------

### Analyze Deprecated Linter Rules

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/cli-tools.md

Compares Very Good Analysis against Dart linter rules to report deprecated ones. Use `--version` to specify a VGA version and `--set-exit-if-changed` to fail CI if deprecated rules are found.

```bash
# Analyze the latest version
dart tool/linter_rules/bin/analyze.dart
```

```bash
# Analyze a specific version
dart tool/linter_rules/bin/analyze.dart --version 10.0.0
```

```bash
# Exit with code 2 if deprecated rules are found
dart tool/linter_rules/bin/analyze.dart --set-exit-if-changed
```

```bash
# Combined
dart tool/linter_rules/bin/analyze.dart --version 10.0.0 --set-exit-if-changed
```

--------------------------------

### Include Very Good Analysis in analysis_options.yaml

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/README.md

Include the default analysis options from the very_good_analysis package to ensure the latest lints are used.

```yaml
include: package:very_good_analysis/analysis_options.yaml
```

--------------------------------

### Error Handling for File System Operations

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/api-reference-bump-version.md

Integrate `bumpVersion()` calls within a try-catch block to gracefully handle potential `FileSystemException` errors during file operations.

```dart
import 'package:bump_version/bump_version.dart';

try {
  bumpVersion('10.4.0');
  print('Version bumped successfully');
} on FileSystemException catch (e) {
  print('Error: Could not access files: ${e.message}');
} catch (e) {
  print('Unexpected error: $e');
}
```

--------------------------------

### Analysis Options YAML Structure

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/types.md

Shows the typical structure of an analysis_options.yaml file, including analyzer and linter configurations.

```yaml
analyzer:
  language:
    strict-casts: true
    strict-inference: true
    strict-raw-types: true
  errors:
    close_sinks: ignore
    missing_return: error

linter:
  rules:
    - prefer_const_constructors
    - always_declare_return_types
    # ... more rules ...

```

--------------------------------

### Run Tool Tests

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/overview.md

Execute the tests for the linter_rules tool package.

```sh
dart test
```

--------------------------------

### latestVgaVersion

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/api-reference-linter-rules.md

Extracts the current latest Very Good Analysis version from the main `lib/analysis_options.yaml` file. Optionally accepts a file path for testing.

```APIDOC
## latestVgaVersion()

### Description
Extracts the current latest Very Good Analysis version from the main `lib/analysis_options.yaml` file. Optionally accepts a file path for testing.

### Signature
```dart
String latestVgaVersion({@visibleForTesting String? filePath})
```

### Parameters
#### Query Parameters
- **filePath** (String?) - Optional - (Testing only) Override the path to the analysis_options.yaml file.

### Return Type
`String` — Semantic version string (format: `x.y.z`, e.g., `10.3.0`).

### Throws
- `ArgumentError` — Raised if the analysis options file does not exist or the version cannot be parsed from the file.

### Example
```dart
import 'package:linter_rules/linter_rules.dart';

final version = latestVgaVersion();
print('Latest VGA version: $version');

// Use this version to fetch the latest rules
final rules = await allVeryGoodAnalysisRules(version: version);
```
```

--------------------------------

### Linter Rules Tool Unit Tests

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/CLAUDE.md

Runs unit tests for the linter rules tooling. Run from the tool/linter_rules directory.

```sh
dart test

```

--------------------------------

### Verify Version Script

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/CLAUDE.md

Checks if the pubspec.yaml version matches the version included in lib/analysis_options.yaml. Fails if versions do not match or if the specified versioned YAML file does not exist.

```sh
dart run tool/verify_version/main.dart

```

--------------------------------

### Linter Rules Configuration

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/configuration.md

Enables a comprehensive set of linter rules for style, error prevention, performance, and documentation. Rules are listed alphabetically.

```yaml
linter:
  rules:
    - always_declare_return_types
    - always_put_required_named_parameters_first
    - always_use_package_imports
    - annotate_overrides
    # ... 206 more rules ...
    - void_checks
```

--------------------------------

### Compare Very Good Analysis Rules Between Versions

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/api-reference-linter-rules.md

Compares the linter rules enabled by two different versions of Very Good Analysis to identify added or removed rules. This helps in understanding changes between VGA releases.

```dart
// Compare against another version
final v9Rules = await allVeryGoodAnalysisRules(version: '9.0.0');
final v10Rules = await allVeryGoodAnalysisRules(version: '10.0.0');

final newRules = v10Rules.toSet().difference(v9Rules.toSet());
print('Added in 10.0.0: ${newRules.join(', ')}');
```

--------------------------------

### Generate Exclusion Reason Table

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/cli-tools.md

Updates the README.md with a table of excluded linter rules and their reasons. Use `--version` to specify a VGA version and `--set-exit-if-changed` to fail CI if changes are detected.

```bash
dart tool/linter_rules/lib/exclusion_reason_table.dart
```

```bash
dart tool/linter_rules/lib/exclusion_reason_table.dart --version 10.0.0
```

```bash
dart tool/linter_rules/lib/exclusion_reason_table.dart --set-exit-if-changed
```

--------------------------------

### Official Rule Documentation URL

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/rules-reference.md

This is the base URL structure for accessing detailed explanations of linter rules. Replace `{rule_name}` with the specific rule identifier.

```text
https://dart.dev/tools/linter-rules/{rule_name}
```

--------------------------------

### Generate Markdown table for linter rules

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/integration-guide.md

Create a Markdown table from a list of linter rule data, useful for documentation generation.

```dart
import 'package:linter_rules/linter_rules.dart';

void main() {
  // Generate a markdown table
  final markdown = generateMarkdownTable([
    ['Rule', 'State', 'Category'],
    ['prefer_const_constructors', 'stable', 'style'],
    ['always_declare_return_types', 'stable', 'typing'],
  ]);
  
  print(markdown);
}
```

--------------------------------

### Format Code

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/CONTRIBUTING.md

Formats all Dart code in the current directory and its subdirectories according to standard Dart formatting.

```bash
dart format .
```

--------------------------------

### Analyze VGA Against Dart Linter Rules

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/overview.md

Compare Very Good Analysis (VGA) rules against all available Dart linter rules. Optionally specify a version and use --set-exit-if-changed to fail if differences are found.

```sh
# Analyze VGA against all Dart linter rules
dart bin/analyze.dart [version] [--set-exit-if-changed]
```

--------------------------------

### bumpVersion()

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/api-reference-bump-version.md

Bumps the version of analysis options files by copying the latest versioned YAML to a new version and updating the main include directive.

```APIDOC
## bumpVersion()

### Description
Bumps the version of analysis options files by copying the latest versioned YAML to a new version and updating the main include directive.

### Method
Dart Function

### Signature
`void bumpVersion(String newVersion, {String basePath = ''})`

### Parameters
#### Path Parameters
- **newVersion** (String) - Required - New semantic version in format `x.y.z` (e.g., `10.4.0`).
- **basePath** (String) - Optional - Base directory path for file operations. Set to non-empty to operate on a copy (used in testing). Default: `''`.

### Return Type
`void` — Performs file I/O operations with no return value.

### Throws
No throws documented. File system errors propagate as exceptions.

### Behavior
1. Reads `lib/analysis_options.yaml` to extract the current latest version
2. Copies `lib/analysis_options.{currentVersion}.yaml` to `lib/analysis_options.{newVersion}.yaml`
3. Updates `lib/analysis_options.yaml` to include the new version file

### Example
```dart
import 'package:bump_version/bump_version.dart';

// Bump from 10.3.0 to 10.4.0
bumpVersion('10.4.0');

// Result:
// - Creates lib/analysis_options.10.4.0.yaml (copy of 10.3.0)
// - Updates lib/analysis_options.yaml to:
//   include: package:very_good_analysis/analysis_options.10.4.0.yaml
```

### CLI Usage
From the project root:

```sh
dart tool/bump_version/lib/bump_version.dart 10.4.0
```

### Source
`tool/bump_version/lib/bump_version.dart:37-58`
```

--------------------------------

### GitHub Actions Workflow for Version Verification

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/cli-tools.md

This YAML snippet configures a GitHub Actions workflow to run a Dart script that verifies version consistency. It's intended to be placed in `.github/workflows/verify_version.yaml`.

```yaml
# .github/workflows/verify_version.yaml
- name: Verify version consistency
  run: dart run tool/verify_version/main.dart
```

--------------------------------

### Local pre-commit hook for analysis and formatting

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/integration-guide.md

Bash script for a Git pre-commit hook to ensure code analysis and formatting before committing.

```bash
# .git/hooks/pre-commit

echo "Running analysis..."
dart analyze --fatal-infos lib test || exit 1

echo "Checking format..."
dart format --set-exit-if-changed . || exit 1

exit 0
```

--------------------------------

### Fetch All Stable Linter Rules

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/api-reference-linter-rules.md

Fetches all currently available stable linter rules from the Dart SDK. Useful for understanding the current linting landscape.

```dart
import 'package:linter_rules/linter_rules.dart';

// Fetch all stable linter rules
final stableRules = await allLinterRules(state: LinterRuleState.stable);
print('Found ${stableRules.length} stable rules');
```

--------------------------------

### Generate Linter Rule Link

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/api-reference-linter-rules.md

Helper function returning documentation URL for a rule. Used by `Readme.generateExcludedRulesTable()`.

```dart
String linterRuleLink(String rule) =>
    'https://dart.dev/tools/linter-rules/$rule'
```

--------------------------------

### Fetch all stable Dart linter rules programmatically

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/integration-guide.md

Use the `linter_rules` package to fetch all stable linter rules and print their names and descriptions.

```dart
import 'package:linter_rules/linter_rules.dart';

void main() async {
  // Fetch all stable rules
  final stableRules = await allLinterRules(state: LinterRuleState.stable);
  for (final rule in stableRules) {
    print('${rule.name}: ${rule.description}');
  }
  
  // Fetch deprecated rules
  final deprecated = await allLinterRules(state: LinterRuleState.deprecated);
  print('Deprecated: ${deprecated.map((r) => r.name).join(', ')}');
}
```

--------------------------------

### Manage exclusion reasons for linter rules

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/integration-guide.md

Read, modify, and write exclusion reasons for linter rules programmatically. Reasons are written back in alphabetical order.

```dart
import 'package:linter_rules/linter_rules.dart';

void main() async {
  // Read existing reasons
  final reasons = await readExclusionReasons();
  
  // Modify
  reasons['new_rule'] = 'Not evaluated yet';
  
  // Write back (alphabetically sorted)
  await writeExclusionReasons(reasons);
}
```

--------------------------------

### Project-Specific Configuration Overrides

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/configuration.md

Extends the default Very Good Analysis configuration with project-specific settings. Allows overriding exclusions or disabling specific linter rules.

```yaml
# In a project's analysis_options.yaml
include: package:very_good_analysis/analysis_options.yaml

analyzer:
  exclude:
    - build/**
    - generated/**

linter:
  rules:
    - prefer_const_constructors: false  # Disable specific rule
```

--------------------------------

### Project-specific overrides for analysis_options.yaml

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/integration-guide.md

Extend the base configuration with project-specific overrides for analyzer exclusions and linter rules.

```yaml
include: package:very_good_analysis/analysis_options.yaml

analyzer:
  exclude:
    - build/**
    - .dart_tool/**
    - generated/**

linter:
  rules:
    # Disable rules not suitable for this project
    - public_member_api_docs: false
    - lines_longer_than_80_chars: false
    - avoid_print: false  # Allow print for CLI tools
```

--------------------------------

### Include Specific Version of Very Good Analysis

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/README.md

If you wish to restrict the lint version, specify a version of analysis_options.yaml instead.

```yaml
include: package:very_good_analysis/analysis_options.10.0.0.yaml
```

--------------------------------

### Linter Rules Tooling Commands

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/CLAUDE.md

Commands to manage linter rules, including regenerating the exclusion table, analyzing against Dart linter rules, and removing deprecated rules. Run from the tool/linter_rules directory.

```sh
dart lib/exclusion_reason_table.dart

```

```sh
dart bin/analyze.dart

```

```sh
dart bin/remove_deprecated_rules.dart

```

--------------------------------

### Linter Rules Library Functions

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/INDEX.md

Provides functions to fetch and manage Dart linter rules, including retrieving all rules, enabled rules for a specific VGA version, and generating markdown tables.

```APIDOC
## Functions

### `allLinterRules()`

**Description**: Fetch all available Dart linter rules.

### `allVeryGoodAnalysisRules()`

**Description**: Read enabled rules from a VGA version.

### `latestVgaVersion()`

**Description**: Get the current latest version number.

### `generateMarkdownTable()`

**Description**: Convert data rows to markdown table.

### `readExclusionReasons()`

**Description**: Load rule exclusion reasons from JSON.

### `writeExclusionReasons()`

**Description**: Persist rule exclusion reasons to JSON.
```

--------------------------------

### allVeryGoodAnalysisRules

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/api-reference-linter-rules.md

Reads all linter rules currently enabled by a specific Very Good Analysis version from its YAML configuration file. Requires a version string and optionally accepts a file path for testing.

```APIDOC
## allVeryGoodAnalysisRules()

### Description
Reads all linter rules currently enabled by a specific Very Good Analysis version from its YAML configuration file. Requires a version string and optionally accepts a file path for testing.

### Signature
```dart
Future<Iterable<String>> allVeryGoodAnalysisRules({
  required String version,
  @visibleForTesting String? filePath,
})
```

### Parameters
#### Query Parameters
- **version** (String) - Required - Semantic version of VGA config to read (format: `x.y.z`, e.g., `10.0.0`).
- **filePath** (String?) - Optional - (Testing only) Override the directory path containing analysis options YAML files.

### Return Type
`Future<Iterable<String>>` — Asynchronous iterable of rule name strings.

### Throws
- `ArgumentError` — Raised if the version file does not exist at the expected path.

### Example
```dart
import 'package:linter_rules/linter_rules.dart';

// Read rules from VGA version 10.0.0
final rules = await allVeryGoodAnalysisRules(version: '10.0.0');
print('VGA 10.0.0 enables ${rules.length} rules');

// Compare against another version
final v9Rules = await allVeryGoodAnalysisRules(version: '9.0.0');
final v10Rules = await allVeryGoodAnalysisRules(version: '10.0.0');

final newRules = v10Rules.toSet().difference(v9Rules.toSet());
print('Added in 10.0.0: ${newRules.join(', ')}');
```
```

--------------------------------

### Pin Very Good Analysis to a Specific Version

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/overview.md

Optionally, pin the analysis options to a specific version of the very_good_analysis package by referencing its versioned YAML file.

```yaml
include: package:very_good_analysis/analysis_options.10.3.0.yaml
```

--------------------------------

### Integration with Overrides

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/configuration.md

Extend the default analysis options by adding custom analyzer and linter rules or exclusions in your project's analysis_options.yaml.

```yaml
include: package:very_good_analysis/analysis_options.yaml

analyzer:
  exclude:
    - build/**
    - ".g.dart"
    - ".freezed.dart"

linter:
  rules:
    - public_member_api_docs: false
    - lines_longer_than_80_chars: false
```

--------------------------------

### Automatically Remove Deprecated Rules and Bump Version

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/overview.md

Automatically remove deprecated lint rules from the configuration and bump the package version.

```sh
# Automatically remove deprecated rules and bump version
dart bin/remove_deprecated_rules.dart
```

--------------------------------

### Bump Version

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/overview.md

Bump the version of the very_good_analysis package. This command creates a new versioned YAML configuration file and updates the main analysis_options.yaml to include it.

```sh
dart tool/bump_version/lib/bump_version.dart <x.y.z>
```

--------------------------------

### generateMarkdownTable

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/api-reference-linter-rules.md

Converts a two-dimensional list of strings into a markdown table. The first row is treated as headers, and subsequent rows as data. Requires all inner lists to have equal length.

```APIDOC
## generateMarkdownTable()

### Description
Converts a two-dimensional list of strings into a markdown table. The first row is treated as headers, and subsequent rows as data. Requires all inner lists to have equal length.

### Signature
```dart
String generateMarkdownTable(List<List<String>> rows)
```

### Parameters
#### Path Parameters
- **rows** (List<List<String>>) - Required - 2D list where first row is headers, subsequent rows are data. Each inner list must have equal length.

### Return Type
`String` — Formatted markdown table with header separator row.

### Throws
- No throws documented. Behavior on unequal row lengths is undefined.
```

--------------------------------

### Generate Markdown Table from Data

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/api-reference-linter-rules.md

Converts a 2D list of strings into a formatted markdown table. This is useful for generating documentation or reports.

```dart
String generateMarkdownTable(List<List<String>> rows)
```

--------------------------------

### Bump Version Script

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/CLAUDE.md

Copies the latest versioned YAML to a new version and updates the main analysis options file. Requires the new version number as an argument.

```sh
dart tool/bump_version/lib/bump_version.dart <x.y.z>

```

--------------------------------

### Generate Markdown Table of Linter Rules

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/api-reference-linter-rules.md

Generates a markdown table from a list of linter rule data. Useful for displaying rule information in documentation.

```dart
import 'package:linter_rules/linter_rules.dart';

final markdown = generateMarkdownTable([
  ['Rule', 'State', 'Fix Status'],
  ['prefer_const_constructors', 'stable', 'hasFix'],
  ['public_member_api_docs', 'stable', 'noFix'],
]);

print(markdown);
// Output:
// | Rule | State | Fix Status |
// | --- | --- | --- |
// | prefer_const_constructors | stable | hasFix |
// | public_member_api_docs | stable | noFix |
```

--------------------------------

### Bump Project Version

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/integration-guide.md

Updates the project's version number. This script copies the current analysis options file to a new versioned file and updates the main analysis options file to point to the new version.

```dart
import 'package:bump_version/bump_version.dart';

void main() {
  // Create new version 10.4.0
  bumpVersion('10.4.0');
  
  // This:
  // 1. Copies lib/analysis_options.10.3.0.yaml to lib/analysis_options.10.4.0.yaml
  // 2. Updates lib/analysis_options.yaml to point to 10.4.0.yaml
}
```

--------------------------------

### Exclusion Reasons JSON Format

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/types.md

Illustrates the JSON format used for storing linter rule exclusion reasons, mapping rule names to explanations.

```json
{
  "always_put_control_body_on_new_line": "Can conflict with the Dart formatter",
  "avoid_classes_with_only_static_members": "Not specified",
  ...
}
```

--------------------------------

### writeExclusionReasons

Source: https://github.com/verygoodopensource/very_good_analysis/blob/main/_autodocs/api-reference-linter-rules.md

Writes exclusion reasons to a JSON file, sorted by rule name for readability. Accepts a map of rule names to exclusion reasons.

```APIDOC
## writeExclusionReasons()

### Description
Writes exclusion reasons to a JSON file, sorted by rule name for readability.

### Signature
```dart
Future<void> writeExclusionReasons(LinterRulesReasons reasons)
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `reasons` | `LinterRulesReasons` | Yes | — | Map of rule name to exclusion reason to persist. |

### Return Type
`Future<void>` — Completes when file write is done.

### Throws
- No throws documented. File I/O errors propagate as exceptions.

### Example
```dart
import 'package:linter_rules/linter_rules.dart';

final reasonsToWrite = {
  'always_put_control_body_on_new_line': 'Can conflict with the Dart formatter',
  'avoid_classes_with_only_static_members': 'Not specified',
};

await writeExclusionReasons(reasonsToWrite);
```
```