commitlint-config-spellbookx 0.11.0 → 0.12.0

package/src/index.ts

@@ -1,160 +1,33 @@
-import type { UserConfig } from '@commitlint/types';
-
-import { getScopes } from './helpers.js';
-
-const SCOPE_WORKSPACE = 'workspace';
-const SCOPE_RELEASE = 'release';
-
-const scopesArray = [SCOPE_WORKSPACE, SCOPE_RELEASE, ...getScopes()];
-
-const scopesEnum: Record<string, { description: string }> = {};
+/**
+ * @file index.ts
+ * Main entry point for commitlint-config-spellbookx.
+ * Exports conventional commit configuration, rules, prompt settings, and scope definitions.
+ */
 
-// Scopes Enum options
-for (const scope of scopesArray) {
-  let description;
-
-  switch (scope) {
-    case SCOPE_WORKSPACE: {
-      description =
-        'workspace scope - root files such as config files, root package.json, etc';
-      break;
-    }
-
-    case SCOPE_RELEASE: {
-      description = 'Special scope for release commits';
-      break;
-    }
-
-    default: {
-      description = `${scope} scope`;
-      break;
-    }
-  }
-
-  Object.defineProperty(scopesEnum, scope, {
-    value: { description },
-    enumerable: true,
-    writable: true,
-    configurable: true,
-  });
-}
+import type { UserConfig } from '@commitlint/types';
 
