arango-query-core 0.2.0__tar.gz → 0.2.2__tar.gz

arango_query_core-0.2.2/.cursor/rules/fix-upstream-dont-fork.mdc

@@ -0,0 +1,104 @@
+---
+description: When a library we own lacks something or gets it wrong, fix it in the library or file it there; a workaround in the consumer is temporary, marked and tracked
+alwaysApply: true
+---
+
+# Fix Upstream, Don't Fork
+
+> **Scope:** Any code that depends on a library we own — arango-sparql-py,
+> arango-query-core, r2g / r2g-arango, arango-schema-analyzer, arango-cypher-py,
+> arango-entity-resolution, or any other library the team maintains. Every one of
+> these is also a consumer of the others, so this applies inside the libraries too.
+
+> **"We own the library. A gap in it is an issue there, not a fork here."**
+
+Written after a 2026-10-15 finding in contextual-data-fabric: its English→SPARQL
+translator was never the library's. In July, arango-sparql-py could only check a
+generated query against one schema, so the consumer took the library's model client
+and wrote its own prompt, check and repair loop around it. That was a reasonable
+call — but no library issue was filed and nothing in the code said it was
+temporary. When the shared engine gained the seam the consumer needed, nobody
+noticed. Three months later there were three implementations, the design record
+still said the engine was reused, and the library's docstring named a function the
+consumer never imported.
+
+The same audit found the pattern again around arango-entity-resolution: a consumer
+guard that copies the resolver's checks line for line, configuration defects worked
+around in a comment instead of filed, and a service that declares the library as a
+dependency, says in its docstring that it runs the library's pipeline, and imports
+none of it.
+
+## When an owned library falls short
+
+| Do, in this order | Not |
+| --- | --- |
+| 1. **Check it isn't already there** — `main`, open branches, and the other org's copy | Assume the version you have pinned is the latest |
+| 2. **Fix it in the library** — we own it; open the pull request there | Patch around it here because this is the repo you have open |
+| 3. **Or file it there** — a bug or feature request on the repo that leads, saying what the consumer needs and why | File it on the mirror, or mention it only in this repo's pull request |
+| 4. **Only if this repo cannot wait** for a library release and a pin bump — a temporary workaround, held to the rules below | A permanent workaround nobody can find |
+
+**Which repo leads.** Most of these libraries exist under two owners, and which one
+leads has changed during 2026. Do not trust the remotes of your clone — a fresh
+clone has only the URL you were handed. The repository with recent pull requests is
+the one that leads:
+
+```sh
+gh pr list --repo <owner>/<name> --state all --limit 5
+```
+
+Run it against both candidates. If neither has recent pull requests, ask.
+
+## A workaround that is allowed
+
+- **Behind the seam the library would provide**, so removing it touches one place:
+  an adapter, or a wrapper with the library's own shape.
+- **Marked where it lives**, on one line at the code that works around the library:
+
+  ```python
+  # upstream: <org>/arango-sparql-py#<n> — remove when the engine accepts a caller's validator
+  ```
+
+  Where a repo has `tests/test_upstream_markers.py`, that test holds the format: an
+  `owner/repo#number` issue a person can open, and a `remove when` condition someone
+  can check. The shared-memory installers place this rule but not the test, so a
+  repo without it copies it from arango-shared-memory
+  `templates/tests/test_upstream_markers.py`.
+- **Listed in this repo's known-debt issue**, if it keeps one, with the same link.
+- **Removed in the pin bump that ships the fix**, not in a later cleanup: when you
+  bump a pin, search for `upstream:` markers that name that library.
+
+## What counts as a fork
+
+| Fork | Why it costs |
+| --- | --- |
+| Taking a library's low-level piece (a client, a parser) and writing your own version of its main entry point around it | Fixes and new capabilities land in the library's version and never reach yours |
+| Copying library code into the consumer | The two copies drift |
+| Patching the library at runtime | The next pin bump breaks it without a word |
+| Reaching past the library's public API into its internals | Internals move without a release note |
+| Defining a public function or class with the same name and job as one the library exports | Readers take one for the other |
+| Declaring a library as a dependency and reimplementing what you would have called | The dependency says one thing and the code does another |
+| Holding a pin back to dodge a bug, with no issue | Nobody knows when it can move |
+
+A fork that is deliberate and permanent — the consumer needs something the library
+should not hold — is a **design record (ADR) in the consumer** plus an **issue in the
+library** for the seam that would let the two share the rest. It is never a silent
+decision.
+
+## The other side: claims about the other repo
+
+A library that says a consumer uses it ("this is what the fabric calls") must be able
+to point at the consumer's import. A consumer that says it uses a library ("runs the
+entity-resolution pipeline") must import it. If either cannot, the claim is a plan,
+and it is written as one.
+
+## Anti-Patterns
+
+| Anti-Pattern | Consequence |
+| --- | --- |
+| "The library can't do X, so I'll write X here" | A fork nobody tracks |
+| A workaround with no `upstream:` marker | Nobody removes it when the fix ships |
+| An issue filed in the consumer instead of the library | The library's maintainers never see it |
+| A library defect documented only in a config comment | The next consumer hits it too |
+| "It's our library, I'll fix it there later" | Later is after the third implementation |
+
+**We own the library: fix it there, or say where it will be fixed.**

