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

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

@@ -0,0 +1,195 @@
+name: Prettier Auto Fix
+
+on:
+  pull_request:
+  pull_request_target:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  autofix:
+    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 Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: package.json
+
+      - name: Install dependencies
+        run: |
+          if [ -f package-lock.json ]; then
+            npm ci
+          else
+            npm i --no-audit --no-fund
+          fi
+
+      - name: Run Prettier (write fixes)
+        if: ${{ github.event.pull_request.user.login == 'dependabot[bot]' }}
+        run: |
+          npm run format:md
+          npm run format:json
+          npm run format:yaml
+
+      - name: Markdownlint (auto-fix)
+        if: ${{ github.event.pull_request.user.login == 'dependabot[bot]' }}
+        run: npx markdownlint "**/*.md" "**/*.markdown" --config .markdownlint.json --ignore-path .markdownlintignore --fix
+
+      - 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 Prettier/markdownlint fixes"
+          branch: ${{ github.head_ref }}
+          file_pattern: |
+            **/*.md
+            **/*.markdown
+            **/*.json
+            **/*.asmdef
+            **/*.asmref
+            **/*.yml
+            **/*.yaml
+
+      - name: Prettier check (Markdown)
+        run: npm run format:md:check
+
+      - name: Prettier check (JSON / asmdef / asmref)
+        run: npm run format:json:check
+
+      - name: Prettier check (YAML)
+        run: npm run format:yaml:check
+
+      - name: Markdown lint (CI gate)
+        run: npm run lint:markdown
+
+      - name: Enforce EOL (CRLF) and No BOM
+        shell: pwsh
+        run: ./scripts/check-eol.ps1 -VerboseOutput
+
+  autofix_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 Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: package.json
+
+      - name: Install dependencies
+        run: |
+          if [ -f package-lock.json ]; then
+            npm ci
+          else
+            npm i --no-audit --no-fund
+          fi
+
+      - name: Run Prettier (write fixes)
+        run: |
+          npm run format:md
+          npm run format:json
+          npm run format:yaml
+
+      - name: Markdownlint (auto-fix)
+        run: npx markdownlint "**/*.md" "**/*.markdown" --config .markdownlint.json --ignore-path .markdownlintignore --fix
+
+      - 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/prettier/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"
+          # Stage only files we format; avoid workflows to prevent permission issues
+          git add '**/*.md' '**/*.markdown' '**/*.json' '**/*.asmdef' '**/*.asmref' '**/*.yml' '**/*.yaml'
+          git commit -m "chore(format): apply Prettier/markdownlint fixes 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/prettier/pr-${prNumber}`;
+            const {owner, repo} = context.repo;
+            const title = `chore(format): Apply Prettier/markdownlint to PR #${prNumber}`;
+            const body = [
+              `This automated PR applies Prettier and markdownlint fixes 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');
+
+            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/prettier/pr-${prNumber}`;
+            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 Prettier/markdownlint fixes to this PR).`;
+              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 });
+              }
+            }

package/.github/workflows/update-dotnet-tools.yml

@@ -0,0 +1,80 @@
+name: Update .NET Tools
+
+on:
+  schedule:
+    - cron: '25 5 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update-tools:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Setup .NET SDK
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: '8.0.x'
+
+      - name: Restore dotnet tools
+        run: dotnet tool restore
+
+      - name: Update local dotnet tools
+        shell: pwsh
+        run: |
+          $manifest = Join-Path $PWD ".config/dotnet-tools.json"
+          if (!(Test-Path $manifest)) {
+            Write-Host "No dotnet tool manifest found. Skipping."
+            exit 0
+          }
+
+          $json = Get-Content $manifest -Raw | ConvertFrom-Json
+          $toolIds = @()
+          if ($json.tools) {
+            $toolIds = $json.tools.PSObject.Properties.Name
+          }
+
+          if ($toolIds.Count -eq 0) {
+            Write-Host "No tools defined in manifest."
+            exit 0
+          }
+
+          foreach ($id in $toolIds) {
+            Write-Host "Updating $id..."
+            dotnet tool update $id --local
+          }
+
+      - name: Detect manifest changes
+        id: git_changes
+        run: |
+          if git diff --quiet; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create Pull Request
+        if: steps.git_changes.outputs.changed == 'true'
+        uses: peter-evans/create-pull-request@v7
+        with:
+          branch: chore/update-dotnet-tools
+          title: "chore: update .NET local tools"
+          commit-message: "chore(dotnet-tools): update .config/dotnet-tools.json"
+          body: |
+            Automated update of local .NET tools defined in `.config/dotnet-tools.json`.
+          labels: dependencies
+          assignees: wallstop
+          reviewers: wallstop
+
+      - name: No changes summary
+        if: steps.git_changes.outputs.changed != 'true'
+        run: |
+          echo "## .NET tools are up to date" >> $GITHUB_STEP_SUMMARY
+

package/.github/workflows/yaml-format-lint.yml

@@ -0,0 +1,41 @@
+name: YAML Format + Lint
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  yaml-checks:
+    name: Prettier and yamllint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup Node
+        uses: actions/setup-node@v5
+        with:
+          node-version: "20"
+          cache: 'npm'
+          cache-dependency-path: package.json
+
+      - name: Install dependencies
+        run: |
+          if [ -f package-lock.json ]; then
+            npm ci
+          else
+            npm i --no-audit --no-fund
+          fi
+
+      - name: Prettier check (YAML)
+        run: npm run format:yaml:check
+
+      - name: yamllint
+        uses: ibiqlik/action-yamllint@v3.1.1
+        with:
+          file_or_dir: .
+          config_file: .yamllint.yaml
+          strict: true

package/.lychee.toml

@@ -1,4 +1,4 @@
-verbose = true
+verbosity = "info"
 no_progress = true
 max_concurrency = 4
 exclude_mail = true
@@ -10,8 +10,9 @@ retry_wait_time = 2     # seconds between retries
 max_redirects = 10
 user_agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36"
 
-# Treat rate-limiting as non-fatal in CI
-accept = [429]
+# Treat successes and rate-limiting as acceptable in CI
+# Accept all 2xx as valid plus 429 (rate limited)
+accept = ["200..=299", 429]
 
 # Only check web links
 scheme = ["https", "http"]
@@ -23,4 +24,3 @@ exclude = [
   "^https?://0\\.0\\.0\\.0",
   "^file://"
 ]
-

package/.markdownlint.jsonc

@@ -0,0 +1,21 @@
+{
+  "default": true,
+  // Allow long lines; Prettier handles wrapping policy
+  "MD013": false,
+  // Allow inline HTML when needed
+  "MD033": false,
+  // First line need not be a top-level heading (many docs start with badges)
+  "MD041": false,
+  // Use fenced code blocks consistently (matches Prettier)
+  "MD046": { "style": "fenced" },
+  // Duplicate headings only matter among siblings
+  "MD024": { "siblings_only": true },
+  // Accept ascending ordered list numbers (matches Prettier behavior)
+  "MD029": { "style": "ordered" },
+  // Permit bare URLs; Prettier won’t auto-wrap, and link checks are handled separately
+  "MD034": false,
+  // Allow exactly one blank line between blocks (Prettier’s behavior)
+  "MD012": { "maximum": 1 },
+  // Don’t flag the two trailing spaces used for hard line breaks in Markdown
+  "MD009": { "strict": false }
+}

package/.pre-commit-config.yaml

@@ -15,7 +15,7 @@ repos:
         description: Install the .NET tools listed at .config/dotnet-tools.json.
       - id: csharpier
         name: Run CSharpier on C# files
-        entry: dotnet tool run Csharpier format
+        entry: dotnet tool run csharpier format
         language: system
         types:
           - c#
@@ -24,10 +24,10 @@ repos:
   - repo: local
     hooks:
       - id: prettier
-        name: Prettier (Markdown, JSON, asmdef, asmref)
+        name: Prettier (Markdown, JSON, asmdef, asmref, YAML)
         entry: npx --yes prettier --write
         language: system
-        files: '(?i)\.(md|markdown|json|asmdef|asmref)$'
+        files: '(?i)\.(md|markdown|json|asmdef|asmref|ya?ml)$'
         description: Use the repo's Prettier version from package.json.
 
   - repo: local
@@ -37,3 +37,11 @@ repos:
         entry: npx --yes markdownlint --config .markdownlint.json --ignore-path .markdownlintignore
         language: system
         files: '(?i)\.(md|markdown)$'
+
+  - repo: local
+    hooks:
+      - id: yamllint
+        name: yamllint (if available)
+        entry: bash -c 'if command -v yamllint >/dev/null 2>&1; then yamllint -c .yamllint.yaml "$@"; else echo "yamllint not installed; skipping"; fi' --
+        language: system
+        files: '(?i)\.(ya?ml)$'

package/.yamllint.yaml

@@ -0,0 +1,31 @@
+extends: default
+
+ignore: |
+  node_modules/
+  .git/
+  Library/
+  obj/
+  Temp/
+  Samples~/
+
+rules:
+  line-length:
+    max: 200
+    allow-non-breakable-words: true
+    allow-non-breakable-inline-mappings: true
+  truthy: disable
+  document-start: disable
+  comments-indentation: disable
+  comments:
+    min-spaces-from-content: 1
+  indentation:
+    spaces: 2
+    indent-sequences: consistent
+  new-lines:
+    type: dos
+  new-line-at-end-of-file: enable
+  trailing-spaces: enable
+  empty-lines:
+    max: 1
+    max-start: 0
+    max-end: 1

package/AGENTS.md

@@ -20,11 +20,12 @@
 ## Coding Style & Naming Conventions
 
 - Indentation: 4 spaces for `*.cs`; 2 spaces for JSON/YAML/`*.asmdef`.
-- Line endings: CRLF; UTF-8 BOM per `.editorconfig`.
+- Line endings: CRLF; UTF-8 (no BOM) per `.editorconfig`.
 - C#: explicit types over `var`; braces required; `using` inside namespace.
 - Naming: PascalCase for types/public members; camelCase for fields/locals; interfaces prefixed `I` (e.g., `IResolver`); type params prefixed `T`; events start with `On...`.
 - Do not use underscores in function names, especially test function names.
 - Do not use regions, anywhere, ever.
+- Avoid `var` wherever possible, use expressive types.
 
 ## Testing Guidelines
 
@@ -34,6 +35,9 @@
 - Do not use regions.
 - Try to use minimal comments and instead rely on expressive naming conventions and assertions.
 - Do not use Description annotations for tests.
+- Do not create `async Task` test methods - the Unity test runner does not support this. Make do with `IEnumerator` based UnityTestMethods.
+- Do not use `Assert.ThrowsAsync`, it does not exist.
+- When asserting that UnityEngine.Objects are null or not null, please check for null directly (thing != null, thing == null), to properly adhere to Unity Object existence checks.
 
 ## Commit & Pull Request Guidelines
 

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 2.0.0
+
+- Deprecate BinaryFormatter with `[Obsolete]`, keep functional for trusted/legacy scenarios.
+- Make GameObject JSON converter output structured JSON with `name`, `type`, and `instanceId`.
+- Fix stray `UnityEditor` imports in Runtime to ensure clean player builds.
+
+## 1.x
+
+- See commit history for incremental features (random engines, spatial trees, serialization converters, editor tools).

package/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing
+
+Thanks for helping make Unity Helpers better! This project uses a few automated checks and formatters to keep the codebase consistent and easy to review.
+
+## Formatting and Linting
+
+- C# formatting: CSharpier (via dotnet tools)
+- Markdown/JSON/YAML formatting: Prettier
+- Markdown linting: markdownlint
+- Link checks: lychee and custom script
+- YAML linting: yamllint
+
+### Dependabot PRs
+
+Dependabot PRs are auto-formatted by CI. The bot pushes commits (same‑repo PRs) or opens a formatting PR (forked PRs) so they pass formatting gates.
+
+### Opt‑In Formatting for Contributor PRs
+
+If you want the bot to apply formatting to your PR:
+
+- Comment on your PR with `/format` (aliases: `/autofix`, `/lint-fix`).
+  - If your branch is in this repo, the bot pushes a commit with fixes.
+  - If your PR is from a fork, the bot opens a formatting PR targeting the base branch.
+  - The commenter must be the PR author or a maintainer/collaborator.
+- Or run manually from the Actions tab: select "Opt‑in Formatting", click "Run workflow", and enter the PR number.
+
+What gets auto‑fixed:
+
+- C# via CSharpier
+- Markdown/JSON/YAML via Prettier
+- Markdown lint via markdownlint with `--fix`
+
+What does not auto‑fix:
+
+- Broken links (lychee)
+- YAML issues that require manual edits
+
+## Run Checks Locally
+
+- Install tools once:
+  - `npm ci` (or `npm i --no-audit --no-fund`)
+  - `dotnet tool restore`
+- Format C#: `dotnet tool run CSharpier format`
+- Check docs/JSON/YAML: `npm run validate:content`
+- Enforce EOL/encoding: `npm run eol:check`
+
+## Style and Naming
+
+Please follow the conventions outlined in `.editorconfig` and the repository guidelines (PascalCase types, camelCase fields, explicit types, braces required, no regions).

package/CONTRIBUTING.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: b7f3a1c4a2b54b7f9d1c3e6f8a2b7c1d
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/EDITOR_TOOLS_GUIDE.md

@@ -1974,3 +1974,7 @@ All tools are designed to work together seamlessly and follow consistent design
 For questions, issues, or feature requests, please contact the Wallstop Studios team.
 
 - Integration note: The cache powers editor dropdowns and reflection shortcuts for the Effects system’s `AttributeModification.attribute` field. See [Effects System](EFFECTS_SYSTEM.md) for how attributes, effects, and tags fit together.
+
+### MultiFile Selector (UI Toolkit)
+
+- The `MultiFileSelectorElement` is primarily intended for Editor tooling. It can also be used in player builds, where it enumerates files under the application’s data root. In the Editor it integrates with `EditorPrefs` and Reveal-in-Finder; at runtime it falls back to `PlayerPrefs` and omits Editor-only affordances.