How redocly/redocly-cli works
Project type and purpose
• This is an open‑source, monorepo CLI tool (“Redocly CLI”) for managing OpenAPI/AsyncAPI/Arazzo specs: linting, bundling, splitting, building docs, running workflow tests (“respect”).
• Key packages:
– packages/cli: the command‑line interface and entry point
– packages/core: the core processing engine (bundle, lint, split, stats, format, resolve)
– packages/respect-core: the “respect” workflow runner (test‑case execution, arazzo flows)
File structure
• Top‑level: docs/ (static guides), packages/ (source code), __tests__/ (end‑to‑end tests), scripts/, resources/, Dockerfile, configs (.eslintrc.yml, tsconfig.json, etc.).
• Monorepo uses Lerna‐style packages. Each package has src/ and __tests__/ subfolders.
• commands in CLI map 1:1 to top‑level features (build‑docs, bundle, lint, split, stats, respect, etc.).
• Config loaders from .redocly.yaml or CLI flags feed into core.
• External calls: cli→packages/core→OpenAPI parsers & decorators; cli→packages/respect-core→HTTP calls / HAR logging for API tests; cli→Reunite API (packages/cli/src/reunite/api); telemetry & update checks.
README
• Describes CLI usage, Node vs Docker, commands (lint, bundle, build‑docs, respect, split, stats).
• Mentions plugin/config system & extension points (custom rulesets, decorators).
• Notes hosted “Reunite” integration for publishing.
a. Main components:
– CLI Invocation (bin/cli.js)
– Argument Parser & Dispatcher (commander.js in packages/cli)
– Config Loader (.redocly.yaml, environment vars)
– Command Modules:
• Build‑Docs → core.buildDocs → Redoc template engine (handlebars) → HTML output
• Bundle/Lint/Split/Stats → core.bundle, core.lint, core.split, core.stats → JSON/YAML output
• Respect → respect-core modules → workflow runner → API calls / HAR logs → test reports
• Reunite → API client modules → Redocly hosted services
– Core Library (packages/core): parse & traverse OpenAPI/AsyncAPI, apply decorators & rules, bundle and resolve refs, format errors.
– Respect‑Core Library (packages/respect-core): parse arazzo YAML, generate test definitions, run HTTP calls, evaluate success criteria.
– External Dependencies:
• File System (read/write spec files, output docs)
• Network (Reunite API, remote config, HTTP calls for “respect”)
• Docker runtime (optional container)
– CI/CD & Release Scripts (scripts/, .github/workflows)
– Documentation (docs/ served separately)
b. Relationships & interactions:
– User types redocly [command] [options] → bin/cli.js → dispatcher
– Dispatcher loads config → invokes relevant command module
– Command module delegates to core or respect-core APIs
– Core reads spec files, applies resolution & linting pipeline → returns AST/results → CLI formats & writes to console or files
– Respect‑Core reads spec + workflows → for each test: makes HTTP calls → matches responses against schemas & criteria → outputs summary
– Some commands call Reunite API client (packages/cli/src/reunite) to push status or docs to Redocly hosted service
– Dockerfile wraps the same CLI, mounting host spec directory
c. Architectural patterns / design principles:
– Monorepo with loosely coupled packages (CLI, Core, Respect)
– Plugin/Decorator pattern for extensibility of rules & transformations
– Single entry point and command dispatcher (Command pattern)
– Pipelines: parsing → resolving refs → applying decorators → linting/bundling → output
– Separation of concerns: CLI/UI vs core logic vs test runner
d. Relevant technologies/frameworks:
– Node.js + TypeScript
– Commander.js (or similar) for CLI
– Handlebars templates for build‑docs
– AJV for JSON schema validation in lint
– Axios / fetch for HTTP calls in respect-core and reunite
– Lerna/Yarn workspaces for monorepo
– Docker for containerization