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

package/dist/builder/scanner/service/angular-decorators.js

@@ -0,0 +1,154 @@
+import ts from 'typescript';
+import { evaluateExpression, evaluateStatic, findDecorator, getDecoratorArgument, UNEVALUABLE } from '../ast-utils.js';
+const ANGULAR_CORE = '@angular/core';
+/**
+ * `@Showcase` fields that only a component can use. A class that carries
+ * one of them next to `@Injectable` or `@Pipe` is a component with that
+ * decorator, not a service or a pipe: showing it as one would drop the field.
+ */
+const COMPONENT_ONLY_FIELDS = ['variants', 'states', 'providers', 'bg', 'canvasLayout', 'host', 'renderPage'];
+/** The values of `providedIn` that make Angular provide a service without anyone listing it. */
+const AUTO_PROVIDED_IN = ['root', 'platform', 'any'];
+/**
+ * {@link findDecorator} for an Angular decorator: it only counts if the
+ * identifier is imported from `@angular/core`. A `@Service` from a
+ * dependency-injection package of another name has nothing to do with Angular's.
+ *
+ * The scanner never imports `Service` itself, since Angular 20 has none: the
+ * decorator is recognised in the source alone.
+ */
+export function findAngularCoreDecorator(classDecl, name, checker) {
+    const decorator = findDecorator(classDecl, name);
+    return decorator && isImportedFromAngularCore(decorator, name, checker) ? decorator : undefined;
+}
+/**
+ * Tell a service or a pipe from a component. They all carry `@Showcase`, and
+ * the only thing that tells them apart is the Angular decorator beside it.
+ *
+ * A class with `@Component` or `@Directive` is a component, whatever else it
+ * carries. Otherwise `@Pipe` makes it a pipe, and `@Service` or `@Injectable`
+ * a service, so that a pipe that is also injectable stays a pipe. Either is
+ * overruled by the `@Showcase` argument declaring a component-only field: such
+ * a class has been shown as a component so far, so it stays one
+ * (`legacy-component`) until 23.0.0, and the scan says why. That check comes
+ * first, before anything is said about the pipe itself.
+ *
+ * `showcaseArg` is read from the literal and from the evaluated value, since a
+ * constant or a spread can bring the field in and a field the evaluator cannot
+ * read is still in the literal.
+ */
+export function classifyShowcaseClass(classDecl, showcaseArg, checker) {
+    // Compared by name, as everywhere else in the scanner.
+    if (findDecorator(classDecl, 'Component') || findDecorator(classDecl, 'Directive'))
+        return { kind: 'component' };
+    const pipe = findAngularCoreDecorator(classDecl, 'Pipe', checker);
+    if (pipe) {
+        const fields = readComponentOnlyFields(showcaseArg, checker);
+        if (fields.length === 0)
+            return { kind: 'pipe', decorator: pipe };
+        return readPipeOptions(pipe, checker).standalone
+            ? { kind: 'legacy-component', fields, source: 'pipe' }
+            : { kind: 'legacy-component', fields, source: 'pipe', standalone: false };
+    }
+    const decorator = findAngularCoreDecorator(classDecl, 'Service', checker) ?? findAngularCoreDecorator(classDecl, 'Injectable', checker);
+    if (!decorator)
+        return { kind: 'component' };
+    const fields = readComponentOnlyFields(showcaseArg, checker);
+    return fields.length > 0 ? { kind: 'legacy-component', fields, source: 'injectable' } : { kind: 'service', decorator };
+}
+/**
+ * Whether Angular provides the service on its own (`auto`) or the user has to
+ * list it in a providers array (`manual`).
+ *
+ * `@Service()` is auto-provided unless it says `autoProvided: false`;
+ * `@Injectable` is when `providedIn` is `'root'`, `'platform'` or `'any'`.
+ * Anything else, such as no argument, no `providedIn`, a module class or a value
+ * the scan cannot read, is `manual`, without a warning: a service nobody
+ * provides is a normal thing to document.
+ */
+export function readProvision(decorator, checker) {
+    const isService = decoratorName(decorator) === 'Service';
+    const arg = getDecoratorArgument(decorator);
+    if (!arg)
+        return isService ? 'auto' : 'manual';
+    let unreadable = false;
+    const raw = evaluateStatic(arg, {
+        checker,
+        report: (issue) => {
+            // A `factory` is a runtime value and always dropped, which leaves the provision alone.
+            if (isService && issue.path[0] === 'autoProvided')
+                unreadable = true;
+        }
+    });
+    if (raw === UNEVALUABLE || typeof raw !== 'object' || raw === null)
+        return 'manual';
+    const options = raw;
+    if (isService)
+        return unreadable || options['autoProvided'] === false ? 'manual' : 'auto';
+    return AUTO_PROVIDED_IN.includes(options['providedIn']) ? 'auto' : 'manual';
+}
+/**
+ * Read `name`, `pure` and `standalone` from the `@Pipe` metadata.
+ *
+ * Nothing that cannot be read is guessed: a `name` or `pure` the source does not
+ * give as a constant is left out, so that the caller can say so, while
+ * `standalone` only counts as `false` when the source says exactly that.
+ */
+export function readPipeOptions(decorator, checker) {
+    const arg = getDecoratorArgument(decorator);
+    let unreadable = false;
+    const raw = arg
+        ? evaluateStatic(arg, {
+            checker,
+            report: (issue) => {
+                // The whole argument or a spread that fails could have carried `pure` along, so it counts for it too.
+                if (issue.path.length === 0 || issue.path[0] === 'pure')
+                    unreadable = true;
+            }
+        })
+        : {};
+    const options = typeof raw === 'object' && raw !== null ? raw : {};
+    const result = { standalone: options['standalone'] !== false };
+    if (typeof options['name'] === 'string')
+        result.name = options['name'];
+    if (typeof options['pure'] === 'boolean')
+        result.pure = options['pure'];
+    else if (!unreadable && options['pure'] === undefined)
+        result.pure = true;
+    return result;
+}
+function isImportedFromAngularCore(decorator, name, checker) {
+    const expr = ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression;
+    if (!ts.isIdentifier(expr))
+        return false;
+    return (checker.getSymbolAtLocation(expr)?.declarations?.some((decl) => {
+        if (!ts.isImportSpecifier(decl))
+            return false;
+        const importDeclaration = decl.parent.parent.parent;
+        // `import { Injectable as Service }` is Angular's Injectable, not its Service.
+        return (ts.isStringLiteral(importDeclaration.moduleSpecifier) &&
+            importDeclaration.moduleSpecifier.text === ANGULAR_CORE &&
+            (decl.propertyName ?? decl.name).text === name);
+    }) ?? false);
+}
+function decoratorName(decorator) {
+    const expr = ts.isCallExpression(decorator.expression) ? decorator.expression.expression : decorator.expression;
+    return ts.isIdentifier(expr) ? expr.text : undefined;
+}
+function readComponentOnlyFields(showcaseArg, checker) {
+    if (!showcaseArg)
+        return [];
+    const declared = new Set();
+    if (ts.isObjectLiteralExpression(showcaseArg)) {
+        for (const prop of showcaseArg.properties) {
+            if (prop.name && (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)))
+                declared.add(prop.name.text);
+        }
+    }
+    const evaluated = evaluateExpression(showcaseArg, checker);
+    if (typeof evaluated === 'object' && evaluated !== null) {
+        for (const key of Object.keys(evaluated))
+            declared.add(key);
+    }
+    return COMPONENT_ONLY_FIELDS.filter((field) => declared.has(field));
+}

package/dist/builder/scanner/service/doc-tags.d.ts

@@ -0,0 +1,13 @@
+import ts from 'typescript';
+import type { ApiDocTags } from '../../../plugin/service.types.js';
+/** The comment text of a node without its tags, as written: line breaks and markdown stay. */
+export declare function readDescription(node: ts.Node): string | undefined;
+/** The tags of a node. `@version` and tags without a place in {@link ApiDocTags} are not read. */
+export declare function readDocTags(node: ts.Node): ApiDocTags;
+/** Whether a node has a doc block of its own, tags only or not. */
+export declare function isDocumented(node: ts.Node): boolean;
+/** Whether a node carries an `@internal` tag. */
+export declare function isInternal(node: ts.Node): boolean;
+/** The `@param` descriptions of a function-like node, by parameter name. */
+export declare function readParamDescriptions(node: ts.Node): Map<string, string>;
+//# sourceMappingURL=doc-tags.d.ts.map

package/dist/builder/scanner/service/doc-tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-tags.d.ts","sourceRoot":"","sources":["../../../../src/builder/scanner/service/doc-tags.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAgCnE,8FAA8F;AAC9F,wBAAgB,eAAe,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,MAAM,GAAG,SAAS,CAEjE;AAED,kGAAkG;AAClG,wBAAgB,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,UAAU,CA6BrD;AAED,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,OAAO,CAEnD;AAED,iDAAiD;AACjD,wBAAgB,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,OAAO,CAEjD;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAaxE"}

