From 1eabebd1bf74ae3d3e17eb09699b831996cc717d Mon Sep 17 00:00:00 2001 From: "facility-bot[app]" Date: Fri, 5 Jun 2026 15:57:36 +0000 Subject: [PATCH] Update Facility .NET repository conventions --- .agents/skills/dotnet-inspect/SKILL.md | 31 ++++++++++++++++---------- apm.lock.yaml | 6 ++--- 2 files changed, 22 insertions(+), 15 deletions(-) diff --git a/.agents/skills/dotnet-inspect/SKILL.md b/.agents/skills/dotnet-inspect/SKILL.md index e87b507..e48c083 100644 --- a/.agents/skills/dotnet-inspect/SKILL.md +++ b/.agents/skills/dotnet-inspect/SKILL.md @@ -1,6 +1,6 @@ --- name: dotnet-inspect -version: 0.8.1 +version: 0.9.1 description: Query .NET APIs across NuGet packages, platform libraries, and local files. Use for factual answers about package contents, API signatures, compatibility changes, relationships, SourceLink, and assembly metadata. --- @@ -24,7 +24,8 @@ Default output is Markdown. Use `--oneline` to scan, `--json` for structured dat | Fix upgrade breaks | `diff --package Foo@old..new --breaking` | Inspect replacement members with `member`. | | Learn what changed | `diff --package Foo@old..new --additive` or `diff --platform Lib@old..new` | Use `-t Type` to narrow. | | Locate source | `source Type --package Foo` | Add `-m Member` or use `member Type Member:1 -v:d`. | -| Audit package/library contents | `package Foo`, `library Foo` | Add `-S Section`, `--fields`, `--source-link-audit`, or `--count`. | +| Inspect package/library signals | `library Foo -S Signals` or `package Foo -S Signals` | `Signals` resolves SourceLink for libraries; add `-S "SourceLink Availability"` for source reachability or `-S "SourceLink Integrity"` for slow content verification. | +| Inventory package library files | `package Foo -S "Library Files"` | Lists all files under `lib/` across TFMs; use paths from this section with `library --package Foo` for specific assemblies. | | Explore relationships | `depends Type`, `extensions Type`, `implements Interface` | Add package/platform scope as needed. | | Keep output small | `--oneline`, `--json`, `-S Section`, `--count`, `-n N` | Prefer built-in limits over shell pipes. | @@ -34,8 +35,9 @@ LLM training may miss .NET 10+ runtime/library features. Prefer metadata inspect | Feature | Description | Use | Watch for | | ------- | ----------- | --- | --------- | -| Runtime async | .NET 11+ libraries may use runtime async instead of compiler-generated state machines. | `library --platform Lib --framework runtime@ -S "Async*"` | `Kind` distinguishes runtime async from state-machine async; use `--count` only for totals. | -| Runtime-pack assemblies | Many BCL libraries ship only as installed platform/runtime-pack assemblies, not standalone packages. | `library --platform Lib --framework runtime@` or direct DLL path | Prefer platform/direct DLL inspection when package lookup is misleading. | +| Runtime async | .NET 11+ libraries may use runtime async instead of compiler-generated state machines. | `library --platform Lib --version -S "Async*"` | `Kind` distinguishes runtime async from state-machine async; use `--count` only for totals. | +| Runtime-pack assemblies | Many BCL libraries ship only as installed platform/runtime-pack assemblies, not standalone packages. | `library --platform Lib --version ` or direct DLL path | Prefer platform/direct DLL inspection when package lookup is misleading. | +| Memory-safety metadata | Newer compilers may stamp updated memory-safety rules and caller-unsafe members in metadata. | `library Lib --version -S Signals` | Compare `MemorySafetyRules` v2+ with the `RequiresUnsafe` member count; unsafe signatures and P/Invoke remain separate signals. | | Extension properties | C# extension blocks can expose properties in addition to extension methods. | `extensions Type --reachable` | Results include extension methods and C# extension properties. | | Lowering changes | Compiler/runtime implementation can differ from API signatures. | `member Type Member:1 -v:d` | Inspect Source, Lowered C#, IL, and annotated IL before inferring behavior. | @@ -82,17 +84,22 @@ dnx dotnet-inspect -y -- member JsonSerializer --package System.Text.Json Serial For crash/stack diagnostics that include a MethodDef token plus IL offset, `source --il-offset 0x06000001+0x5` can map the offset to source. This is a niche deep-debugging path; do not start there for normal API lookup. -## Package and library audit workflow +## Package and library Signals workflow -Use `package` for NuGet metadata and package layout. Use `library` for assembly identity, references, symbols, SourceLink, resources, async methods, and public key token. +Use `Signals` for metadata and provenance observations. It reports observations, not a safety or trust verdict. Cost follows verbosity and explicit selection: `library X -S Signals` reports metadata plus the shared Signals section (acquiring a missing library PDB to resolve SourceLink); add `SourceLink Availability` and `SourceLink Missing Files` for the per-source-file reachability pass. The exhaustive content check is the opt-in `SourceLink Integrity` section. ```bash -dnx dotnet-inspect -y -- package System.Text.Json --versions -dnx dotnet-inspect -y -- library System.Text.Json --source-link-audit -dnx dotnet-inspect -y -- library System.Text.Json -S "Async*" --count +dnx dotnet-inspect -y -- library System.Text.Json -S Signals +dnx dotnet-inspect -y -- library System.Text.Json -S "Signals,SourceLink Availability,SourceLink Missing Files" +dnx dotnet-inspect -y -- library System.Text.Json -S "SourceLink Integrity" +dnx dotnet-inspect -y -- package System.Text.Json -S Signals ``` -`package` supports custom feeds (`--source`, `--add-source`, `--nugetconfig`) and local `.nupkg` files. `library -S "Async*"` classifies async methods as runtime async or classic state-machine async. +Library Signals include assembly metadata such as SourceLink presence, SourceLink availability, SourceLink CR/LF diagnostics, determinism, trim/AOT markers, updated memory-safety model, `RequiresUnsafe` member count, unsafe signatures, P/Invoke, and direct references. Package Signals use the same shape for package metadata/assets, dependencies, signature provenance, and NuGet registry observations. `library X -S Signals` resolves SourceLink by acquiring a missing PDB. The per-source-file reachability pass — SourceLink Availability and SourceLink Missing Files, which issue one HTTP HEAD per tracked source URL — is opt-in: select it explicitly with `-S "SourceLink Availability"`. It does not run in a plain `library X -v:d` flow because its cost scales with source-file count. To verify source *content*, select `library X -S "SourceLink Integrity"`: it downloads each tracked source file and compares its hash to the PDB checksum, exits non-zero on true content mismatch, and reports `CR/LF Mismatch` when checksums match after line-ending normalization. + +Package Signals include TFMs, manifest, readme/license, direct dependencies, package signature, local provenance, and registry-backed signals such as vulnerabilities, package age, dependency vulnerability/deprecation counts, and dependency age. Symbol/SourceLink package evidence names the PDB source (`embedded`, `in-package`, `.snupkg`, `msdl.microsoft.com`). Custom feeds (`--nuget-source`, `--add-source`, `--nugetconfig`) and local `.nupkg` files are supported. + +For package structure, use `package X -S Manifest` to see manifest version/package/tool rows, `package X -S "Library Files"` to list all files under `lib/` across TFMs, and `package X -S All` to include opt-in sections such as Signals. ## Output and query workflow @@ -104,7 +111,7 @@ dnx dotnet-inspect -y -- member JsonSerializer --package System.Text.Json -S Met dnx dotnet-inspect -y -- library System.Text.Json -S "Async*" --count ``` -For `type` and `member`, `-D` reports the effective schema by default: only sections and columns that can render for that query. Add `--schema` for the static schema. `-S`, `--columns`, and `--fields` accept comma-separated or semicolon-separated lists. Use `--count` only when exactly one selected section should produce a row count. +For target-based queries, `-D` and bare `-S` report the effective schema by default: only sections and columns that can render for that query. Add `--schema` for the static schema. `-S`, `--columns`, and `--fields` accept comma-separated or semicolon-separated lists. In `--schema` section output, `section (opt-in)` means the section never runs from normal verbosity; select it explicitly with `-S` when needed, or use `-S All` to include all sections including opt-in sections. Use `--count` only when exactly one selected section should produce a row count. ## Relationship workflow @@ -123,4 +130,4 @@ Scopes include installed platform libraries by default, `--package Foo`, curated - `type` uses `-t` for type filters; `member` uses `-m` for member filters. - Dotted member syntax works: `-m JsonSerializer.Deserialize`. - Diff ranges use `..`: `--package Foo@1.0.0..2.0.0`. -- Use `--all` for non-public, hidden, and extra members; obsolete members are already shown by default. +- In API/member queries, use `--all` for non-public, hidden, and extra members; obsolete members are already shown by default. diff --git a/apm.lock.yaml b/apm.lock.yaml index bb72150..16d18f2 100644 --- a/apm.lock.yaml +++ b/apm.lock.yaml @@ -1,5 +1,5 @@ lockfile_version: '1' -generated_at: '2026-06-02T12:57:49.455909+00:00' +generated_at: '2026-06-05T15:57:36.696853+00:00' apm_version: 0.14.0 dependencies: - repo_url: Faithlife/RepoConventions @@ -13,10 +13,10 @@ dependencies: content_hash: sha256:b4c71ea6793ab8bbc481cf7fa25cf86c7f5c36caefcfbe68053860082191af57 - repo_url: richlander/dotnet-inspect host: github.com - resolved_commit: 06261f5f0d16b14712ff045f86ceb997f8833647 + resolved_commit: 4a7f92a264ba2ad911361bf4057ce68403f5e2e6 virtual_path: skills/dotnet-inspect is_virtual: true package_type: claude_skill deployed_files: - .agents/skills/dotnet-inspect - content_hash: sha256:bac00c8bc7b9120cf8243fa3b5295b510955e41ee8ffd6855270b2fdeb692ab5 + content_hash: sha256:c6040b904eafeb1a7c2fadba8cad8a9595f858723e32ceaa9794fb0937535834