uilint 0.2.1 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uilint",
-  "version": "0.2.1",
+  "version": "0.2.4",
   "description": "CLI for UILint - AI-powered UI consistency checking",
   "author": "Peter Suggate",
   "repository": {
@@ -27,6 +27,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md"
   ],
   "engines": {
@@ -41,9 +42,9 @@
     "dotenv": "^16.4.7",
     "magicast": "^0.3.5",
     "picocolors": "^1.1.1",
-    "uilint-core": "^0.2.1",
-    "uilint-eslint": "^0.2.1",
-    "ws": "^8.18.0"
+    "ws": "^8.18.0",
+    "uilint-core": "0.2.4",
+    "uilint-eslint": "0.2.4"
   },
   "optionalDependencies": {
     "@langfuse/client": "^4.5.1",
@@ -76,6 +77,7 @@
     "typecheck": "tsc --noEmit",
     "lint": "eslint src/",
     "test": "vitest",
+    "test:watch": "vitest --watch",
     "test:unit": "vitest run test/unit",
     "test:integration": "vitest run test/integration"
   }

package/skills/ui-consistency-enforcer/SKILL.md

@@ -0,0 +1,435 @@
+---
+name: ui-consistency-enforcer
+description: |
+  When the user asks you to update React UI code in ways that suggest they want
+  consistency with existing project patterns, style guides, or design systems,
+  this skill helps you create a bulletproof ESLint rule to enforce that pattern
+  permanently. Trigger keywords: "make consistent", "match the style", "follow
+  the pattern", "like the other components", "according to our design system",
+  "enforce across the codebase", "prevent this in the future".
+license: MIT
+metadata:
+  author: uilint
+  version: "1.0.0"
+  category: react-eslint
+compatibility: |
+  Requires TypeScript project with @typescript-eslint,
+  and uilint-eslint package installed.
+---
+
+# UI Consistency Enforcer Skill
+
+You are an expert at writing bulletproof ESLint rules for React/TypeScript projects
+using the @typescript-eslint framework. When the user asks you to update UI code in
+a way that suggests they want consistency with existing patterns, you should:
+
+1. **Identify the consistency pattern** the user wants to enforce
+2. **Create an ESLint rule** that will catch future violations
+3. **Write comprehensive tests** for the rule
+4. **Register the rule** in the uilint-eslint package
+
+## When to Activate
+
+Activate this skill when the user's request matches patterns like:
+
+- "Update this component to use our Button instead of native button"
+- "Make sure all forms use our design system components"
+- "This should match the pattern in our other components"
+- "Enforce that we always use X instead of Y"
+- "Create a lint rule to prevent this"
+- "Make this consistent with our style guide"
+- Refactoring multiple components to follow a pattern
+- Adding design system enforcement
+
+## Step-by-Step Process
+
+### Step 1: Understand the Pattern
+
+Before writing the rule, understand:
+
+1. **What pattern should be enforced?** (e.g., "use shadcn Button instead of native button")
+2. **Where does it apply?** (all files? only components? specific directories?)
+3. **What are the exceptions?** (tests? internal utilities? specific files?)
+4. **What's the fix?** (what should developers do instead?)
+
+Ask clarifying questions if needed before proceeding.
+
+### Step 2: Analyze Existing Rules
+
+Look at existing rules installed in the project for patterns:
+
+```bash
+ls .uilint/rules/
+```
+
+If no rules exist yet, you can reference examples from the uilint-eslint package or look at similar patterns. Common rule patterns include:
+
+- Component analysis and hook counting
+- Cross-file analysis and import tracking
+- className/Tailwind pattern matching
+- Attribute analysis in JSX
+
+### Step 3: Write the Rule
+
+Create the rule file at `.uilint/rules/{rule-name}.ts` in the target project.
+
+Follow this structure exactly:
+
+```typescript
+/**
+ * Rule: {rule-name}
+ *
+ * {Description of what this rule does and why}
+ */
+
+import { createRule } from "uilint-eslint";
+import type { TSESTree } from "@typescript-eslint/utils";
+
+type MessageIds = "{messageId1}" | "{messageId2}";
+type Options = [
+  {
+    /** Option description */
+    optionName?: optionType;
+  }?
+];
+
+export default createRule<Options, MessageIds>({
+  name: "{rule-name}",
+  meta: {
+    type: "problem" | "suggestion" | "layout",
+    docs: {
+      description: "{Human-readable description}",
+    },
+    messages: {
+      messageId1: "{Error message with {{placeholders}}}",
+      messageId2: "{Another message}",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          optionName: {
+            type: "string",
+            description: "Option description",
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  defaultOptions: [{ optionName: "default" }],
+  create(context) {
+    const options = context.options[0] || {};
+    // Use options with defaults
+    const optionName = options.optionName ?? "default";
+
+    return {
+      // AST visitor methods
+      JSXOpeningElement(node) {
+        // Analyze JSX elements
+      },
+      ImportDeclaration(node) {
+        // Track imports
+      },
+      CallExpression(node) {
+        // Analyze function calls like hooks
+      },
+      "Program:exit"() {
+        // Final analysis after parsing entire file
+      },
+    };
+  },
+});
+```
+
+### Step 4: Write Comprehensive Tests
+
+Create the test file at `.uilint/rules/{rule-name}.test.ts` in the target project.
+
+Follow this structure:
+
+```typescript
+/**
+ * Tests for: {rule-name}
+ *
+ * {Description}
+ */
+
+import { RuleTester } from "@typescript-eslint/rule-tester";
+import { describe, it, afterAll, beforeEach } from "vitest";
+import rule from "./{rule-name}";
+// If rule uses caching:
+// import { clearCache } from "../utils/import-graph.js";
+
+RuleTester.afterAll = afterAll;
+RuleTester.describe = describe;
+RuleTester.it = it;
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    ecmaVersion: 2022,
+    sourceType: "module",
+    parserOptions: {
+      ecmaFeatures: { jsx: true },
+    },
+  },
+});
+
+// Clear cache between tests if needed
+// beforeEach(() => {
+//   clearCache();
+// });
+
+ruleTester.run("{rule-name}", rule, {
+  valid: [
+    // ============================================
+    // PREFERRED PATTERN USED CORRECTLY
+    // ============================================
+    {
+      name: "uses preferred pattern",
+      code: `
+        // Valid code example
+      `,
+    },
+    {
+      name: "with custom options",
+      code: `...`,
+      options: [{ optionName: "custom" }],
+    },
+
+    // ============================================
+    // EXCEPTIONS / EDGE CASES
+    // ============================================
+    {
+      name: "exception case is allowed",
+      code: `...`,
+    },
+  ],
+
+  invalid: [
+    // ============================================
+    // BASIC VIOLATIONS
+    // ============================================
+    {
+      name: "violates pattern",
+      code: `
+        // Invalid code example
+      `,
+      errors: [
+        {
+          messageId: "messageId1",
+          data: { key: "value" },
+        },
+      ],
+    },
+
+    // ============================================
+    // WITH OPTIONS
+    // ============================================
+    {
+      name: "violates with custom options",
+      code: `...`,
+      options: [{ optionName: "strict" }],
+      errors: [
+        {
+          messageId: "messageId2",
+        },
+      ],
+    },
+  ],
+});
+```
+
+### Step 5: Configure ESLint to Use the Rule
+
+The rule will be automatically configured in your `eslint.config.{js,ts,mjs,cjs}` file. The installer creates a custom plugin that references your local rules:
+
+```javascript
+import { createRule } from "uilint-eslint";
+import yourRuleName from "./.uilint/rules/your-rule-name.js";
+
+export default [
+  // ... existing config
+  {
+    plugins: {
+      "uilint-custom": {
+        rules: {
+          "your-rule-name": yourRuleName,
+        },
+      },
+    },
+    rules: {
+      "uilint-custom/your-rule-name": "error",
+    },
+  },
+];
+```
+
+If you're creating the rule manually (not via the installer), you'll need to add the import and configure it in your ESLint config.
+
+## Common AST Patterns
+
+### Detecting JSX Elements
+
+```typescript
+JSXOpeningElement(node) {
+  // Get element name
+  if (node.name.type === "JSXIdentifier") {
+    const name = node.name.name;
+    // Check if it's a component (PascalCase) vs HTML (lowercase)
+    if (/^[A-Z]/.test(name)) {
+      // It's a component
+    }
+  }
+}
+```
+
+### Tracking Imports
+
+```typescript
+const importMap = new Map<string, string>();
+
+return {
+  ImportDeclaration(node) {
+    const source = node.source.value as string;
+    for (const spec of node.specifiers) {
+      if (spec.type === "ImportSpecifier") {
+        importMap.set(spec.local.name, source);
+      }
+    }
+  },
+
+  JSXOpeningElement(node) {
+    if (node.name.type === "JSXIdentifier") {
+      const importSource = importMap.get(node.name.name);
+      // Now you know where it was imported from
+    }
+  },
+};
+```
+
+### Checking className for Tailwind Patterns
+
+```typescript
+JSXAttribute(node) {
+  if (node.name.type !== "JSXIdentifier" || node.name.name !== "className") {
+    return;
+  }
+
+  if (node.value?.type === "Literal" && typeof node.value.value === "string") {
+    const classes = node.value.value;
+    // Analyze classes
+  }
+}
+```
+
+### Counting React Hooks in Components
+
+```typescript
+const componentStack: ComponentInfo[] = [];
+
+function isComponentName(name: string): boolean {
+  return /^[A-Z]/.test(name);
+}
+
+function isHookCall(callee: TSESTree.Expression): string | null {
+  if (callee.type === "Identifier" && callee.name.startsWith("use")) {
+    return callee.name;
+  }
+  return null;
+}
+
+return {
+  FunctionDeclaration(node) {
+    if (node.id && isComponentName(node.id.name)) {
+      componentStack.push({ name: node.id.name, node, count: 0 });
+    }
+  },
+  "FunctionDeclaration:exit"(node) {
+    const component = componentStack.pop();
+    if (component && component.count > threshold) {
+      context.report({ node, messageId: "excessive" });
+    }
+  },
+  CallExpression(node) {
+    const hookName = isHookCall(node.callee);
+    if (hookName && componentStack.length > 0) {
+      componentStack[componentStack.length - 1].count++;
+    }
+  },
+};
+```
+
+### Cross-File Analysis
+
+For rules that need to analyze imports across files, use the import-graph utility:
+
+```typescript
+import { getComponentLibrary, clearCache } from "../utils/import-graph.js";
+
+// In create():
+"Program:exit"() {
+  const filename = context.filename || context.getFilename();
+
+  for (const usage of componentUsages) {
+    const libraryInfo = getComponentLibrary(
+      filename,
+      usage.componentName,
+      usage.importSource
+    );
+    // libraryInfo.library, libraryInfo.isLocalComponent, etc.
+  }
+}
+```
+
+## Error Message Best Practices
+
+1. Be specific about what's wrong
+2. Suggest the fix
+3. Use placeholders for dynamic content
+
+Good:
+
+```typescript
+messages: {
+  useDesignSystem:
+    "Use <{{preferred}}> from '{{source}}' instead of native <{{element}}>.",
+}
+```
+
+Bad:
+
+```typescript
+messages: {
+  error: "Invalid element",  // Too vague
+}
+```
+
+## Testing Tips
+
+1. **Test valid cases first** - Make sure correct code passes
+2. **Test with options** - Verify all configuration options work
+3. **Test edge cases** - JSX member expressions, aliases, spread attributes
+4. **Test real-world patterns** - Forms, modals, lists, etc.
+5. **Clear cache if using cross-file analysis** - Use `beforeEach`
+
+## Reference Files
+
+See the following files for complete working examples:
+
+- `references/RULE-TEMPLATE.ts` - Complete rule template
+- `references/TEST-TEMPLATE.ts` - Complete test template
+- `references/REGISTRY-ENTRY.md` - Registry entry format
+
+## Final Checklist
+
+Before finishing, verify:
+
+- [ ] Rule file created at `.uilint/rules/{name}.ts`
+- [ ] Test file created at `.uilint/rules/{name}.test.ts` (if applicable)
+- [ ] Rule imports `createRule` from `"uilint-eslint"`
+- [ ] ESLint config updated to import and use the rule from `.uilint/rules/`
+- [ ] Rule configured in ESLint with appropriate severity
+- [ ] Error messages are clear and actionable
+- [ ] Configuration options are documented in schema
+- [ ] Rule works correctly when ESLint runs

package/skills/ui-consistency-enforcer/references/REGISTRY-ENTRY.md

@@ -0,0 +1,163 @@
+# Adding a Rule to the Registry
+
+After creating your rule, you must register it in `packages/uilint-eslint/src/rule-registry.ts`.
+
+## Entry Format
+
+```typescript
+{
+  id: "rule-name",                    // Must match filename (without .ts)
+  name: "Human Readable Name",        // Display name for CLI
+  description: "Short description",   // Shown in rule selection prompts
+  defaultSeverity: "warn",            // "error" | "warn" | "off"
+  defaultOptions: [{ ... }],          // Default configuration
+  optionSchema: {                     // For interactive configuration
+    fields: [
+      {
+        key: "optionKey",             // Property name in options object
+        label: "Prompt Label",        // Shown in CLI prompts
+        type: "text",                 // "text" | "number" | "boolean" | "select" | "multiselect"
+        defaultValue: "default",      // Pre-filled value
+        placeholder: "hint text",     // For text/number inputs
+        options: [                    // For select/multiselect
+          { value: "a", label: "Option A" },
+          { value: "b", label: "Option B" },
+        ],
+        description: "Help text",     // Explains the option
+      },
+    ],
+  },
+  requiresStyleguide: false,          // true if needs .uilint/styleguide.md
+  category: "static",                 // "static" | "semantic"
+},
+```
+
+## Field Types
+
+### text
+For string values:
+```typescript
+{
+  key: "importSource",
+  label: "Import path for component",
+  type: "text",
+  defaultValue: "@/components/ui/button",
+  placeholder: "@/components/ui/button",
+  description: "The module path to import the preferred component from",
+}
+```
+
+### number
+For numeric values:
+```typescript
+{
+  key: "maxCount",
+  label: "Maximum allowed count",
+  type: "number",
+  defaultValue: 3,
+  placeholder: "3",
+  description: "Maximum number of items before triggering warning",
+}
+```
+
+### boolean
+For on/off toggles:
+```typescript
+{
+  key: "strict",
+  label: "Enable strict mode",
+  type: "boolean",
+  defaultValue: false,
+  description: "When enabled, also checks for edge cases",
+}
+```
+
+### select
+For single-choice options:
+```typescript
+{
+  key: "preferred",
+  label: "Preferred component library",
+  type: "select",
+  defaultValue: "shadcn",
+  options: [
+    { value: "shadcn", label: "shadcn/ui" },
+    { value: "mui", label: "Material UI" },
+    { value: "chakra", label: "Chakra UI" },
+  ],
+  description: "The UI library to enforce",
+}
+```
+
+### multiselect
+For multiple-choice options:
+```typescript
+{
+  key: "elements",
+  label: "Elements to check",
+  type: "multiselect",
+  defaultValue: ["button", "input"],
+  options: [
+    { value: "button", label: "Button" },
+    { value: "input", label: "Input" },
+    { value: "select", label: "Select" },
+    { value: "textarea", label: "Textarea" },
+  ],
+  description: "HTML elements to enforce replacement for",
+}
+```
+
+## Complete Example
+
+Here's a complete registry entry for a rule that enforces design system buttons:
+
+```typescript
+{
+  id: "prefer-design-system-button",
+  name: "Prefer Design System Button",
+  description: "Enforce using Button from design system instead of native <button>",
+  defaultSeverity: "warn",
+  defaultOptions: [
+    {
+      preferred: "Button",
+      importSource: "@/components/ui/button",
+      checkSubmit: true,
+    },
+  ],
+  optionSchema: {
+    fields: [
+      {
+        key: "preferred",
+        label: "Preferred component name",
+        type: "text",
+        defaultValue: "Button",
+        placeholder: "Button",
+        description: "The component to use instead of native button",
+      },
+      {
+        key: "importSource",
+        label: "Import path",
+        type: "text",
+        defaultValue: "@/components/ui/button",
+        placeholder: "@/components/ui/button",
+        description: "Where to import the component from",
+      },
+      {
+        key: "checkSubmit",
+        label: "Check submit buttons",
+        type: "boolean",
+        defaultValue: true,
+        description: "Also check button[type='submit']",
+      },
+    ],
+  },
+  requiresStyleguide: false,
+  category: "static",
+},
+```
+
+## After Adding Entry
+
+1. Run `pnpm -C packages/uilint-eslint generate:index` to regenerate the index
+2. The rule will now appear in `uilint install` prompts
+3. Users can configure it interactively during installation