svelte-docinfo 0.1.0

package/dist/tsdoc.d.ts

@@ -0,0 +1,145 @@
+/**
+ * TSDoc/JSDoc parsing helpers using the TypeScript compiler API.
+ *
+ * Provides `parseComment` for extracting JSDoc/TSDoc from TypeScript nodes.
+ * Primarily designed for build-time code generation but can be used at runtime.
+ *
+ * ## Design
+ *
+ * Pure extraction approach: extracts documentation as-is with minimal transformation,
+ * preserving source intent. Works around TypeScript compiler API quirks where needed.
+ *
+ * Supports both regular TypeScript and Svelte components (via svelte2tsx output).
+ *
+ * ## Tag support
+ *
+ * Supports a subset of standard TSDoc tags:
+ * `@param`, `@returns`, `@throws`, `@example`, `@deprecated`, `@see`, `@since`, `@default`, `@nodocs`.
+ *
+ * The `@nodocs` tag excludes exports from documentation and flat namespace validation.
+ * The declaration is still exported and usable, just not documented.
+ *
+ * Also supports `@mutates` (non-standard) for documenting mutations to parameters or external state.
+ * Uses same format as `@param`: `@mutates key - description of mutation`. The key is
+ * unvalidated — typically a parameter name, but compound paths (`this.foo`, `obj.field`)
+ * and external state references are accepted as-is.
+ *
+ * Only `@returns` is supported (not `@return`).
+ *
+ * The `@see` tag supports multiple formats: plain URLs (`https://...`), `{@link}` syntax, and module names.
+ * Relative/absolute path support in `@see` is TBD.
+ *
+ * ## Behavioral notes
+ *
+ * Due to TS Compiler API limitations:
+ * - TS API includes dash separator in `@param` tag text; we strip the leading `- ` as it's syntax, not content
+ * - `@throws` tags have `{Type}` stripped by TS API; fallback regex extracts first word as error type
+ * - TS API strips URL protocols from `@see` tag text; we use `getText()` to preserve original format including `{@link}` syntax
+ *
+ * @see `declaration-build.ts` for `DeclarationJsonBuild`
+ * @see `typescript-exports.ts` and `svelte.ts` as primary consumers
+ *
+ * @module
+ */
+import ts from 'typescript';
+import type { DeclarationJsonBuild, MemberJsonBuild } from './declaration-build.js';
+/**
+ * Parsed JSDoc/TSDoc comment with structured metadata.
+ *
+ * Returned by `parseComment` — consumers typically pass this to `applyToDeclaration`
+ * to populate `DeclarationJsonBuild` fields.
+ */
+export interface TsdocParsedComment {
+    /** Comment text (excluding comment markers). */
+    text: string;
+    /** Parameter descriptions mapped by parameter name. */
+    params: Record<string, string>;
+    /** Return value description from `@returns`. */
+    returns?: string;
+    /** Thrown errors from `@throws`. */
+    throws?: Array<{
+        type?: string;
+        description: string;
+    }>;
+    /** Code examples from `@example`. */
+    examples?: Array<string>;
+    /** Deprecation message from `@deprecated`. */
+    deprecatedMessage?: string;
+    /** Related references from `@see`. */
+    seeAlso?: Array<string>;
+    /** Version information from `@since`. */
+    since?: string;
+    /** Default value from `@default` tag. */
+    defaultValue?: string;
+    /** Mutation documentation from `@mutates` (non-standard), mapped by parameter name. */
+    mutates?: Record<string, string>;
+    /** Whether to exclude from documentation. From `@nodocs` tag. */
+    nodocs?: boolean;
+}
+/**
+ * Parse JSDoc comment from a TypeScript node.
+ *
+ * Extracts and parses all JSDoc tags including:
+ *
+ * - `@param` - parameter descriptions
+ * - `@returns` - return value description
+ * - `@throws` - error documentation
+ * - `@example` - code examples
+ * - `@deprecated` - deprecation warnings
+ * - `@see` - related references
+ * - `@since` - version information
+ * - `@default` - default value
+ * - `@mutates` - mutation documentation (non-standard)
+ * - `@nodocs` - exclusion flag (non-standard)
+ *
+ * @param node - the TypeScript node to extract JSDoc from
+ * @param sourceFile - source file (used for extracting full `@see` tag text)
+ * @returns parsed comment with structured metadata, or undefined if no JSDoc found
+ *
+ * @example
+ * ```ts
+ * const tsdoc = parseComment(declarationNode, sourceFile);
+ * if (tsdoc) {
+ *   console.log(tsdoc.text); // main comment text
+ *   console.log(tsdoc.params); // {paramName: 'description'}
+ * }
+ * ```
+ */
+export declare const parseComment: (node: ts.Node, sourceFile: ts.SourceFile) => TsdocParsedComment | undefined;
+/**
+ * Apply parsed TSDoc metadata to a declaration.
+ *
+ * Consolidates the common pattern of assigning TSDoc fields to declarations,
+ * with conditional assignment for array fields (only if non-empty).
+ *
+ * @param declaration - declaration object to update
+ * @param tsdoc - parsed TSDoc comment (if available)
+ * @mutates declaration - adds docComment, deprecatedMessage, examples, seeAlso, throws, since, mutates, defaultValue fields
+ */
+export declare const applyToDeclaration: (declaration: DeclarationJsonBuild | MemberJsonBuild, tsdoc: TsdocParsedComment | undefined) => void;
+/**
+ * Check if a TypeScript node has a `@module` JSDoc tag.
+ *
+ * Used to prevent `@module` comments from leaking into declaration `docComment` fields.
+ * Module-level comments are extracted separately by `extractModuleComment`.
+ *
+ * @param node - the TypeScript node to check
+ * @returns true if any JSDoc tag on the node is `@module`
+ */
+export declare const hasModuleTag: (node: ts.Node) => boolean;
+/**
+ * Clean raw JSDoc comment text by removing comment markers and leading asterisks.
+ *
+ * Transforms `/** ... *\/` style comments into clean text.
+ *
+ * @param commentText - the raw comment text including `/**` and `*\/` markers
+ * @returns cleaned comment text, or undefined if empty after cleaning
+ *
+ * @example
+ * ```ts
+ * cleanComment('/** Hello world *\/') // => 'Hello world'
+ * cleanComment('/**\n * Line 1\n * Line 2\n *\/') // => 'Line 1\nLine 2'
+ * ```
+ */
+export declare const cleanComment: (commentText: string) => string | undefined;
+//# sourceMappingURL=tsdoc.d.ts.map

