@pikku/cli 0.12.104 → 0.12.107

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 {};

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

@@ -0,0 +1,25 @@
+import type { SurfaceEntryPointId, SurfaceStep } from './surface-doc.types.js';
+/**
+ * This file is prose, not derived data. Every other field of the surface doc is
+ * computed from the generated output, because the barrel is the source of truth
+ * for what a leaf exports — but which of the six steps a leaf belongs to, and
+ * the sentence that says what it is for, is a judgement no parser can make.
+ *
+ * A leaf with no entry here fails the build rather than defaulting to something
+ * bland, so a new leaf cannot ship undocumented.
+ */
+export type LeafEditorial = {
+    step: SurfaceStep;
+    summary: string;
+};
+export type EntryPointEditorial = {
+    job: string;
+    summary: string;
+};
+/**
+ * Keyed by leaf name — the segment after `#pikku/`. Shared by the application
+ * and addon entry points, which differ in which leaves they have rather than in
+ * what a leaf is for.
+ */
+export declare const LEAF_EDITORIAL: Record<string, LeafEditorial>;
+export declare const ENTRY_POINT_EDITORIAL: Record<SurfaceEntryPointId, EntryPointEditorial>;

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

@@ -0,0 +1,101 @@
+/**
+ * Keyed by leaf name — the segment after `#pikku/`. Shared by the application
+ * and addon entry points, which differ in which leaves they have rather than in
+ * what a leaf is for.
+ */
+export const LEAF_EDITORIAL = {
+    setup: {
+        step: 'create a function',
+        summary: 'The three factories a project declares exactly once — its config, its singleton services and its per-wire services. An addon declares the same three in its own flavour, handed the logger, variables and secrets the host application already built. Everything else on this page is imported by features; these are imported by bootstrap and then left alone.',
+    },
+    function: {
+        step: 'create a function',
+        summary: 'The function definers every wiring eventually points at, and the types they are written against.',
+    },
+    middleware: {
+        step: 'enhance it',
+        summary: 'Middleware is one concept regardless of what it ends up attached to, so it is one import: define it here, then register it globally, against a tag, or against an HTTP route or channel.',
+    },
+    error: {
+        step: 'enhance it',
+        summary: 'The errors your functions throw and the HTTP status each one maps to, so a thrown error is part of the contract rather than a stack trace.',
+    },
+    variables: {
+        step: 'enhance it',
+        summary: 'Configuration a function reads through the variables service, declared once so a deployment can be checked for what it is missing.',
+    },
+    secrets: {
+        step: 'enhance it',
+        summary: 'Secrets a function can use without ever holding, declared here and resolved by the secrets service at runtime.',
+    },
+    credentials: {
+        step: 'enhance it',
+        summary: 'Third-party credentials — OAuth2 grants and API keys — declared so the runtime can acquire, refresh and inject them.',
+    },
+    addon: {
+        step: 'enhance it',
+        summary: 'Installs an addon into this application, on its own or over rpc against a remote one.',
+    },
+    http: {
+        step: 'wire it up',
+        summary: 'Wires a function to an HTTP route, with the path parameters checked against the function input.',
+    },
+    channel: {
+        step: 'wire it up',
+        summary: 'Wires a function to a websocket channel, its message routes and its pub/sub topics.',
+    },
+    queue: {
+        step: 'wire it up',
+        summary: 'Wires a function as a queue worker, so a job on the queue runs the same handler an HTTP route would.',
+    },
+    scheduler: {
+        step: 'wire it up',
+        summary: 'Wires a function to a cron expression to run it on a schedule.',
+    },
+    trigger: {
+        step: 'wire it up',
+        summary: 'Wires a function to an event a source emits, rather than to a caller that asks for it.',
+    },
+    gateway: {
+        step: 'wire it up',
+        summary: 'Wires a function behind a gateway that receives requests on behalf of another system.',
+    },
+    mcp: {
+        step: 'wire it up',
+        summary: 'Wires a function as an MCP tool, resource or prompt for a model to call.',
+    },
+    cli: {
+        step: 'wire it up',
+        summary: 'Wires a function as a command, with its flags and arguments derived from the function input.',
+    },
+    auth: {
+        step: 'guard it',
+        summary: 'Who may call a function, and what the call is made with: permissions that see the request, auth gates that run before it, and the credentials a function borrows rather than holds.',
+    },
+    scopes: {
+        step: 'guard it',
+        summary: 'The scopes a caller can hold and the roles that grant them, gating a call outside the permission pool.',
+    },
+    workflow: {
+        step: 'orchestrate it',
+        summary: 'Composes functions into a durable workflow whose steps survive a restart and retry on their own.',
+    },
+    agent: {
+        step: 'orchestrate it',
+        summary: 'Defines an AI agent, the tools it may call and the scorers that judge what it did.',
+    },
+    scenarios: {
+        step: 'test it',
+        summary: 'Drives features and scenarios against a real running server, in the vocabulary a user would use.',
+    },
+};
+export const ENTRY_POINT_EDITORIAL = {
+    app: {
+        job: 'build an app',
+        summary: 'This is the door you open to build a service. The CLI generates a barrel per concern into .pikku, package.json maps #pikku onto it, and everything below runs in the order you actually meet it while building — write a function, give it what it needs, decide how the world reaches it, say who may call it, compose it, then drive the whole thing in a test.',
+    },
+    addon: {
+        job: 'build an addon',
+        summary: 'An addon declares functions and contracts; the host application decides how the world reaches them. The same barrels are generated under #pikku/addon/*, minus every wiring — an addon that called wireHTTP would be registering a route in a registry it does not own.',
+    },
+};

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

@@ -0,0 +1,12 @@
+import type { SurfaceUsageCounts } from '@pikku/inspector';
+import type { CLILogger } from '../../services/cli-logger.service.js';
+export declare const SURFACE_USAGE_FILE = "surface-usage.gen.json";
+/**
+ * The per-project half of the surface: which of the exports the shipped doc
+ * describes this project actually imports, and where. The counting itself is
+ * free — the inspector does it inside the sweep it already makes over every
+ * source file — so all that happens here is a merge and a write.
+ */
+export declare const writeSurfaceUsage: (logger: CLILogger, config: {
+    outDir: string;
+}, counts: SurfaceUsageCounts) => Promise<void>;

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

@@ -0,0 +1,18 @@
+import { join } from 'node:path';
+import { writeFileInDir } from '../../utils/file-writer.js';
+import { mergeSurfaceUsage } from './collect-surface-usage.js';
+import { readShippedSurfaceDoc } from './shipped-surface-doc.js';
+export const SURFACE_USAGE_FILE = 'surface-usage.gen.json';
+/**
+ * The per-project half of the surface: which of the exports the shipped doc
+ * describes this project actually imports, and where. The counting itself is
+ * free — the inspector does it inside the sweep it already makes over every
+ * source file — so all that happens here is a merge and a write.
+ */
+export const writeSurfaceUsage = async (logger, config, counts) => {
+    const usage = mergeSurfaceUsage({
+        counts,
+        doc: readShippedSurfaceDoc() ?? undefined,
+    });
+    await writeFileInDir(logger, join(config.outDir, SURFACE_USAGE_FILE), JSON.stringify(usage, null, 2));
+};

package/dist/src/functions/validate/pikku-barrel-checks.d.ts

@@ -0,0 +1,12 @@
+import type { ValidateFinding } from './persona-checks.js';
+/**
+ * `#pikku` is the app tier's only door onto Pikku, and it is a namespace rather
+ * than a module: `#pikku/http`, `#pikku/workflow`, one subpath per wiring.
+ *
+ * The bare specifier used to resolve to a hub that re-exported every wiring
+ * leaf with `export *`, undoing the split the leaves exist for. Neither
+ * consumer could drop the result again: bundlers keep `export *` chains unless
+ * the package declares `sideEffects`, and Node and tsx do not tree-shake at
+ * all — so an app with no queues still executed `@pikku/core/queue` at boot.
+ */
+export declare const runPikkuBarrelChecks: (dir: string) => Promise<ValidateFinding[]>;

package/dist/src/functions/validate/pikku-barrel-checks.js

