repositories / pi-ext
pi-ext
bugabingas pi extensions
owned by admin
extensions/devdocs/src/symbols.ts
Rawimport { 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,
);
}