page-analyzer 1.0.0

package/extractors/context-extractor.js

@@ -0,0 +1,275 @@
+import { CssSelectorBuilder } from './css-selector-builder.js';
+import { Context } from '../models/context.js';
+import { normalizeText } from '../utils/text-utils.js';
+
+/**
+ * Extracts enhanced context information for DOM elements
+ */
+export class ContextExtractor {
+  constructor(config = {}) {
+    const level = String(config.contextLevel || '').trim().toLowerCase();
+    const contextLevel = level === 'lean' ? 'lean' : 'full';
+
+    this.config = {
+      maxParentTextLength: config.maxParentTextLength || 100,
+      maxAncestorDepth: config.maxAncestorDepth || 5,
+      maxAncestorTextLength: config.maxAncestorTextLength || 100,
+      maxNearbyTexts: config.maxNearbyTexts || 5,
+      contextLevel
+    };
+  }
+
+  extract($, elem) {
+    const context = new Context();
+    const selectors = CssSelectorBuilder.buildCandidates($, elem);
+    const includeAncestorText = this.config.contextLevel === 'full';
+    const ancestorDepth = this.config.contextLevel === 'lean'
+      ? Math.min(2, this.config.maxAncestorDepth)
+      : this.config.maxAncestorDepth;
+
+    context.parentTag = this.getParentTag($, elem);
+    context.parentText = this.getParentText($, elem);
+    context.ancestorTrail = this.getAncestorTrail($, elem, {
+      includeText: includeAncestorText,
+      maxDepth: ancestorDepth
+    });
+    context.cssSelector = selectors.primary;
+    context.selectorCandidates = selectors.candidates;
+    context.nearbyText = this.getNearbyText($, elem);
+    context.semanticAnchors = this.getSemanticAnchors($, elem);
+    context.containerMeta = this.getContainerMeta($, elem);
+
+    return context;
+  }
+
+  collectTextWithBudget(node, maxChars = 100, options = {}) {
+    const limit = Math.max(0, Number.parseInt(maxChars, 10) || 0);
+    if (!node || limit === 0) {
+      return '';
+    }
+
+    const includeDescendants = options.includeDescendants !== false;
+    const queue = [node];
+    const parts = [];
+    let remaining = limit;
+
+    while (queue.length > 0 && remaining > 0) {
+      const current = queue.shift();
+      if (!current) {
+        continue;
+      }
+
+      const children = Array.isArray(current.children) ? current.children : [];
+
+      for (const child of children) {
+        if (remaining <= 0) {
+          break;
+        }
+        if (child.type !== 'text') {
+          continue;
+        }
+
+        const normalized = normalizeText(child.data);
+        if (!normalized) {
+          continue;
+        }
+
+        if (normalized.length <= remaining) {
+          parts.push(normalized);
+          remaining -= normalized.length;
+        } else {
+          parts.push(normalized.slice(0, remaining));
+          remaining = 0;
+        }
+      }
+
+      if (!includeDescendants) {
+        continue;
+      }
+
+      for (const child of children) {
+        if (child.type !== 'tag') {
+          continue;
+        }
+
+        const tagName = String(child.name || '').toLowerCase();
+        if (tagName === 'script' || tagName === 'style' || tagName === 'noscript') {
+          continue;
+        }
+        queue.push(child);
+      }
+    }
+
+    return normalizeText(parts.join(' ')).slice(0, limit);
+  }
+
+  getParentNode($, elem) {
+    const parent = $(elem).parent();
+    return parent.length > 0 ? (parent[0] || null) : null;
+  }
+
+  getParentTag($, elem) {
+    return this.getParentNode($, elem)?.name || '';
+  }
+
+  getParentText($, elem) {
+    const parentNode = this.getParentNode($, elem);
+    if (!parentNode) {
+      return '';
+    }
+    return this.collectTextWithBudget(parentNode, this.config.maxParentTextLength);
+  }
+
+  _collectAttributes(node) {
+    const source = node?.attribs || {};
+    const attributes = {};
+
+    if (source.class) attributes.class = source.class;
+    if (source.id) attributes.id = source.id;
+    if (source.role) attributes.role = source.role;
+
+    Object.keys(source).forEach(key => {
+      if (key.startsWith('data-')) {
+        attributes[key] = source[key];
+      }
+    });
+
+    return attributes;
+  }
+
+  getAncestorTrail($, elem, options = {}) {
+    const includeText = options.includeText !== false;
+    const maxDepth = Math.max(
+      0,
+      Number.parseInt(options.maxDepth, 10) || this.config.maxAncestorDepth
+    );
+    const ancestors = [];
+    let parent = $(elem).parent();
+    let depth = 1;
+
+    while (parent.length && parent[0].name !== 'html' && depth <= maxDepth) {
+      const node = parent[0];
+      const ancestor = {
+        tag: node?.name || '',
+        attributes: this._collectAttributes(node),
+        depth
+      };
+
+      if (includeText) {
+        const text = this.collectTextWithBudget(node, this.config.maxAncestorTextLength || 80);
+        if (text) {
+          ancestor.text = text;
+        }
+      }
+
+      ancestors.push(ancestor);
+      parent = parent.parent();
+      depth += 1;
+    }
+
+    return ancestors;
+  }
+
+  getNearbyText($, elem) {
+    const texts = [];
+    const parentNode = this.getParentNode($, elem);
+    const maxNearbyTexts = this.config.maxNearbyTexts;
+    const appendText = (value) => {
+      const normalized = normalizeText(value);
+      if (!normalized || normalized.length <= 5) {
+        return;
+      }
+      texts.push(normalized.slice(0, 100));
+    };
+
+    if (parentNode && Array.isArray(parentNode.children)) {
+      for (const child of parentNode.children) {
+        if (child.type !== 'text') {
+          continue;
+        }
+        appendText(child.data);
+        if (texts.length >= maxNearbyTexts) {
+          return texts.slice(0, maxNearbyTexts);
+        }
+      }
+    }
+
+    const prev = $(elem).prev();
+    const next = $(elem).next();
+
+    if (prev.length) {
+      appendText(this.collectTextWithBudget(prev[0], 100));
+    }
+
+    if (next.length) {
+      appendText(this.collectTextWithBudget(next[0], 100));
+    }
+
+    return texts.slice(0, maxNearbyTexts);
+  }
+
+  getSemanticAnchors($, elem) {
+    const anchors = {
+      heading: null,
+      imageAlt: null
+    };
+
+    let current = $(elem);
+    let foundHeading = false;
+
+    while (current.length && !foundHeading && current[0].name !== 'body') {
+      const heading = current.prevAll('h1, h2, h3, h4, h5, h6').first();
+      if (heading.length) {
+        anchors.heading = this.collectTextWithBudget(heading[0], 120);
+        foundHeading = true;
+      } else {
+        current = current.parent();
+      }
+    }
+
+    const nearbyImg = $(elem).find('img').first();
+    if (nearbyImg.length) {
+      const alt = nearbyImg.attr('alt');
+      if (alt) {
+        anchors.imageAlt = alt;
+      }
+    } else {
+      const siblingImg = $(elem).siblings('img').first();
+      if (siblingImg.length) {
+        const alt = siblingImg.attr('alt');
+        if (alt) {
+          anchors.imageAlt = alt;
+        }
+      } else {
+        const parentImg = $(elem).parent().find('img').first();
+        if (parentImg.length) {
+          const alt = parentImg.attr('alt');
+          if (alt) {
+            anchors.imageAlt = alt;
+          }
+        }
+      }
+    }
+
+    return anchors;
+  }
+
+  getContainerMeta($, elem) {
+    const parentNode = this.getParentNode($, elem);
+    if (!parentNode) {
+      return {
+        cssSelector: '',
+        attributes: {}
+      };
+    }
+
+    return {
+      cssSelector: CssSelectorBuilder.build($, parentNode),
+      attributes: {
+        class: parentNode.attribs?.class || '',
+        id: parentNode.attribs?.id || '',
+        role: parentNode.attribs?.role || ''
+      }
+    };
+  }
+}

package/extractors/css-selector-builder.js

@@ -0,0 +1,202 @@
+import { escapeAttributeValue, isLikelyStableClassToken } from '../utils/selector-utils.js';
+
+/**
+ * Builds CSS selector paths for DOM elements
+ */
+export class CssSelectorBuilder {
+  static validateSelector($, selector) {
+    if (!selector) {
+      return false;
+    }
+
+    try {
+      $(selector);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  static isUniqueSelector($, selector) {
+    if (!this.validateSelector($, selector)) {
+      return false;
+    }
+
+    try {
+      return $(selector).length === 1;
+    } catch {
+      return false;
+    }
+  }
+
+  static addCandidate(candidates, selector, $) {
+    const normalized = (selector || '').trim();
+    if (!normalized) {
+      return;
+    }
+
+    if (candidates.includes(normalized)) {
+      return;
+    }
+
+    if (!this.validateSelector($, normalized)) {
+      return;
+    }
+
+    candidates.push(normalized);
+  }
+
+  static build($, elem) {
+    if (!elem || !elem.name) {
+      return '';
+    }
+
+    const path = [];
+    let current = $(elem);
+
+    while (current.length && current[0].name !== 'body' && current[0].name !== 'html') {
+      const parent = current.parent();
+
+      if (!parent.length || parent[0].name === 'html') {
+        break;
+      }
+
+      const index = parent.children().index(current);
+      const tagName = current[0].name;
+
+      path.unshift(`${tagName}:nth-child(${index + 1})`);
+
+      current = parent;
+    }
+
+    if (path.length > 0) {
+      path.unshift('body');
+    } else if (current[0]?.name === 'body') {
+      const bodyChildren = $('body').children();
+      const index = bodyChildren.index(elem);
+      const tagName = elem.name;
+      return `body > ${tagName}:nth-child(${index + 1})`;
+    }
+
+    return path.join(' > ');
+  }
+
+  static buildNthOfType($, elem) {
+    if (!elem || !elem.name) {
+      return '';
+    }
+
+    const path = [];
+    let current = $(elem);
+
+    while (current.length && current[0].name !== 'body' && current[0].name !== 'html') {
+      const parent = current.parent();
+      if (!parent.length || parent[0].name === 'html') {
+        break;
+      }
+
+      const tagName = current[0].name;
+      const sameTagSiblings = parent.children(tagName);
+      const index = sameTagSiblings.index(current[0]);
+      path.unshift(`${tagName}:nth-of-type(${index + 1})`);
+      current = parent;
+    }
+
+    if (path.length > 0) {
+      path.unshift('body');
+    } else if (current[0]?.name === 'body') {
+      const tagName = elem.name;
+      const sameTagChildren = $('body').children(tagName);
+      const index = sameTagChildren.index(elem);
+      return `body > ${tagName}:nth-of-type(${index + 1})`;
+    }
+
+    return path.join(' > ');
+  }
+
+  static buildCandidates($, elem) {
+    if (!elem || !elem.name) {
+      return { primary: '', candidates: [] };
+    }
+
+    const $elem = $(elem);
+    const tagName = elem.name;
+    const candidates = [];
+    const stableFirst = [];
+    const escaped = (value) => escapeAttributeValue(value);
+
+    const id = $elem.attr('id');
+    if (id) {
+      stableFirst.push(`[id="${escaped(id)}"]`);
+    }
+
+    const stableDataAttrs = [
+      'data-testid',
+      'data-test',
+      'data-qa',
+      'data-track',
+      'data-tracking-id',
+      'data-tid'
+    ];
+    for (const attrName of stableDataAttrs) {
+      const attrValue = $elem.attr(attrName);
+      if (attrValue) {
+        stableFirst.push(`[${attrName}="${escaped(attrValue)}"]`);
+      }
+    }
+
+    const href = $elem.attr('href');
+    if (tagName === 'a' && href) {
+      stableFirst.push(`a[href="${escaped(href)}"]`);
+    }
+
+    const name = $elem.attr('name');
+    if (name) {
+      stableFirst.push(`${tagName}[name="${escaped(name)}"]`);
+    }
+
+    const ariaLabel = $elem.attr('aria-label');
+    if (ariaLabel) {
+      stableFirst.push(`${tagName}[aria-label="${escaped(ariaLabel)}"]`);
+    }
+
+    const title = $elem.attr('title');
+    if (title) {
+      stableFirst.push(`${tagName}[title="${escaped(title)}"]`);
+    }
+
+    const alt = $elem.attr('alt');
+    if (alt) {
+      stableFirst.push(`${tagName}[alt="${escaped(alt)}"]`);
+    }
+
+    const className = $elem.attr('class');
+    if (className) {
+      const stableClassTokens = className
+        .split(/\s+/)
+        .map((token) => token.trim())
+        .filter((token) => isLikelyStableClassToken(token))
+        .slice(0, 3);
+
+      if (stableClassTokens.length > 0) {
+        const classSelector = `${tagName}${stableClassTokens.map((token) => `[class~="${escaped(token)}"]`).join('')}`;
+        stableFirst.push(classSelector);
+      }
+    }
+
+    const uniqueStableSelectors = stableFirst.filter((selector) => this.isUniqueSelector($, selector));
+    uniqueStableSelectors.forEach((selector) => this.addCandidate(candidates, selector, $));
+    stableFirst.forEach((selector) => this.addCandidate(candidates, selector, $));
+
+    const nthOfTypePath = this.buildNthOfType($, elem);
+    const nthChildPath = this.build($, elem);
+
+    this.addCandidate(candidates, nthOfTypePath, $);
+    this.addCandidate(candidates, nthChildPath, $);
+
+    return {
+      primary: uniqueStableSelectors[0] || nthOfTypePath || nthChildPath || candidates[0] || '',
+      candidates
+    };
+  }
+}