Skip to content

Project Contributing

github-actions[bot] edited this page Nov 18, 2026 · 65 revisions

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.

This guide is for changing Unity Helpers itself. To add the package to your game, use Getting Started. The tools and runner access below are for repository development.

Development and maintainer guides

Choose the setup you need:

Dev Container Setup (Recommended)

The easiest way to contribute is using the included dev container, which has all CI/CD tools pre-installed:

  1. Open in VS Code with the Dev Containers extension
  2. Click "Reopen in Container" when prompted
  3. Run npm run verify:tools to confirm all tools are available

The verifier runs through locked uv and uses the native version commands for each tool. It limits each probe to 30 seconds and keeps up to 64 KiB of its first output line. On a host machine, tools marked as container-only are optional. Run npm run test:verify-devcontainer-tools to exercise the inventory and version probes.

Run bash scripts/validate-devcontainer-urls.sh to check the Dockerfile's download URLs. If HEAD probes fail, the validator confirms reachability with a GET limited to one byte. This fallback requires curl 8.4.0 or newer; older or unrecognized versions retain the failed HEAD result. A successful 200 or 206 response also permits curl's size-limit stop when a server ignores the range. Missing resources, HTTP errors, and other transfer failures still fail validation. Run npm run test:validate-devcontainer-urls for the offline HTTP and parser controls.

Use npm run eol:fix to normalize supported tracked text files through locked uv. The allowlist in scripts/check_eol.py controls selection. The fixer skips .py and .js files. The PowerShell launcher still accepts -Paths, -DryRun, and -ModifiedPathList for scoped repairs. A dry run returns 2 when changes are needed and can write a NUL-delimited list of affected paths. Preflight uses that list to check for unstaged changes before editing. The fixer refuses files and links outside the checkout, hard-linked files, and invalid text that would need rewriting. Internal symbolic links use the target's path and line-ending policy in the repair plan.

Fast C# Feedback

Use fixture-scoped builds while editing runtime or Editor tests. The npm command runs the locked Python tool through uv and uses the installed .NET SDK:

npm run typecheck:iterate -- tests --server --files Tests/Runtime/Serialization/WProtoEnumFormatterTests.cs
npm run typecheck:iterate -- editor-tests --server --files Tests/Editor/Tools/OdinMigration/OdinMigrationLiveDictionaryTests.cs

Add dependent fixtures to the same --files list. Production code, shared test support, test types, and test doubles remain included. Each scope accepts files only from its corresponding test tree. These commands retain source generators and compiler errors but omit performance analyzers. Run the normal applicable typecheck commands and changed-file preflight before publishing.

When analyzer payloads change, use npm run typecheck:unity:clean. Its typed Python runner removes owned build outputs before running the full source gates with compiler-server reuse disabled. It refuses a linked Generator~ and does not follow linked project or build directories. The former Node entry point remains a compatibility launcher through locked uv.

npm run format:csharp:check and npm run format:csharp also run a typed Python implementation behind their PowerShell launchers. Scoped calls retain -Paths, -Fix, -VerboseOutput, and -SkipWhenUnavailable. The last flag announces missing-tool skips; normal repository checks require the formatter to run.

The analyzer placement check evaluates MSBuild compiler inputs for each owned .NET project with both protobuf oracle settings. Each shipped analyzer must appear exactly once at its package path. Normal assembly references, including the compiler compatibility test reference, do not count as compiler inputs. Run it with node scripts/tests/test-analyzer-placement.js.

The WProto compatibility inventory checks referenced enum values independently of source file order. Its regression compiles both declaration orders and requires the same inventory, including the enum underlying type and constants. Preserve the frozen inventory when fixing its collector.

Test runtime reports

Use the typed NUnit timing reporter to rank slow fixtures and cases:

uv run --project scripts/python~ --locked --no-dev python scripts/unity/report_slow_tests.py --results-path results.xml --top 30 --fixture-budget-seconds 120 --step-summary

Add --fail-over-budget to enforce the fixture budget; otherwise overruns produce warnings. The budget covers every fixture, including those outside --top. Names use ordinal tie ordering. Malformed, negative or nonfinite durations and results without fixtures or cases fail the command; missing durations on skipped tests count as zero. A step summary appends UTF-8 Markdown when GITHUB_STEP_SUMMARY is set. The existing PowerShell command retains its parameter names.

AssetPostprocessorContractTests caches compiled method-signature expressions while retaining its complete source scan and eight case identities. On Windows x64 Unity 6000.6.7f1 Editor Mono, three alternating process pairs reduced median fixture duration from 7.81 to 5.82 seconds. Paired candidate/baseline ratios ranged from 0.589 to 0.903; all six processes passed eight cases, exited zero and reached both stream ends. These are fixture timings, not the whole EditMode suite or editor startup. The source variants, NUnit results and receipts make the scoped comparison reproducible.

Pure EditMode fixtures

Keep pure string and value tests in fixtures without asset setup. The singleton path tests now retain all 30 input/expected-value cases in a plain fixture, while the 13 asset integration cases keep their existing setup and cleanup. Three alternating fresh Unity 6000.6.7f1 process pairs pass all 43 cases with equal canonical case inventories. The moved cases take a median 1.368 seconds before and 0.002 after. The whole cohort medians are 10.557 and 8.667 seconds, with one slower candidate pair. This does not establish full-suite or CI timing. The replay capture retains source variants, all six NUnit results, process receipts, source hashes and the complete case inventory.

Typed Python scripts

Devcontainer configuration validation uses scripts/validate_devcontainer_config.py through locked uv. npm and Repo Lint invoke Python directly. The publish workflow provisions the shared Python/uv tools before its retained PowerShell command. Both PowerShell paths remain tested compatibility launchers. The gate preserves the image namespace, cache tags, publication metadata, workflow coverage and eleven required language-entry checks. Its retained text patterns check entry presence; they do not validate arbitrary JSON/YAML schemas or formatter values.

npm run test:validate-devcontainer-config replays 36 original executable decisions. All 22 original suite assertions pass before and through the port. Additional controls cover five original BOM encodings, ordinal language-identifier casing, Unicode/foreign-directory launchers, failures without input mutation, and Python setup before publication validation. PowerShell's error framing remains host presentation; failure status and actionable message text are preserved. All 184 Python files join strict checks.

Seven alternating Linux tmpfs process pairs after two warmups per arm measured repository validation at 279.06 → 42.45 ms and a 500-workflow fixture at 331.75 → 43.26 ms, including uv startup. Every pair matches successful stdout/stderr and exit status and retains input/source hashes. The qualification record preserves those observations, original decisions and setup limitations. Windows, cold-host and whole-CI speed remain unmeasured.

Devcontainer download URL validation uses scripts/validate_devcontainer_urls.py through locked uv. The Bash validator and test commands remain compatibility launchers. The check discovers versioned GitHub and .NET downloads for amd64 and arm64, rejects apt-based PowerShell installs, and probes each selected URL. It keeps three HEAD attempts and uses a one-byte ranged GET only with curl 8.4 or newer. The offline --contracts-only and --list-tools modes make no network calls.

The test:validate-devcontainer-urls npm command replays 25 original decisions, including exact streams, curl arguments and retry delays, and runs the Dockerfile's nested Lychee archive install for both architectures on Linux. All 51 original assertions also pass through the Python port. Seven paired Linux measurements of --list-tools measured median times of 97.32 to 33.41 ms on the repository Dockerfile and 724.38 to 35.94 ms on a 120-tool fixture, including uv startup. The qualification record retains the inputs, source hashes, raw pairs and scope of the measurements.

GitHub Pages CSS validation uses scripts/validate_github_pages_css.py through locked uv. The Bash commands remain tested compatibility launchers; npm and the lint registry call Python. The gate retains its fixed layout, breakpoint and accessibility checks, fail-fast errors, and warning-only CSS heuristics. It is not a general CSS parser. It reads one regular UTF-8 file without changing its bytes; unreadable, invalid UTF-8 and nonregular inputs fail visibly. npm run test:validate-github-pages-css replays 56 frozen original CLI observations and checks the real theme, foreign-directory launchers, Unicode output, read failures and a large comment.

Seven alternating fresh-process pairs after two warmups per arm on Linux tmpfs measured the real theme at 49.15 → 44.25 ms and a 100 KiB comment fixture at 55.23 → 42.68 ms, including uv startup. Every pair matches stdout, stderr and exit status and preserves inputs and source hashes. The qualification record also retains the rejected initial port: its 100 KiB fixture took 4,587.62 ms because of regex backtracking. A real 1 MiB child and repeated declaration/media-prefix controls each timed out at five seconds before correction and complete afterward. Literal input-path spelling and the legacy GNU grep hex-color exclusions also retain original-executable red/green controls. These local observations do not establish Windows, cold-host or whole-CI speed.

Release-tag validation uses scripts/ci/verify_release_tag.py through locked uv. The release workflow provisions the shared Python tools before validation. The PowerShell entry point remains compatible, including empty values and rejection of stray arguments. npm run test:verify-release-tag replays 24 frozen original CLI observations and checks metadata types, malformed input, output failures and both compatibility entry points. Package names and versions containing CR, LF or NUL fail before writing step outputs; the original verifier accepted a name containing LF and wrote an injected output.

