wize-dev-kit 0.3.0 → 0.4.0

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 };

package/tools/installer/document-project/render-index.js

@@ -0,0 +1,101 @@
+// Master index renderer for `wize-dev-kit document-project`.
+//
+// Generates `.wize/knowledge/document-project/index.md` linking all docs.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function link(name, file) {
+  return `- [${name}](./${file})`;
+}
+
+function linkWithMarker(name, file, exists) {
+  const base = link(name, file);
+  return exists ? base : `${base} _(To be generated)_`;
+}
+
+function renderIndex(projectRoot, { projectTypes = [], parts = [], generated = [], existing = [], deepDiveFiles = [] } = {}) {
+  const dir = path.join(projectRoot, '.wize', 'knowledge', 'document-project');
+  fs.mkdirSync(dir, { recursive: true });
+
+  const generatedSet = new Set(generated.map(g => path.basename(g)));
+  const existingSet = new Set(existing.map(e => path.basename(e)));
+  const has = name => generatedSet.has(name) || existingSet.has(name);
+
+  const isMultiPart = parts.length >= 2;
+  const primaryType = projectTypes[0] || 'unknown';
+
+  const lines = [
+    '---',
+    'status: baseline',
+    'owner: Pepper Potts + Peggy Carter',
+    `created: ${new Date().toISOString().slice(0, 10)}`,
+    `last_refreshed: ${new Date().toISOString().slice(0, 10)}`,
+    '---',
+    '',
+    '# Project Documentation Index',
+    '',
+    `**Type:** ${isMultiPart ? 'multi-part' : primaryType}`,
+    `**Primary project type(s):** ${projectTypes.join(', ') || 'unknown'}`,
+    '',
+    '## Generated Documentation',
+    '',
+    link('Project Overview', 'project-overview.md'),
+    linkWithMarker('Source Tree Analysis', 'source-tree-analysis.md', has('source-tree-analysis.md')),
+  ];
+
+  if (isMultiPart) {
+    for (const part of parts) {
+      const suffix = part.part_id === 'root' ? '' : `-${part.part_id}`;
+      lines.push(linkWithMarker(`Architecture — ${part.part_id || 'root'}`, `architecture${suffix}.md`, has(`architecture${suffix}.md`)));
+      lines.push(linkWithMarker(`Development Guide — ${part.part_id || 'root'}`, `development-guide${suffix}.md`, has(`development-guide${suffix}.md`)));
+      lines.push(linkWithMarker(`Component Inventory — ${part.part_id || 'root'}`, `component-inventory${suffix}.md`, has(`component-inventory${suffix}.md`)));
+      lines.push(linkWithMarker(`API Contracts — ${part.part_id || 'root'}`, `api-contracts${suffix}.md`, has(`api-contracts${suffix}.md`)));
+      lines.push(linkWithMarker(`Data Models — ${part.part_id || 'root'}`, `data-models${suffix}.md`, has(`data-models${suffix}.md`)));
+    }
+    lines.push(linkWithMarker('Integration Architecture', 'integration-architecture.md', has('integration-architecture.md')));
+  } else {
+    lines.push(linkWithMarker('Architecture', 'architecture.md', has('architecture.md')));
+    lines.push(linkWithMarker('Development Guide', 'development-guide.md', has('development-guide.md')));
+    lines.push(linkWithMarker('Component Inventory', 'component-inventory.md', has('component-inventory.md')));
+    lines.push(linkWithMarker('API Contracts', 'api-contracts.md', has('api-contracts.md')));
+    lines.push(linkWithMarker('Data Models', 'data-models.md', has('data-models.md')));
+  }
+
+  lines.push(linkWithMarker('Deployment Guide', 'deployment-guide.md', has('deployment-guide.md')));
+  lines.push(linkWithMarker('Contribution Guide', 'contribution-guide.md', has('contribution-guide.md')));
+  if (deepDiveFiles.length) {
+    lines.push('', '## Deep-Dive Docs', '');
+    for (const f of deepDiveFiles) {
+      lines.push(link(f.replace(/^deep-dive-/, '').replace(/\.md$/, ''), f));
+    }
+  } else {
+    lines.push(linkWithMarker('Deep-Dive Docs', 'deep-dive/', false)); // directory marker
+  }
+
+  if (existing.length) {
+    lines.push('', '## Existing Documentation', '');
+    for (const doc of existing) {
+      const rel = path.relative(dir, doc);
+      lines.push(`- [${path.basename(doc)}](./${rel})`);
+    }
+  }
+
+  lines.push('', '## Brownfield Baseline', '');
+  lines.push(link('Overview', 'overview.md'));
+  lines.push(link('Architecture Snapshot', 'architecture-snapshot.md'));
+  lines.push(link('Conventions', 'conventions.md'));
+  lines.push(link('Dependencies', 'dependencies.md'));
+  lines.push(link('Risk Spots', 'risk-spots.md'));
+  lines.push(link('Open Questions', 'open-questions.md'));
+
+  lines.push('', '---', '', '_Generated by `wize-document-project`._', '');
+
+  const file = path.join(dir, 'index.md');
+  fs.writeFileSync(file, lines.join('\n'), 'utf-8');
+  return { changed: true, written: ['index.md'] };
+}
+
+module.exports = { renderIndex, link, linkWithMarker };