#!/usr/bin/env python3 """Deterministic style checks for application text: CV, cover letter, form answer, post. Stdlib only, so it runs in any Python sandbox. Reads Markdown or plain text (a file or stdin) and .docx. Prints Markdown tables: findings, counts per section and, for a CV, bullets per role. Exit status 1 when an error-level finding exists, else 0. Severity "error" means a rule is broken. Severity "check" is a heuristic hint (spelling, Oxford comma, page estimate, layout) for a human or the model to confirm. Usage: python3 check_text.py draft.md python3 check_text.py cv.docx --kind cv python3 check_text.py answers.md --kind form --limit "Why us=1500" --word-limit "Motivation=200" cat letter.txt | python3 check_text.py - --kind letter """ import argparse import math import re import sys import unicodedata import zipfile import xml.etree.ElementTree as ET from dataclasses import dataclass, field from pathlib import Path HERE = Path(__file__).resolve().parent EM_DASH = "\u2014" NON_ASCII_DASHES = "\u2010\u2011\u2012\u2013\u2014\u2015\u2212" YEAR = r"(?:19|20)\d{2}" MONTH = r"(?:[A-Za-z\u00c0-\u017f]{3,9}\.?[^\S\n]+)?" DATE_DASH = re.compile( rf"{YEAR}[^\S\n]*[{NON_ASCII_DASHES}]" rf"|[{NON_ASCII_DASHES}][^\S\n]*(?:{MONTH}{YEAR}|present\b|today\b|now\b|heute\b)", re.IGNORECASE, ) SPACED_EN_DASH = re.compile(r"(?<=\S)[^\S\n]+\u2013[^\S\n]+(?=\S)") DOUBLE_HYPHEN = re.compile(r"(?])") SPACED_HYPHEN = re.compile(r"(?<=[A-Za-z\u00c0-\u017f,.)])[^\S\n]+-[^\S\n]+(?=[A-Za-z\u00c0-\u017f(])") OXFORD = re.compile( r"\b([\w+#.]+(?: [\w+#.]+)?), ([\w+#.]+(?: [\w+#.]+)?) (and|or) ([\w+#.]+)", re.UNICODE ) EMAIL = re.compile(r"[\w.+-]+@[\w-]+(?:\.[\w-]+)+") PHONE = re.compile(r"(?:\+|\b0)\d[\d ()/.-]{6,}\d") MD_LINK = re.compile(r"\[([^\]]*)\]\(([^)]*)\)") ICON_RANGES = ( (0x2600, 0x27BF), # miscellaneous symbols and dingbats: phone, envelope, check marks (0x2B00, 0x2BFF), # arrows and symbols (0xE000, 0xF8FF), # private use area: icon fonts (0x1F000, 0x1FAFF), # emoji and pictographs ) BULLET = re.compile(r"^(\s*)(?:[-*+\u2022\u00b7\u25aa\u25cf\u2023\u25e6]|\d{1,2}[.)])\s+(.*)$") EXPERIENCE = re.compile(r"experience|erfahrung|work history|employment", re.I) EARLIER = re.compile(r"earlier|previous|prior|other|additional|further|fr\u00fchere|weitere", re.I) SALUTATION = re.compile(r"^(dear|hello|hi|sehr geehrte|liebe|lieber|hallo|guten tag)\b", re.I) CLOSING = re.compile( r"^(kind regards|best regards|warm regards|regards|yours sincerely|yours faithfully" r"|sincerely|best wishes|mit freundlichen gr\u00fc\u00dfen|viele gr\u00fc\u00dfe" r"|beste gr\u00fc\u00dfe|freundliche gr\u00fc\u00dfe)\b", re.I, ) # American spellings with their British form. Stems take the usual endings. US_STEMS = ( "organiz", "optimiz", "prioritiz", "recogniz", "realiz", "specializ", "standardiz", "minimiz", "maximiz", "summariz", "utiliz", "characteriz", "customiz", "digitiz", "finaliz", "centraliz", "visualiz", "monetiz", "operationaliz", "productiz", "containeriz", "virtualiz", "synchroniz", "authoriz", "categoriz", "emphasiz", "normaliz", "parameteriz", "mobiliz", "stabiliz", "internationaliz", "localiz", "modulariz", "industrializ", "capitaliz", "analyz", "paralyz", ) US_STEM_RE = re.compile( r"\b(" + "|".join(US_STEMS) + r")(e|es|ed|ing|ation|ations|er|ers)\b", re.I ) US_WORDS = { "color": "colour", "colors": "colours", "colored": "coloured", "colorful": "colourful", "behavior": "behaviour", "behaviors": "behaviours", "behavioral": "behavioural", "favor": "favour", "favorite": "favourite", "favorable": "favourable", "honor": "honour", "honors": "honours", "labor": "labour", "neighbor": "neighbour", "center": "centre", "centers": "centres", "centered": "centred", "defense": "defence", "offense": "offence", "catalog": "catalogue", "dialog": "dialogue", "modeling": "modelling", "modeled": "modelled", "labeled": "labelled", "labeling": "labelling", "traveled": "travelled", "traveling": "travelling", "canceled": "cancelled", "canceling": "cancelling", "fueled": "fuelled", "enrollment": "enrolment", "fulfill": "fulfil", "fulfillment": "fulfilment", "gray": "grey", "mold": "mould", "skillful": "skilful", "aging": "ageing", } @dataclass class Line: no: int raw: str text: str # markup stripped kind: str # heading, bullet, text, blank level: int = 0 indent: int = 0 section: str = "" @dataclass class Block: label: str section: str in_experience: bool bullets: list = field(default_factory=list) # [line_no, text] @dataclass class Finding: severity: str where: str problem: str rule: str fix: str # ----------------------------------------------------------------------------- input W = "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}" def _para_text(p): parts = [] for el in p.iter(): if el.tag == W + "t": parts.append(el.text or "") elif el.tag == W + "tab": parts.append("\t") elif el.tag in (W + "br", W + "cr"): parts.append(" ") return "".join(parts) def read_docx(path): """Return (markdown-ish text, layout findings) for a .docx file.""" findings = [] with zipfile.ZipFile(path) as z: root = ET.fromstring(z.read("word/document.xml")) header_text = " ".join( _para_text(p) for name in z.namelist() if re.match(r"word/(header|footer)\d*\.xml$", name) for p in ET.fromstring(z.read(name)).iter(W + "p") ) body = root.find(W + "body") out = [] for p in body.iter(W + "p"): text = _para_text(p).strip() if not text: out.append("") continue ppr = p.find(W + "pPr") style = "" is_list = False if ppr is not None: ps = ppr.find(W + "pStyle") style = ps.get(W + "val", "") if ps is not None else "" is_list = ppr.find(W + "numPr") is not None m = re.match(r"(?i)(?:heading|berschrift|titre|kop)\s*(\d)", style) if m: out.append("#" * int(m.group(1)) + " " + text) elif style.lower() == "title": out.append("# " + text) elif is_list or "list" in style.lower(): out.append("- " + text) else: out.append(text) if body.find(".//" + W + "tbl") is not None: findings.append(Finding("check", "document", "table found", "Single column", "use tables only for real tabular data; layout tables can scramble ATS reading order")) if body.find(".//" + W + "txbxContent") is not None: findings.append(Finding("check", "document", "text box found", "Single column", "move text-box content into the body; many ATS skip text boxes")) for cols in body.iter(W + "cols"): if int(cols.get(W + "num", "1") or 1) > 1: findings.append(Finding("check", "document", "multi-column section", "Single column", "use a single column; columns interleave in extraction")) break text = "\n".join(out) for kind, pattern in (("email", EMAIL), ("phone", PHONE)): for m in pattern.finditer(header_text): if m.group(0) not in text: findings.append(Finding("error", "header/footer", f"{kind} {m.group(0)!r} only in the page header or footer", "Plain-text contact", "put it in the body text; many ATS ignore headers and footers")) return text, findings def strip_markup(s): s = MD_LINK.sub(r"\1", s) s = re.sub(r"(\*\*|__|`)", "", s) s = re.sub(r"(?= 3 and len(s) <= 60 and all(not c.islower() for c in letters) and len(s.split()) <= 6 and "," not in s and not s.rstrip().endswith((".", ";", ":")) and not EMAIL.search(s) ) def parse(text): lines = [] section = "(top)" for i, raw in enumerate(text.splitlines(), 1): stripped = raw.strip() if not stripped: lines.append(Line(i, raw, "", "blank", section=section)) continue m = re.match(r"^(#{1,6})\s+(.*?)\s*#*$", stripped) if m: section = strip_markup(m.group(2)) lines.append(Line(i, raw, section, "heading", len(m.group(1)), section=section)) continue b = BULLET.match(raw) if b: lines.append(Line(i, raw, strip_markup(b.group(2)), "bullet", indent=len(b.group(1)), section=section)) continue if is_caps_heading(stripped) and not re.search(r"\d{4}", stripped): section = stripped.title() if stripped.isupper() else stripped lines.append(Line(i, raw, section, "heading", 2, section=section)) continue indent = len(raw) - len(raw.lstrip()) lines.append(Line(i, raw, strip_markup(stripped), "text", indent=indent, section=section)) return lines # ---------------------------------------------------------------------------- checks def excerpt(s, start, end, width=30): a, b = max(0, start - width), min(len(s), end + width) return ("..." if a else "") + s[a:b].strip() + ("..." if b < len(s) else "") def load_banned(path): phrases = [] for raw in path.read_text(encoding="utf-8").splitlines(): p = raw.strip() if p and not p.startswith("#"): phrases.append(p.lower()) phrases.sort(key=len, reverse=True) compiled = [] for p in phrases: parts = [re.escape(w) for w in p.split()] body = r"\s+".join(parts).replace(r"\-", r"[-\s]?").replace("'", "['\u2019]") compiled.append((p, re.compile(rf"(? {t[:50]}{'...' if len(t) > 50 else ''}" def collect_blocks(lines): blocks = [] cur = None label_line = None last_bullet = None exp_level = None # heading level of the open experience subtree in_exp = False for ln in lines: if ln.kind == "heading": cur, label_line, last_bullet = None, None, None if exp_level is not None and ln.level <= exp_level: exp_level, in_exp = None, False if EXPERIENCE.search(ln.text) and not EARLIER.search(ln.text): exp_level, in_exp = ln.level, True continue if ln.kind == "bullet": if cur is None: cur = Block(block_label(ln.section, label_line), ln.section, in_exp) blocks.append(cur) cur.bullets.append([ln.no, ln.text]) last_bullet = ln continue if ln.kind == "text": if cur is not None and last_bullet is not None and ln.indent > last_bullet.indent \ and ln.no == last_bullet.no + 1: cur.bullets[-1][1] += " " + ln.text last_bullet = ln continue if cur is not None: cur, label_line = None, None if label_line is None: label_line = ln return blocks def experience_lines(lines, line_chars): """Estimated rendered lines per experience subtree (heading, est. lines).""" out = [] i = 0 while i < len(lines): ln = lines[i] if ln.kind == "heading" and EXPERIENCE.search(ln.text) and not EARLIER.search(ln.text): total = 1 j = i + 1 while j < len(lines) and not (lines[j].kind == "heading" and lines[j].level <= ln.level): total += rendered_lines(lines[j], line_chars) j += 1 out.append((ln, total)) i = j else: i += 1 return out def rendered_lines(ln, line_chars): if ln.kind == "blank": return 0 width = line_chars - 4 if ln.kind == "bullet" else line_chars return max(1, math.ceil(len(ln.text) / width)) def detect_kind(lines): if any(ln.kind == "heading" and EXPERIENCE.search(ln.text) for ln in lines): return "cv" if any(ln.kind == "text" and SALUTATION.match(ln.text) for ln in lines): return "letter" return "text" def letter_body(lines): start = next((i for i, ln in enumerate(lines) if ln.kind == "text" and SALUTATION.match(ln.text)), None) if start is None: return [ln for ln in lines if ln.kind in ("text", "bullet")], None end = next((i for i in range(start + 1, len(lines)) if lines[i].kind == "text" and CLOSING.match(lines[i].text)), len(lines)) body = [ln for ln in lines[start + 1:end] if ln.kind in ("text", "bullet")] return body, (lines[start].no + 1, lines[end - 1].no) def words(s): return len(re.findall(r"[\w\u00c0-\u017f'\u2019+#.-]+", s)) def section_stats(lines, line_chars): stats = {} order = [] for ln in lines: if ln.kind == "heading": if ln.section not in stats: order.append(ln.section) stats[ln.section] = [] continue if ln.section not in stats: order.append(ln.section) stats[ln.section] = [] stats[ln.section].append(ln) rows = [] for name in order: body = stats[name] while body and body[0].kind == "blank": body = body[1:] while body and body[-1].kind == "blank": body = body[:-1] text = "\n".join(ln.text for ln in body) rows.append({ "section": name, "chars": len(text), "chars_ns": len(re.sub(r"\s", "", text)), "words": words(text), "lines": sum(rendered_lines(ln, line_chars) for ln in body), }) return rows def parse_limits(items, flag): out = {} for item in items or []: name, sep, n = item.rpartition("=") if not sep or not n.strip().isdigit(): sys.exit(f"{flag} expects NAME=NUMBER, got {item!r}") out[name.strip().lower()] = int(n) return out def line_key(f): m = re.match(r"(?:body )?L(\d+)", f.where) return int(m.group(1)) if m else 0 def cell(s): return str(s).replace("|", "\\|").replace("\n", " ") def run(text, args, pre_findings=()): text = unicodedata.normalize("NFC", text) lines = parse(text) kind = args.kind if args.kind != "auto" else detect_kind(lines) banned = load_banned(Path(args.banned)) findings = list(pre_findings) for ln in lines: if ln.kind != "blank": check_line(ln, banned, findings) blocks = collect_blocks(lines) if kind == "cv" else [] if kind == "cv": if not EMAIL.search(text): findings.append(Finding("check", "document", "no email address found as plain text", "Plain-text contact", "print the email in the body")) if not PHONE.search(text): findings.append(Finding("check", "document", "no phone number found as plain text", "Plain-text contact", "print the phone number in the body, if the CV should carry one")) role_blocks = [b for b in blocks if b.in_experience] or blocks prev = None for b in role_blocks: n = len(b.bullets) if n > args.max_bullets: findings.append(Finding("error", f"L{b.bullets[0][0]} ({b.label})", f"{n} bullets", f"At most {args.max_bullets} bullets per role", "cut by relevance to the posting")) same_list = prev is not None and (prev.section == b.section or (prev.in_experience and b.in_experience)) if same_list and n > len(prev.bullets): findings.append(Finding("check", f"L{b.bullets[0][0]} ({b.label})", f"{n} bullets, more than the role above it ({len(prev.bullets)})", "Fewer bullets for older roles", "if this role is older, cut it down")) prev = b limit = 2 * args.line_chars for b in blocks: for no, t in b.bullets: if len(t) > limit: est = math.ceil(len(t) / (args.line_chars - 4)) findings.append(Finding("error", f"L{no} ({b.label})", f"bullet of {len(t)} chars, about {est} lines at {args.line_chars} chars per line", "Bullets at most 2 lines", "split or cut")) for heading, est in experience_lines(lines, args.line_chars): if est > args.page_lines: findings.append(Finding("check", f"L{heading.no} ({heading.text})", f"about {est} rendered lines; one page holds about {args.page_lines}", "Experience at most one page", "move older roles to an earlier-experience section on page two")) body_info = None if kind == "letter" or args.words: body, span = letter_body(lines) n = words("\n".join(ln.text for ln in body)) lo, hi = (250, 300) if args.words: lo_s, _, hi_s = args.words.partition("-") lo, hi = int(lo_s), int(hi_s or lo_s) body_info = (n, span, lo, hi) if not lo <= n <= hi: findings.append(Finding("error", f"body L{span[0]}-L{span[1]}" if span else "whole text", f"{n} body words", f"Letter {lo}-{hi} words", "cut restating sentences first" if n > hi else "add one forward-looking task")) rows = section_stats(lines, args.line_chars) char_limits = parse_limits(args.limit, "--limit") word_limits = parse_limits(args.word_limit, "--word-limit") by_name = {r["section"].lower(): r for r in rows} for name, n in char_limits.items(): r = by_name.get(name) if r is None: findings.append(Finding("error", name, "section not found for --limit", "Character limit", "check the heading text")) elif r["chars"] > n: findings.append(Finding("error", r["section"], f"{r['chars']} chars, limit {n}", "Character limit", f"cut {r['chars'] - n} characters")) for name, n in word_limits.items(): r = by_name.get(name) if r is None: findings.append(Finding("error", name, "section not found for --word-limit", "Word limit", "check the heading text")) elif r["words"] > n: findings.append(Finding("error", r["section"], f"{r['words']} words, limit {n}", "Word limit", f"cut {r['words'] - n} words")) if args.max_chars is not None and len(text.strip()) > args.max_chars: findings.append(Finding("error", "whole text", f"{len(text.strip())} chars, limit {args.max_chars}", "Character limit", f"cut {len(text.strip()) - args.max_chars} characters")) findings.sort(key=line_key) out = [] out.append(f"## check_text: {args.source} (kind: {kind})\n") out.append("### Findings\n") if findings: out.append("| # | Severity | Where | Problem | Rule | Suggested fix |") out.append("|---|---|---|---|---|---|") for i, f in enumerate(findings, 1): out.append(f"| {i} | {f.severity} | {cell(f.where)} | {cell(f.problem)} | {cell(f.rule)} | {cell(f.fix)} |") else: out.append("No findings.") out.append("\n### Sections\n") out.append("| Section | Chars | Chars without spaces | Words | Est. lines | Limit |") out.append("|---|---|---|---|---|---|") for r in rows: lim = [] if r["section"].lower() in char_limits: lim.append(f"{char_limits[r['section'].lower()]} chars") if r["section"].lower() in word_limits: lim.append(f"{word_limits[r['section'].lower()]} words") out.append(f"| {cell(r['section'])} | {r['chars']} | {r['chars_ns']} | {r['words']} | {r['lines']} | {', '.join(lim)} |") total = text.strip() total_ns = len(re.sub(r"\s", "", total)) out.append(f"| (whole text) | {len(total)} | {total_ns} | {words(total)} | | |") if body_info: n, span, lo, hi = body_info where_s = f"L{span[0]}-L{span[1]}" if span else "whole text" out.append(f"\nLetter body ({where_s}): {n} words, target {lo}-{hi}.") if blocks: out.append("\n### Bullets per role\n") out.append("| Role | Line | Bullets | Longest bullet (chars) | Est. lines |") out.append("|---|---|---|---|---|") for b in blocks: longest = max(len(t) for _, t in b.bullets) out.append(f"| {cell(b.label)} | L{b.bullets[0][0]} | {len(b.bullets)} | {longest} | " f"{math.ceil(longest / (args.line_chars - 4))} |") errors = sum(f.severity == "error" for f in findings) checks = len(findings) - errors out.append(f"\nSummary: {errors} error(s), {checks} check(s). Counts strip Markdown markup and bullet markers; " f"a newline counts as one character. Line estimates assume {args.line_chars} characters per line.") return "\n".join(out), errors def build_parser(): p = argparse.ArgumentParser(description="Deterministic style checks for application text.") p.add_argument("path", help="draft file (.md, .txt, .docx) or - for stdin") p.add_argument("--kind", choices=("auto", "cv", "letter", "form", "post", "text"), default="auto") p.add_argument("--banned", default=str(HERE / "banned_phrases.txt"), help="banned phrase list") p.add_argument("--max-bullets", type=int, default=5, help="bullets per role (default 5)") p.add_argument("--line-chars", type=int, default=90, help="characters per rendered line, for bullet and page estimates (default 90, A4 at 10-11pt)") p.add_argument("--page-lines", type=int, default=46, help="rendered lines per page (default 46)") p.add_argument("--words", help="body word range for a letter, e.g. 250-300 (default for --kind letter)") p.add_argument("--limit", action="append", help="NAME=CHARS for a section heading; repeatable") p.add_argument("--word-limit", action="append", help="NAME=WORDS for a section heading; repeatable") p.add_argument("--max-chars", type=int, help="character limit for the whole text") return p def main(argv=None): for stream in (sys.stdout, sys.stderr): if hasattr(stream, "reconfigure"): stream.reconfigure(encoding="utf-8") args = build_parser().parse_args(argv) pre = [] if args.path == "-": args.source = "stdin" text = sys.stdin.read() else: path = Path(args.path) args.source = path.name if path.suffix.lower() == ".docx": text, pre = read_docx(path) else: text = path.read_text(encoding="utf-8") report, errors = run(text, args, pre) print(report) return 1 if errors else 0 if __name__ == "__main__": sys.exit(main())