@pikku/cli 0.12.115 → 0.12.116

package/dist/src/functions/surface/build-surface-doc.js

@@ -96,6 +96,10 @@ const toDocSymbols = (entrypoint, generatedRoot) => [...entrypoint.symbols]
     ...(symbol.deprecated
         ? { deprecated: symbol.deprecatedReason ?? 'Deprecated' }
         : {}),
+    ...(symbol.signature ? { signature: symbol.signature } : {}),
+    ...(symbol.members?.length ? { members: symbol.members } : {}),
+    ...(symbol.examples?.length ? { examples: symbol.examples } : {}),
+    ...(symbol.status !== undefined ? { status: symbol.status } : {}),
 }));
 const byStepThenName = (a, b) => STEP_ORDER.indexOf(a.step) - STEP_ORDER.indexOf(b.step) ||
     a.name.localeCompare(b.name);
@@ -121,6 +125,7 @@ const toLeaves = (entryPoint, entrypoints, editorial, generatedRoot) => {
             name,
             step: copy.step,
             summary: copy.summary,
+            skill: copy.skill,
             symbols: toDocSymbols(entrypoint, generatedRoot),
         });
     }
@@ -129,11 +134,12 @@ const toLeaves = (entryPoint, entrypoints, editorial, generatedRoot) => {
     }
     return leaves.sort(byStepThenName);
 };
-const projectEntryPoint = async (id, project) => {
+const projectEntryPoint = async (id, project, snippets) => {
     const projectDir = resolve(project.projectDir);
     const generatedRoot = resolve(project.outDir ?? join(projectDir, '.pikku'));
     const entrypoints = await collectSurface(projectDir, {
         importsSubpath: PIKKU_IMPORTS_SUBPATH,
+        snippets,
     });
     return {
         id,
@@ -142,10 +148,17 @@ const projectEntryPoint = async (id, project) => {
         leaves: toLeaves(id, entrypoints, (subpath) => LEAF_EDITORIAL[leafNameOf(subpath)], generatedRoot),
     };
 };
-export const buildSurfaceDoc = async ({ version, app, addon, }) => ({
-    version,
-    entryPoints: [
-        await projectEntryPoint('app', app),
-        await projectEntryPoint('addon', addon),
-    ],
-});
+/**
+ * An example names a snippet rather than restating it, and both entrypoints
+ * resolve against the same map — the regions come from one running application
+ * (`examples/online-shop`), not from whichever template happened to hold them.
+ */
+export const buildSurfaceDoc = async ({ version, app, addon, snippets, }) => {
+    return {
+        version,
+        entryPoints: [
+            await projectEntryPoint('app', app, snippets),
+            await projectEntryPoint('addon', addon, snippets),
+        ],
+    };
+};

package/dist/src/functions/surface/collect-snippets.d.ts

@@ -0,0 +1,13 @@
+export declare class UnclosedSnippetError extends Error {
+    constructor(name: string, file: string);
+}
+export declare class DuplicateSnippetError extends Error {
+    constructor(name: string, file: string, other: string);
+}
+/**
+ * The `// @snippet start <name>` regions in a project's source, so an example
+ * in a doc comment can name one instead of restating it. The same mechanism the
+ * website uses to pull its code blocks out of the shop template: the code that
+ * reaches the reader is the code that compiles, and it cannot drift.
+ */
+export declare const collectSnippets: (projectDir: string, into?: Map<string, string>, origins?: Map<string, string>) => Promise<Map<string, string>>;

package/dist/src/functions/surface/collect-snippets.js

@@ -0,0 +1,83 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+const START = /^\s*(?:\/\/|--)\s*@snippet start (\S+)\s*$/;
+const END = /^\s*(?:\/\/|--)\s*@snippet end (\S+)\s*$/;
+const SOURCE_EXTENSIONS = ['.ts', '.tsx', '.sql'];
+const SKIPPED_DIRECTORIES = new Set(['node_modules', '.pikku', 'dist', '.git']);
+export class UnclosedSnippetError extends Error {
+    constructor(name, file) {
+        super(`The snippet "${name}" opens in ${file} and never closes. Add "// @snippet end ${name}".`);
+        this.name = 'UnclosedSnippetError';
+    }
+}
+export class DuplicateSnippetError extends Error {
+    constructor(name, file, other) {
+        super(`The snippet "${name}" is defined twice, in ${other} and ${file}. Snippet names are the reference an example uses, so they have to be unique.`);
+        this.name = 'DuplicateSnippetError';
+    }
+}
+const dedent = (lines) => {
+    const indents = lines
+        .filter((line) => line.trim().length > 0)
+        .map((line) => line.length - line.trimStart().length);
+    const shortest = indents.length > 0 ? Math.min(...indents) : 0;
+    return lines
+        .map((line) => line.slice(shortest))
+        .join('\n')
+        .trim();
+};
+const sourceFilesIn = async (directory, found = []) => {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+        const full = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (SKIPPED_DIRECTORIES.has(entry.name) || entry.name.startsWith('.')) {
+                continue;
+            }
+            await sourceFilesIn(full, found);
+        }
+        else if (SOURCE_EXTENSIONS.some((ext) => entry.name.endsWith(ext))) {
+            found.push(full);
+        }
+    }
+    return found;
+};
+/**
+ * The `// @snippet start <name>` regions in a project's source, so an example
+ * in a doc comment can name one instead of restating it. The same mechanism the
+ * website uses to pull its code blocks out of the shop template: the code that
+ * reaches the reader is the code that compiles, and it cannot drift.
+ */
+export const collectSnippets = async (projectDir, into = new Map(), origins = new Map()) => {
+    for (const file of await sourceFilesIn(projectDir)) {
+        const where = relative(projectDir, file);
+        const lines = (await readFile(file, 'utf8')).split('\n');
+        const open = new Map();
+        for (const line of lines) {
+            const end = line.match(END);
+            if (end?.[1] && open.has(end[1])) {
+                const name = end[1];
+                const existing = origins.get(name);
+                if (existing)
+                    throw new DuplicateSnippetError(name, where, existing);
+                into.set(name, dedent(open.get(name)));
+                origins.set(name, where);
+                open.delete(name);
+                continue;
+            }
+            const start = line.match(START);
+            if (start?.[1]) {
+                if (!open.has(start[1]))
+                    open.set(start[1], []);
+                continue;
+            }
+            if (end)
+                continue;
+            for (const body of open.values())
+                body.push(line);
+        }
+        const [unclosed] = open.keys();
+        if (unclosed)
+            throw new UnclosedSnippetError(unclosed, where);
+    }
+    return into;
+};

package/dist/src/functions/surface/collect-surface.d.ts

@@ -12,6 +12,18 @@ export type SurfaceSymbol = {
     summary?: string;
     /** The symbol's JSDoc in full, paragraphs and examples included. */
     docs?: string;
+    /** The type as the checker prints it, so a caller knows how to call it. */
+    signature?: string;
+    /**
+     * The shape written at the call site, one `name?: type` per entry — the
+     * properties of the object a function takes, or of the type itself. The
+     * signature names that shape; this says what is in it.
+     */
+    members?: SurfaceMember[];
+    /** The `@example` blocks, which the documentation comment leaves out. */
+    examples?: string[];
+    /** The HTTP status an error class is registered with. */
+    status?: number;
 };
 export type SurfaceEntrypoint = {
     subpath: string;
@@ -28,5 +40,19 @@ export type CollectSurfaceOptions = {
     importsSubpath?: string;
     /** Restrict collection to these subpaths, so the program stays small. */
     subpaths?: string[];
+    /** The snippet regions an `@example snippet: name` resolves against. */
+    snippets?: Map<string, string>;
+};
+export declare class UnknownSnippetError extends Error {
+    constructor(name: string, symbol: string, known: string[]);
+}
+/**
+ * One key of an options object: how it is written, and — where the declaring
+ * type says so — what it means. `schedule: string` is a shape; "a cron
+ * expression" is what a caller actually needs, and only the JSDoc has it.
+ */
+export type SurfaceMember = {
+    line: string;
+    doc?: string;
 };
-export declare const collectSurface: (packageDir: string, { importsSubpath, subpaths }?: CollectSurfaceOptions) => Promise<SurfaceEntrypoint[]>;
+export declare const collectSurface: (packageDir: string, { importsSubpath, subpaths, snippets }?: CollectSurfaceOptions) => Promise<SurfaceEntrypoint[]>;

package/dist/src/functions/surface/collect-surface.js

@@ -150,10 +150,15 @@ const KIND_BY_FLAG = [
     [ts.SymbolFlags.TypeAlias, 'type'],
     [ts.SymbolFlags.Namespace, 'namespace'],
 ];
+/**
+ * A leaf re-exports through `export *`, so the symbol reached here is an alias
+ * that carries no kind, no documentation, no tags and no type of its own.
+ */
+const aliasTargetOf = (symbol, checker) => symbol.flags & ts.SymbolFlags.Alias
+    ? checker.getAliasedSymbol(symbol)
+    : symbol;
 const kindOf = (symbol, checker) => {
-    const target = symbol.flags & ts.SymbolFlags.Alias
-        ? checker.getAliasedSymbol(symbol)
-        : symbol;
+    const target = aliasTargetOf(symbol, checker);
     for (const [flag, kind] of KIND_BY_FLAG) {
         if (target.flags & flag)
             return kind;
@@ -169,14 +174,49 @@ const kindOf = (symbol, checker) => {
     }
     return 'const';
 };
-const isDeprecated = (symbol) => symbol.getJsDocTags().some((tag) => tag.name === 'deprecated');
-const deprecationReason = (symbol) => {
-    const tag = symbol.getJsDocTags().find((each) => each.name === 'deprecated');
+const jsDocTagsOf = (symbol, checker) => {
+    const own = symbol.getJsDocTags(checker);
+    if (own.length > 0)
+        return own;
+    return aliasTargetOf(symbol, checker).getJsDocTags(checker);
+};
+const isDeprecated = (tags) => tags.some((tag) => tag.name === 'deprecated');
+const deprecationReason = (tags) => {
+    const tag = tags.find((each) => each.name === 'deprecated');
     if (!tag)
         return undefined;
     const text = ts.displayPartsToString(tag.text).trim();
     return text.length > 0 ? text : undefined;
 };
+export class UnknownSnippetError extends Error {
+    constructor(name, symbol, known) {
+        super(`The example on ${symbol} names the snippet "${name}", which no template declares. Wrap the code you want shown in "// @snippet start ${name}" / "// @snippet end ${name}". Declared: ${known.join(', ')}.`);
+        this.name = 'UnknownSnippetError';
+    }
+}
+const SNIPPET_REFERENCE = /^snippet:\s*(\S+)$/;
+/**
+ * The `@example` blocks. `getDocumentationComment` returns the description only,
+ * so an example an author wrote is dropped unless the tags are read separately.
+ * An `@example snippet: name` names a region of real template source instead of
+ * restating it, and is resolved here so the shipped doc holds code that compiles.
+ */
+const examplesOf = (tags, symbolName, snippets) => tags
+    .filter((tag) => tag.name === 'example')
+    .map((tag) => ts.displayPartsToString(tag.text).trim())
+    .filter((text) => text.length > 0)
+    .map((text) => {
+    const reference = text.match(SNIPPET_REFERENCE);
+    if (!reference?.[1] || !snippets)
+        return text;
+    const snippet = snippets.get(reference[1]);
+    if (snippet === undefined) {
+        throw new UnknownSnippetError(reference[1], symbolName, [
+            ...snippets.keys(),
+        ]);
+    }
+    return snippet;
+});
 /**
  * The doc comment as written. A leaf re-exports through `export *`, so the
  * symbol reached here is an alias carrying no documentation of its own, and an
@@ -195,6 +235,25 @@ const documentationOf = (symbol, checker) => {
         if (documentation.length > 0)
             return documentation;
     }
+    return exportDeclarationDocumentationOf(symbol);
+};
+/**
+ * A re-export the generator documents (`export type { Services }`) carries its
+ * JSDoc on the export statement, which TypeScript attaches to no symbol at all
+ * — so it is read off the node.
+ */
+const exportDeclarationDocumentationOf = (symbol) => {
+    for (const declaration of symbol.declarations ?? []) {
+        if (!ts.isExportSpecifier(declaration))
+            continue;
+        const statement = declaration.parent.parent;
+        const [comment] = ts.getJSDocCommentsAndTags(statement);
+        if (!comment || !ts.isJSDoc(comment))
+            continue;
+        const documentation = ts.getTextOfJSDocComment(comment.comment)?.trim();
+        if (documentation && documentation.length > 0)
+            return documentation;
+    }
     return undefined;
 };
 /**
@@ -210,13 +269,250 @@ const summaryOf = (documentation) => {
         .trim();
 };
 const declarationFileOf = (symbol, checker) => {
-    const target = symbol.flags & ts.SymbolFlags.Alias
-        ? checker.getAliasedSymbol(symbol)
-        : symbol;
+    const target = aliasTargetOf(symbol, checker);
     const declaration = target.declarations?.[0] ?? symbol.declarations?.[0];
     return declaration?.getSourceFile().fileName ?? null;
 };
-export const collectSurface = async (packageDir, { importsSubpath, subpaths } = {}) => {
+/**
+ * `NoTruncation` is the load-bearing one: the default cuts a type off at ~160
+ * characters, which lands in the middle of the generics of every wiring helper.
+ * `UseAliasDefinedOutsideCurrentScope` keeps a named alias named instead of
+ * inlining its definition, which is what keeps the result readable.
+ */
+const SIGNATURE_FLAGS = ts.TypeFormatFlags.NoTruncation |
+    ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope |
+    ts.TypeFormatFlags.WriteTypeArgumentsOfSignature;
+const DECLARED_TYPE_KINDS = new Set(['interface', 'type']);
+const typeOfSymbol = (symbol, kind, checker) => {
+    if (DECLARED_TYPE_KINDS.has(kind))
+        return checker.getDeclaredTypeOfSymbol(symbol);
+    const declaration = symbol.declarations?.[0];
+    return declaration
+        ? checker.getTypeOfSymbolAtLocation(symbol, declaration)
+        : undefined;
+};
+const printType = (type, location, checker) => checker.typeToString(type, location, SIGNATURE_FLAGS).replace(/\s+/g, ' ');
+/**
+ * The widest an expanded type may print before its name is the better answer.
+ * A method verb or a content type says everything inline; a wiring object does
+ * not, and expanding it buries the keys that matter in the ones that do not.
+ */
+const INLINE_LIMIT = 72;
+const EXPANDED_FLAGS = SIGNATURE_FLAGS & ~ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope;
+const NOT_TERMINAL = /[{}]|=>/;
+const collapse = (constituents) => {
+    const collapsed = constituents.includes('true') && constituents.includes('false')
+        ? [
+            'boolean',
+            ...constituents.filter((c) => c !== 'true' && c !== 'false'),
+        ]
+        : constituents;
+    const isAbsent = (c) => c === 'undefined' || c === 'null';
+    return [
+        ...collapsed.filter((c) => !isAbsent(c)),
+        ...collapsed.filter(isAbsent),
+    ];
+};
+/**
+ * A named type whose definition is a short union or an index signature costs a
+ * reader a second lookup to learn something that fits on the line they are
+ * already reading, so it is printed as its values rather than its name.
+ */
+const printResolved = (type, location, checker, optional = false) => {
+    const constraint = type.flags & ts.TypeFlags.TypeParameter
+        ? checker.getBaseConstraintOfType(type)
+        : undefined;
+    if (constraint) {
+        return printResolved(constraint, location, checker, optional);
+    }
+    const named = printType(type, location, checker);
+    const expanded = type.isUnion()
+        ? collapse(type.types.map((constituent) => checker.typeToString(constituent, location, EXPANDED_FLAGS))).join(' | ')
+        : checker.typeToString(type, location, EXPANDED_FLAGS).replace(/\s+/g, ' ');
+    const shed = optional ? / \| undefined$/ : /(?!)/;
+    if (expanded === named || expanded.length > INLINE_LIMIT) {
+        return named.replace(shed, '');
+    }
+    return (NOT_TERMINAL.test(expanded) ? named : expanded).replace(shed, '');
+};
+/**
+ * A class prints as `typeof Foo`, which says nothing. Its construct signatures
+ * are what a caller needs, so they stand in for it.
+ */
+const constructorSignature = (name, type, checker) => {
+    const signatures = type.getConstructSignatures();
+    if (signatures.length === 0)
+        return undefined;
+    return signatures
+        .map((signature) => `new ${name}(${signature
+        .getParameters()
+        .map((parameter) => {
+        const declaration = parameter.valueDeclaration;
+        const parameterType = declaration
+            ? checker.getTypeOfSymbolAtLocation(parameter, declaration)
+            : checker.getTypeOfSymbol(parameter);
+        const optional = declaration &&
+            ts.isParameter(declaration) &&
+            declaration.questionToken
+            ? '?'
+            : '';
+        return `${parameter.getName()}${optional}: ${printResolved(parameterType, declaration, checker, optional === '?')}`;
+    })
+        .join(', ')})`)
+        .join(' | ');
+};
+const signatureOf = (name, type, kind, location, checker) => {
+    const printed = kind === 'class'
+        ? constructorSignature(name, type, checker)
+        : printType(type, location, checker);
+    if (!printed || printed === 'any' || printed === 'error' || printed === name)
+        return undefined;
+    return collapseRuns(printed);
+};
+/**
+ * A union parameterised by the project — every function name, every route —
+ * is unbounded and belongs to `pikku meta`, not to a framework doc that is the
+ * same for every project. Printed in full it buried one export under 4,000
+ * tokens of another project's identifiers.
+ */
+const LITERAL_RUN = /("[^"]*"(?: \| "[^"]*"){7,})/g;
+const collapseRuns = (line) => line.replace(LITERAL_RUN, (run) => `${run.split(' | ').length} names (pikku meta)`);
+/**
+ * A key declared by the project rather than by the framework — the services in
+ * its own `SingletonServices`, a type it wrote — is not part of the surface
+ * every project shares. Left in, the doc built from the sample project told
+ * every reader their singleton services hold a `todoStore`.
+ */
+const isProjectOwned = (declaration, root) => {
+    const file = declaration.getSourceFile().fileName;
+    return file.startsWith(root) && !file.includes('node_modules');
+};
+const memberLine = (property, checker, program, root) => {
+    if (property.getName().startsWith('__'))
+        return undefined;
+    const declaration = property.valueDeclaration ?? property.declarations?.[0];
+    if (declaration &&
+        (program.isSourceFileDefaultLibrary(declaration.getSourceFile()) ||
+            isProjectOwned(declaration, root))) {
+        return undefined;
+    }
+    const type = declaration
+        ? checker.getTypeOfSymbolAtLocation(property, declaration)
+        : checker.getTypeOfSymbol(property);
+    const optional = property.flags & ts.SymbolFlags.Optional ? '?' : '';
+    const doc = ts
+        .displayPartsToString(property.getDocumentationComment(checker))
+        .replace(/\s+/g, ' ')
+        .trim();
+    return {
+        line: collapseRuns(`${property.getName()}${optional}: ${printResolved(type, declaration, checker, optional === '?')}`),
+        ...(doc ? { doc } : {}),
+    };
+};
+/**
+ * Every wiring and function helper takes one options object, so its signature
+ * can only name that object's type and the keys someone has to write sit one
+ * level below it. Anything else describes itself.
+ */
+const shapeOf = (type, kind, checker) => {
+    if (kind === 'class') {
+        return type.getConstructSignatures()[0]?.getReturnType();
+    }
+    if (kind !== 'function' && kind !== 'const')
+        return type;
+    const signature = type.getCallSignatures()[0];
+    if (!signature)
+        return type;
+    for (const parameter of signature.getParameters()) {
+        const declaration = parameter.valueDeclaration;
+        const parameterType = declaration
+            ? checker.getTypeOfSymbolAtLocation(parameter, declaration)
+            : checker.getTypeOfSymbol(parameter);
+        if (checker.getPropertiesOfType(parameterType).length > 0)
+            return parameterType;
+    }
+    return undefined;
+};
+const membersOf = (type, kind, checker, program, root) => {
+    const shape = shapeOf(type, kind, checker);
+    if (!shape)
+        return [];
+    return checker
+        .getPropertiesOfType(shape)
+        .map((property) => memberLine(property, checker, program, root))
+        .filter((member) => member !== undefined)
+        .sort((a, b) => a.line.localeCompare(b.line));
+};
+/**
+ * `addError(SomeError, { status })` is a runtime registration, so nothing about
+ * a class says what it maps to. The calls are top-level statements next to the
+ * classes they register, which makes the mapping readable by parsing rather
+ * than by importing and booting the runtime.
+ *
+ * A surveyed project consumes pikku as `.d.ts`, and a declaration file carries
+ * no statements — the registrations survive only in the `.js` beside it, which
+ * is why the emitted sibling is parsed too.
+ */
+const collectErrorStatuses = (program) => {
+    const statuses = new Map();
+    const record = (name, details) => {
+        if (!ts.isIdentifier(name) || !ts.isObjectLiteralExpression(details))
+            return;
+        for (const property of details.properties) {
+            if (!ts.isPropertyAssignment(property))
+                continue;
+            if (property.name.getText() !== 'status')
+                continue;
+            const status = Number(property.initializer.getText());
+            if (Number.isFinite(status))
+                statuses.set(name.text, status);
+        }
+    };
+    const scan = (sourceFile) => {
+        for (const statement of sourceFile.statements) {
+            if (!ts.isExpressionStatement(statement))
+                continue;
+            const call = statement.expression;
+            if (!ts.isCallExpression(call) || !ts.isIdentifier(call.expression))
+                continue;
+            if (call.expression.text === 'addError') {
+                const [name, details] = call.arguments;
+                if (name && details)
+                    record(name, details);
+                continue;
+            }
+            if (call.expression.text !== 'addErrors')
+                continue;
+            const [list] = call.arguments;
+            if (!list || !ts.isArrayLiteralExpression(list))
+                continue;
+            for (const entry of list.elements) {
+                if (!ts.isArrayLiteralExpression(entry))
+                    continue;
+                const [name, details] = entry.elements;
+                if (name && details)
+                    record(name, details);
+            }
+        }
+    };
+    for (const sourceFile of program.getSourceFiles()) {
+        if (!sourceFile.isDeclarationFile) {
+            scan(sourceFile);
+            continue;
+        }
+        if (!sourceFile.text.includes('PikkuError'))
+            continue;
+        const emitted = sourceFile.fileName.replace(/\.d\.([cm]?ts)$/, '.$1');
+        if (emitted === sourceFile.fileName)
+            continue;
+        const source = ts.sys.readFile(emitted.replace(/\.ts$/, '.js'));
+        if (source === undefined)
+            continue;
+        scan(ts.createSourceFile(emitted, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.JS));
+    }
+    return statuses;
+};
+export const collectSurface = async (packageDir, { importsSubpath, subpaths, snippets } = {}) => {
     const root = resolve(packageDir);
     const packageJson = await readJson(join(root, 'package.json'));
     if (!packageJson)
@@ -275,6 +571,7 @@ export const collectSurface = async (packageDir, { importsSubpath, subpaths } =
         checkJs: false,
     });
     const checker = program.getTypeChecker();
+    const errorStatuses = collectErrorStatuses(program);
     return entries.map((entry) => {
         const sourceFile = program.getSourceFile(join(root, entry.entryFile));
         const moduleSymbol = sourceFile
@@ -287,15 +584,28 @@ export const collectSurface = async (packageDir, { importsSubpath, subpaths } =
             const file = declarationFileOf(symbol, checker);
             const kind = kindOf(symbol, checker);
             const docs = documentationOf(symbol, checker);
+            const tags = jsDocTagsOf(symbol, checker);
+            const name = symbol.getName();
+            const target = aliasTargetOf(symbol, checker);
+            const type = typeOfSymbol(target, kind, checker);
+            const location = target.declarations?.[0];
+            const examples = examplesOf(tags, name, snippets);
+            const members = type ? membersOf(type, kind, checker, program, root) : [];
             symbols.push({
-                name: symbol.getName(),
+                name,
                 kind,
                 declaredAt: file ? relative(root, file) : entry.entryFile,
                 declaredIn: file,
-                deprecated: isDeprecated(symbol),
-                deprecatedReason: deprecationReason(symbol),
+                deprecated: isDeprecated(tags),
+                deprecatedReason: deprecationReason(tags),
                 summary: summaryOf(docs),
                 docs,
+                signature: type
+                    ? signatureOf(name, type, kind, location, checker)
+                    : undefined,
+                members: members.length > 0 ? members : undefined,
+                examples: examples.length > 0 ? examples : undefined,
+                status: errorStatuses.get(name),
             });
         }
         return { ...entry, symbols };

package/dist/src/functions/surface/generate-surface-doc.js

@@ -1,15 +1,16 @@
-import { mkdir, writeFile } from 'node:fs/promises';
-import { dirname, resolve } from 'node:path';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getCLIVersion } from '../../utils/get-cli-version.js';
 import { buildSurfaceDoc } from './build-surface-doc.js';
+import { collectSnippets } from './collect-snippets.js';
 /**
  * Build-time entry point: `@pikku/cli` ships the surface doc, so it is computed
  * once when the CLI is built rather than by every project that consumes it.
  * `build.sh` generates the two projects it reads — one application, one addon —
  * and points this at them.
  */
-const usage = `Usage: generate-surface-doc --app <dir> --addon <dir> --out <file>`;
+const usage = `Usage: generate-surface-doc --app <dir> --addon <dir> --snippets <dir> --out <file> [--snippets-out <file>] [--snippets-meta-out <file>]`;
 const parseArgs = (argv) => {
     const parsed = {};
     for (let index = 0; index < argv.length; index += 2) {
@@ -22,19 +23,53 @@ const parseArgs = (argv) => {
     }
     return parsed;
 };
+/**
+ * The one region a marker cannot reach: `pikku.config.json` is parsed as strict
+ * JSON, so the scenario environments a doc has to show cannot be fenced in
+ * place. Read straight off the project's own config instead of being retyped.
+ */
+const addScenarioConfig = async (projectDir, snippets, origins) => {
+    try {
+        const config = JSON.parse(await readFile(join(projectDir, 'pikku.config.json'), 'utf8'));
+        if (!config.scenarios)
+            return;
+        snippets.set('scenarioConfig', JSON.stringify({ scenarios: config.scenarios }, null, 2));
+        origins.set('scenarioConfig', 'pikku.config.json');
+    }
+    catch {
+        return;
+    }
+};
 const main = async (argv) => {
     const args = parseArgs(argv);
-    const { app, addon, out } = args;
-    if (!app || !addon || !out)
+    const { app, addon, out, snippets: snippetsDir } = args;
+    const snippetsOut = args['snippets-out'];
+    if (!app || !addon || !out || !snippetsDir)
         throw new Error(usage);
+    const origins = new Map();
+    const snippets = await collectSnippets(resolve(snippetsDir), new Map(), origins);
+    await addScenarioConfig(resolve(snippetsDir), snippets, origins);
     const doc = await buildSurfaceDoc({
         version: getCLIVersion(),
         app: { projectDir: app },
         addon: { projectDir: addon },
+        snippets,
     });
     const outFile = resolve(out);
     await mkdir(dirname(outFile), { recursive: true });
     await writeFile(outFile, `${JSON.stringify(doc, null, 2)}\n`, 'utf8');
+    if (snippetsOut) {
+        const snippetsFile = resolve(snippetsOut);
+        await mkdir(dirname(snippetsFile), { recursive: true });
+        await writeFile(snippetsFile, `${JSON.stringify(Object.fromEntries([...snippets].sort()), null, 2)}\n`, 'utf8');
+        process.stdout.write(`  snippets: ${snippets.size}\n`);
+    }
+    const metaOut = args['snippets-meta-out'];
+    if (metaOut) {
+        const metaFile = resolve(metaOut);
+        await mkdir(dirname(metaFile), { recursive: true });
+        await writeFile(metaFile, `${JSON.stringify(Object.fromEntries([...origins].sort()), null, 2)}\n`, 'utf8');
+    }
     for (const entryPoint of doc.entryPoints) {
         const symbols = entryPoint.leaves.reduce((total, leaf) => total + leaf.symbols.length, 0);
         process.stdout.write(`  ${entryPoint.id}: ${entryPoint.leaves.length} leaves, ${symbols} exports\n`);

package/dist/src/functions/surface/render-surface-doc.d.ts

@@ -0,0 +1,12 @@
+import type { SurfaceDoc, SurfaceEntryPointId } from './surface-doc.types.js';
+export type RenderSurfaceDocOptions = {
+    target?: string;
+    ai?: boolean;
+    entryPoint?: SurfaceEntryPointId;
+};
+export declare class UnknownSurfaceTargetError extends Error {
+    readonly target: string;
+    readonly suggestions: string[];
+    constructor(target: string, suggestions: string[]);
+}
+export declare const renderSurfaceDoc: (doc: SurfaceDoc, { target, ai, entryPoint }?: RenderSurfaceDocOptions) => string;