@enrichlayer/el-linear 1.2.0

package/dist/utils/graphql-service.d.ts

@@ -0,0 +1,8 @@
+import type { GraphQLResponseData, GraphQLVariables } from "../types/linear.js";
+import { type AuthOptions } from "./auth.js";
+export declare class GraphQLService {
+    private readonly graphQLClient;
+    constructor(apiToken: string);
+    rawRequest<T = GraphQLResponseData>(query: string, variables?: GraphQLVariables): Promise<T>;
+}
+export declare function createGraphQLService(options: AuthOptions): GraphQLService;

package/dist/utils/graphql-service.js

@@ -0,0 +1,35 @@
+import { LinearClient } from "@linear/sdk";
+import { getApiToken } from "./auth.js";
+export class GraphQLService {
+    graphQLClient;
+    constructor(apiToken) {
+        const client = new LinearClient({
+            apiKey: apiToken,
+            headers: {
+                "public-file-urls-expire-in": "3600",
+            },
+        });
+        // LinearClient stores a private graphql-request client — access via escape hatch
+        this.graphQLClient = client.client;
+    }
+    // Default type allows property access on raw GraphQL responses.
+    // Callers can narrow with explicit type parameter: rawRequest<{ issues: { nodes: T[] } }>(...)
+    async rawRequest(query, variables) {
+        try {
+            const response = await this.graphQLClient.rawRequest(query, variables);
+            return response.data;
+        }
+        catch (error) {
+            const err = error;
+            if (err.response?.errors) {
+                const graphQLError = err.response.errors[0];
+                throw new Error(graphQLError.message || "GraphQL query failed");
+            }
+            throw new Error(`GraphQL request failed: ${err.message}`);
+        }
+    }
+}
+export function createGraphQLService(options) {
+    const apiToken = getApiToken(options);
+    return new GraphQLService(apiToken);
+}

package/dist/utils/identifier-parser.d.ts

@@ -0,0 +1,7 @@
+interface ParsedIdentifier {
+    issueNumber: number;
+    teamKey: string;
+}
+export declare function parseIssueIdentifier(identifier: string): ParsedIdentifier;
+export declare function tryParseIssueIdentifier(identifier: string): ParsedIdentifier | null;
+export {};

package/dist/utils/identifier-parser.js

