@abreen/tada 1.13.9 → 1.14.2

package/README.md

@@ -40,6 +40,7 @@ A static site generator. The successor to Presto.
   * `??? question ... ???` renders a Q & A section; answers hidden until click
   * `+++ ... +++ ... +++` renders a two-column layout
   * Special heading subtitles with `## Heading # A subtitle here`
+  * `{{{ _partial.md }}}` syntax for including partials
 - Automatically generated favicon
   * Text, color, font and font weight taken from config file
 
@@ -333,6 +334,51 @@ templates][lodash].
 - Custom variables from the `"vars"` property of the config are available
   under `vars` (e.g., `<%= vars.staffEmail %>`)
 
+### Markdown partials
+
+Use the `{{{ _partial.md }}}` syntax to include a partial (a fragment of
+Markdown in a separate file whose name must start with `_`) at that particular
+location in a Markdown file.
+
+This is useful for reducing duplication across multiple documents which use the
+exact same content, or for breaking up a large document into building blocks
+which are easier to edit.
+
+Partials are never built into their own pages, and they don't have front matter.
+
+The `{{{ ... }}}` syntax is not a simple string replacement; instead, the
+Markdown syntax tree of the partial is *added* to the syntax tree of the
+Markdown file that includes it. This is a powerful feature because it allows you
+to include content as a subtree.
+
+For example, this partial `_groceries.md`
+
+```
+* apples
+* oranges
+* pears
+```
+
+can be inserted as a sub-list of a larger list in a Markdown page
+
+```
+title: To do list
+
+* Grocery shopping
+  {{{ _groceries.md }}}
+* Car wash
+```
+
+which results in:
+
+```
+* Grocery shopping
+  * apples
+  * oranges
+  * pears
+* Car wash
+```
+
 
 [inter]: https://fonts.google.com/specimen/Inter
 [lodash]: https://lodash.info/doc/template

package/build/generate-content-assets.ts

@@ -14,6 +14,7 @@ import type {
   HtmlOutputAnalysis,
   TraceToolAvailability,
 } from './types';
+import type { TraceCache } from './watch/compiler-types';
 
 const log = makeLogger(import.meta.url);
 
@@ -37,16 +38,7 @@ function writeRecordOutputs(
 export class ContentRenderer {
   private siteVariables: SiteVariables;
   private traceToolAvailability: TraceToolAvailability | undefined;
-  private traceCache: Map<
-    string,
-    {
-      manifestUrl: string;
-      artifactId: string;
-      highlightedSource: string;
-      totalSteps: number;
-      mtime: number;
-    }
-  > = new Map();
+  private traceCache: TraceCache = new Map();
 
   constructor(siteVariables: SiteVariables) {
     this.siteVariables = siteVariables;

package/build/types.d.ts

@@ -86,9 +86,9 @@ export interface RenderPlainTextOptions {
     {
       manifestUrl: string;
       artifactId: string;
-      highlightedSource: string;
+      highlightedSources: { file: string; highlightedSource: string }[];
       totalSteps: number;
-      mtime: number;
+      sourceMtims: Record<string, number>;
     }
   >;
   traceToolAvailability?: TraceToolAvailability;
@@ -206,7 +206,13 @@ export interface TraceStep {
   file: string;
   stack: TraceStackFrame[];
   heap: Record<string, TraceHeapObject>;
-  stdout: string;
+  output?: TraceOutputEvent[];
+  transientHeapRoots?: string[];
+}
+
+export interface TraceOutputEvent {
+  stream: 'stdout' | 'stderr';
+  text: string;
 }
 
 export interface TraceStackFrame {
@@ -232,13 +238,18 @@ export type TraceValue =
 export type TraceHeapObject =
   | { type: string; elements: TraceValue[] }
   | { type: string; fields: Record<string, TraceValue> }
-  | { type: string; value: string };
+  | { type: string; value: string | number | boolean };
 
 /** Manifest written alongside trace chunks */
 export interface TraceManifest {
   totalSteps: number;
   chunkSize: number;
-  sourceFile: string;
+  primaryFile: string;
+  sources: TraceSource[];
+}
+
+export interface TraceSource {
+  file: string;
   source: string;
   lineToSteps: Record<number, number[]>;
 }
@@ -267,8 +278,9 @@ export interface TraceLayout {
 
 /** A single entry in a chunk file (new format with precomputed SVG). */
 export interface TraceChunkEntry {
+  file: string;
   line: number;
-  stdout: string;
+  output?: TraceOutputEvent[];
   svg: string;
 }
 

package/build/utils/html-comments.ts

@@ -0,0 +1,3 @@
+export function stripHtmlComments(str: string): string {
+  return str.replace(/<!---[\s\S]*?-->/g, '');
+}

package/build/utils/jdi-runner/TraceRunner.java

@@ -3,6 +3,7 @@ import com.sun.jdi.connect.*;
 import com.sun.jdi.event.*;
 import com.sun.jdi.request.*;
 import java.io.*;
+import java.nio.charset.StandardCharsets;
 import java.util.*;
 
 /**
@@ -17,7 +18,10 @@ public class TraceRunner {
 
     private static final Map<Long, String> objectIdMap = new HashMap<>();
     private static long nextObjId = 1;
-    private static Map<String, ObjectReference> previousReachable = new LinkedHashMap<>();
+    private static final List<OutputEvent> outputEvents = new ArrayList<>();
+    private static final Set<String> unnamedClassNames = new HashSet<>();
+
+    private record OutputEvent(String stream, String text) {}
 
     public static void main(String[] args) throws Exception {
         if (args.length < 2) {
@@ -27,6 +31,9 @@ public class TraceRunner {
 
         String className = args[0];
         String classPath = args[1];
+        for (int i = 2; i < args.length; i++) {
+            unnamedClassNames.add(args[i]);
+        }
 
         LaunchingConnector connector =
             Bootstrap.virtualMachineManager().defaultConnector();
@@ -39,27 +46,31 @@ public class TraceRunner {
         InputStream targetStdout = process.getInputStream();
         InputStream targetStderr = process.getErrorStream();
 
-        Thread stderrThread = new Thread(() -> {
-            try {
-                targetStderr.transferTo(System.err);
-            } catch (IOException ignored) {
-            }
-        });
+        Thread stdoutThread = new Thread(() -> readStream("stdout", targetStdout));
+        Thread stderrThread = new Thread(() -> readStream("stderr", targetStderr));
+        stdoutThread.setDaemon(true);
         stderrThread.setDaemon(true);
+        stdoutThread.start();
         stderrThread.start();
 
         try {
-            ClassPrepareRequest cpr =
-                vm.eventRequestManager().createClassPrepareRequest();
+            EventRequestManager requests = vm.eventRequestManager();
+            ClassPrepareRequest cpr = requests.createClassPrepareRequest();
             cpr.addClassFilter(className);
             cpr.setSuspendPolicy(EventRequest.SUSPEND_ALL);
             cpr.enable();
 
+            ExceptionRequest exceptionRequest =
+                requests.createExceptionRequest(null, false, true);
+            exceptionRequest.setSuspendPolicy(EventRequest.SUSPEND_ALL);
+            exceptionRequest.enable();
+
             vm.eventQueue().remove().resume(); // consume VMStartEvent
 
             boolean running = true;
             while (running) {
                 EventSet eventSet = vm.eventQueue().remove();
+                boolean resumed = false;
                 for (Event event : eventSet) {
                     if (event instanceof ClassPrepareEvent cpe) {
                         Method mainMethod = findMainMethod(cpe.referenceType());
@@ -75,7 +86,7 @@ public class TraceRunner {
                         cpr.disable();
 
                     } else if (event instanceof BreakpointEvent bpe) {
-                        emitState(bpe.thread(), targetStdout);
+                        emitState(bpe.thread(), drainOutputEventsJson());
 
                         var step = vm.eventRequestManager().createStepRequest(
                             bpe.thread(),
@@ -91,14 +102,31 @@ public class TraceRunner {
                         bpe.request().disable();
 
                     } else if (event instanceof StepEvent se) {
-                        emitState(se.thread(), targetStdout);
+                        emitState(se.thread(), drainOutputEventsJson());
+
+                    } else if (event instanceof ExceptionEvent ee
+                            && isUserClass(ee.location().declaringType())) {
+                        String initialOutput = drainOutputEventsJson();
+                        String statePrefix = buildStatePrefix(ee.thread());
+                        eventSet.resume();
+                        resumed = true;
+                        waitForVmTermination(vm.eventQueue());
+                        process.waitFor();
+                        stdoutThread.join(1000);
+                        stderrThread.join(1000);
+                        String finalOutput = mergeOutputJson(
+                            initialOutput,
+                            drainOutputEventsJson());
+                        emitState(statePrefix, finalOutput);
+                        running = false;
+                        break;
 
                     } else if (event instanceof VMDeathEvent
                             || event instanceof VMDisconnectEvent) {
                         running = false;
                     }
                 }
-                if (running) {
+                if (running && !resumed) {
                     eventSet.resume();
                 }
             }
@@ -108,6 +136,7 @@ public class TraceRunner {
                 vm.dispose();
             } catch (VMDisconnectedException ignored) {
             }
+            stdoutThread.join(1000);
             stderrThread.join(1000);
         }
     }
@@ -127,10 +156,18 @@ public class TraceRunner {
     }
 
     private static void emitState(ThreadReference thread,
-            InputStream targetStdout) throws Exception {
+            String outputJson) throws Exception {
         Thread.sleep(1);
-        String newStdout = drainStream(targetStdout);
+        emitState(buildStatePrefix(thread), outputJson);
+    }
+
+    private static void emitState(String statePrefix, String outputJson) {
+        System.out.println(statePrefix + outputJson + "}");
+        System.out.flush();
+    }
 
+    private static String buildStatePrefix(ThreadReference thread)
+            throws Exception {
         Location loc = thread.frame(0).location();
         int line = loc.lineNumber();
         String file = loc.sourceName();
@@ -138,30 +175,13 @@ public class TraceRunner {
         var reachable = new LinkedHashMap<String, ObjectReference>();
         String stackJson = serializeStack(thread, reachable);
 
-        // Carry forward objects from the previous step that are still alive.
-        // This keeps in-flight objects (e.g., on the operand stack during
-        // chained constructor calls) visible in the diagram.
-        for (var entry : previousReachable.entrySet()) {
-            if (!reachable.containsKey(entry.getKey())) {
-                try {
-                    if (!entry.getValue().isCollected()) {
-                        reachable.put(entry.getKey(), entry.getValue());
-                    }
-                } catch (Exception ignored) {
-                }
-            }
-        }
-
         String heapJson = serializeHeap(reachable);
-        previousReachable = new LinkedHashMap<>(reachable);
 
-        System.out.println(
-            "{\"line\":" + line
+        return "{\"line\":" + line
             + ",\"file\":\"" + jsonEscape(file)
             + "\",\"stack\":" + stackJson
             + ",\"heap\":" + heapJson
-            + ",\"stdout\":\"" + jsonEscape(newStdout) + "\"}");
-        System.out.flush();
+            + ",\"output\":";
     }
 
     private static String serializeStack(ThreadReference thread,
@@ -191,7 +211,7 @@ public class TraceRunner {
             if (!frame.location().method().isStatic()) {
                 try {
                     ObjectReference thisObj = frame.thisObject();
-                    if (thisObj != null) {
+                    if (thisObj != null && shouldEmitThis(declType)) {
                         sb.append("\"this\":")
                             .append(serializeValue(thisObj, reachable));
                         firstVar = false;
@@ -238,6 +258,25 @@ public class TraceRunner {
         return sb.toString();
     }
 
+    private static boolean shouldEmitThis(ReferenceType type) {
+        if (!unnamedClassNames.contains(type.name())) {
+            return true;
+        }
+        return hasInstanceFields(type);
+    }
+
+    private static boolean hasInstanceFields(ReferenceType type) {
+        try {
+            for (Field field : type.visibleFields()) {
+                if (!field.isStatic()) {
+                    return true;
+                }
+            }
+        } catch (Exception ignored) {
+        }
+        return false;
+    }
+
     private static String serializeValue(Value val,
             Map<String, ObjectReference> reachable) {
         if (val == null) {
@@ -336,6 +375,11 @@ public class TraceRunner {
         }
 
         ReferenceType type = obj.referenceType();
+        String boxedPrimitiveJson = serializeBoxedPrimitive(obj, type);
+        if (boxedPrimitiveJson != null) {
+            return boxedPrimitiveJson;
+        }
+
         if (!isUserClass(type)) {
             // JDK object: show type name and toString value
             try {
@@ -369,6 +413,74 @@ public class TraceRunner {
         return sb.toString();
     }
 
+    private static String serializeBoxedPrimitive(ObjectReference obj,
+            ReferenceType type) {
+        if (!isBoxedPrimitive(type)) {
+            return null;
+        }
+
+        Field valueField = type.fieldByName("value");
+        if (valueField == null) {
+            return null;
+        }
+
+        try {
+            Value value = obj.getValue(valueField);
+            return "{\"type\":\"" + jsonEscape(type.name())
+                + "\",\"value\":" + primitiveJsonLiteral(value) + "}";
+        } catch (Exception ignored) {
+            return null;
+        }
+    }
+
+    private static boolean isBoxedPrimitive(ReferenceType type) {
+        return switch (type.name()) {
+            case "java.lang.Boolean",
+                 "java.lang.Byte",
+                 "java.lang.Character",
+                 "java.lang.Double",
+                 "java.lang.Float",
+                 "java.lang.Integer",
+                 "java.lang.Long",
+                 "java.lang.Short" -> true;
+            default -> false;
+        };
+    }
+
+    private static String primitiveJsonLiteral(Value value) {
+        if (value instanceof BooleanValue v) {
+            return String.valueOf(v.value());
+        }
+        if (value instanceof ByteValue v) {
+            return String.valueOf(v.value());
+        }
+        if (value instanceof CharValue v) {
+            return "\"" + jsonEscape(String.valueOf(v.value())) + "\"";
+        }
+        if (value instanceof DoubleValue v) {
+            double n = v.value();
+            return Double.isFinite(n)
+                ? String.valueOf(n)
+                : "\"" + jsonEscape(String.valueOf(n)) + "\"";
+        }
+        if (value instanceof FloatValue v) {
+            float n = v.value();
+            return Float.isFinite(n)
+                ? String.valueOf(n)
+                : "\"" + jsonEscape(String.valueOf(n)) + "\"";
+        }
+        if (value instanceof IntegerValue v) {
+            return String.valueOf(v.value());
+        }
+        if (value instanceof LongValue v) {
+            return String.valueOf(v.value());
+        }
+        if (value instanceof ShortValue v) {
+            return String.valueOf(v.value());
+        }
+        return "\"" + jsonEscape(String.valueOf(value)) + "\"";
+    }
+
     private static String getObjectId(ObjectReference obj) {
         return objectIdMap.computeIfAbsent(
             obj.uniqueID(), k -> "obj_" + nextObjId++);
@@ -383,14 +495,91 @@ public class TraceRunner {
             && !name.startsWith("com.sun.");
     }
 
-    private static String drainStream(InputStream stream) throws IOException {
-        var sb = new StringBuilder();
-        while (stream.available() > 0) {
-            sb.append((char) stream.read());
+    private static void waitForVmTermination(EventQueue eventQueue)
+            throws InterruptedException {
+        boolean running = true;
+        while (running) {
+            try {
+                EventSet eventSet = eventQueue.remove();
+                for (Event event : eventSet) {
+                    if (event instanceof VMDeathEvent
+                            || event instanceof VMDisconnectEvent) {
+                        running = false;
+                        break;
+                    }
+                }
+                if (running) {
+                    eventSet.resume();
+                }
+            } catch (VMDisconnectedException ignored) {
+                running = false;
+            }
         }
+    }
+
+    private static void readStream(String streamName, InputStream stream) {
+        byte[] buffer = new byte[4096];
+        try {
+            int n;
+            while ((n = stream.read(buffer)) != -1) {
+                String text = new String(buffer, 0, n, StandardCharsets.UTF_8);
+                synchronized (outputEvents) {
+                    if (!outputEvents.isEmpty()
+                            && outputEvents.get(outputEvents.size() - 1)
+                                .stream().equals(streamName)) {
+                        OutputEvent previous =
+                            outputEvents.remove(outputEvents.size() - 1);
+                        outputEvents.add(new OutputEvent(
+                            streamName,
+                            previous.text() + text));
+                    } else {
+                        outputEvents.add(new OutputEvent(streamName, text));
+                    }
+                }
+            }
+        } catch (IOException ignored) {
+        }
+    }
+
+    private static String drainOutputEventsJson() {
+        List<OutputEvent> drained;
+        synchronized (outputEvents) {
+            drained = new ArrayList<>(outputEvents);
+            outputEvents.clear();
+        }
+        return outputEventsJson(drained);
+    }
+
+    private static String outputEventsJson(List<OutputEvent> events) {
+        var sb = new StringBuilder("[");
+        boolean first = true;
+        for (OutputEvent event : events) {
+            if (!first) {
+                sb.append(',');
+            }
+            first = false;
+            sb.append("{\"stream\":\"")
+                .append(event.stream())
+                .append("\",\"text\":\"")
+                .append(jsonEscape(event.text()))
+                .append("\"}");
+        }
+        sb.append(']');
         return sb.toString();
     }
 
+    private static String mergeOutputJson(String first, String second) {
+        if (first.equals("[]")) {
+            return second;
+        }
+        if (second.equals("[]")) {
+            return first;
+        }
+        return first.substring(0, first.length() - 1)
+            + ","
+            + second.substring(1);
+    }
+
     private static String jsonEscape(String s) {
         var sb = new StringBuilder();
         for (int i = 0; i < s.length(); i++) {