docs/hexa/mcp/modules/hexa.check_matches.json

{
  "module": "hexa.check_matches",
  "content": {
    "path": "hexa.check_matches",
    "docstring": "# Summary\n\nVerify that two hexa representations agree.\n\n``check_matches`` parses two representations — one YAML spec and/or ABC Python\nmodule each — and reports whether they describe the same port tree.\n\n---\n# Notes\n\n- Uses ``PortNode.diff`` to produce human-readable difference strings.",
    "objects": {
      "PortNode": {
        "name": "PortNode",
        "kind": "class",
        "path": "hexa.check_matches.PortNode",
        "signature": "PortNode(name: str, port_cls: str, kind: str = 'leaf', attributes: dict[str, ConfigValue] = dict(), children: list[PortNode] = list(), methods: dict[str, MethodSpec] = dict())",
        "docstring": "A node in the hexa port tree.\n\nEach node is a leaf (no children), a port (has nested port slots), or the\nparent root of the tree. Every node carries a concrete typed shape derived\nfrom an ABC class name.\n\nAttributes:\n    name (str):\n        Slot name, e.g. ``\"parser\"``, ``\"amount_balance\"``.\n\n    port_cls (str):\n        ABC class name that gives this port its shape, e.g.\n        ``\"TransactionParserPort\"``.  Every port has a concrete typed shape.\n\n    kind (str):\n        One of ``\"leaf\"``, ``\"port\"``, or ``\"parent\"``.\n        - ``\"leaf\"``: no children (e.g. ``NumberPort``)\n        - ``\"port\"``: has children (e.g. ``TransactionParserPort``)\n        - ``\"parent\"``: the root of the tree (e.g. ``ExtractionPipeline``)\n\n    attributes (dict[str, ConfigValue]):\n        Annotated attributes: ``name -> type_expr`` for scalars, or a\n        nested ``dict`` of sub-attributes (a struct) for grouped values.\n\n    children (list[PortNode]):\n        Nested port slots.\n\n    methods (dict[str, MethodSpec]):\n        Abstract methods keyed by method name.",
        "members": {
          "name": {
            "name": "name",
            "kind": "attribute",
            "path": "hexa.check_matches.PortNode.name",
            "signature": null,
            "docstring": null
          },
          "port_cls": {
            "name": "port_cls",
            "kind": "attribute",
            "path": "hexa.check_matches.PortNode.port_cls",
            "signature": null,
            "docstring": null
          },
          "kind": {
            "name": "kind",
            "kind": "attribute",
            "path": "hexa.check_matches.PortNode.kind",
            "signature": null,
            "docstring": null
          },
          "attributes": {
            "name": "attributes",
            "kind": "attribute",
            "path": "hexa.check_matches.PortNode.attributes",
            "signature": null,
            "docstring": null
          },
          "children": {
            "name": "children",
            "kind": "attribute",
            "path": "hexa.check_matches.PortNode.children",
            "signature": null,
            "docstring": null
          },
          "methods": {
            "name": "methods",
            "kind": "attribute",
            "path": "hexa.check_matches.PortNode.methods",
            "signature": null,
            "docstring": null
          },
          "find": {
            "name": "find",
            "kind": "function",
            "path": "hexa.check_matches.PortNode.find",
            "signature": "find(name: str)",
            "docstring": "Find a direct child by slot name.\n\nArgs:\n    name (str):\n        Slot name of the child to look up.\n\nReturns:\n    PortNode | None:\n        The matching child node, or ``None`` if no child has that name."
          },
          "walk": {
            "name": "walk",
            "kind": "function",
            "path": "hexa.check_matches.PortNode.walk",
            "signature": "walk()",
            "docstring": "Return all nodes in depth-first order (self first).\n\nReturns:\n    list[PortNode]:\n        All nodes of the tree, self first, depth-first."
          },
          "diff": {
            "name": "diff",
            "kind": "function",
            "path": "hexa.check_matches.PortNode.diff",
            "signature": "diff(other: PortNode, path: str = '')",
            "docstring": "Return a list of human-readable difference strings.\n\nAn empty list means the trees are equal.\n\nArgs:\n    other (PortNode):\n        Tree to compare against.\n\n    path (str):\n        Path prefix used when recursing into nested nodes; defaults to\n        the root path.\n\nReturns:\n    list[str]:\n        Human-readable difference strings, one per discrepancy."
          }
        }
      },
      "parse_abc": {
        "name": "parse_abc",
        "kind": "function",
        "path": "hexa.check_matches.parse_abc",
        "signature": "parse_abc(module_or_path: str | Path | Any)",
        "docstring": "Parse an ABC Python module into a :class:`PortNode` tree.\n\nABC classes become port nodes.  A nested-struct attribute is expressed as a\n``@dataclass`` annotation on an ABC port (e.g. ``source: ExtractionSource``\nwhere ``ExtractionSource`` is a ``@dataclass``); the dataclass's fields are\nexpanded into a nested ``attributes`` entry.\n\nArgs:\n    module_or_path (str | Path | Any):\n        A file path to a ``.py`` file, a module import string, or a loaded\n        module.\n\nReturns:\n    PortNode:\n        The root node of the tree."
      },
      "parse_yaml": {
        "name": "parse_yaml",
        "kind": "function",
        "path": "hexa.check_matches.parse_yaml",
        "signature": "parse_yaml(path: str | Path)",
        "docstring": "Parse a hexa YAML spec file into a :class:`PortNode` tree.\n\nArgs:\n    path (str | Path):\n        Path to the ``.yaml`` file.\n\nReturns:\n    PortNode:\n        The root node of the parsed tree.\n\nRaises:\n    ValueError:\n        On structural errors in the YAML."
      },
      "check_matches": {
        "name": "check_matches",
        "kind": "function",
        "path": "hexa.check_matches.check_matches",
        "signature": "check_matches(path_a: str | Path, path_b: str | Path) -> bool | list[str]",
        "docstring": "Verify two representations agree.\n\nArgs:\n    path_a (str | Path):\n        Path to a ``.yaml`` or ``.py`` file.\n\n    path_b (str | Path):\n        Path to a ``.yaml`` or ``.py`` file.\n\nReturns:\n    bool | list[str]:\n        ``True`` if they match exactly, otherwise a list of difference\n        strings."
      }
    }
  }
}