bmad-module-skill-forge 4.0.0 → 5.0.0

package/src/shared/scripts/skf-verify-provenance-completeness.py

@@ -89,7 +89,19 @@ name (`App.update`) it is the last segment. The rules follow the
     a keyword argument or a parameter never matches; a file that does not
     tokenize is matched line by line. A `from X import *` line counts only
     when no other line of the file defines NAME (a re-export the
-    extraction could not trace is cited at its star import).
+    extraction could not trace is cited at its star import). An
+    `@overload` group, where every line found is a `def` / `async def
+    NAME` line at one indentation in one enclosing block (one class, not
+    two) and every one but at most the last has `@overload` or
+    `@<module>.overload` (`@typing.overload`,
+    `@typing_extensions.overload`, `@t.overload` after
+    `import typing as t`) in its contiguous decorator block, defines NAME
+    at each of its lines, the stubs and the implementation. A comment line
+    may sit in the decorator block, and so may a decorator's arguments on
+    lines of their own, unless the file does not tokenize. A recorded line
+    that misses the group gives its first line alone, which is its first
+    stub: the public-API runner, its merge rule and the structural diff
+    all record that line, so `fix` can move the entry there.
   - TS/JS (`.ts`, `.tsx`, `.mts`, `.cts`, `.js`, `.jsx`, `.mjs`, `.cjs`): a
     `function` (or `function*`), `class`, `interface`, `type`, `enum`,
     `namespace`, `const`, `let` or `var` declaration of NAME, with any of
@@ -98,7 +110,11 @@ name (`App.update`) it is the last segment. The rules follow the
     and `class`; a name inside a decorator's arguments is not declared);
     a later declarator of a `const`, `let` or `var` list
     (`export const a = 1, NAME = 2;`, or `export const a = 1,` then
-    `  NAME = 2;` as Prettier writes it: see Declarator lists below); NAME
+    `  NAME = 2;` as Prettier writes it: see Declarator lists below);
+    NAME bound by a destructuring pattern that begins such a list
+    (`export const { a, b: NAME } = obj;`, `const [NAME] = list`, the
+    pattern on one line or several), on the line where NAME appears (see
+    Declarator lists below); NAME
     on the line right after a line that ends in its declaration keyword
     (`export function`, `export interface`, `export const` and so on),
     which is the line cited;
