Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 62 additions & 0 deletions .build/just/bump-version.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
// Bumps one part of the semantic version in package.json, for `just bump <major|minor|patch>`.
//
// 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 <major|minor|patch> [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}`);
53 changes: 53 additions & 0 deletions .build/just/dotnet.just
Original file line number Diff line number Diff line change
@@ -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 }}
56 changes: 56 additions & 0 deletions .build/just/env.just
Original file line number Diff line number Diff line change
@@ -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.
41 changes: 41 additions & 0 deletions .build/just/index.just
Original file line number Diff line number Diff line change
@@ -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"
30 changes: 30 additions & 0 deletions .build/just/purview-build-nuget.just
Original file line number Diff line number Diff line change
@@ -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 }}
24 changes: 24 additions & 0 deletions .build/just/purview-build.just
Original file line number Diff line number Diff line change
@@ -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 }}
52 changes: 52 additions & 0 deletions .build/just/skills.just
Original file line number Diff line number Diff line change
@@ -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 '#<ref>' to pin it)
#
# just skills-add purview-dev/engineering-playbook
[doc("Install skills from another repository through the skills CLI (append '#<ref>' 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 }}
44 changes: 44 additions & 0 deletions .build/just/utilities.just
Original file line number Diff line number Diff line change
@@ -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
28 changes: 28 additions & 0 deletions .build/just/version.just
Original file line number Diff line number Diff line change
@@ -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:
Loading
Loading