structure-dumper

Portable repository structure + lightweight content scanner.

Features

• Deterministic directory walk
• Exclusions via regex segments (defaults: node_modules, .git, dist, build, target, .next, .turbo)
• File metadata: size, extension, sha256 hash
• Text analysis: line count, first N sampled lines
• Optional full content embedding for small files
• Binary detection heuristic
• JSON (single file) or NDJSON streaming output
• Optional tree view text export

Install

Copy this folder tools/structure-dumper into any repo or add as a Git submodule. Requires Node.js >= 18.

Usage

node tools/structure-dumper/cli.mjs --out project_structure.json

Common options:

# Different root
node cli.mjs --root ../some/project --out out.json

# Exclude additional directories
node cli.mjs --exclude node_modules,.git,dist,.cache

# Emit NDJSON (one entry per line to stdout)
node cli.mjs --ndjson > structure.ndjson

# Produce a tree outline
node cli.mjs --tree tree.txt

# Adjust sample lines and full content threshold
node cli.mjs --sample-lines 15 --full-max 2048

Output Shape (JSON mode)

{
  "summary": { "generatedAt": "ISO", "root": "repoName", "counts": {...}, "config": {...} },
  "entries": [
    { "path": ".", "type": "dir" },
    { "path": "src/index.ts", "type": "file", "size": 123, "ext": ".ts", "hash": "...", "lineCount": 10, "sample": ["import ..."], "full": "...optional..." }
  ]
}

NDJSON Mode

Each line is an individual JSON object (dir or file entry). Aggregate externally.

License

MIT (see LICENSE file). Attribution appreciated but not required.

Roadmap Ideas

• Parallel hashing / reading
• Ignore patterns file (.structureignore)
• Optional gzip output
• File type classification (code, config, asset)
• Size histogram / language stats

Happy structuring!