@lakindu_perera/toren 1.0.5 → 1.0.7

package/src/renderers/json-renderer.js

@@ -1,57 +1,153 @@
 /**
  * @fileoverview Toren — JSON Renderer
  *
- * Consumes a ScanResult and produces a clean JSON object for programmatic use.
+ * Consumes a ScanResult and produces a stable, consistently-ordered JSON
+ * object suitable for programmatic consumption.
+ *
+ * Design contract (mirrors all other renderers):
+ *  - Accepts a ScanResult and an optional options object.
+ *  - Never scans files or modifies the data it receives.
+ *  - All arrays are always present — never undefined or missing.
+ *  - Property order is fixed and documented below.
+ *  - Backward compatible: no existing field is removed or renamed.
+ *
+ * Output property order:
+ *  1. meta          — schema version + generator provenance
+ *  2. project       — name (basename), path (relative), detected type
+ *  3. frameworks    — derived array of detected frameworks ([] when none)
+ *  4. entryPoints   — array of detected entry-point paths
+ *  5. configs       — array of detected configuration file paths
+ *  6. scripts       — array of { name, command } objects
+ *  7. statistics    — file/folder counts and scan duration (structured)
+ *  8. structure     — recursive file-tree array
+ *  9. summary       — retained for backward compatibility (same data as statistics)
  */
 
 import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const pkg     = require('../../package.json');
+
+// ---------------------------------------------------------------------------
+// Tree mapper
+// ---------------------------------------------------------------------------
 
+/**
+ * Recursively map an internal DirNode / FileNode to a clean JSON shape.
+ * Directory nodes always include a `children` array (never undefined).
+ *
+ * @param {import('../scanner/scan.js').DirNode | import('../scanner/scan.js').FileNode} node
+ * @returns {{ type: 'folder'|'file', name: string, children?: object[] }}
+ */
 function mapTree(node) {
   if (node.type === 'directory') {
     return {
-      type: 'folder',
-      name: node.name,
-      children: (node.children || []).map(mapTree)
-    };
-  } else {
-    return {
-      type: 'file',
-      name: node.name
+      type:     'folder',
+      name:     node.name,
+      children: (node.children || []).map(mapTree),
     };
   }
+  return {
+    type: 'file',
+    name: node.name,
+  };
 }
 
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive a `frameworks` array from the scanner's `projectType` string.
+ * Returns a single-element array when a framework is detected, empty otherwise.
+ * This is a pure presentation decision — no business logic is added.
+ *
+ * @param {string} projectType
+ * @returns {string[]}
+ */
+function deriveFrameworks(projectType) {
+  if (!projectType || projectType === 'Unknown') return [];
+  return [projectType];
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Render a ScanResult as a stable JSON document to stdout.
+ *
+ * @param {import('../scanner/scan.js').ScanResult} result
+ * @param {{ cwd?: string }} [options]
+ */
 export function render(result, options = {}) {
   const {
     rootPath,
     projectType,
-    entryPoints,
-    configs = [],
-    scripts = [],
+    entryPoints   = [],
+    configs       = [],
+    scripts       = [],
     tree,
-    flatFiles,
-    totalFolders,
+    flatFiles     = [],
+    totalFolders  = 0,
     scanDurationMs,
   } = result;
 
-  const cwd = options.cwd ?? process.cwd();
-  const relRoot = path.relative(cwd, rootPath) || '.';
+  const cwd      = options.cwd ?? process.cwd();
+  const relRoot   = path.relative(cwd, rootPath) || '.';
+  const rootName  = path.basename(rootPath) || relRoot;
+
+  // Shared statistics values — computed once, used in both `statistics` and
+  // the backward-compatible `summary` block.
+  // Guard against NaN/undefined: JSON.stringify(NaN) produces null, breaking
+  // the schema guarantee that durationMs is always a number.
+  const totalFiles = flatFiles.length;
+  const durationMs = Number.isFinite(scanDurationMs) ? Math.round(scanDurationMs) : 0;
 
   const output = {
+    // 1. Provenance — lets consumers detect schema changes.
+    meta: {
+      generatedBy: 'Toren',
+      version:     pkg.version,
+      schema:      1,
+    },
+
+    // 2. Project identity — name is the human-readable basename; path is the
+    //    relative path used for filesystem resolution.
     project: {
+      name: rootName,
       path: relRoot,
       type: projectType,
-      framework: projectType,
     },
+
+    // 3. Detected frameworks — always an array.
+    frameworks: deriveFrameworks(projectType),
+
+    // 4–6. Discovery results — all arrays, always present, never null.
+    entryPoints: Array.isArray(entryPoints) ? entryPoints : [],
+    configs:     Array.isArray(configs)     ? configs     : [],
+    scripts:     Array.isArray(scripts)     ? scripts     : [],
+
+    // 7. Structured statistics — always a complete object with numeric values.
+    //    durationMs is rounded to the nearest millisecond (integer).
+    statistics: {
+      files:     totalFiles,
+      folders:   totalFolders,
+      durationMs,
+    },
+
+    // 8. File-tree — array of root-level nodes; always present.
+    //    Empty array when the scanned directory is empty.
+    structure: (tree?.children || []).map(mapTree),
+
+    // 9. Backward-compatible summary block — preserved for existing consumers.
+    //    Contains the same data under the original field names.
     summary: {
-      totalFiles: flatFiles.length,
+      totalFiles,
       totalFolders,
-      scanDurationMs: Math.round(scanDurationMs),
+      scanDurationMs: durationMs,
     },
-    entryPoints,
-    configs,
-    scripts,
-    structure: (tree.children || []).map(mapTree)
   };
 
   console.log(JSON.stringify(output, null, 2));

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('---');
 }
 
 /**
@@ -206,7 +180,7 @@ function sectionSummary(out, result, relRoot) {
   const { projectType, flatFiles, totalFolders } = result;
 
   out.push('');
-  out.push('## Project Summary');
+  out.push('## Project');
   out.push('');
   out.push(markdownTable([
     ['Project Type', projectType],
@@ -214,8 +188,26 @@ function sectionSummary(out, result, relRoot) {
     ['Total Files',  String(flatFiles.length)],
     ['Total Folders', String(totalFolders)],
   ]));
+}
+
+/**
+ * @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 +216,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,9 +226,6 @@ function sectionConfigurationFiles(out, configs) {
       out.push(`- ${c}`);
     }
   }
-
-  out.push('');
-  out.push('---');
 }
 
 /**
@@ -245,21 +234,16 @@ function sectionConfigurationFiles(out, configs) {
  */
 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}\` |`);
+      out.push(`- ${s.name}: ${s.command}`);
     }
   }
-
-  out.push('');
-  out.push('---');
 }
 
 /**
@@ -275,35 +259,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 +299,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 +315,23 @@ 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 } = 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);
+  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

@@ -186,7 +186,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 +453,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>} */
@@ -494,7 +508,12 @@ export function scan(targetPath, options = {}) {
     configs = detectConfigs(flatFiles).configs;
     scripts = detectScripts(path.dirname(rootPath)).scripts;
   } 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;