sequant 1.12.0 → 1.13.1

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

@@ -0,0 +1,385 @@
+/**
+ * Main assessment module for upstream analysis
+ * Coordinates release fetching, analysis, and output generation
+ */
+import { spawn } from "node:child_process";
+import { readFile, writeFile, access, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { analyzeRelease, getActionableFindings } from "./relevance.js";
+import { calculateSummary, generateAssessmentReport, generateBatchedSummaryReport, generateLocalReport, } from "./report.js";
+import { createAssessmentIssue, createOrLinkFinding } from "./issues.js";
+/**
+ * Regex pattern for valid semantic version strings
+ * Matches: v1.2.3, 1.2.3, v1.2.3-beta.1, v1.2.3-rc1, etc.
+ */
+const VERSION_PATTERN = /^v?\d+\.\d+\.\d+(-[\w.]+)?$/;
+/**
+ * Validate a version string to prevent command injection
+ * @throws Error if version format is invalid
+ */
+export function validateVersion(version) {
+    if (!VERSION_PATTERN.test(version)) {
+        throw new Error(`Invalid version format: "${version}". Expected semver format (e.g., v1.2.3 or 1.2.3-beta.1)`);
+    }
+}
+/**
+ * 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 gh CLI is available and authenticated
+ * @returns Object with availability status and error message if not available
+ */
+export async function checkGhCliAvailable() {
+    try {
+        // Check if gh is installed
+        await execCommand("gh", ["--version"]);
+    }
+    catch {
+        return {
+            available: false,
+            authenticated: false,
+            error: "GitHub CLI (gh) is not installed. Install from: https://cli.github.com/",
+        };
+    }
+    try {
+        // Check if gh is authenticated
+        await execCommand("gh", ["auth", "status"]);
+        return { available: true, authenticated: true };
+    }
+    catch {
+        return {
+            available: true,
+            authenticated: false,
+            error: "GitHub CLI is not authenticated. Run: gh auth login",
+        };
+    }
+}
+/**
+ * Default paths for upstream files
+ */
+const BASELINE_PATH = ".sequant/upstream/baseline.json";
+const REPORTS_DIR = ".sequant/upstream";
+/**
+ * Fetch release data from Claude Code repository
+ */
+export async function fetchRelease(version) {
+    try {
+        // Validate version if provided to prevent injection
+        if (version) {
+            validateVersion(version);
+        }
+        // Build args array safely - no shell interpolation
+        const args = ["release", "view"];
+        if (version) {
+            args.push(version);
+        }
+        args.push("--repo", "anthropics/claude-code", "--json", "tagName,name,body,publishedAt");
+        const { stdout } = await execCommand("gh", args);
+        return JSON.parse(stdout);
+    }
+    catch (error) {
+        console.error("Error fetching release:", error);
+        return null;
+    }
+}
+/**
+ * List releases from Claude Code repository
+ */
+export async function listReleases(limit = 50) {
+    try {
+        // Validate limit is a reasonable positive integer
+        if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+            throw new Error("Limit must be an integer between 1 and 100");
+        }
+        const { stdout } = await execCommand("gh", [
+            "release",
+            "list",
+            "--repo",
+            "anthropics/claude-code",
+            "--limit",
+            String(limit),
+            "--json",
+            "tagName,publishedAt",
+        ]);
+        return JSON.parse(stdout);
+    }
+    catch (error) {
+        console.error("Error listing releases:", error);
+        return [];
+    }
+}
+/**
+ * Get releases since a specific version
+ */
+export async function getReleasesSince(sinceVersion) {
+    const releases = await listReleases();
+    const versions = [];
+    for (const release of releases) {
+        if (release.tagName === sinceVersion) {
+            break;
+        }
+        versions.push(release.tagName);
+    }
+    return versions.reverse(); // Oldest first
+}
+/**
+ * Load baseline from file
+ */
+export async function loadBaseline(path = BASELINE_PATH) {
+    try {
+        const content = await readFile(path, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        // Return default baseline if file doesn't exist
+        console.warn("Baseline not found, using defaults");
+        return getDefaultBaseline();
+    }
+}
+/**
+ * Save baseline to file
+ */
+export async function saveBaseline(baseline, path = BASELINE_PATH) {
+    await ensureDir(dirname(path));
+    await writeFile(path, JSON.stringify(baseline, null, 2));
+}
+/**
+ * Update baseline with new assessed version
+ */
+export async function updateBaseline(version, path = BASELINE_PATH) {
+    const baseline = await loadBaseline(path);
+    baseline.lastAssessedVersion = version;
+    await saveBaseline(baseline, path);
+}
+/**
+ * Check if a version has already been assessed
+ */
+export async function isAlreadyAssessed(version) {
+    const reportPath = join(REPORTS_DIR, `${version}.md`);
+    try {
+        await access(reportPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Save local report
+ */
+export async function saveLocalReport(assessment) {
+    const reportPath = join(REPORTS_DIR, `${assessment.version}.md`);
+    await ensureDir(REPORTS_DIR);
+    const content = generateLocalReport(assessment);
+    await writeFile(reportPath, content);
+    return reportPath;
+}
+/**
+ * Run a single version assessment
+ */
+export async function assessVersion(version, options = {}) {
+    const { dryRun = false, force = false } = options;
+    // Check if already assessed
+    if (!force && (await isAlreadyAssessed(version))) {
+        console.log(`Already assessed: ${version}. Use --force to re-assess.`);
+        return null;
+    }
+    // Fetch release
+    const release = await fetchRelease(version);
+    if (!release) {
+        console.error(`Failed to fetch release: ${version}`);
+        return null;
+    }
+    // Load baseline
+    const baseline = await loadBaseline();
+    // Analyze
+    const findings = analyzeRelease(release.body, baseline);
+    const actionableFindings = getActionableFindings(findings);
+    // Create assessment object
+    const assessment = {
+        version: release.tagName,
+        releaseDate: release.publishedAt.split("T")[0],
+        assessmentDate: new Date().toISOString().split("T")[0],
+        previousVersion: baseline.lastAssessedVersion,
+        findings,
+        issuesCreated: [],
+        summary: calculateSummary(findings),
+        dryRun,
+    };
+    // Create assessment issue first (to get issue number for linking)
+    const assessmentBody = generateAssessmentReport(assessment);
+    const assessmentIssueNumber = await createAssessmentIssue(`Upstream: Claude Code ${release.tagName} Assessment`, assessmentBody, dryRun);
+    // Create issues for actionable findings
+    for (let i = 0; i < actionableFindings.length; i++) {
+        const updatedFinding = await createOrLinkFinding(actionableFindings[i], release.tagName, assessmentIssueNumber, dryRun);
+        // Update in original findings array
+        const originalIndex = findings.findIndex((f) => f.description === updatedFinding.description);
+        if (originalIndex >= 0) {
+            findings[originalIndex] = updatedFinding;
+        }
+        if (updatedFinding.issueNumber) {
+            assessment.issuesCreated.push(updatedFinding.issueNumber);
+        }
+    }
+    // Save local report
+    await saveLocalReport(assessment);
+    // Update baseline
+    if (!dryRun) {
+        await updateBaseline(release.tagName);
+    }
+    return assessment;
+}
+/**
+ * Run assessment for latest release
+ */
+export async function assessLatest(options = {}) {
+    const release = await fetchRelease();
+    if (!release) {
+        console.error("Failed to fetch latest release");
+        return null;
+    }
+    return assessVersion(release.tagName, options);
+}
+/**
+ * Run batched assessment for multiple versions
+ */
+export async function assessSince(sinceVersion, options = {}) {
+    const { dryRun = false } = options;
+    const versions = await getReleasesSince(sinceVersion);
+    if (versions.length === 0) {
+        console.log(`No new versions since ${sinceVersion}`);
+        return null;
+    }
+    console.log(`Found ${versions.length} versions to assess: ${versions.join(", ")}`);
+    const assessments = [];
+    for (const version of versions) {
+        const assessment = await assessVersion(version, {
+            ...options,
+            force: true,
+        });
+        if (assessment) {
+            assessments.push(assessment);
+        }
+    }
+    if (assessments.length === 0) {
+        return null;
+    }
+    const batched = {
+        versions,
+        assessments,
+        sinceVersion,
+        toVersion: versions[versions.length - 1],
+    };
+    // Create summary issue
+    if (!dryRun) {
+        const summaryBody = generateBatchedSummaryReport(batched);
+        const summaryIssue = await createAssessmentIssue(`Upstream: Claude Code Assessment (${sinceVersion} → ${batched.toVersion})`, summaryBody, dryRun);
+        batched.summaryIssueNumber = summaryIssue;
+    }
+    return batched;
+}
+/**
+ * Main entry point for upstream assessment
+ */
+export async function runUpstream(options = {}) {
+    const { version, since } = options;
+    if (since) {
+        return assessSince(since, options);
+    }
+    if (version) {
+        return assessVersion(version, options);
+    }
+    return assessLatest(options);
+}
+/**
+ * Get default baseline when none exists
+ */
+function getDefaultBaseline() {
+    return {
+        lastAssessedVersion: null,
+        schemaVersion: "1.0.0",
+        tools: {
+            core: [
+                "Task",
+                "Bash",
+                "Read",
+                "Write",
+                "Edit",
+                "Glob",
+                "Grep",
+                "TodoWrite",
+            ],
+            optional: ["WebFetch", "WebSearch", "NotebookEdit", "AskUserQuestion"],
+        },
+        hooks: {
+            used: ["PreToolUse"],
+            files: ["src/hooks/pre-tool-hook.ts"],
+        },
+        mcpServers: {
+            required: [],
+            optional: ["chrome-devtools", "context7", "sequential-thinking"],
+        },
+        permissions: {
+            patterns: ["Bash(*)", "Task(*)", "Edit(*)"],
+            files: [".claude/settings.json"],
+        },
+        keywords: [
+            "Task",
+            "Bash",
+            "hook",
+            "PreToolUse",
+            "PostToolUse",
+            "MCP",
+            "permission",
+            "allow",
+            "deny",
+            "tool",
+            "background",
+            "parallel",
+            "agent",
+            "subagent",
+        ],
+        dependencyMap: {
+            permission: [".claude/settings.json"],
+            hook: ["src/hooks/pre-tool-hook.ts"],
+            Task: [".claude/skills/**/*.md"],
+            MCP: [".claude/settings.json"],
+        },
+    };
+}
+/**
+ * Ensure directory exists
+ */
+async function ensureDir(dir) {
+    try {
+        await mkdir(dir, { recursive: true });
+    }
+    catch {
+        // Directory may already exist
+    }
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Upstream Assessment Module
+ *
+ * Monitors Claude Code releases and assesses compatibility with sequant.
+ * Auto-creates GitHub issues for feature opportunities and breaking changes.
+ */
+export { runUpstream, assessVersion, assessLatest, assessSince, fetchRelease, listReleases, getReleasesSince, loadBaseline, saveBaseline, updateBaseline, isAlreadyAssessed, saveLocalReport, validateVersion, checkGhCliAvailable, } from "./assessment.js";
+export { extractChanges, matchKeywords, matchPatterns, categorizeChange, determineImpact, getImpactFiles, generateTitle, analyzeChange, analyzeRelease, getActionableFindings, DEFAULT_PATTERNS, } from "./relevance.js";
+export { calculateSummary, generateAssessmentReport, generateFindingIssue, generateBatchedSummaryReport, generateLocalReport, } from "./report.js";
+export { checkForDuplicate, createIssue, addIssueComment, createOrLinkFinding, createAssessmentIssue, extractSearchTerms, isSimilarTitle, } from "./issues.js";
+export type { FindingCategory, ImpactLevel, Finding, AssessmentSummary, UpstreamAssessment, ReleaseData, ToolsConfig, HooksConfig, McpServersConfig, PermissionsConfig, Baseline, DetectionPatterns, AssessmentOptions, DuplicateCheckResult, IssueParams, IssueResult, BatchedAssessment, } from "./types.js";

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

@@ -0,0 +1,14 @@
+/**
+ * Upstream Assessment Module
+ *
+ * Monitors Claude Code releases and assesses compatibility with sequant.
+ * Auto-creates GitHub issues for feature opportunities and breaking changes.
+ */
+// Main exports
+export { runUpstream, assessVersion, assessLatest, assessSince, fetchRelease, listReleases, getReleasesSince, loadBaseline, saveBaseline, updateBaseline, isAlreadyAssessed, saveLocalReport, validateVersion, checkGhCliAvailable, } from "./assessment.js";
+// Relevance detection
+export { extractChanges, matchKeywords, matchPatterns, categorizeChange, determineImpact, getImpactFiles, generateTitle, analyzeChange, analyzeRelease, getActionableFindings, DEFAULT_PATTERNS, } from "./relevance.js";
+// Report generation
+export { calculateSummary, generateAssessmentReport, generateFindingIssue, generateBatchedSummaryReport, generateLocalReport, } from "./report.js";
+// Issue management
+export { checkForDuplicate, createIssue, addIssueComment, createOrLinkFinding, createAssessmentIssue, extractSearchTerms, isSimilarTitle, } from "./issues.js";

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

@@ -0,0 +1,38 @@
+/**
+ * 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 type { DuplicateCheckResult, Finding, IssueParams, IssueResult } from "./types.js";
+/**
+ * Check if a similar upstream issue already exists
+ */
+export declare function checkForDuplicate(title: string, owner?: string, repo?: string): Promise<DuplicateCheckResult>;
+/**
+ * Extract search terms from a title
+ * Removes common words and version info
+ */
+export declare function extractSearchTerms(title: string): string;
+/**
+ * Check if two titles are similar enough to be duplicates
+ */
+export declare function isSimilarTitle(title1: string, title2: string): boolean;
+/**
+ * Create a GitHub issue using a temporary file for the body
+ * This avoids any shell escaping issues with complex markdown content
+ */
+export declare function createIssue(params: IssueParams, owner?: string, repo?: string): Promise<IssueResult>;
+/**
+ * Add a comment to an existing issue
+ */
+export declare function addIssueComment(issueNumber: number, comment: string, owner?: string, repo?: string): Promise<void>;
+/**
+ * Create or link an issue for a finding
+ */
+export declare function createOrLinkFinding(finding: Finding, version: string, assessmentIssueNumber: number | undefined, dryRun?: boolean, owner?: string, repo?: string): Promise<Finding>;
+/**
+ * Create the assessment summary issue
+ */
+export declare function createAssessmentIssue(title: string, body: string, dryRun?: boolean, owner?: string, repo?: string): Promise<number | undefined>;