@savvy-web/silk-effects 0.6.1 → 1.0.0

package/lint/Handler.js

@@ -0,0 +1,39 @@
+//#region src/lint/Handler.ts
+/**
+* Abstract base class for lint-staged handlers.
+*
+* All handler classes follow this pattern and implement:
+* - `glob` - The recommended glob pattern for matching files
+* - `defaultExcludes` - Default patterns to exclude
+* - `handler` - Pre-configured handler with defaults
+* - `create()` - Factory method for custom configuration
+*/
+var Handler = class {
+	/**
+	* Default glob pattern for this handler.
+	* Use as the key in lint-staged config.
+	*/
+	static glob;
+	/**
+	* Default exclude patterns applied when no options provided.
+	*/
+	static defaultExcludes;
+	/**
+	* Pre-configured handler with default options.
+	* Ready to use directly in lint-staged config.
+	*/
+	static handler;
+	/**
+	* Factory method to create a handler with custom options.
+	*
+	* @param _options - Configuration options for this handler
+	* @returns A lint-staged compatible handler function
+	*/
+	static create(_options) {
+		/* v8 ignore next -- abstract factory; always overridden by concrete subclasses */
+		throw new Error("Handler.create() must be implemented by subclass");
+	}
+};
+
+//#endregion
+export { Handler };

package/lint/cli/sections.js

@@ -0,0 +1,65 @@
+import { SectionDefinition } from "../../schemas/SectionDefinition.js";
+import { savvyToolSection } from "../../schemas/SavvySections.js";
+
+//#region src/lint/cli/sections.ts
+/**
+* Shared managed section definitions and constants for CLI commands.
+*
+* @internal
+*/
+/** Path for the husky pre-commit hook. */
+const HUSKY_HOOK_PATH = ".husky/pre-commit";
+/** Path for the husky post-checkout hook. */
+const POST_CHECKOUT_HOOK_PATH = ".husky/post-checkout";
+/** Path for the husky post-merge hook. */
+const POST_MERGE_HOOK_PATH = ".husky/post-merge";
+/** Default path for the lint-staged config file. */
+const DEFAULT_CONFIG_PATH = "lib/configs/lint-staged.config.ts";
+/** Path for the markdownlint-cli2 config file. */
+const MARKDOWNLINT_CONFIG_PATH = "lib/configs/.markdownlint-cli2.jsonc";
+/** Identity definition for the savvy-lint tool section (read / check / remove). */
+const SavvyLintSectionDef = SectionDefinition.make({ toolName: "savvy-lint" });
+/**
+* Identity definition for the legacy `SAVVY-LINT` hygiene section that previously
+* lived in `.husky/post-checkout` and `.husky/post-merge`.
+*
+* @remarks
+* The hygiene block has been replaced by a co-owned `savvy-hooks` section emitted from
+* silk-effects. Use this definition with `ManagedSection.remove` during migration to
+* delete the leftover block from those hooks. The marker matched is identical to
+* `SavvyLintSectionDef`'s; the two definitions are split only by intent (live tool
+* section vs. legacy hygiene block that lives in a different hook).
+*/
+const LegacySavvyLintHygieneDef = SectionDefinition.make({ toolName: "savvy-lint" });
+/**
+* Build the lint-staged command run inside the savvy-lint tool section.
+*
+* @param configPath - Path to the lint-staged config file (relative to repo root)
+*/
+function lintStagedCommand(configPath) {
+	return `lint-staged --config "$ROOT/${configPath}"`;
+}
+/**
+* Build the savvy-lint tool section block for the given config path.
+*
+* @remarks
+* Depends on the savvy-base preamble (`in_ci`, `pm_exec`) preceding it in the hook.
+*/
+function savvyLintBlock(configPath) {
+	return savvyToolSection("savvy-lint", lintStagedCommand(configPath));
+}
+/**
+* Rendered content of the savvy-lint tool section.
+*
+* @remarks
+* Equivalent to `savvyLintBlock(configPath).content`. Retained for the check command
+* and tests.
+*
+* @param configPath - Path to the lint-staged config file
+*/
+function generateManagedContent(configPath) {
+	return savvyLintBlock(configPath).content;
+}
+
+//#endregion
+export { DEFAULT_CONFIG_PATH, HUSKY_HOOK_PATH, LegacySavvyLintHygieneDef, MARKDOWNLINT_CONFIG_PATH, POST_CHECKOUT_HOOK_PATH, POST_MERGE_HOOK_PATH, SavvyLintSectionDef, generateManagedContent, savvyLintBlock };

