@herb-tools/linter 0.6.1 → 0.7.0

package/dist/types/linter.d.ts

@@ -1,9 +1,9 @@
-import type { RuleClass, LintResult, LintContext } from "./types.js";
+import type { RuleClass, Rule, LexerRule, SourceRule, LintResult, LintOffense, LintContext } from "./types.js";
 import type { HerbBackend } from "@herb-tools/core";
 export declare class Linter {
-    private rules;
-    private herb;
-    private offenses;
+    protected rules: RuleClass[];
+    protected herb: HerbBackend;
+    protected offenses: LintOffense[];
     /**
      * Creates a new Linter instance.
      * @param herb - The Herb backend instance for parsing and lexing
@@ -14,16 +14,16 @@ export declare class Linter {
      * Returns the default set of rule classes used by the linter.
      * @returns Array of rule classes
      */
-    private getDefaultRules;
+    protected getDefaultRules(): RuleClass[];
     getRuleCount(): number;
     /**
      * Type guard to check if a rule is a LexerRule
      */
-    private isLexerRule;
+    protected isLexerRule(rule: Rule): rule is LexerRule;
     /**
      * Type guard to check if a rule is a SourceRule
      */
-    private isSourceRule;
+    protected isSourceRule(rule: Rule): rule is SourceRule;
     /**
      * Lint source code using Parser/AST, Lexer, and Source rules.
      * @param source - The source code to lint

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

@@ -0,0 +1,7 @@
+import { ParserRule } from "../types.js";
+import type { LintOffense, LintContext } from "../types.js";
+import type { ParseResult } from "@herb-tools/core";
+export declare class HTMLNoEmptyAttributesRule extends ParserRule {
+    name: string;
+    check(result: ParseResult, context?: Partial<LintContext>): LintOffense[];
+}

package/dist/types/rules/html-no-underscores-in-attribute-names.d.ts

@@ -0,0 +1,7 @@
+import { ParserRule } from "../types.js";
+import type { LintContext, LintOffense } from "../types.js";
+import type { ParseResult } from "@herb-tools/core";
+export declare class HTMLNoUnderscoresInAttributeNamesRule extends ParserRule {
+    name: string;
+    check(result: ParseResult, context?: Partial<LintContext>): LintOffense[];
+}

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

@@ -1,3 +1,4 @@
+export * from "./rule-utils.js";
 export * from "./erb-no-empty-tags.js";
 export * from "./erb-no-output-control-flow.js";
 export * from "./erb-no-silent-tag-in-attribute-name.js";
@@ -20,6 +21,7 @@ export * from "./html-no-aria-hidden-on-focusable.js";
 export * from "./html-no-block-inside-inline.js";
 export * from "./html-no-duplicate-attributes.js";
 export * from "./html-no-duplicate-ids.js";
+export * from "./html-no-empty-attributes.js";
 export * from "./html-no-empty-headings.js";
 export * from "./html-no-nested-links.js";
 export * from "./html-no-positive-tab-index.js";
@@ -27,3 +29,4 @@ export * from "./html-no-self-closing.js";
 export * from "./html-no-title-attribute.js";
 export * from "./html-tag-name-lowercase.js";
 export * from "./svg-tag-name-capitalization.js";
+export * from "./html-no-underscores-in-attribute-names.js";

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

@@ -69,7 +69,7 @@ export declare function getTagName(node: HTMLOpenTagNode): string | null;
  * Gets the attribute name from an HTMLAttributeNode (lowercased)
  * Returns null if the attribute name contains dynamic content (ERB)
  */
-export declare function getAttributeName(attributeNode: HTMLAttributeNode): string | null;
+export declare function getAttributeName(attributeNode: HTMLAttributeNode, lowercase?: boolean): string | null;
 /**
  * Checks if an attribute has a dynamic (ERB-containing) name
  */
@@ -153,12 +153,14 @@ export interface StaticAttributeStaticValueParams {
     attributeName: string;
     attributeValue: string;
     attributeNode: HTMLAttributeNode;
+    originalAttributeName: string;
     parentNode: HTMLOpenTagNode;
 }
 export interface StaticAttributeDynamicValueParams {
     attributeName: string;
     valueNodes: Node[];
     attributeNode: HTMLAttributeNode;
+    originalAttributeName: string;
     parentNode: HTMLOpenTagNode;
     combinedValue?: string | null;
 }
@@ -215,19 +217,19 @@ export declare abstract class AttributeVisitorMixin extends BaseRuleVisitor {
     /**
      * Static attribute name with static value: class="container"
      */
-    protected checkStaticAttributeStaticValue(params: StaticAttributeStaticValueParams): void;
+    protected checkStaticAttributeStaticValue(_params: StaticAttributeStaticValueParams): void;
     /**
      * Static attribute name with dynamic value: class="<%= css_class %>"
      */
-    protected checkStaticAttributeDynamicValue(params: StaticAttributeDynamicValueParams): void;
+    protected checkStaticAttributeDynamicValue(_params: StaticAttributeDynamicValueParams): void;
     /**
      * Dynamic attribute name with static value: data-<%= key %>="foo"
      */
-    protected checkDynamicAttributeStaticValue(params: DynamicAttributeStaticValueParams): void;
+    protected checkDynamicAttributeStaticValue(_params: DynamicAttributeStaticValueParams): void;
     /**
      * Dynamic attribute name with dynamic value: data-<%= key %>="<%= value %>"
      */
-    protected checkDynamicAttributeDynamicValue(params: DynamicAttributeDynamicValueParams): void;
+    protected checkDynamicAttributeDynamicValue(_params: DynamicAttributeDynamicValueParams): void;
 }
 /**
  * Checks if an attribute value is quoted

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

@@ -1,5 +1,5 @@
 import type { ThemeInput } from "@herb-tools/highlighter";
-export type FormatOption = "simple" | "detailed" | "json" | "github";
+export type FormatOption = "simple" | "detailed" | "json";
 export interface ParsedArguments {
     pattern: string;
     formatOption: FormatOption;
@@ -7,6 +7,7 @@ export interface ParsedArguments {
     theme: ThemeInput;
     wrapLines: boolean;
     truncateLines: boolean;
+    useGitHubActions: boolean;
 }
 export declare class ArgumentParser {
     private readonly usage;

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

@@ -5,6 +5,10 @@ export interface ProcessedFile {
     offense: Diagnostic;
     content: string;
 }
+export interface ProcessingContext {
+    projectPath?: string;
+    pattern?: string;
+}
 export interface ProcessingResult {
     totalErrors: number;
     totalWarnings: number;
@@ -15,8 +19,9 @@ export interface ProcessingResult {
         count: number;
         files: Set<string>;
     }>;
+    context?: ProcessingContext;
 }
 export declare class FileProcessor {
     private linter;
-    processFiles(files: string[], formatOption?: FormatOption): Promise<ProcessingResult>;
+    processFiles(files: string[], formatOption?: FormatOption, context?: ProcessingContext): Promise<ProcessingResult>;
 }

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

@@ -2,9 +2,14 @@ import { BaseFormatter } from "./base-formatter.js";
 import type { Diagnostic } from "@herb-tools/core";
 import type { ProcessedFile } from "../file-processor.js";
 export declare class GitHubActionsFormatter extends BaseFormatter {
+    private highlighter;
+    private wrapLines;
+    private truncateLines;
+    constructor(wrapLines?: boolean, truncateLines?: boolean);
     private static readonly MESSAGE_ESCAPE_MAP;
     private static readonly PARAM_ESCAPE_MAP;
-    format(allDiagnostics: ProcessedFile[]): Promise<void>;
+    format(allDiagnostics: ProcessedFile[], _isSingleFile?: boolean): Promise<void>;
+    formatAnnotations(allDiagnostics: ProcessedFile[]): Promise<void>;
     formatFile(filename: string, diagnostics: Diagnostic[]): void;
     private formatDiagnostic;
     private escapeMessage;

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

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

package/dist/types/src/cli/output-manager.d.ts

@@ -7,6 +7,7 @@ interface OutputOptions {
     wrapLines: boolean;
     truncateLines: boolean;
     showTiming: boolean;
+    useGitHubActions: boolean;
     startTime: number;
     startDate: Date;
 }

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

@@ -1,8 +1,23 @@
+import { ArgumentParser, type FormatOption } from "./cli/argument-parser.js";
+import { FileProcessor } from "./cli/file-processor.js";
+import { OutputManager } from "./cli/output-manager.js";
+export * from "./cli/index.js";
 export declare class CLI {
-    private argumentParser;
-    private fileProcessor;
-    private outputManager;
-    private exitWithError;
-    private exitWithInfo;
+    protected argumentParser: ArgumentParser;
+    protected fileProcessor: FileProcessor;
+    protected outputManager: OutputManager;
+    protected projectPath: string;
+    getProjectPath(): string;
+    protected findProjectRoot(startPath: string): string;
+    protected exitWithError(message: string, formatOption: FormatOption, exitCode?: number): void;
+    protected exitWithInfo(message: string, formatOption: FormatOption, exitCode?: number, timingData?: {
+        startTime: number;
+        startDate: Date;
+        showTiming: boolean;
+    }): void;
+    protected determineProjectPath(pattern: string | undefined): void;
+    protected adjustPattern(pattern: string | undefined): string;
+    protected beforeProcess(): Promise<void>;
+    protected afterProcess(_results: any, _outputOptions: any): Promise<void>;
     run(): Promise<void>;
 }

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

@@ -1,9 +1,9 @@
-import type { RuleClass, LintResult, LintContext } from "./types.js";
+import type { RuleClass, Rule, LexerRule, SourceRule, LintResult, LintOffense, LintContext } from "./types.js";
 import type { HerbBackend } from "@herb-tools/core";
 export declare class Linter {
-    private rules;
-    private herb;
-    private offenses;
+    protected rules: RuleClass[];
+    protected herb: HerbBackend;
+    protected offenses: LintOffense[];
     /**
      * Creates a new Linter instance.
      * @param herb - The Herb backend instance for parsing and lexing
@@ -14,16 +14,16 @@ export declare class Linter {
      * Returns the default set of rule classes used by the linter.
      * @returns Array of rule classes
      */
-    private getDefaultRules;
+    protected getDefaultRules(): RuleClass[];
     getRuleCount(): number;
     /**
      * Type guard to check if a rule is a LexerRule
      */
-    private isLexerRule;
+    protected isLexerRule(rule: Rule): rule is LexerRule;
     /**
      * Type guard to check if a rule is a SourceRule
      */
-    private isSourceRule;
+    protected isSourceRule(rule: Rule): rule is SourceRule;
     /**
      * Lint source code using Parser/AST, Lexer, and Source rules.
      * @param source - The source code to lint

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

@@ -0,0 +1,7 @@
+import { ParserRule } from "../types.js";
+import type { LintOffense, LintContext } from "../types.js";
+import type { ParseResult } from "@herb-tools/core";
+export declare class HTMLNoEmptyAttributesRule extends ParserRule {
+    name: string;
+    check(result: ParseResult, context?: Partial<LintContext>): LintOffense[];
+}

package/dist/types/src/rules/html-no-underscores-in-attribute-names.d.ts

@@ -0,0 +1,7 @@
+import { ParserRule } from "../types.js";
+import type { LintContext, LintOffense } from "../types.js";
+import type { ParseResult } from "@herb-tools/core";
+export declare class HTMLNoUnderscoresInAttributeNamesRule extends ParserRule {
+    name: string;
+    check(result: ParseResult, context?: Partial<LintContext>): LintOffense[];
+}

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

@@ -1,3 +1,4 @@
+export * from "./rule-utils.js";
 export * from "./erb-no-empty-tags.js";
 export * from "./erb-no-output-control-flow.js";
 export * from "./erb-no-silent-tag-in-attribute-name.js";
@@ -20,6 +21,7 @@ export * from "./html-no-aria-hidden-on-focusable.js";
 export * from "./html-no-block-inside-inline.js";
 export * from "./html-no-duplicate-attributes.js";
 export * from "./html-no-duplicate-ids.js";
+export * from "./html-no-empty-attributes.js";
 export * from "./html-no-empty-headings.js";
 export * from "./html-no-nested-links.js";
 export * from "./html-no-positive-tab-index.js";
@@ -27,3 +29,4 @@ export * from "./html-no-self-closing.js";
 export * from "./html-no-title-attribute.js";
 export * from "./html-tag-name-lowercase.js";
 export * from "./svg-tag-name-capitalization.js";
+export * from "./html-no-underscores-in-attribute-names.js";

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

@@ -69,7 +69,7 @@ export declare function getTagName(node: HTMLOpenTagNode): string | null;
  * Gets the attribute name from an HTMLAttributeNode (lowercased)
  * Returns null if the attribute name contains dynamic content (ERB)
  */
-export declare function getAttributeName(attributeNode: HTMLAttributeNode): string | null;
+export declare function getAttributeName(attributeNode: HTMLAttributeNode, lowercase?: boolean): string | null;
 /**
  * Checks if an attribute has a dynamic (ERB-containing) name
  */
@@ -153,12 +153,14 @@ export interface StaticAttributeStaticValueParams {
     attributeName: string;
     attributeValue: string;
     attributeNode: HTMLAttributeNode;
+    originalAttributeName: string;
     parentNode: HTMLOpenTagNode;
 }
 export interface StaticAttributeDynamicValueParams {
     attributeName: string;
     valueNodes: Node[];
     attributeNode: HTMLAttributeNode;
+    originalAttributeName: string;
     parentNode: HTMLOpenTagNode;
     combinedValue?: string | null;
 }
@@ -215,19 +217,19 @@ export declare abstract class AttributeVisitorMixin extends BaseRuleVisitor {
     /**
      * Static attribute name with static value: class="container"
      */
-    protected checkStaticAttributeStaticValue(params: StaticAttributeStaticValueParams): void;
+    protected checkStaticAttributeStaticValue(_params: StaticAttributeStaticValueParams): void;
     /**
      * Static attribute name with dynamic value: class="<%= css_class %>"
      */
-    protected checkStaticAttributeDynamicValue(params: StaticAttributeDynamicValueParams): void;
+    protected checkStaticAttributeDynamicValue(_params: StaticAttributeDynamicValueParams): void;
     /**
      * Dynamic attribute name with static value: data-<%= key %>="foo"
      */
-    protected checkDynamicAttributeStaticValue(params: DynamicAttributeStaticValueParams): void;
+    protected checkDynamicAttributeStaticValue(_params: DynamicAttributeStaticValueParams): void;
     /**
      * Dynamic attribute name with dynamic value: data-<%= key %>="<%= value %>"
      */
-    protected checkDynamicAttributeDynamicValue(params: DynamicAttributeDynamicValueParams): void;
+    protected checkDynamicAttributeDynamicValue(_params: DynamicAttributeDynamicValueParams): void;
 }
 /**
  * Checks if an attribute value is quoted

package/docs/rules/README.md

@@ -28,11 +28,13 @@ This page contains documentation for all Herb Linter rules.
 - [`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-duplicate-ids`](./html-no-duplicate-ids.md) - Prevents duplicate IDs within a document
+- [`html-no-empty-attributes`](./html-no-empty-attributes.md) - Attributes must not have empty values
 - [`html-no-nested-links`](./html-no-nested-links.md) - Prevents nested anchor tags
 - [`html-no-positive-tab-index`](./html-no-positive-tab-index.md) - Avoid positive `tabindex` values
 - [`html-no-self-closing`](./html-no-self-closing.md.md) - Disallow self closing tags
 - [`html-no-title-attribute`](./html-no-title-attribute.md) - Avoid using the `title` attribute
 - [`html-tag-name-lowercase`](./html-tag-name-lowercase.md) - Enforces lowercase tag names in HTML
+- [`html-no-underscores-in-attribute-names`](./html-no-underscores-in-attribute-names.md) - Disallow underscores in HTML attribute names
 - [`parser-no-errors`](./parser-no-errors.md) - Disallow parser errors in HTML+ERB documents
 - [`svg-tag-name-capitalization`](./svg-tag-name-capitalization.md) - Enforces proper camelCase capitalization for SVG elements
 

package/docs/rules/html-img-require-alt.md

@@ -33,8 +33,6 @@ Omitting the `alt` attribute entirely leads to poor accessibility and can negati
 
 <img src="/avatar.jpg" alt> <!-- TODO -->
 
-<img src="/divider.png" alt=> <!-- TODO -->
-
 <%= image_tag image_path("logo.png") %> <!-- TODO -->
 ```
 

package/docs/rules/html-no-empty-attributes.md

@@ -0,0 +1,77 @@
+# Linter Rule: Attributes must not have empty values
+
+**Rule:** `html-no-empty-attributes`
+
+## Description
+
+Warn when certain restricted attributes are present but have an empty string as their value. These attributes are required to have meaningful values to function properly, and leaving them empty is typically either a mistake or unnecessary.
+
+In most cases, if the value is not available, it's better to omit the attribute entirely.
+
+### Restricted attributes
+
+- `id`
+- `class`
+- `name`
+- `for`
+- `src`
+- `href`
+- `title`
+- `data`
+- `role`
+- `data-*`
+- `aria-*`
+
+## Rationale
+
+Many HTML attributes are only useful when they carry a value. Leaving these attributes empty can:
+
+- Produce confusing or misleading markup (e.g., `id=""`, `class=""`)
+- Create inaccessible or invalid HTML
+- Interfere with CSS or JS selectors expecting meaningful values
+- Indicate unused or unfinished logic in ERB
+
+This rule helps ensure that required attributes are only added when they are populated.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<div id="header"></div>
+<img src="/logo.png" alt="Company logo">
+<input type="text" name="email">
+
+<!-- Dynamic attributes with meaningful values -->
+<div data-<%= key %>="<%= value %>" aria-<%= prop %>="<%= description %>">
+  Dynamic content
+</div>
+
+<!-- if no class should be set, omit it completely -->
+<div>Plain div</div>
+```
+
+### 🚫 Bad
+
+```erb
+<div id=""></div>
+<img src="">
+<input name="">
+
+<div data-config="">Content</div>
+<button aria-label="">×</button>
+
+<div class="">Plain div</div>
+
+<!-- Dynamic attribute names with empty static values -->
+<div data-<%= key %>="" aria-<%= prop %>="   ">
+  Problematic dynamic attributes
+</div>
+```
+
+## References
+
+- [HTML Living Standard - Global attributes](https://html.spec.whatwg.org/multipage/dom.html#global-attributes)
+- [WCAG 2.2 - Text Alternatives](https://www.w3.org/WAI/WCAG22/Understanding/text-alternatives.html)
+- [MDN - HTML attribute reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes)
+- [ARIA in HTML](https://www.w3.org/TR/html-aria/)

package/docs/rules/html-no-underscores-in-attribute-names.md

@@ -0,0 +1,45 @@
+# Linter Rule: No underscores on attribute names
+
+**Rule:** `html-no-underscores-in-attribute-names`
+
+## Description
+
+---
+
+Warn when an HTML attribute name contains an underscore (`_`). According to the HTML specification, attribute names should use only lowercase letters, digits, hyphens (`-`), and colons (`:`) in specific namespaces (e.g., `xlink:href` in SVG). Underscores are not valid in standard HTML attribute names and may lead to unpredictable behavior or be ignored by browsers entirely.
+
+## Rationale
+
+---
+
+Underscores in attribute names violate the HTML specification and are not supported in standard markup. Their use is almost always accidental (e.g., mistyping `data-attr_name` instead of `data-attr-name`) or stems from inconsistent naming conventions across backend or templating layers.
+
+## Examples
+
+---
+
+✅ Good
+
+```html
+<div data-user-id="123"></div>
+
+<img aria-label="Close">
+
+<div data-<%= key %>-attribute="value"></div>
+```
+
+🚫 Bad
+
+```html
+<div data_user_id="123"></div>
+
+<img aria_label="Close">
+
+<div data-<%= key %>_attribute="value"></div>
+```
+
+## References
+
+---
+
+\-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herb-tools/linter",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "HTML+ERB linter for validating HTML structure and enforcing best practices",
   "license": "MIT",
   "homepage": "https://herb-tools.dev",
@@ -21,6 +21,7 @@
     "build": "yarn clean && tsc -b && rollup -c",
     "watch": "tsc -b -w",
     "test": "vitest run",
+    "test:watch": "vitest --watch",
     "prepublishOnly": "yarn clean && yarn build && yarn test"
   },
   "exports": {
@@ -30,13 +31,18 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs",
       "default": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./dist/types/src/cli.d.ts",
+      "require": "./dist/src/cli.js",
+      "default": "./dist/src/cli.js"
     }
   },
   "dependencies": {
-    "@herb-tools/core": "0.6.1",
-    "@herb-tools/highlighter": "0.6.1",
-    "@herb-tools/node-wasm": "0.6.1",
-    "@herb-tools/printer": "0.6.1",
+    "@herb-tools/core": "0.7.0",
+    "@herb-tools/highlighter": "0.7.0",
+    "@herb-tools/node-wasm": "0.7.0",
+    "@herb-tools/printer": "0.7.0",
     "glob": "^11.0.3"
   },
   "files": [

package/src/cli/argument-parser.ts

@@ -11,7 +11,7 @@ import type { ThemeInput } from "@herb-tools/highlighter"
 
 import { name, version } from "../../package.json"
 
-export type FormatOption = "simple" | "detailed" | "json" | "github"
+export type FormatOption = "simple" | "detailed" | "json"
 
 export interface ParsedArguments {
   pattern: string
@@ -20,6 +20,7 @@ export interface ParsedArguments {
   theme: ThemeInput
   wrapLines: boolean
   truncateLines: boolean
+  useGitHubActions: boolean
 }
 
 export class ArgumentParser {
@@ -34,10 +35,11 @@ export class ArgumentParser {
     Options:
       -h, --help       show help
       -v, --version    show version
-      --format         output format (simple|detailed|json|github) [default: detailed]
+      --format         output format (simple|detailed|json) [default: detailed]
       --simple         use simple output format (shortcut for --format simple)
       --json           use JSON output format (shortcut for --format json)
-      --github         use GitHub Actions output format (shortcut for --format github)
+      --github         enable GitHub Actions annotations (combines with --format)
+      --no-github      disable GitHub Actions annotations (even in GitHub Actions environment)
       --theme          syntax highlighting theme (${THEME_NAMES.join("|")}) or path to custom theme file [default: ${DEFAULT_THEME}]
       --no-color       disable colored output
       --no-timing      hide timing information
@@ -55,6 +57,7 @@ export class ArgumentParser {
         simple: { type: "boolean" },
         json: { type: "boolean" },
         github: { type: "boolean" },
+        "no-github": { type: "boolean" },
         theme: { type: "string" },
         "no-color": { type: "boolean" },
         "no-timing": { type: "boolean" },
@@ -75,8 +78,10 @@ export class ArgumentParser {
       process.exit(0)
     }
 
+    const isGitHubActions = process.env.GITHUB_ACTIONS === "true"
+
     let formatOption: FormatOption = "detailed"
-    if (values.format && (values.format === "detailed" || values.format === "simple" || values.format === "json" || values.format === "github")) {
+    if (values.format && (values.format === "detailed" || values.format === "simple" || values.format === "json")) {
       formatOption = values.format
     }
 
@@ -88,8 +93,11 @@ export class ArgumentParser {
       formatOption = "json"
     }
 
-    if (values.github) {
-      formatOption = "github"
+    const useGitHubActions = (values.github || isGitHubActions) && !values["no-github"]
+
+    if (useGitHubActions && formatOption === "json") {
+      console.error("Error: --github cannot be used with --json format. JSON format is already structured for programmatic consumption.")
+      process.exit(1)
     }
 
     if (values["no-color"]) {
@@ -114,7 +122,7 @@ export class ArgumentParser {
     const theme = values.theme || DEFAULT_THEME
     const pattern = this.getFilePattern(positionals)
 
-    return { pattern, formatOption, showTiming, theme, wrapLines, truncateLines }
+    return { pattern, formatOption, showTiming, theme, wrapLines, truncateLines, useGitHubActions }
   }
 
   private getFilePattern(positionals: string[]): string {