import type { QueryContext } from './query-engine.js';
import type { MemoElement, MemoRelationship } from '../model/semantic.js';
/** What a query selects. Relationship rows carry `source.*` / `target.*` paths. */
export type QuerySelect = 'elements' | 'relationships';
/** One row of a result set — an element, or a relationship under `select: relationships`. */
export type QueryRow = MemoElement | MemoRelationship;
export interface MemoQuerySpec {
    /**
     * What the rows are. `elements` (the default) selects model elements and
     * `kind:` names element definitions; `relationships` selects links and
     * `kind:` names relationship types.
     */
    select?: QuerySelect;
    /** Element kind(s) — or relationship type(s) under `select: relationships` */
    kind?: string | string[];
    /** Filter expression: "field op value" (field, ==, !=, contains) */
    where?: string;
    /** Traverse relationships: "outgoing|incoming <relType>" */
    traverse?: string;
    /** Output display format */
    display?: 'table' | 'list' | 'matrix' | 'grouped' | 'count' | 'metric';
    /** Columns to include (for table/grouped) */
    columns?: string | string[];
    /** Sort field */
    sort?: string;
    /** Message when result is empty */
    empty?: string;
    /** Group by field (for grouped display) */
    group_by?: string;
    /** Max rows to show (default: unlimited) */
    limit?: number;
    /** For matrix: row kind and column kind */
    row_kind?: string;
    col_kind?: string;
    /** For metric: label + value field */
    label?: string;
    value?: string;
}
export declare function parseMemoQuery(blockContent: string): MemoQuerySpec | null;
/** A query directive that cannot be executed as written. */
export declare class MemoQueryError extends Error {
    readonly source?: string | undefined;
    constructor(message: string, source?: string | undefined);
}
/** True when this spec's rows are relationships rather than elements. */
export declare function selectsRelationships(spec: MemoQuerySpec): boolean;
/**
 * Fields a relationship row answers without consulting its attribute map.
 *
 * `source` and `target` are the endpoint *names*, which is what a table column
 * wants; `source.<field>` / `target.<field>` reach the endpoint element itself.
 */
export declare const RELATIONSHIP_FIELDS: Set<string>;
/** The `source` / `target` prefix of a dotted path, or undefined if it has none. */
export declare function endpointOf(field: string): 'source' | 'target' | undefined;
/** Comparison operators the filter engine can actually evaluate. */
export type WhereOperator = '==' | '!=' | 'contains';
export interface WhereClause {
    field: string;
    op: WhereOperator;
    value: string;
}
/**
 * Parse a `where:` expression, or return null if this engine cannot evaluate it.
 *
 * Only a single comparison is supported. Boolean composition, parenthesised
 * groups and `starts with` are all unsupported — callers must treat null as an
 * error, never as "no filter". A dotted endpoint path (`target.layer`) parses,
 * but means nothing to an element query; `validateQuerySpec` rejects it there.
 */
export declare function parseWhereClause(where: string): WhereClause | null;
/** The member name of an enum reference: `RequirementTypeKind::software` → `software`. */
export declare function unqualifyEnum(value: string): string;
/**
 * Validate a query spec against what the engine can execute.
 * Returns a list of human-readable problems; empty means executable.
 */
export declare function validateQuerySpec(spec: MemoQuerySpec): string[];
/** `kind:` as a list, whichever of the two spellings the block used. */
export declare function kindList(spec: MemoQuerySpec): string[];
/** Character ranges of the HTML comments in `content`. */
export declare function htmlCommentRanges(content: string): Array<[number, number]>;
export declare function isCommentedOut(ranges: Array<[number, number]>, offset: number): boolean;
/** Throw if the spec cannot be executed as written. */
export declare function assertExecutable(spec: MemoQuerySpec, source?: string): void;
export declare function executeQuery(spec: MemoQuerySpec, ctx: QueryContext, source?: string): QueryRow[];
export declare function renderQueryResult(spec: MemoQuerySpec, rows: QueryRow[], ctx: QueryContext): string;
export interface ProcessQueryOptions {
    /** Template id or path, used to make error messages locatable. */
    source?: string;
    /**
     * How to handle a block the engine cannot execute.
     * `throw` (default) fails the compile — correct for `memo dhf export`, where
     * a wrong table is worse than no document. `annotate` renders the error into
     * the output instead, for previews where partial output beats none.
     */
    onError?: 'throw' | 'annotate';
}
export declare function processMemoQueryBlocks(content: string, ctx: QueryContext, options?: ProcessQueryOptions): string;
//# sourceMappingURL=query-executor.d.ts.map