@herb-tools/linter 0.4.0

package/dist/types/rules/rule-utils.d.ts

@@ -0,0 +1,89 @@
+import { Visitor } from "@herb-tools/core";
+import type { HTMLAttributeNode, HTMLOpenTagNode, HTMLSelfCloseTagNode, Location } from "@herb-tools/core";
+import type { LintOffense, LintSeverity } from "../types.js";
+/**
+ * Base visitor class that provides common functionality for rule visitors
+ */
+export declare abstract class BaseRuleVisitor extends Visitor {
+    readonly offenses: LintOffense[];
+    protected ruleName: string;
+    constructor(ruleName: string);
+    /**
+     * Helper method to create a lint offense
+     */
+    protected createOffense(message: string, location: Location, severity?: LintSeverity): LintOffense;
+    /**
+     * Helper method to add an offense to the offenses array
+     */
+    protected addOffense(message: string, location: Location, severity?: LintSeverity): void;
+}
+/**
+ * Gets attributes from either an HTMLOpenTagNode or HTMLSelfCloseTagNode
+ */
+export declare function getAttributes(node: HTMLOpenTagNode | HTMLSelfCloseTagNode): any[];
+/**
+ * Gets the tag name from an HTML tag node (lowercased)
+ */
+export declare function getTagName(node: HTMLOpenTagNode | HTMLSelfCloseTagNode): string | null;
+/**
+ * Gets the attribute name from an HTMLAttributeNode (lowercased)
+ */
+export declare function getAttributeName(attributeNode: HTMLAttributeNode): string | null;
+/**
+ * Gets the attribute value content from an HTMLAttributeValueNode
+ */
+export declare function getAttributeValue(attributeNode: HTMLAttributeNode): string | null;
+/**
+ * Checks if an attribute has a value
+ */
+export declare function hasAttributeValue(attributeNode: HTMLAttributeNode): boolean;
+/**
+ * Gets the quote type used for an attribute value
+ */
+export declare function getAttributeValueQuoteType(attributeNode: HTMLAttributeNode): "single" | "double" | "none" | null;
+/**
+ * Finds an attribute by name in a list of attributes
+ */
+export declare function findAttributeByName(attributes: any[], attributeName: string): HTMLAttributeNode | null;
+/**
+ * Checks if a tag has a specific attribute
+ */
+export declare function hasAttribute(node: HTMLOpenTagNode | HTMLSelfCloseTagNode, attributeName: string): boolean;
+/**
+ * Common HTML element categorization
+ */
+export declare const HTML_INLINE_ELEMENTS: Set<string>;
+export declare const HTML_BLOCK_ELEMENTS: Set<string>;
+export declare const HTML_BOOLEAN_ATTRIBUTES: Set<string>;
+export declare const HEADING_TAGS: Set<string>;
+/**
+ * Checks if an element is inline
+ */
+export declare function isInlineElement(tagName: string): boolean;
+/**
+ * Checks if an element is block-level
+ */
+export declare function isBlockElement(tagName: string): boolean;
+/**
+ * Checks if an attribute is a boolean attribute
+ */
+export declare function isBooleanAttribute(attributeName: string): boolean;
+/**
+ * Abstract base class for rules that need to check individual attributes on HTML tags
+ * Eliminates duplication of visitHTMLOpenTagNode/visitHTMLSelfCloseTagNode patterns
+ * and attribute iteration logic. Provides simplified interface with extracted attribute info.
+ */
+export declare abstract class AttributeVisitorMixin extends BaseRuleVisitor {
+    visitHTMLOpenTagNode(node: HTMLOpenTagNode): void;
+    visitHTMLSelfCloseTagNode(node: HTMLSelfCloseTagNode): void;
+    private checkAttributesOnNode;
+    protected abstract checkAttribute(attributeName: string, attributeValue: string | null, attributeNode: HTMLAttributeNode, parentNode: HTMLOpenTagNode | HTMLSelfCloseTagNode): void;
+}
+/**
+ * Checks if an attribute value is quoted
+ */
+export declare function isAttributeValueQuoted(attributeNode: HTMLAttributeNode): boolean;
+/**
+ * Iterates over all attributes of a tag node, calling the callback for each attribute
+ */
+export declare function forEachAttribute(node: HTMLOpenTagNode | HTMLSelfCloseTagNode, callback: (attributeNode: HTMLAttributeNode) => void): void;

package/dist/types/src/cli/argument-parser.d.ts

@@ -0,0 +1,14 @@
+import type { ThemeInput } from "@herb-tools/highlighter";
+export interface ParsedArguments {
+    pattern: string;
+    formatOption: 'simple' | 'detailed';
+    showTiming: boolean;
+    theme: ThemeInput;
+    wrapLines: boolean;
+    truncateLines: boolean;
+}
+export declare class ArgumentParser {
+    private readonly usage;
+    parse(argv: string[]): ParsedArguments;
+    private getFilePattern;
+}

package/dist/types/src/cli/file-processor.d.ts

@@ -0,0 +1,21 @@
+import type { Diagnostic } from "@herb-tools/core";
+export interface ProcessedFile {
+    filename: string;
+    diagnostic: Diagnostic;
+    content: string;
+}
+export interface ProcessingResult {
+    totalErrors: number;
+    totalWarnings: number;
+    filesWithIssues: number;
+    ruleCount: number;
+    allDiagnostics: ProcessedFile[];
+    ruleViolations: Map<string, {
+        count: number;
+        files: Set<string>;
+    }>;
+}
+export declare class FileProcessor {
+    private linter;
+    processFiles(files: string[]): Promise<ProcessingResult>;
+}

package/dist/types/src/cli/formatters/base-formatter.d.ts

@@ -0,0 +1,6 @@
+import type { Diagnostic } from "@herb-tools/core";
+import type { ProcessedFile } from "../file-processor.js";
+export declare abstract class BaseFormatter {
+    abstract format(allDiagnostics: ProcessedFile[], isSingleFile?: boolean): Promise<void>;
+    abstract formatFile(filename: string, diagnostics: Diagnostic[]): void;
+}

package/dist/types/src/cli/formatters/detailed-formatter.d.ts

@@ -0,0 +1,13 @@
+import { type ThemeInput } from "@herb-tools/highlighter";
+import { BaseFormatter } from "./base-formatter.js";
+import type { Diagnostic } from "@herb-tools/core";
+import type { ProcessedFile } from "../file-processor.js";
+export declare class DetailedFormatter extends BaseFormatter {
+    private highlighter;
+    private theme;
+    private wrapLines;
+    private truncateLines;
+    constructor(theme?: ThemeInput, wrapLines?: boolean, truncateLines?: boolean);
+    format(allDiagnostics: ProcessedFile[], isSingleFile?: boolean): Promise<void>;
+    formatFile(_filename: string, _diagnostics: Diagnostic[]): void;
+}

package/dist/types/src/cli/formatters/index.d.ts

@@ -0,0 +1,3 @@
+export { BaseFormatter } from "./base-formatter.js";
+export { SimpleFormatter } from "./simple-formatter.js";
+export { DetailedFormatter } from "./detailed-formatter.js";

package/dist/types/src/cli/formatters/simple-formatter.d.ts

@@ -0,0 +1,7 @@
+import { BaseFormatter } from "./base-formatter.js";
+import type { Diagnostic } from "@herb-tools/core";
+import type { ProcessedFile } from "../file-processor.js";
+export declare class SimpleFormatter extends BaseFormatter {
+    format(allDiagnostics: ProcessedFile[]): Promise<void>;
+    formatFile(filename: string, diagnostics: Diagnostic[]): void;
+}

package/dist/types/src/cli/index.d.ts

@@ -0,0 +1,4 @@
+export { ArgumentParser } from "./argument-parser.js";
+export { FileProcessor } from "./file-processor.js";
+export { SummaryReporter } from "./summary-reporter.js";
+export * from "./formatters/index.js";

package/dist/types/src/cli/summary-reporter.d.ts

@@ -0,0 +1,22 @@
+export interface SummaryData {
+    files: string[];
+    totalErrors: number;
+    totalWarnings: number;
+    filesWithViolations: number;
+    ruleCount: number;
+    startTime: number;
+    startDate: Date;
+    showTiming: boolean;
+    ruleViolations: Map<string, {
+        count: number;
+        files: Set<string>;
+    }>;
+}
+export declare class SummaryReporter {
+    private pluralize;
+    displaySummary(data: SummaryData): void;
+    displayMostViolatedRules(ruleViolations: Map<string, {
+        count: number;
+        files: Set<string>;
+    }>, limit?: number): void;
+}

package/dist/types/src/cli.d.ts

@@ -0,0 +1,6 @@
+export declare class CLI {
+    private argumentParser;
+    private fileProcessor;
+    private summaryReporter;
+    run(): Promise<void>;
+}

package/dist/types/src/default-rules.d.ts

@@ -0,0 +1,2 @@
+import type { RuleClass } from "./types.js";
+export declare const defaultRules: RuleClass[];

package/dist/types/src/herb-lint.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/types/src/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./linter.js";
+export * from "./rules/index.js";
+export * from "./types.js";

package/dist/types/src/linter.d.ts

@@ -0,0 +1,18 @@
+import type { RuleClass, LintResult } from "./types.js";
+import type { DocumentNode } from "@herb-tools/core";
+export declare class Linter {
+    private rules;
+    private offenses;
+    /**
+     * Creates a new Linter instance.
+     * @param rules - Array of rule classes (not instances) to use. If not provided, uses default rules.
+     */
+    constructor(rules?: RuleClass[]);
+    /**
+     * Returns the default set of rule classes used by the linter.
+     * @returns Array of rule classes
+     */
+    private getDefaultRules;
+    getRuleCount(): number;
+    lint(document: DocumentNode): LintResult;
+}

package/dist/types/src/rules/erb-no-empty-tags.d.ts

@@ -0,0 +1,6 @@
+import type { Rule, LintOffense } from "../types.js";
+import type { Node } from "@herb-tools/core";
+export declare class ERBNoEmptyTagsRule implements Rule {
+    name: string;
+    check(node: Node): LintOffense[];
+}

package/dist/types/src/rules/erb-no-output-control-flow.d.ts

@@ -0,0 +1,6 @@
+import type { Node } from "@herb-tools/core";
+import type { Rule, LintOffense } from "../types.js";
+export declare class ERBNoOutputControlFlowRule implements Rule {
+    name: string;
+    check(node: Node): LintOffense[];
+}

package/dist/types/src/rules/erb-require-whitespace-inside-tags.d.ts

@@ -0,0 +1,6 @@
+import type { Node } from "@herb-tools/core";
+import type { LintOffense, Rule } from "../types.js";
+export declare class ERBRequireWhitespaceRule implements Rule {
+    name: string;
+    check(node: Node): LintOffense[];
+}

package/dist/types/src/rules/html-anchor-require-href.d.ts

@@ -0,0 +1,6 @@
+import { Rule, LintOffense } from "../types.js";
+import type { Node } from "@herb-tools/core";
+export declare class HTMLAnchorRequireHrefRule implements Rule {
+    name: string;
+    check(node: Node): LintOffense[];
+}

package/dist/types/src/rules/html-aria-role-heading-requires-level.d.ts

@@ -0,0 +1,6 @@
+import type { Rule, LintOffense } from "../types.js";
+import type { Node } from "@herb-tools/core";
+export declare class HTMLAriaRoleHeadingRequiresLevelRule implements Rule {
+    name: string;
+    check(node: Node): LintOffense[];
+}

package/dist/types/src/rules/html-attribute-double-quotes.d.ts

@@ -0,0 +1,6 @@
+import type { Rule, LintOffense } from "../types.js";
+import type { Node } from "@herb-tools/core";
+export declare class HTMLAttributeDoubleQuotesRule implements Rule {
+    name: string;
+    check(node: Node): LintOffense[];
+}

package/dist/types/src/rules/html-attribute-values-require-quotes.d.ts

@@ -0,0 +1,6 @@
+import type { Rule, LintOffense } from "../types.js";
+import type { Node } from "@herb-tools/core";
+export declare class HTMLAttributeValuesRequireQuotesRule implements Rule {
+    name: string;
+    check(node: Node): LintOffense[];
+}

package/dist/types/src/rules/html-boolean-attributes-no-value.d.ts

@@ -0,0 +1,6 @@
+import type { Rule, LintOffense } from "../types.js";
+import type { Node } from "@herb-tools/core";
+export declare class HTMLBooleanAttributesNoValueRule implements Rule {
+    name: string;
+    check(node: Node): LintOffense[];
+}

package/dist/types/src/rules/html-img-require-alt.d.ts

@@ -0,0 +1,6 @@
+import type { Rule, LintOffense } from "../types.js";
+import type { Node } from "@herb-tools/core";
+export declare class HTMLImgRequireAltRule implements Rule {
+    name: string;
+    check(node: Node): LintOffense[];
+}

