plankit-cli 1.4.0 → 1.6.0

package/README.md

@@ -64,6 +64,8 @@ plankit review my-feature
 | `plankit implement <feature> <phase>` | Validate phase context (spec + prior outputs) and prepare `outputs/phase-N-output.md`. |
 | `plankit review <feature>` | Run verification commands, mark README archived, and move the feature to `artifacts/archived/`. |
 | `plankit status [--json]` | List active and archived features. |
+| `plankit scan [dir] [--json] [--threshold <n>]` | Run zero-dependency static analysis, audit health (0-100), extract design tokens, and generate `artifacts/.plankit-index.json`. |
+| `plankit ui [--no-tui]` | Launch interactive terminal feature progress matrix & action dashboard. |
 | `plankit archive <feature>` | Move a feature to archived without running verification. |
 | `plankit version` / `--version` / `-v` | Print the installed version (`plankit-cli vX.Y.Z`). |
 | `plankit help` / `--help` / `-h` | Show usage. |
@@ -79,6 +81,9 @@ plankit review my-feature
 | `--agent <name>` | Select your coding agent during `init` (`opencode`, `gemini`, `codex`, `cursor`; default `opencode`). |
 | `--framework <name>` | Select framework command suite during `init` (`angular`, `vue`, `dotnet`, `none`, `all`; default `none`). |
 | `--frameworks <list>` | Comma-separated list of framework command suites (e.g. `vue,dotnet`). |
+| `--threshold <score>` | Fail `scan` command with exit code 1 if health score is below threshold (CI quality gate). |
+| `--json` | Output `scan` or `status` as machine-readable JSON. |
+| `--no-tui` | Render static ASCII table instead of interactive dashboard for `ui` command. |
 
 ### Plan options
 
@@ -164,6 +169,74 @@ plankit init --agent cursor
 
 ---
 
