@bevel-software/platform-core-backend 0.32.0 → 0.33.0

package/src/modules/workflow/agent-tools/__tests__/update-change-request.parity.test.ts

@@ -0,0 +1,306 @@
+import type { Server as HttpServer } from 'node:http';
+import express from 'express';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import type { IWorkflowService } from '@bevel-software/platform-shared';
+import { testKbContext } from '../../../../__tests__/kb-context.js';
+import { ToolRegistry } from '../../../tool-registry/tool-registry.js';
+import { InternalTokenService } from '../../../tool-auth/internal-token.service.js';
+import { createToolAuthMiddleware } from '../../../tool-auth/tool-auth.middleware.js';
+import { createToolContextResolver } from '../../../tool-helpers/tool-context.js';
+import { createToolHandlerFactory } from '../../../tool-helpers/tool-handler.js';
+import { WorkflowDomainError } from '../../../../shared/domain-errors.js';
+import type { IAccessControl } from '../../../access/access-control.interface.js';
+import type { AuthService } from '../../../auth/auth.service.js';
+import type { WorkspaceService } from '../../../workspace/workspace.service.js';
+import type { WorkflowEventBus } from '../../event-bus.js';
+import { createWorkflowRoutes } from '../../workflow.routes.js';
+import { registerWorkflowTools } from '../workflow.tools.js';
+
+/**
+ * The app's `PATCH /api/workflow/change-requests/:number` and the agent's
+ * `update_change_request` are one verb: both reach the SAME service method
+ * with the same caller and the same fields, and every refusal it makes reaches
+ * both callers with the same status and the same words. The rule itself is
+ * pinned in `workflow.service.update-change-request.test.ts`; this pins that
+ * neither surface narrows, widens or rewords it.
+ *
+ * One answer differs, and on purpose: a request the caller may not READ is
+ * not found to the agent (404, as `get_change_request` answers it), before
+ * its state or the edit rule is consulted. The app serves every request's
+ * detail to any signed-in viewer, so its route has nothing to hide.
+ */
+
+const CALLER = { id: 'user-A', email: 'alice@example.com', name: 'Alice' };
+
+let calls: unknown[][] = [];
+/** What the shared service does next: answer the request, or refuse. */
+let outcome: () => unknown;
+/** `get_change_request`'s visibility gate, as the tool is handed it. */
+let maySee: (number: number) => Promise<boolean>;
+
+const updated = {
+  number: 9,
+  url: 'https://bevel.example.com/change-requests/9',
+  title: 'New title',
+  state: 'open',
+  touchedNodePaths: ['Docs/a.md'],
+};
+
+const workflowService = {
+  updateChangeRequest: async (number: number, user: { id: string; email: string }, input: unknown) => {
+    calls.push(['updateChangeRequest', number, user.id, input]);
+    return outcome();
+  },
+} as unknown as IWorkflowService;
+
+const authService = { getUserById: async () => CALLER } as unknown as AuthService;
+const workspaceService = {
+  getOrCreateForUser: async () => ({ id: 'ws' }),
+  findAnyWorkspaceId: async () => 'ws',
+} as unknown as WorkspaceService;
+const events = { emit: () => ({}) } as unknown as WorkflowEventBus;
+const internalToken = new InternalTokenService({ secret: 's' });
+
+let httpServer: HttpServer | undefined;
+/** The agent tools `start` registered, as the manual lists them. */
+let registry: ToolRegistry;
+
+async function start(): Promise<string> {
+  const app = express();
+  app.use(express.json());
+
+  // The app's route, signed in as CALLER.
+  const appRouter = express.Router();
+  appRouter.use((req, _res, next) => {
+    (req as unknown as { userId: string }).userId = CALLER.id;
+    next();
+  });
+  appRouter.use(
+    createWorkflowRoutes(
+      workflowService,
+      workspaceService,
+      authService,
+      events,
+      { canReadBatch: async () => new Map() } as unknown as IAccessControl,
+      'knowledge-base',
+    ),
+  );
+
+  // The agent's tool, as CALLER over an internal token.
+  registry = new ToolRegistry();
+  const toolRouter = express.Router();
+  const toolAuth = createToolAuthMiddleware(
+    { looksLikeExternalApiKey: () => false, verifyAndLoadToken: async () => null } as never,
+    internalToken,
+  );
+  const resolve = createToolContextResolver({
+    authService,
+    workspaceService,
+    workflowService,
+    events,
+    kbDirName: 'knowledge-base',
+    creatorAccess: { planForCreate: async () => null, grantInExtractedFile: async () => null, noteAccessFileWritten: () => {} },
+  } as never);
+  registerWorkflowTools(registry, toolRouter, toolAuth, createToolHandlerFactory(resolve), testKbContext(), async (_ctx, number) =>
+    maySee(number),
+  );
+
+  app.use('/api', toolRouter);
+  app.use('/api', appRouter);
+  httpServer = await new Promise<HttpServer>((r) => {
+    const s = app.listen(0, () => r(s));
+  });
+  return `http://127.0.0.1:${(httpServer.address() as { port: number }).port}`;
+}
+
+async function viaRoute(base: string, body: Record<string, unknown>) {
+  const res = await fetch(`${base}/api/workflow/change-requests/9`, {
+    method: 'PATCH',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  return { status: res.status, body: (await res.json()) as Record<string, unknown> };
+}
+
+async function viaTool(base: string, body: Record<string, unknown>) {
+  const res = await fetch(`${base}/api/agent/tools/update_change_request`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${internalToken.mint({ userId: CALLER.id })}` },
+    body: JSON.stringify({ number: 9, ...body }),
+  });
+  return { status: res.status, body: (await res.json()) as Record<string, unknown> };
+}
+
+beforeEach(() => {
+  calls = [];
+  outcome = () => updated;
+  maySee = async () => true;
+});
+afterEach(async () => {
+  if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
+  httpServer = undefined;
+});
+
+describe('update_change_request ⇔ PATCH /workflow/change-requests/:number', () => {
+  it('both hand the same service call the same caller and the same fields', async () => {
+    const base = await start();
+    const fields = { title: 'New title', description: 'P2 - Planned\n\nWhy.' };
+    expect((await viaRoute(base, fields)).status).toBe(200);
+    expect((await viaTool(base, fields)).status).toBe(200);
+    expect(calls).toEqual([
+      ['updateChangeRequest', 9, CALLER.id, fields],
+      ['updateChangeRequest', 9, CALLER.id, fields],
+    ]);
+  });
+
+  it('a description alone reaches the service as a description alone, from both', async () => {
+    const base = await start();
+    await viaRoute(base, { description: 'Only this.' });
+    await viaTool(base, { description: 'Only this.' });
+    expect(calls).toEqual([
+      ['updateChangeRequest', 9, CALLER.id, { title: undefined, description: 'Only this.' }],
+      ['updateChangeRequest', 9, CALLER.id, { title: undefined, description: 'Only this.' }],
+    ]);
+  });
+
+  it('an append reaches the service as an append, from both — the tool offers the field the route takes', async () => {
+    const base = await start();
+    expect((await viaRoute(base, { appendDescription: 'Round two.' })).status).toBe(200);
+    expect((await viaTool(base, { appendDescription: 'Round two.' })).status).toBe(200);
+    expect(calls).toEqual([
+      ['updateChangeRequest', 9, CALLER.id, { title: undefined, description: undefined, appendDescription: 'Round two.' }],
+      ['updateChangeRequest', 9, CALLER.id, { title: undefined, description: undefined, appendDescription: 'Round two.' }],
+    ]);
+  });
+
+  it("the tool's input schema names every field the route takes", async () => {
+    await start();
+    const tool = (await registry.listInternal()).find((t) => t.name === 'update_change_request');
+    // The catalog nests a tool's arguments under `body`.
+    const top = (tool?.inputs as { properties: Record<string, { properties?: Record<string, unknown> }> }).properties;
+    const props = top.body?.properties ?? top;
+    expect(Object.keys(props).sort()).toEqual(['appendDescription', 'description', 'number', 'title']);
+  });
+
+  const refusals: [string, () => never][] = [
+    [
+      'neither the author nor someone who may merge it (403)',
+      () => {
+        throw new WorkflowDomainError(
+          "Only the request's author, an admin, or someone who may approve every file it changes can edit its title and description.",
+          403,
+        );
+      },
+    ],
+    [
+      'a merged request (409)',
+      () => {
+        throw new WorkflowDomainError(
+          'This change request has already been applied; its title and description can no longer be changed.',
+          409,
+        );
+      },
+    ],
+    [
+      'a closed request (409)',
+      () => {
+        throw new WorkflowDomainError(
+          'This change request is closed; its title and description can no longer be changed.',
+          409,
+        );
+      },
+    ],
+  ];
+
+  for (const [name, refuse] of refusals) {
+    it(`refuses ${name} with the same status and the same words`, async () => {
+      const base = await start();
+      outcome = refuse;
+      const route = await viaRoute(base, { title: 'New title' });
+      const tool = await viaTool(base, { title: 'New title' });
+      expect(route.status).toBeGreaterThanOrEqual(400);
+      expect(tool).toEqual(route);
+      expect(typeof route.body.error).toBe('string');
+      expect((route.body.error as string).length).toBeGreaterThan(20);
+    });
+  }
+
+  it('the tool answers a request the caller may not see as not found, whatever its state or the rule would say', async () => {
+    const base = await start();
+    maySee = async () => false;
+    for (const [, refuse] of refusals) {
+      outcome = refuse;
+      const tool = await viaTool(base, { title: 'New title' });
+      expect(tool).toEqual({ status: 404, body: { error: 'Change request #9 not found.' } });
+    }
+    expect(calls).toEqual([]);
+  });
+
+  it('the tool answers the request’s link and its title; the route the request', async () => {
+    const base = await start();
+    const tool = await viaTool(base, { title: 'New title' });
+    expect(tool.body).toEqual({
+      number: 9,
+      url: 'https://bevel.example.com/change-requests/9',
+      title: 'New title',
+    });
+    const route = await viaRoute(base, { title: 'New title' });
+    expect(route.body).toMatchObject({ number: 9, title: 'New title' });
+  });
+
+  it('asks for something to change before reaching the service', async () => {
+    const base = await start();
+    const tool = await viaTool(base, {});
+    expect(tool.status).toBe(400);
+    expect(calls).toEqual([]);
+  });
+
+  it('the route refuses a non-string field before reaching the service', async () => {
+    const base = await start();
+    const route = await viaRoute(base, { title: 7 });
+    expect(route.status).toBe(400);
+    expect(calls).toEqual([]);
+  });
+});
+
+/**
+ * The comment system is gone: no screen ever showed a comment, so the routes,
+ * the service methods, the storage and the two agent tools were removed
+ * rather than surfaced. Its old addresses answer 404 and its tools are not
+ * offered; the request itself still answers on its own address.
+ */
+describe('change-request comments are gone', () => {
+  const routes: [string, string][] = [
+    ['GET', '/api/workflow/change-requests/9/comments'],
+    ['POST', '/api/workflow/change-requests/9/comments'],
+    ['PATCH', '/api/workflow/change-requests/9/comments/00000000-0000-4000-8000-000000000000'],
+    ['DELETE', '/api/workflow/change-requests/9/comments/00000000-0000-4000-8000-000000000000'],
+  ];
+  for (const [method, path] of routes) {
+    it(`${method} ${path.replace('/api', '')} answers 404`, async () => {
+      const base = await start();
+      const res = await fetch(`${base}${path}`, {
+        method,
+        headers: { 'content-type': 'application/json' },
+        ...(method === 'GET' || method === 'DELETE' ? {} : { body: JSON.stringify({ body: 'hi' }) }),
+      });
+      expect(res.status).toBe(404);
+      expect(calls).toEqual([]);
+    });
+  }
+
+  it('the agent is offered no comment tool, and calling one answers 404', async () => {
+    const base = await start();
+    for (const name of ['post_change_request_comment']) {
+      const res = await fetch(`${base}/api/agent/tools/${name}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', authorization: `Bearer ${internalToken.mint({ userId: CALLER.id })}` },
+        body: JSON.stringify({ number: 9, body: 'hi' }),
+      });
+      expect(res.status).toBe(404);
+    }
+    const names = (await registry.listInternal()).map((t) => t.name);
+    expect(names).toContain('update_change_request');
+    expect(names.filter((n) => n.includes('comment'))).toEqual([]);
+  });
+});

