explorbot 0.1.20 → 0.1.21

package/dist/boat/doc-collector/src/ai/tools.js

@@ -0,0 +1,415 @@
+import { parseResearchSections } from "../../../../src/ai/researcher/parser.js";
+const MAX_PRIMARY_CANDIDATES = 3;
+const MAX_INTERACTIONS = 5;
+const MAX_LINKS = 15;
+const DEFAULT_WAIT_MS = 700;
+const TAB_WAIT_MS = 500;
+export async function collectDocInteractions(explorer, state, research) {
+    const sections = parseResearchSections(research);
+    const transitions = [];
+    const tabGroup = findTabGroup(sections);
+    if (tabGroup) {
+        transitions.push(...(await exploreTabGroup(explorer, tabGroup, state.url)));
+    }
+    for (const candidate of findActionCandidates(sections)) {
+        if (transitions.length >= MAX_INTERACTIONS) {
+            break;
+        }
+        const transition = await executeInteraction(explorer, candidate, state.url, DEFAULT_WAIT_MS);
+        if (!transition) {
+            continue;
+        }
+        transitions.push(transition);
+    }
+    return transitions;
+}
+export function pickDocActionCandidates(research) {
+    return findActionCandidates(parseResearchSections(research)).map((candidate) => ({
+        label: candidate.element.name.trim(),
+        role: candidate.role,
+        section: candidate.sectionName,
+    }));
+}
+async function exploreTabGroup(explorer, tabGroup, restoreUrl) {
+    const transitions = [];
+    for (const element of tabGroup.elements) {
+        const transition = await executeInteraction(explorer, {
+            element,
+            container: tabGroup.container,
+            role: 'tab',
+            sectionName: tabGroup.sectionName,
+        }, restoreUrl, TAB_WAIT_MS);
+        if (!transition) {
+            continue;
+        }
+        transitions.push(transition);
+    }
+    await restoreInteractionState(explorer, restoreUrl, buildPrimaryCommand(tabGroup.elements[0], tabGroup.container));
+    return transitions;
+}
+async function executeInteraction(explorer, candidate, restoreUrl, waitMs) {
+    const beforeState = explorer.getStateManager().getCurrentState();
+    if (!beforeState) {
+        return null;
+    }
+    const executed = await attemptInteraction(explorer, candidate);
+    if (!executed) {
+        return null;
+    }
+    await wait(waitMs);
+    const afterState = explorer.getStateManager().getCurrentState();
+    if (!afterState) {
+        return null;
+    }
+    const ariaChanges = countAriaChanges(beforeState.ariaSnapshot || '', afterState.ariaSnapshot || '');
+    const urlChanged = beforeState.url !== afterState.url;
+    const transition = buildTransition(candidate, beforeState, afterState, {
+        urlChanged,
+        newElements: ariaChanges.newCount,
+        removedElements: ariaChanges.removedCount,
+    });
+    if (urlChanged) {
+        await restoreInteractionState(explorer, restoreUrl);
+    }
+    return transition;
+}
+async function attemptInteraction(explorer, candidate) {
+    const action = explorer.createAction();
+    for (const command of buildClickCommands(candidate.element, candidate.container)) {
+        const success = await action.attempt(command, buildPurpose(candidate), false);
+        if (success) {
+            return true;
+        }
+    }
+    return false;
+}
+async function restoreInteractionState(explorer, restoreUrl, primaryCommand) {
+    if (primaryCommand) {
+        const action = explorer.createAction();
+        const restored = await action.attempt(primaryCommand, `Restore initial state on ${restoreUrl}`, false);
+        if (restored) {
+            await wait(TAB_WAIT_MS);
+            return;
+        }
+    }
+    const action = explorer.createAction();
+    await action.attempt(`I.amOnPage(${JSON.stringify(restoreUrl)})`, `Restore page ${restoreUrl}`, false);
+}
+function buildTransition(candidate, beforeState, afterState, changes) {
+    const transition = {
+        action: describeAction(candidate),
+        before: summarizeInteractiveState(beforeState),
+        after: summarizeInteractiveState(afterState),
+        discoveredUrls: collectLinks(afterState).map((link) => link.url),
+        newCapabilities: collectDiscoveryNotes(afterState, changes),
+        element: buildInteractionElement(candidate),
+        changes,
+    };
+    if (changes.urlChanged) {
+        transition.targetUrl = afterState.url;
+    }
+    return transition;
+}
+function buildInteractionElement(candidate) {
+    const element = {
+        role: candidate.role,
+        name: candidate.element.name.trim(),
+        section: candidate.sectionName,
+    };
+    if (candidate.container) {
+        element.container = candidate.container;
+    }
+    if (candidate.element.css || candidate.element.xpath) {
+        element.locator = candidate.element.css || candidate.element.xpath || undefined;
+    }
+    return element;
+}
+function collectDiscoveryNotes(state, changes) {
+    const notes = [];
+    const headings = collectHeadings(state);
+    const links = collectLinks(state);
+    if (changes.urlChanged) {
+        notes.push('URL changed after interaction');
+    }
+    if (changes.newElements > 0) {
+        notes.push(`ARIA snapshot gained ${changes.newElements} elements`);
+    }
+    if (changes.removedElements > 0) {
+        notes.push(`ARIA snapshot removed ${changes.removedElements} elements`);
+    }
+    if (headings.length > 0) {
+        notes.push(`Visible headings after interaction: ${headings.slice(0, 3).join(' | ')}`);
+    }
+    if (links.length > 0) {
+        notes.push(`Visible links after interaction: ${Math.min(links.length, MAX_LINKS)}`);
+    }
+    return notes;
+}
+function findTabGroup(sections) {
+    for (const section of sections) {
+        const sectionName = section.name.toLowerCase();
+        const container = section.containerCss?.toLowerCase() || '';
+        if (isOverlaySection(sectionName, container)) {
+            continue;
+        }
+        const elements = section.elements.filter((element) => getElementRole(element) === 'tab');
+        if (elements.length < 2 || elements.length > 6) {
+            continue;
+        }
+        return {
+            elements,
+            container: section.containerCss || undefined,
+            sectionName: section.name,
+        };
+    }
+    return null;
+}
+function findActionCandidates(sections) {
+    const candidates = [];
+    const seen = new Set();
+    const navigationLabels = collectNavigationLabels(sections);
+    for (const section of sections) {
+        const sectionName = section.name.toLowerCase();
+        const container = section.containerCss?.toLowerCase() || '';
+        if (isOverlaySection(sectionName, container)) {
+            continue;
+        }
+        if (isNavigationSection(sectionName)) {
+            continue;
+        }
+        for (const element of section.elements) {
+            const candidate = toInteractionCandidate(element, section.name, section.containerCss, navigationLabels);
+            if (!candidate) {
+                continue;
+            }
+            const key = `${candidate.role}:${normalizeCandidateLabel(candidate.element.name)}`;
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            candidates.push(candidate);
+        }
+    }
+    return candidates.sort((a, b) => scoreCandidate(b) - scoreCandidate(a)).slice(0, MAX_PRIMARY_CANDIDATES);
+}
+function toInteractionCandidate(element, sectionName, container, navigationLabels) {
+    const role = getElementRole(element);
+    if (role !== 'link' && role !== 'button' && role !== 'tab') {
+        return null;
+    }
+    if (!hasUsableName(element)) {
+        return null;
+    }
+    if (isShellLocator(element.css) || isShellLocator(element.xpath) || isShellLocator(container)) {
+        return null;
+    }
+    if (role === 'link' && navigationLabels.has(normalizeCandidateLabel(element.name))) {
+        return null;
+    }
+    return {
+        element,
+        container: container || undefined,
+        role,
+        sectionName,
+    };
+}
+function buildClickCommands(element, container) {
+    const commands = [];
+    if (element.css) {
+        if (container && !element.css.startsWith(container)) {
+            commands.push(`I.click(${JSON.stringify(element.css)}, ${JSON.stringify(container)})`);
+        }
+        commands.push(`I.click(${JSON.stringify(element.css)})`);
+    }
+    if (element.aria) {
+        if (container) {
+            commands.push(`I.click(${JSON.stringify(element.aria)}, ${JSON.stringify(container)})`);
+        }
+        commands.push(`I.click(${JSON.stringify(element.aria)})`);
+    }
+    const xpath = buildXPathLocator(element);
+    if (xpath) {
+        commands.push(`I.click(${JSON.stringify(xpath)})`);
+    }
+    return [...new Set(commands)];
+}
+function buildPrimaryCommand(element, container) {
+    return buildClickCommands(element, container)[0] || null;
+}
+function buildXPathLocator(element) {
+    if (!element.name) {
+        return null;
+    }
+    const text = xpathStringLiteral(element.name.trim());
+    const role = getElementRole(element);
+    if (role === 'link') {
+        return `//a[normalize-space()=${text}]`;
+    }
+    if (role === 'button' || role === 'tab') {
+        return `//*[self::button or @role="button" or @role="tab"][normalize-space()=${text}]`;
+    }
+    return `//*[normalize-space()=${text}]`;
+}
+function buildPurpose(candidate) {
+    return `Explore ${candidate.role} ${candidate.element.name.trim()}`;
+}
+function summarizeAria(aria) {
+    const lines = aria.split('\n').filter((line) => line.trim());
+    if (lines.length === 0) {
+        return 'No elements';
+    }
+    const roleCounts = {};
+    for (const role of lines.map(extractAriaRole).filter((role) => Boolean(role))) {
+        roleCounts[role] = (roleCounts[role] || 0) + 1;
+    }
+    const topRoles = Object.entries(roleCounts)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5)
+        .map(([role, count]) => `${role}:${count}`)
+        .join(', ');
+    return `${lines.length} elements (${topRoles})`;
+}
+function extractAriaRole(line) {
+    const roleMatch = line.match(/\[role: ([\w-]+)\]/);
+    if (roleMatch) {
+        return roleMatch[1];
+    }
+    const yamlMatch = line.trim().match(/^- ([\w-]+)(?:\s|$|:)/);
+    if (yamlMatch) {
+        return yamlMatch[1];
+    }
+    return null;
+}
+function countAriaChanges(before, after) {
+    const beforeLines = new Set(before.split('\n').filter((line) => line.trim()));
+    const afterLines = new Set(after.split('\n').filter((line) => line.trim()));
+    let newCount = 0;
+    let removedCount = 0;
+    for (const line of afterLines) {
+        if (!beforeLines.has(line)) {
+            newCount++;
+        }
+    }
+    for (const line of beforeLines) {
+        if (!afterLines.has(line)) {
+            removedCount++;
+        }
+    }
+    return { newCount, removedCount };
+}
+function summarizeInteractiveState(state) {
+    const parts = [summarizeAria(state.ariaSnapshot || '')];
+    const headings = collectHeadings(state).slice(0, 3);
+    const links = collectLinks(state).slice(0, 3);
+    if (state.url) {
+        parts.push(`URL ${state.url}`);
+    }
+    if (headings.length > 0) {
+        parts.push(`Headings: ${headings.map((heading) => limitInlineText(heading, 90)).join(' | ')}`);
+    }
+    if (links.length > 0) {
+        parts.push(`Links: ${links.map((link) => `${link.title} -> ${link.url}`).join('; ')}`);
+    }
+    return parts.join('. ');
+}
+function collectHeadings(state) {
+    return [state.h1, state.h2, state.h3, state.h4].filter((heading) => Boolean(heading)).map((heading) => heading.trim());
+}
+function collectLinks(state) {
+    return (state.links || [])
+        .filter((link) => link.url)
+        .slice(0, MAX_LINKS)
+        .map((link) => ({
+        title: link.title || link.url,
+        url: link.url,
+    }));
+}
+function describeAction(candidate) {
+    return `Clicked ${candidate.role}: ${candidate.element.name.trim()}`;
+}
+function hasUsableName(element) {
+    const name = element.name.trim();
+    if (!name) {
+        return false;
+    }
+    if (name.length < 2) {
+        return false;
+    }
+    return true;
+}
+function isNavigationSection(sectionName) {
+    return /(navigation|menu|header|footer|breadcrumb)/i.test(sectionName);
+}
+function isOverlaySection(sectionName, container) {
+    return /(overlay|modal|popup|dialog)/i.test(sectionName) || /(overlay|modal|popup|dialog)/i.test(container);
+}
+function scoreCandidate(candidate) {
+    let score = 0;
+    if (candidate.role === 'link') {
+        score += 50;
+    }
+    if (candidate.role === 'button') {
+        score += 40;
+    }
+    if (candidate.role === 'tab') {
+        score += 30;
+    }
+    if (candidate.container) {
+        score += 10;
+    }
+    if (candidate.element.css) {
+        score += 5;
+    }
+    if (candidate.element.name.trim().length > 8) {
+        score += 5;
+    }
+    return score;
+}
+function isShellLocator(locator) {
+    if (!locator) {
+        return false;
+    }
+    return /(nav\[role="navigation"\]|header|menu|breadcrumb|footer)/i.test(locator);
+}
+function collectNavigationLabels(sections) {
+    const labels = new Set();
+    for (const section of sections) {
+        if (!isNavigationSection(section.name.toLowerCase())) {
+            continue;
+        }
+        for (const element of section.elements) {
+            const label = normalizeCandidateLabel(element.name);
+            if (!label) {
+                continue;
+            }
+            labels.add(label);
+        }
+    }
+    return labels;
+}
+function normalizeCandidateLabel(label) {
+    return label.trim().toLowerCase();
+}
+function limitInlineText(text, maxLength) {
+    const normalized = text.replace(/\s+/g, ' ').trim();
+    if (normalized.length <= maxLength) {
+        return normalized;
+    }
+    return `${normalized.slice(0, maxLength - 3).trimEnd()}...`;
+}
+function getElementRole(element) {
+    return (element.aria?.role || element.type || '').toLowerCase();
+}
+function xpathStringLiteral(value) {
+    if (!value.includes("'")) {
+        return `'${value}'`;
+    }
+    if (!value.includes('"')) {
+        return `"${value}"`;
+    }
+    const parts = value.split("'").map((part) => `'${part}'`);
+    return `concat(${parts.join(`, "'", `)})`;
+}
+async function wait(timeout) {
+    await new Promise((resolve) => setTimeout(resolve, timeout));
+}

