@lynxflow/seo-engine 2.8.0 → 3.2.1

package/dist/meta-ad-library-intelligence.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 🕵️ LynxSEO Meta Ads Library Intelligence & Competitive Creative Tracker
+ *
+ * Repris et adapté sous licence MIT depuis inspiration/03-social-ad-intelligence/repos/nalarin-agentic-ads-studio (backend/app/services/scraper.py).
+ *
+ * Fonctionnalités :
+ * 1. Recherche d'annonces concurrentes (Meta Ads Library Archive API v21+ & fallback).
+ * 2. Déduplication par empreinte de contenu unique (SHA-256 de text + pageId + mediaType).
+ * 3. Compteur d'occurrences et suivi de longévité (`seenCount`, `firstSeenAt`, `lastSeenAt`)
+ *    permettant de détecter les "Winners" (les pubs qui tournent depuis des mois sans interruption).
+ * 4. Planification et suivi de recherches programmées (Daily / Weekly).
+ */
+export interface ScrapedAdItem {
+    id: string;
+    pageId: string;
+    pageName: string;
+    adText: string;
+    headline?: string;
+    caption?: string;
+    linkUrl?: string;
+    ctaText?: string;
+    mediaType: "image" | "video" | "carousel" | "text_only";
+    mediaUrl?: string;
+    firstSeenAt: string;
+    lastSeenAt: string;
+    seenCount: number;
+    contentHash: string;
+    isActive: boolean;
+    reachedCountries?: string[];
+}
+export interface AdLibrarySearchOptions {
+    query: string;
+    country?: string;
+    limit?: number;
+    mediaType?: "ALL" | "IMAGE" | "VIDEO";
+    negativeKeywords?: string[];
+    excludeContentHashes?: string[];
+}
+export interface ScheduledAdSearch {
+    id: string;
+    query: string;
+    country: string;
+    frequency: "daily" | "weekly";
+    lastRunAt?: string;
+    nextRunAt: string;
+    totalAdsTracked: number;
+    newAdsLastRun: number;
+    isActive: boolean;
+}
+export declare class MetaAdLibraryIntelligence {
+    /**
+     * Calcule le hash de contenu canonique pour dédupliquer les annonces identiques.
+     */
+    static computeAdContentHash(params: {
+        pageId: string;
+        adText: string;
+        headline?: string;
+        mediaType: string;
+    }): string;
+    /**
+     * Filtre et déduplique une liste brute d'annonces avec suivi de longévité.
+     */
+    static processAndDeduplicateAds(rawAds: Array<{
+        id: string;
+        pageId: string;
+        pageName: string;
+        adText: string;
+        headline?: string;
+        mediaType: "image" | "video" | "carousel" | "text_only";
+        mediaUrl?: string;
+        linkUrl?: string;
+        ctaText?: string;
+        isActive?: boolean;
+    }>, existingDatabase?: Map<string, ScrapedAdItem>, negativeKeywords?: string[]): {
+        uniqueAds: ScrapedAdItem[];
+        newCount: number;
+        updatedCount: number;
+        filteredByKeywordsCount: number;
+    };
+    /**
+     * Identifie les annonces "Evergreen Winners" (qui tournent depuis longtemps et ont un high seen_count).
+     */
+    static identifyWinningAds(ads: ScrapedAdItem[], options?: {
+        minSeenCount?: number;
+        minDaysActive?: number;
+    }): ScrapedAdItem[];
+    /**
+     * Construit l'URL d'interrogation de l'API Graph Meta v21.0 Ads Archive.
+     */
+    static buildMetaAdsArchiveApiUrl(options: AdLibrarySearchOptions, accessToken: string): string;
+}

