@pikku/core 0.12.83 → 0.12.86

package/scripts/generate-api-report.mjs

@@ -16,74 +16,81 @@
  *
  * Run: yarn api-report
  */
-import { readFileSync, writeFileSync } from 'node:fs';
-import { resolve, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import ts from 'typescript';
-const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const pkg = JSON.parse(readFileSync(resolve(packageRoot, 'package.json'), 'utf-8'));
+import { readFileSync, writeFileSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import ts from 'typescript'
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const pkg = JSON.parse(
+  readFileSync(resolve(packageRoot, 'package.json'), 'utf-8')
+)
 const entryPoints = Object.entries(pkg.exports).map(([subpath, dist]) => ({
-    subpath,
-    file: resolve(packageRoot, dist.replace('./dist/', './src/').replace(/\.js$/, '.ts')),
-}));
-const program = ts.createProgram(entryPoints.map((e) => e.file), {
+  subpath,
+  file: resolve(
+    packageRoot,
+    dist.replace('./dist/', './src/').replace(/\.js$/, '.ts')
+  ),
+}))
+const program = ts.createProgram(
+  entryPoints.map((e) => e.file),
+  {
     target: ts.ScriptTarget.ESNext,
     module: ts.ModuleKind.Node16,
     moduleResolution: ts.ModuleResolutionKind.Node16,
     strict: true,
     skipLibCheck: true,
-});
-const checker = program.getTypeChecker();
+  }
+)
+const checker = program.getTypeChecker()
 /** One line per symbol: how it is declared, flattened and stripped of noise. */
 const signature = (exported) => {
-    // A re-export is an alias; the declaration that matters is the target's, so
-    // an interface re-exported through a barrel still reports its members.
-    const symbol = exported.flags & ts.SymbolFlags.Alias
-        ? checker.getAliasedSymbol(exported)
-        : exported;
-    const declaration = symbol.declarations?.[0];
-    if (!declaration)
-        return exported.getName();
-    if (ts.isInterfaceDeclaration(declaration) ||
-        ts.isClassDeclaration(declaration) ||
-        ts.isTypeAliasDeclaration(declaration) ||
-        ts.isEnumDeclaration(declaration)) {
-        // The declaration itself, so member changes show up in the diff.
-        return declaration
-            .getText()
-            .replace(/\/\*\*[\s\S]*?\*\//g, '')
-            .replace(/\/\/[^\n]*/g, '')
-            .split('\n')
-            .map((l) => l.trim())
-            .filter(Boolean)
-            .join(' ');
-    }
-    const type = checker.getTypeOfSymbolAtLocation(symbol, declaration);
-    return `${exported.getName()}: ${checker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation)}`;
-};
+  // A re-export is an alias; the declaration that matters is the target's, so
+  // an interface re-exported through a barrel still reports its members.
+  const symbol =
+    exported.flags & ts.SymbolFlags.Alias
+      ? checker.getAliasedSymbol(exported)
+      : exported
+  const declaration = symbol.declarations?.[0]
+  if (!declaration) return exported.getName()
+  if (
+    ts.isInterfaceDeclaration(declaration) ||
+    ts.isClassDeclaration(declaration) ||
+    ts.isTypeAliasDeclaration(declaration) ||
+    ts.isEnumDeclaration(declaration)
+  ) {
+    // The declaration itself, so member changes show up in the diff.
+    return declaration
+      .getText()
+      .replace(/\/\*\*[\s\S]*?\*\//g, '')
+      .replace(/\/\/[^\n]*/g, '')
+      .split('\n')
+      .map((l) => l.trim())
+      .filter(Boolean)
+      .join(' ')
+  }
+  const type = checker.getTypeOfSymbolAtLocation(symbol, declaration)
+  return `${exported.getName()}: ${checker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation)}`
+}
 const sections = [
-    '# @pikku/core API report',
-    '',
-    'Generated by `yarn api-report`. Every exported symbol with its full',
-    'signature, so a member-level change is a reviewable diff. Do not edit.',
-    '',
-];
+  '# @pikku/core API report',
+  '',
+  'Generated by `yarn api-report`. Every exported symbol with its full',
+  'signature, so a member-level change is a reviewable diff. Do not edit.',
+  '',
+]
 for (const { subpath, file } of entryPoints) {
-    const source = program.getSourceFile(file);
-    if (!source)
-        continue;
-    const moduleSymbol = checker.getSymbolAtLocation(source);
-    if (!moduleSymbol)
-        continue;
-    const exports = checker
-        .getExportsOfModule(moduleSymbol)
-        .map((s) => [s.getName(), signature(s)])
-        .sort(([a], [b]) => a.localeCompare(b));
-    sections.push(`## ${subpath}`, '');
-    sections.push('```ts');
-    for (const [, sig] of exports)
-        sections.push(sig);
-    sections.push('```', '');
+  const source = program.getSourceFile(file)
+  if (!source) continue
+  const moduleSymbol = checker.getSymbolAtLocation(source)
+  if (!moduleSymbol) continue
+  const exports = checker
+    .getExportsOfModule(moduleSymbol)
+    .map((s) => [s.getName(), signature(s)])
+    .sort(([a], [b]) => a.localeCompare(b))
+  sections.push(`## ${subpath}`, '')
+  sections.push('```ts')
+  for (const [, sig] of exports) sections.push(sig)
+  sections.push('```', '')
 }
