review-code

review-code — Inspecto Code Quality Review

You are performing a deep code quality review of a file or package in the inspecto monorepo. Your goal is to give the developer honest, specific, actionable feedback — not a rubber-stamp.

Project Architecture (reference model)

The intended dependency direction is strictly one-way:

@inspecto-dev/types          ← leaf, no internal deps
        ↓
@inspecto-dev/unplugin       ← build-time only, Node.js
        ↓
@inspecto-dev/core           ← browser runtime + server utils
        ↓
@inspecto-dev/react          ← thin React wrapper (peer: react)
@inspecto-dev/vue            ← thin Vue wrapper (peer: vue)
        ↓
@inspecto-dev/ide                    ← IDE extension (VS Code, Cursor, Trae) (CommonJS, Node.js)

Key architectural invariants to enforce:

• core must never import from react, vue, or ide
• types must never import from any other internal package
• react and vue are thin wrappers — no inspector logic, just prop-passing
• Web Component UI lives entirely in core/src/client/ — zero framework dependency
• Transform layer uses MagicString (not @babel/generator) for source maps
• Server uses portfinder + launch-ide (not custom child_process port scanning)
• Attributes injected only when NODE_ENV !== 'production'

Review Dimensions

For the given file or package, evaluate each dimension thoroughly:

1. Architecture & Module Boundaries

• Does the file import from packages it shouldn't depend on?
• Is the file in the right package given its responsibility?
• Does it introduce coupling between layers that should be independent?
• Are side effects (server startup, DOM mutation, customElements.define) isolated correctly?

2. Implementation Quality

• Are edge cases handled? (file not found, parse errors, empty input, Windows paths)
• Are error paths explicit with structured error codes (not raw throw new Error('string'))?
• No hardcoded magic values — ports, timeouts, attribute names should be constants/config
• Is async/await used correctly? No floating Promises, no unhandled rejections
• Are cleanup paths present? (event listeners removed, servers stopped, DOM elements removed)