Seven alternating Linux tmpfs process pairs after two warmups per arm used bootstrap uv 0.13.6 and PowerShell 7.5.3 to measure original PowerShell versus Python through uv. Median times were 244.12→39.17 ms for a small valid manifest, 243.13→39.66 ms with 1,000 extra fields, and 238.56→38.83 ms for a version mismatch. Exit status, standard output and step-output bytes match in every pair. Source and lock hashes stayed fixed. These local command observations do not measure release-job or Windows speed.

Npm package validation uses scripts/validate_npm_package.py through locked uv. It checks archive entries directly, without extraction. The six original policy lists and 12 original executable decisions remain frozen in regression fixtures. Checks retain exact path case, hidden entries, required metadata, permitted exclusions, and one diagnostic for forbidden PR artifacts. Links, special entries, duplicate paths and path conflicts are refused. The comparison with Git verifies the file inventory; it does not compare file bytes.

npm run test:npm-package-changelog checks the package surface and validator; npm run test:npm-package-signature checks signature metadata. Compatibility PowerShell commands remain tested. Child failures preserve their status and both output streams. Owned temporary directories are cleaned after success and failure. Synchronization contracts execute semantic policy and path controls in place of checks for PowerShell source text.

Seven alternating fresh-process pairs with pinned uv 0.13.8 and Node 22.23.4 on Linux tmpfs measured small-package validation at 539.82 → 225.71 ms and validation with 250 extra source/meta pairs at 811.76 → 348.76 ms. Every pair matched normal output bytes and kept inputs unchanged. The qualification record retains both captures, all timed rows, input manifest hashes and source identities. These are local warm observations; native Windows, cold-machine and whole-CI performance remain unverified.

Release preparation, notes and UPM changelog synchronization use scripts/release_tools.py through locked uv. The PowerShell commands remain compatibility launchers. The release workflows call Python directly. Preparation retains named version/bump arguments, dry runs, fenced changelog examples and lockfile root versions. UPM notes retain the 8,000 UTF-16 code-unit budget and whole-line truncation. npm run test:release-tools replays 42 original helper observations and eight original UPM file outputs, then checks publication and CLI failures.

Selected release files publish atomically and preserve hard-linked authored aliases. Invalid input and redirected source paths fail before preparation writes. A later filesystem failure can still leave a partially published batch. Diagnostic wording for malformed types and integer overflow can differ from PowerShell. These local captures do not establish native Windows behavior.

Seven alternating fresh-process pairs on Linux tmpfs with pinned uv 0.13.8 measured median small preparation dry runs at 283.27 → 53.34 ms, 1,000-line dry runs at 288.11 → 51.31 ms, and 1,000-line note extraction at 246.25 → 51.13 ms. Every pair matched stdout bytes and left its input files unchanged. The qualification record retains the raw rows and source identities. These are local warm observations; release-job, cold-machine and Windows performance remain unverified.

Automatic release publication and native release evidence checks use scripts/release_automation.py through locked uv. The Node CLI paths remain launchers; their former internal test imports have moved to the typed suite. npm run test:auto-publish-release replays 565 original decisions and exercises permanent publication claims, ambiguous mutation responses, pagination limits and exact-source validation. Native export requires the current run attempt, all six ordered cleanup steps, and independent older-editor compatibility jobs. Workflow permissions, trusted checkout refs and concurrency policies retain their original controls.

Seven alternating Linux tmpfs process pairs with pinned uv 0.13.8 and Node 22.23.4 measured fixture publication orchestration at 19.30 → 50.57 ms for four workflow runs, and 20.00 → 51.53 ms for 1,004 runs. Python is slower at both sizes. These fixture APIs perform no network calls or real release mutations. The qualification record retains every pair and source hash. It does not measure production publication or Windows speed. HTTP requests refuse redirects. Each request uses an owned Python child with a parent-enforced 30-second deadline. The token travels through stdin, and a timed-out child is killed and reaped. This adds process startup to actual HTTP calls; the fixture timings do not measure that cost. Claims still prevent retries after uncertain mutations. CLI stdout and summaries retain LF bytes. The timing rows predate later admission corrections and do not measure the corrected source. Release admission retains the original handling of empty container fork flags, requires string branch names, and rejects non-JSON numbers and incompatible package encodings before publication.

Local push-default configuration shares typed Python policy through locked uv. Write failures name the failed key; Bash keeps the Git failure status. Bootstrap or protocol failures preserve a prior native exit value or its absence. The Bash and PowerShell commands retain their caller-specific behavior. The dot-sourced PowerShell helper still returns a result table, preserves the caller's exit state and does not start another PowerShell host. A missing uv tool produces a failure result. The Windows PowerShell 5.1 contract has a dedicated Windows control.

The qualification record retains 34 original profile observations and 67 registered controls. Configuration writes only the two local push-default keys; it preserves other local settings and global/system configuration. Another writer's configuration lock remains untouched. A later write failure can leave the first key updated, so inspect local configuration before retrying.

Seven alternating Linux pairs after two warmup pairs measured Bash CLI times of 10.34 → 48.46 ms and PowerShell CLI times of 294.73 → 304.65 ms. Both regressions are retained. Inside an existing PowerShell parent, the medians were 53.43 → 49.43 ms, excluding parent startup and module loading. These results do not measure the healthy read-only push gate, Windows, complete hooks or CI, and do not establish statistical significance.

The read-only Git push gate runs through locked Python with npm run validate:git-push-config. Its retained PowerShell commands delegate to the same validator and controls. The gate checks local push defaults, classifies hook output artifacts, and preserves the existing container credential postcondition. It changes no configuration or files. The existing Bash checker runs only when a Dev Containers helper is registered; it reads configuration and declared host names, and does not request a token. Git reads and the checker have 30-second process deadlines.

The qualification record retains 39 original CLI observations and 56 typed controls. The real container integration uses disposable Git configuration. A PowerShell probe verifies the case-sensitive versus case-insensitive filename boundary. Historical measurements from seven alternating Linux pairs after two warmup pairs were 298.45 → 41.40 ms for a clean fixture and 575.73 → 66.68 ms with 30 hook artifacts. The receipt seals that pre-review implementation; the corrected credential-read error handling has no new timing claim. These fixture timings exclude the container checker and do not measure Windows, complete pushes or CI. Host configuration helpers remain separate migration scope.

Unity failure patterns and environment warnings share the declarative catalogue in scripts/unity/log-patterns.json. Native consumers retain their existing regex engine and can load the catalogue when Python bootstrap is unavailable. Licensing warnings remain observations; independent cleanup receipts determine cleanup health.

npm run test:catastrophic-pattern-sync runs the typed scanner controls and the original native consumer checks. Native-report summaries stream through locked Python, preserve BOM and line-ending behavior, count all observations and retain at most eight locations for each marker. Read failures retain delivered observations with an unreadable-log state. Child or malformed-protocol failures cannot claim observations. The adapter preserves prior or undefined native exit status and closes its native read handle on success and failure. The native handle retains FileShare.Read semantics.

The log qualification record retains the original implementation, all pattern values, host profiles and performance misses. Seven alternating pairs after two warmup pairs in an existing PowerShell parent measured catalogue loading at 0.11 → 0.59 ms, a tiny scan at 4.09 → 49.90 ms and a 4 MiB scan at 88.44 → 101.04 ms. These all regressed. A 32 MiB scan improved from 688.71 → 460.70 ms on the measured shared 9p fixture. Earlier captures remain retained; these observations do not establish Windows, full-job or statistically significant improvements. The owned Windows writer-sharing control requires Windows CI.

Windows tool validation runs metadata and process-orchestration suites in two isolated phases, with at most two phases active. Each retains a ten-minute job limit. The Assembly tools (Windows) aggregate requires both phases to succeed; cancellation, skips and failures cannot pass it. All previously selected suites remain registered.

Unity 6 projects that seed scripting defines also select the legacy Input Manager used by their generated package manifest. The generation fingerprint includes this bootstrap policy, so earlier generated settings and Libraries keep their old workspace identity. Existing caller-supplied settings remain authoritative.

Unity project workspace selection and retention planning use locked typed Python behind scripts/unity/lib/project-workspace.ps1. Run npm run test:project-workspace for original-host comparisons, filesystem controls and compatibility launchers. Explicit paths retain precedence; generated fingerprints continue to isolate variant projects while sharing download caches. Native PowerShell comparison and timestamp ordering remain at the adapter boundary, including equal-time ordering. Native Directory.Move retains project directories without replacement; existing native volume measurement and deletion preserve host filesystem behavior. The adapter preserves the caller's prior or undefined native exit status on success and failure.

Retention refuses linked ancestors, explicit projects with migration residue and unproven generated projects. A failed move reports source and destination without retrying, deleting residue or falling back to a fresh project. Release blocking handles after licensed work and cleanup are idle before retrying. Prune plans reject nonfinite space observations and consumed negative or nonfinite sizes. They stop at the floor without interpreting unused candidate sizes. A planning failure logs and skips best-effort pruning before any deletion; workspace resolution and retention errors remain fatal.

The workspace qualification record retains original implementations, host comparisons and paired Linux measurements. Seven alternating pairs after two warmup pairs measured workspace resolution at 0.63 → 33.68 ms and prune planning at 0.83 → 34.83 ms. Empty-project retention checks on the measured deep artifact path improved from 343.74 → 39.46 ms. These results include Python startup, retain both regressions and do not measure Windows, shallow paths, complete Unity jobs or statistical significance. No runner file lock is resolved by this migration.

