dslinter 0.1.13 → 0.2.0

package/src/mcp/report-cache.ts

@@ -0,0 +1,209 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { enrichPlaygroundsFromTs } from "../../bin/lib/enrich-playgrounds-from-ts.mjs";
+import { runScannerSync } from "../../bin/lib/run-scanner.mjs";
+import type { McpConfig } from "./config";
+import { normalizeReportPaths } from "./normalize-paths";
+import type { WorkspaceReport } from "../types/report";
+
+const require = createRequire(import.meta.url);
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
+
+export type ReportCacheState = {
+  report: WorkspaceReport | null;
+  loadedAt: number;
+  source: "file" | "scan" | "dev";
+};
+
+export class ReportCache {
+  private state: ReportCacheState = {
+    report: null,
+    loadedAt: 0,
+    source: "file",
+  };
+  private sseAbort: AbortController | null = null;
+  private readonly config: McpConfig;
+
+  constructor(config: McpConfig) {
+    this.config = config;
+  }
+
+  async getReport(opts: { fresh?: boolean } = {}): Promise<WorkspaceReport> {
+    if (!opts.fresh && this.state.report && this.isFresh()) {
+      return this.state.report;
+    }
+
+    const fromDev = await this.tryLoadDevServer();
+    if (fromDev) {
+      this.setState(fromDev, "dev");
+      return fromDev;
+    }
+
+    if (!opts.fresh && (await this.tryLoadFile())) {
+      return this.state.report!;
+    }
+
+    const scanned = await this.runScan();
+    this.setState(scanned, "scan");
+    return scanned;
+  }
+
+  startDevWatch(): void {
+    if (this.sseAbort) return;
+    this.sseAbort = new AbortController();
+    void this.watchDevSse(this.sseAbort.signal);
+  }
+
+  stopDevWatch(): void {
+    this.sseAbort?.abort();
+    this.sseAbort = null;
+  }
+
+  invalidate(): void {
+    this.state.loadedAt = 0;
+  }
+
+  reportHash(): string | null {
+    if (!this.state.report) return null;
+    const json = JSON.stringify(this.state.report);
+    return createHash("sha256").update(json).digest("hex");
+  }
+
+  private isFresh(): boolean {
+    return Date.now() - this.state.loadedAt < this.config.ttlMs;
+  }
+
+  private setState(report: WorkspaceReport, source: ReportCacheState["source"]): void {
+    this.state = { report, loadedAt: Date.now(), source };
+  }
+
+  private async tryLoadFile(): Promise<boolean> {
+    try {
+      const st = await stat(this.config.reportPath);
+      if (Date.now() - st.mtimeMs > this.config.ttlMs) return false;
+      const raw = await readFile(this.config.reportPath, "utf8");
+      const report = normalizeReportPaths(JSON.parse(raw) as WorkspaceReport);
+      this.setState(report, "file");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private async tryLoadDevServer(): Promise<WorkspaceReport | null> {
+    const url = `${this.config.devUrl.replace(/\/$/, "")}/dslinter-report.json`;
+    try {
+      const res = await fetch(url, {
+        cache: "no-store",
+        signal: AbortSignal.timeout(2000),
+      });
+      if (!res.ok) return null;
+      const report = normalizeReportPaths((await res.json()) as WorkspaceReport);
+      return report;
+    } catch {
+      return null;
+    }
+  }
+
+  private async watchDevSse(signal: AbortSignal): Promise<void> {
+    const url = `${this.config.devUrl.replace(/\/$/, "")}/events`;
+    try {
+      const res = await fetch(url, { headers: { Accept: "text/event-stream" }, signal });
+      if (!res.ok || !res.body) return;
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      while (!signal.aborted) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        if (buffer.includes("data: updated")) {
+          buffer = "";
+          this.invalidate();
+          const fromDev = await this.tryLoadDevServer();
+          if (fromDev) this.setState(fromDev, "dev");
+        }
+      }
+    } catch {
+      // dev server not running
+    }
+  }
+
+  private async runScan(): Promise<WorkspaceReport> {
+    const args = [
+      this.config.scanPath,
+      "--output",
+      this.config.reportPath,
+      "--json",
+    ];
+
+    let json = "";
+    try {
+      const { scanWorkspaceJson } = require(join(packageRoot, "index.cjs"));
+      json = scanWorkspaceJson(this.config.scanPath, false);
+    } catch {
+      const code = runScannerSync(args, {
+        projectRoot: this.config.projectRoot,
+        captureStdout: true,
+      });
+      if (code !== 0) {
+        throw new Error(`dslinter scan failed with exit code ${code}`);
+      }
+      json = await readFile(this.config.reportPath, "utf8");
+    }
+
+    let report = normalizeReportPaths(JSON.parse(json) as WorkspaceReport);
+    await enrichPlaygroundsFromTs({
+      projectRoot: this.config.projectRoot,
+      reportPath: this.config.reportPath,
+    });
+
+    try {
+      const enriched = await readFile(this.config.reportPath, "utf8");
+      report = normalizeReportPaths(JSON.parse(enriched) as WorkspaceReport);
+    } catch {
+      // use scan-only report
+    }
+
+    await mkdir(dirname(this.config.reportPath), { recursive: true });
+    await writeFile(this.config.reportPath, JSON.stringify(report, null, 2));
+
+    return report;
+  }
+}
+
+export type BaselineStore = {
+  hash: string;
+  saved_at: string;
+  scores: WorkspaceReport["scores"];
+  finding_count: number;
+};
+
+export async function loadBaseline(projectRoot: string): Promise<BaselineStore | null> {
+  const path = join(projectRoot, ".dslinter", "mcp-baseline.json");
+  try {
+    const raw = await readFile(path, "utf8");
+    return JSON.parse(raw) as BaselineStore;
+  } catch {
+    return null;
+  }
+}
+
+export async function saveBaseline(
+  projectRoot: string,
+  report: WorkspaceReport,
+  hash: string,
+): Promise<void> {
+  const dir = join(projectRoot, ".dslinter");
+  await mkdir(dir, { recursive: true });
+  const payload: BaselineStore = {
+    hash,
+    saved_at: new Date().toISOString(),
+    scores: report.scores,
+    finding_count: report.findings?.length ?? 0,
+  };
+  await writeFile(join(dir, "mcp-baseline.json"), JSON.stringify(payload, null, 2));
+}

package/src/mcp/rule-catalog.json

@@ -0,0 +1,156 @@
+[
+  {
+    "rule_id": "a11y-img-alt",
+    "pillar": "a11y",
+    "default_severity": "warning",
+    "description": "`<img>` must include an `alt` attribute for screen readers.",
+    "fix_hint": "Add alt=\"\" for decorative images or a descriptive alt for meaningful images."
+  },
+  {
+    "rule_id": "a11y-button-name",
+    "pillar": "a11y",
+    "default_severity": "warning",
+    "description": "`<button>` must have an accessible name (text content or aria-label).",
+    "fix_hint": "Add visible text, aria-label, or aria-labelledby."
+  },
+  {
+    "rule_id": "a11y-input-label",
+    "pillar": "a11y",
+    "default_severity": "warning",
+    "description": "`<input>` should have an associated label or aria-label.",
+    "fix_hint": "Wrap with <Label htmlFor=...> or add aria-label."
+  },
+  {
+    "rule_id": "a11y-anchor-href",
+    "pillar": "a11y",
+    "default_severity": "warning",
+    "description": "`<a>` should have a meaningful href.",
+    "fix_hint": "Use a valid href or replace with <button> for actions."
+  },
+  {
+    "rule_id": "a11y-anchor-placeholder-href",
+    "pillar": "a11y",
+    "default_severity": "warning",
+    "description": "`<a href=\"#\">` is a placeholder link pattern.",
+    "fix_hint": "Use <button type=\"button\"> or a real destination URL."
+  },
+  {
+    "rule_id": "a11y-dark-mode-contrast",
+    "pillar": "a11y",
+    "default_severity": "warning",
+    "description": "Light-mode color classes may lack a dark: variant.",
+    "fix_hint": "Add matching dark: text/background utilities or theme tokens."
+  },
+  {
+    "rule_id": "token-hardcoded-color",
+    "pillar": "token",
+    "default_severity": "warning",
+    "description": "Hardcoded hex/rgb color instead of design tokens.",
+    "fix_hint": "Replace with a CSS variable or Tailwind theme utility from css_tokens."
+  },
+  {
+    "rule_id": "token-tailwind-arbitrary",
+    "pillar": "token",
+    "default_severity": "warning",
+    "description": "Tailwind arbitrary value (e.g. bg-[#fff]) bypasses the token system.",
+    "fix_hint": "Use a named theme utility or CSS custom property."
+  },
+  {
+    "rule_id": "token-unused-css-var",
+    "pillar": "token",
+    "default_severity": "info",
+    "description": "CSS custom property defined but never referenced.",
+    "fix_hint": "Remove unused token or reference it via var(--name) or Tailwind."
+  },
+  {
+    "rule_id": "deprecated-component",
+    "pillar": "usage",
+    "default_severity": "warning",
+    "description": "Component is listed as deprecated in .dslinter.json.",
+    "fix_hint": "Replace with the canonical component from the catalog (check usage_by_component)."
+  },
+  {
+    "rule_id": "duplicate-component",
+    "pillar": "usage",
+    "default_severity": "warning",
+    "description": "Same component name is defined in multiple files.",
+    "fix_hint": "Consolidate into one definition and update imports."
+  },
+  {
+    "rule_id": "unused-prop",
+    "pillar": "usage",
+    "default_severity": "info",
+    "description": "Declared prop is never passed at any call site.",
+    "fix_hint": "Remove unused prop from the API or document why it exists."
+  },
+  {
+    "rule_id": "variant-explosion",
+    "pillar": "usage",
+    "default_severity": "info",
+    "description": "Component has an unusually large prop surface at call sites.",
+    "fix_hint": "Split into smaller components or reduce optional props."
+  },
+  {
+    "rule_id": "code-console",
+    "pillar": "code",
+    "default_severity": "info",
+    "description": "console.log (or similar) left in component code.",
+    "fix_hint": "Remove debug logging before shipping."
+  },
+  {
+    "rule_id": "code-console-error",
+    "pillar": "code",
+    "default_severity": "warning",
+    "description": "console.error in component code.",
+    "fix_hint": "Use proper error handling or remove."
+  },
+  {
+    "rule_id": "code-debugger",
+    "pillar": "code",
+    "default_severity": "error",
+    "description": "debugger statement in source.",
+    "fix_hint": "Remove debugger."
+  },
+  {
+    "rule_id": "code-inline-style",
+    "pillar": "code",
+    "default_severity": "warning",
+    "description": "Inline JSX style={{}} bypasses token/Tailwind conventions.",
+    "fix_hint": "Use className with theme utilities."
+  },
+  {
+    "rule_id": "code-empty-catch",
+    "pillar": "code",
+    "default_severity": "warning",
+    "description": "Empty catch block swallows errors.",
+    "fix_hint": "Handle or rethrow the error."
+  },
+  {
+    "rule_id": "code-large-file",
+    "pillar": "code",
+    "default_severity": "info",
+    "description": "File exceeds size heuristic for maintainability.",
+    "fix_hint": "Split into smaller modules."
+  },
+  {
+    "rule_id": "code-redundant-fragment",
+    "pillar": "code",
+    "default_severity": "info",
+    "description": "Redundant React fragment wrapper.",
+    "fix_hint": "Remove unnecessary <>...</>."
+  },
+  {
+    "rule_id": "code-suppression-comment",
+    "pillar": "code",
+    "default_severity": "info",
+    "description": "Lint/TS suppression comment present.",
+    "fix_hint": "Fix the underlying issue instead of suppressing."
+  },
+  {
+    "rule_id": "code-todo-marker",
+    "pillar": "code",
+    "default_severity": "info",
+    "description": "TODO/FIXME marker in source.",
+    "fix_hint": "Resolve or track in issue tracker."
+  }
+]

package/src/mcp/rule-catalog.ts

@@ -0,0 +1,33 @@
+import catalog from "./rule-catalog.json";
+import type { Severity } from "../types/report";
+
+export type RulePillar = "a11y" | "token" | "usage" | "code";
+
+export type RuleCatalogEntry = {
+  rule_id: string;
+  pillar: RulePillar;
+  default_severity: Severity;
+  description: string;
+  fix_hint: string;
+};
+
+const entries = catalog as RuleCatalogEntry[];
+
+const byId = new Map(entries.map((e) => [e.rule_id, e]));
+
+export function ruleCatalog(): RuleCatalogEntry[] {
+  return entries;
+}
+
+export function ruleById(ruleId: string): RuleCatalogEntry | undefined {
+  return byId.get(ruleId);
+}
+
+export function pillarForRule(ruleId: string): RulePillar {
+  const entry = byId.get(ruleId);
+  if (entry) return entry.pillar;
+  if (ruleId.startsWith("a11y-")) return "a11y";
+  if (ruleId.startsWith("token-")) return "token";
+  if (ruleId.startsWith("code-")) return "code";
+  return "usage";
+}

package/src/mcp/schemas.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+
+export const scanInput = z.object({
+  fresh: z.boolean().optional(),
+});
+
+export const catalogInput = z.object({
+  query: z.string().optional(),
+  limit: z.number().int().positive().max(500).optional(),
+});
+
+export const componentInput = z.object({
+  name: z.string().min(1),
+});
+
+export const findingsInput = z.object({
+  component: z.string().optional(),
+  rule_prefix: z.string().optional(),
+  severity: z.enum(["error", "warning", "info"]).optional(),
+  path: z.string().optional(),
+  limit: z.number().int().positive().max(200).optional(),
+});
+
+export const usageExamplesInput = z.object({
+  component: z.string().min(1),
+  limit: z.number().int().positive().max(50).optional(),
+});
+
+export const tokensInput = z.object({
+  category: z
+    .enum(["color", "spacing", "radius", "typography", "other"])
+    .optional(),
+});
+
+export const agentContextInput = z.object({
+  max_components: z.number().int().positive().max(100).optional(),
+  format: z.enum(["markdown", "json"]).optional(),
+});
+
+export const checkPathsInput = z.object({
+  paths: z.array(z.string().min(1)).min(1).max(50),
+  fresh: z.boolean().optional(),
+});
+
+export const diffSinceInput = z.object({
+  save_baseline: z.boolean().optional(),
+  fresh: z.boolean().optional(),
+});
+
+export const suggestFixInput = z.object({
+  rule_id: z.string().min(1),
+  path: z.string().optional(),
+  component: z.string().optional(),
+});

package/src/mcp/server.test.ts

@@ -0,0 +1,44 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { buildMcpConfig } from "./config";
+import { ReportCache } from "./report-cache";
+import { createDslinterMcpServer } from "./server";
+import { ruleCatalog } from "./rule-catalog";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const demoRoot = join(__dirname, "../../../../demo");
+const demoReportPath = join(demoRoot, "public/dslinter-report.json");
+
+describe("MCP server", () => {
+  it("creates server with tools registered", () => {
+    const config = buildMcpConfig({
+      scanPath: demoRoot,
+      projectRoot: demoRoot,
+      reportPath: demoReportPath,
+    });
+    const cache = new ReportCache(config);
+    const server = createDslinterMcpServer(config, cache);
+    expect(server).toBeDefined();
+  });
+
+  it("rule catalog has expected entries", () => {
+    const rules = ruleCatalog();
+    expect(rules.length).toBeGreaterThanOrEqual(20);
+    expect(rules.some((r) => r.rule_id === "deprecated-component")).toBe(true);
+  });
+
+  it("loads demo report through cache", async () => {
+    const config = buildMcpConfig({
+      scanPath: demoRoot,
+      projectRoot: demoRoot,
+      reportPath: demoReportPath,
+      ttlMs: 999_999_999,
+    });
+    const cache = new ReportCache(config);
+    const report = await cache.getReport();
+    expect(report.files.length).toBeGreaterThan(0);
+    expect(readFileSync(demoReportPath, "utf8").length).toBeGreaterThan(100);
+  });
+});