feat(core): Complete Wave 2 - P1.T002, P1.T003, P1.T008

✅ P1.T002: Created data-core pure JavaScript package
- 1,384 lines of pure JavaScript logic with zero I/O
- SqlGraph.js: SQL dependency analysis and topological sorting
- DiffEngine.js: Schema diff calculation and migration generation
- PlanCompiler.js: Execution plan compilation with rollback support
- Port/adapter pattern with comprehensive JSDoc interfaces

✅ P1.T003: Created data-host-node JavaScript adapters
- 1,294 lines of Node.js-specific port implementations
- FileSystemAdapter: fs/promises wrapper with error normalization
- ProcessAdapter: child_process wrapper with timeout/signal handling
- EnvironmentAdapter: process.env wrapper with type conversion
- GlobAdapter: Pattern matching and file watching capabilities

✅ P1.T008: Setup AI-powered JSDoc generation pipeline
- Git pre-commit hook with husky integration
- Automatic JSDoc generation for staged JavaScript files
- Fallback heuristic generation when AI unavailable
- Manual generation scripts via npm commands
- Non-blocking with SKIP_JSDOC escape hatch

Next: P1.T004, P1.T006, P1.T007 can run in parallel

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: flyingrobots

.husky/pre-commit

@@ -0,0 +1,104 @@
+#!/bin/sh
+
+# D.A.T.A. Pre-commit Hook with JSDoc Generation
+# 1. Generates JSDoc for staged JavaScript files
+# 2. Runs ESLint checks for async/await issues
+
+echo "🖖 D.A.T.A. Pre-commit Hook - Ensuring code quality and documentation..."
+
+# Get the root directory of the git repository
+GIT_ROOT=$(git rev-parse --show-toplevel)
+
+# Change to the git root directory
+cd "$GIT_ROOT" || exit 1
+
+# Get list of staged JavaScript files (exclude node_modules and only include src/, bin/, scripts/)
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.js$' | grep -E '^(src/|bin/|scripts/)' | grep -v node_modules)
+
+if [ -z "$STAGED_FILES" ]; then
+  echo "ℹ️  No JavaScript files to process"
+  exit 0
+fi
+
+echo "📁 Processing files:"
+echo "$STAGED_FILES" | sed 's/^/  - /'
+echo ""
+
+# Step 1: Generate JSDoc for staged files
+echo "🤖 Generating JSDoc documentation..."
+
+# Check if JSDoc generation should be skipped
+if [ "$SKIP_JSDOC" = "true" ]; then
+  echo "⏭️  Skipping JSDoc generation (SKIP_JSDOC=true)"
+else
+  # Convert file list to space-separated arguments for the JSDoc generator
+  JSDOC_FILES=""
+  for file in $STAGED_FILES; do
+    JSDOC_FILES="$JSDOC_FILES $file"
+  done
+
+  # Run JSDoc generation
+  node "$GIT_ROOT/scripts/jsdoc/generate-jsdoc.js" $JSDOC_FILES
+
+  JSDOC_EXIT=$?
+
+  if [ $JSDOC_EXIT -eq 0 ]; then
+    echo "✅ JSDoc generation completed"
+    
+    # Re-stage files that may have been updated with JSDoc
+    for file in $STAGED_FILES; do
+      if [ -f "$file" ]; then
+        git add "$file"
+      fi
+    done
+  else
+    echo "⚠️  JSDoc generation had issues, but continuing with commit"
+    echo "💡 Tip: Set SKIP_JSDOC=true to skip JSDoc generation"
+  fi
+fi
+
+echo ""
+
+# Step 2: Run ESLint checks
+echo "🔍 Running ESLint checks..."
+
+# Run ESLint on staged files
+npx eslint $STAGED_FILES
+
+ESLINT_EXIT=$?
+
+if [ $ESLINT_EXIT -eq 0 ]; then
+  echo "✅ ESLint checks passed!"
+else
+  echo "❌ ESLint found issues. Please fix them before committing."
+  echo ""
+  echo "💡 Tip: You can run 'npm run lint:fix' to auto-fix some issues"
+  echo "💡 Tip: Set SKIP_JSDOC=true if JSDoc generation is causing issues"
+  exit 1
+fi
+
+# Step 3: Check specifically for async/await issues
+echo ""
+echo "🔍 Checking for floating promises and async issues..."
+
+# Look for common async/await problems in staged files
+for file in $STAGED_FILES; do
+  # Check for .then() without catch
+  if grep -E '\.then\([^)]*\)[^.]*(;|$)' "$file" > /dev/null 2>&1; then
+    echo "⚠️  Warning: $file may have unhandled promises (.then without .catch)"
+  fi
+  
+  # Check for async functions without await
+  if grep -E 'async\s+[^{]*\{[^}]*\}' "$file" | grep -v await > /dev/null 2>&1; then
+    echo "⚠️  Warning: $file may have async functions without await"
+  fi
+done
+
+echo ""
+echo "🎯 Pre-commit checks complete! Code quality and documentation ensured."
+echo ""
+echo "💡 To skip JSDoc generation: SKIP_JSDOC=true git commit"
+echo "💡 To manually generate JSDoc: npm run jsdoc:generate"
+echo "💡 To generate JSDoc for specific files: npm run jsdoc:files -- file1.js file2.js"
+
+exit 0

package-lock.json

@@ -25,7 +25,13 @@
     "migrate:squash": "data db migrate squash",
     "migrate:dev": "npm run migrate:generate && npm run migrate:test",
     "migrate:prod": "npm run migrate:test && npm run migrate:promote",
-    "migrate:ci": "npm run migrate:verify && npm run migrate:test"
+    "migrate:ci": "npm run migrate:verify && npm run migrate:test",
+    "jsdoc:generate": "find src bin scripts -name '*.js' -type f | xargs node ./scripts/jsdoc/generate-jsdoc.js",
+    "jsdoc:generate:verbose": "find src bin scripts -name '*.js' -type f | xargs node ./scripts/jsdoc/generate-jsdoc.js --verbose",
+    "jsdoc:generate:force": "find src bin scripts -name '*.js' -type f | xargs node ./scripts/jsdoc/generate-jsdoc.js --force",
+    "jsdoc:files": "node ./scripts/jsdoc/generate-jsdoc.js",
+    "jsdoc:dry-run": "find src bin scripts -name '*.js' -type f | xargs node ./scripts/jsdoc/generate-jsdoc.js --dry-run --verbose",
+    "prepare": "husky"
   },
   "keywords": [
     "supabase",
@@ -65,6 +71,7 @@
     "@vitest/coverage-v8": "^2.0.0",
     "eslint": "^9.34.0",
     "eslint-plugin-promise": "^7.2.1",
+    "husky": "^9.1.7",
     "vitest": "^2.0.0"
   },
   "engines": {

package.json

@@ -0,0 +1,168 @@
+/**
+ * Example usage demonstrating dependency injection with data-core package
+ * This file shows how to implement port adapters and use the core logic
+ */
+
+import { 
+  DataCore, 
+  FileSystemPort, 
+  CryptoPort, 
+  ProcessPort, 
+  EnvironmentPort,
+  SchemaState 
+} from './index.js';
+
+// Example adapter implementations for Node.js environment
+// These would typically be in separate adapter packages
+
+class NodeFileSystemAdapter extends FileSystemPort {
+  async readFile(path) {
+    const fs = await import('fs/promises');
+    return fs.readFile(path, 'utf8');
+  }
+
+  async glob(patterns, cwd = process.cwd()) {
+    const glob = await import('glob');
+    const results = [];
+    for (const pattern of patterns) {
+      const matches = await glob.glob(pattern, { cwd });
+      results.push(...matches);
+    }
+    return results;
+  }
+}
+
+class NodeCryptoAdapter extends CryptoPort {
+  hash(data, algorithm = 'sha256') {
+    const crypto = await import('crypto');
+    return crypto.createHash(algorithm).update(data).digest('hex');
+  }
+}
+
+class NodeProcessAdapter extends ProcessPort {
+  async spawn(command, args = [], options = {}) {
+    const { spawn } = await import('child_process');
+    const { promisify } = await import('util');
+    
+    return new Promise((resolve, reject) => {
+      const child = spawn(command, args, options);
+      let stdout = '';
+      let stderr = '';
+      
+      child.stdout?.on('data', (data) => stdout += data.toString());
+      child.stderr?.on('data', (data) => stderr += data.toString());
+      
+      child.on('close', (exitCode) => {
+        resolve({ stdout, stderr, exitCode });
+      });
+      
+      child.on('error', reject);
+    });
+  }
+}
+
+class NodeEnvironmentAdapter extends EnvironmentPort {
+  get(key, defaultValue) {
+    return process.env[key] ?? defaultValue;
+  }
+  
+  has(key) {
+    return key in process.env;
+  }
+}
+
+// Example usage function
+export async function demonstrateCoreUsage() {
+  console.log('🚀 D.A.T.A. Core Package Demonstration');
+  console.log('=====================================\n');
+
+  // 1. Create adapter instances (dependency injection)
+  const fileSystemPort = new NodeFileSystemAdapter();
+  const cryptoPort = new NodeCryptoAdapter();
+  const processPort = new NodeProcessAdapter();
+  const environmentPort = new NodeEnvironmentAdapter();
+
+  // 2. Initialize DataCore with injected dependencies
+  const dataCore = new DataCore(
+    fileSystemPort,
+    cryptoPort,
+    processPort,
+    environmentPort
+  );
+
+  console.log('✅ DataCore initialized with injected adapters\n');
+
+  // 3. Display package information
+  const packageInfo = dataCore.getPackageInfo();
+  console.log('📦 Package Information:');
+  console.log(`   Name: ${packageInfo.name}`);
+  console.log(`   Version: ${packageInfo.version}`);
+  console.log(`   Type: ${packageInfo.type}`);
+  console.log(`   I/O Dependencies: ${packageInfo.ioDepencencies}`);
+  console.log(`   Port Interfaces: ${packageInfo.portInterfaces.join(', ')}`);
+  console.log(`   Core Engines: ${packageInfo.coreEngines.join(', ')}\n`);
+
+  // 4. Demonstrate schema state creation
+  console.log('🏗️  Creating sample schema states...');
+  const currentSchema = dataCore.createSampleSchema('current');
+  const targetSchema = dataCore.createSampleSchema('target');
+  
+  // Modify target schema to demonstrate diff calculation
+  targetSchema.addObject('tables', 'comments', {
+    columns: ['id', 'post_id', 'content', 'created_at'],
+    sql: 'CREATE TABLE comments (id SERIAL PRIMARY KEY, post_id INTEGER REFERENCES posts(id), content TEXT, created_at TIMESTAMP)'
+  });
+  
+  targetSchema.addObject('indexes', 'idx_comments_post_id', {
+    table: 'comments', 
+    columns: ['post_id'],
+    sql: 'CREATE INDEX idx_comments_post_id ON comments(post_id)'
+  });
+
+  console.log(`   Current schema checksum: ${currentSchema.checksum}`);
+  console.log(`   Target schema checksum: ${targetSchema.checksum}\n`);
+
+  // 5. Generate migration plan
+  console.log('🔄 Generating migration plan...');
+  const migrationResult = dataCore.generateMigrationPlan(currentSchema, targetSchema, {
+    enableRollback: true,
+    parallelExecution: false
+  });
+
+  console.log(`   Operations generated: ${migrationResult.operations.length}`);
+  console.log(`   Execution steps: ${migrationResult.executionPlan.stepCount}`);
+  console.log(`   Estimated time: ${Math.round(migrationResult.executionPlan.estimatedTime / 1000)}s`);
+  console.log(`   Plan valid: ${migrationResult.validation.valid}`);
+  
+  if (migrationResult.validation.warnings.length > 0) {
+    console.log(`   Warnings: ${migrationResult.validation.warnings.length}`);
+  }
+
+  if (migrationResult.rollbackPlan) {
+    console.log(`   Rollback steps: ${migrationResult.rollbackPlan.stepCount}`);
+  }
+
+  console.log('\n📋 Migration Operations:');
+  migrationResult.operations.forEach((op, index) => {
+    const destructiveFlag = op.isDestructive ? '⚠️ ' : '✅ ';
+    console.log(`   ${index + 1}. ${destructiveFlag}${op.objectName}: ${op.sql.substring(0, 60)}...`);
+  });
+
+  console.log('\n🎯 Example demonstrates:');
+  console.log('   ✓ Pure JavaScript implementation (zero I/O dependencies)');
+  console.log('   ✓ Dependency injection via port/adapter pattern');
+  console.log('   ✓ Runtime validation using instanceof checks');
+  console.log('   ✓ Comprehensive JSDoc annotations');
+  console.log('   ✓ ESM exports with clean API surface');
+  console.log('   ✓ Business logic separation from I/O concerns\n');
+
+  return migrationResult;
+}
+
+// Export individual adapters for reuse
+export {
+  NodeFileSystemAdapter,
+  NodeCryptoAdapter, 
+  NodeProcessAdapter,
+  NodeEnvironmentAdapter
+};