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

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"}

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

@@ -0,0 +1,61 @@
+import { readProvision } from './api/angular-decorators.js';
+import { extractServiceApi } from './api/service-api.extractor.js';
+import { readSetupRefs } from './api/setup.reader.js';
+import { createReporters, extractShowcaseConfig } from './component.scanner.js';
+import { describeUnreadableApi } from './showcase-diagnostics.js';
+/**
+ * The `@Showcase` fields that mean something for a service, and for a pipe, which the sidebar and the plugins treat the same way:
+ * what places it in the sidebar, and what a plugin may read.
+ */
+const SERVICE_CONFIG_FIELDS = ['description', 'category', 'categoryOrder', 'componentOrder', 'section', 'sectionOrder', 'tags', 'meta', 'status'];
+/**
+ * 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 function scanServices(showcased, checker, { exportIndex, diagnostics, notices }) {
+    const services = [];
+    const { report, notify } = createReporters(diagnostics, notices);
+    for (const { symbol, classDecl, decorator, argument, kind: classKind } of showcased) {
+        if (classKind.kind !== 'service')
+            continue;
+        const className = classDecl.name?.text ?? 'Anonymous';
+        const showcaseConfig = extractShowcaseConfig(decorator, className, report, checker);
+        if (!showcaseConfig || !argument)
+            continue;
+        let api;
+        try {
+            api = extractServiceApi(classDecl, readSetupRefs(argument, className, checker, exportIndex, report), checker, exportIndex);
+        }
+        catch (error) {
+            notify(describeUnreadableApi(className, error, 'service'));
+            continue;
+        }
+        const service = {
+            className,
+            filePath: classDecl.getSourceFile().fileName,
+            showcaseConfig: pickServiceFields(showcaseConfig),
+            provision: readProvision(classKind.decorator, checker),
+            api
+        };
+        const importPath = exportIndex.get(symbol);
+        if (importPath !== undefined)
+            service.importPath = importPath;
+        services.push(service);
+    }
+    return services;
+}
+/** `title` and whichever of the service fields the config sets: a component's `variants`, `bg` and the like mean nothing here. */
+export function pickServiceFields(config) {
+    const picked = { title: config.title };
+    for (const field of SERVICE_CONFIG_FIELDS) {
+        if (config[field] !== undefined)
+            Object.assign(picked, { [field]: config[field] });
+    }
+    return picked;
+}

package/dist/builder/scanner/showcase-diagnostics.d.ts

@@ -1,5 +1,5 @@
 import ts from 'typescript';
-import { type UnevaluableIssue } from './ast-utils.js';
+import { type EvaluationPath, type UnevaluableIssue } from './ast-utils.js';
 import type { UnreadableBase } from './class-hierarchy.js';
 /**
  * Describe one value the scanner had to drop from a `@Showcase` config:
@@ -8,6 +8,21 @@ import type { UnreadableBase } from './class-hierarchy.js';
  * `SguiFileInputComponent › variants[3] "Auto hint" › inputs.maxFileSize — "megabytes(5)" (src/file-input.component.ts:27:22) cannot be evaluated statically and was dropped.`
  */
 export declare function describeUnevaluable(className: string, config: ts.Expression, issue: UnevaluableIssue): string;
+/**
+ * Describe a value of a `@Showcase` config that is valid to the evaluator but not to the scan: which component, where
+ * in the config, what is wrong and where. `path` is read as in {@link describeUnevaluable}, with array indices as
+ * written in the source. The location is the node at `path` when the literal has one, else the whole config.
+ *
+ * `FormFieldComponent › variants[2] "Both" › content — set together with template; template wins and content was dropped (src/form-field.component.ts:31:9)`
+ */
+export declare function describeShowcaseIssue(className: string, config: ts.Expression, path: EvaluationPath, text: string): string;
+/**
+ * Name the places of a `@Showcase` config that something comes from, and where the first of them is written, read as
+ * in {@link describeShowcaseIssue}.
+ *
+ * `variants[0] "Default", variants[3] "Again" (src/form-field.component.ts:20:9)`
+ */
+export declare function describeShowcaseOrigin(config: ts.Expression, paths: readonly EvaluationPath[]): string;
 /**
  * `providers` never reached the manifest: classes, factories and instances
  * cannot be written into static data. One message for the field, not one per
@@ -22,4 +37,48 @@ export declare function describeDeprecatedProviders(className: string, config: t
  * knows which variant values will not reach the component.
  */
 export declare function describeUnreadableBase(className: string, base: UnreadableBase): string;
