Extract props from flat-barrel .d.ts files (#24), v0.0.34

Bundlers like tsup/rollup often emit a single dist/index.d.ts with bare
`interface FooProps {…}` declarations (no `export`) and one export block
at the bottom. Strategy 3's types-hydration path already reads pkg.types,
but extractPropsFromDts silently failed on this layout.

- Make `export` optional in both the exact-name and generic *Props regexes
- When regex matches nothing, fall through to the TS AST parser instead of
  returning empty
- Add exactMatchOnly option so the types-hydration path doesn't fall back to
  "first *Props wins" — a flat barrel .d.ts has many *Props interfaces, and
  the generic fallback would give every component the same wrong props

Author: kurtstohrer

docs/component-discovery.md

@@ -173,12 +173,14 @@ When only a bundled dist file is available (no source), the scanner extracts com
 export{Zu as alertBanner, lu as base64Editor, Au as box, ...}
 ```
 
-This provides component names and import paths but no prop definitions. The scanner filters out non-component exports by skipping:
+This provides component names and import paths. The scanner filters out non-component exports by skipping:
 - `default`, `install`
 - Names ending in `Props` or `Emits`
 - `ALL_CAPS` constants
 - Utility function prefixes (`use*`, `create*`, `get*`, `set*`, `is*`, `has*`, `with*`, `to*`, `from*`)
 
+After extracting names, the scanner hydrates props from the package's declared types file (`pkg.exports["."].types` / `pkg.types` / `pkg.typings`). It looks up the exact `${ComponentName}Props` interface for each discovered component — a flat barrel `.d.ts` typically contains many `*Props` interfaces, so the generic "first-match" fallback is disabled in this path. Interfaces declared without `export` (bundler output from tsup/rollup) are handled by making the `export` keyword optional in both the regex and AST extractors.
+
 ## Props extraction
 
 Props are extracted differently depending on the source file type.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "annotask",
-  "version": "0.0.33",
+  "version": "0.0.34",
   "description": "Visual UI design tool for web apps. Make changes in the browser and generate structured reports that AI agents can apply to source code. Works with Vue, React, Svelte, SolidJS, and plain HTML via Vite or Webpack.",
   "license": "MIT",
   "type": "module",

src/server/component-scanner.ts

@@ -860,9 +860,11 @@ async function scanFromEntryPoint(name: string, pkgDir: string, sourceDir?: stri
         }
       } catch { /* no package.json */ }
       if (typesPath) {
+        // Exact-match only: a flat barrel .d.ts has many *Props interfaces — falling back
+        // to "first *Props wins" would give every component the same wrong props.
         for (const comp of nameOnly) {
           if (comp.props.length === 0) {
-            const dtsResult = await extractPropsFromDts(typesPath, comp.name)
+            const dtsResult = await extractPropsFromDts(typesPath, comp.name, { exactMatchOnly: true })
             comp.props = dtsResult.props
           }
         }
@@ -994,6 +996,7 @@ async function extractPropsFromPropDefs(filePath: string): Promise<ScannedProp[]
 async function extractPropsFromDtsViaTs(
   dtsPath: string,
   componentName: string,
+  options: { exactMatchOnly?: boolean } = {},
 ): Promise<{ props: ScannedProp[]; resolvedName: string | null }> {
   let ts: typeof import('typescript')
   try {
@@ -1017,7 +1020,7 @@ async function extractPropsFromDtsViaTs(
 
   let target = interfaces.get(`${componentName}Props`)
   let resolvedName: string | null = null
-  if (!target) {
+  if (!target && !options.exactMatchOnly) {
     for (const [name, iface] of interfaces) {
       if (!name.endsWith('Props')) continue
       if (name.includes('PassThrough') || name.includes('MethodOptions')) continue
@@ -1096,20 +1099,25 @@ async function extractPropsFromDtsViaTs(
   return { props, resolvedName }
 }
 
-async function extractPropsFromDts(dtsPath: string, componentName: string): Promise<{ props: ScannedProp[]; resolvedName: string | null }> {
+async function extractPropsFromDts(
+  dtsPath: string,
+  componentName: string,
+  options: { exactMatchOnly?: boolean } = {},
+): Promise<{ props: ScannedProp[]; resolvedName: string | null }> {
   let content: string
   try { content = await fsp.readFile(dtsPath, 'utf-8') } catch { return { props: [], resolvedName: null } }
 
-  // Try exact match first, then search for any *Props interface
+  // `export` is optional — bundler outputs (tsup/rollup) often emit `interface FooProps {…}`
+  // without `export`, relying on a single `export { … }` block at the bottom of the file.
   let propsInterfaceName = `${componentName}Props`
-  let interfaceRegex = new RegExp(`export\\s+(?:declare\\s+)?interface\\s+${propsInterfaceName}(?:<[^>]*>)?\\s*(?:extends\\s+[^{]*)?\\{`)
+  let interfaceRegex = new RegExp(`(?:export\\s+)?(?:declare\\s+)?interface\\s+${propsInterfaceName}(?:<[^>]*>)?\\s*(?:extends\\s+[^{]*)?\\{`)
   let match = interfaceRegex.exec(content)
 
   let resolvedName: string | null = null
-  if (!match) {
-    // Find any exported *Props interface (e.g., AutoCompleteProps when dir is "autocomplete")
-    // Handle generics: DataTableProps<T = any> extends ...
-    const genericRegex = /export\s+(?:declare\s+)?interface\s+(\w+Props)(?:<[^>]*>)?\s*(?:extends\s+[^{]*)?\{/g
+  if (!match && !options.exactMatchOnly) {
+    // Find any *Props interface (e.g., AutoCompleteProps when dir is "autocomplete").
+    // Skipped under exactMatchOnly — a flat barrel .d.ts has many *Props; picking the first is wrong.
+    const genericRegex = /(?:export\s+)?(?:declare\s+)?interface\s+(\w+Props)(?:<[^>]*>)?\s*(?:extends\s+[^{]*)?\{/g
     let candidate: RegExpExecArray | null
     while ((candidate = genericRegex.exec(content)) !== null) {
       const name = candidate[1]
@@ -1120,7 +1128,10 @@ async function extractPropsFromDts(dtsPath: string, componentName: string): Prom
       resolvedName = name.replace(/Props$/, '')
       break
     }
-    if (!match) return { props: [], resolvedName: null }
+  }
+  if (!match) {
+    // Regex found nothing — AST parser is the last resort (handles exotic declarations the regex misses).
+    return extractPropsFromDtsViaTs(dtsPath, componentName, options)
   }
 
   // Extract the interface body (track brace depth)
@@ -1179,7 +1190,7 @@ async function extractPropsFromDts(dtsPath: string, componentName: string): Prom
   // Fallback: if regex failed to extract anything (e.g. multi-line types, complex generics),
   // try the TypeScript AST parser. Keeps the fast regex path for the 95% case.
   if (props.length === 0) {
-    const astResult = await extractPropsFromDtsViaTs(dtsPath, componentName)
+    const astResult = await extractPropsFromDtsViaTs(dtsPath, componentName, options)
     if (astResult.props.length > 0) return astResult
   }
 

test/component-scanner/fixtures/flat-barrel.d.ts

@@ -0,0 +1,40 @@
+// Fixture: mimics the single flat `dist/index.d.ts` produced by bundlers like tsup/rollup
+// for libraries that publish only `dist/` (no per-component subdirs, no per-component .d.ts).
+// Interfaces are declared without `export` — the package has a separate export block elsewhere.
+// This is the shape that broke extraction for github.com/kurtstohrer/annotask#24.
+
+/// <reference types="react" />
+
+interface AccordionProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Body content of the accordion */
+    children: React.ReactNode;
+    /** Any additional classes to apply */
+    className?: string;
+    /** Should the accordion be expanded? */
+    expanded?: boolean;
+}
+
+interface AccordionGroupProps {
+    /** Grouped accordion items */
+    children: React.ReactNode;
+    className?: string;
+    /**
+     * Allow multiple accordions open at once.
+     * @defaultValue false
+     */
+    multiselect?: boolean;
+    onToggle?: (index: number) => void;
+    fullWidth?: boolean;
+}
+
+declare function Accordion({ children, className, expanded, ...props }: AccordionProps): JSX.Element;
+declare function AccordionGroup({ children, className, multiselect, onToggle, fullWidth, ...props }: AccordionGroupProps): JSX.Element;
+
+interface AdvancedTableProps<T = unknown> {
+    rows: T[];
+    columns: number;
+}
+
+declare function AdvancedTable<T>({ rows, columns }: AdvancedTableProps<T>): JSX.Element;
+
+export { Accordion, AccordionGroup, AdvancedTable };

test/component-scanner/scanner.test.ts

@@ -24,6 +24,29 @@ describe('extractPropsFromDts — regex path', () => {
   })
 })
 
+describe('extractPropsFromDts — flat barrel .d.ts (issue #24)', () => {
+  it('extracts props from bare `interface` (no `export`)', async () => {
+    const { props } = await S.extractPropsFromDts(fixture('flat-barrel.d.ts'), 'Accordion')
+    // Should resolve AccordionProps specifically, not pick the first *Props blindly.
+    expect(props.map(p => p.name).sort()).toEqual(['children', 'className', 'expanded'])
+    const expanded = props.find(p => p.name === 'expanded')
+    expect(expanded?.required).toBe(false)
+    expect(expanded?.description).toBe('Should the accordion be expanded?')
+  })
+
+  it('resolves per-component props in a file with many *Props interfaces', async () => {
+    const { props: groupProps } = await S.extractPropsFromDts(fixture('flat-barrel.d.ts'), 'AccordionGroup', { exactMatchOnly: true })
+    expect(groupProps.map(p => p.name).sort()).toEqual(['children', 'className', 'fullWidth', 'multiselect', 'onToggle'])
+    const multi = groupProps.find(p => p.name === 'multiselect')
+    expect(multi?.default).toBe('false')
+  })
+
+  it('exactMatchOnly returns empty when no matching interface exists', async () => {
+    const { props } = await S.extractPropsFromDts(fixture('flat-barrel.d.ts'), 'Nonexistent', { exactMatchOnly: true })
+    expect(props).toEqual([])
+  })
+})
+
 describe('extractPropsFromDtsViaTs — AST fallback', () => {
   it('handles multi-line prop types the regex extractor can\'t', async () => {
     const { props, resolvedName } = await S.extractPropsFromDtsViaTs(fixture('tricky-interface.d.ts'), 'DataTable')