sadrazam 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## Unreleased
 
+## v0.1.9
+
+### Added
+- `sadrazam init` for interactive `sadrazam.json` creation, including piped input support for automated setup
+- `--explain <type>` output for supported finding types in text, JSON, and TOON reports
+- TypeScript `compilerOptions.paths` alias resolution for local import reachability
+
+### Changed
+- `--fix` can now add missing package declarations to `devDependencies` with a `"*"` placeholder version, while continuing to remove deterministic unused package declarations
+- Improved `pnpm-workspace.yaml` parsing for quoted workspace patterns, inline comments, and additional top-level keys
+- Expanded script command package detection for common build, test, lint, release, and utility tools
+
+## v0.1.8
+
+### Added
+- `toon` reporter for agent-friendly structured output
+
+### Changed
+- Updated CLI help, README, and docs examples to include TOON output support
+- Expanded CLI coverage for the new TOON reporter
+
 ## v0.1.7
 
 ### Added

package/README.md

@@ -1,418 +1,224 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/borakilicoglu/sadrazam/main/assets/logo.svg?v=2" alt="Sadrazam logo" width="200" />
+  <img src="https://raw.githubusercontent.com/borakilicoglu/sadrazam/main/assets/logo.svg?v=2" alt="Sadrazam logo" width="160" />
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/sadrazam"><img src="https://img.shields.io/npm/v/sadrazam" alt="npm version" /></a>
-  <a href="https://github.com/borakilicoglu/sadrazam/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/sadrazam" alt="license" /></a>
-  <a href="https://www.npmjs.com/package/sadrazam"><img src="https://img.shields.io/npm/dt/sadrazam" alt="npm total downloads" /></a>
-  <a href="https://packagephobia.com/result?p=sadrazam"><img src="https://packagephobia.com/badge?p=sadrazam" alt="install size" /></a>
+  <b>Find and remove unused dependencies in seconds — with AI-powered explanations.</b>
 </p>
 
-<p>Sadrazam is an npm package and CLI for dependency analysis in JavaScript and TypeScript projects. It finds unused packages, flags dependency hygiene issues, and helps explain cleanup decisions with optional AI-powered insights.</p>
-
-## Overview
-
-See the full feature matrix: https://borakilicoglu.github.io/sadrazam/features
-
-- unused `dependencies` and `devDependencies`
-- missing package declarations
-- unused source file detection
-- unused export detection for reachable local modules
-- package and export trace output
-- script-aware dependency detection
-- workspace and monorepo-aware scanning
-- CommonJS and hybrid import support
-- text and JSON reporters
-- source mapping from build output back to source files
-- cache, performance, memory, and watch modes
-- production and strict scan modes
-- config file support via `sadrazam.json` or `package.json#sadrazam`
-- ignore, allowlist, catalog, and preprocessor controls
-- plugin-aware script analysis and config inputs
-- safe `--fix` and `--fix --format` support for `package.json`
-- JSDoc export ignore tags
-- AI summaries via `openai`, `anthropic`, or `gemini`
-
-## Why Sadrazam?
-
-JavaScript projects accumulate packages over time. Some stop being used. Some belong in `devDependencies` but end up in `dependencies`. Some become outdated, deprecated, or risky.
-
-Sadrazam exists to answer a simple question:
-
-Which packages in this project are actually needed, and which ones are adding weight or risk?
-
-Sadrazam's direction is:
-
-- cover the core dependency analysis workflow teams expect from a modern dependency scanner
-- add an optional AI layer for interpretation, prioritization, and remediation suggestions
-- keep the base scanner useful even when no token is provided
-
-## What Sadrazam Does
-
-Sadrazam analyzes a project by reading its manifest and source files, then comparing declared dependencies with actual usage.
+<p align="center">
+  <a href="https://www.npmjs.com/package/sadrazam"><img src="https://img.shields.io/npm/v/sadrazam" /></a>
+  <a href="https://github.com/borakilicoglu/sadrazam/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/sadrazam" /></a>
+  <a href="https://www.npmjs.com/package/sadrazam"><img src="https://img.shields.io/npm/dt/sadrazam" /></a>
+</p>
 
-Without AI:
+---
 
-- scans the project graph
-- resolves imported packages and local source relationships
-- reports unused or suspicious dependencies
-- reports unreachable source files
-- reports unused exports in reachable local modules
+## ⚡ What is Sadrazam?
 
-With AI token provided:
+Sadrazam is a CLI tool that scans your project and tells you:
 
-- explains why a dependency looks unused or risky
-- suggests whether it should be removed, moved, or reviewed
-- helps turn raw analysis into actionable cleanup decisions
+- which dependencies are **unused**
+- which ones are **misplaced or risky**
+- what you can safely **remove or fix**
 
-Current focus:
+👉 And if you enable AI:  
+it explains **why**, **what to do next**, and supports **agent-friendly TOON output** for automation and LLM workflows.
 
-- read `package.json`
-- scan `js`, `ts`, `jsx`, `tsx`, `mjs`, `cjs`, `mts`, `cts`, `svelte`, `vue`, `mdx`, and `astro` files
-- extract package usage from `import`, `export ... from`, `import = require`, `require`, and `require.resolve`
-- include package usage referenced from `package.json` scripts
-- trace local source reachability from package and script entry points
-- report unused dependencies, unused files, unused exports, and suspicious declarations
+---
 
-## Quick Start
+## 🚀 Quick Start
 
 ```bash
 npx sadrazam .
-npx sadrazam . --reporter json
-npx sadrazam . --trace typescript
-npx sadrazam . --trace-export src/lib.ts:usedHelper
-npx sadrazam . --include unused-files,unused-exports
-npx sadrazam . --cache --performance
-npx sadrazam . --fix --format
-AI_PROVIDER=openai AI_TOKEN=your_token npx sadrazam . --ai
 ```
 
-## Install
+That’s it.
 
-Local development:
+---
 
-```bash
-npm install
-```
+## 🧠 Example Output
 
-When published as an npm package:
+```
+❌ Unused dependency: lodash
+💡 Suggested: remove
 
-```bash
-npm install -g sadrazam
+⚠️ Misplaced dependency: typescript
+💡 Suggested: move to devDependencies
 ```
 
-or run it without a global install:
+With AI:
 
-```bash
-npx sadrazam .
+```
+🧠 lodash is not imported anywhere in your codebase.
+Removing it will reduce bundle size and install time.
 ```
 
-## Usage
+---
 
-Common scenarios:
+## 🎯 Why Sadrazam?
 
-- scan a single package
-- scan one workspace inside a monorepo
-- export findings as JSON
-- trace why a package is treated as used
-- trace why an export is treated as used
-- apply safe cleanup fixes to `package.json`
-- run in production or strict mode
-- enrich the report with AI summaries
+JavaScript projects accumulate dependencies over time.
 
-Scan the current project:
+- unused packages slow installs
+- wrong dependencies increase risk
+- messy `package.json` hurts maintainability
 
-```bash
-npx sadrazam .
-```
+Sadrazam answers one question:
 
-Scan a specific directory:
+👉 **What can I safely remove from this project?**
 
-```bash
-npx sadrazam ./packages/web
-```
+---
 
-Scan a single workspace in a monorepo:
+## 🔥 What Makes It Different?
 
-```bash
-npx sadrazam . --workspace packages/web
-```
+Unlike traditional tools:
 
-Get JSON output:
+- detects unused dependencies AND unused files/exports
+- understands monorepos and modern frameworks
+- optional AI layer for real explanations (not raw output)
+- safe auto-fix for `package.json`
 
-```bash
-npx sadrazam . --reporter json
-```
+---
 
-Focus on code hygiene findings:
+## ⚡ Common Use Cases
 
-```bash
-npx sadrazam . --include unused-files,unused-exports
-```
+- clean up old projects
+- audit dependency bloat
+- prepare for production
+- CI dependency checks
+- monorepo hygiene
 
-Measure scan performance with cache enabled:
+---
 
-```bash
-npx sadrazam . --cache --performance
-```
+## 🛠️ Usage
 
-Trace why a package is considered used:
+Basic scan:
 
 ```bash
-npx sadrazam . --trace typescript
+npx sadrazam .
 ```
 
-Trace why an export is considered used:
+Create a config file:
 
 ```bash
-npx sadrazam . --trace-export src/lib.ts:usedHelper
+npx sadrazam init
 ```
 
-Apply safe fixes and normalize modified `package.json` files:
+JSON output:
 
 ```bash
-npx sadrazam . --fix --format
+npx sadrazam . --reporter json
 ```
 
-Production-only scan:
+TOON output:
 
 ```bash
-npx sadrazam . --production
+npx sadrazam . --reporter toon
 ```
 
-Strict mode:
+Auto-fix:
 
 ```bash
-npx sadrazam . --strict
+npx sadrazam . --fix --format
 ```
 
-Ignore or allow specific findings from the CLI:
-
-```bash
-npx sadrazam . --ignore-packages react
-npx sadrazam . --allow-unused-dev-dependencies typescript
-```
+`--fix` removes deterministic unused package declarations and can add missing packages to `devDependencies` with a `"*"` placeholder version.
 
-For local development in this repository:
+Trace why something is used:
 
 ```bash
-npm run dev
-npm run build
-npm run typecheck
-node dist/index.js .
+npx sadrazam . --trace typescript
 ```
 
-Useful local examples:
+Explain findings of one type:
 
 ```bash
-node dist/index.js . --debug
-node dist/index.js . --exclude unused-devDependencies
-node dist/index.js . --reporter json --trace commander
-node dist/index.js . --ignore-packages react --allow-unused-dev-dependencies typescript
-```
-
-## Config
-
-Sadrazam can load config from either:
-
-- `sadrazam.json`
-- `package.json` under the `sadrazam` key
-
-Example `sadrazam.json`:
-
-```json
-{
-  "reporter": "json",
-  "production": false,
-  "strict": false,
-  "exclude": ["missing"],
-  "ignorePackages": ["$packages:ignored"],
-  "allowUnusedDependencies": [],
-  "allowUnusedDevDependencies": ["typescript"],
-  "allowMissingPackages": [],
-  "allowMisplacedDevDependencies": [],
-  "catalog": {
-    "packages": {
-      "ignored": ["react"]
-    },
-    "entryFiles": {
-      "bootstrap": ["scripts/bootstrap.ts"]
-    }
-  },
-  "inputs": {
-    "entryFiles": ["$entryFiles:bootstrap"]
-  },
-  "jsdocTags": {
-    "ignoreExports": ["sadrazam-ignore", "sadrazam-keep"]
-  },
-  "workspace": ["packages/web"],
-  "ai": {
-    "provider": "openai",
-    "model": "gpt-4.1"
-  }
-}
+npx sadrazam . --explain unused-files
 ```
 
-CLI flags take precedence over config values.
+---
 
-## Exit Codes
+## 🧠 AI Mode (Optional)
 
-Sadrazam uses these exit codes:
+Enable AI to get explanations and recommendations:
 
-- `0`: scan completed and no findings were reported
-- `1`: execution error, invalid configuration, or unrecoverable runtime failure
-- `2`: scan completed and findings were reported
+```bash
+AI_PROVIDER=openai AI_TOKEN=your_token npx sadrazam . --ai
+```
 
-## Ignore And Allowlist
+AI will:
 
-Use these when a finding is intentionally acceptable:
+- explain why a dependency is unused
+- suggest what action to take
+- summarize cleanup steps
 
-- `ignorePackages`
-- `allowUnusedDependencies`
-- `allowUnusedDevDependencies`
-- `allowMissingPackages`
-- `allowMisplacedDevDependencies`
-- `catalog.packages`
-- `catalog.entryFiles`
-- `preprocessors.packagePatterns`
-- `preprocessors.filePatterns`
-- `preprocessors.exportPatterns`
-- `jsdocTags.ignoreExports`
+---
 
-## AI Mode
+## ⚙️ Features
 
-Sadrazam works in two modes:
+- unused dependency detection
+- unused file + export detection
+- monorepo & workspace support
+- TypeScript path alias support
+- script-aware scanning
+- CommonJS + modern import support
+- safe auto-fix
+- text, JSON, TOON, markdown, and SARIF output
+- AI-powered insights
 
-- standard analysis mode with no token required
-- AI-assisted mode when the user provides an API token
+👉 Full feature list: https://borakilicoglu.github.io/sadrazam/features
 
-The base CLI remains useful without AI. AI is an upgrade layer, not a requirement.
+---
 
-Environment variables:
+## 📦 Install
 
 ```bash
-AI_PROVIDER=openai
-AI_TOKEN=your_token
-AI_MODEL=gpt-4.1
+npm install -g sadrazam
 ```
 
-Current provider values:
-
-- `openai`
-- `anthropic`
-- `gemini`
-
-Examples:
+or:
 
 ```bash
-AI_PROVIDER=openai AI_TOKEN=your_token npx sadrazam . --ai
-AI_PROVIDER=anthropic AI_TOKEN=your_token npx sadrazam . --ai
-AI_PROVIDER=gemini AI_TOKEN=your_token npx sadrazam . --ai
+npx sadrazam .
 ```
 
-CLI overrides:
+---
 
-```bash
-npx sadrazam . --ai --provider openai --model gpt-4.1
-```
+## 🧪 When to Use It
 
-What AI currently does:
-
-- summarizes findings
-- prioritizes the most important cleanup actions
-- turns raw scan output into a short remediation note
-
-What AI does not yet do:
-
-- automatic fixes
-- package reputation or security scoring
-- multi-step remediation planning
-- guaranteed deterministic recommendations across providers
-
-## Feature Overview
-
-| Name                   | Description or example                                                                                           |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| Auto-fix               | Use `--fix` to safely remove deterministic unused package declarations from `package.json`.                      |
-| Cache                  | Use `--cache` to speed up consecutive runs when inputs are unchanged.                                            |
-| Catalog                | Reuse config entries with `catalog.packages` and `catalog.entryFiles`, and get hints for unused catalog entries. |
-| CommonJS               | `require`, `require.resolve`, and hybrid import patterns are supported.                                          |
-| Compilers              | Support for `.astro`, `.mdx`, `.svelte`, and `.vue` source scanning.                                             |
-| Configuration hints    | Display hints for stale allowlists, ignored entries, and unused catalog references.                              |
-| Debug                  | Use `--debug` for troubleshooting resolved config and rule state.                                                |
-| Filters                | Use `--include` and `--exclude` to focus on specific finding groups.                                             |
-| Format                 | Use `--format` with `--fix` to normalize modified `package.json` files.                                          |
-| JSDoc tags             | Tag exports with `@sadrazam-ignore` or `@sadrazam-keep` to suppress unused export findings.                      |
-| Memory usage           | Use `--memory` for peak heap and RSS insight.                                                                    |
-| Monorepos              | Workspaces are first-class and can be filtered with `--workspace`.                                               |
-| Performance            | Use `--performance` for workspace and total timing insights.                                                     |
-| Plugins                | Built-in plugin analysis exists for common tools.                                                                |
-| Plugins: inputs        | Add entry files and package usage through config inputs.                                                         |
-| Plugins: CLI arguments | Parse common tool arguments such as `--config`, `--plugin`, and `--parser`.                                      |
-| Preprocessors          | Preprocess findings before reporting them through package, file, and export patterns.                            |
-| Production mode        | Use `--production` to lint only production code paths.                                                           |
-| Reporters              | Use built-in `text` and `json` reporters for human and machine-readable output.                                  |
-| Rules                  | Exclude or focus on specific issue types with ignore and allowlist rules.                                        |
-| Script parser          | `package.json` scripts contribute entry paths and package dependencies.                                          |
-| Source mapping         | Map `dist` files back to `src` files through sourcemaps and heuristics.                                          |
-| Strict mode            | Use `--strict` to flag production usage of `devDependencies`.                                                    |
-| Trace                  | Trace packages and exports to find where they are used.                                                          |
-| Watch mode             | Use `--watch` for live updates of unused files, exports, and dependency findings.                                |
-| Workspace              | Use `--workspace` to filter workspaces in a monorepo.                                                            |
-
-See the full feature matrix: https://borakilicoglu.github.io/sadrazam/features
-
-## Testing
-
-Local verification includes fixture-based tests for:
-
-- config loading
-- ignore and allowlist behavior
-- AI response parsing
-- AI auth error handling
-
-Run:
+Run Sadrazam when:
 
