Add versioned Markdown discussion documents with legacy YAML reading and explicit migration that backs up originals and preserves semantic history. Render readable discussion and decision prose in Markdown context, document compatibility, and extend native smoke coverage for migration. Validated with 29 passing tests, macOS ARM64 native smoke, and context-preserving migration of the Zelda pilot Work.
87 lines
5.6 KiB
Java
87 lines
5.6 KiB
Java
package net.intrepid.aiengineering.filesystem;
|
|
|
|
import tools.jackson.databind.json.JsonMapper;
|
|
import tools.jackson.dataformat.yaml.YAMLMapper;
|
|
import tools.jackson.core.StreamReadFeature;
|
|
import tools.jackson.databind.DeserializationFeature;
|
|
import tools.jackson.databind.cfg.EnumFeature;
|
|
import tools.jackson.databind.node.ObjectNode;
|
|
import java.nio.file.Path;
|
|
import java.util.regex.Pattern;
|
|
|
|
/** Explicit protocol records, never Spring internal objects, are canonical. */
|
|
public final class Documents {
|
|
private static final YAMLMapper YAML = YAMLMapper.builder().enable(StreamReadFeature.STRICT_DUPLICATE_DETECTION)
|
|
.enable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES,
|
|
DeserializationFeature.FAIL_ON_TRAILING_TOKENS).enable(EnumFeature.FAIL_ON_NUMBERS_FOR_ENUMS).build();
|
|
private static final JsonMapper JSON = JsonMapper.builder().enable(StreamReadFeature.STRICT_DUPLICATE_DETECTION).build();
|
|
private static final Pattern FRONT_MATTER = Pattern.compile("\\A---\\r?\\n(.*?)\\r?\\n---(?:\\r?\\n|\\z)", Pattern.DOTALL);
|
|
private Documents() {}
|
|
public static String yaml(Object value) { return YAML.writeValueAsString(value); }
|
|
public static String json(Object value) { return JSON.writerWithDefaultPrettyPrinter().writeValueAsString(value) + "\n"; }
|
|
public static <T> T parse(String yaml, Class<T> type) {
|
|
try { return YAML.readValue(yaml, type); }
|
|
catch (RuntimeException e) { throw ProtocolException.validation("Invalid " + type.getSimpleName() + ": " + e.getMessage()); }
|
|
}
|
|
public static <T> T read(Path path, Class<T> type) { return parse(Filespace.read(path), type); }
|
|
public static <T> T readDocument(Path path, Class<T> type) {
|
|
return readMarkdownDocument(path, type, null);
|
|
}
|
|
/** Version 1 keeps prose in YAML; version 2 maps the Markdown body to one explicit text field. */
|
|
public static <T> T readMarkdownDocument(Path path, Class<T> type, String bodyField) {
|
|
var parts = parts(path);
|
|
int version = version(parts.metadata(), path);
|
|
parts.metadata().remove("documentVersion");
|
|
if (version == 2) {
|
|
if (bodyField == null) throw ProtocolException.validation("Markdown body is not supported for " + type.getSimpleName());
|
|
if (parts.metadata().has(bodyField)) throw ProtocolException.validation("Ambiguous " + bodyField + " in front matter and Markdown body: " + path);
|
|
String body = parts.body();
|
|
if (body.startsWith("\r\n")) body = body.substring(2);
|
|
else if (body.startsWith("\n")) body = body.substring(1);
|
|
else throw ProtocolException.validation("Expected a blank line after front matter: " + path);
|
|
parts.metadata().put(bodyField, body);
|
|
}
|
|
try { return YAML.treeToValue(parts.metadata(), type); }
|
|
catch (RuntimeException e) { throw ProtocolException.validation("Invalid " + type.getSimpleName() + " at " + path + ": " + e.getMessage()); }
|
|
}
|
|
public static int documentVersion(Path path) { return version(parts(path).metadata(), path); }
|
|
private static int version(ObjectNode metadata, Path path) {
|
|
var value = metadata.get("documentVersion");
|
|
if (value == null) return 1;
|
|
if (value.isIntegralNumber() && (value.bigIntegerValue().equals(java.math.BigInteger.ONE)
|
|
|| value.bigIntegerValue().equals(java.math.BigInteger.TWO))) return value.intValue();
|
|
throw ProtocolException.validation("Unsupported documentVersion at " + path + ": " + value);
|
|
}
|
|
private record Parts(ObjectNode metadata, String body) {}
|
|
private static Parts parts(Path path) {
|
|
String text = Filespace.read(path); var match = FRONT_MATTER.matcher(text);
|
|
if (!match.find()) throw ProtocolException.validation("Missing or unclosed YAML front matter: " + path);
|
|
try {
|
|
if (!(YAML.readTree(match.group(1)) instanceof ObjectNode metadata))
|
|
throw ProtocolException.validation("Front matter must be an object: " + path);
|
|
return new Parts(metadata, text.substring(match.end()));
|
|
} catch (ProtocolException e) { throw e; }
|
|
catch (RuntimeException e) { throw ProtocolException.validation("Invalid front matter at " + path + ": " + e.getMessage()); }
|
|
}
|
|
public static String markdownDocument(Object value, String bodyField) {
|
|
ObjectNode metadata = YAML.valueToTree(value);
|
|
var body = metadata.remove(bodyField);
|
|
if (body == null || !body.isString()) throw ProtocolException.invalid("Markdown body field must be text: " + bodyField);
|
|
metadata.put("documentVersion", 2);
|
|
return "---\n" + yaml(metadata).replaceFirst("^---\\n", "") + "---\n\n" + body.stringValue();
|
|
}
|
|
public static void writeMarkdownDocument(Path path, Object value, String bodyField, boolean replace) {
|
|
Filespace.write(path, markdownDocument(value, bodyField), replace);
|
|
}
|
|
public static String markdownMigration(Path path, Object value, String bodyField) {
|
|
var parts = parts(path);
|
|
if (version(parts.metadata(), path) != 1) throw ProtocolException.invalid("Document is already Markdown: " + path);
|
|
if (!parts.body().isBlank()) throw ProtocolException.validation("Legacy document has trailing notes; incorporate them into its text before migration: " + path);
|
|
return markdownDocument(value, bodyField);
|
|
}
|
|
public static void writeDocument(Path path, Object value, boolean replace) {
|
|
String yaml = yaml(value).replaceFirst("^---\\n", "");
|
|
Filespace.write(path, "---\n" + yaml + "---\n", replace);
|
|
}
|
|
}
|