Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

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.py
index 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 where
the 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:
continue
groups = 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: