@lakindu_perera/toren 1.0.5 → 1.0.8

package/src/renderers/markdown-renderer.js

@@ -28,37 +28,7 @@ import path from 'node:path';
 // Plain-text tree builder (Markdown-safe, no ANSI, no emoji)
 // ---------------------------------------------------------------------------
 
-/**
- * Build an in-memory nested tree from a flat list of relative file paths.
- * This avoids repeating the walk already done by the scanner while keeping
- * the markdown renderer completely self-contained.
- *
- * @param {string[]} flatFiles - Relative file paths produced by scan()
- * @returns {{ name: string, type: 'directory'|'file', children: object }[]}
- */
-function buildTree(flatFiles) {
-  /** @type {{ type: string, children: Record<string, object> }} */
-  const root = { type: 'directory', children: {} };
-
-  for (const filePath of flatFiles) {
-    const parts = filePath.split(/[/\\]/).filter(Boolean);
-    let node = root;
-
-    for (let i = 0; i < parts.length; i++) {
-      const part    = parts[i];
-      const isLeaf  = i === parts.length - 1;
-
-      if (!node.children[part]) {
-        node.children[part] = isLeaf
-          ? { type: 'file', name: part }
-          : { type: 'directory', name: part, children: {} };
-      }
-      node = node.children[part];
-    }
-  }
 
-  return root;
-}
 
 /**
  * Recursively serialise a tree node into classic tree-connector lines.
@@ -81,11 +51,7 @@ function serializeNode(node, prefix, isLast, lines, depth = 0, maxDepth = 5) {
   lines.push(`${prefix}${connector}${label}`);
 
   if (node.type === 'directory') {
-    const children = Object.values(node.children || {}).sort((a, b) => {
-      // Directories before files, then alphabetically.
-      if (a.type !== b.type) return a.type === 'directory' ? -1 : 1;
-      return a.name.localeCompare(b.name);
-    });
+    const children = node.children || [];
 
     // Truncate deep directories with an ellipsis rather than cutting silently.
     if (depth === maxDepth - 1 && children.length > 0) {
@@ -107,21 +73,18 @@ function serializeNode(node, prefix, isLast, lines, depth = 0, maxDepth = 5) {
 }
 
 /**
- * Convert a flat file list into a Markdown-safe tree string.
+ * Convert a ScanResult tree into a Markdown-safe tree string.
  *
- * @param {string[]} flatFiles
+ * @param {import('../scanner/scan.js').DirNode} tree
  * @param {string}   rootName - Display name for the root node (e.g. "my-app/")
+ * @param {number}   totalFiles
  * @returns {string}
  */
-function buildTreeString(flatFiles, rootName) {
-  if (flatFiles.length === 0) return '';
+function buildTreeString(tree, rootName, totalFiles) {
+  if (totalFiles === 0) return '';
 
-  const root     = buildTree(flatFiles);
   const lines    = [`${rootName}/`];
-  const children = Object.values(root.children).sort((a, b) => {
-    if (a.type !== b.type) return a.type === 'directory' ? -1 : 1;
-    return a.name.localeCompare(b.name);
-  });
+  const children = tree.children || [];
 
   for (let i = 0; i < children.length; i++) {
     serializeNode(children[i], '', i === children.length - 1, lines);
@@ -165,6 +128,19 @@ function markdownTable(rows) {
   return [head, hr, ...body].join('\n');
 }
 
+/**
+ * Derive a frameworks array from the projectType string.
+ * Returns [] when no specific framework is detected.
+ * Mirrors the identical derivation in console-renderer.js and json-renderer.js.
+ *
+ * @param {string} projectType
+ * @returns {string[]}
+ */
+function deriveFrameworks(projectType) {
+  if (!projectType || projectType === 'Unknown') return [];
+  return [projectType];
+}
+
 /**
  * Build a right-aligned Markdown table (used for statistics).
  *
@@ -190,11 +166,9 @@ function statsTable(rows) {
 
 /** @param {string[]} out */
 function sectionTitle(out) {
-  out.push('# Project Analysis Report');
+  out.push('# Toren Report');
   out.push('');
   out.push('Generated by **Toren** — Codebase Onboarding Intelligence');
-  out.push('');
-  out.push('---');
 }
 
 /**
@@ -203,19 +177,48 @@ function sectionTitle(out) {
  * @param {string} relRoot
  */
 function sectionSummary(out, result, relRoot) {
-  const { projectType, flatFiles, totalFolders } = result;
+  const { projectType, flatFiles, totalFolders, packageManager, projectInfo } = result;
 
   out.push('');
-  out.push('## Project Summary');
+  out.push('## Project');
   out.push('');
-  out.push(markdownTable([
-    ['Project Type', projectType],
-    ['Scan Path',    relRoot],
-    ['Total Files',  String(flatFiles.length)],
-    ['Total Folders', String(totalFolders)],
-  ]));
+  
+  const rows = [];
+  if (projectInfo && projectInfo.name) rows.push(['Name', projectInfo.name]);
+  rows.push(['Project Type', projectType]);
+  if (packageManager) rows.push(['Package Manager', packageManager]);
+  if (projectInfo && projectInfo.runtime) rows.push(['Runtime', projectInfo.runtime]);
+  if (projectInfo && projectInfo.language) rows.push(['Language', projectInfo.language]);
+  if (projectInfo && projectInfo.architecture) rows.push(['Architecture', projectInfo.architecture]);
+  if (projectInfo && projectInfo.framework) rows.push(['Framework', projectInfo.framework]);
+  if (projectInfo && projectInfo.entryPoint) rows.push(['Entry Point', projectInfo.entryPoint]);
+  if (projectInfo && projectInfo.sourceDirectory) rows.push(['Source Directory', projectInfo.sourceDirectory]);
+
+  rows.push(['Scan Path', relRoot]);
+  rows.push(['Total Files', String(flatFiles.length)]);
+  rows.push(['Total Folders', String(totalFolders)]);
+
+  out.push(markdownTable(rows));
+}
+
+/**
+ * @param {string[]} out
+ * @param {string}   projectType
+ */
+function sectionFrameworks(out, projectType) {
+  const frameworks = deriveFrameworks(projectType);
+
+  out.push('');
+  out.push('## Frameworks');
   out.push('');
-  out.push('---');
+
+  if (frameworks.length === 0) {
+    out.push('No frameworks detected.');
+  } else {
+    for (const fw of frameworks) {
+      out.push(`- ${fw}`);
+    }
+  }
 }
 
 /**
@@ -224,7 +227,7 @@ function sectionSummary(out, result, relRoot) {
  */
 function sectionConfigurationFiles(out, configs) {
   out.push('');
-  out.push('## Configuration Files');
+  out.push('## Configurations');
   out.push('');
 
   if (configs.length === 0) {
@@ -234,32 +237,71 @@ function sectionConfigurationFiles(out, configs) {
       out.push(`- ${c}`);
     }
   }
-
-  out.push('');
-  out.push('---');
 }
 
 /**
  * @param {string[]} out
- * @param {Array<{name: string, command: string}>} scripts
+ * @param {Array<{name: string, command: string, description: string, usage: string}>} scripts
  */
 function sectionPackageScripts(out, scripts) {
   out.push('');
-  out.push('## Package Scripts');
+  out.push('## Scripts');
   out.push('');
 
   if (scripts.length === 0) {
     out.push('No package scripts detected.');
   } else {
-    out.push('| Script | Command |');
-    out.push('|--------|---------|');
     for (const s of scripts) {
-      out.push(`| \`${s.name}\` | \`${s.command}\` |`);
+      const usage = s.usage || `npm run ${s.name}`;
+      out.push(`- **${usage}**`);
+      if (s.description) {
+        out.push(`  ${s.description}  `);
+        out.push(`  \`${s.command}\``);
+      } else {
+        out.push(`  \`${s.command}\``);
+      }
     }
   }
+}
 
+/**
+ * @param {string[]} out
+ * @param {Array<{path: string, reason: string}>} importantFiles
+ */
+function sectionImportantFiles(out, importantFiles) {
+  out.push('');
+  out.push('## Important Files');
   out.push('');
-  out.push('---');
+
+  if (importantFiles.length === 0) {
+    out.push('No important files detected.');
+  } else {
+    for (const f of importantFiles) {
+      out.push(`- **${f.path}**  `);
+      out.push(`  ${f.reason}`);
+    }
+  }
+}
+
+/**
+ * @param {string[]} out
+ * @param {Array<{id: string, status: string, message: string}>} health
+ */
+function sectionProjectHealth(out, health) {
+  out.push('');
+  out.push('## Project Health');
+  out.push('');
+
+  if (health.length === 0) {
+    out.push('No project health observations available.');
+  } else {
+    for (const h of health) {
+      let icon = 'ℹ';
+      if (h.status === 'pass') icon = '✓';
+      else if (h.status === 'warning') icon = '⚠';
+      out.push(`- ${icon} ${h.message}`);
+    }
+  }
 }
 
 /**
@@ -275,35 +317,29 @@ function sectionEntryPoints(out, entryPoints) {
     out.push('No entry points detected.');
   } else {
     for (const ep of entryPoints) {
-      out.push(`- \`${ep}\``);
+      out.push(`- ${ep}`);
     }
   }
-
-  out.push('');
-  out.push('---');
 }
 
 /**
  * @param {string[]} out
- * @param {string[]} flatFiles
- * @param {string}   rootName
+ * @param {import('../scanner/scan.js').DirNode} tree
+ * @param {number} totalFiles
+ * @param {string} rootName
  */
-function sectionFolderStructure(out, flatFiles, rootName) {
+function sectionFolderStructure(out, tree, totalFiles, rootName) {
+  // Contract: omit section entirely when no files were scanned.
+  if (totalFiles === 0) return;
+
   out.push('');
-  out.push('## Folder Structure');
+  out.push('## Structure');
   out.push('');
 
-  if (flatFiles.length === 0) {
-    out.push('No files scanned.');
-  } else {
-    const tree = buildTreeString(flatFiles, rootName);
-    out.push('```text');
-    out.push(tree);
-    out.push('```');
-  }
-
-  out.push('');
-  out.push('---');
+  const treeStr = buildTreeString(tree, rootName, totalFiles);
+  out.push('```text');
+  out.push(treeStr);
+  out.push('```');
 }
 
 /**
@@ -321,21 +357,6 @@ function sectionStatistics(out, result) {
     ['Folders',       totalFolders],
     ['Scan Duration', formatDuration(scanDurationMs)],
   ]));
-  out.push('');
-  out.push('---');
-}
-
-/**
- * @param {string[]} out
- */
-function sectionScanInfo(out) {
-  out.push('');
-  out.push('## Scan Information');
-  out.push('');
-  out.push('Generated by **Toren**');
-  out.push('');
-  out.push('Output Format: Markdown');
-  out.push('');
 }
 
 // ---------------------------------------------------------------------------
@@ -352,23 +373,25 @@ function sectionScanInfo(out) {
  * @param {{ cwd?: string }} [options]
  */
 export function render(result, options = {}) {
-  const { rootPath, entryPoints, configs = [], scripts = [], flatFiles } = result;
+  const { rootPath, projectType, entryPoints, configs = [], scripts = [], flatFiles, tree, importantFiles = [], health = [] } = result;
 
   const cwd     = options.cwd ?? process.cwd();
   const relRoot  = path.relative(cwd, rootPath) || '.';
-  const rootName = path.basename(rootPath) || relRoot;
+  const rootName = relRoot === '.' ? path.basename(rootPath) : relRoot;
 
   /** @type {string[]} */
   const out = [];
 
   sectionTitle(out);
   sectionSummary(out, result, relRoot);
+  sectionProjectHealth(out, health);
+  sectionImportantFiles(out, importantFiles);
+  sectionFrameworks(out, projectType);
   sectionEntryPoints(out, entryPoints);
   sectionConfigurationFiles(out, configs);
   sectionPackageScripts(out, scripts);
-  sectionFolderStructure(out, flatFiles, rootName);
   sectionStatistics(out, result);
-  sectionScanInfo(out);
+  sectionFolderStructure(out, tree, flatFiles.length, rootName);
 
   console.log(out.join('\n'));
 }

package/src/scanner/scan.js

@@ -20,8 +20,12 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { detectConfigs } from '../detectors/config-detector.js';
-import { detectScripts } from '../detectors/script-detector.js';
+import { detectConfigs }         from '../detectors/config-detector.js';
+import { detectScripts }         from '../detectors/script-detector.js';
+import { detectPackageManager }  from '../detectors/package-manager-detector.js';
+import { detectImportantFiles }  from '../detectors/important-files-detector.js';
+import { detectProjectInfo }     from '../detectors/project-info-detector.js';
+import { detectHealth }          from '../detectors/health-detector.js';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -99,7 +103,8 @@ const PROJECT_TYPE_MARKERS = [
  * @property {string}              projectType    - Detected project type label
  * @property {Array<string>}       entryPoints    - Relative paths of detected entry points
  * @property {Array<string>}       configs        - Relative paths of detected config files
- * @property {Array<{name: string, command: string}>} scripts - Parsed package scripts
+ * @property {Array<{name: string, command: string, category: string|null, description: string|null, usage: string}>} scripts - Parsed and enriched package scripts
+ * @property {string|null}         packageManager - Detected package manager, or null if none/ambiguous
  * @property {DirNode}             tree           - Full in-memory file tree
  * @property {Array<string>}       flatFiles      - All relative file paths (flat list)
  * @property {number}              totalFolders   - Total number of directories walked
@@ -186,7 +191,11 @@ function walkDirectory(dirPath, rootPath, flatFiles, includeHidden, maxFiles) {
       node.children.push(childNode);
     } else if (dirent.isFile()) {
       if (flatFiles.length >= maxFiles) {
-        throw new Error(`Max file scan limit exceeded (${maxFiles} files). Use --max-files <number> to increase the limit.`);
+        const err = new Error(`Max file scan limit exceeded (${maxFiles} files).`);
+        err.title = 'Scan limit exceeded';
+        err.detailLabel = 'Hint';
+        err.detailValue = 'Use --max-files <number> to increase the limit.';
+        throw err;
       }
       const relFilePath = toPosix(path.relative(rootPath, childPath));
 
@@ -449,8 +458,18 @@ export function scan(targetPath, options = {}) {
   let stat;
   try {
     stat = fs.statSync(rootPath);
-  } catch {
-    throw new Error(`Path does not exist: ${rootPath}`);
+  } catch (err) {
+    const error = new Error(`Path does not exist: ${rootPath}`);
+    if (err.code === 'EACCES' || err.code === 'EPERM') {
+      error.title = 'Permission denied';
+      error.message = 'You do not have permission to access the specified path.';
+    } else {
+      error.title = 'Invalid directory';
+      error.message = 'The specified path does not exist.';
+    }
+    error.detailLabel = 'Path';
+    error.detailValue = rootPath;
+    throw error;
   }
 
   /** @type {Array<string>} */
@@ -461,12 +480,17 @@ export function scan(targetPath, options = {}) {
   let configs = [];
   /** @type {Array<{name: string, command: string}>} */
   let scripts = [];
+  /** @type {string|null} */
+  let packageManager = null;
+  let importantFiles = [];
+  let projectInfo = null;
+  let health = [];
 
   const startTime   = performance.now();
   let tree;
   let projectType = 'Unknown';
   let totalFolders = 0;
-
+  
   if (stat.isDirectory()) {
     tree = walkDirectory(rootPath, rootPath, flatFiles, includeHidden, maxFiles);
     projectType = detectProjectType(rootPath);
@@ -474,7 +498,11 @@ export function scan(targetPath, options = {}) {
     totalFolders = countFolders(tree) - 1;
     entryPoints = findEntryPoints(projectType, flatFiles, rootPath);
     configs = detectConfigs(flatFiles).configs;
-    scripts = detectScripts(rootPath).scripts;
+    packageManager = detectPackageManager(flatFiles).packageManager;
+    scripts = detectScripts(rootPath, packageManager).scripts;
+    importantFiles = detectImportantFiles({ flatFiles, projectType, entryPoints, configs }).importantFiles;
+    projectInfo = detectProjectInfo({ rootPath, projectType, flatFiles, entryPoints, packageManager, scripts }).projectInfo;
+    health = detectHealth({ flatFiles, configs, importantFiles, scripts, projectType }).health;
   } else if (stat.isFile()) {
     const relFilePath = toPosix(path.basename(rootPath));
     tree = {
@@ -492,9 +520,18 @@ export function scan(targetPath, options = {}) {
     flatFiles.push(relFilePath);
     entryPoints = [relFilePath]; // A single file is its own entry point
     configs = detectConfigs(flatFiles).configs;
-    scripts = detectScripts(path.dirname(rootPath)).scripts;
+    packageManager = detectPackageManager(flatFiles).packageManager;
+    scripts = detectScripts(path.dirname(rootPath), packageManager).scripts;
+    importantFiles = detectImportantFiles({ flatFiles, projectType, entryPoints, configs }).importantFiles;
+    projectInfo = detectProjectInfo({ rootPath, projectType, flatFiles, entryPoints, packageManager, scripts }).projectInfo;
+    health = detectHealth({ flatFiles, configs, importantFiles, scripts, projectType }).health;
   } else {
-    throw new Error(`Path is neither a file nor a directory: ${rootPath}`);
+    const err = new Error(`Path is neither a file nor a directory: ${rootPath}`);
+    err.title = 'Unsupported path type';
+    err.message = 'The specified path is neither a file nor a directory.';
+    err.detailLabel = 'Path';
+    err.detailValue = rootPath;
+    throw err;
   }
 
   const scanDurationMs = performance.now() - startTime;
@@ -505,6 +542,10 @@ export function scan(targetPath, options = {}) {
     entryPoints,
     configs,
     scripts,
+    packageManager,
+    importantFiles,
+    projectInfo,
+    health,
     tree,
     flatFiles,
     totalFolders,