package/dist/metric-glossary.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Organization-curated metric glossary.
+ *
+ * Every team that reports on the same product tends to invent its own name for
+ * the same number. This glossary gives each metric one id, one unit and one
+ * owner, plus aliases so older dashboards can still resolve their references.
+ * Creation, validation and merging are all pure and deterministic.
+ */
+export type MetricUnit = "count" | "percent" | "currency" | "duration_ms" | "ratio";
+export interface MetricDefinition {
+    id: string;
+    label: string;
+    description: string;
+    unit: MetricUnit;
+    formula?: string;
+    aliases?: string[];
+    owner?: string;
+    deprecated?: boolean;
+}
+export interface MetricGlossary {
+    version: number;
+    metrics: MetricDefinition[];
+    updatedAt: string;
+}
+export interface MetricGlossaryValidation {
+    valid: boolean;
+    errors: string[];
+}
+/** Creates a version-1 glossary and copies every definition and alias list. */
+export declare function createMetricGlossary(definitions: MetricDefinition[], now?: Date): MetricGlossary;
+/**
+ * Checks the invariants that keep references unambiguous: unique ids,
+ * unique aliases, non-empty labels and a supported unit. Ids and aliases are
+ * compared case-insensitively because reference resolution is case-insensitive.
+ */
+export declare function validateMetricGlossary(glossary: MetricGlossary): MetricGlossaryValidation;
+/**
+ * Resolves a reference by metric id first, then by alias, ignoring case and
+ * surrounding whitespace. Deprecated metrics remain resolvable so archived
+ * dashboards keep rendering; the caller can inspect `deprecated`.
+ */
+export declare function resolveMetricReference(glossary: MetricGlossary, reference: string): MetricDefinition | null;
+/**
+ * Merges an override glossary into a base glossary by exact metric id.
+ * Base order is preserved, override definitions replace in place, new ids are
+ * appended and the merged version moves past both inputs.
+ */
+export declare function mergeMetricGlossaries(base: MetricGlossary, override: MetricGlossary, now?: Date): MetricGlossary;

package/dist/mobile-event-queue.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Bounded offline event queue for mobile clients.
+ *
+ * Mobile SDKs cannot assume connectivity, so events are appended to a local
+ * queue and released in small batches once the transport acknowledges them.
+ * Every operation is a value transformation: the queue can be persisted as
+ * JSON, restored on another device and replayed without hidden state.
+ */
+export interface QueuedMobileEvent {
+    id: string;
+    name: string;
+    timestamp: string;
+    properties?: Record<string, unknown>;
+}
+export interface MobileQueueState {
+    events: QueuedMobileEvent[];
+    droppingSince?: string | null;
+}
+export interface MobileEnqueueInput {
+    name: string;
+    properties?: Record<string, unknown>;
+    timestamp?: string;
+    id?: string;
+}
+/**
+ * Appends an event and keeps the queue within `maxEvents` (500 by default).
+ * The oldest events are dropped first, and `droppingSince` records the
+ * timestamp of the first event lost to the cap. Enqueuing an id that already
+ * exists is a no-op so retries from the SDK cannot duplicate events.
+ */
+export declare function enqueueMobileEvent(state: MobileQueueState | null, input: MobileEnqueueInput, options?: {
+    maxEvents?: number;
+}): MobileQueueState;
+/**
+ * Returns the oldest batch without removing it from the queue. The transport
+ * acknowledges the batch with `acknowledgeMobileBatch` only after a successful
+ * upload, so a crash between flush and ack cannot lose events.
+ */
+export declare function flushMobileBatch(state: MobileQueueState | null, options?: {
+    batchSize?: number;
+}): {
+    batch: QueuedMobileEvent[];
+    remaining: MobileQueueState;
+};
+/** Removes only the events the transport confirmed, preserving queue order. */
+export declare function acknowledgeMobileBatch(state: MobileQueueState, acknowledgedIds: string[]): MobileQueueState;
+/**
+ * Marks the queue as offline. The first offline transition records an ISO
+ * timestamp in `droppingSince`; repeated transitions keep the original marker
+ * so the duration of the outage remains measurable.
+ */
+export declare function markMobileQueueOffline(state: MobileQueueState, now?: Date): MobileQueueState;
+/** Clears the offline marker; queued events are never touched by reconnection. */
+export declare function markMobileQueueOnline(state: MobileQueueState): MobileQueueState;
+export interface MobileSdkSourceOptions {
+    /** Absolute URL of the batch ingestion endpoint. */
+    endpoint: string;
+    projectId: string;
+    storageKey?: string;
+    batchSize?: number;
+    maxEvents?: number;
+}
+/**
+ * Emits a self-contained React Native SDK built on the queue semantics above.
+ * The generated module starts offline-first, drops the oldest events past the
+ * cap, and only removes events from storage after the server acknowledges them.
+ */
+export declare function generateMobileSdkSource(options: MobileSdkSourceOptions): string;

