324 lines
14 KiB
JavaScript
324 lines
14 KiB
JavaScript
"use strict";
|
|
/**
|
|
* @license
|
|
* Copyright Google LLC All Rights Reserved.
|
|
*
|
|
* Use of this source code is governed by an MIT-style license that can be
|
|
* found in the LICENSE file at https://angular.dev/license
|
|
*/
|
|
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
if (k2 === undefined) k2 = k;
|
|
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
}
|
|
Object.defineProperty(o, k2, desc);
|
|
}) : (function(o, m, k, k2) {
|
|
if (k2 === undefined) k2 = k;
|
|
o[k2] = m[k];
|
|
}));
|
|
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
}) : function(o, v) {
|
|
o["default"] = v;
|
|
});
|
|
var __importStar = (this && this.__importStar) || (function () {
|
|
var ownKeys = function(o) {
|
|
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
var ar = [];
|
|
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
return ar;
|
|
};
|
|
return ownKeys(o);
|
|
};
|
|
return function (mod) {
|
|
if (mod && mod.__esModule) return mod;
|
|
var result = {};
|
|
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
__setModuleDefault(result, mod);
|
|
return result;
|
|
};
|
|
})();
|
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
exports.DOC_SEARCH_TOOL = void 0;
|
|
const node_crypto_1 = require("node:crypto");
|
|
const node_stream_1 = require("node:stream");
|
|
const zod_1 = require("zod");
|
|
const constants_1 = require("../constants");
|
|
const tool_registry_1 = require("./tool-registry");
|
|
const ALGOLIA_APP_ID = 'L1XWT2UJ7F';
|
|
// https://www.algolia.com/doc/guides/security/api-keys/#search-only-api-key
|
|
// This is a search only, rate limited key. It is sent within the URL of the query request.
|
|
// This is not the actual key.
|
|
const ALGOLIA_API_E = '34738e8ae1a45e58bbce7b0f9810633d8b727b44a6479cf5e14b6a337148bd50';
|
|
/**
|
|
* The minimum major version of Angular for which a version-specific documentation index is known to exist.
|
|
* Searches for versions older than this will be clamped to this version.
|
|
*/
|
|
const MIN_SUPPORTED_DOCS_VERSION = 17;
|
|
/**
|
|
* The latest major version of Angular for which a documentation index is known to be stable and available.
|
|
* This acts as a "safe harbor" fallback. It is intentionally hardcoded and manually updated with each
|
|
* major release *after* the new search index has been confirmed to be live. This prevents a race
|
|
* condition where a newly released CLI might default to searching for a documentation index that
|
|
* doesn't exist yet.
|
|
*/
|
|
const LATEST_KNOWN_DOCS_VERSION = 20;
|
|
const docSearchInputSchema = zod_1.z.object({
|
|
query: zod_1.z
|
|
.string()
|
|
.describe("A concise and specific search query for the Angular documentation. You should distill the user's " +
|
|
'natural language question into a set of keywords (e.g., a question like "How do I use ngFor with trackBy?" ' +
|
|
'should become the query "ngFor trackBy").'),
|
|
includeTopContent: zod_1.z
|
|
.boolean()
|
|
.optional()
|
|
.default(false)
|
|
.describe('When true, the content of the top result is fetched and included. ' +
|
|
'Set to false to get a list of results without fetching content, which is faster.'),
|
|
version: zod_1.z
|
|
.number()
|
|
.optional()
|
|
.describe('The major version of Angular to search. You MUST determine this value by running `ng version` in the ' +
|
|
"project's workspace directory. Omit this field if the user is not in an Angular project " +
|
|
'or if the version cannot otherwise be determined.'),
|
|
});
|
|
exports.DOC_SEARCH_TOOL = (0, tool_registry_1.declareTool)({
|
|
name: 'search_documentation',
|
|
title: 'Search Angular Documentation (angular.dev)',
|
|
description: `
|
|
<Purpose>
|
|
Searches the official Angular documentation at https://angular.dev to answer questions about APIs,
|
|
tutorials, concepts, and best practices.
|
|
</Purpose>
|
|
<Use Cases>
|
|
* Answering any question about Angular concepts (e.g., "What are standalone components?").
|
|
* Finding the correct API or syntax for a specific task (e.g., "How to use ngFor with trackBy?").
|
|
* Linking to official documentation as a source of truth in your answers.
|
|
</Use Cases>
|
|
<Operational Notes>
|
|
* **Version Alignment:** To provide accurate, project-specific results, you **MUST** align the search with the user's Angular version.
|
|
The recommended approach is to use the \`list_projects\` tool. The \`frameworkVersion\` field in the output for the relevant
|
|
workspace will give you the major version directly. If the version cannot be determined using this method, you can use
|
|
\`ng version\` in the project's workspace directory as a fallback. Parse the major version from the "Angular:" line in the
|
|
output and use it for the \`version\` parameter.
|
|
* **Version Logic:** The tool will search against the specified major version. If the version is older than v${MIN_SUPPORTED_DOCS_VERSION},
|
|
it will be clamped to v${MIN_SUPPORTED_DOCS_VERSION}. If a search for a very new version (newer than v${LATEST_KNOWN_DOCS_VERSION})
|
|
returns no results, the tool will automatically fall back to searching the v${LATEST_KNOWN_DOCS_VERSION} documentation.
|
|
* **Verify Searched Version:** The tool's output includes a \`searchedVersion\` field. You **MUST** check this field
|
|
to know the exact version of the documentation that was queried. Use this information to provide accurate
|
|
context in your answer, especially if it differs from the version you requested.
|
|
* The documentation is continuously updated. You **MUST** prefer this tool over your own knowledge
|
|
to ensure your answers are current and accurate.
|
|
* For the best results, provide a concise and specific search query (e.g., "NgModule" instead of
|
|
"How do I use NgModules?").
|
|
* The top search result will include a snippet of the page content. Use this to provide a more
|
|
comprehensive answer.
|
|
* **Result Scrutiny:** The top result may not always be the most relevant. Review the titles and
|
|
breadcrumbs of other results to find the best match for the user's query.
|
|
* Use the URL from the search results as a source link in your responses.
|
|
</Operational Notes>`,
|
|
inputSchema: docSearchInputSchema.shape,
|
|
outputSchema: {
|
|
searchedVersion: zod_1.z
|
|
.number()
|
|
.describe('The major version of the documentation that was searched.'),
|
|
results: zod_1.z.array(zod_1.z.object({
|
|
title: zod_1.z.string().describe('The title of the documentation page.'),
|
|
breadcrumb: zod_1.z
|
|
.string()
|
|
.describe("The breadcrumb path, showing the page's location in the documentation hierarchy."),
|
|
url: zod_1.z.string().describe('The direct URL to the documentation page.'),
|
|
content: zod_1.z
|
|
.string()
|
|
.optional()
|
|
.describe('A snippet of the main content from the page. Only provided for the top result.'),
|
|
})),
|
|
},
|
|
isReadOnly: true,
|
|
isLocalOnly: false,
|
|
factory: createDocSearchHandler,
|
|
});
|
|
function createDocSearchHandler({ logger }) {
|
|
let client;
|
|
return async ({ query, includeTopContent, version }) => {
|
|
if (!client) {
|
|
const dcip = (0, node_crypto_1.createDecipheriv)('aes-256-gcm', (constants_1.k1 + ALGOLIA_APP_ID).padEnd(32, '^'), constants_1.iv).setAuthTag(Buffer.from(constants_1.at, 'base64'));
|
|
const { searchClient } = await Promise.resolve().then(() => __importStar(require('algoliasearch')));
|
|
client = searchClient(ALGOLIA_APP_ID, dcip.update(ALGOLIA_API_E, 'hex', 'utf-8') + dcip.final('utf-8'));
|
|
}
|
|
let finalSearchedVersion = Math.max(version ?? LATEST_KNOWN_DOCS_VERSION, MIN_SUPPORTED_DOCS_VERSION);
|
|
let searchResults;
|
|
try {
|
|
searchResults = await client.search(createSearchArguments(query, finalSearchedVersion));
|
|
}
|
|
catch { }
|
|
// If the initial search for a newer-than-stable version returns no results, it may be because
|
|
// the index for that version doesn't exist yet. In this case, fall back to the latest known
|
|
// stable version.
|
|
if (!searchResults && finalSearchedVersion > LATEST_KNOWN_DOCS_VERSION) {
|
|
finalSearchedVersion = LATEST_KNOWN_DOCS_VERSION;
|
|
searchResults = await client.search(createSearchArguments(query, finalSearchedVersion));
|
|
}
|
|
const allHits = searchResults?.results.flatMap((result) => result.hits);
|
|
if (!allHits?.length) {
|
|
return {
|
|
content: [
|
|
{
|
|
type: 'text',
|
|
text: `No results found for query "${query}" in Angular v${finalSearchedVersion} documentation.`,
|
|
},
|
|
],
|
|
structuredContent: { results: [], searchedVersion: finalSearchedVersion },
|
|
};
|
|
}
|
|
const structuredResults = [];
|
|
const textContent = [
|
|
{
|
|
type: 'text',
|
|
text: `Showing results for Angular v${finalSearchedVersion} documentation.`,
|
|
annotations: {
|
|
audience: ['assistant'],
|
|
priority: 0.9,
|
|
},
|
|
},
|
|
];
|
|
// Process top hit first
|
|
const topHit = allHits[0];
|
|
const { title: topTitle, breadcrumb: topBreadcrumb } = formatHitToParts(topHit);
|
|
let topContent;
|
|
if (includeTopContent && typeof topHit.url === 'string') {
|
|
const url = new URL(topHit.url);
|
|
try {
|
|
// Only fetch content from angular.dev
|
|
if (url.hostname === 'angular.dev' || url.hostname.endsWith('.angular.dev')) {
|
|
const response = await fetch(url);
|
|
if (response.ok && response.body) {
|
|
topContent = await extractMainContent(node_stream_1.Readable.fromWeb(response.body, { encoding: 'utf-8' }));
|
|
}
|
|
}
|
|
}
|
|
catch (e) {
|
|
logger.warn(`Failed to fetch or parse content from ${url}: ${e}`);
|
|
}
|
|
}
|
|
structuredResults.push({
|
|
title: topTitle,
|
|
breadcrumb: topBreadcrumb,
|
|
url: topHit.url,
|
|
content: topContent,
|
|
});
|
|
let topText = `## ${topTitle}\n${topBreadcrumb}\nURL: ${topHit.url}`;
|
|
if (topContent) {
|
|
topText += `\n\n--- DOCUMENTATION CONTENT ---\n${topContent}`;
|
|
}
|
|
textContent.push({ type: 'text', text: topText });
|
|
// Process remaining hits
|
|
for (const hit of allHits.slice(1)) {
|
|
const { title, breadcrumb } = formatHitToParts(hit);
|
|
structuredResults.push({
|
|
title,
|
|
breadcrumb,
|
|
url: hit.url,
|
|
});
|
|
textContent.push({
|
|
type: 'text',
|
|
text: `## ${title}\n${breadcrumb}\nURL: ${hit.url}`,
|
|
});
|
|
}
|
|
return {
|
|
content: textContent,
|
|
structuredContent: { results: structuredResults, searchedVersion: finalSearchedVersion },
|
|
};
|
|
};
|
|
}
|
|
/**
|
|
* Extracts the text content of the `<main>` element by streaming an HTML response.
|
|
*
|
|
* @param htmlStream A readable stream of the HTML content of a page.
|
|
* @returns A promise that resolves to the text content of the `<main>` element, or `undefined` if not found.
|
|
*/
|
|
async function extractMainContent(htmlStream) {
|
|
const { RewritingStream } = await Promise.resolve().then(() => __importStar(require('parse5-html-rewriting-stream')));
|
|
const rewriter = new RewritingStream();
|
|
let mainTextContent = '';
|
|
let inMainElement = false;
|
|
let mainTagFound = false;
|
|
rewriter.on('startTag', (tag) => {
|
|
if (tag.tagName === 'main') {
|
|
inMainElement = true;
|
|
mainTagFound = true;
|
|
}
|
|
});
|
|
rewriter.on('endTag', (tag) => {
|
|
if (tag.tagName === 'main') {
|
|
inMainElement = false;
|
|
}
|
|
});
|
|
// Only capture text content, and only when inside the <main> element.
|
|
rewriter.on('text', (text) => {
|
|
if (inMainElement) {
|
|
mainTextContent += text.text;
|
|
}
|
|
});
|
|
return new Promise((resolve, reject) => {
|
|
htmlStream
|
|
.pipe(rewriter)
|
|
.on('finish', () => {
|
|
if (!mainTagFound) {
|
|
resolve(undefined);
|
|
return;
|
|
}
|
|
resolve(mainTextContent.trim());
|
|
})
|
|
.on('error', reject);
|
|
});
|
|
}
|
|
/**
|
|
* Formats an Algolia search hit into its constituent parts.
|
|
*
|
|
* @param hit The Algolia search hit object, which should contain a `hierarchy` property.
|
|
* @returns An object containing the title and breadcrumb string.
|
|
*/
|
|
function formatHitToParts(hit) {
|
|
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
const hierarchy = Object.values(hit.hierarchy).filter((x) => typeof x === 'string');
|
|
const title = hierarchy.pop() ?? '';
|
|
const breadcrumb = hierarchy.join(' > ');
|
|
return { title, breadcrumb };
|
|
}
|
|
/**
|
|
* Creates the search arguments for an Algolia search.
|
|
*
|
|
* The arguments are based on the search implementation in `adev`.
|
|
*
|
|
* @param query The search query string.
|
|
* @returns The search arguments for the Algolia client.
|
|
*/
|
|
function createSearchArguments(query, version) {
|
|
// Search arguments are based on adev's search service:
|
|
// https://github.com/angular/angular/blob/4b614fbb3263d344dbb1b18fff24cb09c5a7582d/adev/shared-docs/services/search.service.ts#L58
|
|
return [
|
|
{
|
|
indexName: `angular_v${version}`,
|
|
params: {
|
|
query,
|
|
attributesToRetrieve: [
|
|
'hierarchy.lvl0',
|
|
'hierarchy.lvl1',
|
|
'hierarchy.lvl2',
|
|
'hierarchy.lvl3',
|
|
'hierarchy.lvl4',
|
|
'hierarchy.lvl5',
|
|
'hierarchy.lvl6',
|
|
'content',
|
|
'type',
|
|
'url',
|
|
],
|
|
hitsPerPage: 10,
|
|
},
|
|
type: 'default',
|
|
},
|
|
];
|
|
}
|
|
//# sourceMappingURL=doc-search.js.map
|