sequant 1.20.2 → 2.0.0

package/dist/src/lib/workflow/platforms/index.js

@@ -0,0 +1,25 @@
+/**
+ * Platform provider registry.
+ *
+ * Simple map-based registry — not a plugin system.
+ * New providers are registered by adding entries to PLATFORMS.
+ */
+import { GitHubProvider } from "./github.js";
+export { GitHubProvider } from "./github.js";
+const PLATFORMS = {
+    github: () => new GitHubProvider(),
+};
+/**
+ * Get a platform provider by name.
+ *
+ * @param name - Provider name (default: "github")
+ * @throws Error if provider name is unknown
+ */
+export function getPlatform(name = "github") {
+    const factory = PLATFORMS[name];
+    if (!factory) {
+        const available = Object.keys(PLATFORMS).join(", ");
+        throw new Error(`Unknown platform provider "${name}". Available providers: ${available}`);
+    }
+    return factory();
+}

package/dist/src/lib/workflow/platforms/platform-provider.d.ts

@@ -0,0 +1,67 @@
+/**
+ * PlatformProvider interface — decouples workflow orchestration from
+ * platform operations (issue fetching, PR creation, comments, labels).
+ *
+ * GitHub is the default implementation; alternatives can be added by
+ * implementing this interface without touching orchestration logic.
+ */
+/**
+ * Normalized issue representation.
+ */
+export interface Issue {
+    id: string;
+    number: number;
+    title: string;
+    body: string;
+    labels: string[];
+    state: "open" | "closed";
+}
+/**
+ * Options for creating a pull request.
+ */
+export interface CreatePROptions {
+    title: string;
+    body: string;
+    head: string;
+    base: string;
+}
+/**
+ * Information about a created pull request.
+ */
+export interface PRInfo {
+    number: number;
+    url: string;
+}
+/**
+ * Status of a pull request.
+ */
+export interface PRStatus {
+    state: "open" | "closed" | "merged";
+}
+/**
+ * A comment on an issue or pull request.
+ */
+export interface Comment {
+    body: string;
+    createdAt: string;
+}
+/**
+ * Interface that all platform backends must implement.
+ */
+export interface PlatformProvider {
+    /** Platform name for logging/display */
+    name: string;
+    /** Issue operations */
+    fetchIssue(id: string): Promise<Issue>;
+    postComment(issueId: string, body: string): Promise<void>;
+    addLabel(issueId: string, label: string): Promise<void>;
+    removeLabel(issueId: string, label: string): Promise<void>;
+    /** PR operations */
+    createPR(opts: CreatePROptions): Promise<PRInfo>;
+    getPRStatus(prId: string): Promise<PRStatus>;
+    postPRComment(prId: string, body: string): Promise<void>;
+    /** Auth and health */
+    checkAuth(): Promise<boolean>;
+    /** Phase marker operations */
+    getIssueComments(issueId: string): Promise<Comment[]>;
+}

package/dist/src/lib/workflow/platforms/platform-provider.js

@@ -0,0 +1,8 @@
+/**
+ * PlatformProvider interface — decouples workflow orchestration from
+ * platform operations (issue fetching, PR creation, comments, labels).
+ *
+ * GitHub is the default implementation; alternatives can be added by
+ * implementing this interface without touching orchestration logic.
+ */
+export {};

package/dist/src/lib/workflow/pr-status.d.ts

@@ -16,10 +16,8 @@
  * const isMerged = isBranchMergedIntoMain('feature/123-some-feature');
  * ```
  */
-/**
- * PR merge status from GitHub
- */
-export type PRMergeStatus = "MERGED" | "CLOSED" | "OPEN" | null;
+import type { PRMergeStatus } from "./platforms/github.js";
+export type { PRMergeStatus };
 /**
  * Check the merge status of a PR using the gh CLI
  *

package/dist/src/lib/workflow/pr-status.js

@@ -17,6 +17,7 @@
  * ```
  */
 import { spawnSync } from "child_process";
