@chahuadev/junk-sweeper-app 2.0.3 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +441 -126
  2. package/install.js +2 -2
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,39 +1,50 @@
1
- # @chahuadev/junk-sweeper-app
1
+ ---
2
+ license: other
3
+ language:
4
+ - en
5
+ tags:
6
+ - code-analysis
7
+ - static-analysis
8
+ - javascript
9
+ - electron
10
+ ---
11
+ <div align="center">
2
12
 
3
- **Chahuadev Junk Sweeper** — AST-based dead code & silent bug detector with an interactive architecture map.
13
+ # Chahuadev Junk Sweeper
4
14
 
5
- <div align="center">
15
+ **Ultimate Diagnostic Code Analysis Tool**
16
+ Detect junk code with **95%+ accuracy** in read-only, non-destructive analysis mode.
6
17
 
7
18
  <p align="center">
8
- <img src="https://huggingface.co/datasets/chahuadev/chahuadev-png/resolve/main/chahuadev-junk-sweeper.png" width="600" alt="Junk Sweeper — Main Dashboard">
19
+ <img src="https://huggingface.co/datasets/chahuadev/chahuadev-png/resolve/main/chahuadev-junk-sweeper.png" width="700" alt="Junk Sweeper — Main Dashboard">
9
20
  </p>
10
21
 
11
22
  <p align="center">
12
- <a href="https://www.npmjs.com/package/@chahuadev/junk-sweeper-app"><img src="https://img.shields.io/npm/v/@chahuadev/junk-sweeper-app?style=for-the-badge&color=blue" alt="NPM Version"></a>
23
+ <a href="https://www.npmjs.com/package/@chahuadev/junk-sweeper-app"><img src="https://img.shields.io/npm/v/@chahuadev/junk-sweeper-app?style=for-the-badge&color=blue" alt="NPM Version"></a>
13
24
  <a href="https://www.npmjs.com/package/@chahuadev/junk-sweeper-app"><img src="https://img.shields.io/npm/dt/@chahuadev/junk-sweeper-app?style=for-the-badge&color=success" alt="NPM Downloads"></a>
25
+ <a href="https://huggingface.co/datasets/chahuadev/chahuadev-junk-sweeper"><img src="https://img.shields.io/badge/%20HuggingFace-Dataset-yellow?style=for-the-badge" alt="HuggingFace Dataset"></a>
26
+ <a href="LICENSE"><img src="https://img.shields.io/badge/License-Non--Commercial-blue?style=for-the-badge" alt="Non-Commercial License"></a>
27
+ <img src="https://img.shields.io/badge/Electron-40+-47848F?style=for-the-badge&logo=electron&logoColor=white" alt="Electron 40+">
28
+ <img src="https://img.shields.io/badge/Node.js-%E2%89%A522.0.0-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js 22">
29
+ <img src="https://img.shields.io/badge/Python-3.8+-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.8+">
30
+ <img src="https://img.shields.io/badge/.NET-10.0-512BD4?style=for-the-badge&logo=dotnet&logoColor=white" alt=".NET 10">
14
31
  <img src="https://img.shields.io/badge/Platform-Windows-0078D4?style=for-the-badge&logo=windows&logoColor=white" alt="Windows">
15
- <a href="https://huggingface.co/datasets/chahuadev/chahuadev-junk-sweeper/blob/main/LICENSE.md"><img src="https://img.shields.io/badge/License-Non--Commercial-blue?style=for-the-badge" alt="Non-Commercial License"></a>
32
+ <img src="https://img.shields.io/badge/Analysis-Read--Only%20%E2%9C%93-blue?style=for-the-badge" alt="Read-Only Analysis">
33
+ <img src="https://img.shields.io/badge/Security-7--Layer%20Gateway-red?style=for-the-badge&logo=shield&logoColor=white" alt="7-Layer Security">
16
34
  </p>
17
35
 
36
+ > **Built for developers who care about clean code.** Junk Sweeper scans your entire project using **native AST engines per language** — JavaScript/TypeScript (Babel), Python (stdlib ast), and C# (Microsoft Roslyn) — and surfaces unused variables, dead imports, duplicate functions, security vulnerabilities, and silent bugs through a live interactive dashboard and a draggable dependency graph. **Java scanner is in active development.** **Zero code modifications. Diagnostic-only. Always safe.**
37
+
18
38
  </div>
19
39
 
20
40
  ---
21
-
22
- ## ⚙️ Installation
23
-
24
- > **Auto-download:** On install, the binary for your platform is downloaded automatically using `--foreground-scripts` so you can see the progress bar.
25
-
26
- ### Global Install (Recommended)
41
+ ### npm Package (Windows)
27
42
 
28
43
  ```bash
29
44
  npm install -g @chahuadev/junk-sweeper-app --foreground-scripts --force
30
45
  ```
31
46
 
32
- ### Launch
33
-
34
- ```bash
35
- junk-sweeper
36
- ```
47
+ > The installer auto-downloads the correct binary for your platform. Use `--foreground-scripts` to see the download progress bar.
37
48
 
38
49
  ---
39
50
 
@@ -57,159 +68,463 @@ DISPLAY=:0 WAYLAND_DISPLAY=wayland-0 \
57
68
  --appimage-extract-and-run --no-sandbox --disable-gpu
