@markuplint/create-rule 4.7.22 → 4.8.0

package/docs/maintenance.ja.md

@@ -0,0 +1,135 @@
+# @markuplint/create-rule メンテナンスガイド
+
+## 概要
+
+`@markuplint/create-rule` パッケージは、新しい markuplint ルールのボイラープレートファイルを生成する CLI スキャフォルディングツールです。3つのモードをサポートしています:
+
+- **プロジェクトに追加** — 現在のプロジェクトにローカルプラグインディレクトリを作成
+- **パッケージとして公開** — スタンドアロンの npm パッケージをスキャフォルド
+- **コアに貢献** — モノレポ内の `@markuplint/rules` にルールを追加
+
+### ファイル構成
+
+```
+packages/@markuplint/create-rule/
+├── bin/
+│   └── create-rule.mjs       # CLI 実行ファイル
+├── src/
+│   ├── cli.ts                 # 対話ウィザード
+│   ├── types.ts               # 型定義
+│   ├── create-rule-helper.ts  # 目的ベースルーター
+│   ├── create-rule-to-project.ts
+│   ├── create-rule-package.ts
+│   ├── create-rule-to-core.ts
+│   ├── install-scaffold.ts    # スキャフォルドインストーラー
+│   └── transfer.ts            # テンプレート処理
+└── scaffold/
+    ├── core/                  # コアルールテンプレート
+    ├── project/               # プロジェクトプラグインテンプレート
+    └── package/               # パッケージテンプレート
+```
+
+## テンプレートファイルの編集
+
+テンプレートファイルは `scaffold/{core,project,package}/` に配置されています。ユーザーが CLI を実行すると、これらのファイルがプレースホルダーを実際の値に置換してコピーされます。
+
+### プレースホルダー一覧
+
+| プレースホルダー  | 置換内容                       | 入力例         | 出力例         |
+| ----------------- | ------------------------------ | -------------- | -------------- |
+| `__pluginName__`  | プラグイン名（そのまま）       | `my-plugin`    | `my-plugin`    |
+| `__pluginName__c` | プラグイン名（キャメルケース） | `my-plugin`    | `myPlugin`     |
+| `__ruleName__`    | ルール名（そのまま）           | `no-empty-alt` | `no-empty-alt` |
+| `__ruleName__c`   | ルール名（キャメルケース）     | `no-empty-alt` | `noEmptyAlt`   |
+| `__description__` | ルールの説明（コアのみ）       | —              | —              |
+| `__category__`    | ルールカテゴリ（コアのみ）     | —              | —              |
+| `__severity__`    | デフォルト重大度（コアのみ）   | —              | —              |
+
+### キャメルケース変換
+
+`__<name>__c` サフィックスはキャメルケース変換をトリガーします。ハイフンが除去され、次の文字が大文字化されます。例えば、`__ruleName__c` に値 `no-empty-alt` を指定すると `noEmptyAlt` になります。これは生成コード内の変数名に使用されます。
+
+### ファイル名の置換
+
+テンプレートファイル名に含まれる `__ruleName__` は実際のルール名に置換されます。例えば、`rules/__ruleName__.ts` は `rules/no-empty-alt.ts` になります。
+
+### TypeScript から JavaScript へのトランスパイル
+
+ユーザーが JavaScript を選択した場合、すべての `.ts` テンプレートファイルが TypeScript コンパイラ API で `.js` にトランスパイルされます。テンプレートを編集する際は、生成される TypeScript がトランスパイル後も有効な JavaScript になることを確認してください。
+
+### Prettier フォーマット
+
+生成されるすべてのファイルは Prettier でフォーマットされます。テンプレート内の `// prettier-ignore` コメントはフォーマット前に自動削除されます。これにより、プレースホルダー式がリフォーマットされないようにテンプレート内で `// prettier-ignore` を使用できます。
+
+## CLI フローの変更
+
+対話的な質問シーケンスは `src/cli.ts` で定義されています。新しい質問を追加するには:
+
+1. `@markuplint/cli-utils` のヘルパー（`input()`、`select()`、`confirm()`）を使って質問を追加
+2. `src/types.ts` に対応する型を追加（例: `CreateRuleCreatorParams` の新しいフィールド）
+3. `createRuleHelper()` の呼び出しに値を渡す
+4. 値を `replacer` オプションに渡す必要がある場合は `install-scaffold.ts` を更新
+5. 値がスキャフォルド戦略の動作に影響する場合は、関連する戦略ファイルを更新
+
+## i18n の活用
+
+ルール実装を書く際（テンプレートでも実際のルールでも）、ハードコードされた文字列ではなく、ルールコンテキストの `t()` 翻訳関数を使用してすべてのユーザー向けメッセージを生成してください。
+
+### 翻訳関数の使い方
+
+`t()` 関数はすべてのルールの `verify` コンテキストで利用可能です:
+
+```typescript
+async verify({ document, report, t }) {
+  await document.walkOn('Element', el => {
+    report({
+      scope: el,
+      // t() で文テンプレートとキーワード引数を使用
+      message: t('{0} is {1:c}', 'attribute', 'deprecated'),
+    });
+  });
+}
+```
+
+文テンプレートとキーワードは `@markuplint/i18n` で定義されています。このアプローチには以下の利点があります:
+
+- 日本語（およびその他のサポート言語）への自動翻訳
+- すべてのルールで一貫したメッセージフォーマット
+- 補語形式のサポート（日本語の述語接続に使う `:c` フラグ）
+
+### 新しいキーワードやフレーズの追加
+
+ルールに必要なキーワードや文テンプレートが存在しない場合は、`@markuplint/i18n` に追加してください。手順は [i18n メンテナンススキル](../i18n/SKILL.md) を参照してください。主なポイント:
+
+1. キーワードを `locales/ja.json` と `$schema.json` に追加（3ファイル同期ルール）
+2. 文テンプレートは `{0}`, `{1}` プレースホルダーで設計
+3. 補語形式には `{0:c}`、翻訳スキップには `{0*}` を使用
+
+## 既存ルールの参考
+
+新しいルールを作成する際は、`packages/@markuplint/rules/src/` の既存の実装をパターンやベストプラクティスの参考にしてください。
+
+### 推奨例
+
+シンプルなルール:
+
+- `id-duplication` — 要素走査と重複検出のシンプルな実装
+- `class-naming` — 正規表現パターンを使った属性値チェック
+
+i18n を多用するルール:
+
+- `deprecated-attr` — 補語キーワード（`{0:c}`）と複数の文テンプレートを使用
+- `required-attr` — 要素/属性コンテキストでのキーワードベースメッセージを実装
+
+`packages/@markuplint/rules/src/` ディレクトリを参照して、作成しようとしているルールに類似した実装を探してください。
+
+## fix 関数について
+
+`fix` 関数は `RuleSeed` のオプションプロパティで、違反の自動修正を可能にします。しかし、多くの既存ルールでは `fix` の実装が不完全または未実装です。新しいルールを作成する際は、まず `verify` 関数に注力してください。`fix` は自動修正の動作が明確で単純な場合にのみ追加してください。
+
+## コマンドリファレンス
+
+| コマンド                                     | 説明               |
+| -------------------------------------------- | ------------------ |
+| `yarn test --scope @markuplint/create-rule`  | テスト実行         |
+| `yarn build --scope @markuplint/create-rule` | パッケージのビルド |

