@soleri/core 9.0.4 → 9.3.0

package/src/planning/gap-patterns.test.ts

@@ -0,0 +1,394 @@
+/**
+ * Tests for gap-patterns.ts — helpers, constants, and passes 1-4.
+ */
+
+import { describe, it, expect } from 'vitest';
+import type { Plan } from './planner.js';
+import {
+  gap,
+  taskText,
+  decisionText,
+  decisionsText,
+  containsAny,
+  analyzeStructure,
+  analyzeCompleteness,
+  analyzeFeasibility,
+  analyzeRisk,
+  METRIC_PATTERNS,
+  EXCLUSION_KEYWORDS,
+  OVERLY_BROAD_PATTERNS,
+  DEPENDENCY_KEYWORDS,
+  BREAKING_CHANGE_KEYWORDS,
+  MITIGATION_KEYWORDS,
+  VERIFICATION_KEYWORDS,
+} from './gap-patterns.js';
+
+function makePlan(overrides: Partial<Plan> = {}): Plan {
+  return {
+    id: 'plan-test',
+    objective: 'Implement user authentication with JWT tokens and session management',
+    scope: 'Auth module, middleware, and user service. Does not include OAuth providers.',
+    status: 'draft',
+    decisions: [
+      {
+        decision: 'Use JWT for stateless auth',
+        rationale: 'Because it scales horizontally without shared session store',
+      },
+    ],
+    tasks: [
+      {
+        id: 'task-1',
+        title: 'Add JWT signing',
+        description: 'Implement JWT sign/verify using built-in crypto module',
+        status: 'pending',
+        updatedAt: Date.now(),
+      },
+      {
+        id: 'task-2',
+        title: 'Add auth middleware',
+        description: 'Create Express middleware that validates JWT from Authorization header',
+        status: 'pending',
+        updatedAt: Date.now(),
+      },
+      {
+        id: 'task-3',
+        title: 'Add login endpoint',
+        description: 'POST /auth/login returns JWT after verifying credentials',
+        status: 'pending',
+        updatedAt: Date.now(),
+      },
+      {
+        id: 'task-4',
+        title: 'Add test coverage',
+        description: 'Test JWT signing, middleware rejection, and login flow end-to-end',
+        status: 'pending',
+        updatedAt: Date.now(),
+      },
+    ],
+    checks: [],
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+    ...overrides,
+  };
+}
+
+describe('Helper functions', () => {
+  describe('gap()', () => {
+    it('creates a PlanGap with auto-generated id', () => {
+      const result = gap('critical', 'structure', 'desc', 'rec');
+      expect(result.id).toMatch(/^gap_/);
+      expect(result.severity).toBe('critical');
+      expect(result.category).toBe('structure');
+      expect(result.description).toBe('desc');
+      expect(result.recommendation).toBe('rec');
+    });
+
+    it('includes location when provided', () => {
+      const result = gap('minor', 'clarity', 'd', 'r', 'objective');
+      expect(result.location).toBe('objective');
+    });
+
+    it('excludes location when undefined', () => {
+      const result = gap('minor', 'clarity', 'd', 'r');
+      expect(result).not.toHaveProperty('location');
+    });
+
+    it('includes _trigger when provided', () => {
+      const result = gap('minor', 'clarity', 'd', 'r', undefined, 'test_trigger');
+      expect(result._trigger).toBe('test_trigger');
+    });
+
+    it('excludes _trigger when undefined', () => {
+      const result = gap('minor', 'clarity', 'd', 'r');
+      expect(result).not.toHaveProperty('_trigger');
+    });
+  });
+
+  describe('taskText()', () => {
+    it('combines task titles and descriptions', () => {
+      const plan = makePlan();
+      const text = taskText(plan);
+      expect(text).toContain('Add JWT signing');
+      expect(text).toContain('Implement JWT sign/verify');
+    });
+
+    it('returns empty string for plan with no tasks', () => {
+      const plan = makePlan({ tasks: [] });
+      expect(taskText(plan)).toBe('');
+    });
+  });
+
+  describe('decisionText()', () => {
+    it('extracts text from string decision', () => {
+      expect(decisionText('Use JWT')).toBe('Use JWT');
+    });
+
+    it('extracts text from structured decision', () => {
+      const result = decisionText({ decision: 'Use JWT', rationale: 'scales well' });
+      expect(result).toBe('Use JWT scales well');
+    });
+  });
+
+  describe('decisionsText()', () => {
+    it('combines all decisions', () => {
+      const plan = makePlan();
+      const text = decisionsText(plan);
+      expect(text).toContain('Use JWT for stateless auth');
+      expect(text).toContain('scales horizontally');
+    });
+  });
+
+  describe('containsAny()', () => {
+    it('returns true when text contains a pattern', () => {
+      expect(containsAny('rewrite everything from scratch', ['from scratch'])).toBe(true);
+    });
+
+    it('is case-insensitive', () => {
+      expect(containsAny('FROM SCRATCH', ['from scratch'])).toBe(true);
+    });
+
+    it('returns false when no patterns match', () => {
+      expect(containsAny('simple change', ['everything', 'rewrite'])).toBe(false);
+    });
+
+    it('returns false for empty text', () => {
+      expect(containsAny('', ['test'])).toBe(false);
+    });
+
+    it('returns false for empty patterns', () => {
+      expect(containsAny('hello world', [])).toBe(false);
+    });
+  });
+});
+
+describe('Pattern constants', () => {
+  it('METRIC_PATTERNS matches numbers', () => {
+    expect(METRIC_PATTERNS.some((p) => p.test('reduce latency by 50%'))).toBe(true);
+  });
+
+  it('EXCLUSION_KEYWORDS includes common exclusion words', () => {
+    expect(EXCLUSION_KEYWORDS).toContain('exclude');
+    expect(EXCLUSION_KEYWORDS).toContain('not');
+  });
+
+  it('OVERLY_BROAD_PATTERNS includes dangerous scope terms', () => {
+    expect(OVERLY_BROAD_PATTERNS).toContain('complete rewrite');
+  });
+
+  it('DEPENDENCY_KEYWORDS includes ordering terms', () => {
+    expect(DEPENDENCY_KEYWORDS).toContain('depends');
+    expect(DEPENDENCY_KEYWORDS).toContain('prerequisite');
+  });
+
+  it('BREAKING_CHANGE_KEYWORDS includes migration terms', () => {
+    expect(BREAKING_CHANGE_KEYWORDS).toContain('breaking change');
+    expect(BREAKING_CHANGE_KEYWORDS).toContain('database migration');
+  });
+
+  it('MITIGATION_KEYWORDS includes safety terms', () => {
+    expect(MITIGATION_KEYWORDS).toContain('rollback');
+    expect(MITIGATION_KEYWORDS).toContain('feature flag');
+  });
+
+  it('VERIFICATION_KEYWORDS includes testing terms', () => {
+    expect(VERIFICATION_KEYWORDS).toContain('test');
+    expect(VERIFICATION_KEYWORDS).toContain('coverage');
+  });
+});
+
+describe('Pass 1: Structure', () => {
+  it('returns no gaps for a well-structured plan', () => {
+    const gaps = analyzeStructure(makePlan());
+    expect(gaps).toHaveLength(0);
+  });
+
+  it('returns critical gap for missing objective', () => {
+    const gaps = analyzeStructure(makePlan({ objective: '' }));
+    expect(gaps.some((g) => g._trigger === 'missing_or_short_objective')).toBe(true);
+    expect(gaps.find((g) => g._trigger === 'missing_or_short_objective')?.severity).toBe(
+      'critical',
+    );
+  });
+
+  it('returns critical gap for short objective', () => {
+    const gaps = analyzeStructure(makePlan({ objective: 'Fix' }));
+    expect(gaps.some((g) => g._trigger === 'missing_or_short_objective')).toBe(true);
+  });
+
+  it('returns critical gap for missing scope', () => {
+    const gaps = analyzeStructure(makePlan({ scope: '' }));
+    expect(gaps.some((g) => g._trigger === 'missing_or_short_scope')).toBe(true);
+  });
+
+  it('returns critical gap for no tasks', () => {
+    const gaps = analyzeStructure(makePlan({ tasks: [] }));
+    expect(gaps.some((g) => g._trigger === 'no_tasks')).toBe(true);
+  });
+
+  it('returns multiple gaps for completely empty plan', () => {
+    const gaps = analyzeStructure(makePlan({ objective: '', scope: '', tasks: [] }));
+    expect(gaps.length).toBe(3);
+    expect(gaps.every((g) => g.severity === 'critical')).toBe(true);
+  });
+});
+
+describe('Pass 2: Completeness', () => {
+  it('flags objective without measurable metrics', () => {
+    const plan = makePlan({ objective: 'Improve the login experience for all users globally' });
+    const gaps = analyzeCompleteness(plan);
+    expect(gaps.some((g) => g._trigger === 'no_metrics_in_objective')).toBe(true);
+  });
+
+  it('does not flag objective with numbers', () => {
+    const plan = makePlan({ objective: 'Reduce login latency to under 200ms for 95% of users' });
+    const gaps = analyzeCompleteness(plan);
+    expect(gaps.some((g) => g._trigger === 'no_metrics_in_objective')).toBe(false);
+  });
+
+  it('flags short decisions', () => {
+    const plan = makePlan({ decisions: [{ decision: 'JWT', rationale: '' }] });
+    const gaps = analyzeCompleteness(plan);
+    expect(gaps.some((g) => g._trigger === 'short_decision')).toBe(true);
+  });
+
+  it('flags scope without exclusions', () => {
+    const plan = makePlan({ scope: 'Auth module and middleware for the API layer' });
+    const gaps = analyzeCompleteness(plan);
+    expect(gaps.some((g) => g._trigger === 'no_exclusions_in_scope')).toBe(true);
+  });
+
+  it('does not flag scope with exclusion keywords', () => {
+    const plan = makePlan({ scope: 'Auth module. Does not include OAuth providers.' });
+    const gaps = analyzeCompleteness(plan);
+    expect(gaps.some((g) => g._trigger === 'no_exclusions_in_scope')).toBe(false);
+  });
+});
+
+describe('Pass 3: Feasibility', () => {
+  it('flags overly broad scope', () => {
+    const plan = makePlan({ scope: 'Complete rewrite of the entire codebase' });
+    const gaps = analyzeFeasibility(plan);
+    expect(gaps.some((g) => g._trigger === 'overly_broad_scope')).toBe(true);
+  });
+
+  it('does not flag reasonable scope', () => {
+    const plan = makePlan();
+    const gaps = analyzeFeasibility(plan);
+    expect(gaps.some((g) => g._trigger === 'overly_broad_scope')).toBe(false);
+  });
+
+  it('flags missing dependencies for 4+ tasks', () => {
+    const plan = makePlan();
+    // Default plan has 4 tasks, no dependency keywords
+    const gaps = analyzeFeasibility(plan);
+    expect(gaps.some((g) => g._trigger === 'no_dependency_awareness')).toBe(true);
+  });
+
+  it('does not flag when tasks have dependsOn', () => {
+    const plan = makePlan({
+      tasks: [
+        {
+          id: 't1',
+          title: 'Setup',
+          description: 'Setup project',
+          status: 'pending',
+          updatedAt: Date.now(),
+        },
+        {
+          id: 't2',
+          title: 'Build',
+          description: 'Build feature',
+          status: 'pending',
+          dependsOn: ['t1'],
+          updatedAt: Date.now(),
+        },
+        {
+          id: 't3',
+          title: 'Test',
+          description: 'Test feature',
+          status: 'pending',
+          dependsOn: ['t2'],
+          updatedAt: Date.now(),
+        },
+        {
+          id: 't4',
+          title: 'Deploy',
+          description: 'Deploy to prod',
+          status: 'pending',
+          dependsOn: ['t3'],
+          updatedAt: Date.now(),
+        },
+      ],
+    });
+    const gaps = analyzeFeasibility(plan);
+    expect(gaps.some((g) => g._trigger === 'no_dependency_awareness')).toBe(false);
+  });
+
+  it('does not flag when 3 or fewer tasks', () => {
+    const plan = makePlan({
+      tasks: [
+        {
+          id: 't1',
+          title: 'Task 1',
+          description: 'Do something',
+          status: 'pending',
+          updatedAt: Date.now(),
+        },
+        {
+          id: 't2',
+          title: 'Task 2',
+          description: 'Do another thing',
+          status: 'pending',
+          updatedAt: Date.now(),
+        },
+      ],
+    });
+    const gaps = analyzeFeasibility(plan);
+    expect(gaps.some((g) => g._trigger === 'no_dependency_awareness')).toBe(false);
+  });
+});
+
+describe('Pass 4: Risk', () => {
+  it('flags breaking changes without mitigation', () => {
+    const plan = makePlan({
+      objective: 'Database migration to new schema with breaking changes',
+      scope: 'All tables and models. Does not include frontend.',
+    });
+    const gaps = analyzeRisk(plan);
+    expect(gaps.some((g) => g._trigger === 'breaking_without_mitigation')).toBe(true);
+  });
+
+  it('does not flag when mitigation is mentioned', () => {
+    const plan = makePlan({
+      objective: 'Database migration with breaking changes and rollback plan',
+      scope: 'All tables. Not including frontend.',
+    });
+    const gaps = analyzeRisk(plan);
+    expect(gaps.some((g) => g._trigger === 'breaking_without_mitigation')).toBe(false);
+  });
+
+  it('flags missing verification', () => {
+    const plan = makePlan({
+      objective: 'Refactor the authentication module for better performance',
+      scope: 'Auth module only. Not including user service.',
+      decisions: [{ decision: 'Use new pattern', rationale: 'Because it is cleaner code' }],
+      tasks: [
+        {
+          id: 't1',
+          title: 'Refactor auth',
+          description: 'Change the auth flow implementation',
+          status: 'pending',
+          updatedAt: Date.now(),
+        },
+      ],
+    });
+    const gaps = analyzeRisk(plan);
+    expect(gaps.some((g) => g._trigger === 'no_verification_mentioned')).toBe(true);
+  });
+
+  it('does not flag when testing is mentioned', () => {
+    const plan = makePlan(); // default plan has "test" in task descriptions
+    const gaps = analyzeRisk(plan);
+    expect(gaps.some((g) => g._trigger === 'no_verification_mentioned')).toBe(false);
+  });
+});

package/src/planning/gap-patterns.ts

@@ -0,0 +1,317 @@
+/**
+ * Gap analysis helpers, pattern constants, and structural passes (1-4).
+ * Contains shared utilities and the first four analysis passes that check
+ * structure, completeness, feasibility, and risk.
+ */
+
+import type { Plan, PlanDecision } from './planner.js';
+import type { PlanGap, GapSeverity, GapCategory } from './gap-types.js';
+import {
+  generateGapId,
+  MIN_OBJECTIVE_LENGTH,
+  MIN_SCOPE_LENGTH,
+  MIN_DECISION_LENGTH,
+} from './gap-types.js';
+
+// ─── Helper Functions ────────────────────────────────────────────
+
+/** Create a PlanGap with auto-generated ID. */
+export function gap(
+  severity: GapSeverity,
+  category: GapCategory,
+  description: string,
+  recommendation: string,
+  location?: string,
+  trigger?: string,
+): PlanGap {
+  return {
+    id: generateGapId(),
+    severity,
+    category,
+    description,
+    recommendation,
+    ...(location ? { location } : {}),
+    ...(trigger ? { _trigger: trigger } : {}),
+  };
+}
+
+/** Combine all task descriptions + titles into a single text blob for analysis. */
+export function taskText(plan: Plan): string {
+  return plan.tasks.map((t) => `${t.title} ${t.description}`).join(' ');
+}
+
+/** Extract text from a decision (supports both string and structured format). */
+export function decisionText(d: string | PlanDecision): string {
+  return typeof d === 'string' ? d : `${d.decision} ${d.rationale}`;
+}
+
+/** Combine all decisions into a single text blob. */
+export function decisionsText(plan: Plan): string {
+  return plan.decisions.map(decisionText).join(' ');
+}
+
+/** Check if text contains any of the given patterns (case-insensitive). */
+export function containsAny(text: string, patterns: string[]): boolean {
+  const lower = text.toLowerCase();
+  return patterns.some((p) => lower.includes(p.toLowerCase()));
+}
+
+// ─── Pattern Constants (Passes 1-4) ─────────────────────────────
+
+export const METRIC_PATTERNS = [
+  /\d+/,
+  /percent/i,
+  /reduce/i,
+  /increase/i,
+  /measure/i,
+  /target/i,
+  /goal/i,
+  /kpi/i,
+  /metric/i,
+  /benchmark/i,
+];
+
+export const EXCLUSION_KEYWORDS = [
+  'not',
+  'exclude',
+  'outside',
+  'beyond',
+  'limit',
+  'except',
+  "won't",
+  'will not',
+];
+
+export const OVERLY_BROAD_PATTERNS = [
+  'everything',
+  'all systems',
+  'entire codebase',
+  'complete rewrite',
+  'from scratch',
+  'total overhaul',
+  'rewrite everything',
+];
+
+export const DEPENDENCY_KEYWORDS = [
+  'depends',
+  'dependency',
+  'prerequisite',
+  'requires',
+  'blocked',
+  'before',
+];
+
+export const BREAKING_CHANGE_KEYWORDS = [
+  'breaking change',
+  'breaking',
+  'migration',
+  'deprecate',
+  'remove api',
+  'remove endpoint',
+  'schema change',
+  'database migration',
+];
+
+export const MITIGATION_KEYWORDS = [
+  'rollback',
+  'backward compatible',
+  'backwards compatible',
+  'feature flag',
+  'gradual',
+  'phased',
+  'fallback',
+  'backup',
+  'canary',
+  'blue-green',
+];
+
+export const VERIFICATION_KEYWORDS = [
+  'test',
+  'verify',
+  'validate',
+  'check',
+  'assert',
+  'confirm',
+  'spec',
+  'coverage',
+];
+
+// ─── Pass 1: Structure ───────────────────────────────────────────
+
+export function analyzeStructure(plan: Plan): PlanGap[] {
+  const gaps: PlanGap[] = [];
+
+  if (!plan.objective || plan.objective.trim().length < MIN_OBJECTIVE_LENGTH) {
+    gaps.push(
+      gap(
+        'critical',
+        'structure',
+        plan.objective
+          ? `Objective too short (${plan.objective.trim().length} chars, need ${MIN_OBJECTIVE_LENGTH}+).`
+          : 'Plan has no objective.',
+        'Add a clear objective describing what this plan achieves.',
+        'objective',
+        'missing_or_short_objective',
+      ),
+    );
+  }
+
+  if (!plan.scope || plan.scope.trim().length < MIN_SCOPE_LENGTH) {
+    gaps.push(
+      gap(
+        'critical',
+        'structure',
+        plan.scope
+          ? `Scope too short (${plan.scope.trim().length} chars, need ${MIN_SCOPE_LENGTH}+).`
+          : 'Plan has no scope defined.',
+        'Define the scope — what is included and excluded.',
+        'scope',
+        'missing_or_short_scope',
+      ),
+    );
+  }
+
+  if (plan.tasks.length === 0) {
+    gaps.push(
+      gap(
+        'critical',
+        'structure',
+        'Plan has no tasks.',
+        'Add at least one task to make the plan actionable.',
+        'tasks',
+        'no_tasks',
+      ),
+    );
+  }
+
+  return gaps;
+}
+
+// ─── Pass 2: Completeness ────────────────────────────────────────
+
+export function analyzeCompleteness(plan: Plan): PlanGap[] {
+  const gaps: PlanGap[] = [];
+
+  if (plan.objective && !METRIC_PATTERNS.some((p) => p.test(plan.objective))) {
+    gaps.push(
+      gap(
+        'minor',
+        'completeness',
+        'Objective has no measurable targets or metrics.',
+        'Include quantifiable success criteria (numbers, percentages, concrete outcomes).',
+        'objective',
+        'no_metrics_in_objective',
+      ),
+    );
+  }
+
+  if (plan.decisions.length > 0) {
+    for (let i = 0; i < plan.decisions.length; i++) {
+      const d = plan.decisions[i];
+      const text = decisionText(d);
+      if (text.trim().length < MIN_DECISION_LENGTH) {
+        gaps.push(
+          gap(
+            'major',
+            'completeness',
+            `Decision ${i + 1} is too short (${text.trim().length} chars) — lacks rationale.`,
+            'Expand each decision to include the reasoning (why this choice over alternatives).',
+            `decisions[${i}]`,
+            'short_decision',
+          ),
+        );
+      }
+    }
+  }
+
+  if (plan.scope && !containsAny(plan.scope, EXCLUSION_KEYWORDS)) {
+    gaps.push(
+      gap(
+        'minor',
+        'completeness',
+        'Scope does not mention what is excluded.',
+        'Add explicit exclusions to prevent scope creep (e.g., "does NOT include…").',
+        'scope',
+        'no_exclusions_in_scope',
+      ),
+    );
+  }
+
+  return gaps;
+}
+
+// ─── Pass 3: Feasibility ─────────────────────────────────────────
+
+export function analyzeFeasibility(plan: Plan): PlanGap[] {
+  const gaps: PlanGap[] = [];
+  const scopeAndTasks = `${plan.scope} ${taskText(plan)}`;
+
+  if (containsAny(scopeAndTasks, OVERLY_BROAD_PATTERNS)) {
+    gaps.push(
+      gap(
+        'major',
+        'feasibility',
+        'Scope contains overly broad indicators — risk of unrealistic delivery.',
+        'Narrow the scope to a well-defined subset. Prefer incremental delivery over big-bang rewrites.',
+        'scope',
+        'overly_broad_scope',
+      ),
+    );
+  }
+
+  if (plan.tasks.length > 3 && !containsAny(scopeAndTasks, DEPENDENCY_KEYWORDS)) {
+    const hasDeps = plan.tasks.some((t) => t.dependsOn && t.dependsOn.length > 0);
+    if (!hasDeps) {
+      gaps.push(
+        gap(
+          'minor',
+          'feasibility',
+          `${plan.tasks.length} tasks with no dependency mentions — execution order unclear.`,
+          'Identify dependencies between tasks or add explicit ordering notes.',
+          'tasks',
+          'no_dependency_awareness',
+        ),
+      );
+    }
+  }
+
+  return gaps;
+}
+
+// ─── Pass 4: Risk ────────────────────────────────────────────────
+
+export function analyzeRisk(plan: Plan): PlanGap[] {
+  const gaps: PlanGap[] = [];
+  const allText = `${plan.objective} ${plan.scope} ${taskText(plan)} ${decisionsText(plan)}`;
+
+  if (
+    containsAny(allText, BREAKING_CHANGE_KEYWORDS) &&
+    !containsAny(allText, MITIGATION_KEYWORDS)
+  ) {
+    gaps.push(
+      gap(
+        'major',
+        'risk',
+        'Plan involves breaking changes but mentions no mitigation strategy.',
+        'Add a rollback plan, feature flags, or phased migration approach.',
+        undefined,
+        'breaking_without_mitigation',
+      ),
+    );
+  }
+
+  if (plan.tasks.length > 0 && !containsAny(allText, VERIFICATION_KEYWORDS)) {
+    gaps.push(
+      gap(
+        'minor',
+        'risk',
+        'No verification or testing mentioned in the plan.',
+        'Add at least one task or note about testing/validation.',
+        'tasks',
+        'no_verification_mentioned',
+      ),
+    );
+  }
+
+  return gaps;
+}