feat(diagram-lint): package for validating diagram.json files

Author: urish

package.json

@@ -44,7 +44,7 @@
     "vitest": "^3.0.5"
   },
   "lint-staged": {
-    "*.{js,ts}": [
+    "*.{js,ts,mjs}": [
       "prettier --write",
       "eslint --fix"
     ]

packages/diagram-lint/.gitignore

@@ -0,0 +1,2 @@
+# Generated files
+src/registry/parts.json

packages/diagram-lint/README.md

@@ -0,0 +1,80 @@
+# @wokwi/diagram-lint
+
+Linter for Wokwi `diagram.json` files. Catches common issues like invalid pins, missing components, and duplicate IDs.
+
+## Installation
+
+```bash
+npm install @wokwi/diagram-lint
+```
+
+## Usage
+
+```typescript
+import { DiagramLinter } from '@wokwi/diagram-lint';
+
+const linter = new DiagramLinter();
+const result = linter.lint(diagram);
+
+if (!result.valid) {
+  for (const issue of result.issues) {
+    console.error(`[${issue.severity}] ${issue.rule}: ${issue.message}`);
+  }
+}
+```
+
+## Rules
+
+| Rule                | Severity | Description                                |
+| ------------------- | -------- | ------------------------------------------ |
+| `duplicate-id`      | error    | Parts with duplicate IDs                   |
+| `invalid-pin`       | error    | Connections using non-existent pins        |
+| `missing-component` | error    | Connections referencing non-existent parts |
+| `unknown-part-type` | error    | Unknown part types                         |
+| `wrong-coord-names` | error    | Using `x`/`y` instead of `left`/`top`      |
+| `invalid-attribute` | warning  | Unknown or invalid attributes              |
+| `misplaced-coords`  | warning  | `top`/`left` inside attrs                  |
+| `redundant-parts`   | warning  | Parts with no connections                  |
+| `unsupported-part`  | info     | Parts not in official documentation        |
+
+## Configuration
+
+```typescript
+const linter = new DiagramLinter({
+  rules: {
+    'redundant-parts': false, // disable rule
+    'invalid-attribute': { severity: 'error' }, // change severity
+  },
+});
+```
+
+## Loading Latest Board Definitions
+
+The linter includes built-in board definitions, but you can load the latest definitions at runtime from the [wokwi-boards](https://github.com/wokwi/wokwi-boards) bundle:
+
+```typescript
+import { DiagramLinter } from '@wokwi/diagram-lint';
+
+const linter = new DiagramLinter();
+
+// Fetch and load the latest board definitions
+const bundle = await fetch('https://wokwi.github.io/wokwi-boards/boards.json').then((r) =>
+  r.json(),
+);
+const count = linter.getRegistry().loadBoardsBundle(bundle);
+console.log(`Loaded ${count} boards`);
+
+// Now lint with the latest board pin definitions
+const result = linter.lint(diagram);
+```
+
+## Adding Parts
+
+Part definitions are in `src/registry/parts/`. To add or update a part:
+
+1. Edit the JSON file in `src/registry/parts/wokwi-<part-name>.json`
+2. Run `npm run build:parts` to regenerate `parts.json`
+
+## License
+
+[The MIT License (MIT)](LICENSE)

packages/diagram-lint/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@wokwi/diagram-lint",
+  "version": "0.1.0",
+  "description": "Linter for Wokwi diagram.json files",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "sync:boards": "node scripts/sync-boards.mjs",
+    "build:parts": "node scripts/build-parts.mjs",
+    "prebuild": "npm run build:parts",
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix",
+    "test": "vitest --run",
+    "test:watch": "vitest --watch"
+  },
+  "keywords": [
+    "wokwi",
+    "diagram",
+    "linter",
+    "validation",
+    "electronics",
+    "circuit"
+  ],
+  "author": "Uri Shaked",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wokwi/wokwi-cli"
+  },
+  "devDependencies": {
+    "rimraf": "^5.0.0",
+    "typescript": "^5.2.2",
+    "vitest": "^3.0.5"
+  }
+}

