@cisco_open/linting-orchestrator 1.0.0-rc.4

package/build/worker.js

@@ -0,0 +1,427 @@
+// Copyright 2026 Cisco Systems, Inc. and its affiliates
+//
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Worker Thread Implementation
+ *
+ * Each worker is dedicated to a specific ruleset and maintains:
+ * - Pre-loaded Spectral ruleset for fast execution
+ * - Document cache (LRU, 1 document) for repeated linting
+ * - Health monitoring and status reporting
+ *
+ * Architecture:
+ * - Zero-copy: Receives document file paths, not content
+ * - Stateful: Pre-loaded ruleset stays in memory
+ * - Cached: Last document cached for reuse
+ *
+ * @module worker
+ */
+import { parentPort, workerData } from 'worker_threads';
+import pkg from '@stoplight/spectral-core';
+const { Spectral, Ruleset } = pkg;
+// @ts-ignore - ESM export resolution issue with TypeScript
+import { bundleAndLoadRuleset } from '@stoplight/spectral-ruleset-bundler/with-loader';
+import fs from 'fs/promises';
+import { pathToFileURL } from 'url';
+// ============================================
+// Worker State
+// ============================================
+let spectral = null; // Spectral instance (any to avoid CommonJS/ESM type issues)
+let initData;
+let workerStatus = 'initializing';
+// Document cache (LRU, 1 document)
+let cachedDocument = null;
+let cachedDocumentId = null;
+let cachedAt = null;
+let cacheSize = 0;
+// Performance tracking
+let taskCount = 0;
+let totalExecutionTime = 0;
+let lastHeartbeat = new Date();
+// ============================================
+// Initialization
+// ============================================
+/**
+ * Initialize worker with pre-loaded Spectral ruleset
+ */
+async function initialize() {
+    try {
+        initData = workerData;
+        if (!initData || !initData.workerId || !initData.rulesetPath) {
+            throw new Error('Invalid worker initialization data');
+        }
+        // Validate ruleset file exists
+        try {
+            await fs.access(initData.rulesetPath);
+        }
+        catch (error) {
+            throw new Error(`Ruleset file not found: ${initData.rulesetPath}`);
+        }
+        // Load Spectral ruleset using whichever mechanism the catalogue
+        // entry's `loader` field selected. Defaults to `bundler` if absent.
+        // See ruleset-loader.ts for the same two-branch logic and rationale.
+        let ruleset;
+        const loaderKind = initData.rulesetLoader ?? 'bundler';
+        if (loaderKind === 'native') {
+            if (!/\.(js|cjs|mjs)$/i.test(initData.rulesetPath)) {
+                throw new Error(`loader: native only supports .js / .cjs / .mjs entrypoints, got: ${initData.rulesetPath}`);
+            }
+            const mod = await import(pathToFileURL(initData.rulesetPath).href);
+            const def = extractRulesetDef(mod);
+            if (!def || (!def.rules && !def.extends && !def.overrides)) {
+                throw new Error(`module at ${initData.rulesetPath} did not export a Spectral ruleset definition`);
+            }
+            ruleset = new Ruleset(def, { source: initData.rulesetPath });
+        }
+        else {
+            ruleset = await bundleAndLoadRuleset(initData.rulesetPath, {
+                fs: { promises: fs },
+                fetch: fetch
+            });
+        }
+        // Load custom resolver if configured
+        let resolverOpts = {};
+        if (initData.resolverPath) {
+            try {
+                const resolverModule = await import(pathToFileURL(initData.resolverPath).href);
+                const resolver = resolverModule.default ?? resolverModule;
+                resolverOpts = { resolver };
+            }
+            catch (err) {
+                throw new Error(`Failed to load resolver from ${initData.resolverPath}: ${err.message}`);
+            }
+        }
+        // Initialize Spectral with pre-loaded ruleset (and optional custom resolver)
+        spectral = new Spectral(resolverOpts);
+        spectral.setRuleset(ruleset);
+        workerStatus = 'ready';
+        lastHeartbeat = new Date();
+        // Notify main thread that worker is ready
+        sendMessage({
+            type: 'ready',
+            payload: {
+                workerId: initData.workerId,
+                rulesetName: initData.rulesetName,
+                rulesetVersion: initData.rulesetVersion,
+                timestamp: new Date().toISOString()
+            }
+        });
+    }
+    catch (error) {
+        workerStatus = 'error';
+        sendMessage({
+            type: 'error',
+            payload: {
+                workerId: initData?.workerId || 'unknown',
+                phase: 'initialization',
+                error: error instanceof Error ? error.message : String(error),
+                stack: error instanceof Error ? error.stack : undefined
+            }
+        });
+        throw error;
+    }
+}
+// ============================================
+// Task Execution
+// ============================================
+/**
+ * Execute Spectral rules on a document
+ */
+async function executeTask(msg) {
+    const { taskId, documentId, documentPath, timeout, ruleOverrides } = msg.payload;
+    const startTime = Date.now();
+    try {
+        if (!spectral) {
+            throw new Error('Spectral not initialized');
+        }
+        workerStatus = 'busy';
+        sendStatus();
+        // Check if document is in cache BEFORE loading
+        const wasCacheHit = cachedDocumentId === documentId;
+        // Load document (from cache or filesystem)
+        const document = await loadDocument(documentId, documentPath);
+        // Execute Spectral rules with timeout
+        const executionTimeout = timeout || initData.config.taskTimeout;
+        const results = await executeWithTimeout(() => spectral.run(document), executionTimeout); // Spectral returns unknown in some contexts
+        // Update performance metrics
+        const executionTime = Date.now() - startTime;
+        taskCount++;
+        totalExecutionTime += executionTime;
+        lastHeartbeat = new Date();
+        // Send results back to main thread
+        workerStatus = 'ready';
+        let formattedResults = (results || []).map(formatDiagnostic);
+        // Apply rule overrides (post-filter): exclude 'off' rules, remap severities
+        if (ruleOverrides && Object.keys(ruleOverrides).length > 0) {
+            formattedResults = applyRuleOverrides(formattedResults, ruleOverrides);
+        }
+        sendMessage({
+            type: 'result',
+            payload: {
+                taskId,
+                success: true,
+                results: formattedResults,
+                executionTime,
+                cacheHit: wasCacheHit,
+                timestamp: new Date().toISOString()
+            }
+        });
+        sendStatus();
+    }
+    catch (error) {
+        const executionTime = Date.now() - startTime;
+        workerStatus = 'ready';
+        sendMessage({
+            type: 'result',
+            payload: {
+                taskId,
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+                executionTime,
+                timestamp: new Date().toISOString()
+            }
+        });
+        sendStatus();
+    }
+}
+/**
+ * Load document from cache or filesystem (zero-copy architecture)
+ */
+async function loadDocument(documentId, documentPath) {
+    // Check cache first
+    if (initData.config.documentCache.enabled && cachedDocumentId === documentId) {
+        // Check if cache is still valid
+        if (cachedAt && initData.config.documentCache.evictAfterMinutes > 0) {
+            const cacheAge = Date.now() - cachedAt.getTime();
+            const maxAge = initData.config.documentCache.evictAfterMinutes * 60 * 1000;
+            if (cacheAge > maxAge) {
+                // Cache expired, evict
+                evictCache();
+            }
+            else {
+                // Cache hit! Return cached document
+                return cachedDocument;
+            }
+        }
+        else {
+            // Cache hit! Return cached document
+            return cachedDocument;
+        }
+    }
+    // Cache miss - load from filesystem
+    try {
+        const content = await fs.readFile(documentPath, 'utf-8');
+        const document = JSON.parse(content);
+        // Cache document if enabled
+        if (initData.config.documentCache.enabled) {
+            cacheDocument(documentId, document);
+        }
+        return document;
+    }
+    catch (error) {
+        throw new Error(`Failed to load document from ${documentPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Cache document in memory (LRU with 1 slot)
+ */
+function cacheDocument(documentId, document) {
+    // Evict old cache if exists
+    if (cachedDocumentId !== null) {
+        evictCache();
+    }
+    // Calculate document size (rough estimate)
+    const docSize = JSON.stringify(document).length;
+    // Check size limit
+    if (docSize > initData.config.documentCache.maxCacheSizePerWorker) {
+        // Document too large to cache
+        return;
+    }
+    // Cache document
+    cachedDocument = document;
+    cachedDocumentId = documentId;
+    cachedAt = new Date();
+    cacheSize = docSize;
+}
+/**
+ * Evict cached document
+ */
+function evictCache() {
+    cachedDocument = null;
+    cachedDocumentId = null;
+    cachedAt = null;
+    cacheSize = 0;
+}
+/**
+ * Execute function with timeout
+ */
+async function executeWithTimeout(fn, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            const error = new Error(`Execution timeout after ${timeoutMs}ms`);
+            error.code = 'TIMEOUT'; // Mark as timeout error
+            reject(error);
+        }, timeoutMs);
+        fn()
+            .then(result => {
+            if (!timedOut) {
+                clearTimeout(timer);
+                resolve(result);
+            }
+        })
+            .catch(error => {
+            if (!timedOut) {
+                clearTimeout(timer);
+                reject(error);
+            }
+        });
+    });
+}
+/**
+ * Format Spectral diagnostic to our result format
+ */
+function formatDiagnostic(diagnostic) {
+    return {
+        code: diagnostic.code,
+        message: diagnostic.message,
+        severity: diagnostic.severity,
+        path: diagnostic.path,
+        range: diagnostic.range,
+        source: diagnostic.source
+    };
+}
+/**
+ * Apply rule overrides to formatted diagnostics (post-filter).
+ * - 'off': remove the diagnostic entirely
+ * - severity level: remap the diagnostic's severity
+ *
+ * Severity mapping: error=0, warn=1, info=2, hint=3
+ */
+const SEVERITY_MAP = { error: 0, warn: 1, info: 2, hint: 3 };
+function applyRuleOverrides(diagnostics, overrides) {
+    return diagnostics
+        .filter(d => overrides[d.code] !== 'off')
+        .map(d => {
+        const override = overrides[d.code];
+        if (override && override !== 'off' && SEVERITY_MAP[override] !== undefined) {
+            return { ...d, severity: SEVERITY_MAP[override] };
+        }
+        return d;
+    });
+}
+// ============================================
+// Message Handling
+// ============================================
+/**
+ * Send message to main thread
+ */
+function sendMessage(message) {
+    if (parentPort) {
+        parentPort.postMessage(message);
+    }
+}
+/**
+ * Send status update to main thread
+ */
+function sendStatus() {
+    sendMessage({
+        type: 'status',
+        payload: {
+            workerId: initData.workerId,
+            status: workerStatus,
+            taskCount,
+            averageExecutionTime: taskCount > 0 ? totalExecutionTime / taskCount : 0,
+            cachedDocumentId,
+            cachedAt: cachedAt?.toISOString(),
+            cacheSize,
+            lastHeartbeat: lastHeartbeat.toISOString()
+        }
+    });
+}
+/**
+ * Handle incoming messages from main thread
+ */
+function handleMessage(msg) {
+    switch (msg.type) {
+        case 'execute':
+            executeTask(msg).catch(error => {
+                sendMessage({
+                    type: 'error',
+                    payload: {
+                        workerId: initData.workerId,
+                        phase: 'execution',
+                        error: error instanceof Error ? error.message : String(error)
+                    }
+                });
+            });
+            break;
+        case 'evict-cache':
+            evictCache();
+            sendStatus();
+            break;
+        case 'shutdown':
+            workerStatus = 'terminated';
+            sendStatus();
+            process.exit(0);
+            break;
+        case 'ping':
+            lastHeartbeat = new Date();
+            sendMessage({
+                type: 'pong',
+                payload: {
+                    workerId: initData.workerId,
+                    timestamp: lastHeartbeat.toISOString()
+                }
+            });
+            break;
+        default:
+            sendMessage({
+                type: 'error',
+                payload: {
+                    workerId: initData.workerId,
+                    phase: 'message-handling',
+                    error: `Unknown message type: ${msg.type}`
+                }
+            });
+    }
+}
+// ============================================
+// Worker Entry Point
+// ============================================
+if (parentPort) {
+    // Set up message listener
+    parentPort.on('message', handleMessage);
+    // Start initialization
+    initialize().catch(error => {
+        console.error('[Worker] Initialization failed:', error);
+        process.exit(1);
+    });
+}
+else {
+    console.error('[Worker] No parent port available - must be run as worker thread');
+    process.exit(1);
+}
+/**
+ * Extract a Spectral ruleset definition from a Node module namespace.
+ * Mirrors `extractRulesetDef` in ruleset-loader.ts. Handles ESM default,
+ * CJS default, and Babel CJS double-wrap shapes.
+ */
+function extractRulesetDef(mod) {
+    if (!mod || typeof mod !== 'object')
+        return null;
+    const ns = mod;
+    let candidate = (ns.default ?? ns);
+    if (candidate
+        && typeof candidate === 'object'
+        && !('rules' in candidate)
+        && !('extends' in candidate)
+        && !('overrides' in candidate)
+        && candidate.default
+        && typeof candidate.default === 'object') {
+        candidate = candidate.default;
+    }
+    return candidate;
+}
+//# sourceMappingURL=worker.js.map

package/build/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "@cisco_open/linting-orchestrator",
+  "version": "1.0.0-rc.4",
+  "description": "Quality assurance for API specifications. An orchestrator daemon (spectifyd) and CLI (spectify) that run Spectral and custom rule engines at scale, with worker-per-ruleset architecture, document caching, and pluggable storage.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cisco-open/linting-orchestrator.git",
+    "directory": "packages/orchestrator"
+  },
+  "homepage": "https://github.com/cisco-open/linting-orchestrator#readme",
+  "bugs": {
+    "url": "https://github.com/cisco-open/linting-orchestrator/issues"
+  },
+  "spectify": {
+    "components": {
+      "server": "1.0.0-rc.3",
+      "cli": "1.0.0-rc.3"
+    }
+  },
+  "type": "module",
+  "main": "build/index.js",
+  "bin": {
+    "spectify": "build/cli/index.js",
+    "spectifyd": "build/index.js"
+  },
+  "scripts": {
+    "build": "tsc && chmod 755 build/index.js build/cli/index.js",
+    "rebuild": "rm -rf build && npm run build",
+    "dev": "tsx watch src/index.ts",
+    "start": "node build/index.js",
+    "mock": "tsx src/mock-server.ts",
+    "list-rulesets": "tsx src/cli/list-rulesets.ts",
+    "add-ruleset": "bash scripts/add-ruleset.sh",
+    "install-rulesets": "bash scripts/install-rulesets-dependencies.sh",
+    "check-rulesets": "bash scripts/check-rulesets-dependencies.sh",
+    "generate-openapi": "bash scripts/generate-openapi.sh",
+    "test": "vitest run",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration/deployment-modes.test.ts tests/integration/loader-accessor.test.ts",
+    "test:mcp": "vitest run tests/integration/e2e.test.ts tests/integration/performance.test.ts",
+    "test:server": "vitest run tests/unit tests/integration/loader-accessor.test.ts tests/integration/deployment-modes.test.ts",
+    "test:cli": "vitest run tests/integration/cli-config.test.ts",
+    "test:integration:e2e": "vitest run tests/integration/e2e.test.ts",
+    "test:integration:loader": "vitest run tests/integration/loader-accessor.test.ts",
+    "test:integration:perf": "vitest run tests/integration/performance.test.ts",
+    "test:watch": "vitest --watch",
+    "test:coverage": "vitest run --coverage",
+    "lint": "tsc --noEmit",
+    "api-health": "curl -s -X GET http://localhost:3003/health | jq",
+    "api-stats": "curl -s -X GET http://localhost:3003/stats | jq",
+    "api-rulesets": "curl -s -X GET http://localhost:3003/rulesets | jq"
+  },
+  "keywords": [
+    "linting",
+    "spectral",
+    "orchestrator",
+    "api-quality",
+    "openapi",
+    "asyncapi",
+    "arazzo"
+  ],
+  "author": "Cisco Systems, Inc.",
+  "license": "Apache-2.0",
+  "contributors": [
+    "DevNet Team"
+  ],
+  "dependencies": {
+    "@cisco_open/linting-document-store": "*",
+    "@cisco_open/linting-reports": "*",
+    "@fastify/swagger": "^9.7.0",
+    "@stoplight/spectral-cli": "^6.11.0",
+    "@stoplight/spectral-core": "^1.18.3",
+    "@stoplight/spectral-functions": "^1.7.2",
+    "@stoplight/spectral-rulesets": "1.22.2",
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.3",
+    "commander": "^11.1.0",
+    "dotenv": "^17.2.3",
+    "fastify": "^5.8.2",
+    "inquirer": "^9.3.8",
+    "ora": "^8.0.1",
+    "yaml": "^2.3.4"
+  },
+  "devDependencies": {
+    "@types/inquirer": "^9.0.9",
+    "@types/node": "^20.11.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3",
+    "vitest": "^4.0.18"
+  },
+  "files": [
+    "build",
+    "rulesets",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "overrides": {
+    "minimatch": "^9.0.0",
+    "@stoplight/spectral-ruleset-bundler": {
+      "rollup": "^2.80.0"
+    }
+  }
+}

package/rulesets/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Rulesets Changelog
+
+All notable changes to bundled rulesets are documented in this file.
+For orchestrator changes, see [../CHANGELOG.md](../CHANGELOG.md).
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+---
+
+## [1.0.0-rc.4] - 2026-06-18
+
+**Initial open-source release.**
+
+First public release of the bundled rulesets under the Apache-2.0 license.
+
+<!-- UPDATE ME with command: `markdown-toc -i CHANGELOG.md  --maxdepth 2` -->
+
+<!-- toc -->
+
+- [[Unreleased]](#unreleased)
+- [[1.1.0] - 2025-12-18](#110---2025-12-18)
+- [[1.0.0] - 2025-11-20](#100---2025-11-20)
+- [Versioning Policy](#versioning-policy)
+
+<!-- tocstop -->

package/rulesets/config/rulesets.yaml

@@ -0,0 +1,96 @@
+# Spectify Built-in Ruleset Configuration
+#
+# This is the MINIMAL built-in ruleset shipped with the Spectify orchestrator.
+# It serves two purposes:
+#   1. A fresh `spectifyd` install works out of the box — no external repo needed.
+#   2. A concrete, tested example of the rulesets.yaml format.
+#
+# To supply your own ruleset catalogue, point Spectify at an external rulesets
+# directory via the SPECTIFYD_RULESETS_DIR environment variable or the
+# --rulesets-directory CLI flag. See:
+#   docs/maintainers/ruleset-externalization.md
+#
+# Architecture: Source Repositories → Configuration Layer → Exposed Rulesets
+
+rulesets:
+  # ============================================================================
+  # Built-in: OpenAPI Recommended (YAML-only, no npm dependencies)
+  # ============================================================================
+  - name: oas-recommended
+    displayName: "OpenAPI Recommended"
+    category: validation
+    origin: external
+    description: >
+      Core OpenAPI 3.x validation rules built on Spectral's built-in OAS
+      ruleset, extended with a small set of opinionated quality rules.
+      No npm dependencies required.
+    tags:
+      - oas
+      - spectral
+    metadata:
+      team: "Spectify"
+      repository: "https://github.com/cisco-open/spectify"
+      license: "Apache-2.0"
+      documentation: ""
+    versions:
+      - version: "1.0.0"
+        sourceRepo: "example/oas-recommended"
+        sourceVersion: "v1.0.0"
+        entrypoint: "ruleset.yaml"
+        releaseDate: "2026-06-01"
+        deprecated: false
+        changelog: "Initial release. Extends spectral:oas recommended profile."
+      - version: "2.0.0"
+        sourceRepo: "example/oas-recommended"
+        sourceVersion: "v2.0.0"
+        entrypoint: "ruleset.yaml"
+        releaseDate: "2026-06-01"
+        deprecated: false
+        changelog: >
+          v2: adds operation-operationId, operation-tags, and
+          info-contact-email rules on top of the v1 base.
+
+# ============================================================================
+# Default Configuration
+# ============================================================================
+# Default versions for each ruleset.
+# Should always point to stable, non-deprecated versions.
+# "latest" resolves to the last non-deprecated entry in the versions array.
+
+defaults:
+  oas-recommended: "2.0.0"
+
+# ============================================================================
+# Configuration Notes
+# ============================================================================
+#
+# Adding a new ruleset:
+# 1. Add source to: rulesets/sources/{sourceRepo}/{sourceVersion}/
+# 2. Add configuration entry above with unique name
+# 3. Set appropriate category, origin, and metadata
+# 4. Add to defaults section
+# 5. Restart Spectify service (or call cache refresh API when available)
+#
+# Updating an existing ruleset:
+# 1. Add new source version to sources directory
+# 2. Add new version entry under existing ruleset
+# 3. Update defaults to point to new version (optional)
+# 4. Mark old version as deprecated if needed (optional)
+#
+# For team-specific rulesets, use an external rulesets directory instead
+# of modifying this built-in configuration. See ruleset-externalization.md.
+#
+# Categories:
+#   - publishing: Rules for content publishing platforms
+#   - contract: API contract validation and quality
+#   - documentation: Documentation completeness and quality
+#   - validation: General validation and linting
+#   - security: Security-focused validation
+#   - other: Miscellaneous or multi-purpose rulesets
+#
+# Origins:
+#   - internal: Internal repositories
+#   - external: Public open-source repositories
+#   - third-party: External vendor/partner repositories
+#
+# ============================================================================