@markuplint/create-rule 4.0.0-dev.3823

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017-2023 Yusuke Hirao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @markuplint/create-rule
+
+[![npm version](https://badge.fury.io/js/%40markuplint%2Fcreate-rule.svg)](https://www.npmjs.com/package/@markuplint/create-rule)
+
+## Usage
+
+```shell
+$ npx @markuplint/create-rule <rule-name>
+```

package/bin/create-rule.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { createRule } from '../lib/cli.js';
+
+await createRule().catch(error => {
+	process.stderr.write(error + '\n');
+	process.exit(1);
+});
+process.exit(0);

package/lib/cli.d.ts

@@ -0,0 +1 @@
+export declare function createRule(): Promise<void>;

package/lib/cli.js

@@ -0,0 +1,79 @@
+import { resolve } from 'node:path';
+import { input, installModule, select, confirm, font, header } from '@markuplint/cli-utils';
+import { createRuleHelper } from './create-rule-helper.js';
+import { isMarkuplintRepo } from './is-markuplint-repo.js';
+const icons = {
+    README: '📝',
+    index: '📜',
+    schema: '⚙️ ',
+    package: '🎁',
+    tsconfig: '💎',
+};
+export async function createRule() {
+    process.stdout.write(header('Create a rule'));
+    process.stdout.write('\n');
+    process.stdout.write('\n');
+    const firstChoices = [
+        { name: 'Add the rule to this project', value: 'ADD_TO_PROJECT' },
+        { name: 'Create the rule and publish it as a package', value: 'PUBLISH_AS_PACKAGE' },
+    ];
+    if (await isMarkuplintRepo()) {
+        firstChoices.push({ name: 'Contribute the new rule to markuplint core rules', value: 'CONTRIBUTE_TO_CORE' });
+    }
+    const purpose = await select({
+        message: 'What purpose do you create the rule for?',
+        choices: firstChoices,
+    });
+    const dirQuestion = purpose === 'ADD_TO_PROJECT' ? 'What is the directory name?' : 'What is the plugin name?';
+    const pluginName = purpose === 'CONTRIBUTE_TO_CORE' ? '' : await input(dirQuestion, /^[a-z][\da-z]*(?:-[a-z][\da-z]*)*$/i);
+    const ruleName = await input('What is the rule name?', /^[a-z][\da-z]*(?:-[a-z][\da-z]*)*$/i);
+    const core = purpose === 'CONTRIBUTE_TO_CORE'
+        ? {
+            description: await input('Description:'),
+            category: await select({
+                message: 'Category:',
+                choices: [
+                    { name: 'Conformance checking', value: 'validation' },
+                    { name: 'Accessibility', value: 'a11y' },
+                    { name: 'Naming Convention', value: 'naming-convention' },
+                    { name: 'Maintainability', value: 'maintainability' },
+                    { name: 'Style', value: 'style' },
+                ],
+            }),
+            severity: await select({
+                message: 'Severity:',
+                choices: [
+                    { name: 'error', value: 'error' },
+                    { name: 'warning', value: 'warning' },
+                ],
+            }),
+        }
+        : undefined;
+    const lang = purpose === 'CONTRIBUTE_TO_CORE'
+        ? 'TYPESCRIPT'
+        : await select({
+            message: 'Which language will you implement?',
+            choices: [
+                { name: 'TypeScript', value: 'TYPESCRIPT' },
+                { name: 'JavaScript', value: 'JAVASCRIPT' },
+            ],
+        });
+    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, 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);
+    }
+}
+function output(name, icon, title, path) {
+    const _marker = font.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));
+    process.stdout.write('\n');
+}

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

@@ -0,0 +1,3 @@
+export declare class CreateRuleHelperError extends Error {
+    name: string;
+}

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

@@ -0,0 +1,6 @@
+export class CreateRuleHelperError extends Error {
+    constructor() {
+        super(...arguments);
+        this.name = 'CreateRuleHelperError';
+    }
+}

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

@@ -0,0 +1,2 @@
+import type { CreateRuleHelperParams, CreateRuleHelperResult } from './types.js';
+export declare function createRuleHelper(params: CreateRuleHelperParams): Promise<CreateRuleHelperResult>;

package/lib/create-rule-helper.js

