feat: add Linear (linear.app) data source plugin

backend/plugins/linear/README.md

@@ -0,0 +1,115 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Linear
+
+## Summary
+
+This plugin collects data from [Linear](https://linear.app) through its
+[GraphQL API](https://linear.app/developers/graphql) and maps it into DevLake's
+standardized `ticket` domain, so Linear issues appear in DevLake dashboards
+(throughput, lead/cycle time, sprint burndown, etc.).
+
+The selectable **scope** is a Linear **Team**, which maps to a domain `Board`.
+
+## Supported data
+
+| Linear entity   | Tool-layer table                  | Domain-layer table                         |
+|-----------------|-----------------------------------|--------------------------------------------|
+| Team            | `_tool_linear_teams` (scope)      | `boards`                                   |
+| User            | `_tool_linear_accounts`           | `accounts`                                 |
+| Workflow state  | `_tool_linear_workflow_states`    | (drives issue status mapping)              |
+| Issue           | `_tool_linear_issues`             | `issues`, `board_issues`                   |
+| Label           | `_tool_linear_issue_labels`       | `issue_labels`                             |
+| Comment         | `_tool_linear_comments`           | `issue_comments`                           |
+| Cycle           | `_tool_linear_cycles`             | `sprints`, `board_sprints`, `sprint_issues`|
+| Issue history   | `_tool_linear_issue_history`      | `issue_changelogs`                         |
+
+### Field mapping highlights
+
+- **Status** — derived deterministically from Linear's `WorkflowState.type`
+  (no manual mapping needed, unlike Jira):
+  - `backlog`, `unstarted` → `TODO`
+  - `started` → `IN_PROGRESS`
+  - `completed`, `canceled` → `DONE`
+- **Priority** — Linear's integer priority maps to a label: `0` No priority,
+  `1` Urgent, `2` High, `3` Medium, `4` Low.
+- **Type** — Linear has no native issue type, so issues default to `REQUIREMENT`.
+- **Lead time** — `completedAt − createdAt` (Linear provides `startedAt`/`completedAt`
+  natively; the history changelog captures every status transition).
+- **Story points** — Linear's `estimate`.
+
+## Authentication
+
+The plugin uses a Linear **personal API key**, passed verbatim in the
+`Authorization` header (no `Bearer` prefix). Create one under
+**Settings → Security & access → Personal API keys** in Linear.
+
+## Configuration
+
+Create a connection:
+
+```
+curl 'http://localhost:8080/api/plugins/linear/connections' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "name": "linear",
+    "endpoint": "https://api.linear.app/graphql",
+    "token": "<YOUR_LINEAR_API_KEY>",
+    "rateLimitPerHour": 1500
+}'
+```
+
+Add a team scope (the team id is the Linear team UUID):
+
+```
+curl 'http://localhost:8080/api/plugins/linear/connections/<CONNECTION_ID>/scopes' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "data": [{ "connectionId": <CONNECTION_ID>, "teamId": "<TEAM_ID>", "name": "Engineering" }]
+}'
+```
+
+## Collecting data
+
+```
+curl 'http://localhost:8080/api/pipelines' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "name": "linear pipeline",
+    "plan": [[{
+        "plugin": "linear",
+        "options": { "connectionId": <CONNECTION_ID>, "teamId": "<TEAM_ID>" }
+    }]]
+}'
+```
+
+## Rate limiting
+
+Linear enforces a per-API-key request budget (1,500 requests/hour) plus a
+complexity budget. The collector paces requests against the configured
+`rateLimitPerHour` (default 1500). Issues are collected incrementally using
+`updatedAt` ordering so re-runs only fetch changes.
+
+## Limitations / roadmap
+
+- Authentication is personal API key only; OAuth2 is a planned follow-up.
+- Issue type defaults to `REQUIREMENT`; label-based type mapping via the scope
+  config is a planned follow-up.
+- config-ui integration (connection form + team picker) and the website
+  documentation page are planned follow-ups; for now connections and scopes are
+  managed via the API calls shown above.

backend/plugins/linear/api/blueprint_v200.go

@@ -0,0 +1,98 @@
+/*
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package api
+
+import (
+	"github.com/apache/incubator-devlake/core/errors"
+	coreModels "github.com/apache/incubator-devlake/core/models"
+	"github.com/apache/incubator-devlake/core/models/domainlayer/didgen"
+	"github.com/apache/incubator-devlake/core/models/domainlayer/ticket"
+	"github.com/apache/incubator-devlake/core/plugin"
+	"github.com/apache/incubator-devlake/core/utils"
+	helper "github.com/apache/incubator-devlake/helpers/pluginhelper/api"
+	"github.com/apache/incubator-devlake/helpers/srvhelper"
+	"github.com/apache/incubator-devlake/plugins/linear/models"
+	"github.com/apache/incubator-devlake/plugins/linear/tasks"
+)
+
+func MakePipelinePlanV200(
+	subtaskMetas []plugin.SubTaskMeta,
+	connectionId uint64,
+	bpScopes []*coreModels.BlueprintScope,
+) (coreModels.PipelinePlan, []plugin.Scope, errors.Error) {
+	connection, err := dsHelper.ConnSrv.FindByPk(connectionId)
+	if err != nil {
+		return nil, nil, err
+	}
+	scopeDetails, err := dsHelper.ScopeSrv.MapScopeDetails(connectionId, bpScopes)
+	if err != nil {
+		return nil, nil, err
+	}
+	plan, err := makePipelinePlanV200(subtaskMetas, scopeDetails, connection)
+	if err != nil {
+		return nil, nil, err
+	}
+	scopes, err := makeScopesV200(scopeDetails, connection)
+	return plan, scopes, err
+}
+
+func makePipelinePlanV200(
+	subtaskMetas []plugin.SubTaskMeta,
+	scopeDetails []*srvhelper.ScopeDetail[models.LinearTeam, models.LinearScopeConfig],
+	connection *models.LinearConnection,
+) (coreModels.PipelinePlan, errors.Error) {
+	plan := make(coreModels.PipelinePlan, len(scopeDetails))
+	for i, scopeDetail := range scopeDetails {
+		stage := plan[i]
+		if stage == nil {
+			stage = coreModels.PipelineStage{}
+		}
+		scope, scopeConfig := scopeDetail.Scope, scopeDetail.ScopeConfig
+		task, err := helper.MakePipelinePlanTask(
+			"linear",
+			subtaskMetas,
+			scopeConfig.Entities,
+			tasks.LinearOptions{
+				ConnectionId: connection.ID,
+				TeamId:       scope.TeamId,
+			},
+		)
+		if err != nil {
+			return nil, err
+		}
+		stage = append(stage, task)
+		plan[i] = stage
+	}
+	return plan, nil
+}
+
+func makeScopesV200(
+	scopeDetails []*srvhelper.ScopeDetail[models.LinearTeam, models.LinearScopeConfig],
+	connection *models.LinearConnection,
+) ([]plugin.Scope, errors.Error) {
+	scopes := make([]plugin.Scope, 0, len(scopeDetails))
+	idgen := didgen.NewDomainIdGenerator(&models.LinearTeam{})
+	for _, scopeDetail := range scopeDetails {
+		scope, scopeConfig := scopeDetail.Scope, scopeDetail.ScopeConfig
+		id := idgen.Generate(connection.ID, scope.TeamId)
+		if utils.StringsContains(scopeConfig.Entities, plugin.DOMAIN_TYPE_TICKET) {
+			scopes = append(scopes, ticket.NewBoard(id, scope.Name))
+		}
+	}
+	return scopes, nil
+}

backend/plugins/linear/api/blueprint_v200_test.go

@@ -0,0 +1,90 @@
+/*
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package api
+
+import (
+	"testing"
+
+	"github.com/apache/incubator-devlake/core/models/common"
+	"github.com/apache/incubator-devlake/core/plugin"
+	helper "github.com/apache/incubator-devlake/helpers/pluginhelper/api"
+	"github.com/apache/incubator-devlake/helpers/srvhelper"
+	mockplugin "github.com/apache/incubator-devlake/mocks/core/plugin"
+	"github.com/apache/incubator-devlake/plugins/linear/models"
+	"github.com/stretchr/testify/assert"
+)
+
+func mockLinearPlugin(t *testing.T) {
+	mockMeta := mockplugin.NewPluginMeta(t)
+	mockMeta.On("RootPkgPath").Return("github.com/apache/incubator-devlake/plugins/linear")
+	mockMeta.On("Name").Return("linear").Maybe()
+	_ = plugin.RegisterPlugin("linear", mockMeta)
+}
+
+func TestMakeScopesV200(t *testing.T) {
+	mockLinearPlugin(t)
+
+	const connectionId uint64 = 1
+	const teamId = "team-1"
+	const expectDomainScopeId = "linear:LinearTeam:1:team-1"
+
+	scopes, err := makeScopesV200(
+		[]*srvhelper.ScopeDetail[models.LinearTeam, models.LinearScopeConfig]{
+			{
+				Scope: models.LinearTeam{
+					Scope:  common.Scope{ConnectionId: connectionId},
+					TeamId: teamId,
+					Name:   "Engineering",
+				},
+				ScopeConfig: &models.LinearScopeConfig{
+					ScopeConfig: common.ScopeConfig{Entities: []string{plugin.DOMAIN_TYPE_TICKET}},
+				},
+			},
+		},
+		&models.LinearConnection{
+			BaseConnection: helper.BaseConnection{Model: common.Model{ID: connectionId}},
+		},
+	)
+	assert.Nil(t, err)
+	assert.Equal(t, 1, len(scopes))
+	assert.Equal(t, expectDomainScopeId, scopes[0].ScopeId())
+}
+
+func TestMakeScopesV200WithoutTicketEntity(t *testing.T) {
+	mockLinearPlugin(t)
+
+	scopes, err := makeScopesV200(
+		[]*srvhelper.ScopeDetail[models.LinearTeam, models.LinearScopeConfig]{
+			{
+				Scope: models.LinearTeam{
+					Scope:  common.Scope{ConnectionId: 1},
+					TeamId: "team-1",
+				},
+				ScopeConfig: &models.LinearScopeConfig{
+					ScopeConfig: common.ScopeConfig{Entities: []string{}},
+				},
+			},
+		},
+		&models.LinearConnection{
+			BaseConnection: helper.BaseConnection{Model: common.Model{ID: 1}},
+		},
+	)
+	assert.Nil(t, err)
+	// no ticket entity selected => no domain board scope produced
+	assert.Equal(t, 0, len(scopes))
+}