@savvy-web/silk-effects 0.6.1 → 1.0.0

package/lint/handlers/Markdown.js

@@ -0,0 +1,139 @@
+import { Command } from "../utils/Command.js";
+import { Filter } from "../utils/Filter.js";
+import { getWorkspaceRoot } from "../utils/Workspace.js";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+//#region src/lint/handlers/Markdown.ts
+/**
+* Handler for Markdown files.
+*
+* Lints and auto-fixes with markdownlint-cli2.
+*/
+/**
+* Handler for Markdown files.
+*
+* Lints and auto-fixes with markdownlint-cli2.
+*
+* Tool discovery order:
+* 1. Global `markdownlint-cli2` command (preferred)
+* 2. Local installation via `pnpm exec markdownlint-cli2`
+* 3. Local installation via `npx markdownlint-cli2`
+*
+* Config file discovery order:
+* 1. Explicit `config` option if provided
+* 2. `lib/configs/.markdownlint-cli2.jsonc` (and variants)
+* 3. Standard locations (`.markdownlint-cli2.jsonc` at repo root, etc.)
+*
+* @throws Error if markdownlint-cli2 is not available (globally or locally)
+*
+* @example
+* ```typescript
+* import { Markdown } from '@savvy-web/lint-staged';
+*
+* export default {
+*   // Auto-discovers command and config file
+*   [Markdown.glob]: Markdown.handler,
+*
+*   // Or explicit config path
+*   [Markdown.glob]: Markdown.create({
+*     config: './config/.markdownlint.jsonc',
+*   }),
+* };
+* ```
+*/
+var Markdown = class Markdown {
+	/**
+	* Glob pattern for matching Markdown files.
+	* @defaultValue `'**\/*.{md,mdx}'`
+	*/
+	static glob = "**/*.{md,mdx}";
+	/**
+	* Default patterns to exclude from processing.
+	* @defaultValue `[]`
+	*/
+	static defaultExcludes = [];
+	/**
+	* Pre-configured handler with default options.
+	* Auto-discovers command and config file location.
+	*/
+	static handler = Markdown.create();
+	/**
+	* Find the markdownlint-cli2 executable.
+	*
+	* Searches in order:
+	* 1. Global `markdownlint-cli2` command
+	* 2. `pnpm exec markdownlint-cli2`
+	* 3. `npx markdownlint-cli2`
+	*
+	* @returns The command to run markdownlint-cli2, or undefined if not found
+	*/
+	static findMarkdownlint() {
+		return Command.findTool("markdownlint-cli2").command;
+	}
+	/**
+	* Check if markdownlint-cli2 is available.
+	*
+	* @returns `true` if markdownlint-cli2 is available globally or locally
+	*/
+	static isAvailable() {
+		return Command.findTool("markdownlint-cli2").available;
+	}
+	/**
+	* Find the markdownlint config file.
+	*
+	* Paths are anchored to the workspace root (via {@link getWorkspaceRoot}),
+	* falling back to `process.cwd()` when not inside a workspace.
+	*
+	* Searches in order:
+	* 1. `{workspaceRoot}/lib/configs/` directory
+	* 2. `{workspaceRoot}/` (repo root)
+	*
+	* @returns The config file path, or undefined if not found
+	*/
+	static findConfig() {
+		const root = getWorkspaceRoot() ?? process.cwd();
+		for (const name of [
+			".markdownlint-cli2.jsonc",
+			".markdownlint-cli2.json",
+			".markdownlint-cli2.yaml",
+			".markdownlint-cli2.cjs",
+			".markdownlint.jsonc",
+			".markdownlint.json",
+			".markdownlint.yaml"
+		]) {
+			const libPath = join(root, "lib/configs", name);
+			if (existsSync(libPath)) return libPath;
+			const rootPath = join(root, name);
+			if (existsSync(rootPath)) return rootPath;
+		}
+	}
+	/**
+	* Create a handler with custom options.
+	*
+	* @param options - Configuration options
+	* @returns A lint-staged compatible handler function
+	* @throws Error if markdownlint-cli2 is not available when handler is invoked
+	*/
+	static create(options = {}) {
+		const excludes = options.exclude ?? [...Markdown.defaultExcludes];
+		const noFix = options.noFix ?? false;
+		const config = options.config ?? Markdown.findConfig();
+		return (filenames) => {
+			const filtered = Filter.exclude(filenames, excludes);
+			if (filtered.length === 0) return [];
+			const mdlintCmd = Command.requireTool("markdownlint-cli2", "markdownlint-cli2 is not available. Install it globally or add it as a dev dependency.");
+			const files = Filter.shellEscape(filtered);
+			const fixFlag = noFix ? "" : "--fix";
+			return [
+				mdlintCmd,
+				config ? `--config '${config}'` : "",
+				fixFlag,
+				files
+			].filter(Boolean).join(" ");
+		};
+	}
+};
+
+//#endregion
+export { Markdown };

package/lint/handlers/PackageJson.js

@@ -0,0 +1,130 @@
+import { Command } from "../utils/Command.js";
+import { Filter } from "../utils/Filter.js";
+import { isWorkspacePackagePath } from "../utils/Workspace.js";
+import { readFileSync, writeFileSync } from "node:fs";
+import sortPackageJson from "sort-package-json";
+
+//#region src/lint/handlers/PackageJson.ts
+/**
+* Handler for package.json files.
+*
+* Sorts fields with sort-package-json and formats with Biome.
+*/
+/**
+* Handler for package.json files.
+*
+* Sorts fields with sort-package-json and formats with Biome.
+*
+* @example
+* ```typescript
+* import { PackageJson } from '@savvy-web/lint-staged';
+*
+* export default {
+*   // Use defaults
+*   [PackageJson.glob]: PackageJson.handler,
+*
+*   // Or customize
+*   [PackageJson.glob]: PackageJson.create({
+*     exclude: ['packages/legacy/package.json'],
+*     skipSort: true,
+*   }),
+* };
+* ```
+*/
+var PackageJson = class PackageJson {
+	/**
+	* Glob pattern for matching package.json files.
+	* @defaultValue `'**\/package.json'`
+	*/
+	static glob = "**/package.json";
+	/**
+	* Default patterns to exclude from processing.
+	* @defaultValue `['dist/package.json', '__fixtures__']`
+	*/
+	static defaultExcludes = ["dist/package.json", "__fixtures__"];
+	/**
+	* Pre-configured handler with default options.
+	*/
+	static handler = PackageJson.create();
+	/**
+	* Filter filenames to workspace roots only.
+	*
+	* @remarks
+	* Applies exclude patterns first (for backward compatibility with custom
+	* excludes), then filters to workspace root and leaf workspace roots only.
+	* Falls back permissively when not in a workspace.
+	*
+	* @param filenames - Incoming file list from lint-staged
+	* @param excludes - Patterns to exclude before workspace filtering
+	* @returns Filtered list of files at workspace roots
+	*/
+	static filterToWorkspaceRoots(filenames, excludes) {
+		return Filter.exclude(filenames, [...excludes]).filter((f) => isWorkspacePackagePath(f));
+	}
+	/**
+	* Create a handler with custom options.
+	*
+	* @param options - Configuration options
+	* @returns A lint-staged compatible handler function
+	*/
+	/**
+	* Create a handler that returns a CLI command to sort package.json files.
+	*
+	* @remarks
+	* Unlike {@link create}, this does not modify files in the handler function
+	* body. Instead it returns a `savvy-lint fmt package-json` command so
+	* lint-staged can detect the modification and auto-stage it.
+	* Use this in lint-staged array syntax for sequential execution.
+	*
+	* @param options - Configuration options
+	* @returns A lint-staged compatible handler function
+	*/
+	static fmtCommand(options = {}) {
+		const excludes = options.exclude ?? [...PackageJson.defaultExcludes];
+		return (filenames) => {
+			const filtered = PackageJson.filterToWorkspaceRoots(filenames, excludes);
+			if (filtered.length === 0) return [];
+			return `${Command.findSavvyLint()} fmt package-json ${Filter.shellEscape(filtered)}`;
+		};
+	}
+	/**
+	* Sort the keys of a package.json document string.
+	*
+	* @remarks
+	* Pure transform over the file contents using `sort-package-json`. Used by
+	* the `savvy lint fmt package-json` subcommand so the CLI does not depend on
+	* `sort-package-json` directly.
+	*
+	* @param content - The raw package.json file contents
+	* @returns The sorted package.json file contents
+	*/
+	static sortContent(content) {
+		return sortPackageJson(content);
+	}
+	/**
+	* Create a handler with custom options.
+	*
+	* @param options - Configuration options
+	* @returns A lint-staged compatible handler function
+	*/
+	static create(options = {}) {
+		const excludes = options.exclude ?? [...PackageJson.defaultExcludes];
+		const skipSort = options.skipSort ?? false;
+		const skipFormat = options.skipFormat ?? false;
+		return (filenames) => {
+			const filtered = PackageJson.filterToWorkspaceRoots(filenames, excludes);
+			if (filtered.length === 0) return [];
+			if (!skipSort) for (const filepath of filtered) {
+				const content = readFileSync(filepath, "utf-8");
+				const sorted = sortPackageJson(content);
+				if (sorted !== content) writeFileSync(filepath, sorted, "utf-8");
+			}
+			if (skipFormat) return [];
+			const files = Filter.shellEscape(filtered);
+			return options.biomeConfig ? `biome check --write --max-diagnostics=none --config-path=${options.biomeConfig} ${files}` : `biome check --write --max-diagnostics=none ${files}`;
+		};
+	}
+};
+
+//#endregion
+export { PackageJson };

