Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/devdocs/src/symbols.ts

Raw
import { MAX_DOCUMENT_BYTES } from "./normalize.ts";
import type { Section } from "./types.ts";

const MAX_ENTRIES = 10_000;
const MAX_RESULTS = 20;
const JavadocBody = "Javadoc symbol index entry.";
const DoxygenBody = "Doxygen symbol index entry.";

type Entry = { heading: string; locator: string; body: string; index: number };
type JsonEntry = Record<string, unknown>;

function withinLimit(input: string): boolean {
	return Buffer.byteLength(input) <= MAX_DOCUMENT_BYTES;
}

function decodeXml(value: string): string {
	return value.replace(
		/&(amp|lt|gt|quot|apos|#x[\da-f]+|#\d+);/gi,
		(whole, name: string) => {
			if (name === "amp") return "&";
			if (name === "lt") return "<";
			if (name === "gt") return ">";
			if (name === "quot") return '"';
			if (name === "apos") return "'";
			const point =
				name[1]?.toLowerCase() === "x"
					? Number.parseInt(name.slice(2), 16)
					: Number(name.slice(1));
			return Number.isInteger(point) &&
				point > 0 &&
				point <= 0x10ffff &&
				!(point >= 0xd800 && point <= 0xdfff)
				? String.fromCodePoint(point)
				: whole;
		},
	);
}

function text(element: string, name: string): string | undefined {
	const match = new RegExp(`<${name}\\b[^>]*>([^<]*)</${name}\\s*>`, "i").exec(
		element,
	);
	const value = match?.[1];
	return value === undefined ? undefined : decodeXml(value).trim();
}

function attribute(tag: string, name: string): string | undefined {
	const match = new RegExp(
		`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`,
		"i",
	).exec(tag);
	const value = match?.[1] ?? match?.[2];
	return value === undefined ? undefined : decodeXml(value);
}

function safePart(value: string): boolean {
	if (
		!value ||
		value.length > 1024 ||
		!/^(?:[A-Za-z0-9._$()~,+;=@:\-[\]]|%[\da-f]{2})+$/.test(value)
	)
		return false;
	try {
		const decoded = decodeURIComponent(value);
		return (
			decoded !== "." &&
			decoded !== ".." &&
			!/[\\/#?\x00-\x1f\x7f]/.test(decoded)
		);
	} catch {
		return false;
	}
}

function safeLocator(
	path: string | undefined,
	anchor?: string | undefined,
): string | undefined {
	if (
		!path ||
		path.length > 4096 ||
		path.startsWith("/") ||
		/^[a-z][a-z\d+.-]*:/i.test(path) ||
		path.includes("\\") ||
		path.includes("?")
	)
		return undefined;
	const pieces = path.split("#");
	if (pieces.length > 2 || !pieces[0] || !pieces[0].split("/").every(safePart))
		return undefined;
	const fragment = anchor ?? pieces[1];
	if (fragment !== undefined && !safePart(fragment)) return undefined;
	return `${pieces[0]}${fragment ? `#${fragment}` : ""}`;
}

function assignedArray(input: string): unknown[] | undefined {
	for (
		let equals = input.indexOf("=");
		equals !== -1;
		equals = input.indexOf("=", equals + 1)
	) {
		let start = equals + 1;
		while (/\s/.test(input[start] ?? "")) start++;
		if (input[start] !== "[") continue;
		let depth = 0;
		let quoted = false;
		let escaped = false;
		for (let end = start; end < input.length; end++) {
			const char = input[end] ?? "";
			if (quoted) {
				if (escaped) escaped = false;
				else if (char === "\\") escaped = true;
				else if (char === '"') quoted = false;
				continue;
			}
			if (char === '"') quoted = true;
			else if (char === "[") depth++;
			else if (char === "]" && --depth === 0) {
				try {
					const parsed: unknown = JSON.parse(input.slice(start, end + 1));
					return Array.isArray(parsed) ? parsed : undefined;
				} catch {
					return undefined;
				}
			}
		}
		return undefined;
	}
	return undefined;
}

function javadocEntries(input: string): Entry[] {
	const array = assignedArray(input);
	if (!array || array.length > MAX_ENTRIES) return [];
	const result: Entry[] = [];
	const kind =
		/\b(module|package|type|member)SearchIndex\s*=/.exec(input)?.[1] ?? "type";
	for (const value of array) {
		if (!value || typeof value !== "object" || Array.isArray(value)) continue;
		const entry = value as JsonEntry;
		const p = typeof entry["p"] === "string" ? entry["p"] : undefined;
		const c = typeof entry["c"] === "string" ? entry["c"] : undefined;
		const l = typeof entry["l"] === "string" ? entry["l"] : undefined;
		const m = typeof entry["m"] === "string" ? entry["m"] : undefined;
		if (!l) continue;
		const provided = typeof entry["u"] === "string" ? entry["u"] : undefined;
		const prefix =
			(m ? m + "/" : "") +
			(p && !p.startsWith("<") ? p.replaceAll(".", "/") + "/" : "");
		const locator = c
			? provided?.includes(".html")
				? safeLocator(provided)
				: safeLocator(prefix + c + ".html", encodeURIComponent(provided ?? l))
			: provided
				? safeLocator(provided)
				: kind === "package"
					? safeLocator(
							(m ? m + "/" : "") +
								l.replaceAll(".", "/") +
								"/package-summary.html",
						)
					: kind === "module"
						? safeLocator(l + "/module-summary.html")
						: safeLocator(prefix + l + ".html");
		if (!locator) continue;
		const symbol = c
			? [p, c, l].filter(Boolean).join(".")
			: p
				? `${p}.${l}`
				: l;
		const heading = m ? `${m}/${symbol}` : symbol;
		result.push({ heading, locator, body: JavadocBody, index: result.length });
	}
	return result;
}

function refidLocator(
	refid: string | undefined,
	memberRefid?: string | undefined,
): string | undefined {
	if (!refid || !safePart(refid)) return undefined;
	let anchor: string | undefined;
	if (memberRefid?.startsWith(`${refid}_1`))
		anchor = memberRefid.slice(refid.length + 2);
	return safeLocator(`${refid}.html`, anchor);
}

function doxygenEntries(input: string): Entry[] {
	if (/<!\s*(?:doctype|entity)\b/i.test(input)) return [];
	const result: Entry[] = [];
	let scanned = 0;
	for (const compound of input.matchAll(
		/<compound\b([^>]*)>([\s\S]*?)<\/compound\s*>/gi,
	)) {
		if (scanned++ >= MAX_ENTRIES || result.length >= MAX_ENTRIES) break;
		const attributes = compound[1] ?? "";
		const content = compound[2] ?? "";
		const name = text(content, "name");
		const refid = attribute(attributes, "refid");
		const compoundLocator =
			safeLocator(text(content, "filename")) ?? refidLocator(refid);
		if (name && compoundLocator)
			result.push({
				heading: name,
				locator: compoundLocator,
				body: DoxygenBody,
				index: result.length,
			});
		for (const member of content.matchAll(
			/<member\b([^>]*)>([\s\S]*?)<\/member\s*>/gi,
		)) {
			if (scanned++ >= MAX_ENTRIES || result.length >= MAX_ENTRIES) break;
			const memberAttributes = member[1] ?? "";
			const memberContent = member[2] ?? "";
			const memberName = text(memberContent, "name");
			if (!name || !memberName) continue;
			const signature = text(memberContent, "arglist") ?? "";
			const locator =
				safeLocator(
					text(memberContent, "anchorfile"),
					text(memberContent, "anchor"),
				) ?? refidLocator(refid, attribute(memberAttributes, "refid"));
			if (!locator) continue;
			result.push({
				heading: `${name}::${memberName}${signature}`,
				locator,
				body: DoxygenBody,
				index: result.length,
			});
		}
	}
	return result;
}

function normalize(value: string): string {
	return value.trim().replace(/\s+/g, " ").toLowerCase();
}

function select(entries: Entry[], query: string): Section[] {
	const wanted = normalize(query);
	return entries
		.map((entry) => {
			const heading = normalize(entry.heading);
			const score = !wanted
				? 1
				: heading === wanted
					? 3
					: heading.includes(wanted)
						? 2
						: wanted.split(" ").every((term) => heading.includes(term))
							? 1
							: 0;
			return { ...entry, score };
		})
		.filter((entry) => entry.score > 0)
		.sort((a, b) => b.score - a.score || a.index - b.index)
		.slice(0, MAX_RESULTS)
		.map(({ heading, locator, body }) => ({ heading, locator, body }));
}

/** Extracts bounded, inert symbol-discovery metadata from generated documentation indexes. */
export function symbolIndex(
	input: string,
	format: "javadoc" | "doxygen",
	query: string,
): Section[] {
	if (!withinLimit(input)) return [];
	return select(
		format === "javadoc" ? javadocEntries(input) : doxygenEntries(input),
		query,
	);
}