tasks

Implement Forma reference resolve operation

Add the shared read-only operation that resolves editor link targets through canonical Forma path, schema, fragment, and ambiguity semantics.

Implement Forma Reference Resolve Operation

Goal

Expose canonical target resolution for editor integrations without moving reference semantics into the extension.

Sources

In Scope

  • Define a typed read-only reference.resolve request and result in Forma Core and RPC.
  • Accept workspace-relative source path, raw target, intent, and optional fragment information.
  • Resolve ordinary Markdown paths, wikilink-style paths, heading fragments, embeds, and schema-informed entry references through the existing index and path model.
  • Return canonical target path, target title or kind when available, fragment location, ambiguity candidates, and diagnostics.
  • Preserve case-sensitive and workspace-safe behavior; do not silently normalize ambiguous targets.
  • Add a structured CLI command suitable for short-lived editor invocation.
  • Add matching TypeScript result types to packages/shared.
  • Document the operation in the canonical operation API spec.

Out Of Scope

  • Editing or rewriting references.
  • Full-document unsaved-buffer analysis.
  • Backlink panels or search.
  • Editor-specific ranges and UI.

Acceptance Criteria

  • Core tests cover resolved, unresolved, ambiguous, fragment, embed, semantic-field, case, and path-escape cases.
  • RPC and CLI tests prove stable JSON shapes and error boundaries.
  • Shared TypeScript types match serialized Rust results.
  • Public results expose only workspace-relative paths.
  • Existing check, inspect, file-reference, and WebApp behavior does not regress.