@stayicon/drift-guard 0.1.0

package/dist/chunk-27T45SVD.js

@@ -0,0 +1,627 @@
+// src/types/index.ts
+var DEFAULT_CONFIG = {
+  cssFiles: [
+    "src/**/*.css",
+    "app/**/*.css",
+    "styles/**/*.css",
+    "**/*.module.css",
+    "**/*.css"
+  ],
+  htmlFiles: [
+    "**/*.html",
+    "!node_modules/**",
+    "!dist/**",
+    "!build/**"
+  ],
+  threshold: 10,
+  trackCategories: ["color", "font", "spacing", "shadow", "radius", "layout"],
+  ignore: [
+    "node_modules/**",
+    "dist/**",
+    "build/**",
+    ".next/**",
+    "coverage/**"
+  ]
+};
+
+// src/core/snapshot.ts
+import fs from "fs";
+import path from "path";
+import fg from "fast-glob";
+
+// src/parsers/css-parser.ts
+import * as csstree from "css-tree";
+var CATEGORY_MAP = {
+  // Colors
+  "color": "color",
+  "background-color": "color",
+  "background": "color",
+  "border-color": "color",
+  "outline-color": "color",
+  "fill": "color",
+  "stroke": "color",
+  "--color": "color",
+  // Fonts
+  "font-family": "font",
+  "font-size": "font",
+  "font-weight": "font",
+  "line-height": "font",
+  "letter-spacing": "font",
+  // Spacing
+  "margin": "spacing",
+  "margin-top": "spacing",
+  "margin-right": "spacing",
+  "margin-bottom": "spacing",
+  "margin-left": "spacing",
+  "padding": "spacing",
+  "padding-top": "spacing",
+  "padding-right": "spacing",
+  "padding-bottom": "spacing",
+  "padding-left": "spacing",
+  "gap": "spacing",
+  "row-gap": "spacing",
+  "column-gap": "spacing",
+  // Shadows
+  "box-shadow": "shadow",
+  "text-shadow": "shadow",
+  // Radius
+  "border-radius": "radius",
+  "border-top-left-radius": "radius",
+  "border-top-right-radius": "radius",
+  "border-bottom-left-radius": "radius",
+  "border-bottom-right-radius": "radius",
+  // Layout
+  "display": "layout",
+  "flex-direction": "layout",
+  "justify-content": "layout",
+  "align-items": "layout",
+  "grid-template-columns": "layout",
+  "grid-template-rows": "layout",
+  "position": "layout"
+};
+function getCategory(property) {
+  if (CATEGORY_MAP[property]) {
+    return CATEGORY_MAP[property];
+  }
+  if (property.startsWith("--")) {
+    const lower = property.toLowerCase();
+    if (lower.includes("color") || lower.includes("bg") || lower.includes("text")) return "color";
+    if (lower.includes("font") || lower.includes("size") || lower.includes("weight")) return "font";
+    if (lower.includes("spacing") || lower.includes("margin") || lower.includes("padding") || lower.includes("gap")) return "spacing";
+    if (lower.includes("shadow")) return "shadow";
+    if (lower.includes("radius") || lower.includes("rounded")) return "radius";
+    return "other";
+  }
+  return null;
+}
+function parseCss(cssContent, filePath) {
+  const tokens = [];
+  try {
+    const ast = csstree.parse(cssContent, {
+      filename: filePath,
+      positions: true
+    });
+    csstree.walk(ast, {
+      visit: "Declaration",
+      enter(node) {
+        const property = node.property;
+        const category = getCategory(property);
+        if (!category) return;
+        const value = csstree.generate(node.value);
+        if (!value || ["inherit", "initial", "unset", "revert"].includes(value)) return;
+        let selector = ":root";
+        let parent = this.atrule ?? this.rule;
+        if (parent && parent.type === "Rule" && parent.prelude) {
+          selector = csstree.generate(parent.prelude);
+        }
+        tokens.push({
+          category,
+          property,
+          value: value.trim(),
+          selector,
+          file: filePath,
+          line: node.loc?.start?.line
+        });
+      }
+    });
+  } catch (error) {
+    console.warn(`Warning: Failed to parse CSS in ${filePath}: ${error.message}`);
+  }
+  return tokens;
+}
+function extractCssVariables(cssContent, filePath) {
+  const tokens = [];
+  const varRegex = /--([\w-]+)\s*:\s*([^;]+)/g;
+  let match;
+  while ((match = varRegex.exec(cssContent)) !== null) {
+    const property = `--${match[1]}`;
+    const value = match[2].trim();
+    const category = getCategory(property) ?? "other";
+    tokens.push({
+      category,
+      property,
+      value,
+      selector: ":root",
+      file: filePath,
+      line: cssContent.substring(0, match.index).split("\n").length
+    });
+  }
+  return tokens;
+}
+
+// src/parsers/html-parser.ts
+import * as cheerio from "cheerio";
+var TRACKED_PROPERTIES = {
+  "color": "color",
+  "background-color": "color",
+  "background": "color",
+  "border-color": "color",
+  "font-family": "font",
+  "font-size": "font",
+  "font-weight": "font",
+  "line-height": "font",
+  "margin": "spacing",
+  "margin-top": "spacing",
+  "margin-right": "spacing",
+  "margin-bottom": "spacing",
+  "margin-left": "spacing",
+  "padding": "spacing",
+  "padding-top": "spacing",
+  "padding-right": "spacing",
+  "padding-bottom": "spacing",
+  "padding-left": "spacing",
+  "gap": "spacing",
+  "box-shadow": "shadow",
+  "text-shadow": "shadow",
+  "border-radius": "radius",
+  "display": "layout",
+  "flex-direction": "layout",
+  "justify-content": "layout",
+  "align-items": "layout"
+};
+function parseInlineStyle(styleStr) {
+  const result = {};
+  const declarations = styleStr.split(";").filter(Boolean);
+  for (const decl of declarations) {
+    const colonIdx = decl.indexOf(":");
+    if (colonIdx === -1) continue;
+    const prop = decl.substring(0, colonIdx).trim().toLowerCase();
+    const val = decl.substring(colonIdx + 1).trim();
+    if (prop && val) {
+      result[prop] = val;
+    }
+  }
+  return result;
+}
+function parseHtml(htmlContent, filePath) {
+  const tokens = [];
+  const $ = cheerio.load(htmlContent);
+  const styleBlocks = [];
+  $("style").each((_, el) => {
+    const text = $(el).text();
+    if (text) {
+      styleBlocks.push(text);
+    }
+  });
+  $("[style]").each((_, el) => {
+    const element = $(el);
+    const styleStr = element.attr("style");
+    if (!styleStr) return;
+    const selector = buildSelectorPath($, element);
+    const styles = parseInlineStyle(styleStr);
+    for (const [prop, value] of Object.entries(styles)) {
+      const category = TRACKED_PROPERTIES[prop];
+      if (!category) continue;
+      tokens.push({
+        category,
+        property: prop,
+        value,
+        selector: `[inline] ${selector}`,
+        file: filePath
+      });
+    }
+  });
+  return tokens;
+}
+function extractStyleBlocks(htmlContent) {
+  const $ = cheerio.load(htmlContent);
+  const blocks = [];
+  $("style").each((_, el) => {
+    const text = $(el).text();
+    if (text) {
+      blocks.push(text);
+    }
+  });
+  return blocks;
+}
+function buildSelectorPath($, element) {
+  const parts = [];
+  const tagName = element.prop("tagName")?.toLowerCase() ?? "div";
+  const id = element.attr("id");
+  const className = element.attr("class");
+  let sel = tagName;
+  if (id) {
+    sel += `#${id}`;
+  } else if (className) {
+    const classList = className.split(/\s+/).slice(0, 2).join(".");
+    sel += `.${classList}`;
+  }
+  parts.push(sel);
+  return parts.join(" > ");
+}
+
+// src/core/snapshot.ts
+var SNAPSHOT_DIR = ".design-guard";
+var SNAPSHOT_FILE = "snapshot.json";
+var CONFIG_FILE = "config.json";
+function getSnapshotPath(projectRoot) {
+  return path.join(projectRoot, SNAPSHOT_DIR, SNAPSHOT_FILE);
+}
+function getConfigPath(projectRoot) {
+  return path.join(projectRoot, SNAPSHOT_DIR, CONFIG_FILE);
+}
+function loadConfig(projectRoot) {
+  const configPath = getConfigPath(projectRoot);
+  if (fs.existsSync(configPath)) {
+    const raw = fs.readFileSync(configPath, "utf-8");
+    return { ...DEFAULT_CONFIG, ...JSON.parse(raw) };
+  }
+  return { ...DEFAULT_CONFIG };
+}
+function saveConfig(projectRoot, config) {
+  const dir = path.join(projectRoot, SNAPSHOT_DIR);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(getConfigPath(projectRoot), JSON.stringify(config, null, 2), "utf-8");
+}
+async function scanProject(projectRoot, config, stitchHtmlPath) {
+  const allTokens = [];
+  const scannedFiles = [];
+  if (stitchHtmlPath) {
+    const absPath = path.resolve(projectRoot, stitchHtmlPath);
+    if (fs.existsSync(absPath)) {
+      const htmlContent = fs.readFileSync(absPath, "utf-8");
+      const htmlTokens = parseHtml(htmlContent, stitchHtmlPath);
+      allTokens.push(...htmlTokens);
+      const styleBlocks = extractStyleBlocks(htmlContent);
+      for (const block of styleBlocks) {
+        const cssTokens = parseCss(block, stitchHtmlPath);
+        allTokens.push(...cssTokens);
+        const vars = extractCssVariables(block, stitchHtmlPath);
+        allTokens.push(...vars);
+      }
+      scannedFiles.push(stitchHtmlPath);
+    }
+  }
+  const cssFiles = await fg(config.cssFiles, {
+    cwd: projectRoot,
+    ignore: config.ignore,
+    absolute: false
+  });
+  for (const file of cssFiles) {
+    const absPath = path.join(projectRoot, file);
+    const content = fs.readFileSync(absPath, "utf-8");
+    const tokens = parseCss(content, file);
+    allTokens.push(...tokens);
+    const vars = extractCssVariables(content, file);
+    allTokens.push(...vars);
+    scannedFiles.push(file);
+  }
+  const htmlFiles = await fg(config.htmlFiles, {
+    cwd: projectRoot,
+    ignore: config.ignore,
+    absolute: false
+  });
+  for (const file of htmlFiles) {
+    if (scannedFiles.includes(file)) continue;
+    const absPath = path.join(projectRoot, file);
+    const content = fs.readFileSync(absPath, "utf-8");
+    const tokens = parseHtml(content, file);
+    allTokens.push(...tokens);
+    const styleBlocks = extractStyleBlocks(content);
+    for (const block of styleBlocks) {
+      const cssTokens = parseCss(block, file);
+      allTokens.push(...cssTokens);
+    }
+    scannedFiles.push(file);
+  }
+  const filtered = allTokens.filter(
+    (t) => config.trackCategories.includes(t.category)
+  );
+  const seen = /* @__PURE__ */ new Set();
+  const deduplicated = filtered.filter((t) => {
+    const key = `${t.file}:${t.selector}:${t.property}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+  return { tokens: deduplicated, files: scannedFiles };
+}
+function buildSummary(tokens) {
+  const summary = {
+    color: 0,
+    font: 0,
+    spacing: 0,
+    shadow: 0,
+    radius: 0,
+    layout: 0,
+    other: 0
+  };
+  for (const token of tokens) {
+    summary[token.category]++;
+  }
+  return summary;
+}
+async function createSnapshot(projectRoot, stitchHtmlPath) {
+  const config = loadConfig(projectRoot);
+  const { tokens, files } = await scanProject(projectRoot, config, stitchHtmlPath);
+  const snapshot = {
+    version: "1.0.0",
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    projectRoot,
+    sourceFiles: files,
+    tokens,
+    summary: buildSummary(tokens)
+  };
+  return snapshot;
+}
+function saveSnapshot(projectRoot, snapshot) {
+  const dir = path.join(projectRoot, SNAPSHOT_DIR);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  const snapshotPath = getSnapshotPath(projectRoot);
+  fs.writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2), "utf-8");
+  return snapshotPath;
+}
+function loadSnapshot(projectRoot) {
+  const snapshotPath = getSnapshotPath(projectRoot);
+  if (!fs.existsSync(snapshotPath)) {
+    return null;
+  }
+  const raw = fs.readFileSync(snapshotPath, "utf-8");
+  return JSON.parse(raw);
+}
+
+// src/core/drift.ts
+function tokenKey(token) {
+  return `${token.file}::${token.selector}::${token.property}`;
+}
+async function detectDrift(projectRoot, snapshot, threshold = 10) {
+  const config = loadConfig(projectRoot);
+  const { tokens: currentTokens } = await scanProject(projectRoot, config);
+  const snapshotMap = /* @__PURE__ */ new Map();
+  for (const token of snapshot.tokens) {
+    snapshotMap.set(tokenKey(token), token);
+  }
+  const currentMap = /* @__PURE__ */ new Map();
+  for (const token of currentTokens) {
+    currentMap.set(tokenKey(token), token);
+  }
+  const driftItems = [];
+  for (const [key, original] of snapshotMap) {
+    const current = currentMap.get(key);
+    if (!current) {
+      driftItems.push({
+        original,
+        current: null,
+        changeType: "deleted"
+      });
+    } else if (current.value !== original.value) {
+      driftItems.push({
+        original,
+        current,
+        changeType: "modified"
+      });
+    }
+  }
+  const totalTokens = snapshot.tokens.length;
+  const changedTokens = driftItems.length;
+  const driftScore = totalTokens > 0 ? Math.round(changedTokens / totalTokens * 100 * 100) / 100 : 0;
+  const categorySummary = {};
+  const categories = ["color", "font", "spacing", "shadow", "radius", "layout", "other"];
+  for (const cat of categories) {
+    const total = snapshot.tokens.filter((t) => t.category === cat).length;
+    const changed = driftItems.filter((d) => d.original.category === cat).length;
+    categorySummary[cat] = {
+      total,
+      changed,
+      driftPercent: total > 0 ? Math.round(changed / total * 100 * 100) / 100 : 0
+    };
+  }
+  return {
+    checkedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    snapshotCreatedAt: snapshot.createdAt,
+    totalTokens,
+    changedTokens,
+    driftScore,
+    threshold,
+    passed: driftScore <= threshold,
+    items: driftItems,
+    categorySummary
+  };
+}
+
+// src/core/rules-generator.ts
+import fs2 from "fs";
+import path2 from "path";
+function generateRules(snapshot, format) {
+  const generators = {
+    "cursorrules": () => generateCursorRules(snapshot),
+    "claude-md": () => generateClaudeMd(snapshot),
+    "agents-md": () => generateAgentsMd(snapshot),
+    "copilot": () => generateCopilotInstructions(snapshot),
+    "clinerules": () => generateClineRules(snapshot)
+  };
+  return generators[format]();
+}
+function saveRules(projectRoot, format, content, append = false) {
+  const fileMap = {
+    "cursorrules": ".cursorrules",
+    "claude-md": "CLAUDE.md",
+    "agents-md": "AGENTS.md",
+    "copilot": ".github/copilot-instructions.md",
+    "clinerules": ".clinerules"
+  };
+  const filePath = path2.join(projectRoot, fileMap[format]);
+  const dir = path2.dirname(filePath);
+  if (!fs2.existsSync(dir)) {
+    fs2.mkdirSync(dir, { recursive: true });
+  }
+  if (append && fs2.existsSync(filePath)) {
+    const existing = fs2.readFileSync(filePath, "utf-8");
+    fs2.writeFileSync(filePath, existing + "\n\n" + content, "utf-8");
+  } else {
+    fs2.writeFileSync(filePath, content, "utf-8");
+  }
+  return filePath;
+}
+function buildTokenList(snapshot) {
+  const colorTokens = snapshot.tokens.filter((t) => t.category === "color");
+  const fontTokens = snapshot.tokens.filter((t) => t.category === "font");
+  const spacingTokens = snapshot.tokens.filter((t) => t.category === "spacing");
+  const radiusTokens = snapshot.tokens.filter((t) => t.category === "radius");
+  const lines = [];
+  if (colorTokens.length > 0) {
+    lines.push("### Colors (DO NOT CHANGE)");
+    const unique = [...new Set(colorTokens.map((t) => `${t.property}: ${t.value}`))];
+    for (const t of unique.slice(0, 30)) {
+      lines.push(`- \`${t}\``);
+    }
+  }
+  if (fontTokens.length > 0) {
+    lines.push("\n### Fonts (DO NOT CHANGE)");
+    const unique = [...new Set(fontTokens.map((t) => `${t.property}: ${t.value}`))];
+    for (const t of unique.slice(0, 15)) {
+      lines.push(`- \`${t}\``);
+    }
+  }
+  if (spacingTokens.length > 0) {
+    lines.push("\n### Spacing (DO NOT CHANGE)");
+    const unique = [...new Set(spacingTokens.map((t) => `${t.property}: ${t.value}`))];
+    for (const t of unique.slice(0, 20)) {
+      lines.push(`- \`${t}\``);
+    }
+  }
+  if (radiusTokens.length > 0) {
+    lines.push("\n### Border Radius (DO NOT CHANGE)");
+    const unique = [...new Set(radiusTokens.map((t) => `${t.property}: ${t.value}`))];
+    for (const t of unique.slice(0, 10)) {
+      lines.push(`- \`${t}\``);
+    }
+  }
+  return lines.join("\n");
+}
+function generateCursorRules(snapshot) {
+  return `# Design Guard \u2014 Locked Design Tokens
+# Generated by drift-guard on ${snapshot.createdAt}
+# DO NOT modify these values when adding features or fixing bugs.
+
+## CRITICAL: Design Drift Prevention
+
+When modifying this codebase, you MUST preserve the following design tokens exactly as they are.
+Do NOT change colors, fonts, spacing, or border-radius values unless explicitly asked to update the design.
+
+If you need to add new styles, use the existing design tokens as reference.
+If a design change is needed, tell the user to run \`drift-guard snapshot update\` after making the change.
+
+${buildTokenList(snapshot)}
+
+## Rules
+1. NEVER change existing CSS color values
+2. NEVER change font-family, font-size, or font-weight values
+3. NEVER change margin, padding, or gap values on existing elements
+4. NEVER change border-radius values
+5. When adding new components, use the SAME design tokens listed above
+6. If you must change a design token, warn the user first
+`;
+}
+function generateClaudeMd(snapshot) {
+  return `# Design Guard \u2014 Locked Design Tokens
+
+> Generated by drift-guard on ${snapshot.createdAt}
+> Run \`npx drift-guard check\` to verify design consistency
+
+## Design Drift Prevention Rules
+
+When working on this codebase, preserve the existing design exactly as-is.
+The following design tokens are LOCKED and should NOT be modified:
+
+${buildTokenList(snapshot)}
+
+## Important
+- Adding new features should NOT change existing visual styles
+- If a CSS change affects existing components, flag it to the user
+- New components should follow the same design language (colors, fonts, spacing)
+- Run \`npx drift-guard check\` before committing to verify no design drift
+`;
+}
+function generateAgentsMd(snapshot) {
+  return `# AGENTS.md \u2014 Design Guard Rules
+
+> Auto-generated by drift-guard. Do not edit manually.
+> Snapshot: ${snapshot.createdAt} | Tokens: ${snapshot.tokens.length}
+
+## Design Token Protection
+
+This project uses drift-guard to prevent design drift during AI-assisted development.
+The following design tokens are protected:
+
+${buildTokenList(snapshot)}
+
+## Agent Instructions
+1. Do NOT modify existing CSS values for colors, fonts, spacing, or border-radius
+2. New components MUST use the same design tokens
+3. Run \`npx drift-guard check\` before suggesting commits
+4. If design changes are intentional, inform the user to update the snapshot
+`;
+}
+function generateCopilotInstructions(snapshot) {
+  return `# Copilot Instructions \u2014 Design Guard
+
+This project has locked design tokens. When suggesting code changes:
+
+1. Preserve all existing CSS color, font, spacing, and border-radius values
+2. Use the project's design tokens for new components
+3. Do not override CSS custom properties (variables starting with --)
+
+Protected tokens (${snapshot.tokens.length} total):
+
+${buildTokenList(snapshot)}
+`;
+}
+function generateClineRules(snapshot) {
+  return `# Design Guard \u2014 Protected Design Tokens
+# Generated: ${snapshot.createdAt}
+
+DESIGN_PROTECTION=true
+
+## Rules
+- Do NOT change existing CSS values
+- Preserve colors: ${snapshot.summary.color} tokens locked
+- Preserve fonts: ${snapshot.summary.font} tokens locked
+- Preserve spacing: ${snapshot.summary.spacing} tokens locked
+- Preserve radius: ${snapshot.summary.radius} tokens locked
+
+## Verification
+Run: npx drift-guard check
+Threshold: Changes to more than 10% of design tokens will be flagged
+
+${buildTokenList(snapshot)}
+`;
+}
+
+export {
+  DEFAULT_CONFIG,
+  loadConfig,
+  saveConfig,
+  scanProject,
+  createSnapshot,
+  saveSnapshot,
+  loadSnapshot,
+  detectDrift,
+  generateRules,
+  saveRules
+};
+//# sourceMappingURL=chunk-27T45SVD.js.map