package/dist/monolith-inliner.d.ts

@@ -0,0 +1,20 @@
+export interface MonolithOptions {
+    stripScripts?: boolean;
+    inlineImages?: boolean;
+    inlineStyles?: boolean;
+    maxAssetSizeBytes?: number;
+    timeoutMs?: number;
+}
+export interface MonolithResult {
+    html: string;
+    originalUrl: string;
+    archivedAt: string;
+    totalSizeBytes: number;
+    inlinedAssetsCount: number;
+}
+export declare class MonolithInliner {
+    /**
+     * Bundles an HTML document and its external CSS & images into a single self-contained HTML file.
+     */
+    static bundle(html: string, baseUrl: string, options?: MonolithOptions): Promise<MonolithResult>;
+}

package/dist/multi-source-attribution.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Multi-source attribution.
+ */
+export type MultiSourceModel = "first_touch" | "last_touch" | "linear" | "time_decay";
+export interface MultiSourceTouchpoint {
+    id?: string;
+    visitorId: string;
+    source: string;
+    channel?: string;
+    timestamp: string;
+    converted?: boolean;
+    conversionValue?: number;
+}
+export interface ConversionPath {
+    visitorId: string;
+    sources: string[];
+    channels: string[];
+    touchpoints: MultiSourceTouchpoint[];
+    converted: boolean;
+    conversionValue: number;
+}
+export interface SourceCredit {
+    source: string;
+    touchpoints: number;
+    conversions: number;
+    revenue: number;
+    sharePct: number;
+}
+export interface ChannelCredit {
+    channel: string;
+    touchpoints: number;
+    conversions: number;
+    revenue: number;
+    sharePct: number;
+}
+export interface MultiSourceAttributionResult {
+    model: MultiSourceModel;
+    totalConversions: number;
+    totalRevenue: number;
+    sourceBreakdown: SourceCredit[];
+    channelBreakdown: ChannelCredit[];
+    conversionPaths: ConversionPath[];
+    unattributedConversions: number;
+}
+export interface MultiSourceOptions {
+    halfLifeDays?: number;
+    now?: number;
+}
+export declare function buildConversionPaths(touchpoints: MultiSourceTouchpoint[]): ConversionPath[];
+export declare function weightTouchpoints(path: ConversionPath, model: MultiSourceModel, options?: MultiSourceOptions): Map<string, number>;
+export declare function attributeMultiSource(touchpoints: MultiSourceTouchpoint[], model?: MultiSourceModel, options?: MultiSourceOptions): MultiSourceAttributionResult;
+export declare class MultiSourceAttribution {
+    private readonly touchpoints;
+    private readonly model;
+    private readonly options;
+    constructor(touchpoints: MultiSourceTouchpoint[], model?: MultiSourceModel, options?: MultiSourceOptions);
+    analyze(): MultiSourceAttributionResult;
+    getConversionPaths(): ConversionPath[];
+}

package/dist/multi-touch-attribution.d.ts

@@ -0,0 +1,50 @@
+/**
+ * G14 — Multi‑Touch Attribution.
+ *
+ * Traces a complete SEO journey from First‑Touch → Last‑Touch → Linear → Position
+ * Based → Data‑Driven models, measuring revenue influence on each touchpoint.
+ *
+ * The engine accepts a flat event list, normalises timestamps to ISO strings,
+ * and returns a single AttributionResult that aggregates all model outputs.
+ * No external sources are accessed — the data is consumed locally.
+ */
+export interface AttributionEvent {
+    /** Stable identifier for the event. */
+    id: string;
+    /** Optional user identifier (hashed / pseudonymised). */
+    userId?: string;
+    /** Session identifier – links all touches of a single user visit. */
+    sessionId: string;
+    /** Channel where the interaction occurred. */
+    channel: "seo" | "linkedin" | "organic" | "direct" | "social" | "email";
+    /** ISO‑8601 timestamp of the event. */
+    timestamp: string;
+    /** Optional monetary value (revenue) if this event represents a conversion. */
+    value?: number;
+}
+export interface AttributionWindow {
+    /** Days back from the last touch to consider for the journey. */
+    windowDays: number;
+    /** Model to apply when distributing credit. */
+    attributionModel: "firstTouch" | "lastTouch" | "linear" | "positionBased" | "dataDriven";
+}
+export interface AttributionResult {
+    /** Ordered list of events that constitute the journey. */
+    journey: AttributionEvent[];
+    /** The first SEO touchpoint (if any). */
+    firstTouch: AttributionEvent | null;
+    /** The final touchpoint (any channel). */
+    lastTouch: AttributionEvent | null;
+    /** Name of the model used for the calculation. */
+    model: string;
+    /** Total revenue attributed by the model. */
+    revenueInfluenced: number;
+    /** Touchpoint count broken down by channel. */
+    touchpointsByChannel: Record<string, number>;
+}
+export declare class MultiTouchAttribution {
+    private readonly events;
+    private readonly window;
+    constructor(events: AttributionEvent[], window?: Partial<AttributionWindow>);
+    traceJourney(): AttributionResult;
+}