@@ -125,14 +141,23 @@ name (`App.update`) it is the last segment. The rules follow the
 Declarator lists: a `const`, `let` or `var` list is split at its
 top-level commas, outside strings, regular expression literals and
 brackets, a type-argument list included (`Map<K, V>`: a `<` right after
-a name), up to a top-level `;`, and a destructuring pattern declares
-nothing. The list goes on to the next line when a line ends inside a
-bracket, after a top-level comma or after an operator waiting for its
-operand, or when the next line starts with an operator (a member chain or
-a ternary broken over lines), so a declarator on a line of its own
-counts. A `<` where an expression begins (JSX, a type assertion, a generic
+a name), up to a top-level `;`. The list goes on to the next line when a
+line ends inside a bracket, after a top-level comma or after an operator
+waiting for its operand, or when the next line starts with an operator (a
+member chain or a ternary broken over lines), so a declarator on a line
+of its own counts. A `<` where an expression begins (JSX, a type assertion, a generic
 arrow function's type parameters) is not followed: no later declarator of
-the list counts after it.
+the list counts after it. A destructuring pattern that begins the list,
+on the keyword's line, declares the names it binds: a shorthand key, the
+target after `key:`, an array element, a rest `...NAME` and the names of
+a nested pattern, each on the line where it appears (the pattern may
+span lines), with its statement's column. A renamed or computed key, a
+default value, the type annotation after the pattern and anything inside
+a string or a comment bind nothing, and neither does a pattern that does
+not close. The later declarators after a pattern count as any others. A
+pattern that is a later declarator (`export const a = 1, { b } = c`) or
+that sits on the line after a split keyword (`export const`, then
+`  { b } = c;`) is not covered: it declares nothing.
 
 Indentation: for a dotted name every match counts. For an undotted name,
 matches at any indentation count, but when the file has a column-0 match
@@ -140,7 +165,8 @@ the indented ones are dropped, so a local shadow never outranks the
 module-level definition. A line inside a multi-line import, export list
 or `module.exports` object takes the column of the line its statement
 starts on, and so do the name line of a declaration split after its
-keyword and a later declarator on a line of its own. When the recorded
+keyword, a later declarator on a line of its own and the line of a name
+a destructuring pattern binds. When the recorded
 line is itself an indented match that this rule dropped (a method
 recorded under an undotted name beside a module-level function of the
 same name), the finding lists the recorded line too, so it carries
@@ -149,7 +175,11 @@ several lines and no caller auto-moves it.
 Entries in other files, and entries whose `export_type` is `module` or
 `package` (case-insensitive; neither has a definition line), are skipped
 and counted in `summary.line_check_skipped`. A `line-not-definition` item
-lists every defining line in the file in `definition_lines`. An empty list
+lists every defining line in the file in `definition_lines`, the recorded
+line included when it is an indented match the column-0 rule dropped (see
+Indentation). The one exception is a Python `@overload` group: it lists
+the group's first line alone, unless the recorded line is such a dropped
+indented match, which still gives several lines. An empty list
 means the rules found no definition line, which may be a shape they do not
 cover: the entry is unverified, not gone, and no caller auto-fixes it.
 
@@ -387,7 +417,8 @@ Subcommands:
       }
 
     With `--line`, a recorded line that is an indented match the column-0
-    rule dropped joins `definition_lines`, as in `verify`.
+    rule dropped joins `definition_lines`, and one that misses a Python
+    `@overload` group gives its first line alone, as in `verify`.
 
   classify-stale --names <coverage.json> --provenance <provenance-map.json>
                  --source-root <path> [--inventory <inventory.json>]
@@ -450,8 +481,9 @@ Subcommands:
     `export default NAME`, an export-list item without `as`, a
     `module.exports` shorthand key, a binding whose value is an import
     (`require(...)` or `(await) import(...)`, on its line or the next:
-    `const NAME = require(...)`, `exports.NAME = require(...)`,
-    `{ NAME: require(...) }`), an indented line and any line of a Python
+    `const NAME = require(...)`, `const { NAME } = require(...)`,
+    `exports.NAME = require(...)`, `{ NAME: require(...) }`), an
+    indented line and any line of a Python
     file that does not tokenize never count. A module or package named
     NAME (`NAME.py`, `NAME/__init__.py`, a TS/JS `NAME.<ext>` or
     `NAME/index.<ext>`) declares NAME too: at its line 1 when no line of it
@@ -599,6 +631,7 @@ Exit codes:
 from __future__ import annotations
 
 import argparse
+import bisect
 import copy
 import importlib.util
 import io
@@ -913,6 +946,10 @@ _PY_SPLIT_DECL_RE = re.compile(r"^\s*(?:async\s+def|def|class)\s*\\$")
 # A line that can matter to a name it does not hold: an import (which may go
 # on over the next lines) or a `def \` / `class \` whose name is on the next.
 _PY_NAMELESS_MATCH_RE = re.compile(r"^\s*(?:from|import|async|def|class)\b")
