@ng-prism/core 22.5.0 → 22.7.0-beta.0

package/dist/builder/scanner/service/pipe-api.extractor.js

@@ -0,0 +1,72 @@
+import ts from 'typescript';
+import { getClassChain } from '../class-hierarchy.js';
+import { isDocumented, readDescription, readDocTags } from './doc-tags.js';
+import { extractMethod } from './member.extractor.js';
+import { describeSetupEntries } from './service-api.extractor.js';
+import { createTypeCollector } from './type-collector.js';
+/**
+ * What the API page of a pipe shows: the description and tags of the class,
+ * the signatures of `transform()`, its setup functions and tokens with their
+ * config tables, and every documented type all of them reach. A template only
+ * calls `transform()`: no other member is read, and none adds a type.
+ */
+export function extractPipeApi(classDecl, setupRefs, checker, exportIndex) {
+    const collector = createTypeCollector(checker, exportIndex);
+    const transform = extractTransform(classDecl, checker, collector);
+    const setup = describeSetupEntries(setupRefs, checker, collector);
+    const api = { tags: readDocTags(classDecl), transform, setup, types: collector.drain() };
+    // The class's own block only: unlike a member, a pipe does not take the description of its base class.
+    const description = readDescription(classDecl);
+    if (description)
+        api.description = description;
+    return api;
+}
+/**
+ * The signatures of `transform()` in the nearest class that declares it,
+ * which may be a base class that only exists as a declaration, such as
+ * `DatePipe` in the .d.ts of `@angular/common`: its overload signatures, or
+ * the one declaration when there are none. The implementation of overloads is
+ * not one a template can call. In a .d.ts every declaration is a signature.
+ *
+ * A signature without a doc block of its own takes the one of the
+ * implementation, then of the first documented signature of the same class,
+ * then of the first documented `transform()` of the nearest base class that has one.
+ * The implementation and a base class document the method as a whole, so all
+ * of their block is taken. Another signature's block is about that signature:
+ * its description and `@param` texts are taken, its tags are not, since an
+ * overload marked `@deprecated` does not deprecate the one that replaces it.
+ */
+function extractTransform(classDecl, checker, types) {
+    const levels = getClassChain(classDecl, checker).map(getTransformDeclarations);
+    const level = levels.findIndex((declarations) => declarations.length > 0);
+    if (level < 0)
+        return [];
+    const declarations = levels[level];
+    const signatures = declarations.filter((declaration) => !declaration.body);
+    const implementation = declarations.find((declaration) => declaration.body && isDocumented(declaration));
+    const sibling = signatures.find(isDocumented);
+    const fallback = implementation ?? sibling ?? findInheritedDocs(levels.slice(level + 1));
+    return (signatures.length > 0 ? signatures : declarations).map((signature) => {
+        const docs = isDocumented(signature) ? signature : (fallback ?? signature);
+        const method = extractMethod('transform', signature, docs, checker, types);
+        if (docs !== signature && docs === sibling)
+            method.tags = {};
+        return method;
+    });
+}
+/** The instance declarations of `transform()` in a class, in source order: the overload signatures and the implementation. */
+function getTransformDeclarations(classDecl) {
+    return classDecl.members.filter((member) => ts.isMethodDeclaration(member) &&
+        (ts.isIdentifier(member.name) || ts.isStringLiteral(member.name)) &&
+        member.name.text === 'transform' &&
+        !ts.getModifiers(member)?.some((modifier) => modifier.kind === ts.SyntaxKind.StaticKeyword));
+}
+/** The first documented `transform()` declaration in the nearest of the given base classes that has one. */
+function findInheritedDocs(levels) {
+    for (const declarations of levels) {
+        const documented = declarations.find(isDocumented);
+        if (documented)
+            return documented;
+    }
+    return undefined;
+}

package/dist/builder/scanner/service/service-api.extractor.d.ts

@@ -0,0 +1,14 @@
+import ts from 'typescript';
+import type { ApiSetupEntry, ServiceApi } from '../../../plugin/service.types.js';
+import type { ExportIndex } from './export-index.js';
+import { type SetupRef } from './setup.reader.js';
+import { type TypeCollector } from './type-collector.js';
+/**
+ * What the API page of a service shows: the description and tags of the
+ * class, its public members, its setup functions and tokens with their config
+ * tables, and every documented type all of them reach.
+ */
+export declare function extractServiceApi(classDecl: ts.ClassDeclaration, setupRefs: SetupRef[], checker: ts.TypeChecker, exportIndex: ExportIndex): ServiceApi;
+/** The setup functions and tokens of a service or a pipe, with their config tables; the types they reach go to `collector`. */
+export declare function describeSetupEntries(setupRefs: SetupRef[], checker: ts.TypeChecker, collector: TypeCollector): ApiSetupEntry[];
+//# sourceMappingURL=service-api.extractor.d.ts.map

package/dist/builder/scanner/service/service-api.extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-api.extractor.d.ts","sourceRoot":"","sources":["../../../../src/builder/scanner/service/service-api.extractor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,KAAK,EAAe,aAAa,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAE/F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,EAAE,KAAK,QAAQ,EAAmB,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAK9E;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,EAAE,CAAC,gBAAgB,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,EAAE,CAAC,WAAW,EAAE,WAAW,EAAE,WAAW,GAAG,UAAU,CAUtJ;AAED,+HAA+H;AAC/H,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,EAAE,CAAC,WAAW,EAAE,SAAS,EAAE,aAAa,GAAG,aAAa,EAAE,CAE9H"}

package/dist/builder/scanner/service/service-api.extractor.js

@@ -0,0 +1,119 @@
+import ts from 'typescript';
+import { readDescription, readDocTags } from './doc-tags.js';
+import { extractMembers, extractMethod, extractObjectTypeMembers, firstParameter } from './member.extractor.js';
+import { skipParentheses } from './setup.reader.js';
+import { createTypeCollector } from './type-collector.js';
+/** The wrappers a config table looks through. */
+const CONFIG_WRAPPERS = new Set(['Partial', 'Required', 'Readonly']);
+/**
+ * What the API page of a service shows: the description and tags of the
+ * class, its public members, its setup functions and tokens with their config
+ * tables, and every documented type all of them reach.
+ */
+export function extractServiceApi(classDecl, setupRefs, checker, exportIndex) {
+    const collector = createTypeCollector(checker, exportIndex);
+    const { properties, methods } = extractMembers(classDecl, checker, collector);
+    const setup = describeSetupEntries(setupRefs, checker, collector);
+    const api = { tags: readDocTags(classDecl), properties, methods, setup, types: collector.drain() };
+    const description = readDescription(classDecl);
+    if (description)
+        api.description = description;
+    return api;
+}
+/** The setup functions and tokens of a service or a pipe, with their config tables; the types they reach go to `collector`. */
+export function describeSetupEntries(setupRefs, checker, collector) {
+    return setupRefs.map((ref) => (ref.kind === 'function' ? describeSetupFunction(ref, checker, collector) : describeSetupToken(ref, checker, collector)));
+}
+/** A setup function: its signature and docs, and the options of its first parameter when that is an object. */
+function describeSetupFunction({ name, declaration, importPath }, checker, collector) {
+    const fn = ts.isFunctionDeclaration(declaration) ? declaration : skipParentheses(declaration.initializer);
+    const { params, returnType, description, tags } = extractMethod(name, fn, docNodeOf(declaration), checker, collector);
+    const entry = { name, kind: 'function', importPath, tags, params, returnType };
+    const param = firstParameter(fn);
+    const config = param && readConfig(param.type, checker.getTypeAtLocation(param), checker, collector.within(params[0].name));
+    if (description)
+        entry.description = description;
+    if (config)
+        entry.config = config;
+    return entry;
+}
+/** A token: `InjectionToken<T>` as written, and the options of `T` when that is an object. */
+function describeSetupToken({ name, declaration, importPath }, checker, collector) {
+    // A token is always a `const`: the setup reader takes no other declaration for one.
+    const variable = declaration;
+    const typeNode = variable.type;
+    const type = checker.getTypeAtLocation(variable.name);
+    const docs = docNodeOf(variable);
+    const entry = {
+        name,
+        kind: 'token',
+        importPath,
+        tags: readDocTags(docs),
+        tokenType: collector.ref(typeNode, type, `type of ${name}`, { kind: 'property', name })
+    };
+    const argumentNode = typeNode && ts.isTypeReferenceNode(typeNode) ? typeNode.typeArguments?.[0] : undefined;
+    const argument = argumentNode ? checker.getTypeFromTypeNode(argumentNode) : isTypeReference(type) ? checker.getTypeArguments(type)[0] : undefined;
+    const config = argument && readConfig(argumentNode, argument, checker, collector.within(name));
+    const description = readDescription(docs);
+    if (description)
+        entry.description = description;
+    if (config)
+        entry.config = config;
+    return entry;
+}
+/** The doc block of a `const` sits on its statement, not on the declaration. */
+function docNodeOf(declaration) {
+    return ts.isVariableDeclaration(declaration) && ts.isVariableStatement(declaration.parent.parent) ? declaration.parent.parent : declaration;
+}
+/**
+ * The options of a config object: the properties of an interface, an object
+ * literal type or an object type alias, looked for through `Partial`,
+ * `Required` and `Readonly`, which change what the options say. `undefined`
+ * for anything else, a class or an array or a primitive.
+ */
+function readConfig(typeNode, type, checker, types) {
+    const wrappers = [];
+    let node = typeNode;
+    // The type as annotated: the parameter's own type has `undefined` in it when the parameter is optional.
+    let current = node ? checker.getTypeFromTypeNode(node) : checker.getNonNullableType(type);
+    // Through the annotation where there is one, through the alias the checker keeps otherwise.
+    for (;;) {
+        if (node && ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName) && CONFIG_WRAPPERS.has(node.typeName.text) && node.typeArguments?.length === 1) {
+            wrappers.push(node.typeName.text);
+            node = node.typeArguments[0];
+            current = checker.getTypeFromTypeNode(node);
+        }
+        else if (!node && current.aliasSymbol && CONFIG_WRAPPERS.has(current.aliasSymbol.name) && current.aliasTypeArguments?.length === 1) {
+            wrappers.push(current.aliasSymbol.name);
+            current = current.aliasTypeArguments[0];
+        }
+        else {
+            break;
+        }
+    }
+    if (!isConfigObject(current, checker))
+        return undefined;
+    const { properties } = extractObjectTypeMembers(current, checker, types);
+    // The innermost wrapper first: `Partial<Required<T>>` leaves every option optional.
+    for (const wrapper of wrappers.reverse())
+        properties.forEach((option) => applyWrapper(wrapper, option));
+    return properties.length > 0 ? properties : undefined;
+}
+function applyWrapper(wrapper, option) {
+    if (wrapper === 'Partial')
+        option.optional = true;
+    else if (wrapper === 'Required')
+        delete option.optional;
+    else
+        option.readonly = true;
+}
+function isConfigObject(type, checker) {
+    if (type.isIntersection())
+        return type.types.every((part) => isConfigObject(part, checker));
+    if (!(type.flags & ts.TypeFlags.Object) || type.objectFlags & ts.ObjectFlags.Class)
+        return false;
+    return !checker.isArrayType(type) && !checker.isTupleType(type) && type.getCallSignatures().length === 0;
+}
+function isTypeReference(type) {
+    return !!(type.flags & ts.TypeFlags.Object) && !!(type.objectFlags & ts.ObjectFlags.Reference);
+}

package/dist/builder/scanner/service/setup.reader.d.ts

