sveld 0.37.3 → 0.37.4

package/README.md

@@ -435,7 +435,8 @@ Every diagnostic carries a stable, namespaced `code` (`"sveld/<kind>"`) alongsid
 | `sveld/rest-props-unresolved` | `warning` | Spread `$$restProps` onto a plain element (or `svelte:element`) instead of a component, or add an `@restProps` tag to type it manually. |
 | `sveld/context-duplicate-key` | `warning` | Remove the duplicate `setContext` call, or give it a distinct key; only the first call's shape is used. |
 | `sveld/spread-unresolved` | `warning` | Spread a local object literal or a variable with a resolvable type instead; otherwise the spread widens the generated type to `Record<string, any>`. |
-| `sveld/export-unresolved` | `warning` | Export a local declaration directly instead of re-exporting an import or a binding from another file; sveld only resolves exports of a local declaration. |
+| `sveld/export-unresolved` | `warning` | Export a local declaration directly. Instance-script exports are props, so move a re-export (`export { x } from "..."`, or `export { x }` of an import) into `<script context="module">`, where sveld writes it to the `.d.ts` as-is. |
+| `sveld/module-export-conflict` | `warning` | Rename the module-script export. `default` is always skipped (it collides with the component itself); a name matching the generated `<Name>Props`/`<Name>Exports` type breaks the `.d.ts` if the export carries a type. |
 | `sveld/extend-props-target-missing` | `error` | Point `@extends`/`@extendProps` at a file that exists, and (for a bundled `.svelte` target) name its generated `<Name>Props` interface exactly. |
 | `sveld/extend-props-duplicate` | `warning` | Remove the extra `@extends`/`@extendProps` tag; only the last one is used. |
 | `sveld/extend-props-override` | `warning` | Rename the own prop, or accept that it intentionally overrides the `@extends` target's prop of the same name. |
@@ -443,13 +444,14 @@ Every diagnostic carries a stable, namespaced `code` (`"sveld/<kind>"`) alongsid
 | `sveld/typedef-duplicate` | `warning` | Rename one of the `@typedef`/`@callback` declarations; only the later one is kept. |
 | `sveld/property-duplicate` | `warning` | Remove the duplicate `@property`; only the later one is kept. |
 | `sveld/generics-conflict` | `warning` | Rename one of the `@generics`/`@template` declarations to a distinct generic name. |
+| `sveld/event-description-ambiguous` | `warning` | Put an event's description above its `@event` tag (or indent it as a continuation of the tag's line), or give each event its own comment block. Unindented text after an `@event` is read as the description of the tag below it. |
 | `sveld/jsdoc-tag-dropped` | `warning` | Move the tag next to a `@slot`/`@snippet`/`@event`/`@typedef`/`@callback` tag in the same comment block so it has something to attach to. |
 | `sveld/internal-typedef-referenced` | `error` | Remove `@internal`/`@ignore` from the referenced typedef, or stop referencing it from public type text (inline the shape, or make the referencing item `@internal` too). |
 | `sveld/types-inline-unresolved` | `warning` | The import is kept as-is. Point it at a relative `.ts` file that exports a `type`/`interface`, or rename the colliding type. |
 
 #### Severity and `--strict=errors`
 
