feat(cli): add lint command

Author: urish

README.md

@@ -82,6 +82,21 @@ You can also set the `WASI_SDK_PATH` environment variable to use a custom WASI-S
 
 For more information about creating custom chips, see the [Custom Chips documentation](https://docs.wokwi.com/chips-api/getting-started).
 
+## Diagram Linting
+
+Validate your `diagram.json` file for errors and warnings:
+
+```bash
+wokwi-cli lint
+```
+
+The linter checks for common issues like unknown part types, invalid pin connections, and missing components. By default, it fetches the latest board definitions from the Wokwi registry.
+
+Options:
+- `--ignore-warnings` - Only report errors
+- `--warnings-as-errors` - Exit with error code if warnings are found (useful for CI)
+- `--offline` - Skip downloading latest board definitions
+
 ## MCP Server
 
 The MCP server is an experimental feature that allows you to use the Wokwi CLI as a MCP server. You can use it to integrate the Wokwi CLI with AI agents.

packages/cli/package.json

@@ -53,6 +53,7 @@
     "@iarna/toml": "2.2.5",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@wokwi/client": "workspace:*",
+    "@wokwi/diagram-lint": "workspace:*",
     "commander": "^12.1.0",
     "chalk": "^5.3.0",
     "chalk-template": "^1.1.0",

packages/cli/src/cli.ts

@@ -1,5 +1,11 @@
 import { Command } from 'commander';
-import { chipCommand, initCommand, mcpCommand, simulateCommand } from './commands/index.js';
+import {
+  chipCommand,
+  initCommand,
+  lintCommand,
+  mcpCommand,
+  simulateCommand,
+} from './commands/index.js';
 import { readVersion } from './readVersion.js';
 import { handleUnknownCommand } from './utils/didYouMean.js';
 
@@ -36,6 +42,7 @@ export function createCLI(): Command {
 
   // Register other commands
   initCommand(program);
+  lintCommand(program);
   chipCommand(program);
   mcpCommand(program);
 

packages/cli/src/commands/index.ts

@@ -1,4 +1,5 @@
 export { chipCommand } from './chip/index.js';
 export { initCommand } from './init.js';
+export { lintCommand } from './lint.js';
 export { mcpCommand } from './mcp.js';
 export { simulateCommand } from './simulate.js';

packages/cli/src/commands/lint.ts

@@ -0,0 +1,98 @@
+import { DiagramLinter } from '@wokwi/diagram-lint';
+import chalkTemplate from 'chalk-template';
+import type { Command } from 'commander';
+import { existsSync, readFileSync } from 'fs';
+import path from 'path';
+import {
+  displayLintResults,
+  fetchRemoteBoards,
+  formatLintSummary,
+  hasLintErrors,
+} from '../lint/index.js';
+
+interface LintOptions {
+  ignoreWarnings?: boolean;
+  warningsAsErrors?: boolean;
+  offline?: boolean;
+}
+
+export function lintCommand(program: Command): void {
+  program
+    .command('lint')
+    .description('Lint a Wokwi diagram file')
+    .argument('[path]', 'Path to diagram.json or project directory', '.')
+    .option('--ignore-warnings', 'Do not report warnings')
+    .option('--warnings-as-errors', 'Treat warnings as errors (exit code 1)')
+    .option('--offline', 'Skip downloading latest board definitions')
+    .action(async (projectPath: string, options: LintOptions) => {
+      await runLint(projectPath, options);
+    });
+}
+
+async function runLint(projectPath: string, options: LintOptions) {
+  const { ignoreWarnings, warningsAsErrors, offline } = options;
+  const shouldFetch = !offline;
+
+  // Resolve diagram path
+  let diagramPath = path.resolve(projectPath);
+  if (existsSync(diagramPath) && !diagramPath.endsWith('.json')) {
+    // If it's a directory, look for diagram.json inside
+    const diagramFile = path.join(diagramPath, 'diagram.json');
+    if (existsSync(diagramFile)) {
+      diagramPath = diagramFile;
+    } else {
+      console.error(chalkTemplate`{red Error:} diagram.json not found in {yellow ${projectPath}}`);
+      process.exit(1);
+    }
+  }
+
+  if (!existsSync(diagramPath)) {
+    console.error(chalkTemplate`{red Error:} File not found: {yellow ${diagramPath}}`);
+    process.exit(1);
+  }
+
+  // Create linter
+  const linter = new DiagramLinter();
+
+  // Try to fetch remote boards (only for lint command)
+  if (shouldFetch) {
+    const remoteBoards = await fetchRemoteBoards();
+    if (remoteBoards) {
+      linter.getRegistry().loadBoardsBundle(remoteBoards);
+    }
+  }
+
+  // Read and lint the diagram
+  let diagramContent: string;
+  try {
+    diagramContent = readFileSync(diagramPath, 'utf-8');
+  } catch {
+    console.error(chalkTemplate`{red Error:} Could not read file: {yellow ${diagramPath}}`);
+    process.exit(1);
+  }
+
+  const result = linter.lintJSON(diagramContent);
+
+  // Filter issues if ignoring warnings
+  const filteredIssues = ignoreWarnings
+    ? result.issues.filter((i) => i.severity === 'error')
+    : result.issues;
+
+  if (filteredIssues.length === 0) {
+    console.log(chalkTemplate`{green \u2713} No issues found`);
+    process.exit(0);
+  }
+
+  // Display results
+  displayLintResults(result, { quiet: ignoreWarnings });
+
+  // Summary
+  console.log('');
+  console.log(formatLintSummary(result));
+
+  // Exit code
+  if (hasLintErrors(result, warningsAsErrors)) {
+    process.exit(1);
+  }
+  process.exit(0);
+}

packages/cli/src/commands/simulate.ts

@@ -4,6 +4,7 @@ import {
   type ChipsLogPayload,
   type SerialMonitorDataPayload,
 } from '@wokwi/client';
+import { DiagramLinter } from '@wokwi/diagram-lint';
 import chalkTemplate from 'chalk-template';
 import type { Command } from 'commander';
 import { createWriteStream, existsSync, readFileSync, writeFileSync } from 'fs';
@@ -15,6 +16,7 @@ import { TestScenario } from '../TestScenario.js';
 import { parseConfig } from '../config.js';
 import { DEFAULT_SERVER } from '../constants.js';
 import { idfProjectConfig } from '../esp/idfProjectConfig.js';
+import { displayLintResults } from '../lint/index.js';
 import { loadChips } from '../loadChips.js';
 import { readVersion } from '../readVersion.js';
 import { DelayCommand } from '../scenario/DelayCommand.js';
@@ -195,6 +197,17 @@ async function runSimulation(projectPath: string, options: SimulateOptions, comm
 
   const diagram = readFileSync(diagramFilePath, 'utf8');
 
+  // Lint the diagram before simulation
+  const linter = new DiagramLinter();
+  const lintResult = linter.lintJSON(diagram);
+
+  if (lintResult.stats.errors > 0 || lintResult.stats.warnings > 0) {
+    if (!quiet) {
+      console.error(chalkTemplate`{cyan Diagram issues} in {yellow ${diagramFilePath}}:`);
+    }
+    displayLintResults(lintResult, { quiet });
+  }
+
   const chips = loadChips(config?.chip ?? [], rootDir);
 
   const resolvedScenarioFile = scenarioFile ? path.resolve(rootDir, scenarioFile) : null;

packages/cli/src/lint/index.ts

@@ -0,0 +1,117 @@
+/**
+ * Shared lint utilities for CLI commands
+ */
+
+import {
+  REMOTE_BOARDS_URL,
+  type BoardBundle,
+  type LintIssue,
+  type LintResult,
+} from '@wokwi/diagram-lint';
+import chalkTemplate from 'chalk-template';
+
+export interface LintDisplayOptions {
+  /** Only show errors, hide warnings and info */
+  quiet?: boolean;
+}
+
+/**
+ * Format a single lint issue for display
+ */
+export function formatLintIssue(issue: LintIssue): string {
+  const icon =
+    issue.severity === 'error' ? '\u2717' : issue.severity === 'warning' ? '\u26A0' : '\u2139';
+  const color =
+    issue.severity === 'error' ? 'red' : issue.severity === 'warning' ? 'yellow' : 'gray';
+  const location = issue.partId ? ` (${issue.partId})` : '';
+  return chalkTemplate`{${color} ${icon} [${issue.rule}]} ${issue.message}${location}`;
+}
+
+/**
+ * Display lint results to console
+ */
+export function displayLintResults(result: LintResult, options: LintDisplayOptions = {}): void {
+  const { quiet = false } = options;
+
+  // If quiet and no errors, don't show anything
+  if (quiet && result.stats.errors === 0) {
+    return;
+  }
+
+  for (const issue of result.issues) {
+    // In quiet mode, only show errors
+    if (quiet && issue.severity !== 'error') {
+      continue;
+    }
+    console.error(formatLintIssue(issue));
+  }
+}
+
+/**
+ * Check if lint result has blocking errors
+ *
+ * @param result - The lint result
+ * @param warningsAsErrors - If true, treat warnings as errors
+ * @returns true if there are blocking errors (or warnings if warningsAsErrors is true)
+ */
+export function hasLintErrors(result: LintResult, warningsAsErrors?: boolean): boolean {
+  if (result.stats.errors > 0) {
+    return true;
+  }
+  if (warningsAsErrors && result.stats.warnings > 0) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Format lint summary
+ */
+export function formatLintSummary(result: LintResult): string {
+  const parts: string[] = [];
+
+  if (result.stats.errors > 0) {
+    parts.push(chalkTemplate`{red ${result.stats.errors} error(s)}`);
+  }
+  if (result.stats.warnings > 0) {
+    parts.push(chalkTemplate`{yellow ${result.stats.warnings} warning(s)}`);
+  }
+  if (result.stats.infos > 0) {
+    parts.push(chalkTemplate`{gray ${result.stats.infos} info}`);
+  }
+
+  if (parts.length === 0) {
+    return chalkTemplate`{green \u2713} No issues found`;
+  }
+
+  return `Found ${parts.join(', ')}`;
+}
+
+export interface FetchBoardsOptions {
+  /** Timeout in milliseconds (default: 5000) */
+  timeout?: number;
+}
+
+/**
+ * Fetch board definitions from the remote registry
+ *
+ * @returns Board bundle, or null if fetch fails
+ */
+export async function fetchRemoteBoards(options?: FetchBoardsOptions): Promise<BoardBundle | null> {
+  const timeout = options?.timeout ?? 5000;
+
+  try {
+    const response = await fetch(REMOTE_BOARDS_URL, {
+      signal: AbortSignal.timeout(timeout),
+    });
+
+    if (!response.ok) {
+      return null;
+    }
+
+    return (await response.json()) as BoardBundle;
+  } catch {
+    // Network error, timeout, or JSON parse error
+    return null;
+  }
+}

packages/cli/src/mcp/MCPServer.ts

@@ -6,6 +6,9 @@ import {
   ListToolsRequestSchema,
   ReadResourceRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
+import { DiagramLinter, type LintResult } from '@wokwi/diagram-lint';
+import { existsSync, readFileSync } from 'fs';
+import path from 'path';
 import { readVersion } from '../readVersion.js';
 import { SimulationManager } from './SimulationManager.js';
 import { WokwiMCPResources } from './WokwiMCPResources.js';
@@ -22,6 +25,7 @@ export class WokwiMCPServer {
   private readonly simulationManager: SimulationManager;
   private readonly tools: WokwiMCPTools;
   private readonly resources: WokwiMCPResources;
+  private lintWarnings: LintResult | null = null;
 
   constructor(private readonly options: MCPServerOptions) {
     const { version } = readVersion();
@@ -40,7 +44,9 @@ export class WokwiMCPServer {
     );
 
     this.simulationManager = new SimulationManager(options.rootDir, options.token, options.quiet);
-    this.tools = new WokwiMCPTools(this.simulationManager);
+    this.tools = new WokwiMCPTools(this.simulationManager, {
+      getLintWarnings: () => this.getLintWarnings(),
+    });
     this.resources = new WokwiMCPResources(options.rootDir);
 
     this.setupHandlers();
@@ -65,6 +71,27 @@ export class WokwiMCPServer {
   }
 
   async start() {
+    // Validate diagram before starting
+    const diagramPath = path.join(this.options.rootDir, 'diagram.json');
+    if (existsSync(diagramPath)) {
+      const linter = new DiagramLinter();
+      const diagram = readFileSync(diagramPath, 'utf8');
+      const result = linter.lintJSON(diagram);
+
+      if (result.stats.errors > 0) {
+        const errorMessages = result.issues
+          .filter((i) => i.severity === 'error')
+          .map((i) => `[${i.rule}] ${i.message}`)
+          .join('\n');
+        throw new Error(`Diagram lint errors:\n${errorMessages}`);
+      }
+
+      // Store warnings to include in start_simulation response
+      if (result.stats.warnings > 0) {
+        this.lintWarnings = result;
+      }
+    }
+
     const transport = new StdioServerTransport();
     await this.server.connect(transport);
 
@@ -73,6 +100,13 @@ export class WokwiMCPServer {
     }
   }
 
+  /**
+   * Get lint warnings from startup validation
+   */
+  getLintWarnings(): LintResult | null {
+    return this.lintWarnings;
+  }
+
   async stop() {
     await this.simulationManager.cleanup();
     await this.server.close();