jettypod 4.4.0 → 4.4.2

package/docs/DECISIONS.md

@@ -6,61 +6,13 @@ This document records key decisions made during project discovery and epic plann
 
 ## Epic-Level Decisions
 
-### Epic #237: Real-time Collaboration
+### Epic #2: Standalone Chore Workflow System
 
-**Architecture:** WebSockets with Socket.io
+**Architecture:** Two-tier skill structure (chore-planning → chore-mode)
 
-*Rationale:* Bidirectional communication needed, Socket.io provides automatic fallbacks and reconnection
+*Rationale:* Two-tier skill structure chosen to mirror existing feature workflow patterns. Separates planning concerns (scope, criteria, impact) from execution concerns (guidance, verification). Type-dependent test analysis balances thoroughness with pragmatism.
 
-*Date:* 10/29/2025
-
-**State Management:** Redux Toolkit
-
-*Rationale:* Need centralized state for connection status across multiple components
-
-*Date:* 10/29/2025
-
-**Error Handling:** Exponential backoff with jitter for reconnection
-
-*Rationale:* Prevents thundering herd when server recovers, jitter distributes reconnection attempts evenly
-
-*Date:* 10/31/2025
-
-**Testing Strategy:** Integration tests with mock Socket.io server
-
-*Rationale:* Allows testing reconnection logic and state synchronization without real server dependency
-
-*Date:* 10/31/2025
-
----
-
-### Epic #238: Real-time System
-
-**Architecture:** WebSockets
-
-*Rationale:* Real-time bidirectional communication required
-
-*Date:* 10/29/2025
-
----
-
-### Epic #242: Epic Needs Discovery
-
-**Architecture:** GraphQL API
-
-*Rationale:* Flexible querying and strong typing needed for complex data requirements
-
-*Date:* 10/29/2025
-
----
-
-### Epic #1840: Multiple AI Coding Assistant Instances
-
-**Concurrent Merge Architecture:** Database-backed merge queue with rebase-first strategy and smart conflict resolution
-
-*Rationale:* Multiple Claude Code instances need coordinated access to main branch. Using database as coordination point provides simple, reliable serialization without complex distributed locking. Rebase-first strategy ensures linear history and makes conflicts easier to reason about. Smart conflict resolution (auto-resolve trivial, LLM-assist complex) enables autonomous operation while escalating truly ambiguous cases. Graceful degradation ensures system never enters unrecoverable state.
-
-*Date:* 11/14/2025
+*Date:* 11/25/2025
 
 ---
 

package/jettypod.js

@@ -222,6 +222,7 @@ jettypod work create feature "<title>" --parent=<id>
 jettypod work start <id>
 jettypod work status <id> cancelled
 jettypod backlog
+jettypod impact <file>    # Show tests/features affected by changing a file
 
 ## Advanced Commands
 For mode management, decisions, project state: docs/COMMAND_REFERENCE.md
@@ -2062,6 +2063,94 @@ Quick commands:
     break;
   }
 
