bmad-module-skill-forge 4.0.0 → 5.0.0

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

@@ -39,13 +39,21 @@ reading files and writing one JSON object:
   surface   the enumerated source surface, from every input given (their
             union):
               --extraction  skf-extract-public-api.py --mode full output:
-                            the names in entry_point_diff.public, a
+                            the names in entry_point_diff.public, each
+                            other in-scope definition of one
+                            (entry_point_diff.other_definitions, #830) a
+                            record of its own at its file, a
                             namespace with a `members` list given as its
                             members (the names its module passes on, each
                             at its file, once with a public name of the
                             same name and file), less the outside_scope
-                            names (defined in a file the brief scopes
-                            out); exports[] only gives each name's
+                            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
+                            (`outsideInclude`); exports[] only gives each name's
                             kind, line and signature line, looked up by the
                             name its defining file gives it (an aliased
                             re-export's `local`) and that file.
@@ -112,10 +120,11 @@ reading files and writing one JSON object:
 Name sets (surface `sets`, each sorted): `all` (the union above, less a
 nested Python top's names);
 `scope.include` and `tier_a_include` when the scope has those globs and a
-record names a file: the names whose file (an extraction's definition file,
+record names a file: the names with a file (any of the name's records: an
+extraction's definition file, each other in-scope definition's included,
 the quick output's defined_in, else its source_file, a per-file result's
-file, a provenance entry's source_file) matches a glob of the list and no
-scope.exclude glob,
+file, a provenance entry's source_file) that matches a glob of the list
+and no scope.exclude glob,
 and for `tier_a_include` a scope.include glob too when the scope has one,
 so a name with no file is in `all` only and a restored name is in no
 tier_a_include set (a tier_a_include glob an extraction lists as matching
@@ -127,29 +136,39 @@ exclude of `src/gen/**`; a list that counts no name, each glob left out
 or matching only excluded files, files scope.include leaves out or files
 no record names, gives no tier_a_include set); and, from an
 extraction only, `subpaths` (the names a non-root `exports` map subpath
-without `*` reaches) and `root` (the names the root entry points reach).
+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.
 
 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. Both guards run
-only on a surface read from the source. The deflation guard compares the
-re-derived scope.include set (the `all` set without one) with
-`stats.effective_denominator` and fires above DEFLATION_PCT when there is
-no tier A list (with an extraction or --fallback-scan, no tier_a_include
-set; otherwise no tier_a_include glob left in the list, since a name read
-by eye at Quick tier or State 4, and a quick name with no defined_in,
-carries its entry file, not the file that defines it); a stored 0 is
-deflation, not a
-denominator (`pct` null), and fires under that condition when any name is
-re-derived. The inflation guard compares the scope.include set with the
-provenance entry count (--provenance) and fires above INFLATION_PCT under
-the same condition; `guards.tierAInclude` lists the scope's
+only on a surface read from the source. The deflation guard compares a
+re-derived set with `stats.effective_denominator` and names it in `basis`.
+It is the tier_a_include set (`tier_a_include`) when the clause's ladder
+holds a stored count (stratified-scope, specific-modules, multi-entry), the
+surface has that set and each name sits at the file that defines it (a
+runner extraction, --fallback-scan, or quick output whose every name
+carries its defined_in, with no --per-file or --name beside it): it fires
+when the stored count differs from the set by more than DEFLATION_PCT
+either way, since Create Skill stores the runner's tier A count. Otherwise
+it is the scope.include set (`scope.include`, else `all` when the surface
+has no scope.include set), firing above DEFLATION_PCT when there is no tier
+A list (with an extraction or --fallback-scan, no tier_a_include set;
+otherwise no tier_a_include glob left in the list, since a name read by eye
+at Quick tier or State 4, and a quick name with no defined_in, carries its
+entry file, not the file that defines it). A stored 0 is deflation, not a
+denominator (`pct` null), and fires under its basis's condition when any
+name is re-derived. The inflation guard compares the scope.include set
+with the provenance entry count (--provenance) and fires above
+INFLATION_PCT when there is no tier A list, as the scope.include basis
+reads it; `guards.tierAInclude` lists the scope's
 tier_a_include globs ([] when it has none) for gap-ledger.py's wording;
 the umbrella ratio (an
 extraction only) is the share of the root entry points' names that are
 re-exports (a namespace with `members` counting as its members there
-too, each a re-export), and above UMBRELLA_RATIO the barrel is an
+too, each a re-export, and an other in-scope definition left out), and
+above UMBRELLA_RATIO the barrel is an
 umbrella; the
 stale-scope guard (an extraction with scope.include or tier_a_include only)
 fires when the runner lists an include or tier_a_include glob that matches
@@ -162,7 +181,14 @@ included, and `*` and `?` stay inside one.
 Denominator (surface `denominator`): the Source API Surface Definition's
 clause (source-access-protocol.md), the branch reconcile-coverage.py takes
 and the set it and score-signatures.py --surface-set read: {clause, branch,
-surfaceSet, ladderStep, absentSet, rebuild, barrel}. The inputs: the scope
+surfaceSet, ladderStep, absentSet, rebuild, barrel, setCounted}.
+`setCounted` (null off the scalar branch) says whether the scalar branch
+counts its `surfaceSet` as the numerator's set: true only for a scope set
+(not `all`) whose every name sits at the file that defines it, as the
+deflation guard's tier A basis requires (a runner extraction, the fallback
+scan, quick output whose every name carries its defined_in), read whole (an
+extraction neither `incomplete` nor truncated); otherwise the scalar branch
+keeps its looked-up numerator. The inputs: the scope
 type (the brief's, else the extraction's, else metadata.json's
 `scope_type`), metadata.json's `skill_type` and `stats.effective_denominator`,
 the extraction's `arms`, the deflation guard, and:
@@ -200,7 +226,13 @@ The last three walk a ladder, `ladderStep` naming the rung taken: rung 1,
 `stats.effective_denominator` when metadata.json has one above 0 (a stored
 0 is no denominator), is the `scalar` branch, whose `surfaceSet` (the set score-signatures.py scores) is
 tier_a_include, else scope.include, else all, unless the deflation guard
-fires: then the barrel branch over scope.include. The next rungs are sets,
+fires: then the barrel branch over tier_a_include when the ladder has that
+rung (stratified-scope, multi-entry) and the surface has the set, else over
+scope.include (when the inflation guard fires too, that union is itself
+inflated, and both gaps ask for the brief's tier A list, never a stored
+count set by hand). On an incomplete extraction, which can miss tier A
+names, a tier A set below the stored count fires the guard and leaves the
+scalar branch. The next rungs are sets,
 each taken when the surface has it, the last taken in any case:
 tier_a_include then scope.include (stratified-scope), scope.include
 (specific-modules), tier_a_include then subpaths (multi-entry). A set the
@@ -211,9 +243,13 @@ found no ast-grep (`no-ast-grep`), read no file in scope, read files only
 in languages it has no recipe for (`files_without_recipes` and no export),
 or found files no recipe reads while the skill's language (the --brief
 `language`, else the metadata.json `language`) is not one RECIPE_LANGUAGES
-holds, so the per-file scan has to run instead. An `incomplete` run keeps
-its exports; `extraction.readByEye` lists the files its errors and file
-issues name.
+holds, so the per-file scan has to run instead. A run keeps its exports
+whatever its status; `extraction.readByEye` lists the files to read by eye,
+at any status: each file the runner could not parse or decode (a
+`syntax-errors` or `not-utf8` file issue) and, on an `incomplete` run, each
+file a failed call names. `extraction.unread` lists the files nobody can
+read (a `missing` or `unreadable` file issue); a `no-recipes` file, such as
+a stylesheet, holds nothing to read and is in neither list.
 
 Usage:
   uv run load-coverage-inputs.py census --skill-dir <dir> [--output <file>]
@@ -607,9 +643,14 @@ def _members_in_place(public: list[dict]) -> list[dict]:
     return expanded
 
 
+# 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"})
+
+
 def _extraction_summary(data: dict, language: str | None) -> dict:
     """The surface's `extraction` object: the runner's status and counts,
-    the files to read by eye and the fallback verdict."""
+    the files to read by eye, the files no one can read and the fallback
+    verdict."""
     counts = data.get("counts") if isinstance(data.get("counts"), dict) else {}
     arms = data.get("arms") if isinstance(data.get("arms"), dict) else {}
     entry_points = data.get("entry_points") if isinstance(data.get("entry_points"), dict) else {}
@@ -626,8 +667,11 @@ def _extraction_summary(data: dict, language: str | None) -> dict:
         reason = (f"no recipe reads the skill's language, {language} "
                   f"({', '.join(sorted(without))} in scope)")
     errors = [e for e in data.get("errors") or [] if isinstance(e, dict)]
-    read_by_eye = sorted({str(i["file"]) for i in data.get("file_issues") or []
-                          if isinstance(i, dict) and i.get("file") and i.get("issue") != "no-recipes"}
+    issues = [i for i in data.get("file_issues") or [] if isinstance(i, dict) and i.get("file")]
+    # A file missing from disk or one the runner could not open is no file to read by eye.
+    unread = sorted({str(i["file"]) for i in issues if i.get("issue") in UNREADABLE_ISSUES})
+    read_by_eye = sorted({str(i["file"]) for i in issues
+                          if i.get("issue") != "no-recipes" and i.get("issue") not in UNREADABLE_ISSUES}
                          | {str(e["first_file"]) for e in errors if e.get("first_file")}
                          | {str(f) for e in errors if isinstance(e.get("unread"), list) for f in e["unread"] if f})
     return {
@@ -644,6 +688,7 @@ def _extraction_summary(data: dict, language: str | None) -> dict:
         "entryPointsFound": (bool(entry_points["files"]) if isinstance(entry_points.get("files"), list)
                              and data.get("files_in_scope") else None),
         "readByEye": read_by_eye,
+        "unread": unread,
         "fallback": {"needed": reason is not None, "reason": reason},
     }
 
@@ -651,6 +696,21 @@ def _extraction_summary(data: dict, language: str | None) -> dict:
 NO_UMBRELLA = {"entries": [], "names": 0, "reexported": 0, "ratio": None, "umbrella": False}
 
 
+def _outside_row(row: dict, scope: dict) -> dict:
+    """An outside_scope row as `excluded.outsideScope` lists it: its name,
+    file, line and entry point, and why the brief scopes the file out when
+    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."""
+    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"]))}
+
+
 def from_extraction(data: dict, language: str | None = None, brief: dict | None = None) -> dict:
     """The public surface of an extraction, less what lies outside scope,
     plus the root exports a stale scope.include glob left out. A nested
@@ -678,8 +738,12 @@ def from_extraction(data: dict, language: str | None = None, brief: dict | None
                 "extraction": extraction}
 
     diff = data.get("entry_point_diff") if isinstance(data.get("entry_point_diff"), dict) else {}
-    public = _members_in_place([p for p in diff.get("public") or []
-                                if isinstance(p, dict) and isinstance(p.get("name"), str)])
+    # Each in-scope definition of a public name is a record of its own (#830): the runner's other
+    # definitions join the public rows, so a set holds a name when any of its files matches, and
+    # the signature plan reads every declaration.
+    rows = {key: [p for p in diff.get(key) or [] if isinstance(p, dict) and isinstance(p.get("name"), str)]
+            for key in ("public", "other_definitions")}
+    public = _members_in_place(rows["public"] + rows["other_definitions"])
     outside = [o for o in diff.get("outside_scope") or [] if isinstance(o, dict)]
     gaps = [g for g in diff.get("extraction_gaps") or [] if isinstance(g, dict)]
 
@@ -690,7 +754,7 @@ def from_extraction(data: dict, language: str | None = None, brief: dict | None
     # records (so the scope sets a specific-modules or stratified brief
     # counts) and their outside_scope and extraction_gaps rows.
     nested = _nested_tops(entry_files, set(scope["include"]) | set(scope["tier_a_include"]),
-                          {p.get("entry") for p in public})
+                          {p.get("entry") for p in rows["public"]})
     nested_names = {top: sorted({p["name"] for p in public if p.get("entry") == top}) for top in nested}
 
     subpath_files = {e.get("file") for e in entry_files
@@ -731,20 +795,21 @@ def from_extraction(data: dict, language: str | None = None, brief: dict | None
                     found.get("source_line") if found else info.get("line"),
                     found.get("signature_line") if found else None, "extraction"))
 
-    root_names = [p for p in public if p.get("entry") in root_files]
+    # 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")]
 
     sets = {}
     if subpath_files:
         sets["subpaths"] = sorted({p["name"] for p in public if p.get("entry") in subpath_files})
     if root_files:
-        sets["root"] = sorted({p["name"] for p in root_names})
+        sets["root"] = sorted({p["name"] for p in public if p.get("entry") in root_files})
 
     return {
         "records": records,
         "nestedRecords": nested_records,
         "sets": sets,
-        "outside": [{"name": o.get("name"), "file": o.get("file")} for o in outside],
+        "outside": [_outside_row(o, scope) for o in outside],
         "nested": [{"entry": top, "within": nested[top], "names": nested_names[top]} for top in sorted(nested)],
         "staleScope": {"unmatchedInclude": unmatched, "unmatchedTierAInclude": unmatched_tier_a,
                        "restored": [{"name": o["name"], "file": o["file"], "line": o.get("line")}
@@ -828,12 +893,16 @@ def _over(clause: str, sets: dict, name: str, step: int | None, rebuild: str | N
 
 def pick_denominator(sets: dict, stats_eff: int | None, deflation_fires: bool, barrel: str | None, arms: dict,
                      scope_type: str | None, skill_type: str | None, monorepo: bool, pattern_reference: bool,
-                     curated: bool, source_read: bool) -> dict:
+                     curated: bool, source_read: bool, set_trusted: bool = False) -> dict:
     """The Source API Surface Definition's clause for a skill, with the branch
-    and the name set reconcile-coverage.py and score-signatures.py read, and
-    the entry points' state it was picked by (see "Denominator" above)."""
-    return {**_pick(sets, stats_eff, deflation_fires, barrel, arms, scope_type, skill_type, monorepo,
-                    pattern_reference, curated, source_read), "barrel": barrel}
+    and the name set reconcile-coverage.py and score-signatures.py read, the
+    entry points' state it was picked by and, on the scalar branch, whether
+    it counts that set (`set_trusted`: each name at its defining file, read
+    whole; see "Denominator" above)."""
+    picked = _pick(sets, stats_eff, deflation_fires, barrel, arms, scope_type, skill_type, monorepo,
+                   pattern_reference, curated, source_read)
+    counted = (set_trusted and picked["surfaceSet"] not in (None, "all")) if picked["branch"] == "scalar" else None
+    return {**picked, "barrel": barrel, "setCounted": counted}
 
 
 def _pick(sets: dict, stats_eff: int | None, deflation_fires: bool, barrel: str | None, arms: dict,
@@ -868,7 +937,9 @@ def _pick(sets: dict, stats_eff: int | None, deflation_fires: bool, barrel: str
         elif stats_eff:
             # A stored 0 is no denominator: the next rung.
             if deflation_fires:
-                return _over(clause, sets, "scope.include", step)
+                # The ladder's tier A rung when it has one and the surface has the set, else scope.include.
+                rung = "tier_a_include" if "tier_a_include" in ladder and "tier_a_include" in sets else "scope.include"
+                return _over(clause, sets, rung, step)
             scored = next((name for name in ("tier_a_include", "scope.include") if name in sets), "all")
             return {"clause": clause, "branch": "scalar", "surfaceSet": scored, "ladderStep": step,
                     "absentSet": None, "rebuild": None}
@@ -1002,6 +1073,45 @@ def surface(args: argparse.Namespace) -> dict:
     if tier_a_names:
         sets["tier_a_include"] = tier_a_names
 
+    # The clause: an extraction's entry-point status (one the per-file scan replaces says only that it found no
+    # entry point), else a quick output's (an export is a barrel; none, and no warning, an empty one), else what
+    # the workflow read (--barrel).
+    barrel = None
+    summary = extracted["extraction"] if extracted is not None else None
+    if summary is not None and not summary["fallback"]["needed"]:
+        barrel = summary["entryPointStatus"]
+    elif summary is not None and summary["entryPointsFound"] is False:
+        barrel = "no-entry-point"
+    elif quick_outputs:
+        barrel = "barrel" if any(q["exports"] for q in quick_outputs) else (
+            None if any(q.get("warnings") for q in quick_outputs) else "empty-barrel")
+    if barrel is None and args.barrel:
+        barrel = BARREL_FLAG[args.barrel]
+    recorded_type = extracted["scopeType"] if extracted is not None else None
+    meta_type = meta.get("scope_type") if isinstance(meta, dict) and isinstance(meta.get("scope_type"), str) else None
+    arms = summary["arms"] if summary is not None else {}
+    # The extraction's verdict, the rule Create Skill stores the count by, else the workflow's judgment.
+    curated = summary["curatedSubset"] if summary is not None and summary["curatedSubset"] is not None \
+        else bool(args.curated_subset)
+    scope_type = (brief or {}).get("type") or recorded_type or meta_type
+    skill_type = meta.get("skill_type") if isinstance(meta, dict) else None
+    monorepo = bool(args.monorepo or arms.get("monorepo"))
+    # The clause alone (no stored count, no guard): only a clause whose ladder holds a stored count measures it
+    # against the tier A set.
+    clause = _pick(sets, None, False, barrel, arms, scope_type, skill_type, monorepo,
+                   bool(args.pattern_reference_intent), curated, source_read)["clause"]
+    swap = False
+    # Each name sits at the file that defines it (a runner extraction, the fallback scan, quick output whose every
+    # name carries its defined_in); a name read by eye, or a quick name with no defined_in, sits at its entry file.
+    runner = extracted is not None and not extracted["extraction"]["fallback"]["needed"]
+    quick_traced = (bool(quick_outputs) and not args.per_file and not args.name
+                    and all(isinstance(e.get("defined_in"), str) and e["defined_in"]
+                            for q in quick_outputs for e in q["exports"] if isinstance(e, dict)))
+    defining = runner or bool(args.fallback_scan) or quick_traced
+    # The scalar branch counts its scope set only from such names read whole: an incomplete or truncated
+    # extraction can miss names (#791, #792).
+    whole = summary is None or (summary["status"] != "incomplete" and not summary["truncated"])
+
     if extracted is not None or brief is not None or meta is not None:
         include_union = len(sets["scope.include"]) if "scope.include" in sets else len(sets["all"])
         extraction = extracted["extraction"] if extracted is not None else {}
@@ -1021,14 +1131,27 @@ def surface(args: argparse.Namespace) -> dict:
         # file, not the file that defines it).
         no_tier_a = ("tier_a_include" not in sets if extracted is not None or args.fallback_scan
                      else not tier_a)
-        deflation = {"applicable": source_read and stats_eff is not None, "effectiveDenominator": stats_eff,
-                     "rederived": include_union if source_read else None, "pct": None, "fires": False}
+        # A clause whose ladder holds a stored count checks it against the tier A set, both ways, when each name
+        # sits at the file that defines it (a runner extraction, the fallback scan, quick output whose every name
+        # carries its defined_in): Create Skill stores the runner's tier A count, so one beyond the threshold is
+        # stale (#813). A name read by eye, or a quick name with no defined_in, sits at its entry file.
+        tier_a_basis = defining and clause in CLAUSE_LADDERS and "tier_a_include" in sets
+        rederived = len(sets["tier_a_include"]) if tier_a_basis else include_union
+        basis = "tier_a_include" if tier_a_basis else "scope.include" if "scope.include" in sets else "all"
+        deflation = {"applicable": source_read and stats_eff is not None, "basis": basis,
+                     "effectiveDenominator": stats_eff, "rederived": rederived if source_read else None, "pct": None,
+                     "fires": False}
         if deflation["applicable"] and stats_eff:
-            deflation["pct"] = round2((include_union - stats_eff) / stats_eff * 100)
-            deflation["fires"] = no_tier_a and deflation["pct"] > DEFLATION_PCT
+            deflation["pct"] = round2((rederived - stats_eff) / stats_eff * 100)
+            deflation["fires"] = (abs(deflation["pct"]) > DEFLATION_PCT if tier_a_basis
+                                  else no_tier_a and deflation["pct"] > DEFLATION_PCT)
         elif deflation["applicable"]:
             # A stored 0 is deflation, not a denominator, once a name is re-derived.
-            deflation["fires"] = no_tier_a and include_union > 0
+            deflation["fires"] = (tier_a_basis or no_tier_a) and rederived > 0
+        # An incomplete extraction can miss tier A names: a tier A set below the stored count is drift to report,
+        # not a denominator to take.
+        incomplete = runner and extracted["extraction"]["status"] == "incomplete"
+        swap = deflation["fires"] and not (incomplete and tier_a_basis and (deflation["pct"] or 0) < 0)
         entry_count = len(_entries(provenance)) if provenance is not None else 0
         inflation = {"applicable": source_read and no_tier_a and bool(scope["include"]) and entry_count > 0,
                      "scopeIncludeUnion": include_union if scope["include"] else None,
@@ -1052,31 +1175,9 @@ def surface(args: argparse.Namespace) -> dict:
                            "umbrellaRatio": UMBRELLA_RATIO},
         }
 
-    # The clause: an extraction's entry-point status (one the per-file scan replaces says only that it found no
-    # entry point), else a quick output's (an export is a barrel; none, and no warning, an empty one), else what
-    # the workflow read (--barrel).
-    barrel = None
-    summary = extracted["extraction"] if extracted is not None else None
-    if summary is not None and not summary["fallback"]["needed"]:
-        barrel = summary["entryPointStatus"]
-    elif summary is not None and summary["entryPointsFound"] is False:
-        barrel = "no-entry-point"
-    elif quick_outputs:
-        barrel = "barrel" if any(q["exports"] for q in quick_outputs) else (
-            None if any(q.get("warnings") for q in quick_outputs) else "empty-barrel")
-    if barrel is None and args.barrel:
-        barrel = BARREL_FLAG[args.barrel]
-    recorded_type = extracted["scopeType"] if extracted is not None else None
-    meta_type = meta.get("scope_type") if isinstance(meta, dict) and isinstance(meta.get("scope_type"), str) else None
-    arms = summary["arms"] if summary is not None else {}
-    # The extraction's verdict, the rule Create Skill stores the count by, else the workflow's judgment.
-    curated = summary["curatedSubset"] if summary is not None and summary["curatedSubset"] is not None \
-        else bool(args.curated_subset)
-    out["denominator"] = pick_denominator(
-        sets, stats_eff, bool((out["guards"] or {}).get("deflation", {}).get("fires")), barrel, arms,
-        (brief or {}).get("type") or recorded_type or meta_type,
-        meta.get("skill_type") if isinstance(meta, dict) else None, bool(args.monorepo or arms.get("monorepo")),
-        bool(args.pattern_reference_intent), curated, source_read)
+    out["denominator"] = pick_denominator(sets, stats_eff, swap, barrel, arms, scope_type, skill_type, monorepo,
+                                          bool(args.pattern_reference_intent), curated, source_read,
+                                          defining and whole)
 
     return {
         "inputs": {

package/src/skf-test-skill/scripts/locate-export-segments.py

@@ -31,7 +31,7 @@ answer per input and judges no meaning. For each export name it lists:
   as data or output (`json`, `yaml`, `text`, `console` ...) holds none.
 
 A call is `awaited` when `await` stands before it (through its receiver:
-`await client.fetchData(...)`), `.await` follows it (Rust), an asynchronous
+`await client.fetchData(...)`), `.await` or `?.await` follows it (Rust), an asynchronous
 loop or context manager consumes it (`async for row in stream(...)`, `async
 with session(...)`, `for await (const row of stream(...))`), or it sits in
 the arguments of a call that is itself awaited or is an event-loop runner
@@ -40,6 +40,26 @@ crossing into a function body. `chainedMember` names the member read or
 called on its result right after it (`then`, `catch`, `join`, `get`), else
 null: whether that waits for the result is the caller's call.
 
+`awaitedVia` says how an awaited call is awaited, null when it is not:
+
+- "direct": the await applies to the call itself (`directlyAwaited`):
+  `.await` follows it, or `await` stands before it with nothing applied to
+  its result (`await client.fetchData(...)`) but a member that waits for an
+  awaitable (`then`, `catch`, `finally`, `ConfigureAwait`), or it alone
+  fills the groups that `await` stands before (`await ((fetchData(x)))`,
+  `await (fetchData(x) as T)`) and nothing follows them but the end of the
+  statement, of a list or of a bracket.
+- "chain": the await applies to an expression the call starts or sits in:
+  a member, subscript or call applied to its result
+  (`await use_context(e).embed(t)`, `await fetchData(x)[0]`) or a group
+  around it (`await (fetchData(x) or other())`).
+- "consumer": an asynchronous loop or context manager consumes it.
+- "argument" or "runner": it sits in the arguments of an awaited call, or of
+  an event-loop runner; `enclosingCallee` names that callee, whitespace
+  removed (`asyncio.gather`, `Promise.all`, `asyncio.run`), else null.
+
+A backslash continuation counts as whitespace throughout.
+
 Name match: the name as a fixed string, case-sensitive, never inside a
 longer identifier (the Export match rule of skf-scan-skill-md-structure.py
 usage-scope). A qualified name (`client.fetch`, `Store::load`) matches only
@@ -74,9 +94,11 @@ Output (stdout, one object):
         "name": "fetchData",
         "descriptionCount": 3,                    # all found; descriptions[] holds the first 12
         "descriptions": [{"file", "line", "endLine", "kind", "section", "header", "text", "truncated"}],
-        "calls": [{"file", "line", "fence", "language", "awaited", "chainedMember", "text"}],
+        "calls": [{"file", "line", "fence", "language", "awaited", "directlyAwaited", "awaitedVia",
+                   "enclosingCallee", "chainedMember", "text"}],
         "callCount": 2,
-        "awaitedCount": 1
+        "awaitedCount": 1,                        # calls whose `awaited` is true
+        "directlyAwaitedCount": 1                 # calls whose `directlyAwaited` is true
       }
     ],
     "notCalled": ["parseConfig"],                 # names no example calls
@@ -126,9 +148,20 @@ LIST_ITEM_RE = re.compile(r"^\s*(?:[-*+]|\d{1,9}[.)])(?:[ \t]+|$)")
 TABLE_ROW_RE = re.compile(r"^\s*\|")
 TABLE_SEPARATOR_RE = re.compile(r"^\s*\|?\s*:?-+:?\s*(?:\|\s*:?-+:?\s*)*\|?\s*$")
 GENERIC_OR_PATH = r"(?:[ \t]*::)?(?:[ \t]*<[^<>()\n]*(?:<[^<>()\n]*>[^<>()\n]*)*>)?"
-AFTER_CALL_RE = re.compile(f"\\s*\\??\\.\\s*((?:[^\\W\\d]|\\$)[{IDENT_CHARS}]*)")
+# Whitespace, a Python backslash continuation included; LINE_SPACE stays on its line.
+SPACE = r"(?:\s|\\\n)*"
+LINE_SPACE = r"(?:[ \t]|\\\n)*"
+AFTER_CALL_RE = re.compile(f"{SPACE}[?!]?\\.{SPACE}((?:[^\\W\\d]|\\$)[{IDENT_CHARS}]*)")
 AWAIT_BEFORE_RE = re.compile(f"(?<![{IDENT_CHARS}])await$")
-AWAIT_AFTER_RE = re.compile(f"\\s*\\.\\s*await(?![{IDENT_CHARS}])")
+AWAIT_AFTER_RE = re.compile(f"{SPACE}\\??\\.{SPACE}await(?![{IDENT_CHARS}])")
+# A subscript or call applied to a call's result: `f(x)[0]`, `f(x)(y)`, `f(x)?.[0]`, `f(x)!(y)`.
+APPLIED_RE = re.compile(f"{LINE_SPACE}(?:\\?\\.|!)?[\\[(]")
+# What may close a group that holds only the call (`(f(x) as T)`, `(f(x)!)`), and what may follow
+# the outermost group: the end of the statement, of a list or of a bracket.
+GROUP_TAIL_RE = re.compile(f"{SPACE}(?:!|as(?![{IDENT_CHARS}])[^()]*)?{SPACE}")
+GROUP_END_RE = re.compile(f"{LINE_SPACE}(?:[;,)\\]}}]|\\Z|\\n\\s*(?:[^\\s.?\\[(]|\\Z))")
+# Members whose call waits for an awaitable: under `await`, the export returns one.
+WAIT_MEMBERS = frozenset({"then", "catch", "finally", "ConfigureAwait"})
 # An expression an asynchronous loop or context manager consumes: `async for
 # x in NAME(...)`, `async with NAME(...)`, `for await (const x of NAME(...))`,
 # `await foreach (var x in NAME(...))`. Matched against its line up to it.
@@ -515,7 +548,8 @@ def _matching_open(text, close_idx):
 
 
 def _skip_space_back(text, i):
-    while i > 0 and text[i - 1] in " \t\n":
+    """Back over whitespace, a Python backslash continuation included."""
+    while i > 0 and (text[i - 1] in " \t\n" or (text[i - 1] == "\\" and text.startswith("\n", i))):
         i -= 1
     return i
 
@@ -543,14 +577,37 @@ def _chain_start(text, pos):
         i = start
 
 
+def _await_before(text, start):
+    """True when `await` stands right before the expression that starts at `start`."""
+    return bool(AWAIT_BEFORE_RE.search(text, 0, _skip_space_back(text, start)))
+
+
 def _awaited_at(text, start):
     """True when `await` stands right before the expression that starts at `start`, or an
     asynchronous loop or context manager consumes it."""
-    if AWAIT_BEFORE_RE.search(text, 0, _skip_space_back(text, start)):
+    if _await_before(text, start):
         return True
     return bool(ASYNC_CONSUMER_RE.search(text[text.rfind("\n", 0, start) + 1:start]))
 
 
+def _grouped_await(text, chain, close):
+    """True for `await (call(...))` and `await ((call(...) as T))`: the call alone fills each group
+    around it (a trailing `as T` or `!` allowed), `await` stands before the outermost one, and
+    nothing but the end of the statement, of a list or of a bracket follows it."""
+    start, end = chain, close
+    while end is not None:
+        group = _skip_space_back(text, start) - 1
+        if group < 0 or text[group] != "(":
+            return False
+        end_group = _matching_close(text, group)
+        if end_group is None or not GROUP_TAIL_RE.fullmatch(text, end + 1, end_group):
+            return False
+        if _await_before(text, group):
+            return bool(GROUP_END_RE.match(text, end_group + 1))
+        start, end = group, end_group
+    return False
+
+
 def _is_runner(callee):
     """True for `asyncio.run`, `loop.run_until_complete`, `rt.block_on` and the like."""
     parts = [p for p in re.split(r"\.|::", callee) if p]
@@ -568,7 +625,12 @@ def _opens_body(text, brace_idx):
 
 
 def _enclosing_awaits(text, start):
-    """True when a call around the expression at `start` is awaited or runs it, within one function body."""
+    """How a call or group around the expression at `start` awaits it, within one function body.
+
+    ("runner", callee) for a runner it is an argument of, ("argument", callee) for an awaited or
+    consumed call it is an argument of, ("chain", None) for an awaited group around it and
+    ("consumer", None) for a consumed one; None when nothing around it awaits it.
+    """
     i, depth = start, 0
     while i > 0:
         i -= 1
@@ -583,17 +645,39 @@ def _enclosing_awaits(text, start):
             elif c == "(":
                 k = _skip_space_back(text, i)
                 word = WORD_BEFORE_RE.search(text, 0, k)
+                callee = None
                 if word and word.group(1) not in EXPRESSION_WORDS:
                     expr = _chain_start(text, word.start())
-                    if _is_runner(re.sub(r"\s+", "", text[expr:k])):
-                        return True
+                    callee = re.sub(r"(?:\s|\\\n)+", "", text[expr:k])
+                    if _is_runner(callee):
+                        return "runner", callee
                 else:
                     expr = i  # a grouping `(`: `await (fetch())`
                 close = _matching_close(text, i)
-                if _awaited_at(text, expr) or (close is not None and AWAIT_AFTER_RE.match(text, close + 1)):
-                    return True
+                awaits = _await_before(text, expr) or (close is not None and AWAIT_AFTER_RE.match(text, close + 1))
+                if awaits or _awaited_at(text, expr):
+                    return ("argument", callee) if callee else ("chain" if awaits else "consumer", None)
                 i = expr
-    return False
+    return None
+
+
+def _how_awaited(text, chain, close):
+    """(awaitedVia, enclosingCallee, chainedMember) of the call whose expression starts at `chain`
+    and whose argument list closes at `close`."""
+    before = _await_before(text, chain)
+    member = AFTER_CALL_RE.match(text, close + 1) if close is not None else None
+    chained = member.group(1) if member else None
+    if close is not None and AWAIT_AFTER_RE.match(text, close + 1):
+        return "direct", None, None
+    if member or (close is not None and APPLIED_RE.match(text, close + 1)):
+        if before:
+            return ("direct" if chained in WAIT_MEMBERS else "chain"), None, chained
+    elif before or _grouped_await(text, chain, close):
+        return "direct", None, None
+    if _awaited_at(text, chain):
+        return "consumer", None, chained
+    via, callee = _enclosing_awaits(text, chain) or (None, None)
+    return via, callee, chained
 
 
 def _closes_generic(tail):
@@ -670,15 +754,11 @@ def scan_block(rel, lines, opening, closing, info, patterns):
                     continue
                 if regex is not call_re:
                     continue  # the last part of a qualified name counts only as a declaration
-                awaited, chained = _awaited_at(text, chain), None
-                if close is not None:
-                    if AWAIT_AFTER_RE.match(text, close + 1):
-                        awaited = True
-                    elif member := AFTER_CALL_RE.match(text, close + 1):
-                        chained = member.group(1)
+                via, callee, chained = _how_awaited(text, chain, close)
                 found[name]["calls"].append({
                     "file": rel, "line": opening + row + 2, "fence": opening + 1, "language": language or None,
-                    "awaited": awaited or _enclosing_awaits(text, chain), "chainedMember": chained,
+                    "awaited": via is not None, "directlyAwaited": via == "direct", "awaitedVia": via,
+                    "enclosingCallee": callee, "chainedMember": chained,
                     "text": _cap(body[row].strip(), LINE_TEXT_CAP)[0],
                 })
     return found
@@ -734,6 +814,7 @@ def locate(inp):
         "calls": calls[name],
         "callCount": len(calls[name]),
         "awaitedCount": sum(1 for c in calls[name] if c["awaited"]),
+        "directlyAwaitedCount": sum(1 for c in calls[name] if c["directlyAwaited"]),
     } for name in names if calls[name]]
     not_called = [name for name in names if not calls[name]]
     return {