packages/diagram-lint/scripts/build-parts.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// Combines individual part JSON files into src/registry/parts.json
+// Run: node scripts/build-parts.mjs
+
+import { readdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const partsDir = join(__dirname, '../src/registry/parts');
+const outFile = join(__dirname, '../src/registry/parts.json');
+
+const files = readdirSync(partsDir)
+  .filter((f) => f.endsWith('.json'))
+  .sort();
+const parts = files.map((file) => JSON.parse(readFileSync(join(partsDir, file), 'utf-8')));
+
+writeFileSync(outFile, JSON.stringify(parts, null, 2) + '\n');
+console.log(`Built parts.json (${parts.length} parts)`);

packages/diagram-lint/scripts/sync-boards.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// Syncs board definitions from wokwi-boards bundle.json
+// Run: node scripts/sync-boards.mjs
+
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const partsDir = join(__dirname, '../src/registry/parts');
+const BUNDLE_URL = 'https://wokwi.github.io/wokwi-boards/boards.json';
+
+async function fetchBundle() {
+  const response = await fetch(BUNDLE_URL);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch bundle: ${response.status} ${response.statusText}`);
+  }
+  return response.json();
+}
+
+function extractPins(boardDef) {
+  const pins = Object.keys(boardDef.def.pins || {});
+  // Sort pins: numeric first (sorted numerically), then alphabetic
+  return pins.sort((a, b) => {
+    const aNum = parseFloat(a);
+    const bNum = parseFloat(b);
+    const aIsNum = !isNaN(aNum);
+    const bIsNum = !isNaN(bNum);
+    if (aIsNum && bIsNum) return aNum - bNum;
+    if (aIsNum) return -1;
+    if (bIsNum) return 1;
+    return a.localeCompare(b);
+  });
+}
+
+function loadExistingPart(filePath) {
+  if (!existsSync(filePath)) return null;
+  return JSON.parse(readFileSync(filePath, 'utf-8'));
+}
+
+async function main() {
+  console.log('Fetching wokwi-boards bundle...');
+  const bundle = await fetchBundle();
+  const boardIds = Object.keys(bundle);
+  console.log(`Found ${boardIds.length} boards in bundle`);
+
+  let created = 0;
+  let updated = 0;
+  let unchanged = 0;
+
+  for (const boardId of boardIds) {
+    const boardDef = bundle[boardId];
+    const partType = `board-${boardId}`;
+    const filePath = join(partsDir, `${partType}.json`);
+    const pins = extractPins(boardDef);
+
+    const existing = loadExistingPart(filePath);
+
+    const partDef = {
+      type: partType,
+      pins,
+      documented: existing?.documented ?? false,
+      isBoard: true,
+      category: 'boards',
+    };
+
+    if (existing) {
+      // Check if pins changed
+      const pinsChanged = JSON.stringify(existing.pins) !== JSON.stringify(pins);
+      if (pinsChanged) {
+        writeFileSync(filePath, JSON.stringify(partDef, null, 2) + '\n');
+        console.log(`  Updated: ${partType} (${pins.length} pins)`);
+        updated++;
+      } else {
+        unchanged++;
+      }
+    } else {
+      writeFileSync(filePath, JSON.stringify(partDef, null, 2) + '\n');
+      console.log(`  Created: ${partType} (${pins.length} pins)`);
+      created++;
+    }
+  }
+
+  console.log(`\nSummary: ${created} created, ${updated} updated, ${unchanged} unchanged`);
+}
+
+main().catch((err) => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

packages/diagram-lint/src/index.ts

@@ -0,0 +1,39 @@
+// Main exports
+export { DiagramLinter } from './linter.js';
+
+// Types
+export type {
+  AttributeDefinition,
+  BoardBundle,
+  BoardBundleEntry,
+  Connection,
+  Diagram,
+  LintIssue,
+  LintResult,
+  LintSeverity,
+  LinterOptions,
+  Part,
+  PartDefinition,
+  RuleConfig,
+  SerialMonitorConfig,
+} from './types.js';
+
+// Registry
+export { partDefinitions } from './registry/part-definitions.js';
+export { PartRegistry } from './registry/part-registry.js';
+
+// Rules
+export {
+  allRules,
+  duplicateIdRule,
+  invalidAttributeRule,
+  invalidPinRule,
+  misplacedCoordsRule,
+  missingComponentRule,
+  redundantPartsRule,
+  unknownPartTypeRule,
+  unsupportedPartRule,
+  wrongCoordNamesRule,
+} from './rules/index.js';
+export { createIssue } from './rules/rule.js';
+export type { LintContext, LintRule } from './rules/rule.js';