semantic-release-linear-app 0.1.0-next.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Caio Pizzol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+# semantic-release-linear-app
+
+> A [semantic-release](https://github.com/semantic-release/semantic-release) plugin to automatically update Linear issues with version labels when they're included in releases.
+
+## Features
+
+- 🏷️ Automatically adds version labels to Linear issues mentioned in commits
+- 🎨 Color-coded labels based on release type (major/minor/patch)
+- 🧹 Optionally removes old version labels to keep issues clean
+- 💬 Can add release comments to issues (optional)
+- 🔍 Configurable team key filtering
+- ⚡ Batch operations for efficiency
+- 📝 Full TypeScript support with type definitions
+
+## Install
+
+```bash
+npm install --save-dev semantic-release-linear-app
+```
+
+## Usage
+
+Add the plugin to your semantic-release configuration:
+
+```json
+{
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    ["semantic-release-linear-app", {
+      "apiKey": "lin_api_xxx"
+    }],
+    "@semantic-release/github"
+  ]
+}
+```
+
+### TypeScript Configuration
+
+If you're using TypeScript for your configuration, the plugin exports types:
+
+```typescript
+import type { PluginConfig } from 'semantic-release-linear-app';
+
+const config: PluginConfig = {
+  apiKey: process.env.LINEAR_API_KEY,
+  teamKeys: ['ENG', 'FEAT'],
+  labelPrefix: 'v',
+  removeOldLabels: true,
+  addComment: false
+};
+```
+
+## Configuration
+
+### Authentication
+
+Set your Linear API key via environment variable:
+
+```bash
+export LINEAR_API_KEY=lin_api_xxx
+```
+
+Or pass it in the plugin configuration:
+
+```json
+{
+  "apiKey": "lin_api_xxx"
+}
+```
+
+### Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `apiKey` | - | Linear API key (or use `LINEAR_API_KEY` env var) |
+| `teamKeys` | `[]` | Array of team keys to filter issues (e.g., `["ENG", "FEAT"]`) |
+| `labelPrefix` | `"v"` | Prefix for version labels |
+| `removeOldLabels` | `true` | Remove previous version labels from issues |
+| `addComment` | `false` | Add a comment to issues with release info |
+| `dryRun` | `false` | Preview changes without updating Linear |
+
+### Example Configuration
+
+```javascript
+// .releaserc.js
+module.exports = {
+  branches: ['main', 'next'],
+  plugins: [
+    '@semantic-release/commit-analyzer',
+    '@semantic-release/release-notes-generator',
+    ['semantic-release-linear-app', {
+      teamKeys: ['ENG', 'FEAT', 'BUG'],
+      labelPrefix: 'version:',
+      removeOldLabels: true,
+      addComment: true
+    }],
+    '@semantic-release/npm',
+    '@semantic-release/github'
+  ]
+};
+```
+
+## How It Works
+
+1. **Issue Detection**: The plugin scans commit messages for Linear issue IDs (e.g., `ENG-123`)
+2. **Label Creation**: Creates a version label if it doesn't exist (color-coded by release type)
+3. **Issue Updates**: Applies the label to all detected issues
+4. **Cleanup**: Optionally removes old version labels to avoid clutter
+
+### Commit Message Examples
+
+The plugin will detect Linear issues in various formats:
+
+```bash
+# In commit message
+git commit -m "feat: add new feature ENG-123"
+
+# In commit body
+git commit -m "feat: add new feature" -m "Closes ENG-123"
+
+# Multiple issues
+git commit -m "fix: resolve bugs ENG-123, FEAT-456"
+
+# In PR title (when squash merging)
+"feat: add feature (#123) ENG-456"
+```
+
+### Label Colors
+
+Labels are automatically color-coded based on the release type:
+
+- 🔴 **Major** releases (breaking changes) - Red
+- 🟠 **Minor** releases (new features) - Orange  
+- 🟢 **Patch** releases (bug fixes) - Green
+- 🟣 **Prerelease** versions - Purple
+
+## Advanced Usage
+
+### Channel-Specific Configuration
+
+For different behavior on different release channels:
+
+```javascript
+// Coming in v2.0
+{
+  channelConfig: {
+    next: {
+      labelPrefix: 'next:',
+      addComment: false
+    },
+    latest: {
+      labelPrefix: 'stable:',
+      addComment: true
+    }
+  }
+}
+```
+
+### Dry Run
+
+Test what issues would be updated without making changes:
+
+```javascript
+{
+  dryRun: true
+}
+```
+
+## Linear API Setup
+
+1. Go to Linear Settings → API → Personal API keys
+2. Create a new key with "write" access
+3. Add to your CI environment as `LINEAR_API_KEY`
+
+## CI Configuration
+
+### GitHub Actions
+
+```yaml
+- name: Release
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+    LINEAR_API_KEY: ${{ secrets.LINEAR_API_KEY }}
+  run: npx semantic-release
+```
+
+## Troubleshooting
+
+### Issues not being detected
+
+- Ensure issue IDs follow the format `TEAM-NUMBER` (e.g., `ENG-123`)
+- Check that team keys match if using the `teamKeys` filter
+- Verify the issues exist in Linear
+
+### API errors
+
+- Confirm your API key has write access
+- Check that the Linear workspace is accessible
+- Ensure network connectivity from CI environment
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * semantic-release-linear-app
+ * A semantic-release plugin to update Linear issues with version labels
+ */
+import { verifyConditions } from "./lib/verify";
+import { success } from "./lib/success";
+export { verifyConditions, success };
+export type { PluginConfig } from "./types";

package/dist/index.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * semantic-release-linear-app
+ * A semantic-release plugin to update Linear issues with version labels
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.success = exports.verifyConditions = void 0;
+const verify_1 = require("./lib/verify");
+Object.defineProperty(exports, "verifyConditions", { enumerable: true, get: function () { return verify_1.verifyConditions; } });
+const success_1 = require("./lib/success");
+Object.defineProperty(exports, "success", { enumerable: true, get: function () { return success_1.success; } });

package/dist/lib/linear-client.d.ts

@@ -0,0 +1,39 @@
+import { LinearIssue, LinearLabel, LinearViewer } from "../types";
+/**
+ * Linear API client for GraphQL operations
+ */
+export declare class LinearClient {
+    private apiKey;
+    private apiUrl;
+    constructor(apiKey: string);
+    /**
+     * Execute a GraphQL query
+     */
+    private query;
+    /**
+     * Test the API connection
+     */
+    testConnection(): Promise<LinearViewer>;
+    /**
+     * Find or create a label
+     */
+    ensureLabel(name: string, color?: string): Promise<LinearLabel>;
+    /**
+     * Get issue by identifier
+     */
+    getIssue(identifier: string): Promise<LinearIssue | null>;
+    /**
+     * Add label to issue
+     */
+    addLabelToIssue(issueId: string, labelId: string): Promise<LinearIssue>;
+    /**
+     * Remove old version labels from issue
+     */
+    removeVersionLabels(issueId: string, labelPrefix: string): Promise<LinearIssue | null>;
+    /**
+     * Add comment to issue
+     */
+    addComment(issueId: string, body: string): Promise<{
+        id: string;
+    }>;
+}

package/dist/lib/linear-client.js

@@ -0,0 +1,191 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LinearClient = void 0;
+const node_fetch_1 = __importDefault(require("node-fetch"));
+/**
+ * Linear API client for GraphQL operations
+ */
+class LinearClient {
+    apiKey;
+    apiUrl = "https://api.linear.app/graphql";
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    /**
+     * Execute a GraphQL query
+     */
+    async query(query, variables = {}) {
+        const response = await (0, node_fetch_1.default)(this.apiUrl, {
+            method: "POST",
+            headers: {
+                Authorization: this.apiKey,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ query, variables }),
+        });
+        const data = (await response.json());
+        if (data.errors) {
+            throw new Error(`Linear API error: ${data.errors[0].message}`);
+        }
+        if (!data.data) {
+            throw new Error("No data returned from Linear API");
+        }
+        return data.data;
+    }
+    /**
+     * Test the API connection
+     */
+    async testConnection() {
+        const query = `
+      query TestConnection {
+        viewer {
+          id
+          name
+        }
+      }
+    `;
+        const data = await this.query(query);
+        return data.viewer;
+    }
+    /**
+     * Find or create a label
+     */
+    async ensureLabel(name, color = "#4752C4") {
+        // First, try to find existing label
+        const searchQuery = `
+      query FindLabel($name: String!) {
+        issueLabels(filter: { name: { eq: $name } }) {
+          nodes {
+            id
+            name
+          }
+        }
+      }
+    `;
+        const searchData = await this.query(searchQuery, { name });
+        if (searchData.issueLabels.nodes.length > 0) {
+            return searchData.issueLabels.nodes[0];
+        }
+        // Create new label if it doesn't exist
+        const createMutation = `
+      mutation CreateLabel($name: String!, $color: String!) {
+        issueLabelCreate(input: { name: $name, color: $color }) {
+          issueLabel {
+            id
+            name
+          }
+        }
+      }
+    `;
+        const createData = await this.query(createMutation, { name, color });
+        return createData.issueLabelCreate.issueLabel;
+    }
+    /**
+     * Get issue by identifier
+     */
+    async getIssue(identifier) {
+        const query = `
+      query GetIssue($identifier: String!) {
+        issue(id: $identifier) {
+          id
+          identifier
+          title
+          labels {
+            nodes {
+              id
+              name
+            }
+          }
+        }
+      }
+    `;
+        try {
+            const data = await this.query(query, {
+                identifier,
+            });
+            return data.issue;
+        }
+        catch {
+            // Issue might not exist, return null
+            return null;
+        }
+    }
+    /**
+     * Add label to issue
+     */
+    async addLabelToIssue(issueId, labelId) {
+        const mutation = `
+      mutation AddLabel($issueId: String!, $labelId: String!) {
+        issueUpdate(
+          id: $issueId,
+          input: { labelIds: [$labelId] }
+        ) {
+          issue {
+            id
+            identifier
+            title
+            labels {
+              nodes {
+                id
+                name
+              }
+            }
+          }
+        }
+      }
+    `;
+        const data = await this.query(mutation, { issueId, labelId });
+        return data.issueUpdate.issue;
+    }
+    /**
+     * Remove old version labels from issue
+     */
+    async removeVersionLabels(issueId, labelPrefix) {
+        const issue = await this.getIssue(issueId);
+        if (!issue)
+            return null;
+        const versionLabels = issue.labels.nodes.filter((label) => label.name.startsWith(labelPrefix));
+        if (versionLabels.length === 0)
+            return issue;
+        const mutation = `
+      mutation RemoveLabels($issueId: String!, $labelIds: [String!]!) {
+        issueRemoveLabel(id: $issueId, labelIds: $labelIds) {
+          issue {
+            id
+            identifier
+            title
+            labels {
+              nodes {
+                id
+                name
+              }
+            }
+          }
+        }
+      }
+    `;
+        const labelIds = versionLabels.map((label) => label.id);
+        const data = await this.query(mutation, { issueId, labelIds });
+        return data.issueRemoveLabel.issue;
+    }
+    /**
+     * Add comment to issue
+     */
+    async addComment(issueId, body) {
+        const mutation = `
+      mutation AddComment($issueId: String!, $body: String!) {
+        commentCreate(input: { issueId: $issueId, body: $body }) {
+          comment {
+            id
+          }
+        }
+      }
+    `;
+        const data = await this.query(mutation, { issueId, body });
+        return data.commentCreate.comment;
+    }
+}
+exports.LinearClient = LinearClient;

package/dist/lib/parse-issues.d.ts

@@ -0,0 +1,15 @@
+import { Commit } from "semantic-release";
+/**
+ * Extract Linear issue IDs from a commit
+ * @param commit - The commit object from semantic-release
+ * @param teamKeys - Optional list of team keys to filter by
+ * @returns Set of unique issue identifiers
+ */
+export declare function parseCommit(commit: Commit, teamKeys?: string[] | null): Set<string>;
+/**
+ * Extract all Linear issue IDs from a list of commits
+ * @param commits - Array of commit objects
+ * @param teamKeys - Optional list of team keys to filter by
+ * @returns Array of unique issue identifiers
+ */
+export declare function parseIssues(commits: readonly Commit[], teamKeys?: string[] | null): string[];

package/dist/lib/parse-issues.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCommit = parseCommit;
+exports.parseIssues = parseIssues;
+/**
+ * Extract Linear issue IDs from a commit
+ * @param commit - The commit object from semantic-release
+ * @param teamKeys - Optional list of team keys to filter by
+ * @returns Set of unique issue identifiers
+ */
+function parseCommit(commit, teamKeys = null) {
+    const issues = new Set();
+    // Build regex pattern based on team keys
+    const teamPattern = teamKeys ? `(?:${teamKeys.join("|")})` : "[A-Z]+";
+    // Pattern matches: ENG-123, FEAT-45, etc.
+    const issuePattern = new RegExp(`\\b(${teamPattern}-\\d+)\\b`, "gi");
+    // Search in commit message
+    if (commit.message) {
+        const messageMatches = Array.from(commit.message.matchAll(issuePattern));
+        for (const match of messageMatches) {
+            issues.add(match[1].toUpperCase());
+        }
+    }
+    // Search in commit body
+    if (commit.body) {
+        const bodyMatches = Array.from(commit.body.matchAll(issuePattern));
+        for (const match of bodyMatches) {
+            issues.add(match[1].toUpperCase());
+        }
+    }
+    return issues;
+}
+/**
+ * Extract all Linear issue IDs from a list of commits
+ * @param commits - Array of commit objects
+ * @param teamKeys - Optional list of team keys to filter by
+ * @returns Array of unique issue identifiers
+ */
+function parseIssues(commits, teamKeys = null) {
+    const allIssues = new Set();
+    commits.forEach((commit) => {
+        const commitIssues = parseCommit(commit, teamKeys);
+        commitIssues.forEach((issue) => allIssues.add(issue));
+    });
+    return Array.from(allIssues);
+}

package/dist/lib/parse-issues.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/parse-issues.test.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const parse_issues_1 = require("./parse-issues");
+describe("parse-issues", () => {
+    test("extracts Linear issue IDs from commits", () => {
+        const commits = [
+            { message: "fix: solve ENG-123 and FEAT-456" },
+            {
+                message: "feat: new feature",
+                body: "Closes BUG-789",
+            },
+            { message: "chore: no issues here" },
+        ];
+        const result = (0, parse_issues_1.parseIssues)(commits);
+        expect(result).toEqual(expect.arrayContaining(["ENG-123", "FEAT-456", "BUG-789"]));
+        expect(result).toHaveLength(3);
+    });
+    test("filters by team keys when provided", () => {
+        const commits = [{ message: "fix: ENG-123 OTHER-456" }];
+        const result = (0, parse_issues_1.parseIssues)(commits, ["ENG"]);
+        expect(result).toEqual(["ENG-123"]);
+    });
+});

package/dist/lib/success.d.ts

@@ -0,0 +1,10 @@
+import { SuccessContext } from "semantic-release";
+import { PluginConfig, LinearContext } from "../types";
+interface ExtendedContext extends SuccessContext {
+    linear?: LinearContext;
+}
+/**
+ * Update Linear issues after a successful release
+ */
+export declare function success(pluginConfig: PluginConfig, context: ExtendedContext): Promise<void>;
+export {};