@@ -0,0 +1,26 @@
+import ts from 'typescript';
+import type { ExportIndex } from './export-index.js';
+/** One entry of a service's `setup`: what the styleguide shows to configure the service, and where to import it from. */
+export interface SetupRef {
+    name: string;
+    kind: 'function' | 'token';
+    declaration: ts.FunctionDeclaration | ts.VariableDeclaration;
+    importPath: string;
+}
+/** Only the literal: a `setup` that arrives through a spread or a constant is not found, and dropped without a word. */
+export declare function findSetupProperty(showcaseArg: ts.Expression): ts.ObjectLiteralElementLike | undefined;
+/**
+ * Read the functions and tokens a service names in `setup: () => [provideToast, TOAST_LABELS]`.
+ *
+ * `setup` is an arrow function, not an array, so that the imports it refers to
+ * are only touched when it runs: a showcase file that imports from a module
+ * which imports the service back would otherwise hit the temporal dead zone.
+ * The scanner never runs it. It reads the array literal in the source and
+ * traces each element to its declaration, and to the entry point that exports it.
+ *
+ * What cannot be read is reported and dropped: a `setup` of another shape as a
+ * whole, any other entry on its own.
+ */
+export declare function readSetupRefs(showcaseArg: ts.Expression, className: string, checker: ts.TypeChecker, exportIndex: ExportIndex, report: (message: string) => void): SetupRef[];
+export declare function skipParentheses(expression: ts.Expression): ts.Expression;
+//# sourceMappingURL=setup.reader.d.ts.map

package/dist/builder/scanner/service/setup.reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.reader.d.ts","sourceRoot":"","sources":["../../../../src/builder/scanner/service/setup.reader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,yHAAyH;AACzH,MAAM,WAAW,QAAQ;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC;IAC3B,WAAW,EAAE,EAAE,CAAC,mBAAmB,GAAG,EAAE,CAAC,mBAAmB,CAAC;IAC7D,UAAU,EAAE,MAAM,CAAC;CACtB;AAED,wHAAwH;AACxH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,EAAE,CAAC,UAAU,GAAG,EAAE,CAAC,wBAAwB,GAAG,SAAS,CAIrG;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CACzB,WAAW,EAAE,EAAE,CAAC,UAAU,EAC1B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,EAAE,CAAC,WAAW,EACvB,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAClC,QAAQ,EAAE,CAkCZ;AAaD,wBAAgB,eAAe,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,GAAG,EAAE,CAAC,UAAU,CAKxE"}

package/dist/builder/scanner/service/setup.reader.js

