@senad-d/observme 0.1.0

package/src/query/tempo.ts

@@ -0,0 +1,332 @@
+import type { ObservMeConfig } from "../config/schema.ts";
+import type { GrafanaFetch, GrafanaTransportClient } from "./grafana-transport.ts";
+import { createGrafanaTransport } from "./grafana-transport.ts";
+import { assertNoSensitiveQueryInput } from "../safety/sensitive-input.ts";
+import { assertGrafanaQueryReady } from "./grafana-readiness.ts";
+import {
+  AGENT_RUN_ATTRIBUTES,
+  AGENT_SPAWN_ATTRIBUTES,
+  AGENT_WAIT_JOIN_ATTRIBUTES,
+  BRANCH_ATTRIBUTES,
+  COMMON_SPAN_ATTRIBUTES,
+  LOG_ATTRIBUTES,
+  RESOURCE_ATTRIBUTES,
+  TOOL_ATTRIBUTES,
+  TURN_ATTRIBUTES,
+} from "../semconv/attributes.ts";
+
+export type TempoFetch = GrafanaFetch;
+
+export interface TimeRange {
+  readonly from: Date;
+  readonly to: Date;
+}
+
+export interface TraceSummary {
+  readonly traceId: string;
+  readonly rootServiceName?: string;
+  readonly rootTraceName?: string;
+  readonly startTimeUnixNano?: string;
+  readonly durationMs?: number;
+  readonly spanSet?: unknown;
+}
+
+export interface TempoQueryClientOptions {
+  readonly fetch?: TempoFetch;
+}
+
+interface NormalizedTempoSearchAttribute {
+  readonly key: string;
+  readonly value: string;
+}
+
+interface NormalizedTimeRange {
+  readonly from: Date;
+  readonly to: Date;
+}
+
+const minimumMaxTraces = 1;
+const maxTempoSearchAttributes = 8;
+const maxTempoSearchAttributeValueLength = 256;
+const safeTempoAttributeKeyPattern = /^[A-Za-z_][A-Za-z0-9_.-]*$/u;
+const safeTempoAttributeValuePattern = /^[A-Za-z0-9._:-]+$/u;
+const hashedAttributeKeyPattern = /(?:\.hash|_hash)$/u;
+const backslashCharacter = String.fromCodePoint(92);
+const generatedCorrelationAttributeKeys = new Set<string>([
+  COMMON_SPAN_ATTRIBUTES.PI_SESSION_ID,
+  COMMON_SPAN_ATTRIBUTES.PI_WORKFLOW_ID,
+  COMMON_SPAN_ATTRIBUTES.PI_WORKFLOW_ROOT_AGENT_ID,
+  COMMON_SPAN_ATTRIBUTES.PI_AGENT_ID,
+  COMMON_SPAN_ATTRIBUTES.PI_AGENT_PARENT_ID,
+  COMMON_SPAN_ATTRIBUTES.PI_AGENT_ROOT_ID,
+  COMMON_SPAN_ATTRIBUTES.PI_AGENT_RUN_ID,
+  COMMON_SPAN_ATTRIBUTES.PI_ENTRY_ID,
+  COMMON_SPAN_ATTRIBUTES.PI_ENTRY_PARENT_ID,
+  RESOURCE_ATTRIBUTES.PI_WORKFLOW_ID,
+  RESOURCE_ATTRIBUTES.PI_WORKFLOW_ROOT_AGENT_ID,
+  RESOURCE_ATTRIBUTES.PI_AGENT_ID,
+  RESOURCE_ATTRIBUTES.PI_AGENT_PARENT_ID,
+  RESOURCE_ATTRIBUTES.PI_AGENT_ROOT_ID,
+  LOG_ATTRIBUTES.PI_SESSION_ID,
+  LOG_ATTRIBUTES.PI_WORKFLOW_ID,
+  LOG_ATTRIBUTES.PI_WORKFLOW_ROOT_AGENT_ID,
+  LOG_ATTRIBUTES.PI_AGENT_ID,
+  LOG_ATTRIBUTES.PI_AGENT_PARENT_ID,
+  LOG_ATTRIBUTES.PI_AGENT_ROOT_ID,
+  LOG_ATTRIBUTES.PI_AGENT_RUN_ID,
+  LOG_ATTRIBUTES.PI_TURN_ID,
+  LOG_ATTRIBUTES.TRACE_ID,
+  LOG_ATTRIBUTES.SPAN_ID,
+  AGENT_RUN_ATTRIBUTES.PI_AGENT_ID,
+  AGENT_RUN_ATTRIBUTES.PI_AGENT_PARENT_ID,
+  AGENT_RUN_ATTRIBUTES.PI_AGENT_ROOT_ID,
+  AGENT_RUN_ATTRIBUTES.PI_AGENT_RUN_ID,
+  AGENT_SPAWN_ATTRIBUTES.PI_AGENT_SPAWN_ID,
+  AGENT_SPAWN_ATTRIBUTES.PI_AGENT_CHILD_ID,
+  AGENT_SPAWN_ATTRIBUTES.PI_AGENT_PARENT_ID,
+  AGENT_SPAWN_ATTRIBUTES.PI_AGENT_ROOT_ID,
+  AGENT_SPAWN_ATTRIBUTES.PI_WORKFLOW_ID,
+  AGENT_SPAWN_ATTRIBUTES.PI_WORKFLOW_ROOT_AGENT_ID,
+  AGENT_SPAWN_ATTRIBUTES.PI_SESSION_ID,
+  AGENT_WAIT_JOIN_ATTRIBUTES.PI_WORKFLOW_ID,
+  AGENT_WAIT_JOIN_ATTRIBUTES.PI_AGENT_ID,
+  AGENT_WAIT_JOIN_ATTRIBUTES.PI_AGENT_CHILD_ID,
+  AGENT_WAIT_JOIN_ATTRIBUTES.PI_AGENT_SPAWN_ID,
+  TURN_ATTRIBUTES.PI_TURN_ID,
+  TOOL_ATTRIBUTES.PI_TOOL_CALL_ID,
+  BRANCH_ATTRIBUTES.PI_BRANCH_FROM_ID,
+  BRANCH_ATTRIBUTES.PI_BRANCH_TO_ID,
+  BRANCH_ATTRIBUTES.PI_BRANCH_COMMON_ANCESTOR_ID,
+  BRANCH_ATTRIBUTES.PI_LEAF_ID,
+]);
+
+export class TempoQueryClient {
+  readonly #config: ObservMeConfig;
+  readonly #transport: GrafanaTransportClient;
+
+  constructor(config: ObservMeConfig, options: TempoQueryClientOptions = {}) {
+    this.#config = config;
+    this.#transport = createGrafanaTransport(config, options);
+  }
+
+  async searchTempo(attrs: Record<string, string>, range: TimeRange): Promise<TraceSummary[]> {
+    return searchTempoWithTransport(this.#config, this.#transport, attrs, range);
+  }
+}
+
+export function createTempoQueryClient(
+  config: ObservMeConfig,
+  options: TempoQueryClientOptions = {},
+): TempoQueryClient {
+  return new TempoQueryClient(config, options);
+}
+
+export async function searchTempo(
+  config: ObservMeConfig,
+  attrs: Record<string, string>,
+  range: TimeRange,
+  options: TempoQueryClientOptions = {},
+): Promise<TraceSummary[]> {
+  return searchTempoWithTransport(config, createGrafanaTransport(config, options), attrs, range);
+}
+
+async function searchTempoWithTransport(
+  config: ObservMeConfig,
+  transport: GrafanaTransportClient,
+  attrs: Record<string, string>,
+  range: TimeRange,
+): Promise<TraceSummary[]> {
+  if (!config.query.enabled) return [];
+
+  assertGrafanaQueryReady(config, "tempo");
+  const searchAttrs = normalizeTempoSearchAttributes(attrs);
+  const timeRange = normalizeTimeRange(range);
+  const maxTraces = resolveMaxTraces(config);
+  const url = createTempoSearchUrl(config, transport, searchAttrs, timeRange, maxTraces);
+  const response = await transport.fetch(url, { timeoutMessage: "Tempo search timed out." });
+
+  return readTempoTraceSummaries(response, transport, maxTraces);
+}
+
+function normalizeTempoSearchAttributes(attrs: Record<string, string>): NormalizedTempoSearchAttribute[] {
+  const entries = Object.entries(attrs);
+  if (entries.length === 0) throw new Error("Tempo search requires at least one safe correlation attribute.");
+  if (entries.length > maxTempoSearchAttributes) throw new Error("Tempo search is bounded to at most 8 attributes.");
+
+  return entries.map(normalizeTempoSearchAttribute).sort(compareTempoSearchAttributes);
+}
+
+function normalizeTempoSearchAttribute([rawKey, rawValue]: [string, string]): NormalizedTempoSearchAttribute {
+  const key = rawKey.trim();
+  const value = normalizeTempoSearchAttributeValue(rawValue, key);
+
+  assertSafeTempoAttributeKey(key);
+  assertSafeTempoAttributeValue(value, key);
+  return { key, value };
+}
+
+function normalizeTempoSearchAttributeValue(rawValue: string, key: string): string {
+  if (typeof rawValue !== "string") throw new Error(`Unsafe Tempo ${key}: attribute values must be strings.`);
+
+  const value = rawValue.trim();
+  if (!value) throw new Error(`Unsafe Tempo ${key}: empty values are not query inputs.`);
+  return value;
+}
+
+function compareTempoSearchAttributes(
+  left: NormalizedTempoSearchAttribute,
+  right: NormalizedTempoSearchAttribute,
+): number {
+  return left.key.localeCompare(right.key);
+}
+
+function assertSafeTempoAttributeKey(key: string): void {
+  if (!safeTempoAttributeKeyPattern.test(key)) throw new Error(`Unsafe Tempo attribute key: ${key}`);
+  if (isAllowedTempoSearchAttributeKey(key)) return;
+
+  throw new Error(
+    "Unsafe Tempo attribute key: searchTempo may only use generated workflow IDs, generated agent IDs, session IDs, trace/span IDs, or hashed fields.",
+  );
+}
+
+function assertSafeTempoAttributeValue(value: string, key: string): void {
+  if (value.length > maxTempoSearchAttributeValueLength) {
+    throw new Error(`Unsafe Tempo ${key}: attribute values are bounded to 256 characters.`);
+  }
+
+  assertNoSensitiveQueryInput(value, `Tempo ${key}`);
+
+  if (!safeTempoAttributeValuePattern.test(value)) {
+    throw new Error(
+      `Unsafe Tempo ${key}: only generated IDs and hash-like values are accepted; raw prompts, commands, paths, and environment values are rejected.`,
+    );
+  }
+}
+
+function isAllowedTempoSearchAttributeKey(key: string): boolean {
+  return generatedCorrelationAttributeKeys.has(key) || hashedAttributeKeyPattern.test(key);
+}
+
+function normalizeTimeRange(range: TimeRange): NormalizedTimeRange {
+  const from = normalizeDate(range.from, "from");
+  const to = normalizeDate(range.to, "to");
+
+  if (from.getTime() > to.getTime()) throw new Error("Tempo search range must have from <= to.");
+  return { from, to };
+}
+
+function normalizeDate(value: Date, label: string): Date {
+  if (!(value instanceof Date) || !Number.isFinite(value.getTime())) {
+    throw new TypeError(`Tempo search range ${label} must be a valid Date.`);
+  }
+
+  return value;
+}
+
+function createTempoSearchUrl(
+  config: ObservMeConfig,
+  transport: GrafanaTransportClient,
+  attrs: readonly NormalizedTempoSearchAttribute[],
+  range: NormalizedTimeRange,
+  maxTraces: number,
+): URL {
+  const url = transport.datasourceProxyUrl(config.query.grafana.datasourceUids.tempo, "/api/search");
+
+  url.searchParams.set("tags", buildTempoTagsQuery(attrs));
+  url.searchParams.set("start", formatEpochSeconds(range.from, "floor"));
+  url.searchParams.set("end", formatEpochSeconds(range.to, "ceil"));
+  url.searchParams.set("limit", String(maxTraces));
+  return url;
+}
+
+function buildTempoTagsQuery(attrs: readonly NormalizedTempoSearchAttribute[]): string {
+  return attrs.map(formatTempoTagQueryPart).join(" ");
+}
+
+function formatTempoTagQueryPart(attr: NormalizedTempoSearchAttribute): string {
+  return `${attr.key}="${escapeTempoTagValue(attr.value)}"`;
+}
+
+function escapeTempoTagValue(value: string): string {
+  return value.replaceAll(backslashCharacter, String.raw`\\`).replaceAll('"', String.raw`\"`);
+}
+
+function formatEpochSeconds(date: Date, direction: "floor" | "ceil"): string {
+  const seconds = date.getTime() / 1000;
+  const rounded = direction === "floor" ? Math.floor(seconds) : Math.ceil(seconds);
+  return String(rounded);
+}
+
+async function readTempoTraceSummaries(
+  response: Response,
+  transport: GrafanaTransportClient,
+  maxTraces: number,
+): Promise<TraceSummary[]> {
+  if (!response.ok) throw new Error(`Tempo search failed: ${transport.formatHttpFailure(response)}`);
+
+  const payload = (await response.json()) as unknown;
+  const traces = extractTempoTraceItems(payload);
+  return traces.map(toTraceSummary).filter(isTraceSummary).slice(0, maxTraces);
+}
+
+function extractTempoTraceItems(payload: unknown): unknown[] {
+  if (Array.isArray(payload)) return payload;
+  if (isRecord(payload) && Array.isArray(payload.traces)) return payload.traces;
+  return [];
+}
+
+function toTraceSummary(item: unknown): TraceSummary | undefined {
+  if (!isRecord(item)) return undefined;
+
+  const traceId = readTraceId(item);
+  if (!traceId) return undefined;
+
+  return {
+    traceId,
+    rootServiceName: readOptionalString(item, "rootServiceName"),
+    rootTraceName: readOptionalString(item, "rootTraceName"),
+    startTimeUnixNano: readOptionalStringOrNumber(item, "startTimeUnixNano"),
+    durationMs: readOptionalFiniteNumber(item, "durationMs"),
+    spanSet: item.spanSet,
+  };
+}
+
+function readTraceId(item: Record<string, unknown>): string | undefined {
+  const traceId = readOptionalString(item, "traceID") ?? readOptionalString(item, "traceId");
+  if (!traceId) return undefined;
+  return traceId.trim().toLowerCase();
+}
+
+function readOptionalString(item: Record<string, unknown>, key: string): string | undefined {
+  const value = item[key];
+  if (typeof value !== "string") return undefined;
+
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+function readOptionalStringOrNumber(item: Record<string, unknown>, key: string): string | undefined {
+  const value = item[key];
+  if (typeof value === "string" && value.trim()) return value.trim();
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return undefined;
+}
+
+function readOptionalFiniteNumber(item: Record<string, unknown>, key: string): number | undefined {
+  const value = item[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function isTraceSummary(value: TraceSummary | undefined): value is TraceSummary {
+  return value !== undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function resolveMaxTraces(config: ObservMeConfig): number {
+  const maxTraces = config.query.maxTraces;
+  if (!Number.isFinite(maxTraces) || maxTraces < minimumMaxTraces) return minimumMaxTraces;
+  return Math.trunc(maxTraces);
+}

package/src/safety/sensitive-input.ts

@@ -0,0 +1,208 @@
+export interface DiagnosticReplacement {
+  readonly pattern: RegExp;
+  readonly replacement: string;
+}
+
+export interface ObservMeSessionIdOptions {
+  readonly emptyMessage: string;
+}
+
+export const SENSITIVE_QUERY_INPUT_DETAILS =
+  "raw prompts, commands, paths, and inherited environment values are not query inputs.";
+export const UNSAFE_OBSERVME_SESSION_ID_DETAILS =
+  "only generated session IDs may be used; raw prompts, commands, paths, and environment values are not query inputs.";
+
+const maximumDiagnosticLength = 360;
+const rawContentMarkerPattern = /(?:^|[\s"'`|=(])(?:prompt|system prompt|user prompt|assistant response|thinking|raw content)\s*:/iu;
+const shellCommandPattern = /(?:^|[\s"'`|=])(?:sudo|rm|mv|cp|curl|wget|npm|pnpm|yarn|node|python3?|bash|sh|git)\s+\S+/iu;
+const homeFilesystemPathPattern = /(?:^|[\s"'`=])~(?:\/|\b)\S*/u;
+const relativeFilesystemPathPattern = /(?:^|[\s"'`=])\.{1,2}\/\S*/u;
+const unixFilesystemPathPattern = /(?:^|[\s"'`=])\/(?:Users|home|tmp|var|etc|private|workspace|opt|Volumes)\b\S*/u;
+const windowsDriveFilesystemPathPattern = /(?:^|[\s"'`=])[A-Za-z]:\\\S*/u;
+const windowsUncFilesystemPathPattern = /(?:^|[\s"'`=])\\\\\S*/u;
+const environmentAssignmentPattern = /\b[A-Z][A-Z0-9_]{2,}=[^\s"'`;,)]*/u;
+const diagnosticEnvironmentAssignmentPattern = /\b[A-Z][A-Z0-9_]{2,}=[^\s"'`;,)]*/gu;
+const unresolvedEnvironmentPlaceholderPattern = /\$\{[A-Z0-9_]+\}/u;
+const diagnosticUnresolvedEnvironmentPlaceholderPattern = /\$\{[A-Z0-9_]+\}/gu;
+const bearerCredentialPattern = /\bBearer\s+[^\s"'`;,)]+/iu;
+const credentialAssignmentPatterns = [
+  /\baccess[_-]?token\s*[:=]\s*["']?[^\s"'`;,)]*/iu,
+  /\bapi[_-]?key\s*[:=]\s*["']?[^\s"'`;,)]*/iu,
+  /\btoken\s*[:=]\s*["']?[^\s"'`;,)]*/iu,
+  /\bpassword\s*[:=]\s*["']?[^\s"'`;,)]*/iu,
+  /\bsecret\s*[:=]\s*["']?[^\s"'`;,)]*/iu,
+  /\bauthorization\s*[:=]\s*["']?[^\s"'`;,)]*/iu,
+] as const;
+const safeObservMeSessionIdPattern = /^[A-Za-z0-9._:-]{1,256}$/u;
+const sensitiveQueryInputPatterns = [
+  rawContentMarkerPattern,
+  shellCommandPattern,
+  homeFilesystemPathPattern,
+  relativeFilesystemPathPattern,
+  unixFilesystemPathPattern,
+  windowsDriveFilesystemPathPattern,
+  windowsUncFilesystemPathPattern,
+  environmentAssignmentPattern,
+  unresolvedEnvironmentPlaceholderPattern,
+  bearerCredentialPattern,
+  ...credentialAssignmentPatterns,
+] as const;
+const diagnosticReplacements = [
+  { pattern: /Bearer\s+[^\s;,)]+/giu, replacement: "Bearer [redacted]" },
+  { pattern: /Basic\s+[^\s;,)]+/giu, replacement: "Basic [redacted]" },
+  { pattern: /\b(token|password|secret|authorization)\s*[:=]\s*["']?[^"'\s;,)]+/giu, replacement: "$1=[redacted]" },
+  { pattern: diagnosticEnvironmentAssignmentPattern, replacement: "[redacted-env]" },
+  { pattern: diagnosticUnresolvedEnvironmentPlaceholderPattern, replacement: "[redacted-env-placeholder]" },
+  {
+    pattern: /([?&](?:access_)?(?:token|password|secret|authorization)=)[^\s&#;,)]+/giu,
+    replacement: "$1[redacted]",
+  },
+  {
+    pattern: /(^|[\s(["'`])(?:prompt|system prompt|user prompt|assistant response|thinking|raw content)\s*:[^.;\n]*/giu,
+    replacement: "$1[redacted-content]",
+  },
+  {
+    pattern: /(^|[\s(["'`])(?:sudo|rm|mv|cp|curl|wget|npm|pnpm|yarn|node|python3?|bash|sh|git)\s+[^.;\n)]*/giu,
+    replacement: "$1[redacted-command]",
+  },
+  {
+    pattern: /(^|[\s(["'`])(?:~|\.{2}\/|\.\/|\/Users\/|\/home\/|\/tmp\/|[A-Za-z]:\\|\\\\)[^\s)"'`,;]*/gu,
+    replacement: "$1[redacted-path]",
+  },
+] as const satisfies readonly DiagnosticReplacement[];
+
+export function assertNoSensitiveQueryInput(value: string, surface: string): void {
+  if (!isSensitiveQueryInput(value)) return;
+
+  throw new Error(`Unsafe ${surface}: ${SENSITIVE_QUERY_INPUT_DETAILS}`);
+}
+
+export function isSensitiveQueryInput(value: string): boolean {
+  return sensitiveQueryInputPatterns.some(pattern => pattern.test(value));
+}
+
+export function normalizeObservMeSessionId(value: string | undefined, options: ObservMeSessionIdOptions): string {
+  const sessionId = normalizeOptionalString(value);
+
+  if (!sessionId) throw new Error(options.emptyMessage);
+  if (isUnsafeObservMeSessionId(sessionId)) throw new Error(`Unsafe ObservMe session id: ${UNSAFE_OBSERVME_SESSION_ID_DETAILS}`);
+  return sessionId;
+}
+
+export function isUnsafeObservMeSessionId(value: string): boolean {
+  return !safeObservMeSessionIdPattern.test(value) || isSensitiveQueryInput(value);
+}
+
+export function hasUnresolvedEnvironmentPlaceholder(value: string): boolean {
+  return unresolvedEnvironmentPlaceholderPattern.test(value);
+}
+
+export function readDiagnosticMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === "string") return error;
+  return String(error);
+}
+
+export function sanitizeUiDiagnosticText(message: string): string {
+  const normalized = normalizeDiagnosticWhitespace(message);
+  const redactedUrlCredentials = redactUrlCredentials(normalized);
+  const redacted = diagnosticReplacements.reduce(applyDiagnosticReplacement, redactedUrlCredentials);
+  return truncateDiagnostic(redacted || "unknown error");
+}
+
+function applyDiagnosticReplacement(message: string, replacement: DiagnosticReplacement): string {
+  return message.replace(replacement.pattern, replacement.replacement);
+}
+
+function redactUrlCredentials(message: string): string {
+  let redacted = "";
+  let cursor = 0;
+  let searchFrom = 0;
+
+  while (searchFrom < message.length) {
+    const markerIndex = message.indexOf("://", searchFrom);
+    if (markerIndex === -1) break;
+
+    const schemeStart = findUrlSchemeStart(message, markerIndex);
+    if (!isValidUrlScheme(message, schemeStart, markerIndex)) {
+      searchFrom = markerIndex + 3;
+      continue;
+    }
+
+    const credentialsStart = markerIndex + 3;
+    const authorityEnd = findUrlAuthorityEnd(message, credentialsStart);
+    const atIndex = message.indexOf("@", credentialsStart);
+    if (atIndex === -1 || atIndex >= authorityEnd) {
+      searchFrom = authorityEnd + 1;
+      continue;
+    }
+
+    const colonIndex = message.indexOf(":", credentialsStart);
+    if (colonIndex === -1 || colonIndex >= atIndex || colonIndex === credentialsStart || colonIndex + 1 === atIndex) {
+      searchFrom = atIndex + 1;
+      continue;
+    }
+
+    redacted += message.slice(cursor, credentialsStart);
+    redacted += "[redacted]@";
+    cursor = atIndex + 1;
+    searchFrom = atIndex + 1;
+  }
+
+  return redacted + message.slice(cursor);
+}
+
+function findUrlSchemeStart(message: string, schemeEnd: number): number {
+  let start = schemeEnd - 1;
+  while (start > 0 && isUrlSchemeCharacter(message[start - 1])) start -= 1;
+  return start;
+}
+
+function isValidUrlScheme(message: string, schemeStart: number, schemeEnd: number): boolean {
+  if (schemeStart >= schemeEnd) return false;
+  if (!isAsciiLetter(message[schemeStart])) return false;
+
+  for (let index = schemeStart + 1; index < schemeEnd; index += 1) {
+    if (!isUrlSchemeCharacter(message[index])) return false;
+  }
+
+  return true;
+}
+
+function findUrlAuthorityEnd(message: string, start: number): number {
+  let index = start;
+  while (index < message.length && !isUrlAuthorityTerminator(message[index])) index += 1;
+  return index;
+}
+
+function isUrlAuthorityTerminator(value: string): boolean {
+  return value === "/" || value === "?" || value === "#" || value === " ";
+}
+
+function isUrlSchemeCharacter(value: string): boolean {
+  return isAsciiLetter(value) || isAsciiDigit(value) || value === "+" || value === "." || value === "-";
+}
+
+function isAsciiLetter(value: string): boolean {
+  const code = value.codePointAt(0);
+  return code !== undefined && ((code >= 65 && code <= 90) || (code >= 97 && code <= 122));
+}
+
+function isAsciiDigit(value: string): boolean {
+  const code = value.codePointAt(0);
+  return code !== undefined && code >= 48 && code <= 57;
+}
+
+function normalizeOptionalString(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed || undefined;
+}
+
+function normalizeDiagnosticWhitespace(message: string): string {
+  return message.replace(/\s+/gu, " ").trim();
+}
+
+function truncateDiagnostic(message: string): string {
+  if (message.length <= maximumDiagnosticLength) return message;
+  return `${message.slice(0, maximumDiagnosticLength - 1)}…`;
+}