-Each diagnostic's `severity` is `"error"` (`example-compile-error`, `example-syntax-error`, `syntax-skipped`, `extend-props-target-missing`, `internal-typedef-referenced` — sveld emitted broken or unmodeled output) or `"warning"` (`prop-unknown-type`, `context-any-type`, `slot-missing-type`, `event-no-source`, `rest-props-unresolved`, `context-duplicate-key`, `spread-unresolved`, `export-unresolved`, `extend-props-duplicate`, `extend-props-override`, `jsdoc-unknown-tag`, `typedef-duplicate`, `property-duplicate`, `generics-conflict`, `jsdoc-tag-dropped`, `types-inline-unresolved` — a type fell back to `any`). Plain `strict: true` / `--strict` fails on both, unchanged from before. Pass `strict: "errors"` (or `--strict=errors`) to fail CI only on `error`-severity diagnostics, letting `any`-fallback warnings through:
+Each diagnostic's `severity` is `"error"` (`example-compile-error`, `example-syntax-error`, `syntax-skipped`, `extend-props-target-missing`, `internal-typedef-referenced` — sveld emitted broken or unmodeled output) or `"warning"` (`prop-unknown-type`, `context-any-type`, `slot-missing-type`, `event-no-source`, `rest-props-unresolved`, `context-duplicate-key`, `spread-unresolved`, `export-unresolved`, `module-export-conflict`, `extend-props-duplicate`, `extend-props-override`, `jsdoc-unknown-tag`, `typedef-duplicate`, `property-duplicate`, `generics-conflict`, `event-description-ambiguous`, `jsdoc-tag-dropped`, `types-inline-unresolved` — a type fell back to `any`). Plain `strict: true` / `--strict` fails on both, unchanged from before. Pass `strict: "errors"` (or `--strict=errors`) to fail CI only on `error`-severity diagnostics, letting `any`-fallback warnings through:
 
 ```sh
 npx sveld --json --strict=errors
@@ -2667,6 +2669,16 @@ function render(value: unknown, props: ComponentProps) {
 
 Both forms support the same modifiers as typedef properties elsewhere in this doc: optional properties (`[name]`), default values (`[name=value]`), and nested/discriminated-union shapes. See the linked sections above for full signatures and worked examples with generated output.
 
+A description can wrap onto continuation lines, which run until the next tag. Indent them past the `*` gutter to keep them attached to the tag unambiguously; an unindented line right above an `@event`/`@typedef`/`@slot` with no description of its own is read as that tag's description instead, and an unindented line after an event's last `@property` describes the event.
+
+```js
+/**
+ * @typedef {object} Config
+ * @property {number} itemHeight Height of each item in pixels, used for
+ *   virtualization math.
+ */
+```
+
 ### `@callback`
 
 The `@callback` tag defines a function type with `@param` and `@returns`, following the [TypeScript JSDoc `@callback` spec](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#callback). Like `@typedef`, callbacks are exported from the generated `.d.ts`.

package/lib/browser.d.ts

@@ -110,11 +110,22 @@ interface ComponentPropParam {
     optional?: boolean;
 }
 
+interface ComponentPropReExport {
+    /** Module specifier as written in the source (e.g. `"./utils.js"`). */
+    from: string;
+    /** Name `from` exports: `"default"` for a default import, `"*"` for `export *` or a namespace import. */
+    imported: string;
+}
+
 interface ComponentProp {
-    /** Public prop name. */
+    /** Public prop name; `"*"` for a bare `export * from "..."`. */
     name: string;
-    /** `"let"` (required), `"const"` (default), or `"function"`. */
-    kind: "let" | "const" | "function";
+    /**
+     * `"let"` (required), `"const"` (default), or `"function"`. `"re-export"`
+     * is module-export only: `export { x } from "..."`, `export * from "..."`,
+     * or `export { x }` of an imported binding, written to the `.d.ts` as-is.
+     */
+    kind: "let" | "const" | "function" | "re-export";
     /** True when declared with `const`. */
     constant: boolean;
     /** TypeScript type text. */
@@ -133,6 +144,12 @@ interface ComponentProp {
     params?: ComponentPropParam[];
     /** From JSDoc `@returns` on function props. */
     returnType?: string;
+    /**
+     * A function's own type parameter list from its `@template` tags (e.g.
+     * `T extends { id: string }`), without the angle brackets. Also prefixed
+     * onto `type` when that signature is built from `@param`/`@returns`.
+     */
+    typeParameters?: string;
     /**
      * True for arrow/function-expression initializers and bare `function`
      * declarations in every mode; additionally true for a function-shaped
@@ -158,6 +175,8 @@ interface ComponentProp {
     tags?: JsDocPassthroughTag[];
     /** True from `@ignore`/`@internal` JSDoc; excluded from every output by `buildComponentApiDocument`. */
     internal?: boolean;
+    /** Set when `kind` is `"re-export"`. */
+    reExport?: ComponentPropReExport;
     /** Source range when available. */
     source?: SourceRange;
 }
@@ -420,8 +439,17 @@ export class ComponentParser {
         tags?: JsDocPassthroughTag[];
         sveldIgnore?: string[];
         internal: boolean;
+        typeParameters?: string;
     } | undefined;
     private addModuleExport;
+    /**
+     * Resolves one `export { local as exported }` specifier to the variable
+     * declarator it names. Each specifier resolves on its own, so
+     * `export { a, b }` exports both, and `const a = 1, b = ""; export { b }`
+     * exports `b`'s declarator rather than the first one in the declaration.
+     */
+    private resolveExportSpecifier;
+    private recordUnresolvedExportSpecifier;
     /**
      * @example
      * ```ts
@@ -478,7 +506,7 @@ export class ComponentParser {
     parseSvelteComponent(source: string, diagnostics: ComponentParserDiagnostics): ParsedComponent;
 }
 
-export type SveldDiagnosticKind = "prop-unknown-type" | "context-any-type" | "slot-missing-type" | "event-no-source" | "example-compile-error" | "example-syntax-error" | "syntax-skipped" | "rest-props-unresolved" | "context-duplicate-key" | "spread-unresolved" | "export-unresolved" | "extend-props-target-missing" | "extend-props-duplicate" | "extend-props-override" | "jsdoc-unknown-tag" | "typedef-duplicate" | "property-duplicate" | "generics-conflict" | "jsdoc-tag-dropped" | "internal-typedef-referenced" | "types-inline-unresolved";
+export type SveldDiagnosticKind = "prop-unknown-type" | "context-any-type" | "slot-missing-type" | "event-no-source" | "example-compile-error" | "example-syntax-error" | "syntax-skipped" | "rest-props-unresolved" | "context-duplicate-key" | "spread-unresolved" | "export-unresolved" | "module-export-conflict" | "extend-props-target-missing" | "extend-props-duplicate" | "extend-props-override" | "jsdoc-unknown-tag" | "typedef-duplicate" | "property-duplicate" | "generics-conflict" | "event-description-ambiguous" | "jsdoc-tag-dropped" | "internal-typedef-referenced" | "types-inline-unresolved";
 
 type SveldDiagnosticSeverity = "error" | "warning";