@patrizzos/stylesafe 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stylesafe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# StyleSafe - MCP and CLI
+
+An MCP server and CLI that catches CSS cascade conflicts and Tailwind utility clashes before they ship — built for AI coding agents and CI workflows.
+
+## What it does
+
+- Detects duplicate CSS declarations and dead rules from specificity conflicts
+- Flags silent style overrides that may be accidental
+- Finds conflicting Tailwind utilities (padding, margin, background, shadow, opacity, border, ring, etc.)
+- Understands `cn()`, `clsx()`, and `twMerge()` call expressions, not just plain `className` strings
+- Returns structured agent-friendly reports with `confidence`, `riskScore`, and `nextStep`
+
+## Quick start
+
+### As a CLI tool
+
+```bash
+npm install -g stylesafe
+stylesafe src/components/Button.jsx
+stylesafe --changed --fail-on-issues
+stylesafe --projectRoot src
+stylesafe --watch src
+```
+
+### As an MCP server
+
+```json
+{
+  "mcpServers": {
+    "stylesafe": {
+      "command": "node",
+      "args": ["/absolute/path/to/server.js"]
+    }
+  }
+}
+```
+
+## Example output
+
+```bash
+stylesafe examples/tailwind-conflict.jsx
+```
+
+Returns a structured report:
+
+```json
+{
+  "totalIssues": 5,
+  "riskScore": 275,
+  "averageRiskScore": 55,
+  "riskLevel": "medium",
+  "passed": true,
+  "clean": false,
+  "files": [
+    {
+      "filename": "examples/tailwind-conflict.jsx",
+      "issues": [
+        {
+          "type": "tailwind-conflict",
+          "category": "padding",
+          "classes": ["p-4", "px-8"],
+          "confidence": "medium",
+          "riskScore": 55,
+          "nextStep": "Choose one utility from the conflicting set or split the classes by scope.",
+          "requiresUserConfirmation": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+`passed: true` means no hard errors. `clean: true` means zero issues of any kind.
+
+## Use cases
+
+- **AI code generation**: Catch style bugs before the agent commits changes
+- **PR gate**: Block merged changes that introduce cascade conflicts or utility clashes
+- **Agent workflows**: Integrate as a confirmation step in multi-turn coding tasks
+- **Style audits**: Run across a project to find existing issues
+
+## CLI options
+
+- `stylesafe <file>` — analyze a single file
+- `stylesafe <dir>` — analyze a directory recursively
+- `stylesafe --projectRoot <dir>` — same as above
+- `stylesafe --changed` — analyze git-changed files (for PR/CI)
+- `stylesafe --changed --fail-on-issues` — exit with code 1 if any issues found
+- `stylesafe --watch src` — re-run on every file change
+- `npm test` — run regression tests
+
+## Config
+
+Place a `.styleintegrityrc` file in your project root:
+
+```json
+{
+  "ignore": ["dist", "*.min.css"],
+  "failOn": ["error", "warning"]
+}
+```
+
+## GitHub Actions
+
+Add to `.github/workflows/style-check.yml`:
+
+```yaml
+name: stylesafe
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  stylesafe:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install
+      - run: node server.js --changed --fail-on-issues
+```

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@patrizzos/stylesafe",
+  "mcpName": "io.github.Patrizzos/stylesafe",
+  "version": "0.1.5",
+  "description": "MCP server and CLI that catches CSS cascade conflicts and Tailwind utility clashes before they ship.",
+  "main": "server.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Patrizzos/stylesafe.git"
+  },
+  "bin": {
+    "stylesafe": "server.js"
+  },
+  "files": [
+    "src",
+    "server.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node server.js",
+    "test": "node test/run.js"
+  },
+  "keywords": [
+    "mcp",
+    "css",
+    "tailwind",
+    "lint",
+    "style",
+    "frontend",
+    "agent"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/server.js

@@ -0,0 +1 @@
+require('./src/server');

package/src/cascadeAnalyzer.js

@@ -0,0 +1,125 @@
+const { parseCSS } = require('./cssParser');
+const { calculateSpecificity, compareSpecificity, specificityToString } = require('./specificity');
+
+function extractTokens(selector) {
+  const compound = selector.trim().split(/\s+/).pop(); // rightmost compound selector
+  const tokens = compound.match(/[.#]?[\w-]+/g) || [];
+  return new Set(tokens);
+}
+
+function tokensOverlap(setA, setB) {
+  const [small, large] = setA.size <= setB.size ? [setA, setB] : [setB, setA];
+  for (const t of small) {
+    if (!large.has(t)) return false;
+  }
+  return small.size > 0;
+}
+
+function flattenRules(rules) {
+  const flat = [];
+  rules.forEach((rule, ruleIdx) => {
+    rule.selectors.forEach(selector => {
+      flat.push({
+        selector,
+        declarations: rule.declarations,
+        mediaContext: rule.mediaContext,
+        sourceOrder: ruleIdx,
+        specificity: calculateSpecificity(selector),
+      });
+    });
+  });
+  return flat;
+}
+
+function analyzeCascade(cssText, filename = '<input>') {
+  const rules = parseCSS(cssText);
+  const flat = flattenRules(rules);
+  const issues = [];
+
+  for (const rule of rules) {
+    const seen = new Map();
+    for (const decl of rule.declarations) {
+      if (seen.has(decl.prop) && !decl.important) {
+        issues.push({
+          type: 'duplicate-in-rule',
+          severity: 'warning',
+          selector: rule.selectors.join(', '),
+          prop: decl.prop,
+          message: `Property "${decl.prop}" is declared more than once in the same rule. Only the last value ("${decl.value}") takes effect; earlier value is dead code.`,
+        });
+      }
+      seen.set(decl.prop, decl.value);
+    }
+  }
+
+  for (let i = 0; i < flat.length; i++) {
+    for (let j = i + 1; j < flat.length; j++) {
+      const a = flat[i];
+      const b = flat[j];
+      if (a.mediaContext !== b.mediaContext) continue; // different media contexts, skip (not directly comparable)
+      const tokensA = extractTokens(a.selector);
+      const tokensB = extractTokens(b.selector);
+      if (!tokensOverlap(tokensA, tokensB)) continue;
+
+      const aProps = new Map(a.declarations.map(d => [d.prop, d]));
+      const bProps = new Map(b.declarations.map(d => [d.prop, d]));
+
+      for (const [prop, declB] of bProps) {
+        if (!aProps.has(prop)) continue;
+        const declA = aProps.get(prop);
+        if (declA.value === declB.value) continue; // not actually conflicting in effect
+
+        const cmp = compareSpecificity(b.specificity, a.specificity);
+        const bWinsBySource = b.sourceOrder > a.sourceOrder;
+
+        if (cmp < 0 && bWinsBySource === false) {
+        } else if (cmp < 0 && !declB.important && declA.important !== true) {
+          issues.push({
+            type: 'specificity-override',
+            severity: 'error',
+            prop,
+            message: `"${b.selector}" sets ${prop}: ${declB.value}, but it can never apply because "${a.selector}" (specificity ${specificityToString(a.specificity)} vs ${specificityToString(b.specificity)}) sets the same property and wins regardless of source order.`,
+            losingSelector: b.selector,
+            winningSelector: a.selector,
+          });
+        } else if (b.sourceOrder > a.sourceOrder && cmp >= 0) {
+          issues.push({
+            type: 'silent-override',
+            severity: 'info',
+            prop,
+            message: `"${b.selector}" (later in source) overrides "${a.selector}"'s ${prop}: ${declA.value} → ${declB.value}. Confirm this is intentional.`,
+            losingSelector: a.selector,
+            winningSelector: b.selector,
+          });
+        }
+      }
+    }
+  }
+
+  const importantCount = flat.reduce(
+    (sum, r) => sum + r.declarations.filter(d => d.important).length,
+    0
+  );
+  if (importantCount > 0) {
+    issues.push({
+      type: 'important-usage',
+      severity: importantCount > 3 ? 'warning' : 'info',
+      message: `${importantCount} use(s) of !important found. Each one raises the bar for any future rule trying to override it intentionally.`,
+    });
+  }
+
+  return {
+    filename,
+    ruleCount: rules.length,
+    issues,
+    summary: summarize(issues),
+  };
+}
+
+function summarize(issues) {
+  const counts = { error: 0, warning: 0, info: 0 };
+  for (const issue of issues) counts[issue.severity] = (counts[issue.severity] || 0) + 1;
+  return counts;
+}
+
+module.exports = { analyzeCascade };

