Build and validation
Build truth
A successful LocalGPT build is the primary compilation truth. Delimiter counts, regex scans, JSON/XML parsing, IDE inspection, or screenshots cannot replace it.
The repository pins its SDK through global.json and provides validation scripts for architecture and policy. When .NET is unavailable, those scripts can still provide partial evidence, but the result must be labeled uncompiled.
Architecture and source-validation maintenance uses only build-wired PowerShell scripts compatible with Windows PowerShell 5.1 and modern pwsh. The repository does not maintain a parallel Python test suite; application runtime Python is separate. Source checks derive the current project version and embedded-resource inventory from the .csproj file. Release bumps must not require hand-editing static test expectations or introducing version-named test files.
Validation sequence
A normal maintenance pass should run, as applicable:
- source formatting and encoding checks;
- JSON/YAML/XML parsing;
- C# syntax parsing through the pinned SDK/Roslyn route;
- architecture assertions;
- dependency and publish-configuration checks;
- localization and JavaScript diagnostics checks;
- database migration/snapshot checks;
- application build/tests;
- documentation build and artifact verification;
- focused browser smoke tests.
Generated C#
Generated source must preserve namespaces, nullable context, project references, service lifetimes, and existing framework patterns. It must not report compilation success until the target project has actually compiled.
Warnings are triaged by category. Suppression is not the default response to a warning introduced by generated code.
Static and runtime ownership
Application-owned mutable catalogs, regex lists, runtime values, and policy state are not static. Framework bootstrap and pure immutable helpers remain valid static boundaries.
Runtime-value services own mutable definitions and current values. Persistence services own durable policy. Components consume services rather than constructing global state.
Logging integrity
Logs contain technical context needed for diagnosis but avoid prompts, full model responses, uploads, generated file contents, credentials, secrets, and unbounded exception data.
The database logger exposes readiness so startup failures do not recurse. User notifications are sanitized; detailed traces remain in the configured logger.
JavaScript diagnostics
Maintained JavaScript functions used through interop are registered and validated. Build checks detect missing function names and known unsafe patterns. Browser tests cover theme selection, documentation dropdown behavior, fullscreen/close flows, and critical navigation.
Frontend checks
Important checks include:
- interactive render-mode ownership;
- no nested incompatible render boundaries;
- responsive dialogs and scroll ownership;
- keyboard focus and visible labels;
- clickable menus above decorative layers;
- reduced-motion behavior;
- light/dark contrast;
- no fake or dead controls.
Documentation checks
The documentation build verifies conceptual pages, generated API YAML/HTML, versioned PDF, Kawaii CSS/JS markers, icon assets, status JSON, and nonzero source/API counts.
DocFX-only reflection dependencies are isolated in docs/DocfxDependencies.csproj; they are restored and staged into the temporary documentation probe directory and do not become LocalGPT runtime package references. Unresolved assembly metadata is a hard failure before PDF generation.
Cross-platform release/local-development prerequisites validate the DevExpress license location and provide a compatible Node.js 20–22 runtime for documentation tooling on Windows, macOS, and Linux.
Windows Debug/Release builds use repository-owned PowerShell validation and packaging scripts to validate and seed the version-matched GitHub Pages snapshot from the documentation output of that exact build.
The Pages extractor accepts UTF-8 files with or without BOM, normalizes ZIP separators, rejects unsafe paths, and chooses the strongest complete release candidate.
Repository-owned packaging helper: one-command execution contract
Build-Release.ps1 and Build-LocalDevelopment.ps1 both call build/Ensure-ReleasePackagingPackage.ps1. The helper must automatically create or repair its distributable NuGet package and verify the original PDFsharp MIT and third-party notice bytes (SHA-256), without requiring the operator to invoke a separate command.
The build runs the framework-dependent host executable published from the local project source, not a second NuGet tool installation into artifacts/release-tools/.store/.stage. This avoids relying on NuGet tool extraction permissions on external macOS build volumes, while retaining the NuGet package as a separately verified release deliverable. The exact capability pdf-merge-input-list is checked against the published executable before starting expensive documentation. A publish or capability failure stops the build rather than silently dropping PDF functionality.
sequenceDiagram
participant Entry as Release / Local Development
participant Ensure as Ensure-ReleasePackagingPackage
participant NuGet as Local .nupkg
participant SDK as .NET publish
participant Helper as Published apphost
Entry->>Ensure: Prepare helper (one command)
Ensure->>NuGet: Build or repair if required
Ensure->>NuGet: Verify license hashes
Ensure->>SDK: Publish project executable
SDK-->>Ensure: Local apphost path
Ensure->>Helper: capabilities
Helper-->>Ensure: pdf-merge-input-list
Ensure-->>Entry: Verified executable path
Entry->>Helper: Documentation PDF / native packaging
The locally packed NuGet artifact is validated for included license contents; installation of that artifact by unrelated dotnet tool install consumers is not established by the direct-apphost smoke check and must be tested separately before claiming package-installability.
Release preflight: static source assets and text-service ownership (6.0.6)
Normal pwsh ./Build-Release.ps1 now executes the existing text-service ownership
and static-web-asset guards before clearing repository bin/obj, preflighting
signing, or building the RID-neutral assembly. Both guards remain in
Directory.Build.targets for Visual Studio Debug and the CLI build. A failure
cannot be bypassed by choosing a different entrypoint.
The text-service guard has a locally initialized, intentionally empty reviewed exception set and self-checks that direct splitting, regex replacement, joining, and comparison are still detected. New UI/controller text manipulation belongs in injected services; no new exception baseline was introduced.
The static-asset guard enumerates all image and named web assets declared by
LocalGPT.csproj plus the critical runtime files, then verifies that each
file exists. It also enforces four Council evidence popup CSS contracts. If
an asset or CSS contract is absent, it prints the exact source-relative path
or selector before failing. Missing original UI files must be restored;
removing the guard or the project references is not a repair.
The repository's scratch-image exclusion is now anchored at /images/. The
previous unanchored images/ entry matched the authored
src/LocalGPT/wwwroot/images/ tree and could prevent those source assets from
entering Git. Files already missing from an existing Git checkout must be
restored from authoritative source and committed as appropriate; an ignore
rule change alone does not create missing Git objects. A clean git status
does not prove that ignored files are present or tracked.
sequenceDiagram
participant Release as Build-Release.ps1
participant Text as Text-service ownership guard
participant Assets as Static-web-asset guard
participant SDK as dotnet build / MSBuild
Release->>Text: Validate UI/controller service ownership
Text-->>Release: Pass or fail with direct-operation details
Release->>Assets: Validate required assets and CSS contracts
Assets-->>Release: Pass or fail with missing source paths
Release->>SDK: Compile and preserve MSBuild guard checks
SDK->>Text: Run mandatory ownership validation again
SDK->>Assets: Run mandatory static asset validation again