@@ -0,0 +1,16 @@
+import { createRulePackage } from './create-rule-package.js';
+import { createRuleToCore } from './create-rule-to-core.js';
+import { createRuleToProject } from './create-rule-to-project.js';
+export async function createRuleHelper(params) {
+    switch (params.purpose) {
+        case 'ADD_TO_PROJECT': {
+            return await createRuleToProject(params);
+        }
+        case 'PUBLISH_AS_PACKAGE': {
+            return await createRulePackage(params);
+        }
+        case 'CONTRIBUTE_TO_CORE': {
+            return await createRuleToCore(params);
+        }
+    }
+}

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

@@ -0,0 +1,2 @@
+import type { CreateRuleCreatorParams, CreateRuleHelperResult } from './types.js';
+export declare function createRulePackage({ pluginName, ruleName, lang, needTest, }: CreateRuleCreatorParams): Promise<CreateRuleHelperResult>;

package/lib/create-rule-package.js

@@ -0,0 +1,18 @@
+import path from 'node:path';
+import { CreateRuleHelperError } from './create-rule-helper-error.js';
+import { glob } from './glob.js';
+import { installScaffold } from './install-scaffold.js';
+export async function createRulePackage({ pluginName, ruleName, lang, needTest, }) {
+    const newRuleDir = path.resolve(process.cwd(), '*');
+    const files = await glob(newRuleDir);
+    if (files.length > 0) {
+        throw new CreateRuleHelperError('The directory is not empty');
+    }
+    return await installScaffold('package', process.cwd(), {
+        pluginName,
+        ruleName,
+        lang,
+        needTest,
+        packageJson: true,
+    });
+}

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

@@ -0,0 +1,3 @@
+import type { CreateRuleCreatorParams, CreateRuleHelperResult } from './types.js';
+export declare function createRuleToCore({ ruleName, core }: CreateRuleCreatorParams): Promise<CreateRuleHelperResult>;
+export declare function getRulesDir(): Promise<string>;

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

@@ -0,0 +1,36 @@
+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';
+import { searchCoreRepository } from './search-core-repository.js';
+const rulesRelDir = ['packages', '@markuplint', 'rules', 'src'];
+export async function createRuleToCore({ ruleName, core }) {
+    if (!core) {
+        throw new CreateRuleHelperError('Core options are not defined');
+    }
+    const rulesDir = await getRulesDir();
+    const newRuleDir = path.resolve(rulesDir, ruleName);
+    const exists = await fsExists(newRuleDir);
+    if (exists) {
+        throw new CreateRuleHelperError(`A new rule "${ruleName}" already exists`);
+    }
+    return await installScaffold('core', newRuleDir, {
+        pluginName: '',
+        ruleName,
+        lang: 'TYPESCRIPT',
+        needTest: true,
+        core,
+    });
+}
+export async function getRulesDir() {
+    const rootDir = await searchCoreRepository();
+    if (!rootDir) {
+        throw new CreateRuleHelperError('The repository of markuplint is not found');
+    }
+    const rulesDir = path.resolve(rootDir, ...rulesRelDir);
+    const exists = await fsExists(rulesDir);
+    if (!exists) {
+        throw new CreateRuleHelperError(`Core rules directory (${rulesDir}) is not found`);
+    }
+    return rulesDir;
+}

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

@@ -0,0 +1,2 @@
+import type { CreateRuleCreatorParams, CreateRuleHelperResult } from './types.js';
+export declare function createRuleToProject({ pluginName, ruleName, lang, needTest, }: CreateRuleCreatorParams): Promise<CreateRuleHelperResult>;

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

@@ -0,0 +1,16 @@
+import { resolve } from 'node:path';
+import { CreateRuleHelperError } from './create-rule-helper-error.js';
+import { fsExists } from './fs-exists.js';
+import { installScaffold } from './install-scaffold.js';
+export async function createRuleToProject({ pluginName, ruleName, lang, needTest, }) {
+    const pluginDir = resolve(process.cwd(), pluginName);
+    if (await fsExists(pluginDir)) {
+        throw new CreateRuleHelperError(`The directory exists: ${pluginDir}`);
+    }
+    return await installScaffold('project', pluginDir, {
+        pluginName,
+        ruleName,
+        lang,
+        needTest,
+    });
+}

package/lib/fs-exists.d.ts

@@ -0,0 +1 @@
+export declare function fsExists(path: string): Promise<boolean>;

package/lib/fs-exists.js

@@ -0,0 +1,10 @@
+import { stat } from 'node:fs/promises';
+export async function fsExists(path) {
+    const res = await stat(path).catch(error => {
+        if (error?.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    });
+    return !!res;
+}

package/lib/glob.d.ts

@@ -0,0 +1 @@
+export declare const glob: (pattern: string) => Promise<string[]>;

package/lib/glob.js

@@ -0,0 +1,6 @@
+import { sep } from 'node:path';
+import { glob as origin } from 'glob';
+export const glob = async (pattern) => {
+    const normalized = pattern.split(sep).join('/');
+    return await origin(normalized);
+};

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+export * from './create-rule-helper.js';
+export * from './types.js';
+export { isMarkuplintRepo } from './is-markuplint-repo.js';

package/lib/index.js

@@ -0,0 +1,3 @@
+export * from './create-rule-helper.js';
+export * from './types.js';
+export { isMarkuplintRepo } from './is-markuplint-repo.js';

package/lib/install-scaffold.d.ts

@@ -0,0 +1,4 @@
+import type { CreateRuleCreatorParams, CreateRuleHelperResult } from './types.js';
+export declare function installScaffold(scaffoldType: 'core' | 'project' | 'package', dest: string, params: CreateRuleCreatorParams & {
+    readonly packageJson?: boolean;
+}): Promise<CreateRuleHelperResult>;

package/lib/install-scaffold.js

@@ -0,0 +1,61 @@
+import fs from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { fsExists } from './fs-exists.js';
+import { transfer } from './transfer.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+export async function installScaffold(scaffoldType, dest, params) {
+    const exists = await fsExists(dest);
+    if (!exists) {
+        await fs.mkdir(dest);
+    }
+    const scaffoldDir = resolve(__dirname, '..', 'scaffold', scaffoldType);
+    const transferred = await transfer(scaffoldType, scaffoldDir, dest, {
+        transpile: params.lang === 'JAVASCRIPT',
+        test: params.needTest,
+        replacer: {
+            pluginName: params.pluginName,
+            ruleName: params.ruleName,
+            description: params.core?.description,
+            category: params.core?.category,
+            severity: params.core?.severity,
+        },
+    });
+    const packageJson = params.packageJson ? resolve(dest, 'package.json') : null;
+    const dependencies = [];
+    const devDependencies = [];
+    if (packageJson) {
+        // const ext = params.lang === 'JAVASCRIPT' ? 'js' : 'ts';
+        const packageContent = {
+            name: params.ruleName,
+            scripts: {},
+        };
+        if (params.lang === 'TYPESCRIPT') {
+            packageContent.scripts.build = 'tsc';
+        }
+        dependencies.push('@markuplint/ml-core');
+        devDependencies.push('markuplint');
+        if (params.needTest) {
+            packageContent.scripts.test = 'vitest';
+            devDependencies.push('vitest');
+        }
+        if (params.lang === 'TYPESCRIPT') {
+            devDependencies.push('typescript');
+        }
+        await fs.writeFile(packageJson, JSON.stringify(packageContent, null, 2), { encoding: 'utf8' });
+        transferred.push({
+            ext: '.json',
+            name: 'package',
+            fileName: 'package',
+            test: false,
+            destDir: dest,
+            filePath: packageJson,
+        });
+    }
+    return {
+        files: transferred,
+        dependencies,
+        devDependencies,
+    };
+}

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

@@ -0,0 +1 @@
+export declare function isMarkuplintRepo(): Promise<boolean>;

package/lib/is-markuplint-repo.js

@@ -0,0 +1,5 @@
+import { searchCoreRepository } from './search-core-repository.js';
+export async function isMarkuplintRepo() {
+    const rootDir = await searchCoreRepository();
+    return !!rootDir;
+}

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

@@ -0,0 +1 @@
+export declare function readPackageJson(dir: string): Promise<string | null>;

package/lib/read-package-json.js

