com.wallstop-studios.unity-helpers 2.0.0-rc81.9 → 2.0.0

package/.editorconfig

@@ -1,6 +1,6 @@
 
 [*]
-charset = utf-8-bom
+charset = utf-8
 end_of_line = crlf
 trim_trailing_whitespace = false
 insert_final_newline = false

package/.gitattributes

@@ -2,7 +2,7 @@
 # Line endings
 #
 # Enforce CRLF in the working tree for all text files to align with
-# .editorconfig (end_of_line = crlf, charset = utf-8-bom) and avoid
+# .editorconfig (end_of_line = crlf, charset = utf-8 without BOM) and avoid
 # formatter diffs on Linux runners.
 ###############################################################################
 * text=auto eol=crlf

package/.githooks/pre-commit

@@ -1,7 +1,12 @@
 #!/usr/bin/env sh
 set -e
 
-# 1) Lint Markdown links via PowerShell script (existing behavior)
+# 0) Ensure .NET tools available (for CSharpier)
+if command -v dotnet >/dev/null 2>&1; then
+  dotnet tool restore >/dev/null 2>&1 || true
+fi
+
+# 1) Lint Markdown link text style (PowerShell script)
 run_pwsh() {
   pwsh -NoProfile -File scripts/lint-doc-links.ps1
 }
@@ -19,7 +24,7 @@ else
   exit 1
 fi
 
-# 2) Format staged Markdown/JSON (incl. asmdef/asmref) with Prettier and re-stage
+# 2) Format staged Markdown/JSON/YAML with Prettier and re-stage
 if ! command -v npx >/dev/null 2>&1; then
   echo "npx is required for formatting. Please install Node.js." >&2
   exit 1
@@ -28,8 +33,9 @@ fi
 STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
 
 # Collect file lists
-MD_FILES=$(echo "$STAGED_FILES" | grep -E '\.(md|markdown)$' || true)
-JSON_FILES=$(echo "$STAGED_FILES" | grep -E '\.(json|asmdef|asmref)$' || true)
+MD_FILES=$(echo "$STAGED_FILES" | grep -E '\\.(md|markdown)$' || true)
+JSON_FILES=$(echo "$STAGED_FILES" | grep -E '\\.(json|asmdef|asmref)$' || true)
+YAML_FILES=$(echo "$STAGED_FILES" | grep -E '\\.(yml|yaml)$' || true)
 
 # Prettier format and re-add
 if [ -n "$MD_FILES" ]; then
@@ -42,8 +48,28 @@ if [ -n "$JSON_FILES" ]; then
   echo "$JSON_FILES" | xargs git add
 fi
 
-# 3) Markdown lint for staged Markdown files
+if [ -n "$YAML_FILES" ]; then
+  echo "$YAML_FILES" | xargs npx --no-install prettier --write --log-level warn
+  echo "$YAML_FILES" | xargs git add
+fi
+
+# 3) Format staged C# files with CSharpier (if available) and re-stage
+CS_FILES=$(echo "$STAGED_FILES" | grep -E '\\.cs$' || true)
+if [ -n "$CS_FILES" ] && command -v dotnet >/dev/null 2>&1; then
+  # Use local tool version to format paths; fall back to repo-wide if necessary
+  dotnet tool run csharpier $CS_FILES >/dev/null 2>&1 || dotnet tool run csharpier . >/dev/null 2>&1 || true
+  echo "$CS_FILES" | xargs git add
+fi
+
+# 4) Markdown lint for staged Markdown files
 if [ -n "$MD_FILES" ]; then
   npx --no-install markdownlint $MD_FILES --config .markdownlint.json --ignore-path .markdownlintignore
 fi
 
+# 5) Optional YAML lint on staged YAML (if yamllint present)
+if [ -n "$YAML_FILES" ]; then
+  if command -v yamllint >/dev/null 2>&1; then
+    echo "$YAML_FILES" | xargs yamllint -c .yamllint.yaml
+  fi
+fi
+

package/.githooks/pre-push

