[Lint] add custom stylelint rules and config

.eslintignore

@@ -3,6 +3,7 @@
 /.chromium
 /build
 /built_assets
+/bwc_tmp
 /config/apm.dev.js
 /data
 /html_docs

.stylelintrc.yml

@@ -1,5 +1,6 @@
 extends:
   - stylelint-config-standard-scss
+  - '@osd/stylelint-config'
 rules:
   # while we still use node-sass, only legacy rgb() notation is allowed
   color-function-notation: "legacy"

CHANGELOG.md

@@ -35,6 +35,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Upgrade yarn version to be compatible with @opensearch-project/opensearch ([#3443](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/3443))
 - Add an achievement badger to the PR ([#3721](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/3721))
 - Upgrade the backport workflow ([#4343](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/4343))
+- [Lint] Add custom stylelint rules and config to prevent unintended style overrides ([#4290](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/4290))
 
 ### 📝 Documentation
 

package.json

@@ -248,6 +248,8 @@
     "@osd/optimizer": "1.0.0",
     "@osd/plugin-generator": "1.0.0",
     "@osd/pm": "1.0.0",
+    "@osd/stylelint-config": "1.0.0",
+    "@osd/stylelint-plugin-stylelint": "1.0.0",
     "@osd/telemetry-tools": "1.0.0",
     "@osd/test": "1.0.0",
     "@osd/test-subj-selector": "0.2.1",

packages/osd-stylelint-config/.stylelintrc.js

@@ -0,0 +1,32 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ *
+ * Any modifications Copyright OpenSearch Contributors. See
+ * GitHub history for details.
+ */
+
+module.exports = {
+  plugins: [
+    '@osd/stylelint-plugin-stylelint',
+  ],
+
+  rules: {
+    '@osd/stylelint/no_modifying_global_selectors': [
+      {
+        config: "./../../../osd-stylelint-config/config/global_selectors.json"
+      },
+      {
+        severity: "error"
+      }
+    ],
+    '@osd/stylelint/no_custom_colors': [
+      {
+        config: './../../../osd-stylelint-config/config/colors.json'
+      },
+    ]
+  }
+}

packages/osd-stylelint-config/README.md

@@ -0,0 +1,45 @@
+# osd-stylelint-config
+
+The Stylelint config used by OpenSearch Dashboards. This package is created to enable the modification of rules with the JSON files in `config/` and any consumer of the `@osd/stylelint-plugin-stylelint` can just extend this config within its `.stylelintrc`.
+
+The ideal state being that this package is maintained externally from the OpenSearch Dashboards repo so that the configs can be modified with rules without being blocked by processes within OpenSearch Dashboards.
+
+Issue:
+https://github.com/opensearch-project/oui/issues/845
+
+## Usage
+
+To use this stylelint config, just install the peer dependencies and reference it
+in your `.stylelintrc`:
+
+```javascript
+{
+  extends: [
+    '@osd/stylelint-config'
+  ]
+}
+```
+
+This JSON configs that are sent through the compliance engine are expected to follow the schema:
+
+```json
+{
+  "cssProperty": {
+    "regexOfSelector": [
+      {
+        "approved": "OUICompliantValue1",
+        "rejected": [
+          "OUIViolationValue1",
+          "OUIViolationValue2",
+        ]
+      },
+      {
+        "approved": "OUICompliantValue2",
+        "rejected": [
+          "OUIViolationValue3"
+        ]
+      }
+    ]
+  }
+}
+```

packages/osd-stylelint-config/config/colors.json

@@ -0,0 +1,18 @@
+{
+  "background-color": {
+    "buttonTODOTHISANEXAMPLE": [
+      {
+        "approved": "$euiColorPrimary",
+        "rejected": [
+          "blueTODOTHISANEXAMPLE"
+        ]
+      },
+      {
+        "approved": "$euiColorWarning",
+        "rejected": [
+          "redTODOTHISANEXAMPLE"
+        ]
+      }
+    ]
+  }
+}

packages/osd-stylelint-config/config/global_selectors.json

@@ -0,0 +1,30 @@
+{
+  "#opensearch-dashboards-body": {
+    "approved": [
+      "src/core/public/rendering/_base.scss"
+    ]
+  },
+  ".app-wrapper": {
+    "approved": [
+      "src/core/public/rendering/_base.scss"
+    ]
+  },
+  "/\\.[eo]ui/": {
+    "approved": [
+      "examples/expressions_example/public/index.scss",
+      "src/core/public/styles/_base.scss",
+      "src/plugins/vis_default_editor/public/_sidebar.scss",
+      "src/core/public/core_app/styles/_mixins.scss",
+      "src/core/public/chrome/ui/header/_index.scss",
+      "src/core/public/chrome/ui/header/header_breadcrumbs.scss",
+      "src/core/public/chrome/ui/header/home_loader.scss",
+      "src/plugins/data/public/ui/filter_bar/_global_filter_item.scss",
+      "src/plugins/home/public/application/components/_synopsis.scss",
+      "src/plugins/vis_builder/public/application/components/searchable_dropdown.scss",
+      "src/plugins/vis_builder/public/application/components/side_nav.scss",
+      "packages/osd-ui-framework/src/components/button/button_group/_button_group.scss",
+      "src/plugins/discover/public/application/components/sidebar/discover_sidebar.scss",
+      "src/plugins/discover/public/application/angular/doc_table/components/table_row/_open.scss"
+    ]
+  }
+}

packages/osd-stylelint-config/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@osd/stylelint-config",
+  "version": "1.0.0",
+  "description": "The stylelint config used by OpenSearch Dashboards",
+  "main": ".stylelintrc.js",
+  "private": true,
+  "license": "Apache-2.0",
+  "opensearchDashboards": {
+    "devOnly": true
+  },
+  "peerDependencies": {
+    "@osd/stylelint-plugin-stylelint": "1.0.0",
+    "stylelint": "^14.5.2"
+  }
+}

packages/osd-stylelint-plugin-stylelint/README.md

@@ -0,0 +1,18 @@
+# Custom Stylelint rules for OpenSearch Dashboards
+
+This package contains custom Stylelint rules used for OpenSearch Dashboards development. Rules are defined in `src/rules` and are the actual logic of the custom rules which are built around parsing a JSON config file passed in and applying the rules defined within there.
+
+This package can work with `@osd/stylelint-config` which houses the JSON config files to be passed into this plugin. The goal being to seperate out OUI compliance rules which can be modified by anyone versus the actual OUI compliance engine which should be only modified by developers.
+
+## Audit styles that are related to custom rules
+
+Setting: 
+```
+export OUI_AUDIT_ENABLED=true
+```
+
+Enables the ability to capture styling that potentially can be subject to compliance when there is a rule that interacts with the styling.
+
+For example, if a style attempts to set a button to have a `background-color: $incorrectVariable()` and the JSON config passed to the compliance engine does not explicitly reject the `$incorrectVariable()` being applied to a button's background color then the linter will pass. But it will output this if the environment variable is set to `true`.
+
+The goal being that setting this environment variable to output a list that can then be added to the JSON config which we can feed back into the compliance engine.

packages/osd-stylelint-plugin-stylelint/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@osd/stylelint-plugin-stylelint",
+  "main": "./target/index.js",
+  "types": "./target/index.d.ts",
+  "version": "1.0.0",
+  "private": true,
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "tsc",
+    "osd:bootstrap": "yarn build"
+  },
+  "opensearchDashboards": {
+    "devOnly": true
+  },
+  "peerDependencies": {
+    "stylelint": "^14.5.2"
+  },
+  "devDependencies": {
+    "typescript": "4.0.2",
+    "tsd": "^0.21.0"
+  }
+}

packages/osd-stylelint-plugin-stylelint/src/index.ts

@@ -0,0 +1,22 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ *
+ * Any modifications Copyright OpenSearch Contributors. See
+ * GitHub history for details.
+ */
+
+import stylelint from 'stylelint';
+import rules from './rules';
+
+export const NAMESPACE = '@osd/stylelint';
+
+const rulesPlugins = Object.keys(rules).map((ruleName: string) => {
+  return stylelint.createPlugin(`${NAMESPACE}/${ruleName}`, rules[ruleName]);
+});
+
+// eslint-disable-next-line import/no-default-export
+export default rulesPlugins;

packages/osd-stylelint-plugin-stylelint/src/rules/index.ts

@@ -0,0 +1,19 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ *
+ * Any modifications Copyright OpenSearch Contributors. See
+ * GitHub history for details.
+ */
+
+import noCustomColors from './no_custom_colors';
+import noModifyingGlobalSelectors from './no_modifying_global_selectors';
+
+// eslint-disable-next-line import/no-default-export
+export default {
+  no_custom_colors: noCustomColors,
+  no_modifying_global_selectors: noModifyingGlobalSelectors,
+};

packages/osd-stylelint-plugin-stylelint/src/rules/no_custom_colors/index.ts

@@ -0,0 +1,106 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * The OpenSearch Contributors require contributions made to
+ * this file be licensed under the Apache-2.0 license or a
+ * compatible open source license.
+ *
+ * Any modifications Copyright OpenSearch Contributors. See
+ * GitHub history for details.
+ */
+
+import stylelint from 'stylelint';
+import { NAMESPACE } from '../..';
+import {
+  ComplianceEngine,
+  getTrackedMessage,
+  getUntrackedMessage,
+  getNotCompliantMessage,
+  getRulesFromConfig,
+  isColorProperty,
+  isValidOptions,
+} from '../../utils';
+
+const isOuiAuditEnabled = Boolean(process.env.OUI_AUDIT_ENABLED);
+
+const { ruleMessages, report } = stylelint.utils;
+const engine = ComplianceEngine.default;
+
+const ruleName = 'no_custom_colors';
+const messages = ruleMessages(ruleName, {
+  expected: (message) => `${message}`,
+});
+
+const ruleFunction = (
+  primaryOption: Record<string, any>,
+  secondaryOptionObject: Record<string, any>,
+  context
+) => {
+  return (postcssRoot: any, postcssResult: any) => {
+    const validOptions = isValidOptions(postcssResult, ruleName, primaryOption);
+    if (!validOptions) {
+      return;
+    }
+
+    const rules = getRulesFromConfig(primaryOption.config);
+
+    const isAutoFixing = Boolean(context.fix);
+
+    postcssRoot.walkDecls((decl: any) => {
+      if (!isColorProperty(decl.prop)) {
+        return;
+      }
+
+      let shouldReport = false;
+
+      const nodeInfo = {
+        selector: decl.parent.selector,
+        prop: decl.prop,
+        value: decl.value,
+      };
+
+      const reportInfo = {
+        ruleName: `${NAMESPACE}/${ruleName}`,
+        result: postcssResult,
+        node: decl,
+        message: '',
+      };
+
+      if (isOuiAuditEnabled && !engine.isTracked(rules, nodeInfo)) {
+        reportInfo.message = messages.expected(getUntrackedMessage(nodeInfo));
+        report(reportInfo);
+        return;
+      }
+
+      const ruleObject = engine.getComplianceRule(rules, nodeInfo);
+
+      if (!ruleObject) {
+        if (isOuiAuditEnabled) {
+          reportInfo.message = messages.expected(getTrackedMessage(nodeInfo));
+          report(reportInfo);
+        }
+        return;
+      }
+
+      shouldReport = !ruleObject.isComplaint;
+
+      if (shouldReport && isAutoFixing) {
+        decl.value = ruleObject.expected;
+        return;
+      }
+
+      if (!shouldReport) {
+        return;
+      }
+
+      reportInfo.message = messages.expected(getNotCompliantMessage(ruleObject.message));
+      report(reportInfo);
+    });
+  };
+};
+
+ruleFunction.ruleName = ruleName;
+ruleFunction.messages = messages;
+
+// eslint-disable-next-line import/no-default-export
+export default ruleFunction;