package/lint/cli/templates/markdownlint.gen.js

@@ -0,0 +1,183 @@
+//#region src/lint/cli/templates/markdownlint.gen.ts
+/**
+* Auto-generated markdownlint template data.
+*
+* DO NOT EDIT — regenerate with: pnpm generate:templates
+*
+* @internal
+*/
+/** Full markdownlint-cli2 config template. */
+const MARKDOWNLINT_TEMPLATE = {
+	$schema: "https://raw.githubusercontent.com/DavidAnson/markdownlint-cli2/v0.22.0/schema/markdownlint-cli2-config-schema.json",
+	globs: ["**/*.{md,mdx}"],
+	fix: true,
+	gitignore: true,
+	noBanner: true,
+	ignores: [
+		"**/node_modules",
+		"**/.cache",
+		"**/coverage",
+		"**/.coverage",
+		"**/dist",
+		"**/CHANGELOG.md",
+		"**/.claude/plans",
+		"**/docs/superpowers"
+	],
+	customRules: ["@savvy-web/silk/changesets/markdownlint"],
+	config: {
+		default: true,
+		MD001: true,
+		MD002: true,
+		MD003: true,
+		MD004: true,
+		MD005: true,
+		MD006: true,
+		MD007: true,
+		MD008: true,
+		MD009: true,
+		MD010: true,
+		MD011: true,
+		MD012: true,
+		MD013: false,
+		MD014: true,
+		MD015: true,
+		MD016: true,
+		MD017: true,
+		MD018: true,
+		MD019: true,
+		MD020: true,
+		MD021: true,
+		MD022: true,
+		MD023: true,
+		MD024: { siblings_only: true },
+		MD025: true,
+		MD026: true,
+		MD027: true,
+		MD028: true,
+		MD029: true,
+		MD030: true,
+		MD031: true,
+		MD032: true,
+		MD033: { allowed_elements: [
+			"br",
+			"details",
+			"summary",
+			"img",
+			"sup",
+			"sub"
+		] },
+		MD034: true,
+		MD035: true,
+		MD036: true,
+		MD037: true,
+		MD038: true,
+		MD039: true,
+		MD040: true,
+		MD041: true,
+		MD042: true,
+		MD043: false,
+		MD044: false,
+		MD045: true,
+		MD046: true,
+		MD047: true,
+		MD048: true,
+		MD049: true,
+		MD050: true,
+		MD051: true,
+		MD052: true,
+		MD053: true,
+		MD054: true,
+		MD055: true,
+		MD056: true,
+		MD057: true,
+		MD058: true,
+		MD059: true,
+		MD060: { style: "compact" },
+		"changeset-heading-hierarchy": false,
+		"changeset-required-sections": false,
+		"changeset-content-structure": false,
+		"changeset-uncategorized-content": false,
+		"changeset-dependency-table-format": false
+	}
+};
+/** The `$schema` URL from the template. */
+const MARKDOWNLINT_SCHEMA = "https://raw.githubusercontent.com/DavidAnson/markdownlint-cli2/v0.22.0/schema/markdownlint-cli2-config-schema.json";
+/** The `config` rules object from the template. */
+const MARKDOWNLINT_CONFIG = {
+	default: true,
+	MD001: true,
+	MD002: true,
+	MD003: true,
+	MD004: true,
+	MD005: true,
+	MD006: true,
+	MD007: true,
+	MD008: true,
+	MD009: true,
+	MD010: true,
+	MD011: true,
+	MD012: true,
+	MD013: false,
+	MD014: true,
+	MD015: true,
+	MD016: true,
+	MD017: true,
+	MD018: true,
+	MD019: true,
+	MD020: true,
+	MD021: true,
+	MD022: true,
+	MD023: true,
+	MD024: { siblings_only: true },
+	MD025: true,
+	MD026: true,
+	MD027: true,
+	MD028: true,
+	MD029: true,
+	MD030: true,
+	MD031: true,
+	MD032: true,
+	MD033: { allowed_elements: [
+		"br",
+		"details",
+		"summary",
+		"img",
+		"sup",
+		"sub"
+	] },
+	MD034: true,
+	MD035: true,
+	MD036: true,
+	MD037: true,
+	MD038: true,
+	MD039: true,
+	MD040: true,
+	MD041: true,
+	MD042: true,
+	MD043: false,
+	MD044: false,
+	MD045: true,
+	MD046: true,
+	MD047: true,
+	MD048: true,
+	MD049: true,
+	MD050: true,
+	MD051: true,
+	MD052: true,
+	MD053: true,
+	MD054: true,
+	MD055: true,
+	MD056: true,
+	MD057: true,
+	MD058: true,
+	MD059: true,
+	MD060: { style: "compact" },
+	"changeset-heading-hierarchy": false,
+	"changeset-required-sections": false,
+	"changeset-content-structure": false,
+	"changeset-uncategorized-content": false,
+	"changeset-dependency-table-format": false
+};
+
+//#endregion
+export { MARKDOWNLINT_CONFIG, MARKDOWNLINT_SCHEMA, MARKDOWNLINT_TEMPLATE };

