periplus-map 0.2.1__py3-none-any.whl

periplus/contract/schema/pack-manifest.schema.json

@@ -0,0 +1,245 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://periplus.dev/schema/0/pack-manifest.schema.json",
+  "title": "Periplus pack manifest",
+  "description": "pack.yaml, one per pack directory. Holds the pack's identity, where having two answers is a conflict rather than a merge. Everything else in a pack is a contributed file and merges additively.",
+
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["pack", "version"],
+  "properties": {
+
+    "$schema": {
+      "type": "string",
+      "description": "The contract this manifest is written against, by the `$id` of the schema above. Allowed here because the top level refuses every key it does not declare, so a file carrying the key an editor reads would otherwise be invalid for saying which rules it follows. What the key claims is which contract the file was authored against; it does not claim that anything resolves the URL today."
+    },
+
+    "pack":    {"type": "string", "pattern": "^[a-z][a-z0-9_]*$"},
+    "version": {"type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$"},
+
+    "depends": {
+      "type": "array",
+      "items": {"type": "string", "pattern": "^[a-z][a-z0-9_]*$"},
+      "description": "Zero or more packs, forming a directed acyclic graph rather than a chain: Next.js sits on React and on the Node runtime at once. Because a graph has no single load order, contributions must merge additively and without depending on order. There are no kinds of pack — a root is one with nothing beneath it, and it need not be a language."
+    },
+
+    "detect": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["any_of"],
+      "description": "How a repository is recognised as needing this pack, so `periplus init` can prefill a pin the person then edits. Declared here and never in engine code: a third-party pack is detected exactly as a bundled one is, which is what makes a new stack a pack rather than a release. A pack that declares no detector is never suggested — owning an extension is not the same as being a stack anybody pins, and a language pack firing on every file with its extension would prefill noise into every settings file there is.",
+      "properties": {
+        "any_of": {
+          "type": "array",
+          "minItems": 1,
+          "description": "The alternatives, tried in the order written. A repository is Drupal if its composer.json requires Drupal core OR it has a docroot, so the block names its combining rule rather than leaving a bare list for a reader to guess at. An empty list detects nothing and is refused here, where the author sees it, rather than at the one call site that would notice.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["path"],
+            "description": "One alternative: a repository-relative path that must exist as a file, and optionally a literal substring of that file's text. `contains` is a substring and not a regular expression, because detection reads third-party pack data with no time limit around it and a substring has no backtracking cost. The path stays under the repository root — a signal that leaves it never fires, since a detector that reads outside the checkout turns a committed settings file into a readout of the machine that ran `init`. Both levels are closed: an author who writes `contain:` gets a refusal, not a detector that silently degrades to an existence check and fires on every repository in the language.",
+            "properties": {
+              "path":     {"type": "string"},
+              "contains": {"type": "string"}
+            }
+          }
+        }
+      }
+    },
+
+    "grammar": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "provider_version", "language", "grammar_version"],
+      "description": "Only a pack that owns a language declares this. A domain pack gets its grammars by depending on packs that own them, because a domain pack owning a language means every domain pack touching that language redeclares it and they drift.",
+      "properties": {
+        "provider":         {"enum": ["tree-sitter"]},
+        "provider_version": {"$ref": "#/$defs/exactVersion"},
+        "language":         {"type": "string"},
+        "grammar_version":  {"$ref": "#/$defs/exactVersion"},
+        "constant_access": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["node", "scope", "name"],
+          "description": "A class constant read as a call's or an attribute's argument: the tree node type of the access, the node types its first named child, the scope, may have, and the node types its last named child, the constant's name, may have. A scope that is a written name resolves as one. A scope whose text enclosing lists is the enclosing class, and any other scope stands for no text; without enclosing, no scope is. The argument then stands for the text the run read declared for that constant. A pack that reads the file type may declare it, and the first such pack in load order is used.",
+          "properties": {
+            "node":  {"type": "string", "minLength": 1},
+            "scope": {"type": "array", "items": {"type": "string"}, "minItems": 1},
+            "name":  {"type": "array", "items": {"type": "string"}, "minItems": 1},
+            "enclosing": {"type": "array", "items": {"type": "string"}, "minItems": 1}
+          }
+        },
+        "constant_declaration": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["node", "name", "value"],
+          "description": "A class constant declared in a class body: the tree node type of one declaration, the node types of its first named child, the name, and those of its last named child, the value. A value that is a text literal by the identity block's call literal keys is collected, under the full name of the enclosing type declaration and the constant's name.",
+          "properties": {
+            "node":  {"type": "string", "minLength": 1},
+            "name":  {"type": "array", "items": {"type": "string"}, "minItems": 1},
+            "value": {"type": "array", "items": {"type": "string"}, "minItems": 1}
+          }
+        }
+      },
+      "dependentRequired": {
+        "constant_access": ["constant_declaration"],
+        "constant_declaration": ["constant_access"]
+      }
+    },
+
+    "files": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "extends":        {"oneOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}]},
+        "extensions":     {"type": "array", "items": {"type": "string"}},
+        "add_extensions": {"type": "array", "items": {"type": "string"}},
+        "exclude":        {"type": "array", "items": {"type": "string"}},
+        "add_excludes":   {"type": "array", "items": {"type": "string"}},
+        "cache_key_includes": {"type": "array", "items": {"type": "string"}},
+        "types": {
+          "type": "object",
+          "propertyNames": {"pattern": "^[a-z][a-z0-9_.]*$"},
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["reader"],
+            "anyOf": [{"required": ["endings"]}, {"required": ["names"]}],
+            "if": {"properties": {"reader": {"const": "data"}}},
+            "then": {"required": ["format"]},
+            "else": {"not": {"required": ["format"]}},
+            "properties": {
+              "endings": {"type": "array", "items": {"type": "string", "pattern": "^\\.?[^./][^/]*$"}, "minItems": 1},
+              "names":   {"type": "array", "items": {"type": "string", "pattern": "^[^/]+$"}, "minItems": 1},
+              "reader":  {"enum": ["data", "text", "tree"]},
+              "format":  {"type": "string", "description": "The data format a type read as data is written in, by the name of one of the engine's data readers: yaml. Required with reader data and refused with any other reader. The short form extensions is read as yaml."},
+              "path_values": {
+                "type": "object",
+                "propertyNames": {"pattern": "^[a-z][a-z0-9_]*$"},
+                "additionalProperties": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["pattern", "template"],
+                  "properties": {
+                    "pattern":   {"type": "string"},
+                    "template":  {"type": "string"},
+                    "normalize": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["replace", "with"], "properties": {"replace": {"type": "string"}, "with": {"type": "string"}}}},
+                    "case":      {"enum": ["lower", "upper"]},
+                    "relative_to": {"type": "string", "description": "A folder name: the pattern is searched in the path below the deepest directory of that folder that holds the file, and the value is absent for a file no directory of it holds. A folder whose value holds ** is refused at load."}
+                  }
+                },
+                "description": "Values computed once per file of this type from its path from the project folder, forward slashes: the pattern is searched there and the template is filled from its named captures and the project's settings values, then normalize and case reshape it; a template naming a name that is neither, or both, is refused. A pattern that does not match leaves the value absent. Every rule on a file of this type may name the value in a template."
+              },
+              "sections": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["name", "open", "close"],
+                  "properties": {
+                    "name":  {"type": "string"},
+                    "open":  {"type": "string"},
+                    "close": {"type": "string"}
+                  }
+                },
+                "description": "Spans of the file's text a text rule does not read unless its match names the section under reads_sections. Found in one pass from the start: the earliest opening wins, the first listed on a tie, and the section runs to the end of the first closing match after it, or to the end of the file. In close, a braced name stands for the text the named capture of open matched, escaped."
+              },
+              "spans": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["name", "open", "balance"],
+                  "properties": {
+                    "name":    {"type": "string"},
+                    "open":    {"type": "string"},
+                    "balance": {"type": "array", "items": {"type": "string", "minLength": 1, "maxLength": 1}, "minItems": 2, "maxItems": 2}
+                  }
+                },
+                "description": "Regions of the file's text a text rule's value reads with from: {enclosing: <name>, capture: <capture>}. A span starts at each match of open outside the sections. From the end of that match, each balance[0] outside the sections counts one up and each balance[1] one down; the span ends after the closing character that brings the count to zero or below, or at the end of the file. Spans of one name nest."
+              },
+              "resolve": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "oneOf": [
+                    {"enum": ["bound_first_segment", "as_written"]},
+                    {"type": "object", "additionalProperties": false, "required": ["full_if_prefixed"], "properties": {"full_if_prefixed": {"type": "string", "minLength": 1}}},
+                    {"type": "object", "additionalProperties": false, "required": ["prefix_with"], "properties": {"prefix_with": {"type": "string", "minLength": 1}}},
+                    {"type": "object", "additionalProperties": false, "required": ["prefix_bare_with"], "properties": {"prefix_bare_with": {"type": "string", "minLength": 1}}}
+                  ]
+                },
+                "description": "The resolution steps an edge end of a text rule on a file of this type takes when the end declares none: see resolveStep in the pack file schema."
+              },
+              "separator": {"type": "string", "description": "The separator beside the file type's resolve."}
+            }
+          },
+          "description": "Each file type by name. An ending is matched against the end of a file name after a dot, with or without its own leading dot, and the longest ending any loaded pack claims wins; a whole file name claims a file without an ending. The reader says how a rule reads the file: data, text, or tree, which needs the pack's grammar. The short form extensions is one type named by each listed ending, read as a tree when the pack pins a grammar and as data otherwise."
+        }
+      },
+      "description": "Exclude is not boundary. A boundary file is unread but the things inside it can still be nodes, because first-party code names them. An excluded file does not exist as far as the map is concerned, not even as the target of a reference, and it is enforced at file selection before anything parses."
+    },
+
+    "folders": {
+      "type": "object",
+      "additionalProperties": {
+        "oneOf": [
+          {"type": "string"},
+          {"type": "array", "items": {"type": "string"}, "minItems": 1}
+        ]
+      },
+      "propertyNames": {"pattern": "^[a-z][a-z0-9_]*$"},
+      "description": "Named folders a rule refers to with `in:`. A rule never writes a path. The value is a default; the project settings file overrides it for one repository without touching a rule. A value may reference another folder in braces, because a module's own config lives inside whatever custom_module resolves to."
+    },
+
+    "identity": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "How this language composes a qualified name, folds case, and what it must never normalise. Shape not yet derived from enough packs to close.",
+      "properties": {
+        "call_arguments": {"type": "string", "description": "The tree field of a call that holds its arguments, read by an id or a reference end from {argument: N}. Default: arguments."},
+        "call_argument": {"type": "string", "description": "The tree node type that holds one argument of a call; its value is its last named child. Without it, each named child of the arguments field is one argument, a comment or other extra node left out."},
+        "call_argument_name": {"type": "string", "description": "The field of an argument that holds its name. A named argument is found by its name, not its position, and its value is its last named child."},
+        "call_literals": {"type": "array", "items": {"type": "string"}, "description": "The tree node types of a call argument's text literal. Without them, no argument is a text literal."},
+        "call_literal_content": {"type": "array", "items": {"type": "string"}, "description": "The tree node types of a text literal's text. A literal with a named child of any other type is not a text literal."},
+        "call_literal_delimiters": {"type": "array", "items": {"type": "string"}, "description": "The tree node types of a text literal's named children that are skipped, such as a quote the grammar names."}
+      }
+    },
+
+    "boundary": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["type", "ancestry", "names"],
+        "properties": {
+          "type":     {"type": "string", "minLength": 1, "description": "A node type this pack or a pack it depends on declares. The group's names live in its id namespace."},
+          "ancestry": {"type": "array", "items": {"type": "string", "minLength": 1}, "minItems": 1, "description": "The edge kinds whose edges carry descent toward a listed name."},
+          "names": {
+            "type": "object",
+            "additionalProperties": {"type": ["string", "null"]},
+            "description": "Each qualified name where the framework begins, with the node type that classifies a first-party descendant of it, any node type this pack or a pack it depends on declares, or null for none."
+          }
+        }
+      },
+      "description": "Named groups of the names where a framework begins. An edge end no rule found that lands on a listed name becomes a declared node this pack drew, with no location; the engine never reads that code. A boundary node enters the map because first-party code refers to it, never because a pack knows about it, so a listed name no edge reaches is not in the map. Every loaded pack's groups apply, and an id two packs list refuses the map."
+    },
+
+    "tables": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": {"type": "string", "minLength": 1}
+      },
+      "description": "Name tables by table name, each mapping a written name to a node name. A rule's lookup_last_segment_in step names a table this pack or a pack it depends on declares; this pack's table wins over a dependency's of the same name."
+    }
+  },
+
+  "$defs": {
+    "exactVersion": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Exact, never a range. Grammar node type names carry no stability guarantee across a minor release, so a range lets a rule that matched yesterday match nothing today, silently."
+    }
+  }
+}

