"""Expand standard construction bid-item abbreviations before classification.

Agency bid tabulations and estimates write items in a terse shorthand ("CONC BOX CULV (5 FT X 2 FT)",
"RE PM W/RET REQ TY I") that a model trained on spec prose cannot read. This is a general dictionary of
common US bid-item abbreviations (DOT and municipal), written from those conventions, not fitted to an eval set.
Whole ALL-CAPS tokens only; the original text is kept after the expansion so nothing is lost.
"""
import re

ABBREV = {
    "ACP": "asphalt concrete pavement", "AGGR": "aggregate", "AGG": "aggregate", "ASPH": "asphalt",
    "ASM": "assembly", "ASSM": "assembly", "ASSY": "assembly", "ATTEN": "attenuator", "BARR": "barricade",
    "BKFL": "backfill", "BM": "beam", "BRK": "broken line", "BS": "base", "CEM": "cement", "CL": "class",
    "CMP": "corrugated metal pipe", "COMPL": "complete", "CONC": "concrete", "CONDR": "conductor",
    "CONDT": "conduit", "CONST": "construction", "CONT": "control", "CRCP": "continuously reinforced concrete pavement",
    "CULV": "culvert", "CUSH": "cushion", "DEL": "delineator", "DIA": "diameter", "DRV": "driveway",
    "ELEC": "electrical", "EMBK": "embankment", "EXC": "excavation", "EXCAV": "excavation", "EXST": "existing",
    "EXIST": "existing", "FBR": "fiber", "FEN": "fence", "FL": "flexible", "GD": "guard", "GR": "grade",
    "HMA": "hot mix asphalt", "IL": "illumination", "ILL": "illumination", "INSTL": "install", "INST": "install",
    "LT": "light", "MATL": "material", "MLCH": "mulch", "MRK": "marking", "MRKR": "marker", "MTL": "metal",
    "PAV": "pavement", "PVMT": "pavement", "PERM": "permanent", "PM": "pavement marking", "PREFAB": "prefabricated",
    "PRESTR": "prestressed", "RC": "reinforced concrete", "RCP": "reinforced concrete pipe", "RD": "roadway",
    "RDWY": "roadway", "REFL": "reflectorized", "REINF": "reinforced", "REM": "remove", "REMOV": "remove",
    "RET": "retroreflectivity", "ROW": "right of way", "RT": "right", "SEDMT": "sediment", "STAB": "stabilized",
    "STR": "structure", "STRUCT": "structure", "SW": "sidewalk", "SWK": "sidewalk", "TEMP": "temporary",
    "TRT": "treatment", "TREAT": "treatment", "TY": "type", "TRANS": "transition", "VEH": "vehicle",
    "W/": "with ", "WW": "wingwall", "HW": "headwall",
}
_TOK = re.compile(r"[Ww]/(?=[A-Za-z ])|[A-Za-z]+")


def expand(text: str) -> str:
    """'CONC BOX CULV (5 FT X 2 FT)' -> 'concrete BOX culvert (5 FT X 2 FT) | CONC BOX CULV (5 FT X 2 FT)'."""
    hit = False

    def sub(m):
        nonlocal hit
        tok = m.group(0)
        # shorthand is written in capitals: prose words ("row", "cl") are left alone
        w = ABBREV.get(tok.upper()) if tok.upper() == tok else None
        if w:
            hit = True
            return w
        return m.group(0)
    out = _TOK.sub(sub, text)
    return f"{out} | {text}" if hit else text