codemetrics-ai 0.4.0 → 0.6.0-preview.1

package/dist/python/async_helper_paths.py

@@ -0,0 +1,186 @@
+"""Trace bounded local synchronous helpers with explicit callback execution context."""
+
+import ast
+from collections import Counter
+from datetime import datetime, timezone
+from pathlib import Path
+
+from async_adapters import Adapters, AdapterCalls
+from async_provenance import ContextCalls
+import async_usage as usage
+from review_cli import run
+
+POLICY = "python/async-local-helper-paths-review-v1"
+MAX_DEPTH = 3
+MAX_STEPS = 100000
+
+
+def partial_callback(value):
+    if value and value["status"] in {"inline-partial-syntax", "stored-partial-syntax"}:
+        callback = value["partial"]["callback"]
+        return callback["reference"] if callback else None
+    return None
+
+
+class FilePaths:
+    def __init__(self, tree, owners, file, budget):
+        self.bindings = usage.Bindings(tree)
+        self.owners, self.file, self.budget = owners, file, budget
+        self.provenance = Adapters(self.bindings, owners, file)
+        self.nodes, self.cache = {}, {}
+        for node in self.bindings.scopes:
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                key = usage.digest(f"{file}|{node.lineno}|{node.col_offset}|{type(node).__name__}")
+                if key in owners:
+                    self.nodes[key] = node
+
+    def spend(self, amount=1):
+        self.budget[0] += amount
+        if self.budget[0] > MAX_STEPS:
+            raise ValueError("Local helper measurement/traversal budget exceeded.")
+
+    def measure(self, key):
+        if key not in self.cache:
+            node, owner = self.nodes[key], self.owners[key]
+            contextual = ContextCalls(self.bindings, node, owner, self.provenance)
+            measurement, contexts = contextual.measure(node)
+            adapter = AdapterCalls(self.bindings, node, owner, self.provenance)
+            if adapter.measure(node) != measurement:
+                raise ValueError("Local helper call measurements disagree.")
+            self.spend(len(measurement["calls"]))
+            self.cache[key] = measurement, {row["callId"]: row for row in contexts}, adapter.observations
+        return self.cache[key]
+
+    def follow(self, reference, path, execution, visited, traces):
+        if reference and reference["status"] == "import-spelling" and reference.get("target") in usage.BLOCKING:
+            traces.append({"path": path, "executionContext": execution, "status": "blocking-candidate",
+                           "reason": "catalogue-callback-import-spelling", "target": reference["target"]})
+            return
+        if not reference or reference["status"] not in {"local-definition", "decorated-wrapper-syntax"}:
+            traces.append({"path": path, "executionContext": execution, "status": "unresolved",
+                           "reason": (reference or {}).get("reason", "unsupported-callback"), "target": None})
+            return
+        key = reference["definition"]["ownerId"]
+        reason = None
+        if key in visited:
+            reason = "recursive-or-repeated-owner"
+        elif len(visited) - 1 >= MAX_DEPTH:
+            reason = "helper-depth-limit"
+        elif not isinstance(self.nodes.get(key), ast.FunctionDef):
+            reason = "async-or-unselected-callee"
+        elif self.measure(key)[0]["kind"] == "async-generator":
+            # Calls.measure also notices yields in synchronous functions. Calling
+            # such a function constructs a generator; it does not run its body.
+            reason = "generator-body-deferred"
+        if reason:
+            traces.append({"path": path, "executionContext": execution, "status": "unresolved", "reason": reason, "target": None})
+            return
+        traces.append({"path": path, "executionContext": execution, "status": "local-helper-link",
+                       "reason": "bounded-lexical-definition", "target": None, "targetOwnerId": key})
+        self.walk(key, path, execution, visited | {key}, traces)
+
+    def walk(self, key, prefix, execution, visited, traces):
+        measurement, contexts, adapters = self.measure(key)
+        for call in measurement["calls"]:
+            self.spend()
+            lexical, adapter = contexts[call["id"]], adapters[call["id"]]
+            mode = "deferred-generator-body" if call["executionContext"] == "deferred-generator-body" else execution
+            owner = self.owners[key]
+            path = prefix + [{"ownerId": key, "callId": call["id"], "file": self.file,
+                              "member": owner["member"], **{name: call[name] for name in ("line", "column", "endLine", "endColumn")}}]
+            if call["category"] == "blocking-call-candidate":
+                traces.append({"path": path, "executionContext": mode, "status": "blocking-candidate",
+                               "reason": "catalogue-import-spelling", "target": call["binding"]["target"]})
+                continue
+            decorated = adapter["decoratedCallee"]
+            if decorated["status"] == "decorated-wrapper-syntax":
+                self.follow(decorated, path, self.callback_mode(mode), visited, traces)
+                continue
+            local = lexical["localCallee"]
+            partial = partial_callback(adapter["partialCallee"])
+            if local and local["status"] == "local-definition":
+                self.follow(local, path, mode, visited, traces)
+            elif partial:
+                self.follow(partial, path, mode, visited, traces)
+            elif call["category"] == "unresolved-call" and not (lexical["storedWrapper"] and
+                    lexical["storedWrapper"]["status"] == "stored-wrapper-syntax"):
+                traces.append({"path": path, "executionContext": mode, "status": "unresolved",
+                               "reason": (local or {}).get("reason", lexical["unresolvedReason"]), "target": None})
+            if lexical["callback"]:
+                callback = partial_callback(adapter["callbackPartial"]) or lexical["callback"]["reference"]
+                # Constructor callbacks are only references, never evidence of an invocation.
+                callback_mode = "wrapper-callback-reference" if call["category"] == "offload-wrapper-construction" else self.callback_mode(mode)
+                self.follow(callback, path, callback_mode, visited, traces)
+
+    @staticmethod
+    def callback_mode(mode):
+        return "thread-helper-callback" if mode == "async-body" else mode
+
+
+def summarize(rows):
+    def counts(items):
+        traces = [trace for row in items for trace in row["traces"]]
+        blocking = [trace for trace in traces if trace["status"] == "blocking-candidate"]
+        return {"asyncFunctions": len(items), "availability": "available" if items else "unavailable",
+            "functionsWithDirectOrHelperCandidates": sum(any(trace["status"] == "blocking-candidate" and
+                trace["executionContext"] == "async-body" for trace in row["traces"]) for row in items) if items else None,
+            "candidatePathsByContext": dict(sorted(Counter(trace["executionContext"] for trace in blocking).items())),
+            "unresolvedPathsByReason": dict(sorted(Counter(trace["reason"] for trace in traces if trace["status"] == "unresolved").items())),
+            "candidatePaths": len(blocking),
+            "localHelperLinks": sum(trace["status"] == "local-helper-link" for trace in traces),
+            "distinctBlockingSourceCalls": len({trace["path"][-1]["callId"] for trace in blocking})}
+    return {**counts(rows), "populations": {population: counts([row for row in rows if row["population"] == population])
+        for population in sorted({row["population"] for row in rows})}}
+
+
+def review(target, facts, base):
+    configuration = {"policy": POLICY, "asyncConfigurationFingerprint": base["configurationFingerprint"],
+                     "maxHelperDepth": MAX_DEPTH, "maxSteps": MAX_STEPS}
+    report = {"schemaVersion": 1, "artifactKind": "experimental-python-async-helper-paths",
+        "producer": {"name": "codemetrics-ai/python-async-helper-paths", "version": "0.1.0-experimental"},
+        "generatedAtUtc": datetime.now(timezone.utc).isoformat(), "runId": base["runId"], "auditId": base["auditId"],
+        "policy": POLICY, "configuration": configuration, "configurationFingerprint": usage.fingerprint(configuration),
+        "asyncRowsSha256": usage.fingerprint(base["functions"]), "subject": base["subject"], "selection": facts["selection"],
+        "sourceFactsProducer": facts["producer"], "sourceFactsPolicy": facts["measurementPolicy"],
+        "status": "incomplete", "diagnostics": [], "functions": [], "summary": None,
+        "scope": "Bounded same-file lexical synchronous helper paths and callback context. Import spelling, not runtime identity, reachability, successful offloading or performance. Both dimensions remain unscored."}
+    try:
+        fresh = usage.review(target, facts, run_id=base["runId"], audit_id=base["auditId"])
+        stable = lambda value: {key: item for key, item in value.items() if key != "generatedAtUtc"}
+        if fresh["status"] != "complete" or stable(fresh) != stable(base):
+            raise ValueError("Async input is incomplete, stale, or inconsistent.")
+        target = Path(target).absolute()
+        root = target if target.is_dir() else target.parent
+        owners = {row["id"]: row for row in facts["functions"]}
+        originals = {row["id"]: row for row in base["functions"] if row["status"] == "observed"}
+        rows, budget = [], [0]
+        for record in facts["selection"]["files"]:
+            if record["disposition"] != "analyzed":
+                continue
+            paths = FilePaths(ast.parse(usage.read_verified(root, record)), owners, record["file"], budget)
+            for key, node in paths.nodes.items():
+                if not isinstance(node, ast.AsyncFunctionDef):
+                    continue
+                if paths.measure(key)[0] != originals[key]["measurement"]:
+                    raise ValueError("Original async calls changed during helper analysis.")
+                traces = []
+                paths.walk(key, [], "async-body", {key}, traces)
+                row = {name: originals[key][name] for name in ("id", "file", "member", "line", "population", "sourceSha256")}
+                rows.append({**row, "traces": traces, "disposition": "review-only"})
+        if {row["id"] for row in rows} != set(originals):
+            raise ValueError("Async owners changed during helper analysis.")
+        rows.sort(key=lambda row: (row["file"], row["line"], row["id"]))
+        report.update(status="complete", functions=rows, summary=summarize(rows))
+    except (OSError, SyntaxError, UnicodeError, ValueError, RecursionError, KeyError, TypeError) as error:
+        report["diagnostics"].append({"code": "async-helper-analysis", "message": str(error)})
+    return report
+
+
+def analyze(target, *, run_id=None, audit_id=None, **selection):
+    facts = usage.source_facts.analyze(target, **selection)
+    base = usage.review(target, facts, run_id=run_id, audit_id=audit_id)
+    return review(target, facts, base)
+
+
+if __name__ == "__main__":
+    raise SystemExit(run(analyze, __doc__))

