This is an automated email from the ASF dual-hosted git repository. lukaszlenart pushed a commit to branch feat/WW-5864-struts-maven-plugin-watch in repository https://gitbox.apache.org/repos/asf/struts.git
commit 2471b04e08b0ca7cc489c8461a67139d36c3aa08 Author: Lukasz Lenart <[email protected]> AuthorDate: Sat Nov 14 08:34:28 2026 +0100 WW-5864 docs(plan): implementation plan for the struts:watch goal Co-Authored-By: Claude Opus 5.5 <[email protected]> --- .../plans/2026-11-14-struts-maven-plugin-watch.md | 314 +++++++++++++++++++++ 1 file changed, 314 insertions(+) diff --git a/docs/superpowers/plans/2026-11-14-struts-maven-plugin-watch.md b/docs/superpowers/plans/2026-11-14-struts-maven-plugin-watch.md new file mode 100644 index 000000000..2cd2efb60 --- /dev/null +++ b/docs/superpowers/plans/2026-11-14-struts-maven-plugin-watch.md @@ -0,0 +1,314 @@ +# `struts:watch` Maven Goal Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** A `struts-maven-plugin` whose `watch` goal pushes changed resource files into +`target/classes` (with the project's own filtering), so Struts' devMode reload picks them up +without a server restart. + +**Architecture:** Pure, Maven-free core classes (scan → diff/debounce → push) behind a thin +`WatchMojo`. Pushing reuses `maven-filtering`'s `MavenResourcesFiltering` with settings read +from the project's effective `maven-resources-plugin` configuration. A best-effort inspector +warns when Struts' reload switches are off. One invoker IT drives the real goal. + +**Tech Stack:** Java 17, Maven Plugin API + annotations, `maven-filtering`, +`plexus-utils` (`DirectoryScanner`, `Xpp3Dom`), JUnit 4 + AssertJ, `maven-invoker-plugin`. + +**Spec:** `docs/superpowers/specs/2026-11-14-struts-maven-plugin-watch-design.md` (WW-5864) + +## Global Constraints + +- Every commit message starts `WW-5864 `; branch `feat/WW-5864-struts-maven-plugin-watch`. +- Module path `tools/struts-maven-plugin`; `groupId` `org.apache.struts`, `artifactId` + `struts-maven-plugin`, packaging `maven-plugin` → goal prefix `struts`. +- Java package `org.apache.struts2.maven.watch`. +- No dependency on `struts2-core`. Maven API artifacts are `provided` scope. +- Tests are JUnit 4 (`org.junit.Test`) + AssertJ. No Jupiter. +- Every new file carries the ASF license header (RAT runs in the build), including invoker + fixture files. +- Polling, not `WatchService`. Default interval 500 ms. +- Single module only: if the goal is about to run and `session.getProjects().size() > 1`, + fail with: `struts:watch supports a single module; run it in the module that owns the + resources, e.g. -pl <module>`. +- Background mode does nothing unless `struts.watch=true`. Blocking mode always runs. +- Never fetch an external DTD while reading `struts.xml`. +- Default to no code comments (user's global rule); Javadoc only on Mojo parameters, where it + becomes the generated goal docs. +- Build with `./mvnw -B ... > log 2>&1; echo $?` and read the log; never judge a build from a + filtered pipe. + +## Review Focus + +1. **Editor atomic save** (temp file + rename, or delete-then-create within one poll): one + push, never a delete of the output file. → Task 2 test + `deleteFollowedByRecreateBeforeStableIsAPushNotADelete`. +2. **New file in a new sub-directory** (`com/acme/FooAction.properties`): output parent + directories are created. → Task 3 test `pushCreatesMissingParentDirectories`. +3. **`target/` cleaned while watching** (`mvn clean` in another terminal): the next change + still pushes. → Task 3 test `pushAfterOutputDirectoryDeletedRecreatesIt`. +4. **Push failure** (filtering error, locked file): logged, watcher keeps running. → Task 2 + test `pusherFailureIsReportedAndWatchingContinues`. +5. **Binary resource in a filtered directory** (an image under a `<filtering>true</filtering>` + resource): copied byte-for-byte via `nonFilteredFileExtensions`. → Task 3 test + `binaryFileInFilteredResourceIsCopiedUnchanged`. + +--- + +### Task 1: Module skeleton and resources-plugin settings + +**Files:** +- Create: `tools/pom.xml` (aggregator, `artifactId` `struts2-tools`, packaging `pom`, parent + `struts2-parent` with `relativePath` `../parent/pom.xml`, module `struts-maven-plugin`) +- Create: `tools/struts-maven-plugin/pom.xml` +- Modify: `pom.xml` (root `<modules>`: add `<module>tools</module>` after `boot`) +- Create: `tools/struts-maven-plugin/src/main/java/org/apache/struts2/maven/watch/ResourcesPluginSettings.java` +- Test: `tools/struts-maven-plugin/src/test/java/org/apache/struts2/maven/watch/ResourcesPluginSettingsTest.java` + +**Interfaces:** +- Produces: `ResourcesPluginSettings` (immutable) with + `static ResourcesPluginSettings from(Xpp3Dom configuration, String projectEncoding)` (null + configuration → defaults) and getters `getEncoding()`, `getPropertiesEncoding()`, + `getDelimiters(): LinkedHashSet<String>`, `isUseDefaultDelimiters()`, `getEscapeString()`, + `getNonFilteredFileExtensions(): List<String>`, `isAddDefaultExcludes()`. +- Produces: `static Xpp3Dom effectiveResourcesConfiguration(MavenProject project)` on the same + class — the `maven-resources-plugin` plugin-level configuration merged with its + `default-resources` execution configuration (execution wins). + +- [ ] **Step 1: Plugin pom.** Parent `struts2-tools`. Plugins: `maven-plugin-plugin` 3.15.1 + (`goalPrefix` `struts`, `helpmojo` execution). Dependencies: `maven-plugin-api` and + `maven-core` 3.9.11 `provided`; `maven-plugin-annotations` 3.15.1 `provided`; + `org.apache.maven.shared:maven-filtering` 3.4.0; `junit`, `assertj-core` `test` (versions + from the parent's dependencyManagement). Check Central for newer releases of the four pinned + versions; prefer the newest that supports Java 17 and Maven 3.9. +- [ ] **Step 2: Write the failing tests** in `ResourcesPluginSettingsTest`: + - `defaultsWhenNoConfiguration`: `from(null, "UTF-8")` → encoding `UTF-8`, delimiters + empty, `isUseDefaultDelimiters()` true, `isAddDefaultExcludes()` true, + `getNonFilteredFileExtensions()` empty, escape string null. + - `readsAllFilteringSettings`: an `Xpp3Dom` built from + `<configuration><encoding>ISO-8859-1</encoding><propertiesEncoding>UTF-8</propertiesEncoding><delimiters><delimiter>@</delimiter></delimiters><useDefaultDelimiters>false</useDefaultDelimiters><escapeString>\</escapeString><nonFilteredFileExtensions><nonFilteredFileExtension>png</nonFilteredFileExtension></nonFilteredFileExtensions><addDefaultExcludes>false</addDefaultExcludes></configuration>` + (parse with `Xpp3DomBuilder.build(new StringReader(...))`) → each getter returns that value. + - `executionConfigurationOverridesPluginConfiguration`: a `MavenProject` with a + `maven-resources-plugin` whose plugin config sets `encoding` `A` and whose + `default-resources` execution sets `encoding` `B` → `effectiveResourcesConfiguration` + yields `B`. +- [ ] **Step 3: Run** `./mvnw -B test -DskipAssembly -pl tools/struts-maven-plugin -am > <scratchpad>/watch-build.log 2>&1; echo $?` + (log outside the repo — a log in the root fails RAT) — expect compile failure / test failures. +- [ ] **Step 4: Implement** `ResourcesPluginSettings`. Merge with + `Xpp3Dom.mergeXpp3Dom(execution, plugin)`. +- [ ] **Step 5: Run the tests** — expect PASS, and the full module build (`verify`) green + including RAT. +- [ ] **Step 6: Commit** `WW-5864 build(tools): add struts-maven-plugin module skeleton`. + +### Task 2: Scanning and the debounced watcher loop + +**Files:** +- Create: `.../watch/WatchedRoot.java`, `.../watch/FileStamp.java`, `.../watch/SourceFile.java`, + `.../watch/ResourceScanner.java`, `.../watch/ResourcePusher.java`, + `.../watch/ResourceWatcher.java` +- Test: `.../watch/ResourceScannerTest.java`, `.../watch/ResourceWatcherTest.java` + +**Interfaces:** +- Produces: `WatchedRoot` — `Path directory`, `List<String> includes`, + `List<String> excludes`, `String targetPath` (nullable), `boolean filtering`; built from a + Maven `Resource` with `static WatchedRoot of(Resource resource, Path basedir)`. +- Produces: `FileStamp(long lastModified, long size)` with value equality. +- Produces: `ResourceScanner` — `ResourceScanner(List<WatchedRoot> roots, boolean + addDefaultExcludes)`, `Map<SourceFile, FileStamp> scan()`, where + `SourceFile(WatchedRoot root, String relativePath)` has value equality. Uses + `DirectoryScanner` with the root's includes (default `**/**`) and excludes; a missing + root directory yields no entries. +- Produces: `ResourcePusher` interface — `void push(SourceFile file) throws IOException`, + `void delete(SourceFile file) throws IOException`. +- Produces: `ResourceWatcher` — `ResourceWatcher(ResourceScanner scanner, ResourcePusher + pusher, List<Path> filterFiles, Consumer<String> info, BiConsumer<String, Exception> error)`; + `void start()` (takes the baseline scan), `void pollOnce()`, `void run(Duration interval, + BooleanSupplier keepRunning)`. + +Debounce rule (not determined by the signatures): a path is acted on only when two +consecutive scans agree on it after it differed from the last acted-on state — present with +the same stamp in both → `push`; absent in both → `delete`. A filter-file stamp change, once +stable across two scans, pushes every file whose root has `filtering == true`. + +- [ ] **Step 1: Write the failing tests.** `ResourceScannerTest` (temp dirs via + `TemporaryFolder`): `listsFilesHonouringIncludesAndExcludes`, + `skipsDefaultExcludesWhenEnabled` (`.DS_Store`/`*~` ignored), + `missingRootDirectoryYieldsNoFiles`. `ResourceWatcherTest` with a recording fake pusher and a + fake scanner fed a list of scan results: + - `changeIsPushedOnceAfterTwoStableScans` → after scans `{a:1}`,`{a:2}`,`{a:2}`,`{a:2}`: + pushes `[a]`. + - `deletionIsMirroredAfterTwoStableScans` → `{a:1}`,`{}`,`{}`: deletes `[a]`. + - `deleteFollowedByRecreateBeforeStableIsAPushNotADelete` → `{a:1}`,`{}`,`{a:2}`,`{a:2}`: + deletes `[]`, pushes `[a]`. + - `unchangedFilesAreNeverPushed` → `{a:1}`,`{a:1}`,`{a:1}`: pushes `[]`. + - `filterFileChangeRepushesFilteredResourcesOnly` → filtered root file `f`, unfiltered `u`, + filter-file stamp changes and stabilises: pushes `[f]`. + - `pusherFailureIsReportedAndWatchingContinues` → pusher throws on `a`, then `b` changes: + `error` called once for `a`, `b` still pushed. + - `runStopsWhenKeepRunningTurnsFalse` → `run(Duration.ofMillis(10), ...)` returns. +- [ ] **Step 2: Run** — expect FAIL (classes missing). +- [ ] **Step 3: Implement** the five types. `ResourceScanner` should be non-final with + `scan()` overridable, so tests can feed scans. +- [ ] **Step 4: Run** — expect PASS. +- [ ] **Step 5: Commit** `WW-5864 feat(tools): scan resource roots and debounce changes`. + +### Task 3: Filtering pusher + +**Files:** +- Create: `.../watch/FilteringResourcePusher.java` +- Test: `.../watch/FilteringResourcePusherTest.java` + +**Interfaces:** +- Consumes: `ResourcePusher`, `SourceFile`, `WatchedRoot` (Task 2); `ResourcesPluginSettings` + (Task 1). +- Produces: `FilteringResourcePusher(MavenResourcesFiltering filtering, MavenProject project, + MavenSession session, ResourcesPluginSettings settings, Path outputDirectory)`, plus + `Path outputPathOf(SourceFile file)` = `outputDirectory[/targetPath]/relativePath`. + +- [ ] **Step 1: Write the failing tests** (use `DefaultMavenResourcesFiltering` wired by hand + or via a Sisu/`PlexusTestCase`-free construction; temp dirs): + - `pushCopiesUnfilteredFile` → bytes equal. + - `pushFiltersPlaceholdersFromProjectProperties` → source `name=${greeting}`, project + property `greeting=hi` → output `name=hi`. + - `pushHonoursCustomDelimiter` → settings delimiter `@`, source `name=@greeting@` → `name=hi`. + - `pushHonoursTargetPath` → root `targetPath` `conf` → output at `conf/a.xml`. + - `pushCreatesMissingParentDirectories` → `com/acme/FooAction.properties` lands. + - `pushAfterOutputDirectoryDeletedRecreatesIt`. + - `binaryFileInFilteredResourceIsCopiedUnchanged` → `nonFilteredFileExtensions` `png`, + a PNG with `${` bytes stays byte-identical. + - `deleteRemovesOutputFile` and `deleteOfMissingOutputIsANoOp`. +- [ ] **Step 2: Run** — expect FAIL. +- [ ] **Step 3: Implement.** For `push`, build a one-file `Resource` (directory = root, + `includes` = the relative path, `targetPath`, `filtering`) and call + `MavenResourcesFiltering.filterResources(MavenResourcesExecution)` with the settings + applied (encoding, propertiesEncoding, delimiters, useDefaultDelimiters, escapeString, + nonFilteredFileExtensions, `build.filters`, overwrite = true). +- [ ] **Step 4: Run** — expect PASS. +- [ ] **Step 5: Commit** `WW-5864 feat(tools): push changed resources through maven-filtering`. + +### Task 4: Struts reload-settings inspector + +**Files:** +- Create: `.../watch/StrutsReloadInspector.java` +- Test: `.../watch/StrutsReloadInspectorTest.java` + +**Interfaces:** +- Produces: `StrutsReloadInspector(Path outputDirectory)`, `List<String> warnings()`. + +Rule (mirrors `StrutsBeanSelectionProvider#switchDevMode`): read `<constant name value>` from +`outputDirectory/struts.xml` and keys from `outputDirectory/struts.properties` (properties win +on conflict). Effective `struts.configuration.xml.reload` / `struts.i18n.reload` = explicit +value if present, else the devMode value. Warn per switch that is effectively not `true`. +Missing files, parse errors and absent keys produce no exception; when neither file sets +`struts.devMode`, emit one soft warning that devMode was not found (it may be set elsewhere). + +- [ ] **Step 1: Write the failing tests:** + - `devModeTrueNoWarnings`. + - `devModeFalseWarnsForBothReloadSwitches` → two warnings naming + `struts.configuration.xml.reload` and `struts.i18n.reload`. + - `explicitFalseOverridesDevMode` → devMode `true`, `struts.i18n.reload` `false` → one + warning naming `struts.i18n.reload`. + - `propertiesFileOverridesXml`. + - `devModeNotFoundGivesSoftWarning`. + - `doesNotFetchExternalDtd` → `struts.xml` with + `<!DOCTYPE struts PUBLIC "x" "http://127.0.0.1:1/never.dtd">` parses and yields the + constants (no network). + - `malformedXmlProducesNoException`. +- [ ] **Step 2: Run** — expect FAIL. +- [ ] **Step 3: Implement** with `DocumentBuilderFactory`: disable + `http://apache.org/xml/features/nonvalidating/load-external-dtd`, external general and + parameter entities, and XInclude; set `setExpandEntityReferences(false)`. +- [ ] **Step 4: Run** — expect PASS. +- [ ] **Step 5: Commit** `WW-5864 feat(tools): warn when Struts reload switches are off`. + +### Task 5: `WatchMojo` + +**Files:** +- Create: `.../watch/WatchMojo.java` +- Test: `.../watch/WatchMojoTest.java` + +**Interfaces:** +- Consumes: everything above. +- Produces: `@Mojo(name = "watch", defaultPhase = LifecyclePhase.PROCESS_RESOURCES, + threadSafe = true)` with parameters: + - `pollInterval` (`long`, ms, default `500`, property `struts.watch.pollInterval`) + - `background` (`boolean`, default `false`, property `struts.watch.background`) + - `enabled` (`boolean`, default `false`, property `struts.watch`) — consulted only when + `background` is true + - `timeout` (`long`, seconds, default `0` = until stopped, property `struts.watch.timeout`) + — blocking mode stops after it; used by scripted runs and the IT + - injected `MavenProject`, `MavenSession`, `MavenResourcesFiltering`. +- Produces: package-private `boolean shouldRun()` and `void checkSingleModule()` for tests. + +Behaviour: `background && !enabled` → log one debug line, return. Otherwise +`checkSingleModule()`; log inspector warnings at WARN; build roots from +`project.getResources()`; at start push every file whose output is missing or older than its +source; then blocking → `watcher.run(...)` on the calling thread until Ctrl+C or `timeout`; +background → start a daemon thread named `struts-watch` running `watcher.run(...)` and +return. Log one INFO line per push: `pushed <relative> -> <output path relative to basedir>`. + +- [ ] **Step 1: Write the failing tests:** + - `backgroundWithoutEnabledDoesNotRun` → `shouldRun()` false. + - `backgroundWithEnabledRuns` and `blockingAlwaysRuns`. + - `multiModuleSessionFailsWithGuidance` → `checkSingleModule()` throws + `MojoFailureException` whose message contains `-pl <module>`. + - `staleOutputsArePushedAtStart` → source newer than output gets pushed, up-to-date one not. +- [ ] **Step 2: Run** — expect FAIL. +- [ ] **Step 3: Implement.** +- [ ] **Step 4: Run** — expect PASS; `./mvnw -B verify -DskipAssembly -pl tools/struts-maven-plugin -am` green, and the generated `struts:help` lists the four parameters. +- [ ] **Step 5: Commit** `WW-5864 feat(tools): add the struts:watch goal`. + +### Task 6: Invoker integration test + +**Files:** +- Modify: `tools/struts-maven-plugin/pom.xml` (`maven-invoker-plugin` 3.9.1: `install` + + `integration-test` + `verify`, `cloneProjectsTo` `target/it`, `postBuildHookScript` + `verify`, `preBuildHookScript` `prebuild`) +- Create: `tools/struts-maven-plugin/src/it/watch-pushes-change/{pom.xml,invoker.properties,prebuild.groovy,verify.groovy,src/main/resources/struts.xml,src/main/resources/messages.properties}` + +- [ ] **Step 1: Fixture.** Pom declares the plugin at `@project.version@`, a filtered resource + directory, and property `greeting=hi`. `messages.properties` is `msg=${greeting}-v1`. + `invoker.properties`: `invoker.goals = process-resources ${project.groupId}:${project.artifactId}:${project.version}:watch -Dstruts.watch.timeout=20`. +- [ ] **Step 2: `prebuild.groovy`** starts a daemon thread that sleeps 8 s, then rewrites + `src/main/resources/messages.properties` to `msg=${greeting}-v2` and deletes nothing. +- [ ] **Step 3: `verify.groovy`** asserts `target/classes/messages.properties` contains + `msg=hi-v2` and `build.log` contains `pushed messages.properties`. +- [ ] **Step 4: Run** `./mvnw -B verify -DskipAssembly -pl tools/struts-maven-plugin -am` — + expect the IT to pass. Then temporarily break the push (return early in + `FilteringResourcePusher.push`) and confirm the IT fails; revert. +- [ ] **Step 5: Commit** `WW-5864 test(tools): invoker IT for struts:watch`. + +### Task 7: Showcase reference setup and Jetty scanner + +**Files:** +- Modify: `apps/showcase/pom.xml` (Jetty plugin config; add `struts-maven-plugin` with an + execution `watch` bound to `process-resources`, `<background>true</background>`) +- Modify: `apps/rest-showcase/pom.xml` (Jetty scanner config only) + +- [ ] **Step 1: Find the Jetty 11 scanner setting** that keeps scanning compiled classes but + ignores resource files in `target/classes`: check `jetty-maven-plugin` 11.0.26's + `scanClassesPattern` (`<excludes>`). Record the outcome in the commit message. If no such + exclude exists, set `<scan>0</scan>` instead. +- [ ] **Step 2: Apply** it to both showcase poms and add the bound background execution to + `apps/showcase/pom.xml`. +- [ ] **Step 3: Prove CI stays inert:** `./mvnw -B package -DskipTests -DskipITs -DskipAssembly -pl apps/showcase -am` + exits 0 and the log has no `pushed` / `struts-watch` lines. +- [ ] **Step 4: Manual end-to-end check** (temporarily set `struts.devMode=true` in the + showcase `struts.xml`, do not commit it): + `./mvnw -B -pl apps/showcase -DskipAssembly -Dstruts.watch jetty:run`, then add a probe + action to `src/main/resources/struts.xml` and change a key in `globalMessages.properties`. + Expect: a `pushed` line for each, the new action answering on the next request, the new + message rendering, and no Jetty `Restarting` line. This is the check that the background + thread survives `jetty:run`'s forked lifecycle. +- [ ] **Step 5: Commit** `WW-5864 build(showcase): reference struts:watch setup and Jetty scanner`. + +### Task 8: Docs + +**Files:** +- Create: `tools/struts-maven-plugin/README.md` (RAT excludes `**/README.md`) + +- [ ] **Step 1:** README: what the goal does and does not do (Java classes out of scope), + the two ways to run it (`mvn struts:watch -pl <module>` next to the server; + `mvn jetty:run -Dstruts.watch` with the bound execution), the four parameters, the Jetty + scanner setting from Task 7, and the single-module limitation. +- [ ] **Step 2: Commit** `WW-5864 docs(tools): struts-maven-plugin usage`. The struts-site + page is a follow-up PR in that repo.
