open-standards/scripts/check-comparative-prose.sh

#!/usr/bin/env bash
#
# check-comparative-prose.sh
#
# Holds WAI's public text to its writing rule: it states what WAI does,
# plainly, and does not rank WAI against anything else. The phrases below are
# the comparative and promotional forms the tree has had to remove; each is a
# POSIX extended regular expression, matched case-sensitively.
#
# Scope: the same files as scripts/check-public-names.sh — the tracked files
# under wai/ with the extensions .md .rs .toml .py .sh .mjs .js .json .html
# .css .ttl .h .c .txt and wai/'s .gitignore files, except wai/CHANGELOG.md and its entries
# waiting under wai/changes/ (scripts/changelog-assemble.py): its history is a record, and only names are redacted from it. Files given as arguments replace that
# list (the self-test, scripts/test-public-text-checks.sh, uses this).
#
# Opt-out, for a functional identifier or a quotation only (an environment
# variable or file name that contains a listed word, a phrase quoted from a
# cited document): put `allow-phrase: <reason>` on the same line, in a comment
# of the file's own syntax. The reason is required: it must contain a letter or
# a digit.
#
# Exit status: 0 clean; 1 a hit; 2 a pattern grep cannot compile, or any other
# grep error. The check never reads an error as "clean".

set -euo pipefail

REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
cd "$REPO_ROOT"

PHRASES=(
  '\bSOTA\b'
  '\bwin vs\b'
  '\b[Mm]oat\b'
  '[Nn]obody signs'
  '[Nn]ot one signs'
  '[Nn]one signs'
  '[Bb]est[- ]in[- ]class'
  '\b[Bb]eats\b [A-Z]'
  '\b[Ss]uperior(ity)?\b'
  '% better'
  '\b[Tt]he opposite\b'
  '[Ss]trictly worse'
  '[Tt]oll[- ]road'
  '\b[Pp]arity \+'
  '[Ff]eature[- ]parity'
  '\bparity with\b'
  '\b[Uu]nderperforms\b'
  '\b[Oo]utperforms\b'
  'royalty trap'
  'well below [A-Z]'
  'well above [A-Z]'
  'among the (lowest|best|highest|fastest|smallest)'
  'nothing else .* offers?'
  '\b[Nn]o other .* (offers?|signs?|provides?)'
  '[Cc]ommercial wedge'
  '\b[Uu]nclaimed\b'
  '\b[Ff]ast win\b'
  '\b[Dd]ifferentiator\b'
  '[Rr]ate-competitive'
)

args=()
for p in "${PHRASES[@]}"; do args+=(-e "$p"); done
# Compile every phrase once before scanning: grep exits 1 when nothing matches
# and 2 on an error, and only 0 and 1 mean the list is usable.
set +e
grep -E "${args[@]}" /dev/null >/dev/null
rc=$?
set -e
if [ $rc -gt 1 ]; then
  echo "::error::a phrase in $0 does not compile (grep exit $rc); nothing was checked" >&2
  exit 2
fi

files=()
if [ $# -gt 0 ]; then
  files=("$@")
else
  while IFS= read -r f; do
    case "$f" in
      wai/CHANGELOG.md|wai/changes/[0-9]*.md) continue ;;
    esac
    files+=("$f")
  done < <(git ls-files 'wai/*.md' 'wai/*.rs' 'wai/*.toml' 'wai/*.py' 'wai/*.sh' 'wai/*.mjs' 'wai/*.js' \
                        'wai/*.json' 'wai/*.html' 'wai/*.css' 'wai/*.ttl' 'wai/*.h' 'wai/*.c' 'wai/*.txt' \
                        'wai/*.gitignore')
fi
if [ ${#files[@]} -eq 0 ]; then
  echo "::error::no file to check" >&2
  exit 2
fi

out="$(mktemp)"
trap 'rm -f "$out"' EXIT
set +e
grep -HnE "${args[@]}" -- "${files[@]}" > "$out"
rc=$?
set -e
if [ $rc -gt 1 ]; then
  echo "::error::grep failed (exit $rc) while scanning; nothing was checked" >&2
  exit 2
fi

hits=0
while IFS= read -r line; do
  content="${line#*:}"
  content="${content#*:}"
  if printf '%s' "$content" | grep -qE 'allow-phrase:[[:space:]]*[[:alnum:]]'; then
    continue
  fi
  if [ $hits -eq 0 ]; then
    echo "::error::comparative or promotional phrasing in public text (scripts/check-comparative-prose.sh)"
  fi
  echo "$line"
  hits=$((hits + 1))
done < "$out"

if [ $hits -gt 0 ]; then
  echo "Fix: state what WAI does, measured where a figure is given, without ranking it against"
  echo "anything else; for an identifier or a quotation, mark the line with allow-phrase: <reason>."
  exit 1
fi
echo "comparative-prose check: clean (${#files[@]} files)"