periplus-map 0.2.1__py3-none-any.whl

periplus/packs/php@0.1.0/edges/edge_kinds.yaml

@@ -0,0 +1,64 @@
+$schema: "https://periplus.dev/schema/0/pack-file.schema.json"
+
+# php pack — the edge kinds this pack declares. Finding them is in edges/find_*.yaml.
+#
+# Endpoints take one type or a flat list of alternatives. Nesting a combination inside a
+# list is not expressible — that is the grammar restriction that keeps validation cheap,
+# and it can be widened later without breaking any pack written against it.
+
+edge_kinds:
+
+  - kind: contains
+    from: [php.file, php.file_entry, php.class_like, php.callable]
+    to:   [php.class_like, php.callable, php.property, php.class_constant, php.enum_case]
+    source: nearest_enclosing_container
+    # why: the containment source was hardcoded to the file node across 15 language
+    #      configs, so a method's container was the file rather than its class.
+
+  - kind: inherits
+    from: php.class
+    to:   php.class
+
+  - kind: implements
+    from: [php.class, php.enum]
+    to:   php.interface
+
+  - kind: mixes_in
+    from: php.class_like
+    to:   php.trait
+
+  - kind: instantiates
+    from: php.callable
+    to:   php.class
+    # why: `object_creation_expression` was simply absent from the trigger set. On one
+    #      615-file corpus that was 505 `new X(` sites across 178 classes emitting nothing.
+    #
+    # Its own kind rather than folded into `calls`: instantiating a class and calling a
+    # method are different questions, and a reader asking "who constructs this" should not
+    # have to filter call edges.
+
+  - kind: calls
+    from: php.callable
+    to:   php.callable
+
+  - kind: indirect_call
+    from: php.callable
+    to:   php.callable
+    # why: `$obj->m(...)` creates a Closure and transfers control nowhere. Recording it as
+    #      `calls` asserts something false; dropping it loses a real reference.
+
+  # Operational edges. Open in the design, drafted here so the shape can be argued with.
+  - kind: reads
+    from: php.callable
+    to:   [php.property, php.class_constant, php.enum_case]
+
+  - kind: writes
+    from: php.callable
+    to:   php.property
+    # Separate from `reads` rather than one relation with a direction field: the write is
+    # the half that answers "what changes this", and folding them together loses most of
+    # the value of having the edge at all.
+
+  - kind: imports
+    from: php.file
+    to:   [php.class_like, php.function, php.class_constant]

periplus/packs/php@0.1.0/edges/find_calls.yaml

@@ -0,0 +1,34 @@
+$schema: "https://periplus.dev/schema/0/pack-file.schema.json"
+
+# php pack — call edges. Three rules.
+#
+# A call site's shape constrains what it may bind to. A bare `name()` is a function call and
+# can never resolve to a method.
+# why: conflating them fabricated 848 edges from 368 files for `event()` alone, 290 for
+#      `config()`, 186 for `dispatch()`.
+
+needs:
+  types: [php.callable, php.function, php.method]
+
+rules:
+
+  - rule: plain_function_call
+    reads: file
+    in: [source]
+    match: {declaration: function_call_expression}
+    emits: [{edge: {kind: calls, from: enclosing_callable, to: {from: qualified_name}}}]
+    confidence: declared
+
+  - rule: static_call
+    reads: file
+    in: [source]
+    match: {declaration: scoped_call_expression}
+    emits: [{edge: {kind: calls, from: enclosing_callable, to: {from: qualified_name}}}]
+    confidence: declared
+
+  - rule: first_class_callable
+    reads: file
+    in: [source]
+    match: {declaration: first_class_callable}
+    emits: [{edge: {kind: indirect_call, from: enclosing_callable, to: {from: qualified_name}}}]
+    confidence: declared

periplus/packs/php@0.1.0/edges/find_imports.yaml

