f87fcd121b
Some checks are pending
CI / test (push) Waiting to run
CI / native-build (macos-latest) (push) Waiting to run
CI / native-build (ubuntu-latest) (push) Waiting to run
CI / native-build (windows-latest) (push) Waiting to run
CI / native-msrv (macos-latest) (push) Waiting to run
CI / native-msrv (ubuntu-latest) (push) Waiting to run
CI / native-msrv (windows-latest) (push) Waiting to run
171 lines
8.2 KiB
EmacsLisp
171 lines
8.2 KiB
EmacsLisp
;;; ebox-docs-contract-tests.el --- Documentation contracts -*- lexical-binding: t; -*-
|
|
|
|
(require 'ert)
|
|
|
|
(defconst ebox-docs-test--root
|
|
(expand-file-name ".." (file-name-directory (or load-file-name buffer-file-name)))
|
|
"Repository root used by documentation contract tests.")
|
|
|
|
(defconst ebox-docs-test--current-docs
|
|
'("AGENTS.md" "README.md" "README.zh-CN.md" "DESIGN.md" "DESIGN.zh.md"
|
|
"docs/user/ebox-user-guide.en.md" "docs/user/ebox-user-guide.zh.md"
|
|
"docs/user/ebox-api-reference.en.md" "docs/user/ebox-api-reference.zh.md"
|
|
"docs/maintainer/ebox-current-implementation-reference.en.md"
|
|
"docs/maintainer/ebox-current-implementation-reference.zh.md"
|
|
"docs/maintainer/ebox-incremental-update-contract.en.md"
|
|
"docs/maintainer/ebox-incremental-update-contract.zh.md")
|
|
"Long-lived documentation files checked for stale path references.")
|
|
|
|
(defconst ebox-docs-test--public-user-docs
|
|
'("README.md" "README.zh-CN.md"
|
|
"docs/user/ebox-user-guide.en.md" "docs/user/ebox-user-guide.zh.md"
|
|
"docs/user/ebox-api-reference.en.md" "docs/user/ebox-api-reference.zh.md")
|
|
"Public documents that must describe only the canonical author grammar.")
|
|
|
|
(defconst ebox-docs-test--active-files
|
|
'("Makefile" ".github/workflows/ci.yml"
|
|
"ebox.el" "ebox-cache.el" "ebox-runtime-index.el"
|
|
"ebox-state-contract.el" "ebox-style.el"
|
|
"ebox-child-range.el" "ebox-tree.el"
|
|
"ebox-measure.el" "ebox-fragment.el" "ebox-render-context.el"
|
|
"ebox-layout.el" "ebox-flex.el" "ebox-grid.el"
|
|
"ebox-buffer-backend.el" "ebox-patch-plan.el" "ebox-incremental.el"
|
|
"ebox-surface.el" "ebox-dsl.el" "ebox-spi.el"
|
|
"ebox-selector.el" "ebox-native-reflow.el"
|
|
"tests/ebox-core-render-tests.el" "tests/ebox-runtime-index-tests.el"
|
|
"tests/ebox-state-contract-tests.el"
|
|
"tests/ebox-layout-boundary-tests.el"
|
|
"tests/ebox-patch-plan-tests.el"
|
|
"tests/ebox-style-schema-tests.el"
|
|
"tests/ebox-spi-tests.el"
|
|
"tests/ebox-child-range-tests.el" "tests/ebox-grid-tests.el"
|
|
"tests/ebox-commit-tests.el" "tests/ebox-surface-tests.el"
|
|
"tests/ebox-dsl-tests.el" "tests/ebox-flex-tests.el"
|
|
"tests/ebox-selector-tests.el" "tests/ebox-package-tests.el"
|
|
"tests/ebox-visual-check-tests.el" "tests/ebox-docs-contract-tests.el"
|
|
"tests/ebox-ci-contract-tests.el"
|
|
"native/Cargo.toml" "native/Cargo.lock" "native/build.rs"
|
|
"native/vendor/emacs-30/emacs-module.h" "native/src/lib.rs"
|
|
"native/src/layout.rs" "native/c/ebox_module.c"
|
|
"scripts/ebox-package-lint.el" "scripts/ebox-visual-check.el"
|
|
"scripts/ebox-performance-evaluator.el")
|
|
"Active Ebox files that the maintainer map must cover.")
|
|
|
|
(defconst ebox-docs-test--targets
|
|
'("check" "ci" "load" "compile" "core-tests" "runtime-index-tests"
|
|
"child-range-tests" "grid-tests"
|
|
"ebox-commit-tests" "surface-tests" "visual-check-tests" "package-tests"
|
|
"selector-tests" "dsl-tests" "flex-tests" "state-contract-tests"
|
|
"layout-boundary-tests" "layout-boundary-performance"
|
|
"patch-plan-tests" "patch-plan-performance"
|
|
"style-schema-tests" "style-schema-performance"
|
|
"spi-tests" "spi-performance" "c1b-contract-tests"
|
|
"docs-contract-tests" "ci-contract-tests" "performance-evaluator"
|
|
"visual-check"
|
|
"native-rust-tests" "native-build" "package-lint" "diff-check")
|
|
"Make targets that must be documented and executable.")
|
|
|
|
(defun ebox-docs-test--read (relative-path)
|
|
"Return RELATIVE-PATH contents from the repository root."
|
|
(with-temp-buffer
|
|
(insert-file-contents (expand-file-name relative-path ebox-docs-test--root))
|
|
(buffer-string)))
|
|
|
|
(ert-deftest ebox-docs-active-files-exist-and-are-listed ()
|
|
"The maintainer reference should describe every active package file."
|
|
(let ((reference (ebox-docs-test--read
|
|
"docs/maintainer/ebox-current-implementation-reference.en.md")))
|
|
(dolist (file ebox-docs-test--active-files)
|
|
(should (file-exists-p (expand-file-name file ebox-docs-test--root)))
|
|
(should (string-match-p (regexp-quote file) reference)))))
|
|
|
|
(ert-deftest ebox-docs-verification-targets-match-makefile ()
|
|
"Documented verification targets should exist in the Makefile."
|
|
(let ((makefile (ebox-docs-test--read "Makefile"))
|
|
(reference (ebox-docs-test--read
|
|
"docs/maintainer/ebox-current-implementation-reference.en.md")))
|
|
(dolist (target ebox-docs-test--targets)
|
|
(should (string-match-p (concat "^" (regexp-quote target) ":") makefile))
|
|
(should (string-match-p (regexp-quote (concat "make " target))
|
|
reference)))))
|
|
|
|
(ert-deftest ebox-docs-have-paired-language-files ()
|
|
"Every long-lived user and maintainer document should have both languages."
|
|
(dolist (pair '(("docs/user/ebox-user-guide.en.md"
|
|
"docs/user/ebox-user-guide.zh.md")
|
|
("docs/user/ebox-api-reference.en.md"
|
|
"docs/user/ebox-api-reference.zh.md")
|
|
("docs/maintainer/ebox-current-implementation-reference.en.md"
|
|
"docs/maintainer/ebox-current-implementation-reference.zh.md")
|
|
("docs/maintainer/ebox-incremental-update-contract.en.md"
|
|
"docs/maintainer/ebox-incremental-update-contract.zh.md")))
|
|
(dolist (file pair)
|
|
(should (file-exists-p (expand-file-name file ebox-docs-test--root))))))
|
|
|
|
(ert-deftest ebox-docs-public-api-reference-covers-facade ()
|
|
"The bilingual API references should name every facade entry point."
|
|
(require 'ebox)
|
|
(dolist (file '("docs/user/ebox-api-reference.en.md"
|
|
"docs/user/ebox-api-reference.zh.md"))
|
|
(let ((source (ebox-docs-test--read file)))
|
|
(dolist (entry ebox-public-api)
|
|
(should (string-match-p
|
|
(regexp-quote (format "`%s`" entry))
|
|
source))))))
|
|
|
|
(ert-deftest ebox-docs-do-not-present-legacy-source-as-active ()
|
|
"The standalone package documentation must not claim ETAF source ownership."
|
|
(dolist (file ebox-docs-test--current-docs)
|
|
(let ((source (ebox-docs-test--read file)))
|
|
(should-not (string-match-p "`etaf-[[:alnum:]-]+\\.el`" source))
|
|
(should-not (string-match-p "`etaf\\.el`" source)))))
|
|
|
|
(ert-deftest ebox-docs-do-not-present-removed-grid-item-api ()
|
|
"Public documentation must expose direct child Grid placement only."
|
|
(dolist (file '("docs/user/ebox-api-reference.en.md"
|
|
"docs/user/ebox-api-reference.zh.md"
|
|
"docs/user/ebox-user-guide.en.md"
|
|
"docs/user/ebox-user-guide.zh.md"))
|
|
(let ((source (ebox-docs-test--read file)))
|
|
(should-not (string-match-p "ebox-grid-item" source))
|
|
(should-not (string-match-p "`grid-item`" source)))))
|
|
|
|
(ert-deftest ebox-docs-public-author-surface-excludes-removed-forms ()
|
|
"Public docs must not revive removed constructors or field-based children."
|
|
(dolist (file ebox-docs-test--public-user-docs)
|
|
(let ((source (ebox-docs-test--read file)))
|
|
(dolist (removed '("ebox-create" "ebox-concat" "ebox-stack"
|
|
"ebox-spacer" "ebox-flex-item" "ebox-grid-item"
|
|
"raw-ebox" ":content"))
|
|
(should-not (string-match-p (regexp-quote removed) source)))
|
|
(dolist (removed-form '("(item " "(spacer " "(raw-ebox "))
|
|
(should-not (string-match-p (regexp-quote removed-form) source))))))
|
|
|
|
(ert-deftest ebox-docs-canonical-author-grammar-executes ()
|
|
"Every documented author entry must build the advertised typed node."
|
|
(require 'ebox)
|
|
(let ((text-forms '("short" (text "explicit"))))
|
|
(dolist (form text-forms)
|
|
(should
|
|
(ebox-text-node-p
|
|
(ebox-canonical-input--single-root
|
|
(ebox-build form) "Ebox documented Text form")))))
|
|
(dolist (entry '((box "normal")
|
|
(row (box "row child"))
|
|
(column (box "column child"))
|
|
(flex (box "flex child"))
|
|
(grid (box "grid child"))))
|
|
(let* ((node
|
|
(ebox-canonical-input--single-root
|
|
(ebox-build entry) "Ebox documented Box form"))
|
|
(layout (ebox-box-node-layout node)))
|
|
(should (ebox-box-node-p node))
|
|
(should (eq (ebox-layout-config-kind layout)
|
|
(pcase (car entry)
|
|
('box 'normal)
|
|
(kind kind)))))))
|
|
|
|
(provide 'ebox-docs-contract-tests)
|
|
|
|
;;; ebox-docs-contract-tests.el ends here
|