@shundoo-ai/dsh-cosmic 1.0.19 → 1.0.21

package/skills/cosmic-build/scripts/platform_api_contract.py

@@ -120,10 +120,15 @@ _FRONT_MATTER_FIELD_RE = re.compile(r'^(?P<key>\w+):\s*"?(?P<value>[^"\n]*)"?\s*
 # One registered signature inside a ```java block. The return type may carry generics or array
 # markers; the generic body excludes parentheses so it can never swallow the parameter list. The
 # parameter list closes on the same line: every page signature is written that way, and requiring
-# the closing parenthesis keeps a prose fragment from parsing as a signature.
+# the closing parenthesis keeps a prose fragment from parsing as a signature. A generic method
+# declares its type parameters before the return type (`public <T extends Control> T
+# getControl(String key)`); without that optional group IFormView.getControl and
+# IDataModel.getContextVariable looked unregistered, and an ordinary call to either was reported
+# as a remembered spelling of some other member.
 _SIGNATURE_RE = re.compile(
     r"^\s*(?:public|protected)\s+"
     r"(?:(?:static|final|abstract|synchronized|native|default|strictfp)\s+)*"
+    r"(?:(?P<tparams><[^;{}()]*>)\s+)?"
     r"(?P<ret>[\w.$]+(?:\s*<[^;{}()]*>)?(?:\s*\[\s*\])*)\s+"
     r"(?P<name>[A-Za-z_$][\w$]*)\s*\((?P<params>[^)]*)\)",
     re.MULTILINE,
@@ -153,6 +158,26 @@ _ALWAYS_ASSIGNABLE = {"Object", "var"}
 _GENERIC_RE = re.compile(r"<[^<>]*>")
 
 
+def _type_variables(type_parameters: str) -> set[str]:
+    """`<T extends Control, K>` -> {"T", "K"}: only top-level names, not bounds."""
+    body = type_parameters.strip()[1:-1]
+    names, depth, current = set(), 0, ""
+    for char in body + ",":
+        if char == "<":
+            depth += 1
+        elif char == ">":
+            depth -= 1
+        elif char == "," and depth == 0:
+            match = re.match(r"\s*([A-Za-z_$][\w$]*)", current)
+            if match:
+                names.add(match.group(1))
+            current = ""
+            continue
+        if depth == 0:
+            current += char
+    return names
+
+
 def _normalized(type_text: str) -> str:
     """A type as a signature comparison sees it: no package, no generics, array markers kept."""
     bare = type_text.strip()
@@ -195,10 +220,16 @@ def _page(fqcn: str) -> dict | None:
     # a no-argument signature and stays registered, because "overrides nothing" is exactly the
     # finding for a no-arg method that declares a parameter.
     signatures: dict[str, set[tuple[str, ...]]] = {}
+    # Names with an overload whose return type is one of its own type variables: the caller's
+    # declared type is the type argument, so no declared type contradicts that overload.
+    generic_returns: set[str] = set()
     for match in _SIGNATURE_RE.finditer(text):
         returns.setdefault(match.group("name"), set()).add(_normalized(match.group("ret")))
         signatures.setdefault(match.group("name"), set()).add(
             tuple(_param_types(match.group("params"))))
+        if match.group("tparams") and _normalized(match.group("ret")).rstrip("[]") in _type_variables(
+                match.group("tparams")):
+            generic_returns.add(match.group("name"))
     supertypes: set[str] = set()
     for match in _SUPERTYPE_RE.finditer(text[: front.end() + 4000]):
         supertypes.update(_TYPE_TOKEN_RE.findall(match.group("names")))
@@ -207,9 +238,11 @@ def _page(fqcn: str) -> dict | None:
         "className": class_name,
         "fqcn": fqcn,
         "returns": returns,
+        "genericReturns": generic_returns,
         "signatures": signatures,
         "supertypes": supertypes,
         "path": path,
+        "text": text,
     }
 
 
@@ -236,6 +269,168 @@ def _page_by_simple_name(simple_name: str) -> dict | None:
     return _page(f"{PLATFORM_PACKAGE}{relative}.{simple_name}" if relative else f"{PLATFORM_PACKAGE}{simple_name}")
 
 
+def describe_api(selector: str, members: list[str] | None = None) -> dict:
+    """Expose bounded API evidence for one receiver, including inherited declarations."""
+    page = _page(selector) if "." in selector else _page_by_simple_name(selector)
+    if page is None:
+        candidate = _page_by_simple_name(selector.rsplit(".", 1)[-1]) if "." in selector else None
+        return {"status": False, "errorCode": "API_CLASS_NOT_DOCUMENTED", "class": selector,
+                "message": "No unique registered API page; this does not prove the class is absent from the SDK.",
+                "sdkLookup": {"script": str(Path(__file__).with_name("inspect_platform_sdk.py")),
+                              "arguments": ["--class", selector, "--sdk-dir", "<bound target SDK directory>",
+                                            *[arg for member in members or [] for arg in ("--member", member)]]},
+                **({"candidateClass": candidate["fqcn"], "candidateReference": str(candidate["path"])} if candidate else {})}
+    evidence = []
+    sources = {}
+    seen = set()
+    for owner in _lineage_pages(page["fqcn"]):
+        sections = re.split(r"(?m)^###\s+", owner["text"])
+        notes = {section.splitlines()[0].strip(): section.split("```", 1)[0].split("\n", 1)[-1].strip()
+                 for section in sections[1:]}
+        for match in _SIGNATURE_RE.finditer(owner["text"]):
+            name = match.group("name")
+            identity = (name, tuple(_param_types(match.group("params"))))
+            if identity in seen or members and name not in members:
+                continue
+            seen.add(identity)
+            note = notes.get(name, "")
+            evidence.append({"name": name, "declaredBy": owner["fqcn"],
+                             "signature": re.sub(r"\s+", " ", match.group(0)).strip(),
+                             "deprecated": bool(re.search(r"deprecated|已弃用|废弃|过时", note, re.IGNORECASE)),
+                             "notes": note[:600]})
+            sources[owner["fqcn"]] = str(owner["path"])
+    found = {item["name"] for item in evidence}
+    return {"status": True, "class": page["fqcn"], "import": "import " + page["fqcn"] + ";",
+            "reference": str(page["path"]), "members": evidence, "sources": sources,
+            "undocumentedMembers": [name for name in members or [] if name not in found],
+            **({"sdkLookup": {"script": str(Path(__file__).with_name("inspect_platform_sdk.py")),
+                               "arguments": ["--class", page["fqcn"], "--sdk-dir", "<bound target SDK directory>",
+                                             *[arg for name in members or [] if name not in found for arg in ("--member", name)]]}}
+               if any(name not in found for name in members or []) else {}),
+            "evidenceScope": "Registered declarations and documented supertypes; undocumented members are not proof of SDK absence."}
+
+
+def plugin_coding_evidence(plugin_type: str, scenes: list[str] | None = None) -> dict:
+    """Resolve coding references from the existing type and API registries."""
+    registry = json.loads(TYPE_REGISTRY_PAGE.read_text(encoding="utf-8-sig"))
+    definition = next((item for item in registry["types"] if item["type"] == plugin_type), None)
+    if definition is None:
+        return {}
+    root = TYPE_REGISTRY_PAGE.parent.parent
+    evidence = {
+        "codingEntry": str(root / "skills" / "cosmic-coding-impl" / "SKILL.md"),
+        "guide": str(root / definition["guide"]) if definition.get("guide") else None,
+        "typeKnowledge": str(TYPE_CONTRACTS_PAGE),
+        "standards": str(STANDARDS_PAGE),
+        "filterOperators": [{"literal": literal, "constant": "QCP." + constant, "preferred": preferred}
+                            for literal, (constant, preferred) in _qcp_constants().items()],
+        "apiLookup": {"script": str(Path(__file__).resolve()),
+                      "arguments": ["--describe-class", "<receiver class>", "--member", "<required member>"]},
+        "sdkLookup": {"script": str(Path(__file__).with_name("inspect_platform_sdk.py")),
+                      "arguments": ["--class", "<receiver class>", "--sdk-dir", "<bound target SDK directory>",
+                                    "--member", "<required member>"]},
+    }
+    if plugin_type == "operation":
+        evidence["operationDispatch"] = {
+            "transactionEvent": {"class": "kd.bos.entity.plugin.args.OperationArgs", "accessor": "event.getOperationKey()",
+                                 "reference": describe_api("kd.bos.entity.plugin.args.OperationArgs")["reference"]},
+            "validator": {"class": "kd.bos.entity.validate.AbstractValidator", "accessor": "this.getOperateKey()",
+                          "reference": describe_api("kd.bos.entity.validate.AbstractValidator")["reference"]},
+            "guide": str(root / "references" / "operation-dispatch.md"),
+            "evidenceScope": "8.0 SDK accessor signatures checked with javap; these do not verify any operateMeta Map key or actual event execution",
+        }
+    base = definition.get("baseImport")
+    if base:
+        evidence["baseContract"] = describe_api(base)
+        evidence["baseContract"]["members"] = [
+            {key: value for key, value in item.items() if key != "notes" or item["deprecated"]}
+            for item in evidence["baseContract"].get("members", [])
+        ]
+        guide_text = (root / definition["guide"]).read_text(encoding="utf-8-sig")
+        guide_signatures = list(_SIGNATURE_RE.finditer(guide_text))
+        evidence["guideSignatures"] = list(dict.fromkeys(
+            re.sub(r"\s+", " ", match.group(0)).strip() for match in guide_signatures
+        ))
+        parameters = {}
+        for match in guide_signatures:
+            for parameter in _param_types(match.group("params")):
+                page = _page_by_simple_name(parameter.removesuffix("[]"))
+                if page:
+                    parameters[page["fqcn"]] = {"class": page["fqcn"], "reference": str(page["path"])}
+        for owner in _lineage_pages(base):
+            for signatures in owner["signatures"].values():
+                for signature in signatures:
+                    for parameter in signature:
+                        page = _page_by_simple_name(parameter.removesuffix("[]"))
+                        if page:
+                            parameters[page["fqcn"]] = {"class": page["fqcn"], "reference": str(page["path"])}
+        evidence["parameterTypes"] = sorted(parameters.values(), key=lambda item: item["class"])
+    scene_root = (root / "knowledge" / "cosmic" / "platform" / "scenes").resolve()
+    selected = []
+    apis: dict[str, set[str]] = {}
+    for selector in scenes or []:
+        target = (scene_root / (selector if selector.endswith(".md") else selector + ".md")).resolve()
+        if not target.is_relative_to(scene_root) or not target.is_file():
+            raise ValueError(f"unknown coding scene: {selector}")
+        selected.append(str(target))
+        text = target.read_text(encoding="utf-8-sig")
+        # Scene metadata and its explicit evidence links are existing knowledge authorities.
+        references = re.findall(r"`((?:data-access|operation)/[A-Za-z0-9_/.-]+\.md)`", text)
+        texts = [text] + [(scene_root / reference).read_text(encoding="utf-8-sig")
+                          for reference in references if (scene_root / reference).is_file()]
+        for content in texts:
+            related = re.search(r"(?m)^related_apis:\s*\[([^]]*)\]", content)
+            tokens = [token.strip().strip("\"'") for token in
+                      (related.group(1).split(",") if related else [])]
+            owners = [token for token in tokens if _page_by_simple_name(token)]
+            for owner in owners:
+                apis.setdefault(owner, set()).update(token for token in tokens
+                    if re.fullmatch(r"[a-z][A-Za-z0-9_]*", token))
+            for token in tokens:
+                value = token
+                owner, separator, member = value.partition(".")
+                if not _page_by_simple_name(owner):
+                    continue
+                apis.setdefault(owner, set())
+                if separator:
+                    apis[owner].add(member)
+            for owner, member in re.findall(r"\b([A-Z][A-Za-z0-9_]*)\.([a-z][A-Za-z0-9_]*)\s*\(", content):
+                if _page_by_simple_name(owner):
+                    apis.setdefault(owner, set()).add(member)
+    if selected:
+        evidence["scenes"] = selected
+        evidence["apiContracts"] = [describe_api(owner, sorted(members))
+                                    for owner, members in sorted(apis.items()) if members
+                                    and _page_by_simple_name(owner)["fqcn"] != base]
+        for contract in evidence["apiContracts"]:
+            contract["members"] = [{key: value for key, value in item.items()
+                                    if key != "notes" or item["deprecated"]}
+                                   for item in contract.get("members", [])]
+    # Parameter evidence alone misses types such as AbstractValidator.getDataEntities()'s
+    # ExtendedDataEntity[] return value. Resolve only names proven by a unique SDK page.
+    signature_types = {item["class"]: {**item, "import": "import " + item["class"] + ";"}
+                       for item in evidence.get("parameterTypes", [])}
+    signatures = evidence.get("guideSignatures", []) + [
+        member["signature"] for contract in
+        [evidence.get("baseContract", {}), *evidence.get("apiContracts", [])]
+        for member in contract.get("members", [])
+    ]
+    for signature in signatures:
+        match = _SIGNATURE_RE.search(signature)
+        if not match:
+            continue
+        for name in re.findall(r"\b(?:kd\.bos\.[\w.$]+|[A-Z][\w$]*)\b",
+                               match.group("ret") + " " + match.group("params")):
+            page = _page(name) if "." in name else _page_by_simple_name(name)
+            if page:
+                signature_types[page["fqcn"]] = {
+                    "class": page["fqcn"], "import": "import " + page["fqcn"] + ";",
+                    "reference": str(page["path"]),
+                }
+    evidence["signatureTypes"] = sorted(signature_types.values(), key=lambda item: item["class"])
+    return evidence
+
+
 def _imports(code: str) -> dict[str, str]:
     resolved: dict[str, str] = {}
     for match in _IMPORT_RE.finditer(code):
@@ -285,9 +480,10 @@ def return_type_issues(source_text: str) -> list[dict]:
         if not page:
             continue
         registered = page["returns"].get(match.group("method"))
-        if not registered:
+        if not registered or match.group("method") in page["genericReturns"]:
             # The overload set may simply be unregistered — the javadoc export omits everything
-            # that is not @SdkPublic. Unknown is not wrong.
+            # that is not @SdkPublic. Unknown is not wrong. A generic return (`<T> T`) takes its
+            # type from the declaration, so the declared type is never a contradiction.
             continue
         end = _call_end(code, code.index("(", match.end() - 1))
         if end is None or code[end:].lstrip()[:1] != ";":
@@ -409,6 +605,13 @@ def filter_operator_issues(source_text: str) -> list[dict]:
             continue
         operator = _OPERATOR_ARG_RE.match(arguments[1])
         if not operator:
+            # Confirmed javac failure from the recorded delivery; do not treat this typo as a
+            # valid constant or offer a string literal that would trigger the next guard.
+            if (arguments[1] == "kd.bos.orm.query.QCP.equal" or arguments[1] == "QCP.equal"
+                    and _imports(code).get("QCP") == "kd.bos.orm.query.QCP") and "=" in constants:
+                issues.append({"line": code[:match.start()].count("\n") + 1,
+                    "operator": arguments[1], "constant": "QCP." + constants["="][0],
+                    "message": "QCP.equal is not the SDK equality constant; use QCP.equals. Keep the typed operator instead of replacing it with a string."})
             # Already a constant, or a variable / concatenation this scan must not judge.
             continue
         entry = constants.get(operator.group("operator").strip().lower())
@@ -564,7 +767,7 @@ _PROPERTY_WRITE_RE = re.compile(
     r"(?:\bgetModel\s*\(\s*\)\s*\.\s*setValue|\.\s*setValueFast)\s*\(")
 _PROPERTY_GUARD_RE = re.compile(r"getProperty\s*\(\s*\)|getChangeSet\s*\(\s*\)")
 
-_OPERATION_PLUGIN_RE = re.compile(r"\bextends\s+AbstractOperationServicePlugIn\b")
+_OPERATION_PLUGIN_RE = re.compile(r"\bextends\s+(?:[\w$]+\.)*AbstractOperationServicePlugIn\b")
 # The plugin's own inherited accessor, not the one on an event argument. The lookbehind rejects any
 # qualified call so `e.getDataEntities()` — the correct form — is never matched, while `this.` is
 # matched explicitly.
@@ -618,17 +821,22 @@ def scene_misuse_issues(source_text: str) -> list[dict]:
                     "write when the new value already equals the current one",
                 )
 
