From bc0a076e13f2434f2455e2264abaac3334cfbe95 Mon Sep 17 00:00:00 2001 From: Pat Newell Date: Thu, 4 Jun 2026 12:36:29 -0400 Subject: [PATCH] fix(ui): stop linking foreign tracker keys as Paperclip issues (#7511) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes #7514 — the prefix-validation piece of the #5456 auto-linker 404-storm umbrella. The remaining pieces (404 retry guard, word-boundary tightening, comment edit/soft-delete) stay open under #5456. Part of #5456. ## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - Agents and humans cross-reference work in markdown — issue descriptions, comments, documents — which the UI renders through a shared `MarkdownBody` > - That renderer auto-links any `IDENT-123`-shaped token to an internal `/issues/IDENT-123` link > - But foreign tracker keys share that exact shape: a Jira `TREE-604` (or any external `ORG-123`) mentioned in prose becomes a link to a Paperclip issue that does not exist — it 404s, and the renderer also fires a wasted issue-fetch for the bogus identifier > - The set of real issue prefixes is already in the browser: every company carries an `issuePrefix`, exposed via `CompanyContext` > - This PR gates bare-token auto-linking to known company prefixes, leaving explicit `issue://` / `/issues/` references and real markdown links untouched > - The benefit is no dead internal links from foreign keys, with no new query, cache, or server change — and zero regression when prefixes aren't yet known ## What Changed - **`ui/src/lib/issue-reference.ts`** — `parseIssueReferenceFromHref` takes an optional `knownPrefixes` set and rejects a bare `IDENT-123` token whose prefix isn't in it; threaded through `remarkLinkIssueReferences(options)` → tree rewrite → text and inline-code paths. An omitted/empty set keeps the legacy permissive behavior. Explicit `issue://` scheme and `/issues/` path forms are never gated. - **`ui/src/context/CompanyContext.tsx`** — adds `useOptionalCompany()`, a non-throwing variant of `useCompany()` (returns `null` outside a provider). - **`ui/src/components/MarkdownBody.tsx`** — reads company prefixes via `useOptionalCompany()` and passes them to the linkifier. The non-throwing read keeps `MarkdownBody` renderable in provider-less surfaces (e.g. standalone/exported markdown). - Tests extended in `issue-reference.test.ts` (gating + remark-plugin cases) and `MarkdownBody.test.tsx` (gating, empty-companies permissive, explicit-path bypass). ## Verification - `pnpm --filter @paperclipai/ui exec vitest run src/lib/issue-reference.test.ts src/components/MarkdownBody.test.tsx` — green (17 + 40 tests). - Full UI suite: `pnpm --filter @paperclipai/ui exec vitest run` — **1161 passed / 183 files**; pre-existing `MarkdownBody` link tests pass unmodified (they hit the permissive `null`-context path), confirming no regression. - `pnpm --filter @paperclipai/ui run typecheck` — clean. - _Screenshots pending — opening as draft; before/after images to follow before marking ready._ - Manual (before/after): in an issue description containing both a real Paperclip identifier and a Jira key — _before_ both render as `/issues/...` links (the Jira one dead); _after_ only the real identifier links and the Jira key is plain text. ## Risks - **Low risk.** No server/API/migration change; pure client rendering logic. - A referenced issue whose company isn't in the viewer's `companies` list stops auto-linking — acceptable, since that internal link wouldn't resolve for that viewer anyway; explicit `/issues/IDENT` references still render. - During initial load (companies not yet fetched) behavior is identical to today (permissive), so no new flicker. ## Model Used - **Anthropic Claude Opus 4.8** (`claude-opus-4-8`), 1M-token context, extended thinking + tool use. Plan authored and implemented with the model; all decisions reviewed by the human contributor. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes (no doc changes required — behavior gated, no public API/doc surface affected) - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Claude Opus 4.8 (1M context) --- ui/src/components/MarkdownBody.test.tsx | 48 ++++++++++++++- ui/src/components/MarkdownBody.tsx | 10 ++- ui/src/context/CompanyContext.tsx | 10 +++ ui/src/lib/issue-reference.test.ts | 82 ++++++++++++++++++++++++- ui/src/lib/issue-reference.ts | 44 ++++++++++--- 5 files changed, 182 insertions(+), 12 deletions(-) diff --git a/ui/src/components/MarkdownBody.test.tsx b/ui/src/components/MarkdownBody.test.tsx index dd92af4b..d91df21b 100644 --- a/ui/src/components/MarkdownBody.test.tsx +++ b/ui/src/components/MarkdownBody.test.tsx @@ -2,7 +2,7 @@ import type { ComponentProps, ReactNode } from "react"; import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; -import { describe, expect, it, vi } from "vitest"; +import { afterEach, describe, expect, it, vi } from "vitest"; import { renderToStaticMarkup } from "react-dom/server"; import { buildAgentMentionHref, @@ -34,6 +34,18 @@ vi.mock("../api/issues", () => ({ issuesApi: mockIssuesApi, })); +// Defaults to null (no provider) so the existing suite exercises the permissive +// path unchanged. Gating tests override the return value per-case. +const mockUseOptionalCompany = vi.hoisted(() => vi.fn<() => { companies: Array<{ issuePrefix: string }> } | null>(() => null)); + +vi.mock("../context/CompanyContext", () => ({ + useOptionalCompany: mockUseOptionalCompany, +})); + +afterEach(() => { + mockUseOptionalCompany.mockReturnValue(null); +}); + function renderMarkdown( children: string, seededIssues: Array<{ identifier: string; status: string; title?: string }> = [], @@ -486,4 +498,38 @@ describe("MarkdownBody", () => { expect(html).toContain("paperclip-markdown-issue-ref"); expect(html).not.toContain("paperclip-mention-chip--issue"); }); + + it("gates bare-identifier auto-linking to known company prefixes", () => { + mockUseOptionalCompany.mockReturnValue({ companies: [{ issuePrefix: "PAP" }] }); + + const html = renderMarkdown("Depends on PAP-1271 and blocked by JIRA-2.", [ + { identifier: "PAP-1271", status: "done" }, + { identifier: "JIRA-2", status: "done" }, + ]); + + // Known prefix links; foreign tracker key stays as plain text. + expect(html).toContain('href="/issues/PAP-1271"'); + expect(html).not.toContain('href="/issues/JIRA-2"'); + expect(html).toContain("blocked by JIRA-2."); + }); + + it("stays permissive when companies are loaded but the list is empty", () => { + mockUseOptionalCompany.mockReturnValue({ companies: [] }); + + const html = renderMarkdown("See JIRA-2 for context.", [ + { identifier: "JIRA-2", status: "done" }, + ]); + + expect(html).toContain('href="/issues/JIRA-2"'); + }); + + it("never gates explicit internal issue paths, even for unknown prefixes", () => { + mockUseOptionalCompany.mockReturnValue({ companies: [{ issuePrefix: "PAP" }] }); + + const html = renderMarkdown("See /ACME/issues/ACME-1 for the writeup.", [ + { identifier: "ACME-1", status: "done" }, + ]); + + expect(html).toContain('href="/issues/ACME-1"'); + }); }); diff --git a/ui/src/components/MarkdownBody.tsx b/ui/src/components/MarkdownBody.tsx index 5d4fd886..4d4cb8e7 100644 --- a/ui/src/components/MarkdownBody.tsx +++ b/ui/src/components/MarkdownBody.tsx @@ -6,6 +6,7 @@ import remarkGfm from "remark-gfm"; import { cn } from "../lib/utils"; import { Link } from "@/lib/router"; import { useTheme } from "../context/ThemeContext"; +import { useOptionalCompany } from "../context/CompanyContext"; import { mentionChipInlineStyle, parseMentionChipHref } from "../lib/mention-chips"; import { issuesApi } from "../api/issues"; import { queryKeys } from "../lib/queryKeys"; @@ -570,12 +571,19 @@ export function MarkdownBody({ onImageClick, }: MarkdownBodyProps) { const { theme } = useTheme(); + // Read company prefixes non-throwingly: MarkdownBody renders in surfaces that + // may lack a CompanyProvider. A null context (or no companies yet) leaves + // knownPrefixes undefined, which keeps issue auto-linking permissive. + const company = useOptionalCompany(); + const knownPrefixes = company?.companies.length + ? company.companies.map((c) => c.issuePrefix) + : undefined; const remarkPlugins: NonNullable = [remarkGfm]; if (enableWikiLinks) { remarkPlugins.push(createRemarkWikiLinks({ wikiLinkRoot, resolveWikiLinkHref })); } if (linkIssueReferences) { - remarkPlugins.push(remarkLinkIssueReferences); + remarkPlugins.push([remarkLinkIssueReferences, { knownPrefixes }]); } if (softBreaks) { remarkPlugins.push(remarkSoftBreaks); diff --git a/ui/src/context/CompanyContext.tsx b/ui/src/context/CompanyContext.tsx index 140d2c83..19587adb 100644 --- a/ui/src/context/CompanyContext.tsx +++ b/ui/src/context/CompanyContext.tsx @@ -176,3 +176,13 @@ export function useCompany() { } return ctx; } + +/** + * Non-throwing variant of {@link useCompany}. Returns null when called outside a + * CompanyProvider instead of throwing, so components that may render in + * provider-less surfaces (e.g. exported/standalone markdown) can read company + * state without crashing. + */ +export function useOptionalCompany(): CompanyContextValue | null { + return useContext(CompanyContext); +} diff --git a/ui/src/lib/issue-reference.test.ts b/ui/src/lib/issue-reference.test.ts index 9d8ca760..13a42a19 100644 --- a/ui/src/lib/issue-reference.test.ts +++ b/ui/src/lib/issue-reference.test.ts @@ -1,5 +1,15 @@ import { describe, expect, it } from "vitest"; -import { parseIssuePathIdFromPath, parseIssueReferenceFromHref } from "./issue-reference"; +import { parseIssuePathIdFromPath, parseIssueReferenceFromHref, remarkLinkIssueReferences } from "./issue-reference"; + +type TreeNode = { type: string; value?: string; url?: string; children?: TreeNode[] }; + +function paragraph(value: string): TreeNode { + return { type: "root", children: [{ type: "paragraph", children: [{ type: "text", value }] }] }; +} + +function paragraphChildren(tree: TreeNode): TreeNode[] { + return tree.children?.[0]?.children ?? []; +} describe("issue-reference", () => { it("extracts issue ids from company-scoped issue paths", () => { @@ -66,4 +76,74 @@ describe("issue-reference", () => { expect(parseIssueReferenceFromHref("/issues/:id")).toBeNull(); expect(parseIssueReferenceFromHref("http://localhost:3100/api/issues/:id")).toBeNull(); }); + + describe("known-prefix gating", () => { + it("links a bare identifier whose prefix is known", () => { + expect(parseIssueReferenceFromHref("PAP-1271", new Set(["PAP"]))).toEqual({ + issuePathId: "PAP-1271", + href: "/issues/PAP-1271", + }); + }); + + it("matches the prefix case-insensitively", () => { + expect(parseIssueReferenceFromHref("pap-12", new Set(["PAP"]))).toEqual({ + issuePathId: "PAP-12", + href: "/issues/PAP-12", + }); + }); + + it("does not link a bare identifier whose prefix is unknown (e.g. a Jira key)", () => { + expect(parseIssueReferenceFromHref("JIRA-456", new Set(["PAP"]))).toBeNull(); + }); + + it("stays permissive when no prefix set is supplied", () => { + expect(parseIssueReferenceFromHref("FOO-1")).toEqual({ + issuePathId: "FOO-1", + href: "/issues/FOO-1", + }); + }); + + it("stays permissive when the prefix set is empty", () => { + expect(parseIssueReferenceFromHref("FOO-1", new Set())).toEqual({ + issuePathId: "FOO-1", + href: "/issues/FOO-1", + }); + }); + + it("never gates explicit issue:// scheme references", () => { + expect(parseIssueReferenceFromHref("issue://ACME-9", new Set(["PAP"]))).toEqual({ + issuePathId: "ACME-9", + href: "/issues/ACME-9", + }); + }); + + it("never gates explicit /issues/ path references", () => { + expect(parseIssueReferenceFromHref("/ACME/issues/ACME-9", new Set(["PAP"]))).toEqual({ + issuePathId: "ACME-9", + href: "/issues/ACME-9", + }); + }); + }); + + describe("remarkLinkIssueReferences", () => { + it("links only known-prefix tokens and leaves foreign keys as text", () => { + const tree = paragraph("See PAP-1 and JIRA-2 today."); + remarkLinkIssueReferences({ knownPrefixes: ["PAP"] })(tree); + + const children = paragraphChildren(tree); + expect(children).toEqual([ + { type: "text", value: "See " }, + { type: "link", url: "/issues/PAP-1", children: [{ type: "text", value: "PAP-1" }] }, + { type: "text", value: " and JIRA-2 today." }, + ]); + }); + + it("links every identifier when no prefixes are supplied (legacy permissive)", () => { + const tree = paragraph("See PAP-1 and JIRA-2."); + remarkLinkIssueReferences()(tree); + + const links = paragraphChildren(tree).filter((node) => node.type === "link"); + expect(links.map((node) => node.url)).toEqual(["/issues/PAP-1", "/issues/JIRA-2"]); + }); + }); }); diff --git a/ui/src/lib/issue-reference.ts b/ui/src/lib/issue-reference.ts index 89c1a61d..7859a986 100644 --- a/ui/src/lib/issue-reference.ts +++ b/ui/src/lib/issue-reference.ts @@ -23,7 +23,10 @@ export function parseIssuePathIdFromPath(pathOrUrl: string | null | undefined): return BARE_ISSUE_IDENTIFIER_RE.test(issuePathId) ? issuePathId.toUpperCase() : issuePathId; } -export function parseIssueReferenceFromHref(href: string | null | undefined) { +export function parseIssueReferenceFromHref( + href: string | null | undefined, + knownPrefixes?: Set, +) { if (!href) return null; const trimmed = href.trim(); const issueSchemeMatch = trimmed.match(ISSUE_SCHEME_RE); @@ -45,6 +48,15 @@ export function parseIssueReferenceFromHref(href: string | null | undefined) { if (!BARE_ISSUE_IDENTIFIER_RE.test(trimmed)) return null; const normalized = trimmed.toUpperCase(); + // Only auto-link a bare IDENT-123 token when its prefix belongs to a known + // company. An empty or omitted set means "prefixes unknown" -> stay permissive + // (preserves behavior during initial load and in provider-less render + // surfaces). The issue:// scheme and /issues/ path forms handled above are + // never gated -- they are deliberate references, not accidental foreign keys. + if (knownPrefixes && knownPrefixes.size > 0) { + const prefix = normalized.split("-")[0]; + if (!prefix || !knownPrefixes.has(prefix)) return null; + } return { issuePathId: normalized, href: `/issues/${encodeURIComponent(normalized)}`, @@ -83,7 +95,7 @@ function createIssueLinkNode(value: string, href: string, childType: "text" | "i }; } -function linkifyIssueReferencesInText(value: string): MarkdownNode[] | null { +function linkifyIssueReferencesInText(value: string, knownPrefixes?: Set): MarkdownNode[] | null { const nodes: MarkdownNode[] = []; let cursor = 0; let matched = false; @@ -95,7 +107,7 @@ function linkifyIssueReferencesInText(value: string): MarkdownNode[] | null { const start = match.index ?? 0; const end = start + raw.length; const { core, trailing } = splitTrailingPunctuation(raw); - const issueRef = parseIssueReferenceFromHref(core); + const issueRef = parseIssueReferenceFromHref(core, knownPrefixes); if (!issueRef) continue; matched = true; @@ -116,7 +128,7 @@ function linkifyIssueReferencesInText(value: string): MarkdownNode[] | null { return nodes; } -function rewriteMarkdownTree(node: MarkdownNode) { +function rewriteMarkdownTree(node: MarkdownNode, knownPrefixes?: Set) { if (!Array.isArray(node.children) || node.children.length === 0) return; if (node.type === "link" || node.type === "linkReference" || node.type === "code" || node.type === "definition" || node.type === "html") { return; @@ -125,7 +137,7 @@ function rewriteMarkdownTree(node: MarkdownNode) { const nextChildren: MarkdownNode[] = []; for (const child of node.children) { if (child.type === "inlineCode" && typeof child.value === "string") { - const issueRef = parseIssueReferenceFromHref(child.value); + const issueRef = parseIssueReferenceFromHref(child.value, knownPrefixes); if (issueRef) { nextChildren.push(createIssueLinkNode(child.value, issueRef.href, "inlineCode")); continue; @@ -133,21 +145,35 @@ function rewriteMarkdownTree(node: MarkdownNode) { } if (child.type === "text" && typeof child.value === "string") { - const linked = linkifyIssueReferencesInText(child.value); + const linked = linkifyIssueReferencesInText(child.value, knownPrefixes); if (linked) { nextChildren.push(...linked); continue; } } - rewriteMarkdownTree(child); + rewriteMarkdownTree(child, knownPrefixes); nextChildren.push(child); } node.children = nextChildren; } -export function remarkLinkIssueReferences() { +export interface RemarkLinkIssueReferencesOptions { + /** + * Company issue prefixes that are eligible for auto-linking. When provided + * and non-empty, a bare IDENT-123 token only becomes an issue link if its + * prefix is in this set -- this keeps foreign tracker keys (e.g. a Jira + * "TREE-604") from linking to non-existent Paperclip issues. Omit or pass an + * empty list to keep the legacy permissive behavior (link any IDENT-123). + */ + knownPrefixes?: string[]; +} + +export function remarkLinkIssueReferences(options?: RemarkLinkIssueReferencesOptions) { + const knownPrefixes = options?.knownPrefixes && options.knownPrefixes.length > 0 + ? new Set(options.knownPrefixes.map((prefix) => prefix.toUpperCase())) + : undefined; return (tree: MarkdownNode) => { - rewriteMarkdownTree(tree); + rewriteMarkdownTree(tree, knownPrefixes); }; }