From 968379dd87ea85a1a56dda773dce027df381fd2e Mon Sep 17 00:00:00 2001 From: "facility-bot[app]" Date: Mon, 22 Jun 2026 17:41:58 +0000 Subject: [PATCH] Update Facility .NET repository conventions --- .agents/skills/dotnet-inspect/SKILL.md | 187 ++++++++----------------- apm.lock.yaml | 6 +- 2 files changed, 59 insertions(+), 134 deletions(-) diff --git a/.agents/skills/dotnet-inspect/SKILL.md b/.agents/skills/dotnet-inspect/SKILL.md index bb55a8b..edec871 100644 --- a/.agents/skills/dotnet-inspect/SKILL.md +++ b/.agents/skills/dotnet-inspect/SKILL.md @@ -1,173 +1,98 @@ --- name: dotnet-inspect -version: 0.10.5 -description: Find evidence instead of guessing for .NET packages, platform libraries, local assemblies, APIs, dependencies, SourceLink/symbol provenance, and version-to-version API changes. +version: 0.12.0 +description: Find evidence instead of guessing for .NET packages, platform libraries, local assemblies, APIs, dependencies, SourceLink/source, and API version diffs. --- # dotnet-inspect -Use dotnet-inspect when you need evidence instead of guesses for .NET packages, platform libraries, local assemblies, APIs, dependencies, SourceLink/symbol provenance, or version-to-version API changes. - -Invoke with `dnx`: +Use dotnet-inspect when you need evidence instead of guesses for .NET packages, platform libraries, local assemblies, APIs, dependencies, SourceLink/source, or version-to-version API changes. ```bash dnx dotnet-inspect -y -- ``` -## Start with a command - -| Goal | Start with | Drill in | -| ---- | ---------- | -------- | -| Find the right API | `find Pattern` | `type Type --package Foo`, then `member Type --package Foo`. | -| Inspect a package | `package Foo` | Add `-S Signals`, `-S Manifest`, `-S "Library Files"`, or `--library` to inspect the package DLL. | -| Inspect a library or assembly | `library Foo` or `library path/to.dll` | Add `--platform`, `--package`, `-S Signals` when source matters, or `-S Integrations` when ecosystem support matters. | -| Inspect a type | `type Type --package Foo` | Add `--all` for non-public, hidden, and extra members. | -| Inspect members and overloads | `member Type --package Foo -m Name --show-index` | Use `Name:N` selectors for a specific overload. | -| Compare API versions | `diff --package Foo@old..new --breaking` | Use `--additive` for new APIs or `-t Type` to narrow. | -| Locate source or implementation | `source Type --package Foo` | For a selected overload use `member Type Member:1 -S "Original Source"`, `-S Calls`, `-S Callers`, `-S "Call Graph"`, or `-S IL`. | -| Audit unsafe calls | `library MyLib.dll -S @Audit` | Drill into a selected member with `member Type Method:N --library MyLib.dll -S @Audit`. | -| Explore relationships | `depends Type`, `extensions Type`, `implements Interface` | Add package, platform, or project scope as needed. | - -## Output modes +## Common starts -Default output is Markdown. Use Markdown for readable evidence with headings, section boundaries, tables, and code fences. Use `--table` for compact human scanning, `--tsv` for stable field splitting, `--jsonl` for one JSON object per table row, `--json` for structured object graphs, and `--mermaid` for graph-shaped output such as `depends`. +| Goal | Command | +| ---- | ------- | +| Find an API | `find Pattern`, then reuse the reported `--platform`, `--package`, or `--library`. | +| Inspect overloads | `member Type --platform Lib -m Name -S "Member Index"` | +| Select an overload | `member Type --platform Lib Name:1` or `Name~digest` | +| Source/implementation | `member Type Name:1 -S @Source`, `-S Calls`, `-S Callers`, `-S IL` | +| Inspect a type | `type Type --package Foo`; add `--all` for non-public/hidden/extra members. | +| Compare APIs | `diff --package Foo@old..new --breaking`; use `--additive` for new APIs. | +| Inspect packages | `package Foo -S Signals`, `-S "Library Files"`, `--library` | +| Inspect libraries | `library Foo` or `library path/to.dll`; add `--platform`, `--package`, `-S Signals`. | +| Relationships | `depends Type`, `extensions Type`, `implements Interface`; add package/platform/project scope. | -Markdown and JSON can represent multi-section documents. Table, TSV, and JSONL are single-table formats for commands or projections that produce one table. Mermaid is diagram output for commands that produce graph-shaped results. +## Member lookup workflow -Format promises: - -- Markdown table cell values do not contain escaped pipes (`\|`); pipe characters in values are normalized. -- `--tsv` table headers are stable snake_case keys, and cells never contain embedded tabs or newlines. -- `--jsonl` emits one compact JSON object per table row with stable snake_case property names. -- `--table` renders the same projection as `--tsv` and `--jsonl`, with each column starting at a uniform position across rows. - -## Limits - -Prefer built-in limiters to shell pipes. `-n N` and numeric shorthand like `-6` work like `head`; `--tail N` works like `tail`; add `--rows` to make head counts cap Markdown table data rows instead of output lines. Use `--count` to count rows in one selected table section. Use command-specific limiters for command-specific result sets: `-t N` limits type/find results, `-m N` limits member results, and `--versions N` limits package version lists. - -## Query system - -Use the query system when default views do not expose the detail you need. `-D` discovers available sections/columns; `-S Section` selects sections by name or wildcard; `--columns` and `--fields` project values. Discover first instead of guessing field names. - -```bash -dnx dotnet-inspect -y -- member JsonSerializer --package System.Text.Json -D --tsv -dnx dotnet-inspect -y -- member JsonSerializer --package System.Text.Json -D "Method Groups" --tsv -dnx dotnet-inspect -y -- member JsonSerializer --package System.Text.Json -m Serialize -D Methods --tsv -dnx dotnet-inspect -y -- member JsonSerializer --package System.Text.Json -m Serialize -S Methods --columns "Name;Signature" -dnx dotnet-inspect -y -- library System.Text.Json -S "Async*" --count -dnx dotnet-inspect -y -- library System.Text.Json -S "Async*" --rows -n 10 -``` - -`@` represents a category or grouping of sections. Bare `-S` renders `@Default`, a curated high-density view; `-S @All` renders an exhaustive document with all sections. Workflow categories such as `@Audit`, plus focused categories such as `@Integrations` and `@Switches`, expand to related sections. Sections marked opt-in must be selected explicitly with `-S`. Focused library/member `-S Section` output keeps a compact context row before the selected section. - -## General tips - -- Built-in aliases and common BCL types such as `string`, `int`, and `List` resolve without `--package`, `--platform`, or `--library`; start with `type string` or `type 'List'`. -- `type` supports URL-like namespace probing: unresolved namespace-ish names such as `System.Text` produce best-effort prefix matches, while exact package/library/platform matches keep normal precedence. -- After `find`, reuse the package/library it reports in follow-up commands. Use explicit `--platform`, `--package`, or `--library` when the source matters; for multi-library packages, include the `--library` value shown by `find`. -- Always quote generic type names in shell commands: `type 'List'`, `member 'Dictionary'`, or `type 'INumber'`. Use `` rather than `<>` for generic type queries. -- Wildcards are supported for type names and section/schema selection; quote shell patterns, such as `type 'Json*' --package System.Text.Json`, `-S "Async*"`, or `-D "SourceLink*"`. -- `type` uses `-t` for type filters; `member` uses `-m` for member filters. Dotted member syntax works: `-m JsonSerializer.Deserialize`. -- Member `Signature` values are single-line C# declarations and may include high-signal attributes such as `[Obsolete]`. -- Diff ranges use `..`: `--package Foo@1.0.0..2.0.0`. Obsolete members are shown by default; use `--all` for non-public, hidden, and extra members. -- Unpinned packages use the latest stable by default; add `--preview` when prerelease APIs matter. - -## API lookup workflow - -Use `find` when you do not know the package, library, or exact namespace. +Member lookup is a common flow. Use `find` when scope is unknown, then inspect the type, then use `Member Index` to find the overload to select. The bare router also accepts source-qualified member syntax when the source is obvious. ```bash dnx dotnet-inspect -y -- find JsonSerializer -dnx dotnet-inspect -y -- type System.Text -dnx dotnet-inspect -y -- type JsonSerializer --package System.Text.Json -dnx dotnet-inspect -y -- member JsonSerializer --package System.Text.Json -m Serialize --show-index -dnx dotnet-inspect -y -- depends Stream -dnx dotnet-inspect -y -- extensions HttpClient --reachable -dnx dotnet-inspect -y -- implements IJsonTypeInfoResolver --package System.Text.Json -``` - -Default type output is a compact type shape with inheritance, interfaces, logical member groups, and overload counts. For single-type output, `-v:n` and `-v:d` grow the tree to show overload leaves; use `--markdown -v:q` for compact Markdown section output. Narrow member-name views render overload rows with full signatures and stable `Name:N` selectors. Relationship scopes include installed platform libraries by default, `--package Foo`, curated `--aspnetcore`/`--extensions`, and `--project ./App.csproj`. The `extensions` command reports extension methods and C# extension properties. Add `--mermaid` to `depends` when a diagram is more useful than a table. - -## Upgrade and compatibility workflow - -Start with `diff`, then inspect the affected API. - -```bash -dnx dotnet-inspect -y -- diff --package System.Text.Json@9.0.0..10.0.0 --breaking -dnx dotnet-inspect -y -- diff --package System.Text.Json@9.0.0..10.0.0 --additive -dnx dotnet-inspect -y -- member JsonSerializer --package System.Text.Json@10.0.0 +dnx dotnet-inspect -y -- type JsonSerializer --platform System.Text.Json +dnx dotnet-inspect -y -- member JsonSerializer --platform System.Text.Json -m Serialize -S "Member Index" +dnx dotnet-inspect -y -- System.Text.Json.JsonSerializer.Serialize:1 -S Signature +dnx dotnet-inspect -y -- member JsonSerializer --platform System.Text.Json Serialize:1 -S Signature +dnx dotnet-inspect -y -- member JsonSerializer --platform System.Text.Json Serialize~1dc14dd1fb -S @Source +dnx dotnet-inspect -y -- member JsonSerializer --platform System.Text.Json Serialize:1 -S Calls +dnx dotnet-inspect -y -- member string IndexOf:7 -S Callers --caller-package System.Text.Json@9.0.0 --tfm net9.0 ``` -Use `--breaking` for migration work, `--additive` for release-note work, and `-t TypeName` to narrow noisy diffs. For .NET platform APIs, compare individual framework libraries: - -```bash -dnx dotnet-inspect -y -- diff --platform System.Runtime@9.0.0..10.0.0 --additive -``` +Selector syntax: first run `member Type --platform Lib -m Name -S "Member Index"` (or the package/library source `find` reported). Then pass either `Name:N` (1-based, for the current index) or `Name~digest` (stable, from the `Stable` column) as the positional member selector. `Canonical Signature` is the printed digest input. Prefer `Name~digest` in notes, scripts, issues, and handoffs; use `Name:N` for immediate drill-in. `--show-index` is an alias for `-S "Member Index"`. -## Source and implementation workflow +A selected overload defaults to `Signature`; bare `-S` adds `Decompiled Source`. Use `-S @Source` for source and IL evidence: `Decompiled Source` (raised C#), `Annotated Source` (C# with hidden-fact comments and interleaved IL), `Original Source`, and `IL`. Use `Annotated Source` or `IL` when exact opcodes, offsets, branches, tokens, or calls matter. -Use `source` for SourceLink URLs, source text, or token/IL-offset mapping. Use `member Type Member:N -S "Decompiled Source"` when you need a selected member's lowered C# body, `-S "Original Source"` for SourceLink-backed source text, `-S Calls` for direct call-site evidence, `-S Callers` for the reverse edges (methods that call the selected member; defaults to the member's own assembly, widen with `--bin ` / `--project ` / `--caller-package ` for cross-assembly callers), `-S "Call Graph"` for the bounded outbound call tree (callees, depth/node-capped, in-assembly), `-S "Unsafe*"` for unsafe API-member and operation evidence, `-S IL` for raw IL, `-S "Annotated Source"` for the mixed view (C# with hidden-fact comments — allocations, unsafety, lifetime — and the IL interleaved beneath each statement), or `-S "Facts"` for the same hidden facts as a structured table (`--tsv` for agents). +Use `-S Calls` for direct call-site evidence, `-S Callers` for reverse edges (widen with `--bin`, `--project`, or `--caller-package`), `-S "Call Graph"` for a bounded outbound tree, `-S "Unsafe Operations"` for unsafe evidence, and `-S Facts --tsv` for structured hidden facts. -```bash -dnx dotnet-inspect -y -- source JsonSerializer --package System.Text.Json -dnx dotnet-inspect -y -- member JsonSerializer --package System.Text.Json Serialize:1 -S "Decompiled Source" -dnx dotnet-inspect -y -- member JsonSerializer --package System.Text.Json Serialize:1 -S Calls -dnx dotnet-inspect -y -- member JsonSerializer --package System.Text.Json Serialize:1 -S Callers -dnx dotnet-inspect -y -- member string IndexOf:7 -S Callers --caller-package System.Text.Json@9.0.0 --tfm net9.0 -dnx dotnet-inspect -y -- member MyApi.Helper Run:1 --library MyLib.dll --bin ./app/bin/Release/net10.0 -dnx dotnet-inspect -y -- member JsonSerializer --package System.Text.Json Serialize:1 -S "Call Graph" -dnx dotnet-inspect -y -- library MyLib.dll -S @Audit -``` +## Query and output -A selected overload defaults to `Signature`; use bare `-S` for `Signature` plus `Decompiled Source`, or select `Original Source`, `IL`, or `Annotated Source` when you need specific implementation evidence. +Default output is Markdown. Use `--table` for compact aligned rows, `--tsv` for stable snake_case headers with no embedded tabs/newlines, `--jsonl` for one JSON object per row, `--json` for structured documents, and `--mermaid` for graph-shaped output. -When `Decompiled Source` looks wrong and you need to see *how* the decompiler raised IL to C#, dump the per-pass IR pipeline (JitDump-style) with `--dump-stages` (or `-S "IR (Stages)"`): it prints the typed IR tree after import and after each raising pass, so you can spot which pass introduced a defect. Like the other code sections it needs a selected overload (`--index N`/`Name:N`/`--params`), and it is a deep decompiler-debugging view — not a normal lookup path. +Use `-D` to discover sections/columns, `-S Section` to select sections by name or wildcard, and `--columns`/`--fields` to project values. Discover first instead of guessing names. ```bash -dnx dotnet-inspect -y -- member string -m IsNullOrEmpty:1 --dump-stages --raw +dnx dotnet-inspect -y -- member JsonSerializer --platform System.Text.Json -D --tsv +dnx dotnet-inspect -y -- member JsonSerializer --platform System.Text.Json -m Serialize -D "Member Index" --tsv +dnx dotnet-inspect -y -- member JsonSerializer --platform System.Text.Json -m Serialize -S "Member Index" --columns "Selector;Stable;Canonical Signature" --tsv ``` -To read a whole type instead of one member, use `type Name -S "Decompiled Source"`: it renders the entire type as one C# listing — declaration, fields (including non-public, for context), and every member body. Add `--raw` to print only the bare listing (no headings or code fences), suitable for redirecting to a file: +`@` names a category: `-S @All`, `-S @Source`, `-S @Audit`, `-S @Integrations`, `-S @Switches`. Row formats (`--tsv`/`--jsonl`/`--table`) work best with one concrete section, not a category. -```text -dnx dotnet-inspect -y -- type Stack --platform System.Collections -S "Decompiled Source" --raw > Stack.cs -``` - -Fidelity expectations: `Original Source` is the SourceLink-backed original source when available. `Decompiled Source` is lowered C#, a best-effort readable reconstruction from IL that helps explain intent; it uses PDB debug information such as local names when available, but is not guaranteed to match original syntax or compiler transformations. Raw IL and the interleaved IL in `Annotated Source` are the highest-fidelity displays for exact opcodes, offsets, branches, tokens, and member calls; use them to confirm behavior when precision matters. +## Limits -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. +Prefer built-in limits to shell pipes. `-n N` and numeric shorthand like `-6` cap output lines; `--tail N` shows the end; `--rows` makes `-n` cap Markdown table data rows; `--count` counts rows in one selected table. Command-specific caps: `-t N` for type/find rows, `-m N` for members, and `--versions N` for package versions. -## Unsafe call audit workflow +## Package docs, libraries, and signals -Start with the library/type roll-up, then drill into a selected overload for exact evidence. +For agent-readable package docs, use `--path @readme --content`; the resolver exposes the best README content for agents, preferring `AGENTS.md` over `README.md` when present. For multi-package doc surveys, pass multiple package IDs with `--path @readme --jsonl` for metadata rows or `--path @readme --content --jsonl` for content rows. Add `--frontmatter`/`--yaml-header` or `--body` with `--content`; keep `--readme` for single-package reads. ```bash -dnx dotnet-inspect -y -- library MyLib.dll -S @Audit -dnx dotnet-inspect -y -- member MyType MyMethod:1 --library MyLib.dll -S @Audit -dnx dotnet-inspect -y -- member MyType MyMethod:1 --library MyLib.dll -S "Calls,IL" +dnx dotnet-inspect -y -- package Microsoft.Extensions.AI -S Signals +dnx dotnet-inspect -y -- package Microsoft.Extensions.AI --path @readme --content --frontmatter +dnx dotnet-inspect -y -- package Microsoft.Extensions.AI Microsoft.Extensions.AI.OpenAI --path @readme --content --jsonl +dnx dotnet-inspect -y -- project ./App --agents-index --jsonl +dnx dotnet-inspect -y -- package Microsoft.Extensions.AI --library -S @Integrations +dnx dotnet-inspect -y -- library System.Text.Json -S Switches ``` -At library/type scope, `@Audit` surfaces unsafe members, P/Invoke, and switch evidence. On a selected member, `@Audit` expands to signature, direct calls, unsafe operations, and IL; use the `IL` offsets and metadata tokens to confirm the exact binary evidence. - -## Package, library, integrations, and Signals workflow +Use `package Foo --library` for the primary DLL when unambiguous; add a DLL name or use `--all-libraries` for multi-library packages. `Signals` reports observations, not trust: SourceLink, determinism, trim/AOT, memory-safety metadata, unsafe/PInvoke, references, TFMs, manifest/docs, license, vulnerabilities, package age, and dependency risk. -Use `package` for NuGet package structure and registry-backed signals. Use `library` for assembly metadata, APIs, PDB/SourceLink evidence, direct references, and unsafe-member audits. +## Other workflows -```bash -dnx dotnet-inspect -y -- package System.Text.Json -S Signals -dnx dotnet-inspect -y -- package System.Text.Json -S "Library Files" -dnx dotnet-inspect -y -- package Aspire.Azure.AI.OpenAI --library -S @Integrations -dnx dotnet-inspect -y -- library System.Text.Json -S Signals -dnx dotnet-inspect -y -- library System.Text.Json -S Switches -dnx dotnet-inspect -y -- library System.Diagnostics.DiagnosticSource -S OpenTelemetry -``` +Use `diff --package Foo@old..new --breaking` for migration work, `--additive` for release-note work, and `-t Type` to narrow. For platform APIs, compare individual libraries: `diff --platform System.Runtime@9.0.0..10.0.0 --additive`. -`Signals` reports observations, not a safety or trust verdict. Library Signals include SourceLink presence, SourceLink availability, determinism, trim/AOT markers, async kind (`Runtime`, `State machine`, `Mixed`, or `None`), memory-safety metadata, unsafe/PInvoke observations, and direct references. Package Signals include TFMs, manifest, readme/license, dependencies, package signature, local provenance, vulnerabilities, package age, dependency vulnerability/deprecation counts, and dependency age. +For unsafe audits, start with `library MyLib.dll -S @Audit`, then drill into `member Type Method:1 --library MyLib.dll -S "Unsafe Operations,IL"`. -Use `package Foo --library` to inspect the package's primary DLL when it is unambiguous; add a DLL name when a package contains multiple libraries. Use `package Foo --all-libraries` when a package contains multiple relevant DLLs or a tool package carries libraries under `tools/`; aggregate Markdown sections such as `@Integrations` include library provenance when needed. For row modes such as `--tsv`/`--jsonl`, select one concrete section such as `Integrations` or `OpenTelemetry`, not a category like `@Integrations`. Use `-S Integrations` for the ecosystem roll-up, `-S @Integrations` for roll-up plus focused sections, or a focused section such as `OpenTelemetry`. Integration sections cover AI, ASP.NET Core, Aspire resources, Authentication, Configuration, Dependency Injection, Logging, Options, Hosting, Health Checks, HTTP Client, OpenAPI, and OpenTelemetry. Focused sections list package-owned starter APIs, support types, and telemetry controls, not raw assembly references. +Use `type Name -S "Decompiled Source" --raw` for a whole-type C# listing. Use `source --il-offset 0x06000001+0x5` for crash diagnostics with MethodDef token plus IL offset. If decompiled output looks wrong, capture `Decompiled Source`, `Annotated Source`, `Original Source`, and `IL`; maintainers diagnose pipeline state with DecompilerHarness. -Use `-S Switches` when runtime feature switches or compatibility switches may affect behavior. - -`library X -S Signals` resolves SourceLink by acquiring a missing PDB. Per-source-file reachability is opt-in: add `-S "SourceLink Availability"` and `-S "SourceLink Missing Files"` for HTTP HEAD checks, or `-S "SourceLink Integrity"` to download source files and compare checksums. For .NET tool packages, inspect the tool DLL through the package context, for example `library dotnet-inspect.dll --package dotnet-inspect@ -S "SourceLink Integrity"`. Tool v2 pointer/RID packages resolve to their inspectable framework-dependent payload. +## General tips -For BCL/runtime-pack assemblies that are misleading as standalone packages, prefer `library --platform Lib --version ` or a direct DLL path. +- Built-in aliases and common BCL types resolve without scope: `type string`, `type 'List'`. +- Quote generic type names and shell patterns: `member 'Dictionary'`, `-S "Async*"`. +- After `find`, reuse the package/library it reports; add `--library` for multi-library packages. +- `type` uses `-t` for type filters; `member` uses `-m` for member filters. +- Unpinned packages use latest stable; add `--preview` for prerelease APIs. +- If behavior is surprising, rerun with `--trace-mermaid` and include stderr in bug reports. diff --git a/apm.lock.yaml b/apm.lock.yaml index b3b012e..3e91338 100644 --- a/apm.lock.yaml +++ b/apm.lock.yaml @@ -1,5 +1,5 @@ lockfile_version: '1' -generated_at: '2026-06-19T16:08:19.152322+00:00' +generated_at: '2026-06-22T17:41:58.841282+00:00' apm_version: 0.14.0 dependencies: - repo_url: Faithlife/RepoConventions @@ -13,10 +13,10 @@ dependencies: content_hash: sha256:6e4dc45d96d7adc8f1d3e3300d9ee90eef9c2d0231ea83ad86fed64fca105034 - repo_url: richlander/dotnet-inspect host: github.com - resolved_commit: 6745978a216375a68cd19a80d9e892204c2e5c59 + resolved_commit: 0abdc4de48bb2efe9b3eaed39d2daa7aa3e6b534 virtual_path: skills/dotnet-inspect is_virtual: true package_type: claude_skill deployed_files: - .agents/skills/dotnet-inspect - content_hash: sha256:63c7334e7df7b87c0dda52c1dec0b7e337112f4b9790ade3d4f4bbd5cb258c61 + content_hash: sha256:da19863fa0a920a6eb3efef70b44fb618cc0c8492771ecf8130f50bb01b1e6c2