package/dist/tsdoc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tsdoc.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/tsdoc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,KAAK,EAAC,oBAAoB,EAAE,eAAe,EAAC,MAAM,wBAAwB,CAAC;AAElF;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IAClC,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,MAAM,CAAC,EAAE,KAAK,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IACrD,qCAAqC;IACrC,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACzB,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,sCAAsC;IACtC,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,YAAY,GACxB,MAAM,EAAE,CAAC,IAAI,EACb,YAAY,EAAE,CAAC,UAAU,KACvB,kBAAkB,GAAG,SAoGvB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAC9B,aAAa,oBAAoB,GAAG,eAAe,EACnD,OAAO,kBAAkB,GAAG,SAAS,KACnC,IAgCF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,EAAE,CAAC,IAAI,KAAG,OACsB,CAAC;AAEpE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY,GAAI,aAAa,MAAM,KAAG,MAAM,GAAG,SAW3D,CAAC"}

package/dist/tsdoc.js

@@ -0,0 +1,262 @@
+/**
+ * TSDoc/JSDoc parsing helpers using the TypeScript compiler API.
+ *
+ * Provides `parseComment` for extracting JSDoc/TSDoc from TypeScript nodes.
+ * Primarily designed for build-time code generation but can be used at runtime.
+ *
+ * ## Design
+ *
+ * Pure extraction approach: extracts documentation as-is with minimal transformation,
+ * preserving source intent. Works around TypeScript compiler API quirks where needed.
+ *
+ * Supports both regular TypeScript and Svelte components (via svelte2tsx output).
+ *
+ * ## Tag support
+ *
+ * Supports a subset of standard TSDoc tags:
+ * `@param`, `@returns`, `@throws`, `@example`, `@deprecated`, `@see`, `@since`, `@default`, `@nodocs`.
+ *
+ * The `@nodocs` tag excludes exports from documentation and flat namespace validation.
+ * The declaration is still exported and usable, just not documented.
+ *
+ * Also supports `@mutates` (non-standard) for documenting mutations to parameters or external state.
+ * Uses same format as `@param`: `@mutates key - description of mutation`. The key is
+ * unvalidated — typically a parameter name, but compound paths (`this.foo`, `obj.field`)
+ * and external state references are accepted as-is.
+ *
+ * Only `@returns` is supported (not `@return`).
+ *
+ * The `@see` tag supports multiple formats: plain URLs (`https://...`), `{@link}` syntax, and module names.
+ * Relative/absolute path support in `@see` is TBD.
+ *
+ * ## Behavioral notes
+ *
+ * Due to TS Compiler API limitations:
+ * - TS API includes dash separator in `@param` tag text; we strip the leading `- ` as it's syntax, not content
+ * - `@throws` tags have `{Type}` stripped by TS API; fallback regex extracts first word as error type
+ * - TS API strips URL protocols from `@see` tag text; we use `getText()` to preserve original format including `{@link}` syntax
+ *
+ * @see `declaration-build.ts` for `DeclarationJsonBuild`
+ * @see `typescript-exports.ts` and `svelte.ts` as primary consumers
+ *
+ * @module
+ */
+import ts from 'typescript';
+/**
+ * Clean TSDoc tag description text by stripping leading `- ` separator.
+ * TSDoc syntax uses `- ` as a separator, but it shouldn't be part of the description content.
+ * Only strips the first `- ` to preserve markdown lists later in the text.
+ *
+ * @param text - the tag text to clean
+ * @returns cleaned text with leading `- ` removed if present
+ */
+const cleanTagDescription = (text) => text.trim().replace(/^-\s+/, '');
+/**
+ * Parse JSDoc comment from a TypeScript node.
+ *
+ * Extracts and parses all JSDoc tags including:
+ *
+ * - `@param` - parameter descriptions
+ * - `@returns` - return value description
+ * - `@throws` - error documentation
+ * - `@example` - code examples
+ * - `@deprecated` - deprecation warnings
+ * - `@see` - related references
+ * - `@since` - version information
+ * - `@default` - default value
+ * - `@mutates` - mutation documentation (non-standard)
+ * - `@nodocs` - exclusion flag (non-standard)
+ *
+ * @param node - the TypeScript node to extract JSDoc from
+ * @param sourceFile - source file (used for extracting full `@see` tag text)
+ * @returns parsed comment with structured metadata, or undefined if no JSDoc found
+ *
+ * @example
+ * ```ts
+ * const tsdoc = parseComment(declarationNode, sourceFile);
+ * if (tsdoc) {
+ *   console.log(tsdoc.text); // main comment text
+ *   console.log(tsdoc.params); // {paramName: 'description'}
+ * }
+ * ```
+ */
+export const parseComment = (node, sourceFile) => {
+    const tsdocComments = ts.getJSDocCommentsAndTags(node);
+    if (tsdocComments.length === 0)
+        return undefined;
+    let fullText = '';
+    const params = {};
+    let returns;
+    let throws;
+    let examples;
+    let deprecatedMessage;
+    let seeAlso;
+    let since;
+    let defaultValue;
+    let mutates;
+    let nodocs;
+    // Extract main comment text
+    for (const comment of tsdocComments) {
+        if (ts.isJSDoc(comment) && comment.comment) {
+            const text = typeof comment.comment === 'string'
+                ? comment.comment
+                : comment.comment.map((c) => c.text).join('');
+            fullText += text + '\n';
+        }
+    }
+    // Extract tags
+    const tags = ts.getJSDocTags(node);
+    for (const tag of tags) {
+        const tagText = typeof tag.comment === 'string' ? tag.comment : tag.comment?.map((c) => c.text).join('');
+        const tagName = tag.tagName.text;
+        if (tagName === 'param' && ts.isJSDocParameterTag(tag)) {
+            // Extract parameter name and description
+            const paramName = ts.isIdentifier(tag.name) ? tag.name.text : tag.name.getText();
+            if (paramName && tagText) {
+                params[paramName] = cleanTagDescription(tagText);
+            }
+        }
+        else if (tagName === 'returns' && tagText) {
+            returns = tagText.trim();
+        }
+        else if (tagName === 'throws' && tagText) {
+            // Try to extract error type and description
+            const match = /^\{?(\w+)\}?\s+(.+)/.exec(tagText);
+            if (match) {
+                (throws ??= []).push({ type: match[1], description: cleanTagDescription(match[2]) });
+            }
+            else {
+                (throws ??= []).push({ description: cleanTagDescription(tagText) });
+            }
+        }
+        else if (tagName === 'example' && tagText) {
+            (examples ??= []).push(tagText.trim());
+        }
+        else if (tagName === 'deprecated') {
+            deprecatedMessage = tagText?.trim() ?? '';
+        }
+        else if (tagName === 'see') {
+            // The TS API strips 'https' from URLs in @see tags, so get full text from source
+            const fullTagText = tag.getText(sourceFile);
+            // Extract content after @see, handling JSDoc formatting artifacts
+            const seeContent = fullTagText
+                .replace(/^@see\s+/, '') // remove @see prefix
+                .replace(/\n\s*\*\s*/g, ' ') // remove JSDoc line continuations
+                .replace(/\s*\*\s*$/, '') // remove trailing asterisk artifacts
+                .trim();
+            if (seeContent) {
+                (seeAlso ??= []).push(seeContent);
+            }
+        }
+        else if (tagName === 'since' && tagText) {
+            since = tagText.trim();
+        }
+        else if (tagName === 'default' && tagText) {
+            defaultValue = tagText.trim();
+        }
+        else if (tagName === 'mutates' && tagText) {
+            // Extract parameter name and description (format: @mutates paramName - description)
+            const cleanedText = cleanTagDescription(tagText);
+            const match = /^(\w+)\s+-?\s*(.+)/.exec(cleanedText);
+            if (match) {
+                const paramName = match[1];
+                const description = match[2].trim();
+                (mutates ??= {})[paramName] = description;
+            }
+        }
+        else if (tagName === 'nodocs') {
+            nodocs = true;
+        }
+    }
+    fullText = fullText.trim();
+    return {
+        text: fullText,
+        params,
+        returns,
+        throws,
+        examples,
+        deprecatedMessage,
+        seeAlso,
+        since,
+        defaultValue,
+        mutates,
+        nodocs,
+    };
+};
+/**
+ * Apply parsed TSDoc metadata to a declaration.
+ *
+ * Consolidates the common pattern of assigning TSDoc fields to declarations,
+ * with conditional assignment for array fields (only if non-empty).
+ *
+ * @param declaration - declaration object to update
+ * @param tsdoc - parsed TSDoc comment (if available)
+ * @mutates declaration - adds docComment, deprecatedMessage, examples, seeAlso, throws, since, mutates, defaultValue fields
+ */
+export const applyToDeclaration = (declaration, tsdoc) => {
+    if (!tsdoc)
+        return;
+    if (tsdoc.text) {
+        declaration.docComment = tsdoc.text;
+    }
+    if (tsdoc.deprecatedMessage !== undefined) {
+        declaration.deprecatedMessage = tsdoc.deprecatedMessage;
+    }
+    // Only assign arrays if they have content
+    if (tsdoc.examples?.length) {
+        declaration.examples = tsdoc.examples;
+    }
+    if (tsdoc.seeAlso?.length) {
+        declaration.seeAlso = tsdoc.seeAlso;
+    }
+    if (tsdoc.throws?.length) {
+        declaration.throws = tsdoc.throws;
+    }
+    if (tsdoc.since) {
+        declaration.since = tsdoc.since;
+    }
+    if (tsdoc.mutates && Object.keys(tsdoc.mutates).length > 0) {
+        declaration.mutates = tsdoc.mutates;
+    }
+    // `defaultValue` is schema-allowed on variable declarations/members only;
+    // `z.strictObject` would reject it on other kinds. Component props consume
+    // the parsed `defaultValue` directly in `svelte.ts` (not via this helper).
+    if (tsdoc.defaultValue !== undefined && declaration.kind === 'variable') {
+        declaration.defaultValue = tsdoc.defaultValue;
+    }
+};
+/**
+ * Check if a TypeScript node has a `@module` JSDoc tag.
+ *
+ * Used to prevent `@module` comments from leaking into declaration `docComment` fields.
+ * Module-level comments are extracted separately by `extractModuleComment`.
+ *
+ * @param node - the TypeScript node to check
+ * @returns true if any JSDoc tag on the node is `@module`
+ */
+export const hasModuleTag = (node) => ts.getJSDocTags(node).some((tag) => tag.tagName.text === 'module');
+/**
+ * Clean raw JSDoc comment text by removing comment markers and leading asterisks.
+ *
+ * Transforms `/** ... *\/` style comments into clean text.
+ *
+ * @param commentText - the raw comment text including `/**` and `*\/` markers
+ * @returns cleaned comment text, or undefined if empty after cleaning
+ *
+ * @example
+ * ```ts
+ * cleanComment('/** Hello world *\/') // => 'Hello world'
+ * cleanComment('/**\n * Line 1\n * Line 2\n *\/') // => 'Line 1\nLine 2'
+ * ```
+ */
+export const cleanComment = (commentText) => {
+    const text = commentText
+        .replace(/^\/\*\*/, '')
+        .replace(/\*\/$/, '')
+        .replace(/\r\n/g, '\n')
+        .split('\n')
+        .map((line) => line.replace(/^\s*\*\s?/, ''))
+        .join('\n')
+        .trim();
+    return text || undefined;
+};