@lakindu_perera/toren 1.0.5 → 1.0.8

package/src/renderers/html-renderer.js

@@ -31,34 +31,6 @@ import path from 'node:path';
 // Tree builder (plain-text, HTML-safe — same algorithm as markdown-renderer)
 // ---------------------------------------------------------------------------
 
-/**
- * Build an in-memory nested tree from a flat list of relative file paths.
- *
- * @param {string[]} flatFiles - Relative file paths produced by scan()
- * @returns {{ type: string, children: Record<string, object> }}
- */
-function buildInternalTree(flatFiles) {
-  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.
@@ -80,10 +52,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) => {
-      if (a.type !== b.type) return a.type === 'directory' ? -1 : 1;
-      return a.name.localeCompare(b.name);
-    });
+    const children = node.children || [];
 
     if (depth === maxDepth - 1 && children.length > 0) {
       lines.push(`${prefix}${childPad}└── ...`);
@@ -104,21 +73,18 @@ function serializeNode(node, prefix, isLast, lines, depth = 0, maxDepth = 5) {
 }
 
 /**
- * Convert a flat file list into a plain-text tree string.
+ * Convert a ScanResult tree into a plain-text tree string.
  *
- * @param {string[]} flatFiles
+ * @param {import('../scanner/scan.js').DirNode} tree
  * @param {string}   rootName
+ * @param {number}   totalFiles
  * @returns {string}
  */
-function buildTreeString(flatFiles, rootName) {
-  if (flatFiles.length === 0) return 'No files scanned.';
+function buildTreeString(tree, rootName, totalFiles) {
+  if (totalFiles === 0) return 'No files scanned.';
 
-  const root     = buildInternalTree(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);
@@ -148,12 +114,13 @@ function esc(value) {
 
 /**
  * Format a scan duration in milliseconds to a human-readable string.
+ * Returns plain text only — callers are responsible for HTML-escaping via esc().
  *
  * @param {number} ms
  * @returns {string}
  */
 function formatDuration(ms) {
-  if (ms < 1)     return '&lt; 1 ms';
+  if (ms < 1)     return '< 1 ms';
   if (ms >= 1000) return `${(ms / 1000).toFixed(2)} s`;
   return `${Math.round(ms)} ms`;
 }
@@ -632,6 +599,19 @@ const icon = {
 // Section builders (one function per report section)
 // ---------------------------------------------------------------------------
 
+/**
+ * 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];
+}
+
 /**
  * Render the gradient page header.
  *
@@ -696,7 +676,7 @@ function renderSummaryCards(result) {
     {
       label: 'Scan Duration',
       icon:  icon.clock(),
-      value: formatDuration(scanDurationMs),
+      value: esc(formatDuration(scanDurationMs)),
       isText: true,
       sub:   'wall-clock time',
     },
@@ -715,6 +695,41 @@ function renderSummaryCards(result) {
   return `<div class="cards">${cardHTML}</div>`;
 }
 
+/**
+ * Render the frameworks section.
+ *
+ * @param {string} projectType
+ * @returns {string}
+ */
+function renderFrameworks(projectType) {
+  const frameworks = deriveFrameworks(projectType);
+  const count      = frameworks.length;
+
+  const body = count === 0
+    ? `<p class="empty-msg">No frameworks detected.</p>`
+    : `<ul class="entry-list">
+        ${frameworks.map(fw => `
+          <li class="entry-item">
+            <span class="entry-dot"></span>
+            ${esc(fw)}
+          </li>`).join('')}
+       </ul>`;
+
+  const countBadge = count > 0
+    ? `<span class="section-count">${count} found</span>`
+    : '';
+
+  return `
+  <section class="section">
+    <div class="section-header">
+      <div class="section-icon">${icon.code()}</div>
+      <h2 class="section-title">Frameworks</h2>
+      ${countBadge}
+    </div>
+    <div class="section-body">${body}</div>
+  </section>`;
+}
+
 /**
  * Render the entry points section.
  *
@@ -739,14 +754,14 @@ function renderEntryPoints(entryPoints) {
     : '';
 
   return `
-  <div class="section">
+  <section class="section">
     <div class="section-header">
       <div class="section-icon">${icon.door()}</div>
-      <span class="section-title">Entry Points</span>
+      <h2 class="section-title">Entry Points</h2>
       ${countBadge}
     </div>
     <div class="section-body">${body}</div>
-  </div>`;
+  </section>`;
 }
 
 /**
@@ -773,14 +788,14 @@ function renderConfigurationFiles(configs) {
     : '';
 
   return `
-  <div class="section">
+  <section class="section">
     <div class="section-header">
       <div class="section-icon">${icon.file()}</div>
-      <span class="section-title">Configuration Files</span>
+      <h2 class="section-title">Configuration Files</h2>
       ${countBadge}
     </div>
     <div class="section-body">${body}</div>
-  </div>`;
+  </section>`;
 }
 
 /**
@@ -789,6 +804,118 @@ function renderConfigurationFiles(configs) {
  * @param {Array<{name: string, command: string}>} scripts
  * @returns {string}
  */
+function renderProjectInfo(projectInfo, packageManager) {
+  const rows = [];
+  if (projectInfo?.name) rows.push(['Name', projectInfo.name]);
+  if (packageManager) rows.push(['Package Manager', packageManager]);
+  if (projectInfo?.runtime) rows.push(['Runtime', projectInfo.runtime]);
+  if (projectInfo?.language) rows.push(['Language', projectInfo.language]);
+  if (projectInfo?.architecture) rows.push(['Architecture', projectInfo.architecture]);
+  if (projectInfo?.framework) rows.push(['Framework', projectInfo.framework]);
+  if (projectInfo?.entryPoint) rows.push(['Entry Point', projectInfo.entryPoint]);
+  if (projectInfo?.sourceDirectory) rows.push(['Source Directory', projectInfo.sourceDirectory]);
+
+  if (rows.length === 0) return '';
+
+  const rowsHTML = rows.map(([prop, value]) => `
+    <tr>
+      <td>${esc(prop)}</td>
+      <td class="val-plain">${esc(value)}</td>
+    </tr>`).join('');
+
+  return `
+  <section class="section">
+    <div class="section-header">
+      <div class="section-icon">${icon.info()}</div>
+      <h2 class="section-title">Project Info</h2>
+    </div>
+    <div class="section-body" style="padding:0">
+      <table class="data-table">
+        <thead>
+          <tr>
+            <th>Property</th>
+            <th style="text-align:right">Value</th>
+          </tr>
+        </thead>
+        <tbody>${rowsHTML}</tbody>
+      </table>
+    </div>
+  </section>`;
+}
+
+function renderImportantFiles(importantFiles) {
+  const count = importantFiles.length;
+
+  const body = count === 0
+    ? `<p class="empty-msg" style="padding: 1.5rem">No important files detected.</p>`
+    : `<table class="data-table">
+        <thead>
+          <tr>
+            <th>Path</th>
+            <th>Reason</th>
+          </tr>
+        </thead>
+        <tbody>
+          ${importantFiles.map(f => `
+            <tr>
+              <td><code>${esc(f.path)}</code></td>
+              <td class="val-plain">${esc(f.reason)}</td>
+            </tr>`).join('')}
+        </tbody>
+       </table>`;
+
+  const countBadge = count > 0
+    ? `<span class="section-count">${count} found</span>`
+    : '';
+
+  return `
+  <section class="section">
+    <div class="section-header">
+      <div class="section-icon">${icon.file()}</div>
+      <h2 class="section-title">Important Files</h2>
+      ${countBadge}
+    </div>
+    <div class="section-body" style="padding:0">
+      ${body}
+    </div>
+  </section>`;
+}
+
+function renderProjectHealth(health) {
+  const count = health.length;
+
+  const body = count === 0
+    ? `<p class="empty-msg" style="padding: 1.5rem">No project health observations available.</p>`
+    : `<ul class="entry-list">
+        ${health.map(h => {
+          let emoji = 'ℹ';
+          if (h.status === 'pass') emoji = '✓';
+          else if (h.status === 'warning') emoji = '⚠';
+          return `
+          <li class="entry-item">
+            <span>${esc(emoji)}</span>
+            ${esc(h.message)}
+          </li>`;
+        }).join('')}
+       </ul>`;
+
+  const countBadge = count > 0
+    ? `<span class="section-count">${count} observations</span>`
+    : '';
+
+  return `
+  <section class="section">
+    <div class="section-header">
+      <div class="section-icon">${icon.info()}</div>
+      <h2 class="section-title">Project Health</h2>
+      ${countBadge}
+    </div>
+    <div class="section-body">
+      ${body}
+    </div>
+  </section>`;
+}
+
 function renderPackageScripts(scripts) {
   const count = scripts.length;
 
@@ -797,16 +924,21 @@ function renderPackageScripts(scripts) {
     : `<table class="data-table">
         <thead>
           <tr>
-            <th>Script</th>
+            <th>Usage</th>
+            <th>Description</th>
             <th>Command</th>
           </tr>
         </thead>
         <tbody>
-          ${scripts.map(s => `
+          ${scripts.map(s => {
+            const usage = s.usage || `npm run ${s.name}`;
+            return `
             <tr>
-              <td><code>${esc(s.name)}</code></td>
+              <td><code>${esc(usage)}</code></td>
+              <td class="val-plain">${esc(s.description || '')}</td>
               <td class="val-plain"><code>${esc(s.command)}</code></td>
-            </tr>`).join('')}
+            </tr>`;
+          }).join('')}
         </tbody>
        </table>`;
 
@@ -815,31 +947,34 @@ function renderPackageScripts(scripts) {
     : '';
 
   return `
-  <div class="section">
+  <section class="section">
     <div class="section-header">
       <div class="section-icon">${icon.terminal()}</div>
-      <span class="section-title">Package Scripts</span>
+      <h2 class="section-title">Package Scripts</h2>
       ${countBadge}
     </div>
-    <div class="section-body" style="padding:0">${body}</div>
-  </div>`;
+    <div class="section-body" style="padding:0">
+      ${body}
+    </div>
+  </section>`;
 }
 
 /**
- * Render the folder structure section with a dark <pre><code> tree.
+ * Render the folder structure section.
  *
+ * @param {import('../scanner/scan.js').DirNode} tree
  * @param {string[]} flatFiles
- * @param {string}   rootName
+ * @param {string} rootName
  * @returns {string}
  */
-function renderFolderStructure(flatFiles, rootName) {
-  const treeStr = buildTreeString(flatFiles, rootName);
+function renderFolderStructure(tree, flatFiles, rootName) {
+  const treeStr = buildTreeString(tree, rootName, flatFiles.length);
 
   return `
-  <div class="section">
+  <section class="section">
     <div class="section-header">
       <div class="section-icon">${icon.tree()}</div>
-      <span class="section-title">Folder Structure</span>
+      <h2 class="section-title">Folder Structure</h2>
       ${flatFiles.length > 0 ? `<span class="section-count">${flatFiles.length} files</span>` : ''}
     </div>
     <div class="section-body">
@@ -847,7 +982,7 @@ function renderFolderStructure(flatFiles, rootName) {
         <pre><code>${esc(treeStr)}</code></pre>
       </div>
     </div>
-  </div>`;
+  </section>`;
 }
 
 /**
@@ -868,14 +1003,14 @@ function renderStats(result) {
   const rowsHTML = rows.map(([metric, value, isNum]) => `
     <tr>
       <td>${esc(metric)}</td>
-      <td class="${isNum ? 'val' : 'val-plain'}">${value}</td>
+      <td class="${isNum ? 'val' : 'val-plain'}">${esc(value)}</td>
     </tr>`).join('');
 
   return `
-  <div class="section">
+  <section class="section">
     <div class="section-header">
       <div class="section-icon">${icon.bar()}</div>
-      <span class="section-title">Statistics</span>
+      <h2 class="section-title">Statistics</h2>
     </div>
     <div class="section-body">
       <table class="data-table">
@@ -888,7 +1023,7 @@ function renderStats(result) {
         <tbody>${rowsHTML}</tbody>
       </table>
     </div>
-  </div>`;
+  </section>`;
 }
 
 /**
@@ -909,17 +1044,17 @@ function renderScanInfo() {
     </tr>`).join('');
 
   return `
-  <div class="section">
+  <section class="section">
     <div class="section-header">
       <div class="section-icon">${icon.info()}</div>
-      <span class="section-title">Scan Information</span>
+      <h2 class="section-title">Scan Information</h2>
     </div>
     <div class="section-body">
       <table class="data-table">
         <tbody>${rowsHTML}</tbody>
       </table>
     </div>
-  </div>`;
+  </section>`;
 }
 
 /**
@@ -950,7 +1085,7 @@ function renderFooter() {
  * @param {{ cwd?: string }} [options]
  */
 export function render(result, options = {}) {
-  const { rootPath, projectType, entryPoints, configs = [], scripts = [], flatFiles } = result;
+  const { rootPath, projectType, entryPoints, configs = [], scripts = [], flatFiles, tree, importantFiles = [], health = [], projectInfo, packageManager } = result;
 
   const cwd      = options.cwd ?? process.cwd();
   const relRoot  = path.relative(cwd, rootPath) || '.';
@@ -974,11 +1109,15 @@ export function render(result, options = {}) {
 
     <main>
       ${renderSummaryCards(result)}
+      ${renderProjectInfo(projectInfo, packageManager)}
+      ${renderProjectHealth(health)}
+      ${renderImportantFiles(importantFiles)}
+      ${renderFrameworks(projectType)}
       ${renderEntryPoints(entryPoints)}
       ${renderConfigurationFiles(configs)}
       ${renderPackageScripts(scripts)}
-      ${renderFolderStructure(flatFiles, rootName)}
       ${renderStats(result)}
+      ${renderFolderStructure(tree, flatFiles, rootName)}
       ${renderScanInfo()}
     </main>
 

package/src/renderers/json-renderer.js

@@ -1,57 +1,167 @@
 /**
  * @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       = [],
+    packageManager,
+    importantFiles = [],
+    projectInfo = null,
+    health        = [],
     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: (projectInfo && projectInfo.name) ? projectInfo.name : rootName,
       path: relRoot,
       type: projectType,
-      framework: projectType,
+      packageManager: packageManager || null,
+      runtime: projectInfo ? projectInfo.runtime : null,
+      language: projectInfo ? projectInfo.language : null,
+      framework: projectInfo ? projectInfo.framework : null,
+      architecture: projectInfo ? projectInfo.architecture : null,
+      entryPoint: projectInfo ? projectInfo.entryPoint : null,
+      sourceDirectory: projectInfo ? projectInfo.sourceDirectory : null,
     },
+
+    // 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     : [],
+    
+    importantFiles: Array.isArray(importantFiles) ? importantFiles : [],
+    health:         Array.isArray(health)         ? health         : [],
+
+    // 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));