chore: quality polishing

Author: gmelodie

.github/workflows/ci.yml

@@ -133,7 +133,11 @@ jobs:
         uses: actions/cache@v4
         with:
           path: tests/e2e/cpp/build/_deps
-          key: ${{ runner.os }}-cpp-e2e-deps-${{ hashFiles('tests/e2e/cpp/CMakeLists.txt') }}
+          # The FetchContent subbuild bakes the CMake generator (e.g. the MSVC
+          # "Visual Studio NN" version) into its CMakeCache.txt. Key on the
+          # runner image so a toolchain bump can't restore a generator-mismatched
+          # build dir — that aborts the configure. No restore-keys, for the same reason.
+          key: ${{ runner.os }}-${{ env.ImageOS }}-${{ env.ImageVersion }}-cpp-e2e-deps-${{ hashFiles('tests/e2e/cpp/CMakeLists.txt') }}
 
       - name: Run C++ e2e tests
         shell: bash

ffi/codegen/cddl.nim

@@ -92,7 +92,7 @@ proc emitObjectFields(t: FFITypeMeta): string =
 proc emitReqFields(p: FFIProcMeta): string =
   var fields: seq[tuple[name: string, typeName: string, isPtr: bool]] = @[]
   for ep in p.extraParams:
-    fields.add((name: ep.name, typeName: ep.typeName, isPtr: ep.ridesAsPtr()))
+    fields.add((name: ep.name, typeName: ep.typeName, isPtr: ep.wireIsPtr()))
   emitMap(fields)
 
 proc responseRule(p: FFIProcMeta): string =
@@ -106,7 +106,7 @@ proc responseRule(p: FFIProcMeta): string =
     # The dtor has no meaningful payload — handleRes sends a CBOR null sentinel.
     "nil"
   of FFIKind.FFI:
-    if p.returnRidesAsPtr():
+    if p.returnWireIsPtr():
       "uint"
     else:
       nimTypeToCddl(p.returnTypeName)

ffi/codegen/cpp.nim

@@ -299,7 +299,7 @@ proc generateCppHeader*(
     lines.add("struct $1 {" % [reqName])
     for ep in p.extraParams:
       let cppType =
-        if ep.ridesAsPtr():
+        if ep.wireIsPtr():
           CppPtrType
         else:
           nimTypeToCpp(ep.typeName)
@@ -308,7 +308,7 @@ proc generateCppHeader*(
     var fields: seq[(string, string)] = @[]
     for ep in p.extraParams:
       let cppType =
-        if ep.ridesAsPtr():
+        if ep.wireIsPtr():
           CppPtrType
         else:
           nimTypeToCpp(ep.typeName)
@@ -388,7 +388,7 @@ proc generateCppHeader*(
     var epNames: seq[string] = @[]
     for ep in ctor.extraParams:
       let cppType =
-        if ep.ridesAsPtr():
+        if ep.wireIsPtr():
           CppPtrType
         else:
           nimTypeToCpp(ep.typeName)
@@ -492,7 +492,7 @@ proc generateCppHeader*(
   for m in methods:
     let methodName = stripLibPrefixCpp(m.procName, libName)
     let retCppType =
-      if m.returnRidesAsPtr():
+      if m.returnWireIsPtr():
         CppPtrType
       else:
         nimTypeToCpp(m.returnTypeName)
@@ -502,7 +502,7 @@ proc generateCppHeader*(
     var methParamNames: seq[string] = @[]
     for ep in m.extraParams:
       let cppType =
-        if ep.ridesAsPtr():
+        if ep.wireIsPtr():
           CppPtrType
         else:
           nimTypeToCpp(ep.typeName)

ffi/codegen/meta.nim

@@ -5,8 +5,8 @@ type
   FFIParamMeta* = object
     name*: string # Nim param name, e.g. "req"
     typeName*: string # Nim type name, e.g. "EchoRequest"
-    isPtr*: bool # true if the type is `ptr T`
-    isHandle*: bool # true if the type is an {.ffiHandle.} type (wire form uint64)
+    isPtr*: bool
+    isHandle*: bool # wire form uint64
 
   FFIKind* {.pure.} = enum
     FFI
@@ -20,8 +20,8 @@ type
     libTypeName*: string # e.g. "Timer"
     extraParams*: seq[FFIParamMeta] # all params except the lib param
     returnTypeName*: string # e.g. "EchoResponse", "string", "pointer"
-    returnIsPtr*: bool # true if return type is ptr T
-    returnIsHandle*: bool # true if return type is an {.ffiHandle.} type
+    returnIsPtr*: bool
+    returnIsHandle*: bool
 
   FFIFieldMeta* = object
     name*: string # e.g. "delayMs"
@@ -57,12 +57,12 @@ var ffiHandleTypeNames* {.compileTime.}: seq[string]
 proc isFFIHandleTypeName*(name: string): bool {.compileTime.} =
   name in ffiHandleTypeNames
 
-proc ridesAsPtr*(ep: FFIParamMeta): bool =
+proc wireIsPtr*(ep: FFIParamMeta): bool =
   ## True if the param crosses the wire as an opaque uint64 — a raw `ptr` or an
   ## `{.ffiHandle.}` id. Both share the codegen pointer type.
   ep.isPtr or ep.isHandle
 
-proc returnRidesAsPtr*(p: FFIProcMeta): bool =
+proc returnWireIsPtr*(p: FFIProcMeta): bool =
   ## True if the return crosses the wire as an opaque uint64 (raw `ptr` or handle).
   p.returnIsPtr or p.returnIsHandle
 

ffi/codegen/rust.nim

@@ -256,7 +256,7 @@ proc generateTypesRs*(types: seq[FFITypeMeta], procs: seq[FFIProcMeta]): string
       for ep in p.extraParams:
         let snake = camelToSnakeCase(ep.name)
         let rustType =
-          if ep.ridesAsPtr():
+          if ep.wireIsPtr():
             RustPtrType
           else:
             nimTypeToRust(ep.typeName)
@@ -550,7 +550,7 @@ proc generateApiRs*(
     for ep in ctor.extraParams:
       let snake = camelToSnakeCase(ep.name)
       let rustType =
-        if ep.ridesAsPtr():
+        if ep.wireIsPtr():
           RustPtrType
         else:
           nimTypeToRust(ep.typeName)
@@ -711,7 +711,7 @@ proc generateApiRs*(
     for ep in m.extraParams:
       let snake = camelToSnakeCase(ep.name)
       let rustType =
-        if ep.ridesAsPtr():
+        if ep.wireIsPtr():
           RustPtrType
         else:
           nimTypeToRust(ep.typeName)
@@ -729,7 +729,7 @@ proc generateApiRs*(
       else:
         reqName & " {}"
 
-    let retTypeForApi = if m.returnRidesAsPtr(): RustPtrType else: retRustType
+    let retTypeForApi = if m.returnWireIsPtr(): RustPtrType else: retRustType
 
     # -- blocking method --
     lines.add(

ffi/internal/ffi_macro.nim

@@ -87,8 +87,8 @@ proc isHandleType(typ: NimNode): bool =
   typ.kind == nnkIdent and isFFIHandleTypeName($typ)
 
 proc storageType(typ: NimNode): NimNode =
-  ## In-Req-struct storage type. `cstring` rides as `string`; an {.ffiHandle.}
-  ## type rides as its `uint64` id; everything else as-is.
+  ## In-Req-struct storage type. `cstring` stores as `string`; an {.ffiHandle.}
+  ## type stores as its `uint64` id; everything else as-is.
   if typ.kind == nnkIdent and $typ == "cstring":
     return ident("string")
   if isHandleType(typ):
@@ -631,26 +631,27 @@ macro ffiRaw*(prc: untyped): untyped =
     echo stmts.repr
   return stmts
 
-macro ffiHandle*(prc: untyped): untyped =
+macro ffiHandle*(node: untyped): untyped =
   ## Marks a `ref object` as an opaque FFI handle. Its wire form is a `uint64`
   ## id; the live object stays in the per-ctx handle registry and never crosses.
   ##
   ##   type Kernel {.ffiHandle.} = ref object
   ##     ...
-  if prc.kind != nnkTypeDef:
+  if node.kind != nnkTypeDef:
     error("`.ffiHandle.` must be applied to a type definition")
 
-  var clean = prc.copyNimTree()
-  if clean[0].kind == nnkPragmaExpr:
-    clean[0] = clean[0][0]
+  # Strip the `{.ffiHandle.}` pragma off the type name before re-emitting.
+  let typeDef = node.copyNimTree()
+  if typeDef[0].kind == nnkPragmaExpr:
+    typeDef[0] = typeDef[0][0]
 
   let typeName =
-    if clean[0].kind == nnkPostfix:
-      clean[0][1]
+    if typeDef[0].kind == nnkPostfix:
+      typeDef[0][1]
     else:
-      clean[0]
+      typeDef[0]
 
-  let refTy = clean[2]
+  let refTy = typeDef[2]
   if refTy.kind != nnkRefTy or refTy[0].kind != nnkObjectTy:
     error("`.ffiHandle.` type " & $typeName & " must be a `ref object`")
   let objTy = refTy[0]
@@ -662,8 +663,8 @@ macro ffiHandle*(prc: untyped): untyped =
   ffiHandleTypeNames.add($typeName)
 
   when defined(ffiDumpMacros):
-    echo clean.repr
-  return clean
+    echo typeDef.repr
+  return typeDef
 
 macro ffi*(prc: untyped): untyped =
   ## Simplified FFI macro — applies to procs or types.
@@ -687,10 +688,11 @@ macro ffi*(prc: untyped): untyped =
   ##     return ok("done")
 
   if prc.kind == nnkTypeDef:
-    var cleanTypeDef = prc.copyNimTree()
-    if cleanTypeDef[0].kind == nnkPragmaExpr:
-      cleanTypeDef[0] = cleanTypeDef[0][0]
-    return registerFFITypeInfo(cleanTypeDef)
+    # Strip the `{.ffi.}` pragma off the type name before registering it.
+    let typeDef = prc.copyNimTree()
+    if typeDef[0].kind == nnkPragmaExpr:
+      typeDef[0] = typeDef[0][0]
+    return registerFFITypeInfo(typeDef)
 
   let procName = prc[0]
   let formalParams = prc[3]
@@ -735,7 +737,7 @@ macro ffi*(prc: untyped): untyped =
   let resultRetType = resultInner[1]
   rejectRawPtrType(resultRetType, "`.ffi.` proc " & $procName & " return type")
 
-  # A handle receiver rides the wire; a value-type lib receiver binds to ctx.myLib.
+  # A handle receiver crosses the wire; a value-type lib receiver binds to ctx.myLib.
   var extraParamNames: seq[string] = @[]
   var extraParamTypes: seq[NimNode] = @[]
   let wireStart = if firstIsHandle: 1 else: 2