carrick 0.3.53

package/sidecar/dist/src/capture/anchors.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Anchor resolution for the surface entry: guards for addressable anchors
+ * (symbol / handler_return) and the locator + node-builder path for
+ * anonymous inferred types. Produces the final alias line for each anchor,
+ * or a recorded demotion -- never a silently wrong line.
+ */
+import ts from 'typescript';
+import type { CaptureAnchorRequest, InferAnchorRequest } from './api.js';
+export interface ResolvedAnchor {
+    request: CaptureAnchorRequest;
+    /** RHS of `export type <alias> = ...;` in the surface entry. */
+    aliasText: string;
+    serialization: 'emitted' | 'node_builder' | 'structural_fallback';
+    /** Present exactly for demotions (the alias line is `unknown`). */
+    failureReason?: string;
+    /**
+     * Provenance for a non-demoting re-aim (#438/#439): recorded into the
+     * alias's `self_check_detail` when the alias self-checks clean, so a symbol
+     * anchor redirected from a value const to its `typeof` type sibling, or a
+     * builder-chain anchor moved off its config descriptor, stays traceable.
+     */
+    reaimNote?: string;
+    /**
+     * carrick#766: why an alias ABSTAINED — the surface line is `unknown`
+     * because nothing was resolvable, not because a step failed.
+     *
+     * Deliberately NOT `failureReason`. The scanner's literal backfill
+     * (`backfill_anchors`, engine/type_compat_v2.rs) keys on
+     * `capture_failure_reason` and re-anchors any alias carrying one off the v1
+     * bundle's text. For an alias whose v1 answer was itself blind that text is
+     * a bare element symbol, and re-anchoring it would publish a confident
+     * contract whose array-ness was guessed — the #349/#306 false mismatch. An
+     * abstain has nothing better to fall back to, so it must not look
+     * backfillable; the reason rides `self_check_detail` instead.
+     */
+    abstainReason?: string;
+}
+/** Repo-root-relative source file -> extensionless specifier from entryDir. */
+export declare function entryRelativeSpecifier(entryDir: string, repoRoot: string, sourceFile: string): string;
+/**
+ * Resolve one anchor against the analysis program. `placeholder` is the
+ * anchor's own placeholder alias declaration in the entry file -- the
+ * destination node the node builder anchors to (banked correction 1).
+ */
+export declare function resolveAnchor(program: ts.Program, request: CaptureAnchorRequest, args: {
+    repoRoot: string;
+    entryDir: string;
+    placeholder: ts.TypeAliasDeclaration | undefined;
+    /**
+     * symbol_name -> entry-relative specifier for every sibling `symbol`
+     * anchor. A literal anchor whose text is a bare identifier naming one of
+     * these resolves through that module instead of dangling in the entry.
+     */
+    siblingSymbolSpecs?: Map<string, string>;
+}): ResolvedAnchor;
+/**
+ * Locate the target node: tightest expression covering the byte span when
+ * given; else the expression matching expression_text on/after line_number;
+ * else the first expression starting on line_number.
+ */
+export declare function locateNode(sourceFile: ts.SourceFile, request: InferAnchorRequest): ts.Node | undefined;