feat(tests): add shadow-classification lint; fix real cp/mv/less bugs

New Phase 1b in tests/run-tests.fish: catches a bare C1-shadowed-command call in a functions/*.fish body with no matching uses-shadow(name) or self-limiting(name) in that function's own CLASSIFICATION header. This is exactly the check discussed after the rm and cd audits -- runtime auto-unwrapping isn't viable in fish (there's no hook finer than shadowing itself, and rewriting behavior invisibly at runtime is its own footgun); a static lint using the CLASSIFICATION tag as the declared-intentional marker is. Scoped to functions/*.fish only: the one-function-per-file convention there makes body extraction exact with no block-depth parser needed. Added a new self-limiting(name) tag to the schema for the case a bare call is safe not because the caller did anything, but because the shadow's own logic already neutralizes the override: rm's and mkdir's flag checks (verified precisely -- rm falls back to command rm for any flag except a bare -r/-R/--recursive alone, which still routes to trash; mkdir falls back to command mkdir -p for any flag, no exception), and grep/fgrep/egrep/dir/vdir/cat's own tty auto-detection (--color=auto, and bat's default color behavior -- verified byte-identical to stock cat when piped, since bat also auto-disables highlighting on a non-terminal). Explicit and durable rather than a silent lint exemption: if a shadow's bypass condition is ever weakened, every self-limiting site is one grep away instead of silently wrong. Running the first draft of the lint surfaced three more real bugs, none previously audited: - config-help.fish's --man pager path checks `type -q less` (proving it wants the real less binary specifically, for less-only -R/+N flag syntax) then called it bare, routing through our own $PAGER -> ov -> less -> more -> cat fallback chain instead -- which could hand those less-specific flags to a completely different program. Now command less. - _fish_deps_install.fish and _fish_deps_update.fish's binary-upgrade paths cp a freshly downloaded binary over an already-installed one with no existence guard -- the update flow's target is guaranteed to already exist. Our cp shadow forces -i unconditionally (a plain alias, not flag-aware like rm's), so this would hang waiting on a confirmation prompt in any non-interactive run. Now command cp. Same two files' lazydocker install path piped curl output into bare bash, invoking our shell-switch wrapper instead of a plain subshell. Now command bash. - agents-init.fish's AGENTS.md/CLAUDE.md relocation calls mv bare in four places; each is already guarded by a preceding test -f check on the destination, so the -i alias was unlikely to ever fire in practice, but explicit command mv removes the reliance on that guard entirely rather than leaving it as the only thing standing between a file move and an unattended hang. The remaining ~65 flagged call sites across ~24 files were reviewed individually and tagged self-limiting(rm)/self-limiting(mkdir) (verified flagged with -f/-rf or -p) and self-limiting(grep)/ self-limiting(cat) (verified piped, captured, or -q/-c; none display color to a human), plus uses-shadow(ls) for two existence-check-only calls (cffetch.fish, ffetch.fish) whose output is redirected to /dev/null.
2026-09-21 21:26:55 -04:00
parent 373917d002
commit 3414f81cb6
26 changed files with 165 additions and 23 deletions
@@ -35,6 +35,26 @@ it empty as a placeholder.
  break this function's logic: timestamps leaking into a parsed capture,
  `-i` prompting on a path meant to run unattended, structural output
  changes breaking a `string`/`sed` parse, etc.
+- **`self-limiting(name[,name...])`** — calls a shadowed command bare, and
+  it's safe not because the caller did anything but because *the shadow's
+  own logic* already neutralizes the override for this call. Verify the
+  actual condition per shadow, it's not the same check for each one:
+  - `rm` falls back to `command rm` for any flag **except** a bare `-r`,
+    `-R`, or `--recursive` (those still route to `trash put`) — so
+    `rm -f`/`rm -rf` qualify, but `rm -r $dir` alone does not.
+  - `mkdir` falls back to `command mkdir -p` for *any* flag at all, no
+    exception.
+  - `--color=auto`/`bat`'s own tty auto-detection (`grep`, `fgrep`,
+    `egrep`, `dir`, `vdir`, `cat` — verified byte-identical to stock when
+    piped or captured, since none of these force color on a
+    non-terminal).
+
+  Document it explicitly rather than leaving the bare call untagged: if a
+  shadow's bypass condition is ever weakened, narrowed, or removed, every
+  `self-limiting` site is one grep away instead of silently wrong.
+  Don't use this for `ls` — eza's long-format/icon layout is structural,
+  not tty-gated, so it stays different from stock `ls` even piped; a
+  bare `ls` call still needs `uses-shadow(ls)` or a real bypass.
 - **`destructive`** — can irreversibly delete or overwrite data: `rm -f`,
  `rm -rf`, truncating or force-overwriting a file, `git push --force`.
  Routine cleanup of the function's own `$tmpdir`/`$_tmpdir`/`mktemp`
@@ -4,6 +4,9 @@
 # COMPONENT
 #   logging/terminal-capture
 #
+# CLASSIFICATION
+#   self-limiting(rm,mkdir)
+#
 # SYNOPSIS
 #   __fish_config_sync_logging
 #
@@ -1,6 +1,9 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later

+# CLASSIFICATION
+#   self-limiting(grep)
+#
 # SYNOPSIS
 #   __fish_real_command <name>
 #
@@ -5,7 +5,7 @@
 #   autoexec/sync
 #
 # CLASSIFICATION
-#   destructive
+#   self-limiting(rm), destructive
 #
 # SYNOPSIS
 #   __fish_user_dots_link
@@ -1,6 +1,9 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later

+# CLASSIFICATION
+#   self-limiting(grep)
+#
 # SYNOPSIS
 #   _agents_init_ensure_gitignore <root> <label> <pattern>...
 #
@@ -1,6 +1,9 @@
 # Copyright (C) 2026 Rootiest
 # SPDX-License-Identifier: AGPL-3.0-or-later

+# CLASSIFICATION
+#   self-limiting(rm,mkdir)
+#
 # SYNOPSIS
 #   _agents_repo_ensure_symlink <link> <target>
 #
@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later

 # CLASSIFICATION
-#   destructive, network, blocking-prompt
+#   self-limiting(rm,mkdir,cat), bypasses-shadow(cp,bash), destructive, network, blocking-prompt
 #
 # SYNOPSIS
 #   _fish_deps_install
@@ -284,7 +284,7 @@ function _fish_deps_install
                    end
                    test $_go_status -eq 0
                case special-lazydocker
-                    curl https://raw.githubusercontent.com/jesseduffield/lazydocker/master/scripts/install_update_linux.sh | bash
+                    curl https://raw.githubusercontent.com/jesseduffield/lazydocker/master/scripts/install_update_linux.sh | command bash
                case special-marktext-paru
                    paru -S --noconfirm marktext-bin
                case special-marktext-yay
@@ -312,7 +312,7 @@ function _fish_deps_install
                        -o "$_tmpdir/$_zip"
                    and unzip -o "$_tmpdir/$_zip" -d "$_tmpdir"
                    and mkdir -p "$_wt_dir" "$HOME/.local/bin"
-                    and cp "$_tmpdir/$_bin_src" "$_wt_bin"
+                    and command cp "$_tmpdir/$_bin_src" "$_wt_bin"
                    and chmod +x "$_wt_bin"
                    and ln -sf "$_wt_bin" "$HOME/.local/bin/wakatime"
                    rm -rf "$_tmpdir"
@@ -323,7 +323,7 @@ function _fish_deps_install
                    and curl -fL "https://github.com/equalsraf/win32yank/releases/latest/download/$_zip" \
                        -o "$_tmpdir/$_zip"
                    and unzip -o "$_tmpdir/$_zip" -d "$_tmpdir"
-                    and cp "$_tmpdir/win32yank.exe" "$HOME/.local/bin/win32yank.exe"
+                    and command cp "$_tmpdir/win32yank.exe" "$HOME/.local/bin/win32yank.exe"
                    and chmod +x "$HOME/.local/bin/win32yank.exe"
                    set -l _dl_status $status
                    rm -rf "$_tmpdir"
@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later

 # CLASSIFICATION
-#   destructive, network
+#   self-limiting(rm,mkdir), bypasses-shadow(mv), destructive, network
 #
 # SYNOPSIS
 #   _fish_deps_marktext_appimage
@@ -57,7 +57,7 @@ function _fish_deps_marktext_appimage
    and chmod +x "$tmp/marktext"
    # Replace via mv, not a write into $dest: overwriting a running AppImage
    # in place corrupts the live mount.
-    and mv -f "$tmp/marktext" "$dest"
+    and command mv -f "$tmp/marktext" "$dest"
    and set ok 1
    rm -rf $tmp

@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later

 # CLASSIFICATION
-#   destructive, network
+#   self-limiting(rm), bypasses-shadow(cp,bash), destructive, network
 #
 # SYNOPSIS
 #   _fish_deps_update
@@ -93,7 +93,7 @@ function _fish_deps_update
        # lazydocker: re-run the official install/update script
        if test "$special" = curl-lazydocker
            echo "Updating $bin..."
-            curl https://raw.githubusercontent.com/jesseduffield/lazydocker/master/scripts/install_update_linux.sh | bash
+            curl https://raw.githubusercontent.com/jesseduffield/lazydocker/master/scripts/install_update_linux.sh | command bash
            set updated_any 1
            set i (math $i + 1)
            continue
@@ -141,7 +141,7 @@ function _fish_deps_update
            curl -L "https://github.com/wakatime/wakatime-cli/releases/latest/download/$_zip" \
                -o "$_tmpdir/$_zip"
            and unzip -o "$_tmpdir/$_zip" -d "$_tmpdir"
-            and cp "$_tmpdir/$_bin_src" "$_wt_bin"
+            and command cp "$_tmpdir/$_bin_src" "$_wt_bin"
            and chmod +x "$_wt_bin"
            rm -rf "$_tmpdir"
            and set updated_any 1
@@ -158,7 +158,7 @@ function _fish_deps_update
            curl -fL "https://github.com/equalsraf/win32yank/releases/latest/download/$_zip" \
                -o "$_tmpdir/$_zip"
            and unzip -o "$_tmpdir/$_zip" -d "$_tmpdir"
-            and cp "$_tmpdir/win32yank.exe" "$HOME/.local/bin/win32yank.exe"
+            and command cp "$_tmpdir/win32yank.exe" "$HOME/.local/bin/win32yank.exe"
            and chmod +x "$HOME/.local/bin/win32yank.exe"
            set -l _up_status $status
            rm -rf "$_tmpdir"
@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later

 # CLASSIFICATION
-#   bypasses-shadow(cat,rm), destructive
+#   bypasses-shadow(cat,rm), self-limiting(grep), destructive
 #
 # SYNOPSIS
 #   _scrollback_prune_junk [dir]
@@ -7,6 +7,9 @@
 # DEPENDENCIES
 #   _agents_repo_install_tools, _agents_repo_sync, _agents_init_ensure_gitignore
 #
+# CLASSIFICATION
+#   self-limiting(rm,mkdir), bypasses-shadow(mv)
+#
 # SYNOPSIS
 #   agents-init [-a | --agents] [-p | --plugins] [-v | --verbose]
 #               [-q | --quiet] [-s | --silent] [-h | --help]
@@ -212,7 +215,7 @@ function agents-init --description 'scaffold AGENTS/ sub-repo with agent spec fi
        if test $has_agents -eq 1; and test $has_claude -eq 1
            # Both exist: preserve each as its own file in AGENTS/
            if not test -f "$agents_dir/AGENTS.md"
-                if not mv "$root/AGENTS.md" "$agents_dir/AGENTS.md"
+                if not command mv "$root/AGENTS.md" "$agents_dir/AGENTS.md"
                    echo "$c_err""Error: could not move AGENTS.md → AGENTS/AGENTS.md$c_reset" >&2
                    return 1
                end
@@ -220,7 +223,7 @@ function agents-init --description 'scaffold AGENTS/ sub-repo with agent spec fi
                test $verbose -eq 1; and echo "$c_ok→ Moved AGENTS.md → AGENTS/AGENTS.md$c_reset"
            end
            if not test -f "$agents_dir/CLAUDE.md"; and not test -L "$agents_dir/CLAUDE.md"
-                if not mv "$root/CLAUDE.md" "$agents_dir/CLAUDE.md"
+                if not command mv "$root/CLAUDE.md" "$agents_dir/CLAUDE.md"
                    echo "$c_err""Error: could not move CLAUDE.md → AGENTS/CLAUDE.md$c_reset" >&2
                    return 1
                end
@@ -229,7 +232,7 @@ function agents-init --description 'scaffold AGENTS/ sub-repo with agent spec fi
            end
        else if test $has_agents -eq 1
            if not test -f "$agents_dir/AGENTS.md"
-                if not mv "$root/AGENTS.md" "$agents_dir/AGENTS.md"
+                if not command mv "$root/AGENTS.md" "$agents_dir/AGENTS.md"
                    echo "$c_err""Error: could not move AGENTS.md → AGENTS/AGENTS.md$c_reset" >&2
                    return 1
                end
@@ -239,7 +242,7 @@ function agents-init --description 'scaffold AGENTS/ sub-repo with agent spec fi
        else if test $has_claude -eq 1
            # Only CLAUDE.md: treat it as the agent spec
            if not test -f "$agents_dir/AGENTS.md"
-                if not mv "$root/CLAUDE.md" "$agents_dir/AGENTS.md"
+                if not command mv "$root/CLAUDE.md" "$agents_dir/AGENTS.md"
                    echo "$c_err""Error: could not move CLAUDE.md → AGENTS/AGENTS.md$c_reset" >&2
                    return 1
                end
@@ -9,6 +9,9 @@
 #   _agents_repo_ensure_symlink, _agents_repo_sync,
 #   _agents_repo_install_tools, git, hostname
 #
+# CLASSIFICATION
+#   self-limiting(rm,mkdir)
+#
 # SYNOPSIS
 #   agents-vault [--link] [--push] [--restore] [--status]
 #                [--adopt=SLUG] [--remote=URL]
@@ -4,6 +4,9 @@
 # CATEGORY
 #   12-ai-and-developer-tools
 #
+# CLASSIFICATION
+#   self-limiting(grep)
+#
 # SYNOPSIS
 #   antigravity-ide [args...]
 #
@@ -4,6 +4,9 @@
 # CATEGORY
 #   14-miscellaneous
 #
+# CLASSIFICATION
+#   uses-shadow(ls)
+#
 # SYNOPSIS
 #   cffetch [args...]
 #
@@ -4,6 +4,9 @@
 # CATEGORY
 #   05-package-management
 #
+# CLASSIFICATION
+#   self-limiting(grep)
+#
 # SYNOPSIS
 #   cleanup
 #
@@ -4,6 +4,9 @@
 # CATEGORY
 #   14-miscellaneous
 #
+# CLASSIFICATION
+#   self-limiting(grep), bypasses-shadow(less)
+#
 # SYNOPSIS
 #   config-help [section]
 #   config-help --html
@@ -347,7 +350,7 @@ function config-help --description 'Open the offline fish shell configuration ma

    else if type -q less
        string replace -ra $span_raw $span_bold <"$doc_file" \
-            | less -R +"$start_line"
+            | command less -R +"$start_line"

    else
        string replace -ra $span_raw $span_bold <"$doc_file"
@@ -4,6 +4,9 @@
 # CATEGORY
 #   13-media-and-utilities
 #
+# CLASSIFICATION
+#   self-limiting(rm)
+#
 # SYNOPSIS
 #   dng2avif [-h] [-i <file>] [-o <file>] [-q <n>] [-s <n>] [input.dng]
 #
@@ -5,7 +5,7 @@
 #   03-editors-and-viewers
 #
 # CLASSIFICATION
-#   bypasses-shadow(rm)
+#   bypasses-shadow(rm), self-limiting(cat)
 #
 # SYNOPSIS
 #   fc [command_prefix]
@@ -4,6 +4,9 @@
 # CATEGORY
 #   14-miscellaneous
 #
+# CLASSIFICATION
+#   uses-shadow(ls)
+#
 # SYNOPSIS
 #   ffetch [args...]
 #
@@ -5,7 +5,7 @@
 #   04-git-and-version-control
 #
 # CLASSIFICATION
-#   network, blocking-prompt
+#   self-limiting(grep,cat), network, blocking-prompt
 #
 # SYNOPSIS
 #   gi [-h] [-b] [-p] [-s] [-l] [targets...]
@@ -8,7 +8,7 @@
 #   integrations/history-logs
 #
 # CLASSIFICATION
-#   bypasses-shadow(cat), network
+#   bypasses-shadow(cat), self-limiting(rm), network
 #
 # SYNOPSIS
 #   logs [-h] [-c <category>]
@@ -10,7 +10,7 @@
 #   _mkrep_repo_exists, git
 #
 # CLASSIFICATION
-#   bypasses-shadow(cd), destructive, network
+#   bypasses-shadow(cd), self-limiting(rm), destructive, network
 #
 # SYNOPSIS
 #   mkrep [--cd | --no-cd] [--mkdir | --no-mkdir] [--git | --no-git]
@@ -5,7 +5,7 @@
 #   10-network
 #
 # CLASSIFICATION
-#   network
+#   self-limiting(cat), network
 #
 # SYNOPSIS
 #   qr [text...]
@@ -4,6 +4,9 @@
 # CATEGORY
 #   07-system-and-monitoring
 #
+# CLASSIFICATION
+#   self-limiting(grep)
+#
 # SYNOPSIS
 #   sbver [--brief]
 #
@@ -9,7 +9,7 @@
 #   site logging-guard: logging/terminal-capture
 #
 # CLASSIFICATION
-#   destructive
+#   self-limiting(rm,mkdir), destructive
 #
 # SYNOPSIS
 #   smart_exit [-h] [-n]
@@ -53,6 +53,89 @@ if test $syntax_failed -ne 0 -o $indent_failed -ne 0
    set overall_failed 1
 end

+# ---- Phase 1b: shadow-classification lint --------------------------------
+# Catches a bare C1-shadowed-command call in a function body with no
+# matching uses-shadow(name) or self-limiting(name) in that function's own
+# CLASSIFICATION header -- the exact bug class fixed across fc.fish,
+# dng2avif.fish, _scrollback_prune_junk.fish, mkcd.fish, and mkrep.fish. A
+# bare call is either declared (uses-shadow: wanted; self-limiting: safe
+# because the shadow's own logic neutralizes it, e.g. rm/mkdir's flag check
+# or grep/cat's tty-auto-detected color) or it's undocumented at best, a bug
+# at worst -- the lint never guesses which on its own; see
+# docs/function-classification-schema.md for the full tag definitions and
+# why the reasoning belongs in a tag, not in this script.
+#
+# Scoped to functions/*.fish only: the one-function-per-file convention
+# there makes "everything after the function line is its body" exact, with
+# no block-depth parser needed. conf.d/*.fish can define several functions
+# in one file and isn't covered -- see docs/function-classification-schema.md.
+echo
+echo "== Shadow-classification lint =="
+
+# help and edit are deliberately excluded: help's real bypass is
+# __original_help (not command/builtin), and edit has no backing binary at
+# all to bypass to -- see docs/manual/08-components-reference/01-c1-command-shadows.md.
+set -l shadow_names ls cat cd rm less du top ping ssh rg mkdir bash cp mv wget grep fgrep egrep dir vdir claude
+
+set -l class_checked 0
+set -l class_files_failed 0
+set -l class_issues 0
+
+for f in $repo_root/functions/*.fish
+    set -l lines (cat $f)
+
+    # Find the function line; everything before it is header, everything
+    # from it onward is body (one function per file).
+    set -l func_idx 0
+    for i in (seq (count $lines))
+        if string match -qr '^function ' -- $lines[$i]
+            set func_idx $i
+            break
+        end
+    end
+    test $func_idx -eq 0; and continue
+    set class_checked (math $class_checked + 1)
+
+    # Pull uses-shadow(...) and self-limiting(...) names from the
+    # CLASSIFICATION tag line, if any -- either one accounts for a bare call.
+    set -l declared
+    for i in (seq (math $func_idx - 1))
+        if test "$lines[$i]" = "# CLASSIFICATION"; and test $i -lt $func_idx
+            set -l tagline $lines[(math $i + 1)]
+            for tag in uses-shadow self-limiting
+                set -l m (string match -r "$tag"'\(([^)]*)\)' -- $tagline)
+                test -n "$m[2]"; and set -a declared (string trim -- (string split ',' -- $m[2]))
+            end
+            break
+        end
+    end
+
+    set -l file_failed 0
+    for i in (seq $func_idx (count $lines))
+        set -l line $lines[$i]
+        # Strip quoted spans and comments so string literals (error
+        # messages, --description text) never masquerade as a call.
+        set -l stripped (string replace -ra '"[^"]*"' '' -- $line)
+        set stripped (string replace -ra "'[^']*'" '' -- $stripped)
+        set stripped (string replace -r '#.*$' '' -- $stripped)
+
+        for name in $shadow_names
+            if string match -qr '(^|[;|(]|\band\b|\bor\b|\bnot\b|\bif\b|\bwhile\b|\bbegin\b)\s*'"$name"'(\s|$)' -- $stripped
+                if not contains -- $name $declared
+                    echo "  FAIL (shadow) "(string replace $repo_root/ '' $f)": line $i calls bare '$name' with no uses-shadow($name)/self-limiting($name)"
+                    set class_issues (math $class_issues + 1)
+                    set file_failed 1
+                end
+            end
+        end
+    end
+    test $file_failed -eq 1; and set class_files_failed (math $class_files_failed + 1)
+end
+echo (math $class_checked - $class_files_failed)"/$class_checked functions passed shadow-classification check"
+if test $class_issues -ne 0
+    set overall_failed 1
+end
+
 # ---- Phase 2: discover suites --------------------------------------------
 # Mode is declared by the suite, not by this driver. Detection is
 # case-insensitive so a near-miss like "# Mode: in-session" is caught rather