@pikku/cli 0.12.105 → 0.12.107

package/dist/src/functions/runtimes/tanstack-start/pikku-command-tanstack-start.d.ts

@@ -1 +1 @@
-export declare const pikkuTanStackStart: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").WiredServices, unknown> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
+export declare const pikkuTanStackStart: import("#pikku/function").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<void, void, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;

package/dist/src/functions/runtimes/tanstack-start/pikku-command-tanstack-start.js

@@ -1,4 +1,4 @@
-import { pikkuSessionlessFunc } from '#pikku';
+import { pikkuSessionlessFunc } from '#pikku/function';
 import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
 import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';

package/dist/src/functions/runtimes/websocket/pikku-command-websocket-typed.d.ts

@@ -1 +1 @@
-export declare const pikkuWebSocketTyped: import("#pikku").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku").WiredServices, unknown> | import("#pikku").PikkuFunction<void, void, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
+export declare const pikkuWebSocketTyped: import("#pikku/function").PikkuFunctionConfig<void, void, "rpc" | "session", import("#pikku/function").PikkuFunctionSessionless<void, void, "rpc" | "session", import("#pikku/function").WiredServices, unknown> | import("#pikku/function").PikkuFunction<void, void, "rpc" | "session", import("#pikku/function").WiredServices>, undefined, undefined>;

package/dist/src/functions/runtimes/websocket/pikku-command-websocket-typed.js

@@ -1,4 +1,4 @@
-import { pikkuSessionlessFunc } from '#pikku';
+import { pikkuSessionlessFunc } from '#pikku/function';
 import { getFileImportRelativePath } from '../../../utils/file-import-path.js';
 import { writeFileInDir } from '../../../utils/file-writer.js';
 import { logCommandInfoAndTime } from '../../../middleware/log-command-info-and-time.js';

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

@@ -0,0 +1,22 @@
+import type { SurfaceDoc, SurfaceEntryPointId } from './surface-doc.types.js';
+/** The specifier an application reaches its generated leaves through. */
+export declare const PIKKU_IMPORTS_SUBPATH = "#pikku/*";
+export declare class MissingSurfaceEditorialError extends Error {
+    constructor(entryPoint: SurfaceEntryPointId, leaves: string[]);
+}
+/**
+ * A generated project — an application or an addon — whose `.pikku` tree has
+ * been written and whose package.json maps `#pikku/*` onto it.
+ */
+export type SurfaceProject = {
+    projectDir: string;
+    /** The generated tree, so a symbol declared inside it reads as `generated`. */
+    outDir?: string;
+};
+export type BuildSurfaceDocOptions = {
+    /** The `@pikku/cli` version the doc describes. */
+    version: string;
+    app: SurfaceProject;
+    addon: SurfaceProject;
+};
+export declare const buildSurfaceDoc: ({ version, app, addon, }: BuildSurfaceDocOptions) => Promise<SurfaceDoc>;

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