@@ -0,0 +1,13 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+export async function readPackageJson(dir) {
+    const filePath = path.resolve(dir, 'package.json');
+    try {
+        const json = await fs.readFile(filePath, { encoding: 'utf8' });
+        const data = JSON.parse(json);
+        return data?.name ?? null;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1 @@
+export declare function searchCoreRepository(): Promise<string | null>;

package/lib/search-core-repository.js

@@ -0,0 +1,17 @@
+import path from 'node:path';
+import { readPackageJson } from './read-package-json.js';
+export async function searchCoreRepository() {
+    const paths = path.resolve(process.cwd()).split(path.sep);
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        const currentDir = paths.join(path.sep);
+        const name = await readPackageJson(currentDir);
+        if (name === 'markuplint-packages') {
+            return currentDir;
+        }
+        const dir = paths.pop();
+        if (!dir) {
+            return null;
+        }
+    }
+}

package/lib/transfer.d.ts

@@ -0,0 +1,8 @@
+import type { File } from './types.js';
+type TransferOptions = {
+    readonly transpile?: boolean;
+    readonly test?: boolean;
+    readonly replacer?: Readonly<Record<string, string | void>>;
+};
+export declare function transfer(scaffoldType: 'core' | 'project' | 'package', baseDir: string, destDir: string, options?: TransferOptions): Promise<File[]>;
+export {};

package/lib/transfer.js

@@ -0,0 +1,112 @@
+import { statSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import { resolve, extname, basename, relative, dirname, sep } from 'node:path';
+import { format } from 'prettier';
+import tsc from 'typescript';
+import { fsExists } from './fs-exists.js';
+import { glob } from './glob.js';
+// eslint-disable-next-line import/no-named-as-default-member
+const { transpile, ScriptTarget } = tsc;
+export async function transfer(scaffoldType, baseDir, destDir, options) {
+    const files = await scan(baseDir, destDir);
+    const results = [];
+    for (const file of files) {
+        const result = await transferFile(scaffoldType, file, options);
+        if (result) {
+            results.push(result);
+        }
+    }
+    return results;
+}
+async function transferFile(scaffoldType, file, options) {
+    if (!(await fsExists(file.filePath))) {
+        return null;
+    }
+    if (file.test && !options?.test) {
+        return null;
+    }
+    let contents = await fs.readFile(file.filePath, { encoding: 'utf8' });
+    if (options?.replacer) {
+        for (const [before, after] of Object.entries(options?.replacer)) {
+            if (!after) {
+                continue;
+            }
+            // Hyphenation to camel-case for variables
+            // `rule-name` => `ruleName`
+            contents = contents.replaceAll(new RegExp(`__${before}__c`, 'g'), 
+            // Camelize
+            after.replaceAll(/-+([a-z])/gi, (_, $1) => $1.toUpperCase()).replace(/^[a-z]/, $0 => $0.toLowerCase()));
+            contents = contents.replaceAll(new RegExp(`__${before}__`, 'g'), after);
+        }
+    }
+    // Remove prettier ignore comment
+    contents = contents.replace(/\n\s*\/\/ prettier-ignore/, '');
+    contents = contents.replace(/\n\s*<!-- prettier-ignore(?:-(?:start|end))? -->/, '');
+    const newFile = { ...file };
+    if (scaffoldType === 'core' && file.test) {
+        const name = options?.replacer?.ruleName;
+        if (!name) {
+            throw new Error('Rule name is empty');
+        }
+        newFile.destDir = newFile.destDir.replace(`${sep}rules${sep}src${sep}`, `${sep}rules${sep}test${sep}`);
+        contents = contents.replace("require('./').default", `require('../../lib/${name}').default`);
+    }
+    // TypeScript transpiles to JS
+    if (newFile.ext === '.ts' && options?.transpile) {
+        newFile.ext = '.js';
+        contents = transpile(contents, {
+            target: ScriptTarget.ESNext,
+        }, newFile.filePath);
+        // Insert new line before comments and the export keyword
+        contents = contents.replaceAll(/(\n)(\s+\/\*\*|export)/g, '$1\n$2');
+    }
+    const candidateName = options?.replacer?.[newFile.name.replaceAll('_', '')];
+    if (candidateName) {
+        newFile.name = candidateName;
+        newFile.fileName = candidateName + (newFile.test ? '.spec' : '');
+    }
+    const dest = resolve(newFile.destDir, newFile.fileName + newFile.ext);
+    // Prettier
+    const parser = newFile.ext === '.md'
+        ? 'markdown'
+        : newFile.ext === '.json'
+            ? 'json'
+            : newFile.ext === '.ts'
+                ? options?.transpile
+                    ? 'babel'
+                    : 'typescript'
+                : undefined;
+    contents = await format(contents, { parser, filepath: dest });
+    if (!(await fsExists(newFile.destDir))) {
+        await fs.mkdir(newFile.destDir, { recursive: true });
+    }
+    await fs.writeFile(dest, contents, { encoding: 'utf8' });
+    return newFile;
+}
+async function scan(baseDir, destDir) {
+    const fileList = await glob(resolve(baseDir, '**', '*'));
+    const destList = fileList
+        .map(filePath => {
+        const stat = statSync(filePath);
+        if (!stat.isFile()) {
+            return null;
+        }
+        const relPath = relative(baseDir, filePath);
+        const destPath = resolve(destDir, relPath);
+        const ext = extname(destPath);
+        const fileName = basename(destPath, ext);
+        const test = extname(fileName) === '.spec';
+        const name = basename(fileName, '.spec');
+        const destFileDir = dirname(destPath);
+        return {
+            ext,
+            fileName,
+            name,
+            test,
+            destDir: destFileDir,
+            filePath,
+        };
+    })
+        .filter((f) => !!f);
+    return destList;
+}

package/lib/types.d.ts

@@ -0,0 +1,30 @@
+export type CreateRuleHelperParams = CreateRuleCreatorParams & {
+    readonly purpose: CreateRulePurpose;
+};
+export type CreateRuleCreatorParams = {
+    readonly pluginName: string;
+    readonly ruleName: string;
+    readonly lang: CreateRuleLanguage;
+    readonly needTest: boolean;
+    readonly core?: CreateRuleCreatorCoreParams;
+};
+export type CreateRuleCreatorCoreParams = {
+    readonly description: string;
+    readonly category: string;
+    readonly severity: string;
+};
+export type CreateRuleHelperResult = {
+    readonly files: readonly File[];
+    readonly dependencies: readonly string[];
+    readonly devDependencies: readonly string[];
+};
+export type CreateRuleLanguage = 'JAVASCRIPT' | 'TYPESCRIPT';
+export type CreateRulePurpose = 'ADD_TO_PROJECT' | 'PUBLISH_AS_PACKAGE' | 'CONTRIBUTE_TO_CORE';
+export type File = {
+    readonly ext: string;
+    readonly name: string;
+    readonly fileName: string;
+    readonly test: boolean;
+    readonly destDir: string;
+    readonly filePath: string;
+};

package/lib/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,40 @@
+{
+	"name": "@markuplint/create-rule",
+	"version": "4.0.0-dev.3823+b28398ab",
+	"description": "Rule generator for markuplint",
+	"repository": "git@github.com:markuplint/markuplint.git",
+	"author": "Yusuke Hirao <yusukehirao@me.com>",
+	"license": "MIT",
+	"private": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"import": "./lib/index.js"
+		}
+	},
+	"types": "./lib/index.d.ts",
+	"bin": {
+		"create-rule": "./bin/create-rule.mjs"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "tsc",
+		"dev": "tsc --build --watch",
+		"clean": "tsc --build --clean"
+	},
+	"dependencies": {
+		"@markuplint/cli-utils": "4.0.0-dev.3823+b28398ab",
+		"@markuplint/ml-core": "4.0.0-dev.10+b28398ab",
+		"glob": "^10.3.6",
+		"prettier": "^3.1.1",
+		"ts-node": "^10.9.2",
+		"typescript": "^5.3.3"
+	},
+	"devDependencies": {
+		"@types/fs-extra": "^11.0.4",
+		"fs-extra": "^11.2.0"
+	},
+	"gitHead": "b28398ab9c8f0ad790f2915ad5da8f3a80e9b8d6"
+}

