@kb-labs/devkit 1.0.0

package/bin/devkit-check-types.mjs

@@ -0,0 +1,450 @@
+#!/usr/bin/env node
+
+/**
+ * @kb-labs/devkit - TypeScript Types Checker
+ *
+ * Ensures all packages properly generate TypeScript declaration files (.d.ts).
+ * Detects technical debt like `dts: false` in tsup configs.
+ *
+ * Usage:
+ *   kb-devkit-check-types                 # Check all packages
+ *   kb-devkit-check-types --package=cli   # Check specific package
+ *   kb-devkit-check-types --fix           # Auto-fix dts: false
+ *   kb-devkit-check-types --json          # JSON output
+ *   kb-devkit-check-types --graph         # Show types dependency graph
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// ANSI colors
+const colors = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  gray: '\x1b[90m',
+  bold: '\x1b[1m',
+};
+
+function log(message, color = 'reset') {
+  if (!options.json) {
+    console.log(`${colors[color]}${message}${colors.reset}`);
+  }
+}
+
+// Parse CLI arguments
+const args = process.argv.slice(2);
+const options = {
+  fix: args.includes('--fix'),
+  json: args.includes('--json'),
+  graph: args.includes('--graph'),
+  verbose: args.includes('--verbose') || args.includes('-v'),
+  package: args.find((arg) => arg.startsWith('--package='))?.split('=')[1],
+};
+
+/**
+ * Find all packages
+ */
+function findPackages(rootDir, filterPackage) {
+  const packages = [];
+  const entries = fs.readdirSync(rootDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !entry.name.startsWith('kb-labs-')) {continue;}
+
+    const repoPath = path.join(rootDir, entry.name);
+    const packagesDir = path.join(repoPath, 'packages');
+
+    if (!fs.existsSync(packagesDir)) {continue;}
+
+    const packageDirs = fs.readdirSync(packagesDir, { withFileTypes: true });
+
+    for (const pkgDir of packageDirs) {
+      if (!pkgDir.isDirectory()) {continue;}
+
+      if (filterPackage && pkgDir.name !== filterPackage) {continue;}
+
+      const packageJsonPath = path.join(packagesDir, pkgDir.name, 'package.json');
+
+      if (fs.existsSync(packageJsonPath)) {
+        packages.push({
+          path: packageJsonPath,
+          dir: path.join(packagesDir, pkgDir.name),
+        });
+      }
+    }
+  }
+
+  return packages;
+}
+
+/**
+ * Check if package has TypeScript source files
+ */
+function hasTypeScriptSources(packageDir) {
+  const srcDir = path.join(packageDir, 'src');
+  if (!fs.existsSync(srcDir)) {return false;}
+
+  function walkDir(dir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        if (walkDir(fullPath)) {return true;}
+      } else if (entry.isFile() && /\.(ts|tsx)$/.test(entry.name)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  return walkDir(srcDir);
+}
+
+/**
+ * Check tsup.config for dts setting
+ */
+function checkTsupConfig(packageDir) {
+  const tsupConfigPath = path.join(packageDir, 'tsup.config.ts');
+
+  if (!fs.existsSync(tsupConfigPath)) {
+    return { exists: false };
+  }
+
+  const content = fs.readFileSync(tsupConfigPath, 'utf-8');
+
+  // Check for dts: false (bad!)
+  const hasDtsFalse = /dts\s*:\s*false/.test(content);
+
+  // Check for dts: true (good!)
+  const hasDtsTrue = /dts\s*:\s*true/.test(content);
+
+  // Check if dts is explicitly set
+  const hasDtsConfig = /dts\s*:/.test(content);
+
+  return {
+    exists: true,
+    path: tsupConfigPath,
+    content,
+    hasDtsFalse,
+    hasDtsTrue,
+    hasDtsConfig,
+  };
+}
+
+/**
+ * Check if package.json has types field
+ */
+function checkPackageJsonTypes(packagePath) {
+  const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf-8'));
+
+  return {
+    name: packageJson.name,
+    hasTypes: !!packageJson.types || !!packageJson.typings,
+    typesPath: packageJson.types || packageJson.typings,
+    hasExports: !!packageJson.exports,
+  };
+}
+
+/**
+ * Check if dist folder has .d.ts files
+ */
+function checkDistFolder(packageDir) {
+  const distDir = path.join(packageDir, 'dist');
+
+  if (!fs.existsSync(distDir)) {
+    return { exists: false, hasDts: false };
+  }
+
+  function hasDtsFiles(dir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        if (hasDtsFiles(fullPath)) {return true;}
+      } else if (entry.isFile() && entry.name.endsWith('.d.ts')) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  return {
+    exists: true,
+    hasDts: hasDtsFiles(distDir),
+  };
+}
+
+/**
+ * Fix dts: false in tsup config
+ */
+function fixTsupConfig(tsupConfigPath, dryRun = false) {
+  const content = fs.readFileSync(tsupConfigPath, 'utf-8');
+
+  // Replace dts: false with dts: true
+  const fixed = content.replace(/dts\s*:\s*false/g, 'dts: true');
+
+  if (fixed !== content) {
+    if (!dryRun) {
+      fs.writeFileSync(tsupConfigPath, fixed);
+    }
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Check single package
+ */
+function checkPackage(packageInfo) {
+  const { path: packagePath, dir: packageDir } = packageInfo;
+  const packageJson = checkPackageJsonTypes(packagePath);
+  const packageName = packageJson.name;
+
+  if (!packageName || !packageName.startsWith('@kb-labs/')) {
+    return null;
+  }
+
+  const hasTS = hasTypeScriptSources(packageDir);
+  const tsupConfig = checkTsupConfig(packageDir);
+  const dist = checkDistFolder(packageDir);
+
+  const issues = [];
+
+  // TypeScript sources but no tsup config
+  if (hasTS && !tsupConfig.exists) {
+    issues.push({
+      type: 'no_tsup_config',
+      severity: 'warning',
+      message: 'Has TypeScript sources but no tsup.config.ts',
+    });
+  }
+
+  // tsup config with dts: false (technical debt!)
+  if (tsupConfig.hasDtsFalse) {
+    issues.push({
+      type: 'dts_false',
+      severity: 'error',
+      message: 'tsup.config.ts has dts: false (bad practice!)',
+      fixable: true,
+    });
+  }
+
+  // Has TypeScript but no dts config at all
+  if (hasTS && tsupConfig.exists && !tsupConfig.hasDtsConfig) {
+    issues.push({
+      type: 'no_dts_config',
+      severity: 'warning',
+      message: 'tsup.config.ts missing dts configuration',
+    });
+  }
+
+  // Has TypeScript but package.json has no types field
+  if (hasTS && !packageJson.hasTypes) {
+    issues.push({
+      type: 'no_types_field',
+      severity: 'error',
+      message: 'package.json missing "types" field',
+    });
+  }
+
+  // Has tsup with dts: true but no .d.ts files in dist
+  if (tsupConfig.hasDtsTrue && dist.exists && !dist.hasDts) {
+    issues.push({
+      type: 'no_dist_types',
+      severity: 'warning',
+      message: 'No .d.ts files found in dist/ (need to build?)',
+    });
+  }
+
+  return {
+    name: packageName,
+    dir: packageDir,
+    hasTypeScript: hasTS,
+    tsupConfig,
+    dist,
+    packageJson,
+    issues,
+    isClean: issues.length === 0,
+  };
+}
+
+/**
+ * Print results
+ */
+function printResults(results) {
+  log('\n🔍 KB Labs TypeScript Types Checker\n', 'bold');
+
+  const allPackages = results.filter(r => r !== null);
+  const withIssues = allPackages.filter(r => !r.isClean);
+  const dtsFalse = allPackages.filter(r => r.issues.some(i => i.type === 'dts_false'));
+  const clean = allPackages.filter(r => r.isClean && r.hasTypeScript);
+
+  log(`Found ${allPackages.length} package(s) to check\n`, 'gray');
+
+  // Show packages with dts: false (technical debt!)
+  if (dtsFalse.length > 0) {
+    log(`🔴 Technical Debt: ${dtsFalse.length} package(s) with dts: false\n`, 'red');
+
+    for (const result of dtsFalse) {
+      log(`   ${result.name}`, 'yellow');
+      log(`      ${result.tsupConfig.path}`, 'gray');
+      log(`      └─ Has "dts: false" - types not being generated!`, 'red');
+
+      if (options.fix) {
+        const fixed = fixTsupConfig(result.tsupConfig.path, false);
+        if (fixed) {
+          log(`      ✅ Fixed: Changed to "dts: true"`, 'green');
+        }
+      }
+    }
+    log('', 'reset');
+
+    if (!options.fix) {
+      log('💡 Run with --fix to automatically change dts: false → dts: true\n', 'cyan');
+    }
+  }
+
+  // Show other issues
+  const otherIssues = withIssues.filter(r => !r.issues.some(i => i.type === 'dts_false'));
+
+  if (otherIssues.length > 0) {
+    log(`⚠️  Other Issues: ${otherIssues.length} package(s)\n`, 'yellow');
+
+    for (const result of otherIssues) {
+      log(`   ${result.name}`, 'yellow');
+
+      for (const issue of result.issues) {
+        const icon = issue.severity === 'error' ? '❌' : '⚠️';
+        log(`      ${icon} ${issue.message}`, 'gray');
+      }
+    }
+    log('', 'reset');
+  }
+
+  // Show clean packages (only in verbose mode)
+  if (options.verbose && clean.length > 0) {
+    log(`✅ Clean packages with types: ${clean.length}\n`, 'green');
+
+    for (const result of clean.slice(0, 10)) {
+      log(`   ${result.name}`, 'gray');
+    }
+
+    if (clean.length > 10) {
+      log(`   ... and ${clean.length - 10} more`, 'gray');
+    }
+    log('', 'reset');
+  }
+
+  // Summary
+  log('─'.repeat(60) + '\n', 'gray');
+  log('📊 Summary:\n', 'blue');
+
+  log(`   Total packages:       ${allPackages.length}`, 'cyan');
+  log(`   With TypeScript:      ${allPackages.filter(r => r.hasTypeScript).length}`, 'cyan');
+  log(`   ✅ Clean:             ${clean.length}`, 'green');
+
+  if (dtsFalse.length > 0) {
+    log(`   🔴 dts: false:        ${dtsFalse.length} (technical debt!)`, 'red');
+  }
+  if (otherIssues.length > 0) {
+    log(`   ⚠️  Other issues:      ${otherIssues.length}`, 'yellow');
+  }
+
+  log('', 'reset');
+
+  // Tips
+  log('💡 Tips:', 'blue');
+  log('   • Use --fix to automatically fix dts: false', 'gray');
+  log('   • Use --verbose to see all packages', 'gray');
+  log('   • Run pnpm run build after fixing configs', 'gray');
+  log('', 'reset');
+}
+
+/**
+ * Build types dependency graph
+ */
+function buildTypesDependencyGraph(results) {
+  const graph = new Map();
+
+  // Build graph of packages that provide types
+  for (const result of results) {
+    if (!result || !result.hasTypeScript) {continue;}
+
+    const hasTypes = result.tsupConfig.hasDtsTrue && !result.issues.some(i => i.type === 'dts_false');
+
+    graph.set(result.name, {
+      hasTypes,
+      issues: result.issues.length,
+    });
+  }
+
+  return graph;
+}
+
+/**
+ * Main function
+ */
+function main() {
+  const rootDir = process.cwd();
+
+  if (!options.json) {
+    log('\n🚀 KB Labs TypeScript Types Checker\n', 'bold');
+  }
+
+  const packages = findPackages(rootDir, options.package);
+
+  if (packages.length === 0) {
+    log('⚠️  No KB Labs packages found', 'yellow');
+    process.exit(0);
+  }
+
+  // Check all packages
+  const results = packages.map(checkPackage);
+
+  if (options.json) {
+    const output = {
+      total: results.filter(r => r !== null).length,
+      withTypeScript: results.filter(r => r && r.hasTypeScript).length,
+      clean: results.filter(r => r && r.isClean && r.hasTypeScript).length,
+      dtsFalse: results.filter(r => r && r.issues.some(i => i.type === 'dts_false')).length,
+      issues: results.filter(r => r && !r.isClean).map(r => ({
+        name: r.name,
+        issues: r.issues,
+      })),
+    };
+
+    console.log(JSON.stringify(output, null, 2));
+  } else if (options.graph) {
+    const graph = buildTypesDependencyGraph(results);
+    log('\n📊 Types Dependency Graph\n', 'blue');
+
+    for (const [pkg, info] of graph.entries()) {
+      const status = info.hasTypes ? '✅' : '❌';
+      log(`${status} ${pkg}${info.issues > 0 ? ` (${info.issues} issues)` : ''}`, info.hasTypes ? 'green' : 'red');
+    }
+    log('', 'reset');
+  } else {
+    printResults(results);
+  }
+
+  // Exit with error if issues found
+  const hasIssues = results.some(r => r && !r.isClean);
+  process.exit(hasIssues ? 1 : 0);
+}
+
+main();

package/bin/devkit-ci.mjs

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+
+/**
+ * @kb-labs/devkit - CI Combo Tool
+ *
+ * Runs all devkit checks in one command for CI/CD pipelines.
+ * Perfect for GitHub Actions, GitLab CI, or any CI/CD system.
+ *
+ * Checks performed:
+ * 1. Naming convention validation
+ * 2. Import issues (broken imports, unused deps, circular deps)
+ * 3. Export issues (unused exports, dead code)
+ * 4. Duplicate dependencies
+ * 5. Package structure validation
+ * 6. Path validation (workspace deps, exports, bin)
+ * 7. TypeScript types (dts generation, types field)
+ *
+ * Usage:
+ *   kb-devkit-ci                    # Run all checks
+ *   kb-devkit-ci --skip naming      # Skip naming check
+ *   kb-devkit-ci --only imports     # Run only imports check
+ *   kb-devkit-ci --json             # Output JSON for parsing
+ */
+
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// ANSI colors
+const colors = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  gray: '\x1b[90m',
+  bold: '\x1b[1m',
+};
+
+function log(message, color = 'reset') {
+  console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+// Parse CLI arguments
+const args = process.argv.slice(2);
+const options = {
+  skip: args.find((arg) => arg.startsWith('--skip='))?.split('=')[1]?.split(',') || [],
+  only: args.find((arg) => arg.startsWith('--only='))?.split('=')[1]?.split(',') || [],
+  json: args.includes('--json'),
+  verbose: args.includes('--verbose') || args.includes('-v'),
+};
+
+/**
+ * Available checks
+ */
+const CHECKS = {
+  naming: {
+    name: 'Naming Convention',
+    command: 'devkit-validate-naming.mjs',
+    emoji: '📦',
+  },
+  imports: {
+    name: 'Import Analysis',
+    command: 'devkit-check-imports.mjs',
+    emoji: '🔍',
+  },
+  exports: {
+    name: 'Export Analysis',
+    command: 'devkit-check-exports.mjs',
+    emoji: '📤',
+  },
+  duplicates: {
+    name: 'Duplicate Dependencies',
+    command: 'devkit-check-duplicates.mjs',
+    emoji: '🔄',
+  },
+  structure: {
+    name: 'Package Structure',
+    command: 'devkit-check-structure.mjs',
+    emoji: '📐',
+  },
+  paths: {
+    name: 'Path Validation',
+    command: 'devkit-check-paths.mjs',
+    emoji: '🔗',
+  },
+  types: {
+    name: 'TypeScript Types',
+    command: 'devkit-check-types.mjs',
+    emoji: '📝',
+  },
+};
+
+/**
+ * Run a single check
+ */
+function runCheck(checkId, check) {
+  return new Promise((resolve) => {
+    const startTime = Date.now();
+    const scriptPath = path.join(__dirname, check.command);
+
+    if (!options.json) {
+      log(`\n${check.emoji} Running ${check.name}...`, 'blue');
+    }
+
+    const child = spawn('node', [scriptPath], {
+      stdio: options.json ? 'pipe' : 'inherit',
+      cwd: process.cwd(),
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    if (options.json) {
+      child.stdout.on('data', (data) => {
+        stdout += data.toString();
+      });
+      child.stderr.on('data', (data) => {
+        stderr += data.toString();
+      });
+    }
+
+    child.on('close', (code) => {
+      const duration = ((Date.now() - startTime) / 1000).toFixed(2);
+
+      resolve({
+        checkId,
+        name: check.name,
+        emoji: check.emoji,
+        passed: code === 0,
+        exitCode: code,
+        duration: parseFloat(duration),
+        stdout,
+        stderr,
+      });
+    });
+
+    child.on('error', (err) => {
+      resolve({
+        checkId,
+        name: check.name,
+        emoji: check.emoji,
+        passed: false,
+        exitCode: 1,
+        duration: 0,
+        error: err.message,
+      });
+    });
+  });
+}
+
+/**
+ * Main function
+ */
+async function main() {
+  const startTime = Date.now();
+
+  if (!options.json) {
+    log('\n🚀 KB Labs CI Checker\n', 'bold');
+    log('Running all devkit checks...\n', 'gray');
+  }
+
+  // Determine which checks to run
+  let checksToRun = Object.keys(CHECKS);
+
+  if (options.only.length > 0) {
+    checksToRun = checksToRun.filter((id) => options.only.includes(id));
+  }
+
+  if (options.skip.length > 0) {
+    checksToRun = checksToRun.filter((id) => !options.skip.includes(id));
+  }
+
+  if (checksToRun.length === 0) {
+    log('⚠️  No checks to run', 'yellow');
+    process.exit(0);
+  }
+
+  // Run all checks
+  const results = [];
+
+  for (const checkId of checksToRun) {
+    const check = CHECKS[checkId];
+    const result = await runCheck(checkId, check);
+    results.push(result);
+
+    if (!options.json) {
+      if (result.passed) {
+        log(`   ✅ ${result.name} passed (${result.duration}s)`, 'green');
+      } else {
+        log(`   ❌ ${result.name} failed (${result.duration}s)`, 'red');
+      }
+    }
+  }
+
+  const totalDuration = ((Date.now() - startTime) / 1000).toFixed(2);
+
+  // Print summary
+  const passed = results.filter((r) => r.passed).length;
+  const failed = results.filter((r) => !r.passed).length;
+  const total = results.length;
+
+  if (options.json) {
+    // JSON output for CI parsing
+    const output = {
+      summary: {
+        total,
+        passed,
+        failed,
+        duration: parseFloat(totalDuration),
+        success: failed === 0,
+      },
+      checks: results.map((r) => ({
+        id: r.checkId,
+        name: r.name,
+        passed: r.passed,
+        exitCode: r.exitCode,
+        duration: r.duration,
+        error: r.error,
+      })),
+    };
+
+    console.log(JSON.stringify(output, null, 2));
+  } else {
+    log('\n' + '─'.repeat(60) + '\n', 'gray');
+    log('📊 Summary:\n', 'blue');
+
+    log(`   Total checks:  ${total}`, 'cyan');
+    log(`   ✅ Passed:     ${passed}`, 'green');
+    if (failed > 0) {
+      log(`   ❌ Failed:     ${failed}`, 'red');
+    }
+    log(`   ⏱️  Duration:   ${totalDuration}s`, 'gray');
+
+    log('', 'reset');
+
+    if (failed > 0) {
+      log('💡 Failed checks:', 'yellow');
+      for (const result of results.filter((r) => !r.passed)) {
+        log(`   • ${result.name}`, 'red');
+      }
+      log('', 'reset');
+    }
+
+    log('💡 Tips:', 'blue');
+    log('   • Run individual checks to see detailed output', 'gray');
+    log('   • Use --skip=<check> to skip specific checks', 'gray');
+    log('   • Use --only=<check> to run only specific checks', 'gray');
+    log('   • Use --json for machine-readable output', 'gray');
+    log('', 'reset');
+  }
+
+  // Exit with appropriate code
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+main();