@@ -0,0 +1,20 @@
+export function parseIssueIdentifier(identifier) {
+    const parts = identifier.split("-");
+    if (parts.length !== 2) {
+        throw new Error(`Invalid issue identifier format: "${identifier}". Expected format: TEAM-123`);
+    }
+    const teamKey = parts[0];
+    const issueNumber = Number.parseInt(parts[1], 10);
+    if (Number.isNaN(issueNumber)) {
+        throw new Error(`Invalid issue number in identifier: "${identifier}"`);
+    }
+    return { teamKey, issueNumber };
+}
+export function tryParseIssueIdentifier(identifier) {
+    try {
+        return parseIssueIdentifier(identifier);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/utils/issue-reference-extractor.d.ts

@@ -0,0 +1,18 @@
+export type IssueRelationType = "related" | "blocks" | "duplicate";
+export interface IssueReference {
+    identifier: string;
+    /** When true, swap source/target on the create mutation (e.g. "blocked by X" means X→source). */
+    reverse: boolean;
+    type: IssueRelationType;
+}
+/**
+ * Extract issue identifiers from text along with the inferred relation type.
+ * Strips fenced code blocks before scanning to avoid false positives in pasted logs.
+ *
+ * The relation type is inferred from prose keywords immediately before the identifier
+ * (e.g. "blocked by DEV-100" → blocks/reverse=true). Default is `related`.
+ *
+ * Each identifier appears at most once in the result. If the same identifier appears
+ * with different qualifiers, the strongest non-default inference wins.
+ */
+export declare function extractIssueReferences(text: string, selfIdentifier?: string): IssueReference[];

package/dist/utils/issue-reference-extractor.js

@@ -0,0 +1,95 @@
+const IDENTIFIER_REGEX = /\b([A-Z][A-Z0-9]*-\d+)\b/g;
+const FENCED_CODE_BLOCK_REGEX = /(?:^|\n)([ \t]*)(?:```|~~~)[^\n]*\n[\s\S]*?\n\1?(?:```|~~~)(?=\n|$)/g;
+/**
+ * Window of text immediately before an identifier where we look for relation keywords.
+ * 30 chars covers phrases like "is a prerequisite of" comfortably.
+ */
+const KEYWORD_WINDOW = 30;
+/**
+ * Phrase patterns matched against the text immediately preceding an identifier.
+ * Each pattern is anchored at the *end* of the window (so the phrase must directly precede
+ * the identifier, modulo whitespace). Order matters — most-specific phrases first.
+ *
+ * `reverse: true` flips the source/target on the relation create:
+ *   - "blocked by DEV-100" → DEV-100 blocks the source issue
+ *   - "duplicated by EMW-258" → EMW-258 duplicates the source issue
+ */
+const PHRASE_PATTERNS = [
+    {
+        regex: /\bduplicated by\s*$/i,
+        type: "duplicate",
+        reverse: true,
+    },
+    {
+        regex: /\b(?:duplicate of|dup(?:e)? of|duplicates)\s*$/i,
+        type: "duplicate",
+        reverse: false,
+    },
+    {
+        regex: /\b(?:blocked by|blocked on|depends on|waiting on|requires)\s*$/i,
+        type: "blocks",
+        reverse: true,
+    },
+    {
+        regex: /\b(?:blocks|unblocks|prerequisite (?:for|of)|required by)\s*$/i,
+        type: "blocks",
+        reverse: false,
+    },
+];
+function stripFencedCodeBlocks(text) {
+    return text.replace(FENCED_CODE_BLOCK_REGEX, "");
+}
+function inferRelation(textBefore) {
+    const window = textBefore.slice(-KEYWORD_WINDOW);
+    for (const { regex, type, reverse } of PHRASE_PATTERNS) {
+        if (regex.test(window)) {
+            return { type, reverse };
+        }
+    }
+    return { type: "related", reverse: false };
+}
+/**
+ * Specificity ranking — used when the same identifier appears more than once in the text
+ * with different qualifiers. The strongest non-default inference wins.
+ */
+function specificity(ref) {
+    if (ref.type === "duplicate") {
+        return 3;
+    }
+    if (ref.type === "blocks") {
+        return 2;
+    }
+    return 1; // related
+}
+/**
+ * Extract issue identifiers from text along with the inferred relation type.
+ * Strips fenced code blocks before scanning to avoid false positives in pasted logs.
+ *
+ * The relation type is inferred from prose keywords immediately before the identifier
+ * (e.g. "blocked by DEV-100" → blocks/reverse=true). Default is `related`.
+ *
+ * Each identifier appears at most once in the result. If the same identifier appears
+ * with different qualifiers, the strongest non-default inference wins.
+ */
+export function extractIssueReferences(text, selfIdentifier) {
+    if (!text) {
+        return [];
+    }
+    const stripped = stripFencedCodeBlocks(text);
+    const byIdentifier = new Map();
+    for (const match of stripped.matchAll(IDENTIFIER_REGEX)) {
+        const id = match[1];
+        if (selfIdentifier && id === selfIdentifier) {
+            continue;
+        }
+        const matchIndex = match.index ?? 0;
+        const textBefore = stripped.slice(0, matchIndex);
+        const { type, reverse } = inferRelation(textBefore);
+        const candidate = { identifier: id, type, reverse };
+        const existing = byIdentifier.get(id);
+        if (!existing || specificity(candidate) > specificity(existing)) {
+            byIdentifier.set(id, candidate);
+        }
+    }
+    return [...byIdentifier.values()];
+}

package/dist/utils/issue-reference-wrapper.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Rewrite `text`, wrapping each occurrence of a known-valid Linear issue identifier
+ * as a markdown link. Skips any occurrence inside protected ranges (code blocks,
+ * inline code, existing markdown links, angle-bracket autolinks).
+ *
+ * Only IDs in `validIdentifiers` are wrapped — IDs that don't resolve in the
+ * workspace are left as plain text (handles false positives like ISO codes).
+ *
+ * If `text` already contains `[ID](url)` for a given ID, that occurrence is left
+ * alone (it's inside a protected range), so this function is idempotent.
+ */
+export declare function wrapIssueReferencesAsLinks(text: string, validIdentifiers: Set<string>, workspaceUrlKey: string): string;

package/dist/utils/issue-reference-wrapper.js

@@ -0,0 +1,91 @@
+// Workspace URL key resolution lives in `./workspace-url.ts` — call
+// `getWorkspaceUrlKey(graphQLService)` to obtain it before invoking
+// `wrapIssueReferencesAsLinks`. Linear URLs look like
+// `https://linear.app/<urlKey>/issue/<identifier>/`.
+const IDENTIFIER_REGEX = /\b([A-Z][A-Z0-9]*-\d+)\b/g;
+const FENCED_CODE_BLOCK_REGEX = /(?:^|\n)([ \t]*)(?:```|~~~)[^\n]*\n[\s\S]*?\n\1?(?:```|~~~)(?=\n|$)/g;
+// Inline backtick spans — `EMW-258`. Markdown allows multiple backticks for spans containing
+// backticks; we keep it simple and match single-backtick spans.
+const INLINE_CODE_REGEX = /`[^`\n]+?`/g;
+// Existing markdown links: [text](url). We protect both the text and the url.
+const MARKDOWN_LINK_REGEX = /\[([^\]]*)\]\(([^)]*)\)/g;
+// Angle-bracket autolinks: <https://...>
+const ANGLE_AUTOLINK_REGEX = /<[^>\s]+>/g;
+// Bare URLs in prose. We protect these so identifiers inside paths
+// (e.g. "https://github.com/foo/DEV-100") don't get split by wrapping.
+const BARE_URL_REGEX = /https?:\/\/\S+/g;
+/**
+ * Find ranges of `text` that should NOT have identifiers wrapped:
+ * - Fenced code blocks (``` or ~~~)
+ * - Inline backtick code spans
+ * - Existing markdown links — both `[text]` and `(url)`
+ * - Angle-bracket autolinks
+ *
+ * The returned ranges may overlap; callers only need to test "is this position
+ * inside any protected range" so overlap is fine.
+ */
+function findProtectedRanges(text) {
+    const ranges = [];
+    for (const re of [
+        FENCED_CODE_BLOCK_REGEX,
+        INLINE_CODE_REGEX,
+        MARKDOWN_LINK_REGEX,
+        ANGLE_AUTOLINK_REGEX,
+        BARE_URL_REGEX,
+    ]) {
+        for (const m of text.matchAll(re)) {
+            const start = m.index ?? 0;
+            ranges.push({ start, end: start + m[0].length });
+        }
+    }
+    return ranges;
+}
+function isProtected(pos, ranges) {
+    for (const r of ranges) {
+        if (pos >= r.start && pos < r.end) {
+            return true;
+        }
+    }
+    return false;
+}
+function buildIssueUrl(identifier, workspaceUrlKey) {
+    return `https://linear.app/${workspaceUrlKey}/issue/${identifier}/`;
+}
+/**
+ * Rewrite `text`, wrapping each occurrence of a known-valid Linear issue identifier
+ * as a markdown link. Skips any occurrence inside protected ranges (code blocks,
+ * inline code, existing markdown links, angle-bracket autolinks).
+ *
+ * Only IDs in `validIdentifiers` are wrapped — IDs that don't resolve in the
+ * workspace are left as plain text (handles false positives like ISO codes).
+ *
+ * If `text` already contains `[ID](url)` for a given ID, that occurrence is left
+ * alone (it's inside a protected range), so this function is idempotent.
+ */
+export function wrapIssueReferencesAsLinks(text, validIdentifiers, workspaceUrlKey) {
+    if (!text || validIdentifiers.size === 0) {
+        return text;
+    }
+    const ranges = findProtectedRanges(text);
+    // Walk through matches and build the result string in pieces.
+    // We can't use String.replace with a callback because we need positional protection checks.
+    let result = "";
+    let cursor = 0;
+    for (const m of text.matchAll(IDENTIFIER_REGEX)) {
+        const id = m[1];
+        const start = m.index ?? 0;
+        const end = start + m[0].length;
+        if (!validIdentifiers.has(id)) {
+            continue;
+        }
+        if (isProtected(start, ranges)) {
+            continue;
+        }
+        // Append everything up to this match unchanged
+        result += text.slice(cursor, start);
+        result += `[${id}](${buildIssueUrl(id, workspaceUrlKey)})`;
+        cursor = end;
+    }
+    result += text.slice(cursor);
+    return result;
+}

package/dist/utils/linear-service.d.ts

@@ -0,0 +1,26 @@
+import type { LinearComment, LinearCycleDetail, LinearCycleSummary, LinearLabel, LinearProject, LinearTeam, LinearUser } from "../types/linear.js";
+import { type AuthOptions } from "./auth.js";
+export declare class LinearService {
+    private readonly client;
+    constructor(apiToken: string);
+    resolveIssueId(issueId: string): Promise<string>;
+    getTeams(limit?: number): Promise<LinearTeam[]>;
+    resolveUserId(nameOrEmailOrId: string): Promise<string>;
+    getUsers(activeOnly?: boolean, limit?: number): Promise<LinearUser[]>;
+    getProjects(limit?: number): Promise<LinearProject[]>;
+    resolveTeamId(teamKeyOrNameOrId: string): Promise<string>;
+    resolveStatusId(statusName: string, teamId?: string): Promise<string>;
+    private buildLabelData;
+    getLabels(teamFilter?: string, limit?: number): Promise<{
+        labels: LinearLabel[];
+    }>;
+    createComment(args: {
+        issueId: string;
+        body: string;
+    }): Promise<LinearComment>;
+    getCycles(teamFilter?: string, activeOnly?: boolean, limit?: number): Promise<LinearCycleSummary[]>;
+    getCycleById(cycleId: string, issuesLimit?: number): Promise<LinearCycleDetail>;
+    resolveCycleId(cycleNameOrId: string, teamFilter?: string): Promise<string>;
+    resolveProjectId(projectNameOrId: string): Promise<string>;
+}
+export declare function createLinearService(options: AuthOptions): LinearService;