package/dist/boat/doc-collector/src/cli.js

@@ -83,6 +83,7 @@ export function createDocsCommands(name = 'docs') {
             maxPages: 100,
             output: 'docs',
             screenshot: true,
+            interactive: false,
             collapseDynamicPages: true,
             scope: 'site',
             includePaths: [],

package/dist/boat/doc-collector/src/config.js

@@ -104,6 +104,7 @@ class DocbotConfigParser {
                 maxPages: 100,
                 output: 'docs',
                 screenshot: true,
+                interactive: false,
                 collapseDynamicPages: true,
                 scope: 'site',
                 includePaths: [],

package/dist/boat/doc-collector/src/docbot.js

@@ -37,7 +37,7 @@ class DocBot {
             config: this.options.docsConfig,
             path: this.options.path,
         });
-        this.documentarian = new Documentarian(this.explorBot.getProvider(), this.config);
+        this.documentarian = new Documentarian(this.explorBot.getProvider(), this.config, this.explorBot.getExplorer());
         this.ensureDirectory(this.configParser.getOutputDir());
         this.ensureDirectory(this.getPagesDir());
     }
@@ -112,17 +112,21 @@ class DocBot {
                     summary: documentation.summary,
                     canCount: documentation.can.length,
                     mightCount: documentation.might.length,
+                    interactionCount: (documentation.interactions || []).length,
                     canActions: documentation.can.map((item) => item.action),
                     mightActions: documentation.might.map((item) => item.action),
+                    interactionActions: (documentation.interactions || []).map((item) => item.action),
+                    qualityNotes: documentation.qualityNotes || [],
                     filePath,
                 });
                 documented.add(pageKey);
