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 parse(String yaml, Class type) { try { return YAML.readValue(yaml, type); } catch (RuntimeException e) { throw ProtocolException.validation("Invalid " + type.getSimpleName() + ": " + e.getMessage()); } } public static T read(Path path, Class type) { return parse(Filespace.read(path), type); } public static T readDocument(Path path, Class 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 readMarkdownDocument(Path path, Class 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); } }