@thebassclef/lite 0.1.3 → 1.0.1

package/substrate/lib/rewrite-check.sh

@@ -1,214 +0,0 @@
-#!/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
-}