@enrichlayer/el-linear 1.7.0 → 1.10.0

package/dist/commands/issues/link-references.js

@@ -0,0 +1,171 @@
+/**
+ * `el-linear issues link-references` handler.
+ *
+ * Two modes:
+ *   - Single-issue (`<issueId>`): scan one issue's description (and
+ *     optionally its comments) for issue refs, create sidebar
+ *     relations for any that aren't already linked, optionally
+ *     rewrite the description to wrap the bare refs as markdown
+ *     links.
+ *   - Batch (`--team <key>`): walk the team's recent issues and run
+ *     the same auto-link pass on each. Description rewrite is
+ *     intentionally disabled in batch mode — bulk rewrites
+ *     bot-author every issue's revision history, which makes
+ *     "who edited this?" attribution noisy.
+ *
+ * Extracted from `commands/issues.ts` (ALL-938) so that file can
+ * focus on commander wiring + the create / update / read / search
+ * handlers.
+ */
+import { resolveTeam } from "../../config/resolver.js";
+import { LIST_COMMENTS_QUERY } from "../../queries/comments.js";
+import { GET_ISSUE_RELATIONS_QUERY, SCAN_ISSUES_QUERY, } from "../../queries/issues.js";
+import { autoLinkReferences, } from "../../utils/auto-link-references.js";
+import { createGraphQLService, } from "../../utils/graphql-service.js";
+import { createLinearService, } from "../../utils/linear-service.js";
+import { outputSuccess } from "../../utils/output.js";
+import { getRootOpts } from "../../utils/root-opts.js";
+import { parsePositiveInt } from "../../utils/validators.js";
+import { prepareDescriptionRewrite, pushDescriptionUpdate, } from "./description.js";
+async function fetchCommentBodies(issueUuid, graphQLService) {
+    const result = await graphQLService.rawRequest(LIST_COMMENTS_QUERY, {
+        issueId: issueUuid,
+        first: 250,
+    });
+    const nodes = result.issue?.comments.nodes ?? [];
+    return nodes.map((c) => c.body).filter((b) => b.length > 0);
+}
+async function linkReferencesForIssue(args) {
+    const comments = args.includeComments
+        ? await fetchCommentBodies(args.issueUuid, args.graphQLService)
+        : undefined;
+    return autoLinkReferences({
+        issueId: args.issueUuid,
+        identifier: args.identifier,
+        description: args.description,
+        comments,
+        dryRun: args.dryRun,
+        graphQLService: args.graphQLService,
+        linearService: args.linearService,
+        preResolved: args.preResolved,
+    });
+}
+async function handleLinkReferencesSingle(issueId, options, graphQLService, linearService) {
+    const resolvedId = await linearService.resolveIssueId(issueId);
+    // GET_ISSUE_RELATIONS_QUERY also returns description, so this single call gives us everything
+    // we need for the description-only path. Comments are fetched separately on demand.
+    const issueResult = await graphQLService.rawRequest(GET_ISSUE_RELATIONS_QUERY, { id: resolvedId });
+    if (!issueResult.issue) {
+        throw new Error(`Issue "${issueId}" not found`);
+    }
+    const issue = issueResult.issue;
+    const identifier = issue.identifier;
+    const description = issue.description ?? "";
+    const dryRun = Boolean(options.dryRun);
+    const includeComments = Boolean(options.includeComments);
+    const rewriteDescription = Boolean(options.rewriteDescription);
+    // If rewriting, validate refs once up front so we can both wrap the description and
+    // pass the resolved map down to autoLink — avoids a second resolve round trip.
+    const rewrite = rewriteDescription
+        ? await prepareDescriptionRewrite(description, identifier, linearService, graphQLService)
+        : { preResolved: undefined, wrapped: undefined };
+    const autoLinked = await linkReferencesForIssue({
+        issueUuid: resolvedId,
+        identifier,
+        description,
+        includeComments,
+        dryRun,
+        graphQLService,
+        linearService,
+        preResolved: rewrite.preResolved,
+    });
+    let descriptionRewritten = false;
+    if (rewriteDescription && rewrite.wrapped && !dryRun) {
+        await pushDescriptionUpdate(resolvedId, rewrite.wrapped, graphQLService);
+        descriptionRewritten = true;
+    }
+    outputSuccess({
+        id: resolvedId,
+        identifier,
+        title: issue.title,
+        autoLinked,
+        ...(rewriteDescription
+            ? {
+                descriptionRewritten,
+                ...(dryRun && rewrite.wrapped
+                    ? { descriptionPreview: rewrite.wrapped }
+                    : {}),
+            }
+            : {}),
+        meta: {
+            dryRun,
+            includeComments,
+            ...(rewriteDescription ? { rewriteDescription: true } : {}),
+        },
+    });
+}
+async function handleLinkReferencesBatch(teamInput, options, graphQLService, linearService) {
+    const teamId = resolveTeam(teamInput);
+    const limit = options.limit
+        ? parsePositiveInt(options.limit, "--limit")
+        : 100;
+    const dryRun = Boolean(options.dryRun);
+    const includeComments = Boolean(options.includeComments);
+    const scan = await graphQLService.rawRequest(SCAN_ISSUES_QUERY, {
+        filter: { team: { id: { eq: teamId } } },
+        first: limit,
+    });
+    const nodes = scan.issues.nodes;
+    const entries = [];
+    for (const node of nodes) {
+        const issueUuid = node.id;
+        const identifier = node.identifier;
+        const description = node.description ?? "";
+        const autoLinked = await linkReferencesForIssue({
+            issueUuid,
+            identifier,
+            description,
+            includeComments,
+            dryRun,
+            graphQLService,
+            linearService,
+        });
+        entries.push({ identifier, autoLinked });
+    }
+    // Summary counts across the batch
+    const totalLinked = entries.reduce((n, e) => n + e.autoLinked.linked.length, 0);
+    const totalSkipped = entries.reduce((n, e) => n + e.autoLinked.skipped.length, 0);
+    const totalFailed = entries.reduce((n, e) => n + e.autoLinked.failed.length, 0);
+    outputSuccess({
+        data: entries,
+        meta: {
+            count: entries.length,
+            team: teamInput,
+            dryRun,
+            includeComments,
+            totals: {
+                linked: totalLinked,
+                skipped: totalSkipped,
+                failed: totalFailed,
+            },
+        },
+    });
+}
+export async function handleLinkReferencesIssue(issueIdOrTeamFlag, options, command) {
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
+    const linearService = await createLinearService(rootOpts);
+    if (options.team) {
+        if (issueIdOrTeamFlag) {
+            throw new Error("Provide either an issueId positional argument OR --team, not both. With --team, omit the issueId.");
+        }
+        if (options.rewriteDescription) {
+            throw new Error("--rewrite-description is single-issue only. Use it case by case (one issueId per invocation) — bulk description rewrites bot-author the whole team's history.");
+        }
+        return handleLinkReferencesBatch(options.team, options, graphQLService, linearService);
+    }
+    if (!issueIdOrTeamFlag) {
+        throw new Error("issueId is required (or use --team <key> to scan a whole team)");
+    }
+    return handleLinkReferencesSingle(issueIdOrTeamFlag, options, graphQLService, linearService);
+}

package/dist/commands/issues/relations.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Issue-relation helpers — `transformIssueRelation` for the create
+ * path, plus the `RelatedIssueEntry` builders used by the
+ * `issues related` query path.
+ *
+ * Extracted from `commands/issues.ts` (ALL-938) so that file can
+ * focus on commander wiring + handlers.
+ */
+import type { IssueRelationCreateResponse, RelationIncomingNode, RelationOutgoingNode, RelationPeerNode } from "../../queries/issues-types.js";
+import type { LinearIssueRelation } from "../../types/linear.js";
+import type { GraphQLService } from "../../utils/graphql-service.js";
+import type { LinearService } from "../../utils/linear-service.js";
+type CreatedIssueRelation = NonNullable<IssueRelationCreateResponse["issueRelationCreate"]["issueRelation"]>;
+export declare function transformIssueRelation(rel: CreatedIssueRelation): LinearIssueRelation;
+/**
+ * Walk the `--related-to` / `--blocks` / `--blocked-by` /
+ * `--duplicate-of` flags and create the corresponding
+ * IssueRelation rows. Used by `issues create`.
+ */
+export declare function createRelations(sourceId: string, options: Record<string, unknown>, graphQLService: GraphQLService, linearService: LinearService): Promise<LinearIssueRelation[]>;
+export interface RelatedIssueEntry {
+    direction: "outgoing" | "incoming";
+    id: string;
+    issue: {
+        id: string;
+        identifier: string;
+        title: string;
+        state?: {
+            id: string;
+            name: string;
+        };
+        priority?: number;
+        assignee?: {
+            id: string;
+            name: string;
+        };
+        team?: {
+            id: string;
+            key: string;
+            name: string;
+        };
+    };
+    type: string;
+}
+/**
+ * Invert relation type for incoming (inverse) relations so the output
+ * reads naturally from the perspective of the queried issue. E.g. if
+ * DEV-100 "blocks" DEV-200, and we query DEV-200, the inverse relation
+ * type is "blocks" but direction is incoming → "blockedBy".
+ */
+export declare function normalizeInverseType(type: string): string;
+export declare function buildRelatedIssueSummary(peer: RelationPeerNode): RelatedIssueEntry["issue"];
+export declare function buildOutgoingRelationEntries(nodes: RelationOutgoingNode[] | undefined): RelatedIssueEntry[];
+export declare function buildIncomingRelationEntries(nodes: RelationIncomingNode[] | undefined): RelatedIssueEntry[];
+export {};

