Skip to content

Commit 14ca8e8

Browse files
ez-pluginsez-plugins
committed
First public commit
0 parents  commit 14ca8e8

49 files changed

Lines changed: 3170 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/dependabot.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Dependabot configuration for GitHub Actions and Maven
2+
version: 2
3+
updates:
4+
- package-ecosystem: "github-actions"
5+
directory: "/"
6+
schedule:
7+
interval: "weekly"
8+
- package-ecosystem: "maven"
9+
directory: "/"
10+
schedule:
11+
interval: "weekly"

‎.github/workflows/code-quality.yml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: Code Quality
2+
3+
on:
4+
push:
5+
branches: [ "main", "master" ]
6+
pull_request:
7+
branches: [ "main", "master" ]
8+
9+
jobs:
10+
checkstyle:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- name: Checkout code
14+
uses: actions/checkout@v4
15+
- name: Set up JDK 21
16+
uses: actions/setup-java@v4
17+
with:
18+
distribution: 'temurin'
19+
java-version: '25'
20+
- name: Run Checkstyle
21+
run: mvn --batch-mode checkstyle:check
22+
- name: Annotate Checkstyle results in PR
23+
if: github.event_name == 'pull_request'
24+
uses: reviewdog/action-checkstyle@v1
25+
with:
26+
github_token: ${{ secrets.GITHUB_TOKEN }}
27+
reporter: github-pr-review
28+
level: error
29+
checkstyle_input: target/checkstyle-result.xml
30+
31+
coverage:
32+
runs-on: ubuntu-latest
33+
steps:
34+
- name: Checkout code
35+
uses: actions/checkout@v4
36+
- name: Set up JDK 21
37+
uses: actions/setup-java@v4
38+
with:
39+
distribution: 'temurin'
40+
java-version: '25'
41+
- name: Build with coverage
42+
run: mvn --batch-mode clean verify
43+
- name: Upload JaCoCo coverage report
44+
uses: actions/upload-artifact@v4
45+
with:
46+
name: jacoco-report
47+
path: target/site/jacoco/
48+
- name: Comment JaCoCo coverage summary in PR
49+
if: github.event_name == 'pull_request'
50+
uses: madrapps/jacoco-report@v1.6.1
51+
with:
52+
paths: target/site/jacoco/jacoco.xml
53+
token: ${{ secrets.GITHUB_TOKEN }}
54+
min-coverage-overall: 0
55+
min-coverage-changed-files: 0

‎.github/workflows/javadoc.yml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
name: Javadoc
2+
3+
on:
4+
push:
5+
branches: [ "main", "master" ]
6+
pull_request:
7+
branches: [ "main", "master" ]
8+
9+
jobs:
10+
javadoc:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- name: Checkout code
14+
uses: actions/checkout@v4
15+
- name: Set up JDK 25
16+
uses: actions/setup-java@v4
17+
with:
18+
distribution: 'temurin'
19+
java-version: '25'
20+
- name: Build Javadoc
21+
run: mvn --batch-mode javadoc:javadoc
22+
- name: Upload Javadoc artifact
23+
uses: actions/upload-artifact@v4
24+
with:
25+
name: java-query-builder-javadoc
26+
path: target/site/apidocs/

‎.github/workflows/publish.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: Publish to GitHub Packages
2+
3+
on:
4+
release:
5+
types: [created]
6+
7+
jobs:
8+
publish:
9+
runs-on: ubuntu-latest
10+
permissions:
11+
contents: read
12+
packages: write
13+
14+
steps:
15+
- name: Checkout code
16+
uses: actions/checkout@v4
17+
18+
- name: Set up JDK 21
19+
uses: actions/setup-java@v4
20+
with:
21+
distribution: 'temurin'
22+
java-version: '25'
23+
server-id: github
24+
server-username: GITHUB_ACTOR
25+
server-password: GITHUB_TOKEN
26+
27+
- name: Publish package
28+
run: mvn --batch-mode -DskipTests deploy
29+
env:
30+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.github/workflows/unit-tests.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: Unit Tests
2+
3+
on:
4+
push:
5+
branches: [ "main", "master" ]
6+
pull_request:
7+
branches: [ "main", "master" ]
8+
9+
jobs:
10+
unit-tests:
11+
runs-on: ubuntu-latest
12+
strategy:
13+
matrix:
14+
java-version: [ '25' ]
15+
steps:
16+
- name: Checkout code
17+
uses: actions/checkout@v4
18+
- name: Set up JDK ${{ matrix.java-version }}
19+
uses: actions/setup-java@v4
20+
with:
21+
distribution: 'temurin'
22+
java-version: ${{ matrix.java-version }}
23+
- name: Run unit tests
24+
run: mvn --batch-mode -Dtest='!feature.**.*Test' test
25+
- name: Upload JAR artifact
26+
uses: actions/upload-artifact@v4
27+
with:
28+
name: java-query-builder-jar
29+
path: target/*.jar
30+
- name: Publish JUnit test results
31+
uses: actions/upload-test-results@v2
32+
with:
33+
files: target/surefire-reports/*.xml
34+
35+
feature-tests:
36+
runs-on: ubuntu-latest
37+
strategy:
38+
matrix:
39+
java-version: [ '25' ]
40+
steps:
41+
- name: Checkout code
42+
uses: actions/checkout@v4
43+
- name: Set up JDK ${{ matrix.java-version }}
44+
uses: actions/setup-java@v4
45+
with:
46+
distribution: 'temurin'
47+
java-version: ${{ matrix.java-version }}
48+
- name: Run feature tests
49+
run: mvn --batch-mode -Dtest='feature.**.*Test' test
50+
- name: Publish Feature Test Results
51+
uses: actions/upload-test-results@v2
52+
with:
53+
files: target/surefire-reports/*.xml

‎.gitignore‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Java
2+
/target/
3+
!.mvn/wrapper/maven-wrapper.jar
4+
5+
# Maven
6+
/logs/
7+
*.log
8+
9+
# Eclipse
10+
.classpath
11+
.project
12+
.settings/
13+
14+
# IntelliJ
15+
.idea/
16+
*.iml
17+
*.ipr
18+
*.iws
19+
out/
20+
21+
# VS Code
22+
.vscode/
23+
24+
# OS
25+
.DS_Store
26+
Thumbs.db
27+
28+
# Build
29+
/build/
30+
31+
# Test
32+
/test-output/
33+
34+
# Dependency directories
35+
/node_modules/
36+
37+
# Others
38+
*.swp
39+
*.swo
40+
*.bak
41+
*.tmp

‎AGENTS.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# JavaQueryBuilder – Project Guidelines
2+
3+
## Code Style
4+
5+
Enforced by Checkstyle ([checkstyle.xml](checkstyle.xml)) — runs automatically on `mvn validate`. Violations fail the build.
6+
7+
- **Indentation**: 4 spaces; no tabs
8+
- **Line length**: max 120 characters
9+
- **Trailing whitespace**: none allowed
10+
- **Imports**: grouped (`java`, `javax`, `org`, `com`), no star imports, ordered and separated by blank line
11+
- **Braces**: required on all blocks (`NeedBraces`), same-line opening (`LeftCurly`)
12+
- **Complexity**: cyclomatic complexity ≤ 10 per method; method body ≤ 60 lines; class fan-out ≤ 20
13+
- **Magic numbers**: flag literals other than `-1, 0, 1, 2` outside field declarations and annotations
14+
- **`FinalLocalVariable`**: declare local variables `final` whenever they are not reassigned
15+
- Test classes (`*Test.java`): Javadoc and complexity rules are suppressed via [suppressions.xml](suppressions.xml)
16+
17+
### JavaDoc Requirements
18+
19+
All public API classes, interfaces, enums, and their methods must have complete Javadoc:
20+
21+
```java
22+
/**
23+
* One clear summary sentence ending with a period.
24+
*
25+
* @param column the column name to filter on
26+
* @param value the value to compare against
27+
* @return this builder instance for chaining
28+
* @throws IllegalArgumentException if column is null or blank
29+
*/
30+
public QueryBuilder whereEquals(String column, Object value) { … }
31+
```
32+
33+
- `@author` and `@version` required on type-level Javadoc
34+
- `@param` required for every parameter, `@return` for every non-void method
35+
- `@throws` required for every checked and declared unchecked exception
36+
- First sentence must be a meaningful summary — no generic openers like `"A {@code X} is a …"`
37+
38+
## Architecture
39+
40+
Package `com.github.ezframework.javaquerybuilder.query`:
41+
42+
| Class / Type | Role |
43+
|---|---|
44+
| `QueryBuilder` | Fluent builder for SELECT queries; returns a `Query` |
45+
| `DeleteBuilder`, `InsertBuilder`, `UpdateBuilder` | Fluent builders for DML statements |
46+
| `Query` | Immutable data holder (columns, conditions, limit, offset, …) |
47+
| `Condition` / `ConditionEntry` | Per-field condition (operator + value) with in-memory match support |
48+
| `Operator` | Enum of 14 comparison operators (`EQ`, `LIKE`, `BETWEEN`, …) |
49+
| `Connector` | `AND` / `OR` enum for joining conditions |
50+
| `sql.SqlDialect` | Strategy: `STANDARD`, `MYSQL`, `SQLITE` |
51+
| `sql.AbstractSqlDialect` | Base SQL rendering logic |
52+
53+
**Key conventions**:
54+
- Builder methods **always return `this`** (or the builder type) for fluent chaining.
55+
- All SQL values must go through the parameterized SQL path — never concatenate user input into SQL strings.
56+
- `Operator` is the single source of truth for supported operators; add new operators there first.
57+
58+
## Build and Test
59+
60+
```bash
61+
# Full build: checkstyle → compile → test → JaCoCo report → coverage check → package
62+
mvn clean verify
63+
64+
# Checkstyle only
65+
mvn checkstyle:check
66+
67+
# Tests only (skips coverage threshold)
68+
mvn test
69+
70+
# Coverage report (generated after mvn verify or mvn test)
71+
open target/site/jacoco/index.html
72+
```
73+
74+
**Coverage target**: 80% instruction coverage enforced by JaCoCo on `mvn verify`. New code must maintain or improve coverage.
75+
76+
## Conventions
77+
78+
- Fluent builder methods use verb prefixes: `where*`, `orderBy`, `groupBy`, `select`, `from`
79+
- `OR` variants are named `orWhere*` — the first condition in a builder always uses `AND` as connector
80+
- Exception hierarchy: `QueryBuilderException` → `QueryException` / `QueryRenderException` in `query.exception`
81+
- Test class names match source class names with `Test` suffix and live in the same sub-package under `src/test/`
82+
83+
## Packaging and Distribution
84+
85+
- **GitHub Packages**: published automatically on GitHub Release creation via [.github/workflows/publish.yml](.github/workflows/publish.yml)
86+
- **JitPack**: available at `https://jitpack.io/#EzFramework/JavaQueryBuilder`; build config in [jitpack.yml](jitpack.yml)
87+
- Both `-sources.jar` and `-javadoc.jar` are attached to every release

