Core workflow

1. Discover files

parse and update normalize the root path, recursively walk it, and keep supported extensions. The scanner skips .git, .idea, .vscode, node_modules, __pycache__, vendor, and hidden directories. It then applies the root .gitignore rules and explicit --exclude patterns.

Unreadable walk entries are skipped. A path that does not exist stops the CLI with an error before scanning.

2. Select parser work

For a normal parse, caching is enabled by default. Sunset reads the content hash for each discovered file, skips unchanged files, and parses new or changed files. With --no-cache, Sunset does not load or save cache state and parses every discovered file. The default parser concurrency is runtime.NumCPU; a positive --concurrency value limits parser work. The engine records per-file errors and continues processing other files.

update uses the cache but always selects summary mode and does not expose --detail, --max-depth, or --no-cache.

3. Render Markdown

Summary mode extracts functions, types, imports, constants, package names for Go, and associated doc comments. Full mode renders the complete concrete syntax tree and accepts --max-depth. Sunset writes index.md plus sanitized per-file names under the output directory.

4. Save incremental state

Successful runs save file hashes, language IDs, and update times to .sunset/cache/cache.json. On later runs unchanged files are skipped and cache entries for no-longer-discovered files are pruned. clean removes the complete .sunset directory.