@savvy-web/silk-effects 0.6.1 → 1.0.0

package/commitlint/config/factory.js

@@ -0,0 +1,69 @@
+import { detectDCO } from "../detection/dco.js";
+import { COMMIT_TYPES } from "./rules.js";
+import { createPromptConfig } from "../prompt/config.js";
+import { createScopeEnumRule, silkPlugin } from "./plugins.js";
+
+//#region src/commitlint/config/factory.ts
+/**
+* Configuration factory implementation.
+*
+* @internal
+*/
+/**
+* Create a commitlint configuration with auto-detection.
+*
+* @remarks
+* This function is the internal implementation for {@link CommitlintConfig.silk}.
+* It receives already-validated options and performs the actual configuration
+* assembly with auto-detection of repository settings.
+*
+* @param options - Resolved configuration options (after Zod parsing)
+* @returns Commitlint UserConfig object
+*
+* @internal
+*/
+function createConfig(options) {
+	const cwd = options.cwd ?? process.cwd();
+	const dco = process.env.COMMITLINT_SKIP_DCO === "1" || process.env.COMMITLINT_SKIP_DCO === "true" ? false : options.dco ?? detectDCO(cwd);
+	const scopes = options.scopes ?? [];
+	const allScopes = [...new Set([...scopes, ...options.additionalScopes ?? []])].sort();
+	const rules = {
+		"body-max-line-length": [
+			2,
+			"always",
+			options.bodyMaxLineLength
+		],
+		"type-enum": [
+			2,
+			"always",
+			[...COMMIT_TYPES]
+		],
+		"subject-case": [0]
+	};
+	if (allScopes.length > 0) {
+		rules["scope-enum"] = [0];
+		rules["silk/tdd-scope"] = [0];
+		rules["silk/scope-enum"] = [2, "always"];
+	} else rules["silk/tdd-scope"] = [2, "always"];
+	const plugins = [allScopes.length > 0 ? { rules: {
+		...silkPlugin.rules,
+		"silk/scope-enum": createScopeEnumRule(allScopes)
+	} } : silkPlugin];
+	if (dco) rules["silk/signed-off-by"] = [2, "always"];
+	if (options.noMarkdown) {
+		rules["silk/body-no-markdown"] = [2, "always"];
+		rules["silk/subject-no-markdown"] = [2, "always"];
+	}
+	return {
+		extends: ["@commitlint/config-conventional"],
+		plugins,
+		rules,
+		prompt: createPromptConfig({
+			emojis: options.emojis,
+			...allScopes.length > 0 && { scopes: allScopes }
+		})
+	};
+}
+
+//#endregion
+export { createConfig };

package/commitlint/config/plugins.js

