Skip to content

chore(docs): pin widdershins as a devDependency instead of npx in the three services #124

Description

@rohit-sourcefuse

Background

#123 added OpenAPI markdown generation via an apidocs script in all three services:

"apidocs": "npx widdershins --language_tabs 'javascript:JavaScript:request' 'javascript--nodejs:Node.JS' --summary openapi.json -o openapi.md"

widdershins is not a declared dependency, so npx resolves and downloads it from the registry on every run. Since build now chains apidocs (lb-tsc && npm run openapi-spec && npm run apidocs) — and pretest → rebuild → build — this means every npm run build, npm test, and the Docker RUN npm run build now depends on a network fetch of an unpinned, floating version.

Problems:

  • Non-reproducible builds (picks up new widdershins releases silently → openapi.md output can change).
  • Breaks on offline / air-gapped CI or a registry hiccup, and adds latency on clean environments.
  • A bad widdershins release would break the build of all three services.

Fix

Pin widdershins as a devDependency (the version that generated the committed docs is 4.0.1 — see Generator: Widdershins v4.0.1 in the existing openapi.md) and call the local bin instead of npx, in services/{orchestrator,subscription,tenant-management}-service/package.json:

"devDependencies": {
  "widdershins": "4.0.1"
},
"scripts": {
  "apidocs": "widdershins --language_tabs 'javascript:JavaScript:request' 'javascript--nodejs:Node.JS' --summary openapi.json -o openapi.md"
}

Then npm install to lock it.

Optional (same area)

  • Consider moving doc generation out of build into a dedicated docs script + a CI drift-guard (npm run docs --workspaces && git diff --exit-code services/**/openapi.{json,md}) so doc-gen failures don't fail compile/test and Docker builds stay offline-safe.
  • orchestrator's openapi.json info.title is the package name (@sourceloop/ctrl-plane-orchestrator-service) — set a human title to match the tenant/subscription fix.

Acceptance

  • widdershins is a pinned devDependency in all three services; lockfile updated.
  • apidocs no longer uses npx.
  • npm run build works with no network access to the npm registry for widdershins.

Follow-up to #123 (merged with these as non-blocking review comments).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions