chore: 🤖 add circular dependency safe guards (#864)

* chore: 🤖 add script for circular dependency check

* chore: 🤖 declare circular-dependency:check script

* docs: 📝 add circular dependency check section

* chore: 🤖 add changeset

* chore: 🤖 add circular dependency check to pre-commit hook

* chore: 🤖 add circular dep check to code-quality workflow ci/cd

* chore: 🤖 update lockfile

* chore: 🤖 update changeset (fix incorrect name)

* fix: 🐛 skott cmd call

* chore: 🤖 code review suggestions

Author: punkbit

.changeset/nine-queens-allow.md

@@ -0,0 +1,23 @@
+---
+'@clickhouse/click-ui': patch
+---
+
+Add circular dependency check to prevent and detect circular import cycles that can cause build issues, runtime errors, and bundle size problems.
+
+## How to use?
+
+Run the circular dependency check:
+
+```sh
+yarn circular-dependency:check
+```
+
+The command analyzes the source code starting from the `src` directory and reports any circular dependencies found.
+
+To check a specific entry point:
+
+```sh
+yarn circular-dependency:check src/components
+```
+
+If circular dependencies are detected, the output will show the file paths involved in the cycle, helping you identify which imports need to be refactored to break the dependency chain.

.github/workflows/code-quality.yml

@@ -30,3 +30,6 @@ jobs:
 
       - name: Formatter
         run: yarn format
+
+      - name: Circular Dependencies
+        run: yarn circular-dependency:check

.husky/pre-commit

@@ -31,6 +31,14 @@ else
   exit 1
 fi
 
+if yarn circular-dependency:check; then
+  echo "✅ Circular dependency check is good!"
+else
+  echo "⚠️ WARNING: Circular dependency checkup found issues, fix them before committing, please!"
+  echo "💡 Use the following command to get further reports in your resolution yarn circular-dependency:check"
+  exit 1
+fi
+
 if yarn changeset:verify; then
   echo "✅ Changeset file's included!"
 else

.scripts/bash/circular-dependency-check

@@ -0,0 +1,42 @@
+#!/bin/bash
+
+ENTRY_POINT="${1:-src}"
+
+IGNORE_PATTERNS="node_modules/**,**/*.stories.tsx,**/*.stories.ts,**/*.test.ts,**/*.test.tsx"
+
+echo "🔍 Checking for circular dependencies in $ENTRY_POINT..."
+echo ""
+
+TEMP_OUTPUT=$(mktemp)
+trap 'rm -f "$TEMP_OUTPUT"' EXIT
+
+if command -v yarn &> /dev/null; then
+  yarn exec skott "$ENTRY_POINT" \
+    --displayMode=file-tree \
+    --showCircularDependencies \
+    --ignorePattern="$IGNORE_PATTERNS" \
+    --exitCodeOnCircularDependencies=1 > "$TEMP_OUTPUT" 2>&1 || true
+else
+  echo "👹 Oops! The package skott is missing, have you installed the project dependencies?"
+
+  exit 1
+fi
+
+if grep -q "✖.*circular dependencies found" "$TEMP_OUTPUT"; then
+  echo "❌ Circular dependencies detected!"
+  echo ""
+  grep -A 1000 "✖.*circular dependencies found" "$TEMP_OUTPUT" | head -100
+  echo ""
+  echo "💡 To fix these issues, review the files listed above."
+
+  exit 1
+elif grep -q "✓.*no circular dependencies found" "$TEMP_OUTPUT"; then
+  echo "✅ No circular dependencies found!"
+
+  exit 0
+else
+  echo "⚠️  Warning: Could not determine circular dependency status from skott output"
+  cat "$TEMP_OUTPUT"
+
+  exit 1
+fi

README.md

@@ -22,6 +22,7 @@ You can find the official docs for the Click UI design system and component libr
 * [Development](#development)
   - [Generating design tokens](#generating-design-tokens)
   - [Local development](#local-development)
+  - [Circular dependency check](#circular-dependency-check)
 * [Tests](#Tests)
   - [Functional tests](#functional-tests)
   - [Visual regression tests](#visual-regression-tests)
@@ -96,6 +97,16 @@ After cloning the repository change to the work directory and install the depend
 yarn
 ```
 
+### Circular dependency check
+
+Check for circular dependencies that can cause build and runtime issues:
+
+```sh
+yarn circular-dependency:check
+```
+
+If circular dependencies are found it'll exit with a report showing the affeced files which require your attention.
+
 ### Generating design tokens
 
 Tokens are provided by a style directionary sourced from [tokens-studio](https://tokens.studio/).

package.json

@@ -322,6 +322,7 @@
     "changeset:add": "yarn changeset",
     "changeset:status": "yarn changeset status",
     "changeset:verify": ".scripts/bash/changeset-verification",
+    "circular-dependency:check": ".scripts/bash/circular-dependency-check",
     "changeset:version": "yarn changeset version",
     "convert:logo": ".scripts/convert-svg-to-react-component --type=logos",
     "convert:icon": ".scripts/convert-svg-to-react-component --type=icons",
@@ -418,6 +419,7 @@
     "react": "18.3.1",
     "react-dom": "18.3.1",
     "rollup-plugin-visualizer": "^6.0.5",
+    "skott": "^0.35.4",
     "storybook": "^10.1.10",
     "storybook-addon-pseudo-states": "^10.1.10",
     "style-dictionary": "^5.0.0",