@bendyline/docblocks 2.0.0 → 2.1.1

package/src/mcp/wire.ts

@@ -1,1280 +0,0 @@
-import { tryParseWorkspacePath, type WorkspacePath } from '../filesystem/workspace-path.js';
-import {
-  DOCBLOCKS_MCP_WIRE_VERSION,
-  type AppliedOption,
-  type ArtifactRef,
-  type AssetSummary,
-  type BlockSummary,
-  type BundleAssetRef,
-  type BundleAssetContentSource,
-  type ComparisonChange,
-  type ComparisonMetric,
-  type ComparisonResult,
-  type ConversionFidelity,
-  type ConversionResult,
-  type DiagnosticLocation,
-  type DiagnosticSeverity,
-  type DiagnosticStage,
-  type DocumentMetadataSummary,
-  type DocumentItemSummary,
-  type DocumentSource,
-  type DocumentStatistics,
-  type EngineVersion,
-  type InspectionResult,
-  type LinkSummary,
-  type MaterializationOptions,
-  type McpDiagnostic,
-  type McpErrorResult,
-  type OutlineEntry,
-  type PreviewItem,
-  type PreviewResult,
-  type SourceRange,
-  type ThemeSummary,
-  type TableSummary,
-  type ValidationResult,
-  type ValidationSummary,
-} from './types.js';
-
-/** Quantitative limits for untrusted MCP payloads. */
-export const MCP_WIRE_LIMITS = Object.freeze({
-  identifierCharacters: 256,
-  formatCharacters: 64,
-  mimeTypeCharacters: 256,
-  labelCharacters: 1_024,
-  pathCharacters: 4_096,
-  uriCharacters: 8_192,
-  messageCharacters: 4_000,
-  excerptCharacters: 4_096,
-  documentCharacters: 20 * 1024 * 1024,
-  artifactBytes: 500 * 1024 * 1024,
-  bundleAssets: 256,
-  arrayEntries: 10_000,
-  previewItems: 1_000,
-  imageDimension: 32_768,
-});
-
-const IDENTIFIER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/u;
-const ENGINE_NAME_PATTERN =
-  /^(?:[A-Za-z0-9][A-Za-z0-9._:-]*|@[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*)$/u;
-const FORMAT_PATTERN = /^[a-z0-9][a-z0-9.+_-]*$/u;
-const MIME_TYPE_PATTERN = /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/iu;
-const SHA256_PATTERN = /^[a-f0-9]{64}$/u;
-const ISO_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u;
-
-export function parseArtifactRef(value: unknown): ArtifactRef | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, [
-      'id',
-      'uri',
-      'format',
-      'mimeType',
-      'size',
-      'sha256',
-      'sourceFormat',
-      'sourceSha256',
-      'suggestedFilename',
-      'appliedOptions',
-      'engineVersions',
-      'createdAt',
-      'expiresAt',
-    ])
-  ) {
-    return null;
-  }
-
-  const {
-    id,
-    uri,
-    format,
-    mimeType,
-    size,
-    sha256,
-    sourceFormat,
-    sourceSha256,
-    suggestedFilename,
-    createdAt,
-    expiresAt,
-  } = value;
-  const appliedOptions = parseArray(value.appliedOptions, parseAppliedOption);
-  const engineVersions = parseArray(value.engineVersions, parseEngineVersion);
-  if (
-    !isIdentifier(id) ||
-    !isArtifactUri(uri, id) ||
-    !isFormat(format) ||
-    !isMimeType(mimeType) ||
-    !isBoundedInteger(size, 0, MCP_WIRE_LIMITS.artifactBytes) ||
-    !isSha256(sha256) ||
-    !(sourceFormat === null || isFormat(sourceFormat)) ||
-    !(sourceSha256 === null || isSha256(sourceSha256)) ||
-    !isSafeFilename(suggestedFilename) ||
-    appliedOptions === null ||
-    engineVersions === null ||
-    hasDuplicateNames(appliedOptions) ||
-    hasDuplicateNames(engineVersions) ||
-    !isIsoTimestamp(createdAt) ||
-    !(expiresAt === null || isIsoTimestamp(expiresAt)) ||
-    (expiresAt !== null && Date.parse(expiresAt) <= Date.parse(createdAt))
-  ) {
-    return null;
-  }
-
-  return {
-    id,
-    uri,
-    format,
-    mimeType,
-    size,
-    sha256,
-    sourceFormat,
-    sourceSha256,
-    suggestedFilename,
-    appliedOptions,
-    engineVersions,
-    createdAt,
-    expiresAt,
-  };
-}
-
-export function parseDocumentSource(value: unknown): DocumentSource | null {
-  if (!isRecord(value) || typeof value.kind !== 'string') return null;
-
-  switch (value.kind) {
-    case 'markdown': {
-      if (!hasExactKeys(value, ['kind', 'markdown', 'name'])) return null;
-      const { markdown, name } = value;
-      if (
-        !isBoundedString(markdown, MCP_WIRE_LIMITS.documentCharacters) ||
-        !isNullableBoundedString(name, MCP_WIRE_LIMITS.labelCharacters)
-      ) {
-        return null;
-      }
-      return { kind: 'markdown', markdown, name };
-    }
-    case 'file': {
-      if (!hasExactKeys(value, ['kind', 'rootId', 'path', 'format'])) return null;
-      const { rootId, path, format } = value;
-      const parsedPath = parseNonRootWorkspacePath(path);
-      if (!isIdentifier(rootId) || parsedPath === null || !(format === null || isFormat(format))) {
-        return null;
-      }
-      return { kind: 'file', rootId, path: parsedPath, format };
-    }
-    case 'artifact': {
-      if (!hasExactKeys(value, ['kind', 'uri']) || !isArtifactUri(value.uri)) return null;
-      return { kind: 'artifact', uri: value.uri };
-    }
-    case 'bundle': {
-      if (!hasExactKeys(value, ['kind', 'markdown', 'assets', 'name'])) return null;
-      const { markdown, name } = value;
-      if (
-        !isBoundedString(markdown, MCP_WIRE_LIMITS.documentCharacters) ||
-        !isNullableBoundedString(name, MCP_WIRE_LIMITS.labelCharacters)
-      ) {
-        return null;
-      }
-      const assets = parseArray(value.assets, parseBundleAssetRef, MCP_WIRE_LIMITS.bundleAssets);
-      if (assets === null || hasDuplicatePaths(assets)) return null;
-      return { kind: 'bundle', markdown, assets, name };
-    }
-    default:
-      return null;
-  }
-}
-
-export function parseMcpDiagnostic(value: unknown): McpDiagnostic | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, [
-      'code',
-      'severity',
-      'stage',
-      'format',
-      'count',
-      'message',
-      'remediation',
-      'retryable',
-      'location',
-    ])
-  ) {
-    return null;
-  }
-
-  const { code, severity, stage, format, count, message, remediation, retryable } = value;
-  const location = parseNullable(value.location, parseDiagnosticLocation);
-  if (
-    !isIdentifier(code) ||
-    !isDiagnosticSeverity(severity) ||
-    !isDiagnosticStage(stage) ||
-    !(format === null || isFormat(format)) ||
-    !isBoundedInteger(count, 1, Number.MAX_SAFE_INTEGER) ||
-    !isBoundedString(message, MCP_WIRE_LIMITS.messageCharacters, 1) ||
-    !isNullableBoundedString(remediation, MCP_WIRE_LIMITS.messageCharacters) ||
-    typeof retryable !== 'boolean' ||
-    location === undefined
-  ) {
-    return null;
-  }
-
-  return {
-    code,
-    severity,
-    stage,
-    format,
-    count,
-    message,
-    remediation,
-    retryable,
-    location,
-  };
-}
-
-export function parseMcpErrorResult(value: unknown): McpErrorResult | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, ['version', 'kind', 'result', 'error']) ||
-    value.version !== DOCBLOCKS_MCP_WIRE_VERSION ||
-    value.kind !== 'error' ||
-    value.result !== null ||
-    !isRecord(value.error) ||
-    !hasExactKeys(value.error, [
-      'code',
-      'message',
-      'stage',
-      'format',
-      'hint',
-      'retryable',
-      'operationLoad',
-    ])
-  ) {
-    return null;
-  }
-  const { code, message, stage, format, hint, retryable, operationLoad } = value.error;
-  if (
-    !isIdentifier(code) ||
-    !isBoundedString(message, MCP_WIRE_LIMITS.messageCharacters, 1) ||
-    !(stage === null || isDiagnosticStage(stage)) ||
-    !(format === null || isFormat(format)) ||
-    !isNullableBoundedString(hint, MCP_WIRE_LIMITS.messageCharacters) ||
-    typeof retryable !== 'boolean' ||
-    !(
-      operationLoad === null ||
-      (isRecord(operationLoad) &&
-        hasExactKeys(operationLoad, ['active', 'capacity']) &&
-        isBoundedInteger(operationLoad.active, 0, 32) &&
-        isBoundedInteger(operationLoad.capacity, 1, 32) &&
-        operationLoad.active <= operationLoad.capacity)
-    )
-  ) {
-    return null;
-  }
-  return {
-    version: DOCBLOCKS_MCP_WIRE_VERSION,
-    kind: 'error',
-    result: null,
-    error: {
-      code,
-      message,
-      stage,
-      format,
-      hint,
-      retryable,
-      operationLoad:
-        operationLoad === null
-          ? null
-          : {
-              active: operationLoad.active as number,
-              capacity: operationLoad.capacity as number,
-            },
-    },
-  };
-}
-
-export function parseConversionResult(value: unknown): ConversionResult | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, [
-      'version',
-      'kind',
-      'sourceFormat',
-      'targetFormat',
-      'artifact',
-      'fidelity',
-      'appliedThemeId',
-      'appliedTransformId',
-      'sourceAssets',
-      'sourceAssetCount',
-      'diagnostics',
-    ]) ||
-    value.version !== DOCBLOCKS_MCP_WIRE_VERSION ||
-    value.kind !== 'conversion' ||
-    !isFormat(value.sourceFormat) ||
-    !isFormat(value.targetFormat) ||
-    !isConversionFidelity(value.fidelity) ||
-    !isNullableIdentifier(value.appliedThemeId) ||
-    !isNullableIdentifier(value.appliedTransformId) ||
-    !isBoundedInteger(value.sourceAssetCount, 0, MCP_WIRE_LIMITS.arrayEntries)
-  ) {
-    return null;
-  }
-
-  const artifact = parseArtifactRef(value.artifact);
-  const sourceAssets = parseArray(value.sourceAssets, parseAssetSummary);
-  const diagnostics = parseArray(value.diagnostics, parseMcpDiagnostic);
-  if (
-    artifact === null ||
-    sourceAssets === null ||
-    diagnostics === null ||
-    sourceAssets.length !== value.sourceAssetCount ||
-    hasDuplicatePaths(sourceAssets) ||
-    artifact.format !== value.targetFormat ||
-    (artifact.sourceFormat !== null && artifact.sourceFormat !== value.sourceFormat)
-  ) {
-    return null;
-  }
-
-  return {
-    version: DOCBLOCKS_MCP_WIRE_VERSION,
-    kind: 'conversion',
-    sourceFormat: value.sourceFormat,
-    targetFormat: value.targetFormat,
-    artifact,
-    fidelity: value.fidelity,
-    appliedThemeId: value.appliedThemeId,
-    appliedTransformId: value.appliedTransformId,
-    sourceAssets,
-    sourceAssetCount: value.sourceAssetCount,
-    diagnostics,
-  };
-}
-
-export function parseInspectionResult(value: unknown): InspectionResult | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, [
-      'version',
-      'kind',
-      'sourceFormat',
-      'metadata',
-      'statistics',
-      'outline',
-      'blocks',
-      'blockOffset',
-      'nextCursor',
-      'tables',
-      'links',
-      'items',
-      'assets',
-      'theme',
-      'truncated',
-      'detailsTruncated',
-      'diagnostics',
-    ]) ||
-    value.version !== DOCBLOCKS_MCP_WIRE_VERSION ||
-    value.kind !== 'inspection' ||
-    !isFormat(value.sourceFormat) ||
-    !isBoundedInteger(value.blockOffset, 0, MCP_WIRE_LIMITS.arrayEntries) ||
-    !isNullableBoundedString(value.nextCursor, MCP_WIRE_LIMITS.identifierCharacters) ||
-    typeof value.truncated !== 'boolean' ||
-    typeof value.detailsTruncated !== 'boolean'
-  ) {
-    return null;
-  }
-
-  const metadata = parseDocumentMetadata(value.metadata);
-  const statistics = parseDocumentStatistics(value.statistics);
-  const outline = parseArray(value.outline, parseOutlineEntry);
-  const blocks = parseArray(value.blocks, parseBlockSummary);
-  const tables = parseArray(value.tables, parseTableSummary);
-  const links = parseArray(value.links, parseLinkSummary);
-  const items = parseArray(value.items, parseDocumentItemSummary);
-  const assets = parseArray(value.assets, parseAssetSummary);
-  const theme = parseNullable(value.theme, parseThemeSummary);
-  const diagnostics = parseArray(value.diagnostics, parseMcpDiagnostic);
-  if (
-    metadata === null ||
-    statistics === null ||
-    outline === null ||
-    blocks === null ||
-    tables === null ||
-    links === null ||
-    items === null ||
-    assets === null ||
-    theme === undefined ||
-    diagnostics === null ||
-    statistics.blockCount < value.blockOffset + blocks.length ||
-    statistics.assetCount < assets.length ||
-    (!value.truncated && statistics.blockCount !== value.blockOffset + blocks.length) ||
-    value.truncated !== (value.nextCursor !== null) ||
-    statistics.tableCount < tables.length ||
-    statistics.linkCount < links.length ||
-    hasDuplicateIds(outline) ||
-    hasDuplicateIds(blocks) ||
-    hasDuplicateIndexes(tables) ||
-    hasDuplicateIndexes(links) ||
-    hasDuplicateItemIndexes(items) ||
-    hasDuplicatePaths(assets) ||
-    outline.some((entry) => entry.blockIndex >= statistics.blockCount) ||
-    blocks.some(
-      (block) => block.sourceRange !== null && block.sourceRange.end > statistics.characterCount,
-    )
-  ) {
-    return null;
-  }
-
-  return {
-    version: DOCBLOCKS_MCP_WIRE_VERSION,
-    kind: 'inspection',
-    sourceFormat: value.sourceFormat,
-    metadata,
-    statistics,
-    outline,
-    blocks,
-    blockOffset: value.blockOffset,
-    nextCursor: value.nextCursor,
-    tables,
-    links,
-    items,
-    assets,
-    theme,
-    truncated: value.truncated,
-    detailsTruncated: value.detailsTruncated,
-    diagnostics,
-  };
-}
-
-export function parseValidationResult(value: unknown): ValidationResult | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, [
-      'version',
-      'kind',
-      'sourceFormat',
-      'targetFormat',
-      'valid',
-      'summary',
-      'diagnostics',
-    ]) ||
-    value.version !== DOCBLOCKS_MCP_WIRE_VERSION ||
-    value.kind !== 'validation' ||
-    !isFormat(value.sourceFormat) ||
-    !(value.targetFormat === null || isFormat(value.targetFormat)) ||
-    typeof value.valid !== 'boolean'
-  ) {
-    return null;
-  }
-
-  const summary = parseValidationSummary(value.summary);
-  const diagnostics = parseArray(value.diagnostics, parseMcpDiagnostic);
-  if (summary === null || diagnostics === null) return null;
-  const actualSummary = summarizeDiagnostics(diagnostics);
-  if (
-    summary.errorCount !== actualSummary.errorCount ||
-    summary.warningCount !== actualSummary.warningCount ||
-    summary.infoCount !== actualSummary.infoCount ||
-    value.valid !== (summary.errorCount === 0)
-  ) {
-    return null;
-  }
-
-  return {
-    version: DOCBLOCKS_MCP_WIRE_VERSION,
-    kind: 'validation',
-    sourceFormat: value.sourceFormat,
-    targetFormat: value.targetFormat,
-    valid: value.valid,
-    summary,
-    diagnostics,
-  };
-}
-
-export function parsePreviewResult(value: unknown): PreviewResult | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, [
-      'version',
-      'kind',
-      'sourceFormat',
-      'previewBasis',
-      'totalItems',
-      'items',
-      'truncated',
-      'diagnostics',
-    ]) ||
-    value.version !== DOCBLOCKS_MCP_WIRE_VERSION ||
-    value.kind !== 'preview' ||
-    !isFormat(value.sourceFormat) ||
-    !(
-      value.previewBasis === 'source-render' ||
-      value.previewBasis === 'reconstructed-import' ||
-      value.previewBasis === 'native-extracted'
-    ) ||
-    !isBoundedInteger(value.totalItems, 0, Number.MAX_SAFE_INTEGER) ||
-    typeof value.truncated !== 'boolean'
-  ) {
-    return null;
-  }
-
-  const items = parseArray(value.items, parsePreviewItem, MCP_WIRE_LIMITS.previewItems);
-  const diagnostics = parseArray(value.diagnostics, parseMcpDiagnostic);
-  if (
-    items === null ||
-    diagnostics === null ||
-    value.totalItems < items.length ||
-    (!value.truncated && value.totalItems !== items.length) ||
-    hasDuplicatePreviewIndexes(items) ||
-    items.some(
-      (item) =>
-        item.artifact.sourceFormat !== null && item.artifact.sourceFormat !== value.sourceFormat,
-    )
-  ) {
-    return null;
-  }
-
-  return {
-    version: DOCBLOCKS_MCP_WIRE_VERSION,
-    kind: 'preview',
-    sourceFormat: value.sourceFormat,
-    previewBasis: value.previewBasis,
-    totalItems: value.totalItems,
-    items,
-    truncated: value.truncated,
-    diagnostics,
-  };
-}
-
-export function parseComparisonResult(value: unknown): ComparisonResult | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, [
-      'version',
-      'kind',
-      'leftFormat',
-      'rightFormat',
-      'equivalent',
-      'score',
-      'changes',
-      'metrics',
-      'diagnostics',
-    ]) ||
-    value.version !== DOCBLOCKS_MCP_WIRE_VERSION ||
-    value.kind !== 'comparison' ||
-    !isFormat(value.leftFormat) ||
-    !isFormat(value.rightFormat) ||
-    typeof value.equivalent !== 'boolean' ||
-    !isBoundedNumber(value.score, 0, 1)
-  ) {
-    return null;
-  }
-
-  const changes = parseArray(value.changes, parseComparisonChange);
-  const metrics = parseArray(value.metrics, parseComparisonMetric);
-  const diagnostics = parseArray(value.diagnostics, parseMcpDiagnostic);
-  if (
-    changes === null ||
-    metrics === null ||
-    diagnostics === null ||
-    hasDuplicateNames(metrics) ||
-    (value.equivalent &&
-      (value.score !== 1 || changes.some((change) => change.status !== 'retained')))
-  ) {
-    return null;
-  }
-
-  return {
-    version: DOCBLOCKS_MCP_WIRE_VERSION,
-    kind: 'comparison',
-    leftFormat: value.leftFormat,
-    rightFormat: value.rightFormat,
-    equivalent: value.equivalent,
-    score: value.score,
-    changes,
-    metrics,
-    diagnostics,
-  };
-}
-
-export function parseMaterializationOptions(value: unknown): MaterializationOptions | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, ['rootId', 'path', 'ifExists', 'expectedSha256']) ||
-    !isIdentifier(value.rootId)
-  ) {
-    return null;
-  }
-  const path = parseNonRootWorkspacePath(value.path);
-  if (path === null) return null;
-
-  if (value.ifExists === 'error' && value.expectedSha256 === null) {
-    return { rootId: value.rootId, path, ifExists: 'error', expectedSha256: null };
-  }
-  if (value.ifExists === 'replace' && isSha256(value.expectedSha256)) {
-    return {
-      rootId: value.rootId,
-      path,
-      ifExists: 'replace',
-      expectedSha256: value.expectedSha256,
-    };
-  }
-  return null;
-}
-
-function parseBundleAssetRef(value: unknown): BundleAssetRef | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, ['path', 'source', 'mimeType', 'altText', 'credit', 'license'])
-  ) {
-    return null;
-  }
-  const path = parseNonRootWorkspacePath(value.path);
-  const source = parseBundleAssetContentSource(value.source);
-  if (
-    path === null ||
-    source === null ||
-    !(value.mimeType === null || isMimeType(value.mimeType)) ||
-    !isNullableBoundedString(value.altText, MCP_WIRE_LIMITS.labelCharacters) ||
-    !isNullableBoundedString(value.credit, MCP_WIRE_LIMITS.labelCharacters) ||
-    !isNullableBoundedString(value.license, MCP_WIRE_LIMITS.labelCharacters)
-  ) {
-    return null;
-  }
-  return {
-    path,
-    source,
-    mimeType: value.mimeType,
-    altText: value.altText,
-    credit: value.credit,
-    license: value.license,
-  };
-}
-
-function parseBundleAssetContentSource(value: unknown): BundleAssetContentSource | null {
-  if (!isRecord(value) || typeof value.kind !== 'string') return null;
-  if (value.kind === 'file') {
-    if (!hasExactKeys(value, ['kind', 'rootId', 'path']) || !isIdentifier(value.rootId)) {
-      return null;
-    }
-    const path = parseNonRootWorkspacePath(value.path);
-    return path === null ? null : { kind: 'file', rootId: value.rootId, path };
-  }
-  if (value.kind === 'artifact') {
-    return hasExactKeys(value, ['kind', 'uri']) && isArtifactUri(value.uri)
-      ? { kind: 'artifact', uri: value.uri }
-      : null;
-  }
-  return null;
-}
-
-function parseDiagnosticLocation(value: unknown): DiagnosticLocation | null {
-  if (!isRecord(value) || typeof value.kind !== 'string') return null;
-  switch (value.kind) {
-    case 'source':
-      return hasExactKeys(value, ['kind', 'line', 'column']) &&
-        isBoundedInteger(value.line, 1, Number.MAX_SAFE_INTEGER) &&
-        isBoundedInteger(value.column, 1, Number.MAX_SAFE_INTEGER)
-        ? { kind: 'source', line: value.line, column: value.column }
-        : null;
-    case 'block':
-      return hasExactKeys(value, ['kind', 'blockId', 'nodeType']) &&
-        isIdentifier(value.blockId) &&
-        isIdentifier(value.nodeType)
-        ? { kind: 'block', blockId: value.blockId, nodeType: value.nodeType }
-        : null;
-    case 'asset': {
-      if (!hasExactKeys(value, ['kind', 'path'])) return null;
-      const path = parseNonRootWorkspacePath(value.path);
-      return path === null ? null : { kind: 'asset', path };
-    }
-    case 'item':
-      return hasExactKeys(value, ['kind', 'itemKind', 'index']) &&
-        isPreviewItemKind(value.itemKind) &&
-        isBoundedInteger(value.index, 0, Number.MAX_SAFE_INTEGER)
-        ? { kind: 'item', itemKind: value.itemKind, index: value.index }
-        : null;
-    default:
-      return null;
-  }
-}
-
-function parseAppliedOption(value: unknown): AppliedOption | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, ['name', 'value']) ||
-    !isIdentifier(value.name) ||
-    !isAppliedOptionValue(value.value)
-  ) {
-    return null;
-  }
-  return { name: value.name, value: value.value };
-}
-
-function parseEngineVersion(value: unknown): EngineVersion | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, ['name', 'version']) ||
-    !isEngineName(value.name) ||
-    !isBoundedString(value.version, MCP_WIRE_LIMITS.identifierCharacters, 1)
-  ) {
-    return null;
-  }
-  return { name: value.name, version: value.version };
-}
-
-function parseDocumentMetadata(value: unknown): DocumentMetadataSummary | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, ['title', 'author', 'description']) ||
-    !isNullableBoundedString(value.title, MCP_WIRE_LIMITS.labelCharacters) ||
-    !isNullableBoundedString(value.author, MCP_WIRE_LIMITS.labelCharacters) ||
-    !isNullableBoundedString(value.description, MCP_WIRE_LIMITS.messageCharacters)
-  ) {
-    return null;
-  }
-  return { title: value.title, author: value.author, description: value.description };
-}
-
-function parseDocumentStatistics(value: unknown): DocumentStatistics | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, [
-      'blockCount',
-      'wordCount',
-      'characterCount',
-      'tableCount',
-      'linkCount',
-      'assetCount',
-      'pageCount',
-      'slideCount',
-      'sheetCount',
-    ]) ||
-    !isNonNegativeInteger(value.blockCount) ||
-    !isNonNegativeInteger(value.wordCount) ||
-    !isNonNegativeInteger(value.characterCount) ||
-    !isNonNegativeInteger(value.tableCount) ||
-    !isNonNegativeInteger(value.linkCount) ||
-    !isNonNegativeInteger(value.assetCount) ||
-    !isNullableNonNegativeInteger(value.pageCount) ||
-    !isNullableNonNegativeInteger(value.slideCount) ||
-    !isNullableNonNegativeInteger(value.sheetCount)
-  ) {
-    return null;
-  }
-  return {
-    blockCount: value.blockCount,
-    wordCount: value.wordCount,
-    characterCount: value.characterCount,
-    tableCount: value.tableCount,
-    linkCount: value.linkCount,
-    assetCount: value.assetCount,
-    pageCount: value.pageCount,
-    slideCount: value.slideCount,
-    sheetCount: value.sheetCount,
-  };
-}
-
-function parseOutlineEntry(value: unknown): OutlineEntry | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, ['id', 'title', 'level', 'blockIndex']) ||
-    !isIdentifier(value.id) ||
-    !isBoundedString(value.title, MCP_WIRE_LIMITS.labelCharacters, 1) ||
-    !isBoundedInteger(value.level, 1, 6) ||
-    !isNonNegativeInteger(value.blockIndex)
-  ) {
-    return null;
-  }
-  return { id: value.id, title: value.title, level: value.level, blockIndex: value.blockIndex };
-}
-
-function parseBlockSummary(value: unknown): BlockSummary | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, ['id', 'type', 'text', 'wordCount', 'templateId', 'sourceRange']) ||
-    !isIdentifier(value.id) ||
-    !isIdentifier(value.type) ||
-    !isBoundedString(value.text, MCP_WIRE_LIMITS.excerptCharacters) ||
-    !isNonNegativeInteger(value.wordCount) ||
-    !isNullableIdentifier(value.templateId)
-  ) {
-    return null;
-  }
-  const sourceRange = parseNullable(value.sourceRange, parseSourceRange);
-  if (sourceRange === undefined) return null;
-  return {
-    id: value.id,
-    type: value.type,
-    text: value.text,
-    wordCount: value.wordCount,
-    templateId: value.templateId,
-    sourceRange,
-  };
-}
-
-function parseSourceRange(value: unknown): SourceRange | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, ['start', 'end']) ||
-    !isNonNegativeInteger(value.start) ||
-    !isNonNegativeInteger(value.end) ||
-    value.end < value.start
-  ) {
-    return null;
-  }
-  return { start: value.start, end: value.end };
-}
-
-function parseTableSummary(value: unknown): TableSummary | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, ['index', 'rowCount', 'columnCount', 'headers']) ||
-    !isNonNegativeInteger(value.index) ||
-    !isNonNegativeInteger(value.rowCount) ||
-    !isNonNegativeInteger(value.columnCount)
-  ) {
-    return null;
-  }
-  const headers = parseArray(value.headers, (entry) =>
-    isBoundedString(entry, MCP_WIRE_LIMITS.labelCharacters) ? entry : null,
-  );
-  if (headers === null || headers.length > value.columnCount) return null;
-  return {
-    index: value.index,
-    rowCount: value.rowCount,
-    columnCount: value.columnCount,
-    headers,
-  };
-}
-
-function parseLinkSummary(value: unknown): LinkSummary | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, ['index', 'text', 'target']) ||
-    !isNonNegativeInteger(value.index) ||
-    !isBoundedString(value.text, MCP_WIRE_LIMITS.labelCharacters) ||
-    !isBoundedString(value.target, MCP_WIRE_LIMITS.uriCharacters, 1)
-  ) {
-    return null;
-  }
-  return { index: value.index, text: value.text, target: value.target };
-}
-
-function parseDocumentItemSummary(value: unknown): DocumentItemSummary | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, ['kind', 'index', 'label', 'blockIds']) ||
-    !isPreviewItemKind(value.kind) ||
-    !isNonNegativeInteger(value.index) ||
-    !isNullableBoundedString(value.label, MCP_WIRE_LIMITS.labelCharacters)
-  ) {
-    return null;
-  }
-  const blockIds = parseArray(value.blockIds, (entry) => (isIdentifier(entry) ? entry : null));
-  if (blockIds === null || new Set(blockIds).size !== blockIds.length) return null;
-  return { kind: value.kind, index: value.index, label: value.label, blockIds };
-}
-
-function parseAssetSummary(value: unknown): AssetSummary | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, ['path', 'mimeType', 'size', 'sha256', 'altText', 'credit', 'license'])
-  ) {
-    return null;
-  }
-  const path = parseNonRootWorkspacePath(value.path);
-  if (
-    path === null ||
-    !isMimeType(value.mimeType) ||
-    !isBoundedInteger(value.size, 0, MCP_WIRE_LIMITS.artifactBytes) ||
-    !(value.sha256 === null || isSha256(value.sha256)) ||
-    !isNullableBoundedString(value.altText, MCP_WIRE_LIMITS.labelCharacters) ||
-    !isNullableBoundedString(value.credit, MCP_WIRE_LIMITS.labelCharacters) ||
-    !isNullableBoundedString(value.license, MCP_WIRE_LIMITS.labelCharacters)
-  ) {
-    return null;
-  }
-  return {
-    path,
-    mimeType: value.mimeType,
-    size: value.size,
-    sha256: value.sha256,
-    altText: value.altText,
-    credit: value.credit,
-    license: value.license,
-  };
-}
-
-function parseThemeSummary(value: unknown): ThemeSummary | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, ['id', 'name', 'source', 'layouts']) ||
-    !isIdentifier(value.id) ||
-    !isBoundedString(value.name, MCP_WIRE_LIMITS.labelCharacters, 1) ||
-    !(value.source === 'built-in' || value.source === 'document' || value.source === 'inferred')
-  ) {
-    return null;
-  }
-  const layouts = parseStringArray(value.layouts, MCP_WIRE_LIMITS.labelCharacters);
-  if (layouts === null || new Set(layouts).size !== layouts.length) return null;
-  return { id: value.id, name: value.name, source: value.source, layouts };
-}
-
-function parseValidationSummary(value: unknown): ValidationSummary | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, ['errorCount', 'warningCount', 'infoCount']) ||
-    !isNonNegativeInteger(value.errorCount) ||
-    !isNonNegativeInteger(value.warningCount) ||
-    !isNonNegativeInteger(value.infoCount)
-  ) {
-    return null;
-  }
-  return {
-    errorCount: value.errorCount,
-    warningCount: value.warningCount,
-    infoCount: value.infoCount,
-  };
-}
-
-function parsePreviewItem(value: unknown): PreviewItem | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, ['kind', 'index', 'label', 'artifact', 'width', 'height']) ||
-    !isPreviewItemKind(value.kind) ||
-    !isNonNegativeInteger(value.index) ||
-    !isNullableBoundedString(value.label, MCP_WIRE_LIMITS.labelCharacters) ||
-    !isBoundedInteger(value.width, 1, MCP_WIRE_LIMITS.imageDimension) ||
-    !isBoundedInteger(value.height, 1, MCP_WIRE_LIMITS.imageDimension)
-  ) {
-    return null;
-  }
-  const artifact = parseArtifactRef(value.artifact);
-  if (artifact === null || !artifact.mimeType.startsWith('image/')) return null;
-  return {
-    kind: value.kind,
-    index: value.index,
-    label: value.label,
-    artifact,
-    width: value.width,
-    height: value.height,
-  };
-}
-
-function parseComparisonChange(value: unknown): ComparisonChange | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, ['category', 'status', 'path', 'message']) ||
-    !isComparisonCategory(value.category) ||
-    !isComparisonStatus(value.status) ||
-    !isNullableBoundedString(value.path, MCP_WIRE_LIMITS.pathCharacters) ||
-    !isBoundedString(value.message, MCP_WIRE_LIMITS.messageCharacters, 1)
-  ) {
-    return null;
-  }
-  return {
-    category: value.category,
-    status: value.status,
-    path: value.path,
-    message: value.message,
-  };
-}
-
-function parseComparisonMetric(value: unknown): ComparisonMetric | null {
-  if (
-    !isRecord(value) ||
-    !hasExactKeys(value, ['name', 'leftValue', 'rightValue', 'similarity']) ||
-    !isIdentifier(value.name) ||
-    !isFiniteNumber(value.leftValue) ||
-    !isFiniteNumber(value.rightValue) ||
-    !isBoundedNumber(value.similarity, 0, 1)
-  ) {
-    return null;
-  }
-  return {
-    name: value.name,
-    leftValue: value.leftValue,
-    rightValue: value.rightValue,
-    similarity: value.similarity,
-  };
-}
-
-function summarizeDiagnostics(diagnostics: readonly McpDiagnostic[]): ValidationSummary {
-  let errorCount = 0;
-  let warningCount = 0;
-  let infoCount = 0;
-  for (const diagnostic of diagnostics) {
-    if (diagnostic.severity === 'error') errorCount += diagnostic.count;
-    else if (diagnostic.severity === 'warning') warningCount += diagnostic.count;
-    else infoCount += diagnostic.count;
-  }
-  return { errorCount, warningCount, infoCount };
-}
-
-function parseArray<T>(
-  value: unknown,
-  parser: (entry: unknown) => T | null,
-  maximumEntries: number = MCP_WIRE_LIMITS.arrayEntries,
-): T[] | null {
-  if (!Array.isArray(value) || value.length > maximumEntries) return null;
-  const parsed: T[] = [];
-  for (const entry of value) {
-    const result = parser(entry);
-    if (result === null) return null;
-    parsed.push(result);
-  }
-  return parsed;
-}
-
-function parseStringArray(value: unknown, maximumCharacters: number): string[] | null {
-  if (!Array.isArray(value) || value.length > MCP_WIRE_LIMITS.arrayEntries) return null;
-  const parsed: string[] = [];
-  for (const entry of value) {
-    if (!isBoundedString(entry, maximumCharacters, 1)) return null;
-    parsed.push(entry);
-  }
-  return parsed;
-}
-
-function parseNullable<T>(
-  value: unknown,
-  parser: (entry: unknown) => T | null,
-): T | null | undefined {
-  if (value === null) return null;
-  return parser(value) ?? undefined;
-}
-
-function parseNonRootWorkspacePath(value: unknown): WorkspacePath | null {
-  if (
-    !isBoundedString(value, MCP_WIRE_LIMITS.pathCharacters, 1) ||
-    value.includes('\\') ||
-    value.startsWith('/') ||
-    value.endsWith('/') ||
-    value.includes('//')
-  ) {
-    return null;
-  }
-  const parsed = tryParseWorkspacePath(value);
-  return parsed !== null && parsed !== '' && parsed === value ? parsed : null;
-}
-
-function isArtifactUri(value: unknown, expectedId?: string): value is string {
-  if (!isBoundedString(value, MCP_WIRE_LIMITS.uriCharacters, 1)) return false;
-  try {
-    const url = new URL(value);
-    if (
-      url.protocol !== 'docblocks:' ||
-      url.hostname !== 'artifacts' ||
-      url.username !== '' ||
-      url.password !== '' ||
-      url.port !== '' ||
-      url.search !== '' ||
-      url.hash !== ''
-    ) {
-      return false;
-    }
-    const id = url.pathname.slice(1);
-    return (
-      !id.includes('/') &&
-      isIdentifier(id) &&
-      value === `docblocks://artifacts/${id}` &&
-      (expectedId === undefined || id === expectedId)
-    );
-  } catch {
-    return false;
-  }
-}
-
-function isSafeFilename(value: unknown): value is string {
-  return (
-    isBoundedString(value, MCP_WIRE_LIMITS.labelCharacters, 1) &&
-    value !== '.' &&
-    value !== '..' &&
-    !value.includes('/') &&
-    !value.includes('\\')
-  );
-}
-
-function isIsoTimestamp(value: unknown): value is string {
-  if (typeof value !== 'string' || !ISO_TIMESTAMP_PATTERN.test(value)) return false;
-  const timestamp = Date.parse(value);
-  return Number.isFinite(timestamp) && new Date(timestamp).toISOString() === value;
-}
-
-function isIdentifier(value: unknown): value is string {
-  return (
-    isBoundedString(value, MCP_WIRE_LIMITS.identifierCharacters, 1) &&
-    IDENTIFIER_PATTERN.test(value)
-  );
-}
-
-function isEngineName(value: unknown): value is string {
-  return (
-    isBoundedString(value, MCP_WIRE_LIMITS.identifierCharacters, 1) &&
-    ENGINE_NAME_PATTERN.test(value)
-  );
-}
-
-function isNullableIdentifier(value: unknown): value is string | null {
-  return value === null || isIdentifier(value);
-}
-
-function isFormat(value: unknown): value is string {
-  return isBoundedString(value, MCP_WIRE_LIMITS.formatCharacters, 1) && FORMAT_PATTERN.test(value);
-}
-
-function isMimeType(value: unknown): value is string {
-  return (
-    isBoundedString(value, MCP_WIRE_LIMITS.mimeTypeCharacters, 3) && MIME_TYPE_PATTERN.test(value)
-  );
-}
-
-function isSha256(value: unknown): value is string {
-  return typeof value === 'string' && SHA256_PATTERN.test(value);
-}
-
-function isAppliedOptionValue(value: unknown): value is string | number | boolean | null {
-  return (
-    value === null ||
-    typeof value === 'boolean' ||
-    isBoundedString(value, MCP_WIRE_LIMITS.messageCharacters) ||
-    isFiniteNumber(value)
-  );
-}
-
-function isDiagnosticSeverity(value: unknown): value is DiagnosticSeverity {
-  return value === 'info' || value === 'warning' || value === 'error';
-}
-
-function isDiagnosticStage(value: unknown): value is DiagnosticStage {
-  return (
-    value === 'resolve' ||
-    value === 'import' ||
-    value === 'parse' ||
-    value === 'inspect' ||
-    value === 'validate' ||
-    value === 'transform' ||
-    value === 'convert' ||
-    value === 'render' ||
-    value === 'export' ||
-    value === 'materialize' ||
-    value === 'compare'
-  );
-}
-
-function isConversionFidelity(value: unknown): value is ConversionFidelity {
-  return (
-    value === 'semantic' ||
-    value === 'editable-native' ||
-    value === 'rendered-fidelity' ||
-    value === 'hybrid'
-  );
-}
-
-function isPreviewItemKind(value: unknown): value is PreviewItem['kind'] {
-  return value === 'page' || value === 'slide' || value === 'sheet' || value === 'frame';
-}
-
-function isComparisonCategory(value: unknown): value is ComparisonChange['category'] {
-  return (
-    value === 'text' ||
-    value === 'structure' ||
-    value === 'table' ||
-    value === 'media' ||
-    value === 'theme' ||
-    value === 'layout' ||
-    value === 'metadata' ||
-    value === 'timing' ||
-    value === 'accessibility'
-  );
-}
-
-function isComparisonStatus(value: unknown): value is ComparisonChange['status'] {
-  return (
-    value === 'retained' ||
-    value === 'changed' ||
-    value === 'degraded' ||
-    value === 'omitted' ||
-    value === 'added'
-  );
-}
-
-function hasDuplicateNames(values: readonly { readonly name: string }[]): boolean {
-  return new Set(values.map((value) => value.name)).size !== values.length;
-}
-
-function hasDuplicateIds(values: readonly { readonly id: string }[]): boolean {
-  return new Set(values.map((value) => value.id)).size !== values.length;
-}
-
-function hasDuplicatePaths(values: readonly { readonly path: WorkspacePath }[]): boolean {
-  return new Set(values.map((value) => value.path)).size !== values.length;
-}
-
-function hasDuplicateIndexes(values: readonly { readonly index: number }[]): boolean {
-  return new Set(values.map((value) => value.index)).size !== values.length;
-}
-
-function hasDuplicateItemIndexes(values: readonly DocumentItemSummary[]): boolean {
-  return new Set(values.map((value) => `${value.kind}:${value.index}`)).size !== values.length;
-}
-
-function hasDuplicatePreviewIndexes(values: readonly PreviewItem[]): boolean {
-  const keys = values.map((value) => `${value.kind}:${value.index}`);
-  return new Set(keys).size !== keys.length;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-function hasExactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
-  const actual = Object.keys(value);
-  return (
-    actual.length === keys.length &&
-    keys.every((key) => Object.prototype.hasOwnProperty.call(value, key))
-  );
-}
-
-function isBoundedString(
-  value: unknown,
-  maximumCharacters: number,
-  minimumCharacters = 0,
-): value is string {
-  return (
-    typeof value === 'string' &&
-    value.length >= minimumCharacters &&
-    value.length <= maximumCharacters &&
-    ![...value].some((character) => {
-      const codePoint = character.codePointAt(0) ?? 0;
-      return codePoint === 0 || codePoint === 0x7f;
-    })
-  );
-}
-
-function isNullableBoundedString(
-  value: unknown,
-  maximumCharacters: number,
-): value is string | null {
-  return value === null || isBoundedString(value, maximumCharacters);
-}
-
-function isFiniteNumber(value: unknown): value is number {
-  return typeof value === 'number' && Number.isFinite(value);
-}
-
-function isBoundedNumber(value: unknown, minimum: number, maximum: number): value is number {
-  return isFiniteNumber(value) && value >= minimum && value <= maximum;
-}
-
-function isBoundedInteger(value: unknown, minimum: number, maximum: number): value is number {
-  return (
-    Number.isSafeInteger(value) && typeof value === 'number' && value >= minimum && value <= maximum
-  );
-}
-
-function isNonNegativeInteger(value: unknown): value is number {
-  return isBoundedInteger(value, 0, Number.MAX_SAFE_INTEGER);
-}
-
-function isNullableNonNegativeInteger(value: unknown): value is number | null {
-  return value === null || isNonNegativeInteger(value);
-}