@markuplint/create-rule 5.0.0-rc.4 → 5.0.0-rc.5

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.0.0-rc.5](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.4...v5.0.0-rc.5) (2026-08-28)
+
+### Code Refactoring
+
+- **rules:** redesign v5 rule system — naming, splits, specConformance ([#3989](https://github.com/markuplint/markuplint/issues/3989)) ([e925565](https://github.com/markuplint/markuplint/commit/e925565ce537848d7d1573369723cbce724a841b)), closes [#4](https://github.com/markuplint/markuplint/issues/4) [#aside-conditional-role-mapping-aria-13](https://github.com/markuplint/markuplint/issues/aside-conditional-role-mapping-aria-13)
+
+### BREAKING CHANGES
+
+- **rules:** with no alias coverage.
+
 # [5.0.0-rc.4](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.3...v5.0.0-rc.4) (2026-04-19)
 
 **Note:** Version bump only for package @markuplint/create-rule

package/README.md

@@ -50,7 +50,7 @@ $ npx @markuplint/create-rule -p project -n my-plugin -r no-empty-alt --json
 | `--json`               |       | Output result as JSON                    | `false`                          |
 | `--help`               | `-h`  | Show help message                        |                                  |
 
-Available categories: `validation`, `a11y`, `naming-convention`, `maintainability`, `style`
+Available categories: `syntax`, `structure`, `attributes`, `references`, `forms`, `a11y`, `style`, `maintainability`, `compat`
 
 > When contributing to core (`--purpose core`), `--lang` is always TypeScript and `--test` is always enabled regardless of the options provided.
 
@@ -73,7 +73,7 @@ The CLI asks questions in the following order:
 3. **Rule name** — The kebab-case name of the rule (e.g., `no-empty-alt`)
 4. **Core-only questions** (contribute to core only):
    - Description
-   - Category (`validation`, `a11y`, `naming-convention`, `maintainability`, `style`)
+   - Category (`syntax`, `structure`, `attributes`, `references`, `forms`, `a11y`, `style`, `maintainability`, `compat`)
    - Severity (`error` or `warning`)
 5. **Language** — TypeScript or JavaScript (core mode always uses TypeScript)
 6. **Tests** — Whether to generate test files (core mode always includes tests)

package/lib/cli.js

@@ -4,16 +4,23 @@ import { input, installModule, select, confirm, font, header, xterm } from '@mar
 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 CATEGORIES = [
+    'syntax',
+    'structure',
+    'attributes',
+    'references',
+    'forms',
+    'a11y',
+    'style',
+    'maintainability',
+    'compat',
+];
 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: '📜',
@@ -21,9 +28,6 @@ const icons = {
     package: '🎁',
     tsconfig: '💎',
 };
-/**
- * Prints the CLI usage information, options, and examples to stdout.
- */
 function printHelp() {
     process.stdout.write(`
 Usage: create-rule [options]
@@ -40,8 +44,8 @@ Options:
       --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
+                               syntax, structure, attributes, references,
+                               forms, a11y, style, maintainability, compat
   -s, --severity <level>     Severity: error or warning (required for core)
       --json                 Output result as JSON
   -h, --help                 Show this help message
@@ -58,16 +62,11 @@ Examples:
 `);
 }
 /**
- * Sentinel class thrown when `--help` is requested to signal a
- * successful early exit without using `process.exit`.
+ * Sentinel for a successful early exit on `--help`, avoiding `process.exit`.
  */
 class HelpRequested {
     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.`);
@@ -75,10 +74,8 @@ class UsageHintError extends Error {
     }
 }
 /**
- * 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).
+ * @returns The parsed parameters, 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.
  */
@@ -212,14 +209,6 @@ export async function createRule() {
         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) {
@@ -250,13 +239,6 @@ async function createRuleNonInteractive(params, json) {
         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');
@@ -281,11 +263,15 @@ async function createRuleInteractive() {
             category: await select({
                 message: 'Category:',
                 choices: [
-                    { name: 'Conformance checking', value: 'validation' },
+                    { name: 'Syntax', value: 'syntax' },
+                    { name: 'Structure', value: 'structure' },
+                    { name: 'Attributes', value: 'attributes' },
+                    { name: 'References', value: 'references' },
+                    { name: 'Forms', value: 'forms' },
                     { name: 'Accessibility', value: 'a11y' },
-                    { name: 'Naming Convention', value: 'naming-convention' },
-                    { name: 'Maintainability', value: 'maintainability' },
                     { name: 'Style', value: 'style' },
+                    { name: 'Maintainability', value: 'maintainability' },
+                    { name: 'Browser Compatibility', value: 'compat' },
                 ],
             }),
             severity: await select({
@@ -318,14 +304,6 @@ async function createRuleInteractive() {
         await installModule(result.devDependencies, true);
     }
 }
-/**
- * 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}`);

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

@@ -1,8 +1,3 @@
-/**
- * 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,8 +1,3 @@
-/**
- * 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 {
     name = 'CreateRuleHelperError';
 }

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

@@ -1,9 +1,2 @@
 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,13 +1,6 @@
 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,13 +1,2 @@
 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,17 +2,6 @@ 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);

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

@@ -1,22 +1,3 @@
 import type { CreateRuleCreatorParams, CreateRuleHelperResult } from './types.js';
-/**
- * Scaffolds a new rule within the markuplint core rules directory.
- *
- * Creates the rule in the `packages/@markuplint/rules/src/<ruleName>` directory
- * of the monorepo. Requires core-specific parameters (description, category, severity)
- * and always uses TypeScript with tests enabled.
- *
- * @param params - The rule creation parameters. The `core` property is required.
- * @returns The scaffold result containing generated files and dependencies.
- * @throws {CreateRuleHelperError} If core options are not defined or a rule with the same name already exists.
- */
 export declare function createRuleToCore({ ruleName, core }: CreateRuleCreatorParams): Promise<CreateRuleHelperResult>;
-/**
- * Resolves the absolute path to the core rules source directory within the
- * markuplint monorepo. Searches upward from the cwd for the repository root
- * and then constructs the path to `packages/@markuplint/rules/src`.
- *
- * @returns The absolute path to the core rules directory.
- * @throws {CreateRuleHelperError} If the monorepo root or the core rules directory is not found.
- */
 export declare function getRulesDir(): Promise<string>;

package/lib/create-rule-to-core.js

@@ -3,21 +3,7 @@ import { CreateRuleHelperError } from './create-rule-helper-error.js';
 import { fsExists } from './fs-exists.js';
 import { installScaffold } from './install-scaffold.js';
 import { searchCoreRepository } from './search-core-repository.js';
-/**
- * Relative path segments from the monorepo root to the core rules source directory.
- */
 const rulesRelDir = ['packages', '@markuplint', 'rules', 'src'];
-/**
- * Scaffolds a new rule within the markuplint core rules directory.
- *
- * Creates the rule in the `packages/@markuplint/rules/src/<ruleName>` directory
- * of the monorepo. Requires core-specific parameters (description, category, severity)
- * and always uses TypeScript with tests enabled.
- *
- * @param params - The rule creation parameters. The `core` property is required.
- * @returns The scaffold result containing generated files and dependencies.
- * @throws {CreateRuleHelperError} If core options are not defined or a rule with the same name already exists.
- */
 export async function createRuleToCore({ ruleName, core }) {
     if (!core) {
         throw new CreateRuleHelperError('Core options are not defined');
@@ -36,14 +22,6 @@ export async function createRuleToCore({ ruleName, core }) {
         core,
     });
 }
-/**
- * Resolves the absolute path to the core rules source directory within the
- * markuplint monorepo. Searches upward from the cwd for the repository root
- * and then constructs the path to `packages/@markuplint/rules/src`.
- *
- * @returns The absolute path to the core rules directory.
- * @throws {CreateRuleHelperError} If the monorepo root or the core rules directory is not found.
- */
 export async function getRulesDir() {
     const rootDir = await searchCoreRepository();
     if (!rootDir) {

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

@@ -1,10 +1,2 @@
 import type { CreateRuleCreatorParams, CreateRuleHelperResult } from './types.js';
-/**
- * Scaffolds a new markuplint rule as a local plugin directory within the
- * current project. Creates a new directory named after the plugin in the cwd.
- *
- * @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 target plugin directory already exists.
- */
 export declare function createRuleToProject({ pluginName, ruleName, lang, needTest, }: CreateRuleCreatorParams): Promise<CreateRuleHelperResult>;

package/lib/create-rule-to-project.js

@@ -2,14 +2,6 @@ import path from 'node:path';
 import { CreateRuleHelperError } from './create-rule-helper-error.js';
 import { fsExists } from './fs-exists.js';
 import { installScaffold } from './install-scaffold.js';
-/**
- * Scaffolds a new markuplint rule as a local plugin directory within the
- * current project. Creates a new directory named after the plugin in the cwd.
- *
- * @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 target plugin directory already exists.
- */
 export async function createRuleToProject({ pluginName, ruleName, lang, needTest, }) {
     const pluginDir = path.resolve(process.cwd(), pluginName);
     if (await fsExists(pluginDir)) {

package/lib/fs-exists.d.ts

@@ -1,10 +1 @@
-/**
- * Checks whether a file or directory exists at the given path.
- *
- * Uses `fs.stat` internally and treats `ENOENT` errors as a non-existent path.
- * Any other filesystem errors are re-thrown.
- *
- * @param path - The absolute or relative filesystem path to check.
- * @returns `true` if the path exists, `false` otherwise.
- */
 export declare function fsExists(path: string): Promise<boolean>;

package/lib/fs-exists.js

@@ -1,13 +1,4 @@
 import { stat } from 'node:fs/promises';
-/**
- * Checks whether a file or directory exists at the given path.
- *
- * Uses `fs.stat` internally and treats `ENOENT` errors as a non-existent path.
- * Any other filesystem errors are re-thrown.
- *
- * @param path - The absolute or relative filesystem path to check.
- * @returns `true` if the path exists, `false` otherwise.
- */
 export async function fsExists(path) {
     const res = await stat(path).catch(error => {
         if (error?.code === 'ENOENT') {

package/lib/glob.d.ts

@@ -1,10 +1,5 @@
 /**
- * Cross-platform glob wrapper that normalizes path separators before matching.
- *
  * Converts backslashes (Windows `path.sep`) to forward slashes so that
  * glob patterns work consistently across operating systems.
- *
- * @param pattern - The glob pattern to match against (may contain OS-specific separators).
- * @returns An array of file paths matching the pattern.
  */
 export declare const glob: (pattern: string) => Promise<string[]>;

package/lib/glob.js

@@ -1,13 +1,8 @@
 import path from 'node:path';
 import { glob as origin } from 'glob';
 /**
- * Cross-platform glob wrapper that normalizes path separators before matching.
- *
  * Converts backslashes (Windows `path.sep`) to forward slashes so that
  * glob patterns work consistently across operating systems.
- *
- * @param pattern - The glob pattern to match against (may contain OS-specific separators).
- * @returns An array of file paths matching the pattern.
  */
 export const glob = async (pattern) => {
     const normalized = pattern.split(path.sep).join('/');

package/lib/install-scaffold.d.ts

@@ -1,18 +1,4 @@
 import type { CreateRuleCreatorParams, CreateRuleHelperResult } from './types.js';
-/**
- * Installs scaffold template files to the destination directory and optionally
- * generates a `package.json` with appropriate scripts and dependency declarations.
- *
- * This is the low-level function used by all scaffold strategies (core, project, package).
- * It copies template files from the built-in `scaffold/<type>` directory, applies
- * placeholder replacements, and sets up the project structure.
- *
- * @param scaffoldType - The type of scaffold to install ("core", "project", or "package").
- * @param dest - The absolute path to the destination directory.
- * @param params - The creation parameters, extended with an optional `packageJson` flag
- *                 indicating whether to generate a `package.json` file.
- * @returns The scaffold result containing the list of generated files and dependency arrays.
- */
 export declare function installScaffold(scaffoldType: 'core' | 'project' | 'package', dest: string, params: CreateRuleCreatorParams & {
     readonly packageJson?: boolean;
 }): Promise<CreateRuleHelperResult>;

package/lib/install-scaffold.js

@@ -2,20 +2,6 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fsExists } from './fs-exists.js';
 import { transfer } from './transfer.js';
-/**
- * Installs scaffold template files to the destination directory and optionally
- * generates a `package.json` with appropriate scripts and dependency declarations.
- *
- * This is the low-level function used by all scaffold strategies (core, project, package).
- * It copies template files from the built-in `scaffold/<type>` directory, applies
- * placeholder replacements, and sets up the project structure.
- *
- * @param scaffoldType - The type of scaffold to install ("core", "project", or "package").
- * @param dest - The absolute path to the destination directory.
- * @param params - The creation parameters, extended with an optional `packageJson` flag
- *                 indicating whether to generate a `package.json` file.
- * @returns The scaffold result containing the list of generated files and dependency arrays.
- */
 export async function installScaffold(scaffoldType, dest, params) {
     const exists = await fsExists(dest);
     if (!exists) {

package/lib/is-markuplint-repo.d.ts

@@ -1,8 +1,4 @@
 /**
- * Determines whether the current working directory is inside the markuplint
- * core monorepo. This is used to conditionally offer the "Contribute to core"
- * option in the CLI wizard.
- *
- * @returns `true` if the cwd is within the markuplint monorepo, `false` otherwise.
+ * Used to conditionally offer the "Contribute to core" option in the CLI wizard.
  */
 export declare function isMarkuplintRepo(): Promise<boolean>;

package/lib/is-markuplint-repo.js

@@ -1,10 +1,6 @@
 import { searchCoreRepository } from './search-core-repository.js';
 /**
- * Determines whether the current working directory is inside the markuplint
- * core monorepo. This is used to conditionally offer the "Contribute to core"
- * option in the CLI wizard.
- *
- * @returns `true` if the cwd is within the markuplint monorepo, `false` otherwise.
+ * Used to conditionally offer the "Contribute to core" option in the CLI wizard.
  */
 export async function isMarkuplintRepo() {
     const rootDir = await searchCoreRepository();

package/lib/read-package-json.d.ts

@@ -1,8 +1 @@
-/**
- * Reads the `package.json` file in the given directory and extracts the package name.
- *
- * @param dir - The directory containing the `package.json` file.
- * @returns The `name` field from the package.json, or `null` if the file
- *          does not exist, cannot be parsed, or has no `name` field.
- */
 export declare function readPackageJson(dir: string): Promise<string | null>;

package/lib/read-package-json.js

@@ -1,12 +1,5 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-/**
- * Reads the `package.json` file in the given directory and extracts the package name.
- *
- * @param dir - The directory containing the `package.json` file.
- * @returns The `name` field from the package.json, or `null` if the file
- *          does not exist, cannot be parsed, or has no `name` field.
- */
 export async function readPackageJson(dir) {
     const filePath = path.resolve(dir, 'package.json');
     try {

package/lib/search-core-repository.d.ts

@@ -1,9 +1 @@
-/**
- * Searches for the markuplint core monorepo root by traversing up from the
- * current working directory. Identifies the root by checking for a
- * `package.json` with the name `"markuplint-packages"`.
- *
- * @returns The absolute path to the monorepo root directory, or `null` if
- *          the current working directory is not within the markuplint repository.
- */
 export declare function searchCoreRepository(): Promise<string | null>;

package/lib/search-core-repository.js

@@ -1,13 +1,5 @@
 import path from 'node:path';
 import { readPackageJson } from './read-package-json.js';
-/**
- * Searches for the markuplint core monorepo root by traversing up from the
- * current working directory. Identifies the root by checking for a
- * `package.json` with the name `"markuplint-packages"`.
- *
- * @returns The absolute path to the monorepo root directory, or `null` if
- *          the current working directory is not within the markuplint repository.
- */
 export async function searchCoreRepository() {
     const paths = path.resolve(process.cwd()).split(path.sep);
     while (true) {

package/lib/transfer.d.ts

@@ -1,27 +1,13 @@
 import type { File } from './types.js';
-/**
- * Options controlling how scaffold files are transferred to their destination.
- */
 type TransferOptions = {
-    /** Whether to transpile TypeScript files to JavaScript. */
     readonly transpile?: boolean;
-    /** Whether to include test files in the transfer. */
     readonly test?: boolean;
-    /** A mapping of placeholder names to replacement values for template substitution. */
     readonly replacer?: Readonly<Record<string, string | void>>;
 };
 /**
- * Transfers scaffold template files from a source directory to a destination directory.
- *
- * Scans all files in `baseDir`, processes each file through template substitution,
- * optional TypeScript-to-JavaScript transpilation, and Prettier formatting, then
- * writes the results to `destDir`.
- *
- * @param scaffoldType - The type of scaffold being transferred ("core", "project", or "package").
- * @param baseDir - The source directory containing scaffold template files.
- * @param destDir - The destination directory where processed files will be written.
- * @param options - Optional settings for transpilation, test inclusion, and placeholder replacement.
- * @returns An array of file metadata for each successfully transferred file.
+ * Template authoring constraint: because users may choose JavaScript output, every
+ * `.ts` template under `scaffold/` must remain a correct example after `tsc.transpile()`
+ * strips its type syntax.
  */
 export declare function transfer(scaffoldType: 'core' | 'project' | 'package', baseDir: string, destDir: string, options?: TransferOptions): Promise<File[]>;
 export {};

package/lib/transfer.js

@@ -7,17 +7,9 @@ import { fsExists } from './fs-exists.js';
 import { glob } from './glob.js';
 const { transpile, ScriptTarget } = tsc;
 /**
- * Transfers scaffold template files from a source directory to a destination directory.
- *
- * Scans all files in `baseDir`, processes each file through template substitution,
- * optional TypeScript-to-JavaScript transpilation, and Prettier formatting, then
- * writes the results to `destDir`.
- *
- * @param scaffoldType - The type of scaffold being transferred ("core", "project", or "package").
- * @param baseDir - The source directory containing scaffold template files.
- * @param destDir - The destination directory where processed files will be written.
- * @param options - Optional settings for transpilation, test inclusion, and placeholder replacement.
- * @returns An array of file metadata for each successfully transferred file.
+ * Template authoring constraint: because users may choose JavaScript output, every
+ * `.ts` template under `scaffold/` must remain a correct example after `tsc.transpile()`
+ * strips its type syntax.
  */
 export async function transfer(scaffoldType, baseDir, destDir, options) {
     const files = await scan(baseDir, destDir);
@@ -51,7 +43,10 @@ async function transferFile(scaffoldType, file, options) {
             contents = contents.replaceAll(new RegExp(`__${before}__`, 'g'), after);
         }
     }
-    // Remove prettier ignore comment
+    // Remove prettier ignore comment.
+    // The markers exist only so that formatters do not rewrite placeholder expressions
+    // (e.g. `__ruleName__c`) inside the scaffold templates; the output is fully
+    // reformatted by Prettier below, and generated files must not inherit the markers.
     contents = contents.replace(/\n\s*\/\/ prettier-ignore/, '');
     contents = contents.replace(/\n\s*<!-- prettier-ignore(?:-(?:start|end))? -->/, '');
     const newFile = { ...file };
@@ -62,6 +57,7 @@ async function transferFile(scaffoldType, file, options) {
             target: ScriptTarget.ESNext,
         }, newFile.filePath);
         // Insert new line before comments and the export keyword
+        // to restore readability, since transpiling drops the blank lines.
         contents = contents.replaceAll(/(\n)(\s+\/\*\*|export)/g, '$1\n$2');
     }
     const candidateName = options?.replacer?.[newFile.name.replaceAll('_', '')];