mockymock 0.10.1__py3-none-any.whl

mockymock/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.10.1"  # x-release-please-version

mockymock/_lines.py

@@ -0,0 +1,86 @@
+"""Record-boundary line splitting for COBOL source text.
+
+`str.splitlines()` breaks on every Unicode line boundary: not only `\\n`,
+`\\r\\n` and `\\r` but also form feed (`\\x0c`, a page eject that legacy
+sources carry inside comment lines), vertical tab, the `\\x1c`-`\\x1e`
+separators, NEL (`\\x85`) and U+2028/2029. cobolparser splits a source's
+records on `\\n` / `\\r\\n` / `\\r` only (its own `_lines.split_source_lines`),
+so every `SourceLocation.line` it hands back counts records that way. A
+mockymock stage that split the same text with `splitlines()` saw one more
+line per such character, and every splice span after it landed one line
+early -- the mock replaced the statement BEFORE the boundary and the real
+CALL / file I/O still ran. Every split of COBOL source text (raw or
+normalized) that is later indexed by an AST line number goes through here.
+
+The rule that matters is *agreement with the installed cobolparser*, not
+any one splitting rule: cobolparser releases before `cobolparser._lines`
+existed (1.8.x and earlier, still allowed by the `>=1.7.7` floor) number
+records the `str.splitlines()` way themselves. Splitting on record
+delimiters only against one of those would shift every splice the other
+way. So record-delimiter splitting is used exactly when the parser does
+it, and `str.splitlines()` otherwise.
+"""
+
+from __future__ import annotations
+
+import re
+from importlib.util import find_spec
+from pathlib import Path
+
+_LINE_BREAK_RE = re.compile(r"\r\n|\r|\n")
+
+#: True when the installed cobolparser numbers records on `\\n` / `\\r\\n` /
+#: `\\r` only (it ships `cobolparser._lines`); False for older releases,
+#: which number them the `str.splitlines()` way.
+PARSER_SPLITS_ON_RECORD_DELIMITERS = find_spec("cobolparser._lines") is not None
+
+
+def split_source_lines(text: str) -> list[str]:
+    """Split `text` into lines the way the installed cobolparser numbers
+    them: on `\\n` / `\\r\\n` / `\\r` only when it does
+    (`PARSER_SPLITS_ON_RECORD_DELIMITERS`), otherwise `str.splitlines()`.
+    Either way: no trailing empty line for a terminating line break, `[]`
+    for `""`."""
+    if not PARSER_SPLITS_ON_RECORD_DELIMITERS:
+        return text.splitlines()
+    if not text:
+        return []
+    parts = _LINE_BREAK_RE.split(text)
+    if parts[-1] == "":
+        parts.pop()
+    return parts
+
+
+class SourceEncodingError(ValueError):
+    """A `.cbl` / `.cut` input that is not valid UTF-8.
+
+    mockymock refuses rather than guessing a legacy code page: the spliced
+    copy is written back as UTF-8 and compiled, so a cp1252 `é` inside a
+    `PIC X` literal would silently become two bytes and change the field's
+    length (the copybook path refuses a lossy decode the same way, as
+    EXPANSION_WARNING). The message names the file, the byte offset and
+    the conversion to run, so the CLI can print it instead of a traceback.
+    """
+
+    def __init__(self, path: object, exc: UnicodeDecodeError) -> None:
+        self.path = path
+        self.offset = exc.start
+        super().__init__(
+            f"{path} is not valid UTF-8 (byte 0x{exc.object[exc.start]:02x} at "
+            f"offset {exc.start}); mockymock reads COBOL sources and .cut "
+            f"files as UTF-8 -- convert the file first, e.g. "
+            f"`iconv -f cp1252 -t utf-8 {path}` for a Windows code-page source"
+        )
+
+
+def read_utf8_source(path: Path, *, keep_newlines: bool = False) -> str:
+    """`path.read_text(encoding="utf-8")`, raising `SourceEncodingError`
+    (not a bare UnicodeDecodeError) when the file is not UTF-8.
+    `keep_newlines=True` skips universal-newline translation, so a caller
+    that rewrites the file in place can see (and keep) its CRLFs."""
+    try:
+        if keep_newlines:
+            return path.read_bytes().decode("utf-8")
+        return path.read_text(encoding="utf-8")
+    except UnicodeDecodeError as exc:
+        raise SourceEncodingError(path, exc) from exc

mockymock/analysis/assertion_labels.py

@@ -0,0 +1,132 @@
+"""Where each `.cut` assertion's expected value came from.
+
+An `EXPECT`/`VERIFY` is only as good as the reason its value is the right
+one. Two reasons are worth telling apart, and the `cobol-test` skill (and
+`mockymock report`) asks for them to be written down as a comment line
+directly above the assertions they cover:
+
+    *> INTENT: BR-003 orders over 1000.00 get 5% off (ORDRPROC.cbl:212)
+    EXPECT WS-NET-AMOUNT TO BE 950.00
+
+    *> CHARACTERIZATION: recorded by run --record-expectations
+    EXPECT WS-AUDIT-COUNT TO BE 3
+
+INTENT means the value was derived from a business rule, a spec, or the
+developer -- a mismatch is a suspected program bug. CHARACTERIZATION means
+the value is whatever the program produced on some run -- it pins current
+behavior and proves nothing about correctness.
+
+A label covers every EXPECT/VERIFY line that follows it, up to the first
+blank line, the next label, the next TESTCASE, or any other directive.
+Other comment lines in between (a `*> STUB EXPECT`, a note) do not end it.
+An assertion no label covers is reported as unlabelled.
+
+Pure text analysis: works on any `.cut` that `parse_cut` accepts, needs no
+program and no Docker.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+INTENT = "intent"
+CHARACTERIZATION = "characterization"
+
+_LABEL_RE = re.compile(
+    r"^\*>\s*(?P<kind>INTENT|CHARACTERI[SZ]ATION)\b\s*:?\s*(?P<note>.*)$",
+    re.IGNORECASE,
+)
+_TESTCASE_RE = re.compile(r'^TESTCASE\s+"(?P<name>(?:[^"]|"")*)"', re.IGNORECASE)
+_ASSERTION_RE = re.compile(r"^(?P<kind>EXPECT|VERIFY)\b", re.IGNORECASE)
+_RULE_ID_RE = re.compile(r"\bBR-\d+\b", re.IGNORECASE)
+
+# The comment line `--record-expectations` writes above the EXPECTs it
+# recorded (see report/record_rewrite.py), so recorded values are labelled
+# without anyone having to remember to.
+RECORDED_LABEL = "*> CHARACTERIZATION: recorded by mockymock run --record-expectations"
+
+
+@dataclass
+class LabelledAssertion:
+    case_name: str
+    line: int
+    kind: str  # "expect" | "verify"
+    text: str
+    label: str | None = None  # INTENT | CHARACTERIZATION | None
+    note: str = ""
+    label_line: int | None = None
+    rule_ids: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "case": self.case_name,
+            "line": self.line,
+            "kind": self.kind,
+            "text": self.text,
+            "label": self.label,
+            "note": self.note,
+            "labelLine": self.label_line,
+            "ruleIds": list(self.rule_ids),
+        }
+
+
+def scan_assertion_labels(cut_text: str) -> list[LabelledAssertion]:
+    """Every EXPECT/VERIFY inside a TESTCASE, in file order, with the label
+    covering it (if any). Assertions outside any TESTCASE (a malformed file)
+    are skipped -- they belong to no case the report could attribute."""
+    results: list[LabelledAssertion] = []
+    case_name: str | None = None
+    label: tuple[str, str, int] | None = None  # (kind, note, line)
+
+    for line_no, raw in enumerate(cut_text.splitlines(), start=1):
+        stripped = raw.strip()
+        if not stripped:
+            label = None
+            continue
+        testcase = _TESTCASE_RE.match(stripped)
+        if testcase:
+            case_name = testcase.group("name").replace('""', '"')
+            label = None
+            continue
+        labelled = _LABEL_RE.match(stripped)
+        if labelled:
+            kind = labelled.group("kind").upper()
+            label = (
+                INTENT if kind == "INTENT" else CHARACTERIZATION,
+                labelled.group("note").strip(),
+                line_no,
+            )
+            continue
+        if stripped.startswith("*>"):
+            continue
+        assertion = _ASSERTION_RE.match(stripped)
+        if assertion is None:
+            label = None
+            continue
+        if case_name is None:
+            continue
+        item = LabelledAssertion(
+            case_name=case_name,
+            line=line_no,
+            kind=assertion.group("kind").lower(),
+            text=stripped,
+        )
+        if label is not None:
+            item.label, item.note, item.label_line = label
+            item.rule_ids = sorted(
+                {match.upper() for match in _RULE_ID_RE.findall(item.note)}
+            )
+        results.append(item)
+    return results
+
+
+def summarize_labels(items: list[LabelledAssertion]) -> dict[str, int]:
+    """Counts by label: the numbers the report's headline shows."""
+    return {
+        "total": len(items),
+        INTENT: sum(1 for i in items if i.label == INTENT),
+        CHARACTERIZATION: sum(1 for i in items if i.label == CHARACTERIZATION),
+        "unlabelled": sum(1 for i in items if i.label is None),
+    }