@@ -0,0 +1,151 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { collectSurface } from './collect-surface.js';
+import { ENTRY_POINT_EDITORIAL, LEAF_EDITORIAL, } from './surface-editorial.js';
+/** The specifier an application reaches its generated leaves through. */
+export const PIKKU_IMPORTS_SUBPATH = '#pikku/*';
+const CORE_PACKAGE_NAME = '@pikku/core';
+const STEP_ORDER = [
+    'create a function',
+    'enhance it',
+    'wire it up',
+    'guard it',
+    'orchestrate it',
+    'test it',
+];
+export class MissingSurfaceEditorialError extends Error {
+    constructor(entryPoint, leaves) {
+        super(`The ${entryPoint} surface has ${leaves.length} leaf${leaves.length === 1 ? '' : 'es'} with no editorial entry: ${leaves.join(', ')}. Add ${leaves.length === 1 ? 'it' : 'them'} to LEAF_EDITORIAL in src/functions/surface/surface-editorial.ts.`);
+        this.name = 'MissingSurfaceEditorialError';
+    }
+}
+const readPackageJson = (path) => {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+};
+const nearestPackage = (file) => {
+    let directory = dirname(file);
+    for (;;) {
+        const candidate = join(directory, 'package.json');
+        if (existsSync(candidate)) {
+            const packageJson = readPackageJson(candidate);
+            if (packageJson?.name)
+                return { dir: directory, packageJson };
+        }
+        const parent = dirname(directory);
+        if (parent === directory)
+            return null;
+        directory = parent;
+    }
+};
+const isInside = (parent, child) => {
+    const rel = relative(parent, child);
+    return rel.length > 0 && !rel.startsWith('..') && !rel.startsWith(sep);
+};
+/**
+ * Which `@pikku/core` subpath a declaration sits behind. The declaring file is
+ * usually deeper than the entry the leaf re-exported — `wireHTTP` is declared in
+ * `src/wirings/http/http-runner.ts`, not in the `./http` entry — so the longest
+ * declared subpath that prefixes the path wins, and the package root is the
+ * answer when none does.
+ */
+const coreSubpathOf = (packageDir, packageJson, file) => {
+    const declared = new Set(Object.keys(packageJson.exports ?? {}).filter((key) => key.startsWith('./') && !key.includes('*')));
+    const segments = relative(packageDir, file)
+        .split(sep)
+        .filter((segment) => segment !== 'src' && segment !== 'dist');
+    // Wirings live one directory down from the subpath that publishes them.
+    const meaningful = segments[0] === 'wirings' ? segments.slice(1) : segments;
+    for (let length = Math.min(meaningful.length, 2); length > 0; length--) {
+        const candidate = `./${meaningful.slice(0, length).join('/')}`;
+        if (declared.has(candidate))
+            return candidate;
+    }
+    return '.';
+};
+const originOf = (declaredIn, generatedRoot) => {
+    if (!declaredIn)
+        return { via: 'generated' };
+    if (generatedRoot && isInside(generatedRoot, declaredIn)) {
+        return { via: 'generated' };
+    }
+    const owner = nearestPackage(declaredIn);
+    if (!owner)
+        return { via: 'generated' };
+    const packageName = owner.packageJson.name;
+    if (packageName === CORE_PACKAGE_NAME) {
+        return {
+            via: 'core',
+            subpath: coreSubpathOf(owner.dir, owner.packageJson, declaredIn),
+        };
+    }
+    return { via: 'package', packageName };
+};
+const toDocSymbols = (entrypoint, generatedRoot) => [...entrypoint.symbols]
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((symbol) => ({
+    name: symbol.name,
+    kind: symbol.kind,
+    origin: originOf(symbol.declaredIn, generatedRoot),
+    ...(symbol.summary ? { summary: symbol.summary } : {}),
+    ...(symbol.docs ? { docs: symbol.docs } : {}),
+    ...(symbol.deprecated
+        ? { deprecated: symbol.deprecatedReason ?? 'Deprecated' }
+        : {}),
+}));
+const byStepThenName = (a, b) => STEP_ORDER.indexOf(a.step) - STEP_ORDER.indexOf(b.step) ||
+    a.name.localeCompare(b.name);
+const leafNameOf = (subpath) => subpath
+    .replace(/^#pikku\//, '')
+    .replace(/^\.\//, '')
+    // An addon's whole tree roots under `addon/`, so the prefix locates a leaf
+    // rather than naming one — `#pikku/addon/http` is the http leaf as an addon
+    // reaches it. The application's install leaf is bare `addon` and stays.
+    .replace(/^addon\/(?=.)/, '');
+const toLeaves = (entryPoint, entrypoints, editorial, generatedRoot) => {
+    const leaves = [];
+    const missing = [];
+    for (const entrypoint of entrypoints) {
+        const name = leafNameOf(entrypoint.subpath);
+        const copy = editorial(entrypoint.subpath);
+        if (!copy) {
+            missing.push(name);
+            continue;
+        }
+        leaves.push({
+            specifier: entrypoint.specifier,
+            name,
+            step: copy.step,
+            summary: copy.summary,
+            symbols: toDocSymbols(entrypoint, generatedRoot),
+        });
+    }
+    if (missing.length > 0) {
+        throw new MissingSurfaceEditorialError(entryPoint, missing.sort());
+    }
+    return leaves.sort(byStepThenName);
+};
+const projectEntryPoint = async (id, project) => {
+    const projectDir = resolve(project.projectDir);
+    const generatedRoot = resolve(project.outDir ?? join(projectDir, '.pikku'));
+    const entrypoints = await collectSurface(projectDir, {
+        importsSubpath: PIKKU_IMPORTS_SUBPATH,
+    });
+    return {
+        id,
+        ...ENTRY_POINT_EDITORIAL[id],
+        specifierBase: '#pikku',
+        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),
+    ],
+});

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

@@ -0,0 +1,16 @@
+import type { SurfaceUsageCounts } from '@pikku/inspector';
+import type { SurfaceDoc, SurfaceUsage } from './surface-doc.types.js';
+export type MergeSurfaceUsageOptions = {
+    /** Counted by the inspector during the sweep it already makes. */
+    counts: SurfaceUsageCounts;
+    /**
+     * Seeds the result, so an export nothing imports is reported as `imports: 0`
+     * rather than being absent. Without it only what was seen is reported.
+     */
+    doc?: SurfaceDoc;
+};
+/**
+ * The per-project overlay: the inspector's raw counters, seeded with every
+ * export the shipped doc describes and given a stable ordering.
+ */
+export declare const mergeSurfaceUsage: ({ counts, doc, }: MergeSurfaceUsageOptions) => SurfaceUsage;

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

@@ -0,0 +1,35 @@
+/**
+ * The per-project overlay: the inspector's raw counters, seeded with every
+ * export the shipped doc describes and given a stable ordering.
+ */
+export const mergeSurfaceUsage = ({ counts, doc, }) => {
+    const bySpecifier = {};
+    for (const entryPoint of doc?.entryPoints ?? []) {
+        for (const leaf of entryPoint.leaves) {
+            if (!leaf.specifier.startsWith('#pikku/'))
+                continue;
+            const symbols = (bySpecifier[leaf.specifier] ??= {});
+            for (const symbol of leaf.symbols) {
+                symbols[symbol.name] ??= { imports: 0, seenIn: [], files: [] };
+            }
+        }
+    }
+    for (const [specifier, symbols] of Object.entries(counts)) {
+        const merged = (bySpecifier[specifier] ??= {});
+        for (const [name, usage] of Object.entries(symbols)) {
+            merged[name] = {
+                imports: usage.imports,
+                seenIn: [...usage.seenIn].sort(),
+                files: [...usage.files].sort(),
+            };
+        }
+    }
+    return {
+        bySpecifier: Object.fromEntries(Object.entries(bySpecifier)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([specifier, symbols]) => [
+            specifier,
+            Object.fromEntries(Object.entries(symbols).sort(([a], [b]) => a.localeCompare(b))),
+        ])),
+    };
+};

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

@@ -3,7 +3,15 @@ export type SurfaceSymbol = {
     name: string;
     kind: SurfaceKind;
     declaredAt: string;
+    /** Absolute path of the declaring file, or null when it could not be found. */
+    declaredIn: string | null;
     deprecated: boolean;
+    /** The text of the `@deprecated` tag, when it carries one. */
+    deprecatedReason?: string;
+    /** First paragraph of the symbol's JSDoc. */
+    summary?: string;
+    /** The symbol's JSDoc in full, paragraphs and examples included. */
+    docs?: string;
 };
 export type SurfaceEntrypoint = {
     subpath: string;
@@ -11,4 +19,14 @@ export type SurfaceEntrypoint = {
     entryFile: string;
     symbols: SurfaceSymbol[];
 };
-export declare const collectSurface: (packageDir: string) => Promise<SurfaceEntrypoint[]>;
+export type CollectSurfaceOptions = {
+    /**
+     * Read the package's `imports` map instead of its `exports` map, taking the
+     * one key given — `#pikku/*` is what an application reaches its generated
+     * leaves through, and it is a private specifier rather than a published one.
+     */
+    importsSubpath?: string;
+    /** Restrict collection to these subpaths, so the program stays small. */
+    subpaths?: string[];
+};
+export declare const collectSurface: (packageDir: string, { importsSubpath, subpaths }?: CollectSurfaceOptions) => Promise<SurfaceEntrypoint[]>;

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

@@ -44,10 +44,19 @@ const sourceForTarget = (packageDir, target, outDir) => {
     }
     return null;
 };