package/dist/nango-integration.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 🔗 Nango Integration — Agrégation de données tierces via Nango
+ *
+ * Permet de récupérer et d'agréger des données externes (CRM, analytics,
+ * support, marketing automation) via l'API Nango, puis de les fusionner
+ * avec les résultats SERP de LynxSEO.
+ *
+ * Aucune clé API n'est codée en dur : la configuration passe par les
+ * variables d'environnement (NANGO_API_KEY, NANGO_BASE_URL).
+ */
+export type NangoConnectionStatus = "connected" | "disconnected" | "error";
+export interface NangoContact {
+    id: string;
+    email?: string;
+    firstName?: string;
+    lastName?: string;
+    company?: string;
+    createdAt?: string;
+    updatedAt?: string;
+}
+export interface NangoCompany {
+    id: string;
+    name: string;
+    domain?: string;
+    industry?: string;
+    size?: string;
+    createdAt?: string;
+}
+export interface NangoAnalyticsEvent {
+    id: string;
+    name: string;
+    properties: Record<string, unknown>;
+    timestamp: string;
+}
+export interface NangoIntegrationResult {
+    status: NangoConnectionStatus;
+    contacts: NangoContact[];
+    companies: NangoCompany[];
+    events: NangoAnalyticsEvent[];
+    error?: string;
+    fetchedAt: string;
+}
+/** Résultat SERP enrichi avec des données Nango (CRM/analytics). */
+export interface SerpResultWithNango {
+    position: number;
+    title: string;
+    url: string;
+    snippet: string;
+    domain: string;
+    crawlData?: {
+        robotsAllowed: boolean;
+        crawlDelay?: number;
+        sitemap?: string;
+        fetchedAt: string;
+    };
+    /** Données Nango associées à ce domaine (si disponibles). */
+    nango?: {
+        contactsCount: number;
+        companiesCount: number;
+        recentEvents: NangoAnalyticsEvent[];
+    };
+}
+export interface NangoClientConfig {
+    apiKey: string;
+    baseUrl: string;
+    provider?: string;
+}
+/**
+ * Client léger pour l'API Nango. Aucune dépendance externe : utilise fetch.
+ */
+export declare class NangoClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly provider?;
+    constructor(config: NangoClientConfig);
+    private request;
+    listContacts(connectionId: string): Promise<NangoContact[]>;
+    listCompanies(connectionId: string): Promise<NangoCompany[]>;
+    listEvents(connectionId: string): Promise<NangoAnalyticsEvent[]>;
+    getConnectionStatus(connectionId: string): Promise<NangoConnectionStatus>;
+}
+/**
+ * Intégration Nango de haut niveau : agrège CRM + analytics et les fusionne
+ * avec des résultats SERP par correspondance de domaine.
+ */
+export declare class NangoIntegration {
+    private client?;
+    private connectionId?;
+    constructor(config?: NangoClientConfig, connectionId?: string);
+    /** Vérifie si Nango est configuré et connecté. */
+    isConfigured(): boolean;
+    /**
+     * Récupère les données Nango et les associe aux résultats SERP par domaine.
+     * Retourne les résultats enrichis avec les données CRM/analytics.
+     */
+    enrichSerpResults(items: SerpResultWithNango[]): Promise<SerpResultWithNango[]>;
+    /** Requête standalone pour obtenir l'état complet Nango. */
+    fetchIntegrationState(): Promise<NangoIntegrationResult>;
+}

package/dist/nap-consistency-checker.d.ts

@@ -0,0 +1,60 @@
+/**
+ * NAP (Name, Address, Phone) Consistency Checker
+ * Audit de cohérence des mentions locales sur les annuaires et le web pour éliminer
+ * les conflits qui dégradent le classement dans le Pack Local Google Maps.
+ */
+export interface CanonicalNap {
+    businessName: string;
+    streetAddress: string;
+    postalCode: string;
+    city: string;
+    phone: string;
+}
+export interface DirectoryCitation {
+    directoryName: string;
+    url?: string;
+    scrapedName?: string;
+    scrapedAddress?: string;
+    scrapedPhone?: string;
+}
+export interface NapMismatch {
+    field: "name" | "address" | "phone";
+    expected: string;
+    found: string;
+    severity: "high" | "medium" | "low";
+    reason: string;
+}
+export interface DirectoryAuditResult {
+    directoryName: string;
+    url?: string;
+    isConsistent: boolean;
+    score: number;
+    mismatches: NapMismatch[];
+}
+export interface NapAuditSummary {
+    overallScore: number;
+    totalDirectories: number;
+    consistentDirectories: number;
+    inconsistentDirectories: number;
+    criticalMismatchesCount: number;
+    directories: DirectoryAuditResult[];
+    recommendations: string[];
+}
+export declare class NapConsistencyChecker {
+    /**
+     * Normalise un numéro de téléphone en supprimant les espaces, points, tirets et indicatifs
+     */
+    static normalizePhone(phone?: string): string;
+    /**
+     * Normalise une adresse pour tolérer les abréviations courantes (bd, av, r, etc.)
+     */
+    static normalizeAddress(addr?: string): string;
+    /**
+     * Normalise un nom d'entreprise (supprime les extensions légales courantes SA, SAS, SARL)
+     */
+    static normalizeName(name?: string): string;
+    /**
+     * Exécute l'audit complet NAP
+     */
+    static audit(canonical: CanonicalNap, citations: DirectoryCitation[]): NapAuditSummary;
+}

package/dist/narrative-validator.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Narrative Anti-Hallucination & Number Verification Engine
+ */
+export interface NarrativePlanItem {
+    horizon: string;
+    items: string[];
+}
+export interface AuditNarrative {
+    executive_summary: string[];
+    strengths: string[];
+    risks: string[];
+    plan: NarrativePlanItem[];
+    closing?: string;
+    author?: string;
+    automatic?: boolean;
+    unverified_numbers?: string[];
+    effort_mismatches?: string[];
+}
+export declare const EFFORT_TEXT_MAP: Record<number, string>;
+/**
+ * Checks for plan items where the stated effort in parentheses mismatches the action's effort band.
+ */
+export declare function checkEffortMismatches(narrative: AuditNarrative, actions: Array<{
+    action_id: string;
+    effort: number;
+}>): string[];
+/**
+ * Verifies that all numbers cited in the narrative are grounded in audit facts.
+ */
+export declare function checkUnverifiedNumbers(text: string, data: any): string[];
+/**
+ * Validates a narrative against audit data, throwing on schema violations or returning validation flags.
+ */
+export declare function validateNarrative(narrative: any, auditData: any): AuditNarrative;
+/**
+ * Generates an automatic, 100% evidence-grounded narrative if no custom narrative is supplied.
+ */
+export declare function generateAutoNarrative(auditData: any): AuditNarrative;