-                const nextPaths = this.extractNextPaths(state, baseUrl, research);
+                const nextPaths = this.extractNextPaths(state, baseUrl, research, documentation);
+                const interactionPriorityPaths = new Set(this.extractInteractionPaths(baseUrl, documentation));
                 for (const nextPath of nextPaths) {
                     if (documented.has(this.getPageKey(nextPath))) {
                         continue;
                     }
-                    if (stateManager.hasVisitedState(nextPath)) {
+                    if (!interactionPriorityPaths.has(nextPath) && stateManager.hasVisitedState(nextPath)) {
                         continue;
                     }
                     this.enqueuePath(nextPath, queue, queued);
@@ -162,9 +166,16 @@ class DocBot {
         }
         return true;
     }
-    extractNextPaths(state, baseUrl, research) {
+    extractNextPaths(state, baseUrl, research, documentation) {
         const paths = [];
         const seen = new Set();
+        for (const interactionPath of this.extractInteractionPaths(baseUrl, documentation)) {
+            if (seen.has(interactionPath)) {
+                continue;
+            }
+            seen.add(interactionPath);
+            paths.push(interactionPath);
+        }
         for (const link of state.links || []) {
             const nextPath = this.resolveLink(link, baseUrl);
             if (!nextPath) {
@@ -197,10 +208,51 @@ class DocBot {
         }
         return paths;
     }
+    extractInteractionPaths(baseUrl, documentation) {
+        const paths = [];
+        const seen = new Set();
+        const interactions = documentation?.interactions;
+        for (const interaction of interactions || []) {
+            if (interaction.targetUrl) {
+                const nextPath = this.resolveRawUrl(interaction.targetUrl, baseUrl);
+                if (nextPath && this.isEligibleNextPath(nextPath) && !seen.has(nextPath)) {
+                    seen.add(nextPath);
+                    paths.push(nextPath);
+                }
+            }
+            for (const discoveredUrl of interaction.discoveredUrls || []) {
+                const discoveredPath = this.resolveRawUrl(discoveredUrl, baseUrl);
+                if (!discoveredPath) {
+                    continue;
+                }
+                if (!this.isEligibleNextPath(discoveredPath)) {
+                    continue;
+                }
+                if (seen.has(discoveredPath)) {
+                    continue;
+                }
+                seen.add(discoveredPath);
+                paths.push(discoveredPath);
+            }
+        }
+        return paths;
+    }
+    isEligibleNextPath(nextPath) {
+        if (!shouldCrawlDocPath(nextPath, this.config)) {
+            return false;
+        }
+        if (!this.isInScope(nextPath)) {
+            return false;
+        }
+        return true;
+    }
     resolveLink(link, baseUrl) {
+        return this.resolveRawUrl(link.url, baseUrl);
+    }
+    resolveRawUrl(rawUrl, baseUrl) {
         let resolved;
         try {
-            resolved = new URL(link.url, baseUrl);
+            resolved = new URL(rawUrl, baseUrl);
         }
         catch {
             return null;

package/dist/boat/doc-collector/src/docs-renderer.js

@@ -11,6 +11,26 @@ function renderPageDocumentation(state, documentation) {
     lines.push('');
     lines.push(ensureSentence(documentation.summary));
     lines.push('');
+    const interactions = documentation.interactions;
+    if (interactions && interactions.length > 0) {
+        lines.push('## State Transitions');
+        lines.push('');
+        for (const transition of interactions) {
+            lines.push(`### ${transition.action}`);
+            lines.push('');
+            lines.push(`**Before:** ${transition.before}`);
+            lines.push('');
+            lines.push(`**After:** ${transition.after}`);
+            lines.push('');
+            if (transition.newCapabilities && transition.newCapabilities.length > 0) {
+                lines.push('**Observed changes:**');
+                for (const cap of transition.newCapabilities) {
+                    lines.push(`- ${cap}`);
+                }
+                lines.push('');
+            }
+        }
+    }
     lines.push('## User Can');
     lines.push('');
     if (documentation.can.length === 0) {
@@ -37,6 +57,15 @@ function renderPageDocumentation(state, documentation) {
     if (documentation.might.length > 0) {
         lines.push('');
     }
+    const qualityNotes = documentation.qualityNotes;
+    if (qualityNotes && qualityNotes.length > 0) {
+        lines.push('## Coverage Notes');
+        lines.push('');
+        for (const note of qualityNotes) {
+            lines.push(`- ${ensureSentence(note)}`);
+        }
+        lines.push('');
+    }
     return `${lines.join('\n').trimEnd()}\n`;
 }
 function renderSpecIndex(outputDir, startPath, pages, skipped, maxPages) {
@@ -63,6 +92,9 @@ function renderSpecIndex(outputDir, startPath, pages, skipped, maxPages) {
         lines.push(`Purpose: ${ensureSentence(page.summary)}`);
         lines.push(`Proven actions: ${page.canCount}`);
         lines.push(`Possible actions: ${page.mightCount}`);
+        if (page.interactionCount > 0) {
+            lines.push(`Interactive transitions: ${page.interactionCount}`);
+        }
         if (page.title) {
             lines.push(`Title: ${normalizeInlineText(page.title)}`);
         }
@@ -81,6 +113,20 @@ function renderSpecIndex(outputDir, startPath, pages, skipped, maxPages) {
             }
             lines.push('');
         }
+        if (page.interactionActions.length > 0) {
+            lines.push('Interactive Findings:');
+            for (const action of page.interactionActions.slice(0, 3)) {
+                lines.push(`- ${normalizeInlineText(action)}`);
+            }
+            lines.push('');
+        }
+        if (page.qualityNotes.length > 0) {
+            lines.push('Coverage Notes:');
+            for (const note of page.qualityNotes) {
+                lines.push(`- ${ensureSentence(note)}`);
+            }
+            lines.push('');
+        }
     }
     if (skipped.length > 0) {
         lines.push('## Skipped');

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",