tissues 0.5.1 → 0.6.0

package/src/lib/ai/steps.js

@@ -0,0 +1,472 @@
+/**
+ * Pipeline step definitions for multi-step AI issue enhancement.
+ *
+ * Each step is a plain object with:
+ *   - name:          unique identifier
+ *   - displayName:   human-readable label for progress display
+ *   - maxTokens:     token budget for this step's LLM call
+ *   - shouldRun:     (ctx, stepConfig) => boolean — whether to run in 'auto' mode
+ *   - buildMessages: (ctx) => [{ role, content }] — prompt for the LLM
+ *   - parseResponse: (raw, ctx) => void — parse LLM output and mutate ctx
+ */
+
+import { buildBodyGuidance } from './body-template.js'
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function tryParseJSON(raw) {
+  let cleaned = raw.trim()
+  // Strip markdown fences if present
+  if (cleaned.startsWith('```')) {
+    cleaned = cleaned.replace(/^```(?:json)?\s*\n?/, '').replace(/\n?```\s*$/, '')
+  }
+  return JSON.parse(cleaned)
+}
+
+function contextSummary(ctx) {
+  const parts = [`Title: ${ctx.title}`]
+  if (ctx.description) parts.push(`Description: ${ctx.description}`)
+  if (ctx.instructions) parts.push(`User instructions: ${ctx.instructions}`)
+  if (ctx.templateBody) parts.push(`Template:\n${ctx.templateBody}`)
+  if (ctx.labels?.length) parts.push(`Labels: ${ctx.labels.join(', ')}`)
+  return parts.join('\n\n')
+}
+
+function priorStepsSummary(ctx) {
+  const parts = []
+  if (ctx.dedupScore != null) {
+    parts.push(`Dedup confidence: ${ctx.dedupScore.confidence}/100 (${ctx.dedupScore.level})`)
+  }
+  if (ctx.structuredContext) {
+    parts.push(`Context: ${JSON.stringify(ctx.structuredContext)}`)
+  }
+  if (ctx.scopeAnalysis) {
+    parts.push(`Scope: ${JSON.stringify(ctx.scopeAnalysis)}`)
+  }
+  if (ctx.complexity != null) {
+    parts.push(`Complexity: ${ctx.complexity}/10 — ${ctx.complexityRationale || ''}`)
+  }
+  if (ctx.risk != null) {
+    parts.push(`Risk: ${ctx.risk}/10 — ${ctx.riskRationale || ''}`)
+  }
+  if (ctx.aiLabels?.length) {
+    parts.push(`AI labels: ${ctx.aiLabels.join(', ')}`)
+  }
+  return parts.length > 0 ? '\n\nPrior analysis:\n' + parts.join('\n') : ''
+}
+
+// ---------------------------------------------------------------------------
+// Step: triage — extract title + description from freeform input
+// ---------------------------------------------------------------------------
+
+const triageStep = {
+  name: 'triage',
+  displayName: 'Input analyzed',
+  maxTokens: 1024,
+
+  shouldRun(ctx) {
+    return !!(ctx.rawInput && ctx.rawInput.length > 0)
+  },
+
+  buildMessages(ctx) {
+    return [
+      {
+        role: 'system',
+        content: [
+          'You extract a structured GitHub issue title and description from freeform user input.',
+          'Return a JSON object with:',
+          '  title: string — concise issue title, ≤80 characters, imperative mood (e.g. "Fix login timeout on Safari")',
+          '  description: string — structured description expanding on the input, in markdown',
+          'The title must capture the core intent. The description should organize and expand the raw input into clear context.',
+          'Return ONLY valid JSON.',
+        ].join('\n'),
+      },
+      {
+        role: 'user',
+        content: ctx.rawInput,
+      },
+    ]
+  },
+
+  parseResponse(raw, ctx) {
+    try {
+      const parsed = tryParseJSON(raw)
+      if (parsed.title && typeof parsed.title === 'string') {
+        ctx.title = parsed.title.slice(0, 80)
+      }
+      if (parsed.description && typeof parsed.description === 'string') {
+        ctx.description = parsed.description
+      }
+    } catch {
+      // Parse failure — keep splitInput() values as fallback
+    }
+  },
+}
+
+// ---------------------------------------------------------------------------
+// Step: dedup
+// ---------------------------------------------------------------------------
+
+const dedupStep = {
+  name: 'dedup',
+  displayName: 'Duplicate check',
+  maxTokens: 1024,
+
+  shouldRun(ctx) {
+    // Only useful when there are existing issues to compare against
+    return ctx.existingIssues?.length > 0
+  },
+
+  buildMessages(ctx) {
+    const existing = (ctx.existingIssues || [])
+      .slice(0, 20)
+      .map((i) => `#${i.number}: ${i.title}`)
+      .join('\n')
+
+    return [
+      {
+        role: 'system',
+        content: [
+          'You are a duplicate detection system for GitHub issues.',
+          'Compare the new issue against existing open issues.',
+          'Return a JSON object with:',
+          '  confidence: number 0-100 (how likely this is a duplicate)',
+          '  level: "high" | "medium" | "low" | "none"',
+          '  matches: array of { number, reason } for similar issues',
+          'Return ONLY valid JSON.',
+        ].join('\n'),
+      },
+      {
+        role: 'user',
+        content: `New issue:\nTitle: ${ctx.title}\nDescription: ${ctx.description || 'none'}\n\nExisting open issues:\n${existing}`,
+      },
+    ]
+  },
+
+  parseResponse(raw, ctx) {
+    try {
+      const parsed = tryParseJSON(raw)
+      ctx.dedupScore = {
+        confidence: Math.min(100, Math.max(0, Number(parsed.confidence) || 0)),
+        level: ['high', 'medium', 'low', 'none'].includes(parsed.level) ? parsed.level : 'none',
+        matches: Array.isArray(parsed.matches) ? parsed.matches : [],
+      }
+    } catch {
+      ctx.dedupScore = null
+    }
+  },
+}
+
+// ---------------------------------------------------------------------------
+// Step: context
+// ---------------------------------------------------------------------------
+
+const contextStep = {
+  name: 'context',
+  displayName: 'Context gathered',
+  maxTokens: 1024,
+
+  shouldRun() {
+    return true
+  },
+
+  buildMessages(ctx) {
+    return [
+      {
+        role: 'system',
+        content: [
+          'You are an expert at understanding software issues.',
+          'Extract structured context from the issue description.',
+          'Return a JSON object with:',
+          '  problem: string — the core problem in one sentence',
+          '  files: string[] — file paths mentioned or implied',
+          '  errors: string[] — error messages mentioned',
+          '  sessionContext: string — any relevant session/environment context',
+          'Return ONLY valid JSON.',
+        ].join('\n'),
+      },
+      {
+        role: 'user',
+        content: contextSummary(ctx),
+      },
+    ]
+  },
+
+  parseResponse(raw, ctx) {
+    try {
+      const parsed = tryParseJSON(raw)
+      ctx.structuredContext = {
+        problem: parsed.problem || '',
+        files: Array.isArray(parsed.files) ? parsed.files : [],
+        errors: Array.isArray(parsed.errors) ? parsed.errors : [],
+        sessionContext: parsed.sessionContext || '',
+      }
+    } catch {
+      ctx.structuredContext = null
+    }
+  },
+}
+
+// ---------------------------------------------------------------------------
+// Step: scope
+// ---------------------------------------------------------------------------
+
+const scopeStep = {
+  name: 'scope',
+  displayName: 'Scope analyzed',
+  maxTokens: 1024,
+
+  shouldRun(ctx) {
+    // Only run if description mentions code/files or context step found files
+    const desc = (ctx.description || '').toLowerCase()
+    const hasCodeMentions = /\.(js|ts|py|go|rs|rb|java|css|html|json|yml|yaml|md)\b/.test(desc) ||
+      /\b(file|module|component|function|class|import|require)\b/.test(desc)
+    const hasContextFiles = ctx.structuredContext?.files?.length > 0
+    return hasCodeMentions || hasContextFiles
+  },
+
+  buildMessages(ctx) {
+    return [
+      {
+        role: 'system',
+        content: [
+          'You are a software scope analyzer.',
+          'Given an issue description and context, identify the files and areas affected.',
+          'Return a JSON object with:',
+          '  files: array of { path: string, purpose: string, deps: string[] }',
+          '  affectedAreas: string[] — high-level areas (e.g. "auth", "UI", "database")',
+          'Return ONLY valid JSON.',
+        ].join('\n'),
+      },
+      {
+        role: 'user',
+        content: contextSummary(ctx) + priorStepsSummary(ctx),
+      },
+    ]
+  },
+
+  parseResponse(raw, ctx) {
+    try {
+      const parsed = tryParseJSON(raw)
+      ctx.scopeAnalysis = {
+        files: Array.isArray(parsed.files) ? parsed.files : [],
+        affectedAreas: Array.isArray(parsed.affectedAreas) ? parsed.affectedAreas : [],
+      }
+    } catch {
+      ctx.scopeAnalysis = null
+    }
+  },
+}
+
+// ---------------------------------------------------------------------------
+// Step: complexity
+// ---------------------------------------------------------------------------
+
+const complexityStep = {
+  name: 'complexity',
+  displayName: 'Complexity scored',
+  maxTokens: 512,
+
+  shouldRun(ctx) {
+    // Run if we have scope analysis or a non-trivial description
+    return ctx.scopeAnalysis != null || (ctx.description || '').length > 50
+  },
+
+  buildMessages(ctx) {
+    return [
+      {
+        role: 'system',
+        content: [
+          'You assess implementation complexity for GitHub issues.',
+          'Return a JSON object with:',
+          '  score: number 1-10 (1=trivial, 10=massive refactor)',
+          '  rationale: string — one sentence explaining the score',
+          'Return ONLY valid JSON.',
+        ].join('\n'),
+      },
+      {
+        role: 'user',
+        content: contextSummary(ctx) + priorStepsSummary(ctx),
+      },
+    ]
+  },
+
+  parseResponse(raw, ctx) {
+    try {
+      const parsed = tryParseJSON(raw)
+      ctx.complexity = Math.min(10, Math.max(1, Number(parsed.score) || 5))
+      ctx.complexityRationale = parsed.rationale || ''
+    } catch {
+      ctx.complexity = null
+      ctx.complexityRationale = null
+    }
+  },
+}
+
+// ---------------------------------------------------------------------------
+// Step: risk
+// ---------------------------------------------------------------------------
+
+const riskStep = {
+  name: 'risk',
+  displayName: 'Risk assessed',
+  maxTokens: 512,
+
+  shouldRun(ctx) {
+    return ctx.scopeAnalysis != null || (ctx.description || '').length > 50
+  },
+
+  buildMessages(ctx) {
+    return [
+      {
+        role: 'system',
+        content: [
+          'You assess implementation risk for GitHub issues.',
+          'Consider: breaking changes, data loss potential, security implications, blast radius.',
+          'Return a JSON object with:',
+          '  score: number 1-10 (1=no risk, 10=extremely risky)',
+          '  rationale: string — one sentence explaining the score',
+          'Return ONLY valid JSON.',
+        ].join('\n'),
+      },
+      {
+        role: 'user',
+        content: contextSummary(ctx) + priorStepsSummary(ctx),
+      },
+    ]
+  },
+
+  parseResponse(raw, ctx) {
+    try {
+      const parsed = tryParseJSON(raw)
+      ctx.risk = Math.min(10, Math.max(1, Number(parsed.score) || 3))
+      ctx.riskRationale = parsed.rationale || ''
+    } catch {
+      ctx.risk = null
+      ctx.riskRationale = null
+    }
+  },
+}
+
+// ---------------------------------------------------------------------------
+// Step: labels
+// ---------------------------------------------------------------------------
+
+const labelsStep = {
+  name: 'labels',
+  displayName: 'Labels suggested',
+  maxTokens: 512,
+
+  shouldRun(ctx) {
+    // Run if there are repo labels to choose from
+    return ctx.repoLabels?.length > 0
+  },
+
+  buildMessages(ctx) {
+    const available = (ctx.repoLabels || []).join(', ')
+    return [
+      {
+        role: 'system',
+        content: [
+          'You suggest GitHub labels for issues.',
+          `Available labels in this repo: ${available}`,
+          'Return a JSON object with:',
+          '  labels: string[] — labels to apply (must be from the available list)',
+          '  reasoning: string — brief explanation',
+          'Only suggest labels that genuinely fit. Return ONLY valid JSON.',
+        ].join('\n'),
+      },
+      {
+        role: 'user',
+        content: contextSummary(ctx) + priorStepsSummary(ctx),
+      },
+    ]
+  },
+
+  parseResponse(raw, ctx) {
+    try {
+      const parsed = tryParseJSON(raw)
+      const suggested = Array.isArray(parsed.labels) ? parsed.labels : []
+      // Filter to only labels that actually exist in the repo
+      const valid = ctx.repoLabels || []
+      ctx.aiLabels = suggested.filter((l) => valid.includes(l))
+    } catch {
+      ctx.aiLabels = null
+    }
+  },
+}
+
+// ---------------------------------------------------------------------------
+// Step: format
+// ---------------------------------------------------------------------------
+
+const formatStep = {
+  name: 'format',
+  displayName: 'Body formatted',
+  maxTokens: 4096,
+
+  shouldRun() {
+    return true
+  },
+
+  buildMessages(ctx) {
+    const guidance = buildBodyGuidance(ctx)
+    return [
+      {
+        role: 'system',
+        content: [
+          'You are an expert at writing clear, well-structured GitHub issues.',
+          'Given an issue title, description, and analysis from prior steps,',
+          'write a complete issue body in markdown.',
+          '',
+          guidance,
+        ].join('\n'),
+      },
+      {
+        role: 'user',
+        content: contextSummary(ctx) + priorStepsSummary(ctx),
+      },
+    ]
+  },
+
+  parseResponse(raw, ctx) {
+    // The format step returns raw markdown, not JSON
+    // Strip wrapping code fences (```markdown ... ```) that LLMs often add
+    let cleaned = raw.trim()
+    const fenceMatch = cleaned.match(/^```(?:markdown|md)?\n([\s\S]*)\n```$/)
+    if (fenceMatch) cleaned = fenceMatch[1].trim()
+    if (cleaned.length > 0) {
+      ctx.body = cleaned
+    }
+    // If empty, ctx.body stays as whatever it was (template fallback)
+  },
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+/**
+ * All pipeline steps in execution order.
+ */
+export const ALL_STEPS = [
+  triageStep,
+  dedupStep,
+  contextStep,
+  scopeStep,
+  complexityStep,
+  riskStep,
+  labelsStep,
+  formatStep,
+]
+
+/**
+ * Get a step by name.
+ * @param {string} name
+ * @returns {object|undefined}
+ */
+export function getStep(name) {
+  return ALL_STEPS.find((s) => s.name === name)
+}

package/src/lib/attribution.js

@@ -1,216 +1,55 @@
-import { createRequire } from 'node:module'
-import { fileURLToPath } from 'node:url'
-import path from 'node:path'
-import fs from 'node:fs'
-
-// ---------------------------------------------------------------------------
-// Package version (read once at module load)
-// ---------------------------------------------------------------------------
-
-/**
- * Resolve the package version from the nearest package.json.
- * Falls back to '0.0.0' if unavailable.
- *
- * @returns {string}
- */
-function resolvePackageVersion() {
-  try {
-    const require = createRequire(import.meta.url)
-    // Walk up from this file to find package.json
-    let dir = path.dirname(fileURLToPath(import.meta.url))
-    const { root } = path.parse(dir)
-    while (dir !== root) {
-      const pkgPath = path.join(dir, 'package.json')
-      if (fs.existsSync(pkgPath)) {
-        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'))
-        if (pkg.name === 'tissues' && pkg.version) return pkg.version
-      }
-      dir = path.dirname(dir)
-    }
-  } catch {
-    // ignore
-  }
-  return '0.0.0'
-}
-
-const PKG_VERSION = resolvePackageVersion()
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Return the current UTC timestamp in ISO 8601 format.
- *
- * @returns {string}
- */
-function nowISO() {
-  return new Date().toISOString()
-}
-
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
 
 /**
  * @typedef {object} AttributionOpts
- * @property {string}  [agent]          - agent identifier (e.g. 'claude-opus-4-6')
- * @property {string}  [session]        - session or conversation ID
- * @property {number}  [pid]            - process ID (opt-in; omitted by default)
- * @property {string}  [model]          - AI model used (if any)
- * @property {string}  [trigger]        - how the issue was created (e.g. 'cli-create')
- * @property {string}  [fingerprint]    - content fingerprint (sha256:...)
- * @property {string}  [idempotencyKey] - deterministic idempotency key
- * @property {number}  [risk]           - risk score [0,1]
- * @property {number}  [complexity]     - complexity estimate [0,1]
- * @property {number}  [confidence]     - AI confidence score [0,1]
- * @property {string[]} [contextTags]   - free-form tags for filtering/search
- * @property {string}  [createdAt]      - override timestamp (defaults to now)
+ * @property {string}  [session] - session or conversation ID
+ * @property {string}  [model]   - AI model used (if any)
  */
 
 /**
  * Build a normalized attribution metadata object from raw options.
  *
- * The returned object includes all provided fields plus automatic defaults
- * (`created_at`, `created_via`). Undefined/null fields are omitted.
- * `pid` is opt-in — it is only included if explicitly passed.
+ * Only includes session and model — fields the user actually cares about.
+ * Undefined/null fields are omitted.
  *
  * @param {AttributionOpts} opts
  * @returns {object} metadata record
  */
 export function buildAttribution(opts = {}) {
-  const {
-    agent,
-    session,
-    pid,
-    model,
-    trigger,
-    fingerprint,
-    idempotencyKey,
-    risk,
-    complexity,
-    confidence,
-    contextTags,
-    createdAt,
-  } = opts
-
+  const { session, model } = opts
   const meta = {}
 
-  // Identity
-  if (agent != null) meta.agent = String(agent)
   if (session != null) meta.session = String(session)
   if (model != null) meta.model = String(model)
 
-  // Process info (pid is opt-in — pass it explicitly to include)
-  if (pid != null) meta.pid = Number(pid)
-  meta.trigger = trigger != null ? String(trigger) : 'cli-create'
-
-  // Deduplication handles
-  if (fingerprint != null) meta.fingerprint = String(fingerprint)
-  if (idempotencyKey != null) meta.idempotency_key = String(idempotencyKey)
-
-  // Scoring (numeric, clamped to [0,1])
-  if (risk != null) meta.risk = Math.max(0, Math.min(1, Number(risk)))
-  if (complexity != null) meta.complexity = Math.max(0, Math.min(1, Number(complexity)))
-  if (confidence != null) meta.confidence = Math.max(0, Math.min(1, Number(confidence)))
-
-  // Tags
-  if (Array.isArray(contextTags) && contextTags.length > 0) {
-    meta.context_tags = contextTags.map(String)
-  }
-
-  // Timestamps / versioning
-  meta.created_at = createdAt ?? nowISO()
-  meta.created_via = `tissues-cli/${PKG_VERSION.split('.').slice(0, 2).join('.')}`
-
   return meta
 }
 
 /**
- * Render attribution metadata as an HTML comment block for inclusion at the
- * bottom of a GitHub issue body.
- *
- * The format is a YAML-like key: value listing inside an HTML comment, which
- * GitHub renders as invisible text. Other tools (including tissues itself)
- * can parse it back via `parseAttribution`.
+ * Render attribution metadata as a YAML frontmatter block for inclusion at
+ * the bottom of a GitHub issue body.
  *
  * @example
- * <!-- tissues-meta
- * agent: claude-opus-4-6
+ * ---
+ * tissues-meta:
  * session: abc123
- * trigger: cli-create
- * fingerprint: sha256:deadbeef
- * created_at: 2026-02-19T15:30:00Z
- * created_via: tissues-cli/0.1
- * -->
+ * model: claude-opus-4-6
+ * ---
  *
  * @param {AttributionOpts} opts
- * @returns {string}
+ * @returns {string | null} frontmatter block, or null if no fields to render
  */
 export function renderAttribution(opts = {}) {
   const meta = buildAttribution(opts)
-  const lines = ['<!-- tissues-meta']
+  const entries = Object.entries(meta)
+  if (entries.length === 0) return null
 
-  for (const [key, value] of Object.entries(meta)) {
-    if (Array.isArray(value)) {
-      // Render arrays as comma-separated values on a single line
-      lines.push(`${key}: ${value.join(', ')}`)
-    } else {
-      lines.push(`${key}: ${value}`)
-    }
+  const lines = ['---', 'tissues-meta:']
+  for (const [key, value] of entries) {
+    lines.push(`${key}: ${value}`)
   }
-
-  lines.push('-->')
+  lines.push('---')
   return lines.join('\n')
 }
-
-/**
- * Parse a `<!-- tissues-meta ... -->` attribution block from an issue body.
- *
- * Returns the parsed key/value pairs as a plain object, or `null` if no
- * attribution block is present in `issueBody`.
- *
- * Numeric fields (`risk`, `complexity`, `confidence`) are coerced to
- * numbers. The `context_tags` field is split back into an array.
- *
- * @param {string} issueBody - raw GitHub issue body markdown
- * @returns {object|null} parsed metadata, or null if not found
- */
-export function parseAttribution(issueBody) {
-  if (!issueBody) return null
-
-  // Match the comment block (non-greedy, handle CRLF)
-  const match = issueBody.match(/<!--\s*tissues-meta\s*([\s\S]*?)-->/m)
-  if (!match) return null
-
-  const block = match[1]
-  const meta = {}
-
-  for (const line of block.split(/\r?\n/)) {
-    const trimmed = line.trim()
-    if (!trimmed) continue
-
-    const colonIdx = trimmed.indexOf(':')
-    if (colonIdx === -1) continue
-
-    const key = trimmed.slice(0, colonIdx).trim()
-    const rawValue = trimmed.slice(colonIdx + 1).trim()
-
-    if (!key) continue
-
-    // Type coercions
-    if (['pid'].includes(key)) {
-      const n = Number(rawValue)
-      meta[key] = Number.isNaN(n) ? rawValue : n
-    } else if (['risk', 'complexity', 'confidence'].includes(key)) {
-      const n = parseFloat(rawValue)
-      meta[key] = Number.isNaN(n) ? rawValue : n
-    } else if (key === 'context_tags') {
-      meta[key] = rawValue.split(',').map((t) => t.trim()).filter(Boolean)
-    } else {
-      meta[key] = rawValue
-    }
-  }
-
-  return Object.keys(meta).length > 0 ? meta : null
-}