@@ -0,0 +1,227 @@
+import { TDD_SCOPE_PATTERN } from "./rules.js";
+
+//#region src/commitlint/config/plugins.ts
+/**
+* Custom commitlint plugin rules.
+*
+* @remarks
+* These rules help enforce plain-text commit messages by rejecting
+* common markdown formatting patterns that AI agents tend to add.
+*
+* @internal
+*/
+/**
+* Patterns that indicate markdown formatting in commit messages.
+*
+* @internal
+*/
+const MARKDOWN_PATTERNS = {
+	/** Markdown headers (# Header, ## Header, etc.) */
+	headers: /^#{1,6}\s/m,
+	/** Markdown bullet lists (- item, * item) */
+	bullets: /^[\t ]*[-*]\s/m,
+	/** Markdown numbered lists (1. item, 2. item) */
+	numberedLists: /^[\t ]*\d+\.\s/m,
+	/** Markdown code fences (triple backticks) */
+	codeFences: /```/,
+	/** Markdown inline code (`code`) - only flag if excessive */
+	inlineCode: /`[^`]+`/g,
+	/** Markdown bold (**text** or __text__) */
+	bold: /(\*\*|__)[^*_]+(\*\*|__)/,
+	/** Markdown italic (*text* or _text_) - be careful not to match normal underscores */
+	italic: /(?<!\w)\*[^*]+\*(?!\w)/,
+	/** Markdown links [text](url) */
+	links: /\[.+?\]\(.+?\)/,
+	/** Markdown horizontal rules (---, ***, ___) */
+	horizontalRules: /^[-*_]{3,}$/m
+};
+/**
+* Check if text contains markdown formatting.
+*
+* @param text - Text to check
+* @returns Object with detected patterns
+*/
+function detectMarkdown(text) {
+	const detected = [];
+	if (MARKDOWN_PATTERNS.headers.test(text)) detected.push("headers (#)");
+	if (MARKDOWN_PATTERNS.numberedLists.test(text)) detected.push("numbered lists (1.)");
+	if (MARKDOWN_PATTERNS.codeFences.test(text)) detected.push("code fences (```)");
+	if (MARKDOWN_PATTERNS.bold.test(text)) detected.push("bold (**text**)");
+	if (MARKDOWN_PATTERNS.links.test(text)) detected.push("links ([text](url))");
+	if (MARKDOWN_PATTERNS.horizontalRules.test(text)) detected.push("horizontal rules (---)");
+	const inlineCodeMatches = text.match(MARKDOWN_PATTERNS.inlineCode);
+	if (inlineCodeMatches && inlineCodeMatches.length > 2) detected.push("excessive inline code (`code`)");
+	return {
+		hasMarkdown: detected.length > 0,
+		patterns: detected
+	};
+}
+/**
+* Rule: body-no-markdown
+*
+* @remarks
+* Rejects commit message bodies that contain markdown formatting.
+* This helps ensure commit messages are plain text and readable
+* in terminals, git log, and other tools that don't render markdown.
+*
+* Simple unordered lists (`-` or `*`) are allowed for readability.
+*
+* @example
+* ```
+* // Invalid - contains markdown headers
+* feat: add feature
+*
+* ## Summary
+* This adds a new feature.
+*
+* // Valid - plain text with lists
+* feat: add feature
+*
+* Added new feature and fixed related bug:
+* - Implemented user authentication
+* - Fixed session timeout issue
+* ```
+*/
+const bodyNoMarkdown = (parsed) => {
+	const body = parsed.body;
+	if (!body) return [true, ""];
+	const { hasMarkdown, patterns } = detectMarkdown(body);
+	if (hasMarkdown) return [false, `body contains markdown formatting: ${patterns.join(", ")}`];
+	return [true, ""];
+};
+/**
+* Rule: subject-no-markdown
+*
+* @remarks
+* Rejects commit message subjects (first line) that contain markdown.
+* Subjects should be plain text without any formatting.
+*/
+const subjectNoMarkdown = (parsed) => {
+	const subject = parsed.subject;
+	if (!subject) return [true, ""];
+	const { hasMarkdown, patterns } = detectMarkdown(subject);
+	if (hasMarkdown) return [false, `subject contains markdown formatting: ${patterns.join(", ")}`];
+	return [true, ""];
+};
+/**
+* Rule: body-prose-only
+*
+* @remarks
+* A stricter rule that requires commit bodies to be prose paragraphs,
+* rejecting any list-like structures even without markdown markers.
+* Checks for lines that look like list items.
+*/
+const bodyProseOnly = (parsed) => {
+	const body = parsed.body;
+	if (!body) return [true, ""];
+	if (/^[\t ]*(?:[-*•]|\d+[.):])\s/m.test(body)) return [false, "body should be prose paragraphs, not lists"];
+	return [true, ""];
+};
+/**
+* Rule: signed-off-by
+*
+* @remarks
+* Case-insensitive check for DCO signoff trailer. Accepts both
+* "Signed-off-by:" and "signed-off-by:" (and any other casing).
+*
+* This replaces the built-in commitlint signed-off-by rule which
+* is case-sensitive.
+*/
+const signedOffBy = (parsed) => {
+	const raw = parsed.raw;
+	if (!raw) return [false, "message must be signed off"];
+	if (/^signed-off-by:\s*.+$/im.test(raw)) return [true, ""];
+	return [false, "message must be signed off"];
+};
+/**
+* Rule: tdd-scope
+*
+* @remarks
+* Enforces scope format for TDD commits. Non-TDD commits pass unconditionally.
+* TDD commits require a scope in the format `<goalId>:<state>` where:
+* - goalId is a numeric ID (one or more digits)
+* - state is one of: spike, red, green, refactor
+*
+* @example
+* ```
+* // Valid - numeric goalId with valid state
+* tdd(7:green): implement feature
+* tdd(12:spike): research approach
+*
+* // Invalid - no scope
+* tdd: implement feature
+*
+* // Invalid - missing state
+* tdd(7): implement feature
+*
+* // Invalid - non-numeric goalId
+* tdd(feature:green): implement feature
+*
+* // Invalid - invalid state
+* tdd(7:done): implement feature
+* ```
+*/
+function checkTddScope(scope) {
+	if (!scope) return [false, "tdd commits require a scope in the format <goalId>:<state>"];
+	if (!TDD_SCOPE_PATTERN.test(scope)) return [false, `tdd scope must match <digits>:(spike|red|green|refactor), got: ${scope}`];
+	return [true, ""];
+}
+const tddScope = (parsed) => {
+	if (parsed.type !== "tdd") return [true, ""];
+	return checkTddScope(parsed.scope);
+};
+/**
+* Custom commitlint plugin with markdown prevention rules.
+*
+* @remarks
+* This plugin provides rules to enforce plain-text commit messages.
+* Rules are prefixed with `silk/` to namespace them.
+*
+* Available rules:
+* - `silk/body-no-markdown`: Reject markdown in commit body
+* - `silk/subject-no-markdown`: Reject markdown in commit subject
+* - `silk/body-prose-only`: Require prose paragraphs (no lists)
+* - `silk/signed-off-by`: Require DCO signoff
+* - `silk/tdd-scope`: Enforce TDD scope format
+*
+* @internal
+*/
+const silkPlugin = { rules: {
+	"silk/body-no-markdown": bodyNoMarkdown,
+	"silk/subject-no-markdown": subjectNoMarkdown,
+	"silk/body-prose-only": bodyProseOnly,
+	"silk/signed-off-by": signedOffBy,
+	"silk/tdd-scope": tddScope
+} };
+/**
+* Factory function to create a scope enum rule.
+*
+* @remarks
+* Creates a rule that validates commit scopes, with special handling for TDD commits.
+* - For TDD commits: enforces scope format `<goalId>:<state>` where state is one of spike, red, green, refactor
+* - For non-TDD commits: enforces scope is one of the provided project scopes
+*
+* This replaces the built-in commitlint `scope-enum` rule, avoiding duplicate error
+* messages when a TDD commit has an invalid scope.
+*
+* @param scopes - Array of valid project scope strings (e.g. ["api", "cli"])
+* @returns A Rule function that validates scopes
+*
+* @example
+* ```ts
+* const rule = createScopeEnumRule(["api", "cli"]);
+* const [valid, msg] = rule(parsedCommit);
+* ```
+*
+* @internal
+*/
+function createScopeEnumRule(scopes) {
+	return (parsed) => {
+		if (parsed.type === "tdd") return checkTddScope(parsed.scope);
+		if (!parsed.scope || !scopes.includes(parsed.scope)) return [false, `scope must be one of: ${scopes.join(", ")}`];
+		return [true, ""];
+	};
+}
+
+//#endregion
+export { createScopeEnumRule, silkPlugin };

