fix: address bugbot findings (round 4)

- Preserve top-level $ref in refsUsed when composition branch is taken,
  so computeDependencyDepths correctly tracks cross-operation schema
  sharing for oneOf/anyOf/allOf/discriminator schemas
- Return constraintClarity=1 when totalSchemaProperties is 0, matching
  errorClarity's "no data" pattern — avoids unfairly penalizing DELETE
  and binary-returning endpoints that have no schema properties

Made-with: Cursor

Author: adamaltman

packages/cli/src/commands/score/collect-metrics.ts

@@ -211,6 +211,10 @@ export function collectMetrics({
       if (allOfStats) result = addStats(result, allOfStats);
       if (polyStats) result = addStats(result, polyStats);
       if (discStats) result = addStats(result, discStats);
+
+      if (ref) {
+        result = { ...result, refsUsed: [ref, ...result.refsUsed] };
+      }
     } else {
       result = walkSchemaRaw(schemaNode, debug);
     }

packages/cli/src/commands/score/scoring.ts

@@ -31,8 +31,10 @@ export function computeOperationSubscores(
   const descTotal = 1 + metrics.parameterCount + metrics.totalSchemaProperties;
   const documentationQuality = descTotal > 0 ? clamp01(descCount / descTotal) : 1;
 
-  const propCount = metrics.totalSchemaProperties || 1;
-  const constraintClarity = clamp01(metrics.constraintCount / propCount);
+  const constraintClarity =
+    metrics.totalSchemaProperties > 0
+      ? clamp01(metrics.constraintCount / metrics.totalSchemaProperties)
+      : 1;
 
   const examplePoints =
     (metrics.requestExamplePresent ? 1 : 0) + (metrics.responseExamplePresent ? 1 : 0);

tests/e2e/score/score-json/snapshot.txt

@@ -5,7 +5,7 @@
     "parameterSimplicity": 0.8625,
     "schemaSimplicity": 0.796875,
     "documentationQuality": 0.9017857142857143,
-    "constraintClarity": 0.4375,
+    "constraintClarity": 0.5625,
     "exampleCoverage": 0.875,
     "errorClarity": 1,
     "dependencyClarity": 0.7291666666666669,
@@ -309,12 +309,12 @@
       }
     },
     "getTicketCode": {
-      "agentReadiness": 69,
+      "agentReadiness": 81,
       "subscores": {
         "parameterSimplicity": 0.9,
         "schemaSimplicity": 1,
         "documentationQuality": 1,
-        "constraintClarity": 0,
+        "constraintClarity": 1,
         "exampleCoverage": 0,
         "errorClarity": 1,
         "dependencyClarity": 1,
@@ -338,7 +338,7 @@
       "path": "/tickets/{ticketId}/qr",
       "method": "get",
       "operationId": "getTicketCode",
-      "agentReadinessScore": 69,
+      "agentReadinessScore": 81,
       "reasons": [
         "Missing response examples"
       ]

tests/e2e/score/score-stylish/snapshot.txt

@@ -8,7 +8,7 @@
   Parameter Simplicity     [█████████████████░░░] 86%
   Schema Simplicity        [████████████████░░░░] 80%
   Documentation Quality    [██████████████████░░] 90%
-  Constraint Clarity       [█████████░░░░░░░░░░░] 44%
+  Constraint Clarity       [███████████░░░░░░░░░] 56%
   Example Coverage         [██████████████████░░] 88%
   Error Clarity            [████████████████████] 100%
   Dependency Clarity       [███████████████░░░░░] 73%
@@ -30,7 +30,7 @@
   Top 1 Hotspot Operations
 
   GET /tickets/{ticketId}/qr (getTicketCode)
-    Agent Readiness: 69.0
+    Agent Readiness: 81.0
     - Missing response examples