Merge pull request #2369 from getappmap/feat/sequence-diagram-labels

feat(sequence-diagram): carry AppMap labels on diagram actions

Author: kgilpin

packages/cli/src/cli.ts

@@ -21,6 +21,7 @@ import InstallCommand from './cmds/agentInstaller/install-agent';
 import StatusCommand from './cmds/agentInstaller/status';
 import { default as OpenAPICommand } from './cmds/openapi/openapi';
 import PruneCommand from './cmds/prune/prune';
+import TrimCommand from './cmds/trim/trim';
 import RecordCommand from './cmds/record/record';
 import { handleWorkingDirectory } from './lib/handleWorkingDirectory';
 import { locateAppMapDir } from './lib/locateAppMapDir';
@@ -146,6 +147,7 @@ yargs(process.argv.slice(2))
   .command(SequenceDiagramCommand)
   .command(SequenceDiagramDiffCommand)
   .command(PruneCommand)
+  .command(TrimCommand)
   .command(ArchiveCommand)
   .command(RestoreCommand)
   .command(CompareCommand)

packages/cli/src/cmds/prune/pruneAppMap.ts

@@ -22,6 +22,10 @@ export const pruneAppMap = (appMap: AppMap, size: number): PruneResult => {
   return { appmap };
 };
 