package/src/modules/workflow/agent-tools/__tests__/workflow.tools.test.ts

@@ -72,7 +72,6 @@ function detailOf(files: Record<string, unknown>[]): Record<string, unknown> {
     headSha: 'head-1',
     baseSha: 'base-1',
     files,
-    comments: [],
     approvals: files.map((f) => approvalOf(f.path as string)),
     mergeableInBevel: false,
     mergeBlockedReasons: files.map((f) => `${f.path as string} is not approved`),
@@ -94,8 +93,6 @@ const externalApiKeyService = {
     t === 'bevel_key' ? { user: { id: 'user-A', email: 'e@x', name: 'N' }, tokenId: 'tok' } : null,
 } as never;
 const authService = { getUserById: async (id: string) => ({ id, email: 'e@x', name: 'N' }) } as never;
-/** A declined change request: no sha records what it proposed, so it has no head. */
-const DECLINED_CR = 21;
 
 const workspaceService = {
   getOrCreateForUser: async () => ({ id: WS }),
@@ -129,15 +126,12 @@ const workflowService = {
   releaseLock: async (ws: string, branch: string, path: string) => {
     calls.push(['releaseLock', ws, branch, path]);
   },
-  // #21 is DECLINED: the service reads such a row from nothing (no sha records
-  // what it proposed), so its detail carries no head — which is what the comment
-  // tool has to anchor to. Every other number is an ordinary open request.
   getChangeRequestDetail: async (number: number) => ({
     number,
     url: `https://bevel.example.com/change-requests/${number}`,
-    headSha: number === DECLINED_CR ? '' : 'head-1',
+    headSha: 'head-1',
     approvals: [],
-    state: number === DECLINED_CR ? 'closed' : 'open',
+    state: 'open',
     title: 'T',
     base: 'main',
   }),
@@ -181,10 +175,6 @@ const workflowService = {
     }
     return { kind: 'deleted', branch: name, lastCommit: 'tip-1', discardedCommits: name === 'me/unmerged' ? 3 : 0 };
   },
-  postComment: async (number: number, _user: unknown, input: { path?: string }) => {
-    calls.push(['postComment', number, input.path]);
-    return { id: 'c-1' };
-  },
   // The history and syncing reads, answered from a fixed script.
   listChangesForFile: async (ws: string, path: string, limit?: number) => {
     calls.push(['listChangesForFile', ws, path, limit]);
@@ -373,51 +363,6 @@ describe('registerWorkflowTools', () => {
     expect(calls).toContainEqual(['commitChange', WS, 'user-A', { summary: 'fix typo', description: undefined }]);
   });
 
-  // A change request's files are repository-relative; the Copy path form
-  // carries the clone folder, which is dropped so the comment lands on the file.
-  it('post_change_request_comment anchors a copied workspace path to the repository-relative file', async () => {
-    const base = await start();
-    for (const path of ['/knowledge-base/KnowledgeBase/Foo.md', 'knowledge-base/KnowledgeBase/Foo.md', 'KnowledgeBase/Foo.md']) {
-      const res = await post(`${base}/api/agent/tools/post_change_request_comment`, writeTok(), { number: 3, body: 'hi', path });
-      expect(res.status, path).toBe(200);
-    }
-    expect(calls.filter((c) => c[0] === 'postComment')).toEqual([
-      ['postComment', 3, 'KnowledgeBase/Foo.md'],
-      ['postComment', 3, 'KnowledgeBase/Foo.md'],
-      ['postComment', 3, 'KnowledgeBase/Foo.md'],
-    ]);
-  });
-
-  // An agent hands the change request's link to a person, so the tools that
-  // act on one by number return its `{ number, url }` beside their own payload.
-  it('post_change_request_comment returns the change request link', async () => {
-    const base = await start();
-    const comment = await post(`${base}/api/agent/tools/post_change_request_comment`, writeTok(), { number: 3, body: 'hi' });
-    expect(comment.status).toBe(200);
-    const commentBody = await comment.json();
-    expect(commentBody).toMatchObject({
-      comment: { id: 'c-1' },
-      changeRequest: { number: 3, url: 'https://bevel.example.com/change-requests/3' },
-    });
-    // A configured address yields an absolute link, so no note rides along.
-    expect(commentBody.changeRequest).not.toHaveProperty('urlNote');
-  });
-
-  // A comment anchors to a commit. A declined request records none — nothing
-  // durable says what it proposed, so it is read from nothing and its detail
-  // carries no head. Say so, rather than letting the service's `head sha is
-  // required` come back as a 400 about an argument the caller never passed.
-  it('post_change_request_comment says why a declined request takes no comment', async () => {
-    const base = await start();
-    const res = await post(`${base}/api/agent/tools/post_change_request_comment`, writeTok(), { number: DECLINED_CR, body: 'why was this turned down?' });
-    expect(res.status).toBe(409);
-    expect(((await res.json()) as { error: string }).error).toMatch(
-      new RegExp(`#${DECLINED_CR} is closed and has no commit to anchor a comment to`),
-    );
-    // Nothing was written: the refusal happens before the service is asked.
-    expect(calls.some((c) => c[0] === 'postComment')).toBe(false);
-  });
-
   describe('delete_branch', () => {
     it('is on both catalogs, takes name, dryRun and discardUnmerged, and is a write tool', async () => {
       await start();
@@ -746,6 +691,37 @@ describe('registerWorkflowTools', () => {
       ]);
     });
 
+    it('names each user owner by name, or by email when the name is empty — never a blank string', async () => {
+      const base = await start();
+      opened = detailOf([
+        { path: 'Skills/Owned/SKILL.md', status: 'modified', additions: 1, deletions: 1, isBinary: false, sha: 'b5', rawUrl: 'r5' },
+      ]);
+      // What the resolver hands back for owners `roles.yaml` lists by email:
+      // an empty name. QA saw `users: [""]` here while `mergeBlockedReasons`
+      // named qa-user2@example.com.
+      opened.approvals = [
+        {
+          path: 'Skills/Owned/SKILL.md',
+          eligibleApprovers: {
+            roles: [],
+            users: [
+              { name: '', email: 'qa-user2@example.com' },
+              { name: 'Razvan Radulescu', email: 'razvan.radulescu@bevel.software' },
+              { name: '  ', email: 'qa-user3@example.com' },
+              { name: '', email: '' },
+            ],
+          },
+          approvedBy: [],
+          eligibilityResolved: true,
+          isApproved: false,
+          inMergeGate: true,
+        },
+      ];
+      const [entry] = (await open(base)).approvals as { users: string[] }[];
+      expect(entry.users).toEqual(['qa-user2@example.com', 'Razvan Radulescu', 'qa-user3@example.com']);
+      expect(entry.users.every((u) => u.trim() !== '')).toBe(true);
+    });
+
     it('surfaces the `change-request-conflicts` error as before', async () => {
       const base = await start();
       openFails = new ChangeRequestConflictsError('me/draft', 'target-company-state', ['KnowledgeBase/Clash.md']);

package/src/modules/workflow/agent-tools/change-request-read-shape.ts

@@ -22,8 +22,8 @@
  *     and an agent reading `state` should not have to read a second field to
  *     learn whether the change landed.
  *   - **One name per path.** GitHub names a pull-request file's path `filename`
- *     and a review comment's `path`; mirroring that inconsistency was the point
- *     while these tools wore GitHub's names, and is now just a trap. Every path
+ *     and elsewhere `path`; mirroring that inconsistency was the point while
+ *     these tools wore GitHub's names, and is now just a trap. Every path
  *     in every answer is `path`, and a moved file's old name is `previousPath`,
  *     as `open_change_request` names them.
  *   - **A file's kind of change** is `change` — `added` / `changed` / `deleted`
@@ -37,9 +37,6 @@
  *   - **`stale`, not `DISMISSED`.** Hexis's word for an approval a later push
  *     invalidated is `isStale`; a review entry reports `stale: true` rather
  *     than borrowing GitHub's review state.
- *   - **A reply names its parent `parentId`**, which is the argument
- *     `post_change_request_comment` takes to create one. Reading a comment and
- *     replying to it use the same word for the same thing.
  *
  * The tools' INPUTS are untouched and stay GitHub's (`state`, `head`, `base`,
  * `author`, `per_page`, `page`, `include`): the ticket pins them by name, and
@@ -53,27 +50,26 @@
  * tools file does the IO and calls in here for every decision.
  */
 
-import type {
-  ChangeRequest,
-  ChangeRequestComment,
-  ChangeRequestDetail,
-  ChangeRequestState,
-  ChangedFile,
-  FileApproval,
+import {
+  type ChangeRequest,
+  type ChangeRequestDetail,
+  type ChangeRequestState,
+  type ChangedFile,
+  type FileApproval,
 } from '@bevel-software/platform-shared';
 import { canonicalEmail, hashEmail } from '../../../shared/email-identity.js';
 import { changeKindOf, type ChangeKind } from './change-request-summary.js';
 
-/** A person on a change request, a review or a comment. */
+/** A person on a change request or a review. */
 export interface CrUser {
   /** Hexis's author login — `user-<first 12 of the email hash>`, no raw email. */
   login: string;
   /** Display name, when Hexis knows one. */
   name?: string;
   /**
-   * The person's address, for a comment author and an approver — the two
-   * places the app's own change-request surfaces already show it, and what an
-   * agent needs to address a reply to a reviewer. Never set on a change
+   * The person's address, for an approver — where the app's own
+   * change-request surfaces already show it, and what an agent needs to
+   * reach a reviewer. Never set on a change
    * request's `author`, which carries a hash-derived login only.
    */
   email?: string;
@@ -202,26 +198,6 @@ export interface CrReview {
   withheldFiles: number;
 }
 
-export interface CrComment {
-  id: string;
-  author: CrUser;
-  body: string;
-  /** Set on a file-level or inline comment. */
-  path?: string;
-  /** Set on an inline comment. */
-  line?: number;
-  /**
-   * The comment this one replies to — the same `parentId`
-   * `post_change_request_comment` takes to post the reply.
-   */
-  parentId?: string;
-  /** The head the comment was anchored to. */
-  headSha: string;
-  createdAt: string;
-  /** Present once edited. */
-  updatedAt?: string;
-}
-
 /** One page of a list, and whether there is another. */
 export interface CrPage<T> {
   items: T[];
@@ -374,7 +350,7 @@ export function toCrSummary(
   };
 }
 
-/** A detail: the row, the author's description, and the gate as this caller sees it. */
+/** A detail: the row, its description, and the gate as this caller sees it. */
 export function toCrDetail(
   detail: ChangeRequestDetail,
   counts: { readable: number; withheld: number },
@@ -388,7 +364,10 @@ export function toCrDetail(
     // read as a sha nobody can look up.
     ...(detail.headSha ? { headSha: detail.headSha } : {}),
     ...(detail.baseSha ? { baseSha: detail.baseSha } : {}),
-    body: authorsDescription(detail.body),
+    // The body is the description and nothing else — Hexis writes none of
+    // its own facts into it, so there is nothing to cut and no path in it
+    // that the author did not choose to write about.
+    body: detail.body,
     mergeable: detail.mergeableInBevel,
     mergeBlockedReasons: blockers.visible,
     withheldMergeBlockedReasons: blockers.withheld,
@@ -396,50 +375,6 @@ export function toCrDetail(
   };
 }
 
-/**
- * The part of a change-request body its AUTHOR wrote.
- *
- * A Hexis body is part human and part machine: `openChangeRequest` appends an
- * `## Affected owners` block — one line per changed path, naming that path and
- * its eligible approvers — to whatever the author typed. Returning the body
- * verbatim NAMED every file of the request, including the ones this caller may
- * not read: Local Testing caught a GTM-team reader being handed
- * `- \`KnowledgeBase/Engineering/…\` — Admin` out of a request whose file list
- * had correctly withheld that very path.
- *
- * So the generated block goes, and NOTHING ELSE does. The first cut at this
- * copied the app's dialog, which drops everything from the first `##` heading
- * on; Razvan's review (2026-10-02) asked for the narrower cut, because an
- * author who writes their description in sections loses it from that heading
- * onwards and is never told. The generated block is appended LAST and begins
- * with a line that is exactly `## Affected owners`, so cutting at the LAST such
- * line removes the machinery and keeps every heading a person wrote. (An author
- * who writes that exact heading themselves loses their text from there — the
- * safe direction, and the only way this can err.)
- *
- * Hexis's OWN hidden markers go too — the `<!--hexis:…-->` / `<!--bevel:…-->`
- * comments older bodies carry identity in — and no other comment: an HTML
- * comment the author wrote is the author's prose, like the rest.
- *
- * Who must approve each file is NOT lost by this — it is what
- * `list_change_request_files` answers under `requiredApprovers`, per file and
- * access-filtered, which is where a caller should read it from anyway.
- *
- * Two things this deliberately does not do. It does not vary by caller: one
- * body for everyone is a body nobody has to reason about. And it does not touch
- * the author's own prose, which may mention any path they chose to write about —
- * that is a person's sentence, shown to every viewer in the app, not Hexis
- * naming a file it was asked to withhold.
- */
-export function authorsDescription(body: string): string {
-  const lines = body.split('\n');
-  const generated = lines.lastIndexOf('## Affected owners');
-  return (generated === -1 ? lines : lines.slice(0, generated))
-    .join('\n')
-    .replace(/<!--\s*(?:hexis|bevel)[:/][\s\S]*?-->/g, '')
-    .trim();
-}
-
 /**
  * What this caller may do with the request.
  *
@@ -599,8 +534,7 @@ export function loginFor(email: string): string {
  * readable approvals alone, for the same reason.
  *
  * Hexis records nothing about who DECLINED a request — a rejection closes it
- * and stores no reviewer — so no review entry can report one. A reviewer's
- * objection lives in a comment, which `list_change_request_comments` returns.
+ * and stores no reviewer — so no review entry can report one.
  */
 export function toCrReviews(
   approvals: FileApproval[],
@@ -641,72 +575,3 @@ export function toCrReviews(
     withheldReviews: all.length - reviews.length,
   };
 }
-
-/** A comment. Covers the file-anchored and the general ones — Hexis has one table. */
-export function toCrComment(comment: ChangeRequestComment): CrComment {
-  return {
-    id: comment.id,
-    author: {
-      login: loginFor(comment.author.email),
-      name: comment.author.name,
-      email: comment.author.email,
-    },
-    body: comment.body,
-    ...(comment.path ? { path: comment.path } : {}),
-    ...(comment.line !== undefined ? { line: comment.line } : {}),
-    ...(comment.parentId ? { parentId: comment.parentId } : {}),
-    headSha: comment.headSha,
-    createdAt: comment.createdAt,
-    ...(comment.updatedAt ? { updatedAt: comment.updatedAt } : {}),
-  };
-}
-
-/**
- * The comments the caller may read, replies included in the answer only when
- * the comment they reply to is.
- *
- * A comment with no path is about the request as a whole, and a comment with
- * one is as readable as that path is NAMEABLE here (`mayShow`, so a comment
- * anchored to the new name of a file withheld for its old one goes with the
- * file rather than announcing it). A REPLY is neither, quite: it carries no
- * path of its own when it was posted without one, so judged on itself it is a
- * general comment — and `post_change_request_comment` takes `parentId` without
- * requiring `path`, so a reply to a comment on a withheld file was returned
- * with its body and a `parentId` naming a comment the caller cannot see.
- * Razvan's review (2026-10-02) asked for the rule the ticket states: a reply is
- * shown only when its parent is.
- *
- * So a comment is visible when its OWN path may be shown (if it has one) AND
- * its parent is visible, all the way up the chain. Both halves are needed:
- * inheriting only would show a reply naming a withheld file under a readable
- * parent, and checking only its own path would show it under a withheld one.
- *
- * Fail-closed at the edges. A `parentId` naming a comment that is not in this
- * request's list (deleted, or from somewhere this answer cannot see) is not
- * provably pathless, so the reply goes. A cycle — which the schema does not
- * permit and a corrupted row could still hold — is unresolvable, so it goes
- * too. Both are counted in the withheld total, never named.
- */
-export function visibleComments<T extends { id: string; path?: string; parentId?: string }>(
-  comments: T[],
-  mayShow: (path: string) => boolean,
-): { visible: T[]; withheld: number } {
-  const byId = new Map(comments.map((c) => [c.id, c]));
-  /** Memoised per id, so a long thread costs one walk and not one per reply. */
-  const verdicts = new Map<string, boolean>();
-  const mayShowComment = (comment: T, seen: Set<string>): boolean => {
-    const cached = verdicts.get(comment.id);
-    if (cached !== undefined) return cached;
-    if (seen.has(comment.id)) return false;
-    seen.add(comment.id);
-    let verdict = !comment.path || mayShow(comment.path);
-    if (verdict && comment.parentId) {
-      const parent = byId.get(comment.parentId);
-      verdict = parent !== undefined && mayShowComment(parent, seen);
-    }
-    verdicts.set(comment.id, verdict);
-    return verdict;
-  };
-  const visible = comments.filter((c) => mayShowComment(c, new Set()));
-  return { visible, withheld: comments.length - visible.length };
-}