Skip to content

Fix jsdoc build warnings/errors (unblocks removing '|| true' and hardening the deploy) #45

Description

@cewert

Low priority — the API docs are rarely used and the build issues are harmless today — but worth capturing so it isn't forgotten.

Root issue: the jsdoc build emits warnings/errors

npm run build (jsdoc over the jellyrock source) currently produces build warnings/errors. Because of that, both ci.yml and update.yml run it as npm run build || true (there's already a TODO noting this), so the build can never fail the pipeline. Fixing those warnings/errors is the prerequisite for everything below.

Why it matters (the downstream fragility)

Until the build is clean and || true can be removed, the deploy shape is fragile:

  • deploy.yml rsyncs the committed docs/ artifact — it does not build on deploy.
  • ci.yml build can't fail (|| true), so a broken/partial build is invisible.
  • update.yml regenerates + commits docs/ only on repository_dispatch: code-update from jellyrock/jellyrock, not when api-docs config changes — and it also builds with || true, so it could commit empty/partial docs.

Net effect: a config change (e.g. jsdoc.json) doesn't reach the live site until docs/ is regenerated, and a silently-broken build could still deploy.

How it surfaced

During the ADR-0006 first-party analytics migration (jellyrock/command-center), switching the tracker embed in jsdoc.json had no effect on live api.jellyrock.app — the deploy served the stale committed docs/. Needed a second PR to regenerate the artifact (#43 = config, #44 = artifact).

Suggested order

  1. Fix the jsdoc build warnings/errors (the actual work; low priority).
  2. Remove || true from ci.yml + update.yml so build failures are visible.
  3. Then harden the deploy — either build-on-deploy (stop committing docs/) or gate the rsync deploy on a green build via workflow_run.

Steps 2–3 are cheap once step 1 is done. Org-deploy-consistency context: ADR-0004 / ADR-0005 in jellyrock/command-center.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions