Skip to content

Commit c8f6e8d

Browse files
wax911Copilot
wax911
and
Copilot
committed
chore: add SQLite and annotation processing maps for improved guidance
Co-authored-by: Copilot <copilot@github.com>
1 parent 59ae06c commit c8f6e8d

8 files changed

Lines changed: 504 additions & 0 deletions

File tree

‎.github/skills/support-query-builder-reference-map/SKILL.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,3 +37,4 @@ argument-hint: 'Describe the feature, type, or consumer workflow you are trying
3737
## References
3838

3939
- [module reference map](./references/module-map.md)
40+
- Related SQLite and processor flow guidance: `support-query-builder-sqlite-android-map`

‎.github/skills/support-query-builder-reference-map/references/module-map.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,3 +29,8 @@ Use this map to determine where code belongs before searching for a specific fil
2929
- `:annotations` and `:core` are JVM-only and can be used in non-Android Kotlin projects.
3030
- `:core:ext` is an Android library; add it only when Room integration is needed.
3131
- If a change affects a public type, assume the Dokka page is part of the deliverable.
32+
33+
## Related Maps
34+
35+
- SQLite and Android bridge flow: `support-query-builder-sqlite-android-map` -> `references/sqlite-android-query-map.md`
36+
- Annotation processing and KotlinPoet flow: `support-query-builder-sqlite-android-map` -> `references/annotation-processing-map.md`

‎.github/skills/support-query-builder-sqlite-android-map/SKILL.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
name: support-query-builder-sqlite-android-map
3+
description: Use when mapping SQLite query behavior, Room raw query integration, annotation processing flow, or KAPT-to-KSP migration decisions in support-query-builder.
4+
argument-hint: Describe the SQLite, Room, processor, or migration question you need to answer.
5+
---
6+
7+
# Support Query Builder SQLite Android Map
8+
9+
## Overview
10+
11+
This skill provides a fast, source-backed map for how SQL is built, translated into Android SQLite query objects, and connected to Room via raw queries. It also maps current KAPT behavior, KSP migration boundaries, and KotlinPoet code-generation ownership.
12+
13+
Core principle: answer from module ownership and concrete file paths first, then use external docs to validate edge behavior.
14+
15+
## When To Use
16+
17+
- Onboarding an LLM or developer to this repository.
18+
- Explaining where SQL text and SQL parameters are produced.
19+
- Tracing `@EntitySchema` to generated schema object output.
20+
- Confirming whether a behavior belongs to `:core`, `:core:ext`, `:annotations`, or `:processor`.
21+
- Planning KAPT to KSP migration work without breaking module boundaries.
22+
23+
Do not use this skill for general Gradle dependency editing. Use `support-query-builder-build-dependencies` for that.
24+
25+
## Procedure
26+
27+
1. Start with the package and ownership map in [sqlite-android-query-map.md](./references/sqlite-android-query-map.md).
28+
2. If the question involves generated schema constants, switch to [annotation-processing-map.md](./references/annotation-processing-map.md).
29+
3. Validate claimed behavior against the exact owner file before answering.
30+
4. When external behavior is unclear, consult the official references listed below and map findings back to local code.
31+
32+
## Quick Reference
33+
34+
| Question | Primary module | First file |
35+
| --- | --- | --- |
36+
| Where does SQL string building happen? | `:core` | `core/src/main/kotlin/co/anitrend/support/query/builder/core/QueryBuilder.kt` |
37+
| Where does `SupportSQLiteQuery` come from? | `:core:ext` | `core/ext/src/main/kotlin/co/anitrend/support/query/builder/core/ext/QueryBuilderExtension.kt` |
38+
| Where is `@EntitySchema` defined? | `:annotations` | `annotations/src/main/kotlin/co/anitrend/support/query/builder/annotation/EntitySchema.kt` |
39+
| Where is annotation processing entrypoint? | `:processor` | `processor/src/main/kotlin/co/anitrend/support/query/builder/processor/EntitySchemaProcessor.kt` |
40+
| Where is KotlinPoet emission committed? | `:processor` | `processor/src/main/kotlin/co/anitrend/support/query/builder/processor/factory/ClassFactory.kt` |
41+
| Where is KAPT wired into sample usage? | `:sample` | `sample/build.gradle.kts` |
42+
| How do I verify Android SQLite runtime capability? | `:sample` runtime diagnostics | `SELECT sqlite_version();` and `PRAGMA compile_options;` |
43+
44+
## Example
45+
46+
```kotlin
47+
import co.anitrend.support.query.builder.core.QueryBuilder
48+
import co.anitrend.support.query.builder.core.ext.asSupportSQLiteQuery
49+
import co.anitrend.support.query.builder.dsl.from
50+
import co.anitrend.support.query.builder.dsl.select
51+
52+
val builder = QueryBuilder()
53+
builder select "*" from "person"
54+
55+
// Bridge from pure query builder to Android Room raw-query input type
56+
val sqliteQuery = builder.asSupportSQLiteQuery()
57+
```
58+
59+
## Common Mistakes
60+
61+
- Assuming `SupportSQLiteQuery` is created in `:core` instead of `:core:ext`.
62+
- Assuming KSP support exists because build output folders contain `ksp` artifacts.
63+
- Answering processor flow without checking `ClassFactory` for generated output options.
64+
- Ignoring package typos that are intentional and already in use (for example `from.extentions`).
65+
- Assuming a SQLite function from upstream docs is automatically available on all Android runtime versions.
66+
67+
## Rationalization Table
68+
69+
| Excuse | Reality |
70+
| --- | --- |
71+
| "KSP folders exist, so migration is done" | Folder artifacts are not build wiring truth. Confirm plugin and processor APIs in source/build files. |
72+
| "I can infer output path without reading processor code" | Output path is explicitly tied to `kapt.kotlin.generated` in `ClassFactory`. |
73+
| "Bridge code is obvious" | Verify owner module. This repo keeps SQL building and Android bridge in different modules. |
74+
75+
## Red Flags
76+
77+
- "I will answer from memory without file checks"
78+
- "I only need README for processor details"
79+
- "Build artifact folders are enough evidence for migration status"
80+
81+
If any red flag appears, stop and reopen the reference maps.
82+
83+
## External References
84+
85+
- SQLite official docs: https://sqlite.org/docs.html
86+
- Android SQLite package summary: https://developer.android.com/reference/android/database/sqlite/package-summary
87+
- KAPT overview: https://kotlinlang.org/docs/kapt.html
88+
- KSP overview: https://kotlinlang.org/docs/ksp-overview.html
89+
- Android migration to KSP: https://developer.android.com/build/migrate-to-ksp
90+
- KotlinPoet docs: https://square.github.io/kotlinpoet/
91+
92+
## References
93+
94+
- [SQLite and Android query map](./references/sqlite-android-query-map.md)
95+
- [Annotation processing map](./references/annotation-processing-map.md)

‎.github/skills/support-query-builder-sqlite-android-map/references/annotation-processing-map.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Annotation Processing Map
2+
3+
Use this map to understand how room metadata becomes generated schema constants.
4+
5+
## Current State
6+
7+
- Processor type: KAPT `AbstractProcessor`
8+
- Processing entrypoint: `EntitySchemaProcessor`
9+
- Codegen library: KotlinPoet
10+
- Output option key: `kapt.kotlin.generated`
11+
12+
## Pipeline
13+
14+
1. Consumer annotates Room entity with `@EntitySchema`.
15+
2. `EntitySchemaProcessor` finds annotated elements in `process(...)`.
16+
3. `createCandidate(...)` validates and adapts element metadata.
17+
4. `Candidate` extracts table name, `@ColumnInfo` columns, and `@Embedded` prefixes.
18+
5. `ClassFactory` builds KotlinPoet `TypeSpec` and `FileSpec`.
19+
6. KotlinPoet output is committed to `kapt.kotlin.generated` directory.
20+
21+
## Core Files
22+
23+
| Step | File |
24+
| --- | --- |
25+
| Annotation API | `annotations/src/main/kotlin/co/anitrend/support/query/builder/annotation/EntitySchema.kt` |
26+
| Processor entrypoint | `processor/src/main/kotlin/co/anitrend/support/query/builder/processor/EntitySchemaProcessor.kt` |
27+
| Candidate creation helpers | `processor/src/main/kotlin/co/anitrend/support/query/builder/processor/extensions/ElementExtensions.kt` |
28+
| Metadata model | `processor/src/main/kotlin/co/anitrend/support/query/builder/processor/model/Candidate.kt` |
29+
| KotlinPoet output commit | `processor/src/main/kotlin/co/anitrend/support/query/builder/processor/factory/ClassFactory.kt` |
30+
| Column mapping | `processor/src/main/kotlin/co/anitrend/support/query/builder/processor/model/column/ColumnItem.kt` |
31+
| Embedded mapping | `processor/src/main/kotlin/co/anitrend/support/query/builder/processor/model/embed/EmbedItem.kt` |
32+
| Table mapping | `processor/src/main/kotlin/co/anitrend/support/query/builder/processor/model/table/TableItem.kt` |
33+
34+
## Build Wiring
35+
36+
- Processor module applies kapt tasks and depends on `:annotations`.
37+
- Sample module consumes processor with `kapt(project(":processor"))`.
38+
- Shared plugin wiring applies `kotlin-kapt` to `:processor` and `:sample`.
39+
40+
## KAPT to KSP Migration Boundary Map
41+
42+
Keep this high-level migration map to avoid mixing APIs:
43+
44+
1. Replace `AbstractProcessor` entrypoint with KSP `SymbolProcessorProvider` plus `SymbolProcessor`.
45+
2. Replace `javax.lang.model` element traversal with KSP symbol traversal.
46+
3. Replace `kapt.kotlin.generated` output contract with KSP `CodeGenerator` output writes.
47+
4. Update module and sample Gradle wiring from `kapt(...)` usage to KSP equivalents.
48+
5. Re-run sample raw query workflows to verify generated schema names remain stable.
49+
50+
## External References
51+
52+
- KAPT: https://kotlinlang.org/docs/kapt.html
53+
- KSP overview: https://kotlinlang.org/docs/ksp-overview.html
54+
- Android KSP migration: https://developer.android.com/build/migrate-to-ksp
55+
- KotlinPoet: https://square.github.io/kotlinpoet/

‎.github/skills/support-query-builder-sqlite-android-map/references/sqlite-android-query-map.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# SQLite and Android Query Map
2+
3+
Use this map to answer SQL and Android SQLite integration questions in support-query-builder.
4+
5+
## Module Ownership
6+
7+
| Concern | Module | Source of truth |
8+
| --- | --- | --- |
9+
| SQL select/where/group/order/union rendering | `:core` | `core/src/main/kotlin/co/anitrend/support/query/builder/core/QueryBuilder.kt` |
10+
| Clause abstractions and builder contracts | `:core` | `core/src/main/kotlin/co/anitrend/support/query/builder/core/contract/AbstractQueryBuilder.kt` |
11+
| DSL entrypoints and infix helpers | `:core` | `core/src/main/kotlin/co/anitrend/support/query/builder/dsl/QueryBuilderDsl.kt` |
12+
| Translate builder to Room raw query type | `:core:ext` | `core/ext/src/main/kotlin/co/anitrend/support/query/builder/core/ext/QueryBuilderExtension.kt` |
13+
| Runtime demo and Room DAO raw query call sites | `:sample` | `sample/src/main/kotlin/co/anitrend/support/query/builder/sample/data/entity/*` |
14+
15+
## Runtime Flow
16+
17+
1. Build SQL string and argument list in `QueryBuilder.build()` and `QueryBuilder.buildParameters()`.
18+
2. Call `asSupportSQLiteQuery()` to create `SimpleSQLiteQuery(build(), buildParameters().toTypedArray())`.
19+
3. Pass resulting `SupportSQLiteQuery` to Room DAO `@RawQuery` methods.
20+
21+
## Capability Checks For New SQLite Functions
22+
23+
Before adding or expanding SQL function usage in query builders:
24+
25+
1. Confirm the function is available in Android SQLite runtimes targeted by this project.
26+
2. Validate behavior on minSdk and latest Android API levels.
27+
3. Capture runtime signals when diagnosing compatibility:
28+
- `SELECT sqlite_version();`
29+
- `PRAGMA compile_options;`
30+
4. Favor function usage that degrades safely if unavailable, or gate advanced usage behind explicit checks.
31+
5. Keep Android docs and SQLite upstream docs in sync during design review, with Android compatibility as the deciding constraint.
32+
33+
## Package Index
34+
35+
- `co.anitrend.support.query.builder.core`
36+
- `co.anitrend.support.query.builder.core.contract`
37+
- `co.anitrend.support.query.builder.core.contract.query`
38+
- `co.anitrend.support.query.builder.core.criteria`
39+
- `co.anitrend.support.query.builder.core.criteria.extensions`
40+
- `co.anitrend.support.query.builder.core.from`
41+
- `co.anitrend.support.query.builder.core.from.extentions`
42+
- `co.anitrend.support.query.builder.core.order`
43+
- `co.anitrend.support.query.builder.core.order.extensions`
44+
- `co.anitrend.support.query.builder.core.projection`
45+
- `co.anitrend.support.query.builder.core.projection.extensions`
46+
- `co.anitrend.support.query.builder.dsl`
47+
- `co.anitrend.support.query.builder.core.ext`
48+
49+
## SQLite and Android References
50+
51+
- SQLite docs index: https://sqlite.org/docs.html
52+
- Android SQLite package summary: https://developer.android.com/reference/android/database/sqlite/package-summary

‎.serena/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
/cache
2+
/project.local.yml

0 commit comments

Comments
 (0)