refcount linter

.github/workflows/refcount.yml

@@ -0,0 +1,63 @@
+name: Refcount lint
+
+on:
+  pull_request:
+    paths:
+      - 'build.zig'
+      - 'build.zig.zon'
+      - 'ext/**'
+      - '!ext/**.md'
+      - 'pkg/**'
+      - 'tools/refcount-check/**'
+      - '.github/workflows/refcount.yml'
+
+jobs:
+  refcount:
+    runs-on: ubuntu-24.04
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: mlugg/setup-zig@v2
+        with:
+          version: 0.15.2
+          # 8GB cache limit chosen at random
+          cache-size-limit: 8192
+
+      # the checker loads libclang at runtime; pin the major version the
+      # @Refcount annotations are validated against. libclang 18 anchors
+      # macro-expanded operator cursors differently, defeating the
+      # checker's macro-origin exemption (false [strange expression]
+      # findings on u3a_to_ptr-style word punning)
+      - name: Install libclang 19
+        run: |
+          sudo apt-get update
+          if ! sudo apt-get install -y --no-install-recommends libclang-19-dev; then
+            wget -qO /tmp/llvm.sh https://apt.llvm.org/llvm.sh
+            sudo bash /tmp/llvm.sh 19
+            sudo apt-get install -y --no-install-recommends libclang-19-dev
+          fi
+
+      # independent tasks: cargo does not need the compile db, only the
+      # lint run does. wait for both before failing so neither is orphaned
+      - name: Generate compile_commands.json, build refcount-check
+        run: |
+          zig build -Dgenerate-commands --summary all &
+          zig_pid=$!
+          cargo build --manifest-path tools/refcount-check/Cargo.toml &
+          cargo_pid=$!
+          zig_rc=0; cargo_rc=0
+          wait "$zig_pid"   || zig_rc=$?
+          wait "$cargo_pid" || cargo_rc=$?
+          [ "$zig_rc" -eq 0 ] && [ "$cargo_rc" -eq 0 ]
+
+      - name: Run selftest
+        run: |
+          ./tools/refcount-check/target/debug/refcount-check \
+            --selftest \
+            --libclang /usr/lib/llvm-19/lib/libclang.so
+
+      - name: Run refcount lint
+        run: |
+          ./tools/refcount-check/target/debug/refcount-check \
+            --libclang /usr/lib/llvm-19/lib/libclang.so

.gitignore

@@ -31,6 +31,9 @@ GPATH
 GRTAGS
 GTAGS
 
+# Tools
+tools/__pycache__
+
 # Fake ships.
 /zod
 /nec

pkg/noun/allocate.c

@@ -1,4 +1,6 @@
 /// @file
+/// @Refcount: all functions are custom unless asserted otherwise
+/// -- implements or sits below the refcount machinery.
 
 #include "allocate.h"
 
@@ -468,6 +470,7 @@ _me_wash_south(u3_noun dog)
 }
 
 /* u3a_wash(): wash all lazy mugs.  RETAIN.
+** @Refcount: retains arguments
 */
 void
 u3a_wash(u3_noun som)
@@ -1207,6 +1210,7 @@ u3a_mark_rptr(void* ptr_v)
 }
 
 /* u3a_mark_noun(): mark a noun for gc.  Produce size.
+** @Refcount: retains arguments
 */
 c3_w
 u3a_mark_noun(u3_noun som)
@@ -1567,6 +1571,7 @@ _ca_prof_mark(u3_noun som)
 }
 
 /* u3a_prof(): mark/measure/print memory profile. RETAIN.
+** @Refcount: retains arguments
 */
 u3m_quac*
 u3a_prof(FILE* fil_u, u3_noun mas)
@@ -2015,6 +2020,7 @@ _ca_detect(u3p(u3h_root) har_p, u3_noun fum, u3_noun som, c3_d axe_d)
 /* u3a_detect(): for debugging, check if (som) is referenced from (fum).
 **
 ** (som) and (fum) are both RETAINED.
+** @Refcount: retains arguments
 */
 c3_d
 u3a_detect(u3_noun fum, u3_noun som)
@@ -2110,6 +2116,7 @@ u3a_walk_fore(u3_noun    a,
 }
 
 /* u3a_string(): `a` as an on-loom c-string.
+ @Refcount: retains
 */
 c3_c*
 u3a_string(u3_atom a)

pkg/noun/allocate.h

@@ -63,6 +63,8 @@
     */
 #     define u3a_crag_no  (u3a_page - u3a_min_log)
 
