@lakindu_perera/toren 1.0.7 → 1.0.8

package/src/detectors/project-info-detector.js

@@ -0,0 +1,89 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Detect project info from the scanned repository.
+ */
+export function detectProjectInfo({
+  rootPath,
+  projectType,
+  flatFiles,
+  entryPoints,
+  packageManager,
+  scripts
+}) {
+  const fileSet = new Set(flatFiles);
+
+  let name = null;
+  const pkgPath = path.join(rootPath, 'package.json');
+  try {
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      if (pkg.name) name = pkg.name;
+    }
+  } catch {}
+  if (!name) {
+    name = path.basename(rootPath) || null;
+  }
+
+  let runtime = null;
+  const pt = projectType.toLowerCase();
+  if (pt.includes('node') || fileSet.has('package.json')) runtime = 'Node.js';
+  else if (pt.includes('python')) runtime = 'Python';
+  else if (pt.includes('java') || pt.includes('spring')) runtime = 'JVM / Java';
+  else if (pt.includes('go')) runtime = 'Go';
+  else if (pt.includes('rust')) runtime = 'Rust';
+  else if (pt.includes('ruby')) runtime = 'Ruby';
+  else if (pt.includes('php') || pt.includes('composer')) runtime = 'PHP';
+  else if (pt.includes('elixir') || pt.includes('phoenix')) runtime = 'Erlang / BEAM';
+
+  let language = null;
+  if (fileSet.has('tsconfig.json') || pt.includes('angular')) {
+    language = 'TypeScript';
+  } else if (fileSet.has('package.json') && !fileSet.has('tsconfig.json')) {
+    language = 'JavaScript';
+  } else if (pt.includes('python')) language = 'Python';
+  else if (pt.includes('java') || pt.includes('spring')) language = 'Java';
+  else if (pt.includes('go')) language = 'Go';
+  else if (pt.includes('rust')) language = 'Rust';
+  else if (pt.includes('ruby')) language = 'Ruby';
+  else if (pt.includes('php')) language = 'PHP';
+  else if (pt.includes('elixir')) language = 'Elixir';
+
+  let framework = null;
+  if (projectType && projectType !== 'Unknown') {
+    framework = projectType;
+  }
+
+  let architecture = null;
+  if (pt.includes('next')) {
+    const hasApp = Array.from(fileSet).some(f => f.startsWith('app/'));
+    const hasPages = Array.from(fileSet).some(f => f.startsWith('pages/'));
+    if (hasApp && hasPages) architecture = 'Hybrid App/Pages Router';
+    else if (hasApp) architecture = 'App Router';
+    else if (hasPages) architecture = 'Pages Router';
+  }
+
+  const entryPoint = entryPoints.length > 0 ? entryPoints[0] : null;
+
+  let sourceDirectory = null;
+  if (entryPoint) {
+    if (entryPoint.startsWith('src/')) sourceDirectory = 'src';
+    else if (entryPoint.startsWith('app/')) sourceDirectory = 'app';
+    else if (entryPoint.startsWith('pages/')) sourceDirectory = 'pages';
+  }
+
+  return {
+    projectInfo: {
+      name,
+      projectType,
+      runtime,
+      language,
+      framework,
+      architecture,
+      packageManager,
+      entryPoint,
+      sourceDirectory
+    }
+  };
+}

package/src/detectors/script-detector.js

@@ -1,30 +1,246 @@
-import fs from 'node:fs';
+/**
+ * @fileoverview Toren — Script Detector with Intelligence Layer
+ *
+ * Reads package.json scripts and enriches each entry with:
+ *  - category  — functional grouping (development, build, testing, etc.)
+ *  - description — human-readable purpose string
+ *  - usage — ready-to-run command string for the detected package manager
+ *
+ * Design contract:
+ *  - Backward compatible: name and command are always present and unchanged.
+ *  - category and description are null when no deterministic match exists.
+ *  - usage is always a string — derived from packageManager or falls back to
+ *    "npm run <name>" when packageManager is null.
+ *  - Descriptions are never fabricated. Only canonical mappings and known
+ *    command-keyword inferences are used.
+ *  - Deterministic: same input always produces the same output.
+ *  - Graceful: malformed or missing package.json returns an empty array.
+ *
+ * @module detectors/script-detector
+ */
+
+import fs   from 'node:fs';
 import path from 'node:path';
 