-const config: UserConfig = {
+import { prompt } from './prompt.js';
+import { rules } from './rules.js';
+
+export { COMMIT_TYPES, type CommitType } from './constants/commit-types.js';
+export * from './lib/index.js';
+export { prompt } from './prompt.js';
+export { rules } from './rules.js';
+export {
+  SCOPE_RELEASE,
+  SCOPE_WORKSPACE,
+  scopesArray,
+  scopesEnum,
+} from './scopes.js';
+
+/**
+ * Shareable Commitlint configuration preset enforcing conventional commits.
+ */
+export const config: UserConfig = {
   extends: ['@commitlint/config-conventional'],
   parserPreset: 'conventional-changelog-conventionalcommits',
-  rules: {
-    'type-enum': [
-      2,
-      'always',
-      [
-        'feat',
-        'fix',
-        'docs',
-        'style',
-        'refactor',
-        'perf',
-        'test',
-        'chore',
-        'ci',
-        'build',
-        'revert',
-      ],
-    ],
-    'scope-enum': [2, 'always', scopesArray],
-    'subject-empty': [2, 'never'],
-    'subject-full-stop': [2, 'never', '.'],
-    'header-max-length': [2, 'always', 72],
-    'body-max-line-length': [2, 'always', 100],
-    'footer-max-line-length': [2, 'always', 100],
-  },
-  prompt: {
-    settings: {
-      enableMultipleScopes: true,
-      scopeEnumSeparator: ',',
-    },
-    messages: {
-      skip: ':skip',
-      max: 'upper %d chars',
-      min: '%d chars at least',
-      emptyWarning: 'can not be empty',
-      upperLimitWarning: 'over limit',
-      lowerLimitWarning: 'below limit',
-    },
-    questions: {
-      type: {
-        description: "Select the type of change that you're committing:",
-        enum: {
-          feat: {
-            description: 'A new feature',
-            title: 'Features',
-            emoji: '✨',
-          },
-          fix: { description: 'A bug fix', title: 'Bug Fixes', emoji: '🐛' },
-          docs: {
-            description: 'Documentation only changes',
-            title: 'Documentation',
-            emoji: '📚',
-          },
-          style: {
-            description: 'Changes that do not affect meaning of the code',
-            title: 'Styles',
-            emoji: '💎',
-          },
-          refactor: {
-            description: 'Code refactoring',
-            title: 'Code Refactoring',
-            emoji: '📦',
-          },
-          perf: {
-            description: 'Performance improvements',
-            title: 'Performance Improvements',
-            emoji: '🚀',
-          },
-          test: {
-            description: 'Adding or fixing tests',
-            title: 'Tests',
-            emoji: '🚨',
-          },
-          build: {
-            description: 'Changes that affect build system',
-            title: 'Builds',
-            emoji: '🛠',
-          },
-          ci: {
-            description: 'Changes to CI config',
-            title: 'Continuous Integrations',
-            emoji: '⚙️',
-          },
-          chore: { description: 'Other changes', title: 'Chores', emoji: '♻️' },
-          revert: {
-            description: 'Reverts a previous commit',
-            title: 'Reverts',
-            emoji: '🗑',
-          },
-        },
-      },
-      scope: {
-        description:
-          'Select the scope(s) of the change (use arrow keys or space to select multiple)',
-        enum: scopesEnum,
-      },
-      subject: {
-        description:
-          'Write a short, imperative tense description of the change',
-      },
-      body: { description: 'Provide a longer description of the change' },
-      isBreaking: { description: 'Are there any breaking changes?' },
-      breakingBody: { description: 'Describe the breaking changes with body' },
-      breaking: { description: 'Describe the breaking changes' },
-      isIssueAffected: {
-        description: 'Does this change affect any open issues?',
-      },
-      issuesBody: {
-        description: 'If issues are closed, enter longer description',
-      },
-      issues: { description: 'Add issue references (e.g., "fix #123")' },
-    },
-  },
+  rules,
+  prompt,
 };
 
 export default config;

package/src/lib/find-git-root.ts

@@ -0,0 +1,31 @@
+/**
+ * @file find-git-root.ts
+ * Utility to locate the root directory of a git repository.
+ */
+
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Finds the git root directory by traversing upwards from startDir.
+ *
+ * @param startDir - Directory to start searching from (defaults to process.cwd()).
+ * @returns Path to git root directory, or null if not within a git repository.
+ * @example
+ * ```ts
+ * const root = findGitRoot();
+ * ```
+ */
+export function findGitRoot(startDir: string = process.cwd()): string | null {
+  let current = path.resolve(startDir);
+  while (true) {
+    if (existsSync(path.join(current, '.git'))) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}

package/src/lib/get-scope-description.ts

@@ -0,0 +1,38 @@
+/**
+ * @file get-scope-description.ts
+ * Formats user-facing description strings for commit scopes.
+ */
+
+/**
+ * Scope identifier for workspace-level changes.
+ */
+const SCOPE_WORKSPACE = 'workspace';
+
+/**
+ * Scope identifier for release commits.
+ */
+const SCOPE_RELEASE = 'release';
+
+/**
+ * Returns a human-readable description for a given commit scope.
+ *
+ * @param scope - The scope identifier.
+ * @returns The description string for the scope.
+ * @example
+ * ```ts
+ * getScopeDescription('workspace');
+ * // 'workspace scope - root files such as config files, root package.json, etc'
+ * getScopeDescription('release');
+ * // 'Special scope for release commits'
+ * getScopeDescription('my-package');
+ * // 'my-package scope'
+ * ```
+ */
+export function getScopeDescription(scope: string): string {
+  if (scope === SCOPE_WORKSPACE) {
+    return 'workspace scope - root files such as config files, root package.json, etc';
+  }
+  return scope === SCOPE_RELEASE
+    ? 'Special scope for release commits'
+    : `${scope} scope`;
+}

package/src/lib/get-scopes.ts

@@ -0,0 +1,89 @@
+/**
+ * @file get-scopes.ts
+ * Discovers and gathers workspace package scopes in a monorepo or standard repository.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import fg from 'fast-glob';
+
+import { findGitRoot } from './find-git-root.js';
+import { getWorkspacesRawPath } from './get-workspaces-raw-path.js';
+
+/**
+ * Retrieves a list of package scope names from monorepo configuration files (npm, pnpm, lerna).
+ *
+ * @param cwd - Working directory to start git root discovery from (defaults to process.cwd()).
+ * @returns An array of package scope names found in the repository.
+ * @example
+ * ```ts
+ * const scopes = getScopes();
+ * ```
+ */
+export function getScopes(cwd: string = process.cwd()): string[] {
+  const root = findGitRoot(cwd);
+
+  if (!root) {
+    throw new Error('[FATAL] Not a repository.');
+  }
+
+  const rawWorkspaces: string[] = [];
+
+  const packageJsonPath = path.join(root, 'package.json');
+  rawWorkspaces.push(
+    ...getWorkspacesRawPath(packageJsonPath, 'json', 'workspaces')
+  );
+
+  const pnpmWorkspaceYamlPath = path.join(root, 'pnpm-workspace.yaml');
+  rawWorkspaces.push(
+    ...getWorkspacesRawPath(pnpmWorkspaceYamlPath, 'yaml', 'packages')
+  );
+
+  const pnpmWorkspaceYmlPath = path.join(root, 'pnpm-workspace.yml');
+  rawWorkspaces.push(
+    ...getWorkspacesRawPath(pnpmWorkspaceYmlPath, 'yaml', 'packages')
+  );
+
+  const lernaJsonPath = path.join(root, 'lerna.json');
+  rawWorkspaces.push(
+    ...getWorkspacesRawPath(lernaJsonPath, 'json', 'packages')
+  );
+
+  const workspaces = new Set<string>();
+
+  const rootPackageJsonPath = path.join(root, 'package.json');
+  if (existsSync(rootPackageJsonPath) && !rawWorkspaces.includes('.')) {
+    rawWorkspaces.push('.');
+  }
+
+  for (const pattern of rawWorkspaces) {
+    const entries = fg.sync(pattern, {
+      cwd: root,
+      onlyDirectories: true,
+      absolute: true,
+    });
+
+    for (const dirPath of entries) {
+      const packageJsonPath = path.join(dirPath, 'package.json');
+
+      if (existsSync(packageJsonPath)) {
+        try {
+          const package_ = JSON.parse(
+            readFileSync(packageJsonPath, 'utf8')
+          ) as {
+            name?: string;
+          };
+
+          if (package_.name) {
+            workspaces.add(package_.name);
+          }
+        } catch {
+          // ignore invalid package.json files
+        }
+      }
+    }
+  }
+
+  return [...workspaces];
+}

package/src/lib/get-workspaces-raw-path.ts

@@ -0,0 +1,53 @@
+/**
+ * @file get-workspaces-raw-path.ts
+ * Parser for extracting workspace path globs from JSON and YAML configuration files.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+
+import { load } from 'js-yaml';
+
+/**
+ * Reads workspace paths from configuration files (JSON or YAML).
+ *
+ * @param configPath - The path to the config file (e.g., package.json, pnpm-workspace.yaml).
+ * @param parser - The parser type to use for reading the file ('json' or 'yaml').
+ * @param property - The property name in the config containing workspace paths (defaults to 'workspaces').
+ * @returns Array of raw workspace path patterns.
+ * @example
+ * ```ts
+ * getWorkspacesRawPath('package.json', 'json', 'workspaces');
+ * getWorkspacesRawPath('pnpm-workspace.yaml', 'yaml', 'packages');
+ * ```
+ */
+export function getWorkspacesRawPath(
+  configPath: string,
+  parser: 'json' | 'yaml',
+  property: string = 'workspaces'
+): string[] {
+  const rawWorkspacesPaths: string[] = [];
+
+  if (existsSync(configPath)) {
+    const asString = readFileSync(configPath, 'utf8');
+
+    let parsed: Record<string, unknown>;
+
+    if (parser === 'json') {
+      parsed = JSON.parse(asString);
+    } else if (parser === 'yaml') {
+      parsed = load(asString) as Record<string, unknown>;
+    } else {
+      throw new Error(`Unsupported parser type: ${parser}`);
+    }
+
+    const workspaces = parsed[property];
+
+    if (Array.isArray(workspaces)) {
+      for (const project of workspaces) {
+        rawWorkspacesPaths.push(project);
+      }
+    }
+  }
+
+  return rawWorkspacesPaths;
+}

package/src/lib/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @file index.ts
+ * Barrel export for atomic utility functions in commitlint-config-spellbookx.
+ */
+
+export { findGitRoot } from './find-git-root.js';
+export { getScopeDescription } from './get-scope-description.js';
+export { getScopes } from './get-scopes.js';
+export { getWorkspacesRawPath } from './get-workspaces-raw-path.js';
+export { packageJson } from './package-json.js';

package/src/lib/package-json.ts

@@ -0,0 +1,22 @@
+/**
+ * @file package-json.ts
+ * Reads package metadata for commitlint-config-spellbookx.
+ */
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath, URL } from 'node:url';
+
+const packagePath = fileURLToPath(
+  new URL('../../package.json', import.meta.url)
+);
+
+/**
+ * Parsed `package.json` metadata for `commitlint-config-spellbookx`.
+ */
+export const packageJson = JSON.parse(readFileSync(packagePath, 'utf8')) as {
+  name: string;
+  version: string;
+  peerDependencies: Record<string, string>;
+};
+
+export default packageJson;

package/src/prompt.ts

@@ -0,0 +1,99 @@
+/**
+ * @file prompt.ts
+ * Commitizen prompt questions and settings for interactive commits with cz-git.
+ */
+
+import type { UserConfig } from '@commitlint/types';
+
+import { scopesEnum } from './scopes.js';
+
+/**
+ * Commitizen and cz-git interactive prompt configuration.
+ */
+export const prompt: UserConfig['prompt'] = {
+  settings: {
+    enableMultipleScopes: true,
+    scopeEnumSeparator: ',',
+  },
+  messages: {
+    skip: ':skip',
+    max: 'upper %d chars',
+    min: '%d chars at least',
+    emptyWarning: 'can not be empty',
+    upperLimitWarning: 'over limit',
+    lowerLimitWarning: 'below limit',
+  },
+  questions: {
+    type: {
+      description: "Select the type of change that you're committing:",
+      enum: {
+        feat: {
+          description: 'A new feature',
+          title: 'Features',
+          emoji: '✨',
+        },
+        fix: { description: 'A bug fix', title: 'Bug Fixes', emoji: '🐛' },
+        docs: {
+          description: 'Documentation only changes',
+          title: 'Documentation',
+          emoji: '📚',
+        },
+        style: {
+          description: 'Changes that do not affect meaning of the code',
+          title: 'Styles',
+          emoji: '💎',
+        },
+        refactor: {
+          description: 'Code refactoring',
+          title: 'Code Refactoring',
+          emoji: '📦',
+        },
+        perf: {
+          description: 'Performance improvements',
+          title: 'Performance Improvements',
+          emoji: '🚀',
+        },
+        test: {
+          description: 'Adding or fixing tests',
+          title: 'Tests',
+          emoji: '🚨',
+        },
+        build: {
+          description: 'Changes that affect build system',
+          title: 'Builds',
+          emoji: '🛠',
+        },
+        ci: {
+          description: 'Changes to CI config',
+          title: 'Continuous Integrations',
+          emoji: '⚙️',
+        },
+        chore: { description: 'Other changes', title: 'Chores', emoji: '♻️' },
+        revert: {
+          description: 'Reverts a previous commit',
+          title: 'Reverts',
+          emoji: '🗑',
+        },
+      },
+    },
+    scope: {
+      description:
+        'Select the scope(s) of the change (use arrow keys or space to select multiple)',
+      enum: scopesEnum,
+    },
+    subject: {
+      description: 'Write a short, imperative tense description of the change',
+    },
+    body: { description: 'Provide a longer description of the change' },
+    isBreaking: { description: 'Are there any breaking changes?' },
+    breakingBody: { description: 'Describe the breaking changes with body' },
+    breaking: { description: 'Describe the breaking changes' },
+    isIssueAffected: {
+      description: 'Does this change affect any open issues?',
+    },
+    issuesBody: {
+      description: 'If issues are closed, enter longer description',
+    },
+    issues: { description: 'Add issue references (e.g., "fix #123")' },
+  },
+};

package/src/rules.ts

@@ -0,0 +1,22 @@
+/**
+ * @file rules.ts
+ * Commitlint rule definitions for enforcing conventional commits.
+ */
+
+import type { QualifiedRules } from '@commitlint/types';
+
+import { COMMIT_TYPES } from './constants/commit-types.js';
+import { scopesArray } from './scopes.js';
+
+/**
+ * Standard commitlint rules configuration.
+ */
+export const rules: QualifiedRules = {
+  'type-enum': [2, 'always', [...COMMIT_TYPES]],
+  'scope-enum': [2, 'always', scopesArray],
+  'subject-empty': [2, 'never'],
+  'subject-full-stop': [2, 'never', '.'],
+  'header-max-length': [2, 'always', 72],
+  'body-max-line-length': [2, 'always', 100],
+  'footer-max-line-length': [2, 'always', 100],
+};

package/src/scopes.ts

@@ -0,0 +1,40 @@
+/**
+ * @file scopes.ts
+ * Scopes constants and scope enumeration generator for commitlint and commitizen.
+ */
+
+import { getScopeDescription } from './lib/get-scope-description.js';
+import { getScopes } from './lib/get-scopes.js';
+
+/**
+ * Scope identifier for repository-wide or workspace-level changes.
+ */
+export const SCOPE_WORKSPACE = 'workspace';
+
+/**
+ * Scope identifier for release and versioning commits.
+ */
+export const SCOPE_RELEASE = 'release';
+
+/**
+ * Array of all valid commit scopes, including workspace, release, and discovered monorepo packages.
+ */
+export const scopesArray: string[] = [
+  SCOPE_WORKSPACE,
+  SCOPE_RELEASE,
+  ...getScopes(),
+];
+
+/**
+ * Record of scopes mapped to their human-readable descriptions for Commitizen interactive prompt.
+ */
+export const scopesEnum: Record<string, { description: string }> = {};
+
+for (const scope of scopesArray) {
+  Object.defineProperty(scopesEnum, scope, {
+    value: { description: getScopeDescription(scope) },
+    enumerable: true,
+    writable: true,
+    configurable: true,
+  });
+}

package/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "extends": "@dcdavidev/tsconfig/base.json",
   "compilerOptions": {
+    "types": ["node"],
     "outDir": "./dist",
     "rootDir": "./src",
     "tsBuildInfoFile": "./dist/.tsbuildinfo",