[Lint] add custom stylelint rules and config (#4290)

* [Lint] add custom stylelint rules and config

Adding `@osd/stylelint-config` and `@osd/stylelint-plugin-stylelint` packages.

These packages are utilized by OSD core and can be ran with the following:
`yarn lint:style`

Can be used to fix known non-compliant styling with the following:
`yarn lint:style --fix`

Can be used to audit untracked styling (based on defined rules) with the following:
```
export OUI_AUDIT_ENABLED=true
yarn lint:style
```

---

`@osd/stylelint-config`

Defines rules approved by UX and OSD core in JSON files and is added to OSD core.
Within this commit is defined `colors.json` and `global_selectors.json`.

`colors.json` defines a property that can be matched with a regex of a selector.
If the selector is tracked it will have an `approved` value and a list of `rejected`
values that UX knows if a value should be something.

`global_selectors.json` defines a selector that if tracked, it will have an `approved`
list of relative paths to files that can modify the global selector.

---

`@osd/stylelint-plugin-stylelint`

Creates the functionality that utilizes the JSON files within the `@osd/stylelint-config`.
Within this commit is defined `no_custom_colors` and `no_modifying_global_selectors` rules.

`no_custom_colors` checks if a property is a color property. It then utilizes a compliance
engine helper to check the `colors.json` to see if the property being modified has a compliance
rule available for the property for the specific selector and if it is not compliant.
For example, if a selector matches `button` and we are trying to apply `background-color: red`
to it. Stylelint will catch this and flag this as a known non-compliance issue since it knows
that it should `$euiColorWarning`. If we pass `--fix` the property will be updated to be
`$euiColorWarning`. If `OUI_AUDIT_ENABLED` is true it will catch all `background-color` being
modified that is not being defined explicitly in `colors.json`

`no_modifying_global_selectors` checks if a selector being modified is defined in
`global_selectors.json` to see if a selector not defined in a specific list of approved files.
For example, if a selector matches `#opensearch-dashboards-body` and it is being modified in
`src/core/public/rendering/_base.scss`. Stylelint will catch this and flag this as a
non-compliance issue. Since no other file should be modifying this selector. If we pass `--fix`
the styling will be complete removed from the non-compliant file.

---

Next steps:

* Migrate these packages to OUI
* Consider adding `yarn lint:style --fix` to the build release script here:
https://github.com/opensearch-project/opensearch-build/blob/main/scripts/default/opensearch-dashboards/build.sh#L89

Issue:
#4246

Signed-off-by: Kawika Avilla <kavilla414@gmail.com>

* fix to use find

Signed-off-by: Kawika Avilla <kavilla414@gmail.com>

* Add regex matching and OUI modification lint

Signed-off-by: Matt Provost <provomat@amazon.com>

* add changelog

Signed-off-by: Josh Romero <rmerqg@amazon.com>

* address issues

Signed-off-by: Kawika Avilla <kavilla414@gmail.com>

---------

Signed-off-by: Kawika Avilla <kavilla414@gmail.com>
Signed-off-by: Matt Provost <provomat@amazon.com>
Signed-off-by: Josh Romero <rmerqg@amazon.com>
Co-authored-by: Matt Provost <provomat@amazon.com>
Co-authored-by: Josh Romero <rmerqg@amazon.com>

.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;