package/dist/commands/issues/relations.js

@@ -0,0 +1,132 @@
+/**
+ * Issue-relation helpers — `transformIssueRelation` for the create
+ * path, plus the `RelatedIssueEntry` builders used by the
+ * `issues related` query path.
+ *
+ * Extracted from `commands/issues.ts` (ALL-938) so that file can
+ * focus on commander wiring + handlers.
+ */
+import { ISSUE_RELATION_CREATE_MUTATION } from "../../queries/issues.js";
+import { splitList } from "../../utils/validators.js";
+export function transformIssueRelation(rel) {
+    return {
+        id: rel.id,
+        type: rel.type,
+        issue: {
+            id: rel.issue.id,
+            identifier: rel.issue.identifier,
+            title: rel.issue.title,
+        },
+        relatedIssue: {
+            id: rel.relatedIssue.id,
+            identifier: rel.relatedIssue.identifier,
+            title: rel.relatedIssue.title,
+        },
+    };
+}
+/**
+ * Walk the `--related-to` / `--blocks` / `--blocked-by` /
+ * `--duplicate-of` flags and create the corresponding
+ * IssueRelation rows. Used by `issues create`.
+ */
+export async function createRelations(sourceId, options, graphQLService, linearService) {
+    const relations = [];
+    const relationSpecs = [
+        { option: "relatedTo", type: "related" },
+        { option: "blocks", type: "blocks" },
+        { option: "blockedBy", type: "blocks", reverse: true },
+        { option: "duplicateOf", type: "duplicate" },
+    ];
+    for (const spec of relationSpecs) {
+        const value = options[spec.option];
+        if (!value) {
+            continue;
+        }
+        for (const id of splitList(value)) {
+            const targetId = await linearService.resolveIssueId(id);
+            const result = await graphQLService.rawRequest(ISSUE_RELATION_CREATE_MUTATION, {
+                input: {
+                    issueId: spec.reverse ? targetId : sourceId,
+                    relatedIssueId: spec.reverse ? sourceId : targetId,
+                    type: spec.type,
+                },
+            });
+            const issueRelation = result.issueRelationCreate.issueRelation;
+            if (!issueRelation) {
+                throw new Error(`Failed to create ${spec.type} relation from ${sourceId} to ${id}`);
+            }
+            relations.push(transformIssueRelation(issueRelation));
+        }
+    }
+    return relations;
+}
+/**
+ * Invert relation type for incoming (inverse) relations so the output
+ * reads naturally from the perspective of the queried issue. E.g. if
+ * DEV-100 "blocks" DEV-200, and we query DEV-200, the inverse relation
+ * type is "blocks" but direction is incoming → "blockedBy".
+ */
+export function normalizeInverseType(type) {
+    if (type === "blocks") {
+        return "blockedBy";
+    }
+    return type;
+}
+export function buildRelatedIssueSummary(peer) {
+    return {
+        id: peer.id,
+        identifier: peer.identifier,
+        title: peer.title,
+        ...(peer.state
+            ? { state: { id: peer.state.id, name: peer.state.name } }
+            : {}),
+        ...(peer.priority == null ? {} : { priority: peer.priority }),
+        ...(peer.assignee
+            ? {
+                assignee: {
+                    id: peer.assignee.id,
+                    name: peer.assignee.name,
+                },
+            }
+            : {}),
+        ...(peer.team
+            ? {
+                team: {
+                    id: peer.team.id,
+                    key: peer.team.key,
+                    name: peer.team.name,
+                },
+            }
+            : {}),
+    };
+}
+export function buildOutgoingRelationEntries(nodes) {
+    const entries = [];
+    for (const rel of nodes ?? []) {
+        if (!rel.relatedIssue) {
+            continue;
+        }
+        entries.push({
+            id: rel.id,
+            type: rel.type,
+            direction: "outgoing",
+            issue: buildRelatedIssueSummary(rel.relatedIssue),
+        });
+    }
+    return entries;
+}
+export function buildIncomingRelationEntries(nodes) {
+    const entries = [];
+    for (const rel of nodes ?? []) {
+        if (!rel.issue) {
+            continue;
+        }
+        entries.push({
+            id: rel.id,
+            type: normalizeInverseType(rel.type),
+            direction: "incoming",
+            issue: buildRelatedIssueSummary(rel.issue),
+        });
+    }
+    return entries;
+}