bmad-module-skill-forge 1.9.0 → 2.0.0

package/src/shared/scripts/skf-extract-public-api.py

@@ -261,6 +261,29 @@ def parse_settings_gradle(content: str) -> list[str]:
     return modules
 
 
+def parse_package_swift(content: str) -> dict:
+    """Best-effort parse of a SwiftPM Package.swift manifest.
+
+    SwiftPM has no version field in the manifest (versions come from git tags),
+    so `version` is always None; the brief falls back to target_version / default.
+    """
+    name_m = re.search(r"\bPackage\s*\(\s*name:\s*['\"]([^'\"]+)['\"]", content, re.DOTALL)
+    deps: list[str] = []
+    for m in re.finditer(r"\.package\s*\(\s*url:\s*['\"]([^'\"]+)['\"]", content):
+        seg = m.group(1).rstrip("/").rsplit("/", 1)[-1]
+        if seg.endswith(".git"):
+            seg = seg[: -len(".git")]
+        if seg:
+            deps.append(seg)
+    return {
+        "name": name_m.group(1).strip() if name_m else None,
+        "version": None,
+        "description": None,
+        "dependencies": deps,
+        "modules": [],
+    }
+
+
 # --------------------------------------------------------------------------
 # Export scanners
 # --------------------------------------------------------------------------
@@ -388,6 +411,35 @@ def scan_exports_kotlin(content: str, source_file: str) -> list[dict]:
     return out
 
 
+# Swift declarations are public only when explicitly marked `public`/`open`
+# (the default is internal). The lazy `[^\n]*?` skips intervening modifiers
+# (final/static/class-method/@attributes) between the access keyword and the
+# declaration keyword.
+_SWIFT_DECL_RE = re.compile(
+    r"^\s*(?:public|open)\b[^\n]*?\b"
+    r"(func|class|struct|enum|protocol|actor|typealias|var|let)\s+([A-Za-z_]\w*)",
+    re.MULTILINE,
+)
+_SWIFT_DECL_KEYWORDS = {
+    "func", "class", "struct", "enum", "protocol", "actor", "typealias", "var", "let",
+}
+
+
+def scan_exports_swift(content: str, source_file: str) -> list[dict]:
+    """Swift defaults to internal — emit only public/open declarations."""
+    out: list[dict] = []
+    seen: set[str] = set()
+    for m in _SWIFT_DECL_RE.finditer(content):
+        name = m.group(2)
+        # Guard the rare `public class func foo` case where the lazy skip stops
+        # on the `class` modifier and captures the next keyword as the name.
+        if name in _SWIFT_DECL_KEYWORDS or name in seen:
+            continue
+        seen.add(name)
+        out.append({"name": name, "type": m.group(1), "source_file": source_file})
+    return out
+
+
 # --------------------------------------------------------------------------
 # Orchestrator
 # --------------------------------------------------------------------------
@@ -405,6 +457,7 @@ LANGUAGE_DISPATCH: dict[str, tuple[ManifestParser, ExportScanner]] = {
     "go": (parse_go_mod, scan_exports_go),
     "java": (parse_pom_xml, scan_exports_java),
     "kotlin": (parse_gradle, scan_exports_kotlin),
+    "swift": (parse_package_swift, scan_exports_swift),
 }
 
 

package/src/shared/scripts/skf-language-corpora.py

