{"id":26256611,"url":"https://github.com/netcracker/qubership-apihub-api-processor","last_synced_at":"2026-02-09T20:12:30.690Z","repository":{"id":270134887,"uuid":"907631878","full_name":"Netcracker/qubership-apihub-api-processor","owner":"Netcracker","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-27T14:22:37.000Z","size":2700,"stargazers_count":0,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"develop","last_synced_at":"2026-01-27T23:38:44.286Z","etag":null,"topics":["apihub","broadcast-pilot","frontend","qubership-apihub"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Netcracker.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE-OF-CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-12-24T03:18:09.000Z","updated_at":"2026-01-21T08:25:47.000Z","dependencies_parsed_at":"2025-07-01T11:22:04.106Z","dependency_job_id":"2261fb95-c444-4573-8853-93c700de6950","html_url":"https://github.com/Netcracker/qubership-apihub-api-processor","commit_stats":null,"previous_names":["netcracker/qubership-apihub-api-processor"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/Netcracker/qubership-apihub-api-processor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Netcracker%2Fqubership-apihub-api-processor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Netcracker%2Fqubership-apihub-api-processor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Netcracker%2Fqubership-apihub-api-processor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Netcracker%2Fqubership-apihub-api-processor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Netcracker","download_url":"https://codeload.github.com/Netcracker/qubership-apihub-api-processor/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Netcracker%2Fqubership-apihub-api-processor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29279470,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-09T19:05:41.198Z","status":"ssl_error","status_checked_at":"2026-02-09T19:05:37.449Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apihub","broadcast-pilot","frontend","qubership-apihub"],"created_at":"2025-03-13T20:18:40.911Z","updated_at":"2026-02-09T20:12:30.685Z","avatar_url":"https://github.com/Netcracker.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# qubership-apihub-api-processor\n\nTypeScript/Node.js library that processes API source specifications (REST/OpenAPI, GraphQL, text, and unknown files) into a **package-version build result**: parsed documents, extracted operations, optional version comparisons (changelog), export artifacts, and notifications.\n\nThis repository is published as `@netcracker/qubership-apihub-api-processor`.\n\n## What it does (high level)\n\nThe main entry point is `PackageVersionBuilder`. You provide:\n\n- **Build configuration** (`BuildConfig`) that describes *what* to build (package id/version, files/refs, build type, etc.)\n- **Resolvers** (`BuilderResolvers`) that describe *how* to fetch inputs (files, previous version data, templates, documents, etc.)\n\nThe builder produces a `BuildResult` that contains:\n\n- **documents** (`Map\u003cstring, VersionDocument\u003e`)\n- **operations** (`Map\u003cstring, ApiOperation\u003e`)\n- **comparisons** (`VersionsComparison[]`, when changelog comparison is enabled)\n- **notifications** (errors/warnings/info produced during parsing/building)\n- **exportDocuments / exportFileName** (for export-related build types)\n- **merged** document (for merged outputs where applicable)\n\n## Technologies used in this repo\n\n- **Language**: TypeScript\n- **Runtime**: Node.js (see `package.json` engines: Node \u003e= 18)\n- **Build**: `tsc` (CommonJS) + `vite` (ES/UMD bundle + types via `vite-plugin-dts`)\n- **Testing**: Jest + `ts-jest`\n- **API parsing \u0026 processing**: `graphql`, `swagger2openapi`, `js-yaml`, `ajv`, plus Netcracker ApiHub libraries:\n  - `@netcracker/qubership-apihub-api-diff`\n  - `@netcracker/qubership-apihub-api-unifier`\n  - `@netcracker/qubership-apihub-graphapi`\n  - `@netcracker/qubership-apihub-json-crawl`\n\n## Installation (as a dependency)\n\n```bash\nnpm i @netcracker/qubership-apihub-api-processor\n```\n\n## Basic usage\n\n```typescript\nimport { PackageVersionBuilder } from '@netcracker/qubership-apihub-api-processor'\n\nconst builder = new PackageVersionBuilder(config, {\n  resolvers: {\n    fileResolver: this.fileResolver.bind(this),\n    ...versionResolvers,\n  },\n})\n\nconst buildResult = await builder.run()\n```\n\n## Configuration model\n\n### BuildConfig\n\n`BuildConfig` includes (among other fields):\n\n- **packageId / version**: identify the package version being built\n- **status**: `release | draft | archived | release-candidate` (and `''` for some build types)\n- **previousVersion / previousVersionPackageId**: previous version for changelog comparisons\n- **buildType**: selects the processing strategy (see below)\n- **files**: list of `{ fileId, ... }` source inputs (YAML/JSON/GraphQL/MD/Proto/etc. depending on supported formats)\n- **refs**: references to other packages/versions to include or resolve against\n- **format / allowedOasExtensions / operationsSpecTransformation**: export-specific switches (for export build types)\n\n### Build types (strategies)\n\nThe builder selects a strategy based on `buildType`:\n\n- **`build`**: build documents and operations; optionally compute comparisons to `previousVersion`\n- **`changelog`**: build changelog/comparisons (requires previous version)\n- **`prefix-groups-changelog`**: changelog with group prefixing logic\n- **`exportVersion`**: export a whole version in the selected format\n- **`exportRestDocument`**: export a single REST document by `documentId`\n- **`exportRestOperationsGroup`**: export a REST operations group (`groupName`) using a transformation (`reducedSourceSpecifications` or `mergedSpecification`)\n\nDeprecated (still present in constants/types):\n\n- **`documentGroup`**\n- **`reducedSourceSpecifications`**\n- **`mergedSpecification`**\n\n## Resolvers (I/O boundary)\n\n`PackageVersionBuilder` itself does not know how to fetch files or previous versions — it delegates this to resolvers.\n\nOnly **`fileResolver` is required**. The rest are optional in the type system, but some build types/flows will throw if a resolver is missing.\n\nResolvers you can provide (see `BuilderResolvers`):\n\n- **fileResolver**: load a file by `fileId` (required)\n- **packageResolver**: resolve package metadata\n- **versionResolver**: resolve version metadata (used for comparisons and various flows)\n- **versionOperationsResolver**: fetch operations for a given version (may include operation data)\n- **versionReferencesResolver**: fetch references for a version\n- **versionDeprecatedResolver**: fetch deprecated operations/items for a version\n- **versionComparisonResolver**: fetch cached comparison summary (optional)\n- **groupDocumentsResolver**: fetch documents filtered by operation group\n- **versionDocumentsResolver**: fetch documents for a version (optionally filtered by apiType)\n- **rawDocumentResolver**: fetch a raw document file by (version, packageId, slug)\n- **groupExportTemplateResolver / templateResolver**: resolve templates for export\n\n## Incremental rebuilds\n\n`PackageVersionBuilder.update()` supports incremental rebuild scenarios:\n\n- Clears caches depending on `cleanCache`\n- Re-parses only changed inputs (based on `changedFiles`)\n- Recomputes comparisons when previous version changed or inputs changed (unless `withoutChangelog`)\n\n## High-level architecture (ASCII)\n\nThe library is structured as a pipeline with a **single public orchestrator** (`PackageVersionBuilder`), pluggable **strategies** (by build type), reusable **components**, and per-api-type **builders**.\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                              PUBLIC API / ENTRY                             │\n│                                                                             │\n│                       PackageVersionBuilder (main)                          │\n│                        ┌────────────────────────┐                           │\n│                        │ run()                  │                           │\n│                        │ update()               │                           │\n│                        │ createVersionPackage() │                           │\n│                        └───────────┬────────────┘                           │\n└────────────────────────────────────┼────────────────────────────────────────┘\n                                     │\n                                     ▼\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                          STRATEGIES (Strategy pattern)                       │\n│                                                                             │\n│  BuilderStrategyContext selects \u0026 runs:                                      │\n│  - BuildStrategy                                                            │\n│  - ChangelogStrategy                                                        │\n│  - DocumentGroupStrategy / PrefixGroupsChangelogStrategy                     │\n│  - MergedDocumentGroupStrategy                                              │\n│  - ExportVersionStrategy / ExportRestDocumentStrategy                        │\n│  - ExportRestOperationsGroupStrategy                                        │\n└────────────────────────────────────┬────────────────────────────────────────┘\n                                     │\n                                     ▼\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                               COMPONENTS                                    │\n│                                                                             │\n│  Files → Document → Operations → Compare → Package/Deprecated                │\n└────────────────────────────────────┬────────────────────────────────────────┘\n                                     │\n                                     ▼\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                          API TYPE BUILDERS                                   │\n│                                                                             │\n│  REST (OpenAPI)  |  GraphQL  |  Text  |  Unknown                             │\n│   - parser       |  - parser |  ...   |  ...                                 │\n│   - document     |  - doc    |        |                                      │\n│   - operations   |  - ops    |        |                                      │\n│   - changes      |  - changes|        |                                      │\n└────────────────────────────────────┬────────────────────────────────────────┘\n                                     │\n                                     ▼\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                       RESOLVERS \u0026 STORAGE                                    │\n│                                                                             │\n│  External resolvers supply I/O (files, versions, documents, templates).      │\n│  Internal caches store parsedFiles/documents/operations and version caches.  │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n### Data flow (simplified)\n\n```\n1) BuildConfig + Resolvers\n   ↓\n2) PackageVersionBuilder.run() selects strategy by buildType\n   ↓\n3) Strategy invokes components using BuilderContext / CompareContext\n   ↓\n4) Components parse inputs via apiBuilders (REST/GraphQL/Text/Unknown)\n   ↓\n5) BuildResult is produced: documents, operations, comparisons, notifications, exports\n```\n\n## Build artifacts (this repo)\n\nThis repo builds two sets of outputs (see `package.json` and Vite config):\n\n- **CommonJS**: `dist/cjs` (via `tsc --module commonjs --outDir dist/cjs`)\n- **ES/UMD bundle + types**: `dist/esm/apihub-builder.es.js` and `dist/esm/apihub-builder.umd.js` (via `vite build`)\n\n## How to build (repo)\n\n```bash\nnpm ci\nnpm run build\n```\n\n## How to run tests\n\n```bash\nnpm test\n```\n\nCoverage:\n\n```bash\nnpm run test:coverage\n```\n\n## How to run \u0026 debug (repo)\n\nThis is a library, so there is no `start` script. For debugging runtime behavior, the repo contains a performance harness entrypoint at `test/performance.ts` and a dedicated Vite config for it.\n\n- Build the performance bundle:\n\n```bash\nnpm run performance:build\n```\n\n- Run it with Node inspector:\n\n```bash\nnpm run performance:run-inspect\n```\n\nNotes:\n\n- `npm run performance:run-inspect` executes `node --inspect dist/index.es.js` (the file produced by the performance Vite build).\n- `profile:*` and `operation:test` scripts in `package.json` reference `./test/profile.js` and `./test/operation.js`, but those files are not present in this repository snapshot.\n\n## Local development tips\n\nThe repo includes helper scripts to link/unlink related ApiHub packages (useful when developing multiple packages together):\n\n```bash\nnpm run development:link\n```\n\n```bash\nnpm run development:unlink\n```\n\n## Repository layout (quick map)\n\n- **`src/builder.ts`**: `PackageVersionBuilder` orchestrator (run/update/package creation)\n- **`src/strategies/`**: build-type strategies (build, changelog, export, etc.)\n- **`src/components/`**: reusable build components (files/document/operations/compare/package/deprecated)\n- **`src/apitypes/`**: per-API-type logic (REST/OpenAPI, GraphQL, text, unknown)\n- **`src/types/`**: public and internal types (configs, resolvers, build results)\n- **`src/utils/`**: shared helpers (diff/merge/validate/logging/etc.)\n- **`test/`**: Jest test suite + test projects fixtures\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetcracker%2Fqubership-apihub-api-processor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetcracker%2Fqubership-apihub-api-processor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetcracker%2Fqubership-apihub-api-processor/lists"}