+# The decorator of an `@overload` stub, imported by name or used through its
+# module under any name (`typing`, `typing_extensions`, `t` after
+# `import typing as t`).
+_PY_OVERLOAD_RE = re.compile(r"^\s*@\s*(?:[A-Za-z_]\w*\.)?overload\s*$")
 # Tokens that never begin a statement.
 _PY_LAYOUT_TOKENS = frozenset(
     {
@@ -989,6 +1026,11 @@ _DECL_MAYBE = "maybe"
 # What `_js_declarators` gives: None, or (brackets left open, how) the list
 # goes on with, and the pieces that begin a declarator.
 _DeclSplit = tuple[tuple[str, str] | None, list[str]]
+# What `_js_destructured` gives for a `const` / `let` / `var` statement
+# whose first declarator is a destructuring pattern: the (name, line) of
+# each name it binds, and the (line, text after the `=` on that line) its
+# initializer starts at, None when it has none.
+_PatternDecl = tuple[list[tuple[str, int]], tuple[int, str] | None]
 # After one of these, `/` begins a regular expression and `<` begins JSX, a
 # type assertion or a generic arrow function's type parameters.
 _JS_EXPRESSION_START = frozenset("([{,;=?:&|^%+-*/<>!~")
@@ -1105,15 +1147,17 @@ def _js_code_lines(lines: list[str]) -> list[str]:
 
 
 class _SourceCache:
-    """Source lines, Python statement starts and TS/JS comment-free lines,
-    read once per file, and TS/JS declarator lists, split once per line
-    (the split does not depend on the export looked up)."""
+    """Source lines, Python statement starts, TS/JS comment-free lines and
+    the names TS/JS destructuring patterns bind, read once per file, and
+    TS/JS declarator lists, split once per line (neither depends on the
+    export looked up)."""
 
     def __init__(self) -> None:
         self._lines: dict[Path, list[str] | None] = {}
         self._starts: dict[Path, set[int] | None] = {}
         self._js_code: dict[Path, list[str]] = {}
         self._js_quiet: dict[Path, list[bool]] = {}
+        self._js_patterns: dict[Path, dict[int, _PatternDecl]] = {}
         self._js_decl: dict[tuple[str, str, bool], _DeclSplit] = {}
 
     def lines(self, path: Path) -> list[str] | None:
@@ -1136,6 +1180,13 @@ class _SourceCache:
             self._js_quiet[path] = _js_quiet_lines(code_lines)
         return self._js_quiet[path]
 
+    def js_destructured(
+        self, path: Path, code_lines: list[str]
+    ) -> dict[int, _PatternDecl]:
+        if path not in self._js_patterns:
+            self._js_patterns[path] = _js_destructured(code_lines)
+        return self._js_patterns[path]
+
     def js_declarators(
         self, text: str, opened: str = "", fresh: bool = True
     ) -> _DeclSplit:
@@ -1269,6 +1320,76 @@ def _python_definition_lines(
     return found or star_imports
 
 
+def _py_overloaded(lines: list[str], number: int, starts: set[int] | None) -> bool:
+    """True when the `def` on line `number` has `@overload` or
+    `@<module>.overload` (`@typing.overload`, `@t.overload`) in its
+    contiguous decorator block: the decorator lines at its indentation
+    right above it, up to a blank line or a line that is not a decorator.
+    A comment line is passed over, and so, in a file that tokenizes, is a
+    line on which no statement begins (a decorator's arguments over
+    several lines)."""
+    text = lines[number - 1]
+    indent = text[: len(text) - len(text.lstrip())]
+    i = number - 1
+    while i >= 1:
+        text = lines[i - 1]
+        code = text.split("#", 1)[0]
+        if not text.strip():
+            return False
+        if not code.strip() or (starts is not None and i not in starts):
+            i -= 1
+            continue
+        if not code.lstrip().startswith("@") or text[: len(text) - len(text.lstrip())] != indent:
+            return False
+        if _PY_OVERLOAD_RE.match(code):
+            return True
+        i -= 1
+    return False
+
+
+def _py_enclosing_line(
+    lines: list[str], number: int, indent: str, starts: set[int] | None
+) -> int | None:
+    """The line of the block that holds the statement on line `number`,
+    indented by `indent`: the nearest line above it where a statement
+    begins with less indentation. None at module level."""
+    i = number - 1
+    while indent and i >= 1:
+        text = lines[i - 1]
+        if text.split("#", 1)[0].strip() and (starts is None or i in starts):
+            if len(text) - len(text.lstrip()) < len(indent):
+                return i
+        i -= 1
+    return None
+
+
+def _python_overload_start(
+    lines: list[str], name: str, defs: list[int], starts: set[int] | None
+) -> int | None:
+    """The first of `defs` when they are one `@overload` group: two lines
+    or more, each a `def` / `async def NAME` line, all at one indentation
+    in one enclosing block (`_py_enclosing_line`, so two classes'
+    methods never make one group), and each but at most the last
+    decorated as an overload (`_py_overloaded`). None otherwise."""
+    if len(defs) < 2:
+        return None
+    decl = re.compile(rf"^(\s*)(?:async\s+def|def)\s+{re.escape(name)}(?!\w)")
+    indents = set()
+    for number in defs:
+        m = decl.match(lines[number - 1].split("#", 1)[0])
+        if m is None:
+            return None
+        indents.add(m.group(1))
+    if len(indents) > 1:
+        return None
+    (indent,) = indents
+    if len({_py_enclosing_line(lines, number, indent, starts) for number in defs}) > 1:
+        return None
+    if not all(_py_overloaded(lines, number, starts) for number in defs[:-1]):
+        return None
+    return defs[0]
+
+
 def _js_export_item_binds(item: str, name: str, alias_only: bool = False) -> bool:
     """True when one `export { ... }` item exposes `name`: the name after
     `as`, else (unless `alias_only`) the item's own name, an identifier or
@@ -1469,6 +1590,252 @@ def _js_paren_tail_is_call(after_open: str) -> bool:
     return False
 
 
+def _js_pattern_bindings(
+    text: str, start: int
+) -> tuple[list[tuple[str, int]], int | None]:
+    """The names the destructuring pattern whose `{` or `[` is at
+    `text[start]` binds, each with its offset in `text`, and the offset
+    just past the pattern's closing bracket.
+
+    An object pattern's property is `...target`, a shorthand key or
+    `key: target` (a key is a name, a string, a number or a computed
+    `[...]`, and only a shorthand key binds itself); an array pattern's
+    element is `...target`, a target or a hole; a target is a name or a
+    nested pattern. A `= default` is skipped to the next comma at the
+    pattern's depth, and so is a property or element of any other shape,
+    which binds nothing. '...', "..." and `...` strings are skipped
+    whole, so no bracket or comma inside one counts. Whitespace, newlines
+    included, may sit anywhere between the parts.
+
+    Returns ([], None) when `text[start]` opens no pattern, the pattern
+    does not close in `text`, a string in it does not end, or a bracket in
+    it closes one it did not open. A pure function of its arguments (no
+    module state), so another script can carry a copy of it.
+    """
+    n = len(text)
+    names: list[tuple[str, int]] = []
+
+    def space(i: int) -> int:
+        while i < n and text[i].isspace():
+            i += 1
+        return i
+
+    def name_end(i: int) -> int:
+        """The end of the identifier at `i`, `i` itself when none starts there."""
+        if i < n and (text[i].isalpha() or text[i] in "_$"):
+            i += 1
+            while i < n and (text[i].isalnum() or text[i] in "_$"):
+                i += 1
+        return i
+
+    def string_end(i: int) -> int | None:
+        """The offset past the string whose quote is at `i`."""
+        quote = text[i]
+        i += 1
+        while i < n:
+            if text[i] == "\\":
+                i += 2
+            elif text[i] == quote:
+                return i + 1
+            else:
+                i += 1
+        return None
+
+    def skip(i: int, to_comma: bool = True) -> int | None:
+        """From `i`, the offset of the next comma (unless not `to_comma`)
+        or closing bracket at depth 0; with `to_comma` False, `text[i]`
+        opens a bracket and the offset past the one closing it."""
+        depth = 0
+        while i < n:
+            ch = text[i]
+            if ch in "'\"`":
+                end = string_end(i)
+                if end is None:
+                    return None
+                i = end
+                continue
+            if ch in "([{":
+                depth += 1
+            elif ch in ")]}":
+                if depth == 0:
+                    return i
+                depth -= 1
+                if depth == 0 and not to_comma:
+                    return i + 1
+            elif ch == "," and depth == 0 and to_comma:
+                return i
+            i += 1
+        return None
+
+    def default(i: int) -> int | None:
+        """After a target: past its `= default`, when it has one."""
+        i = space(i)
+        if i < n and text[i] == "=" and text[i + 1 : i + 2] not in ("=", ">"):
+            return skip(i + 1)
+        return i
+
+    def bind(i: int, end: int, close: str) -> int | None:
+        """The name `text[i:end]` is bound when its property or element
+        ends after it or takes a default (any other text: another shape)."""
+        after = space(end)
+        if after < n and (
+            text[after] in (",", close)
+            or text[after] == "=" and text[after + 1 : after + 2] not in ("=", ">")
+        ):
+            names.append((text[i:end], i))
+            return default(after)
+        return after
+
+    def target(i: int, close: str) -> int | None:
+        if i < n and text[i] in "{[":
+            end = pattern(i)
+            return None if end is None else default(end)
+        end = name_end(i)
+        return i if end == i else bind(i, end, close)
+
+    def element(i: int, close: str) -> int | None:
+        """One property or element at `i`: the offset after it."""
+        if text.startswith("...", i):
+            return target(space(i + 3), close)
+        if close == "]":
+            return target(i, close)
+        if text[i] in "'\"":
+            end = string_end(i)
+        elif text[i] == "[":
+            end = skip(i, to_comma=False)  # a computed key
+        else:
+            end = name_end(i)
+            if end > i:
+                after = space(end)
+                if after < n and text[after] == ":":
+                    return target(space(after + 1), close)
+                return bind(i, end, close)  # a shorthand key
+            while end < n and (text[end].isalnum() or text[end] in "._"):
+                end += 1  # a number key
+        if end is None:
+            return None
+        after = space(end)
+        if end > i and after < n and text[after] == ":":
+            return target(space(after + 1), close)
+        return after
+
+    def pattern(i: int) -> int | None:
+        """The pattern opening at `i`: the offset past its closing bracket."""
+        close = "}" if text[i] == "{" else "]"
+        i += 1
+        while True:
+            i = space(i)
+            if i >= n:
+                return None
+            if text[i] == close:
+                return i + 1
+            if text[i] in ")]}":
+                return None
+            if text[i] == ",":
+                i += 1  # a hole, or a stray comma
+                continue
+            end = element(i, close)
+            if end is None:
+                return None
+            end = space(end)
+            if end < n and text[end] not in (",", close):
+                end = skip(end)  # any other shape binds nothing
+                if end is None:
+                    return None
+            i = end + 1 if end < n and text[end] == "," else end
+
+    if not (0 <= start < n and text[start] in "{["):
+        return [], None
+    end = pattern(start)
+    return (names, end) if end is not None else ([], None)
+
+
+def _js_initializer_start(text: str, end: int) -> int | None:
+    """The offset just past the `=` that begins the initializer of a
+    declarator whose name or pattern ends at `end`, a type annotation
+    (`: T`, brackets, strings and `=>` in it included) skipped. None when
+    neither `=` nor `:` follows, or when a `,` or `;` outside the
+    annotation's brackets, or the end of `text`, comes first."""
+    n = len(text)
+    i = end
+    while i < n and text[i].isspace():
+        i += 1
+    if i < n and text[i] == "=":
+        return None if text[i + 1 : i + 2] == "=" else i + 1
+    if not (i < n and text[i] == ":"):
+        return None
+    i += 1
+    depth = 0
+    while i < n:
+        ch = text[i]
+        if ch in "'\"`":
+            i += 1
+            while i < n and text[i] != ch:
+                i += 2 if text[i] == "\\" else 1
+        elif text.startswith("=>", i):
+            i += 1
+        elif ch in "([{<":
+            depth += 1
+        elif ch in ")]}>":
+            depth -= 1
+            if depth < 0:
+                return None
+        elif ch in ",;" and depth == 0:
+            return None
+        elif ch == "=" and depth == 0:
+            return None if text[i + 1 : i + 2] == "=" else i + 1
+        i += 1
+    return None
+
+
+def _js_destructured(code_lines: list[str]) -> dict[int, _PatternDecl]:
+    """For each line that opens a `const` / `let` / `var` statement whose
+    first declarator is a destructuring pattern (`_JS_VAR_DECL_RE`, the
+    rest starting with `{` or `[`): the names the pattern binds, each with
+    the line it appears on, and where its initializer starts.
+
+    The patterns are read from the comment-free lines joined with `\\n`
+    (`_js_pattern_bindings`), so a pattern may span lines and a name's
+    offset maps back to its line. A pattern that does not close, or that
+    nests deeper than the interpreter's recursion limit, binds nothing and
+    gives no item.
+    """
+    starts: list[tuple[int, int]] = []
+    for number, code in enumerate(code_lines, start=1):
+        if "{" not in code and "[" not in code:
+            continue
+        m = _JS_VAR_DECL_RE.match(code)
+        if m is not None and m.group(1)[:1] in ("{", "["):
+            starts.append((number, m.start(1)))
+    if not starts:
+        return {}
+    text = "\n".join(code_lines)
+    offsets: list[int] = []
+    pos = 0
+    for code in code_lines:
+        offsets.append(pos)
+        pos += len(code) + 1
+
+    def line_of(offset: int) -> int:
+        return bisect.bisect_right(offsets, offset)
+
+    out: dict[int, _PatternDecl] = {}
+    for number, column in starts:
+        try:
+            names, end = _js_pattern_bindings(text, offsets[number - 1] + column)
+        except RecursionError:
+            continue  # patterns nested past the interpreter's limit: none bound
+        if end is None:
+            continue
+        value = _js_initializer_start(text, end)
+        at = None
+        if value is not None:
+            line = line_of(value)
+            at = (line, code_lines[line - 1][value - offsets[line - 1] :])
+        out[number] = ([(name, line_of(offset)) for name, offset in names], at)
+    return out
+
+
 def _tsjs_definition_lines(
     lines: list[str],
     code_lines: list[str],
@@ -1477,6 +1844,7 @@ def _tsjs_definition_lines(
     declarators: Callable[..., _DeclSplit] = _js_declarators,
     declarations_only: bool = False,
     quiet: list[bool] | None = None,
+    destructured: dict[int, _PatternDecl] | None = None,
 ) -> list[tuple[int, bool]]:
     """(line, at column 0) for every line that defines `name`.
 
@@ -1486,15 +1854,20 @@ def _tsjs_definition_lines(
     JSDoc line or a commented-out declaration never matches. A line inside
     a multi-line `export { ... }` list or `module.exports = { ... }` object
     takes the column of the line the statement starts on, and so do the
-    name line of a declaration whose keyword ends the line above it and a
-    later declarator on a line of its own. Class members count only for a
+    name line of a declaration whose keyword ends the line above it, a
+    later declarator on a line of its own and the line of a name that a
+    destructuring pattern binds. `destructured` is
+    `_js_destructured(code_lines)` when the caller has it (it does not
+    depend on the name either): a name its pattern binds counts when the
+    `const` / `let` / `var` line it is keyed by opens a statement here.
+    Class members count only for a
     dotted export name. `declarators` splits a declarator list
     (`_js_declarators`, or `_SourceCache.js_declarators`, which splits each
     line once for every export looked up). With `declarations_only`,
     `export import NAME =`, `export default NAME`, an export-list item
     without an `as` that renames, a `module.exports` shorthand key and an
-    import-valued binding (a declarator, `exports.NAME =` or a
-    `module.exports` key whose value starts with `require(` or an
+    import-valued binding (a declarator, a destructured name, `exports.NAME =`
+    or a `module.exports` key whose value starts with `require(` or an
     `(await) import(`, on its line or the next one) never count, nor does
     a class member.
     """
@@ -1515,7 +1888,8 @@ def _tsjs_definition_lines(
         ]
     # One declarator of a `const` / `let` / `var` list: `NAME = v`,
     # `NAME: T = v`, `NAME!: T`, or a bare `NAME`. A destructuring pattern
-    # starts with `{` or `[` and never matches.
+    # starts with `{` or `[` and never matches: the names a pattern that
+    # begins the list binds come from `destructured` (`_js_pattern_bindings`).
     declarator = re.compile(rf"^\s*{esc}{end}\s*(?:!?\s*:|=|$)")
     # With declarations_only, the value bound to NAME (the rest of a
     # declarator, of `exports.NAME =` or of a `module.exports` key), to
@@ -1590,6 +1964,22 @@ def _tsjs_definition_lines(
     decls: list[tuple[bool, str, str]] = []
     if quiet is None:
         quiet = _js_quiet_lines(code_lines)
+    if destructured is None:
+        destructured = _js_destructured(code_lines)
+
+    def pattern_binds(number: int) -> list[int]:
+        """The lines on which the pattern that begins the `const` / `let` /
+        `var` list of line `number` binds `name` (none with
+        `declarations_only` when its value is an import)."""
+        decl = destructured.get(number)
+        if decl is None:
+            return []
+        bound, value = decl
+        at = [line for bound_name, line in bound if bound_name == name]
+        if at and declarations_only and value is not None and imported(value[1], value[0]):
+            return []
+        return at
+
     for number, (text, code) in enumerate(zip(lines, code_lines), start=1):
         if quiet[number - 1] and not (decls or split or cont) and name not in code:
             continue  # no rule below can match it: spares a scan per name
@@ -1637,7 +2027,8 @@ def _tsjs_definition_lines(
                 found.append((number, top))
             continue
         top = _is_column_0(text)
-        # every rule that matches a line needs the name in it
+        # every rule that matches a line needs the name in it, but for a
+        # destructuring pattern, whose names may sit on the lines below
         named = name in code
         if named and is_statement(code, number):
             found.append((number, top))
@@ -1647,6 +2038,9 @@ def _tsjs_definition_lines(
             carry, pieces = declarators(m.group(1))
             if carry is not None:
                 decls.append((top, *carry))
+            # `export const { a, b: NAME } = obj;`, on one line or several:
+            # each name's line, at the statement's column
+            found.extend((line, top) for line in pattern_binds(number))
             if named and any(declares(p, number) for p in pieces):
                 # a later declarator: `export const a = 1, NAME = 2;`
                 found.append((number, top))
@@ -1766,7 +2160,7 @@ def _line_matches(
         code_lines = cache.js_code_lines(path, lines)
         found = _tsjs_definition_lines(
             lines, code_lines, name, dotted, cache.js_declarators, declarations_only,
-            cache.js_quiet_lines(path, code_lines),
+            cache.js_quiet_lines(path, code_lines), cache.js_destructured(path, code_lines),
         )
     if declarations_only:
         top = {n for n, at_column_0 in found if at_column_0}
@@ -1790,6 +2184,39 @@ def find_definition_lines(
     return None if matches is None else matches[0]
 
 
+def _missed_definition_lines(
+    source_file: str,
+    export_name: str,
+    source_root: Path,
+    cache: _SourceCache,
+    line: int,
+    defs: list[int],
+    every: set[int],
+) -> list[int]:
+    """The `definition_lines` a finding lists for a recorded `line` that is
+    not one of `defs` (`_definition_matches` over the same `cache`).
+
+    A recorded line that is an indented match the column-0 rule dropped
+    joins them, so the finding carries several lines and nobody moves it.
+    Otherwise a Python file's `@overload` group gives its first line alone
+    (`_python_overload_start`), the line to move the entry to, and any
+    other answer gives `defs` as they are.
+    """
+    if line in every:
+        return sorted(set(defs) | {line})
+    rel = source_file.strip().replace("\\", "/")
+    if Path(rel).suffix.lower() not in PYTHON_EXTENSIONS or len(defs) < 2:
+        return defs
+    path = (source_root / rel).resolve()
+    lines = cache.lines(path)
+    if lines is None:
+        return defs
+    first = _python_overload_start(
+        lines, definition_name(export_name), defs, cache.py_statement_starts(path, lines)
+    )
+    return defs if first is None else [first]
+
+
 def definition_lines_report(
     source_file: str,
     export_name: str,
@@ -1802,9 +2229,11 @@ def definition_lines_report(
 
     `line_check` is `file-missing`, `skipped-export-type` (a `module` or
     `package`, no definition line), `skipped-language` (no rule for the
-    extension) or `checked`. With `line`, a recorded line that is an
-    indented match the column-0 rule dropped joins `definition_lines`, as in
-    `verify`, so the answer carries several lines.
+    extension) or `checked`. With `line`, a recorded line that is not a
+    definition line gets the lines `verify` would list
+    (`_missed_definition_lines`): an indented match the column-0 rule
+    dropped joins `definition_lines`, so the answer carries several lines,
+    and a Python `@overload` group gives its first line alone.
     """
     report: dict = {
         "source_file": source_file,
@@ -1823,14 +2252,17 @@ def definition_lines_report(
         covered = suffix in PYTHON_EXTENSIONS or suffix in TSJS_EXTENSIONS
         report["line_check"] = "skipped-export-type" if covered else "skipped-language"
         return report
-    matches = _definition_matches(source_file, export_name, source_root)
+    cache = _SourceCache()
+    matches = _definition_matches(source_file, export_name, source_root, cache)
     if matches is None:
         raise ValueError(f"failed to read source file {source_root / rel}")
     defs, every = matches
     if line is not None:
         report["line_is_definition"] = line in defs
-        if line not in defs and line in every:
-            defs = sorted(set(defs) | {line})
+        if line not in defs:
+            defs = _missed_definition_lines(
+                source_file, export_name, source_root, cache, line, defs, every
+            )
     report["definition_lines"] = defs
     return report
 
@@ -2161,8 +2593,8 @@ def baseline_gaps(
 ) -> tuple[list[dict], list[dict]]:
     """The provenance entries an extraction left out whose cited file still
     declares them: the recipe runner never reports a module, an alias that
-    renames, a dunder such as `__version__` or another underscore name, so
-    a diff would read each as removed.
+    renames, a dunder such as `__version__` or another Python or Rust
+    underscore name, so a diff would read each as removed.
 
     `held` holds the (name, file) of every export the extraction found,
     `files` the files whose entries are checked (the ones read), and
@@ -3291,13 +3723,13 @@ def verify(
                     continue
                 defs, every = matches
                 if line not in defs:
-                    if line in every:
-                        # The recorded line is an indented match the
-                        # column-0 rule dropped: keep it, so the finding
-                        # lists several lines and nobody auto-moves it.
-                        defs = sorted(set(defs) | {line})
+                    # An indented match the column-0 rule dropped joins
+                    # the lines, so nobody auto-moves it; an @overload
+                    # group gives its first line alone, the move target.
                     item["reason"] = STALE_LINE_NOT_DEFINITION
-                    item["definition_lines"] = defs
+                    item["definition_lines"] = _missed_definition_lines(
+                        sf, name, source_root, cache, line, defs, every
+                    )
                     stale.append(item)
         stale.sort(key=lambda s: (s["export_name"], s.get("source_file") or ""))