sequant 1.12.0 → 1.13.1

package/dist/src/lib/content-analyzer.js

@@ -0,0 +1,437 @@
+/**
+ * Content Analyzer for Phase Detection
+ *
+ * Analyzes issue title and body content to detect phase-relevant keywords
+ * and patterns. This supplements (not replaces) label-based detection.
+ *
+ * @example
+ * ```typescript
+ * import { analyzeTitleForPhases, analyzeBodyForPhases, analyzeContentForPhases } from './content-analyzer';
+ *
+ * const title = "Extract header component from main layout";
+ * const body = "Refactor the header.tsx file to create a reusable component...";
+ *
+ * const signals = analyzeContentForPhases(title, body);
+ * // Returns: { phases: ['test'], signals: [...], source: 'content' }
+ * ```
+ */
+/**
+ * Title keyword patterns for phase detection
+ *
+ * Based on issue #175 specification:
+ * | Pattern | Detection | Suggested Phase |
+ * |---------|-----------|-----------------|
+ * | `extract`, `component`, `refactor.*ui` | UI work | Add `/test` |
+ * | `fix.*unused`, `remove.*variable`, `typo` | Trivial | Note in output |
+ * | `auth`, `permission`, `security` | Security-sensitive | Add `/security-review` |
+ * | `api`, `endpoint`, `route` | Backend | Skip `/test` |
+ */
+const TITLE_PATTERNS = [
+    // UI work patterns → Add /test
+    {
+        pattern: /\bextract\b/i,
+        phase: "test",
+        confidence: "high",
+        reason: "Component extraction typically requires UI testing",
+    },
+    {
+        pattern: /\bcomponent\b/i,
+        phase: "test",
+        confidence: "medium",
+        reason: "Component work typically requires UI testing",
+    },
+    {
+        pattern: /\brefactor.*ui\b/i,
+        phase: "test",
+        confidence: "high",
+        reason: "UI refactoring requires browser testing",
+    },
+    {
+        pattern: /\bui\s*(refactor|change|update)\b/i,
+        phase: "test",
+        confidence: "high",
+        reason: "UI changes require browser testing",
+    },
+    {
+        pattern: /\bfrontend\b/i,
+        phase: "test",
+        confidence: "medium",
+        reason: "Frontend work typically requires UI testing",
+    },
+    {
+        pattern: /\bdashboard\b/i,
+        phase: "test",
+        confidence: "medium",
+        reason: "Dashboard changes require browser testing",
+    },
+    {
+        pattern: /\badmin\s*(page|panel|ui)\b/i,
+        phase: "test",
+        confidence: "medium",
+        reason: "Admin UI changes require browser testing",
+    },
+    // Security-sensitive patterns → Add /security-review
+    {
+        pattern: /\bauth(entication|orization)?\b/i,
+        phase: "security-review",
+        confidence: "high",
+        reason: "Authentication changes require security review",
+    },
+    {
+        pattern: /\bpermission[s]?\b/i,
+        phase: "security-review",
+        confidence: "high",
+        reason: "Permission changes require security review",
+    },
+    {
+        pattern: /\bsecurity\b/i,
+        phase: "security-review",
+        confidence: "high",
+        reason: "Security-related changes require security review",
+    },
+    {
+        pattern: /\brole[s]?\s*(based|access|control)\b/i,
+        phase: "security-review",
+        confidence: "high",
+        reason: "Role-based access changes require security review",
+    },
+    {
+        pattern: /\baccess\s*control\b/i,
+        phase: "security-review",
+        confidence: "high",
+        reason: "Access control changes require security review",
+    },
+    {
+        pattern: /\btoken[s]?\b/i,
+        phase: "security-review",
+        confidence: "medium",
+        reason: "Token handling may require security review",
+    },
+    {
+        pattern: /\bpassword[s]?\b/i,
+        phase: "security-review",
+        confidence: "high",
+        reason: "Password handling requires security review",
+    },
+    {
+        pattern: /\bcredential[s]?\b/i,
+        phase: "security-review",
+        confidence: "high",
+        reason: "Credential handling requires security review",
+    },
+    // Complex work patterns → Enable quality loop
+    {
+        pattern: /\brefactor\b/i,
+        phase: "quality-loop",
+        confidence: "medium",
+        reason: "Refactoring benefits from quality loop iterations",
+    },
+    {
+        pattern: /\bmigrat(e|ion)\b/i,
+        phase: "quality-loop",
+        confidence: "high",
+        reason: "Migrations are complex and benefit from quality loop",
+    },
+    {
+        pattern: /\brestructur(e|ing)\b/i,
+        phase: "quality-loop",
+        confidence: "high",
+        reason: "Restructuring is complex and benefits from quality loop",
+    },
+    {
+        pattern: /\bbreaking\s*change\b/i,
+        phase: "quality-loop",
+        confidence: "high",
+        reason: "Breaking changes require careful quality validation",
+    },
+];
+/**
+ * Body content patterns for phase detection
+ *
+ * Based on issue #175 specification:
+ * | Pattern | Detection |
+ * |---------|-----------|
+ * | References `.tsx` files | UI work likely |
+ * | References `scripts/` | CLI work, needs `/verify` |
+ * | Contains "breaking change" | Complex, enable quality loop |
+ */
+const BODY_PATTERNS = [
+    // UI work patterns
+    {
+        pattern: /\.tsx\b/i,
+        phase: "test",
+        confidence: "medium",
+        reason: "References .tsx files indicating React components",
+    },
+    {
+        pattern: /\.jsx\b/i,
+        phase: "test",
+        confidence: "medium",
+        reason: "References .jsx files indicating React components",
+    },
+    {
+        pattern: /\bcomponents?\//i,
+        phase: "test",
+        confidence: "medium",
+        reason: "References components directory",
+    },
+    {
+        pattern: /\bpages?\//i,
+        phase: "test",
+        confidence: "low",
+        reason: "References pages directory (may be UI)",
+    },
+    {
+        pattern: /\bapp\/.*page\.tsx\b/i,
+        phase: "test",
+        confidence: "high",
+        reason: "References Next.js page component",
+    },
+    // CLI/Script work patterns
+    {
+        pattern: /\bscripts\//i,
+        phase: "exec",
+        confidence: "medium",
+        reason: "References scripts directory, may need verify phase",
+    },
+    {
+        pattern: /\bbin\//i,
+        phase: "exec",
+        confidence: "medium",
+        reason: "References bin directory, CLI work",
+    },
+    {
+        pattern: /\bcli\b/i,
+        phase: "exec",
+        confidence: "low",
+        reason: "Mentions CLI functionality",
+    },
+    // Security patterns
+    {
+        pattern: /\bauth\//i,
+        phase: "security-review",
+        confidence: "high",
+        reason: "References auth directory",
+    },
+    {
+        pattern: /\bmiddleware\.ts\b/i,
+        phase: "security-review",
+        confidence: "medium",
+        reason: "References middleware (often auth-related)",
+    },
+    {
+        pattern: /\brls\s*(polic|rule)/i,
+        phase: "security-review",
+        confidence: "high",
+        reason: "References RLS (Row Level Security)",
+    },
+    {
+        pattern: /\bserver[-_]?action/i,
+        phase: "security-review",
+        confidence: "medium",
+        reason: "Server actions may require security review",
+    },
+    // Complexity patterns
+    {
+        pattern: /\bbreaking\s*change\b/i,
+        phase: "quality-loop",
+        confidence: "high",
+        reason: "Breaking change mentioned in body",
+    },
+    {
+        pattern: /\bmajor\s*(refactor|change|update)\b/i,
+        phase: "quality-loop",
+        confidence: "high",
+        reason: "Major changes benefit from quality loop",
+    },
+    {
+        pattern: /\bcomplex\b/i,
+        phase: "quality-loop",
+        confidence: "low",
+        reason: "Complexity mentioned, may benefit from quality loop",
+    },
+];
+/**
+ * Trivial work patterns (for noting, not phase changes)
+ * These are informational - we note them but don't change phases
+ */
+const TRIVIAL_PATTERNS = [
+    /\bfix.*unused\b/i,
+    /\bremove.*variable\b/i,
+    /\btypo\b/i,
+    /\btypos\b/i,
+    /\bspelling\b/i,
+    /\bwhitespace\b/i,
+    /\bformat(ting)?\b/i,
+    /\blint(ing)?\b/i,
+];
+/**
+ * Analyze issue title for phase-relevant keywords
+ *
+ * @param title - The issue title
+ * @returns Array of detected signals
+ */
+export function analyzeTitleForPhases(title) {
+    const signals = [];
+    for (const { pattern, phase, confidence, reason } of TITLE_PATTERNS) {
+        const match = title.match(pattern);
+        if (match) {
+            signals.push({
+                phase,
+                source: "title",
+                pattern: pattern.source,
+                match: match[0],
+                confidence,
+                reason,
+            });
+        }
+    }
+    return signals;
+}
+/**
+ * Analyze issue body for phase-relevant patterns
+ *
+ * @param body - The issue body
+ * @returns Array of detected signals
+ */
+export function analyzeBodyForPhases(body) {
+    const signals = [];
+    for (const { pattern, phase, confidence, reason } of BODY_PATTERNS) {
+        const match = body.match(pattern);
+        if (match) {
+            signals.push({
+                phase,
+                source: "body",
+                pattern: pattern.source,
+                match: match[0],
+                confidence,
+                reason,
+            });
+        }
+    }
+    return signals;
+}
+/**
+ * Check if content indicates trivial work
+ *
+ * @param title - The issue title
+ * @param body - The issue body
+ * @returns True if the work appears trivial
+ */
+export function isTrivialWork(title, body) {
+    const combined = `${title}\n${body}`;
+    for (const pattern of TRIVIAL_PATTERNS) {
+        if (pattern.test(combined)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Analyze issue content (title + body) for phase recommendations
+ *
+ * This is the main entry point for content analysis.
+ * It analyzes both title and body, deduplicates signals,
+ * and returns a consolidated result.
+ *
+ * @param title - The issue title
+ * @param body - The issue body
+ * @returns Consolidated analysis result with phases and signals
+ */
+export function analyzeContentForPhases(title, body) {
+    const titleSignals = analyzeTitleForPhases(title);
+    const bodySignals = analyzeBodyForPhases(body);
+    // Combine all signals
+    const allSignals = [...titleSignals, ...bodySignals];
+    // Deduplicate phases (keep highest confidence signal for each phase)
+    const phaseMap = new Map();
+    const confidenceRank = {
+        high: 3,
+        medium: 2,
+        low: 1,
+    };
+    for (const signal of allSignals) {
+        const existing = phaseMap.get(signal.phase);
+        const currentRank = confidenceRank[signal.confidence];
+        if (!existing || currentRank > existing.confidence) {
+            phaseMap.set(signal.phase, { signal, confidence: currentRank });
+        }
+    }
+    // Extract phases and quality loop setting
+    const phases = [];
+    let qualityLoop = false;
+    for (const [phase] of phaseMap) {
+        if (phase === "quality-loop") {
+            qualityLoop = true;
+        }
+        else {
+            phases.push(phase);
+        }
+    }
+    // Build notes
+    const notes = [];
+    if (isTrivialWork(title, body)) {
+        notes.push("Trivial work detected - may not require full workflow");
+    }
+    if (phases.includes("test")) {
+        notes.push("UI/component work detected - browser testing recommended");
+    }
+    if (phases.includes("security-review")) {
+        notes.push("Security-sensitive content detected - security review recommended");
+    }
+    if (qualityLoop) {
+        notes.push("Complex work detected - quality loop recommended");
+    }
+    if (allSignals.length === 0) {
+        notes.push("No phase signals detected from content analysis");
+    }
+    return {
+        phases,
+        qualityLoop,
+        signals: allSignals,
+        notes,
+    };
+}
+/**
+ * Format content analysis result for display
+ *
+ * @param result - The analysis result
+ * @returns Formatted markdown string
+ */
+export function formatContentAnalysis(result) {
+    const lines = [];
+    lines.push("## Content Analysis");
+    lines.push("");
+    if (result.signals.length === 0) {
+        lines.push("No phase-relevant patterns detected in title or body.");
+        return lines.join("\n");
+    }
+    lines.push("### Detected Signals");
+    lines.push("");
+    lines.push("| Source | Pattern | Match | Phase | Confidence | Reason |");
+    lines.push("|--------|---------|-------|-------|------------|--------|");
+    for (const signal of result.signals) {
+        const phaseDisplay = signal.phase === "quality-loop" ? "quality-loop" : `/${signal.phase}`;
+        lines.push(`| ${signal.source} | \`${signal.pattern}\` | "${signal.match}" | ${phaseDisplay} | ${signal.confidence} | ${signal.reason} |`);
+    }
+    lines.push("");
+    if (result.phases.length > 0 || result.qualityLoop) {
+        lines.push("### Recommendations");
+        lines.push("");
+        if (result.phases.length > 0) {
+            lines.push(`**Additional phases:** ${result.phases.map((p) => `/${p}`).join(", ")}`);
+        }
+        if (result.qualityLoop) {
+            lines.push("**Quality loop:** Recommended based on content complexity");
+        }
+    }
+    if (result.notes.length > 0) {
+        lines.push("");
+        lines.push("### Notes");
+        lines.push("");
+        for (const note of result.notes) {
+            lines.push(`- ${note}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/src/lib/phase-signal.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Phase Signal Types and Merging
+ *
+ * Provides types for tracking where phase recommendations come from
+ * and logic for merging signals with priority:
+ * Labels > Solve Comment > Title > Body
+ *
+ * @example
+ * ```typescript
+ * import { PhaseSignal, mergePhaseSignals } from './phase-signal';
+ *
+ * const signals: PhaseSignal[] = [
+ *   { phase: 'test', source: 'label', confidence: 'high' },
+ *   { phase: 'test', source: 'title', confidence: 'medium' },
+ *   { phase: 'security-review', source: 'body', confidence: 'high' },
+ * ];
+ *
+ * const merged = mergePhaseSignals(signals);
+ * // Returns unique phases with highest-priority source for each
+ * ```
+ */
+import type { Phase } from "./workflow/types.js";
+/**
+ * Source of a phase signal, ordered by priority (highest first)
+ */
+export type SignalSource = "label" | "solve" | "title" | "body";
+/**
+ * Priority order for signal sources (higher = takes precedence)
+ */
+export declare const SIGNAL_PRIORITY: Record<SignalSource, number>;
+/**
+ * Confidence level for a signal
+ */
+export type SignalConfidence = "high" | "medium" | "low";
+/**
+ * A phase signal with source tracking
+ */
+export interface PhaseSignal {
+    /** The phase being recommended */
+    phase: Phase | "quality-loop";
+    /** Where this signal came from */
+    source: SignalSource;
+    /** Confidence level of the signal */
+    confidence: SignalConfidence;
+    /** Human-readable reason for this signal */
+    reason?: string;
+    /** The pattern or keyword that matched (for content signals) */
+    match?: string;
+}
+/**
+ * Result of merging phase signals
+ */
+export interface MergedPhaseResult {
+    /** Unique phases to include in workflow */
+    phases: Phase[];
+    /** Whether quality loop should be enabled */
+    qualityLoop: boolean;
+    /** Map of phase to the signal that contributed it */
+    phaseSignals: Map<Phase | "quality-loop", PhaseSignal>;
+    /** All original signals (for debugging/display) */
+    allSignals: PhaseSignal[];
+}
+/**
+ * Merge phase signals with priority-based deduplication
+ *
+ * Priority order: Labels > Solve > Title > Body
+ * When multiple signals suggest the same phase, the highest-priority
+ * source wins. Signals can only ADD phases, never remove.
+ *
+ * @param signals - Array of phase signals from various sources
+ * @returns Merged result with unique phases and source tracking
+ */
+export declare function mergePhaseSignals(signals: PhaseSignal[]): MergedPhaseResult;
+/**
+ * Create a phase signal from a label
+ *
+ * @param labelName - The GitHub label name
+ * @returns Phase signal if the label maps to a phase, null otherwise
+ */
+export declare function signalFromLabel(labelName: string): PhaseSignal | null;
+/**
+ * Create phase signals from an array of labels
+ *
+ * @param labels - Array of GitHub label names
+ * @returns Array of phase signals from labels
+ */
+export declare function signalsFromLabels(labels: string[]): PhaseSignal[];
+/**
+ * Format merged phase result for display
+ *
+ * @param result - The merged phase result
+ * @returns Formatted markdown string
+ */
+export declare function formatMergedPhases(result: MergedPhaseResult): string;

package/dist/src/lib/phase-signal.js

@@ -0,0 +1,171 @@
+/**
+ * Phase Signal Types and Merging
+ *
+ * Provides types for tracking where phase recommendations come from
+ * and logic for merging signals with priority:
+ * Labels > Solve Comment > Title > Body
+ *
+ * @example
+ * ```typescript
+ * import { PhaseSignal, mergePhaseSignals } from './phase-signal';
+ *
+ * const signals: PhaseSignal[] = [
+ *   { phase: 'test', source: 'label', confidence: 'high' },
+ *   { phase: 'test', source: 'title', confidence: 'medium' },
+ *   { phase: 'security-review', source: 'body', confidence: 'high' },
+ * ];
+ *
+ * const merged = mergePhaseSignals(signals);
+ * // Returns unique phases with highest-priority source for each
+ * ```
+ */
+/**
+ * Priority order for signal sources (higher = takes precedence)
+ */
+export const SIGNAL_PRIORITY = {
+    label: 4, // Highest priority - explicit labels
+    solve: 3, // Solve command analysis
+    title: 2, // Title keyword detection
+    body: 1, // Body pattern detection (lowest)
+};
+/**
+ * Merge phase signals with priority-based deduplication
+ *
+ * Priority order: Labels > Solve > Title > Body
+ * When multiple signals suggest the same phase, the highest-priority
+ * source wins. Signals can only ADD phases, never remove.
+ *
+ * @param signals - Array of phase signals from various sources
+ * @returns Merged result with unique phases and source tracking
+ */
+export function mergePhaseSignals(signals) {
+    // Map to track the best signal for each phase
+    const phaseSignals = new Map();
+    for (const signal of signals) {
+        const existing = phaseSignals.get(signal.phase);
+        if (!existing) {
+            // First signal for this phase
+            phaseSignals.set(signal.phase, signal);
+        }
+        else {
+            // Compare priorities - higher wins
+            const existingPriority = SIGNAL_PRIORITY[existing.source];
+            const newPriority = SIGNAL_PRIORITY[signal.source];
+            if (newPriority > existingPriority) {
+                phaseSignals.set(signal.phase, signal);
+            }
+            // If same priority, keep the existing one (first wins)
+        }
+    }
+    // Extract phases and quality loop setting
+    const phases = [];
+    let qualityLoop = false;
+    for (const [phase] of phaseSignals) {
+        if (phase === "quality-loop") {
+            qualityLoop = true;
+        }
+        else {
+            phases.push(phase);
+        }
+    }
+    return {
+        phases,
+        qualityLoop,
+        phaseSignals,
+        allSignals: signals,
+    };
+}
+/**
+ * Create a phase signal from a label
+ *
+ * @param labelName - The GitHub label name
+ * @returns Phase signal if the label maps to a phase, null otherwise
+ */
+export function signalFromLabel(labelName) {
+    const lowerLabel = labelName.toLowerCase();
+    // UI/Frontend labels → test phase
+    if (["ui", "frontend", "admin"].includes(lowerLabel)) {
+        return {
+            phase: "test",
+            source: "label",
+            confidence: "high",
+            reason: `Label '${labelName}' indicates UI work requiring browser testing`,
+        };
+    }
+    // Security labels → security-review phase
+    if (["security", "auth", "permissions"].includes(lowerLabel)) {
+        return {
+            phase: "security-review",
+            source: "label",
+            confidence: "high",
+            reason: `Label '${labelName}' indicates security-sensitive changes`,
+        };
+    }
+    // Complex work labels → quality loop
+    if (["complex", "refactor", "breaking", "major"].includes(lowerLabel)) {
+        return {
+            phase: "quality-loop",
+            source: "label",
+            confidence: "high",
+            reason: `Label '${labelName}' indicates complex work benefiting from quality loop`,
+        };
+    }
+    // Backend labels → no specific phase (but note for test skipping)
+    if (["backend", "api", "cli"].includes(lowerLabel)) {
+        return null; // Backend work doesn't add phases, but we may skip /test
+    }
+    return null;
+}
+/**
+ * Create phase signals from an array of labels
+ *
+ * @param labels - Array of GitHub label names
+ * @returns Array of phase signals from labels
+ */
+export function signalsFromLabels(labels) {
+    const signals = [];
+    for (const label of labels) {
+        const signal = signalFromLabel(label);
+        if (signal) {
+            signals.push(signal);
+        }
+    }
+    return signals;
+}
+/**
+ * Format merged phase result for display
+ *
+ * @param result - The merged phase result
+ * @returns Formatted markdown string
+ */
+export function formatMergedPhases(result) {
+    const lines = [];
+    lines.push("## Phase Signal Summary");
+    lines.push("");
+    if (result.allSignals.length === 0) {
+        lines.push("No phase signals detected.");
+        return lines.join("\n");
+    }
+    lines.push("### Signal Sources");
+    lines.push("");
+    lines.push("| Phase | Source | Confidence | Reason |");
+    lines.push("|-------|--------|------------|--------|");
+    for (const [phase, signal] of result.phaseSignals) {
+        const phaseDisplay = phase === "quality-loop" ? "quality-loop" : `/${phase}`;
+        const reason = signal.reason || "-";
+        lines.push(`| ${phaseDisplay} | ${signal.source} | ${signal.confidence} | ${reason} |`);
+    }
+    lines.push("");
+    lines.push("### Final Recommendations");
+    lines.push("");
+    if (result.phases.length > 0) {
+        lines.push(`**Phases to add:** ${result.phases.map((p) => `/${p}`).join(", ")}`);
+    }
+    else {
+        lines.push("**Phases to add:** None");
+    }
+    if (result.qualityLoop) {
+        lines.push("**Quality loop:** Enabled");
+    }
+    return lines.join("\n");
+}