package/scaffold/.eslintrc

@@ -0,0 +1,5 @@
+{
+	"rules": {
+		"import/no-default-export": 0
+	}
+}

package/scaffold/core/README.ja.md

@@ -0,0 +1,26 @@
+---
+description: TODO/翻訳 __description__
+---
+
+# `__ruleName__`
+
+<!-- textlint-disable ja-technical-writing/ja-no-mixed-period -->
+
+<!-- prettier-ignore-start -->
+TODO: 翻訳
+__description__
+<!-- prettier-ignore-end -->
+
+❌ 間違ったコード例
+
+```html
+<todo>Write incorrect codes</todo>
+```
+
+✅ 正しいコード例
+
+```html
+<todo>Write correct codes</todo>
+```
+
+<!-- textlint-enable ja-technical-writing/ja-no-mixed-period -->

package/scaffold/core/README.md

@@ -0,0 +1,22 @@
+---
+id: __ruleName__
+description: __description__
+---
+
+# `__ruleName__`
+
+<!-- prettier-ignore-start -->
+__description__
+<!-- prettier-ignore-end -->
+
+❌ Examples of **incorrect** code for this rule
+
+```html
+<todo>Write incorrect codes</todo>
+```
+
+✅ Examples of **correct** code for this rule
+
+```html
+<todo>Write correct codes</todo>
+```

