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

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

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;
+}