-const expandWildcard = (packageDir, subpath, target) => {
+const expandWildcard = (packageDir, subpath, target, outDir) => {
     const targetDir = target.replace(/^\.\//, '').split('*')[0] ?? '';
     const suffix = target.slice(target.indexOf('*') + 1);
-    const absolute = join(packageDir, targetDir);
+    const suffixStem = wildcardStem(suffix) ?? suffix;
+    // A package that points its subpaths at the build output has nothing to walk
+    // until it is built, so the sources the output would be compiled from stand
+    // in for it. `sourceForTarget` strips the same prefix, so the target stays
+    // the declared one and only the directory being read changes.
+    const scanDir = existsSync(join(packageDir, targetDir)) ||
+        !targetDir.startsWith(`${outDir}/`)
+        ? targetDir
+        : targetDir.slice(outDir.length + 1);
+    const absolute = join(packageDir, scanDir);
     if (!existsSync(absolute))
         return [];
     const expanded = [];
@@ -59,14 +68,25 @@ const expandWildcard = (packageDir, subpath, target) => {
             }
             if (!entry.isFile())
                 continue;
-            if (suffix && !entry.name.endsWith(suffix))
+            if (wildcardStem(entry.name) === null)
                 continue;
-            const stem = wildcardStem(entry.name);
-            if (stem === null)
+            // The suffix is matched against the path the wildcard stands in for, not
+            // the file name, so `#pikku/*` → `./.pikku/*/index.ts` captures the leaf
+            // directory rather than failing to match `index.ts` against `/index.ts`.
+            const relativePath = `${prefix}${entry.name}`;
+            // Matched without extensions, so a `*/index.js` target still finds the
+            // `index.ts` it would have been compiled from.
+            const pathStem = `${prefix}${wildcardStem(entry.name)}`;
+            if (suffixStem && !pathStem.endsWith(suffixStem))
+                continue;
+            const captured = suffixStem
+                ? pathStem.slice(0, -suffixStem.length)
+                : pathStem;
+            if (!captured)
                 continue;
             expanded.push({
-                subpath: subpath.replace('*', `${prefix}${stem}`),
-                target: `${targetDir}${prefix}${entry.name}`,
+                subpath: subpath.replace('*', captured),
+                target: `${scanDir}${relativePath}`,
             });
         }
     };
@@ -76,6 +96,16 @@ const expandWildcard = (packageDir, subpath, target) => {
 const targetOf = (value) => {
     if (typeof value === 'string')
         return value;
+    // A fallback array declares the same specifier several ways; the first entry
+    // is the one a resolver reaches for, and the rest only matter when it misses.
+    if (Array.isArray(value)) {
+        for (const candidate of value) {
+            const resolved = targetOf(candidate);
+            if (resolved)
+                return resolved;
+        }
+        return null;
+    }
     if (!value || typeof value !== 'object')
         return null;
     const conditions = value;
@@ -140,6 +170,45 @@ 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');
+    if (!tag)
+        return undefined;
+    const text = ts.displayPartsToString(tag.text).trim();
+    return text.length > 0 ? text : undefined;
+};
+/**
+ * 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
+ * overloaded function documents whichever overload the author chose to explain
+ * — hence the walk through the aliased symbol and then every declaration.
+ */
+const documentationOf = (symbol, checker) => {
+    const targets = [symbol];
+    if (symbol.flags & ts.SymbolFlags.Alias) {
+        targets.push(checker.getAliasedSymbol(symbol));
+    }
+    for (const target of targets) {
+        const documentation = ts
+            .displayPartsToString(target.getDocumentationComment(checker))
+            .trim();
+        if (documentation.length > 0)
+            return documentation;
+    }
+    return undefined;
+};
+/**
+ * The first paragraph of the doc comment. A symbol's JSDoc regularly runs to
+ * several paragraphs of examples, and a list row shows one line.
+ */
+const summaryOf = (documentation) => {
+    if (!documentation)
+        return undefined;
+    return documentation
+        .split(/\n\s*\n/)[0]
+        .replace(/\s+/g, ' ')
+        .trim();
+};
 const declarationFileOf = (symbol, checker) => {
     const target = symbol.flags & ts.SymbolFlags.Alias
         ? checker.getAliasedSymbol(symbol)
@@ -147,34 +216,47 @@ const declarationFileOf = (symbol, checker) => {
     const declaration = target.declarations?.[0] ?? symbol.declarations?.[0];
     return declaration?.getSourceFile().fileName ?? null;
 };
-export const collectSurface = async (packageDir) => {
+export const collectSurface = async (packageDir, { importsSubpath, subpaths } = {}) => {
     const root = resolve(packageDir);
     const packageJson = await readJson(join(root, 'package.json'));
-    if (!packageJson?.exports)
+    if (!packageJson)
+        return [];
+    const declaredMap = importsSubpath
+        ? packageJson.imports?.[importsSubpath] !== undefined
+            ? { [importsSubpath]: packageJson.imports[importsSubpath] }
+            : {}
+        : packageJson.exports
+            ? subpathMap(packageJson.exports)
+            : {};
+    if (Object.keys(declaredMap).length === 0)
         return [];
     const { outDir, paths } = await readCompilerOptions(root);
     const packageName = packageJson.name ?? '';
     const entries = [];
     const seenEntryFiles = new Set();
-    for (const [subpath, value] of Object.entries(subpathMap(packageJson.exports))) {
-        if (!subpath.startsWith('.'))
+    for (const [subpath, value] of Object.entries(declaredMap)) {
+        if (!importsSubpath && !subpath.startsWith('.'))
             continue;
         const target = targetOf(value);
         if (!target || !publishesCode(target))
             continue;
         const declared = target.includes('*')
-            ? expandWildcard(root, subpath, target)
+            ? expandWildcard(root, subpath, target, outDir)
             : [{ subpath, target }];
         for (const each of declared) {
+            if (subpaths && !subpaths.includes(each.subpath))
+                continue;
             const entryFile = sourceForTarget(root, each.target, outDir);
             if (!entryFile || seenEntryFiles.has(entryFile))
                 continue;
             seenEntryFiles.add(entryFile);
             entries.push({
                 subpath: each.subpath,
-                specifier: each.subpath === '.'
-                    ? packageName
-                    : `${packageName}${each.subpath.slice(1)}`,
+                specifier: importsSubpath
+                    ? each.subpath
+                    : each.subpath === '.'
+                        ? packageName
+                        : `${packageName}${each.subpath.slice(1)}`,
                 entryFile,
             });
         }
@@ -203,11 +285,17 @@ export const collectSurface = async (packageDir) => {
             ? checker.getExportsOfModule(moduleSymbol)
             : []) {
             const file = declarationFileOf(symbol, checker);
+            const kind = kindOf(symbol, checker);
+            const docs = documentationOf(symbol, checker);
             symbols.push({
                 name: symbol.getName(),
-                kind: kindOf(symbol, checker),
+                kind,
                 declaredAt: file ? relative(root, file) : entry.entryFile,
+                declaredIn: file,
                 deprecated: isDeprecated(symbol),
+                deprecatedReason: deprecationReason(symbol),
+                summary: summaryOf(docs),
+                docs,
             });
         }
         return { ...entry, symbols };

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,46 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getCLIVersion } from '../../utils/get-cli-version.js';
+import { buildSurfaceDoc } from './build-surface-doc.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 parseArgs = (argv) => {
+    const parsed = {};
+    for (let index = 0; index < argv.length; index += 2) {
+        const flag = argv[index];
+        const value = argv[index + 1];
+        if (!flag?.startsWith('--') || value === undefined) {
+            throw new Error(usage);
+        }
+        parsed[flag.slice(2)] = value;
+    }
+    return parsed;
+};
+const main = async (argv) => {
+    const args = parseArgs(argv);
+    const { app, addon, out } = args;
+    if (!app || !addon || !out)
+        throw new Error(usage);
+    const doc = await buildSurfaceDoc({
+        version: getCLIVersion(),
+        app: { projectDir: app },
+        addon: { projectDir: addon },
+    });
+    const outFile = resolve(out);
+    await mkdir(dirname(outFile), { recursive: true });
+    await writeFile(outFile, `${JSON.stringify(doc, 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`);
+    }
+};
+if (process.argv[1] &&
+    resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    await main(process.argv.slice(2));
+}

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

@@ -0,0 +1,16 @@
+import type { SurfaceDoc } from './surface-doc.types.js';
+/** The name the doc is published under, inside the `@pikku/cli` package. */
+export declare const SURFACE_DOC_FILE = "surface.json";
+/**
+ * Where the shipped surface doc lives. It sits at the root of the `@pikku/cli`
+ * package, so a consumer outside this repository resolves it as
+ * `@pikku/cli/surface.json` — from in here the package root has to be walked to,
+ * because this module runs both from `src` and from `dist/src`.
+ */
+export declare const shippedSurfaceDocPath: () => string | null;
+/**
+ * The doc is built with the CLI, so a CLI running out of a source checkout that
+ * has never been built has none. That is a reason to skip seeding the usage
+ * overlay, not a reason to fail a prebuild.
+ */
+export declare const readShippedSurfaceDoc: () => SurfaceDoc | null;

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

@@ -0,0 +1,44 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** The name the doc is published under, inside the `@pikku/cli` package. */
+export const SURFACE_DOC_FILE = 'surface.json';
+/**
+ * Where the shipped surface doc lives. It sits at the root of the `@pikku/cli`
+ * package, so a consumer outside this repository resolves it as
+ * `@pikku/cli/surface.json` — from in here the package root has to be walked to,
+ * because this module runs both from `src` and from `dist/src`.
+ */
+export const shippedSurfaceDocPath = () => {
+    let directory = dirname(fileURLToPath(import.meta.url));
+    for (;;) {
+        // The first package.json above this module is the CLI's own, whether it is
+        // running from `src` or from `dist/src`. Stopping there rather than looking
+        // for the file itself keeps the search from wandering into a consumer's
+        // project and finding an unrelated surface.json.
+        if (existsSync(join(directory, 'package.json'))) {
+            const path = join(directory, SURFACE_DOC_FILE);
+            return existsSync(path) ? path : null;
+        }
+        const parent = dirname(directory);
+        if (parent === directory)
+            return null;
+        directory = parent;
+    }
+};
+/**
+ * The doc is built with the CLI, so a CLI running out of a source checkout that
+ * has never been built has none. That is a reason to skip seeding the usage
+ * overlay, not a reason to fail a prebuild.
+ */
+export const readShippedSurfaceDoc = () => {
+    const path = shippedSurfaceDocPath();
+    if (!path)
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+};

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

@@ -0,0 +1,69 @@
+import type { SurfaceKind } from './collect-surface.js';
+export type { SurfaceKind };
+/**
+ * The order in which you meet these doors while building a service. It is the
+ * page's spine: the console groups by it and the reading order follows it.
+ */
+export type SurfaceStep = 'create a function' | 'enhance it' | 'wire it up' | 'guard it' | 'orchestrate it' | 'test it';
+export type SurfaceOrigin = {
+    via: 'generated';
+} | {
+    via: 'core';
+    subpath: string;
+} | {
+    via: 'package';
+    packageName: string;
+};
+export type SurfaceDocSymbol = {
+    name: string;
+    kind: SurfaceKind;
+    origin: SurfaceOrigin;
+    /** One line, for a list row. */
+    summary?: string;
+    /** The full documentation, for the panel that reads one export. */
+    docs?: string;
+    deprecated?: string;
+};
+export type SurfaceLeaf = {
+    /** The specifier you import from, e.g. `#pikku/http`. */
+    specifier: string;
+    name: string;
+    step: SurfaceStep;
+    summary: string;
+    symbols: SurfaceDocSymbol[];
+};
+export type SurfaceEntryPointId = 'app' | 'addon';
+export type SurfaceEntryPoint = {
+    id: SurfaceEntryPointId;
+    /** What someone reaching for this entry point is trying to do. */
+    job: string;
+    specifierBase: string;
+    summary: string;
+    leaves: SurfaceLeaf[];
+};
+/**
+ * Metadata about the framework itself rather than about any one project: which
+ * leaves an application gets, which an addon gets, and what each one exports.
+ * It is computed when `@pikku/cli` is built and published inside it, so a
+ * consumer reads it at `@pikku/cli/surface.json` without generating anything.
+ */
+export type SurfaceDoc = {
+    /** The `@pikku/cli` version this surface was computed from. */
+    version: string;
+    entryPoints: SurfaceEntryPoint[];
+};
+export type SurfaceSymbolUsage = {
+    imports: number;
+    /** The workspace packages or top-level source directories it is imported in. */
+    seenIn: string[];
+    /** The project-relative files the imports are written in. */
+    files: string[];
+};
+/**
+ * Measured usage, keyed by specifier and then by export name. It is per-project
+ * and written at prebuild time, so the console has it and the website does not
+ * — every affordance that reads it is optional.
+ */
+export type SurfaceUsage = {
+    bySpecifier: Record<string, Record<string, SurfaceSymbolUsage>>;
+};

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

@@ -0,0 +1 @@
+export {};