‎CONTRIBUTING.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Contributing to JavaQueryBuilder
2+
3+
## Getting Started
4+
5+
1. Fork and clone the repository
6+
2. Ensure Java 21 and Maven 3.8+ are installed
7+
3. Run `mvn clean verify` — all checks must pass before you start
8+
9+
## Branching
10+
11+
- Branch from `main`
12+
- Use descriptive branch names: `feature/add-join-support`, `fix/between-operator-null`
13+
- Open a pull request against `main`
14+
15+
## Pull Request Requirements
16+
17+
All of the following must pass before a PR is merged:
18+
19+
| Check | Command | Gating |
20+
|---|---|---|
21+
| Checkstyle | runs during `mvn validate` | build fails on any violation |
22+
| Tests | `mvn test` | all tests must pass |
23+
| Coverage | `mvn verify` | ≥ 80% instruction coverage (JaCoCo) |
24+
25+
**Do not use `--forks-enforced` or `-Dcheckstyle.skip` to bypass checks.**
26+
27+
## Code Style
28+
29+
See [AGENTS.md](AGENTS.md) for the full style guide. The short version:
30+
31+
- 4-space indentation, max 120 chars per line, no trailing whitespace
32+
- Full Javadoc on every public class and method (`@param`, `@return`, `@throws`)
33+
- Declare locals `final` when not reassigned
34+
- Cyclomatic complexity ≤ 10; method length ≤ 60 lines
35+
36+
Run `mvn checkstyle:check` locally before pushing.
37+
38+
## Writing Tests
39+
40+
- Place tests in `src/test/…` mirroring the source package
41+
- Test method names should describe the behaviour: `buildsSelectWithDistinct()`, `throwsOnNullColumn()`
42+
- Cover both happy paths and edge cases (null inputs, empty lists, boundary values)
43+
- Aim to keep or improve the 80% instruction coverage threshold
44+
45+
## Adding New Operators
46+
47+
1. Add the value to the `Operator` enum with a Javadoc comment
48+
2. Handle the new operator in `Condition#matches()` for in-memory filtering
49+
3. Handle it in `AbstractSqlDialect` (and dialect subclasses if behaviour differs)
50+
4. Add tests for all three layers
51+
52+
## Releasing
53+
54+
Releases are published to **GitHub Packages** and available via **JitPack** automatically:
55+
56+
1. Draft a new GitHub Release with a semantic version tag (e.g. `v1.1.0`)
57+
2. Publishing the release triggers [`.github/workflows/publish.yml`](.github/workflows/publish.yml)
58+
3. The workflow deploys the JAR, `-sources.jar`, and `-javadoc.jar` to GitHub Packages
59+
4. JitPack picks up the tag and builds automatically from [jitpack.yml](jitpack.yml)
60+
61+
## Reporting Issues
62+
63+
Open a GitHub Issue with a minimal reproducible example. For security issues see the security section in [README.md](README.md).

0 commit comments

Comments
 (0)