burgee 0.9.2 → 0.11.0

package/README.md

@@ -15,7 +15,7 @@
   <a href="https://www.npmjs.com/package/burgee"><img src="https://img.shields.io/npm/v/burgee?style=flat-square&color=0a6b47" alt="npm version" /></a>
   <a href="https://www.npmjs.com/package/burgee"><img src="https://img.shields.io/npm/dm/burgee?style=flat-square" alt="npm downloads" /></a>
   <img src="https://img.shields.io/badge/dependencies-5%20in--family-0a6b47?style=flat-square" alt="Five dependencies, all in this repository: bellpull, closeout, linegauge, roundel, seniority" />
-  <img src="https://img.shields.io/badge/Node.js-24+-green.svg?style=flat-square" alt="Node.js 24+" />
+  <img src="https://img.shields.io/badge/Node.js-20.19%2B%20%7C%2022.13%2B-green.svg?style=flat-square" alt="Node.js 20.19+ or 22.13+" />
   <img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License: MIT" />
 </p>
 
@@ -164,7 +164,7 @@ so nothing reaches an agent by accident. Register it with any stdio client:
 
 ### Does it have dependencies?
 
-None outside this repository. `burgee` installs five packages from its own family —
+None outside the burgee family. `burgee` installs five packages from that family —
 `bellpull`, `closeout`, `linegauge`, `roundel` and `seniority` — and each of those takes
 nothing from outside it either: one repository, one release pipeline, one supply chain to
 audit.

package/dist/commander/command.d.ts

@@ -58,6 +58,22 @@ export interface OutputContext {
     error?: boolean;
 }
 export type HookEvent = 'preSubcommand' | 'preAction' | 'postAction';
