tier3: contracts + tests for 12 remaining modules (all 39 files now have Contracts)

org/programming-lisp.org

@@ -15,6 +15,22 @@ The skill has four layers:
 3. **Structural surgery** — extract, inject, wrap, slurp — surgical code transformations without regex
 4. **Formatting** — auto-indentation via Emacs batch mode
 
+** Contract
+
+1. (lisp-structural-check code): returns (values T nil) if parentheses
+   balanced, (values nil error-msg) if reader errors detected.
+2. (lisp-syntactic-check code): alias for lisp-structural-check.
+3. (lisp-semantic-check code): returns (values T nil) if no unsafe forms
+   (eval, load, run-program) found; (values nil reason) if blocked.
+4. (lisp-validate code &key strict): unified gate — returns
+   ~(:status :success)~ or ~(:status :error :reason ...)~.
+5. (lisp-eval code-string): sandboxed eval with captured output.
+   Returns ~(:status :success :result ...)~ or ~(:status :error ...)~.
+6. (lisp-extract code fn-name): extracts a single defun from code.
+7. (lisp-list-definitions code): returns list of defined symbol names.
+8. (lisp-inject code target new-form): injects a form into a function body.
+9. (lisp-slurp code target form): appends a form to a function body.
+
 * Implementation
 
 ** Package Context
@@ -233,43 +249,53 @@ Tests for the Lisp Validator structural, syntactic, and semantic gates.
 (in-suite utils-lisp-suite)
 
 (test structural-balanced
+  "Contract 1: balanced code returns T."
   (is (eq t (passepartout:lisp-structural-check "(+ 1 2)"))))
 
 (test structural-unbalanced-open
+  "Contract 1: missing close paren returns nil + error."
   (multiple-value-bind (ok reason) (passepartout:lisp-structural-check "(+ 1 2")
     (is (null ok))
     (is (search "Reader Error" reason))))
 
 (test structural-unbalanced-close
+  "Contract 1: extra close paren returns nil + error."
   (multiple-value-bind (ok reason) (passepartout:lisp-structural-check "+ 1 2)")
     (is (null ok))
     (is (search "Reader Error" reason))))
 
 (test syntactic-valid
+  "Contract 2: valid syntax passes syntactic check."
   (is (eq t (passepartout:lisp-syntactic-check "(+ 1 2)"))))
 
 (test semantic-safe
+  "Contract 3: safe code passes semantic check."
   (is (eq t (passepartout:lisp-semantic-check "(+ 1 2)"))))
 
 (test semantic-blocked-eval
+  "Contract 3: eval forms are blocked by semantic check."
   (multiple-value-bind (ok reason) (passepartout:lisp-semantic-check "(eval '(+ 1 2))")
     (is (null ok))
     (is (search "Unsafe" reason))))
 
 (test unified-success
+  "Contract 4: valid code returns :success via lisp-validate."
   (let ((result (passepartout:lisp-validate "(+ 1 2)" :strict t)))
     (is (eq (getf result :status) :success))))
 
 (test unified-failure
+  "Contract 4: invalid code returns :error via lisp-validate."
   (let ((result (passepartout:lisp-validate "(+ 1 2" :strict nil)))
     (is (eq (getf result :status) :error))))
 
 (test eval-basic
+  "Contract 5: lisp-eval returns :success with captured result."
   (let ((result (passepartout:lisp-eval "(+ 1 2)")))
     (is (eq (getf result :status) :success))
     (is (string= (getf result :result) "3"))))
 
 (test structural-extract
+  "Contract 6: lisp-extract finds and returns a named function."
   (let* ((code "(defun hello () (print \"hi\")) (defun bye () (print \"bye\"))")
          (extracted (passepartout:lisp-extract code "hello")))
     (is (not (null extracted)))
@@ -278,6 +304,7 @@ Tests for the Lisp Validator structural, syntactic, and semantic gates.
       (is (eq (second form) 'HELLO)))))
 
 (test list-definitions
+  "Contract 7: lisp-list-definitions returns all defined names."
   (let ((code "(defun foo () t) (defmacro bar () nil) (defparameter *baz* 10)"))
     (let ((names (passepartout:lisp-list-definitions code)))
       (is (member 'FOO names))
@@ -285,12 +312,14 @@ Tests for the Lisp Validator structural, syntactic, and semantic gates.
       (is (member '*BAZ* names)))))
 
 (test structural-inject
+  "Contract 8: lisp-inject adds a form to a function body."
   (let* ((code "(defun my-fun (x) (print x))")
          (injected (passepartout:lisp-inject code "my-fun" "(finish-output)")))
     (let ((form (read-from-string injected)))
       (is (equal (last form) '((FINISH-OUTPUT)))))))
 
 (test structural-slurp
+  "Contract 9: lisp-slurp appends a form to a function body."
   (let* ((code "(defun work () (step-1))")
          (slurped (passepartout:lisp-slurp code "work" "(step-2)")))
     (let ((form (read-from-string slurped)))