@lakindu_perera/toren 1.0.5 → 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

@@ -1,16 +1,45 @@
 /**
- * @fileoverview Focused output modes handling for Toren CLI.
+ * @fileoverview Toren — Focused Output Mode Handler
+ *
+ * Handles the six focused output flags:
+ *   --project-type  --frameworks  --entry-points
+ *   --structure     --configs     --scripts
+ *
+ * Design contract:
+ *  - Each flag renders exactly one section to stdout using the console visual
+ *    style (ANSI colours, section header + divider).
+ *  - Empty-state messages are canonical strings declared in EMPTY below.
+ *    They must end with a period and stay in sync with console-renderer.js.
+ *  - No business logic. All data comes from the ScanResult passed in.
+ *  - Stateless: renderFocusedMode() may be called multiple times safely.
  */
 
 import { renderStructure } from './renderers/console-renderer.js';
 
+// ---------------------------------------------------------------------------
+// Canonical empty-state messages
+// Keep these in sync with the equivalent strings in console-renderer.js.
+// ---------------------------------------------------------------------------
+
+const EMPTY = {
+  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 = [
   '--project-type',
   '--frameworks',
   '--entry-points',
   '--structure',
   '--configs',
-  '--scripts'
+  '--scripts',
+  '--summary',
+  '--important-files',
+  '--health'
 ];
 
 /**
@@ -25,8 +54,10 @@ export function getFocusedModeInfo(args) {
   if (activeFlags.length > 1) {
     return {
       error: true,
-      message: '\x1b[31mError: focused output flags are mutually exclusive. Please use only one of:\x1b[0m\n' + 
-               FOCUSED_FLAGS.map(f => `  ${f}`).join('\n') + '\n'
+      title: 'Conflicting options',
+      message: 'Focused output flags are mutually exclusive.',
+      detailLabel: 'Provided flags',
+      detailValue: activeFlags.join(', ')
     };
   }
 
@@ -36,6 +67,37 @@ export function getFocusedModeInfo(args) {
   };
 }
 
+/**
+ * Print a bold-white section title followed by a dim matched-length divider
+ * and a blank line — same visual pattern as console-renderer.js's section().
+ *
+ * @param {string} title
+ */
+function printSectionHeader(title) {
+  console.log(`\x1b[1m\x1b[97m${title}\x1b[0m`);
+  console.log(`\x1b[2m${'─'.repeat(title.length)}\x1b[0m`);
+  console.log('');
+}
+
+/**
+ * Print a focused section: header, then items or an empty-state message.
+ *
+ * @param {string}   title    - Section heading
+ * @param {string[]} items    - Pre-formatted lines to print
+ * @param {string}   emptyMsg - Canonical empty-state message (ends with '.')
+ */
+function section(title, items, emptyMsg) {
+  printSectionHeader(title);
+
+  if (!items || items.length === 0) {
+    console.log(`\x1b[2m${emptyMsg}\x1b[0m`);
+  } else {
+    for (const item of items) {
+      console.log(item);
+    }
+  }
+}
+
 /**
  * Renders the scan result based on the active focused mode.
  * 
@@ -44,53 +106,111 @@ export function getFocusedModeInfo(args) {
  */
 export function renderFocusedMode(mode, result) {
   switch (mode) {
-    case '--project-type':
-      console.log(`Project Type: ${result.projectType}`);
+    case '--project-type': {
+      // projectType is always a string; 'Unknown' when undetected.
+      section('Project Type', [result.projectType], 'Unknown');
       break;
-      
-    case '--frameworks':
-      if (!result.projectType || result.projectType === 'Unknown') {
-        console.log('Frameworks: None detected');
-      } else {
-        console.log('Frameworks:');
-        console.log(`- ${result.projectType}`);
-      }
+    }
+
+    case '--frameworks': {
+      const frameworks = (!result.projectType || result.projectType === 'Unknown')
+        ? []
+        : [result.projectType];
+      section('Frameworks', frameworks, EMPTY.frameworks);
       break;
-      
-    case '--entry-points':
-      if (!result.entryPoints || result.entryPoints.length === 0) {
-        console.log('Entry Points: None detected');
-      } else {
-        console.log('Entry Points:');
-        result.entryPoints.forEach(ep => console.log(`- ${ep}`));
-      }
+    }
+
+    case '--entry-points': {
+      section('Entry Points', result.entryPoints || [], EMPTY.entryPoints);
       break;
-      
-    case '--structure':
+    }
+
+    case '--structure': {
       renderStructure(result);
       break;
-      
-    case '--configs':
-      console.log('Configuration Files');
-      console.log('───────────────────\n');
-      if (!result.configs || result.configs.length === 0) {
-        console.log('No configuration files detected.');
-      } else {
-        result.configs.forEach(c => console.log(`✓ ${c}`));
+    }
+
+    case '--configs': {
+      section('Configuration Files', result.configs || [], EMPTY.configs);
+      break;
+    }
+
+    case '--scripts': {
+      const scriptsList = [];
+      if (result.scripts && result.scripts.length > 0) {
+        for (const s of result.scripts) {
+          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 '--scripts':
-      console.log('Available Scripts\n');
-      if (!result.scripts || result.scripts.length === 0) {
-        console.log('No scripts found');
-      } else {
-        const maxNameLen = Math.max(...result.scripts.map(s => s.name.length));
-        result.scripts.forEach(s => {
-          const paddedName = s.name.padEnd(maxNameLen + 6, ' ');
-          console.log(`${paddedName}${s.command}`);
+    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;
+    }
   }
 }