@@ -0,0 +1,18 @@
+$schema: "https://periplus.dev/schema/0/pack-file.schema.json"
+
+# php pack — the imports edge. One rule.
+#
+# The facts a `use` statement carries are declared separately, in imports/imports.yaml. This
+# rule only emits the edge.
+
+needs:
+  types: [php.class_like, php.function, php.class_constant]
+
+rules:
+
+  - rule: imports_edge
+    reads: file
+    in: [source]
+    match: {declaration: namespace_use_declaration}
+    emits: [{edge: {kind: imports, from: enclosing_file, to: {from: qualified_name}}}]
+    confidence: declared

periplus/packs/php@0.1.0/edges/find_member_access.yaml

@@ -0,0 +1,22 @@
+$schema: "https://periplus.dev/schema/0/pack-file.schema.json"
+
+# php pack — reads and writes of members. Two rules.
+
+needs:
+  types: [php.property, php.class_constant, php.enum_case]
+
+rules:
+
+  - rule: writes_property
+    reads: file
+    in: [source]
+    match: {declaration: assignment_expression_lhs}
+    emits: [{edge: {kind: writes, from: enclosing_callable, to: {from: qualified_name}}}]
+    confidence: declared
+
+  - rule: reads_member
+    reads: file
+    in: [source]
+    match: {declaration: member_access_expression}
+    emits: [{edge: {kind: reads, from: enclosing_callable, to: {from: qualified_name}}}]
+    confidence: declared

periplus/packs/php@0.1.0/edges/find_structure.yaml

@@ -0,0 +1,38 @@
+$schema: "https://periplus.dev/schema/0/pack-file.schema.json"
+
+# php pack — the edges written at a declaration site. Four rules.
+
+needs:
+  types: [php.class, php.class_like, php.interface, php.trait, php.enum]
+
+rules:
+
+  - rule: inherits_from_base_clause
+    reads: file
+    in: [source]
+    match: {declaration: base_clause}
+    emits: [{edge: {kind: inherits, from: enclosing_class, to: {from: qualified_name}}}]
+    confidence: declared
+
+  - rule: implements_from_interface_clause
+    reads: file
+    in: [source]
+    match: {declaration: class_interface_clause}
+    emits: [{edge: {kind: implements, from: enclosing_class, to: {from: qualified_name}}}]
+    confidence: declared
+
+  - rule: mixes_in_from_use_declaration
+    reads: file
+    in: [source]
+    match: {declaration: use_declaration}
+    emits: [{edge: {kind: mixes_in, from: enclosing_class, to: {from: qualified_name}}}]
+    confidence: declared
+
+  - rule: instantiates_from_new
+    reads: file
+    in: [source]
+    match: {declaration: object_creation_expression}
+    emits: [{edge: {kind: instantiates, from: enclosing_callable, to: {from: qualified_name}}}]
+    confidence: declared
+    # why: absent from the trigger set entirely — 505 `new X(` sites across 178 classes
+    #      emitting nothing, including 0 of 22 `$bus->dispatch(new SomeCommand())` sites.

periplus/packs/php@0.1.0/embedded/embedded_regions.yaml

@@ -0,0 +1,19 @@
+$schema: "https://periplus.dev/schema/0/pack-file.schema.json"
+
+# php pack — embedded sub-language regions.
+
+# --------------------------------------------------------------------------------------
+# Files that hold more than one language.
+#
+# why: inline `<script>` in `.php` was never indexed, so a helper and its caller both
+#      vanished along with the call between them.
+# --------------------------------------------------------------------------------------
+embedded_regions:
+  - open: "<script(?![^>]*\\bsrc=)[^>]*>"
+    close: "</script>"
+    language: javascript
+    line_offset: preserve
+    skip_when_empty: true
+    host_constructs_inside: ["<?= ?>", "<?php ?>"]
+    # Host tags inside the region are replaced with placeholders before the sub-language
+    # parses, or the sub-parse fails on syntax that is not its own.

periplus/packs/php@0.1.0/imports/imports.yaml