package/src/checkStyleIntegrity.js

@@ -0,0 +1,182 @@
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { analyzeCascade } = require('./cascadeAnalyzer');
+const { extractClassStringsFromMarkup, detectTailwindConflicts } = require('./tailwindAnalyzer');
+
+const CSS_EXTENSIONS = new Set(['.css', '.scss']);
+const MARKUP_EXTENSIONS = new Set(['.jsx', '.tsx', '.html', '.vue', '.js', '.ts']);
+
+function getConfidence(issue) {
+  if (issue.type === 'specificity-override' || issue.type === 'duplicate-in-rule') return 'high';
+  if (issue.type === 'tailwind-conflict' || issue.type === 'important-usage') return 'medium';
+  return 'medium';
+}
+
+function getRiskScore(issue) {
+  if (issue.type === 'duplicate-in-rule') return 80;
+  if (issue.type === 'specificity-override') return 75;
+  if (issue.type === 'important-usage') return 65;
+  if (issue.type === 'tailwind-conflict') return 55;
+  return 40;
+}
+
+function toIssueWithAction(issue, filePath) {
+  const explanation = issue.message || 'Style issue detected.';
+  const nextStep = issue.type === 'specificity-override'
+    ? 'Review the selectors and adjust the weaker rule or increase specificity intentionally.'
+    : issue.type === 'duplicate-in-rule'
+      ? 'Remove the duplicate declaration or consolidate the values into a single declaration.'
+      : issue.type === 'tailwind-conflict'
+        ? 'Choose one utility from the conflicting set or split the classes by scope.'
+        : 'Review this override and confirm the intended winner before changing the styles.';
+
+  const suggestions = [];
+  if (issue.type === 'specificity-override') {
+    suggestions.push(`Replace or simplify the lower-specificity rule in ${filePath}`);
+    suggestions.push('Make the intended winner more explicit with a more specific selector');
+  } else if (issue.type === 'duplicate-in-rule') {
+    suggestions.push(`Remove the duplicate property from ${filePath}`);
+    suggestions.push('Keep a single canonical declaration for the property');
+  } else if (issue.type === 'tailwind-conflict') {
+    suggestions.push('Choose a single utility from the conflicting set');
+    suggestions.push('Split conflicting utilities into different variant scopes');
+  } else {
+    suggestions.push('Confirm whether the override is intentional');
+    suggestions.push('Refactor the selectors if the override was accidental');
+  }
+
+  const recommendedAction = issue.type === 'specificity-override'
+    ? 'Review the selector hierarchy before making any change.'
+    : issue.type === 'duplicate-in-rule'
+      ? 'Remove the duplicate declaration and keep one canonical value.'
+      : issue.type === 'tailwind-conflict'
+        ? 'Choose one utility or split the classes by variant scope.'
+        : 'Review the override and confirm whether it is intentional.';
+
+  return {
+    ...issue,
+    confidence: getConfidence(issue),
+    riskScore: getRiskScore(issue),
+    explanation,
+    suggestions: suggestions.slice(0, 3),
+    nextStep,
+    recommendedAction,
+    requiresUserConfirmation: true,
+  };
+}
+
+function collectChangedFiles() {
+  try {
+    const raw = execSync('git diff --name-only --diff-filter=ACMRTUXB HEAD', { encoding: 'utf8' });
+    return raw
+      .split(/\r?\n/)
+      .map(line => line.trim())
+      .filter(Boolean)
+      .filter(file => {
+        const ext = path.extname(file).toLowerCase();
+        return CSS_EXTENSIONS.has(ext) || MARKUP_EXTENSIONS.has(ext);
+      });
+  } catch {
+    return [];
+  }
+}
+
+function collectFilesToAnalyze(input) {
+  if (Array.isArray(input)) return input.filter(Boolean);
+  if (input && typeof input === 'object') {
+    if (input.changedFiles) return collectChangedFiles();
+    if (Array.isArray(input.files)) return input.files.filter(Boolean);
+    if (input.projectRoot) {
+      const root = input.projectRoot;
+      const results = [];
+      const walk = currentPath => {
+        if (!fs.existsSync(currentPath)) return;
+        const entries = fs.readdirSync(currentPath, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.name.startsWith('.')) continue;
+          if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === 'build') continue;
+          const fullPath = path.join(currentPath, entry.name);
+          if (entry.isDirectory()) {
+            walk(fullPath);
+          } else if (entry.isFile()) {
+            const ext = path.extname(entry.name).toLowerCase();
+            if (CSS_EXTENSIONS.has(ext) || MARKUP_EXTENSIONS.has(ext)) results.push(fullPath);
+          }
+        }
+      };
+      walk(root);
+      return results;
+    }
+  }
+  return [];
+}
+
+/**
+ * Checks a set of files for style integrity issues. This is the single function the
+ * MCP tool calls. Returns a structured report an agent can read and act on directly.
+ */
+function checkStyleIntegrity(input) {
+  const filePaths = collectFilesToAnalyze(input);
+  const report = {
+    files: [],
+    totalIssues: 0,
+    riskScore: 0,
+    averageRiskScore: 0,
+    riskLevel: 'low',
+    summary: { error: 0, warning: 0, info: 0, highConfidence: 0, mediumConfidence: 0, lowConfidence: 0 },
+    agentGuidance: {
+      requiresUserConfirmation: true,
+      message: 'Analyze the findings, explain the risk, and ask for permission before applying any fix.',
+    },
+    overview: {
+      recommendedNextAction: 'Review the highest-confidence issues first and ask for confirmation before changing styles.',
+    },
+  };
+
+  for (const filePath of filePaths) {
+    if (!fs.existsSync(filePath)) {
+      report.files.push({ filename: filePath, error: 'File not found' });
+      continue;
+    }
+
+    const stat = fs.statSync(filePath);
+    if (stat.isDirectory()) continue;
+
+    const ext = path.extname(filePath).toLowerCase();
+    const source = fs.readFileSync(filePath, 'utf8');
+    const fileReport = { filename: filePath, issues: [] };
+
+    if (CSS_EXTENSIONS.has(ext)) {
+      const result = analyzeCascade(source, filePath);
+      fileReport.issues.push(...result.issues.map(issue => toIssueWithAction(issue, filePath)));
+    }
+
+    if (MARKUP_EXTENSIONS.has(ext)) {
+      const classStrings = extractClassStringsFromMarkup(source);
+      for (const cs of classStrings) {
+        fileReport.issues.push(...detectTailwindConflicts(cs, cs).map(issue => toIssueWithAction(issue, filePath)));
+      }
+    }
+
+    for (const issue of fileReport.issues) {
+      report.summary[issue.severity] = (report.summary[issue.severity] || 0) + 1;
+      if (issue.confidence === 'high') report.summary.highConfidence++;
+      if (issue.confidence === 'medium') report.summary.mediumConfidence++;
+      if (issue.confidence === 'low') report.summary.lowConfidence++;
+      report.totalIssues++;
+      report.riskScore += issue.riskScore || 0;
+    }
+    report.files.push(fileReport);
+  }
+
+  report.passed = report.summary.error === 0;
+  report.clean = report.totalIssues === 0;
+  if (report.totalIssues > 0) {
+    report.averageRiskScore = Math.round(report.riskScore / report.totalIssues);
+    report.riskLevel = report.averageRiskScore >= 70 ? 'high' : report.averageRiskScore >= 50 ? 'medium' : 'low';
+  }
+  return report;
+}
+
+module.exports = { checkStyleIntegrity };

