From cbdf9ed33f61056f71962ec36f3212943ef3ea6d Mon Sep 17 00:00:00 2001
From: Landon Curt Noll <github-mail@asthe.com>
Date: Sun, 1 Sep 2024 00:16:13 -0700
Subject: [PATCH] add bin/all-jfmt.sh tool

Added `bin/all-jfmt.sh` tool.

Added `make all_jfmt` rule to `Makefile`.
Added `make all_jfmt` to `make www`.

NOTE: Because the `bin/all-jfmt.sh` tool is slow, we did not
add `make all_jfmt` to `make quick_www`.
NOTE: Once the `jprint(1)` tool, as described in [issue
repo](https://github.com/xexyl/jparse), this tool (and a number of other
tools) will run **MUCH FASTER**.

Performed `make www` to accomplish the above and to test under macOS.

FYI: The `make www` takes:

    make www  396.29s user 523.94s system 102% cpu 15:00.82 total

This command will become somewhat faster when the `jprint(1)` tool is ready.
It will become **MUCH** faster when the `jval(1)` tool is ready.

As a comparison, `make quick_www` takes only:

    make quick_www  43.63s user 53.87s system 109% cpu 1:29.17 total
---
 Makefile        |  12 +-
 bin/all-jfmt.sh | 649 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 660 insertions(+), 1 deletion(-)
 create mode 100755 bin/all-jfmt.sh

diff --git a/Makefile b/Makefile
index 3f9a7d628..49241b801 100644
--- a/Makefile
+++ b/Makefile
@@ -53,6 +53,7 @@ GEN_AUTHORS= bin/gen-authors.sh
 GEN_LOCATION= bin/gen-location.sh
 GEN_YEARS= bin/gen-years.sh
 GEN_YEAR_INDEX= bin/gen-year-index.sh
+ALL_JFMT= bin/all-jfmt.sh
 CHK_ENTRY= bin/chk-entry.sh
 GEN_TOP_HTML= bin/gen-top-html.sh
 GEN_OTHER_HTML= bin/gen-other-html.sh
@@ -276,7 +277,7 @@ clobber:
 # Finally: The rules in this section are NOT needed if you
 #	   simple want to examine, run / test winning IOCCC entries.
 
-.PHONY: help genpath genfilelist verify_entry_files gen_authors quick_authors \
+.PHONY: help genpath genfilelist all_jfmt verify_entry_files gen_authors quick_authors \
 	gen_location quick_location gen_years find_missing_links test entry_index gen_top_html \
 	thanks gen_other_html quick_other_html quick_entry_index \
 	gen_year_index quick_year_index quick_www www untar_entry_tarball untar_year_tarball \
@@ -310,6 +311,7 @@ help:
 	@echo 'make tab_check		;: check for ASCII tabs in markdown files'
 	@echo 'make genpath		;: form top level .top and .allyear, YYYY level .year and winner .path files'
 	@echo 'make genfilelist	;: generate YYYY level .filelist'
+	@echo 'make all_jfmt	;: be sure all JSON files are canonical
 	@echo 'make verify_entry_files	;: check to be sure all files in all entries exist'
 	@echo 'make gen_authors	;: generate the top level authors.html page'
 	@echo 'make quick_authors	;: build authors.html if out of date with author JSON files'
@@ -432,6 +434,13 @@ genfilelist:
 	done
 	@echo '=-=-=-=-= IOCCC complete make $@ =-=-=-=-='
 
+# be sure that all JSON files are canonical
+#
+all_jfmt: ${ALL_RUN} ${CHK_ENTRY}
+	@echo '=-=-=-=-= IOCCC begin make $@ =-=-=-=-='
+	${ALL_JFMT} -v 1
+	@echo '=-=-=-=-= IOCCC complete make $@ =-=-=-=-='
+
 # check to be sure all files in all entries exist
 #
 verify_entry_files: ${ALL_RUN} ${CHK_ENTRY}
@@ -705,6 +714,7 @@ www:
 	@${MAKE} genpath >/dev/null
 	@echo '=-=-=-=-= IOCCC complete make genpath =-=-=-=-='
 	${MAKE} genfilelist
+	${MAKE} all_jfmt
 	${MAKE} verify_entry_files
 	${MAKE} gen_authors
 	${MAKE} gen_location
diff --git a/bin/all-jfmt.sh b/bin/all-jfmt.sh
new file mode 100755
index 000000000..fe7e112f0
--- /dev/null
+++ b/bin/all-jfmt.sh
@@ -0,0 +1,649 @@
+#!/usr/bin/env bash
+#
+# all-jfmt.sh - canonically format all entry and author JSON files
+#
+# Copyright (c) 2024 by Landon Curt Noll.  All Rights Reserved.
+#
+# Permission to use, copy, modify, and distribute this software and
+# its documentation for any purpose and without fee is hereby granted,
+# provided that the above copyright, this permission notice and text
+# this comment, and the disclaimer below appear in all of the following:
+#
+#       supporting documentation
+#       source copies
+#       source works derived from this source
+#       binaries derived from this source or from derived source
+#
+# LANDON CURT NOLL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
+# INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
+# EVENT SHALL LANDON CURT NOLL BE LIABLE FOR ANY SPECIAL, INDIRECT OR
+# CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
+# USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+# OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+# PERFORMANCE OF THIS SOFTWARE.
+#
+# chongo (Landon Curt Noll, http://www.isthe.com/chongo/index.html) /\oo/\
+#
+# Share and enjoy! :-)
+
+
+# firewall - run only with a bash that is version 5.1.8 or later
+#
+# The "/usr/bin/env bash" command must result in using a bash that
+# is version 5.1.8 or later.
+#
+# We could relax this version and insist on version 4.2 or later.  Versions
+# of bash between 4.2 and 5.1.7 might work.  However, to be safe, we will require
+# bash version 5.1.8 or later.
+#
+# WHY 5.1.8 and not 4.2?  This safely is done because macOS Homebrew bash we
+# often use is "version 5.2.26(1)-release" or later, and the RHEL Linux bash we
+# use often use is "version 5.1.8(1)-release" or later.  These versions are what
+# we initially tested.  We recommend you either upgrade bash or install a newer
+# version of bash and adjust your $PATH so that "/usr/bin/env bash" finds a bash
+# that is version 5.1.8 or later.
+#
+# NOTE: The macOS shipped, as of 2024 March 15, a version of bash is something like
+#	bash "version 3.2.57(1)-release".  That macOS shipped version of bash
+#	will NOT work.  For users of macOS we recommend you install Homebrew,
+#	(see https://brew.sh), and then run "brew install bash" which will
+#	typically install it into /opt/homebrew/bin/bash, and then arrange your $PATH
+#	so that "/usr/bin/env bash" finds "/opt/homebrew/bin" (or whatever the
+#	Homebrew bash is).
+#
+# NOTE: And while MacPorts might work, we noticed a number of subtle differences
+#	with some of their ported tools to suggest you might be better off
+#	with installing Homebrew (see https://brew.sh).  No disrespect is intended
+#	to the MacPorts team as they do a commendable job.  Nevertheless we ran
+#	into enough differences with MacPorts environments to suggest you
+#	might find a better experience with this tool under Homebrew instead.
+#
+if [[ -z ${BASH_VERSINFO[0]} ||
+	 ${BASH_VERSINFO[0]} -lt 5 ||
+	 ${BASH_VERSINFO[0]} -eq 5 && ${BASH_VERSINFO[1]} -lt 1 ||
+	 ${BASH_VERSINFO[0]} -eq 5 && ${BASH_VERSINFO[1]} -eq 1 && ${BASH_VERSINFO[2]} -lt 8 ]]; then
+    echo "$0: ERROR: bash version needs to be >= 5.1.8: $BASH_VERSION" 1>&2
+    echo "$0: Warning: bash version >= 4.2 might work but 5.1.8 was the minimum we tested" 1>&2
+    echo "$0: Notice: For macOS users: install Homebrew (see https://brew.sh), then run" \
+	 ""brew install bash" and then modify your \$PATH so that \"#!/usr/bin/env bash\"" \
+	 "finds the Homebrew installed (usually /opt/homebrew/bin/bash) version of bash" 1>&2
+    exit 4
+fi
+
+
+# setup bash file matching
+#
+# We must declare arrays with -ag or -Ag, and we need loops to "export" modified variables.
+# This requires a bash with a version 4.2 or later.  See the larger comment above about bash versions.
+#
+shopt -s nullglob	# enable expanded to nothing rather than remaining unexpanded
+shopt -u failglob	# disable error message if no matches are found
+shopt -u dotglob	# disable matching files starting with .
+shopt -u nocaseglob	# disable strict case matching
+shopt -u extglob	# enable extended globbing patterns
+shopt -s globstar	# enable ** to match all files and zero or more directories and subdirectories
+
+
+# set variables referenced in the usage message
+#
+export VERSION="1.0 2024-08-31"
+NAME=$(basename "$0")
+export NAME
+export V_FLAG=0
+GIT_TOOL=$(type -P git)
+export GIT_TOOL
+if [[ -z "$GIT_TOOL" ]]; then
+    echo "$0: FATAL: git tool is not installed or not in \$PATH" 1>&2
+    exit 5
+fi
+"$GIT_TOOL" rev-parse --is-inside-work-tree >/dev/null 2>&1
+status="$?"
+if [[ $status -eq 0 ]]; then
+    TOPDIR=$("$GIT_TOOL" rev-parse --show-toplevel)
+fi
+export TOPDIR
+export DOCROOT_SLASH="../../"
+export TAGLINE="unspecified"
+export REPO_TOP_URL="https://github.com/ioccc-src/temp-test-ioccc"
+# GitHub puts individual files under the "blob/master" sub-directory.
+export REPO_URL="$REPO_TOP_URL/blob/master"
+export SITE_URL="https://ioccc-src.github.io/temp-test-ioccc"
+#
+export NOOP=
+export DO_NOT_PROCESS=
+export EXIT_CODE="0"
+#
+JPARSE_TOOL=$(type -P jparse)
+export JPARSE_TOOL
+
+
+# clear options we will add to tools
+#
+unset TOOL_OPTION
+declare -ag TOOL_OPTION
+
+
+# usage
+#
+export USAGE="usage: $0 [-h] [-v level] [-V] [-d topdir] [-D docroot/] [-j jparse] [-n] [-N]
+
+	-h		print help message and exit
+	-v level	set verbosity level (def level: 0)
+	-V		print version string and exit
+
+	-d topdir	set topdir (def: $TOPDIR)
+	-D docroot/	set the document root path followed by slash (def: $DOCROOT_SLASH)
+			NOTE: The '-D docroot/' is passed as leading options on tool command lines.
+			NOTE: 'docroot' must end in a slash
+
+	-j jparse	path to the jparse tool (def: $JPARSE_TOOL)
+
+	-n		go thru the actions, but do not update any files (def: do the action)
+	-N		do not process anything, just parse arguments (def: process something)
+
+Exit codes:
+     0         all OK
+     1	       some internal tool exited non-zero
+     2         -h and help string printed or -V and version string printed
+     3         command line error
+     4         bash version is too old
+     5	       some internal tool is not found or not an executable file
+     6	       problems found with or in the topdir or topdir/YYYY directory
+     7	       problems found with or in the entry topdir/YYYY/dir directory
+ >= 10         internal error
+
+$NAME version: $VERSION"
+
+
+# parse command line
+#
+while getopts :hv:Vd:D:j:nN flag; do
+  case "$flag" in
+    h) echo "$USAGE" 1>&2
+	exit 2
+	;;
+    v) V_FLAG="$OPTARG"
+	;;
+    V) echo "$VERSION"
+	exit 2
+	;;
+    d) TOPDIR="$OPTARG"
+	;;
+    D) # parse -D docroot/
+	case "$OPTARG" in
+	*/) ;;
+	*) echo "$0: ERROR: in -D docroot/, the docroot must end in /" 1>&2
+	   echo 1>&2
+	   print_usage 1>&2
+	   exit 3
+	   ;;
+	esac
+	DOCROOT_SLASH="$OPTARG"
+	TOOL_OPTION+=("-D")
+	TOOL_OPTION+=("$DOCROOT_SLASH")
+	;;
+    j) JPARSE_TOOL="$OPTARG"
+	;;
+    n) NOOP="-n"
+	;;
+    N) DO_NOT_PROCESS="-N"
+	;;
+    \?) echo "$0: ERROR: invalid option: -$OPTARG" 1>&2
+	echo 1>&2
+	print_usage 1>&2
+	exit 3
+	;;
+    :) echo "$0: ERROR: option -$OPTARG requires an argument" 1>&2
+	echo 1>&2
+	echo "$USAGE" 1>&2
+	exit 3
+	;;
+    *) echo "$0: ERROR: unexpected value from getopts: $flag" 1>&2
+	echo 1>&2
+	echo "$USAGE" 1>&2
+	exit 3
+	;;
+  esac
+done
+#
+# remove the options
+#
+shift $(( OPTIND - 1 ));
+#
+if [[ $V_FLAG -ge 5 ]]; then
+    echo "$0: debug[5]: file argument count: $#" 1>&2
+fi
+#
+# verify arg count and parse args
+#
+if [[ $# -ne 0 ]]; then
+    echo "$0: ERROR: expected 0 args, found: $#" 1>&2
+    echo "$USAGE" 1>&2
+    exit 3
+fi
+
+
+# verify that we have a topdir directory
+#
+REPO_NAME=$(basename "$REPO_TOP_URL")
+export REPO_NAME
+if [[ -z $TOPDIR ]]; then
+    echo "$0: ERROR: cannot find top of git repo directory" 1>&2
+    echo "$0: Notice: if needed: $GIT_TOOL clone $REPO_TOP_URL; cd $REPO_NAME" 1>&2
+    exit 6
+fi
+if [[ ! -e $TOPDIR ]]; then
+    echo "$0: ERROR: TOPDIR does not exist: $TOPDIR" 1>&2
+    echo "$0: Notice: if needed: $GIT_TOOL clone $REPO_TOP_URL; cd $REPO_NAME" 1>&2
+    exit 6
+fi
+if [[ ! -d $TOPDIR ]]; then
+    echo "$0: ERROR: TOPDIR is not a directory: $TOPDIR" 1>&2
+    echo "$0: Notice: if needed: $GIT_TOOL clone $REPO_TOP_URL; cd $REPO_NAME" 1>&2
+    exit 6
+fi
+
+
+# cd to topdir
+#
+if [[ ! -e $TOPDIR ]]; then
+    echo "$0: ERROR: cannot cd to non-existent path: $TOPDIR" 1>&2
+    exit 6
+fi
+if [[ ! -d $TOPDIR ]]; then
+    echo "$0: ERROR: cannot cd to a non-directory: $TOPDIR" 1>&2
+    exit 6
+fi
+export CD_FAILED
+if [[ $V_FLAG -ge 5 ]]; then
+    echo "$0: debug[5]: about to: cd $TOPDIR" 1>&2
+fi
+cd "$TOPDIR" || CD_FAILED="true"
+if [[ -n $CD_FAILED ]]; then
+    echo "$0: ERROR: cd $TOPDIR failed" 1>&2
+    exit 6
+fi
+if [[ $V_FLAG -ge 3 ]]; then
+    echo "$0: debug[3]: now in directory: $(/bin/pwd)" 1>&2
+fi
+
+
+# verify that we have an author subdirectory
+#
+export AUTHOR_PATH="$TOPDIR/author"
+if [[ ! -d $AUTHOR_PATH ]]; then
+    echo "$0: ERROR: author is not a directory under topdir: $AUTHOR_PATH" 1>&2
+    exit 6
+fi
+export AUTHOR_DIR="author"
+
+
+# verify that we have a bin subdirectory
+#
+export BIN_PATH="$TOPDIR/bin"
+if [[ ! -d $BIN_PATH ]]; then
+    echo "$0: ERROR: bin is not a directory under topdir: $BIN_PATH" 1>&2
+    exit 6
+fi
+export BIN_DIR="bin"
+
+
+# verify that the bin/jfmt-wrapper.sh tool is executable
+#
+JFMT_WRAPPER="$BIN_DIR/jfmt-wrapper.sh"
+if [[ ! -e $JFMT_WRAPPER ]]; then
+    echo  "$0: ERROR: bin/jfmt-wrapper.sh does not exist: $JFMT_WRAPPER" 1>&2
+    exit 5
+fi
+if [[ ! -f $JFMT_WRAPPER ]]; then
+    echo  "$0: ERROR: bin/jfmt-wrapper.sh is not a regular file: $JFMT_WRAPPER" 1>&2
+    exit 5
+fi
+if [[ ! -x $JFMT_WRAPPER ]]; then
+    echo  "$0: ERROR: bin/jfmt-wrapper.sh is not an executable file: $JFMT_WRAPPER" 1>&2
+    exit 5
+fi
+
+
+# verify we have a non-empty readable .top file
+#
+export TOP_FILE=".top"
+if [[ ! -e $TOP_FILE ]]; then
+    echo  "$0: ERROR: .top does not exist: $TOP_FILE" 1>&2
+    exit 6
+fi
+if [[ ! -f $TOP_FILE ]]; then
+    echo  "$0: ERROR: .top is not a regular file: $TOP_FILE" 1>&2
+    exit 6
+fi
+if [[ ! -r $TOP_FILE ]]; then
+    echo  "$0: ERROR: .top is not an readable file: $TOP_FILE" 1>&2
+    exit 6
+fi
+if [[ ! -s $TOP_FILE ]]; then
+    echo  "$0: ERROR: .top is not a non-empty readable file: $TOP_FILE" 1>&2
+    exit 6
+fi
+
+
+# verify jparse tool
+#
+if [[ -z "$JPARSE_TOOL" ]]; then
+    echo "$0: ERROR: cannot find an executable jparse tool" 1>&2
+    exit 5
+fi
+if [[ ! -f "$JPARSE_TOOL" ]]; then
+    echo "$0: ERROR: jparse is not a file: $JPARSE_TOOL" 1>&2
+    exit 5
+fi
+if [[ ! -x "$JPARSE_TOOL" ]]; then
+    echo "$0: ERROR: jparse is not an executable file: $JPARSE_TOOL" 1>&2
+    exit 5
+fi
+
+
+# print running info if verbose
+#
+# If -v 3 or higher, print exported variables in order that they were exported.
+#
+if [[ $V_FLAG -ge 3 ]]; then
+    echo "$0: debug[3]: VERSION=$VERSION" 1>&2
+    echo "$0: debug[3]: NAME=$NAME" 1>&2
+    echo "$0: debug[3]: V_FLAG=$V_FLAG" 1>&2
+    echo "$0: debug[3]: GIT_TOOL=$GIT_TOOL" 1>&2
+    echo "$0: debug[3]: TOPDIR=$TOPDIR" 1>&2
+    echo "$0: debug[3]: DOCROOT_SLASH=$DOCROOT_SLASH" 1>&2
+    echo "$0: debug[3]: TAGLINE=$TAGLINE" 1>&2
+    echo "$0: debug[3]: REPO_TOP_URL=$REPO_TOP_URL" 1>&2
+    echo "$0: debug[3]: REPO_URL=$REPO_URL" 1>&2
+    echo "$0: debug[3]: SITE_URL=$SITE_URL" 1>&2
+    echo "$0: debug[3]: NOOP=$NOOP" 1>&2
+    echo "$0: debug[3]: DO_NOT_PROCESS=$DO_NOT_PROCESS" 1>&2
+    echo "$0: debug[3]: EXIT_CODE=$EXIT_CODE" 1>&2
+    for index in "${!TOOL_OPTION[@]}"; do
+	echo "$0: debug[3]: TOOL_OPTION[$index]=${TOOL_OPTION[$index]}" 1>&2
+    done
+    echo "$0: debug[3]: REPO_NAME=$REPO_NAME" 1>&2
+    echo "$0: debug[3]: CD_FAILED=$CD_FAILED" 1>&2
+    echo "$0: debug[3]: AUTHOR_PATH=$AUTHOR_PATH" 1>&2
+    echo "$0: debug[3]: AUTHOR_DIR=$AUTHOR_DIR" 1>&2
+    echo "$0: debug[3]: BIN_PATH=$BIN_PATH" 1>&2
+    echo "$0: debug[3]: BIN_DIR=$BIN_DIR" 1>&2
+    echo "$0: debug[3]: JFMT_WRAPPER=$JFMT_WRAPPER" 1>&2
+    echo "$0: debug[3]: TOP_FILE=$TOP_FILE" 1>&2
+    echo "$0: debug[3]: JPARSE_TOOL=$JPARSE_TOOL" 1>&2
+fi
+
+
+# -N stops early before any processing is performed
+#
+if [[ -n $DO_NOT_PROCESS ]]; then
+    if [[ $V_FLAG -ge 3 ]]; then
+	echo "$0: debug[3]: arguments parsed, -N given, exiting 0" 1>&2
+    fi
+    exit 0
+fi
+
+
+# create a temporary author_handle inventory file
+#
+export TMP_AUTHOR_HANDLE_INVENTORY=".tmp.$NAME.AUTHOR_HANDLE_INVENTORY.$$.tmp"
+if [[ $V_FLAG -ge 3 ]]; then
+    echo  "$0: debug[3]: temporary author_handle inventory file: $TMP_AUTHOR_HANDLE_INVENTORY" 1>&2
+fi
+trap 'rm -f $TMP_AUTHOR_HANDLE_INVENTORY; exit' 0 1 2 3 15
+rm -f "$TMP_AUTHOR_HANDLE_INVENTORY"
+if [[ -e $TMP_AUTHOR_HANDLE_INVENTORY ]]; then
+    echo "$0: ERROR: cannot remove temporary author_handle inventory file: $TMP_AUTHOR_HANDLE_INVENTORY" 1>&2
+    exit 20
+fi
+: > "$TMP_AUTHOR_HANDLE_INVENTORY"
+if [[ ! -e $TMP_AUTHOR_HANDLE_INVENTORY ]]; then
+    echo "$0: ERROR: cannot create temporary author_handle inventory file: $TMP_AUTHOR_HANDLE_INVENTORY" 1>&2
+    exit 21
+fi
+
+
+# process each year
+#
+export YYYY
+for YYYY in $(< "$TOP_FILE"); do
+
+    # debug YYYY
+    #
+    if [[ $V_FLAG -ge 1 ]]; then
+	echo "$0: debug[1]: for $JFMT_WRAPPER: starting to process year: $YYYY" 1>&2
+    fi
+
+    # verify that YYYY is a readable directory
+    #
+    if [[ ! -e $YYYY ]]; then
+	echo  "$0: ERROR: YYYY does not exist: $YYYY" 1>&2
+	EXIT_CODE="6"  # exit 6
+	echo "$0: Warning: EXIT_CODE set to: $EXIT_CODE" 1>&2
+	continue
+    fi
+    if [[ ! -d $YYYY ]]; then
+	echo  "$0: ERROR: YYYY is not a directory: $YYYY" 1>&2
+	EXIT_CODE="6"  # exit 6
+	echo "$0: Warning: EXIT_CODE set to: $EXIT_CODE" 1>&2
+	continue
+    fi
+    if [[ ! -r $YYYY ]]; then
+	echo  "$0: ERROR: YYYY is not an readable directory: $YYYY" 1>&2
+	EXIT_CODE="6"  # exit 6
+	echo "$0: Warning: EXIT_CODE set to: $EXIT_CODE" 1>&2
+	continue
+    fi
+
+    # verify that YYYY has a non-empty readable .year file
+    #
+    export YEAR_FILE="$YYYY/.year"
+    if [[ ! -e $YEAR_FILE ]]; then
+	echo  "$0: ERROR: YYYY/.year does not exist: $YEAR_FILE" 1>&2
+	EXIT_CODE="6"  # exit 6
+	echo "$0: Warning: EXIT_CODE set to: $EXIT_CODE" 1>&2
+	continue
+    fi
+    if [[ ! -f $YEAR_FILE ]]; then
+	echo  "$0: ERROR: YYYY/.year is not a regular file: $YEAR_FILE" 1>&2
+	EXIT_CODE="6"  # exit 6
+	echo "$0: Warning: EXIT_CODE set to: $EXIT_CODE" 1>&2
+	continue
+    fi
+    if [[ ! -r $YEAR_FILE ]]; then
+	echo  "$0: ERROR: YYYY/.year is not an readable file: $YEAR_FILE" 1>&2
+	EXIT_CODE="6"  # exit 6
+	echo "$0: Warning: EXIT_CODE set to: $EXIT_CODE" 1>&2
+	continue
+    fi
+    if [[ ! -s $YEAR_FILE ]]; then
+	echo  "$0: ERROR: YYYY/.year is not a non-empty readable file: $YEAR_FILE" 1>&2
+	EXIT_CODE="6"  # exit 6
+	echo "$0: Warning: EXIT_CODE set to: $EXIT_CODE" 1>&2
+	continue
+    fi
+
+    # process each entry directory under YYYY
+    #
+    export YYYY_DIR
+    for YYYY_DIR in $(< "$YEAR_FILE"); do
+
+	# debug YYYY
+	#
+	if [[ $V_FLAG -ge 3 ]]; then
+	    echo "$0: debug[3]: for $JFMT_WRAPPER: starting to process year/dir: $YYYY_DIR" 1>&2
+	fi
+
+	# parse YYYY_DIR
+	#
+	if [[ ! -d $YYYY_DIR ]]; then
+	    echo "$0: ERROR: YYYY_DIR is not a directory: $YYYY_DIR" 1>&2
+	    EXIT_CODE="6"  # exit 6
+	    echo "$0: Warning: EXIT_CODE set to: $EXIT_CODE" 1>&2
+	    continue
+	fi
+	if [[ ! -w $YYYY_DIR ]]; then
+	    echo "$0: ERROR: YYYY_DIR is not a writable directory: $YYYY_DIR" 1>&2
+	    EXIT_CODE="6"  # exit 6
+	    echo "$0: Warning: EXIT_CODE set to: $EXIT_CODE" 1>&2
+	    continue
+	fi
+	export YEAR_DIR=${YYYY_DIR%%/*}
+	if [[ -z $YEAR_DIR ]]; then
+	    echo "$0: ERROR: YYYY_DIR not in YYYY/dir form: $YYYY_DIR" 1>&2
+	    EXIT_CODE="6"  # exit 6
+	    echo "$0: Warning: EXIT_CODE set to: $EXIT_CODE" 1>&2
+	    continue
+	fi
+	export ENTRY_DIR=${YYYY_DIR#*/}
+	if [[ -z $ENTRY_DIR ]]; then
+	    echo "$0: ERROR: YYYY_DIR not in $YEAR_DIR/dir form: $YYYY_DIR" 1>&2
+	    EXIT_CODE="6"  # exit 6
+	    echo "$0: Warning: EXIT_CODE set to: $EXIT_CODE" 1>&2
+	    continue
+	fi
+	if [[ $ENTRY_DIR = */* ]]; then
+	    echo "$0: ERROR: YYYY_DIR: $YYYY_DIR dir contains a /: $ENTRY_DIR" 1>&2
+	    EXIT_CODE="6"  # exit 6
+	    echo "$0: Warning: EXIT_CODE set to: $EXIT_CODE" 1>&2
+	    continue
+	fi
+
+	# verify that YYYY_DIR is a writable directory
+	#
+	if [[ ! -e $YYYY_DIR ]]; then
+	    echo  "$0: ERROR: YYYY_DIR does not exist: $YYYY_DIR" 1>&2
+	    EXIT_CODE="7"  # exit 7
+	    echo "$0: Warning: EXIT_CODE set to: $EXIT_CODE" 1>&2
+	    continue
+	fi
+	if [[ ! -d $YYYY_DIR ]]; then
+	    echo  "$0: ERROR: YYYY_DIR is not a directory: $YYYY_DIR" 1>&2
+	    EXIT_CODE="7"  # exit 7
+	    echo "$0: Warning: EXIT_CODE set to: $EXIT_CODE" 1>&2
+	    continue
+	fi
+	if [[ ! -w $YYYY_DIR ]]; then
+	    echo  "$0: ERROR: YYYY_DIR is not an writable directory: $YYYY_DIR" 1>&2
+	    EXIT_CODE="7"  # exit 7
+	    echo "$0: Warning: EXIT_CODE set to: $EXIT_CODE" 1>&2
+	    continue
+	fi
+
+	# verify YYYY/dir/.path
+	#
+	export DOT_PATH="$YYYY_DIR/.path"
+	if [[ ! -s $DOT_PATH ]]; then
+	    echo "$0: ERROR: not a non-empty file: $DOT_PATH" 1>&2
+	    EXIT_CODE="7"  # exit 7
+	    echo "$0: Warning: EXIT_CODE set to: $EXIT_CODE" 1>&2
+	    continue
+	fi
+	DOT_PATH_CONTENT=$(< "$DOT_PATH")
+	if [[ $YYYY_DIR != "$DOT_PATH_CONTENT" ]]; then
+	    echo "$0: ERROR: arg: $YYYY_DIR does not match $DOT_PATH contents: $DOT_PATH_CONTENT" 1>&2
+	    EXIT_CODE="7"  # exit 7
+	    echo "$0: Warning: EXIT_CODE set to: $EXIT_CODE" 1>&2
+	    continue
+	fi
+
+	# verify the YYYY/dir/.entry.json
+	#
+	export ENTRY_JSON="$YYYY_DIR/.entry.json"
+	if [[ ! -e $ENTRY_JSON ]]; then
+	    echo "$0: ERROR: .entry.json does not exist: $ENTRY_JSON" 1>&2
+	    EXIT_CODE="7"  # exit 7
+	    echo "$0: Warning: EXIT_CODE set to: $EXIT_CODE" 1>&2
+	    continue
+	fi
+	if [[ ! -f $ENTRY_JSON ]]; then
+	    echo "$0: ERROR: .entry.json is not a file: $ENTRY_JSON" 1>&2
+	    EXIT_CODE="7"  # exit 7
+	    echo "$0: Warning: EXIT_CODE set to: $EXIT_CODE" 1>&2
+	    continue
+	fi
+	if [[ ! -r $ENTRY_JSON ]]; then
+	    echo "$0: ERROR: .entry.json is not a readable file: $ENTRY_JSON" 1>&2
+	    EXIT_CODE="7"  # exit 7
+	    echo "$0: Warning: EXIT_CODE set to: $EXIT_CODE" 1>&2
+	    continue
+	fi
+	if [[ $V_FLAG -ge 3 ]]; then
+	    echo "$0: debug[3]: about to run: $JPARSE_TOOL -q -- $ENTRY_JSON" 1>&2
+	fi
+	if "$JPARSE_TOOL" -q -- "$ENTRY_JSON"; then
+	    if [[ $V_FLAG -ge 5 ]]; then
+		echo "$0: debug[5]: valid JSON: $ENTRY_JSON" 1>&2
+	    fi
+	else
+	    echo "$0: ERROR: .entry.json is not valid JSON: $ENTRY_JSON" 1>&2
+	    EXIT_CODE="7"  # exit 7
+	    echo "$0: Warning: EXIT_CODE set to: $EXIT_CODE" 1>&2
+	    continue
+	fi
+
+	# canonically format YYYY/dir/.entry.json unless -n
+	#
+	if [[ -z $NOOP ]]; then
+	    if [[ $V_FLAG -ge 1 ]]; then
+		echo "$0: debug[1]: about to run: $JFMT_WRAPPER ${TOOL_OPTION[*]} -- $YYYY_DIR/.entry.json" 1>&2
+	    fi
+	    "$JFMT_WRAPPER" "${TOOL_OPTION[@]}" -- "$YYYY_DIR/.entry.json"
+	    status="$?"
+	    if [[ $status -ne 0 ]]; then
+		echo "$0: ERROR: tool: $JFMT_WRAPPER ${TOOL_OPTION[*]} -- $YYYY_DIR/.entry.json failed, error: $status" 1>&2
+		EXIT_CODE="1"  # exit 1
+		echo "$0: Warning: EXIT_CODE set to: $EXIT_CODE" 1>&2
+		continue
+	    fi
+
+	# report disabled by -n
+	#
+	elif [[ $V_FLAG -ge 5 ]]; then
+	    echo "$0: debug[5]: because of -n, did not run: $JFMT_WRAPPER ${TOOL_OPTION[*]} -- $YYYY_DIR/.entry.json" 1>&2
+	fi
+    done
+done
+
+
+# process author/author_handle.json files
+#
+if [[ $V_FLAG -ge 1 ]]; then
+    echo "$0: debug[1]: for $JFMT_WRAPPER: starting to process author_handle.json files under: $AUTHOR_DIR" 1>&2
+fi
+find "$AUTHOR_DIR" -mindepth 1 -maxdepth 1 -type f -name '*.json' 2>/dev/null |
+  LC_ALL=C sort -d -u > "$TMP_AUTHOR_HANDLE_INVENTORY"
+while read -r AUTHOR_HANDLE_JSON; do
+
+    # canonically format author/author_handle.json unless -n
+    #
+    if [[ -z $NOOP ]]; then
+	if [[ $V_FLAG -ge 1 ]]; then
+	    echo "$0: debug[1]: about to run: $JFMT_WRAPPER ${TOOL_OPTION[*]} -- $AUTHOR_HANDLE_JSON" 1>&2
+	fi
+	"$JFMT_WRAPPER" "${TOOL_OPTION[@]}" -- "$AUTHOR_HANDLE_JSON"
+	status="$?"
+	if [[ $status -ne 0 ]]; then
+	    echo "$0: ERROR: tool: $JFMT_WRAPPER ${TOOL_OPTION[*]} -- $AUTHOR_HANDLE_JSON failed, error: $status" 1>&2
+	    EXIT_CODE="1"  # exit 1
+	    echo "$0: Warning: EXIT_CODE set to: $EXIT_CODE" 1>&2
+	    continue
+	fi
+
+    # report disabled by -n
+    #
+    elif [[ $V_FLAG -ge 5 ]]; then
+	echo "$0: debug[5]: because of -n, did not run: $JFMT_WRAPPER ${TOOL_OPTION[*]} -- $AUTHOR_HANDLE_JSON" 1>&2
+    fi
+done < "$TMP_AUTHOR_HANDLE_INVENTORY"
+
+
+# All Done!!! All Done!!! -- Jessica Noll, Age 2
+#
+if [[ $EXIT_CODE -ne 0 ]]; then
+    echo "$0: Warning: about to exit non-zero: $EXIT_CODE" 1>&2
+elif [[ $V_FLAG -ge 1 ]]; then
+    echo "$0: debug[1]: about to exit $EXIT_CODE" 1>&2
+fi
+exit "$EXIT_CODE"