refactor: align identifier naming with house style + re-enable the gate (#124)

Correct the readability-identifier-naming policy to match the documented house
style and re-enable the check as a WarningsAsErrors gate (it was "temporarily
disabled during rename migration"). The SDK already follows the policy closely;
this is a config alignment plus a small internal-only cleanup.

.clang-tidy amendments:
- LocalConstant/LocalVariable = lower_case: const/constexpr *locals* stay
  lower_case; the k-prefix Constant policy applies to file-scope/global
  constants only (without this, const locals falsely flag en masse).
- NamespaceIgnoredRegexp '^(PJ|Ui)$': the flat `PJ` namespace (house style) and
  uic-generated `Ui`.
- C-ABI / canonical-schema / STL exemptions (the plugin binary + wire contract):
    * Struct/Enum/EnumConstant/Function/GlobalConstant `PJ_`/`pj_` extern "C"
      C-ABI identifiers, plus the camelBack vtable member `fetchMessageData`.
    * PublicMember single-capital `D K R P` (ROS/OpenCV CameraInfo/DepthImage
      intrinsics -- a wire-format field contract).
    * Method has_value/value_or/error_or (std::expected drop-in interface) and
      load_config/save_config/ui_content/widget_data/trampoline_* (plugin-author
      and C-ABI-bridge methods every compiled plugin links by name).
    * TypeAlias `json` (nlohmann alias).
  Recasing any of these breaks wire compat, STL-shaped generic code, or the
  plugin ABI -- they are grandfathered (revisit the snake_case plugin virtuals
  in a future coordinated 1.0.0).
- StructIgnoredRegexp `overloaded` (std::visit idiom).
- ParameterIgnoredRegexp '.*_': a trailing underscore on a parameter is the
  idiomatic shadow-avoidance form (`PayloadView(Span bytes_) : bytes(bytes_)`);
  stripping it reintroduces a -Wshadow error, so trailing-underscore params are
  exempt.

Internal-only renames (no public API/ABI change -- local variables, file-local
helpers, test/example code):
  flatten_impl/count_leaf_fields_impl -> camelBack; test helpers (ColorEq,
  ColorNear, schema_release, array_release, stream_release, make_robot_pose)
  -> camelBack; local vars (requiredString/withPath/writeField/...) -> lower_case;
  named constants (ns_per_second, default_a_/default_b_) -> k-prefix.

Versioning: config + invisible internal renames only; no installed public API,
ABI struct, or wire-format change, and abi/baseline.abi is untouched -> no
version bump warranted.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: facontidavide

.clang-tidy

@@ -45,7 +45,7 @@ WarningsAsErrors: >
   modernize-use-nullptr,
   modernize-use-override,
   performance-move-const-arg,
-  # readability-identifier-naming,  # temporarily disabled during rename migration
+  readability-identifier-naming,
 
 HeaderFilterRegex: '.*'
 
@@ -98,6 +98,49 @@ CheckOptions:
     value: CamelCase
   - key: readability-identifier-naming.TemplateParameterCase
     value: CamelCase
+  # const/constexpr LOCALS follow lower_case (house style); the k-prefixed
+  # Constant policy above applies to file-scope/global constants only.
+  - key: readability-identifier-naming.LocalConstantCase
+    value: lower_case
+  - key: readability-identifier-naming.LocalConstantPrefix
+    value: ''
+  - key: readability-identifier-naming.LocalVariableCase
+    value: lower_case
+  # `PJ` is the documented flat project namespace; `Ui` is uic-generated.
+  - key: readability-identifier-naming.NamespaceIgnoredRegexp
+    value: '^(PJ|Ui)$'
+  # extern "C" C-ABI plugin contract: PJ_* structs/enums/enum-constants/entry
+  # points and pj_* exported globals are the plugin binary ABI — recasing them
+  # breaks every compiled plugin. Also exempt Google Benchmark BM_ functions and
+  # the std::visit `overloaded` idiom.
+  - key: readability-identifier-naming.FunctionIgnoredRegexp
+    value: '(BM_|PJ_|pj_).*'
+  - key: readability-identifier-naming.StructIgnoredRegexp
+    value: '(overloaded|PJ_.*)'
+  - key: readability-identifier-naming.EnumIgnoredRegexp
+    value: 'PJ_.*'
+  - key: readability-identifier-naming.EnumConstantIgnoredRegexp
+    value: 'PJ_.*'
+  - key: readability-identifier-naming.GlobalConstantIgnoredRegexp
+    value: 'pj_.*'
+  # Canonical schema and STL-/plugin-facing API are grandfathered: the ROS/OpenCV
+  # CameraInfo/DepthImage intrinsics (single-capital D/K/R/P) are a wire-format
+  # field contract; `has_value`/`value_or`/`error_or` are the std::expected drop-in
+  # interface; and `load_config`/`save_config`/`trampoline_*` are plugin-author or
+  # C-ABI-bridge methods that every compiled plugin links by name. Recasing any of
+  # these breaks wire compat, STL-shaped generic code, or the plugin ABI. (Revisit
+  # the snake_case plugin virtuals in a future coordinated 1.0.0.)
+  - key: readability-identifier-naming.PublicMemberIgnoredRegexp
+    value: '([A-Z]|fetchMessageData)'
+  - key: readability-identifier-naming.MethodIgnoredRegexp
+    value: '(has_value|value_or|error_or|load_config|save_config|ui_content|widget_data|trampoline_.*)'
+  - key: readability-identifier-naming.TypeAliasIgnoredRegexp
+    value: 'json'
+  # A trailing underscore on a *parameter* is the idiomatic shadow-avoidance form
+  # (e.g. `PayloadView(Span bytes_) : bytes(bytes_)` where `bytes` is a member);
+  # stripping it reintroduces a -Wshadow error. Exempt trailing-underscore params.
+  - key: readability-identifier-naming.ParameterIgnoredRegexp
+    value: '.*_'
 
   # --- Function size limits ---
   - key: readability-function-size.LineThreshold

pj_base/src/type_tree.cpp

@@ -11,20 +11,20 @@
 namespace PJ {
 namespace {
 
-void flatten_impl(const TypeTreeNode& node, std::string_view prefix, std::vector<std::string>& out) {
+void flattenImpl(const TypeTreeNode& node, std::string_view prefix, std::vector<std::string>& out) {
   std::string current_path = prefix.empty() ? node.name : std::string(prefix) + "." + node.name;
 
   switch (node.kind) {
     case TypeKind::kStruct:
       for (const auto& child : node.children) {
-        flatten_impl(*child, current_path, out);
+        flattenImpl(*child, current_path, out);
       }
       break;
     case TypeKind::kArray:
       if (node.element_type && node.fixed_array_size.has_value()) {
         for (uint32_t idx = 0; idx < *node.fixed_array_size; ++idx) {
           std::string indexed = current_path + "[" + std::to_string(idx) + "]";
-          flatten_impl(*node.element_type, indexed, out);
+          flattenImpl(*node.element_type, indexed, out);
         }
       }
       // Dynamic arrays (no fixed_array_size) produce 0 paths
@@ -36,18 +36,18 @@ void flatten_impl(const TypeTreeNode& node, std::string_view prefix, std::vector
   }
 }
 
-std::size_t count_leaf_fields_impl(const TypeTreeNode& node) {
+std::size_t countLeafFieldsImpl(const TypeTreeNode& node) {
   switch (node.kind) {
     case TypeKind::kStruct: {
       std::size_t count = 0;
       for (const auto& child : node.children) {
-        count += count_leaf_fields_impl(*child);
+        count += countLeafFieldsImpl(*child);
       }
       return count;
     }
     case TypeKind::kArray:
       if (node.element_type && node.fixed_array_size.has_value()) {
-        return *node.fixed_array_size * count_leaf_fields_impl(*node.element_type);
+        return *node.fixed_array_size * countLeafFieldsImpl(*node.element_type);
       }
       return 0;  // dynamic array: 0 columns until expanded
     default:
@@ -118,13 +118,13 @@ std::vector<std::string> flattenFieldPaths(const TypeTreeNode& root) {
   }
   // Skip root struct name -- children use empty prefix
   for (const auto& child : root.children) {
-    flatten_impl(*child, "", result);
+    flattenImpl(*child, "", result);
   }
   return result;
 }
 
 std::size_t countLeafFields(const TypeTreeNode& root) {
-  return count_leaf_fields_impl(root);
+  return countLeafFieldsImpl(root);
 }
 
 }  // namespace PJ

pj_base/tests/arrow_holders_test.cpp

@@ -37,36 +37,36 @@ int& streamReleaseCount() {
   return count;
 }
 
-void schema_release(::ArrowSchema* s) {
+void schemaRelease(::ArrowSchema* s) {
   ++schemaReleaseCount();
   std::memset(s, 0, sizeof(*s));  // spec: release sets fields to null/0
 }
 
-void array_release(::ArrowArray* a) {
+void arrayRelease(::ArrowArray* a) {
   ++arrayReleaseCount();
   std::memset(a, 0, sizeof(*a));
 }
 
-void stream_release(::ArrowArrayStream* s) {
+void streamRelease(::ArrowArrayStream* s) {
   ++streamReleaseCount();
   std::memset(s, 0, sizeof(*s));
 }
 
 ::ArrowSchema makeLiveSchema() {
   ::ArrowSchema s{};
-  s.release = schema_release;
+  s.release = schemaRelease;
   return s;
 }
 
 ::ArrowArray makeLiveArray() {
   ::ArrowArray a{};
-  a.release = array_release;
+  a.release = arrayRelease;
   return a;
 }
 
 ::ArrowArrayStream makeLiveStream() {
   ::ArrowArrayStream s{};
-  s.release = stream_release;
+  s.release = streamRelease;
   return s;
 }
 

pj_base/tests/image_annotations_codec_test.cpp

@@ -34,7 +34,7 @@ sdk::ImageAnnotations roundTrip(const sdk::ImageAnnotations& input) {
 
 // Compare two ColorRGBA values allowing 1-LSB drift on each channel from the
 // double-quantization round-trip (uint8 -> double in [0,1] -> uint8).
-::testing::AssertionResult ColorEq(const ColorRGBA& a, const ColorRGBA& b) {
+::testing::AssertionResult colorEq(const ColorRGBA& a, const ColorRGBA& b) {
   auto near = [](uint8_t x, uint8_t y) { return x > y ? (x - y) <= 1 : (y - x) <= 1; };
   if (near(a.r, b.r) && near(a.g, b.g) && near(a.b, b.b) && near(a.a, b.a)) {
     return ::testing::AssertionSuccess();
@@ -150,8 +150,8 @@ TEST(ImageAnnotationCodecTest, RoundTrip_LineLoopFourPoints) {
   ASSERT_EQ(out.points.size(), 1u);
   EXPECT_EQ(out.points[0].topology, AnnotationTopology::kLineLoop);
   EXPECT_EQ(out.points[0].points, in.points[0].points);
-  EXPECT_TRUE(ColorEq(in.points[0].color, out.points[0].color));
-  EXPECT_TRUE(ColorEq(in.points[0].fill_color, out.points[0].fill_color));
+  EXPECT_TRUE(colorEq(in.points[0].color, out.points[0].color));
+  EXPECT_TRUE(colorEq(in.points[0].fill_color, out.points[0].fill_color));
   EXPECT_DOUBLE_EQ(out.points[0].thickness, 2.5);
 }
 
@@ -190,8 +190,8 @@ TEST(ImageAnnotationCodecTest, RoundTrip_CirclePreservesDiameterRadiusInverse) {
   EXPECT_DOUBLE_EQ(out.circles[0].center.y, 60.0);
   EXPECT_DOUBLE_EQ(out.circles[0].radius, 10.0);
   EXPECT_DOUBLE_EQ(out.circles[0].thickness, 1.5);
-  EXPECT_TRUE(ColorEq(in.circles[0].color, out.circles[0].color));
-  EXPECT_TRUE(ColorEq(in.circles[0].fill_color, out.circles[0].fill_color));
+  EXPECT_TRUE(colorEq(in.circles[0].color, out.circles[0].color));
+  EXPECT_TRUE(colorEq(in.circles[0].fill_color, out.circles[0].fill_color));
 }
 
 TEST(ImageAnnotationCodecTest, RoundTrip_TextUtf8) {
@@ -209,7 +209,7 @@ TEST(ImageAnnotationCodecTest, RoundTrip_TextUtf8) {
   EXPECT_DOUBLE_EQ(out.texts[0].position.x, 320.5);
   EXPECT_DOUBLE_EQ(out.texts[0].position.y, 240.25);
   EXPECT_DOUBLE_EQ(out.texts[0].font_size, 14.0);
-  EXPECT_TRUE(ColorEq(in.texts[0].color, out.texts[0].color));
+  EXPECT_TRUE(colorEq(in.texts[0].color, out.texts[0].color));
 }
 
 TEST(ImageAnnotationCodecTest, RoundTrip_FullImageAnnotationAllThreeKinds) {
@@ -291,9 +291,9 @@ TEST(ImageAnnotationCodecTest, RoundTrip_PerVertexColors) {
   auto out = roundTrip(in);
   ASSERT_EQ(out.points.size(), 1u);
   ASSERT_EQ(out.points[0].colors.size(), 3u);
-  EXPECT_TRUE(ColorEq(in.points[0].colors[0], out.points[0].colors[0]));
-  EXPECT_TRUE(ColorEq(in.points[0].colors[1], out.points[0].colors[1]));
-  EXPECT_TRUE(ColorEq(in.points[0].colors[2], out.points[0].colors[2]));
+  EXPECT_TRUE(colorEq(in.points[0].colors[0], out.points[0].colors[0]));
+  EXPECT_TRUE(colorEq(in.points[0].colors[1], out.points[0].colors[1]));
+  EXPECT_TRUE(colorEq(in.points[0].colors[2], out.points[0].colors[2]));
 }
 
 }  // namespace

pj_base/tests/protobuf_wire_test_helpers.hpp

@@ -73,12 +73,12 @@ inline void appendBytes(std::vector<uint8_t>& out, const uint8_t* data, size_t s
 // each builds the inner message body (sans length prefix) for the proto type.
 
 inline std::vector<uint8_t> encodeTimestamp(Timestamp timestamp_ns) {
-  constexpr int64_t ns_per_second = 1'000'000'000LL;
-  int64_t seconds = timestamp_ns / ns_per_second;
-  int32_t nanos = static_cast<int32_t>(timestamp_ns % ns_per_second);
+  constexpr int64_t kNsPerSecond = 1'000'000'000LL;
+  int64_t seconds = timestamp_ns / kNsPerSecond;
+  int32_t nanos = static_cast<int32_t>(timestamp_ns % kNsPerSecond);
   if (nanos < 0) {
     --seconds;
-    nanos += static_cast<int32_t>(ns_per_second);
+    nanos += static_cast<int32_t>(kNsPerSecond);
   }
   std::vector<uint8_t> body;
   appendTag(body, 1, 0);

pj_base/tests/scene_entities_codec_test.cpp

@@ -35,7 +35,7 @@ namespace pb = ::PJ::test_pb;
 
 // Compare two ColorRGBA values allowing 1-LSB drift on each channel from the
 // uint8 -> double in [0,1] -> uint8 round-trip in the codec.
-::testing::AssertionResult ColorNear(const ColorRGBA& a, const ColorRGBA& b) {
+::testing::AssertionResult colorNear(const ColorRGBA& a, const ColorRGBA& b) {
   auto near = [](uint8_t x, uint8_t y) { return x > y ? (x - y) <= 1 : (y - x) <= 1; };
   if (near(a.r, b.r) && near(a.g, b.g) && near(a.b, b.b) && near(a.a, b.a)) {
     return ::testing::AssertionSuccess();
@@ -161,7 +161,7 @@ TEST(SceneEntitiesCodecTest, RoundTripOneEntityWithEachPrimitive) {
   ASSERT_EQ(dst.axes.size(), 1u);
 
   EXPECT_EQ(dst.arrows.front().pose, src.arrows.front().pose);
-  EXPECT_TRUE(ColorNear(src.arrows.front().color, dst.arrows.front().color));
+  EXPECT_TRUE(colorNear(src.arrows.front().color, dst.arrows.front().color));
   EXPECT_EQ(dst.cubes.front().size, src.cubes.front().size);
   EXPECT_DOUBLE_EQ(dst.cylinders.front().top_scale, src.cylinders.front().top_scale);
   EXPECT_EQ(dst.lines.front().type, src.lines.front().type);
@@ -196,7 +196,7 @@ TEST(SceneEntitiesCodecTest, RoundTripLineWithPerVertexColorsAndIndices) {
   EXPECT_EQ(dst_line.type, LineType::kLineList);
   EXPECT_EQ(dst_line.indices, std::vector<uint32_t>({0, 1, 2, 3}));
   ASSERT_EQ(dst_line.colors.size(), 4u);
-  EXPECT_TRUE(ColorNear(ColorRGBA{0, 255, 0, 255}, dst_line.colors[1]));
+  EXPECT_TRUE(colorNear(ColorRGBA{0, 255, 0, 255}, dst_line.colors[1]));
 }
 
 TEST(SceneEntitiesCodecTest, RoundTripModelPrimitive) {
@@ -228,7 +228,7 @@ TEST(SceneEntitiesCodecTest, RoundTripModelPrimitive) {
   const auto& dst = out->entities.front().models.front();
   EXPECT_EQ(dst.pose, src.pose);
   EXPECT_EQ(dst.scale, src.scale);
-  EXPECT_TRUE(ColorNear(src.color, dst.color));
+  EXPECT_TRUE(colorNear(src.color, dst.color));
   EXPECT_TRUE(dst.override_color);
   EXPECT_EQ(dst.url, src.url);
   EXPECT_EQ(dst.media_type, src.media_type);

pj_base/tests/type_tree_test.cpp

@@ -19,7 +19,7 @@ namespace {
 //   position: struct {x: float32, y: float32, z: float32}
 //   rotation: struct {w: float32, x: float32, y: float32, z: float32}
 //             semantic_tags = {"quaternion"}
-std::shared_ptr<TypeTreeNode> make_robot_pose() {
+std::shared_ptr<TypeTreeNode> makeRobotPose() {
   auto position = makeStruct(
       "position", {
                       makePrimitive("x", PrimitiveType::kFloat32),
@@ -51,7 +51,7 @@ std::shared_ptr<TypeTreeNode> make_robot_pose() {
 // ---------- Test 1: flatten_field_paths on robot_pose ----------
 
 TEST(TypeTreeTest, FlattenFieldPathsRobotPose) {
-  auto pose = make_robot_pose();
+  auto pose = makeRobotPose();
   auto paths = flattenFieldPaths(*pose);
 
   const std::vector<std::string> expected = {
@@ -67,7 +67,7 @@ TEST(TypeTreeTest, FlattenFieldPathsRobotPose) {
 // ---------- Test 2: count_leaf_fields on robot_pose ----------
 
 TEST(TypeTreeTest, CountLeafFieldsRobotPose) {
-  auto pose = make_robot_pose();
+  auto pose = makeRobotPose();
   EXPECT_EQ(countLeafFields(*pose), 8u);
 }
 
@@ -110,7 +110,7 @@ TEST(TypeTreeTest, MakeEnumSetsKind) {
 // ---------- Test 4: semantic tags are preserved ----------
 
 TEST(TypeTreeTest, SemanticTagsPreserved) {
-  auto pose = make_robot_pose();
+  auto pose = makeRobotPose();
   // rotation is the third child (index 2)
   ASSERT_GE(pose->children.size(), 3u);
   const auto& rotation = pose->children[2];

pj_plugins/dialog_protocol/include/pj_plugins/sdk/dialog_plugin_base.hpp

@@ -85,16 +85,16 @@ class DialogPluginBase {
       return;
     }
     out_error->code = code;
-    auto writeField = [](char* dest, std::size_t dest_size, std::string_view src) {
+    auto write_field = [](char* dest, std::size_t dest_size, std::string_view src) {
       if (dest == nullptr || dest_size == 0) {
         return;
       }
       std::size_t n = src.size() < dest_size - 1 ? src.size() : dest_size - 1;
       std::memcpy(dest, src.data(), n);
       dest[n] = '\0';
     };
-    writeField(out_error->domain, sizeof(out_error->domain), domain);
-    writeField(out_error->message, sizeof(out_error->message), message);
+    write_field(out_error->domain, sizeof(out_error->domain), domain);
+    write_field(out_error->message, sizeof(out_error->message), message);
     // Clear the v3.1 growth-path slots so a reused error struct does not
     // carry a stale pointer from a previous call. Matches sdk::fillError.
     out_error->extended = nullptr;