Skip to content

📚 ZSHAND Library

Internal library modules in lib/ that support the build system and scripts. These define the canonical framework directory list, manage per-directory dependency manifests, provide dependency-aware rebuild checks, and shared helpers for markdown config, zsh header parsing, and path filtering.

When you need this

Most users never edit lib/. Use this when adding a new framework directory, changing load order, or debugging why a directory isn't rebuilding when a dependency changes. The CLI zr-deps updates .zshand-deps from source; run it after adding cross-directory calls.

Script-support modules (top-level lib/)

Module Purpose
md_config.zsh Resolve and load markdown config (config + docs): _zshand_resolve_md_file, _zshand_load_md_vars.
zsh_header_parse.zsh Parse zsh file headers (# ── Section ─── style): _zshand_header_excerpt, _zshand_get_sizes, _zshand_get_sections, _zshand_normalize_section_key, _zshand_has_priority_title_line, _zshand_file_content_summary.
path_filter.zsh Exclude paths by dir list, fragments, and ignore file: _zshand_should_exclude_path (uses globals PROJ_ROOT, exclude_dirs, exclude_path_fragments, ignore_list).
version.zsh Framework version and related helpers.

Used by bin/header_priority_audit and other scripts that need header parsing or path exclusion.

lib/rebuild/

The rebuild library provides four modules used by the build system and CLI tools like zr-deps.

dirs.zsh

Defines _ZSHAND_FRAMEWORK_DIRS, the canonical ordered list of framework directories: startup, shared_functions, core, functions, widgets, hooks, private_functions. Also provides _zshand_get_framework_dirs [base] to resolve full paths. Every build and loading operation uses this list to ensure consistent ordering.

manifest.zsh

Reads and writes .zshand-deps files — plain text manifests listing which other framework directories a given directory depends on (one name per line). Provides _zshand_read_manifest_deps dir (populates reply array) and _zshand_write_manifest_deps dir dep1 dep2 ....

update_manifest_dependencies.zsh

Scans .zsh files in framework directories for references to other directories (patterns like $ZSHAND/<dir>/) and automatically updates .zshand-deps manifests. Called by the zr-deps CLI tool. Accepts an optional directory name to update only one directory.

check_with_deps.zsh

Provides _zshand_check_needs_rebuild_directory_with_deps dir [base_dir] — returns 0 (needs rebuild) if the directory itself is stale or if any of its declared dependencies have changed. This enables transitive rebuild detection: changing core/ triggers rebuilds of functions/, widgets/, and any other directory that declares core as a dependency.

Dependency Manifests

Each framework directory may contain an .zshand-deps file. For example, widgets/.zshand-deps might contain:

shared_functions
core

This tells the build system that if shared_functions/ or core/ changes, the widgets/ bundle should also be rebuilt.

Load Order

The canonical load order defined in dirs.zsh is:

  1. startup
  2. shared_functions
  3. core
  4. functions
  5. widgets
  6. hooks
  7. private_functions
Document Purpose
🏗️ Build System Compilation and bundle pipeline
📟 zr-deps Update .zshand-deps manifests
📟 zr Standard rebuild
📚 Documentation Index Full doc nav