add-dart-lint-validation-rule

Add a New Validation Rule and Flag

Use this skill when you need to add a new validation rule to the dart_skills_lint package, expose it as a toggleable CLI flag, and verify its behavior.

🛠️ Step-by-Step Implementation

1. Create the Rule Class

Create a new file in lib/src/rules/ extending SkillRule.

[!TIP] If your rule expects a specific structure in the skill's YAML frontmatter (e.g., inside metadata), document this structure clearly in the class Dart docstring.

// lib/src/rules/my_new_rule.dart
 
import '../models/analysis_severity.dart';
import '../models/skill_context.dart';
import '../models/skill_rule.dart';
import '../models/validation_error.dart';
 
class MyNewRule

Accessing YAML Frontmatter

If your rule needs configuration from the skill's YAML frontmatter, you can access it via context.parsedYaml.

2. Register the Rule in lib/src/rule_registry.dart

Add a new CheckType instance to RuleRegistry.allChecks list. This automatically exposes it as a CLI flag.

Then, add a case to RuleRegistry.createRule to instantiate your rule:

3. Handle Disabled by Default Rules (If applicable)

If the rule is disabled by default (defaultSeverity: AnalysisSeverity.disabled), passing the flag --check-my-new-rule will automatically enable it with AnalysisSeverity.error severity (handled in entry_point.dart).

🧪 Testing the New Rule

You must write automated tests verifying your rule triggers when it should and skips when it shouldn't.

Preferred Approach: In-Memory Unit Tests

Instead of writing files to disk, test the rule directly using a mock SkillContext. This is faster and avoids I/O dependencies.

Alternative Approach: File System Interaction

If the rule interacts with the file system or wraps an external CLI tool (like popmark), you should use a temporary directory for testing instead of in-memory mocks.

Integration Tests

If the rule interacts with CLI flags or configuration files, add a test in test/cli_integration_test.dart using TestProcess.

[!IMPORTANT] When writing integration tests that use config files and TestProcess, ensure that paths in the config file and paths passed to the CLI match in style (both relative or both absolute) to avoid issues with path matching in entry_point.dart.

📚 Documentation Updates

When a new rule is introduced, verify that you synchronize sibling markdown files!

1. README.md:
   • Add your flag under the Flags section (under Usage) so users know it exists.
   • CRITICAL FORMATTING: You MUST use the exact format - \--[no-]`: . (Disabled by default if applicable)`.
   • CRITICAL NAMING: Ensure the flag string matches the ruleName EXACTLY. For example, if the ruleName is file-existence, the flag MUST be documented as --[no-]file-existence (do NOT hallucinate a check- prefix like --[no-]check-file-existence). Do NOT add empty bullet points.
2. RULES.md:
   • Add a new entry for your rule documenting its default severity, fixability, what it checks, diagnostic shape, auto-fix behavior, and how to disable it. This is strictly required by the rules_md_consistency_test.dart test.
3. documentation/knowledge/SPECIFICATION.md:
   • Document the formal constraint in the specification if it defines a standard for skill files.

🚦 Checklist Before Submitting PR

• Rule class created in lib/src/rules/.
• Rule registered in lib/src/rule_registry.dart.
• Unit tests added in test/ using in-memory SkillContext.
• CRITICAL: Usage flag correctly documented in README.md under Flags (ensure flag string matches ruleName EXACTLY and format is correct).
• Rule documented in RULES.md.
• Schema documented in documentation/knowledge/SPECIFICATION.md (if applicable).
• Run dart format . to format code.
• Run dart analyze --fatal-infos to ensure no issues.
• Run dart test to ensure tests passing.