Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

11.7 KB
Raw Blame
import {
    NotebookBlockNode,
    NotebookComponentProps,
    NotebookDocument,
    NotebookInlineMark,
    NotebookInlineNode,
    NotebookListItem,
    NotebookPropValue,
} from './types'

const nodeFingerprintCache = new WeakMap<NotebookBlockNode, string>()

export function hashString(value: string): string {
    let hash = 5381
    for (let index = 0; index < value.length; index++) {
        hash = (hash * 33) ^ value.charCodeAt(index)
    }
    return (hash >>> 0).toString(36)
}

export function normalizeWhitespace(value: string): string {
    return value.replace(/\s+/g, ' ').trim()
}

export function createStableNodeId(fingerprint: string, occurrence: number): string {
    return `mdn-${hashString(fingerprint)}-${occurrence}`
}

export function ensureUniqueNodeIds(nodes: NotebookBlockNode[]): NotebookBlockNode[] {
    const seenIds = new Set<string>()
    let didChange = false

    const uniqueNodes = nodes.map((node, index) => {
        if (node.id && !seenIds.has(node.id)) {
            seenIds.add(node.id)
            return node
        }

        didChange = true
        let occurrence = 0
        let nextId = createStableNodeId(
            `${node.id || 'empty'}:${getNodeFingerprint(node)}:${String(index)}`,
            occurrence
        )
        while (seenIds.has(nextId)) {
            occurrence += 1
            nextId = createStableNodeId(
                `${node.id || 'empty'}:${getNodeFingerprint(node)}:${String(index)}`,
                occurrence
            )
        }

        seenIds.add(nextId)
        return { ...node, id: nextId }
    })

    return didChange ? uniqueNodes : nodes
}

export function cloneNotebookDocument(document: NotebookDocument): NotebookDocument {
    return JSON.parse(JSON.stringify(document)) as NotebookDocument
}

export function cloneNotebookNode<T extends NotebookBlockNode>(node: T): T {
    return JSON.parse(JSON.stringify(node)) as T
}

export function getInlineText(nodes: NotebookInlineNode[]): string {
    return nodes.map((node) => (node.type === 'hardBreak' ? '\n' : node.text)).join('')
}

export function getNodeText(node: NotebookBlockNode): string {
    if (node.type === 'paragraph' || node.type === 'heading' || node.type === 'blockquote') {
        return getInlineText(node.children)
    }
    if (node.type === 'list') {
        return node.items.map((item) => getInlineText(item.children)).join('\n')
    }
    if (node.type === 'table') {
        return [
            node.headers.map((cell) => getInlineText(cell.children)).join(' '),
            ...node.rows.map((row) => row.map((cell) => getInlineText(cell.children)).join(' ')),
        ].join('\n')
    }
    if (node.type === 'code') {
        return node.text
    }
    if (node.type === 'component') {
        return `${node.tagName}:${JSON.stringify(node.props)}`
    }
    return ''
}

export function getNodeSignature(node: NotebookBlockNode): string {
    if (node.type === 'heading') {
        return `${node.type}:${node.level ?? 1}`
    }
    if (node.type === 'list') {
        return `${node.type}:${node.ordered ? `ordered:${String(node.start ?? 1)}` : 'bullet'}`
    }
    if (node.type === 'table') {
        return `${node.type}:${node.headers.length}`
    }
    if (node.type === 'component') {
        return `${node.type}:${node.tagName}`
    }
    return node.type
}

export function getNodeFingerprint(node: NotebookBlockNode): string {
    const cachedFingerprint = nodeFingerprintCache.get(node)
    if (cachedFingerprint !== undefined) {
        return cachedFingerprint
    }

    const fingerprint = getUncachedNodeFingerprint(node)
    nodeFingerprintCache.set(node, fingerprint)
    return fingerprint
}

/** Adopt a known fingerprint for a node copy whose fingerprint inputs are shared with the
 * original (same tagName and props), so the copy skips re-encoding them. */
export function seedNodeFingerprint(node: NotebookBlockNode, fingerprint: string): void {
    nodeFingerprintCache.set(node, fingerprint)
}

function getUncachedNodeFingerprint(node: NotebookBlockNode): string {
    if (node.type === 'paragraph' || node.type === 'heading' || node.type === 'blockquote') {
        return JSON.stringify({
            type: node.type,
            level: node.level,
            blockquote: node.blockquote,
            children: node.children,
        })
    }
    if (node.type === 'list') {
        return JSON.stringify({
            type: node.type,
            ordered: node.ordered,
            start: node.start,
            items: node.items.map(getListItemFingerprint),
        })
    }
    if (node.type === 'table') {
        return JSON.stringify({
            type: node.type,
            headers: node.headers,
            rows: node.rows,
            alignments: node.alignments,
        })
    }
    if (node.type === 'code') {
        return JSON.stringify({
            type: node.type,
            language: node.language,
            text: node.text,
        })
    }
    if (node.type === 'component') {
        return JSON.stringify({
            type: node.type,
            tagName: node.tagName,
            props: sortProps(node.props),
        })
    }
    return JSON.stringify(node)
}

function getListItemFingerprint(item: NotebookListItem): Omit<NotebookListItem, 'id'> {
    return {
        children: item.children,
        depth: item.depth,
        ordered: item.ordered,
        start: item.start,
        checked: item.checked,
    }
}

