sveld 0.37.3 → 0.37.5

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
@@ -2185,7 +2187,27 @@ Chained references are also resolved:
 count?: number;
 ```
 
-Resolution follows up to 5 levels of indirection. Beyond that, the last resolved identifier name is used as the default value. If the identifier cannot be resolved (e.g., it is imported from another module), the variable name is used as-is.
+Resolution follows up to 5 levels of indirection. Beyond that, the last resolved identifier name is used as the default value.
+
+A named import resolves when the imported module (followed through re-exports) declares it as an `export const` with a string, number, boolean, or static template literal:
+
+```svelte
+<script>
+  // timing.js: export const TOOLTIP_LEAVE_DELAY_MS = 300;
+  import { TOOLTIP_LEAVE_DELAY_MS } from "./timing.js";
+
+  export let leaveDelayMs = TOOLTIP_LEAVE_DELAY_MS;
+</script>
+```
+
+```ts
+/**
+ * @default 300
+ */
+leaveDelayMs?: number;
+```
+
+Any other identifier that cannot be resolved (an `export let`, a computed value, a package import) is used as-is, and its type falls back to `any`.
 
 When an explicit `@default` annotation is provided, it always takes precedence over the resolved value.
 
@@ -2667,6 +2689,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

@@ -37,6 +37,13 @@ interface PendingCallDefaultCandidate {
     importedName?: string;
 }
 
+interface PendingConstDefaultCandidate {
+    propName: string;
+    location: "props" | "moduleExports";
+    importSource: string;
+    importedName: string;
+}
+
 interface PendingContextKeyCandidate {
     importSource: string;
     importedName: string;
@@ -60,6 +67,8 @@ interface ParsedComponentTypeScriptMetadata {
     referencesComponentGenerics?: boolean;
     /** Unresolved CallExpression defaults for the cross-file pass in `generateBundle`. */
     pendingCallDefaultCandidates?: PendingCallDefaultCandidate[];
+    /** Imported-identifier defaults for the cross-file pass in `generateBundle`. */
+    pendingConstDefaultCandidates?: PendingConstDefaultCandidate[];
     /** Unresolved `setContext` import keys for the cross-file pass in `generateBundle`. */
     pendingContextKeyCandidates?: PendingContextKeyCandidate[];
 }
@@ -110,11 +119,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 +153,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 +184,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 +448,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 +515,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";