@thebassclef/lite 0.0.1 → 0.1.2

package/substrate/lib/rewrite-check.sh

@@ -0,0 +1,214 @@
+#!/bin/bash
+# tier: lite
+# rewrite-check.sh — six heuristic checks for /kiss REWRITE mode (goal 25d Step 5).
+#
+# Grounded in four public sources:
+#   - UK ONS Style Guide — Plain English section
+#   - Nielsen Norman Group — Plain Language for Experts (2018)
+#   - US Federal Plain Language Guidelines (plainlanguage.gov)
+#   - Hemingway Editor heuristics (public rules — passive, adverbs, long sentences)
+#
+# The six checks are HEURISTIC not perfect NLP. They surface CANDIDATES for
+# human review. Not a gate. Not a blocking check. Exit 0 always.
+#
+# Sister to lib/output-discipline.sh (classifier for /kiss dispatch presence)
+# and lib/code-comment-discipline.sh (classifier for header comment jargon).
+# Same Ousterhout deep-module shape — small interface, shared implementation.
+#
+# Per bassclef-upstream#859 Iteration D + goal 25d Step 5.
+# Bash 3.2+ compatible.
+#
+# Usage — sourced by /kiss words --rewrite mode:
+#   source lib/rewrite-check.sh
+#   check_passive_voice <file>       # prints lines with passive-voice patterns
+#   check_hyphen_words <file>        # prints hyphenated compound words flagged
+#   check_sentence_length <file> [N] # prints sentences over N words (default 25)
+#   check_svo <file>                 # prints sentences NOT starting with subject
+#   check_noun_stack <file>          # prints 3+ noun runs without verb
+#   check_adverb_density <file>      # prints density note if >5% -ly adverbs
+#   run_rewrite_checks <file>        # runs all six; prints findings table
+
+set -o pipefail
+
+# === Standard tech hyphens allow-list ===
+# Common tech compound words that should NOT be flagged as jargon.
+# Grep-alternation shape (pipe-separated).
+REWRITE_TECH_HYPHENS='pre-commit|pre-push|post-commit|post-push|real-time|data-driven|end-to-end|non-blocking|read-only|copy-on-write|test-driven|type-safe|open-source|self-hosted|cross-platform|multi-tenant|single-tenant|full-stack|front-end|back-end|no-op|no-code|low-code|check-in|check-out|log-in|log-out|sign-in|sign-out|drop-down|pop-up|pull-request|merge-request|feature-branch|main-branch|no-fast-forward|off-the-shelf|out-of-the-box'
+
+# === Passive voice check ===
+# Pattern per Hemingway Editor: "to be" + past participle + optional "by".
+# Common shapes:
+#   was <verb-ed> by
+#   were <verb-ed> by
+#   has been <verb-ed>
+#   have been <verb-ed>
+#   had been <verb-ed>
+#   is being <verb-ed>
+#   was <verb-ed>
+# Returns matching lines. Exit 0 always.
+check_passive_voice() {
+  local file="$1"
+  [ -f "$file" ] || return 0
+  grep -niE '\b(was|were|has been|have been|had been|is being|are being|will be) [a-z]+(ed|en) (by|to)\b|\b(was|were|has been|have been|had been) [a-z]+(ed|en)\b' "$file" 2>/dev/null
+  return 0
+}
+
+# === Hyphen-word check ===
+# Flag hyphenated compounds that are NOT in the standard tech allow-list.
+# Per operator-facing-prose.md — hyphen words like X-side, N-layer X, X-as-Y
+# should be rewritten to plain description.
+check_hyphen_words() {
+  local file="$1"
+  [ -f "$file" ] || return 0
+  # Extract hyphenated words (letters-letters); filter to those NOT in the allow-list
+  # AND that look like adjective compounds (letters-letters where both parts are 2+ chars).
+  grep -oE '\b[a-z]{2,}-[a-z]{2,}\b' "$file" 2>/dev/null \
+    | sort -u \
+    | grep -vwE "$REWRITE_TECH_HYPHENS" \
+    | head -20
+  return 0
+}
+
+# === Sentence length check ===
+# Flag sentences over N words (default 25 per Hemingway + Federal Plain
+# Language recommendation). Very-long sentences (>30) get the strong flag.
+check_sentence_length() {
+  local file="$1"
+  local ceiling="${2:-25}"
+  [ -f "$file" ] || return 0
+  # Split on sentence-ending punctuation, count words per sentence.
+  # awk splits, counts words, flags any over ceiling.
+  awk -v CEIL="$ceiling" '
+    BEGIN { RS = "[.!?][[:space:]]+" }
+    {
+      # Count words (whitespace-separated tokens)
+      n = split($0, words, /[[:space:]]+/)
+      if (n > CEIL) {
+        # Trim + print first 60 chars for context
+        sample = substr($0, 1, 60)
+        gsub(/\n/, " ", sample)
+        printf "SENTENCE: %d words — %s...\n", n, sample
+      }
+    }
+  ' "$file" 2>/dev/null
+  return 0
+}
+
+# === SVO check ===
+# Heuristic: flag sentences that START with a preposition or subordinating
+# conjunction rather than a subject. Common non-SVO openers:
+#   Because, Although, While, When, If, Since, Unless, Whereas, After, Before
+#   In X, On X, At X, With X, Under X, Without X, Despite X, Given X
+# This catches the most common non-SVO shapes. False positives happen on
+# legitimate variety; the check surfaces candidates for review.
+check_svo() {
+  local file="$1"
+  [ -f "$file" ] || return 0
+  # Grep for lines starting with (after optional whitespace/quote) a non-SVO opener.
+  grep -niE '^[[:space:]]*(Because|Although|While|When|If|Since|Unless|Whereas|After|Before|In [A-Z]|On [A-Z]|At [A-Z]|With [A-Z]|Under [A-Z]|Without [A-Z]|Despite|Given)\b' "$file" 2>/dev/null
+  return 0
+}
+
+# === Noun-stack check ===
+# Per operator-facing-prose.md: no more than 2 nouns in a row without a verb.
+# Heuristic: look for 3+ consecutive words that end in common noun suffixes
+# OR that are capitalized (proper nouns). Approximate.
+#
+# The heuristic flags runs of 3+ words that look like nouns (no verb-form
+# suffix like -ed, -ing, -es, -s at verb pattern). Bash regex is limited;
+# we use a simple approximation:
+#   - 3+ consecutive words each 4+ chars long
+#   - none ending in -ed, -ing, -ly, -s (verb / adverb / plural marker)
+#   - separated by single space (not by "the", "a", "an", "and", "or", "of")
+# Approximation: words separated only by spaces (no articles/verbs between).
+check_noun_stack() {
+  local file="$1"
+  [ -f "$file" ] || return 0
+  # Simple heuristic: match "word word word word" with no small connector.
+  # Look for runs of 4+ non-tiny words in a row.
+  awk '
+    {
+      # Split into words, find runs of 3+ nouny-looking tokens
+      n = split($0, w, /[[:space:]]+/)
+      run = 0
+      run_words = ""
+      for (i = 1; i <= n; i++) {
+        word = w[i]
+        # Strip punctuation for the check
+        clean = word
+        gsub(/[^A-Za-z]/, "", clean)
+        # Nouny heuristic: 4+ chars, not a verb/adverb marker, not a small word
+        if (length(clean) >= 4 \
+            && clean !~ /^(the|and|for|with|from|that|this|when|where|which|been|were|have|will|would|could|should|about|because|through|these|those)$/ \
+            && clean !~ /(ing|ed|ly)$/) {
+          run++
+          run_words = run_words " " clean
+        } else {
+          if (run >= 3) {
+            printf "NOUN-STACK: %d nouns —%s\n", run, run_words
+          }
+          run = 0
+          run_words = ""
+        }
+      }
+      if (run >= 3) {
+        printf "NOUN-STACK: %d nouns —%s\n", run, run_words
+      }
+    }
+  ' "$file" 2>/dev/null
+  return 0
+}
+
+# === Adverb density check ===
+# Per Hemingway Editor: -ly adverbs above 1 per 20 words signal weak verbs.
+# Federal Plain Language: prefer strong verbs over adverbs.
+# Threshold: >5% (equivalent to 1 per 20 words).
+check_adverb_density() {
+  local file="$1"
+  [ -f "$file" ] || return 0
+  local total_words adverb_count percent
+  # Count total words
+  total_words=$(tr -s '[:space:]' '\n' < "$file" | grep -cE '^[A-Za-z]+' 2>/dev/null || echo 0)
+  # Count -ly adverbs (word ending -ly, excluding common -ly words that aren't adverbs)
+  adverb_count=$(grep -oiE '\b[a-z]{3,}ly\b' "$file" 2>/dev/null \
+    | grep -viwE 'only|early|ally|belly|silly|fully|jolly|holy|really|apply|comply|imply|reply|supply|family|reply' \
+    | wc -l | tr -d ' ')
+  if [ "$total_words" -eq 0 ]; then
+    return 0
+  fi
+  # Compute percent (integer math * 1000 for one decimal)
+  percent=$((adverb_count * 1000 / total_words))
+  # Threshold: 50 = 5.0%
+  if [ "$percent" -gt 50 ]; then
+    printf "ADVERB density: %d/%d words = %d.%d%%\n" \
+      "$adverb_count" "$total_words" "$((percent / 10))" "$((percent % 10))"
+  fi
+  return 0
+}
+
+# === Composite check ===
+# Runs all six checks against a file. Prints a findings table.
+# Exit 0 always (informational, not a gate).
+run_rewrite_checks() {
+  local file="$1"
+  [ -f "$file" ] || return 0
+  local passive hyphens length svo nouns adverbs
+  passive=$(check_passive_voice "$file")
+  hyphens=$(check_hyphen_words "$file")
+  length=$(check_sentence_length "$file")
+  svo=$(check_svo "$file")
+  nouns=$(check_noun_stack "$file")
+  adverbs=$(check_adverb_density "$file")
+
+  echo "=== REWRITE check findings: $file ==="
+  [ -n "$passive" ] && { echo "-- passive voice --"; echo "$passive"; }
+  [ -n "$hyphens" ] && { echo "-- hyphen compounds --"; echo "$hyphens"; }
+  [ -n "$length"  ] && { echo "-- long sentences --"; echo "$length"; }
+  [ -n "$svo"     ] && { echo "-- non-SVO openers --"; echo "$svo"; }
+  [ -n "$nouns"   ] && { echo "-- noun stacks --"; echo "$nouns"; }
+  [ -n "$adverbs" ] && { echo "-- adverb density --"; echo "$adverbs"; }
+  if [ -z "$passive$hyphens$length$svo$nouns$adverbs" ]; then
+    echo "CLEAN — no rewrite findings"
+  fi
+  return 0
+}