Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

scripts/readme/config.test.ts

Raw
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, describe, expect, it } from "vitest";
import { extensionDirs, extractSurface, renderSurface } from "./config.ts";

const roots: string[] = [];

afterEach(() => {
	for (const root of roots.splice(0))
		rmSync(root, { recursive: true, force: true });
});

function extension(files: Record<string, string>): string {
	const root = mkdtempSync(join(tmpdir(), "pi-ext-readme-config-"));
	roots.push(root);
	for (const [path, content] of Object.entries(files)) {
		const target = join(root, path);
		mkdirSync(join(target, ".."), { recursive: true });
		writeFileSync(target, content, "utf8");
	}
	return root;
}

describe("README configuration extraction", () => {
	it("resolves declarations, identifiers, factories, and nested defaults", () => {
		const dir = extension({
			"index.ts": `
const DESCRIPTION = "Use "+"the tool";
const tool = { name: "fixture_tool", description: DESCRIPTION };
const unrelated = { key: "not-a-setting", default: true };
function modelSetting(key: string) { return { key, parse: () => undefined, default: undefined }; }
const MODEL = modelSetting("fixture.model");
const OPTIONS = { key: "fixture.options", parse: () => undefined, default: { nested: [1, true] }, env: "FIXTURE_OPTIONS", flag: { name: "fixture-options" } };
export function load(pi: any, ctx: any) {
  pi.registerTool(tool);
  pi.registerCommand("fixture", { description: DESCRIPTION });
  pi.registerFlag("verbose", { type: "boolean", description: DESCRIPTION });
  resolveSetting(pi, ctx, MODEL);
  resolveSetting(pi, ctx, OPTIONS);
}
`,
		});
		const surface = extractSurface(dir);
		expect(surface.diagnostics).toEqual([]);
		expect(surface.tools).toEqual([
			{ name: "fixture_tool", description: "Use the tool" },
		]);
		expect(surface.commands).toEqual([
			{ name: "/fixture", description: "Use the tool" },
		]);
		expect(surface.flags).toEqual([
			{ name: "--verbose", type: "boolean", description: "Use the tool" },
		]);
		expect(surface.settings).toEqual([
			{ key: "fixture.model", default: "`undefined`" },
			{
				key: "fixture.options",
				env: "FIXTURE_OPTIONS",
				flag: "--fixture-options",
				default: "`{ nested: [1, true] }`",
			},
		]);
	});

	it("extracts declarative choices and integer ranges without executing imports", () => {
		const dir = extension({
			"engines.ts": `const FAST = "fast"; export const ENGINES = [FAST, "quality"] as const; throw new Error("must not execute");`,
			"index.ts": `
import { ENGINES as OPTIONS } from "./engines.js";
const ENGINE: SettingDeclaration<string> = defineChoiceSetting({ key: "demo.engine", label: "Engine", description: "Choose speed or quality.", choices: OPTIONS, default: "fast" });
const COUNT = defineIntegerSetting({ key: "demo.count", label: "Count", range: { min: -2, max: 8, step: 2 }, default: 2 });
const AUTOMATIC = defineIntegerSetting({ key: "demo.threads", range: { min: 1, max: 8 }, default: undefined });
const COMPUTED = defineChoiceSetting({ key: "demo.computed", choices: OPTIONS, default: platformProfile().engine });
`,
		});
		const surface = extractSurface(dir);
		expect(surface.diagnostics).toEqual([]);
		expect(surface.settings).toEqual(
			expect.arrayContaining([
				expect.objectContaining({
					key: "demo.engine",
					label: "Engine",
					constraints: '`"fast"`, `"quality"`',
					default: '`"fast"`',
				}),
				expect.objectContaining({
					key: "demo.count",
					constraints: "Integer -2–8, step 2",
					default: "`2`",
				}),
				expect.objectContaining({
					key: "demo.computed",
					computedDefault: true,
				}),
			]),
		);
		const markdown = renderSurface(surface);
		expect(markdown).toContain(
			"| Setting | Default | Valid values | Purpose |",
		);
		expect(markdown).toContain(
			'| `demo.engine` | `"fast"` | `"fast"`, `"quality"` | Engine: Choose speed or quality. |',
		);
		expect(markdown).toContain("| `demo.threads` | Unset | Integer 1–8 |");
		expect(markdown).toContain("| `demo.computed` | Computed |");
		expect(markdown).not.toContain("platformProfile()");
	});

	it("resolves imported choice expressions in their defining module", () => {
		const dir = extension({
			"engines.ts":
				'const PREFIX = "actual"; const FAST = PREFIX + "-fast"; export const OPTIONS = [PREFIX + "-slow", FAST, `${PREFIX}-quality`];',
			"index.ts":
				'import { OPTIONS } from "./engines.ts"; const PREFIX = "wrong"; const SETTING = defineChoiceSetting({key: "demo.engine", default: "actual-fast", choices: OPTIONS});',
		});
		const surface = extractSurface(dir);
		expect(surface.diagnostics).toEqual([]);
		expect(surface.settings[0]?.constraints).toBe(
			'`"actual-slow"`, `"actual-fast"`, `"actual-quality"`',
		);
	});

	it("extracts imported integer bounds, including owned generated helper constants", () => {
		const dir = extension({
			"src/pi-ext-settings.ts":
				'const BASE = 7; export const MAX_TIMER_MS = BASE * 1000; throw new Error("must not execute");',
			"index.ts": `
import { MAX_TIMER_MS as LIMIT } from "./src/pi-ext-settings.ts";
const BASE = 99;
const ALIAS = LIMIT;
const EXPANDED = ALIAS + 2;
const TIMER = defineIntegerSetting({key: "demo.timer", default: 5 * 1000, range: {min: 0, max: LIMIT}});
const ALIASED = defineIntegerSetting({key: "demo.alias", default: 5, range: {min: 0, max: EXPANDED}});
const SIZE = defineIntegerSetting({key: "demo.size", default: 1, range: {min: 1, max: Number.MAX_SAFE_INTEGER}});
`,
		});
		const surface = extractSurface(dir);
		expect(surface.diagnostics).toEqual([]);
		expect(surface.settings).toHaveLength(3);
		expect(
			surface.settings.find((row) => row.key === "demo.timer")?.default,
		).toBe("`5000`");
		expect(
			surface.settings.find((row) => row.key === "demo.alias")?.constraints,
		).toBe("Integer 0–7002");
		expect(
			surface.settings.find((row) => row.key === "demo.timer")?.constraints,
		).toBe("Integer 0–7000");
		expect(
			surface.settings.find((row) => row.key === "demo.size")?.constraints,
		).toBe("Integer 1–9007199254740991");
	});

	it("does not interpret a shadowed Number as the global range constant", () => {
		const dir = extension({
			"index.ts":
				'const Number = {MAX_SAFE_INTEGER: 7}; const SETTING = defineIntegerSetting({key: "demo.size", default: 1, range: {min: 1, max: Number.MAX_SAFE_INTEGER}});',
		});
		expect(extractSurface(dir).diagnostics).toEqual([
			"demo.size: range must have static integer bounds and a positive integer step",
		]);
	});

	it.each([
		'function make(Number) { return defineIntegerSetting({key: "demo.size", default: 1, range: {min: 1, max: Number.MAX_SAFE_INTEGER}}); }',
		'const make = (Number = {}) => defineIntegerSetting({key: "demo.size", default: 1, range: {min: 1, max: Number.MAX_SAFE_INTEGER}});',
		'import * as Number from "external"; const SETTING = defineIntegerSetting({key: "demo.size", default: 1, range: {min: 1, max: Number.MAX_SAFE_INTEGER}});',
		'const A = B; const B = A; const SETTING = defineIntegerSetting({key: "demo.size", default: 1, range: {min: 1, max: A}});',
	])(
		"diagnoses shadowed globals and cyclic bounds without evaluating them",
		(source) => {
			const dir = extension({ "index.ts": source });
			expect(extractSurface(dir).diagnostics).toEqual([
				"demo.size: range must have static integer bounds and a positive integer step",
			]);
		},
	);

	it("reports unresolved choices and range steps instead of inventing valid values", () => {
		const dir = extension({
			"index.ts": `
const CHOICE = defineChoiceSetting({ key: "demo.choice", choices: discover(), default: "fast" });
const INTEGER = defineIntegerSetting({ key: "demo.integer", range: { min: 1, max: 8, step: discover() }, default: 1 });
`,
		});
		expect(extractSurface(dir).diagnostics).toEqual([
			"demo.choice: choices must resolve to a static string array",
			"demo.integer: range must have static integer bounds and a positive integer step",
		]);
	});

	it("extracts Voice speech-service settings without removed native-engine controls", () => {
		const surface = extractSurface(join(process.cwd(), "extensions", "voice"));
		expect(surface.diagnostics).toEqual([]);
		expect(surface.settings.map(({ key }) => key)).toEqual([
			"voice.classifierModel",
			"voice.command",
			"voice.maxSentences",
			"voice.maxSpeechSeconds",
			"voice.model",
			"voice.muteShortcut",
			"voice.preview",
			"voice.profile",
			"voice.toggleShortcut",
		]);
		expect(
			surface.settings.find((row) => row.key === "voice.command"),
		).toMatchObject({
			env: "PI_VOICE_COMMAND",
			default: '`["speak_to_me"]`',
		});
		expect(
			surface.settings.find((row) => row.key === "voice.profile"),
		).toMatchObject({
			env: "PI_VOICE_PROFILE",
			default: "`undefined`",
		});
		expect(
			surface.settings.find((row) => row.key === "voice.maxSentences")
				?.constraints,
		).toBe("Integer 1–20");
		expect(
			surface.settings.find((row) => row.key === "voice.maxSpeechSeconds")
				?.constraints,
		).toBe("Integer 1–120");
	});

	it("extracts typed, satisfies, and factory setting declarations without helper diagnostics", () => {
		const dir = extension({
			"index.ts": `
const direct: SettingDeclaration<string> = { key: "direct", parse: text, default: "value" };
const grouped = {
  nested: { key: "grouped", env: "GROUPED", parse: text, default: 42 },
} satisfies Record<string, SettingDeclaration<unknown>>;
const factory = (name: string) => ({ key: "factory." + name, parse: text, default: undefined });
const derived = factory("value");
function helper(declaration: SettingDeclaration<unknown>) { resolveSetting(pi, ctx, declaration); }
resolveSetting(pi, ctx, direct);
resolveSetting(pi, ctx, derived);
`,
		});
		expect(extractSurface(dir).settings).toEqual([
			{ key: "direct", shape: "string", default: '`"value"`' },
			{ key: "factory.value", default: "`undefined`" },
			{ key: "grouped", env: "GROUPED", default: "`42`" },
		]);
		expect(extractSurface(dir).diagnostics).toEqual([]);
	});

	it("renders declared object shapes without treating nested paths as settings", () => {
		const dir = extension({
			"index.ts": `
interface Pair { executor: string; advisor: string }
interface Settings { enabled?: boolean; pairs?: Pair[]; names: "all" | "none" | string[] }
const setting: SettingDeclaration<Settings> = { key: "dilemma", parse: parse, default: {} };
const omitted: SettingDeclaration<boolean> = { key: "omitted", parse: parse };
resolveSetting(pi, ctx, setting);
resolveSetting(pi, ctx, omitted);
`,
		});
		expect(extractSurface(dir).settings).toMatchObject([
			{
				key: "dilemma",
				shape:
					'{ enabled?: boolean; pairs?: { executor: string; advisor: string }[]; names: "all" | "none" | string[] }',
				default: "`{}`",
			},
			{ key: "omitted", shape: "boolean", default: "omitted" },
		]);
		const markdown = renderSurface(extractSurface(dir));
		expect(markdown).toContain("| Setting |");
		expect(markdown).not.toContain("Optional |\n");
		expect(markdown).toContain("`dilemma`");
		expect(markdown).toContain("`dilemma.pairs`");
		expect(markdown).toContain("`dilemma.pairs[].executor`");
		expect(markdown).toContain("not literal top-level keys");
	});

	it("extracts Dilemma's declared nested configuration shape", () => {
		const surface = extractSurface(
			join(process.cwd(), "extensions", "dilemma"),
		);
		expect(surface.settings).toMatchObject([
			{
				key: "dilemma",
				shape:
					'{ pairs?: { executor: string; advisor: string }[]; enabled?: boolean; thinkingLevel?: ThinkingLevel; subagentExtensions?: "none" | "all" | string[]; devilThreshold?: number }',
				default: "`{}`",
			},
		]);
		expect(surface.settings[0]?.fields?.map((field) => field.path)).toEqual([
			"dilemma.pairs",
			"dilemma.pairs[].executor",
			"dilemma.pairs[].advisor",
			"dilemma.enabled",
			"dilemma.thinkingLevel",
			"dilemma.subagentExtensions",
			"dilemma.devilThreshold",
		]);
	});

	it("identifies Masks' parser result instead of documenting it as input", () => {
		const surface = extractSurface(join(process.cwd(), "extensions", "masks"));
		expect(surface.settings).toMatchObject([
			{
				key: "masks",
				shape: "parser-defined input (parsed as ParsedMasks)",
				default: "`{ config, errors }`",
			},
		]);
	});

	it("resolves exposure overrides spread from native defineTool declarations", () => {
		const dir = extension({
			"index.ts": `
const tool = defineTool({ name: "wrapped", description: "Native tool" });
pi.registerTool({ ...tool, exposure: "hidden" });
pi.registerTool({ ...tool, exposure: "direct" });
`,
		});
		const surface = extractSurface(dir);
		expect(surface.diagnostics).toEqual([]);
		expect(surface.tools).toEqual([
			{ name: "wrapped", description: "Native tool" },
		]);
	});

	it("handles external tool factories and discovery-derived tools", () => {
		const dir = extension({
			"index.ts": `
import { createTool } from "./tool.js";
pi.registerTool(createTool());
pi.registerTool({ name: catalog.localName, description: skillText });
`,
			"tool.ts": `export function createTool() { return defineTool({ name: "external", description: "First sentence.\\n${"x".repeat(500)}" }); }`,
		});
		const surface = extractSurface(dir);
		expect(surface.diagnostics).toEqual([]);
		expect(surface.tools).toEqual([
			{ name: "external", description: "First sentence." },
		]);
		expect(surface.toolDiscovery).toBe(true);
		expect(renderSurface(surface)).not.toContain("catalog");
	});

	it("covers repository wrappers, loops, factories, and discovery-derived tools", () => {
		const root = join(process.cwd(), "extensions");
		const surfaces = new Map(
			extensionDirs(process.cwd()).map((name) => [
				name,
				extractSurface(join(root, name)),
			]),
		);
		for (const [name, surface] of surfaces)
			expect(surface.diagnostics, name).toEqual([]);
		for (const name of [
			"ask",
			"bak",
			"chrome-cdp",
			"firefox-bidi",
			"git-safe",
			"good-job",
			"intellij",
			"notes",
			"the-system",
			"web",
		])
			expect(surfaces.get(name)?.diagnostics, name).toEqual([]);
		const intellij = surfaces.get("intellij");
		expect(intellij?.toolDiscovery).toBe(false);
		expect(intellij?.tools).toEqual([]);
		expect(intellij?.commands.map(({ name }) => name)).toEqual(["/intellij"]);
		expect(surfaces.get("notes")?.settings.map(({ key }) => key)).toEqual([
			"notes.addFromEditorShortcut",
			"notes.sendPickerShortcut",
			"notes.toggleShortcut",
		]);
		expect(
			surfaces.get("web")?.settings.find(({ key }) => key === "web.zai.mcpUrl")
				?.env,
		).toBe("ZAI_SEARCH_MCP_URL | ZAI_SEARCH_BASE_URL");
	});

	it("bounds recursive factory resolution", () => {
		const dir = extension({
			"index.ts": `function loop(value: string) { return loop(value); } const setting = loop("x"); resolveSetting(pi, ctx, setting);`,
		});
		expect(extractSurface(dir).diagnostics).toEqual([]);
	});

	it("bounds recursive spread resolution after factory substitution", () => {
		const dir = extension({
			"index.ts": `function wrap() { return { ...wrap() }; } const value = wrap(); resolveSetting(pi, ctx, value);`,
		});
		expect(extractSurface(dir).settings).toEqual([]);
	});

	it("escapes aliases in table cells", () => {
		const surface = extractSurface(
			extension({
				"index.ts": `const setting = { key: "a", parse: String, default: null, env: "A | B" };`,
			}),
		);
		expect(renderSurface(surface)).toContain("`A \\| B`");
	});

	it("reports unresolved registrations and never claims the surface is empty", () => {
		const dir = extension({
			"index.ts":
				"export function load(pi: any, tool: unknown) { pi.registerTool(tool); }\n",
			"demo/ignored.ts":
				'pi.registerTool({ name: "ignored", description: "ignored" });\n',
			"__tests__/ignored.ts":
				'pi.registerTool({ name: "ignored_test", description: "ignored" });\n',
		});
		const surface = extractSurface(dir);
		expect(surface.tools).toEqual([]);
		expect(surface.diagnostics).toEqual([
			"index.ts: tool definition cannot be resolved statically",
		]);
		const markdown = renderSurface(surface);
		expect(markdown).toContain("### Extraction diagnostics");
		expect(markdown).not.toContain(
			"This extension has no commands, tools, flags, or settings.",
		);
	});

	it("reports parse errors instead of silently omitting a source file", () => {
		const dir = extension({ "broken.ts": "export const = ;\n" });
		expect(extractSurface(dir).diagnostics[0]).toMatch(
			/^broken\.ts: parse failed:/,
		);
	});
});