package/scaffold/core/index.spec.ts

@@ -0,0 +1,18 @@
+import { mlRuleTest } from 'markuplint';
+import { test, expect } from 'vitest';
+
+import rule from './index.js';
+
+test('It is test', async () => {
+	const { violations } = await mlRuleTest(rule, '<x-foo></x-foo>');
+	expect(violations.length).toBe(1);
+	// expect(violations).toStrictEqual([
+	// 	{
+	// 		severity: 'error',
+	// 		line: 1,
+	// 		col: 1,
+	// 		raw: '',
+	// 		message: 'It is issue',
+	// 	},
+	// ]);
+});

package/scaffold/core/index.ts

@@ -0,0 +1,31 @@
+import { createRule } from '@markuplint/ml-core';
+
+export default createRule<boolean, null>({
+	defaultValue: true,
+	defaultOptions: null,
+	async verify({ document, report, t }) {
+		// Element
+		await document.walkOn('Element', el => {
+			const raw = el.raw.trim();
+			if (/./.test(raw)) {
+				report({
+					scope: el,
+					message: t('It is {0}', 'issue'),
+				});
+			}
+		});
+
+		// Attribute
+		await document.walkOn('Attr', attr => {
+			if (/./.test(attr.name)) {
+				report({
+					scope: attr,
+					line: attr.nameNode?.startLine,
+					col: attr.nameNode?.startCol,
+					raw: attr.nameNode?.raw,
+					message: t('It is {0}', 'issue'),
+				});
+			}
+		});
+	},
+});

package/scaffold/core/schema.json

@@ -0,0 +1,47 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"_category": "__category__",
+	"definitions": {
+		"value": {
+			"type": "boolean",
+			"description": "__VALUE_DESCRIPTION__",
+			"description:ja": "__VALUE_DESCRIPTION_IN_JAPANESE__"
+		},
+		"options": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"__OPTIONS_PROP_NAME__": {
+					"type": "boolean",
+					"default": "true",
+					"description": "__OPTIONS_PROP_DESCRIPTION__",
+					"description:ja": "__OPTIONS_PROP_DESCRIPTION_IN_JAPANESE__"
+				}
+			}
+		}
+	},
+	"oneOf": [
+		{
+			"type": "boolean"
+		},
+		{
+			"$ref": "#/definitions/value"
+		},
+		{
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"value": { "$ref": "#/definitions/value" },
+				"options": { "$ref": "#/definitions/options" },
+				"option": { "$ref": "#/definitions/options", "deprecated": true },
+				"severity": {
+					"$ref": "https://raw.githubusercontent.com/markuplint/markuplint/main/packages/%40markuplint/ml-config/schema.json#/definitions/severity",
+					"default": "__severity__"
+				},
+				"reason": {
+					"type": "string"
+				}
+			}
+		}
+	]
+}

package/scaffold/package/README.md

