@critical-path/core 0.20.1 → 0.21.0

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

package/src/utils/status.ts

@@ -3,6 +3,7 @@ import type {
   StatusDefinition,
   SemanticStatus,
   TaskDerivedStatus,
+  Workflow
 } from '../types/index.js';
 
 export const DEFAULT_STATUS_DEFINITIONS: Record<string, StatusDefinition> = {
@@ -170,3 +171,249 @@ export function deriveTaskLifecycleState(
     isCancelled
   };
 }
+
+export type TaskLike = {
+  status?: string | null;
+  semanticStatus?: SemanticStatus | string | null;
+  trashed?: boolean | null;
+  trashedAt?: string | null;
+  archived?: boolean | null;
+  archivedAt?: string | null;
+  isDraft?: boolean | null;
+  assigneeId?: string | null;
+  assignees?: Array<{ id?: string; name?: string } | string> | null;
+  customFields?: Record<string, unknown> | null;
+  [key: string]: unknown;
+};
+
+/**
+ * Extracts a list of StatusDefinitions from either a Workflow or an array of definitions.
+ */
+export function extractStatusDefinitions(
+  workflowOrStatuses?: Workflow | StatusDefinition[] | unknown
+): StatusDefinition[] | undefined {
+  if (!workflowOrStatuses) return undefined;
+  if (Array.isArray(workflowOrStatuses)) {
+    return workflowOrStatuses as StatusDefinition[];
+  }
+  if (typeof workflowOrStatuses === 'object' && workflowOrStatuses !== null) {
+    const statuses = (workflowOrStatuses as any).statuses;
+    if (Array.isArray(statuses)) {
+      return statuses as StatusDefinition[];
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Checks whether a task is flagged as a draft outside the active workflow.
+ */
+export function isDraftTask(task: TaskLike | null | undefined): boolean {
+  if (!task) return false;
+  return Boolean(task.isDraft);
+}
+
+/**
+ * Checks whether a task is archived.
+ */
+export function isArchivedTask(task: TaskLike | null | undefined): boolean {
+  if (!task) return false;
+  return (
+    Boolean(task.archived) ||
+    Boolean(task.archivedAt) ||
+    task.status === 'archived' ||
+    Boolean((task.customFields as any)?.isArchived)
+  );
+}
+
+/**
+ * Checks whether a task is soft-deleted / trashed.
+ */
+export function isTrashedTask(task: TaskLike | null | undefined): boolean {
+  if (!task) return false;
+  return (
+    Boolean(task.trashed) ||
+    Boolean(task.trashedAt) ||
+    task.status === 'trashed' ||
+    Boolean((task.customFields as any)?.isTrashed)
+  );
+}
+
+/**
+ * Checks whether a task is trashed, archived, or soft-deleted.
+ */
+export function isTrashedOrArchivedTask(task: TaskLike | null | undefined): boolean {
+  if (!task) return false;
+  return isTrashedTask(task) || isArchivedTask(task);
+}
+
+/**
+ * Determines whether a task is part of the legitimate project workflow.
+ * A workflow task is not trashed, not archived, and not a draft.
+ */
+export function isWorkflowTask(task: TaskLike | null | undefined): boolean {
+  if (!task) return false;
+  return !isTrashedTask(task) && !isArchivedTask(task) && !isDraftTask(task);
+}
+
+export const isTaskDraft = isDraftTask;
+export const isTaskArchived = isArchivedTask;
+export const isTaskTrashed = isTrashedTask;
+export const isTaskTrashedOrArchived = isTrashedOrArchivedTask;
+export const isTaskWorkflow = isWorkflowTask;
+
+/**
+ * Resolves the canonical SemanticStatus for a task based on the project's workflow or default heuristics.
+ */
+export function getTaskSemanticStatus(
+  task: TaskLike | null | undefined,
+  workflowOrStatuses?: Workflow | StatusDefinition[] | unknown
+): SemanticStatus {
+  if (!task) return 'not_started';
+
+  const customDefs = extractStatusDefinitions(workflowOrStatuses);
+
+  // 1. Look up the task's status in custom workflow definitions
+  if (task.status) {
+    if (customDefs) {
+      const match = customDefs.find((s) => s.key === task.status);
+      if (match?.category) return match.category;
+      if (match) {
+        if ((match as any).completionState === 'done') {
+          return (match as any).isCancelled ? 'canceled' : 'completed';
+        }
+        if ((match as any).executionState === 'active') {
+          return 'in_progress';
+        }
+        if ((match as any).completionState === 'not_done') {
+          return 'not_started';
+        }
+      }
+    }
+
+    // 2. Default status definition lookup from @critical-path/core for standard statuses
+    const normalizedKey = task.status.toLowerCase().replace(/[-\s]+/g, '_');
+    const defaultDef =
+      DEFAULT_STATUS_DEFINITIONS[task.status] || DEFAULT_STATUS_DEFINITIONS[normalizedKey];
+    if (defaultDef?.category) {
+      return defaultDef.category;
+    }
+  }
+
+  // 3. If task has an explicit valid semanticStatus (for custom/unknown status), use it
+  if (task.semanticStatus) {
+    const raw = String(task.semanticStatus).toLowerCase();
+    if (
+      raw === 'completed' ||
+      raw === 'in_progress' ||
+      raw === 'not_started' ||
+      raw === 'canceled' ||
+      raw === 'cancelled'
+    ) {
+      return raw === 'cancelled' ? 'canceled' : (raw as SemanticStatus);
+    }
+  }
+
+  // 4. Fallback to resolveStatusDefinition for general fallback or 'not_started'
+  if (task.status) {
+    const def = resolveStatusDefinition(task.status, customDefs);
+    if (def?.category) {
+      return def.category;
+    }
+  }
+
+  return 'not_started';
+}
+
+/**
+ * Determines whether a task has reached completion in its lifecycle.
+ */
+export function isTaskCompleted(
+  task: TaskLike | null | undefined,
+  workflowOrStatuses?: Workflow | StatusDefinition[] | unknown
+): boolean {
+  if (!task) return false;
+  return getTaskSemanticStatus(task, workflowOrStatuses) === 'completed';
+}
+
+export const isTaskDone = isTaskCompleted;
+
+/**
+ * Determines whether a task is actively in progress.
+ */
+export function isTaskInProgress(
+  task: TaskLike | null | undefined,
+  workflowOrStatuses?: Workflow | StatusDefinition[] | unknown
+): boolean {
+  if (!task) return false;
+  return getTaskSemanticStatus(task, workflowOrStatuses) === 'in_progress';
+}
+
+/**
+ * Determines whether a task is pending or not yet started.
+ */
+export function isTaskNotStarted(
+  task: TaskLike | null | undefined,
+  workflowOrStatuses?: Workflow | StatusDefinition[] | unknown
+): boolean {
+  if (!task) return false;
+  return getTaskSemanticStatus(task, workflowOrStatuses) === 'not_started';
+}
+
+/**
+ * Determines whether a task has been canceled or abandoned.
+ */
+export function isTaskCanceled(
+  task: TaskLike | null | undefined,
+  workflowOrStatuses?: Workflow | StatusDefinition[] | unknown
+): boolean {
+  if (!task) return false;
+  return getTaskSemanticStatus(task, workflowOrStatuses) === 'canceled';
+}
+
+/**
+ * Determines whether a task is active in an ongoing project workflow.
+ * An active task:
+ * 1. Is not trashed or archived.
+ * 2. Is not a draft (exists within the active workflow).
+ * 3. Has not reached terminal completion ('completed') or terminal abandonment ('canceled').
+ */
+export function isTaskActive(
+  task: TaskLike | null | undefined,
+  workflowOrStatuses?: Workflow | StatusDefinition[] | unknown
+): boolean {
+  if (!task) return false;
+  if (isTrashedOrArchivedTask(task)) return false;
+  if (isDraftTask(task)) return false;
+  const sem = getTaskSemanticStatus(task, workflowOrStatuses);
+  return sem !== 'completed' && sem !== 'canceled';
+}
+
+/**
+ * Checks whether a task currently has no assigned owner.
+ */
+export function isTaskUnassigned(task: TaskLike | null | undefined): boolean {
+  if (!task) return true;
+
+  const rawId = task.assigneeId ? String(task.assigneeId).trim() : '';
+  const hasAssigneeId = rawId !== '' && rawId.toLowerCase() !== 'unassigned';
+
+  const hasValidAssignees =
+    Array.isArray(task.assignees) &&
+    task.assignees.some((a: any) => {
+      if (!a) return false;
+      if (typeof a === 'string') {
+        const s = a.trim();
+        return s !== '' && s.toLowerCase() !== 'unassigned';
+      }
+      const id = a.id ? String(a.id).trim() : '';
+      const name = a.name ? String(a.name).trim() : '';
+      return (
+        (id !== '' && id.toLowerCase() !== 'unassigned') ||
+        (name !== '' && name.toLowerCase() !== 'unassigned')
+      );
+    });
+
+  return !hasAssigneeId && !hasValidAssignees;
+}
+

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/deliverables.test.ts","./src/index.test.ts","./src/index.ts","./src/status.test.ts","./src/task-state.test.ts","./src/use-case-validation.test.ts","./src/domain/calendar.test.ts","./src/domain/calendar.ts","./src/domain/cpm.test.ts","./src/domain/cpm.ts","./src/domain/custom-fields.ts","./src/domain/ddd.test.ts","./src/domain/entities.ts","./src/domain/events.ts","./src/domain/graph.ts","./src/domain/index.ts","./src/domain/ladder.test.ts","./src/domain/ladder.ts","./src/domain/metrics.test.ts","./src/domain/metrics.ts","./src/domain/task-duration.test.ts","./src/domain/workload.test.ts","./src/domain/workload.ts","./src/engine/index.ts","./src/plugins/index.ts","./src/storage/file-storage.ts","./src/storage/firebase-storage.ts","./src/storage/index.ts","./src/storage/s3.ts","./src/storage/storage.test.ts","./src/store/firebase.test.ts","./src/store/firebase.ts","./src/store/index.ts","./src/store/sqlite.test.ts","./src/store/sqlite.ts","./src/types/index.ts","./src/utils/index.ts","./src/utils/key.test.ts","./src/utils/key.ts","./src/utils/mentions.test.ts","./src/utils/mentions.ts","./src/utils/status.ts","./src/utils/workflow.ts"],"version":"5.9.3"}
+{"root":["./src/deliverables.test.ts","./src/index.test.ts","./src/index.ts","./src/status.test.ts","./src/task-state.test.ts","./src/use-case-validation.test.ts","./src/domain/calendar.test.ts","./src/domain/calendar.ts","./src/domain/cpm.test.ts","./src/domain/cpm.ts","./src/domain/custom-fields.ts","./src/domain/ddd.test.ts","./src/domain/entities.ts","./src/domain/events.ts","./src/domain/graph.ts","./src/domain/index.ts","./src/domain/ladder.test.ts","./src/domain/ladder.ts","./src/domain/metrics.test.ts","./src/domain/metrics.ts","./src/domain/task-duration.test.ts","./src/domain/workload.test.ts","./src/domain/workload.ts","./src/engine/index.ts","./src/plugins/index.ts","./src/storage/file-storage.ts","./src/storage/firebase-storage.ts","./src/storage/index.ts","./src/storage/s3.ts","./src/storage/storage.test.ts","./src/store/firebase.test.ts","./src/store/firebase.ts","./src/store/index.ts","./src/store/sqlite.test.ts","./src/store/sqlite.ts","./src/types/index.ts","./src/utils/fractional-index.test.ts","./src/utils/fractional-index.ts","./src/utils/index.ts","./src/utils/key.test.ts","./src/utils/key.ts","./src/utils/mentions.test.ts","./src/utils/mentions.ts","./src/utils/status.ts","./src/utils/workflow.ts"],"version":"5.9.3"}