From 927eebc589bc98841beca464eced930814820e67 Mon Sep 17 00:00:00 2001 From: "facility-bot[app]" Date: Mon, 29 Jun 2026 16:43:07 +0000 Subject: [PATCH] Update Facility .NET repository conventions --- .agents/skills/dotnet-inspect/SKILL.md | 90 ++++++-------------------- apm.lock.yaml | 6 +- 2 files changed, 24 insertions(+), 72 deletions(-) diff --git a/.agents/skills/dotnet-inspect/SKILL.md b/.agents/skills/dotnet-inspect/SKILL.md index 6e04d1f..c58cd59 100644 --- a/.agents/skills/dotnet-inspect/SKILL.md +++ b/.agents/skills/dotnet-inspect/SKILL.md @@ -1,12 +1,14 @@ --- name: dotnet-inspect -version: 0.13.0 -description: Find evidence instead of guessing for .NET packages, platform libraries, local assemblies, APIs, dependencies, SourceLink/source, and API version diffs. +version: 0.14.0 +description: Find evidence instead of guessing for .NET packages, platform libraries, local assemblies, APIs, dependencies, and version-to-version API changes. --- # dotnet-inspect -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. +Use dotnet-inspect for evidence instead of guesses about .NET packages, platform +libraries, assemblies, APIs, dependencies, or API version diffs. Focused skills +are listed at the end. ```bash dnx dotnet-inspect -y -- @@ -17,82 +19,32 @@ dnx dotnet-inspect -y -- | Goal | Command | | ---- | ------- | | Find an API | `find Pattern`, then reuse the reported `--platform`, `--package`, or `--library`. | +| Inspect a type | `type Type --package Foo`; add `--all` for non-public/hidden members. | | 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 | `type Type -S "Source Files"`; `member Type -m Name -S "Source Locations"`; `member Type Name:1 -S @Source`; `library/package Foo -S "Source Files"` | -| 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. | +| Compare APIs | `diff --package Foo@old..new --breaking` (`--additive` new APIs); `--alloc-regressions` for perf regressions (allocations up, hot first). | +| Inspect packages | `package Foo -S Signals`, `--library`, `--path @readme --content`. | +| Inspect libraries | `library Foo` or `library path/to.dll`; add `--platform`, `-S Signals`. | +| Relationships | `depends Type`, `extensions Type`, `implements Interface`. | -## Member lookup workflow +## Member lookup -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. +Run `find Name` when scope is unknown, inspect the type, then `-S "Member Index"` +to list overloads. Select with `Name:N` (1-based) or `Name~digest` (stable). A +selected overload defaults to `Signature`. You can also pass a fully-qualified +`Namespace.Type.Member` and the tool finds the type/member split — no scope. ```bash dnx dotnet-inspect -y -- find JsonSerializer -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 +dnx dotnet-inspect -y -- member System.Text.Json.JsonSerializer.Serialize -S "Member Index" ``` -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"`. +## Tips -A selected overload defaults to `Signature`; bare `-S` adds `Decompiled Source`. Use `-S "Source Locations"` for member file/line URLs without fetching source bodies. 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 `-S Calls` for direct call-site evidence, `-S Callers` for reverse edges (widen with `--bin`, `--project`, or `--caller-package`), `-S "Unsafe Operations"` for unsafe evidence, and `-S Facts --tsv` for structured hidden facts. - -## Query and output - -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, `--bare` for one undecorated payload or URL list, `--count` for a bare row count, and `--mermaid` for graph-shaped output. - -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 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 -``` - -`@` 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. - -## Limits - -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. - -## Package docs, libraries, and signals - -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 -- 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 "Source Files" -``` - -Use `package Foo --library` for the primary DLL when unambiguous; add a DLL name or use `--all-libraries` for multi-library packages. Use `-S "Source Files"` for SourceLink type-to-URL rows. `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. - -## Other workflows - -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`. - -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 `--bare` to extract one undecorated payload: `type Name -S "Decompiled Source" --bare`, `member Type Method:1 -S "Source Locations" --bare`, or `package Foo --readme --bare`. SourceLink URLs default to raw/fetchable form; add `--blob` for browser URLs. Use `library Foo --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. - -## General tips - -- 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. +- Default output is Markdown; for formats, `-D`/`-S` discovery, projection, and + limits, load `dotnet-inspect skill query`. +- Common BCL types resolve without scope: `type string`, `type 'List'`. Quote + generics and patterns: `member 'Dictionary'`, `-S "Async*"`. - 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 38089e5..702d950 100644 --- a/apm.lock.yaml +++ b/apm.lock.yaml @@ -1,5 +1,5 @@ lockfile_version: '1' -generated_at: '2026-06-25T15:46:42.256474+00:00' +generated_at: '2026-06-29T16:43:06.988910+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: e0710ec1780b8e0893dfb3c7417c469ec3248a36 + resolved_commit: 77dbcf900ae78d8f977179ce368eb69c3aaffb20 virtual_path: skills/dotnet-inspect is_virtual: true package_type: claude_skill deployed_files: - .agents/skills/dotnet-inspect - content_hash: sha256:091c8576b7d3b25fdca8104aeb2d343206b5531bdc79db067d018e59f072a8b7 + content_hash: sha256:ac7e3f9ed53d5bb058a6b3d509ef670c8dcc71f1890a7aba0ad477667626efa9