agileflow 2.90.7 → 2.92.0

package/scripts/validators/component-validator.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/**
+ * Component Validator
+ *
+ * Validates React/Vue/Svelte component files for common issues.
+ *
+ * Exit codes:
+ *   0 = Success
+ *   2 = Error (Claude will attempt to fix)
+ *   1 = Warning (logged but not blocking)
+ *
+ * Usage in agent hooks:
+ *   hooks:
+ *     PostToolUse:
+ *       - matcher: "Write"
+ *         hooks:
+ *           - type: command
+ *             command: "node .agileflow/hooks/validators/component-validator.js"
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+let input = '';
+process.stdin.on('data', chunk => (input += chunk));
+process.stdin.on('end', () => {
+  try {
+    const context = JSON.parse(input);
+    const filePath = context.tool_input?.file_path;
+
+    // Only validate component files
+    if (!filePath || !isComponentFile(filePath)) {
+      process.exit(0);
+    }
+
+    // Skip if file doesn't exist
+    if (!fs.existsSync(filePath)) {
+      console.log(`File not found: ${filePath} (skipping validation)`);
+      process.exit(0);
+    }
+
+    const issues = validateComponent(filePath);
+
+    if (issues.length > 0) {
+      console.error(`Fix these component issues in ${filePath}:`);
+      issues.forEach(i => console.error(`  - ${i}`));
+      process.exit(2); // Claude will fix
+    }
+
+    console.log(`Component validation passed: ${filePath}`);
+    process.exit(0);
+  } catch (e) {
+    console.error(`Validator error: ${e.message}`);
+    process.exit(1);
+  }
+});
+
+function isComponentFile(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  const componentExtensions = ['.jsx', '.tsx', '.vue', '.svelte'];
+
+  // Also check for .js/.ts files in component directories
+  if (['.js', '.ts'].includes(ext)) {
+    const normalizedPath = filePath.toLowerCase();
+    return (
+      normalizedPath.includes('/components/') ||
+      normalizedPath.includes('/pages/') ||
+      normalizedPath.includes('/views/')
+    );
+  }
+
+  return componentExtensions.includes(ext);
+}
+
+function validateComponent(filePath) {
+  const issues = [];
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const ext = path.extname(filePath).toLowerCase();
+    const fileName = path.basename(filePath, ext);
+
+    // Check for empty component
+    if (!content.trim()) {
+      issues.push('Component file is empty');
+      return issues;
+    }
+
+    // React/JSX/TSX validation
+    if (['.jsx', '.tsx'].includes(ext) || content.includes('React')) {
+      issues.push(...validateReactComponent(content, fileName));
+    }
+
+    // Vue validation
+    if (ext === '.vue') {
+      issues.push(...validateVueComponent(content));
+    }
+
+    // Svelte validation
+    if (ext === '.svelte') {
+      issues.push(...validateSvelteComponent(content));
+    }
+
+    // General accessibility checks
+    issues.push(...validateAccessibility(content));
+  } catch (e) {
+    issues.push(`Read error: ${e.message}`);
+  }
+
+  return issues;
+}
+
+function validateReactComponent(content, fileName) {
+  const issues = [];
+
+  // Check for component export
+  if (
+    !content.includes('export default') &&
+    !content.includes('export function') &&
+    !content.includes('export const')
+  ) {
+    issues.push(
+      'Component should have an export (export default, export function, or export const)'
+    );
+  }
+
+  // Check for React import in JSX files
+  if (
+    content.includes('React.') &&
+    !content.includes("from 'react'") &&
+    !content.includes('from "react"')
+  ) {
+    issues.push('Using React. prefix but React is not imported');
+  }
+
+  // Check for proper function/component naming (should match filename for default exports)
+  const pascalCaseRegex = /^[A-Z][a-zA-Z0-9]*$/;
+  if (!pascalCaseRegex.test(fileName) && !fileName.startsWith('use')) {
+    // Only warn, don't block - could be a utility file
+    console.log(`Note: Component filename "${fileName}" should be PascalCase`);
+  }
+
+  // Check for inline styles (prefer CSS modules or styled-components)
+  const inlineStyleCount = (content.match(/style=\{\{/g) || []).length;
+  if (inlineStyleCount > 5) {
+    issues.push(
+      `Too many inline styles (${inlineStyleCount}) - consider using CSS modules or styled-components`
+    );
+  }
+
+  // Check for console.log in production code
+  if (
+    content.includes('console.log') &&
+    !content.includes('// debug') &&
+    !content.includes('// DEBUG')
+  ) {
+    console.log("Note: console.log found - ensure it's removed before production");
+  }
+
+  // Check for missing key prop in map
+  if (content.includes('.map(') && content.includes('<') && !content.includes('key=')) {
+    issues.push('Array .map() rendering elements should include key prop');
+  }
+
+  return issues;
+}
+
+function validateVueComponent(content) {
+  const issues = [];
+
+  // Check for required template section
+  if (!content.includes('<template>') && !content.includes('<template ')) {
+    issues.push('Vue component must have a <template> section');
+  }
+
+  // Check for script section
+  if (!content.includes('<script') && !content.includes('<script>')) {
+    // Not strictly required but recommended
+    console.log('Note: Vue component has no <script> section');
+  }
+
+  // Check for scoped styles (recommended)
+  if (
+    content.includes('<style>') &&
+    !content.includes('<style scoped') &&
+    !content.includes('scoped>')
+  ) {
+    console.log('Note: Consider using scoped styles to prevent CSS leaks');
+  }
+
+  return issues;
+}
+
+function validateSvelteComponent(content) {
+  const issues = [];
+
+  // Check for script section
+  if (!content.includes('<script') && !content.includes('<script>')) {
+    console.log('Note: Svelte component has no <script> section');
+  }
+
+  return issues;
+}
+
+function validateAccessibility(content) {
+  const issues = [];
+
+  // Check for images without alt
+  const imgWithoutAlt = content.match(/<img[^>]*(?!alt=)[^>]*>/gi) || [];
+  const imgWithEmptyAlt = content.match(/<img[^>]*alt=["']["'][^>]*>/gi) || [];
+
+  if (imgWithoutAlt.length > 0) {
+    issues.push(`Found ${imgWithoutAlt.length} <img> tag(s) without alt attribute`);
+  }
+
+  // Check for button without type
+  if (content.includes('<button') && !content.includes('type=')) {
+    console.log('Note: <button> elements should have explicit type attribute');
+  }
+
+  // Check for click handlers on non-interactive elements
+  const clickOnDiv = content.match(/onClick[^>]*>[^<]*<\/div>/gi) || [];
+  if (clickOnDiv.length > 0) {
+    issues.push(
+      'onClick on <div> detected - use <button> for interactive elements (accessibility)'
+    );
+  }
+
+  // Check for form inputs without labels
+  if (
+    content.includes('<input') &&
+    !content.includes('<label') &&
+    !content.includes('aria-label')
+  ) {
+    console.log('Note: <input> elements should have associated <label> or aria-label');
+  }
+
+  return issues;
+}

package/scripts/validators/json-schema-validator.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+/**
+ * JSON Schema Validator
+ *
+ * Validates JSON files for proper structure after Write operations.
+ *
+ * Exit codes:
+ *   0 = Success
+ *   2 = Error (Claude will attempt to fix)
+ *   1 = Warning (logged but not blocking)
+ *
+ * Usage in agent hooks:
+ *   hooks:
+ *     PostToolUse:
+ *       - matcher: "Write"
+ *         hooks:
+ *           - type: command
+ *             command: "node .agileflow/hooks/validators/json-schema-validator.js"
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Import status constants from single source of truth
+const { VALID_STATUSES } = require('../lib/story-state-machine');
+
+// Extended statuses for backward compatibility (maps to canonical values)
+// These legacy values are accepted but should be migrated to canonical values
+const LEGACY_STATUSES = ['pending', 'done', 'in-progress', 'in-review'];
+const ALL_ACCEPTED_STATUSES = [...VALID_STATUSES, ...LEGACY_STATUSES];
+
+let input = '';
+process.stdin.on('data', chunk => (input += chunk));
+process.stdin.on('end', () => {
+  try {
+    const context = JSON.parse(input);
+    const filePath = context.tool_input?.file_path;
+
+    // Only validate JSON files
+    if (!filePath || !filePath.endsWith('.json')) {
+      process.exit(0);
+    }
+
+    // Skip if file doesn't exist (might be a create failure)
+    if (!fs.existsSync(filePath)) {
+      console.log(`File not found: ${filePath} (skipping validation)`);
+      process.exit(0);
+    }
+
+    const issues = validateJson(filePath);
+
+    if (issues.length > 0) {
+      console.error(`Resolve these JSON issues in ${filePath}:`);
+      issues.forEach(i => console.error(`  - ${i}`));
+      process.exit(2); // Claude will fix
+    }
+
+    console.log(`JSON validation passed: ${filePath}`);
+    process.exit(0);
+  } catch (e) {
+    console.error(`Validator error: ${e.message}`);
+    process.exit(1);
+  }
+});
+
+function validateJson(filePath) {
+  const issues = [];
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+
+    // Check for empty file
+    if (!content.trim()) {
+      issues.push('File is empty');
+      return issues;
+    }
+
+    // Try to parse JSON
+    const data = JSON.parse(content);
+
+    // Check for common JSON issues
+    if (typeof data !== 'object' || data === null) {
+      issues.push('Root must be an object or array');
+    }
+
+    // Specific checks for known files
+    const fileName = path.basename(filePath);
+
+    if (fileName === 'status.json') {
+      issues.push(...validateStatusJson(data));
+    } else if (fileName === 'package.json') {
+      issues.push(...validatePackageJson(data));
+    } else if (fileName === 'tsconfig.json') {
+      issues.push(...validateTsConfig(data));
+    }
+  } catch (e) {
+    if (e instanceof SyntaxError) {
+      issues.push(`Invalid JSON syntax: ${e.message}`);
+    } else {
+      issues.push(`Read error: ${e.message}`);
+    }
+  }
+
+  return issues;
+}
+
+function validateStatusJson(data) {
+  const issues = [];
+
+  // Check for required structure - status.json has epics object with embedded stories
+  if (!data.epics && !data.current_story && !data.updated) {
+    issues.push('status.json should have epics, current_story, or updated field');
+  }
+
+  // Validate epics object if present
+  if (data.epics) {
+    if (typeof data.epics !== 'object' || Array.isArray(data.epics)) {
+      issues.push('epics must be an object (not array)');
+    } else {
+      Object.entries(data.epics).forEach(([epicId, epic]) => {
+        if (!epic.title) {
+          issues.push(`Epic ${epicId} missing 'title' field`);
+        }
+        if (epic.stories && !Array.isArray(epic.stories)) {
+          issues.push(`Epic ${epicId} stories must be an array`);
+        }
+      });
+    }
+  }
+
+  // Validate stories - can be object (map by ID) or array
+  if (data.stories) {
+    if (Array.isArray(data.stories)) {
+      // Array format
+      data.stories.forEach((story, index) => {
+        if (!story.id) {
+          issues.push(`Story at index ${index} missing required 'id' field`);
+        }
+        if (!story.title && !story.name) {
+          issues.push(`Story ${story.id || index} missing 'title' or 'name' field`);
+        }
+        if (story.status && !ALL_ACCEPTED_STATUSES.includes(story.status)) {
+          issues.push(`Story ${story.id || index} has invalid status: ${story.status}`);
+        }
+      });
+    } else if (typeof data.stories === 'object') {
+      // Object/map format (keyed by story ID)
+      Object.entries(data.stories).forEach(([storyId, story]) => {
+        if (!story.title && !story.name) {
+          issues.push(`Story ${storyId} missing 'title' or 'name' field`);
+        }
+        if (story.status && !ALL_ACCEPTED_STATUSES.includes(story.status)) {
+          issues.push(`Story ${storyId} has invalid status: ${story.status}`);
+        }
+      });
+    }
+  }
+
+  return issues;
+}
+
+function validatePackageJson(data) {
+  const issues = [];
+
+  if (!data.name) {
+    issues.push('package.json requires "name" field');
+  }
+  if (!data.version) {
+    issues.push('package.json requires "version" field');
+  }
+  if (data.version && !/^\d+\.\d+\.\d+/.test(data.version)) {
+    issues.push(`Invalid version format: ${data.version} (expected semver)`);
+  }
+
+  return issues;
+}
+
+function validateTsConfig(data) {
+  const issues = [];
+
+  if (!data.compilerOptions) {
+    issues.push('tsconfig.json should have compilerOptions');
+  }
+
+  return issues;
+}

package/scripts/validators/markdown-validator.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/**
+ * Markdown Validator
+ *
+ * Validates markdown files for proper structure after Write operations.
+ *
+ * Exit codes:
+ *   0 = Success
+ *   2 = Error (Claude will attempt to fix)
+ *   1 = Warning (logged but not blocking)
+ *
+ * Usage in agent hooks:
+ *   hooks:
+ *     PostToolUse:
+ *       - matcher: "Write"
+ *         hooks:
+ *           - type: command
+ *             command: "node .agileflow/hooks/validators/markdown-validator.js"
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+let input = '';
+process.stdin.on('data', chunk => (input += chunk));
+process.stdin.on('end', () => {
+  try {
+    const context = JSON.parse(input);
+    const filePath = context.tool_input?.file_path;
+
+    // Only validate markdown files
+    if (!filePath || !filePath.endsWith('.md')) {
+      process.exit(0);
+    }
+
+    // Skip if file doesn't exist
+    if (!fs.existsSync(filePath)) {
+      console.log(`File not found: ${filePath} (skipping validation)`);
+      process.exit(0);
+    }
+
+    const issues = validateMarkdown(filePath);
+
+    if (issues.length > 0) {
+      console.error(`Resolve these markdown issues in ${filePath}:`);
+      issues.forEach(i => console.error(`  - ${i}`));
+      process.exit(2); // Claude will fix
+    }
+
+    console.log(`Markdown validation passed: ${filePath}`);
+    process.exit(0);
+  } catch (e) {
+    console.error(`Validator error: ${e.message}`);
+    process.exit(1);
+  }
+});
+
+function validateMarkdown(filePath) {
+  const issues = [];
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const lines = content.split('\n');
+    const fileName = path.basename(filePath);
+
+    // Check for empty file
+    if (!content.trim()) {
+      issues.push('File is empty');
+      return issues;
+    }
+
+    // Check for title (first line should be # heading)
+    const firstContentLine = lines.find(l => l.trim());
+    if (!firstContentLine?.startsWith('#')) {
+      issues.push('Document should start with a heading (#)');
+    }
+
+    // Check for broken links (basic check)
+    const brokenLinkPattern = /\[([^\]]*)\]\(\s*\)/g;
+    let match;
+    while ((match = brokenLinkPattern.exec(content)) !== null) {
+      issues.push(`Empty link found: [${match[1]}]()`);
+    }
+
+    // Check for unclosed code blocks
+    const codeBlockCount = (content.match(/```/g) || []).length;
+    if (codeBlockCount % 2 !== 0) {
+      issues.push('Unclosed code block (odd number of ``` markers)');
+    }
+
+    // Check for heading hierarchy issues
+    let lastHeadingLevel = 0;
+    lines.forEach((line, index) => {
+      const headingMatch = line.match(/^(#{1,6})\s/);
+      if (headingMatch) {
+        const level = headingMatch[1].length;
+        // Skip from level 0 to level 1 is OK
+        if (lastHeadingLevel > 0 && level > lastHeadingLevel + 1) {
+          issues.push(`Line ${index + 1}: Heading level jump (h${lastHeadingLevel} to h${level})`);
+        }
+        lastHeadingLevel = level;
+      }
+    });
+
+    // Check for specific file types
+    if (fileName.startsWith('adr-') || fileName.startsWith('ADR-')) {
+      issues.push(...validateADR(content));
+    } else if (filePath.includes('/10-research/')) {
+      issues.push(...validateResearchNote(content));
+    }
+  } catch (e) {
+    issues.push(`Read error: ${e.message}`);
+  }
+
+  return issues;
+}
+
+function validateADR(content) {
+  const issues = [];
+
+  const requiredSections = ['## Context', '## Decision', '## Consequences'];
+  requiredSections.forEach(section => {
+    if (!content.includes(section)) {
+      issues.push(`ADR missing required section: ${section}`);
+    }
+  });
+
+  if (!content.includes('**Status**:')) {
+    issues.push('ADR missing Status field');
+  }
+  if (!content.includes('**Date**:')) {
+    issues.push('ADR missing Date field');
+  }
+
+  return issues;
+}
+
+function validateResearchNote(content) {
+  const issues = [];
+
+  if (!content.includes('**Import Date**:')) {
+    issues.push('Research note missing Import Date');
+  }
+  if (!content.includes('## Summary')) {
+    issues.push('Research note missing Summary section');
+  }
+  if (!content.includes('## Key Findings')) {
+    issues.push('Research note missing Key Findings section');
+  }
+
+  return issues;
+}

package/scripts/validators/migration-validator.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/**
+ * Migration Validator
+ *
+ * Validates database migration commands for proper patterns.
+ *
+ * Exit codes:
+ *   0 = Success
+ *   2 = Error (Claude will attempt to fix)
+ *   1 = Warning (logged but not blocking)
+ *
+ * Usage in agent hooks:
+ *   hooks:
+ *     PostToolUse:
+ *       - matcher: "Bash"
+ *         hooks:
+ *           - type: command
+ *             command: "node .agileflow/hooks/validators/migration-validator.js"
+ */
+
+let input = '';
+process.stdin.on('data', chunk => (input += chunk));
+process.stdin.on('end', () => {
+  try {
+    const context = JSON.parse(input);
+    const command = context.tool_input?.command;
+    const result = context.result || '';
+
+    // Only validate migration-related commands
+    if (!command || !isMigrationCommand(command)) {
+      process.exit(0);
+    }
+
+    const issues = validateMigration(command, result);
+
+    if (issues.length > 0) {
+      console.error(`Migration validation issues:`);
+      issues.forEach(i => console.error(`  - ${i}`));
+      process.exit(2); // Claude will fix
+    }
+
+    console.log(`Migration validation passed: ${command.substring(0, 50)}...`);
+    process.exit(0);
+  } catch (e) {
+    console.error(`Validator error: ${e.message}`);
+    process.exit(1);
+  }
+});
+
+function isMigrationCommand(command) {
+  const migrationPatterns = [
+    /prisma\s+migrate/i,
+    /drizzle-kit/i,
+    /typeorm\s+migration/i,
+    /knex\s+migrate/i,
+    /sequelize\s+db:migrate/i,
+    /alembic/i,
+    /flyway/i,
+    /liquibase/i,
+    /rails\s+db:migrate/i,
+    /django.*migrate/i,
+    /psql.*-f.*\.sql/i,
+    /mysql.*<.*\.sql/i,
+  ];
+
+  return migrationPatterns.some(pattern => pattern.test(command));
+}
+
+function validateMigration(command, result) {
+  const issues = [];
+
+  // Check for destructive operations without safeguards
+  const destructivePatterns = [
+    {
+      pattern: /DROP\s+TABLE/i,
+      message: 'DROP TABLE detected - ensure backup exists and this is intentional',
+    },
+    {
+      pattern: /DROP\s+DATABASE/i,
+      message: 'DROP DATABASE detected - this is extremely destructive!',
+    },
+    { pattern: /TRUNCATE/i, message: 'TRUNCATE detected - this removes all data permanently' },
+    {
+      pattern: /DELETE\s+FROM.*WHERE\s*$/i,
+      message: 'DELETE without WHERE clause detected - will delete all rows',
+    },
+    { pattern: /--force|--skip-safe/i, message: 'Force flag used - bypassing safety checks' },
+  ];
+
+  for (const { pattern, message } of destructivePatterns) {
+    if (pattern.test(command) || pattern.test(result)) {
+      issues.push(message);
+    }
+  }
+
+  // Check for production environment safeguards
+  if (/production|prod/i.test(command) && !/--dry-run/i.test(command)) {
+    issues.push('Production migration without --dry-run flag - consider dry run first');
+  }
+
+  // Check for failed migrations in output
+  const failurePatterns = [
+    { pattern: /error.*migration/i, message: 'Migration error detected in output' },
+    { pattern: /rollback.*failed/i, message: 'Rollback failure detected' },
+    { pattern: /constraint.*violation/i, message: 'Database constraint violation' },
+    {
+      pattern: /duplicate.*key/i,
+      message: 'Duplicate key error - migration may have partially applied',
+    },
+    { pattern: /already exists/i, message: 'Object already exists - migration may need cleanup' },
+  ];
+
+  for (const { pattern, message } of failurePatterns) {
+    if (pattern.test(result)) {
+      issues.push(message);
+    }
+  }
+
+  // Check for missing rollback strategy
+  if (/migrate.*dev|migrate.*run/i.test(command)) {
+    // Prisma and similar ORMs
+    if (!/down|rollback|reset/i.test(result) && result.includes('migration')) {
+      // Just a warning, not blocking
+      console.log('Note: Ensure rollback migration exists for this change');
+    }
+  }
+
+  return issues;
+}