@@ -0,0 +1,60 @@
+# The `__pluginName__` rule
+
+TODO: Write a description
+
+## Install
+
+```shell
+npm install --save-dev {{ name }}
+```
+
+## Applying rules
+
+```json
+{
+  "plugins": ["__pluginName__"],
+  "rules": {
+    "__pluginName__/__ruleName__": {
+      "value": "__MAIN_VALUE__",
+      "options": {
+        "foo": "__OPTIONAL_VALUE__",
+        "bar": [123, 456, 789]
+      }
+    }
+  }
+}
+```
+
+## Rule Details
+
+👎 Examples of **incorrect** code for this rule
+
+```html
+<todo>Write incorrect codes</todo>
+```
+
+👍 Examples of **correct** code for this rule
+
+```html
+<todo>Write correct codes</todo>
+```
+
+### Interface
+
+- Type: `string`
+- Default Value: `"__DEFAULT_MAIN_VALUE__"`
+
+### Options
+
+TODO: Write a description
+
+#### Interface
+
+| Property | Type       | Optional | Default Value | Description               |
+| -------- | ---------- | -------- | ------------- | ------------------------- |
+| `foo`    | `string`   | ✔       | `undefined`   | TODO: Write a description |
+| `bar`    | `number[]` | ✔       | `undefined`   | TODO: Write a description |
+
+### Default severity
+
+TODO: Choose `error` or `warning`

package/scaffold/package/src/index.ts

@@ -0,0 +1,15 @@
+import { createPlugin } from '@markuplint/ml-core';
+
+import { __ruleName__c } from './rules/__ruleName__.js';
+
+export default createPlugin({
+	name: '__pluginName__',
+	create(settings) {
+		return {
+			rules: {
+				// prettier-ignore
+				'__ruleName__': __ruleName__c(settings),
+			},
+		};
+	},
+});

package/scaffold/package/src/rules/__ruleName__.ts

@@ -0,0 +1,94 @@
+import type { CreatePluginSettings } from '@markuplint/ml-core';
+
+import { createRule } from '@markuplint/ml-core';
+
+/**
+ * Step 0-1. Define the type of principal value
+ *
+ * You can define it as either `string` or `number` or `boolean` or `Array`.
+ * If you define a complex structure, you should define `boolean` to this
+ * and define that structure to the options.
+ */
+type MainValue = string;
+
+/**
+ * Step 0-2. Define the type of options
+ *
+ * You can define it as an _Object_. Set `null` if it is empty.
+ */
+type Options = {
+	foo?: string;
+	bar?: number[];
+};
+
+export const __ruleName__c = (settings: CreatePluginSettings) =>
+	createRule<MainValue, Options>({
+		/**
+		 * Step 1-1. Choose the severity from `error` or `warning`
+		 *
+		 * Default is `error`
+		 */
+		defaultSeverity: 'error',
+
+		/**
+		 * Step 1-2. Set the default principal value
+		 *
+		 * It adopts this value in the evaluation
+		 * if it sets `true` or undefined (in other words, it doesn't set)
+		 * to the configuration.
+		 */
+		defaultValue: '__DEFAULT_MAIN_VALUE__',
+
+		/**
+		 * Step 1-3. Set the default options
+		 *
+		 * It adopts this value in the evaluation
+		 * if it doesn't set to the configuration.
+		 */
+		defaultOptions: {},
+
+		/**
+		 * Step 2. Write a process.
+		 *
+		 * @param context
+		 */
+		async verify({ document, report, t }) {
+			/**
+			 * Example: Use `walkOn` method to traverse the node tree
+			 */
+			await document.walkOn('Comment', comment => {
+				/**
+				 * Example: Access the property of the node to get needed data
+				 */
+				const commentText = comment.raw.trim();
+
+				/**
+				 * Example: Compare data according to your design to report the violation
+				 */
+				if (/^<!--\s*todo:/i.test(commentText)) {
+					/**
+					 * Example: It delivers the violation to the linter engine
+					 *
+					 * This `report` method can call many times.
+					 */
+					report({
+						/**
+						 * Example: Define the scope.
+						 *
+						 * Set the _node_ that gives
+						 * the location (line number and column number)
+						 * to the linter engine.
+						 */
+						scope: comment,
+
+						/**
+						 * Example: The message that is output to a user.
+						 *
+						 * You can set just strings without through the translator.
+						 */
+						message: t('It is {0}', 'TODO'),
+					});
+				}
+			});
+		},
+	});

package/scaffold/package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+	"compilerOptions": {
+		"module": "commonjs",
+		"target": "es2019",
+		"strict": true,
+		"strictNullChecks": true,
+		"strictPropertyInitialization": true,
+		"allowSyntheticDefaultImports": true,
+		"experimentalDecorators": true,
+		"esModuleInterop": true,
+		"noImplicitAny": true,
+		"declaration": true,
+		"lib": ["dom", "es2015", "es2016", "es2017", "es2018", "es2019", "esnext"],
+		"skipLibCheck": true,
+		"outDir": "./lib",
+		"rootDir": "./src"
+	},
+	"include": ["./src/**/*"],
+	"exclude": ["node_modules", "lib", "./src/**/*.spec.ts"]
+}

