bmad-module-skill-forge 1.9.0 → 2.0.1

package/src/shared/scripts/skf-structural-diff.py

@@ -6,36 +6,76 @@
 """Structural Diff — Deterministic comparison of skill export inventories.
 
 Compares a baseline export inventory against a current export inventory and
-produces a structured JSON diff showing added, removed, and changed entries.
-Used by audit-skill and update-skill to replace LLM-based inventory comparison.
+produces a structured JSON diff showing added, removed, changed, and moved
+entries. Used by audit-skill (structural-diff step) and update-skill to
+replace LLM-based, token-spending inventory comparison — the LLM can silently
+drop or mis-match entries when diffing dozens/hundreds of exports by hand.
 
 CLI:
   python3 skf-structural-diff.py baseline.json current.json
   python3 skf-structural-diff.py baseline.json current.json -o diff-result.json
+  python3 skf-structural-diff.py provenance-map.json snapshot.json --reexport-map map.json
 
 Input:
-  Two JSON files. Each file must be either:
-    - An object with an "exports" array  (provenance-map / extraction-snapshot format)
+  Two JSON files. Each file may be either:
+    - An object with an "exports" array   (extraction-snapshot format)
+    - An object with an "entries" array    (provenance-map.json format)
     - A plain array of export entries
-
-  Each export entry must have at minimum:
-    - name: string   (primary key for matching)
-    - type: string   (function/class/type/const/interface/etc.)
-
-  Optional fields used for change detection:
-    - signature: string
-    - file: string
-    - line: number
-    - confidence: string
+    - A name-keyed object of entry objects
+
+  Field-name aliasing (provenance-map entries[] vs extraction-snapshot
+  exports[]) is handled transparently, so the two sides may use different
+  shapes:
+    - name        <- name        | export_name
+    - type        <- type        | export_type
+    - file        <- file        | source_file
+    - line        <- line        | source_line
+    - signature   <- signature
+    - confidence  <- confidence
+
+  "name" is the primary match key. Nameless entries are skipped.
+
+Canonicalization (applied symmetrically to BOTH sides before matching):
+  The baseline extractor (skf-create-skill) and the re-extractor (audit step 2)
+  can differ in cosmetic detail that would otherwise surface as false-positive
+  "Changed"/"Removed"/"Added" entries. These deterministic transforms collapse
+  the cosmetic differences:
+    - quote-style          : normalize string-literal quotes in signatures
+                             (double -> single), so `= "Hnsw"` == `= 'Hnsw'`.
+    - stdlib-prefix        : strip module prefixes on well-known stdlib helpers
+                             (typing., dataclasses., collections[.abc]., enum.),
+                             so `typing.Optional[int]` == `Optional[int]`.
+                             User-defined namespaces (e.g. `pkg.typing.X`) are
+                             NOT collapsed.
+    - reexport-resolution  : rewrite internal symbol names to their public
+                             re-export name via the reexport map, so a renamed
+                             public re-export (`_Impl` -> `Public`) matches the
+                             baseline entry instead of showing up as
+                             Removed `_Impl` + Added `Public`.
+
+  The reexport map is taken from --reexport-map when provided; otherwise it is
+  derived from the baseline provenance map itself (top-level `reexport_map`
+  plus any per-entry `reexported_as`) — the same projection produced by
+  `skf-load-provenance.py normalize`.
+
+Change detection:
+  A field is only compared when present (non-null) on BOTH sides — a field
+  absent on one side means "insufficient data", never an asserted change. This
+  avoids false positives when the two inventories carry different metadata.
 
 Output:
   JSON object:
-    summary:          { added, removed, changed, moved, unchanged }
-    added:            list of entries present in current but not baseline
-    removed:          list of entries present in baseline but not current
-    changed:          list of { name, field, baseline_value, current_value }
-    moved:            list of { name, previous_file, current_file }
-    unchanged_count:  number of entries that matched exactly
+    summary:            { added, removed, changed, moved, unchanged }
+    added:              list of entries present in current but not baseline
+    removed:            list of entries present in baseline but not current
+    changed:            list of { name, field, baseline_value, current_value }
+    moved:              list of { name, previous_file, current_file }
+    unchanged_count:    number of entries that matched with no field change
+    applied_transforms: list of { transform, count } — which canonicalization
+                        transforms actually fired and how many values each
+                        touched (empty when none fired). Surfaced by audit
+                        step 6's Provenance section so a reviewer can tell
+                        which differences the diff collapsed.
 
 Exit codes:
   0  — inventories are identical (no diff)
@@ -45,7 +85,9 @@ Exit codes:
 from __future__ import annotations
 
 import argparse
+import collections
 import json
+import re
 import sys
 from pathlib import Path
 
@@ -55,68 +97,220 @@ from pathlib import Path
 # "file" is excluded — file moves are tracked separately in the "moved" list.
 DIFF_FIELDS = ["type", "signature", "line", "confidence"]
 
+# Well-known stdlib module prefixes whose unqualified form is importable at
+# the call site. Longer prefixes must precede their own containing prefix
+# (collections.abc before collections) so the alternation strips the longest.
+# The negative lookbehind `(?<![\w.])` ensures we only strip a top-level module
+# reference — never a user-defined namespace such as `pkg.typing.Foo`.
+_STDLIB_PREFIX_RE = re.compile(
+    r"(?<![\w.])(?:typing|dataclasses|collections\.abc|collections|enum)\."
+)
 
-def load_inventory(path: Path) -> tuple[list[dict], str | None]:
-    """Load an export inventory from a JSON file.
 
-    Accepts either:
-      - {"exports": [...]}  (provenance-map / extraction-snapshot)
-      - [...]               (plain array)
+# --------------------------------------------------------------------------
+# Loading
+# --------------------------------------------------------------------------
 
-    Returns (exports, error_message).
-    """
+
+def load_json(path: Path) -> tuple[object, str | None]:
+    """Read and parse a JSON file. Returns (data, error_message)."""
     try:
         text = path.read_text(encoding="utf-8")
     except OSError as exc:
-        return [], f"Cannot read file '{path}': {exc}"
-
+        return None, f"Cannot read file '{path}': {exc}"
     try:
-        data = json.loads(text)
+        return json.loads(text), None
     except json.JSONDecodeError as exc:
-        return [], f"Invalid JSON in '{path}': {exc}"
+        return None, f"Invalid JSON in '{path}': {exc}"
 
+
+def entries_from_data(data: object, source: str = "") -> tuple[list[dict], str | None]:
+    """Extract the export-entry list from an already-parsed inventory.
+
+    Accepts:
+      - [...]                 (plain array)
+      - {"exports": [...]}    (extraction-snapshot format)
+      - {"entries": [...]}    (provenance-map.json format)
+      - {name: {...}, ...}    (name-keyed object of entry objects)
+
+    Returns (entries, error_message).
+    """
+    where = f" in '{source}'" if source else ""
     if isinstance(data, list):
         return data, None
     if isinstance(data, dict):
-        if "exports" in data and isinstance(data["exports"], list):
+        if isinstance(data.get("exports"), list):
             return data["exports"], None
-        # If it's a plain object without "exports", treat values as entries
-        # (some inventory formats are name-keyed objects)
-        if all(isinstance(v, dict) for v in data.values()):
-            return list(data.values()), None
-        return [], f"Unrecognised inventory format in '{path}': expected array or object with 'exports' key"
+        if isinstance(data.get("entries"), list):
+            return data["entries"], None
+        # A plain name-keyed object of entries (some inventory formats).
+        values = list(data.values())
+        if values and all(isinstance(v, dict) for v in values):
+            return values, None
+        return [], (
+            f"Unrecognised inventory format{where}: expected array or object "
+            f"with an 'exports' or 'entries' key"
+        )
+    return [], f"Unrecognised inventory format{where}: top-level value must be array or object"
+
 
-    return [], f"Unrecognised inventory format in '{path}': top-level value must be array or object"
+def load_inventory(path: Path) -> tuple[list[dict], str | None]:
+    """Load an export inventory from a JSON file (thin wrapper, back-compat).
+
+    Returns (exports, error_message).
+    """
+    data, err = load_json(path)
+    if err:
+        return [], err
+    return entries_from_data(data, str(path))
+
+
+# --------------------------------------------------------------------------
+# Re-export map
+# --------------------------------------------------------------------------
+
+
+def extract_reexport_map(data: object) -> dict[str, str]:
+    """Derive the {internal -> public} re-export map from a provenance map.
+
+    Mirrors skf-load-provenance.extract_reexport_map:
+      1. top-level `reexport_map` object, plus
+      2. per-entry `reexported_as` on `entries[]` items
+         ({"export_name": "_Impl", "reexported_as": "Public"}).
+    Non-string keys/values are skipped. Returns {} for non-dict input.
+    """
+    out: dict[str, str] = {}
+    if not isinstance(data, dict):
+        return out
+    top = data.get("reexport_map")
+    if isinstance(top, dict):
+        for k, v in top.items():
+            if isinstance(k, str) and isinstance(v, str):
+                out[k] = v
+    entries = data.get("entries")
+    if isinstance(entries, list):
+        for entry in entries:
+            if not isinstance(entry, dict):
+                continue
+            internal = entry.get("export_name")
+            public = entry.get("reexported_as")
+            if isinstance(internal, str) and isinstance(public, str):
+                out.setdefault(internal, public)
+    return out
+
+
+def load_reexport_map(path: Path) -> tuple[dict[str, str], str | None]:
+    """Load an explicit re-export map file.
+
+    Accepts either a plain {internal: public} object or the full
+    `skf-load-provenance.py normalize` output (which nests it under the
+    `reexport_map` key). Non-string pairs are skipped.
+    """
+    data, err = load_json(path)
+    if err:
+        return {}, err
+    if not isinstance(data, dict):
+        return {}, f"reexport map '{path}' must be a JSON object"
+    src = data["reexport_map"] if isinstance(data.get("reexport_map"), dict) else data
+    return {k: v for k, v in src.items() if isinstance(k, str) and isinstance(v, str)}, None
 
 
-def index_by_name(entries: list[dict]) -> dict[str, dict]:
-    """Build a name-keyed dict from an export list, skipping nameless entries."""
+# --------------------------------------------------------------------------
+# Canonicalization
+# --------------------------------------------------------------------------
+
+
+def _first(entry: dict, *keys: str) -> object:
+    """First non-null value among the given keys (field-name aliasing)."""
+    for k in keys:
+        v = entry.get(k)
+        if v is not None:
+            return v
+    return None
+
+
+def canon_signature(sig: object) -> tuple[object, set[str]]:
+    """Canonicalize a signature string. Returns (canonical, transforms_fired).
+
+    Non-string input passes through unchanged (empty transform set).
+    """
+    if not isinstance(sig, str):
+        return sig, set()
+    applied: set[str] = set()
+    out = sig
+    if '"' in out:
+        out = out.replace('"', "'")
+        applied.add("quote-style")
+    stripped = _STDLIB_PREFIX_RE.sub("", out)
+    if stripped != out:
+        applied.add("stdlib-prefix")
+        out = stripped
+    return out, applied
+
+
+def _normalize_entries(
+    entries: list[dict],
+    reexport_map: dict[str, str],
+    transform_counts: collections.Counter,
+) -> dict[str, dict]:
+    """Build a name-keyed dict of canonicalized records.
+
+    Applies field-name aliasing, signature canonicalization, and re-export
+    name resolution. Accumulates fired-transform counts into transform_counts.
+    Nameless entries are skipped. On duplicate resolved names, the last entry
+    wins (consistent with prior behaviour).
+    """
     result: dict[str, dict] = {}
     for entry in entries:
-        name = entry.get("name", "").strip()
-        if name:
-            result[name] = entry
+        if not isinstance(entry, dict):
+            continue
+        raw_name = _first(entry, "name", "export_name")
+        if not isinstance(raw_name, str) or not raw_name.strip():
+            continue
+        name = raw_name.strip()
+        resolved = reexport_map.get(name, name)
+        if resolved != name:
+            transform_counts["reexport-resolution"] += 1
+            name = resolved
+
+        canon_sig, sig_transforms = canon_signature(entry.get("signature"))
+        for t in sig_transforms:
+            transform_counts[t] += 1
+
+        # Normalized record — also the public entry shape emitted in
+        # added[]/removed[], so both sides render into one consistent table
+        # regardless of the input shape they came from.
+        result[name] = {
+            "name": name,
+            "type": _first(entry, "type", "export_type"),
+            "signature": canon_sig,
+            "file": _first(entry, "file", "source_file"),
+            "line": _first(entry, "line", "source_line"),
+            "confidence": entry.get("confidence"),
+        }
     return result
 
 
-def entry_matches(base: dict, curr: dict) -> bool:
-    """Return True if two entries are identical across all DIFF_FIELDS."""
-    for field in DIFF_FIELDS:
-        if base.get(field) != curr.get(field):
-            return False
-    return True
+# --------------------------------------------------------------------------
+# Diff
+# --------------------------------------------------------------------------
 
 
 def diff_inventories(
     baseline_entries: list[dict],
     current_entries: list[dict],
+    reexport_map: dict[str, str] | None = None,
 ) -> dict:
     """Compute the structural diff between two export inventories.
 
-    Returns a dict with keys: summary, added, removed, changed, unchanged_count.
+    Returns a dict with keys: summary, added, removed, changed, moved,
+    unchanged_count, applied_transforms.
     """
-    baseline = index_by_name(baseline_entries)
-    current = index_by_name(current_entries)
+    reexport_map = reexport_map or {}
+    transform_counts: collections.Counter = collections.Counter()
+
+    baseline = _normalize_entries(baseline_entries, reexport_map, transform_counts)
+    current = _normalize_entries(current_entries, reexport_map, transform_counts)
 
     baseline_names = set(baseline.keys())
     current_names = set(current.keys())
@@ -125,6 +319,9 @@ def diff_inventories(
     removed_names = baseline_names - current_names
     common_names = baseline_names & current_names
 
+    # Emit normalized entries (uniform name/type/signature/file/line/confidence
+    # shape) so added[] and removed[] render into the same report table even
+    # though they originate from the snapshot and provenance-map shapes.
     added = [current[n] for n in sorted(added_names)]
     removed = [baseline[n] for n in sorted(removed_names)]
 
@@ -133,12 +330,12 @@ def diff_inventories(
     unchanged_count = 0
 
     for name in sorted(common_names):
-        base_entry = baseline[name]
-        curr_entry = current[name]
+        base_rec = baseline[name]
+        curr_rec = current[name]
 
-        # Detect file moves separately
-        base_file = base_entry.get("file")
-        curr_file = curr_entry.get("file")
+        # File moves are tracked separately from field changes.
+        base_file = base_rec.get("file")
+        curr_file = curr_rec.get("file")
         if base_file and curr_file and base_file != curr_file:
             moved.append({
                 "name": name,
@@ -148,8 +345,12 @@ def diff_inventories(
 
         entry_changed = False
         for field in DIFF_FIELDS:
-            base_val = base_entry.get(field)
-            curr_val = curr_entry.get(field)
+            base_val = base_rec.get(field)
+            curr_val = curr_rec.get(field)
+            # Compare only when data is present on both sides; a missing value
+            # on either side is insufficient evidence to assert a change.
+            if base_val is None or curr_val is None:
+                continue
             if base_val != curr_val:
                 changed.append({
                     "name": name,
@@ -162,9 +363,14 @@ def diff_inventories(
         if not entry_changed:
             unchanged_count += 1
 
-    # Count distinct names that have at least one field change
     changed_names = len({c["name"] for c in changed})
 
+    applied_transforms = [
+        {"transform": name, "count": transform_counts[name]}
+        for name in sorted(transform_counts)
+        if transform_counts[name] > 0
+    ]
+
     return {
         "summary": {
             "added": len(added),
@@ -178,18 +384,26 @@ def diff_inventories(
         "changed": changed,
         "moved": moved,
         "unchanged_count": unchanged_count,
+        "applied_transforms": applied_transforms,
     }
 
 
+# --------------------------------------------------------------------------
+# CLI
+# --------------------------------------------------------------------------
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(
         prog="skf-structural-diff.py",
         description=(
             "Compare two JSON export inventories and produce a structured diff.\n"
             "\n"
-            "Each inventory file must be either a JSON array of export entries\n"
-            "or a JSON object with an 'exports' key containing such an array.\n"
-            "Every entry must have at minimum 'name' and 'type' fields.\n"
+            "Each inventory may be a JSON array of export entries, an object with\n"
+            "an 'exports' key (extraction-snapshot), or an object with an 'entries'\n"
+            "key (provenance-map.json). Field names are aliased across the two\n"
+            "shapes, and signatures are canonicalized (quote style, stdlib module\n"
+            "prefixes, public re-export names) symmetrically before matching.\n"
             "\n"
             "Exit code 0 means no differences were found.\n"
             "Exit code 1 means differences were found (or an error occurred)."
@@ -197,8 +411,9 @@ def main() -> int:
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog=(
             "examples:\n"
-            "  python3 skf-structural-diff.py provenance-map.json current-snapshot.json\n"
+            "  python3 skf-structural-diff.py provenance-map.json extraction-snapshot.json\n"
             "  python3 skf-structural-diff.py baseline.json current.json -o diff.json\n"
+            "  python3 skf-structural-diff.py provenance-map.json snapshot.json --reexport-map map.json\n"
         ),
     )
     parser.add_argument(
@@ -211,6 +426,15 @@ def main() -> int:
         metavar="current.json",
         help="path to the current export inventory (e.g. extraction-snapshot.json)",
     )
+    parser.add_argument(
+        "--reexport-map",
+        metavar="FILE",
+        help=(
+            "path to a JSON re-export map ({internal: public}) or a "
+            "skf-load-provenance normalize output. When omitted, the map is "
+            "derived from the baseline provenance map itself."
+        ),
+    )
     parser.add_argument(
         "-o",
         "--output",
@@ -223,17 +447,33 @@ def main() -> int:
     baseline_path = Path(args.baseline)
     current_path = Path(args.current)
 
-    baseline_entries, err = load_inventory(baseline_path)
+    baseline_data, err = load_json(baseline_path)
+    if err:
+        print(json.dumps({"status": "error", "error": err}, indent=2))
+        return 1
+    current_data, err = load_json(current_path)
     if err:
         print(json.dumps({"status": "error", "error": err}, indent=2))
         return 1
 
-    current_entries, err = load_inventory(current_path)
+    baseline_entries, err = entries_from_data(baseline_data, str(baseline_path))
     if err:
         print(json.dumps({"status": "error", "error": err}, indent=2))
         return 1
+    current_entries, err = entries_from_data(current_data, str(current_path))
+    if err:
+        print(json.dumps({"status": "error", "error": err}, indent=2))
+        return 1
+
+    if args.reexport_map:
+        reexport_map, err = load_reexport_map(Path(args.reexport_map))
+        if err:
+            print(json.dumps({"status": "error", "error": err}, indent=2))
+            return 1
+    else:
+        reexport_map = extract_reexport_map(baseline_data)
 
-    result = diff_inventories(baseline_entries, current_entries)
+    result = diff_inventories(baseline_entries, current_entries, reexport_map)
     output_text = json.dumps(result, indent=2)
 
     if args.output:

package/src/shared/scripts/skf-validate-brief-schema.py

@@ -5,8 +5,8 @@
 """SKF Validate Brief Schema — schema check for a skill-brief.yaml on disk.
 
 Loads `skill-brief.yaml` from a path (or from stdin/inline-YAML), validates
-it against `src/shared/scripts/schemas/skill-brief.v1.json`, and applies the
-two conditional rules from `skf-create-skill/references/load-brief.md §3`
+it against `schemas/skill-brief.v1.json` (sibling of this script), and applies the
+conditional rules from `skf-create-skill/references/load-brief.md §3`
 that the JSON schema doesn't express today:
 
   - When `source_type == "docs-only"`: `doc_urls` must have ≥1 entry, and
@@ -18,6 +18,11 @@ that the JSON schema doesn't express today:
     only contains whitespace would slip past a naive presence check; we
     catch that case explicitly so the downstream directory-resolution code
     doesn't produce `{name}//` paths.
+  - `scope.include` must contain ≥1 glob pattern for every scope type except
+    `docs-only`. The schema requires the `scope.include` key but types it as
+    an array without a `minItems` floor; this rule enforces the non-empty
+    constraint conditional on `scope.type`, matching brief-skill's
+    consumption-time validation.
 
 The script produces skill-friendly error messages — translating raw
 jsonschema diagnostics into the "Brief validation failed: ..." form the
@@ -56,10 +61,7 @@ import yaml
 from jsonschema import Draft202012Validator
 
 
-REPO_ROOT = Path(__file__).resolve().parent.parent.parent.parent
-SCHEMA_PATH = (
-    REPO_ROOT / "src" / "shared" / "scripts" / "schemas" / "skill-brief.v1.json"
-)
+SCHEMA_PATH = Path(__file__).resolve().parent / "schemas" / "skill-brief.v1.json"
 
 
 # --------------------------------------------------------------------------
@@ -265,6 +267,38 @@ def _version_non_empty_rule(brief: dict) -> list[dict]:
     return []
 
 
+def _scope_include_non_empty_rule(brief: dict) -> list[dict]:
+    """`scope.include` must carry ≥1 glob pattern, except for docs-only scope.
+
+    The JSON schema requires the `scope.include` key and types it as an array of
+    strings, but cannot express the non-empty constraint conditional on
+    `scope.type`. A `docs-only` skill has no source globs to include, so it is
+    exempt; every other scope type must name at least one pattern or the
+    downstream extraction has nothing to walk. Surfacing it here keeps the
+    deterministic gate consistent with brief-skill's consumption-time
+    validation instead of paying the model to re-check structure each run.
+    """
+    scope = brief.get("scope")
+    if not isinstance(scope, dict):
+        # missing/malformed scope is the schema's `required`/`type` job
+        return []
+    if scope.get("type") == "docs-only":
+        return []
+    include = scope.get("include")
+    if not (isinstance(include, list) and len(include) >= 1):
+        return [
+            {
+                "field": "scope.include",
+                "message": (
+                    "Brief validation failed: `scope.include` must contain at "
+                    "least one glob pattern (docs-only scope excepted). "
+                    "Update your skill-brief.yaml and re-run."
+                ),
+            }
+        ]
+    return []
+
+
 # --------------------------------------------------------------------------
 # Main validate
 # --------------------------------------------------------------------------
@@ -287,6 +321,7 @@ def validate_brief(brief: dict) -> dict:
 
     errors.extend(_version_non_empty_rule(brief))
     errors.extend(_target_version_matches_version_rule(brief))
+    errors.extend(_scope_include_non_empty_rule(brief))
 
     return {
         "valid": not errors,