bmad-module-skill-forge 8.1.0 → 9.0.0

package/src/skf-test-skill/scripts/load-coverage-inputs.py

@@ -76,24 +76,37 @@ reading files and writing one JSON object:
                            data block (json, yaml, text...) gives none.
             Signatures (#888): an origin whose place writes the name's
             signature in a fixed form that is surely complete also carries
-            it as `signature`, {"params", "return_type"}, two strings, each
-            one's whitespace runs read as one space, which
-            validate-inventory.py --floor refuses an inventory for
-            changing; any other place pins nothing, since a wrong pin would
-            be forced into the inventory. `params` is the text inside the
-            parameter group (score-signatures.py's _group: the first pair
-            of parentheses outside every bracket pair and string), and
-            `return_type` the type written after it (score-signatures.py's
-            _signature_parts), "" for none. A form that writes neither
-            (`f()`, `useQuery<T>()`) gives none, so an empty call claims no
-            form. A span (a table cell's or a heading's) is complete when
-            it is the name (or no name, as a Signature cell's `(x: A) =>
-            B`), its type parameters, one parameter group, then nothing or
-            a return separator (`->`, `=>`, `→` or `:`) and the return, with
-            nothing else: `useQuery(key).data`, `f(a) / f(a, b)`, a
-            trailing comment, a `;` or `,` outside the return's brackets,
-            an unclosed bracket, `Meta<T>` (no group) and `new Client(opts)`
-            give none. By form:
+            it as `signature`, which validate-inventory.py --floor refuses
+            an inventory for changing; any other place pins nothing, since
+            a wrong pin would be forced into the inventory. A signature is
+            two strings, each one's whitespace runs read as one space,
+            {"params", "return_type"} for a complete form or a Props cell
+            (below) and {"usage_signature", "return_type"} for a usage form
+            (and `signature_form` "partial" under a header's partial
+            label, below). `params` is the text inside the parameter group
+            (score-signatures.py's _group: the first pair of parentheses
+            outside every bracket pair and string), and `return_type` the
+            type written after it (score-signatures.py's _signature_parts),
+            "" for none. A form that writes neither (`f()`,
+            `useQuery<T>()`) gives none, so an empty call claims no form. A
+            span (a table cell's or a heading's) is complete when it is the
+            name (or no name, as a Signature cell's `(x: A) => B`), its type
+            parameters, one parameter group, then nothing or a return
+            separator (`->`, `=>`, `→` or `:`) and the return, with nothing
+            else: `useQuery(key).data`, `f(a) / f(a, b)`, a trailing
+            comment, a `;` or `,` outside the return's brackets, an
+            unclosed bracket, `Meta<T>` (no group) and `new Client(opts)`
+            give none. A span that is no complete form is a usage form when
+            it writes, before the name's complete form, at least one of, in
+            this order, an assignment (`x =`, `const { data } =`), `await`,
+            `new` and a receiver or module path (`cognee.`): its
+            `usage_signature` is the span through the parameter group, its
+            `return_type` the return after it (`await run(a, b):
+            Promise<R>` gives `await run(a, b)` and `Promise<R>`); or when
+            it is one self-closing JSX element of the name that sets a prop
+            (`<Canvas of={X} />`), its `return_type` "". An empty call
+            (`new Client()`) and a prop-less element (`<Canvas />`) give
+            none. By form:
               table-row    a row whose first cell names one name (a row
                            naming several gives none), each cell's `\\|`
                            read as `|`: the leading code span of its
@@ -102,15 +115,38 @@ reading files and writing one JSON object:
                            the one span of its first cell that gives the
                            name (another export's span there, as in
                            `fetch` (same as `http.request(opts)`), gives
-                           nothing). A Signature span with a group that is
-                           no complete form (`client.get(k) -> str`,
-                           `new Client(opts)`) gives none, so a shorter
-                           first-cell call never stands in for it. A header
-                           cell matches whole, so a labelled one is not a
-                           Signature column, and a Props, Params or
-                           Parameters cell is never read (its shared
-                           members and usage forms stay the reader's).
-              heading      its code span
+                           nothing), each a complete form, else a usage
+                           form. A Signature span with a group that is
+                           neither (`client.get(k).data`, `f(a) //
+                           overload`) gives none, so a shorter first-cell
+                           call never stands in for it, and so does such a
+                           first-cell span (`useData(key).data`). Only
+                           then a Props, Params or Parameters cell, when
+                           the whole cell is one code span (trailing prose
+                           or several spans leave it the reader's): a
+                           complete form (`(a, b)` gives `a, b`), else a
+                           usage form, else none when it writes a
+                           parameter group or opens a JSX element, or when
+                           it only names a type or writes a placeholder
+                           (`ButtonProps`, `ComponentProps<typeof Link>`,
+                           `None`, `-`), else the span whole
+                           as `params` with `return_type` ""
+                           (`TitleProps = { of?: Of }`, `key: string`),
+                           kept as written. A Signature, Props, Params
+                           or Parameters header may give one partial
+                           label in parentheses after its word, any case:
+                           `Signature (simplified)`, `Props (simplified)`,
+                           `(partial)`, `(key parameters)` or
+                           `(key params)`. The form its cell gives then
+                           also carries `signature_form` "partial", so the
+                           label is the script's, not the reader's; the
+                           first-cell form never does, as the label heads
+                           that column only. Any other text after the word
+                           (`Signature (TypeScript)`, `Props / Usage`)
+                           leaves the column unread.
+              heading      its code span, a complete form, else a usage
+                           form (`new Client(opts)`: a name is cut as
+                           above, so no other usage names one there)
               declaration  a function's (`function`, `def`, `fn` or Go's
                            `func` before its name; a `const` holding an
                            arrow gives none): its lines as one, as
@@ -174,10 +210,12 @@ reading files and writing one JSON object:
                             same name and file), less the outside_scope
                             names (defined in a file out of scope), which
                             `excluded.outsideScope` lists with their file,
-                            line and entry point and, when the brief
-                            scopes the file out, why: the scope.exclude
-                            glob that matches it (`excludeGlob`) or no
-                            scope.include glob covering it
+                            line and entry point and, for a namespace's
+                            member, the namespace (`namespace`) and, when
+                            the brief scopes the file out, why: the
+                            scope.exclude glob that matches it
+                            (`excludeGlob`) or no scope.include glob
+                            covering it
                             (`outsideInclude`); exports[] only gives each name's
                             kind, line and signature line (a local export
                             list's item: its binding's declaration_line and
@@ -204,7 +242,10 @@ reading files and writing one JSON object:
                             line of its outside_scope row, when no include,
                             exclude or declined scope-expansion amendment
                             (latest action skipped or demoted-include, from
-                            --brief) matches its file. A tier_a_include glob
+                            --brief) matches its file; no recipe reads its
+                            file, so its kind is the one --provenance gives
+                            the name at that file (PROVENANCE_KINDS), else
+                            none. A tier_a_include glob
                             the runner lists as matching no file
                             (scope.unmatched_tier_a_include, [] when the key
                             is absent) counts no name. An extraction the
@@ -225,11 +266,13 @@ reading files and writing one JSON object:
                             its entry file): as with an extraction, no
                             tier_a_include set is no tier A list
               --name        a name read by eye whose file is not known
-              --provenance  the provenance entries' named exports (State 2)
+              --provenance  the provenance entries' named exports (State 2),
+                            and the kinds of restored names
               --metadata    the metadata.json exports[] names (States 2, 3)
             A surface read from the source (--extraction, --quick or
             --per-file) takes no name from --provenance and --metadata:
-            they are the baselines of the candidates and guards. Without
+            they are the baselines of the candidates and guards, and the
+            map gives only a restored name its kind. Without
             one, with --provenance and --metadata both, `state2` gives the
             provenance count, the metadata count and their union count,
             which compute-score.py turns into the State 2 divergence. --fold
@@ -268,6 +311,23 @@ without `*` reaches) and `root` (the names the root entry points reach),
 each through the entry point of any of the name's definitions.
 reconcile-coverage.py and score-signatures.py --surface-set pick one.
 
+Other declarations (surface `otherDeclarations`, #918): for each name with
+a record (a nested Python top's included), each declaration of the name
+the extraction's exports[] holds (under the name, or under the name an
+aliased record's defining file gives it, `local`, as the record lookup
+reads it; a re-export row declares nothing) in a file none of the name's
+records names and no scope.exclude glob matches, as {name, kind, file,
+line, signatureLine}, its file with forward slashes and no leading `./`,
+its line and signature line taken as a record's are; sorted, each
+declaration once however its path is written, and [] with none, with no
+extraction or with one the per-file scan replaces. Such a declaration is a
+same-named function no entry point exports, as cognee's lightweight
+`run_pipeline`, which a lazy `__getattr__` passes on beside the
+orchestrator a namespace exports. They are no records: they join no set,
+no count and no guard, and only score-signatures.py reads them, plan
+binding a documented form to one when the form's own citations name it and
+no other declaration of the name.
+
 Candidates and guards (with an extraction, --brief or --metadata): each
 set's count, the metadata `stats.effective_denominator` (--metadata), and
 the extractor's own effective_denominator and its basis; for the
@@ -437,9 +497,32 @@ FLOOR_TABLE_HEADERS = frozenset({
     "export", "exports", "symbol", "symbols", "function", "functions", "class", "classes", "interface", "interfaces",
     "type", "types", "hook", "hooks", "component", "components", "helper", "helpers", "constant", "constants",
     "enum", "enums", "api", "apis"})
-# The header words (as _header_word reads them, whole) of a floor table's column that writes the row's signature
-# (#888); a labelled header, such as `Signature (simplified)`, is not one.
+# The header words (as _header_label reads them, a partial label cut) of a floor table's column that writes the row's
+# signature (#888); a header with any other text after the word, such as `Signature (TypeScript)`, is not one.
 FLOOR_SIGNATURE_HEADERS = frozenset({"signature", "signatures"})
+# The header words (as _header_label reads them, a partial label cut) of a floor table's column that writes the row's
+# props or parameters (#888): its cell is read only when it is exactly one code span, and only after the Signature
+# and first-cell forms; a `Props / Usage` or `Key params` header is not one.
+FLOOR_PROPS_HEADERS = frozenset({"props", "params", "parameters"})
+# The partial labels (lower case, whitespace runs as one space) a header may give in parentheses after its word, as
+# `Signature (simplified)` and `Props (simplified)` do (#888): each form read from that Signature, Props, Params or
+# Parameters column is partial, so an optional parameter it leaves out is Info, not Critical, and the floor pins the
+# label with the form.
+FLOOR_PARTIAL_LABELS = frozenset({"simplified", "partial", "key parameters", "key params"})
+# What a usage form writes before its name's complete form (#888), each part optional, in this order: an assignment
+# (`x =`, `a, b =`, `const { data } =`, `let [a, b] =`), `await`, `new`, and a receiver or module path (`cognee.`,
+# `client.messages.`).
+USAGE_PREFIX_RE = re.compile(
+    r"(?:(?:(?:const|let|var)\s+)?(?:[A-Za-z_$][\w$]*(?:\s*,\s*[A-Za-z_$][\w$]*)*"
+    r"|\{(?:[^{}]|\{[^{}]*\})*\}|\[(?:[^\[\]]|\[[^\[\]]*\])*\])\s*=(?![=>])\s*)?"
+    r"(?:await\s+)?(?:new\s+)?(?:[A-Za-z_$][\w$]*\.)*")
+# A span that opens a JSX element (`<Canvas`), which a Props, Params or Parameters cell writes as a usage, not as
+# the row's props.
+ELEMENT_OPEN_RE = re.compile(r"<[A-Za-z_$]")
+# A Props, Params or Parameters span that only names a type or writes a placeholder, not the row's props or
+# parameters (`ButtonProps`, `ComponentProps<typeof Link>`, `None`, `-`): a lone dash, or one identifier or dotted
+# path, then at most one `<...>` type-argument list (group 1, which _type_parameters_only reads).
+TYPE_ONLY_RE = re.compile(r"[-\u2013\u2014]|[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*\s*(<.*>)?")
 # A complete form's name, before its type parameters and parameter group (group 1, absent for none).
 SPAN_NAME_RE = re.compile(r"\s*([A-Za-z_$][\w$]*)?\s*")
 # What a complete form writes after its parameter group before its return: `->`, `=>`, `→` or `:` (not `::`).
@@ -635,6 +718,19 @@ def _header_word(cell: str) -> str:
     return (m.group(2) if m else cell).strip().lower()
 
 
+def _header_label(cell: str) -> tuple[str, bool]:
+    """A header cell's word as _header_word reads it, and whether it carries a partial label (#888): one of
+    FLOOR_PARTIAL_LABELS in parentheses after the word (`Signature (simplified)`, `**Signatures (Key
+    Parameters)**`), any case, whitespace runs inside them as one space, the label then cut from the word. Any other
+    text after the word (`Signature (TypeScript)`) stays in it, so that column is read as before."""
+    word = _header_word(cell)
+    if word.endswith(")"):
+        head, opened, label = word[:-1].rpartition("(")
+        if opened and " ".join(label.split()) in FLOOR_PARTIAL_LABELS:
+            return head.rstrip(), True
+    return word, False
+
+
 def _cells(row: str) -> list[str]:
     """A table row's cells, split on each unescaped `|`, each stripped."""
     row = row.strip()
@@ -790,6 +886,64 @@ def _call_form(span: str, name: str | None) -> dict | None:
     return _form(text, group)
 
 
+def _element_form(text: str, name: str) -> dict | None:
+    """{"usage_signature", "return_type"} of a span that is one self-closing JSX element of `name` setting at least
+    one prop (`<Canvas of={X} />`): the element, whitespace runs as one space, and ""; None for any other span, a
+    prop-less `<Canvas />`, an element with children, two elements and an unclosed brace or string among them."""
+    head = re.match(rf"<{re.escape(name)}\s+", text)
+    if head is None or not text.endswith("/>") or not text[head.end():-2].strip():
+        return None
+    depth, quote = 0, None  # brace depth, and the quote a string is open on
+    for ch in text[head.end():-2]:
+        if quote:
+            quote = None if ch == quote else quote
+        elif ch in "\"'`":
+            quote = ch
+        elif ch in "{}":
+            depth += 1 if ch == "{" else -1
+            if depth < 0:
+                return None
+        elif depth == 0 and ch in "<>/":
+            return None
+    return None if depth or quote else {"usage_signature": " ".join(text.split()), "return_type": ""}
+
+
+def _usage_form(span: str, name: str) -> dict | None:
+    """The signature a span writes as a usage of `name` (#888), whitespace runs as one space: at least one of, in this
+    order, an assignment (`x =`, `const { data } =`), `await`, `new` and a receiver or module path (`cognee.`), then
+    `name`'s complete form (_call_form): {"usage_signature": the span through the parameter group, "return_type": the
+    return after it, "" for none}; or one JSX element of `name` that sets a prop (_element_form). None for any other
+    span, an empty call (`new Client()`) and a prop-less element (`<Canvas />`) among them."""
+    text = span.strip()
+    if text.startswith("<"):
+        return _element_form(text, name)
+    prefix = USAGE_PREFIX_RE.match(text)
+    rest = text[prefix.end():]
+    if not prefix.group() or not re.match(rf"{re.escape(name)}(?![\w$])", rest):
+        return None
+    form = _call_form(rest, name)
+    if form is None:
+        return None
+    group = _sibling("score-signatures.py")._group(rest)
+    return {"usage_signature": " ".join(text[:prefix.end() + group[1] + 1].split()), "return_type": form["return_type"]}
+
+
+def _span_form(span: str, name: str | None) -> dict | None:
+    """The signature a span writes: its complete form (_call_form), else its usage form (_usage_form)."""
+    return _call_form(span, name) or (_usage_form(span, name) if name else None)
+
+
+def _labelled(form: dict | None, partial: bool) -> dict | None:
+    """`form`, with `signature_form` "partial" when its column's header gives a partial label (#888)."""
+    return {**form, "signature_form": "partial"} if form and partial else form
+
+
+def _column(labels: list[tuple[str, bool]], words: frozenset) -> tuple[int | None, bool]:
+    """The first header cell whose word (_header_label) is one of `words`, and its partial label; (None, False) for
+    none."""
+    return next(((i, labelled) for i, (word, labelled) in enumerate(labels) if word in words), (None, False))
+
+
 def _leading_span(cell: str) -> str | None:
     """The code span a table cell opens with, None when it opens with none."""
     run = len(cell) - len(cell.lstrip("`"))
@@ -801,22 +955,44 @@ def _row_form(header: list[str], row: list[str]) -> dict | None:
     """The signature a floor table's row writes for the one name its first cell names (a row naming several gives
     none), each cell's `\\|` read as `|`: the leading code span of its Signature or Signatures cell, else, when that
     span writes no parameter group, the one span of its first cell that gives that name (another export's span there
-    gives nothing), each a complete form (_call_form). A Signature span with a group that is no complete form gives
-    none. A Props, Params or Parameters cell is never read."""
+    gives nothing), each a complete form (_call_form), else a usage form (_usage_form, #888). A Signature span with a
+    group that is neither gives none, and so does such a first-cell span. Only then its Props, Params or Parameters
+    cell, when the whole cell is one code span (trailing prose or several spans leave it the reader's): a complete
+    form, else a usage form, else none when it writes a parameter group or opens a JSX element, or when it only names
+    a type or writes a placeholder (`ButtonProps`, `ComponentProps<typeof Link>`, `None`, `-`), else the span whole as
+    `params`, `return_type` "", kept as written. A Signature, Props, Params or Parameters header may carry a partial
+    label (_header_label, #888): the form its cell gives then also gives `signature_form` "partial", the first-cell
+    form never."""
     segments = _sibling("locate-export-segments.py")
+    scorer = _sibling("score-signatures.py")
     names = {name for name in map(_floor_name, segments._inline_code(row[0])) if name}
     if len(names) != 1:
         return None
     [name] = names
     cells = [cell.replace("\\|", "|") for cell in row]
-    at = next((i for i, cell in enumerate(header) if _header_word(cell) in FLOOR_SIGNATURE_HEADERS), None)
+    labels = [_header_label(cell) for cell in header]
+    at, partial = _column(labels, FLOOR_SIGNATURE_HEADERS)
     span = _leading_span(cells[at]) if at is not None and at < len(cells) else None
-    if span is not None and (form := _call_form(span, name)):
-        return form
-    if span is not None and _sibling("score-signatures.py")._group(span.strip()) is not None:
+    if span is not None and (form := _span_form(span, name)):
+        return _labelled(form, partial)
+    if span is not None and scorer._group(span.strip()) is not None:
         return None  # the cell writes a call the floor cannot pin: a shorter first-cell form would hide it
     own = [span for span in segments._inline_code(cells[0]) if _floor_name(span) == name]
-    return _call_form(own[0], name) if len(own) == 1 else None
+    if len(own) == 1 and (form := _span_form(own[0], name)):
+        return form
+    if any(scorer._group(span.strip()) is not None for span in own):
+        return None  # the first cell writes a call the floor cannot pin: the Props cell would stand in for it
+    at, partial = _column(labels, FLOOR_PROPS_HEADERS)
+    span = _whole_span(cells[at], segments) if at is not None and at < len(cells) else None
+    if span is None:
+        return None
+    if form := _span_form(span, name):
+        return _labelled(form, partial)
+    if scorer._group(span.strip()) is not None or ELEMENT_OPEN_RE.match(span.strip()) or not span.strip():
+        return None
+    if (only := TYPE_ONLY_RE.fullmatch(span.strip())) and _type_parameters_only(only.group(1) or ""):
+        return None  # the span names a type or writes a placeholder, no props or parameters
+    return _labelled({"params": " ".join(span.split()), "return_type": ""}, partial)
 
 
 def _function_declaration(line: str, language: str, js_family) -> int | None:
@@ -924,7 +1100,7 @@ def floor(skill_dir: str) -> dict:
         for index, _level, text, _above in headings:
             span = _whole_span(text, segments)
             if span is not None:
-                add(_floor_name(span), file_index, index, "heading", None, _call_form(span, _floor_name(span)))
+                add(_floor_name(span), file_index, index, "heading", None, _span_form(span, _floor_name(span)))
         comments = _html_comment_lines(lines, start, code)
         for opening, closing, info in blocks:
             language = segments._language(info)
@@ -1066,6 +1242,37 @@ def _record(name, kind, file, line, signature_line, origin) -> dict:
             "origin": origin}
 
 
+# A provenance map's export_type, read case-insensitively, as the kind of a restored name (#913): the type kinds
+# score-signatures.py's Type Coverage counts (a dataclass, NamedTuple or TypedDict is a class, a Protocol an
+# interface, a type alias a type), and `function` and `const`, which are no type (a TypeVar is no type). Any
+# other export_type (`re-export`, `module`, `decorator_namespace`, ...) gives no kind.
+PROVENANCE_KINDS = {
+    **dict.fromkeys(("class", "dataclass", "namedtuple", "typeddict"), "class"),
+    **dict.fromkeys(("protocol", "interface"), "interface"),
+    "enum": "enum",
+    **dict.fromkeys(("type", "type_alias"), "type"),
+    "struct": "struct",
+    "trait": "trait",
+    **dict.fromkeys(("function", "method", "staticmethod", "classmethod"), "function"),
+    **dict.fromkeys(("const", "constant", "variable", "sentinel", "typevar"), "const"),
+}
+
+
+def _restored_kinds(records: list[dict], provenance: dict | None) -> None:
+    """Give each restored record with no kind the kind PROVENANCE_KINDS reads
+    from the first provenance entry, in map order, with its name and its
+    file (both paths `_norm`ed) and a known kind; no other record changes."""
+    entries = _entries(provenance)
+    for record in records:
+        if record["origin"] != "restored" or record["kind"] or not record["file"]:
+            continue
+        file = _norm(record["file"])
+        record["kind"] = next(
+            (kind for e in entries
+             if e.get("export_name") == record["name"] and _norm(e.get("source_file")) == file
+             and (kind := PROVENANCE_KINDS.get(str(e.get("export_type")).strip().lower()))), None)
+
+
 def _globs(value) -> list[str]:
     return [g for g in (_norm(v) for v in value if isinstance(v, str)) if g] if isinstance(value, list) else []
 
@@ -1186,6 +1393,50 @@ def _members_in_place(public: list[dict]) -> list[dict]:
     return expanded
 
 
+def _declared_at(row: dict) -> tuple:
+    """(line, signature line) of an extraction's exports[] row, as a record
+    takes them: a local `export { ... }` list's item at the declaration it
+    names (#836), its `declaration_line` and `declaration_signature_line`
+    (both from that one pair), when it has that line; else its own
+    `source_line` and `signature_line`."""
+    if isinstance(row.get("declaration_line"), int):
+        return row["declaration_line"], row.get("declaration_signature_line")
+    return row.get("source_line"), row.get("signature_line")
+
+
+OTHER_DECLARATION_KEYS = ("name", "kind", "file", "line", "signatureLine")
+
+
+def other_declarations(records: list[dict], declarations: list[dict], aliases: dict[str, set[str]],
+                       excludes: list[str]) -> list[dict]:
+    """The other declarations of the surface names (#918): for each name
+    `records` holds, each of `declarations` (an extraction's exports[] rows,
+    a re-export left out) recorded under the name, or under a name an
+    aliased record's defining file gives it (`aliases`), in a file no
+    record of the name names and no exclude glob matches, as {name, kind,
+    file, line, signatureLine}, the file normalised (_norm), sorted, each
+    declaration once however its path is written. They are no records:
+    only score-signatures.py reads them."""
+    files: dict[str, set[str]] = {}
+    for record in records:
+        files.setdefault(record["name"], set()).update([_norm(record["file"])] if record.get("file") else [])
+    by_export: dict[str, list[dict]] = {}
+    for declaration in declarations:
+        by_export.setdefault(declaration["exportName"], []).append(declaration)
+    found = set()
+    for name, own in files.items():
+        for looked in {name} | aliases.get(name, set()):
+            for d in by_export.get(looked, []):
+                path = _norm(d["file"])
+                if path in own or any(glob_match(path, g) for g in excludes):
+                    continue
+                line = d["line"] if isinstance(d["line"], int) and not isinstance(d["line"], bool) else None
+                found.add((name, d["kind"] if isinstance(d["kind"], str) else None, path, line,
+                           d["signatureLine"] if isinstance(d["signatureLine"], str) else None))
+    ordered = sorted(found, key=lambda t: (t[0], t[2], t[3] or 0, t[1] or "", t[4] or ""))
+    return [dict(zip(OTHER_DECLARATION_KEYS, t)) for t in ordered]
+
+
 # The runner's file issues for a file it could not open at all: no one can read it by eye either.
 UNREADABLE_ISSUES = frozenset({"missing", "unreadable"})
 
@@ -1245,13 +1496,19 @@ def _outside_row(row: dict, scope: dict) -> dict:
     it does (#796): `excludeGlob`, the first scope.exclude glob that matches
     the file, and `outsideInclude`, true when scope.include has globs and
     none matches it. Neither (null and false) when the brief does not
-    explain it, such as a file no recipe reads or no file at all."""
+    explain it, such as a file no recipe reads or no file at all. A
+    namespace's member also keeps the namespace it came through
+    (`namespace`, #969) when the row gives it as a non-empty string, and
+    no such key otherwise."""
     file = row.get("file") if isinstance(row.get("file"), str) and row.get("file") else None
     path = _norm(file) if file else None
-    return {"name": row.get("name"), "file": file, "line": row.get("line"), "entry": row.get("entry"),
-            "excludeGlob": next((g for g in scope["exclude"] if glob_match(path, g)), None) if path else None,
-            "outsideInclude": bool(path and scope["include"]
-                                   and not any(glob_match(path, g) for g in scope["include"]))}
+    out = {"name": row.get("name"), "file": file, "line": row.get("line"), "entry": row.get("entry"),
+           "excludeGlob": next((g for g in scope["exclude"] if glob_match(path, g)), None) if path else None,
+           "outsideInclude": bool(path and scope["include"]
+                                  and not any(glob_match(path, g) for g in scope["include"]))}
+    if isinstance(row.get("namespace"), str) and row["namespace"]:
+        out["namespace"] = row["namespace"]
+    return out
 
 
 def from_extraction(data: dict, language: str | None = None, brief: dict | None = None) -> dict:
@@ -1274,7 +1531,8 @@ def from_extraction(data: dict, language: str | None = None, brief: dict | None
     unmatched_tier_a = _globs(recorded.get("unmatched_tier_a_include"))
     extraction = _extraction_summary(data, language)
     if extraction["fallback"]["needed"]:
-        return {"records": [], "nestedRecords": [], "sets": {}, "outside": [], "nested": [],
+        return {"records": [], "nestedRecords": [], "declarations": [], "aliases": {}, "sets": {}, "outside": [],
+                "nested": [],
                 "staleScope": {"unmatchedInclude": unmatched, "unmatchedTierAInclude": unmatched_tier_a,
                                "restored": []},
                 "gaps": [], "scope": scope, "scopeType": recorded.get("type"), "umbrella": dict(NO_UMBRELLA),
@@ -1325,6 +1583,8 @@ def from_extraction(data: dict, language: str | None = None, brief: dict | None
     index = {(e.get("export_name"), e.get("source_file")): e
              for e in data.get("exports") or [] if isinstance(e, dict)}
     records, nested_records = [], []
+    # The names an aliased record's defining file gives it, for the other declarations (#918).
+    aliases: dict[str, set[str]] = {}
     for info in public:
         name, file = info["name"], info.get("file")
         if (name, file) in outside_keys:
@@ -1336,19 +1596,27 @@ def from_extraction(data: dict, language: str | None = None, brief: dict | None
             continue
         # An aliased re-export (`export { Options as Config }`) is recorded
         # under the name its defining file gives it, `local`.
-        found = index.get((info.get("local") or name, file)) or index.get((name, file))
+        local = info.get("local")
+        if isinstance(local, str) and local and local != name:
+            aliases.setdefault(name, set()).add(local)
+        found = index.get((local or name, file)) or index.get((name, file))
         kind = found.get("export_type") if found else None
-        # A local `export { ... }` list's item is planned at the declaration it
-        # names (#836): the line and the signature line both come from that pair.
-        if found and isinstance(found.get("declaration_line"), int):
-            line, signature_line = found["declaration_line"], found.get("declaration_signature_line")
-        elif found:
-            line, signature_line = found.get("source_line"), found.get("signature_line")
-        else:
-            line, signature_line = info.get("line"), None
+        line, signature_line = _declared_at(found) if found else (info.get("line"), None)
         (nested_records if info.get("entry") in nested else records).append(
             _record(name, None if kind == "re-export" else kind, file, line, signature_line, "extraction"))
 
+    # Every declaration exports[] records, a re-export row left out (it declares nothing): the other
+    # declarations of a surface name come from these (#918).
+    declarations = []
+    for e in data.get("exports") or []:
+        if not isinstance(e, dict) or e.get("export_type") == "re-export":
+            continue
+        name, file = e.get("export_name"), e.get("source_file")
+        if isinstance(name, str) and name and isinstance(file, str) and file.strip():
+            line, signature_line = _declared_at(e)
+            declarations.append({"exportName": name, "kind": e.get("export_type"), "file": file, "line": line,
+                                 "signatureLine": signature_line})
+
     # The umbrella ratio reads the public rows alone: an other definition is no root barrel name there.
     root_names = [p for p in _members_in_place(rows["public"]) if p.get("entry") in root_files]
     reexported = [p for p in root_names if p.get("via") not in (None, "declaration")]
@@ -1362,6 +1630,8 @@ def from_extraction(data: dict, language: str | None = None, brief: dict | None
     return {
         "records": records,
         "nestedRecords": nested_records,
+        "declarations": declarations,
+        "aliases": aliases,
         "sets": sets,
         "outside": [_outside_row(o, scope) for o in outside],
         "nested": [{"entry": top, "within": nested[top], "names": nested_names[top]} for top in sorted(nested)],
@@ -1600,12 +1870,18 @@ def surface(args: argparse.Namespace) -> dict:
     sets["all"] = sorted({r["name"] for r in records})
     # A nested Python top's records count in the scope sets, never in `all`.
     records += extracted["nestedRecords"] if extracted is not None else []
+    # A restored name takes its kind from the provenance map at its file (#913): no set, count or guard changes.
+    if provenance is not None:
+        _restored_kinds(records, provenance)
     records.sort(key=lambda r: (r["name"], str(r["file"] or ""), r["origin"]))
 
     # The scope: the one the extractor recorded, else the brief's.
     scope = extracted["scope"] if extracted is not None and any(extracted["scope"].values()) else None
     if scope is None:
         scope = brief["scope"] if brief is not None else _scope(None, None, None)
+    # Each other declaration of a surface name (#918), for the signature plan alone: no record, set or count.
+    others = (other_declarations(records, extracted["declarations"], extracted["aliases"], scope["exclude"])
+              if extracted is not None else [])
     # A tier A glob the runner lists as matching no file counts no name, and
     # so does one whose folder or file differs from every scope.include
     # glob's before any `*` or `?` (`gen/**` beside `src/**`) or one a
@@ -1749,6 +2025,7 @@ def surface(args: argparse.Namespace) -> dict:
             "brief": args.brief, "fold": bool(args.fold),
         },
         "exports": records,
+        "otherDeclarations": others,
         "sets": sets,
         **out,
         "warnings": warnings,