+// ---------------------------------------------------------------------------
+// Description and category tables — keyed by exact script name (lowercase)
+// ---------------------------------------------------------------------------
+
+/**
+ * Maps a known script name to its canonical human-readable description.
+ * @type {Map<string, string>}
+ */
+const NAME_DESCRIPTIONS = new Map([
+  ['dev',        'Start the development server'],
+  ['develop',    'Start the development server'],
+  ['start',      'Start the application'],
+  ['serve',      'Serve the application'],
+  ['preview',    'Preview the production build'],
+  ['build',      'Create a production build'],
+  ['test',       'Run the test suite'],
+  ['test:watch', 'Run tests in watch mode'],
+  ['test:e2e',   'Run end-to-end tests'],
+  ['lint',       'Run code-quality checks'],
+  ['lint:fix',   'Run code-quality checks and fix supported issues'],
+  ['format',     'Format the codebase'],
+  ['typecheck',  'Run static type checks'],
+  ['check',      'Run project checks'],
+  ['clean',      'Remove generated build artifacts'],
+  ['generate',   'Generate project files or code'],
+  ['migrate',    'Run database migrations'],
+  ['seed',       'Seed the database'],
+  ['deploy',     'Deploy the application'],
+]);
+
+/**
+ * Maps a known script name to its functional category.
+ * @type {Map<string, string>}
+ */
+const NAME_CATEGORIES = new Map([
+  ['dev',        'development'],
+  ['develop',    'development'],
+  ['start',      'development'],
+  ['serve',      'development'],
+  ['preview',    'development'],
+  ['build',      'build'],
+  ['test',       'testing'],
+  ['test:watch', 'testing'],
+  ['test:e2e',   'testing'],
+  ['lint',       'quality'],
+  ['lint:fix',   'quality'],
+  ['format',     'quality'],
+  ['typecheck',  'quality'],
+  ['check',      'quality'],
+  ['clean',      'utility'],
+  ['generate',   'utility'],
+  ['migrate',    'database'],
+  ['seed',       'database'],
+  ['deploy',     'deployment'],
+]);
+
+// ---------------------------------------------------------------------------
+// Command-keyword inference — ordered most-specific first
+// ---------------------------------------------------------------------------
+
+/**
+ * Ordered list of command-keyword → { description, category } inferences.
+ * Evaluated only when a script name has no entry in NAME_DESCRIPTIONS.
+ * More specific patterns (e.g. "playwright test") must appear before broader
+ * ones (e.g. "jest") to prevent false matches.
+ *
+ * @type {Array<{ keyword: string, description: string, category: string }>}
+ */
+const COMMAND_INFERENCE = [
+  { keyword: 'playwright test', description: 'Run end-to-end tests',                          category: 'testing'     },
+  { keyword: 'cypress run',     description: 'Run end-to-end tests',                          category: 'testing'     },
+  { keyword: 'vitest',          description: 'Run the test suite',                            category: 'testing'     },
+  { keyword: 'jest',            description: 'Run the test suite',                            category: 'testing'     },
+  { keyword: 'tsc --noEmit',    description: 'Run static type checks',                        category: 'quality'     },
+  { keyword: 'eslint',          description: 'Run code-quality checks',                       category: 'quality'     },
+  { keyword: 'prettier',        description: 'Format the codebase',                           category: 'quality'     },
+];
+
+// ---------------------------------------------------------------------------
+// Usage builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Script names that npm treats as built-in lifecycle commands.
+ * These do NOT need the "run" subcommand: `npm test`, `npm start`, etc.
+ * @type {Set<string>}
+ */
+const NPM_LIFECYCLE = new Set(['test', 'start', 'stop', 'restart']);
+
+/**
+ * Script names that bun exposes as direct subcommands (no "run" needed).
+ * @type {Set<string>}
+ */
+const BUN_LIFECYCLE = new Set(['test', 'start']);
+
+/**
+ * Build the ready-to-run usage string for a script.
+ *
+ * Rules:
+ *  npm:  lifecycle commands (test, start…) → `npm <name>`
+ *        all others                        → `npm run <name>`
+ *  pnpm: all scripts                       → `pnpm <name>`   (pnpm forwards directly)
+ *  yarn: all scripts                       → `yarn <name>`
+ *  bun:  lifecycle commands (test, start)  → `bun <name>`
+ *        all others                        → `bun run <name>`
+ *  null: conservative fallback             → `npm run <name>` (always valid)
+ *
+ * @param {string}      name           - Script name
+ * @param {string|null} packageManager - Detected package manager or null
+ * @returns {string}
+ */
+function buildUsage(name, packageManager) {
+  switch (packageManager) {
+    case 'npm':
+      return NPM_LIFECYCLE.has(name) ? `npm ${name}` : `npm run ${name}`;
+
+    case 'pnpm':
+      // pnpm forwards all script names without requiring the 'run' sub-command.
+      return `pnpm ${name}`;
+
+    case 'yarn':
+      // yarn similarly runs scripts directly without 'run'.
+      return `yarn ${name}`;
+
+    case 'bun':
+      return BUN_LIFECYCLE.has(name) ? `bun ${name}` : `bun run ${name}`;
+
+    default:
+      // null or unknown — conservative: `npm run <name>` is always valid even
+      // for lifecycle names, so we keep it unconditionally safe.
+      return `npm run ${name}`;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Description + category resolver
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve description and category for a single script entry.
+ * Priority: exact name match → command-keyword inference → null.
+ *
+ * @param {string} name
+ * @param {string} command
+ * @returns {{ description: string|null, category: string|null }}
+ */
+function resolveIntelligence(name, command) {
+  // 1. Exact name match (canonical mapping — highest confidence).
+  const nameDescription = NAME_DESCRIPTIONS.get(name) ?? null;
+  const nameCategory    = NAME_CATEGORIES.get(name)    ?? null;
+
+  if (nameDescription !== null || nameCategory !== null) {
+    return { description: nameDescription, category: nameCategory };
+  }
+
+  // 2. Command-keyword inference (fallback — only for unknown names).
+  for (const { keyword, description, category } of COMMAND_INFERENCE) {
+    if (command.includes(keyword)) {
+      return { description, category };
+    }
+  }
+
+  // 3. Unknown — do not fabricate.
+  return { description: null, category: null };
+}
+
+// ---------------------------------------------------------------------------
+// Types (JSDoc — no TypeScript dependency required)
+// ---------------------------------------------------------------------------
+
 /**
- * Detects npm/package scripts from package.json in the project root.
+ * @typedef {Object} ScriptItem
+ * @property {string}      name          - Script name as declared in package.json
+ * @property {string}      command       - Raw script command string
+ * @property {string|null} category      - Functional category, or null when unknown
+ * @property {string|null} description   - Human-readable purpose, or null when unknown
+ * @property {string}      usage         - Ready-to-run invocation string
+ */
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect and enrich npm/package scripts from package.json.
  *
- * @param {string} rootPath - The absolute path of the scanned root
- * @returns {{ scripts: Array<{name: string, command: string}> }}
+ * The `packageManager` parameter is optional for backward compatibility.
+ * When omitted (or null), usage strings fall back to `npm run <name>`.
+ *
+ * @param {string}      rootPath       - Absolute path of the scanned root
+ * @param {string|null} [packageManager=null] - Detected package manager name
+ * @returns {{ scripts: ScriptItem[] }}
  */
-export function detectScripts(rootPath) {
+export function detectScripts(rootPath, packageManager = null) {
   const scripts = [];
   const pkgPath = path.join(rootPath, 'package.json');
 
   try {
     if (fs.existsSync(pkgPath)) {
       const content = fs.readFileSync(pkgPath, 'utf8');
-      const pkg = JSON.parse(content);
+      const pkg     = JSON.parse(content);
 
       if (pkg.scripts && typeof pkg.scripts === 'object') {
         for (const [name, command] of Object.entries(pkg.scripts)) {
-          if (typeof command === 'string') {
-            scripts.push({ name, command });
-          }
+          if (typeof command !== 'string') continue;
+
+          const { description, category } = resolveIntelligence(name, command);
+
+          scripts.push({
+            name,
+            command,
+            category,
+            description,
+            usage: buildUsage(name, packageManager),
+          });
         }
       }
     }
-  } catch (error) {
+  } catch {
     // Return empty scripts on malformed or unreadable package.json
   }
 

package/src/focused-output.js

@@ -22,10 +22,12 @@ import { renderStructure } from './renderers/console-renderer.js';
 // ---------------------------------------------------------------------------
 
 const EMPTY = {
-  frameworks:  'No frameworks detected.',
-  entryPoints: 'No entry points detected.',
-  configs:     'No configuration files detected.',
-  scripts:     'No package scripts detected.',
+  frameworks:     'No frameworks detected.',
+  entryPoints:    'No entry points detected.',
+  configs:        'No configuration files detected.',
+  scripts:        'No package scripts detected.',
+  importantFiles: 'No important files detected.',
+  health:         'No project health observations available.',
 };
 
 export const FOCUSED_FLAGS = [
@@ -34,7 +36,10 @@ export const FOCUSED_FLAGS = [
   '--entry-points',
   '--structure',
   '--configs',
-  '--scripts'
+  '--scripts',
+  '--summary',
+  '--important-files',
+  '--health'
 ];
 
 /**
@@ -133,14 +138,79 @@ export function renderFocusedMode(mode, result) {
     case '--scripts': {
       const scriptsList = [];
       if (result.scripts && result.scripts.length > 0) {
-        const maxNameLen = Math.max(...result.scripts.map(s => s.name.length));
         for (const s of result.scripts) {
-          const paddedName = s.name.padEnd(maxNameLen, ' ');
-          scriptsList.push(`\x1b[97m${paddedName}\x1b[0m  \x1b[2m${s.command}\x1b[0m`);
+          const usage = s.usage || `npm run ${s.name}`;
+          scriptsList.push(`\x1b[97m${usage}\x1b[0m`);
+          if (s.description) {
+            scriptsList.push(`  \x1b[2m${s.description}\x1b[0m\n`);
+          } else {
+            scriptsList.push(`  \x1b[2m${s.command}\x1b[0m\n`);
+          }
         }
       }
+      // Remove trailing newline from last element if it exists
+      if (scriptsList.length > 0) {
+        scriptsList[scriptsList.length - 1] = scriptsList[scriptsList.length - 1].replace(/\n$/, '');
+      }
       section('Package Scripts', scriptsList, EMPTY.scripts);
       break;
     }
+
+    case '--summary': {
+      const p = result.projectInfo || {};
+      const lines = [
+        `Name             ${p.name || 'Unknown'}`,
+        `Type             ${result.projectType || 'Unknown'}`,
+      ];
+      if (p.runtime) lines.push(`Runtime          ${p.runtime}`);
+      if (p.language) lines.push(`Language         ${p.language}`);
+      if (p.framework) lines.push(`Framework        ${p.framework}`);
+      if (p.architecture) lines.push(`Architecture     ${p.architecture}`);
+      if (result.packageManager) lines.push(`Package Manager  ${result.packageManager}`);
+      if (p.entryPoint) lines.push(`Entry Point      ${p.entryPoint}`);
+      if (p.sourceDirectory) lines.push(`Source Directory ${p.sourceDirectory}`);
+      
+      lines.push(`Files            ${result.flatFiles ? result.flatFiles.length : 0}`);
+      lines.push(`Folders          ${result.totalFolders || 0}`);
+      
+      section('Project Summary', lines, 'No summary available.');
+      break;
+    }
+
+    case '--important-files': {
+      const items = [];
+      if (result.importantFiles && result.importantFiles.length > 0) {
+        const top10 = result.importantFiles.slice(0, 10);
+        top10.forEach((f, idx) => {
+          items.push(`${idx + 1}. \x1b[97m${f.path}\x1b[0m`);
+          items.push(`   \x1b[2m${f.reason}\x1b[0m\n`);
+        });
+        // Remove trailing newline
+        if (items.length > 0) {
+          items[items.length - 1] = items[items.length - 1].replace(/\n$/, '');
+        }
+      }
+      section('Important Files', items, EMPTY.importantFiles);
+      break;
+    }
+
+    case '--health': {
+      const items = [];
+      if (result.health && result.health.length > 0) {
+        for (const h of result.health) {
+          let icon = 'ℹ';
+          if (h.status === 'pass') icon = '✓';
+          else if (h.status === 'warning') icon = '⚠';
+          
+          let color = '\x1b[97m';
+          if (h.status === 'pass') color = '\x1b[32m';
+          else if (h.status === 'warning') color = '\x1b[33m';
+          
+          items.push(`${color}${icon}\x1b[0m ${h.message}`);
+        }
+      }
+      section('Project Health', items, EMPTY.health);
+      break;
+    }
   }
 }

package/src/renderers/console-renderer.js

@@ -229,6 +229,10 @@ export function render(result, options = {}) {
     entryPoints,
     configs = [],
     scripts = [],
+    packageManager,
+    importantFiles = [],
+    projectInfo = null,
+    health = [],
     tree,
     flatFiles,
     totalFolders,
@@ -245,11 +249,50 @@ export function render(result, options = {}) {
   // ── Summary ───────────────────────────────────────────────────────────────
   section('Project Summary');
   row('Path:         ', paint(relRoot, C.cyan));
+  if (projectInfo && projectInfo.name) {
+    row('Name:         ', paint(projectInfo.name, C.white));
+  }
   row('Project type: ', paint(projectType, C.bold, C.green));
+  if (packageManager) {
+    row('Pkg manager:  ', paint(packageManager, C.white));
+  }
   row('Total files:  ', paint(String(flatFiles.length), C.yellow));
   row('Total folders:', paint(String(totalFolders), C.yellow));
   console.log('');
 
+  // ── Project Health ────────────────────────────────────────────────────────
+  section('Project Health');
+  if (health.length === 0) {
+    console.log(paint('No project health observations available.', C.dim));
+  } else {
+    for (const h of health) {
+      let icon = 'ℹ';
+      let color = C.white;
+      if (h.status === 'pass') {
+        icon = '✓';
+        color = C.green;
+      } else if (h.status === 'warning') {
+        icon = '⚠';
+        color = C.yellow;
+      }
+      console.log(`${paint(icon, color)} ${h.message}`);
+    }
+  }
+  console.log('');
+
+  // ── Important Files ───────────────────────────────────────────────────────
+  section('Important Files');
+  if (importantFiles.length === 0) {
+    console.log(paint('No important files detected.', C.dim));
+  } else {
+    importantFiles.forEach((f, idx) => {
+      console.log(`${idx + 1}. ${paint(f.path, C.white)}`);
+      console.log(`   ${paint(f.reason, C.dim)}`);
+      if (idx < importantFiles.length - 1) console.log('');
+    });
+  }
+  console.log('');
+
   // ── Frameworks ────────────────────────────────────────────────────────────
   section('Frameworks');
   const frameworks = deriveFrameworks(projectType);
@@ -289,10 +332,16 @@ export function render(result, options = {}) {
   if (scripts.length === 0) {
     console.log(paint('No package scripts detected.', C.dim));
   } else {
-    const maxNameLen = Math.max(...scripts.map(s => s.name.length));
-    for (const s of scripts) {
-      const paddedName = s.name.padEnd(maxNameLen, ' ');
-      console.log(`${paint(paddedName, C.white)}  ${paint(s.command, C.dim)}`);
+    for (let i = 0; i < scripts.length; i++) {
+      const s = scripts[i];
+      const usage = s.usage || `npm run ${s.name}`;
+      console.log(paint(usage, C.white));
+      if (s.description) {
+        console.log(`  ${paint(s.description, C.dim)}`);
+      } else {
+        console.log(`  ${paint(s.command, C.dim)}`);
+      }
+      if (i < scripts.length - 1) console.log('');
     }
   }
   console.log('');