diff-easy 0.1.0

package/dist/utils/commentImports.js

@@ -0,0 +1,386 @@
+import { createId } from './createId.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isValidIsoTimestamp(value) {
+    return Number.isFinite(Date.parse(value));
+}
+function normalizeTimestamp(value, fieldName) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'string' || value.trim().length === 0 || !isValidIsoTimestamp(value)) {
+        throw new Error(`Invalid comment import field: ${fieldName}`);
+    }
+    return value;
+}
+function normalizeLineRange(value) {
+    if (typeof value === 'number' && Number.isInteger(value) && value > 0) {
+        return value;
+    }
+    if (!isRecord(value)) {
+        throw new Error('Invalid comment import field: position.line');
+    }
+    const start = value.start;
+    const end = value.end;
+    if (typeof start !== 'number' ||
+        typeof end !== 'number' ||
+        !Number.isInteger(start) ||
+        !Number.isInteger(end) ||
+        start <= 0 ||
+        end <= 0 ||
+        start > end) {
+        throw new Error('Invalid comment import field: position.line');
+    }
+    return { start, end };
+}
+function normalizePosition(value) {
+    if (!isRecord(value)) {
+        throw new Error('Invalid comment import field: position');
+    }
+    if (value.side !== 'old' && value.side !== 'new') {
+        throw new Error('Invalid comment import field: position.side');
+    }
+    return {
+        side: value.side,
+        line: normalizeLineRange(value.line),
+    };
+}
+function normalizeCodeSnapshot(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!isRecord(value) || typeof value.content !== 'string') {
+        throw new Error('Invalid comment import field: codeSnapshot');
+    }
+    if (value.language !== undefined && typeof value.language !== 'string') {
+        throw new Error('Invalid comment import field: codeSnapshot.language');
+    }
+    return {
+        content: value.content,
+        language: value.language,
+    };
+}
+function normalizeOptionalString(value, fieldName) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'string') {
+        throw new Error(`Invalid comment import field: ${fieldName}`);
+    }
+    return value;
+}
+function normalizeRequiredBody(value) {
+    if (typeof value !== 'string') {
+        throw new Error('Invalid comment import field: body');
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new Error('Invalid comment import field: body');
+    }
+    return trimmed;
+}
+function normalizeCommentImportEntry(value) {
+    if (!isRecord(value)) {
+        throw new Error('Comment import must be an object');
+    }
+    if (value.type !== 'thread' && value.type !== 'reply') {
+        throw new Error('Invalid comment import field: type');
+    }
+    if (typeof value.filePath !== 'string' || value.filePath.trim().length === 0) {
+        throw new Error('Invalid comment import field: filePath');
+    }
+    const createdAt = normalizeTimestamp(value.createdAt, 'createdAt');
+    const updatedAt = normalizeTimestamp(value.updatedAt, 'updatedAt');
+    const normalized = {
+        type: value.type,
+        id: normalizeOptionalString(value.id, 'id'),
+        filePath: value.filePath,
+        position: normalizePosition(value.position),
+        body: normalizeRequiredBody(value.body),
+        author: normalizeOptionalString(value.author, 'author'),
+        createdAt,
+        updatedAt,
+        codeSnapshot: normalizeCodeSnapshot(value.codeSnapshot),
+    };
+    return normalized;
+}
+export function normalizeCommentImports(input) {
+    if (Array.isArray(input)) {
+        return input.map((entry) => normalizeCommentImportEntry(entry));
+    }
+    return [normalizeCommentImportEntry(input)];
+}
+export function parseCommentImportValue(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new Error('Invalid --comment JSON');
+    }
+    return normalizeCommentImports(parsed);
+}
+function getPositionKey(position) {
+    if (typeof position.line === 'number') {
+        return `${position.side}:${position.line}`;
+    }
+    return `${position.side}:${position.line.start}-${position.line.end}`;
+}
+function positionsMatch(left, right) {
+    return getPositionKey(left) === getPositionKey(right);
+}
+function normalizeAuthor(author) {
+    return author?.trim() || '';
+}
+function messageMatchesImport(message, commentImport, includeId = true) {
+    if (includeId && commentImport.id && message.id === commentImport.id) {
+        return true;
+    }
+    if (normalizeAuthor(message.author) !== normalizeAuthor(commentImport.author)) {
+        return false;
+    }
+    if (message.body !== commentImport.body) {
+        return false;
+    }
+    if (commentImport.createdAt && message.createdAt !== commentImport.createdAt) {
+        return false;
+    }
+    return true;
+}
+function rootThreadMatchesImport(thread, commentImport) {
+    if (commentImport.id && thread.id === commentImport.id) {
+        return true;
+    }
+    if (thread.filePath !== commentImport.filePath ||
+        !positionsMatch(thread.position, commentImport.position)) {
+        return false;
+    }
+    const rootMessage = thread.messages[0];
+    if (!rootMessage) {
+        return false;
+    }
+    return messageMatchesImport(rootMessage, commentImport, true);
+}
+function toThreadTimestamp(commentImport, now) {
+    const createdAt = commentImport.createdAt ?? now;
+    const updatedAt = commentImport.updatedAt ?? createdAt;
+    return { createdAt, updatedAt };
+}
+function maxIsoTimestamp(left, right) {
+    return left.localeCompare(right) >= 0 ? left : right;
+}
+function sortByNewestThread(left, right) {
+    return right.updatedAt.localeCompare(left.updatedAt);
+}
+function createImportedThread(commentImport, now) {
+    const { createdAt, updatedAt } = toThreadTimestamp(commentImport, now);
+    const threadId = commentImport.id ?? createId();
+    return {
+        id: threadId,
+        filePath: commentImport.filePath,
+        createdAt,
+        updatedAt,
+        position: commentImport.position,
+        codeSnapshot: commentImport.codeSnapshot,
+        messages: [
+            {
+                id: commentImport.id ?? threadId,
+                body: commentImport.body,
+                author: commentImport.author,
+                createdAt,
+                updatedAt,
+            },
+        ],
+    };
+}
+function createImportedReply(commentImport, now) {
+    const { createdAt, updatedAt } = toThreadTimestamp(commentImport, now);
+    return {
+        id: commentImport.id ?? createId(),
+        body: commentImport.body,
+        author: commentImport.author,
+        createdAt,
+        updatedAt,
+    };
+}
+function cloneLineRange(line) {
+    if (typeof line === 'number') {
+        return line;
+    }
+    return {
+        start: line.start,
+        end: line.end,
+    };
+}
+function clonePosition(position) {
+    return {
+        side: position.side,
+        line: cloneLineRange(position.line),
+    };
+}
+function cloneCodeSnapshot(snapshot) {
+    if (!snapshot) {
+        return undefined;
+    }
+    return {
+        content: snapshot.content,
+        language: snapshot.language,
+    };
+}
+function cloneMessage(message) {
+    return {
+        id: message.id,
+        body: message.body,
+        author: message.author,
+        createdAt: message.createdAt,
+        updatedAt: message.updatedAt,
+    };
+}
+function cloneThread(thread) {
+    return {
+        id: thread.id,
+        filePath: thread.filePath,
+        createdAt: thread.createdAt,
+        updatedAt: thread.updatedAt,
+        position: clonePosition(thread.position),
+        codeSnapshot: cloneCodeSnapshot(thread.codeSnapshot),
+        messages: thread.messages.map(cloneMessage),
+    };
+}
+function messagesMatch(left, right) {
+    if (left.id === right.id) {
+        return true;
+    }
+    if (normalizeAuthor(left.author) !== normalizeAuthor(right.author)) {
+        return false;
+    }
+    return left.body === right.body && left.createdAt === right.createdAt;
+}
+function threadsMatch(left, right) {
+    if (left.id === right.id) {
+        return true;
+    }
+    if (left.filePath !== right.filePath || !positionsMatch(left.position, right.position)) {
+        return false;
+    }
+    const leftRoot = left.messages[0];
+    const rightRoot = right.messages[0];
+    if (!leftRoot || !rightRoot) {
+        return false;
+    }
+    return messagesMatch(leftRoot, rightRoot);
+}
+function sortReplies(left, right) {
+    const createdAtOrder = left.createdAt.localeCompare(right.createdAt);
+    if (createdAtOrder !== 0) {
+        return createdAtOrder;
+    }
+    return left.id.localeCompare(right.id);
+}
+function pickNewerMessage(existingMessage, incomingMessage) {
+    if (incomingMessage.updatedAt.localeCompare(existingMessage.updatedAt) >= 0) {
+        return cloneMessage(incomingMessage);
+    }
+    return cloneMessage(existingMessage);
+}
+function mergeThread(existingThread, incomingThread) {
+    const mergedMessages = existingThread.messages.map(cloneMessage);
+    for (const incomingMessage of incomingThread.messages) {
+        const matchIndex = mergedMessages.findIndex((message) => messagesMatch(message, incomingMessage));
+        if (matchIndex >= 0) {
+            mergedMessages[matchIndex] = pickNewerMessage(mergedMessages[matchIndex], incomingMessage);
+            continue;
+        }
+        mergedMessages.push(cloneMessage(incomingMessage));
+    }
+    const [rootMessage, ...replyMessages] = mergedMessages;
+    const orderedMessages = rootMessage
+        ? [rootMessage, ...replyMessages.sort(sortReplies)]
+        : replyMessages.sort(sortReplies);
+    const updatedAt = orderedMessages.reduce((latest, message) => maxIsoTimestamp(latest, message.updatedAt), maxIsoTimestamp(existingThread.updatedAt, incomingThread.updatedAt));
+    return {
+        ...cloneThread(existingThread),
+        createdAt: existingThread.createdAt.localeCompare(incomingThread.createdAt) <= 0
+            ? existingThread.createdAt
+            : incomingThread.createdAt,
+        updatedAt,
+        position: clonePosition(existingThread.position),
+        codeSnapshot: cloneCodeSnapshot(incomingThread.codeSnapshot ?? existingThread.codeSnapshot),
+        messages: orderedMessages,
+    };
+}
+export function mergeCommentThreads(existingThreads, incomingThreads) {
+    const threads = existingThreads.map(cloneThread);
+    for (const incomingThread of incomingThreads) {
+        const existingIndex = threads.findIndex((thread) => threadsMatch(thread, incomingThread));
+        if (existingIndex < 0) {
+            threads.push(cloneThread(incomingThread));
+            continue;
+        }
+        threads[existingIndex] = mergeThread(threads[existingIndex], incomingThread);
+    }
+    return { threads, warnings: [] };
+}
+function serializeLineRange(line) {
+    if (typeof line === 'number') {
+        return line;
+    }
+    return { start: line.start, end: line.end };
+}
+export function serializeCommentImports(commentImports) {
+    return JSON.stringify(commentImports.map((commentImport) => ({
+        type: commentImport.type,
+        id: commentImport.id,
+        filePath: commentImport.filePath,
+        position: {
+            side: commentImport.position.side,
+            line: serializeLineRange(commentImport.position.line),
+        },
+        body: commentImport.body,
+        author: commentImport.author,
+        createdAt: commentImport.createdAt,
+        updatedAt: commentImport.updatedAt,
+        codeSnapshot: commentImport.codeSnapshot
+            ? {
+                content: commentImport.codeSnapshot.content,
+                language: commentImport.codeSnapshot.language,
+            }
+            : undefined,
+    })));
+}
+export function mergeCommentImports(existingThreads, commentImports) {
+    // Clone (don't shallow-copy) so appending a reply doesn't mutate the caller's
+    // thread objects in place — otherwise the server can't detect the change and
+    // skips the commentsChanged broadcast, leaving open browsers stale.
+    const threads = existingThreads.map(cloneThread);
+    const warnings = [];
+    for (const commentImport of commentImports) {
+        const now = new Date().toISOString();
+        if (commentImport.type === 'thread') {
+            const hasDuplicate = threads.some((thread) => rootThreadMatchesImport(thread, commentImport));
+            if (hasDuplicate) {
+                continue;
+            }
+            threads.push(createImportedThread(commentImport, now));
+            continue;
+        }
+        const targetThreads = threads
+            .filter((thread) => thread.filePath === commentImport.filePath &&
+            positionsMatch(thread.position, commentImport.position))
+            .sort(sortByNewestThread);
+        const targetThread = targetThreads[0];
+        if (!targetThread) {
+            warnings.push(`Skipped reply import for ${commentImport.filePath}:${getPositionKey(commentImport.position)} because no matching thread was found.`);
+            continue;
+        }
+        const hasDuplicateReply = targetThread.messages.some((message) => messageMatchesImport(message, commentImport, true));
+        if (hasDuplicateReply) {
+            continue;
+        }
+        const importedReply = createImportedReply(commentImport, now);
+        targetThread.messages = [...targetThread.messages, importedReply];
+        targetThread.updatedAt = maxIsoTimestamp(targetThread.updatedAt, importedReply.updatedAt);
+    }
+    return { threads, warnings };
+}

package/dist/utils/createId.d.ts

@@ -0,0 +1 @@
+export declare function createId(): string;

package/dist/utils/createId.js

@@ -0,0 +1,5 @@
+const ID_ALPHABET = 'abcdefghijklmnopqrstuvwxyz0123456789';
+const ID_LENGTH = 16;
+export function createId() {
+    return Array.from({ length: ID_LENGTH }, () => ID_ALPHABET[Math.floor(Math.random() * ID_ALPHABET.length)]).join('');
+}

package/dist/utils/diffMode.d.ts

@@ -0,0 +1,3 @@
+import type { DiffViewMode } from '../types/diff.js';
+export declare const DEFAULT_DIFF_VIEW_MODE: DiffViewMode;
+export declare function normalizeDiffViewMode(mode?: string | null): DiffViewMode;

package/dist/utils/diffMode.js

@@ -0,0 +1,13 @@
+export const DEFAULT_DIFF_VIEW_MODE = 'split';
+export function normalizeDiffViewMode(mode) {
+    switch (mode) {
+        case 'split':
+        case 'side-by-side':
+            return 'split';
+        case 'unified':
+        case 'inline':
+            return 'unified';
+        default:
+            return DEFAULT_DIFF_VIEW_MODE;
+    }
+}

package/dist/utils/diffSelection.d.ts