package/commitlint/config/rules.js

@@ -0,0 +1,155 @@
+//#region src/commitlint/config/rules.ts
+/**
+* Allowed commit types for conventional commits.
+*
+* @remarks
+* Extends the standard conventional commit types with:
+* - `ai`: For AI/LLM agent document updates (CLAUDE.md, context files)
+* - `release`: For release commits (version bumps, changelogs)
+*
+* Types are sorted alphabetically for consistent ordering.
+*
+* @public
+*/
+const COMMIT_TYPES = [
+	"ai",
+	"build",
+	"chore",
+	"ci",
+	"docs",
+	"feat",
+	"fix",
+	"perf",
+	"refactor",
+	"release",
+	"revert",
+	"style",
+	"tdd",
+	"test"
+];
+/**
+* Pattern for valid TDD commit scope.
+*
+* @remarks
+* TDD commits require a scope in the format: `<goalId>:<state>`
+* where goalId is a numeric ID and state is one of: spike, red, green, refactor.
+*
+* Example: `tdd(42:red)` or `tdd(1:green)`
+*
+* @public
+*/
+const TDD_SCOPE_PATTERN = /^\d+:(spike|red|green|refactor)$/;
+/**
+* Valid TDD states for commit scope.
+*
+* @remarks
+* These states correspond to the phases of test-driven development:
+* - spike: Research/exploration phase
+* - red: Write failing test
+* - green: Make test pass
+* - refactor: Clean up code
+*
+* @public
+*/
+const TDD_STATES = [
+	"spike",
+	"red",
+	"green",
+	"refactor"
+];
+/**
+* Commit type definitions with metadata for prompts and changelogs.
+*
+* @remarks
+* Each definition provides human-readable text for interactive commit
+* tools and changelog generation. The order here determines display
+* order in prompts (most common types first).
+*
+* @public
+*/
+const COMMIT_TYPE_DEFINITIONS = [
+	{
+		type: "ai",
+		description: "AI/LLM agent document updates (CLAUDE.md, context files)",
+		title: "AI Context"
+	},
+	{
+		type: "feat",
+		description: "A new feature",
+		title: "Features"
+	},
+	{
+		type: "fix",
+		description: "A bug fix",
+		title: "Bug Fixes"
+	},
+	{
+		type: "docs",
+		description: "Documentation only changes",
+		title: "Documentation"
+	},
+	{
+		type: "style",
+		description: "Code style changes (formatting, semicolons, etc)",
+		title: "Styles"
+	},
+	{
+		type: "refactor",
+		description: "Code change that neither fixes a bug nor adds a feature",
+		title: "Code Refactoring"
+	},
+	{
+		type: "perf",
+		description: "A code change that improves performance",
+		title: "Performance Improvements"
+	},
+	{
+		type: "test",
+		description: "Adding missing tests or correcting existing tests",
+		title: "Tests"
+	},
+	{
+		type: "tdd",
+		description: "TDD agent commit (goalId:state scope required)",
+		title: "TDD"
+	},
+	{
+		type: "build",
+		description: "Changes to build system or external dependencies",
+		title: "Builds"
+	},
+	{
+		type: "ci",
+		description: "Changes to CI configuration files and scripts",
+		title: "Continuous Integration"
+	},
+	{
+		type: "chore",
+		description: "Other changes that don't modify src or test files",
+		title: "Chores"
+	},
+	{
+		type: "revert",
+		description: "Reverts a previous commit",
+		title: "Reverts"
+	},
+	{
+		type: "release",
+		description: "Release commits (version bumps, changelogs)",
+		title: "Releases"
+	}
+];
+/**
+* DCO (Developer Certificate of Origin) signoff text.
+*
+* @remarks
+* This is the standard DCO signoff prefix. When DCO is required,
+* commit messages must include a trailer in the format:
+* `Signed-off-by: Name <email>`
+*
+* @public
+*/
+const DCO_SIGNOFF_TEXT = "Signed-off-by:";
+
+//#endregion
+export { COMMIT_TYPES, COMMIT_TYPE_DEFINITIONS, DCO_SIGNOFF_TEXT, TDD_SCOPE_PATTERN, TDD_STATES };