package/dist/lib/success.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.success = success;
+const linear_client_1 = require("./linear-client");
+const parse_issues_1 = require("./parse-issues");
+/**
+ * Update Linear issues after a successful release
+ */
+async function success(pluginConfig, context) {
+    const { logger, nextRelease, commits, linear } = context;
+    if (!linear) {
+        logger.log("Linear context not found, skipping issue updates");
+        return;
+    }
+    const { removeOldLabels = true, addComment = false, dryRun = false, } = pluginConfig;
+    const client = new linear_client_1.LinearClient(linear.apiKey);
+    const version = nextRelease.version;
+    const channel = nextRelease.channel || "latest";
+    // Format the label based on configuration
+    const labelName = `${linear.labelPrefix}${version}`;
+    const labelColor = getLabelColor(nextRelease.type);
+    logger.log(`Updating Linear issues for release ${version} (${channel})`);
+    // Extract issue IDs from commits
+    const issueIds = (0, parse_issues_1.parseIssues)(commits, linear.teamKeys);
+    if (issueIds.length === 0) {
+        logger.log("No Linear issues found in commits");
+        return;
+    }
+    logger.log(`Found ${issueIds.length} Linear issue(s): ${issueIds.join(", ")}`);
+    if (dryRun) {
+        logger.log("[Dry run] Would update issues:", issueIds);
+        logger.log(`[Dry run] Would apply label: ${labelName}`);
+        return;
+    }
+    // Ensure the version label exists
+    const label = await client.ensureLabel(labelName, labelColor);
+    logger.log(`✓ Ensured label exists: ${labelName}`);
+    // Update each issue
+    const results = await Promise.allSettled(issueIds.map(async (issueId) => {
+        try {
+            // Get the issue first
+            const issue = await client.getIssue(issueId);
+            if (!issue) {
+                logger.warn(`Issue ${issueId} not found, skipping`);
+                return { issueId, status: "not_found" };
+            }
+            // Remove old version labels if configured
+            if (removeOldLabels) {
+                await client.removeVersionLabels(issue.id, linear.labelPrefix);
+            }
+            // Add the new version label
+            await client.addLabelToIssue(issue.id, label.id);
+            // Add comment if configured
+            if (addComment) {
+                const comment = formatComment(version, channel, nextRelease);
+                await client.addComment(issue.id, comment);
+            }
+            logger.log(`✓ Updated issue ${issueId}`);
+            return { issueId, status: "updated" };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error(`Failed to update issue ${issueId}: ${message}`);
+            return { issueId, status: "failed", error: message };
+        }
+    }));
+    // Log summary
+    const updated = results.filter((r) => r.status === "fulfilled" && r.value.status === "updated").length;
+    const failed = results.filter((r) => r.status === "rejected" ||
+        (r.status === "fulfilled" && r.value.status === "failed")).length;
+    const notFound = results.filter((r) => r.status === "fulfilled" && r.value.status === "not_found").length;
+    logger.log(`Linear update complete: ${updated} updated, ${failed} failed, ${notFound} not found`);
+}
+/**
+ * Get label color based on release type
+ */
+function getLabelColor(releaseType) {
+    const colors = {
+        major: "#F44336", // Red for breaking changes
+        premajor: "#E91E63", // Pink for pre-major
+        minor: "#FF9800", // Orange for new features
+        preminor: "#FFC107", // Amber for pre-minor
+        patch: "#4CAF50", // Green for fixes
+        prepatch: "#8BC34A", // Light green for pre-patch
+        prerelease: "#9C27B0", // Purple for prereleases
+    };
+    return colors[releaseType] || "#4752C4"; // Default blue
+}
+/**
+ * Format comment for Linear issue
+ */
+function formatComment(version, channel, release) {
+    const emoji = channel === "latest" ? "🚀" : "🔬";
+    const channelText = channel === "latest" ? "stable" : channel;
+    let comment = `${emoji} **Released in \`v${version}\`** (${channelText})\n\n`;
+    const githubRepo = process.env.GITHUB_REPOSITORY;
+    if (release.gitTag && githubRepo) {
+        comment += `[View release →](https://github.com/${githubRepo}/releases/tag/${release.gitTag})`;
+    }
+    return comment;
+}

package/dist/lib/verify.d.ts

@@ -0,0 +1,8 @@
+import { VerifyConditionsContext } from "semantic-release";
+import { PluginConfig, LinearContext } from "../types";
+/**
+ * Verify the plugin configuration and Linear API access
+ */
+export declare function verifyConditions(pluginConfig: PluginConfig, context: VerifyConditionsContext & {
+    linear?: LinearContext;
+}): Promise<void>;