@@ -0,0 +1,20 @@
+$schema: "https://periplus.dev/schema/0/pack-file.schema.json"
+
+# php pack — the import-statement facts this pack extracts.
+
+# --------------------------------------------------------------------------------------
+# Import statements are facts, not just a lookup table.
+#
+# why: the importer kept only the last path segment and discarded the rest, so
+#      `use function A\{render};` claimed `render` as a class and re-pointed a sibling's
+#      `extends Render`.
+# --------------------------------------------------------------------------------------
+imports:
+  - ast: namespace_use_declaration
+    group_ast: namespace_use_group
+    facts:
+      target_fqn: written_path
+      alias: as_clause
+      use_kind: declaration_keyword     # `function` / `const` sits on the declaration in
+                                        # group form, not on each clause
+    binds_through_alias: true

periplus/packs/php@0.1.0/pack.yaml

@@ -0,0 +1,117 @@
+$schema: "https://periplus.dev/schema/0/pack-manifest.schema.json"
+
+# PHP pack — first draft
+#
+# Every section below exists because something concrete went wrong when the same
+# information was an engine constant instead of configuration. The `# why:` lines cite
+# the failure, with the numbers the reporter measured. If a section has no `# why:`, it
+# is a design choice and not yet evidence-backed.
+#
+# This is the DATA schema side only. Nothing here describes the emitted map.
+
+pack: php
+version: 0.1.0
+depends: []
+# A pack with no dependencies. Not a "language pack" — there is no such kind. It is the
+# root of this dependency graph only because nothing sits beneath PHP.
+
+# --------------------------------------------------------------------------------------
+# The grammar this pack's rules are written against.
+#
+# The engine never parses source; an adapter does. So the pack has to say which grammar
+# its AST node names belong to, or `class_declaration` is a magic string that means
+# whatever the adapter happens to think.
+# --------------------------------------------------------------------------------------
+grammar:
+  provider: tree-sitter
+  provider_version: "0.26.13"      # tree-sitter runtime, released 2026-08-23
+  language: php
+  grammar_version: "0.23.11"       # tree-sitter-php
+  # Grammar versions are PINNED EXACTLY, never a range. Node type names are not guaranteed
+  # stable across a grammar's minor releases: tree-sitter issue #2611 records a JavaScript
+  # grammar rename, with the maintainer-adjacent line "just about any time a change is made
+  # to a grammar, the change is somehow breaking to consumers." A range would let a rule
+  # that matched yesterday silently match nothing today.
+  #
+  # tree-sitter PR #4135 (merged 2025-01-25, milestone 0.25) added a `semantic_version` field
+  # to TSLanguage and `ts_language_semantic_version()`, sourced from the grammar's
+  # tree-sitter.json manifest — so the engine can read which grammar it actually got and
+  # refuse a mismatch. It does not make grammar authors honour semver, which is why the pin
+  # is exact rather than caret.
+  #
+  # Two versions, because they move independently: the runtime that parses, and the grammar
+  # whose node names the rules below reference.
+
+# --------------------------------------------------------------------------------------
+# Which files are ours.
+#
+# A list, not a global map. A pack that depends on this one may add extensions, and the
+# project settings file may override any of them. All three layers resolve before extraction.
+#
+# why: `.inc` was hard-mapped to a Pascal extractor. Identical bytes gave 7 nodes as
+#      `a.inc` and 471 as `b.php`; across 12 pfSense files, 20 nodes instead of 755. One
+#      19,046-line file with 460 functions produced 7 nodes. Silently.
+# --------------------------------------------------------------------------------------
+# ======================================================================================
+# NAMED FOLDERS
+#
+# A rule says `in: [source]`. It never writes a path. php the language has no opinion about
+# where source lives, so the default is the repository root and the project settings file
+# narrows it. A dependent pack overrides it with something meaningful — Drupal replaces it
+# with custom_module and custom_theme.
+# ======================================================================================
+folders:
+  source: ./
+
+files:
+  extensions: [php, phtml, php3, php4, php5, php7, phps]
+  # Deliberately NOT here: module, inc, install, theme, profile. Those are Drupal
+  # conventions, not PHP ones, and belong to the pack that knows they are PHP.
+
+  exclude: []
+  # A path the extractor never opens. Different from a boundary, and the difference
+  # matters:
+  #   boundary — the file is not read, but a thing inside it can still be a node,
+  #              because something first-party refers to it by name.
+  #   exclude  — the file does not exist as far as the map is concerned. Nothing from
+  #              it appears, not even as the target of a reference.
+  #
+  # Enforced at file selection, before anything parses. Never "read it and drop the
+  # results": the map is a committed artifact, and a string literal or a variable name
+  # from an excluded file reaching a commit is not a mistake you can take back.
+  #
+  # Empty here on purpose. PHP the language excludes nothing. Every real exclusion is a
+  # convention of some framework or of one project, so it belongs to the pack or the
+  # overlay that knows the convention.
+
+  # The resolved language must reach the extraction cache key, or bytes cached under the
+  # previous language get served after an override changes it — in either direction.
+  cache_key_includes: [resolved_language]
+
+# --------------------------------------------------------------------------------------
+# Identity.
+#
+# The test for every rule here: does a declaration site and a reference site
+# independently produce the same string?
+#
+# why: one global lowercased name-to-id map fused a PHP `Exception` with an unrelated
+#      TypeScript class — 12 phantom inheritance edges across 3 Composer packages, and it
+#      inflated the TS node into a top-10 hub. Separately, `App\Models\Page` and
+#      `Filament\Pages\Page` collapsed onto one node.
+# --------------------------------------------------------------------------------------
+identity:
+  qualified_name:
+    parts: [namespace, declared_name]
+    separator: "\\"
+    leading_separator: strip     # `\Foo\Bar` and `Foo\Bar` name the same type
+  scope: pack                    # ids are namespaced to this pack; never a global name map
+
+  case_folding:
+    # PHP is case-insensitive for these and case-sensitive for the rest. Declared rather
+    # than assumed, because getting it backwards silently merges or splits nodes.
+    insensitive: [php.class, php.interface, php.trait, php.enum, php.function, php.method]
+    sensitive:   [php.property, php.class_constant]
+
+  # why: id normalization that casefolded AND stripped underscores collided `_count` with
+  #      `Count`. Normalization beyond what the language itself does is a defect.
+  never_normalize: [underscores, punctuation]

