From 3c085504767d8eb28c0a16b8152fcd9bf79fbd8e Mon Sep 17 00:00:00 2001 From: Yosuke Ota Date: Fri, 6 Oct 2023 21:29:42 +0900 Subject: [PATCH] chore(docs): use vitepress (#114) --- .eslintignore | 5 +- .github/workflows/GHPages.yml | 3 +- .gitignore | 3 +- docs/.vitepress/.eslintrc.js | 26 + docs/.vitepress/config.mjs | 74 +++ .../theme/components/eslint-editor.vue | 444 ++++++++++++++++++ .../theme/components/eslint-playground.vue | 203 ++++++++ .../theme/components/monaco-editor.vue | 356 ++++++++++++++ .../theme/components/monaco/index.mjs | 2 + .../theme/components/monaco/monaco-loader.mjs | 69 +++ .../theme/components/monaco/monaco-setup.mjs | 221 +++++++++ docs/.vitepress/theme/index.mjs | 20 + docs/.vitepress/theme/style.css | 27 ++ docs/.vitepress/vite-plugin.mjs | 87 ++++ .../components/eslint-playground.vue | 125 ----- docs/.vuepress/config.js | 82 ---- docs/.vuepress/enhanceApp.mjs | 10 - docs/.vuepress/public/.nojekyll | 0 docs/.vuepress/styles/index.styl | 2 - docs/.vuepress/styles/palette.styl | 1 - docs/{README.md => index.md} | 2 +- docs/rules/disable-enable-pair.md | 54 ++- docs/rules/{README.md => index.md} | 0 docs/rules/no-aggregating-enable.md | 27 +- docs/rules/no-duplicate-disable.md | 27 +- docs/rules/no-restricted-disable.md | 36 +- docs/rules/no-unlimited-disable.md | 18 +- docs/rules/no-unused-disable.md | 36 +- docs/rules/no-unused-enable.md | 36 +- docs/rules/no-use.md | 9 +- docs/rules/require-description.md | 18 +- package.json | 14 +- scripts/update-docs-index.js | 2 +- 33 files changed, 1747 insertions(+), 292 deletions(-) create mode 100644 docs/.vitepress/.eslintrc.js create mode 100644 docs/.vitepress/config.mjs create mode 100644 docs/.vitepress/theme/components/eslint-editor.vue create mode 100644 docs/.vitepress/theme/components/eslint-playground.vue create mode 100644 docs/.vitepress/theme/components/monaco-editor.vue create mode 100644 docs/.vitepress/theme/components/monaco/index.mjs create mode 100644 docs/.vitepress/theme/components/monaco/monaco-loader.mjs create mode 100644 docs/.vitepress/theme/components/monaco/monaco-setup.mjs create mode 100644 docs/.vitepress/theme/index.mjs create mode 100644 docs/.vitepress/theme/style.css create mode 100644 docs/.vitepress/vite-plugin.mjs delete mode 100644 docs/.vuepress/components/eslint-playground.vue delete mode 100644 docs/.vuepress/config.js delete mode 100644 docs/.vuepress/enhanceApp.mjs delete mode 100644 docs/.vuepress/public/.nojekyll delete mode 100644 docs/.vuepress/styles/index.styl delete mode 100644 docs/.vuepress/styles/palette.styl rename docs/{README.md => index.md} (99%) rename docs/rules/{README.md => index.md} (100%) diff --git a/.eslintignore b/.eslintignore index 0d2fd1f..bdca81e 100644 --- a/.eslintignore +++ b/.eslintignore @@ -1,5 +1,6 @@ -!.vuepress +!.vitepress /coverage -/docs/.vuepress/dist +/docs/.vitepress/dist +/docs/.vitepress/cache /node_modules diff --git a/.github/workflows/GHPages.yml b/.github/workflows/GHPages.yml index 55770eb..315eb6f 100644 --- a/.github/workflows/GHPages.yml +++ b/.github/workflows/GHPages.yml @@ -35,7 +35,6 @@ jobs: - name: Build docs run: |+ - export NODE_OPTIONS=--openssl-legacy-provider npm run docs:build - name: Setup Pages @@ -44,7 +43,7 @@ jobs: - name: Upload artifact uses: actions/upload-pages-artifact@v2 with: - path: ./docs/.vuepress/dist + path: ./docs/.vitepress/dist/eslint-plugin-eslint-comments - name: Deploy to GitHub Pages id: deployment diff --git a/.gitignore b/.gitignore index 50e3d3d..5303a54 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,8 @@ /.nyc_output /.vscode /coverage -/docs/.vuepress/dist +/docs/.vitepress/dist +/docs/.vitepress/cache /node_modules /npm-debug.log /test.js diff --git a/docs/.vitepress/.eslintrc.js b/docs/.vitepress/.eslintrc.js new file mode 100644 index 0000000..58693f5 --- /dev/null +++ b/docs/.vitepress/.eslintrc.js @@ -0,0 +1,26 @@ +"use strict" + +module.exports = { + rules: { + "n/no-missing-import": "off", + "n/no-extraneous-import": "off", + "n/file-extension-in-import": "off", + "n/no-extraneous-require": "off", + }, + globals: { + window: "readonly", + document: "readonly", + }, + overrides: [ + { + files: ["*.vue"], + rules: { + "vue/multiline-html-element-content-newline": "off", + "vue/singleline-html-element-content-newline": "off", + "vue/name-property-casing": "off", + "vue/html-self-closing": "off", + "vue/comma-dangle": "off", + }, + }, + ], +} diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs new file mode 100644 index 0000000..ac8a738 --- /dev/null +++ b/docs/.vitepress/config.mjs @@ -0,0 +1,74 @@ +import { defineConfig } from "vitepress" +import path from "path" +import { fileURLToPath } from "url" +import { vitePluginGetLinter, viteCommonjs } from "./vite-plugin.mjs" +import eslint4b from "vite-plugin-eslint4b" +import { createRequire } from "module" + +const __filename = fileURLToPath(import.meta.url) +const __dirname = path.dirname(__filename) +const require = createRequire(import.meta.url) + +const { withCategories } = require("../../scripts/lib/rules") +require("../../scripts/update-docs-headers") +require("../../scripts/update-docs-index") + +export default defineConfig({ + title: "eslint-plugin-eslint-comments", + base: "/eslint-plugin-eslint-comments/", + description: "Additional ESLint rules for ESLint directive comments.", + head: [["link", { rel: "icon", href: "/favicon.png" }]], + + outDir: path.resolve(__dirname, "./dist/eslint-plugin-eslint-comments"), + vite: { + publicDir: path.resolve(__dirname, "./public"), + plugins: [eslint4b(), vitePluginGetLinter(), viteCommonjs()], + define: { + MONACO_EDITOR_VERSION: JSON.stringify( + require("monaco-editor/package.json").version + ), + }, + }, + + lastUpdated: true, + themeConfig: { + search: { + provider: "local", + options: { + detailedView: true, + }, + }, + editLink: { + pattern: + "https://github.com/eslint-community/eslint-plugin-eslint-comments/edit/main/docs/:path", + }, + socialLinks: [ + { + icon: "github", + link: "https://github.com/eslint-community/eslint-plugin-eslint-comments", + }, + ], + + nav: [ + { text: "Guide", link: "/" }, + { text: "Rules", link: "/rules/" }, + ], + + sidebar: [ + { + items: [ + { text: "Guide", link: "/" }, + { text: "Available Rules", link: "/rules/" }, + ], + }, + ...withCategories.map(({ category, rules }) => ({ + text: `Rules in ${category}`, + collapsable: false, + items: rules.map((rule) => ({ + text: `eslint-comments/${rule.name}`, + link: `/rules/${rule.name}`, + })), + })), + ], + }, +}) diff --git a/docs/.vitepress/theme/components/eslint-editor.vue b/docs/.vitepress/theme/components/eslint-editor.vue new file mode 100644 index 0000000..bb567da --- /dev/null +++ b/docs/.vitepress/theme/components/eslint-editor.vue @@ -0,0 +1,444 @@ + + + + + + + diff --git a/docs/.vitepress/theme/components/eslint-playground.vue b/docs/.vitepress/theme/components/eslint-playground.vue new file mode 100644 index 0000000..ec0c68c --- /dev/null +++ b/docs/.vitepress/theme/components/eslint-playground.vue @@ -0,0 +1,203 @@ + + + + + diff --git a/docs/.vitepress/theme/components/monaco-editor.vue b/docs/.vitepress/theme/components/monaco-editor.vue new file mode 100644 index 0000000..74e34ff --- /dev/null +++ b/docs/.vitepress/theme/components/monaco-editor.vue @@ -0,0 +1,356 @@ + + + + + diff --git a/docs/.vitepress/theme/components/monaco/index.mjs b/docs/.vitepress/theme/components/monaco/index.mjs new file mode 100644 index 0000000..56778e3 --- /dev/null +++ b/docs/.vitepress/theme/components/monaco/index.mjs @@ -0,0 +1,2 @@ +export { setupMonacoEditor } from "./monaco-setup.mjs" +export { loadMonacoEditor } from "./monaco-loader.mjs" diff --git a/docs/.vitepress/theme/components/monaco/monaco-loader.mjs b/docs/.vitepress/theme/components/monaco/monaco-loader.mjs new file mode 100644 index 0000000..900f48e --- /dev/null +++ b/docs/.vitepress/theme/components/monaco/monaco-loader.mjs @@ -0,0 +1,69 @@ +/* globals MONACO_EDITOR_VERSION */ +async function setupMonaco() { + if (typeof window !== "undefined") { + const monacoScript = + Array.from(document.head.querySelectorAll("script")).find( + (script) => + script.src && + script.src.includes("monaco") && + script.src.includes("vs/loader") + ) || (await appendMonacoEditorScript()) + + // @ts-expect-error -- global Monaco's require + window.require.config({ + paths: { + vs: monacoScript.src.replace(/\/vs\/.*$/u, "/vs"), + }, + }) + } +} + +function appendMonacoEditorScript() { + return new Promise((resolve) => { + const script = document.createElement("script") + script.src = `https://cdnjs.cloudflare.com/ajax/libs/monaco-editor/${MONACO_EDITOR_VERSION}/min/vs/loader.min.js` + script.onload = () => { + script.onload = null + + watch() + + function watch() { + // @ts-expect-error -- global Monaco's require + if (window.require) { + resolve(script) + return + } + setTimeout(watch, 200) + } + } + document.head.append(script) + }) +} + +let setupedMonaco = null +let editorLoaded = null + +export function loadMonacoEngine() { + return setupedMonaco || (setupedMonaco = setupMonaco()) +} +export function loadMonacoEditor() { + if (editorLoaded) { + return editorLoaded + } + return (editorLoaded = (async () => { + const monaco = await loadModuleFromMonaco("vs/editor/editor.main") + return monaco + })()) +} + +export async function loadModuleFromMonaco(moduleName) { + await loadMonacoEngine() + return new Promise((resolve) => { + if (typeof window !== "undefined") { + // @ts-expect-error -- global Monaco's require + window.require([moduleName], (r) => { + resolve(r) + }) + } + }) +} diff --git a/docs/.vitepress/theme/components/monaco/monaco-setup.mjs b/docs/.vitepress/theme/components/monaco/monaco-setup.mjs new file mode 100644 index 0000000..360d7f1 --- /dev/null +++ b/docs/.vitepress/theme/components/monaco/monaco-setup.mjs @@ -0,0 +1,221 @@ +import { loadMonacoEditor } from "./monaco-loader.mjs" + +/** Setup editor */ +export async function setupMonacoEditor({ + init, + listeners, + useDiffEditor, + rootElement, +}) { + const monaco = await loadMonacoEditor() + const language = init.language + + const options = { + value: init.value, + readOnly: init.readOnly, + theme: "vs-dark", + language, + automaticLayout: true, + fontSize: 14, + // tabSize: 2, + minimap: { + enabled: false, + }, + renderControlCharacters: true, + renderIndentGuides: true, + renderValidationDecorations: "on", + renderWhitespace: "boundary", + scrollBeyondLastLine: false, + scrollbar: { alwaysConsumeMouseWheel: false }, + unusualLineTerminators: "off", + } + + if (useDiffEditor) { + const diffEditor = monaco.editor.createDiffEditor(rootElement, { + originalEditable: true, + ...options, + }) + const original = monaco.editor.createModel(init.value, language) + const modified = monaco.editor.createModel( + init.right?.value || "", + language + ) + + const leftEditor = diffEditor.getOriginalEditor() + const rightEditor = diffEditor.getModifiedEditor() + rightEditor.updateOptions({ readOnly: true }) + diffEditor.setModel({ original, modified }) + original.onDidChangeContent(() => { + const value = original.getValue() + listeners?.onChangeValue?.(value) + }) + leftEditor.onDidChangeCursorPosition((evt) => { + listeners?.onDidChangeCursorPosition?.(evt) + }) + leftEditor.onDidFocusEditorText(() => { + listeners?.onFocus?.() + }) + + const registerCodeActionProvider = buildRegisterCodeActionProvider( + leftEditor, + language + ) + + const result = { + setModelLanguage(lang) { + for (const model of [original, modified]) { + monaco.editor.setModelLanguage(model, lang) + } + registerCodeActionProvider.setLanguage(lang) + }, + setLeftValue(code) { + const value = original.getValue() + if (code !== value) { + original.setValue(code) + } + }, + setRightValue(code) { + const value = modified.getValue() + if (code !== value) { + modified.setValue(code) + } + }, + setLeftMarkers(markers) { + updateMarkers(leftEditor, markers) + }, + setRightMarkers(markers) { + updateMarkers(rightEditor, markers) + }, + getLeftEditor: () => leftEditor, + getRightEditor: () => rightEditor, + + registerCodeActionProvider: registerCodeActionProvider.register, + disposeEditor() { + registerCodeActionProvider.dispose() + leftEditor.getModel()?.dispose() + rightEditor.getModel()?.dispose() + leftEditor.dispose() + rightEditor.dispose() + diffEditor.dispose() + }, + } + if (init.markers) { + result.setLeftMarkers(init.markers) + } + if (init.right?.markers) { + result.setRightMarkers(init.right?.markers) + } + + return result + } + const standaloneEditor = monaco.editor.create(rootElement, options) + + standaloneEditor.onDidChangeModelContent(() => { + const value = standaloneEditor.getValue() + listeners?.onChangeValue?.(value) + }) + standaloneEditor.onDidChangeCursorPosition((evt) => { + listeners?.onDidChangeCursorPosition?.(evt) + }) + standaloneEditor.onDidFocusEditorText(() => { + listeners?.onFocus?.() + }) + + const registerCodeActionProvider = buildRegisterCodeActionProvider( + standaloneEditor, + language + ) + const result = { + setModelLanguage(lang) { + const model = standaloneEditor.getModel() + if (model) { + monaco.editor.setModelLanguage(model, lang) + } + registerCodeActionProvider.setLanguage(lang) + }, + setLeftValue(code) { + const value = standaloneEditor.getValue() + if (code !== value) { + standaloneEditor.setValue(code) + } + }, + setRightValue() { + /* noop */ + }, + setLeftMarkers(markers) { + updateMarkers(standaloneEditor, markers) + }, + setRightMarkers() { + /* noop */ + }, + getLeftEditor: () => standaloneEditor, + getRightEditor: () => null, + + registerCodeActionProvider: registerCodeActionProvider.register, + disposeEditor() { + registerCodeActionProvider.dispose() + standaloneEditor.getModel()?.dispose() + standaloneEditor.dispose() + }, + } + if (init.markers) { + result.setLeftMarkers(init.markers) + } + return result + + /** Update markers */ + function updateMarkers(editor, markers) { + const model = editor.getModel() + const id = editor.getId() + monaco.editor.setModelMarkers( + model, + id, + JSON.parse(JSON.stringify(markers)) + ) + } + + function buildRegisterCodeActionProvider(editor, initLanguage) { + let codeActionProviderDisposable = { + dispose() { + // void + }, + } + let currProvideCodeActions = null + let currLanguage = initLanguage + + function register() { + codeActionProviderDisposable.dispose() + codeActionProviderDisposable = + monaco.languages.registerCodeActionProvider(currLanguage, { + provideCodeActions(model, ...args) { + if ( + !currProvideCodeActions || + editor.getModel().uri !== model.uri + ) { + return { + actions: [], + dispose() { + /* nop */ + }, + } + } + return currProvideCodeActions(model, ...args) + }, + }) + } + + return { + setLanguage(lang) { + currLanguage = lang + register() + }, + register(provideCodeActions) { + currProvideCodeActions = provideCodeActions + register() + }, + dispose() { + codeActionProviderDisposable.dispose() + }, + } + } +} diff --git a/docs/.vitepress/theme/index.mjs b/docs/.vitepress/theme/index.mjs new file mode 100644 index 0000000..ecb67c3 --- /dev/null +++ b/docs/.vitepress/theme/index.mjs @@ -0,0 +1,20 @@ +// eslint-disable-next-line @eslint-community/mysticatea/node/no-missing-import +import DefaultTheme from "vitepress/theme" +// eslint-disable-next-line @eslint-community/mysticatea/node/no-extraneous-import +import { defineAsyncComponent } from "vue" +import "./style.css" + +/** @type {import('vitepress').Theme} */ +const theme = { + extends: DefaultTheme, + enhanceApp(ctx) { + ctx.app.component( + "eslint-playground", + defineAsyncComponent({ + // @ts-expect-error -- ignore + loader: () => import("./components/eslint-playground.vue"), + }) + ) + }, +} +export default theme diff --git a/docs/.vitepress/theme/style.css b/docs/.vitepress/theme/style.css new file mode 100644 index 0000000..8352d6d --- /dev/null +++ b/docs/.vitepress/theme/style.css @@ -0,0 +1,27 @@ +:root { + --color-primary-200: #dedeff; + --color-primary-300: #ccccfa; + --color-primary-400: #b7b7ff; + --color-primary-500: #a0a0f5; + --color-primary-600: #8080f2; + --color-primary-700: #6358d4; + --color-primary-800: #4b32c3; + --color-primary-900: #341bab; + --vp-c-brand: var(--color-primary-800); + --vp-c-brand-light: var(--color-primary-600); + --vp-c-brand-lighter: var(--color-primary-500); + --vp-c-brand-dark: var(--color-primary-900); + --vp-c-brand-darker: var(--color-primary-900); +} + +.dark { + --vp-c-brand: var(--color-primary-400); + --vp-c-brand-light: var(--color-primary-300); + --vp-c-brand-lighter: var(--color-primary-200); + --vp-c-brand-dark: var(--color-primary-700); + --vp-c-brand-darker: var(--color-primary-800); +} + +a > img { + display: inline-block; +} diff --git a/docs/.vitepress/vite-plugin.mjs b/docs/.vitepress/vite-plugin.mjs new file mode 100644 index 0000000..31372ca --- /dev/null +++ b/docs/.vitepress/vite-plugin.mjs @@ -0,0 +1,87 @@ +import path from "path" +import { fileURLToPath } from "url" +import esbuild from "esbuild" + +const __filename = fileURLToPath(import.meta.url) +const __dirname = path.dirname(__filename) + +const pluginRoot = path.join(__dirname, "../..") +const libRoot = path.join(pluginRoot, "lib") +const index = path.join(pluginRoot, "index.js") + +export function vitePluginGetLinter() { + return { + name: "vite-plugin-get-linter", + transform(_code, id, _options) { + if ( + id.startsWith(libRoot) && + /internal[\\/]get-linters\.js$/u.test(id) + ) { + return 'module.exports = () => [require("eslint").Linter]' + } + return undefined + }, + } +} + +export function viteCommonjs() { + return { + name: "vite-plugin-cjs-to-esm", + apply: () => true, + transform(code, id) { + if (!id.startsWith(libRoot) && !id.startsWith(index)) { + return undefined + } + const base = transformRequire(code) + try { + // eslint-disable-next-line @eslint-community/mysticatea/node/no-sync + const transformed = esbuild.transformSync(base, { + format: "esm", + }) + return transformed.code + } catch (e) { + console.error(`Transform error. base code:\n${base}`, e) + } + return undefined + }, + } +} + +/** + * Transform `require()` to `import` + */ +function transformRequire(code) { + if (!code.includes("require")) { + return code + } + const modules = new Map() + const replaced = code.replace( + /(\/\/[^\n\r]*|\/\*[\s\S]*?\*\/)|\brequire\s*\(\s*(["'].*?["'])\s*\)/gu, + (match, comment, moduleString) => { + if (comment) { + return match + } + + let id = `__${moduleString.replace( + /[^a-zA-Z0-9_$]+/gu, + "_" + )}${Math.random().toString(32).substring(2)}` + while (code.includes(id) || modules.has(id)) { + id += Math.random().toString(32).substring(2) + } + modules.set(id, moduleString) + return id + } + ) + + return `${[...modules] + .map( + ([ + id, + moduleString, + ]) => `import * as __temp_${id} from ${moduleString}; +const ${id} = __temp_${id}.default || __temp_${id}; +` + ) + .join("")};\n${replaced}` +} diff --git a/docs/.vuepress/components/eslint-playground.vue b/docs/.vuepress/components/eslint-playground.vue deleted file mode 100644 index 5ba1cb9..0000000 --- a/docs/.vuepress/components/eslint-playground.vue +++ /dev/null @@ -1,125 +0,0 @@ - - - - - diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js deleted file mode 100644 index ad6dc4c..0000000 --- a/docs/.vuepress/config.js +++ /dev/null @@ -1,82 +0,0 @@ -"use strict" - -const path = require("path") -const webpack = require("webpack") -const { withCategories } = require("../../scripts/lib/rules") -require("../../scripts/update-docs-headers") -require("../../scripts/update-docs-index") - -module.exports = { - base: "/eslint-plugin-eslint-comments/", - title: "@eslint-community/eslint-plugin-eslint-comments", - description: "Additional ESLint rules for ESLint directive comments.", - evergreen: true, - - plugins: { - "@vuepress/pwa": { updatePopup: true }, - }, - - themeConfig: { - repo: "eslint-community/eslint-plugin-eslint-comments", - docsRepo: "eslint-community/eslint-plugin-eslint-comments", - docsDir: "docs", - docsBranch: "main", - editLinks: true, - search: false, - - nav: [ - { - text: "Changelog", - link: "https://github.com/eslint-community/eslint-plugin-eslint-comments/releases", - }, - ], - - sidebarDepth: 0, - sidebar: { - "/": [ - "/", - "/rules/", - ...withCategories.map(({ category, rules }) => ({ - title: `Rules in ${category}`, - collapsable: false, - children: rules.map((rule) => `/rules/${rule.name}`), - })), - ], - }, - }, - - enhanceAppFiles: require.resolve("./enhanceApp.mjs"), - configureWebpack: { - plugins: [ - new webpack.DefinePlugin({ - "process.env.TIMING": JSON.stringify(""), - }), - ], - resolve: { - alias: { - esquery: path.resolve( - __dirname, - "../../node_modules/esquery/dist/esquery.min.js" - ), - "@eslint/eslintrc/universal": path.resolve( - __dirname, - "../../node_modules/@eslint/eslintrc/dist/eslintrc-universal.cjs" - ), - }, - }, - module: { - rules: [ - { - test: /internal[\\/]get-linters\.js$/u, - loader: "string-replace-loader", - options: { - search: "[\\s\\S]+", // whole file. - replace: - 'module.exports = () => [require("eslint/lib/linter").Linter]', - flags: "g", - }, - }, - ], - }, - }, -} diff --git a/docs/.vuepress/enhanceApp.mjs b/docs/.vuepress/enhanceApp.mjs deleted file mode 100644 index 9e95e20..0000000 --- a/docs/.vuepress/enhanceApp.mjs +++ /dev/null @@ -1,10 +0,0 @@ -/* globals window */ -export default () => { - if (typeof window !== "undefined") { - if (typeof window.process === "undefined") { - window.process = { - cwd: () => undefined, - } - } - } -} diff --git a/docs/.vuepress/public/.nojekyll b/docs/.vuepress/public/.nojekyll deleted file mode 100644 index e69de29..0000000 diff --git a/docs/.vuepress/styles/index.styl b/docs/.vuepress/styles/index.styl deleted file mode 100644 index 05e005a..0000000 --- a/docs/.vuepress/styles/index.styl +++ /dev/null @@ -1,2 +0,0 @@ -table a - white-space nowrap diff --git a/docs/.vuepress/styles/palette.styl b/docs/.vuepress/styles/palette.styl deleted file mode 100644 index fa76bfb..0000000 --- a/docs/.vuepress/styles/palette.styl +++ /dev/null @@ -1 +0,0 @@ -$accentColor = #463fd4 diff --git a/docs/README.md b/docs/index.md similarity index 99% rename from docs/README.md rename to docs/index.md index 5063a83..90da2ee 100644 --- a/docs/README.md +++ b/docs/index.md @@ -4,7 +4,7 @@ [![Downloads/month](https://img.shields.io/npm/dm/@eslint-community/eslint-plugin-eslint-comments.svg)](http://www.npmtrends.com/@eslint-community/eslint-plugin-eslint-comments) [![Build Status](https://github.com/eslint-community/eslint-plugin-eslint-comments/workflows/CI/badge.svg)](https://github.com/eslint-community/eslint-plugin-eslint-comments/actions) [![codecov](https://codecov.io/gh/eslint-community/eslint-plugin-eslint-comments/branch/main/graph/badge.svg)](https://codecov.io/gh/eslint-community/eslint-plugin-eslint-comments) -[ + Additional ESLint rules for ESLint directive comments (e.g. `//eslint-disable-line`). ## 🏁 Goal diff --git a/docs/rules/disable-enable-pair.md b/docs/rules/disable-enable-pair.md index b2c1992..9d37cdb 100644 --- a/docs/rules/disable-enable-pair.md +++ b/docs/rules/disable-enable-pair.md @@ -13,34 +13,54 @@ This rule warns `eslint-disable` directive-comments if the `eslint-enable` direc Examples of :-1: **incorrect** code for this rule: - + +```js +/*eslint @eslint-community/eslint-comments/disable-enable-pair: error */ /*eslint-disable no-undef, no-unused-vars */ var foo = bar() -" /> +``` + + - + +```js +/*eslint @eslint-community/eslint-comments/disable-enable-pair: error */ /*eslint-disable no-undef, no-unused-vars */ var foo = bar() /*eslint-enable no-unused-vars */ -" /> +``` + + Examples of :+1: **correct** code for this rule: - + +```js +/*eslint @eslint-community/eslint-comments/disable-enable-pair: error */ /*eslint-disable no-undef, no-unused-vars */ var foo = bar() /*eslint-enable no-undef, no-unused-vars */ -" /> +``` + + - + +```js +/*eslint @eslint-community/eslint-comments/disable-enable-pair: error */ /*eslint-disable no-undef, no-unused-vars */ var foo = bar() /*eslint-enable*/ -" /> +``` + + ## Options @@ -54,21 +74,31 @@ The `allowWholeFile` option lets you allow disabling rules for the entire file w Examples of :-1: **incorrect** code for this rule: - + +```js +/*eslint @eslint-community/eslint-comments/disable-enable-pair: [error, {allowWholeFile: true}] */ /*eslint-disable no-undef */ var foo = bar() /*eslint-disable no-unused-vars */ var fizz = buzz() -" /> +``` + + Examples of :+1: **correct** code for this rule: - + +```js +/*eslint @eslint-community/eslint-comments/disable-enable-pair: [error, {allowWholeFile: true}] */ /*eslint-disable no-undef */ var foo = bar() /*eslint-disable no-unused-vars */ var fizz = buzz() /*eslint-enable no-unused-vars */ -" /> +``` + + diff --git a/docs/rules/README.md b/docs/rules/index.md similarity index 100% rename from docs/rules/README.md rename to docs/rules/index.md diff --git a/docs/rules/no-aggregating-enable.md b/docs/rules/no-aggregating-enable.md index 51d9632..c1bb866 100644 --- a/docs/rules/no-aggregating-enable.md +++ b/docs/rules/no-aggregating-enable.md @@ -21,27 +21,40 @@ This rule warns `eslint-enable` directive-comments which enable rules for multip :-1: Examples of **incorrect** code for this rule: - + +```js +/*eslint @eslint-community/eslint-comments/no-aggregating-enable: error*/ /*eslint-disable no-undef */ f() /*eslint-disable no-var */ var a /*eslint-enable */ -" /> +``` - + +```js +/*eslint @eslint-community/eslint-comments/no-aggregating-enable: error*/ /*eslint-disable no-undef */ f() /*eslint-disable no-var */ var a /*eslint-enable no-undef, no-var */ -" /> +``` + + :+1: Examples of **correct** code for this rule: - + +```js +/*eslint @eslint-community/eslint-comments/no-aggregating-enable: error*/ /*eslint-disable no-undef */ f() @@ -50,4 +63,6 @@ var a /*eslint-enable no-var */ /*eslint-enable no-undef */ -" /> +``` + + diff --git a/docs/rules/no-duplicate-disable.md b/docs/rules/no-duplicate-disable.md index 40a554b..0eb8827 100644 --- a/docs/rules/no-duplicate-disable.md +++ b/docs/rules/no-duplicate-disable.md @@ -13,23 +13,38 @@ This rule warns duplicate `eslint-disable` directive-comments. Examples of :-1: **incorrect** code for this rule: - + +```js +/*eslint @eslint-community/eslint-comments/no-duplicate-disable: error */ /*eslint-disable no-undef */ var foo = bar() //eslint-disable-line no-undef -" /> +``` + + Examples of :+1: **correct** code for this rule: - + +```js +/*eslint @eslint-community/eslint-comments/no-duplicate-disable: error */ /*eslint-disable no-undef */ var foo = bar() -" /> +``` - + +```js +/*eslint @eslint-community/eslint-comments/no-duplicate-disable: error */ var foo = bar() //eslint-disable-line no-undef -" /> +``` + + diff --git a/docs/rules/no-restricted-disable.md b/docs/rules/no-restricted-disable.md index 029f917..91c05ff 100644 --- a/docs/rules/no-restricted-disable.md +++ b/docs/rules/no-restricted-disable.md @@ -8,28 +8,48 @@ This rule warns `eslint-disable` directive-comments if the comment disable speci :-1: Examples of **incorrect** code for this rule: - + +```js +/*eslint @eslint-community/eslint-comments/no-restricted-disable: [error, no-undef, no-unused-vars]*/ /*eslint-disable no-undef */ f() -" /> +``` + + - + +```js +/*eslint @eslint-community/eslint-comments/no-restricted-disable: [error, no-undef, no-unused-vars]*/ f() //eslint-disable-line no-undef -" /> +``` + + - + +```js +/*eslint @eslint-community/eslint-comments/no-restricted-disable: [error, no-undef, no-unused-vars]*/ f() //eslint-disable-line -" /> +``` + + :+1: Examples of **correct** code for this rule: - + +```js +/*eslint @eslint-community/eslint-comments/no-restricted-disable: [error, no-undef, no-unused-vars]*/ f() //eslint-disable-line another-rule -" /> +``` + + ## Options diff --git a/docs/rules/no-unlimited-disable.md b/docs/rules/no-unlimited-disable.md index 3874d8a..263cc50 100644 --- a/docs/rules/no-unlimited-disable.md +++ b/docs/rules/no-unlimited-disable.md @@ -11,14 +11,24 @@ So you should specify the rules to disable accurately. Examples of :-1: **incorrect** code for this rule: - + +```js +/*eslint @eslint-community/eslint-comments/no-unlimited-disable: error */ var foo; //eslint-disable-line -" /> +``` + + Examples of :+1: **correct** code for this rule: - + +```js +/*eslint @eslint-community/eslint-comments/no-unlimited-disable: error */ var foo; //eslint-disable-line no-unused-vars -" /> +``` + + diff --git a/docs/rules/no-unused-disable.md b/docs/rules/no-unused-disable.md index 3952547..78139d1 100644 --- a/docs/rules/no-unused-disable.md +++ b/docs/rules/no-unused-disable.md @@ -11,29 +11,49 @@ This rule warns unnecessary `eslint-disable` directive-comments. Examples of :-1: **incorrect** code for this rule: - + +```js +/*eslint @eslint-community/eslint-comments/no-unused-disable: error, eqeqeq: error, no-undef: error */ var foo = bar() //eslint-disable-line no-undef,eqeqeq -" /> +``` + + - + +```js +/*eslint @eslint-community/eslint-comments/no-unused-disable: error, eqeqeq: error, no-undef: error */ /*globals doSomething */ doSomething() //eslint-disable-line -" /> +``` + + Examples of :+1: **correct** code for this rule: - + +```js +/*eslint @eslint-community/eslint-comments/no-unused-disable: error, eqeqeq: error, no-undef: error */ var foo = bar() //eslint-disable-line no-undef -" /> +``` + + - + +```js +/*eslint @eslint-community/eslint-comments/no-unused-disable: error, eqeqeq: error, no-undef: error */ /*globals doSomething */ doSomething() -" /> +``` + + ## Known limitations diff --git a/docs/rules/no-unused-enable.md b/docs/rules/no-unused-enable.md index 7e81182..920d8c7 100644 --- a/docs/rules/no-unused-enable.md +++ b/docs/rules/no-unused-enable.md @@ -10,29 +10,49 @@ This rule warns `eslint-enable` directive-comments which have no effect. Examples of :-1: **incorrect** code for this rule: - + +```js +/*eslint @eslint-community/eslint-comments/no-unused-enable: error */ /*eslint-disable no-undef */ doSomething() /*eslint-enable no-undef-init */ -" /> +``` + + - + +```js +/*eslint @eslint-community/eslint-comments/no-unused-enable: error */ doSomething() /*eslint-enable */ -" /> +``` + + Examples of :+1: **correct** code for this rule: - + +```js +/*eslint @eslint-community/eslint-comments/no-unused-enable: error */ /*eslint-disable no-undef */ doSomething() /*eslint-enable no-undef */ -" /> +``` + + - + +```js +/*eslint @eslint-community/eslint-comments/no-unused-enable: error */ doSomething() -" /> +``` + + diff --git a/docs/rules/no-use.md b/docs/rules/no-use.md index ba738ac..1ebaecc 100644 --- a/docs/rules/no-use.md +++ b/docs/rules/no-use.md @@ -9,7 +9,10 @@ This rule disallows a use of directive-comments. Examples of :-1: **incorrect** code for this rule: - + +```js +/*eslint @eslint-community/eslint-comments/no-use: error */ /* eslint no-undef: off */ /* eslint-env browser */ @@ -20,7 +23,9 @@ Examples of :-1: **incorrect** code for this rule: /* exported foo */ /* global $ */ /* globals a, b, c */ -" /> +``` + + ## Options diff --git a/docs/rules/require-description.md b/docs/rules/require-description.md index 4a92e48..b917e79 100644 --- a/docs/rules/require-description.md +++ b/docs/rules/require-description.md @@ -12,7 +12,10 @@ This rule can only be used with ESLint v7.x or later. Examples of :-1: **incorrect** code for this rule: - + +```js +/*eslint @eslint-community/eslint-comments/require-description: error */ /* eslint no-undef: off */ /* eslint-env browser */ @@ -23,17 +26,24 @@ Examples of :-1: **incorrect** code for this rule: /* exported foo */ /* global $ */ /* globals a, b, c */ -" /> +``` + + Examples of :+1: **correct** code for this rule: - + +```js +/*eslint @eslint-community/eslint-comments/require-description: error -- If you use directive comments, you should explain why you use them. */ /* eslint no-undef: off -- Here's a description about why this directive-comment is necessary. */ /* eslint-env browser -- This script works in browser. */ // eslint-disable-next-line -- Temporarily avoids the lint error problem. See issue XXX. /* global $ -- This script using jQuery. */ -" /> +``` + + ## Options diff --git a/package.json b/package.json index 1869fe9..fd8405f 100644 --- a/package.json +++ b/package.json @@ -23,25 +23,25 @@ "@types/node": "^14.18.54", "@vuepress/plugin-pwa": "^1.9.9", "cross-spawn": "^7.0.3", + "esbuild": "^0.19.3", "eslint": "^8.46.0", "fs-extra": "^10.1.0", "mocha": "^9.2.2", + "monaco-editor": "^0.43.0", "nyc": "^15.1.0", "opener": "^1.5.2", "rimraf": "^3.0.2", "semver": "^7.5.4", - "string-replace-loader": "^2.3.0", - "vue-eslint-editor": "^1.1.0", - "vuepress": "^1.9.9", - "webpack": "^4.47.0" + "vite-plugin-eslint4b": "^0.2.1", + "vitepress": "^1.0.0-rc.15" }, "scripts": { "preversion": "npm test", "version": "node scripts/update && git add .", "postversion": "git push && git push --tags", - "clean": "rimraf .nyc_output coverage docs/.vuepress/dist", - "docs:build": "vuepress build docs", - "docs:watch": "vuepress dev docs", + "clean": "rimraf .nyc_output coverage docs/.vitepress/cache", + "docs:build": "vitepress build docs", + "docs:watch": "vitepress dev docs", "lint": "eslint lib scripts tests", "test": "nyc mocha \"tests/lib/**/*.js\" --reporter dot --timeout 8000", "coverage": "nyc report --reporter lcov && opener coverage/lcov-report/index.html", diff --git a/scripts/update-docs-index.js b/scripts/update-docs-index.js index f86ca98..f45fee5 100644 --- a/scripts/update-docs-index.js +++ b/scripts/update-docs-index.js @@ -35,7 +35,7 @@ ${rules.map(toTableRow).join("\n")} } fs.writeFileSync( - path.resolve(__dirname, "../docs/rules/README.md"), + path.resolve(__dirname, "../docs/rules/index.md"), `# Available Rules - 🌟 mark: the rule which is enabled by \`@eslint-community/eslint-comments/recommended\` preset.