package/commitlint/config/schema.js

@@ -0,0 +1,46 @@
+import { Schema } from "effect";
+
+//#region src/commitlint/config/schema.ts
+/**
+* Effect Schemas for commitlint configuration options.
+*
+* @internal
+*/
+/**
+* Effect Schema for {@link ReleaseFormat}.
+*
+* @internal
+*/
+const ReleaseFormatSchema = Schema.Literal("semver", "packages", "scoped");
+/**
+* Effect Schema for validating {@link ConfigOptions}.
+*
+* @remarks
+* This schema validates and applies defaults to user-provided configuration.
+* Used internally by {@link CommitlintConfig.silk} via {@link decodeConfigOptions}.
+*
+* @internal
+*/
+const ConfigOptionsSchema = Schema.Struct({
+	dco: Schema.optional(Schema.Boolean),
+	scopes: Schema.optional(Schema.Array(Schema.String)),
+	additionalScopes: Schema.optional(Schema.Array(Schema.String)),
+	releaseFormat: Schema.optional(ReleaseFormatSchema),
+	emojis: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+	bodyMaxLineLength: Schema.optionalWith(Schema.Number.pipe(Schema.positive()), { default: () => 300 }),
+	noMarkdown: Schema.optionalWith(Schema.Boolean, { default: () => true }),
+	cwd: Schema.optional(Schema.String)
+});
+/**
+* Decode unknown input into {@link ResolvedConfigOptions}, applying defaults.
+*
+* @remarks
+* Synchronous decoder that throws a `ParseError` on invalid input, mirroring
+* the previous Zod `.parse()` contract used by {@link CommitlintConfig.silk}.
+*
+* @internal
+*/
+const decodeConfigOptions = Schema.decodeUnknownSync(ConfigOptionsSchema);
+
+//#endregion
+export { decodeConfigOptions };

