Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/devdocs/src/catalog.ts

Raw
export type FormatId =
	| "html"
	| "markdown"
	| "text"
	| "mdx"
	| "rst"
	| "man"
	| "info"
	| "help"
	| "javadoc"
	| "sphinx"
	| "doxygen"
	| "docset"
	| "json"
	| "pdf";

/** Format support is independent of publisher identity and source availability. */
export const formatReaders: ReadonlyArray<{
	id: FormatId;
	available: boolean;
	capability: string;
}> = [
	{
		id: "html",
		available: true,
		capability:
			"Static HTML headings, anchors, prose and code; no scripts, DOM execution or site search.",
	},
	{
		id: "markdown",
		available: true,
		capability: "Markdown sections and fenced code; no macro execution.",
	},
	{
		id: "text",
		available: true,
		capability: "Plain text document; no structural symbol index.",
	},
	{
		id: "mdx",
		available: true,
		capability:
			"Static Markdown/MDX; imports and JSX wrappers omitted, macros retained as inert unsupported text.",
	},
	{
		id: "rst",
		available: true,
		capability:
			"Basic reStructuredText headings and literal blocks; directives retained, never executed.",
	},
	{
		id: "man",
		available: true,
		capability:
			"Installed man rendering or static roff headings/prose; macros are never executed by the static reader.",
	},
	{
		id: "info",
		available: true,
		capability: "Installed Info rendering or static Info nodes.",
	},
	{
		id: "help",
		available: true,
		capability: "Installed command help through the local adapter.",
	},
	{
		id: "javadoc",
		available: true,
		capability:
			"Rendered HTML, bounded ZIP/JAR pages, and standard generated search indexes; no Java or index-script execution.",
	},
	{
		id: "sphinx",
		available: true,
		capability:
			"Rendered HTML or bounded objects.inv v2 discovery metadata only; inventory has no documentation bodies.",
	},
	{
		id: "doxygen",
		available: true,
		capability:
			"Rendered HTML plus bounded Doxygen index/tag symbol discovery linked to documentation bodies.",
	},
	{
		id: "docset",
		available: true,
		capability:
			"Installed Dash/Zeal bundle HTML via its read-only SQLite symbol index; remote tgz expansion is unavailable.",
	},
	{
		id: "json",
		available: true,
		capability:
			"Structured JSON entries with exact keys, glyphs and compatibility/provenance fields; no schema inference.",
	},
	{
		id: "pdf",
		available: true,
		capability:
			"PDF text via an already installed pdftotext, fixed arguments and deadline/output limits; tool availability is not guaranteed.",
	},
];

export type CatalogSource = {
	id: string;
	aliases: readonly string[];
	domain: string;
	home: string;
	index: string | null;
	format: FormatId;
	authority: "publisher" | "standards" | "community" | "host" | "installed";
	role: "reference" | "supplemental" | "registry" | "host";
	adapter: "upstream" | "local" | "devdocs" | "context7" | "unavailable";
	versionSupport: string;
	description: string;
	/** Only operator-provided, verified release identity may populate these. */
	version?: string;
	evidence?: string;
};

type Row = [
	id: string,
	aliases: string,
	domain: string,
	home: string,
	description: string,
];
const rows: Row[] = [
	[
		"mdn",
		"web|javascript|css|html",
		"web",
		"https://developer.mozilla.org/en-US/docs/Web/",
		"Web reference prose; browser compatibility is separate structured data.",
	],
	[
		"mdn-content",
		"",
		"web",
		"https://github.com/mdn/content",
		"Source Markdown contains macros; repository revisions and macro normalization need dedicated support.",
	],
	[
		"browser-compat-data",
		"bcd",
		"web",
		"https://raw.githubusercontent.com/mdn/browser-compat-data/main/data.json",
		"Structured browser and release compatibility, not reference prose.",
	],
	[
		"whatwg",
		"html standard",
		"standards",
		"https://html.spec.whatwg.org/",
		"Living HTML standard; retain section anchors and revision identity.",
	],
	[
		"w3c",
		"web standards",
		"standards",
		"https://www.w3.org/TR/",
		"Normative status and specification revision differ from implementation support.",
	],
	[
		"rfc",
		"rfc editor",
		"protocols",
		"https://www.rfc-editor.org/",
		"RFC status, revisions, obsoletes and supersedes relationships require explicit evidence.",
	],
	[
		"wcag",
		"accessibility|wai",
		"accessibility",
		"https://www.w3.org/WAI/WCAG22/quickref/",
		"WCAG requirements differ from WAI supporting techniques and examples.",
	],
	[
		"webdriver-bidi",
		"bidi",
		"browser automation",
		"https://w3c.github.io/webdriver-bidi/",
		"Protocol revision is not browser implementation support.",
	],
	[
		"java",
		"jdk|java se|javadoc",
		"java",
		"https://docs.oracle.com/en/java/javase/",
		"Java SE API: JDK release, module, package, class and exact member identity.",
	],
	[
		"java-specs",
		"jls|jvms",
		"java",
		"https://docs.oracle.com/javase/specs/",
		"Normative language and VM specifications, not tutorials.",
	],
	[
		"dev-java",
		"dev.java",
		"java",
		"https://dev.java/learn/",
		"Publisher-authored Java tutorials, not normative specifications.",
	],
	[
		"maven-central",
		"maven",
		"jvm",
		"https://central.sonatype.com/",
		"Group/artifact/version discovery; missing -javadoc.jar artifacts remain misses.",
	],
	[
		"javadoc-io",
		"javadoc.io",
		"jvm",
		"https://javadoc.io/",
		"Repository-hosted Javadoc; publisher authority depends on artifact identity.",
	],
	[
		"node",
		"nodejs|node.js",
		"javascript",
		"https://nodejs.org/api/",
		"Node API reference; runtime release must be verified separately.",
	],
	[
		"node-learn",
		"node diagnostics",
		"javascript",
		"https://nodejs.org/en/learn",
		"Learning and operational diagnostics, separate from API reference.",
	],
	[
		"typescript",
		"ts",
		"typescript",
		"https://www.typescriptlang.org/docs/",
		"Compiler-version handbook and language reference.",
	],
	[
		"libuv",
		"",
		"runtime internals",
		"https://docs.libuv.org/",
		"Implementation-specific event loop and API behavior.",
	],
	[
		"v8",
		"",
		"runtime internals",
		"https://v8.dev/docs",
		"Implementation-specific engine behavior and performance.",
	],
	[
		"v8-source",
		"",
		"runtime internals",
		"https://github.com/v8/v8/tree/main/docs",
		"Source documentation; repository revision must be explicit.",
	],
	[
		"rust",
		"rustdoc",
		"rust",
		"https://www.rust-lang.org/learn",
		"Rust language documentation; installed rustdoc is a separate local source.",
	],
	[
		"docs-rs",
		"docs.rs",
		"rust",
		"https://docs.rs/",
		"Crate/version/target identity; rustdoc JSON compatibility and historical availability are not assumed.",
	],
	[
		"go",
		"golang",
		"go",
		"https://go.dev/doc/",
		"Language and toolchain documentation; local go doc is a separate source.",
	],
	[
		"pkg-go-dev",
		"pkg.go.dev",
		"go",
		"https://pkg.go.dev/",
		"Module/package/version and OS/architecture build context require verification.",
	],
	[
		"python",
		"python3",
		"python",
		"https://docs.python.org/",
		"Python language/library releases; rendered Sphinx pages are readable.",
	],
	[
		"readthedocs",
		"read the docs",
		"python",
		"https://about.readthedocs.com/",
		"Hosting platform, not publisher authority; configure the actual project root.",
	],
	[
		"cppreference",
		"cpp|c++|c",
		"c and c++",
		"https://en.cppreference.com/",
		"Community reference, not normative ISO standard; distinguish implementation and library versions.",
	],
	[
		"gcc",
		"compiler manuals",
		"c and c++",
		"https://gcc.gnu.org/onlinedocs/",
		"Compiler manuals are implementation- and release-specific.",
	],
	[
		"glibc",
		"libc",
		"c and c++",
		"https://www.gnu.org/software/libc/manual/",
		"C library manual; installed implementation version is separate evidence.",
	],
	[
		"doxygen",
		"",
		"c and c++",
		"https://www.doxygen.nl/manual/",
		"Configure upstream project pages; Doxygen is a format, not an authority.",
	],
	[
		"sqlite",
		"sqlite3",
		"databases",
		"https://sqlite.org/docs.html",
		"SQLite dialect, library versions, compile options and extensions.",
	],
	[
		"postgresql",
		"postgres",
		"databases",
		"https://www.postgresql.org/docs/",
		"Server-version SQL dialect, extensions and platform requirements.",
	],
	[
		"man7",
		"linux man|linux",
		"linux",
		"https://man7.org/linux/man-pages/",
		"Linux userspace manuals preserve manual section; kernel and distro identity differ.",
	],
	[
		"gnu",
		"gnu manuals",
		"linux userspace",
		"https://www.gnu.org/manual/manual.html",
		"GNU package manuals; package and manual versions need evidence.",
	],
	[
		"kernel",
		"linux kernel",
		"linux kernel",
		"https://docs.kernel.org/",
		"Kernel documentation, not userspace or distribution administration.",
	],
	[
		"systemd",
		"",
		"linux services",
		"https://www.freedesktop.org/software/systemd/man/latest/",
		"System/user scope and implementation versions; latest is not installed-version evidence.",
	],
	[
		"freedesktop",
		"desktop specifications",
		"desktop standards",
		"https://specifications.freedesktop.org/",
		"Desktop specifications differ from installed implementations.",
	],
	[
		"archwiki",
		"arch wiki",
		"distribution administration",
		"https://wiki.archlinux.org/",
		"Community Arch-specific administration; not a cross-distribution assumption.",
	],
	[
		"arch-man",
		"arch manuals",
		"distribution administration",
		"https://man.archlinux.org/",
		"Arch package manuals and distribution-specific release context.",
	],
	[
		"arch-news",
		"arch news",
		"distribution administration",
		"https://archlinux.org/news/",
		"Time-sensitive distribution advisories must retain publication dates.",
	],
	[
		"microsoft-learn",
		"microsoft learn|windows|powershell|dotnet",
		"windows",
		"https://learn.microsoft.com/",
		"Microsoft product documentation; OS, .NET and PowerShell versions differ.",
	],
	[
		"win32",
		"windows win32",
		"windows",
		"https://learn.microsoft.com/en-us/windows/win32/",
		"Win32 OS support, API variants, headers and libraries.",
	],
	[
		"win32-api",
		"windows sdk",
		"windows",
		"https://learn.microsoft.com/en-us/windows/win32/api/",
		"SDK API reference; preserve header, library and minimum supported OS.",
	],
	[
		"windows-paths",
		"windows paths",
		"paths",
		"https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file",
		"Filesystem names versus Win32 namespaces and argument conversion.",
	],
	[
		"msys2",
		"msys2 paths",
		"paths",
		"https://www.msys2.org/docs/filesystem-paths/",
		"Shell/native path and argument conversion, not Windows filesystem rules.",
	],
	[
		"bash",
		"",
		"shells",
		"https://www.gnu.org/software/bash/manual/",
		"Bash syntax and native argument semantics are shell-specific.",
	],
	[
		"git",
		"",
		"version control",
		"https://git-scm.com/docs",
		"Command and recovery semantics depend on installed Git version.",
	],
	[
		"jujutsu",
		"jj",
		"version control",
		"https://docs.jj-vcs.dev/latest/",
		"Revision syntax, bookmarks, working-copy and recovery semantics.",
	],
	[
		"github-cli",
		"gh",
		"github",
		"https://cli.github.com/manual/",
		"CLI command/version and permissions; retrieval never authorizes mutations.",
	],
	[
		"github-rest",
		"github api",
		"github",
		"https://docs.github.com/en/rest",
		"API version, scopes and pagination differ from CLI versions.",
	],
	[
		"github",
		"",
		"github",
		"https://docs.github.com/",
		"Product documentation, not authorization for account changes.",
	],
	[
		"nushell",
		"nu",
		"shells",
		"https://www.nushell.sh/book/",
		"Typed data and installed syntax; command reference and migration intervals differ.",
	],
	[
		"nushell-commands",
		"nu commands",
		"shells",
		"https://www.nushell.sh/commands/",
		"Nushell command reference.",
	],
	[
		"nushell-releases",
		"nu releases",
		"shells",
		"https://www.nushell.sh/blog/",
		"Dated release notes and syntax migrations.",
	],
	[
		"mise",
		"",
		"tooling",
		"https://mise.jdx.dev/",
		"Configuration discovery, trust, CLI, backends and schema.",
	],
	[
		"niri",
		"",
		"desktop",
		"https://niri-wm.github.io/niri/",
		"Compositor config, IPC and installed version support.",
	],
	[
		"wezterm",
		"",
		"terminal",
		"https://wezterm.org/config/files.html",
		"Lua API, CLI and renderer support are version-specific.",
	],
	[
		"ast-grep",
		"sg",
		"structural search",
		"https://ast-grep.github.io/",
		"Structural syntax matching, not semantic references.",
	],
	[
		"d2",
		"",
		"diagrams",
		"https://d2lang.com/",
		"Renderer version, syntax, layout and configuration.",
	],
	[
		"d2-source",
		"",
		"diagrams",
		"https://github.com/terrastruct/d2-docs",
		"Source fallback for rendered pages; repository revision is explicit.",
	],
	[
		"mermaid",
		"",
		"diagrams",
		"https://mermaid.js.org/",
		"Renderer version, syntax, layouts and configuration.",
	],
	[
		"mdbook",
		"",
		"documentation tooling",
		"https://rust-lang.github.io/mdBook/",
		"Version-specific book tooling and configuration.",
	],
	[
		"pastel",
		"",
		"colors",
		"https://github.com/sharkdp/pastel",
		"Source README and installed help; no guessed color conversion.",
	],
	[
		"nerd-fonts",
		"nerdfonts|glyphnames",
		"icons",
		"https://raw.githubusercontent.com/ryanoasis/nerd-fonts/master/glyphnames.json",
		"Exact glyph identity, code points and registry revision require a structured JSON reader.",
	],
	[
		"cloudflare",
		"",
		"hosted platforms",
		"https://developers.cloudflare.com/",
		"Product-scoped references, API versions and changing service behavior.",
	],
	[
		"google-workspace",
		"workspace",
		"hosted platforms",
		"https://developers.google.com/workspace",
		"API methods, schemas, scopes, pagination and versions; no account access needed.",
	],
	[
		"google-discovery",
		"google discovery",
		"hosted platforms",
		"https://discovery.googleapis.com/discovery/v1/apis",
		"Structured API discovery metadata; not account data.",
	],
	[
		"microsoft-learn-mcp",
		"learn mcp",
		"provider retrieval",
		"https://learn.microsoft.com/en-us/training/support/mcp",
		"Anonymous search/fetch MCP needs runtime schema discovery; generated-answer tools are excluded.",
	],
	[
		"devdocs",
		"devdocs.io",
		"cross-domain",
		"https://devdocs.io/",
		"Curated docsets with catalog, indexes, release metadata and offline bundles.",
	],
	[
		"dash-zeal",
		"dash|zeal",
		"cross-domain",
		"https://kapeli.com/docsets",
		"Optional feeds/bundles subject to access, attribution and redistribution restrictions.",
	],
	[
		"llms-txt",
		"llms.txt",
		"cross-domain",
		"https://llmstxt.org/",
		"Machine-index convention; register each publisher's scoped index separately.",
	],
	[
		"tldr",
		"tldr-pages",
		"command examples",
		"https://github.com/tldr-pages/tldr",
		"Supplementary platform/language examples, not complete release-compatible reference coverage.",
	],
	[
		"context7",
		"",
		"cross-domain",
		"https://context7.com/",
		"Last-ranked query-scoped fallback; anonymous/keyed mode and version verification are separate.",
	],
];

