chore(webapp): drop the comments the code already says

Author: kathiekiwi

apps/webapp/app/components/dashboard-agent/DashboardAgentMessages.tsx

@@ -97,14 +97,7 @@ export function winningInvestigationOccurrences(messages: UIMessage[]): Map<stri
   return new Map([...best.entries()].map(([id, w]) => [id, w.occurrence]));
 }
 
-/**
- * The winners map, with a stable identity while the winners hold.
- *
- * The recompute itself still runs on every streamed token — `messages` is a fresh
- * array each time the stream appends — so this doesn't save the walk. What it saves
- * is handing a fresh `Map` to the memoized turns, which would re-render the whole
- * transcript per token even though nothing about the winners moved.
- */
+// The stable identity is the point: a fresh `Map` re-renders the whole transcript per token.
 function useInvestigationWinners(messages: UIMessage[]): Map<string, string> {
   const previous = useRef<Map<string, string>>();
   const next = useMemo(() => winningInvestigationOccurrences(messages), [messages]);

apps/webapp/app/components/dashboard-agent/investigation-winners.ts

@@ -1,11 +1,3 @@
-/**
- * Identity handling for the investigation winners map (see
- * `winningInvestigationOccurrences` in `DashboardAgentMessages.tsx`).
- *
- * Kept free of component imports so it stays testable on its own.
- */
-
-/** Content equality, so a recompute that changed nothing can be thrown away. */
 export function sameOccurrences(a: Map<string, string>, b: Map<string, string>): boolean {
   if (a.size !== b.size) return false;
   for (const [id, occurrence] of a) {
@@ -14,7 +6,6 @@ export function sameOccurrences(a: Map<string, string>, b: Map<string, string>):
   return true;
 }
 
-/** Returns `previous` when the winners are unchanged, so the reference is reusable. */
 export function reuseWinners(
   previous: Map<string, string> | undefined,
   next: Map<string, string>

apps/webapp/app/components/dashboard-agent/model-markdown.ts

@@ -1,35 +1,19 @@
-/**
- * Model-authored markdown, made safe to render.
- *
- * An image reference in model output is a beacon: the browser fetches the URL as
- * soon as the message renders, so anything the model can put in the query string
- * leaves the page. A host allow-list still leaves that channel open, so no image
- * is rendered at all — the alt text stays as plain prose.
- */
+// No model-supplied image is rendered at all: the browser fetches the URL on render, so any
+// URL the model controls exfiltrates the page. Alt text is re-emitted as plain prose.
 
-/** Inline `![alt](url)` and reference `![alt][ref]` images. */
 const MARKDOWN_IMAGE = /!\[([^\]]*)\]\s*(?:\([^)]*\)|\[[^\]]*\])/g;
 
-/** Bare `![alt]` — a shortcut reference image, its definition elsewhere. */
 const MARKDOWN_SHORTCUT_IMAGE = /!\[([^\]]*)\]/g;
 
-/**
- * Tags that fetch a URL on render, closing bracket optional: an unterminated tag
- * still parses as an element in the browser.
- */
+// Closing bracket optional: an unterminated tag still parses as an element in the browser.
 const FETCHING_TAG =
   /<\s*\/?\s*(?:img|image|picture|source|srcset|svg|use|embed|object|iframe|frame|video|audio|track|link|input|script|style|base)\b[^>]*>?/gi;
 
-/** Alt text is re-emitted as prose, so it must not itself become markup. */
 function plainAlt(alt: string): string {
   return alt.replace(/[![\]<>`]/g, "").trim();
 }
 
-/**
- * Strip every image construct, everywhere — including inside code fences. A
- * fence-aware pass would be the bypass: a crafted half-fence makes the parser
- * and the renderer disagree about what is code.
- */
+// Strips inside code fences too: a fence-aware pass is bypassable with a half-fence.
 export function stripModelImages(text: string): string {
   return text
     .replace(MARKDOWN_IMAGE, (_whole, alt: string) => plainAlt(alt))

apps/webapp/app/routes/api.v1.dashboard-agent.alerts.$channelId.ts

@@ -7,8 +7,7 @@ import { authenticateUatOrApiRequest } from "~/services/uatRoutePreamble.server"
 
 /**
  * `DELETE /api/v1/dashboard-agent/alerts/:channelId` — stop alerting this channel
- * when a watch fires. The channel is looked up scoped to the chat's project, the caller's
- * organization and the caller's own address.
+ * when a watch fires. The channel is looked up scoped to the chat's project.
  */
 
 const ParamsSchema = z.object({ channelId: z.string().min(1) });
@@ -74,8 +73,7 @@ export async function action({ request, params }: ActionFunctionArgs) {
 
     const result = await unsubscribeChannelFromWatchAlerts(parsedParams.data.channelId, {
       projectId: context.environment.project.id,
-      // A project is shared by every member, so the owner is part of the scope: the agent
-      // may only turn off the alerts the caller's own address subscribed.
+      // A project is shared by every member, so the caller's own address is part of the scope.
       organizationId: context.environment.organizationId,
       ownerUserId: userId,
     });

apps/webapp/app/routes/api.v1.dashboard-agent.watches.$watchId.fired.ts

@@ -82,8 +82,6 @@ export async function action({ request, params }: ActionFunctionArgs) {
       );
     }
 
-    // The durable marker, keyed on this watch's terminal outcome: a token holder can call
-    // this as often as they like, and only the first call sends an alert.
     const claimed = await claimWatchAlertDispatch(dashboardAgentDb, {
       id: watch.id,
       terminalStatus: "fired",
@@ -96,7 +94,6 @@ export async function action({ request, params }: ActionFunctionArgs) {
     try {
       await enqueueWatchFiredAlert(watch, "fired");
     } catch (error) {
-      // Nothing was queued, so the claim goes back rather than muting the alert for good.
       await releaseWatchAlertDispatch(dashboardAgentDb, { id: watch.id, terminalStatus: "fired" });
       throw error;
     }

apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.dashboard-agent.in.$.ts

@@ -32,10 +32,8 @@ const FORWARDED_HEADERS = [
   "x-trigger-branch",
 ];
 
-// The only turn metadata a browser may set. Everything else the agent reads — identity, tenancy,
-// the delegated token, the eval opt-out's inputs — is injected server-side, so a client-sent copy
-// is dropped rather than merged. A whitelist, not a deny-list: a field added to the agent's
-// clientData is server-owned until it is listed here on purpose.
+// The only turn metadata a browser may set: everything else the agent reads is injected
+// server-side. A whitelist — a new clientData field is server-owned until listed here on purpose.
 const CLIENT_METADATA_KEYS = ["currentPage", "pageContext"] as const;
 
 export function pickAgentClientMetadata(
@@ -120,8 +118,6 @@ export async function action({ request, params }: ActionFunctionArgs) {
         return tooLarge();
       }
       parsed.payload.metadata = {
-        // Whitelisted: only the page context the browser is allowed to set survives, so it can
-        // neither overwrite nor smuggle in any of the server-owned fields below.
         ...pickAgentClientMetadata(parsed.payload.metadata),
         userActorToken: await mintDashboardAgentUserActorToken(user.id, {
           environmentId: runtimeEnv.id,

apps/webapp/app/services/dashboardAgentWatchAlerts.server.ts

@@ -154,11 +154,7 @@ export async function canUseDashboardAgentEmailAlerts(
   return { allowed: true };
 }
 
-/**
- * The dedup key a user's own watch-alert channel is created under. A channel has no owner
- * column, so this key is the only thing that says whose channel it is — the subscribe and
- * the unsubscribe must derive it the same way.
- */
+// A channel has no owner column, so this key is the only record of whose channel it is.
 export function watchAlertDeduplicationKey(email: string): string {
   return `dashboard-agent-watch:${email}`;
 }
@@ -216,17 +212,14 @@ const UNSUBSCRIBE_ATTEMPTS = 3;
  * Take `DASHBOARD_AGENT_WATCH` off a channel, disabling one left with no alert types. The
  * write is conditional on the list the read saw, so a concurrent edit fails this attempt.
  *
- * A project is not a tenant: every member can see it, so `projectId` alone would let one
- * member turn off another member's alerts. `organizationId` and `ownerUserId` are the
- * scope a request-driven caller must pass.
+ * A project is shared by every member, so a request-driven caller must pass
+ * `organizationId` and `ownerUserId` too.
  */
 export async function unsubscribeChannelFromWatchAlerts(
   channelId: string,
   options: { projectId?: string; organizationId?: string; ownerUserId?: string } = {},
   db: PrismaClientOrTransaction = prisma
 ): Promise<UnsubscribeResult> {
-  // The owner is not a column: the channel's dedup key carries the address it was created
-  // for, so it is what scopes this to the caller's own channel.
   let ownerKey: string | undefined;
   if (options.ownerUserId) {
     const owner = await db.user.findFirst({
@@ -260,8 +253,8 @@ export async function unsubscribeChannelFromWatchAlerts(
     );
 
     const { count } = await db.projectAlertChannel.updateMany({
-      // Compare-and-swap on the row the scoped read returned. Scalars only: `updateMany`
-      // takes no relation filter, so the org scope is carried by the read's `projectId`.
+      // Compare-and-swap on the row the scoped read returned. `updateMany` takes no relation
+      // filter, so the org scope is carried by the read's `projectId`.
       where: {
         id: channelId,
         projectId: channel.projectId,

apps/webapp/app/services/routeBuilders/apiBuilder.server.ts

@@ -465,16 +465,12 @@ export function createLoaderApiRoute<
   };
 }
 
-// What the request targets, resolved from its params. `environmentId` is checked against a
-// user-actor token's environment claim, so an env-scoped route enforces the scope by declaring it.
+// `environmentId` is checked against a user-actor token's environment claim, so an env-scoped
+// route enforces the scope by declaring it here.
 type PATRouteContext = { organizationId?: string; projectId?: string; environmentId?: string };
 
-/**
- * The verified claims of the presented user-actor token.
- *
- * The controller returns them, but a plugin built against an older contract may not — in that case
- * verify the token here rather than continue with no environment scope to enforce.
- */
+// Fail closed: a plugin built against an older contract returns no claims, so verify here rather
+// than continue with no environment scope to enforce.
 async function resolveUserActorClaims(
   claims: UserActorClaims | undefined,
   bearer: string
@@ -662,7 +658,6 @@ export function createLoaderPATApiRoute<
             corsStrategy !== "none"
           );
         }
-        // The token's environment scope is enforced against what the URL targets.
         await assertUserActorScope(claims, ctx);
         authenticationResult = { userId: uatAuth.userId, userActor: claims };
         ability = uatAuth.ability;