feat: add Purview.OpenAPI.XmlComments

.config/dotnet-tools.json

@@ -0,0 +1,27 @@
+{
+  "version": 1,
+  "isRoot": true,
+  "tools": {
+    "csharpier": {
+      "version": "1.3.0",
+      "commands": [
+        "csharpier"
+      ],
+      "rollForward": false
+    },
+    "dotnet-inspect": {
+      "version": "0.26.0",
+      "commands": [
+        "dotnet-inspect"
+      ],
+      "rollForward": false
+    },
+    "purview.build": {
+      "version": "0.8.0",
+      "commands": [
+        "purview-build"
+      ],
+      "rollForward": false
+    }
+  }
+}

.config/lefthook.yml

@@ -0,0 +1,9 @@
+pre-commit:
+  jobs:
+    - name: lint staged
+      run: just lint-check
+
+commit-msg:
+  jobs:
+    - name: conventional commits
+      run: bunx commitlint --edit {1}

.config/purview-build.json

@@ -0,0 +1,47 @@
+{
+	"Build": {
+		"Solution": "src/XmlComments.slnx",
+		"TestRoot": "src/tests",
+		"TestPatterns": "*Tests.csproj",
+		"TestProjects": "*Tests*",
+		// Every tier: the unit tests and the integration tests, which build and run throwaway consumers against the real
+		// OpenAPI XML-comment generator. The integration tier is the only proof the targets work, so it is not optional.
+		"TestFilter": "/*/*/*/*"
+	},
+	"PackValidation": {
+		// Explicit because Purview.Build 0.5.3 defaults RequiredCompilerFlags to empty.
+		"RequiredCompilerFlags": [
+			"optimization=release"
+		],
+		// The PDB ships in the symbol package, not the .nupkg, matching the other purview-dev repositories.
+		"RequireSymbolPackage": false,
+		// RequireExplicitContent defaults to true, so this is the exhaustive declaration of what the package ships: an
+		// entry matching none of these globs fails.
+		"RequiredContent": {
+			"purview.openapi.xmlcomments": [
+				"README.md",
+				"buildTransitive/Purview.OpenAPI.XmlComments.props",
+				"buildTransitive/Purview.OpenAPI.XmlComments.targets",
+				"purview-logo-light.png",
+				"tasks/netstandard2.0/Purview.OpenAPI.XmlComments.dll",
+				"tasks/netstandard2.0/Purview.OpenAPI.XmlComments.xml"
+			]
+		},
+		// Every package ("*"). These hold even if a RequiredContent glob is ever widened.
+		"ForbiddenContent": {
+			"*": [
+				// A build-time package: under lib/ or ref/ every consumer would compile against the task assembly and copy
+				// it to their output.
+				"lib/**",
+				"ref/**",
+				"runtimes/**",
+				// The host MSBuild supplies its own assemblies; a packed copy beside the task breaks type identity for
+				// ITask and ITaskItem when MSBuild loads it.
+				"**/Microsoft.Build*"
+			]
+		}
+	},
+	"Release": {
+		"Mode": "None"
+	}
+}

.gitattributes

@@ -0,0 +1,108 @@
+# Default: auto-detect text and normalise to LF in the index.
+# Everything below only overrides the *working tree* checkout behaviour.
+* text=auto
+
+# ---------------------------------------------------------------------------
+# .NET source and project files
+# No eol= means each dev's core.autocrlf / core.eol decides. Set eol=lf here
+# instead if you want to hard-enforce LF everywhere -- but keep it in sync
+# with end_of_line in .editorconfig or `dotnet format --verify-no-changes`
+# will fail in CI.
+# ---------------------------------------------------------------------------
+*.cs        text diff=csharp
+*.csx       text diff=csharp
+*.vb        text
+*.fs        text
+*.fsx       text
+*.csproj    text
+*.fsproj    text
+*.vbproj    text
+*.props     text
+*.targets   text
+*.resx      text
+*.config    text
+*.ruleset   text
+*.xaml      text
+*.cshtml    text diff=html
+*.razor     text diff=html
+*.sln       text eol=lf
+*.slnx      text eol=lf
+
+# ---------------------------------------------------------------------------
+# Data, config and docs
+# ---------------------------------------------------------------------------
+*.json      text
+*.xml       text
+*.yml       text
+*.yaml      text
+*.toml      text
+*.md        text diff=markdown
+*.svg       text
+*.editorconfig text
+.gitattributes text
+.gitignore  text
+
+# ---------------------------------------------------------------------------
+# Web assets (only relevant if the repo ships any)
+# ---------------------------------------------------------------------------
+*.js        text
+*.jsx       text
+*.ts        text
+*.tsx       text
+*.html      text diff=html
+*.css       text
+*.scss      text
+
+# ---------------------------------------------------------------------------
+# Scripts -- these MUST be pinned regardless of platform.
+# cmd.exe misparses LF in multi-line blocks and labels; sh needs LF.
+# ---------------------------------------------------------------------------
+*.sh        text eol=lf
+*.bash      text eol=lf
+*.zsh       text eol=lf
+*.bat       text eol=crlf
+*.cmd       text eol=crlf
+*.ps1       text eol=lf
+*.psm1      text eol=lf
+*.psd1      text eol=lf
+Dockerfile  text eol=lf
+*.dockerfile text eol=lf
+justfile    text eol=lf
+Makefile    text eol=lf
+
+# Patches carry their own endings -- never touch them.
+*.patch     -text
+
+# ---------------------------------------------------------------------------
+# Binary
+# ---------------------------------------------------------------------------
+*.png       binary
+*.jpg       binary
+*.jpeg      binary
+*.gif       binary
+*.ico       binary
+*.webp      binary
+*.mp4       binary
+*.zip       binary
+*.gz        binary
+*.7z        binary
+*.tar       binary
+*.exe       binary
+*.dll       binary
+*.pdb       binary
+*.obj       binary
+*.vsix      binary
+*.nupkg     binary
+*.snupkg    binary
+*.snk       binary
+*.pfx       binary
+*.lockb     binary
+*.woff      binary
+*.woff2     binary
+
+# ---------------------------------------------------------------------------
+# Keep repo scaffolding out of `git archive` / source packages
+# ---------------------------------------------------------------------------
+.gitattributes  export-ignore
+.gitignore      export-ignore
+.github/        export-ignore

