From fff44ec758e7f611da22880ef6837cc8eff73d91 Mon Sep 17 00:00:00 2001 From: Eva Marco Date: Wed, 18 Nov 2026 13:30:40 +0100 Subject: [PATCH 01/10] :bug: Fix shared files 500 on shapes with invalid child ids (#12528) * :bug: Fix shared files 500 on shapes with invalid child ids Old files can list in :shapes ids that are not uuids or that point to no shape. Migration 0033 walked them and hit the uuid assert in get-shape, which throws an AssertionError. The shared files list only caught Exception, so that Error broke the whole list with a 500. Make migration 0033 skip those ids, and catch Throwable when loading each shared file, so a broken file is skipped and logged. Closes #12343 AI-assisted-by: claude-opus-5-5 * :bug: Repair invalid child ids in migration 0033 v2 Skipping invalid child ids in migration 0033 was not enough: the ids stayed in :shapes, so the file still failed schema validation and could not load. Files that already applied the migration would also never run a changed version of it. The migration now repairs each container before the naming walk: string ids are parsed with uuid/coerce, nil and ids that point to no shape are dropped, the duplicate that 0032 adds when a child is listed as a string is removed, and a :shapes list becomes a vector. Only the shapes that change are re-assoc'ed, so a healthy ObjectsMap is not marked as modified and its page is not rewritten. It ships as 0033-normalize-main-instance-names-v2 at the same position in available-migrations, so files that recorded the old id run it again. That position also makes it parse strings before 0035-fix-dangling-children drops the ids it cannot find. The shared files listing restores the interrupt flag when the cause of a skipped file is an InterruptedException. Tests cover children outside the root walk, legacy components, the objects-map wrapper of the unrealized save path, a list turned into a vector, a shape without a :shapes key, a file that applied the old id, and the end-to-end load of a broken shared file. Relates to #12343 AI-assisted-by: claude-opus-5-5 AI-assisted-by: inkling-2-small-free --- ...-change-validation-migration-subtleties.md | 3 + backend/src/app/rpc/commands/files.clj | 7 +- backend/test/backend_tests/rpc_file_test.clj | 53 ++++-- common/src/app/common/files/migrations.cljc | 59 +++++-- .../files_migrations_0033_test.cljc | 24 +-- .../files_migrations_0035_test.cljc | 2 +- .../common_tests/files_migrations_test.cljc | 154 +++++++++++++++++- 7 files changed, 260 insertions(+), 42 deletions(-) diff --git a/.serena/memories/common/file-change-validation-migration-subtleties.md b/.serena/memories/common/file-change-validation-migration-subtleties.md index fab22a45fd..d43b6da088 100644 --- a/.serena/memories/common/file-change-validation-migration-subtleties.md +++ b/.serena/memories/common/file-change-validation-migration-subtleties.md @@ -35,3 +35,6 @@ - Closed schemas (`schema:stroke-attrs` and others) reject a key that was dropped from the declaration, so removing a declared attr needs a migration in the same change, for data already written with it. - Rebase collision on a migration number: upstream keeps the id. Renumber the branch migration to the next free one, keep it last in `available-migrations`, and rename everything that spells the number — its test file and namespace (`files_migrations_00NN_test.cljc`), the test names, and comments in production code or memories that name it. - Withdrawing a migration id: remove both the `defmethod` and the id from `available-migrations`; the replacement migration subsumes it and files that recorded the old id re-migrate through the replacement (persisted `:migrations` keep the old id via union — do not rewrite them, including playwright fixture JSONs). Idempotent/pure-cleanup migrations only; never withdraw one whose transform must not run again unless the replacement is safe for those files. Precedents: "0021-fix-shape-svg-attrs" -> "0035-fix-shape-svg-attrs-and-defs"; "legacy-36" -> "0036-clear-nil-keys-in-objects". +- A shipped migration whose behavior must change AND reach every file (most files already recorded its id, so `migrate` skips it): rename it to `-v2` and swap the old id for the new one in `available-migrations` at the SAME position. Precedents: `0002-normalize-bool-content-v2`, `0003-convert-path-content-v2`, `0008-fix-library-colors-v4`, and `0035-fix-shape-svg-attrs-and-defs` withdrawing `0021-fix-shape-svg-attrs`. Files keep the old id in `:migrations`, which is harmless because `migrate` diffs against the available set. Cost: one full pass over every file on its next read (the `get-file` ETag hashes `available-migrations`, so clients refetch). +- The alternative is patch the old id plus add a new migration id for the files that already applied it. Then the position in the list decides which repair runs first: a coerce-then-drop repair must come before a drop-only one, or the strings are gone before they can be parsed. +- `0033-normalize-main-instance-names-v2` repairs the container before its naming walk: child ids stored as strings are parsed with `uuid/coerce`, ids missing from `:objects` are dropped, duplicates are removed (the one `0032` adds when a child is stored as a string). The walk only re-assocs a shape when the normalization changed it (`identical?` on the normalized shape), so a healthy container keeps its `ObjectsMap` instance: no `modified` flag, no page rewrite. `0035-fix-dangling-children` prunes whatever is left. diff --git a/backend/src/app/rpc/commands/files.clj b/backend/src/app/rpc/commands/files.clj index de4d98444f..b49a0951f2 100644 --- a/backend/src/app/rpc/commands/files.clj +++ b/backend/src/app/rpc/commands/files.clj @@ -628,11 +628,14 @@ (fn [{:keys [id library-file-ids]}] ;; One shared file that fails to load (for example, a migration ;; error on old data) must not break the whole list; skip it - ;; and report it with its id. + ;; and report it with its id. Old data can also fail with a JVM + ;; Error (an assert or a deep recursion), so catch Throwable. (try (let [file (get-file-with-summary cfg id)] (assoc file :library-file-ids (db/decode-pgarray library-file-ids #{}))) - (catch Exception cause + (catch Throwable cause + (when (instance? InterruptedException cause) + (.interrupt (Thread/currentThread))) (l/error :hint "unable to load shared file" :file-id (str id) :team-id (str team-id) diff --git a/backend/test/backend_tests/rpc_file_test.clj b/backend/test/backend_tests/rpc_file_test.clj index 6019839a59..81b501585e 100644 --- a/backend/test/backend_tests/rpc_file_test.clj +++ b/backend/test/backend_tests/rpc_file_test.clj @@ -9,6 +9,7 @@ [app.binfile.common :as bfc] [app.common.features :as cfeat] [app.common.files.changes-builder :as pcb] + [app.common.files.migrations :as fmg] [app.common.files.tokens :as cfo] [app.common.pprint :as pp] [app.common.thumbnails :as thc] @@ -3355,17 +3356,49 @@ file2 (th/create-file* 2 {:profile-id (:id profile) :project-id (:default-project-id profile) :is-shared true}) - get-file (deref #'files/get-file-with-summary) - broken (fn [cfg id] - (if (= id (:id file1)) - (throw (ex-info "broken file" {:type :assertion})) - (get-file cfg id))) - out (with-redefs-fn {#'files/get-file-with-summary broken} - #(th/command! {::th/type :get-team-shared-files - ::rpc/profile-id (:id profile) - :team-id (:default-team-id profile)}))] + get-file (deref #'files/get-file-with-summary)] + + ;; Old file data can fail with a JVM Error (an assert or a deep + ;; recursion), not only with an exception. + (doseq [cause [(ex-info "broken file" {:type :assertion}) + (AssertionError. "point instance expected") + (StackOverflowError.)]] + (let [broken (fn [cfg id] + (if (= id (:id file1)) + (throw cause) + (get-file cfg id))) + out (with-redefs-fn {#'files/get-file-with-summary broken} + #(th/command! {::th/type :get-team-shared-files + ::rpc/profile-id (:id profile) + :team-id (:default-team-id profile)}))] + (t/is (th/success? out) (str "skips file failing with " (class cause))) + (t/is (= #{(:id file2)} (into #{} (map :id) (:result out)))))))) + +(t/deftest get-team-shared-files-repairs-invalid-children-ids + ;; A stored shared file that lists nil and a dangling id in :shapes and + ;; has not run 0033 yet: the migrations repair it on load, so it is + ;; listed instead of skipped. + (let [profile (th/create-profile* 1) + file (th/create-file* 1 {:profile-id (:id profile) + :project-id (:default-project-id profile) + :is-shared true}) + page-id (first (get-in file [:data :pages])) + root [:data :pages-index page-id :objects uuid/zero :shapes] + broken (-> (bfc/get-file th/*system* (:id file) :realize? true) + (update-in root conj nil (str (uuid/next))) + (assoc :migrations (disj fmg/available-migrations + "0033-normalize-main-instance-names-v2"))) + _ (db/tx-run! th/*system* + (fn [cfg] + (bfc/update-file! cfg broken ::bfc/reset-migrations? true))) + out (th/command! {::th/type :get-team-shared-files + ::rpc/profile-id (:id profile) + :team-id (:default-team-id profile)})] + (t/is (th/success? out)) - (t/is (= #{(:id file2)} (into #{} (map :id) (:result out)))))) + (t/is (= #{(:id file)} (into #{} (map :id) (:result out)))) + (t/is (= [] (get-in (bfc/get-file th/*system* (:id file) :realize? true) root)) + "the repaired data is stored"))) (t/deftest get-team-shared-files-does-not-expose-the-storage-pointer (let [profile (th/create-profile* 1 {:is-active true}) diff --git a/common/src/app/common/files/migrations.cljc b/common/src/app/common/files/migrations.cljc index b930a88385..e18f6bc575 100644 --- a/common/src/app/common/files/migrations.cljc +++ b/common/src/app/common/files/migrations.cljc @@ -2212,7 +2212,34 @@ (update :pages-index d/update-vals update-container) (d/update-when :components d/update-vals update-container)))) -(defmethod migrate-data "0033-normalize-main-instance-names" +(defn- repair-shape-children + [objects shape] + (if-let [shapes (:shapes shape)] + (let [shapes' (into [] + (comp (keep uuid/coerce) + (filter #(contains? objects %)) + (distinct)) + shapes)] + (if (and (vector? shapes) (= shapes shapes')) + shape + (assoc shape :shapes shapes'))) + shape)) + +(defn- repair-container-children + [container] + (d/update-when container :objects + (fn [objects] + ;; Only assoc the shapes that change, so an ObjectsMap is + ;; not marked as modified when nothing is repaired. + (reduce-kv (fn [result id shape] + (let [shape' (repair-shape-children objects shape)] + (if (identical? shape shape') + result + (assoc result id shape')))) + objects + objects)))) + +(defmethod migrate-data "0033-normalize-main-instance-names-v2" [data _] ;; In penpot shape names always have "/" characters normalized with one space between and after, ;; to form paths. But this is not enforced and may be places that still admit names like @@ -2221,15 +2248,13 @@ ;; Here we normalize the names of all main instances, and a new file integrity validation has ;; been added to enforce this from now on. ;; Main instances in variants are a special case because they need to match the variant name. + ;; Old files may also list in :shapes child ids stored as strings, nil, or ids that point to no + ;; shape. They fail the shape schema and the uuid assert of get-shape, so the container is + ;; repaired first (see `repair-container-children`). That repair is the reason for the `-v2`: + ;; files that already applied the original migration need to run it again to get it. (letfn [(update-shape [container shape-id] - (let [shape (ctn/get-shape container shape-id)] - ;; A shape may reference a child that does not exist in the - ;; container (a dangling reference). There is nothing to update - ;; on it, and storing it would add a nil entry to the objects - ;; map, making the whole file invalid. - (if (nil? shape) - container - (let [shape (cond + (let [shape (ctn/get-shape container shape-id) + shape' (cond ;; Variant container must have a normalized name (ctk/is-variant-container? shape) (let [name (:name shape) @@ -2262,13 +2287,19 @@ ;; Any other shape does not need processing :else shape)] - (reduce update-shape - (ctt/set-shape container shape) - (:shapes shape)))))) + ;; Only assoc the shape when the normalization changed it, so an + ;; ObjectsMap is not marked as modified, and the page is not + ;; rewritten, when there is nothing to normalize. + (reduce update-shape + (if (identical? shape shape') + container + (ctt/set-shape container shape')) + (:shapes shape')))) (update-container [container] - (let [root (ctn/get-container-root container)] + (let [container (repair-container-children container) + root (ctn/get-container-root container)] (if root (update-shape container (:id root)) container)))] @@ -2502,7 +2533,7 @@ "0030-remove-stroke-per-side-attr" "0031-migrate-stroke-width-token-attr" "0032-fix-children-not-in-parent" - "0033-normalize-main-instance-names" + "0033-normalize-main-instance-names-v2" "0034-fix-path-content-offset" "0035-fix-dangling-children" "0036-clear-nil-keys-in-objects" diff --git a/common/test/common_tests/files_migrations_0033_test.cljc b/common/test/common_tests/files_migrations_0033_test.cljc index 6f56602b77..729110a96f 100644 --- a/common/test/common_tests/files_migrations_0033_test.cljc +++ b/common/test/common_tests/files_migrations_0033_test.cljc @@ -6,21 +6,21 @@ (ns common-tests.files-migrations-0033-test "Regression coverage for the shape tree traversal of the - `0033-normalize-main-instance-names` migration. + `0033-normalize-main-instance-names-v2` migration. The migration walks a container from its root down, following the `:shapes` vectors. A file can hold a `:shapes` entry pointing to a shape that is not in the `:objects` map (a dangling reference). The - traversal must skip it instead of storing a nil shape into the - `:objects` map, and must keep normalizing the names of the shapes - that do exist." + repair that runs before the walk drops it instead of storing a nil + shape into the `:objects` map, and the walk keeps normalizing the + names of the shapes that do exist." (:require [app.common.files.migrations :as cfm] [app.common.types.shape :as cts] [app.common.uuid :as uuid] [clojure.test :as t])) -(def ^:private migration "0033-normalize-main-instance-names") +(def ^:private migration "0033-normalize-main-instance-names-v2") (defn- make-root [children] @@ -47,7 +47,7 @@ [component-id objects] {:components {component-id {:id component-id :objects objects}}}) -;; --- The guard: a missing child must not become a nil shape +;; --- A missing child is dropped, and never becomes a nil shape (t/deftest missing-child-of-a-page-does-not-create-a-nil-shape (let [page-id (uuid/next) @@ -61,8 +61,8 @@ "no nil key is added to the objects map") (t/is (= 1 (count objects')) "the objects map keeps only the shapes that exist") - (t/is (= root (get objects' uuid/zero)) - "the root is left untouched"))) + (t/is (= (assoc root :shapes []) (get objects' uuid/zero)) + "the dangling child is dropped, the rest of the root is left untouched"))) (t/deftest missing-child-of-a-component-does-not-create-a-nil-shape (let [component-id (uuid/next) @@ -76,8 +76,8 @@ "no nil key is added to the objects map") (t/is (= 1 (count objects')) "the objects map keeps only the shapes that exist") - (t/is (= root (get objects' uuid/zero)) - "the component root is left untouched"))) + (t/is (= (assoc root :shapes []) (get objects' uuid/zero)) + "the dangling child is dropped, the rest of the component root is left untouched"))) (t/deftest missing-child-deep-in-the-tree-does-not-create-a-nil-shape (let [page-id (uuid/next) @@ -92,8 +92,8 @@ (t/is (not (contains? objects' nil)) "no nil key is added to the objects map") - (t/is (= frame (get objects' frame-id)) - "the parent of the missing child is left untouched"))) + (t/is (= (assoc frame :shapes []) (get objects' frame-id)) + "the missing child is dropped, the rest of its parent is left untouched"))) ;; --- The behavior: names keep being normalized next to a missing child diff --git a/common/test/common_tests/files_migrations_0035_test.cljc b/common/test/common_tests/files_migrations_0035_test.cljc index c64ce69527..67857c5b89 100644 --- a/common/test/common_tests/files_migrations_0035_test.cljc +++ b/common/test/common_tests/files_migrations_0035_test.cljc @@ -166,7 +166,7 @@ file {:id file-id :data data :migrations (disj cfm/available-migrations - "0033-normalize-main-instance-names" + "0033-normalize-main-instance-names-v2" "0034-fix-path-content-offset" migration)}] diff --git a/common/test/common_tests/files_migrations_test.cljc b/common/test/common_tests/files_migrations_test.cljc index cb27492b6a..5cc3299c0b 100644 --- a/common/test/common_tests/files_migrations_test.cljc +++ b/common/test/common_tests/files_migrations_test.cljc @@ -17,6 +17,7 @@ [app.common.test-helpers.shapes :as ths] [app.common.test-helpers.variants :as thv] [app.common.types.file :as ctf] + [app.common.types.objects-map :as omap] [app.common.types.path :as path] [app.common.types.shape :as cts] [app.common.types.token :as ctt] @@ -715,7 +716,7 @@ "path points repaired before schema validation"))) (t/deftest migration-0033-normalize-main-instance-diff-from-component - (let [migration-id "0033-normalize-main-instance-names" + (let [migration-id "0033-normalize-main-instance-names-v2" file (-> (thf/sample-file :file1) (tho/add-simple-component :component1 :root1 :child1 :component-params {:path "Group / Subgroup" @@ -746,7 +747,7 @@ (t/is (= "Other Group/Other Subgroup / Other Name" (:name shape1'))))) (t/deftest migration-0033-normalize-variant-instance-diff-from-container - (let [migration-id "0033-normalize-main-instance-names" + (let [migration-id "0033-normalize-main-instance-names-v2" file (-> (thf/sample-file :file1) (thv/add-variant :variant1 :component1 :root1 :component2 :root2) (ths/update-shape :variant1 :name "Group / Subgroup / Component") @@ -778,7 +779,7 @@ (t/is (= "Group / Subgroup/Component" (:name copy2'))))) (t/deftest migration-0033-normalize-variant-name-not-normalized - (let [migration-id "0033-normalize-main-instance-names" + (let [migration-id "0033-normalize-main-instance-names-v2" file (-> (thf/sample-file :file1) (thv/add-variant :variant1 :component1 :root1 :component2 :root2) (ths/update-shape :variant1 :name "Group/Subgroup / Component") @@ -808,3 +809,150 @@ (t/is (= "Component" (:name component1'))) (t/is (= "Component" (:name component2'))) (t/is (= "Group / Subgroup/Component" (:name copy2'))))) + +(t/deftest migration-0033-fixes-children-ids + ;; Old files may list in :shapes child ids stored as strings, nil or + ;; ids that point to no shape; strings become uuids, the rest goes. + (let [migration-id "0033-normalize-main-instance-names-v2" + file (-> (thf/sample-file :file1) + (tho/add-frame-with-child :frame1 :child1) + (tho/add-simple-component :component1 :root1 :child2)) + child1-id (thi/id :child1) + child2-id (thi/id :child2) + file (-> file + (ths/update-shape :frame1 :shapes + [nil "not-a-uuid" (str child1-id) + (uuid/next) child1-id]) + (ths/update-shape :root1 :shapes [(str child2-id)])) + data' (cfm/migrate-data (ctf/file-data file) migration-id) + file' (assoc file :data data')] + + (t/is (= [child1-id] (:shapes (ths/get-shape file' :frame1)))) + (t/is (= [child2-id] (:shapes (ths/get-shape file' :root1)))) + (t/is (= data' (cfm/migrate-data data' migration-id)) + "migration is idempotent"))) + +(t/deftest migration-0033-fixes-children-ids-outside-the-root-walk + ;; A shape that the page root does not reach is not visited by the + ;; walk of 0033, so its children must be repaired before it. + (let [migration-id "0033-normalize-main-instance-names-v2" + file (-> (thf/sample-file :file1) + (tho/add-frame-with-child :frame1 :child1) + (tho/add-frame :frame2)) + frame2-id (thi/id :frame2) + file (-> file + (ths/update-shape :frame1 :shapes []) + (ths/update-shape :child1 :parent-id (uuid/next)) + (ths/update-shape :child1 :shapes [nil (str frame2-id)])) + data' (cfm/migrate-data (ctf/file-data file) migration-id) + file' (assoc file :data data')] + + (t/is (= [frame2-id] (:shapes (ths/get-shape file' :child1)))))) + +(t/deftest migration-0033-fixes-children-ids-in-legacy-components + ;; Legacy components keep their own :objects, which the data schema + ;; does not validate shape by shape. + (let [migration-id "0033-normalize-main-instance-names-v2" + component-id (uuid/next) + root-id (uuid/next) + child-id (uuid/next) + data (-> (ctf/file-data (thf/sample-file :file1)) + (assoc-in [:components component-id] + {:id component-id + :name "Component" + :objects {root-id {:id root-id :shapes [nil (str child-id) (uuid/next)]} + child-id {:id child-id}}})) + data' (cfm/migrate-data data migration-id)] + + (t/is (= [child-id] (get-in data' [:components component-id :objects root-id :shapes]))))) + +(t/deftest migration-0033-turns-shapes-lists-into-vectors + (let [migration-id "0033-normalize-main-instance-names-v2" + file (-> (thf/sample-file :file1) + (tho/add-frame-with-child :frame1 :child1)) + child1-id (thi/id :child1) + file (ths/update-shape file :frame1 :shapes (list child1-id)) + data' (cfm/migrate-data (ctf/file-data file) migration-id) + shapes (:shapes (ths/get-shape (assoc file :data data') :frame1))] + + (t/is (vector? shapes)) + (t/is (= [child1-id] shapes)))) + +(t/deftest migration-0033-leaves-valid-objects-untouched + ;; Nothing to repair: the objects map must be the same instance, so an + ;; ObjectsMap is not marked as modified and its page is not rewritten. + (let [migration-id "0033-normalize-main-instance-names-v2" + file (-> (thf/sample-file :file1) + (tho/add-frame-with-child :frame1 :child1)) + page-id (thf/current-page-id file) + data (ctf/file-data file) + data' (cfm/migrate-data data migration-id)] + + (t/is (identical? (get-in data [:pages-index page-id :objects]) + (get-in data' [:pages-index page-id :objects])))) + + ;; Same property through the objects-map wrapper the backend uses on the + ;; unrealized save path, whose `assoc` marks the page as modified. + (let [migration-id "0033-normalize-main-instance-names-v2" + file (-> (thf/sample-file :file1) + (tho/add-frame-with-child :frame1 :child1)) + page-id (thf/current-page-id file) + objects (omap/wrap (get-in (ctf/file-data file) [:pages-index page-id :objects])) + data (assoc-in (ctf/file-data file) [:pages-index page-id :objects] objects) + data' (cfm/migrate-data data migration-id)] + + (t/is (omap/objects-map? objects) "wrapped in an ObjectsMap") + (t/is (identical? objects (get-in data' [:pages-index page-id :objects]))))) + +(t/deftest migration-0033-v2-runs-on-files-that-applied-the-original-id + ;; Files that applied the original migration before it repaired children + ;; never run it again, so the id moved to -v2. A file still carrying the + ;; old id must run the v2, and keeping the old id does no harm. + (let [file (-> (thf/sample-file :file1) + (tho/add-frame-with-child :frame1 :child1)) + child1-id (thi/id :child1) + file (-> file + (ths/update-shape :frame1 :shapes [(str child1-id) nil]) + (assoc :migrations + (conj (disj cfm/available-migrations + "0033-normalize-main-instance-names-v2") + "0033-normalize-main-instance-names"))) + file' (cfm/migrate-file file {})] + + (t/is (not (cfm/need-migration? file')) "the v2 migration is recorded") + (t/is (contains? (:migrations file') "0033-normalize-main-instance-names") + "the old id is kept") + (t/is (= [child1-id] (:shapes (ths/get-shape file' :frame1)))))) + +(t/deftest migrations-leave-shapes-without-the-shapes-key-untouched + ;; Only containers have a :shapes key; other shapes come out of the + ;; repair unchanged, without a :shapes key being added. + (let [migration-id "0033-normalize-main-instance-names-v2" + file (-> (thf/sample-file :file1) + (tho/add-frame-with-child :frame1 :child1)) + child (ths/get-shape file :child1) + data' (cfm/migrate-data (ctf/file-data file) migration-id) + child' (ths/get-shape (assoc file :data data') :child1)] + + (t/is (not (contains? child :shapes)) "the fixture shape has no :shapes key") + (t/is (not (contains? child' :shapes)) (str migration-id)) + (t/is (= child child') migration-id))) + +(t/deftest migration-0033-fixes-children-ids-through-file-migration + ;; 0032 adds the uuid of a child listed as a string, so the child is + ;; listed twice before 0033; the file must still pass validation. The v2 + ;; keeps the position of the original migration, so it parses the string + ;; before 0035-fix-dangling-children drops the ids it cannot find. + (let [file (-> (thf/sample-file :file1) + (tho/add-frame-with-child :frame1 :child1)) + child1-id (thi/id :child1) + file (-> file + (ths/update-shape :frame1 :shapes [(str child1-id)]) + (assoc :migrations + (disj cfm/available-migrations + "0032-fix-children-not-in-parent" + "0033-normalize-main-instance-names-v2"))) + file' (cfm/migrate-file file {})] + + (t/is (not (cfm/need-migration? file')) "new migrations recorded") + (t/is (= [child1-id] (:shapes (ths/get-shape file' :frame1)))))) From 8e575894f121105208bf13b9a6832d3712baa9e8 Mon Sep 17 00:00:00 2001 From: Pablo Alba Date: Wed, 18 Nov 2026 15:46:38 +0100 Subject: [PATCH 02/10] :sparkles: Add migrations to sanitize variant properties and align component names (#12957) * :sparkles: Add migration to sanitize variant property text (cherry picked from commit 77f1767240026df0cc705f4f084725e28b94230e) * :sparkles: Add migration to align variant component names (cherry picked from commit 844993796d2cd16a02d20e10469107a769ace60c) * :sparkles: MR fixes * :sparkles: MR review 2 --- common/src/app/common/files/migrations.cljc | 76 +++++++++- common/src/app/common/files/variant.cljc | 89 ++++++++++++ common/src/app/common/types/variant.cljc | 119 +++++++++++++++ .../test/common_tests/files/variant_test.cljc | 87 +++++++++++ .../files_migrations_0038_test.cljc | 137 ++++++++++++++++++ .../files_migrations_0039_test.cljc | 136 +++++++++++++++++ common/test/common_tests/runner.cljc | 4 + .../test/common_tests/types/variant_test.cljc | 128 ++++++++++++++++ 8 files changed, 775 insertions(+), 1 deletion(-) create mode 100644 common/test/common_tests/files_migrations_0038_test.cljc create mode 100644 common/test/common_tests/files_migrations_0039_test.cljc diff --git a/common/src/app/common/files/migrations.cljc b/common/src/app/common/files/migrations.cljc index e18f6bc575..b3d71465db 100644 --- a/common/src/app/common/files/migrations.cljc +++ b/common/src/app/common/files/migrations.cljc @@ -14,6 +14,7 @@ [app.common.files.defaults :as cfd] [app.common.files.helpers :as cfh] [app.common.files.tokens :as cfo] + [app.common.files.variant :as cfv] [app.common.geom.matrix :as gmt] [app.common.geom.point :as gpt] [app.common.geom.rect :as grc] @@ -2445,6 +2446,77 @@ (update :pages-index d/update-vals update-container) (d/update-when :components d/update-vals update-container)))) +;; Property names and values used to accept `,` and `=`. The formula +;; editor treats those as separators, and a later edit strips them. +;; Files saved before that strip can also hold two identical names, two +;; identical value combinations, or a label that was not saved with the +;; values. Rewrite the text in place and refresh the label. +(defn- variant-container-entries + [data] + (concat + (for [page (vals (:pages-index data)) + shape (vals (:objects page)) + :when (ctk/is-variant-container? shape)] + {:objects (:objects page) + :container shape}) + (for [component (vals (:components data)) + shape (vals (:objects component)) + :when (ctk/is-variant-container? shape)] + {:objects (:objects component) + :container shape}))) + +(defmethod migrate-data "0038-sanitize-variant-property-text" + [data _] + (let [entries (variant-container-entries data) + used-ids (into #{} + (comp (mapcat (fn [{:keys [objects container]}] + (cfv/qualifying-variant-members data objects container))) + (map :component-id)) + entries) + data (reduce (fn [data {:keys [objects container]}] + (cfv/sanitize-variant-container data objects container)) + data + entries)] + (->> (vals (:components data)) + (filter ctk/is-variant?) + (remove #(contains? used-ids (:id %))) + (reduce cfv/sanitize-variant-component data)))) + +;; The board name and each main's layer name are already normalized. +;; The library entry could still carry the previous path. Point every +;; member of the board at that board name. +(defmethod migrate-data "0039-align-variant-component-names" + [data _] + (letfn [(align-container [data objects container] + (let [board-name (or (:name container) "") + [path item-name] (cpn/split-group-name board-name)] + (reduce (fn [data child-id] + (let [child (get objects child-id) + component (when child + (get-in data [:components (:component-id child)]))] + (if (and (ctk/is-variant? child) + (= (:id container) (:variant-id child)) + (some? component) + (= (:id container) (:variant-id component)) + (not= board-name + (cpn/merge-path-item (:path component) (:name component)))) + (update-in data [:components (:id component)] + assoc :path path :name item-name) + data))) + data + (:shapes container)))) + + (containers-in [objects] + (filter ctk/is-variant-container? (vals objects)))] + + (reduce (fn [data objects] + (reduce #(align-container %1 objects %2) + data + (containers-in objects))) + data + (concat (map :objects (vals (:pages-index data))) + (map :objects (vals (:components data))))))) + (def available-migrations (into (d/ordered-set) ["legacy-2" @@ -2537,4 +2609,6 @@ "0034-fix-path-content-offset" "0035-fix-dangling-children" "0036-clear-nil-keys-in-objects" - "0037-fix-shape-svg-attrs-and-defs"])) + "0037-fix-shape-svg-attrs-and-defs" + "0038-sanitize-variant-property-text" + "0039-align-variant-component-names"])) diff --git a/common/src/app/common/files/variant.cljc b/common/src/app/common/files/variant.cljc index 80dde18d72..01baabbfbe 100644 --- a/common/src/app/common/files/variant.cljc +++ b/common/src/app/common/files/variant.cljc @@ -100,3 +100,92 @@ :component-id (ctcl/get-component data)) component))) + +(defn- variant-main-shape-path + "Path in file data to the main shape of `component`: inside the + component `:objects` when it is deleted, or on its page. Nil when the + component has no main." + [component] + (let [main-id (:main-instance-id component) + page-id (:main-instance-page component)] + (cond + (and (:deleted component) main-id) + [:components (:id component) :objects main-id] + + (and page-id main-id) + [:pages-index page-id :objects main-id] + + :else + nil))) + +(defn get-variant-main-shape + "Return the main shape map for `component`, or nil when it is absent." + [data component] + (some->> (variant-main-shape-path component) + (get-in data))) + +(defn variant-main-label-changed? + "True when the main shape exists and its :variant-name is not + `properties-to-name` of `props`." + [data component props] + (let [shape (get-variant-main-shape data component)] + (and (map? shape) + (not= (ctv/properties-to-name props) + (:variant-name shape))))) + +(defn- qualifying-variant-member + [data objects container child-id] + (when-let [child (get objects child-id)] + (let [component (get-in data [:components (:component-id child)])] + (when (and (ctc/is-variant? child) + (= (:id container) (:variant-id child)) + (some? component) + (= (:id container) (:variant-id component))) + {:component component + :component-id (:id component)})))) + +(defn qualifying-variant-members + "Return qualifying members of `container` in `:shapes` order. + Each member is {:component component :component-id id}." + [data objects container] + (into [] + (keep #(qualifying-variant-member data objects container %)) + (:shapes container))) + +(defn update-variant-properties + "Apply `f` to the `:variant-properties` of `component` and write the + result to `data`. Also refresh the `:variant-name` of its main shape + when it no longer matches. Return `data` unchanged when nothing differs." + [data component f] + (let [old-props (vec (or (:variant-properties component) [])) + props (f old-props) + data (if (= old-props props) + data + (assoc-in data [:components (:id component) :variant-properties] props))] + (if (variant-main-label-changed? data component props) + (assoc-in data + (conj (variant-main-shape-path component) :variant-name) + (ctv/properties-to-name props)) + data))) + +(defn update-variant-container-properties + "Apply `f` to the property vectors of the members of `container`, in + `:shapes` order, and write each result with `update-variant-properties`. + `f` takes and returns a vector of property vectors." + [data objects container f] + (let [components (mapv :component (qualifying-variant-members data objects container)) + props-seq (f (mapv #(vec (or (:variant-properties %) [])) components))] + (reduce (fn [data [component props]] + (update-variant-properties data component (constantly props))) + data + (map vector components props-seq)))) + +(defn sanitize-variant-component + "Sanitize the properties of one variant component on its own." + [data component] + (update-variant-properties data component ctv/sanitize-properties)) + +(defn sanitize-variant-container + "Sanitize the properties of every member of `container` as one set." + [data objects container] + (update-variant-container-properties data objects container ctv/sanitize-properties-set)) diff --git a/common/src/app/common/types/variant.cljc b/common/src/app/common/types/variant.cljc index 0469c3c674..f4a6636448 100644 --- a/common/src/app/common/types/variant.cljc +++ b/common/src/app/common/types/variant.cljc @@ -235,6 +235,125 @@ :value (:value prop)})) []))) +;; Sanitize stored property sets. Unlike `prepare-property-name` and +;; `prepare-property-value`, which reject invalid user input with nil, +;; these helpers always return valid text, so they can repair data. + +(defn clip-property-text + "Cut `text` to at most `max-length` characters." + [text max-length] + (if (> (count text) max-length) + (subs text 0 max-length) + text)) + +(defn- numbered-property-text + "Join `base` and the ` (n)` suffix. Clip and trim `base` so the result + fits in `property-max-length`, whatever the length of the suffix. An + empty base yields \"(n)\"." + [base n] + (let [suffix (str " (" n ")") + base (-> base + (clip-property-text (- property-max-length (count suffix))) + str/trim)] + (if (str/empty? base) + (str "(" n ")") + (str base suffix)))) + +(defn unique-property-text + "Return `text`, trimmed and fitted in `property-max-length`. When the + result is in `taken`, add or raise a ` (n)` suffix until it is not. + A ` (n)` suffix is never cut: the base is clipped to leave room for it." + [taken text] + (let [text (str/trim (or text "")) + [base num] (split-base-name-and-number text) + text (if (and (pos? num) (> (count text) property-max-length)) + (numbered-property-text base num) + (-> text + (clip-property-text property-max-length) + str/trim)) + taken (set taken)] + (if-not (contains? taken text) + text + (let [[base num] (split-base-name-and-number text)] + (->> (iterate inc (max num 1)) + (map #(numbered-property-text base %)) + (d/seek #(not (contains? taken %)))))))) + +(defn sanitize-property-name + "Return a valid property name for `name`, unique against the names in + `taken`. Strip forbidden characters and trim. A blank or non-string + name becomes a generated `Property N`." + [name taken] + (let [text (or (sanitize-property-text name) "") + text (if (str/blank? text) + (str property-prefix + (next-property-number (map (fn [name] {:name name}) taken))) + text)] + (unique-property-text taken text))) + +(defn sanitize-property-value + "Return a valid property value for `value`. Strip forbidden characters, + trim and clip. A non-string value becomes \"\"." + [value] + (-> (or (sanitize-property-text value) "") + (clip-property-text property-max-length) + str/trim)) + +(defn sanitize-properties + "Sanitize the name and value of every property in `props`, keeping + names unique. Other keys of each property are kept." + [props] + (reduce (fn [acc prop] + (conj acc (assoc prop + :name (sanitize-property-name (:name prop) (map :name acc)) + :value (sanitize-property-value (:value prop))))) + [] + props)) + +(defn properties-names + "Return every property name in `props-seq` (a seq of property vectors), + without repeats, in the order they first appear." + [props-seq] + (into [] (comp cat (map :name) (distinct)) props-seq)) + +(defn align-properties + "Return the properties of `props` in the order of `names`. A name with + no property in `props` gets an empty value." + [props names] + (mapv (fn [name] + (or (d/seek #(= name (:name %)) props) + {:name name :value ""})) + names)) + +(defn unique-values-tuple + "Return `props` with a value combination that is not in `seen` (a seq of + value vectors). On a clash, number the last non-blank value, or the + first value when all are blank." + [props seen] + (let [seen (set seen)] + (if (or (empty? props) + (not (contains? seen (mapv :value props)))) + props + (let [idx (or (last (keep-indexed (fn [idx prop] + (when-not (str/blank? (:value prop)) idx)) + props)) + 0) + taken (map #(nth % idx "") seen)] + (update-in props [idx :value] #(unique-property-text taken %)))))) + +(defn sanitize-properties-set + "Sanitize the property vectors of all the variants of one set, given in + board order. Every vector gets the same names in the same order, and no + two vectors share a value combination. Earlier vectors keep their values." + [props-seq] + (let [cleaned (mapv sanitize-properties props-seq) + names (properties-names cleaned)] + (reduce (fn [acc props] + (conj acc (unique-values-tuple (align-properties props names) + (map #(mapv :value %) acc)))) + [] + cleaned))) + (defn find-index-for-property-name "Finds the index of a name in a property map" [props name] diff --git a/common/test/common_tests/files/variant_test.cljc b/common/test/common_tests/files/variant_test.cljc index fda97d565e..15b7386ab2 100644 --- a/common/test/common_tests/files/variant_test.cljc +++ b/common/test/common_tests/files/variant_test.cljc @@ -12,6 +12,7 @@ [app.common.test-helpers.ids-map :as thi] [app.common.test-helpers.shapes :as ths] [app.common.test-helpers.variants :as thv] + [app.common.uuid :as uuid] [clojure.test :as t])) (t/use-fixtures :each thi/test-fixture) @@ -47,3 +48,89 @@ collected (cfv/collect-variant-properties (:data file) (:objects page) shape)] (t/is (= {} collected)))) + +(defn- variant-file + [] + (-> (thf/sample-file :file1) + (thv/add-variant :v01 :c01 :m01 :c02 :m02))) + +(t/deftest test-update-variant-properties-writes-props-and-label + (let [file (variant-file) + props [{:name "Property 1" :value "New"}] + data' (cfv/update-variant-properties (:data file) (thc/get-component file :c01) (constantly props)) + file' (assoc file :data data')] + + (t/is (= props (:variant-properties (thc/get-component file' :c01)))) + (t/is (= "New" (:variant-name (ths/get-shape file' :m01)))))) + +(t/deftest test-update-variant-properties-leaves-clean-data-unchanged + (let [file (variant-file) + data (:data file)] + + (t/is (= data (cfv/update-variant-properties data (thc/get-component file :c01) identity))))) + +(t/deftest test-update-variant-properties-writes-the-label-of-a-deleted-component + (let [file (variant-file) + deleted-id (uuid/next) + main-id (uuid/next) + component {:id deleted-id + :name "Gone" + :path "" + :deleted true + :variant-id (thi/id :v01) + :main-instance-id main-id + :main-instance-page (:id (thf/current-page file)) + :variant-properties [{:name "Size" :value "big"}] + :objects {main-id {:id main-id + :type :frame + :name "Gone" + :variant-id (thi/id :v01) + :variant-name "stale"}}} + data (assoc-in (:data file) [:components deleted-id] component) + data' (cfv/update-variant-properties data component identity)] + + (t/is (= "big" (get-in data' [:components deleted-id :objects main-id :variant-name]))))) + +(t/deftest test-sanitize-variant-container-cleans-members-in-board-order + ;; :shapes of the board is [m02 m01], so c02 keeps its value. + (let [props [{:name "Property 1" :value "a=b"}] + file (-> (variant-file) + (thc/update-component :c01 {:variant-properties props}) + (thc/update-component :c02 {:variant-properties props})) + page (thf/current-page file) + container (ths/get-shape file :v01) + data' (cfv/sanitize-variant-container (:data file) (:objects page) container) + file' (assoc file :data data')] + + (t/is (= [{:name "Property 1" :value "ab"}] + (:variant-properties (thc/get-component file' :c02)))) + (t/is (= [{:name "Property 1" :value "ab (1)"}] + (:variant-properties (thc/get-component file' :c01)))) + (t/is (= "ab (1)" (:variant-name (ths/get-shape file' :m01)))))) + +(t/deftest test-sanitize-variant-component + (let [file (-> (variant-file) + (thc/update-component :c01 {:variant-properties [{:name "Size=Big" :value "a,b"}]})) + data' (cfv/sanitize-variant-component (:data file) (thc/get-component file :c01)) + file' (assoc file :data data')] + + (t/is (= [{:name "SizeBig" :value "ab"}] + (:variant-properties (thc/get-component file' :c01)))) + (t/is (= "ab" (:variant-name (ths/get-shape file' :m01)))))) + +(t/deftest test-sanitize-variant-container-skips-a-child-of-another-set + ;; m03 belongs to v02 but is listed in the :shapes of v01. + (let [dirty [{:name "Property 1" :value "a=b"}] + file (-> (variant-file) + (thv/add-variant :v02 :c03 :m03 :c04 :m04) + (thc/update-component :c03 {:variant-properties dirty})) + shapes (conj (:shapes (ths/get-shape file :v01)) (thi/id :m03)) + file (ths/update-shape file :v01 :shapes shapes) + page (thf/current-page file) + container (ths/get-shape file :v01) + data' (cfv/sanitize-variant-container (:data file) (:objects page) container) + file' (assoc file :data data')] + + (t/is (= dirty (:variant-properties (thc/get-component file' :c03)))) + (t/is (= (:variant-name (ths/get-shape file :m03)) + (:variant-name (ths/get-shape file' :m03)))))) diff --git a/common/test/common_tests/files_migrations_0038_test.cljc b/common/test/common_tests/files_migrations_0038_test.cljc new file mode 100644 index 0000000000..d5ea3383d4 --- /dev/null +++ b/common/test/common_tests/files_migrations_0038_test.cljc @@ -0,0 +1,137 @@ +;; This Source Code Form is subject to the terms of the Mozilla Public +;; License, v. 2.0. If a copy of the MPL was not distributed with this +;; file, You can obtain one at http://mozilla.org/MPL/2.0/. +;; +;; Copyright (c) KALEIDOS SUBSIDIARY SL + +(ns common-tests.files-migrations-0038-test + (:require + [app.common.files.migrations :as cfm] + [app.common.test-helpers.components :as thk] + [app.common.test-helpers.files :as thf] + [app.common.test-helpers.ids-map :as thi] + [app.common.test-helpers.shapes :as ths] + [app.common.test-helpers.variants :as thv] + [app.common.types.file :as ctf] + [app.common.types.variant :as ctv] + [app.common.uuid :as uuid] + [clojure.test :as t])) + +(t/use-fixtures :each thi/test-fixture) + +;; ====================================================================== +;; 0038-sanitize-variant-property-text +;; Property names and values used to accept `,` and `=`, which the +;; formula editor treats as separators. Files saved before those were +;; stripped can also hold two identical names, two identical value +;; combinations, or a main whose `:variant-name` does not match its +;; properties. The migration rewrites the text in place and refreshes +;; the label. +;; ====================================================================== + +(def ^:private migration-id + "0038-sanitize-variant-property-text") + +(defn- migrate-text + [file] + (let [data' (cfm/migrate-data (ctf/file-data file) migration-id)] + (assoc file :data data'))) + +(defn- variant-file + [] + (-> (thf/sample-file :file1) + (thv/add-variant :variant1 :component1 :root1 :component2 :root2))) + +(t/deftest migration-0038-strips-forbidden-characters + ;; root2 is the first child of :shapes, so its names lead the set. + (let [file (-> (variant-file) + (thk/update-component :component2 {:variant-properties [{:name "Size=Big" + :value "a=b," + :hidden true}]}) + (thk/instantiate-component :component1 :copy2) + (ths/update-shape :copy2 :name "Loose copy")) + copy (ths/get-shape file :copy2) + file' (migrate-text file) + comp2' (thk/get-component file' :component2) + root2' (ths/get-shape file' :root2) + comp1' (thk/get-component file' :component1) + copy' (ths/get-shape file' :copy2) + data' (ctf/file-data file')] + + (t/is (= "SizeBig" (-> comp2' :variant-properties first :name))) + (t/is (= "ab" (-> comp2' :variant-properties first :value))) + (t/is (true? (-> comp2' :variant-properties first :hidden))) + (t/is (= "ab" (:variant-name root2'))) + (t/is (= "Value1" (->> (:variant-properties comp1') + (some #(when (= "Property 1" (:name %)) %)) + :value))) + (t/is (= copy copy') "copies are left untouched") + (t/is (= data' (cfm/migrate-data data' migration-id))))) + +(t/deftest migration-0038-refreshes-a-stale-variant-name + (let [props [{:name "State" :value "active"} + {:name "Tone" :value "crítica"}] + file (-> (variant-file) + (thk/update-component :component2 {:variant-properties props}) + (thk/update-component :component1 {:variant-properties [{:name "State" :value "active"} + {:name "Tone" :value "hostil"}]}) + (ths/update-shape :root2 :variant-name "active, hostil")) + file' (migrate-text file) + comp' (thk/get-component file' :component2) + root' (ths/get-shape file' :root2) + data' (ctf/file-data file')] + + (t/is (= props (:variant-properties comp'))) + (t/is (= "active, crítica" (:variant-name root'))) + (t/is (= (ctv/properties-to-name props) (:variant-name root'))) + (t/is (= data' (cfm/migrate-data data' migration-id))))) + +(t/deftest migration-0038-does-not-take-names-from-a-detached-component + (let [deleted-id (uuid/next) + main-id (uuid/next) + file (variant-file) + variant-id (thi/id :variant1) + page-id (:id (thf/current-page file)) + file (update file :data + (fn [data] + (assoc-in data [:components deleted-id] + {:id deleted-id + :name "Gone" + :path "" + :deleted true + :variant-id variant-id + :main-instance-id main-id + :main-instance-page page-id + :variant-properties [{:name "Legacy=Name" :value "a=b"}] + :objects {main-id {:id main-id + :type :frame + :name "Gone" + :variant-id variant-id + :variant-name "stale"}}}))) + file' (migrate-text file) + live-names (mapv :name (:variant-properties (thk/get-component file' :component2))) + deleted (get-in file' [:data :components deleted-id]) + data' (ctf/file-data file')] + + (t/is (= ["Property 1"] live-names)) + (t/is (= "LegacyName" (-> deleted :variant-properties first :name))) + (t/is (= "ab" (-> deleted :variant-properties first :value))) + (t/is (= "ab" (get-in deleted [:objects main-id :variant-name]))) + (t/is (= data' (cfm/migrate-data data' migration-id))))) + +(t/deftest migration-0038-leaves-a-clean-set-unchanged + (let [data (ctf/file-data (variant-file)) + data' (cfm/migrate-data data migration-id)] + + (t/is (= data data')) + (t/is (= data' (cfm/migrate-data data' migration-id))))) + +(t/deftest migration-0038-runs-through-file-migration + (let [file (-> (variant-file) + (thk/update-component :component2 {:variant-properties [{:name "Size=Big" :value "red"}]}) + (assoc :migrations (disj cfm/available-migrations migration-id))) + file' (cfm/migrate-file file {})] + + (t/is (contains? (:migrations file') migration-id)) + (t/is (= "SizeBig" (-> (thk/get-component file' :component2) :variant-properties first :name))) + (t/is (some? (ctf/check-file-data (:data file')))))) diff --git a/common/test/common_tests/files_migrations_0039_test.cljc b/common/test/common_tests/files_migrations_0039_test.cljc new file mode 100644 index 0000000000..344fc22383 --- /dev/null +++ b/common/test/common_tests/files_migrations_0039_test.cljc @@ -0,0 +1,136 @@ +;; This Source Code Form is subject to the terms of the Mozilla Public +;; License, v. 2.0. If a copy of the MPL was not distributed with this +;; file, You can obtain one at http://mozilla.org/MPL/2.0/. +;; +;; Copyright (c) KALEIDOS SUBSIDIARY SL + +(ns common-tests.files-migrations-0039-test + (:require + [app.common.files.migrations :as cfm] + [app.common.path-names :as cpn] + [app.common.test-helpers.components :as thk] + [app.common.test-helpers.files :as thf] + [app.common.test-helpers.ids-map :as thi] + [app.common.test-helpers.shapes :as ths] + [app.common.test-helpers.variants :as thv] + [app.common.types.file :as ctf] + [app.common.types.variant :as ctv] + [app.common.uuid :as uuid] + [clojure.test :as t])) + +(t/use-fixtures :each thi/test-fixture) + +;; ====================================================================== +;; 0039-align-variant-component-names +;; The variant board name and the layer name of each main are already +;; normalized, but the library entry of a member could still carry an +;; older path and name. The migration sets the `:path` and `:name` of +;; every member component from the board name. +;; ====================================================================== + +(def ^:private migration-id + "0039-align-variant-component-names") + +(def ^:private text-migration-id + "0038-sanitize-variant-property-text") + +(defn- named-board + [board-name] + (-> (thf/sample-file :file1) + (thv/add-variant :variant1 :component1 :root1 :component2 :root2) + (ths/update-shape :variant1 :name board-name) + (ths/update-shape :root1 :name board-name) + (ths/update-shape :root2 :name board-name))) + +(t/deftest migration-0039-aligns-component-path-with-the-board + (let [file (-> (named-board "Group / Button") + (thk/update-component :component1 {:path "UI" :name "Button"}) + (thk/update-component :component2 {:path "UI" :name "Button"}) + (thk/instantiate-component :component2 :copy2) + (ths/update-shape :copy2 :name "Loose copy")) + before {:root1 (ths/get-shape file :root1) + :props1 (:variant-properties (thk/get-component file :component1)) + :label1 (:variant-name (ths/get-shape file :root1)) + :copy (ths/get-shape file :copy2)} + data' (cfm/migrate-data (ctf/file-data file) migration-id) + file' (assoc file :data data') + comp1' (thk/get-component file' :component1) + comp2' (thk/get-component file' :component2) + root1' (ths/get-shape file' :root1) + copy' (ths/get-shape file' :copy2)] + + (t/is (= "Group" (:path comp1') (:path comp2'))) + (t/is (= "Button" (:name comp1') (:name comp2'))) + (t/is (= "Group / Button" (cpn/merge-path-item (:path comp1') (:name comp1')))) + (t/is (= (:name (:root1 before)) (:name root1'))) + (t/is (= (:props1 before) (:variant-properties comp1'))) + (t/is (= (:label1 before) (:variant-name root1'))) + (t/is (= (:name (:copy before)) (:name copy'))) + (t/is (= data' (cfm/migrate-data data' migration-id))))) + +(t/deftest migration-0039-keeps-a-board-named-empty + ;; 0033 stores a blank board name as "(empty)"; this migration copies + ;; that name as it is. + (let [file (-> (named-board "(empty)") + (thk/update-component :component1 {:path "Old" :name "Thing"}) + (thk/update-component :component2 {:path "Old" :name "Thing"})) + data' (cfm/migrate-data (ctf/file-data file) migration-id) + file' (assoc file :data data') + comp' (thk/get-component file' :component1)] + + (t/is (= "" (:path comp'))) + (t/is (= "(empty)" (:name comp'))) + (t/is (= "(empty)" (cpn/merge-path-item (:path comp') (:name comp')))) + (t/is (= data' (cfm/migrate-data data' migration-id))))) + +(t/deftest migration-0039-leaves-a-matching-component-unchanged + (let [file (-> (named-board "Group / Button") + (thk/update-component :component1 {:path "Group" :name "Button"}) + (thk/update-component :component2 {:path "Group" :name "Button"})) + data (ctf/file-data file) + data' (cfm/migrate-data data migration-id)] + + (t/is (= data data')) + (t/is (= data' (cfm/migrate-data data' migration-id))))) + +(t/deftest migration-0039-skips-a-component-with-no-board + (let [orphan-id (uuid/next) + file (update (thf/sample-file :file1) :data + (fn [data] + (assoc-in data [:components orphan-id] + {:id orphan-id + :name "Name" + :path "Old" + :variant-id (uuid/next)}))) + data (ctf/file-data file) + data' (cfm/migrate-data data migration-id)] + + (t/is (= data data')))) + +(t/deftest migration-0038-then-0039-cleans-text-and-the-library-name + (let [file (-> (named-board "Group / Button") + (thk/update-component :component2 {:path "UI" + :name "Button" + :variant-properties [{:name "Size=Big" :value "red"}]}) + (thk/update-component :component1 {:path "UI" + :name "Button" + :variant-properties [{:name "Size=Big" :value "blue"}]})) + data' (-> (ctf/file-data file) + (cfm/migrate-data text-migration-id) + (cfm/migrate-data migration-id)) + file' (assoc file :data data') + comp2 (thk/get-component file' :component2) + comp1 (thk/get-component file' :component1) + root2 (ths/get-shape file' :root2) + root1 (ths/get-shape file' :root1)] + + (t/is (= "SizeBig" (-> comp2 :variant-properties first :name))) + (t/is (= "red" (-> comp2 :variant-properties first :value))) + (t/is (= "blue" (-> comp1 :variant-properties first :value))) + (t/is (= (ctv/properties-to-name (:variant-properties comp2)) (:variant-name root2))) + (t/is (= (ctv/properties-to-name (:variant-properties comp1)) (:variant-name root1))) + (t/is (= "Group" (:path comp2) (:path comp1))) + (t/is (= "Button" (:name comp2) (:name comp1))) + (t/is (= data' (-> data' + (cfm/migrate-data text-migration-id) + (cfm/migrate-data migration-id)))))) diff --git a/common/test/common_tests/runner.cljc b/common/test/common_tests/runner.cljc index 29c80c981b..8e2f88006f 100644 --- a/common/test/common_tests/runner.cljc +++ b/common/test/common_tests/runner.cljc @@ -27,6 +27,8 @@ [common-tests.files-migrations-0035-test] [common-tests.files-migrations-0036-test] [common-tests.files-migrations-0037-test] + [common-tests.files-migrations-0038-test] + [common-tests.files-migrations-0039-test] [common-tests.files-migrations-test] [common-tests.files.comp-processors-test] [common-tests.files.helpers-test] @@ -146,6 +148,8 @@ 'common-tests.files-migrations-0035-test 'common-tests.files-migrations-0036-test 'common-tests.files-migrations-0037-test + 'common-tests.files-migrations-0038-test + 'common-tests.files-migrations-0039-test 'common-tests.files-migrations-test 'common-tests.files.comp-processors-test 'common-tests.files.helpers-test diff --git a/common/test/common_tests/types/variant_test.cljc b/common/test/common_tests/types/variant_test.cljc index f477da5bd9..a82abb9e65 100644 --- a/common/test/common_tests/types/variant_test.cljc +++ b/common/test/common_tests/types/variant_test.cljc @@ -107,6 +107,134 @@ (t/is (< dist2 dist4)) (t/is (< dist4 dist3)))) +(def ^:private long-text (apply str (repeat 60 "n"))) +(defn- numbered-long-text + [n] + (let [suffix (str " (" n ")")] + (str (subs long-text 0 (- 60 (count suffix))) suffix))) +(t/deftest clip-property-text + (t/is (= "abc" (ctv/clip-property-text "abc" 5))) + (t/is (= "abc" (ctv/clip-property-text "abcdef" 3)))) +(t/deftest unique-property-text + (t/testing "free text is kept" + (t/is (= "Size" (ctv/unique-property-text [] "Size"))) + (t/is (= "A (1)" (ctv/unique-property-text ["A"] "A (1)")))) + + (t/testing "taken text gets a number" + (t/is (= "Size (1)" (ctv/unique-property-text ["Size"] "Size"))) + (t/is (= "A (2)" (ctv/unique-property-text ["A" "A (1)"] "A (1)")))) + + (t/testing "empty text is numbered without a leading space" + (t/is (= "(1)" (ctv/unique-property-text [""] ""))) + (t/is (= "(2)" (ctv/unique-property-text ["" "(1)"] "")))) + + (t/testing "long text is clipped" + (t/is (= long-text (ctv/unique-property-text [] (str long-text "n"))))) + + (t/testing "the base leaves room for the suffix" + (t/is (= (numbered-long-text 1) (ctv/unique-property-text [long-text] long-text))) + (let [taken (into [long-text] (map numbered-long-text) (range 1 11)) + result (ctv/unique-property-text taken long-text)] + (t/is (= (str (apply str (repeat 55 "n")) " (11)") result)) + (t/is (= 60 (count result))) + (t/is (= result (ctv/unique-property-text taken result))) + (t/is (= result (ctv/unique-property-text (remove #{result} taken) result))))) + + (t/testing "a numbered text over the limit keeps its suffix" + (let [over-1 (str (subs long-text 0 57) " (1)") + over-12 (str (subs long-text 0 58) " (12)")] + (t/is (= (numbered-long-text 1) (ctv/unique-property-text [] over-1))) + (t/is (= (numbered-long-text 12) (ctv/unique-property-text [] over-12))) + (t/is (= (numbered-long-text 1) + (ctv/unique-property-text [] (numbered-long-text 1)))) + (t/is (= (numbered-long-text 2) + (ctv/unique-property-text [(numbered-long-text 1)] over-1)))))) + +(t/deftest sanitize-property-name + (t/is (= "SizeBig" (ctv/sanitize-property-name "Size=Big" []))) + (t/is (= "Size (1)" (ctv/sanitize-property-name "Size" ["Size"]))) + (t/is (= "Property 1" (ctv/sanitize-property-name "=,=" []))) + (t/is (= "Property 2" (ctv/sanitize-property-name "=,=" ["Color"]))) + (t/is (= "Property 1" (ctv/sanitize-property-name 5 [])))) + +(t/deftest sanitize-property-value + (t/is (= "ab" (ctv/sanitize-property-value "a=b,"))) + (t/is (= "x" (ctv/sanitize-property-value " x "))) + (t/is (= "" (ctv/sanitize-property-value 5))) + (t/is (= "" (ctv/sanitize-property-value nil))) + (t/is (= long-text (ctv/sanitize-property-value (str long-text "n"))))) + +(t/deftest sanitize-properties + (t/testing "other keys are kept" + (t/is (= [{:name "SizeBig" :value "ab" :hidden true}] + (ctv/sanitize-properties [{:name "Size=Big" :value "a=b," :hidden true}])))) + + (t/testing "names are unique" + (t/is (= ["SizeBig" "SizeBig (1)"] + (mapv :name (ctv/sanitize-properties [{:name "Size=Big" :value "one"} + {:name "SizeBig" :value "two"}]))))) + + (t/testing "long names stay distinct and keep their values" + (t/is (= [{:name long-text :value "x"} + {:name (numbered-long-text 1) :value "y"}] + (ctv/sanitize-properties [{:name long-text :value "x"} + {:name long-text :value "y"}])))) + + (t/testing "a name numbered past the limit keeps its suffix" + (let [base (subs long-text 0 57)] + (t/is (= [base (numbered-long-text 1)] + (mapv :name (ctv/sanitize-properties [{:name base :value "x"} + {:name (str base " (1)") :value "y"}]))))))) + +(t/deftest properties-names + (t/is (= ["A" "B" "C"] + (ctv/properties-names [[{:name "A"} {:name "B"}] + [{:name "B"} {:name "C"}]])))) + +(t/deftest align-properties + (t/is (= [{:name "A" :value ""} {:name "B" :value "b" :hidden true}] + (ctv/align-properties [{:name "B" :value "b" :hidden true}] ["A" "B"])))) + +(t/deftest unique-values-tuple + (t/testing "no clash" + (t/is (= [{:name "S" :value "a"}] + (ctv/unique-values-tuple [{:name "S" :value "a"}] [["b"]]))) + (t/is (= [] (ctv/unique-values-tuple [] [[]])))) + + (t/testing "the last non-blank value is numbered" + (t/is (= [{:name "S" :value "a (1)"}] + (ctv/unique-values-tuple [{:name "S" :value "a"}] [["a"]]))) + (t/is (= [{:name "S" :value "x"} {:name "C" :value "red (2)"} {:name "D" :value ""}] + (ctv/unique-values-tuple [{:name "S" :value "x"} {:name "C" :value "red"} {:name "D" :value ""}] + [["x" "red" ""] ["y" "red (1)" ""]])))) + + (t/testing "all values blank" + (t/is (= [{:name "S" :value "(1)"}] + (ctv/unique-values-tuple [{:name "S" :value ""}] [[""]]))))) + +(t/deftest sanitize-properties-set + (t/testing "a colliding value tuple is numbered" + (t/is (= [[{:name "Size" :value "ab"}] + [{:name "Size" :value "ab (1)"}]] + (ctv/sanitize-properties-set [[{:name "Size" :value "a=b"}] + [{:name "Size" :value "a=b"}]])))) + + (t/testing "every vector gets the same names" + (t/is (= [[{:name "SizeBig" :value "one"} {:name "SizeBig (1)" :value "two"}] + [{:name "SizeBig" :value "only"} {:name "SizeBig (1)" :value ""}]] + (ctv/sanitize-properties-set [[{:name "Size=Big" :value "one"} + {:name "SizeBig" :value "two"}] + [{:name "Size=Big" :value "only"}]])))) + + (t/testing "a clean set is unchanged and a second run changes nothing" + (let [props-seq [[{:name "Size" :value "big"} {:name "Color" :value "red"}] + [{:name "Size" :value "small"} {:name "Color" :value "red"}]] + dirty [[{:name "a=b" :value long-text} {:name "a=b" :value ""}] + [{:name "ab" :value long-text}] + [{:name "=" :value 5}]] + once (ctv/sanitize-properties-set dirty)] + (t/is (= props-seq (ctv/sanitize-properties-set props-seq))) + (t/is (= once (ctv/sanitize-properties-set once)))))) From eddb824ca72e230f5f54d1d4d588a5354028a1ac Mon Sep 17 00:00:00 2001 From: Andrey Antukh Date: Wed, 18 Nov 2026 14:55:42 +0000 Subject: [PATCH 03/10] :bug: Resolve UI CSS copy paths during bundle builds Resolve the UI CSS source and destination from the package directory so Vite works when launched outside that directory. Add a regression test and quiet the bundle's rsync output. AI-assisted-by: gpt-6-luna --- frontend/packages/ui/README.md | 1 + frontend/packages/ui/package.json | 3 +- .../packages/ui/tests/copy-css-plugin.test.ts | 49 +++++++++++++++++++ frontend/packages/ui/vite.config.mts | 19 ++++--- frontend/scripts/build | 7 ++- 5 files changed, 66 insertions(+), 13 deletions(-) create mode 100644 frontend/packages/ui/tests/copy-css-plugin.test.ts diff --git a/frontend/packages/ui/README.md b/frontend/packages/ui/README.md index ef431d1b50..a4e58ca410 100644 --- a/frontend/packages/ui/README.md +++ b/frontend/packages/ui/README.md @@ -9,3 +9,4 @@ Run from workspace root: - **`pnpm storybook:ui`** - Start Storybook for component development - **`pnpm build:ui`** - Build the library for production - **`pnpm start:ui`** - Build in watch mode for development +- **`pnpm --dir packages/ui test`** - Run the package tests diff --git a/frontend/packages/ui/package.json b/frontend/packages/ui/package.json index 1726ff6d1f..7c1d7767f8 100644 --- a/frontend/packages/ui/package.json +++ b/frontend/packages/ui/package.json @@ -20,7 +20,8 @@ }, "scripts": { "watch": "vite build --watch", - "build": "vite build" + "build": "vite build", + "test": "vitest run --config vite.config.mts" }, "devDependencies": { "@babel/core": "^8.0.6", diff --git a/frontend/packages/ui/tests/copy-css-plugin.test.ts b/frontend/packages/ui/tests/copy-css-plugin.test.ts new file mode 100644 index 0000000000..dbbd8c5187 --- /dev/null +++ b/frontend/packages/ui/tests/copy-css-plugin.test.ts @@ -0,0 +1,49 @@ +import { + mkdtempSync, + mkdirSync, + readFileSync, + rmSync, + writeFileSync, +} from "node:fs"; +import os from "node:os"; +import path from "node:path"; +import { afterEach, expect, it } from "vitest"; +import { copyCssPlugin } from "../vite.config.mts"; + +const temporaryDirectories: string[] = []; + +afterEach(() => { + for (const directory of temporaryDirectories.splice(0)) { + rmSync(directory, { recursive: true, force: true }); + } +}); + +it("copies the generated CSS using paths based on the package directory", () => { + const temporaryDirectory = mkdtempSync( + path.join(os.tmpdir(), "penpot-ui-css-copy-"), + ); + temporaryDirectories.push(temporaryDirectory); + + const packageDirectory = path.join( + temporaryDirectory, + "frontend", + "packages", + "ui", + ); + const cssPath = path.join(packageDirectory, "dist", "ui.css"); + const destinationPath = path.join( + temporaryDirectory, + "frontend", + "resources", + "public", + "css", + "ui.css", + ); + + mkdirSync(path.dirname(cssPath), { recursive: true }); + writeFileSync(cssPath, ".ui { color: red; }"); + + copyCssPlugin(packageDirectory).closeBundle(); + + expect(readFileSync(destinationPath, "utf8")).toBe(".ui { color: red; }"); +}); diff --git a/frontend/packages/ui/vite.config.mts b/frontend/packages/ui/vite.config.mts index 9519e70987..ed2fc91c48 100644 --- a/frontend/packages/ui/vite.config.mts +++ b/frontend/packages/ui/vite.config.mts @@ -2,19 +2,22 @@ import { defineConfig, esmExternalRequirePlugin } from "vite"; import react from "@vitejs/plugin-react"; import dts from "vite-plugin-dts"; -import * as path from "path"; -import { copyFileSync } from "node:fs"; +import * as path from "node:path"; +import { copyFileSync, mkdirSync } from "node:fs"; const externalDeps = ["react", "react-dom", "react/jsx-runtime"]; -const copyCssPlugin = () => ({ +export const copyCssPlugin = (packageDir = import.meta.dirname) => ({ name: "copy-css", closeBundle: () => { - try { - copyFileSync("dist/ui.css", "../../resources/public/css/ui.css"); - } catch (e) { - console.log("Error copying css file", e); - } + const cssPath = path.resolve(packageDir, "dist/ui.css"); + const destinationPath = path.resolve( + packageDir, + "../../resources/public/css/ui.css", + ); + + mkdirSync(path.dirname(destinationPath), { recursive: true }); + copyFileSync(cssPath, destinationPath); }, }); diff --git a/frontend/scripts/build b/frontend/scripts/build index 379b730ed7..5164061129 100755 --- a/frontend/scripts/build +++ b/frontend/scripts/build @@ -55,13 +55,12 @@ pnpm run build:app:assets; sed -i "s/\.\/render.js/.\/render.js?version=$VERSION_TAG/g" resources/public/js/worker/main*.js -rsync -avr resources/public/ target/dist/ +rsync -ar resources/public/ target/dist/ # Include all plugins on the bundle -rsync -avr ../plugins/dist/apps/ target/dist/plugins/; +rsync -ar ../plugins/dist/apps/ target/dist/plugins/; # Include the MCP plugin on the bundle mkdir -p target/dist/plugins/mcp; -rsync -avr ../mcp/packages/plugin/dist/ target/dist/plugins/mcp/; - +rsync -ar ../mcp/packages/plugin/dist/ target/dist/plugins/mcp/; From 15f9994022f9c2f5ae0bd9f4ef3f1b5d2bcce0cf Mon Sep 17 00:00:00 2001 From: Alonso Torres Date: Wed, 18 Nov 2026 17:53:32 +0100 Subject: [PATCH 04/10] :sparkles: Add test coverage reports to CI and pull requests (#13156) Measure the coverage of the backend, common, frontend and render-wasm test suites in CI, and show it on the workflow run pages and in one "Coverage Report" comment on each pull request. - Backend and common run kaocha with the cloverage plugin through a new `:coverage` alias, which writes lcov, HTML and an EMMA report. The PR report shows lines and Clojure forms (as statements); cloverage measures no functions or branches. Plain local runs are unchanged. - Frontend runs the compiled test bundle with V8 coverage (`pnpm run test:coverage`, `frontend/scripts/coverage.js`) and maps it back to the ClojureScript sources through the source maps of the test build. UI namespaces (`app/main/ui`) are left out. - Render-wasm runs its native Rust tests under cargo-llvm-cov when `RENDER_WASM_COVERAGE` is set. The devenv image lacks the tool, so the workflow downloads a pinned release and checks its sha256. - `scripts/coverage-summary.mjs` renders an lcov file as a markdown table by source area for `$GITHUB_STEP_SUMMARY`; each workflow also uploads the HTML report as an artifact. - `scripts/coverage-comment.mjs` keeps a single PR comment, laid out like the Vitest Coverage Report Action, with a section per project and the coverage of the changed files. Each job updates its own section; the data of every project lives in a hidden block of the comment, and a job writes again when a concurrent one dropped its data. - Lines have targets that only colour the report: 70% backend and common, 50% frontend, 40% render-wasm. - The comment step only runs for PRs from branches of this repo: fork PRs get a read-only token and keep the summary on the run page. AI-assisted-by: claude-opus-5-5 --- .github/workflows/tests-backend.yml | 40 ++- .github/workflows/tests-common.yml | 38 +++ .github/workflows/tests-frontend.yml | 39 +++ .github/workflows/tests-wasm.yml | 60 +++++ .gitignore | 1 + .serena/memories/backend/testing.md | 1 + .serena/memories/common/testing.md | 1 + .serena/memories/critical-info.md | 2 + .serena/memories/frontend/testing.md | 1 + .serena/memories/render-wasm/core.md | 1 + backend/deps.edn | 5 + backend/tests.edn | 14 +- common/deps.edn | 5 + common/scripts/test | 2 +- common/tests.edn | 15 +- frontend/package.json | 5 + frontend/pnpm-lock.yaml | 12 + frontend/scripts/coverage.js | 139 ++++++++++ frontend/scripts/test | 2 +- render-wasm/test | 20 +- scripts/coverage-comment.mjs | 373 +++++++++++++++++++++++++++ scripts/coverage-lcov.mjs | 49 ++++ scripts/coverage-summary.mjs | 99 +++++++ 23 files changed, 917 insertions(+), 7 deletions(-) create mode 100644 frontend/scripts/coverage.js create mode 100644 scripts/coverage-comment.mjs create mode 100644 scripts/coverage-lcov.mjs create mode 100644 scripts/coverage-summary.mjs diff --git a/.github/workflows/tests-backend.yml b/.github/workflows/tests-backend.yml index 40b99ff3c5..b6cd409312 100644 --- a/.github/workflows/tests-backend.yml +++ b/.github/workflows/tests-backend.yml @@ -34,6 +34,9 @@ permissions: jobs: test-backend: if: ${{ !github.event.pull_request.draft }} + permissions: + contents: read + pull-requests: write # coverage comment on the PR name: "Backend Tests" runs-on: penpot-extended-runner container: @@ -91,4 +94,39 @@ jobs: run: | mkdir -p /tmp/penpot; - clojure -M:dev:test + clojure -M:dev:test:coverage + + - name: Coverage summary + if: ${{ !cancelled() && hashFiles('backend/target/coverage/lcov.info') != '' }} + run: | + node scripts/coverage-summary.mjs \ + --title "Backend test coverage" \ + --note "Namespaces under \`backend/src/app\`." \ + --lcov backend/target/coverage/lcov.info \ + > backend/target/coverage/summary.md + cat backend/target/coverage/summary.md >> "$GITHUB_STEP_SUMMARY" + + - name: Coverage comment + # Fork PRs get a read-only token, so only branches of this repo comment. + if: ${{ !cancelled() && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && hashFiles('backend/target/coverage/lcov.info') != '' }} + continue-on-error: true + env: + GITHUB_TOKEN: ${{ github.token }} + PR_NUMBER: ${{ github.event.pull_request.number }} + HEAD_SHA: ${{ github.event.pull_request.head.sha }} + run: | + node scripts/coverage-comment.mjs \ + --project Backend \ + --lcov backend/target/coverage/lcov.info \ + --emma-xml backend/target/coverage/coverage.xml \ + --prefix backend/ + + - name: Upload coverage report + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + if: ${{ !cancelled() }} + with: + name: backend-coverage + path: backend/target/coverage/ + overwrite: true + if-no-files-found: ignore + retention-days: 7 diff --git a/.github/workflows/tests-common.yml b/.github/workflows/tests-common.yml index f8168dbade..e586cf7290 100644 --- a/.github/workflows/tests-common.yml +++ b/.github/workflows/tests-common.yml @@ -32,6 +32,9 @@ permissions: jobs: test-common: if: ${{ !github.event.pull_request.draft }} + permissions: + contents: read + pull-requests: write # coverage comment on the PR name: "Common Tests" runs-on: penpot-extended-runner container: @@ -58,3 +61,38 @@ jobs: working-directory: ./common run: | ./scripts/test + + - name: Coverage summary + if: ${{ !cancelled() && hashFiles('common/target/coverage/lcov.info') != '' }} + run: | + node scripts/coverage-summary.mjs \ + --title "Common JVM test coverage" \ + --note "Namespaces under \`common/src/app\`, measured by the JVM tests." \ + --lcov common/target/coverage/lcov.info \ + > common/target/coverage/summary.md + cat common/target/coverage/summary.md >> "$GITHUB_STEP_SUMMARY" + + - name: Coverage comment + # Fork PRs get a read-only token, so only branches of this repo comment. + if: ${{ !cancelled() && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && hashFiles('common/target/coverage/lcov.info') != '' }} + continue-on-error: true + env: + GITHUB_TOKEN: ${{ github.token }} + PR_NUMBER: ${{ github.event.pull_request.number }} + HEAD_SHA: ${{ github.event.pull_request.head.sha }} + run: | + node scripts/coverage-comment.mjs \ + --project Common \ + --lcov common/target/coverage/lcov.info \ + --emma-xml common/target/coverage/coverage.xml \ + --prefix common/ + + - name: Upload coverage report + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + if: ${{ !cancelled() }} + with: + name: common-coverage + path: common/target/coverage/ + overwrite: true + if-no-files-found: ignore + retention-days: 7 diff --git a/.github/workflows/tests-frontend.yml b/.github/workflows/tests-frontend.yml index 9a6ff9ae4b..b9a2135cd5 100644 --- a/.github/workflows/tests-frontend.yml +++ b/.github/workflows/tests-frontend.yml @@ -36,6 +36,9 @@ permissions: jobs: test-frontend: if: ${{ !github.event.pull_request.draft }} + permissions: + contents: read + pull-requests: write # coverage comment on the PR name: "Frontend Tests" runs-on: penpot-extended-runner container: @@ -66,6 +69,42 @@ jobs: run: | ./scripts/test + - name: Coverage summary + if: ${{ !cancelled() && hashFiles('frontend/coverage/lcov.info') != '' }} + run: | + node scripts/coverage-summary.mjs \ + --title "Frontend unit test coverage" \ + --note "Logic namespaces under \`frontend/src/app\`, without \`app/main/ui\`." \ + --lcov frontend/coverage/lcov.info \ + --unloaded frontend/coverage/unloaded.txt \ + > frontend/coverage/summary.md + cat frontend/coverage/summary.md >> "$GITHUB_STEP_SUMMARY" + + - name: Coverage comment + # Fork PRs get a read-only token, so only branches of this repo comment. + if: ${{ !cancelled() && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && hashFiles('frontend/coverage/lcov.info') != '' }} + continue-on-error: true + env: + GITHUB_TOKEN: ${{ github.token }} + PR_NUMBER: ${{ github.event.pull_request.number }} + HEAD_SHA: ${{ github.event.pull_request.head.sha }} + run: | + node scripts/coverage-comment.mjs \ + --project Frontend \ + --lcov frontend/coverage/lcov.info \ + --json-summary frontend/coverage/coverage-summary.json \ + --unloaded frontend/coverage/unloaded.txt + + - name: Upload coverage report + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + if: ${{ !cancelled() }} + with: + name: frontend-coverage + path: frontend/coverage/ + overwrite: true + if-no-files-found: ignore + retention-days: 7 + - name: Component Tests working-directory: ./frontend env: diff --git a/.github/workflows/tests-wasm.yml b/.github/workflows/tests-wasm.yml index f3e1547321..a0d8554a60 100644 --- a/.github/workflows/tests-wasm.yml +++ b/.github/workflows/tests-wasm.yml @@ -32,6 +32,9 @@ permissions: jobs: test-render-wasm: if: ${{ !github.event.pull_request.draft }} + permissions: + contents: read + pull-requests: write # coverage comment on the PR name: "Render WASM Tests" runs-on: penpot-extended-runner container: @@ -56,7 +59,64 @@ jobs: run: | ./lint + - name: Install cargo-llvm-cov + env: + CARGO_LLVM_COV_VERSION: "0.9.1" + run: | + case "$(uname -m)" in + aarch64|arm64) + arch="aarch64" + sha256="abf5f13c1520f8756d2192bfaaeadb0208f5b7eaa8cadc15bf847befa42b7360" + ;; + *) + arch="x86_64" + sha256="b3f68e625481fed9b16444174f3fa5ebcdbde4a1878803a35eabe2dcefcdc41a" + ;; + esac + archive="cargo-llvm-cov-${arch}-unknown-linux-gnu.tar.gz" + curl -fsSL --retry 3 -o "$RUNNER_TEMP/$archive" \ + "https://github.com/taiki-e/cargo-llvm-cov/releases/download/v${CARGO_LLVM_COV_VERSION}/${archive}" + echo "${sha256} $RUNNER_TEMP/$archive" | sha256sum -c - + tar -xzf "$RUNNER_TEMP/$archive" -C /usr/local/bin cargo-llvm-cov + cargo llvm-cov --version + - name: Test working-directory: ./render-wasm + env: + RENDER_WASM_COVERAGE: "true" run: | ./test + + - name: Coverage summary + if: ${{ !cancelled() && hashFiles('render-wasm/target/coverage/lcov.info') != '' }} + run: | + node scripts/coverage-summary.mjs \ + --title "Render WASM test coverage" \ + --note "Rust sources under \`render-wasm/src\`, measured by cargo-llvm-cov on the native test build." \ + --lcov render-wasm/target/coverage/lcov.info \ + > render-wasm/target/coverage/summary.md + cat render-wasm/target/coverage/summary.md >> "$GITHUB_STEP_SUMMARY" + + - name: Coverage comment + # Fork PRs get a read-only token, so only branches of this repo comment. + if: ${{ !cancelled() && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && hashFiles('render-wasm/target/coverage/lcov.info') != '' }} + continue-on-error: true + env: + GITHUB_TOKEN: ${{ github.token }} + PR_NUMBER: ${{ github.event.pull_request.number }} + HEAD_SHA: ${{ github.event.pull_request.head.sha }} + run: | + node scripts/coverage-comment.mjs \ + --project "Render WASM" \ + --lcov render-wasm/target/coverage/lcov.info \ + --llvm-json render-wasm/target/coverage/summary.json + + - name: Upload coverage report + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + if: ${{ !cancelled() }} + with: + name: render-wasm-coverage + path: render-wasm/target/coverage/ + overwrite: true + if-no-files-found: ignore + retention-days: 7 diff --git a/.gitignore b/.gitignore index 974b11f495..a3bba245a3 100644 --- a/.gitignore +++ b/.gitignore @@ -68,6 +68,7 @@ opencode.json /frontend/playwright-report/ /frontend/playwright/ui/visual-specs/ /frontend/text-editor/src/wasm/ +/frontend/coverage/ /frontend/dist/ /frontend/npm-debug.log /frontend/out/ diff --git a/.serena/memories/backend/testing.md b/.serena/memories/backend/testing.md index 671ebc1b50..3ed98a539e 100644 --- a/.serena/memories/backend/testing.md +++ b/.serena/memories/backend/testing.md @@ -13,6 +13,7 @@ JVM `clojure.test` (kaocha runner) under `backend/test/backend_tests/`. - Isolated run: `clojure -M:dev:test --focus backend-tests.my-ns-test` for a specific test namespace, or `clojure -M:dev:test --focus backend-tests.my-ns-test/my-test-var` for a specific test var. - Multiple focus symbols are supported by REPEATING the flag (kaocha accumulates them, last-wins does not apply): `clojure -M:dev:test --focus backend-tests.ns-one --focus backend-tests.ns-two` — preferred over a shell loop of isolated runs. - Regression run: `clojure -M:dev:test` to ensure no regressions in related functional areas. +- Line coverage: append the `:coverage` alias (`clojure -M:dev:test:coverage`, kaocha-cloverage). It instruments every `app.*` namespace under `src/` at load, before any test runs, so even a `--focus` run instruments them all; options live under `:cloverage/opts` in `tests.edn`, output in `target/coverage/` (lcov, HTML, and EMMA `coverage.xml` whose form counts the PR report shows as statements; cloverage measures no functions or branches) (`lcov.info`, HTML). About 2x slower and noisy with reflection warnings (instrumented forms lose type hints): never use it for normal runs. `tests-backend.yml` runs it and renders the step summary with `scripts/coverage-summary.mjs`. - If you need to filter output, tee to a temp file first: `clojure -M:dev:test 2>&1 | tee /tmp/penpot-test-output.txt`. - RPC test helpers `command!`/`management-command!` split the data map: qualified keys become server params, unqualified keys become request body params. To inject request-level context (headers, `:app.http/auth-key-id`, ip), pass a map under `:app.http/request` metadata; non-map `IRequest` stubs fall back to a dummy request. - The test system is `main/system-config` + `main/worker-config` with the diff --git a/.serena/memories/common/testing.md b/.serena/memories/common/testing.md index b18fa3904b..6d9cd754ba 100644 --- a/.serena/memories/common/testing.md +++ b/.serena/memories/common/testing.md @@ -15,6 +15,7 @@ From `common/`: - Full JS test run (always builds, build output visible): `pnpm run test` - Focus a JVM test namespace: `clojure -M:dev:test --focus common-tests.logic.variants-switch-test` - Focus a JVM test var: `clojure -M:dev:test --focus common-tests.logic.variants-switch-test/test-basic-switch` +- JVM line coverage: `clojure -M:dev:test:coverage` (kaocha-cloverage, about 2x slower; `:cloverage/opts` in `tests.edn`, which excludes `app.common.test-helpers.*`; output in `target/coverage/` (lcov, HTML, and EMMA `coverage.xml` whose form counts the PR report shows as statements; cloverage measures no functions or branches)). `scripts/test` (CI) uses it; the JS side has no coverage. - Focus a JS test namespace: `pnpm run test:quiet -- --focus common-tests.logic.comp-sync-test` - Focus a JS test var: `pnpm run test:quiet -- --focus common-tests.logic.comp-sync-test/test-sync-when-changing-attribute` - Quiet logging during a JS run: append `--log-level warn` (or `trace|debug|info|warn|error`) diff --git a/.serena/memories/critical-info.md b/.serena/memories/critical-info.md index ca15de08db..2e9c0c6f5a 100644 --- a/.serena/memories/critical-info.md +++ b/.serena/memories/critical-info.md @@ -61,6 +61,8 @@ The memory is structured in a way that you can get the critical information abou - `scripts/psql` — PostgreSQL client wrapper with devenv defaults. Companion: `scripts/db-schema` for DDL dumps. See `mem:scripts/psql`. - `scripts/taiga.py` — Fetch public issues, user stories, and tasks from the Penpot Taiga project without authentication. See `mem:scripts/taiga`. - `scripts/gh.py` — GitHub operations helper: list milestone issues, fetch PR details, compare against CHANGES.md. Requires `gh` CLI. See `mem:scripts/gh`. +- `scripts/coverage-summary.mjs` — Renders an lcov file as a markdown table grouped by source area, for `$GITHUB_STEP_SUMMARY` (`--title`, `--lcov`, optional `--note`, `--unloaded`). Used by the backend, common and frontend test workflows; module coverage commands are in `mem:backend/testing`, `mem:common/testing`, `mem:frontend/testing`. +- `scripts/coverage-comment.mjs` — Keeps one PR comment (``) with the coverage table of Backend, Common, Frontend and Render WASM, in the format of the Vitest Coverage Report Action (status, metric, %, covered/total, changed-file coverage, run/commit footer). Each test job updates its own project: the data of all three lives base64-encoded in a hidden `coverage-data` block, and the job re-reads after `SETTLE_MS` and rewrites if a concurrent job dropped its data; extra report comments from simultaneous creates are merged and deleted. Targets (`THRESHOLDS`, per project and metric, status colour only, never fail CI) are on lines only: 70 Backend, 70 Common, 50 Frontend, 40 Render WASM; other metrics get the blue dot. Statements are Clojure forms for Backend/Common (`--emma-xml`) and llvm regions for Render WASM (`--llvm-json`). Shared lcov parsing: `scripts/coverage-lcov.mjs`. The test workflows run it only for PRs from branches of this repo (job-level `pull-requests: write`, `continue-on-error`): fork PRs get a read-only token, so they only get the run-page summary. A fork-safe `workflow_run` commenter would run only from the default branch's copy of the workflow. - `scripts/project-anomalies.py` — Main-board anomaly check for a milestone (`check` writes `tmp/-ANOMALIES.md`). Bulk resolution via `scripts/gh.py`. See `mem:scripts/project-anomalies`. - `scripts/changelog.py` — Changelog checks for `mem:workflow/updating-changelog`: `boom` (generate the `:boom:` section from `breaking change` issues), `check-merged` (PR merge status), `cross-ref` (milestone PRs vs changelog section), `report` (anomaly report to CHANGES-ISSUES.md). Calls `scripts/gh.py` via subprocess. See `mem:scripts/changelog`. - `scripts/error-reports.mjs` — Query error reports via RPC API with token authentication. Supports list/get operations with filtering and pagination. See `mem:scripts/error-reports`. diff --git a/.serena/memories/frontend/testing.md b/.serena/memories/frontend/testing.md index 3bfbe08542..60fd08f945 100644 --- a/.serena/memories/frontend/testing.md +++ b/.serena/memories/frontend/testing.md @@ -51,6 +51,7 @@ From `frontend/`: - Build test target only (no run): `pnpm run build:test`. - After `build:test` has been run, run the compiled runner directly: `node target/tests/test.js [--focus ...] [--log-level ...]`. - Watch tests: `pnpm run watch:test`. +- Coverage: `pnpm run test:coverage` (builds, runs the suite under `NODE_V8_COVERAGE`, keeps its exit code). `scripts/coverage.js` maps V8 data back to `.cljs`/`.cljc` through the test build's source maps (`ast-v8-to-istanbul` + acorn) and writes `coverage/` (`lcov.info`, `coverage-summary.json`, `html/`, `unloaded.txt`); `tests-frontend.yml` renders the step summary with `scripts/coverage-summary.mjs` and uploads `coverage/` as the `frontend-coverage` artifact. `scripts/test` (CI) runs `test:coverage`, not `test`. Scope: `frontend/src/app/**` minus `app/main/ui/` (`EXCLUDED_DIRS`); namespaces no test loads are listed apart, never counted. Never pass `ignoreSourceCode` to `convert`: CLJS maps point past source lines and it throws. Trust line % over branch % (branches are of the generated JS). New frontend test namespaces must be required/listed in `frontend_tests/runner.cljs`; new vars in existing namespaces need no runner change. diff --git a/.serena/memories/render-wasm/core.md b/.serena/memories/render-wasm/core.md index c3b8dd1db7..8102540a80 100644 --- a/.serena/memories/render-wasm/core.md +++ b/.serena/memories/render-wasm/core.md @@ -34,6 +34,7 @@ From `render-wasm/`: - Clean one target: `./clean [frontend|export]`; never run root `cargo clean` on the shared `target/`. - Watch rebuild: `./watch [frontend|export]`; its initial and change-triggered builds use `./build`. - Rust tests: `./test` or `cargo test `. +- Rust coverage: `RENDER_WASM_COVERAGE=1 ./test` runs the same tests under `cargo llvm-cov` (needs `cargo-llvm-cov` on PATH; the script adds `llvm-tools-preview`) and writes `target/coverage/` (`lcov.info` with absolute paths, `summary.json` llvm export totals, `html/`). Native build only: code behind wasm-only `cfg` is not measured. `tests-wasm.yml` downloads a pinned, checksum-verified `cargo-llvm-cov` release because the devenv image lacks it. - Cross-cutting testing principles and anti-patterns: `mem:testing`. - Lint: `./lint`. - Format check: `cargo fmt --check`. diff --git a/backend/deps.edn b/backend/deps.edn index b513f50eee..e0207ec7d0 100644 --- a/backend/deps.edn +++ b/backend/deps.edn @@ -95,6 +95,11 @@ :jvm-opts ["-Dlog4j2.configurationFile=log4j2-devenv-repl.xml"] :extra-deps {lambdaisland/kaocha {:mvn/version "1.91.1392"}}} + ;; Use after :test (`-M:dev:test:coverage`) to run the suite with cloverage. + :coverage + {:main-opts ["-m" "kaocha.runner" "--plugin" "cloverage"] + :extra-deps {lambdaisland/kaocha-cloverage {:mvn/version "1.1.89"}}} + :outdated {:extra-deps {com.github.liquidz/antq {:mvn/version "2.11.1276"}} :main-opts ["-m" "antq.core"]} diff --git a/backend/tests.edn b/backend/tests.edn index 7af172c443..f4d0b7a559 100644 --- a/backend/tests.edn +++ b/backend/tests.edn @@ -3,4 +3,16 @@ [{:id :unit :test-paths ["test" "src"] :ns-patterns [".*-test$"] - :kaocha/reporter [kaocha.report/dots]}]} + :kaocha/reporter [kaocha.report/dots]}] + + ;; Only read when the cloverage plugin is on (`:coverage` alias). + :cloverage/opts {:src-ns-path ["src"] + :ns-regex ["^app\\..*"] + :output "target/coverage" + :lcov? true + ;; EMMA XML carries the form counts the PR report shows as statements. + :emma-xml? true + :html? true + :summary? true + :codecov? false + :fail-threshold 0}} diff --git a/common/deps.edn b/common/deps.edn index e7ed617f90..c0b3719783 100644 --- a/common/deps.edn +++ b/common/deps.edn @@ -76,6 +76,11 @@ {:main-opts ["-m" "kaocha.runner"] :extra-deps {lambdaisland/kaocha {:mvn/version "1.91.1392"}}} + ;; Use after :test (`-M:dev:test:coverage`) to run the suite with cloverage. + :coverage + {:main-opts ["-m" "kaocha.runner" "--plugin" "cloverage"] + :extra-deps {lambdaisland/kaocha-cloverage {:mvn/version "1.1.89"}}} + :shadow-cljs {:main-opts ["-m" "shadow.cljs.devtools.cli"] :jvm-opts ["--sun-misc-unsafe-memory-access=allow"]} diff --git a/common/scripts/test b/common/scripts/test index b22dbff38d..6051d86d20 100755 --- a/common/scripts/test +++ b/common/scripts/test @@ -3,4 +3,4 @@ set -ex pnpm install; pnpm run test; -clojure -M:dev:test; +clojure -M:dev:test:coverage; diff --git a/common/tests.edn b/common/tests.edn index 0a0582fed6..b13214b709 100644 --- a/common/tests.edn +++ b/common/tests.edn @@ -1,4 +1,17 @@ #kaocha/v1 {:tests [{:id :unit :test-paths ["test"]}] - :kaocha/reporter [kaocha.report/dots]} + :kaocha/reporter [kaocha.report/dots] + + ;; Only read when the cloverage plugin is on (`:coverage` alias). + :cloverage/opts {:src-ns-path ["src"] + :ns-regex ["^app\\..*"] + :ns-exclude-regex ["^app\\.common\\.test-helpers\\..*"] + :output "target/coverage" + :lcov? true + ;; EMMA XML carries the form counts the PR report shows as statements. + :emma-xml? true + :html? true + :summary? true + :codecov? false + :fail-threshold 0}} diff --git a/frontend/package.json b/frontend/package.json index fd9bed22ea..69ff0c0e7a 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -36,6 +36,7 @@ "build:test": "pnpm run build:wasm && clojure -M:dev:shadow-cljs compile test", "test": "pnpm run build:test && node target/tests/test.js", "test:quiet": "node ./scripts/test-quiet.js", + "test:coverage": "pnpm run build:test && node ./scripts/coverage.js", "test:storybook": "vitest run --project=storybook", "watch:test": "mkdir -p target/tests && concurrently \"clojure -M:dev:shadow-cljs watch test\" \"nodemon -C -d 2 -w target/tests --exec 'node target/tests/test.js'\"", "test:e2e": "playwright test --project default", @@ -67,7 +68,11 @@ "@vitest/browser": "5.0.3", "@vitest/browser-playwright": "5.0.3", "@vitest/coverage-v8": "5.0.3", + "@vitest/istanbul-lib-coverage": "1.0.2", + "@vitest/istanbul-lib-report": "1.0.2", "@zip.js/zip.js": "2.8.34", + "acorn": "8.19.0", + "ast-v8-to-istanbul": "1.0.7", "autoprefixer": "^10.6.1", "compression": "^1.8.2", "concurrently": "^10.0.5", diff --git a/frontend/pnpm-lock.yaml b/frontend/pnpm-lock.yaml index e054fa7f2a..bd9b4f38f7 100644 --- a/frontend/pnpm-lock.yaml +++ b/frontend/pnpm-lock.yaml @@ -252,9 +252,21 @@ importers: '@vitest/coverage-v8': specifier: 5.0.3 version: 5.0.3(@vitest/browser@5.0.3)(vitest@5.0.3) + '@vitest/istanbul-lib-coverage': + specifier: 1.0.2 + version: 1.0.2 + '@vitest/istanbul-lib-report': + specifier: 1.0.2 + version: 1.0.2 '@zip.js/zip.js': specifier: 2.8.34 version: 2.8.34(patch_hash=7b556bbd426f152eb086f0126a53900e369a95cf64357c380b7c8d8e940c3d95) + acorn: + specifier: 8.19.0 + version: 8.19.0 + ast-v8-to-istanbul: + specifier: 1.0.7 + version: 1.0.7 autoprefixer: specifier: ^10.6.1 version: 10.6.1(postcss@8.5.29) diff --git a/frontend/scripts/coverage.js b/frontend/scripts/coverage.js new file mode 100644 index 0000000000..e56a3baf4a --- /dev/null +++ b/frontend/scripts/coverage.js @@ -0,0 +1,139 @@ +// Runs the compiled unit test bundle with V8 coverage enabled and writes +// Istanbul reports mapped back to the ClojureScript sources through the +// source maps of the shadow-cljs test build. +// +// Expects the test bundle to be built (`pnpm run build:test`). Extra +// arguments are passed to the test runner. Exits with the status of the +// tests. Reports land in `coverage/`, with `unloaded.txt` listing the +// namespaces in scope that no test loads (`scripts/coverage-summary.mjs` +// renders both as markdown). + +import { spawnSync } from "node:child_process"; +import fs from "node:fs"; +import path from "node:path"; +import { fileURLToPath, pathToFileURL } from "node:url"; + +import { parse } from "acorn"; +import { convert } from "ast-v8-to-istanbul"; +import { createCoverageMap } from "@vitest/istanbul-lib-coverage"; +import { create, createContext } from "@vitest/istanbul-lib-report"; + +const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); +const REPO_ROOT = path.resolve(ROOT, ".."); +const TEST_BUNDLE = path.join(ROOT, "target/tests/test.js"); +const RUNTIME_DIR = path.join(ROOT, "target/tests/cljs-runtime"); +const RAW_DIR = path.join(ROOT, "target/coverage-raw"); +const REPORT_DIR = path.join(ROOT, "coverage"); +const SOURCE_DIR = path.join(ROOT, "src"); + +// UI components are left out: coverage measures the logic namespaces. +const EXCLUDED_DIRS = ["app/main/ui/"]; + +function inScope(relPath) { + return ( + /^app\/.*\.clj[sc]$/.test(relPath) && + !EXCLUDED_DIRS.some((dir) => relPath.startsWith(dir)) + ); +} + +function runTests(args) { + fs.rmSync(RAW_DIR, { recursive: true, force: true }); + const result = spawnSync("node", [TEST_BUNDLE, ...args], { + stdio: "inherit", + env: { ...process.env, NODE_V8_COVERAGE: RAW_DIR }, + }); + return result.status ?? 1; +} + +// Resolves the sources of a source map to absolute paths under `src/`; +// returns null when the map has no source in scope. +function resolveSources(sourceMap) { + let anyInScope = false; + const sources = sourceMap.sources.map((source) => { + const relPath = path.join(sourceMap.sourceRoot ?? "", source); + if (inScope(relPath) && fs.existsSync(path.join(SOURCE_DIR, relPath))) { + anyInScope = true; + return path.join(SOURCE_DIR, relPath); + } + return source; + }); + return anyInScope ? { ...sourceMap, sources, sourceRoot: "" } : null; +} + +async function collectCoverage() { + const coverageMap = createCoverageMap({}); + const runtimeUrl = pathToFileURL(RUNTIME_DIR).href + "/"; + + for (const rawFile of fs.readdirSync(RAW_DIR)) { + const raw = JSON.parse( + fs.readFileSync(path.join(RAW_DIR, rawFile), "utf8"), + ); + + for (const script of raw.result) { + if (!script.url.startsWith(runtimeUrl)) continue; + + const file = fileURLToPath(script.url); + const mapFile = file + ".map"; + if (!fs.existsSync(mapFile)) continue; + + const sourceMap = resolveSources( + JSON.parse(fs.readFileSync(mapFile, "utf8")), + ); + if (!sourceMap) continue; + + const code = fs.readFileSync(file, "utf8"); + const data = await convert({ + ast: parse(code, { ecmaVersion: "latest", sourceType: "module" }), + code, + wrapperLength: 0, + coverage: { url: script.url, functions: script.functions }, + sourceMap, + }); + + for (const [sourcePath, fileCoverage] of Object.entries(data)) { + if (inScope(path.relative(SOURCE_DIR, sourcePath))) { + coverageMap.merge({ [sourcePath]: fileCoverage }); + } + } + } + } + return coverageMap; +} + +function listScopeFiles(dir = path.join(SOURCE_DIR, "app")) { + return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => { + const fullPath = path.join(dir, entry.name); + if (entry.isDirectory()) return listScopeFiles(fullPath); + return inScope(path.relative(SOURCE_DIR, fullPath)) ? [fullPath] : []; + }); +} + +function writeReports(coverageMap) { + fs.rmSync(REPORT_DIR, { recursive: true, force: true }); + const context = createContext({ + dir: REPORT_DIR, + coverageMap, + defaultSummarizer: "nested", + }); + create("lcovonly", { projectRoot: REPO_ROOT }).execute(context); + create("json-summary").execute(context); + create("html", { subdir: "html" }).execute(context); + create("text-summary").execute(context); +} + +const testStatus = runTests(process.argv.slice(2)); + +const coverageMap = await collectCoverage(); +const loaded = new Set(coverageMap.files()); +const unloaded = listScopeFiles() + .filter((file) => !loaded.has(file)) + .sort(); + +writeReports(coverageMap); +fs.writeFileSync( + path.join(REPORT_DIR, "unloaded.txt"), + unloaded.map((file) => path.relative(REPO_ROOT, file) + "\n").join(""), +); +fs.rmSync(RAW_DIR, { recursive: true, force: true }); + +process.exit(testStatus); diff --git a/frontend/scripts/test b/frontend/scripts/test index c61c28b543..c53b9757c8 100755 --- a/frontend/scripts/test +++ b/frontend/scripts/test @@ -9,7 +9,7 @@ pushd ../render-wasm; popd pnpm run lint:scss; -pnpm run test; +pnpm run test:coverage; # Mousetrap JS unit tests (node:test, zero deps) pushd packages/mousetrap; diff --git a/render-wasm/test b/render-wasm/test index 3f680ac09a..a46b09c50b 100755 --- a/render-wasm/test +++ b/render-wasm/test @@ -17,9 +17,25 @@ pushd "$_SCRIPT_DIR" > /dev/null node --test scripts/cargo-build.test.cjs || exit $? setup -cargo test --bin render_wasm -- --show-output -RESULT=$? +# With RENDER_WASM_COVERAGE set, the same tests run under cargo-llvm-cov +# (must be on PATH) and leave lcov, a JSON summary and HTML in +# target/coverage/. +if [ -n "${RENDER_WASM_COVERAGE:-}" ]; then + rustup component add llvm-tools-preview --toolchain "$RUST_VERSION" + _COV_ARGS=(--target "$CARGO_BUILD_TARGET") + cargo llvm-cov clean --workspace + # Keep going on failure so the reports still get written. + RESULT=0 + cargo llvm-cov --no-report "${_COV_ARGS[@]}" --bin render_wasm -- --show-output || RESULT=$? + mkdir -p target/coverage + cargo llvm-cov report "${_COV_ARGS[@]}" --lcov --output-path target/coverage/lcov.info + cargo llvm-cov report "${_COV_ARGS[@]}" --json --summary-only --output-path target/coverage/summary.json + cargo llvm-cov report "${_COV_ARGS[@]}" --html --output-dir target/coverage +else + cargo test --bin render_wasm -- --show-output + RESULT=$? +fi popd > /dev/null exit $RESULT diff --git a/scripts/coverage-comment.mjs b/scripts/coverage-comment.mjs new file mode 100644 index 0000000000..fd56c10bd3 --- /dev/null +++ b/scripts/coverage-comment.mjs @@ -0,0 +1,373 @@ +#!/usr/bin/env node +// Keeps one pull request comment with the coverage report of every project +// (backend, common, frontend, render-wasm). Each test job runs it with its own +// lcov file. +// The comment stores the data of every project in a hidden block, so a run +// updates its own project and renders the whole report again. +// +// Usage: +// node scripts/coverage-comment.mjs --project --lcov +// [--prefix ] [--json-summary ] [--emma-xml ] +// [--llvm-json ] +// [--unloaded ] +// +// --prefix prepended to lcov paths relative to the project directory +// --json-summary Istanbul json-summary whose totals replace the lcov ones +// (it adds statements) +// --emma-xml cloverage EMMA report; its form counts become statements +// --llvm-json `cargo llvm-cov --json --summary-only` output whose totals +// replace the lcov ones (regions become statements) +// --unloaded repo-relative sources no test loads, one per line +// +// Env: GITHUB_TOKEN, GITHUB_REPOSITORY, PR_NUMBER and HEAD_SHA; also +// GITHUB_API_URL, GITHUB_SERVER_URL, GITHUB_RUN_ID and GITHUB_RUN_NUMBER, +// which Actions sets. + +import fs from "node:fs"; +import path from "node:path"; +import { setTimeout as sleep } from "node:timers/promises"; +import { parseArgs } from "node:util"; + +import { addTotals, emptyTotals, parseLcov } from "./coverage-lcov.mjs"; + +const PROJECTS = ["Backend", "Common", "Frontend", "Render WASM"]; +const METRICS = [ + ["lines", "Lines"], + ["statements", "Statements"], + ["functions", "Functions"], + ["branches", "Branches"], +]; +// Minimum percentage per project and metric; a metric without one gets the +// blue status. +const THRESHOLDS = { + Backend: { lines: 70 }, + Common: { lines: 70 }, + Frontend: { lines: 50 }, + "Render WASM": { lines: 40 }, +}; +const MAX_CHANGED_FILES = 100; +const MAX_ATTEMPTS = 3; +// Time to let a concurrent update of another project land before checking +// that this project's data survived it. +const SETTLE_MS = Number(process.env.COVERAGE_COMMENT_SETTLE_MS ?? 10000); + +const MARKER = ""; +const DATA_RE = //; + +const { values: opts } = parseArgs({ + options: { + project: { type: "string" }, + lcov: { type: "string" }, + prefix: { type: "string", default: "" }, + "json-summary": { type: "string" }, + "emma-xml": { type: "string" }, + "llvm-json": { type: "string" }, + unloaded: { type: "string" }, + }, +}); + +const env = process.env; +for (const [name, value] of Object.entries({ + "--project": PROJECTS.includes(opts.project), + "--lcov": opts.lcov, + GITHUB_TOKEN: env.GITHUB_TOKEN, + GITHUB_REPOSITORY: env.GITHUB_REPOSITORY, + PR_NUMBER: env.PR_NUMBER, + HEAD_SHA: env.HEAD_SHA, +})) { + if (!value) { + console.error( + `Missing or invalid ${name}. Usage: coverage-comment.mjs ` + + `--project <${PROJECTS.join("|")}> --lcov [--prefix ] ` + + "[--json-summary ] [--emma-xml ] [--llvm-json ] " + + "[--unloaded ]", + ); + process.exit(2); + } +} + +const API = `${env.GITHUB_API_URL ?? "https://api.github.com"}/repos/${env.GITHUB_REPOSITORY}`; +const SERVER = env.GITHUB_SERVER_URL ?? "https://github.com"; + +class NotFound extends Error {} + +async function request(method, url, body) { + const response = await fetch(url, { + method, + headers: { + Accept: "application/vnd.github+json", + Authorization: `Bearer ${env.GITHUB_TOKEN}`, + "X-GitHub-Api-Version": "2022-11-28", + ...(body ? { "Content-Type": "application/json" } : {}), + }, + body: body ? JSON.stringify(body) : undefined, + }); + if (response.status === 404) throw new NotFound(`${method} ${url}: 404`); + if (!response.ok) { + throw new Error( + `${method} ${url}: ${response.status} ${await response.text()}`, + ); + } + return response.status === 204 ? null : response.json(); +} + +async function getAll(path) { + const items = []; + for (let page = 1; ; page++) { + const batch = await request( + "GET", + `${API}${path}?per_page=100&page=${page}`, + ); + items.push(...batch); + if (batch.length < 100) return items; + } +} + +// --- Coverage of this project ------------------------------------------- + +function readList(file) { + return file && fs.existsSync(file) + ? fs.readFileSync(file, "utf8").split("\n").filter(Boolean) + : []; +} + +function totalsOf(records) { + const totals = emptyTotals(); + records.forEach((record) => addTotals(totals, record)); + const result = {}; + for (const [key] of METRICS) { + if (totals[key]?.total > 0) result[key] = totals[key]; + } + if (opts["json-summary"]) { + const summary = JSON.parse(fs.readFileSync(opts["json-summary"], "utf8")); + for (const [key] of METRICS) { + const { covered, total } = summary.total[key] ?? {}; + if (total > 0) result[key] = { covered, total }; + } + } + if (opts["llvm-json"]) { + Object.assign( + result, + llvmTotals(JSON.parse(fs.readFileSync(opts["llvm-json"], "utf8"))), + ); + } + if (opts["emma-xml"]) { + const forms = emmaForms(fs.readFileSync(opts["emma-xml"], "utf8")); + if (forms?.total > 0) result.statements = forms; + } + return result; +} + +// Form counts of the whole report, from the `block, %` entry of the `total` +// element: ``. +function emmaForms(xml) { + const match = xml.match( + /[\s\S]*? 0) result[key] = { covered, total: count }; + } + return result; +} + +// llvm-cov writes absolute paths; the other tools write paths relative to the +// repository or to the project directory. +function repoPath(lcovPath) { + if (path.isAbsolute(lcovPath)) return path.relative(process.cwd(), lcovPath); + return lcovPath.startsWith(opts.prefix) ? lcovPath : opts.prefix + lcovPath; +} + +async function projectData() { + const records = parseLcov(fs.readFileSync(opts.lcov, "utf8")); + const byPath = new Map(records.map((r) => [repoPath(r.path), r])); + const unloaded = new Set(readList(opts.unloaded)); + + const prFiles = await getAll(`/pulls/${env.PR_NUMBER}/files`); + const changed = prFiles + .filter((f) => f.status !== "removed") + .map((f) => f.filename) + .filter((file) => byPath.has(file) || unloaded.has(file)) + .sort() + .map((file) => + byPath.has(file) + ? { file, lines: byPath.get(file).lines } + : { file, unloaded: true }, + ); + + return { + sha: env.HEAD_SHA, + runId: Number(env.GITHUB_RUN_ID ?? 0), + runNumber: env.GITHUB_RUN_NUMBER ?? env.GITHUB_RUN_ID ?? "", + totals: totalsOf(records), + changed, + }; +} + +// --- Rendering ------------------------------------------------------------ + +function pct({ covered, total }) { + return `${Math.round((10000 * covered) / total) / 100}%`; +} + +function statusOf(threshold, cov) { + if (threshold === undefined) return "🔵"; + return (100 * cov.covered) / cov.total >= threshold ? "🟢" : "🔴"; +} + +function metricRow(threshold, label, cov) { + const target = threshold === undefined ? "" : ` (🎯 ${threshold}%)`; + return ( + ` ${statusOf(threshold, cov)} ${label} ` + + `${pct(cov)}${target} ` + + `${cov.covered} / ${cov.total} ` + ); +} + +function fileCoverage(changed) { + if (changed.length === 0) return "No changed files found."; + const shown = changed.slice(0, MAX_CHANGED_FILES); + const rows = shown.map(({ file, lines, unloaded }) => + unloaded + ? ` ${file} no test loads it ` + : ` ${file} ${lines.total ? pct(lines) : "-"} ${lines.covered} / ${lines.total} `, + ); + const more = + changed.length > shown.length + ? `

${changed.length - shown.length} more files not shown.

` + : ""; + return ( + ` ` + + ` ${rows.join(" ")}
File LinesCovered / Total
${more}` + ); +} + +function renderProject(name, data) { + if (!data) { + return `

${name}

\n

Its tests have not run on this pull request.

`; + } + const rows = METRICS.filter(([key]) => data.totals[key]).map(([key, label]) => + metricRow(THRESHOLDS[name]?.[key], label, data.totals[key]), + ); + const runUrl = `${SERVER}/${env.GITHUB_REPOSITORY}/actions/runs/${data.runId}`; + const commitUrl = `${SERVER}/${env.GITHUB_REPOSITORY}/commit/${data.sha}`; + return [ + `

${name}

`, + ` ` + + ` ` + + ` ${rows.join(" ")}
Status CategoryPercentage Covered / Total
`, + `
File Coverage${fileCoverage(data.changed)}
`, + `Generated in workflow #${data.runNumber} ` + + `for commit ${data.sha.slice(0, 7)}`, + ].join("\n"); +} + +function render(all) { + const encoded = Buffer.from(JSON.stringify(all)).toString("base64"); + return [ + MARKER, + "

Coverage Report

", + ...PROJECTS.map((name) => renderProject(name, all[name])), + "Backend and Common are measured by cloverage, which counts lines " + + "and Clojure forms (shown as statements) but not functions or branches. " + + "Render WASM is measured by cargo-llvm-cov on the native test build; " + + "its statements are llvm regions.", + ``, + "", + ].join("\n\n"); +} + +// --- Comment update ------------------------------------------------------- + +function dataOf(comment) { + const match = comment.body?.match(DATA_RE); + if (!match) return {}; + try { + return JSON.parse(Buffer.from(match[1], "base64").toString("utf8")); + } catch { + return {}; + } +} + +async function reportComments() { + const comments = await getAll(`/issues/${env.PR_NUMBER}/comments`); + return comments + .filter((c) => c.user?.type === "Bot" && c.body?.startsWith(MARKER)) + .sort((a, b) => a.id - b.id); +} + +// Merges the data of every report comment, keeping the latest run of each +// project. +function mergeData(comments) { + const merged = {}; + for (const comment of comments) { + for (const [name, data] of Object.entries(dataOf(comment))) { + if (PROJECTS.includes(name) && (merged[name]?.runId ?? -1) < data.runId) { + merged[name] = data; + } + } + } + return merged; +} + +// Writes the report on the oldest report comment and drops the others, which +// appear when two jobs create the comment at the same time. +async function write(comments, all) { + const body = render(all); + if (comments.length === 0) { + await request("POST", `${API}/issues/${env.PR_NUMBER}/comments`, { body }); + return; + } + const [primary, ...extra] = comments; + await request("PATCH", `${API}/issues/comments/${primary.id}`, { body }); + for (const comment of extra) { + // Another job may have dropped it already. + await request("DELETE", `${API}/issues/comments/${comment.id}`).catch( + (error) => { + if (!(error instanceof NotFound)) throw error; + }, + ); + } +} + +const mine = await projectData(); + +for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) { + const comments = await reportComments(); + const all = mergeData(comments); + if ((all[opts.project]?.runId ?? -1) > mine.runId) { + console.log(`A newer run already reported ${opts.project}.`); + break; + } + all[opts.project] = mine; + try { + await write(comments, all); + } catch (error) { + // The comment vanished under a concurrent update; the check below retries. + if (!(error instanceof NotFound)) throw error; + } + + await sleep(SETTLE_MS * (1 + Math.random() / 2)); + const after = await reportComments(); + const saved = mergeData(after)[opts.project]; + if (after.length === 1 && (saved?.runId ?? -1) >= mine.runId) { + console.log(`Coverage report updated for ${opts.project}.`); + break; + } + if (attempt === MAX_ATTEMPTS) { + throw new Error(`Could not keep the ${opts.project} coverage report.`); + } + console.log(`Concurrent update detected; writing ${opts.project} again.`); +} diff --git a/scripts/coverage-lcov.mjs b/scripts/coverage-lcov.mjs new file mode 100644 index 0000000000..e83d8e62e1 --- /dev/null +++ b/scripts/coverage-lcov.mjs @@ -0,0 +1,49 @@ +// lcov parsing shared by the coverage scripts. + +const COUNTERS = { + LF: "lines", + LH: "lines", + FNF: "functions", + FNH: "functions", + BRF: "branches", + BRH: "branches", +}; + +export function emptyTotals() { + return { + files: 0, + lines: { covered: 0, total: 0 }, + functions: { covered: 0, total: 0 }, + branches: { covered: 0, total: 0 }, + }; +} + +// One record per source file: `{path, lines, functions, branches}`, each +// metric as `{covered, total}`. +export function parseLcov(text) { + const records = []; + let current = null; + for (const line of text.split("\n")) { + const sep = line.indexOf(":"); + const tag = sep === -1 ? line.trim() : line.slice(0, sep); + const value = line.slice(sep + 1).trim(); + if (tag === "SF") { + current = { path: value, ...emptyTotals() }; + } else if (tag === "end_of_record" && current) { + records.push(current); + current = null; + } else if (current && tag in COUNTERS) { + const key = tag.endsWith("F") ? "total" : "covered"; + current[COUNTERS[tag]][key] = Number(value); + } + } + return records; +} + +export function addTotals(totals, record) { + totals.files += 1; + for (const key of ["lines", "functions", "branches"]) { + totals[key].covered += record[key].covered; + totals[key].total += record[key].total; + } +} diff --git a/scripts/coverage-summary.mjs b/scripts/coverage-summary.mjs new file mode 100644 index 0000000000..36ff582694 --- /dev/null +++ b/scripts/coverage-summary.mjs @@ -0,0 +1,99 @@ +#!/usr/bin/env node +// Prints a markdown coverage summary of an lcov file, grouped by source area. +// +// Usage: +// node scripts/coverage-summary.mjs --title --lcov <file> +// [--note <text>] [--unloaded <file>] +// +// `--unloaded` names a file listing, one per line, the sources no test loaded; +// they are shown apart and never counted. Meant to be appended to +// `$GITHUB_STEP_SUMMARY`. + +import fs from "node:fs"; +import { parseArgs } from "node:util"; + +import { addTotals, emptyTotals, parseLcov } from "./coverage-lcov.mjs"; + +const { values: opts } = parseArgs({ + options: { + title: { type: "string" }, + lcov: { type: "string" }, + note: { type: "string" }, + unloaded: { type: "string" }, + }, +}); + +if (!opts.title || !opts.lcov) { + console.error( + "Usage: coverage-summary.mjs --title <title> --lcov <file> [--note <text>] [--unloaded <file>]", + ); + process.exit(2); +} + +// Path from `app/` on: `app/main/<dir>` and `app/common/<dir>` group one +// level deeper than the rest, which group by `app/<dir>`. +function areaOf(filePath) { + const parts = filePath.replace(/^.*?\bsrc\//, "").split("/"); + const depth = + ["main", "common"].includes(parts[1]) && parts.length > 3 ? 3 : 2; + return parts.slice(0, Math.min(depth, parts.length - 1)).join("/") || "src"; +} + +function percent({ covered, total }) { + return total === 0 ? "-" : `${((100 * covered) / total).toFixed(1)}%`; +} + +function row(name, t, metrics) { + const cells = metrics.map((key) => percent(t[key])); + return `| ${name} | ${t.files} | ${cells.join(" | ")} |`; +} + +const records = parseLcov(fs.readFileSync(opts.lcov, "utf8")); +const areas = new Map(); +const total = emptyTotals(); +for (const record of records) { + const area = areaOf(record.path); + if (!areas.has(area)) areas.set(area, emptyTotals()); + addTotals(areas.get(area), record); + addTotals(total, record); +} + +// Some tools (cloverage) report lines only; metrics with no data are left out. +const metrics = ["lines", "functions", "branches"].filter( + (key) => total[key].total > 0, +); +const headers = { + lines: "Lines", + functions: "Functions", + branches: "Branches", +}; + +const unloaded = + opts.unloaded && fs.existsSync(opts.unloaded) + ? fs.readFileSync(opts.unloaded, "utf8").split("\n").filter(Boolean) + : []; + +const out = [`## ${opts.title}`, ""]; +if (opts.note) out.push(opts.note, ""); +out.push( + `**${percent(total.lines)}** of lines covered (${total.lines.covered} of ${total.lines.total}).`, + "", + `| Area | Files | ${metrics.map((key) => headers[key]).join(" | ")} |`, + `| --- | ---: | ${metrics.map(() => "---:").join(" | ")} |`, + ...[...areas.keys()] + .sort() + .map((area) => row(area, areas.get(area), metrics)), + row("**Total**", total, metrics), + "", +); +if (unloaded.length > 0) { + out.push( + `<details><summary>${unloaded.length} sources no test loads (not counted above)</summary>`, + "", + ...unloaded.map((file) => `- \`${file}\``), + "", + "</details>", + "", + ); +} +console.log(out.join("\n")); From b76eaa1f5c433c77898a1be2e9654b0b4dfb6883 Mon Sep 17 00:00:00 2001 From: Andrey Antukh <niwi@niwi.nz> Date: Wed, 18 Nov 2026 17:58:41 +0000 Subject: [PATCH 05/10] :books: Switch agent tooling to @-mentions for skills Agent skills are invoked directly with @-mentions, so the slash-command wrappers that exposed them as /commands are no longer needed. Update .agents/README.md and every skill that references another skill to use the @ syntax, and delete the six .opencode/commands/ dispatcher files. AI-assisted-by: hy4-flash-free --- .agents/README.md | 50 ++++++++++----------- .agents/skills/create-pr/SKILL.md | 4 +- .agents/skills/implement-plan/SKILL.md | 10 ++--- .agents/skills/make-a-plan/SKILL.md | 10 ++--- .agents/skills/planner/SKILL.md | 6 +-- .agents/skills/review-code/SKILL.md | 4 +- .agents/skills/review-plan/SKILL.md | 12 ++--- .agents/skills/ste/SKILL.md | 4 +- .opencode/commands/create-pr.md | 10 ----- .opencode/commands/implement-plan.md | 10 ----- .opencode/commands/make-a-plan.md | 10 ----- .opencode/commands/resolve-git-conflicts.md | 6 --- .opencode/commands/review-code.md | 10 ----- .opencode/commands/review-plan.md | 10 ----- 14 files changed, 50 insertions(+), 106 deletions(-) delete mode 100644 .opencode/commands/create-pr.md delete mode 100644 .opencode/commands/implement-plan.md delete mode 100644 .opencode/commands/make-a-plan.md delete mode 100644 .opencode/commands/resolve-git-conflicts.md delete mode 100644 .opencode/commands/review-code.md delete mode 100644 .opencode/commands/review-plan.md diff --git a/.agents/README.md b/.agents/README.md index 371444a89d..b102aff013 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -337,28 +337,28 @@ small. To delegate without switching models, delegate to `general`. report with your intent: "investigate this and find the possible cause", "investigate and tell me where this points", or "does this still apply?". Explore until you and the agent roughly agree on the problem. -2. **Write the plan.** Run `/make-a-plan` — it executes in Build mode. - If you need to step in and answer something yourself, press TAB to - leave Build mode. Use Plan mode only when you want a hard guarantee - that the agent modifies no file under any circumstance. If you +2. **Write the plan.** Invoke `@make-a-plan`. Skills use the current agent; + select Build mode first when the skill needs to write files. Use Plan mode + only when you want a hard guarantee that the agent modifies no file under + any circumstance. If you explored with a weaker model but want a stronger one to write the plan, switch models first or delegate: - `/make-a-plan delegate to @engineer-glm`. + `@make-a-plan delegate to @engineer-glm`. 3. **Iterate on the plan.** The plan is saved to `.agents/plans/`, so you - never depend on LLM memory: read the file directly, or run `/review-plan` + never depend on LLM memory: read the file directly, or invoke `@review-plan` for a second opinion (delegation works here too). Complex plans deserve a review; simple ones can skip it. -4. **Execute.** Run `/implement-plan`. It first prints the full picture — +4. **Execute.** Invoke `@implement-plan`. It first prints the full picture — whether it will create an issue and a branch, the execution style, and a task checklist — and waits for your go-ahead. Say "step by step" to stop after each task (one commit per task) so you can verify as it goes; the default runs all tasks with one final commit. -5. **Land the work.** When it finishes, either push yourself and run - `/create-pr`, or loop `/review-code` → `/make-a-plan` → - `/implement-plan` until the findings are addressed, then push and - `/create-pr`. Nothing pushes for you — you always push from your shell. +5. **Land the work.** When it finishes, either push yourself and invoke + `@create-pr`, or loop `@review-code` → `@make-a-plan` → + `@implement-plan` until the findings are addressed, then push and invoke + `@create-pr`. Nothing pushes for you — you always push from your shell. -> Note: `/implement-plan` checks the current branch. On a base branch +> Note: `@implement-plan` checks the current branch. On a base branch > (`main`, `develop`, `staging`) it creates a GitHub issue and a branch > `issue-NNNN`; on an existing feature branch it continues there and > creates nothing. The pre-run summary tells you which applies. Read the @@ -367,14 +367,14 @@ small. To delegate without switching models, delegate to `general`. ### Big feature with multiple plans -When the work is too large for a single plan, tell `/make-a-plan` +When the work is too large for a single plan, tell `@make-a-plan` up front: produce a high-level roadmap where each task will get its own execution plan, and the roadmap doubles as the progress tracker. From there the flow mirrors the issue flow above, one level down: -take each roadmap task in turn, write its own plan (`/make-a-plan`, +take each roadmap task in turn, write its own plan (`@make-a-plan`, delegating when it helps), review it when the task is complex -(`/review-plan`), implement it (`/implement-plan`), and mark progress +(`@review-plan`), implement it (`@implement-plan`), and mark progress on the roadmap as you land each piece. ### Plan file naming (base + derivatives) @@ -392,7 +392,7 @@ keeps everything adjacent in `ls`: `2026-09-20-upload-pipeline-roadmap--task-01-chunk-upload.md` - Chained: `...--task-02-gc--review-01.md` -While a plan is still unimplemented, `/make-a-plan` revises it in +While a plan is still unimplemented, `@make-a-plan` revises it in place. Once implemented and reviewed, it writes a new followup file. Full rules live in the `planner` skill. @@ -401,11 +401,11 @@ Full rules live in the `planner` skill. Every plan carries `Status: draft | reviewed | done` plus an append-only `Review Log` (UTC ISO 8601, one line per entry): -- `draft` — fresh from `/make-a-plan`. -- `reviewed` — review feedback incorporated. `/review-plan` stays - read-only; only your explicit "apply" makes `/make-a-plan` apply +- `draft` — fresh from `@make-a-plan`. +- `reviewed` — review feedback incorporated. `@review-plan` stays + read-only; only your explicit "apply" makes `@make-a-plan` apply the changes, flip the status, and log one line. -- `done` — `/implement-plan` closes it on completion, logging the +- `done` — `@implement-plan` closes it on completion, logging the issue URL when one exists (never commit hashes). A plan approved with no changes goes `draft` → `done` directly. @@ -516,11 +516,11 @@ JSON, REPL access, and so on. ### A typical round -1. `/make-a-plan` — you get a plan and a saved file in `.agents/plans/`. -2. `/review-plan` — a second opinion; approve or request changes. -3. `/implement-plan` — the code gets written and committed. Starting from a base branch, it also opens the GitHub issue and the `issue-NNNN` branch; the plans that follow continue on that same branch. -4. `/review-code` — a reviewer checks the commit. -5. `/create-pr` — the branch goes up as a pull request. +1. `@make-a-plan` — you get a plan and a saved file in `.agents/plans/`. +2. `@review-plan` — a second opinion; approve or request changes. +3. `@implement-plan` — the code gets written and committed. Starting from a base branch, it also opens the GitHub issue and the `issue-NNNN` branch; the plans that follow continue on that same branch. +4. `@review-code` — a reviewer checks the commit. +5. `@create-pr` — the branch goes up as a pull request. Every step also works on its own, and you can always say what you want in plain words — the agents pick the right skill from what you say. diff --git a/.agents/skills/create-pr/SKILL.md b/.agents/skills/create-pr/SKILL.md index 3ab1ccf5d5..00d8fd7dc6 100644 --- a/.agents/skills/create-pr/SKILL.md +++ b/.agents/skills/create-pr/SKILL.md @@ -18,7 +18,7 @@ push — the user pushes from their own shell. - The user asks to open or create a NEW PR for the current task branch, in any phrasing ("open a PR", "create the pull request", "put this up for - review") — or runs `/create-pr`. → **Open mode**. + review") — or invokes `@create-pr`. → **Open mode**. - The user asks to fix or update an EXISTING PR's title or description to match conventions. → **Update mode**. @@ -59,7 +59,7 @@ Run all checks before reporting, then report every failure together: 5. **Branch not pushed.** The remote-tracking ref `origin/<branch>` is missing, or `git rev-parse origin/<branch>` differs from HEAD — the branch was never pushed, or has commits the remote does not have. Never - push yourself; ask the user to push and to run `/create-pr` again + push yourself; ask the user to push and to invoke `@create-pr` again afterwards, then stop. ### 3. Already-open PR diff --git a/.agents/skills/implement-plan/SKILL.md b/.agents/skills/implement-plan/SKILL.md index ec81467343..87b7e2bf53 100644 --- a/.agents/skills/implement-plan/SKILL.md +++ b/.agents/skills/implement-plan/SKILL.md @@ -26,9 +26,9 @@ in the local working tree. - The user asks to implement or execute a plan, in any phrasing: "implement the plan", "execute it", "go build it" — or runs - `/implement-plan`. + `@implement-plan`. - A ready, reviewed plan is in the session context or a plan file path - was given (typically after `/make-a-plan` or `/review-plan`). + was given (typically after `@make-a-plan` or `@review-plan`). Do not use it to produce plans — that is the `make-a-plan` flow. @@ -149,9 +149,9 @@ stop and ask the user before splitting it. End by suggesting the next steps (suggestions, not a required pipeline — any instruction from me overrides them): -- `/review-code` — to review the changes just committed; it routes to - `/make-a-plan` by itself if the findings need one. -- `/create-pr` — when the task is done and the branch is ready to merge. +- `@review-code` — to review the changes just committed; it routes to + `@make-a-plan` by itself if the findings need one. +- `@create-pr` — when the task is done and the branch is ready to merge. ## User input, overrides and additional context diff --git a/.agents/skills/make-a-plan/SKILL.md b/.agents/skills/make-a-plan/SKILL.md index 2314b559a8..09f9a86a56 100644 --- a/.agents/skills/make-a-plan/SKILL.md +++ b/.agents/skills/make-a-plan/SKILL.md @@ -16,12 +16,12 @@ stop — this skill needs the build agent to save the plan. - The user asks to plan, design, or break down a task, in any phrasing: "make a plan", "how would we build X", "design an approach for Y" — - or runs `/make-a-plan`. + or invokes `@make-a-plan`. - The user asks to rework or extend an existing plan. While the plan is still unimplemented (pre-`implement-plan` iteration, e.g. after - `/review-plan` findings or user feedback), revise the saved plan file + `@review-plan` findings or user feedback), revise the saved plan file in place. Once the plan has been implemented and reviewed (post - `/review-code` findings on committed work), write a new derived plan + `@review-code` findings on committed work), write a new derived plan file instead — never rewrite the executed plan. The `planner` skill defines the derived naming (`--review-NN`, `--task-NN`). - The user says to apply `review-plan` findings to a still-unimplemented @@ -101,8 +101,8 @@ constraints and risks, what is deliberately out of scope, and the path where the is saved. Never assume that a short list of task names is enough context. End the final response by suggesting the next steps, in this order: -1. `/review-plan` — to get a second opinion on the plan before executing it. -2. `/implement-plan` — to execute the plan from the current session context. +1. `@review-plan` — to get a second opinion on the plan before executing it. +2. `@implement-plan` — to execute the plan from the current session context. These are suggestions, not a required pipeline — any instruction from me overrides them (for example, asking you to implement the plan directly). diff --git a/.agents/skills/planner/SKILL.md b/.agents/skills/planner/SKILL.md index a242cf83bd..c57cafa383 100644 --- a/.agents/skills/planner/SKILL.md +++ b/.agents/skills/planner/SKILL.md @@ -192,8 +192,8 @@ Source: review-code over `<commit>` (branch `<branch>`) | task `NN` of roadmap ` Created: YYYY-MM-DD ``` -End the response by suggesting the next steps: `/review-plan` to get a second -opinion on the plan and `/implement-plan` to execute it. +End the response by suggesting the next steps: `@review-plan` to get a second +opinion on the plan and `@implement-plan` to execute it. ### Plan Structure @@ -261,5 +261,5 @@ Before delivering the plan, confirm: - [ ] No task is XL or larger — break it down instead - [ ] Checkpoints exist after every 2-3 tasks - [ ] The response states the plan's path (saved or suggested) and suggests - `/review-plan` and `/implement-plan` + `@review-plan` and `@implement-plan` - [ ] The plan is ready for human review diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index 65c811e71d..332e9ded5a 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md @@ -12,7 +12,7 @@ Act as a senior software engineer and perform a thorough code review. - The user asks to review code, in any phrasing: "review this diff", "review the PR", "check my changes", "code review" — or runs - `/review-code`. + `@review-code`. - A commit, branch, PR, or diff is ready and the user wants it assessed before merge. @@ -43,7 +43,7 @@ Act as a senior software engineer and perform a thorough code review. - **Approve (no required changes):** say so — there is nothing to address. - **Minor findings (nits):** applying them directly as-is is fine once the review is done — no plan needed. - - **Substantive findings:** suggest `/make-a-plan` to make a plan to address + - **Substantive findings:** suggest `@make-a-plan` to make a plan to address them. ### Hard rule — read-only while reviewing diff --git a/.agents/skills/review-plan/SKILL.md b/.agents/skills/review-plan/SKILL.md index c690df6b85..c286eeded0 100644 --- a/.agents/skills/review-plan/SKILL.md +++ b/.agents/skills/review-plan/SKILL.md @@ -12,15 +12,15 @@ implementation plan. ## When to use - The user asks to review a plan, in any phrasing: "review this plan", - "does this plan look right?", "second opinion on the plan" — or runs - `/review-plan`. -- A plan was just produced (typically by `/make-a-plan`) and the user + "does this plan look right?", "second opinion on the plan" — or invokes + `@review-plan`. +- A plan was just produced (typically by `@make-a-plan`) and the user wants it evaluated before executing it. ## Instructions 1. **Determine the plan under review** from the session context (for example, a - plan just produced by `/make-a-plan`) or from a plan file path given by the + plan just produced by `@make-a-plan`) or from a plan file path given by the user (typically under `.agents/plans/`). If a file path is given, read the file first so the complete plan is in context. 2. Delegate the review to the `general` subagent (via the task tool), unless the @@ -30,8 +30,8 @@ implementation plan. summarize it and do not act on its findings. 4. Right after the review, suggest the next step based on the verdict. These are suggestions — the user decides, and any instruction overrides them: - - **Approve** → suggest `/implement-plan` to execute it. - - **Request changes** → suggest `/make-a-plan` to make a plan to address the + - **Approve** → suggest `@implement-plan` to execute it. + - **Request changes** → suggest `@make-a-plan` to make a plan to address the findings. ### Hard rule — read-only while reviewing diff --git a/.agents/skills/ste/SKILL.md b/.agents/skills/ste/SKILL.md index 67e474ef6b..049c75c069 100644 --- a/.agents/skills/ste/SKILL.md +++ b/.agents/skills/ste/SKILL.md @@ -1,6 +1,6 @@ --- name: ste -description: Write or rewrite text in ASD-STE100 Simplified Technical English. ONLY use this skill when the user explicitly invokes it by name — i.e. they type "/ste" or literally write "use the ste skill" / "apply ASD-STE100". Do NOT trigger it on paraphrased intent such as "simplify this", "make it clearer", "write technical documentation", or "shorter sentences please" — the user has deliberately scoped this skill to explicit invocation only. For those requests, respond normally without loading this skill unless they name it. +description: Write or rewrite text in ASD-STE100 Simplified Technical English. ONLY use this skill when the user explicitly invokes it by name — i.e. they type "@ste" or literally write "use the ste skill" / "apply ASD-STE100". Do NOT trigger it on paraphrased intent such as "simplify this", "make it clearer", "write technical documentation", or "shorter sentences please" — the user has deliberately scoped this skill to explicit invocation only. For those requests, respond normally without loading this skill unless they name it. --- # ASD-STE100 Simplified Technical English @@ -11,7 +11,7 @@ Compliance note (for you, not for output): the official specification and its di ## When to use -Only when the user explicitly invokes it: they type `/ste`, or say "use +Only when the user explicitly invokes it: they type `@ste`, or say "use the ste skill" / "apply ASD-STE100". Requests like "simplify this", "make it clearer", or "shorter sentences" do NOT invoke it — respond normally unless it is named. diff --git a/.opencode/commands/create-pr.md b/.opencode/commands/create-pr.md deleted file mode 100644 index a6c21f7bb2..0000000000 --- a/.opencode/commands/create-pr.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -description: Create a PR for the current task branch or update an existing one — loads and follows the create-pr skill -agent: build ---- - -Load the **`create-pr`** skill and follow it as your only instruction. - -## User input, overrides and additional context - -$ARGUMENTS diff --git a/.opencode/commands/implement-plan.md b/.opencode/commands/implement-plan.md deleted file mode 100644 index eaf9d29fc3..0000000000 --- a/.opencode/commands/implement-plan.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -description: Execute a ready plan — task checklist, your confirmation, then all tasks with one commit (default) or step by step with a commit and a pause per task; creates issue + branch when on a base branch, or commits on the current branch with "direct" — loads and follows the implement-plan skill -agent: build ---- - -Load the **`implement-plan`** skill and follow it as your only instruction. - -## User input, overrides and additional context - -$ARGUMENTS diff --git a/.opencode/commands/make-a-plan.md b/.opencode/commands/make-a-plan.md deleted file mode 100644 index 27a2be5559..0000000000 --- a/.opencode/commands/make-a-plan.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -description: Investigate the chosen task, produce an implementation plan, and save it — loads and follows the make-a-plan skill -agent: build ---- - -Load the **`make-a-plan`** skill and follow it as your only instruction. - -## User input, overrides and additional context - -$ARGUMENTS diff --git a/.opencode/commands/resolve-git-conflicts.md b/.opencode/commands/resolve-git-conflicts.md deleted file mode 100644 index 05b13d3a4b..0000000000 --- a/.opencode/commands/resolve-git-conflicts.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -description: Resolve local git conflicts and stage the resolved files; never continues the rebase — loads and follows the resolve-git-conflicts skill -agent: build ---- - -Load the **`resolve-git-conflicts`** skill and follow it as your only instruction. diff --git a/.opencode/commands/review-code.md b/.opencode/commands/review-code.md deleted file mode 100644 index 4bea9ab7ff..0000000000 --- a/.opencode/commands/review-code.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -description: Code review — review a diff, PR, or code change — loads and follows the review-code skill -agent: build ---- - -Load the **`review-code`** skill and follow it as your only instruction. - -## User input, overrides and additional context - -$ARGUMENTS diff --git a/.opencode/commands/review-plan.md b/.opencode/commands/review-plan.md deleted file mode 100644 index 90bc6161a9..0000000000 --- a/.opencode/commands/review-plan.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -description: Plan review — evaluate an implementation plan before executing it — loads and follows the review-plan skill -agent: build ---- - -Load the **`review-plan`** skill and follow it as your only instruction. - -## User input, overrides and additional context - -$ARGUMENTS From e7732541c38091ae3b0df86738b858d7ef8fee5f Mon Sep 17 00:00:00 2001 From: Andrey Antukh <niwi@niwi.nz> Date: Wed, 18 Nov 2026 18:35:25 +0000 Subject: [PATCH 06/10] :books: Add follow-up verification to code reviews Include remedies, tests and decisions in review findings. Preserve review context in plans and offer to resume the reviewer after implementation. Keep follow-up verification optional and report deferred findings clearly. AI-assisted-by: gpt-6.1-terra --- .agents/README.md | 5 +++- .agents/skills/code-review-criteria/SKILL.md | 8 +++-- .agents/skills/implement-plan/SKILL.md | 20 +++++++++++-- .agents/skills/make-a-plan/SKILL.md | 5 ++++ .agents/skills/review-code/SKILL.md | 31 +++++++++++++++++++- 5 files changed, 62 insertions(+), 7 deletions(-) diff --git a/.agents/README.md b/.agents/README.md index b102aff013..1741c8e12f 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -352,7 +352,10 @@ small. To delegate without switching models, delegate to `general`. whether it will create an issue and a branch, the execution style, and a task checklist — and waits for your go-ahead. Say "step by step" to stop after each task (one commit per task) so you can verify as it goes; - the default runs all tasks with one final commit. + the default runs all tasks with one final commit. For a plan based on a + code review, it then asks whether to have the original reviewer verify the + corrections. If that session is unavailable, it tells you and uses a new + reviewer with the review and implementation context. 5. **Land the work.** When it finishes, either push yourself and invoke `@create-pr`, or loop `@review-code` → `@make-a-plan` → `@implement-plan` until the findings are addressed, then push and invoke diff --git a/.agents/skills/code-review-criteria/SKILL.md b/.agents/skills/code-review-criteria/SKILL.md index b95c563a57..6964822689 100644 --- a/.agents/skills/code-review-criteria/SKILL.md +++ b/.agents/skills/code-review-criteria/SKILL.md @@ -103,6 +103,8 @@ For detailed security guidance, see `security-and-hardening`. For each finding, describe the circumstances under which it could fail: specific inputs, load conditions, timing, or user actions that trigger the problem. "This crashes when input is null" is actionable; "this might crash" is not. +For each finding, propose a concrete remedy and the tests needed to verify it. If a decision requires user input, state the real options, their consequences, and your recommendation within that finding. Do not ask the user to decide during the review, and do not ask about implementation details the code can settle. + Lead with what matters: correctness and security first, then structural issues, then everything else. A few high-conviction comments beat a long list. 5. **Check the evidence, do not re-run it** — Which tests cover the change? What did the author run, and what did CI report? Never re-run the full suite or a build yourself: the author's run and CI already cover that, and repeating it only lengthens the review. Run at most the single test file that settles a specific doubt. When no checks have been run at all (a change you did not see tested), run the module's checks before the verdict. @@ -127,11 +129,11 @@ Briefly explain what the code does and give an overall assessment. ### Critical and High-Priority Issues -List problems that could cause security incidents, data loss, crashes, incorrect behavior, or major performance degradation. Each finding gets its unique ID (`R1`, `R2`, …). For each: state the severity, identify the file/function/code section, explain why it's a problem, describe failure circumstances, and provide a concrete improvement with corrected code when useful. +List problems that could cause security incidents, data loss, crashes, incorrect behavior, or major performance degradation. Each finding gets its unique ID (`R1`, `R2`, …). For each: state the severity, identify the file/function/code section, explain why it's a problem, describe failure circumstances, and provide a concrete improvement with corrected code when useful. Include the tests needed and any user decision, options and recommendation in the finding itself. ### Other Findings -List medium- and low-priority issues, including maintainability and design concerns. Use `M1`, `M2`, … for Medium/Low and `S1`, `S2`, … for Suggestions. +List medium- and low-priority issues, including maintainability and design concerns. Use `M1`, `M2`, … for Medium/Low and `S1`, `S2`, … for Suggestions. Apply the same remedy, test and decision guidance to each finding; say when no new test is needed and why. ### Suggested Refactoring @@ -139,7 +141,7 @@ Provide focused code changes or revised snippets. Preserve existing behavior unl ### Testing Recommendations -Identify missing tests and describe specific test cases, including edge cases and failure scenarios. +Summarize the verification approach and any cross-cutting test cases, including edge cases and failure scenarios. Keep missing tests as severity-tagged findings and link this section to their IDs. ### Positive Observations diff --git a/.agents/skills/implement-plan/SKILL.md b/.agents/skills/implement-plan/SKILL.md index 87b7e2bf53..31e1eee9ca 100644 --- a/.agents/skills/implement-plan/SKILL.md +++ b/.agents/skills/implement-plan/SKILL.md @@ -32,6 +32,11 @@ in the local working tree. Do not use it to produce plans — that is the `make-a-plan` flow. +For a plan derived from a code review, retain its review target, reviewer +session ID, original findings and decisions. Record the starting revision and +the exact commits or diff produced by this implementation, plus test evidence, +in session context for follow-up. Do not put commit hashes in the plan file. + ## 1. Read the plan first Identify the plan to execute — from the file path the user gave, the @@ -146,11 +151,22 @@ stop and ask the user before splitting it. ## When you are done +After the entire plan is implemented and verified, including the final task in +step-by-step mode, if it addresses code review findings, ask whether the user +wants the original reviewer to verify the corrections. Use the `question` tool +if available; otherwise ask in chat. Wait for the answer. Do not start the +follow-up without consent, and do not ask after each intermediate task. + +If the user accepts, follow `@review-code`'s follow-up procedure with the +review context, decisions, exact correction range or diff and test evidence. +If the original reviewer cannot be resumed, say so and use a new reviewer with +the same context. If the user declines, stop without starting a review. The +follow-up is read-only; further fixes require the user's direction. + End by suggesting the next steps (suggestions, not a required pipeline — any instruction from me overrides them): -- `@review-code` — to review the changes just committed; it routes to - `@make-a-plan` by itself if the findings need one. +- `@review-code` — for a new independent review of the changes. - `@create-pr` — when the task is done and the branch is ready to merge. ## User input, overrides and additional context diff --git a/.agents/skills/make-a-plan/SKILL.md b/.agents/skills/make-a-plan/SKILL.md index 09f9a86a56..3c549d272a 100644 --- a/.agents/skills/make-a-plan/SKILL.md +++ b/.agents/skills/make-a-plan/SKILL.md @@ -39,6 +39,11 @@ Do not use it to execute a plan — that is the `implement-plan` flow. example, `delegated` in the user context), delegate to the `general` subagent instead — the delegate must also follow the `planner` skill and receive all the relevant session context (a review, user feedback, and so on). + When the plan addresses a code review, preserve the review target, reviewer + session ID if available, original findings and IDs, and decisions including + deferred or rejected findings and their reasons in the local plan. Map + accepted findings to tasks. If context is unavailable, mark it unknown; do + not invent it. Pass this context to a delegated planner too. 2. Before asking me to decide anything, explain the plan and every open question in plain language. Assume I know only the high-level project goal, not the codebase, architecture, implementation terms, or the problem this task solves. diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index 332e9ded5a..f67c40537d 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md @@ -32,12 +32,17 @@ Act as a senior software engineer and perform a thorough code review. - Read-only: modify no file and create no commit. Reviewing never writes. - Do not invent problems: every finding must be real and actionable. - Missing tests are an issue, not a suggestion — a severity-tagged finding. + - For each finding, give a concrete remedy and the tests needed to verify it. + If a user decision is needed, include the real options and a recommendation + in that finding. Do not pause to ask during the review. - Prioritize by impact: one structural issue outweighs ten nits, and "this could be better" is not a finding — say why and how. - Skip generated files, lockfile-only changes and unrelated modifications unless they introduce security risks. 3. When the subagent returns, output the review to the user verbatim. Do not - summarize it and do not act on its findings. + summarize it and do not act on its findings. Retain the subagent session ID, + review target and complete findings in the session context for follow-up; + do not invent an ID if the tool does not provide one. 4. Right after the review, suggest how to proceed based on the findings. These are suggestions — the user decides: - **Approve (no required changes):** say so — there is nothing to address. @@ -45,6 +50,30 @@ Act as a senior software engineer and perform a thorough code review. review is done — no plan needed. - **Substantive findings:** suggest `@make-a-plan` to make a plan to address them. + - If the user wants to discuss findings one by one, use `@issue-walkthrough` + on request; do not start it automatically. + +### Follow-up after implementation + +When the user agrees to verify corrections, resume the original reviewer using +its session ID if the tool supports it. Give it the original review target and +findings, the decisions and plan, the exact correction commit range or diff, +and the test evidence. Require it to inspect the actual corrections and +evidence, not rely on its earlier context alone. If the original session is +unavailable or cannot be resumed, tell the user and delegate to a new reviewer +with the same context; never claim it is the original reviewer. If the review, +decisions or correction range cannot be established, ask for the missing +information rather than inventing it. + +The reviewer follows `code-review-criteria` and remains read-only. It reports +each original finding with its unchanged ID as **resolved**, **pending**, or +**not addressed** (including the agreed reason); report any new problems with +new, non-conflicting IDs. For pending and new problems, give evidence, a remedy, +tests and any user decision as in the original review. Summarize separately +whether all agreed corrections are resolved and whether any findings remain, +including deferred findings. Do not equate deferred with resolved. Present the +result without implementing fixes; the user chooses whether to iterate, request +an independent review, or stop. ### Hard rule — read-only while reviewing From 14a623da08e77c90b186fed112af6c716dd0de98 Mon Sep 17 00:00:00 2001 From: Andrey Antukh <niwi@niwi.nz> Date: Wed, 18 Nov 2026 18:41:50 +0000 Subject: [PATCH 07/10] :books: Apply plan review improvements automatically Apply clear review improvements to the plan and resolve consequential decisions through the walkthrough before updating the plan metadata. AI-assisted-by: gpt-6.1-terra --- .agents/README.md | 10 +- .agents/skills/make-a-plan/SKILL.md | 9 +- .agents/skills/plan-review-criteria/SKILL.md | 7 ++ .agents/skills/planner/SKILL.md | 10 +- .agents/skills/review-code/SKILL.md | 3 +- .agents/skills/review-plan/SKILL.md | 110 +++++++++---------- 6 files changed, 73 insertions(+), 76 deletions(-) diff --git a/.agents/README.md b/.agents/README.md index 1741c8e12f..05722cff38 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -346,8 +346,9 @@ small. To delegate without switching models, delegate to `general`. `@make-a-plan delegate to @engineer-glm`. 3. **Iterate on the plan.** The plan is saved to `.agents/plans/`, so you never depend on LLM memory: read the file directly, or invoke `@review-plan` - for a second opinion (delegation works here too). Complex plans deserve a - review; simple ones can skip it. + for a second opinion (delegation works here too). It applies clear plan + improvements and discusses consequential decisions one by one before + applying them. Complex plans deserve a review; simple ones can skip it. 4. **Execute.** Invoke `@implement-plan`. It first prints the full picture — whether it will create an issue and a branch, the execution style, and a task checklist — and waits for your go-ahead. Say "step by step" to stop @@ -405,9 +406,8 @@ Every plan carries `Status: draft | reviewed | done` plus an append-only `Review Log` (UTC ISO 8601, one line per entry): - `draft` — fresh from `@make-a-plan`. -- `reviewed` — review feedback incorporated. `@review-plan` stays - read-only; only your explicit "apply" makes `@make-a-plan` apply - the changes, flip the status, and log one line. +- `reviewed` — review feedback incorporated. `@review-plan` applies clear + improvements and agreed decisions, then updates the status and log. - `done` — `@implement-plan` closes it on completion, logging the issue URL when one exists (never commit hashes). diff --git a/.agents/skills/make-a-plan/SKILL.md b/.agents/skills/make-a-plan/SKILL.md index 3c549d272a..7a46cd9261 100644 --- a/.agents/skills/make-a-plan/SKILL.md +++ b/.agents/skills/make-a-plan/SKILL.md @@ -24,11 +24,10 @@ stop — this skill needs the build agent to save the plan. `@review-code` findings on committed work), write a new derived plan file instead — never rewrite the executed plan. The `planner` skill defines the derived naming (`--review-NN`, `--task-NN`). -- The user says to apply `review-plan` findings to a still-unimplemented - plan: apply the agreed changes, flip `Status` to `reviewed`, and - append one UTC ISO 8601 line to `Review Log` describing what changed. - This apply step is the only pre-implementation write to those fields — - `review-plan` itself stays read-only and never writes. +- The user says to apply additional review feedback to a still-unimplemented + plan: apply the agreed changes, flip `Status` to `reviewed`, and append one + UTC ISO 8601 line to `Review Log`. `review-plan` can also update the plan + and its metadata as part of its own review flow. Do not use it to execute a plan — that is the `implement-plan` flow. diff --git a/.agents/skills/plan-review-criteria/SKILL.md b/.agents/skills/plan-review-criteria/SKILL.md index 649bd1118f..8b75cde394 100644 --- a/.agents/skills/plan-review-criteria/SKILL.md +++ b/.agents/skills/plan-review-criteria/SKILL.md @@ -11,6 +11,13 @@ Multi-dimensional plan review with quality gates. Every plan gets reviewed befor **The approval standard:** Approve a plan when it is specific enough that a skilled implementer could execute it without guessing, the task ordering is sound, and risks are acknowledged. Perfect plans don't exist — the goal is confidence that implementation won't derail. Don't block a plan because it isn't exactly how you would have structured it. If it's executable and well-organized, approve it. +In the `review-plan` flow, apply clear improvements within the plan's existing +goal, scope and decisions. Flag consequential choices for the user instead of +choosing them. Report applied changes and unresolved decisions with evidence, +options and a recommendation; the parent conducts the walkthrough. Recheck the +plan after answers are applied and never approve while required decisions or +changes remain unresolved. Only the plan file may be edited. + ## When to Use - The reviewer subagent of the `review-plan` flow loads this skill to perform diff --git a/.agents/skills/planner/SKILL.md b/.agents/skills/planner/SKILL.md index c57cafa383..7059189596 100644 --- a/.agents/skills/planner/SKILL.md +++ b/.agents/skills/planner/SKILL.md @@ -223,16 +223,16 @@ Review Log: log. `reviewed` never means "a review was emitted" — it means "review feedback was incorporated". A plan approved with no changes goes `draft` → `done` without passing through `reviewed`. -- Only a user-triggered apply step writes them before implementation: - when the user says to apply `review-plan` findings, `make-a-plan` - applies the changes, flips to `reviewed`, and appends one UTC - ISO 8601 line describing what changed. +- Before implementation, `review-plan` applies clear review feedback and + agreed decisions, flips to `reviewed` and appends one UTC ISO 8601 entry + when the plan changed. `make-a-plan` can also do this for additional + feedback when the user asks. - `implement-plan` flips to `done` on completion and appends one line with the issue URL when one exists (standalone mode); otherwise just `done`. Never record commit hashes — they rot on amend/rebase and git already links the commit. - The log is append-only: never rewrite or delete lines. -- `review-plan` and `review-code` never write these fields. +- `review-code` never writes these fields. Omit empty sections only when they do not apply. Every implementation task still requires acceptance criteria, verification, dependencies, likely files, diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index f67c40537d..f09f084a6c 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md @@ -51,7 +51,8 @@ Act as a senior software engineer and perform a thorough code review. - **Substantive findings:** suggest `@make-a-plan` to make a plan to address them. - If the user wants to discuss findings one by one, use `@issue-walkthrough` - on request; do not start it automatically. + on request; do not start it automatically. The walkthrough returns its + decisions to `@make-a-plan`, not to automatic code editing. ### Follow-up after implementation diff --git a/.agents/skills/review-plan/SKILL.md b/.agents/skills/review-plan/SKILL.md index c286eeded0..b4beb20641 100644 --- a/.agents/skills/review-plan/SKILL.md +++ b/.agents/skills/review-plan/SKILL.md @@ -1,70 +1,60 @@ --- name: review-plan -description: Plan review flow — evaluate an implementation plan before it is executed, delegating the review to a subagent that follows the plan-review-criteria skill. Use it when the user asks to review a plan, in any phrasing. +description: Review an implementation plan with a subagent, apply clear improvements and resolve consequential decisions with the user. slash: true --- # Review Plan -Act as a senior software engineer and perform a thorough review of an -implementation plan. +Review an unimplemented plan with a subagent and improve the plan without +implementing it. Use this flow when the user asks for a plan review or invokes +`@review-plan`. -## When to use +## Flow -- The user asks to review a plan, in any phrasing: "review this plan", - "does this plan look right?", "second opinion on the plan" — or invokes - `@review-plan`. -- A plan was just produced (typically by `@make-a-plan`) and the user - wants it evaluated before executing it. +1. Identify and read the complete plan and its file. If the target or path is + ambiguous, ask. If no saved file exists, ask for a path or have the user save + it first. Do not edit a completed plan: propose a derived plan instead. +2. Delegate to `general`, unless the user specifies a different subagent or + model. Supply the plan path, relevant session context and these instructions: + - Load `plan-review-criteria`, read `AGENTS.md` and the relevant module and + testing memories, and review the plan against the criteria. + - Apply clear, evidence-based improvements directly to that plan file only. + Preserve the goal, scope, agreed decisions and intended behavior. Examples: + clarify tasks, add missing tests, correct dependencies and specify actual + verification commands. Do not guess commands or invent findings. + - A change that affects the goal, user-visible behavior, scope, tradeoffs or + an existing decision needs the user's decision. Leave it unresolved; report + concrete options, consequences and a recommendation. Do not ask questions + from the subagent. + - Return a concise summary of applied changes, remaining decisions with + stable IDs, evidence and recommendations, and an honest provisional + verdict. Retain the subagent session ID for follow-up if available. + - Do not change source files, other plans or documents, run state-changing + checks, commit, or implement the plan. If the plan is not writable, report + this and return the proposed edits instead. +3. Show the summary. If decisions remain, start `@issue-walkthrough` immediately + in the parent session with those questions and their IDs. Follow its one + question per turn and read-only rules. Do not ask questions that the code or + existing decisions settle. Wait for every answer. +4. Resume the same subagent with the decision table and plan path. It applies + the decisions to the plan, rechecks consistency and reports changes and any + newly discovered consequential decisions. Repeat the walkthrough for new + decisions, then apply those answers. If the original session cannot be + resumed, tell the user and apply the changes in the parent or delegate a new + subagent with the full context. If the reviewer cannot write, apply its + proposed edits in the parent only if the plan file is writable; otherwise + explain the blocker and stop. +5. Once all decisions are resolved and the plan is coherent, update its + metadata: when review feedback changed the plan, set `Status: reviewed` and + append one UTC ISO 8601 `Review Log` entry for this review, summarizing the + changes. Preserve prior log entries. If no feedback changed the plan, leave + status and log unchanged. Never record commit hashes. If decisions or + required changes remain unresolved, do not claim the plan is ready or mark + it reviewed. +6. Show the final summary, plan path and verdict. Suggest `@implement-plan` only + when the plan is ready. Never execute the plan automatically. -## Instructions - -1. **Determine the plan under review** from the session context (for example, a - plan just produced by `@make-a-plan`) or from a plan file path given by the - user (typically under `.agents/plans/`). If a file path is given, read the - file first so the complete plan is in context. -2. Delegate the review to the `general` subagent (via the task tool), unless the - user specifies another agent. Include in the prompt the - **`plan-review-criteria`** skill name and all user context. -3. When the subagent returns, output the review to the user verbatim. Do not - summarize it and do not act on its findings. -4. Right after the review, suggest the next step based on the verdict. These - are suggestions — the user decides, and any instruction overrides them: - - **Approve** → suggest `@implement-plan` to execute it. - - **Request changes** → suggest `@make-a-plan` to make a plan to address the - findings. - -### Hard rule — read-only while reviewing - -This flow is read-only **for the duration of the review**: from the moment it -starts until the user considers the review finished (including any feedback, -questions, or clarifications about it). During that period, never fix, -implement, edit files or create commits — not even "obvious" fixes derived from -the findings. Once the user explicitly states the review is done (or moves on to -a different task), this rule no longer applies and you act as a normal build -agent again. - -## Instructions for the subagent - -1. Load the **`plan-review-criteria`** skill and follow its process and output - format. -2. Read `AGENTS.md` (if present) and follow its instructions for finding and - reading all related documentation and testing memories before reviewing. -3. Return in your final message the COMPLETE review, verbatim, exactly as the - skill instructs it to be produced. Do not summarize it — include the full - structured review. - -### Strong rules for the subagent - -1. Do not invent problems. Every finding must be real and actionable. -2. Read-only: do not modify any file and do not create a commit — reviewing - never writes. -3. Be specific and constructive. "This could be better" is not helpful — explain - why and how. -4. Prioritize by impact. One structural issue outweighs ten nits. -5. Judge the plan as the implementer would: every task executable without - guessing, ordering follows the dependency graph, risks named. - -## User input, overrides and additional context - -$ARGUMENTS +The only permitted write in this flow is the specified local plan file, +including its status and log. Do not stage or commit it. If a user instruction +overrides automatic editing, respect it and report findings without editing. From 7d5fef711cf45c010b11513b4cf63acac2810c6d Mon Sep 17 00:00:00 2001 From: Andrey Antukh <niwi@niwi.nz> Date: Wed, 18 Nov 2026 18:59:17 +0000 Subject: [PATCH 08/10] :books: Refine plan and code review criteria Make review criteria proportional to risk and project conventions. Keep code reviews read-only, use existing test evidence and stable IDs. AI-assisted-by: gpt-6.1-terra --- .agents/skills/code-review-criteria/SKILL.md | 219 ++++------ .agents/skills/plan-review-criteria/SKILL.md | 401 +++++-------------- .agents/skills/review-code/SKILL.md | 21 +- 3 files changed, 174 insertions(+), 467 deletions(-) diff --git a/.agents/skills/code-review-criteria/SKILL.md b/.agents/skills/code-review-criteria/SKILL.md index 6964822689..af926a26e2 100644 --- a/.agents/skills/code-review-criteria/SKILL.md +++ b/.agents/skills/code-review-criteria/SKILL.md @@ -1,174 +1,95 @@ --- name: code-review-criteria -description: Code review criteria — the five review axes, core principles, severity format, and verdict for reviewing code changes. Loaded by the reviewer subagent of the review-code flow. Not a user-facing flow — to review code, use the review-code flow. +description: Code review criteria for correctness, clarity, architecture, security and performance. Loaded by the review-code subagent. --- -# Code Review Criteria and Quality +# Code Review Criteria -## Overview +Assess whether the change improves the codebase and is safe to merge. Review +the diff in context, its intent and relevant tests. Follow project conventions +and module memories. Do not block on personal preferences or invent problems. +Apply each axis in proportion to the change and its risks. -Multi-dimensional code review with quality gates. Every change gets reviewed before merge — no exceptions. Review covers five axes: correctness, readability, architecture, security, and performance. +Follow `review-code` for delegation and its read-only contract. Never run tests, +builds, linters or other state-changing checks during a review or follow-up. +Inspect prior test results or CI evidence when available. Identify their source +and scope; if evidence is missing, stale or inaccessible, say what is +unverified. Never claim a suite passed without evidence. -**The approval standard:** Approve a change when it definitely improves overall code health, even if it isn't perfect. Perfect code doesn't exist — the goal is continuous improvement. Don't block a change because it isn't exactly how you would have written it. If it improves the codebase and follows the project's conventions, approve it. +## Review axes -## When to Use +### Correctness and tests -- The reviewer subagent of the `review-code` flow loads this skill to perform the review of a code change. -- To review code, always go through the `review-code` flow — never load this skill directly for that. This is the criteria reference, not the flow. +Check requirements, relevant boundaries, error paths, concurrency and state. +Use the module's contracts to decide where validation belongs; do not demand +redundant guards inside functions with established preconditions. Check that +new functionality has tests covering its behavior and important failure +cases, using the appropriate layer and project testing guidance. Missing +required tests are findings; documentation-only changes need not add tests. +Do not infer that a test failed before a fix without evidence. -## Core Principles +### Readability and simplicity -These principles underpin every axis. When in doubt, default to them. +Check names, control flow and maintainability against existing conventions. +Flag duplication when it creates a concrete risk of drift or maintenance +cost, not merely because code appears more than once. In tests, prefer +self-contained, readable cases even when they repeat setup. Suggest the +simplest remedy that preserves behavior. -- **DRY (Don't Repeat Yourself):** Every piece of knowledge has one authoritative representation. Flag duplicated logic as a required change — it is not "just similar", it is drift that will diverge. -- **KISS (Keep It Simple, Stupid):** The simplest solution that works is the best solution. Complexity must earn its place: if it needs more than a sentence to explain, push for simplification before merge. -- **YAGNI (You Aren't Gonna Need It):** No abstractions, hooks or generalizations for hypothetical future use cases. Generalize on the third occurrence, not the first. -- **Don't invent problems:** Every finding must be a real risk, a real readability barrier, or a real architectural concern — not a hypothetical or a stylistic preference disguised as a problem. +### Architecture and compatibility -## The Five-Axis Review +Check module boundaries, existing abstractions, contracts and unnecessary +complexity. Review surrounding code when needed to understand the change. +Do not label a compatibility shim dead code without checking its purpose. +For file formats or data model changes, consult the relevant compatibility, +migration and feature memories; for Clojure, logging and translations, read +the corresponding guidance when relevant. -Every review evaluates code across these dimensions. +### Security -### 1. Correctness +Evaluate relevant input boundaries, authorization, secrets, data handling and +external integrations. Consult project security guidance for the affected +technology; do not assume a generic framework or tool applies to this module. -Does the code do what it claims to do? +### Performance -- Does it match the spec or task requirements? -- Are edge cases handled (null, empty, boundary values)? -- Are error paths handled (not just the happy path)? -- Do the tests cover the changed behavior, including its edge cases? -- Are there off-by-one errors, race conditions, or state inconsistencies? +Assess relevant hot paths, resource bounds, data access and scaling. Explain +the workload or conditions in which a problem matters; do not flag speculative +optimizations without a concrete risk. -### 2. Readability & Simplicity +## Scope and dependencies -Can another engineer (or agent) understand this code without the author explaining it? +Review relevant generated files or lockfile changes when they affect the +contract, dependencies or security; do not skip a lockfile-only dependency +change. Check dependency changes against available changelogs, project tools +and relevant lockfile diffs. Treat size as a signal to assess reviewability, +not an automatic finding. Identify unrelated work in the target diff when it +materially impedes review; do not review unrelated working-tree changes. -- Are names descriptive and consistent with project conventions? (No `temp`, `data`, `result` without context) -- Is the control flow straightforward (avoid nested ternaries, deep callbacks)? -- Are there "clever" tricks that should be simplified? Could this be done in fewer lines? (1000 lines where 100 suffice is a failure) -- Is a new conditional bolted onto an unrelated flow? Push the logic into its own helper, state, or policy. -- Do repeated conditionals on the same shape appear? They signal a missing model or dispatcher. -- Are there dead code artifacts: no-op variables, backwards-compat shims, or `// removed` comments? +## Findings and verdict -### 3. Architecture +Assign each finding a stable ID (`F1`, `F2`, …), independent of severity. +Never renumber it within the review or follow-up; severity may change as +evidence changes. New findings receive unused IDs. -Does the change fit the system's design? +For each finding state severity, file and location, concrete circumstances, +impact, remedy and the tests needed to verify it; explain when no new test is +needed. If a consequential decision requires user input, give the real options, +consequences and recommendation within that finding, without pausing to ask. -- Does it follow existing patterns or introduce a new one? If new, is it justified? -- Does it keep clean module boundaries, with dependencies flowing the right way (no cycles)? -- Is the abstraction level appropriate (not over-engineered, not too coupled)? -- Is there existing code that already does this? Reuse the canonical helper instead of a near-duplicate, and collapse branches that do nearly the same thing. -- Is feature-specific logic leaking into a shared or general-purpose module? -- Are type boundaries explicit? Question gratuitous `any`/`unknown`/optional/casts and silent fallbacks. -- Does the change reduce complexity or relocate it? Count the concepts a reader must hold: prefer the restructuring that makes whole branches disappear, and deleting an abstraction over polishing it. -- **Give the remedy, not only the problem:** replace conditionals with dispatchers, separate orchestration from business logic, extract helpers, split large files. Prefer the remedy that removes moving pieces over one that spreads the same complexity around. +- **Critical:** security incident, data loss or comparably severe breakage; + blocks merge. +- **High:** a significant defect or missing required test; must be addressed. +- **Medium:** a substantive issue worth fixing but not a merge blocker. +- **Low / Suggestion:** an optional improvement with a concrete benefit. -### 4. Security +Base severity on impact and project requirements. Missing tests required for +new functionality must be addressed; do not invent a test requirement for +changes where none applies. -For detailed security guidance, see `security-and-hardening`. - -- Is user input validated and sanitized? -- Are secrets kept out of code, logs, and version control? -- Is authentication/authorization checked where needed? -- Are SQL queries parameterized (no string concatenation)? -- Are outputs encoded to prevent XSS? -- Are dependencies from trusted sources with no known vulnerabilities? -- Is data from external sources (APIs, logs, user content, config files) treated as untrusted? - -### 5. Performance - -- Any N+1 query patterns? -- Any unbounded loops or unconstrained data fetching? -- Any synchronous operations that should be async? -- Any unnecessary re-renders in UI components? -- Any missing pagination on list endpoints? -- Any large objects created in hot paths? - -## Review Process - -1. **Understand the intent** — What is this change trying to accomplish? What spec or task does it implement? -2. **Review tests first** — Tests reveal intent and coverage. Do they test behavior, not implementation details? Are edge cases covered? -3. **Review the implementation** — Walk through each file with the five axes in mind. -4. **Categorize findings** — Label every comment with its severity: - -| Prefix | Meaning | Author Action | -|--------|---------|---------------| -| **Critical:** | Blocks merge | Security vulnerability, data loss, broken functionality | -| **High:** | Required change | Must address before merge | -| **Medium:** | Should fix | Strongly recommended, not a blocker | -| **Low:** | Minor, optional | Author may ignore — formatting, style preferences | -| **Suggestion:** | Worth considering | Not required, but improves the code | - -**Finding IDs.** Assign every finding a stable identifier by severity class: `R1`, `R2`, … for required findings (Critical, High), `M1`, `M2`, … for minor findings (Medium, Low), and `S1`, `S2`, … for suggestions. Number within each class in review order. Use the ID everywhere the finding is mentioned — in section headers, in the verdict, in follow-up discussion. Never renumber within a review. Example: `**R2** — `app/validate.cljs:42` — duplicate branch logic…`. - -For each finding, describe the circumstances under which it could fail: specific inputs, load conditions, timing, or user actions that trigger the problem. "This crashes when input is null" is actionable; "this might crash" is not. - -For each finding, propose a concrete remedy and the tests needed to verify it. If a decision requires user input, state the real options, their consequences, and your recommendation within that finding. Do not ask the user to decide during the review, and do not ask about implementation details the code can settle. - -Lead with what matters: correctness and security first, then structural issues, then everything else. A few high-conviction comments beat a long list. - -5. **Check the evidence, do not re-run it** — Which tests cover the change? What did the author run, and what did CI report? Never re-run the full suite or a build yourself: the author's run and CI already cover that, and repeating it only lengthens the review. Run at most the single test file that settles a specific doubt. When no checks have been run at all (a change you did not see tested), run the module's checks before the verdict. - -## Change Sizing - -Small, focused changes are easier to review, faster to merge, and safer to deploy. Flag the size when a diff exceeds ~300 lines, or when it grows a file past ~1000 total lines, and name the remedy: split it, and separate refactoring from feature work. This is a finding about the change, not work to do inside the review. - -## Dependencies - -Before accepting a new dependency: does the existing stack already solve it, how large is the bundle impact, is it maintained, does `npm audit` report anything, is the license compatible. Prefer the standard library and existing utilities — every dependency is a liability. - -For upgrades: read the changelog, not just the version number; one dependency per change; a green suite before and after; review the lockfile diff and never hand-edit it. Supply-chain triage follows `security-and-hardening`. - -## Review Output - -Structure every review using this format: - -### Summary - -Briefly explain what the code does and give an overall assessment. - -### Critical and High-Priority Issues - -List problems that could cause security incidents, data loss, crashes, incorrect behavior, or major performance degradation. Each finding gets its unique ID (`R1`, `R2`, …). For each: state the severity, identify the file/function/code section, explain why it's a problem, describe failure circumstances, and provide a concrete improvement with corrected code when useful. Include the tests needed and any user decision, options and recommendation in the finding itself. - -### Other Findings - -List medium- and low-priority issues, including maintainability and design concerns. Use `M1`, `M2`, … for Medium/Low and `S1`, `S2`, … for Suggestions. Apply the same remedy, test and decision guidance to each finding; say when no new test is needed and why. - -### Suggested Refactoring - -Provide focused code changes or revised snippets. Preserve existing behavior unless a behavior change is explicitly justified. - -### Testing Recommendations - -Summarize the verification approach and any cross-cutting test cases, including edge cases and failure scenarios. Keep missing tests as severity-tagged findings and link this section to their IDs. - -### Positive Observations - -Mention implementation choices that are clear, safe, efficient, or well designed. This is not fluff — it reinforces good patterns and tells the author what to keep doing. - -### Final Verdict - -Choose one: - -- **Approve** — Ready to merge -- **Approve with minor changes** — Good to merge after addressing low/medium issues -- **Request changes** — Critical or high issues must be resolved before merge - -List the finding IDs the verdict depends on (e.g. "Request changes: R1, R2"). - -## Red Flags - -- A change merged without any review. -- A review that only checks whether the tests pass. -- Security-sensitive changes without a security-focused review. -- A change too large to review properly: split it. - -## Verification - -Before emitting the verdict, confirm the evidence the review rests on. This covers the state of the code at review time, not the later fixing of findings: - -- [ ] The suite is green, and the evidence is the author's run or CI — not your own re-run. Say which one you relied on. -- [ ] New behavior has tests that cover the edge cases in the diff. -- [ ] The verification story is stated: what changed and how it was verified. -- [ ] Dependency changes were reviewed against the changelog and the lockfile diff. +Return a short summary, findings ordered by impact and a verdict with the +relevant IDs: **Approve**, **Approve with minor changes**, or **Request +changes**. State verification evidence and limitations. Do not duplicate +remedies or tests in separate sections. If no findings exist, say so. In +follow-up, retain original IDs and +report resolved, pending and not-addressed findings as `review-code` requires. diff --git a/.agents/skills/plan-review-criteria/SKILL.md b/.agents/skills/plan-review-criteria/SKILL.md index 8b75cde394..86352f6b77 100644 --- a/.agents/skills/plan-review-criteria/SKILL.md +++ b/.agents/skills/plan-review-criteria/SKILL.md @@ -1,322 +1,105 @@ --- name: plan-review-criteria -description: Plan review criteria — the six review axes, severity rubric, approval standard, and output format for reviewing implementation plans. Loaded by the reviewer subagent of the review-plan flow. Not a user-facing flow — to review a plan, use the review-plan flow. +description: Criteria for reviewing implementation plans, including evidence, severity and verdicts. Loaded by the review-plan subagent. --- # Plan Review Criteria -## Overview +Evaluate whether the plan can deliver its stated goal safely and whether a +skilled implementer can execute and verify it without guessing. Perfect plans +do not exist: do not block on personal preferences or missing sections that +add no useful information. Apply each criterion in proportion to the plan's +scope and risks; explain when a criterion is not applicable. -Multi-dimensional plan review with quality gates. Every plan gets reviewed before implementation starts — no exceptions. Review covers six axes: completeness, task quality, architecture & sequencing, risk coverage, actionability, and proposed code quality. +Follow `review-plan` for delegation, permitted edits, decisions and handover. +Do not run tests, builds or other state-changing checks during the review. -**The approval standard:** Approve a plan when it is specific enough that a skilled implementer could execute it without guessing, the task ordering is sound, and risks are acknowledged. Perfect plans don't exist — the goal is confidence that implementation won't derail. Don't block a plan because it isn't exactly how you would have structured it. If it's executable and well-organized, approve it. +## Evidence and scope -In the `review-plan` flow, apply clear improvements within the plan's existing -goal, scope and decisions. Flag consequential choices for the user instead of -choosing them. Report applied changes and unresolved decisions with evidence, -options and a recommendation; the parent conducts the walkthrough. Recheck the -plan after answers are applied and never approve while required decisions or -changes remain unresolved. Only the plan file may be edited. +- Read the plan, relevant code, project guidance and module memories. Check + that cited paths, symbols and proposed commands exist and are appropriate; + distinguish verified facts from assumptions and unknowns. Do not invent + findings or claim checks were run when they were not. +- Check that tasks serve the stated goal and respect existing requirements and + decisions. Identify scope creep, contradictions and dependencies on external + work. A consequential change in scope, behavior or tradeoffs needs the user's + decision. +- Evaluate the proposed approach even without code snippets: does it solve the + problem, fit existing conventions and avoid unnecessary complexity? If the + plan includes code, also check its types, signatures and examples. -## When to Use - -- The reviewer subagent of the `review-plan` flow loads this skill to perform - the review of a plan. -- To review a plan, always go through the `review-plan` flow — never load this - skill directly for that. This is the criteria reference, not the flow. - -**Do NOT use for:** Single-file changes with obvious scope, or when the task is trivial enough to just do. - -## The Six-Axis Review - -Every plan gets evaluated across these dimensions: +## Six review axes ### 1. Completeness -Does the plan cover everything needed to implement successfully? - -- Is the **context** clear? (What problem, why now, what's the goal?) -- Are **affected modules** identified with paths? -- Are **architecture decisions** documented with rationale? -- Is there a **testing strategy**? -- Are **verification commands** explicit (not "run the tests")? -- Are **open questions** listed (not buried in someone's head)? -- Is there a **parallelization** assessment for multi-task plans? - -**Missing any of these is a gap, not a nit.** - -### 2. Task Quality - -Are the tasks well-defined and independently executable? - -- Does every task have **acceptance criteria**? (Testable, not vague) -- Does every task have **verification steps**? -- Are tasks **sized appropriately**? (XS–M is ideal, L is acceptable, XL must be split) -- Are **dependencies** between tasks explicitly stated? -- Are **files likely touched** listed? -- Is each task a **single, self-contained change**? (Not "implement the whole feature") -- Could a skilled implementer pick up any task and execute it without asking clarifying questions? - -### 3. Architecture & Sequencing - -Is the plan structured so implementation flows correctly? - -- Does implementation order follow the **dependency graph** (foundations first)? -- Are tasks **vertically sliced** (feature paths) rather than horizontally layered? -- Does each task leave the system in a **working state**? -- Are there **checkpoints** between major phases? -- Are **high-risk tasks early** (fail fast)? -- Is the total plan a reasonable number of tasks? (More than ~15 tasks suggests the scope should be split into multiple plans) - -### 4. Risk Coverage - -Are the hard parts acknowledged and mitigated? - -- Are **edge cases** identified? -- Are **breaking changes** or **migration concerns** noted? -- Are **security implications** considered? -- Are **performance implications** considered? -- Are **external dependencies** or integration risks flagged? -- Is there a plan for **rollback** if something goes wrong? -- Are **data integrity** risks addressed (what happens if a migration fails mid-way)? - -### 5. Actionability - -Can an implementer actually execute this? - -- Are **file paths** specific (not "update the relevant files")? -- Are **function/method names** mentioned where applicable? -- Are **verification commands** copy-pasteable (not "run the linter")? -- Are **test commands** project-specific (not generic)? -- Is the **code shape** described where the implementation isn't obvious? -- Are **conventions** referenced (naming, patterns, existing utilities to reuse)? -- Does the plan reference **existing code** the implementer should read first? - -### 6. Proposed Code Quality *(when the plan includes implementation details)* - -If the plan proposes code shapes, function signatures, data structures, or API designs, evaluate those proposals against `code-review-criteria`: - -- **Correctness:** Do the proposed types/signatures handle edge cases (null, empty, boundaries)? -- **Readability:** Are proposed names descriptive and consistent with project conventions? -- **Architecture:** Do proposed abstractions follow existing patterns? Are they justified (not over-engineered)? -- **Security:** Do proposed APIs validate input at boundaries? Any injection/XSS vectors in the design? -- **Performance:** Do proposed data structures avoid N+1 patterns? Any unbounded operations in the design? - -**When to apply:** Only when the plan includes specific code snippets, type definitions, API contracts, or function signatures. Plans that only describe "what" without showing "how" skip this axis. - -## Structural Remedies - -When you flag a structural problem in a plan, propose the fix — not just the problem: - -- **A task is too large (XL):** Split it into vertical slices. Each slice should be independently testable. -- **Missing acceptance criteria:** Draft 2–3 specific, testable conditions for the task. -- **Wrong sequencing:** Identify the dependency and propose the correct order. -- **No checkpoints:** Suggest where checkpoints should go (typically after every 2–3 tasks). -- **Vague verification:** Replace "run tests" with the actual project command. -- **Horizontal slicing:** Restructure into vertical feature paths. -- **Missing risk section:** Draft the risks you can identify from the plan content. - -Prefer the remedy that makes the plan immediately actionable over one that just flags the gap. - -## Plan Sizing - -Plans should be scoped to a single deliverable: - -``` -1–5 tasks → Good. A focused feature or bug fix. -6–10 tasks → Acceptable for a moderate feature. -11–15 tasks → Large. Consider splitting into phases. -15+ tasks → Too large. Split into multiple plans. -``` - -**What counts as "one plan":** A self-contained set of changes that delivers a single coherent capability. If you can describe the goal in one sentence, it's one plan. - -## Categorize Findings - -Label every comment with its severity so the author knows what's required vs optional: - -| Prefix | Meaning | Author Action | -|--------|---------|---------------| -| *(no prefix)* | Required change | Must address before implementation starts | -| **Critical:** | Blocks implementation | Missing security consideration, data integrity risk, fundamentally wrong approach | -| **Nit:** | Minor, optional | Author may ignore — wording, formatting | -| **Optional:** / **Consider:** | Suggestion | Worth considering but not required | -| **FYI** | Informational only | No action needed — context for future reference | - -**Lead with what matters.** Order findings by leverage: missing risks and wrong sequencing first, then task quality gaps, then completeness, then nits. If you have one critical sequencing problem and ten nits, the sequencing problem *is* the review. - -## Review Process - -### Step 1: Understand the Goal - -Before evaluating structure, understand intent: - -``` -- What is this plan trying to accomplish? -- What problem does it solve? -- What does "done" look like? -``` - -### Step 2: Check Completeness First - -Scan for missing sections before diving into content: - -``` -- Context present? -- Affected modules listed? -- Architecture decisions documented? -- Risks acknowledged? -- Testing strategy defined? -- Verification commands explicit? -``` - -### Step 3: Review Task Quality - -Walk through each task: - -``` -For each task: -1. Can I tell exactly what to build? -2. Are acceptance criteria specific and testable? -3. Is the size reasonable (not XL)? -4. Are dependencies clear? -5. Would I know which files to touch? -``` - -### Step 4: Validate Sequencing - -Check the dependency graph: - -``` -- Are foundations built first? -- Does each task leave the system working? -- Are checkpoints placed correctly? -- Are high-risk items early? -- Is it vertically sliced? -``` - -### Step 5: Assess Actionability - -Put yourself in the implementer's shoes: - -``` -- Could I pick up task 1 and start coding without asking any questions? -- Are the verification commands copy-pasteable? -- Are file paths and function names specific? -- Is existing code referenced where I'd need to read it? -``` - -### Step 6: Verify the Verification Story - -Check that the plan can actually confirm it worked: - -``` -- What tests should pass after implementation? -- What build/compile commands are relevant? -- What manual checks are needed? -- How do we know the feature works end-to-end? -``` - -### Step 7: Evaluate Proposed Code Quality *(if applicable)* - -If the plan includes code snippets, types, or API designs: - -``` -- Load code-review-criteria skill for criteria -- Check proposed signatures for edge cases -- Verify naming follows project conventions -- Confirm abstractions follow existing patterns -- Scan for security vectors in proposed APIs -- Check for performance issues in proposed data structures -``` - -## Review Checklist - -```markdown -## Review: [Plan title] - -### Completeness -- [ ] Context explains the problem and goal -- [ ] Affected modules are listed with paths -- [ ] Architecture decisions have rationale -- [ ] Testing strategy is defined -- [ ] Verification commands are explicit and project-specific -- [ ] Open questions are listed - -### Task Quality -- [ ] Every task has acceptance criteria -- [ ] Every task has verification steps -- [ ] Tasks are sized XS–M (L acceptable, XL must be split) -- [ ] Task dependencies are stated -- [ ] Files likely touched are listed - -### Architecture & Sequencing -- [ ] Order follows dependency graph (foundations first) -- [ ] Vertically sliced (not horizontal layers) -- [ ] Each task leaves system working -- [ ] Checkpoints exist between phases -- [ ] High-risk tasks are early - -### Risk Coverage -- [ ] Edge cases identified -- [ ] Breaking changes / migrations noted -- [ ] Security implications considered -- [ ] Performance implications considered -- [ ] Rollback strategy exists (if applicable) - -### Actionability -- [ ] File paths are specific -- [ ] Verification commands are copy-pasteable -- [ ] Existing code to read is referenced -- [ ] Conventions and patterns are noted - -### Proposed Code Quality *(if plan includes implementation details)* -- [ ] Proposed types/signatures handle edge cases -- [ ] Proposed names follow project conventions -- [ ] Proposed abstractions follow existing patterns -- [ ] No security vectors in proposed APIs -- [ ] No performance issues in proposed structures - -### Verdict -- [ ] **Approve** — Ready to implement -- [ ] **Request changes** — Gaps must be addressed -``` - -## Common Rationalizations - -| Rationalization | Reality | -|---|---| -| "I'll figure out the details during implementation" | That's how you discover blocking dependencies mid-task. Surface them now. | -| "The tasks are obvious, no need for criteria" | Write them anyway. Explicit criteria surface hidden assumptions. | -| "It's just a small feature, it doesn't need a plan" | Small features have edge cases too. 3 tasks with criteria takes 5 minutes. | -| "The plan is good enough" | "Good enough" without acceptance criteria means the implementer defines "done" — and they might define it differently. | -| "I'll add verification steps later" | Later never comes. The plan is the contract — define verification now. | -| "Risks are minimal" | Every change has risks. If you can't name them, you haven't thought about them. | -| "The file paths are obvious" | They're obvious to the author. The implementer might not know the codebase. | -| "The code in the plan is fine, it'll get reviewed later" | Plan-level code review catches design problems before implementation — fixing them after coding is more expensive. | - -## Red Flags - -- No acceptance criteria on any task -- Tasks that say "implement the feature" without specifics -- No verification steps anywhere in the plan -- All tasks are XL-sized -- No checkpoints between phases -- Dependency order isn't considered (e.g., API handler before domain model) -- No testing strategy -- Verification commands are generic ("run tests") instead of project-specific -- Plan has 20+ tasks (scope too large for one plan) -- No risk section on a plan with migrations, breaking changes, or security implications -- Horizontal slicing (all domain, then all services, then all API) -- File paths are vague ("update the relevant files") -- Missing open questions section despite stated unknowns -- Proposed code ignores project conventions or existing patterns -- Proposed types use gratuitous `any`/`unknown`/optional without justification -- Proposed APIs don't validate input at boundaries - -## See Also - -- For producing plans, use the `planner` skill -- For reviewing implemented code, use `code-review-criteria` — also the criteria source for axis 6 -- For security-specific concerns, see `security-and-hardening` -- For testing strategy guidance, see `testing` +Are the problem, intended outcome, affected areas and relevant constraints +clear? Does the plan explain important decisions and include an appropriate +testing strategy? Identify missing information that would change the outcome +or force an implementer to guess. Require risk, rollback, migration or +parallelization details only when relevant. + +### 2. Task quality + +Are tasks scoped, ordered and specific enough to execute? Check likely files, +dependencies, rationale, acceptance criteria and verification where relevant. +Acceptance criteria should describe observable behavior, including important +failure cases. Split work when it is too large to understand or verify safely, +not merely because it crosses an arbitrary task count. + +### 3. Architecture and sequencing + +Does the approach fit the existing architecture and reuse appropriate +facilities? Do dependencies precede their consumers, and can the work be +verified as it progresses? Prefer independently testable slices where useful; +use checkpoints where risk or coordination warrants them, not at a fixed +interval. Flag unrelated work or abstractions that add complexity without +helping the goal. + +### 4. Risk coverage + +Consider relevant edge cases, security, performance, compatibility, data +integrity, migrations and external dependencies. Where failure has meaningful +consequences, check detection, mitigation and rollback or recovery. Do not +invent risks or demand a rollback section for changes that do not need one. + +### 5. Actionability and verification + +Can the implementer identify the affected code, follow project conventions and +run the stated project-specific checks? Are commands and prerequisites correct? +Do tests and other checks demonstrate the intended behavior and important +failure cases? Surface unknowns honestly rather than presenting an unverified +command or assumption as fact. + +### 6. Proposed solution quality + +Assess correctness, clarity, architecture, security and performance of the +proposed solution, even when the plan contains no code. For any code sketches, +also check boundary cases, names, types and contracts. Preserve intended +behavior unless a change is explicitly agreed; prefer the simplest solution +that meets the requirements. + +## Findings and verdict + +Give each reported item a stable ID (`P1`, `P2`, …); retain it throughout the +review and any decision walkthrough. For each item state the evidence, impact, +concrete remedy and verification needed. For a consequential user decision, +include real options, consequences and a recommendation. + +- **Blocking:** implementation cannot proceed safely or an essential user + decision remains open. Explain what blocks it. +- **Improvement:** a clear correction that preserves the agreed goal, scope + and behavior. Apply it under `review-plan`'s permitted-edit rules. +- **Optional:** a suggestion that does not prevent implementation. Do not + silently expand scope or override the user's decisions. + +Report applied improvements and any outstanding items with their IDs. Give a +provisional verdict before any walkthrough and a final verdict after applying +the decisions: + +- **Ready:** no blocking issue or essential decision remains. +- **Awaiting decisions:** user decisions are needed before the plan is ready. +- **Blocked:** required work or evidence is missing and cannot be resolved by + applying clear improvements or obtaining the current decisions alone. + +Do not approve an unresolved blocker. A plan may be ready with optional +suggestions; identify them without treating them as required. diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index f09f084a6c..564db4faa8 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md @@ -29,7 +29,9 @@ Act as a senior software engineer and perform a thorough code review. code being reviewed. - Return the COMPLETE review, verbatim, exactly as the skill instructs it to be produced. Never summarize it. - - Read-only: modify no file and create no commit. Reviewing never writes. + - Read-only: modify no file, create no commit, and run no tests, builds, + linters or other state-changing checks. Use prior results or CI evidence; + state explicitly when evidence is unavailable. - Do not invent problems: every finding must be real and actionable. - Missing tests are an issue, not a suggestion — a severity-tagged finding. - For each finding, give a concrete remedy and the tests needed to verify it. @@ -37,8 +39,8 @@ Act as a senior software engineer and perform a thorough code review. in that finding. Do not pause to ask during the review. - Prioritize by impact: one structural issue outweighs ten nits, and "this could be better" is not a finding — say why and how. - - Skip generated files, lockfile-only changes and unrelated modifications - unless they introduce security risks. + - Inspect generated files and lockfiles when relevant to the change, its + dependencies or security; exclude unrelated working-tree modifications. 3. When the subagent returns, output the review to the user verbatim. Do not summarize it and do not act on its findings. Retain the subagent session ID, review target and complete findings in the session context for follow-up; @@ -46,8 +48,8 @@ Act as a senior software engineer and perform a thorough code review. 4. Right after the review, suggest how to proceed based on the findings. These are suggestions — the user decides: - **Approve (no required changes):** say so — there is nothing to address. - - **Minor findings (nits):** applying them directly as-is is fine once the - review is done — no plan needed. + - **Minor findings:** suggest direct fixes after the user ends the review if + appropriate; no plan is required. - **Substantive findings:** suggest `@make-a-plan` to make a plan to address them. - If the user wants to discuss findings one by one, use `@issue-walkthrough` @@ -82,9 +84,10 @@ This flow is read-only **for the duration of the review**: from the moment it starts until the user considers the review finished (including any feedback, questions, or clarifications about it). During that period, never fix, implement, edit files or create commits — not even "obvious" fixes derived from -the findings. Once the user explicitly states the review is done (or moves on to -a different task), this rule no longer applies and you act as a normal build -agent again. +the findings. Never run tests, builds, linters or state-changing checks during +the review; inspect existing evidence instead. Once the user explicitly states +the review is done (or moves on to a different task), this rule no longer +applies and you act as a normal build agent again. ## Posting as a GitHub comment @@ -100,7 +103,7 @@ session. PR comments go in English, with this minimal structure: problem, concrete remedy. 4. **Closing** — optional and short. Cut it when it adds nothing. -Reference every finding by its ID (`R1`, `M1`, `S1`, … from +Reference every finding by its ID (`F1`, `F2`, … from `code-review-criteria`) so follow-up replies can point to findings unambiguously. From 9b24b6c7c950567f30aa9de41cd0b09c9b4f680b Mon Sep 17 00:00:00 2001 From: Andrey Antukh <niwi@niwi.nz> Date: Wed, 18 Nov 2026 19:06:44 +0000 Subject: [PATCH 09/10] :books: Improve agent workflow safeguards Protect staged changes when rewriting commit messages and close plans after verified commits. Clarify checks and remove the unused Taiga skill. AI-assisted-by: gpt-6.1-terra --- .agents/README.md | 1 - .agents/skills/create-commit/SKILL.md | 16 +-- .agents/skills/implement-plan/SKILL.md | 15 +-- .agents/skills/local-ci/SKILL.md | 2 +- .agents/skills/planner/SKILL.md | 7 +- .../skills/rewrite-commit-message/SKILL.md | 15 +-- .agents/skills/ripgrep/SKILL.md | 2 +- .agents/skills/taiga/SKILL.md | 116 ------------------ 8 files changed, 27 insertions(+), 147 deletions(-) delete mode 100644 .agents/skills/taiga/SKILL.md diff --git a/.agents/README.md b/.agents/README.md index 05722cff38..98937323af 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -508,7 +508,6 @@ JSON, REPL access, and so on. | [`ripgrep`](skills/ripgrep/SKILL.md) | Fast content search with regular expressions. | | [`jq-json-processor`](skills/jq-json-processor/SKILL.md) | Slice, filter, and reshape JSON output. | | [`nrepl-eval`](skills/nrepl-eval/SKILL.md) | Run Clojure or ClojureScript code in the live REPL sessions (backend and frontend). | -| [`taiga`](skills/taiga/SKILL.md) | Look up Penpot issues, user stories, and tasks in Taiga. | | [`testing`](skills/testing/SKILL.md) | The repo's testing rules and TDD workflow, loaded before writing tests. | | [`local-ci`](skills/local-ci/SKILL.md) | Run CI-style lint, test, and format checks for the modules you touched with `scripts/ci`, and read the logs when they fail. | | [`security-and-hardening`](skills/security-and-hardening/SKILL.md) | Security checks for code that handles user input, auth, or external services. | diff --git a/.agents/skills/create-commit/SKILL.md b/.agents/skills/create-commit/SKILL.md index 264f870e03..2a49b29dc8 100644 --- a/.agents/skills/create-commit/SKILL.md +++ b/.agents/skills/create-commit/SKILL.md @@ -7,7 +7,7 @@ slash: true # Skill: create-commit Produce a git commit that follows Penpot's commit message conventions. This -skill owns the commit format, staging review, and safety checks — it does not +skill handles staging review and safety checks — it does not implement features or push. ## When to Use @@ -23,15 +23,9 @@ subject/body limits, and the `AI-assisted-by` trailer. Follow it exactly. ## Iron Rules (non-negotiable) -1. **Wrap every body line at 80 characters or fewer.** Count characters, do - not eyeball. Exceptions: `Signed-off-by:` / `AI-assisted-by:` trailers and - lines carrying a URL. This is the rule agents skip most often. -2. **Subject ≤80 chars**, imperative, capitalized, no trailing period. - `Merge`/`Revert`/`Reapply` commits skip the length check. -3. **Blank line between subject and body.** -4. **Run `./scripts/check-commit` and require exit code 0.** It mechanically - checks rules 1–3. A non-zero exit is a hard blocker: fix the message and - re-commit. Never report the commit as done with a failing checker. +Follow the message rules and exceptions in `mem:workflow/creating-commits`. +**Run `./scripts/check-commit` and require exit code 0.** A non-zero exit is a +hard blocker: fix the message and re-check it before reporting success. ## Workflow @@ -67,4 +61,4 @@ subject/body limits, and the `AI-assisted-by` trailer. Follow it exactly. bots are rejected by `./scripts/check-commit`; for AI participation use the `AI-assisted-by:` trailer. - Do not add untracked files that were not created in this session. -- Do not skip the `scripts/check-commit` verification step (Iron Rule 4). +- Do not skip the `scripts/check-commit` verification step. diff --git a/.agents/skills/implement-plan/SKILL.md b/.agents/skills/implement-plan/SKILL.md index 31e1eee9ca..20dbce4d75 100644 --- a/.agents/skills/implement-plan/SKILL.md +++ b/.agents/skills/implement-plan/SKILL.md @@ -116,19 +116,20 @@ Implement every task in one go. Work methodically, keeping changes focused on what the issue requires. Respect the plan's proposed parallelization when it applies. -When the implementation is complete, close the plan file first: flip its -`Status` to `done` and append one UTC ISO 8601 line to its `Review Log` -with the issue URL when one exists (standalone mode, e.g. -`https://github.com/penpot/penpot/issues/NNNN`); in continue/direct -mode with no issue, just `done` with no invented identifier. Never -record commit hashes. Leave the closed plan file local and uncommitted. -Then load the **`create-commit`** skill and follow its workflow to commit +When the implementation is complete, load the **`create-commit`** skill and +follow its workflow to commit only the implementation, tests, memory, and documentation changes. Before committing, verify that the staged file list does not contain the plan file. Provide a brief summary of what was implemented and why, the issue reference (`issue-NNNN`) when there is one, and the model name you are running as so the `AI-assisted-by` trailer is set correctly. +Only after the commit exists and passes its checks, close the plan: flip +`Status` to `done` and append one UTC ISO 8601 line to `Review Log` with the +issue URL when one exists; otherwise record `done` without inventing an +identifier. Never record commit hashes. Leave the plan local and uncommitted. +If the commit or its checks fail, do not close the plan. + ### Step-by-step mode (on request) When the user asks for it — "step by step", "task by task", "one commit diff --git a/.agents/skills/local-ci/SKILL.md b/.agents/skills/local-ci/SKILL.md index d04f581dc1..c6ab6d30b7 100644 --- a/.agents/skills/local-ci/SKILL.md +++ b/.agents/skills/local-ci/SKILL.md @@ -86,7 +86,7 @@ log path. ./scripts/ci --lint frontend # Changed common/ — validate its consumers too -./scripts/ci frontend backend exporter +./scripts/ci common frontend backend exporter # Preview what would run, without running it ./scripts/ci --dry-run --all diff --git a/.agents/skills/planner/SKILL.md b/.agents/skills/planner/SKILL.md index 7059189596..7874bbccfd 100644 --- a/.agents/skills/planner/SKILL.md +++ b/.agents/skills/planner/SKILL.md @@ -42,9 +42,10 @@ Skipping this step is the #1 cause of incorrect or incomplete plans. only file you may write is the plan itself, and only when the command or user explicitly instructs you to save it. - You do **not** run builds, tests, linters, or any commands that modify state. -- You do **not** create git commits or interact with version control. -- You do **not** execute shell commands beyond read-only searches (`rg`, `ls`, - `find`, `cat`, `bat`). +- You do **not** create commits or run commands that modify version control. + Read-only inspection such as `git status`, `git log`, `git show` and + `git diff` is allowed. +- Shell commands must be read-only. - Your output is a structured plan or analysis, ready for handoff to an engineer agent or developer. diff --git a/.agents/skills/rewrite-commit-message/SKILL.md b/.agents/skills/rewrite-commit-message/SKILL.md index 3281d0fa75..7284f0721b 100644 --- a/.agents/skills/rewrite-commit-message/SKILL.md +++ b/.agents/skills/rewrite-commit-message/SKILL.md @@ -6,9 +6,8 @@ slash: true # Skill: rewrite-commit-message -HEAD's message is a concatenation of older messages (typical after a -squash): several subjects, bodies and repeated trailers stacked in a -single message. Replace it with one proper message and amend HEAD. +Rewrite HEAD's title and description from its own diff. This also handles a +squash message with several subjects, bodies and repeated trailers. ## When to Use @@ -17,9 +16,11 @@ single message. Replace it with one proper message and amend HEAD. ## Steps -1. Read the full current message (`git log -1 --format=%B HEAD`) and - the branch diff (`git diff develop..HEAD --stat`, plus the code - when the summary needs grounding). +1. Check `git diff --cached` first. If any changes are staged, stop and ask + the user to handle them; an amend must never include those changes. Read + the full current message (`git log -1 --format=%B HEAD`) and HEAD's own + diff (`git show --format= --stat HEAD` and the patch). Respect the project + rule on amending pushed commits. 2. Collect every DISTINCT `AI-assisted-by:` value in the current message. All of them survive into the new message, one line each: attributions are never dropped in a rewrite, even when most of @@ -27,7 +28,7 @@ single message. Replace it with one proper message and amend HEAD. 3. Draft one message per `mem:workflow/creating-commits` (read it end-to-end first): single subject (imperative, capitalized, no trailing period, ≤80 chars), blank line, body wrapped at ≤80 - chars covering the whole diff (not the old per-commit slices), + chars covering HEAD's diff (not the old per-commit slices), then the preserved trailers. 4. Write it to a file (a heredoc keeps real newlines; inline `-m` with `\n` does not) and `git commit --amend -F <file>`. diff --git a/.agents/skills/ripgrep/SKILL.md b/.agents/skills/ripgrep/SKILL.md index 1b028d8c58..e7690ed9e8 100644 --- a/.agents/skills/ripgrep/SKILL.md +++ b/.agents/skills/ripgrep/SKILL.md @@ -67,7 +67,7 @@ rg "user_\d+" rg -F "function()" # Multiline search -rg -U "start.*end" +rg -U '(?s)start.*end' # Only show matches, not lines rg -o "https?://[^\s]+" diff --git a/.agents/skills/taiga/SKILL.md b/.agents/skills/taiga/SKILL.md deleted file mode 100644 index a5f32565a1..0000000000 --- a/.agents/skills/taiga/SKILL.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -name: taiga -description: Fetch information from Taiga public API for the Penpot project (id 345963) — issues, user stories, and tasks, without authentication. -metadata: {"clawdbot":{"requires":{"bins":["python3"]}}} ---- - -# Taiga API Skill - -Fetch information from Taiga public API for the **Penpot** project -(project id: `345963`, slug: `penpot`). - -**No authentication required** — only public project data is accessed. - -## When to use - -- The user asks about Penpot issues, user stories, or tasks tracked in - Taiga — fetch them via the public API (project id 345963), no - authentication needed. - -## Prerequisites - -- `python3` — the `scripts/taiga.py` CLI script is self-contained (stdlib only) - -## Quick Start - -The easiest way is to use the bundled Python script: - -```bash -# Pass a Taiga URL directly -python3 scripts/taiga.py https://tree.taiga.io/project/penpot/issue/13714 - -# Or use "<type> <ref>" syntax -python3 scripts/taiga.py us 14128 -python3 scripts/taiga.py task 13648 - -# Add --json for raw output -python3 scripts/taiga.py --json issue 13714 - -# See full usage -python3 scripts/taiga.py --help -``` - -## URL Pattern Reference - -Taiga web URLs follow these patterns: - -| Type | Web URL Pattern | -|------|----------------| -| Issue | `https://tree.taiga.io/project/penpot/issue/<REF>` | -| User Story | `https://tree.taiga.io/project/penpot/us/<REF>` | -| Task | `https://tree.taiga.io/project/penpot/task/<REF>` | - -To extract the **type** and **ref** from a URL: -- `issue/13714` → type=`issue`, ref=`13714` -- `us/14128` → type=`us`, ref=`14128` -- `task/13648` → type=`task`, ref=`13648` - -## Python Script Reference - -The `scripts/taiga.py` script wraps the Taiga API into a single convenient CLI -with sensible defaults. - -### Usage - -``` -python3 scripts/taiga.py <taiga-url> -python3 scripts/taiga.py <type> <ref> -python3 scripts/taiga.py [--json] <taiga-url> -python3 scripts/taiga.py [--json] <type> <ref> -``` - -### Examples - -```bash -# By URL (recommended — no need to think about type/ref) -python3 scripts/taiga.py https://tree.taiga.io/project/penpot/issue/13714 - -# By type and ref -python3 scripts/taiga.py us 14128 -python3 scripts/taiga.py task 13648 - -# Raw JSON output -python3 scripts/taiga.py --json issue 13714 -``` - -### Output - -The script prints a clean, structured summary: - -```text -User Story #11964 — 🔴 [DESIGN TOKENS] Typography Composite Input -================================ -Status: Defining -Milestone: design-systems-sprint-26 -Points: 3 role(s) -Assignee: Natacha Menjibar -Author: Natacha Menjibar -Created: 2025-09-01 -Tags: iop-design-tokens -URL: https://tree.taiga.io/project/penpot/us/11964 -================================ -<full description text, unmodified> -``` - -The fields section includes type-specific information: -- **Issues:** Status, Type ID, Severity ID, Priority ID -- **User Stories:** Status, Milestone, Points -- **Tasks:** Status, Milestone, Parent US - -## Reference - -- API docs: https://docs.taiga.io/api.html -- Taiga instance: https://tree.taiga.io -- API base: https://api.taiga.io/api/v1 -- Penpot project id: `345963` -- Penpot project slug: `penpot` From 7916e5e073b5165864bded9a8511bf559929476d Mon Sep 17 00:00:00 2001 From: Andrey Antukh <niwi@niwi.nz> Date: Wed, 18 Nov 2026 19:12:59 +0000 Subject: [PATCH 10/10] :books: Clarify agent memory guidance Promote Clojure design rules to a required core memory and simplify the discovery guide. Correct test output redirection and RPC routes. AI-assisted-by: gpt-6.1-terra --- .serena/memories/backend/core.md | 2 +- .../clojure/{design-rules.md => core.md} | 4 ++-- .serena/memories/clojure/idioms.md | 2 +- .serena/memories/critical-info.md | 3 +-- .serena/memories/testing.md | 4 ++-- AGENTS.md | 20 ++++++------------- 6 files changed, 13 insertions(+), 22 deletions(-) rename .serena/memories/clojure/{design-rules.md => core.md} (93%) diff --git a/.serena/memories/backend/core.md b/.serena/memories/backend/core.md index de55cfa1de..0a066d89cf 100644 --- a/.serena/memories/backend/core.md +++ b/.serena/memories/backend/core.md @@ -14,7 +14,7 @@ Backend: JVM Clojure; Integrant; PostgreSQL; Redis/Valkey; RPC; HTTP; storage; m ## Stable namespace map -- `app.rpc.commands.*`: RPC command implementations exposed under `/api/rpc/command/<cmd-name>`. +- `app.rpc.commands.*`: RPC command implementations exposed under `/api/main/methods/<method-name>`; `/api/rpc/command/<method-name>` remains as a backward-compatible route. - `app.rpc.permissions`: permission predicate/check helper factories. - `app.http.*`: HTTP routes and middleware. - `app.auth.*`: provider-specific authentication helpers such as LDAP/OIDC. diff --git a/.serena/memories/clojure/design-rules.md b/.serena/memories/clojure/core.md similarity index 93% rename from .serena/memories/clojure/design-rules.md rename to .serena/memories/clojure/core.md index 2b439ee038..203ae823b3 100644 --- a/.serena/memories/clojure/design-rules.md +++ b/.serena/memories/clojure/core.md @@ -1,4 +1,4 @@ -# Clojure Design Rules +# Clojure Core How to shape a function in this codebase. Each rule came from a review round; do not re-derive from taste. @@ -11,4 +11,4 @@ How to shape a function in this codebase. Each rule came from a review round; do Reference implementation: the http metrics samplers in `app.http` (`sample-worker-metrics` / `sample-connector-metrics` are guard-free; `sample-http-metrics` guards at the boundary). -See also: `mem:clojure/idioms` (language behaviors), `mem:testing` (TDD and test conventions). +See also: `mem:clojure/idioms` (language behaviors and naming exceptions), `mem:clojure/logging` (structured logging), `mem:testing` (TDD and test conventions). diff --git a/.serena/memories/clojure/idioms.md b/.serena/memories/clojure/idioms.md index cf85848c3a..e901805542 100644 --- a/.serena/memories/clojure/idioms.md +++ b/.serena/memories/clojure/idioms.md @@ -8,5 +8,5 @@ Behaviors confirmed against the language/stdlib — do not re-derive from assump - The analyzer reads `:async` only from the fn name meta and the `fn` operator meta; list-level meta is ignored (would make a MetaFn). `(fn ^:async [] …)` puts the meta on argv (pre/post only, NOT async). - Valid: `(defn ^:async f)`, `(defn- ^:async f)`, `(^:async fn [] …)` (the latter is what stock `t/async` generates itself). - `^:async` fns never throw synchronously (rejected promises instead); `try/catch/finally` supported; continuations are microtasks, timers and RxJS schedulers are macrotasks (FIFO). -- `!` suffix allowed cases (only exceptions to the no-new-`!` rule in `mem:clojure/design-rules`): mutating public `app.db` API (`insert!`, `update!`, `delete!`, `run!`, `tx-run!`, `exec!`, ...) and fns whose contract is to work over transients (stdlib `conj!`, `assoc!`, `dissoc!`, `disj!`, `persistent!` and custom helpers over them); any further case must be registered here with justification before use. +- `!` suffix allowed cases (only exceptions to the no-new-`!` rule in `mem:clojure/core`): mutating public `app.db` API (`insert!`, `update!`, `delete!`, `run!`, `tx-run!`, `exec!`, ...) and fns whose contract is to work over transients (stdlib `conj!`, `assoc!`, `dissoc!`, `disj!`, `persistent!` and custom helpers over them); any further case must be registered here with justification before use. - `cuerdas.core/index-of` returns `nil` (not `-1`) when the substring is absent, like `clojure.string/index-of`. `(pos? nil)` **throws on the JVM** but evaluates to `false` in CLJS (JS coercion), so `(if (pos? (str/index-of s "\n")) …)` works in the browser and crashes the backend. Guard with `some?` before `pos?` (this was `app.common.exceptions/first-line`). diff --git a/.serena/memories/critical-info.md b/.serena/memories/critical-info.md index ac15e674bd..15b1fc04cb 100644 --- a/.serena/memories/critical-info.md +++ b/.serena/memories/critical-info.md @@ -8,7 +8,7 @@ You are working on the GitHub project `penpot/penpot`, a monorepo. - Cross-cutting testing principles, TDD workflow, and anti-patterns: `mem:testing`. - Structured logging conventions (`:hint` casing and fields, log levels): `mem:clojure/logging` — read before adding or changing any log call. - Verified Clojure language behaviors that contradict common assumptions (e.g. `int?` covers `Long`; `integer?` is the general predicate): `mem:clojure/idioms` — read before assuming stdlib predicate semantics. -- Read `mem:clojure/design-rules` (function shape, boundary checks, naming) before writing or modifying Clojure/ClojureScript code — not only when designing a solution or an API. +- Read `mem:clojure/core` (function shape, boundary checks, naming) before writing or modifying Clojure/ClojureScript code — not only when designing a solution or an API. # Development workflow @@ -23,7 +23,6 @@ You are working on the GitHub project `penpot/penpot`, a monorepo. - **Never `git push`, force-push, or modify `git origin`** (or any other remote). The user pushes from their own shell; if a push is required, say so and wait. Never amend a commit that the user has already pushed unless explicitly asked. - **Never edit `CHANGES.md` by hand.** The changelog is generated from GitHub milestones during the release process; update it only via `mem:workflow/updating-changelog` (the `update-changelog` skill flow) or on explicit user request. - You have access to the GitHub CLI `gh` or corresponding MCP tools. -- Issues are also managed on Taiga. Read issues using the `read_taiga_issue` tool. - Before writing code, analyze the task in depth and describe your plan. If the task is complex, break it down into atomic steps. After making changes, run the applicable lint and format checks for the affected module before considering the work done (per example `mem:backend/core` or `mem:frontend/core`). - Align `let` binding values: when a `let` form has multiple bindings spanning several lines, align the value forms to the same column with spaces. - If you introduce delimiter errors (mismatched parens/brackets) in Clojure/CLJS files, fix them with `scripts/paren-repair` BEFORE running lint/format checks. See `mem:scripts/paren-repair` for usage. diff --git a/.serena/memories/testing.md b/.serena/memories/testing.md index ce301ff5bb..9112a05369 100644 --- a/.serena/memories/testing.md +++ b/.serena/memories/testing.md @@ -142,10 +142,10 @@ E2E tests should not be added unless explicitly requested. When running ANY test command (CLJS/JS or JVM): 1. **NEVER pipe test output directly to `| head`, `| tail`, `| grep`, or similar filters** — this can hide failures and cause you to miss critical errors. -2. **ALWAYS pipe to a file first, then read the file:** +2. **ALWAYS redirect to a file first, then read the file:** ```bash # CORRECT: - pnpm run test 2>&1 > /tmp/test-output.txt + pnpm run test > /tmp/test-output.txt 2>&1 grep -A 5 "failures" /tmp/test-output.txt # WRONG: diff --git a/AGENTS.md b/AGENTS.md index c39c02dcaf..c80c764bf4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -39,6 +39,8 @@ Do this **before planning, before coding, before touching any file**: 3. Read each affected module's **core memory** — the name is `<module>/core` (e.g. `frontend/core`, `backend/core`, `common/core`). 4. If the core memory references deeper `mem:` memories relevant to your task, read those too. +5. Before writing or modifying Clojure or ClojureScript, read `mem:clojure/core` + and the relevant focused Clojure memories it references. **STOP: Do not proceed until you have read the core memory of every affected module.** Skipping this step is the #1 cause of incorrect or incomplete work. @@ -80,11 +82,6 @@ Review every prose output against these rules before delivering. Memories are the **primary project guidance** — not docs or readme files. They are dense, agent-oriented notes: terse bullets, invariants, no prose. -## Entry point - -Start at `critical-info` (the graph root). It describes the project structure, -module dependency graph, and references section-level core memories. - ## Progressive discovery model Memories form a **reference graph**, not a flat list: @@ -96,11 +93,8 @@ critical-info ← read first (graph root) └─ ... ← deeper memories as needed ``` -When working on a task: -1. Read `critical-info` to identify which sections are affected. -2. Read the affected section's `core` memory for an overview. -3. Follow `mem:` references in the core memory to focused memories relevant to your task. -4. Continue following references deeper as needed. +Follow the mandatory reading sequence above. Cross-cutting topics can also be +referenced directly from `critical-info` or other memories. ## Accessing memories @@ -117,9 +111,8 @@ When you encounter a `mem:` reference relevant to your task, read that memory ne ## Topic/folder organization -Memories are grouped into folders that mirror project modules or topics: -`backend/`, `common/`, `frontend/`, `render-wasm/`, `exporter/`, `workflow/`, etc. -Each folder's top-level memory is `<folder>/core`. +Memories are grouped into folders for modules or topics. Project modules have +a `<module>/core` memory; other topic folders may contain focused memories only. --- @@ -155,4 +148,3 @@ precision while maintaining a strong focus on maintainability and performance. - `scripts/check-fmt-clj` — Check Clojure formatting without modifying files. - `scripts/ci` — CI orchestration script for running lint, tests, format checks and, on request (`--build`), production builds across modules. See `mem:scripts/ci`. - `scripts/gh.py` — Multi-purpose GitHub CLI helper. Subcommands: `issues` (list issues in a milestone), `prs` (fetch PR details), `advisories` (list/inspect security advisories). See `python3 scripts/gh.py --help`. -