periplus/packs/php@0.1.0/resolution/excluded_tokens.yaml

@@ -0,0 +1,23 @@
+$schema: "https://periplus.dev/schema/0/pack-file.schema.json"
+
+# php pack — tokens excluded from resolution.
+
+# --------------------------------------------------------------------------------------
+# Tokens that are never type names.
+# --------------------------------------------------------------------------------------
+excluded_tokens:
+
+  - group: relative_scope
+    tokens: [self, static, parent]
+    case_sensitive: false
+    positions: [type_reference, callee, supertype]
+    # why: treated as types, these minted one global node each, wired to a large fraction
+    #      of all classes. `parent::setUp()` alone fabricated 1,698 inbound calls onto a
+    #      single method. `STATIC` needs the same treatment, hence case-insensitive.
+
+  - group: builtin_bases
+    tokens: [Exception, Throwable, Error, ArrayObject, ArrayAccess, Countable,
+             Iterator, IteratorAggregate, Traversable, JsonSerializable, Stringable]
+    positions: [type_reference, callee, supertype]
+    # why: the supertype resolver never consulted the builtin list at all — it was applied
+    #      at call sites only. Positions are declared here so that cannot recur.

periplus/packs/php@0.1.0/resolution/resolution.yaml

@@ -0,0 +1,35 @@
+$schema: "https://periplus.dev/schema/0/pack-file.schema.json"
+
+# php pack — the name-resolution rules.
+
+# --------------------------------------------------------------------------------------
+# Resolution.
+#
+# These are the rules for turning a written name into a node, and most of the damage in
+# the record came from here rather than from extraction.
+# --------------------------------------------------------------------------------------
+resolution:
+  scope: same_pack
+  # why: bare `extends Exception` in PHP bound to a TypeScript class because one global
+  #      name map served every language.
+
+  match: qualified_name_exact
+  never_match_by: [prefix, substring, case_folded_and_stripped]
+  # why: a class whose name is a strict prefix of its siblings lost its entire fan-in —
+  #      `Pivot` went from degree 4 to degree 1 once `PivotRepository` existed, and the
+  #      "what depends on this" query then answered "nothing".
+
+  on_multiple_definitions: refuse
+  on_zero_definitions: unresolved
+  # `unresolved` emits a node recording which rule fired and what it looked for. It never
+  # drops the edge.
+  # why: every failure in this record was silent, and the graph still looked populated.
+
+  # Ambiguity is decided on evidence, not on a vocabulary list. These are two jobs and
+  # conflating them was load-bearing by accident: a shared builtin list suppressed 27–29
+  # of 29 names in most languages, and removing it recovered 45 edges of which 43 were
+  # phantom. The refusal rule above does that work; the list below does not.
+  detect_references_independently_of_imports: true
+  # why: 158 of 240 Eloquent relationships (65%) were unlinked because the edge tracked
+  #      the `use` statement rather than the reference. 140 were same-namespace, so no
+  #      import existed to track.