package/lint/config/Preset.js

@@ -0,0 +1,152 @@
+import { createConfig } from "./createConfig.js";
+
+//#region src/lint/config/Preset.ts
+/**
+* Preset configurations for common lint-staged setups.
+*
+* @example
+* ```typescript
+* import { Preset } from '@savvy-web/lint-staged';
+*
+* // Use a preset directly
+* export default Preset.standard();
+*
+* // Extend a preset with customizations
+* export default Preset.standard({
+*   biome: { exclude: ['vendor/'] },
+*   custom: {
+*     '*.css': (files) => `stylelint ${files.join(' ')}`,
+*   },
+* });
+* ```
+*/
+var Preset = class Preset {
+	/**
+	* Minimal preset: formatting only.
+	*
+	* Includes:
+	* - PackageJson (sort + format)
+	* - Biome (format JS/TS/JSON)
+	*
+	* @param extend - Options to customize or extend the preset
+	* @returns A lint-staged configuration object
+	*
+	* @example
+	* ```typescript
+	* import { Preset } from '@savvy-web/lint-staged';
+	*
+	* export default Preset.minimal();
+	* ```
+	*/
+	static minimal(extend = {}) {
+		const options = {
+			packageJson: extend.packageJson ?? {},
+			biome: extend.biome ?? {},
+			markdown: extend.markdown ?? false,
+			yaml: extend.yaml ?? false,
+			pnpmWorkspace: extend.pnpmWorkspace ?? false,
+			shellScripts: extend.shellScripts ?? false,
+			typescript: extend.typescript ?? false
+		};
+		if (extend.custom !== void 0) options.custom = extend.custom;
+		return createConfig(options);
+	}
+	/**
+	* Standard preset: formatting + linting.
+	*
+	* Includes:
+	* - PackageJson (sort + format)
+	* - Biome (format JS/TS/JSON)
+	* - Markdown (lint + fix)
+	* - Yaml (format + lint)
+	* - PnpmWorkspace (sort + format)
+	* - ShellScripts (chmod management)
+	*
+	* @param extend - Options to customize or extend the preset
+	* @returns A lint-staged configuration object
+	*
+	* @example
+	* ```typescript
+	* import { Preset } from '@savvy-web/lint-staged';
+	*
+	* export default Preset.standard({
+	*   biome: { exclude: ['legacy/'] },
+	* });
+	* ```
+	*/
+	static standard(extend = {}) {
+		const options = {
+			packageJson: extend.packageJson ?? {},
+			biome: extend.biome ?? {},
+			markdown: extend.markdown ?? {},
+			yaml: extend.yaml ?? {},
+			pnpmWorkspace: extend.pnpmWorkspace ?? {},
+			shellScripts: extend.shellScripts ?? {},
+			typescript: extend.typescript ?? false
+		};
+		if (extend.custom !== void 0) options.custom = extend.custom;
+		return createConfig(options);
+	}
+	/**
+	* Silk preset: all handlers enabled.
+	*
+	* Includes:
+	* - PackageJson (sort + format)
+	* - Biome (format JS/TS/JSON)
+	* - Markdown (lint + fix)
+	* - Yaml (format + lint)
+	* - PnpmWorkspace (sort + format)
+	* - ShellScripts (chmod management)
+	* - TypeScript (TSDoc + typecheck)
+	*
+	* @param extend - Options to customize or extend the preset
+	* @returns A lint-staged configuration object
+	*
+	* @example
+	* ```typescript
+	* import { Preset } from '@savvy-web/lint-staged';
+	*
+	* export default Preset.silk({
+	*   typescript: { skipTypecheck: true },
+	* });
+	* ```
+	*/
+	static silk(extend = {}) {
+		const options = {
+			packageJson: extend.packageJson ?? {},
+			biome: extend.biome ?? {},
+			markdown: extend.markdown ?? {},
+			yaml: extend.yaml ?? {},
+			pnpmWorkspace: extend.pnpmWorkspace ?? {},
+			shellScripts: extend.shellScripts ?? {},
+			typescript: extend.typescript ?? {}
+		};
+		if (extend.custom !== void 0) options.custom = extend.custom;
+		return createConfig(options);
+	}
+	/**
+	* Get a preset by name.
+	*
+	* @param name - The preset name: 'minimal', 'standard', or 'silk'
+	* @param extend - Options to customize or extend the preset
+	* @returns A lint-staged configuration object
+	*
+	* @example
+	* ```typescript
+	* import { Preset } from '@savvy-web/lint-staged';
+	*
+	* const presetName = process.env.LINT_PRESET || 'standard';
+	* export default Preset.get(presetName);
+	* ```
+	*/
+	static get(name, extend = {}) {
+		switch (name) {
+			case "minimal": return Preset.minimal(extend);
+			case "silk": return Preset.silk(extend);
+			default: return Preset.standard(extend);
+		}
+	}
+};
+
+//#endregion
+export { Preset };

package/lint/config/createConfig.js

@@ -0,0 +1,89 @@
+import { Biome } from "../handlers/Biome.js";
+import { Markdown } from "../handlers/Markdown.js";
+import { PackageJson } from "../handlers/PackageJson.js";
+import { PnpmWorkspace } from "../handlers/PnpmWorkspace.js";
+import { ShellScripts } from "../handlers/ShellScripts.js";
+import { TypeScript } from "../handlers/TypeScript.js";
+import { Yaml } from "../handlers/Yaml.js";
+
+//#region src/lint/config/createConfig.ts
+/**
+* Configuration factory for generating complete lint-staged configurations.
+*/
+/**
+* Create a complete lint-staged configuration with all handlers.
+*
+* @param options - Configuration options for each handler
+* @returns A lint-staged compatible configuration object
+*
+* @example
+* ```typescript
+* import { createConfig } from '@savvy-web/lint-staged';
+*
+* // Use all defaults
+* export default createConfig();
+*
+* // Customize specific handlers
+* export default createConfig({
+*   packageJson: { skipSort: true },
+*   biome: { exclude: ['vendor/'] },
+*   custom: {
+*     '*.css': (files) => `stylelint ${files.join(' ')}`,
+*   },
+* });
+* ```
+*/
+function createConfig(options = {}) {
+	const config = {};
+	const pkgJsonEnabled = options.packageJson !== false;
+	const biomeEnabled = options.biome !== false;
+	if (pkgJsonEnabled && biomeEnabled) {
+		const pkgOpts = typeof options.packageJson === "object" ? options.packageJson : {};
+		const biomeOpts = typeof options.biome === "object" ? options.biome : {};
+		config[PackageJson.glob] = [PackageJson.fmtCommand(pkgOpts), Biome.create({
+			...biomeOpts,
+			exclude: [...PackageJson.defaultExcludes]
+		})];
+	} else if (pkgJsonEnabled) {
+		const pkgOpts = typeof options.packageJson === "object" ? options.packageJson : {};
+		config[PackageJson.glob] = PackageJson.create(pkgOpts);
+	}
+	if (biomeEnabled) {
+		const handlerOptions = typeof options.biome === "object" ? options.biome : {};
+		config[Biome.glob] = Biome.create(handlerOptions);
+	}
+	if (options.markdown !== false) {
+		const handlerOptions = typeof options.markdown === "object" ? options.markdown : {};
+		config[Markdown.glob] = Markdown.create(handlerOptions);
+	}
+	const pnpmEnabled = options.pnpmWorkspace !== false;
+	const yamlEnabled = options.yaml !== false;
+	if (pnpmEnabled && yamlEnabled) config[PnpmWorkspace.glob] = [PnpmWorkspace.fmtCommand(), Yaml.create({
+		exclude: [],
+		skipFormat: true
+	})];
+	else if (pnpmEnabled) {
+		const pnpmOpts = typeof options.pnpmWorkspace === "object" ? options.pnpmWorkspace : {};
+		config[PnpmWorkspace.glob] = PnpmWorkspace.create(pnpmOpts);
+	}
+	if (yamlEnabled) {
+		const yamlOpts = typeof options.yaml === "object" ? options.yaml : {};
+		config[Yaml.glob] = [Yaml.fmtCommand(yamlOpts), Yaml.create({
+			...yamlOpts,
+			skipFormat: true
+		})];
+	}
+	if (options.shellScripts !== false) {
+		const handlerOptions = typeof options.shellScripts === "object" ? options.shellScripts : {};
+		config[ShellScripts.glob] = ShellScripts.create(handlerOptions);
+	}
+	if (options.typescript !== false) {
+		const handlerOptions = typeof options.typescript === "object" ? options.typescript : {};
+		config[TypeScript.glob] = TypeScript.create(handlerOptions);
+	}
+	if (options.custom) for (const [glob, handler] of Object.entries(options.custom)) config[glob] = handler;
+	return config;
+}
+
+//#endregion
+export { createConfig };