@@ -0,0 +1,100 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = []
+# ///
+"""SKF Language Corpora — canonical companion prose corpora for a language.
+
+A whole-language skill (issue #427) is forged from a language-reference repo
+(a compiler/interpreter such as rust-lang/rust). That repo carries the
+language's CODE, but a skill's value comes from the language's PROSE — the
+guide/Book, the standard/library API docs, idioms. README detection
+(skf-detect-docs.py) is the primary source for those; this lookup guarantees
+the canonical corpora for well-known languages even when the repo's README
+does not link them.
+
+Pure static lookup over src/shared/data/language-corpora.json — no network,
+no git, no `gh`. Output is the brief `doc_urls` contract (`{url, label,
+source}`), with `source` fixed to `"language-registry"` (issue #432), so the
+result can be seeded directly into a skill brief and later distinguished from
+README-detected docs.
+
+CLI:
+  uv run src/shared/scripts/skf-language-corpora.py --language <id>
+
+Output (JSON array on stdout): [{"url": "...", "label": "...", "source": "language-registry"}, ...]
+
+Exit codes:
+  0  registry hit — one or more corpora emitted
+  1  no entry for this language (long-tail / unknown) — emits []
+  2  error (bad args, missing/unreadable/invalid data file)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+_DATA_FILE = Path(__file__).resolve().parent.parent / "data" / "language-corpora.json"
+
+
+def _die(message: str, code: str = "INTERNAL_ERROR") -> None:
+    json.dump({"error": message, "code": code}, sys.stderr, ensure_ascii=False)
+    sys.stderr.write("\n")
+    sys.exit(2)
+
+
+def _load_registry() -> dict:
+    try:
+        data = json.loads(_DATA_FILE.read_text(encoding="utf-8"))
+    except OSError as exc:
+        _die(f"Cannot read {_DATA_FILE.as_posix()}: {exc}", "DATA_READ_ERROR")
+    except json.JSONDecodeError as exc:
+        _die(f"Cannot parse {_DATA_FILE.as_posix()}: {exc}", "DATA_PARSE_ERROR")
+    if not isinstance(data, dict):
+        _die("Corpora registry must be a JSON object", "DATA_PARSE_ERROR")
+    return data
+
+
+def corpora_for(language: str) -> list[dict]:
+    """Return the `{url, label, source}` corpora for a language id, or [] if none.
+
+    Every emitted entry is stamped `source: "language-registry"` (issue #432) so
+    downstream — the brief writer, the noise-suppression filter (#431), and the
+    assembly tier-ordering (#430) — can distinguish a registry-guaranteed
+    corpus from an opportunistically README-detected doc.
+    """
+    registry = _load_registry()
+    entries = registry.get((language or "").strip().lower())
+    if not isinstance(entries, list):
+        return []
+    out: list[dict] = []
+    for e in entries:
+        if isinstance(e, dict) and e.get("url"):
+            out.append({
+                "url": e["url"],
+                "label": e.get("label", ""),
+                "source": "language-registry",
+            })
+    return out
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        description="Look up canonical companion prose corpora for a language.",
+    )
+    parser.add_argument(
+        "--language", required=True,
+        help="Lowercase language id (rust, python, go, typescript, ruby, ...)",
+    )
+    args = parser.parse_args(argv)
+
+    result = corpora_for(args.language)
+    json.dump(result, sys.stdout, ensure_ascii=False)
+    sys.stdout.write("\n")
+    return 0 if result else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/src/shared/scripts/skf-merge-doc-urls.py

@@ -0,0 +1,244 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = []
+# ///
+"""SKF Merge Doc URLs — merge corpora-seeded + detected docs for a skill brief.
+
+Deterministic merge of an upstream brief's `doc_urls` (registry-seeded
+companion corpora, source: language-registry) with the docs freshly
+discovered by `skf-detect-docs.py` (mapped to the brief `{url, label, source}`
+contract). Replaces the prose dedup/suppression that lived inline in
+`skf-brief-skill/references/step-auto-brief.md` §3 — that logic is fiddly
+(normalized-URL collisions, non-corpus path segments, locale duplicates) and
+must behave identically on every run, so it belongs in a tested script.
+
+Three operations, in order:
+
+  1. Normalized-URL dedup — lowercase host, strip a trailing `/index.html`
+     and any trailing `/` before comparing, so a seeded `…/book/` and a
+     README's `…/book/index.html` collapse to one entry. Existing
+     (corpora-seeded) entries always win and are NEVER dropped.
+
+  2. Non-corpus segment suppression (whole-language references only) — when
+     the brief is a whole-language reference (scope_type == "full-library"
+     AND ≥1 existing entry carries source == "language-registry"), drop a
+     README-detected entry whose host matches a registry corpus host and
+     whose path contains a known non-corpus segment (whatsnew / contribute /
+     wiki). Path-component-anchored, never a bare substring — `/whatsnew/`
+     and `/whatsnew-2024/` drop, `/docs/whatsnewfeatures/` does not.
+
+  3. Non-primary-locale collapse (whole-language references only) — drop a
+     README-detected entry on a registry host whose leading path segment is a
+     non-primary locale (e.g. `/ja/master/`) when a locale-stripped twin is
+     already kept (e.g. a seeded `/en/master/` or `/master/`). Twin-required:
+     a `/ja/…` page with no `/en/…` counterpart is kept.
+
+Suppression is GATED on the whole-language marker so ordinary skills pass
+through with byte-identical merge behaviour (dedup only). N==0 whole-language
+references (registry miss → no seeded corpora) carry no language-registry
+entry, so the gate is inactive and their README docs are NOT suppressed — the
+DEGRADED case is intentionally out of scope (there is no canonical corpus host
+to anchor suppression against).
+
+CLI:
+  echo '{"scope_type": "...", "existing": [...], "detected": [...]}' \
+    | uv run src/shared/scripts/skf-merge-doc-urls.py
+
+Input (JSON object on stdin):
+  {
+    "scope_type": "full-library",
+    "existing":   [{"url": "...", "label": "...", "source": "language-registry"}, ...],
+    "detected":   [{"url": "...", "label": "...", "source": "readme-detection"}, ...]
+  }
+
+Output (JSON object on stdout):
+  {
+    "doc_urls":   [{"url": "...", "label": "...", "source": "..."}, ...],
+    "suppressed": [{"url": "...", "reason": "non-corpus-segment|non-primary-locale-dup"}, ...]
+  }
+
+Exit codes:
+  0  success (merged list emitted)
+  2  error (bad JSON, wrong input shape)
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from typing import Any
+from urllib.parse import urlsplit
+
+# Path components (case-insensitive) that mark a non-corpus page on a doc host:
+# changelogs/news, contribution guides, wikis. Matched as whole path components
+# (or component + a separator), never as a bare substring.
+_NON_CORPUS_SEGMENTS = ("whatsnew", "contribute", "wiki")
+
+# Closed allowlist of plausible doc-site locale codes. A leading path segment is
+# treated as a locale only when it is in this set (or a `ll-rr` form whose
+# language part is). Keeps a genuine subsection like `/go/` or `/is/` from being
+# misread as a locale.
+_LOCALE_CODES = {
+    "en", "ja", "zh", "ko", "fr", "de", "es", "pt", "ru", "it", "nl", "pl",
+    "tr", "uk", "cs", "id", "vi", "fa", "ar", "hi", "th", "sv", "da", "fi",
+    "nb", "no", "hu", "ro", "el", "he", "bg", "hr", "sk", "sl", "et", "lv",
+    "lt", "sr", "ca",
+}
+_LOCALE_REGION_RE = re.compile(r"^([a-z]{2})-[a-z]{2}$")
+
+
+def _norm_parts(url: str) -> tuple[str, str]:
+    """Return (lowercased host, normalized path) for dedup / host matching.
+
+    Path normalization strips a trailing `/index.html` and any trailing `/`.
+    Scheme, query, and fragment are ignored — a doc page is identified by its
+    host + path.
+    """
+    parts = urlsplit(url.strip())
+    host = parts.netloc.lower()
+    path = parts.path
+    low = path.lower()
+    if low.endswith("/index.html"):
+        path = path[: -len("/index.html")]
+    path = path.rstrip("/")
+    return host, path
+
+
+def _norm_key(url: str) -> tuple[str, str]:
+    return _norm_parts(url)
+
+
+def _is_locale(seg: str) -> bool:
+    s = seg.lower()
+    if s in _LOCALE_CODES:
+        return True
+    m = _LOCALE_REGION_RE.match(s)
+    return bool(m) and m.group(1) in _LOCALE_CODES
+
+
+def _is_primary_locale(seg: str) -> bool:
+    s = seg.lower()
+    return s == "en" or s.startswith("en-")
+
+
+def _path_segments(path: str) -> list[str]:
+    return [s for s in path.split("/") if s]
+
+
+def _locale_stripped_key(url: str) -> tuple[str, str, bool, bool]:
+    """Return (host, path-without-leading-locale, has_locale, is_primary).
+
+    The third/fourth flags let the caller tell `/ja/master/` (non-primary
+    locale) apart from `/master/` (no locale) and `/en/master/` (primary).
+    """
+    host, path = _norm_parts(url)
+    segs = _path_segments(path)
+    has_locale = bool(segs) and _is_locale(segs[0])
+    is_primary = has_locale and _is_primary_locale(segs[0])
+    if has_locale:
+        segs = segs[1:]
+    return host, "/".join(segs), has_locale, is_primary
+
+
+def _matches_non_corpus_segment(path: str) -> bool:
+    for seg in _path_segments(path):
+        low = seg.lower()
+        for token in _NON_CORPUS_SEGMENTS:
+            if low == token:
+                return True
+            # component + separator (whatsnew-2024) — but NOT whatsnewfeatures
+            if low.startswith(token) and len(low) > len(token) and not low[len(token)].isalnum():
+                return True
+    return False
+
+
+def merge_doc_urls(
+    scope_type: str,
+    existing: list[dict[str, Any]],
+    detected: list[dict[str, Any]],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """Merge existing (seeded) + detected doc_urls. Returns (doc_urls, suppressed)."""
+    kept: list[dict[str, Any]] = []
+    suppressed: list[dict[str, Any]] = []
+    seen: set[tuple[str, str]] = set()
+
+    # 1. Existing (corpora-seeded) entries win and are never dropped.
+    for e in existing:
+        if not isinstance(e, dict) or not e.get("url"):
+            continue
+        key = _norm_key(e["url"])
+        if key in seen:
+            continue
+        seen.add(key)
+        kept.append(e)
+
+    # Whole-language gate: registry-seeded corpora present on a full-library brief.
+    registry_hosts = {
+        _norm_parts(e["url"])[0]
+        for e in kept
+        if isinstance(e, dict) and e.get("url") and e.get("source") == "language-registry"
+    }
+    suppression_active = scope_type == "full-library" and bool(registry_hosts)
+
+    for d in detected:
+        if not isinstance(d, dict) or not d.get("url"):
+            continue
+        url = d["url"]
+        key = _norm_key(url)
+        if key in seen:
+            continue  # dedup — a seeded/earlier entry already covers this URL
+
+        if suppression_active:
+            host, path = _norm_parts(url)
+            if host in registry_hosts:
+                if _matches_non_corpus_segment(path):
+                    suppressed.append({"url": url, "reason": "non-corpus-segment"})
+                    continue
+                dh, dpath, has_locale, is_primary = _locale_stripped_key(url)
+                if has_locale and not is_primary:
+                    twin = any(
+                        _locale_stripped_key(k["url"])[0] == dh
+                        and _locale_stripped_key(k["url"])[1] == dpath
+                        for k in kept
+                        if k.get("url")
+                    )
+                    if twin:
+                        suppressed.append({"url": url, "reason": "non-primary-locale-dup"})
+                        continue
+
+        seen.add(key)
+        kept.append(d)
+
+    return kept, suppressed
+
+
+def main() -> int:
+    raw = sys.stdin.read()
+    if not raw or not raw.strip():
+        sys.stderr.write("skf-merge-doc-urls: empty stdin (expected JSON object)\n")
+        return 2
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        sys.stderr.write(f"skf-merge-doc-urls: invalid JSON on stdin: {exc}\n")
+        return 2
+    if not isinstance(payload, dict):
+        sys.stderr.write("skf-merge-doc-urls: input must be a JSON object\n")
+        return 2
+
+    scope_type = payload.get("scope_type") or ""
+    existing = payload.get("existing") or []
+    detected = payload.get("detected") or []
+    if not isinstance(existing, list) or not isinstance(detected, list):
+        sys.stderr.write("skf-merge-doc-urls: 'existing' and 'detected' must be arrays\n")
+        return 2
+
+    doc_urls, suppressed = merge_doc_urls(scope_type, existing, detected)
+    json.dump({"doc_urls": doc_urls, "suppressed": suppressed}, sys.stdout, ensure_ascii=False)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/shared/scripts/skf-preapply.py

@@ -9,7 +9,7 @@ registry, then scans target directory files for fingerprint matches and applies
 the corresponding fixes.
 
 CLI:
-  uv run python src/shared/scripts/skf-preapply.py \
+  uv run src/shared/scripts/skf-preapply.py \
       --target-dir <path> [--registry <path>] [--local-registry <path>] [--log-dir <path>]
 
 Input: