svelte-docinfo 0.2.1 → 0.4.0

package/README.md

@@ -37,15 +37,14 @@ but instead of AST-only inspection it uses the TypeScript compiler API for riche
 and also analyzes TypeScript modules.
 The docs [compare](https://svelte-docinfo.fuz.dev/docs/introduction#Compared-to-sveld) them.
 
-This is an early release --
-there are gaps to be filled and design choices to make,
-but for Svelte 5 it's mostly complete and used in production websites.
-Please open issues for bugs
+The library is mostly complete for Svelte 5 and used in production websites,
+but you may find gaps and flaws -- please open issues for bugs
 and [discussions](https://github.com/fuzdev/svelte-docinfo/discussions)
 for everything else!
 
-**AI disclosure:** the code and docs beyond the intro were written by Claude Code with uneven human guidance.
-The first release took about 5 months of intermittent work and 500 manual commits.
+**AI disclosure:** the code and docs beyond the intro
+were mostly written by Claude Code with uneven human guidance.
+The first release took 5 months of intermittent work and ~500 manual commits.
 
 ## Quick start
 
@@ -175,6 +174,8 @@ All three produce the same JSON shape:
 }
 ```
 
+For many more worked examples — source input paired with the exact JSON `svelte-docinfo` emits — browse the [test fixtures](https://github.com/fuzdev/svelte-docinfo/tree/main/src/test/fixtures), where each case sits beside its `expected.json`.
+
 ## Vite plugin
 
 1. Add the plugin to `vite.config.ts`:
@@ -337,7 +338,8 @@ Known gaps: standalone `namespace Foo {}` declarations and decorators are not ye
 was this project's main inspiration.
 
 Extracted from [fuz_ui](https://github.com/fuzdev/fuz_ui),
-which has example components using the data for docs websites.
+which has example components using the data for docs websites like
+[`DeclarationDetail`](https://github.com/fuzdev/fuz_ui/blob/main/src/lib/DeclarationDetail.svelte).
 
 `svelte-docinfo` is more featureful than it would be
 otherwise thanks to LLM assistance, mostly Claude Code.

package/dist/analyze-core.d.ts

@@ -2,8 +2,8 @@
  * Pure two-phase analysis orchestrator.
  *
  * Extracted from `analyze.ts` to break what would otherwise be a circular
- * import: `session.ts → analyze.ts (for the orchestrator) → session.ts (for
- * the wrappers)`. With the orchestrator here, both `session.ts` and
+ * import: `session.ts` → `analyze.ts` (for the orchestrator) → `session.ts`
+ * (for the wrappers). With the orchestrator here, both `session.ts` and
  * `analyze.ts` import downward into this module without depending on each
  * other.
  *

package/dist/analyze-core.js

@@ -2,8 +2,8 @@
  * Pure two-phase analysis orchestrator.
  *
  * Extracted from `analyze.ts` to break what would otherwise be a circular
- * import: `session.ts → analyze.ts (for the orchestrator) → session.ts (for
- * the wrappers)`. With the orchestrator here, both `session.ts` and
+ * import: `session.ts` → `analyze.ts` (for the orchestrator) → `session.ts`
+ * (for the wrappers). With the orchestrator here, both `session.ts` and
  * `analyze.ts` import downward into this module without depending on each
  * other.
  *

package/dist/svelte.d.ts

@@ -15,7 +15,7 @@
  * There is no Svelte 4 compatibility layer.
  *
  * @see `typescript-exports.ts` for `analyzeExports`, `extractModuleComment`
- * @see `typescript-extract-shared.ts` for `parseGenericParam`, `filterIntersectionProperties`
+ * @see `typescript-extract-shared.ts` for `parseGenericParam`, `filterExternalProperties`
  * @see `typescript-program.ts` for `IsExternalFile`, `createIsExternalFile`
  * @see `tsdoc.ts` for `parseComment`, `applyToDeclaration`
  * @see `source.ts` for `SourceFileInfo`, `getComponentName`

package/dist/svelte.js

@@ -15,7 +15,7 @@
  * There is no Svelte 4 compatibility layer.
  *
  * @see `typescript-exports.ts` for `analyzeExports`, `extractModuleComment`
- * @see `typescript-extract-shared.ts` for `parseGenericParam`, `filterIntersectionProperties`
+ * @see `typescript-extract-shared.ts` for `parseGenericParam`, `filterExternalProperties`
  * @see `typescript-program.ts` for `IsExternalFile`, `createIsExternalFile`
  * @see `tsdoc.ts` for `parseComment`, `applyToDeclaration`
  * @see `source.ts` for `SourceFileInfo`, `getComponentName`
@@ -28,7 +28,7 @@ import { svelte2tsx } from 'svelte2tsx';
 import ts from 'typescript';
 import { parseComment, applyToDeclaration, hasModuleTag } from './tsdoc.js';
 import { createIsExternalFile } from './typescript-program.js';
-import { parseGenericParam, filterIntersectionProperties } from './typescript-extract-shared.js';
+import { parseGenericParam, filterExternalProperties } from './typescript-extract-shared.js';
 import { extractModuleComment, analyzeExports } from './typescript-exports.js';
 import { getComponentName, SVELTE_VIRTUAL_SUFFIX } from './source.js';
 import { extractDependencies } from './source-config.js';
@@ -638,14 +638,14 @@ const extractPropsViaChecker = (virtualSource, checker, componentName, filePath,
     // Detect `acceptsChildren` via type inference: `children` must resolve to a
     // `Snippet<...>` type. Checking the symbol name alone (the previous approach)
     // misreports a non-Snippet `children` (e.g. `children: string`) as accepting
-    // children. The lookup runs on the unfiltered intersection so inherited
+    // children. The lookup runs on the unfiltered props type so inherited
     // `children` from `SvelteHTMLElements`/`DOMAttributes` (declared as `Snippet`)
     // is honored even when its declaration lives in node_modules.
-    const allProperties = propsType.getProperties();
     const acceptsChildren = detectChildrenSnippet(propsType, propsTypeNode, checker, diagnostics, componentName, filePath);
-    // For intersection types, filter out properties from external sources (node_modules)
-    const intersectionResult = filterIntersectionProperties(propsType, propsTypeNode, checker, isExternalFile);
-    const properties = intersectionResult?.properties ?? allProperties;
+    // Drop properties contributed by external types (node_modules / svelte's
+    // element-attribute bags like `SvelteHTMLElements['li']`); those external
+    // types are summarized in `intersects` rather than enumerated as props.
+    const { properties, externalTypes } = filterExternalProperties(propsType, propsTypeNode, checker, isExternalFile);
     const props = [];
     for (const prop of properties) {
         const propDecl = prop.valueDeclaration || prop.declarations?.[0];
@@ -693,7 +693,7 @@ const extractPropsViaChecker = (virtualSource, checker, componentName, filePath,
         const propSourceFile = propDecl?.getSourceFile();
         props.push(assemblePropInfo(prop.name, typeString, optional, propDecl, propSourceFile, propsDefaults, bindableProps, snippetParams));
     }
-    return { props, intersectionTypes: intersectionResult?.intersectionTypes, acceptsChildren };
+    return { props, externalTypes, acceptsChildren };
 };
 /**
  * Analyze a Svelte module using checker-backed analysis.
@@ -813,15 +813,15 @@ export const analyzeSvelteModule = (sourceFile, modulePath, checker, options, di
     const isExternalFile = createIsExternalFile(options);
     // Extract props via checker (resolves imported types)
     const { bindableProps, propsDefaults } = extractPropsMetadata(virtualTsSource);
-    const { props, intersectionTypes, acceptsChildren: propsAcceptsChildren, } = extractPropsViaChecker(virtualTsSource, checker, componentName, modulePath, virtualFile.sourceMap, diagnostics, propsDefaults, bindableProps, isExternalFile);
+    const { props, externalTypes, acceptsChildren: propsAcceptsChildren, } = extractPropsViaChecker(virtualTsSource, checker, componentName, modulePath, virtualFile.sourceMap, diagnostics, propsDefaults, bindableProps, isExternalFile);
     if (props.length > 0) {
         componentDecl.props = props;
     }
-    if (intersectionTypes?.length) {
-        componentDecl.intersects = intersectionTypes;
+    if (externalTypes?.length) {
+        componentDecl.intersects = externalTypes;
     }
     // Determine acceptsChildren via two paths:
-    // Path A: children found in props type (from extractPropsViaChecker, before intersection filtering)
+    // Path A: children found in props type (from extractPropsViaChecker, before external-property filtering)
     // Path B: implicit children usage in template (for components without $props() children declaration)
     let acceptsChildren = propsAcceptsChildren;
     if (!acceptsChildren) {

package/dist/typescript-extract-shared.d.ts

@@ -86,19 +86,23 @@ export declare const isExternalIntersectionBranch: (branchNode: ts.TypeNode, che
  */
 export declare const resolveIntersectionTypeNode: (type: ts.Type, typeNode: ts.Node) => ts.IntersectionTypeNode | undefined;
 /**
- * Filter intersection type properties to exclude those from external sources,
- * and extract type names for branches whose properties are all external.
- *
- * Returns `null` for non-intersection types (caller should use unfiltered properties).
- * For intersection types, returns filtered properties and external type names.
- *
- * Per-property filtering works through utility types (Partial, Pick, Readonly)
- * because TypeScript preserves original declaration sources on mapped type properties.
+ * Partition a type's properties into local (kept) and external (dropped), and
+ * collect the external type references that contributed the dropped ones.
+ *
+ * Applies to any composition shape — intersection, union, bare reference,
+ * indexed-access — not only intersections. Membership is decided per property
+ * by declaration origin (`isExternalProperty`), which is structure-agnostic:
+ * TypeScript preserves original declaration sources on derived properties, so
+ * the test gives the right answer through utility-type wrappers (Partial, Pick,
+ * `OmitStrict`) too. A property with no declarations (synthesized) is treated as
+ * local and kept. The external-type labels for `intersects` come from an AST
+ * walk (`collectExternalTypeRefs`) — the authoritative source for the
+ * `&`/`|`/index-access shape inference would otherwise erase.
  */
-export declare const filterIntersectionProperties: (type: ts.Type, typeNode: ts.Node, checker: ts.TypeChecker, isExternalFile: IsExternalFile) => {
+export declare const filterExternalProperties: (type: ts.Type, typeNode: ts.Node, checker: ts.TypeChecker, isExternalFile: IsExternalFile) => {
     properties: Array<ts.Symbol>;
-    intersectionTypes: Array<string>;
-} | null;
+    externalTypes: Array<string>;
+};
 /**
  * Detect a Svelte 5 reactivity rune from a variable or property initializer.
  *

package/dist/typescript-extract-shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"typescript-extract-shared.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/typescript-extract-shared.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"typescript-extract-shared.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/typescript-extract-shared.ts"],"names":[],"mappings":"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"}

package/dist/typescript-extract-shared.js

@@ -350,38 +350,92 @@ export const resolveIntersectionTypeNode = (type, typeNode) => {
     return undefined;
 };
 /**
- * Filter intersection type properties to exclude those from external sources,
- * and extract type names for branches whose properties are all external.
+ * Determine whether a type-reference / indexed-access node names a type whose
+ * properties all come from external files (e.g. `SvelteHTMLElements['li']`,
+ * `HTMLAttributes<HTMLDivElement>`). Such a node is an external attribute "bag"
+ * that should be summarized in `intersects` rather than enumerated as members.
  *
- * Returns `null` for non-intersection types (caller should use unfiltered properties).
- * For intersection types, returns filtered properties and external type names.
+ * Mirrors the per-property origin test used for membership: external only when
+ * the node has at least one property and every property is external. A
+ * zero-property branch (e.g. a pure index signature) is not surfaced — there is
+ * no named member to attribute to it.
+ */
+const isExternalTypeRefNode = (node, checker, isExternalFile) => {
+    const props = checker.getTypeAtLocation(node).getProperties();
+    return props.length > 0 && props.every((p) => isExternalProperty(p, isExternalFile));
+};
+/**
+ * Walk a written type node and collect, in source order, the verbatim text of
+ * every external type reference it composes.
+ *
+ * Structure is read from the AST rather than the inferred type because
+ * inference erases it: `(A | B) & C` normalizes to a union and `X['k']`
+ * flattens to a property bag, both losing the `&`/`|`/index-access shape the
+ * author wrote. Composition nodes (intersection, union, parenthesized) recurse;
+ * leaf references (`TypeReference`, `IndexedAccessType`) are tested with
+ * `isExternalTypeRefNode` and, when external, emitted via `getText()`. Inline
+ * object literals and other local shapes contribute no entry.
+ *
+ * @mutates out - appends each external reference's source text
+ */
+const collectExternalTypeRefs = (node, checker, isExternalFile, out) => {
+    if (ts.isParenthesizedTypeNode(node)) {
+        collectExternalTypeRefs(node.type, checker, isExternalFile, out);
+    }
+    else if (ts.isIntersectionTypeNode(node) || ts.isUnionTypeNode(node)) {
+        for (const branch of node.types)
+            collectExternalTypeRefs(branch, checker, isExternalFile, out);
+    }
+    else if (ts.isTypeReferenceNode(node) || ts.isIndexedAccessTypeNode(node)) {
+        if (isExternalTypeRefNode(node, checker, isExternalFile))
+            out.push(node.getText());
+    }
+};
+/**
+ * Resolve a props/type-alias annotation node to the written type node whose
+ * structure drives `intersects` extraction.
+ *
+ * The svelte2tsx props annotation is a reference to a generated `$$ComponentProps`
+ * alias; unwrap one level of *local* type-alias reference so the underlying
+ * composition (`SvelteHTMLElements['li']`, `(A | B) & C`, …) is visible. External
+ * alias references are left intact so they read as a single named bag rather than
+ * leaking their node_modules-internal definition. Type-alias callers pass the
+ * written node directly, so for them this is a no-op.
+ */
+const resolveAnnotationTypeNode = (typeNode, checker, isExternalFile) => {
+    if (ts.isTypeReferenceNode(typeNode)) {
+        const aliasDecl = checker
+            .getSymbolAtLocation(typeNode.typeName)
+            ?.getDeclarations()
+            ?.find(ts.isTypeAliasDeclaration);
+        if (aliasDecl && !isExternalFile(aliasDecl.getSourceFile()))
+            return aliasDecl.type;
+    }
+    return ts.isTypeNode(typeNode) ? typeNode : undefined;
+};
+/**
+ * Partition a type's properties into local (kept) and external (dropped), and
+ * collect the external type references that contributed the dropped ones.
  *
- * Per-property filtering works through utility types (Partial, Pick, Readonly)
- * because TypeScript preserves original declaration sources on mapped type properties.
+ * Applies to any composition shape — intersection, union, bare reference,
+ * indexed-access — not only intersections. Membership is decided per property
+ * by declaration origin (`isExternalProperty`), which is structure-agnostic:
+ * TypeScript preserves original declaration sources on derived properties, so
+ * the test gives the right answer through utility-type wrappers (Partial, Pick,
+ * `OmitStrict`) too. A property with no declarations (synthesized) is treated as
+ * local and kept. The external-type labels for `intersects` come from an AST
+ * walk (`collectExternalTypeRefs`) — the authoritative source for the
+ * `&`/`|`/index-access shape inference would otherwise erase.
  */
-export const filterIntersectionProperties = (type, typeNode, checker, isExternalFile) => {
-    if (!type.isIntersection())
-        return null;
+export const filterExternalProperties = (type, typeNode, checker, isExternalFile) => {
     const properties = type
         .getProperties()
         .filter((prop) => !isExternalProperty(prop, isExternalFile));
-    // Resolve through type aliases (e.g., svelte2tsx $$ComponentProps) to find
-    // the IntersectionTypeNode for `intersects` extraction.
-    const intersectionNode = resolveIntersectionTypeNode(type, typeNode);
-    const intersectionTypes = [];
-    if (intersectionNode) {
-        for (const branch of intersectionNode.types) {
-            if (ts.isTypeReferenceNode(branch) || ts.isIndexedAccessTypeNode(branch)) {
-                const branchType = checker.getTypeAtLocation(branch);
-                const branchProps = branchType.getProperties();
-                if (branchProps.length > 0 &&
-                    branchProps.every((p) => isExternalProperty(p, isExternalFile))) {
-                    intersectionTypes.push(branch.getText());
-                }
-            }
-        }
-    }
-    return { properties, intersectionTypes };
+    const externalTypes = [];
+    const annotation = resolveAnnotationTypeNode(typeNode, checker, isExternalFile);
+    if (annotation)
+        collectExternalTypeRefs(annotation, checker, isExternalFile, externalTypes);
+    return { properties, externalTypes };
 };
 /**
  * Detect a Svelte 5 reactivity rune from a variable or property initializer.

package/dist/typescript-extract-type-properties.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"typescript-extract-type-properties.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/typescript-extract-type-properties.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,MAAM,YAAY,CAAC;AAG5B,OAAO,KAAK,EAAC,oBAAoB,EAAkB,MAAM,wBAAwB,CAAC;AAClF,OAAO,EAAC,KAAK,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAEjD,OAAO,EAAC,KAAK,cAAc,EAAC,MAAM,yBAAyB,CAAC;AA+J5D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,GACtC,MAAM,EAAE,CAAC,oBAAoB,EAC7B,UAAU,EAAE,CAAC,IAAI,EACjB,SAAS,EAAE,CAAC,WAAW,EACvB,aAAa,oBAAoB,EACjC,aAAa,KAAK,CAAC,UAAU,CAAC,EAC9B,gBAAgB,cAAc,KAC5B,IA2IF,CAAC"}
+{"version":3,"file":"typescript-extract-type-properties.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/typescript-extract-type-properties.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,MAAM,YAAY,CAAC;AAG5B,OAAO,KAAK,EAAC,oBAAoB,EAAkB,MAAM,wBAAwB,CAAC;AAClF,OAAO,EAAC,KAAK,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAEjD,OAAO,EAAC,KAAK,cAAc,EAAC,MAAM,yBAAyB,CAAC;AA+J5D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,GACtC,MAAM,EAAE,CAAC,oBAAoB,EAC7B,UAAU,EAAE,CAAC,IAAI,EACjB,SAAS,EAAE,CAAC,WAAW,EACvB,aAAa,oBAAoB,EACjC,aAAa,KAAK,CAAC,UAAU,CAAC,EAC9B,gBAAgB,cAAc,KAC5B,IA8IF,CAAC"}

package/dist/typescript-extract-type-properties.js

@@ -18,7 +18,7 @@ import ts from 'typescript';
 import {} from './diagnostics.js';
 import { parseComment, applyToDeclaration } from './tsdoc.js';
 import {} from './typescript-program.js';
-import { emitCallOrConstructSignature, filterIntersectionProperties, getNodeLocation, isExternalIntersectionBranch, populateCallableMember, resolveIntersectionTypeNode, } from './typescript-extract-shared.js';
+import { emitCallOrConstructSignature, filterExternalProperties, getNodeLocation, isExternalIntersectionBranch, populateCallableMember, resolveIntersectionTypeNode, } from './typescript-extract-shared.js';
 /**
  * Check whether a resolved type has properties worth extracting for documentation.
  *
@@ -160,11 +160,15 @@ const isReadonlyProperty = (prop, mappedReadonly) => {
 export const extractTypeAliasProperties = (node, nodeType, checker, declaration, diagnostics, isExternalFile) => {
     if (!hasExtractableProperties(nodeType))
         return;
-    // For intersection types, filter out properties from external sources (node_modules)
-    // and extract type names for the `intersects` field
-    const intersectionResult = filterIntersectionProperties(nodeType, node.type, checker, isExternalFile);
-    if (intersectionResult?.intersectionTypes.length) {
-        declaration.intersects = intersectionResult.intersectionTypes;
+    // Drop properties contributed by external types (node_modules / declaration
+    // files) and surface those external types in the `intersects` field. Applies
+    // to the property-bearing shapes that pass `hasExtractableProperties` above —
+    // intersections, bare references, indexed-access. Unions are gated out here
+    // (the Svelte prop path calls `filterExternalProperties` directly, so unions
+    // still surface `intersects` there, just not for plain type aliases).
+    const { properties: filteredProperties, externalTypes } = filterExternalProperties(nodeType, node.type, checker, isExternalFile);
+    if (externalTypes.length) {
+        declaration.intersects = externalTypes;
     }
     // Detect mapped-type-level readonly (e.g., Readonly<T>, { readonly [K in ...]: ... })
     let mappedReadonly = false;
@@ -177,9 +181,8 @@ export const extractTypeAliasProperties = (node, nodeType, checker, declaration,
             mappedReadonly = true;
         }
     }
-    // Extract named properties (filtered for intersections, full for other types)
-    const properties = intersectionResult?.properties ?? nodeType.getProperties();
-    for (const prop of properties) {
+    // Extract named properties (external contributions already filtered out)
+    for (const prop of filteredProperties) {
         // Skip internal TypeScript symbols
         if (prop.getName().startsWith('__@'))
             continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-docinfo",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "static analysis for TypeScript and Svelte",
   "glyph": "📜",
   "logo": "logo.svg",
@@ -42,27 +42,19 @@
     "es-module-lexer": "^2.0.0",
     "picomatch": "^4.0.4",
     "tinyglobby": "^0.2.15",
-    "typescript": "^5.9.3",
-    "zod": "^4.3.6"
+    "typescript": "^5.9.3"
   },
   "peerDependencies": {
     "svelte": "^5.0.0",
-    "svelte2tsx": "^0.7.30"
-  },
-  "peerDependenciesMeta": {
-    "svelte": {
-      "optional": true
-    },
-    "svelte2tsx": {
-      "optional": true
-    }
+    "svelte2tsx": "^0.7.30",
+    "zod": "^4"
   },
   "devDependencies": {
     "@fuzdev/blake3_wasm": "^0.1.1",
     "@fuzdev/fuz_code": "^0.45.1",
     "@fuzdev/fuz_css": "^0.61.1",
     "@fuzdev/fuz_ui": "^0.197.0",
-    "@fuzdev/fuz_util": "^0.63.0",
+    "@fuzdev/fuz_util": "^0.63.1",
     "@fuzdev/gro": "^0.200.0",
     "@ryanatkn/eslint-config": "^0.12.1",
     "@sveltejs/acorn-typescript": "^1.0.9",
@@ -87,7 +79,8 @@
     "typescript-eslint": "^8.48.1",
     "vite": "^7.3.1",
     "vitest": "^4.0.15",
-    "zimmerframe": "^1.1.4"
+    "zimmerframe": "^1.1.4",
+    "zod": "^4.3.6"
   },
   "prettier": {
     "plugins": [