dslinter 0.1.13 → 0.2.0

package/src/mcp/server.ts

@@ -0,0 +1,343 @@
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { buildAgentContext } from "./agent-context";
+import {
+  catalogSummary,
+  componentSpec,
+  findingsQuery,
+  governanceSummary,
+  policyFromReport,
+  tokenSummary,
+  usageExamples,
+} from "./agent-query";
+import type { McpConfig } from "./config";
+import { ReportCache, loadBaseline, saveBaseline } from "./report-cache";
+import {
+  agentContextInput,
+  catalogInput,
+  checkPathsInput,
+  componentInput,
+  diffSinceInput,
+  findingsInput,
+  scanInput,
+  suggestFixInput,
+  tokensInput,
+  usageExamplesInput,
+} from "./schemas";
+import {
+  computeDrift,
+  findingsForPaths,
+  suggestFix,
+} from "./verify-loop";
+
+function jsonResult(data: unknown, isError = false): CallToolResult {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    ...(isError ? { isError: true } : {}),
+  };
+}
+
+export function createDslinterMcpServer(
+  config: McpConfig,
+  cache: ReportCache,
+): McpServer {
+  const server = new McpServer({
+    name: "dslinter",
+    version: "0.1.0",
+  });
+
+  server.registerTool(
+    "dslinter_scan",
+    {
+      description:
+        "Refresh or load the DSLinter workspace report. Returns governance scores and finding counts.",
+      inputSchema: scanInput,
+    },
+    async (args) => {
+      const report = await cache.getReport({ fresh: args.fresh ?? false });
+      const gov = governanceSummary(report);
+      return jsonResult({
+        schema_version: report.schema_version,
+        generated_at: report.generated_at,
+        source: "scan",
+        scores: gov.scores,
+        finding_counts: gov.finding_counts,
+        total_findings: gov.total_findings,
+        component_count: catalogSummary(report, { limit: 10_000 }).length,
+      });
+    },
+  );
+
+  server.registerTool(
+    "dslinter_get_catalog",
+    {
+      description:
+        "List design-system components sorted by usage frequency, with import paths and flags.",
+      inputSchema: catalogInput,
+    },
+    async (args) => {
+      const report = await cache.getReport();
+      return jsonResult(catalogSummary(report, args));
+    },
+  );
+
+  server.registerTool(
+    "dslinter_get_component",
+    {
+      description:
+        "Full component spec: props, CVA variants, usage, findings, and example JSX from repo patterns.",
+      inputSchema: componentInput,
+    },
+    async (args) => {
+      const report = await cache.getReport();
+      const spec = componentSpec(report, args.name);
+      if (!spec) {
+        return jsonResult({ error: `Component not found: ${args.name}` }, true);
+      }
+      return jsonResult(spec);
+    },
+  );
+
+  server.registerTool(
+    "dslinter_get_findings",
+    {
+      description: "Filtered governance findings by component, rule prefix, severity, or path.",
+      inputSchema: findingsInput,
+    },
+    async (args) => {
+      const report = await cache.getReport();
+      return jsonResult(findingsQuery(report, args));
+    },
+  );
+
+  server.registerTool(
+    "dslinter_get_usage_examples",
+    {
+      description:
+        "Real call sites and prop value frequencies for a component from repo usage data.",
+      inputSchema: usageExamplesInput,
+    },
+    async (args) => {
+      const report = await cache.getReport();
+      const examples = usageExamples(report, args.component, args.limit);
+      if (!examples) {
+        return jsonResult(
+          { error: `No usage data for component: ${args.component}` },
+          true,
+        );
+      }
+      return jsonResult(examples);
+    },
+  );
+
+  server.registerTool(
+    "dslinter_get_tokens",
+    {
+      description: "CSS design tokens: definitions, usage counts, and unused tokens.",
+      inputSchema: tokensInput,
+    },
+    async (args) => {
+      const report = await cache.getReport();
+      return jsonResult(tokenSummary(report, args.category));
+    },
+  );
+
+  server.registerTool(
+    "dslinter_get_agent_context",
+    {
+      description:
+        "Compact design-system context pack for LLM system prompts (scores, top components, policy, dos/donts).",
+      inputSchema: agentContextInput,
+    },
+    async (args) => {
+      const report = await cache.getReport();
+      const context = buildAgentContext(report, args);
+      if (args.format === "json") {
+        return jsonResult(context);
+      }
+      return {
+        content: [{ type: "text", text: String(context) }],
+      };
+    },
+  );
+
+  server.registerTool(
+    "dslinter_get_policy",
+    {
+      description:
+        "Effective governance policy from .dslinter.json snapshot and rule catalog.",
+    },
+    async () => {
+      const report = await cache.getReport();
+      return jsonResult(policyFromReport(report));
+    },
+  );
+
+  server.registerTool(
+    "dslinter_check_paths",
+    {
+      description:
+        "Findings for specific file paths after agent edits (post-write verification).",
+      inputSchema: checkPathsInput,
+    },
+    async (args) => {
+      const report = await cache.getReport({ fresh: args.fresh ?? true });
+      return jsonResult(findingsForPaths(report, args.paths));
+    },
+  );
+
+  server.registerTool(
+    "dslinter_diff_since",
+    {
+      description:
+        "Compare current governance scores/findings to saved MCP baseline (.dslinter/mcp-baseline.json).",
+      inputSchema: diffSinceInput,
+    },
+    async (args) => {
+      const report = await cache.getReport({ fresh: args.fresh ?? false });
+      const baseline = await loadBaseline(config.projectRoot);
+      const drift = computeDrift(report, baseline);
+      if (args.save_baseline) {
+        const hash = cache.reportHash();
+        if (hash) await saveBaseline(config.projectRoot, report, hash);
+      }
+      return jsonResult(drift);
+    },
+  );
+
+  server.registerTool(
+    "dslinter_suggest_fix",
+    {
+      description:
+        "Heuristic fix suggestion for a rule id (deprecated components, tokens, a11y).",
+      inputSchema: suggestFixInput,
+    },
+    async (args) => {
+      const report = await cache.getReport();
+      const fix = suggestFix(report, args);
+      if (!fix) {
+        return jsonResult({ error: "No suggestion available" }, true);
+      }
+      return jsonResult(fix);
+    },
+  );
+
+  server.registerResource(
+    "agent-context",
+    "dslinter://context",
+    {
+      description: "Compact design-system agent context (markdown)",
+      mimeType: "text/markdown",
+    },
+    async () => ({
+      contents: [
+        {
+          uri: "dslinter://context",
+          mimeType: "text/markdown",
+          text: String(
+            buildAgentContext(await cache.getReport(), { format: "markdown" }),
+          ),
+        },
+      ],
+    }),
+  );
+
+  server.registerResource(
+    "catalog",
+    "dslinter://catalog",
+    {
+      description: "Component catalog sorted by usage",
+      mimeType: "application/json",
+    },
+    async () => ({
+      contents: [
+        {
+          uri: "dslinter://catalog",
+          mimeType: "application/json",
+          text: JSON.stringify(
+            catalogSummary(await cache.getReport(), { limit: 200 }),
+            null,
+            2,
+          ),
+        },
+      ],
+    }),
+  );
+
+  server.registerResource(
+    "component",
+    {
+      uriTemplate: "dslinter://component/{name}",
+      name: "component",
+      description: "Single component spec by name",
+      mimeType: "application/json",
+    },
+    async (uri, { name }) => {
+      const report = await cache.getReport();
+      const spec = componentSpec(report, name);
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(
+              spec ?? { error: `Component not found: ${name}` },
+              null,
+              2,
+            ),
+          },
+        ],
+      };
+    },
+  );
+
+  server.registerPrompt(
+    "design-system-ui-task",
+    {
+      description:
+        "System prompt template for building UI with the repo design system.",
+      argsSchema: {
+        task: z.string().describe("What UI to build"),
+      },
+    },
+    async ({ task }) => {
+      const context = buildAgentContext(await cache.getReport(), {
+        format: "markdown",
+      });
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `You are building UI in this repository. Use only catalog components and match repo usage patterns.\n\n${context}\n\nTask: ${task}`,
+            },
+          },
+        ],
+      };
+    },
+  );
+
+  return server;
+}
+
+export async function runMcpServer(config: McpConfig): Promise<void> {
+  const cache = new ReportCache(config);
+  cache.startDevWatch();
+  const server = createDslinterMcpServer(config, cache);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+export async function runMcpSelfTest(config: McpConfig): Promise<void> {
+  const cache = new ReportCache(config);
+  const report = await cache.getReport({ fresh: false });
+  const catalog = catalogSummary(report, { limit: 5 });
+  if (catalog.length === 0 && (report.files?.length ?? 0) === 0) {
+    throw new Error("Self-test: empty report");
+  }
+  governanceSummary(report);
+  buildAgentContext(report);
+}

package/src/mcp/start.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/**
+ * MCP stdio server entry (run via `node --experimental-strip-types` or vitest).
+ */
+import { buildMcpConfig } from "./config";
+import { runMcpSelfTest, runMcpServer } from "./server";
+
+export type McpStartOptions = {
+  cwd?: string;
+  scanPath: string;
+  projectRoot: string;
+  reportPath?: string;
+};
+
+export async function startMcp(opts: McpStartOptions): Promise<void> {
+  const config = buildMcpConfig({
+    cwd: opts.cwd,
+    scanPath: opts.scanPath,
+    projectRoot: opts.projectRoot,
+    reportPath: opts.reportPath,
+  });
+
+  if (process.argv.includes("--self-test")) {
+    await runMcpSelfTest(config);
+    return;
+  }
+
+  await runMcpServer(config);
+}

package/src/mcp/verify-loop.test.ts

@@ -0,0 +1,49 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { computeDrift, suggestFix } from "./verify-loop";
+import { normalizeReportPaths } from "./normalize-paths";
+import type { WorkspaceReport } from "../types/report";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const demoReportPath = join(__dirname, "../../../../demo/public/dslinter-report.json");
+
+function loadDemoReport(): WorkspaceReport {
+  const raw = readFileSync(demoReportPath, "utf8");
+  return normalizeReportPaths(JSON.parse(raw) as WorkspaceReport);
+}
+
+describe("verify-loop", () => {
+  it("computes drift from baseline", () => {
+    const report = loadDemoReport();
+    const baseline = {
+      saved_at: "2020-01-01T00:00:00Z",
+      scores: {
+        design_system_health: 100,
+        ux_consistency: 100,
+        accessibility: 100,
+        maintainability: 100,
+      },
+      finding_count: 0,
+    };
+    const drift = computeDrift(report, baseline);
+    expect(drift.finding_delta).toBeGreaterThan(0);
+    expect(drift.score_deltas.design_system_health).toBeLessThan(0);
+  });
+
+  it("suggests fix for deprecated component", () => {
+    const report = loadDemoReport();
+    const fix = suggestFix(report, {
+      rule_id: "deprecated-component",
+      component: "LegacyButton",
+    });
+    expect(fix?.suggestion).toMatch(/LegacyButton|Replace/);
+  });
+
+  it("suggests fix for hardcoded color", () => {
+    const report = loadDemoReport();
+    const fix = suggestFix(report, { rule_id: "token-hardcoded-color" });
+    expect(fix?.fix_hint).toBeTruthy();
+  });
+});

package/src/mcp/verify-loop.ts

@@ -0,0 +1,149 @@
+import { catalogSummary, componentSpec, findingsForPaths } from "./agent-query";
+import { ruleById } from "./rule-catalog";
+import type { LintFinding, WorkspaceReport } from "../types/report";
+
+export type FixSuggestion = {
+  rule_id: string;
+  fix_hint: string;
+  suggestion: string;
+  replacement_component?: string;
+  replacement_import?: string;
+  token?: string;
+};
+
+export function suggestFix(
+  report: WorkspaceReport,
+  opts: { rule_id: string; path?: string; component?: string },
+): FixSuggestion | null {
+  const entry = ruleById(opts.rule_id);
+  const fix_hint = entry?.fix_hint ?? "Review the finding and align with design system conventions.";
+
+  if (opts.rule_id === "deprecated-component" && opts.component) {
+    const snap = report.config_snapshot?.deprecated_components ?? [];
+    const catalog = catalogSummary(report, { limit: 20 });
+    const replacement = catalog.find(
+      (c) =>
+        !c.deprecated &&
+        !snap.includes(c.name) &&
+        c.name.toLowerCase().includes(
+          opts.component!.replace(/^Legacy|Deprecated/i, "").toLowerCase(),
+        ),
+    ) ?? catalog.find((c) => !c.deprecated && c.reference_count > 0);
+
+    return {
+      rule_id: opts.rule_id,
+      fix_hint,
+      suggestion: replacement
+        ? `Replace \`${opts.component}\` with \`${replacement.name}\` from ${replacement.import_path ?? "the catalog"}.`
+        : `Remove usage of deprecated \`${opts.component}\`; pick a catalog component with similar usage.`,
+      replacement_component: replacement?.name,
+      replacement_import: replacement?.import_path ?? undefined,
+    };
+  }
+
+  if (opts.rule_id === "token-hardcoded-color") {
+    const colorToken = report.css_tokens?.definitions.find(
+      (d) => d.category === "color",
+    );
+    return {
+      rule_id: opts.rule_id,
+      fix_hint,
+      suggestion: colorToken
+        ? `Use theme token \`${colorToken.name}\` or Tailwind utility bound to it instead of a hardcoded color.`
+        : "Replace hardcoded color with a CSS variable or Tailwind theme utility.",
+      token: colorToken?.name,
+    };
+  }
+
+  if (opts.rule_id === "a11y-img-alt" && opts.path) {
+    const decorative =
+      /avatar|icon|logo|decorative|spacer/i.test(opts.path) ||
+      /AvatarImage|Icon|Logo/i.test(opts.path);
+    return {
+      rule_id: opts.rule_id,
+      fix_hint,
+      suggestion: decorative
+        ? 'Add alt="" for decorative images.'
+        : "Add a descriptive alt attribute summarizing the image content.",
+    };
+  }
+
+  if (opts.rule_id === "duplicate-component" && opts.component) {
+    const spec = componentSpec(report, opts.component);
+    return {
+      rule_id: opts.rule_id,
+      fix_hint,
+      suggestion: spec?.duplicates
+        ? `Consolidate definitions at: ${spec.duplicates.join(", ")}`
+        : "Keep one canonical definition and update imports.",
+    };
+  }
+
+  return {
+    rule_id: opts.rule_id,
+    fix_hint,
+    suggestion: fix_hint,
+  };
+}
+
+export type DriftSummary = {
+  baseline: { saved_at: string; scores: WorkspaceReport["scores"]; finding_count: number } | null;
+  current: { scores: WorkspaceReport["scores"]; finding_count: number };
+  score_deltas: Record<keyof WorkspaceReport["scores"], number>;
+  finding_delta: number;
+};
+
+export function computeDrift(
+  report: WorkspaceReport,
+  baseline: {
+    saved_at: string;
+    scores: WorkspaceReport["scores"];
+    finding_count: number;
+  } | null,
+): DriftSummary {
+  const currentCount = report.findings?.length ?? 0;
+  const score_deltas = {
+    design_system_health:
+      report.scores.design_system_health -
+      (baseline?.scores.design_system_health ?? report.scores.design_system_health),
+    ux_consistency:
+      report.scores.ux_consistency -
+      (baseline?.scores.ux_consistency ?? report.scores.ux_consistency),
+    accessibility:
+      report.scores.accessibility -
+      (baseline?.scores.accessibility ?? report.scores.accessibility),
+    maintainability:
+      report.scores.maintainability -
+      (baseline?.scores.maintainability ?? report.scores.maintainability),
+  };
+
+  return {
+    baseline: baseline
+      ? {
+          saved_at: baseline.saved_at,
+          scores: baseline.scores,
+          finding_count: baseline.finding_count,
+        }
+      : null,
+    current: { scores: report.scores, finding_count: currentCount },
+    score_deltas,
+    finding_delta: currentCount - (baseline?.finding_count ?? currentCount),
+  };
+}
+
+export function findingsWithSuggestions(
+  findings: LintFinding[],
+  report: WorkspaceReport,
+): Array<LintFinding & { suggestion?: FixSuggestion }> {
+  return findings.map((f) => {
+    const componentMatch = f.message.match(/`([A-Z][A-Za-z0-9_]*)`/);
+    const suggestion = suggestFix(report, {
+      rule_id: f.rule_id,
+      path: f.path,
+      component: componentMatch?.[1],
+    });
+    return suggestion ? { ...f, suggestion } : f;
+  });
+}
+
+export { findingsForPaths };