sequant 1.11.0 → 1.13.0

package/dist/src/lib/ac-linter.js

@@ -0,0 +1,304 @@
+/**
+ * Acceptance Criteria Linter
+ *
+ * Static analysis of acceptance criteria to flag vague, untestable,
+ * or incomplete requirements before implementation begins.
+ *
+ * @example
+ * ```typescript
+ * import { lintAcceptanceCriteria } from './ac-linter';
+ * import { parseAcceptanceCriteria } from './ac-parser';
+ *
+ * const criteria = parseAcceptanceCriteria(issueBody);
+ * const lintResults = lintAcceptanceCriteria(criteria);
+ *
+ * console.log(formatACLintResults(lintResults));
+ * ```
+ */
+/**
+ * Default lint patterns organized by issue type
+ *
+ * Patterns are checked in order, with longer/more specific patterns first
+ */
+const DEFAULT_LINT_PATTERNS = [
+    // Vague patterns
+    {
+        regex: /\bshould work\b/i,
+        type: "vague",
+        problem: 'Vague: "should work" is not specific',
+        suggestion: "Specify the expected behavior and success criteria",
+    },
+    {
+        regex: /\bwork(?:s|ing)? (?:properly|correctly|well|nicely)\b/i,
+        type: "vague",
+        problem: "Vague: adverb does not define expected behavior",
+        suggestion: "Define specific, measurable outcomes",
+    },
+    {
+        regex: /\bproperly\b/i,
+        type: "vague",
+        problem: 'Vague: "properly" is subjective',
+        suggestion: "Specify what correct behavior looks like",
+    },
+    {
+        regex: /\bcorrectly\b/i,
+        type: "vague",
+        problem: 'Vague: "correctly" is subjective',
+        suggestion: "Define the expected output or behavior",
+    },
+    {
+        regex: /\bnicely\b/i,
+        type: "vague",
+        problem: 'Vague: "nicely" is subjective',
+        suggestion: "Specify concrete UX requirements",
+    },
+    {
+        regex: /\bgood\b(?!\s+(?:practice|pattern|reason))/i,
+        type: "vague",
+        problem: 'Vague: "good" is subjective without context',
+        suggestion: "Define measurable quality criteria",
+    },
+    {
+        regex: /\bas expected\b/i,
+        type: "vague",
+        problem: 'Vague: "as expected" requires explicit expectations',
+        suggestion: "Define what the expected behavior is",
+    },
+    {
+        regex: /\bshould be fine\b/i,
+        type: "vague",
+        problem: 'Vague: "should be fine" is not a testable criterion',
+        suggestion: "Specify the acceptance threshold",
+    },
+    // Unmeasurable patterns (performance-related)
+    {
+        regex: /\bfast(?:er)?\b(?!\s+forward)/i,
+        type: "unmeasurable",
+        problem: 'Unmeasurable: "fast" has no threshold',
+        suggestion: "Add latency threshold (e.g., <2 seconds, <100ms)",
+    },
+    {
+        regex: /\bslow(?:er)?\b/i,
+        type: "unmeasurable",
+        problem: 'Unmeasurable: "slow" has no threshold',
+        suggestion: "Define specific timing or threshold",
+    },
+    {
+        regex: /\bperformant\b/i,
+        type: "unmeasurable",
+        problem: 'Unmeasurable: "performant" has no threshold',
+        suggestion: "Add specific performance metrics (latency, throughput)",
+    },
+    {
+        regex: /\befficient(?:ly)?\b/i,
+        type: "unmeasurable",
+        problem: 'Unmeasurable: "efficient" has no threshold',
+        suggestion: "Define resource usage limits or benchmarks",
+    },
+    {
+        regex: /\bresponsive\b/i,
+        type: "unmeasurable",
+        problem: 'Unmeasurable: "responsive" has no threshold',
+        suggestion: "Add response time target (e.g., <100ms interaction, <3s load)",
+    },
+    {
+        regex: /\bquick(?:ly)?\b/i,
+        type: "unmeasurable",
+        problem: 'Unmeasurable: "quickly" has no threshold',
+        suggestion: "Specify time limit (e.g., completes in <5 seconds)",
+    },
+    {
+        regex: /\bscalable\b/i,
+        type: "unmeasurable",
+        problem: 'Unmeasurable: "scalable" needs concrete bounds',
+        suggestion: "Define load targets (e.g., handles 1000 concurrent users)",
+    },
+    // Incomplete patterns (error handling, edge cases)
+    {
+        regex: /\bhandle(?:s)? errors?\b/i,
+        type: "incomplete",
+        problem: "Incomplete: error types not specified",
+        suggestion: "List specific error types and expected responses (e.g., 400 for invalid input, 503 for service unavailable)",
+    },
+    {
+        regex: /\berror handling\b/i,
+        type: "incomplete",
+        problem: "Incomplete: error scenarios not specified",
+        suggestion: "Enumerate error conditions and recovery behaviors",
+    },
+    {
+        regex: /\bedge cases?\b/i,
+        type: "incomplete",
+        problem: "Incomplete: edge cases not enumerated",
+        suggestion: "List the specific edge cases to handle",
+    },
+    {
+        regex: /\bcorner cases?\b/i,
+        type: "incomplete",
+        problem: "Incomplete: corner cases not enumerated",
+        suggestion: "List the specific corner cases to handle",
+    },
+    {
+        regex: /\ball (?:cases|scenarios|situations)\b/i,
+        type: "incomplete",
+        problem: 'Incomplete: "all" cases cannot be verified',
+        suggestion: "Enumerate the specific cases to test",
+    },
+    {
+        regex: /\bappropriate(?:ly)?\b/i,
+        type: "incomplete",
+        problem: 'Incomplete: "appropriate" behavior not defined',
+        suggestion: "Specify what the appropriate response is",
+    },
+    // Open-ended patterns
+    {
+        regex: /\betc\.?\b/i,
+        type: "open_ended",
+        problem: 'Open-ended: "etc." leaves scope undefined',
+        suggestion: "Enumerate all items explicitly",
+    },
+    {
+        regex: /\band more\b/i,
+        type: "open_ended",
+        problem: 'Open-ended: "and more" leaves scope undefined',
+        suggestion: "List all items explicitly",
+    },
+    {
+        regex: /\bsuch as\b/i,
+        type: "open_ended",
+        problem: 'Open-ended: "such as" implies incomplete list',
+        suggestion: "Provide exhaustive list or define boundaries",
+    },
+    {
+        regex: /\bincluding but not limited to\b/i,
+        type: "open_ended",
+        problem: "Open-ended: scope is unbounded",
+        suggestion: "Define explicit boundaries or enumerate all items",
+    },
+    {
+        regex: /\bfor example\b/i,
+        type: "open_ended",
+        problem: 'Open-ended: "for example" implies other cases exist',
+        suggestion: "List all cases or define scope boundaries",
+    },
+    {
+        regex: /\bvarious\b/i,
+        type: "open_ended",
+        problem: 'Open-ended: "various" items not specified',
+        suggestion: "Enumerate the specific items",
+    },
+    {
+        regex: /\bother(?:s)?\b(?!\s+(?:than|hand|words|side))/i,
+        type: "open_ended",
+        problem: 'Open-ended: "other" items not specified',
+        suggestion: "List all items explicitly or define boundaries",
+    },
+];
+/**
+ * Lint a single acceptance criterion against all patterns
+ *
+ * @param ac - The acceptance criterion to lint
+ * @param patterns - Optional custom patterns (defaults to DEFAULT_LINT_PATTERNS)
+ * @returns Lint result with any issues found
+ */
+export function lintAcceptanceCriterion(ac, patterns = DEFAULT_LINT_PATTERNS) {
+    const issues = [];
+    const description = ac.description;
+    for (const pattern of patterns) {
+        const match = description.match(pattern.regex);
+        if (match) {
+            issues.push({
+                type: pattern.type,
+                matchedPattern: match[0],
+                problem: pattern.problem,
+                suggestion: pattern.suggestion,
+            });
+        }
+    }
+    return {
+        ac,
+        issues,
+        passed: issues.length === 0,
+    };
+}
+/**
+ * Lint all acceptance criteria
+ *
+ * @param criteria - Array of acceptance criteria to lint
+ * @param patterns - Optional custom patterns
+ * @returns Complete lint results with summary
+ */
+export function lintAcceptanceCriteria(criteria, patterns) {
+    const results = criteria.map((ac) => lintAcceptanceCriterion(ac, patterns));
+    const passed = results.filter((r) => r.passed).length;
+    const flagged = results.filter((r) => !r.passed).length;
+    return {
+        results,
+        summary: {
+            total: criteria.length,
+            passed,
+            flagged,
+        },
+        hasIssues: flagged > 0,
+    };
+}
+/**
+ * Format lint results as markdown for the spec output
+ *
+ * @param results - Lint results to format
+ * @returns Markdown-formatted output string
+ */
+export function formatACLintResults(results) {
+    if (results.summary.total === 0) {
+        return "## AC Quality Check\n\nNo acceptance criteria found to lint.";
+    }
+    const lines = ["## AC Quality Check", ""];
+    // Add summary line
+    if (!results.hasIssues) {
+        lines.push(`✅ All ${results.summary.total} acceptance criteria are clear and testable.`);
+        lines.push("");
+        return lines.join("\n");
+    }
+    // Add issues
+    for (const result of results.results) {
+        if (!result.passed) {
+            lines.push(`⚠️ **${result.ac.id}:** "${result.ac.description}"`);
+            for (const issue of result.issues) {
+                lines.push(`   → ${issue.problem}`);
+                lines.push(`   → Suggest: ${issue.suggestion}`);
+            }
+            lines.push("");
+        }
+    }
+    // Add passed ACs summary
+    const passedIds = results.results.filter((r) => r.passed).map((r) => r.ac.id);
+    if (passedIds.length > 0) {
+        lines.push(`✅ ${passedIds.join(", ")}: Clear and testable`);
+        lines.push("");
+    }
+    // Add summary
+    lines.push(`**Summary:** ${results.summary.flagged}/${results.summary.total} AC items flagged for review`);
+    return lines.join("\n");
+}
+/**
+ * Get the default lint patterns
+ *
+ * @returns Copy of the default lint patterns
+ */
+export function getDefaultLintPatterns() {
+    return [...DEFAULT_LINT_PATTERNS];
+}
+/**
+ * Create custom lint patterns from a simplified configuration
+ *
+ * @param config - Array of pattern configurations
+ * @returns Array of LintPattern objects
+ */
+export function createLintPatterns(config) {
+    return config.map((c) => ({
+        regex: new RegExp(c.pattern, "i"),
+        type: c.type,
+        problem: c.problem,
+        suggestion: c.suggestion,
+    }));
+}

