@markuplint/create-rule 4.7.22 → 5.0.0-alpha.0

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

@@ -1,3 +1,22 @@
 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,7 +3,21 @@ 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');
@@ -22,6 +36,14 @@ 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,2 +1,10 @@
 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,6 +2,14 @@ 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 +1,10 @@
+/**
+ * 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,4 +1,13 @@
 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 +1,10 @@
+/**
+ * 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,5 +1,14 @@
 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('/');
     return await origin(normalized);

package/lib/install-scaffold.d.ts

@@ -1,4 +1,18 @@
 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

@@ -5,6 +5,20 @@ import { fsExists } from './fs-exists.js';
 import { transfer } from './transfer.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+/**
+ * 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 +1,8 @@
+/**
+ * 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.
+ */
 export declare function isMarkuplintRepo(): Promise<boolean>;

package/lib/is-markuplint-repo.js

@@ -1,4 +1,11 @@
 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.
+ */
 export async function isMarkuplintRepo() {
     const rootDir = await searchCoreRepository();
     return !!rootDir;

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

@@ -1 +1,8 @@
+/**
+ * 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,5 +1,12 @@
 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 +1,9 @@
+/**
+ * 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,5 +1,13 @@
 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,8 +1,27 @@
 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.
+ */
 export declare function transfer(scaffoldType: 'core' | 'project' | 'package', baseDir: string, destDir: string, options?: TransferOptions): Promise<File[]>;
 export {};

package/lib/transfer.js

@@ -6,6 +6,19 @@ import tsc from 'typescript';
 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.
+ */
 export async function transfer(scaffoldType, baseDir, destDir, options) {
     const files = await scan(baseDir, destDir);
     const results = [];

package/lib/types.d.ts

@@ -1,30 +1,72 @@
+/**
+ * Parameters for the create-rule helper, combining creator params with a purpose selection.
+ */
 export type CreateRuleHelperParams = CreateRuleCreatorParams & {
     readonly purpose: CreateRulePurpose;
 };
+/**
+ * Parameters required for scaffolding a new markuplint rule.
+ */
 export type CreateRuleCreatorParams = {
+    /** The name of the plugin that will contain the rule. */
     readonly pluginName: string;
+    /** The name of the rule to create. */
     readonly ruleName: string;
+    /** The programming language for the rule implementation. */
     readonly lang: CreateRuleLanguage;
+    /** Whether to generate test files alongside the rule. */
     readonly needTest: boolean;
+    /** Additional parameters required when contributing to core rules. */
     readonly core?: CreateRuleCreatorCoreParams;
 };
+/**
+ * Additional parameters specific to contributing a rule to the markuplint core.
+ */
 export type CreateRuleCreatorCoreParams = {
+    /** A human-readable description of what the rule checks. */
     readonly description: string;
+    /** The rule category (e.g., "validation", "a11y", "style"). */
     readonly category: string;
+    /** The default severity level for rule violations. */
     readonly severity: string;
 };
+/**
+ * The result returned after scaffolding a new rule, containing generated files and dependency information.
+ */
 export type CreateRuleHelperResult = {
+    /** The list of files that were generated. */
     readonly files: readonly File[];
+    /** Runtime dependencies to install. */
     readonly dependencies: readonly string[];
+    /** Development dependencies to install. */
     readonly devDependencies: readonly string[];
 };
+/**
+ * The programming language used for the rule implementation.
+ */
 export type CreateRuleLanguage = 'JAVASCRIPT' | 'TYPESCRIPT';
+/**
+ * The intended purpose for creating a rule, which determines the scaffolding strategy.
+ *
+ * - `ADD_TO_PROJECT` - Add the rule directly to the current project.
+ * - `PUBLISH_AS_PACKAGE` - Create a standalone publishable npm package.
+ * - `CONTRIBUTE_TO_CORE` - Add the rule to the markuplint core rules.
+ */
 export type CreateRulePurpose = 'ADD_TO_PROJECT' | 'PUBLISH_AS_PACKAGE' | 'CONTRIBUTE_TO_CORE';
+/**
+ * Metadata describing a generated file in the scaffold output.
+ */
 export type File = {
+    /** The file extension (e.g., ".ts", ".js", ".json"). */
     readonly ext: string;
+    /** The base name of the file without extension or test suffix. */
     readonly name: string;
+    /** The full file name including test suffix if applicable, but without extension. */
     readonly fileName: string;
+    /** Whether this file is a test file. */
     readonly test: boolean;
+    /** The destination directory where the file is written. */
     readonly destDir: string;
+    /** The absolute path to the source file in the scaffold. */
     readonly filePath: string;
 };

package/package.json

@@ -1,10 +1,13 @@
 {
 	"name": "@markuplint/create-rule",
-	"version": "4.7.22",
+	"version": "5.0.0-alpha.0",
 	"description": "Rule generator for markuplint",
 	"repository": "git@github.com:markuplint/markuplint.git",
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
 	"license": "MIT",
+	"engines": {
+		"node": ">=22"
+	},
 	"type": "module",
 	"exports": {
 		".": {
@@ -22,15 +25,15 @@
 		"clean": "tsc --build --clean tsconfig.build.json"
 	},
 	"dependencies": {
-		"@markuplint/cli-utils": "4.4.13",
-		"@markuplint/ml-core": "4.13.2",
-		"glob": "11.0.3",
-		"prettier": "3.6.2",
-		"typescript": "5.9.2"
+		"@markuplint/cli-utils": "5.0.0-alpha.0",
+		"@markuplint/ml-core": "5.0.0-alpha.0",
+		"glob": "13.0.6",
+		"prettier": "3.8.1",
+		"typescript": "5.9.3"
 	},
 	"devDependencies": {
 		"@types/fs-extra": "11.0.4",
-		"fs-extra": "11.3.2"
+		"fs-extra": "11.3.3"
 	},
-	"gitHead": "6213ea30269ef404f030e67bbcc7fc7443ec1060"
+	"gitHead": "13dcfc84ec83d87360c720e253383b60767e1b56"
 }

package/scaffold/package/README.md

@@ -52,8 +52,8 @@ TODO: Write a description
 
 | Property | Type       | Optional | Default Value | Description               |
 | -------- | ---------- | -------- | ------------- | ------------------------- |
-| `foo`    | `string`   | ✔       | `undefined`   | TODO: Write a description |
-| `bar`    | `number[]` | ✔       | `undefined`   | TODO: Write a description |
+| `foo`    | `string`   | ✔        | `undefined`   | TODO: Write a description |
+| `bar`    | `number[]` | ✔        | `undefined`   | TODO: Write a description |
 
 ### Default severity