@@ -0,0 +1,89 @@
+import ts from 'typescript';
+import { describeInvalidSetup, describeSetupEntryNotExported, describeSetupEntryNotSupported } from '../showcase-diagnostics.js';
+/** Only the literal: a `setup` that arrives through a spread or a constant is not found, and dropped without a word. */
+export function findSetupProperty(showcaseArg) {
+    if (!ts.isObjectLiteralExpression(showcaseArg))
+        return undefined;
+    return showcaseArg.properties.find((p) => p.name !== undefined && (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) && p.name.text === 'setup');
+}
+/**
+ * Read the functions and tokens a service names in `setup: () => [provideToast, TOAST_LABELS]`.
+ *
+ * `setup` is an arrow function, not an array, so that the imports it refers to
+ * are only touched when it runs: a showcase file that imports from a module
+ * which imports the service back would otherwise hit the temporal dead zone.
+ * The scanner never runs it. It reads the array literal in the source and
+ * traces each element to its declaration, and to the entry point that exports it.
+ *
+ * What cannot be read is reported and dropped: a `setup` of another shape as a
+ * whole, any other entry on its own.
+ */
+export function readSetupRefs(showcaseArg, className, checker, exportIndex, report) {
+    const property = findSetupProperty(showcaseArg);
+    if (!property)
+        return [];
+    const array = ts.isPropertyAssignment(property) ? readSetupArray(property.initializer) : undefined;
+    if (!array) {
+        report(describeInvalidSetup(className, ts.isPropertyAssignment(property) ? property.initializer : property));
+        return [];
+    }
+    const refs = [];
+    array.elements.forEach((element, index) => {
+        const symbol = resolveEntry(element, checker);
+        const target = symbol && classifyEntry(symbol, checker);
+        if (!symbol || !target) {
+            report(describeSetupEntryNotSupported(className, index, element));
+            return;
+        }
+        const importPath = exportIndex.get(symbol);
+        if (importPath === undefined) {
+            report(describeSetupEntryNotExported(className, index, element));
+            return;
+        }
+        refs.push({ name: symbol.name, ...target, importPath });
+    });
+    return refs;
+}
+/** The array literal an arrow function returns, as an expression body or as the only statement of a block. */
+function readSetupArray(initializer) {
+    if (!ts.isArrowFunction(initializer))
+        return undefined;
+    const { body } = initializer;
+    const returned = ts.isBlock(body) ? (body.statements.length === 1 && ts.isReturnStatement(body.statements[0]) ? body.statements[0].expression : undefined) : body;
+    const value = returned && skipParentheses(returned);
+    return value && ts.isArrayLiteralExpression(value) ? value : undefined;
+}
+export function skipParentheses(expression) {
+    let current = expression;
+    while (ts.isParenthesizedExpression(current))
+        current = current.expression;
+    return current;
+}
+/**
+ * The declaration symbol an entry refers to, with an import followed to its
+ * source: the symbol the export index holds. Only a name or a property access
+ * (`toasts.provideToast`) can refer to one; a call or a spread cannot.
+ */
+function resolveEntry(element, checker) {
+    if (!ts.isIdentifier(element) && !ts.isPropertyAccessExpression(element))
+        return undefined;
+    const symbol = checker.getSymbolAtLocation(element);
+    if (!symbol)
+        return undefined;
+    // A declaration that is exported from its own file is a local symbol there, and the export symbol is the one that is indexed.
+    return checker.getExportSymbolOfSymbol(symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol);
+}
+function classifyEntry(symbol, checker) {
+    for (const declaration of symbol.declarations ?? []) {
+        if (ts.isFunctionDeclaration(declaration))
+            return { kind: 'function', declaration };
+        if (!ts.isVariableDeclaration(declaration) || !(ts.getCombinedNodeFlags(declaration) & ts.NodeFlags.Const))
+            continue;
+        const initializer = declaration.initializer && skipParentheses(declaration.initializer);
+        if (initializer && (ts.isArrowFunction(initializer) || ts.isFunctionExpression(initializer)))
+            return { kind: 'function', declaration };
+        if (checker.getTypeAtLocation(declaration.name).getSymbol()?.name === 'InjectionToken')
+            return { kind: 'token', declaration };
+    }
+    return undefined;
+}

package/dist/builder/scanner/service/type-collector.d.ts

@@ -0,0 +1,23 @@
+import ts from 'typescript';
+import type { ApiTypeDoc } from '../../../plugin/service.types.js';
+import type { ExportIndex } from './export-index.js';
+import { type TypeRefResolver } from './member.extractor.js';
+/** A {@link TypeRefResolver} that links the documented types it meets and collects them for `ServiceApi.types`. */
+export interface TypeCollector extends TypeRefResolver {
+    /** A resolver for the members of the value at `path`, e.g. the options of a setup function's `config`. */
+    within(path: string): TypeRefResolver;
+    /** Documents what was reached so far, and what their members reach in turn, in the order of first reach. */
+    drain(): ApiTypeDoc[];
+}
+/**
+ * Collects the types a service's API reaches. A type is documented when it is
+ * an interface, class, type alias or enum, a scanned entry point exports it,
+ * and it is not tagged `@internal`. Anything else, `Signal` or `Provider` or a
+ * type the library keeps to itself, stays text without a link.
+ *
+ * Each type is documented once, under the id it got when it was first
+ * reached: its name, or `${name}@${importPath}` when a type of that name was
+ * reached before. That also ends a type that refers to itself.
+ */
+export declare function createTypeCollector(checker: ts.TypeChecker, exportIndex: ExportIndex): TypeCollector;
+//# sourceMappingURL=type-collector.d.ts.map

package/dist/builder/scanner/service/type-collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-collector.d.ts","sourceRoot":"","sources":["../../../../src/builder/scanner/service/type-collector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,KAAK,EAA0B,UAAU,EAAc,MAAM,kCAAkC,CAAC;AAEvG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAA8E,KAAK,eAAe,EAAiB,MAAM,uBAAuB,CAAC;AAexJ,mHAAmH;AACnH,MAAM,WAAW,aAAc,SAAQ,eAAe;IAClD,0GAA0G;IAC1G,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAAC;IACtC,4GAA4G;IAC5G,KAAK,IAAI,UAAU,EAAE,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,EAAE,CAAC,WAAW,EAAE,WAAW,EAAE,WAAW,GAAG,aAAa,CAqGpG"}

package/dist/builder/scanner/service/type-collector.js

@@ -0,0 +1,210 @@
+import ts from 'typescript';
+import { isInternal, readDescription, readDocTags } from './doc-tags.js';
+import { collapseWhitespace, extractMembers, extractObjectTypeMembers, readTypeText } from './member.extractor.js';
+/**
+ * Collects the types a service's API reaches. A type is documented when it is
+ * an interface, class, type alias or enum, a scanned entry point exports it,
+ * and it is not tagged `@internal`. Anything else, `Signal` or `Provider` or a
+ * type the library keeps to itself, stays text without a link.
+ *
+ * Each type is documented once, under the id it got when it was first
+ * reached: its name, or `${name}@${importPath}` when a type of that name was
+ * reached before. That also ends a type that refers to itself.
+ */
+export function createTypeCollector(checker, exportIndex) {
+    /** Every symbol met so far: what it was reached as, or `null` when it is not documented. */
+    const reached = new Map();
+    const ids = new Set();
+    const queue = [];
+    const docs = [];
+    function collect(typeNode, type, reachedFrom, path) {
+        const links = [];
+        const visit = (symbol) => {
+            const target = reach(symbol, reachedFrom, path);
+            if (target && !links.includes(target.id))
+                links.push(target.id);
+        };
+        if (typeNode)
+            forEachReferenceInNode(typeNode, checker, visit);
+        else
+            forEachReferenceInType(type, checker, visit, new Set());
+        const text = readTypeText(checker, typeNode, type);
+        return links.length > 0 ? { text, links } : { text };
+    }
+    function reach(symbol, reachedFrom, path) {
+        const target = resolveSymbol(symbol, checker);
+        const known = reached.get(target);
+        if (known !== undefined)
+            return known ?? undefined;
+        const declaration = target.declarations?.find(isDocumentedKind);
+        const importPath = exportIndex.get(target);
+        if (!declaration || importPath === undefined || isInternal(declaration)) {
+            reached.set(target, null);
+            return undefined;
+        }
+        const id = ids.has(target.name) ? `${target.name}@${importPath}` : target.name;
+        const entry = { id, symbol: target, declaration, importPath, reachedFrom, path: path ?? target.name };
+        ids.add(id);
+        reached.set(target, entry);
+        queue.push(entry);
+        return entry;
+    }
+    function within(owner) {
+        return {
+            ref(typeNode, type, reachedFrom, site) {
+                switch (site?.kind) {
+                    case 'property':
+                        return collect(typeNode, type, `via ${owner}.${site.name}`, `${owner}.${site.name}`);
+                    case 'parameter':
+                        return collect(typeNode, type, `parameter of ${owner}.${site.method}()`, site.name);
+                    case 'return':
+                        return collect(typeNode, type, `returned by ${owner}.${site.method}()`, `${owner}.${site.method}()`);
+                    default:
+                        return collect(typeNode, type, `via ${owner}`, owner);
+                }
+            }
+        };
+    }
+    function describe({ id, symbol, declaration, importPath, reachedFrom, path }) {
+        const doc = { id, name: symbol.name, kind: kindOf(declaration), importPath, tags: readDocTags(declaration) };
+        const description = readDescription(declaration);
+        const members = within(path);
+        if (description)
+            doc.description = description;
+        if (ts.isClassDeclaration(declaration)) {
+            assignMembers(doc, extractMembers(declaration, checker, members));
+        }
+        else if (ts.isInterfaceDeclaration(declaration)) {
+            assignMembers(doc, extractObjectTypeMembers(checker.getDeclaredTypeOfSymbol(symbol), checker, members));
+        }
+        else if (ts.isEnumDeclaration(declaration)) {
+            doc.members = declaration.members.filter((member) => !isInternal(member)).map((member) => describeEnumMember(member, checker));
+        }
+        else if (isLiteralUnion(declaration.type)) {
+            doc.union = declaration.type.types.map((member) => member.getText());
+        }
+        else if (ts.isTypeLiteralNode(declaration.type)) {
+            assignMembers(doc, extractObjectTypeMembers(checker.getDeclaredTypeOfSymbol(symbol), checker, members));
+        }
+        else {
+            // The text has no links of its own, but the types it names are reached all the same.
+            doc.text = collect(declaration.type, checker.getDeclaredTypeOfSymbol(symbol), `via ${path}`, path).text;
+        }
+        doc.reachedFrom = reachedFrom;
+        return doc;
+    }
+    return {
+        ref: (typeNode, type, reachedFrom, site) => collect(typeNode, type, reachedFrom, site && pathOf(site)),
+        within,
+        drain() {
+            // Describing a type reaches the types of its members, which join the queue behind it.
+            while (docs.length < queue.length)
+                docs.push(describe(queue[docs.length]));
+            return [...docs];
+        }
+    };
+}
+/** The value a type at the top level is the type of: a property, a parameter by its name, or `show()` for a return value. */
+function pathOf(site) {
+    return site.kind === 'return' ? `${site.method}()` : site.name;
+}
+/**
+ * The declaration a reference ends at: an import followed to its source, the
+ * export symbol of a declaration exported from its own file, an enum for one
+ * of its members. That is the symbol the export index holds.
+ */
+function resolveSymbol(symbol, checker) {
+    let target = symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+    if (target.flags & ts.SymbolFlags.EnumMember && target.valueDeclaration && ts.isEnumDeclaration(target.valueDeclaration.parent)) {
+        target = checker.getSymbolAtLocation(target.valueDeclaration.parent.name) ?? target;
+    }
+    return checker.getExportSymbolOfSymbol(target);
+}
+function isDocumentedKind(declaration) {
+    return ts.isInterfaceDeclaration(declaration) || ts.isClassDeclaration(declaration) || ts.isTypeAliasDeclaration(declaration) || ts.isEnumDeclaration(declaration);
+}
+function kindOf(declaration) {
+    if (ts.isInterfaceDeclaration(declaration))
+        return 'interface';
+    if (ts.isClassDeclaration(declaration))
+        return 'class';
+    if (ts.isEnumDeclaration(declaration))
+        return 'enum';
+    return 'type';
+}
+/** `'top-left' | 'top-right'`, `1 | 2` or `true | null`: a union of literals only. */
+function isLiteralUnion(node) {
+    return ts.isUnionTypeNode(node) && node.types.every(ts.isLiteralTypeNode);
+}
+function assignMembers(doc, { properties, methods }) {
+    if (properties.length > 0)
+        doc.properties = properties;
+    if (methods.length > 0)
+        doc.methods = methods;
+}
+/** The initializer as written, or the value TypeScript counts up to without one. */
+function describeEnumMember(member, checker) {
+    const result = {
+        name: ts.isIdentifier(member.name) || ts.isStringLiteral(member.name) ? member.name.text : member.name.getText()
+    };
+    const value = member.initializer ? collapseWhitespace(member.initializer.getText()) : checker.getConstantValue(member)?.toString();
+    const description = readDescription(member);
+    if (value !== undefined)
+        result.value = value;
+    if (description)
+        result.description = description;
+    return result;
+}
+/** Every type reference in an annotation: in type arguments, arrays, unions and object literal types too. */
+function forEachReferenceInNode(node, checker, visit) {
+    if (ts.isTypeReferenceNode(node)) {
+        const symbol = checker.getSymbolAtLocation(ts.isQualifiedName(node.typeName) ? node.typeName.right : node.typeName);
+        if (symbol)
+            visit(symbol);
+    }
+    ts.forEachChild(node, (child) => forEachReferenceInNode(child, checker, visit));
+}
+/**
+ * Every named type in a type without annotation, as `typeToString` prints it:
+ * an alias or a class or interface with their type arguments, the parts of a
+ * union or intersection, and the members of an object literal or function type.
+ */
+function forEachReferenceInType(type, checker, visit, seen) {
+    if (seen.has(type))
+        return;
+    seen.add(type);
+    const walk = (inner) => forEachReferenceInType(inner, checker, visit, seen);
+    if (type.aliasSymbol) {
+        visit(type.aliasSymbol);
+        type.aliasTypeArguments?.forEach(walk);
+        return;
+    }
+    // An enum, or one of its members.
+    if (type.flags & ts.TypeFlags.EnumLiteral && type.symbol) {
+        visit(type.symbol);
+        return;
+    }
+    if (type.isUnionOrIntersection()) {
+        type.types.forEach(walk);
+        return;
+    }
+    if (!(type.flags & ts.TypeFlags.Object))
+        return;
+    const { objectFlags } = type;
+    if (objectFlags & (ts.ObjectFlags.Class | ts.ObjectFlags.Interface | ts.ObjectFlags.Reference)) {
+        if (type.symbol)
+            visit(type.symbol);
+        if (objectFlags & ts.ObjectFlags.Reference)
+            checker.getTypeArguments(type).forEach(walk);
+        return;
+    }
+    if (objectFlags & ts.ObjectFlags.Anonymous) {
+        for (const property of type.getProperties())
+            walk(checker.getTypeOfSymbol(property));
+        for (const signature of type.getCallSignatures()) {
+            for (const parameter of signature.getParameters())
+                walk(checker.getTypeOfSymbol(parameter));
+            walk(signature.getReturnType());
+        }
+    }
+}

