eslint-plugin-markdown-preferences 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yosuke Ota
+
+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,110 @@
+# Introduction
+
+[eslint-plugin-markdown-preferences](https://www.npmjs.com/package/eslint-plugin-markdown-preferences) is ESLint plugin that enforces our markdown preferences.
+
+[![NPM license](https://img.shields.io/npm/l/eslint-plugin-markdown-preferences.svg)](https://www.npmjs.com/package/eslint-plugin-markdown-preferences)
+[![NPM version](https://img.shields.io/npm/v/eslint-plugin-markdown-preferences.svg)](https://www.npmjs.com/package/eslint-plugin-markdown-preferences)
+[![NPM downloads](https://img.shields.io/badge/dynamic/json.svg?label=downloads&colorB=green&suffix=/day&query=$.downloads&uri=https://api.npmjs.org//downloads/point/last-day/eslint-plugin-markdown-preferences&maxAge=3600)](http://www.npmtrends.com/eslint-plugin-markdown-preferences)
+[![NPM downloads](https://img.shields.io/npm/dw/eslint-plugin-markdown-preferences.svg)](http://www.npmtrends.com/eslint-plugin-markdown-preferences)
+[![NPM downloads](https://img.shields.io/npm/dm/eslint-plugin-markdown-preferences.svg)](http://www.npmtrends.com/eslint-plugin-markdown-preferences)
+[![NPM downloads](https://img.shields.io/npm/dy/eslint-plugin-markdown-preferences.svg)](http://www.npmtrends.com/eslint-plugin-markdown-preferences)
+[![NPM downloads](https://img.shields.io/npm/dt/eslint-plugin-markdown-preferences.svg)](http://www.npmtrends.com/eslint-plugin-markdown-preferences)
+[![Build Status](https://github.com/ota-meshi/eslint-plugin-markdown-preferences/actions/workflows/NodeCI.yml/badge.svg?branch=main)](https://github.com/ota-meshi/eslint-plugin-markdown-preferences/actions/workflows/NodeCI.yml)
+
+## 📛 Features
+
+ESLint plugin that enforces our markdown preferences.
+
+You can check on the [Online DEMO](https://eslint-online-playground.netlify.app/#eslint-plugin-markdown-preferences).
+
+<!--DOCS_IGNORE_START-->
+
+## 📖 Documentation
+
+See [documents](https://ota-meshi.github.io/eslint-plugin-markdown-preferences/).
+
+## 💿 Installation
+
+```bash
+npm install --save-dev eslint eslint-plugin-markdown-preferences
+```
+
+<!--DOCS_IGNORE_END-->
+
+## 📖 Usage
+
+<!--USAGE_SECTION_START-->
+<!--USAGE_GUIDE_START-->
+
+### Configuration
+
+#### New Config (`eslint.config.js`)
+
+Use `eslint.config.js` file to configure rules. See also: <https://eslint.org/docs/latest/use/configure/configuration-files-new>.
+
+Example **eslint.config.js**:
+
+```js
+import { defineConfig } from "eslint/config";
+// import markdown from "@eslint/markdown";
+import markdownPreferences from 'eslint-plugin-markdown-preferences';
+export default [
+  // add more generic rule sets here, such as:
+  // markdown.configs.recommended,
+  markdownPreferences.configs.recommended,
+  {
+    rules: {
+      // override/add rules settings here, such as:
+      // 'markdown-preferences/prefer-linked-words': 'error'
+    }
+  }
+];
+```
+
+This plugin provides configs:
+
+- `*.configs.recommended` ... Recommended config provided by the plugin.
+
+See [the rule list](https://ota-meshi.github.io/eslint-plugin-markdown-preferences/rules/) to get the `rules` that this plugin provides.
+
+#### Legacy Config (`.eslintrc`)
+
+Is not supported.
+
+<!--USAGE_GUIDE_END-->
+<!--USAGE_SECTION_END-->
+
+## ✅ Rules
+
+<!--RULES_SECTION_START-->
+
+The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#fixing-problems) automatically fixes problems reported by rules which have a wrench 🔧 below.  
+The rules with the following star ⭐ are included in the configs.
+
+<!--RULES_TABLE_START-->
+
+### Markdown Rules
+
+| Rule ID | Description | Fixable | RECOMMENDED |
+|:--------|:------------|:-------:|:-----------:|
+| [markdown-preferences/hard-linebreak-style](https://ota-meshi.github.io/eslint-plugin-markdown-preferences/rules/hard-linebreak-style.html) | enforce consistent hard linebreak style. | 🔧 | ⭐ |
+| [markdown-preferences/prefer-linked-words](https://ota-meshi.github.io/eslint-plugin-markdown-preferences/rules/prefer-linked-words.html) | enforce the specified word to be a link. | 🔧 |  |
+
+<!--RULES_TABLE_END-->
+<!--RULES_SECTION_END-->
+<!--DOCS_IGNORE_START-->
+
+## 🍻 Contributing
+
+Welcome contributing!
+
+Please use GitHub's Issues/PRs.
+
+### Development Tools
+
+- `npm test` runs tests and measures coverage.  
+- `npm run update` runs in order to update readme and recommended configuration.  
+
+## 🔒 License
+
+See the [LICENSE](LICENSE) file for license rights and limitations (MIT).

package/lib/index.d.ts

@@ -0,0 +1,76 @@
+import * as _eslint_core from '@eslint/core';
+import { RuleDefinition } from '@eslint/core';
+import { Linter, ESLint } from 'eslint';
+import markdown from '@eslint/markdown';
+
+declare module 'eslint' {
+    namespace Linter {
+        interface RulesRecord extends RuleOptions {
+        }
+    }
+}
+interface RuleOptions {
+    /**
+     * enforce consistent hard linebreak style.
+     * @see https://ota-meshi.github.io/eslint-plugin-markdown-preferences/rules/hard-linebreak-style.html
+     */
+    'markdown-preferences/hard-linebreak-style'?: Linter.RuleEntry<MarkdownPreferencesHardLinebreakStyle>;
+    /**
+     * enforce the specified word to be a link.
+     * @see https://ota-meshi.github.io/eslint-plugin-markdown-preferences/rules/prefer-linked-words.html
+     */
+    'markdown-preferences/prefer-linked-words'?: Linter.RuleEntry<MarkdownPreferencesPreferLinkedWords>;
+}
+type MarkdownPreferencesHardLinebreakStyle = [] | [
+    {
+        style?: ("backslash" | "spaces");
+    }
+];
+type MarkdownPreferencesPreferLinkedWords = [] | [
+    {
+        words: ({
+            [k: string]: (string | null);
+        } | string[]);
+        [k: string]: unknown | undefined;
+    }
+];
+
+declare const name$1 = "markdown-preferences/recommended";
+declare const files: string[];
+declare const language = "markdown/commonmark";
+declare const plugins: {
+    markdown: typeof markdown;
+    readonly "markdown-preferences": ESLint.Plugin;
+};
+declare const rules$1: Linter.RulesRecord;
+
+declare const recommended_files: typeof files;
+declare const recommended_language: typeof language;
+declare const recommended_plugins: typeof plugins;
+declare namespace recommended {
+  export { recommended_files as files, recommended_language as language, name$1 as name, recommended_plugins as plugins, rules$1 as rules };
+}
+
+declare const name: "eslint-plugin-markdown-preferences";
+declare const version: "0.1.0";
+
+declare const meta_name: typeof name;
+declare const meta_version: typeof version;
+declare namespace meta {
+  export { meta_name as name, meta_version as version };
+}
+
+declare const configs: {
+    recommended: typeof recommended;
+};
+declare const rules: Record<string, RuleDefinition>;
+
+declare const _default: {
+    meta: typeof meta;
+    configs: {
+        recommended: typeof recommended;
+    };
+    rules: Record<string, RuleDefinition<_eslint_core.RuleDefinitionTypeOptions>>;
+};
+
+export { configs, _default as default, meta, rules };

package/lib/index.js

@@ -0,0 +1,251 @@
+import path from 'path';
+import markdown from '@eslint/markdown';
+
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name3 in all)
+    __defProp(target, name3, { get: all[name3], enumerable: true });
+};
+
+// src/utils/index.ts
+function createRule(ruleName, rule) {
+  return {
+    meta: {
+      ...rule.meta,
+      docs: {
+        ...rule.meta.docs,
+        url: `https://ota-meshi.github.io/eslint-plugin-markdown-preferences/rules/${ruleName}.html`,
+        ruleId: `markdown-preferences/${ruleName}`,
+        ruleName
+      }
+    },
+    create(context) {
+      return rule.create(context);
+    }
+  };
+}
+
+// src/rules/hard-linebreak-style.ts
+var hard_linebreak_style_default = createRule("hard-linebreak-style", {
+  meta: {
+    type: "layout",
+    docs: {
+      description: "enforce consistent hard linebreak style.",
+      categories: ["recommended"]
+    },
+    fixable: "code",
+    hasSuggestions: false,
+    schema: [
+      {
+        type: "object",
+        properties: {
+          style: {
+            enum: ["backslash", "spaces"]
+          }
+        },
+        additionalProperties: false
+      }
+    ],
+    messages: {
+      expectedBackslash: "Expected a backslash linebreak.",
+      expectedSpaces: "Expected a space linebreak."
+    }
+  },
+  create(context) {
+    const sourceCode = context.sourceCode;
+    const linebreakStyle = context.options[0]?.style || "backslash";
+    return {
+      break: (node) => {
+        const text = sourceCode.getText(node);
+        if (linebreakStyle === "backslash" && !text.startsWith("\\")) {
+          context.report({
+            node,
+            messageId: "expectedBackslash",
+            fix(fixer) {
+              return fixer.replaceText(node, "\\\n");
+            }
+          });
+        } else if (linebreakStyle === "spaces" && !text.startsWith("  ")) {
+          context.report({
+            node,
+            messageId: "expectedSpaces",
+            fix(fixer) {
+              return fixer.replaceText(node, "  \n");
+            }
+          });
+        }
+      }
+    };
+  }
+});
+var prefer_linked_words_default = createRule("prefer-linked-words", {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "enforce the specified word to be a link.",
+      categories: []
+    },
+    fixable: "code",
+    hasSuggestions: false,
+    schema: [
+      {
+        type: "object",
+        properties: {
+          words: {
+            anyOf: [
+              {
+                type: "object",
+                patternProperties: {
+                  "^[\\s\\S]+$": {
+                    type: ["string", "null"]
+                  }
+                }
+              },
+              {
+                type: "array",
+                items: {
+                  type: "string"
+                }
+              }
+            ]
+          }
+        },
+        required: ["words"]
+      }
+    ],
+    messages: {
+      requireLink: 'The word "{{name}}" should be a link.'
+    }
+  },
+  create(context) {
+    const sourceCode = context.sourceCode;
+    const words = context.options[0]?.words || {};
+    const wordEntries = (Array.isArray(words) ? words.map((word) => [word, void 0]) : Object.entries(words)).map(
+      ([word, link]) => [word, link ? adjustLink(link) : void 0]
+    ).filter(([, link]) => link !== `./${path.basename(context.filename)}`);
+    let ignore = null;
+    return {
+      "link, linkReference, heading"(node) {
+        if (ignore) return;
+        ignore = node;
+      },
+      "link, linkReference, heading:exit"(node) {
+        if (ignore === node) ignore = null;
+      },
+      text(node) {
+        if (ignore) return;
+        for (const [word, link] of wordEntries) {
+          let startPosition = 0;
+          while (true) {
+            const index = node.value.indexOf(word, startPosition);
+            if (index < 0) break;
+            startPosition = index + word.length;
+            if ((node.value[index - 1] || "").trim() || (node.value[index + word.length] || "").trim()) {
+              continue;
+            }
+            const loc = sourceCode.getLoc(node);
+            const beforeLines = node.value.slice(0, index).split(/\n/u);
+            const line = loc.start.line + beforeLines.length - 1;
+            const column = (beforeLines.length === 1 ? loc.start.column : 1) + (beforeLines.at(-1) || "").length;
+            context.report({
+              node,
+              loc: {
+                start: { line, column },
+                end: { line, column: column + word.length }
+              },
+              messageId: "requireLink",
+              data: {
+                name: word
+              },
+              fix: link ? (fixer) => {
+                const [start] = sourceCode.getRange(node);
+                return fixer.replaceTextRange(
+                  [start + index, start + index + word.length],
+                  `[${word}](${link})`
+                );
+              } : null
+            });
+          }
+        }
+      },
+      inlineCode(node) {
+        if (ignore) return;
+        for (const [word, link] of wordEntries) {
+          if (node.value === word) {
+            context.report({
+              node,
+              messageId: "requireLink",
+              data: {
+                name: word
+              },
+              fix: link ? (fixer) => {
+                return fixer.replaceText(node, `[\`${word}\`](${link})`);
+              } : null
+            });
+          }
+        }
+      }
+    };
+    function adjustLink(link) {
+      if (/^\w+:/.test(link)) {
+        return link;
+      }
+      if (link.startsWith("#")) {
+        return link;
+      }
+      const absoluteLink = path.isAbsolute(link) ? link : path.join(context.cwd, link);
+      return `./${path.relative(path.dirname(context.filename), absoluteLink)}`;
+    }
+  }
+});
+
+// src/utils/rules.ts
+var rules = [hard_linebreak_style_default, prefer_linked_words_default];
+
+// src/configs/recommended.ts
+var recommended_exports = {};
+__export(recommended_exports, {
+  files: () => files,
+  language: () => language,
+  name: () => name,
+  plugins: () => plugins,
+  rules: () => rules2
+});
+var name = "markdown-preferences/recommended";
+var files = ["**/*.md"];
+var language = "markdown/commonmark";
+var plugins = {
+  markdown,
+  // eslint-disable-next-line @typescript-eslint/naming-convention -- ignore
+  get "markdown-preferences"() {
+    return index_default;
+  }
+};
+var rules2 = {
+  // eslint-plugin-markdown-preferences rules
+  "markdown-preferences/hard-linebreak-style": "error"
+};
+
+// src/meta.ts
+var meta_exports = {};
+__export(meta_exports, {
+  name: () => name2,
+  version: () => version
+});
+var name2 = "eslint-plugin-markdown-preferences";
+var version = "0.1.0";
+
+// src/index.ts
+var configs = {
+  recommended: recommended_exports
+};
+var rules3 = rules.reduce(
+  (obj, r) => {
+    obj[r.meta.docs.ruleName] = r;
+    return obj;
+  },
+  {}
+);
+var index_default = { meta: meta_exports, configs, rules: rules3 };
+
+export { configs, index_default as default, meta_exports as meta, rules3 as rules };

package/package.json

@@ -0,0 +1,124 @@
+{
+  "name": "eslint-plugin-markdown-preferences",
+  "version": "0.1.0",
+  "description": "ESLint plugin that enforces our markdown preferences",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib"
+  ],
+  "engines": {
+    "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+  },
+  "scripts": {
+    "build": "npm run build:meta && npm run build:tsup",
+    "build:meta": "npm run ts -- ./tools/update-meta.ts",
+    "build:tsup": "tsup",
+    "lint": "eslint .",
+    "tsc": "tsc --project tsconfig.build.json",
+    "eslint-fix": "eslint . --fix",
+    "test": "npm run mocha -- \"tests/src/**/*.ts\" --reporter=dot --timeout=60000",
+    "cover": "c8 --reporter=lcov npm run test",
+    "test:update": "npm run mocha -- \"tests/src/**/*.ts\" --reporter=dot --update",
+    "update": "npm run ts -- ./tools/update.ts && npm run eslint-fix",
+    "new": "npm run ts -- ./tools/new-rule.ts",
+    "docs:watch": "vitepress dev docs --open",
+    "docs:build": "vitepress build docs",
+    "ts": "node --import=tsx",
+    "mocha": "npm run ts ./node_modules/mocha/bin/mocha.js",
+    "generate:version": "env-cmd -e version npm run update && npm run lint -- --fix",
+    "changeset:version": "changeset version && npm run generate:version && git add --all",
+    "changeset:publish": "npm run build && changeset publish"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ota-meshi/eslint-plugin-markdown-preferences.git"
+  },
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "markdown",
+    "preferences",
+    "lint"
+  ],
+  "author": "Yosuke Ota",
+  "funding": "https://github.com/sponsors/ota-meshi",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/ota-meshi/eslint-plugin-markdown-preferences/issues"
+  },
+  "homepage": "https://ota-meshi.github.io/eslint-plugin-markdown-preferences/",
+  "dependencies": {},
+  "peerDependencies": {
+    "eslint": ">=9.0.0",
+    "@eslint/markdown": "^7.1.0"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.5.1",
+    "@changesets/cli": "^2.28.1",
+    "@changesets/get-release-plan": "^4.0.8",
+    "@eslint/core": "^0.15.0",
+    "@eslint/markdown": "^7.1.0",
+    "@ota-meshi/eslint-plugin": "^0.17.6",
+    "@shikijs/vitepress-twoslash": "^3.0.0",
+    "@types/eslint": "^9.6.1",
+    "@types/eslint-scope": "^8.0.0",
+    "@types/eslint-utils": "^3.0.5",
+    "@types/estree": "^1.0.6",
+    "@types/json-schema": "^7.0.15",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^22.13.10",
+    "@types/semver": "^7.5.8",
+    "assert": "^2.1.0",
+    "c8": "^10.1.3",
+    "env-cmd": "^10.1.0",
+    "eslint": "^9.22.0",
+    "eslint-compat-utils": "^0.6.4",
+    "eslint-config-prettier": "^10.1.1",
+    "eslint-plugin-eslint-comments": "^3.2.0",
+    "eslint-plugin-eslint-plugin": "^6.4.0",
+    "eslint-plugin-jsdoc": "^52.0.0",
+    "eslint-plugin-json-schema-validator": "^5.3.1",
+    "eslint-plugin-jsonc": "^2.19.1",
+    "eslint-plugin-markdown": "^5.1.0",
+    "eslint-plugin-n": "^17.16.2",
+    "eslint-plugin-node-dependencies": "^1.0.0",
+    "eslint-plugin-prettier": "^5.2.3",
+    "eslint-plugin-regexp": "^2.7.0",
+    "eslint-plugin-vue": "^10.0.0",
+    "eslint-plugin-yml": "^1.17.0",
+    "eslint-snapshot-rule-tester": "^0.1.0",
+    "eslint-typegen": "^2.0.0",
+    "espree": "^10.3.0",
+    "events": "^3.3.0",
+    "globals": "^16.0.0",
+    "mocha": "^11.1.0",
+    "pako": "^2.1.0",
+    "prettier": "^3.5.3",
+    "semver": "^7.7.1",
+    "stylelint": "^16.15.0",
+    "stylelint-config-recommended": "^17.0.0",
+    "stylelint-config-recommended-vue": "^1.6.0",
+    "stylelint-config-standard": "^39.0.0",
+    "stylelint-config-standard-vue": "^1.0.0",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.3",
+    "twoslash-eslint": "^0.3.1",
+    "type-fest": "^4.37.0",
+    "typescript": "~5.9.0",
+    "typescript-eslint": "^8.26.1",
+    "util": "^0.12.5",
+    "vite-plugin-eslint4b": "^0.6.0",
+    "vitepress": "^1.6.3",
+    "vue-eslint-parser": "^10.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}