From 1dc986f146c33e1d91acccc8cfc31fbe2bad4ca5 Mon Sep 17 00:00:00 2001 From: Mihaela Mihaljevic Date: Thu, 9 Jul 2026 23:38:23 +0200 Subject: [PATCH] docs(readme): retire the stale Mermaid roadmap and its dead CI gate The roadmap diagrams referenced issue numbers (#1, #8-#13, #43-#55) that no longer exist on Codeberg: the GitHub to Codeberg migration reset this repo's issue tracker, and those numbers were never re-created. scripts/check-roadmap.sh existed only to keep that roadmap in sync with GitHub epic-labeled issues via gh, which can't resolve a Codeberg/Forgejo repo anyway, so the gate had been a silent no-op since the move. Removed the roadmap section, the gate script, its two call sites, and its now-pointless rule doc, and pointed the remaining work at the real, live issues (#4, #5, #6, #7, tracked under epic #8). Also fixed two leftover Mihaela/PureYAML references in docs/RELEASE.md. --- README.md | 76 +++----------- docs/RELEASE.md | 5 +- docs/rules/mermaid.md | 51 ---------- scripts/check-all.sh | 1 - scripts/check-roadmap.sh | 211 --------------------------------------- scripts/check-style.sh | 4 - 6 files changed, 14 insertions(+), 334 deletions(-) delete mode 100644 docs/rules/mermaid.md delete mode 100755 scripts/check-roadmap.sh diff --git a/README.md b/README.md index b8b6fbe..a1c3527 100644 --- a/README.md +++ b/README.md @@ -20,69 +20,6 @@ C-backed parsers. The package is intentionally strict about portability: - root Swift package layout - macOS, Linux, Windows, and WASI build gates -## Roadmap - -Mermaid status legend: - -The roadmap uses the TileDown Mermaid palette: green for merged work, yellow for -review, purple for epic grouping, and gray for open work with no PR. - -```mermaid -flowchart TB - classDef done fill:#ddf9e4,stroke:#34c759,color:#111827 - classDef review fill:#fff7d6,stroke:#ffcc00,color:#111827 - classDef epic fill:#f2e5ff,stroke:#af52de,color:#111827 - classDef todo fill:#f2f4f7,stroke:#8e8e93,color:#111827 - %% Completed parser replacement epics: #1 #8 #9 #10 #11 #12 #13 - LDone["In main now"]:::done - LReview["PR in review"]:::review - LEpic["Epic grouping"]:::epic - LTodo["Open issue, no PR"]:::todo - LDone --> LReview - LReview --> LEpic - LEpic --> LTodo -``` - -Parser Replacement Roadmap #8 is complete in main. - -Production Hardening and Validation Readiness #54 is active. PureYAML now has -checked-corpus Yams parse-success parity, structured diagnostics and validation, -JSON compatibility proof gates, internal token/event streaming, real-corpus -property tests, and repeatable performance comparison artifacts. Remaining work -is concentrated in downstream integration, true chunked input streaming, broader -malformed fixtures, and continued throughput optimization: - -```mermaid -flowchart TB - classDef done fill:#ddf9e4,stroke:#34c759,color:#111827 - classDef review fill:#fff7d6,stroke:#ffcc00,color:#111827 - classDef epic fill:#f2e5ff,stroke:#af52de,color:#111827 - classDef todo fill:#f2f4f7,stroke:#8e8e93,color:#111827 - E54["#54 Production hardening epic"]:::epic - I49["#49 Structured validation reports"]:::done - I50["#50 False-positive diagnostic triage"]:::done - I51["#51 Bad-YAML mutation suite"]:::todo - I55["#55 Corpus fuzz and property gates"]:::done - I44["#44 Humongous YAML corpus gate"]:::done - I45["#45 Yams execution and diagnostics comparison"]:::done - I47["#47 Yams-parseable OpenAPI gaps"]:::done - I52["#52 OpenAPIDoctor integration dry run"]:::todo - I53["#53 Yams differential regression gate"]:::done - I43["#43 True chunked input streaming"]:::todo - I48["#48 Parser throughput toward libyaml parity"]:::todo - E54 --> I49 - I49 --> I50 - I50 --> I51 - I51 --> I55 - I55 --> I44 - I44 --> I45 - I45 --> I47 - I47 --> I53 - I53 --> I52 - I52 --> I43 - I43 --> I48 -``` - ## Status The current release is 0.2.0. It includes block mappings, block sequences, @@ -111,6 +48,18 @@ Unsupported gaps are pinned by executable tests so they produce exact errors, exact validation issues, or exact fallback value trees instead of silent parser drift. +PureYAML now has checked-corpus Yams parse-success parity, structured +diagnostics and validation, JSON compatibility proof gates, internal +token/event streaming, real-corpus property tests, and repeatable performance +comparison artifacts. Remaining work is tracked under the +[production hardening and validation readiness](https://codeberg.org/NodetteHQ/PureYAML/issues/8) +epic: +[true chunked input streaming](https://codeberg.org/NodetteHQ/PureYAML/issues/4), +[throughput toward libyaml parity](https://codeberg.org/NodetteHQ/PureYAML/issues/5), +[a broader bad-YAML mutation suite](https://codeberg.org/NodetteHQ/PureYAML/issues/6), +and an +[OpenAPIDoctor integration dry run](https://codeberg.org/NodetteHQ/PureYAML/issues/7). + ## Attribution PureYAML is informed by Yams and its bundled `CYaml` / libyaml-derived parser, @@ -308,7 +257,6 @@ bash scripts/check-style.sh bash scripts/check-namespacing.sh bash scripts/check-forbidden-patterns.sh bash scripts/check-changelog-touched.sh -bash scripts/check-roadmap.sh swiftformat . --config .swiftformat --lint swiftlint --config .swiftlint.yml --strict swift build diff --git a/docs/RELEASE.md b/docs/RELEASE.md index e8c442d..c59ccd0 100644 --- a/docs/RELEASE.md +++ b/docs/RELEASE.md @@ -28,7 +28,6 @@ bash scripts/check-style.sh bash scripts/check-namespacing.sh bash scripts/check-forbidden-patterns.sh bash scripts/check-changelog-touched.sh -bash scripts/check-roadmap.sh swiftformat . --config .swiftformat --lint swiftlint --config .swiftlint.yml --strict swift build @@ -62,7 +61,7 @@ Only run these commands after the local gates pass and hosted CI passes. git status --short --branch git tag -a 0.2.0 -m "PureYAML 0.2.0" git push origin main 0.2.0 -tea releases create --login codeberg --repo Mihaela/PureYAML \ +tea releases create --login codeberg --repo NodetteHQ/PureYAML \ --tag 0.2.0 --title "PureYAML 0.2.0" \ --note "$(cat docs/releases/pureyaml-0-2-0.md)" ``` @@ -71,7 +70,7 @@ After publishing, verify the release exists: ```sh git ls-remote --tags origin 0.2.0 -tea releases list --login codeberg --repo Mihaela/PureYAML | head +tea releases list --login codeberg --repo NodetteHQ/PureYAML | head ``` ## Do Not Tag If diff --git a/docs/rules/mermaid.md b/docs/rules/mermaid.md deleted file mode 100644 index a4ecf7e..0000000 --- a/docs/rules/mermaid.md +++ /dev/null @@ -1,51 +0,0 @@ -# Mermaid Rules - -## Rule 1: Use the TileDown Mermaid palette - -Every Mermaid roadmap diagram in this repository must use TileDown's Mermaid -status classes and exact colors. - -```mermaid -flowchart TB - classDef done fill:#ddf9e4,stroke:#34c759,color:#111827 - classDef review fill:#fff7d6,stroke:#ffcc00,color:#111827 - classDef epic fill:#f2e5ff,stroke:#af52de,color:#111827 - classDef todo fill:#f2f4f7,stroke:#8e8e93,color:#111827 - Done["In main now"]:::done - Review["PR in review"]:::review - Epic["Epic grouping"]:::epic - Todo["Open issue, no PR"]:::todo - Done ~~~ Review - Review ~~~ Epic - Epic ~~~ Todo -``` - -Allowed classes: - -- `done`: merged or shipped work -- `review`: pull request in review -- `epic`: grouping issue or roadmap parent -- `todo`: open work with no PR - -Do not add ad-hoc Mermaid status colors. Add a new class only after TileDown's -Mermaid palette adds the same class. - -## Rule 2: Keep roadmap Mermaid mechanically checkable - -Roadmap Mermaid blocks must keep `classDef` lines before nodes and edges. Every -node must use one of the allowed classes, and every edge must reference nodes -already defined in that block. - -The README must start its Mermaid section with the shared legend. Run -`bash scripts/check-roadmap.sh` after changing roadmap diagrams. - -## Rule 3: Collapse completed epics - -Completed epics must not be expanded into their child issues in Mermaid -roadmaps. Once every child in an epic is `done`, remove that detailed Mermaid -block and show the completed epic as one `done` node in its parent or -super-epic roadmap. - -Do not keep all-green detailed roadmap diagrams. The issue checklist can retain -the historical child issue list, but Mermaid must stay focused on active or -upcoming work. diff --git a/scripts/check-all.sh b/scripts/check-all.sh index 409768f..34f16bb 100755 --- a/scripts/check-all.sh +++ b/scripts/check-all.sh @@ -31,7 +31,6 @@ run_gate "namespacing" bash scripts/check-namespacing.sh run_gate "validation coverage" bash scripts/check-validation-coverage.sh run_gate "forbidden patterns" bash scripts/check-forbidden-patterns.sh run_gate "changelog" bash scripts/check-changelog-touched.sh -run_gate "roadmap" bash scripts/check-roadmap.sh run_gate "swiftformat" swiftformat . --config .swiftformat --lint run_gate "swiftlint" swiftlint --config .swiftlint.yml --strict run_gate "swift build" swift build diff --git a/scripts/check-roadmap.sh b/scripts/check-roadmap.sh deleted file mode 100755 index 900f271..0000000 --- a/scripts/check-roadmap.sh +++ /dev/null @@ -1,211 +0,0 @@ -#!/usr/bin/env bash -# Mermaid roadmap gate. Keeps README roadmap diagrams vertical, legend-first, -# TileDown-palette colored, and covered by live epic issues. -# See docs/rules/mermaid.md. - -set -u - -README="README.md" -FAIL=0 - -fail() { - echo "roadmap: $1" >&2 - FAIL=1 -} - -expected_classes() { - cat <<'EOF' - classDef done fill:#ddf9e4,stroke:#34c759,color:#111827 - classDef review fill:#fff7d6,stroke:#ffcc00,color:#111827 - classDef epic fill:#f2e5ff,stroke:#af52de,color:#111827 - classDef todo fill:#f2f4f7,stroke:#8e8e93,color:#111827 -EOF -} - -known_class() { - case "$1" in - done|review|epic|todo) return 0 ;; - *) return 1 ;; - esac -} - -extract_blocks() { - awk -v dir="$1" ' - /^```mermaid$/ { - inside = 1 - count += 1 - file = sprintf("%s/block-%03d.mmd", dir, count) - next - } - /^```$/ { - if (inside == 1) { - inside = 0 - file = "" - } - next - } - inside == 1 { - print > file - } - END { - count_file = dir "/count" - print count + 0 > count_file - } - ' "$README" -} - -node_defined() { - grep -Fxq "$1" "$2" -} - -validate_block() { - block="$1" - index="$2" - defined_nodes="$3" - expected="$4" - defs="$5" - - grep '^ classDef ' "$block" > "$defs" || true - if ! diff -u "$expected" "$defs" >/dev/null; then - fail "mermaid block $index must use the TileDown Mermaid color classDefs" - fi - - : > "$defined_nodes" - saw_non_class_def=0 - - while IFS= read -r line || [ -n "$line" ]; do - trimmed=$(printf '%s' "$line" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//') - case "$trimmed" in - ""|"flowchart "*|"%%"*) continue ;; - esac - - case "$trimmed" in - classDef\ *) - if [ "$saw_non_class_def" -ne 0 ]; then - fail "mermaid block $index has classDef after nodes or edges" - fi - continue - ;; - esac - - saw_non_class_def=1 - - if [[ "$line" =~ ^[[:space:]]*([A-Za-z][A-Za-z0-9_]*)[[:space:]]*(\[.*\]|\(.*\)|\{.*\})[[:space:]]*:::[[:space:]]*([A-Za-z][A-Za-z0-9_]*)[[:space:]]*$ ]]; then - node="${BASH_REMATCH[1]}" - node_class="${BASH_REMATCH[3]}" - if ! known_class "$node_class"; then - fail "mermaid block $index uses unknown class $node_class" - fi - echo "$node" >> "$defined_nodes" - continue - fi - - if [[ "$line" =~ (--\>|~~~) ]]; then - if [[ "$line" =~ ^[[:space:]]*([A-Za-z][A-Za-z0-9_]*)[[:space:]]*(--\>|~~~)[[:space:]]*([A-Za-z][A-Za-z0-9_]*)[[:space:]]*$ ]]; then - left="${BASH_REMATCH[1]}" - right="${BASH_REMATCH[3]}" - if ! node_defined "$left" "$defined_nodes" || ! node_defined "$right" "$defined_nodes"; then - fail "mermaid block $index has edge with undefined node: $left to $right" - fi - else - fail "mermaid block $index has unsupported edge syntax: $trimmed" - fi - continue - fi - - if [[ "$line" =~ ^[[:space:]]*[A-Za-z][A-Za-z0-9_]*[[:space:]]*(\[.*\]|\(.*\)|\{.*\})[[:space:]]*$ ]]; then - fail "mermaid block $index has unclassed node: $trimmed" - fi - done < "$block" - - if [ "$index" -gt 1 ] && - grep -Fq ':::done' "$block" && - ! grep -Eq ':::(todo|review|epic)' "$block"; then - fail "mermaid block $index expands completed work; collapse completed epics to one done node" - fi -} - -repo_name() { - if [ -n "${GITHUB_REPOSITORY:-}" ]; then - printf '%s\n' "$GITHUB_REPOSITORY" - return 0 - fi - command -v gh >/dev/null 2>&1 || return 1 - gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null -} - -check_epic_coverage() { - repo=$(repo_name || true) - if [ -z "$repo" ] || ! command -v gh >/dev/null 2>&1; then - if [ -n "${GITHUB_ACTIONS:-}" ]; then - fail "gh is required in CI to verify epic coverage" - else - echo "roadmap: skipping GitHub epic coverage because gh is unavailable" >&2 - fi - return - fi - - numbers=$(gh issue list \ - --repo "$repo" \ - --label epic \ - --state all \ - --limit 1000 \ - --json number \ - --jq '.[].number' 2>/dev/null) - if [ $? -ne 0 ]; then - if [ -n "${GITHUB_ACTIONS:-}" ]; then - fail "failed to query epic issues" - else - echo "roadmap: skipping GitHub epic coverage because gh issue list failed" >&2 - fi - return - fi - - combined="$1" - for number in $numbers; do - if ! grep -Fq "#$number" "$combined"; then - fail "epic issue #$number is missing from README Mermaid diagrams" - fi - done -} - -tmp=$(mktemp -d "${TMPDIR:-/tmp}/pureyaml-roadmap.XXXXXX") || exit 1 -trap 'rm -rf "$tmp"' EXIT - -extract_blocks "$tmp" -count=$(cat "$tmp/count") -if [ "$count" -eq 0 ]; then - fail "README has no Mermaid blocks" - exit "$FAIL" -fi - -first="$tmp/block-001.mmd" -if ! grep -Fq 'LDone["In main now"]' "$first" || ! grep -Fq 'LTodo["Open issue, no PR"]' "$first"; then - fail "first Mermaid block must be the shared legend" -fi - -expected="$tmp/expected-classes.txt" -expected_classes > "$expected" - -combined="$tmp/all-blocks.mmd" -: > "$combined" -index=1 -while [ "$index" -le "$count" ]; do - block=$(printf '%s/block-%03d.mmd' "$tmp" "$index") - cat "$block" >> "$combined" - validate_block \ - "$block" \ - "$index" \ - "$tmp/defined-$index.txt" \ - "$expected" \ - "$tmp/defs-$index.txt" - index=$((index + 1)) -done - -check_epic_coverage "$combined" - -if [ "$FAIL" -eq 0 ]; then - echo "roadmap: OK" -fi - -exit "$FAIL" diff --git a/scripts/check-style.sh b/scripts/check-style.sh index 194c237..d8efd7f 100755 --- a/scripts/check-style.sh +++ b/scripts/check-style.sh @@ -68,8 +68,4 @@ if [ "$FAIL" -ne 0 ]; then echo "style: gate failed. Rules: docs/rules/git-discipline.md" >&2 fi -if ! bash scripts/check-roadmap.sh; then - FAIL=1 -fi - exit "$FAIL"