package/dist/builder/scanner/service.scanner.d.ts

@@ -0,0 +1,26 @@
+import ts from 'typescript';
+import type { ShowcaseConfig } from '../../decorator/showcase.types.js';
+import type { ScannedService } from '../../plugin/service.types.js';
+import type { ExportIndex } from './api/export-index.js';
+import { type ShowcasedClass } from './component.scanner.js';
+export interface ScanServicesOptions {
+    /** Built from every entry point of the library, since a setup function or a type is often exported by another one than the service. */
+    exportIndex: ExportIndex;
+    /** Shared with {@link scanComponents}, and across entry points, so that a service exported from several of them does not repeat its warnings. */
+    diagnostics: string[];
+    notices: Set<string>;
+}
+/**
+ * Read the services among the showcased classes of an entry point: classes
+ * with `@Injectable` or `@Service`, unless they declare fields only a component
+ * can use. Components are left to {@link scanComponents}.
+ *
+ * Nothing is run and the class is never imported: the service is read from the
+ * source, its API from the declarations, its `setup` from the array literal
+ * the arrow function returns. A service whose API cannot be read is left out
+ * with a notice, so that it does not take the whole scan down.
+ */
+export declare function scanServices(showcased: ShowcasedClass[], checker: ts.TypeChecker, { exportIndex, diagnostics, notices }: ScanServicesOptions): ScannedService[];
+/** `title` and whichever of the service fields the config sets: a component's `variants`, `bg` and the like mean nothing here. */
+export declare function pickServiceFields(config: ShowcaseConfig): ShowcaseConfig;
+//# sourceMappingURL=service.scanner.d.ts.map

package/dist/builder/scanner/service.scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.scanner.d.ts","sourceRoot":"","sources":["../../../src/builder/scanner/service.scanner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAEpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD,OAAO,EAA0C,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AASrG,MAAM,WAAW,mBAAmB;IAChC,uIAAuI;IACvI,WAAW,EAAE,WAAW,CAAC;IACzB,iJAAiJ;IACjJ,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,cAAc,EAAE,EAAE,OAAO,EAAE,EAAE,CAAC,WAAW,EAAE,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,mBAAmB,GAAG,cAAc,EAAE,CAoC/J;AAED,kIAAkI;AAClI,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAQxE"}