package/dist/src/lib/cli-ui.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Centralized CLI UI module for Sequant
+ *
+ * Provides consistent styling, spinners, boxes, tables, and branding
+ * with graceful fallbacks for non-TTY, CI, and legacy terminals.
+ */
+/**
+ * UI configuration options
+ */
+export interface UIConfig {
+    /** Disable all colors and styling */
+    noColor: boolean;
+    /** JSON output mode - suppress decorative output */
+    jsonMode: boolean;
+    /** Verbose mode - use text-only spinners to avoid overwriting output */
+    verbose: boolean;
+    /** Whether stdout is a TTY */
+    isTTY: boolean;
+    /** Running in CI environment */
+    isCI: boolean;
+    /** Minimal output mode */
+    minimal: boolean;
+}
+/**
+ * Configure UI settings
+ *
+ * Call this early in CLI startup to set global options.
+ */
+export declare function configureUI(options: Partial<UIConfig>): void;
+/**
+ * Get current UI configuration
+ */
+export declare function getUIConfig(): Readonly<UIConfig>;
+/**
+ * Standardized color palette for consistent styling
+ */
+export declare const colors: {
+    success: ((s: string) => string) | import("chalk").ChalkInstance;
+    error: import("chalk").ChalkInstance | ((s: string) => string);
+    warning: import("chalk").ChalkInstance | ((s: string) => string);
+    info: import("chalk").ChalkInstance | ((s: string) => string);
+    muted: import("chalk").ChalkInstance | ((s: string) => string);
+    header: import("chalk").ChalkInstance | ((s: string) => string);
+    label: import("chalk").ChalkInstance | ((s: string) => string);
+    value: import("chalk").ChalkInstance | ((s: string) => string);
+    accent: import("chalk").ChalkInstance | ((s: string) => string);
+    bold: import("chalk").ChalkInstance | ((s: string) => string);
+    pending: import("chalk").ChalkInstance | ((s: string) => string);
+    running: import("chalk").ChalkInstance | ((s: string) => string);
+    completed: import("chalk").ChalkInstance | ((s: string) => string);
+    failed: import("chalk").ChalkInstance | ((s: string) => string);
+};
+/**
+ * Get the ASCII logo with optional gradient
+ */
+export declare function logo(): string;
+/**
+ * Get the banner (logo + tagline)
+ */
+export declare function banner(): string;
+/**
+ * Spinner manager interface
+ */
+export interface SpinnerManager {
+    /** Start the spinner with optional new text */
+    start(text?: string): SpinnerManager;
+    /** Mark as succeeded with optional message */
+    succeed(text?: string): SpinnerManager;
+    /** Mark as failed with optional message */
+    fail(text?: string): SpinnerManager;
+    /** Mark as warning with optional message */
+    warn(text?: string): SpinnerManager;
+    /** Stop the spinner */
+    stop(): SpinnerManager;
+    /** Update the spinner text */
+    text: string;
+    /** Check if spinner is active */
+    isSpinning: boolean;
+}
+/**
+ * Create a spinner with automatic fallback
+ *
+ * Returns an animated spinner for TTY, text-only for non-TTY/verbose/CI.
+ */
+export declare function spinner(text: string): SpinnerManager;
+/**
+ * Box style presets
+ */
+export type BoxStyle = "success" | "error" | "warning" | "info" | "header" | "default";
+/**
+ * Create a boxed message
+ */
+export declare function box(content: string, style?: BoxStyle): string;
+/**
+ * Create a success box with title and message
+ */
+export declare function successBox(title: string, message: string): string;
+/**
+ * Create an error box with title and message
+ */
+export declare function errorBox(title: string, message: string): string;
+/**
+ * Create a warning box with title and message
+ */
+export declare function warningBox(title: string, message: string): string;
+/**
+ * Create a header box
+ */
+export declare function headerBox(title: string): string;
+/**
+ * Table column definition
+ */
+export interface TableColumn {
+    /** Column header text */
+    header: string;
+    /** Column width (optional) */
+    width?: number;
+    /** Text alignment */
+    align?: "left" | "center" | "right";
+}
+/**
+ * Table options
+ */
+export interface TableOptions {
+    /** Column definitions */
+    columns: TableColumn[];
+    /** Table style */
+    style?: "default" | "compact" | "borderless";
+}
+/**
+ * Create a formatted table
+ */
+export declare function table(rows: (string | number)[][], options: TableOptions): string;
+/**
+ * Create a simple key-value table
+ */
+export declare function keyValueTable(data: Record<string, string | number>): string;
+/**
+ * Status indicator types
+ */
+export type StatusType = "success" | "error" | "warning" | "pending" | "running";
+/**
+ * Get a status icon
+ */
+export declare function statusIcon(type: StatusType): string;
+/**
+ * Print a status message with icon
+ */
+export declare function printStatus(type: StatusType, message: string): void;
+/**
+ * Create a horizontal divider
+ */
+export declare function divider(width?: number): string;
+/**
+ * Create a section header
+ */
+export declare function sectionHeader(title: string): string;
+/**
+ * Phase status for progress display
+ */
+export interface PhaseStatus {
+    name: string;
+    status: "pending" | "running" | "success" | "failure" | "skipped";
+}
+/**
+ * Display phase progress as a visual indicator
+ */
+export declare function phaseProgress(phases: PhaseStatus[]): string;
+/**
+ * Create a progress bar
+ */
+export declare function progressBar(current: number, total: number, width?: number): string;
+/**
+ * Unified UI object for convenient access to all utilities
+ */
+export declare const ui: {
+    configure: typeof configureUI;
+    getConfig: typeof getUIConfig;
+    logo: typeof logo;
+    banner: typeof banner;
+    spinner: typeof spinner;
+    box: typeof box;
+    successBox: typeof successBox;
+    errorBox: typeof errorBox;
+    warningBox: typeof warningBox;
+    headerBox: typeof headerBox;
+    table: typeof table;
+    keyValueTable: typeof keyValueTable;
+    statusIcon: typeof statusIcon;
+    printStatus: typeof printStatus;
+    divider: typeof divider;
+    sectionHeader: typeof sectionHeader;
+    phaseProgress: typeof phaseProgress;
+    progressBar: typeof progressBar;
+};
+export default ui;