ebox/tests/ebox-docs-contract-tests.el

;;; 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-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-incremental.el" "ebox-surface.el" "ebox-dsl.el"
    "ebox-selector.el" "ebox-native-reflow.el"
    "tests/ebox-core-render-tests.el" "tests/ebox-state-contract-tests.el"
    "tests/ebox-layout-boundary-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" "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"
    "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