+import { GitHubProvider } from "./platforms/github.js";
 /**
  * Check the merge status of a PR using the gh CLI
  *
@@ -24,22 +25,8 @@ import { spawnSync } from "child_process";
  * @returns "MERGED" | "CLOSED" | "OPEN" | null (null if PR not found or gh unavailable)
  */
 export function checkPRMergeStatus(prNumber) {
-    try {
-        const result = spawnSync("gh", ["pr", "view", String(prNumber), "--json", "state", "-q", ".state"], { stdio: "pipe", timeout: 10000 });
-        if (result.status === 0 && result.stdout) {
-            const state = result.stdout.toString().trim().toUpperCase();
-            if (state === "MERGED")
-                return "MERGED";
-            if (state === "CLOSED")
-                return "CLOSED";
-            if (state === "OPEN")
-                return "OPEN";
-        }
-    }
-    catch {
-        // gh not available or error - return null
-    }
-    return null;
+    const github = new GitHubProvider();
+    return github.getPRMergeStatusSync(prNumber);
 }
 /**
  * Check if a branch has been merged into a base branch using git

package/dist/src/lib/workflow/qa-cache.d.ts

@@ -56,6 +56,28 @@ export declare const CachedCheckResultSchema: z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type CachedCheckResult = z.infer<typeof CachedCheckResultSchema>;
+/**
+ * Schema for QA run context - stores metadata from the last QA run
+ * for incremental re-run optimization
+ */
+export declare const QARunContextSchema: z.ZodObject<{
+    lastQACommitSHA: z.ZodString;
+    lastQADiffHash: z.ZodString;
+    acStatuses: z.ZodRecord<z.ZodString, z.ZodEnum<{
+        pending: "pending";
+        blocked: "blocked";
+        met: "met";
+        not_met: "not_met";
+        partially_met: "partially_met";
+    }>>;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+export type QARunContext = z.infer<typeof QARunContextSchema>;
+/**
+ * Checks that are always re-run on every QA invocation, regardless of cache.
+ * These are either cheap or can regress independently of code changes.
+ */
+export declare const ALWAYS_RERUN_CHECKS: readonly string[];
 /**
  * Schema for the complete cache file
  */
@@ -84,6 +106,18 @@ export declare const QACacheSchema: z.ZodObject<{
             details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strip>;
     }, z.core.$strip>>;
+    runContext: z.ZodOptional<z.ZodObject<{
+        lastQACommitSHA: z.ZodString;
+        lastQADiffHash: z.ZodString;
+        acStatuses: z.ZodRecord<z.ZodString, z.ZodEnum<{
+            pending: "pending";
+            blocked: "blocked";
+            met: "met";
+            not_met: "not_met";
+            partially_met: "partially_met";
+        }>>;
+        timestamp: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type QACacheState = z.infer<typeof QACacheSchema>;
 /**
@@ -171,6 +205,30 @@ export declare class QACache {
      * Clear all cached results
      */
     clearAll(): Promise<void>;
+    /**
+     * Get the QA run context from the last QA run
+     */
+    getRunContext(): Promise<QARunContext | undefined>;
+    /**
+     * Set the QA run context after a QA run completes
+     */
+    setRunContext(context: QARunContext): Promise<void>;
+    /**
+     * Compute hash of git diff between a specific commit and HEAD.
+     * Used for incremental QA to detect changes since last QA run.
+     *
+     * @param sinceCommit - The commit SHA to diff from
+     * @returns Hash of the diff, or null if the commit is invalid/missing
+     */
+    computeIncrementalDiffHash(sinceCommit: string): string | null;
+    /**
+     * Get files changed since a specific commit.
+     * Used for incremental QA to determine which checks need re-running.
+     *
+     * @param sinceCommit - The commit SHA to diff from
+     * @returns Array of changed file paths, or null if the commit is invalid
+     */
+    getChangedFilesSince(sinceCommit: string): string[] | null;
     /**
      * Get cache status for all check types
      */

package/dist/src/lib/workflow/qa-cache.js

@@ -67,6 +67,25 @@ export const CachedCheckResultSchema = z.object({
         details: z.record(z.string(), z.unknown()).optional(),
     }),
 });
+/**
+ * Schema for QA run context - stores metadata from the last QA run
+ * for incremental re-run optimization
+ */
+export const QARunContextSchema = z.object({
+    /** Git HEAD SHA at the time of QA completion */
+    lastQACommitSHA: z.string(),
+    /** Diff hash (main...HEAD) at the time of QA */
+    lastQADiffHash: z.string(),
+    /** Map of AC ID → status from the last QA run */
+    acStatuses: z.record(z.string(), z.enum(["met", "not_met", "partially_met", "pending", "blocked"])),
+    /** ISO 8601 timestamp of last QA completion */
+    timestamp: z.string().datetime(),
+});
+/**
+ * Checks that are always re-run on every QA invocation, regardless of cache.
+ * These are either cheap or can regress independently of code changes.
+ */
+export const ALWAYS_RERUN_CHECKS = ["build"];
 /**
  * Schema for the complete cache file
  */