Read-only push validation honors the explicit repository even when inherited repository-location variables identify another Git directory. Child Git reads and the credential checker retain configuration variables, including GIT_CONFIG_*. The hook-text PowerShell wrapper resolves null, empty or whitespace-only roots to its own repository. An explicit nonblank root stays authoritative.

Hook executable-mode validation runs through locked Python with npm run validate:hook-perms; the shell validation and test commands remain launchers. Only tracked, extensionless hook basenames are checked, including nested paths. The index must contain stage-zero entries with mode 100755. Empty audits and unmerged entries fail. --fix delegates one mode batch to the existing native PowerShell mutex and retry coordinator. Repairs preserve staged blobs and the assume-unchanged, skip-worktree and intent-to-add settings. They respect alternate indexes and other writers' locks. Git reads have 30-second deadlines. Repair hints quote the launcher and selected --repo-root, so running a hint from another directory repairs the same repository that validation inspected. Keep noncooperating index writers idle; a failed readback after mutation requires inspection before retrying and does not roll back the index.

The qualification record retains original CLI decisions, the original shell driver and portable repair controls. The original bare chmod operation could stage working-file content; the coordinated repair preserves the staged blob even when working content differs. Diagnostics are plain text. The historical capture at 0d814246 used its recorded tooling configuration; later integration hashes do not rebind those measurements. Seven alternating Linux pairs after two warmup pairs measured 3.59 → 36.12 ms for healthy validation, 3.74 → 36.37 ms for rejection and 7.18 → 376.11 ms for repair. All startup regressions are retained, including the native coordinator launch cost. These results do not measure Windows, complete hooks or CI, and do not establish statistical significance.

Hook text validation runs through locked Python with npm run validate:hook-sync. The retained PowerShell validator and test commands delegate to that implementation. Required tokens and forbidden merge-hook startup tokens keep their case-insensitive presence rules. These rules also match comments; they do not parse or execute PowerShell. UTF-8, UTF-16 and UTF-32 BOM files retain their original behavior. Empty, unreadable, and malformed hook files fail. The previous validator incorrectly accepted empty hook files.

The qualification record retains 24 original CLI observations and the three intentional empty-file corrections. The 50 controls cover each required and forbidden token, both retained launchers, and the current hooks. Seven alternating Linux pairs measured median CLI times of 204.70 ms for PowerShell and 37.11 ms for locked uv/Python after two warmup pairs. These observations concern this no-op validator on one host; they do not measure whole hooks, Windows or CI.

Version reference synchronization uses scripts/version_sync.py through locked uv. The PowerShell entry points remain launchers. Content rules, sorting and validation run in Python; batched staging delegates to the existing PowerShell mutex and retry coordinator. This native coordinator preserves the active alternate index and existing contention policy. Default template synchronization reads the tracked manifest; release preparation alone adds a package version. Local tags and remote releases cannot add dropdown entries.

The read-only check-banner command checks every actual text badge and repeated version field. Commented and CDATA text cannot satisfy a badge check; repairs retain those bytes. It rejects five retained false positives from the old substring checks. The regression suite retains 40 original synchronization observations and ten original validation observations, including malformed metadata that now fails before writes. Missing optional repair inputs still produce warnings. The validator and repository dropdown checks require their real input files.

Before the later banner validation corrections, seven alternating fresh-process pairs after two warmups per arm on Linux tmpfs measured:

Command and input Original PowerShell Python through uv
Banner, small, unchanged 303.25 ms 53.95 ms
Banner, small, rewrite 349.09 ms 353.51 ms
Banner, large, unchanged 305.55 ms 54.10 ms
Banner, large, rewrite 345.96 ms 359.80 ms
Templates, small, unchanged 333.74 ms 54.13 ms
Templates, small, rewrite 355.54 ms 355.63 ms
Templates, large, unchanged 337.42 ms 54.62 ms
Templates, large, rewrite 373.83 ms 361.20 ms

Banner rewrites are slower at both sizes. Small template rewrite medians are effectively equal. A separate call inside an already running PowerShell parent measured 147.28 → 92.14 ms, excluding parent startup. The qualification record retains every pair, source seals, fixtures and limits. These historical rows do not measure the corrected banner implementation, Windows, cold-machine, complete Git-commit or CI speed.

Known non-writable destinations fail before any file is replaced. Hard-linked authored aliases stay unchanged. Each selected file publishes atomically; keep other writers idle. Publication is not a transaction across files and the index. A later I/O or staging failure can leave working files updated. Inspect the selected files and active index before retrying.

Skill indexing, instruction validation and skill-split migration also use typed Python. The PowerShell and Node entry points remain tested compatibility launchers. The generator preserves the canonical index bytes and ordinal basename order. Links retain the actual source filename. Its --check mode reads the index and requires matching bytes, a tracked file and clean Git status for that path. Instruction checks retain all 35 original policy requirements and two independent generator processes. The regression suite mutates temporary copies of tracked guidance.

Publication replaces each selected file atomically and preserves existing file modes. A hard-linked authored file stays unchanged. Invalid reference filenames fail before writes; the original refresh could change an authored file outside the instruction roots and then fail. Skill publication validates and stages all selected files before replacement. It rolls back handled publication failures. It compares every source, reference and manifest with its captured bytes after formatting and staging, checks each destination immediately before its replacement, and checks the resulting batch before cleanup. Rollback preserves an observed later edit instead of restoring a backup over it. If rollback fails, .llm/.skill-migration-recovery retains backups and hashes; later migration and check commands refuse to skip that recovery state.

Seven fresh-process pairs on Linux x86_64 with tmpfs, uv 0.13.8, Node 22.23.4, PowerShell 7.5.3 and Python 3.14.10 measured these median command times:

Command Original Python through uv
Index stdout 321.41 ms 45.84 ms
Split verification 81.90 ms 111.27 ms
Authorship policy 288.19 ms 55.71 ms
Full instruction validation 1050.85 ms 196.17 ms

Split verification is slower. Keep that cost beside the index and validation gains. The qualification record retains every paired observation, source and runtime identities, the earlier bootstrap-tool regression, and the filesystem-label correction. Guidance and discovery inputs are identical across the two worktrees. Each implementation’s source seals remain unchanged during its capture. These observations do not establish Windows, cold-machine or whole-CI performance.

The portability qualification records the Windows failures and their local regression controls. Explicit generated manifests bypass formatter ignore rules, matching the former Prettier API. Index stdout stays LF across platforms. The registry CLI restores its caller's output mode. Release preparation requires ASCII versions, rejects dangling lockfile links, and preserves fenced example headings.

The timing tables describe the captured implementations before these later corrections. They do not measure the corrected source. Pending recovery must be inspected before retrying: first save any later authored edits separately. Restore the owned paths from the recorded backups and verify their hashes, then remove the recovery directory and retry the whole migration. Reapply saved edits and refresh again. Keep editors and other writers idle during migration; byte comparisons detect observed changes but do not provide an operating-system compare-and-swap against a noncooperating writer between the final check and replacement. Remove a published path only when the journal records that no original file existed. A hard process termination or an operating system refusal can require this manual recovery.

Repository-local Prettier, cspell and markdownlint launch through scripts/run_node_bin.py in locked uv. The existing Node launchers remain compatible. The launcher selects the installed package's declared binary, preserves argument boundaries without a shell, inherits standard input without reading it, and propagates child exit status. --check-install validates the package and binary without starting Node. Run npm run test:node-bin for the frozen original CLI observations and process controls. Invalid package metadata fails with a diagnostic; JSON parser wording can differ from Node.

npm run lint:comparison-direction and its :fix variant run the typed Python comparison checker. The Node entry points remain compatibility launchers. The port retains token handling for generics, shifts, patterns, strings and interpolation holes, along with the existing cautious rewrite rules. npm run test:lint-comparison-direction replays 56 frozen original findings and rewrites and exercises CLI failures, source ownership, build-output exclusions and line endings. The original 41 controls passed before capture. Reports retain UTF-16 columns and physical line numbers; rewrites preserve CRLF bytes. These observations establish parity for the retained corpus, not a complete C# parser or permission to reorder arbitrary property getters.

The original observations include unsafe rewrites. Current controls retain that historical data but require manual changes for generic or shift operands and comparisons without a literal constant on either side. A literal boundary avoids reordering two potentially dependent reads or effects. Overlapping edits are refused, including edits surrounding interpolation holes; disjoint edits can still apply, with a failing exit status for unresolved comparisons. The replay archive captures the initial port at 7390d47d, before these safety corrections.

A local full-tree comparison over the same 2915 files used three alternating pairs. Median process times were 7.001 seconds for the original Node checker and 10.014 seconds for Python. The port is slower in all three pairs; this change establishes typed tooling and retained behavior, not a startup-speed improvement. The replay data retains the commands, source hashes, coverage validation and all six observations.

Documentation links run through scripts/lint_doc_links.py in locked uv. The doc-links and doc-links-test Repo Lint subjects and both npm link commands use Python directly. The Node and PowerShell commands remain compatibility entry points. --mode Targets checks local file and directory targets; --mode Format checks Markdown style; All does both. --paths accepts literal repository paths and refuses missing or external sources. Empty supported-source scans fail. Git inventories use NUL delimiters, preserve exact case, and include untracked files while respecting ignore rules. Targets must exist inside the repository. Angle-bracket targets preserve spaces; URL-encoded paths are decoded before resolution.

The frozen scripts/tests/fixtures/doc-links-v1.json replays 41 actual invocations of the original checker after its complete 51-assertion suite passed. Additional Python controls cover source masking, shell heredocs, JavaScript regex literals, lexical case, missing indexed files, links outside the repository, and actual compatibility launches from another working directory. Markdown targets resolve from their document directory; source references retain repository-root fallback. Reference definitions keep target validation without prose-only style errors. Fences track their marker and length. Python docstrings are identified by syntax, while assigned and returned multiline strings remain visible. Source references do not truncate longer extensions such as .mdx to .md.

The checker retains the earlier inline-link grammar limitation for parentheses inside targets. The replay capture retains the original corpus, source identities, native Windows results and six suite timing observations. The expanded 90-case suite takes about eight seconds locally, as did the original 51-assertion suite; no consistent suite speedup is established.

uv run --project scripts/python~ --locked pytest scripts/tests/test_doc_links.py -q

npm run lint:tests runs the typed Python test-lifecycle checker. The PowerShell lint and test commands remain compatibility entry points. Explicit --paths are literal files; absent, linked or unreadable inputs fail. Full scans require a nonempty Tests tree and exclude Unity's hidden consumer folders. Null-assertion repair validates the full input batch before writing, preserves encoding and line endings, and refuses writable hard links. Comments and string literals are neither repaired nor treated as test code. Calls left for manual repair retain inline suppressions. Editor-reference guards must exclude player builds even when another symbol is enabled; merely mentioning UNITY_EDITOR in an OR condition is insufficient.

The regression corpus in scripts/tests/fixtures/test-lifecycle-v1.json records 144 actual invocations of the previous linter at a86ec34b, including diagnostics and repaired contents. The original PowerShell suite passed all 157 assertions before the port. The Python suite replays those captures and adds input, scanner, repair and compatibility-launcher controls:

uv run --project scripts/python~ --locked pytest scripts/tests/test_lifecycle_lint.py -q

At commit 87fc1cd1, three alternating fresh-process pairs over the same 1,785 C# files retained identical 75 path/line/code diagnostics. Median complete-command time fell from 26.05 to 9.25 seconds on this Linux host. This includes process launch and the full scan; it does not predict CI timing. The timing captures and replay sources retain the unchanged source inventory, all six observations and tool identities. The timing data applies to that version. Later fixes to assertion repair and category detection have separate correctness coverage.

Documentation counts use scripts/doc_counts.py through locked uv. npm run lint:doc-counts checks without writing; npm run sync:doc-counts updates only the documented target files. Counts ignore C# comments and literal contents. Linked target files and parent directories are rejected. For metadata JSON, run uv run --project scripts/python~ --locked --no-dev python scripts/doc_counts.py generate. The three PowerShell commands remain compatibility entry points. Run npm run test:lint-doc-counts for count, encoding, newline, read-only, and wrapper exit-code controls.

npm run eol:check runs the typed Python line-ending checker. It checks worktree line endings and UTF-8 BOMs, plus committed text blobs whose CR bytes would make fresh clones appear dirty. Use -- --paths <path> <path> for literal file scopes. Missing selected text files, linked inputs, and failed Git reads fail explicitly. A full scan requires nonempty tracked text input. npm run test:check-eol runs the Git-blob, worktree, path-scope and compatibility-launcher controls. The two PowerShell entry points remain available for existing hooks and callers.

npm run test:final-newline checks tracked text and named configuration files. The standalone bash scripts/validate-formatting.sh --fix uses Prettier for formatting and cached Git attributes for newline repairs. A repair updates the worktree and leaves the index intact. The command refuses linked tracked inputs before repair. Run --fix when other tools have finished writing the files.

npm run validate:lint-error-codes harvests error-code prefixes from lint scripts, their controls, and Git hooks, including typed Python names. It sends one batch through the repository's actual cspell configuration and prints source locations plus a root-word patch for rejected families. npm run test:validate-lint-error-codes also runs the retained PowerShell runspace controls, which continue to protect the fixture host while other PowerShell suites still use it.

npm run lint:code-samples runs the typed Python documentation sample extractor. Its report keeps each C# fence's actual opening line across LF, CRLF, and CR input. The CommonMark parser handles matching backtick/tilde markers, blockquotes and nested lists. Source maps retain the opening line; extracted code omits the Markdown container prefixes. The sample commands select the documentation dependency group; metadata-only tools keep an empty base environment. The default scan uses Git's tracked and nonignored file inventory, so local evidence and dependency directories do not extend the walk. CODE_SAMPLES_ROOT or --scan-root selects an explicit fixture tree instead. The Node launcher and PowerShell test launcher remain compatible entry points.

npm run test:extract-code-samples covers classification, source locations, generated files, name collisions, empty inputs, path ownership, and both launchers. The extractor retains the existing JSON report fields. Corrected source lines can change generated filenames. Source paths on another Windows volume remain absolute in reports and generated identities. Complete struct and interface examples remain at type scope when compilation units are generated. Generation is a heuristic convenience; the standalone documentation compiler checks remain the separate compilation gate.

Release payload staging, archive creation, and Unity metadata generation run through uv. Install uv 0.13.8, then use:

python -m pip install --disable-pip-version-check uv==0.13.8
uv sync --project scripts/python~ --locked
npm run lint:python
npm run test:create-unitypackage
npm run test:asmdef
npm run test:protobuf-candidate
npm run test:native-debugger-download
npm run test:meta-generation
npm run test:fixture-assets
npm run test:frozen-files
npm run meta:generate -- Runtime/Example.cs
uv run --project scripts/python~ --locked --no-dev python scripts/unity/create_unitypackage.py --output .artifacts/release/local.unitypackage
uv run --project scripts/python~ --locked --no-dev python scripts/unity/stage_unitypackage.py --project-dir .artifacts/unity/local-export

lint:repo, validate:local, validate:tests:fast, validate:tests:hook-regressions, and test:agent-preflight require uv, including the metadata parity check. Outside the devcontainer, run the bootstrap and locked sync above before these developer entry points.

Image fixture generators use the locked fixtures dependency group. They keep existing .meta files byte for byte, including asset GUIDs and sprite IDs. Missing metadata is created once; competing creators preserve the first file. Pixel output remains the same on repeated runs. New metadata is published with a hard link after its temporary file closes. Unsupported filesystems report an error and leave the destination absent; failed writes do not leave a partial metadata file. Use --output-dir to generate an isolated fixture set:

uv run --project scripts/python~ --locked --no-dev --group fixtures python scripts/generate-test-sprites.py --output-dir .artifacts/sprites
uv run --project scripts/python~ --locked --no-dev --group fixtures python scripts/generate-test-textures.py --extended --output-dir .artifacts/textures

Repository lint and contract execution share scripts/check_runner.py. Existing Node entry points retain their importable interfaces and delegate process execution, concurrency, selection, and reporting to the locked Python environment. Exclusive checks finish before concurrent checks start; failed checks do not prevent the remaining checks from running. Windows uses the Bash executable from its Git for Windows installation. npm run test:check-runner exercises these contracts, including an interrupted child that exits zero. Linux checks receive separate temporary cache roots to isolate PowerShell startup profiles. The runner preserves the existing uv cache directory and removes each temporary root after its child exits, including failed checks. This prevents concurrent suites from sharing the startup profile implicated in PowerShell issue 26528. Upstream issue

A check can declare a completionPattern when exit status alone is insufficient. The native acceptance self-test requires its final completion line after cleanup as well as exit zero. Missing completion evidence fails the aggregate and preserves the captured output; it cannot count as a passing suite. This requirement does not imply that other checks have completion receipts.

Before licensed jobs start, the hosted matrix validates Standalone Direct, debugger heap and attachment selections with one typed Python entry point through locked uv. The three earlier Node commands forward CLI calls to the same policy. Run npm run test:unity-acceptance-workflow:predicates to check the workflow wiring, original decision and diagnostic digests, and actual command exit codes and streams. Invalid inputs still fail before any runner acquires a Unity license.

Seven alternating local Linux launches per mode after two warmups measured 20–24 ms for the original Node selectors and 33–39 ms through locked uv. The Node forwarding commands took 50–61 ms. These isolated timings cover selector startup. The hosted matrix already provisions uv for module validation and moves that setup before the selectors.

The WProto player and host source censuses use scripts/unity/frozen_files.py through locked uv. The PowerShell library entry points retain their names and result properties. Census walks include untracked and hidden inputs, prune only generated compiler output, and bind the Python project and lock alongside the source files. The host census also binds its Python implementation and requires the actual Git repository root. Spaces in Git root directory names are preserved. Each variant retains its own selection rules: the host scans every physical file in its four source trees, while the player filters compiler sources and also scans Unity scripts. The scans reject redirects and missing roots. They compare file identity, size and timestamps before opening, after reading and through the final path, refusing observed changes. Windows hashing permits concurrent readers while excluding writers and deletion until its handle closes. On other platforms, metadata checks cannot detect a rewrite that preserves every observed value. Keep source inputs unchanged throughout a capture on every platform. Every request reads the current bytes. A PowerShell process reuses one locked Python worker for source scans. It checks the implementation, project and lock hashes before and after each request; changes restart the worker or refuse the capture. Protocol, request and process identities must match. The worker exits when its owner's input closes, or callers can explicitly call Stop-WProtoSourceCensusWorker. Small player inventories retain their existing implementation to avoid process startup overhead. Run npm run test:frozen-files for the focused controls.

The devcontainer runs the locked sync during creation. Python 3.11.8 or newer is required; uv can provision a compatible interpreter. The environment lives under scripts/python~/.venv, separate from the documentation environment. Unity ignores that tooling folder. The release CLI still accepts --output; staging still accepts --project-dir and UNITY_VERSION, with the same safe scratch-directory restrictions. Invalid framework and module policies fail before an existing export project is removed. Archive checksums support UTF-8 output filenames.

The Markdown fence repairer also runs in typed Python:

uv run --project scripts/python~ --locked --no-dev --group documentation python scripts/fix_markdown_fence_languages.py --paths README.md

The compatible PowerShell launcher preserves its existing path arguments. It repairs only closed, unlabeled fences, preserving labeled blocks and the document's newline style. Without paths it selects staged Markdown files; it changes the worktree and does not stage the repair. The locked JSON5 parser preserves the old PowerShell reader's accepted comments and trailing commas, with explicit compatibility controls for its object and numeric rules. Frozen original-source observations cover inference and fence shapes. Run npm run test:markdown-fence-repair for the focused controls, including multi-path launcher and staged UTF-8 filename coverage. The contract registry runs this suite in CI.

All repository Python sources now belong to the strict scope, including the standard-library-only agent-state tool that runs before uv is available during container startup. The source registry also covers Python stubs. The bounded-random proof uses the locked proof group and a narrow stub for the public Z3 API it uses. Z3 comparisons return symbolic formulas; their stub return types state that behavior explicitly. Production arithmetic is parsed with a closed Python AST grammar rather than evaluated as Python code.

Agent discovery stubs are generated by typed Python through the compatible node scripts/generate-agent-skill-stubs.mjs --write entry point. --check verifies the same output without writing. Existing generated markers and stub bytes are preserved, including Unicode descriptions and the original UTF-16 length limit. Unchanged files retain their timestamps. Empty canonical inventories and linked source or output paths fail before generation; stale folders are removed only when they contain a single generated stub. Run npm run test:skill-stubs for the frozen original observations, ownership controls, and legacy-launcher check.

The production test-hook naming gate also runs in Python. It checks identifiers and explicit markers in production source, plus literal and concatenated C# emitted by generators. It is a naming check, not a semantic C# parser: references inside interpolation expressions remain outside its scope. Existing Node commands and imports remain compatibility entry points; import the Python helpers for content tests that make many calls.

The MIT-header and conditional-call checks also run in typed Python. Use npm run lint:license-headers and npm run lint:conditional-call-chains; the PowerShell entry points forward existing calls. Both checks require their source roots and a nonempty corpus, avoid linked or generated directories, and fail on unreadable input. Body checks require UTF-8; header checks also retain BOM-marked UTF-16 and UTF-32 support. Header reads stop after 20 lines and use at most eight concurrent readers; findings keep a fixed order. The conditional check masks comments and string literals, includes same-line bodies and generic calls, and rejects methods whose bodies cannot be inspected. It remains a source check by method name, with explicit external receivers; it does not replace C# semantic analysis. The Odin Undo check shares that lexer and keeps its PowerShell path selectors. Missing inputs fail; an unrelated nearby null check cannot excuse an unsafe array cast. Suppressions must be comments, not string literals. Its remaining nearby-filter recognition is a source heuristic, not proof that every Undo target is valid. npm run lint:odin-undo-safety checks drawers and npm run test:odin-undo-safety runs its focused tests. Run npm run test:csharp-lints for discovery, parser and direct/PowerShell CLI controls.

Multiline ordinary comment checks use typed Python through npm run lint:comment-block-form. The PowerShell entry point retains explicit paths, fixture roots, and -Fix; its JavaScript test entry point forwards to the same Python tests. Both use the shared C# scanner to distinguish comments from literals and XML documentation. Conversion preserves newline style and any existing UTF-8 BOM, and refuses runs containing comment delimiters. Full scans require a nonempty corpus in every owned root; missing or unreadable explicit inputs fail before any file is rewritten. Git discovery includes untracked sources and excludes ignored files and unstaged deletions. Discovered dangling links still fail validation. Run npm run test:lint-comment-block-form for the focused controls.

Region checks run as typed Python through the no-regions Repo Lint subject. The PowerShell entry point forwards -VerboseOutput, -Fix, -Paths and -StagedOnly. The shared C# scanner keeps directive-like text in multiline strings and comments intact. Repair preserves other bytes, UTF-8 BOMs and line endings. Full scans cover Runtime, Editor, Tests and Generator sources through Git's tracked and unignored inventory. Git-discovered filenames stay literal, including Unix backslashes. Staged checks read index blobs; repair is a worktree operation, so fix explicit paths and stage reviewed changes separately. CI never applies repairs. Run uv run --project scripts/python~ --locked pytest scripts/tests/test_no_regions.py -q for parser, index, path and launcher controls.

The concurrent-cache checker also runs in typed Python through npm run lint:concurrent-cache-fill. It requires Runtime, Editor and Styles source roots, ignores comments and literal text, and preserves explicit overwrite reasons. Only a plain SINGLE_THREADED guard exempts writes; compound conditions remain checked because another symbol may enable that branch in a concurrent build. Use npm run test:lint-concurrent-cache-fill for the original fixtures, parser boundaries and both CLI routes. The PowerShell entry points remain compatibility launchers.

YAML validation uses the same locked Python project through npm run lint:yaml. The PowerShell command remains a compatibility launcher with multiple-path support. The metadata dependency group installs yamllint. The runner checks tracked and untracked, nonignored YAML files without walking ignored build trees. Missing explicit inputs and invalid configuration fail visibly. --staged-only reads Git index blobs, so unstaged edits cannot hide invalid staged YAML. Warnings remain nonblocking. Run the yaml-controls contract check for source-discovery, staged-content, parser and launcher coverage.

Dependabot structure checks also use typed Python and the metadata group. Run npm run lint:dependabot and npm run test:lint-dependabot. The checker accepts multi-ecosystem groups with inherited schedules, YAML aliases and merges, and mapping keys in any order. Ordinary dependency groups may select dependency or update types without a patterns field. Duplicate keys, cyclic aliases, missing inputs and malformed shapes fail visibly. GitHub's options reference defines the ecosystem-specific options beyond these structural checks.

The lockfile pins Ruff, mypy, Pyright, pytest, and their dependencies. lint:python checks Ruff formatting and correctness rules plus both type checkers in strict mode. Function signatures must be fully annotated and explicit Any is forbidden. CI runs these checks on Linux and Windows, along with the package tests.

Local MkDocs builds and Pages deployment write .artifacts/site/. The dot directory keeps copied Unity metadata outside asset import scope. Use the default destination for local checks; building into a visible package folder can duplicate GUIDs when Unity imports the copied .meta files.

The existing scripts/generate-meta.sh entry point delegates to Python and retains --force, CRLF metadata, and importer defaults. Use npm run meta:generate -- <path> or invoke scripts/generate_meta.py through uv for a shell-independent entry point. Existing metadata is refused unless --force is explicit; a competing creation also preserves the first file. Runtime commands use --no-dev, so they do not install analysis or test packages into a fresh environment. They retain tools already installed in a shared warm environment; compatible Python may still need to be provisioned on the first run.

The documentation identifier, runtime attribute-preservation, and spelling-bucket tools also use the locked Python environment. Their npm commands invoke Python directly; the old Node and PowerShell paths remain compatibility launchers. The preservation gate includes generic reflection calls such as GetCustomAttribute<PoolPurgePolicyAttribute>(). Spelling fixes retain the first spelling of each word and the file's line endings; word insertion refuses cross-bucket duplicates before writing. Fixes leave path-only dictionaries and absent word lists unchanged. Use --config <path> when checking or updating a separate spelling configuration. Set PRESERVE_ATTRIBUTES_ROOT to check a separate runtime source tree. Diagnostics use absolute paths when that tree is on a different Windows drive from the repository. These command-line tools write UTF-8 diagnostics even when Windows pipes use a legacy encoding.

npm run lint:doc-identifiers
npm run lint:preserve-attributes
npm run lint:spelling:config
npm run lint:spelling:add -- tech-terms ExampleWord
uv run --project scripts/python~ --locked pytest scripts/tests/test_doc_identifiers.py scripts/tests/test_preserve_attributes.py scripts/tests/test_cspell_tools.py

