@enrichlayer/el-linear 1.29.1 → 1.30.0

package/claude-skills/linear-operations/SKILL.md

@@ -352,6 +352,27 @@ el-linear comments create ENG-123 --body "cc @alice — Bob can you review?" 2>&
 
 Works in comments only (not descriptions).
 
+### Confirming a mention fired (the `mentions` output field)
+
+A real mention lives in the comment's structured `bodyData`, not in the markdown — so a comment whose body reads `@alice` may or may not have actually pinged anyone. **Don't guess: read the `mentions` field** that `comments create|update` attach to their output (the sibling of `autoLinked`):
+
+```jsonc
+{
+  "id": "…",
+  "mentions": {
+    "resolved":   [{ "label": "alice", "userId": "…" }],  // real notifications sent
+    "unresolved": ["bobby"],                                // explicit @names that matched nobody
+    "delivered":  true                                      // false ⇒ Linear rejected bodyData, fell back to plain text
+  }
+}
+```
+
+- An **unresolved** explicit `@name` (typo or unknown handle) is left as plain text — **no notification** — and el-linear prints a loud `⚠ @name did not resolve …` warning to **stderr**. Fix the name and re-comment; never assume the ping landed.
+- `delivered: false` means the structured body was rejected and the comment shipped as plain markdown, so the resolved mentions did **not** fire — also warned on stderr.
+- Under `--quiet`, the stdout stays the one-line `comment <id>`; the `mentions: resolved=[…] unresolved=[…]` confirmation is echoed to **stderr**.
+
+This makes "a real @mention" a verifiable, deterministic convention rather than a hope ([DEV-4987](https://linear.app/verticalint/issue/DEV-4987/)).
+
 ---
 
 ## CLI Syntax Rules

package/dist/commands/comments.js

@@ -7,8 +7,9 @@ import { createGraphQLService, } from "../utils/graphql-service.js";
 import { extractIssueReferences } from "../utils/issue-reference-extractor.js";
 import { wrapIssueReferencesAsLinks } from "../utils/issue-reference-wrapper.js";
 import { createLinearService, } from "../utils/linear-service.js";
-import { resolveMentions } from "../utils/mention-resolver.js";
-import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+import { logger } from "../utils/logger.js";
+import { resolveMentions, } from "../utils/mention-resolver.js";
+import { getQuietMode, handleAsyncCommand, outputSuccess, } from "../utils/output.js";
 import { getRootOpts } from "../utils/root-opts.js";
 import { validateReferences } from "../utils/validate-references.js";
 import { parsePositiveInt } from "../utils/validators.js";
@@ -17,6 +18,54 @@ import { getWorkspaceUrlKey } from "../utils/workspace-url.js";
 // tweak on their side doesn't silently regress the fallback path.
 const BODY_DATA_ERROR_RE = /prosemirror|bodydata|invalid.*body/i;
 const ISSUE_IDENTIFIER_REGEX = /^[A-Z][A-Z0-9]*-\d+$/;
+/**
+ * Turn a {@link MentionReport} into the `mentions` output field, or `undefined`
+ * when there is nothing to report. `delivered=false` records a bodyData→plain
+ * fallback so the JSON output never falsely claims a ping was sent.
+ */
+function buildMentionsOutput(report, delivered) {
+    if (!report) {
+        return undefined;
+    }
+    if (report.resolved.length === 0 && report.unresolvedExplicit.length === 0) {
+        return undefined;
+    }
+    return {
+        resolved: report.resolved.map((m) => ({
+            label: m.label,
+            userId: m.userId,
+        })),
+        unresolved: report.unresolvedExplicit,
+        delivered,
+    };
+}
+/**
+ * Emit the human-facing side of mention resolution to **stderr** (so it never
+ * pollutes the machine-stable stdout line, and survives `--quiet`):
+ *   - a loud warning for each explicit `@name` that resolved to nobody,
+ *   - a warning when a bodyData rejection dropped resolved mentions,
+ *   - under `--quiet`, a one-line confirmation of what resolved (since the
+ *     quiet stdout line can't carry the `mentions` field).
+ */
+function reportMentions(mentions) {
+    if (!mentions) {
+        return;
+    }
+    for (const name of mentions.unresolved) {
+        logger.error(`⚠ @${name} did not resolve to a team member — left as plain text (no notification sent)`);
+    }
+    if (!mentions.delivered && mentions.resolved.length > 0) {
+        logger.error(`⚠ Linear rejected the structured comment body; fell back to plain text — ${mentions.resolved.length} mention(s) were NOT delivered as notifications`);
+    }
+    // In quiet mode stdout is a single `comment <id>` line with no room for the
+    // `mentions` field, so echo a concise confirmation to stderr.
+    if (getQuietMode()) {
+        const resolved = mentions.delivered
+            ? mentions.resolved.map((m) => `${m.label}→${m.userId}`).join(", ")
+            : "(none delivered)";
+        logger.error(`mentions: resolved=[${resolved}] unresolved=[${mentions.unresolved.join(", ")}]`);
+    }
+}
 function readBody(options) {
     // --body and --body-file are two sources for the same field; accepting both
     // would silently drop one. Reject up front (DEV-4450) — the same mutual-
@@ -130,12 +179,15 @@ async function handleCreateComment(issueId, options, command) {
         selfUserId,
     });
     const input = { issueId: resolvedIssueId };
-    if (mentionResult) {
+    if (mentionResult?.bodyData) {
         input.bodyData = mentionResult.bodyData;
     }
     else {
         input.body = body;
     }
+    // Tracks whether resolved mentions actually shipped as structured nodes;
+    // flipped to false if the bodyData fallback below sends plain text instead.
+    let mentionsDelivered = true;
     let result;
     try {
         result = await graphQLService.rawRequest(CREATE_COMMENT_MUTATION, { input });
@@ -146,6 +198,7 @@ async function handleCreateComment(issueId, options, command) {
         // Linear handle the conversion server-side.
         const msg = err instanceof Error ? err.message : String(err);
         if (input.bodyData && BODY_DATA_ERROR_RE.test(msg)) {
+            mentionsDelivered = false;
             const fallbackInput = {
                 issueId: resolvedIssueId,
                 body,
@@ -179,7 +232,13 @@ async function handleCreateComment(issueId, options, command) {
         linearService,
     });
     const output = transformComment(mutation.comment);
-    outputSuccess(autoLinked ? { ...output, autoLinked } : output);
+    const mentions = buildMentionsOutput(mentionResult, mentionsDelivered);
+    reportMentions(mentions);
+    outputSuccess({
+        ...output,
+        ...(autoLinked ? { autoLinked } : {}),
+        ...(mentions ? { mentions } : {}),
+    });
 }
 async function handleUpdateComment(commentId, options, command) {
     const rootOpts = getRootOpts(command);
@@ -196,12 +255,13 @@ async function handleUpdateComment(commentId, options, command) {
         selfUserId,
     });
     const input = {};
-    if (mentionResult) {
+    if (mentionResult?.bodyData) {
         input.bodyData = mentionResult.bodyData;
     }
     else {
         input.body = body;
     }
+    let mentionsDelivered = true;
     let result;
     try {
         result = await graphQLService.rawRequest(UPDATE_COMMENT_MUTATION, { id: commentId, input });
@@ -217,6 +277,7 @@ async function handleUpdateComment(commentId, options, command) {
         // extraction; copy-then-refactor on the third per the repo convention.
         const msg = err instanceof Error ? err.message : String(err);
         if (input.bodyData && BODY_DATA_ERROR_RE.test(msg)) {
+            mentionsDelivered = false;
             const fallbackInput = { body };
             result = await graphQLService.rawRequest(UPDATE_COMMENT_MUTATION, { id: commentId, input: fallbackInput });
         }
@@ -243,7 +304,13 @@ async function handleUpdateComment(commentId, options, command) {
         });
     }
     const output = transformComment(comment);
-    outputSuccess(autoLinked ? { ...output, autoLinked } : output);
+    const mentions = buildMentionsOutput(mentionResult, mentionsDelivered);
+    reportMentions(mentions);
+    outputSuccess({
+        ...output,
+        ...(autoLinked ? { autoLinked } : {}),
+        ...(mentions ? { mentions } : {}),
+    });
 }
 async function handleListComments(issueId, options, command) {
     const rootOpts = getRootOpts(command);

package/dist/utils/mention-resolver.d.ts

@@ -12,6 +12,27 @@ export interface ResolveMentionsOptions {
      */
     selfUserId?: string;
 }
+interface ResolvedMention {
+    label: string;
+    userId: string;
+}
+export interface MentionReport {
+    /**
+     * ProseMirror doc carrying `suggestion_userMentions` nodes — the structured
+     * body that makes Linear fire real notifications. `null` when nothing
+     * resolved (the caller should send the plain markdown `body` instead).
+     */
+    bodyData: ProseMirrorNode | null;
+    /** Mentions that resolved to a real user (explicit `@name` + bare names). */
+    resolved: ResolvedMention[];
+    /**
+     * Explicit `@name` tokens that did NOT resolve to any team member — almost
+     * always a typo or an unknown handle. Left as plain text (no notification),
+     * so the caller surfaces them as a warning. Bare-name non-matches are not
+     * tracked here: they were never an intended ping.
+     */
+    unresolvedExplicit: string[];
+}
 /**
  * Resolve mentions in markdown body text to Linear user IDs.
  *
@@ -23,9 +44,9 @@ export interface ResolveMentionsOptions {
  * are also converted to mentions — without requiring the `@` prefix. This
  * catches cases like "Bob owns the design" → "@bob owns the design".
  *
- * Returns a ProseMirror `bodyData` doc with `suggestion_userMentions` nodes,
- * or `null` if nothing was resolved.
+ * Returns a {@link MentionReport} describing which names resolved, which
+ * explicit `@names` did not, and the `bodyData` doc to send — or `null` when
+ * there was nothing to resolve and nothing to warn about.
  */
-export declare function resolveMentions(body: string, linearService: LinearService, options?: ResolveMentionsOptions): Promise<{
-    bodyData: ProseMirrorNode;
-} | null>;
+export declare function resolveMentions(body: string, linearService: LinearService, options?: ResolveMentionsOptions): Promise<MentionReport | null>;
+export {};

package/dist/utils/mention-resolver.js

@@ -21,20 +21,27 @@ const MARKDOWN_LINK_REGEX = /\[([^\]]+)\]\(([^)]+)\)/g;
  * are also converted to mentions — without requiring the `@` prefix. This
  * catches cases like "Bob owns the design" → "@bob owns the design".
  *
- * Returns a ProseMirror `bodyData` doc with `suggestion_userMentions` nodes,
- * or `null` if nothing was resolved.
+ * Returns a {@link MentionReport} describing which names resolved, which
+ * explicit `@names` did not, and the `bodyData` doc to send — or `null` when
+ * there was nothing to resolve and nothing to warn about.
  */
 export async function resolveMentions(body, linearService, options = {}) {
     const autoMention = options.autoMention !== false;
     const selfUserId = options.selfUserId;
     // 1. Resolve explicit @name mentions (existing behavior).
     const explicit = new Map();
+    const unresolvedExplicit = [];
     const explicitNames = [...body.matchAll(EXPLICIT_MENTION_REGEX)].map((m) => m[1]);
     for (const name of new Set(explicitNames)) {
         const userId = await resolveUserByName(name, linearService);
         if (userId) {
             explicit.set(name, { userId, label: name });
         }
+        else {
+            // An explicit `@name` the author clearly meant as a ping, but it
+            // matched no team member — surface it so the ping never dies silently.
+            unresolvedExplicit.push(name);
+        }
     }
     // 2. Bare-name mentions: scan for candidate names that actually appear as
     //    standalone words in the body (outside code / link contexts).
@@ -61,12 +68,33 @@ export async function resolveMentions(body, linearService, options = {}) {
             bare.set(candidate, { userId, label: candidate });
         }
     }
-    if (explicit.size === 0 && bare.size === 0) {
+    // Nothing resolved and no failed explicit ping → caller has nothing to do.
+    if (explicit.size === 0 &&
+        bare.size === 0 &&
+        unresolvedExplicit.length === 0) {
         return null;
     }
-    const doc = markdownToProseMirror(body);
-    const bodyData = injectMentions(doc, explicit, bare);
-    return { bodyData };
+    // De-dup by userId for the reported set: a capitalized explicit `@Bob` also
+    // matches the bare candidate "Bob" (the `@` isn't a word char, so the bare
+    // lookbehind passes), landing the same user in both maps. The injected
+    // bodyData is unaffected (the `@name` alternation consumes the span first,
+    // so only one mention node is emitted), but `resolved` would over-count and
+    // `--quiet` would print the user twice — which undercuts the whole point of
+    // a trustworthy mention report. Explicit-first so the label is the typed
+    // `@name`, not the capitalized bare candidate.
+    const resolvedByUser = new Map();
+    for (const m of [...explicit.values(), ...bare.values()]) {
+        if (!resolvedByUser.has(m.userId)) {
+            resolvedByUser.set(m.userId, m);
+        }
+    }
+    const resolved = [...resolvedByUser.values()];
+    // Only build the structured doc when something actually resolved; a body
+    // whose only mention was an unresolved `@typo` is sent as plain markdown.
+    const bodyData = explicit.size > 0 || bare.size > 0
+        ? injectMentions(markdownToProseMirror(body), explicit, bare)
+        : null;
+    return { bodyData, resolved, unresolvedExplicit };
 }
 async function resolveUserByName(name, linearService) {
     const configResult = resolveMember(name);

package/dist/utils/output.d.ts

@@ -6,6 +6,12 @@ export declare function setRawMode(enabled: boolean): void;
  * the summary block. Set in main.ts's preAction when the flag is present.
  */
 export declare function setQuietMode(enabled: boolean): void;
+/**
+ * Whether `--quiet` is active. Lets a command decide to route extra
+ * human-facing detail (e.g. a mention-resolution confirmation) to stderr,
+ * keeping the single machine-stable stdout line intact.
+ */
+export declare function getQuietMode(): boolean;
 export declare function setJqFilter(filter: string | null): void;
 export declare function setFieldsFilter(fields: string[] | null): void;
 export declare function setOutputFormat(format: OutputFormat): void;

package/dist/utils/output.js

@@ -19,6 +19,14 @@ export function setRawMode(enabled) {
 export function setQuietMode(enabled) {
     quietMode = enabled;
 }
+/**
+ * Whether `--quiet` is active. Lets a command decide to route extra
+ * human-facing detail (e.g. a mention-resolution confirmation) to stderr,
+ * keeping the single machine-stable stdout line intact.
+ */
+export function getQuietMode() {
+    return quietMode;
+}
 export function setJqFilter(filter) {
     jqFilter = filter;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.29.1",
+  "version": "1.30.0",
   "description": "A pragmatic CLI for Linear.app — deterministic team/label/member resolution, structured issue validation, configurable term enforcement, and a GraphQL escape hatch.",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",