#!/usr/bin/env python3
"""
diff-check.py — Post-revision quality checker for revision-guard.
Compares original text against revised text and flags homogenization signals.
Usage:
python scripts/diff-check.py original.txt revised.txt
python scripts/diff-check.py --mode substantive original.txt revised.txt
python scripts/diff-check.py --mode rewrite original.txt revised.txt
python scripts/diff-check.py --text "original" "revised"
python scripts/diff-check.py --json original.tex revised.tex
Modes (match the edit type from SKILL.md Step 1):
edit (default) Language, structural, and formatting edits.
substantive Substantive edits: added material is expected, so word
count growth is reported but not flagged.
rewrite Full rewrites, where nearly every word changes by design.
Flags the revised text only where it is both weak in
absolute terms and worse than the original.
Checks:
1. Word count growth (>15% = likely filler; edit mode only)
2. First-person pronouns (dropped to zero, or down by 2+ and 25%+)
3. Specific numbers (a number from the original is missing = generalization)
4. Hedges (2+ more, at a higher density per 100 words)
5. Sentence length spread (much more uniform, and uniform in absolute terms)
6. Stock transitions ("Moreover," "Furthermore," ... opening sentences)
7. Summary closers ("This suggests..." ending a paragraph)
Two or more flags = homogenization warning. Files ending in .tex have LaTeX
comments and \\cite/\\ref commands removed before analysis.
"""
import sys
import re
import json
import argparse
import statistics
from decimal import Decimal, InvalidOperation
from pathlib import Path
# --- Text preparation -------------------------------------------------------
# Abbreviations that never end a sentence, and ones that sometimes do.
ABBREVIATIONS = (
'e.g.', 'i.e.', 'cf.', 'vs.', 'approx.', 's.e.', 'S.E.', 'Fig.', 'Figs.',
'Eq.', 'Eqs.', 'Tab.', 'Sec.', 'Ch.', 'App.', 'No.', 'pp.', 'Dr.', 'Mr.',
'Ms.', 'Mrs.', 'Prof.', 'Jan.', 'Feb.', 'Aug.', 'Sept.', 'Oct.', 'Nov.', 'Dec.',
)
SENTENCE_END_ABBREVIATIONS = ('et al.', 'etc.', 'resp.', 'U.S.', 'U.K.', 'Inc.', 'Ltd.', 'Co.')
SENTENCE_STARTER = re.compile(
r'^["\'\u201c\u2018(]?(?:The|This|These|That|Those|There|Here|It|We|I|Our|My|'
r'In|On|At|For|From|With|By|As|A|An|But|And|Yet|So|Thus|Hence|However|'
r'Moreover|Furthermore|Additionally|Overall|Such|Taken|Together|Finally|'
r'First|Second|Third|Notably|Importantly|Indeed|Instead|Because|Since|'
r'When|While|If|Although|Using)\b'
)
# A capital letter after these is a label ("Panel A."), not a person's initial.
LETTER_LABELS = {
'Panel', 'Appendix', 'Table', 'Figure', 'Column', 'Section', 'Part', 'Model',
'Plan', 'Exhibit', 'Group', 'Sample', 'Period', 'Region', 'Scenario', 'Option',
'Treatment', 'Arm', 'Case', 'Type', 'Class', 'Tier', 'Study', 'Wave', 'Phase',
'Stage', 'Step', 'Hypothesis', 'Specification', 'Grade',
}
SENTENCE_BOUNDARY = re.compile(
r'(?<=[.!?])["\'\u201d\u2019)\]]*\s+(?=["\'\u201c\u2018(\[]?[A-Z0-9$\\])'
)
def strip_latex(text: str) -> str:
# % starts a comment unless escaped by an odd number of backslashes
text = re.sub(r'(?m)(^|[^\\])((?:\\\\)*)%.*$', r'\1\2', text)
text = re.sub(r'\\(?:[a-zA-Z]*cite[a-zA-Z]*|[cC]?ref|eqref|autoref|pageref|label)\*?'
r'(?:\[[^\]]*\])*\{[^}]*\}', '', text)
return text.replace('\\%', '%').replace('~', ' ')
def paragraphs(text: str) -> list:
blocks = re.split(r'\n\s*\n', text)
return [re.sub(r'\s+', ' ', b).strip() for b in blocks if b.strip()]
def ends_with(sentence: str, abbreviations) -> bool:
s = sentence.rstrip()
return any(s.endswith(a) and (len(s) == len(a) or not s[-len(a) - 1].isalpha())
for a in abbreviations)
def continues_sentence(previous: str, following: str) -> bool:
"""True if a split after `previous` fell on an abbreviation, not a sentence end."""
previous = previous.rstrip()
if re.fullmatch(r'\(?\d{1,2}[.)]', previous): # list marker: "1."
return True
if ends_with(previous, ABBREVIATIONS):
return True
initial = re.search(r'(?:^|\s)(?:(\w+)\s+)?[A-Z]\.$', previous) # "Joel Z. Leibo"
if initial and initial.group(1) in LETTER_LABELS:
return False # "Panel A."
if initial or ends_with(previous, SENTENCE_END_ABBREVIATIONS):
return not SENTENCE_STARTER.match(following)
return False
def split_sentences(paragraph: str) -> list:
sentences = []
for part in SENTENCE_BOUNDARY.split(paragraph.strip()):
if sentences and continues_sentence(sentences[-1], part):
sentences[-1] += ' ' + part
else:
sentences.append(part)
return [s for s in sentences if s.strip()]
def all_sentences(text: str) -> list:
return [s for p in paragraphs(text) for s in split_sentences(p)]
def count_words(text: str) -> int:
return len(text.split())
# --- Signals ----------------------------------------------------------------
FIRST_PERSON = re.compile(r'\b(?:I|[Mm]e|[Mm]y|[Mm]ine|[Ww]e|us|[Oo]ur|[Oo]urs)\b')
MATH = re.compile(r'\$\$.*?\$\$|\$[^$\n]*\$|\\\(.*?\\\)|\\\[.*?\\\]', re.S)
ROMAN_LABELS = {
'Type', 'Table', 'Column', 'Panel', 'Figure', 'Model', 'Phase', 'Stage',
'Part', 'Chapter', 'Section', 'Appendix', 'Study', 'Experiment', 'Wave',
'Step', 'Tier', 'Class', 'Title', 'War', 'Specification', 'Hypothesis',
}
ROMAN_FOLLOWERS = {'error', 'errors', 'and', 'or', 'to', 'through', 'vs', 'versus'}
def is_roman_numeral(text: str, start: int, end: int) -> bool:
"""'Type I error', 'Table I', 'type I and type II', '(I)' -- not the pronoun."""
if text[end:end + 1] == ')':
return True
before = re.search(r'(\w+)\W*$', text[:start])
previous = before.group(1) if before else ''
if previous in ROMAN_LABELS:
return True
after = re.match(r'(\s*)(\w*)', text[end:])
if previous.lower() in {w.lower() for w in ROMAN_LABELS}:
# lowercase label: "type I error" yes, "this section I estimate" no
return not after.group(1) or after.group(2).lower() in ROMAN_FOLLOWERS
return False
def count_first_person(text: str) -> int:
text = MATH.sub(' ', text)
return sum(1 for m in FIRST_PERSON.finditer(text)
if m.group() != 'I' or not is_roman_numeral(text, m.start(), m.end()))
NUMBER = re.compile(
r'(?<![\w.])[-\u2212]?(?:\d{1,3}(?:,\d{3})+(?:\.\d+)?|\d+(?:\.\d+)?|\.\d+)'
r'(?:[eE][-+\u2212]?\d+)?'
)
# Numbers that label things rather than report them: "Table 2",
# "Columns (1)-(3)", "Tables 2 and 3", "Appendix B4", "pp. 12-15", "R^2",
# "x_{it}", "(3)", and list markers.
_REF = r'[(\[]?[A-Z]?\d+[a-z]?[)\]]?'
LABEL_REFERENCE = re.compile(
r'\b(?:(?i:tables?|columns?|cols?\.|figures?|figs?\.|panels?|sections?|secs?\.|'
r'chapters?|ch\.|appendix|appendices|app\.|equations?|eqs?\.|footnotes?|'
r'specifications?)|Models?|Hypothes[ie]s|Steps?|Rounds?|Waves?|Stud(?:y|ies)|'
r'Experiments?|Notes?|Pages?|pp?\.)\s*' + _REF +
r'(?:\s*(?:,|and|&|or|to|through|-|\u2013)\s*' + _REF + r')*'
)
NOT_DATA = re.compile(
r'\d*[\^_]\{[^}]*\}|\d*[\^_][-\u2212]?\d+' # powers and subscripts: R^2, 10^{-3}
r'|\(\d{1,2}\)' # enumerators: (1), (3)
r'|^\s*\d{1,2}[.)](?=\s)' # list markers at line start
r'|(?<=[.!?:]\s)\d{1,2}[.)](?=\s)', # ...and after a sentence
re.M,
)
def extract_numbers(text: str) -> set:
"""Specific values in the text, ignoring labels like 'Table 2'."""
text = NOT_DATA.sub(' ', LABEL_REFERENCE.sub(' ', text))
found = set()
for m in NUMBER.finditer(text):
raw = m.group().replace(',', '').replace('\u2212', '-').rstrip('.')
try:
found.add(format(Decimal(raw).normalize(), 'f')) # '40', not '4E+1'
except InvalidOperation:
continue
return found
HEDGES = [
r'\bmight\b', r'\bcould\b', r'\bperhaps\b', r'\bpossibly\b',
r'\bpotentially\b', r'\bappear(?:s|ed)?\b(?!\s+in\b)', r'\bseems?\b',
r'(?<!\)\s)\bsuggests?\b', r'\bapproximately\b', r'\bbroadly\b',
r'\bgenerally\b', r'\btends?\b', r'\bsomewhat\b', r'\brelatively\b',
r'\barguably\b', r'\bto some extent\b',
r'\bcannot be (?:entirely |fully )?ruled out\b',
r'\bit is worth noting\b', r'\bit is important to\b',
]
def count_hedge_words(text: str) -> int:
modal_may = len(re.findall(r'\bmay\b', text)) # lowercase only: not the month
return modal_may + sum(len(re.findall(h, text, re.IGNORECASE)) for h in HEDGES)
def per_100_words(count: int, words: int) -> float:
return count / words * 100 if words else 0.0
def length_spread(sentences: list):
"""Coefficient of variation of sentence length; None if under 3 sentences."""
lengths = [count_words(s) for s in sentences]
if len(lengths) < 3 or statistics.mean(lengths) == 0:
return None
return statistics.pstdev(lengths) / statistics.mean(lengths)
STOCK_OPENER = re.compile(
r'^["\'\u201c\u2018(]?(?:Moreover|Furthermore|Additionally|In addition|Notably|'
r'Importantly|Crucially|Overall|Ultimately)\b'
)
SUMMARY_CLOSER = re.compile(
r'^["\'\u201c\u2018(]?(?:This|These|Such|Together|Taken together|Overall|In sum|'
r'In short|Collectively|Ultimately)\b[^.]{0,60}?\b(?:suggests?|indicates?|'
r'underscores?|highlights?|demonstrates?|illustrates?|shows?|reveals?|'
r'points? to|speaks? to|reflects?|emphasi[sz]es?|confirms?|impl(?:y|ies)|'
r'signals?|attests? to)\b'
)
REPORTS_RESULT = re.compile(r'\d|\b(?:Table|Figure|Column|Panel)\b')
def count_stock_openers(sentences: list) -> int:
return sum(1 for s in sentences if STOCK_OPENER.match(s))
def summary_closers(text: str):
"""(paragraphs ending in a summary closer, paragraphs with 2+ sentences)."""
eligible = closers = 0
for p in paragraphs(text):
sentences = split_sentences(p)
if len(sentences) < 2:
continue
eligible += 1
last = sentences[-1]
if SUMMARY_CLOSER.match(last) and not REPORTS_RESULT.search(last):
closers += 1
return closers, eligible
# --- Analysis ---------------------------------------------------------------
def analyze(original: str, revised: str, mode: str = 'edit') -> dict:
rewrite = mode == 'rewrite'
results = {}
orig_sents, rev_sents = all_sentences(original), all_sentences(revised)
# 1. Word count
orig_wc, rev_wc = count_words(original), count_words(revised)
wc_change = (rev_wc - orig_wc) / orig_wc * 100 if orig_wc > 0 else 0
note = ''
if mode != 'edit':
note = f' (reported only in {mode} mode)'
elif wc_change > 15:
note = ' — likely filler added'
elif wc_change < -15:
note = ' — shorter; check that nothing substantive was cut'
results['word_count'] = {
'original': orig_wc,
'revised': rev_wc,
'change_pct': round(wc_change, 1),
'checked': mode == 'edit',
'flag': mode == 'edit' and wc_change > 15,
'message': f"Word count changed {wc_change:+.1f}%" + note,
}
# 2. First-person pronouns
orig_fp, rev_fp = count_first_person(original), count_first_person(revised)
if rewrite:
fp_flag = orig_fp > 0 and rev_fp == 0
else:
fp_flag = orig_fp > 0 and (rev_fp == 0 or
(orig_fp - rev_fp >= 2 and rev_fp <= 0.75 * orig_fp))
results['first_person'] = {
'original': orig_fp,
'revised': rev_fp,
'flag': fp_flag,
'message': f"First-person pronouns: {orig_fp} → {rev_fp}"
+ (" — voice may be erased" if fp_flag else ""),
}
# 3. Specific numbers
orig_nums, rev_nums = extract_numbers(original), extract_numbers(revised)
lost = sorted(orig_nums - rev_nums, key=lambda n: (len(n), n))
results['numbers'] = {
'original': len(orig_nums),
'revised': len(rev_nums),
'lost': lost,
'flag': bool(lost),
'message': f"Specific numbers: {len(orig_nums)} → {len(rev_nums)}"
+ (f" — missing from revision: {', '.join(lost[:5])}" if lost else ""),
}
# 4. Hedges
orig_h, rev_h = count_hedge_words(original), count_hedge_words(revised)
orig_d, rev_d = per_100_words(orig_h, orig_wc), per_100_words(rev_h, rev_wc)
if rewrite:
hedge_flag = rev_d >= 3.0 and rev_d > orig_d
else:
hedge_flag = rev_h - orig_h >= 2 and rev_d > orig_d
results['hedge_words'] = {
'original': orig_h,
'revised': rev_h,
'density_original': round(orig_d, 2),
'density_revised': round(rev_d, 2),
'flag': hedge_flag,
'message': f"Hedge words: {orig_h} → {rev_h} "
f"({orig_d:.1f} → {rev_d:.1f} per 100 words)"
+ (" — confidence may be eroded" if hedge_flag else ""),
}
# 5. Sentence length spread
orig_cv, rev_cv = length_spread(orig_sents), length_spread(rev_sents)
if rev_cv is None:
spread_flag = False
elif rewrite:
spread_flag = (len(rev_sents) >= 4 and rev_cv < 0.25
and (orig_cv is None or rev_cv < orig_cv))
else:
spread_flag = orig_cv is not None and rev_cv < 0.6 * orig_cv and rev_cv < 0.3
fmt = lambda v: 'n/a' if v is None else f"{v:.2f}"
results['sentence_variance'] = {
'original': None if orig_cv is None else round(orig_cv, 2),
'revised': None if rev_cv is None else round(rev_cv, 2),
'flag': spread_flag,
'message': f"Sentence length spread (CV): {fmt(orig_cv)} → {fmt(rev_cv)}"
+ (" — sentences becoming uniform" if spread_flag else ""),
}
# 6. Stock transitions
orig_t, rev_t = count_stock_openers(orig_sents), count_stock_openers(rev_sents)
orig_ts = orig_t / len(orig_sents) if orig_sents else 0.0
rev_ts = rev_t / len(rev_sents) if rev_sents else 0.0
if rewrite:
trans_flag = len(rev_sents) >= 4 and rev_ts >= 0.3 and rev_ts > orig_ts
else:
trans_flag = rev_t > orig_t and rev_ts - orig_ts >= 0.1 - 1e-9
results['transitions'] = {
'original': orig_t,
'revised': rev_t,
'flag': trans_flag,
'message': f"Sentences opening with stock transitions: {orig_t} → {rev_t}"
+ (" — mechanical rhythm" if trans_flag else ""),
}
# 7. Summary closers
(orig_c, _), (rev_c, rev_elig) = summary_closers(original), summary_closers(revised)
if rewrite:
closer_flag = rev_elig >= 2 and rev_c / rev_elig >= 0.5 and rev_c > orig_c
else:
closer_flag = rev_c > orig_c
results['summary_closers'] = {
'original': orig_c,
'revised': rev_c,
'flag': closer_flag,
'message': f"Paragraphs ending in a summary closer: {orig_c} → {rev_c}"
+ (" — template paragraphs" if closer_flag else ""),
}
flags = sum(1 for r in results.values() if r['flag'])
results['summary'] = {
'mode': mode,
'flags_triggered': flags,
'total_checks': 7 if mode == 'edit' else 6,
'homogenization_warning': flags >= 2,
'verdict': "HOMOGENIZATION WARNING" if flags >= 2
else "MINOR CONCERNS" if flags == 1
else "CLEAN",
}
return results
# --- CLI --------------------------------------------------------------------
def load_text(path: str) -> str:
p = Path(path)
try:
return p.read_text(encoding='utf-8')
except UnicodeDecodeError:
return p.read_text(encoding='utf-8', errors='replace')
def main():
parser = argparse.ArgumentParser(
description="Check for homogenization signals between original and revised text."
)
parser.add_argument('--text', nargs=2, metavar=('ORIGINAL', 'REVISED'),
help='Pass original and revised text directly as arguments')
parser.add_argument('--mode', choices=['edit', 'substantive', 'rewrite'], default='edit',
help="match the edit type: edit (default), substantive, rewrite")
parser.add_argument('--latex', action='store_true',
help='Strip LaTeX comments and citation/reference commands')
parser.add_argument('--json', action='store_true', help='Print results as JSON')
parser.add_argument('files', nargs='*',
help='Two file paths: original.txt revised.txt')
args = parser.parse_args()
if args.text and args.files:
parser.error("give either --text or two files, not both")
if args.text:
original, revised = args.text
elif len(args.files) == 2:
try:
original, revised = load_text(args.files[0]), load_text(args.files[1])
except OSError as e:
parser.error(str(e))
else:
parser.error("give two files (original.txt revised.txt) or --text 'original' 'revised'")
if args.latex or any(Path(f).suffix.lower() == '.tex' for f in args.files):
original, revised = strip_latex(original), strip_latex(revised)
results = analyze(original, revised, args.mode)
if args.json:
print(json.dumps(results, ensure_ascii=False, indent=2))
return
summary = results['summary']
print(f"\n=== Revision Guard: Diff Check ({summary['mode']} mode) ===\n")
for key, value in results.items():
if key == 'summary':
continue
marker = '[--]' if not value.get('checked', True) else '[!!]' if value['flag'] else '[ok]'
print(f" {marker} {value['message']}")
print(f"\n {'[!!]' if summary['homogenization_warning'] else '[ok]'} "
f"Verdict: {summary['verdict']} "
f"({summary['flags_triggered']}/{summary['total_checks']} checks flagged)")
print()
if __name__ == '__main__':
if hasattr(sys.stdout, 'reconfigure'):
sys.stdout.reconfigure(encoding='utf-8', errors='replace')
main()