com.wallstop-studios.dxmessaging 2.0.0-rc27 → 2.0.0-rc27.2

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))

package/.github/workflows/csharpier-autofix.yml

@@ -0,0 +1,152 @@
+name: CSharpier Auto Format
+
+on:
+  pull_request:
+  pull_request_target:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  format:
+    name: Format and propose changes
+    if: ${{ github.event_name != 'pull_request_target' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: "8.0.x"
+
+      - name: Restore .NET tools
+        run: dotnet tool restore
+
+      - name: Run CSharpier (format repository)
+        if: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && github.event.pull_request.user.login == 'dependabot[bot]' }}
+        run: dotnet tool run csharpier format
+
+      - name: Commit formatting changes to PR branch (Dependabot only)
+        if: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && github.event.pull_request.user.login == 'dependabot[bot]' }}
+        uses: stefanzweifel/git-auto-commit-action@v7
+        with:
+          commit_message: "chore(format): apply CSharpier formatting"
+          branch: ${{ github.head_ref }}
+          file_pattern: |
+            **/*.cs
+
+      - name: Verify formatting (CI gate)
+        run: dotnet tool run csharpier check .
+
+  format_fork:
+    name: Fork PR bot formatting PR (Dependabot only)
+    if: ${{ github.event_name == 'pull_request_target' && github.event.pull_request.head.repo.full_name != github.repository && github.event.pull_request.user.login == 'dependabot[bot]' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout fork PR HEAD
+        uses: actions/checkout@v5
+        with:
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          ref: ${{ github.event.pull_request.head.ref }}
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: "8.0.x"
+
+      - name: Install CSharpier (pinned)
+        run: dotnet tool install -g csharpier --version 1.1.2
+
+      - name: Run CSharpier (format repository)
+        run: ~/.dotnet/tools/csharpier .
+
+      - name: Detect changes
+        id: changes
+        shell: bash
+        run: |
+          if git diff --quiet; then
+            echo "has_changes=false" >> $GITHUB_OUTPUT
+          else
+            echo "has_changes=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create bot branch and push to base repo
+        if: steps.changes.outputs.has_changes == 'true'
+        shell: bash
+        env:
+          GH_REPO: ${{ github.repository }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          BRANCH="bot/csharpier/pr-${{ github.event.pull_request.number }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -B "$BRANCH"
+          # Only stage C# files to avoid touching workflow YAML (requires special permissions)
+          git add '**/*.cs'
+          git commit -m "chore(format): apply CSharpier formatting for PR #${{ github.event.pull_request.number }}"
+          git remote add upstream "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git"
+          git fetch upstream
+          git push upstream "$BRANCH" --force
+          echo "branch=$BRANCH" >> $GITHUB_OUTPUT
+
+      - name: Open or update formatting PR in base repo
+        if: steps.changes.outputs.has_changes == 'true'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const prNumber = context.payload.pull_request.number;
+            const baseRef = context.payload.pull_request.base.ref;
+            const headBranch = `bot/csharpier/pr-${prNumber}`;
+            const {owner, repo} = context.repo;
+            const title = `chore(format): Apply CSharpier to PR #${prNumber}`;
+            const body = [
+              `This automated PR applies CSharpier formatting to the changes from PR #${prNumber}.`,
+              '',
+              `- Source PR (fork): #${prNumber}`,
+              `- Target branch: ${baseRef}`,
+              '',
+              'If this PR is merged, it will include the contributor\'s changes plus required formatting.',
+              'You can then close the original PR or ask the author to rebase.',
+            ].join('\n');
+
+            // Check if a PR from this branch already exists
+            const existing = await github.rest.pulls.list({ owner, repo, state: 'open', head: `${owner}:${headBranch}` });
+            if (existing.data.length === 0) {
+              await github.rest.pulls.create({ owner, repo, head: headBranch, base: baseRef, title, body });
+            }
+
+      - name: Comment link on original PR
+        if: steps.changes.outputs.has_changes == 'true'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const prNumber = context.payload.pull_request.number;
+            const {owner, repo} = context.repo;
+            const headBranch = `bot/csharpier/pr-${prNumber}`;
+            // Find the formatting PR we just created or updated
+            const resp = await github.rest.pulls.list({ owner, repo, state: 'open', head: `${owner}:${headBranch}` });
+            if (resp.data.length > 0) {
+              const fmtPr = resp.data[0];
+              const body = `A formatting PR has been opened: #${fmtPr.number} (applies CSharpier to this PR).`;
+              // Avoid duplicate comments by checking recent comments
+              const comments = await github.rest.issues.listComments({ owner, repo, issue_number: prNumber, per_page: 50 });
+              const already = comments.data.some(
+                (c) =>
+                  c.body &&
+                  c.body.includes(`#${fmtPr.number}`) &&
+                  c.user &&
+                  c.user.login === 'github-actions[bot]'
+              );
+              if (!already) {
+                await github.rest.issues.createComment({ owner, repo, issue_number: prNumber, body });
+              }
+            }