feat(java,kotlin): eject -Dundo, owned-copy notice; drop the dead api-docs model link

Author: dmealing

docs/ports/java.md

@@ -31,6 +31,27 @@ or replaced (`<handEdits>overwrite</handEdits>`). `mvn metaobjects:eject -Dnames
 generator into your repo to own. Commit the manifest. Details:
 [Own your codegen](../features/own-your-codegen.md).
 
+## Undo an eject, strict loading, and diagnostics
+
+**Undo an eject.** `mvn metaobjects:eject -Dundo=true` deletes the owned copies under `codegen/`
+that are identical to the generator this plugin ships (the comparison `-Dlist` shows as
+`[owned — identical]`: the generator, the classes copied with it and its page templates, the
+`package` line and the other lines eject itself rewrites ignored). With `-Dnames=a,b` it removes
+those only, and a copy that differs is refused, with nothing removed, unless `-Dforce=true`; every
+name is checked before anything is deleted. It never edits `pom.xml`: for each generator removed it
+prints the `<classname>` to put back, owned to shipped. The shared support classes and helper
+runtime that eject also wrote stay (other owned generators may import them) and are named. While an
+identical copy exists, `mvn metaobjects:generate` logs one advisory line naming it and this command;
+it never changes the outcome of the build.
+
+**Strict loading.** `metaobjects:generate` already loads strictly, exactly as `metaobjects:verify`
+does (ADR-0023): an attribute no registered provider declares fails the goal with
+`ERR_UNKNOWN_ATTR` before any generator runs, and no file is written. `-Dmeta.lax=true` is the
+opt-out for both goals. There is no separate `-Dstrict` switch.
+
+**No `doctor` goal.** There is no `metaobjects:doctor`; `metaobjects:verify` (drift and the
+requirement gate) and `eject -Dlist` (owned-copy status) are the diagnostics the plugin has.
+
 ## Install
 
 Set `${metaobjects.version}` to the current Maven Central release (`8.1.4`) — both
@@ -382,7 +403,7 @@ name in every port.
 | `report-export` | `SpringReportExportGenerator` | `metaobjects-codegen-spring` | Standalone export of a served report (`?format=csv\|json\|xml`, see [Report export](#report-export)): one `<R>Export` per served report beside its controller (columns in derived-field order, wire-form cells, `MAX_ROWS`, `csv(rows)` and `xml(rows)`) and one shared `ReportExportWriter` (CSV quoting, CRLF, the `EXPORT_CSV_BOM` constant, the formula-injection guard, XML over JDK StAX; no new dependency, Jackson is already there). Args: `outputDir` (required), `maxRows` (default `100000`), `xmlNulls` (`empty`, the default, or `nil`), `csvBom` (default `false`) and `writerPackage` (default: the package prefix the served reports share, else `export`). Never implied by a library. Ejectable. |
 | `trace-helper` | `LlmTraceHelperGenerator` | `metaobjects-codegen-spring` | One `<Entity>TraceHelper` per concrete entity that transitively `extends` `metaobjects::ai::LlmCallBase` **and** nests a `template.prompt` carrying `@responseRef` — a static `record<Entity>(...)` that extracts the typed response, builds the `LlmCallBase` trace row, and persists it. Emits nothing for any other entity. |
 | `template` | `TemplateScopeGenerator` | `metaobjects-codegen-base` | The generic Mustache primitive: walk the model by a named `scope`, render one shared template per walk result, write each file. The declarative alternative to writing a generator class — see [Declarative template-codegen](#declarative-template-codegen-templatescopegenerator) below. It renders through `render.templategen.TemplateGenerator`, the byte-pinned cross-port factory; that factory takes a walk callback and is not itself a `Generator`, so `TemplateScopeGenerator` is the class a pom names. |
-| `api-docs` | `JavaApiDocsGenerator` | `metaobjects-codegen-spring` | The Java SDK api reference: one page per entity, value object, projection, served report and template, an index and `AGENT-API.md`, under `<outputDir>/<apiSubDir>`. A `<generator>` entry like any other, run by `metaobjects:generate` and checked by `metaobjects:verify`. Args: `outputDir` (required; give it generated files only, since `verify` compares the whole tree), `apiSubDir` (default `api/java`), `layout` (`flat`, the default, or `package`), `projectName` (the agent page's header label, default `project`) and `modelBaseUrl` (absolute base for the links to the model pages; relative when unset). The `metaobjects:docs` goal was removed in 8.1.0 ([migration](../features/migrations/docs-are-generators.md#java-and-kotlin)). Ejectable: the copy takes the page IR, the builder, the renderer, the page paths and the page templates with it. |
+| `api-docs` | `JavaApiDocsGenerator` | `metaobjects-codegen-spring` | The Java SDK api reference: one page per entity, value object, projection, served report and template, an index and `AGENT-API.md`, under `<outputDir>/<apiSubDir>`. A `<generator>` entry like any other, run by `metaobjects:generate` and checked by `metaobjects:verify`. Args: `outputDir` (required; give it generated files only, since `verify` compares the whole tree), `apiSubDir` (default `api/java`), `layout` (`flat`, the default, or `package`), `projectName` (the agent page's header label, default `project`) and `modelBaseUrl` (absolute base for the links to the model pages; with none set the pages carry no `Model / metadata` link, since nothing writes a page for it to point at). The `metaobjects:docs` goal was removed in 8.1.0 ([migration](../features/migrations/docs-are-generators.md#java-and-kotlin)). Ejectable: the copy takes the page IR, the builder, the renderer, the page paths and the page templates with it. |
 | `plantuml` | `PlantUMLGenerator` | `metaobjects-codegen-plantuml` | One PlantUML class diagram of the object model (`outputDir`, `outputFilename`; `showAttrs`, `showFields`, `showAbstracts`, `drawKeys`, `drawRefs` choose what is drawn). Ejectable: the copy takes `PlantUMLWriter` with it. |
 | `html-docs` | `MetaDataHtmlDocumentationGenerator` | `metaobjects-codegen-base` | One HTML page describing the registered metamodel types (`outputDir`, `outputFilename`). It reads the type registry, not your model, so it documents the vocabulary your build loads, providers included. Ejectable: the copy takes `MetaDataHtmlDocumentationWriter` with it. |
 | `ai-docs` | `MetaDataAIDocumentationGenerator` | `metaobjects-codegen-base` | The same type reference as JSON, laid out for an AI reader (`outputDir`, `outputFilename`). Ejectable: the copy takes `MetaDataAIDocumentationWriter` with it. |

docs/ports/kotlin.md

@@ -28,6 +28,27 @@ manifest (`.metaobjects/.gen-state/.hashes.json`) is overwritten, and an edited
 name (or replaced with `<handEdits>overwrite</handEdits>`). `mvn metaobjects:eject -Dnames=<name>`
 copies a generator into your repo to own.
 
+## Undo an eject, strict loading, and diagnostics
+
+**Undo an eject.** `mvn metaobjects:eject -Dundo=true` deletes the owned copies under `codegen/`
+that are identical to the generator this plugin ships (the comparison `-Dlist` shows as
+`[owned — identical]`: the generator, the classes copied with it and its page templates, the
+`package` line and the other lines eject itself rewrites ignored). With `-Dnames=a,b` it removes
+those only, and a copy that differs is refused, with nothing removed, unless `-Dforce=true`; every
+name is checked before anything is deleted. It never edits `pom.xml`: for each generator removed it
+prints the `<classname>` to put back, owned to shipped. The shared support classes and helper
+runtime that eject also wrote stay (other owned generators may import them) and are named. While an
+identical copy exists, `mvn metaobjects:generate` logs one advisory line naming it and this command;
+it never changes the outcome of the build.
+
+**Strict loading.** `metaobjects:generate` already loads strictly, exactly as `metaobjects:verify`
+does (ADR-0023): an attribute no registered provider declares fails the goal with
+`ERR_UNKNOWN_ATTR` before any generator runs, and no file is written. `-Dmeta.lax=true` is the
+opt-out for both goals. There is no separate `-Dstrict` switch.
+
+**No `doctor` goal.** There is no `metaobjects:doctor`; `metaobjects:verify` (drift and the
+requirement gate) and `eject -Dlist` (owned-copy status) are the diagnostics the plugin has.
+
 ## Install
 
 Every version below comes from one `<properties>` entry. Set the Java level (Maven defaults to
@@ -156,7 +177,7 @@ The 17 generators registered in `codegen-kotlin` (`GeneratorRegistry.kt`):
 | `KotlinSpringControllerGenerator` | `<Entity>Controller.kt` — Spring `@RestController` (5 CRUD endpoints; cross-port API contract). **Select `KotlinRelationsGenerator` with it** when the model has a M:N relationship: the traversal routes call the `<rel>Query` helpers only that generator emits, and without it the controller does not compile | entities with `source.rdb @kind="table"` |
 | `KotlinRequirementTestsGenerator` | Per metamodel package that holds a tested requirement, two files in `testPackage`: `Requirements_<pkgKey>_Witnesses.kt` (an interface whose default members fail with `unimplemented requirement: ...`) and `Requirements_<pkgKey>_Test.kt` (one JUnit Jupiter `@Test` per requirement, calling a project-owned witness). See "Requirement tests" below | every tested `requirement.*` (functional, level 4 or above by default) |
 | `KotlinReportExportGenerator` | Standalone export of a served report (`?format=csv\|json\|xml`, see [Report export](#report-export)): one `<Report>Export.kt` per served report beside its controller and one shared `ReportExportWriter.kt`. Args: `outputDir` (required), `maxRows` (default `100000`), `xmlNulls` (`empty`, the default, or `nil`), `csvBom` (default `false`) and `writerPackage` (default: the package prefix the served reports share, else `export`). Never implied by a library. Ejectable | every served report |
-| `KotlinApiDocsGenerator` | The Kotlin SDK api reference, under `<outputDir>/<apiSubDir>`: `<Unit>.md` per entity, value object, projection, served report and template, a `README.md` index and `AGENT-API.md`. A `<generator>` entry like any other, run by `metaobjects:generate` and checked by `metaobjects:verify`. Args: `outputDir` (required, generated files only), `apiSubDir` (default `api/kotlin`), `layout` (`flat` or `package`), `projectName` and `modelBaseUrl`, as for the Java `api-docs`. The `metaobjects:docs` goal was removed in 8.1.0 ([migration](../features/migrations/docs-are-generators.md#java-and-kotlin)). Ejectable, with the page model, builder, renderer and path math | the whole model, once |
+| `KotlinApiDocsGenerator` | The Kotlin SDK api reference, under `<outputDir>/<apiSubDir>`: `<Unit>.md` per entity, value object, projection, served report and template, a `README.md` index and `AGENT-API.md`. A `<generator>` entry like any other, run by `metaobjects:generate` and checked by `metaobjects:verify`. Args: `outputDir` (required, generated files only), `apiSubDir` (default `api/kotlin`), `layout` (`flat` or `package`), `projectName` and `modelBaseUrl`, as for the Java `api-docs` (with no `modelBaseUrl` the pages carry no `Model / metadata` link). The `metaobjects:docs` goal was removed in 8.1.0 ([migration](../features/migrations/docs-are-generators.md#java-and-kotlin)). Ejectable, with the page model, builder, renderer and path math | the whole model, once |
 
 Maven wiring. The plugin bundles `metaobjects-codegen-kotlin`, so it is not a dependency of your
 project. Keep `<configuration>` at plugin level and bind the goal in `<executions>`: without the

server/java/codegen-kotlin/src/main/kotlin/com/metaobjects/generator/kotlin/apidocs/KotlinApiDocsGenerator.kt

@@ -47,7 +47,10 @@ class KotlinApiDocsGenerator : FileEmittingGenerator() {
         }
         for (unit in model.units) {
             val pagePath = DocsPaths.docPageOutputPath(layout, unit.pkg, unit.node)
-            val modelHref = DocsPaths.modelCrossHref("$subDir/$pagePath", pagePath, modelBaseUrl)
+            // No model pages are written beside the api pages, so a relative link would be dead:
+            // the link is emitted only against a <modelBaseUrl> that hosts them.
+            val modelHref = if (modelBaseUrl.isNullOrEmpty()) null
+                else DocsPaths.modelCrossHref("$subDir/$pagePath", pagePath, modelBaseUrl)
             add(pagePath, renderer.renderUnitPage(unit, modelHref))
         }
         add("README.md", renderer.renderIndex(model, layout))
@@ -65,7 +68,7 @@ class KotlinApiDocsGenerator : FileEmittingGenerator() {
         /** Arg: the page layout, `flat` (one file per unit, the default) or `package`. */
         const val ARG_LAYOUT: String = "layout"
 
-        /** Arg: when set, the base URL the pages' links to the model pages are written against. */
+        /** Arg: the base URL the pages' links to the model pages are written against; with none set, the pages carry no such link. */
         const val ARG_MODEL_BASE_URL: String = "modelBaseUrl"
 
         /** The api-surface subdirectory of the cross-port docs contract. */

server/java/codegen-spring/src/main/java/com/metaobjects/generator/apidocs/JavaApiDocsGenerator.java

@@ -41,7 +41,7 @@ public final class JavaApiDocsGenerator extends FileEmittingGenerator {
     /** Arg: the page layout, {@code flat} (one file per unit, the default) or {@code package}. */
     public static final String ARG_LAYOUT = "layout";
 
-    /** Arg: when set, the base URL the pages' links to the model pages are written against. */
+    /** Arg: the base URL the pages' links to the model pages are written against; with none set, the pages carry no such link. */
     public static final String ARG_MODEL_BASE_URL = "modelBaseUrl";
 
     /** The api-surface subdirectory of the cross-port docs contract. */
@@ -67,7 +67,10 @@ protected List<EmittedFile> generate(MetaDataLoader loader) {
         Set<String> paths = new HashSet<>();
         for (ApiUnit unit : model.units()) {
             String pagePath = DocsPaths.docPageOutputPath(layout, unit.pkg(), unit.node());
-            String modelHref = DocsPaths.modelCrossHref(subDir + "/" + pagePath, pagePath, modelBaseUrl);
+            // No model pages are written beside the api pages, so a relative link would be dead:
+            // the link is emitted only against a <modelBaseUrl> that hosts them.
+            String modelHref = modelBaseUrl == null || modelBaseUrl.isEmpty() ? null
+                    : DocsPaths.modelCrossHref(subDir + "/" + pagePath, pagePath, modelBaseUrl);
             add(pages, paths, subDir, pagePath, renderer.renderUnitPage(unit, modelHref));
         }
         add(pages, paths, subDir, "README.md", renderer.renderIndex(model, layout));