repositories / pi-ext
pi-ext
bugabingas pi extensions
owned by admin
scripts/readme/config.test.ts
Rawimport { 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:/,
);
});
});