import { type FlowStepParseResult } from 'pipework-flow-parser';
interface Position {
    readonly line: number;
    readonly column: number;
}
interface SourceLocation {
    readonly start: Position;
    readonly end: Position;
}
/** A structurally-typed ESTree node — enough to walk without a parser type dependency. */
export interface AstNode {
    readonly type: string;
    readonly range: readonly [number, number];
    readonly loc: SourceLocation;
    readonly [key: string]: unknown;
}
/**
 * How a `@flow_step`-annotated declaration is shaped.
 *
 * - `function` — a standalone function (declaration or a `const` bound to an
 *   arrow / function expression). The only legal shape.
 * - `method` — a class method, class field bound to a function, or object
 *   literal method. Banned: a method carries hidden `this` state, so the trace
 *   boundary is untrustworthy. See PLAN.tracing.md, Q3.
 * - `orphan` — the JSDoc block documents no declaration the analyzer can see.
 */
export type FlowStepShape = 'function' | 'method' | 'orphan';
export interface FlowStepSubject {
    readonly shape: FlowStepShape;
    /** Declared name, or `<anonymous>` / `<computed>` when none can be read. */
    readonly name: string;
    /** 1-based line of the declaration, or of the JSDoc block when orphaned. */
    readonly line: number;
    /** The declaration node, or `null` when orphaned. */
    readonly node: AstNode | null;
    /**
     * The documented function's executable body — what the cardinality analyzer
     * walks. `null` exactly when `node` is `null` (an orphan): every `function`
     * and `method` subject resolves to a function with a body.
     */
    readonly body: AstNode | null;
}
export interface FlowStepSite {
    /** Parsed content of the `@flow_step` JSDoc block — never `not-a-flow-step`. */
    readonly annotation: Exclude<FlowStepParseResult, {
        kind: 'not-a-flow-step';
    }>;
    /** The declaration the block documents, and how it is shaped. */
    readonly subject: FlowStepSubject;
    /** 1-based line where the `@flow_step` JSDoc block opens. */
    readonly commentLine: number;
}
/**
 * Parse `code` and return every `@flow_step` site it contains, in source order.
 *
 * Memoized by source text: the flow, cardinality, and coverage checks each scan
 * the same file, and the parse-and-walk produces a bit-identical result every
 * time — the cache collapses it to one parse per file. Issue #322.
 *
 * Throws if `code` is not parseable — callers scanning many files should catch
 * and skip, leaving syntax errors to the type checker.
 */
export declare function collectFlowStepSites(code: string): FlowStepSite[];
export declare function isNode(value: unknown): value is AstNode;
export {};
//# sourceMappingURL=flow-step-site.d.ts.map