Warn on YAML comment loss in frontmatter write commands#52
Open
DandyLyons wants to merge 1 commit into
Open
Conversation
YAML comments in frontmatter are silently discarded whenever any write operation is performed. This is a fundamental limitation of Yams/libYAML: comment tokens are dropped before they reach the parsed AST and cannot be recovered. - Add `FrontMatterParser.containsYAMLComments(_:)` — a naive check using swift-parsing's `Prefix(while:)` that detects standalone comment lines (first non-whitespace character is `#`) in the raw YAML string before Yams parses it - Add `MarkdownDocument.containsYAMLComments: Bool` property, set at `init(content:)` time; always `false` for programmatic init - Emit `warning: <path>: frontmatter contains YAML comments which will be lost` to stderr in all 9 frontmatter write commands (set, remove, rename, replace, sort-keys, touch, array append/prepend/remove) - Document the limitation in docs/architecture.md under Known Limitations - Add 16 tests covering detection true/false cases and the document property Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
# ...) in frontmatter are silently destroyed by any write operation — this is a fundamental limitation of Yams/libYAML, which discards comment tokens before they reach the ASTwarning:to stderr when comments are detected, so users know data loss is about to occurdocs/architecture.mdChanges
FrontMatterParserstatic func containsYAMLComments(_:)— scans raw YAML line-by-line usingPrefix(while:)from swift-parsingMarkdownDocumentpublic let containsYAMLComments: Bool, set atinit(content:)timewarning: <path>: frontmatter contains YAML comments which will be lostto stderr before mutatingdocs/architecture.mdYAMLCommentDetectionTests.swiftScope of detection
The check is intentionally naive: it detects standalone comment lines (where the first non-whitespace character is
#). It does not detect inline comments (key: value # comment). This avoids false positives on YAML string values that legitimately contain#(URLs, hex color codes, hashtags).Test plan
swift test --filter YAMLComment— all 16 tests passswift test— full suite passesmd-utils fm seton a file with# commentin frontmatter and confirm warning appears on stderr🤖 Generated with Claude Code