periplus/packs/php@0.1.0/types/find_declarations.yaml

@@ -0,0 +1,102 @@
+$schema: "https://periplus.dev/schema/0/pack-file.schema.json"
+
+# php pack — finds every declaration the language has. Nine rules, one per construct.
+#
+# One rule per construct rather than one rule with a list, because each declares where its
+# name lives and which child holds its body, and those differ. That difference is not
+# cosmetic: `enum_declaration_list` differs from `declaration_list` by one word, and that
+# single difference is what made all 119 enums invisible.
+
+needs:
+  types: [php.class, php.interface, php.trait, php.enum, php.function, php.method,
+          php.property, php.class_constant, php.enum_case]
+
+rules:
+
+  - rule: find_class
+    reads: file
+    in: [source]
+    match: {declaration: class_declaration, name_child: name, body_child: declaration_list}
+    id: {from: qualified_name}
+    emits: [{node: {type: php.class}}]
+    confidence: declared
+
+  - rule: find_interface
+    reads: file
+    in: [source]
+    match: {declaration: interface_declaration, name_child: name, body_child: declaration_list}
+    id: {from: qualified_name}
+    emits: [{node: {type: php.interface}}]
+    confidence: declared
+
+  - rule: find_trait
+    reads: file
+    in: [source]
+    match: {declaration: trait_declaration, name_child: name, body_child: declaration_list}
+    id: {from: qualified_name}
+    emits: [{node: {type: php.trait}}]
+    confidence: declared
+
+  - rule: find_enum
+    reads: file
+    in: [source]
+    match: {declaration: enum_declaration, name_child: name, body_child: enum_declaration_list}
+    id: {from: qualified_name}
+    emits: [{node: {type: php.enum}}]
+    confidence: declared
+    # why: this one child name differs from the other three, and that single difference is
+    #      what made all 119 enums invisible. Declaring it per rule is the fix.
+
+  - rule: find_function
+    reads: file
+    in: [source]
+    match: {declaration: function_definition, name_child: name}
+    id: {from: qualified_name}
+    emits: [{node: {type: php.function}}]
+    confidence: declared
+
+  - rule: find_method
+    reads: file
+    in: [source]
+    match: {declaration: method_declaration, name_child: name}
+    id:
+      from: [namespace, enclosing_type, declared_name]
+      template: "{namespace}\\{enclosing_type}::{declared_name}"
+    emits: [{node: {type: php.method}}]
+    confidence: declared
+
+  - rule: find_property
+    reads: file
+    in: [source]
+    match: {declaration: property_declaration, name_child: name}
+    id:
+      from: [namespace, enclosing_type, declared_name]
+      template: "{namespace}\\{enclosing_type}::{declared_name}"
+    emits: [{node: {type: php.property}}]
+    confidence: declared
+
+  # why: the pack's own identity block is `parts: [namespace, declared_name]`, which is right
+  #      for a class and wrong for everything inside one. Run against block_ways it merged
+  #      four different build() methods on four different classes into one node —
+  #      AnnotationBlock:31, AttributeBlock:30, ContextAwareBlock:40, DerivedBlock:33 — with
+  #      no error. A member's id needs the type that holds it, so these four rules carry
+  #      their own template, exactly as go's find_method carries its receiver.
+  - rule: find_class_constant
+    reads: file
+    in: [source]
+    match: {declaration: const_declaration, name_child: name}
+    id:
+      from: [namespace, enclosing_type, declared_name]
+      template: "{namespace}\\{enclosing_type}::{declared_name}"
+    emits: [{node: {type: php.class_constant}}]
+    confidence: declared
+
+  - rule: find_enum_case
+    reads: file
+    in: [source]
+    match: {declaration: enum_case, name_child: name}
+    id:
+      from: [namespace, enclosing_type, declared_name]
+      template: "{namespace}\\{enclosing_type}::{declared_name}"
+    emits: [{node: {type: php.enum_case}}]
+    confidence: declared

