tlc-claude-code 2.1.0 → 2.2.0

package/server/lib/review/plan-reviewer.js

@@ -0,0 +1,260 @@
+/**
+ * Plan Reviewer
+ * Validates .planning/phases/{N}-PLAN.md files for structure, scope, and completeness.
+ */
+
+/**
+ * Parse a TLC plan markdown file into a structured object.
+ *
+ * @param {string} content - Raw markdown content of the plan file.
+ * @returns {{ tasks: Array, prerequisites: string[], dependencies: string, rawContent: string }}
+ */
+export function parsePlan(content) {
+  const rawContent = content;
+  const tasks = [];
+  const prerequisites = [];
+  let dependencies = '';
+
+  // --- Prerequisites section (also accept "Context" with "Depends on" lines) ---
+  const prereqMatch = content.match(/^##\s+(?:Prerequisites|Context)\s*\n([\s\S]*?)(?=^##\s|\Z)/m);
+  if (prereqMatch) {
+    const block = prereqMatch[1];
+    const lines = block.split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith('-') || trimmed.startsWith('*')) {
+        const item = trimmed.replace(/^[-*]\s*/, '').trim();
+        if (item) prerequisites.push(item);
+      }
+    }
+  }
+
+  // --- Dependencies section ---
+  const depsMatch = content.match(/^##\s+Dependencies\s*\n([\s\S]*?)(?=^##\s|$)/m);
+  if (depsMatch) {
+    dependencies = depsMatch[1].trim();
+  }
+
+  // --- Tasks section ---
+  // Split on ### Task N: headings
+  const taskHeadingRegex = /^###\s+Task\s+\d+:\s+(.+?)(?:\s+\[.*?\])?\s*$/m;
+  // Use a global split to get all task blocks
+  const taskBlocks = [];
+  const taskHeadingGlobal = /^###\s+Task\s+[\d.]+:\s+(.*?)(?:\s+\[.*?\])?\s*$/gm;
+  let match;
+  const headingPositions = [];
+
+  while ((match = taskHeadingGlobal.exec(content)) !== null) {
+    headingPositions.push({ index: match.index, title: match[1].trim(), end: match.index + match[0].length });
+  }
+
+  for (let i = 0; i < headingPositions.length; i++) {
+    const start = headingPositions[i].end;
+    const end = i + 1 < headingPositions.length ? headingPositions[i + 1].index : content.length;
+    taskBlocks.push({ title: headingPositions[i].title, body: content.slice(start, end) });
+  }
+
+  for (const { title, body } of taskBlocks) {
+    // Goal
+    const goalMatch = body.match(/^\*\*Goal:\*\*\s*(.+)$/m);
+    const goal = goalMatch ? goalMatch[1].trim() : '';
+
+    // Helper: extract a named section from the task body.
+    // Stops at the next **SectionName:** heading or end of body.
+    const extractSection = (sectionName) => {
+      const pattern = new RegExp(`\\*\\*${sectionName}:\\*\\*\\s*\\n([\\s\\S]*?)(?=\\*\\*[A-Za-z]|$)`);
+      const m = body.match(pattern);
+      return m ? m[1] : null;
+    };
+
+    // Files
+    const files = [];
+    const filesBlock = extractSection('Files');
+    if (filesBlock) {
+      for (const line of filesBlock.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('-') || trimmed.startsWith('*')) {
+          const file = trimmed.replace(/^[-*]\s*/, '').trim();
+          if (file) files.push(file);
+        }
+      }
+    }
+
+    // Acceptance Criteria
+    const criteria = [];
+    const criteriaBlock = extractSection('Acceptance Criteria');
+    if (criteriaBlock) {
+      for (const line of criteriaBlock.split('\n')) {
+        const trimmed = line.trim();
+        // Match "- [ ] text" or "- [x] text" checkboxes
+        const cbMatch = trimmed.match(/^[-*]\s+\[[ xX]\]\s+(.+)$/);
+        if (cbMatch) {
+          criteria.push(cbMatch[1].trim());
+        }
+      }
+    }
+
+    // Test Cases
+    const testCases = [];
+    const testCasesBlock = extractSection('Test Cases');
+    if (testCasesBlock) {
+      for (const line of testCasesBlock.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('-') || trimmed.startsWith('*')) {
+          const tc = trimmed.replace(/^[-*]\s*/, '').trim();
+          if (tc) testCases.push(tc);
+        }
+      }
+    }
+
+    tasks.push({ title, goal, files, criteria, testCases });
+  }
+
+  return { tasks, prerequisites, dependencies, rawContent };
+}
+
+/**
+ * Validate the structural completeness of a parsed plan.
+ * Flags tasks missing acceptance criteria or test cases.
+ *
+ * @param {{ tasks: Array }} plan
+ * @returns {Array<{ task: string, message: string }>}
+ */
+export function validateStructure(plan) {
+  const issues = [];
+  for (const task of plan.tasks) {
+    if (!task.criteria || task.criteria.length === 0) {
+      issues.push({ task: task.title, message: `Task "${task.title}" is missing acceptance criteria` });
+    }
+    if (!task.testCases || task.testCases.length === 0) {
+      issues.push({ task: task.title, message: `Task "${task.title}" is missing test cases` });
+    }
+  }
+  return issues;
+}
+
+// Words that indicate a vague/broad task title
+const VAGUE_WORDS = ['system', 'entire', 'all', 'everything', 'complete', 'whole', 'full'];
+
+/**
+ * Validate the scope of tasks in a parsed plan.
+ * Flags vague task titles and tasks with no files listed.
+ *
+ * @param {{ tasks: Array }} plan
+ * @returns {Array<{ task: string, message: string }>}
+ */
+export function validateScope(plan) {
+  const issues = [];
+  for (const task of plan.tasks) {
+    // Check for vague/overly-broad titles
+    const titleLower = task.title.toLowerCase();
+    const vagueFound = VAGUE_WORDS.some(w => titleLower.includes(w));
+    if (vagueFound) {
+      issues.push({
+        task: task.title,
+        message: `Task "${task.title}" title is too vague or broad — consider narrowing the scope`,
+      });
+    }
+
+    // Check for missing files
+    if (!task.files || task.files.length === 0) {
+      issues.push({
+        task: task.title,
+        message: `Task "${task.title}" has no files listed`,
+      });
+    }
+  }
+  return issues;
+}
+
+/**
+ * Validate the architecture of a parsed plan.
+ * Flags files with line-count estimates exceeding 1000 lines.
+ *
+ * @param {{ tasks: Array }} plan
+ * @returns {Array<{ task: string, message: string }>}
+ */
+export function validateArchitecture(plan) {
+  const issues = [];
+  // Match patterns like "(estimated: 1500 lines)" or "(estimated ~1500 lines)"
+  const overSizedPattern = /estimated[^)]*?(\d{4,})\s*lines/i;
+
+  for (const task of plan.tasks) {
+    for (const file of task.files) {
+      const match = file.match(overSizedPattern);
+      if (match) {
+        const lineCount = parseInt(match[1], 10);
+        if (lineCount > 1000) {
+          issues.push({
+            task: task.title,
+            message: `Task "${task.title}" plans a file larger than 1000 lines (${lineCount} lines estimated): ${file}`,
+          });
+        }
+      }
+    }
+    // Also check task goal for large estimates
+    if (task.goal) {
+      const goalMatch = task.goal.match(overSizedPattern);
+      if (goalMatch) {
+        const lineCount = parseInt(goalMatch[1], 10);
+        if (lineCount > 1000) {
+          issues.push({
+            task: task.title,
+            message: `Task "${task.title}" goal describes a file larger than 1000 lines (${lineCount} lines estimated)`,
+          });
+        }
+      }
+    }
+  }
+  return issues;
+}
+
+/**
+ * Validate the completeness of a parsed plan.
+ * Flags plans with no prerequisites section.
+ *
+ * @param {{ prerequisites: string[] }} plan
+ * @returns {Array<{ task: string, message: string }>}
+ */
+export function validateCompleteness(plan) {
+  const issues = [];
+  if (!plan.prerequisites || plan.prerequisites.length === 0) {
+    issues.push({
+      task: null,
+      message: 'Plan is missing a prerequisites section — add a ## Prerequisites block listing prior phases',
+    });
+  }
+  return issues;
+}
+
+/**
+ * Generate a review prompt string for LLM-based plan review.
+ *
+ * @param {{ tasks: Array, rawContent: string }} plan
+ * @param {{ projectName?: string, techStack?: string }} context
+ * @param {{ maxLines?: number }} [options]
+ * @returns {string}
+ */
+export function generateReviewPrompt(plan, context = {}, options = {}) {
+  const projectName = context.projectName || 'Unknown Project';
+  const techStack = context.techStack ? `\nTech stack: ${context.techStack}` : '';
+
+  const taskList = plan.tasks.map((t, i) => `  ${i + 1}. ${t.title}`).join('\n');
+
+  let planContent = plan.rawContent || '';
+  if (options.maxLines && typeof options.maxLines === 'number') {
+    const lines = planContent.split('\n');
+    if (lines.length > options.maxLines) {
+      planContent = lines.slice(0, options.maxLines).join('\n') + '\n[... truncated ...]';
+    }
+  }
+
+  return `You are reviewing a TLC phase plan for the project: ${projectName}.${techStack}
+
+Tasks in this plan:
+${taskList}
+
+Please review the following plan for structure, scope, architecture, and completeness:
+
+${planContent}`;
+}

