Add option to not report errors if documentation of class names exist to no-unused-selector and require-selector-used-inside.

docs/rules/no-unused-selector.md

@@ -88,12 +88,14 @@ This is a limitation of this rule. Without this limitation, the root element can
 ```json
 {
   "vue-scoped-css/no-unused-selector": ["error", {
-    "ignoreBEMModifier": false
+    "ignoreBEMModifier": false,
+    "captureClassesFromDoc": []
   }]
 }
 ```
 
 - `ignoreBEMModifier` ... Set `true` if you want to ignore the `BEM` modifier. Default is false.
+- `captureClassesFromDoc` ... Specifies the regexp that extracts the class name from the documentation in the comments. Even if there is no matching element, no error is reported if the document of a class name exists in the comments.
 
 ### `"ignoreBEMModifier": true`
 
@@ -111,13 +113,49 @@ This is a limitation of this rule. Without this limitation, the root element can
 
 </eslint-code-block>
 
+### `"captureClassesFromDoc": [ "/(\\.[a-z-]+)(?::[a-z-]+)?\\s+-\\s*[^\\r\\n]+/i" ]`
+
+Example of [KSS] format:
+
+<eslint-code-block :rules="{'vue-scoped-css/no-unused-selector': ['error', {captureClassesFromDoc: ['/(\\.[a-z-]+)(?::[a-z-]+)?\\s+-\\s*[^\\r\\n]+/i']}]}">
+
+```vue
+<template>
+  <div>
+    <a class="button star"></a>
+  </div>
+</template>
+<style scoped lang="scss">
+/* ✓ GOOD */
+
+// A button suitable for giving a star to someone.
+//
+// :hover             - Subtle hover highlight.
+// .star-given        - A highlight indicating you've already given a star.
+// .star-given:hover  - Subtle hover highlight on top of star-given styling.
+// .disabled          - Dims the button to indicate it cannot be used.
+//
+// Styleguide 2.1.3.
+a.button.star {
+  &.star-given {
+  }
+  &.disabled {
+  }
+}
+</style>
+```
+
+</eslint-code-block>
+
 ## :books: Further reading
 
 - [vue-scoped-css/require-selector-used-inside]
 - [Vue Loader - Scoped CSS]
+- [KSS]
 
 [Vue Loader - Scoped CSS]: https://vue-loader.vuejs.org/guide/scoped-css.html
 [vue-scoped-css/require-selector-used-inside]: ./require-selector-used-inside.md
+[KSS]: http://warpspire.com/kss/
 
 ## Implementation
 

docs/rules/require-selector-used-inside.md

@@ -53,20 +53,74 @@ div {}
 ```json
 {
   "vue-scoped-css/require-selector-used-inside": ["error", {
-    "ignoreBEMModifier": false
+    "ignoreBEMModifier": false,
+    "captureClassesFromDoc": []
   }]
 }
 ```
 
 - `ignoreBEMModifier` ... Set `true` if you want to ignore the `BEM` modifier. Default is false.
+- `captureClassesFromDoc` ... Specifies the regexp that extracts the class name from the documentation in the comments. Even if there is no matching element, no error is reported if the document of a class name exists in the comments.
+
+### `"ignoreBEMModifier": true`
+
+<eslint-code-block :rules="{'vue-scoped-css/require-selector-used-inside': ['error', {ignoreBEMModifier: true}]}">
+
+```vue
+<template>
+  <div class="cool-component"></div>
+</template>
+<style scoped>
+/* ✓ GOOD */
+.cool-component--active {}
+</style>
+```
+
+</eslint-code-block>
+
+### `"captureClassesFromDoc": [ "/(\\.[a-z-]+)(?::[a-z-]+)?\\s+-\\s*[^\\r\\n]+/i" ]`
+
+Example of [KSS] format:
+
+<eslint-code-block :rules="{'vue-scoped-css/require-selector-used-inside': ['error', {captureClassesFromDoc: ['/(\\.[a-z-]+)(?::[a-z-]+)?\\s+-\\s*[^\\r\\n]+/i']}]}">
+
+```vue
+<template>
+  <div>
+    <a class="button star"></a>
+  </div>
+</template>
+<style scoped lang="scss">
+/* ✓ GOOD */
+
+// A button suitable for giving a star to someone.
+//
+// :hover             - Subtle hover highlight.
+// .star-given        - A highlight indicating you've already given a star.
+// .star-given:hover  - Subtle hover highlight on top of star-given styling.
+// .disabled          - Dims the button to indicate it cannot be used.
+//
+// Styleguide 2.1.3.
+a.button.star {
+  &.star-given {
+  }
+  &.disabled {
+  }
+}
+</style>
+```
+
+</eslint-code-block>
 
 ## :books: Further reading
 
 - [vue-scoped-css/no-unused-selector]
 - [Vue Loader - Scoped CSS]
+- [KSS]
 
 [Vue Loader - Scoped CSS]: https://vue-loader.vuejs.org/guide/scoped-css.html
 [vue-scoped-css/no-unused-selector]: ./no-unused-selector.md
+[KSS]: http://warpspire.com/kss/
 
 ## Implementation
 

lib/options.ts

@@ -1,3 +1,28 @@
+import { toRegExp } from "./utils/regexp"
+
 export interface QueryOptions {
     ignoreBEMModifier?: boolean
+    captureClassesFromDoc?: string[]
+}
+
+export interface ParsedQueryOptions {
+    ignoreBEMModifier: boolean
+    captureClassesFromDoc: RegExp[]
+}
+
+export namespace ParsedQueryOptions {
+    /**
+     * Parse options
+     */
+    export function parse(
+        options: QueryOptions | undefined,
+    ): ParsedQueryOptions {
+        const { ignoreBEMModifier, captureClassesFromDoc } = options || {}
+
+        return {
+            ignoreBEMModifier: ignoreBEMModifier ?? false,
+            captureClassesFromDoc:
+                captureClassesFromDoc?.map(s => toRegExp(s, "g")) ?? [],
+        }
+    }
 }

lib/rules/no-parsing-error.ts

@@ -1,10 +1,10 @@
+import { RuleContext } from "../types"
+import { VCSSParsingError } from "../styles/ast"
 import {
     getStyleContexts,
     getCommentDirectivesReporter,
-    StyleContext,
-} from "../styles"
-import { RuleContext, LineAndColumnData } from "../types"
-import { VCSSParsingError } from "../styles/ast"
+    InvalidStyleContext,
+} from "../styles/context"
 
 module.exports = {
     meta: {
@@ -48,15 +48,7 @@ module.exports = {
          * Reports the given style
          * @param {ASTNode} node node to report
          */
-        function reportInvalidStyle(
-            style: StyleContext & {
-                invalid: {
-                    message: string
-                    needReport: boolean
-                    loc: LineAndColumnData
-                }
-            },
-        ) {
+        function reportInvalidStyle(style: InvalidStyleContext) {
             reporter.report({
                 node: style.styleElement,
                 loc: style.invalid.loc,
@@ -72,15 +64,7 @@ module.exports = {
                 for (const style of styles) {
                     if (style.invalid != null) {
                         if (style.invalid.needReport) {
-                            reportInvalidStyle(
-                                style as StyleContext & {
-                                    invalid: {
-                                        message: string
-                                        needReport: boolean
-                                        loc: LineAndColumnData
-                                    }
-                                },
-                            )
+                            reportInvalidStyle(style)
                         }
                     } else {
                         for (const node of style.cssNode?.errors || []) {

lib/rules/no-unused-keyframes.ts

@@ -1,11 +1,12 @@
+import { VCSSAtRule, VCSSDeclarationProperty } from "../styles/ast"
+import { RuleContext } from "../types"
+import { Template } from "../styles/template"
 import {
     getStyleContexts,
     getCommentDirectivesReporter,
+    ValidStyleContext,
     StyleContext,
-} from "../styles"
-import { VCSSAtRule, VCSSDeclarationProperty } from "../styles/ast"
-import { RuleContext } from "../types"
-import { Template } from "../styles/template"
+} from "../styles/context"
 
 module.exports = {
     meta: {
@@ -24,9 +25,9 @@ module.exports = {
         type: "suggestion", // "problem",
     },
     create(context: RuleContext) {
-        const styles = getStyleContexts(context).filter(
-            style => !style.invalid && style.scoped,
-        )
+        const styles = getStyleContexts(context)
+            .filter(StyleContext.isValid)
+            .filter(style => style.scoped)
         if (!styles.length) {
             return {}
         }
@@ -59,7 +60,7 @@ module.exports = {
          * Extract nodes
          */
         function extract(
-            style: StyleContext,
+            style: ValidStyleContext,
         ): {
             keyframes: { node: VCSSAtRule; params: Template }[]
             animationNames: VCSSDeclarationProperty[]
@@ -106,7 +107,7 @@ module.exports = {
         /**
          * Verify the style
          */
-        function verify(style: StyleContext) {
+        function verify(style: ValidStyleContext) {
             const { keyframes, animationNames, animations } = extract(style)
 
             for (const decl of animationNames) {

lib/rules/no-unused-selector.ts

@@ -1,11 +1,4 @@
-import {
-    getStyleContexts,
-    getCommentDirectivesReporter,
-    StyleContext,
-} from "../styles"
-
 import { getResolvedSelectors, ResolvedSelector } from "../styles/selectors"
-
 import { VCSSSelectorNode, VCSSSelectorCombinator } from "../styles/ast"
 import {
     isTypeSelector,
@@ -18,17 +11,23 @@ import {
     isGeneralSiblingCombinator,
     isDeepCombinator,
 } from "../styles/utils/selectors"
-
 import { createQueryContext, QueryContext } from "../styles/selectors/query"
 import { isRootElement } from "../styles/selectors/query/elements"
 import { RuleContext } from "../types"
+import { ParsedQueryOptions } from "../options"
+import {
+    ValidStyleContext,
+    getStyleContexts,
+    StyleContext,
+    getCommentDirectivesReporter,
+} from "../styles/context"
 
 /**
  * Gets scoped selectors.
  * @param {StyleContext} style The style context
  * @returns {VCSSSelectorNode[][]} selectors
  */
-function getScopedSelectors(style: StyleContext): VCSSSelectorNode[][] {
+function getScopedSelectors(style: ValidStyleContext): VCSSSelectorNode[][] {
     const resolvedSelectors = getResolvedSelectors(style)
     return resolvedSelectors.map(getScopedSelector)
 }
@@ -84,16 +83,26 @@ module.exports = {
                     ignoreBEMModifier: {
                         type: "boolean",
                     },
+                    captureClassesFromDoc: {
+                        type: "array",
+                        items: [
+                            {
+                                type: "string",
+                            },
+                        ],
+                        minItems: 0,
+                        uniqueItems: true,
+                    },
                 },
                 additionalProperties: false,
             },
         ],
         type: "suggestion", // "problem",
     },
     create(context: RuleContext) {
-        const styles = getStyleContexts(context).filter(
-            style => !style.invalid && style.scoped,
-        )
+        const styles = getStyleContexts(context)
+            .filter(StyleContext.isValid)
+            .filter(style => style.scoped)
         if (!styles.length) {
             return {}
         }
@@ -215,7 +224,7 @@ module.exports = {
             "Program:exit"() {
                 const queryContext = createQueryContext(
                     context,
-                    context.options[0] || {},
+                    ParsedQueryOptions.parse(context.options[0]),
                 )
 
                 for (const style of styles) {

lib/rules/require-scoped.ts

@@ -1,5 +1,9 @@
-import { getStyleContexts, getCommentDirectivesReporter } from "../styles"
 import { RuleContext, AST, TokenStore } from "../types"
+import {
+    getStyleContexts,
+    StyleContext,
+    getCommentDirectivesReporter,
+} from "../styles/context"
 
 module.exports = {
     meta: {
@@ -21,7 +25,7 @@ module.exports = {
         type: "suggestion",
     },
     create(context: RuleContext) {
-        const styles = getStyleContexts(context).filter(style => !style.invalid)
+        const styles = getStyleContexts(context).filter(StyleContext.isValid)
         if (!styles.length) {
             return {}
         }