.github/copilot-instructions.md

@@ -0,0 +1,18 @@
+# GitHub Copilot Instructions
+
+## Primary instruction source
+
+Use the repository root [`AGENTS.md`](../AGENTS.md) as the **primary** source of truth for behavior, architecture context, testing standards, and completion criteria.
+
+If this file and `AGENTS.md` appear to conflict, prefer `AGENTS.md` unless this file explicitly states a GitHub Copilot-only exception.
+
+## Copilot-specific guidance
+
+This file should only contain **GitHub Copilot-specific** instruction details.
+Keep product, architecture, and general engineering standards centralized in `AGENTS.md`.
+
+## Operating expectations for Copilot
+
+- Apply the `AGENTS.md` testing bar strictly (TUnit and TUnit.Mocks, `{SubjectUnderTest}_{Scenario}_{Expectation}` naming, cancellation token rule, an integration test for any change to the props or targets).
+- Treat work as incomplete until relevant tests pass.
+- Keep edits minimal, focused, and aligned with existing SDK and repository conventions.

.github/workflows/pr.yml

@@ -0,0 +1,48 @@
+name: PR
+
+on:
+  pull_request:
+    branches: [main]
+    # `ready_for_review` is not one of the default activity types, so a draft PR would never
+    # re-evaluate the required build gate once it is marked ready for review.
+    types: [opened, synchronize, reopened, ready_for_review]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build and test
+    uses: purview-dev/build/.github/workflows/purview-build.yml@main
+    with:
+      # The shared workflow defaults to the 10.0.x SDK, but this repository pins the .NET 11 SDK in
+      # global.json (the tests run on net10.0 and net11.0). Without the matching SDK the runner cannot
+      # resolve global.json and every step fails.
+      # Keep in sync with `sdk.version` in global.json.
+      dotnet-version: "11.0.100-rc.3.26522.148"
+      # Mirrors Build:TestFilter in purview-build.json: the unit tests and the integration tests, which
+      # build and run throwaway consumers against the real OpenAPI XML-comment generator.
+      test-filter: "/*/*/*/*"
+      run-pack: true
+      validate-pack: true
+    secrets: inherit
+
+  # Every other job builds against the source props, targets and task assembly; this one builds what ships. It packs
+  # the package to an isolated feed and package cache, then builds and runs scripts/packed-consumer against it through
+  # PackageReference alone. `just smoke-packed-consumer` runs the same locally.
+  packed-consumer:
+    name: Packed consumer
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      # The SDK from global.json, plus the .NET 10 runtime the consumer runs on.
+      - uses: actions/setup-dotnet@v6
+        with:
+          global-json-file: global.json
+          dotnet-version: 10.0.x
+
+      - name: Pack, then build and run a consumer of the package
+        shell: pwsh
+        run: ./scripts/test-packed-consumer.ps1 -PackOutput artifacts/packed

.github/workflows/release.yml

@@ -0,0 +1,45 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  # Neither a reusable workflow nor a composite action can grant a scope, so the caller owns these:
+  # `packages: write` for the GitHub Packages mirror, `id-token: write` for the nuget.org Trusted
+  # Publishing exchange, which GitHub withholds by default.
+  packages: write
+  id-token: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  release:
+    name: Release packages
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      # A composite action, not a reusable workflow: nuget.org validates the OIDC `job_workflow_ref`
+      # claim against the registered Trusted Publishing policy, and inside a called workflow that
+      # claim names the called repository. Running it here keeps the claim on this file, which is the
+      # file name the policy is registered against.
+      - uses: purview-dev/build/actions/purview-release@main
+        with:
+          release-mode: NuGet
+          # The shared action defaults to the 10.0.x SDK, but this repository pins
+          # the .NET 11 SDK in global.json; without it the release job cannot resolve global.json.
+          # Keep in sync with `sdk.version` in global.json (and with .github/workflows/pr.yml).
+          dotnet-version: "11.0.100-rc.3.26522.148"
+          trusted-publishing: true
+          # The nuget.org profile name, not the sign-in email.
+          nuget-user: kieronlanning
+          # A composite action has no `secrets` context, so the read token is passed explicitly.
+          packages-read-token: ${{ secrets.PURVIEW_PACKAGES_READ_TOKEN }}
+          # A composite action has no `vars` context, so repository variables are passed here.
+          source-mapping: ${{ vars.PURVIEW_NUGET_SOURCE_MAPPING }}
+          github-packages: ${{ vars.PURVIEW_PUBLISH_GITHUB_PACKAGES == 'true' }}
+          github-packages-keep-versions: ${{ vars.PURVIEW_GITHUB_PACKAGES_KEEP_VERSIONS || '1' }}
+          github-packages-retention-hours: ${{ vars.PURVIEW_GITHUB_PACKAGES_RETENTION_HOURS || '24' }}