Skip to content

Commit df28fde

Browse files
DJGosnellclaude
DJGosnell
and
claude
authored
Add NuGet package READMEs and CodeFixes listing (#1)
* Add NuGet package READMEs and CodeFixes package listing - Add Quarry.Analyzers.CodeFixes to packages table in all READMEs - Create project-local READMEs for Quarry.Generator, Quarry.Analyzers, and Quarry.Analyzers.CodeFixes - Add standard Quarry header with logo to all sub-project READMEs - Add IsPackable=true to Generator, Analyzers, and Analyzers.CodeFixes csproj files - Fix Directory.Build.targets StripImgTags to use each project's own README via PackageReadmeSource property - Quarry project uses root README.md via PackageReadmeSource override Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add package icon to all NuGet packages Include logo-128.png in all packable projects via Directory.Build.targets and set PackageIcon in Directory.Build.props. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 4438723 commit df28fde

11 files changed

Lines changed: 241 additions & 1 deletion

File tree

‎Directory.Build.props‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,5 +15,6 @@
1515
<RepositoryType>git</RepositoryType>
1616
<PackageTags>sql;orm;aot;source-generator;database</PackageTags>
1717
<PackageReadmeFile>README.md</PackageReadmeFile>
18+
<PackageIcon>logo-128.png</PackageIcon>
1819
</PropertyGroup>
1920
</Project>

‎Directory.Build.targets‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,16 @@
1919
</Task>
2020
</UsingTask>
2121

22+
<PropertyGroup>
23+
<PackageReadmeSource Condition="'$(PackageReadmeSource)' == ''">$(MSBuildProjectDirectory)/README.md</PackageReadmeSource>
24+
</PropertyGroup>
25+
2226
<Target Name="StripHtmlImages" BeforeTargets="_GetPackageFiles" Condition="'$(IsPackable)' == 'true'">
23-
<StripImgTags InputFile="$(MSBuildThisFileDirectory)README.md"
27+
<StripImgTags InputFile="$(PackageReadmeSource)"
2428
OutputFile="$(IntermediateOutputPath)README.md" />
2529
<ItemGroup>
2630
<None Include="$(IntermediateOutputPath)README.md" Pack="true" PackagePath="\" />
31+
<None Include="$(MSBuildThisFileDirectory)docs/images/logo-128.png" Pack="true" PackagePath="\" />
2732
</ItemGroup>
2833
</Target>
2934
</Project>

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ Type-safe SQL builder for .NET 10. Source generators + C# 12 interceptors emit a
2828
| [`Quarry`](https://www.nuget.org/packages/Quarry) | [![Quarry](https://img.shields.io/nuget/v/Quarry.svg?maxAge=60)](https://www.nuget.org/packages/Quarry) | Runtime types: builders, schema DSL, dialects, executors. |
2929
| [`Quarry.Generator`](https://www.nuget.org/packages/Quarry.Generator) | [![Quarry.Generator](https://img.shields.io/nuget/v/Quarry.Generator.svg?maxAge=60)](https://www.nuget.org/packages/Quarry.Generator) | Roslyn incremental source generator + interceptor emitter. |
3030
| [`Quarry.Analyzers`](https://www.nuget.org/packages/Quarry.Analyzers) | [![Quarry.Analyzers](https://img.shields.io/nuget/v/Quarry.Analyzers.svg?maxAge=60)](https://www.nuget.org/packages/Quarry.Analyzers) | Compile-time SQL query analysis rules (QRA series) with code fixes. |
31+
| [`Quarry.Analyzers.CodeFixes`](https://www.nuget.org/packages/Quarry.Analyzers.CodeFixes) | [![Quarry.Analyzers.CodeFixes](https://img.shields.io/nuget/v/Quarry.Analyzers.CodeFixes.svg?maxAge=60)](https://www.nuget.org/packages/Quarry.Analyzers.CodeFixes) | Code fix providers for QRA diagnostics. |
3132
| [`Quarry.Tool`](https://www.nuget.org/packages/Quarry.Tool) | [![Quarry.Tool](https://img.shields.io/nuget/v/Quarry.Tool.svg?maxAge=60)](https://www.nuget.org/packages/Quarry.Tool) | CLI tool for migrations and database scaffolding (`quarry` command). |
3233

3334
---

‎src/Quarry.Analyzers.CodeFixes/Quarry.Analyzers.CodeFixes.csproj‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
<ImplicitUsings>enable</ImplicitUsings>
66
<EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules>
77
<IsRoslynComponent>true</IsRoslynComponent>
8+
<IsPackable>true</IsPackable>
89
<NoWarn>$(NoWarn);RS2008</NoWarn>
910
</PropertyGroup>
1011

‎src/Quarry.Analyzers.CodeFixes/README.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# <img src="../../docs/images/logo-128.png" height="48"> Quarry
2+
3+
Type-safe SQL builder for .NET 10. Source generators + C# 12 interceptors emit all SQL at compile time. AOT compatible. Structured logging via Logsmith.
4+
5+
---
6+
7+
# Quarry.Analyzers.CodeFixes
8+
9+
Code fix providers for Quarry analyzer diagnostics. Adds IDE lightbulb actions that automatically rewrite flagged query patterns.
10+
11+
## Packages
12+
13+
| Name | NuGet | Description |
14+
|------|-------|-------------|
15+
| [`Quarry`](https://www.nuget.org/packages/Quarry) | [![Quarry](https://img.shields.io/nuget/v/Quarry.svg?maxAge=60)](https://www.nuget.org/packages/Quarry) | Runtime types: builders, schema DSL, dialects, executors. |
16+
| [`Quarry.Generator`](https://www.nuget.org/packages/Quarry.Generator) | [![Quarry.Generator](https://img.shields.io/nuget/v/Quarry.Generator.svg?maxAge=60)](https://www.nuget.org/packages/Quarry.Generator) | Roslyn incremental source generator + interceptor emitter. |
17+
| [`Quarry.Analyzers`](https://www.nuget.org/packages/Quarry.Analyzers) | [![Quarry.Analyzers](https://img.shields.io/nuget/v/Quarry.Analyzers.svg?maxAge=60)](https://www.nuget.org/packages/Quarry.Analyzers) | Compile-time SQL query analysis rules (QRA series) with code fixes. |
18+
| [`Quarry.Analyzers.CodeFixes`](https://www.nuget.org/packages/Quarry.Analyzers.CodeFixes) | [![Quarry.Analyzers.CodeFixes](https://img.shields.io/nuget/v/Quarry.Analyzers.CodeFixes.svg?maxAge=60)](https://www.nuget.org/packages/Quarry.Analyzers.CodeFixes) | Code fix providers for QRA diagnostics. |
19+
| [`Quarry.Tool`](https://www.nuget.org/packages/Quarry.Tool) | [![Quarry.Tool](https://img.shields.io/nuget/v/Quarry.Tool.svg?maxAge=60)](https://www.nuget.org/packages/Quarry.Tool) | CLI tool for migrations and database scaffolding (`quarry` command). |
20+
21+
---
22+
23+
## Installation
24+
25+
```xml
26+
<PackageReference Include="Quarry.Analyzers.CodeFixes" Version="1.0.0"
27+
OutputItemType="Analyzer"
28+
ReferenceOutputAssembly="false" />
29+
```
30+
31+
Requires `Quarry.Analyzers` to be referenced in the same project. The code fixes act on diagnostics reported by the analyzer package.
32+
33+
---
34+
35+
## Available Code Fixes
36+
37+
| Diagnostic | Fix Title | Transformation |
38+
|------------|-----------|----------------|
39+
| QRA101 | Replace Count() comparison with Any() | Rewrites `Count() > 0` to `Any()`, `Count() == 0` to `!Any()`. Handles async variants. |
40+
| QRA102 | Replace single-value Contains with == | Rewrites `new[] { x }.Contains(col)` to `col == x`. |
41+
| QRA201 | Remove unused join | Removes the `.Join(...)` call from the query chain, preserving the receiver. |
42+
43+
---
44+
45+
## Examples
46+
47+
### QRA101 — Count to Any
48+
49+
```csharp
50+
// Before (flagged by QRA101)
51+
var hasOrders = await db.Users
52+
.Where(u => u.Orders.Count() > 0)
53+
.ExecuteFetchAllAsync();
54+
55+
// After fix applied
56+
var hasOrders = await db.Users
57+
.Where(u => u.Orders.Any())
58+
.ExecuteFetchAllAsync();
59+
```
60+
61+
### QRA102 — Single-value IN to Equals
62+
63+
```csharp
64+
// Before (flagged by QRA102)
65+
db.Users.Where(u => new[] { 42 }.Contains(u.UserId));
66+
67+
// After fix applied
68+
db.Users.Where(u => u.UserId == 42);
69+
```
70+
71+
### QRA201 — Remove Unused Join
72+
73+
```csharp
74+
// Before (flagged by QRA201)
75+
db.Users.Join<Order>((u, o) => u.UserId == o.UserId.Id)
76+
.Select((u, o) => u.UserName); // 'o' never used
77+
78+
// After fix applied
79+
db.Users
80+
.Select(u => u.UserName);
81+
```

‎src/Quarry.Analyzers/Quarry.Analyzers.csproj‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
<EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules>
77
<IsRoslynComponent>true</IsRoslynComponent>
88
<BuildOutputTargetFolder>analyzers/dotnet/cs</BuildOutputTargetFolder>
9+
<IsPackable>true</IsPackable>
910
<NoWarn>$(NoWarn);RS2008</NoWarn>
1011
</PropertyGroup>
1112

‎src/Quarry.Analyzers/README.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# <img src="../../docs/images/logo-128.png" height="48"> Quarry
2+
3+
Type-safe SQL builder for .NET 10. Source generators + C# 12 interceptors emit all SQL at compile time. AOT compatible. Structured logging via Logsmith.
4+
5+
---
6+
7+
# Quarry.Analyzers
8+
9+
Compile-time SQL query analysis rules for Quarry. 18 Roslyn diagnostics detect performance issues, wasteful patterns, and dialect-specific problems in Quarry query call sites.
10+
11+
## Packages
12+
13+
| Name | NuGet | Description |
14+
|------|-------|-------------|
15+
| [`Quarry`](https://www.nuget.org/packages/Quarry) | [![Quarry](https://img.shields.io/nuget/v/Quarry.svg?maxAge=60)](https://www.nuget.org/packages/Quarry) | Runtime types: builders, schema DSL, dialects, executors. |
16+
| [`Quarry.Generator`](https://www.nuget.org/packages/Quarry.Generator) | [![Quarry.Generator](https://img.shields.io/nuget/v/Quarry.Generator.svg?maxAge=60)](https://www.nuget.org/packages/Quarry.Generator) | Roslyn incremental source generator + interceptor emitter. |
17+
| [`Quarry.Analyzers`](https://www.nuget.org/packages/Quarry.Analyzers) | [![Quarry.Analyzers](https://img.shields.io/nuget/v/Quarry.Analyzers.svg?maxAge=60)](https://www.nuget.org/packages/Quarry.Analyzers) | Compile-time SQL query analysis rules (QRA series) with code fixes. |
18+
| [`Quarry.Analyzers.CodeFixes`](https://www.nuget.org/packages/Quarry.Analyzers.CodeFixes) | [![Quarry.Analyzers.CodeFixes](https://img.shields.io/nuget/v/Quarry.Analyzers.CodeFixes.svg?maxAge=60)](https://www.nuget.org/packages/Quarry.Analyzers.CodeFixes) | Code fix providers for QRA diagnostics. |
19+
| [`Quarry.Tool`](https://www.nuget.org/packages/Quarry.Tool) | [![Quarry.Tool](https://img.shields.io/nuget/v/Quarry.Tool.svg?maxAge=60)](https://www.nuget.org/packages/Quarry.Tool) | CLI tool for migrations and database scaffolding (`quarry` command). |
20+
21+
---
22+
23+
## Installation
24+
25+
```xml
26+
<PackageReference Include="Quarry.Analyzers" Version="1.0.0"
27+
OutputItemType="Analyzer"
28+
ReferenceOutputAssembly="false" />
29+
```
30+
31+
Requires `Quarry` and `Quarry.Generator` to be referenced in the same project.
32+
33+
---
34+
35+
## Diagnostic Rules
36+
37+
All rules are enabled by default. Suppress individual rules via `#pragma`, `.editorconfig`, or `[SuppressMessage]`.
38+
39+
### QRA1xx — Simplification
40+
41+
| ID | Title | Severity | What it detects |
42+
|----|-------|----------|-----------------|
43+
| QRA101 | Count compared to zero | Info | `Count() > 0`, `Count() == 0` — use `Any()` instead |
44+
| QRA102 | Single-value IN clause | Info | `IN (@p0)` with one value — simplify to `==` |
45+
| QRA103 | Tautological condition | Info | Always-true conditions (`1 = 1`, `col = col`) |
46+
| QRA104 | Contradictory condition | Info | Always-false conditions (`x > 5 AND x < 3`) |
47+
| QRA105 | Redundant condition | Info | Subsumed conditions (`x > 5 AND x > 3`) |
48+
| QRA106 | Nullable without null check | Info | Nullable column in `==` comparison without null handling |
49+
50+
### QRA2xx — Wasted Work
51+
52+
| ID | Title | Severity | What it detects |
53+
|----|-------|----------|-----------------|
54+
| QRA201 | Unused join | Warning | Joined table not referenced in SELECT, WHERE, or ORDER BY |
55+
| QRA202 | Wide table SELECT * | Info | `Select(u => u)` on tables exceeding column threshold |
56+
| QRA203 | ORDER BY without LIMIT | Info | Sorting without pagination on unbounded result sets |
57+
| QRA204 | Duplicate projection column | Info | Same column projected multiple times in SELECT |
58+
| QRA205 | Cartesian product | Warning | JOIN with missing or trivial ON condition (`1 = 1`) |
59+
60+
### QRA3xx — Performance
61+
62+
| ID | Title | Severity | What it detects |
63+
|----|-------|----------|-----------------|
64+
| QRA301 | Leading wildcard LIKE | Info | `Contains()` → `LIKE '%…%'` prevents index usage |
65+
| QRA302 | Function on column in WHERE | Info | `LOWER()`, `UPPER()`, `TRIM()`, etc. on columns in WHERE |
66+
| QRA303 | OR across different columns | Info | `col1 = x OR col2 = y` prevents single-index scan |
67+
| QRA304 | WHERE on non-indexed column | Info | Filter on column not covered by any declared index |
68+
69+
### QRA4xx — Patterns
70+
71+
| ID | Title | Severity | What it detects |
72+
|----|-------|----------|-----------------|
73+
| QRA401 | Query inside loop | Warning | Execution method inside `for`/`foreach`/`while`/LINQ — N+1 risk |
74+
| QRA402 | Multiple queries on same table | Info | Multiple independent queries on the same entity in one method |
75+
76+
### QRA5xx — Dialect
77+
78+
| ID | Title | Severity | What it detects |
79+
|----|-------|----------|-----------------|
80+
| QRA501 | Dialect optimization available | Info | PostgreSQL: suggest `ILIKE` over `LOWER() + LIKE`; SQLite: suggest `COLLATE NOCASE` |
81+
| QRA502 | Suboptimal for dialect | Warning | SQLite: `RIGHT JOIN` unsupported; SQL Server: `OFFSET` requires `ORDER BY` |
82+
83+
---
84+
85+
## Configuration
86+
87+
### EditorConfig
88+
89+
```ini
90+
# .editorconfig
91+
[*.cs]
92+
# Column threshold for QRA202 (wide table SELECT *), default: 10
93+
quarry_analyzers.wide_table_column_count = 12
94+
```
95+
96+
### Suppressing Rules
97+
98+
```ini
99+
# .editorconfig — suppress a rule project-wide
100+
[*.cs]
101+
dotnet_diagnostic.QRA203.severity = none
102+
```
103+
104+
```csharp
105+
// Per-site suppression
106+
#pragma warning disable QRA301
107+
var results = await db.Users
108+
.Where(u => u.UserName.Contains(search))
109+
.ExecuteFetchAllAsync();
110+
#pragma warning restore QRA301
111+
```
112+
113+
---
114+
115+
## Severity Summary
116+
117+
Four rules default to **Warning** — these indicate likely bugs or significant performance issues:
118+
119+
| ID | Rule |
120+
|----|------|
121+
| QRA201 | Unused join |
122+
| QRA205 | Cartesian product |
123+
| QRA401 | Query inside loop (N+1) |
124+
| QRA502 | Suboptimal for dialect |
125+
126+
The remaining 14 rules default to **Info** — suggestions that may or may not apply depending on context.

‎src/Quarry.Generator/Quarry.Generator.csproj‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
<!-- Package metadata -->
1616
<PackageId>Quarry.Generator</PackageId>
1717
<Description>Source generators and analyzers for Quarry SQL builder</Description>
18+
<IsPackable>true</IsPackable>
1819
<DevelopmentDependency>true</DevelopmentDependency>
1920
<IncludeBuildOutput>true</IncludeBuildOutput>
2021
<BuildOutputTargetFolder>analyzers/dotnet/cs</BuildOutputTargetFolder>

‎src/Quarry.Generator/README.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# <img src="../../docs/images/logo-128.png" height="48"> Quarry
2+
3+
Type-safe SQL builder for .NET 10. Source generators + C# 12 interceptors emit all SQL at compile time. AOT compatible. Structured logging via Logsmith.
4+
5+
---
6+
7+
## Packages
8+
9+
| Name | NuGet | Description |
10+
|------|-------|-------------|
11+
| [`Quarry`](https://www.nuget.org/packages/Quarry) | [![Quarry](https://img.shields.io/nuget/v/Quarry.svg?maxAge=60)](https://www.nuget.org/packages/Quarry) | Runtime types: builders, schema DSL, dialects, executors. |
12+
| [`Quarry.Generator`](https://www.nuget.org/packages/Quarry.Generator) | [![Quarry.Generator](https://img.shields.io/nuget/v/Quarry.Generator.svg?maxAge=60)](https://www.nuget.org/packages/Quarry.Generator) | Roslyn incremental source generator + interceptor emitter. |
13+
| [`Quarry.Analyzers`](https://www.nuget.org/packages/Quarry.Analyzers) | [![Quarry.Analyzers](https://img.shields.io/nuget/v/Quarry.Analyzers.svg?maxAge=60)](https://www.nuget.org/packages/Quarry.Analyzers) | Compile-time SQL query analysis rules (QRA series) with code fixes. |
14+
| [`Quarry.Analyzers.CodeFixes`](https://www.nuget.org/packages/Quarry.Analyzers.CodeFixes) | [![Quarry.Analyzers.CodeFixes](https://img.shields.io/nuget/v/Quarry.Analyzers.CodeFixes.svg?maxAge=60)](https://www.nuget.org/packages/Quarry.Analyzers.CodeFixes) | Code fix providers for QRA diagnostics. |
15+
| [`Quarry.Tool`](https://www.nuget.org/packages/Quarry.Tool) | [![Quarry.Tool](https://img.shields.io/nuget/v/Quarry.Tool.svg?maxAge=60)](https://www.nuget.org/packages/Quarry.Tool) | CLI tool for migrations and database scaffolding (`quarry` command). |

‎src/Quarry.Tool/README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
# <img src="../../docs/images/logo-128.png" height="48"> Quarry
2+
3+
Type-safe SQL builder for .NET 10. Source generators + C# 12 interceptors emit all SQL at compile time. AOT compatible. Structured logging via Logsmith.
4+
5+
---
6+
17
# Quarry Migration Tool
28

39
Code-first migration scaffolding for Quarry. Reads your C# schema definitions via Roslyn, diffs them against the previous snapshot, and generates migration files — no database connection required.
@@ -9,6 +15,7 @@ Code-first migration scaffolding for Quarry. Reads your C# schema definitions vi
915
| [`Quarry`](https://www.nuget.org/packages/Quarry) | [![Quarry](https://img.shields.io/nuget/v/Quarry.svg?maxAge=60)](https://www.nuget.org/packages/Quarry) | Runtime types: builders, schema DSL, dialects, executors. |
1016
| [`Quarry.Generator`](https://www.nuget.org/packages/Quarry.Generator) | [![Quarry.Generator](https://img.shields.io/nuget/v/Quarry.Generator.svg?maxAge=60)](https://www.nuget.org/packages/Quarry.Generator) | Roslyn incremental source generator + interceptor emitter. |
1117
| [`Quarry.Analyzers`](https://www.nuget.org/packages/Quarry.Analyzers) | [![Quarry.Analyzers](https://img.shields.io/nuget/v/Quarry.Analyzers.svg?maxAge=60)](https://www.nuget.org/packages/Quarry.Analyzers) | Compile-time SQL query analysis rules (QRA series) with code fixes. |
18+
| [`Quarry.Analyzers.CodeFixes`](https://www.nuget.org/packages/Quarry.Analyzers.CodeFixes) | [![Quarry.Analyzers.CodeFixes](https://img.shields.io/nuget/v/Quarry.Analyzers.CodeFixes.svg?maxAge=60)](https://www.nuget.org/packages/Quarry.Analyzers.CodeFixes) | Code fix providers for QRA diagnostics. |
1219
| [`Quarry.Tool`](https://www.nuget.org/packages/Quarry.Tool) | [![Quarry.Tool](https://img.shields.io/nuget/v/Quarry.Tool.svg?maxAge=60)](https://www.nuget.org/packages/Quarry.Tool) | CLI tool for migrations and database scaffolding (`quarry` command). |
1320

1421
---

0 commit comments

Comments
 (0)