-```bash
-npm test
-```
+- your project feels bloated
+- you're unsure which deps are safe to remove
+- you're preparing for deployment
+- you're reviewing a codebase
 
-Smoke scenarios:
+---
 
-```bash
-npm run smoke
-```
+## 💡 Philosophy
 
-This runs repeatable checks for:
+Sadrazam is built around a simple idea:
 
-- single-package config-driven repo
-- CommonJS repo
-- monorepo with multiple workspaces
-- compiler-style source files
-- file and export hygiene scenarios
-- config features such as catalog, preprocessors, and JSDoc export tags
+> **Keep your dependency tree clean, understandable, and safe.**
 
-## Known Limitations
+AI is optional — the core tool works without it.
 
-- AI summaries depend on third-party provider behavior and network availability
-- source mapping uses source maps first and path heuristics second
-- misplaced dependency detection is intentionally conservative
-- dependency analysis is strongest for standard JS/TS project layouts
-- `--fix` is intentionally narrow and currently targets deterministic `package.json` cleanup
+---
 
-## Support
+## ❤️ Support
 
-If Sadrazam helps you keep dependency hygiene under control, you can support ongoing maintenance through GitHub Sponsors:
+If this tool saves you time:
 
-- https://github.com/sponsors/borakilicoglu
+⭐ Star the repo  
+☕ Support via GitHub Sponsors
 
-## Resources
+https://github.com/sponsors/borakilicoglu
 
-- Website: https://borakilicoglu.github.io/sadrazam/
-- GitHub repo: https://github.com/borakilicoglu/sadrazam
-- Official npm package: https://www.npmjs.com/package/sadrazam
-- Docs: https://borakilicoglu.github.io/sadrazam/features
-- Contributing: https://github.com/borakilicoglu/sadrazam/blob/main/CONTRIBUTING.md
-- Releases: https://github.com/borakilicoglu/sadrazam/releases
+---
 
+## 🔗 Links
+
+- GitHub: https://github.com/borakilicoglu/sadrazam
+- npm: https://www.npmjs.com/package/sadrazam
+- Docs: https://borakilicoglu.github.io/sadrazam/features

package/dist/aliasResolver.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A resolved alias entry: the prefix to match and the absolute base path(s) it maps to.
+ */
+export interface AliasEntry {
+    /** The prefix as written in imports, e.g. "@/" or "~/" or "src/" */
+    prefix: string;
+    /** Absolute directory paths the prefix maps to, in priority order */
+    targets: string[];
+}
+/**
+ * Reads tsconfig.json (and follows a single level of `extends`) from the given
+ * package directory and returns the resolved path alias entries.
+ *
+ * Returns an empty array when no tsconfig is found or no paths are configured.
+ */
+export declare function loadAliasEntries(packageDir: string): Promise<AliasEntry[]>;
+/**
+ * Given a specifier and the alias entries for the project, returns the resolved
+ * absolute path if the specifier matches an alias — or null if it doesn't.
+ *
+ * Example:
+ *   specifier = "@/components/Button"
+ *   alias     = { prefix: "@/", targets: ["/project/src"] }
+ *   returns     "/project/src/components/Button"
+ */
+export declare function resolveAlias(specifier: string, aliases: AliasEntry[]): string | null;
+export declare function resolveAliasCandidates(specifier: string, aliases: AliasEntry[]): string[];
+//# sourceMappingURL=aliasResolver.d.ts.map

package/dist/aliasResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aliasResolver.d.ts","sourceRoot":"","sources":["../src/aliasResolver.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAUD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CA8ChF;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,GAAG,IAAI,CAEpF;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,EAAE,CAYzF"}