sequant 1.12.0 → 1.13.1

package/dist/src/lib/upstream/issues.js

@@ -0,0 +1,267 @@
+/**
+ * GitHub issue management for upstream assessments
+ * Handles issue creation, deduplication, and commenting
+ *
+ * Security: All gh CLI calls use spawn() with argument arrays to prevent
+ * command injection. No shell interpolation is used.
+ */
+import { spawn } from "node:child_process";
+import { writeFile, unlink } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { generateFindingIssue } from "./report.js";
+/**
+ * Regex pattern for valid GitHub owner/repo names
+ * Only alphanumeric, hyphens, underscores, and dots allowed
+ */
+const REPO_NAME_PATTERN = /^[a-zA-Z0-9._-]+$/;
+/**
+ * Validate owner and repo names to prevent injection
+ */
+function validateRepoParams(owner, repo) {
+    if (!REPO_NAME_PATTERN.test(owner)) {
+        throw new Error(`Invalid owner name: "${owner}"`);
+    }
+    if (!REPO_NAME_PATTERN.test(repo)) {
+        throw new Error(`Invalid repo name: "${repo}"`);
+    }
+}
+/**
+ * Execute a command safely using spawn with argument arrays
+ * This prevents command injection by not using shell interpolation
+ */
+async function execCommand(command, args) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(command, args, { stdio: ["pipe", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        proc.stdout.on("data", (data) => {
+            stdout += data.toString();
+        });
+        proc.stderr.on("data", (data) => {
+            stderr += data.toString();
+        });
+        proc.on("close", (code) => {
+            if (code === 0) {
+                resolve({ stdout, stderr });
+            }
+            else {
+                reject(new Error(`Command failed with exit code ${code}: ${stderr}`));
+            }
+        });
+        proc.on("error", (err) => {
+            reject(err);
+        });
+    });
+}
+/**
+ * Check if a similar upstream issue already exists
+ */
+export async function checkForDuplicate(title, owner = "admarble", repo = "sequant") {
+    try {
+        validateRepoParams(owner, repo);
+        // Search for existing upstream issues with similar title
+        // Extract key terms from title for search
+        const searchTerms = extractSearchTerms(title);
+        // Use spawn with argument arrays - no shell interpolation
+        const { stdout } = await execCommand("gh", [
+            "issue",
+            "list",
+            "--repo",
+            `${owner}/${repo}`,
+            "--label",
+            "upstream",
+            "--search",
+            searchTerms,
+            "--json",
+            "number,title",
+            "--limit",
+            "10",
+        ]);
+        const issues = JSON.parse(stdout);
+        // Check for similarity
+        for (const issue of issues) {
+            if (isSimilarTitle(title, issue.title)) {
+                return {
+                    isDuplicate: true,
+                    existingIssue: issue.number,
+                    existingTitle: issue.title,
+                };
+            }
+        }
+        return { isDuplicate: false };
+    }
+    catch (error) {
+        // If search fails, assume no duplicate
+        console.error("Error checking for duplicates:", error);
+        return { isDuplicate: false };
+    }
+}
+/**
+ * Extract search terms from a title
+ * Removes common words and version info
+ */
+export function extractSearchTerms(title) {
+    const stopWords = [
+        "the",
+        "a",
+        "an",
+        "from",
+        "to",
+        "in",
+        "for",
+        "of",
+        "on",
+        "with",
+        "claude",
+        "code",
+    ];
+    // Remove version patterns like v2.1.29
+    let cleaned = title.replace(/v?\d+\.\d+\.\d+/g, "");
+    // Remove prefixes
+    cleaned = cleaned.replace(/^(BREAKING|Deprecated|New tool|Hook change|feat|fix|chore):?\s*/i, "");
+    // Split into words and filter
+    const words = cleaned
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((w) => w.length > 2 && !stopWords.includes(w));
+    // Take first 5 meaningful words
+    return words.slice(0, 5).join(" ");
+}
+/**
+ * Check if two titles are similar enough to be duplicates
+ */
+export function isSimilarTitle(title1, title2) {
+    const terms1 = new Set(extractSearchTerms(title1)
+        .split(" ")
+        .filter((t) => t.length > 0));
+    const terms2 = new Set(extractSearchTerms(title2)
+        .split(" ")
+        .filter((t) => t.length > 0));
+    // Calculate Jaccard similarity
+    const intersection = new Set([...terms1].filter((x) => terms2.has(x)));
+    const union = new Set([...terms1, ...terms2]);
+    // Handle edge case where both are empty
+    if (union.size === 0)
+        return false;
+    const similarity = intersection.size / union.size;
+    // Consider similar if > 60% overlap
+    return similarity > 0.6;
+}
+/**
+ * Create a GitHub issue using a temporary file for the body
+ * This avoids any shell escaping issues with complex markdown content
+ */
+export async function createIssue(params, owner = "admarble", repo = "sequant") {
+    validateRepoParams(owner, repo);
+    // Write body to a temp file to avoid any escaping issues
+    const tempFile = join(tmpdir(), `gh-issue-body-${Date.now()}.md`);
+    try {
+        await writeFile(tempFile, params.body, "utf-8");
+        // Build args array
+        const args = [
+            "issue",
+            "create",
+            "--repo",
+            `${owner}/${repo}`,
+            "--title",
+            params.title,
+            "--body-file",
+            tempFile,
+        ];
+        // Add labels
+        for (const label of params.labels) {
+            args.push("--label", label);
+        }
+        const { stdout } = await execCommand("gh", args);
+        // Parse issue URL from output
+        const url = stdout.trim();
+        const numberMatch = url.match(/\/issues\/(\d+)$/);
+        const number = numberMatch ? parseInt(numberMatch[1], 10) : 0;
+        return { number, url };
+    }
+    finally {
+        // Clean up temp file
+        try {
+            await unlink(tempFile);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+    }
+}
+/**
+ * Add a comment to an existing issue
+ */
+export async function addIssueComment(issueNumber, comment, owner = "admarble", repo = "sequant") {
+    validateRepoParams(owner, repo);
+    // Validate issue number
+    if (!Number.isInteger(issueNumber) || issueNumber < 1) {
+        throw new Error(`Invalid issue number: ${issueNumber}`);
+    }
+    // Write comment to a temp file to avoid escaping issues
+    const tempFile = join(tmpdir(), `gh-comment-${Date.now()}.md`);
+    try {
+        await writeFile(tempFile, comment, "utf-8");
+        await execCommand("gh", [
+            "issue",
+            "comment",
+            String(issueNumber),
+            "--repo",
+            `${owner}/${repo}`,
+            "--body-file",
+            tempFile,
+        ]);
+    }
+    finally {
+        // Clean up temp file
+        try {
+            await unlink(tempFile);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+    }
+}
+/**
+ * Create or link an issue for a finding
+ */
+export async function createOrLinkFinding(finding, version, assessmentIssueNumber, dryRun = false, owner = "admarble", repo = "sequant") {
+    // Generate issue content
+    const issueContent = generateFindingIssue(finding, version, assessmentIssueNumber);
+    // Check for duplicate
+    const duplicate = await checkForDuplicate(issueContent.title, owner, repo);
+    if (duplicate.isDuplicate && duplicate.existingIssue) {
+        // Link to existing issue
+        if (!dryRun) {
+            await addIssueComment(duplicate.existingIssue, `Also relevant in Claude Code ${version} assessment${assessmentIssueNumber ? ` (#${assessmentIssueNumber})` : ""}.`, owner, repo);
+        }
+        return {
+            ...finding,
+            existingIssue: duplicate.existingIssue,
+        };
+    }
+    // Create new issue
+    if (!dryRun) {
+        const result = await createIssue(issueContent, owner, repo);
+        return {
+            ...finding,
+            issueNumber: result.number,
+        };
+    }
+    return finding;
+}
+/**
+ * Create the assessment summary issue
+ */
+export async function createAssessmentIssue(title, body, dryRun = false, owner = "admarble", repo = "sequant") {
+    if (dryRun) {
+        return undefined;
+    }
+    const result = await createIssue({
+        title,
+        body,
+        labels: ["upstream", "assessment"],
+    }, owner, repo);
+    return result.number;
+}

package/dist/src/lib/upstream/relevance.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Relevance detection for upstream release changes
+ * Matches changes against sequant's baseline to identify relevant items
+ */
+import type { Baseline, DetectionPatterns, Finding, FindingCategory, ImpactLevel } from "./types.js";
+/**
+ * Default detection patterns for categorizing changes
+ */
+export declare const DEFAULT_PATTERNS: DetectionPatterns;
+/**
+ * Extract individual change items from release body
+ * Handles various markdown formats
+ */
+export declare function extractChanges(releaseBody: string): string[];
+/**
+ * Check if a change matches any keywords from baseline
+ */
+export declare function matchKeywords(change: string, keywords: string[]): string[];
+/**
+ * Check which detection patterns match a change
+ */
+export declare function matchPatterns(change: string, patterns?: DetectionPatterns): string[];
+/**
+ * Determine the category of a change based on matched patterns
+ */
+export declare function categorizeChange(matchedPatterns: string[]): FindingCategory;
+/**
+ * Determine impact level based on category and matched keywords
+ */
+export declare function determineImpact(category: FindingCategory, matchedKeywords: string[]): ImpactLevel;
+/**
+ * Get affected sequant files from dependency map
+ */
+export declare function getImpactFiles(matchedKeywords: string[], dependencyMap: Record<string, string[]>): string[];
+/**
+ * Generate a title for a finding
+ */
+export declare function generateTitle(category: FindingCategory, change: string): string;
+/**
+ * Analyze a single change against the baseline
+ */
+export declare function analyzeChange(change: string, baseline: Baseline): Finding;
+/**
+ * Analyze all changes from a release
+ */
+export declare function analyzeRelease(releaseBody: string, baseline: Baseline): Finding[];
+/**
+ * Filter findings to only actionable ones (not no-action)
+ */
+export declare function getActionableFindings(findings: Finding[]): Finding[];

package/dist/src/lib/upstream/relevance.js

@@ -0,0 +1,209 @@
+/**
+ * Relevance detection for upstream release changes
+ * Matches changes against sequant's baseline to identify relevant items
+ */
+/**
+ * Default detection patterns for categorizing changes
+ */
+export const DEFAULT_PATTERNS = {
+    newTool: /\b(added?|new|introduc(e|ing|ed))\b.*\btool\b/i,
+    deprecation: /\b(deprecat(e|ed|ing|ion)|remov(e|ed|ing)|no longer support)/i,
+    breaking: /\b(breaking|incompatible|must update|require(s|d) migration)/i,
+    hook: /\b(hook|PreToolUse|PostToolUse|pre-tool|post-tool)\b/i,
+    permission: /\b(permission|allow(ed)?|deny|denied|ask|consent|approve|reject)\b/i,
+    mcp: /\b(MCP|model context protocol|mcp server)\b/i,
+};
+/**
+ * Extract individual change items from release body
+ * Handles various markdown formats
+ */
+export function extractChanges(releaseBody) {
+    const changes = [];
+    const lines = releaseBody.split("\n");
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Skip empty lines and headers
+        if (!trimmed || trimmed.startsWith("#")) {
+            continue;
+        }
+        // Match bullet points (-, *, +)
+        const bulletMatch = trimmed.match(/^[-*+]\s+(.+)$/);
+        if (bulletMatch) {
+            changes.push(bulletMatch[1].trim());
+            continue;
+        }
+        // Match numbered items
+        const numberedMatch = trimmed.match(/^\d+\.\s+(.+)$/);
+        if (numberedMatch) {
+            changes.push(numberedMatch[1].trim());
+        }
+    }
+    return changes;
+}
+/**
+ * Check if a change matches any keywords from baseline
+ */
+export function matchKeywords(change, keywords) {
+    const matched = [];
+    for (const keyword of keywords) {
+        // Create word boundary regex for keyword
+        const pattern = new RegExp(`\\b${escapeRegex(keyword)}\\b`, "i");
+        if (pattern.test(change)) {
+            matched.push(keyword);
+        }
+    }
+    return matched;
+}
+/**
+ * Check which detection patterns match a change
+ */
+export function matchPatterns(change, patterns = DEFAULT_PATTERNS) {
+    const matched = [];
+    for (const [name, pattern] of Object.entries(patterns)) {
+        if (pattern.test(change)) {
+            matched.push(name);
+        }
+    }
+    return matched;
+}
+/**
+ * Determine the category of a change based on matched patterns
+ */
+export function categorizeChange(matchedPatterns) {
+    // Priority order: breaking > deprecation > new-tool > hook > opportunity > no-action
+    if (matchedPatterns.includes("breaking")) {
+        return "breaking";
+    }
+    if (matchedPatterns.includes("deprecation")) {
+        return "deprecation";
+    }
+    if (matchedPatterns.includes("newTool")) {
+        return "new-tool";
+    }
+    if (matchedPatterns.includes("hook")) {
+        return "hook-change";
+    }
+    // If any keywords matched but no specific pattern, it's an opportunity
+    if (matchedPatterns.length > 0) {
+        return "opportunity";
+    }
+    return "no-action";
+}
+/**
+ * Determine impact level based on category and matched keywords
+ */
+export function determineImpact(category, matchedKeywords) {
+    // Breaking changes are always high impact
+    if (category === "breaking") {
+        return "high";
+    }
+    // Deprecations are medium to high depending on what's affected
+    if (category === "deprecation") {
+        const criticalKeywords = [
+            "hook",
+            "PreToolUse",
+            "PostToolUse",
+            "permission",
+        ];
+        if (matchedKeywords.some((k) => criticalKeywords.includes(k))) {
+            return "high";
+        }
+        return "medium";
+    }
+    // Hook changes can be significant
+    if (category === "hook-change") {
+        return "medium";
+    }
+    // New tools and opportunities are lower priority
+    if (category === "new-tool" || category === "opportunity") {
+        return "low";
+    }
+    return "none";
+}
+/**
+ * Get affected sequant files from dependency map
+ */
+export function getImpactFiles(matchedKeywords, dependencyMap) {
+    const files = new Set();
+    for (const keyword of matchedKeywords) {
+        const mappedFiles = dependencyMap[keyword];
+        if (mappedFiles) {
+            for (const file of mappedFiles) {
+                files.add(file);
+            }
+        }
+    }
+    return Array.from(files);
+}
+/**
+ * Generate a title for a finding
+ */
+export function generateTitle(category, change) {
+    // Truncate long changes
+    const maxLength = 80;
+    const title = change.length > maxLength ? change.slice(0, maxLength) + "..." : change;
+    // Add prefix based on category
+    switch (category) {
+        case "breaking":
+            return `BREAKING: ${title}`;
+        case "deprecation":
+            return `Deprecated: ${title}`;
+        case "new-tool":
+            return `New tool: ${title}`;
+        case "hook-change":
+            return `Hook change: ${title}`;
+        case "opportunity":
+            return title;
+        default:
+            return title;
+    }
+}
+/**
+ * Analyze a single change against the baseline
+ */
+export function analyzeChange(change, baseline) {
+    // Match keywords and patterns
+    const matchedKeywords = matchKeywords(change, baseline.keywords);
+    const matchedPatterns = matchPatterns(change);
+    // Combine for categorization (keywords count as pattern matches for opportunity detection)
+    const allMatches = [
+        ...matchedPatterns,
+        ...(matchedKeywords.length > 0 ? ["keywords"] : []),
+    ];
+    // Categorize
+    const category = categorizeChange(allMatches);
+    // Determine impact
+    const impact = determineImpact(category, matchedKeywords);
+    // Get affected files
+    const sequantFiles = getImpactFiles(matchedKeywords, baseline.dependencyMap);
+    // Generate title
+    const title = generateTitle(category, change);
+    return {
+        category,
+        title,
+        description: change,
+        impact,
+        matchedKeywords,
+        matchedPatterns,
+        sequantFiles,
+    };
+}
+/**
+ * Analyze all changes from a release
+ */
+export function analyzeRelease(releaseBody, baseline) {
+    const changes = extractChanges(releaseBody);
+    return changes.map((change) => analyzeChange(change, baseline));
+}
+/**
+ * Filter findings to only actionable ones (not no-action)
+ */
+export function getActionableFindings(findings) {
+    return findings.filter((f) => f.category !== "no-action");
+}
+/**
+ * Escape special regex characters in a string
+ */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/src/lib/upstream/report.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Report generation for upstream assessments
+ * Creates markdown reports for GitHub issues and local files
+ */
+import type { AssessmentSummary, Finding, UpstreamAssessment, BatchedAssessment } from "./types.js";
+/**
+ * Calculate summary counts from findings
+ */
+export declare function calculateSummary(findings: Finding[]): AssessmentSummary;
+/**
+ * Generate the assessment issue body
+ */
+export declare function generateAssessmentReport(assessment: UpstreamAssessment): string;
+/**
+ * Generate an individual issue body for an actionable finding
+ */
+export declare function generateFindingIssue(finding: Finding, version: string, assessmentIssueNumber?: number): {
+    title: string;
+    body: string;
+    labels: string[];
+};
+/**
+ * Generate a batched summary issue for multiple versions
+ */
+export declare function generateBatchedSummaryReport(batched: BatchedAssessment): string;
+/**
+ * Generate local report markdown file
+ */
+export declare function generateLocalReport(assessment: UpstreamAssessment): string;