package/commitlint/detection/dco.js

@@ -0,0 +1,53 @@
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+//#region src/commitlint/detection/dco.ts
+/**
+* DCO (Developer Certificate of Origin) detection module.
+*
+* @internal
+*/
+/** Filename for the DCO file that indicates signoff is required. */
+const DCO_FILENAME = "DCO";
+/** Markers that indicate a project root directory. */
+const ROOT_MARKERS = [
+	"pnpm-workspace.yaml",
+	".git",
+	"package.json"
+];
+/**
+* Walk up the directory tree to find the project root.
+*
+* @param cwd - Starting directory
+* @returns Project root path or null if not found
+*
+* @internal
+*/
+function findProjectRoot(cwd) {
+	let dir = resolve(cwd);
+	while (true) {
+		for (const marker of ROOT_MARKERS) if (existsSync(join(dir, marker))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+/**
+* Detect if DCO signoff should be required.
+*
+* @remarks
+* Checks for the presence of a DCO file at the repository root.
+* Walks up the directory tree to find the project root by looking
+* for workspace markers (pnpm-workspace.yaml, .git, package.json).
+*
+* @param cwd - Working directory (defaults to process.cwd())
+* @returns `true` if DCO file exists at repo root, `false` otherwise
+*
+* @public
+*/
+function detectDCO(cwd = process.cwd()) {
+	return existsSync(join(findProjectRoot(cwd) ?? cwd, DCO_FILENAME));
+}
+
+//#endregion
+export { detectDCO };

package/commitlint/detection/scopes.js

@@ -0,0 +1,45 @@
+import { Effect } from "effect";
+import { WorkspaceDiscovery } from "workspaces-effect";
+
+//#region src/commitlint/detection/scopes.ts
+/**
+* Workspace scope detection module.
+*
+* @internal
+*/
+/**
+* Extract scope-friendly name from a package name.
+*
+* @param name - Package name (e.g., `@scope/package-name` or `package-name`)
+* @returns Package name without scope prefix
+*
+* @internal
+*/
+function extractScopeName(name) {
+	if (name.startsWith("@")) return name.split("/")[1];
+	return name;
+}
+/**
+* Detect package scopes from workspace configuration.
+*
+* @remarks
+* Uses workspaces-effect to find all packages in the workspace and extracts
+* their names as potential commit scopes. For scoped packages like
+* `@scope/package-name`, only the package name portion is used as the scope.
+*
+* @returns Effect yielding sorted array of scope names, requires WorkspaceDiscovery
+*
+* @public
+*/
+const detectScopes = Effect.gen(function* () {
+	const packages = yield* (yield* WorkspaceDiscovery).listPackages();
+	const scopes = [];
+	for (const pkg of packages) {
+		const scopeName = extractScopeName(pkg.name);
+		if (scopeName) scopes.push(scopeName);
+	}
+	return scopes.sort();
+});
+
+//#endregion
+export { detectScopes };

package/commitlint/formatter/format.js

@@ -0,0 +1,85 @@
+import { getExplanation, getSuggestion } from "./messages.js";
+
+//#region src/commitlint/formatter/format.ts
+/**
+* Custom formatter implementation for commitlint.
+*
+* @internal
+*/
+/** Unicode symbol for error indicator. */
+const ERROR_ICON = "✗";
+/** Unicode symbol for warning indicator. */
+const WARNING_ICON = "⚠";
+/**
+* Format a single rule result with explanation and suggestion.
+*
+* @param result - Rule result to format
+* @param level - "error" or "warning"
+* @returns Formatted string
+*
+* @internal
+*/
+function formatRuleResult(result, level) {
+	const lines = [`  ${level === "error" ? ERROR_ICON : WARNING_ICON} ${result.name}: ${result.message}`];
+	const explanation = getExplanation(result.name);
+	if (explanation) lines.push(`    ${explanation}`);
+	const suggestion = getSuggestion(result.name);
+	if (suggestion) lines.push(`    Suggestion: ${suggestion}`);
+	return lines.join("\n");
+}
+/**
+* Build summary line for error/warning counts.
+*
+* @param errorCount - Number of errors
+* @param warningCount - Number of warnings
+* @returns Summary string
+*
+* @internal
+*/
+function buildSummary(errorCount, warningCount) {
+	const parts = [];
+	if (errorCount > 0) parts.push(`${errorCount} error${errorCount === 1 ? "" : "s"}`);
+	if (warningCount > 0) parts.push(`${warningCount} warning${warningCount === 1 ? "" : "s"}`);
+	return `Found ${parts.join(", ")}.`;
+}
+/**
+* Format lint results for display.
+*
+* @remarks
+* This is the main formatter function exported for commitlint.
+* It formats errors and warnings with helpful explanations and suggestions.
+*
+* @param formatterResult - Results from commitlint
+* @returns Formatted output string
+*
+* @public
+*/
+function format(formatterResult) {
+	const { results, options } = formatterResult;
+	const output = [];
+	let totalErrors = 0;
+	let totalWarnings = 0;
+	for (const result of results) {
+		if (!(!result.valid || result.errors.length > 0 || result.warnings.length > 0)) continue;
+		const firstLine = result.input.split("\n")[0];
+		output.push(`\nInput: "${firstLine}..."`);
+		output.push("");
+		for (const error of result.errors) {
+			output.push(formatRuleResult(error, "error"));
+			totalErrors++;
+		}
+		for (const warning of result.warnings) {
+			output.push(formatRuleResult(warning, "warning"));
+			totalWarnings++;
+		}
+	}
+	if (totalErrors > 0 || totalWarnings > 0) {
+		output.push("");
+		output.push(buildSummary(totalErrors, totalWarnings));
+		if (options?.helpUrl) output.push(`\nFor more information, see: ${options.helpUrl}`);
+	}
+	return output.join("\n");
+}
+
+//#endregion
+export { format };