package/dist/near-duplicate-detector.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 🦁 LynxSEO MinHash Near-Duplicate Detector
+ *
+ * Implements industry-standard MinHash locality-sensitive shingling and Jaccard similarity
+ * estimation.
+ *
+ * Capabilities:
+ * - K-Shingle tokenization with HTML stripping and normalization
+ * - 64-permutation MinHash signature generation with 31-bit Mersenne prime hashing
+ * - High-speed pairwise and clustered near-duplicate detection (>= 80% to 95% similarity)
+ * - Identifies primary canonical candidate vs duplicate cannibalizing URLs
+ */
+export interface PageContentInput {
+    url: string;
+    htmlOrText: string;
+    canonicalUrl?: string | null;
+    statusCode?: number;
+}
+export interface NearDuplicatePair {
+    urlA: string;
+    urlB: string;
+    similarityPercentage: number;
+    isAboveThreshold: boolean;
+}
+export interface NearDuplicateCluster {
+    id: string;
+    primaryUrl: string;
+    duplicateUrls: {
+        url: string;
+        similarityToPrimary: number;
+    }[];
+    severity: "CRITICAL" | "HIGH" | "MEDIUM";
+    recommendation: string;
+}
+export interface NearDuplicateReport {
+    totalUrlsAudited: number;
+    totalClustersFound: number;
+    totalNearDuplicateUrls: number;
+    duplicateRatioPercentage: number;
+    thresholdPercentage: number;
+    clusters: NearDuplicateCluster[];
+    pairs: NearDuplicatePair[];
+}
+export declare class NearDuplicateDetector {
+    private numHashes;
+    private shingleSize;
+    private hashCoefficients;
+    constructor(numHashes?: number, shingleSize?: number);
+    /**
+     * Deterministically generate random hash coefficients (a * x + b) % p
+     */
+    private generateCoefficients;
+    /**
+     * Strip HTML tags, remove non-alphanumeric chars, lowercase, and tokenize into words
+     */
+    extractWords(htmlOrText: string): string[];
+    /**
+     * Generates k-shingles (n-grams of tokens)
+     */
+    generateShingles(words: string[]): Set<string>;
+    /**
+     * Fast 32-bit FNV-1a string hashing
+     */
+    private hashString;
+    /**
+     * Computes the MinHash signature vector for a set of shingles
+     */
+    computeSignature(shingles: Set<string>): number[];
+    /**
+     * Computes MinHash estimated Jaccard similarity between two signatures
+     */
+    static estimateSimilarity(sigA: number[], sigB: number[]): number;
+    /**
+     * Computes exact Jaccard similarity between two shingle sets
+     */
+    static exactJaccard(shinglesA: Set<string>, shinglesB: Set<string>): number;
+    /**
+     * Run comprehensive crawl-wide near-duplicate audit
+     *
+     * @param pages List of crawled pages with content
+     * @param threshold Similarity percentage threshold
+     */
+    audit(pages: PageContentInput[], threshold?: number): NearDuplicateReport;
+}

package/dist/network-intelligence.d.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+export type UsageType = "residential" | "business" | "hosting" | "mobile" | "isp" | "education" | "government" | "unknown";
+export interface NetworkProfile {
+    ip: string;
+    isp?: string;
+    organization?: string;
+    asn?: string;
+    country?: string;
+    usageType: UsageType;
+    isProxy?: boolean;
+    isVpn?: boolean;
+    isTor?: boolean;
+}
+export declare const NetworkProfileSchema: z.ZodObject<{
+    ip: z.ZodString;
+    isp: z.ZodOptional<z.ZodString>;
+    organization: z.ZodOptional<z.ZodString>;
+    asn: z.ZodOptional<z.ZodString>;
+    country: z.ZodOptional<z.ZodString>;
+    usageType: z.ZodEnum<{
+        unknown: "unknown";
+        mobile: "mobile";
+        education: "education";
+        government: "government";
+        business: "business";
+        residential: "residential";
+        hosting: "hosting";
+        isp: "isp";
+    }>;
+    isProxy: z.ZodOptional<z.ZodBoolean>;
+    isVpn: z.ZodOptional<z.ZodBoolean>;
+    isTor: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare function classifyUsageType(profile: Omit<NetworkProfile, "usageType"> & {
+    usageType?: UsageType;
+}): NetworkProfile;
+export declare function isDatacenter(profile: NetworkProfile): boolean;

package/dist/ngram-density-analyzer.d.ts

@@ -1,5 +1,5 @@
 /**
- * 📊 N-Gram Density & Weighted Lexical Frequency Analyzer (Inspiration: advertools/word_frequency.py)
+ * 📊 N-Gram Density & Weighted Lexical Frequency Analyzer
  *
  * Computes 1-gram, 2-gram (bigrams), and 3-gram (trigrams) frequency and density percentages
  * to detect keyword stuffing (> 3.5%) and identify high-value missing co-occurrences.