package/server/lib/review/plan-reviewer.test.js

@@ -0,0 +1,269 @@
+import { describe, it, expect } from 'vitest';
+import {
+  parsePlan,
+  validateStructure,
+  validateScope,
+  validateArchitecture,
+  validateCompleteness,
+  generateReviewPrompt,
+} from './plan-reviewer.js';
+
+const WELL_FORMED_PLAN = `# Phase 42: User Auth — Plan
+
+## Overview
+
+User authentication with JWT tokens.
+
+## Prerequisites
+
+- [x] Phase 41: Database setup
+
+## Tasks
+
+### Task 1: Create user schema [ ]
+
+**Goal:** Define database schema for users table
+
+**Files:**
+- src/modules/user/user.repository.js
+- src/modules/user/user.repository.test.js
+
+**Acceptance Criteria:**
+- [ ] Schema has id, email, passwordHash, createdAt
+- [ ] Email is unique
+
+**Test Cases:**
+- Schema validates correct user data
+- Schema rejects duplicate emails
+
+---
+
+### Task 2: Login endpoint [ ]
+
+**Goal:** POST /api/auth/login
+
+**Files:**
+- src/modules/auth/login.js
+- src/modules/auth/login.test.js
+
+**Acceptance Criteria:**
+- [ ] Validates email/password
+- [ ] Returns JWT token
+
+**Test Cases:**
+- Valid credentials return token
+- Invalid password returns 401
+
+## Dependencies
+
+Task 2 depends on Task 1
+`;
+
+const PLAN_MISSING_CRITERIA = `# Phase 43: Something
+
+## Tasks
+
+### Task 1: Do something [ ]
+
+**Goal:** Build the thing
+
+**Files:**
+- src/thing.js
+`;
+
+const PLAN_VAGUE_TASK = `# Phase 44: Auth
+
+## Prerequisites
+
+- [x] Phase 43
+
+## Tasks
+
+### Task 1: Build auth system [ ]
+
+**Goal:** Build the entire authentication system
+
+**Files:**
+- src/auth.js
+
+**Acceptance Criteria:**
+- [ ] Auth works
+
+**Test Cases:**
+- Auth works correctly
+`;
+
+const PLAN_OVERSIZED_FILE = `# Phase 45: Big Module
+
+## Prerequisites
+
+- [x] Phase 44
+
+## Tasks
+
+### Task 1: Create mega module [ ]
+
+**Goal:** Build a massive module (estimated ~1500 lines)
+
+**Files:**
+- src/mega-module.js (estimated: 1500 lines)
+
+**Acceptance Criteria:**
+- [ ] Module works
+
+**Test Cases:**
+- Module functions correctly
+`;
+
+describe('plan-reviewer', () => {
+  describe('parsePlan', () => {
+    it('extracts tasks from well-formed plan', () => {
+      const plan = parsePlan(WELL_FORMED_PLAN);
+      expect(plan.tasks).toHaveLength(2);
+      expect(plan.tasks[0].title).toContain('Create user schema');
+      expect(plan.tasks[1].title).toContain('Login endpoint');
+    });
+
+    it('extracts acceptance criteria per task', () => {
+      const plan = parsePlan(WELL_FORMED_PLAN);
+      expect(plan.tasks[0].criteria.length).toBeGreaterThanOrEqual(2);
+      expect(plan.tasks[0].criteria[0]).toContain('id, email');
+    });
+
+    it('extracts file lists per task', () => {
+      const plan = parsePlan(WELL_FORMED_PLAN);
+      expect(plan.tasks[0].files).toHaveLength(2);
+      expect(plan.tasks[0].files[0]).toContain('user.repository.js');
+    });
+
+    it('extracts test cases per task', () => {
+      const plan = parsePlan(WELL_FORMED_PLAN);
+      expect(plan.tasks[0].testCases.length).toBeGreaterThanOrEqual(2);
+    });
+
+    it('extracts dependencies section', () => {
+      const plan = parsePlan(WELL_FORMED_PLAN);
+      expect(plan.dependencies).toContain('Task 2 depends on Task 1');
+    });
+
+    it('handles plan with no tasks', () => {
+      const plan = parsePlan('# Empty Plan\n\nNo tasks here.');
+      expect(plan.tasks).toHaveLength(0);
+    });
+
+    it('extracts prerequisites', () => {
+      const plan = parsePlan(WELL_FORMED_PLAN);
+      expect(plan.prerequisites.length).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  describe('validateStructure', () => {
+    it('passes for well-formed plan', () => {
+      const plan = parsePlan(WELL_FORMED_PLAN);
+      const issues = validateStructure(plan);
+      expect(issues).toHaveLength(0);
+    });
+
+    it('flags missing acceptance criteria', () => {
+      const plan = parsePlan(PLAN_MISSING_CRITERIA);
+      const issues = validateStructure(plan);
+      expect(issues.some(i => i.message.toLowerCase().includes('criteria'))).toBe(true);
+    });
+
+    it('flags missing test cases', () => {
+      const plan = parsePlan(PLAN_MISSING_CRITERIA);
+      const issues = validateStructure(plan);
+      expect(issues.some(i => i.message.toLowerCase().includes('test'))).toBe(true);
+    });
+  });
+
+  describe('validateScope', () => {
+    it('passes for properly scoped tasks', () => {
+      const plan = parsePlan(WELL_FORMED_PLAN);
+      const issues = validateScope(plan);
+      expect(issues).toHaveLength(0);
+    });
+
+    it('flags vague task title', () => {
+      const plan = parsePlan(PLAN_VAGUE_TASK);
+      const issues = validateScope(plan);
+      expect(issues.some(i => i.message.toLowerCase().includes('vague') || i.message.toLowerCase().includes('broad'))).toBe(true);
+    });
+
+    it('flags task with no files listed', () => {
+      const noFiles = `# Phase 50: X
+
+## Prerequisites
+
+- [x] Phase 49
+
+## Tasks
+
+### Task 1: Do thing [ ]
+
+**Goal:** Do the thing
+
+**Acceptance Criteria:**
+- [ ] Thing is done
+
+**Test Cases:**
+- Thing works
+`;
+      const plan = parsePlan(noFiles);
+      const issues = validateScope(plan);
+      expect(issues.some(i => i.message.toLowerCase().includes('file'))).toBe(true);
+    });
+  });
+
+  describe('validateArchitecture', () => {
+    it('passes for normal-sized files', () => {
+      const plan = parsePlan(WELL_FORMED_PLAN);
+      const issues = validateArchitecture(plan);
+      expect(issues).toHaveLength(0);
+    });
+
+    it('flags planned >1000 line file', () => {
+      const plan = parsePlan(PLAN_OVERSIZED_FILE);
+      const issues = validateArchitecture(plan);
+      expect(issues.some(i => i.message.toLowerCase().includes('1000') || i.message.toLowerCase().includes('large'))).toBe(true);
+    });
+  });
+
+  describe('validateCompleteness', () => {
+    it('passes for complete plan', () => {
+      const plan = parsePlan(WELL_FORMED_PLAN);
+      const issues = validateCompleteness(plan);
+      expect(issues).toHaveLength(0);
+    });
+
+    it('flags missing prerequisites', () => {
+      const plan = parsePlan(PLAN_MISSING_CRITERIA);
+      const issues = validateCompleteness(plan);
+      expect(issues.some(i => i.message.toLowerCase().includes('prerequisite'))).toBe(true);
+    });
+  });
+
+  describe('generateReviewPrompt', () => {
+    it('includes project context', () => {
+      const plan = parsePlan(WELL_FORMED_PLAN);
+      const prompt = generateReviewPrompt(plan, { projectName: 'MyApp', techStack: 'Node.js' });
+      expect(prompt).toContain('MyApp');
+    });
+
+    it('includes plan content', () => {
+      const plan = parsePlan(WELL_FORMED_PLAN);
+      const prompt = generateReviewPrompt(plan, { projectName: 'MyApp' });
+      expect(prompt).toContain('Create user schema');
+      expect(prompt).toContain('Login endpoint');
+    });
+
+    it('truncates large plans for external providers', () => {
+      const longContent = 'x\n'.repeat(1000);
+      const plan = parsePlan(WELL_FORMED_PLAN);
+      plan.rawContent = longContent;
+      const prompt = generateReviewPrompt(plan, { projectName: 'MyApp' }, { maxLines: 500 });
+      const lines = prompt.split('\n').length;
+      expect(lines).toBeLessThanOrEqual(600); // 500 + prompt template overhead
+    });
+  });
+});

package/server/lib/review/review-schemas.js

@@ -0,0 +1,173 @@
+/**
+ * Review Output Schemas
+ * JSON schemas for structured output from Claude and Codex review commands.
+ */
+
+/** @type {string[]} Valid severity levels in descending order of urgency. */
+export const SEVERITY_LEVELS = ['critical', 'high', 'medium', 'low'];
+
+/**
+ * Internal schema descriptor for code review output.
+ * Describes the shape expected from an LLM code review response.
+ * @type {object}
+ */
+export const codeReviewSchema = {
+  name: 'codeReview',
+  required: ['verdict', 'score', 'summary', 'issues'],
+  verdicts: ['APPROVED', 'CHANGES_REQUESTED'],
+  issueRequired: ['file', 'line', 'severity', 'category', 'message', 'suggestion'],
+};
+
+/**
+ * Internal schema descriptor for plan review output.
+ * Describes the shape expected from an LLM plan review response.
+ * @type {object}
+ */
+export const planReviewSchema = {
+  name: 'planReview',
+  required: ['verdict', 'structureIssues', 'scopeIssues', 'suggestions'],
+  verdicts: ['APPROVED', 'CHANGES_REQUESTED'],
+};
+
+/**
+ * Validates a review output object against a schema descriptor.
+ *
+ * @param {object} output - The review output to validate.
+ * @param {object} schema - The schema descriptor (codeReviewSchema or planReviewSchema).
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateReviewOutput(output, schema) {
+  const errors = [];
+
+  // Check top-level required fields
+  for (const field of schema.required) {
+    if (!(field in output)) {
+      errors.push(`Missing required field: ${field}`);
+    }
+  }
+
+  // Validate verdict value if present
+  if ('verdict' in output && schema.verdicts && !schema.verdicts.includes(output.verdict)) {
+    errors.push(`Invalid verdict: "${output.verdict}". Must be one of: ${schema.verdicts.join(', ')}`);
+  }
+
+  // For code review schema: validate each issue
+  if (schema.issueRequired && Array.isArray(output.issues)) {
+    output.issues.forEach((issue, idx) => {
+      for (const field of schema.issueRequired) {
+        if (!(field in issue)) {
+          errors.push(`Issue[${idx}] missing required field: ${field}`);
+        }
+      }
+      if ('severity' in issue && !SEVERITY_LEVELS.includes(issue.severity)) {
+        errors.push(`Issue[${idx}] has invalid severity: "${issue.severity}". Must be one of: ${SEVERITY_LEVELS.join(', ')}`);
+      }
+    });
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Parses a freeform markdown review text and extracts structured data.
+ *
+ * Verdict is detected from lines like `Verdict: APPROVED` or `Verdict: CHANGES_REQUESTED`.
+ * Issues are detected from bullet lines like:
+ *   `- src/auth.js:42 [high] Hardcoded password`
+ *
+ * @param {string} text - Freeform markdown review text.
+ * @returns {{ verdict: string, issues: Array<{file: string, line: number, severity: string, message: string}> }}
+ */
+export function parseMarkdownReview(text) {
+  let verdict = 'UNKNOWN';
+  const issues = [];
+
+  // Match "Verdict: APPROVED" or "Verdict: CHANGES_REQUESTED" (case-insensitive label)
+  const verdictMatch = text.match(/verdict\s*:\s*(APPROVED|CHANGES_REQUESTED)/i);
+  if (verdictMatch) {
+    verdict = verdictMatch[1].toUpperCase();
+  }
+
+  // Match bullet lines: - path/file.js:linenum [severity] message
+  const issueRegex = /^[-*]\s+([\w./\-]+):(\d+)\s+\[(\w+)\]\s+(.+)$/gm;
+  let match;
+  while ((match = issueRegex.exec(text)) !== null) {
+    const [, file, lineStr, severity, message] = match;
+    issues.push({
+      file,
+      line: parseInt(lineStr, 10),
+      severity: severity.toLowerCase(),
+      message: message.trim(),
+    });
+  }
+
+  return { verdict, issues };
+}
+
+/**
+ * Exports the internal schema descriptors as proper JSON Schema objects.
+ *
+ * @returns {{ codeReview: object, planReview: object }}
+ */
+export function exportSchemas() {
+  const codeReview = {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    type: 'object',
+    required: ['verdict', 'score', 'summary', 'issues'],
+    properties: {
+      verdict: {
+        type: 'string',
+        enum: ['APPROVED', 'CHANGES_REQUESTED'],
+      },
+      score: {
+        type: 'number',
+        minimum: 0,
+        maximum: 100,
+      },
+      summary: {
+        type: 'string',
+      },
+      issues: {
+        type: 'array',
+        items: {
+          type: 'object',
+          required: ['file', 'line', 'severity', 'category', 'message', 'suggestion'],
+          properties: {
+            file: { type: 'string' },
+            line: { type: 'integer' },
+            severity: { type: 'string', enum: SEVERITY_LEVELS },
+            category: { type: 'string' },
+            message: { type: 'string' },
+            suggestion: { type: 'string' },
+          },
+        },
+      },
+    },
+  };
+
+  const planReview = {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    type: 'object',
+    required: ['verdict', 'structureIssues', 'scopeIssues', 'suggestions'],
+    properties: {
+      verdict: {
+        type: 'string',
+        enum: ['APPROVED', 'CHANGES_REQUESTED'],
+      },
+      structureIssues: {
+        type: 'array',
+        items: { type: 'string' },
+      },
+      scopeIssues: {
+        type: 'array',
+        items: { type: 'string' },
+      },
+      suggestions: {
+        type: 'array',
+        items: { type: 'string' },
+      },
+    },
+  };
+
+  return { codeReview, planReview };
+}