inital commit

2026-03-23 23:50:58 +00:00
commit 503c232b30
110 changed files with 7218 additions and 0 deletions
@@ -0,0 +1,80 @@
+.\" ===========================================================================
+.\" dotfiles_doctor.1 — Manual page for the dotfiles_doctor utility
+.\" ===========================================================================
+.TH DOTFILES_DOCTOR 1 "2025-11-06" "dotfiles_doctor" "User Commands"
+.SH NAME
+dotfiles_doctor \- analyze zsh startup health, timings, and timeline from NDJSON logs
+.SH SYNOPSIS
+.B dotfiles_doctor
+.RI [ --timeline ]
+.RI [ --logfile= PATH ]
+.SH DESCRIPTION
+.B dotfiles_doctor
+reads an NDJSON log (newline\-delimited JSON objects) produced by your
+.ZN call_file
+logger during shell startup and prints a health report:
+per\-file durations, exit codes, aggregate timings, and optionally a
+microsecond\-precision load timeline.
+
+The log entries are emitted one JSON object per line (not a single JSON array).
+The tool always "slurps" the file internally.
+.SH OPTIONS
+.TP
+.BR --timeline
+Show a start\->end timeline for each loaded file with microsecond timestamps.
+.TP
+.BR --logfile = PATH
+Path to the NDJSON log file to analyze. Defaults to
+.IR ~/zshrc\-log.json .
+.SH ENVIRONMENT
+.TP
+.B SLOW_THRESHOLD
+Duration (ms) above which a module is flagged "slow". Default: 200.
+.TP
+.B WARN_THRESHOLD
+Duration (ms) above which a module is flagged "warning/very slow". Default: 500.
+.SH REQUIREMENTS
+The script relies on
+.BR jq (1),
+.BR awk (1),
+.BR column (1),
+and standard shell utilities.
+.SH FILES
+.TP
+.I ~/zshrc\-log.json
+Default NDJSON log consumed by
+.B dotfiles_doctor .
+Each line is a JSON object with keys:
+.BR file ,
+.BR label ,
+.BR start ,
+.BR end ,
+.BR duration_ms ,
+.BR exit_code .
+.SH EXIT STATUS
+Returns 0 on success; non\-zero on invocation errors (e.g. missing jq or log file).
+.SH EXAMPLES
+Analyze with defaults:
+.P
+.EX
+dotfiles_doctor
+.EE
+.P
+Show microsecond timeline:
+.P
+.EX
+dotfiles_doctor --timeline
+.EE
+.P
+Use a custom log and tighter thresholds:
+.P
+.EX
+SLOW_THRESHOLD=100 WARN_THRESHOLD=300 dotfiles_doctor \\
+  --logfile="$HOME/tmp/startup.ndjson" --timeline
+.EE
+.SH SEE ALSO
+.BR jq (1),
+.BR zsh (1),
+.BR compinit (1)
+.SH AUTHOR
+Written for your dotfiles; completion and manpage generated by ChatGPT.