diff --git a/.build/just/bump-version.ts b/.build/just/bump-version.ts new file mode 100644 index 0000000..8cb38ff --- /dev/null +++ b/.build/just/bump-version.ts @@ -0,0 +1,62 @@ +// Bumps one part of the semantic version in package.json, for `just bump `. +// +// The parts after the one bumped are reset to 0, and a pre-release or build suffix is dropped: +// +// 2.0.1 major -> 3.0.0 minor -> 2.1.0 patch -> 2.0.2 +// 2.1.0-rc.1 patch -> 2.1.1 +// +// Only the "version" value is rewritten, in place, so the file keeps its own indentation, key order +// and line endings - re-serialising the JSON would reformat it. +// +// bun bump-version.ts [package.json] [--dry-run] + +import { readFileSync, writeFileSync } from "node:fs"; + +const parts = ["major", "minor", "patch"] as const; +type Part = (typeof parts)[number]; + +const args = process.argv.slice(2); +const dryRun = args.includes("--dry-run"); +const [part, file = "package.json"] = args.filter((arg) => arg !== "--dry-run"); + +if (!parts.includes(part as Part)) { + console.error(`Expected one of ${parts.join(", ")}, not '${part ?? ""}'.`); + process.exit(1); +} + +const text = readFileSync(file, "utf8"); +const versionPattern = /("version"\s*:\s*")([^"]*)(")/; +const match = versionPattern.exec(text); +if (!match) { + console.error(`No "version" field in ${file}.`); + process.exit(1); +} + +const current = match[2]; +const semver = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(current); +if (!semver) { + console.error(`'${current}' in ${file} is not a major.minor.patch version.`); + process.exit(1); +} + +let [major, minor, patch] = semver.slice(1, 4).map(Number); +switch (part as Part) { + case "major": + [major, minor, patch] = [major + 1, 0, 0]; + break; + case "minor": + [minor, patch] = [minor + 1, 0]; + break; + case "patch": + patch += 1; + break; +} + +const next = `${major}.${minor}.${patch}`; +if (dryRun) { + console.log(` ${file}: ${current} -> ${next} (dry run, nothing written)`); + process.exit(0); +} + +writeFileSync(file, text.replace(versionPattern, `$1${next}$3`)); +console.log(` ${file}: ${current} -> ${next}`); diff --git a/.build/just/dotnet.just b/.build/just/dotnet.just new file mode 100644 index 0000000..9507263 --- /dev/null +++ b/.build/just/dotnet.just @@ -0,0 +1,53 @@ +# .NET recipes: tools, restore, build, clean, test and pack, all against one solution. +# +# Override these in the root Justfile. `solution_file` is the one nearly every repository sets; "." +# lets dotnet find the single solution or project in the repository root. + +solution_file := "." +build_configuration := "Debug" +artifacts_folder := "./artifacts" + +# Every test. A TUnit/MTP tree-node filter: /assembly/namespace/class/test. +test_filter := "/*/*/*/*/" + +# Restore the repository's .NET local tools (.config/dotnet-tools.json) +[group('Build and Test')] +ensure-tools: + dotnet tool restore + +# Restore NuGet packages for the solution +[group('Build and Test')] +restore *args: + echo "==> Restoring {{ BLUE }}{{ solution_file }}{{ NORMAL }}" + dotnet restore "{{ solution_file }}" {{ args }} + +# Build the solution with build_configuration (default: Debug) +[group('Build and Test')] +build *args: + echo "==> Building {{ BLUE }}{{ solution_file }}{{ NORMAL }} ({{ GREEN }}{{ current_version }}{{ NORMAL }}) with configuration {{ YELLOW }}{{ build_configuration }}{{ NORMAL }}" + dotnet build "{{ solution_file }}" --configuration "{{ build_configuration }}" {{ args }} + +# Clean the solution with build_configuration (default: Debug) +[group('Build and Test')] +clean *args: + echo "==> Cleaning {{ BLUE }}{{ solution_file }}{{ NORMAL }} with configuration {{ YELLOW }}{{ build_configuration }}{{ NORMAL }}" + dotnet clean "{{ solution_file }}" --configuration "{{ build_configuration }}" {{ args }} + +# Run the tests matching a tree-node filter (default: every test) +# +# just test "/*/*/*/*[Category=Unit]" +# just test "/*/*/ProjectHarnessTests/*" +# +# Exit code 8 - "no test ran" - is ignored, so a filter that matches nothing in one test project does +# not fail the run for the others. +[doc('Run the tests matching a tree-node filter (default: every test)')] +[group('Build and Test')] +test filter=test_filter *args: + echo "==> Testing {{ BLUE }}{{ solution_file }}{{ NORMAL }} ({{ YELLOW }}{{ build_configuration }}{{ NORMAL }}) with filter {{ GREEN }}{{ filter }}{{ NORMAL }}" + dotnet test --project "{{ solution_file }}" --configuration "{{ build_configuration }}" --treenode-filter "{{ filter }}" --ignore-exit-code 8 {{ args }} + +# Pack every packable project into artifacts_folder (default: ./artifacts) +[group('Build and Test')] +pack artifact_folder=artifacts_folder *args: + echo "==> Packing {{ BLUE }}{{ solution_file }}{{ NORMAL }} ({{ GREEN }}{{ current_version }}{{ NORMAL }}) to {{ YELLOW }}{{ artifact_folder }}{{ NORMAL }}" + dotnet pack "{{ solution_file }}" --configuration "{{ build_configuration }}" --output "{{ artifact_folder }}" {{ args }} diff --git a/.build/just/env.just b/.build/just/env.just new file mode 100644 index 0000000..6156f34 --- /dev/null +++ b/.build/just/env.just @@ -0,0 +1,56 @@ +# The environment every recipe runs in: telemetry opt-outs, and the .NET CLI speed-ups. +# +# `export` hands each value to every process a recipe starts - dotnet, bun, pwsh, git. Each one is a +# default: `env(NAME, value)` keeps whatever the caller's environment already says, so a developer +# who has opted back in, or a CI job that sets its own value, is never overridden. + +# -- Telemetry and tracking -------------------------------------------------------------------------- + +# The .NET CLI, MSBuild and Aspire. +export DOTNET_CLI_TELEMETRY_OPTOUT := env("DOTNET_CLI_TELEMETRY_OPTOUT", "1") +export MSBUILD_TELEMETRY_OPTOUT := env("MSBUILD_TELEMETRY_OPTOUT", "1") +export ASPIRE_CLI_TELEMETRY_OPTOUT := env("ASPIRE_CLI_TELEMETRY_OPTOUT", "true") +export ASPIRE_DASHBOARD_TELEMETRY_OPTOUT := env("ASPIRE_DASHBOARD_TELEMETRY_OPTOUT", "true") + +# The Azure SDKs and the Azure MCP server. +export AZURE_CORE_COLLECT_TELEMETRY := env("AZURE_CORE_COLLECT_TELEMETRY", "0") +export AZURE_MCP_COLLECT_TELEMETRY := env("AZURE_MCP_COLLECT_TELEMETRY", "0") + +# PowerShell, for scripts a recipe runs through pwsh, and Git Credential Manager. +export POWERSHELL_TELEMETRY_OPTOUT := env("POWERSHELL_TELEMETRY_OPTOUT", "1") +export GCM_TELEMETRY_OPTOUT := env("GCM_TELEMETRY_OPTOUT", "1") + +# JavaScript tooling: Next.js, Astro, Yarn, and the funding banners printed by postinstall scripts. +export NEXT_TELEMETRY_DISABLED := env("NEXT_TELEMETRY_DISABLED", "1") +export ASTRO_TELEMETRY_DISABLED := env("ASTRO_TELEMETRY_DISABLED", "1") +export YARN_ENABLE_TELEMETRY := env("YARN_ENABLE_TELEMETRY", "0") +export DISABLE_OPENCOLLECTIVE := env("DISABLE_OPENCOLLECTIVE", "true") + +# Claude Code, when a recipe launches it. +export CLAUDE_CLI_TELEMETRY_OPTOUT := env("CLAUDE_CLI_TELEMETRY_OPTOUT", "1") +export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC := env("CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC", "1") +export DISABLE_ERROR_REPORTING := env("DISABLE_ERROR_REPORTING", "1") +export DISABLE_TELEMETRY := env("DISABLE_TELEMETRY", "1") + +# The cross-tool conventions, honoured by Bun and many other CLIs. +export DO_NOT_TRACK := env("DO_NOT_TRACK", "1") +export TELEMETRY_DISABLED := env("TELEMETRY_DISABLED", "1") + +# -- .NET CLI speed and noise ------------------------------------------------------------------------ + +# No welcome banner or first-run notice. +export DOTNET_NOLOGO := env("DOTNET_NOLOGO", "1") + +# The NativeAOT CLI host (.NET 11): near-instant `dotnet --version`, `--help` and tool launches, with +# everything else falling back to the managed CLI. On by default; opt out with DOTNET_CLI_ENABLEAOT=false. +export DOTNET_CLI_ENABLEAOT := env("DOTNET_CLI_ENABLEAOT", "true") + +# The MSBuild server (DOTNET_CLI_USE_MSBUILD_SERVER) is deliberately left to the SDK's own default. +# Forcing it on makes every `dotnet build` share one long-lived MSBuild process, and its NuGet SDK +# resolver keeps the settings it first read: a build under a different nuget.config - a test +# harness's throwaway consumer, a second repository - then resolves SDKs with the wrong sources and +# fallback folders, and fails with MSB4242. Set it yourself where every build shares one NuGet +# configuration; `just scrub` shuts the server down. + +# Multithreaded MSBuild (-mt) is deliberately not set here. Purview.BuildSdk bootstraps it into the +# repository's Directory.Build.rsp, so a plain `dotnet build` and an IDE build get it as well. diff --git a/.build/just/index.just b/.build/just/index.just new file mode 100644 index 0000000..1d73bbe --- /dev/null +++ b/.build/just/index.just @@ -0,0 +1,41 @@ +# The barrel for the shared just modules. The root Justfile imports this file, and nothing else: +# +# set allow-duplicate-variables +# set allow-duplicate-recipes +# +# import ".build/just/index.just" +# +# Every module gives its variables a default. The root Justfile overrides one by defining the same +# name - `solution_file := "src/Acme.slnx"` - and overrides a no-op hook such as `_after-bump` the +# same way. Both settings are what let a root definition win; without them a duplicate is an error. +# +# The required modules are imported unconditionally. The optional ones use `import?`, so a module is +# switched on by copying its file into this folder and off by deleting it: this file never changes. +# +# These files are copied verbatim from the purview-buildsdk-justfile skill. Change a recipe there, +# not here, and put anything specific to one repository in its root Justfile. + +# Telemetry opt-outs and the .NET CLI speed-ups, exported to every recipe. +import "env.just" + +# version, bump +import "version.just" + +# ensure-tools, restore, build, clean, test, pack +import "dotnet.just" + +# lint-check, lint-fix, vs, scrub +import "utilities.just" + +# pipeline-pr, pipeline-build, pipeline-tests - local runs of the Purview.Build pipeline +import "purview-build.just" + +# skills-* - the Purview.BuildSdk agent-skill targets +import "skills.just" + +# Optional. pipeline-pack-validate, pipeline-local-release, pipeline-release - for a repository that +# packs NuGet packages. +import? "purview-build-nuget.just" + +# Optional. docs, docs-install, docs-check - for a pm-docs-site project site (purview-dev/pm-skills). +import? "docs.just" diff --git a/.build/just/purview-build-nuget.just b/.build/just/purview-build-nuget.just new file mode 100644 index 0000000..2154876 --- /dev/null +++ b/.build/just/purview-build-nuget.just @@ -0,0 +1,30 @@ +# Optional: Purview.Build pipeline runs that pack, validate and publish NuGet packages. Copy this file +# into the module folder only when the repository packs packages; the barrel imports it if present. +# +# Pack validation reads PackValidation in .config/purview-build.json. Its RequiredContent lists every +# file each package must contain, and a packed file it does not list fails the run - so a new file +# under a package's Sdk/, build/ or buildTransitive/ needs a RequiredContent entry too. + +# Run the pipeline through pack and pack validation (restore, build, lint, tests, pack, validate), publishing nothing +[group('Pipeline')] +pipeline-pack-validate *args: ensure-tools + echo "==> Running the pack and validate pipeline" + {{ pipeline_tool }} --Build:RunPack=true --Build:ValidatePack=true --Release:Mode=None {{ args }} + +# Run the release pipeline, publishing to a local NuGet feed (restore, build, lint, tests, pack, validate, publish) +# +# `just` runs recipes through sh, which strips backslashes from unquoted arguments. Set the +# LOCAL_NUGET_FEED_PATH environment variable, or use forward slashes: +# +# just pipeline-local-release --PublishLocalNuGet:LocalFeedPath=p:/_sync-projects/.local-nuget/ +[doc('Run the release pipeline, publishing to a local NuGet feed (restore, build, lint, tests, pack, validate, publish)')] +[group('Pipeline')] +pipeline-local-release *args: ensure-tools + echo "==> Running the local release pipeline" + {{ pipeline_tool }} --Release:Mode=LocalNuGet {{ args }} + +# Run the release pipeline, publishing to NuGet (restore, build, lint, tests, pack, validate, publish, GitHub release) +[group('Pipeline')] +pipeline-release *args: ensure-tools + echo "==> Running the release pipeline" + {{ pipeline_tool }} --Release:Mode=NuGet {{ args }} diff --git a/.build/just/purview-build.just b/.build/just/purview-build.just new file mode 100644 index 0000000..244e44c --- /dev/null +++ b/.build/just/purview-build.just @@ -0,0 +1,24 @@ +# Local runs of the Purview.Build pipeline - the same `dotnet purview-build` tool, and the same +# .config/purview-build.json, that CI runs. Every Build stage - tests, lint, pack and pack validation - +# runs unless that file or an argument turns it off. Anything after the recipe name is passed to the +# tool, so a setting can be overridden for one run: `just pipeline-pr --Build:TestFilter="/*/*/*/*[Category=Unit]"`. + +pipeline_tool := "dotnet purview-build" + +# Run the PR pipeline (restore, build, lint, tests, pack, validate), as configured +[group('Pipeline')] +pipeline-pr *args: ensure-tools + echo "==> Running the PR pipeline" + {{ pipeline_tool }} {{ args }} + +# Run the build pipeline (restore, build, lint, pack, validate), without tests +[group('Pipeline')] +pipeline-build *args: ensure-tools + echo "==> Running the build pipeline" + {{ pipeline_tool }} --Build:RunTests=false --Release:Mode=None {{ args }} + +# Run the pipeline with tests forced on and release off (restore, build, lint, tests, pack, validate) +[group('Pipeline')] +pipeline-tests *args: ensure-tools + echo "==> Running the tests pipeline" + {{ pipeline_tool }} --Build:RunTests=true --Release:Mode=None {{ args }} diff --git a/.build/just/skills.just b/.build/just/skills.just new file mode 100644 index 0000000..0d33902 --- /dev/null +++ b/.build/just/skills.just @@ -0,0 +1,52 @@ +# The Purview.BuildSdk agent-skill targets. Each recipe names one target; the behaviour lives there. +# +# The targets are a thin wrapper over the standard skills CLI (`bun x skills` by default), run from the +# repository root. Every skill target runs once for the whole solution, however many projects it holds, +# so the recipes name the solution, not a hand-picked project. +# +# Every recipe here is run by a person, on purpose. Never make one a dependency of build, test or +# default, or call skills-add, -install, -update or -fix from a git hook: they change the repository, +# and the SDK refuses to run them inside a build (PRSKL0009). skills-check is read-only. +# +# The runner and agents are MSBuild properties (PurviewSkillsRunner, PurviewSkillsAgents), set once in +# Directory.Build.props. Pass a one-off through *args; `dotnet msbuild -p:` splits on `,` and `;`, so +# escape the separator: `just skills-update -p:PurviewSkillsAgents=claude-code%2Ccodex`. + +skills_project := solution_file + +# Install skills from another repository through the skills CLI (append '#' to pin it) +# +# just skills-add purview-dev/engineering-playbook +[doc("Install skills from another repository through the skills CLI (append '#' to pin it)")] +[group('Agent Skills')] +skills-add source *args: + echo "==> Installing skills from {{ BLUE }}{{ source }}{{ NORMAL }}" + dotnet msbuild "{{ skills_project }}" -t:InstallPurviewSkills -p:PurviewSkillsSource={{ source }} -v:n {{ args }} + +# Restore every skill skills-lock.json records - how a fresh clone gets the repository's skills back +[group('Agent Skills')] +skills-install *args: + dotnet msbuild "{{ skills_project }}" -t:InstallPurviewSkills -v:n {{ args }} + +# Update the agent skills by re-adding every unique source in skills-lock.json +# +# Each source is re-added at its latest with every skill it has, which refreshes the installed skills +# and adds any a source has gained; `skills update` is never run. FixPurviewSkills then removes links +# from agent directories PurviewSkillsAgents does not select, and does nothing when it is unset. +# The -t: value is quoted because sh would otherwise end the command at the `;`. +# +# just skills-update -p:PurviewSkillsDryRun=true +[doc('Update the agent skills by re-adding every unique source in skills-lock.json')] +[group('Agent Skills')] +skills-update *args: + dotnet msbuild "{{ skills_project }}" "-t:UpdatePurviewSkills;FixPurviewSkills" -v:n {{ args }} + +# Check that only the skill directories of the agents in PurviewSkillsAgents exist +[group('Agent Skills')] +skills-check *args: + dotnet msbuild "{{ skills_project }}" -t:CheckPurviewSkills -v:n {{ args }} + +# Remove the skills CLI's links from agent directories PurviewSkillsAgents does not select +[group('Agent Skills')] +skills-fix *args: + dotnet msbuild "{{ skills_project }}" -t:FixPurviewSkills -v:n {{ args }} diff --git a/.build/just/utilities.just b/.build/just/utilities.just new file mode 100644 index 0000000..d813497 --- /dev/null +++ b/.build/just/utilities.just @@ -0,0 +1,44 @@ +# Formatting, opening the solution, and scrubbing the build output. + +csharpier := "dotnet csharpier" + +# Check formatting with CSharpier +[group('Utilities')] +lint-check: + {{ csharpier }} check . + +# Format the code with CSharpier +[group('Utilities')] +lint-fix: + {{ csharpier }} format . + +# Open the solution in Visual Studio, or whichever application is registered for it +[group('Utilities')] +[windows] +vs: + start "" "{{ solution_file }}" + +# Open the solution in whichever application is registered for it +[group('Utilities')] +[macos] +vs: + open "{{ solution_file }}" + +# Open the solution in whichever application is registered for it +[group('Utilities')] +[linux] +vs: + xdg-open "{{ solution_file }}" + +# Delete every bin/, obj/ and artifacts_folder, stop the build servers, and restore from scratch +# +# The build servers go first: the MSBuild server and the compiler server hold files open under obj/, +# which on Windows stops them being deleted. node_modules/ and .git/ are never searched. +[doc('Delete every bin/, obj/ and artifacts_folder, stop the build servers, and restore from scratch')] +[group('Utilities')] +scrub: + echo "==> Scrubbing build output and stopping the build servers" + dotnet build-server shutdown + find . \( -name node_modules -o -name .git \) -prune -o -type d \( -name bin -o -name obj \) -prune -exec rm -rf {} + + rm -rf "{{ artifacts_folder }}" + just restore --force-evaluate diff --git a/.build/just/version.just b/.build/just/version.just new file mode 100644 index 0000000..09dbb37 --- /dev/null +++ b/.build/just/version.just @@ -0,0 +1,28 @@ +# The package version, from package.json: the single source of truth Purview.BuildSdk versions every +# project and package from. + +version_file := "package.json" + +# Read by just itself rather than by spawning bun, so `just --list` needs no Node tooling. +current_version := if path_exists(version_file) == "true" { replace_regex(read(version_file), '(?s).*?"version"\s*:\s*"([^"]*)".*', '$1') } else { "0.0.0" } + +# Display the current version, from package.json +[group('Version')] +version: + echo "==> Current version: {{ GREEN }}{{ current_version }}{{ NORMAL }} (from {{ version_file }}, stamped into every build by Purview.BuildSdk)" + +# Bump one part of the version in package.json - major, minor or patch - resetting the parts after it +# +# just bump minor # 2.0.1 -> 2.1.0 +# just bump patch --dry-run # print the new version, write nothing +# +# A pre-release suffix is dropped. Requires Bun. Afterwards it runs `_after-bump`, which does nothing +# unless the root Justfile overrides it to refresh whatever else pins the version. +[doc('Bump one part of the version in package.json - major, minor or patch - resetting the parts after it')] +[arg("part", pattern="major|minor|patch")] +[group('Version')] +bump part *args: && _after-bump + bun "{{ source_directory() / 'bump-version.ts' }}" "{{ part }}" "{{ version_file }}" {{ args }} + +# Runs after a successful `bump`. Override it in the root Justfile, e.g. `_after-bump: version-sync`. +_after-bump: diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index 1978504..ec846e1 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -10,14 +10,14 @@ "rollForward": false }, "dotnet-inspect": { - "version": "0.27.0", + "version": "0.28.0", "commands": [ "dotnet-inspect" ], "rollForward": false }, "purview.build": { - "version": "0.9.1", + "version": "0.9.2", "commands": [ "purview-build" ], diff --git a/.config/lefthook.yml b/.config/lefthook.yml index 23b964f..97949c3 100644 --- a/.config/lefthook.yml +++ b/.config/lefthook.yml @@ -6,4 +6,4 @@ pre-commit: commit-msg: jobs: - name: conventional commits - run: bunx commitlint --edit {1} \ No newline at end of file + run: bun x commitlint --edit {1} diff --git a/.config/purview-build.json b/.config/purview-build.json index 5772e2d..2c51666 100644 --- a/.config/purview-build.json +++ b/.config/purview-build.json @@ -72,4 +72,4 @@ "Release": { "Mode": "None" } -} \ No newline at end of file +} diff --git a/.editorconfig b/.editorconfig index 229c475..a1e0051 100644 --- a/.editorconfig +++ b/.editorconfig @@ -1,4 +1,4 @@ -# Purview.BuildSdk 2.0.1 - managed file, do not edit +# Purview.BuildSdk 2.1.0 - managed file, do not edit # # This file is written by Purview.BuildSdk and is replaced whenever the SDK version changes. The version # on the first line is how the SDK recognises a file it owns: a .editorconfig without that marker is diff --git a/.gitignore b/.gitignore index fb933b4..e3ebfce 100644 --- a/.gitignore +++ b/.gitignore @@ -601,12 +601,10 @@ coverage/ .tools/ -# Agent skills are installed into the universal .agents/skills/ folder only, and that folder and -# skills-lock.json are committed. Per-agent folders (and Claude Code's local settings) stay out. - -# Agent skills are installed into the universal .agents/skills/ folder, which is a local install: -# gitignored, and reproducible from the committed skills-lock.json with `just skills-install`. The -# skills this repository authors live in skills/ and are the only ones another repository installs. -# Per-agent folders (including .claude/) are local too - never commit a copy. +# Agent skills: this repository's own skills live in skills/ and are committed. The skills installed from +# other repositories are a local install the CLI owns, so .agents/skills/ stays out of git - committing it +# would publish someone else's skills as this repository's and put a second writer on a path the CLI owns. +# skills-lock.json is committed, so a fresh clone restores the recorded set with `just skills-install`. +# Per-agent folders (and Claude Code's local settings) stay out for the same reason, one level down. .agents/skills/ -.claude/ +/.claude/ diff --git a/AGENTS.md b/AGENTS.md index fa95edf..738a579 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,9 +28,10 @@ a diagnostic analyzer, a code fix, tests, samples, and documentation for scalar | `src/Directory.Build.props` / `src/Directory.Build.targets` | Solution-wide SDK, package, analyzer, and build behavior | | `global.json` | Required .NET SDK and Microsoft.Testing.Platform selection | | `package.json` | Authoritative repository/package version | -| `Justfile` | Supported local workflow commands | +| `Justfile` | Repository-specific recipes; imports the shared modules in `.build/just/` (copied verbatim from the `purview-buildsdk-justfile` skill) | | `skills` | Authored agent skills, installable with the skills CLI (see [Agent skills](#agent-skills)) | -| `.agents/skills`, `skills-lock.json` | Skills installed from other repositories (gitignored; `skills-lock.json` is the tracked record) - see [Installed skills](#installed-skills-agentsskills) | +| `.agents/skills` | Skills installed from other repositories - a local install the CLI owns, gitignored (see [Installed skills](#installed-skills-agentsskills)) | +| `skills-lock.json` | The record of that install - committed, so a fresh clone restores it | ## Standard workflow @@ -209,10 +210,12 @@ Before handing work back: Specialist guidance this repository depends on - the Purview engineering playbook, `Purview.BuildSdk` configuration, the `Purview.SourceGeneratorFramework` generator and test APIs, and the ZodSharp integration - is -published by the repositories that own it, and installed here by the skills CLI. Only the CLI's -`skills-lock.json` (source, skill path and content hash of every entry) is committed: `.agents/skills/` is a local -install, gitignored so a skill this repository installs but does not publish can never be found through -`skills add purview-dev/value-objects`. A fresh clone restores the set with `just skills-install`. +published by the repositories that own it, and installed here by the skills CLI. The install is **local and not +tracked**: `.agents/skills/**` is gitignored, because it is the CLI's copy of someone else's skills - committing it +would publish them as this repository's own, make a skill this repository installs but does not publish findable +through `npx skills add purview-dev/value-objects` (which discovers the root `skills/` folder, not them), and put a +second writer on a path the CLI owns. The CLI's `skills-lock.json` (source, skill path and content hash of every +entry) **is** committed, so a fresh clone restores the exact recorded set with `just skills-install`. | Skill | Source | Load before | | --- | --- | --- | @@ -243,22 +246,23 @@ npx -y skills@1 add purview-dev/build-sdk -s '*' -a universal -y npx -y skills@1 add purview-dev/sourcegenerator-framework -s '*' -a universal -y npx -y skills@1 add purview-dev/zodsharp -s '*' -a universal -y -# restore the committed set from skills-lock.json +# restore the recorded set from skills-lock.json (a fresh clone has no install) npx -y skills@1 experimental_install ``` -Commit the changed `skills-lock.json` in its own `chore` commit; `.agents/skills/` is gitignored and must not be -committed, or a skill this repository installs but does not publish becomes findable through -`skills add purview-dev/value-objects`. Do not edit -anything under `.agents/skills/` by hand - the CLI is its only writer, and a hand edit no longer matches the -lockfile's hash. `Purview.BuildSdk`'s `InstallPurviewSkills` target delegates to the same CLI; -`src/Directory.Build.props` sets `PurviewSkillsAgents=universal` so it is restricted the same way rather than -defaulting to every agent (`*`). +Commit `skills-lock.json` when it changes, in its own `chore` commit, and never commit anything under +`.agents/skills/` - the ignore rule refuses it, and `git add -f` is not the way around that: a committed copy would +make a skill this repository installs but does not publish findable through +`skills add purview-dev/value-objects`. Do not edit anything under `.agents/skills/` by hand either: the CLI is its +only writer, and a hand edit no longer matches the lockfile's hash. `Purview.BuildSdk`'s `InstallPurviewSkills` +target delegates to the same CLI; `src/Directory.Build.props` sets `PurviewSkillsAgents=universal` so it is +restricted the same way rather than defaulting to every agent (`*`). -`src/tests/Repository.UnitTests/InstalledSkillTests.cs` keeps this honest: every `skills-lock.json` entry has its -`.agents/skills//SKILL.md`, every installed folder is in the lockfile, no skill authored in `skills/` is -copied into `.agents/skills/`, no `.claude/skills/` copy exists, and there is no `CLAUDE.md` (at the root or in -`.github/`). +`src/tests/Repository.UnitTests/InstalledSkillTests.cs` keeps this honest: `.agents/skills/` and `/.claude/` are +ignored, every `skills-lock.json` entry records a source, skill path and hash a clone can restore, an install that is +present holds exactly what the lockfile records, no skill authored in `skills/` is copied into `.agents/skills/`, no +`.claude/skills/` copy exists, and there is no `CLAUDE.md` (at the root or in `.github/`). The install checks are +skipped when no install is present, because a fresh clone legitimately has none. ## Agent skills @@ -266,9 +270,9 @@ Authored skills live in the repository-root `skills/` folder. Nothing packs them delivers skills through the skills CLI, which clones the *git* repository and only discovers a root `skills/` folder. -`.agents/skills/` holds the skills installed from **other** repositories (above). This repository's own skills are -never installed into it — that would leave two copies to drift apart. Read them at their authored path, -`skills//SKILL.md`. +`.agents/skills/` holds the skills installed from **other** repositories (above) - a gitignored local install. This +repository's own skills are never installed into it — that would leave two copies to drift apart. Read them at their +authored path, `skills//SKILL.md`. Consumers install these skills with: diff --git a/CHANGELOG.md b/CHANGELOG.md index b708ba5..a592594 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ Released versions correspond to `v` GitHub releases. `package.json` is newest heading below is the version in development. Earlier releases are listed under [releases](https://github.com/purview-dev/value-objects/releases). -## 2.0.0-prerelease.1 +## 2.0.0 A major release for the .NET 11 GA. It drops the two out-of-support target frameworks and modernises the build; the generated API and the serialized payload shapes are unchanged. @@ -25,13 +25,22 @@ the generated API and the serialized payload shapes are unchanged. generated EF members are unchanged; `VO1019` is still reported for a project that references EF Core 7. - **The packed-consumer gate's oldest consumer is now `net10.0`**, replacing the `net8.0` console. +### Added + +- **Seven diagnostics now ship in a stable release.** `VO1025`-`VO1031` arrived with the `1.3.0` prereleases and are + recorded in `AnalyzerReleases.Shipped.md` under 2.0.0. They cover `[StringNormalize]` applied where it has no + effect (`VO1025`), a `[ValueObjectDefaults]` argument or `[Scalar]`/`[ValueObject]` option that repeats the + project or assembly default (`VO1026`, `VO1027`), the automatic `[Scalar]` form declaring nullability twice or + contradicting its declared property (`VO1028`-`VO1030`), and a nullable scalar mapped to a non-nullable Entity + Framework Core property, which is a required column (`VO1031`, the only warning). + ### Changed - **Package validation now records the dropped frameworks.** The baseline is the last stable release (1.2.3) and `CompatibilitySuppressions.xml` suppresses only `PKV006` for `net8.0` and `net9.0`, so any future public API regression is still a `dotnet pack` failure. - Built and tested against Purview.BuildSdk 2.0.0, Purview.SourceGeneratorFramework 2.0.0 and - Purview.ZodSharp 3.0.0-prerelease.5 on the .NET 11 GA SDK (11.0.100), TUnit 1.81.16, + Purview.ZodSharp 3.0.0 on the .NET 11 GA SDK (11.0.100), TUnit 1.81.16, Microsoft.SourceLink.GitHub 11.0.100, and EF Core 10.0.15 and 11.0.0. - The `net11.0` leg compiles with Runtime Async (`runtime-async=on`) and C# 15 as the default language version. The updated memory-safety rules are deliberately left off: they are preview, this repository has no unsafe diff --git a/Directory.Packages.props b/Directory.Packages.props index f6f2738..a98f59b 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -2,8 +2,8 @@ 5.9.0 1.83.0 - 2.0.0 - 3.0.0-prerelease.6 + 2.1.0 + 3.0.0 @@ -21,7 +21,7 @@ - + diff --git a/Justfile b/Justfile index 52e7731..05ee9a5 100644 --- a/Justfile +++ b/Justfile @@ -1,103 +1,37 @@ +# Recipes for Purview.ValueObjects. Run `just` for the list. +# +# The shared recipes come from .build/just/, copied verbatim from the purview-buildsdk-justfile +# skill. Change them there, not here; this file holds what belongs to this repository. + set quiet -root_folder := "./src/" -solution_file := root_folder + "ValueObjects.slnx" -test_solution := solution_file -build_configuration := "Debug" +# Let a definition here override a module's default variable or no-op hook. +set allow-duplicate-variables +set allow-duplicate-recipes -pipeline_tool := "dotnet purview-build" +import ".build/just/index.just" -artifact_folder := "./artifacts/" +# The one solution. Purview.Build names the same path in .config/purview-build.json. +solution_file := "src/ValueObjects.slnx" -# Displays the list of available commands +# Every test, matching TestFilter in .config/purview-build.json so a local run selects what CI does. +test_filter := "/*/*/*/*" + +root_folder := "./src/" [private] default: just --list # Restore the repository's .NET local tools (.config/dotnet-tools.json) -[private] -ensure-pipeline-tool: - pwsh -NoProfile -File scripts/restore-dotnet-tools.ps1 - -# Run the PR pipeline (restore, build, lint, tests, pack, validate) -[group('Pipeline')] -pipeline-pr *args: - just ensure-pipeline-tool - echo "Running PR pipeline..." - {{ pipeline_tool }} {{ args }} - -# Run the build pipeline (restore, build, lint) -[group('Pipeline')] -pipeline-build *args: - just ensure-pipeline-tool - echo "Running build pipeline..." - {{ pipeline_tool }} --Build:RunTests=false --Release:Mode=None {{ args }} - -# Run the release pipeline (restore, build, lint, tests, pack, publish, GitHub release) -[group('Pipeline')] -pipeline-release *args: - just ensure-pipeline-tool - echo "Running release pipeline..." - {{ pipeline_tool }} --Release:Mode=NuGet {{ args }} - -# Run the release pipeline (restore, build, lint, tests, pack, local nuget publish) -# Note: `just` runs recipes through the shell, which strips backslashes from unquoted arguments. -# Use the LOCAL_NUGET_FEED_PATH environment variable or forward slashes, e.g. -# just pipeline-local-release --PublishLocalNuGet:LocalFeedPath=p:/_sync-projects/.local-nuget/ -[group('Pipeline')] -pipeline-local-release *args: - just ensure-pipeline-tool - echo "Running local release pipeline..." - {{ pipeline_tool }} --Release:Mode=LocalNuGet {{ args }} - -# Run the pipeline with tests enabled -[group('Pipeline')] -pipeline-tests *args: - just ensure-pipeline-tool - echo "Running tests pipeline..." - {{ pipeline_tool }} --Build:RunTests=true --Release:Mode=None {{ args }} - -# Run the pipeline through pack + validate (restore, build, lint, tests, pack, validate pack contents) without publishing/releasing -[group('Pipeline')] -pipeline-pack-validate *args: - just ensure-pipeline-tool - echo "Running pack + validate pipeline..." - {{ pipeline_tool }} --Build:RunPack=true --Build:ValidatePack=true --Release:Mode=None {{ args }} - -# ----------------------------------------------------------------------------- -# Build and Test -# ----------------------------------------------------------------------------- - -# Builds the solution with the specified configuration (default: Debug) -[group('Build and Test')] -build *args: - echo "Building {{ BLUE }}{{ solution_file }}{{ NORMAL }} with {{ YELLOW }}{{ build_configuration }}{{ NORMAL }}..." - dotnet build "{{ solution_file }}" --configuration "{{ build_configuration }}" {{ args }} - -# Restore NuGet packages for the solution +# +# The shared recipe runs a plain `dotnet tool restore`. This repository's script also retries the +# cold-cache failure the .NET 11 SDK can produce, and is the only place the tools are restored, so +# `just` and CI behave the same way. +[doc("Restore the repository's .NET local tools (.config/dotnet-tools.json)")] [group('Build and Test')] -restore *args: - dotnet restore {{ solution_file }} {{ args }} - -# Runs tests for the solution with the specified configuration (default: Debug) -[group('Build and Test')] -test filter="/*/*/*/*/" *args: - echo "Running tests for {{ BLUE }}{{ test_solution }}{{ NORMAL }} with {{ YELLOW }}{{ build_configuration }}{{ NORMAL }}..." - dotnet test --solution "{{ test_solution }}" --configuration "{{ build_configuration }}" --treenode-filter={{ filter }} {{ args }} - -# Cleans the solution with the specified configuration (default: Debug) -[group('Build and Test')] -clean *args: - echo "Cleaning {{ BLUE }}{{ solution_file }}{{ NORMAL }} with {{ YELLOW }}{{ build_configuration }}{{ NORMAL }}..." - dotnet clean "{{ solution_file }}" --configuration "{{ build_configuration }}" {{ args }} - -# Packs the package into a NuGet package and outputs it to the specified folder -[group('Build and Test')] -pack *args: - just build - echo "Packing {{ BLUE }}{{ solution_file }}{{ NORMAL }} with {{ YELLOW }}{{ build_configuration }}{{ NORMAL }}..." - dotnet pack "{{ solution_file }}" --configuration "{{ build_configuration }}" --no-restore --output "{{ artifact_folder }}" {{ args }} +ensure-tools: + pwsh -NoProfile -File scripts/restore-dotnet-tools.ps1 # Prove the packed package works for real consumers: packs Purview.ValueObjects to an isolated feed, then publishes # and runs a Native AOT console, a Blazor WebAssembly app (trimmed and RunAOTCompilation, run in a headless browser), @@ -105,66 +39,24 @@ pack *args: # Needs the Native AOT toolchain, the wasm-tools workload for the WebAssembly AOT step, and Chrome or Edge for the # browser steps. Purview.ZodSharp/Purview.SourceGeneratorFramework versions not yet on nuget.org restore from # LOCAL_NUGET_FEED_PATH (or VALUEOBJECTS_DEPENDENCY_FEED). See scripts/test-packed-consumers.ps1 for the options. +[doc('Pack, then publish and run Native AOT, Blazor WebAssembly and Blazor Server consumers of the package')] [group('Build and Test')] smoke-packed-consumers *args: echo "Running the packed consumer gate..." pwsh -NoProfile -File scripts/test-packed-consumers.ps1 {{ args }} # Prove every PackValidation ForbiddenContent rule in .config/purview-build.json rejects a package: injects a matching -# file into scratch copies of the packed packages and runs the real purview-build validation on them. Reads artifacts/, -# so pack first (`just pipeline-pack-validate`); `just pipeline-local-release` moves its packages to the local feed, so -# pass -PackagesFolder after it. +# file into scratch copies of the packed packages and runs the real purview-build validation on them. Reads +# ./artifacts, so pack first (`just pipeline-pack-validate`); `just pipeline-local-release` moves its packages to the +# local feed, so pass -PackagesFolder after it. +[doc('Prove every PackValidation ForbiddenContent rule in .config/purview-build.json rejects a package')] [group('Build and Test')] -verify-pack-rules *args: - just ensure-pipeline-tool +verify-pack-rules *args: ensure-tools + echo "Proving the pack-validation forbidden-content rules..." pwsh -NoProfile -File scripts/test-pack-validation-rules.ps1 {{ args }} -# ----------------------------------------------------------------------------- -# Formatting -# ----------------------------------------------------------------------------- - -# Checks for linting issues in the root folder -[group('Formatting')] -lint-check: - echo "Linting checking {{ BLUE }}root folder{{ NORMAL }}..." - dotnet csharpier check . - -# Fixes linting issues in the root folder -[group('Formatting')] -lint-fix: - echo "Linting fixing {{ BLUE }}root folder{{ NORMAL }}..." - dotnet csharpier format . - -# ----------------------------------------------------------------------------- -# Versioning and Release -# ----------------------------------------------------------------------------- - -# Displays the current version of the project. -# Requires Bun. -[group('Versioning and Release')] -version: - bun -e "console.log('Current Version: {{ GREEN }}' + require('./package.json').version + '{{ NORMAL }}')" - -# ----------------------------------------------------------------------------- -# System / Shell -# ----------------------------------------------------------------------------- - -# Opens the solution in the default associated application -[group('Utilities')] -vs: - echo "Opening {{ BLUE }}{{ solution_file }}{{ NORMAL }}..." - open "{{ solution_file }}" - -# Opens the root folder in Visual Studio Code +# Open the source folder in Visual Studio Code [group('Utilities')] code: echo "Opening {{ BLUE }}Visual Studio Code{{ NORMAL }}..." code "{{ root_folder }}" - -# Clean up the repository by removing build artifacts, bin/obj folders etc, and shutting down the build server -[group('Utilities')] -scrub: - find . -type d \( -name bin -o -name obj \) -exec rm -rf {} + - just clean - just restore --force-evaluate - dotnet build-server shutdown diff --git a/docs/Trimming-AOT-and-Blazor.md b/docs/Trimming-AOT-and-Blazor.md index 0c2dcb2..46ebc42 100644 --- a/docs/Trimming-AOT-and-Blazor.md +++ b/docs/Trimming-AOT-and-Blazor.md @@ -75,7 +75,7 @@ Inside a generated converter: ## ZodSharp packages A Native AOT minimal API with `[Scalar]` + `[ZodSchema]` value objects in `Strict` mode, built against ZodSharp -3.0.0-prerelease.2, raises no trim or AOT warning from any ZodSharp API it uses, under the build analyzers or ILC's +3.0.0, raises no trim or AOT warning from any ZodSharp API it uses, under the build analyzers or ILC's whole-program analysis: | Package | Under trimming and Native AOT | diff --git a/docs/ZodSharp-Validation.md b/docs/ZodSharp-Validation.md index 33258b9..66a6af9 100644 --- a/docs/ZodSharp-Validation.md +++ b/docs/ZodSharp-Validation.md @@ -573,7 +573,7 @@ builder.Services.AddZodSharpProblemDetails(); `HandleBindingFailures` sets `RouteHandlerOptions.ThrowOnBadRequest` for the whole application, so every minimal-API binding failure travels through `UseExceptionHandler()`. Malformed JSON is still a standard `400` ProblemDetails. This -needs Purview.ZodSharp 3.0.0-prerelease.2 or later, and works under Native AOT. +needs Purview.ZodSharp 3.0.0 or later, and works under Native AOT. One limit remains: binding stops at the first invalid member. The bound-request validation above reports every one, so prefer it for request bodies, and keep `Strict` for payloads that are not validated any other way. diff --git a/global.json b/global.json index 4975af0..b7cd7fa 100644 --- a/global.json +++ b/global.json @@ -4,7 +4,7 @@ "rollForward": "latestMajor" }, "msbuild-sdks": { - "Purview.BuildSdk": "2.0.1" + "Purview.BuildSdk": "2.1.0" }, "test": { "runner": "Microsoft.Testing.Platform" diff --git a/package.json b/package.json index 16de3f6..68c2616 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "value-objects", - "version": "2.0.0-prerelease.1", + "version": "2.0.0", "license": "MIT", "author": { "name": "Kieron Lanning", diff --git a/skills-lock.json b/skills-lock.json index 90f6427..d8f4457 100644 --- a/skills-lock.json +++ b/skills-lock.json @@ -1,161 +1,215 @@ { - "version": 1, + "version": 2, "skills": { "purview-architecture": { "source": "purview-dev/engineering-playbook", "sourceType": "github", "skillPath": "skills/purview-architecture/SKILL.md", - "computedHash": "d194bd0f30091ffab6ef35c29582e56511d2daca32fdbb1942c50134198f9270" + "computedHash": "2500e935ff2ccb350f26ebb9be321dc9f99800121aa9412fdc597f95c2c465c8" }, "purview-architecture-testing": { "source": "purview-dev/engineering-playbook", "sourceType": "github", "skillPath": "skills/purview-architecture-testing/SKILL.md", - "computedHash": "5907c6bf28788b755b752041e2f0cd88222604a949988d487c25940b6284fce4" + "computedHash": "23af6d9baeb408e1e3f4034cef6539d7efa3fecb1b4da918cb539bd8dfbd5a00" }, "purview-buildsdk-adoption": { "source": "purview-dev/build-sdk", "sourceType": "github", "skillPath": "skills/purview-buildsdk-adoption/SKILL.md", - "computedHash": "ca2e13fc8074281f8ca2b510b742ae99db28f97d78f5fb36a6f27936a91941fc" + "computedHash": "ed38157d532c45582bc3f768ca6605c4cbc1339fbbb6a45e34a8badee06af06f" }, "purview-buildsdk-configuration": { "source": "purview-dev/build-sdk", "sourceType": "github", "skillPath": "skills/purview-buildsdk-configuration/SKILL.md", - "computedHash": "88b4a655efdc058b9a10adb1b5cbcd44e89bff6ed8c858e066092e5be0ca3e0b" + "computedHash": "7f33e4fee919a7e67033763f76f8e99e585ef128c937c6df58ebdae823949934" + }, + "purview-buildsdk-docs-sync": { + "source": "purview-dev/build-sdk", + "sourceType": "github", + "skillPath": "skills/purview-buildsdk-docs-sync/SKILL.md", + "computedHash": "e04a1043a1bf2f70bda95b5a5f544cfd093bd6e3ca159ef1c2425ba6e8129e41" + }, + "purview-buildsdk-justfile": { + "source": "purview-dev/build-sdk", + "sourceType": "github", + "skillPath": "skills/purview-buildsdk-justfile/SKILL.md", + "computedHash": "a3eba9ce21459f6db54ea0ecbf1aadfc01109e1446f9ad0142ae0f5ff217a65c" + }, + "purview-buildsdk-msbuild-properties": { + "source": "purview-dev/build-sdk", + "sourceType": "github", + "skillPath": "skills/purview-buildsdk-msbuild-properties/SKILL.md", + "computedHash": "76af7d5e1d12fd159acea43d3591bb6543b7ecb8375f3cfdc2f090f28729431f" }, "purview-buildsdk-project-detection": { "source": "purview-dev/build-sdk", "sourceType": "github", "skillPath": "skills/purview-buildsdk-project-detection/SKILL.md", - "computedHash": "7c30062fe592105b7a2539384843759521c5a3f90ace8f7c60f0e6ae2405b0b1" + "computedHash": "8b39fdeba80cad1cfd19d394209affc95d2dbc3e6a2e0358d14dc54ba6892ed7" }, "purview-buildsdk-project-layout": { "source": "purview-dev/build-sdk", "sourceType": "github", "skillPath": "skills/purview-buildsdk-project-layout/SKILL.md", - "computedHash": "101f09c92cf97e93387b926c48adab9598a0cf0a64a4932d41085ab0a0078cfa" + "computedHash": "e2df530972d850894ea3129f30041b5f0a16a067b6a6b037188f920e81d488bb" }, "purview-buildsdk-repository-review": { "source": "purview-dev/build-sdk", "sourceType": "github", "skillPath": "skills/purview-buildsdk-repository-review/SKILL.md", - "computedHash": "d366821995ff410caa436ccb996eaa6429f1ba51ba985b210d74ec3963f6c06f" + "computedHash": "08a5b7a34511959b72702ae8107c15ece77a27a7ef58c0b6b08e25a206f76c25" + }, + "purview-buildsdk-settings-docs-sync": { + "source": "purview-dev/build-sdk", + "sourceType": "github", + "skillPath": "skills/purview-buildsdk-settings-docs-sync/SKILL.md", + "computedHash": "a2a121d7b1fb97bf2e4c63ed58a20cc737f7d844a10cf30862c62bece930e3ff" }, "purview-buildsdk-skill-installation": { "source": "purview-dev/build-sdk", "sourceType": "github", "skillPath": "skills/purview-buildsdk-skill-installation/SKILL.md", - "computedHash": "b61cce9f0f213469c3acab4dd5ebaec450ee2be730680b166c9718c901aedffe" + "computedHash": "5a8cffd36dc696ec86276ddd089e9f859d4571b7606b46c0b82a5c52d5935e16" }, "purview-buildsdk-skill-tests": { "source": "purview-dev/build-sdk", "sourceType": "github", "skillPath": "skills/purview-buildsdk-skill-tests/SKILL.md", - "computedHash": "807b64466de0a871e5f8e678e7686c48a06d8bb9d42a03448f604a35d40d3935" + "computedHash": "bfa5798b756ab0fdc174fcba98184a516135f61f5b99453fc62b042a5c3551fa" + }, + "purview-buildsdk-skills-layout": { + "source": "purview-dev/build-sdk", + "sourceType": "github", + "skillPath": "skills/purview-buildsdk-skills-layout/SKILL.md", + "computedHash": "1067c53b6011c601c6a4b702ba327c461372c4fa3f6b36af746c0d10171c717d" }, "purview-buildsdk-testing": { "source": "purview-dev/build-sdk", "sourceType": "github", "skillPath": "skills/purview-buildsdk-testing/SKILL.md", - "computedHash": "d6a2ac1167faf68e8c27493de81c2e5b0d8183e523de4411aca5f5b9249c8a9c" + "computedHash": "5faaf12203c835f1af452137304feed6b99c5e94d7fb1e628ba0b304751914f9" + }, + "purview-component-compatibility": { + "source": "purview-dev/engineering-playbook", + "sourceType": "github", + "skillPath": "skills/purview-component-compatibility/SKILL.md", + "computedHash": "973337ad2a39704e92059f2a0c6abdfcb62a62d18c904b2d7707635944012bab" }, "purview-engineering-principles": { "source": "purview-dev/engineering-playbook", "sourceType": "github", "skillPath": "skills/purview-engineering-principles/SKILL.md", - "computedHash": "fd38d374b816ecf77964c41486e7c734ea34998c3f2a5538c90a2ba793905994" + "computedHash": "d1b0d2b50e635160f96d03d2790cb725242434bb28b1b47913371bb39d83215b" + }, + "purview-org-harvest": { + "source": "purview-dev/engineering-playbook", + "sourceType": "github", + "skillPath": "skills/purview-org-harvest/SKILL.md", + "computedHash": "040b34d9cd41f23e71dbe1500b0748793377703d1032e1135ed0a3eeeee4a7f8" }, "purview-persistence": { "source": "purview-dev/engineering-playbook", "sourceType": "github", "skillPath": "skills/purview-persistence/SKILL.md", - "computedHash": "0523ecc210bf3571e2fccb859128a499fd80694e9d4089b377a8d39d73c028f4" + "computedHash": "28e92fa8bccc241ca864b6731148bd721f47699baf3a1a2ec07cce42ed650bae" + }, + "purview-sourcegenerator-attribute-data-models": { + "source": "purview-dev/sourcegenerator-framework", + "sourceType": "github", + "skillPath": "skills/purview-sourcegenerator-attribute-data-models/SKILL.md", + "computedHash": "475bf4ef2c6e5c29e02725383f97fb0aea60243c05a2d779b03533c392c6d395" }, "purview-sourcegenerator-codewriter": { "source": "purview-dev/sourcegenerator-framework", "sourceType": "github", "skillPath": "skills/purview-sourcegenerator-codewriter/SKILL.md", - "computedHash": "f24ae680340784e62236d044cbc3658d5ca7bdc3cea3fc44f2bb5cf75a84f5e4" + "computedHash": "efc58013ff2122eb56981d482f8b66345977f235339473d5db63afca45bee198" }, "purview-sourcegenerator-diagnostics": { "source": "purview-dev/sourcegenerator-framework", "sourceType": "github", "skillPath": "skills/purview-sourcegenerator-diagnostics/SKILL.md", - "computedHash": "c3c7920701e0e688f34ddece9e448472e010e69767e8c08914638128d34a8f17" + "computedHash": "751a6feac6487bb70dba6ceb9b8bfb7201bae9e3733e1634df7dea443fe4f6a1" }, "purview-sourcegenerator-packaging": { "source": "purview-dev/sourcegenerator-framework", "sourceType": "github", "skillPath": "skills/purview-sourcegenerator-packaging/SKILL.md", - "computedHash": "e0e6372e92aefc8df026a73010d9e7436b0a8c2378a96fdebd8b4de9e025d4a0" + "computedHash": "6044272af5982bbf9750a198ca8094c17106579de36dc259712cedc166b7b2fb" }, "purview-sourcegenerator-pipeline": { "source": "purview-dev/sourcegenerator-framework", "sourceType": "github", "skillPath": "skills/purview-sourcegenerator-pipeline/SKILL.md", - "computedHash": "7d48394d7e3890f288949c79f040646207f34af9ae85827a63d056bae1b1b985" + "computedHash": "62835d55eab1ccf233241796d34d17bfd7b2fbe4be03424bf9a3a40d8ad2e6a7" }, "purview-sourcegenerator-testing": { "source": "purview-dev/sourcegenerator-framework", "sourceType": "github", "skillPath": "skills/purview-sourcegenerator-testing/SKILL.md", - "computedHash": "d88bf2353073013ff9ddf9d3fe1a2e9415eb60d319bbd053baa105f50fa3f889" + "computedHash": "027d6eb1b63783635b9000acd72ec4c3d06e129fed742e7b71a79fe7535040ed" }, "purview-sourcegenerator-tunit-tests": { "source": "purview-dev/sourcegenerator-framework", "sourceType": "github", "skillPath": "skills/purview-sourcegenerator-tunit-tests/SKILL.md", - "computedHash": "14809d3727643e9a779d590b6627b3283af7b36c835e902cb80162552cb45b4f" + "computedHash": "29f966d9331a556bc3a7d5aa8ad8fe7b1a9091557d629e9c23f65ebd14e3aee7" }, "purview-telemetry": { "source": "purview-dev/engineering-playbook", "sourceType": "github", "skillPath": "skills/purview-telemetry/SKILL.md", - "computedHash": "08ba26e1379dfa2bb826ddfd011e95ac84cd583b865f0b89673d7302b2c2c27d" + "computedHash": "f92aab10e3d2be7b24be559316537ba7d0485d0e479c67f4d5c6126f5f2fc652" }, "purview-testing-conventions": { "source": "purview-dev/engineering-playbook", "sourceType": "github", "skillPath": "skills/purview-testing-conventions/SKILL.md", - "computedHash": "388b0a79b565ed45a8513d77e8ed6e3d4491f96b43328cb09933cec7811c10f6" + "computedHash": "e053513db856852a23aad0e22625e1408fdd63377acb793e6d720fe37b9f7214" }, "purview-zodsharp-aspnetcore": { "source": "purview-dev/zodsharp", "sourceType": "github", "skillPath": "skills/purview-zodsharp-aspnetcore/SKILL.md", - "computedHash": "a1c1f9fc008be609cb12622ca08022965497fe306cc1b4203333440a0edb4206" + "computedHash": "5eb63e5679a9e277a83a06ef65d74abe59055831bebd452d6838e24de0b7c98b" + }, + "purview-zodsharp-blazor": { + "source": "purview-dev/zodsharp", + "sourceType": "github", + "skillPath": "skills/purview-zodsharp-blazor/SKILL.md", + "computedHash": "9b82c48aa59517088b6c194519001030e9f4a7422768159fad0526fbe3dffe44" }, "purview-zodsharp-core": { "source": "purview-dev/zodsharp", "sourceType": "github", "skillPath": "skills/purview-zodsharp-core/SKILL.md", - "computedHash": "e89c1000bb305420b85c1b93f3f77d9b500fc6b7d52b7016f670430fab1659b0" + "computedHash": "f5f42e314139495d5975111c9c56a5aa8c08cc8087b6a927abcbfe22fb149c29" }, "purview-zodsharp-custom-rules": { "source": "purview-dev/zodsharp", "sourceType": "github", "skillPath": "skills/purview-zodsharp-custom-rules/SKILL.md", - "computedHash": "3726a476b75b842daf67898e19b197331a1195061053183d66e9e05a66294266" + "computedHash": "033b0c0491e7abeb46090a261ad853fae063709eeaa7ad8167437de1888828d1" }, "purview-zodsharp-diagnostics": { "source": "purview-dev/zodsharp", "sourceType": "github", "skillPath": "skills/purview-zodsharp-diagnostics/SKILL.md", - "computedHash": "19e480b1eca26e417642b8c55f689580eb7b741f02e78387041ffebba1216ddb" + "computedHash": "f51b1926c21f92f8af14da70788a5bbf8e2ba1ad6305436ab4d91f72649a27b3" }, "purview-zodsharp-json": { "source": "purview-dev/zodsharp", "sourceType": "github", "skillPath": "skills/purview-zodsharp-json/SKILL.md", - "computedHash": "82da551adff5506232d5419d925ed198d71844f7901ad13ef7a3a0bead4a826f" + "computedHash": "105a094e56bf712a95d2b666c50e58c782429db189029a4eb8ca5df8136fb955" }, "purview-zodsharp-source-generator": { "source": "purview-dev/zodsharp", "sourceType": "github", "skillPath": "skills/purview-zodsharp-source-generator/SKILL.md", - "computedHash": "7172450983d6130c3335276fdcec80ca87b473ab7fbb43dfd08304b55c1632b0" + "computedHash": "207b891a41d074d116e23e8155c8f440a7976e05996b973376dce4f1df220155" } } } diff --git a/skills/purview-value-objects-zodsharp/SKILL.md b/skills/purview-value-objects-zodsharp/SKILL.md index 3b1568b..53ed408 100644 --- a/skills/purview-value-objects-zodsharp/SKILL.md +++ b/skills/purview-value-objects-zodsharp/SKILL.md @@ -291,7 +291,7 @@ register the generated converters (`new EmailAddress.EmailAddressJsonConverter() throws `JsonException(inner: ZodException)`, System.Text.Json records `$.customerEmail`, and `ZodExceptionHandler` re-roots the errors (`CustomerEmail.Value`, `Copies[1].Value`). On .NET 10 set `AddZodSharpProblemDetails(o => o.HandleBindingFailures = true)`, or binding answers a bare `400`; .NET 11 -needs nothing. Requires Purview.ZodSharp 3.0.0-prerelease.2+. It still stops at the first invalid member, so +needs nothing. Requires Purview.ZodSharp 3.0.0+. It still stops at the first invalid member, so prefer bound-request validation for request bodies. Don't register `ScalarJsonConverterFactory`: under Native AOT every request fails. diff --git a/src/ValueObjects.slnx b/src/ValueObjects.slnx index 54ccc8b..0a8b81e 100644 --- a/src/ValueObjects.slnx +++ b/src/ValueObjects.slnx @@ -2,10 +2,10 @@ + - diff --git a/src/src/SourceGenerator/AnalyzerReleases.Shipped.md b/src/src/SourceGenerator/AnalyzerReleases.Shipped.md index 13684ca..e38ad7b 100644 --- a/src/src/SourceGenerator/AnalyzerReleases.Shipped.md +++ b/src/src/SourceGenerator/AnalyzerReleases.Shipped.md @@ -30,3 +30,17 @@ Rule ID | Category | Severity | Notes VO1022 | ValueObjects | Error | The automatic [Scalar]/[Scalar(typeof(T))] form declares the scalar property, so the author must not declare it VO1023 | ValueObjects | Warning | Built-in string normalization is ignored because the value object implements OnNormalize or declares its own Create VO1024 | ValueObjects | Warning | Built-in string normalization requires a string scalar or member + +## Release 2.0.0 + +### New Rules + +Rule ID | Category | Severity | Notes +--------|----------|----------|------- +VO1025 | ValueObjects | Error | [StringNormalize] is only supported on a string member of a complex [ValueObject]; on a [Scalar] or any other type it has no effect +VO1026 | ValueObjects | Error | [ValueObjectDefaults] repeats a default already supplied by the project's MSBuild configuration +VO1027 | ValueObjects | Error | A [Scalar]/[ValueObject] option repeats the effective assembly default +VO1028 | ValueObjects | Error | An automatic [Scalar(Nullable = true)] also declares the property, so nullability has two sources; remove one of them +VO1029 | ValueObjects | Error | An automatic [Scalar(Nullable = false)] declares a nullable Value property, contradicting the option +VO1030 | ValueObjects | Error | An automatic [Scalar] declares a Value property whose type does not match the underlying type +VO1031 | ValueObjects | Warning | A nullable scalar is used as a non-nullable entity/complex property, which Entity Framework Core maps to a required column diff --git a/src/src/SourceGenerator/AnalyzerReleases.Unshipped.md b/src/src/SourceGenerator/AnalyzerReleases.Unshipped.md index cbaa31d..f21fc2d 100644 --- a/src/src/SourceGenerator/AnalyzerReleases.Unshipped.md +++ b/src/src/SourceGenerator/AnalyzerReleases.Unshipped.md @@ -8,10 +8,4 @@ Rule ID | Category | Severity | Notes --------|----------|----------|------- -VO1025 | ValueObjects | Error | [StringNormalize] is only supported on a string member of a complex [ValueObject]; on a [Scalar] or any other type it has no effect -VO1026 | ValueObjects | Error | [ValueObjectDefaults] repeats a default already supplied by the project's MSBuild configuration -VO1027 | ValueObjects | Error | A [Scalar]/[ValueObject] option repeats the effective assembly default -VO1028 | ValueObjects | Error | An automatic [Scalar(Nullable = true)] also declares the property, so nullability has two sources; remove one of them -VO1029 | ValueObjects | Error | An automatic [Scalar(Nullable = false)] declares a nullable Value property, contradicting the option -VO1030 | ValueObjects | Error | An automatic [Scalar] declares a Value property whose type does not match the underlying type -VO1031 | ValueObjects | Warning | A nullable scalar is used as a non-nullable entity/complex property, which Entity Framework Core maps to a required column + diff --git a/src/src/SourceGenerator/ValueObject/ComplexValueObjectEmitter.Serialization.cs b/src/src/SourceGenerator/ValueObject/ComplexValueObjectEmitter.Serialization.cs index 8f4c269..1b8ce61 100644 --- a/src/src/SourceGenerator/ValueObject/ComplexValueObjectEmitter.Serialization.cs +++ b/src/src/SourceGenerator/ValueObject/ComplexValueObjectEmitter.Serialization.cs @@ -69,8 +69,7 @@ static void EmitJsonConverter(CodeWriter writer, ComplexValueObjectModel model) { methodBody.IfBlock( "reader.TokenType != global::System.Text.Json.JsonTokenType.StartObject", - ifBody => - ifBody.Line($"throw new global::System.Text.Json.JsonException({unableToDeserialize});") + ifBody => ifBody.Throw(TypeLibrary.System.Text.Json.JsonException, unableToDeserialize) ); for (var index = 0; index < properties.Length; index++) @@ -89,8 +88,8 @@ static void EmitJsonConverter(CodeWriter writer, ComplexValueObjectModel model) ) ); - loop.Line("var jsonName = reader.GetString();"); - loop.Line("reader.Read();"); + loop.Assignment("var", "jsonName", "reader.GetString()"); + loop.MethodCallOn("reader", "Read"); for (var index = 0; index < properties.Length; index++) { @@ -106,12 +105,12 @@ static void EmitJsonConverter(CodeWriter writer, ComplexValueObjectModel model) } if (properties.Length == 0) - loop.Line("reader.Skip();"); + loop.MethodCallOn("reader", "Skip"); else - loop.Else(static branch => branch.Line("reader.Skip();")); + loop.Else(static branch => branch.MethodCallOn("reader", "Skip")); }); - methodBody.Line($"throw new global::System.Text.Json.JsonException({unableToDeserialize});"); + methodBody.Throw(TypeLibrary.System.Text.Json.JsonException, unableToDeserialize); } ); @@ -128,16 +127,26 @@ static void EmitJsonConverter(CodeWriter writer, ComplexValueObjectModel model) }, methodBody => { - methodBody.Line("writer.WriteStartObject();"); + methodBody.MethodCallOn("writer", "WriteStartObject"); for (var index = 0; index < properties.Length; index++) { var property = properties[index]; - methodBody.Line( - $"{helper}.WriteMember<{property.TypeName}>(writer, \"{property.Name}\", value.{property.Name}, options{ConverterArgument(property, index)});" + + methodBody.MethodCallOn( + helper, + "WriteMember", + arguments: + [ + "writer", + $"\"{property.Name}\"", + $"value.{property.Name}", + $"options{ConverterArgument(property, index)}", + ], + genericArguments: [property.Type] ); } - methodBody.Line("writer.WriteEndObject();"); + methodBody.MethodCallOn("writer", "WriteEndObject"); } ); } diff --git a/src/tests/Repository.UnitTests/InstalledSkillTests.cs b/src/tests/Repository.UnitTests/InstalledSkillTests.cs index 3196b9f..44680d3 100644 --- a/src/tests/Repository.UnitTests/InstalledSkillTests.cs +++ b/src/tests/Repository.UnitTests/InstalledSkillTests.cs @@ -4,66 +4,97 @@ namespace Purview.ValueObjects.Repository; /// -/// Guards the skills installed from other repositories. They are installed by the skills CLI into the -/// universal .agents/skills/ folder only, which is a local install: gitignored, reproducible from -/// the committed skills-lock.json, and never tracked - a skill this repository installs but does -/// not publish must not become discoverable through skills add purview-dev/value-objects. +/// Guards how the skills installed from other repositories sit in the working tree. /// /// -/// The checks that need an install are skipped on a fresh clone, which has none until -/// just skills-install runs; SkillTests covers this repository's own skills in -/// skills/. +/// +/// The install belongs to the skills CLI, not to git. .agents/skills/ is gitignored, because committing it +/// would publish someone else's skills as this repository's own - a skill this repository installs but does not +/// publish would become discoverable through skills add purview-dev/value-objects - and would put a second +/// writer on a path the CLI owns. Only skills-lock.json (source, skill path and content hash of every entry) +/// is committed, so a fresh clone restores the recorded set with just skills-install. +/// +/// +/// The install is therefore checked only when one is present: a fresh clone has none, and its absence is the +/// state these tests allow. SkillTests validates this repository's own skills in skills/; these are +/// someone else's, so their content is not checked here, only their placement. +/// /// public sealed class InstalledSkillTests { static readonly Lazy RepositoryRoot = new(FindRepositoryRoot); [Test] - public async Task Lockfile_GivenEveryEntry_HasItsSkillInstalledUnderAgents(CancellationToken cancellationToken) + public async Task GitIgnore_GivenTheRepository_KeepsTheInstallAndPerAgentFoldersOut( + CancellationToken cancellationToken + ) { // Arrange - var recorded = await ReadLockfileSkillsAsync(cancellationToken); - if (!Directory.Exists(AgentsSkillsFolder())) - { - // A fresh clone has no local install - it is gitignored and restored with `just skills-install` - - // so the committed record is what has to be there. - await Assert.That(recorded).IsNotEmpty().Because("skills-lock.json records no installed skills"); - return; - } + var rules = await File.ReadAllLinesAsync(Path.Combine(RepositoryRoot.Value, ".gitignore"), cancellationToken); // Act - var missing = recorded - .Where(static name => !File.Exists(Path.Combine(AgentsSkillsFolder(), name, "SKILL.md"))) - .ToArray(); + var required = new[] { ".agents/skills/", "/.claude/" }; + var missing = required.Where(rule => !rules.Contains(rule, StringComparer.Ordinal)).ToArray(); // Assert - await Assert.That(recorded).IsNotEmpty().Because("skills-lock.json records no installed skills"); await Assert .That(missing) .IsEmpty() .Because( - "skills-lock.json records skills that are not installed in .agents/skills/. Restore them with " - + $"`npx -y skills@1 experimental_install`: {string.Join(", ", missing)}" + "the skills CLI owns .agents/skills/ and the per-agent folders, so both stay out of git: " + + string.Join(", ", missing) + ); + } + + [Test] + public async Task Lockfile_GivenEveryEntry_RecordsWhatAFreshCloneRestores(CancellationToken cancellationToken) + { + // Arrange + var recorded = await ReadLockfileAsync(cancellationToken); + + // Act + var incomplete = recorded + .Where(static skill => + skill.Source.Length == 0 || skill.SkillPath.Length == 0 || skill.ComputedHash.Length == 0 + ) + .Select(static skill => skill.Name) + .ToArray(); + + // Assert + await Assert + .That(recorded) + .IsNotEmpty() + .Because("skills-lock.json is the only tracked half of the install, so it must record at least one skill"); + await Assert + .That(incomplete) + .IsEmpty() + .Because( + $"an entry without a source, skill path and hash cannot be restored: {string.Join(", ", incomplete)}" ); } [Test] - public async Task AgentsSkills_GivenEveryInstalledSkill_IsRecordedInTheLockfile(CancellationToken cancellationToken) + public async Task AgentsSkills_GivenAnInstall_MatchesTheLockfile(CancellationToken cancellationToken) { // Arrange - var recorded = await ReadLockfileSkillsAsync(cancellationToken); + var recorded = await ReadLockfileAsync(cancellationToken); + if (!Directory.Exists(AgentsSkillsFolder())) { - // No local install to check against the record; the record itself is checked above. + // A fresh clone has no install. That is the arrangement, not a gap: the lockfile is tracked and + // `just skills-install` writes the rest. + await Assert + .That(File.Exists(LockfilePath())) + .IsTrue() + .Because("without skills-lock.json a clone cannot restore the skills the repository depends on"); return; } + var installed = InstalledSkillNames(); + // Act - var unrecorded = Directory - .GetDirectories(AgentsSkillsFolder()) - .Select(static path => Path.GetFileName(path)) - .Where(name => !recorded.Contains(name, StringComparer.Ordinal)) - .ToArray(); + var unrecorded = installed.Where(name => !recorded.Any(skill => skill.Name == name)).ToArray(); + var missing = recorded.Select(static skill => skill.Name).Where(name => !installed.Contains(name)).ToArray(); // Assert await Assert @@ -73,6 +104,13 @@ await Assert "every folder in .agents/skills/ must be written by the skills CLI, which records it in " + $"skills-lock.json: {string.Join(", ", unrecorded)}" ); + await Assert + .That(missing) + .IsEmpty() + .Because( + "skills-lock.json records skills the install does not hold. Restore them with `just skills-install`: " + + string.Join(", ", missing) + ); } [Test] @@ -207,9 +245,16 @@ .. output static string AgentsSkillsFolder() => Path.Combine(RepositoryRoot.Value, ".agents", "skills"); - static async Task ReadLockfileSkillsAsync(CancellationToken cancellationToken) + static string LockfilePath() => Path.Combine(RepositoryRoot.Value, "skills-lock.json"); + + static string[] InstalledSkillNames() => + !Directory.Exists(AgentsSkillsFolder()) + ? [] + : [.. Directory.GetDirectories(AgentsSkillsFolder()).Select(static path => Path.GetFileName(path))]; + + static async Task ReadLockfileAsync(CancellationToken cancellationToken) { - await using var stream = File.OpenRead(Path.Combine(RepositoryRoot.Value, "skills-lock.json")); + await using var stream = File.OpenRead(LockfilePath()); using var lockfile = await JsonDocument.ParseAsync(stream, cancellationToken: cancellationToken); return @@ -217,8 +262,13 @@ static async Task ReadLockfileSkillsAsync(CancellationToken cancellati .. lockfile .RootElement.GetProperty("skills") .EnumerateObject() - .Select(static property => property.Name) - .Order(StringComparer.Ordinal), + .Select(static property => new LockedSkill( + property.Name, + property.Value.GetProperty("source").GetString() ?? string.Empty, + property.Value.GetProperty("skillPath").GetString() ?? string.Empty, + property.Value.GetProperty("computedHash").GetString() ?? string.Empty + )) + .OrderBy(static skill => skill.Name, StringComparer.Ordinal), ]; } @@ -242,4 +292,6 @@ static string FindRepositoryRoot() $"No repository root above '{AppContext.BaseDirectory}' carries AGENTS.md, skills-lock.json and src/src." ); } + + sealed record LockedSkill(string Name, string Source, string SkillPath, string ComputedHash); }