diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md new file mode 100644 index 000000000..52f9f6f34 --- /dev/null +++ b/.claude/CLAUDE.md @@ -0,0 +1,247 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Overview + +The Metaschema Java framework provides libraries for working with models defined by the Metaschema modeling language. It supports creating, modifying, parsing, and writing XML, JSON, and YAML instance data conforming to Metaschema models. + +**Metapath** is the project's implementation of XPath 3.1. When implementing or fixing Metapath functions, use the [XPath 3.1 specification](https://www.w3.org/TR/xpath-31/) and [XPath Functions 3.1](https://www.w3.org/TR/xpath-functions-31/) as authoritative references. If behavior differs from the spec, clarify with the user before making changes. + +## Build Commands + +```bash +# Initialize submodules (required before first build, or in new worktrees) +git submodule update --init --recursive + +# Build and install all modules +mvn install + +# CI/CD build (REQUIRED before pushing - includes all quality checks) +mvn install -PCI -Prelease + +# Run tests only +mvn test + +# Run single test class/method +mvn -pl core test -Dtest=FnCountTest +mvn -pl core test -Dtest=FnCountTest#testCount + +# Build specific module (with dependencies) +mvn -pl core -am install + +# Skip tests during build +mvn install -DskipTests + +# Run the CLI locally (after building) +java -jar metaschema-cli/target/metaschema-cli-*-metaschema-cli.jar --help +``` + +### Code Quality Commands + +```bash +mvn license:check # Check license headers +mvn license:format # Add license headers +mvn formatter:validate # Check code formatting +mvn formatter:format # Auto-format code +mvn checkstyle:check # Check Javadoc and style +mvn javadoc:javadoc # Generate Javadoc (find errors) +``` + +## Static Analysis + +Tools configured in parent POM ([oss-maven](https://github.com/metaschema-framework/oss-maven)): + +- **Checkstyle**: Code style, Javadoc enforcement +- **PMD**: Source code analysis (fails on priority 2+ violations) +- **SpotBugs**: Bug pattern detection (uses `spotbugs-exclude.xml`) +- **Jacoco**: Code coverage (target: 60%) + +## Project Architecture + +### Module Hierarchy + +```text +metaschema-framework (parent) +├── core - Core API, Metapath expression language +├── databind - Data binding and code generation +├── schemagen - XML/JSON schema generation +├── databind-modules - Metaschema binding modules +├── metaschema-maven-plugin - Maven plugin for code/schema generation +├── metaschema-testing - Testing utilities +├── cli-processor - CLI framework +└── metaschema-cli - Command-line interface +``` + +### Core Module Structure (dev.metaschema.core) + +- **model/** - Metaschema model interfaces (`IModule`, `IAssemblyDefinition`, `IFieldDefinition`, `IFlagDefinition`) +- **metapath/** - Metapath query language implementation + - **antlr/** - ANTLR4-generated parser (from `src/main/antlr4`) + - **cst/** - Concrete syntax tree expressions + - **function/** - Function library (`core/src/main/java/.../function/library/`) + - **item/** - Metapath item types (node items, atomic items) +- **datatype/** - Data type adapters for Metaschema types +- **mdm/** - Metaschema Document Model node items + +### Key Interfaces + +- `IModule` - Represents a Metaschema module with definitions +- `IModuleLoader` - Loads Metaschema modules from various sources +- `IDataTypeAdapter` - Adapts between Java types and Metaschema data types +- `StaticContext` / `DynamicContext` - Metapath evaluation contexts + +### Generated Code + +- **Metaschema bindings**: Generated from Metaschema modules via metaschema-maven-plugin +- **ANTLR4**: Metapath parser from `core/src/main/antlr4` + +Generated sources go to `target/generated-sources/` and are excluded from style checks. + +### Bootstrap Binding Classes + +Several modules contain pre-generated binding classes due to circular dependencies. **Never manually edit these** - modify the source Metaschema module instead. + +| Module | Bootstrap POM | Source Metaschema | +|--------|--------------|-------------------| +| metaschema-testing | `pom-bootstrap.xml` | `unit-tests.yaml` | +| databind | `pom-bootstrap-config.xml` | `metaschema-bindings.yaml` | +| databind | `pom-bootstrap-model.xml` | `metaschema-module-metaschema.xml` | + +To regenerate: + +```bash +mvn install -DskipTests +mvn -f {module}/pom-bootstrap.xml process-sources +``` + +### Metaschema Module Authoring + +**YAML-first approach**: Prefer YAML format over XML for new modules. +- Store in `src/main/metaschema/` with `.yaml` extension +- Use JSON schema at `databind-modules/target/generated-resources/schema/json/metaschema-model_schema.json` for IDE validation + +## Testing + +- Tests use JUnit 5 with parallel execution enabled +- Test utilities in `metaschema-testing` module +- 100% of unit tests must pass before pushing (BLOCKING) + +### Test-Driven Development (TDD) + +All code changes must follow TDD: +1. **Write tests first** - capture expected behavior +2. **Watch tests fail** - verify tests are meaningful +3. **Write minimal code** - make tests pass +4. **Refactor** - clean up while keeping tests green + +## Code Style + +- Java 11 target +- SpotBugs annotations (`@NonNull`, `@Nullable`) for null safety +- Package structure: `dev.metaschema.*` + +### Javadoc Requirements (BLOCKING) + +Use `dev-metaschema:javadoc-style-guide` skill for full guide. + +- **New code**: 100% Javadoc on `public`/`protected` members (BLOCKING) +- **Modified code**: Add/update Javadoc on touched members +- **Exceptions**: `@Override` methods, `@Test` methods, generated code + +## Git Workflow + +- Repository: +- **All PRs MUST be created from a personal fork** (BLOCKING) +- **All PRs MUST target the `develop` branch** (BLOCKING) +- Clone with submodules: `git clone --recurse-submodules` +- All changes require PR review (CODEOWNERS enforced) + +## Git Worktrees (MANDATORY) + +**All development work MUST be done in a git worktree**, not in the main checkout. + +Worktrees are stored in `.worktrees/` (gitignored). + +```bash +# Create worktree for new feature +git worktree add .worktrees/ -b origin/develop +cd .worktrees/ +git submodule update --init --recursive + +# Check existing worktrees +git worktree list + +# Remove after PR merged +git worktree remove .worktrees/ +``` + +## PRD Workflow + +For larger initiatives, use PRDs stored in `PRDs/-/`: +- `PRD.md` - Requirements document +- `implementation-plan.md` - Detailed PR breakdown + +**PR Size**: Target ≤50 files, maximum 100 files per PR. + +**Verification**: Run `mvn clean install -PCI -Prelease` after each PR. + +### Active PRDs + +| PRD | Description | Status | +|-----|-------------|--------| +| `PRDs/20251206-build-cleanup/` | Build warnings and deprecation removal | In Progress | + +### Completed PRDs + +| PRD | Description | Completed | +|-----|-------------|-----------| +| `PRDs/20251229-javadoc-coverage/` | Complete Javadoc coverage for schemagen, databind, and maven-plugin modules | 2025-12-29 | +| `PRDs/20251228-targeted-report-constraint/` | Add constraint processing support for TargetedReportConstraint (issue #592) | 2025-12-29 | +| `PRDs/20251228-validation-errors/` | Validation error message improvements (#595, #596, #205) | 2025-12-28 | +| `PRDs/20251224-codegen-quality/` | Code generator Javadoc and quality improvements | 2025-12-28 | +| `PRDs/20251217-cli-processor-refactor/` | CLI processor refactoring (issue #252) | 2025-12-21 | +| `PRDs/20251217-context-functions/` | Complete Metapath context functions (issue #162) | 2025-12-17 | +| `PRDs/20251221-xmlbeans-removal/` | Replace XMLBeans with Metaschema bindings | 2025-12-24 | + +## Available Skills + +Use these skills via the Skill tool when working in this repository: + +### Metaschema-Specific (dev-metaschema plugin) + +- `dev-metaschema:development-workflow` - TDD, PRD workflow, parallel agents, debugging +- `dev-metaschema:prd-construction` - Creating PRDs and implementation plans +- `dev-metaschema:repo-organization` - Project structure and module relationships +- `dev-metaschema:unit-test-writing` - Edge case checklist, test patterns +- `dev-metaschema:javadoc-style-guide` - Javadoc requirements and patterns +- `dev-metaschema:claude-md-conventions` - CLAUDE.md structure and content rules +- `dev-metaschema:pr-feedback` - Addressing PR review feedback + +### Metaschema Concepts (metaschema plugin) + +- `metaschema:metaschema-basics` - Introduction and overview +- `metaschema:metaschema-module-authoring` - Module structure, definitions +- `metaschema:metaschema-constraints-authoring` - Constraint types, validation +- `metaschema:metapath-expressions` - Path syntax, operators, functions + +### Metaschema Java Library (metaschema-tools plugin) + +- `metaschema-tools:metaschema-java-library` - Key interfaces, exceptions, Metapath evaluation +- `metaschema-tools:using-metaschema-java` - CLI commands for validation, schema generation + +### Development Workflow (superpowers plugin) + +- `superpowers:brainstorming` - Refine ideas into designs through collaborative questioning +- `superpowers:writing-plans` - Create detailed implementation plans +- `superpowers:executing-plans` - Execute tasks in batches with review checkpoints +- `superpowers:test-driven-development` - Write tests first, then implementation +- `superpowers:systematic-debugging` - 4-phase debugging framework +- `superpowers:root-cause-tracing` - Trace bugs backward to find source +- `superpowers:verification-before-completion` - Confirm work is complete before claiming done +- `superpowers:requesting-code-review` - Review implementation against plan +- `superpowers:receiving-code-review` - Handle code review feedback properly +- `superpowers:dispatching-parallel-agents` - Concurrent work on independent tasks +- `superpowers:subagent-driven-development` - Quality-gated autonomous work +- `superpowers:using-git-worktrees` - Isolated worktree creation and management +- `superpowers:testing-anti-patterns` - Avoid common testing mistakes diff --git a/.claude/settings.json b/.claude/settings.json index 2c63c0851..a3491aeb8 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,2 +1,22 @@ { + "extraKnownMarketplaces": { + "metaschema-framework": { + "source": { + "source": "github", + "repo": "metaschema-framework/claude-plugins" + } + }, + "superpowers-marketplace": { + "source": { + "source": "github", + "repo": "obra/superpowers" + } + } + }, + "enabledPlugins": { + "metaschema@metaschema-framework": true, + "metaschema-tools@metaschema-framework": true, + "dev-metaschema@metaschema-framework": true, + "superpowers@superpowers-marketplace": true + } } diff --git a/.gitignore b/.gitignore index 267721cb5..ea2742110 100644 --- a/.gitignore +++ b/.gitignore @@ -24,6 +24,9 @@ pom.xml.versionsBackup release.properties velocity.log* +# Java files +javac.*.args + # oXygen files /metaschema.xpr diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 8abe444d0..000000000 --- a/CLAUDE.md +++ /dev/null @@ -1,308 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Build Commands - -```bash -# Initialize submodules (required before first build, or in new worktrees) -git submodule update --init --recursive - -# Build and install all modules -mvn install - -# Replicate CI/CD build (recommended before pushing) -mvn install -PCI -Prelease - -# Build with release profile (includes additional checks) -mvn -Prelease install - -# Run tests only -mvn test - -# Run a single test class -mvn -pl core test -Dtest=FnCountTest - -# Run a single test method -mvn -pl core test -Dtest=FnCountTest#testCount - -# Skip tests during build -mvn install -DskipTests - -# Build specific module (e.g., core) -mvn -pl core install - -# Build module with dependencies -mvn -pl core -am install - -# Generate site documentation -mvn site site:stage - -# Check license headers in source files -mvn license:check - -# Add license headers to source files -mvn license:format - -# Check source code formatting -mvn formatter:validate - -# Auto-format source code -mvn formatter:format - -# Check for Checkstyle issues (e.g., missing Javadoc) -mvn checkstyle:check -``` - -## Static Analysis - -The project uses multiple static analysis tools configured in the parent POM (configurations in [oss-maven](https://github.com/metaschema-framework/oss-maven)): - -- **Checkstyle**: Code style enforcement ([checkstyle.xml](https://github.com/metaschema-framework/oss-maven/blob/main/oss-build-support/src/main/resources/checkstyle/checkstyle.xml)) -- **PMD**: Source code analysis, fails on priority 2+ violations ([custom.xml](https://github.com/metaschema-framework/oss-maven/blob/main/oss-build-support/src/main/resources/pmd/category/java/custom.xml)) -- **SpotBugs**: Bug pattern detection (uses `spotbugs-exclude.xml` for exclusions) -- **Jacoco**: Code coverage analysis (target: 60% coverage) - -## Project Architecture - -### Module Dependency Hierarchy - -``` -metaschema-framework (parent) -├── core (metaschema-core) - Core API, Metapath expression language -├── databind (metaschema-databind) - Data binding and code generation -├── schemagen (metaschema-schema-generator) - XML/JSON schema generation -├── databind-modules - Metaschema binding modules -├── metaschema-maven-plugin - Maven plugin for code/schema generation -├── metaschema-testing - Testing utilities -├── cli-processor - CLI framework -└── metaschema-cli - Command-line interface -``` - -### Core Module Structure (dev.metaschema.core) - -- **model/** - Metaschema model interfaces (`IModule`, `IAssemblyDefinition`, `IFieldDefinition`, `IFlagDefinition`) -- **metapath/** - Metapath query language implementation - - **antlr/** - ANTLR4-generated parser (from `src/main/antlr4`) - - **cst/** - Concrete syntax tree expressions - - **function/** - Function library implementation - - **item/** - Metapath item types (node items, atomic items) -- **datatype/** - Data type adapters for Metaschema types -- **mdm/** - Metaschema Document Model node items - -### Metapath and XPath 3.1 - -Metapath is an implementation of XPath 3.1. The [XPath 3.1 specification](https://www.w3.org/TR/xpath-31/) and [XPath Functions 3.1](https://www.w3.org/TR/xpath-functions-31/) should be used as the authoritative behavioral reference when: -- Implementing new Metapath functions -- Fixing bugs in existing function implementations -- Understanding expected error handling behavior - -**When behavior differs from the spec**: If you discover that the current Metapath implementation differs from the XPath 3.1 specification, raise this as a clarification to the user before making changes. Consider: -- Whether the deviation is intentional (Metaschema-specific extension) -- The risk of changing behavior that existing code may depend on -- Whether tests need to be added to verify spec-compliant behavior - -### Generated Code - -Code generation occurs during Maven build: -- **Metaschema bindings**: Generated from Metaschema modules via metaschema-maven-plugin -- **ANTLR4**: Metapath parser from `core/src/main/antlr4` - -Generated sources are placed in `target/generated-sources/` and excluded from style checks. - -### Bootstrap Binding Classes - -Several modules contain pre-generated binding classes that cannot be generated during the normal build due to circular dependencies. These classes must be regenerated manually when their source Metaschema modules change. - -| Module | Bootstrap POM | Generated Package | Source Metaschema | -|--------|--------------|-------------------|-------------------| -| metaschema-testing | `metaschema-testing/pom-bootstrap.xml` | `...model.testing.testsuite` | `unit-tests.yaml` | -| databind | `databind/pom-bootstrap-config.xml` | `...databind.config.binding` | `metaschema-bindings.yaml` | -| databind | `databind/pom-bootstrap-model.xml` | `...databind.model.metaschema.binding` | `metaschema-module-metaschema.xml` | - -To regenerate binding classes: - -```bash -# First ensure the project is built -mvn install -DskipTests - -# Generate binding classes using bootstrap POM (choose the appropriate module) -# Each bootstrap POM generates classes directly into src/main/java -mvn -f metaschema-testing/pom-bootstrap.xml process-sources -mvn -f databind/pom-bootstrap-config.xml process-sources -mvn -f databind/pom-bootstrap-model.xml process-sources -``` - -See the README.md files in each module for detailed instructions. - -### Metaschema Module Authoring - -**YAML-first approach**: When creating new Metaschema modules, prefer YAML format over XML. -- YAML modules use `.yaml` extension and are stored in `src/main/metaschema/` -- Use the JSON schema at `databind-modules/target/generated-resources/schema/json/metaschema-model_schema.json` for IDE validation -- Reference existing YAML modules (e.g., `databind/src/main/metaschema/metaschema-bindings.yaml`) for structure examples - -### Key Interfaces - -- `IModule` - Represents a Metaschema module with definitions -- `IModuleLoader` - Loads Metaschema modules from various sources -- `IDataTypeAdapter` - Adapts between Java types and Metaschema data types -- `StaticContext` / `DynamicContext` - Metapath evaluation contexts - -## Testing - -- Tests use JUnit 5 with parallel execution enabled (Maven Surefire plugin) -- Test utilities are in the `metaschema-testing` module -- Integration tests for the Maven plugin use the maven-invoker-plugin -- All PRs require passing CI checks before merge -- 100% of unit tests must pass before pushing code (BLOCKING) - -### Test-Driven Development (TDD) - -All code changes should follow TDD principles: - -1. **Write tests first**: Before implementing new functionality, write tests that capture the expected behavior -2. **Watch tests fail**: Verify the tests fail with the current implementation (proving the tests are meaningful) -3. **Write minimal code**: Implement just enough code to make the tests pass -4. **Refactor**: Clean up the code while keeping tests green - -For existing code without tests: -- When modifying existing files, add tests as you touch the code -- This ensures behavioral equivalence before and after changes - -```bash -# Run a single test class -mvn -pl core test -Dtest=FnCountTest - -# Run a single test method -mvn -pl core test -Dtest=FnCountTest#testCount -``` - -## Code Style - -- Java 11 target -- Uses SpotBugs annotations (`@NonNull`, `@Nullable`) for null safety -- Package structure follows `dev.metaschema.*` convention - -### Javadoc Requirements (BLOCKING) - -**All code changes must follow the Javadoc style guide**: [docs/javadoc-style-guide.md](docs/javadoc-style-guide.md) - -Key requirements: -- **New code**: 100% Javadoc coverage on `public`/`protected` members (BLOCKING) -- **Modified code**: Add/update Javadoc on any members you touch (Required) -- **Surrounding code**: Document nearby undocumented members when practical (Encouraged) - -Checkstyle enforces these rules (configured in [oss-maven checkstyle.xml](https://github.com/metaschema-framework/oss-maven/blob/main/oss-build-support/src/main/resources/checkstyle/checkstyle.xml)): -- `MissingJavadocMethod` - requires Javadoc on protected+ methods -- `JavadocMethod` - validates `@param`, `@return`, `@throws` tags -- `JavadocType` - requires Javadoc on protected+ types -- `NonEmptyAtclauseDescription` - tags must have meaningful content -- `AtclauseOrder` - tags must follow order: `@param`, `@return`, `@throws`, `@deprecated` - -Exceptions (no Javadoc required): -- `@Override` methods (inherit documentation from interface/superclass) -- `@Test` methods (use descriptive names) -- Generated code (`*.antlr` packages) - -When adding implementation-specific behavior to `@Override` methods, use `{@inheritDoc}` with additional notes: - -```java -/** - * {@inheritDoc} - *

- * Implementation note: delegates to the model container. - */ -@Override -public List getChoiceInstances() { - return getModelContainer().getChoiceInstances(); -} -``` - -### Addressing Automated Review Feedback - -When automated reviewers (e.g., CodeRabbit) flag Javadoc issues: - -1. **Critical/blocking issues**: Address immediately per project conventions -2. **@Override method flags**: Use `{@inheritDoc}` if adding implementation notes, otherwise explain the project exception -3. **Missing `@throws` tags**: Add for declared exceptions -4. **Nitpick suggestions**: Address if in scope, defer otherwise with explanation - -After addressing review comments: -- Reply explaining what was fixed or why the comment doesn't apply -- Close resolved conversation threads - -```bash -# Check Javadoc compliance -mvn checkstyle:check - -# Generate Javadoc to find errors -mvn javadoc:javadoc -``` - -## Git Workflow - -- Repository: https://github.com/metaschema-framework/metaschema-java -- **All PRs MUST be created from a personal fork** (BLOCKING - required by CONTRIBUTING.md) -- **All PRs MUST target the `develop` branch** (BLOCKING - required by CONTRIBUTING.md) -- Clone with submodules: `git clone --recurse-submodules` -- All changes require PR review (CODEOWNERS enforced) -- Squash non-relevant commits before submitting PR (BLOCKING) - -## Databind XML Parsing - -Key entry points for XML deserialization (see `databind/parsing-api-notes.md`): -- `DefaultXmlDeserializer.deserialize(Reader)` - main entry point -- `AbstractClassBinding.readInternal()` - reads flags then body -- `DefaultAssemblyClassBinding.readBody()` - parses assembly model contents -- `DefaultFieldClassBinding` - handles field value parsing - -## PRD Workflow - -For larger initiatives requiring multiple PRs, use a structured PRD (Product Requirements Document) approach. - -### PRD Structure - -PRDs are stored in `PRDs/-/` with: -- `PRD.md` - Main requirements document (goals, requirements, success metrics) -- `implementation-plan.md` - Detailed PR breakdown with acceptance criteria -- Supporting analysis documents as needed - -### PRD Process - -1. **Planning Phase**: Create PRD folder with requirements and implementation plan -2. **PR Size Limits**: Target ≤50 files per PR, maximum 100 files per PR -3. **TDD Requirement**: All functional code changes require test-driven development: - - Write/update tests first to capture expected behavior - - Verify tests pass with existing implementation - - Make code changes - - Verify tests still pass after changes -4. **Verification**: After each PR, run `mvn clean install -PCI -Prelease` -5. **Completion Tracking**: Mark completed items in `implementation-plan.md` acceptance criteria - -### Active PRD Management - -**When starting development on a PRD:** -- Add entry to "Active PRDs" section below with status "In Progress" - -**When completing a PRD:** -- Update status to "Completed" with completion date -- Move to "Completed PRDs" section if list grows - -### Active PRDs - -| PRD | Description | Status | -|-----|-------------|--------| -| `PRDs/20251206-build-cleanup/` | Build warnings and deprecation removal | In Progress | - -### Completed PRDs - -| PRD | Description | Completed | -|-----|-------------|-----------| -| `PRDs/20251229-javadoc-coverage/` | Complete Javadoc coverage for schemagen, databind, and maven-plugin modules | 2025-12-29 | -| `PRDs/20251228-targeted-report-constraint/` | Add constraint processing support for TargetedReportConstraint (issue #592) | 2025-12-29 | -| `PRDs/20251228-validation-errors/` | Validation error message improvements (#595, #596, #205) | 2025-12-28 | -| `PRDs/20251224-codegen-quality/` | Code generator Javadoc and quality improvements | 2025-12-28 | -| `PRDs/20251217-cli-processor-refactor/` | CLI processor refactoring (issue #252) | 2025-12-21 | -| `PRDs/20251217-context-functions/` | Complete Metapath context functions (issue #162) | 2025-12-17 | -| `PRDs/20251221-xmlbeans-removal/` | Replace XMLBeans with Metaschema bindings | 2025-12-24 |