@@ -0,0 +1,97 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import ts from 'typescript';
+const SKIP_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    '.pikku',
+    '.pikku-runtime',
+    'coverage',
+    '.next',
+    '.yarn',
+]);
+const SOURCE_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts'];
+/**
+ * `.gen.*` and `.d.ts` are the generator's own output — what they import is
+ * decided by the codegen templates, not by the project.
+ */
+const isGenerated = (path) => path.includes('.gen.') || path.endsWith('.d.ts');
+/**
+ * The specifiers that reach the retired re-export hub: the bare namespace, and
+ * the hub as a deep file. Every other `#pikku/*` is a leaf or a generated
+ * client and resolves to exactly what it names.
+ */
+const isBarrel = (specifier) => specifier === '#pikku' || /^#pikku\/pikku-types\.gen(\.js)?$/.test(specifier);
+/**
+ * Parsed rather than grepped: a project's own codegen templates hold the
+ * specifiers they emit inside template literals, and those are output text
+ * rather than imports the file itself makes.
+ */
+const barrelImports = (file, content) => {
+    const source = ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true);
+    const found = [];
+    for (const statement of source.statements) {
+        if (!ts.isImportDeclaration(statement) &&
+            !ts.isExportDeclaration(statement)) {
+            continue;
+        }
+        const moduleSpecifier = statement.moduleSpecifier;
+        if (!moduleSpecifier || !ts.isStringLiteral(moduleSpecifier))
+            continue;
+        if (isBarrel(moduleSpecifier.text))
+            found.push(moduleSpecifier.text);
+    }
+    return found;
+};
+const collectSources = async (dir, out = []) => {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (SKIP_DIRS.has(entry.name) || entry.name.startsWith('.'))
+                continue;
+            await collectSources(path, out);
+        }
+        else if (SOURCE_EXTENSIONS.some((ext) => entry.name.endsWith(ext)) &&
+            !isGenerated(entry.name)) {
+            out.push(path);
+        }
+    }
+    return out;
+};
+/**
+ * `#pikku` is the app tier's only door onto Pikku, and it is a namespace rather
+ * than a module: `#pikku/http`, `#pikku/workflow`, one subpath per wiring.
+ *
+ * The bare specifier used to resolve to a hub that re-exported every wiring
+ * leaf with `export *`, undoing the split the leaves exist for. Neither
+ * consumer could drop the result again: bundlers keep `export *` chains unless
+ * the package declares `sideEffects`, and Node and tsx do not tree-shake at
+ * all — so an app with no queues still executed `@pikku/core/queue` at boot.
+ */
+export const runPikkuBarrelChecks = async (dir) => {
+    const findings = [];
+    for (const file of await collectSources(dir)) {
+        const content = await readFile(file, 'utf8');
+        if (!content.includes('#pikku'))
+            continue;
+        for (const specifier of barrelImports(file, content)) {
+            findings.push({
+                id: 'pikku-barrel-import',
+                severity: 'error',
+                message: `${relative(dir, file)} imports '${specifier}' — the app tier reaches Pikku through one subpath per wiring, and a barrel pulls every wiring's core dependencies into the module graph`,
+                path: file,
+                fixHint: "Import from the leaf the name belongs to — '#pikku/function' for pikkuFunc, '#pikku/http' for wireHTTP, '#pikku/workflow' for workflow wiring",
+            });
+        }
+    }
+    return findings;
+};

package/dist/src/functions/validate/scenario-file-checks.js

@@ -44,7 +44,7 @@ const VIRTUAL_USER_FILE = /\.(virtual-user|vu)\.tsx?$/;
  * are edited for opposite reasons, and a rubric buried in an agent definition
  * is one nobody reviews as a rubric.
  */
-const SCORER_DECLARATIONS = ['pikkuAIScorer', 'pikkuAIJudge'];
+const SCORER_DECLARATIONS = ['pikkuAgentScorer', 'pikkuAgentJudge'];
 const SCORER_FILE = /\.scorers?\.tsx?$/;
 const isGenerated = (path) => path.includes('.gen.') || path.includes(`${'/'}.pikku${'/'}`);
 const listSourceFiles = async (dir) => {

package/dist/src/functions/validate/shared-checks.d.ts

@@ -45,6 +45,16 @@ export type SharedCheckResult = {
  */
 export declare function readJsonSafe<T>(path: string): Promise<T | null>;
 export declare function readTextSafe(path: string): Promise<string | null>;
+/**
+ * Does any statement in `sql` create `tableName`?
+ *
+ * Every dialect quotes identifiers differently and Kysely's schema builder
+ * always quotes, so an unquoted-only match reports a table as missing on the
+ * exact projects most likely to have it. Accept each dialect's pair — and only
+ * a matching pair, via the backreference, so `"audit'` is not a hit — plus an
+ * optional schema qualifier, since `main.audit` is the same table.
+ */
+export declare function migrationCreatesTable(sql: string, tableName: string): boolean;
 /**
  * Every check that is true of any pikku project, regardless of where it deploys.
  *

package/dist/src/functions/validate/shared-checks.js

@@ -49,9 +49,23 @@ async function hasAuthSessionMiddleware(fnDir) {
         return false;
     return Object.values(meta.instances).some((instance) => /^betterAuth\w*Session$/.test(instance.definitionId ?? ''));
 }
-function migrationCreatesTable(sql, tableName) {
+/**
+ * Does any statement in `sql` create `tableName`?
+ *
+ * Every dialect quotes identifiers differently and Kysely's schema builder
+ * always quotes, so an unquoted-only match reports a table as missing on the
+ * exact projects most likely to have it. Accept each dialect's pair — and only
+ * a matching pair, via the backreference, so `"audit'` is not a hit — plus an
+ * optional schema qualifier, since `main.audit` is the same table.
+ */
+export function migrationCreatesTable(sql, tableName) {
     const escapedTable = tableName.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&');
-    const re = new RegExp(`\\bcreate\\s+table\\s+(?:if\\s+not\\s+exists\\s+)?["'\`]?${escapedTable}["'\`]?\\b`, 'i');
+    const qualifier = `(?:(?:["'\`]?\\w+["'\`]?|\\[\\w+\\])\\.)?`;
+    // The word boundary belongs to the bare alternative only: a trailing `\b`
+    // after a closing quote would demand a word character next, so `"audit" (`
+    // would not match.
+    const quoted = `(?:(["'\`])${escapedTable}\\1|\\[${escapedTable}\\]|${escapedTable}\\b)`;
+    const re = new RegExp(`\\bcreate\\s+table\\s+(?:if\\s+not\\s+exists\\s+)?${qualifier}${quoted}`, 'i');
     return re.test(sql);
 }
 /** better-auth's core schema — the tables its adapter queries on every request. */

package/dist/src/functions/validate/validate-registry.js

@@ -2,8 +2,10 @@ import { existsSync } from 'node:fs';
 import { readdir } from 'node:fs/promises';
 import { join, relative } from 'node:path';
 import { isAddonPackage, runAddonPackageChecks, } from './addon-package-checks.js';
+import { runPikkuBarrelChecks } from './pikku-barrel-checks.js';
 import { runSharedProjectChecks } from './shared-checks.js';
 import { runTypeIdentityChecks } from './type-identity-checks.js';
+import { runWorkspaceExportsChecks } from './workspace-exports-checks.js';
 /** A hand-written `types/application-types.d.ts` beside package.json. */
 const ADDON_MARKER = join('types', 'application-types.d.ts');
 const SKIP_DIRS = new Set([
@@ -63,6 +65,15 @@ export const CHECKS = [
             !existsSync(join(dir, ADDON_MARKER)),
         run: async ({ dir }) => (await runSharedProjectChecks(dir)).findings,
     },
+    {
+        id: 'pikku-barrel',
+        subject: 'app tier imports',
+        // Every Pikku project, addon included: an addon never generates the wiring
+        // leaves, so a barrel import there is the one that used to compile against
+        // a hub whose re-exports had quietly been dropped.
+        applies: async ({ dir }) => existsSync(join(dir, 'pikku.config.json')),
+        run: async ({ dir }) => runPikkuBarrelChecks(dir),
+    },
     {
         id: 'addon-package',
         subject: 'addon',
@@ -79,6 +90,15 @@ export const CHECKS = [
         applies: async ({ dir, label }) => label === '.' && existsSync(join(dir, 'node_modules')),
         run: async ({ dir }) => runTypeIdentityChecks(dir),
     },
+    {
+        id: 'workspace-exports',
+        subject: 'workspace subpath imports',
+        // Root only: the check pairs an import in one package with the exports map
+        // of another, so it needs the whole tree in view. Per-package it would see
+        // the consumer without the producer and report nothing.
+        applies: async ({ label }) => label === '.',
+        run: async ({ dir }) => runWorkspaceExportsChecks(dir),
+    },
 ];
 export async function planValidation(root) {
     const plan = [];

package/dist/src/functions/validate/workspace-exports-checks.d.ts

@@ -0,0 +1,14 @@
+import type { ValidateFinding } from './persona-checks.js';
+/**
+ * Every workspace-internal subpath import must resolve through the owning
+ * package's own `exports`.
+ *
+ * `exports` does not probe extensions the way a bundler alias does, so a map
+ * like `"./pikku/*": "./src/pikku/*"` resolves `pkg/pikku/client.gen` to a file
+ * called `client.gen` that was never written — the real file is `client.gen.ts`.
+ * Nothing catches it while a `resolve.alias` in the consumer's own vite config
+ * covers the same specifier: the alias wins locally, and the broken map only
+ * surfaces where that config is not in play (a sandbox scaffold config, a
+ * different bundler, plain node, another app in the same repo).
+ */
+export declare function runWorkspaceExportsChecks(root: string): Promise<ValidateFinding[]>;