@estiva-app/ui 0.22.0 → 0.23.0

package/src/registry/build.ts

@@ -24,7 +24,7 @@ import { SCHEMA_VERSION, type EntryBehaviour, type EntryKind, type EntryProp, ty
 export interface BuildOptions {
   /** The repository's top folder. */
   root?: string
-  /** The name this registry's entries are recorded under. One repo per registry until UIG-13. */
+  /** The name this registry's entries are recorded under. */
   repo?: string
 }
 
@@ -36,7 +36,7 @@ interface RawExport {
   isType: boolean
 }
 
-/** What the parser found above and about one exported declaration. */
+/** What the parser found above and about one top-level declaration. */
 interface Declared {
   /** The doc comment, cleaned, or `''`. */
   doc: string
@@ -49,7 +49,7 @@ interface Declared {
   propsType?: ts.TypeNode
 }
 
-const PACKAGE_IMPORT = '@estiva-app/ui'
+export const PACKAGE_IMPORT = '@estiva-app/ui'
 
 /**
  * Storybook's own `sanitize`, which is what turns a title and a story's export
@@ -58,7 +58,7 @@ const PACKAGE_IMPORT = '@estiva-app/ui'
  * builder, which apps run. A test holds this to the ids a real Storybook build
  * produces.
  */
-function sanitize(name: string): string {
+export function sanitize(name: string): string {
   return name
     .toLowerCase()
     .replace(/[ ’–—―′¿'`~!@#$%^&*()_|+\-=?;:'",.<>{}[\]\\/]/g, '-')
@@ -87,7 +87,7 @@ function storyNameFromExport(key: string): string {
     .trim()
 }
 
-const toId = (title: string, name: string) => `${sanitize(title)}--${sanitize(storyNameFromExport(name))}`
+export const toId = (title: string, name: string) => `${sanitize(title)}--${sanitize(storyNameFromExport(name))}`
 
 /** Read `src/index.ts`. Its `export { … } from './Sibling'` statements are the target set. */
 export function readIndexExports(source: string): RawExport[] {
@@ -122,9 +122,11 @@ function docAbove(source: string, node: ts.Node, headerPos: number | null = null
   if (!jsdoc) return ''
   if (headerPos !== null && jsdoc.pos === headerPos) return ''
   // Only a comment that sits against the declaration describes it: anything
-  // with a blank line or another statement between them is about something else.
+  // with another statement between them is about something else. A `//` line
+  // between is still its own — the written note an escape needs sits there, and
+  // TypeScript attaches the doc comment through it too.
   const between = source.slice(jsdoc.end, node.getStart())
-  if (between.trim() !== '') return ''
+  if (between.replace(/\/\/[^\n]*/g, '').trim() !== '') return ''
   return source
     .slice(jsdoc.pos, jsdoc.end)
     .split(/\r?\n/)
@@ -141,7 +143,7 @@ function docAbove(source: string, node: ts.Node, headerPos: number | null = null
  * "A list of actions from a trigger." is a purpose; "One row, two parts." is
  * not, on its own.
  */
-function firstSentence(prose: string): string {
+export function firstSentence(prose: string): string {
   const flat = prose
     .split(/\n\s*\n/)[0]
     .split('\n')
@@ -157,7 +159,7 @@ function firstSentence(prose: string): string {
 }
 
 /** A page's opening paragraph: everything between its `# Heading` and the first blank line. */
-function pageOpening(mdx: string): string {
+export function pageOpening(mdx: string): string {
   const lines = mdx.split(/\r?\n/)
   const heading = lines.findIndex((line) => /^#\s+\S/.test(line))
   if (heading < 0) return ''
@@ -214,17 +216,31 @@ function literalUnion(type: ts.TypeNode | undefined, aliases: Map<string, ts.Typ
   return values.length > 1 ? values : null
 }
 
-/** Everything one sibling file says about the names it exports. */
 /** A type’s finished props and word-choices, read by the module that declares them. */
-interface Resolved {
+export interface Resolved {
   props: EntryProp[]
   variants: EntryVariant[]
 }
 
-/** Ask another file of this package for a type it declares, already resolved. */
-type Sibling = (module: string, typeName: string) => Resolved | undefined
+/**
+ * Ask another file for a type it declares, already resolved. `specifier` is the
+ * import as written (`./IconButton`, `@/lib/types`); the caller decides what it
+ * points at, and answers `undefined` for anything outside the library it reads.
+ */
+export type Sibling = (specifier: string, typeName: string) => Resolved | undefined
 
-function readModule(source: string, sibling: Sibling = () => undefined) {
+export interface ReadOptions {
+  /**
+   * Whether a file with no comment of its own at the top lends the comment on
+   * its first declaration to the file. The package: yes — `Skeleton.tsx`'s
+   * family paragraph sits there, and taking it as `SkeletonBar`'s was wrong. An
+   * app: no — a comment directly above a part is that part's, which is what a
+   * person writing one expects; a file's own goes at the very top.
+   */
+  lendFirstComment?: boolean
+}
+
+export function readModule(source: string, sibling: Sibling = () => undefined, { lendFirstComment = true }: ReadOptions = {}) {
   const file = ts.createSourceFile('module.tsx', source, ts.ScriptTarget.Latest, true)
   const declarations = new Map<string, Declared>()
   const aliases = new Map<string, ts.TypeNode>()
@@ -232,7 +248,7 @@ function readModule(source: string, sibling: Sibling = () => undefined) {
   /** What each interface extends, as written — `Omit<IdentityMenuProps, 'compact'>` and all. */
   const bases = new Map<string, ts.ExpressionWithTypeArguments[]>()
   /** Which module each imported name came from. */
-  const importedFrom = new Map<string, string>()
+  const importedFrom = new Map<string, { specifier: string; imported: string }>()
 
   const propsTypeOf = (parameters: readonly ts.ParameterDeclaration[]): ts.TypeNode | undefined => parameters[0]?.type
 
@@ -257,18 +273,42 @@ function readModule(source: string, sibling: Sibling = () => undefined) {
     return undefined
   }
 
+  /**
+   * `const Row: FC<RowProps> = ({ … }) => …` leaves the parameter bare: the
+   * props are the annotation's type argument — `FC`, `FunctionComponent`,
+   * `React.FC`, `React.FunctionComponent`.
+   */
+  const propsOfAnnotation = (type: ts.TypeNode | undefined): ts.TypeNode | undefined => {
+    if (!type || !ts.isTypeReferenceNode(type)) return undefined
+    const named = ts.isIdentifier(type.typeName) ? type.typeName.text : type.typeName.right.text
+    return named === 'FC' || named === 'FunctionComponent' ? type.typeArguments?.[0] : undefined
+  }
+
   // The file's header comment: the first `/**` above the first thing that is
   // not an import. It belongs to the file, whatever export happens to follow it.
   const opening = file.statements.find((statement) => !ts.isImportDeclaration(statement))
   const headerPos = opening ? ((ts.getLeadingCommentRanges(source, opening.getFullStart()) ?? []).find((range) => source.slice(range.pos, range.pos + 3) === '/**')?.pos ?? null) : null
+  // A file that opens with its own comment, above its imports — Peek's and Ship's
+  // way — has its header there, so the comment on its first declaration is that
+  // declaration's own. Only a file with no such comment lends the first one it has.
+  const topPos = file.statements[0] ? ((ts.getLeadingCommentRanges(source, file.statements[0].getFullStart()) ?? []).find((range) => source.slice(range.pos, range.pos + 3) === '/**')?.pos ?? null) : null
+  // An app lends no comment to the file but one above its imports: in a file
+  // with no imports the first comment sits on the first part, and is the part's.
+  const aboveImports = !!file.statements[0] && ts.isImportDeclaration(file.statements[0])
+  const refused = lendFirstComment ? (topPos ?? headerPos) : aboveImports ? topPos : null
 
   for (const statement of file.statements) {
     if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier)) {
       const bindings = statement.importClause?.namedBindings
       if (bindings && ts.isNamedImports(bindings)) {
-        for (const element of bindings.elements) importedFrom.set(element.name.text, statement.moduleSpecifier.text)
+        for (const element of bindings.elements) importedFrom.set(element.name.text, { specifier: statement.moduleSpecifier.text, imported: (element.propertyName ?? element.name).text })
       }
     }
+    // `export type { TopicRowProps } from './TopicRow'` hands a type on without
+    // declaring it: a file that asks this one for it is sent on to the next.
+    if (ts.isExportDeclaration(statement) && statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier) && statement.exportClause && ts.isNamedExports(statement.exportClause)) {
+      for (const element of statement.exportClause.elements) importedFrom.set(element.name.text, { specifier: statement.moduleSpecifier.text, imported: (element.propertyName ?? element.name).text })
+    }
     if (ts.isTypeAliasDeclaration(statement)) aliases.set(statement.name.text, statement.type)
     if (ts.isInterfaceDeclaration(statement)) {
       shapes.set(statement.name.text, [...statement.members])
@@ -280,19 +320,49 @@ function readModule(source: string, sibling: Sibling = () => undefined) {
     }
     if (ts.isTypeAliasDeclaration(statement) && ts.isTypeLiteralNode(statement.type)) shapes.set(statement.name.text, [...statement.type.members])
 
-    const exported = ts.canHaveModifiers(statement) && ts.getModifiers(statement)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)
-    if (!exported) continue
-    const doc = docAbove(source, statement, headerPos)
+    // Every top-level function, class and constant, exported or not. The package
+    // exports at the declaration, so for it the two are the same; an app also
+    // writes `function Row() {…}` and `export { Row }` or `export default Row`
+    // further down, and the name is still read here, with its comment and props.
+    if (ts.isClassDeclaration(statement)) {
+      // `class ErrorBoundary extends Component<Props, State>`: its props are the
+      // first type argument of what it extends. `export default class extends …`
+      // has no name of its own, and is kept under `default`.
+      const base = (statement.heritageClauses ?? []).find((clause) => clause.token === ts.SyntaxKind.ExtendsKeyword)?.types[0]
+      const name = statement.name?.text ?? (ts.getModifiers(statement)?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword) ? 'default' : null)
+      if (name) declarations.set(name, { doc: docAbove(source, statement, refused), deprecated: false, propsType: base?.typeArguments?.[0] })
+      continue
+    }
+    // `export default memo(() => …)` and `export default function () {…}`: a part
+    // an app writes as its file's default, with no name of its own. Kept under
+    // `default`, with its comment and its props.
+    if (ts.isExportAssignment(statement) && !statement.isExportEquals && !ts.isIdentifier(statement.expression)) {
+      declarations.set('default', { doc: docAbove(source, statement, refused), deprecated: false, propsType: propsOfInitializer(statement.expression) })
+      continue
+    }
+    if (ts.isFunctionDeclaration(statement) && !statement.name && ts.getModifiers(statement)?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword)) {
+      declarations.set('default', { doc: docAbove(source, statement, refused), deprecated: false, propsType: propsTypeOf(statement.parameters) })
+      continue
+    }
+    if (!ts.isFunctionDeclaration(statement) && !ts.isVariableStatement(statement)) continue
+    const doc = docAbove(source, statement, refused)
     const deprecated = /(^|\n)@deprecated\b/.test(doc) || /\*\s*@deprecated\b/.test(source.slice(Math.max(0, statement.getFullStart()), statement.getStart()))
 
     if (ts.isFunctionDeclaration(statement) && statement.name) {
+      // Overloads: the first signature carries the comment and the props a caller
+      // sees; a later one, or the body, only fills in a comment the first lacks.
+      const held = declarations.get(statement.name.text)
+      if (held) {
+        if (!held.doc && doc) held.doc = doc
+        continue
+      }
       declarations.set(statement.name.text, { doc, deprecated, propsType: propsTypeOf(statement.parameters) })
       continue
     }
     if (ts.isVariableStatement(statement)) {
       for (const declaration of statement.declarationList.declarations) {
         if (!ts.isIdentifier(declaration.name)) continue
-        declarations.set(declaration.name.text, { doc, deprecated, propsType: propsOfInitializer(declaration.initializer) })
+        declarations.set(declaration.name.text, { doc, deprecated, propsType: propsOfInitializer(declaration.initializer) ?? propsOfAnnotation(declaration.type) })
       }
     }
   }
@@ -427,19 +497,34 @@ function readModule(source: string, sibling: Sibling = () => undefined) {
     // `type ToolbarInputProps = TextInputProps` — an alias, not an interface.
     const alias = aliases.get(name)
     if (alias) return resolveNode(alias, seen)
-    // Not declared here at all. Follow the import, but only into this package.
+    // Not declared here at all. Follow the import; the caller says where it may go.
     const from = importedFrom.get(name)
-    return (from?.startsWith('./') ? sibling(from.slice(2), name) : undefined) ?? EMPTY
+    return (from ? sibling(from.specifier, from.imported) : undefined) ?? EMPTY
   }
 
   /** What one declaration's first parameter takes. */
   const resolve = (propsType: ts.TypeNode | undefined): Resolved => resolveNode(propsType, new Set())
 
-  return { declarations, resolve, resolveName: (name: string) => resolveName(name, new Set()) }
+  // The file's own description, for an app's file of one part: the first `/**`
+  // at the very top, above the imports — where Peek and Ship write it — or else
+  // the one directly above the first thing that is not an import.
+  const jsdocAt = (node: ts.Node | undefined) => (node ? (ts.getLeadingCommentRanges(source, node.getFullStart()) ?? []).find((range) => source.slice(range.pos, range.pos + 3) === '/**') : undefined)
+  const headerRange = jsdocAt(file.statements[0]) ?? jsdocAt(opening)
+  return { declarations, headerDoc: headerRange ? headerComment(source, headerRange) : '', resolve, resolveName: (name: string) => resolveName(name, new Set()) }
+}
+
+/** The file's own header comment, cleaned the way `docAbove` cleans a declaration's. */
+function headerComment(source: string, range: ts.CommentRange): string {
+  return source
+    .slice(range.pos, range.end)
+    .split(/\r?\n/)
+    .map((line) => line.trim().replace(/^\/\*\*/, '').replace(/\*\/$/, '').replace(/^\*/, '').trim())
+    .join('\n')
+    .trim()
 }
 
 /** The `title` a stories file gives Storybook, and the stories it exports. */
-function readStories(source: string): { title: string | null; stories: string[] } {
+export function readStories(source: string): { title: string | null; stories: string[] } {
   const file = ts.createSourceFile('x.stories.tsx', source, ts.ScriptTarget.Latest, true)
   let title: string | null = null
   const stories: string[] = []
@@ -502,7 +587,7 @@ export function buildRegistry({ root = process.cwd(), repo = 'estiva-ui' }: Buil
     // The callback lets one file's props type reach a type declared in another
     // — `ToolbarButtonProps extends IconButtonProps`. It is only called later,
     // by which time this module is in the cache, so the recursion terminates.
-    const read = { ...readModule(readFileSync(join(src, file), 'utf8'), (module, typeName) => moduleOf(module).resolveName(typeName)), file: `src/${file}` }
+    const read = { ...readModule(readFileSync(join(src, file), 'utf8'), (specifier, typeName) => (specifier.startsWith('./') ? moduleOf(specifier.slice(2)).resolveName(typeName) : undefined)), file: `src/${file}` }
     modules.set(name, read)
     return read
   }
@@ -555,6 +640,7 @@ export function buildRegistry({ root = process.cwd(), repo = 'estiva-ui' }: Buil
       docsId: title ? `${sanitize(title)}--docs` : null,
       storyId: title && story ? toId(title, story) : null,
       docPage: pageFile,
+      app: null,
     })
   }
 
@@ -565,11 +651,13 @@ export function buildRegistry({ root = process.cwd(), repo = 'estiva-ui' }: Buil
   return {
     schemaVersion: SCHEMA_VERSION,
     builtFrom: {
+      kind: 'package',
       repo,
       package: manifest.name,
       packageVersion: manifest.version,
       exports: values.length,
       typeExports: exported.length - values.length,
+      files: null,
     },
     storybook: {
       docsPath: '/?path=/docs/{docsId}',
@@ -581,6 +669,7 @@ export function buildRegistry({ root = process.cwd(), repo = 'estiva-ui' }: Buil
     // hook included, each marked by `kind`. The field stays because the count
     // has to reconcile out loud — see validateRegistry.
     excluded: [],
+    filesWithoutParts: [],
   }
 }
 

package/src/registry/cli.ts

@@ -1,47 +1,59 @@
 /// <reference types="node" />
 /**
- * `estiva-ui` — the catalogue as a command (UIG-12; docs/GATES.md §23 for why
- * it ships in the package rather than as a script pasted into each repo).
+ * `estiva-ui` — the catalogue as a command (UIG-12, UIG-13; docs/GATES.md §23
+ * for why it ships in the package rather than as a script pasted into each repo).
  *
- *   estiva-ui find <words…> [--json] [--limit n]   what do we have for this?
- *   estiva-ui build [--out <path>]                 write registry.json
- *   estiva-ui check                                rebuild and compare; CI runs this
+ *   estiva-ui find <words…> [--also [name=]<folder>]… [--json] [--limit n]
+ *   estiva-ui build [--out <path>]
+ *   estiva-ui check
  *
- * `find` reads the committed `registry.json`: the one in the folder it is run
- * from, else the one shipped inside the installed package. So an app can ask
- * the question without a checkout of this repo. `build` and `check` read the
- * source, so they only mean anything inside the library they describe.
+ * Every command takes `--root <folder>` (the library it reads; default: here)
+ * and `--repo <name>` (what an app's entries are called; default: its package name).
+ *
+ * **In the package** (`@estiva-app/ui` itself): `build` writes the committed
+ * `registry.json`, and `check` rebuilds it and fails on a single byte of drift.
+ *
+ * **In an app**: nothing is committed (Katerina, 18 September 2026 — the
+ * package is public, the apps are private). `check` builds the app's catalogue
+ * and fails when a part has no one-line description or cannot be sorted; CI's
+ * `gate` job runs it. `build` writes the catalogue to a file only when asked.
+ *
+ * `find` searches the package's catalogue — the one shipped inside the installed
+ * package, or this repo's own in the package — plus, in an app, the app's own,
+ * built fresh, plus each `--also` app that sits beside it.
  */
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
-import { resolve } from 'node:path'
+import { basename, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { findInRegistry, formatFindings } from './find'
-import { validateRegistry, type Registry } from './schema'
+import { findInRegistries, formatFindings } from './find'
+import { CLASSES, validateRegistry, type Registry } from './schema'
 
 /**
- * The builder, loaded only when it is used.
+ * The builders, loaded only when they are used.
  *
- * It reads TypeScript with TypeScript, and `typescript` is a dev dependency of
+ * They read TypeScript with TypeScript, and `typescript` is a dev dependency of
  * the app that installs this package — a real one in Peek, Ship and this repo,
- * and possibly absent elsewhere. `find` needs none of it: it reads a JSON file.
- * A static import made the bundler put the whole builder in the same chunk as
- * `find`, so `npx estiva-ui find …` died with ERR_MODULE_NOT_FOUND before
- * opening the file it needed.
+ * and possibly absent elsewhere. A static import made the bundler put the whole
+ * builder in the same chunk as `find`, so `npx estiva-ui find …` died with
+ * ERR_MODULE_NOT_FOUND before opening the file it needed.
  */
-const builder = () => import('./build')
+const packageBuilder = () => import('./build')
+const appBuilder = () => import('./app')
 
 const [command, ...rest] = process.argv.slice(2)
+const VALUED = ['--limit', '--out', '--file', '--root', '--repo', '--also']
 const flag = (name: string) => rest.includes(`--${name}`)
 const value = (name: string) => {
   const at = rest.indexOf(`--${name}`)
   return at === -1 ? undefined : rest[at + 1]
 }
+const values = (name: string) => rest.flatMap((word, i) => (word === `--${name}` && rest[i + 1] !== undefined ? [rest[i + 1]] : []))
 /** Everything that is not a flag or a flag's value: the words of the question. */
 const plain = () => {
   const out: string[] = []
   for (let i = 0; i < rest.length; i++) {
     if (rest[i].startsWith('--')) {
-      if (rest[i] === '--limit' || rest[i] === '--out' || rest[i] === '--file') i += 1
+      if (VALUED.includes(rest[i])) i += 1
       continue
     }
     out.push(rest[i])
@@ -49,19 +61,24 @@ const plain = () => {
   return out
 }
 
-/** The committed file: where it is run, else the copy inside the installed package. */
-function registryPath(): string {
+const root = resolve(value('root') ?? '.')
+const manifestAt = (folder: string) => JSON.parse(readFileSync(resolve(folder, 'package.json'), 'utf8')) as { name?: string }
+/** The package itself, or an app that installs it. */
+const isPackage = existsSync(resolve(root, 'package.json')) && manifestAt(root).name === '@estiva-app/ui'
+
+/** The package's committed catalogue: `--file`, this repo's own in the package, else the copy inside the installed package. */
+function packageRegistryPath(): string {
   const named = value('file')
   if (named) return resolve(named)
-  const here = resolve(process.cwd(), 'registry.json')
-  if (existsSync(here)) return here
-  // dist/registry/cli.js → the package's own root.
+  if (isPackage) return resolve(root, 'registry.json')
+  // dist/registry/cli.js → the package's own root. Never an app's own folder:
+  // a registry.json there is the app's, written by `estiva-ui build`.
   return fileURLToPath(new URL('../../registry.json', import.meta.url))
 }
 
-function readRegistry(): Registry {
-  const path = registryPath()
-  if (!existsSync(path)) throw new Error(`no registry.json at ${path} — run "estiva-ui build" in the library first`)
+function readPackageRegistry(): Registry {
+  const path = packageRegistryPath()
+  if (!existsSync(path)) throw new Error(`no registry.json at ${path} — run "estiva-ui build" in the package first`)
   const registry = JSON.parse(readFileSync(path, 'utf8')) as Registry
   const problems = validateRegistry(registry)
   // A malformed catalogue is worse than none: it would answer, wrongly.
@@ -69,6 +86,22 @@ function readRegistry(): Registry {
   return registry
 }
 
+async function buildApp(folder: string, repo: string | undefined): Promise<Registry> {
+  const { buildAppRegistry } = await appBuilder()
+  const registry = buildAppRegistry({ root: folder, repo })
+  const problems = validateRegistry(registry)
+  if (problems.length) throw new Error(`the catalogue of ${registry.builtFrom.repo} does not match its own schema:\n  ${problems.join('\n  ')}`)
+  return registry
+}
+
+/** One line per kind, in a fixed order, so two runs read the same. */
+function summary(registry: Registry): string {
+  const count = (cls: string) => registry.entries.filter((entry) => entry.app?.class === cls).length
+  const kinds = CLASSES.map((cls) => `${count(cls)} ${cls}`).join(', ')
+  const files = registry.builtFrom.files ?? 0
+  return `${registry.builtFrom.repo}: ${registry.entries.length} parts in ${files - registry.filesWithoutParts.length} files (${registry.filesWithoutParts.length} more hold none) — ${kinds}. Every part is described and sorted.`
+}
+
 async function main(): Promise<number> {
   switch (command) {
     case 'find': {
@@ -77,37 +110,67 @@ async function main(): Promise<number> {
         process.stderr.write('estiva-ui find <words…> — what the thing you need does, in words\n')
         return 1
       }
-      const registry = readRegistry()
+      const registries: Registry[] = [readPackageRegistry()]
+      // An app that cannot be read is said out loud, and the rest still answer.
+      const add = async (folder: string, repo: string | undefined) => {
+        try {
+          registries.push(await buildApp(folder, repo))
+        } catch (error) {
+          const [first, ...more] = String(error instanceof Error ? error.message : error).split('\n')
+          process.stderr.write(`not searched: ${first}${more.length ? `\n${more.slice(0, 3).join('\n')}${more.length > 3 ? `\n  …and ${more.length - 3} more — run "estiva-ui check" there` : ''}` : ''}\n`)
+        }
+      }
+      if (!isPackage) await add(root, value('repo'))
+      for (const also of values('also')) {
+        const [name, folder] = also.includes('=') ? [also.slice(0, also.indexOf('=')), also.slice(also.indexOf('=') + 1)] : [undefined, also]
+        const at = resolve(root, folder)
+        if (!existsSync(resolve(at, 'package.json'))) {
+          process.stderr.write(`not searched: ${name ?? basename(at)} — nothing at ${at}\n`)
+          continue
+        }
+        await add(at, name)
+      }
       const limit = Number(value('limit') ?? 5)
-      const findings = findInRegistry(registry, query, { limit: Number.isFinite(limit) && limit > 0 ? limit : 5 })
+      const findings = findInRegistries(registries, query, { limit: Number.isFinite(limit) && limit > 0 ? limit : 5 })
       if (flag('json')) {
         process.stdout.write(`${JSON.stringify(findings.map((finding) => finding.entry), null, 2)}\n`)
         return 0
       }
-      process.stdout.write(`${formatFindings(registry, findings, query)}\n`)
+      process.stdout.write(`${formatFindings(registries, findings, query)}\n`)
       // Nothing found is not a failure — it is the answer that sends a session
       // to ask rather than to invent.
       return 0
     }
 
     case 'build': {
-      const { buildRegistry, serializeRegistry } = await builder()
-      const out = resolve(value('out') ?? 'registry.json')
-      const registry = buildRegistry()
-      const problems = validateRegistry(registry)
-      if (problems.length) {
-        process.stderr.write(`the registry this build produced does not match its own schema:\n  ${problems.join('\n  ')}\n`)
-        return 1
+      const out = resolve(root, value('out') ?? 'registry.json')
+      if (isPackage) {
+        const { buildRegistry, serializeRegistry } = await packageBuilder()
+        const registry = buildRegistry({ root })
+        const problems = validateRegistry(registry)
+        if (problems.length) {
+          process.stderr.write(`the registry this build produced does not match its own schema:\n  ${problems.join('\n  ')}\n`)
+          return 1
+        }
+        writeFileSync(out, serializeRegistry(registry), 'utf8')
+        process.stdout.write(`${out}: ${registry.entries.length} entries from ${registry.builtFrom.exports} exports\n`)
+        return 0
       }
+      const { serializeRegistry } = await packageBuilder()
+      const registry = await buildApp(root, value('repo'))
       writeFileSync(out, serializeRegistry(registry), 'utf8')
-      process.stdout.write(`${out}: ${registry.entries.length} entries from ${registry.builtFrom.exports} exports\n`)
+      process.stdout.write(`${out}: ${summary(registry)}\n`)
       return 0
     }
 
     case 'check': {
-      const { buildRegistry, serializeRegistry } = await builder()
-      const path = registryPath()
-      const built = buildRegistry()
+      if (!isPackage) {
+        process.stdout.write(`${summary(await buildApp(root, value('repo')))}\n`)
+        return 0
+      }
+      const { buildRegistry, serializeRegistry } = await packageBuilder()
+      const path = packageRegistryPath()
+      const built = buildRegistry({ root })
       const problems = validateRegistry(built)
       if (problems.length) {
         process.stderr.write(`the registry does not match its own schema:\n  ${problems.join('\n  ')}\n`)

package/src/registry/find.ts

@@ -86,6 +86,18 @@ const hit = (query: string, text: string) => words(text).some((word) => alike(qu
  * over `MenuPanel`, whose name carries one of them loudly.
  */
 export function findInRegistry(registry: Registry, query: string, { limit = 5 }: { limit?: number } = {}): Finding[] {
+  return findInRegistries([registry], query, { limit })
+}
+
+/**
+ * Search several catalogues as one: the package's, the app's own, and any app
+ * beside it (UIG-13).
+ *
+ * An app's pass-on is not a result of its own — it is the package's part, and
+ * the package's entry answers for it, saying which apps hand it on. At the
+ * same strength the package's part comes first: it is the one to reach for.
+ */
+export function findInRegistries(registries: Registry[], query: string, { limit = 5 }: { limit?: number } = {}): Finding[] {
   const all = words(query)
   // Drop the words that mean nothing. If the question was only those, keep them
   // rather than answer nothing at all.
@@ -94,7 +106,8 @@ export function findInRegistry(registry: Registry, query: string, { limit = 5 }:
   if (asked.length === 0) return []
 
   const findings: Finding[] = []
-  for (const entry of registry.entries) {
+  const entries = registries.flatMap((registry) => registry.entries).filter((entry) => entry.app?.class !== 're-export')
+  for (const entry of entries) {
     let score = 0
     let matched = 0
     const where = new Set<string>()
@@ -148,7 +161,8 @@ export function findInRegistry(registry: Registry, query: string, { limit = 5 }:
     if (matched > 0) findings.push({ entry, matched, score, where: [...where], props: [...byName] })
   }
 
-  findings.sort((a, b) => b.matched - a.matched || b.score - a.score || a.entry.name.localeCompare(b.entry.name))
+  const fromPackage = (finding: Finding) => (finding.entry.app === null ? 0 : 1)
+  findings.sort((a, b) => b.matched - a.matched || b.score - a.score || fromPackage(a) - fromPackage(b) || a.entry.name.localeCompare(b.entry.name))
   return findings.slice(0, limit)
 }
 
@@ -158,22 +172,45 @@ export function docsLink(registry: Registry, entry: RegistryEntry): string | nul
   return registry.storybook.devUrl + registry.storybook.docsPath.replace('{docsId}', entry.docsId)
 }
 
+/** What an app's part is, in the words the search prints. */
+const CLASS_WORDS: Record<string, string> = {
+  'one-off': 'used in one place',
+  reusable: 'used in several places',
+  'promote-candidate': 'used in several places; could move into the package',
+  unused: 'used nowhere in the app',
+}
+
 /** What the command prints: the import line first, because that is what the reader came for. */
-export function formatFindings(registry: Registry, findings: Finding[], query: string): string {
+export function formatFindings(searched: Registry | Registry[], findings: Finding[], query: string): string {
+  const registries = Array.isArray(searched) ? searched : [searched]
   if (findings.length === 0) {
     return [
-      `Nothing in ${registry.builtFrom.repo} matches "${query}".`,
+      `Nothing in ${registries.map((registry) => registry.builtFrom.repo).join(', ')} matches "${query}".`,
       'If nothing here does what you need, say so and ask — do not invent a component.',
     ].join('\n')
   }
+  const registryOf = (entry: RegistryEntry) => registries.find((registry) => registry.builtFrom.repo === entry.repo) ?? registries[0]
+  // Which apps hand a package part on, and from where: in Peek, `Button` is
+  // imported from `@/components/ui/Button`, and the answer should say so.
+  const handedOn = new Map<string, string[]>()
+  for (const registry of registries) {
+    for (const entry of registry.entries) {
+      if (entry.app?.class !== 're-export' || entry.app.handsOn === null) continue
+      handedOn.set(entry.app.handsOn, [...(handedOn.get(entry.app.handsOn) ?? []), `${entry.repo} hands it on${entry.name === entry.app.handsOn ? '' : ` as ${entry.name}`} from ${entry.importPath}`])
+    }
+  }
 
   const blocks = findings.map((finding) => {
     const { entry } = finding
+    const facts = entry.app
     const lines = [
-      `${entry.name}  ·  ${entry.kind}  ·  ${entry.repo}  (matched ${finding.where.join(', ')})`,
+      `${entry.name}  ·  ${facts ? CLASS_WORDS[facts.class] ?? facts.class : entry.kind}  ·  ${entry.repo}  (matched ${finding.where.join(', ')})`,
       `  ${entry.purpose}`,
-      `  import { ${entry.name} } from '${entry.importPath}'`,
+      facts?.defaultExport ? `  import ${entry.name} from '${entry.importPath}'` : `  import { ${entry.name} } from '${entry.importPath}'`,
     ]
+    if (!facts) for (const said of handedOn.get(entry.name) ?? []) lines.push(`  ${said}`)
+    if (facts?.packageNamesake) lines.push(`  the package has a ${facts.packageNamesake} too: check it first`)
+    if (facts && facts.usedIn.length) lines.push(`  used in ${facts.usedIn.slice(0, 2).join(', ')}${facts.usedIn.length > 2 ? ` and ${facts.usedIn.length - 2} more` : ''}`)
     if (entry.ownsBehaviours.length) lines.push(`  owns: ${entry.ownsBehaviours.map((owned) => owned.behaviour).join(' · ')}`)
     if (entry.variants.length) lines.push(`  ${entry.variants.map((variant) => `${variant.prop}: ${variant.values.join(' | ')}`).join('   ')}`)
     // The props the question named, with their own line — not all of them. A
@@ -185,8 +222,8 @@ export function formatFindings(registry: Registry, findings: Finding[], query: s
     for (const prop of shown) {
       if (prop) lines.push(`  ${prop.name}: ${prop.takes}${prop.note ? ` — ${prop.note}` : ''}`)
     }
-    if (entry.props.length) lines.push(`  ${entry.props.length} props in all; see the page for the rest`)
-    const link = docsLink(registry, entry)
+    if (entry.props.length) lines.push(`  ${entry.props.length} props in all; see ${entry.docsId ? 'the page' : entry.sourceFile} for the rest`)
+    const link = docsLink(registryOf(entry), entry)
     if (link) lines.push(`  ${link}`)
     return lines.join('\n')
   })

package/src/registry/index.ts

@@ -7,13 +7,20 @@
  *
  * The data itself is `registry.json` at the package's root, committed and
  * shipped. Read it with `estiva-ui find`, or import these to read it yourself.
+ * An app's own catalogue (UIG-13) is built from its code with
+ * `buildAppRegistry` each time it is read, and never committed.
  */
 export { buildRegistry, readIndexExports, serializeRegistry, type BuildOptions } from './build'
-export { docsLink, findInRegistry, formatFindings, type Finding } from './find'
+export { buildAppRegistry, type AppBuildOptions } from './app'
+export { docsLink, findInRegistries, findInRegistry, formatFindings, type Finding } from './find'
 export {
+  CLASSES,
   SCHEMA_VERSION,
   validateRegistry,
+  type AppFacts,
   type EntryBehaviour,
+  type EntryClass,
+  type FileWithoutPart,
   type EntryKind,
   type EntryStatus,
   type EntryVariant,