package/lint/handlers/PnpmWorkspace.js

@@ -0,0 +1,141 @@
+import { Command } from "../utils/Command.js";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { parse, stringify } from "yaml";
+
+//#region src/lint/handlers/PnpmWorkspace.ts
+/**
+* Handler for pnpm-workspace.yaml.
+*
+* Sorts, formats, and validates pnpm-workspace.yaml using bundled libraries.
+*/
+/**
+* Default YAML stringify options for consistent formatting.
+*/
+const DEFAULT_STRINGIFY_OPTIONS = {
+	indent: 2,
+	lineWidth: 0,
+	singleQuote: false
+};
+/**
+* Handler for pnpm-workspace.yaml.
+*
+* Sorts, formats, and validates pnpm-workspace.yaml using bundled libraries.
+*
+* @remarks
+* This handler processes the workspace file entirely in JavaScript:
+* - Sorts the `packages` array alphabetically (if present)
+* - Sorts `onlyBuiltDependencies` and `publicHoistPattern` arrays (if present)
+* - Sorts all top-level keys alphabetically, keeping `packages` first
+* - Formats the output with consistent YAML styling
+* - Validates the YAML structure
+*
+* @example
+* ```typescript
+* import { PnpmWorkspace } from '\@savvy-web/lint-staged';
+*
+* export default {
+*   [PnpmWorkspace.glob]: PnpmWorkspace.create({
+*     skipSort: true, // Skip sorting
+*   }),
+* };
+* ```
+*/
+var PnpmWorkspace = class PnpmWorkspace {
+	/**
+	* Glob pattern for matching pnpm-workspace.yaml.
+	* @defaultValue `'pnpm-workspace.yaml'`
+	*/
+	static glob = "pnpm-workspace.yaml";
+	/**
+	* Default patterns to exclude (none, since this is a single file).
+	* @defaultValue `[]`
+	*/
+	static defaultExcludes = [];
+	/**
+	* Pre-configured handler with default options.
+	*/
+	static handler = PnpmWorkspace.create();
+	/**
+	* Keys whose array values should be sorted alphabetically.
+	*/
+	static SORTABLE_ARRAY_KEYS = new Set([
+		"packages",
+		"onlyBuiltDependencies",
+		"publicHoistPattern"
+	]);
+	/**
+	* Sort the pnpm-workspace.yaml content.
+	*
+	* Sorts:
+	* - `packages` array alphabetically
+	* - `onlyBuiltDependencies` array (if present)
+	* - `publicHoistPattern` array (if present)
+	* - All keys alphabetically, keeping `packages` first
+	*
+	* @param content - Parsed pnpm-workspace.yaml content
+	* @returns Sorted content
+	*/
+	static sortContent(content) {
+		const result = {};
+		const keys = Object.keys(content).sort((a, b) => {
+			if (a === "packages") return -1;
+			if (b === "packages") return 1;
+			return a.localeCompare(b);
+		});
+		for (const key of keys) {
+			const value = content[key];
+			if (PnpmWorkspace.SORTABLE_ARRAY_KEYS.has(key) && Array.isArray(value)) result[key] = [...value].sort();
+			else result[key] = value;
+		}
+		return result;
+	}
+	/**
+	* Create a handler that returns a CLI command to sort/format pnpm-workspace.yaml.
+	*
+	* @remarks
+	* Unlike {@link create}, this does not modify files in the handler function
+	* body. Instead it returns a `savvy-lint fmt pnpm-workspace` command so
+	* lint-staged can detect the modification and auto-stage it.
+	* Use this in lint-staged array syntax for sequential execution.
+	*
+	* @returns A lint-staged compatible handler function
+	*/
+	static fmtCommand() {
+		return () => {
+			if (!existsSync("pnpm-workspace.yaml")) return [];
+			return `${Command.findSavvyLint()} fmt pnpm-workspace`;
+		};
+	}
+	/**
+	* Create a handler with custom options.
+	*
+	* @param options - Configuration options
+	* @returns A lint-staged compatible handler function
+	*/
+	static create(options = {}) {
+		const skipSort = options.skipSort ?? false;
+		const skipFormat = options.skipFormat ?? false;
+		const skipLint = options.skipLint ?? false;
+		return () => {
+			const filepath = "pnpm-workspace.yaml";
+			if (!existsSync(filepath)) return [];
+			const content = readFileSync(filepath, "utf-8");
+			let parsed;
+			try {
+				parsed = parse(content);
+			} catch (error) {
+				if (!skipLint) throw new Error(`Invalid YAML in ${filepath}: ${error instanceof Error ? error.message : String(error)}`);
+				return [];
+			}
+			if (!skipSort) parsed = PnpmWorkspace.sortContent(parsed);
+			if (!skipSort || !skipFormat) {
+				writeFileSync(filepath, stringify(parsed, DEFAULT_STRINGIFY_OPTIONS), "utf-8");
+				return [];
+			}
+			return [];
+		};
+	}
+};
+
+//#endregion
+export { PnpmWorkspace };

package/lint/handlers/ShellScripts.js

@@ -0,0 +1,58 @@
+import { Filter } from "../utils/Filter.js";
+
+//#region src/lint/handlers/ShellScripts.ts
+/**
+* Handler for shell script files.
+*
+* Removes executable bit by default (security best practice).
+*
+* @remarks
+* By default, excludes `.claude/scripts/` which need to remain executable
+* for lint-staged hooks to work.
+*
+* @example
+* ```typescript
+* import { ShellScripts } from '@savvy-web/lint-staged';
+*
+* export default {
+*   [ShellScripts.glob]: ShellScripts.create({
+*     exclude: ['.claude/scripts/', 'bin/'],
+*   }),
+* };
+* ```
+*/
+var ShellScripts = class ShellScripts {
+	/**
+	* Glob pattern for matching shell script files.
+	* @defaultValue `'**\/*.sh'`
+	*/
+	static glob = "**/*.sh";
+	/**
+	* Default patterns to exclude from processing.
+	* @defaultValue `['.claude/scripts/']`
+	*/
+	static defaultExcludes = [".claude/scripts/"];
+	/**
+	* Pre-configured handler with default options.
+	*/
+	static handler = ShellScripts.create();
+	/**
+	* Create a handler with custom options.
+	*
+	* @param options - Configuration options
+	* @returns A lint-staged compatible handler function
+	*/
+	static create(options = {}) {
+		const excludes = options.exclude ?? [...ShellScripts.defaultExcludes];
+		const makeExecutable = options.makeExecutable ?? false;
+		return (filenames) => {
+			const filtered = Filter.exclude(filenames, excludes);
+			if (filtered.length === 0) return [];
+			const chmodFlag = makeExecutable ? "+x" : "-x";
+			return filtered.map((file) => `chmod ${chmodFlag} ${file}`);
+		};
+	}
+};
+
+//#endregion
+export { ShellScripts };

package/lint/handlers/TypeScript.js

@@ -0,0 +1,134 @@
+import { Command } from "../utils/Command.js";
+import { Filter } from "../utils/Filter.js";
+
+//#region src/lint/handlers/TypeScript.ts
+/**
+* Handler for TypeScript files.
+*
+* Runs type checking with tsgo or tsc.
+*
+* @remarks
+* Type checking runs on all staged TypeScript files using the configured
+* compiler (tsgo or tsc). The compiler is auto-detected at runtime using
+* `Command.findTool()`, which correctly handles pnpm catalogs, peer
+* dependencies, and hoisted/transitive deps.
+*
+* @example
+* ```typescript
+* import { TypeScript } from '\@savvy-web/lint-staged';
+*
+* export default {
+*   // Auto-detects compiler and runs type checking
+*   [TypeScript.glob]: TypeScript.handler,
+*
+*   // Or explicit config
+*   [TypeScript.glob]: TypeScript.create({
+*     skipTypecheck: true,
+*   }),
+* };
+* ```
+*/
+var TypeScript = class TypeScript {
+	/**
+	* Glob pattern for matching TypeScript files.
+	* @defaultValue `'*.{ts,cts,mts,tsx}'`
+	*/
+	static glob = "*.{ts,cts,mts,tsx}";
+	/**
+	* Default patterns to exclude from processing.
+	* @defaultValue `[]`
+	*/
+	static defaultExcludes = [];
+	/** Cached compiler detection result */
+	static cachedCompilerResult = null;
+	/**
+	* Detect which TypeScript compiler to use.
+	*
+	* Uses `Command.findTool()` to check for available compilers:
+	* 1. `tsgo` (native TypeScript) — checked first
+	* 2. `tsc` (standard TypeScript) — fallback
+	*
+	* @remarks
+	* Unlike the previous implementation that parsed `package.json` dependencies,
+	* this uses runtime tool detection which works correctly with pnpm catalogs,
+	* peer dependencies, and hoisted/transitive deps.
+	*
+	* @param _cwd - Ignored (kept for backward compatibility)
+	* @returns The compiler to use, or undefined if neither is available
+	*/
+	static detectCompiler(_cwd) {
+		if (TypeScript.cachedCompilerResult !== null) return TypeScript.cachedCompilerResult.compiler;
+		const tsgo = Command.findTool("tsgo");
+		if (tsgo.available) {
+			TypeScript.cachedCompilerResult = {
+				compiler: "tsgo",
+				tool: tsgo
+			};
+			return "tsgo";
+		}
+		const tsc = Command.findTool("tsc");
+		if (tsc.available) {
+			TypeScript.cachedCompilerResult = {
+				compiler: "tsc",
+				tool: tsc
+			};
+			return "tsc";
+		}
+	}
+	/**
+	* Check if a TypeScript compiler is available.
+	*
+	* @returns `true` if either tsgo or tsc is available
+	*/
+	static isAvailable() {
+		return TypeScript.detectCompiler() !== void 0;
+	}
+	/**
+	* Get the default type checking command for the detected compiler.
+	*
+	* @remarks
+	* Uses the cached `ToolSearchResult` from `detectCompiler()` to build
+	* the command string, avoiding a separate package manager detection step.
+	*
+	* @returns Command string like `pnpm exec tsgo --noEmit` or `tsgo --noEmit`
+	* @throws Error if no TypeScript compiler is available
+	*/
+	static getDefaultTypecheckCommand() {
+		if (!TypeScript.detectCompiler() || !TypeScript.cachedCompilerResult) throw new Error("No TypeScript compiler found. Install 'typescript' or '@typescript/native-preview' as a dev dependency.");
+		return `${TypeScript.cachedCompilerResult.tool.command} --noEmit`;
+	}
+	/**
+	* Clear the cached compiler detection result.
+	* Useful for testing or when the environment changes.
+	*/
+	static clearCache() {
+		TypeScript.cachedCompilerResult = null;
+	}
+	/**
+	* Pre-configured handler with default options.
+	*/
+	static handler = TypeScript.create();
+	/**
+	* Create a handler with custom options.
+	*
+	* @param options - Configuration options
+	* @returns A lint-staged compatible handler function
+	*/
+	static create(options = {}) {
+		const excludes = options.exclude ?? [...TypeScript.defaultExcludes];
+		const skipTypecheck = options.skipTypecheck ?? false;
+		let typecheckCommand;
+		const getTypecheckCommand = () => {
+			if (typecheckCommand === void 0) typecheckCommand = options.typecheckCommand ?? TypeScript.getDefaultTypecheckCommand();
+			return typecheckCommand;
+		};
+		return (filenames) => {
+			if (Filter.exclude(filenames, excludes).length === 0) return [];
+			if (!skipTypecheck) return [getTypecheckCommand()];
+			return [];
+		};
+	}
+};
+
+//#endregion
+export { TypeScript };