@@ -77,6 +96,8 @@ export const QACacheSchema = z.object({
     lastUpdated: z.string().datetime(),
     /** Cached check results keyed by check type */
     checks: z.record(z.string(), CachedCheckResultSchema),
+    /** QA run context for incremental re-runs (optional for backward compat) */
+    runContext: QARunContextSchema.optional(),
 });
 /**
  * Default TTL: 1 hour
@@ -382,6 +403,73 @@ export class QACache {
         await this.saveState(emptyState);
         this.log("Cleared all cache");
     }
+    /**
+     * Get the QA run context from the last QA run
+     */
+    async getRunContext() {
+        const state = await this.getState();
+        return state.runContext;
+    }
+    /**
+     * Set the QA run context after a QA run completes
+     */
+    async setRunContext(context) {
+        const state = await this.getState();
+        state.runContext = context;
+        await this.saveState(state);
+        this.log("Saved QA run context");
+    }
+    /**
+     * Compute hash of git diff between a specific commit and HEAD.
+     * Used for incremental QA to detect changes since last QA run.
+     *
+     * @param sinceCommit - The commit SHA to diff from
+     * @returns Hash of the diff, or null if the commit is invalid/missing
+     */
+    computeIncrementalDiffHash(sinceCommit) {
+        if (!/^[a-f0-9]{4,40}$/.test(sinceCommit)) {
+            this.log(`Invalid commit SHA format: ${sinceCommit}`);
+            return null;
+        }
+        try {
+            const diff = execSync(`git diff ${sinceCommit}...HEAD`, {
+                encoding: "utf-8",
+                maxBuffer: 10 * 1024 * 1024,
+            });
+            return crypto
+                .createHash("sha256")
+                .update(diff)
+                .digest("hex")
+                .slice(0, 16);
+        }
+        catch {
+            this.log(`Failed to compute incremental diff from ${sinceCommit}`);
+            return null;
+        }
+    }
+    /**
+     * Get files changed since a specific commit.
+     * Used for incremental QA to determine which checks need re-running.
+     *
+     * @param sinceCommit - The commit SHA to diff from
+     * @returns Array of changed file paths, or null if the commit is invalid
+     */
+    getChangedFilesSince(sinceCommit) {
+        if (!/^[a-f0-9]{4,40}$/.test(sinceCommit)) {
+            this.log(`Invalid commit SHA format: ${sinceCommit}`);
+            return null;
+        }
+        try {
+            const output = execSync(`git diff ${sinceCommit}...HEAD --name-only`, {
+                encoding: "utf-8",
+            });
+            return output.trim().split("\n").filter(Boolean);
+        }
+        catch {
+            this.log(`Failed to get changed files since ${sinceCommit}`);
+            return null;
+        }
+    }
     /**
      * Get cache status for all check types
      */

package/dist/src/lib/workflow/reconcile.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Reconciliation engine for sequant status
+ *
+ * Reconciles local state.json with GitHub API and filesystem
+ * to provide accurate, up-to-date status information.
+ *
+ * @module reconcile
+ */
+import { StateManager } from "./state-manager.js";
+import { type BatchIssueInfo, type BatchPRInfo } from "./platforms/github.js";
+import type { IssueState } from "./state-schema.js";
+/**
+ * Classification of detected drift between local state and reality.
+ */
+export type DriftType = "unambiguous" | "ambiguous" | "none";
+/**
+ * A single drift action detected during reconciliation.
+ */
+export interface DriftAction {
+    issueNumber: number;
+    type: DriftType;
+    action: string;
+    description: string;
+}
+/**
+ * Result of a reconciliation operation.
+ */
+export interface ReconcileResult {
+    success: boolean;
+    /** Actions taken (unambiguous drift auto-healed). */
+    healed: DriftAction[];
+    /** Ambiguous drift flagged to user. */
+    warnings: DriftAction[];
+    /** ISO timestamp of when reconciliation completed. */
+    lastSynced: string;
+    /** Whether GitHub was reachable. */
+    githubReachable: boolean;
+    /** Error message if reconciliation failed entirely. */
+    error?: string;
+}
+/**
+ * Options for reconciliation.
+ */
+export interface ReconcileOptions {
+    /** Skip GitHub API queries (offline mode). */
+    offline?: boolean;
+    /** State manager to use. */
+    stateManager?: StateManager;
+}
+/**
+ * Classify drift for a single issue based on GitHub and filesystem state.
+ */
+export declare function classifyDrift(issue: IssueState, githubIssue?: BatchIssueInfo, githubPR?: BatchPRInfo, worktreeExists?: boolean): DriftAction | null;
+/**
+ * Get a next-action hint for an issue based on its current state.
+ */
+export declare function getNextActionHint(issue: IssueState): string;
+/**
+ * Format a relative time string from an ISO timestamp.
+ */
+export declare function formatRelativeTime(isoTimestamp: string | undefined): string;
+/**
+ * Reconcile local workflow state with GitHub and filesystem.
+ *
+ * This is the main entry point for reconciliation. Called by:
+ * - `sequant status` (CLI)
+ * - `sequant_status` (MCP tool)
+ */
+export declare function reconcileState(options?: ReconcileOptions): Promise<ReconcileResult>;