agentforge-graph 0.3.2__py3-none-any.whl

agentforge_graph/ingest/packs/csharp/structure.scm

@@ -0,0 +1,45 @@
+; C# structure queries (feat-002, pack-csharp).
+; Namespace-prefix import model: `using App.Geo` names a *namespace* (not a class),
+; so it resolves to every in-repo file declaring that namespace.
+
+; --- namespace (block or file-scoped) ---
+(namespace_declaration
+  name: (_) @namespace)
+(file_scoped_namespace_declaration
+  name: (_) @namespace)
+
+; --- definitions ---
+(class_declaration
+  name: (identifier) @name) @def.class
+
+; --- inheritance (INHERITS): `class B : A, IFoo`. The base_list mixes the base
+; class with interfaces (C# doesn't distinguish syntactically); only an entry
+; that resolves to an in-repo class becomes an INHERITS edge (interfaces, which
+; aren't Class nodes, drop out in the resolver). ---
+(class_declaration
+  (base_list (identifier) @base.name)) @base.def
+
+(interface_declaration
+  name: (identifier) @name) @def.interface
+
+; struct + enum + record -> Class (named nominal types).
+(struct_declaration
+  name: (identifier) @name) @def.class
+
+(enum_declaration
+  name: (identifier) @name) @def.class
+
+(record_declaration
+  name: (identifier) @name) @def.class
+
+; methods + constructors live in a type body -> promoted to Method.
+(method_declaration
+  name: (identifier) @name) @def.function
+
+(constructor_declaration
+  name: (identifier) @name) @def.function
+
+; --- imports ---
+; `using System;` / `using App.Shapes;` -> a namespace (resolved to its files).
+(using_directive
+  [(identifier) (qualified_name)] @import.module) @import

agentforge_graph/ingest/packs/go/__init__.py

@@ -0,0 +1,38 @@
+"""The Go language pack (Tier A — structure + directory-package import resolution).
+
+Go differs from the file-level packs: a **package is a directory**, so every
+``.go`` file in a dir shares one module key (``module_style="go"``). Import paths
+are full module paths (``example.com/m/internal/bar``); the resolver suffix-matches
+them to an in-repo package dir (it can't know the go.mod module prefix). Methods
+are package-scoped (attached to a receiver type), captured here as ``Method`` but
+file-owned — receiver→method ``CONTAINS`` linkage is a follow-up.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from agentforge_graph.core import NodeKind
+from agentforge_graph.ingest.pack import DescriptorRules, LanguagePack
+
+_HERE = Path(__file__).parent
+
+GO_PACK = LanguagePack(
+    language="go",
+    lang_slug="go",
+    grammar="go",
+    extensions=(".go",),
+    structure_queries=(_HERE / "structure.scm").read_text(encoding="utf-8"),
+    reference_queries=(_HERE / "references.scm").read_text(encoding="utf-8"),
+    descriptor_rules=DescriptorRules(
+        kinds={
+            "def.function": NodeKind.FUNCTION,
+            "def.method": NodeKind.METHOD,
+            "def.class": NodeKind.CLASS,  # struct
+            "def.interface": NodeKind.INTERFACE,
+            "def.type": NodeKind.TYPE_ALIAS,  # defined types / aliases
+            "def.variable": NodeKind.VARIABLE,  # package-level const/var
+        }
+    ),
+    module_style="go",
+)

agentforge_graph/ingest/packs/go/references.scm

@@ -0,0 +1,12 @@
+; Go reference queries (feat-002, pack-go).
+; Plain call `f(...)` and selector call `x.f(...)`. @call.recv is the operand, so
+; a call on the method's receiver (`s.f()`) resolves to a method of the receiver's
+; type (BUG-006); `pkg.Func` / other receivers stay unresolved (ADR-0004).
+
+(call_expression
+  function: (identifier) @call.callee) @call
+
+(call_expression
+  function: (selector_expression
+    operand: (identifier) @call.recv
+    field: (field_identifier) @call.callee)) @call

agentforge_graph/ingest/packs/go/structure.scm

@@ -0,0 +1,64 @@
+; Go structure queries (feat-002, pack-go).
+; Shares the capture vocabulary so edge kinds mean the same as other packs.
+; A Go package is a *directory*: every `.go` file in a dir is one package, and
+; same-package files reference each other with no import (handled in the resolver).
+
+; --- definitions ---
+(function_declaration
+  name: (identifier) @name) @def.function
+
+; methods are declared at package scope, attached to a receiver type. They're not
+; AST-nested in the type, so they're file-owned here (receiver→method CONTAINS
+; linkage is a follow-up); captured directly as Method.
+(method_declaration
+  name: (field_identifier) @name) @def.method
+
+; the method's receiver `(s *T)` / `(s T)` -> bind the var name + type, so a call
+; on `s` inside the method resolves to a method of type T (BUG-006).
+(method_declaration
+  receiver: (parameter_list (parameter_declaration
+    name: (identifier) @recv.var
+    type: [(type_identifier) @recv.type
+           (pointer_type (type_identifier) @recv.type)]))) @recv.method
+
+; `type T struct {…}` -> Class, `type T interface {…}` -> Interface.
+(type_spec
+  name: (type_identifier) @name
+  (struct_type)) @def.class
+
+(type_spec
+  name: (type_identifier) @name
+  (interface_type)) @def.interface
+
+; defined types / aliases: `type Celsius float64`, `type ID = string`, `type
+; Handler func(...)`. Listed underlying kinds exclude struct/interface so there's
+; no double-match with the two patterns above.
+(type_spec
+  name: (type_identifier) @name
+  [(type_identifier)
+   (qualified_type)
+   (pointer_type)
+   (slice_type)
+   (array_type)
+   (map_type)
+   (channel_type)
+   (function_type)
+   (generic_type)]) @def.type
+
+(type_alias
+  name: (type_identifier) @name) @def.type
+
+; package-level const / var (anchored to source_file so locals don't inflate).
+(source_file
+  (const_declaration
+    (const_spec name: (identifier) @name) @def.variable))
+(source_file
+  (var_declaration
+    (var_spec name: (identifier) @name) @def.variable))
+
+; --- imports ---
+; `import "example.com/m/pkg"` (and grouped `import ( … )`) -> the path string.
+; Go imports bind a *package*, not names; the resolver maps the path to a repo dir.
+(import_spec
+  (interpreted_string_literal
+    (interpreted_string_literal_content) @import.module)) @import

agentforge_graph/ingest/packs/java/__init__.py

@@ -0,0 +1,35 @@
+"""The Java language pack (Tier A — structure + namespace/FQN import resolution).
+
+Java reuses the namespace/FQN mechanism (separator "."): a file declares a
+`package`, and `import com.foo.Bar` resolves to the file declaring class `Bar` in
+that package. Extracts class/enum/record (→Class), interface (→Interface),
+methods + constructors. Method calls (`obj.m()`) stay unresolved (member access,
+ADR-0004); since Java has no top-level functions, intra-class calls are method
+dispatch too — the symbol graph + FQN dependency graph are the value.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from agentforge_graph.core import NodeKind
+from agentforge_graph.ingest.pack import DescriptorRules, LanguagePack
+
+_HERE = Path(__file__).parent
+
+JAVA_PACK = LanguagePack(
+    language="java",
+    lang_slug="java",
+    grammar="java",
+    extensions=(".java",),
+    structure_queries=(_HERE / "structure.scm").read_text(encoding="utf-8"),
+    reference_queries=(_HERE / "references.scm").read_text(encoding="utf-8"),
+    descriptor_rules=DescriptorRules(
+        kinds={
+            "def.class": NodeKind.CLASS,  # class + enum + record
+            "def.interface": NodeKind.INTERFACE,
+            "def.function": NodeKind.FUNCTION,  # method + constructor (promoted)
+        }
+    ),
+    namespace_sep=".",  # `import com.foo.Bar` -> FQN resolution
+)

agentforge_graph/ingest/packs/java/references.scm

@@ -0,0 +1,12 @@
+; Java reference queries (feat-002, pack-java).
+; A method invocation's `name` is the called method, with or without a receiver
+; (`f(...)`, `this.f(...)`, `obj.f(...)`). The second pattern captures the
+; receiver (@call.recv) so `this.f()` binds to the enclosing class's method
+; (BUG-006); other receivers stay unresolved (member access, ADR-0004).
+
+(method_invocation
+  name: (identifier) @call.callee) @call
+
+(method_invocation
+  object: (_) @call.recv
+  name: (identifier) @call.callee) @call

agentforge_graph/ingest/packs/java/structure.scm

@@ -0,0 +1,38 @@
+; Java structure queries (feat-002, pack-java).
+; Namespace/FQN import model (reuses the PHP mechanism, separator "."): a file
+; declares a `package`; `import com.foo.Bar` resolves to the file declaring Bar.
+
+; --- package (drives FQN import resolution) ---
+(package_declaration
+  (scoped_identifier) @namespace)
+
+; --- definitions ---
+(class_declaration
+  name: (identifier) @name) @def.class
+
+; --- inheritance (INHERITS): `class B extends A` (implemented interfaces are a
+; separate relation, not captured here). ---
+(class_declaration
+  superclass: (superclass (type_identifier) @base.name)) @base.def
+
+(interface_declaration
+  name: (identifier) @name) @def.interface
+
+; enum + record -> Class (named nominal types).
+(enum_declaration
+  name: (identifier) @name) @def.class
+
+(record_declaration
+  name: (identifier) @name) @def.class
+
+; methods + constructors live in a class/interface body -> promoted to Method.
+(method_declaration
+  name: (identifier) @name) @def.function
+
+(constructor_declaration
+  name: (identifier) @name) @def.function
+
+; --- imports ---
+; `import com.foo.shapes.Shape;` -> the fully-qualified class name (FQN index).
+(import_declaration
+  (scoped_identifier) @import.module) @import

agentforge_graph/ingest/packs/javascript/__init__.py

@@ -0,0 +1,34 @@
+"""The JavaScript language pack (Tier A — structure + import resolution).
+
+Shares the TS grammar family. The only structural delta is that JS
+``class_declaration`` names are ``(identifier)``, not ``(type_identifier)``
+(see ``structure.scm``). Like TS, JS module specifiers are path-based
+(``./util``), so the pack uses ``module_style="relative"``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from agentforge_graph.core import NodeKind
+from agentforge_graph.ingest.pack import DescriptorRules, LanguagePack
+
+_HERE = Path(__file__).parent
+
+JAVASCRIPT_PACK = LanguagePack(
+    language="javascript",
+    lang_slug="js",
+    grammar="javascript",
+    extensions=(".js", ".jsx", ".mjs", ".cjs"),
+    structure_queries=(_HERE / "structure.scm").read_text(encoding="utf-8"),
+    reference_queries=(_HERE / "references.scm").read_text(encoding="utf-8"),
+    descriptor_rules=DescriptorRules(
+        kinds={
+            "def.class": NodeKind.CLASS,
+            "def.function": NodeKind.FUNCTION,  # promoted to METHOD inside a class
+            # ENH-008: arrow/function-bound consts + module-level const tables.
+            "def.variable": NodeKind.VARIABLE,
+        }
+    ),
+    module_style="relative",  # JS imports are path specifiers (./util), not dotted
+)

agentforge_graph/ingest/packs/javascript/references.scm

@@ -0,0 +1,11 @@
+; JavaScript reference queries (feat-002, pack-js).
+; Plain call `f(...)` and method/attribute call `recv.f(...)`. @call.recv is the
+; receiver (BUG-006), so `this.f()` binds to the enclosing class's method.
+
+(call_expression
+  function: (identifier) @call.callee) @call
+
+(call_expression
+  function: (member_expression
+    object: (_) @call.recv
+    property: (property_identifier) @call.callee)) @call

agentforge_graph/ingest/packs/javascript/structure.scm

@@ -0,0 +1,166 @@
+; JavaScript structure queries (feat-002, pack-js).
+; Mirrors the TS pack; the only grammar delta is the class name node:
+; JS `class_declaration` names are (identifier), not (type_identifier).
+; Definitions may be wrapped in `export_statement`; queries match nested.
+
+; --- definitions ---
+(class_declaration
+  name: (identifier) @name) @def.class
+
+; --- inheritance (INHERITS): `class B extends A` (JS heritage holds the
+; superclass expression directly, no extends_clause wrapper). ---
+(class_declaration
+  (class_heritage (identifier) @base.name)) @base.def
+
+; qualified base `class B extends mod.Base` -> base `mod.Base`; the resolver splits
+; the receiver and binds it via the importing module alias (default require).
+(class_declaration
+  (class_heritage (member_expression) @base.name)) @base.def
+
+(function_declaration
+  name: (identifier) @name) @def.function
+
+; methods live in a class_body -> promoted to METHOD by the extractor
+(method_definition
+  name: (property_identifier) @name) @def.function
+
+; --- JSDoc docstrings (DESCRIBES) ---
+; a `/** … */` block comment immediately before a function/class/method becomes a
+; DocChunk that DESCRIBES the symbol (feat-010). `#match?` keeps only JSDoc (`/**`).
+((comment) @docstring . (function_declaration) @doc.owner
+  (#match? @docstring "^/[*][*]"))
+((comment) @docstring . (class_declaration) @doc.owner
+  (#match? @docstring "^/[*][*]"))
+(class_body
+  (comment) @docstring . (method_definition) @doc.owner
+  (#match? @docstring "^/[*][*]"))
+
+; --- value bindings (ENH-008, shared with TS) ---
+; `const f = (…) => …` / `const f = function () {}` -> Function (named from the
+; binding). Captured at any depth — these are genuine functions. (JS has no
+; interface/enum/type-alias, so those TS captures are absent here.)
+(lexical_declaration
+  (variable_declarator
+    name: (identifier) @name
+    value: [(arrow_function) (function_expression)])) @def.function
+
+; module-level const data tables -> Variable. Scoped to the top level (program /
+; export) so locals don't inflate it. Only object/array initializers — NOT call
+; results: `const x = require(...)` is an import binding (BUG-006), not a symbol.
+(program
+  (lexical_declaration
+    (variable_declarator
+      name: (identifier) @name
+      value: [(object) (array)])) @def.variable)
+(program
+  (export_statement
+    (lexical_declaration
+      (variable_declarator
+        name: (identifier) @name
+        value: [(object) (array)])) @def.variable))
+
+; --- imports (ESM) ---
+; `import { a, b } from "./mod"` -> module (relative path) + bound names
+(import_statement
+  (import_clause (named_imports (import_specifier name: (identifier) @import.name)))
+  source: (string (string_fragment) @import.module)) @import
+
+; `import * as ns from "./mod"` -> the namespace alias binds the whole module, so
+; `ns.foo()` and a qualified base `extends ns.Base` resolve to its exports (BUG-006).
+(import_statement
+  (import_clause (namespace_import (identifier) @import.default))
+  source: (string (string_fragment) @import.module)) @import
+
+; --- imports (CommonJS require, BUG-006) ---
+; `const x = require("./mod")` -> module + the default-bound local name
+(variable_declarator
+  name: (identifier) @import.default
+  value: (call_expression
+    function: (identifier) @_require
+    arguments: (arguments (string (string_fragment) @import.module)))
+  (#eq? @_require "require")) @import
+
+; `const { a, b } = require("./mod")` -> module + named bindings
+(variable_declarator
+  name: (object_pattern (shorthand_property_identifier_pattern) @import.name)
+  value: (call_expression
+    function: (identifier) @_require
+    arguments: (arguments (string (string_fragment) @import.module)))
+  (#eq? @_require "require")) @import
+
+; --- exports (CommonJS, BUG-006) ---
+; `module.exports = name` (incl. chained `exports = module.exports = name`) ->
+; the module's default export, so a default require binds to this symbol.
+(assignment_expression
+  left: (member_expression
+    object: (identifier) @_mod
+    property: (property_identifier) @_exp)
+  right: (identifier) @export.default
+  (#eq? @_mod "module")
+  (#eq? @_exp "exports")) @export
+
+; `module.exports = function name() {}` (named function-expression default export —
+; the express-style router-factory pattern, incl. chained `var p = module.exports =
+; function name(){}`; BUG-006 residual). Two patterns on the same assignment: the
+; first makes the function a Function symbol, the second marks it the module default
+; export — so `const r = require("./m"); r()` resolves to it. (Anonymous
+; `module.exports = function(){}` / `= () => {}` have no name → no symbol; the
+; IMPORTS edge still exists.)
+(assignment_expression
+  left: (member_expression
+    object: (identifier) @_mod
+    property: (property_identifier) @_exp)
+  right: (function_expression
+    name: (identifier) @name) @def.function
+  (#eq? @_mod "module")
+  (#eq? @_exp "exports"))
+
+(assignment_expression
+  left: (member_expression
+    object: (identifier) @_mod
+    property: (property_identifier) @_exp)
+  right: (function_expression
+    name: (identifier) @export.default)
+  (#eq? @_mod "module")
+  (#eq? @_exp "exports")) @export
+
+; --- export-member modeling (BUG-006 residual) ---
+; Assigned-property exports whose value is an *anonymous* function — these never
+; become symbols any other way, so `m.foo()` / `const { foo } = require(...)` /
+; direct calls have nothing to bind to. The property name is the export name (an
+; anonymous function has no name of its own). Named function-expression values are
+; covered by the `const f = function name(){}` value-binding pattern's sibling
+; forms; here we deliberately name from the property, which is the export name.
+
+; `exports.foo = function () {}` / `exports.foo = () => {}` -> Function `foo`
+(assignment_expression
+  left: (member_expression
+    object: (identifier) @_obj
+    property: (property_identifier) @name)
+  right: [(function_expression) (arrow_function)] @def.function
+  (#eq? @_obj "exports"))
+
+; `module.exports.foo = function () {}` / `= () => {}` -> Function `foo`
+(assignment_expression
+  left: (member_expression
+    object: (member_expression
+      object: (identifier) @_mod
+      property: (property_identifier) @_exp)
+    property: (property_identifier) @name)
+  right: [(function_expression) (arrow_function)] @def.function
+  (#eq? @_mod "module")
+  (#eq? @_exp "exports"))
+
+; `module.exports = { foo: function(){}, bar: () => {} }` -> Function per inline
+; function-valued pair. Shorthand props (`{ a, b }`) that name top-level defs
+; already resolve via the export map, so only inline functions need extracting.
+(assignment_expression
+  left: (member_expression
+    object: (identifier) @_mod
+    property: (property_identifier) @_exp)
+  right: (object
+    (pair
+      key: (property_identifier) @name
+      value: [(function_expression) (arrow_function)] @def.function))
+  (#eq? @_mod "module")
+  (#eq? @_exp "exports"))

agentforge_graph/ingest/packs/php/__init__.py

@@ -0,0 +1,35 @@
+"""The PHP language pack (Tier A — structure + namespace/FQN import resolution).
+
+PHP is the first namespace/FQN-based pack: a file declares one `namespace`, and
+`use App\\Foo\\Bar` resolves to the file declaring class `Bar` in namespace
+`App\\Foo` (PSR-4 maps namespaces to dirs). Extracts class/interface/trait/enum
+(→Class/Interface), functions, methods, and constants. Method/static calls
+(`$x->m()`, `C::m()`) stay unresolved (member access, ADR-0004).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from agentforge_graph.core import NodeKind
+from agentforge_graph.ingest.pack import DescriptorRules, LanguagePack
+
+_HERE = Path(__file__).parent
+
+PHP_PACK = LanguagePack(
+    language="php",
+    lang_slug="php",
+    grammar="php",
+    extensions=(".php",),
+    structure_queries=(_HERE / "structure.scm").read_text(encoding="utf-8"),
+    reference_queries=(_HERE / "references.scm").read_text(encoding="utf-8"),
+    descriptor_rules=DescriptorRules(
+        kinds={
+            "def.class": NodeKind.CLASS,  # class + trait + enum
+            "def.interface": NodeKind.INTERFACE,
+            "def.function": NodeKind.FUNCTION,  # function + method (promoted)
+            "def.variable": NodeKind.VARIABLE,  # const
+        }
+    ),
+    namespace_sep="\\",  # `use App\Foo\Bar` -> FQN resolution
+)

agentforge_graph/ingest/packs/php/references.scm

@@ -0,0 +1,15 @@
+; PHP reference queries (feat-002, pack-php).
+; Plain call `f(...)`, method call `$x->f(...)`, static call `C::f(...)`. The
+; receiver is captured (@call.recv) so `$this->f()` / `self::f()` bind to the
+; enclosing class's method (BUG-006); other receivers stay unresolved (ADR-0004).
+
+(function_call_expression
+  function: (name) @call.callee) @call
+
+(member_call_expression
+  object: (_) @call.recv
+  name: (name) @call.callee) @call
+
+(scoped_call_expression
+  scope: (_) @call.recv
+  name: (name) @call.callee) @call

agentforge_graph/ingest/packs/php/structure.scm

@@ -0,0 +1,44 @@
+; PHP structure queries (feat-002, pack-php).
+; Namespace/FQN import model: a file declares one namespace; `use App\Foo\Bar`
+; resolves to the file declaring class Bar in namespace App\Foo.
+
+; --- namespace (drives FQN import resolution) ---
+(namespace_definition
+  name: (namespace_name) @namespace)
+
+; --- definitions ---
+(class_declaration
+  name: (name) @name) @def.class
+
+; --- inheritance (INHERITS): `class B extends A` (implemented interfaces are a
+; separate relation, not captured here). ---
+(class_declaration
+  (base_clause (name) @base.name)) @base.def
+
+(interface_declaration
+  name: (name) @name) @def.interface
+
+; a trait is a reusable unit of methods — model as Class (named method container).
+(trait_declaration
+  name: (name) @name) @def.class
+
+; enum -> Class (a named nominal type; no dedicated Enum kind).
+(enum_declaration
+  name: (name) @name) @def.class
+
+(function_definition
+  name: (name) @name) @def.function
+
+; methods live in a class/interface/trait body -> promoted to Method by nesting.
+(method_declaration
+  name: (name) @name) @def.function
+
+; top-level + class constants -> Variable.
+(const_element
+  (name) @name) @def.variable
+
+; --- imports ---
+; `use App\Shapes\Shape;` -> the fully-qualified class name (resolved via FQN index).
+(namespace_use_declaration
+  (namespace_use_clause
+    (qualified_name) @import.module)) @import

agentforge_graph/ingest/packs/python/__init__.py

@@ -0,0 +1,25 @@
+"""The Python language pack (Tier A — structure + import resolution)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from agentforge_graph.core import NodeKind
+from agentforge_graph.ingest.pack import DescriptorRules, LanguagePack
+
+_HERE = Path(__file__).parent
+
+PYTHON_PACK = LanguagePack(
+    language="python",
+    lang_slug="py",
+    grammar="python",
+    extensions=(".py",),
+    structure_queries=(_HERE / "structure.scm").read_text(encoding="utf-8"),
+    reference_queries=(_HERE / "references.scm").read_text(encoding="utf-8"),
+    descriptor_rules=DescriptorRules(
+        kinds={
+            "def.class": NodeKind.CLASS,
+            "def.function": NodeKind.FUNCTION,  # promoted to METHOD when nested in a class
+        }
+    ),
+)

agentforge_graph/ingest/packs/python/references.scm

@@ -0,0 +1,14 @@
+; Python reference queries (feat-002).
+; Calls only at v0.1: a plain call `f(...)` and an attribute call `recv.f(...)`.
+; @call.callee is the called name; @call.recv is the receiver (BUG-006), so the
+; resolver can bind `self.f()` to the enclosing class's method without guessing
+; for other receivers. The extractor attributes the call to its enclosing
+; definition and records it for pass-2 resolution.
+
+(call
+  function: (identifier) @call.callee) @call
+
+(call
+  function: (attribute
+    object: (_) @call.recv
+    attribute: (identifier) @call.callee)) @call

agentforge_graph/ingest/packs/python/structure.scm

@@ -0,0 +1,57 @@
+; Python structure queries (feat-002).
+; Each definition pattern captures the definition node (@def.<kind>) and its
+; identifier (@name) in one pattern, so the extractor pairs them via matches().
+; Imports capture the module and (for `from` imports) the bound names.
+
+; --- definitions ---
+(class_definition
+  name: (identifier) @name) @def.class
+
+(function_definition
+  name: (identifier) @name) @def.function
+
+; --- docstrings (DESCRIBES) ---
+; the first string in a def/class body is its docstring; the extractor turns it
+; into a DocChunk that DESCRIBES the symbol (feat-010). The `.` anchor restricts
+; the match to the *first* body statement, so a non-leading string is not one.
+(function_definition
+  body: (block . (string) @docstring)) @doc.owner
+(class_definition
+  body: (block . (string) @docstring)) @doc.owner
+
+; --- inheritance (INHERITS) ---
+; a base class named by a bare identifier: `class B(A)` -> base `A`.
+(class_definition
+  superclasses: (argument_list (identifier) @base.name)) @base.def
+
+; a qualified base `class B(mod.Base)` -> base `mod.Base`; the resolver splits the
+; receiver and binds it via the importing module alias (`import mod`).
+(class_definition
+  superclasses: (argument_list (attribute) @base.name)) @base.def
+
+; --- imports ---
+; `import a.b.c` -> module only (the receiver in code is the dotted path itself).
+(import_statement
+  name: (dotted_name) @import.module) @import
+
+; `import a.b.c as x` -> module + the alias `x` as the local binding name, so a
+; whole-module import bound to a short alias (`import numpy as np`) makes `np.f()`
+; / `extends np.Base` resolve to module `a.b.c`'s exports (BUG-006).
+(import_statement
+  name: (aliased_import
+    (dotted_name) @import.module
+    alias: (identifier) @import.default)) @import
+
+; `from a.b import c, d`  -> module + one or more bound names
+(import_from_statement
+  module_name: (dotted_name) @import.module
+  name: [(dotted_name) @import.name
+         (aliased_import (dotted_name) @import.name)]) @import
+
+; `from .mod import x` / `from . import x` (relative) -> the relative module
+; text (leading dots + optional name, e.g. `.utils`, `..pkg.mod`, `.`) + names.
+; resolve_import() resolves the dots against the importer's package (BUG-004).
+(import_from_statement
+  module_name: (relative_import) @import.module
+  name: [(dotted_name) @import.name
+         (aliased_import (dotted_name) @import.name)]) @import