Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
docs(core): shorten comments in the receiver-type scanner (#2577)
Raghav Chamadiya1bd288a1638e
diff --git a/packages/core/src/repowise/core/ingestion/languages/receiver_types.py b/packages/core/src/repowise/core/ingestion/languages/receiver_types.pyindex c0c31aa6f..0ddb6b140 100644--- a/packages/core/src/repowise/core/ingestion/languages/receiver_types.py+++ b/packages/core/src/repowise/core/ingestion/languages/receiver_types.py@@ -1,29 +1,22 @@"""What type is the receiver a call is made on.``user.save()`` names no type, so member resolution has nothing to look up.-The declaration that gives ``user`` its type is either inside the same function-— a parameter, a local, a catch or loop binding — or, when the receiver is a-field, at the enclosing class's own scope. In the C family both are written-``T name``, so one scan finds both and only the span they are read back over-differs. A language may order them the other way round: Go writes ``name T``-and declares a method's receiver in the signature, which the body span already-covers.+The declaration typing ``user`` is inside the same function (parameter, local,+catch or loop binding) or, for a field, at the enclosing class's scope; one+scan finds both and only the span they are read back over differs.The scan is allowed to be wrong. Nothing it returns becomes an edge until the-resolver has checked that the type actually declares the method, so a-mis-inference costs a missing edge and never a wrong one. That check is what-licenses matching declarations with a regex instead of a type checker.--Split in two on purpose. ``scan_declarations`` reads a whole file once and is-the expensive half; ``types_in_span`` and ``types_by_class`` narrow the result-and are nearly free. Scanning per body instead would re-read every line that-two spans share, and a class body contains all of its methods'.--Adding a language means adding its shapes to ``_LANGUAGE_PATTERNS``; a-language absent from it is excluded by construction. Two smaller tables sit-beside it: ``_FRAMEWORK_DECORATOR_TYPES``, for a decorator that changes what-the symbol it wraps is, and ``_PY_BINDINGS``, which says only that a name is-taken — a refusal rather than a type.+resolver has checked that the type declares the method, so a mis-inference+costs a missing edge, never a wrong one. That check is what licenses a regex+instead of a type checker.++``scan_declarations`` reads a whole file once (the expensive half);+``types_in_span`` and ``types_by_class`` narrow it nearly for free, where a+per-body scan would re-read every line two spans share.++Adding a language means adding its shapes to ``_LANGUAGE_PATTERNS``.+``_FRAMEWORK_DECORATOR_TYPES`` covers a decorator that changes what a symbol+is; ``_PY_BINDINGS`` says only that a name is taken, a refusal, not a type."""from __future__ import annotations@@ -41,21 +34,15 @@ from ..type_names import (unwrap_pointer_like,)-# A type as written before a declared name: optionally qualified, optionally-# generic to two levels of nesting, optionally an array. A third level yields-# no match, which is a deliberate ceiling — a deeper group needs a real bracket-# matcher, and failing to type a name costs an edge, never a wrong one.+# A type as written before a declared name: optionally qualified, generic to two+# levels, an array. A third level yields no match: a deliberate ceiling, since a+# deeper group needs a real bracket matcher._TYPE = r"[A-Z]\w*(?:\.\w+)*(?:<(?:[^<>]|<[^<>]*>)*>)?(?:\[\])*"-# ``T name`` closed by the punctuation that can end a declaration: an-# initialiser, a statement end, the next parameter, the end of a parameter-# list, or an enhanced-for colon. Requiring one of those is what keeps the-# pattern off ``(Foo) bar`` and ``foo(Bar.BAZ, qux)``, which have no space in-# the same place.-# The closer is captured because it is the only thing separating a field from-# a parameter at class scope — `T name;` against `T name,`. Some constructors-# and static methods are extracted as no symbol at all, so their parameter-# lists sit at class scope with nothing else to tell them apart.+# ``T name`` closed by punctuation that can end a declaration, which keeps it+# off ``(Foo) bar`` and ``foo(Bar.BAZ, qux)``. The closer is captured because it+# alone separates a field (`T name;`) from a parameter (`T name,`) at class+# scope, where unextracted constructors leave their parameter lists._TYPED_DECLARATION = re.compile(rf"(?<![\w.])(?P<type>{_TYPE})\s+(?P<name>[a-z_]\w*)\s*(?=(?P<closer>[=;,):]))")@@ -64,199 +51,104 @@ _INFERRED_FROM_NEW = re.compile(r"(?<![\w.])var\s+(?P<name>[a-z_]\w*)\s*=\s*new\s+(?P<type>[A-Z]\w*(?:\.\w+)*)")-# Truncating at ``//`` also truncates a URL inside a string literal. That can-# only ever lose a declaration, never invent one, which is the safe direction.+# Truncating at ``//`` also cuts a URL in a string: it can only lose a+# declaration, never invent one._LINE_COMMENT = re.compile(r"//.*")_HASH_COMMENT = re.compile(r"#.*")-# Python writes its documentation as a string literal in the body, which a-# comment strip does not reach. Prose is the one false-positive source the-# C-family shape never had — ``context: The caller`` reads as an annotation —-# so triple-quoted runs are blanked, keeping their newlines so line numbers-# survive.+# Docstring prose reads as annotations (``context: The caller``), so triple-quoted+# runs are blanked, keeping newlines so line numbers survive._DOCSTRING = re.compile(r"(\"\"\"|''')(?:.|\n)*?\1")-# A block comment, blanked to its newlines so line numbers survive. Kotlin-# needs this where Java and C# do not, and the asymmetry is in the shapes-# rather than in the languages: KDoc writes `@param connection: Store`, which-# is exactly Kotlin's `name: Type`, while javadoc's `@param connection the-# Store` is not the C family's `Type name`. Measured on the same text — the-# Kotlin scan fabricated `connection: Store` from prose and the Java scan-# returned nothing.-#-# Run before the line strip, not after: truncating at `//` first would eat the-# `*/` out of `/* see http://x */` and leave the opener unterminated. As with-# `//`, a `/*` inside a string literal is over-matched, which can only ever-# lose a declaration and never invent one.+# A block comment, blanked to its newlines. Needed where doc-comment prose+# matches the language's own shape: KDoc's `@param connection: Store` is+# Kotlin's `name: Type`, while javadoc's is not Java's `Type name`.+# Run before the line strip, or `//` would eat the `*/` of `/* see http://x */`._BLOCK_COMMENT = re.compile(r"/\*(?:.|\n)*?\*/")_NEWLINE = re.compile(r"\n")-# Python annotates after the name, not before it: ``x: T``, ``def f(x: T)``.-# The closer is what keeps the pattern off prose, and it is the reason a-# generic annotation is refused rather than mis-read — ``x: Optional[T]`` is-# followed by ``[``, so it matches nothing, which is right, since the value is-# an Optional and not a T.+# Python annotates after the name: ``x: T``. The closer keeps the pattern off+# prose and refuses a generic: ``x: Optional[T]`` is an Optional, not a T._PY_TYPE = r"[A-Z]\w*(?:\.\w+)*"_PY_ANNOTATED = re.compile(rf"(?<![\w.])(?P<name>[a-z_]\w*)\s*:\s*(?P<type>{_PY_TYPE})\s*(?=(?P<closer>[=,)\]\n]))")-# ``x = T(...)``, the only shape unannotated Python offers. Bare-named on-# purpose: ``x = Foo.bar(...)`` is a call on a class rather than a-# construction, and typing ``x`` as ``Foo`` from it would simply be wrong.-# Anchored to the start of a statement because ``dispatch(logger=Emitter())``-# is otherwise read as declaring ``logger``, which then answers for a-# ``logger`` that came from somewhere else entirely. The C family is safe from-# that shape only because its equivalent needs the ``var`` keyword.+# ``x = T(...)``. Bare-named: ``x = Foo.bar(...)`` is a call on a class, not a+# construction. Anchored to a statement start, or ``dispatch(logger=Emitter())``+# would read as declaring ``logger``._PY_CONSTRUCTED = re.compile(r"(?m)^[ \t]*(?P<name>[a-z_]\w*)\s*=\s*(?P<type>[A-Z]\w*)\s*\(")-# Go writes the name before the type, so none of the C-family shapes above-# match a line of it. Two further differences decide these patterns.-#-# A type name may be lowercase, because that is how Go spells an unexported-# one, and a private method hangs off exactly those. Admitting lowercase is-# only safe because the language spec carries every predeclared identifier in-# ``builtin_types``, so ``string`` and ``error`` are refused downstream rather-# than looked up.-#-# The receiver a method is declared on — ``func (s *Server) handle()`` — is-# written in the signature rather than the body, and it is the largest shape-# by some way: 50.2% of the reachable population over five Go repos, against-# 24.1% for parameters and 21.5% for composite literals. It needs no scope of-# its own, because a function symbol's span starts at its ``func`` line, so-# the body scan already reads it.+# Go writes the name before the type. A type may be lowercase (unexported);+# that is safe only because ``builtin_types`` carries every predeclared+# identifier, so ``string`` and ``error`` are refused downstream. A method's+# receiver sits in the signature, which the function span already covers._GO_NAME = r"[a-z_]\w*"_GO_TYPE = r"[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)?"-# A parameter, a named return, or a method's own receiver: ``name Type``-# juxtaposed before a comma or the end of the list. Juxtaposition is a-# declaration nearly everywhere it is legal in Go, which is why this needs-# less guarding than the C family's did.-#-# ``func (s *Server) handle()`` needs no pattern of its own — the receiver-# group presents as ``s *Server)`` and is matched here. A separate anchored-# pattern for it was measured and removed: it added a whole-file scan and-# changed no edge on any of the five Go repos.-#-# ``a * b`` is not matched because gofmt spaces a binary operator on both-# sides while a pointer type binds tight, and Go source is gofmt'd.+# A parameter, named return, or method receiver (``s *Server)``): ``name Type``+# before a comma or the list end. Juxtaposition is a declaration nearly+# everywhere Go allows it. ``a * b`` is not matched because gofmt spaces binary+# operators while a pointer type binds tight._GO_PARAM = re.compile(rf"(?<![\w.])(?P<name>{_GO_NAME})\s+\*?(?P<type>{_GO_TYPE})\s*(?=[,)])")-# ``x := Foo{}``, ``x := &Foo{}``, ``x := y.(Foo)`` and ``x, ok := y.(Foo)``.-# One scan rather than two: both shapes are a short declaration whose type is-# written outright, and they differ only in what brackets it. The closing-# ``{`` or ``)`` is what tells them from ``x := f()``, whose type is a return-# value this phase deliberately does not chase.-#-# ``x := []Foo{}`` and ``x := map[k]Foo{}`` match nothing on purpose: the-# value is a slice or a map, and typing ``x`` as ``Foo`` would be wrong rather-# than merely unhelpful.+# ``x := Foo{}``, ``x := &Foo{}``, ``x := y.(Foo)``, ``x, ok := y.(Foo)``. The+# closing ``{`` or ``)`` tells them from ``x := f()``, whose return type is not+# chased. ``[]Foo{}`` and ``map[k]Foo{}`` match nothing: the value is not a Foo._GO_SHORT_DECL = re.compile(rf"(?<![\w.])(?P<name>{_GO_NAME})\s*(?:,\s*{_GO_NAME}\s*)?:="rf"\s*(?:&|[\w.]+\.\(\*?)?(?P<type>{_GO_TYPE})\s*(?:\{{|\))")-# ``var x Foo`` / ``var x *Foo``. The smallest shape in every Go repo-# measured — 2.5% of the reachable population — and kept only because it is-# the one shape neither pattern above reaches.+# ``var x Foo`` / ``var x *Foo``: rare, but no pattern above reaches it._GO_VAR_DECL = re.compile(rf"(?<![\w.])var\s+(?P<name>{_GO_NAME})\s+\*?(?P<type>{_GO_TYPE})")-# Kotlin annotates after the name, as Python does, and one shape reaches every-# declaration that matters: `val x: Foo`, `var x: Foo`, `fun f(x: Foo)` and a-# primary constructor's `class A(val x: Foo)` are all `name: Type`. Measured-# over ktor and exposed, that one shape is 6,291 typed `val`s, 1,242 `var`s and-# ~8,800 parameters, against 1,183 for the constructor shape below.-#-# The type reuses the C family's `_TYPE`, so a generic is matched and reduced to-# its bare name. That is right in Kotlin and wrong in Python for the same-# reason spelled backwards: `List<Foo>` bares to `List`, a builtin the language-# spec refuses downstream, while `Column<T>` bares to `Column`, which is the-# type the value actually has. Python's `Optional[T]` had no such reading, which-# is why `_PY_ANNOTATED` refuses a generic outright.+# Kotlin annotates after the name, and `val x: Foo`, `var x: Foo`, parameters+# and `class A(val x: Foo)` are all `name: Type`.#-# A trailing `?` is consumed rather than refused: `Foo?` is still a `Foo` at the-# call site, and it is 15% of ktor's typed declarations.+# A generic bares to its head, which is right here (unlike Python's+# `Optional[T]`): `List<Foo>` bares to a builtin refused downstream, `Column<T>`+# to the value's real type. A trailing `?` is consumed: `Foo?` is still a `Foo`.#-# `by` closes a declaration as well as the punctuation does. `val x: Foo by-# lazy { ... }` is a delegated property, `x` is a `Foo`, and without this the-# whole idiom types nothing. It is a word rather than a symbol, so it is an-# alternation and not another character in the class — and it can never be a-# field closer, which is the conservative reading: a delegated property at-# class scope stays untyped rather than being guessed at.+# `by` closes a delegated property (`val x: Foo by lazy {}`), but never as a+# field closer, so a delegated property at class scope stays untyped.#-# The `val`/`var` keyword is captured, optional, and read by nothing except-# field classification. A parameter is `name: Type` with no keyword, and a-# primary constructor's `class C(timeout: Duration = 5.seconds)` therefore-# closes on `=` at class scope exactly as a real property does — so without-# this group `timeout` is registered as a field it is not, since a parameter-# with no `val`/`var` is not a property and no method body can name it.-# Blanking the closer is what refuses it; body typing is unaffected either-# way, because only `types_by_class` reads a closer at all.+# The `val`/`var` keyword is captured for field classification only: a+# constructor parameter with a default (`class C(timeout: Duration = 5.seconds)`)+# closes on `=` at class scope like a property but is not one, and a match+# without the keyword gets its closer blanked.#-# `(` is deliberately not a closer. It is what keeps the pattern off an-# annotation use-site target — `@get:JvmName("x")` reads as `get: JvmName`.-#-# A function type's own parameters are reached incidentally: `statement:-# Transaction.(dest: Dest) -> Unit` presents `dest: Dest` to the same pattern.-# That is kept rather than excluded — the hand-read found 3 such rows and all-# 3 were right, and the validator makes a wrong one cost an edge, not an error.+# `(` is not a closer, which keeps the pattern off `@get:JvmName("x")`._KT_ANNOTATED = re.compile(rf"(?<![\w.])(?:(?P<keyword>va[lr])\s+)?(?P<name>[a-z_]\w*)\s*:\s*"rf"(?P<type>{_TYPE})\??\s*(?=(?P<closer>[=,)\n]|by\b))")-# `val x = Foo(...)`, the shape an inferred Kotlin declaration takes. Anchored-# to `val`/`var` rather than to the start of a statement, which is what Python's-# equivalent needed: Kotlin spells a named argument with `=` too, so-# `dispatch(logger = Emitter())` is otherwise read as declaring `logger`.-# Bare-named on purpose — `val x = Foo.bar()` is a call on a class, and typing-# `x` as `Foo` from it would simply be wrong.-#-# The lookahead refuses a chain: `val x = Builder().build()` makes `x` whatever-# `build()` returns, not a `Builder`, and typing it as one is a wrong answer-# rather than a missing one. `_PY_CONSTRUCTED` has the same shape and does not-# refuse it; moving Python is its own measured change and is not made here.-# `[^()]*` cannot cross a nested call, so `Foo(bar(1)).baz()` is still typed ---# a stated ceiling, and the same direction of error as today rather than a new-# one.+# `val x = Foo(...)`. Anchored to `val`/`var`, since a named argument+# `dispatch(logger = Emitter())` also uses `=`; bare-named, since `Foo.bar()` is+# a call on a class. The lookahead refuses a chain (`Builder().build()` is not+# a `Builder`); `_PY_CONSTRUCTED` does not refuse one yet. Ceiling: `[^()]*`+# cannot cross a nested call, so `Foo(bar(1)).baz()` is still typed._KT_CONSTRUCTED = re.compile(r"(?<![\w.])va[lr]\s+(?P<name>[a-z_]\w*)\s*=\s*(?P<type>[A-Z]\w*)\s*\((?![^()]*\)\s*\.)")-# Swift annotates after the name as Kotlin does, and the same one shape reaches-# more of the language than it does of Kotlin: `let x: Foo`, `var x: Foo` and-# all three parameter spellings are `name: Type`.-#-# The argument label is the reason to anchor on the colon rather than on the-# bracket that opens the list. Swift writes a parameter as `f(x: Foo)`,-# `f(_ x: Foo)` or `f(label x: Foo)`, and in the last of those the declared-# name is the *second* identifier. A pattern anchored at `(` or `,` takes the-# label instead and is wrong 736 times over swift-nio and Alamofire. The-# identifier adjacent to the colon is the declared name in all three-# spellings, with no branch on any of them.-#-# Measured over those two repos, this one shape is 88% of the declaration-# population: 4,001 single-name parameters, 2,876 stored properties, 2,104-# `var`s, 1,356 underscore-label parameters, 1,304 `let`s and 736 two-name-# parameters. The construction shape below is a further 6%.-#-# `some`/`any` is consumed rather than refused: an opaque or existential-# `some Foo` is a `Foo` at the call site, as a trailing `?` or `!` is.+# Swift annotates after the name: `let x: Foo`, `var x: Foo` and every parameter+# spelling are `name: Type`. Anchored on the colon, not the opening bracket,+# because in `f(label x: Foo)` the declared name is the identifier next to the+# colon, not the label.#-# `[Foo]` and `[K: V]` match nothing on purpose — the value is an Array or a-# Dictionary, and typing the name as `Foo` would be wrong rather than merely-# unhelpful. `]` stays out of the closer set for the same reason: it is what a-# dictionary type's inner `k: V` would otherwise close on.+# `some`/`any`, `?` and `!` are consumed: the value is still a `Foo`. `[Foo]`+# and `[K: V]` match nothing (an Array or Dictionary), and `]` is not a closer+# so a dictionary's inner `k: V` cannot close.#-# The `let`/`var` keyword is captured for the reason Kotlin's is: an-# initialiser's `init(timeout: Duration = .seconds(5))` sits at type scope and-# closes on `=` exactly as a stored property does, and it is a parameter-# rather than a property. Only a keyword-bearing match may own a field.+# The `let`/`var` keyword is captured as in Kotlin: an `init(timeout: ... = ...)`+# parameter closes on `=` at type scope but is not a property._SWIFT_ANNOTATED = re.compile(rf"(?<![\w.])(?:(?P<keyword>let|var)\s+)?(?P<name>[a-z_]\w*)\s*:\s*"rf"(?:(?:some|any)\s+)?(?P<type>{_TYPE})[?!]?\s*(?=(?P<closer>[=,)\n{{]))"@@ -269,14 +161,10 @@ _SWIFT_CONSTRUCTED = re.compile(r"(?<![\w.])(?:let|var)\s+(?P<name>[a-z_]\w*)\s*=\s*(?P<type>[A-Z]\w*)\s*\((?![^()]*\)\s*\.)")-# C++ writes the C family's ``T name``, with three differences ``_TYPE`` cannot-# read: ``::`` qualifies rather than ``.``, a pointer or reference star binds-# between the type and the name, and a lowercase head is ordinary rather than a-# Go-style unexported one, because every STL type is written that way.-#-# A keyword head is refused outright. Without it ``struct foo {`` and-# ``namespace foo {`` present as ``struct``/``namespace`` naming a ``foo``, and-# ``auto`` would be read as a type rather than as the absence of one.+# C++ writes ``T name`` with differences ``_TYPE`` cannot read: ``::`` qualifies,+# ``*``/``&`` bind between type and name, and lowercase heads (the STL) are+# ordinary. A keyword head is refused, or ``struct foo {`` would declare ``foo``+# and ``auto`` would read as a type._CPP_KEYWORDS = (r"(?:const|constexpr|consteval|constinit|static|mutable|volatile|extern|"r"inline|virtual|explicit|friend|typedef|using|namespace|template|typename|"@@ -285,24 +173,16 @@ _CPP_KEYWORDS = (r"operator|sizeof|decltype|noexcept|co_await|co_return|co_yield)")-# Two levels of nesting, the same ceiling ``_TYPE`` states and for the same-# reason: a third needs a real bracket matcher, and failing to type a name-# costs an edge rather than inventing one.+# Two levels of nesting: the same ceiling as ``_TYPE``._CPP_TYPE = r"(?:[A-Za-z_]\w*\s*::\s*)*[A-Za-z_]\w*(?:\s*<(?:[^<>]|<[^<>]*>)*>)?"# ``T name``, ``T* name``, ``T& name``, ``ns::T name``, ``W<T> name``, closed by# the same punctuation the C family requires plus ``{`` for brace init.#-# ``(`` is deliberately NOT a closer, and it is load-bearing twice. ``Status-# doIt(int x);`` is a method declaration and not a variable of type ``Status``,-# and it is the commonest line in a C++ header. Excluding it also drops ``Foo-# bar(args);``, a real construction -- that costs an edge, which is the safe-# direction, and it additionally keeps a constructed local from being read at a-# scope where a same-named field would answer instead.-#-# ``>`` and ``:`` sit in the lookbehind so the scan cannot restart inside a-# type it has already read: without them ``std::shared_ptr<Foo>& p`` matches a-# second time at ``shared_ptr``.+# ``(`` is NOT a closer: ``Status doIt(int x);`` is a method declaration, the+# commonest line in a header. That also drops ``Foo bar(args);``, costing an+# edge, the safe direction. ``>`` and ``:`` in the lookbehind stop a restart+# inside a type already read (``std::shared_ptr<Foo>& p``)._CPP_DECLARATION = re.compile(rf"(?<![\w.>:])(?!{_CPP_KEYWORDS}\b)(?P<type>{_CPP_TYPE})"rf"(?:\s*[*&]{{1,2}}\s*|\s+)(?P<name>[a-z_]\w*)\s*(?=(?P<closer>[=;,){{]))"@@ -310,9 +190,8 @@ _CPP_DECLARATION = re.compile(_C_FAMILY = (_TYPED_DECLARATION, _INFERRED_FROM_NEW)-# No Go shape captures a closer, so every Go declaration carries ``""`` and-# class scope would drop all of them. That is the intended reading: Go is not-# in IMPLICIT_FIELD_LANGUAGES and must not be.+# No Go shape captures a closer, so class scope drops every Go declaration:+# intended, since Go is not in IMPLICIT_FIELD_LANGUAGES._GO_FAMILY = (_GO_PARAM, _GO_SHORT_DECL, _GO_VAR_DECL)_KT_FAMILY = (_KT_ANNOTATED, _KT_CONSTRUCTED)_SWIFT_FAMILY = (_SWIFT_ANNOTATED, _SWIFT_CONSTRUCTED)@@ -329,30 +208,17 @@ _LANGUAGE_PATTERNS: dict[str, tuple[re.Pattern[str], ...]] = {RECEIVER_TYPE_LANGUAGES = frozenset(_LANGUAGE_PATTERNS)-# Languages where a field can be named with no qualifier, which is the only-# thing that lets a class-scope declaration answer for a bare receiver. Python-# writes ``self.foo.bar()``, whose receiver is dotted and which our grammar-# queries mint no call site for at all — so class scope has nothing there to-# answer, and consulting it could only bind a bare local name to a field.-#-# Kotlin is here on a count rather than on its semantics, which is the lesson-# the Python attempt cost: Python has implicit field access too, and-# registering it would have promised nothing, because only 1.8% of its field-# receivers are typed where this scan looks. Kotlin declares a property at-# class scope in its own idiom, and the scan does find them — 56 of ktor's-# 1,349 gained edges and 100 of exposed's 320, hand-read 10/10 correct. Small,-# and measured.-#-# Only a `val`/`var` reaches class scope. A primary-constructor parameter with-# a default closes on `=` there too and is not a property at all, which is why-# `_KT_ANNOTATED` captures the keyword.+# Languages where a field can be named with no qualifier, the only case where a+# class-scope declaration may answer for a bare receiver. Python is absent: it+# writes ``self.foo.bar()``, a dotted receiver the grammar mints no call site+# for, so class scope could only bind a bare local to a field. Membership rests+# on the scan actually finding typed fields in the language's idiom.IMPLICIT_FIELD_LANGUAGES = frozenset({"csharp", "java", "kotlin", "swift"})# A decorator that changes what the symbol it wraps *is*: `@shared_task` leaves-# no function behind, so `add.s(...)` is a method call and `(Task, s)` a-# checkable pair. A table, not an inference — the decorator lives in the-# framework, which an application imports rather than vendors. Ceiling: an entry-# earns nothing unless the repo also declares the type.+# no function behind, so `add.s(...)` is a method call on `Task`. A table, since+# the decorator lives in an imported framework. Ceiling: an entry earns nothing+# unless the repo also declares the type._FRAMEWORK_DECORATOR_TYPES: dict[str, tuple[tuple[re.Pattern[str], str], ...]] = {"python": (# celery: `@task`, `@shared_task`, `@app.task`, `@celery.task`, bare or@@ -364,14 +230,12 @@ _FRAMEWORK_DECORATOR_TYPES: dict[str, tuple[tuple[re.Pattern[str], str], ...]] =FRAMEWORK_DECORATOR_LANGUAGES = frozenset(_FRAMEWORK_DECORATOR_TYPES)-# Every shape that binds a name in a Python body, whatever its value. The-# framework scope must refuse a name the body rebinds: `fail = signature(...)`-# leaves `fail` a Signature, and the CapWords-only scan above cannot see it.-# Over-matching is safe here — refusing only ever costs an edge.+# Every shape that binds a name in a Python body, whatever its value, so the+# framework scope can refuse a rebound name (`fail = signature(...)`) that the+# CapWords-only scan cannot see. Over-matching only costs an edge.-# A comma-separated target list: every name in `a, b[0], c.d = ...` and in-# `for a, b in ...`. Read whole and split by the caller, so a subscript or an-# attribute in any position cannot hide the bare names beside it.+# A comma-separated target list (`a, b[0], c.d = ...`, `for a, b in ...`), split+# by the caller so a subscript or attribute cannot hide the bare names beside it._TARGETS = r"[\w.\[\]]+(?:\s*,\s*[\w.\[\]]+)*"_PY_TARGET_LISTS = (@@ -394,9 +258,8 @@ _PY_BINDINGS = (re.compile(r"\b(?:def\s+\w+\s*\(|lambda\s+)[^)\n:]*?\b(?P<name>[a-z_]\w*)\s*(?=[,=)\n:])"),)-# A plain `import` inside a body is deliberately absent: it names the same-# module symbol this scope resolves against, and refusing it cost 3 correct-# edges on celery (`from .tasks import ping`, then `ping.delay()`).+# A plain `import` in a body is deliberately absent: it names the same module+# symbol this scope resolves against (`from .tasks import ping`; `ping.delay()`)._PY_IDENTIFIER = re.compile(r"^[a-z_]\w*$")@@ -470,10 +333,9 @@ class Declaration(NamedTuple):``closer`` is the punctuation that ended the declaration, or empty wherethe shape has none. Only class scope reads it.- ``unwrapped`` marks a type taken from inside a pointer-like wrapper rather- than written outright. The two spellings answer differently depending on- which operator the call used, and the caller that cannot see the operator- reads this to refuse the ambiguous names.+ ``unwrapped`` marks a type taken from inside a pointer-like wrapper, which+ answers differently by call operator; a caller that cannot see the+ operator refuses these names."""line: int@@ -491,10 +353,9 @@ _FIELD_CLOSERS = frozenset({";", "="})def _nests_in_a_builtin(raw: str, language: str) -> bool:"""True for ``Map.Entry`` and its kind — a member type of a builtin.- Taking the bare name of one of these answers ``Entry``, which the repo may- well declare somewhere and which the declaration never meant. Discarding a- qualifier is right when the qualifier is a package; it is wrong when the- qualifier is a type, and a builtin head is the case we can tell apart.+ Its bare name ``Entry`` may match an unrelated repo type. Dropping a+ package qualifier is right, a type qualifier wrong, and a builtin head is+ the type case that can be told apart."""if "." not in raw:return False@@ -505,11 +366,8 @@ def _nests_in_a_builtin(raw: str, language: str) -> bool:def _usable_type_name(raw: str, language: str) -> tuple[str | None, bool]:"""``(bare name, unwrapped)`` for *raw*, or ``(None, False)``.- C++ is the one language that looks inside the spelling: ``shared_ptr<Foo>``- denotes a ``Foo`` at every call the arrow can reach, and taking the head- would answer ``shared_ptr``, which names no repo symbol and resolves- nothing. Every other language keeps the head, where a generic really is- the type the value has.+ Only C++ looks inside the spelling: ``shared_ptr<Foo>`` is a ``Foo`` behind+ the arrow. Elsewhere the generic head is the value's real type."""if _nests_in_a_builtin(raw, language):return None, False@@ -552,9 +410,8 @@ def scan_declarations(text: str, language: str) -> tuple[Declaration, ...]:if type_name is None:continuegroups = match.groupdict()- # A shape that names a declaration keyword and did not match one- # is not a declaration that can own a field — see `_KT_ANNOTATED`.- # Shapes with no `keyword` group are unaffected.+ # A keyword-capable shape without its keyword cannot own a field+ # (see `_KT_ANNOTATED`).closer = groups.get("closer") or ""if "keyword" in groups and not groups["keyword"]:closer = ""@@ -575,10 +432,9 @@ def scan_declarations(text: str, language: str) -> tuple[Declaration, ...]:def _record(types: dict[str, str | None], declaration: Declaration) -> None:"""Add one declaration to a scope, or mark the name unanswerable.- A name declared twice with two types maps to ``None`` rather than being- dropped. A caller has to tell "this scope says nothing about the name"- from "this scope says something unusable about it", because only the first- of those may fall through to a wider scope.+ A name declared with two types maps to ``None`` rather than being dropped:+ only "says nothing" may fall through to a wider scope, not "says something+ unusable"."""if declaration.name not in types:types[declaration.name] = declaration.type_name@@ -594,9 +450,7 @@ def types_in_span("""``{name: type}`` for the declarations inside one function body."""types: dict[str, str | None] = {}- # Bisected rather than skipped over: a file's bodies each ask once, so- # walking from the front every time is quadratic in a large file, and that- # — not the regex — was what the scan actually cost.+ # Bisected: walking from the front for every body is quadratic in a large file.first = bisect_left(declarations, start_line, key=lambda d: d.line)for declaration in declarations[first:]:if declaration.line > end_line: