com.elestrago.unity.package-tools 2.0.11 → 2.1.0

package/Samples~/ClaudeSkills/unity-package-docs/unity-package-docs/scripts/scan_package.py

@@ -0,0 +1,504 @@
+#!/usr/bin/env python3
+"""Scan a Unity package source tree (and optional sample dirs) and emit a JSON manifest.
+
+The manifest is consumed by the unity-package-docs skill to render README.md,
+manual.md, api.md and samples.md. Paths in the manifest are relative to --repo-root
+(default: cwd) so the consumer can use them verbatim in markdown.
+
+Usage:
+    scan_package.py --package <pkg-dir> [--samples <dir> ...] [--repo-root <dir>]
+
+The script uses only the Python standard library. It is best-effort regex-based C#
+parsing: good enough for well-formatted Unity editor code, not a full Roslyn parser.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Iterable
+
+# ---------------------------------------------------------------------------
+# Source normalization: replace string and comment contents with whitespace so
+# brace counts and regex matches are not fooled by braces in strings/comments.
+# Preserves line numbers (newlines are kept verbatim).
+# ---------------------------------------------------------------------------
+
+def _blank_preserve_newlines(s: str) -> str:
+    return re.sub(r"[^\n]", " ", s)
+
+
+def normalize(src: str) -> str:
+    out: list[str] = []
+    i, n = 0, len(src)
+    while i < n:
+        c = src[i]
+        c1 = src[i + 1] if i + 1 < n else ""
+        if c == "/" and c1 == "/":
+            j = src.find("\n", i)
+            j = n if j < 0 else j
+            out.append(" " * (j - i))
+            i = j
+        elif c == "/" and c1 == "*":
+            j = src.find("*/", i + 2)
+            j = n if j < 0 else j + 2
+            out.append(_blank_preserve_newlines(src[i:j]))
+            i = j
+        elif c == "@" and c1 == '"':
+            j = i + 2
+            while j < n:
+                if src[j] == '"':
+                    if j + 1 < n and src[j + 1] == '"':
+                        j += 2
+                        continue
+                    j += 1
+                    break
+                j += 1
+            inner = src[i + 1 : j - 1] if j > i + 1 else ""
+            out.append('"' + _blank_preserve_newlines(inner) + '"')
+            i = j
+        elif c == '"':
+            j = i + 1
+            while j < n:
+                if src[j] == "\\" and j + 1 < n:
+                    j += 2
+                    continue
+                if src[j] == '"':
+                    j += 1
+                    break
+                if src[j] == "\n":
+                    break
+                j += 1
+            chunk = src[i:j]
+            if len(chunk) >= 2 and chunk.endswith('"'):
+                out.append('"' + " " * (len(chunk) - 2) + '"')
+            else:
+                out.append(" " * len(chunk))
+            i = j
+        elif c == "'":
+            j = i + 1
+            depth = 0
+            while j < n and depth < 6:
+                if src[j] == "\\" and j + 1 < n:
+                    j += 2
+                    depth += 1
+                    continue
+                if src[j] == "'":
+                    j += 1
+                    break
+                j += 1
+                depth += 1
+            chunk = src[i:j]
+            if len(chunk) >= 2 and chunk.endswith("'"):
+                out.append("'" + " " * (len(chunk) - 2) + "'")
+            else:
+                out.append(chunk)
+            i = j
+        else:
+            out.append(c)
+            i += 1
+    return "".join(out)
+
+
+# ---------------------------------------------------------------------------
+# Regex patterns applied to the normalized source line-by-line.
+# ---------------------------------------------------------------------------
+
+NAMESPACE_RE = re.compile(r"^\s*namespace\s+(?P<name>[\w.]+)\s*[{;]?\s*$")
+
+TYPE_DECL_RE = re.compile(
+    r"^\s*(?P<mods>(?:(?:public|internal|private|protected|sealed|static|abstract|partial|new|unsafe)\s+)*)"
+    r"(?P<kind>class|struct|interface|enum)\s+"
+    r"(?P<name>[A-Za-z_]\w*)"
+    r"(?P<generic><[^>]*>)?"
+    r"\s*(?::\s*(?P<base>[^{]+?))?"
+    r"\s*(?:where\s+[^{]+)?"
+    r"\s*\{?\s*$"
+)
+
+METHOD_RE = re.compile(
+    r"^\s*(?P<mods>(?:(?:public|internal|private|protected|static|virtual|override|sealed|abstract|async|extern|new|partial|unsafe)\s+)+)"
+    r"(?P<ret>(?:[\w\.\?\[\]]|<[^>]*>)+(?:\s*[\?\[\]])*)\s+"
+    r"(?P<name>[A-Za-z_]\w*)\s*"
+    r"(?P<generic><[^>]*>)?\s*"
+    r"\((?P<params>[^)]*)\)\s*"
+    r"(?:where\s+[^{;=]+)?"
+    r"\s*(?:[{;=]|=>)?\s*$"
+)
+
+PROPERTY_RE = re.compile(
+    r"^\s*(?P<mods>(?:(?:public|internal|private|protected|static|virtual|override|sealed|abstract|new|readonly)\s+)+)"
+    r"(?P<type>(?:[\w\.\?\[\]]|<[^>]*>)+)\s+"
+    r"(?P<name>[A-Za-z_]\w*)\s*"
+    r"(?:\{[^}]*\}|=>\s*[^;]+;)"
+)
+
+FIELD_RE = re.compile(
+    r"^\s*(?P<mods>(?:(?:public|internal|private|protected|static|readonly|const|new|volatile|unsafe)\s+)+)"
+    r"(?P<type>(?:[\w\.\?\[\]]|<[^>]*>)+)\s+"
+    r"(?P<name>[A-Za-z_]\w*)\s*"
+    r"(?:=\s*[^;]+)?;"
+)
+
+ATTR_LINE_RE = re.compile(r"^\s*\[(?P<body>.+)\]\s*$")
+SUMMARY_LINE_RE = re.compile(r"^\s*///\s?(?P<text>.*)$")
+
+
+# ---------------------------------------------------------------------------
+# C# file parser
+# ---------------------------------------------------------------------------
+
+def parse_cs_file(path: Path, rel_path: str) -> dict:
+    """Return {'types': [...], 'namespaces': set([...])} for one .cs file."""
+    raw = path.read_text(encoding="utf-8", errors="replace")
+    norm = normalize(raw)
+    norm_lines = norm.split("\n")
+    raw_lines = raw.split("\n")
+
+    types: list[dict] = []
+    namespaces: set[str] = set()
+
+    scope_stack: list[dict] = []  # entries: {"kind": "namespace"|"type", "name": str, "open_depth": int, "type_idx": int|None}
+    brace_depth = 0
+    pending_attrs: list[str] = []
+    pending_summary: list[str] = []
+
+    def current_namespace() -> str:
+        for s in reversed(scope_stack):
+            if s["kind"] == "namespace":
+                return s["name"]
+        return ""
+
+    def current_type_idx() -> int | None:
+        for s in reversed(scope_stack):
+            if s["kind"] == "type":
+                return s["type_idx"]
+        return None
+
+    def drain_attrs_and_summary():
+        attrs = list(pending_attrs)
+        summary = "\n".join(pending_summary).strip()
+        pending_attrs.clear()
+        pending_summary.clear()
+        return attrs, summary
+
+    for idx, line in enumerate(norm_lines):
+        raw_line = raw_lines[idx] if idx < len(raw_lines) else ""
+        stripped = line.strip()
+
+        # Capture XML summary from RAW line (the normalizer keeps the `///` prefix).
+        m = SUMMARY_LINE_RE.match(raw_line)
+        if m:
+            text = m.group("text")
+            # Drop the <summary>/</summary> envelope; keep inner text.
+            text = re.sub(r"</?summary>", "", text).strip()
+            if text:
+                pending_summary.append(text)
+            continue
+
+        # Capture attribute lines (allow multiple attrs separated by commas).
+        # Read the body from the RAW line so string literal contents are preserved.
+        m = ATTR_LINE_RE.match(raw_line)
+        if m:
+            body = m.group("body").strip()
+            pending_attrs.append(body)
+            # Attribute lines don't open/close braces; safe to continue.
+            continue
+
+        if not stripped:
+            # blank line breaks attribute/summary accumulation? keep summary, drop attrs only on declaration.
+            # Reset summary on blank lines to avoid stealing distant comments.
+            pending_summary.clear()
+            pending_attrs.clear()
+            continue
+
+        # Namespace declaration
+        m = NAMESPACE_RE.match(line)
+        if m:
+            name = m.group("name")
+            namespaces.add(name)
+            # If the line had a `{`, that opens a scope.
+            if "{" in line:
+                scope_stack.append({"kind": "namespace", "name": name, "open_depth": brace_depth + 1, "type_idx": None})
+                brace_depth += line.count("{") - line.count("}")
+            elif ";" in line:
+                # file-scoped namespace: applies until EOF; no brace opened.
+                scope_stack.append({"kind": "namespace", "name": name, "open_depth": 0, "type_idx": None})
+            else:
+                # brace likely on next line; record pending namespace.
+                scope_stack.append({"kind": "namespace", "name": name, "open_depth": brace_depth + 1, "type_idx": None})
+            # don't drain attrs/summary for namespace
+            continue
+
+        # Type declaration (top-level OR nested directly inside another type body)
+        m = TYPE_DECL_RE.match(line)
+        nested_ok = current_type_idx() is None or _is_direct_type_body(scope_stack, brace_depth)
+        if m and nested_ok and not (
+            re.search(r"\b(new|return|throw)\b", line[: m.start("kind")])
+        ):
+            attrs, summary = drain_attrs_and_summary()
+            mods = [w for w in m.group("mods").split() if w] if m.group("mods") else []
+            base = m.group("base").strip() if m.group("base") else None
+            base_list = [b.strip() for b in base.split(",")] if base else []
+            tinfo = {
+                "file": rel_path,
+                "line": idx + 1,
+                "namespace": current_namespace(),
+                "name": m.group("name"),
+                "kind": m.group("kind"),
+                "modifiers": mods,
+                "baseList": base_list,
+                "attributes": attrs,
+                "summary": summary,
+                "containingType": _innermost_type_name(scope_stack),
+                "members": [],
+            }
+            types.append(tinfo)
+            type_idx = len(types) - 1
+            # If brace opens on this line, push scope. Else expect next line.
+            has_open = "{" in line
+            if has_open:
+                scope_stack.append({"kind": "type", "name": tinfo["name"], "open_depth": brace_depth + 1, "type_idx": type_idx})
+            else:
+                scope_stack.append({"kind": "type", "name": tinfo["name"], "open_depth": brace_depth + 1, "type_idx": type_idx})
+            brace_depth += line.count("{") - line.count("}")
+            # Pop scopes whose open_depth now exceeds brace_depth (closed in same line)
+            while scope_stack and brace_depth < scope_stack[-1]["open_depth"] - 1:
+                scope_stack.pop()
+            continue
+
+        # Member declarations only if we are directly inside a type scope (not nested in a method).
+        ct_idx = current_type_idx()
+        if ct_idx is not None and _is_direct_type_body(scope_stack, brace_depth):
+            member = _try_member(line, idx + 1)
+            if member is not None:
+                attrs, summary = drain_attrs_and_summary()
+                member["attributes"] = attrs
+                member["summary"] = summary
+                types[ct_idx]["members"].append(member)
+
+        # Track brace depth changes for this line.
+        opens = line.count("{")
+        closes = line.count("}")
+        brace_depth += opens - closes
+
+        # Pop scopes whose brace went below their open depth.
+        while scope_stack and brace_depth < scope_stack[-1]["open_depth"]:
+            scope_stack.pop()
+        # Clear attrs that didn't attach to anything (this line ended a statement).
+        if opens or closes or stripped.endswith(";"):
+            pending_attrs.clear()
+            pending_summary.clear()
+
+    return {"types": types, "namespaces": sorted(namespaces)}
+
+
+def _innermost_type_name(scope_stack: list[dict]) -> str | None:
+    for s in reversed(scope_stack):
+        if s["kind"] == "type":
+            return s["name"]
+    return None
+
+
+def _is_direct_type_body(scope_stack: list[dict], brace_depth: int) -> bool:
+    """True iff brace_depth equals the open depth of the innermost type (i.e. we're directly in the type body, not nested deeper)."""
+    for s in reversed(scope_stack):
+        if s["kind"] == "type":
+            return brace_depth == s["open_depth"]
+    return False
+
+
+def _try_member(line: str, line_no: int) -> dict | None:
+    """Detect a method/property/field declaration on this normalized line."""
+    m = METHOD_RE.match(line)
+    if m and m.group("ret").strip() not in ("class", "struct", "interface", "enum"):
+        return {
+            "line": line_no,
+            "kind": "method",
+            "name": m.group("name"),
+            "signature": _collapse_ws(line.split("{")[0].split(";")[0].split("=>")[0]).rstrip(),
+        }
+    m = PROPERTY_RE.match(line)
+    if m:
+        return {
+            "line": line_no,
+            "kind": "property",
+            "name": m.group("name"),
+            "signature": _collapse_ws(line.split("{")[0].split("=>")[0]).rstrip(),
+        }
+    m = FIELD_RE.match(line)
+    if m:
+        return {
+            "line": line_no,
+            "kind": "field",
+            "name": m.group("name"),
+            "signature": _collapse_ws(line.split("=")[0].split(";")[0]).rstrip(),
+        }
+    return None
+
+
+def _collapse_ws(s: str) -> str:
+    return re.sub(r"\s+", " ", s).strip()
+
+
+# ---------------------------------------------------------------------------
+# Asmdef + meta scanning
+# ---------------------------------------------------------------------------
+
+def scan_asmdefs(package_dir: Path, repo_root: Path) -> list[dict]:
+    results: list[dict] = []
+    for p in package_dir.rglob("*.asmdef"):
+        try:
+            data = json.loads(p.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            continue
+        results.append(
+            {
+                "path": _rel(p, repo_root),
+                "name": data.get("name"),
+                "rootNamespace": data.get("rootNamespace", ""),
+                "includePlatforms": data.get("includePlatforms", []),
+                "excludePlatforms": data.get("excludePlatforms", []),
+                "references": data.get("references", []),
+                "precompiledReferences": data.get("precompiledReferences", []),
+                "defineConstraints": data.get("defineConstraints", []),
+                "autoReferenced": data.get("autoReferenced", True),
+            }
+        )
+    return results
+
+
+META_GUID_RE = re.compile(r"^guid:\s*([a-fA-F0-9]+)", re.MULTILINE)
+
+
+def build_script_guid_map(repo_root: Path) -> dict[str, str]:
+    """Walk every *.cs.meta under Assets/ and return {guid: relative_cs_path}."""
+    mapping: dict[str, str] = {}
+    assets = repo_root / "Assets"
+    if not assets.is_dir():
+        return mapping
+    for meta in assets.rglob("*.cs.meta"):
+        try:
+            text = meta.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        m = META_GUID_RE.search(text)
+        if not m:
+            continue
+        cs_path = meta.with_suffix("")  # drop the .meta
+        if cs_path.exists():
+            mapping[m.group(1)] = _rel(cs_path, repo_root)
+    return mapping
+
+
+SCRIPT_REF_RE = re.compile(r"m_Script:\s*\{[^}]*guid:\s*([a-fA-F0-9]+)")
+
+
+def scan_sample_dir(sample_dir: Path, repo_root: Path, package_types: set[str], guid_map: dict[str, str], package_files: set[str]) -> list[dict]:
+    results: list[dict] = []
+    if not sample_dir.is_dir():
+        return results
+    for p in sorted(sample_dir.rglob("*")):
+        if not p.is_file():
+            continue
+        rel = _rel(p, repo_root)
+        suf = p.suffix.lower()
+        if suf == ".cs":
+            try:
+                src = p.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                continue
+            norm = normalize(src)
+            ns_match = NAMESPACE_RE.search(norm)
+            ns = ns_match.group("name") if ns_match else ""
+            words = set(re.findall(r"\b([A-Z][A-Za-z0-9_]*)\b", norm))
+            refs = sorted(words & package_types)
+            results.append({"path": rel, "kind": "script", "namespace": ns, "packageTypesReferenced": refs})
+        elif suf in (".unity", ".prefab"):
+            try:
+                text = p.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                continue
+            guids = sorted(set(SCRIPT_REF_RE.findall(text)))
+            refs = []
+            for g in guids:
+                resolved = guid_map.get(g)
+                if resolved and resolved in package_files:
+                    refs.append({"guid": g, "resolvedTo": resolved})
+            results.append({"path": rel, "kind": "scene" if suf == ".unity" else "prefab", "scriptsReferenced": refs})
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Utilities
+# ---------------------------------------------------------------------------
+
+def _rel(p: Path, root: Path) -> str:
+    try:
+        return str(p.resolve().relative_to(root.resolve())).replace(os.sep, "/")
+    except ValueError:
+        return str(p)
+
+
+def iter_cs_files(root: Path) -> Iterable[Path]:
+    for p in sorted(root.rglob("*.cs")):
+        if p.is_file():
+            yield p
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main(argv: list[str]) -> int:
+    ap = argparse.ArgumentParser(description="Scan a Unity package and emit a JSON manifest.")
+    ap.add_argument("--package", required=True, help="Path to the package source directory.")
+    ap.add_argument("--samples", action="append", default=[], help="Path to a sample directory (repeatable).")
+    ap.add_argument("--repo-root", default=os.getcwd(), help="Repository root (paths in output are relative to this).")
+    args = ap.parse_args(argv)
+
+    repo_root = Path(args.repo_root).resolve()
+    package_dir = Path(args.package).resolve()
+    if not package_dir.is_dir():
+        print(f"error: package dir not found: {package_dir}", file=sys.stderr)
+        return 2
+
+    all_types: list[dict] = []
+    all_namespaces: set[str] = set()
+    package_files: set[str] = set()
+
+    for cs in iter_cs_files(package_dir):
+        rel = _rel(cs, repo_root)
+        package_files.add(rel)
+        result = parse_cs_file(cs, rel)
+        all_types.extend(result["types"])
+        all_namespaces.update(result["namespaces"])
+
+    asmdefs = scan_asmdefs(package_dir, repo_root)
+    guid_map = build_script_guid_map(repo_root)
+
+    package_type_names: set[str] = {t["name"] for t in all_types}
+
+    samples: list[dict] = []
+    for s in args.samples:
+        samples.extend(scan_sample_dir(Path(s).resolve(), repo_root, package_type_names, guid_map, package_files))
+
+    manifest = {
+        "packageDir": _rel(package_dir, repo_root),
+        "asmdefs": asmdefs,
+        "namespaces": sorted(all_namespaces),
+        "types": all_types,
+        "scriptGuidCount": len(guid_map),
+        "samples": samples,
+    }
+    json.dump(manifest, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "com.elestrago.unity.package-tools",
-  "version": "2.0.11",
+  "version": "2.1.0",
   "displayName": "Package Tool",
   "description": "Tool for create unity packages",
   "category": "unity",
   "unity": "2021.3",
   "homepage": "https://gitlab.com/elestrago-pkg/package-tool",
-  "documentationUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.0.11/README.md",
-  "changelogUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.0.11/CHANGELOG.md",
-  "licensesUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.0.11/LICENSE",
+  "documentationUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.1.0/README.md",
+  "changelogUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.1.0/CHANGELOG.md",
+  "licensesUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.1.0/LICENSE",
   "license": "MIT",
   "keywords": [
     "unity",
@@ -24,6 +24,11 @@
       "displayName": "Example Sample",
       "description": "This is example for check test samples",
       "path": "Samples~/ExampleSample"
+    },
+    {
+      "displayName": "Claude Skills",
+      "description": "This file contain claude skill for create package documentation",
+      "path": "Samples~/ClaudeSkills"
     }
   ],
   "author": {