Skip to content

feat: export an opened artifact as a clean, docket-free Markdown file - #439

Merged
danielhanold merged 12 commits into
mainfrom
feat/export-an-opened-artifact-as-a-clean-docket-free-markdown-fi
Oct 20, 2026
Merged

danielhanold merged 12 commits into
mainfrom
feat/export-an-opened-artifact-as-a-clean-docket-free-markdown-fi

Conversation

@danielhanold

@danielhanold danielhanold commented Oct 20, 2026 •

Copy link
Copy Markdown
Owner

↩ Change 0561 — Export an opened artifact as a clean, docket-free Markdown file

Summary

Adds docket open <change|spec|plan|results> [<id>] --export. It writes a clean Markdown copy of the artifact that can be shared with people who do not use docket, then opens it (--print prints the path instead).

  • Where the copy goes: ~/Downloads on macOS or the home folder on Linux, or --output-path. The file is named <date>-<type>-<name>.md. Exporting over the source or into the metadata checkout is refused.
  • What is removed: frontmatter, managed blocks and their markers, spec change stamps, and every link (its text is kept). An issue keeps only its proposal sections, under an H1.
  • What is converted: explicit change references (change 0559, padded ids) become quoted titles. A bare #N, a PR number or an ADR reference stays. Code is never touched.
  • Self-check: an independent detector (internal/exportcheck, which shares no code with internal/export) reports leftovers and mentions of docket as warnings, filtered by --warnings all|leftovers|mentions. It never blocks.
  • Tests: a frozen real corpus, plus a standing test that switching off any one transform step turns the corpus test red.

Review

Whole-branch review ran at the deep tier (bumped for a diff over 1,500 lines). It returned 7 findings, all fixed in-branch.

# Severity Finding Disposition
1 important Older spec stamp shapes (colon, · runs, linked ids) were missed and shipped converted, and the self-check could not see them fixed — 30eea1e
2 important Self-check flagged author prose (any ↩, <a> placeholders, x[i][j]) as leftovers fixed — c1b86fa
3 minor Code spans crossing a line break were not protected fixed — e707401
4 minor Inserted titles clashed with the author's quotes (""title"", "(0507)" → "") fixed — e707401
5 minor Stray-marker leftovers put a source line number in the output-line field fixed — e707401 (source_line)
6 minor --output-path could overwrite the source artifact fixed — e707401 (output-path-protected)
7 minor The corpus test had no direct assertion for change-reference conversion fixed — e707401

The full suite is green at e707401.

…er ship as a converted title

Review finding: removeStamps and the self-check's isStamp listed stamp spellings,
so 83 of 240 real stamped specs kept a stamp (`Change: #N · slug …`,
`**Change:** N — title`, `Change N. Spec date …`, linked `**Change:** [#N](…)`),
which step 6 then shipped as `**Change:** "<title>"` unnoticed.

The transform now matches a stamp by shape on the link-stripped line: a line
opening `Change`, `Change:`, or `**Change:**` with the id (or a later
`· **Change:**` field). The head and its metadata go; an author sentence after it
stays. The detector recognizes the label and converted-title shapes without
needing a digit, still sharing no code with the transform. Two older real specs
(a plain-label `·` run and a linked stamp) join the frozen corpus.
The self-check reported a ↩ anywhere outside code, any <a>/<A> placeholder,
and any [x][y] pair as docket machinery the export did not remove, though the
transform keeps all three on purpose. The banner rule now matches only the
banner's '> ↩' line shape, an anchor needs an attribute assignment or a
closing </a> on the line, and a reference link is flagged only when its label
has a definition in the document.
…-check, and destination

- Finding 3: the transform (maskParagraph) and the self-check
  (maskParagraphs), each written separately, now find inline code spans
  across a whole paragraph. A span that crosses a line break stays code on
  both of its lines. PROVENANCE.md no longer lists this as a limitation.
- Finding 4: an inserted title respects the author's quotes. A fully
  convertible reference that is the whole quoted text takes those quotes
  ("change 0559" -> "<title>"). A quoted references-only parenthesis is
  replaced by its titles and never leaves "". Inside a longer quoted phrase,
  the title gets single quotes.
- Finding 5: a stray-marker leftover reports its source line as
  source_line. line is left only for output lines, and the JSON test and
  human warning are updated.
- Finding 6: --output-path is refused with output-path-protected when the
  resolved destination (cleaned, parent symlinks resolved) is the source
  artifact or lies inside the metadata checkout.
- Finding 7: corpusProblems directly asserts that no known word-form or
  padded change id is left outside code, using a regex of its own.
@danielhanold
danielhanold merged commit c58321f into main Oct 20, 2026
7 checks passed
@danielhanold
danielhanold deleted the feat/export-an-opened-artifact-as-a-clean-docket-free-markdown-fi branch October 20, 2026 15:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant