Home /Modules/tests/java_signature_comparison.py

java_signature_comparison.py

tests/java_signature_comparison.py · 245 line(s) · py

#!/usr/bin/env python3
"""Deterministic normalized Java/SLeeLa declaration comparison.

This is a source/API congruence tool. It deliberately does not compare JVM
descriptors, bytecode, or runtime behavior.

The normal form records:
- owned/nested type declarations and inheritance clauses;
- class/interface/enum/record declaration modifiers and type parameters;
- fields;
- constructors (distinct from methods);
- methods, including generic parameters, varargs, receiver-like metadata,
  parameter modifiers, return type, throws types, and annotations.

The parser is intentionally lightweight: it is a qualification fixture tool,
not the production Java parser.
"""
import argparse
import json
import re
from pathlib import Path

IDENT = r"[A-Za-z_$][\w$]*"
MODIFIERS = (
    "public|protected|private|static|final|abstract|native|synchronized|"
    "volatile|transient|strictfp|sealed|non-sealed|default"
)
DECL_RE = re.compile(
    rf"(?P<mods>(?:(?:{MODIFIERS})\s+)*)"
    rf"(?P<kind>class|interface|enum|record)\s+"
    rf"(?P<name>{IDENT})"
    rf"(?P<generics>\s*<[^{{}};()]+>)?"
    rf"(?P<tail>[^{{;]*)(?=\{{)"
)
METHOD_RE = re.compile(
    rf"(?P<mods>(?:(?:{MODIFIERS})\s+)*)"
    rf"(?P<generics><[^{{}}()]+>\s*)?"
    rf"(?P<ret>[A-Za-z_$][\w$]*(?:\s*<[^;{{}}()]+>)?(?:\[\])*(?:\.[A-Za-z_$][\w$]*)*)"
    rf"\s+(?P<name>{IDENT})\s*\((?P<args>[^(){{}}]*)\)"
    rf"(?:\s+throws\s+(?P<throws>[^{{;]+))?"
)
CTOR_RE = re.compile(
    rf"(?P<mods>(?:(?:public|protected|private)\s+)*)"
    rf"(?P<generics><[^{{}}()]+>\s*)?"
    rf"(?P<name>{IDENT})\s*\((?P<args>[^(){{}}]*)\)"
    rf"(?:\s+throws\s+(?P<throws>[^{{;]+))?"
)
FIELD_RE = re.compile(
    rf"(?P<mods>(?:(?:public|protected|private|static|final|volatile|transient)\s+)*)"
    rf"(?P<type>[A-Za-z_$][\w$]*(?:\s*<[^;{{}}()]+>)?(?:\[\])*(?:\.[A-Za-z_$][\w$]*)*)"
    rf"\s+(?P<name>{IDENT})\s*(?:=[^;]*)?;"
)

def strip_comments(text):
    text = re.sub(r"/\*.*?\*/", "", text, flags=re.S)
    return re.sub(r"//.*", "", text)

def normalize_type(text):
    text = re.sub(r"@(?:[\w$.]+)(?:\([^)]*\))?\s*", "", text.strip())
    text = re.sub(r"\b(final|volatile|transient)\b\s+", "", text)
    text = re.sub(r"\s+", "", text)
    return text.replace("java.lang.", "")

def split_top(text):
    out, start, depth = [], 0, 0
    pairs = {"<": ">", "(": ")", "[": "]"}
    closing = set(pairs.values())
    for i, ch in enumerate(text):
        if ch in pairs:
            depth += 1
        elif ch in closing:
            depth = max(0, depth - 1)
        elif ch == "," and depth == 0:
            out.append(text[start:i].strip())
            start = i + 1
    tail = text[start:].strip()
    if tail:
        out.append(tail)
    return out

def generic_shape(text):
    if not text:
        return []
    inner = text.strip()[1:-1]
    return [re.sub(r"\s+", " ", item.strip()) for item in split_top(inner) if item.strip()]

def annotations(text):
    return sorted(set(re.findall(r"@([A-Za-z_$][\w$.]*)", text)))

def params(text):
    out = []
    for item in split_top(text):
        item = item.strip()
        if not item:
            continue
        ann = annotations(item)
        item = re.sub(r"@(?:[\w$.]+)(?:\([^)]*\))?\s*", "", item)
        item = re.sub(r"\b(final|volatile|transient)\b\s+", "", item).strip()
        varargs = "..." in item
        item = item.replace("...", "[]")
        bits = item.split()
        if len(bits) >= 2:
            typ, name = " ".join(bits[:-1]), bits[-1]
        else:
            typ, name = item, ""
        out.append({
            "name": name,
            "type": normalize_type(typ),
            "varargs": varargs,
            "annotations": ann,
        })
    return out

def throws(text):
    if not text:
        return []
    return sorted(normalize_type(x) for x in split_top(text))

def modifiers(text):
    return sorted(text.split())

def inheritance(tail):
    tail = re.sub(r"\s+", " ", tail.strip())
    result = {"extends": [], "implements": [], "permits": []}
    for key in result:
        m = re.search(rf"\b{key}\s+(.+?)(?=\b(?:extends|implements|permits)\b|$)", tail)
        if m:
            result[key] = sorted(normalize_type(x) for x in split_top(m.group(1)))
    return result

def normalize(text):
    src = strip_comments(text)
    declarations = []
    # Stack ownership is intentionally approximate but deterministic for the
    # qualification corpus: declarations are ordered by source occurrence.
    decl_matches = list(DECL_RE.finditer(src))
    owners = []
    for m in decl_matches:
        name = m.group("name")
        owner = "::".join(owners) if owners else ""
        path = f"{owner}::{name}" if owner else name
        declarations.append({
            "kind": m.group("kind"),
            "name": name,
            "path": path,
            "modifiers": modifiers(m.group("mods")),
            "typeParameters": generic_shape(m.group("generics")),
            **inheritance(m.group("tail")),
            "annotations": annotations(src[max(0, m.start()-300):m.start()]),
        })
        # Nested declaration ownership is inferred only when a prior type's
        # opening brace encloses this declaration.
        opens = src.find("{", m.end())
        closes_before = src.rfind("}", 0, m.start())
        if opens >= 0 and opens > closes_before:
            owners.append(name)

    type_names = {d["name"] for d in declarations}
    constructors = []
    for m in CTOR_RE.finditer(src):
        if m.group("name") in type_names:
            constructors.append({
                "owner": m.group("name"),
                "name": m.group("name"),
                "modifiers": modifiers(m.group("mods")),
                "typeParameters": generic_shape(m.group("generics")),
                "parameters": params(m.group("args")),
                "throws": throws(m.group("throws")),
                "annotations": annotations(src[max(0, m.start()-300):m.start()]),
            })

    constructor_spans = {(m.start(), m.end()) for m in CTOR_RE.finditer(src) if m.group("name") in type_names}
    methods = []
    for m in METHOD_RE.finditer(src):
        if (m.start(), m.end()) in constructor_spans:
            continue
        methods.append({
                "name": m.group("name"),
                "modifiers": modifiers(m.group("mods")),
                "typeParameters": generic_shape(m.group("generics")),
                "returnType": normalize_type(m.group("ret")),
                "parameters": params(m.group("args")),
                "throws": throws(m.group("throws")),
                "annotations": annotations(src[max(0, m.start()-300):m.start()]),
            })

    fields = []
    for m in FIELD_RE.finditer(src):
        fields.append({
            "name": m.group("name"),
            "modifiers": modifiers(m.group("mods")),
            "type": normalize_type(m.group("type")),
            "annotations": annotations(src[max(0, m.start()-300):m.start()]),
        })

    return {
        "normalizationVersion": 2,
        "declarations": sorted(declarations, key=lambda x: x["path"]),
        "constructors": sorted(constructors, key=lambda x: (x["owner"], x["parameters"])),
        "methods": sorted(methods, key=lambda x: (x["name"], x["returnType"], x["parameters"])),
        "fields": sorted(fields, key=lambda x: (x["name"], x["type"])),
    }

def compare(java, sleela):
    def delta(key):
        j = {json.dumps(x, sort_keys=True) for x in java[key]}
        s = {json.dumps(x, sort_keys=True) for x in sleela[key]}
        return [json.loads(x) for x in sorted(j-s)], [json.loads(x) for x in sorted(s-j)]
    result = {}
    mismatch = False
    for key in ("declarations", "constructors", "methods", "fields"):
        missing, extra = delta(key)
        result[key] = {"missing": missing, "extra": extra}
        mismatch |= bool(missing or extra)
    result["status"] = "PASS" if not mismatch else "MISMATCH"
    return result

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--java", required=True, type=Path)
    ap.add_argument("--sleela", required=True, type=Path)
    ap.add_argument("--json", type=Path)
    args = ap.parse_args()
    java = normalize(args.java.read_text(encoding="utf-8"))
    sleela = normalize(args.sleela.read_text(encoding="utf-8"))
    result = {
        "tool": "sleela-java-normalized-signature-comparison",
        "normalizationVersion": 2,
        "scope": "source/API declaration congruence; no JVM/SLVM requirement",
        "java": java,
        "sleela": sleela,
        "comparison": compare(java, sleela),
    }
    rendered = json.dumps(result, indent=2, sort_keys=True)
    if args.json:
        args.json.write_text(rendered + "\n", encoding="utf-8")
    print("SLeeLa Java Normalized Signature Comparison")
    print("  status:", result["comparison"]["status"])
    if args.json:
        print("  report:", args.json)
    return 0 if result["comparison"]["status"] == "PASS" else 1

if __name__ == "__main__":
    raise SystemExit(main())