+  case 'impact': {
+    // Test impact analysis
+    const targetFile = args[0];
+
+    if (!targetFile) {
+      console.log('Usage: jettypod impact <file-path>');
+      console.log('');
+      console.log('Analyze what tests and features would be affected by changing a file.');
+      console.log('');
+      console.log('Examples:');
+      console.log('  jettypod impact lib/database.js');
+      console.log('  jettypod impact features/work-tracking/index.js');
+      process.exit(1);
+    }
+
+    try {
+      const { DependencyGraph } = require('./lib/test-impact-analyzer');
+      const graph = new DependencyGraph();
+
+      console.log('🔍 Building dependency graph...');
+      await graph.build(process.cwd());
+
+      const impact = graph.getImpact(targetFile);
+
+      if (impact.error) {
+        console.error(`\n❌ ${impact.error}`);
+        console.log('');
+        console.log('Make sure the file path is relative to the project root.');
+        process.exit(1);
+      }
+
+      // Pretty-print impact analysis
+      const levelColors = {
+        LOW: '\x1b[32m',    // green
+        MEDIUM: '\x1b[33m', // yellow
+        HIGH: '\x1b[31m'    // red
+      };
+      const reset = '\x1b[0m';
+      const bold = '\x1b[1m';
+      const dim = '\x1b[2m';
+
+      console.log('');
+      console.log('═'.repeat(60));
+      console.log(`${bold}IMPACT ANALYSIS: ${targetFile}${reset}`);
+      console.log('═'.repeat(60));
+      console.log('');
+      console.log(`Impact Score: ${bold}${impact.impactScore}/100${reset} ${levelColors[impact.impactLevel]}(${impact.impactLevel})${reset}`);
+      console.log(`Total Affected Files: ${impact.totalAffected}`);
+
+      if (impact.tests.length > 0) {
+        console.log('');
+        console.log(`${bold}AFFECTED TESTS (${impact.tests.length}):${reset}`);
+        for (const t of impact.tests) {
+          console.log(`  ${dim}[dist=${t.distance}]${reset} ${t.file}`);
+        }
+      }
+
+      if (impact.features.length > 0) {
+        console.log('');
+        console.log(`${bold}AFFECTED BDD FILES (${impact.features.length}):${reset}`);
+        for (const f of impact.features) {
+          console.log(`  ${dim}[dist=${f.distance}]${reset} ${f.file}`);
+        }
+      }
+
+      if (impact.code.length > 0) {
+        console.log('');
+        console.log(`${bold}AFFECTED CODE (${impact.code.length}):${reset}`);
+        const displayCode = impact.code.slice(0, 10);
+        for (const c of displayCode) {
+          console.log(`  ${dim}[dist=${c.distance}]${reset} ${c.file}`);
+        }
+        if (impact.code.length > 10) {
+          console.log(`  ${dim}... and ${impact.code.length - 10} more${reset}`);
+        }
+      }
+
+      console.log('');
+      console.log('═'.repeat(60));
+      console.log('');
+
+    } catch (err) {
+      console.error(`❌ Error: ${err.message}`);
+      process.exit(1);
+    }
+    break;
+  }
+
   default:
     // Smart mode: auto-initialize if needed, otherwise show guidance
     if (!fs.existsSync('.jettypod')) {

package/lib/chore-classifier.js

@@ -0,0 +1,232 @@
+/**
+ * Chore Classifier
+ *
+ * Classifies chore type from title/description using keyword matching.
+ * Maps to the 4 chore types defined in chore-taxonomy.js
+ */
+
+const { CHORE_TYPES, isValidChoreType } = require('./chore-taxonomy');
+
+// Keywords that indicate each chore type
+const TYPE_KEYWORDS = {
+  [CHORE_TYPES.REFACTOR]: [
+    'refactor',
+    'restructure',
+    'reorganize',
+    'extract',
+    'inline',
+    'rename',
+    'move',
+    'split',
+    'consolidate',
+    'simplify',
+    'decouple',
+    'modularize'
+  ],
+  [CHORE_TYPES.DEPENDENCY]: [
+    'update',
+    'upgrade',
+    'bump',
+    'migrate',
+    'dependency',
+    'dependencies',
+    'package',
+    'library',
+    'framework',
+    'version',
+    'security patch',
+    'vulnerability',
+    'npm',
+    'yarn',
+    'lodash',
+    'react',
+    'node'
+  ],
+  [CHORE_TYPES.CLEANUP]: [
+    'cleanup',
+    'clean up',
+    'remove',
+    'delete',
+    'deprecate',
+    'dead code',
+    'unused',
+    'legacy',
+    'obsolete',
+    'prune',
+    'trim'
+  ],
+  [CHORE_TYPES.TOOLING]: [
+    'tooling',
+    'ci',
+    'cd',
+    'pipeline',
+    'build',
+    'lint',
+    'eslint',
+    'prettier',
+    'config',
+    'configuration',
+    'script',
+    'automation',
+    'github action',
+    'workflow',
+    'jest',
+    'test setup'
+  ]
+};
+
+/**
+ * Normalize and validate input text
+ * @param {string} title - The chore title
+ * @param {string} [description] - Optional description
+ * @returns {string} - Normalized text for classification
+ * @throws {Error} - If title is invalid
+ */
+function normalizeInput(title, description = '') {
+  // Validate title
+  if (title === null || title === undefined) {
+    throw new Error('Chore title is required for classification');
+  }
+  if (typeof title !== 'string') {
+    throw new Error(`Chore title must be a string, got ${typeof title}`);
+  }
+
+  const trimmedTitle = title.trim();
+  if (trimmedTitle.length === 0) {
+    throw new Error('Chore title cannot be empty or whitespace only');
+  }
+
+  // Normalize description (coerce to string if not)
+  const normalizedDesc = description != null ? String(description).trim() : '';
+
+  return `${trimmedTitle} ${normalizedDesc}`.toLowerCase();
+}
+
+/**
+ * Escape special regex characters in a string
+ * @param {string} str - String to escape
+ * @returns {string} - Escaped string safe for regex
+ */
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Calculate scores for all chore types
+ * @param {string} text - Normalized text to analyze
+ * @returns {Object} - Scores for each type
+ */
+function calculateScores(text) {
+  const scores = {};
+  for (const [type, keywords] of Object.entries(TYPE_KEYWORDS)) {
+    scores[type] = 0;
+    for (const keyword of keywords) {
+      if (text.includes(keyword.toLowerCase())) {
+        // Exact word match scores higher (escape special chars for safety)
+        const escapedKeyword = escapeRegex(keyword);
+        const wordBoundaryRegex = new RegExp(`\\b${escapedKeyword}\\b`, 'i');
+        if (wordBoundaryRegex.test(text)) {
+          scores[type] += 2;
+        } else {
+          scores[type] += 1;
+        }
+      }
+    }
+  }
+  return scores;
+}
+
+/**
+ * Find the winning type from scores
+ * @param {Object} scores - Scores for each type
+ * @returns {Object} - { type: string, score: number }
+ */
+function findWinningType(scores) {
+  let maxScore = 0;
+  let classifiedType = CHORE_TYPES.REFACTOR; // Default fallback
+
+  for (const [type, score] of Object.entries(scores)) {
+    if (score > maxScore) {
+      maxScore = score;
+      classifiedType = type;
+    }
+  }
+
+  return { type: classifiedType, score: maxScore };
+}
+
+/**
+ * Classify a chore based on its title (and optionally description)
+ * @param {string} title - The chore title
+ * @param {string} [description] - Optional description for additional context
+ * @returns {string} - One of the 4 chore types
+ * @throws {Error} - If title is invalid
+ */
+function classifyChoreType(title, description = '') {
+  const text = normalizeInput(title, description);
+  const scores = calculateScores(text);
+  const { type } = findWinningType(scores);
+  return type;
+}
+
+/**
+ * Determine confidence level based on score
+ * @param {number} score - The classification score
+ * @returns {string} - 'high', 'medium', or 'low'
+ */
+function getConfidenceLevel(score) {
+  if (score >= 4) return 'high';
+  if (score >= 2) return 'medium';
+  return 'low';
+}
+
+/**
+ * Get confidence level for a classification
+ * @param {string} title - The chore title
+ * @param {string} [description] - Optional description
+ * @returns {object} - { type: string, confidence: 'high'|'medium'|'low', score: number }
+ * @throws {Error} - If title is invalid
+ */
+function classifyWithConfidence(title, description = '') {
+  const text = normalizeInput(title, description);
+  const scores = calculateScores(text);
+  const { type, score } = findWinningType(scores);
+  const confidence = getConfidenceLevel(score);
+
+  return { type, confidence, score };
+}
+
+/**
+ * Get detailed classification with all type scores
+ * Useful for debugging or when needing transparency in classification
+ * @param {string} title - The chore title
+ * @param {string} [description] - Optional description
+ * @returns {object} - { type, confidence, score, allScores }
+ * @throws {Error} - If title is invalid
+ */
+function classifyWithDetails(title, description = '') {
+  const text = normalizeInput(title, description);
+  const scores = calculateScores(text);
+  const { type, score } = findWinningType(scores);
+  const confidence = getConfidenceLevel(score);
+
+  return {
+    type,
+    confidence,
+    score,
+    allScores: scores
+  };
+}
+
+module.exports = {
+  classifyChoreType,
+  classifyWithConfidence,
+  classifyWithDetails,
+  TYPE_KEYWORDS,
+  // Expose helpers for testing
+  normalizeInput,
+  escapeRegex,
+  calculateScores,
+  findWinningType,
+  getConfidenceLevel
+};

package/lib/chore-taxonomy.js

@@ -0,0 +1,172 @@
+/**
+ * Chore Type Taxonomy
+ * Defines the 4 chore types and their workflow guidance for the chore-planning and chore-mode skills.
+ */
+
+/**
+ * Chore types
+ * @constant {Object}
+ */
+const CHORE_TYPES = Object.freeze({
+  REFACTOR: 'refactor',
+  DEPENDENCY: 'dependency',
+  CLEANUP: 'cleanup',
+  TOOLING: 'tooling'
+});
+
+/**
+ * Valid chore type values as array
+ * @constant {Array<string>}
+ */
+const VALID_CHORE_TYPES = Object.freeze(Object.values(CHORE_TYPES));
+
+/**
+ * Guidance for each chore type
+ * @constant {Object}
+ */
+const CHORE_TYPE_GUIDANCE = Object.freeze({
+  [CHORE_TYPES.REFACTOR]: {
+    scope: [
+      'Define clear boundaries - what code is being restructured',
+      'Identify all callers/dependents of code being changed',
+      'Ensure behavior remains unchanged (refactor, not rewrite)',
+      'Consider breaking into smaller refactors if scope is large'
+    ],
+    verification: [
+      'All existing tests pass without modification',
+      'No new functionality added (that requires new tests)',
+      'Code review confirms behavior preservation',
+      'Performance is not degraded'
+    ],
+    testHandling: {
+      required: true,
+      approach: 'Run all tests for affected modules before and after. Update test file paths/imports if moved. Do NOT change test assertions - if tests fail, the refactor broke behavior.'
+    }
+  },
+  [CHORE_TYPES.DEPENDENCY]: {
+    scope: [
+      'Identify which packages are being updated',
+      'Check changelogs for breaking changes',
+      'Note any deprecated APIs that need migration',
+      'Consider update strategy: one at a time vs batch'
+    ],
+    verification: [
+      'All tests pass after update',
+      'Application builds successfully',
+      'No new deprecation warnings (or documented)',
+      'Security vulnerabilities addressed (if security update)'
+    ],
+    testHandling: {
+      required: false,
+      approach: 'Run full test suite to catch regressions. No new tests needed unless migrating to new API patterns. Document any test changes needed due to library API changes.'
+    }
+  },
+  [CHORE_TYPES.CLEANUP]: {
+    scope: [
+      'Define what is being cleaned (dead code, unused files, etc.)',
+      'Verify code is actually unused (grep for references)',
+      'Set clear boundaries to avoid scope creep',
+      'Consider impact on git history/blame'
+    ],
+    verification: [
+      'All tests still pass',
+      'No broken imports or references',
+      'Application runs correctly',
+      'Removed code was actually unused'
+    ],
+    testHandling: {
+      required: false,
+      approach: 'Run existing tests to ensure nothing breaks. Remove tests only if they test deleted code. No new tests needed for cleanup work.'
+    }
+  },
+  [CHORE_TYPES.TOOLING]: {
+    scope: [
+      'Define what tooling is being changed (CI, build, dev environment)',
+      'Document current behavior before changes',
+      'Consider impact on team workflows',
+      'Plan rollback strategy if changes cause issues'
+    ],
+    verification: [
+      'CI pipeline passes',
+      'Build completes successfully',
+      'Dev environment works for all team members',
+      'No regression in build times or developer experience'
+    ],
+    testHandling: {
+      required: false,
+      approach: 'Verify tooling changes work via manual testing or CI runs. Add integration tests only if tooling is complex. Focus on verification over unit testing for infrastructure.'
+    }
+  }
+});
+
+/**
+ * Normalize a chore type string (lowercase, trimmed)
+ * @param {string} type - Type to normalize
+ * @returns {string|null} Normalized type or null if input is invalid
+ */
+function normalizeChoreType(type) {
+  if (type === null || type === undefined) {
+    return null;
+  }
+  if (typeof type !== 'string') {
+    return null;
+  }
+  return type.toLowerCase().trim();
+}
+
+/**
+ * Check if a chore type is valid (case-insensitive)
+ * @param {string} type - Type to validate
+ * @returns {boolean} True if type is valid
+ */
+function isValidChoreType(type) {
+  const normalized = normalizeChoreType(type);
+  if (normalized === null) {
+    return false;
+  }
+  return VALID_CHORE_TYPES.includes(normalized);
+}
+
+/**
+ * Get guidance for a chore type
+ * @param {string} type - Chore type (case-insensitive)
+ * @returns {Object} Guidance object with scope, verification, and testHandling
+ * @throws {Error} If type is null, undefined, or invalid
+ */
+function getGuidance(type) {
+  if (type === null || type === undefined) {
+    throw new Error(
+      'Chore type is required. Valid types: refactor, dependency, cleanup, tooling'
+    );
+  }
+
+  const normalized = normalizeChoreType(type);
+
+  if (!normalized || !VALID_CHORE_TYPES.includes(normalized)) {
+    throw new Error(
+      `Invalid chore type: "${type}". Valid types: refactor, dependency, cleanup, tooling`
+    );
+  }
+
+  return CHORE_TYPE_GUIDANCE[normalized];
+}
+
+/**
+ * Get all chore types
+ * @returns {Array<string>} Array of valid chore types
+ */
+function getChoreTypes() {
+  return [...VALID_CHORE_TYPES];
+}
+
+module.exports = {
+  CHORE_TYPES,
+  VALID_CHORE_TYPES,
+  CHORE_TYPE_GUIDANCE,
+  normalizeChoreType,
+  isValidChoreType,
+  getGuidance,
+  getChoreTypes,
+  // Alias for step definitions
+  types: CHORE_TYPES
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jettypod",
-  "version": "4.4.0",
+  "version": "4.4.2",
   "description": "AI-powered development workflow manager with TDD, BDD, and automatic test generation",
   "main": "jettypod.js",
   "bin": {