@critical-path/core 0.20.2 → 0.21.0

package/src/utils/fractional-index.ts

@@ -0,0 +1,260 @@
+/**
+ * Fractional Lexical Indexing Utility
+ *
+ * Deterministic Base-62 fractional indexing for ordered lists and swimlane task sequences.
+ * Produces lexicographically sortable strings (`orderIndex`) that allow infinite insertion
+ * between any two items without floating-point precision loss.
+ */
+
+export const BASE_62 = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+
+/**
+ * Encodes a non-negative integer into Base-62.
+ */
+function toBase62(n: number): string {
+  if (n === 0) return '0';
+  let s = '';
+  let curr = n;
+  while (curr > 0) {
+    s = BASE_62[curr % 62] + s;
+    curr = Math.floor(curr / 62);
+  }
+  return s;
+}
+
+/**
+ * Decodes a Base-62 string into a non-negative integer.
+ */
+function fromBase62(s: string): number {
+  let n = 0;
+  for (let i = 0; i < s.length; i++) {
+    const idx = BASE_62.indexOf(s[i]);
+    if (idx === -1) return 0;
+    n = n * 62 + idx;
+  }
+  return n;
+}
+
+/**
+ * Encodes an integer into a prefix-encoded string such that standard
+ * string comparison strictly matches integer comparison.
+ *
+ * Non-negative integers (0, 1, 2, ...):
+ *   Prefix 'a'-'z' specifies the digit count (1 to 26 digits).
+ *   0 -> "a0", 1 -> "a1", 61 -> "az", 62 -> "b10", ...
+ *
+ * Negative integers (-1, -2, ...):
+ *   Prefix 'Z'-'A' specifies inverted digit count with inverted digits.
+ *   -1 -> "Zz", -2 -> "Zy", ...
+ */
+export function encodeInteger(n: number): string {
+  if (n >= 0) {
+    const digits = toBase62(n);
+    const prefixCode = 97 + digits.length - 1; // 97 is 'a'
+    const prefix = String.fromCharCode(Math.min(prefixCode, 122)); // clamp to 'z'
+    return prefix + digits;
+  } else {
+    const pos = -n - 1;
+    const digits = toBase62(pos);
+    let inverted = '';
+    for (let i = 0; i < digits.length; i++) {
+      const idx = BASE_62.indexOf(digits[i]);
+      inverted += BASE_62[61 - idx];
+    }
+    const prefixCode = 90 - (digits.length - 1); // 90 is 'Z'
+    const prefix = String.fromCharCode(Math.max(prefixCode, 65)); // clamp to 'A'
+    return prefix + inverted;
+  }
+}
+
+/**
+ * Decodes a prefix-encoded integer string back into a number.
+ */
+export function decodeInteger(s: string): number {
+  if (!s || s.length < 2) return 0;
+  const prefix = s[0];
+  if (prefix >= 'a' && prefix <= 'z') {
+    const len = prefix.charCodeAt(0) - 97 + 1;
+    const digits = s.slice(1, 1 + len);
+    return fromBase62(digits);
+  } else if (prefix >= 'A' && prefix <= 'Z') {
+    const len = 90 - prefix.charCodeAt(0) + 1;
+    const inverted = s.slice(1, 1 + len);
+    let digits = '';
+    for (let i = 0; i < inverted.length; i++) {
+      const idx = BASE_62.indexOf(inverted[i]);
+      digits += idx !== -1 ? BASE_62[61 - idx] : '0';
+    }
+    const pos = fromBase62(digits);
+    return -pos - 1;
+  }
+  return 0;
+}
+
+/**
+ * Extracts the integer component from an order key.
+ */
+export function getIntegerPart(key: string): string {
+  if (!key || key.length < 2) return 'a0';
+  const prefix = key[0];
+  if (prefix >= 'a' && prefix <= 'z') {
+    const len = prefix.charCodeAt(0) - 97 + 1;
+    return key.slice(0, Math.min(key.length, 1 + len));
+  } else if (prefix >= 'A' && prefix <= 'Z') {
+    const len = 90 - prefix.charCodeAt(0) + 1;
+    return key.slice(0, Math.min(key.length, 1 + len));
+  }
+  return 'a0';
+}
+
+/**
+ * Computes a fractional midpoint suffix between suffixA and suffixB.
+ */
+function midpointSuffix(a: string, b: string | null): string {
+  let i = 0;
+  while (i < a.length && b !== null && i < b.length && a[i] === b[i]) {
+    i++;
+  }
+
+  const common = a.slice(0, i);
+  const charA = i < a.length ? a[i] : null;
+  const charB = b !== null && i < b.length ? b[i] : null;
+
+  const digitA = charA !== null ? BASE_62.indexOf(charA) : 0;
+  const digitB = charB !== null ? BASE_62.indexOf(charB) : BASE_62.length;
+
+  if (digitB - digitA > 1) {
+    const mid = Math.floor((digitA + digitB) / 2);
+    return common + BASE_62[mid];
+  }
+
+  if (charA !== null) {
+    const restA = a.slice(i + 1);
+    const restB = b !== null && i < b.length && charA === charB ? b.slice(i + 1) : null;
+    return common + charA + midpointSuffix(restA, restB);
+  }
+
+  if (b !== null && i < b.length) {
+    if (digitB === 0) {
+      const restB = b.slice(i + 1);
+      return common + '0' + midpointSuffix('', restB);
+    }
+  }
+
+  return common + 'V';
+}
+
+/**
+ * Generates a default initial order key for an index with optional spacing.
+ * E.g. index 0 -> "a0", index 1 (spacing 2) -> "a2", index 2 -> "a4"
+ */
+export function getInitialKey(index: number, spacing: number = 2): string {
+  return encodeInteger(Math.max(0, index) * Math.max(1, spacing));
+}
+
+/**
+ * Generates a single key strictly between keys `a` and `b` (a < key < b).
+ * Handles null/undefined for lower and upper bounds.
+ */
+export function generateKeyBetween(
+  a: string | null | undefined,
+  b: string | null | undefined
+): string {
+  const hasA = a !== null && a !== undefined && a !== '';
+  const hasB = b !== null && b !== undefined && b !== '';
+
+  if (!hasA && !hasB) {
+    return 'a0';
+  }
+
+  if (!hasA && hasB) {
+    const intB = getIntegerPart(b!);
+    if (intB === b) {
+      const valB = decodeInteger(intB);
+      return encodeInteger(valB - 1);
+    }
+    // If b has fractional suffix (e.g. "a0V"), integer part is already strictly smaller than b
+    return intB;
+  }
+
+  if (hasA && !hasB) {
+    const intA = getIntegerPart(a!);
+    const valA = decodeInteger(intA);
+    return encodeInteger(valA + 1);
+  }
+
+  // Both a and b are present
+  if (a! >= b!) {
+    // Graceful fallback for inverted or equal keys
+    return a! + 'V';
+  }
+
+  const intA = getIntegerPart(a!);
+  const intB = getIntegerPart(b!);
+
+  if (intA !== intB) {
+    const valA = decodeInteger(intA);
+    const valB = decodeInteger(intB);
+
+    if (valB - valA > 1) {
+      const midVal = Math.floor((valA + valB) / 2);
+      return encodeInteger(midVal);
+    }
+
+    if (valB - valA === 1) {
+      const suffixA = a!.slice(intA.length);
+      return intA + midpointSuffix(suffixA, null);
+    }
+  }
+
+  // Same integer part or fractional subdivision
+  const suffixA = a!.slice(intA.length);
+  const suffixB = b!.slice(intB.length);
+  return intA + midpointSuffix(suffixA, suffixB);
+}
+
+/**
+ * Generates `count` keys in strictly ascending order between keys `a` and `b`.
+ * Uses a balanced divide-and-conquer partition to guarantee even spacing.
+ */
+export function generateNKeysBetween(
+  a: string | null | undefined,
+  b: string | null | undefined,
+  count: number
+): string[] {
+  if (count <= 0) return [];
+  if (count === 1) return [generateKeyBetween(a, b)];
+
+  const result: string[] = new Array(count);
+
+  function fill(
+    leftKey: string | null | undefined,
+    rightKey: string | null | undefined,
+    startIdx: number,
+    endIdx: number
+  ) {
+    if (startIdx > endIdx) return;
+    const midIdx = Math.floor((startIdx + endIdx) / 2);
+    const midKey = generateKeyBetween(leftKey, rightKey);
+    result[midIdx] = midKey;
+    fill(leftKey, midKey, startIdx, midIdx - 1);
+    fill(midKey, rightKey, midIdx + 1, endIdx);
+  }
+
+  fill(a, b, 0, count - 1);
+  return result;
+}
+
+/**
+ * Standard comparator for fractional order indices.
+ * Uses strict code-point comparison matching Firestore, SQLite, and JavaScript array.sort().
+ */
+export function compareOrderIndices(
+  a: string | null | undefined,
+  b: string | null | undefined
+): number {
+  if (!a && !b) return 0;
+  if (!a) return 1;
+  if (!b) return -1;
+  return a < b ? -1 : a > b ? 1 : 0;
+}