+/**
+ * commander's option-value types, as `typings/index.d.ts` declares them. `any` is
+ * commander's choice and the point: `program.opts().port` is usable without a cast, and
+ * `opts<T>()` narrows it — a program written against commander's types relies on both;
+ * `unknown` here breaks every `opts().x` such a program reads.
+ */
+export type OptionValues = Record<string, any>;
+/** Where an option's value came from. A string, so an author can define their own; the known ones autocomplete. */
+export type OptionValueSource = 'default' | 'config' | 'env' | 'cli' | 'implied' | (string & Record<never, never>) | undefined;
+/** What `.configureHelp()` takes: any subset of `Help`'s methods and settings. */
+export type HelpConfiguration = Partial<Help>;
+/** `.parseOptions()`'s split of an argv into operands and unknown options. */
+export interface ParseOptionsResult {
+    operands: string[];
+    unknown: string[];
+}
 export type HookListener = (thisCommand: Command, actionCommand: Command) => void | Promise<void>;
 export type AddHelpTextPosition = 'beforeAll' | 'before' | 'after' | 'afterAll';
 export type AddHelpTextContext = {
@@ -236,14 +252,11 @@ export declare class Command extends EventEmitter {
      *     sub --unknown uuu op => [sub], [--unknown uuu op]
      *     sub -- --unknown uuu op => [sub --unknown uuu op], []
      */
-    parseOptions(args: string[]): {
-        operands: string[];
-        unknown: string[];
-    };
-    /** Local option values as key-value pairs. */
-    opts(): Record<string, unknown>;
+    parseOptions(args: string[]): ParseOptionsResult;
+    /** Local option values as key-value pairs; `opts<T>()` types them, as commander's own declaration does. */
+    opts<T extends OptionValues = OptionValues>(): T;
     /** Merged local and global option values; globals overwrite locals. */
-    optsWithGlobals(): Record<string, unknown>;
+    optsWithGlobals<T extends OptionValues = OptionValues>(): T;
     /** Display an error message and exit (or call exitOverride). */
     error(message: string, errorOptions?: ErrorOptions): never;
     /** One failure as the envelope (E3, G5); `fix` only when one candidate was named. */

package/dist/commander.d.ts

@@ -4,13 +4,19 @@
  * `.sdlc/intents/commander-compat/spec.md` and `npm run compat`.
  */
 import { Argument } from './commander/argument.js';
-import { Command } from './commander/command.js';
+import { Command, type OutputConfiguration as ResolvedOutputConfiguration } from './commander/command.js';
 import { Option } from './commander/option.js';
 export { Argument, humanReadableArgName } from './commander/argument.js';
-export { Command, useColor, type AddHelpTextContext, type AddHelpTextPosition, type BurgeeParseOptions, type CommandOptions, type ErrorOptions, type ExecutableCommandOptions, type HookEvent, type HookListener, type OutputConfiguration, type OutputContext, type ParseOptions, } from './commander/command.js';
+export { Command, useColor, type AddHelpTextContext, type AddHelpTextPosition, type BurgeeParseOptions, type CommandOptions, type ErrorOptions, type ExecutableCommandOptions, type HelpConfiguration, type HookEvent, type HookListener, type OptionValueSource, type OptionValues, type OutputContext, type ParseOptions, type ParseOptionsResult, } from './commander/command.js';
 export { CommanderError, InvalidArgumentError, InvalidArgumentError as InvalidOptionArgumentError } from './commander/error.js';
 export { Help, type HelpContext } from './commander/help.js';
 export { DualOptions, Option } from './commander/option.js';
+/**
+ * commander's `OutputConfiguration`: every member optional, because `.configureOutput()`
+ * takes any subset of them and a typed program annotates exactly that subset. What
+ * `.configureOutput()` hands back is the resolved, complete one.
+ */
+export type OutputConfiguration = Partial<ResolvedOutputConfiguration>;
 /** The root command, for programs that never construct their own. */
 export declare const program: Command;
 export declare const createCommand: (name?: string) => Command;

package/dist/execute.js

@@ -326,6 +326,7 @@ async function surface(manifest, argv, io) {
         return true;
     }
     if (head.includes('--schema')) {
+        const { schemaSurface } = await import('./schema-surface.js');
         io.out.write(`${await machineJson(await schemaSurface(manifest, argv), head)}\n`);
         return true;
     }
@@ -351,16 +352,6 @@ async function surface(manifest, argv, io) {
     }
     return false;
 }
-const SCHEMA_BUDGET = 48_000;
-async function schemaSurface(manifest, argv) {
-    const { commandSchemaOf, schemaOf, summaryOf } = await import('./schema.js');
-    const { node } = manifest.resolve(beforeTerminator(argv).filter((a) => a !== '--schema' && !a.startsWith('--format=')), manifest.rootPath);
-    if (node?.run !== undefined)
-        return commandSchemaOf(node, manifest.rootPath);
-    const full = schemaOf(manifest);
-    const budget = manifest.schemaBudget ?? SCHEMA_BUDGET;
-    return JSON.stringify(full).length <= budget ? full : summaryOf(manifest, budget);
-}
 async function helpCommand(manifest, argv, root, io) {
     const { node } = manifest.resolve(argv, root);
     return renderHelp(manifest, node ?? rootNode(manifest, root), io);

package/dist/migrate.d.ts

@@ -8,8 +8,24 @@ import { type Graded } from './compat.js';
 export declare const MAPPING: Readonly<Record<string, string>>;
 /** The packages a project depends on that this command is about (A1). */
 export declare const HOSTS: readonly ["commander", "yargs"];
-/** Why a file was left untouched. Both are named positions, never a guess (A4). */
-export type RefusalReason = 'deep-import' | 'non-literal-specifier';
+/**
+ * Every name each target exports — values and types alike — so a rewrite that moves
+ * `import { Argv } from 'yargs'` can first ask whether `burgee/yargs` has an `Argv`.
+ *
+ * A specifier-only rewrite (D-050) cannot tell a value from a type, and does not need to:
+ * a name the target does not export breaks the build either way. This is data rather than
+ * a lookup because the lookup is the TypeScript checker, which is the dependency this
+ * command exists not to have; `facade-types.test.ts` holds the table equal to what the
+ * checker sees in `dist/*.d.ts`, so it cannot drift from the façades it describes.
+ */
+export declare const FACADE_EXPORTS: Readonly<Record<string, readonly string[]>>;
+/**
+ * Why a file was left untouched. Each is a named position, never a guess (A4).
+ *
+ * `unknown-export` is a named import the target does not export — rewriting it would turn a
+ * working import into TS2305 or a `SyntaxError` at load, so the file stays as it was.
+ */
+export type RefusalReason = 'deep-import' | 'non-literal-specifier' | 'unknown-export';
 export interface Refusal {
     /** Relative to the directory being migrated, with forward slashes on every platform. */
     file: string;
@@ -17,6 +33,23 @@ export interface Refusal {
     /** The specifier as written, or `''` for a dynamic specifier that is not a literal. */
     specifier: string;
     reason: RefusalReason;
+    /** For `unknown-export`: the names the target does not export. */
+    names?: string[];
+}
+/**
+ * A type-only import left on the incumbent because the façade does not export every name in
+ * it. Types are erased, so the file's values still move to burgee and the program runs on it;
+ * the types keep compiling against the incumbent's declarations, which is why the incumbent
+ * is then not reported removable.
+ */
+export interface Kept {
+    file: string;
+    line: number;
+    specifier: string;
+    /** The names the façade does not export. */
+    names: string[];
+    /** The note a reader acts on. */
+    note: string;
 }
 /** One rewritten specifier, for the per-mapping rollup the report prints. */
 export interface Mapped {
@@ -36,6 +69,8 @@ export interface MigrationReport {
     imports: number;
     mapped: Mapped[];
     refused: Refusal[];
+    /** Type-only imports left pointing at the incumbent, each with the note that says why. */
+    kept: Kept[];
     detected: Detection;
     dependencies: {
         before: string[];
@@ -57,6 +92,11 @@ interface Site {
     start: number;
     end: number;
     line: number;
+    /**
+     * For `import … from` and `export … from`: the code tokens between the keyword and `from`
+     * — the import clause, which is all `bindingsOf` needs. Absent for the other three positions.
+     */
+    clause?: string[];
 }
 interface Scan {
     sites: Site[];
@@ -80,6 +120,7 @@ export interface Rewrite {
         to: string;
     }[];
     refused: Omit<Refusal, 'file'>[];
+    kept: Omit<Kept, 'file'>[];
     /** Whether this file references a host at all. A file that does not is not "untouched", it is unrelated. */
     relevant: boolean;
 }
@@ -93,6 +134,19 @@ export interface Rewrite {
  * on a `Buffer` it also skips decoding 3 MB of UTF-8 that nothing was going to read.
  */
 export declare function mentionsAHost(source: string | Buffer): boolean;
+/**
+ * The names an import or re-export clause asks the module for, and whether the whole
+ * statement is type-only (`import type …`, `export type …`).
+ *
+ * Read off the tokens the scan already has: `{ a, type b, c as d }` asks for `a`, `b` and
+ * `c`; a default or namespace binding asks for no name a façade could lack (`default` is
+ * the factory, and `* as ns` is checked where it is used, which a scan cannot see). A name
+ * written as a string (`{ 'a-b' as c }`) is left unverified rather than guessed at.
+ */
+export declare function bindingsOf(clause: readonly string[]): {
+    typeOnly: boolean;
+    names: string[];
+};
 /**
  * A2/A5 — map every host specifier in one file, or map none of them.
  *

package/dist/migrate.js

@@ -11,6 +11,89 @@ export const MAPPING = {
     'yargs/helpers': 'burgee/yargs/helpers',
 };
 export const HOSTS = ['commander', 'yargs'];
+export const FACADE_EXPORTS = {
+    'burgee/commander': [
+        'AddHelpTextContext',
+        'AddHelpTextPosition',
+        'Argument',
+        'BurgeeParseOptions',
+        'Command',
+        'CommandOptions',
+        'CommanderError',
+        'DualOptions',
+        'ErrorOptions',
+        'ExecutableCommandOptions',
+        'Help',
+        'HelpConfiguration',
+        'HelpContext',
+        'HookEvent',
+        'HookListener',
+        'InvalidArgumentError',
+        'InvalidOptionArgumentError',
+        'Option',
+        'OptionValueSource',
+        'OptionValues',
+        'OutputConfiguration',
+        'OutputContext',
+        'ParseOptions',
+        'ParseOptionsResult',
+        'createArgument',
+        'createCommand',
+        'createOption',
+        'humanReadableArgName',
+        'program',
+        'useColor',
+    ],
+    'burgee/yargs': [
+        'Arguments',
+        'ArgumentsCamelCase',
+        'Argv',
+        'AsyncCompletionFunction',
+        'BuilderArguments',
+        'BuilderCallback',
+        'Choices',
+        'CommandBuilder',
+        'CommandModule',
+        'CompletionCallback',
+        'Defined',
+        'DetailedArguments',
+        'FallbackCompletionFunction',
+        'InferredOptionType',
+        'InferredOptionTypeInner',
+        'InferredOptionTypePrimitive',
+        'InferredOptionTypes',
+        'MiddlewareFunction',
+        'Options',
+        'ParseCallback',
+        'ParsedCommand',
+        'Parser',
+        'ParserConfigurationOptions',
+        'PlatformShim',
+        'PositionalOptions',
+        'PositionalOptionsType',
+        'PromiseCompletionFunction',
+        'RequireDirectoryOptions',
+        'SyncCompletionFunction',
+        'ToArray',
+        'ToNumber',
+        'ToString',
+        'YError',
+        'YargsInstance',
+        'applyExtends',
+        'argsert',
+        'camelCase',
+        'decamelize',
+        'default',
+        'hideBin',
+        'isPromise',
+        'isYargsInstance',
+        'looksLikeNumber',
+        'objFilter',
+        'parseCommand',
+        'platformShim',
+    ],
+    'burgee/yargs/helpers': ['Parser', 'applyExtends', 'hideBin'],
+};
 const WORD = /[A-Za-z0-9_$]/;
 const DIVIDES = new Set([')', ']', '}']);
 function startsRegex(previous) {
@@ -123,12 +206,25 @@ function push(tokens, text, line) {
     if (tokens.pending && text !== QUOTED && text !== ')')
         tokens.nonLiteral.push(line);
     tokens.pending = text === '(' && (tokens.previous === 'import' || tokens.previous === 'require');
+    if (text === 'import' || text === 'export')
+        tokens.clause = [];
+    else if (text === '(' || text === '=' || tokens.previous === 'from')
+        tokens.clause = undefined;
+    else
+        tokens.clause?.push(text);
     tokens.before = tokens.previous;
     tokens.previous = text;
 }
+function siteOf(source, at, tokens) {
+    const { open, close, line } = at;
+    const site = { specifier: source.slice(open + 1, close - 1), start: open + 1, end: close - 1, line };
+    if (tokens.previous === 'from' && tokens.clause !== undefined)
+        site.clause = tokens.clause.slice(0, -1);
+    return site;
+}
 export function scan(source) {
     const sites = [];
-    const tokens = { previous: '', before: '', pending: false, nonLiteral: [] };
+    const tokens = { previous: '', before: '', pending: false, nonLiteral: [], clause: undefined };
     let line = 1;
     let i = 0;
     while (i < source.length) {
@@ -143,7 +239,7 @@ export function scan(source) {
             const c = source.charAt(i);
             const quoted = c === "'" || c === '"';
             if (quoted && isSpecifier(tokens.previous, tokens.before))
-                sites.push({ specifier: source.slice(i + 1, literal - 1), start: i + 1, end: literal - 1, line });
+                sites.push(siteOf(source, { open: i, close: literal, line }, tokens));
             push(tokens, quoted ? QUOTED : 'lit', line);
             line += newlines(source, i, literal);
             i = literal;
@@ -169,27 +265,71 @@ function isDeep(specifier) {
         return false;
     return HOSTS.some((host) => specifier.startsWith(`${host}/`));
 }
+export function bindingsOf(clause) {
+    const typeOnly = clause[0] === 'type' && clause.length > 1;
+    const open = clause.indexOf('{');
+    const close = clause.indexOf('}', open);
+    if (open === -1 || close === -1)
+        return { typeOnly, names: [] };
+    const names = [];
+    let element = [];
+    for (const token of [...clause.slice(open + 1, close), ',']) {
+        if (token !== ',') {
+            element.push(token);
+            continue;
+        }
+        const modifier = element[0] === 'type' && element.length > 1 && element[1] !== 'as';
+        const name = modifier ? element[1] : element[0];
+        if (name !== undefined && name !== 'default' && name !== QUOTED && WORD.test(name.charAt(0)))
+            names.push(name);
+        element = [];
+    }
+    return { typeOnly, names };
+}
+function missingFrom(site, to) {
+    const exported = FACADE_EXPORTS[to];
+    if (site.clause === undefined || exported === undefined)
+        return { typeOnly: false, missing: [] };
+    const { typeOnly, names } = bindingsOf(site.clause);
+    return { typeOnly, missing: names.filter((name) => !exported.includes(name)) };
+}
 export function rewriteSource(source) {
     if (!mentionsAHost(source))
-        return { source, mapped: [], refused: [], relevant: false };
+        return { source, mapped: [], refused: [], kept: [], relevant: false };
     const { sites, nonLiteral } = scan(source);
     const hits = sites.filter((s) => MAPPING[s.specifier] !== undefined || isDeep(s.specifier));
     if (hits.length === 0)
-        return { source, mapped: [], refused: [], relevant: false };
+        return { source, mapped: [], refused: [], kept: [], relevant: false };
+    const kept = [];
+    const unknown = [];
+    const moving = [];
+    for (const site of hits) {
+        const to = MAPPING[site.specifier];
+        if (to === undefined)
+            continue;
+        const { typeOnly, missing } = missingFrom(site, to);
+        if (missing.length === 0)
+            moving.push(site);
+        else if (typeOnly)
+            kept.push({ line: site.line, specifier: site.specifier, names: missing, note: `${to} does not export ${missing.join(', ')}; this type-only import stays on '${site.specifier}', so keep its types installed` });
+        else
+            unknown.push({ line: site.line, specifier: site.specifier, reason: 'unknown-export', names: missing });
+    }
     const refused = [
         ...hits.filter((s) => isDeep(s.specifier)).map((s) => ({ line: s.line, specifier: s.specifier, reason: 'deep-import' })),
         ...nonLiteral.map((line) => ({ line, specifier: '', reason: 'non-literal-specifier' })),
+        ...unknown,
     ].sort((a, b) => a.line - b.line);
     if (refused.length > 0)
-        return { source, mapped: [], refused, relevant: true };
+        return { source, mapped: [], refused, kept: [], relevant: true };
     let out = source;
     const mapped = [];
-    for (const site of [...hits].sort((a, b) => b.start - a.start)) {
+    for (const site of moving.sort((a, b) => b.start - a.start)) {
         const to = MAPPING[site.specifier];
         out = `${out.slice(0, site.start)}${to}${out.slice(site.end)}`;
         mapped.push({ from: site.specifier, to });
     }
-    return { source: out, mapped: mapped.reverse(), refused: [], relevant: true };
+    return { source: out, mapped: mapped.reverse(), refused: [], kept, relevant: true };
 }
 const SOURCE_EXTENSIONS = new Set(['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.mts', '.cts']);
 const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.turbo', '.next', '.output', '.cache', '.vercel']);
@@ -230,7 +370,7 @@ export class DirtyTreeError extends Error {
         this.name = 'DirtyTreeError';
     }
 }
-const EMPTY = { source: '', mapped: [], refused: [], relevant: false };
+const EMPTY = { source: '', mapped: [], refused: [], kept: [], relevant: false };
 async function migrateBatch(dir, batch, write) {
     const sources = await Promise.all(batch.map(async (file) => await readFile(join(dir, file))));
     const results = sources.map((bytes) => (mentionsAHost(bytes) ? rewriteSource(bytes.toString('utf8')) : EMPTY));
@@ -264,9 +404,10 @@ export async function migrate(options) {
     }
     const all = results.flatMap(({ file, result }) => result.mapped.map((m) => ({ ...m, file })));
     const refused = results.flatMap(({ file, result }) => result.refused.map((r) => ({ file, ...r })));
-    const imported = [...new Set(results.flatMap(({ result }) => (result.relevant ? result.mapped.map((m) => m.from) : [])))];
+    const kept = results.flatMap(({ file, result }) => result.kept.map((k) => ({ file, ...k })));
+    const imported = [...new Set(results.flatMap(({ result }) => (result.relevant ? [...result.mapped.map((m) => m.from), ...result.kept.map((k) => k.specifier)] : [])))];
     const declared = await declaredHosts(dir);
-    const stillUsed = new Set(refused.map((r) => r.specifier.split('/')[0] ?? ''));
+    const stillUsed = new Set([...refused, ...kept].map((r) => r.specifier.split('/')[0] ?? ''));
     const removable = declared.filter((host) => !stillUsed.has(host));
     const touched = [...new Set(all.map((m) => m.file))];
     return {
@@ -274,6 +415,7 @@ export async function migrate(options) {
         imports: all.length,
         mapped: rollup(all),
         refused,
+        kept,
         detected: { declared, imported: [...new Set(imported.map((s) => s.split('/')[0] ?? s))].sort() },
         dependencies: { before: declared, removable, after: declared.length - removable.length },
         graded: gradedFor([...new Set([...declared, ...imported.map((s) => s.split('/')[0] ?? s)])].sort()),

package/dist/schema-surface.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) 2026 Ofri Peretz
+ * Licensed under the MIT License. Use of this source code is governed by the
+ * MIT license that can be found in the LICENSE file.
+ */
+/**
+ * N13 / D-116 — `--schema <command> --field <path>`: one field of one command's schema, so an
+ * agent under a token budget reads `options.region` instead of the whole document. The path is
+ * dotted; a step that does not exist is refused naming the steps that do.
+ *
+ * With the `--schema` surface it serves: `execute.ts` imports this module only when `--schema`
+ * is on the command line (M2), so neither weighs on a run that does not ask for it.
+ */
+import { type Manifest } from './manifest.js';
+export declare function fieldOf(doc: unknown, path: string, command: string): unknown;
+/**
+ * `--schema` under a character budget (N13): one command's full schema when a command is
+ * named (the drilling), the whole program when it fits, a summary naming every command
+ * and how to drill when it does not.
+ */
+export declare function schemaSurface(manifest: Manifest, argv: string[]): Promise<unknown>;

package/dist/schema-surface.js

@@ -0,0 +1,38 @@
+import { UsageError } from './validate.js';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+export function fieldOf(doc, path, command) {
+    let at = doc;
+    const walked = [];
+    for (const step of path.split('.')) {
+        if (!isRecord(at) || !(step in at)) {
+            const here = walked.length === 0 ? `"${command}"` : `"${walked.join('.')}"`;
+            const valid = isRecord(at) ? Object.keys(at).join(', ') : 'none — it is a value';
+            throw new UsageError(`${here} has no field "${step}"`, `fields here: ${valid}`);
+        }
+        at = at[step];
+        walked.push(step);
+    }
+    return at;
+}
+const SCHEMA_BUDGET = 48_000;
+export async function schemaSurface(manifest, argv) {
+    const { commandSchemaOf, schemaOf, summaryOf } = await import('./schema.js');
+    const end = argv.indexOf('--');
+    const head = end === -1 ? argv : argv.slice(0, end);
+    const at = head.findIndex((a) => a === '--field' || a.startsWith('--field='));
+    const field = at === -1 ? undefined : (head[at]?.slice('--field='.length) || head[at + 1]);
+    const width = head[at] === '--field' ? 1 : 0;
+    const drop = at === -1 ? -1 : at + width;
+    const path = head.filter((a, i) => a !== '--schema' && !a.startsWith('--format=') && (i < at || i > drop));
+    const { node } = manifest.resolve(path, manifest.rootPath);
+    if (field !== undefined) {
+        if (node?.run === undefined)
+            throw new UsageError('--field drills into one command', 'name the command first: --schema <command> --field <path>');
+        return fieldOf(commandSchemaOf(node, manifest.rootPath), field, path.join(' '));
+    }
+    if (node?.run !== undefined)
+        return commandSchemaOf(node, manifest.rootPath);
+    const full = schemaOf(manifest);
+    const budget = manifest.schemaBudget ?? SCHEMA_BUDGET;
+    return JSON.stringify(full).length <= budget ? full : summaryOf(manifest, budget);
+}