feat(shell): open and complete project_open projects anywhere under ~/Code (#204)

* feat(shell): add `project_open` autocomplete

* fix(shell): hash-key cache, sort scan, return 0 from completion

* refactor(shell): drop project_open theme target and redundant targets guard

* refactor(shell): scan projects in a single find pass instead of recursive find

* refactor(shell): scan projects at fixed category/project depth via .git

* fix(shell): drop dead project_open_scan argument flagged by shellcheck

* fix(shell): sort project_open targets and return success from completion guard

* chore(test): convert project_open suite to bats and run it in ci

Author: codepuncher

.github/workflows/lint.yml

@@ -12,6 +12,20 @@ jobs:
         uses: actions/checkout@v3
       - name: Run Shellcheck
         uses: azohra/shell-linter@latest
+        with:
+          # zsh completion functions (shell/completions) use zsh-only syntax
+          # ShellCheck cannot parse; tests/ holds .bats files (non-bash @test
+          # syntax) and third-party BATS submodules. ShellCheck skips both.
+          exclude-paths: "shell/completions,tests"
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          submodules: recursive
+      - name: Run BATS tests
+        run: ./tests/bats/bin/bats tests/*.bats
 
   lua:
     runs-on: ubuntu-latest

.gitmodules

@@ -0,0 +1,12 @@
+[submodule "tests/bats"]
+	path = tests/bats
+	url = https://github.com/bats-core/bats-core.git
+[submodule "tests/test_helper/bats-support"]
+	path = tests/test_helper/bats-support
+	url = https://github.com/bats-core/bats-support.git
+[submodule "tests/test_helper/bats-assert"]
+	path = tests/test_helper/bats-assert
+	url = https://github.com/bats-core/bats-assert.git
+[submodule "tests/test_helper/bats-file"]
+	path = tests/test_helper/bats-file
+	url = https://github.com/bats-core/bats-file.git

shell/aliases

@@ -268,19 +268,101 @@ delete_terms() {
 set_posts_statuses() {
 	wp post update "$(wp post list --post_type="${1}" --post_status="${2}" --format=ids)" --post_status="${3}"
 }
+_project_open_root() {
+	printf '%s\n' "${PROJECT_OPEN_ROOT:-${HOME}/Code}"
+}
+
+_project_open_scan() {
+	local root
+	root="$(_project_open_root)"
+	# Projects live at <root>/<category>/<project> and always hold a .git, so one
+	# find at that fixed depth lists them; submodules sit deeper and fall out.
+	find "${root}" -mindepth 3 -maxdepth 3 -name '.git' 2>/dev/null |
+		sed 's#/\.git$##' |
+		LC_ALL=C sort
+}
+
+_project_open_cache_file() {
+	# Key the cache by a hash of the root so a different PROJECT_OPEN_ROOT never
+	# reads a stale cache. Hashing (not char substitution) avoids path collisions;
+	# trailing slashes are stripped so "/x" and "/x/" share one cache.
+	local root key
+	root="$(_project_open_root)"
+	root="${root%/}"
+	key="$(printf '%s' "${root}" | cksum | cut -d' ' -f1)"
+	printf '%s\n' "${XDG_CACHE_HOME:-${HOME}/.cache}/project_open/projects-${key}"
+}
+
+_project_open_build_cache() {
+	local cache dir tmp root
+	root="$(_project_open_root)"
+	[[ -d "${root}" ]] || return 1
+	cache="$(_project_open_cache_file)"
+	[[ -f "${cache}" ]] && return 0
+
+	dir="${cache%/*}"
+	mkdir -p "${dir}" 2>/dev/null || return 1
+	tmp="$(mktemp "${dir}/projects.XXXXXX")" || return 1
+	if _project_open_scan >"${tmp}" && mv -f "${tmp}" "${cache}"; then
+		return 0
+	fi
+	rm -f "${tmp}"
+	return 1
+}
+
+_project_open_read_cache() {
+	local cache line
+	cache="$(_project_open_cache_file)"
+	[[ -f "${cache}" ]] || return 0
+	while IFS= read -r line || [[ -n "${line}" ]]; do
+		printf '%s\n' "${line}"
+	done < "${cache}"
+}
+
+po_refresh() {
+	local cache
+	cache="$(_project_open_cache_file)"
+	rm -f "${cache}"
+	_project_open_build_cache
+}
+
+_project_open_resolve() {
+	local name="${1}" cache_only="${2}" cache line tmp
+	[[ -n "${name}" ]] || return 1
+	cache="$(_project_open_cache_file)"
+	if [[ -f "${cache}" ]]; then
+		while IFS= read -r line || [[ -n "${line}" ]]; do
+			[[ "${line##*/}" == "${name}" ]] && { printf '%s\n' "${line}"; return 0; }
+		done < "${cache}"
+	fi
+	[[ -n "${cache_only}" ]] && return 1
+	tmp="$(mktemp "${TMPDIR:-/tmp}/project_open_scan.XXXXXX")" || return 1
+	_project_open_scan >"${tmp}"
+	# shellcheck disable=SC2094
+	while IFS= read -r line || [[ -n "${line}" ]]; do
+		[[ "${line##*/}" == "${name}" ]] && { printf '%s\n' "${line}"; rm -f "${tmp}"; return 0; }
+	done < "${tmp}"
+	rm -f "${tmp}"
+	return 1
+}
+
 project_open() {
-	WP_PATH="${HOME}/Code/wordpress"
+	CODE_PATH="$(_project_open_root)"
 
 	if [ -z "${1}" ]; then
-		NEW_PATH="${WP_PATH}"
+		NEW_PATH="${CODE_PATH}"
 
 		tmux setw automatic-rename
 	else
-		NEW_PATH="${WP_PATH}/${1}"
+		NEW_PATH="$(_project_open_resolve "${1}")"
+		if [ -z "${NEW_PATH}" ]; then
+			printf 'No project named %s under %s\n' "${1}" "${CODE_PATH}" >&2
+			return 1
+		fi
 		tmux rename-window "${1}"
 	fi
 
-	if [ -n "${2}" ] && [[ "${2}" != "theme" ]]; then
+	if [ -n "${2}" ]; then
 		# shellcheck disable=SC2164
 		cd "${NEW_PATH}/${2}"
 		return
@@ -292,23 +374,70 @@ project_open() {
 		NEW_PATH="${NEW_PATH}/site"
 	fi
 
-	if [ -z "${2}" ]; then
-		# shellcheck disable=SC2164
-		cd "${NEW_PATH}"
-		return
+	# shellcheck disable=SC2164
+	cd "${NEW_PATH}"
+}
+alias po='project_open'
+
+_project_open_projects() {
+	local proj
+	_project_open_read_cache | while IFS= read -r proj; do
+		printf '%s\n' "${proj##*/}"
+	done
+}
+
+_project_open_targets() {
+	local name="${1}" project_path target_dir
+	[[ -n "${name}" ]] || return 0
+	project_path="$(_project_open_resolve "${name}" cache_only)"
+	[[ -n "${project_path}" ]] || return 0
+	find "${project_path}" -mindepth 1 -maxdepth 1 -type d -not -name '.*' 2>/dev/null |
+		while IFS= read -r target_dir; do
+			printf '%s\n' "${target_dir##*/}"
+		done |
+		LC_ALL=C sort
+}
+
+_project_open_complete_bash() {
+	local current previous candidate
+	current="${COMP_WORDS[COMP_CWORD]}"
+	COMPREPLY=()
+
+	if (( COMP_CWORD == 1 )); then
+		while IFS= read -r candidate; do
+			[[ "${candidate}" == "${current}"* ]] && COMPREPLY+=("${candidate}")
+		done < <(_project_open_projects)
+		return 0
 	fi
 
-	# Find only themes using Composer.
-	THEMES=("${NEW_PATH}/web/app/themes/"*/composer.json)
-	THEME_PATH="${THEMES[1]//composer.json/}"
-	if [ -z "${THEME_PATH}" ]; then
-		echo "No theme available" >&2
-		return 1
+	if (( COMP_CWORD == 2 )); then
+		previous="${COMP_WORDS[COMP_CWORD-1]}"
+		while IFS= read -r candidate; do
+			[[ "${candidate}" == "${current}"* ]] && COMPREPLY+=("${candidate}")
+		done < <(_project_open_targets "${previous}")
+		return 0
 	fi
 
-	cd "${THEME_PATH}" || return
+	return 0
 }
-alias po='project_open'
+
+if [[ -n "${BASH_VERSION:-}" ]]; then
+	complete -F _project_open_complete_bash project_open
+	complete -F _project_open_complete_bash po
+	if [[ $- == *i* ]]; then
+		( _project_open_build_cache & ) >/dev/null 2>&1
+	fi
+fi
+
+if [[ -n "${ZSH_VERSION:-}" ]]; then
+	# Completion is registered the canonical way via an autoloaded #compdef
+	# function on $fpath (shell/completions/_project_open). Here we only kick
+	# off the async cache build; eval defers the zsh-only `&!` past bash parsing.
+	if [[ -o interactive ]]; then
+		eval '_project_open_build_cache >/dev/null 2>&1 &!'
+	fi
+fi
+
 project_edit() {
 	WP_PATH="${HOME}/Code/wordpress"
 

shell/completions/_project_open

@@ -0,0 +1,25 @@
+#compdef project_open po
+
+# Autoloaded via $fpath so compinit (re)registers it on every run, surviving
+# the repeated/deferred compinit calls in zshrc. Discovery helpers live in
+# shell/aliases and are available in the interactive shell.
+
+# Succeed with no candidates if the discovery helpers (from shell/aliases) aren't
+# loaded yet, so zsh doesn't treat this as a failed completer.
+(( $+functions[_project_open_projects] )) || return 0
+
+local -a candidates
+
+if (( CURRENT == 2 )); then
+	candidates=("${(@f)$(_project_open_projects)}")
+	compadd -- "${candidates[@]}"
+	return 0
+fi
+
+if (( CURRENT == 3 )); then
+	candidates=("${(@f)$(_project_open_targets "${words[CURRENT-1]}")}")
+	compadd -- "${candidates[@]}"
+	return 0
+fi
+
+return 0

shell/zshrc

@@ -97,6 +97,9 @@ HISTSIZE=100000
 SAVEHIST=10000
 setopt SHARE_HISTORY
 
+if (( ! ${fpath[(Ie)${HOME}/.dotfiles/shell/completions]} )); then
+	fpath=("${HOME}/.dotfiles/shell/completions" ${fpath})
+fi
 autoload -U compinit && compinit
 zmodload -i zsh/complist
 compdef __git_branch_names gpDo