const community = new Set([
	"mdn",
	"mdn-content",
	"browser-compat-data",
	"cppreference",
	"archwiki",
	"tldr",
	"nerd-fonts",
]);
const hosts = new Set([
	"maven-central",
	"javadoc-io",
	"docs-rs",
	"pkg-go-dev",
	"readthedocs",
	"dash-zeal",
]);
const registries = new Set([
	"browser-compat-data",
	"nerd-fonts",
	"google-discovery",
]);
const indexes: Record<string, string> = {
	mise: "https://mise.jdx.dev/llms.txt",
	"ast-grep": "https://ast-grep.github.io/llms.txt",
	cloudflare: "https://developers.cloudflare.com/llms.txt",
};

export const sourceCatalog: readonly CatalogSource[] = rows.map(
	([id, aliases, domain, home, description]) => ({
		id,
		aliases: aliases ? aliases.split("|") : [],
		domain,
		home,
		index: indexes[id] ?? null,
		format: registries.has(id)
			? "json"
			: id === "dash-zeal"
				? "docset"
				: "html",
		authority: hosts.has(id)
			? "host"
			: community.has(id)
				? "community"
				: [
							"whatwg",
							"w3c",
							"wcag",
							"webdriver-bidi",
							"rfc",
							"freedesktop",
						].includes(id)
					? "standards"
					: "publisher",
		role:
			id === "tldr"
				? "supplemental"
				: registries.has(id)
					? "registry"
					: hosts.has(id)
						? "host"
						: "reference",
		adapter:
			id === "devdocs"
				? "devdocs"
				: id === "context7"
					? "context7"
					: ["dash-zeal", "microsoft-learn-mcp"].includes(id)
						? "unavailable"
						: "upstream",
		versionSupport:
			"Unknown by default; explicit releases require independently verified source identity. URL paths or HTTP success alone are not evidence.",
		description,
	}),
);