export function textSimilarity(left: string, right: string): number {
    const normalizedLeft = normalizeForSimilarity(left)
    const normalizedRight = normalizeForSimilarity(right)
    if (!normalizedLeft && !normalizedRight) {
        return 1
    }
    if (!normalizedLeft || !normalizedRight) {
        return 0
    }
    if (normalizedLeft.includes(normalizedRight) || normalizedRight.includes(normalizedLeft)) {
        const shorterLength = Math.min(normalizedLeft.length, normalizedRight.length)
        if (shorterLength >= 4) {
            return 0.6
        }
        return (
            Math.min(normalizedLeft.length, normalizedRight.length) /
            Math.max(normalizedLeft.length, normalizedRight.length)
        )
    }

    const leftWords = new Set(normalizedLeft.split(' '))
    const rightWords = new Set(normalizedRight.split(' '))
    const intersection = [...leftWords].filter((word) => rightWords.has(word)).length
    const union = new Set([...leftWords, ...rightWords]).size
    return union === 0 ? 0 : intersection / union
}

function normalizeForSimilarity(value: string): string {
    // Punctuation becomes a separator (not stripped), so JSON-ish content — component props
    // are serialized as one JSON blob — tokenizes into comparable words instead of one
    // giant word that any single change makes entirely dissimilar.
    return value
        .toLowerCase()
        .replace(/[^\w]+/g, ' ')
        .trim()
}

export function marksEqual(left: NotebookInlineMark[], right: NotebookInlineMark[]): boolean {
    return JSON.stringify(normalizeInlineMarks(left)) === JSON.stringify(normalizeInlineMarks(right))
}

export function normalizeInlineMarks(marks: NotebookInlineMark[]): NotebookInlineMark[] {
    const dedupedMarks: NotebookInlineMark[] = []
    const seenTypes = new Set<NotebookInlineMark['type']>()

    marks.forEach((mark) => {
        if (seenTypes.has(mark.type)) {
            return
        }
        seenTypes.add(mark.type)
        dedupedMarks.push(mark)
    })

    return dedupedMarks.sort((left, right) => getInlineMarkOrder(left) - getInlineMarkOrder(right))
}

function getInlineMarkOrder(mark: NotebookInlineMark): number {
    if (mark.type === 'code') {
        return 0
    }
    if (mark.type === 'bold') {
        return 1
    }
    if (mark.type === 'italic') {
        return 2
    }
    if (mark.type === 'underline') {
        return 3
    }
    if (mark.type === 'strike') {
        return 4
    }
    if (mark.type === 'mention') {
        return 6
    }
    if (mark.type === 'ref') {
        // Outermost, so the ref tag wraps the fully formatted text.
        return 7
    }
    return 5
}

export function normalizeInlineNodes(nodes: NotebookInlineNode[]): NotebookInlineNode[] {
    const normalized: NotebookInlineNode[] = []

    nodes.forEach((node) => {
        if (node.type === 'hardBreak') {
            if (normalized[normalized.length - 1]?.type !== 'hardBreak') {
                normalized.push(node)
            }
            return
        }

        if (!node.text) {
            return
        }

        const marks = normalizeInlineMarks(node.marks ?? [])
        const previous = normalized[normalized.length - 1]
        if (previous?.type === 'text' && marksEqual(previous.marks ?? [], marks)) {
            previous.text += node.text
            return
        }

        normalized.push({
            ...node,
            marks: marks.length ? marks : undefined,
        })
    })

    return normalized
}

export function isNotebookComponentProps(value: unknown): value is NotebookComponentProps {
    if (!value || typeof value !== 'object' || Array.isArray(value)) {
        return false
    }

    return Object.values(value).every(isNotebookPropValue)
}

export function isNotebookPropValue(value: unknown): value is NotebookComponentProps[string] {
    if (value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
        return true
    }

    if (Array.isArray(value)) {
        return value.every(isNotebookPropValue)
    }

    if (typeof value === 'object') {
        return Object.values(value).every(isNotebookPropValue)
    }

    return false
}

// Project a value onto the serializable NotebookPropValue space — the same JSON.stringify
// normalization markdown serialization applies — dropping nested `undefined` (e.g. an absent
// `label`/`group_type_index` on a person-property filter inside a query). Counterpart to the
// isNotebookPropValue guard: where the guard rejects dirty values, this cleans them. Returns
// `undefined` for values JSON can't represent (top-level `undefined`, functions, symbols), so
// callers can omit the key entirely.
export function toSerializablePropValue(value: unknown): NotebookPropValue | undefined {
    const serialized = JSON.stringify(value)
    if (serialized === undefined) {
        return undefined
    }
    return JSON.parse(serialized) as NotebookPropValue
}

// Project a set of node attributes onto the props a component block can carry, dropping the keys
// whose values markdown can't represent.
export function getSerializableProps<T extends object>(attributes: T): NotebookComponentProps {
    return Object.entries(attributes).reduce<NotebookComponentProps>((props, [key, value]) => {
        // Normalize before validating. isNotebookPropValue rejects an object that holds a nested
        // `undefined`, so an unnormalized value loses its whole key: a person-property filter with
        // an absent `label` or `group_type_index` inside `query.source.properties` takes the entire
        // `query` prop with it. Normalizing first drops those keys, so the guard sees a value
        // markdown can actually carry.
        const normalized = toSerializablePropValue(value)
        if (normalized !== undefined && isNotebookPropValue(normalized)) {
            props[key] = normalized
        }
        return props
    }, {})
}

function sortProps(props: NotebookComponentProps): NotebookComponentProps {
    return Object.keys(props)
        .sort()
        .reduce<NotebookComponentProps>((accumulator, key) => {
            accumulator[key] = sortPropValue(props[key])
            return accumulator
        }, {})
}

function sortPropValue(value: NotebookComponentProps[string]): NotebookComponentProps[string] {
    if (Array.isArray(value)) {
        return value.map(sortPropValue)
    }
    if (value && typeof value === 'object') {
        return sortProps(value)
    }
    return value
}