@@ -0,0 +1,13 @@
+import type { BaseMode, DiffSelection } from '../types/diff.js';
+export declare function normalizeBaseMode(baseMode?: BaseMode): BaseMode;
+export declare function createDiffSelection(baseCommitish: string, targetCommitish: string, baseMode?: BaseMode): DiffSelection;
+export declare function diffSelectionsEqual(left: DiffSelection | null | undefined, right: DiffSelection | null | undefined): boolean;
+export declare function getDiffSelectionKey(selection: DiffSelection): string;
+/**
+ * Working-tree sentinel targets whose diff is *mutable* — it depends on the
+ * current working tree / index, not just the ref. Re-selecting one must refetch
+ * (an identical selection can now have different content), unlike an immutable
+ * commit range where an unchanged selection can be safely skipped.
+ */
+export declare function isWorkingTreeTarget(targetCommitish: string): boolean;
+export declare function getMergeBaseTargetRef(targetCommitish: string): string;

package/dist/utils/diffSelection.js

@@ -0,0 +1,39 @@
+export function normalizeBaseMode(baseMode) {
+    return baseMode ?? 'direct';
+}
+export function createDiffSelection(baseCommitish, targetCommitish, baseMode) {
+    if (normalizeBaseMode(baseMode) === 'merge-base') {
+        return {
+            baseCommitish,
+            targetCommitish,
+            baseMode: 'merge-base',
+        };
+    }
+    return {
+        baseCommitish,
+        targetCommitish,
+    };
+}
+export function diffSelectionsEqual(left, right) {
+    return (left?.baseCommitish === right?.baseCommitish &&
+        left?.targetCommitish === right?.targetCommitish &&
+        normalizeBaseMode(left?.baseMode) === normalizeBaseMode(right?.baseMode));
+}
+export function getDiffSelectionKey(selection) {
+    return `${selection.baseCommitish}:${selection.targetCommitish}:${normalizeBaseMode(selection.baseMode)}`;
+}
+/**
+ * Working-tree sentinel targets whose diff is *mutable* — it depends on the
+ * current working tree / index, not just the ref. Re-selecting one must refetch
+ * (an identical selection can now have different content), unlike an immutable
+ * commit range where an unchanged selection can be safely skipped.
+ */
+export function isWorkingTreeTarget(targetCommitish) {
+    return targetCommitish === '.' || targetCommitish === 'staged' || targetCommitish === 'working';
+}
+export function getMergeBaseTargetRef(targetCommitish) {
+    if (targetCommitish === '.' || targetCommitish === 'staged' || targetCommitish === 'working') {
+        return 'HEAD';
+    }
+    return targetCommitish;
+}

package/dist/utils/editorOptions.d.ts

@@ -0,0 +1,60 @@
+export type EditorOptionId = 'vscode' | 'cursor' | 'zed' | 'textmate' | 'bbedit' | 'emacs' | 'macvim' | 'sublime' | 'nova' | 'custom' | 'none';
+interface EditorOption {
+    readonly id: EditorOptionId;
+    readonly label: string;
+    /**
+     * Executable to run. Empty string for the `custom` placeholder (filled in by
+     * the user) and for `none` (open-in-editor disabled).
+     */
+    readonly command: string;
+    /**
+     * Whitespace-separated argument template. Supports the `%file` and `%line`
+     * placeholders. Parsed just before spawning so quoted segments survive:
+     * e.g. `'-l %line "%file"'`.
+     */
+    readonly argsTemplate: string;
+}
+export declare const CUSTOM_EDITOR_ID: EditorOptionId;
+export declare const NONE_EDITOR_ID: EditorOptionId;
+export declare const DEFAULT_EDITOR_ID: EditorOptionId;
+export declare const EDITOR_OPTIONS: readonly [EditorOption, ...EditorOption[]];
+export declare const DEFAULT_EDITOR_OPTION: EditorOption;
+/**
+ * Case-insensitive lookup by id. Used mostly for the `DIFIT_EDITOR` / `EDITOR`
+ * environment-variable fallback on the server; the browser UI passes the full
+ * `{id, command, argsTemplate}` shape so it does not rely on this helper.
+ */
+export declare const resolveEditorOption: (input?: string) => EditorOption;
+/**
+ * Tokenise a user-supplied arguments template string into individual CLI
+ * arguments. Supports single and double quoted segments so paths and flags
+ * containing spaces can be preserved.
+ *
+ * Inside double-quoted segments `\"` decodes to a literal `"` and `\\` to a
+ * literal `\`, mirroring common shell intuition. Other `\x` sequences pass
+ * through untouched so Lisp/regex fragments like `\s` or `\$` stay intact.
+ * Single-quoted segments are fully literal. The template is handed to
+ * `spawn` as argv directly – no shell is involved.
+ */
+export declare const parseEditorArgsTemplate: (template: string | undefined | null) => string[];
+interface EditorSpawnSpec {
+    readonly command: string;
+    readonly args: readonly string[];
+}
+interface BuildEditorSpawnSpecInput {
+    readonly command: string;
+    readonly argsTemplate: string;
+    readonly filePath: string;
+    readonly lineNumber: number | null;
+}
+/**
+ * Build the final `{ command, args }` tuple to hand to `child_process.spawn`.
+ * Returns `null` when the command is empty so callers can surface a clear
+ * "not configured" error instead of spawning an empty process.
+ *
+ * `%file` and `%line` are substituted as-is inside each token, so composite
+ * tokens such as `"%file:%line"` become `"/abs/file.ts:42"`. When no line
+ * number is available the substitution falls back to `1`.
+ */
+export declare const buildEditorSpawnSpec: (input: BuildEditorSpawnSpecInput) => EditorSpawnSpec | null;
+export {};