package/scaffold/project/index.ts

@@ -0,0 +1,15 @@
+import { createPlugin } from '@markuplint/ml-core';
+
+import { __ruleName__c } from './rules/__ruleName__.js';
+
+export default createPlugin({
+	name: '__pluginName__',
+	create(setting) {
+		return {
+			rules: {
+				// prettier-ignore
+				'__ruleName__': __ruleName__c(setting),
+			},
+		};
+	},
+});

package/scaffold/project/rules/__ruleName__.spec.ts

@@ -0,0 +1,32 @@
+import { mlRuleTest } from 'markuplint';
+import { test, expect } from 'vitest';
+
+import { __ruleName__c } from './__ruleName__.js';
+
+/**
+ * Example: Write tests
+ */
+test('It is test', async () => {
+	const { violations } = await mlRuleTest(
+		__ruleName__c({
+			/* Plugin settings */
+		}),
+		/**
+		 * Example: The target HTML that is evaluated
+		 */
+		'<div><!-- TODO: I will do something --></div>',
+	);
+
+	/**
+	 * Example: Set expected results.
+	 */
+	expect(violations).toStrictEqual([
+		{
+			severity: 'error',
+			line: 1,
+			col: 6,
+			raw: '<!-- TODO: I will do something -->',
+			message: 'It is TODO',
+		},
+	]);
+});

package/scaffold/project/rules/__ruleName__.ts

@@ -0,0 +1,94 @@
+import type { CreatePluginSettings } from '@markuplint/ml-core';
+
+import { createRule } from '@markuplint/ml-core';
+
+/**
+ * Step 0-1. Define the type of principal value
+ *
+ * You can define it as either `string` or `number` or `boolean` or `Array`.
+ * If you define a complex structure, you should define `boolean` to this
+ * and define that structure to the options.
+ */
+type MainValue = string;
+
+/**
+ * Step 0-2. Define the type of options
+ *
+ * You can define it as an _Object_. Set `null` if it is empty.
+ */
+type Options = {
+	foo?: string;
+	bar?: number[];
+};
+
+export const __ruleName__c = (settings: CreatePluginSettings = {}) =>
+	createRule<MainValue, Options>({
+		/**
+		 * Step 1-1. Choose the severity from `error` or `warning`
+		 *
+		 * Default is `error`
+		 */
+		defaultSeverity: 'error',
+
+		/**
+		 * Step 1-2. Set the default principal value
+		 *
+		 * It adopts this value in the evaluation
+		 * if it sets `true` or undefined (in other words, it doesn't set)
+		 * to the configuration.
+		 */
+		defaultValue: '__DEFAULT_MAIN_VALUE__',
+
+		/**
+		 * Step 1-3. Set the default options
+		 *
+		 * It adopts this value in the evaluation
+		 * if it doesn't set to the configuration.
+		 */
+		defaultOptions: {},
+
+		/**
+		 * Step 2. Write a process.
+		 *
+		 * @param context
+		 */
+		async verify({ document, report, t }) {
+			/**
+			 * Example: Use `walkOn` method to traverse the node tree
+			 */
+			await document.walkOn('Comment', comment => {
+				/**
+				 * Example: Access the property of the node to get needed data
+				 */
+				const commentText = comment.raw.trim();
+
+				/**
+				 * Example: Compare data according to your design to report the violation
+				 */
+				if (/^<!--\s*todo:/i.test(commentText)) {
+					/**
+					 * Example: It delivers the violation to the linter engine
+					 *
+					 * This `report` method can call many times.
+					 */
+					report({
+						/**
+						 * Example: Define the scope.
+						 *
+						 * Set the _node_ that gives
+						 * the location (line number and column number)
+						 * to the linter engine.
+						 */
+						scope: comment,
+
+						/**
+						 * Example: The message that is output to a user.
+						 *
+						 * You can set just strings without through the translator.
+						 */
+						message: t('It is {0}', 'TODO'),
+					});
+				}
+			});
+		},
+	});