package/src/cssParser.js

@@ -0,0 +1,142 @@
+function stripComments(css) {
+  return css.replace(/\/\*[\s\S]*?\*\//g, '');
+}
+
+function parseDeclarations(block) {
+  const decls = [];
+  const parts = block.split(';');
+  for (const part of parts) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+    const colonIdx = trimmed.indexOf(':');
+    if (colonIdx === -1) continue;
+    const prop = trimmed.slice(0, colonIdx).trim().toLowerCase();
+    let value = trimmed.slice(colonIdx + 1).trim();
+    const important = /!important\s*$/i.test(value);
+    if (important) value = value.replace(/!important\s*$/i, '').trim();
+    decls.push({ prop, value, important });
+  }
+  return decls;
+}
+
+function combineSelectors(parentSelector, childSelector) {
+  const parent = parentSelector.trim();
+  const child = childSelector.trim();
+  if (!parent) return [child];
+  if (!child) return [parent];
+  if (child.startsWith('&')) {
+    return [parent + child.slice(1)];
+  }
+  return [`${parent} ${child}`];
+}
+
+function parseStyleBlock(blockText, parentSelectors = [], mediaStack = []) {
+  const declarations = [];
+  const nestedRules = [];
+  let cursor = 0;
+
+  while (cursor < blockText.length) {
+    const nextOpen = blockText.indexOf('{', cursor);
+    const nextSemi = blockText.indexOf(';', cursor);
+
+    if (nextOpen === -1 && nextSemi === -1) break;
+
+    if (nextOpen !== -1 && (nextSemi === -1 || nextOpen < nextSemi)) {
+      const selectorText = blockText.slice(cursor, nextOpen).trim();
+      if (selectorText) {
+        const closeIdx = findMatchingBrace(blockText, nextOpen);
+        const childBlock = blockText.slice(nextOpen + 1, closeIdx);
+        const combinedSelectors = parentSelectors.flatMap(parent => combineSelectors(parent, selectorText));
+        const childResult = parseStyleBlock(childBlock, combinedSelectors, mediaStack);
+        if (childResult.declarations.length > 0) {
+          nestedRules.push({
+            selectors: combinedSelectors,
+            declarations: childResult.declarations,
+            mediaContext: mediaStack.length > 0 ? mediaStack.join(' > ') : null,
+            raw: blockText.slice(nextOpen, closeIdx + 1),
+            start: cursor,
+          });
+        }
+        nestedRules.push(...childResult.nestedRules);
+        cursor = closeIdx + 1;
+        continue;
+      }
+    }
+
+    const semicolonIndex = nextSemi === -1 ? blockText.length : nextSemi;
+    const segment = blockText.slice(cursor, semicolonIndex).trim();
+    if (segment) {
+      declarations.push(...parseDeclarations(segment));
+    }
+    cursor = semicolonIndex + 1;
+  }
+
+  return { declarations, nestedRules };
+}
+
+function parseCSS(cssText) {
+  const css = stripComments(cssText);
+  const rules = [];
+  let i = 0;
+  let mediaStack = [];
+
+  while (i < css.length) {
+    while (i < css.length && /\s/.test(css[i])) i++;
+    if (i >= css.length) break;
+
+    if (css[i] === '@') {
+      const braceIdx = css.indexOf('{', i);
+      const semiIdx = css.indexOf(';', i);
+      if (braceIdx === -1 || (semiIdx !== -1 && semiIdx < braceIdx)) {
+        i = semiIdx === -1 ? css.length : semiIdx + 1;
+        continue;
+      }
+      const atRuleHeader = css.slice(i, braceIdx).trim();
+      mediaStack.push(atRuleHeader);
+      i = braceIdx + 1;
+      continue;
+    }
+
+    if (css[i] === '}') {
+      if (mediaStack.length > 0) mediaStack.pop();
+      i++;
+      continue;
+    }
+
+    const braceIdx = css.indexOf('{', i);
+    if (braceIdx === -1) break;
+    const selectorText = css.slice(i, braceIdx).trim();
+    const closeIdx = findMatchingBrace(css, braceIdx);
+    const declBlock = css.slice(braceIdx + 1, closeIdx);
+    const selectors = selectorText.split(',').map(s => s.trim()).filter(Boolean);
+    const parsedBlock = parseStyleBlock(declBlock, selectors, mediaStack);
+
+    if (parsedBlock.declarations.length > 0) {
+      rules.push({
+        selectors,
+        declarations: parsedBlock.declarations,
+        mediaContext: mediaStack.length > 0 ? mediaStack.join(' > ') : null,
+        raw: css.slice(i, closeIdx + 1),
+        start: i,
+      });
+    }
+
+    rules.push(...parsedBlock.nestedRules);
+    i = closeIdx + 1;
+  }
+
+  return rules;
+}
+
+function findMatchingBrace(css, openIdx) {
+  let depth = 1;
+  let i = openIdx + 1;
+  while (i < css.length && depth > 0) {
+    if (css[i] === '{') depth++;
+    else if (css[i] === '}') depth--;
+    i++;
+  }
+  return i - 1;
+}
+
+module.exports = { parseCSS, parseDeclarations };

