@lickle/docs 0.0.0-dev.1

package/dist/esm/core/reflect/scan.js

@@ -0,0 +1,787 @@
+import { makeScanState } from "./state.js";
+import ts from 'typescript';
+export const scan = (rootFiles, options) => {
+    const compilerOptions = { jsx: ts.JsxEmit.ReactJSX, ...options.compilerOptions };
+    const program = ts.createProgram(rootFiles, compilerOptions);
+    const checker = program.getTypeChecker();
+    const s = makeScanState(checker, options);
+    const files = new Array();
+    for (const file of rootFiles) {
+        const sf = program.getSourceFile(file);
+        if (!sf)
+            continue;
+        files.push(sf);
+    }
+    while (files.length) {
+        const sf = files.shift();
+        scan.SourceFile(s, sf, files);
+    }
+    return s;
+};
+scan.SourceFile = (s, node, queue) => {
+    if (s.seen.has(node) || !s.include(node))
+        return;
+    s.seen.add(node);
+    s.parent = s.root;
+    const f = statement(s, node, 'module', () => ({ path: s.getPath(node) }));
+    s.parent = f.id;
+    node.statements.forEach((stmt) => {
+        if (ts.isExportDeclaration(stmt))
+            return scan.ExportDeclaration(s, stmt, queue);
+        if (ts.isExportAssignment(stmt))
+            return scan.ExportAssignment(s, stmt);
+        scan.Statement(s, stmt);
+    });
+    return;
+};
+scan.Statement = (s, node) => {
+    if (ts.isVariableStatement(node)) {
+        return node.declarationList.declarations.forEach((d) => scan.VariableDeclaration(s, d));
+    }
+    if (ts.isVariableDeclaration(node))
+        return scan.VariableDeclaration(s, node);
+    if (ts.isFunctionDeclaration(node))
+        return scan.FunctionDeclaration(s, node);
+    if (ts.isClassDeclaration(node))
+        return scan.ClassDeclaration(s, node);
+    if (ts.isInterfaceDeclaration(node))
+        return scan.InterfaceDeclaration(s, node);
+    if (ts.isTypeAliasDeclaration(node))
+        return scan.TypeAliasDeclaration(s, node);
+    if (ts.isEnumDeclaration(node))
+        return scan.EnumDeclaration(s, node);
+    if (ts.isModuleDeclaration(node))
+        return scan.ModuleDeclaration(s, node);
+};
+scan.VariableDeclaration = (s, node) => {
+    const init = node.initializer;
+    if (init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init))) {
+        return statement(s, node, 'function', () => functionBody(s, init));
+    }
+    return statement(s, node, 'variable', () => ({
+        type: node.type ? scan.Type(s, node.type) : inferAt(s, node),
+        defaultValue: node.initializer?.getText(),
+    }));
+};
+scan.FunctionDeclaration = (s, decl) => {
+    return statement(s, decl, 'function', () => functionBody(s, decl));
+};
+scan.ClassDeclaration = (s, node) => {
+    const constructors = [];
+    const properties = [];
+    const methods = [];
+    let indexSignature;
+    for (const m of node.members) {
+        if (ts.isConstructorDeclaration(m))
+            constructors.push(signature(s, m));
+        else if (ts.isPropertyDeclaration(m) && ts.isIdentifier(m.name))
+            properties.push(property(s, m));
+        else if (ts.isMethodDeclaration(m) && ts.isIdentifier(m.name))
+            methods.push(method(s, m));
+        else if (ts.isIndexSignatureDeclaration(m))
+            indexSignature = indexSignatureDecl(s, m);
+    }
+    return statement(s, node, 'class', () => ({
+        ...generics(s, node),
+        ...heritage(s, node),
+        constructors,
+        properties,
+        methods,
+        ...(indexSignature ? { indexSignature } : {}),
+    }));
+};
+scan.InterfaceDeclaration = (s, node) => statement(s, node, 'interface', () => ({
+    ...generics(s, node),
+    ...interfaceExtends(s, node),
+    ...objectMembers(s, node.members),
+}));
+scan.TypeAliasDeclaration = (s, node) => statement(s, node, 'type-alias', () => ({
+    ...generics(s, node),
+    type: scan.Type(s, node.type),
+}));
+scan.EnumDeclaration = (s, node) => statement(s, node, 'enum', () => ({
+    const: !!node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ConstKeyword),
+    members: node.members.map((m) => enumMember(s, m)),
+}));
+scan.ModuleDeclaration = (s, node) => {
+    const ns = statement(s, node, 'namespace', () => ({}));
+    const body = node.body;
+    if (!body)
+        return ns;
+    const prev = s.parent;
+    s.parent = ns.id;
+    if (ts.isModuleBlock(body)) {
+        body.statements.forEach((stmt) => scan.Statement(s, stmt));
+    }
+    else if (ts.isModuleDeclaration(body)) {
+        // `namespace A.B { … }` → recurse on the inner `B`.
+        scan.ModuleDeclaration(s, body);
+    }
+    s.parent = prev;
+    return ns;
+};
+scan.ExportDeclaration = (s, node, queue) => {
+    const spec = node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier) ? node.moduleSpecifier.text : undefined;
+    // Enqueue the source module so its declarations exist for resolution.
+    if (spec) {
+        const sym = s.checker.getSymbolAtLocation(node.moduleSpecifier);
+        const decl = sym?.valueDeclaration ?? sym?.declarations?.[0];
+        if (decl && ts.isSourceFile(decl) && !s.seen.has(decl) && s.include(decl)) {
+            queue.push(decl);
+        }
+    }
+    // Emit an `export` declaration node (ref filled by resolver).
+    const exp = statement(s, node, 'export', () => ({ names: [], star: false }));
+    s.exports.push(exp);
+    if (!node.exportClause) {
+        if (!spec)
+            return;
+        s.exportsForm.set(exp.id, 'star');
+        s.exportsSpec.set(exp.id, spec);
+        s.exportsOrigin.set(exp.id, node);
+        exp.star = true;
+        return;
+    }
+    if (ts.isNamespaceExport(node.exportClause)) {
+        if (!spec)
+            return;
+        s.exportsForm.set(exp.id, 'namespace-from');
+        s.exportsSpec.set(exp.id, spec);
+        s.exportsAlias.set(exp.id, node.exportClause.name.text);
+        s.exportsOrigin.set(exp.id, node);
+        return;
+    }
+    const entries = node.exportClause.elements.map((el) => ({
+        name: (el.propertyName ?? el.name).text,
+        ...(el.propertyName ? { as: el.name.text } : {}),
+    }));
+    s.exportsForm.set(exp.id, spec ? 'named-from' : 'named-local');
+    if (spec)
+        s.exportsSpec.set(exp.id, spec);
+    s.exportsEntries.set(exp.id, entries);
+    s.exportsOrigin.set(exp.id, node);
+};
+// `export default <expr>` / `export = <expr>`. The target is resolved later.
+scan.ExportAssignment = (s, node) => {
+    const exp = statement(s, node, 'export', () => ({ names: [], star: false }));
+    s.exports.push(exp);
+    s.exportsForm.set(exp.id, 'assignment');
+    s.exportsOrigin.set(exp.id, node);
+    return exp;
+};
+// ---------------- Type Components ----------------
+scan.Type = (s, node) => {
+    if (ts.isLiteralTypeNode(node))
+        return scan.Literal(s, node);
+    if (ts.isArrayTypeNode(node))
+        return scan.Array(s, node);
+    if (ts.isTupleTypeNode(node))
+        return scan.Tuple(s, node);
+    if (ts.isUnionTypeNode(node))
+        return scan.Union(s, node);
+    if (ts.isIntersectionTypeNode(node))
+        return scan.Intersection(s, node);
+    if (ts.isTypeOperatorNode(node))
+        return scan.TypeOperator(s, node);
+    if (ts.isFunctionTypeNode(node) || ts.isConstructorTypeNode(node))
+        return scan.FunctionType(s, node);
+    if (ts.isTypeLiteralNode(node))
+        return scan.Record(s, node);
+    if (ts.isParenthesizedTypeNode(node))
+        return scan.Type(s, node.type);
+    if (ts.isConditionalTypeNode(node))
+        return scan.Conditional(s, node);
+    if (ts.isInferTypeNode(node))
+        return scan.Infer(s, node);
+    if (ts.isIndexedAccessTypeNode(node))
+        return scan.IndexedAccess(s, node);
+    if (ts.isMappedTypeNode(node))
+        return scan.Mapped(s, node);
+    if (ts.isTypeQueryNode(node))
+        return scan.Query(s, node);
+    if (ts.isTemplateLiteralTypeNode(node))
+        return scan.TemplateLiteral(s, node);
+    if (ts.isTypePredicateNode(node))
+        return scan.Predicate(s, node);
+    if (ts.isImportTypeNode(node))
+        return scan.ImportType(s, node);
+    const name = INTRINSICS[node.kind];
+    if (name)
+        return scan.Intrinsic(s, node, name);
+    if (ts.isTypeReferenceNode(node))
+        return scan.TypeReference(s, node);
+    return scan.Unknown(s, node);
+};
+scan.Literal = (s, node) => type(s, node, 'literal', { value: literalValue(node.literal) });
+scan.Array = (s, node) => type(s, node, 'array', { elementType: scan.Type(s, node.elementType) });
+scan.Union = (s, node) => type(s, node, 'union', { types: node.types.map((t) => scan.Type(s, t)) });
+scan.Intersection = (s, node) => type(s, node, 'intersection', { types: node.types.map((t) => scan.Type(s, t)) });
+scan.Tuple = (s, node) => type(s, node, 'tuple', { elements: node.elements.map((el) => tupleElement(s, el)) });
+scan.TypeOperator = (s, node) => type(s, node, 'type-operator', { operator: TYPE_OPERATORS[node.operator], target: scan.Type(s, node.type) });
+scan.FunctionType = (s, node) => type(s, node, 'function-type', { signatures: [signature(s, node)] });
+scan.Record = (s, node) => type(s, node, 'record', objectMembers(s, node.members));
+scan.Conditional = (s, node) => type(s, node, 'conditional', {
+    check: scan.Type(s, node.checkType),
+    extends: scan.Type(s, node.extendsType),
+    true: scan.Type(s, node.trueType),
+    false: scan.Type(s, node.falseType),
+});
+scan.Infer = (s, node) => type(s, node, 'infer', {
+    name: node.typeParameter.name.text,
+    ...(node.typeParameter.constraint ? { constraint: scan.Type(s, node.typeParameter.constraint) } : {}),
+});
+scan.IndexedAccess = (s, node) => type(s, node, 'indexed-access', { object: scan.Type(s, node.objectType), index: scan.Type(s, node.indexType) });
+scan.Mapped = (s, node) => type(s, node, 'mapped', {
+    typeParameter: scan.TypeParam(s, node.typeParameter),
+    ...(node.nameType ? { nameType: scan.Type(s, node.nameType) } : {}),
+    ...(node.type ? { type: scan.Type(s, node.type) } : {}),
+    ...(node.questionToken ? { optional: true } : {}),
+    ...(node.readonlyToken ? { readonly: true } : {}),
+});
+scan.Query = (s, node) => type(s, node, 'query', {
+    name: node.exprName.getText(),
+    ...(node.typeArguments?.length ? { args: node.typeArguments.map((a) => scan.Type(s, a)) } : {}),
+});
+scan.TemplateLiteral = (s, node) => type(s, node, 'template-literal', {
+    head: node.head.text,
+    spans: node.templateSpans.map((sp) => ({ type: scan.Type(s, sp.type), literal: sp.literal.text })),
+});
+scan.Predicate = (s, node) => type(s, node, 'predicate', {
+    parameter: node.parameterName.getText(),
+    ...(node.assertsModifier ? { asserts: true } : {}),
+    ...(node.type ? { type: scan.Type(s, node.type) } : {}),
+});
+scan.ImportType = (s, node) => {
+    const arg = ts.isLiteralTypeNode(node.argument) && ts.isStringLiteral(node.argument.literal)
+        ? node.argument.literal.text
+        : node.argument.getText();
+    return type(s, node, 'import-type', {
+        argument: arg,
+        ...(node.qualifier ? { qualifier: node.qualifier.getText() } : {}),
+        ...(node.isTypeOf ? { isTypeOf: true } : {}),
+        ...(node.typeArguments?.length ? { args: node.typeArguments.map((a) => scan.Type(s, a)) } : {}),
+    });
+};
+scan.TypeReference = (s, node) => {
+    const r = type(s, node, 'reference', { type: 'internal', targetId: 0 });
+    r.id = s.nextId();
+    r.owner = s.currentStmt;
+    r.name = getName(node) ?? 'unknown';
+    if (node.typeArguments?.length)
+        r.args = node.typeArguments.map((a) => scan.Type(s, a));
+    s.references.push(r);
+    s.referenceOrigins.set(r.id, node);
+    return r;
+};
+scan.Unknown = (s, node) => type(s, node, 'unknown', { text: node.getText(), nodeType: ts.SyntaxKind[node.kind] });
+scan.Intrinsic = (s, node, name) => {
+    return type(s, node, 'intrinsic', { name });
+};
+scan.TypeParam = (s, node) => {
+    return part(s, node, 'generic', {
+        constraint: node.constraint ? scan.Type(s, node.constraint) : undefined,
+        default: node.default ? scan.Type(s, node.default) : undefined,
+    });
+};
+// ---------------- Inference ----------------
+/**
+ * Infer a declaration's type from the checker when no annotation is present.
+ * Builds a structured `Type` for the common shapes (primitives, literals,
+ * unions, arrays, named references, object literals) and falls back to the
+ * checker's string form for anything more exotic — the hybrid contract.
+ */
+const inferAt = (s, node) => fromType(s, node, s.checker.getTypeAtLocation(node), new Set());
+const inferReturn = (s, node) => {
+    const sig = s.checker.getSignatureFromDeclaration(node);
+    return sig ? fromType(s, node, sig.getReturnType(), new Set()) : scan.Intrinsic(s, node, 'unknown');
+};
+const fromType = (s, ctx, type, seen) => structured(s, ctx, type, seen) ?? inferredText(s, ctx, type);
+const inferredText = (s, ctx, type) => inode(s, 'unknown', { text: s.checker.typeToString(type, ctx, ts.TypeFormatFlags.NoTruncation), nodeType: 'inferred' });
+const structured = (s, ctx, type, seen) => {
+    const f = type.flags;
+    // Literals first — their flags never overlap the primitive intrinsics.
+    if (f & ts.TypeFlags.StringLiteral)
+        return inode(s, 'literal', { value: type.value });
+    if (f & ts.TypeFlags.NumberLiteral)
+        return inode(s, 'literal', { value: type.value });
+    if (f & ts.TypeFlags.BigIntLiteral) {
+        const v = type.value;
+        return inode(s, 'literal', { value: BigInt((v.negative ? '-' : '') + v.base10Value) });
+    }
+    if (f & ts.TypeFlags.BooleanLiteral)
+        return inode(s, 'literal', { value: type.intrinsicName === 'true' });
+    const intr = intrinsicName(f);
+    if (intr)
+        return inode(s, 'intrinsic', { name: intr });
+    // Keep a named alias rather than expanding it inline.
+    const alias = type.aliasSymbol;
+    if (alias && isNamed(alias))
+        return inferRef(s, alias.getName(), alias, mapArgs(s, ctx, type.aliasTypeArguments, seen));
+    if (type.isUnion())
+        return inode(s, 'union', { types: type.types.map((t) => fromType(s, ctx, t, seen)) });
+    if (type.isIntersection())
+        return inode(s, 'intersection', { types: type.types.map((t) => fromType(s, ctx, t, seen)) });
+    return objectType(s, ctx, type, seen);
+};
+/** Arrays, named references, and anonymous object literals. */
+const objectType = (s, ctx, type, seen) => {
+    if (!(type.flags & ts.TypeFlags.Object))
+        return undefined;
+    const obj = type;
+    if (obj.objectFlags & ts.ObjectFlags.Reference) {
+        const ref = type;
+        if (ref.target.objectFlags & ts.ObjectFlags.Tuple)
+            return undefined; // → string form
+        const args = s.checker.getTypeArguments(ref);
+        const tname = ref.target.symbol?.getName();
+        if ((tname === 'Array' || tname === 'ReadonlyArray') && args.length === 1)
+            return inode(s, 'array', { elementType: fromType(s, ctx, args[0], seen) });
+        const sym = type.getSymbol();
+        if (sym && isNamed(sym))
+            return inferRef(s, sym.getName(), sym, mapArgs(s, ctx, args, seen));
+    }
+    const sym = type.getSymbol();
+    if (sym && isNamed(sym))
+        return inferRef(s, sym.getName(), sym, undefined);
+    // Callable / constructable objects are too rich for a record — defer to text.
+    if (type.getCallSignatures().length || type.getConstructSignatures().length)
+        return undefined;
+    const props = type.getProperties();
+    if (!props.length || seen.has(type))
+        return undefined;
+    seen.add(type);
+    return inode(s, 'record', { properties: props.map((p) => inferProp(s, ctx, p, seen)), methods: [] });
+};
+const inferProp = (s, ctx, sym, seen) => {
+    const decl = sym.valueDeclaration ?? sym.declarations?.[0] ?? ctx;
+    const pt = s.checker.getTypeOfSymbolAtLocation(sym, decl);
+    return {
+        kind: 'property',
+        parent: s.parent,
+        sources: [],
+        name: sym.getName(),
+        type: fromType(s, ctx, pt, seen),
+        ...(sym.flags & ts.SymbolFlags.Optional ? { optional: true } : {}),
+    };
+};
+const inferRef = (s, name, symbol, args) => {
+    const r = {
+        kind: 'reference',
+        parent: s.parent,
+        sources: [],
+        type: 'internal',
+        targetId: 0,
+        id: s.nextId(),
+        name,
+        owner: s.currentStmt,
+        ...(args?.length ? { args } : {}),
+    };
+    s.references.push(r);
+    s.referenceSymbols.set(r.id, symbol);
+    return r;
+};
+const mapArgs = (s, ctx, args, seen) => args?.length ? args.map((a) => fromType(s, ctx, a, seen)) : undefined;
+/** A symbol that should render as a clickable name rather than an expanded shape. */
+const isNamed = (sym) => {
+    if (sym.flags & ts.SymbolFlags.TypeParameter)
+        return false;
+    const n = sym.getName();
+    return !!n && !n.startsWith('__');
+};
+const inode = (s, kind, fields) => ({ kind, parent: s.parent, sources: [], ...fields });
+const intrinsicName = (f) => {
+    if (f & ts.TypeFlags.String)
+        return 'string';
+    if (f & ts.TypeFlags.Number)
+        return 'number';
+    if (f & ts.TypeFlags.Boolean)
+        return 'boolean';
+    if (f & ts.TypeFlags.BigInt)
+        return 'bigint';
+    if (f & (ts.TypeFlags.ESSymbol | ts.TypeFlags.UniqueESSymbol))
+        return 'symbol';
+    if (f & ts.TypeFlags.Void)
+        return 'void';
+    if (f & ts.TypeFlags.Undefined)
+        return 'undefined';
+    if (f & ts.TypeFlags.Null)
+        return 'null';
+    if (f & ts.TypeFlags.Never)
+        return 'never';
+    if (f & ts.TypeFlags.Any)
+        return 'any';
+    if (f & ts.TypeFlags.Unknown)
+        return 'unknown';
+    if (f & ts.TypeFlags.NonPrimitive)
+        return 'object';
+    return undefined;
+};
+// ---------------- Type Components ----------------
+const signature = (s, node) => part(s, node, 'signature', {
+    ...(node.typeParameters ? { generics: node.typeParameters.map((tp) => scan.TypeParam(s, tp)) } : {}),
+    params: node.parameters.map((p) => parameter(s, p)),
+    return: node.type ? scan.Type(s, node.type) : inferReturn(s, node),
+});
+const parameter = (b, node) => part(b, node, 'parameter', {
+    type: node.type ? scan.Type(b, node.type) : inferAt(b, node),
+    optional: !!node.questionToken || !!node.initializer,
+    ...(node.dotDotDotToken ? { rest: true } : {}),
+    ...(node.initializer ? { default: node.initializer.getText() } : {}),
+});
+const functionBody = (s, node) => ({
+    signatures: [signature(s, node)],
+});
+const commentForNode = (b, node) => {
+    const all = ts.getJSDocCommentsAndTags(node);
+    if (!all.length)
+        return undefined;
+    const parts = [];
+    const tags = [];
+    let seenBlock = false;
+    for (const doc of all) {
+        if (!ts.isJSDoc(doc))
+            continue;
+        seenBlock = true;
+        appendCommentBody(doc.comment, parts);
+        if (doc.tags)
+            for (const t of doc.tags) {
+                const tag = buildTag(b, t);
+                if (tag.tag === '@module')
+                    return undefined;
+                tags.push(tag);
+            }
+    }
+    if (!seenBlock)
+        return undefined;
+    return { parts, ...(tags.length ? { tags } : {}) };
+};
+/** Flatten a JSDoc comment into `parts`. */
+const appendCommentBody = (comment, parts) => {
+    if (!comment)
+        return;
+    if (typeof comment === 'string') {
+        const trimmed = comment.trim();
+        if (trimmed)
+            parts.push({ kind: 'text', text: trimmed });
+        return;
+    }
+    for (const c of comment) {
+        if (c.kind === ts.SyntaxKind.JSDocText) {
+            parts.push({ kind: 'text', text: c.text });
+            continue;
+        }
+        const target = c.name?.getText() ?? '';
+        const linkText = c.text || undefined;
+        const style = ts.isJSDocLinkCode(c) ? 'code' : ts.isJSDocLinkPlain(c) ? 'plain' : undefined;
+        parts.push({ kind: 'link', target, ...(linkText ? { text: linkText } : {}), ...(style ? { style } : {}) });
+    }
+};
+const buildTag = (s, tag) => {
+    const text = ts.getTextOfJSDocComment(tag.comment)?.trim() ?? '';
+    const exprType = (te) => (te ? scan.Type(s, te.type) : undefined);
+    if (ts.isJSDocPropertyTag(tag)) {
+        return {
+            tag: '@property',
+            name: tag.name.getText(),
+            type: exprType(tag.typeExpression),
+            text,
+        };
+    }
+    if (ts.isJSDocParameterTag(tag)) {
+        return {
+            tag: '@param',
+            name: tag.name.getText(),
+            type: exprType(tag.typeExpression),
+            ...(tag.isBracketed ? { optional: true } : {}),
+            text,
+        };
+    }
+    if (ts.isJSDocReturnTag(tag)) {
+        const type = exprType(tag.typeExpression);
+        return { tag: '@returns', ...(type ? { type } : {}), text };
+    }
+    if (ts.isJSDocThrowsTag(tag)) {
+        const type = exprType(tag.typeExpression);
+        return { tag: '@throws', ...(type ? { type } : {}), text };
+    }
+    if (ts.isJSDocTypeTag(tag))
+        return { tag: '@type', type: exprType(tag.typeExpression), text };
+    if (ts.isJSDocSatisfiesTag(tag))
+        return { tag: '@satisfies', type: exprType(tag.typeExpression), text };
+    if (ts.isJSDocTemplateTag(tag)) {
+        return { tag: '@template', generics: tag.typeParameters.map((tp) => scan.TypeParam(s, tp)), text };
+    }
+    if (ts.isJSDocSeeTag(tag)) {
+        return { tag: '@see', ...(tag.name ? { target: tag.name.name.getText() } : {}), text };
+    }
+    if (ts.isJSDocAugmentsTag(tag))
+        return { tag: '@augments', class: scan.Type(s, tag.class), text };
+    if (ts.isJSDocImplementsTag(tag))
+        return { tag: '@implements', class: scan.Type(s, tag.class), text };
+    const name = '@' + tag.tagName.text;
+    // `@example` carries semantic indentation; re-extract from source so the
+    // leader-strip never eats author tabs (see `rawTagBody`).
+    if (name === '@example')
+        return parseExample(rawTagBody(tag));
+    return { tag: name, text };
+};
+/**
+ * Reconstruct the body of a JSDoc tag from source, stripping the per-line
+ * `*` leader and at most one *space* of separator. Unlike
+ * `ts.getTextOfJSDocComment` — which strips `[ \t]?` and so eats a single
+ * tab of user indentation — this preserves tabs intact.
+ */
+const rawTagBody = (tag) => {
+    const src = tag.getSourceFile().text;
+    // Body starts immediately after the tag name (`@example`), runs to tag end.
+    const raw = src.slice(tag.tagName.end, tag.end);
+    return raw
+        .split('\n')
+        .map((line, i) => (i === 0 ? line : line.replace(/^[ \t]*\*( ?)/, '')))
+        .join('\n')
+        .trim();
+};
+/**
+ * Pull an optional caption out of an `@example` body. Two forms are recognised:
+ *   1. Legacy JSDoc: `<caption>…</caption>` prefix.
+ *   2. TypeDoc-style: any text on the line(s) before the first fenced code
+ *      block becomes the caption; the fence and its body become the code.
+ * When neither pattern matches, the entire body is treated as `code`.
+ */
+const parseExample = (raw) => {
+    const html = raw.match(/^<caption>([\s\S]*?)<\/caption>\s*([\s\S]*)$/);
+    if (html)
+        return { tag: '@example', caption: html[1].trim(), code: html[2].trim() };
+    const fence = raw.search(/^```/m);
+    if (fence > 0) {
+        const caption = raw.slice(0, fence).trim();
+        if (caption)
+            return { tag: '@example', caption, code: raw.slice(fence).trim() };
+    }
+    return { tag: '@example', code: raw.trim() };
+};
+export const commentForModule = (s, sf) => {
+    if (sf.statements.length === 0)
+        return undefined;
+    // 1. Target the leading comment ranges for the first statement per your rules
+    const sourceText = sf.getFullText();
+    const commentRanges = ts.getLeadingCommentRanges(sourceText, sf.statements[0].pos);
+    if (!commentRanges || commentRanges.length === 0)
+        return undefined;
+    const parts = [];
+    const tags = [];
+    let seenBlock = false;
+    // 2. Evaluate each comment text range
+    for (let i = 0; i < commentRanges.length; i++) {
+        const range = commentRanges[i];
+        const commentText = sourceText.slice(range.pos, range.end);
+        // Apply your specific layout logic
+        const isModuleComment = i < commentRanges.length - 1 || commentText.includes('@module');
+        if (isModuleComment) {
+            // 3. Trick the compiler into parsing the raw text snippet back into an AST Node block
+            // We append an empty statement (;) so the parser attaches the JSDoc to a valid target.
+            const dummyFile = ts.createSourceFile('dummy.ts', `${commentText}\n;`, ts.ScriptTarget.Latest, true);
+            // 4. Safely extract the compiled JSDoc node from the dummy file
+            const dummyStmt = dummyFile.statements[0];
+            if (dummyStmt) {
+                const jsdocBlocks = ts.getJSDocCommentsAndTags(dummyStmt);
+                const matchingBlock = jsdocBlocks.find(ts.isJSDoc);
+                if (matchingBlock) {
+                    seenBlock = true;
+                    // Feed the generated AST structure down your pipeline seamlessly
+                    appendCommentBody(matchingBlock.comment, parts);
+                    if (matchingBlock.tags) {
+                        for (const t of matchingBlock.tags) {
+                            tags.push(buildTag(s, t));
+                        }
+                    }
+                }
+            }
+        }
+    }
+    if (!seenBlock)
+        return undefined;
+    return { parts, ...(tags.length ? { tags } : {}) };
+};
+const statement = (s, node, kind, fields) => {
+    const b = base(s, node);
+    s.currentStmt = b.id;
+    Object.assign(b, fields(), { kind });
+    s.declarations.push(b);
+    return b;
+};
+const type = (s, node, kind, fields) => {
+    const nd = typeBase(s, node);
+    Object.assign(nd, { kind }, fields);
+    return nd;
+};
+const part = (s, node, kind, fields) => {
+    const nd = typeBase(s, node);
+    Object.assign(nd, { kind }, fields);
+    if (nd.name === undefined) {
+        const n = getName(node);
+        if (n !== undefined)
+            nd.name = n;
+    }
+    return nd;
+};
+const base = (s, node) => {
+    const result = typeBase(s, node);
+    result.id = s.nextId();
+    result.name = getName(node) ?? 'unknown';
+    result.exported = isExported(node);
+    const named = node.name;
+    const sym = s.checker.getSymbolAtLocation(named ?? node);
+    if (sym)
+        s.symbolsById.set(result.id, sym);
+    return result;
+};
+const typeBase = (s, node) => {
+    const result = { parent: s.parent, sources: [] };
+    const named = node.name;
+    const sym = s.checker.getSymbolAtLocation(named ?? node);
+    if (sym?.declarations?.length)
+        result.sources = sym.declarations.map((d) => sourceOf(s, d));
+    else
+        result.sources = [sourceOf(s, node)];
+    const comment = ts.isSourceFile(node) ? commentForModule(s, node) : commentForNode(s, node);
+    if (comment)
+        result.comment = comment;
+    return result;
+};
+const sourceOf = (s, node) => {
+    const sf = node.getSourceFile();
+    const { line, character } = sf.getLineAndCharacterOfPosition(node.getStart());
+    return { file: s.getPath(sf), line: line + 1, column: character + 1 };
+};
+// ---------------- Utilities ----------------
+export const isExported = (node) => {
+    if (ts.isExportDeclaration(node) || ts.isExportAssignment(node))
+        return true;
+    // `export const x` carries the modifier on the enclosing `VariableStatement`.
+    if (ts.isVariableDeclaration(node)) {
+        const stmt = node.parent?.parent;
+        return !!stmt && ts.isVariableStatement(stmt) && isExported(stmt);
+    }
+    const mods = node.modifiers;
+    return !!mods?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+};
+export const getName = (node) => {
+    if (ts.isTypeReferenceNode(node))
+        return node.typeName.getText();
+    if (ts.isExpressionWithTypeArguments(node))
+        return node.expression.getText();
+    if (ts.isTypeQueryNode(node))
+        return node.exprName.getText();
+    if (ts.isDeclarationStatement(node))
+        return ts.getNameOfDeclaration(node)?.getText();
+    if (ts.isExpression(node))
+        return ts.getNameOfDeclaration(node)?.getText();
+    if (node.name)
+        return node.name.getText();
+    return undefined;
+};
+const property = (s, node) => part(s, node, 'property', {
+    type: node.type ? scan.Type(s, node.type) : inferAt(s, node),
+    ...(node.questionToken ? { optional: true } : {}),
+    ...('initializer' in node && node.initializer ? { defaultValue: node.initializer.getText() } : {}),
+});
+const method = (s, node) => part(s, node, 'method', { signatures: [signature(s, node)] });
+const indexSignatureDecl = (s, node) => part(s, node, 'index-signature', {
+    parameter: parameter(s, node.parameters[0]),
+    type: node.type ? scan.Type(s, node.type) : scan.Intrinsic(s, node, 'unknown'),
+});
+const enumMember = (s, node) => {
+    const value = s.checker.getConstantValue(node);
+    return part(s, node, 'enum-member', { ...(value !== undefined ? { value } : {}) });
+};
+const generics = (s, node) => node.typeParameters?.length ? { generics: node.typeParameters.map((tp) => scan.TypeParam(s, tp)) } : {};
+const heritage = (s, node) => {
+    const out = {};
+    for (const h of node.heritageClauses ?? []) {
+        const types = h.types.map((t) => scan.Type(s, t));
+        if (h.token === ts.SyntaxKind.ExtendsKeyword)
+            out.extends = types;
+        else
+            out.implements = types;
+    }
+    return out;
+};
+const interfaceExtends = (s, node) => {
+    const ext = node.heritageClauses?.flatMap((h) => h.types).map((t) => scan.Type(s, t));
+    return ext?.length ? { extends: ext } : {};
+};
+const objectMembers = (s, members) => {
+    const properties = [];
+    const methods = [];
+    const callSignatures = [];
+    const constructSignatures = [];
+    let indexSignature;
+    for (const m of members) {
+        if (ts.isPropertySignature(m) && ts.isIdentifier(m.name))
+            properties.push(property(s, m));
+        else if (ts.isMethodSignature(m) && ts.isIdentifier(m.name))
+            methods.push(method(s, m));
+        else if (ts.isCallSignatureDeclaration(m))
+            callSignatures.push(signature(s, m));
+        else if (ts.isConstructSignatureDeclaration(m))
+            constructSignatures.push(signature(s, m));
+        else if (ts.isIndexSignatureDeclaration(m))
+            indexSignature = indexSignatureDecl(s, m);
+    }
+    return {
+        properties,
+        methods,
+        ...(callSignatures.length ? { callSignatures } : {}),
+        ...(constructSignatures.length ? { constructSignatures } : {}),
+        ...(indexSignature ? { indexSignature } : {}),
+    };
+};
+const literalValue = (lit) => {
+    if (lit.kind === ts.SyntaxKind.NullKeyword)
+        return null;
+    if (ts.isStringLiteral(lit))
+        return lit.text;
+    if (ts.isNumericLiteral(lit))
+        return Number(lit.text);
+    if (lit.kind === ts.SyntaxKind.TrueKeyword)
+        return true;
+    if (lit.kind === ts.SyntaxKind.FalseKeyword)
+        return false;
+    if (ts.isBigIntLiteral(lit))
+        return BigInt(lit.text.replace(/n$/, ''));
+    return lit.getText();
+};
+const tupleElement = (s, el) => {
+    if (ts.isNamedTupleMember(el))
+        return part(s, el, 'tuple-element', {
+            type: scan.Type(s, el.type),
+            ...(el.questionToken ? { optional: true } : {}),
+            ...(el.dotDotDotToken ? { rest: true } : {}),
+        });
+    if (ts.isOptionalTypeNode(el))
+        return part(s, el, 'tuple-element', { type: scan.Type(s, el.type), optional: true });
+    if (ts.isRestTypeNode(el))
+        return part(s, el, 'tuple-element', { type: scan.Type(s, el.type), rest: true });
+    return part(s, el, 'tuple-element', { type: scan.Type(s, el) });
+};
+const INTRINSICS = {
+    [ts.SyntaxKind.StringKeyword]: 'string',
+    [ts.SyntaxKind.NumberKeyword]: 'number',
+    [ts.SyntaxKind.BooleanKeyword]: 'boolean',
+    [ts.SyntaxKind.BigIntKeyword]: 'bigint',
+    [ts.SyntaxKind.SymbolKeyword]: 'symbol',
+    [ts.SyntaxKind.VoidKeyword]: 'void',
+    [ts.SyntaxKind.UndefinedKeyword]: 'undefined',
+    [ts.SyntaxKind.NeverKeyword]: 'never',
+    [ts.SyntaxKind.AnyKeyword]: 'any',
+    [ts.SyntaxKind.UnknownKeyword]: 'unknown',
+    [ts.SyntaxKind.ObjectKeyword]: 'object',
+    [ts.SyntaxKind.ThisType]: 'this',
+};
+const TYPE_OPERATORS = {
+    [ts.SyntaxKind.KeyOfKeyword]: 'keyof',
+    [ts.SyntaxKind.ReadonlyKeyword]: 'readonly',
+    [ts.SyntaxKind.UniqueKeyword]: 'unique',
+};
+//# sourceMappingURL=scan.js.map