Refactor (packages/codemode/src/tool-schema.ts:43): Function with high complexity (count = 18): hasUnresolvedRef

[vaishnavipalas]

P1B: Starter Task: Refactoring PR

1. Issue

Link to the associated GitHub issue: #68

Full path to the refactored file: packages/codemode/src/tool-schema.ts

What do you think this file does?
I think tool-schema.ts is supposed to convert JSON Schema (or Effect Schema) definitions into TypeScript-style type signatures. It could be so that you can show a model what shape to produce for a tool's input or output without handing it just the raw JSON schema.

What is the scope of your refactoring within that file?
I only touched the targeted function hasUnresolvedRef (flagged for high complexity) by splitting it into three separate functions. The first function I created was resolveRef, which handles matching and looking up a $ref and checking if it has already been seen. The second function was collectChildSchemas, which gathers all the child schemas from anyOf, oneOf, allOf, properties, items, and additionalProperties. Then, I refactored hasUnresolvedRef to use these functions.

Which Qlty‑reported issue did you address?
"Function with high complexity," count = 18, in hasUnresolvedRef (line 43).

2. Refactoring

How did the specific issue you chose impact the codebase’s maintainability?
The function hasUnresolvedRef contained a lot of logic, including ref-resolution logic, cycle detection, and child-schema traversal all into one function with many branch points. This made it hard to figure out which condition would have caused an "unresolved" verdict, to isolate it into pieces and unit-test, and risky to iterate on without breaking the logic.

What changes did you make to resolve the issue?
I split the function into three:

• resolveRef: handles $ref parsing, $defs lookup, and the cycle check
• collectChildSchemas: gathers the child schemas to recurse into
• hasUnresolvedRef: uses the two functions above, plus the existing visited-based identity guarding

The algorithm itself didn't change, the logic is just now cleanly distributed across more specific functions.

How do your changes improve maintainability? Did you consider alternatives?
Each function now has a low, independent complexity and can be read and tested on its own. By doing so, I was able to find a coverage gap in the ref-propagation path that the original function's tests didn't exercise. Another alternative could have been to do a more drastic restructuring, like a general-purpose schema-visitor. However, the approach I went with dealt with the smallest change while still preserving the existing algorithm.

3. Validation

How did you validate that the change is correct?
I added five test cases in targeting the specific branches of the original hasUnresolvedRef logic. I then ran bun test to confirm that every line inside these new functions was actually executed. I also ran bun lint to ensure that no new errors appeared.

Attach a screenshot of the test coverage showing the lines were executed by the tests.

Attach a screenshot showing the tests that cover the change passing during CI

Attach a screenshot of qlty smells --no-snippets <full/path/to/file.ts> showing fewer reported issues after the changes.

before: