@lakindu_perera/toren 1.0.0 → 1.0.2

package/README.md

@@ -1,8 +1,8 @@
-# Toren
+# Toren — Codebase Intelligence CLI
 
 > Understand any codebase in seconds.
 
-[![npm version](https://img.shields.io/npm/v/toren.svg)](https://www.npmjs.com/package/toren)
+[![npm version](https://img.shields.io/npm/v/@lakindu_perera/toren.svg)](https://www.npmjs.com/package/@lakindu_perera/toren)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node.js](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)
@@ -11,85 +11,96 @@
 
 ## What is Toren?
 
-**Toren** is a lightweight, zero-dependency CLI tool that scans a software project and gives you an instant, structured overview — without reading a single line of code.
+**Toren** is a powerful **codebase intelligence CLI** and **project analysis** tool designed to help developers understand unfamiliar repositories instantly. By running this lightweight **scanner**, you gain immediate insight into the architecture of any software project. It performs robust **framework detection**, identifies critical application start files through **entry point analysis**, and generates a clear **project structure visualization**—all without requiring you to read a single line of code.
 
-Drop it into any unfamiliar repository and immediately see:
-
-- What technology stack the project uses
-- Where the application starts (entry points)
-- How many files and folders exist
-- A visual preview of the directory structure
-
-Whether you've just cloned an open-source project, joined a new team, or are reviewing a client's codebase, Toren cuts through the noise and gets you oriented fast.
+Whether you are onboarding to a new team, auditing a complex repository, or looking for a fast **monorepo analyzer**, Toren cuts through the noise and gets you oriented fast.
 
 ---
 
 ## Features
 
-- ⚡ **Fast scanning** — recursively walks a project in milliseconds
-- 📦 **Zero external dependencies** — pure Node.js stdlib only
-- 🧠 **Framework detection** — identifies React, Next.js, Vue, Angular, Go, Rust, Python, and more
-- 🚪 **Entry point detection** — pinpoints `index.js`, `main.ts`, `App.tsx`, `Application.java`, and other common entry files
-- 🌲 **File tree preview** — visual directory structure, up to 4 levels deep
-- 🎨 **Beautiful terminal output** — ANSI-styled, readable at a glance
-- 🔧 **JSON output** — machine-readable format for scripting and tooling integration
-- 🙈 **Smart ignore rules** — skips `node_modules`, `.git`, `dist`, `build`, `.venv`, and more
-- 🔌 **Extensible renderer architecture** — add new output formats without touching core logic
+Toren is built to deliver comprehensive repository insights efficiently:
+
+- **Codebase Scanning**: Recursively walks any project in milliseconds to gather deep architectural insights.
+- **Framework Detection**: Instantly identifies the underlying technologies powering the application.
+- **Entry Point Analysis**: Automatically pinpoints where execution begins (e.g., `index.js`, `main.ts`, `App.tsx`, `Application.java`).
+- **Project Structure Visualization**: Generates a beautiful, hierarchical directory tree right in your terminal.
+- **Monorepo Support**: Gracefully handles complex, multi-package repositories without failing.
+- **Zero Dependencies**: A pure Node.js CLI tool with zero external runtime packages.
+- **Machine-Readable Output**: Full JSON support for seamless integration with other developer tools and AI agents.
 
 ---
 
 ## Installation
 
-Install globally with npm:
+Install the **Toren CLI tool** globally via npm to use it across all your local projects:
 
 ```bash
-npm install -g toren
+npm install -g @lakindu_perera/toren
 ```
 
-Or run without installing:
+Alternatively, you can run it instantly without global installation:
 
 ```bash
-npx toren
+npx @lakindu_perera/toren
 ```
 
 **Requirements:** Node.js 18.0.0 or higher.
 
 ---
 
-## Quick Start
-
-Scan the current directory:
+## Usage Examples
 
-```bash
-toren
-```
+Navigate to your target project folder or point Toren directly to a repository.
 
-Scan a specific path:
+Scan the current directory for an instant summary:
 
 ```bash
 toren .
-toren ../my-project
-toren /path/to/any/repo
 ```
 
-Output results as JSON:
+Scan and output the analysis in JSON format (ideal for toolchain integrations):
 
 ```bash
-toren --json
+toren . --format json
 ```
 
-Check your global installation:
+Run a deep analysis on the codebase:
 
 ```bash
-toren --doctor
+toren . --analyze
 ```
 
+*Note: You can also point Toren to any absolute or relative path, e.g., `toren ../my-project`.*
+
+---
+
+## Supported Frameworks
+
+Toren is equipped with highly accurate **framework detection** for modern development stacks. It automatically detects:
+
+- **Next.js**
+- **React**
+- **Node.js** (including Express, Fastify, Koa, and TypeScript variants)
+- **Spring Boot** (Java)
+- **Python** (including Pipenv and pyproject.toml setups)
+- **Go**
+- **Rust**
+- **Vue.js**
+- **Angular**
+- **Svelte**
+- **PHP**
+- **Ruby**
+- **Elixir**
+
+If a specific marker is not found, Toren intelligently falls back to structural heuristics to identify generic entry points, ensuring you always get meaningful project analysis.
+
 ---
 
 ## Example Output
 
 ```
-  Toren v1.0.0  —  Codebase Onboarding Intelligence
+  Toren v1.0.1  —  Codebase Onboarding Intelligence
 
 🔍  Project Summary
 ────────────────────────────────────────────────────────────────────────────────
@@ -130,218 +141,17 @@ my-app/
 
 ---
 
-## JSON Output
-
-Use `toren --json` to get a machine-readable result suitable for piping into other tools:
-
-```json
-{
-  "project": {
-    "path": "./my-app",
-    "type": "Next.js",
-    "framework": "Next.js"
-  },
-  "summary": {
-    "totalFiles": 48,
-    "totalFolders": 11,
-    "scanDurationMs": 3
-  },
-  "entryPoints": [
-    "src/app/page.tsx",
-    "src/app/layout.tsx"
-  ],
-  "structure": [
-    {
-      "type": "folder",
-      "name": "src",
-      "children": [
-        {
-          "type": "folder",
-          "name": "app",
-          "children": [
-            { "type": "file", "name": "layout.tsx" },
-            { "type": "file", "name": "page.tsx" }
-          ]
-        }
-      ]
-    },
-    { "type": "file", "name": "package.json" },
-    { "type": "file", "name": "next.config.js" }
-  ]
-}
-```
-
----
-
-## Supported Project Types
-
-Toren detects the following project types automatically:
-
-| Marker File                          | Detected Type              |
-|--------------------------------------|----------------------------|
-| `package.json`                       | Node.js / JavaScript       |
-| `package.json` + `next` dep          | Next.js                    |
-| `package.json` + `react` dep         | React                      |
-| `package.json` + `vue` dep           | Vue.js                     |
-| `package.json` + `@angular/core` dep | Angular                    |
-| `package.json` + `svelte` dep        | Svelte                     |
-| `package.json` + `express` dep       | Node.js / Express          |
-| `package.json` + `fastify` dep       | Node.js / Fastify          |
-| `package.json` + `koa` dep           | Node.js / Koa              |
-| `package.json` + `typescript` dep    | Node.js / TypeScript       |
-| `requirements.txt`                   | Python                     |
-| `Pipfile`                            | Python (Pipenv)            |
-| `pyproject.toml`                     | Python (pyproject)         |
-| `go.mod`                             | Go                         |
-| `Cargo.toml`                         | Rust                       |
-| `pom.xml`                            | Java / Spring Boot         |
-| `build.gradle`                       | Java / Gradle              |
-| `composer.json`                      | PHP / Composer             |
-| `Gemfile`                            | Ruby                       |
-| `mix.exs`                            | Elixir                     |
-
-If no marker is found, Toren reports `Unknown` without failing.
-
----
-
-## CLI Reference
-
-| Command              | Description                                      |
-|----------------------|--------------------------------------------------|
-| `toren`              | Scan the current directory                       |
-| `toren [path]`       | Scan a specific directory or file path           |
-| `toren --json`       | Output scan results as formatted JSON            |
-| `toren --version`    | Print the installed version number               |
-| `toren --help`       | Show usage information                           |
-| `toren --doctor`     | Diagnose the global installation health          |
-| `toren --uninstall`  | Guided removal of the global installation        |
-
----
-
-## Project Structure
-
-```
-toren/
-├── bin/
-│   └── toren.js          # CLI entry point — argument parsing and orchestration
-├── src/
-│   ├── lifecycle.js      # --doctor and --uninstall command implementations
-│   ├── scanner/
-│   │   └── scan.js       # Core scanning engine — file walker, type detection, entry point detection
-│   └── renderers/
-│       ├── console-renderer.js   # ANSI-styled terminal output
-│       ├── json-renderer.js      # Machine-readable JSON output
-│       └── tree-renderer.js      # Standalone flat-file tree formatter (utility)
-└── package.json
-```
-
----
-
-## How It Works
-
-### 1. Scanner
-
-`src/scanner/scan.js` is the core engine. It takes a target path and recursively walks the file system using Node's `fs.readdirSync`, collecting every file and directory while skipping entries in the ignore list (`node_modules`, `.git`, `dist`, `build`, etc.).
-
-The result is an in-memory tree of `DirNode` and `FileNode` objects, along with a flat list of all relative file paths.
-
-### 2. Framework Detection
-
-After walking the directory, the scanner checks for known marker files at the project root (e.g. `package.json`, `go.mod`, `Cargo.toml`). For `package.json`, it reads the file and inspects `dependencies`, `devDependencies`, and `peerDependencies` to determine the specific framework (React, Next.js, Vue, Angular, etc.).
-
-### 3. Entry Point Detection
-
-During the walk, each filename is checked against a known set of entry points: `index.js`, `index.ts`, `main.py`, `App.tsx`, `Application.java`, `page.tsx`, `layout.tsx`, etc. All matches are collected and surfaced in the output.
-
-### 4. Renderer
-
-The scan result — a plain JavaScript object — is passed to a renderer. Renderers are completely decoupled from the scanner; they only read data and produce output.
-
-### 5. Output
-
-The CLI selects the appropriate renderer based on flags (`--json` → JSON renderer; default → console renderer). Errors are caught and formatted consistently in both modes.
-
----
-
-## Architecture
-
-```
-CLI (bin/toren.js)
-        │
-        ▼
-  Argument Parser
-        │
-        ▼
-   Scanner (scan.js)
-        │
-        ├── Directory Walker
-        ├── Ignore Filter
-        ├── Framework Detector
-        └── Entry Point Detector
-        │
-        ▼
-   ScanResult (plain object)
-        │
-        ├──────────────────┐
-        ▼                  ▼
-Console Renderer      JSON Renderer
-(ANSI terminal)    (stdout / pipe)
-```
-
-Adding a new output format is as simple as creating a new file in `src/renderers/` and importing it in `bin/toren.js`.
-
----
-
-## Why Toren?
-
-When you encounter a new codebase, the usual approach is to start opening files, guessing at folder names, and reading `package.json` manually. This works — but it's slow and inconsistent.
-
-Toren automates that first pass. In one command, you get a structured summary of what the project is, where it starts, and what's inside. This is especially useful when:
-
-- **Onboarding to a new job** — quickly orient yourself before your first meeting
-- **Reviewing a pull request or open-source repo** — understand the scope at a glance
-- **Auditing a legacy codebase** — know what you're dealing with before diving in
-- **Building tooling** — use `--json` to feed project metadata into scripts or AI tools
-
----
-
-## Roadmap
-
-- [x] Console renderer
-- [x] JSON renderer
-- [x] Framework detection (11+ project types)
-- [x] Entry point detection
-- [x] `--doctor` install health check
-- [x] `--uninstall` guided removal
-- [x] Markdown renderer (`--format md`)
-- [x] HTML renderer (`--format html`)
-- [ ] YAML output
-- [ ] `.torenignore` configuration file
-- [ ] Plugin / custom renderer system
-- [ ] Dependency graph analysis
-- [ ] AI-generated project summary
-- [ ] Project health score
-- [ ] Architecture visualisation layer
-
----
-
 ## Contributing
 
-Contributions are welcome and appreciated.
-
-1. **Fork** this repository
-2. **Create** a feature branch: `git checkout -b feature/my-feature`
-3. **Commit** your changes: `git commit -m "feat: add my feature"`
-4. **Push** to your branch: `git push origin feature/my-feature`
-5. **Open** a pull request
+Contributions to improve this **repository analyzer** and **developer tool** are welcome!
 
-For bugs or feature requests, please [open an issue](https://github.com/your-username/toren/issues). Try to include a clear description and, for bugs, the output of `toren --doctor`.
+1. **Fork** this repository.
+2. **Create** a feature branch: `git checkout -b feature/my-feature`.
+3. **Commit** your changes: `git commit -m "feat: add my feature"`.
+4. **Push** to your branch: `git push origin feature/my-feature`.
+5. **Open** a Pull Request.
 
-**Code style notes:**
-- Zero external runtime dependencies — keep it that way
-- No TypeScript compilation step — plain ES modules only
-- Keep scanner and renderers strictly decoupled
-- Document public functions with JSDoc
+Please ensure any additions maintain the zero-dependency architecture. 
 
 ---
 
@@ -351,4 +161,4 @@ For bugs or feature requests, please [open an issue](https://github.com/your-use
 
 ---
 
-*If Toren saves you time, consider starring the repository — it helps others discover the project.* ⭐
+*If Toren saves you time during your codebase analysis, please consider starring the repository — it helps other developers discover this project.* ⭐

package/bin/toren.js

@@ -71,6 +71,7 @@ ${formatList}
  * @property {'exit'|'wait'|'scan'} action
  * @property {string}  [target]  - Resolved path to scan
  * @property {string}  [format]  - Renderer format name
+ * @property {boolean} [includeHidden] - Whether to include hidden files
  */
 
 /**
@@ -121,6 +122,10 @@ function parseArgs() {
     format = 'json';
   }
 
+  // ── Hidden files ────────────────────────────────────────────────────────
+  const includeHidden = args.includes('--include-hidden');
+
+
   // ── Target path ─────────────────────────────────────────────────────────
   // Build the set of tokens that are consumed as values by named flags so
   // we don't accidentally treat them as the positional path argument.
@@ -134,7 +139,7 @@ function parseArgs() {
   const target = args.find(a => !a.startsWith('-') && !consumedValues.has(a)) ?? '.';
 
   // ── Unknown flag check ──────────────────────────────────────────────────
-  const knownFlags = new Set(['--help', '-h', '--version', '-v', '--v', '--doctor', '--uninstall', '--format', '--json']);
+  const knownFlags = new Set(['--help', '-h', '--version', '-v', '--v', '--doctor', '--uninstall', '--format', '--json', '--include-hidden']);
   const unknownFlag = args.find(a => a.startsWith('-') && !knownFlags.has(a) && !consumedValues.has(a));
   
   if (unknownFlag) {
@@ -143,7 +148,7 @@ function parseArgs() {
     return { action: 'exit' };
   }
 
-  return { action: 'scan', target, format };
+  return { action: 'scan', target, format, includeHidden };
 }
 
 // ---------------------------------------------------------------------------
@@ -187,7 +192,7 @@ function assertValidFormat(format) {
   const render = renderers[parsed.format];
 
   try {
-    const result = scan(parsed.target);
+    const result = scan(parsed.target, { includeHidden: parsed.includeHidden });
     render(result, { cwd: process.cwd() });
   } catch (err) {
     // Render errors in the requested format where possible.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@lakindu_perera/toren",
-  "version": "1.0.0",
-  "description": "A CLI that analyzes software codebases and generates onboarding insights.",
+  "version": "1.0.2",
+  "description": "A powerful codebase scanner CLI tool for project analysis, framework detection, and understanding repository structure instantly.",
   "type": "module",
   "bin": {
-    "toren": "./bin/toren.js"
+    "toren": "bin/toren.js"
   },
   "preferGlobal": true,
   "main": "bin/toren.js",
@@ -17,16 +17,21 @@
     "lint": "node --check bin/toren.js src/scanner/scan.js"
   },
   "keywords": [
-    "cli",
-    "codebase",
-    "onboarding",
-    "developer-tool",
-    "scanner"
+    "cli tool",
+    "codebase scanner",
+    "repository analyzer",
+    "project structure viewer",
+    "framework detection",
+    "monorepo analyzer",
+    "node cli tool",
+    "developer tool",
+    "typescript cli",
+    "onboarding"
   ],
   "author": "Lakindu Perera",
   "repository": {
     "type": "git",
-    "url": "https://github.com/lakindudev/toren.git"
+    "url": "git+https://github.com/lakindudev/toren.git"
   },
   "bugs": {
     "url": "https://github.com/lakindudev/toren/issues"

package/src/renderers/console-renderer.js

@@ -98,10 +98,10 @@ function row(label, value, ...valueCodes) {
  * @param {import('../scanner/scan.js').DirNode | import('../scanner/scan.js').FileNode} node
  * @param {string}            prefix   - Accumulated indentation
  * @param {boolean}           isLast   - Whether this is the last sibling
- * @param {{ count: number }} counter  - Shared mutable file counter
+ * @param {{ count: number, maxReached: boolean }} counter  - Shared mutable file counter
  */
 function renderTree(node, prefix, isLast, counter, depth = 0, maxDepth = 4) {
-  if (counter.count >= PREVIEW_LIMIT) return;
+  if (counter.maxReached) return;
   if (depth >= maxDepth) return;
 
   const connector = isLast ? '└── ' : '├── ';
@@ -117,8 +117,16 @@ function renderTree(node, prefix, isLast, counter, depth = 0, maxDepth = 4) {
     }
 
     for (let i = 0; i < children.length; i++) {
-      if (counter.count >= PREVIEW_LIMIT) break;
-      renderTree(children[i], prefix + extension, i === children.length - 1, counter, depth + 1, maxDepth);
+      if (counter.count >= PREVIEW_LIMIT) {
+        console.log(`${prefix}${extension}└── ${paint('...', C.dim)}`);
+        counter.maxReached = true;
+        break;
+      }
+      // Check if this child will be the last one we render due to limits
+      let willBeLast = i === children.length - 1;
+      
+      renderTree(children[i], prefix + extension, willBeLast, counter, depth + 1, maxDepth);
+      if (counter.maxReached) break;
     }
   } else {
     console.log(`${prefix}${connector}${paint(node.name, C.white)}`);
@@ -198,11 +206,15 @@ export function render(result, options = {}) {
 
   console.log(paint(`${tree.name || '.'}/`, C.bold, C.blue));
 
-  const counter  = { count: 0 };
+  const counter  = { count: 0, maxReached: false };
   const children = tree.children ?? [];
   for (let i = 0; i < children.length; i++) {
-    if (counter.count >= PREVIEW_LIMIT) break;
+    if (counter.count >= PREVIEW_LIMIT) {
+      console.log(`└── ${paint('...', C.dim)}`);
+      break;
+    }
     renderTree(children[i], '', i === children.length - 1, counter);
+    if (counter.maxReached) break;
   }
 
   if (flatFiles.length > PREVIEW_LIMIT) {

package/src/scanner/scan.js

@@ -8,7 +8,8 @@
  *  - Detect the project type from marker files
  *  - Identify known entry-point files
  *
- * This module is intentionally free of side-effects (no console.log).
+ * This module is intentionally free of side-effects (no console.log),
+ * except for warnings about unreadable directories.
  * All output concerns live in bin/toren.js.
  *
  * Designed to scale into:
@@ -65,24 +66,6 @@ const PROJECT_TYPE_MARKERS = [
   { marker: 'mix.exs',            label: 'Elixir'                  },
 ];
 
-const ENTRY_POINT_EXACT = new Set([
-  'index.js', 'index.ts', 'index.jsx', 'index.tsx',
-  'main.js', 'main.ts', 'main.jsx', 'main.tsx', 'main.py',
-  'app.js', 'app.ts', 'app.jsx', 'app.tsx', 'App.js', 'App.ts', 'App.jsx', 'App.tsx',
-  'server.js', 'server.ts', 'server.jsx', 'server.tsx',
-  'Application.java', 'Main.java',
-  'page.js', 'page.ts', 'page.jsx', 'page.tsx',
-  'layout.js', 'layout.ts', 'layout.jsx', 'layout.tsx',
-  '_app.js', '_app.ts', '_app.jsx', '_app.tsx',
-  '_document.js', '_document.ts', '_document.jsx', '_document.tsx'
-]);
-
-function isEntryPoint(filename) {
-  if (ENTRY_POINT_EXACT.has(filename)) return true;
-  if (filename.endsWith('Application.java')) return true;
-  return false;
-}
-
 // ---------------------------------------------------------------------------
 // Types (JSDoc — no TypeScript dependency required)
 // ---------------------------------------------------------------------------
@@ -92,7 +75,7 @@ function isEntryPoint(filename) {
  * @property {'file'} type
  * @property {string} name      - Basename of the file
  * @property {string} fullPath  - Absolute path
- * @property {string} relPath   - Path relative to the scanned root
+ * @property {string} relPath   - Path relative to the scanned root (POSIX style)
  */
 
 /**
@@ -100,7 +83,7 @@ function isEntryPoint(filename) {
  * @property {'directory'} type
  * @property {string} name      - Basename of the directory
  * @property {string} fullPath  - Absolute path
- * @property {string} relPath   - Path relative to the scanned root
+ * @property {string} relPath   - Path relative to the scanned root (POSIX style)
  * @property {Array<FileNode|DirNode>} children
  */
 
@@ -119,31 +102,40 @@ function isEntryPoint(filename) {
 // Internal helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Normalize a path to use POSIX separators ('/').
+ */
+function toPosix(p) {
+  return p.replace(/\\/g, '/');
+}
+
 /**
  * Determine whether a directory entry should be skipped.
  *
  * @param {string} name - Basename of the entry
  * @param {fs.Dirent} dirent
+ * @param {boolean} includeHidden
  * @returns {boolean}
  */
-function shouldIgnore(name, dirent) {
-  if (name.startsWith('.') && dirent.isDirectory()) return true;
+function shouldIgnore(name, dirent, includeHidden) {
+  if (!includeHidden && name.startsWith('.')) return true;
   return IGNORED_DIRS.has(name);
 }
 
 /**
  * Recursively walk `dirPath`, building a DirNode tree.
- * Also populates `flatFiles` and `entryPoints` arrays by reference.
+ * Also populates `flatFiles` array by reference.
  *
  * @param {string} dirPath      - Absolute path of the current directory
  * @param {string} rootPath     - Absolute path of the scan root (for relative paths)
- * @param {Array<string>} flatFiles    - Accumulator for all relative file paths
- * @param {Array<string>} entryPoints  - Accumulator for entry-point relative paths
+ * @param {Array<string>} flatFiles - Accumulator for all relative file paths
+ * @param {boolean} includeHidden - Whether to include hidden files
  * @returns {DirNode}
  */
-function walkDirectory(dirPath, rootPath, flatFiles, entryPoints) {
+function walkDirectory(dirPath, rootPath, flatFiles, includeHidden) {
   const name    = path.basename(dirPath);
-  const relPath = path.relative(rootPath, dirPath) || '.';
+  let rawRelPath = path.relative(rootPath, dirPath) || '.';
+  const relPath = toPosix(rawRelPath);
 
   /** @type {DirNode} */
   const node = {
@@ -157,8 +149,9 @@ function walkDirectory(dirPath, rootPath, flatFiles, entryPoints) {
   let entries;
   try {
     entries = fs.readdirSync(dirPath, { withFileTypes: true });
-  } catch {
-    // Permission-denied or unreadable directory — skip silently.
+  } catch (err) {
+    // Permission-denied or unreadable directory — skip and log warnings instead of failing.
+    console.warn(`[warn] Skipping ${dirPath} (permission denied)`);
     return node;
   }
 
@@ -171,15 +164,15 @@ function walkDirectory(dirPath, rootPath, flatFiles, entryPoints) {
   });
 
   for (const dirent of entries) {
-    if (shouldIgnore(dirent.name, dirent)) continue;
+    if (shouldIgnore(dirent.name, dirent, includeHidden)) continue;
 
     const childPath = path.join(dirPath, dirent.name);
 
     if (dirent.isDirectory()) {
-      const childNode = walkDirectory(childPath, rootPath, flatFiles, entryPoints);
+      const childNode = walkDirectory(childPath, rootPath, flatFiles, includeHidden);
       node.children.push(childNode);
     } else if (dirent.isFile()) {
-      const relFilePath = path.relative(rootPath, childPath);
+      const relFilePath = toPosix(path.relative(rootPath, childPath));
 
       /** @type {FileNode} */
       const fileNode = {
@@ -191,10 +184,6 @@ function walkDirectory(dirPath, rootPath, flatFiles, entryPoints) {
 
       node.children.push(fileNode);
       flatFiles.push(relFilePath);
-
-      if (isEntryPoint(dirent.name)) {
-        entryPoints.push(relFilePath);
-      }
     }
   }
 
@@ -255,6 +244,124 @@ function refineNodeProjectType(pkgPath) {
   return 'Node.js / JavaScript';
 }
 
+// ---------------------------------------------------------------------------
+// Entry Point Heuristics
+// ---------------------------------------------------------------------------
+
+const FALSE_POSITIVES = [
+  '/internal/', '/renderer/', '/renderers/', '/dist/', '/build/', '/generated/', '/node_modules/'
+];
+
+function isFalsePositive(relPath) {
+  const normalized = '/' + relPath + '/'; // relPath is already POSIX
+  if (FALSE_POSITIVES.some(fp => normalized.includes(fp))) return true;
+  if (relPath.includes('.test.') || relPath.includes('.spec.')) return true;
+  // Exclude config files usually not entry points
+  if (relPath.endsWith('.config.js') || relPath.endsWith('.config.ts')) return true;
+  return false;
+}
+
+function findEntryPoints(projectType, flatFiles, rootPath) {
+  let entries = [];
+  const validFiles = flatFiles.filter(f => !isFalsePositive(f));
+  const validSet = new Set(validFiles);
+  
+  if (projectType === 'Node.js / JavaScript' || projectType.startsWith('Node.js')) {
+    try {
+      const pkgPath = path.join(rootPath, 'package.json');
+      if (fs.existsSync(pkgPath)) {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        if (pkg.bin) {
+          if (typeof pkg.bin === 'string') entries.push(pkg.bin);
+          else Object.values(pkg.bin).forEach(b => entries.push(b));
+        }
+        if (pkg.main) entries.push(pkg.main);
+      }
+    } catch {}
+    
+    // Normalize and filter package.json entries to ensure they exist
+    entries = entries.map(e => toPosix(e).replace(/^\.\//, '')).filter(e => validSet.has(e));
+    
+    if (entries.length === 0) {
+      const fallbacks = ['src/index.ts', 'src/index.js', 'lib/index.js', 'index.js'];
+      for (const f of fallbacks) {
+        if (validSet.has(f)) { entries.push(f); break; }
+      }
+    }
+  } else if (projectType === 'React' || projectType === 'Next.js' || projectType === 'Vue.js' || projectType === 'Angular' || projectType === 'Svelte') {
+    const priorities = ['src/main.tsx', 'src/main.jsx', 'pages/_app.tsx', 'app/layout.tsx', 'src/App.tsx', 'index.html'];
+    for (const p of priorities) {
+      if (validSet.has(p)) { entries.push(p); break; }
+    }
+  } else if (projectType.includes('Java')) {
+    const applicationJava = validFiles.filter(f => f.endsWith('Application.java'));
+    if (applicationJava.length > 0) {
+      entries.push(...applicationJava);
+    } else {
+      for (const f of validFiles) {
+        if (f.endsWith('.java')) {
+          try {
+            const content = fs.readFileSync(path.join(rootPath, f), 'utf8');
+            if (content.includes('public static void main')) {
+              entries.push(f);
+              break;
+            }
+          } catch {}
+        }
+      }
+    }
+  } else if (projectType.includes('Python')) {
+    const priorities = ['main.py', 'app.py', '__main__.py'];
+    for (const p of priorities) {
+      if (validSet.has(p)) { entries.push(p); break; }
+    }
+    if (entries.length === 0) {
+      for (const f of validFiles) {
+        if (f.endsWith('.py')) {
+          try {
+            const content = fs.readFileSync(path.join(rootPath, f), 'utf8');
+            if (content.includes('if __name__ == "__main__":') || content.includes("if __name__ == '__main__':")) {
+              entries.push(f);
+              break;
+            }
+          } catch {}
+        }
+      }
+    }
+  }
+  
+  if (entries.length === 0) {
+    // Fallbacks for Unknown or missed projects
+    let best = null;
+    let maxScore = -1;
+    for (const f of validFiles) {
+      if (/^(src\/)?index\.[a-z]+$/.test(f)) {
+        entries.push(f);
+        break;
+      }
+    }
+    if (entries.length === 0) {
+      for (const f of validFiles) {
+        if (f.match(/\.(js|ts|jsx|tsx|py|java|go|rb|php)$/)) {
+          try {
+            const content = fs.readFileSync(path.join(rootPath, f), 'utf8');
+            const score = (content.match(/import /g) || []).length + 
+                          (content.match(/export /g) || []).length + 
+                          (content.match(/require\(/g) || []).length;
+            if (score > maxScore) {
+              maxScore = score;
+              best = f;
+            }
+          } catch {}
+        }
+      }
+      if (best) entries.push(best);
+    }
+  }
+  
+  return Array.from(new Set(entries));
+}
+
 // ---------------------------------------------------------------------------
 // Tree helpers
 // ---------------------------------------------------------------------------
@@ -279,8 +386,9 @@ function countFolders(node) {
 // Public API
 // ---------------------------------------------------------------------------
 
-export function scan(targetPath) {
+export function scan(targetPath, options = {}) {
   const rootPath = path.resolve(targetPath);
+  const includeHidden = !!options.includeHidden;
 
   // Validate target
   let stat;
@@ -293,7 +401,7 @@ export function scan(targetPath) {
   /** @type {Array<string>} */
   const flatFiles   = [];
   /** @type {Array<string>} */
-  const entryPoints = [];
+  let entryPoints = [];
 
   const startTime   = performance.now();
   let tree;
@@ -301,12 +409,13 @@ export function scan(targetPath) {
   let totalFolders = 0;
 
   if (stat.isDirectory()) {
-    tree = walkDirectory(rootPath, rootPath, flatFiles, entryPoints);
+    tree = walkDirectory(rootPath, rootPath, flatFiles, includeHidden);
     projectType = detectProjectType(rootPath);
     // Count all directory nodes in the tree (excluding root itself).
     totalFolders = countFolders(tree) - 1;
+    entryPoints = findEntryPoints(projectType, flatFiles, rootPath);
   } else if (stat.isFile()) {
-    const relFilePath = path.basename(rootPath);
+    const relFilePath = toPosix(path.basename(rootPath));
     tree = {
       type: 'directory',
       name: path.basename(path.dirname(rootPath)),
@@ -320,9 +429,7 @@ export function scan(targetPath) {
       }]
     };
     flatFiles.push(relFilePath);
-    if (isEntryPoint(relFilePath)) {
-      entryPoints.push(relFilePath);
-    }
+    entryPoints = [relFilePath]; // A single file is its own entry point
   } else {
     throw new Error(`Path is neither a file nor a directory: ${rootPath}`);
   }