+#     define u3a_direct_max 0x7fffffff
+
     /* page table constants
     */
 #     define u3a_free_pg  (u3p(u3a_crag))0
@@ -237,6 +239,27 @@ STATIC_ASSERT( u3a_vits <= u3a_min_log,
 
   /**  Macros.  Should be better commented.
   **/
+#   ifdef U3_REFCOUNT_LINT
+    /* Lint-mode declarations: the refcount checker parses with
+    ** U3_REFCOUNT_LINT defined so that noun primitives appear as plain
+    ** function calls in the AST instead of macro expansions.  These
+    ** declarations are never compiled or linked; they must stay
+    ** semantically equivalent to the macros in the #else branch.
+    */
+      c3_o u3a_is_cat(u3_noun som);
+      c3_o u3a_is_dog(u3_noun som);
+      c3_o u3a_is_pug(u3_noun som);
+      c3_o u3a_is_pom(u3_noun som);
+      c3_o u3a_is_atom(u3_noun som);
+      c3_o u3a_is_cell(u3_noun som);
+#     define u3ud(som)  u3a_is_atom(som)
+#     define u3du(som)  u3a_is_cell(som)
+
+      u3_noun u3a_h(u3_noun som);  //  @Refcount: retains arguments
+      u3_noun u3a_t(u3_noun som);  //  @Refcount: retains arguments
+#     define u3h(som) u3a_h(som)
+#     define u3t(som) u3a_t(som)
+#   else
     /* u3a_is_cat(): yes if noun [som] is direct atom.
     */
 #     define u3a_is_cat(som)    (((som) >> 31) ? c3n : c3y)
@@ -279,6 +302,7 @@ STATIC_ASSERT( u3a_vits <= u3a_min_log,
            ? ( ((u3a_cell *)u3a_to_ptr(som))->tel )\
            : u3m_bail(c3__exit) )
 #     define u3t(som) u3a_t(som)
+#   endif
 
 #     define  u3to(type, x) ((type *)u3a_into(x))
 #     define  u3tn(type, x) (x) ? (type*)u3a_into(x) : (void*)NULL
@@ -646,10 +670,14 @@ u3a_post_info(u3_post);
         */
           u3_weak
           u3a_gain(u3_weak som);
+#         ifdef U3_REFCOUNT_LINT
+#           define u3k(som) u3a_gain(som)
+#         else
 #         define u3k(som) ({                                                    \
             u3_noun __som = som;                                                \
             ( c3y == u3a_is_cat(__som) ) ? __som : u3a_gain(__som);             \
           })
+#         endif
 
         /* u3a_take(): gain, copying juniors.
         */
@@ -665,12 +693,17 @@ u3a_post_info(u3_post);
         */
           void
           u3a_lose(u3_weak som);
+#         ifdef U3_REFCOUNT_LINT
+#           define u3z(som) u3a_lose(som)
+#         else
 #         define u3z(som) ({                                                    \
             u3_noun __som = som;                                                \
             ( c3y == u3a_is_cat(__som) ) ? (void)0 : u3a_lose(__som);           \
           })
+#         endif
 
         /* u3a_wash(): wash all lazy mugs in subtree.  RETAIN.
+        ** @Refcount: retains arguments
         */
           void
           u3a_wash(u3_noun som);
@@ -706,6 +739,7 @@ u3a_post_info(u3_post);
           u3a_mark_rptr(void* ptr_v);
 
         /* u3a_mark_noun(): mark a noun for gc.  Produce size.
+        ** @Refcount: retains arguments
         */
           c3_w
           u3a_mark_noun(u3_noun som);
@@ -825,6 +859,7 @@ u3a_dash(void);
           u3a_print_memory_str(c3_c* str_c, c3_c* cap_c, c3_w wor_w);
 
         /* u3a_prof(): mark/measure/print memory profile. RETAIN.
+        ** @Refcount: retains arguments
         */
           u3m_quac*
           u3a_prof(FILE* fil_u, u3_noun mas);
@@ -861,6 +896,7 @@ u3a_dash(void);
                         c3_o     (*cel_f)(u3_noun, void*));
 
         /* u3a_string(): `a` as an on-loom c-string.
+           @Refcount: retains
         */
           c3_c*
           u3a_string(u3_atom a);

pkg/noun/events.c

@@ -1,4 +1,6 @@
 //! @file events.c
+//! @Refcount: all functions are custom unless asserted otherwise
+//! -- loom snapshotting sits below the refcount machinery.
 //!
 //! incremental, orthogonal, paginated loom snapshots
 //!