1.0.0-rc.5 • Published 2d agoCLI

@cisco_open/linting-orchestrator

Licence

Apache-2.0

Version

1.0.0-rc.5

Deps

Size

1.0 MB

Vulns

Weekly

Summary Dependency Versions

Linting Orchestrator for Quality Assurance

Quality assurance for API descriptions — orchestrated linting with Spectral and custom rule engines.

Quick start

# Install the orchestrator (CLI + daemon)
npm install -g @cisco_open/linting-orchestrator

# Optional: install the reporting service
npm install -g @cisco_open/linting-reports

spectifyd &                             # start the orchestrator daemon
spectify lint path/to/your-api.yaml    # lint a YAML or JSON document

New here? The tour walks through the full workflow: daemon, rulesets, results, and the reports UI.

Maintainers / contributors: See installation.md for the source-based workflow.

What's in this repo

Binary	Role
`spectifyd`	The orchestrator daemon (HTTP API + worker pool)
`spectify`	The CLI used to talk to the daemon (or run embedded)
`spectifyr`	Optional companion: the linting reporting service

The orchestrator is designed as three cooperating components:

The linting orchestrator service (spectifyd) accepts lint jobs over HTTP, dispatches them to a pool of worker threads pre-loaded with rulesets, and returns SARIF-formatted results. One worker is kept warm per ruleset; document affinity keeps recently-linted documents in worker memory.
The orchestrator CLI (spectify) is the everyday user-facing tool. It can embed the daemon for one-shot use, talk to a long-running daemon, or be driven from CI.
The linting reporting service (spectifyr, separate package @cisco_open/linting-reports) persists job results into SQLite and exposes a small web UI for browsing them across runs.

How it fits together

┌──────────┐     ┌──────────────┐     ┌────────────┐     ┌────────────┐
│ spectify │───▶│  spectifyd   │────▶│  workers   │     │ spectifyr  │
│  (CLI)   │     │  (daemon)    │     │ (Spectral) │───▶│  (reports   │
└──────────┘     │  HTTP API    │     │            │     │  + DB)     │
                 └──────────────┘     └────────────┘     └────────────┘
                       │                     ▲
                       ▼                     │
                ┌──────────────┐             │
                │  document    │             │
                │   store      │◀───────────┘
                │ (filesystem) │
                └──────────────┘

The orchestrator never copies document content between processes; workers read by path. The reports service is optional and can be added at any time without touching ruleset configuration.

Three modes are supported — embedded (in-process, ideal for one-shot/CI use), standalone (long-running service), and companion (co-located with an MCP uploader). In every mode the command is the same (spectify lint); what differs is where the daemon lives. See deployment modes for details.

Rulesets

The orchestrator ships with Spectral-based rulesets out of the box and can load additional rulesets from the filesystem. See packages/orchestrator/docs/ruleset-management.md for adding, versioning, and configuring rulesets.

# list installed rulesets
spectify rulesets              

# list rules for a particular ruleset
spectify rulesets --name contract --verbose

Configuration

The daemon is configured via config/default.yaml with environment-variable overrides.

Daemon-side variables use the SPECTIFYD_prefix; client-side connection config for the reporting service uses SPECTIFYD_REPORTS_.

The reporting service itself reads SPECTIFYR_* in its own repo.

Variable	Purpose
`SPECTIFYD_PORT`	HTTP API port (default `3003`)
`SPECTIFYD_DOCUMENT_STORE_TYPE`	`local` or `passthrough`
`SPECTIFYD_DOCUMENT_STORE_DIR`	Document directory
`SPECTIFYD_TOTAL_MAX_WORKERS`	Cap on total worker threads
`SPECTIFYD_LOG_LEVEL`	`error` \| `warn` \| `info` \| `debug` \| `trace`
`SPECTIFYD_REPORTS_ENABLED`	Forward results to the reporting service
`SPECTIFYD_REPORTS_URL`	Reporting service URL

See packages/orchestrator/docs/installation.md for the complete list and recommended values per deployment mode.

Testing

npm test                       # unit + non-network integration suites
npm run test:unit
npm run test:integration       # deployment modes + loader/accessor
npm run test:mcp               # requires a running MCP-style uploader

Documentation

User guides:

Tour — 5-minute walkthrough from clone to lint report
Installation — global install, npm link, or from source
CLI quick start
HTTP API quick start
Deployment modes — embedded, standalone, companion
Ruleset management
MCP integration
Pluggable document store
Versioning strategy

Design & internals:

Contributing:

CONTRIBUTING.md
CODE_OF_CONDUCT.md
SECURITY.md
AGENTS.md — guidance for AI coding agents working on the repo

Repository layout

This repo is an npm-workspaces monorepo. The three packages live under packages/:

Path	Package name	Role
`packages/orchestrator/`	`@cisco_open/linting-orchestrator`	The orchestrator daemon (`spectifyd`) and CLI (`spectify`).
`packages/reports/`	`@cisco_open/linting-reports`	The linting reporting service (`spectifyr`).
`packages/document-store/`	`@cisco_open/linting-document-store`	Pluggable document-storage library.

Shared assets stay at the repo root: rulesets/, scripts/, examples/, docs/, plus the LICENSE and community files.

Common workflow:

npm install                                          # links workspaces
npm run build                                        # builds all three, in order
npm test                                             # runs every package's tests
npm run dev                                          # tsx watch on the orchestrator