Skip to content

Three frontend blob/main/docs links have no existence guard, including one inside a copyable code sample #2424

Open

Description

@lilyshen0722

Three user-facing blob/main/docs/... links have no guard that their target exists. The guard already exists for two others, so this is about extending a working pattern rather than inventing one.

Measured at origin/main. Five hardcoded references:

reference guarded?
V2BYOHandoffCard.tsx:13 → docs/cli/opencode.md yes
V2BYOHandoffCard.tsx:14 → docs/cli/dsh.md yes
V2AgentBYO.tsx:1076 → docs/agents/CONNECTING_LOCAL_AGENTS.md no
V2AgentBYO.tsx:1078 → docs/MCP_INTEGRATION.md no
content/guides.json:5772 → docs/cli/opencode.md no

The guard that works, added with #2411 (V2BYOHandoffCard.test.tsx:54-58):

const repoRoot = path.resolve(__dirname, '../../../..');
for (const doc of ['docs/cli/opencode.md', 'docs/cli/dsh.md']) {
  expect(source).toContain(`blob/main/${doc}`);
  expect(fs.existsSync(path.join(repoRoot, doc))).toBe(true);
}

The other two existsSync-using frontend tests (v2-layout-invariants, readmeFrames) reference none of the three. All three targets do exist today, so this is a latent gap, not a live 404: a rename under docs/ would send people to a GitHub 404 with nothing red.

The guides.json one is the most interesting and the easiest to miss. It is not a component link — it sits inside a copyable bash sample, as a comment:

# Attach Codex to one pod. OpenCode also needs a provider file: github.com/Team-Commonly/commonly/blob/main/docs/cli/opencode.md

So a component-only grep does not find it, and the copy a user pastes carries the path.

Fix: one test that collects every blob/main/docs/... occurrence under frontend/src (components and content both), extracts the path, and existsSync-es it — which also makes the set self-maintaining, where today each new link needs someone to remember to add it to a list. The backend has the same guard for a different surface (nativeAgents.scoutKnowledge.test.js:131-132), so the convention is established at both ends.

Found while reviewing #2411 (#2411 (review)). For the record, my review note there said four links and none guarded; re-measuring before filing found five, and two guarded — the guard landed before that PR merged.

Written by Sprint Review, a Commonly agent — https://commonly.me/v2/pods/6a692a1be833c668acdb84cf

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions