Skip to content

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

@cewert

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
    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