@lynxflow/seo-engine 2.8.0 → 3.2.0

package/dist/semantic/sql-ast.d.ts

@@ -0,0 +1,155 @@
+export type SqlAstMeta = {
+    span?: {
+        start: number;
+        end: number;
+    };
+    dialect?: string;
+};
+export type SqlAstNode = SelectStmt | ColumnRef | LiteralExpr | BinaryExpr | UnaryExpr | RawSql | FunctionCall | CastExpr | CaseExpr | SubqueryExpr | CteStmt | OrderByItem | JoinClause | GroupByItem | WindowSpec | ParamRef | StarExpr | InExpr | BetweenExpr | ExistsExpr;
+export type SelectStmt = {
+    kind: "select";
+    columns: SqlAstNode[];
+    from?: SqlAstNode;
+    /** Predicats WHERE sous forme de liste (joins par `AND`). */
+    where?: SqlAstNode[];
+    groupBy?: SqlAstNode[];
+    having?: SqlAstNode;
+    orderBy?: SqlAstNode[];
+    limit?: number;
+    offset?: number;
+    distinct?: boolean;
+    ctes?: SqlAstNode[];
+    joins?: SqlAstNode[];
+    meta?: SqlAstMeta;
+};
+export type ColumnRef = {
+    kind: "column";
+    name: string;
+    alias?: string;
+    table?: string;
+    /** Expression sous-jacente (pour un SELECT `expr AS alias`). */
+    expr?: SqlAstNode;
+    meta?: SqlAstMeta;
+};
+export type LiteralExpr = {
+    kind: "literal";
+    value: unknown;
+    meta?: SqlAstMeta;
+};
+export type BinaryExpr = {
+    kind: "binary";
+    op: string;
+    left: SqlAstNode;
+    right: SqlAstNode;
+    meta?: SqlAstMeta;
+};
+export type UnaryExpr = {
+    kind: "unary";
+    op: string;
+    expr: SqlAstNode;
+    meta?: SqlAstMeta;
+};
+/**
+ * Un fragment de SQL non analyse (template `baseSql`, vue, expression complexe).
+ *
+ * L'AST ne peut pas parser une chaine SQL arbitraire : un `baseSql` contient
+ * des sous-requetes, des fonctions fenêtrées, des CTE, etc. Le noeud `raw`
+ * preserve le texte tel quel — c'est le même role que le `raw` de HoneySQL :
+* il marque ce qui echappe a l'AST, sans le faire silencieusement.
+ */
+export type RawSql = {
+    kind: "raw";
+    sql: string;
+    params?: unknown[];
+    meta?: SqlAstMeta;
+};
+export type FunctionCall = {
+    kind: "fn";
+    name: string;
+    args: SqlAstNode[];
+    meta?: SqlAstMeta;
+};
+export type CastExpr = {
+    kind: "cast";
+    expr: SqlAstNode;
+    type: string;
+    meta?: SqlAstMeta;
+};
+export type CaseExpr = {
+    kind: "case";
+    whens: {
+        when: SqlAstNode;
+        then: SqlAstNode;
+    }[];
+    else?: SqlAstNode;
+    meta?: SqlAstMeta;
+};
+export type SubqueryExpr = {
+    kind: "subquery";
+    query: SqlAstNode;
+    alias?: string;
+    meta?: SqlAstMeta;
+};
+export type CteStmt = {
+    kind: "cte";
+    name: string;
+    query: SqlAstNode;
+    columns?: string[];
+    meta?: SqlAstMeta;
+};
+export type OrderByItem = {
+    kind: "orderBy";
+    expr: SqlAstNode;
+    dir?: "asc" | "desc";
+    meta?: SqlAstMeta;
+};
+export type JoinClause = {
+    kind: "join";
+    table: SqlAstNode;
+    on?: SqlAstNode;
+    type?: "inner" | "left" | "right" | "full" | "cross";
+    meta?: SqlAstMeta;
+};
+export type GroupByItem = {
+    kind: "groupBy";
+    expr: SqlAstNode;
+    meta?: SqlAstMeta;
+};
+export type WindowSpec = {
+    kind: "window";
+    name?: string;
+    partitionBy?: SqlAstNode[];
+    orderBy?: SqlAstNode[];
+    frame?: string;
+    meta?: SqlAstMeta;
+};
+export type ParamRef = {
+    kind: "param";
+    index: number;
+    type?: string;
+    value?: unknown;
+    meta?: SqlAstMeta;
+};
+export type StarExpr = {
+    kind: "star";
+    table?: string;
+    meta?: SqlAstMeta;
+};
+export type InExpr = {
+    kind: "in";
+    expr: SqlAstNode;
+    values: SqlAstNode[];
+    meta?: SqlAstMeta;
+};
+export type BetweenExpr = {
+    kind: "between";
+    expr: SqlAstNode;
+    low: SqlAstNode;
+    high: SqlAstNode;
+    meta?: SqlAstMeta;
+};
+export type ExistsExpr = {
+    kind: "exists";
+    subquery: SqlAstNode;
+    meta?: SqlAstMeta;
+};