package/dist/builder/scanner/service/doc-tags.js

@@ -0,0 +1,97 @@
+import ts from 'typescript';
+/**
+ * The block that documents a node: the last `/** *\/` above it, as long as it
+ * sits right on top of the node and says something. Line comments in between,
+ * such as `// eslint-disable-next-line`, keep it attached. TypeScript also
+ * attaches a block that floats a few lines above, such as a section banner,
+ * and one that is only a ruler (`/** ===== *\/`); neither describes the node.
+ */
+function readDocBlock(node) {
+    const blocks = node.jsDoc;
+    const block = blocks?.[blocks.length - 1];
+    if (!block)
+        return undefined;
+    const sourceFile = node.getSourceFile();
+    // The first line is the rest of the block's last line, the last one the indentation of the node.
+    const linesBetween = sourceFile.text.slice(block.end, node.getStart(sourceFile)).split('\n').slice(1, -1);
+    if (linesBetween.some((line) => !/^\s*\/\//.test(line)))
+        return undefined;
+    const stripped = block.getText(sourceFile).replace(/[/*\s]/g, '');
+    if (stripped.length === 0 || /^[*=\-_#~]+$/.test(stripped))
+        return undefined;
+    return block;
+}
+function commentText(comment) {
+    return ts.getTextOfJSDocComment(comment)?.trim() || undefined;
+}
+/** The comment text of a node without its tags, as written: line breaks and markdown stay. */
+export function readDescription(node) {
+    return commentText(readDocBlock(node)?.comment);
+}
+/** The tags of a node. `@version` and tags without a place in {@link ApiDocTags} are not read. */
+export function readDocTags(node) {
+    const result = {};
+    for (const tag of readDocBlock(node)?.tags ?? []) {
+        const comment = commentText(tag.comment);
+        switch (tag.tagName.text) {
+            case 'deprecated':
+                result.deprecated = comment ?? true;
+                break;
+            case 'since':
+                if (comment)
+                    result.since = comment;
+                break;
+            case 'default':
+                if (comment)
+                    result.default = comment;
+                break;
+            case 'see': {
+                const reference = readSeeReference(tag);
+                if (reference)
+                    result.see = [...(result.see ?? []), reference];
+                break;
+            }
+            case 'example':
+                if (comment)
+                    result.example = [...(result.example ?? []), comment];
+                break;
+        }
+    }
+    return result;
+}
+/** Whether a node has a doc block of its own, tags only or not. */
+export function isDocumented(node) {
+    return readDocBlock(node) !== undefined;
+}
+/** Whether a node carries an `@internal` tag. */
+export function isInternal(node) {
+    return readDocBlock(node)?.tags?.some((tag) => tag.tagName.text === 'internal') ?? false;
+}
+/** The `@param` descriptions of a function-like node, by parameter name. */
+export function readParamDescriptions(node) {
+    const result = new Map();
+    for (const tag of readDocBlock(node)?.tags ?? []) {
+        if (!ts.isJSDocParameterTag(tag) || !ts.isIdentifier(tag.name))
+            continue;
+        // `@param name - text` is the TSDoc spelling; the dash is not part of the text.
+        const description = commentText(tag.comment)?.replace(/^-\s+/, '');
+        if (description)
+            result.set(tag.name.text, description);
+    }
+    return result;
+}
+/**
+ * What a `@see` points at: the target of a `{@link}`, a name, or a URL. The
+ * parser reads a URL as a name followed by `://…` and leaves a stray `*` of the
+ * next line behind, so the tag is read from the source instead of from its parts.
+ */
+function readSeeReference(tag) {
+    const body = tag
+        .getSourceFile()
+        .text.slice(tag.tagName.end, tag.end)
+        .split('\n')
+        .map((line) => line.replace(/^\s*\*?\s*/, ''))
+        .join(' ')
+        .trim();
+    return /^\{@link(?:code|plain)?\s+([^\s}|]+)/.exec(body)?.[1] ?? (body.split(/\s+/)[0] || undefined);
+}

package/dist/builder/scanner/service/export-index.d.ts

@@ -0,0 +1,18 @@
+import ts from 'typescript';
+/** Where a symbol can be imported from: the resolved symbol of an export, and the `importPath` of the entry point that exports it. */
+export type ExportIndex = ReadonlyMap<ts.Symbol, string>;
+/**
+ * Index everything the library's entry points export by its resolved symbol,
+ * so that a reference found anywhere in the source can be traced to the entry
+ * point a consumer imports it from. A re-export (`export { x } from`) is an
+ * alias and is followed to the declaration, which is what a reference resolves
+ * to as well.
+ *
+ * A symbol exported more than once keeps the first entry: callers put the
+ * secondary entry points before the primary one, as the component dedupe does.
+ */
+export declare function buildExportIndex(entries: ReadonlyArray<{
+    exports: ts.Symbol[];
+    importPath: string;
+}>, checker: ts.TypeChecker): ExportIndex;
+//# sourceMappingURL=export-index.d.ts.map

package/dist/builder/scanner/service/export-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-index.d.ts","sourceRoot":"","sources":["../../../../src/builder/scanner/service/export-index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,sIAAsI;AACtI,MAAM,MAAM,WAAW,GAAG,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEzD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,CAAC;IAAE,OAAO,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC,WAAW,GAAG,WAAW,CAY3I"}

package/dist/builder/scanner/service/export-index.js

@@ -0,0 +1,22 @@
+import ts from 'typescript';
+/**
+ * Index everything the library's entry points export by its resolved symbol,
+ * so that a reference found anywhere in the source can be traced to the entry
+ * point a consumer imports it from. A re-export (`export { x } from`) is an
+ * alias and is followed to the declaration, which is what a reference resolves
+ * to as well.
+ *
+ * A symbol exported more than once keeps the first entry: callers put the
+ * secondary entry points before the primary one, as the component dedupe does.
+ */
+export function buildExportIndex(entries, checker) {
+    const index = new Map();
+    for (const { exports, importPath } of entries) {
+        for (const sym of exports) {
+            const resolved = sym.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(sym) : sym;
+            if (!index.has(resolved))
+                index.set(resolved, importPath);
+        }
+    }
+    return index;
+}

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

@@ -0,0 +1,65 @@
+import ts from 'typescript';
+import type { ApiMethod, ApiProperty, ApiTypeRef } from '../../../plugin/service.types.js';
+/** What a type is the type of: a property, a parameter of a method, or what a method returns. */
+export type TypeSite = {
+    kind: 'property';
+    name: string;
+} | {
+    kind: 'parameter';
+    name: string;
+    method: string;
+} | {
+    kind: 'return';
+    method: string;
+};
+/**
+ * Turns the type of a member, parameter or return value into an {@link ApiTypeRef}.
+ * `reachedFrom` says where it was met, e.g. `parameter of show()`, and `site`
+ * the same in parts, for a resolver that documents the types it finds on the
+ * way and follows their members.
+ */
+export interface TypeRefResolver {
+    ref(typeNode: ts.TypeNode | undefined, type: ts.Type, reachedFrom: string, site?: TypeSite): ApiTypeRef;
+}
+/** A type as written, or as the checker prints it when there is nothing written. Whitespace is collapsed, so a multi-line literal type stays on one line. */
+export declare function readTypeText(checker: ts.TypeChecker, typeNode: ts.TypeNode | undefined, type: ts.Type): string;
+/** Gives the text of a type and nothing else: no links, no documented types. */
+export declare function textOnlyResolver(checker: ts.TypeChecker): TypeRefResolver;
+/**
+ * The public instance members of a class and of its base classes, nearest
+ * class first and in source order. A class that declares a name hides it in
+ * the classes above, whatever it declares: an `@internal` override removes
+ * the member, a redeclaration replaces the inherited one. A static member
+ * hides nothing, as it is not an instance member.
+ *
+ * Left out: `private`, `protected` and `#` members, names with a `_` prefix,
+ * lifecycle hooks, the constructor, statics and what is tagged `@internal`.
+ * The constructor's parameter properties (`constructor(readonly id: string)`)
+ * are properties, in the constructor's place, described by its `@param`.
+ * Methods are listed with or without JSDoc. A redeclaration without JSDoc of
+ * its own keeps its signature, but takes description, tags and `@param` texts
+ * from the nearest base class member of that name that has them.
+ */
+export declare function extractMembers(classDecl: ts.ClassDeclaration, checker: ts.TypeChecker, types: TypeRefResolver): {
+    properties: ApiProperty[];
+    methods: ApiMethod[];
+};
+/**
+ * The members of an interface or an object literal type, the inherited ones
+ * included, own members first. What is tagged `@internal` is left out; there
+ * is nothing private to leave out.
+ */
+export declare function extractObjectTypeMembers(type: ts.Type, checker: ts.TypeChecker, types: TypeRefResolver): {
+    properties: ApiProperty[];
+    methods: ApiMethod[];
+};
+/**
+ * The signature of a method, or of a function such as a setup function, with
+ * the doc block read from `docs`: the declaration itself, the statement of a
+ * `const` arrow function, or a declaration it inherits the docs of.
+ */
+export declare function extractMethod(name: string, declaration: ts.SignatureDeclaration, docs: ts.Node, checker: ts.TypeChecker, types: TypeRefResolver): ApiMethod;
+/** The first parameter that is not `this`. */
+export declare function firstParameter(declaration: ts.SignatureDeclaration): ts.ParameterDeclaration | undefined;
+export declare function collapseWhitespace(text: string): string;
+//# sourceMappingURL=member.extractor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"member.extractor.d.ts","sourceRoot":"","sources":["../../../../src/builder/scanner/service/member.extractor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,KAAK,EAAE,SAAS,EAAY,WAAW,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAIrG,iGAAiG;AACjG,MAAM,MAAM,QAAQ,GAAG;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAErJ;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC5B,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,GAAG,SAAS,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;CAC3G;AAkBD,6JAA6J;AAC7J,wBAAgB,YAAY,CAAC,OAAO,EAAE,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,EAAE,CAAC,QAAQ,GAAG,SAAS,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,MAAM,CAE9G;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,EAAE,CAAC,WAAW,GAAG,eAAe,CAIzE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,EAAE,CAAC,gBAAgB,EAAE,OAAO,EAAE,EAAE,CAAC,WAAW,EAAE,KAAK,EAAE,eAAe,GAAG;IAAE,UAAU,EAAE,WAAW,EAAE,CAAC;IAAC,OAAO,EAAE,SAAS,EAAE,CAAA;CAAE,CAyBnK;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,WAAW,EAAE,KAAK,EAAE,eAAe,GAAG;IAAE,UAAU,EAAE,WAAW,EAAE,CAAC;IAAC,OAAO,EAAE,SAAS,EAAE,CAAA;CAAE,CAuB5J;AAiFD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,CAAC,oBAAoB,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,WAAW,EAAE,KAAK,EAAE,eAAe,GAAG,SAAS,CAe3J;AAoBD,8CAA8C;AAC9C,wBAAgB,cAAc,CAAC,WAAW,EAAE,EAAE,CAAC,oBAAoB,GAAG,EAAE,CAAC,oBAAoB,GAAG,SAAS,CAExG;AAkBD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD"}

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

@@ -0,0 +1,216 @@
+import ts from 'typescript';
+import { getClassHierarchy } from '../class-hierarchy.js';
+import { isDocumented, isInternal, readDescription, readDocTags, readParamDescriptions } from './doc-tags.js';
+/** The lifecycle hooks Angular calls on a service; they are not part of what a user calls. */
+const LIFECYCLE_HOOKS = new Set([
+    'ngOnInit',
+    'ngOnDestroy',
+    'ngOnChanges',
+    'ngDoCheck',
+    'ngAfterContentInit',
+    'ngAfterContentChecked',
+    'ngAfterViewInit',
+    'ngAfterViewChecked'
+]);
+/** A type as written, or as the checker prints it when there is nothing written. Whitespace is collapsed, so a multi-line literal type stays on one line. */
+export function readTypeText(checker, typeNode, type) {
+    return typeNode ? collapseWhitespace(typeNode.getText()) : checker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation);
+}
+/** Gives the text of a type and nothing else: no links, no documented types. */
+export function textOnlyResolver(checker) {
+    return {
+        ref: (typeNode, type) => ({ text: readTypeText(checker, typeNode, type) })
+    };
+}
+/**
+ * The public instance members of a class and of its base classes, nearest
+ * class first and in source order. A class that declares a name hides it in
+ * the classes above, whatever it declares: an `@internal` override removes
+ * the member, a redeclaration replaces the inherited one. A static member
+ * hides nothing, as it is not an instance member.
+ *
+ * Left out: `private`, `protected` and `#` members, names with a `_` prefix,
+ * lifecycle hooks, the constructor, statics and what is tagged `@internal`.
+ * The constructor's parameter properties (`constructor(readonly id: string)`)
+ * are properties, in the constructor's place, described by its `@param`.
+ * Methods are listed with or without JSDoc. A redeclaration without JSDoc of
+ * its own keeps its signature, but takes description, tags and `@param` texts
+ * from the nearest base class member of that name that has them.
+ */
+export function extractMembers(classDecl, checker, types) {
+    const properties = [];
+    const methods = [];
+    const declared = new Set();
+    const levels = getClassHierarchy(classDecl, checker).classes.map(({ classDecl: current }) => groupByName(current));
+    levels.forEach((groups, level) => {
+        for (const [name, group] of groups) {
+            if (declared.has(name))
+                continue;
+            // The doc block sits on one of them: the first overload, or the getter or the setter.
+            const declaration = group.find(hasOwnDocs) ?? group[0];
+            if (!isPublicApi(name, group, declaration))
+                continue;
+            const docs = hasOwnDocs(declaration) ? declaration : (findInheritedDocs(levels.slice(level + 1), name) ?? declaration);
+            if (ts.isMethodDeclaration(declaration))
+                methods.push(extractMethod(name, declaration, docs, checker, types));
+            else
+                properties.push(extractProperty(name, group, declaration, docs, checker, types));
+        }
+        for (const name of groups.keys())
+            declared.add(name);
+    });
+    return { properties, methods };
+}
+/**
+ * The members of an interface or an object literal type, the inherited ones
+ * included, own members first. What is tagged `@internal` is left out; there
+ * is nothing private to leave out.
+ */
+export function extractObjectTypeMembers(type, checker, types) {
+    const properties = [];
+    const methods = [];
+    for (const symbol of checker.getPropertiesOfType(type)) {
+        const group = (symbol.declarations ?? []).filter((d) => ts.isMethodSignature(d) ||
+            ts.isMethodDeclaration(d) ||
+            ts.isPropertySignature(d) ||
+            ts.isPropertyDeclaration(d) ||
+            ts.isGetAccessor(d) ||
+            ts.isSetAccessor(d));
+        const declaration = group.find(isDocumented) ?? group[0];
+        if (!declaration || isInternal(declaration))
+            continue;
+        if (ts.isMethodSignature(declaration) || ts.isMethodDeclaration(declaration))
+            methods.push(extractMethod(symbol.name, declaration, declaration, checker, types));
+        else
+            properties.push(extractProperty(symbol.name, group, declaration, declaration, checker, types));
+    }
+    return { properties, methods };
+}
+/**
+ * The named instance members of a class by name, in source order: a getter and
+ * its setter, or the overloads of a method, share one entry. The parameter
+ * properties of the constructor come in where the constructor stands.
+ */
+function groupByName(classDecl) {
+    const groups = new Map();
+    const add = (name, member) => groups.set(name, [...(groups.get(name) ?? []), member]);
+    for (const member of classDecl.members) {
+        if (ts.isConstructorDeclaration(member)) {
+            for (const param of member.parameters) {
+                if (ts.isParameterPropertyDeclaration(param, member))
+                    add(param.name.text, param);
+            }
+            continue;
+        }
+        if (!(ts.isPropertyDeclaration(member) || ts.isMethodDeclaration(member) || ts.isGetAccessorDeclaration(member) || ts.isSetAccessorDeclaration(member)))
+            continue;
+        if (hasModifier(member, ts.SyntaxKind.StaticKeyword))
+            continue;
+        const name = getMemberName(member);
+        if (name !== undefined)
+            add(name, member);
+    }
+    return groups;
+}
+/**
+ * Whether a member is documented where it is declared: by a doc block of its
+ * own, or, for a parameter property, by the constructor's `@param` for it.
+ */
+function hasOwnDocs(member) {
+    return isDocumented(member) || (ts.isParameter(member) && readParamDescriptions(member.parent).has(member.name.text));
+}
+function isPublicApi(name, group, declaration) {
+    if (name.startsWith('_') || LIFECYCLE_HOOKS.has(name))
+        return false;
+    if (group.some((member) => hasModifier(member, ts.SyntaxKind.PrivateKeyword) || hasModifier(member, ts.SyntaxKind.ProtectedKeyword)))
+        return false;
+    // Only its own block: a member is internal where it is declared, as for `stripInternal`.
+    return !isInternal(declaration);
+}
+/** The documented declaration of a name in the nearest of the given base classes that has one. */
+function findInheritedDocs(levels, name) {
+    for (const groups of levels) {
+        const documented = groups.get(name)?.find(hasOwnDocs);
+        if (documented)
+            return documented;
+    }
+    return undefined;
+}
+/** `docs` is the node the doc block is read from: the declaration itself, or a declaration it inherits the docs of. */
+function extractProperty(name, group, declaration, docs, checker, types) {
+    const getter = group.find(ts.isGetAccessorDeclaration);
+    const setter = group.find(ts.isSetAccessorDeclaration);
+    const isField = ts.isPropertyDeclaration(declaration) || ts.isPropertySignature(declaration) || ts.isParameter(declaration);
+    // A property reads its type from the getter, and from the setter's parameter when there is none.
+    const typeNode = isField ? declaration.type : (getter?.type ?? setter?.parameters[0]?.type);
+    const property = {
+        name,
+        type: types.ref(typeNode, checker.getTypeAtLocation(declaration), `type of ${name}`, { kind: 'property', name }),
+        readonly: isField ? hasModifier(declaration, ts.SyntaxKind.ReadonlyKeyword) : !!getter && !setter,
+        tags: readDocTags(docs)
+    };
+    if (isField && declaration.questionToken)
+        property.optional = true;
+    // A parameter property has its text in the constructor's `@param`, unless it carries a block of its own.
+    const description = readDescription(docs) ?? (ts.isParameter(docs) && ts.isIdentifier(docs.name) ? readParamDescriptions(docs.parent).get(docs.name.text) : undefined);
+    if (description)
+        property.description = description;
+    return property;
+}
+/**
+ * The signature of a method, or of a function such as a setup function, with
+ * the doc block read from `docs`: the declaration itself, the statement of a
+ * `const` arrow function, or a declaration it inherits the docs of.
+ */
+export function extractMethod(name, declaration, docs, checker, types) {
+    const signature = checker.getSignatureFromDeclaration(declaration);
+    const returnType = signature ? checker.getReturnTypeOfSignature(signature) : checker.getTypeAtLocation(declaration);
+    const descriptions = readParamDescriptions(docs);
+    const result = {
+        name,
+        params: declaration.parameters.filter((param) => !isThisParameter(param)).map((param) => extractParam(name, param, descriptions, checker, types)),
+        returnType: types.ref(declaration.type, returnType, `returned by ${name}()`, { kind: 'return', method: name }),
+        tags: readDocTags(docs)
+    };
+    const description = readDescription(docs);
+    if (description)
+        result.description = description;
+    return result;
+}
+function extractParam(methodName, param, descriptions, checker, types) {
+    const name = ts.isIdentifier(param.name) ? param.name.text : collapseWhitespace(param.name.getText());
+    const result = {
+        name,
+        type: types.ref(param.type, checker.getTypeAtLocation(param), `parameter of ${methodName}()`, { kind: 'parameter', name, method: methodName }),
+        optional: !!(param.questionToken || param.initializer)
+    };
+    if (param.dotDotDotToken)
+        result.rest = true;
+    if (param.initializer)
+        result.defaultValue = collapseWhitespace(param.initializer.getText());
+    const description = descriptions.get(name);
+    if (description)
+        result.description = description;
+    return result;
+}
+/** The first parameter that is not `this`. */
+export function firstParameter(declaration) {
+    return declaration.parameters.find((param) => !isThisParameter(param));
+}
+function isThisParameter(param) {
+    return ts.isIdentifier(param.name) && param.name.text === 'this';
+}
+/** `#private` and computed names have none: neither is part of the API a user reads. */
+function getMemberName(member) {
+    if (!member.name)
+        return undefined;
+    if (ts.isIdentifier(member.name) || ts.isStringLiteral(member.name))
+        return member.name.text;
+    return undefined;
+}
+function hasModifier(node, kind) {
+    return ts.canHaveModifiers(node) && !!ts.getModifiers(node)?.some((modifier) => modifier.kind === kind);
+}
+export function collapseWhitespace(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}

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

@@ -0,0 +1,12 @@
+import ts from 'typescript';
+import type { PipeApi } from '../../../plugin/pipe.types.js';
+import type { ExportIndex } from './export-index.js';
+import type { SetupRef } from './setup.reader.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 declare function extractPipeApi(classDecl: ts.ClassDeclaration, setupRefs: SetupRef[], checker: ts.TypeChecker, exportIndex: ExportIndex): PipeApi;
+//# sourceMappingURL=pipe-api.extractor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pipe-api.extractor.d.ts","sourceRoot":"","sources":["../../../../src/builder/scanner/service/pipe-api.extractor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAI7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAGlD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,EAAE,CAAC,gBAAgB,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,EAAE,CAAC,WAAW,EAAE,WAAW,EAAE,WAAW,GAAG,OAAO,CAWhJ"}