package/dist/python/async_provenance.py

@@ -0,0 +1,129 @@
+"""Bounded source links for async calls; never follow or execute callback bodies."""
+
+import ast
+
+from async_bindings import dotted
+import async_usage as usage
+
+
+def shape(node):
+    if isinstance(node, ast.Name):
+        return "name"
+    if isinstance(node, ast.Attribute):
+        return "attribute-path" if dotted(node) else "attribute-on-expression"
+    return {ast.Call: "call-result", ast.Subscript: "subscript", ast.Lambda: "lambda"}.get(type(node), "other-expression")
+
+
+def unresolved(reason):
+    return {"status": "unresolved", "reason": reason, "definition": None}
+
+
+def before(definition, use):
+    return (definition.end_lineno, definition.end_col_offset) < (use.lineno, use.col_offset)
+
+
+class Provenance:
+    def __init__(self, bindings, owners, file):
+        self.bindings, self.owners, self.file = bindings, owners, file
+        self.definitions, self.assignments = {}, {}
+        for scope in bindings.scopes.values():
+            self.definitions[scope] = {node.name: node for node in scope.direct
+                if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))}
+            self.assignments[scope] = {node.targets[0].id: node for node in scope.direct
+                if isinstance(node, ast.Assign) and len(node.targets) == 1 and isinstance(node.targets[0], ast.Name)}
+
+    def veto(self, name, shadowed):
+        if name in shadowed:
+            return "comprehension-local-binding"
+        if self.bindings.dynamic or name in self.bindings.redirected:
+            return "reflective-or-cross-scope-binding"
+        return None
+
+    def reference(self, node, scope, shadowed):
+        # An import match is still only spelling; a local link is only a declaration.
+        target, reason = self.bindings.resolve(node, scope, shadowed=shadowed)
+        if target:
+            return {"status": "import-spelling", "reason": reason, "target": target, "definition": None}
+        if not isinstance(node, ast.Name):
+            return unresolved("non-name-reference")
+        veto = self.veto(node.id, shadowed)
+        if veto:
+            return unresolved(veto)
+        while scope:
+            if node.id in scope.bindings:
+                if len(scope.bindings[node.id]) != 1:
+                    return unresolved("rebound-or-ambiguous-name")
+                definition = self.definitions[scope].get(node.id)
+                if definition is None:
+                    return unresolved("not-a-direct-function-definition")
+                if definition.decorator_list:
+                    return unresolved("decorated-definition")
+                if not before(definition, node):
+                    return unresolved("definition-not-before-reference")
+                key = usage.digest(f"{self.file}|{definition.lineno}|{definition.col_offset}|{type(definition).__name__}")
+                owner = self.owners.get(key)
+                if owner is None:
+                    return unresolved("definition-outside-selected-owners")
+                return {"status": "local-definition", "reason": "unique-direct-lexical-definition",
+                        "definition": {"ownerId": key, "file": self.file, "member": owner["member"],
+                                       "functionKind": type(definition).__name__, **usage.extent(definition)}}
+            scope = scope.parent
+        return unresolved("no-local-definition")
+
+    def wrapper(self, node, scope, shadowed, context, owner_id):
+        veto = self.veto(node.id, shadowed)
+        if veto:
+            return unresolved(veto), None
+        if context != "async-body":
+            return unresolved("deferred-execution-context"), None
+        if len(scope.bindings.get(node.id, [])) != 1:
+            return unresolved("not-a-unique-same-owner-binding"), None
+        assignment = self.assignments[scope].get(node.id)
+        if assignment is None or not isinstance(assignment.value, ast.Call):
+            return unresolved("not-a-direct-wrapper-assignment"), None
+        if not before(assignment, node):
+            return unresolved("assignment-not-before-use"), None
+        construction = assignment.value
+        target, _ = self.bindings.resolve(construction.func, scope)
+        if target != usage.WRAPPER:
+            return unresolved("unmatched-wrapper-constructor"), None
+        if not construction.args or isinstance(construction.args[0], ast.Starred):
+            return unresolved("unresolved-argument-layout"), None
+        location = usage.extent(construction)
+        return {"status": "stored-wrapper-syntax", "reason": "unique-direct-same-owner-assignment",
+                "definition": {"name": node.id, "assignment": usage.extent(assignment),
+                               "constructionCallId": usage.fingerprint([owner_id, location]),
+                               "construction": location, "importTarget": target}}, construction.args[0]
+
+
+class ContextCalls(usage.Calls):
+    def __init__(self, bindings, node, owner, provenance):
+        super().__init__(bindings, node, owner)
+        self.provenance, self.contexts = provenance, []
+
+    def record(self, node, context, shadowed, parent):
+        super().record(node, context, shadowed, parent)
+        call = self.rows[-1]
+        local, wrapper, callback = None, None, None
+        callback_node = None
+        if call["category"] in {"offload-call", "offload-wrapper-construction", "offload-wrapped-invocation"}:
+            helper = node.func if call["category"] == "offload-wrapped-invocation" else node
+            if helper.args and not isinstance(helper.args[0], ast.Starred):
+                callback_node = helper.args[0]
+        if call["binding"]["status"] == "unresolved" and isinstance(node.func, ast.Name):
+            local = self.provenance.reference(node.func, self.scope, shadowed)
+            wrapper, callback_node = self.provenance.wrapper(node.func, self.scope, shadowed, context, self.owner["id"])
+        if callback_node is not None:
+            # A stored wrapper's callback was evaluated at construction, outside a use-site comprehension.
+            callback_shadowed = frozenset() if wrapper and wrapper["status"] == "stored-wrapper-syntax" else shadowed
+            callback = {"kind": type(callback_node).__name__,
+                        "evaluation": "eager-call-expression" if isinstance(callback_node, ast.Call) else "callback-expression-only",
+                        "reference": self.provenance.reference(callback_node, self.scope, callback_shadowed)}
+        self.contexts.append({"callId": call["id"], "executionContext": context, "shape": shape(node.func),
+                              "unresolvedReason": call["binding"]["reason"] if call["binding"]["status"] == "unresolved" else None,
+                              "localCallee": local, "storedWrapper": wrapper, "callback": callback})
+
+    def measure(self, node):
+        measurement = super().measure(node)
+        by_id = {row["callId"]: row for row in self.contexts}
+        return measurement, [by_id[call["id"]] for call in measurement["calls"]]

