@pikku/cli 0.12.100 → 0.12.103

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

@@ -0,0 +1,26 @@
+import type { ValidateFinding as Finding } from './persona-checks.js';
+/**
+ * A package that publishes generated pikku output.
+ *
+ * The generated files carry relative imports to hand-written sources, so what
+ * the package ships and what it references have to agree — which is what the
+ * checks below are for.
+ *
+ * Having a `.pikku` directory is not enough on its own: an app's
+ * packages/functions has one too, and it is codegen output for that app rather
+ * than something anybody installs. The question is whether the package *ships*
+ * it, so the signal is a `files`/`exports` that carries it into the tarball.
+ * A private package is excluded for the same reason — nobody installs it, so
+ * its published file set is not a thing that can be wrong.
+ */
+export declare function isAddonPackage(pkgDir: string): Promise<boolean>;
+/**
+ * Every relative import in a shipped generated file must resolve to a file
+ * that is itself shipped.
+ *
+ * Stated as a property rather than as "the build script must copy types/",
+ * because the build script is not the only way to get this wrong and will not
+ * always be a `cp`. The generated files declare what they need; the check just
+ * holds the package to it.
+ */
+export declare function runAddonPackageChecks(pkgDir: string): Promise<Finding[]>;

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

@@ -0,0 +1,258 @@
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { readJsonSafe, readTextSafe } from './shared-checks.js';
+/** Where the CLI writes generated output, both in source and once built. */
+const GENERATED_DIRS = ['.pikku', join('dist', '.pikku')];
+/** Roots that carry generated output into the tarball when listed in `files`. */
+const SHIPPING_ROOTS = new Set(['dist', '.pikku']);
+/**
+ * A package that publishes generated pikku output.
+ *
+ * The generated files carry relative imports to hand-written sources, so what
+ * the package ships and what it references have to agree — which is what the
+ * checks below are for.
+ *
+ * Having a `.pikku` directory is not enough on its own: an app's
+ * packages/functions has one too, and it is codegen output for that app rather
+ * than something anybody installs. The question is whether the package *ships*
+ * it, so the signal is a `files`/`exports` that carries it into the tarball.
+ * A private package is excluded for the same reason — nobody installs it, so
+ * its published file set is not a thing that can be wrong.
+ */
+export async function isAddonPackage(pkgDir) {
+    const pkg = await readJsonSafe(join(pkgDir, 'package.json'));
+    if (!pkg || pkg.private)
+        return false;
+    if (!GENERATED_DIRS.some((dir) => existsSync(join(pkgDir, dir))))
+        return false;
+    const shipsViaFiles = (pkg.files ?? []).some((entry) => SHIPPING_ROOTS.has(entry.replace(/^\.\//, '').split('/')[0]));
+    return shipsViaFiles || JSON.stringify(pkg.exports ?? null).includes('.pikku');
+}
+async function walk(dir) {
+    const 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())
+            out.push(...(await walk(path)));
+        else
+            out.push(path);
+    }
+    return out;
+}
+const IMPORT_RE = /(?:^|[\s(};])(?:from|import|require)\s*\(?\s*['"]([^'"]+)['"]/g;
+function relativeSpecifiers(source) {
+    const found = new Set();
+    for (const match of source.matchAll(IMPORT_RE)) {
+        const specifier = match[1];
+        if (specifier.startsWith('.'))
+            found.add(specifier);
+    }
+    return [...found];
+}
+/**
+ * The on-disk file a specifier names, under TypeScript's NodeNext rules.
+ *
+ * `./x.js` may be satisfied by `x.ts` or `x.d.ts`, and pikku's generated files
+ * import hand-written declarations as `./x.d.js` — the `.js` extension the
+ * compiler wants, on a file that only ever exists as `.d.ts`.
+ */
+function resolveCandidates(specifier, fromDir) {
+    const base = resolve(fromDir, specifier);
+    if (base.endsWith('.d.js'))
+        return [base.slice(0, -5) + '.d.ts'];
+    if (base.endsWith('.js')) {
+        const stem = base.slice(0, -3);
+        return [base, stem + '.ts', stem + '.d.ts', stem + '.tsx'];
+    }
+    // `.mjs` and `.cjs` are scanned as generated files, so they are also imported
+    // as one, and each has its own TypeScript twin rather than sharing `.ts`.
+    if (base.endsWith('.mjs') || base.endsWith('.cjs')) {
+        const stem = base.slice(0, -4);
+        const kind = base.slice(-3, -2);
+        return [base, `${stem}.${kind}ts`, `${stem}.d.${kind}ts`];
+    }
+    if (/\.(ts|tsx|json)$/.test(base))
+        return [base];
+    return [
+        base + '.ts',
+        base + '.d.ts',
+        base + '.js',
+        join(base, 'index.ts'),
+        join(base, 'index.d.ts'),
+        join(base, 'index.js'),
+    ];
+}
+/**
+ * The directory a `files` entry is rooted at.
+ *
+ * `dist`, `dist/`, `dist/**` and `dist/*` all publish the same tree, so the
+ * root is what decides both whether a path ships and whether the entry has
+ * anything behind it. Anything more elaborate than a trailing wildcard is left
+ * to npm.
+ */
+function packedRoot(entry) {
+    return entry
+        .replace(/^\.\//, '')
+        .replace(/\/\*+$/, '')
+        .replace(/\/$/, '');
+}
+/**
+ * Whether `files` carries this path into the published tarball.
+ *
+ * A package with no `files` publishes everything, so the question only has
+ * teeth when the field is present.
+ */
+function isPacked(absPath, pkgDir, files) {
+    if (!files)
+        return true;
+    const rel = relative(pkgDir, absPath);
+    if (rel.startsWith('..'))
+        return false;
+    return files.some((entry) => {
+        const normalized = packedRoot(entry);
+        return rel === normalized || rel.startsWith(normalized + sep);
+    });
+}
+/**
+ * Every `./…` target reachable through an `exports` or `imports` map, paired
+ * with the entry-point name that leads to it.
+ *
+ * Both fields nest arbitrarily deep — a subpath holds a condition object, which
+ * may hold another — so the walk collects strings rather than assuming a shape.
+ * A `*` is left in place: the wildcard's own directory is what has to ship.
+ */
+function entryPointTargets(map, name = '') {
+    if (typeof map === 'string') {
+        return map.startsWith('./') ? [{ name, target: map }] : [];
+    }
+    if (!map || typeof map !== 'object')
+        return [];
+    return Object.entries(map).flatMap(([key, value]) => entryPointTargets(value, name || key));
+}
+/**
+ * Every relative import in a shipped generated file must resolve to a file
+ * that is itself shipped.
+ *
+ * Stated as a property rather than as "the build script must copy types/",
+ * because the build script is not the only way to get this wrong and will not
+ * always be a `cp`. The generated files declare what they need; the check just
+ * holds the package to it.
+ */
+export async function runAddonPackageChecks(pkgDir) {
+    const findings = [];
+    const pkg = await readJsonSafe(join(pkgDir, 'package.json'));
+    if (!pkg)
+        return findings;
+    // `files` is the package's own statement of what it publishes, so an entry
+    // with nothing behind it means the build has not run — and validating the
+    // published file set of a package that has not been built proves nothing.
+    const absent = (pkg.files ?? []).filter((entry) => !existsSync(join(pkgDir, packedRoot(entry))));
+    if (absent.length > 0) {
+        findings.push({
+            id: 'addon-not-built',
+            severity: 'info',
+            message: `${pkg.name ?? relative(dirname(pkgDir), pkgDir)} lists ${absent.join(', ')} in "files" with nothing on disk — packaging was not verified because the package is not built`,
+            path: join(pkgDir, absent[0]),
+            fixHint: 'Run the package build first, then validate. In CI, `build && pikku validate` is the order that checks what actually publishes.',
+        });
+        return findings;
+    }
+    // The entry points are the package's promise about what can be reached from
+    // outside it, and nothing inside dist/.pikku mentions them — so the import
+    // walk below cannot see a `#pikku` that still points at the source tree.
+    for (const { name, target } of [
+        ...entryPointTargets(pkg.imports),
+        ...entryPointTargets(pkg.exports),
+    ]) {
+        const withoutWildcard = target.slice(2).split('*')[0];
+        if (!isPacked(join(pkgDir, withoutWildcard), pkgDir, pkg.files)) {
+            findings.push({
+                id: 'addon-entry-point-not-packed',
+                severity: 'error',
+                message: `"${name}" resolves to ${target}, which "files" does not publish — the entry point exists here and not for anyone who installs ${pkg.name ?? 'this addon'}`,
+                path: join(pkgDir, withoutWildcard),
+                fixHint: `Point it at the built copy under dist, or add ${withoutWildcard.split('/')[0]} to "files".`,
+            });
+            continue;
+        }
+        // Shipping the directory is not the same as producing the file. A wildcard
+        // names a directory whose contents are the point, so only a concrete
+        // target can be held to existing.
+        if (!target.includes('*') && !existsSync(join(pkgDir, withoutWildcard))) {
+            findings.push({
+                id: 'addon-entry-point-missing',
+                severity: 'error',
+                message: `"${name}" resolves to ${target}, which does not exist — importing it fails for anyone who installs ${pkg.name ?? 'this addon'}`,
+                path: join(pkgDir, withoutWildcard),
+                fixHint: 'Point the entry point at a file the build produces, or drop it from "exports".',
+            });
+        }
+    }
+    // Both generated directories ship, and they are not the same check twice.
+    // `exports` maps `./.pikku/*` to the root one, making it a public entry
+    // point whose imports climb to `<pkg>/types`, while the copy under dist
+    // reaches `<pkg>/dist/types` — two roots, two ways to fall outside the
+    // tarball.
+    const generatedRoots = GENERATED_DIRS.map((dir) => join(pkgDir, dir)).filter((dir) => existsSync(dir) && isPacked(dir, pkgDir, pkg.files));
+    // One missing file is imported by every generated file that needs its types,
+    // so reporting per import turns a single packaging mistake into a page of
+    // findings. Group by what is actually wrong: the thing that is not shipped.
+    const unresolved = new Map();
+    const unpacked = new Map();
+    const shippedFiles = (await Promise.all(generatedRoots.map((root) => walk(root)))).flat();
+    for (const file of shippedFiles) {
+        if (!/\.(ts|tsx|js|mjs|cjs)$/.test(file))
+            continue;
+        const source = await readTextSafe(file);
+        if (!source)
+            continue;
+        for (const specifier of relativeSpecifiers(source)) {
+            const candidates = resolveCandidates(specifier, dirname(file));
+            const target = candidates.find((candidate) => existsSync(candidate));
+            if (!target) {
+                // Keyed by the file that is missing rather than by the specifier: the
+                // same absent file is spelled `../types/x` from one directory and
+                // `../../types/x` from another, and it is still one thing to fix.
+                const missing = candidates[0];
+                const seen = unresolved.get(missing) ?? { specifier, files: [] };
+                seen.files.push(file);
+                unresolved.set(missing, seen);
+            }
+            else if (!isPacked(target, pkgDir, pkg.files)) {
+                const seen = unpacked.get(target) ?? { target, files: [] };
+                seen.files.push(file);
+                unpacked.set(target, seen);
+            }
+        }
+    }
+    const alsoIn = (files) => files.length > 1
+        ? ` (and ${files.length - 1} other generated file${files.length > 2 ? 's' : ''})`
+        : '';
+    for (const [missing, { specifier, files }] of unresolved) {
+        findings.push({
+            id: 'addon-shipped-import-unresolved',
+            severity: 'error',
+            message: `${relative(pkgDir, missing)} is not in the package, but ${files.length} shipped generated file${files.length === 1 ? '' : 's'} import${files.length === 1 ? 's' : ''} it (as "${specifier}" from ${relative(pkgDir, files[0])}) — anything installing ${pkg.name ?? 'this addon'} typechecks against a module that is not there`,
+            path: missing,
+            fixHint: 'Ship the file it names. The generated output is copied into dist, so whatever it imports has to be copied too — e.g. `cp -r .pikku types dist/` rather than `cp -r .pikku dist/`.',
+        });
+    }
+    for (const { target, files } of unpacked.values()) {
+        findings.push({
+            id: 'addon-shipped-import-not-packed',
+            severity: 'error',
+            message: `${relative(pkgDir, files[0])} imports ${relative(pkgDir, target)}${alsoIn(files)}, which exists but is excluded by "files" — it resolves here and not for anyone who installs the package`,
+            path: target,
+            fixHint: `Add ${relative(pkgDir, target).split(sep)[0]} to "files" in package.json, or move the file under a path already listed there.`,
+        });
+    }
+    return findings;
+}

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

@@ -15,7 +15,7 @@ export type PersonaCheckConfig = {
 /**
  * The people this project can run as, and whether it can run as them.
  *
- * Shared by `pikku workspace validate` and `pikku fabric validate` — the two
+ * Shared by `pikku validate` and `pikku fabric validate` — the two
  * validators are separate implementations, and a check that only one of them
  * makes is a check half the projects never see.
  *

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

@@ -100,7 +100,7 @@ const hasActorSignIn = async (sourceFiles) => {
 /**
  * The people this project can run as, and whether it can run as them.
  *
- * Shared by `pikku workspace validate` and `pikku fabric validate` — the two
+ * Shared by `pikku validate` and `pikku fabric validate` — the two
  * validators are separate implementations, and a check that only one of them
  * makes is a check half the projects never see.
  *

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

@@ -36,6 +36,16 @@ const SCENARIO_FILE = /\.(scenario|scenarios|steps)\.tsx?$/;
  */
 const VIRTUAL_USER_DECLARATIONS = ['definePersonas', 'runVirtualUser'];
 const VIRTUAL_USER_FILE = /\.(virtual-user|vu)\.tsx?$/;
+/**
+ * The declarations that grade an agent, and where they live.
+ *
+ * A scorer is a test of the agent that is also shipped, which is exactly why it
+ * needs its own file rather than sitting beside the agent it grades: the two
+ * 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_FILE = /\.scorers?\.tsx?$/;
 const isGenerated = (path) => path.includes('.gen.') || path.includes(`${'/'}.pikku${'/'}`);
 const listSourceFiles = async (dir) => {
     if (!existsSync(dir))
@@ -119,5 +129,28 @@ export const runScenarioFileChecks = async (root, srcDirectories) => {
             ].join('\n'),
         });
     }
+    for (const file of files) {
+        if (SCORER_FILE.test(file) || isGenerated(file))
+            continue;
+        const text = await readTextSafe(file);
+        if (!text)
+            continue;
+        const used = SCORER_DECLARATIONS.filter((name) => new RegExp(`\\b${name}\\s*\\(`).test(text));
+        if (used.length === 0)
+            continue;
+        const rel = relative(root, file);
+        findings.push({
+            id: 'scorer-declared-outside-scorer-file',
+            severity: 'error',
+            message: `${rel} declares ${used.join(', ')} — scorers and judges must live in a *.scorer.ts file, not mixed into application code`,
+            path: file,
+            fixHint: [
+                'Move the declaration into a dedicated file, e.g.:',
+                `  ${rel.replace(/[^/\\]+$/, 'grading.scorer.ts')}`,
+                'A scorer grades the agent it sits next to, and is edited for the',
+                'opposite reason — keeping it separate is what keeps it reviewable.',
+            ].join('\n'),
+        });
+    }
     return findings;
 };

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

@@ -48,7 +48,7 @@ export declare function readTextSafe(path: string): Promise<string | null>;
 /**
  * Every check that is true of any pikku project, regardless of where it deploys.
  *
- * `pikku workspace validate` is exactly this; `pikku fabric validate` is this
+ * `pikku validate`'s app-project check is exactly this; `pikku fabric validate` is this
  * plus the deploy-shaped checks (themes, frontends, the Cloudflare adapter, the
  * .gitignore contract). Before this module the two were separate walks over the
  * same project that duplicated sixteen findings verbatim, and each carried

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

@@ -85,7 +85,7 @@ const REQUIRED_SCAFFOLD = [
 /**
  * Every check that is true of any pikku project, regardless of where it deploys.
  *
- * `pikku workspace validate` is exactly this; `pikku fabric validate` is this
+ * `pikku validate`'s app-project check is exactly this; `pikku fabric validate` is this
  * plus the deploy-shaped checks (themes, frontends, the Cloudflare adapter, the
  * .gitignore contract). Before this module the two were separate walks over the
  * same project that duplicated sixteen findings verbatim, and each carried

package/dist/src/functions/validate/type-identity-checks.d.ts

@@ -0,0 +1,25 @@
+import type { ValidateFinding } from './persona-checks.js';
+/**
+ * A linked dependency resolves its own imports from its own checkout, so it can
+ * hand the project types built against a different version of a shared package.
+ * The symptom is a typecheck that OOMs rather than one that fails, so nothing
+ * else in this validator would catch it.
+ *
+ * Runs against the workspace root only. The mismatch is a property of the
+ * install, not of any one package in it, so running per workspace package would
+ * report the same pair once per package.
+ */
+export declare function runTypeIdentityChecks(root: string): Promise<ValidateFinding[]>;
+/**
+ * Preflight for codegen. Runs BEFORE the typecheck, because the failure it
+ * explains kills the process rather than failing it: a V8 heap OOM aborts, so
+ * nothing printed after the fact is ever seen. By the time the user has a
+ * symptom, the only thing that can help them is already on screen above it.
+ *
+ * Warns rather than throws. A skewed linked dependency is a strong signal, not
+ * a certainty — plenty of them are harmless, and refusing to build on one would
+ * break working setups over a heuristic.
+ */
+export declare function warnOnSplitTypeIdentity(rootDir: string, logger: {
+    warn: (message: string) => void;
+}): Promise<void>;

package/dist/src/functions/validate/type-identity-checks.js

@@ -0,0 +1,218 @@
+import { existsSync } from 'node:fs';
+import { lstat, readdir, realpath } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { ErrorCode } from '@pikku/inspector';
+import { readJsonSafe } from './shared-checks.js';
+/**
+ * Packages whose TYPE identity matters, not just their runtime identity.
+ *
+ * Two copies of one of these at different versions give TypeScript two
+ * unrelated declarations of the same interface, and every place they meet
+ * becomes a structural comparison of the full shape. Inside a generic inference
+ * chain that compounds: one project went from a 1.3GB/13s typecheck to an
+ * unbounded OOM (8GB and 12GB ceilings both died, 7.7M types, single
+ * assignability checks taking 8s) because one dependency's `dist` was symlinked
+ * into a sibling checkout that carried its own better-auth. It reads as "codegen
+ * is slow", never as a version problem, which is why it is worth a check.
+ *
+ * Distinct from the duplicate-copy check, which is two copies of the SAME
+ * version splitting module state at runtime. This is a compile-time blow-up and
+ * only fires when the versions differ.
+ */
+const TYPE_IDENTITY_PKGS = [
+    'better-auth',
+    '@better-auth/core',
+    '@pikku/core',
+    'kysely',
+    'zod',
+];
+/**
+ * Installed version of `pkg` as seen FROM `fromDir`, walking parent
+ * node_modules the way node resolution does. Used to ask what a linked
+ * dependency resolves in its own checkout, which is not what the project
+ * resolves.
+ */
+async function versionResolvedFrom(fromDir, pkg) {
+    let dir = fromDir;
+    for (;;) {
+        const j = await readJsonSafe(join(dir, 'node_modules', pkg, 'package.json'));
+        if (j?.version)
+            return j.version;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Where `pkg` resolves for the project itself. The root alone is not enough:
+ * an isolated/pnpm-style install (bun's default) links dependencies under the
+ * workspace package that declares them and leaves the root node_modules
+ * without them, so probing only the root silently finds nothing.
+ */
+async function projectResolvedVersion(root, pkg) {
+    const bases = [root];
+    for (const group of ['packages', 'apps', 'backends']) {
+        const groupDir = join(root, group);
+        if (!existsSync(groupDir))
+            continue;
+        const entries = await readdir(groupDir, { withFileTypes: true }).catch(() => []);
+        for (const d of entries) {
+            if (d.isDirectory())
+                bases.push(join(groupDir, d.name));
+        }
+    }
+    for (const base of bases) {
+        const j = await readJsonSafe(join(base, 'node_modules', pkg, 'package.json'));
+        if (j?.version)
+            return { version: j.version, from: base };
+    }
+    return null;
+}
+/**
+ * Dependencies whose code physically lives outside the project: a `link:` or
+ * `portal:` dep, or a hand-made symlink into a sibling checkout. Only these can
+ * introduce a second version of a type-identity package, because a normal
+ * install dedupes through the lockfile.
+ *
+ * The symlink is often NOT the package directory but a build output inside it
+ * (`node_modules/@scope/pkg/dist -> ../../../other-repo/packages/pkg/dist`),
+ * which still moves type resolution to the other tree since TypeScript resolves
+ * symlinks to their realpath. So each candidate subdir is probed too.
+ *
+ * Only symlinks are resolved. `realpath` lstats every component of the path, so
+ * running it over every installed package costs 20x more on a hoisted install
+ * (1781 packages at the root) than on an isolated one (35) — and a path that
+ * traverses no symlink cannot leave the project anyway. `readdir` already hands
+ * back the entry type, so ruling a package out is free.
+ */
+async function externalDependencyRoots(root) {
+    const found = new Map();
+    const nodeModules = join(root, 'node_modules');
+    if (!existsSync(nodeModules))
+        return found;
+    // Compare realpath against realpath: on macOS the temp/project path is often
+    // itself a symlink (/var -> /private/var), which would otherwise make every
+    // dependency look external.
+    const realRoot = await realpath(root).catch(() => root);
+    const topLevel = await readdir(nodeModules, { withFileTypes: true }).catch(() => []);
+    const pkgDirs = [];
+    for (const entry of topLevel) {
+        if (entry.name.startsWith('.'))
+            continue;
+        if (entry.name.startsWith('@')) {
+            const scoped = await readdir(join(nodeModules, entry.name), {
+                withFileTypes: true,
+            }).catch(() => []);
+            for (const inner of scoped) {
+                pkgDirs.push({
+                    dir: join(nodeModules, entry.name, inner.name),
+                    link: inner.isSymbolicLink(),
+                });
+            }
+        }
+        else {
+            pkgDirs.push({
+                dir: join(nodeModules, entry.name),
+                link: entry.isSymbolicLink(),
+            });
+        }
+    }
+    const linkTarget = async (path) => {
+        const stats = await lstat(path).catch(() => null);
+        if (!stats?.isSymbolicLink())
+            return null;
+        return realpath(path).catch(() => null);
+    };
+    const isExternal = (real) => relative(realRoot, real).startsWith('..');
+    for (const { dir: pkgDir, link } of pkgDirs) {
+        // A package linked to a path inside the project (bun's .bun store) is not
+        // external, but the build output *inside* that target still can be.
+        const target = link ? await realpath(pkgDir).catch(() => null) : null;
+        if (link && !target)
+            continue;
+        const candidates = [
+            target && isExternal(target) ? target : null,
+            await linkTarget(join(target ?? pkgDir, 'dist')),
+        ];
+        for (const real of candidates) {
+            if (!real || !isExternal(real))
+                continue;
+            const name = relative(nodeModules, pkgDir);
+            // `real` may point at a build output (…/pkg/dist); report the linked
+            // package's own root so the message names something a reader can act on.
+            let owner = real;
+            while (!existsSync(join(owner, 'package.json')) &&
+                dirname(owner) !== owner) {
+                owner = dirname(owner);
+            }
+            if (!found.has(name))
+                found.set(name, owner);
+            break;
+        }
+    }
+    return found;
+}
+/**
+ * A linked dependency resolves its own imports from its own checkout, so it can
+ * hand the project types built against a different version of a shared package.
+ * The symptom is a typecheck that OOMs rather than one that fails, so nothing
+ * else in this validator would catch it.
+ *
+ * Runs against the workspace root only. The mismatch is a property of the
+ * install, not of any one package in it, so running per workspace package would
+ * report the same pair once per package.
+ */
+export async function runTypeIdentityChecks(root) {
+    const findings = [];
+    const external = await externalDependencyRoots(root);
+    if (external.size === 0)
+        return findings;
+    for (const pkg of TYPE_IDENTITY_PKGS) {
+        const local = await projectResolvedVersion(root, pkg);
+        if (!local)
+            continue;
+        const ours = local.version;
+        for (const [depName, depRoot] of external) {
+            const theirs = await versionResolvedFrom(depRoot, pkg);
+            if (!theirs || theirs === ours)
+                continue;
+            findings.push({
+                id: `split-type-identity-${depName.replace(/[@/]/g, '-')}-${pkg.replace(/[@/]/g, '-')}`,
+                severity: 'error',
+                message: `"${depName}" is linked to ${depRoot} and resolves ${pkg}@${theirs} there, while this project resolves ${pkg}@${ours} — two type identities for ${pkg}`,
+                path: join(root, 'node_modules', depName),
+                fixHint: [
+                    `TypeScript treats the two ${pkg} declarations as unrelated types and structurally compares them wherever they meet, which can make a typecheck OOM instead of fail.`,
+                    `Align the versions so both trees resolve one ${pkg}: either bump ${pkg} to ${theirs} here, or to ${ours} in ${depRoot}.`,
+                    `If the link is no longer needed, remove it and reinstall so "${depName}" comes from the registry.`,
+                ].join('\n'),
+            });
+        }
+    }
+    return findings;
+}
+/**
+ * Preflight for codegen. Runs BEFORE the typecheck, because the failure it
+ * explains kills the process rather than failing it: a V8 heap OOM aborts, so
+ * nothing printed after the fact is ever seen. By the time the user has a
+ * symptom, the only thing that can help them is already on screen above it.
+ *
+ * Warns rather than throws. A skewed linked dependency is a strong signal, not
+ * a certainty — plenty of them are harmless, and refusing to build on one would
+ * break working setups over a heuristic.
+ */
+export async function warnOnSplitTypeIdentity(rootDir, logger) {
+    if (process.env?.PIKKU_SKIP_TYPE_IDENTITY_CHECK)
+        return;
+    const findings = await runTypeIdentityChecks(rootDir).catch(() => []);
+    if (findings.length === 0)
+        return;
+    logger.warn(`[${ErrorCode.SPLIT_TYPE_IDENTITY}] ${findings.length === 1 ? 'A linked dependency resolves a shared package' : 'Linked dependencies resolve shared packages'} at a different version than this project:\n` +
+        findings.map((f) => `  ${f.message}`).join('\n') +
+        `\nTypeScript treats each pair as two unrelated types and structurally compares them\n` +
+        `wherever they meet, which inside a generic inference chain can exhaust the heap —\n` +
+        `codegen then dies of memory pressure instead of reporting an error.\n\n` +
+        `Fix: align the versions so both trees resolve one copy, or drop the link and\n` +
+        `reinstall. Set PIKKU_SKIP_TYPE_IDENTITY_CHECK=1 to silence this.`);
+}

package/dist/src/functions/validate/validate-registry.d.ts

@@ -0,0 +1,52 @@
+import type { ValidateFinding as Finding } from './persona-checks.js';
+export type ValidateTarget = {
+    /** Absolute directory the check runs against. */
+    dir: string;
+    /** How the target is named in output — repo-relative, or "." for the root. */
+    label: string;
+};
+/**
+ * A check plus the condition under which it means anything.
+ *
+ * `pikku validate` runs every check whose precondition holds, wherever it
+ * holds. It deliberately does not detect a project *kind* and then dispatch:
+ * the repos that motivated this are several kinds at once — the addons
+ * monorepo is a workspace containing 217 publishable addons — and any
+ * single-kind guess is wrong for them. Preconditions compose where a mode
+ * would have had to pick.
+ */
+export type ValidateCheck = {
+    id: string;
+    /** What this check is for, shown when reporting what ran. */
+    subject: string;
+    applies: (target: ValidateTarget) => Promise<boolean>;
+    run: (target: ValidateTarget) => Promise<Finding[]>;
+};
+/**
+ * Every directory under `root` that holds a package.json.
+ *
+ * Walking beats reading the `workspaces` globs: the field is an array in one
+ * repo and `{ packages: [...] }` in the next, spells the same layout as
+ * `packages/**` or as six explicit globs, and a package that is real but
+ * unlisted is exactly the kind of thing worth validating. Over-collecting is
+ * harmless here because the preconditions decide what actually runs.
+ */
+export declare function discoverTargets(root: string, maxDepth?: number): Promise<ValidateTarget[]>;
+export declare const CHECKS: ValidateCheck[];
+export type ValidationPlan = Array<{
+    check: ValidateCheck;
+    target: ValidateTarget;
+}>;
+export declare function planValidation(root: string): Promise<ValidationPlan>;
+export type ValidateReport = {
+    ok: boolean;
+    root: string;
+    /** What ran, so a clean result can say what it actually looked at. */
+    ran: Array<{
+        checkId: string;
+        subject: string;
+        target: string;
+    }>;
+    findings: Finding[];
+};
+export declare function runValidate(root: string): Promise<ValidateReport>;