From f1e8f0898244bd2d834baf7541d10e5eff351d34 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Sun, 10 May 2026 14:13:56 -0500
Subject: refactor(system-lib): extract cj/shell-quote-argument-readable from
 dev-fkeys

Phase 2.2 of utility-consolidation. The "quote only when shell-unsafe characters appear, otherwise leave the argument readable" pattern was trapped in dev-fkeys as `cj/--f6-shell-quote-argument' alongside its `cj/--f6-shell-safe-argument-regexp' constant. Lift both into system-lib.el under their generic names; the F6 branding hid that the same shape is useful for any generated compile/test command where the surrounding line ends up in a *compilation* buffer the user reads.

Six Normal/Boundary tests cover safe inputs that pass through unchanged (alphanumeric paths, test regexes, `FLAG=value', `host:port'), unsafe inputs that get quoted (spaces, `$', `;', `&', backticks, `*'), and the empty-string boundary.

Migrate dev-fkeys's five callers to the new name and add `(require \='system-lib)' per the Phase 2 exit criterion.
---
 ...est-system-lib-shell-quote-argument-readable.el | 55 ++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 tests/test-system-lib-shell-quote-argument-readable.el

(limited to 'tests/test-system-lib-shell-quote-argument-readable.el')

diff --git a/tests/test-system-lib-shell-quote-argument-readable.el b/tests/test-system-lib-shell-quote-argument-readable.el
new file mode 100644
index 00000000..1a0c7227
--- /dev/null
+++ b/tests/test-system-lib-shell-quote-argument-readable.el
@@ -0,0 +1,55 @@
+;;; test-system-lib-shell-quote-argument-readable.el --- Tests for cj/shell-quote-argument-readable -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; `cj/shell-quote-argument-readable' is the readable-quote helper.
+;; When ARGUMENT consists only of characters safe in a shell string,
+;; return it unchanged so the surrounding command stays human-readable
+;; (compile / test command lines, log inspection).  When it contains
+;; whitespace or shell metacharacters, fall back to
+;; `shell-quote-argument' so the result is safe to interpolate.
+
+;;; Code:
+
+(require 'ert)
+
+(add-to-list 'load-path (expand-file-name "modules" user-emacs-directory))
+(require 'system-lib)
+
+(ert-deftest test-cj-shell-quote-argument-readable-simple-path-unchanged ()
+  "Normal: an alphanumeric path is returned unchanged."
+  (should (equal (cj/shell-quote-argument-readable "tests/test-foo.el")
+                 "tests/test-foo.el")))
+
+(ert-deftest test-cj-shell-quote-argument-readable-test-regex-unchanged ()
+  "Normal: a typical test-name regex with safe punctuation is unchanged."
+  (should (equal (cj/shell-quote-argument-readable "^test-dev-fkeys-")
+                 "^test-dev-fkeys-")))
+
+(ert-deftest test-cj-shell-quote-argument-readable-flags-unchanged ()
+  "Normal: arguments with `=', `+', `:' read as-is (FLAG=value, addr:port)."
+  (should (equal (cj/shell-quote-argument-readable "FILE=tests/test-foo.el")
+                 "FILE=tests/test-foo.el"))
+  (should (equal (cj/shell-quote-argument-readable "host:1234")
+                 "host:1234")))
+
+(ert-deftest test-cj-shell-quote-argument-readable-spaces-quoted ()
+  "Boundary: an argument containing spaces falls back to shell-quote-argument."
+  (let ((quoted (cj/shell-quote-argument-readable "path/with space.el")))
+    ;; shell-quote-argument either backslash-escapes or wraps in single
+    ;; quotes; either way the raw input cannot survive verbatim.
+    (should-not (equal quoted "path/with space.el"))
+    (should (string-match-p "space" quoted))))
+
+(ert-deftest test-cj-shell-quote-argument-readable-shell-metachars-quoted ()
+  "Boundary: arguments with `$', `;', `&', backticks, `*' are quoted."
+  (dolist (arg '("$HOME" "a;b" "foo&bar" "back`tick`" "glob*"))
+    (let ((quoted (cj/shell-quote-argument-readable arg)))
+      (should-not (equal quoted arg)))))
+
+(ert-deftest test-cj-shell-quote-argument-readable-empty-string-quoted ()
+  "Boundary: empty string is unsafe in a command line and is quoted."
+  (let ((quoted (cj/shell-quote-argument-readable "")))
+    (should-not (equal quoted ""))))
+
+(provide 'test-system-lib-shell-quote-argument-readable)
+;;; test-system-lib-shell-quote-argument-readable.el ends here
-- 
cgit v1.2.3