package/docs/maintenance.md

@@ -0,0 +1,135 @@
+# @markuplint/create-rule Maintenance Guide
+
+## Overview
+
+The `@markuplint/create-rule` package is a CLI scaffolding tool that generates boilerplate files for new markuplint rules. It supports three modes:
+
+- **Add to project** — Creates a local plugin directory in the current project
+- **Publish as package** — Scaffolds a standalone npm package
+- **Contribute to core** — Adds a rule to `@markuplint/rules` within the monorepo
+
+### File Structure
+
+```
+packages/@markuplint/create-rule/
+├── bin/
+│   └── create-rule.mjs       # CLI executable
+├── src/
+│   ├── cli.ts                 # Interactive wizard
+│   ├── types.ts               # Type definitions
+│   ├── create-rule-helper.ts  # Purpose-based router
+│   ├── create-rule-to-project.ts
+│   ├── create-rule-package.ts
+│   ├── create-rule-to-core.ts
+│   ├── install-scaffold.ts    # Scaffold installer
+│   └── transfer.ts            # Template processing
+└── scaffold/
+    ├── core/                  # Core rule templates
+    ├── project/               # Project plugin templates
+    └── package/               # Package templates
+```
+
+## Editing Template Files
+
+Template files live in `scaffold/{core,project,package}/`. When a user runs the CLI, these files are copied to the destination with placeholders replaced by actual values.
+
+### Placeholder Reference
+
+| Placeholder       | Replaced with                | Example input  | Example output |
+| ----------------- | ---------------------------- | -------------- | -------------- |
+| `__pluginName__`  | Plugin name (as-is)          | `my-plugin`    | `my-plugin`    |
+| `__pluginName__c` | Plugin name (camelCase)      | `my-plugin`    | `myPlugin`     |
+| `__ruleName__`    | Rule name (as-is)            | `no-empty-alt` | `no-empty-alt` |
+| `__ruleName__c`   | Rule name (camelCase)        | `no-empty-alt` | `noEmptyAlt`   |
+| `__description__` | Rule description (core only) | —              | —              |
+| `__category__`    | Rule category (core only)    | —              | —              |
+| `__severity__`    | Default severity (core only) | —              | —              |
+
+### CamelCase Conversion
+
+The `__<name>__c` suffix triggers camelCase conversion: hyphens are removed and the following letter is uppercased. For example, `__ruleName__c` with value `no-empty-alt` becomes `noEmptyAlt`. This is used for variable names in generated code.
+
+### File Name Replacement
+
+Template file names containing `__ruleName__` are renamed to the actual rule name. For example, `rules/__ruleName__.ts` becomes `rules/no-empty-alt.ts`.
+
+### TypeScript-to-JavaScript Transpilation
+
+When the user selects JavaScript, all `.ts` template files are transpiled to `.js` using the TypeScript compiler API. Keep this in mind when editing templates: the generated TypeScript must also produce valid JavaScript after transpilation.
+
+### Prettier Formatting
+
+All generated files are formatted with Prettier. Any `// prettier-ignore` comments in templates are automatically stripped before formatting. This means `// prettier-ignore` can be used in templates to preserve formatting of placeholder expressions that would otherwise be reformatted.
+
+## Changing the CLI Flow
+
+The interactive question sequence is defined in `src/cli.ts`. To add a new question:
+
+1. Add the question using helpers from `@markuplint/cli-utils` (`input()`, `select()`, `confirm()`)
+2. Add the corresponding type to `src/types.ts` (e.g., a new field on `CreateRuleCreatorParams`)
+3. Pass the value through the `createRuleHelper()` call
+4. Update `install-scaffold.ts` if the value needs to be passed to the `replacer` options
+5. Update the relevant scaffold strategy files if the value affects their behavior
+
+## Leveraging i18n
+
+When writing rule implementations (whether in templates or actual rules), use the `t()` translator function from the rule context for all user-facing messages rather than hardcoded strings.
+
+### Using the Translator
+
+The `t()` function is available in the `verify` context of every rule:
+
+```typescript
+async verify({ document, report, t }) {
+  await document.walkOn('Element', el => {
+    report({
+      scope: el,
+      // Use t() with a sentence template and keyword arguments
+      message: t('{0} is {1:c}', 'attribute', 'deprecated'),
+    });
+  });
+}
+```
+
+The sentence templates and keywords are defined in `@markuplint/i18n`. This approach provides:
+
+- Automatic translation to Japanese (and other supported languages)
+- Consistent message formatting across all rules
+- Complement form support (`:c` flag for Japanese predicate attachment)
+
+### Adding New Keywords or Sentences
+
+If your rule needs a keyword or sentence template that does not exist yet, add it to `@markuplint/i18n`. See the [i18n maintenance skill](../i18n/SKILL.md) for the procedure. The key points are:
+
+1. Add the keyword to `locales/ja.json` and `$schema.json` (three-file sync rule)
+2. Design sentence templates with `{0}`, `{1}` placeholders
+3. Use `{0:c}` for complement forms and `{0*}` to skip translation
+
+## Referencing Existing Rules
+
+When creating a new rule, refer to existing implementations in `packages/@markuplint/rules/src/` for patterns and best practices.
+
+### Recommended Examples
+
+Simple rules to start with:
+
+- `id-duplication` — Straightforward element traversal with duplicate detection
+- `class-naming` — Attribute value checking with regex patterns
+
+Rules with rich i18n usage:
+
+- `deprecated-attr` — Uses complement keywords (`{0:c}`) and multiple sentence templates
+- `required-attr` — Demonstrates keyword-based messages with element/attribute context
+
+Browse the `packages/@markuplint/rules/src/` directory to find rules similar to what you are building.
+
+## About the `fix` Function
+
+The `fix` function is an optional property of `RuleSeed` that enables auto-fixing violations. However, many existing rules have incomplete or missing `fix` implementations. When creating a new rule, focus on the `verify` function first. Add `fix` only if the auto-fix behavior is straightforward and well-defined.
+
+## Command Reference
+
+| Command                                      | Description       |
+| -------------------------------------------- | ----------------- |
+| `yarn test --scope @markuplint/create-rule`  | Run tests         |
+| `yarn build --scope @markuplint/create-rule` | Build the package |