package/dist/python/async_scoring.py

@@ -0,0 +1,203 @@
+"""Standalone Async/Blocking Usage scoring study; no target execution or v3 gates."""
+
+import ast
+from collections import Counter
+from datetime import datetime, timezone
+import io
+from pathlib import Path
+import re
+import tokenize
+
+import async_helper_paths as helpers
+from review_cli import run
+
+usage = helpers.usage
+POLICY = "python/async-blocking-owner-rate-v1"
+INTENT_POLICY = "adjacent-simple-statement-declared-blocking-prose-v1"
+MAX_NODES = 1000000
+LADDER = [
+    {"percent": 1, "inclusive": False, "score": 10},
+    {"percent": 2, "inclusive": False, "score": 9},
+    {"percent": 5, "inclusive": False, "score": 8},
+    {"percent": 10, "inclusive": True, "score": 6},
+    {"percent": 15, "inclusive": True, "score": 4},
+    {"percent": 20, "inclusive": True, "score": 2},
+]
+SIMPLE = (ast.Expr, ast.Return, ast.Assign, ast.AnnAssign, ast.AugAssign, ast.Raise, ast.Assert)
+BOUNDARIES = (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda, ast.ClassDef)
+DIRECTIVE = re.compile(r"^(?:noqa\b|type:|pragma:|fmt:|pylint:|ruff:)", re.I)
+KEYWORD = re.compile(r"\b(?:blocking|synchronous|sync-over-async|sleep)\b", re.I)
+MARKER = re.compile(r"\b(?:TODO|FIXME|HACK|XXX)\b", re.I)
+INTENT = re.compile(r"\b(?:intentional(?:ly)?|deliberate(?:ly)?|required|necessary|unavoidable)\b", re.I)
+CAUTION = re.compile(r"\b(?:not|never|avoid|remove|replace|shouldn't|mustn't|unnecessary)\b", re.I)
+
+
+def owner_score(affected, eligible):
+    """Exact comparisons; displayed percentages never select a band."""
+    if type(eligible) is not int or type(affected) is not int or not 0 <= affected <= eligible:
+        raise ValueError("Owner counts must be integers with 0 <= affected <= eligible.")
+    if not eligible:
+        return None
+    for band in LADDER:
+        left, right = 100 * affected, band["percent"] * eligible
+        if left < right or (band["inclusive"] and left == right):
+            return band["score"]
+    return 0
+
+
+def rationale(text):
+    if (DIRECTIVE.match(text) or MARKER.search(text) or not KEYWORD.search(text)
+            or not INTENT.search(text) or CAUTION.search(text)):
+        return False
+    if len(re.findall(r"[A-Za-z]+", text)) < 2:
+        return False
+    try:
+        ast.parse(text)
+    except SyntaxError:
+        return True
+    return False  # Commented-out code is not an explanation.
+
+
+class IntentIndex:
+    """Attach actual comment tokens only to a single simple statement."""
+
+    def __init__(self, source, budget):
+        self.lines = source.splitlines()
+        tree = ast.parse(source)
+        self.parents, self.calls, self.statements = {}, {}, []
+        for node in ast.walk(tree):
+            budget[0] += 1
+            if budget[0] > MAX_NODES:
+                raise ValueError("Async scoring source-index budget exceeded.")
+            for child in ast.iter_child_nodes(node):
+                self.parents[child] = node
+            if isinstance(node, ast.Call):
+                self.calls[self.key(usage.extent(node))] = node
+            if isinstance(node, ast.stmt):
+                self.statements.append(node)
+        self.starts = Counter(node.lineno for node in self.statements)
+        self.ends = Counter(node.end_lineno for node in self.statements if isinstance(node, SIMPLE))
+        self.comments = {}
+        for token in tokenize.generate_tokens(io.StringIO(source).readline):
+            if token.type == tokenize.COMMENT:
+                self.comments[token.start[0]] = token
+
+    @staticmethod
+    def key(location):
+        return tuple(location[name] for name in ("line", "column", "endLine", "endColumn"))
+
+    def documents(self, location):
+        node = self.calls.get(self.key(location))
+        if node is None:
+            raise ValueError("Blocking path has no matching source call.")
+        while not isinstance(node, ast.stmt):
+            node = self.parents.get(node)
+            if node is None or isinstance(node, BOUNDARIES):
+                return []
+        if not isinstance(node, SIMPLE):
+            return []
+        # Do not let a semicolon, one-line compound suite, or sibling inherit prose.
+        if self.starts[node.lineno] != 1 or self.ends[node.end_lineno] != 1:
+            return []
+        prefix = self.lines[node.lineno - 1].encode("utf-8")[:node.col_offset].decode("utf-8")
+        if prefix.strip():
+            return []
+        found = []
+        for line in (node.lineno - 1, node.end_lineno):
+            token = self.comments.get(line)
+            if token is None:
+                continue
+            before = self.lines[line - 1][:token.start[1]]
+            if line == node.lineno - 1:
+                attached = before == prefix
+            else:
+                end = len(self.lines[line - 1].encode("utf-8")[:node.end_col_offset].decode("utf-8"))
+                attached = token.start[1] >= end and not self.lines[line - 1][end:token.start[1]].strip()
+            text = token.string[1:].strip()
+            if attached and rationale(text):
+                found.append({"line": line, "text": text})
+        return found
+
+
+def classify(trace, indexes):
+    result = {**trace, "documentation": []}
+    if trace["executionContext"] != "async-body":
+        return {**result, "classification": "excluded-execution-context"}
+    documents = []
+    for step in trace["path"]:
+        documents.extend({"file": step["file"], "callId": step["callId"], **item}
+                         for item in indexes[step["file"]].documents(step))
+    return {**result, "documentation": documents,
+            "classification": "documented-choice" if documents else "scored-signal"}
+
+
+def contributions(base, indexes):
+    rows = []
+    for owner in base["functions"]:
+        observations = [classify(trace, indexes) for trace in owner["traces"] if trace["status"] == "blocking-candidate"]
+        eligible = owner["population"] == "production"
+        unresolved = [trace for trace in owner["traces"] if trace["status"] == "unresolved"]
+        rows.append({**{key: owner[key] for key in ("id", "file", "member", "line", "population", "sourceSha256")},
+            "eligible": eligible, "eligibilityReason": "production-async-implementation" if eligible else "nonproduction",
+            "affected": eligible and any(item["classification"] == "scored-signal" for item in observations),
+            "observations": observations, "unresolvedPaths": unresolved})
+    return rows
+
+
+def summarize(rows):
+    eligible = [row for row in rows if row["eligible"]]
+    affected = sum(row["affected"] for row in eligible)
+    observations = [item for row in eligible for item in row["observations"]]
+    unresolved = [item for row in eligible for item in row["unresolvedPaths"]]
+    return {"availability": "available" if eligible else "unavailable", "eligibleOwners": len(eligible),
+        "affectedOwners": affected, "score": owner_score(affected, len(eligible)),
+        "affectedRate": {"numerator": affected, "denominator": len(eligible)} if eligible else None,
+        "excludedOwnersByPopulation": dict(sorted(Counter(row["population"] for row in rows if not row["eligible"]).items())),
+        "observationPathsByClassification": dict(sorted(Counter(item["classification"] for item in observations).items())),
+        "distinctScoredSourceCalls": len({item["path"][-1]["callId"] for item in observations if item["classification"] == "scored-signal"}),
+        "ownersWithUnresolvedPaths": sum(bool(row["unresolvedPaths"]) for row in eligible),
+        "unresolvedPathsByReason": dict(sorted(Counter(item["reason"] for item in unresolved).items()))}
+
+
+def review(target, facts, base):
+    configuration = {"policy": POLICY, "helperConfigurationFingerprint": base["configurationFingerprint"],
+        "intentPolicy": INTENT_POLICY, "maxSourceIndexNodes": MAX_NODES, "ladder": LADDER,
+        "population": "selected-production-async-implementations", "unresolvedTreatment": "visible-without-deduction"}
+    report = {"schemaVersion": 1, "artifactKind": "experimental-python-async-scoring",
+        "producer": {"name": "codemetrics-ai/python-async-scoring", "version": "0.1.0-experimental"},
+        "generatedAtUtc": datetime.now(timezone.utc).isoformat(), "runId": base["runId"], "auditId": base["auditId"],
+        "policy": POLICY, "configuration": configuration, "configurationFingerprint": usage.fingerprint(configuration),
+        "helperRowsSha256": usage.fingerprint(base["functions"]), "subject": base["subject"], "selection": facts["selection"],
+        "sourceFactsProducer": facts["producer"], "sourceFactsPolicy": facts["measurementPolicy"],
+        "status": "incomplete", "diagnostics": [], "functions": [], "summary": None,
+        "scope": "Partial static blocking-catalogue usage score. Import spelling and bounded helper paths, not runtime identity, reachability, throughput, latency, or proof of safe async behavior. Standalone study; no scorecard v3 aggregate or gates. Error Handling remains unscored."}
+    try:
+        original = usage.review(target, facts, run_id=base["runId"], audit_id=base["auditId"])
+        fresh = helpers.review(target, facts, original)
+        stable = lambda value: {key: item for key, item in value.items() if key != "generatedAtUtc"}
+        if fresh["status"] != "complete" or stable(fresh) != stable(base):
+            raise ValueError("Async helper input is incomplete, stale, or inconsistent.")
+        target = Path(target).absolute()
+        root = target if target.is_dir() else target.parent
+        needed = {step["file"] for row in base["functions"] for trace in row["traces"]
+                  if trace["status"] == "blocking-candidate" and trace["executionContext"] == "async-body" for step in trace["path"]}
+        indexes, budget = {}, [0]
+        for record in facts["selection"]["files"]:
+            if record["file"] in needed:
+                indexes[record["file"]] = IntentIndex(usage.read_verified(root, record), budget)
+        rows = contributions(base, indexes)
+        report.update(status="complete", functions=rows, summary=summarize(rows))
+    except (OSError, SyntaxError, UnicodeError, ValueError, RecursionError, KeyError, TypeError, tokenize.TokenError) as error:
+        report["diagnostics"].append({"code": "async-scoring-analysis", "message": str(error)})
+    return report
+
+
+def analyze(target, *, run_id=None, audit_id=None, **selection):
+    facts = usage.source_facts.analyze(target, **selection)
+    original = usage.review(target, facts, run_id=run_id, audit_id=audit_id)
+    base = helpers.review(target, facts, original)
+    return review(target, facts, base)
+
+
+if __name__ == "__main__":
+    raise SystemExit(run(analyze, __doc__))