wize-dev-kit 0.3.0 → 0.3.1

package/tools/installer/document-project/classify.js

@@ -0,0 +1,170 @@
+// Project-type classifier for `wize-dev-kit document-project`.
+//
+// Detects the project type(s) of a repo from file patterns, then decides
+// whether the repo is a monolith, multi-part, or monorepo.
+// No source files are read — this is pattern-only detection.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const MULTI_PART_FOLDERS = ['client', 'server', 'api', 'web', 'app', 'frontend', 'backend', 'mobile', 'desktop'];
+
+function toBool(v) {
+  return String(v).toLowerCase() === 'true';
+}
+
+function splitPatterns(str) {
+  if (!str || str === 'N/A') return [];
+  return str.split(';').map(s => s.trim()).filter(Boolean);
+}
+
+function loadRequirements(csvPath) {
+  const content = fs.readFileSync(csvPath, 'utf-8');
+  const lines = content.split(/\r?\n/).filter(l => l.trim());
+  const header = lines[0].split(',').map(h => h.trim());
+  const rows = [];
+  for (let i = 1; i < lines.length; i++) {
+    const values = lines[i].split(',').map(v => v.trim());
+    const row = {};
+    for (let j = 0; j < header.length; j++) {
+      const key = header[j];
+      const raw = values[j];
+      if (key.startsWith('requires_')) {
+        row[key] = toBool(raw);
+      } else {
+        row[key] = raw || '';
+      }
+    }
+    rows.push(row);
+  }
+  return rows;
+}
+
+function globMatch(rootDir, pattern) {
+  // Very small pattern matcher: supports * wildcard and trailing / for dirs.
+  const isDirPattern = pattern.endsWith('/');
+  const base = isDirPattern ? pattern.slice(0, -1) : pattern;
+  const parts = base.split('/');
+  return walkMatch(rootDir, parts, 0, isDirPattern);
+}
+
+function walkMatch(dir, parts, depth, isDirPattern) {
+  if (depth >= parts.length) return true;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return false; }
+  const part = parts[depth];
+  const isLast = depth === parts.length - 1;
+  const regex = globToRegex(part);
+  for (const e of entries) {
+    if (!regex.test(e.name)) continue;
+    if (isLast) {
+      if (isDirPattern && e.isDirectory()) return true;
+      if (!isDirPattern && e.isFile()) return true;
+      if (!isDirPattern && e.isDirectory()) {
+        // pattern like vite.config.* can match a directory named vite.config.ts? no.
+        // But pattern may be a prefix; treat directory match as false for files.
+        return false;
+      }
+    } else if (e.isDirectory()) {
+      if (walkMatch(path.join(dir, e.name), parts, depth + 1, isDirPattern)) return true;
+    }
+  }
+  return false;
+}
+
+function globToRegex(pattern) {
+  const escaped = pattern
+    .replace(/\./g, '\\.')
+    .replace(/\*/g, '.*')
+    .replace(/\?/g, '.');
+  return new RegExp(`^${escaped}$`);
+}
+
+function scorePart(rootDir, row, { prefer = [] } = {}) {
+  let score = 0;
+  const keyPatterns = splitPatterns(row.key_file_patterns);
+  const dirPatterns = splitPatterns(row.critical_directories);
+  for (const p of keyPatterns) {
+    if (globMatch(rootDir, p)) score += 2;
+  }
+  for (const p of dirPatterns) {
+    if (globMatch(rootDir, p)) score += 1;
+  }
+  if (prefer.includes(row.project_type_id)) score += 0.5;
+  return score;
+}
+
+function detectParts(rootDir) {
+  const parts = [];
+  const candidates = [];
+  let entries;
+  try { entries = fs.readdirSync(rootDir, { withFileTypes: true }); } catch { return parts; }
+
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (!MULTI_PART_FOLDERS.includes(e.name.toLowerCase())) continue;
+    candidates.push(e.name);
+  }
+
+  if (candidates.length < 2) return parts;
+
+  const rows = loadRequirements(requirementsPath());
+  for (const partId of candidates) {
+    const partRoot = path.join(rootDir, partId);
+    const prefer = partId.toLowerCase() === 'server' || partId.toLowerCase() === 'backend' ? ['backend'] : [];
+    const scored = rows.map(r => ({ ...r, score: scorePart(partRoot, r, { prefer }) }));
+    scored.sort((a, b) => b.score - a.score);
+    const best = scored[0];
+    if (best && best.score > 0) {
+      parts.push({ part_id: partId, project_type_id: best.project_type_id, root_path: partRoot });
+    }
+  }
+  return parts;
+}
+
+function isMultiPart(rootDir) {
+  return detectParts(rootDir).length >= 2;
+}
+
+function classifyProject(rootDir, options = {}) {
+  const csvPath = options.csvPath || requirementsPath();
+  const rows = loadRequirements(csvPath);
+  const parts = detectParts(rootDir);
+
+  if (parts.length >= 2) {
+    return { projectTypes: [...new Set(parts.map(p => p.project_type_id))], parts };
+  }
+
+  const scored = rows.map(r => ({ ...r, score: scorePart(rootDir, r, { prefer: options.prefer || [] }) }));
+  scored.sort((a, b) => b.score - a.score);
+  const best = scored[0];
+  const tied = scored.filter(s => s.score === best.score).map(s => s.project_type_id);
+
+  if (!best || best.score === 0) {
+    return { projectTypes: [], parts: [] };
+  }
+
+  // Cli + library often appear together; prefer both when tied at the top.
+  const projectTypes = tied.includes('cli') && tied.includes('library')
+    ? ['cli', 'library']
+    : [best.project_type_id];
+
+  return {
+    projectTypes,
+    parts: [{ part_id: 'root', project_type_id: best.project_type_id, root_path: rootDir }]
+  };
+}
+
+function requirementsPath() {
+  // When running from the installed package, the CSV is next to this file under
+  // node_modules/wize-dev-kit/... When running from the source repo, resolve from
+  // the repo root via the known relative path.
+  const installed = path.resolve(__dirname, '..', '..', '..', 'src', 'method-skills', '1-analysis', 'wize-document-project', 'documentation-requirements.csv');
+  if (fs.existsSync(installed)) return installed;
+  // Fallback for source repo layout.
+  return path.resolve(__dirname, '..', '..', '..', '..', 'src', 'method-skills', '1-analysis', 'wize-document-project', 'documentation-requirements.csv');
+}
+
+module.exports = { classifyProject, loadRequirements, isMultiPart, scorePart, requirementsPath, globMatch };

package/tools/installer/document-project/modes/deep-dive.js

@@ -0,0 +1,196 @@
+// Deep-dive mode for `wize-dev-kit document-project`.
+//
+// Exhaustive documentation of a specific folder/file/feature.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { batchScanner, scanFolder } = require('../batch-scanner.js');
+const { updateState } = require('../state.js');
+const { renderIndex } = require('../render-index.js');
+
+function sanitize(name) {
+  return name.replace(/[^a-z0-9_-]/gi, '-').toLowerCase();
+}
+
+function walkAllFiles(rootDir, ignore = ['node_modules', '.git', 'dist', 'build', 'coverage']) {
+  const files = [];
+  const stack = [rootDir];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (!ignore.includes(e.name)) stack.push(full);
+        continue;
+      }
+      if (e.isFile() && /\.(js|ts|jsx|tsx|mjs|cjs)$/.test(e.name)) files.push(full);
+    }
+  }
+  return files;
+}
+
+function matchesTarget(filePath, projectRoot, targetType, targetName) {
+  const rel = path.relative(projectRoot, filePath).toLowerCase();
+  const name = targetName.toLowerCase();
+  if (targetType === 'feature') {
+    return rel.includes(name);
+  }
+  if (targetType === 'api_group') {
+    const inApiFolder = /\/(routes|api|controllers|endpoints)\//.test(rel);
+    return inApiFolder && rel.includes(name);
+  }
+  if (targetType === 'component_group') {
+    const inComponentFolder = /\/(components|ui|widgets)\//.test(rel);
+    return inComponentFolder && rel.includes(name);
+  }
+  return false;
+}
+
+function resolveTarget(projectRoot, target) {
+  if (!target) return { targetType: null, targetName: null, targetPath: null, files: [] };
+
+  // Explicit typed target: "feature:auth", "api:users", "component:Button"
+  const typedMatch = target.match(/^([a-z_]+):(.+)$/i);
+  if (typedMatch) {
+    const targetType = typedMatch[1].toLowerCase();
+    const targetName = typedMatch[2];
+    if (['feature', 'api_group', 'component_group'].includes(targetType)) {
+      const all = walkAllFiles(projectRoot);
+      const files = all.filter(f => matchesTarget(f, projectRoot, targetType, targetName));
+      return { targetType, targetName, targetPath: target, files };
+    }
+    return { targetType, targetName, targetPath: target, files: [], error: `unknown target type: ${targetType}` };
+  }
+
+  // Path-based target (folder or file)
+  const targetPath = path.resolve(projectRoot, target);
+  if (fs.existsSync(targetPath)) {
+    const stats = fs.statSync(targetPath);
+    const targetType = stats.isFile() ? 'file' : 'folder';
+    const files = stats.isFile() ? [targetPath] : scanFolder(targetPath, { ignore: ['node_modules', '.git', 'dist', 'build', 'coverage'] }).files.map(f => f.path);
+    return { targetType, targetName: path.basename(targetPath), targetPath, files };
+  }
+
+  // Bare name treated as feature search
+  const all = walkAllFiles(projectRoot);
+  const files = all.filter(f => matchesTarget(f, projectRoot, 'feature', target));
+  return { targetType: 'feature', targetName: target, targetPath: target, files };
+}
+
+function listFilesInScope(rootDir, targetPath) {
+  const stats = fs.statSync(targetPath);
+  if (stats.isFile()) return [targetPath];
+  const scan = scanFolder(targetPath, { ignore: ['node_modules', '.git', 'dist', 'build', 'coverage'] });
+  return scan.files.map(f => f.path);
+}
+
+function readFileSummary(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n');
+    const exports = [];
+    const todos = [];
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (/\b(module\.exports|exports\.|export\s+(default\s+)?|function\s+|class\s+)/.test(line)) {
+        exports.push(line.trim().slice(0, 80));
+      }
+      if (/\b(TODO|FIXME|HACK|XXX)\b/i.test(line)) {
+        todos.push(`${i + 1}: ${line.trim().slice(0, 80)}`);
+      }
+    }
+    return {
+      path: filePath,
+      loc: lines.length,
+      exports: exports.slice(0, 10),
+      todos: todos.slice(0, 10)
+    };
+  } catch {
+    return { path: filePath, loc: 0, exports: [], todos: [] };
+  }
+}
+
+function runDeepDive(projectRoot, { target, log = console.log } = {}) {
+  if (!target) {
+    return { ok: false, error: 'missing --target for deep_dive', exitCode: 1 };
+  }
+
+  const resolved = resolveTarget(projectRoot, target);
+  if (resolved.error) {
+    return { ok: false, error: resolved.error, exitCode: 1 };
+  }
+  if (resolved.targetType === 'file' || resolved.targetType === 'folder') {
+    if (!fs.existsSync(resolved.targetPath)) {
+      return { ok: false, error: `target not found: ${target}`, exitCode: 1 };
+    }
+  }
+  if (resolved.files.length === 0) {
+    return { ok: false, error: `target not found or no files matched: ${target}`, exitCode: 1 };
+  }
+
+  const files = resolved.files;
+  const summaries = files.map(readFileSummary);
+  const targetName = resolved.targetName;
+  const outputName = `deep-dive-${sanitize(targetName)}.md`;
+  const outputPath = path.join(projectRoot, '.wize', 'knowledge', 'document-project', outputName);
+
+  const lines = [
+    '---',
+    'status: baseline',
+    'owner: Pepper Potts + Tony Stark',
+    `created: ${new Date().toISOString().slice(0, 10)}`,
+    `last_refreshed: ${new Date().toISOString().slice(0, 10)}`,
+    '---',
+    '',
+    `# Deep Dive — ${targetName}`,
+    '',
+    `**Type:** ${resolved.targetType}`,
+    `**Scope:** ${target}`,
+    `**Files analyzed:** ${files.length}`,
+    '',
+    '## File Inventory',
+    ''
+  ];
+
+  for (const s of summaries) {
+    lines.push(`### ${path.relative(projectRoot, s.path)}`);
+    lines.push(`- **LOC:** ${s.loc}`);
+    if (s.exports.length) {
+      lines.push('- **Exports/signatures:**');
+      for (const e of s.exports) lines.push(`  - \`${e}\``);
+    }
+    if (s.todos.length) {
+      lines.push('- **TODOs/FIXMEs:**');
+      for (const t of s.todos) lines.push(`  - ${t}`);
+    }
+    lines.push('');
+  }
+
+  lines.push('## Modification Guidance', '', '- Verify tests before changing exported signatures.', '');
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, lines.join('\n'), 'utf-8');
+
+  updateState(projectRoot, {
+    deep_dive_targets: [{
+      target_name: targetName,
+      target_path: resolved.targetPath,
+      files_analyzed: files.length,
+      output_file: outputName,
+      timestamp: new Date().toISOString()
+    }],
+    outputs_generated: [outputName]
+  });
+
+  // Update master index with a link to this deep-dive doc.
+  renderIndex(projectRoot, { deepDiveFiles: [outputName] });
+
+  log(`Deep-dive written to ${outputPath}`);
+  return { ok: true, mode: 'deep_dive', changed: true, written: [outputName] };
+}
+
+module.exports = { runDeepDive, listFilesInScope, readFileSummary, resolveTarget };

package/tools/installer/document-project/modes/full-rescan.js

@@ -0,0 +1,15 @@
+// Full rescan mode for `wize-dev-kit document-project`.
+//
+// Archives the previous state and re-runs an initial scan from scratch.
+
+'use strict';
+
+const { archiveOldState } = require('../state.js');
+const { runInitialScan } = require('./initial-scan.js');
+
+function runFullRescan(projectRoot, options = {}) {
+  archiveOldState(projectRoot);
+  return runInitialScan(projectRoot, { ...options, mode: 'full_rescan' });
+}
+
+module.exports = { runFullRescan };

package/tools/installer/document-project/modes/initial-scan.js

@@ -0,0 +1,100 @@
+// Initial scan mode for `wize-dev-kit document-project`.
+//
+// Runs project-type classification, conditional scans, and generates index + docs.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { classifyProject } = require('../classify.js');
+const { batchScanner } = require('../batch-scanner.js');
+const { renderIndex } = require('../render-index.js');
+const { initState, updateState } = require('../state.js');
+const { runQuick } = require('./quick.js');
+
+function now() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function readRequirements(row) {
+  return {
+    api: row.requires_api_scan,
+    data: row.requires_data_models,
+    state: row.requires_state_management,
+    ui: row.requires_ui_components,
+    deploy: row.requires_deployment_config,
+    hardware: row.requires_hardware_docs,
+    assets: row.requires_asset_inventory
+  };
+}
+
+function existingDocs(root) {
+  const candidates = [
+    'README.md',
+    'CONTRIBUTING.md',
+    'ARCHITECTURE.md',
+    'DEPLOYMENT.md',
+    'API.md'
+  ];
+  return candidates.filter(f => fs.existsSync(path.join(root, f))).map(f => path.join(root, f));
+}
+
+function runInitialScan(projectRoot, { scanLevel = 'quick', log = console.log, csvPath } = {}) {
+  const classification = classifyProject(projectRoot, csvPath ? { csvPath } : {});
+  const state = initState(projectRoot, 'initial_scan', scanLevel);
+
+  updateState(projectRoot, {
+    completed_steps: [{ step: 'classify', status: 'completed', timestamp: new Date().toISOString(), summary: `Classified as ${classification.projectTypes.join(', ')}` }],
+    current_step: 'scan',
+    findings: {
+      project_classification: {
+        repository_type: classification.parts.length >= 2 ? 'multi-part' : 'monolith',
+        parts_count: classification.parts.length,
+        primary_language: 'unknown',
+        architecture_type: classification.projectTypes[0] || 'unknown'
+      }
+    }
+  });
+
+  let generated = [];
+  if (scanLevel === 'deep' || scanLevel === 'exhaustive') {
+    const batches = batchScanner(projectRoot, { ignore: ['.wize', '.git', 'node_modules'] });
+    updateState(projectRoot, {
+      completed_steps: [{ step: 'scan', status: 'completed', timestamp: new Date().toISOString(), summary: `${batches.length} batches scanned` }],
+      current_step: 'generate',
+      findings: {
+        batches_completed: batches.map(b => ({ path: b.folder, files_scanned: b.fileCount, summary: `${b.totalLoc} LOC` }))
+      }
+    });
+  }
+
+  // Always write baseline + index.
+  const quick = runQuick(projectRoot, { log });
+  generated.push(...quick.written.map(f => path.join(projectRoot, '.wize', 'knowledge', 'document-project', f)));
+
+  const indexResult = renderIndex(projectRoot, {
+    projectTypes: classification.projectTypes,
+    parts: classification.parts,
+    generated,
+    existing: existingDocs(projectRoot)
+  });
+  generated.push(path.join(projectRoot, '.wize', 'knowledge', 'document-project', 'index.md'));
+
+  updateState(projectRoot, {
+    completed_steps: [{ step: 'generate', status: 'completed', timestamp: new Date().toISOString(), summary: `Generated ${generated.length} files` }],
+    current_step: 'completed',
+    outputs_generated: generated.map(g => path.basename(g)),
+    resume_instructions: 'Scan complete'
+  });
+
+  return {
+    changed: true,
+    mode: 'initial_scan',
+    scanLevel,
+    projectTypes: classification.projectTypes,
+    parts: classification.parts,
+    generated: generated.map(g => path.basename(g))
+  };
+}
+
+module.exports = { runInitialScan };

