Check #5's three findings: guard order, absolute paths, and 0020's overdue amendment

An independent critique of the 0021 pair (17/20) executed the shapes the
tests had not:

- {:components [vector]} -- the rejected first-draft shape, and the
  likeliest mistake -- hit an eager mapcat before the map? guard and
  surfaced as a raw nth exception instead of the message written for it.
  The guard now runs first, and the shape is a test.
- An absolute :wasm or :dir crashed inside io/file (it throws on an
  absolute child) with no entry named. Refused at read-project with
  provenance; everything in cljwit.edn is root-relative by design, and a
  committed absolute path is a machine-specific assumption anyway.
- A hand-deleted exports-hash line was misread as :stale ("the component
  changed"); :stale must only ever mean the API moved, so a missing hash
  line is :modified. The orphan scan also always covers the default src
  and dedupes files reachable through nested :dirs, and its recorded
  limit -- deleting a custom :dir's last entry removes that dir from
  view -- is in the docstring and the note.
- 0020 A still said "the API hash makes it a string compare" while
  aa7c935 claimed the supersession was recorded there. Now it is.

Claude-Session: https://claude.ai/code/session_01XF5Hfq4Ca2N2XYEzWQQuHt

Author: chaploud

doc/design/0020-generated-namespaces.md

@@ -45,9 +45,10 @@ anywhere. The *loud* half is already covered — marshalling is rebuilt from
 the live component at instantiate, so a renamed export fails
 `:no-such-export` with a did-you-mean and a changed argument list fails
 `:wrong-arity`. The silent half is exactly the regenerate-and-diff check
-that `cljwit.edn` (S2) owes its components; the API hash makes it a string
-compare. Until S2 exists, staleness detection is the reviewer's, and this
-paragraph is the warning.
+that `cljwit.edn` (S2) owes its components. *(Superseded on that point by
+`0021` B: the hash alone misses hand edits and `:rename` changes, so the
+check became tiered — hash line for `:stale`, bytes for `:modified` — and
+the hash's job shrank to distinguishing the two.)*
 
 ### B. Every var takes the instance first
 

doc/design/0021-cljwit-edn.md

@@ -89,6 +89,14 @@ a public API; it should name the file's owner.
   someone deleted the entry and left the namespace loadable — is exactly
   the silent staleness this unit exists to kill, so `status` reports it.
   Nothing is deleted: removal is the human's, with the list in hand.
+  One recorded limit: the scan covers the `:dir`s of *current* entries
+  plus the default `src`, so deleting the last entry of a custom `:dir`
+  also removes that dir from view. Scanning the whole tree instead would
+  make `status` cost scale with the repo, not the config.
+- **Paths in the file are relative, enforced.** An absolute `:wasm` or
+  `:dir` is refused with its entry named — `io/file` throws on an
+  absolute child, so it would otherwise crash without provenance, and a
+  committed absolute path is a machine-specific assumption anyway.
 - **`check` is the CI verb**, and it enumerates on stdout and in the
   exception message — measured: `-X` shows a caller only `ex-message`;
   `ex-data` lands in a temp-file report CI discards.

src/cljwit/project.clj

@@ -36,6 +36,12 @@
         (throw (ex-info (str "unknown key(s) in " f ": " (pr-str (vec bad)))
                         {:cljwit/error :bad-project :cljwit/keys (vec bad)})))
       (let [comps (:components cfg)
+            ;; This guard must run before anything walks comps: a vector here
+            ;; — the rejected first-draft shape, and the likeliest mistake —
+            ;; would otherwise surface as a raw nth exception.
+            _     (when-not (map? comps)
+                    (throw (ex-info ":components must be a map of namespace symbol -> options"
+                                    {:cljwit/error :bad-project})))
             errs  (into []
                         (mapcat (fn [[nss opts]]
                                   (cond
@@ -48,11 +54,20 @@
                                      (when-let [bad (seq (remove ENTRY-KEYS (keys opts)))]
                                        [(str nss " — unknown key(s): " (pr-str (vec bad)))])
                                      (when-not (string? (:wasm opts))
-                                       [(str nss " — :wasm must be a path string")])))))
+                                       [(str nss " — :wasm must be a path string")])
+                                     ;; io/file throws on an absolute child, so
+                                     ;; an absolute path here would crash later
+                                     ;; without naming its entry. Everything in
+                                     ;; this file is root-relative by design
+                                     ;; (0021 A) — a committed absolute path is
+                                     ;; a machine-specific assumption anyway.
+                                     (for [k [:wasm :dir]
+                                           :let [v (get opts k)]
+                                           :when (and (string? v)
+                                                      (.isAbsolute (io/file v)))]
+                                       (str nss " — " k " must be relative to cljwit.edn: "
+                                            (pr-str v)))))))
                         comps)]
-        (when-not (map? comps)
-          (throw (ex-info ":components must be a map of namespace symbol -> options"
-                          {:cljwit/error :bad-project})))
         (when (seq errs)
           (throw (ex-info (str "cljwit.edn: " (str/join "; " errs))
                           {:cljwit/error :bad-project :cljwit/errors errs})))
@@ -145,10 +160,12 @@
   "Touches nothing. {:ok [...] :stale [...] :modified [...] :missing [...]
    :orphans [...]} — :stale means the component's API changed (the
    exports-hash line differs: regenerate); :modified means the API did not
-   (a hand edit, a changed option, or a newer generator — the file's
-   generator: line says which); :orphans are files under a configured :dir
-   that carry the generated header but no entry, which is the silent
-   staleness this file exists to kill (0021 B). Nothing is deleted."
+   (a hand edit, a changed option, a newer generator, or a direct
+   write-ns! over a sync!-managed file — the generator: and regenerate:
+   lines say which); :orphans are generated files no entry claims, found
+   under the :dirs current entries configure plus the default \"src\" —
+   so removing the *last* entry of a custom :dir also removes that dir
+   from view, a recorded limit (0021 B). Nothing is deleted."
   ([] (status nil))
   ([opts]
    (let [proj    (read-project (or opts {}))
@@ -160,19 +177,26 @@
                              (update acc :missing conj (str file))
                              (= src (slurp file))
                              (update acc :ok conj (str file))
-                             (not= (hash-line src) (hash-line (slurp file)))
+                             ;; No hash line at all is an edit, not a changed
+                             ;; component — :stale must only ever mean "the
+                             ;; API moved".
+                             (and (some? (hash-line (slurp file)))
+                                  (not= (hash-line src) (hash-line (slurp file))))
                              (update acc :stale conj (str file))
                              :else
                              (update acc :modified conj (str file))))
                          {:ok [] :stale [] :modified [] :missing [] :orphans []}
                          entries)
-         orphans (for [d     (distinct (map :dir entries))
-                       ^File f (file-seq (io/file (:root proj) (str d)))
-                       :when (and (.isFile f)
-                                  (str/ends-with? (.getName f) ".clj")
-                                  (not (claimed (str (.getCanonicalFile f))))
-                                  (generated? f))]
-                   (str (.getCanonicalFile f)))]
+        ;; distinct twice over: "src" is always scanned, so a custom :dir
+        ;; under it would visit the same file through both roots.
+         orphans (distinct
+                  (for [d     (distinct (cons "src" (map :dir entries)))
+                        ^File f (file-seq (io/file (:root proj) (str d)))
+                        :when (and (.isFile f)
+                                   (str/ends-with? (.getName f) ".clj")
+                                   (not (claimed (str (.getCanonicalFile f))))
+                                   (generated? f))]
+                    (str (.getCanonicalFile f))))]
      (update base :orphans into orphans))))
 
 (defn check

test/cljwit/project_test.clj

@@ -52,7 +52,17 @@
   (testing "a missing wasm is named before anything is written"
     (let [d (tmp-project! {:components {'acme.a {:wasm "nowhere.wasm"}}})
           ex (is (thrown? clojure.lang.ExceptionInfo (project/sync! (opts d))))]
-      (is (str/includes? (ex-message ex) "nowhere.wasm")))))
+      (is (str/includes? (ex-message ex) "nowhere.wasm"))))
+  (testing "a non-map :components gets the written message, not an nth trace"
+    ;; The vector is the rejected first-draft shape — the likeliest mistake.
+    (let [d (tmp-project! {:components [{:ns 'acme.a :wasm "a.wasm"}]})
+          ex (is (thrown? clojure.lang.ExceptionInfo (project/status (opts d))))]
+      (is (= :bad-project (:cljwit/error (ex-data ex))))))
+  (testing "an absolute path is refused with its entry named"
+    (let [d (tmp-project! {:components {'acme.a {:wasm "/abs/a.wasm"}}})
+          ex (is (thrown? clojure.lang.ExceptionInfo (project/status (opts d))))]
+      (is (str/includes? (ex-message ex) "acme.a"))
+      (is (str/includes? (ex-message ex) "relative to cljwit.edn")))))
 
 (defn- build-echo-into! [^File d]
   (let [core (File/createTempFile "cljwit-proj" ".core.wasm")
@@ -107,6 +117,12 @@
             (is (= [(str (.getCanonicalFile f))] (:stale (project/status o))))
             (spit f pristine)))
 
+        (testing "deleting the hash line altogether is :modified — an edit, not an API change"
+          (let [pristine (slurp f)]
+            (spit f (str/replace pristine #";; exports-hash: sha256:[0-9a-f]+\n" ""))
+            (is (= [(str (.getCanonicalFile f))] (:modified (project/status o))))
+            (spit f pristine)))
+
         (testing "a deleted file is :missing"
           (let [pristine (slurp f)]
             (.delete f)