no-mistakes(review): Count owned runtime adapter in undo; gate api-docs entity symbols

Author: dmealing

CHANGELOG.md

@@ -220,9 +220,11 @@ here.**
   It is now written only when `modelBaseUrl` is set.
 
 - **TypeScript API docs describe only what the run writes.** The `api-docs` pages listed the
-  stock queries and Fastify routes for every entity, whatever the generator list held. A project
-  that wires neither now gets pages without them, and an owned generator that writes them
-  counts when it carries the `emitsQueries` or `mountsRoutes` marker.
+  stock entity module (the model, its Zod schemas and `relations()`), queries and Fastify routes
+  for every entity, whatever the generator list held. A project that wires none of them, such as
+  the `meta init --with-docs` scaffold, now gets pages without them. An owned generator that
+  writes one counts when it carries the `emitsEntityModule`, `emitsQueries` or `mountsRoutes`
+  marker.
 
 - **The metamodel reference index reads as prose.** The generated index said "NOT documentation"
   in capitals and told a reader of an HTML page to "follow a link into `types/<family>.md`". It

server/csharp/MetaObjects.Cli.Tests/EjectUndoTests.cs

@@ -153,4 +153,36 @@ public void Gen_notice_names_identical_copies_and_the_undo_command_and_is_silent
         Assert.DoesNotContain("entity", notice);
         Assert.Contains("dotnet meta eject --undo", notice);
     }
+
+    [Fact]
+    public void A_changed_helper_runtime_keeps_its_generator_out_of_the_notice_and_out_of_no_name_undo()
+    {
+        Eject("routes");
+        Assert.Contains("routes", OwnedCopy.IdenticalNotice(_root)!);
+        var runtimeFile = $"{HelperRuntime.OwnedDirectory}/{HelperRuntime.Files[0]}";
+        Edit(runtimeFile);
+
+        Assert.Null(OwnedCopy.IdenticalNotice(_root));
+        var result = EjectCommand.Undo([], _root, force: false);
+        Assert.Equal(0, result.ExitCode);
+        Assert.True(File.Exists(Owned("codegen/generators/RoutesGenerator.cs")));
+        Assert.True(File.Exists(Owned(runtimeFile)));
+
+        var named = EjectCommand.Undo(["routes"], _root, force: false);
+        Assert.Equal(2, named.ExitCode);
+        Assert.Contains(HelperRuntime.Files[0], string.Join("\n", named.Err));
+        Assert.True(File.Exists(Owned("codegen/generators/RoutesGenerator.cs")));
+    }
+
+    [Fact]
+    public void Undoing_the_last_runtime_user_removes_the_whole_identical_helper_runtime()
+    {
+        Eject("routes");
+
+        var result = EjectCommand.Undo([], _root, force: false);
+
+        Assert.Equal(0, result.ExitCode);
+        Assert.False(Directory.Exists(Owned(HelperRuntime.OwnedDirectory)));
+        Assert.Contains(result.Out, l => l.StartsWith("The helper runtime copy is gone"));
+    }
 }

server/csharp/MetaObjects.Cli/EjectCommand.cs

@@ -252,7 +252,8 @@ public static Outcome Run(IReadOnlyList<string> names, string root, bool force)
     /// <paramref name="names"/> every identical owned copy goes; with names only those, and a copy that
     /// DIFFERS is refused (exit 2, nothing removed) unless <paramref name="force"/>. Every name is
     /// validated before anything is deleted. Companion emitters go only when identical (or forced) and
-    /// no remaining owned generator is handed them; the helper runtime likewise. It never edits
+    /// no remaining owned generator is handed them. The helper runtime counts toward a copy being
+    /// identical, so it goes whole when no remaining owned generator's output imports it. It never edits
     /// codegen/Generators.cs or the project: it prints the edit that points each entry back at the
     /// shipped generator.
     /// </summary>
@@ -269,7 +270,7 @@ public static Outcome Undo(IReadOnlyList<string> names, string root, bool force)
                 return new Outcome(0, [owned.Count == 0
                     ? "no owned generator copies under codegen/generators/; nothing to undo."
                     : "no owned copy is identical to its shipped generator, so nothing was removed: " +
-                      string.Join("; ", owned.Select(e => $"{e.Name} {OwnedCopy.Status(root, e)}")) + "."], []);
+                      string.Join("; ", owned.Select(e => $"{e.Name} {OwnedCopy.UndoStatus(root, e)}")) + "."], []);
             }
         }
         else
@@ -285,11 +286,11 @@ public static Outcome Undo(IReadOnlyList<string> names, string root, bool force)
             if (notOwned.Count > 0)
                 return Outcome.Usage(
                     $"no owned copy of: {string.Join(", ", notOwned)} under codegen/generators/. Nothing was removed.");
-            var differs = targets.Where(e => OwnedCopy.Status(root, e) != "identical").ToList();
+            var differs = targets.Where(e => OwnedCopy.UndoStatus(root, e) != "identical").ToList();
             if (differs.Count > 0 && !force)
                 return Outcome.Usage(
                     "not removed (nothing was changed): " +
-                    string.Join("; ", differs.Select(e => $"{e.Name} {OwnedCopy.Status(root, e)}")) +
+                    string.Join("; ", differs.Select(e => $"{e.Name} {OwnedCopy.UndoStatus(root, e)}")) +
                     ". Undo drops only copies identical to the shipped generator; `dotnet meta gen --list` " +
                     "shows how each one differs. Pass --force to discard your edits.");
         }
@@ -335,12 +336,6 @@ public static Outcome Undo(IReadOnlyList<string> names, string root, bool force)
                 {
                     var path = Path.Combine(runtimeDir, file);
                     if (!File.Exists(path)) continue;
-                    if (!force && OwnedCopy.Compare(File.ReadAllText(path), HelperRuntime.OwnedReference(file)).Verdict
-                        != OwnedCopy.Verdict.Identical)
-                    {
-                        lines.Add($"  kept {HelperRuntime.OwnedDirectory}/{file} — it differs from the shipped one, so it is yours");
-                        continue;
-                    }
                     File.Delete(path);
                     lines.Add($"  removed {HelperRuntime.OwnedDirectory}/{file}");
                     runtimeRemoved = true;

server/csharp/MetaObjects.Cli/OwnedCopy.cs

@@ -128,10 +128,28 @@ public static Comparison Compare(string owned, string reference)
         return clauses.Count == 0 ? "identical" : string.Join("; ", clauses);
     }
 
-    /// <summary>Every ejectable entry whose owned copy, and the emitters eject handed over with it,
-    /// is identical to the shipped one (<see cref="Status"/> reads <c>identical</c>).</summary>
+    /// <summary>
+    /// <see cref="Status"/>, plus a <c>"codegen/runtime/: …"</c> clause when the generator's output
+    /// imports the helper runtime and the owned copy of it is not identical. Undo reads this: the
+    /// shipped generator imports the shipped runtime, so dropping such a copy would silently stop
+    /// the runtime edit reaching the generated code.
+    /// </summary>
+    public static string? UndoStatus(string root, MetaObjects.Codegen.GeneratorRegistryEntry entry)
+    {
+        var status = Status(root, entry);
+        if (status is null
+            || !MetaObjects.Codegen.HelperRuntime.UsedBy(MetaObjects.Codegen.EjectableGenerators.ReadSource(entry.Name)!)
+            || RuntimeStatus(root) is not { } runtime || runtime == "identical")
+            return status;
+        var clause = $"{MetaObjects.Codegen.HelperRuntime.OwnedDirectory}/: {runtime}";
+        return status == "identical" ? clause : $"{status}; {clause}";
+    }
+
+    /// <summary>Every ejectable entry whose owned copy, the emitters eject handed over with it and the
+    /// helper runtime its output imports, is identical to the shipped one (<see cref="UndoStatus"/>
+    /// reads <c>identical</c>).</summary>
     public static IReadOnlyList<MetaObjects.Codegen.GeneratorRegistryEntry> IdenticalCopies(string root) =>
-        MetaObjects.Codegen.EjectableGenerators.Entries().Where(e => Status(root, e) == "identical").ToList();
+        MetaObjects.Codegen.EjectableGenerators.Entries().Where(e => UndoStatus(root, e) == "identical").ToList();
 
     /// <summary>
     /// The one advisory line <c>dotnet meta gen</c> prints when owned copies identical to the shipped

server/java/maven-plugin/src/main/java/com/metaobjects/mojo/MetaDataEjectMojo.java

@@ -268,7 +268,9 @@ private void undo() throws MojoExecutionException, MojoFailureException {
         Path codegenRoot = project.getBasedir().toPath().resolve(CODEGEN_DIR);
         List<OwnedStock.Copy> all;
         try {
-            all = OwnedStock.find(codegenRoot, OwnedStock.classpath(getClass().getClassLoader()));
+            all = OwnedStock.find(codegenRoot,
+                    OwnedStock.runtimeRoots(project.getBasedir().toPath(), project.getModules()),
+                    OwnedStock.classpath(getClass().getClassLoader()));
         } catch (IOException ex) {
             throw new MojoExecutionException("Could not compare the owned copies under " + codegenRoot, ex);
         }
@@ -988,21 +990,8 @@ private static void fold(int[] totals, List<String> differing, String name, Ejec
     /** The owned runtime copy of {@code simple} in this module or one of its children, or {@code null}. */
     private Path findOwnedRuntime(String simple) throws IOException {
         if (project == null || project.getBasedir() == null) return null;
-        Path base = project.getBasedir().toPath();
-        List<Path> roots = new ArrayList<>();
-        roots.add(base.resolve("src/main/java"));
-        if (project.getModules() != null) {
-            for (String module : project.getModules()) roots.add(base.resolve(module).resolve("src/main/java"));
-        }
-        for (Path root : roots) {
-            if (!Files.isDirectory(root)) continue;
-            try (var walk = Files.walk(root)) {
-                for (Path p : (Iterable<Path>) walk.filter(f -> f.getFileName().toString().equals(simple + ".java"))::iterator) {
-                    if (EjectSupport.isOwnedRuntime(Files.readString(p, StandardCharsets.UTF_8))) return p;
-                }
-            }
-        }
-        return null;
+        return OwnedStock.findOwnedRuntime(
+                OwnedStock.runtimeRoots(project.getBasedir().toPath(), project.getModules()), simple);
     }
 
     // ------------------------------------------------------------------------------------

server/java/maven-plugin/src/main/java/com/metaobjects/mojo/MetaDataGeneratorMojo.java

@@ -136,8 +136,10 @@ protected void executeGenerators(MetaDataLoader loader, List<Generator> generato
     private void noteOwnedStock() {
         if (project == null || project.getBasedir() == null) return;
         try {
+            Path base = project.getBasedir().toPath();
             String line = OwnedStock.notice(OwnedStock.find(
-                    project.getBasedir().toPath().resolve(MetaDataEjectMojo.CODEGEN_DIR),
+                    base.resolve(MetaDataEjectMojo.CODEGEN_DIR),
+                    OwnedStock.runtimeRoots(base, project.getModules()),
                     OwnedStock.classpath(getClass().getClassLoader())));
             if (line != null) getLog().info("MetaData Mojo > " + line);
         } catch (IOException | RuntimeException ignored) {

server/java/maven-plugin/src/main/java/com/metaobjects/mojo/OwnedStock.java

@@ -18,11 +18,13 @@
  * this plugin ships: what {@code mvn metaobjects:eject -Dundo=true} removes, and what
  * {@code metaobjects:generate} mentions in one advisory line.
  *
- * <p>Maven-free, like {@link EjectSupport}: it takes a directory and a resource reader. "Identical"
+ * <p>Maven-free, like {@link EjectSupport}: it takes directories and a resource reader. "Identical"
  * is {@link EjectSupport#compare} over every file the eject wrote for the generator: the generator,
  * the classes copied with it and the page templates it reads (a file gone missing counts as
- * differing). The shared support and runtime copies are not part of that verdict: other owned
- * generators import them, so undo leaves them and names them.
+ * differing), and the shared support and helper runtime copies it reaches. Undo never deletes the
+ * shared copies (other owned generators import them) and names them instead; but a change to one
+ * keeps the generator out of "identical", because the shipped generator imports the shipped
+ * support and runtime, so the change would stop reaching the generated code.
  */
 final class OwnedStock {
 
@@ -76,8 +78,34 @@ static final class Copy {
         String stockClassname() { return entry.classname; }
     }
 
-    /** Every owned copy under {@code codegenRoot}, in catalog order; empty when there is none. */
-    static List<Copy> find(Path codegenRoot, Reader reader) throws IOException {
+    /** The source roots an owned helper runtime may sit under: {@code base}'s and each module's
+     *  {@code src/main/java}. */
+    static List<Path> runtimeRoots(Path base, List<String> modules) {
+        List<Path> roots = new ArrayList<>();
+        roots.add(base.resolve("src/main/java"));
+        if (modules != null) {
+            for (String module : modules) roots.add(base.resolve(module).resolve("src/main/java"));
+        }
+        return roots;
+    }
+
+    /** The owned runtime copy of {@code simple} under {@code roots}, recognised by its ownership
+     *  marker, or {@code null}. */
+    static Path findOwnedRuntime(List<Path> roots, String simple) throws IOException {
+        for (Path root : roots) {
+            if (!Files.isDirectory(root)) continue;
+            try (var walk = Files.walk(root)) {
+                for (Path p : (Iterable<Path>) walk.filter(f -> f.getFileName().toString().equals(simple + ".java"))::iterator) {
+                    if (EjectSupport.isOwnedRuntime(Files.readString(p, StandardCharsets.UTF_8))) return p;
+                }
+            }
+        }
+        return null;
+    }
+
+    /** Every owned copy under {@code codegenRoot}, in catalog order; empty when there is none. The
+     *  helper runtime its output imports is looked for under {@code runtimeRoots}. */
+    static List<Copy> find(Path codegenRoot, List<Path> runtimeRoots, Reader reader) throws IOException {
         List<Copy> out = new ArrayList<>();
         if (codegenRoot == null || !Files.isDirectory(codegenRoot)) return out;
         for (EjectSupport.Entry e : EjectSupport.allEntries()) {
@@ -117,6 +145,22 @@ static List<Copy> find(Path codegenRoot, Reader reader) throws IOException {
                             owned, reader.read(GeneratorRegistry.EJECT_TEMPLATE_RESOURCE_ROOT
                                     + ref + EjectSupport.TEMPLATE_EXTENSION)));
                 }
+                Set<String> support = new LinkedHashSet<>();
+                for (String source : e.sources()) support.addAll(EjectSupport.supportFor(reader.read(e.resourceOf(source))));
+                for (String simple : support) {
+                    Path owned = MetaDataEjectMojo.findOwned(codegenRoot, "java", simple + ".java");
+                    if (owned == null) continue;
+                    fold(totals, differing, simple + ".java", EjectSupport.compare(
+                            Files.readString(owned, StandardCharsets.UTF_8),
+                            reader.read(GeneratorRegistry.EJECT_SUPPORT_RESOURCE_ROOT + simple + ".java")));
+                }
+                for (String simple : e.runtime) {
+                    Path owned = findOwnedRuntime(runtimeRoots, simple);
+                    if (owned == null) continue;
+                    fold(totals, differing, simple + ".java", EjectSupport.compare(
+                            Files.readString(owned, StandardCharsets.UTF_8),
+                            reader.read(GeneratorRegistry.EJECT_RUNTIME_RESOURCE_ROOT + simple + ".java")));
+                }
             }
             out.add(new Copy(e, ownedPackage, files, differing, totals[0], totals[1],
                     shared(codegenRoot, e, reader)));

server/java/maven-plugin/src/test/java/com/metaobjects/mojo/EjectUndoTest.java

@@ -66,6 +66,18 @@ private String logged(Log log) {
         return c.getAllValues().stream().map(CharSequence::toString).collect(Collectors.joining("\n"));
     }
 
+    private List<OwnedStock.Copy> findOwned() throws IOException {
+        return OwnedStock.find(basedir.resolve("codegen"), OwnedStock.runtimeRoots(basedir, List.of()),
+                OwnedStock.classpath(getClass().getClassLoader()));
+    }
+
+    /** The helper runtime eject copied for the owned generators, under {@code src/main/java}. */
+    private List<Path> ownedRuntime() throws IOException {
+        try (var walk = Files.walk(basedir.resolve("src/main/java"))) {
+            return walk.filter(p -> p.toString().endsWith(".java")).sorted().collect(Collectors.toList());
+        }
+    }
+
     private Path ownedDto() {
         return basedir.resolve("codegen/src/main/java/com/acme/codegen/SpringDtoGenerator.java");
     }
@@ -138,19 +150,34 @@ public void anUnknownOrUnownedNameFailsTheWholeCall() throws Exception {
 
     @Test
     public void theGenerateNoticeNamesIdenticalCopiesAndStaysSilentOtherwise() throws Exception {
-        assertNull(OwnedStock.notice(OwnedStock.find(basedir.resolve("codegen"),
-                OwnedStock.classpath(getClass().getClassLoader()))));
+        assertNull(OwnedStock.notice(findOwned()));
         eject("dto");
-        String line = OwnedStock.notice(OwnedStock.find(basedir.resolve("codegen"),
-                OwnedStock.classpath(getClass().getClassLoader())));
+        String line = OwnedStock.notice(findOwned());
         assertNotNull(line);
         assertTrue(line, line.contains("dto"));
         assertTrue(line, line.contains("mvn metaobjects:eject -Dundo=true"));
         Files.writeString(ownedDto(), Files.readString(ownedDto()) + "\n// mine\n");
-        assertNull(OwnedStock.notice(OwnedStock.find(basedir.resolve("codegen"),
-                OwnedStock.classpath(getClass().getClassLoader()))));
-        assertEquals(1, OwnedStock.find(basedir.resolve("codegen"),
-                OwnedStock.classpath(getClass().getClassLoader())).stream()
+        assertNull(OwnedStock.notice(findOwned()));
+        assertEquals(1, findOwned().stream()
                 .filter(c -> c.entry.stableName.equals("dto")).count());
     }
+
+    @Test
+    public void aChangedHelperRuntimeKeepsTheGeneratorOutOfTheNoticeAndOutOfNoNameUndo() throws Exception {
+        eject("dto");
+        List<Path> runtime = ownedRuntime();
+        assertFalse("ejecting dto copies the helper runtime its output imports", runtime.isEmpty());
+        assertNotNull(OwnedStock.notice(findOwned()));
+        Files.writeString(runtime.get(0), Files.readString(runtime.get(0)) + "\n// mine\n");
+        assertNull(OwnedStock.notice(findOwned()));
+        undo(null, false);
+        assertTrue("the generator whose runtime changed is not undone", Files.exists(ownedDto()));
+        try {
+            undo("dto", false);
+            fail("expected MojoFailureException");
+        } catch (MojoFailureException expected) {
+            assertTrue(expected.getMessage(), expected.getMessage().contains(runtime.get(0).getFileName().toString()));
+        }
+        assertTrue(Files.exists(ownedDto()));
+    }
 }