package/src/utils/index.ts

@@ -2,4 +2,6 @@ export * from './status.js';
 export * from './key.js';
 export * from './workflow.js';
 export * from './mentions.js';
+export * from './fractional-index.js';
+
 

package/src/utils/key.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { generateProjectKey, validateProjectKey, formatTaskKey } from './key.js';
+import { generateProjectKey, validateProjectKey, formatTaskKey, isTempTaskId } from './key.js';
 
 describe('Project Key Utilities', () => {
   describe('generateProjectKey', () => {
@@ -52,4 +52,25 @@ describe('Project Key Utilities', () => {
       expect(formatTaskKey('', 10)).toBe('TASK-10');
     });
   });
+
+  describe('isTempTaskId', () => {
+    it('detects temp_ prefixed IDs', () => {
+      expect(isTempTaskId('temp_123456_abc')).toBe(true);
+      expect(isTempTaskId('#temp_123456_abc')).toBe(true);
+    });
+
+    it('detects temp- prefixed IDs', () => {
+      expect(isTempTaskId('temp-task-1')).toBe(true);
+      expect(isTempTaskId('#temp-task-1')).toBe(true);
+    });
+
+    it('returns false for permanent or invalid IDs', () => {
+      expect(isTempTaskId('task_123')).toBe(false);
+      expect(isTempTaskId('PROJ-1')).toBe(false);
+      expect(isTempTaskId(null)).toBe(false);
+      expect(isTempTaskId(undefined)).toBe(false);
+      expect(isTempTaskId('')).toBe(false);
+    });
+  });
 });