-    # `AbstractValidator` declares a `getDataEntities()` of its own that is correct to call, and a
-    # validator is routinely written in the same file as the operation plugin that adds it. The two
-    # are indistinguishable without class-level scoping, so the presence of a validator waives this
-    # rule for the file: missing one null dereference costs a stack trace, while reporting the
-    # validator's correct call would block a delivery that has nothing wrong with it.
-    if _OPERATION_PLUGIN_RE.search(code) and "AbstractValidator" not in code:
+    # A validator's same-named method is valid; determine the actual enclosing receiver
+    # instead of waiving the operation-plugin check for the entire file.
+    classes = _class_bodies(code)
+    if _OPERATION_PLUGIN_RE.search(code):
         for match in _INHERITED_DATA_ENTITIES_RE.finditer(code):
             # Only a call inside a method body: the same text outside one is the class declaring
             # its own override, which is not this defect.
             if not any(body["start"] <= match.start() < body["end"] for body in bodies):
                 continue
+            scopes = [scope for scope in classes if scope["start"] <= match.start() < scope["end"]]
+            qualifier = re.search(r"([A-Za-z_$][\w$]*)\s*\.\s*$", code[:match.start()])
+            if qualifier:
+                scopes = [scope for scope in scopes if scope["name"] == qualifier.group(1)]
+            owner = max(scopes, key=lambda scope: scope["start"]) if scopes else None
+            if not owner or owner["base"].rsplit(".", 1)[-1] != "AbstractOperationServicePlugIn":
+                continue
             add(
                 match.start(),
                 "AbstractOperationServicePlugIn.getDataEntities",
@@ -642,6 +850,26 @@ def scene_misuse_issues(source_text: str) -> list[dict]:
     return issues
 
 
+def _class_bodies(code: str) -> list[dict]:
+    """Locate named and anonymous class scopes in comment/literal-free Java."""
+    pattern = re.compile(
+        r"\b(?:class\s+(?P<name>[\w$]+)(?:\s+extends\s+(?P<base>[\w$.]+))?[^;{}]*"
+        r"|new\s+(?P<anonymous>[\w$.]+)\s*\([^;{}]*\))\s*\{")
+    scopes = []
+    for match in pattern.finditer(code):
+        opening = match.end() - 1
+        depth = 1
+        end = opening + 1
+        while end < len(code) and depth:
+            depth += (code[end] == "{") - (code[end] == "}")
+            end += 1
+        if depth == 0:
+            scopes.append({"name": match.group("name"),
+                           "base": match.group("base") or match.group("anonymous") or "",
+                           "start": opening + 1, "end": end - 1})
+    return scopes
+
+
 # The outermost class declaration's `extends` clause. Generic bounds are skipped rather than
 # parsed: a plugin class never carries them, and a missed base is one finding fewer, never a
 # false one.
@@ -1177,8 +1405,15 @@ def unverified_member_issues(source_text: str) -> list[dict]:
 def main() -> int:
     parser = argparse.ArgumentParser(
         description="Check platform API contracts in one Java plugin source")
-    parser.add_argument("--source-path", required=True)
+    mode = parser.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--source-path")
+    mode.add_argument("--describe-class", action="append", help="Exact SDK class name or fully qualified name; repeat to batch lookups")
+    parser.add_argument("--member", action="append", help="Limit API evidence to named members")
     args = parser.parse_args()
+    if args.describe_class:
+        results = [describe_api(selector, args.member) for selector in args.describe_class]
+        print(json.dumps({"status": all(item["status"] for item in results), "classes": results}, ensure_ascii=False))
+        return 0 if all(item["status"] for item in results) else 2
     source = Path(args.source_path)
     if not source.is_file():
         print(json.dumps({