package/dist/types/src/rules/html-no-block-inside-inline.d.ts

@@ -0,0 +1,6 @@
+import type { Rule, LintOffense } from "../types.js";
+import type { Node } from "@herb-tools/core";
+export declare class HTMLNoBlockInsideInlineRule implements Rule {
+    name: string;
+    check(node: Node): LintOffense[];
+}

package/dist/types/src/rules/html-no-duplicate-attributes.d.ts

@@ -0,0 +1,6 @@
+import type { Rule, LintOffense } from "../types.js";
+import type { Node } from "@herb-tools/core";
+export declare class HTMLNoDuplicateAttributesRule implements Rule {
+    name: string;
+    check(node: Node): LintOffense[];
+}

package/dist/types/src/rules/html-no-empty-headings.d.ts

@@ -0,0 +1,6 @@
+import type { Rule, LintOffense } from "../types.js";
+import type { Node } from "@herb-tools/core";
+export declare class HTMLNoEmptyHeadingsRule implements Rule {
+    name: string;
+    check(node: Node): LintOffense[];
+}

package/dist/types/src/rules/html-no-nested-links.d.ts

@@ -0,0 +1,6 @@
+import type { Rule, LintOffense } from "../types.js";
+import type { Node } from "@herb-tools/core";
+export declare class HTMLNoNestedLinksRule implements Rule {
+    name: string;
+    check(node: Node): LintOffense[];
+}

package/dist/types/src/rules/html-tag-name-lowercase.d.ts

@@ -0,0 +1,6 @@
+import type { Rule, LintOffense } from "../types.js";
+import type { Node } from "@herb-tools/core";
+export declare class HTMLTagNameLowercaseRule implements Rule {
+    name: string;
+    check(node: Node): LintOffense[];
+}

package/dist/types/src/rules/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./erb-no-empty-tags.js";
+export * from "./erb-no-output-control-flow.js";
+export * from "./html-anchor-require-href.js";
+export * from "./html-attribute-double-quotes.js";
+export * from "./html-attribute-values-require-quotes.js";
+export * from "./html-boolean-attributes-no-value.js";
+export * from "./html-img-require-alt.js";
+export * from "./html-no-block-inside-inline.js";
+export * from "./html-no-duplicate-attributes.js";
+export * from "./html-no-empty-headings.js";
+export * from "./html-no-nested-links.js";
+export * from "./html-tag-name-lowercase.js";

package/dist/types/src/rules/rule-utils.d.ts

@@ -0,0 +1,89 @@
+import { Visitor } from "@herb-tools/core";
+import type { HTMLAttributeNode, HTMLOpenTagNode, HTMLSelfCloseTagNode, Location } from "@herb-tools/core";
+import type { LintOffense, LintSeverity } from "../types.js";
+/**
+ * Base visitor class that provides common functionality for rule visitors
+ */
+export declare abstract class BaseRuleVisitor extends Visitor {
+    readonly offenses: LintOffense[];
+    protected ruleName: string;
+    constructor(ruleName: string);
+    /**
+     * Helper method to create a lint offense
+     */
+    protected createOffense(message: string, location: Location, severity?: LintSeverity): LintOffense;
+    /**
+     * Helper method to add an offense to the offenses array
+     */
+    protected addOffense(message: string, location: Location, severity?: LintSeverity): void;
+}
+/**
+ * Gets attributes from either an HTMLOpenTagNode or HTMLSelfCloseTagNode
+ */
+export declare function getAttributes(node: HTMLOpenTagNode | HTMLSelfCloseTagNode): any[];
+/**
+ * Gets the tag name from an HTML tag node (lowercased)
+ */
+export declare function getTagName(node: HTMLOpenTagNode | HTMLSelfCloseTagNode): string | null;
+/**
+ * Gets the attribute name from an HTMLAttributeNode (lowercased)
+ */
+export declare function getAttributeName(attributeNode: HTMLAttributeNode): string | null;
+/**
+ * Gets the attribute value content from an HTMLAttributeValueNode
+ */
+export declare function getAttributeValue(attributeNode: HTMLAttributeNode): string | null;
+/**
+ * Checks if an attribute has a value
+ */
+export declare function hasAttributeValue(attributeNode: HTMLAttributeNode): boolean;
+/**
+ * Gets the quote type used for an attribute value
+ */
+export declare function getAttributeValueQuoteType(attributeNode: HTMLAttributeNode): "single" | "double" | "none" | null;
+/**
+ * Finds an attribute by name in a list of attributes
+ */
+export declare function findAttributeByName(attributes: any[], attributeName: string): HTMLAttributeNode | null;
+/**
+ * Checks if a tag has a specific attribute
+ */
+export declare function hasAttribute(node: HTMLOpenTagNode | HTMLSelfCloseTagNode, attributeName: string): boolean;
+/**
+ * Common HTML element categorization
+ */
+export declare const HTML_INLINE_ELEMENTS: Set<string>;
+export declare const HTML_BLOCK_ELEMENTS: Set<string>;
+export declare const HTML_BOOLEAN_ATTRIBUTES: Set<string>;
+export declare const HEADING_TAGS: Set<string>;
+/**
+ * Checks if an element is inline
+ */
+export declare function isInlineElement(tagName: string): boolean;
+/**
+ * Checks if an element is block-level
+ */
+export declare function isBlockElement(tagName: string): boolean;
+/**
+ * Checks if an attribute is a boolean attribute
+ */
+export declare function isBooleanAttribute(attributeName: string): boolean;
+/**
+ * Abstract base class for rules that need to check individual attributes on HTML tags
+ * Eliminates duplication of visitHTMLOpenTagNode/visitHTMLSelfCloseTagNode patterns
+ * and attribute iteration logic. Provides simplified interface with extracted attribute info.
+ */
+export declare abstract class AttributeVisitorMixin extends BaseRuleVisitor {
+    visitHTMLOpenTagNode(node: HTMLOpenTagNode): void;
+    visitHTMLSelfCloseTagNode(node: HTMLSelfCloseTagNode): void;
+    private checkAttributesOnNode;
+    protected abstract checkAttribute(attributeName: string, attributeValue: string | null, attributeNode: HTMLAttributeNode, parentNode: HTMLOpenTagNode | HTMLSelfCloseTagNode): void;
+}
+/**
+ * Checks if an attribute value is quoted
+ */
+export declare function isAttributeValueQuoted(attributeNode: HTMLAttributeNode): boolean;
+/**
+ * Iterates over all attributes of a tag node, calling the callback for each attribute
+ */
+export declare function forEachAttribute(node: HTMLOpenTagNode | HTMLSelfCloseTagNode, callback: (attributeNode: HTMLAttributeNode) => void): void;

package/dist/types/src/types.d.ts

@@ -0,0 +1,26 @@
+import { Node, Diagnostic } from "@herb-tools/core";
+import type { defaultRules } from "./default-rules.js";
+export type LintSeverity = "error" | "warning";
+/**
+ * Automatically inferred union type of all available linter rule names.
+ * This type extracts the 'name' property from each rule class instance.
+ */
+export type LinterRule = InstanceType<typeof defaultRules[number]>['name'];
+export interface LintOffense extends Diagnostic {
+    rule: LinterRule;
+    severity: LintSeverity;
+}
+export interface LintResult {
+    offenses: LintOffense[];
+    errors: number;
+    warnings: number;
+}
+export interface Rule {
+    name: string;
+    check(node: Node): LintOffense[];
+}
+/**
+ * Type representing a rule class constructor.
+ * The Linter accepts rule classes rather than instances for better performance and memory usage.
+ */
+export type RuleClass = new () => Rule;

package/dist/types/types.d.ts

@@ -0,0 +1,26 @@
+import { Node, Diagnostic } from "@herb-tools/core";
+import type { defaultRules } from "./default-rules.js";
+export type LintSeverity = "error" | "warning";
+/**
+ * Automatically inferred union type of all available linter rule names.
+ * This type extracts the 'name' property from each rule class instance.
+ */
+export type LinterRule = InstanceType<typeof defaultRules[number]>['name'];
+export interface LintOffense extends Diagnostic {
+    rule: LinterRule;
+    severity: LintSeverity;
+}
+export interface LintResult {
+    offenses: LintOffense[];
+    errors: number;
+    warnings: number;
+}
+export interface Rule {
+    name: string;
+    check(node: Node): LintOffense[];
+}
+/**
+ * Type representing a rule class constructor.
+ * The Linter accepts rule classes rather than instances for better performance and memory usage.
+ */
+export type RuleClass = new () => Rule;

package/docs/rules/README.md