periplus/contract/schema/project-settings.schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://periplus.dev/schema/0/project-settings.schema.json",
+  "title": "Periplus project settings",
+  "description": "periplus.settings.yml, at the root of the repository being mapped. Committed and reviewed like source. It is the only place a person edits anything the map depends on, and it holds what no pack can know. A general settings file holds what is true for a machine or a user; this one wins where they disagree.",
+
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["periplus_version"],
+  "properties": {
+
+    "periplus_version": {"type": "integer", "minimum": 0},
+
+    "packs": {
+      "type": "array",
+      "minItems": 1,
+      "items": {"type": "string", "pattern": "^[a-z][a-z0-9_]*@\\d+\\.\\d+\\.\\d+$"},
+      "description": "Named, not implied by what happens to be on disk. A pack shipped inside a downloaded module loads because this list names it, not because it is present — which is also the whole of the trust story for third-party packs. Not required: a project nobody has configured has no `packs` key at all, which is the file `periplus init` writes and the state `periplus status` exits 0 on. `minItems` is what keeps the other case refused — a key present and empty is a claim that no pack applies, which is a different statement and one no run should accept quietly."
+    },
+
+    "pack_paths": {
+      "type": "array",
+      "items": {"type": "string"},
+      "description": "Extra directories to resolve packs from, beside the ones the tool ships. A pack a person writes for their own repository is found the same way a bundled one is, or third-party packs are second-class by construction."
+    },
+
+    "folders": {
+      "type": "object",
+      "additionalProperties": {
+        "oneOf": [
+          {"type": "string"},
+          {"type": "array", "items": {"type": "string"}, "minItems": 1}
+        ]
+      },
+      "propertyNames": {"pattern": "^[a-z][a-z0-9_]*$"},
+      "description": "Overrides the pack's defaults for this repository. Exported configuration is the case that proves it: three real Drupal sites keep it in three different places, one of them computed in PHP at runtime."
+    },
+
+    "first_party": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "include": {"type": "array", "items": {"type": "string"}},
+        "exclude": {"type": "array", "items": {"type": "string"}}
+      },
+      "description": "Path-based, needing no pack, so a dependency published tomorrow still stops at the boundary. This is also where a dependency is deliberately promoted to first-party, which is the boundary mechanism under test: one line, no engine change."
+    },
+
+    "extensions": {
+      "type": "object",
+      "additionalProperties": {"type": "string"},
+      "description": "The last word over any pack. An extension can have no correct global meaning — .inc is PHP here and Pascal somewhere else — so the only place that settles is the project."
+    },
+
+    "values": {
+      "type": "object",
+      "additionalProperties": {"type": "string"},
+      "propertyNames": {"pattern": "^[a-z][a-z0-9_]*$"},
+      "description": "Named text values that no pack can know, such as the module path a project's packages sit under. Every template of every pack may name one as {name}, as it names a path value: a rule's id template, and the template of a file type's path value, so a path value can read {module}/{dir}. A name a loaded pack also gives as a path value, or that a rule captures, is refused when the map is made, and so is a path value template that names a value neither its pattern nor these values give."
+    },
+
+    "exclude":    {"type": "array", "items": {"type": "string"}},
+    "re_include": {
+      "type": "array", "items": {"type": "string"},
+      "description": "Takes back a pack's exclusion without forking the pack. It has to exist for the same reason the extension override does: a pack states a convention, and one repository is always the exception."
+    },
+
+    "accepted_unknowns": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "rule", "reason", "accepted_by", "accepted_on"],
+        "properties": {
+          "id":          {"type": "string"},
+          "rule":        {"type": "string", "description": "pack.rule_name, matching the `rule:` key of the rule that failed."},
+          "reason":      {"type": "string"},
+          "accepted_by": {"type": "string"},
+          "accepted_on": {"type": "string", "format": "date"}
+        }
+      },
+      "description": "Gaps accepted as permanent. Dynamic dispatch, a computed string, an id assembled at runtime. This cannot live in the map, which is generated and must never be hand-edited. Same shape as a lint suppression, and it is what lets an unresolved count reach zero and mean something."
+    }
+  }
+}

