treezip 1.1.0 → 1.1.2

package/README.md

@@ -1,22 +1,42 @@
 # treezip
 
-Compressed directory trees for AI prompts. Zero dependencies.
+compressed directory trees for llm prompts. zero dependencies, aggressively de-noised.
 
-`tree` output is verbose — `treezip` compresses it using brace grouping, directory collapsing, and truncation so you can fit more codebase structure into fewer tokens.
+```bash
+npx treezip ./my-project
+```
+
+## the problem
+
+you paste a `tree` dump into an llm so it understands your codebase. two things go wrong:
+
+1. **it's verbose.** every file gets its own line, its own indent guides, its own copy of the extension. a 400-file repo eats thousands of tokens on pure structure.
+2. **it's full of junk.** `node_modules`, `DerivedData`, `__pycache__`, `.turbo`, coverage reports, `.DS_Store` — none of it helps the model, all of it costs tokens. one xcode build folder can turn a 100-line tree into an 11,000-line one. (that's a real number — see below.)
+
+`treezip` fixes both. it compresses the structure losslessly with brace notation, and it hardcodes a multi-ecosystem noise filter so build artifacts never reach the output in the first place.
+
+real-world result on a swift app with a checked-in derived-data dir and agent worktrees lying around:
+
+| | lines |
+|---|---|
+| plain `tree` | 11,261 |
+| `treezip` | **98** |
+
+same source files visible. 99% less noise.
 
-## Install
+## install
 
 ```bash
 npm install -g treezip
 ```
 
-Or run directly:
+or don't install at all:
 
 ```bash
 npx treezip ./my-project
 ```
 
-## Before / After
+## before / after
 
 **`tree` (43 lines):**
 
@@ -69,7 +89,7 @@ my-project/
 └── tsconfig.json
 ```
 
-**`treezip` (17 lines):**
+**`treezip` (12 lines):**
 
 ```
 my-project/
@@ -86,60 +106,29 @@ my-project/
     └── {Button,Card,Header,Modal,Sidebar}.test.tsx
 ```
 
-**60% fewer lines.** Same information. Every brace group decompresses to exactly one file per entry.
+every brace group decompresses to exactly one path per entry — the compression is lossless (except explicit `...` truncation, which is marked so the model knows more files exist).
 
-## How it works
+## the format
 
-| Pattern | Meaning | Example |
+| pattern | meaning | example |
 |---|---|---|
-| `{a,b,c}.ext` | Siblings sharing an extension | `{Button,Card,Modal}.tsx` |
-| `{a.x,b.y}` | Siblings with different extensions | `{README.md,tsconfig.json}` |
-| `dir/{stems}.ext` | All files in dir share an extension | `utils/{api,auth,format}.ts` |
-| `dir/file` | Single-child directory collapsed | `scripts/build.sh` |
-| `{a,b,...}.ext` | Truncated group (more files exist) | `images/{logo,hero,...}.png` |
-
-### Compression rules
-
-1. **Mixed directories** (files + subdirs): all files grouped into one `{...}` set
-2. **Files-only directories**: grouped by shared extension (compound-aware: `.test.ts`, `.config.js`)
-3. **Inline collapse**: directories that compress to a single item shown inline
-4. **Single-child chain**: `a/b/c.txt` when each level has one child
-5. **Truncation**: groups with >8 items show the first 5 + `...`
-
-### Default ignores
-
-treezip hardcodes an aggressive noise filter tuned for LLM context — build
-artifacts, caches, and OS junk never reach the output:
-
-- **VCS**: `.git` (dir and worktree pointer file), `.hg`, `.svn`, `.jj`, …
-- **OS**: `.DS_Store`, `Thumbs.db`, `desktop.ini`, `._*` AppleDouble files, …
-- **JS/TS**: `node_modules`, `.next`, `.nuxt`, `.turbo`, `.vite`, `.svelte-kit`,
-  `.astro`, `coverage`, `.wrangler`, `.vercel`, `*.tsbuildinfo`, …
-- **Python**: `__pycache__`, `.venv`/`venv`, `.pytest_cache`, `.mypy_cache`,
-  `.ruff_cache`, `*.egg-info`, `*.pyc`, …
-- **Swift/Xcode**: `DerivedData`, `.build`, `.swiftpm`, `xcuserdata`,
-  `Index.noindex` and friends, …
-- **Others**: `.gradle`, `zig-out`, `_build` (Elixir), `.dart_tool`,
-  `CMakeFiles`, `cmake-build-*`, `.terraform`, `.idea`, `.vs`, …
-
-Three smarter rules on top of the basename list:
-
-1. **Content markers** — a directory containing `pyvenv.cfg` is a venv, one
-   containing `Index.noindex` is an Xcode DerivedData root; both are skipped
-   *whatever they're named* (catches custom `-derivedDataPath` dirs).
-2. **Sibling confirmation** — generic names are only skipped when the
-   ecosystem is proven: `target/` next to `Cargo.toml`/`pom.xml`, `build/`
-   next to `build.gradle`, `bin`/`obj` next to a `.csproj`. A docs folder
-   named `build/` stays visible.
-3. **Scoped rules** — `.claude/worktrees` is hidden but `.claude/skills`
-   stays; `.yarn/cache` is hidden but `.yarn/patches` stays.
-
-Meaningful files are never hidden: lockfiles (`package-lock.json`,
-`Package.resolved`, `uv.lock`, …), `.env`, `.envrc`, `.vscode`, `.github`.
-
-## Output header
-
-Every output includes a self-documenting header:
+| `{a,b,c}.ext` | siblings sharing an extension | `{Button,Card,Modal}.tsx` |
+| `{a.x,b.y}` | siblings with mixed extensions | `{README.md,tsconfig.json}` |
+| `dir/{stems}.ext` | whole dir shares one extension | `utils/{api,auth,format}.ts` |
+| `dir/file` | single-child chain collapsed | `scripts/build.sh` |
+| `{a,b,...}.ext` | truncated — more files exist | `images/{logo,hero,...}.png` |
+
+### compression rules
+
+1. **mixed directories** (files + subdirs): all files fold into one `{...}` set, subdirs listed after
+2. **files-only directories**: grouped by shared extension, compound-aware — `.test.ts` groups separately from `.ts`, `.config.js` from `.js`
+3. **inline collapse**: a directory that compresses to a single item renders on one line
+4. **single-child chains**: `a/b/c.txt` when each level has exactly one child
+5. **truncation**: groups over 8 items show the first 5 + `...`
+
+### self-documenting header
+
+every output starts with a 3-line legend:
 
 ```
 # COMPRESSED FILE TREE — AI READ GUIDE
