@lakindu_perera/toren 1.0.5 → 1.0.8

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.7] - 2026-08-29
+### Added
+- **Project Intelligence Upgrade**: Added Package Manager detection, project metadata extraction (name, language, runtime, architecture), and important file detection.
+- **Project Health Checks**: New `--health` flag to evaluate repository health (checking for README, License, linting, tests, docker files).
+- **Richer Output Formats**: Expanded HTML and Markdown renderers to include the newly extracted project details, ensuring a highly readable and comprehensive project overview.
+- **Enhanced JSON schema**: Output JSON schema has been substantially updated to support these rich data properties in a deterministic order.
+- **New CLI flags**: `--summary`, `--important-files`, and `--health`.
+
+### Changed
+- Refactored `ScanResult` object with `packageManager`, `projectInfo`, `health`, and `importantFiles`.
+- Updated test suite for new CLI flags and deterministic JSON output.
+

package/README.md

@@ -1,8 +1,8 @@
-# Toren — Codebase Analyzer CLI
+# Toren — Fast Repository Discovery CLI
 
 > The fastest way to understand any project structure. A zero-dependency codebase scanner CLI for modern developers.
 
-[![npm version](https://img.shields.io/npm/v/@lakindu_perera/toren.svg)](https://www.npmjs.com/package/@lakindu_perera/toren)
+[![npm version](https://img.shields.io/npm/v/@lakindudev/toren.svg)](https://www.npmjs.com/package/@lakindudev/toren)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org)
 [![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-success.svg)](package.json)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
@@ -23,6 +23,8 @@ Built with zero external dependencies, this **Node.js repository explorer** is t
 - **Framework Detection**: Instantly identifies Node.js, React, Next.js, Vue, Nuxt, Angular, Svelte, Python, Go, Rust, Spring Boot, Ruby, PHP, Elixir and more.
 - **Entry Point Detection**: Automatically pinpoints where execution begins (e.g., `index.js`, `main.ts`, `App.tsx`, `main.go`).
 - **Project Structure Visualizer**: Generates clean, hierarchical file trees.
+- **Project Health Diagnostics**: Provides observations and warnings for common project health issues.
+- **Package Manager Detection**: Identifies whether a project uses npm, pnpm, yarn, bun, etc.
 - **Multiple Output Formats**: Choose between `console` (default), `json`, `markdown`, or `html` reports.
 - **Zero Dependencies**: A pure Node.js CLI tool with no external runtime packages. Lightning fast install, infinitely secure.
 - **CLI Lifecycle Tools**: Native diagnostic and uninstallation tools (`--doctor`, `--uninstall`).
@@ -34,7 +36,7 @@ Built with zero external dependencies, this **Node.js repository explorer** is t
 Install Toren globally via npm to make the **repository inspection CLI** available anywhere on your machine:
 
 ```bash
-npm install -g @lakindu_perera/toren
+npm install -g @lakindudev/toren
 ```
 
 **Requirements:** Node.js 18.0.0 or higher.
@@ -69,6 +71,9 @@ toren --entry-points
 toren --structure
 toren --configs
 toren --scripts
+toren --summary
+toren --important-files
+toren --health
 
 # Lifecycle & Help Commands
 toren --help
@@ -77,10 +82,10 @@ toren --doctor
 toren --uninstall
 ```
 
-### All Flags
+### CLI Reference
 
-| Flag | Description |
-|------|-------------|
+| Command / Flag | Description |
+|----------------|-------------|
 | `[path]` | Directory to scan. Defaults to the current directory (`.`). |
 | `--project-type` | Show detected project type only. |
 | `--frameworks` | Show detected frameworks only. |
@@ -88,70 +93,46 @@ toren --uninstall
 | `--structure` | Show repository structure only. |
 | `--configs` | Show detected project configuration files. |
 | `--scripts` | Show available package scripts only. |
+| `--summary` | Show project summary only. |
+| `--important-files` | Show important files only. |
+| `--health` | Show project health observations only. |
 | `--format <type>` | Output format: `console` (default), `json`, `markdown`, `html`. |
 | `--include-hidden` | Include hidden files and dot-directories in the scan. |
-| `--max-files <N>` | Override the default 50,000-file scan limit. |
-| `--help` / `-h` | Show usage information. |
-| `--version` / `-V` | Print the installed version number. |
+| `--max-files <n>` | Override the default 50,000-file scan limit. |
+| `--help`, `-h` | Show usage and help message. |
+| `--version`, `-v` | Print the installed version number. |
 | `--doctor` | Diagnose the global installation health. |
 | `--uninstall` | Safely remove Toren from the global npm environment. |
 
 > **Note:** `--format md` is not a valid alias. Use `--format markdown` in full.
-> **Note:** Focused output flags (`--project-type`, `--frameworks`, `--entry-points`, `--structure`, `--configs`, `--scripts`) are mutually exclusive.
+> **Note:** Focused output flags are mutually exclusive.
 
 ---
 
-## Output Examples
+## Screenshots & Output Examples
 
-### Focused Output Example
-Sometimes you only need a specific piece of intelligence for use in a script or a quick lookup. Use the focused output flags to bypass the full report:
-
-```bash
-$ toren --project-type
-Project Type: Node.js / JavaScript
+### Console Output Example
+The default `console` format renders a beautiful summary directly in your terminal:
 
-$ toren --frameworks
-Frameworks:
-- React
+```text
+Toren v1.0.7  —  Fast Repository Discovery CLI
 
-$ toren --entry-points
-Entry Points:
-- src/main.tsx
+Project Summary
+───────────────
 
-$ toren --configs
-Configuration Files
-───────────────────
+Path:          ./my-react-app
+Project type:  React
+Total files:   32
+Total folders: 6
 
-✓ package.json
-✓ vite.config.ts
+Entry Points
+────────────
 
-$ toren --scripts
-Available Scripts
+src/main.tsx
 
-start      node bin/toren.js
-test       node --test
-```
+Folder Structure  (first 20 files)
+──────────────────────────────────
 
-### Console Output Example
-The default `console` format renders a beautiful summary directly in your terminal:
-
-```text
-  Toren v1.0.4  —  Codebase Onboarding Intelligence
-
- Project Summary
-────────────────────────────────────────────────────────────────────────────────
-  Path:          ./my-react-app
-  Project type:  React
-  Total files:   32
-  Total folders: 6
-  Scan duration: 4 ms
-
- Entry Points
-────────────────────────────────────────────────────────────────────────────────
-  →  src/main.tsx
-
- Folder Structure  (first 20 files)
-────────────────────────────────────────────────────────────────────────────────
 my-react-app/
 ├── public/
 │   └── vite.svg
@@ -165,10 +146,27 @@ my-react-app/
 ├── index.html
 ├── package.json
 └── vite.config.ts
-  … and 21 more file(s) not shown
+… and 21 more file(s) not shown
+
+Scan completed in 4 ms
+```
+
+### Focused Output Examples
+Sometimes you only need a specific piece of intelligence for use in a script or a quick lookup. Use the focused output flags to bypass the full report:
 
-────────────────────────────────────────────────────────────────────────────────
-  Scan complete.
+```bash
+$ toren --project-type
+Project Type
+────────────
+
+Node.js / JavaScript
+
+$ toren --scripts
+Package Scripts
+───────────────
+
+start  vite
+test   vitest
 ```
 
 ### JSON Output Example
@@ -176,19 +174,54 @@ Generate machine-readable output for scripts, toolchains, or AI context windows
 
 ```json
 {
+  "meta": {
+    "version": "1.0.7",
+    "scanDurationMs": 4,
+    "timestamp": "2026-08-29T23:51:00.000Z"
+  },
   "project": {
+    "name": "my-react-app",
     "path": "./my-react-app",
     "type": "React",
-    "framework": "React"
-  },
-  "summary": {
-    "totalFiles": 32,
-    "totalFolders": 6,
-    "scanDurationMs": 4
+    "framework": "React",
+    "packageManager": "npm"
   },
+  "frameworks": [
+    "React"
+  ],
   "entryPoints": [
     "src/main.tsx"
   ],
+  "configs": [
+    "package.json",
+    "vite.config.ts"
+  ],
+  "scripts": [
+    {
+      "name": "start",
+      "command": "vite",
+      "description": "Start the development server",
+      "category": "development",
+      "usage": "npm start"
+    }
+  ],
+  "importantFiles": [
+    {
+      "path": "package.json",
+      "reason": "Defines dependencies"
+    }
+  ],
+  "health": [
+    {
+      "id": "readme",
+      "status": "pass",
+      "message": "README file is present"
+    }
+  ],
+  "statistics": {
+    "totalFiles": 32,
+    "totalFolders": 6
+  },
   "structure": [
     {
       "type": "folder",
@@ -199,7 +232,12 @@ Generate machine-readable output for scripts, toolchains, or AI context windows
       ]
     },
     { "type": "file", "name": "package.json" }
-  ]
+  ],
+  "summary": {
+    "totalFiles": 32,
+    "totalFolders": 6,
+    "scanDurationMs": 4
+  }
 }
 ```
 
@@ -207,6 +245,23 @@ Generate machine-readable output for scripts, toolchains, or AI context windows
 
 ---
 
+## Release Notes
+
+### v1.0.7 - Intelligence Upgrade
+- **Project Intelligence Upgrade**: Added Package Manager detection, project metadata extraction (name, language, runtime, architecture), and important file detection.
+- **Project Health Checks**: New `--health` flag to evaluate repository health (checking for README, License, linting, tests, docker files).
+- **Richer Output Formats**: Expanded HTML and Markdown renderers to include the newly extracted project details, ensuring a highly readable and comprehensive project overview.
+- **Enhanced JSON schema**: Output JSON schema has been substantially updated to support these rich data properties in a deterministic order.
+
+### v1.0.6 - CLI Experience Update
+- **Redesigned CLI Output**: Completely revamped the console layout to use minimal typography, bold section titles, and dynamic divider lines matching the title width.
+- **Improved Error Handling**: Transformed raw exceptions into user-friendly error messages outlining the issue and potential fixes, ensuring consistent exit codes.
+- **Enhanced Focused Modes**: Focused output flags (`--configs`, `--entry-points`, `--structure`, etc.) now strictly mirror the design tokens of the full console renderer, providing identical spacing and layouts.
+- **Streamlined Help & Version**: The `--help` interface was fully redesigned for faster reading, and `-v` / `--version` flags were added to output the exact binary version directly from `package.json`.
+- **Accurate Timing Metrics**: Scan duration logic was improved to utilize native timing APIs, precisely measuring execution and printing results natively as "Scan completed in X ms" without clogging the project summary.
+
+---
+
 ## Architecture
 
 Toren's internal architecture emphasizes modular design, separation of concerns, and a strict **zero dependency** philosophy.
@@ -253,6 +308,60 @@ Contributions to improve this codebase analyzer CLI are always welcome!
 
 ---
 
+## Maintainer: Releasing a New Version
+
+Toren uses **automated npm publishing via GitHub Actions** and [npm Trusted Publishing (OIDC)](https://docs.npmjs.com/generating-provenance-statements).  
+**Do not run `npm publish` manually** — GitHub Actions owns the publish step.
+
+### Release checklist
+
+```text
+1. Implement changes on a feature branch.
+
+2. Update the version in package.json:
+       "version": "1.0.8"
+
+3. Run tests and lint locally:
+       npm test
+       npm run lint
+
+4. Commit the version bump and any other changes:
+       git commit -m "chore: release v1.0.8"
+
+5. Open a Pull Request → merge to main.
+
+6. On GitHub, create a new Release:
+       Tag:   v1.0.8        ← must match package.json exactly (with leading v)
+       Title: v1.0.8
+       Body:  paste CHANGELOG.md entry
+
+7. Click "Publish Release".
+
+8. GitHub Actions runs automatically:
+       ✔ npm ci
+       ✔ npm test  (all 233+ tests must pass)
+       ✔ npm run lint
+       ✔ tag format validated  (vX.Y.Z)
+       ✔ tag v1.0.8 == package.json 1.0.8
+       ✔ npm pack --dry-run
+       ✔ npm publish --access public --provenance
+
+9. @lakindudev/toren@1.0.8 is live on npmjs.com.
+```
+
+### If the workflow fails
+
+| Failure step | Cause | Fix |
+|---|---|---|
+| Run tests | A test is failing | Fix the test, push, re-create release |
+| Run lint | Syntax error in source | Fix lint error, push, re-create release |
+| Validate tag format | Tag is not `vX.Y.Z` | Delete the release, re-create with correct tag |
+| Verify version matches | `package.json` not bumped | Update `package.json`, push, re-create release |
+| Verify package contents | `files` array misconfigured | Fix `package.json`, push, re-create release |
+| Publish to npm | Trusted Publisher not configured | Follow the npm Trusted Publisher setup in `.github/workflows/publish.yml` header |
+
+---
+
 ## License
 
 Distributed under the MIT License. See `LICENSE` for more information.

package/bin/toren.js

@@ -38,43 +38,59 @@ const DEFAULT_FORMAT = 'console';
 const SUPPORTED_FORMATS = Object.keys(renderers);
 
 // ---------------------------------------------------------------------------
-// Help
+// Helpers
 // ---------------------------------------------------------------------------
 
+function printError(title, message, detailLabel, detailValue) {
+  console.error(`\x1b[31m✖ ${title}\x1b[0m\n`);
+  console.error(`${message}\n`);
+  if (detailLabel && detailValue) {
+    console.error(`${detailLabel}:\n`);
+    console.error(`${detailValue}\n`);
+  }
+}
+
 function printHelp() {
-  const formatList = SUPPORTED_FORMATS.map(f => `      ${f}`).join('\n');
+  const formatList = SUPPORTED_FORMATS.map(f => {
+    const suffix = f === DEFAULT_FORMAT ? '  (default)' : '';
+    return `  --format ${f.padEnd(10)}${suffix}`;
+  }).join('\n');
+
   console.log(`
-\x1b[1mUsage:\x1b[0m
+\x1b[1mToren\x1b[0m v${pkg.version}
+Fast Repository Discovery CLI
+
+\x1b[1mUSAGE\x1b[0m
   toren [path] [options]
 
-\x1b[1mOptions:\x1b[0m
+\x1b[1mCOMMANDS\x1b[0m
   --project-type      Show detected project type only
   --frameworks        Show detected frameworks only
   --entry-points      Show detected entry points only
   --structure         Show repository structure only
   --configs           Show detected project configuration files
   --scripts           Show available package scripts only
-  --format <type>     Output as console, json, markdown, or html
+  --summary           Show project summary only
+  --important-files   Show important files only
+  --health            Show project health observations only
   --include-hidden    Include hidden files and folders
   --max-files <n>     Set scan file limit
-  --help              Show this help message
-  --version           Show version number
   --doctor            Run CLI diagnostics
   --uninstall         Remove Toren global installation
+  --help              Show this help message
+  --version           Show version number
 
-\x1b[1mOutput Formats:\x1b[0m
+\x1b[1mOUTPUT FORMATS\x1b[0m
 ${formatList}
 
-    console is the default.
-
-\x1b[1mExamples:\x1b[0m
+\x1b[1mEXAMPLES\x1b[0m
   toren .                              Scan the current directory
   toren ./my-project                   Scan a specific project folder
   toren --format json .                Output results as JSON
   toren --format markdown . > out.md   Save a Markdown report to a file
   toren --format html . > out.html     Save an HTML report to a file
-  toren --include-hidden .             Include hidden dot-files in scan
-  toren --max-files 100000 .           Override the 50k file scan limit
+  toren . --configs                    Show project configuration files
+  toren . --frameworks                 Show detected frameworks
 `);
 }
 
@@ -110,7 +126,7 @@ function parseArgs() {
   }
 
   if (args.includes('--version') || args.includes('-V') || args.includes('-v')) {
-    console.log(pkg.version);
+    console.log(`Toren ${pkg.version}`);
     return { action: 'exit', code: 0 };
   }
 
@@ -135,13 +151,12 @@ function parseArgs() {
     const nextToken = args[formatIdx + 1];
     // If the next token is missing or starts with '-', the user omitted the value.
     if (nextToken === undefined || nextToken.startsWith('-')) {
-      console.error('');
-      console.error('\x1b[31m  --format requires a value.\x1b[0m');
-      console.error('');
-      console.error(`  Supported formats: ${SUPPORTED_FORMATS.join(', ')}`);
-      console.error('');
-      console.error('  Run \x1b[36mtoren --help\x1b[0m for usage.');
-      console.error('');
+      printError(
+        'Missing value',
+        'The --format flag requires a valid output format.',
+        'Supported formats',
+        SUPPORTED_FORMATS.join(', ')
+      );
       return { action: 'exit', code: 1 };
     }
     format = nextToken;
@@ -153,7 +168,7 @@ function parseArgs() {
   const focusedInfo = getFocusedModeInfo(args);
   
   if (focusedInfo.error) {
-    console.error(focusedInfo.message);
+    printError(focusedInfo.title, focusedInfo.message, focusedInfo.detailLabel, focusedInfo.detailValue);
     return { action: 'exit', code: 1 };
   }
 
@@ -176,17 +191,22 @@ function parseArgs() {
   if (maxFilesIdx !== -1) {
     const rawVal = args[maxFilesIdx + 1];
     if (rawVal === undefined || rawVal.startsWith('-')) {
-      console.error('');
-      console.error('\x1b[31m  --max-files requires a numeric value.\x1b[0m');
-      console.error('  Example: toren --max-files 100000');
-      console.error('');
+      printError(
+        'Missing value',
+        'The --max-files flag requires a numeric value.',
+        'Example',
+        'toren --max-files 100000'
+      );
       return { action: 'exit', code: 1 };
     }
     maxFiles = parseInt(rawVal, 10);
     if (isNaN(maxFiles) || maxFiles < 1) {
-      console.error('');
-      console.error(`\x1b[31m  --max-files must be a positive integer, got: ${rawVal}\x1b[0m`);
-      console.error('');
+      printError(
+        'Invalid value',
+        'The --max-files flag must be a positive integer.',
+        'Provided value',
+        rawVal
+      );
       return { action: 'exit', code: 1 };
     }
     consumedValues.add(rawVal);
@@ -213,8 +233,12 @@ function parseArgs() {
   );
 
   if (unknownFlag) {
-    console.error(`\x1b[31m  Unknown flag: ${unknownFlag}\x1b[0m`);
-    console.error(`  Run \x1b[36mtoren --help\x1b[0m for usage.\n`);
+    printError(
+      'Unknown option',
+      'An unrecognized flag was provided.',
+      'Flag',
+      unknownFlag
+    );
     return { action: 'exit', code: 1 };
   }
 
@@ -234,16 +258,12 @@ function parseArgs() {
 function assertValidFormat(format) {
   if (renderers[format]) return;
 
-  const list = SUPPORTED_FORMATS.map(f => `  • ${f}`).join('\n');
-  console.error('');
-  console.error(`\x1b[31m  Unknown output format: ${format}\x1b[0m`);
-  console.error('');
-  console.error('  Supported formats:');
-  console.error('');
-  console.error(list);
-  console.error('');
-  console.error('  Run \x1b[36mtoren --help\x1b[0m for usage.');
-  console.error('');
+  printError(
+    'Unsupported output format',
+    'The requested output format is not supported.',
+    'Format',
+    format
+  );
   process.exit(1);
 }
 
@@ -280,9 +300,11 @@ function assertValidFormat(format) {
     if (parsed.format === 'json') {
       console.error(JSON.stringify({ error: err.message }, null, 2));
     } else {
-      console.error('');
-      console.error(`\x1b[31m  ❌  Error: ${err.message}\x1b[0m`);
-      console.error('');
+      if (err.title) {
+        printError(err.title, err.message, err.detailLabel, err.detailValue);
+      } else {
+        printError('Scan failed', err.message);
+      }
     }
     process.exit(1);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lakindu_perera/toren",
-  "version": "1.0.5",
+  "version": "1.0.8",
   "description": "A powerful codebase scanner CLI tool for project analysis, framework detection, and understanding repository structure instantly.",
   "type": "module",
   "bin": {
@@ -10,12 +10,16 @@
     "bin",
     "src",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "start": "node bin/toren.js",
     "test": "node --test",
-    "lint": "node --check bin/toren.js src/scanner/scan.js src/lifecycle.js src/renderers/index.js src/renderers/console-renderer.js src/renderers/json-renderer.js src/renderers/markdown-renderer.js src/renderers/html-renderer.js"
+    "lint": "node --check bin/toren.js src/scanner/scan.js src/lifecycle.js src/renderers/index.js src/renderers/console-renderer.js src/renderers/json-renderer.js src/renderers/markdown-renderer.js src/renderers/html-renderer.js src/detectors/config-detector.js src/detectors/script-detector.js src/detectors/package-manager-detector.js"
   },
   "keywords": [
     "cli tool",

package/src/detectors/health-detector.js

@@ -0,0 +1,72 @@
+/**
+ * Detect project health observations.
+ */
+export function detectHealth({
+  flatFiles,
+  configs,
+  importantFiles,
+  scripts,
+  projectType
+}) {
+  const health = [];
+  const fileSet = new Set(flatFiles);
+
+  // README
+  if (fileSet.has('README.md') || fileSet.has('README') || fileSet.has('readme.md')) {
+    health.push({ id: 'readme', status: 'pass', message: 'README found' });
+  } else {
+    health.push({ id: 'readme', status: 'warning', message: 'README not found' });
+  }
+
+  // LICENSE
+  if (fileSet.has('LICENSE') || fileSet.has('LICENSE.md') || fileSet.has('LICENSE.txt')) {
+    health.push({ id: 'license', status: 'pass', message: 'LICENSE found' });
+  } else {
+    health.push({ id: 'license', status: 'warning', message: 'LICENSE not found' });
+  }
+
+  // ENVIRONMENT EXAMPLE
+  if (fileSet.has('.env.example') || fileSet.has('.env.sample')) {
+    health.push({ id: 'env-example', status: 'pass', message: 'Environment example found' });
+  }
+
+  // TESTS
+  const hasTestFiles = flatFiles.some(f => 
+    f.startsWith('test/') || 
+    f.startsWith('tests/') || 
+    f.startsWith('__tests__/') || 
+    f.includes('.test.') || 
+    f.includes('.spec.')
+  );
+  const hasTestScripts = (scripts || []).some(s => s.category === 'testing' || s.name === 'test');
+  if (hasTestFiles || hasTestScripts) {
+    health.push({ id: 'tests', status: 'pass', message: 'Tests detected' });
+  }
+
+  // LINTER
+  const hasLinter = (configs || []).some(c => 
+    c.includes('eslint') || 
+    c.includes('biome') || 
+    c.includes('stylelint')
+  ) || (scripts || []).some(s => s.category === 'quality' || s.name === 'lint');
+  if (hasLinter) {
+    health.push({ id: 'lint', status: 'pass', message: 'Linter detected' });
+  }
+
+  // TYPESCRIPT
+  if (fileSet.has('tsconfig.json')) {
+    health.push({ id: 'typescript', status: 'pass', message: 'TypeScript configuration found' });
+  }
+
+  // GIT
+  if (fileSet.has('.gitignore')) {
+    health.push({ id: 'git', status: 'info', message: '.gitignore found' });
+  }
+
+  // DOCKER
+  if (fileSet.has('Dockerfile') || fileSet.has('docker-compose.yml') || fileSet.has('compose.yml')) {
+    health.push({ id: 'docker', status: 'info', message: 'Docker configuration found' });
+  }
+
+  return { health };
+}