package/lib/cli.d.ts

@@ -1 +1,10 @@
+/**
+ * CLI entry point for creating a new markuplint rule.
+ *
+ * Supports two modes:
+ * - **Non-interactive**: When CLI options are provided, creates the rule directly.
+ * - **Interactive**: When no options are provided, starts the guided wizard.
+ *
+ * @returns Resolves when the rule has been fully scaffolded and dependencies installed.
+ */
 export declare function createRule(): Promise<void>;

package/lib/cli.js

@@ -1,7 +1,19 @@
 import path from 'node:path';
+import { parseArgs } from 'node:util';
 import { input, installModule, select, confirm, font, header, xterm } from '@markuplint/cli-utils';
 import { createRuleHelper } from './create-rule-helper.js';
 import { isMarkuplintRepo } from './is-markuplint-repo.js';
+const KEBAB_CASE = /^[a-z][\da-z]*(?:-[a-z][\da-z]*)*$/i;
+const CATEGORIES = ['validation', 'a11y', 'naming-convention', 'maintainability', 'style'];
+const SEVERITIES = ['error', 'warning'];
+const PURPOSE_MAP = {
+    project: 'ADD_TO_PROJECT',
+    package: 'PUBLISH_AS_PACKAGE',
+    core: 'CONTRIBUTE_TO_CORE',
+};
+/**
+ * Icon mapping for scaffold output display, keyed by base file name.
+ */
 const icons = {
     README: '📝',
     index: '📜',
@@ -9,7 +21,245 @@ const icons = {
     package: '🎁',
     tsconfig: '💎',
 };
+/**
+ * Prints the CLI usage information, options, and examples to stdout.
+ */
+function printHelp() {
+    process.stdout.write(`
+Usage: create-rule [options]
+
+  Without options, starts the interactive wizard.
+  With options, creates a rule non-interactively.
+
+Options:
+  -p, --purpose <type>       Purpose: project, package, or core (required)
+  -n, --plugin-name <name>   Plugin/directory name (required for project/package)
+  -r, --rule-name <name>     Rule name in kebab-case (required)
+  -l, --lang <lang>          Language: ts or js (default: ts, ignored for core)
+  -t, --test                 Generate test files (default: true)
+      --no-test              Skip test file generation
+  -d, --description <text>   Rule description (required for core)
+  -c, --category <cat>       Category (required for core):
+                               validation, a11y, naming-convention,
+                               maintainability, style
+  -s, --severity <level>     Severity: error or warning (required for core)
+      --json                 Output result as JSON
+  -h, --help                 Show this help message
+
+Examples:
+  # Add a rule to this project
+  create-rule -p project -n my-plugin -r no-empty-alt
+
+  # Create a publishable package
+  create-rule -p package -n my-plugin -r no-empty-alt -l js --no-test
+
+  # Contribute to core
+  create-rule -p core -r no-empty-alt -d "Disallow empty alt" -c a11y -s error
+`);
+}
+/**
+ * Sentinel class thrown when `--help` is requested to signal a
+ * successful early exit without using `process.exit`.
+ */
+class HelpRequested {
+    constructor() {
+        this.code = 0;
+    }
+}
+/**
+ * Error thrown when CLI arguments are invalid or missing.
+ * Includes a usage hint directing users to `--help`.
+ */
+class UsageHintError extends Error {
+    constructor(message) {
+        super(`${message}\nRun 'create-rule --help' for usage.`);
+        this.name = 'UsageHintError';
+    }
+}
+/**
+ * Parses `process.argv` into validated {@link CreateRuleHelperParams}.
+ *
+ * @returns The parsed parameters and output format flag, or `null` when
+ *          no arguments are provided (indicating interactive mode).
+ * @throws {HelpRequested} When `--help` is passed.
+ * @throws {UsageHintError} When required options are missing or values are invalid.
+ */
+function parseCliArgs() {
+    const { values } = parseArgs({
+        options: {
+            purpose: { type: 'string', short: 'p' },
+            'plugin-name': { type: 'string', short: 'n' },
+            'rule-name': { type: 'string', short: 'r' },
+            lang: { type: 'string', short: 'l' },
+            test: { type: 'boolean', short: 't', default: true },
+            'no-test': { type: 'boolean', default: false },
+            description: { type: 'string', short: 'd' },
+            category: { type: 'string', short: 'c' },
+            severity: { type: 'string', short: 's' },
+            json: { type: 'boolean', default: false },
+            help: { type: 'boolean', short: 'h', default: false },
+        },
+        strict: true,
+    });
+    if (values.help) {
+        printHelp();
+        throw new HelpRequested();
+    }
+    // No arguments → interactive mode
+    if (!values.purpose && !values['rule-name'] && !values['plugin-name']) {
+        return null;
+    }
+    // Validate purpose
+    if (!values.purpose) {
+        throw new UsageHintError('--purpose is required in non-interactive mode');
+    }
+    const purpose = PURPOSE_MAP[values.purpose];
+    if (!purpose) {
+        throw new UsageHintError(`Invalid --purpose "${values.purpose}". Must be one of: project, package, core`);
+    }
+    // Validate rule name
+    if (!values['rule-name']) {
+        throw new UsageHintError('--rule-name is required');
+    }
+    const ruleName = values['rule-name'];
+    if (!KEBAB_CASE.test(ruleName)) {
+        throw new UsageHintError(`Invalid --rule-name "${ruleName}". Must be kebab-case (e.g., "no-empty-alt")`);
+    }
+    // Validate plugin name
+    let pluginName = '';
+    if (purpose !== 'CONTRIBUTE_TO_CORE') {
+        if (!values['plugin-name']) {
+            throw new UsageHintError('--plugin-name is required for project/package purpose');
+        }
+        pluginName = values['plugin-name'];
+        if (!KEBAB_CASE.test(pluginName)) {
+            throw new UsageHintError(`Invalid --plugin-name "${pluginName}". Must be kebab-case (e.g., "my-plugin")`);
+        }
+    }
+    // Language
+    let lang;
+    if (purpose === 'CONTRIBUTE_TO_CORE') {
+        lang = 'TYPESCRIPT';
+    }
+    else {
+        switch (values.lang ?? 'ts') {
+            case 'ts': {
+                lang = 'TYPESCRIPT';
+                break;
+            }
+            case 'js': {
+                lang = 'JAVASCRIPT';
+                break;
+            }
+            default: {
+                throw new UsageHintError(`Invalid --lang "${values.lang}". Must be "ts" or "js"`);
+            }
+        }
+    }
+    // Test
+    const needTest = purpose === 'CONTRIBUTE_TO_CORE' ? true : !values['no-test'];
+    // Core-specific params
+    let core;
+    if (purpose === 'CONTRIBUTE_TO_CORE') {
+        if (!values.description) {
+            throw new UsageHintError('--description is required for core purpose');
+        }
+        if (!values.category) {
+            throw new UsageHintError('--category is required for core purpose');
+        }
+        if (!CATEGORIES.includes(values.category)) {
+            throw new UsageHintError(`Invalid --category "${values.category}". Must be one of: ${CATEGORIES.join(', ')}`);
+        }
+        if (!values.severity) {
+            throw new UsageHintError('--severity is required for core purpose');
+        }
+        if (!SEVERITIES.includes(values.severity)) {
+            throw new UsageHintError(`Invalid --severity "${values.severity}". Must be one of: ${SEVERITIES.join(', ')}`);
+        }
+        core = {
+            description: values.description,
+            category: values.category,
+            severity: values.severity,
+        };
+    }
+    return {
+        params: { purpose, pluginName, ruleName, lang, needTest, core },
+        json: values.json ?? false,
+    };
+}
+/**
+ * CLI entry point for creating a new markuplint rule.
+ *
+ * Supports two modes:
+ * - **Non-interactive**: When CLI options are provided, creates the rule directly.
+ * - **Interactive**: When no options are provided, starts the guided wizard.
+ *
+ * @returns Resolves when the rule has been fully scaffolded and dependencies installed.
+ */
 export async function createRule() {
+    let parsed;
+    try {
+        parsed = parseCliArgs();
+    }
+    catch (error) {
+        if (error instanceof HelpRequested) {
+            return;
+        }
+        throw error;
+    }
+    if (parsed) {
+        await createRuleNonInteractive(parsed.params, parsed.json);
+    }
+    else {
+        await createRuleInteractive();
+    }
+}
+/**
+ * Creates a rule non-interactively from pre-validated CLI options.
+ * Runs the scaffold, prints results (or JSON), and installs dependencies.
+ *
+ * @param params - The validated rule creation parameters.
+ * @param json - When `true`, outputs the result as JSON instead of
+ *               the human-readable file list.
+ */
+async function createRuleNonInteractive(params, json) {
+    const result = await createRuleHelper(params);
+    if (!json) {
+        process.stdout.write(header('Create a rule'));
+        process.stdout.write('\n\n');
+    }
+    if (json) {
+        const output = {
+            files: result.files.map(file => ({
+                name: file.fileName + file.ext,
+                path: path.resolve(file.destDir, file.fileName + file.ext),
+                test: file.test,
+            })),
+            dependencies: result.dependencies,
+            devDependencies: result.devDependencies,
+        };
+        process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+    }
+    else {
+        for (const file of result.files) {
+            printFile(params.pluginName || 'core', file.test ? '🖍 ' : (icons[file.name] ?? '🛡 '), file.fileName, path.resolve(file.destDir, file.fileName + file.ext));
+        }
+    }
+    if (result.dependencies.length > 0) {
+        await installModule(result.dependencies);
+    }
+    if (result.devDependencies.length > 0) {
+        await installModule(result.devDependencies, true);
+    }
+}
+/**
+ * Interactive CLI wizard for creating a new markuplint rule.
+ *
+ * Guides the user through selecting a purpose, naming the plugin and rule,
+ * choosing a language, and optionally generating tests. After scaffolding,
+ * it prints the generated files and installs any required dependencies.
+ */
+async function createRuleInteractive() {
     process.stdout.write(header('Create a rule'));
     process.stdout.write('\n');
     process.stdout.write('\n');
@@ -61,7 +311,7 @@ export async function createRule() {
     const needTest = purpose === 'CONTRIBUTE_TO_CORE' ? true : await confirm('Do you need the test?', { initial: true });
     const result = await createRuleHelper({ purpose, pluginName, ruleName, lang, needTest, core });
     for (const file of result.files) {
-        output(pluginName || 'core', file.test ? '🖍 ' : (icons[file.name] ?? '🛡 '), file.fileName, path.resolve(file.destDir, file.fileName + file.ext));
+        printFile(pluginName || 'core', file.test ? '🖍 ' : (icons[file.name] ?? '🛡 '), file.fileName, path.resolve(file.destDir, file.fileName + file.ext));
     }
     if (result.dependencies.length > 0) {
         await installModule(result.dependencies);
@@ -70,10 +320,18 @@ export async function createRule() {
         await installModule(result.devDependencies, true);
     }
 }
-function output(name, icon, title, path) {
+/**
+ * Prints a single scaffolded file entry to stdout with a check mark, icon, and file path.
+ *
+ * @param name - The plugin or module name used as a prefix.
+ * @param icon - The icon character to display next to the file name.
+ * @param title - The display title (typically the file name).
+ * @param filePath - The absolute path to the generated file.
+ */
+function printFile(name, icon, title, filePath) {
     const _marker = xterm(39)('✔') + ' ';
     const _title = (icon, title) => `${icon} ` + font.bold(`${name}/${title}`);
-    const _file = (path) => ' ' + font.cyanBright(path);
-    process.stdout.write(_marker + _title(icon, title) + _file(path));
+    const _file = (filePath) => ' ' + font.cyanBright(filePath);
+    process.stdout.write(_marker + _title(icon, title) + _file(filePath));
     process.stdout.write('\n');
 }

package/lib/create-rule-helper-error.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Custom error class for failures that occur during rule scaffolding.
+ * Thrown when preconditions are not met (e.g., directory already exists,
+ * core options missing, or repository not found).
+ */
 export declare class CreateRuleHelperError extends Error {
     name: string;
 }

package/lib/create-rule-helper-error.js

@@ -1,3 +1,8 @@
+/**
+ * Custom error class for failures that occur during rule scaffolding.
+ * Thrown when preconditions are not met (e.g., directory already exists,
+ * core options missing, or repository not found).
+ */
 export class CreateRuleHelperError extends Error {
     constructor() {
         super(...arguments);

package/lib/create-rule-helper.d.ts

@@ -1,2 +1,9 @@
 import type { CreateRuleHelperParams, CreateRuleHelperResult } from './types.js';
+/**
+ * Dispatches rule creation to the appropriate scaffolding function based on the
+ * specified purpose. Acts as the central entry point for programmatic rule creation.
+ *
+ * @param params - The helper parameters including purpose, plugin name, rule name, language, and options.
+ * @returns The scaffold result containing generated files and dependencies.
+ */
 export declare function createRuleHelper(params: CreateRuleHelperParams): Promise<CreateRuleHelperResult>;

package/lib/create-rule-helper.js

@@ -1,6 +1,13 @@
 import { createRulePackage } from './create-rule-package.js';
 import { createRuleToCore } from './create-rule-to-core.js';
 import { createRuleToProject } from './create-rule-to-project.js';
+/**
+ * Dispatches rule creation to the appropriate scaffolding function based on the
+ * specified purpose. Acts as the central entry point for programmatic rule creation.
+ *
+ * @param params - The helper parameters including purpose, plugin name, rule name, language, and options.
+ * @returns The scaffold result containing generated files and dependencies.
+ */
 export async function createRuleHelper(params) {
     switch (params.purpose) {
         case 'ADD_TO_PROJECT': {

package/lib/create-rule-package.d.ts

@@ -1,2 +1,13 @@
 import type { CreateRuleCreatorParams, CreateRuleHelperResult } from './types.js';
+/**
+ * Scaffolds a new markuplint rule as a standalone publishable npm package
+ * in the current working directory.
+ *
+ * Validates that the current directory is empty before proceeding.
+ * Generates a complete package structure including `package.json`.
+ *
+ * @param params - The rule creation parameters (plugin name, rule name, language, test preference).
+ * @returns The scaffold result containing generated files and dependencies.
+ * @throws {CreateRuleHelperError} If the current directory is not empty.
+ */
 export declare function createRulePackage({ pluginName, ruleName, lang, needTest, }: CreateRuleCreatorParams): Promise<CreateRuleHelperResult>;

package/lib/create-rule-package.js

@@ -2,6 +2,17 @@ import path from 'node:path';
 import { CreateRuleHelperError } from './create-rule-helper-error.js';
 import { glob } from './glob.js';
 import { installScaffold } from './install-scaffold.js';
+/**
+ * Scaffolds a new markuplint rule as a standalone publishable npm package
+ * in the current working directory.
+ *
+ * Validates that the current directory is empty before proceeding.
+ * Generates a complete package structure including `package.json`.
+ *
+ * @param params - The rule creation parameters (plugin name, rule name, language, test preference).
+ * @returns The scaffold result containing generated files and dependencies.
+ * @throws {CreateRuleHelperError} If the current directory is not empty.
+ */
 export async function createRulePackage({ pluginName, ruleName, lang, needTest, }) {
     const newRuleDir = path.resolve(process.cwd(), '*');
     const files = await glob(newRuleDir);