diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md new file mode 100644 index 00000000..53fc5e4d --- /dev/null +++ b/.claude/skills/release/SKILL.md @@ -0,0 +1,209 @@ +--- +name: release +description: Cut a cui-java-tools release — bump .github/project.yml version, open and merge the release PR, wait for the automated Release workflow, verify the release landed, then reformat the generated GitHub release notes +user-invocable: true +allowed-tools: Bash, Read, Edit +--- + +# Release Skill + +Cuts a new cui-java-tools release end-to-end: determine the version, open the version-bump +PR that triggers the release, merge it, wait for the automated Release workflow, verify the +release landed, and reformat the auto-generated GitHub release notes. + +## How the release is wired (read first) + +The release is **fully automated by GitHub Actions**. `.github/workflows/release.yml` +triggers on a **merged pull request that changes `.github/project.yml`**: + +```yaml +on: + pull_request: + types: [closed] + paths: + - '.github/project.yml' +``` + +So this skill never runs Maven release goals by hand. Its job is to produce and merge the +correct `project.yml` change; the reusable `cuioss-organization` release workflow +(`reusable-maven-release.yml`) does the tagging, Maven Central deploy, GitHub release +creation, and — because `pages.deploy-at-release: true` — the documentation pages deploy. + +Observed timings (use these as the basis for the waits below): +- PR gating check: **Maven Build ~4–7 min** (matrix over Java 21 + 25). This is a + zero-dependency library with no integration/e2e suites, so a full green PR is typically + **~5–8 min**. +- Release workflow itself: **~6 min**, but Maven Central propagation, the GitHub release + publish, and the pages deploy can lag → allow **up to ~30 min** before treating it as + stuck. + +## Workflow + +### Step 1 — Determine the version number + +Read the current release block in `.github/project.yml`: +- `release.current-version` (e.g. `2.6.2`) — the **last released** version. +- `release.next-version` (e.g. `2.6-SNAPSHOT`) — the floating development version that + `pom.xml` carries between releases. + +**Default rule (patch line):** cui-java-tools ships three-segment `X.Y.Z` releases +(`2.6.0` → `2.6.1` → `2.6.2` …) while the pom stays permanently on the `X.Y-SNAPSHOT` +minor floor. The release version is therefore `current-version` with the **patch segment +incremented** (`2.6.2` → `2.6.3`), and `next-version` is left **unchanged** (`2.6-SNAPSHOT`). + +**Starting a new minor/major line** (e.g. `2.7.0`, `3.0.0`) also bumps `next-version` to the +matching `X.Y-SNAPSHOT` (e.g. `2.7-SNAPSHOT`) and the pom moves with it. That is a deliberate +decision — **ask the user** (AskUserQuestion) before assuming it. Otherwise state the +determined patch version and proceed. + +Also **ask the user** if the numbers look inconsistent (e.g. `current-version` doesn't sit on +the `next-version` minor line, or a patch/major release seems intended by recent history). + +### Step 2 — Determine current status (clean to release?) + +```bash +gh pr list --repo cuioss/cui-java-tools --state open --json number,title,isDraft +``` +- **No open PRs** → good, proceed. +- **Open PRs exist** → these would normally be merged before a release. Surface the list + and **ask the user** whether to proceed anyway or wait. Do not silently ignore them. + +Also confirm the working tree is clean (`git status --porcelain`) before branching. + +### Step 3 — Pull current main + +```bash +git checkout main && git pull --ff-only origin main +``` + +### Step 4 — Create the release branch + +Branch name uses the `chore/` prefix (required — the Maven CI workflow only triggers on +`main`, `feature/*`, `fix/*`, `chore/*`, `release/*`, `dependabot/**`; other prefixes skip +the `build` check and block auto-merge): + +```bash +git checkout -b chore/release_ # e.g. chore/release_2.6.3 +``` + +### Step 5 — Update `.github/project.yml` + +Edit the `release` block: +- `current-version:` → the version determined in Step 1 (e.g. `2.6.3`). +- `next-version:` → **leave unchanged** for a patch release (stays `2.6-SNAPSHOT`); only bump + it when starting a new minor/major line (e.g. `2.7-SNAPSHOT`). + +Leave everything else untouched. cui-java-tools' README badges (CI, CodeQL, Maven Central, +SonarCloud) are all dynamic endpoints — there is **no** per-release badge to hand-edit. + +### Step 6 — Commit, push, open PR + +```bash +git add .github/project.yml +git commit -m "chore(release): prepare release " +git push -u origin chore/release_ +gh pr create --repo cuioss/cui-java-tools --base main \ + --title "chore(release): prepare release " \ + --body "Bump current-version to . Triggers the automated Release workflow on merge." +``` + +Use the project commit convention: `Co-Authored-By: Claude ` (no +model name / no "Generated with Claude Code" footer). + +### Step 7 — Wait for PR checks (~5–8 min) + +Watch the checks rather than blindly sleeping: + +```bash +gh pr checks --repo cuioss/cui-java-tools --watch +``` +If using a scheduled/loop wait, poll roughly every couple of minutes up to ~8 min. + +### Step 8 — Handle PR comments / failures (if any) + +- If a check fails, read the failing run's log (`gh run view --log-failed`), fix the + cause on the branch, push, and re-wait. **Never** merge a red PR. +- If the Gemini reviewer or a human leaves comments (`gh pr view --comments`), address + them on the branch per the repo's PR-comment protocol in `CLAUDE.md`: reply to and resolve + every comment; ask the user when uncertain. +- Re-run Step 7 after any push. + +### Step 9 — Merge → release starts automatically + +Once checks are green and comments resolved: + +```bash +gh pr merge --repo cuioss/cui-java-tools --squash --delete-branch +``` +Merging this PR (it touches `.github/project.yml`) fires `release.yml` automatically — do +**not** dispatch the release manually unless the auto-trigger demonstrably did not fire. + +### Step 10 — Wait for the Release workflow (~30 min) + +```bash +gh run list --repo cuioss/cui-java-tools --workflow "Release" --limit 3 \ + --json status,conclusion,displayTitle,databaseId +# then watch the in-progress run +gh run watch --repo cuioss/cui-java-tools +``` +The workflow itself runs ~6 min; allow up to ~30 min for tag + GitHub release publish + +Maven Central propagation + pages deploy before treating it as stuck. + +### Step 11 — Verify the release landed + +```bash +gh release view --repo cuioss/cui-java-tools \ + --json tagName,name,createdAt,body +git fetch --tags && git tag --list +``` +Confirm the tag exists and a GitHub release for `` was created. If it did not +appear, inspect the Release workflow run log before proceeding. + +### Step 12 — Reformat the generated release notes + +The Release workflow creates the GitHub release with **auto-generated** notes (a flat +`## What's Changed` list). Rewrite them in place using the **house format below**, then +push the update: + +```bash +mkdir -p .plan/temp +gh release view --repo cuioss/cui-java-tools --json body --jq .body > .plan/temp/release--orig.md +# ...build the reformatted body in .plan/temp/release-.md... +gh release edit --repo cuioss/cui-java-tools --notes-file .plan/temp/release-.md +``` + +#### House format rules (apply exactly) + +1. **Two top-level groups:** `## Features & Enhancements` and `## Dependency Updates`. +2. **Features & Enhancements** — group functional PRs by theme with `###` subheadings, + adapted to cui-java-tools' domain, e.g.: + - `### Collections` — `collect` builders, literals, `MapDifference`, `MoreCollections` + - `### Strings & Formatting` — `string` utilities and the `formatting` template engine + - `### I/O` — file loaders, paths, streams + - `### Logging` — `CuiLogger`, `LogRecord` + - `### Net & SSL` — URL/parameter helpers, IDN, keystore/SSL + - `### Property & Reflection` — `property` / `reflect` helpers + - `### Lang, Codec & Concurrent` — `LocaleUtils`, `Hex`, ring buffers, `StopWatch` + - `### API & Code Quality` — public-API changes, refactors, cleanup, and standards + recipes (e.g. `refactor-to-profile-standards` belongs here, **not** under build/tooling) + - `### Testing & Standards` + - `### Documentation` + Adapt theme headings to the actual PRs; omit empty sections. +3. **Dependency Updates** — group by type with `###` subheadings (cui-java-tools is Java-only + — there is no JavaScript group): + - `### Java` — Java libraries (e.g. lombok, junit, cui-test-generator). + - `### Infra` — platform/build/CI: build plugins, `cuioss-organization` workflow bumps, + parent-POM / `cui-java-parent` updates. +4. **Collapse version chains** — when the same artifact is bumped multiple times + (`A → B → C`), keep only the **latest** entry spanning the full range + (e.g. `lombok 1.18.30 → 1.18.32 → 1.18.34` becomes a single `1.18.30 → 1.18.34`). +5. **Remove all OpenRewrite bumps and friends** — drop every `rewrite-maven-plugin`, + `rewrite-migrate-java`, `rewrite-testing-frameworks`, and related OpenRewrite dependency PR. +6. **Remove internal tooling churn** — drop PRs that only touch dev/build orchestration with + no user-facing effect: `marshal.json`/plan-marshall config migrations, plan-marshall build + wiring, internal dev-skill changes, and the mechanical version-bump PR itself. +7. Preserve each kept PR line verbatim (`* by @author in <url>`); when two PRs share + an identical title, merge them onto one line with both URLs. +8. Keep the trailing `**Full Changelog**: ...compare/<prev>...<version>` line. + +### Step 13 — Done diff --git a/.gitignore b/.gitignore index e53d8973..3e533d64 100644 --- a/.gitignore +++ b/.gitignore @@ -24,5 +24,9 @@ target/ .flattened-pom.xml -# Claude Code configuration -.claude/ +# Claude Code configuration — ignore local settings, but track shared skills +.claude/* +!.claude/skills/ + +# plan-marshall local working directory +.plan/ diff --git a/CLAUDE.md b/CLAUDE.md index ab9c41a0..563e96bb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,115 +1,124 @@ # CLAUDE.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +Guidance for Claude Code (and other AI tools) when working in this repository. ## Project Overview -cui-java-tools is a Java utility library providing essential tools for collections, strings, I/O, logging, and networking. It serves as a zero-dependency replacement for parts of Guava and Apache Commons, following Jakarta EE standards. +`cui-java-tools` is a **zero-dependency** Java utility library — a curated replacement +for parts of Guava and Apache Commons, following Jakarta EE conventions. Lombok is the +only compile-time dependency (dev-only, not transitive). -### Key Features -- Zero external dependencies (only Lombok for development) -- Comprehensive utility classes for collections, strings, I/O, logging, and networking -- Type-safe property access and reflection helpers -- Template-based formatting system -- Custom logging framework wrapping java.util.logging -- SSL/TLS utilities +- Maven coordinates: `de.cuioss:cui-java-tools` +- Java module: `de.cuioss.java.tools` (`src/main/java/module-info.java`) +- Java release: **21** (`maven.compiler.release`) +- Current version: see `<version>` in `pom.xml` (floats on the `X.Y-SNAPSHOT` minor line between releases) +- Published on **Maven Central** — public API changes require deliberate consideration. -## Build System +## Build & Test -This is a Maven project with standard structure: +Always build and test through Maven. **Never** invoke `javac` directly or write ad-hoc +`main`/verifier classes outside JUnit. -### Essential Commands -- **Build**: `./mvnw clean install` -- **Test**: `./mvnw test` -- **Run single test**: `./mvnw test -Dtest=ClassName#methodName` -- **Pre-commit checks**: `./mvnw -Ppre-commit clean verify -DskipTests` -- **Clean and verify**: `./mvnw clean verify` - -### Project Structure -- Main source: `src/main/java/de/cuioss/tools/` -- Test source: `src/test/java/de/cuioss/tools/` -- Maven module: `de.cuioss.java.tools` -- Current version: see `<version>` in `pom.xml` +- Build: `./mvnw clean install` +- Test: `./mvnw test` +- Single test: `./mvnw test -Dtest=ClassName#methodName` +- Coverage: `./mvnw -Pcoverage verify` +- Pre-commit gate (run before every commit): `./mvnw -Ppre-commit clean verify` + - Fix **all** errors and warnings. + - OpenRewrite recipes may add markers or rewrite sources — either accept the rewrite or + suppress with justification. **Never commit rewrite markers**, and never leave the tree + dirty after a pre-commit run. ## Architecture -### Core Packages -- `de.cuioss.tools.base` - Basic utilities (Preconditions, BooleanOperations) -- `de.cuioss.tools.collect` - Collection utilities (builders, literals, more collections) -- `de.cuioss.tools.string` - String utilities (Joiner, Splitter, MoreStrings) -- `de.cuioss.tools.io` - I/O utilities (file loaders, path utilities) -- `de.cuioss.tools.logging` - Custom logging framework (CuiLogger) -- `de.cuioss.tools.net` - Network utilities (URL helpers, SSL) -- `de.cuioss.tools.lang` - Language utilities (LocaleUtils, MoreObjects) -- `de.cuioss.tools.concurrent` - Concurrency utilities (StopWatch, ConcurrentTools) -- `de.cuioss.tools.formatting` - Template-based formatting system -- `de.cuioss.tools.codec` - Encoding/decoding utilities (Hex) -- `de.cuioss.tools.property` - Property access utilities -- `de.cuioss.tools.reflect` - Reflection helpers - -### Design Principles -- Zero external dependencies (except Lombok for development) -- Facade/decorator pattern over complete reimplementation -- Builder patterns for complex object creation -- Immutable objects where possible -- Comprehensive test coverage - -## Development Guidelines - -### Code Style -- Uses Lombok for reducing boilerplate -- Follows standard Java conventions -- Comprehensive Javadoc documentation -- Package-info.java files for all packages - -### Testing -- JUnit 5 with extensive test coverage -- Test support classes in `de.cuioss.tools.support` -- All public APIs must be tested -- Uses JUnit 5 assertions (Hamcrest and Mockito are forbidden, see `doc/ai-rules.md`) - -### Logging -- Custom logging framework in `de.cuioss.tools.logging` -- Uses `CuiLogger` instead of standard logging frameworks -- Formatting supports both `{}` and `%s` placeholders -- Log levels: TRACE, DEBUG, INFO, WARN, ERROR - -### Important Notes -- Published on Maven Central; public API changes need deliberate consideration -- API removals go through a deprecation cycle: mark with `@Deprecated(since = ..., forRemoval = true)` and remove in the next major release -- Remove unused internal code directly - -## Special Considerations - -### Module System -- Uses Java modules (`module-info.java`) -- Exports all main packages -- Requires static lombok dependency - -### Documentation -- Main documentation in README.adoc -- Detailed package documentation in Javadoc -- Examples in test classes demonstrate usage patterns - -### AI Development Rules -- Follow CUI standards as outlined in `doc/ai-rules.md` -- Always run pre-commit checks before making changes -- Use appropriate test coverage for all new code -- Document any new public APIs according to Javadoc standards +Main source under `src/main/java/de/cuioss/tools/`, tests mirror it under `src/test/java/`. + +- `base` — `Preconditions`, `BooleanOperations` +- `collect` — collection builders, literals, `MoreCollections`, `MapDifference` +- `string` — `Joiner`, `Splitter`, `MoreStrings`, `TextSplitter` +- `io` — file loaders, `MorePaths`, `FilenameUtils`, `IOStreams` +- `logging` — `CuiLogger` framework (wraps `java.util.logging`) +- `net` / `net.ssl` — URL/parameter helpers, IDN, keystore & SSL utilities +- `lang` — `LocaleUtils`, `MoreObjects` +- `concurrent` — `StopWatch`, `ConcurrentTools`, ring buffers +- `formatting` — template-based formatting (lexer / token / template) +- `codec` — `Hex` +- `property` / `reflect` — type-safe property access and reflection helpers + +### Design principles + +- Zero external runtime dependencies. +- Facade/decorator over standard Java rather than full reimplementation. +- Builders for complex construction; immutable objects where possible. +- Every code-bearing package has a `package-info.java`. + +## Logging + +- Use `de.cuioss.tools.logging.CuiLogger` — declare as `private static final CuiLogger LOGGER`. +- No `slf4j`, `log4j`, `System.out`, or `System.err`. +- Placeholders use `%s` (and `{}` is also supported); the exception parameter always comes + **first** in logging methods. +- Use `de.cuioss.tools.logging.LogRecord` for templated, catalogued messages. +- Message-identifier ranges: **INFO 001–099, WARN 100–199, ERROR 200–299** (there is no + FATAL level). Catalogued messages are documented in `doc/LogMessages.adoc`. + +## Testing + +- JUnit 5 only. **Forbidden: Mockito, PowerMock, Hamcrest** — use the CUI alternatives. +- Follow AAA (Arrange-Act-Assert); tests must be order-independent. +- Use the **cui-test-generator** for test-data generation and `cui-test-value-objects` for + value-object contract tests. +- Use `cui-test-juli-logger` (`@EnableTestLogger`, `assertLogMessagePresentContaining`) for + logging assertions. +- Prefer `@ParameterizedTest` for 3+ similar variants. +- All public APIs must be tested; keep coverage at or above the project gate (80% line/branch). + +## Null-safety (JSpecify) + +JSpecify is a dependency. Adoption is **in progress** — currently only +`de.cuioss.tools.logging` is `@NullMarked`. When touching a package, prefer marking it +`@NullMarked` at the `package-info.java` level and annotating the exceptions with +`@Nullable`. Note Lombok `@NonNull` (runtime check) and JSpecify (static contract) are +complementary, not interchangeable. + +## API & Deprecation Policy + +- Since this is published on Maven Central, treat public API changes deliberately. +- API removals go through a deprecation cycle: mark with + `@Deprecated(since = "<version>", forRemoval = true)` and remove only in the next major + release. Do **not** delete public members (including enum constants) outright. +- Remove unused **internal** code directly. ## Git Workflow -All cuioss repositories have branch protection on `main`. Direct pushes to `main` are never allowed. Always use this workflow: - -1. Create a feature branch: `git checkout -b <branch-name>` -2. Commit changes: `git add <files> && git commit -m "<message>"` -3. Push the branch: `git push -u origin <branch-name>` -4. Create a PR: `gh pr create --repo cuioss/cui-java-tools --head <branch-name> --base main --title "<title>" --body "<body>"` -5. Wait for CI + Gemini review (check every ~60s until checks complete): `while ! gh pr checks --repo cuioss/cui-java-tools <pr-number> --watch; do sleep 60; done` -6. **Handle Gemini review comments** — fetch with `gh api repos/cuioss/cui-java-tools/pulls/<pr-number>/comments` and for each: - - If clearly valid and fixable: fix it, commit, push, then reply explaining the fix and resolve the comment - - If disagree or out of scope: reply explaining why, then resolve the comment - - If uncertain (not 100% confident): **ask the user** before acting - - Every comment MUST get a reply (reason for fix or reason for not fixing) and MUST be resolved -7. Do **NOT** enable auto-merge unless explicitly instructed. Wait for user approval. -8. Return to main: `git checkout main && git pull` +`main` is branch-protected — **never push to `main` directly**. + +1. Branch: `git checkout -b <prefix>/<name>` (prefixes that trigger CI: `feature/*`, + `fix/*`, `chore/*`, `release/*`). +2. Commit: `git add <files> && git commit -m "<message>"`. + - End commit messages with: `Co-Authored-By: Claude <noreply@anthropic.com>` + (no model name, no "Generated with Claude Code" footer). +3. Push: `git push -u origin <branch>`. +4. PR: `gh pr create --repo cuioss/cui-java-tools --head <branch> --base main --title "<title>" --body "<body>"`. +5. Wait for CI + Gemini review: + `while ! gh pr checks --repo cuioss/cui-java-tools <pr> --watch; do sleep 60; done`. +6. Address every review comment (fix or explain, then resolve). If uncertain about a + comment, ask the user before acting. +7. Do **not** enable auto-merge unless explicitly told to. +8. After merge: `git checkout main && git pull`. + +## Releases + +Releases are fully automated by GitHub Actions. A release is cut by bumping +`.github/project.yml` `release.current-version` (patch bump on the `X.Y.Z` line, e.g. +`2.6.2` → `2.6.3`) in a merged PR — the `pom.xml` stays on the floating `X.Y-SNAPSHOT` minor line. +Use the `/release` skill (`.claude/skills/release/`); never run Maven release goals by hand. + +## Process Rules + +- If in doubt, ask the user — don't guess or invent APIs/standards. +- Research current best practices with the available tools before proposing changes. +- Don't add dependencies without approval. +- Don't proliferate documents — reuse existing ones; create new docs only when asked. +- Use the JetBrains MCP only for per-file IDE diagnostics, not for other tasks. +- Use the `gh` CLI for all GitHub access. diff --git a/doc/ai-rules.md b/doc/ai-rules.md deleted file mode 100644 index 7627e8fb..00000000 --- a/doc/ai-rules.md +++ /dev/null @@ -1,321 +0,0 @@ -# AI Development Guidelines - -This file provides guidance to AI tools (IntelliJ Junie, Claude Code, GitHub Copilot, etc.) when working with code in CUI projects. - -## Configuration - -**Standards Base URL**: Configure this based on your development environment: -- **Remote (gitingest)**: `https://gitingest.com/github.com/cuioss/cui-llm-rules/tree/main` -- **Local checkout**: Use relative path to your local standards directory (e.g., `../cui-llm-rules`) - -Replace `{STANDARDS_BASE_URL}` in all references below with your chosen base URL. - -## Context Hierarchy and Priority Framework -**Critical for AI System Decision Making** - -When conflicting information exists, AI systems must follow this priority order: - -1. **Core Process Rules** (CRITICAL - highest priority, non-negotiable) -2. **Project-Specific Context** (CLAUDE.md, .github/copilot-instructions.md, local config) -3. **Standards References** (adaptable based on context and requirements) -4. **General Guidelines** (lowest priority, may be overridden by higher levels) - -### Context-Aware Response Patterns -- **New Project Context**: Emphasize architecture decisions and initial setup standards -- **Legacy Code Context**: Prioritize compatibility, incremental changes, and migration paths -- **Testing Context**: Focus on coverage requirements and quality standards -- **Documentation Context**: Emphasize clarity, completeness, and AsciiDoc standards -- **Security Context**: Apply strictest security standards without compromise - -## Core Process Rules (CRITICAL - READ FIRST) -**Reference**: `{STANDARDS_BASE_URL}/standards/process/general.adoc` - -These rules govern ALL development activities: - -### General Process Rules -1. **If in doubt, ask the user** - Never make assumptions -2. **Always research topics** - Use available tools (WebSearch, WebFetch, etc.) to find the most recent best practices -3. **Never guess or be creative** - If you cannot find best practices, ask the user -4. **Do not proliferate documents** - Always use context-relevant documents, never create without user approval -5. **Never add dependencies without approval** - Always ask before adding any dependency - -## AI Safety and Validation Framework -**Mandatory for All AI-Generated Content** - -### Safety Constraints (NON-NEGOTIABLE) -- **Never bypass security measures**: AI must not suggest workarounds for security controls -- **Preserve data integrity**: All changes must maintain data consistency -- **Respect privacy**: No exposure of sensitive data in logs or outputs -- **Maintain auditability**: All AI-generated changes must be traceable -- **Follow standards hierarchy**: Respect the context priority framework above - -### Validation Requirements -Before any code implementation: -1. **Standards Compliance Check**: Verify output matches CUI standards -2. **Build Verification**: Ensure generated code compiles and passes pre-commit checks -3. **Security Review**: Check for security anti-patterns and vulnerabilities -4. **Documentation Sync**: Verify documentation reflects any code changes -5. **Test Coverage**: Ensure adequate test coverage for new functionality - -### Error Recovery Patterns -- **Standards Violation**: Provide specific correction guidance with reference links -- **Build Failures**: Include diagnostic steps and reference Build Commands Template -- **Test Failures**: Guide through debugging using Testing Standards -- **Integration Issues**: Escalate to human review with detailed context - -## Task Completion Standards (MANDATORY) -**Reference**: `{STANDARDS_BASE_URL}/standards/process/task-completion-standards.adoc` - -### Pre-Commit Checklist -Execute in sequence before ANY commit: - -1. **Quality Verification**: `./mvnw -Ppre-commit clean verify` - - Fix ALL errors and warnings (mandatory) - - Some recipes may add markers: Either fix them, or suppress them with proper justification. Never commit the markers. - - Address code quality, formatting, and linting issues - -2. **Documentation**: Ensure all changes are documented - - Update Javadoc for public APIs - - Update AsciiDoc documentation if necessary - -3. **Documentation**: Update if changes affect APIs, features, or configuration - -4. **Commit Message**: Follow Git Commit Standards - -### Quality Requirements -- New code requires appropriate test coverage -- Existing tests must continue to pass -- Documentation must be updated for API/feature changes -- Link commits to relevant issues or tasks - -## Build Commands Template -Common Maven commands for CUI projects: -- Build project: `./mvnw clean install` -- Run tests: `./mvnw test` -- Run single test: `./mvnw test -Dtest=ClassName#methodName` -- Clean-Up Code: `./mvnw -Ppre-commit clean install` -> Check the console after running the command and fix all errors and warnings, verify until they are all corrected - -## Standards Overview -**Base Reference**: `{STANDARDS_BASE_URL}/standards` - -## Java Standards -**References**: -- Java Code Standards: `{STANDARDS_BASE_URL}/standards/java` -- DSL-Style Constants: `{STANDARDS_BASE_URL}/standards/java/dsl-style-constants.adoc` - -### Language Standards -- Use latest Java LTS version features (Java 17+ minimum) -- Use records for data carriers and DTOs -- Use switch expressions over classic switch statements -- Use text blocks for multi-line strings -- Use var for local variables with obvious types -- Use sealed classes for restricted hierarchies -- Pattern matching in instanceof and switch -- Stream API for complex data transformations -- Use proper access modifiers (prefer package-private over public) -- Mark classes final unless designed for inheritance -- Prefer composition over inheritance -- Return empty collections instead of null -- Use Optional for nullable return values -- Never catch or throw generic Exception or RuntimeException - always use specific exception types -- Use DSL-style nested constants for logging messages -- Follow builder pattern for complex object creation -- Implement fluent interfaces where appropriate -- Use method references over lambdas when possible -- Keep lambda expressions short and clear -- Avoid side effects in streams -- Use immutable objects when possible -- Make fields final by default -- Use enum instead of constants for fixed sets -- Prefer immutable collections (List.of(), Set.of()) -- Avoid magic numbers, use named constants -- Use StringBuilder for string concatenation in loops -- Override toString() for debugging -- Implement equals() and hashCode() together -- Use @Override annotation consistently -- Avoid premature optimization -- See Lombok Usage section for annotation patterns - -### JSpecify Null-Handling -**Reference**: `{STANDARDS_BASE_URL}/standards/java/java-code-standards.adoc#null-safety-and-api-design` -- Use `@Nullable` for fields, parameters, and returns that may be null -- Use `@NonNull` for explicit non-null guarantees -- Default assumption is non-null unless marked `@Nullable` -- Apply `@NullMarked` at package level for consistent null-safety -- Validate null constraints at API boundaries -- Prefer Optional over nullable return types where appropriate - -### Lombok Usage -**Reference**: `{STANDARDS_BASE_URL}/standards/java/java-code-standards.adoc` -- Use `@Builder` for complex object creation -- Use `@Value` for immutable objects -- Use `@ToString` and `@EqualsAndHashCode` for value objects -- Use `@UtilityClass` for utility classes -- Make proper use of `lombok.config` settings - -## Logging Standards -**References**: -- Logging Core Standards: `{STANDARDS_BASE_URL}/standards/logging` -- Logging Implementation Guide: `{STANDARDS_BASE_URL}/standards/logging/implementation-guide.adoc` -- Logging Testing Guide: `{STANDARDS_BASE_URL}/standards/logging/testing-guide.adoc` -- Use `de.cuioss.tools.logging.CuiLogger` (private static final LOGGER) -- Logger must be private static final with constant name 'LOGGER' -- Module/artifact: cui-java-tools -- Exception parameter always comes first in logging methods -- Use '%s' for string substitutions (not '{}' or '%d') -- Use `de.cuioss.tools.logging.LogRecord` for template logging -- Follow logging level ranges: INFO (001-99), WARN (100-199), ERROR (200-299), FATAL (300-399) -- All log messages must be documented in doc/LogMessages.adoc -- No log4j, slf4j, System.out, or System.err usage - -## Testing Standards -**References**: -- Testing Core Standards: `{STANDARDS_BASE_URL}/standards/testing` -- Quality Standards: `{STANDARDS_BASE_URL}/standards/testing/quality-standards.adoc` -- CUI Test Generator Guide: `https://gitingest.com/github.com/cuioss/cui-test-generator` (separate repository) -- Use JUnit 5 (`@Test`, `@DisplayName`, `@Nested`) -- Follow AAA pattern (Arrange-Act-Assert) -- One logical assertion per test -- Tests must be independent and not rely on execution order -- Minimum 80% line and branch coverage -- Use Maven profile `-Pcoverage` for coverage verification -- All public APIs must be tested -- Use cui-test-juli-logger for logger testing with `@EnableTestLogger` -- Use assertLogMessagePresentContaining for testing log messages -- Critical paths must have 100% coverage -- Forbidden: Mockito, PowerMock, Hamcrest - use CUI alternatives - -### CUI Test Generator Usage -**Reference**: `https://gitingest.com/github.com/cuioss/cui-test-generator` (separate repository) -- Mandatory for all test data generation in CUI projects -- Primary framework for creating test objects and data -- Provides type-safe, consistent test data generation -- Use cui-test-value-objects for value object contract testing -- Integrates with parameterized tests via @GeneratorsSource -- See Parameterized Tests Standards for annotation hierarchy - -### Parameterized Tests Standards -**Reference**: `{STANDARDS_BASE_URL}/standards/testing/quality-standards.adoc#parameterized-tests-best-practices` -- **Mandatory** for 3+ similar test variants -- Annotation hierarchy (preferred order): - 1. `@GeneratorsSource` - Most preferred for complex objects - 2. `@CompositeTypeGeneratorSource` - For multiple related types - 3. `@CsvSource` - Standard choice for simple data - 4. `@ValueSource` - Single parameter variations - 5. `@MethodSource` - Last resort only -- Use `@ParameterizedTest` with `@DisplayName` -- Consolidate duplicate test methods -- Provide clear test data and expected outcomes -- Document why @MethodSource if used - -## Documentation Standards -**References**: -- General Documentation: `{STANDARDS_BASE_URL}/standards/documentation` -- Javadoc Standards: `{STANDARDS_BASE_URL}/standards/documentation/javadoc-standards.adoc` -- AsciiDoc Standards: `{STANDARDS_BASE_URL}/standards/documentation/asciidoc-standards.adoc` -- README Structure: `{STANDARDS_BASE_URL}/standards/documentation/readme-structure.adoc` - -### Javadoc Standards -- Every public and protected class/interface must be documented -- Include clear purpose statement in class documentation -- Document all public methods with parameters, returns, and exceptions -- Include `@since` tag with version information -- Document thread-safety considerations -- Include usage examples for complex classes and methods -- Every package must have package-info.java -- Use `{@link}` for references to classes, methods, and fields -- Document Builder classes with complete usage examples - -### General Documentation Standards -- Use AsciiDoc format with `.adoc` extension -- Include proper document header with TOC and section numbering -- Use `:source-highlighter: highlight.js` attribute -- Use `xref:` syntax for cross-references (not `<<>>`) -- Blank lines required before all lists -- Consistent heading hierarchy -- Update main README when adding new documents -- Reference AsciiDoc standards from all relevant documents - -## Process Standards -**Reference**: `{STANDARDS_BASE_URL}/standards/process` -- Follow standardized git commit message format -- Use structured refactoring process for code improvements -- Complete task completion standards for quality assurance -- Maintain Javadoc error resolution process -- Follow Java test maintenance procedures -- Implement logger maintenance standards compliance -- If in doubt, ask the user - never guess or be creative -- Always research topics using available tools - -## Requirements Standards -**References**: -- Requirements Documents: `{STANDARDS_BASE_URL}/standards/requirements` -- Specification Documents: `{STANDARDS_BASE_URL}/standards/requirements/specification-documents.adoc` -- New Project Guide: `{STANDARDS_BASE_URL}/standards/requirements/new-project-guide.adoc` -- All requirements must be traceable to specifications -- Requirements must be specific, measurable, achievable, relevant, time-bound -- Maintain consistent documentation structure across projects -- Link implemented specifications to actual implementation code -- Use standard directory structure: doc/Requirements.adoc, doc/Specification.adoc -- Update specifications when implementation is complete -- See Documentation Standards for AsciiDoc formatting rules - -## AI Tool Specific Instructions - -### For IntelliJ Junie -- Always check for pre-commit profile availability -- Use proper Maven module selection for focused builds -- Leverage IDE integration for testing and debugging -- **Context Management**: Use module-level context awareness for focused assistance -- **Incremental Guidance**: Apply progressive disclosure of standards based on task complexity - -### For Claude Code (Agentic Coding) -- **CLAUDE.md Integration**: Auto-generate and maintain project-specific CLAUDE.md files -- **Permission Management**: Configure safe tool allowlists using `/permissions` command -- **Custom Slash Commands**: Create CUI-specific workflow commands in `.claude/commands/` -- **MCP Integration**: Leverage Model Context Protocol for enhanced capabilities -- Use todo lists for complex multi-step tasks -- Batch tool calls for parallel operations -- Always run lint and typecheck commands after code changes -- **Context Window Optimization**: Prioritize recent and relevant context for token efficiency - -### For GitHub Copilot -- **Repository Instructions**: Maintain `.github/copilot-instructions.md` for repo-specific guidance -- **Setup Steps**: Configure `copilot-setup-steps.yml` for consistent development environments -- **Task Scoping**: Optimize issue descriptions as effective AI prompts -- **Review Iteration**: Structure PR comments for effective AI collaboration using batch reviews -- Context-aware suggestions based on CUI standards -- Follow established patterns in the codebase -- Respect existing code style and architecture - -### For All AI Tools -- **Standards Hierarchy**: Follow the Context Hierarchy and Priority Framework -- **Safety First**: Apply AI Safety and Validation Framework for all outputs -- Always refer to CUI standards documentation before making changes -- Validate against existing patterns in the codebase -- Run tests after any code modifications -- Follow the pre-commit process for code quality -- Document any new public APIs according to Javadoc standards -- Use gitingest.com links for accessing CUI standards repository content -- **Feedback Integration**: Learn from user corrections and adapt instruction effectiveness -- **Escalation Protocol**: When in doubt, ask the user rather than making assumptions - -## Performance and Context Optimization -**Guidelines for Efficient AI Interactions** - -### Context Window Management -- **Prioritize Recent Context**: Weight recent files and conversations higher in decision making -- **Dynamic Context Selection**: Load only relevant standards for current task context -- **Token Economy**: Balance instruction comprehensiveness with context window efficiency -- **Incremental Loading**: Request additional context only when needed for task completion - -### Iterative Improvement Patterns -- **Pattern Recognition**: Identify and codify successful interaction patterns within CUI projects -- **Continuous Calibration**: Adjust instruction effectiveness based on build outcomes and user feedback -- **Workflow Optimization**: Streamline common development workflows through custom commands and templates - -### Integration with Development Workflows -- **CI/CD Awareness**: Understand and respect automated build and deployment processes -- **Quality Gate Integration**: Ensure all outputs pass automated quality checks -- **Collaborative Development**: Optimize for effective human-AI pair programming -- **Knowledge Contribution**: Help maintain and improve team knowledge base and documentation diff --git a/doc/commands.md b/doc/commands.md deleted file mode 100644 index 178b4ce2..00000000 --- a/doc/commands.md +++ /dev/null @@ -1,21 +0,0 @@ -# Command Configuration - -## ./mvnw -Ppre-commit clean install - -### Last Execution Duration -- **Duration**: 57656ms (57.7 seconds) -- **Last Updated**: 2025-10-16 - -### Acceptable Warnings -- OpenRewrite `CuiLogRecordPatternRecipe` warnings about converting logging to LogRecord pattern -- Deprecation warning for `writeProperty` method in test code (intentional test of deprecated API) - -## handle-pull-request - -### CI/Sonar Duration -- **Duration**: 300000ms (5 minutes) -- **Last Updated**: 2025-10-16 - -### Notes -- This duration represents the time to wait for CI and SonarCloud checks to complete -- Includes buffer time for queue delays