periplus/packs/php@0.1.0/types/node_types.yaml

@@ -0,0 +1,55 @@
+$schema: "https://periplus.dev/schema/0/pack-file.schema.json"
+
+# php pack — the node types this pack declares. Finding them is in types/find_*.yaml.
+#
+# why: `class_types` held `class_declaration` only. 291 declarations minted no node —
+#      142 interfaces, 30 traits, 119 enums — and their methods re-attributed to the file
+#      as free functions. ~19,000 imports edges dangled. 18 stubs shared one label.
+
+node_types:
+
+  - name: php.file
+    container: true
+
+  - name: php.file_entry
+    container: true
+    parent: php.file
+    synthetic: true
+    # why: top-level code has no enclosing callable, so a call from module scope had no
+    #      caller and the function looked dead — 18 file-caller edges out of ~195 known
+    #      sites. A declared synthetic entry container gives that code somewhere to live.
+
+  - name: php.class_like
+    abstract: true
+    container: true
+
+  - name: php.class
+    parent: php.class_like
+
+  - name: php.interface
+    parent: php.class_like
+
+  - name: php.trait
+    parent: php.class_like
+
+  - name: php.enum
+    parent: php.class_like
+
+  - name: php.callable
+    abstract: true
+    container: true
+
+  - name: php.function
+    parent: php.callable
+
+  - name: php.method
+    parent: php.callable
+
+  # Members get their own types so an edge can terminate on one.
+  # why: no language emitted an edge pointing at a member. `Foo::$prop` pointed at the
+  #      class, so "what writes this field" had no answer anywhere in the graph.
+  - name: php.property
+
+  - name: php.class_constant
+
+  - name: php.enum_case

periplus/packs/php_basic@0.2.0/edges/edge_kinds.yaml

@@ -0,0 +1,48 @@
+$schema: "https://periplus.dev/schema/0/pack-file.schema.json"
+
+# The edge kinds this pack declares. Finding them is in edges/find_structure.yaml.
+#
+# inherits ends at the abstract php.class_like, so a type named only by an extends and also by an
+# implements elsewhere takes the more specific php.interface.
+edge_kinds:
+
+- kind: inherits
+  from: php.class_like
+  to: php.class_like
+
+- kind: implements
+  from: [php.class, php.enum]
+  to: php.interface
+
+- kind: mixes_in
+  from: php.class_like
+  to: php.trait
+
+- kind: contains
+  from: php.class_like
+  to: php.method
+
+- kind: calls
+  from: [php.function, php.method]
+  to: [php.function, php.method]
+
+# The joins of a call through a property; edges/find_structure.yaml finds them.
+- kind: declares_property
+  from: php.class_like
+  to: php.property
+
+- kind: parameter_typed_as
+  from: php.parameter
+  to: php.parameter_type
+
+- kind: assigned_value
+  from: php.member_assignment
+  to: php.member_assignment_value
+
+- kind: has_call_site
+  from: php.method
+  to: php.call_site
+
+- kind: call_site_in
+  from: php.call_site
+  to: php.method