@@ -0,0 +1,39 @@
+# Linter Rules
+
+This page contains documentation for all Herb Linter rules.
+
+## Available Rules
+
+- [`erb-no-empty-tags`](./erb-no-empty-tags.md) - Disallow empty ERB tags
+- [`erb-no-output-control-flow`](./erb-no-output-control-flow.md) - Prevents outputting control flow blocks
+- [`erb-require-whitespace-inside-tags`](./erb-require-whitespace-inside-tags.md) - Requires whitespace around erb tags
+- [`html-aria-role-heading-requires-level`](./html-aria-role-heading-requires-level.md) - Requires `aria-level` when supplying a `role`
+- [`html-attribute-double-quotes`](./html-attribute-double-quotes.md) - Enforces double quotes for attribute values
+- [`html-attribute-values-require-quotes`](./html-attribute-values-require-quotes.md) - Requires quotes around attribute values
+- [`html-boolean-attributes-no-value`](./html-boolean-attributes-no-value.md) - Prevents values on boolean attributes
+- [`html-img-require-alt`](./html-img-require-alt.md) - Requires alt attributes on img tags
+- [`html-no-block-inside-inline`](./html-no-block-inside-inline.md) - Prevents block-level elements inside inline elements
+- [`html-no-duplicate-attributes`](./html-no-duplicate-attributes.md) - Prevents duplicate attributes on HTML elements
+- [`html-no-nested-links`](./html-no-nested-links.md) - Prevents nested anchor tags
+- [`html-tag-name-lowercase`](./html-tag-name-lowercase.md) - Enforces lowercase tag names in HTML
+
+## Contributing
+
+To add a new linter rule you can scaffold a new rule by running:
+
+```bash
+cd javascript/packages/linter
+
+scripts/generate-rule
+```
+
+The script creates the documentation, rule stub, and test stub based on the GitHub issue (requires the `linter` label and a `Rule name: [rule-name]` line).
+
+Alternatively, you can create one manually:
+
+1. Create the rule class implementing the `Rule` interface
+2. Add comprehensive tests in `test/rules/`
+3. Add documentation in `docs/rules/`
+4. Update the main linter to include the rule by default (if appropriate)
+
+See [`html-tag-name-lowercase.ts`](https://github.com/marcoroth/herb/blob/main/javascript/packages/linter/src/rules/html-tag-name-lowercase.ts) for an example implementation.

package/docs/rules/erb-no-empty-tags.md

@@ -0,0 +1,38 @@
+# Linter Rule: Disallow empty ERB tags
+
+**Rule:** `erb-no-empty-tags`
+
+## Description
+
+Disallow ERB tags (`<% %>` or `<%= %>`) that contain no meaningful content i.e., tags that are completely empty or contain only whitespace.
+
+## Rationale
+
+Empty ERB tags serve no purpose and may confuse readers or indicate incomplete code. They clutter the template and may have been left behind accidentally after editing.
+
+## Examples
+
+### ✅ Good
+
+```html
+<%= user.name %>
+
+<% if user.admin? %>
+  Admin tools
+<% end %>
+```
+
+### 🚫 Bad
+
+```erb
+<% %>
+
+<%=  %>
+
+<%
+%>
+```
+
+## References
+
+\-

package/docs/rules/erb-no-output-control-flow.md

@@ -0,0 +1,45 @@
+# Linter Rule: Disallow output ERB tags with control flow
+
+**Rule:** `erb-no-output-control-flow`
+
+## Description
+
+Disallow using output ERB tags (`<%=`) for control flow statements like `if`, `unless`, `case`, `while`, etc. Control flow should be written with regular ERB tags (`<% ... %>`), since these do not produce output directly.
+
+## Rationale
+
+Using `<%=` with control flow is typically a mistake or misunderstanding of ERB behavior. Output tags (`<%=`) are designed to render values into the HTML output, while control flow statements only affect execution and do not produce a value to render. This misuse can result in unexpected output, unnecessary blank spaces, or subtle bugs.
+
+Reporting this as a warning can help developers catch likely mistakes while allowing flexibility for rare advanced cases.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<% if condition %>
+  Content here
+<% end %>
+```
+
+```erb
+<%= user.name %>
+```
+
+### 🚫 Bad
+
+```erb
+<%= if condition %>
+  Content here
+<% end %>
+```
+
+```erb
+<%= unless user.nil? %>
+  Welcome!
+<% end %>
+```
+
+## References
+
+* [Inspiration](https://x.com/specialcasedev/status/1935013470069719231)