periplus/contract/spec/engine.md

@@ -0,0 +1,151 @@
+# The engine
+
+What the tool must do, in order, and what it must refuse. The four schemas in `schema/` are
+the machine-checkable half; this is the half a person builds against.
+
+Every requirement here comes from something that happened. Where a line exists because
+something broke, the measurement is beside it.
+
+## What the engine is
+
+A program that reads packs and a settings file, opens source files, and writes a map.
+
+It contains no knowledge of any language, framework, or file format. Every construct name,
+condition, id part and emit target comes from a pack. The test is mechanical: the string
+`php`, `go`, `drupal`, `twig` must not appear in the engine outside a comment.
+
+It is not a server, a daemon, a database, or a language server. It runs, writes a file, and
+exits.
+
+## The run, in order
+
+The order is not an implementation detail. Two steps of it are load-bearing and named as
+such below.
+
+### 1. Resolve settings
+
+Read the project settings file. It names the packs, and it may override any folder a pack
+declares. Absent settings is an error, not a default — the engine must not guess where a
+repository keeps its configuration.
+
+### 2. Resolve the pack graph, and build the type table
+
+**Before any source file is opened.** A pack may only name a type it declares or that a pack
+in its dependency graph declares; that check runs here, against zero source files, and a
+violation fails the run.
+
+Packs form a directed acyclic graph, not a chain. Contributions merge additively and without
+depending on order, because a graph has no single load order to appeal to. Two files
+declaring the same type is a conflict and fails. Two files contributing rules to one type is
+ordinary.
+
+There are no kinds of pack. A pack with nothing beneath it is a root and need not be a
+language. If any level were special, a third party could not occupy it.
+
+### 3. Select files
+
+From the folders each rule names, filtered by the extensions packs claim, minus every
+exclusion.
+
+Exclusion is not the boundary. A boundary file is unread and the things inside it may still
+be nodes, because first-party code names them. An excluded file does not exist as far as the
+map is concerned, not even as the target of a reference, and the check happens here, before
+anything parses. A settings file may exclude what a pack would read and re-include what a
+pack excluded; the project has the last word in both directions.
+
+### 4. Run source rules
+
+Every rule whose `reads` is `file`, over every selected file, in any order. They cannot see
+each other, which is why their order does not matter.
+
+A file is opened as a parse tree when a pack claims its extension and declares a grammar,
+and as text otherwise. A pack with no grammar is legal and complete — `packs/twig` maps
+templates with patterns alone.
+
+### 5. Run map rules to a fixpoint
+
+Every rule whose `reads` is `map`, repeatedly, until nothing changes.
+
+It terminates because a pass may only add attributes or refine a type downward through a
+hierarchy the packs declare, and that hierarchy is finite. Nothing moves back up. Edges a map
+rule adds terminate too: map rules match and follow only nodes and edges the rules found or file
+rules emitted, never an end a map rule composed, so the ids a pass reads are fixed once the file
+rules have run. Edges merge on `(kind, from, to)` over that finite set, and a pass that adds
+nothing stops the loop.
+
+Each pass reads the map as it stood when the pass began, rules in load order and nodes in id
+order, so a rule reads an edge another map rule made in the next pass, and the map stays
+byte-identical across runs.
+
+The engine must report how many passes ran and which rules fired in each. The fixpoint hides
+its own sequencing, and when a classification comes out wrong, "it fired in pass three off a
+type assigned in pass two" is the only thing that makes it traceable.
+
+### 6. Merge and resolve
+
+Nodes merge on their id. Edges merge on `(kind, from, to)`; their locations accumulate and
+`occurrences` is the count. Deduplicating per pair and discarding the rest was measured at
+186 caller functions against 303 call sites, and one pair in a real map had 58.
+
+An endpoint naming no node becomes one — `declared` when a pack's `boundary` lists it,
+`referenced` when nothing does. Doing this took dangling edges in one real map from 792 of 884 to
+zero. A boundary group gives a `type`, the `ancestry` edge kinds and its `names`; a listed node
+takes the group's type, no location, and the drawing pack's provenance. A name's value is a node
+type: a mapped class whose ancestry edges reach the name through mapped classes is classified by
+it, or keeps its type with a skipped row when its type and the value lie on no one chain.
+
+### 7. Emit
+
+Canonical JSON. Keys in a fixed order, arrays sorted by a declared key, LF, no trailing
+whitespace, no timestamps, no absolute paths.
+
+## What it must refuse
+
+A run fails, loudly, on any of these. None of them may be a warning.
+
+- A pack naming a type nothing in its dependency graph declares.
+- Two packs declaring the same type.
+- An edge whose endpoints are not legal for its kind.
+- An unknown key anywhere in a pack. Three separate silent failures in one day came from
+  keys that read fine and did nothing: `on:` parsed as the boolean `true` in five rules; two
+  `id:` keys in one mapping discarded 48 rule names; a duplicate `pack:` key threw away a
+  whole file.
+- A rule shape the engine cannot execute. The spike printed these and ran on, which is the
+  minimum; refusing is better, because a map missing a third of its rules is worse than no
+  map.
+- A grammar version that does not match what the pack pinned.
+
+## What it must report
+
+- Which rules fired, and how many times each.
+- How many passes the fixpoint took.
+- Every rule that matched nothing. A rule that fires zero times is either dead or broken,
+  and the difference matters.
+- Every unresolved node, with what the rule looked for and what it found. "Unresolved" alone
+  is a shrug. The entry has to read as "add an anchor for this symbol", not "unknown".
+
+## What it must never do
+
+**Guess.** Where a rule cannot resolve something, it emits an unresolved node recording the
+attempt. It never emits an edge to a name it could not resolve. The spike did, and produced
+221 call edges to bare words — `Draft -> t`, where `t` is a translation method.
+
+**Write prose.** Nothing a model wrote enters the map. The determinism gate extracts twice
+and byte-compares; a model writing during extraction fails on the first run. Descriptions are
+a separate committed artifact keyed by node id, joined through each node's `source_hash`.
+
+**Carry advice.** A pack may recommend; the map holds the count and the pack holds the note,
+joined at read time.
+
+**Depend on locale, working directory, or filesystem order.** Proven by running twice and
+byte-comparing, including under a Turkish locale, where `I` does not lowercase to `i`.
+
+## Open, and deliberately not decided here
+
+- **Cardinality.** Nothing expresses that a class extends one class and implements many. A
+  second `inherits` edge on one PHP class would sit in a map looking fine. It belongs on the
+  edge kind, per pack, because Go has no `inherits` at all and a Go struct embeds many.
+- **Descriptions.** The join exists; the artifact has no schema.
+- **Incremental runs.** Every run is a full run. `source_hash` is the obvious lever.
+- **Addressing inside a data file.** `each: "services.*"` is one underspecified line, and two
+  packs need it.