package/src/server.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * Minimal MCP server implementing the core JSON-RPC transport for the style-integrity tool.
+ */
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { checkStyleIntegrity } = require('./checkStyleIntegrity');
+
+
+const TOOL_DEFINITION = {
+  name: 'check_style_integrity',
+  description:
+    'Analyzes CSS/SCSS files and Tailwind-related markup for cascade conflicts, duplicate declarations, specificity issues, and conflicting utilities. ' +
+    'The result is a structured report with explanation, suggested fixes, and a next step for the agent, intended for human review before any style change is applied.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      files: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Absolute or relative file paths to analyze (.css, .scss, .jsx, .tsx, .html, .vue, .js, .ts)',
+      },
+      projectRoot: {
+        type: 'string',
+        description: 'A project root directory to analyze recursively for style-related files',
+      },
+      changedFiles: {
+        type: 'boolean',
+        description: 'Analyze git changed files in the current repository working tree',
+      },
+    },
+    additionalProperties: false,
+  },
+};
+
+function send(message) {
+  process.stdout.write(JSON.stringify(message) + '\n');
+}
+
+function isStyleTarget(target) {
+  const ext = path.extname(target).toLowerCase();
+  return ['.css', '.scss', '.jsx', '.tsx', '.html', '.vue', '.js', '.ts'].includes(ext);
+}
+
+function loadConfig(startDir) {
+  // Walk up from startDir looking for .styleintegrityrc
+  let dir = path.resolve(startDir);
+  for (let i = 0; i < 6; i++) {
+    const candidate = path.join(dir, '.styleintegrityrc');
+    if (fs.existsSync(candidate)) {
+      try { return JSON.parse(fs.readFileSync(candidate, 'utf8')); } catch { return {}; }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return {};
+}
+
+function printCliUsage() {
+  console.log('Usage: node server.js [--changed] [--fail-on-issues] [--watch] [--projectRoot <dir>] [<file-or-directory>]');
+  console.log('  --changed          Analyze git changed files in the current repository');
+  console.log('  --fail-on-issues   Exit with code 1 if any issues are found');
+  console.log('  --watch            Re-run analysis on file changes (use with file or --projectRoot)');
+  console.log('  --projectRoot DIR  Analyze a directory recursively for style files');
+  console.log('  <file-or-directory> Analyze a single file or directory by extension');
+  console.log('');
+  console.log('Config: place a .styleintegrityrc JSON file in your project root.');
+  console.log('  { "ignore": ["dist", "*.min.css"], "failOn": ["error", "warning"] }');
+}
+
+function runCli(args) {
+  if (args.length === 0) {
+    printCliUsage();
+    return;
+  }
+
+  if (args.includes('--help') || args.includes('-h')) {
+    printCliUsage();
+    return;
+  }
+
+  let input;
+  const failOnIssues = args.includes('--fail-on-issues');
+  const changedFiles = args.includes('--changed');
+  const watchMode = args.includes('--watch');
+  const config = loadConfig(process.cwd());
+
+  if (changedFiles) {
+    input = { changedFiles: true };
+  } else if (args.includes('--projectRoot')) {
+    const idx = args.indexOf('--projectRoot');
+    input = { projectRoot: args[idx + 1] };
+  } else {
+    const target = args.find(a => !a.startsWith('--'));
+    if (!target) { printCliUsage(); return; }
+    input = isStyleTarget(target) ? { files: [target] } : { projectRoot: target };
+  }
+
+  function runAnalysis() {
+    const report = checkStyleIntegrity(input, config);
+    console.log(JSON.stringify(report, null, 2));
+    if (failOnIssues && !report.clean) process.exitCode = 1;
+  }
+
+  runAnalysis();
+
+  if (watchMode) {
+    const watchTarget = input.projectRoot || (Array.isArray(input.files) ? path.dirname(input.files[0]) : process.cwd());
+    console.error(`[stylesafe] Watching ${watchTarget} for changes...`);
+    let debounce;
+    fs.watch(watchTarget, { recursive: true }, (_, filename) => {
+      if (!filename) return;
+      const ext = path.extname(filename).toLowerCase();
+      if (!['.css', '.scss', '.jsx', '.tsx', '.html', '.vue', '.js', '.ts'].includes(ext)) return;
+      clearTimeout(debounce);
+      debounce = setTimeout(() => {
+        console.error(`[stylesafe] Change detected in ${filename}, re-analyzing...`);
+        runAnalysis();
+      }, 150);
+    });
+  }
+}
+
+function handleRequest(req) {
+  const { id, method, params } = req;
+
+  if (method === 'initialize') {
+    send({ jsonrpc: '2.0', id, result: { protocolVersion: '2024-11-05', capabilities: { tools: {} }, serverInfo: { name: 'stylesafe', version: '0.1.0' } } });
+    return;
+  }
+
+  if (method === 'notifications/initialized') {
+    return;
+  }
+
+  if (method === 'tools/list') {
+    send({ jsonrpc: '2.0', id, result: { tools: [TOOL_DEFINITION] } });
+    return;
+  }
+
+  if (method === 'tools/call') {
+    const { name, arguments: args } = params || {};
+    if (name !== 'check_style_integrity') {
+      send({ jsonrpc: '2.0', id, error: { code: -32601, message: `Unknown tool: ${name}` } });
+      return;
+    }
+    try {
+      const files = (args && args.files) || [];
+      const projectRoot = (args && args.projectRoot) || null;
+      const changedFiles = args && args.changedFiles;
+      const report = checkStyleIntegrity(changedFiles ? { changedFiles } : projectRoot ? { projectRoot } : files);
+      send({ jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: JSON.stringify(report, null, 2) }], isError: !report.passed } });
+    } catch (err) {
+      send({ jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: `Error running analysis: ${err.message}` }], isError: true } });
+    }
+    return;
+  }
+
+  if (id !== undefined) {
+    send({ jsonrpc: '2.0', id, error: { code: -32601, message: `Method not found: ${method}` } });
+  }
+}
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  if (args.length > 0) {
+    runCli(args);
+    return;
+  }
+
+  const rl = readline.createInterface({ input: process.stdin, terminal: false });
+  rl.on('line', line => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+
+    let req;
+    try {
+      req = JSON.parse(trimmed);
+    } catch {
+      return;
+    }
+
+    handleRequest(req);
+  });
+}

package/src/specificity.js

@@ -0,0 +1,56 @@
+/**
+ * Computes CSS specificity for a single selector string as [inlineFlag, idCount, classCount, typeCount].
+ * Follows the standard algorithm: IDs > classes/attrs/pseudo-classes > elements/pseudo-elements.
+ * Combinators (>, +, ~, space) and universal selector (*) don't add weight.
+ */
+
+function compareSpecificity(a, b) {
+  for (let i = 0; i < 4; i++) {
+    if (a[i] !== b[i]) return a[i] - b[i];
+  }
+  return 0;
+}
+
+function specificityToString(spec) {
+  return `(${spec[0]},${spec[1]},${spec[2]},${spec[3]})`;
+}
+
+function calculateSpecificity(selector) {
+  let sel = selector.trim();
+  let idCount = 0;
+  let classCount = 0;
+  let typeCount = 0;
+
+  // Strip pseudo-element (counts as type): ::before, ::after, etc. (also legacy single-colon :before/:after)
+  const pseudoElements = /::?(before|after|first-line|first-letter|placeholder|selection|marker)\b/gi;
+  sel = sel.replace(pseudoElements, () => {
+    typeCount++;
+    return '';
+  });
+
+  // :not(), :is(), :where() — :where() contributes 0, :not()/:is() contribute the specificity of their most specific argument.
+  // Simplified: treat :not(...) and :is(...) contents as normal selectors (recurse), :where(...) strip entirely with 0 weight.
+  sel = sel.replace(/:where\([^)]*\)/gi, '');
+  sel = sel.replace(/:(not|is|has)\(([^)]*)\)/gi, (_, _name, inner) => ` ${inner} `);
+
+  // IDs
+  sel = sel.replace(/#[\w-]+/g, () => { idCount++; return ''; });
+
+  // Classes, attribute selectors, pseudo-classes (excluding pseudo-elements already removed)
+  sel = sel.replace(/\.[\w-]+/g, () => { classCount++; return ''; });
+  sel = sel.replace(/\[[^\]]*\]/g, () => { classCount++; return ''; });
+  sel = sel.replace(/:[\w-]+/g, () => { classCount++; return ''; });
+
+  // Remaining type selectors (element names) and universal selector
+  const typeMatches = sel.match(/(^|[\s>+~])([a-zA-Z][\w-]*)/g);
+  if (typeMatches) {
+    for (const m of typeMatches) {
+      const tag = m.replace(/^[\s>+~]+/, '');
+      if (tag && tag !== '*') typeCount++;
+    }
+  }
+
+  return [0, idCount, classCount, typeCount];
+}
+
+module.exports = { calculateSpecificity, compareSpecificity, specificityToString };

package/src/tailwindAnalyzer.js

@@ -0,0 +1,173 @@
+/**
+ * Detects conflicting Tailwind utility classes within the same class list —
+ * e.g. "flex hidden" (both control display), "p-4 p-8" (both control all-side padding),
+ * "text-left text-right" (both control text-align).
+ *
+ * This is a deliberately curated table, not a full Tailwind config parser. It covers the
+ * utility families that are most commonly involved in agent-introduced bugs: layout/display,
+ * spacing, sizing, typography, flex/grid alignment, color. Extend CATEGORIES as needed.
+ */
+
+// Each utility definition includes the CSS property set it writes. This allows the
+// analyzer to detect real Tailwind conflicts such as p-4 vs px-8 while allowing
+// non-conflicting combos like px-3 and py-1.
+const UTILITY_DEFINITIONS = [
+  { name: 'display', pattern: /^(block|inline-block|inline|flex|inline-flex|grid|inline-grid|hidden|table|contents|flow-root)$/, properties: ['display'] },
+  { name: 'position', pattern: /^(static|fixed|absolute|relative|sticky)$/, properties: ['position'] },
+  { name: 'padding-all', pattern: /^p-(\d+|px|\[.+\]|auto)$/, properties: ['padding-top', 'padding-right', 'padding-bottom', 'padding-left'] },
+  { name: 'padding-x', pattern: /^px-(\d+|px|\[.+\]|auto)$/, properties: ['padding-left', 'padding-right'] },
+  { name: 'padding-y', pattern: /^py-(\d+|px|\[.+\]|auto)$/, properties: ['padding-top', 'padding-bottom'] },
+  { name: 'padding-top', pattern: /^pt-(\d+|px|\[.+\]|auto)$/, properties: ['padding-top'] },
+  { name: 'padding-right', pattern: /^pr-(\d+|px|\[.+\]|auto)$/, properties: ['padding-right'] },
+  { name: 'padding-bottom', pattern: /^pb-(\d+|px|\[.+\]|auto)$/, properties: ['padding-bottom'] },
+  { name: 'padding-left', pattern: /^pl-(\d+|px|\[.+\]|auto)$/, properties: ['padding-left'] },
+  { name: 'margin-all', pattern: /^m-(\d+|px|\[.+\]|auto)$/, properties: ['margin-top', 'margin-right', 'margin-bottom', 'margin-left'] },
+  { name: 'margin-x', pattern: /^mx-(\d+|px|\[.+\]|auto)$/, properties: ['margin-left', 'margin-right'] },
+  { name: 'margin-y', pattern: /^my-(\d+|px|\[.+\]|auto)$/, properties: ['margin-top', 'margin-bottom'] },
+  { name: 'margin-top', pattern: /^mt-(\d+|px|\[.+\]|auto)$/, properties: ['margin-top'] },
+  { name: 'margin-right', pattern: /^mr-(\d+|px|\[.+\]|auto)$/, properties: ['margin-right'] },
+  { name: 'margin-bottom', pattern: /^mb-(\d+|px|\[.+\]|auto)$/, properties: ['margin-bottom'] },
+  { name: 'margin-left', pattern: /^ml-(\d+|px|\[.+\]|auto)$/, properties: ['margin-left'] },
+  { name: 'width', pattern: /^w-(\d+|px|full|screen|auto|fit|min|max|\[.+\]|\d+\/\d+)$/, properties: ['width'] },
+  { name: 'height', pattern: /^h-(\d+|px|full|screen|auto|fit|min|max|\[.+\]|\d+\/\d+)$/, properties: ['height'] },
+  { name: 'text-align', pattern: /^text-(left|center|right|justify|start|end)$/, properties: ['text-align'] },
+  { name: 'font-weight', pattern: /^font-(thin|extralight|light|normal|medium|semibold|bold|extrabold|black)$/, properties: ['font-weight'] },
+  { name: 'font-size', pattern: /^text-(xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|8xl|9xl)$/, properties: ['font-size'] },
+  { name: 'text-color', pattern: /^text-(?:\[(?:.+)\]|(?:red|blue|green|yellow|purple|pink|gray|grey|indigo|black|white|orange|teal|cyan|slate|zinc|neutral|stone|amber|lime|emerald|sky|violet|fuchsia|rose)(?:-?\d{0,3})?)$/, properties: ['color'] },
+  { name: 'background-color', pattern: /^bg-(?:\[(?:.+)\]|(?:red|blue|green|yellow|purple|pink|gray|grey|indigo|black|white|orange|teal|cyan|slate|zinc|neutral|stone|amber|lime|emerald|sky|violet|fuchsia|rose)(?:-?\d{0,3})?)$/, properties: ['background-color'] },
+  { name: 'flex-direction', pattern: /^flex-(row|row-reverse|col|col-reverse)$/, properties: ['flex-direction'] },
+  { name: 'justify-content', pattern: /^justify-(start|end|center|between|around|evenly)$/, properties: ['justify-content'] },
+  { name: 'align-items', pattern: /^items-(start|end|center|baseline|stretch)$/, properties: ['align-items'] },
+  { name: 'border-radius', pattern: /^rounded(-\w+)?(-\d+)?$/, properties: ['border-radius'] },
+  { name: 'overflow', pattern: /^overflow-(auto|hidden|visible|scroll|x-auto|x-hidden|y-auto|y-hidden)$/, properties: ['overflow'] },
+  { name: 'float', pattern: /^float-(left|right|none)$/, properties: ['float'] },
+  { name: 'shadow', pattern: /^shadow(-[a-z]+)?$/, properties: ['box-shadow'] },
+  { name: 'opacity', pattern: /^opacity-(0|25|50|75|100)$/, properties: ['opacity'] },
+  { name: 'gap', pattern: /^gap-(\d+|px|\[.+\]|auto)$/, properties: ['gap'] },
+  { name: 'gap-x', pattern: /^gap-x-(\d+|px|\[.+\]|auto)$/, properties: ['column-gap'] },
+  { name: 'gap-y', pattern: /^gap-y-(\d+|px|\[.+\]|auto)$/, properties: ['row-gap'] },
+  { name: 'border', pattern: /^border(?:-(\d+|px|solid|dashed|dotted|double|none))?$/, properties: ['border-top', 'border-right', 'border-bottom', 'border-left'] },
+  { name: 'border-x', pattern: /^border-x(?:-(\d+|px|solid|dashed|dotted|double|none))?$/, properties: ['border-left', 'border-right'] },
+  { name: 'border-y', pattern: /^border-y(?:-(\d+|px|solid|dashed|dotted|double|none))?$/, properties: ['border-top', 'border-bottom'] },
+  { name: 'border-top', pattern: /^border-t(?:-(\d+|px|solid|dashed|dotted|double|none))?$/, properties: ['border-top'] },
+  { name: 'border-right', pattern: /^border-r(?:-(\d+|px|solid|dashed|dotted|double|none))?$/, properties: ['border-right'] },
+  { name: 'border-bottom', pattern: /^border-b(?:-(\d+|px|solid|dashed|dotted|double|none))?$/, properties: ['border-bottom'] },
+  { name: 'border-left', pattern: /^border-l(?:-(\d+|px|solid|dashed|dotted|double|none))?$/, properties: ['border-left'] },
+  { name: 'ring', pattern: /^ring(?:-(\d+|px|offset|inset|white|black|red|blue|green|yellow|purple|pink|gray|slate|zinc|neutral|stone|amber|emerald|teal|cyan|sky|violet|fuchsia|rose)(?:-?\d{0,3})?)?$/, properties: ['box-shadow'] },
+  { name: 'ring-offset', pattern: /^ring-offset(?:-(\d+|px|white|black|red|blue|green|yellow|purple|pink|gray|slate|zinc|neutral|stone|amber|emerald|teal|cyan|sky|violet|fuchsia|rose)(?:-?\d{0,3})?)?$/, properties: ['box-shadow'] },
+  { name: 'text-decoration', pattern: /^(underline|line-through|no-underline)$/, properties: ['text-decoration'] },
+];
+
+function splitVariant(cls) {
+  const parts = cls.split(':');
+  const base = parts.pop();
+  const scope = parts.join(':') || '__base__';
+  return { scope, base };
+}
+
+function normalizeBaseClass(baseClass) {
+  return baseClass.replace(/^(?:[A-Za-z0-9_-]+:)+/, '');
+}
+
+function categorize(baseClass) {
+  const normalized = normalizeBaseClass(baseClass);
+  for (const def of UTILITY_DEFINITIONS) {
+    if (def.pattern.test(normalized)) return { category: def.name, properties: def.properties };
+  }
+  return null;
+}
+
+function detectTailwindConflicts(classString, context = '') {
+  const classes = classString.split(/\s+/).filter(Boolean);
+  const byScope = new Map();
+
+  for (const cls of classes) {
+    const { scope, base } = splitVariant(cls);
+    const info = categorize(base);
+    if (!info) continue;
+    if (!byScope.has(scope)) {
+      byScope.set(scope, { propertyMap: new Map(), classMeta: new Map() });
+    }
+
+    const scopeData = byScope.get(scope);
+    scopeData.classMeta.set(cls, info.category);
+
+    for (const property of info.properties) {
+      if (!scopeData.propertyMap.has(property)) scopeData.propertyMap.set(property, []);
+      scopeData.propertyMap.get(property).push(cls);
+    }
+  }
+
+  const conflicts = [];
+  for (const [scope, scopeData] of byScope) {
+    const groupedConflicts = new Map();
+
+    for (const clsList of scopeData.propertyMap.values()) {
+      if (clsList.length <= 1) continue;
+      const uniqueClasses = Array.from(new Set(clsList)).sort();
+      const key = uniqueClasses.join('|');
+      const conflict = groupedConflicts.get(key) || { classes: uniqueClasses, categories: new Set() };
+      uniqueClasses.forEach(cls => conflict.categories.add(scopeData.classMeta.get(cls)));
+      groupedConflicts.set(key, conflict);
+    }
+
+    for (const conflict of groupedConflicts.values()) {
+          const rawCategory = [...conflict.categories][0];
+      const category = rawCategory.replace(/-(all|x|y|top|right|bottom|left)$/, '');
+      conflicts.push({
+        type: 'tailwind-conflict',
+        severity: 'warning',
+        scope: scope === '__base__' ? '(no variant)' : scope,
+        category,
+        classes: conflict.classes,
+        context,
+        message: `Conflicting "${category}" utilities in the same scope${scope !== '__base__' ? ` (${scope}:)` : ''}: ${conflict.classes.join(', ')}. The later class in the source order usually wins, so this may be unintended.`,
+      });
+    }
+  }
+
+  return conflicts;
+}
+
+/**
+ * Pulls class strings out of JSX/HTML/template files for Tailwind conflict analysis.
+ * Handles:
+ *   - className="..." and class="..."
+ *   - className={`...`} template literals
+ *   - cn('...', '...'), clsx('...'), twMerge('...') call expressions
+ *   - Object keys in cn({ 'class-name': condition }) syntax
+ */
+function extractClassStringsFromMarkup(source) {
+  const results = [];
+
+  // 1. Simple string and template-literal className/class attributes
+  const attrPattern = /(?:className|class)\s*=\s*(?:"([^"]*)"|'([^']*)'|\{`([^`]*)`\})/g;
+  let match;
+  while ((match = attrPattern.exec(source)) !== null) {
+    const raw = match[1] ?? match[2] ?? match[3] ?? '';
+    const cleaned = raw.replace(/\$\{[^}]*\}/g, '').trim();
+    if (cleaned) results.push(cleaned);
+  }
+
+  // 2. cn(...), clsx(...), twMerge(...), tw(...) call expressions
+  // Extract all string literal arguments and object-syntax string keys.
+  const callPattern = /\b(?:cn|clsx|twMerge|tw|classNames)\s*\(([^)]{0,800})\)/g;
+  while ((match = callPattern.exec(source)) !== null) {
+    const args = match[1];
+    // String literal args: 'foo bar' or "foo bar"
+    const stringArgs = /(?:"|')([^"']+)(?:"|')/g;
+    let strMatch;
+    const collected = [];
+    while ((strMatch = stringArgs.exec(args)) !== null) {
+      collected.push(strMatch[1].trim());
+    }
+    if (collected.length > 0) {
+      // Join all string args into one class list for conflict detection
+      results.push(collected.join(' '));
+    }
+  }
+
+  return results;
+}
+
+module.exports = { detectTailwindConflicts, extractClassStringsFromMarkup };