@claudian-collab/protocol 3.2.0 → 3.2.1

package/dist/esm/CollabRequestTicketResponseCodecs.mjs

@@ -0,0 +1,353 @@
+import { COLLAB_LIMITS } from './CollabConstants.mjs';
+import { CollabError } from './CollabError.mjs';
+import { hasUtf8ByteLengthAtMost, isCollabGitOid, isCollabMemberId, isCollabOpaqueId, } from './CollabValidation.mjs';
+function decodeError(field) {
+    return new CollabError({
+        code: 'protocol-payload-invalid',
+        recoveryActions: ['retry'],
+        safeContext: { field },
+    });
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function record(value, field) {
+    if (!isRecord(value))
+        throw decodeError(field);
+    return value;
+}
+function assertJsonUtf8ByteLengthAtMost(value, maximum, field) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(value);
+    }
+    catch {
+        throw decodeError(field);
+    }
+    if (serialized === undefined
+        || !hasUtf8ByteLengthAtMost(serialized, maximum)) {
+        throw decodeError(field);
+    }
+}
+function string(value, field, maxLength, validate, unit = 'utf16') {
+    const candidate = value[field];
+    if (typeof candidate !== 'string'
+        || candidate.length === 0
+        || (unit === 'utf8'
+            ? !hasUtf8ByteLengthAtMost(candidate, maxLength)
+            : candidate.length > maxLength)
+        || (validate && !validate(candidate))) {
+        throw decodeError(field);
+    }
+    return candidate;
+}
+function text(value, field, maxLength, unit = 'utf16') {
+    const candidate = value[field];
+    if (typeof candidate !== 'string'
+        || (unit === 'utf8'
+            ? !hasUtf8ByteLengthAtMost(candidate, maxLength)
+            : candidate.length > maxLength))
+        throw decodeError(field);
+    return candidate;
+}
+function timestamp(value, field) {
+    const candidate = string(value, field, 64);
+    if (Number.isNaN(Date.parse(candidate)) || new Date(candidate).toISOString() !== candidate) {
+        throw decodeError(field);
+    }
+    return candidate;
+}
+function optionalTimestamp(value, field) {
+    return value[field] === undefined ? undefined : timestamp(value, field);
+}
+function nonNegativeInteger(value, field) {
+    const candidate = value[field];
+    if (typeof candidate !== 'number'
+        || !Number.isSafeInteger(candidate)
+        || candidate < 0) {
+        throw decodeError(field);
+    }
+    return candidate;
+}
+function boundedNonNegativeInteger(value, field, maximum) {
+    const candidate = nonNegativeInteger(value, field);
+    if (candidate > maximum)
+        throw decodeError(field);
+    return candidate;
+}
+function positiveInteger(value, field) {
+    const candidate = nonNegativeInteger(value, field);
+    if (candidate < 1)
+        throw decodeError(field);
+    return candidate;
+}
+function requestTicketRelation(value) {
+    const source = record(value, 'request.ticketRelations');
+    const kind = source.kind;
+    const state = source.state;
+    if ((kind !== 'references' && kind !== 'resolves')
+        || (state !== 'pending' && state !== 'accepted')) {
+        throw decodeError('request.ticketRelations');
+    }
+    return {
+        commitOid: string(source, 'commitOid', 64, isCollabGitOid),
+        id: string(source, 'id', 128, isCollabOpaqueId),
+        kind,
+        state,
+        ticketId: string(source, 'ticketId', 128, isCollabOpaqueId),
+        ticketNumber: positiveInteger(source, 'ticketNumber'),
+        ticketRevision: positiveInteger(source, 'ticketRevision'),
+        ticketTitle: string(source, 'ticketTitle', COLLAB_LIMITS.maxTicketTitleUtf16),
+    };
+}
+function changeRequest(value) {
+    const source = record(value, 'request');
+    const status = source.status;
+    if ((status !== 'open' && status !== 'merged' && status !== 'discarded')
+        || !Array.isArray(source.ticketRelations)
+        || source.ticketRelations.length > COLLAB_LIMITS.maxRequestTicketRelations) {
+        throw decodeError('request.status');
+    }
+    const mergedOid = source.mergedOid === undefined
+        ? undefined
+        : string(source, 'mergedOid', 64, isCollabGitOid);
+    return {
+        commentCount: boundedNonNegativeInteger(source, 'commentCount', COLLAB_LIMITS.maxRequestComments),
+        createdAt: timestamp(source, 'createdAt'),
+        description: text(source, 'description', COLLAB_LIMITS.maxRequestDescriptionBytes, 'utf8'),
+        firstBaseOid: string(source, 'firstBaseOid', 64, isCollabGitOid),
+        id: string(source, 'id', 128, isCollabOpaqueId),
+        latestHeadOid: string(source, 'latestHeadOid', 64, isCollabGitOid),
+        memberId: string(source, 'memberId', 64, isCollabMemberId),
+        ...(mergedOid ? { mergedOid } : {}),
+        revision: nonNegativeInteger(source, 'revision'),
+        status,
+        ticketRelations: source.ticketRelations.map(requestTicketRelation),
+        updatedAt: timestamp(source, 'updatedAt'),
+    };
+}
+function ticketSummary(value) {
+    const source = record(value, 'ticket');
+    const status = source.status;
+    const closedAt = optionalTimestamp(source, 'closedAt');
+    const closedByMemberId = source.closedByMemberId === undefined
+        ? undefined
+        : string(source, 'closedByMemberId', 64, isCollabMemberId);
+    if ((status !== 'open' && status !== 'closed')
+        || (status === 'open' && (closedAt !== undefined || closedByMemberId !== undefined))
+        || (status === 'closed' && (closedAt === undefined || closedByMemberId === undefined))) {
+        throw decodeError('ticket.status');
+    }
+    return {
+        acceptedRelationCount: boundedNonNegativeInteger(source, 'acceptedRelationCount', COLLAB_LIMITS.maxTicketAcceptedRelations),
+        authorMemberId: string(source, 'authorMemberId', 64, isCollabMemberId),
+        ...(closedAt && closedByMemberId ? { closedAt, closedByMemberId } : {}),
+        commentCount: boundedNonNegativeInteger(source, 'commentCount', COLLAB_LIMITS.maxTicketComments),
+        createdAt: timestamp(source, 'createdAt'),
+        id: string(source, 'id', 128, isCollabOpaqueId),
+        number: positiveInteger(source, 'number'),
+        revision: positiveInteger(source, 'revision'),
+        status,
+        title: string(source, 'title', COLLAB_LIMITS.maxTicketTitleUtf16),
+        updatedAt: timestamp(source, 'updatedAt'),
+    };
+}
+function ticketComment(value) {
+    const source = record(value, 'ticket.comment');
+    return {
+        authorMemberId: string(source, 'authorMemberId', 64, isCollabMemberId),
+        body: string(source, 'body', COLLAB_LIMITS.maxTicketCommentBytes, undefined, 'utf8'),
+        createdAt: timestamp(source, 'createdAt'),
+        id: string(source, 'id', 128, isCollabOpaqueId),
+        ticketId: string(source, 'ticketId', 128, isCollabOpaqueId),
+    };
+}
+function acceptedTicketRelation(value) {
+    const source = record(value, 'ticket.acceptedRelation');
+    const kind = source.kind;
+    if (kind !== 'references' && kind !== 'resolves') {
+        throw decodeError('ticket.acceptedRelation.kind');
+    }
+    return {
+        acceptedAt: timestamp(source, 'acceptedAt'),
+        acceptedMergeOid: string(source, 'acceptedMergeOid', 64, isCollabGitOid),
+        commitOid: string(source, 'commitOid', 64, isCollabGitOid),
+        id: string(source, 'id', 128, isCollabOpaqueId),
+        kind,
+        requestId: string(source, 'requestId', 128, isCollabOpaqueId),
+    };
+}
+function pageCursor(source) {
+    return source.nextCursor === undefined
+        ? undefined
+        : string(source, 'nextCursor', COLLAB_LIMITS.maxPageCursorUtf16);
+}
+function commentPage(value) {
+    const source = record(value, 'commentPage');
+    assertJsonUtf8ByteLengthAtMost(source, COLLAB_LIMITS.commentPageMaxUtf8Bytes, 'commentPage.bytes');
+    if (!Array.isArray(source.comments)
+        || source.comments.length > COLLAB_LIMITS.maxCommentPageSize) {
+        throw decodeError('commentPage');
+    }
+    const nextCursor = pageCursor(source);
+    return {
+        comments: source.comments.map(comment),
+        ...(nextCursor ? { nextCursor } : {}),
+    };
+}
+function ticketCommentPage(value) {
+    const source = record(value, 'ticketCommentPage');
+    assertJsonUtf8ByteLengthAtMost(source, COLLAB_LIMITS.commentPageMaxUtf8Bytes, 'ticketCommentPage.bytes');
+    if (!Array.isArray(source.comments)
+        || source.comments.length > COLLAB_LIMITS.maxCommentPageSize) {
+        throw decodeError('ticketCommentPage');
+    }
+    const nextCursor = pageCursor(source);
+    return {
+        comments: source.comments.map(ticketComment),
+        ...(nextCursor ? { nextCursor } : {}),
+    };
+}
+function acceptedRelationPage(value) {
+    const source = record(value, 'ticketAcceptedRelationPage');
+    assertJsonUtf8ByteLengthAtMost(source, COLLAB_LIMITS.relationPageMaxUtf8Bytes, 'ticketAcceptedRelationPage.bytes');
+    if (!Array.isArray(source.acceptedRelations)
+        || source.acceptedRelations.length > COLLAB_LIMITS.maxRelationsPerPage) {
+        throw decodeError('ticketAcceptedRelationPage');
+    }
+    const nextCursor = pageCursor(source);
+    return {
+        acceptedRelations: source.acceptedRelations.map(acceptedTicketRelation),
+        ...(nextCursor ? { nextCursor } : {}),
+    };
+}
+function ticketDetail(value) {
+    const source = record(value, 'ticketDetail');
+    assertJsonUtf8ByteLengthAtMost(source, COLLAB_LIMITS.detailMaxUtf8Bytes, 'ticketDetail.bytes');
+    if (!isRecord(source.comments)
+        || !isRecord(source.acceptedRelations)) {
+        throw decodeError('ticketDetail');
+    }
+    const decodedTicket = ticketSummary(source.ticket);
+    const comments = ticketCommentPage(source.comments);
+    if (comments.comments.some(commentValue => commentValue.ticketId !== decodedTicket.id)) {
+        throw decodeError('ticketDetail.comments');
+    }
+    const acceptedRelations = acceptedRelationPage(source.acceptedRelations);
+    return {
+        acceptedRelations,
+        body: string(source, 'body', COLLAB_LIMITS.maxTicketBodyBytes, undefined, 'utf8'),
+        comments,
+        ticket: decodedTicket,
+    };
+}
+function comment(value) {
+    const source = record(value, 'comment');
+    return {
+        authorMemberId: string(source, 'authorMemberId', 64, isCollabMemberId),
+        body: string(source, 'body', COLLAB_LIMITS.maxCommentBytes, undefined, 'utf8'),
+        createdAt: timestamp(source, 'createdAt'),
+        id: string(source, 'id', 128, isCollabOpaqueId),
+        requestId: string(source, 'requestId', 128, isCollabOpaqueId),
+    };
+}
+function envelopeData(value) {
+    return value;
+}
+export function decodeEnsureMyRequestResponse(value) {
+    const data = record(envelopeData(value), 'data');
+    return {
+        mainOid: string(data, 'mainOid', 64, isCollabGitOid),
+        request: changeRequest(data.request),
+    };
+}
+export function decodeRequestDetailResponse(value) {
+    const data = record(envelopeData(value), 'data');
+    assertJsonUtf8ByteLengthAtMost(data, COLLAB_LIMITS.detailMaxUtf8Bytes, 'requestDetail.bytes');
+    if (!isRecord(data.comments)
+        || data.changedFiles !== undefined) {
+        throw decodeError('requestDetail');
+    }
+    const decodedRequest = changeRequest(data.request);
+    const reviewedHeadOid = string(data, 'reviewedHeadOid', 64, isCollabGitOid);
+    const reviewCondition = data.reviewCondition;
+    const comments = commentPage(data.comments);
+    if (reviewedHeadOid !== decodedRequest.latestHeadOid
+        || !['clean', 'conflicting', 'stale'].includes(String(reviewCondition))
+        || comments.comments.some(item => item.requestId !== decodedRequest.id)) {
+        throw decodeError('requestDetail');
+    }
+    return {
+        comments,
+        currentMainOid: string(data, 'currentMainOid', 64, isCollabGitOid),
+        request: decodedRequest,
+        reviewCondition: reviewCondition,
+        reviewedHeadOid,
+    };
+}
+export function decodeCommentPageResponse(value) {
+    return commentPage(record(envelopeData(value), 'data'));
+}
+export function decodeTicketCommentPageResponse(value) {
+    return ticketCommentPage(record(envelopeData(value), 'data'));
+}
+export function decodeTicketAcceptedRelationPageResponse(value) {
+    return acceptedRelationPage(record(envelopeData(value), 'data'));
+}
+export function decodeCreateCommentResponse(value) {
+    const data = record(envelopeData(value), 'data');
+    const decodedRequest = changeRequest(data.request);
+    const decodedComment = comment(data.comment);
+    if (decodedComment.requestId !== decodedRequest.id
+        || decodedRequest.commentCount < 1) {
+        throw decodeError('commentResponse');
+    }
+    return { comment: decodedComment, request: decodedRequest };
+}
+export function decodeAcceptResponse(value) {
+    const data = record(envelopeData(value), 'data');
+    const mainOid = string(data, 'mainOid', 64, isCollabGitOid);
+    const mergeCommitOid = string(data, 'mergeCommitOid', 64, isCollabGitOid);
+    const decodedRequest = changeRequest(data.request);
+    if (mergeCommitOid !== mainOid
+        || decodedRequest.status !== 'merged'
+        || decodedRequest.mergedOid !== mainOid) {
+        throw decodeError('acceptResponse');
+    }
+    return { mainOid, mergeCommitOid, request: decodedRequest };
+}
+export function decodeTicketPageResponse(value) {
+    const data = record(envelopeData(value), 'data');
+    assertJsonUtf8ByteLengthAtMost(data, COLLAB_LIMITS.ticketPageMaxUtf8Bytes, 'ticketPage.bytes');
+    if (!Array.isArray(data.tickets)
+        || data.tickets.length > COLLAB_LIMITS.maxTicketPageSize)
+        throw decodeError('ticketPage');
+    const nextCursor = data.nextCursor === undefined
+        ? undefined
+        : string(data, 'nextCursor', 512);
+    return {
+        ...(nextCursor ? { nextCursor } : {}),
+        tickets: data.tickets.map(ticketSummary),
+    };
+}
+export function decodeTicketDetailResponse(value) {
+    return ticketDetail(envelopeData(value));
+}
+export function decodeCreateTicketResponse(value) {
+    return { ticket: ticketDetail(record(envelopeData(value), 'data').ticket) };
+}
+export function decodeTicketMutationResponse(value) {
+    return { ticket: ticketSummary(record(envelopeData(value), 'data').ticket) };
+}
+export function decodeTicketCommentResponse(value) {
+    const data = record(envelopeData(value), 'data');
+    const decodedTicket = ticketSummary(data.ticket);
+    const decodedComment = ticketComment(data.comment);
+    if (decodedComment.ticketId !== decodedTicket.id) {
+        throw decodeError('ticketCommentResponse');
+    }
+    return { comment: decodedComment, ticket: decodedTicket };
+}
+export function decodeUpdateRequestMetadataResponse(value) {
+    return { request: changeRequest(record(envelopeData(value), 'data').request) };
+}

package/dist/esm/CollabTicketReferenceParser.mjs

@@ -0,0 +1,52 @@
+import { COLLAB_LIMITS } from './CollabConstants.mjs';
+import { maskCollabMarkdownProse } from './CollabMarkdownProse.mjs';
+const CLOSING_KEYWORD_PATTERN = /(?:^|[^A-Za-z])(close|closes|closed|fix|fixes|fixed|resolve|resolves|resolved)[ \t]*:?[ \t]*$/i;
+const TICKET_REFERENCE_PATTERN = /(^|[^#0-9A-Za-z_])#([1-9][0-9]*)(?![#0-9A-Za-z_])/gm;
+function relationKindBefore(maskedDescription, referenceOffset) {
+    const prefix = maskedDescription.slice(0, referenceOffset);
+    return CLOSING_KEYWORD_PATTERN.test(prefix) ? 'resolves' : 'references';
+}
+export function parseCollabTicketReferences(description) {
+    if (new TextEncoder().encode(description).byteLength >
+        COLLAB_LIMITS.maxRequestDescriptionBytes) {
+        return { status: 'invalid', reason: 'description-too-large' };
+    }
+    const scanned = scanCollabTicketReferences(description);
+    if (scanned.status === 'invalid')
+        return scanned;
+    const references = new Map();
+    for (const token of scanned.tokens) {
+        const existing = references.get(token.ticketNumber);
+        if (existing !== 'resolves' || token.kind === 'resolves') {
+            references.set(token.ticketNumber, token.kind);
+        }
+    }
+    return {
+        status: 'ok',
+        references: [...references.entries()]
+            .sort(([left], [right]) => left - right)
+            .map(([ticketNumber, kind]) => ({ ticketNumber, kind })),
+    };
+}
+export function scanCollabTicketReferences(description) {
+    const prose = maskCollabMarkdownProse(description);
+    const tokens = [];
+    for (const match of prose.matchAll(TICKET_REFERENCE_PATTERN)) {
+        const prefix = match[1] ?? '';
+        const numberToken = match[2];
+        if (!numberToken || match.index === undefined)
+            continue;
+        const ticketNumber = Number(numberToken);
+        if (!Number.isSafeInteger(ticketNumber)) {
+            return { status: 'invalid', reason: 'ticket-number-out-of-range' };
+        }
+        const referenceOffset = match.index + prefix.length;
+        tokens.push({
+            from: referenceOffset,
+            kind: relationKindBefore(prose, referenceOffset),
+            ticketNumber,
+            to: referenceOffset + numberToken.length + 1,
+        });
+    }
+    return { status: 'ok', tokens };
+}

package/dist/esm/CollabValidation.mjs

@@ -0,0 +1,19 @@
+const COLLAB_PROJECT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const COLLAB_MEMBER_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const COLLAB_OPAQUE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+const COLLAB_GIT_OID_PATTERN = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
+export function isCollabProjectId(value) {
+    return typeof value === 'string' && COLLAB_PROJECT_ID_PATTERN.test(value);
+}
+export function isCollabMemberId(value) {
+    return typeof value === 'string' && COLLAB_MEMBER_ID_PATTERN.test(value);
+}
+export function isCollabOpaqueId(value) {
+    return typeof value === 'string' && COLLAB_OPAQUE_ID_PATTERN.test(value);
+}
+export function isCollabGitOid(value) {
+    return typeof value === 'string' && COLLAB_GIT_OID_PATTERN.test(value);
+}
+export function hasUtf8ByteLengthAtMost(value, maximum) {
+    return new TextEncoder().encode(value).byteLength <= maximum;
+}