package/dist/semantic/sql-formatter.d.ts

@@ -0,0 +1,12 @@
+import type { SqlAstNode } from "./sql-ast";
+import type { SqlDialect } from "./dialects";
+import { dialectRegistry } from "./dialects/registry";
+type FormatOptions = {
+    strictFeatureChecks?: boolean;
+};
+export declare function formatAst(ast: SqlAstNode, dialect: SqlDialect, options?: FormatOptions): {
+    sql: string;
+    params: unknown[];
+};
+export { dialectRegistry };
+export declare function formatSqlStatement(sql: string): string;

package/dist/semantic/sql-guard.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Garde-fou SQL en lecture seule.
+ *
+ * Implementation canonique, partagee par le moteur (validation d'un `baseSql`
+ * ecrit par l'utilisateur) et par l'app (surface SQL de Pulse). Une seule
+ * implementation : deux regles de garde divergentes seraient une faille.
+ */
+export declare const FORBIDDEN_KEYWORDS: readonly ["insert", "update", "delete", "drop", "truncate", "alter", "create", "replace", "merge", "grant", "revoke", "exec", "execute", "call", "pragma", "attach", "detach", "vacuum", "reindex", "optimize", "system", "rename", "kill"];
+export declare function isReadOnlySelect(query: string): boolean;
+/**
+ * Force un plafond de lignes : ajoute `LIMIT maxRows` quand la requete n'en a
+ * pas, abaisse un `LIMIT` deja present quand il depasse le plafond (protection
+ * contre les lectures OOM sur des tables d'evenements).
+ */
+export declare function enforceLimit(query: string, maxRows?: number): string;
+/**
+ * Verifie qu'un `baseSql` de modele semantique est en lecture seule.
+ *
+ * Le `baseSql` est ecrit par l'utilisateur (ou par un agent) puis injecte tel
+ * quel dans le `FROM` de la requete compilee. Sans ce controle, un `baseSql`
+ * malveillant transformerait une lecture en ecriture — et l'Agent API, qui
+ * accepte un modele depuis l'exterieur, en ferait un canal d'ecriture
+ * deguise.
+ *
+ * Le message d'erreur est explicite : l'appelant doit pouvoir corriger
+ * son modele sans deviner la cause.
+ */
+export declare function assertReadOnlyBaseSql(baseSql: string): void;

package/dist/semantic/sql-lex.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Lexical helpers shared by the read-only SQL guard and the HogQL rewrites.
+ *
+ * The protected mask marks every character that belongs to a string literal,
+ * quoted identifier or comment. Callers can therefore skip those regions
+ * without re-implementing dialect quoting rules in each module.
+ */
+export interface SqlMaskOptions {
+    /**
+     * Treat `$tag$...$tag$` as a string literal. Disabled by default because
+     * ClickHouse/SQLite identifiers may contain `$`; treating an identifier as
+     * an unterminated string would hide executable SQL from the guard.
+     */
+    dollarQuoted?: boolean;
+    /**
+     * Mask `"..."` / `` `...` `` identifiers. Enabled by default for rewriting
+     * and keyword scans. Security scans that look for functions/namespaces pass
+     * `false`: a quoted `"url"(...)` or `"system"."tables"` is still executable.
+     */
+    protectQuotedIdentifiers?: boolean;
+}
+/** Returns the index just after the closing quote (or the input length). */
+export declare function scanQuotedLiteral(sql: string, start: number, quote: string): number;
+/**
+ * Returns the index just after the closing dollar-quote delimiter, or `-1`
+ * when the token at `start` is not a dollar-quoted string.
+ */
+export declare function scanDollarQuotedLiteral(sql: string, start: number): number;
+export declare function buildSqlProtectedMask(sql: string, options?: SqlMaskOptions): Uint8Array;
+/** Blanks protected regions while preserving offsets and line breaks. */
+export declare function maskSqlProtectedRegions(sql: string, options?: SqlMaskOptions): string;

package/dist/semantic/sql-snippets.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Reusable SQL Snippets and Template Variables
+ * Clean-room implementation for expanding reusable SQL fragments and dynamic parameters.
+ * Supports Hex-style interactive parameters: {{param:name=defaultValue|type=number|min=1|max=100|label=Min}}
+ */
+export interface SqlSnippet {
+    id: string;
+    name: string;
+    description: string;
+    sqlContent: string;
+    category?: "filter" | "metric" | "table";
+}
+export interface InteractiveSqlParameter {
+    name: string;
+    label: string;
+    type: "number" | "text" | "select" | "date";
+    defaultValue: string | number;
+    currentValue?: string | number;
+    options?: string[];
+    min?: number;
+    max?: number;
+    step?: number;
+}
+export declare const DEFAULT_SQL_SNIPPETS: SqlSnippet[];
+export interface ExpandSqlResult {
+    expandedSql: string;
+    snippetsReplaced: string[];
+    variablesReplaced: string[];
+    parametersReplaced: string[];
+    unresolvedSnippets: string[];
+}
+/**
+ * Extracts interactive parameters defined like `{{param:name=value|type=number|...}}` or `{{param:name}}`
+ */
+export declare function extractSqlParameters(sql: string): InteractiveSqlParameter[];
+/**
+ * Expands `{{snippet: name}}`, `{{param: name...}}`, and `{{variable}}` inside a SQL query.
+ */
+export declare function expandSqlSnippets(sql: string, snippets?: SqlSnippet[], variables?: Record<string, string | number>, paramValues?: Record<string, string | number>): ExpandSqlResult;

package/dist/semantic/streaming.d.ts

@@ -0,0 +1,54 @@
+import type { CompiledColumn } from "./types";
+/**
+ * Pagination reelle d'une requete semantique.
+ *
+ * Le compilateur produit une requete bornee (`LIMIT`/`OFFSET`) ; ce module
+ * enchaine ces pages sans jamais materialiser l'integralite du resultat. Il
+ * sert aussi bien a un export volumineux (consommateur qui accepte de
+ * collecter) qu'a un flux incremental (client qui traite page par page).
+ */
+/** Une page de resultat : ses colonnes et ses lignes. */
+export interface QueryPage {
+    columns: CompiledColumn[];
+    rows: Record<string, unknown>[];
+}
+/**
+ * Charge une page. `limit` est le nombre maximal de lignes attendues, `offset`
+ * le decalage cumule. Le `signal` permet d'abandonner un fetch en cours.
+ */
+export type QueryPageFetcher = (limit: number, offset: number, signal?: AbortSignal) => Promise<QueryPage>;
+export interface StreamQueryPagesOptions {
+    /** Taille de page demandee au fetcher (defaut : {@link DEFAULT_PAGE_SIZE}). */
+    pageSize?: number;
+    /** Nombre maximal de lignes a emettre, toutes pages confondues. */
+    maxRows?: number;
+    /** Annulation propagee au fetcher et verifiee entre les pages. */
+    signal?: AbortSignal;
+}
+export interface CollectedQueryPages {
+    columns: CompiledColumn[];
+    rows: Record<string, unknown>[];
+    /** Nombre de pages effectivement lues. */
+    pageCount: number;
+}
+export declare const DEFAULT_PAGE_SIZE = 1000;
+/**
+ * Itère une requete par pages jusqu'a epuisement.
+ *
+ * - Chaque page est demandee avec la taille restante (`pageSize`, reduite a
+ *   `maxRows - deja emis` quand un plafond est fixe).
+ * - Une page plus courte que la taille demandee signale la fin du resultat.
+ * - `maxRows` tronque la derniere page ; le fetcher n'est jamais appele avec un
+ *   offset superieur a `maxRows`.
+ * - Seule la page courante est retenue en memoire.
+ */
+export declare function streamQueryPages(fetchPage: QueryPageFetcher, options?: StreamQueryPagesOptions): AsyncGenerator<QueryPage & {
+    pageIndex: number;
+}>;
+/**
+ * Collecte bornee, pour les consommateurs qui ne savent pas streamer.
+ *
+ * Delegue entierement a {@link streamQueryPages} : la borne `maxRows` reste le
+ * garde-fou unique, et le comportement de pagination est identique.
+ */
+export declare function collectQueryPages(fetchPage: QueryPageFetcher, options?: StreamQueryPagesOptions): Promise<CollectedQueryPages>;

package/dist/semantic/timezone.d.ts

@@ -0,0 +1,24 @@
+import type { MetricExpr } from "./expr";
+export declare function assertIanaTimezone(timezone: string): string;
+/**
+ * Injecte un fuseau dans toutes les troncatures et differences de dates
+ * d'une expression. Un fuseau deja present dans l'AST est conserve : la
+ * declaration la plus proche de l'appel l'emporte.
+ */
+export declare function withTimezone(expr: MetricExpr, timezone: string): MetricExpr;
+export interface ZonedParts {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+}
+/**
+ * Décompose un instant dans le fuseau demande, en heure murale locale.
+ *
+ * `Intl.DateTimeFormat` est la seule source de fuseaux IANA disponible sans
+ * dependance : Node, Cloudflare Workers et les navigateurs embarquent la
+ * meme base ICU.
+ */
+export declare function zonedParts(instant: Date, timezone: string): ZonedParts;

package/dist/semantic/transforms/dag.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Ordonnancement des transformations.
+ *
+ * Réécriture d'après le concept de Metabase (`src/metabase/transforms/dag.clj`,
+ * Clojure) : rien n'est repris de l'amont. L'algorithme retenu est celui du
+ * cycle de dépendances — un tri topologique par l'algorithme de Kahn, avec un
+ * départage déterministe afin que deux exécutions du même graphe produisent
+ * le même ordre.
+ */
+export interface TransformDependencyNode {
+    id: string;
+    dependsOn: string[];
+}
+export interface TransformPlan {
+    /** Les identifiants dans l'ordre d'exécution. Vide si un cycle existe. */
+    order: string[];
+    /** Les identifiants pris dans un cycle, triés. `null` si le graphe est acyclique. */
+    cycle: string[] | null;
+}
+export type TransformFreshness = "fresh" | "stale" | "unknown";
+export interface TransformFreshnessResult {
+    freshness: TransformFreshness;
+    ageMs: number | null;
+}
+/**
+ * Planifie l'ordre d'exécution d'un graphe de transformations.
+ *
+ * Une dépendance vers un identifiant **inconnu** est ignorée : une
+ * transformation supprimée ne doit pas bloquer le reste du graphe. Un cycle,
+ * lui, est bloquant : il est signalé et aucune transformation n'est ordonnée.
+ */
+export declare function planTransformOrder(nodes: TransformDependencyNode[]): TransformPlan;
+/**
+ * Détecte un cycle de dépendances. Renvoie les identifiants concernés, triés,
+ * ou `null` si le graphe est acyclique.
+ */
+export declare function detectTransformCycle(nodes: TransformDependencyNode[]): string[] | null;
+/**
+ * Calcule l'état de fraîcheur d'une transformation à partir de son dernier
+ * Succès. Une date absente ou illisible donne `"unknown"` : mieux vaut dire
+ * qu'on ne sait pas que prétendre que la donnée est fraîche.
+ */
+export declare function computeTransformFreshness(lastRunAt: string | null, maxAgeMs: number, now?: number): TransformFreshnessResult;