+// Deserializes an untrusted serialized filter (the CLI accepts it as a
+// base64url-encoded string) into an AppMapFilter and applies it to the map.
+// Labeled so appmap-review interprets changes to this deserialization boundary.
+// @label security.deserialization
 export const pruneWithFilter = (appMap: AppMap, serializedFilter: string): PruneResult => {
   // TODO: update type for AppMap
   const fullMap = buildAppMap().source(appMap).normalize().build() as any;

packages/cli/src/cmds/query/lib/recordingId.ts

@@ -34,6 +34,7 @@ import type { AppmapInfo } from '../queries/tree';
 // shapes silently collide in real corpora (multiple recordings share
 // the same basename or name), and the resulting wrong-recording
 // resolution is harder to debug than an explicit error.
+// @label security.path-resolution
 export function resolveAppmapPath(db: sqlite3.Database, ref: unknown): AppmapInfo {
   const s = String(ref);
   if (looksLikeDisplayLabel(s)) {

packages/cli/src/cmds/query/lib/treeRender.ts

@@ -10,6 +10,16 @@ import {
 } from '../queries/tree';
 import { formatCount, formatMs, formatTable } from './format';
 import { projectLogMessage } from './logMessage';
+import {
+  MCP_RETURN_VALUE_BUDGET,
+  truncate,
+  truncateStructValue,
+} from '../../../lib/truncateStructValue';
+import type { StructBudget } from '../../../lib/truncateStructValue';
+
+// Re-exported so existing importers (e.g. treeRender.spec.ts) keep working.
+export { MCP_RETURN_VALUE_BUDGET, truncateStructValue };
+export type { StructBudget };
 
 const INDENT = '  ';
 
@@ -76,10 +86,6 @@ function bracket(ms: number | null): string {
   return ms == null ? '' : `[${formatMs(ms)}]`;
 }
 
-function truncate(s: string, n: number): string {
-  return s.length <= n ? s : s.slice(0, n - 1) + '…';
-}
-
 // Dense one-line-per-event rendering for MCP responses. Each line starts
 // with the event_id (so the agent can drill via find_calls/find_queries)
 // and includes file:line for source-reading without a follow-up call.
@@ -110,127 +116,6 @@ function renderTreeLineForMcp(node: TreeNode): string {
   }
 }
 
-// Return values in the dense MCP tree are truncated value-aware, not by a
-// flat prefix cut. A flat cut wastes the budget on identity fields — a
-// record like `ApprovalRequest[requestId=<uuid>, loanId=<uuid>,
-// status=APPROVED, …]` spends ~80 chars on two UUIDs before reaching the
-// state field that actually distinguishes the call. truncateStructValue
-// parses the struct shape and budgets *per field value*, clipping
-// id/hash-shaped values hard so semantic fields downstream survive.
-export interface StructBudget {
-  perValueCap: number; // max chars for an ordinary field value
-  idCap: number; // max chars for a uuid/hash-shaped value (identity, low signal)
-  maxFields: number; // fields rendered before the tail is elided
-  flatCap: number; // flat cap applied to non-struct strings
-}
-
-export const MCP_RETURN_VALUE_BUDGET: StructBudget = {
-  perValueCap: 48,
-  idCap: 12,
-  maxFields: 16,
-  flatCap: 120,
-};
-
-// A uuid, a hex object hash (`@1a2b3c4`, `0x00007f…`), or either prefixed
-// by a short tag (`LOAN-<uuid>`, `PID-<uuid>`). These are identity, not
-// state — low root-cause signal — so they get the tight idCap.
-const ID_VALUE_RE =
-  /(?:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|(?:@|0x)[0-9a-f]{4,})/i;
-
-const CLOSE_FOR: Record<string, string> = { '[': ']', '{': '}', '(': ')' };
-
-interface Struct {
-  prefix: string; // leading type name (may be empty for a bare collection)
-  open: string; // opening delimiter
-  body: string; // comma-separated field list
-  close: string; // closing delimiter
-}
-
-// Recognize the toString()/repr shapes AppMap captures across the four
-// supported languages:
-//   Java record / Python repr   Type[…]  /  Type(…)
-//   Java bean / JS-ish object   Type{…}  /  {…}
-//   Ruby                        #<Type …>
-// Returns null for primitives, `[object Object]`-style opaque values, and
-// `Type@1a2b3c` hashes — those fall back to a flat truncation.
-function parseStruct(s: string): Struct | null {
-  const ruby = /^#<([^\s>]+)\s+(.+)>$/.exec(s);
-  if (ruby) return { prefix: `#<${ruby[1]} `, open: '', body: ruby[2], close: '>' };
-  const m = /^([A-Za-z_][\w.$]*)?([[{(])([\s\S]*)([\]})])$/.exec(s);
-  if (m && CLOSE_FOR[m[2]] === m[4]) {
-    return { prefix: m[1] ?? '', open: m[2], body: m[3], close: m[4] };
-  }
-  return null;
-}
-
-// Split a struct body on top-level ", ". Commas nested inside [], {}, (),
-// or <> belong to a field's own value and must not split it.
-function splitTopLevelFields(body: string): string[] {
-  if (body.length === 0) return [];
-  const out: string[] = [];
-  let depth = 0;
-  let start = 0;
-  for (let i = 0; i < body.length; i++) {
-    const c = body[i];
-    if (c === '[' || c === '{' || c === '(' || c === '<') depth++;
-    else if (c === ']' || c === '}' || c === ')' || c === '>') depth = Math.max(0, depth - 1);
-    else if (c === ',' && depth === 0 && body[i + 1] === ' ') {
-      out.push(body.slice(start, i));
-      start = i + 2;
-      i++;
-    }
-  }
-  out.push(body.slice(start));
-  return out;
-}
-
-// A field value that is itself a struct (a nested record, or an element
-// of a collection-of-records like `getParticipants`) recurses so its own
-// fields get the per-field budget too — flat-clipping it would collapse
-// `[ParticipantState[…status=PENDING], …]` down to an opaque stub. Depth
-// is bounded so a pathologically deep value can't recurse without end.
-const MAX_STRUCT_DEPTH = 4;
-
-// Truncate one field value: recurse if it is itself a struct, else
-// id/hash-shaped values get the tight idCap and all others the perValueCap.
-function truncateFieldValue(value: string, budget: StructBudget, depth: number): string {
-  if (depth < MAX_STRUCT_DEPTH) {
-    const nested = parseStruct(value);
-    if (nested) return renderStruct(nested, budget, depth + 1);
-  }
-  const cap = ID_VALUE_RE.test(value) ? budget.idCap : budget.perValueCap;
-  return truncate(value, cap);
-}
-
-// Truncate one `name=value` / `name: value` field, keeping the name whole
-// and budgeting only the value. A field with no recognizable name
-// separator (a bare collection element) is budgeted as a whole value.
-function truncateField(field: string, budget: StructBudget, depth: number): string {
-  const m = /^(\s*[\w$]+\s*)([:=])(\s*)([\s\S]*)$/.exec(field);
-  if (!m) return truncateFieldValue(field, budget, depth);
-  return `${m[1]}${m[2]}${m[3]}${truncateFieldValue(m[4], budget, depth)}`;
-}
-
-function renderStruct(st: Struct, budget: StructBudget, depth: number): string {
-  const fields = splitTopLevelFields(st.body);
-  const kept = fields.slice(0, budget.maxFields).map((f) => truncateField(f, budget, depth));
-  const elided = fields.length - kept.length;
-  const tail = elided > 0 ? `${kept.length > 0 ? ', ' : ''}…+${elided} more` : '';
-  return `${st.prefix}${st.open}${kept.join(', ')}${tail}${st.close}`;
-}
-
-// Value-aware truncation for a captured return value / parameter. Parses
-// the struct shape and budgets per field value, recursing into nested
-// structs; non-struct strings fall back to a flat cap. See StructBudget.
-export function truncateStructValue(
-  s: string,
-  budget: StructBudget = MCP_RETURN_VALUE_BUDGET
-): string {
-  const st = parseStruct(s);
-  if (!st) return truncate(s, budget.flatCap);
-  return renderStruct(st, budget, 1);
-}
-
 function renderFunctionForMcp(n: FunctionNode): string {
   const id = n.fqid ?? `${n.defined_class}${n.is_static ? '.' : '#'}${n.method_id}`;
   const where =

packages/cli/src/cmds/trim/trim.ts

@@ -0,0 +1,125 @@
+import { mkdirSync, readFileSync } from 'fs';
+import { basename, dirname, join } from 'path';
+import Yargs from 'yargs';
+
+import { handleWorkingDirectory } from '../../lib/handleWorkingDirectory';
+import { MCP_RETURN_VALUE_BUDGET, truncateStructValue } from '../../lib/truncateStructValue';
+import type { StructBudget } from '../../lib/truncateStructValue';
+import { writeFileAtomic } from '../../utils';
+
+// The captured `value` of a parameter, return value, receiver, or log message.
+interface ValueSlot {
+  value?: unknown;
+}
+
+interface AppMapEvent {
+  parameters?: ValueSlot[];
+  message?: ValueSlot[];
+  receiver?: ValueSlot;
+  return_value?: ValueSlot;
+  exceptions?: ValueSlot[];
+}
+
+interface AppMap {
+  events?: AppMapEvent[];
+}
+
+function trimSlot(slot: ValueSlot | undefined, budget: StructBudget): void {
+  if (slot && typeof slot.value === 'string') {
+    slot.value = truncateStructValue(slot.value, budget);
+  }
+}
+
+// Truncate every captured value string in an AppMap, in place. Trimming only
+// touches `value` strings — the call structure, code objects, SQL, and every
+// other stable property are untouched — so a trimmed AppMap is behaviorally
+// identical (its sequence-diagram digest is unchanged) but much smaller.
+export function trimAppMap(appmap: AppMap, budget: StructBudget = MCP_RETURN_VALUE_BUDGET): AppMap {
+  for (const event of appmap.events ?? []) {
+    for (const p of event.parameters ?? []) trimSlot(p, budget);
+    for (const m of event.message ?? []) trimSlot(m, budget);
+    trimSlot(event.receiver, budget);
+    trimSlot(event.return_value, budget);
+    for (const x of event.exceptions ?? []) trimSlot(x, budget);
+  }
+  return appmap;
+}
+
+export default {
+  command: 'trim <files..>',
+
+  describe:
+    'Shrink AppMaps by truncating captured parameter, return, receiver, and message values',
+
+  builder: (args: Yargs.Argv) => {
+    args.positional('files', {
+      describe: 'AppMap file(s) to trim',
+      type: 'string',
+    });
+
+    args.option('max-length', {
+      describe:
+        'Maximum length of any captured value string — caps flat strings and struct field/id values alike',
+      type: 'number',
+      default: MCP_RETURN_VALUE_BUDGET.flatCap,
+    });
+
+    args.option('output-dir', {
+      describe: 'Write trimmed AppMaps here (default: overwrite each file in place)',
+      type: 'string',
+      alias: 'o',
+    });
+
+    args.option('directory', {
+      describe: 'Working directory for the command',
+      type: 'string',
+      alias: 'd',
+    });
+
+    return args;
+  },
+
+  handler: async (argv: any): Promise<void> => {
+    handleWorkingDirectory(argv.directory);
+
+    // --max-length is a hard cap on every captured value string: it sets the
+    // flat cap and, so the flag means what it says, lowers the per-field and id
+    // caps to match (never above their defaults). maxFields 12 (vs the MCP
+    // renderer's 16) — trim leans slightly more aggressive since a baseline
+    // wants leanness over readability.
+    const maxLength = argv.maxLength as number;
+    const budget: StructBudget = {
+      perValueCap: Math.min(MCP_RETURN_VALUE_BUDGET.perValueCap, maxLength),
+      idCap: Math.min(MCP_RETURN_VALUE_BUDGET.idCap, maxLength),
+      maxFields: 12,
+      flatCap: maxLength,
+    };
+    const files = argv.files as string[];
+    if (argv.outputDir) mkdirSync(argv.outputDir, { recursive: true });
+
+    let failed = 0;
+    for (const file of files) {
+      let before: string;
+      let trimmed: string;
+      try {
+        before = readFileSync(file, 'utf8');
+        trimmed = JSON.stringify(trimAppMap(JSON.parse(before) as AppMap, budget));
+      } catch (error) {
+        // Skip an unreadable/malformed file rather than aborting: one bad file
+        // in a batch must not stop the rest or leave earlier files half-done.
+        failed += 1;
+        console.warn(`trim ${file}: skipped (${(error as Error).message})`);
+        continue;
+      }
+      const outputPath = argv.outputDir ? join(argv.outputDir, basename(file)) : file;
+      // Write atomically (temp file in the same dir, then rename) so an
+      // interrupted or failed write never leaves a partial AppMap in place.
+      await writeFileAtomic(dirname(outputPath), basename(outputPath), 'trim.tmp', trimmed);
+      const pct = Math.round((100 * trimmed.length) / before.length);
+      console.warn(`trim ${file}: ${before.length} -> ${trimmed.length} bytes (${pct}%)`);
+    }
+    if (files.length > 0 && failed === files.length) {
+      throw new Error(`trim: all ${failed} input file(s) failed to process`);
+    }
+  },
+};