58
69
  ```
59
70
 
60
- > **WSL2 tip:** Copy to WSL native filesystem first:
61
- > ```bash
62
- > # Path after: npm install -g @chahuadev/junk-sweeper-app
63
- > # (no sudo)
64
- > cp ~/.npm-global/lib/node_modules/@chahuadev/junk-sweeper-app/bin/"Junk Sweeper.AppImage" /tmp/JunkSweeper.AppImage
65
- > # (with sudo)
66
- > # cp /usr/lib/node_modules/@chahuadev/junk-sweeper-app/bin/"Junk Sweeper.AppImage" /tmp/JunkSweeper.AppImage
67
- > chmod +x /tmp/JunkSweeper.AppImage
68
- > DISPLAY=:0 WAYLAND_DISPLAY=wayland-0 /tmp/JunkSweeper.AppImage \
69
- > --appimage-extract-and-run --no-sandbox --disable-gpu
70
- > ```
71
+ **WSL2 tip:** Copy to WSL native filesystem first:
72
+
73
+ # Path after: npm install -g @chahuadev/junk-sweeper-app
74
+ # (no sudo)
75
+
76
+ ```bash
77
+ cp ~/.npm-global/lib/node_modules/@chahuadev/junk-sweeper-app/bin/"Junk Sweeper.AppImage" /tmp/JunkSweeper.AppImage
78
+ ```
79
+ # (with sudo)
80
+ # cp /usr/lib/node_modules/@chahuadev/junk-sweeper-app/bin/"Junk Sweeper.AppImage" /tmp/JunkSweeper.AppImage
81
+
82
+ ```bash
83
+ chmod +x /tmp/JunkSweeper.AppImage
84
+ DISPLAY=:0 WAYLAND_DISPLAY=wayland-0 /tmp/JunkSweeper.AppImage \
85
+ --appimage-extract-and-run --no-sandbox --disable-gpu
86
+ ```
87
+
88
+ ---
89
+ ## Security Guarantee
90
+
91
+ Junk Sweeper is **read-only by design** — verified at the code level, not just by policy.
92
+
93
+ | Guarantee | How It Works |
94
+ |---|---|
95
+ | **Never modifies user files** | All detectors use `fs.readFileSync()` only — no `writeFileSync()` anywhere near your code |
96
+ | **Never touches the OS** | No registry writes, no admin privilege requests, no system calls outside the app's own data folder |
97
+ | **Path Traversal Protection** | Every scan path is validated against `../` traversal, symlinks, and forbidden OS directories (`System32`, `/etc`, `/sys`, `/proc`) |
98
+ | **Executable Injection Prevention** | Strict file-type whitelist — `.exe`, `.dll`, `.bat`, `.sh` and all binary formats are blocked before analysis |
99
+ | **App Integrity on Every Launch** | SHA-256 checksums of `main.js`, `preload.js`, and all detectors are verified before the app starts — tampered builds are rejected |
100
+ | **Sandboxed Renderer** | Electron runs with `contextIsolation: true`, `sandbox: true`, `nodeIntegration: false` — the UI has zero direct Node.js access |
101
+ | **Audit Log** | Every file access and security event is logged to `~/.chahuadev/logs/` for full traceability |
102
+
103
+ The only files the app ever writes are its **own** layout cache (`%APPDATA%\Junk Sweeper\layouts\`) and its own security audit log — nothing inside your project.
71
104
 
72
105
  ---
73
106
 
74
- ## 🚀 What It Does
107
+ ## Key Features That Set Us Apart
75
108
 
76
- While standard linters look for syntax errors, **Chahuadev Junk Sweeper** uses deep AST analysis to understand the *context* and *architecture* of your entire project.
109
+ While standard linters look for syntax errors, **Chahuadev Junk Sweeper** uses deep AST (Abstract Syntax Tree) analysis to understand the *context* and *architecture* of your entire project.
77
110
 
78
- ### 🐛 Silent Bug Catcher — 8 patterns
79
- Detects logical flaws that compile fine but silently break business logic:
111
+ ### Silent Bug Catcher
112
+ Detects logical flaws that won't crash your app but **will** silently break your business logic:
80
113
 
81
114
  | Pattern | What It Catches |
82
115
  |---|---|
83
116
  | **Empty Catch Blocks** | Errors swallowed with `catch(e) {}` — bugs disappear without a trace |
84
- | **Zombie Event Listeners** | `.addEventListener()` without `.removeEventListener()` — memory leaks |
85
- | **Scope Shadowing** | Inner variable re-declaring an outer name — wrong value runs silently |
86
- | **Floating Promises** | `async` calls without `await` inside `try/catch` — rejections go unhandled |
87
- | **Orphaned Timers** | `setTimeout`/`setInterval` without cleanup reference — phantom callbacks |
88
- | **Uncaught Promise Chains** | `.then()` without `.catch()` — unhandled rejections |
89
- | **Naked JSON.parse** | `JSON.parse()` outside `try/catch` — crashes on malformed input |
90
- | **Await in Loop** | `await` inside `for`/`forEach` — accidental serial execution instead of parallel |
117
+ | **Zombie Event Listeners** | `.addEventListener()` without a matching `.removeEventListener()` — memory leaks that grow over time |
118
+ | **Scope Shadowing** | Inner variable re-declaring an outer name — logic in the outer scope runs on the wrong value |
119
+ | **Floating Promises** | `async` functions called without `await` inside `try/catch` — rejections go unhandled |
91
120
 
92
- ### 🛠️ Code Quality Auditor 10 patterns
93
- Catches patterns that compile and run today, but rot the codebase over time:
121
+ This is what separates Junk Sweeper from a plain linter. Your code compiles fine, your tests pass and the bug ships anyway.
94
122
 
95
- | Pattern | What It Catches |
96
- |---|---|
97
- | **debugger statement** | Debug pause left in production code |
98
- | **eval() / new Function(string)** | Arbitrary code execution security + performance risk |
99
- | **NaN comparison** | `x === NaN` always evaluates to `false` use `Number.isNaN()` |
100
- | **Assignment in condition** | `if (x = foo())` likely a typo of `===` |
101
- | **parseInt without radix** | Octal parsing surprises in legacy engines |
102
- | **var declaration** | Function-scoped hoisting footgun use `const`/`let` |
103
- | **console.\* debug logging** | Debug output left in production build |
104
- | **Prototype mutation** | `__proto__` / built-in `.prototype` mutation attack vector |
105
- | **Overly long functions** | Functions >60 lines complexity & maintainability risk |
106
- | **TODO / FIXME / HACK markers** | Unresolved technical debt accumulating in comments |
123
+ ### Interactive Architecture Map
124
+ Not just a static graph. A **fully interactive dependency diagram** that maps every cross-file connection in your project:
125
+
126
+ - **Left-to-Right auto-layout** powered by ELK Layered (Sugiyama) instantly see architecture flow with better crossing minimization
127
+ - **Drag nodes freely** to group related files your way
128
+ - **Save / Load / Copy Layout JSON** positions persist across sessions, so your team always sees the same organised view
129
+ - **Bidirectional issue linking** click a file node to filter the Issues list; click the pin icon on any issue to fly to that node on the map
130
+ - **Color-coded severity** Green (clean) / Amber (1–2 issues) / Red (3+ issues)
131
+ - **Standalone map mode** open map window without scan data and import a previously exported workflow JSON
132
+ - **Portable workflow export** exported JSON embeds graph data, issue structures, layout/view state, and render assets for future mobile import
133
+ - Detects `require()`, `import`, `<script src>`, `loadFile()`, IPC channels, and `preload:` edges
134
+
135
+ ### One-Click VS Code Integration
136
+ Found an issue? Click the **filename** in the report and Junk Sweeper opens VS Code directly at the **exact problematic line** — no searching, no scrolling. The moment you see the issue, you're already in position to fix it.
137
+
138
+ ### Multi-Threaded Performance
139
+ Heavy AST analysis runs in **Node.js Worker Threads** — your UI stays smooth and responsive while scanning 1,000+ file projects in the background.
107
140
 
108
- ### ✨ Live AST Recommendations
109
- Every finding includes a **live recommendation** generated from your actual code — real variable names, the exact problematic source line, and a concrete before/after fix example. No hardcoded template strings.
141
+ ---
110
142
 
111
- ### 🗺️ Interactive Architecture Map (n8n-style)
112
- - **Left-to-Right auto-layout** — see cross-file dependency flow instantly
113
- - **Drag nodes freely** — organise your architecture your way
114
- - **Save / Load / Copy Layout** — positions persist across sessions
115
- - **Node Status legend** — Clean / Minor / Critical / npm / Gateway Box with colour coding; collapsible, state remembered in localStorage
116
- - **Bidirectional issue ↔ map linking** — click an issue to fly to its node; click a node to filter issues
117
- - **Graph Export (⬆ button)** — export in 4 formats: Copy as Mermaid · Draw.io XML · Excalidraw JSON · Graphviz .dot
143
+ > **Dataset & Model Hub:** [huggingface.co/datasets/chahuadev/chahuadev-junk-sweeper](https://huggingface.co/datasets/chahuadev/chahuadev-junk-sweeper)
118
144
 
119
- ### 🏥 Project Health Score
120
- After every scan, the sidebar shows an **A–F grade ring** weighted by issue severity and confidence. The grade is also embedded in the HTML export.
145
+ ---
121
146
 
122
- ### 🚩 Mark as False Positive
123
- Every issue card has a **"Mark as False Positive"** button that copies the exact suppress comment to clipboard — paste it above the flagged line to silence the finding in future scans.
147
+ ## What It Detects
148
+
149
+ | Issue Type | Accuracy | Method | Language |
150
+ |---|---|---|---|
151
+ | Unused Imports | 99% | AST (`@babel/parser` + `@babel/traverse`) | JS/TS/JSX/TSX |
152
+ | Unused Variables | 85–90% | AST + cross-file scope analysis | JS/TS/JSX/TSX |
153
+ | Dead Code | 90–98% | AST control-flow / reachability | JS/TS/JSX/TSX |
154
+ | Duplicate Functions | 88–94% | AST structural hash + semantic similarity | JS/TS/JSX/TSX |
155
+ | Silent Bugs (8 patterns) | 85–95% | AST pattern matching | JS/TS/JSX/TSX |
156
+ | Code Quality (10 patterns) | 80–100% | AST — debugger, eval, NaN, var, console, prototype… | JS/TS/JSX/TSX |
157
+ | SAST Security (6 levels L1–L6) | 85–95% | AST — injection, path traversal, hardcoded secrets, unsafe eval… | JS/TS/JSX/TSX |
158
+ | Python Security | 85–95% | Python stdlib ast subprocess | Python |
159
+ | Python Dead Code | 88–94% | Python stdlib ast subprocess | Python |
160
+ | Python Unused Imports | 90–97% | Python stdlib ast subprocess | Python |
161
+ | Python Duplicates | 80–90% | Python stdlib ast subprocess | Python |
162
+ | Python Complexity | 80–90% | Python stdlib ast subprocess | Python |
163
+ | Python Type Hints | 85–95% | Python stdlib ast subprocess | Python |
164
+ | C# Security | 85–95% | Roslyn `CSharpSyntaxTree` | C# |
165
+ | C# Dead Code | 88–94% | Roslyn `CSharpSyntaxTree` | C# |
166
+ | C# Unused Usings | 90–97% | Roslyn `CSharpSyntaxTree` | C# |
167
+ | C# Code Quality | 80–92% | Roslyn `CSharpSyntaxTree` | C# |
168
+ | C# Silent Bugs | 82–92% | Roslyn `CSharpSyntaxTree` | C# |
169
+ | Java (structural) | ⚠️ กำลังพัฒนา | `--source 11` subprocess | Java |
170
+
171
+ > Every finding now includes a **live recommendation** generated from your actual code — real variable names, the exact problematic line, and a concrete fix example. No hardcoded templates.
172
+
173
+ Supports (full AST): **JavaScript, TypeScript, JSX, TSX, Python, C#**
174
+ Supports (in development): **Java**
124
175
 
125
- ### ⚙️ Per-Project Config
126
- Drop `.junksweeper.json` in your project root to tune `minConfidence`, `ignorePatterns`, per-detector toggles, and `excludePatterns` — no app restart needed.
176
+ ---
127
177
 
128
- ### 📤 SARIF 2.1.0 Export
129
- Export findings in **SARIF 2.1.0** format — compatible with GitHub Code Scanning, Azure DevOps, VS Code SARIF Viewer, and any SARIF-aware CI pipeline.
178
+ ## Core Features
179
+
180
+ ### Static Code Analysis
181
+ - **Multi-language AST engines** — each language uses its own dedicated native parser:
182
+ - **JS/TS/JSX/TSX** — `@babel/parser` + `@babel/traverse` (in-process, Worker Thread)
183
+ - **Python** — stdlib `ast` module via subprocess (`main_json.py`); 7 detectors
184
+ - **C#** — Microsoft Roslyn (`CSharpSyntaxTree`) via subprocess (`Program.cs`, .NET 10); 5 detectors
185
+ - **Java** — subprocess via `--source 11` ⚠️ *กำลังพัฒนา*
186
+ - **6 active detectors** — unused variables, unused imports, dead code, duplicate functions, silent bugs, code quality
187
+ - **Silent Bugs — 8 patterns:** empty catch, floating promises, zombie listeners, orphaned timers, uncaught promise chains, scope shadowing, naked JSON.parse, await-in-loop
188
+ - **Code Quality — 10 patterns:** debugger statements, eval/new Function, NaN comparison, assignment-in-condition, parseInt without radix, var declaration, console.* debug logging, prototype mutation, overly long functions, TODO/FIXME markers
189
+ - **Live AST recommendations** — every finding shows real variable names, the actual code line, and a concrete fix example extracted from the AST at scan time — no hardcoded templates
190
+ - **Common-sense filtering** — permanent Node.js/Electron lifecycle events not flagged; stdlib module names and error callback names excluded from shadow warnings
191
+ - **Confidence scoring** — every finding includes an accuracy percentage and severity level
192
+ - **Read-only analysis** — safe diagnostic mode, zero code modification
193
+
194
+ ### SAST Security Scanner
195
+ - **Dedicated SCAN SECURITY button** — independent scan from junk analysis; runs in a separate Worker Thread
196
+ - **6-level severity (L1–L6)** — from critical injection flaws to low-risk style-security issues
197
+ - **Detects:** SQL/NoSQL injection, command injection, path traversal, hardcoded secrets/tokens/passwords, unsafe `eval` / `new Function`, prototype pollution, insecure `Math.random`, unvalidated redirects, and more
198
+ - **Security tab severity chips** — ALL / CRITICAL / HIGH / MEDIUM / LOW filter chips sync with sidebar badge clicks
199
+ - **Security Statistics Sidebar** — severity breakdown with clickable severity badges (toggle mode) — syncs with security chips
200
+ - **Map Monitor integration** — security issue count + ⚠N badge shown on every affected file card
201
+ - **Mutual exclusion** — switching between Junk Scan and Security Scan automatically clears the previous result
202
+
203
+ ### Project Map Monitor
204
+ - **Interactive n8n-style dependency graph** — not a static image; every node is draggable, zoomable, and clickable
205
+ - **SVG card nodes** — color-coded by file type and issue severity; file-type badge (JS / TS / HT / JSON / etc.) on every node
206
+ - **ELK LR auto-layout** — left-to-right layered layout on first open; re-run anytime via the Auto-Layout button
207
+ - **Layout Memory** — positions saved to `%APPDATA%\Junk Sweeper\layouts\<project>.json` automatically; close and reopen the app and every node is exactly where you left it; share the JSON with your team via the Copy button
208
+ - **IPC channel edges** — visualises Electron `ipcRenderer`/`ipcMain` connections
209
+ - **Dependency detection** across JS, TS, HTML (`<script src>`, `<link href>`), and Electron patterns (`loadFile()`, `preload:`)
210
+ - **Per-file issue badges** — each node shows issue count with Green / Amber / Red status; ⚠N security badge appears above the role badge (non-overlapping)
211
+ - **Node Status legend** — Clean (green) / Minor (amber) / Critical (red) / npm (purple) / Gateway Box (orange pill) — collapsible, state persists
212
+ - **Electron Role badges** — MAIN / BR / UI / 🛡 / ⚙ role labels on key Electron files
213
+ - **Bidirectional Issues ↔ Map linking** — click the 📍 pin icon on any issue card to fly to that node on the map; click a node on the map to filter the Issues list to that file
214
+ - **One-Click VS Code Integration** — click any filename in the issue report to open VS Code at the exact problematic line
215
+ - **Workflow JSON Export / Import** — one-click save/load of map state as Junk Sweeper workflow JSON
216
+ - **Mobile-ready portable payload** — workflow JSON contains full map payload (nodes, edges, issueLinesByFile, positions, zoom/pan, edge style, node SVG data URIs, tooltips)
217
+ - **Free-drag** — 8-direction resize + drag-anywhere code panel; nodes freely repositionable
218
+
219
+ ### Security-First Architecture
220
+ - **7-Layer Security Gateway**: path validation, file-type whitelist, authentication, permission checks, audit logging, rate limiting, sandbox IPC isolation
221
+ - **Path Traversal Protection** — prevents directory traversal attacks
222
+ - **Checksum Validation** — file integrity verification on startup (production mode)
223
+ - **Context Isolation** — Electron `contextBridge` / `contextIsolation: true`, no direct Node.js access in renderer
224
+
225
+ ### Report Export Formats
226
+ - **JSON** — machine-readable analysis data
227
+ - **HTML** — premium dark-theme interactive report with embedded CSS, Project Health Score, and all findings — shareable as a single file
228
+ - **CSV** — spreadsheet-compatible data export
229
+ - **PDF** — professional A4 PDF generated via native Electron `printToPDF` — no printer required, works without a print dialog
230
+ - **SARIF 2.1.0** — Static Analysis Results Interchange Format; import directly into GitHub Code Scanning, Azure DevOps, VS Code SARIF Viewer, and CI/CD pipelines
231
+
232
+ All formats trigger the native OS **Save File dialog** via Electron IPC — no browser download workarounds.
233
+
234
+ ### Project Health Score
235
+ After every scan the sidebar displays a live **Health Score** ring: **A** (90–100) → **B** (75–89) → **C** (55–74) → **D** (35–54) → **F** (<35). Score is calculated from issue penalty points weighted by severity and confidence — gives an instant at-a-glance quality grade for the entire project.
236
+
237
+ ### Mark as False Positive
238
+ Every issue card has a **"Mark as False Positive"** button. Clicking it copies the exact suppress comment for that line to the clipboard — paste it above the flagged code to silence the finding in future scans. Works for all 6 detectors.
239
+
240
+ ### Per-Project Config — `.junksweeper.json`
241
+ Drop a `.junksweeper.json` file in your project root to override scan behaviour without touching the app:
242
+ ```json
243
+ {
244
+ "minConfidence": 0.5,
245
+ "ignorePatterns": ["node_modules/**", "dist/**"],
246
+ "detectors": { "code_quality": false },
247
+ "excludePatterns": ["*.test.js"]
248
+ }
249
+ ```
130
250
 
131
- ### One-Click VS Code Integration
132
- Click any filename in the report VS Code opens at the **exact problematic line**.
251
+ ### Severity Filter Chips Issues & Security Tabs
252
+ Both the **Code Issues** tab and the **Security Issues** tab have filter chips (ALL / HIGH / MEDIUM / LOW for junk; ALL / CRITICAL / HIGH / MEDIUM / LOW for security) that instantly narrow the visible findings.
133
253
 
134
- ### 🧵 Multi-Threaded Performance
135
- Worker Threads keep the UI responsive while scanning 1,000+ file projects.
254
+ ### Dual Interface
255
+ - **Desktop App (Electron)** split-layout dashboard with live terminal, issue browser, code snippets, and project map
256
+ - **CLI Tool** — `junk-sweeper-cli` for CI/CD pipelines
136
257
 
137
258
  ---
259
+ ## Installation
138
260
 
139
- ## 🔒 Security Guarantee
140
261
 
141
- Junk Sweeper is **read-only by design** — verified at the code level, not just by policy.
142
262
 
143
- | Guarantee | How It Works |
144
- |---|---|
145
- | **Never modifies user files** | All detectors use `fs.readFileSync()` only — no `writeFileSync()` anywhere near your code |
146
- | **Never touches the OS** | No registry writes, no admin privilege requests, no system calls outside the app's own data folder |
147
- | **Path Traversal Protection** | Every scan path is validated against `../` traversal, symlinks, and forbidden OS directories (`System32`, `/etc`, `/sys`, `/proc`) |
148
- | **Executable Injection Prevention** | Strict file-type whitelist — `.exe`, `.dll`, `.bat`, `.sh` and all binary formats are blocked before analysis |
149
- | **App Integrity on Every Launch** | SHA-256 checksums of `main.js`, `preload.js`, and all detectors are verified before the app starts — tampered builds are rejected |
150
- | **Sandboxed Renderer** | Electron runs with `contextIsolation: true`, `sandbox: true`, `nodeIntegration: false` — the UI has zero direct Node.js access |
151
- | **Audit Log** | Every file access and security event is logged to `~/.chahuadev/logs/` for full traceability |
263
+ ---
152
264
 
153
- The only files the app ever writes are its **own** layout cache (`%APPDATA%\Junk Sweeper\layouts\`) and its own security audit log — nothing inside your project.
265
+ ## Usage
266
+
267
+ ### Desktop Application
268
+
269
+ #### Scan for Junk & Code Quality Issues
270
+ 1. App launches with animated **Splash Screen** (security gateway initialisation)
271
+ 2. Click **SELECT FOLDER** → choose target directory
272
+ 3. Click **START SCAN** → monitor Live Terminal for real-time progress
273
+ 4. Browse detected issues in the **Code Issues** tab
274
+
275
+ #### Scan for Security Vulnerabilities (SAST)
276
+ 1. Select a folder (same or different project)
277
+ 2. Click **SCAN SECURITY** → dedicated SAST Worker Thread runs independently
278
+ 3. Security findings appear in the **Security Issues** tab with level, severity, and code snippet
279
+ 4. Use the **sidebar severity badges** (L1–L6) to filter findings — click the same badge again to clear the filter
280
+
281
+ #### View Analysis Results
282
+ - **Live Terminal** — real-time scan progress and status messages
283
+ - **Code Issues** — searchable, filterable list of all detected problems with file, line, confidence score, and inline code snippet
284
+
285
+ #### Project Map Monitor
286
+ 1. Click **PROJECT MAP** to open the map window any time (even before scanning)
287
+ 2. Nodes represent files; edges represent `require()`, `import`, `<script src>`, `loadFile()`, IPC channels, etc.
288
+ 3. Node color: **Green** = clean, **Amber** = 1–2 issues, **Red** = 3+ issues, **Purple** = npm package, **Cyan** = IPC/bridge
289
+ 4. **Layout Memory**: node positions save automatically on drag; use the hamburger menu (☰) to Save / Copy / Paste / Reset layout
290
+ 5. **Bidirectional linking**: click the 📍 pin icon on any issue card → map focuses that node; click a node in the map → Issues list filters to that file
291
+ 6. Hover a node to see full path and issue count; click to open its source code in the side panel
292
+ 7. Use **Export → Save as JSON** to produce a portable workflow file that includes full render context
293
+ 8. Use **Import** in map window to load workflow JSON back (desktop) or into future mobile map clients
294
+
295
+ #### Export Report
296
+ 1. Click **EXPORT REPORT** → select **JSON**, **HTML**, **CSV**, or **PDF**
297
+ 2. The native OS Save dialog opens — choose your location and filename
298
+ 3. File is written directly by the Electron main process (no browser sandbox limitations)
299
+
300
+ ---
301
+
302
+ ## Security Architecture
303
+
304
+ ### 7-Layer Protection Stack
305
+ 1. **Path Validation** — prevents directory traversal attacks (`../` etc.)
306
+ 2. **File Type Whitelist** — only approved code file extensions are analysed
307
+ 3. **Authentication Layer** — validates user access before operations
308
+ 4. **Permission System** — checks read rights before file access
309
+ 5. **Operation Audit Logging** — complete trail of all IPC actions
310
+ 6. **Rate Limiting** — prevents scan-loop / DoS abuse
311
+ 7. **Sandbox Isolation** — Electron `contextIsolation: true`, `sandbox: true`, `nodeIntegration: false`
312
+
313
+ ### Confidence Levels
314
+ - **High (95%+)** — highly reliable, recommended for automated pipelines
315
+ - **Medium (50–95%)** — requires manual verification
316
+ - **Low (<50%)** — likely false positives, informational only
317
+
318
+ ---
319
+
320
+ ## Example Output
321
+
322
+ ### Live Terminal
323
+ ```
324
+ [init] System initialized. Awaiting scan command...
325
+ [info] Scan started for directory: C:\projects\myapp
326
+ [info] Analyzing files (5 of 247)...
327
+ [success] Scan complete. Found 47 issues.
328
+ [success] High confidence: 34
329
+ [success] Medium confidence: 10
330
+ [success] Low confidence: 3
331
+ ```
332
+
333
+ ### Analysis Report (JSON)
334
+ ```json
335
+ {
336
+ "scanDate": "2026-03-08T10:30:00Z",
337
+ "targetPath": "./src",
338
+ "totalIssuesFound": 47,
339
+ "confidenceBreakdown": { "high": 34, "medium": 10, "low": 3 },
340
+ "issues": [
341
+ {
342
+ "file": "src/app.js",
343
+ "line": 42,
344
+ "type": "unused_variable",
345
+ "message": "Variable 'tempVar' is declared but never used",
346
+ "confidence": 0.96,
347
+ "codeSnippet": "const tempVar = calculateValue();"
348
+ }
349
+ ]
350
+ }
351
+ ```
154
352
 
155
353
  ---
156
354
 
157
- ## 📝 Changelog
355
+ ## Configuration
356
+
357
+ ### `.junksweeper.json` (optional, place in project root)
358
+ ```json
359
+ {
360
+ "minConfidence": 0.5,
361
+ "languages": ["js", "ts", "py"],
362
+ "ignorePatterns": [
363
+ "node_modules/**",
364
+ "dist/**",
365
+ ".git/**",
366
+ "test/**"
367
+ ],
368
+ "maxScanDepth": 50,
369
+ "maxPathLength": 260
370
+ }
371
+ ```
372
+
373
+ ---
374
+
375
+ ## Project Structure
376
+
377
+ ```
378
+ chahuadev-junk-sweeper/
379
+ ├── main.js # Electron main process — IPC handlers, window management, startup watchdog
380
+ ├── preload.js # Secure contextBridge IPC gateway for all windows
381
+ ├── index.html # Main UI — split-layout dashboard (Terminal / Issues / Project Map tabs)
382
+ ├── splash.html # Animated splash screen with preload bridge retry loop
383
+ ├── map-monitor.html # Interactive dependency graph (ELK layered, n8n-style, Layout Memory)
384
+ ├── junk-sweeper-cli.js # CLI entry point
385
+ ├── checksums.json # Integrity checksums (production)
386
+ ├── backend/
387
+ │ └── utils/
388
+ │ ├── project-inspector.js # Dependency graph engine (AST + HTML/CSS/IPC)
389
+ │ ├── project-inspector-ipc.js # IPC bridge for inspector
390
+ │ ├── inspector-worker.js # Worker thread for dependency graph
391
+ │ ├── junk-scanner-worker.js # Worker thread for junk/code-quality scan
392
+ │ └── security-scanner-worker.js # Worker thread for SAST security scan
393
+ ├── engines/
394
+ │ ├── engine-dispatcher.js # Orchestrates all scan engines (JS + subprocess engines)
395
+ │ ├── engine-registry.js # Discovers engines via manifest.json scan
396
+ │ ├── subprocess-bridge.js # Generic OS-aware subprocess runner
397
+ │ ├── project-mapper.js # Polyglot import extractor (Python, C#, HTML)
398
+ │ ├── js_scanner/
399
+ │ │ ├── junk-detector.js # Main JS/TS detection orchestrator (6 detectors)
400
+ │ │ └── js-ts/
401
+ │ │ ├── ast-unused-variables-detector.js
402
+ │ │ ├── ast-unused-imports-detector.js
403
+ │ │ ├── ast-dead-code-detector.js
404
+ │ │ ├── ast-duplicate-functions-detector.js
405
+ │ │ ├── ast-silent-bug-detector.js # 8 silent-bug patterns
406
+ │ │ ├── ast-code-quality-detector.js # 10 code-quality patterns
407
+ │ │ └── ast-security-detector.js # SAST L1–L6
408
+ │ ├── py_scanner/
409
+ │ │ ├── manifest.json # runtime: python
410
+ │ │ ├── main_json.py # Python coordinator (subprocess entry)
411
+ │ │ ├── engine.py
412
+ │ │ ├── models.py
413
+ │ │ ├── ast_map.py
414
+ │ │ └── detector_*.py # 7 Python detectors
415
+ │ ├── cs_scanner/
416
+ │ │ ├── manifest.json # runtime: dotnet, entry: Program.cs
417
+ │ │ ├── cs_scanner.csproj # .NET 10 + Microsoft.CodeAnalysis.CSharp
418
+ │ │ ├── Program.cs # C# coordinator (Roslyn AST)
419
+ │ │ └── cs/
420
+ │ │ ├── AstSecurityDetector.cs
421
+ │ │ ├── AstDeadCodeDetector.cs
422
+ │ │ ├── AstUnusedUsingsDetector.cs
423
+ │ │ ├── AstCodeQualityDetector.cs
424
+ │ │ ├── AstSilentBugDetector.cs
425
+ │ │ └── Issue.cs
426
+ │ └── java_scanner/
427
+ │ ├── manifest.json # runtime: java, --source 11
428
+ │ └── Main.java # ⚠️ กำลังพัฒนา — basic structural scanner
429
+ ├── security/
430
+ │ ├── authentication-gateway.js # 7-layer security gateway
431
+ │ └── security-validator.js # Checksum validation
432
+ ├── icons/
433
+ └── vendor/
434
+ ├── elkjs/ # Bundled ELK layered graph layout
435
+ └── vis-network.min.js # Bundled offline vis-network
436
+ ```
437
+
438
+ ---
439
+
440
+ ## Key Technologies
441
+
442
+ | Technology | Role |
443
+ |---|---|
444
+ | Electron 40 | Desktop app framework |
445
+ | vis-network 9 | Interactive dependency graph |
446
+ | elkjs | ELK layered graph layout (replaced dagre) |
447
+ | @babel/parser + @babel/traverse | JS/TS/JSX/TSX AST parsing and traversal (6 detectors) |
448
+ | Python 3.8+ stdlib ast | Python AST via subprocess (7 detectors) |
449
+ | Microsoft.CodeAnalysis.CSharp 4.12 | Roslyn C# AST via subprocess (5 detectors) |
450
+ | Java --source 11 | Java structural scanner (⚠️ กำลังพัฒนา) |
451
+ | @swc/core | High-speed JS/TS compilation & analysis |
452
+ | parse5 | HTML parser (script/link dependency extraction) |
453
+ | esquery | AST query engine |
454
+ | estraverse | AST traversal utility |
455
+ | jscpd | Duplicate code detection support |
456
+ | typescript | TypeScript compiler API |
457
+
458
+ ---
459
+
460
+ ## Changelog
158
461
 
159
462
  ### v1.0.0 — Initial Release
160
- - Read-only AST analysis JSON/HTML/CSV export
161
- - Interactive n8n-style Project Map with Layout Memory
162
- - 5 AST detectors: Unused Variables, Unused Imports, Dead Code, Duplicate Functions, Silent Bugs
163
- - 7-Layer Security Gateway + SHA-256 checksum integrity verification
463
+ - Read-only AST analysis, JSON/HTML/CSV export, Project Map Monitor, animated splash screen
464
+ - IPC dependency graph, Layout Memory (save/load/copy/reset)
465
+ - 5 detectors: Unused Variables, Unused Imports, Dead Code, Duplicate Functions, Silent Bugs
466
+ - 7-Layer Security Gateway: path validation, file-type whitelist, auth, permissions, audit log, rate limiter, sandbox
467
+ - SHA-256 checksum integrity verification on every launch
164
468
  - One-Click VS Code Go-to-Line integration
165
- - Worker Thread architecture — UI stays responsive during large scans
469
+ - Worker Thread architecture — UI remains responsive during large scans
166
470
 
167
- ### v1.0.1 — AST Recommendations & Code Quality Auditor
168
- - **6th detector:** `ast-code-quality-detector.js` — 10 production-safety patterns (debugger, eval, NaN comparison, assignment-in-condition, parseInt radix, var, console.\*, prototype mutation, long functions, TODO markers)
169
- - **Silent Bugs expanded to 8 patterns:** Orphaned Timers, Uncaught Promise Chains, Naked `JSON.parse`, Await-in-Loop
170
- - **Live AST-driven recommendations** across all 6 detectors every finding shows the actual code line from your source, real variable/function names from the AST, and a concrete before/after fix example
171
- - **Collapsible Node Status legend** in Project Map — collapse to save screen space; state persists in localStorage
172
- - **Terminal boot sequence** shows all 7 security layers and all 6 active detectors on launch
471
+ ### v1.0.1 — AST Recommendations & Code Quality
472
+ - **6th detector activated:** `ast-code-quality-detector.js` — 10 patterns including `debugger`, `eval`, NaN comparison, assignment-in-condition, `parseInt` without radix, `var` declarations, `console.*`, prototype mutation, overly long functions, and TODO/FIXME markers
473
+ - **Live AST-driven recommendations** across all 6 detectors every finding now shows the actual code line and real variable/function names extracted from the AST, plus a concrete before/after fix example. No more hardcoded template strings.
474
+ - **Silent Bugs expanded to 8 patterns:** added Naked `JSON.parse` (no try/catch) and Await-in-Loop (serial awaits inside `for`/`forEach`)
475
+ - **Collapsible Node Status legend** in Project Map — click to collapse/expand; state persists in `localStorage`
476
+ - Terminal boot sequence now shows all 7 security layers and 6 active detectors on startup
173
477
 
174
478
  ### v1.0.2 — SAST Security Scanner & Premium Export
175
- - **SAST Security Scanner** — dedicated **SCAN SECURITY** button running `ast-security-detector.js` (6-level L1–L6) in a separate Worker Thread
176
- - **Security Issues Tab** — severity-tagged findings with code snippet, file location, and searchable list
177
- - **Security Statistics Sidebar** — per-severity issue count, toggleable filter badges
178
- - **PDF Export** — A4 PDF via Electron `printToPDF`; no printer required
179
- - **Premium HTML Export** — single-file dark-theme shareable report
180
- - **Native Save Dialog** — all 4 formats (JSON/HTML/CSV/PDF) use `dialog.showSaveDialog` via IPC
479
+ - **SAST Security Scanner** — dedicated **SCAN SECURITY** button; runs `ast-security-detector.js` (6-level L1–L6) in a separate Worker Thread independent of junk analysis
480
+ - **Security Issues Tab** — severity-tagged findings (L1 Critical → L6 Low) with code snippet, file, and line; searchable list
481
+ - **Security Statistics Sidebar** — per-severity issue count with toggleable severity filter (click badge to filter, click again to clear)
482
+ - **Map Monitor security count** — total security findings shown in the stats bar of the dependency graph
483
+ - **Mutual-exclusion scans** — switching between Junk Scan and Security Scan automatically clears the previous result and UI
484
+ - **PDF Export** — premium A4 PDF via Electron `webContents.printToPDF` with dark-theme embedded CSS; no printer needed
485
+ - **Premium HTML Export** — single-file shareable dark-theme report with all findings and embedded styles
486
+ - **Native Save Dialog** — all 4 export formats (JSON/HTML/CSV/PDF) use `dialog.showSaveDialog` via IPC — bypasses Electron renderer sandbox limitations
487
+ - **Security findings export** — Export Report works after either Junk Scan or Security Scan
181
488
 
182
489
  ### v1.0.3 — Health Score, SARIF, Config & QoL
183
- - **Project Health Score** — A–F grade ring in sidebar; embedded in HTML export
184
- - **SARIF 2.1.0 Export** — GitHub Code Scanning, Azure DevOps, VS Code SARIF Viewer compatible
185
- - **Mark as False Positive** — copies exact suppress comment to clipboard for any issue
186
- - **`.junksweeper.json` config** — per-project `minConfidence`, `ignorePatterns`, detector toggles, `excludePatterns`
187
- - **Issues tab severity chips** — ALL / HIGH / MEDIUM / LOW filter chips
490
+ - **Project Health Score** — A–F grade ring displayed in the sidebar after every scan; penalty-weighted by severity and confidence
491
+ - **SARIF 2.1.0 Export** — import into GitHub Code Scanning, Azure DevOps, VS Code SARIF Viewer, and any SARIF-compatible CI tool
492
+ - **HTML Report includes Health Score** — exported HTML report embeds the current grade alongside all findings
493
+ - **Mark as False Positive** — one-click button on each issue card copies the exact suppress comment to clipboard; paste above the flagged code to silence it in future scans
494
+ - **`.junksweeper.json` per-project config** — drop a config file in project root to override `minConfidence`, `ignorePatterns`, `detectors` toggles, and `excludePatterns` without touching the app
495
+ - **Issues tab severity chips** — ALL / HIGH / MEDIUM / LOW filter chips for instant narrowing of the junk issues list
188
496
 
189
497
  ### v1.0.4 — Security UX, Node Status Legend & Graph Export
190
- - **Security tab severity chips** — ALL / CRITICAL / HIGH / MEDIUM / LOW; synced with sidebar badge filter
191
- - **Security ⚠N badge** repositioned on map cards no longer overlaps Electron role badge
192
- - **Node Status legend** reorganised Clean / Minor / Critical / npm / Gateway Box with accurate colours
193
- - **Graph Export button** (⬆ in map toolbar) Mermaid · Draw.io XML · Excalidraw JSON · Graphviz .dot
194
-
498
+ - **Security tab severity chips** — ALL / CRITICAL / HIGH / MEDIUM / LOW chips in the Security Issues tab; sync with sidebar badge filter clicks
499
+ - **Security ⚠N badge repositioned** — security badge on map cards moved to mid-right above the Electron role badge; no longer obstructs role label
500
+ - **Node Status legend** — legend section renamed and reorganised: Clean / Minor / Critical / npm / Gateway Box with accurate colour coding
501
+ - **`execFile` shell injection fix** in `main.js`VS Code Go-to-Line now uses `execFile` with array args instead of `exec()` with shell string
502
+
503
+ ### v1.0.5 — Standalone Map Import + Portable Workflow Payload
504
+ - **Map window launch without scan** — open Project Map in import-only mode and load a workflow JSON directly
505
+ - **Fresh scan map window behavior** — after scan, map opens as a fresh scan window while import window remains usable
506
+ - **Portable workflow JSON schema v2** — export now embeds complete map payload for cross-platform rendering:
507
+ - raw graph (`nodes`, `edges`, `issueLinesByFile`, scan metadata)
508
+ - layout state (`positions`, collapsed folder state)
509
+ - view state (`zoom`, `pan`, edge routing style)
510
+ - render payload (node SVG data URIs, ghost variants, tooltip HTML, accent colors)
511
+ - **Backward compatible import** — map importer supports both new portable payload and legacy workflow JSON
195
512
  ---
513
+ ## License
196
514
 
197
- ## 📦 Platform Support
198
-
199
- | Platform | Architecture | Status |
200
- |---|---|---|
201
- | Windows | x64 | ✅ Supported |
202
- | Windows | ia32 | ✅ Supported |
203
- | Linux | x64 | ✅ Supported |
204
- | macOS | arm64 / x64 | 🔜 Coming soon |
515
+ Non-Commercial & Acceptable Use — See [LICENSE](LICENSE)
205
516
 
206
517
  ---
207
518
 
208
- ## 🔗 Links
519
+ ## Support
209
520
 
210
- - [HuggingFace Dataset](https://huggingface.co/datasets/chahuadev/chahuadev-junk-sweeper)
211
- - [NPM Package](https://www.npmjs.com/package/@chahuadev/junk-sweeper-app)
521
+ - Email: chahuadev@gmail.com
522
+ - Website: https://chahuadev.com
523
+ - GitHub Issues: Report bugs and feature requests
524
+ - Documentation: See [./docs/](docs/)
525
+ - Dataset / Model Hub: [huggingface.co/datasets/chahuadev/chahuadev-junk-sweeper](https://huggingface.co/datasets/chahuadev/chahuadev-junk-sweeper)
212
526
 
213
527
  ---
214
528
 
215
- *Made by [Chahuadev](https://chahuadev.com) | Security-First Code Analysis Tools*
529
+ *Made by Chahuadev | Security-First Code Analysis Tools*
530
+
package/install.js CHANGED
@@ -13,10 +13,10 @@ let downloadUrl = '';
13
13
  let fileName = '';
14
14
 
15
15
  if (platform === 'win32') {
16
- downloadUrl = `${R2_BASE}/Junk-Sweeper.exe`;
16
+ downloadUrl = `${R2_BASE}/Junk%20Sweeper.exe`;
17
17
  fileName = 'Junk Sweeper.exe';
18
18
  } else if (platform === 'linux') {
19
- downloadUrl = `${R2_BASE}/Junk-Sweeper.AppImage`;
19
+ downloadUrl = `${R2_BASE}/Junk%20Sweeper.AppImage`;
20
20
  fileName = 'Junk Sweeper.AppImage';
21
21
  } else {
22
22
  console.warn(`Chahuadev Junk Sweeper does not support ${platform} ${arch} yet.`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@chahuadev/junk-sweeper-app",
3
- "version": "2.0.3",
3
+ "version": "3.1.0",
4
4
  "description": "Chahuadev Junk Sweeper — AST-based dead code & silent bug detector with interactive architecture map",
5
5
  "main": "index.js",
6
6
  "bin": {