component-parser

@auto-engineer/component-parser

Static analysis library that extracts prop metadata from React component files using the TypeScript compiler.

---

Purpose

Without @auto-engineer/component-parser, you would have to manually inspect React component source files to determine their prop names, types, default values, and descriptions -- or write your own ts-morph traversal logic to extract that information.

---

Installation

pnpm add @auto-engineer/component-parser

Quick Start

import { createProject, parseComponentFile } from '@auto-engineer/component-parser';

const project = createProject('./tsconfig.json');
const components = parseComponentFile(project, '/absolute/path/to/Button.tsx');

for (const component of components) {
  console.log(component.name);       // "Button"
  console.log(component.description); // JSDoc description, if present
  for (const prop of component.props) {
    console.log(prop.name, prop.type, prop.required, prop.defaultValue);
  }
}

---

How-to Guides

Parse multiple component files from a manifest

When you have a list of relative component paths (e.g., from a project manifest), use parseManifestComponents to parse them all at once with automatic deduplication:

import { createProject, parseManifestComponents } from '@auto-engineer/component-parser';

const project = createProject('./tsconfig.json');
const paths = ['./components/Button.tsx', './components/Card.tsx'];
const components = parseManifestComponents(project, paths, process.cwd());

Filter out HTML-native props

The parser automatically excludes standard HTML props (e.g., className, onClick, children) from results. It does this by resolving all props of React.ComponentProps<"div"> and subtracting them. Only custom props defined by the component author appear in the output.

If you need the raw HTML prop set for other purposes:

import { createProject, buildHtmlPropSet } from '@auto-engineer/component-parser';

const project = createProject('./tsconfig.json');
const htmlProps: Set<string> = buildHtmlPropSet(project);

Resolve props from a type directly

If you already have a ts-morph Type object and a set of HTML props to exclude, use resolveCustomProps:

import { resolveCustomProps } from '@auto-engineer/component-parser';

const props = resolveCustomProps(paramType, htmlProps, defaults);

---

API Reference

createProject(tsconfigPath: string): Project

Creates a ts-morph Project from a tsconfig.json path. All other functions require this project instance.

parseComponentFile(project: Project, filePath: string): ParsedComponent[]

Parses a single .tsx file and returns metadata for every exported React component (identified as functions with a capitalized name and at least one parameter).

parseManifestComponents(project: Project, componentPaths: string[], projectRoot: string): ParsedComponent[]

Parses multiple component files from a list of relative paths, resolving them against projectRoot. Deduplicates paths so each file is only parsed once.

buildHtmlPropSet(project: Project): Set<string>

Returns the full set of standard HTML div element prop names (from React.ComponentProps<"div">). Results are cached per project instance.

resolveCustomProps(type: Type, htmlProps: Set<string>, defaults: Map<string, string>): PropInfo[]

Walks a ts-morph Type and returns all properties that are not in htmlProps, enriched with default values and JSDoc descriptions.

extractDefaults(fn: FunctionDeclaration): Map<string, string>

Extracts default values from destructured parameters in a function declaration. Returns a map of parameter name to default value text.

Types

type ParsedComponent = {
  name: string;
  filePath: string;
  props: PropInfo[];
  description?: string;
};

type PropInfo = {
  name: string;
  type: string;
  required: boolean;
  defaultValue?: string;
  description?: string;
};

---

Architecture

The package is a pipeline of small, composable functions built on top of ts-morph:

createProject
  └─> parseComponentFile (or parseManifestComponents)
        ├─> buildHtmlPropSet   — resolves standard HTML props to exclude
        ├─> extractDefaults    — reads destructured default values from the function signature
        └─> resolveCustomProps — walks the props type, subtracts HTML props, attaches defaults and JSDoc

The only runtime dependency is ts-morph. The HTML prop set is cached per Project instance using a WeakMap to avoid repeated type resolution.