feat(linear): add Linear fixture data generator (CHAOS-246 part 1/2) (#15)

* feat(linear): add Terraform seeder scaffold for CHAOS-246

* feat(linear): add deterministic Linear seeder for CHAOS-246

* feat(linear): document Linear fixture seeding for CHAOS-246

Author: chrisgeo

linear/README.md

@@ -0,0 +1,78 @@
+# Linear Demo Data Seeder
+
+This module seeds deterministic Linear fixture data for Developer Health analytics. It mirrors the `atlassian/` fixture pattern: Terraform orchestrates a local Python seeder, while the seeder writes teams, projects, cycles, issues, comments, and `out/manifest.json` via the Linear GraphQL API.
+
+## Terraform support
+
+Linear does not maintain an official Terraform provider. A community provider exists, but its resource coverage and maintenance cadence may not match the fixture needs. This module therefore uses Terraform only as an orchestrator (`null_resource` + `local-exec`) and performs Linear writes through `seed/seed_linear.py`.
+
+## Requirements
+
+- Python 3.10+
+- Terraform (optional, for orchestration)
+- Linear personal API key with permission to create teams/projects/issues
+
+## Environment variables
+
+- `LINEAR_API_KEY` — required for real writes. Pass the raw API key in the `Authorization` header value; do not prefix it with `Bearer`.
+
+## Dry run
+
+Dry run is the default Terraform behavior and does not require `LINEAR_API_KEY`:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r linear/seed/requirements.txt
+python linear/seed/seed_linear.py --dry-run
+```
+
+The dry run creates `linear/out/manifest.json` with deterministic counts and samples but performs no API writes.
+
+## Terraform usage
+
+```bash
+cd linear
+terraform init
+terraform apply
+```
+
+To perform real writes:
+
+```hcl
+# terraform.tfvars
+linear_api_key        = "lin_api_..."
+```
+
+Optional toggles:
+
+- `enable_issue_creation` (default `false`): when false, runs `--dry-run`
+- `enable_cycles` (default `true`): create two-week cycles for each seeded team
+- `enable_comments` (default `true`): create deterministic comments on a subset of issues
+- `monthly_issue_count` (default `0`): override issue volume per team per month
+- `assignee_emails`: optional Linear user emails for deterministic assignment
+- `provision_start_date` / `provision_end_date`: override the 24-month date range
+
+## Direct seeder usage
+
+```bash
+export LINEAR_API_KEY="lin_api_..."
+python linear/seed/seed_linear.py \
+  --story linear/seed/story_map.yaml \
+  --manifest linear/out/manifest.json \
+  --seed dev-health-linear-demo
+```
+
+## Idempotency and timestamps
+
+The seeder uses stable hashes in issue titles (`[<external_id>]`) and checks for existing issues before writing. Linear does not support backdating issue creation timestamps through normal GraphQL mutations, so simulated historical dates are encoded in issue descriptions, due dates, cycles, and the manifest.
+
+## Investment View themes
+
+`seed/story_map.yaml` uses the canonical Investment View themes only:
+
+- Feature Delivery
+- Operational / Support
+- Maintenance / Tech Debt
+- Quality / Reliability
+- Risk / Security

linear/main.tf

@@ -0,0 +1,59 @@
+locals {
+  dry_run_flag       = var.enable_issue_creation ? "" : "--dry-run"
+  comments_flag      = var.enable_comments ? "" : "--disable-comments"
+  cycles_flag        = var.enable_cycles ? "" : "--disable-cycles"
+  start_date_flag    = var.provision_start_date != "" ? "--start-date ${var.provision_start_date}" : ""
+  end_date_flag      = var.provision_end_date != "" ? "--end-date ${var.provision_end_date}" : ""
+  monthly_issue_flag = var.monthly_issue_count != 0 ? "--monthly-issue-count ${var.monthly_issue_count}" : ""
+  assignees_flag     = length(var.assignee_emails) > 0 ? "--assignees ${join(",", var.assignee_emails)}" : ""
+  date_range_valid   = var.provision_end_date == "" || var.provision_start_date != ""
+  auth_valid         = !var.enable_issue_creation || var.linear_api_key != ""
+}
+
+resource "null_resource" "seed" {
+  lifecycle {
+    precondition {
+      condition     = local.date_range_valid
+      error_message = "provision_start_date is required when provision_end_date is set."
+    }
+    precondition {
+      condition     = local.auth_valid
+      error_message = "linear_api_key is required when enable_issue_creation is true."
+    }
+  }
+
+  triggers = {
+    story_map_hash = filesha256("${path.module}/seed/story_map.yaml")
+    script_hash    = filesha256("${path.module}/seed/seed_linear.py")
+    seed_hash      = sha256(var.seed_string)
+    batch_size     = var.batch_size
+    dry_run        = tostring(!var.enable_issue_creation)
+    start_date     = var.provision_start_date
+    end_date       = var.provision_end_date
+    monthly_issues = var.monthly_issue_count
+  }
+
+  provisioner "local-exec" {
+    command = join(" ", compact([
+      "pip3 install -q -r ${path.module}/seed/requirements.txt &&",
+      "mkdir -p ${path.module}/out &&",
+      "python3",
+      "${path.module}/seed/seed_linear.py",
+      "--story", "${path.module}/seed/story_map.yaml",
+      "--manifest", "${path.module}/out/manifest.json",
+      "--seed", var.seed_string,
+      "--batch-size", tostring(var.batch_size),
+      local.start_date_flag,
+      local.end_date_flag,
+      local.monthly_issue_flag,
+      local.assignees_flag,
+      local.dry_run_flag,
+      local.comments_flag,
+      local.cycles_flag,
+    ]))
+
+    environment = {
+      LINEAR_API_KEY = var.linear_api_key
+    }
+  }
+}

linear/seed/requirements.txt

@@ -0,0 +1,2 @@
+PyYAML==6.0.1
+requests==2.32.4