@@ -0,0 +1,50 @@
+#!/usr/bin/env sh
+set -e
+
+# Mirror key CI checks before pushing
+
+# Ensure Node is available
+if ! command -v npx >/dev/null 2>&1; then
+  echo "npx is required. Please install Node.js." >&2
+  exit 1
+fi
+
+# 1) Prettier checks (Markdown, JSON, asmdef/asmref, YAML)
+npx --no-install prettier --check "**/*.{md,markdown}" || exit 1
+npx --no-install prettier --check "**/*.{json,asmdef,asmref}" || exit 1
+npx --no-install prettier --check "**/*.{yml,yaml}" || exit 1
+
+# 2) Markdownlint (uses repo config and ignore list)
+npx --no-install markdownlint "**/*.md" "**/*.markdown" --config .markdownlint.json --ignore-path .markdownlintignore || exit 1
+
+# 3) EOL policy (CRLF, no UTF-8 BOM)
+if command -v pwsh >/dev/null 2>&1; then
+  pwsh -NoProfile -File scripts/check-eol.ps1 -VerboseOutput
+elif command -v powershell >/dev/null 2>&1; then
+  powershell -NoProfile -ExecutionPolicy Bypass -File scripts/check-eol.ps1 -VerboseOutput
+else
+  echo "PowerShell not found; skipping EOL validation." >&2
+fi
+
+# 4) Optional YAML lint (if yamllint installed)
+if command -v yamllint >/dev/null 2>&1; then
+  yamllint -c .yamllint.yaml .
+else
+  echo "yamllint not found; skipping YAML lint. CI will catch issues." >&2
+fi
+
+# 5) Optional external link check (if lychee installed)
+if command -v lychee >/dev/null 2>&1; then
+  lychee -c .lychee.toml --no-progress --verbose "./**/*.md"
+else
+  echo "lychee not found; skipping external link check. CI will run lychee." >&2
+fi
+
+# 6) Test lifecycle lint
+if command -v pwsh >/dev/null 2>&1; then
+  pwsh -NoProfile -File scripts/lint-tests.ps1 -VerboseOutput
+elif command -v powershell >/dev/null 2>&1; then
+  powershell -NoProfile -ExecutionPolicy Bypass -File scripts/lint-tests.ps1 -VerboseOutput
+else
+  echo  'PowerShell not found; skipping test lints.' >&2 
+fi

package/.github/dependabot.yml

@@ -1,10 +1,32 @@
 version: 2
 updates:
+  # GitHub Actions workflow updates
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
-      interval: "weekly"
+      interval: "daily"
     assignees:
       - wallstop
     reviewers:
-      - wallstop
+      - wallstop
+
+  # NuGet: .csproj/props/targets and .config/dotnet-tools.json (local tools)
+  - package-ecosystem: "nuget"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    assignees:
+      - wallstop
+    reviewers:
+      - wallstop
+
+  # npm/UPM: package.json at repo root (Unity package manifest)
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    versioning-strategy: increase
+    assignees:
+      - wallstop
+    reviewers:
+      - wallstop

package/.github/scripts/check-markdown-links.ps1

@@ -0,0 +1,77 @@
+Param(
+    [string]$Root = "."
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Normalize-Name {
+    param([string]$s)
+    if ([string]::IsNullOrWhiteSpace($s)) { return "" }
+    # Remove extension (like .md), collapse non-alphanumerics, lowercase
+    $noExt = $s -replace '\.[^\.]+$',''
+    $normalized = ($noExt -replace '[^A-Za-z0-9]', '')
+    return $normalized.ToLowerInvariant()
+}
+
+$issueCount = 0
+
+# Exclude typical directories that shouldn't be scanned
+$excludeDirs = @('.git', 'node_modules', '.vs')
+
+$mdFiles = Get-ChildItem -Path $Root -Recurse -File -Filter *.md |
+    Where-Object { $excludeDirs -notcontains $_.Directory.Name }
+
+# Regex for inline markdown links (exclude images), capture optional title
+$pattern = '(?<!\!)\[(?<text>[^\]]+)\]\((?<target>[^)\s]+)(?:\s+"[^"]*")?\)'
+
+foreach ($file in $mdFiles) {
+    $lines = Get-Content -LiteralPath $file.FullName -Encoding UTF8
+    for ($i = 0; $i -lt $lines.Count; $i++) {
+        $line = $lines[$i]
+        $matches = [System.Text.RegularExpressions.Regex]::Matches($line, $pattern)
+        foreach ($m in $matches) {
+            $text = $m.Groups['text'].Value.Trim()
+            $targetRaw = $m.Groups['target'].Value.Trim()
+
+            # Skip anchors, external links, and mailto
+            if ($targetRaw -match '^(#|https?://|mailto:|tel:|data:)') { continue }
+
+            # Remove query/anchor for file checks
+            $targetCore = $targetRaw -replace '[?#].*$',''
+
+            # Decode URL-encoded chars
+            try { $targetCore = [uri]::UnescapeDataString($targetCore) } catch { }
+
+            # Only care about links to markdown files
+            if (-not ($targetCore -match '\.md$')) { continue }
+
+            $fileName = [System.IO.Path]::GetFileName($targetCore)
+            $baseName = [System.IO.Path]::GetFileNameWithoutExtension($targetCore)
+
+            # Fail when the visible link text is the raw file name
+            $isExactFileName = $text.Equals($fileName, [System.StringComparison]::OrdinalIgnoreCase)
+
+            # Also fail when the visible text looks like a path or ends with .md
+            # contains path separators and no whitespace (heuristic for raw paths)
+            $looksLikePath = ($text -match '[\\/]' -and -not ($text -match '\\s'))
+            $looksLikeMarkdownFileName = $text.Trim().ToLowerInvariant().EndsWith('.md')
+
+            if ($isExactFileName -or $looksLikePath -or $looksLikeMarkdownFileName) {
+                $issueCount++
+                $lineNo = $i + 1
+                $msg = "Link text '$text' should be human-readable, not a raw file name or path"
+                # GitHub Actions annotation
+                Write-Output "::error file=$($file.FullName),line=$lineNo::$msg (target: $targetRaw)"
+            }
+        }
+    }
+}
+
+if ($issueCount -gt 0) {
+    Write-Host "Found $issueCount documentation link(s) with non-human-readable text." -ForegroundColor Red
+    Write-Host "Use a descriptive phrase instead of the raw file name."
+    exit 1
+}
+else {
+    Write-Host "All markdown links have human-readable text."
+}

package/.github/scripts/check_markdown_links.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+import os
+import re
+import sys
+import urllib.parse
+
+
+EXCLUDE_DIRS = {".git", "node_modules", ".vs"}
+
+
+def normalize_name(s: str) -> str:
+    if not s:
+        return ""
+    # remove extension, strip non-alphanumerics, lowercase
+    base = re.sub(r"\.[^.]+$", "", s)
+    return re.sub(r"[^A-Za-z0-9]", "", base).lower()
+
+
+LINK_RE = re.compile(r"(?<!\!)\[(?P<text>[^\]]+)\]\((?P<target>[^)\s]+)(?:\s+\"[^\"]*\")?\)")
+
+
+def should_check_target(target: str) -> bool:
+    if re.match(r"^(#|https?://|mailto:|tel:|data:)", target):
+        return False
+    # only check links that end in .md (ignoring anchors/query)
+    core = re.sub(r"[?#].*$", "", target)
+    try:
+        core = urllib.parse.unquote(core)
+    except Exception:
+        pass
+    return core.lower().endswith(".md")
+
+
+def main(root: str) -> int:
+    issues = 0
+    for dirpath, dirnames, filenames in os.walk(root):
+        # prune excluded directories
+        dirnames[:] = [d for d in dirnames if d not in EXCLUDE_DIRS]
+        for filename in filenames:
+            if not filename.lower().endswith(".md"):
+                continue
+            path = os.path.join(dirpath, filename)
+            try:
+                with open(path, "r", encoding="utf-8") as f:
+                    lines = f.readlines()
+            except Exception:
+                continue
+            for idx, line in enumerate(lines, start=1):
+                for m in LINK_RE.finditer(line):
+                    text = m.group("text").strip()
+                    target_raw = m.group("target").strip()
+                    if not should_check_target(target_raw):
+                        continue
+                    target_core = re.sub(r"[?#].*$", "", target_raw)
+                    try:
+                        target_core = urllib.parse.unquote(target_core)
+                    except Exception:
+                        pass
+                    file_name = os.path.basename(target_core)
+                    base_name, _ = os.path.splitext(file_name)
+
+                    is_exact_file_name = text.lower() == file_name.lower()
+                    looks_like_path = (("/" in text) or ("\\" in text)) and not re.search(r"\s", text)
+                    looks_like_markdown = text.strip().lower().endswith(".md")
+
+                    if (
+                        is_exact_file_name
+                        or looks_like_path
+                        or looks_like_markdown
+                    ):
+                        issues += 1
+                        msg = f"{path}:{idx}: Link text '{text}' should be human-readable, not a raw file name or path (target: {target_raw})"
+                        print(msg)
+
+    if issues:
+        print(
+            f"Found {issues} documentation link(s) with non-human-readable text.",
+            file=sys.stderr,
+        )
+        print(
+            "Use a descriptive phrase instead of the raw file name.", file=sys.stderr
+        )
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    root = sys.argv[1] if len(sys.argv) > 1 else "."
+    sys.exit(main(root))

package/.github/scripts/check_markdown_url_encoding.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+import os
+import re
+import sys
+
+
+EXCLUDE_DIRS = {".git", "node_modules", ".vs", ".vscode", "Library", "Temp"}
+
+
+# Inline markdown link or image: ![alt](target "title") or [text](target "title")
+INLINE_LINK_RE = re.compile(
+    r"!?(?P<all>\[(?P<text>[^\]]+)\]\((?P<target>[^)\s]+)(?:\s+\"[^\"]*\")?\))"
+)
+
+# Reference-style link definitions: [id]: target "title"
+REF_DEF_RE = re.compile(r"^\s*\[[^\]]+\]:\s*(?P<target>\S+)(?:\s+\"[^\"]*\")?\s*$")
+
+
+def is_external(target: str) -> bool:
+    return target.startswith("http://") or target.startswith("https://") or target.startswith("mailto:") or target.startswith("tel:") or target.startswith("data:")
+
+
+def has_unencoded_chars(target: str) -> bool:
+    # Only flag raw spaces or plus signs in the path/query/fragment
+    return (" " in target) or ("+" in target)
+
+
+def scan_file(path: str) -> int:
+    issues = 0
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            lines = f.readlines()
+    except Exception:
+        return 0
+
+    for idx, line in enumerate(lines, start=1):
+        # Inline links/images
+        for m in INLINE_LINK_RE.finditer(line):
+            target = m.group("target").strip()
+            if is_external(target):
+                continue
+            if has_unencoded_chars(target):
+                issues += 1
+                print(f"{path}:{idx}: Unencoded character(s) in link target: '{target}'. Encode spaces as %20 and '+' as %2B.")
+
+        # Reference-style link definitions
+        m = REF_DEF_RE.match(line)
+        if m:
+            target = m.group("target").strip()
+            if not is_external(target) and has_unencoded_chars(target):
+                issues += 1
+                print(f"{path}:{idx}: Unencoded character(s) in link definition: '{target}'. Encode spaces as %20 and '+' as %2B.")
+
+    return issues
+
+
+def main(root: str) -> int:
+    issues = 0
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in EXCLUDE_DIRS]
+        for filename in filenames:
+            if filename.lower().endswith(".md"):
+                issues += scan_file(os.path.join(dirpath, filename))
+    if issues:
+        print(f"Found {issues} markdown link(s) with unencoded spaces or plus signs.", file=sys.stderr)
+        print("Please URL-encode spaces as %20 and '+' as %2B in relative links.", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    root = sys.argv[1] if len(sys.argv) > 1 else "."
+    sys.exit(main(root))
+

package/.github/scripts/validate_markdown_links.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+import os
+import re
+import sys
+import urllib.parse
+from typing import Dict, List, Set, Tuple
+
+
+EXCLUDE_DIRS = {".git", "node_modules", ".vs"}
+
+
+LINK_RE = re.compile(r"(?<!\!)\[(?P<text>[^\]]+)\]\((?P<target>[^)\s]+)(?:\s+\"[^\"]*\")?\)")
+
+
+def unescape_uri(s: str) -> str:
+    try:
+        return urllib.parse.unquote(s)
+    except Exception:
+        return s
+
+
+def normalize_heading_to_id(text: str) -> str:
+    """
+    Approximate GitHub-style anchor slug generation (GFM):
+    - Lowercase
+    - Strip Markdown formatting and code ticks
+    - Remove most punctuation
+    - Replace whitespace with hyphens
+    - Collapse multiple hyphens
+    - Trim leading/trailing hyphens
+    """
+    if not text:
+        return ""
+    t = text
+    # Remove inline code ticks
+    t = t.replace("`", "")
+    # Remove Markdown emphasis markers
+    t = t.replace("*", "").replace("_", "").replace("~", "")
+    # Remove link/image markup inside headings e.g. [text](url)
+    t = re.sub(r"!?\[[^\]]*\]\([^)]*\)", "", t)
+    # Remove HTML tags
+    t = re.sub(r"<[^>]+>", "", t)
+    # Lowercase
+    t = t.lower()
+    # Replace whitespace with hyphens
+    t = re.sub(r"\s+", "-", t)
+    # Remove punctuation except hyphens and alphanumerics
+    t = re.sub(r"[^a-z0-9-]", "", t)
+    # Collapse multiple hyphens
+    t = re.sub(r"-+", "-", t)
+    # Trim hyphens
+    t = t.strip("-")
+    return t
+
+
+def collect_heading_ids(file_path: str) -> Set[str]:
+    """
+    Build the set of anchor IDs generated by headings within a markdown file.
+    Handles ATX (# ...) and Setext (underlined) headings. Accounts for duplicate
+    slugs by adding -1, -2, ... suffixes (GitHub behavior).
+    """
+    try:
+        with open(file_path, "r", encoding="utf-8") as f:
+            lines = f.readlines()
+    except Exception:
+        return set()
+
+    ids: Set[str] = set()
+    slug_counts: Dict[str, int] = {}
+
+    def add_slug_from_text(text: str):
+        slug = normalize_heading_to_id(text)
+        if slug == "":
+            return
+        count = slug_counts.get(slug, 0)
+        if count == 0:
+            final = slug
+        else:
+            final = f"{slug}-{count}"
+        slug_counts[slug] = count + 1
+        ids.add(final)
+
+    # ATX headings
+    atx_re = re.compile(r"^\s{0,3}#{1,6}\s+(.*)$")
+
+    # Walk lines, handle setext headings by looking ahead
+    i = 0
+    while i < len(lines):
+        line = lines[i].rstrip("\n")
+        m = atx_re.match(line)
+        if m:
+            add_slug_from_text(m.group(1).strip())
+            i += 1
+            continue
+        # Setext H1/H2
+        if i + 1 < len(lines):
+            underline = lines[i + 1].rstrip("\n")
+            if re.match(r"^\s{0,3}=+\s*$", underline) or re.match(r"^\s{0,3}-+\s*$", underline):
+                add_slug_from_text(line.strip())
+                i += 2
+                continue
+        i += 1
+
+    return ids
+
+
+def is_external(target: str) -> bool:
+    return bool(re.match(r"^(https?://|mailto:|tel:|data:)", target))
+
+
+def resolve_path(base_dir: str, target_path: str) -> str:
+    return os.path.normpath(os.path.join(base_dir, target_path))
+
+
+def check_internal_link(src_file: str, target_raw: str) -> Tuple[bool, str]:
+    # Separate fragment
+    if target_raw.startswith("#"):
+        # Anchor within same file
+        frag = target_raw[1:]
+        anchor = unescape_uri(frag)
+        anchor = anchor.strip()
+        anchor = anchor.lower()
+        ids = collect_heading_ids(src_file)
+        if anchor in ids:
+            return True, ""
+        return False, f"dangling anchor '#{frag}' (no matching heading)"
+
+    # Split off query/fragment
+    core = re.sub(r"[?#].*$", "", target_raw)
+    core = unescape_uri(core)
+    base_dir = os.path.dirname(src_file)
+    target_fs = resolve_path(base_dir, core)
+    if not os.path.exists(target_fs):
+        return False, f"target file not found: {core}"
+
+    # Fragment check if present
+    m = re.search(r"#(.+)$", target_raw)
+    if m:
+        frag = m.group(1)
+        anchor = unescape_uri(frag).strip().lower()
+        ids = collect_heading_ids(target_fs)
+        if anchor not in ids:
+            return False, f"dangling anchor '#{frag}' in {core}"
+
+    return True, ""
+
+
+def main(paths: List[str]) -> int:
+    issues = 0
+
+    def iter_markdown_files() -> List[str]:
+        files: List[str] = []
+        for p in paths:
+            if os.path.isdir(p):
+                for dirpath, dirnames, filenames in os.walk(p):
+                    dirnames[:] = [d for d in dirnames if d not in EXCLUDE_DIRS]
+                    for filename in filenames:
+                        if filename.lower().endswith(".md"):
+                            files.append(os.path.join(dirpath, filename))
+            else:
+                if p.lower().endswith(".md") and os.path.exists(p):
+                    files.append(p)
+        return files
+
+    files = iter_markdown_files()
+    for path in files:
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                lines = f.readlines()
+        except Exception:
+            continue
+        for idx, line in enumerate(lines, start=1):
+            for m in LINK_RE.finditer(line):
+                target = m.group("target").strip()
+                # Skip images, external links, anchors we can't resolve externally here
+                if is_external(target):
+                    continue
+                ok, reason = check_internal_link(path, target)
+                if not ok:
+                    issues += 1
+                    print(f"{path}:{idx}: Broken link '{target}': {reason}")
+
+    if issues:
+        print(f"Found {issues} broken internal markdown link(s).", file=sys.stderr)
+        print("Fix the paths or anchors so links resolve.", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    args = sys.argv[1:]
+    if not args:
+        args = ["."]
+    sys.exit(main(args))