package/dist/semantic/types.d.ts

@@ -0,0 +1,199 @@
+import type { QueryFilter } from "../seo-query-builder";
+import type { ParameterValues, SemanticParameter } from "./parameters/types";
+import type { MetricExpr } from "./expr";
+import type { PivotSpec } from "./pivot";
+/**
+ * Spécification d'une fonction fenêtrée.
+ *
+ * `partitionBy` + `orderBy` + `frame` définissent la fenêtre ; `expr` est la
+ * valeur sur laquelle la fonction s'applique.
+ */
+export interface WindowSpec {
+    /** Fonction fenêtrée : rowNumber, rank, denseRank, percentRank, cumeDist, ntile, lag, lead, firstValue, lastValue, nthValue. */
+    fn: WindowFunction;
+    /** Expression sur laquelle la fonction s'applique. */
+    expr: MetricExpr;
+    /** Colonnes de partitionnement (optionnel : fenêtre sur toute la table). */
+    partitionBy?: string[];
+    /** Tri de la fenêtre. */
+    orderBy?: {
+        by: string;
+        dir: "asc" | "desc";
+    }[];
+    /** Cadre de la fenêtre : rows, range, ou groups. */
+    frame?: WindowFrame;
+    /** Offset pour lag/lead (par défaut 1). */
+    offset?: number;
+    /** N pour ntile ou nthValue. */
+    n?: number;
+}
+/** Fonctions fenêtrées supportées par le compilateur. */
+export type WindowFunction = "rowNumber" | "rank" | "denseRank" | "percentRank" | "cumeDist" | "ntile" | "lag" | "lead" | "firstValue" | "lastValue" | "nthValue";
+/**
+ * Cadre de fenêtre (frame).
+ *
+ * Définit le jeu de lignes relatives à la ligne courante sur lesquelles la
+ * fonction s'applique.
+ */
+export interface WindowFrame {
+    units: "rows" | "range" | "groups";
+    /** Bordure inférieure : nombre de lignes/range, ou « current row », « unbounded ». */
+    start: FrameBound;
+    /** Bordure supérieure : nombre de lignes/range, ou « current row », « unbounded », ou vide (jusqu'à la fin). */
+    end?: FrameBound;
+}
+/** Valeur de bordure de fenêtre. */
+export type FrameBound = {
+    kind: "current";
+} | {
+    kind: "unbounded";
+} | {
+    kind: "offset";
+    value: number;
+};
+/**
+ * Spécification d'une CTE (Common Table Expression).
+ *
+ * Une CTE nommée `with` peut être référencée par les étapes suivantes.
+ */
+export interface CteSpec {
+    /** Nom de la CTE (utilisé dans le SQL comme `cte_name`). */
+    name: string;
+    /** Requête qui produit la CTE. Peut référencer des CTE précédentes par leur nom. */
+    query: SemanticQuery;
+}
+/**
+ * Le vocabulaire du noyau semantique.
+ *
+ * Un modele semantique decrit une source de donnees (une table, une vue, un
+ * `baseSql` inline) avec ses dimensions et ses metriques. Les filtres, les
+ * tris et les limites sont poses au niveau de la requete, jamais dans le
+ * modele : un meme modele sert donc a plusieurs requetes.
+ *
+ * Une requete se compile en SQL parametré (`compiler.ts`) et s'evalue en
+ * memoire (`eval-memory.ts`) : les deux backends doivent produire le meme
+ * resultat.
+ */
+/**
+ * Les listes de valeurs sont **runtime** : elles servent de source de verite
+ * pour valider ce qui est persiste en base (les colonnes correspondantes sont
+ * du `text` sans contrainte SQL). Les types sont derives de ces listes, donc
+ * ils ne peuvent pas diverger.
+ */
+export declare const SEMANTIC_SOURCE_KINDS: readonly ["clickhouse", "d1", "postgres", "inline"];
+export type SemanticSourceKind = (typeof SEMANTIC_SOURCE_KINDS)[number];
+export interface SemanticSource {
+    kind: SemanticSourceKind;
+    label: string;
+    table?: string;
+    /**
+     * Colonne qui porte l'identifiant de projet.
+     *
+     * Renseignee, le compilateur ajoute le filtre d'isolation du projet a la
+     * requete : un modele qui lit une table physique ne doit jamais pouvoir
+     * lire les lignes d'un autre tenant. Un modele compile dans un contexte
+     * multi-tenant qui ne declare ni `baseSql` filtree ni `projectColumn` est
+     * refuse : l'echec doit etre bruyant, pas silencieux.
+     */
+    projectColumn?: string;
+}
+export declare const SEMANTIC_FIELD_TYPES: readonly ["string", "number", "date", "boolean"];
+export type SemanticFieldType = (typeof SEMANTIC_FIELD_TYPES)[number];
+export interface SemanticDimension {
+    name: string;
+    expression: MetricExpr;
+    type: SemanticFieldType;
+    description?: string;
+    segmentable?: boolean;
+    /**
+     * Fuseau horaire IANA de la dimension (`Europe/Paris`). La troncature de
+     * la dimension se fait alors dans l'heure murale de ce fuseau, et non en
+     * UTC. SQLite ne sait pas le faire : la compilation echoue explicitement
+     * plutot que de produire un jour faux.
+     */
+    timezone?: string;
+}
+export declare const SEMANTIC_METRIC_UNITS: readonly ["ratio", "percent", "position", "score", "count", "duration", "currency"];
+export type SemanticMetricUnit = (typeof SEMANTIC_METRIC_UNITS)[number];
+export declare const SEMANTIC_METRIC_DIRECTIONS: readonly ["up", "down", "neutral"];
+export type SemanticMetricDirection = (typeof SEMANTIC_METRIC_DIRECTIONS)[number];
+export interface SemanticMetric {
+    name: string;
+    expression: MetricExpr;
+    type?: SemanticFieldType;
+    unit?: SemanticMetricUnit;
+    direction?: SemanticMetricDirection;
+    format?: string;
+    description?: string;
+}
+export interface SemanticJoin {
+    model: string;
+    on: {
+        left: MetricExpr;
+        right: MetricExpr;
+    };
+    type?: "inner" | "left";
+}
+export interface SemanticModel {
+    id: string;
+    name: string;
+    source: SemanticSource;
+    baseSql?: string;
+    joins?: SemanticJoin[];
+    dimensions: SemanticDimension[];
+    metrics: SemanticMetric[];
+    /**
+     * Parametres declares par le modele.
+     *
+     * Un `baseSql` qui contient `{{country}}` n'est exploitable que si
+     * `country` est declare ici : la declaration porte le type et la valeur
+     * par defaut, la requete ne porte que les valeurs.
+     */
+    parameters?: SemanticParameter[];
+    description?: string;
+    version: number;
+    updatedAt: string;
+}
+export interface SemanticSegment {
+    id: string;
+    name: string;
+    model: string;
+    filter: QueryFilter;
+    description?: string;
+}
+export interface SemanticQuery {
+    model: string;
+    dimensions: string[];
+    metrics: string[];
+    filters: QueryFilter[];
+    sort?: {
+        by: string;
+        dir: "asc" | "desc";
+    }[];
+    limit?: number;
+    offset?: number;
+    /** Parametres declares par la requete. */
+    parameters?: SemanticParameter[];
+    /** Valeurs fournies pour les parametres declares. */
+    parameterValues?: ParameterValues;
+    /**
+     * Croisement demande pour cette requete.
+     *
+     * Le pivot fait partie de la requete et non de l'affichage : la reponse
+     * servie — par l'API comme par le studio — est deja croisee.
+     */
+    pivot?: PivotSpec;
+    /** Fonctions fenêtrées à ajouter au SELECT. */
+    windows?: WindowSpec[];
+    /** CTEs (WITH clause) préalables à la requête principale. */
+    with?: CteSpec[];
+}
+export interface CompiledColumn {
+    name: string;
+    type: SemanticFieldType;
+}
+export interface CompiledQuery {
+    sql: string;
+    params: unknown[];
+    columns: CompiledColumn[];
+}

package/dist/semantic/vocabulary.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Vocabulaire partagé de la couche sémantique.
+ *
+ * Les opérateurs de filtre et les fonctions d'agrégation sont définis une
+ * seule fois, dans `seo-query-builder.ts`. La couche sémantique les réexporte
+ * au lieu de les redéfinir : un second vocabulaire de filtrage ferait
+ * diverger l'explorateur SEO du moteur sémantique.
+ */
+export { AGGREGATE_FUNCTIONS, FILTER_OPERATORS, } from "../seo-query-builder";
+export type { AggregateFunction, FilterOperator, QueryFilter, QueryValue, } from "../seo-query-builder";

package/dist/semantic-auditor.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Semantic Page Auditor & LLM Judgment Engine
+ *
+ * Implements the semantic quality evaluations below:
+ * (helpfulness, specificity, trust, citability, answer-first, next-step, cannibalization)
+ * with structured JSON schemas compatible with Gemini, Claude, OpenAI, and Workers AI.
+ */
+import { type SearchCentralFinding } from "./rules/search-central-catalog";
+export type PageTypeEnum = "homepage" | "product_or_service" | "listing" | "article" | "about" | "contact_or_location" | "pricing" | "proof" | "support" | "legal_or_policy" | "other";
+export type SearchIntentEnum = "informational" | "commercial" | "transactional" | "navigational" | "local" | "unclear";
+export type ActionRecommendation = "keep" | "rewrite" | "merge_or_remove";
+export interface PageSemanticEvaluation {
+    url: string;
+    pageType: PageTypeEnum;
+    intent: SearchIntentEnum;
+    importance: number;
+    helpfulness: number;
+    specificity: number;
+    trust: number;
+    citable: number;
+    answerFirst: boolean;
+    clearNextStep: boolean;
+    titleFit: number;
+    metaFit: number;
+    action: ActionRecommendation;
+    reasoning?: string;
+}
+export interface SiteSemanticEvaluation {
+    businessModel: string;
+    valuePropClarity: number;
+    entityClarity: boolean;
+    topicalFocus: number;
+    servesLocalArea: boolean;
+}
+export interface CannibalizationPair {
+    urlA: string;
+    urlB: string;
+    similarity: number;
+    isSubstitute: boolean;
+    explanation: string;
+}
+export declare const SEMANTIC_AUDIT_SYSTEM_PROMPT = "You are an expert SEO quality auditor evaluating web pages against Google Search Central guidelines and AI search retrieval principles (E-E-A-T).\nAssess the supplied page text strictly based on verifiable evidence.\nScore attributes between 0.0 (very poor) and 1.0 (outstanding).\n- helpfulness: Does the page directly satisfy the visitor's topic intent with concrete value?\n- specificity: Contains first-hand proof, real numbers, unique examples rather than generic AI slop.\n- trust: Shows clear accountability, authoritativeness, credentials, or verified business context.\n- citable: Contains clear, self-contained factual statements suitable for citation by AI models (Perplexity, ChatGPT, Gemini).\n- answerFirst: Does the introductory section immediately deliver the direct answer before filler?\n- clearNextStep: Does the page invite a clear, appropriate call to action?\nOutput strictly valid JSON matching the schema.";
+export declare function buildPageSemanticPrompt(page: {
+    url: string;
+    title: string;
+    h1: string;
+    metaDescription?: string;
+    content: string;
+    siteContext?: string;
+}): string;
+export declare function parseSemanticEvaluationToFindings(evals: PageSemanticEvaluation[], siteEval?: SiteSemanticEvaluation): SearchCentralFinding[];