package/tools/installer/document-project/modes/quick.js

@@ -0,0 +1,211 @@
+// Quick baseline mode for `wize-dev-kit document-project`.
+//
+// Produces the 6 lightweight baseline files. Does not read source files.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const BASELINE_FILES = {
+  'overview.md': overviewMarkdown,
+  'architecture-snapshot.md': architectureMarkdown,
+  'conventions.md': conventionsMarkdown,
+  'dependencies.md': dependenciesMarkdown,
+  'risk-spots.md': riskMarkdown,
+  'open-questions.md': questionsMarkdown
+};
+
+function now() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function readPackage(root) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+function countLines(root) {
+  let total = 0;
+  const dirs = ['src', 'tools', 'adapters', 'schemas', 'test'];
+  for (const dir of dirs) {
+    const full = path.join(root, dir);
+    if (!fs.existsSync(full)) continue;
+    total += walkLines(full);
+  }
+  return total;
+}
+
+function walkLines(dir) {
+  let total = 0;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) total += walkLines(full);
+    else if (e.isFile() && /\.(js|md|yaml|json)$/.test(e.name)) {
+      const content = fs.readFileSync(full, 'utf-8');
+      total += content.split('\n').length;
+    }
+  }
+  return total;
+}
+
+function recentCommitCount(root) {
+  // Avoid shelling out; return 0 if not a git repo or git unavailable.
+  // Caller can overlay a real count from CLI.
+  return 0;
+}
+
+function overviewMarkdown(root, pkg) {
+  return `---
+status: baseline
+owner: Pepper Potts + Peggy Carter
+created: ${now()}
+last_refreshed: ${now()}
+---
+
+# Overview
+
+**Project:** ${pkg.name || path.basename(root)}
+**What it is:** ${pkg.description || 'Project documented by Wize Dev Kit.'}
+**Current version:** ${pkg.version || 'unknown'}
+
+## Size
+
+- Source lines of code: ~${countLines(root)} LOC.
+- Runtime dependencies: ${Object.keys(pkg.dependencies || {}).length}.
+- Dev dependencies: ${Object.keys(pkg.devDependencies || {}).length}.
+
+## What it ships
+
+- See architecture-snapshot.md for components and entry points.
+- See conventions.md for coding patterns.
+- See dependencies.md for runtime and dev dependency roles.
+`;
+}
+
+function architectureMarkdown() {
+  return `---
+status: baseline
+owner: Pepper Potts + Tony Stark
+created: ${now()}
+last_refreshed: ${now()}
+---
+
+# Architecture Snapshot
+
+## Entry points
+
+- Documented after a deeper scan (initial_scan mode).
+
+## Components
+
+- Run \`wize-dev-kit document-project initial_scan deep\` for component-level detail.
+
+## Integration surface
+
+- See dependencies.md for external integrations.
+`;
+}
+
+function conventionsMarkdown() {
+  return `---
+status: baseline
+owner: Peggy Carter
+created: ${now()}
+last_refreshed: ${now()}
+sampled: "pending deeper scan"
+---
+
+# Conventions (observed, not prescribed)
+
+## Quick notes
+
+- Run \`wize-dev-kit document-project initial_scan deep\` to sample files and fill this doc.
+`;
+}
+
+function dependenciesMarkdown(root, pkg) {
+  const runtime = Object.entries(pkg.dependencies || {})
+    .map(([name, version]) => `| ${name} | ${version} | | |`).join('\n');
+  const dev = Object.entries(pkg.devDependencies || {})
+    .map(([name, version]) => `| ${name} | ${version} | | |`).join('\n');
+
+  return `---
+status: baseline
+owner: Pepper Potts
+created: ${now()}
+last_refreshed: ${now()}
+---
+
+# Dependencies
+
+## Runtime
+
+| Name | Version | Role in this repo | Load-bearing? |
+|---|---|---|---|
+${runtime || '| — | — | — | — |'}
+
+## Dev / bundled
+
+| Name | Version | Role in this repo | Load-bearing? |
+|---|---|---|---|
+${dev || '| — | — | — | — |'}
+`;
+}
+
+function riskMarkdown() {
+  return `---
+status: baseline
+owner: Pepper Potts + Tony Stark
+created: ${now()}
+last_refreshed: ${now()}
+---
+
+# Risk Spots
+
+| Area | Symptom | Likely cause | Confidence |
+|---|---|---|---|
+| | | | |
+
+Run \`wize-dev-kit document-project initial_scan deep\` to populate risk spots.
+`;
+}
+
+function questionsMarkdown() {
+  return `---
+status: baseline
+owner: Pepper Potts + Peggy Carter
+created: ${now()}
+last_refreshed: ${now()}
+---
+
+# Open Questions
+
+| Question | Why it matters | Owner to ask |
+|---|---|---|
+| | | |
+`;
+}
+
+function runQuick(projectRoot, opts = {}) {
+  const pkg = readPackage(projectRoot);
+  const dir = path.join(projectRoot, '.wize', 'knowledge', 'document-project');
+  fs.mkdirSync(dir, { recursive: true });
+
+  const written = [];
+  for (const [name, factory] of Object.entries(BASELINE_FILES)) {
+    const file = path.join(dir, name);
+    const content = factory(projectRoot, pkg);
+    fs.writeFileSync(file, content, 'utf-8');
+    written.push(name);
+  }
+
+  if (opts.log) opts.log(`Quick baseline written to ${dir}`);
+  return { changed: true, mode: 'quick', written };
+}
+
+module.exports = { runQuick, BASELINE_FILES, countLines };