package/lint/handlers/Biome.js

@@ -0,0 +1,179 @@
+import { Command } from "../utils/Command.js";
+import { Filter } from "../utils/Filter.js";
+import { getWorkspacePackagePaths, getWorkspaceRoot } from "../utils/Workspace.js";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+//#region src/lint/handlers/Biome.ts
+/**
+* Handler for JavaScript/TypeScript/JSON files.
+*
+* Formats and lints with Biome.
+*/
+/**
+* Handler for JavaScript, TypeScript, and JSON files.
+*
+* Formats and lints with Biome.
+*
+* Biome discovery order:
+* 1. Global `biome` command (preferred)
+* 2. Local installation via `pnpm exec biome`
+* 3. Local installation via `npx biome`
+*
+* Config file discovery:
+* - Searches the workspace root for `biome.jsonc` or `biome.json`.
+* - Falls back to CWD when not in a workspace.
+* - No `lib/configs/` convention — biome configs live at workspace roots only.
+*
+* @throws Error if Biome is not available (globally or locally)
+*
+* @example
+* ```typescript
+* import { Biome } from '@savvy-web/lint-staged';
+*
+* export default {
+*   // Auto-discovers biome command and config file
+*   [Biome.glob]: Biome.handler,
+*
+*   // Or with custom excludes
+*   [Biome.glob]: Biome.create({
+*     exclude: ['vendor/', 'generated/'],
+*   }),
+* };
+* ```
+*/
+var Biome = class Biome {
+	/**
+	* Glob pattern for matching JavaScript/TypeScript/JSON files.
+	* @defaultValue `'*.{js,ts,cjs,mjs,d.cts,d.mts,jsx,tsx,json,jsonc}'`
+	*/
+	static glob = "*.{js,ts,cjs,mjs,d.cts,d.mts,jsx,tsx,json,jsonc}";
+	/**
+	* Default patterns to exclude from processing.
+	* Excludes package.json since PackageJson handler processes those files.
+	* @defaultValue `['package.json', 'package-lock.json', '__fixtures__', '__test__/fixtures']`
+	*/
+	static defaultExcludes = [
+		"package.json",
+		"package-lock.json",
+		"__fixtures__",
+		"__test__/fixtures"
+	];
+	/** Candidate config file names in preference order. */
+	static CONFIG_NAMES = ["biome.jsonc", "biome.json"];
+	/**
+	* Pre-configured handler with default options.
+	* Auto-discovers biome command and config file location.
+	*/
+	static handler = Biome.create();
+	/**
+	* Find the Biome executable.
+	*
+	* Searches in order:
+	* 1. Global `biome` command
+	* 2. `pnpm exec biome`
+	* 3. `npx biome`
+	*
+	* @returns The command to run biome, or undefined if not found
+	*/
+	static findBiome() {
+		return Command.findTool("biome").command;
+	}
+	/**
+	* Check if Biome is available.
+	*
+	* @returns `true` if biome is available globally or locally
+	*/
+	static isAvailable() {
+		return Command.findTool("biome").available;
+	}
+	/**
+	* Find the Biome config file at the workspace root.
+	*
+	* @remarks
+	* Searches the workspace root directory for `biome.jsonc` then `biome.json`.
+	* Falls back to CWD when not running inside a workspace. The `lib/configs/`
+	* convention is not used — biome configs are expected at workspace roots only.
+	*
+	* @returns Absolute path to the config file, or undefined if not found
+	*/
+	static findConfig() {
+		const searchDir = getWorkspaceRoot() ?? process.cwd();
+		for (const name of Biome.CONFIG_NAMES) {
+			const fullPath = join(searchDir, name);
+			if (existsSync(fullPath)) return fullPath;
+		}
+	}
+	/**
+	* Find all Biome config files across workspace roots.
+	*
+	* @remarks
+	* Searches the workspace root and each leaf workspace root for a
+	* `biome.jsonc` or `biome.json` config file. At most one config is
+	* collected per directory (the first match in preference order).
+	* Falls back to CWD when not running inside a workspace.
+	*
+	* This method is intended for the CLI check command, which validates
+	* `$schema` URLs across all workspace biome configs.
+	*
+	* @returns Array of absolute config file paths (may be empty)
+	*/
+	static findAllConfigs() {
+		const root = getWorkspaceRoot();
+		const configs = [];
+		if (root === null) {
+			const cwd = process.cwd();
+			for (const name of Biome.CONFIG_NAMES) {
+				const fullPath = join(cwd, name);
+				if (existsSync(fullPath)) {
+					configs.push(fullPath);
+					break;
+				}
+			}
+			return configs;
+		}
+		for (const name of Biome.CONFIG_NAMES) {
+			const fullPath = join(root, name);
+			if (existsSync(fullPath)) {
+				configs.push(fullPath);
+				break;
+			}
+		}
+		for (const pkgPath of getWorkspacePackagePaths()) for (const name of Biome.CONFIG_NAMES) {
+			const fullPath = join(pkgPath, name);
+			if (existsSync(fullPath)) {
+				configs.push(fullPath);
+				break;
+			}
+		}
+		return configs;
+	}
+	/**
+	* Create a handler with custom options.
+	*
+	* @param options - Configuration options
+	* @returns A lint-staged compatible handler function
+	* @throws Error if Biome is not available when handler is invoked
+	*/
+	static create(options = {}) {
+		const excludes = options.exclude ?? [...Biome.defaultExcludes];
+		const config = options.config ?? Biome.findConfig();
+		return (filenames) => {
+			const filtered = Filter.exclude(filenames, excludes);
+			if (filtered.length === 0) return [];
+			const biomeCmd = Command.requireTool("biome", "Biome is not available. Install it globally (recommended) or add @biomejs/biome as a dev dependency.");
+			const files = Filter.shellEscape(filtered);
+			const flags = options.flags ?? [];
+			const configFlag = config ? `--config-path=${config}` : "";
+			return [
+				`${biomeCmd} check --write --no-errors-on-unmatched`,
+				configFlag,
+				...flags,
+				files
+			].filter(Boolean).join(" ");
+		};
+	}
+};
+
+//#endregion
+export { Biome };