/** Local discovery is deliberately separate from generic HTTP retrieval. */
export const localSourceCatalog: readonly CatalogSource[] = [
	[
		"installed-man",
		"man",
		"Installed manual sections and owning package versions.",
	],
	["installed-info", "info", "Installed GNU Info nodes and package versions."],
	[
		"installed-help",
		"help",
		"Built-in/subcommand help and PowerShell help through applicable platform conventions.",
	],
	[
		"installed-package-docs",
		"markdown",
		"Installed READMEs, manuals, examples and package documentation trees.",
	],
	[
		"installed-javadoc",
		"javadoc",
		"Existing Javadoc archives and generated JVM API docs; never install or build.",
	],
	[
		"installed-docsets",
		"docset",
		"Existing Dash/Zeal HTML and symbol indexes; no browser application required.",
	],
	[
		"installed-sdk-docs",
		"html",
		"Application/SDK documentation including Pi via installation metadata or configured roots.",
	],
].map(([id, format, description]) => ({
	id: id ?? "",
	aliases: [],
	domain: "installed documentation",
	home: "",
	index: null,
	format: format as FormatId,
	authority: "installed",
	role: "reference",
	adapter: "local",
	versionSupport:
		"Requires installation/package metadata; not inferred from host OS.",
	description: description ?? "",
}));

export function sourceCapabilities(source: CatalogSource): {
	id: string;
	available: boolean;
	coverage: "supplemental" | "document";
	version: string | null;
	capability: string | undefined;
} {
	const reader = formatReaders.find((item) => item.id === source.format);
	return {
		id: source.id,
		available: source.adapter === "upstream" && reader?.available === true,
		coverage: source.role === "supplemental" ? "supplemental" : "document",
		version: source.version && source.evidence ? source.version : null,
		capability:
			source.adapter === "upstream"
				? reader?.capability
				: `Requires ${source.adapter} adapter; availability is determined by parent configuration.`,
	};
}