npm run pr:feedback -- <number> uses the locked Python environment to read all four PR feedback surfaces and audit author identities. The shell entry point remains available; uv run --project scripts/python~ --locked --no-dev python scripts/pr_feedback.py <number> also works directly. Run its offline controls with --self-test, or its full regression suite with uv run --project scripts/python~ --locked pytest scripts/tests/test_pr_feedback.py. Known automation is trusted only when its exact login belongs to a Bot account. An inline alias can inherit its associated review account's canonical login only when both accounts are Bots with the same positive numeric user ID, the review ID is unique, and the inline comment belongs to the requested PR. The associated review must already have a trusted automation login. Missing or mismatched evidence keeps the alias unknown; its display name and repository association never establish trust. Unknown bots and outside people still require issue-specific direction before action. HTTP redirects fail closed to keep credentials on the GitHub API origin.

npm run verify:shipped-analyzers compares all three committed compiler-input DLLs with isolated Release builds through the same locked environment. Add :fix to refresh stale or missing payloads. A failed copy or replacement preserves the previous DLL and its importer metadata. The Node entry points remain compatibility launchers.

npm run lint:repo -- --only meta-files checks tracked asset coverage and C# importer shapes through typed Python. The PowerShell and shell test commands remain compatibility launchers. C# companions require one valid fileFormatVersion: 2, one 32-digit hexadecimal GUID, and a nonempty MonoImporter mapping with valid YAML syntax and distinct setting keys. Changed-path preflight checks metadata-only edits and validates both the working copy and any indexed companion. Validation reads at most 1 MiB per C# companion and never rewrites existing bytes or index entries. Keep customized references, execution order, and other importer settings; repair a stub by retaining its headers and adding the generated importer block. Samples retain their companions when imported into Assets; Unity-ignored tooling folders remain excluded. Metadata checks select the metadata dependency group; generation uses only Python's standard library.

The three standalone Markdown checkers under .github/scripts also join strict validation. Invoke them through the locked environment, for example:

uv run --project scripts/python~ --locked --no-dev python .github/scripts/validate_markdown_links.py docs
uv run --project scripts/python~ --locked pytest scripts/tests/test_meta_lint.py scripts/tests/test_markdown_checks.py

They retain their link policies and diagnostics. Missing inputs, empty source scans, and unreadable Markdown now fail rather than reporting an unchecked pass. These standalone checks remain separate from the repository's normal documentation lint commands.

Wiki generation and its test suite use the same locked Python project. The deployment and validation workflows provision uv before running these commands. Link text, code blocks, page names, sidebars, and footer output retain their existing contracts.

uv run --project scripts/python~ --locked pytest scripts/wiki/test_wiki_scripts.py -v
uv run --project scripts/python~ --locked --no-dev python scripts/wiki/prepare_wiki.py --source . --dest /tmp/test-wiki --verbose
npm run test:wiki-generation

New Python files must join the strict tool.pyright.include list in scripts/python~/pyproject.toml; a Git-backed inventory rejects unregistered files. The explicit legacy list records existing Python scripts still awaiting migration. Remove an entry when its script joins strict validation; do not add new scripts to that backlog.

Assembly-definition and bundled-BCL validation, the protobuf candidate builder and verifier, and the native-debugger downloader also use this locked environment. The PowerShell assembly-check entry points remain compatibility launchers; npm calls Python directly. The assembly check rejects missing source roots, empty assembly scans, invalid references and version expressions, and package defines used without a declaration in the owning assembly. File fixtures cover nested assemblies, optional package guards, case-insensitive cache exclusions, and hidden files. Unreadable C# files report their relative paths without hiding later ownership errors. JSON input is validated before using its typed values. CI runs these assembly fixtures on Linux and Windows; the Windows job exercises real hidden attributes on both files and directories.

npm run test:protobuf-candidate exercises real child-process exit, timeout, descendant cleanup, source inventory and shipped-byte checks. npm run test:native-debugger-download serves a local nested archive to check bounded range requests, hashes, sizes and destination paths. These tests do not download or execute a debugger, rebuild shipped binaries, or qualify Unity player behavior. Native fault capture requires uv on the Windows host for its locked downloader command; it keeps the existing process watchdog and retained download receipt.

The package tests check archive headers, GUIDs, checksums, repeated output, failure preservation, CLI errors, policy validation, and the real npm payload. They also inject type, lint, and formatting defects to prove each gate rejects them. Port remaining scripts incrementally while keeping their CLI contracts and executable controls.

Marked Documentation Compiler Samples

npm run lint:doc-samples extracts marked C# fences through the locked Python toolchain and compiles both runtime and Editor corpora. Use <!-- doc-sample: compiles --> before a complete runtime example, or <!-- doc-sample: compiles-editor --> for Editor-only APIs. CommonMark backtick and tilde fences are supported. Source line numbers identify the first code line. Markers inside other code blocks are data; misplaced markers, empty claimed samples and sanitized filename collisions fail before output changes.

The extractor shares the C# literal scanner with the other Python checks. It preserves literal text when hoisting using directives and classifying compilation scopes. Explicit DOC_SAMPLES_ROOT, DOC_SAMPLES_OUT and DOC_SAMPLES_REQUIRE_BOTH values retain fixture and automation support. Outputs cannot replace documentation or traverse links. Stale generated sources are removed; unrelated files in the output directory are preserved. The two legacy Node commands remain thin compatibility launchers, including the explicit Editor compiler failure control.

GitHub Credentials in the Container

The container resolves github.com credentials from a cached token. The Dev Containers credential helper is out of the path entirely: that helper raises a dialog on the host desktop on every invocation, and git push, git fetch and every API call invoke it.

With a token cached, nothing prompts. With an empty cache, git used to fall back to the editor's own askpass dialog, another window on the host desktop from a different mechanism. The container points GIT_ASKPASS at scripts/git-askpass-refuse.sh instead, so that path now ends in an error naming the commands below rather than in a dialog. (The editor's own Git UI is unaffected: the Git extension sets GIT_ASKPASS explicitly for the processes it launches.)

Supply the token once per container, either way:

npm run github:token:bootstrap   # asks the Dev Containers helper once; answer the dialog
npm run github:token:store       # paste a personal access token on stdin; no dialog at all

git push, git fetch and scripts/github-token.sh then read the same 0600 cache. A missing credential is reported with the command that fixes it, never prompted for.

Pre-installed CI/CD Tools (Container Only)

The dev container includes these additional tools that are not required on your host machine. Git hooks gracefully skip them if not present; CI will catch any issues:

  • actionlint: GitHub Actions workflow linter
  • shellcheck: Shell script linter
  • yamllint: YAML linter
  • lychee: Fast link checker

The container also installs the coding agent CLIs at startup. With npm 12, the installer allows the OpenCode and Claude install scripts by package name, then checks that each launcher responds to --version. It repairs a broken launcher even when its package is already current. Registry failures remain nonfatal and are reported in the startup log.

Required Tools (All Environments)

These tools are required and installed via npm/dotnet:

  • markdownlint: Markdown linter (via npm)
  • prettier: Markdown/JSON/YAML formatter (via npm)
  • cspell: Spell checker (via npm)
  • CSharpier: C# formatter (via .NET tools)
  • uv: Locked Python script environment and analysis tools

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
  • Workflow linting: actionlint

npm run lint:markdown checks tracked Markdown and new files that Git does not ignore, then applies .markdownlintignore. Tracked files remain eligible even when a Git ignore rule matches them. Hidden paths stay excluded, and generated, ignored local artifacts do not slow file discovery. The command fails if discovery fails or finds no eligible documents.

npm run lint:unsafe-code refuses compiler-unsafe code, unchecked memory access, disabled IL2CPP safety checks, and unbounded stack allocations. A variable stack allocation must be the direct branch of an assignment whose condition compares that length with a constant. For example, count <= Max ? stackalloc int[count] : default and count > Max ? default : stackalloc int[count] are bounded. Reversing those branches is refused. Compound conditions and intervening expressions are refused because a nearby comparison alone does not establish the bound on the path that allocates.

IL2CPP safety options must omit the value or use the exact literal true. A constant expression such as !true disables checks even though it contains that word. Named constants, compound expressions, attribute aliases and numeric option casts follow the same rule. Each scan must report both a literal-false control and a negated-true control before it can report a clean package.

Memory-access and IL2CPP option checks parse C# syntax, including Unicode escapes, invisible identifier format characters and interpolation expressions. Comments, literal text and format strings remain excluded. Every conditional branch is checked, and each source site is counted once. Aliases and static imports of Unsafe are refused because they hide member names. Size and reference-identity queries remain permitted. The positive controls require plain, escaped, formatted and interpolated calls to be found. Separate sources exercise format characters without an ordinary spelling that could mask a prefilter regression.

CSharpier 1.4 requires .NET SDK 10. The devcontainer installs SDK 10.0.403 alongside SDK 9.0.320.

Stack-allocation and memory-access checks use the existing Roslyn policy tool and require .NET SDK 9.0.320. CI installs that SDK into an isolated runner directory and verifies the selected version. A newer SDK preinstalled on the runner cannot override the declared compiler.

The compiler resolves constants and the actual length symbol; parameters, locals, readonly fields and properties cannot borrow an unrelated constant's name. Constant expressions and shared constants remain supported. The scan covers conditional branches and follows the declarations and base types used by a bound to include their conditional symbols. Unresolved bounds fail validation. Compiler contexts are cached only within one source snapshot, with at most eight cached contexts; concurrent commands build into separate temporary output folders.

To scan another package checkout with the current tool, pass --root /path/to/checkout. Report paths are relative to that checkout regardless of argument order. The checkout must contain the normal required source trees, runtime assembly definition and check projects.

During linter development, npm run test:lint-unsafe-code -- --filter "semantic binding" selects matching controls without running the full corpus. The summary reports the unselected count, and an empty selection fails. Run the unfiltered suite before publication.

Use npm run lint:unsafe-code -- --sarif artifacts/unsafe-code.sarif to retain a SARIF 2.1.0 report. Repo Lint retains the same report as the unsafe-code-sarif artifact. Findings use the unsafe-code rule, repository-relative URI paths and deterministic fingerprints. Every finding fails the gate; there is no exception baseline. Reports include per-tree source and assembly counts plus positive-control results. Missing required subjects, discovery/read errors and report write failures fail validation; an execution failure cannot be mistaken for a clean result list.

Python Tooling

Use Python 3.11.8 or newer for the repository's Python checks. The dev container pins uv==0.13.8 and exposes it as uv. Documentation CI installs that same version with pip, then installs the fully pinned requirements-docs.lock with uv. requirements-docs.txt lists the direct constraints; the lock records their transitive versions. Run locally with:

uv venv .venv --python '>=3.11.8,<3.12'
uv pip install --python .venv/bin/python -r requirements-docs.lock
.venv/bin/mkdocs build --strict
Python path Dependency source Installer and cache Invocation
Documentation validation and Pages deployment requirements-docs.lock from requirements-docs.txt Pinned uv; setup-python caches the pip bootstrap wheel mkdocs build --strict
Wiki validation and generation scripts/python~/uv.lock Pinned uv; the shared project installs test tools only for tests uv run --project scripts/python~ --locked pytest scripts/wiki/test_wiki_scripts.py -v; generation uses --no-dev
Local Gates bounded-random proof scripts/python~/uv.lock locked uv environment uv run --project scripts/python~ --locked --no-dev --group proof python scripts/random-quality/verify-bounded-sampling.py
Dev container image .devcontainer/requirements-tools.txt Pinned uv installs yamllint and pinned MCP tools; pip bootstraps uv Tools run from the image, not during hooks
Optional local hooks and Unity/result helpers No Python packages installed by hooks Existing interpreter or optional yamllint tool Hooks call yamllint when available; helper scripts call python3

Release, metadata, binary-check, feedback, wiki, changelog, XML-summary, and README mirror commands use the shared locked uv project. The asset fixture generators use its fixtures group, and the bounded-random proof uses its proof group. Every Python source is in strict scope; PowerShell, Bash, JavaScript, and inline workflow implementations still need migration. The old requirements-wiki.in and requirements-wiki.txt remain compatibility inputs for existing standalone environments; current wiki CI uses the shared uv lock.

npm run sync:readme-mirror generates the documentation front page from the root README with readme_mirror.py. npm run lint:readme-mirror checks it without writing. Both use locked Python and the shared documentation parser; the historical Node commands remain compatibility launchers. Prettier still formats the generated Markdown. Cross-document fragments map from the target headings; source prose and fenced examples retain their content. Missing or empty sources, unsafe output links, and formatter errors fail the command. Successful writes replace the complete mirror atomically. The port evidence retains the original corpus, native Windows checks and paired startup captures. Startup remains slower than the original Node command; the port makes no startup performance claim. The archive records the initial 64-case source snapshot. Later fixes also reject missing documentation assets and preserve inline-code link examples; their current regressions remain in the source suite. Historical captures keep their recorded identities.

npm run check:reference-upstream-drift checks the pinned sort and random source hashes through locked typed Python. --manifest and --report retain the historical CLI and JSON report shape; the Node entry points remain compatibility launchers. Downloads use a 30-second timeout and a 16 MiB source limit. Source and redirect URLs stay on raw.githubusercontent.com over HTTPS. The checker rejects missing local files, paths escaping the repository, duplicate names, and empty coverage. Its tests replay frozen reports captured from the original JavaScript, plus manifest, URL, download, failure, and launcher controls. These checks do not update local source adaptations or their pinned hashes.

The code-fence syntax validator and its regression suite also run through locked typed Python. The historical shell entry points remain compatibility launchers. The validator retains its comma-attribute rules, source locations, scan counts and failure exits. Seven original-executable corpora freeze its output. Pure parser controls cover fence lengths, indentation, nested paths, multiple findings and physical line endings; the suite also invokes both shell launchers.

Six pure singleton policy tests avoid asset setup and refresh while integration cases retain their cleanup. See the fixture measurements.

Earlier installer comparisons measured the bootstrap costs. On Python 3.11, fresh environments with separate cold and warm caches gave documentation installs of 8.66/5.90 seconds with pip and 5.42/0.15 seconds with uv. Pytest took 1.26/0.85 seconds with pip and 0.35/0.04 seconds with uv; Z3 took 2.94/0.76 seconds with pip and 2.20/0.04 seconds with uv. Bootstrapping pinned uv itself with pip took another 3.57/0.99 seconds. Wiki CI and the bounded-random proof now use the shared uv project; these historical install measurements do not describe its current end-to-end runtime.

To update Python dependencies, edit the direct constraints, then regenerate the locks with the pinned uv version:

uv lock --project scripts/python~
uv pip compile --universal --python-version 3.11.8 requirements-docs.txt --output-file requirements-docs.lock
uv pip compile --universal --python-version 3.11 requirements-wiki.in --output-file requirements-wiki.txt

Review the lock diff, install into a fresh Python 3.11.8 or newer environment, run the strict MkDocs build and wiki tests, and keep the CI uv pin aligned with .devcontainer/Dockerfile. The single Z3 requirement and container tooling requirements are exact pins; update those and their checks together. The pip install commands that bootstrap uv are deliberate because uv cannot install itself into an otherwise empty runner or container.

LLM Scratch Artifacts

  • Files or folders starting with _llm_ are git-ignored and automatically removed from the Unity package during imports.
  • Keep temporary AI outputs outside the package root (or rename them) to avoid unexpected deletions by the asset cleaner.

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

For browser correctness checks, scripts/unity/run-browser-consumer.py builds an isolated WebGL consumer and runs retained-map, enum, RNG, and spatial-query cases in Chromium. It requires an installed Unity Editor with WebGL support and Playwright. The runner uses Release IL2CPP, High stripping, and SINGLE_THREADED; it checks exact golden bytes and rejects corrupt-byte and stale-source controls. Install its matching Chromium and view the editor, browser, and artifact path options with:

uv run --project scripts/python~ --locked --group browser playwright install chromium
uv run --project scripts/python~ --locked --group browser python scripts/unity/browser_consumer.py --help

Use --browser-executable to select an existing browser instead. This manual check does not replace the supported Unity CI matrix or provide performance measurements. The browser runner and its tests use the shared locked Python toolchain; the former hyphenated entry point remains a compatibility launcher.

  • Install tools once:
    • npm install --no-audit --no-fund (the generated root lockfile stays ignored)
    • dotnet tool restore
    • npm run hooks:install: installs git hooks. The install script also configures push.autoSetupRemote=true and push.default=simple locally, so git push on a new branch sets tracking automatically.
  • Verify all tools: npm run verify:tools
  • Format C#: dotnet tool run csharpier format
  • Check member ordering: npm run lint:nested-type-placement. Tuple return types, including tuples inside generic return types, keep methods in their method tier. Tuple fields and properties keep their field or property tier; initializer calls do not turn them into methods.
  • Check docs/JSON/YAML: npm run validate:content
  • Run the complete contract suite: npm run validate:tests. Hook regressions share the bounded worker pool with the fast checks; any check that mutates the repository runs exclusively first. npm run validate:tests:fast keeps its smaller scope, and npm run validate:tests:hook-regressions remains available for hook changes. To select a hook check in the full runner, use node scripts/run-contract-tests.js --include-hook-regressions --only agent-preflight.
  • Run changed-file checks with npm run agent:preflight (or agent:preflight:fix). Select paths with -Paths first/path second/path, or use -PathList list.txt for a file containing one path per line or separated by NUL characters. Relative list filenames resolve from the repository root. Missing, directory and unreadable list inputs fail before any mutation, including with -Fix. An empty readable list selects no files. Unsupported options such as --files fail before any mutation. Trailing paths require -Paths; prefix filenames starting with a hyphen with ./, or use an absolute path. With no path arguments, preflight checks the changed-file set. A failed required Git query stops preflight with Git's status and diagnostic. Initial index queries run before any fixes. Explicit selections use literal Git path scopes for their safety checks and known generated outputs. Read-only C# metadata validation also follows selected staged rename destinations to their former companion paths; formatter targets and write scope remain unchanged. Fixes must resolve inside the repository; linked targets keep partial-staging protection. A linked destination that resolves to the repository root is refused before tools start. Changed destinations outside the checked scope and hard links with unknown destinations fail before writing. Metadata recovery checks every staged source and its parent/file companions, including sources outside the selected validation list. With no explicit selection, discovery still covers the whole repository.
  • Enforce EOL/encoding: npm run eol:check
  • Lint GitHub Actions: actionlint
  • Verify Markdown/code links: npm run lint:doc-links (locked uv Python)
    • The wrapper lives at scripts/run-doc-link-lint.js so you can also run node ./scripts/run-doc-link-lint.js --verbose if you are not using npm scripts.
    • The Python checker validates intra-repo Markdown links and docs/... references inside source files or scripts. Repo Lint runs it on every PR, so run it locally before pushing large doc updates.

Thread allocation observations

Package tests use Tests.Core.ThreadAllocationCounter for per-thread allocation measurements. It excludes the raw GC counter call from IL2CPP player compilation: the installed Unity 6000.6.7f1 implementation still invokes an unimplemented icall and returns zero. A newer Unity version alone does not qualify that backend. Mono and .NET must observe a retained 4096-byte allocation before the shared counter becomes available. An unavailable counter skips allocation observations; WProto budget fixtures retain separate functional cases. Unity profiler-recorder and native-profiler controls remain independent instruments. Editor and standalone-player launches save *.execution-diagnostics.json beside their logs. Check raw process exits and both output stream ends alongside NUnit results when qualifying a backend.

Style and Naming

Please follow the conventions outlined in .editorconfig and the repository guidelines (PascalCase types, camelCase fields, explicit types, braces required, no regions).

Releases and Versioning

This project follows Semantic Versioning. Key points:

  • Git tags use the format 3.1.5 (no v prefix)
  • package.json contains the authoritative version number
  • SVG banner displays the version with a v prefix (e.g., v3.1.5) for visual consistency, synced automatically via pre-commit hook

When installing via Git URL, reference versions without the v prefix:

https://github.com/wallstop/unity-helpers.git#3.1.5

Maintainers can dispatch Unity Benchmarks to validate the licensed benchmark lifecycle. The weekly hosted scheduler dispatches it on protected main. Both workflows must be enabled in the repository. Branch dispatches retain diagnostics without updating the canonical performance baseline.

Maintainers prepare releases from the default branch with the Release Prepare workflow. Choose a major, minor, or patch bump, review the generated release PR, and squash-merge it with the default release: X.Y.Z title. Auto publish is enabled by default. After the merged commit passes Unity Tests, Local Gates, Repo Lint, and every other triggered push validation workflow, automation starts Release Publish with that exact commit. It validates and packs npm, creates the .unitypackage without opening Unity, creates the release tag when needed, and publishes npm and GitHub Release assets.

Clear Auto publish during preparation to publish manually. In Release Publish, choose a branch, tag, or commit with source_ref; leave version blank to read it from that source's package.json. Export only validates and produces downloadable archives without changing tags or publishing. Automatic publication never moves an existing tag. A failed validation or prior publication attempt requires inspection and manual recovery; duplicate completion events do not dispatch the same release twice. Remove <!-- unity-helpers:auto-publish --> from an unmerged release PR to cancel its automatic publication.

Before dispatch, automation atomically creates the internal release-publish-claims/X.Y.Z tag at the validated commit. This retained claim prevents duplicate dispatch even before GitHub lists the publication run. A lost response or interrupted publisher leaves the claim in place: inspect the publication history, then use Release Publish manually with the claimed source commit. Every main validation workflow uses a separate concurrency group for each pushed commit; newer pull-request revisions still cancel older pull-request runs. Documentation deployment, issue-template synchronization and devcontainer publication have separate recovery paths and do not validate release archives, so their pending or superseded runs do not block publication.

Rebuild bundled serialization dependencies

These are maintainer steps for changing the shipped assemblies, not package-installation steps. The assembly conflict guide explains consumer diagnosis.

uv run --project scripts/python~ --locked --no-dev python scripts/build-protobuf-candidate.py --output /tmp/protobuf-candidate
uv run --project scripts/python~ --locked --no-dev python scripts/verify-protobuf-shipped.py --candidate-root /tmp/protobuf-candidate/assemblies

The retained candidate builder requires SDK 9.0.319 and produces isolated binaries with a source-bound build receipt. Repository validation uses SDK 9.0.320; install the older SDK separately when rebuilding that retained candidate. The independent current lane uses ProtobufNetOracle=candidate and ProtobufNetCandidateRoot=/tmp/protobuf-candidate/assemblies. Frozen v2/v3 lanes retain their original DLLs under Generator~; dependency upgrades must not refresh those historical oracles. The retained Dox consumer suite exercises the frozen v3 and current builds.

Keep the Unity-version constraints, importer GUIDs and assembly ownership policy when rebuilding. npm run lint:bundled-assemblies checks the Runtime/Binaries/ constraints and absence rules. It does not inventory the separate protobuf dependency directory. Preserve the documented source and binary hashes when updating provenance.

A .NET Standard target and passing host tests do not establish Unity assembly ownership or backend health. The complete supported-version, stripped IL2CPP, WebGL and native process qualification remains tracked in the dependency qualification issue.

Documentation environment

Use Python 3.11.8 or later within the 3.11 series for the documentation lock. An older existing environment may build successfully with stale plugins while failing to install the current lock. Create a supported environment and sync requirements-docs.lock before running mkdocs build --strict; the repository's documentation CI uses that lock.

Pinned build-lock input checks

npm run test:build-lock-action-inputs runs the typed Python validator against BUILD_LOCK_POLICY_ROOT, a full-history checkout of the central policy repository. Every call is checked against its own pinned action definition. The validator refuses missing required inputs, unknown supplied inputs, unreadable pins and zero-call scans. A missing policy checkout is an explicit local skip and a failure under GitHub Actions.

The Node entry points remain compatibility launchers, including the exported pin resolver. The resolver reads live uses: lines and refuses absent, conflicting or non-commit references. Its twelve original observations accompany twelve parser observations captured after the earlier seventeen parser assertions passed. Additional controls create real local Git commits to check different pinned contracts, declaration caching, missing history, output bounds, timeouts and full CLI execution. The checker reads local Git objects and does not fetch or modify either checkout. Git reads discard inherited GIT_* overrides and disable replacement objects so a pinned definition refers to its physical commit. Controls exercise both environment redirection and a real replacement object. Python and uv setup precede the workflow step that resolves the policy checkout pin.

Compiler gate controls

npm run typecheck:controls runs the typed Python control runner through the locked toolchain. The five real build projects must report the exact expected compiler or analyzer diagnostics; missing anchors, extra diagnostics and an empty or unassigned project group fail the gate. Runtime and integration controls share a serial lane. At most two local groups run at once; CI can use -- --jobs=1. Only the known NuGet migration startup collision receives one retry.

npm run test:typecheck-controls checks the frozen observations from the original Node runner, including 200 diagnostic verdicts, argument handling, rendered source bodies and SDK setup guards. Additional controls cover subprocess bytes, retry bounds and group scheduling. These controls supplement the real negative builds; they do not replace them. The Node entry points remain compatibility launchers.

The equality witness is now readonly so it targets missing equality without also triggering an unrelated readonly diagnostic. Its original source remains in the frozen fixture. Unknown coded or code-less build errors fail even when every expected diagnostic is present. The excluded-source control recognizes its audit wrapper only after a complete reporting-control summary with exactly the expected findings, the named audit command, and exit code one. Missing or fatal audit reports, other commands and other exit codes fail.

The launcher and compiler-control qualification record lists capture outcomes, source hashes and selected log hashes. Frozen original observations and control sources live under scripts/; raw logs and original executables remain in ignored progress/. The uv 0.13.8 Windows runs cover 346 passing controls, including malformed paths and metadata access failures, plus strict analysis over 143 Python sources with UTF-8 mode disabled. Earlier failed captures remain identified in the record. No timing improvement is claimed for these ports.

Idle Editor fixtures

The Unity CI runner gives idle-only editor fixtures a fresh process before compilation and ruleset-writing tests. On Unity 6, BuildProfileSceneSyncTests uses IdleEditorIsolation; the main phase excludes that category, and the result verifier requires the separate fixture's passing results. Ruleset imports can leave compilation pending until the current Test Runner invocation completes, so waiting inside a later test cannot make that process idle.

Use SanitizePath() or PathHelper.Sanitize for separator normalization in Runtime, Editor, Tests and Generator~, and reuse the result when checking multiple paths. npm run lint:path-normalization enforces the rule and npm run test:lint-path-normalization checks reporting and empty-scope rejection. The shared helper implementation is the only exception within those trees; standalone Generator tools link the same Unity-free helper source.

Wiki publication

The wiki deployment uses the existing auto-commit GitHub App through AUTO_COMMIT_APP_ID and AUTO_COMMIT_APP_PRIVATE_KEY, requesting only its existing repository contents write capability. The workflow token reads source; it does not authenticate wiki writes. Checkout does not persist credentials, and wiki Git authentication is supplied through process environment configuration rather than a credential-bearing remote URL.

A missing credential fails before cloning. A receive-access dry run precedes content generation; public clone success alone does not prove write access. Generation and content validation remain mandatory. Publication pushes only the detected branch once and verifies its remote revision against the generated commit. The summary reports failures before considering dry-run or no-change states. Run the publication controls with uv run --project scripts/python~ --locked pytest scripts/wiki/test_wiki_scripts.py -q.

If the App is denied wiki access, inspect its existing installation and this repository's access to the two secrets. Do not retry alternate branches or widen permissions. Record the denied run and the exact owner action required before attempting publication again. A workflow dry run checks receive access and validates generated content without publishing it.

📚 Documentation

Getting Started

Inspector Features

Effects System

Relational Components

Serialization

Spatial Trees

Logging

Utilities

Editor Tools

Guides

Performance

Project

Clone this wiki locally