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 { 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 = 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 = { key: "direct", parse: text, default: "value" }; const grouped = { nested: { key: "grouped", env: "GROUPED", parse: text, default: 42 }, } satisfies Record>; const factory = (name: string) => ({ key: "factory." + name, parse: text, default: undefined }); const derived = factory("value"); function helper(declaration: SettingDeclaration) { 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 = { key: "dilemma", parse: parse, default: {} }; const omitted: SettingDeclaration = { 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:/, ); }); });