mockymock/analysis/cics_eib.py

@@ -0,0 +1,161 @@
+"""Detects whether a program references the CICS Execute Interface Block
+(`DFHEIBLK`) or any of its named fields (`EIBCALEN`, `EIBAID`, ...) without
+declaring them anywhere itself -- see
+docs/2026-08-27-cics-eib-linkage-support-design.md.
+
+A real CICS translator inserts `DFHEIBLK`'s LINKAGE SECTION layout ahead of
+`cobc`/the native compiler ever seeing the source; mockymock never runs a
+CICS translator (`splicer.injector.build_exec_trap` already avoids needing
+one for `EXEC CICS` command syntax itself, see the design doc's problem
+statement), so a program referencing an EIB field from ordinary COBOL
+outside any `EXEC CICS` block would otherwise fail `cobc` compilation with
+an undeclared-data-name error.
+
+Detection here is a pure, side-effect-free query, mirroring
+`analysis.linkage.linkage_plan`'s split from its own guardrail check:
+`cics_eib_plan` answers "is there anything to do" (`None` when the program
+never references any EIB name, or when it already declares its own copy --
+an ordinary non-CICS program, or a program that hand-declares/COPYs
+`DFHEIBLK` itself, either way untouched by this feature). It does not decide
+whether OTHER CICS constructs in the program are safe (`DFHRESP`/`DFHVALUE`
+macro calls, an undeclared `DFHCOMMAREA`) -- that is
+`refusal.check_cics_eib_layout`'s job.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from cobolparser.analysis.unused_variables import collect_declared_items
+
+DFHEIBLK_NAME = "DFHEIBLK"
+
+# The standard IBM CICS Execute Interface Block field names, unchanged
+# across CICS TS releases. See the design doc's "The DFHEIBLK layout"
+# section for the full PICTURE clauses -- this module only needs the names,
+# for reference detection.
+EIB_FIELD_NAMES: frozenset[str] = frozenset(
+    {
+        "EIBTIME",
+        "EIBDATE",
+        "EIBTRNID",
+        "EIBTASKN",
+        "EIBTRMID",
+        "EIBCPOSN",
+        "EIBCALEN",
+        "EIBAID",
+        "EIBFN",
+        "EIBRCODE",
+        "EIBDS",
+        "EIBREQID",
+        "EIBRSRCE",
+        "EIBSYNC",
+        "EIBFREE",
+        "EIBRECV",
+        "EIBATT",
+        "EIBEOC",
+        "EIBFMH",
+        "EIBCOMPL",
+        "EIBSIG",
+        "EIBCONF",
+        "EIBERR",
+        "EIBERRCD",
+        "EIBSYNRB",
+        "EIBNODAT",
+        "EIBRESP",
+        "EIBRESP2",
+        "EIBRLDBK",
+    }
+)
+
+_EIB_NAMES = EIB_FIELD_NAMES | {DFHEIBLK_NAME}
+# Plain `\b...\b` is wrong here: COBOL identifiers may contain hyphens,
+# which are not `\w` characters, so `\bEIBCALEN\b` would false-match inside
+# an unrelated hyphenated name like `WS-EIBCALEN-SAVED` (a `\b` boundary
+# exists at the transition between the non-word `-` and the word-char `E`).
+# Use an explicit lookaround against the full COBOL identifier character
+# class (letters/digits/hyphen) instead, and match case-insensitively --
+# COBOL identifiers are themselves case-insensitive, so a lowercase or
+# mixed-case source reference is exactly as real a reference as an
+# uppercase one.
+# One combined alternation rather than 29 separate patterns: each pattern
+# starts with a lookbehind, which defeats `re`'s literal-prefix scan
+# optimization, so every name cost a full pass over the program text --
+# measured at 0.73s of a 2.5s static-check pass on a 29k-line program, ~15x
+# `refusal.check_cics_eib_layout`'s two-pattern equivalent. Longest name
+# first so a prefix never shadows a longer sibling (EIBRESP vs EIBRESP2);
+# occurrences cannot overlap, since the lookarounds delimit every match
+# with a non-identifier character on both sides.
+_EIB_NAME_RE = re.compile(
+    "(?<![A-Za-z0-9-])(?:"
+    + "|".join(sorted((re.escape(n) for n in _EIB_NAMES), key=len, reverse=True))
+    + ")(?![A-Za-z0-9-])",
+    re.IGNORECASE,
+)
+
+
+# The EXEC DLI interface block (DIB). Like the EIB, the DL/I translator
+# normally supplies it, so a program testing DIBSTAT after an EXEC DLI call
+# did not compile under mockymock -- behind a clean lint (issue #145).
+DLIDIB_NAME = "DLIDIB"
+DIB_FIELD_NAMES: frozenset[str] = frozenset(
+    {
+        "DIBVER",
+        "DIBSTAT",
+        "DIBSEGM",
+        "DIBSEGLV",
+        "DIBKFBL",
+        "DIBDBDNM",
+        "DIBDBORG",
+    }
+)
+_DIB_NAMES = DIB_FIELD_NAMES | {DLIDIB_NAME}
+_DIB_NAME_RE = re.compile(
+    "(?<![A-Za-z0-9-])(?:"
+    + "|".join(sorted((re.escape(n) for n in _DIB_NAMES), key=len, reverse=True))
+    + ")(?![A-Za-z0-9-])",
+    re.IGNORECASE,
+)
+
+
+@dataclass
+class CicsEibPlan:
+    """Everything `splicer.cics_eib`'s synthesis functions need.
+
+    `referenced_names` is sorted, transparency-message-only: synthesis
+    always emits the full fixed `DFHEIBLK` layout regardless of which
+    specific fields matched (see module docstring on the design doc's
+    reasoning -- a real translator always inserts the whole block).
+    """
+
+    referenced_names: list[str]
+    #: DL/I interface block names referenced and undeclared (issue #145);
+    #: empty when the program needs no DIB. Synthesized the same way, as a
+    #: `01 DLIDIB.` group.
+    dib_names: list[str] = field(default_factory=list)
+
+
+def cics_eib_plan(program, lines: list[str]) -> CicsEibPlan | None:
+    """`None` when there is nothing for this feature to do: no EIB name
+    referenced anywhere in `lines`, or every referenced name is already
+    declared somewhere in the program's own DATA DIVISION (a hand-declared
+    or `COPY DFHEIBLK`-expanded copy -- synthesizing a second one would be a
+    duplicate-data-name compile error, and the program already has real
+    storage for it).
+    """
+    text = "\n".join(lines)
+    referenced = sorted({m.group(0).upper() for m in _EIB_NAME_RE.finditer(text)})
+    dib = sorted({m.group(0).upper() for m in _DIB_NAME_RE.finditer(text)})
+    if not referenced and not dib:
+        return None
+
+    declared = {item.name.upper() for item in collect_declared_items(program)}
+    if declared & set(referenced):
+        referenced = []
+    if declared & _DIB_NAMES:
+        dib = []
+    if not referenced and not dib:
+        return None
+
+    return CicsEibPlan(referenced_names=referenced, dib_names=dib)