Repository navigation
ToppleCat 0.2.1
ToppleCat 0.2.1 lets Java/JUnit teams review the complete business Spec beside its exact executable acceptance contract—without switching between Markdown, Java tests, and case-data files.
Highlights
Review the complete selected Spec
Spec Review now renders every selected Markdown document in full and inserts the checked Java/JUnit acceptance projection at each authored marker:
<!-- topplecat:acceptance -->The report preserves authored Markdown, multiple Given/When/Then/And/But narratives, public and reviewer-owned case rows, AC navigation, nested data, and source snapshots.
Select one or more Specs explicitly
Check, Review, and scoped Verify use the same repository-relative .md paths:
./gradlew toppleCatCheck \
--spec docs/specs/checkout.md \
--spec docs/specs/payment.md
./gradlew toppleCatReview \
--spec docs/specs/checkout.md \
--spec docs/specs/payment.md
./gradlew toppleCatVerify \
--spec docs/specs/checkout.md \
--spec docs/specs/payment.mdReview always requires at least one --spec. Without a Spec selection, Check, Seal, and Verify continue to operate on the complete executable contract.
Remove the separate Spec registry
The former topplecat-specs.json locator, stable Spec keys, AC inventory mirror, and Python maintenance helper are removed.
ToppleCat now reads the explicitly selected Markdown documents directly. .feature files are not read, registered, translated, or executed.
Safer checked input
Selected paths reject absolute paths, repository traversal, symbolic-link escapes, missing documents, invalid marker structures, and duplicate AC declarations.
Check snapshots the selected Markdown, Java source, and report assets. Review refuses content changed after Check and clears stale selected-Spec output after a failed selection.
More readable reports
Spec Review now supports:
- English and Traditional Chinese;
- keyboard and screen-reader navigation;
- narrow screens and large reports;
- safe rendering of raw HTML;
- stable links from ordinary AC references;
- accessible nested JSON and YAML case data.
Upgrade notes
If you used the earlier selected-Spec prototype:
- Remove
topplecat-specs.jsonand its maintenance scripts. - Pass the same repository-relative
--specpaths to Check, Review, and scoped Verify. - Add an exact
<!-- topplecat:acceptance -->marker where each AC projection should appear.
Users upgrading from 0.2.0 should note that toppleCatReview now requires an explicit Spec selection.
Installation
ToppleCat 0.2.1 is available from Maven Central.
plugins {
java
id("io.github.samzhu.topplecat") version "0.2.1"
}
dependencies {
testImplementation(
"io.github.samzhu.topplecat:topplecat-junit:0.2.1"
)
}ToppleCat runs on JDK 21 or 25. Consumer source may target Java 17, 21, or 25 when Gradle runs on a supported JDK.
Full changelog
Compare ToppleCat 0.2.0 to 0.2.1
繁體中文
ToppleCat 0.2.1 讓 Java/JUnit 團隊能在同一份 Spec Review 中閱讀完整業務規格與確切的可執行驗收契約,不必再來回切換 Markdown、Java 測試與案例資料。
完整呈現選定的規格
Spec Review 現在會完整呈現每一份選定的 Markdown 文件,並在作者放置的標記處插入已經 Check 的 Java/JUnit 驗收內容:
<!-- topplecat:acceptance -->報告會保留原始 Markdown、多組 Given/When/Then/And/But 敘事、公開及審閱者案例、AC 導覽、巢狀資料與原始碼快照。
明確選擇一份或多份規格
Check、Review 與指定範圍的 Verify 使用相同的專案相對 .md 路徑:
./gradlew toppleCatCheck \
--spec docs/specs/checkout.md \
--spec docs/specs/payment.md
./gradlew toppleCatReview \
--spec docs/specs/checkout.md \
--spec docs/specs/payment.md
./gradlew toppleCatVerify \
--spec docs/specs/checkout.md \
--spec docs/specs/payment.mdReview 一律需要至少一個 --spec。沒有選擇規格時,Check、Seal 與 Verify 仍會處理完整的可執行契約。
移除額外的規格索引
舊的 topplecat-specs.json、固定 Spec key、AC 清單副本與 Python 維護工具均已移除。
ToppleCat 現在直接讀取明確選定的 Markdown 文件,也不會讀取、登記、轉譯或執行 .feature 文件。
更安全的檢查內容
選定的路徑會拒絕絕對路徑、跳出專案目錄、symbolic link 越界、文件不存在、marker 結構錯誤,以及重複的 AC 宣告。
Check 會保存當下的 Markdown、Java source 與報告資源。若內容在 Check 後遭到修改,Review 會拒絕產生報告;選取失敗時也會清除舊結果。
更容易閱讀的報告
Spec Review 現在支援:
- 英文與繁體中文;
- 鍵盤及螢幕閱讀器操作;
- 窄螢幕與大型報告;
- 安全呈現 raw HTML;
- 一般 AC 引用的穩定導覽;
- 容易展開閱讀的巢狀 JSON、YAML 案例資料。
升級注意事項
如果曾使用先前的 selected-Spec 原型:
- 移除
topplecat-specs.json與相關維護工具。 - 將同一組專案相對
--spec路徑傳給 Check、Review 與指定範圍的 Verify。 - 在每個 AC 要插入驗收內容的位置加入精確的
<!-- topplecat:acceptance -->marker。
從 0.2.0 升級的使用者請注意:toppleCatReview 現在必須明確選擇 Spec。
安裝
ToppleCat 0.2.1 已發布至 Maven Central。
plugins {
java
id("io.github.samzhu.topplecat") version "0.2.1"
}
dependencies {
testImplementation(
"io.github.samzhu.topplecat:topplecat-junit:0.2.1"
)
}ToppleCat 的執行環境需要 JDK 21 或 25。只要 Gradle 使用支援的 JDK,使用端程式碼可以 target Java 17、21 或 25。