devlens-mcp 0.3.0

package/src/tools/ds-tools.ts

@@ -0,0 +1,395 @@
+import { z } from "zod";
+import { readFile, readdir, stat } from "fs/promises";
+import { resolve, join } from "path";
+import type { DesignSystemConfig } from "../config/devlens-config.js";
+
+/**
+ * Design System Context tool.
+ *
+ * When devlens.config.json is configured with a designSystem block,
+ * this tool scans the consumer project and returns:
+ *   - Design token values (colors, spacing, typography, etc.)
+ *   - TypeScript prop interfaces for DS components
+ *   - Component usage patterns found in the codebase
+ *
+ * The AI uses this context to write DS-compliant code when fixing
+ * differences found by devlens_compare_with_figma.
+ */
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface TokenEntry {
+  name: string;
+  value: string;
+  group: string;
+}
+
+export interface ComponentUsagePattern {
+  componentName: string;
+  importedFrom: string;
+  usageCount: number;
+  /** prop name → distinct values seen in the codebase */
+  sampleProps: Record<string, string[]>;
+  sourceFiles: string[];
+}
+
+// ─── Tool Schema ─────────────────────────────────────────────────────────────
+
+export const dsToolSchemas = {
+  devlens_ds_context: {
+    description:
+      "Get design system context: available DS3 components with their TypeScript prop interfaces, design token values (colors, spacing, typography), and usage patterns from the codebase. Use this before fixing code — it tells you exactly which components and tokens to use. Requires 'designSystem' to be configured in devlens.config.json (pointed to by DEVLENS_CONFIG env var).",
+    parameters: z.object({
+      includeTokens: z
+        .boolean()
+        .default(true)
+        .describe("Include design token values (colors, spacing, typography)"),
+      includeComponents: z
+        .boolean()
+        .default(true)
+        .describe("Scan source files for DS component usage patterns and prop value combinations"),
+      includeInterfaces: z
+        .boolean()
+        .default(true)
+        .describe("Include TypeScript prop interface definitions for each DS component"),
+    }),
+  },
+};
+
+// ─── Token Parsing ────────────────────────────────────────────────────────────
+
+/**
+ * Parse a TypeScript constants file for exported const objects.
+ * Handles patterns like:
+ *   export const FIGMA_COLORS = { KEY: '#hex', ... }
+ *   export const FIGMA_SPACING = { XS: 8, ... }
+ */
+async function parseTokensFile(absolutePath: string): Promise<TokenEntry[]> {
+  const tokens: TokenEntry[] = [];
+
+  let content: string;
+  try {
+    content = await readFile(absolutePath, "utf-8");
+  } catch {
+    return tokens;
+  }
+
+  const blockRegex = /export\s+const\s+(\w+)\s*=\s*\{([^}]+)\}/g;
+  let blockMatch: RegExpExecArray | null;
+
+  while ((blockMatch = blockRegex.exec(content)) !== null) {
+    const blockName = blockMatch[1];
+    const blockBody = blockMatch[2];
+
+    const lower = blockName.toLowerCase();
+    const group = lower.includes("color") ? "colors"
+                : lower.includes("spacing") ? "spacing"
+                : lower.includes("typo") ? "typography"
+                : lower.includes("shape") ? "shapes"
+                : lower.includes("dimension") ? "dimensions"
+                : "other";
+
+    const entryRegex = /['"]?(\w+)['"]?\s*:\s*([^,\n]+)/g;
+    let entryMatch: RegExpExecArray | null;
+
+    while ((entryMatch = entryRegex.exec(blockBody)) !== null) {
+      const name = entryMatch[1].trim();
+      const raw = entryMatch[2]
+        .trim()
+        .replace(/\/\/.*$/, "")   // strip trailing comments
+        .trim()
+        .replace(/,$/, "")         // strip trailing comma
+        .trim()
+        .replace(/^['"]/, "")      // strip leading quote
+        .replace(/['"]$/, "")      // strip trailing quote
+        .replace(/\s+as\s+const$/, "") // strip "as const"
+        .trim();
+
+      if (name && raw) {
+        tokens.push({ name, value: raw, group });
+      }
+    }
+  }
+
+  return tokens;
+}
+
+// ─── Component Interface Reading ──────────────────────────────────────────────
+
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "__tests__", "__mocks__", ".expo"]);
+
+/** Recursively walk a directory and collect .ts/.tsx files */
+async function collectSourceFiles(dir: string): Promise<string[]> {
+  const files: string[] = [];
+
+  async function walk(current: string): Promise<void> {
+    let entries: string[];
+    try {
+      entries = await readdir(current);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (SKIP_DIRS.has(entry)) continue;
+      const fullPath = join(current, entry);
+      try {
+        const s = await stat(fullPath);
+        if (s.isDirectory()) {
+          await walk(fullPath);
+        } else if (entry.endsWith(".tsx") || entry.endsWith(".ts")) {
+          files.push(fullPath);
+        }
+      } catch {
+        // ignore permission errors
+      }
+    }
+  }
+
+  await walk(dir);
+  return files;
+}
+
+/**
+ * Read component interface definitions from a DS components directory.
+ * Expects structure: componentsDir/<ComponentName>/generated/interface.ts
+ * Returns map of interface name → full TypeScript interface text.
+ */
+async function readComponentInterfaces(componentsDir: string): Promise<Record<string, string>> {
+  const interfaces: Record<string, string> = {};
+
+  let entries: string[];
+  try {
+    entries = await readdir(componentsDir);
+  } catch {
+    return interfaces;
+  }
+
+  for (const entry of entries) {
+    // Try common paths for generated interfaces
+    const candidates = [
+      join(componentsDir, entry, "generated", "interface.ts"),
+      join(componentsDir, entry, "interface.ts"),
+      join(componentsDir, entry, "types.ts"),
+    ];
+
+    for (const interfacePath of candidates) {
+      try {
+        const content = await readFile(interfacePath, "utf-8");
+        // Extract first interface name from "export interface FooProps {"
+        const nameMatch = content.match(/export\s+(?:interface|type)\s+(\w+)/);
+        if (nameMatch) {
+          interfaces[nameMatch[1]] = content.trim();
+          break; // found one for this component
+        }
+      } catch {
+        // file not found — try next candidate
+      }
+    }
+  }
+
+  return interfaces;
+}
+
+// ─── Usage Pattern Scanning ───────────────────────────────────────────────────
+
+/**
+ * Scan TSX/TS source files for DS component usages and collect prop patterns.
+ * Detects: <JDS*> components and common React Native DS component names.
+ */
+async function scanComponentUsages(
+  projectRoot: string
+): Promise<ComponentUsagePattern[]> {
+  const files = await collectSourceFiles(projectRoot);
+  const usageMap = new Map<string, ComponentUsagePattern>();
+
+  // Matches JSX tags: <JDSText variant="..." /> or <Icon name="..." />
+  const componentTagRegex = /<(JDS\w+|DS3\w+|(?:Icon|Chip|Divider|JDSButton|JDSInput|JDSText)\b)\s([^>]{0,500})(?:\/?>|>)/g;
+  const propRegex = /(\w+)=["'{]([^"'}\n]{0,80})["'}]/g;
+
+  for (const filePath of files) {
+    let content: string;
+    try {
+      content = await readFile(filePath, "utf-8");
+    } catch {
+      continue;
+    }
+
+    // Find import lines to identify where components come from
+    const importLines = content.match(/import[^;]+from\s+['"][^'"]+['"]/g) || [];
+
+    componentTagRegex.lastIndex = 0;
+    let tagMatch: RegExpExecArray | null;
+
+    while ((tagMatch = componentTagRegex.exec(content)) !== null) {
+      const componentName = tagMatch[1];
+      const propsStr = tagMatch[2];
+
+      // Find import source for this component
+      const importedFrom = importLines
+        .find(line => line.includes(componentName))
+        ?.match(/from\s+['"]([^'"]+)['"]/)?.[1] ?? "unknown";
+
+      if (!usageMap.has(componentName)) {
+        usageMap.set(componentName, {
+          componentName,
+          importedFrom,
+          usageCount: 0,
+          sampleProps: {},
+          sourceFiles: [],
+        });
+      }
+
+      const usage = usageMap.get(componentName)!;
+      usage.usageCount++;
+
+      if (!usage.sourceFiles.includes(filePath)) {
+        usage.sourceFiles.push(filePath);
+      }
+
+      propRegex.lastIndex = 0;
+      let propMatch: RegExpExecArray | null;
+      while ((propMatch = propRegex.exec(propsStr)) !== null) {
+        const propName = propMatch[1];
+        const propValue = propMatch[2];
+        if (!usage.sampleProps[propName]) {
+          usage.sampleProps[propName] = [];
+        }
+        if (!usage.sampleProps[propName].includes(propValue)) {
+          usage.sampleProps[propName].push(propValue);
+        }
+      }
+    }
+  }
+
+  return Array.from(usageMap.values()).sort((a, b) => b.usageCount - a.usageCount);
+}
+
+// ─── Formatting ───────────────────────────────────────────────────────────────
+
+function formatOutput(
+  dsName: string,
+  tokens: TokenEntry[],
+  componentInterfaces: Record<string, string>,
+  components: ComponentUsagePattern[]
+): string {
+  const lines: string[] = [`=== Design System: ${dsName} ===`, ""];
+
+  // Tokens grouped by category
+  if (tokens.length > 0) {
+    const groups = new Map<string, TokenEntry[]>();
+    for (const t of tokens) {
+      if (!groups.has(t.group)) groups.set(t.group, []);
+      groups.get(t.group)!.push(t);
+    }
+    for (const [group, groupTokens] of groups) {
+      lines.push(`--- ${group.toUpperCase()} ---`);
+      for (const t of groupTokens) {
+        lines.push(`  ${t.name}: ${t.value}`);
+      }
+      lines.push("");
+    }
+  }
+
+  // Component TypeScript interfaces
+  if (Object.keys(componentInterfaces).length > 0) {
+    lines.push("--- COMPONENT INTERFACES ---");
+    for (const [, iface] of Object.entries(componentInterfaces)) {
+      lines.push("", iface);
+    }
+    lines.push("");
+  }
+
+  // Usage patterns
+  if (components.length > 0) {
+    lines.push("--- COMPONENT USAGE PATTERNS ---");
+    lines.push("(props and values observed in the codebase)");
+    for (const c of components.slice(0, 20)) {
+      lines.push(`\n${c.componentName}  (${c.usageCount} uses, from '${c.importedFrom}')`);
+      for (const [prop, values] of Object.entries(c.sampleProps)) {
+        lines.push(`  ${prop}: ${values.slice(0, 10).join(" | ")}`);
+      }
+    }
+  }
+
+  return lines.join("\n");
+}
+
+// ─── Handler Factory ──────────────────────────────────────────────────────────
+
+export function createDsToolHandlers(dsConfig: DesignSystemConfig | undefined) {
+  return {
+    devlens_ds_context: async (params: {
+      includeTokens: boolean;
+      includeComponents: boolean;
+      includeInterfaces: boolean;
+    }) => {
+      if (!dsConfig) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: [
+                "No design system configured.",
+                "",
+                "To enable DS context, create devlens.config.json in your app root:",
+                JSON.stringify(
+                  {
+                    designSystem: {
+                      name: "jds3",
+                      projectRoot: "/absolute/path/to/your-app",
+                      tokensFile: "src/constants/figmaTokens.ts",
+                      componentsDir: "src/jds-components",
+                      componentsGlob: "src/**/*.tsx",
+                    },
+                  },
+                  null,
+                  2
+                ),
+                "",
+                "Then point to it in your MCP config env block:",
+                '  "DEVLENS_CONFIG": "/absolute/path/to/your-app/devlens.config.json"',
+              ].join("\n"),
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      const absoluteProjectRoot = resolve(dsConfig.projectRoot);
+      const absoluteTokensFile = join(absoluteProjectRoot, dsConfig.tokensFile);
+      const absoluteComponentsDir = dsConfig.componentsDir
+        ? join(absoluteProjectRoot, dsConfig.componentsDir)
+        : null;
+
+      // Run all analyses in parallel
+      const [tokens, componentInterfaces, components] = await Promise.all([
+        params.includeTokens
+          ? parseTokensFile(absoluteTokensFile)
+          : Promise.resolve([] as TokenEntry[]),
+        params.includeInterfaces && absoluteComponentsDir
+          ? readComponentInterfaces(absoluteComponentsDir)
+          : Promise.resolve({} as Record<string, string>),
+        params.includeComponents
+          ? scanComponentUsages(absoluteProjectRoot)
+          : Promise.resolve([] as ComponentUsagePattern[]),
+      ]);
+
+      const summary = [
+        `${tokens.length} tokens`,
+        `${Object.keys(componentInterfaces).length} component interfaces`,
+        `${components.reduce((s, c) => s + c.usageCount, 0)} component usages across ${components.length} component types`,
+      ].join(", ");
+
+      console.error(`[devlens] DS context: ${summary}`);
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: formatOutput(dsConfig.name, tokens, componentInterfaces, components),
+          },
+        ],
+      };
+    },
+  };
+}