+/**
+ * A class with `@Injectable` or `@Service` that still declares fields only a
+ * component can use. Shown as a component for now, so nothing is lost, but
+ * the service page will not have these fields, which is why it is said early.
+ */
+export declare function describeLegacyServiceComponent(className: string, fields: string[]): string;
+/**
+ * A class with `@Pipe` that still declares fields only a component can use:
+ * the pipe counterpart of {@link describeLegacyServiceComponent}. A pipe declared
+ * in an NgModule (`standalone: false`) has more to lose, since ng-prism will not
+ * show it at all.
+ */
+export declare function describeLegacyPipeComponent(className: string, fields: string[], standalone: boolean): string;
+/** A pipe declared in an NgModule cannot be called from a template the styleguide builds, so it is not shown. */
+export declare function describePipeNotStandalone(className: string, node: ts.Node): string;
+/**
+ * The name is what a template calls the pipe by; without it the pipe has no
+ * usage to show. It points at the `name` property of the `@Pipe({ … })`
+ * literal if there is one, else at the decorator.
+ */
+export declare function describePipeNameUnreadable(className: string, decorator: ts.Decorator): string;
+/** `setup` lists what configures a service or a pipe; a component has no use for it, and says so instead of silently ignoring it. */
+export declare function describeSetupOnComponent(className: string, node: ts.Node): string;
+/**
+ * {@link describeSetupOnComponent} for a service or pipe that its component-only `fields` still keep a component:
+ * the class has the decorator the generic message names, so it says why that is not enough.
+ */
+export declare function describeSetupOnLegacyComponent(className: string, node: ts.Node, fields: string[]): string;
+/**
+ * The notice for an API the extractor could not read. A notice, not a diagnostic: no `@Showcase` value was dropped,
+ * so strictShowcase does not fail over it. A component keeps its page, which falls back to its inputs and outputs;
+ * a service or a pipe has nothing else to show and is left out.
+ */
+export declare function describeUnreadableApi(className: string, error: unknown, kind: 'component' | 'service' | 'pipe'): string;
+/**
+ * `setup` has to be readable without running anything: an arrow function whose
+ * body is an array literal. Anything else drops the whole field, since there is
+ * no telling which entries it would have listed.
+ */
+export declare function describeInvalidSetup(className: string, node: ts.Node): string;
+/** The styleguide shows where to import a `setup` entry from, which it only knows for what a library entry point exports. */
+export declare function describeSetupEntryNotExported(className: string, index: number, node: ts.Node): string;
+/** A `setup` entry stands for a provider function or an InjectionToken; a class, a plain value or a call is neither. */
+export declare function describeSetupEntryNotSupported(className: string, index: number, node: ts.Node): string;
 //# sourceMappingURL=showcase-diagnostics.d.ts.map

package/dist/builder/scanner/showcase-diagnostics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"showcase-diagnostics.d.ts","sourceRoot":"","sources":["../../../src/builder/scanner/showcase-diagnostics.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,EAA2C,KAAK,gBAAgB,EAA4B,MAAM,gBAAgB,CAAC;AAC1H,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAa3D;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,UAAU,EAAE,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAY7G;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,UAAU,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,GAAG,MAAM,CAO7G;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,MAAM,CAOtF"}
+{"version":3,"file":"showcase-diagnostics.d.ts","sourceRoot":"","sources":["../../../src/builder/scanner/showcase-diagnostics.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,EAAsB,KAAK,cAAc,EAAwB,KAAK,gBAAgB,EAA4B,MAAM,gBAAgB,CAAC;AAChJ,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAa3D;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,UAAU,EAAE,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAY7G;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,UAAU,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1H;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,EAAE,KAAK,EAAE,SAAS,cAAc,EAAE,GAAG,MAAM,CAEtG;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,UAAU,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,GAAG,MAAM,CAO7G;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,MAAM,CAOtF;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAK1F;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,OAAO,GAAG,MAAM,CAM5G;AAED,iHAAiH;AACjH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,MAAM,CAElF;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,CAAC,SAAS,GAAG,MAAM,CAK7F;AAED,qIAAqI;AACrI,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,MAAM,CAEjF;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAEzG;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAMvH;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,MAAM,CAK7E;AAED,6HAA6H;AAC7H,wBAAgB,6BAA6B,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,MAAM,CAKrG;AAED,wHAAwH;AACxH,wBAAgB,8BAA8B,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,MAAM,CAEtG"}

package/dist/builder/scanner/showcase-diagnostics.js

@@ -1,6 +1,6 @@
 import { relative } from 'node:path';
 import ts from 'typescript';
-import { evaluateExpression } from './ast-utils.js';
+import { evaluateExpression, getDecoratorArgument } from './ast-utils.js';
 const MAX_EXCERPT_LENGTH = 60;
 const CAUSES = {
     let: 'is declared with let; only const declarations can be read',
@@ -27,6 +27,25 @@ export function describeUnevaluable(className, config, issue) {
     const cause = issue.cause ? `: ${excerpt(issue.cause.node)} ${CAUSES[issue.cause.kind]}` : '';
     return `${className} › ${where} — "${excerpt(issue.node)}" (${location(issue.node)}) ${consequence}${cause}.`;
 }
+/**
+ * Describe a value of a `@Showcase` config that is valid to the evaluator but not to the scan: which component, where
+ * in the config, what is wrong and where. `path` is read as in {@link describeUnevaluable}, with array indices as
+ * written in the source. The location is the node at `path` when the literal has one, else the whole config.
+ *
+ * `FormFieldComponent › variants[2] "Both" › content — set together with template; template wins and content was dropped (src/form-field.component.ts:31:9)`
+ */
+export function describeShowcaseIssue(className, config, path, text) {
+    return `${className} › ${formatShowcasePath(path, config)} — ${text} (${location(nodeAtPath(config, path) ?? config)})`;
+}
+/**
+ * Name the places of a `@Showcase` config that something comes from, and where the first of them is written, read as
+ * in {@link describeShowcaseIssue}.
+ *
+ * `variants[0] "Default", variants[3] "Again" (src/form-field.component.ts:20:9)`
+ */
+export function describeShowcaseOrigin(config, paths) {
+    return `${paths.map((path) => formatShowcasePath(path, config)).join(', ')} (${location((paths[0] && nodeAtPath(config, paths[0])) ?? config)})`;
+}
 /**
  * `providers` never reached the manifest: classes, factories and instances
  * cannot be written into static data. One message for the field, not one per
@@ -49,6 +68,81 @@ export function describeUnreadableBase(className, base) {
     return (`${className} inherits ${base.inputs.join(', ')} from ${baseName}, which only exists as a declaration (${location(base.classDecl)}); ` +
         `without its source these inputs cannot be read, so they are missing from the manifest and variants cannot set them.`);
 }
+/**
+ * A class with `@Injectable` or `@Service` that still declares fields only a
+ * component can use. Shown as a component for now, so nothing is lost, but
+ * the service page will not have these fields, which is why it is said early.
+ */
+export function describeLegacyServiceComponent(className, fields) {
+    return (`${className} is an @Injectable/@Service with @Showcase and declares ${fields.join(', ')}, so it is still treated as a component. ` +
+        `From 23.0.0 it will be shown as a service and these fields will be dropped; remove them, or move the page to a componentPage.`);
+}
+/**
+ * A class with `@Pipe` that still declares fields only a component can use:
+ * the pipe counterpart of {@link describeLegacyServiceComponent}. A pipe declared
+ * in an NgModule (`standalone: false`) has more to lose, since ng-prism will not
+ * show it at all.
+ */
+export function describeLegacyPipeComponent(className, fields, standalone) {
+    const lead = `${className} is a @Pipe with @Showcase and declares ${fields.join(', ')}, so it is still treated as a component. `;
+    return standalone
+        ? `${lead}From 23.0.0 it will be shown as a pipe and these fields will be dropped; remove them, or move the page to a componentPage.`
+        : `${lead}From 23.0.0 it will be dropped, because ng-prism shows standalone pipes only; make the pipe standalone and remove the fields, or move the page to a componentPage.`;
+}
+/** A pipe declared in an NgModule cannot be called from a template the styleguide builds, so it is not shown. */
+export function describePipeNotStandalone(className, node) {
+    return `${className} › @Pipe (${location(node)}) is declared with standalone: false; ng-prism shows standalone pipes only, so it was dropped.`;
+}
+/**
+ * The name is what a template calls the pipe by; without it the pipe has no
+ * usage to show. It points at the `name` property of the `@Pipe({ … })`
+ * literal if there is one, else at the decorator.
+ */
+export function describePipeNameUnreadable(className, decorator) {
+    const arg = getDecoratorArgument(decorator);
+    const name = arg && ts.isObjectLiteralExpression(arg) ? findProperty(arg, 'name') : undefined;
+    return `${className} › @Pipe name (${location(name ?? decorator)}) cannot be evaluated statically, so the pipe was dropped.`;
+}
+/** `setup` lists what configures a service or a pipe; a component has no use for it, and says so instead of silently ignoring it. */
+export function describeSetupOnComponent(className, node) {
+    return `${className} › setup (${location(node)}) only applies to services and pipes (@Injectable, @Service or @Pipe); it was dropped.`;
+}
+/**
+ * {@link describeSetupOnComponent} for a service or pipe that its component-only `fields` still keep a component:
+ * the class has the decorator the generic message names, so it says why that is not enough.
+ */
+export function describeSetupOnLegacyComponent(className, node, fields) {
+    return `${className} › setup (${location(node)}) was dropped: setup only applies to services and pipes, and the class is still a component because it declares ${fields.join(', ')}.`;
+}
+/**
+ * The notice for an API the extractor could not read. A notice, not a diagnostic: no `@Showcase` value was dropped,
+ * so strictShowcase does not fail over it. A component keeps its page, which falls back to its inputs and outputs;
+ * a service or a pipe has nothing else to show and is left out.
+ */
+export function describeUnreadableApi(className, error, kind) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return kind === 'component'
+        ? `${className}: could not read its API for the API page (${reason}); the page falls back to its inputs and outputs.`
+        : `${className}: could not read its API (${reason}); the ${kind} is left out of the styleguide.`;
+}
+/**
+ * `setup` has to be readable without running anything: an arrow function whose
+ * body is an array literal. Anything else drops the whole field, since there is
+ * no telling which entries it would have listed.
+ */
+export function describeInvalidSetup(className, node) {
+    return (`${className} › setup — "${excerpt(node)}" (${location(node)}) must be an arrow function returning an array literal, ` +
+        `e.g. setup: () => [provideX]; setup was dropped.`);
+}
+/** The styleguide shows where to import a `setup` entry from, which it only knows for what a library entry point exports. */
+export function describeSetupEntryNotExported(className, index, node) {
+    return (`${className} › setup[${index}] — "${excerpt(node)}" (${location(node)}) is not exported from any library entry point, ` +
+        `so the styleguide cannot show where to import it from; it was dropped.`);
+}
+/** A `setup` entry stands for a provider function or an InjectionToken; a class, a plain value or a call is neither. */
+export function describeSetupEntryNotSupported(className, index, node) {
+    return `${className} › setup[${index}] — "${excerpt(node)}" (${location(node)}) is neither a function nor an InjectionToken; it was dropped.`;
+}
 /** A variant or a state is named by its `name` as well as its index, since that is what the styleguide shows. */
 function formatShowcasePath(path, config) {
     const [head, index, ...rest] = path;
@@ -77,6 +171,25 @@ function elementName(config, key, index) {
     const value = name && evaluateExpression(name);
     return typeof value === 'string' ? value : undefined;
 }
+/** The property or element the literal has at `path`, or `undefined` as soon as the literal stops spelling the path out, as with a spread or a constant. */
+function nodeAtPath(config, path) {
+    let container = config;
+    let found;
+    for (const segment of path) {
+        const member = typeof segment === 'number'
+            ? ts.isArrayLiteralExpression(container)
+                ? container.elements[segment]
+                : undefined
+            : ts.isObjectLiteralExpression(container)
+                ? findProperty(container, segment)
+                : undefined;
+        if (!member)
+            return undefined;
+        found = member;
+        container = ts.isPropertyAssignment(member) ? member.initializer : member;
+    }
+    return found;
+}
 function findProperty(object, key) {
     return object.properties.find((prop) => prop.name !== undefined && (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)) && prop.name.text === key);
 }

package/dist/builder/shared/prism-pipeline.d.ts

@@ -11,6 +11,10 @@ export interface PrismPipelineOptions {
 export interface PrismPipelineResult {
     manifestPath: string;
     componentCount: number;
+    /** Services in the manifest: 0 when no plugin shows services, however many the scan found. */
+    serviceCount: number;
+    /** Pipes in the manifest: 0 when no plugin shows pipes, however many the scan found. */
+    pipeCount: number;
     pageCount: number;
     /** True if the manifest file was actually written; false if the existing content was identical. */
     written: boolean;
@@ -19,6 +23,8 @@ export interface PrismPipelineState {
     scanner: Scanner | undefined;
     /** Sorted, joined entry-file paths. Used to detect when the entry set changed between rebuilds. */
     lastEntrySetKey: string | undefined;
+    /** Hints already logged in this builder run, so that `serve` does not repeat them on every rebuild. */
+    hints: Set<string>;
 }
 export declare function createPipelineState(): PrismPipelineState;
 export declare function runPrismPipeline(options: PrismPipelineOptions, context: BuilderContext, state: PrismPipelineState): Promise<PrismPipelineResult>;

package/dist/builder/shared/prism-pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prism-pipeline.d.ts","sourceRoot":"","sources":["../../../src/builder/shared/prism-pipeline.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAUhE,OAAO,EAAiB,KAAK,OAAO,EAAmB,MAAM,uBAAuB,CAAC;AAErF,MAAM,WAAW,oBAAoB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,mGAAmG;IACnG,OAAO,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IAC/B,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,mGAAmG;IACnG,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,wBAAgB,mBAAmB,IAAI,kBAAkB,CAExD;AAED,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,oBAAoB,EAAE,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA2FtJ"}
+{"version":3,"file":"prism-pipeline.d.ts","sourceRoot":"","sources":["../../../src/builder/shared/prism-pipeline.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAYhE,OAAO,EAAiB,KAAK,OAAO,EAAqC,MAAM,uBAAuB,CAAC;AAEvG,MAAM,WAAW,oBAAoB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,8FAA8F;IAC9F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,8FAA8F;IAC9F,YAAY,EAAE,MAAM,CAAC;IACrB,wFAAwF;IACxF,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,mGAAmG;IACnG,OAAO,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IAC/B,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,mGAAmG;IACnG,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,uGAAuG;IACvG,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACtB;AAED,wBAAgB,mBAAmB,IAAI,kBAAkB,CAExD;AAED,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,oBAAoB,EAAE,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA8ItJ"}