-writeFileSync(resolve(packageRoot, 'api-report.md'), sections.join('\n'));
-console.log(`api-report.md written for ${entryPoints.length} entry points`);
+writeFileSync(resolve(packageRoot, 'api-report.md'), sections.join('\n'))
+console.log(`api-report.md written for ${entryPoints.length} entry points`)

package/scripts/generate-api-report.mts

@@ -22,7 +22,7 @@
  *
  * Run: yarn api-report
  */
-import { readFileSync, writeFileSync } from 'node:fs'
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { resolve, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import ts from 'typescript'
@@ -32,15 +32,36 @@ const pkg = JSON.parse(
   readFileSync(resolve(packageRoot, 'package.json'), 'utf-8')
 )
 
-const entryPoints = Object.entries(pkg.exports as Record<string, string>).map(
-  ([subpath, dist]) => ({
+/**
+ * A wildcard subpath stands for as many entry points as there are files behind
+ * it, and the report is per entry point. Left as a pattern it resolves to no
+ * source file at all, so every sub-barrel it publishes goes unreported.
+ */
+const expand = ([subpath, dist]: [string, string]): [string, string][] => {
+  if (!subpath.includes('*')) return [[subpath, dist]]
+  const [prefix] = dist.split('*') as [string]
+  return readdirSync(
+    resolve(packageRoot, prefix.replace('./dist/', './src/')),
+    {
+      recursive: true,
+      encoding: 'utf-8',
+    }
+  )
+    .filter((file) => file.endsWith('.ts') && !file.endsWith('.d.ts'))
+    .map((file) => file.slice(0, -'.ts'.length))
+    .sort()
+    .map((area) => [subpath.replace('*', area), dist.replace('*', area)])
+}
+
+const entryPoints = Object.entries(pkg.exports as Record<string, string>)
+  .flatMap(expand)
+  .map(([subpath, dist]) => ({
     subpath,
     file: resolve(
       packageRoot,
       dist.replace('./dist/', './src/').replace(/\.js$/, '.ts')
     ),
-  })
-)
+  }))
 
 const program = ts.createProgram(
   entryPoints.map((e) => e.file),
@@ -159,9 +180,7 @@ const isPublic = (member: ts.ClassElement | ts.TypeElement): boolean =>
  */
 const membered = (
   declaration:
-    | ts.ClassDeclaration
-    | ts.InterfaceDeclaration
-    | ts.EnumDeclaration,
+    ts.ClassDeclaration | ts.InterfaceDeclaration | ts.EnumDeclaration,
   members: ts.NodeArray<ts.ClassElement | ts.TypeElement | ts.EnumMember>
 ): string => {
   if (members.length === 0) return oneLine(declaration.getText())
@@ -212,14 +231,6 @@ const signature = (exported: ts.Symbol): string => {
   return `${exported.getName()}: ${checker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation)}`
 }
 
-/**
- * Entry points whose signatures move with the CLI's codegen. Everything else
- * is what an application imports, and is what a compatibility promise covers.
- *
- * knowledge: decisions/internals/the-ecosystem-entry-point-carries-the-adapter-surface.md
- */
-const ECOSYSTEM_SUBPATHS = new Set(['./ecosystem', './internal'])
-
 type Exported = { name: string; members: number; signature: string }
 
 /** The members the report lists, which is what the tally is counting. */
@@ -258,33 +269,16 @@ for (const { subpath, file } of entryPoints) {
   )
 }
 
-// A name reachable from more than one entry point is counted once, against the
-// weaker promise — reaching it through a stable subpath is what a consumer will
-// have done, whatever else also exports it.
-const tierOf = new Map<string, string>()
+// A name reachable from more than one entry point is counted once: what a
+// compatibility promise owes is the name, not each door onto it.
 const membersOf = new Map<string, number>()
-for (const [subpath, exports] of modules) {
-  const tier = ECOSYSTEM_SUBPATHS.has(subpath) ? 'ecosystem' : 'stable'
-  for (const { name, members } of exports) {
-    if (tier === 'stable' || !tierOf.has(name)) tierOf.set(name, tier)
+for (const exports of modules.values())
+  for (const { name, members } of exports)
     membersOf.set(name, Math.max(membersOf.get(name) ?? 0, members))
-  }
-}
 
-const tally = (tier: string) => {
-  const names = [...tierOf].filter(([, t]) => t === tier).map(([n]) => n)
-  return {
-    entryPoints: [...modules.keys()].filter(
-      (s) => (ECOSYSTEM_SUBPATHS.has(s) ? 'ecosystem' : 'stable') === tier
-    ).length,
-    names: names.length,
-    members: names.reduce((total, n) => total + (membersOf.get(n) ?? 0), 0),
-  }
-}
-const stable = tally('stable')
-const ecosystem = tally('ecosystem')
-const observable =
-  stable.names + stable.members + ecosystem.names + ecosystem.members
+const names = membersOf.size
+const members = [...membersOf.values()].reduce((total, n) => total + n, 0)
+const observable = names + members
 
 const reachableFrom = new Map<string, number>()
 for (const exports of modules.values())
@@ -313,13 +307,9 @@ const sections: string[] = [
   '',
   '## What a compatibility promise covers',
   '',
-  `**${observable} observable things**: ${stable.names + ecosystem.names} exported names, plus`,
-  `${stable.members + ecosystem.members} members on the classes and interfaces among them.`,
-  '',
-  '| tier | entry points | names | members |',
-  '| --- | ---: | ---: | ---: |',
-  `| stable | ${stable.entryPoints} | ${stable.names} | ${stable.members} |`,
-  `| ecosystem | ${ecosystem.entryPoints} | ${ecosystem.names} | ${ecosystem.members} |`,
+  `**${observable} observable things**: ${names} exported names, plus`,
+  `${members} members on the classes and interfaces among them, reachable`,
+  `through ${modules.size} entry points.`,
   '',
   'An entry point whose exports are mostly *exclusive* is a self-contained',
   'subsystem rather than shared machinery — which tends to mean a newer one.',

package/src/agent-naming.test.ts

@@ -0,0 +1,68 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join, dirname } from 'node:path'
+
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
+const reportPath = join(packageRoot, 'api-report.md')
+
+/**
+ * `AI` described the model provider, never the agent runtime, so #596 renamed
+ * every agent symbol to `Agent`. The names below are the ones that survived,
+ * because each really does wrap a provider call.
+ *
+ * Listing them here is what makes the rule checkable: anything else exported as
+ * `AI*` is a symbol that slipped back to the old naming, and this fails rather
+ * than letting it reach a consumer.
+ */
+const PROVIDER_SYMBOLS = new Set([
+  'AIEmbeddingService',
+  'AIEmbedManyParams',
+  'AIEmbedManyResult',
+  'AIEmbedParams',
+  'AIEmbedResult',
+  'AIGenerateImageParams',
+  'AIGenerateImagePrompt',
+  'AIGenerateImageResult',
+  'AIGenerateSpeechParams',
+  'AIGenerateSpeechResult',
+  'AIProviderAuthError',
+  'AIProviderNotConfiguredError',
+  'AIProviderOptions',
+  'AIRerankParams',
+  'AIRerankResult',
+  'AITranscriptionParams',
+  'AITranscriptionResult',
+])
+
+describe('the agent runtime is not exported under the AI name', () => {
+  test('every AI* symbol in the public surface is a provider wrapper', () => {
+    const report = readFileSync(reportPath, 'utf-8')
+    const found = new Set(report.match(/\bAI[A-Z][A-Za-z]*/g) ?? [])
+
+    const strays = [...found].filter((name) => !PROVIDER_SYMBOLS.has(name))
+
+    assert.deepEqual(
+      strays,
+      [],
+      'these are exported as `AI*` but are not provider wrappers — rename them ' +
+        'to `Agent*`, or add them to PROVIDER_SYMBOLS if they genuinely wrap a ' +
+        'model provider call'
+    )
+  })
+
+  test('the agent entry points are the renamed ones', () => {
+    const { exports } = JSON.parse(
+      readFileSync(join(packageRoot, 'package.json'), 'utf-8')
+    )
+
+    assert.ok(exports['./agent'], 'expected the ./agent entry point')
+    assert.ok(
+      exports['./agent-scorer'],
+      'expected the ./agent-scorer entry point'
+    )
+    assert.equal(exports['./ai-agent'], undefined)
+    assert.equal(exports['./ai-scorer'], undefined)
+  })
+})

package/src/api-report.test.ts

@@ -1,7 +1,8 @@
 import { describe, test } from 'node:test'
 import assert from 'node:assert/strict'
 import { execFileSync } from 'node:child_process'
-import { readFileSync, writeFileSync } from 'node:fs'
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
 import { fileURLToPath } from 'node:url'
 import { join, dirname } from 'node:path'
 
@@ -67,3 +68,71 @@ describe('the API report matches the code', () => {
     )
   })
 })