{arango_query_core-0.2.0 → arango_query_core-0.2.2}/CHANGELOG.md

@@ -6,6 +6,53 @@ exact versions (contextual-data-fabric CC-9) and re-run their golden /
 eval suites on every bump — pre-1.0, **minor** bumps may break the API
 and this file must say so explicitly.
 
+## [0.2.2] - 2026-10-21
+
+### Fixed
+
+- **Traversals no longer hint an array-expanded edge index.** `resolve_indexes`
+  treated any edge index led by `_from` / `_to` as a vertex-centric index, so
+  `[_from, type, toLabels[*]]` (r2g's opt-in `LpgLayout.index_edge_labels`
+  shape) could become arango-cypher-py's traversal `indexHint`. A persistent
+  index stores one entry per array element and a traversal scans all of them,
+  so the hinted traversal returned each edge once per label -- inflated counts,
+  no error (measured on ArangoDB 3.12.9: 20x the rows at one hop, 400x at two).
+  Such an index is now never `vci`, even with an explicit `vci: true` flag. With
+  only that index, arango-cypher-py reports a missing VCI instead of hinting it;
+  next to a flat `[_from, type]` index, the flat one is hinted, whatever the
+  order.
+- **The schema analyzer's verdict is honored.** When a relationship mapping
+  carries arangodb-schema-analyzer's `vci.indexLevel.indexes[].traversalSafe:
+  false` (analyzer 0.15.2+), that index is not traversal-safe, whatever its
+  shape. Older exports carry no verdict; the local array-expansion check still
+  applies to them.
+
+### Added
+
+- `IndexInfo.traversal_safe` (default `True`): False when a traversal must not
+  use the index. Additive; existing callers are unaffected.
+
+## [0.2.1] - 2026-10-16
+
+### Fixed
+
+- **OWL import keeps property names.** `owl_turtle.turtle_to_mapping` cut
+  every datatype-property name at its last underscore — a rule meant for the
+  `:<REL>_<prop>` relationship properties `mapping_to_turtle` writes — so
+  `file_name` imported as `name` and `account_id` as `id`, including on a
+  round trip of this library's own export. Entity properties now keep their
+  full name; relationship properties lose exactly their `<REL>_` prefix.
+- **Shared fields reach every class.** Both importers (`turtle_to_mapping`
+  and the rdflib-based `parse_owl_with_rdflib`) dropped a property whose
+  `rdfs:domain` is an `owl:unionOf` list — arangodb-schema-analyzer
+  0.15.1's form for a field several classes share — and the rdflib one read
+  only the first of several domains. Each member / domain now gets the field,
+  and the anonymous union class is no longer imported as an entity.
+- **Stored field names.** `phys:attributeName` (analyzer 0.15.1) now maps a
+  property to its stored field in the physical mapping
+  (`properties.<name>.field`), so a sanitized or renamed field (`file-name`,
+  `page_count`) resolves to the attribute that holds it.
+
 ## [0.2.0] - 2026-08-23
 
 ### BREAKING

{arango_query_core-0.2.0 → arango_query_core-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: arango-query-core
-Version: 0.2.0
+Version: 0.2.2
 Summary: Shared conceptual-model and NL substrate for ArangoDB query transpilers (arango-cypher-py, arango-sparql-py)
 Project-URL: Repository, https://github.com/ArthurKeen/arango-query-core
 Project-URL: Changelog, https://github.com/ArthurKeen/arango-query-core/blob/main/CHANGELOG.md

{arango_query_core-0.2.0 → arango_query_core-0.2.2}/arango_query_core/mapping.py

@@ -87,9 +87,49 @@ def _is_structural_vci(index_type: str, fields: tuple[str, ...]) -> bool:
     return any(f not in _SYSTEM_INDEX_FIELDS for f in fields)
 
 
+def _has_array_expansion(fields: tuple[str, ...]) -> bool:
+    """True when any indexed field is an array expansion (``labels[*]``).
+
+    A persistent index stores one entry per array element, and a traversal
+    scans every entry under the ``_from`` / ``_to`` prefix, so a traversal that
+    uses such an index returns each edge once per element -- inflated counts,
+    no error. The index is still correct for a pattern-match lookup
+    (``FOR e IN edges FILTER e._from == ...``), but never for a traversal hint.
+    """
+    return any("[*]" in f for f in fields)
+
+
+def _analyzer_unsafe_index_fields(mapping: JsonObj) -> set[tuple[str, ...]]:
+    """Field tuples the schema analyzer marked ``traversalSafe: false``.
+
+    arangodb-schema-analyzer (0.15.2+) records its verdict per relationship
+    under ``vci.indexLevel.indexes``; ``traversalSafe`` is present only when
+    false. Older exports carry no verdict, so absence means "no opinion" and
+    the local :func:`_has_array_expansion` check still applies.
+    """
+    vci = mapping.get("vci")
+    index_level = vci.get("indexLevel") if isinstance(vci, dict) else None
+    indexes = index_level.get("indexes") if isinstance(index_level, dict) else None
+    if not isinstance(indexes, list):
+        return set()
+    unsafe: set[tuple[str, ...]] = set()
+    for entry in indexes:
+        if not isinstance(entry, dict) or entry.get("traversalSafe") is not False:
+            continue
+        fields = entry.get("fields")
+        if isinstance(fields, list):
+            unsafe.add(tuple(str(f) for f in fields))
+    return unsafe
+
+
 @dataclass(frozen=True)
 class IndexInfo:
-    """Metadata for a single index on a collection."""
+    """Metadata for a single index on a collection.
+
+    ``traversal_safe`` is False when a traversal must not use the index
+    (array-expanded fields, or the schema analyzer's ``traversalSafe: false``
+    verdict). Such an index is never ``vci``, whatever its shape or flags.
+    """
 
     type: str
     fields: tuple[str, ...]
@@ -98,6 +138,7 @@ class IndexInfo:
     name: str = ""
     vci: bool = False
     deduplicate: bool = False
+    traversal_safe: bool = True
 
 
 @dataclass(frozen=True)
@@ -573,6 +614,7 @@ class MappingResolver:
         if not isinstance(indexes_raw, list):
             return []
 
+        unsafe = _analyzer_unsafe_index_fields(mapping)
         result: list[IndexInfo] = []
         for idx in indexes_raw:
             if not isinstance(idx, dict):
@@ -583,6 +625,8 @@ class MappingResolver:
             else:
                 continue
             index_type = str(idx.get("type", "persistent"))
+            traversal_safe = fields not in unsafe and not _has_array_expansion(fields)
+            vci = bool(idx.get("vci", False)) or _is_structural_vci(index_type, fields)
             result.append(
                 IndexInfo(
                     type=index_type,
@@ -590,8 +634,9 @@ class MappingResolver:
                     unique=bool(idx.get("unique", False)),
                     sparse=bool(idx.get("sparse", False)),
                     name=str(idx.get("name", "")),
-                    vci=bool(idx.get("vci", False)) or _is_structural_vci(index_type, fields),
+                    vci=vci and traversal_safe,
                     deduplicate=bool(idx.get("deduplicate", False)),
+                    traversal_safe=traversal_safe,
                 )
             )
         return result

{arango_query_core-0.2.0 → arango_query_core-0.2.2}/arango_query_core/owl_rdflib.py

@@ -42,23 +42,30 @@ def parse_owl_with_rdflib(turtle_text: str) -> MappingBundle:
     entities: list[dict[str, Any]] = []
     entity_props: dict[str, list[dict[str, str]]] = {}
 
-    for cls in g.subjects(RDF.type, OWL.Class):
+    for cls in _named_classes(g, RDF, OWL):
         name = _local_name(cls)
         entities.append({"name": name, "labels": [name], "properties": []})
         entity_props[name] = []
 
     # ── Extract datatype properties ──────────────────────────────────
+    # A property's domain may be one class, several (each gets the field),
+    # or an owl:unionOf class expression — arangodb-schema-analyzer's form
+    # for a field several classes share. phys:attributeName names the
+    # stored field when it differs from the property name.
+    fields: dict[str, dict[str, str]] = {}
     for prop in g.subjects(RDF.type, OWL.DatatypeProperty):
         prop_name = _local_name(prop)
-        domain = g.value(prop, RDFS.domain)
         range_uri = g.value(prop, RDFS.range)
         prop_entry: dict[str, str] = {"name": prop_name}
         if range_uri:
             prop_entry["type"] = _xsd_to_simple(str(range_uri))
-        if domain:
-            domain_name = _local_name(domain)
-            if domain_name in entity_props:
-                entity_props[domain_name].append(prop_entry)
+        attribute = g.value(prop, PHYS.attributeName)
+        for domain_node in g.objects(prop, RDFS.domain):
+            for domain_name in _domain_names(g, domain_node, OWL):
+                if domain_name in entity_props:
+                    entity_props[domain_name].append(prop_entry)
+                    if attribute:
+                        fields.setdefault(domain_name, {})[prop_name] = str(attribute)
 
     for entity in entities:
         entity["properties"] = entity_props.get(entity["name"], [])
@@ -82,7 +89,7 @@ def parse_owl_with_rdflib(turtle_text: str) -> MappingBundle:
     physical_entities: dict[str, dict[str, Any]] = {}
     physical_rels: dict[str, dict[str, Any]] = {}
 
-    for cls in g.subjects(RDF.type, OWL.Class):
+    for cls in _named_classes(g, RDF, OWL):
         name = _local_name(cls)
         coll = g.value(cls, PHYS.collectionName)
         style = g.value(cls, PHYS.style) or g.value(cls, PHYS.mappingStyle)
@@ -98,6 +105,8 @@ def parse_owl_with_rdflib(turtle_text: str) -> MappingBundle:
                 pm_entry["typeField"] = str(type_field)
             if type_value:
                 pm_entry["typeValue"] = str(type_value)
+            for prop_name, field in fields.get(name, {}).items():
+                pm_entry["properties"][prop_name] = {"field": field}
             physical_entities[name] = pm_entry
 
     for prop in g.subjects(RDF.type, OWL.ObjectProperty):
@@ -127,6 +136,27 @@ def parse_owl_with_rdflib(turtle_text: str) -> MappingBundle:
     )
 
 
+def _named_classes(g: Any, rdf: Any, owl: Any) -> list[Any]:
+    """Every ``owl:Class`` with an IRI. An anonymous class expression (the
+    ``[ a owl:Class ; owl:unionOf ( … ) ]`` of a shared field's domain) is not
+    an entity."""
+    import rdflib
+
+    return [c for c in g.subjects(rdf.type, owl.Class) if isinstance(c, rdflib.URIRef)]
+
+
+def _domain_names(g: Any, domain: Any, owl: Any) -> list[str]:
+    """Class names a ``rdfs:domain`` value covers: the class itself, or every
+    member of an ``owl:unionOf`` list."""
+    import rdflib
+    from rdflib.collection import Collection
+
+    if isinstance(domain, rdflib.BNode):
+        members = g.value(domain, owl.unionOf)
+        return [_local_name(m) for m in Collection(g, members)] if members is not None else []
+    return [_local_name(domain)]
+
+
 def _local_name(uri: Any) -> str:
     """Extract the local (fragment / last-path-segment) name from a URI."""
     s = str(uri)

{arango_query_core-0.2.0 → arango_query_core-0.2.2}/arango_query_core/owl_turtle.py

@@ -111,10 +111,21 @@ def mapping_to_turtle(bundle: MappingBundle) -> str:
 
 
 def turtle_to_mapping(turtle: str) -> MappingBundle:
-    """Parse an OWL/Turtle string into a MappingBundle."""
+    """Parse an OWL/Turtle string into a MappingBundle.
+
+    A line-oriented reader for the layout :func:`mapping_to_turtle` and
+    arangodb-schema-analyzer write (no rdflib needed; see
+    :mod:`.owl_rdflib` for arbitrary Turtle). A datatype property keeps its
+    full local name (``:file_name`` is ``file_name``); only a relationship
+    property written ``:<REL>_<prop>`` with ``rdfs:domain :<REL>`` loses the
+    ``<REL>_`` prefix. Its domain may be one class, several ``rdfs:domain``
+    lines, or an ``owl:unionOf`` list (the analyzer's form for a field
+    several classes share), and ``phys:attributeName`` names the stored
+    field when it differs from the property name.
+    """
     classes: dict[str, dict[str, str]] = {}
     obj_props: dict[str, dict[str, str]] = {}
-    data_props: list[dict[str, str]] = []
+    data_props: list[dict[str, Any]] = []
     annotations: dict[str, dict[str, str]] = {}
 
     current_subject: str | None = None
@@ -143,14 +154,20 @@ def turtle_to_mapping(turtle: str) -> MappingBundle:
         if m_dataprop:
             current_subject = m_dataprop.group(1)
             current_kind = "dataprop"
-            data_props.append({"name": current_subject})
+            data_props.append({"name": current_subject, "domains": []})
+            continue
+
+        m_union = re.match(r"rdfs:domain\s+\[.*owl:unionOf\s*\(([^)]*)\)", stripped)
+        if m_union:
+            if current_kind == "dataprop" and data_props:
+                data_props[-1]["domains"].extend(re.findall(r":(\w+)", m_union.group(1)))
             continue
 
         m_domain = re.match(r"rdfs:domain\s+:(\w+)", stripped)
         if m_domain:
             domain = m_domain.group(1)
             if current_kind == "dataprop" and data_props:
-                data_props[-1]["domain"] = domain
+                data_props[-1]["domains"].append(domain)
             elif current_kind == "objprop" and current_subject:
                 obj_props[current_subject]["domain"] = domain
             continue
@@ -164,7 +181,14 @@ def turtle_to_mapping(turtle: str) -> MappingBundle:
                 obj_props[current_subject]["range"] = rng.lstrip(":")
             continue
 
-        for annot in ("mappingStyle", "collectionName", "typeField", "typeValue", "edgeCollectionName"):
+        for annot in (
+            "mappingStyle",
+            "collectionName",
+            "typeField",
+            "typeValue",
+            "edgeCollectionName",
+            "attributeName",
+        ):
             m_a = re.match(rf':(\w+)\s+phys:{annot}\s+"([^"]+)"', stripped)
             if m_a:
                 subject = m_a.group(1)
@@ -174,14 +198,8 @@ def turtle_to_mapping(turtle: str) -> MappingBundle:
     entities_cs: list[dict[str, Any]] = []
     entities_pm: dict[str, dict[str, Any]] = {}
     for name in classes:
-        props = [
-            {
-                "name": dp["name"].split("_")[-1] if "_" in dp["name"] else dp["name"],
-                "type": _from_xsd_type(dp.get("range", "xsd:string")),
-            }
-            for dp in data_props
-            if dp.get("domain") == name
-        ]
+        own = [dp for dp in data_props if name in dp["domains"]]
+        props = [{"name": dp["name"], "type": _from_xsd_type(dp.get("range", "xsd:string"))} for dp in own]
         entities_cs.append({"name": name, "labels": [name], "properties": props})
         ann = annotations.get(name, {})
         pm_entry: dict[str, Any] = {
@@ -191,6 +209,13 @@ def turtle_to_mapping(turtle: str) -> MappingBundle:
         if pm_entry["style"] == "LABEL":
             pm_entry["typeField"] = ann.get("typeField", "type")
             pm_entry["typeValue"] = ann.get("typeValue", name)
+        fields = {
+            dp["name"]: {"field": annotations[dp["name"]]["attributeName"]}
+            for dp in own
+            if annotations.get(dp["name"], {}).get("attributeName")
+        }
+        if fields:
+            pm_entry["properties"] = fields
         entities_pm[name] = pm_entry
 
     rels_cs: list[dict[str, Any]] = []
@@ -201,11 +226,12 @@ def turtle_to_mapping(turtle: str) -> MappingBundle:
         to_e = op.get("range", "Any")
         props = [
             {
-                "name": dp["name"].replace(f"{rtype}_", ""),
+                # Exactly the `<REL>_` prefix mapping_to_turtle adds, not every occurrence.
+                "name": dp["name"].removeprefix(f"{rtype}_"),
                 "type": _from_xsd_type(dp.get("range", "xsd:string")),
             }
             for dp in data_props
-            if dp.get("domain") == rtype
+            if rtype in dp["domains"]
         ]
         rels_cs.append({"type": rtype, "fromEntity": from_e, "toEntity": to_e, "properties": props})
         ann = annotations.get(rtype, {})

{arango_query_core-0.2.0 → arango_query_core-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arango-query-core"
-version = "0.2.0"
+version = "0.2.2"
 description = "Shared conceptual-model and NL substrate for ArangoDB query transpilers (arango-cypher-py, arango-sparql-py)"
 readme = "README.md"
 license = { file = "LICENSE" }

{arango_query_core-0.2.0 → arango_query_core-0.2.2}/tests/test_mapping_vci_detection.py

@@ -86,3 +86,61 @@ class TestResolverStructuralVci:
     def test_no_indexes_means_no_vci(self) -> None:
         b = _bundle_with_edge_indexes([])
         assert MappingResolver(b).has_vci("REL") is False
+
+
+class TestArrayExpandedIndexIsNotTraversalSafe:
+    """An edge index with an array-expanded field must never be hinted in a traversal.
+
+    A persistent index stores one entry per array element and a traversal scans
+    every entry under the _from/_to prefix, so ``[_from, type, toLabels[*]]``
+    returns each edge once per label (measured on ArangoDB 3.12.9: 20 labels
+    per edge -> 20x the rows at one hop, 400x at two). r2g provisions this shape
+    when ``LpgLayout.index_edge_labels`` is on.
+    """
+
+    def test_array_expanded_index_is_not_vci(self) -> None:
+        b = _bundle_with_edge_indexes(
+            [{"type": "persistent", "fields": ["_from", "type", "toLabels[*]"], "name": "lbl"}]
+        )
+        r = MappingResolver(b)
+        (idx,) = r.resolve_indexes("REL")
+        assert idx.traversal_safe is False
+        assert idx.vci is False
+        assert r.has_vci("REL") is False
+
+    def test_explicit_flag_does_not_override_array_expansion(self) -> None:
+        b = _bundle_with_edge_indexes(
+            [{"type": "persistent", "fields": ["_from", "toLabels[*]"], "name": "lbl", "vci": True}]
+        )
+        assert MappingResolver(b).has_vci("REL") is False
+
+    def test_safe_index_still_vci_alongside_risky_one(self) -> None:
+        b = _bundle_with_edge_indexes(
+            [
+                {"type": "persistent", "fields": ["_from", "type"], "name": "flat"},
+                {"type": "persistent", "fields": ["_from", "type", "toLabels[*]"], "name": "lbl"},
+            ]
+        )
+        by_name = {i.name: i for i in MappingResolver(b).resolve_indexes("REL")}
+        assert by_name["flat"].vci is True and by_name["flat"].traversal_safe is True
+        assert by_name["lbl"].vci is False
+
+    def test_analyzer_verdict_is_honored(self) -> None:
+        # The schema analyzer's traversalSafe: false wins even for a shape the
+        # local check would accept -- its verdict is the source of truth.
+        b = _bundle_with_edge_indexes([{"type": "persistent", "fields": ["_from", "type"], "name": "flat"}])
+        b.physical_mapping["relationships"]["REL"]["vci"] = {
+            "indexLevel": {"indexes": [{"fields": ["_from", "type"], "traversalSafe": False}]}
+        }
+        (idx,) = MappingResolver(b).resolve_indexes("REL")
+        assert idx.traversal_safe is False and idx.vci is False
+
+    def test_analyzer_block_without_verdict_keeps_safe_index(self) -> None:
+        # Exports before analyzer 0.15.2 have a vci block but no traversalSafe:
+        # absence is "no opinion", not "unsafe".
+        b = _bundle_with_edge_indexes([{"type": "persistent", "fields": ["_from", "type"], "name": "flat"}])
+        b.physical_mapping["relationships"]["REL"]["vci"] = {
+            "indexLevel": {"indexes": [{"fields": ["_from", "type"], "discriminatorFields": ["type"]}]}
+        }
+        (idx,) = MappingResolver(b).resolve_indexes("REL")
+        assert idx.traversal_safe is True and idx.vci is True

{arango_query_core-0.2.0 → arango_query_core-0.2.2}/tests/test_owl_rdflib.py

@@ -189,3 +189,53 @@ class TestImportError:
         with patch("builtins.__import__", side_effect=mock_import):
             with pytest.raises(ImportError, match="rdflib is required"):
                 parse_owl_with_rdflib(MINIMAL_OWL)
+
+
+ANALYZER_OWL = """\
+@prefix : <http://arangodb.com/schema/hybrid#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+@prefix phys: <http://arangodb.com/schema/physical#> .
+
+:Chunk a owl:Class ; phys:collectionName "chunks" .
+:Document a owl:Class ; phys:collectionName "documents" .
+:Note a owl:Class ; phys:collectionName "notes" .
+
+:content a owl:DatatypeProperty ;
+  rdfs:domain [ a owl:Class ; owl:unionOf ( :Chunk :Document ) ] .
+:file_name a owl:DatatypeProperty ;
+  rdfs:domain :Document ;
+  phys:attributeName "file-name" .
+:tag a owl:DatatypeProperty ;
+  rdfs:domain :Document , :Note ;
+  rdfs:range xsd:string .
+"""
+
+
+def _names(bundle, entity):
+    return sorted(
+        p["name"]
+        for e in bundle.conceptual_schema["entities"]
+        if e["name"] == entity
+        for p in e["properties"]
+    )
+
+
+def test_a_union_domain_gives_the_field_to_every_member():
+    bundle = parse_owl_with_rdflib(ANALYZER_OWL)
+    # The anonymous union class is not an entity of its own.
+    assert sorted(e["name"] for e in bundle.conceptual_schema["entities"]) == ["Chunk", "Document", "Note"]
+    assert _names(bundle, "Chunk") == ["content"]
+    assert _names(bundle, "Document") == ["content", "file_name", "tag"]
+
+
+def test_several_domains_each_get_the_field():
+    assert _names(parse_owl_with_rdflib(ANALYZER_OWL), "Note") == ["tag"]
+
+
+def test_attribute_name_becomes_the_physical_field():
+    bundle = parse_owl_with_rdflib(ANALYZER_OWL)
+    assert bundle.physical_mapping["entities"]["Document"]["properties"] == {
+        "file_name": {"field": "file-name"}
+    }

{arango_query_core-0.2.0 → arango_query_core-0.2.2}/tests/test_owl_turtle_roundtrip.py

@@ -164,3 +164,91 @@ def test_export_label_style() -> None:
     assert pm_p["style"] == "LABEL"
     assert pm_p["typeField"] == "type"
     assert pm_p["typeValue"] == "Person"
+
+
+# ---------------------------------------------------------------------------
+# Property names, shared fields and stored-field names (import fixes)
+# ---------------------------------------------------------------------------
+
+# The layout arangodb-schema-analyzer >= 0.15.1 writes: a field two classes
+# share has an owl:unionOf domain; a renamed or sanitized field carries its
+# stored name in phys:attributeName.
+ANALYZER_OWL = """\
+@prefix : <http://arangodb.com/schema/hybrid#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+@prefix phys: <http://arangodb.com/schema/physical#> .
+
+:Chunk a owl:Class ;
+  rdfs:label "Chunk" .
+:Chunk phys:mappingStyle "COLLECTION" .
+:Chunk phys:collectionName "chunks" .
+
+:Document a owl:Class ;
+  rdfs:label "Document" .
+:Document phys:mappingStyle "COLLECTION" .
+:Document phys:collectionName "documents" .
+
+:content a owl:DatatypeProperty ;
+  rdfs:label "content" ;
+  rdfs:domain [ a owl:Class ; owl:unionOf ( :Chunk :Document ) ] .
+
+:file_name a owl:DatatypeProperty ;
+  rdfs:label "file-name" ;
+  rdfs:domain :Document .
+:file_name phys:attributeName "file-name" .
+
+:page_count a owl:DatatypeProperty ;
+  rdfs:label "page_count" ;
+  rdfs:domain :Document ;
+  rdfs:range xsd:integer .
+"""
+
+
+def _props(bundle: MappingBundle, entity: str) -> list[str]:
+    return [
+        p["name"]
+        for e in bundle.conceptual_schema["entities"]
+        if e["name"] == entity
+        for p in e["properties"]
+    ]
+
+
+def test_snake_case_entity_properties_keep_their_names(simple_bundle: MappingBundle) -> None:
+    """Regression: every name was cut at its last underscore (file_name -> name)."""
+    simple_bundle.conceptual_schema["entities"][0]["properties"].append(
+        {"name": "account_id", "type": "string"}
+    )
+    back = turtle_to_mapping(mapping_to_turtle(simple_bundle))
+    assert _props(back, "Person") == ["name", "age", "account_id"]
+
+
+def test_relationship_properties_lose_only_their_prefix(simple_bundle: MappingBundle) -> None:
+    simple_bundle.conceptual_schema["relationships"][0]["properties"] = [
+        {"name": "role_name", "type": "string"}
+    ]
+    back = turtle_to_mapping(mapping_to_turtle(simple_bundle))
+    (rel,) = back.conceptual_schema["relationships"]
+    assert [p["name"] for p in rel["properties"]] == ["role_name"]
+
+
+def test_a_field_with_a_union_domain_belongs_to_every_member() -> None:
+    bundle = turtle_to_mapping(ANALYZER_OWL)
+    assert _props(bundle, "Chunk") == ["content"]
+    assert _props(bundle, "Document") == ["content", "file_name", "page_count"]
+
+
+def test_attribute_name_maps_the_property_to_its_stored_field() -> None:
+    bundle = turtle_to_mapping(ANALYZER_OWL)
+    assert bundle.physical_mapping["entities"]["Document"]["properties"] == {
+        "file_name": {"field": "file-name"}
+    }
+    assert "properties" not in bundle.physical_mapping["entities"]["Chunk"]
+
+
+def test_a_property_declared_once_per_domain_reaches_each(simple_bundle: MappingBundle) -> None:
+    """mapping_to_turtle writes one block per entity for a shared name."""
+    simple_bundle.conceptual_schema["entities"][1]["properties"].append({"name": "name", "type": "string"})
+    back = turtle_to_mapping(mapping_to_turtle(simple_bundle))
+    assert "name" in _props(back, "Person") and "name" in _props(back, "Movie")

arango_query_core-0.2.2/tests/test_upstream_markers.py

@@ -0,0 +1,173 @@
+"""A workaround for a library we own names its upstream issue
+(`.cursor/rules/fix-upstream-dont-fork.mdc`).
+
+A gap in an owned library is fixed or filed in that library. When this repo
+cannot wait for the release, the workaround is allowed only while it is marked
+where it lives::
+
+    # upstream: <owner>/<repo>#<n> — remove when <condition>
+
+so the pin bump that ships the fix can find it. This holds the marker's shape in
+every scanned file: an issue a person can open, and a condition someone can
+check. Whether that issue is still open needs the network, so it is not checked
+here.
+
+Shared source: arango-shared-memory ``templates/tests/test_upstream_markers.py``.
+Copy changes back there so every repository keeps the same check.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[1]
+RULE = ROOT / ".cursor" / "rules" / "fix-upstream-dont-fork.mdc"
+
+#: Files whose comments start with ``#``.
+SCANNED_SUFFIXES = frozenset({".py", ".sh", ".yml", ".yaml", ".toml", ".cfg"})
+SCANNED_NAMES = frozenset({"Makefile", "Dockerfile"})
+#: Directories that hold no code of ours. Hidden directories are skipped too,
+#: except ``.github``, where CI steps can work around a library.
+SKIPPED_DIRS = frozenset(
+    {
+        "__pycache__",
+        "build",
+        "dist",
+        "node_modules",
+        "site-packages",
+        "venv",
+    }
+)
+KEPT_HIDDEN_DIRS = frozenset({".github"})
+
+#: Any comment that claims to be a marker, however it is written.
+MARKER = re.compile(r"#\s*upstream\s*:(?P<rest>.*)$", re.IGNORECASE)
+#: What a marker must say: an issue (owner/repo#n), then when to remove it.
+WELL_FORMED = re.compile(
+    r"^\s*(?P<repo>[A-Za-z0-9][\w.-]*/[A-Za-z0-9][\w.-]*)#(?P<issue>[1-9]\d*)"
+    r"\s+(?:—|–|--?)\s+remove when\s+(?P<when>\S.*?)\s*$"
+)
+
+
+def marker_problems(text: str, where: str) -> list[str]:
+    """Each malformed ``upstream:`` marker in ``text``, as ``where:line: why``."""
+    problems = []
+    for number, line in enumerate(text.splitlines(), start=1):
+        found = MARKER.search(line)
+        if found is None:
+            continue
+        if WELL_FORMED.match(found.group("rest")) is None:
+            problems.append(
+                f"{where}:{number}: {line.strip()!r} — write it as "
+                "'# upstream: <owner>/<repo>#<n> — remove when <condition>'"
+            )
+    return problems
+
+
+def _skipped_dir(name: str) -> bool:
+    if name in SKIPPED_DIRS or name.endswith(".egg-info"):
+        return True
+    return name.startswith(".") and name not in KEPT_HIDDEN_DIRS
+
+
+def _skipped(relative: Path) -> bool:
+    return any(_skipped_dir(part) for part in relative.parts[:-1])
+
+
+def _scanned_files() -> list[Path]:
+    files = []
+    # os.walk with pruning, so .git, virtualenvs and node_modules are never entered.
+    for current, dirs, names in os.walk(ROOT):
+        dirs[:] = sorted(name for name in dirs if not _skipped_dir(name))
+        for name in sorted(names):
+            path = Path(current) / name
+            if path.suffix in SCANNED_SUFFIXES or name in SCANNED_NAMES:
+                files.append(path)
+    # This file states malformed markers on purpose, to prove they are caught.
+    return [path for path in files if path.resolve() != Path(__file__).resolve()]
+
+
+# -- the tree --------------------------------------------------------------------
+
+
+def test_every_upstream_marker_names_an_issue_and_when_to_remove_it() -> None:
+    problems = []
+    for path in _scanned_files():
+        text = path.read_text(encoding="utf-8", errors="replace")
+        problems.extend(marker_problems(text, str(path.relative_to(ROOT))))
+    assert not problems, "malformed upstream markers:\n  " + "\n  ".join(problems)
+
+
+def test_the_scan_reaches_this_repositorys_code() -> None:
+    """A scan that silently finds nothing would pass forever."""
+    scanned = {path.relative_to(ROOT).parts[0] for path in _scanned_files()}
+    assert "tests" in scanned
+    assert len(_scanned_files()) > 1
+
+
+@pytest.mark.parametrize(
+    ("relative", "skipped"),
+    [
+        ("src/pkg/module.py", False),
+        (".github/workflows/ci.yml", False),
+        (".venv/lib/python3.11/site-packages/x.py", True),
+        ("pkg.egg-info/PKG-INFO.py", True),
+        ("frontend/node_modules/x/setup.py", True),
+        (".claude/hooks/x.py", True),
+    ],
+)
+def test_the_scan_skips_only_what_is_not_ours(relative: str, skipped: bool) -> None:
+    assert _skipped(Path(relative)) is skipped
+
+
+# -- the check itself ------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "line",
+    [
+        "# upstream: ArthurKeen/arango-sparql-py#123 — remove when the engine takes a validator",
+        "x = build()  # upstream: arango-solutions-org/r2g-arango#7 -- remove when 0.7 ships",
+        "    # upstream: org/arango-query-core#42 – remove when LabelIndex accepts aliases",
+        "  run: make gate  # upstream: org/arango-cypher#9 - remove when the pin moves",
+    ],
+)
+def test_a_well_formed_marker_passes(line: str) -> None:
+    assert marker_problems(line, "example") == []
+
+
+@pytest.mark.parametrize(
+    ("line", "missing"),
+    [
+        ("# upstream: TODO file an issue", "no issue at all"),
+        ("# upstream: arango-sparql-py#12 — remove when fixed", "no owner"),
+        ("# upstream: org/arango-sparql-py — remove when fixed", "no issue number"),
+        ("# upstream: org/arango-sparql-py#0 — remove when fixed", "issue zero"),
+        ("# upstream: org/arango-sparql-py#12", "no removal condition"),
+        ("# upstream: org/arango-sparql-py#12 — remove when ", "an empty condition"),
+        ("# Upstream: org/arango-sparql-py#12 remove when fixed", "no separator"),
+        ("#upstream:https://github.com/org/arango-sparql-py/issues/12", "a URL, not owner/repo#n"),
+    ],
+)
+def test_a_malformed_marker_is_named_with_where_it_is(line: str, missing: str) -> None:
+    problems = marker_problems(f"first line\n{line}\n", "src/example.py")
+    assert len(problems) == 1, f"{missing}: {problems}"
+    assert problems[0].startswith("src/example.py:2: ")
+
+
+def test_a_line_that_only_mentions_upstream_is_not_a_marker() -> None:
+    text = "# fixed upstream in 0.6.1\n# the upstream repository leads\nupstream = 'x'\n"
+    assert marker_problems(text, "example") == []
+
+
+# -- the rule says what this test holds ------------------------------------------
+
+
+def test_the_rule_names_this_test_and_the_marker_format() -> None:
+    rule = RULE.read_text(encoding="utf-8")
+    assert "tests/test_upstream_markers.py" in rule
+    assert "# upstream: <org>/" in rule and "remove when" in rule

arango_query_core-0.2.0/.claude/settings.json

@@ -1,8 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(gh run *)",
-      "Bash(git worktree *)"
-    ]
-  }
-}