feat: improve llm support and auto discover

- add semantic release
- update dependencies

Author: ph1p

.github/workflows/release.yml

@@ -2,26 +2,36 @@ name: Release
 
 on:
   push:
-    tags:
-      - "v*"
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: release
+  cancel-in-progress: false
 
 jobs:
   release:
-    name: Release
+    name: Semantic Release
     runs-on: ubuntu-latest
     permissions:
       contents: write
       id-token: write
+      issues: write
+      pull-requests: write
 
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: "24"
-          registry-url: "https://registry.npmjs.org"
+          node-version: "22"
+
+      - name: Ensure npm version for trusted publishing
+        run: npm install -g npm@latest
 
       - name: Install pnpm
         uses: pnpm/action-setup@v4
@@ -51,14 +61,7 @@ jobs:
       - name: Build
         run: pnpm build
 
-      - name: Publish to npm
-        run: pnpm publish --provenance --access public --no-git-checks
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Create GitHub Release
-        uses: softprops/action-gh-release@v2
-        with:
-          generate_release_notes: true
+      - name: Semantic release
+        run: pnpm release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.releaserc.cjs

@@ -0,0 +1,23 @@
+const isLocalDryRun = process.env.SEMREL_LOCAL === "1";
+const commitAnalyzerConfig = {
+	releaseRules: [
+		{ breaking: true, release: "major" },
+		{ type: "feat", release: "minor" },
+		{ type: "fix", release: "patch" },
+		{ type: "perf", release: "patch" },
+		{ type: "revert", release: "patch" },
+	],
+};
+
+/** @type {import('semantic-release').GlobalConfig} */
+module.exports = {
+	branches: ["main"],
+	plugins: isLocalDryRun
+		? [["@semantic-release/commit-analyzer", commitAnalyzerConfig]]
+		: [
+				["@semantic-release/commit-analyzer", commitAnalyzerConfig],
+				"@semantic-release/release-notes-generator",
+				"@semantic-release/npm",
+				"@semantic-release/github",
+			],
+};

README.md

@@ -65,6 +65,7 @@ tailwind-lint --verbose
 - `-c, --config <path>` - Path to Tailwind config file (default: auto-discover)
 - `-a, --auto` - Auto-discover files from config content patterns (legacy, enabled by default)
 - `--fix` - Automatically fix problems that can be fixed
+- `--format <text|json>` - Output format (`text` default, `json` for machine-readable output)
 - `-v, --verbose` - Enable verbose logging for debugging
 - `-h, --help` - Show help message
 - `--version` - Show version number
@@ -83,8 +84,33 @@ tailwind-lint "**/*.vue" --fix
 
 # Lint with a specific CSS config (v4)
 tailwind-lint --config ./styles/app.css
+
+# Machine-readable output for LLMs/agents
+tailwind-lint --auto --format json
 ```
 
+## LLM / Agent Integration
+
+Use JSON output to avoid brittle text parsing:
+
+```bash
+tailwind-lint --auto --format json
+```
+
+The JSON payload includes:
+
+- `ok` - `true` when no errors are found
+- `summary` - counts for `errors`, `warnings`, `fixed`, `filesWithIssues`, `totalFilesProcessed`
+- `config` - resolved runtime values (`cwd`, `configPath`, `autoDiscover`, `fix`, `patterns`)
+- `files[]` - per-file diagnostics with 1-based `line`/`column` ranges
+
+Typical agent flow:
+
+1. Run `tailwind-lint --auto --format json`.
+2. If `summary.errors > 0`, fail the check and surface diagnostics.
+3. If only warnings exist, optionally continue and open a cleanup task.
+4. Re-run with `--fix` when autofix is allowed.
+
 ## Configuration
 
 ### Tailwind CSS v4
@@ -172,4 +198,25 @@ pnpm format
 
 # Check code without fixing
 pnpm lint
+
+# Preview next version locally (no publish)
+pnpm release:dry
 ```
+
+## Releases
+
+Releases are automated with Semantic Release on pushes to `main`.
+
+- Version bump is derived from Conventional Commits.
+- npm release and GitHub release are generated automatically.
+- npm publish uses npm Trusted Publishing (OIDC), no `NPM_TOKEN` required.
+
+Commit examples:
+
+- `feat: add json output mode` -> minor release
+- `fix: resolve v4 config discovery in monorepos` -> patch release
+- `feat: drop Node 20 support` + commit body `BREAKING CHANGE: Node 20 is no longer supported` -> major release
+- `perf: speed up config discovery` -> patch release
+- `docs: update readme` -> no release
+
+`pnpm release:dry` runs against the local repo metadata (`--repository-url .`) so it does not require GitHub remote access.

__tests__/discovery.test.ts

@@ -3,7 +3,11 @@ import os from "node:os";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { TAILWIND_V4_IMPORT_REGEX } from "../src/constants";
-import { extractSourcePatterns } from "../src/linter";
+import {
+	extractImportSourceDirectives,
+	extractSourcePatterns,
+} from "../src/linter";
+import { findTailwindConfigPath } from "../src/utils/config";
 import { readGitignorePatterns } from "../src/utils/fs";
 
 describe("extractSourcePatterns", () => {
@@ -97,6 +101,28 @@ describe("extractSourcePatterns", () => {
 	});
 });
 
+describe("extractImportSourceDirectives", () => {
+	it("should extract source roots from @import directives", () => {
+		const css = `
+@import "tailwindcss" source("../src");
+@import "tailwindcss" source("./components");
+`;
+
+		expect(extractImportSourceDirectives(css)).toEqual({
+			roots: ["../src", "./components"],
+			disableAutoSource: false,
+		});
+	});
+
+	it("should detect source(none)", () => {
+		const css = `@import "tailwindcss" source(none);`;
+		expect(extractImportSourceDirectives(css)).toEqual({
+			roots: [],
+			disableAutoSource: true,
+		});
+	});
+});
+
 describe("TAILWIND_V4_IMPORT_REGEX", () => {
 	it("should match standard @import tailwindcss", () => {
 		expect(TAILWIND_V4_IMPORT_REGEX.test('@import "tailwindcss"')).toBe(true);
@@ -222,3 +248,39 @@ describe("readGitignorePatterns", () => {
 		expect(patterns).toEqual(["vendor/**"]);
 	});
 });
+
+describe("findTailwindConfigPath", () => {
+	let tmpDir: string;
+
+	beforeEach(() => {
+		tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "tailwind-config-test-"));
+	});
+
+	afterEach(() => {
+		fs.rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	it("should discover nested v3 config files recursively", async () => {
+		const nestedDir = path.join(tmpDir, "packages", "web");
+		fs.mkdirSync(nestedDir, { recursive: true });
+		fs.writeFileSync(
+			path.join(nestedDir, "tailwind.config.js"),
+			"module.exports = { content: ['./src/**/*.tsx'] }",
+		);
+
+		const discovered = await findTailwindConfigPath(tmpDir);
+		expect(discovered).toBe(path.join(nestedDir, "tailwind.config.js"));
+	});
+
+	it("should discover nested v4 css configs recursively", async () => {
+		const nestedDir = path.join(tmpDir, "apps", "site", "styles");
+		fs.mkdirSync(nestedDir, { recursive: true });
+		fs.writeFileSync(
+			path.join(nestedDir, "theme.css"),
+			'@import "tailwindcss";',
+		);
+
+		const discovered = await findTailwindConfigPath(tmpDir);
+		expect(discovered).toBe(path.join(nestedDir, "theme.css"));
+	});
+});

__tests__/output.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { createJsonOutput, toJsonDiagnostic } from "../src/output";
+import type { Diagnostic } from "vscode-languageserver";
+
+describe("toJsonDiagnostic", () => {
+	it("should convert diagnostic ranges to 1-based positions", () => {
+		const diagnostic: Diagnostic = {
+			range: {
+				start: { line: 0, character: 4 },
+				end: { line: 0, character: 8 },
+			},
+			severity: 1,
+			message: "Test error",
+			code: "testRule",
+			source: "tailwindcss",
+		};
+
+		expect(toJsonDiagnostic(diagnostic)).toEqual({
+			line: 1,
+			column: 5,
+			endLine: 1,
+			endColumn: 9,
+			severity: "error",
+			code: "testRule",
+			message: "Test error",
+			source: "tailwindcss",
+		});
+	});
+});
+
+describe("createJsonOutput", () => {
+	it("should build machine-readable summary and config metadata", () => {
+		const output = createJsonOutput({
+			files: [
+				{
+					path: "src/example.html",
+					fixed: true,
+					fixedCount: 2,
+					diagnostics: [
+						{
+							range: {
+								start: { line: 0, character: 0 },
+								end: { line: 0, character: 5 },
+							},
+							severity: 1,
+							message: "Invalid class",
+							code: "invalidClass",
+						},
+						{
+							range: {
+								start: { line: 1, character: 2 },
+								end: { line: 1, character: 6 },
+							},
+							severity: 2,
+							message: "Suggested order",
+							code: "recommendedVariantOrder",
+						},
+					],
+				},
+			],
+			totalFilesProcessed: 3,
+			cwd: "/tmp/project",
+			configPath: "src/app.css",
+			autoDiscover: true,
+			fix: true,
+			patterns: [],
+		});
+
+		expect(output.ok).toBe(false);
+		expect(output.summary).toEqual({
+			errors: 1,
+			warnings: 1,
+			fixed: 2,
+			filesWithIssues: 1,
+			totalFilesProcessed: 3,
+		});
+		expect(output.config).toEqual({
+			cwd: "/tmp/project",
+			configPath: "src/app.css",
+			autoDiscover: true,
+			fix: true,
+			patterns: [],
+		});
+		expect(output.files[0].path).toBe("src/example.html");
+		expect(output.files[0].diagnostics).toHaveLength(2);
+	});
+});