+
+/**
+ * Every branch that touches the public surface rewrites the whole report, so
+ * two of them meeting is a ~9000-line conflict with no meaningful resolution
+ * in it. A merge driver takes the conflict away; the test above is what still
+ * insists on a report that matches the code.
+ *
+ * knowledge: decisions/internals/the-api-report-pins-members-not-just-names.md
+ */
+describe('merging the API report is not hand work', () => {
+  const repoRoot = join(packageRoot, '..', '..')
+
+  test('.gitattributes routes the report through the driver', () => {
+    const attributes = readFileSync(join(repoRoot, '.gitattributes'), 'utf-8')
+
+    assert.match(
+      attributes,
+      /^packages\/core\/api-report\.md\s+merge=api-report\b/m,
+      'the report must name the merge driver, or git conflicts on it as usual'
+    )
+  })
+
+  test('the setup script registers the driver as a plain take-one-side', () => {
+    // Against a throwaway repository rather than this one: a driver is written
+    // to `.git/config`, which every worktree of a checkout shares, so running
+    // this in place would reach into whatever else is checked out beside it.
+    const sandbox = mkdtempSync(join(tmpdir(), 'pikku-merge-driver-'))
+    try {
+      execFileSync('git', ['init', '--quiet', sandbox], { stdio: 'pipe' })
+      execFileSync(
+        'node',
+        [join(repoRoot, 'scripts', 'setup-merge-drivers.mjs')],
+        { cwd: sandbox, stdio: 'pipe' }
+      )
+      const driver = execFileSync(
+        'git',
+        ['config', '--local', 'merge.api-report.driver'],
+        { cwd: sandbox, stdio: 'pipe' }
+      )
+        .toString()
+        .trim()
+
+      // `true` writes nothing and succeeds, which is how a driver tells git to
+      // keep the side already in %A. Anything that regenerates the report is
+      // the trap this pins shut: git runs a driver while merging that one
+      // path, with the rest of the tree still unmerged, so the generator reads
+      // the old sources and resolves to a report missing exactly the API the
+      // incoming branch adds — conflict-free and wrong, which is worse than a
+      // conflict. The regeneration belongs to the guard above, which runs
+      // against a finished tree.
+      assert.equal(
+        driver,
+        'true',
+        'the driver must resolve to one side verbatim and run nothing'
+      )
+    } finally {
+      rmSync(sandbox, { recursive: true, force: true })
+    }
+  })
+
+  test('postinstall runs the setup, so a fresh clone is not left without it', () => {
+    const manifest = JSON.parse(
+      readFileSync(join(repoRoot, 'package.json'), 'utf-8')
+    )
+
+    assert.match(manifest.scripts.postinstall, /setup-merge-drivers\.mjs/)
+  })
+})

package/src/app-alias-surface.test.ts

@@ -0,0 +1,179 @@
+import { test, describe } from 'node:test'
+import * as assert from 'assert'
+import ts from 'typescript'
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/**
+ * The generated `#pikku` alias is the app developer's public API. An app
+ * reaching past it into `@pikku/core` is the smell this file measures: the
+ * alias is typed against that app's own functions, so a name pulled from core
+ * directly is one the app is holding untyped and one the CLI cannot evolve.
+ *
+ * The trees below are apps rather than packages, so they have no `src`
+ * convention to walk — bootstrap and test files sit wherever the runtime wants
+ * them. Walking each tree root means skipping what an app accumulates:
+ * installed dependencies, build output, and its own generated `.pikku`.
+ */
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '../../..')
+const appTrees = ['templates', 'e2e', 'verifiers']
+const skipped = new Set(['node_modules', 'dist', '.next', 'build'])
+
+/**
+ * `outDir` is a project's own setting, so the generated tree is not always
+ * `.pikku` — the treeshake verifier writes one output tree per scenario under
+ * `.pikku-shake`. Matching the prefix keeps a leaf's generated `index.ts`, which
+ * carries no `.gen.` in its name, from reading as hand-written app code.
+ */
+const isGeneratedTree = (entry: string) => entry.startsWith('.pikku')
+
+const walkApp = (dir: string, out: string[] = []): string[] => {
+  for (const entry of readdirSync(dir)) {
+    if (skipped.has(entry) || isGeneratedTree(entry)) continue
+    const path = join(dir, entry)
+    if (statSync(path).isDirectory()) walkApp(path, out)
+    else if (path.endsWith('.ts') || path.endsWith('.tsx')) out.push(path)
+  }
+  return out
+}
+
+/**
+ * `.gen.*` and `.d.ts` files are CLI output, not hand-written source: what they
+ * import is decided by the codegen templates, which are the thing that writes
+ * the alias in the first place.
+ */
+const isGenerated = (path: string) =>
+  path.includes('.gen.') || path.endsWith('.d.ts')
+
+const appSourceFiles = () =>
+  appTrees
+    .flatMap((tree) => walkApp(join(repoRoot, tree)))
+    .filter((file) => !isGenerated(file))
+
+/**
+ * Parsed rather than grepped: a step body held as a template literal is fixture
+ * text describing a user's file, not an import the app itself makes.
+ */
+const coreImports = (file: string) => {
+  const source = ts.createSourceFile(
+    file,
+    readFileSync(file, 'utf8'),
+    ts.ScriptTarget.Latest,
+    true
+  )
+  const found: { specifier: string; line: number; names: string[] }[] = []
+  for (const statement of source.statements) {
+    if (
+      !ts.isImportDeclaration(statement) &&
+      !ts.isExportDeclaration(statement)
+    ) {
+      continue
+    }
+    const moduleSpecifier = statement.moduleSpecifier
+    if (!moduleSpecifier || !ts.isStringLiteral(moduleSpecifier)) continue
+    const specifier = moduleSpecifier.text
+    if (specifier !== '@pikku/core' && !specifier.startsWith('@pikku/core/')) {
+      continue
+    }
+    const { line } = source.getLineAndCharacterOfPosition(
+      statement.getStart(source)
+    )
+    const clause = ts.isImportDeclaration(statement)
+      ? statement.importClause?.namedBindings
+      : statement.exportClause
+    const names =
+      clause && (ts.isNamedImports(clause) || ts.isNamedExports(clause))
+        ? clause.elements.map((element) => element.name.text)
+        : []
+    found.push({ specifier, line: line + 1, names })
+  }
+  return found
+}
+
+/**
+ * The scenario and persona surfaces are test-only names — actors, cookie jars,
+ * polling helpers, the typed personas an app declares. They are app code, but a
+ * distinct surface from wiring, so they reach the app through their own
+ * sub-entry rather than crowding the main hub.
+ */
+const scenarioSubpaths = new Set(['@pikku/core/scenario', '@pikku/core/persona'])
+
+/**
+ * A relative path into the generated scenario barrel reaches the same file the
+ * alias does, so it compiles — and then hard-codes how far the app file sits
+ * from `outDir`. Moving either end breaks it, and the CLI has no way to see
+ * that it is depended upon.
+ */
+const relativeIntoScenarioBarrel = (file: string) => {
+  const source = ts.createSourceFile(
+    file,
+    readFileSync(file, 'utf8'),
+    ts.ScriptTarget.Latest,
+    true
+  )
+  const found: { specifier: string; line: number }[] = []
+  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 (!moduleSpecifier.text.startsWith('.')) continue
+    if (!/\/pikku-scenario-types\.gen\.js$/.test(moduleSpecifier.text)) continue
+    const { line } = source.getLineAndCharacterOfPosition(
+      statement.getStart(source)
+    )
+    found.push({ specifier: moduleSpecifier.text, line: line + 1 })
+  }
+  return found
+}
+
+describe('the #pikku alias is the app surface', () => {
+  test('scenario code reaches the test surface through #pikku/scenario', () => {
+    const offenders: string[] = []
+
+    for (const file of appSourceFiles()) {
+      for (const { specifier, line, names } of coreImports(file)) {
+        if (!scenarioSubpaths.has(specifier)) continue
+        offenders.push(
+          `${relative(repoRoot, file)}:${line}  ${names.join(', ')}  from '${specifier}'`
+        )
+      }
+    }
+
+    assert.deepStrictEqual(
+      offenders,
+      [],
+      `Scenario and persona names come from the generated ` +
+        `'#pikku/scenario' entry, which is typed against this app's own ` +
+        `personas and steps.\n` +
+        `Reaching '@pikku/core/scenario' or '@pikku/core/persona' directly ` +
+        `gets the untyped shape, from a subpath scheduled for deletion.\n\n` +
+        offenders.join('\n')
+    )
+  })
+
+  test('the scenario barrel is reached through the alias, not a relative path', () => {
+    const offenders: string[] = []
+
+    for (const file of appSourceFiles()) {
+      for (const { specifier, line } of relativeIntoScenarioBarrel(file)) {
+        offenders.push(`${relative(repoRoot, file)}:${line}  '${specifier}'`)
+      }
+    }
+
+    assert.deepStrictEqual(
+      offenders,
+      [],
+      `The generated scenario barrel is reached through '#pikku/scenario', ` +
+        `which the app's own 'imports' map points at.\n` +
+        `A relative path hard-codes the distance from the file to 'outDir', ` +
+        `so moving either end breaks it silently.\n\n` +
+        offenders.join('\n')
+    )
+  })
+})