@@ -147,20 +136,88 @@ Every output includes a self-documenting header:
 # {...}.ext     → truncated list (more exist)  | decompress: expand braces × each entry = 1 path
 ```
 
-This lets LLMs interpret the format without extra instructions.
+paste the output anywhere — the model gets the decoding instructions for free, no system-prompt setup needed.
+
+## the noise filter
+
+this is the part most tree tools don't do. ripgrep, fd, tokei, eza all delegate to `.gitignore` — which is great until the repo has no gitignore, or the junk is inside a worktree, or someone pointed `-derivedDataPath` at a folder inside the repo. `treezip` ships its own opinionated filter, built from the github/gitignore templates, vendor docs, and the default-ignore lists of repomix/gitingest. it works in three layers:
+
+### layer 1 — basename blocklist
+
+distinctive names that are noise in any repo, skipped unconditionally:
+
+- **vcs internals**: `.git` (dir *and* the worktree/submodule pointer file), `.hg`, `.svn`, `.bzr`, `.jj`, `.sapling`
+- **os junk**: `.DS_Store`, `.Spotlight-V100`, `.Trashes`, `.fseventsd`, `Thumbs.db`, `desktop.ini`, `$RECYCLE.BIN`, `__MACOSX`, `._*` appledouble files
+- **js/ts**: `node_modules`, `.pnpm`, `.next`, `.nuxt`, `.output`, `.turbo`, `.parcel-cache`, `.vite`, `.svelte-kit`, `.astro`, `.angular`, `.docusaurus`, `.expo`, `.wrangler`, `.vercel`, `.netlify`, `.serverless`, `coverage`, `.nyc_output`, `storybook-static`, `*.tsbuildinfo`, `.eslintcache`
+- **python**: `__pycache__`, `.venv`, `venv`, `.tox`, `.nox`, `.pytest_cache`, `.mypy_cache`, `.ruff_cache`, `.hypothesis`, `.ipynb_checkpoints`, `*.egg-info`, `htmlcov`, `*.pyc`, `.coverage`
+- **swift/xcode**: `DerivedData`, `.build`, `.swiftpm`, `xcuserdata`, `Carthage`, `SourcePackages`, `Index.noindex`, `ModuleCache.noindex`, `Intermediates.noindex`, `CompilationCache.noindex`, `SDKStatCaches.noindex`
+- **everything else**: `.gradle` (jvm), `zig-cache`/`.zig-cache`/`zig-out`, `_build`/`.elixir_ls` (elixir), `.dart_tool` (flutter), `CMakeFiles`/`_deps`/`cmake-build-*` (cmake), `.vs`/`.idea` (ide caches), `.bundle`/`.yardoc` (ruby), `.terraform`/`.terragrunt-cache`/`.vagrant`/`.direnv` (infra)
 
-## Programmatic API
+### layer 2 — content markers
+
+build roots can be named *anything*. xcode's `-derivedDataPath` lets you point builds at `.test-app-build/` or `whatever/`; python venvs get called `env`, `myenv`, `env310`. name-matching can't catch these — so `treezip` peeks one level inside every directory:
+
+- contains `pyvenv.cfg` → it's a venv, skip it
+- contains `Index.noindex` / `ModuleCache.noindex` / `SDKStatCaches.noindex` / `CompilationCache.noindex` → it's a derived-data root, skip it
+
+whatever it's named, however deep it hides.
+
+### layer 3 — context-aware rules
+
+generic words like `target` and `build` are dangerous to blanket-ignore — a docs folder named `build/` is real content. so these only get skipped when a sibling file proves the ecosystem:
+
+| dir | skipped only next to |
+|---|---|
+| `target/` | `Cargo.toml` or `pom.xml` |
+| `build/` | `build.gradle`, `build.gradle.kts`, `settings.gradle(.kts)` |
+| `deps/` | `mix.exs` |
+| `bin/`, `obj/` | a `.csproj`/`.fsproj`/`.vbproj`/`.sln` |
+
+plus parent-scoped rules where a dot-dir is half config, half cache:
+
+- `.claude/worktrees` hidden, `.claude/skills` kept
+- `.yarn/cache`, `.yarn/unplugged` hidden, `.yarn/patches`, `.yarn/releases` kept
+
+### what never gets hidden
+
+signal stays, always:
+
+- lockfiles — `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, `Cargo.lock`, `Package.resolved`, `poetry.lock`, `uv.lock`
+- `.env`, `.envrc` — you want to *know* those exist
+- `.vscode`, `.github` — committed config, often load-bearing
+- `.xcodeproj` bundles — project definition is source (only the `xcuserdata` inside is junk)
+
+## programmatic api
 
 ```ts
 import { scan, compress, render, countNodes } from "treezip";
 
-const tree = scan("./my-project");
-const compressed = compress(tree);
-const { dirs, files } = countNodes(tree);
+const tree = scan("./my-project");          // filtered TreeNode
+const compressed = compress(tree);           // CompressedItem[]
+const { dirs, files } = countNodes(tree);    // post-filter counts
 const output = render("my-project/", compressed);
 console.log(output);
 ```
 
-## License
+the noise predicates are exported too, if you want the filter without the tree:
+
+```ts
+import { isNoiseDir, isNoiseFile, hasNoiseMarker, NOISE_DIRS, NOISE_FILES } from "treezip";
+
+isNoiseDir("node_modules", "my-project", []);        // true
+isNoiseDir("build", "repo", ["build.gradle"]);        // true (gradle proven)
+isNoiseDir("build", "repo", ["README.md"]);           // false (could be real)
+hasNoiseMarker(["pyvenv.cfg", "bin", "lib"]);          // true (it's a venv)
+```
+
+## design notes
+
+- **zero dependencies.** stdlib `fs` + `path`, nothing else. install is instant, supply chain is empty.
+- **symlinks are skipped**, so cycles can't happen and the tree never leaves the root.
+- **deterministic output**: files first, then dirs, both alphabetical — same input, same bytes out.
+- **the root is never filtered.** if you explicitly run `treezip ./node_modules`, you get `node_modules` — you asked, treezip answers.
+- releases are automated: every push to `main` runs the test suite, bumps the patch version, tags, and publishes to npm.
+
+## license
 
-MIT
+mit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "treezip",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Compressed tree output for AI-optimized codebase summaries",
   "type": "module",
   "bin": {