+

package/src/utils/key.ts

@@ -49,3 +49,14 @@ export function formatTaskKey(projectKey: string, taskNumber: number): string {
   const prefix = projectKey ? projectKey.toUpperCase() : 'TASK';
   return `${prefix}-${taskNumber}`;
 }
+
+/**
+ * Checks whether a given task ID represents a temporary/optimistic task
+ * (e.g. temp_1790... or temp-task-...) while it is actively being created.
+ */
+export function isTempTaskId(id?: string | null): boolean {
+  if (!id || typeof id !== 'string') return false;
+  const clean = id.trim().replace(/^#/, '');
+  return clean.startsWith('temp_') || clean.startsWith('temp-');
+}
+

package/src/utils/mentions.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { extractMentions, parseMentionSegments } from './mentions.js';
+import { extractMentions, parseMentionSegments, stripMarkdownCode } from './mentions.js';
 
 describe('mentions utility', () => {
   describe('extractMentions', () => {
@@ -37,6 +37,42 @@ describe('mentions utility', () => {
       const text = 'Check with @turquoise. Then ping @john.doe! Also ask @coordinator, and @"Jane Doe".';
       expect(extractMentions(text)).toEqual(['turquoise', 'john.doe', 'coordinator', 'Jane Doe']);
     });
+
+    it('suppresses mentions inside fenced code blocks and inline backticks (UCH-128, UCH-138)', () => {
+      const markdown = `
+Hey @alice, please review this test output:
+\`\`\`ts
+import { describe } from '@vitest/runner';
+// mention in code comment: @bob
+const handler = () => '@charlie';
+\`\`\`
+Also do not match \`@david\` in inline backticks or ~~~@eva~~~ in tilde fences.
+Only real mentions like @frank should match.
+      `;
+      expect(extractMentions(markdown)).toEqual(['alice', 'frank']);
+    });
+
+    it('suppresses mentions inside HTML <pre> and <code> blocks', () => {
+      const html = 'Hello @alice! Check <pre>npm i @types/node</pre> and <code>@bob</code>. Thanks @charlie!';
+      expect(extractMentions(html)).toEqual(['alice', 'charlie']);
+    });
+
+    it('suppresses handles inside URLs and markdown link destinations', () => {
+      const text = 'Visit https://github.com/@org/repo and [profile](https://example.com/@jack) then ping @jack';
+      expect(extractMentions(text)).toEqual(['jack']);
+    });
+
+    it('preserves rich text HTML mention nodes while ignoring attributes', () => {
+      const html = '<p>Assigned to <span data-type="mention" data-label="Jane Doe" data-mention-suggestion-char="@">@Jane Doe</span> and ping @coordinator</p>';
+      expect(extractMentions(html)).toEqual(['Jane Doe', 'coordinator']);
+    });
+  });
+
+  describe('stripMarkdownCode', () => {
+    it('strips code blocks, tilde blocks, inline backticks, pre and code tags', () => {
+      const raw = 'Before ```code @foo``` and `inline @bar` and <pre>pre @baz</pre> and <code>c @qux</code> after @real';
+      expect(stripMarkdownCode(raw)).toBe('Before  and  and  and  after @real');
+    });
   });
 
   describe('parseMentionSegments', () => {

package/src/utils/mentions.ts

@@ -6,29 +6,72 @@ export interface MentionSegment {
 
 /**
  * Regex matching mentions:
- * - Quoted mentions: @"Jane Doe"
- * - Standard mentions: @jane_doe, @planner, @user-1, @john.smith
- * Note: Does not match emails like foo@bar.com (requires word boundary or start of string before @).
+ * - Quoted mentions: @"Jane Doe", "Jane Doe"
+ * - Standard handles: @planner, @user-1, @john.smith
+ * Unquoted handles exclude trailing punctuation (e.g. @turquoise. matches handle "turquoise" without the dot).
  */
-export const MENTION_REGEX = /(?:^|\s)@(?:"([^"]+)"|([a-zA-Z0-9_-]+(?:\.[a-zA-Z0-9_-]+)*))/g;
+export const MENTION_REGEX =
+  /(?:^|[\s>(*_"';\\/[\]{}~`:]|"|>|<|&)@(?:"([^"]+)"|"([^&]+)"|([a-zA-Z0-9_-]+(?:\.[a-zA-Z0-9_-]+)*))/g;
 
 /**
- * Extracts unique mention handles from a text string.
- * Strips quotes and the leading '@' symbol.
+ * Strips code blocks and inline code from markdown or HTML content:
+ * - Fenced code blocks: ```...``` and ~~~...~~~
+ * - Inline backtick code: `...`
+ * - HTML code/pre tags: <pre>...</pre>, <code>...</code>
+ * Used to avoid false-positive mention parsing within code snippets, terminal logs, or stack traces.
+ */
+export function stripMarkdownCode(content: string): string {
+  if (!content || typeof content !== 'string') return '';
+  return content
+    .replace(/```[\s\S]*?```/g, '')
+    .replace(/~~~[\s\S]*?~~~/g, '')
+    .replace(/<pre[\s\S]*?<\/pre>/gi, '')
+    .replace(/<code[\s\S]*?<\/code>/gi, '')
+    .replace(/`[^`\n]*`/g, '');
+}
+
+/**
+ * Extracts unique mention handles from a text string, ignoring trailing punctuation,
+ * code blocks or inline code snippets, URLs, markdown link destinations, and pre-existing HTML mention nodes.
  * Preserves the order of their first appearance.
  */
 export function extractMentions(content: string): string[] {
   if (!content || typeof content !== 'string') return [];
 
+  // Normalize rich text mention nodes (e.g. from TipTap or custom mention spans)
+  const normalizedMentionNodes = content.replace(
+    /<span\b[^>]*\b(?:data-type=["']mention["']|class=["'][^"']*pixerate-mention-node[^"']*["'])[^>]*>([\s\S]*?)<\/span>/gi,
+    (match, inner) => {
+      const labelMatch = match.match(/\bdata-label=["']([^"']+)["']/i);
+      if (labelMatch) {
+        const val = labelMatch[1].trim();
+        return val.includes(' ') ? ` @"${val}" ` : ` @${val} `;
+      }
+      const idMatch = match.match(/\bdata-id=["']([^"']+)["']/i);
+      if (idMatch) {
+        const val = idMatch[1].trim();
+        return val.includes(' ') ? ` @"${val}" ` : ` @${val} `;
+      }
+      return ` ${inner} `;
+    }
+  );
+
+  const cleanContent = stripMarkdownCode(normalizedMentionNodes);
+  // Strip URLs and markdown link destinations so @package or @handles in URLs are not extracted as mentions
+  const withoutUrls = cleanContent
+    .replace(/(?:https?|ftp|file):\/\/[^\s<>()]+/gi, '')
+    .replace(/\]\([^)]*\)/g, ']');
+  // Strip remaining HTML tags
+  const textOnly = withoutUrls.replace(/<[^>]+>/g, ' ');
+
   const mentions: string[] = [];
   const seen = new Set<string>();
 
-  // Reset regex lastIndex
   const regex = new RegExp(MENTION_REGEX.source, 'g');
   let match: RegExpExecArray | null;
 
-  while ((match = regex.exec(content)) !== null) {
-    const handle = match[1] ?? match[2];
+  while ((match = regex.exec(textOnly)) !== null) {
+    const handle = (match[1] ?? match[2] ?? match[3] ?? '').trim();
     if (handle && !seen.has(handle)) {
       seen.add(handle);
       mentions.push(handle);
@@ -52,12 +95,11 @@ export function parseMentionSegments(content: string): MentionSegment[] {
 
   while ((match = regex.exec(content)) !== null) {
     const fullMatch = match[0];
-    const leadingWhitespace = fullMatch.startsWith(' ') || fullMatch.startsWith('\t') || fullMatch.startsWith('\n')
-      ? fullMatch[0]
-      : '';
-    const mentionToken = fullMatch.slice(leadingWhitespace.length);
-    const handle = match[1] ?? match[2];
-    const matchStart = match.index + leadingWhitespace.length;
+    const atIndex = fullMatch.indexOf('@');
+    const prefix = atIndex > 0 ? fullMatch.slice(0, atIndex) : '';
+    const mentionToken = fullMatch.slice(atIndex);
+    const handle = match[1] ?? match[2] ?? match[3];
+    const matchStart = match.index + prefix.length;
 
     // Push text before this mention if any
     if (matchStart > lastIndex) {
@@ -74,7 +116,7 @@ export function parseMentionSegments(content: string): MentionSegment[] {
       handle
     });
 
-    lastIndex = match.index + fullMatch.length;
+    lastIndex = matchStart + mentionToken.length;
   }
 
   // Push any remaining text after the last match