feat(preflight): report each problem as data, with a stable code

[kkdev92]

Summary

Preflight throws before VS Code is touched and reports every problem it found. Until now it reported them as sentences only, so a test asserting "this plan has a captive dependency" matched prose, and a script reading the error had nothing to branch on.

PreflightError.problems now carries each finding as data:

try {
  defineExtension({ name: 'Sample', modules });
} catch (error) {
  if (error instanceof PreflightError) {
    for (const problem of error.problems) {
      // { code: 'SERVICE_CAPTIVE_DEPENDENCY', subject: 'projects.repository',
      //   moduleId: 'projects', path: ['projects.repository', 'core.clock'], message: '…' }
    }
  }
}

What was being lost

The information existed and was dropped at the throw. The service-graph validator reports a code, the token it is about and the dependency path it walked; runtime preflight reports a code and the module. Both were reduced to message on the way out. compileApplication's own checks — duplicate ids, a handler conflict, a hosted service with no lifecycle, syncable on a workspace-scoped key — were built as sentences from the start.

Each check now produces a PreflightProblem with a stable code. The graph validator's codes join the same vocabulary (SERVICE_DUPLICATE, SERVICE_MISSING_DEPENDENCY, SERVICE_CIRCULAR_DEPENDENCY, SERVICE_CAPTIVE_DEPENDENCY) so a reader of problems sees one. The full list is on compileApplication's documentation; the runtime codes are on RuntimeIssue.

Compatibility

Additive. issues remains the list of messages in the same order, and the error's own message is the same text as before, so nothing changes for anyone reading the console or matching on message.

PreflightError is now exported from the root. It is the error consumers already receive; exporting it means instanceof instead of comparing error.name.

Two JSDoc examples that showed the old constructor were updated with it.

Verification

npm run quality (1043 tests) and npm run verify:package pass. New assertions pin the code, subject and module of every finding kind, the dependency path on a graph problem, the runtime code surviving activation failure, and issues equalling problems reduced to messages.

A published extension built on this package was run against this build with its own sources untouched: type-check, lint and 271 tests pass.

🤖 Generated with Claude Code