+## Static analysis engine (`plankit scan`)
+
+PlanKit ships with an ultra-fast, **zero-dependency static analyzer** that audits codebase modernization health without burning LLM tokens:
+
+```bash
+# Run audit and output terminal report + save artifacts/.plankit-index.json
+plankit scan
+
+# Output machine-readable JSON metrics
+plankit scan --json
+
+# CI Quality Gate: fail if health score drops below threshold
+plankit scan --threshold 80
+```
+
+### What it checks:
+- **Vue SFC Architecture**: Options API vs `<script setup>` ratio, TypeScript vs JavaScript, Pinia vs Vuex vs composables.
+- **Design Token Mining**: Automatically detects repeated hex colors, font sizes, margins, and paddings across templates and styles.
+- **.NET Architecture**: Target frameworks, layer dependency boundaries (Clean Architecture / Vertical Slices), and Minimal APIs vs Controllers.
+- **Modernization Hotspots**: Flags god components (> 400 lines), deprecated deep selectors (`::v-deep`, `/deep/`), mixins, and layer boundary violations.
+- **Index Generation**: Saves `artifacts/.plankit-index.json` so AI agents can query repository intelligence immediately.
+
+---
+
+## Interactive feature dashboard (`plankit ui`)
+
+Launch a terminal UI to visualize active features, phase completion status, and trigger development workflows with single keystrokes:
+
+```bash
+# Launch interactive TUI
+plankit ui
+
+# Non-interactive / CI ASCII table output
+plankit ui --no-tui
+```
+
+### Interactive Actions:
+- **`[↑/↓]` or `[j/k]`**: Navigate between active features.
+- **`[i]`**: Prepare and validate implementation context for the next pending phase.
+- **`[c]`**: Generate a design alignment and clarification artifact.
+- **`[r]`**: Review, verify DoD, and archive completed feature.
+- **`[s]`**: Run the repository static scan and view live health scorecard.
+- **`[q]`**: Exit dashboard.
+
+---
+
+## Visual web dashboard companion (`plankit serve`)
+
+Launch an interactive, local browser companion on your choice of port:
+
+```bash
+# Launch on default port 4200 (prompts if run interactively without flag)
+plankit serve
+
+# Specify custom port
+plankit serve --port 5000
+plankit web -p 8080
+```
+
+### Features:
+- **Feature Matrix & Progress Board**: Visual cards with completion percentages and modal document viewers for specs and outputs.
+- **Architecture Health Scorecard**: Live breakdown of Vue `<script setup>` ratio, TypeScript ratio, Pinia stores, and .NET Clean Architecture violations.
+- **Design Token Palette**: Interactive color swatches with one-click hex copying and rule usage counts mined across the repository.
+- **Hotspots Backlog**: Filterable table of god components, deprecated deep selectors, mixins, and legacy code.
+- **Zero Dependencies**: Powered by native `node:http`, starts in under 20ms.
+
+---
+
 ## Framework command suites
 
 During `plankit init`, PlanKit prompts you to choose optional framework-specific command suites (or pass `--framework <name>` / `--frameworks <names>`):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plankit-cli",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "PlanKit Command Suite CLI for AI Coding Assistants (Antigravity, OpenCode, Codex, Cursor)",
   "main": "src/cli.js",
   "bin": {

package/src/analyzer/dotnetScanner.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Fast static analyzer for .NET projects and solutions (.sln, .csproj, .cs).
+ */
+
+export function analyzeCsprojFile(filePath, content = null) {
+  const code = content !== null ? content : fs.readFileSync(filePath, 'utf8');
+  const fileName = path.basename(filePath);
+  const projectName = fileName.replace(/\.csproj$/i, '');
+
+  // Target Framework
+  const tfMatch = /<TargetFramework(?:s)?>([^<]+)<\/TargetFramework(?:s)?>/i.exec(code);
+  const targetFramework = tfMatch ? tfMatch[1].trim() : 'unknown';
+
+  // Nullable
+  const nullableMatch = /<Nullable>([^<]+)<\/Nullable>/i.exec(code);
+  const nullable = nullableMatch ? nullableMatch[1].trim().toLowerCase() === 'enable' : false;
+
+  // Project References
+  const projectReferences = [];
+  const refRegex = /<ProjectReference\s+Include=["']([^"']+)["']/gi;
+  let match;
+  while ((match = refRegex.exec(code)) !== null) {
+    const refPath = match[1].replace(/\\/g, '/');
+    const refProject = path.basename(refPath).replace(/\.csproj$/i, '');
+    projectReferences.push(refProject);
+  }
+
+  // Package References
+  const packageReferences = [];
+  const pkgRegex = /<PackageReference\s+Include=["']([^"']+)["'](?:\s+Version=["']([^"']+)["'])?/gi;
+  while ((match = pkgRegex.exec(code)) !== null) {
+    packageReferences.push({
+      name: match[1],
+      version: match[2] || 'unknown'
+    });
+  }
+
+  // Determine Layer (Clean Architecture heuristics)
+  let layer = 'other';
+  const lowerName = projectName.toLowerCase();
+  if (lowerName.includes('domain') || lowerName.includes('core')) {
+    layer = 'domain';
+  } else if (lowerName.includes('application') || lowerName.includes('usecase')) {
+    layer = 'application';
+  } else if (lowerName.includes('infrastructure') || lowerName.includes('data') || lowerName.includes('persistence')) {
+    layer = 'infrastructure';
+  } else if (lowerName.includes('api') || lowerName.includes('web') || lowerName.includes('server')) {
+    layer = 'api';
+  } else if (lowerName.includes('test')) {
+    layer = 'tests';
+  }
+
+  // Layer Boundary Violations
+  const violations = [];
+  if (layer === 'domain') {
+    for (const ref of projectReferences) {
+      const lowerRef = ref.toLowerCase();
+      if (lowerRef.includes('infra') || lowerRef.includes('api') || lowerRef.includes('web') || lowerRef.includes('app')) {
+        violations.push({
+          type: 'domain_layer_violation',
+          message: `Domain project "${projectName}" illegally references outer layer "${ref}"`
+        });
+      }
+    }
+  } else if (layer === 'application') {
+    for (const ref of projectReferences) {
+      const lowerRef = ref.toLowerCase();
+      if (lowerRef.includes('infra') || lowerRef.includes('api') || lowerRef.includes('web')) {
+        violations.push({
+          type: 'application_layer_violation',
+          message: `Application project "${projectName}" illegally references outer layer "${ref}"`
+        });
+      }
+    }
+  }
+
+  return {
+    filePath,
+    projectName,
+    targetFramework,
+    nullable,
+    layer,
+    projectReferences,
+    packageReferences,
+    violations
+  };
+}
+
+export function analyzeCSharpFile(filePath, content = null) {
+  const code = content !== null ? content : fs.readFileSync(filePath, 'utf8');
+  const lines = code.split(/\r?\n/).length;
+
+  const isMinimalApi = /\bapp\.Map(?:Get|Post|Put|Delete|Patch|Group)\b/.test(code) ||
+    /\bgroup\.Map(?:Get|Post|Put|Delete|Patch)\b/.test(code);
+  const isController = /:\s*(?:ControllerBase|Controller)\b/.test(code) || /\[ApiController\]/.test(code);
+  const hasFileScopedNamespace = /^namespace\s+[\w.]+\s*;/m.test(code);
+  const hasPrimaryConstructor = /(?:public|internal|private)\s+(?:class|record|struct)\s+\w+\s*\([^)]*\)\s*(?::|\{)/.test(code);
+
+  return {
+    filePath,
+    fileName: path.basename(filePath),
+    lines,
+    isMinimalApi,
+    isController,
+    hasFileScopedNamespace,
+    hasPrimaryConstructor
+  };
+}

package/src/analyzer/engine.js

@@ -0,0 +1,290 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { analyzeVueFile } from './vueScanner.js';
+import { analyzeCSharpFile, analyzeCsprojFile } from './dotnetScanner.js';
+
+const IGNORED_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  'bin',
+  'obj',
+  'coverage',
+  '.gemini',
+  '.opencode',
+  '.codex',
+  'artifacts'
+]);
+
+export async function runAnalysis(targetDir, options = {}) {
+  const rootDir = path.resolve(targetDir);
+  const files = collectScannableFiles(rootDir);
+
+  const vueResults = [];
+  const csprojResults = [];
+  const csharpResults = [];
+
+  for (const file of files) {
+    const ext = path.extname(file).toLowerCase();
+    if (ext === '.vue') {
+      vueResults.push(analyzeVueFile(file));
+    } else if (ext === '.csproj') {
+      csprojResults.push(analyzeCsprojFile(file));
+    } else if (ext === '.cs') {
+      csharpResults.push(analyzeCSharpFile(file));
+    }
+  }
+
+  const score = calculateHealthScore(vueResults, csprojResults, csharpResults);
+  const tokenCandidates = aggregateTokens(vueResults);
+  const hotspots = aggregateHotspots(vueResults, csprojResults);
+
+  const report = {
+    timestamp: new Date().toISOString(),
+    rootDir,
+    totalFilesScanned: files.length,
+    score,
+    vue: summarizeVueMetrics(vueResults),
+    dotnet: summarizeDotnetMetrics(csprojResults, csharpResults),
+    designTokens: tokenCandidates,
+    hotspots
+  };
+
+  if (options.saveIndex !== false) {
+    saveIndexFile(rootDir, report, options.artifactsDir || 'artifacts');
+  }
+
+  return report;
+}
+
+export function formatReport(report, useColors = true) {
+  const c = useColors
+    ? {
+        reset: '\x1b[0m',
+        bold: '\x1b[1m',
+        green: '\x1b[32m',
+        yellow: '\x1b[33m',
+        red: '\x1b[31m',
+        cyan: '\x1b[36m',
+        dim: '\x1b[2m'
+      }
+    : {
+        reset: '',
+        bold: '',
+        green: '',
+        yellow: '',
+        red: '',
+        cyan: '',
+        dim: ''
+      };
+
+  const scoreColor = report.score.total >= 80 ? c.green : (report.score.total >= 50 ? c.yellow : c.red);
+  const out = [];
+
+  out.push(`${c.bold}======================================================${c.reset}`);
+  out.push(`${c.bold}            PlanKit Repository Health Audit            ${c.reset}`);
+  out.push(`${c.bold}======================================================${c.reset}`);
+  out.push(`Root Directory: ${c.cyan}${report.rootDir}${c.reset}`);
+  out.push(`Files Scanned:  ${report.totalFilesScanned}`);
+  out.push(`Health Score:   ${scoreColor}${c.bold}${report.score.total} / 100${c.reset} (${report.score.grade})`);
+  out.push('');
+
+  // Vue summary if Vue files detected
+  if (report.vue && report.vue.totalSfc > 0) {
+    out.push(`${c.bold}Vue Architecture & Modernization Metrics:${c.reset}`);
+    out.push(`  SFC Count:               ${report.vue.totalSfc}`);
+    out.push(`  <script setup> Ratio:    ${c.green}${report.vue.scriptSetupPercent}%${c.reset} (${report.vue.scriptSetupCount}/${report.vue.totalSfc})`);
+    out.push(`  TypeScript Ratio:        ${c.green}${report.vue.tsPercent}%${c.reset} (${report.vue.tsCount}/${report.vue.totalSfc})`);
+    out.push(`  Pinia / Modern State:    ${report.vue.piniaCount} files (Vuex legacy: ${report.vue.vuexCount})`);
+    out.push(`  Maturity Distribution:  ${c.green}Preferred: ${report.vue.maturity.preferred}${c.reset} | ${c.yellow}Transitional: ${report.vue.maturity.transitional}${c.reset} | ${c.red}Legacy: ${report.vue.maturity.legacy}${c.reset}`);
+    out.push('');
+  }
+
+  // .NET summary if .NET files detected
+  if (report.dotnet && (report.dotnet.projectsCount > 0 || report.dotnet.csharpFilesCount > 0)) {
+    out.push(`${c.bold}.NET Solution Architecture Metrics:${c.reset}`);
+    out.push(`  Projects:                ${report.dotnet.projectsCount}`);
+    out.push(`  C# Source Files:         ${report.dotnet.csharpFilesCount}`);
+    out.push(`  Minimal APIs:            ${report.dotnet.minimalApiCount} | Controllers: ${report.dotnet.controllerCount}`);
+    if (report.dotnet.layerViolations.length > 0) {
+      out.push(`  ${c.red}Layer Boundary Violations:${c.reset} ${report.dotnet.layerViolations.length}`);
+    }
+    out.push('');
+  }
+
+  // Token candidates
+  if (report.designTokens && report.designTokens.frequentColors.length > 0) {
+    out.push(`${c.bold}Top Discovered Design Token Candidates (Colors):${c.reset}`);
+    for (const item of report.designTokens.frequentColors.slice(0, 5)) {
+      out.push(`  ${c.cyan}${item.color}${c.reset} (used in ${item.count} component/style rules)`);
+    }
+    out.push('');
+  }
+
+  // Hotspots
+  if (report.hotspots.length > 0) {
+    out.push(`${c.bold}Modernization Hotspots & Anti-Patterns (${report.hotspots.length}):${c.reset}`);
+    for (const h of report.hotspots.slice(0, 8)) {
+      out.push(`  - ${c.yellow}${h.file}${c.reset}: ${h.message}`);
+    }
+    if (report.hotspots.length > 8) {
+      out.push(`  ${c.dim}... and ${report.hotspots.length - 8} more in artifacts/.plankit-index.json${c.reset}`);
+    }
+    out.push('');
+  }
+
+  out.push(`${c.bold}======================================================${c.reset}`);
+  out.push(`Index saved to ${c.cyan}artifacts/.plankit-index.json${c.reset}`);
+  return out.join('\n');
+}
+
+function collectScannableFiles(dir, files = []) {
+  if (!fs.existsSync(dir)) return files;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (IGNORED_DIRS.has(entry.name) || entry.name.startsWith('.')) {
+      continue;
+    }
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      collectScannableFiles(fullPath, files);
+    } else if (entry.isFile()) {
+      const ext = path.extname(entry.name).toLowerCase();
+      if (['.vue', '.csproj', '.cs', '.ts', '.js'].includes(ext)) {
+        files.push(fullPath);
+      }
+    }
+  }
+
+  return files;
+}
+
+function calculateHealthScore(vueResults, csprojResults, csharpResults) {
+  let score = 100;
+
+  if (vueResults.length > 0) {
+    const total = vueResults.length;
+    const scriptSetup = vueResults.filter((r) => r.vueStyle === 'script_setup').length;
+    const ts = vueResults.filter((r) => r.language === 'ts').length;
+    const legacy = vueResults.filter((r) => r.maturity === 'legacy').length;
+    const vuex = vueResults.filter((r) => r.state === 'vuex').length;
+
+    // Deduct for non-script setup ratio
+    score -= Math.round(((total - scriptSetup) / total) * 35);
+    // Deduct for JS ratio (lack of TS)
+    score -= Math.round(((total - ts) / total) * 20);
+    // Deduct for legacy Vuex
+    if (vuex > 0) {
+      score -= Math.min(15, vuex * 3);
+    }
+    // Deduct for legacy anti-patterns (mixins, filters, etc.)
+    score -= Math.min(20, legacy * 4);
+  }
+
+  if (csprojResults.length > 0) {
+    const violations = csprojResults.flatMap((r) => r.violations).length;
+    score -= Math.min(25, violations * 10);
+  }
+
+  const finalScore = Math.max(0, Math.min(100, score));
+  let grade = 'A';
+  if (finalScore < 60) grade = 'F';
+  else if (finalScore < 70) grade = 'D';
+  else if (finalScore < 80) grade = 'C';
+  else if (finalScore < 90) grade = 'B';
+
+  return { total: finalScore, grade };
+}
+
+function summarizeVueMetrics(vueResults) {
+  const totalSfc = vueResults.length;
+  if (totalSfc === 0) return null;
+
+  const scriptSetupCount = vueResults.filter((r) => r.vueStyle === 'script_setup').length;
+  const tsCount = vueResults.filter((r) => r.language === 'ts').length;
+  const piniaCount = vueResults.filter((r) => r.state === 'pinia').length;
+  const vuexCount = vueResults.filter((r) => r.state === 'vuex').length;
+
+  const maturity = {
+    preferred: vueResults.filter((r) => r.maturity === 'preferred').length,
+    transitional: vueResults.filter((r) => r.maturity === 'transitional').length,
+    legacy: vueResults.filter((r) => r.maturity === 'legacy').length
+  };
+
+  return {
+    totalSfc,
+    scriptSetupCount,
+    scriptSetupPercent: Math.round((scriptSetupCount / totalSfc) * 100),
+    tsCount,
+    tsPercent: Math.round((tsCount / totalSfc) * 100),
+    piniaCount,
+    vuexCount,
+    maturity
+  };
+}
+
+function summarizeDotnetMetrics(csprojResults, csharpResults) {
+  if (csprojResults.length === 0 && csharpResults.length === 0) return null;
+
+  const layerViolations = csprojResults.flatMap((r) => r.violations);
+  const minimalApiCount = csharpResults.filter((r) => r.isMinimalApi).length;
+  const controllerCount = csharpResults.filter((r) => r.isController).length;
+
+  return {
+    projectsCount: csprojResults.length,
+    csharpFilesCount: csharpResults.length,
+    minimalApiCount,
+    controllerCount,
+    layerViolations
+  };
+}
+
+function aggregateTokens(vueResults) {
+  const colorCounts = new Map();
+  const spacingCounts = new Map();
+
+  for (const r of vueResults) {
+    for (const color of r.tokens.hexColors) {
+      colorCounts.set(color, (colorCounts.get(color) || 0) + 1);
+    }
+    for (const spacing of r.tokens.spacing) {
+      spacingCounts.set(spacing, (spacingCounts.get(spacing) || 0) + 1);
+    }
+  }
+
+  const frequentColors = Array.from(colorCounts.entries())
+    .map(([color, count]) => ({ color, count }))
+    .sort((a, b) => b.count - a.count);
+
+  const frequentSpacing = Array.from(spacingCounts.entries())
+    .map(([spacing, count]) => ({ spacing, count }))
+    .sort((a, b) => b.count - a.count);
+
+  return { frequentColors, frequentSpacing };
+}
+
+function aggregateHotspots(vueResults, csprojResults) {
+  const hotspots = [];
+  for (const r of vueResults) {
+    for (const h of r.hotspots) {
+      hotspots.push({ file: path.basename(r.filePath), relativePath: r.filePath, ...h });
+    }
+  }
+  for (const p of csprojResults) {
+    for (const v of p.violations) {
+      hotspots.push({ file: path.basename(p.filePath), relativePath: p.filePath, ...v });
+    }
+  }
+  return hotspots;
+}
+
+function saveIndexFile(rootDir, report, artifactsDirName = 'artifacts') {
+  const targetDir = path.join(rootDir, artifactsDirName);
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+  const indexPath = path.join(targetDir, '.plankit-index.json');
+  fs.writeFileSync(indexPath, JSON.stringify(report, null, 2), 'utf8');
+}