@agent-scope/babel-plugin 1.17.1 → 1.17.3

package/README.md

@@ -0,0 +1,510 @@
+# `@agent-scope/babel-plugin`
+
+Build-time AST transform that injects two static properties into every React component definition: `__scopeSource` (file + line + column) and `__scopeProps` (TypeScript prop type metadata). No runtime overhead — all analysis happens at compile time.
+
+## Installation
+
+```bash
+npm install --save-dev @agent-scope/babel-plugin
+# or
+bun add -d @agent-scope/babel-plugin
+```
+
+---
+
+## What it does
+
+For each detected React component the plugin emits two assignment statements immediately after the component definition:
+
+```typescript
+// Input
+interface ButtonProps {
+  variant: 'primary' | 'secondary' | 'ghost';
+  size?: 'sm' | 'md' | 'lg';
+  disabled?: boolean;
+  children: React.ReactNode;
+  onClick?: (e: MouseEvent) => void;
+}
+
+function Button({ variant, size = 'md', disabled = false, children, onClick }: ButtonProps) {
+  return <button type="button" disabled={disabled}>{children}</button>;
+}
+
+// Output (after transform)
+function Button({ variant, size = 'md', disabled = false, children, onClick }) {
+  return /*#__PURE__*/React.createElement("button", { type: "button", disabled }, children);
+}
+Button.__scopeSource = { filePath: "src/Button.tsx", line: 9, column: 0 };
+Button.__scopeProps = {
+  variant:  { type: "union",      required: true,  values: ["primary", "secondary", "ghost"] },
+  size:     { type: "union",      required: false, values: ["sm", "md", "lg"], defaultValue: "md" },
+  disabled: { type: "boolean",    required: false, defaultValue: false },
+  children: { type: "ReactNode",  required: true },
+  onClick:  { type: "function",   required: false },
+};
+```
+
+---
+
+## Architecture
+
+```
+Program.enter
+  └── Pre-collect all TS interface / type alias declarations
+      into a WeakMap<Program, Map<typeName, TSTypeElement[]>>
+      (before @babel/preset-typescript strips them)
+
+FunctionDeclaration / VariableDeclaration / ExportDefaultDeclaration
+  └── component-detector.ts
+      ├── isComponentName()  → name starts with uppercase
+      └── bodyContainsJSX()  → body has a return statement returning JSX
+               │
+               ▼
+      source-injector.ts
+      └── buildScopeSourceStatement() → AST node for __scopeSource = {...}
+
+      prop-type-extractor.ts
+      └── resolveTypeReferenceName()  → look up interface/type in pre-collected map
+          extractPropsFromTypeMembers() → PropMap
+          extractDefaultValues()       → defaults from destructuring
+               │
+               ▼
+      props-injector.ts
+      └── buildScopePropsStatement() → AST node for __scopeProps = {...}
+```
+
+### Why `Program.enter` pre-collection?
+
+`@babel/preset-typescript` removes `TSInterfaceDeclaration` and `TSTypeAliasDeclaration` nodes during the same traversal pass. Because Babel traverses top-down, interface declarations (defined before the component) are visited and removed **before** the `FunctionDeclaration` visitor fires. The plugin collects all type declarations at `Program.enter` — before any child nodes are visited or removed — and stores them in a `WeakMap` keyed by the Program node.
+
+---
+
+## Component detection rules
+
+A function is treated as a React component if:
+
+1. **Name starts with an uppercase letter** — `isComponentName(name)` checks `/^[A-Z]/`
+2. **Body returns JSX** — `bodyContainsJSX()` checks for a `ReturnStatement` whose argument is a `JSXElement` or `JSXFragment` (including via ternary and logical expressions one level deep)
+
+Detected patterns:
+
+| Pattern | Example |
+|---|---|
+| Named function declaration | `function Button() { return <div/>; }` |
+| Arrow function variable | `const Card = () => <div/>;` |
+| Function expression variable | `const Card = function() { return <div/>; };` |
+| `React.memo()` wrapper | `const Memo = React.memo(() => <div/>);` |
+| `React.forwardRef()` wrapper | `const Ref = React.forwardRef((ref, p) => <input ref={ref}/>);` |
+| Named default export | `export default function Page() { return <main/>; }` |
+| Anonymous default export (arrow/fn) | `export default () => <div/>;` |
+
+Not detected (intentionally excluded):
+
+- Lowercase-named functions: `function formatDate(d)` → skipped
+- React hooks: `function useCounter()` → skipped (lowercase 'u')
+- Functions that don't return JSX: `function GetData() { return fetch(...); }` → skipped
+
+---
+
+## `__scopeSource` injection
+
+**Injected shape**
+
+```typescript
+ComponentName.__scopeSource = {
+  filePath: string;  // relative path (or opts.filePath override)
+  line: number;      // 1-based line number of the component declaration
+  column: number;    // 0-based column number
+};
+```
+
+**`filePath` resolution** (from `plugin.test.ts`)
+
+Pass `filePath` in plugin options to override Babel's automatic filename. This is critical in test environments where absolute paths vary by machine:
+
+```javascript
+// babel.config.js
+module.exports = {
+  plugins: [['@agent-scope/babel-plugin', { filePath: 'src/Button.tsx' }]],
+};
+```
+
+Without `filePath`, Babel's `state.filename` is used (often an absolute path).
+
+---
+
+## `__scopeProps` injection
+
+**Injected shape**
+
+```typescript
+ComponentName.__scopeProps = {
+  [propName: string]: {
+    type: PropTypeString;     // simplified type category
+    required: boolean;        // true if prop has no '?'
+    values?: string[];        // only for 'union' type — the literal string values
+    defaultValue?: unknown;   // extracted from destructuring default, if present
+  };
+};
+```
+
+**`PropTypeString` values**
+
+| Value | TypeScript types that map to it |
+|---|---|
+| `"string"` | `string` |
+| `"number"` | `number` |
+| `"boolean"` | `boolean` |
+| `"union"` | A union of all string/number literals: `'a' \| 'b' \| 'c'` |
+| `"function"` | `() => void`, `MouseEvent`, `ChangeEvent`, `React.*Handler` |
+| `"ReactNode"` | `React.ReactNode`, `ReactNode`, `ReactElement`, `React.ReactElement` |
+| `"object"` | `{ ... }` (TSTypeLiteral), mapped types |
+| `"array"` | `T[]`, tuples |
+| `"unknown"` | Intersection, conditional, generic references, `any`, `never`, etc. |
+
+**Default value extraction**
+
+Destructuring defaults are extracted from the first parameter:
+
+```typescript
+function Button({ size = 'md', disabled = false, count = 0 }: ButtonProps) { ... }
+// → size.defaultValue: "md", disabled.defaultValue: false, count.defaultValue: 0
+```
+
+Supported literal default types: `string`, `number`, `boolean`, `null`, and negative numbers (`-1`).
+
+---
+
+## Configuration
+
+### `babel.config.js`
+
+```javascript
+module.exports = {
+  plugins: ['@agent-scope/babel-plugin'],
+};
+```
+
+### `babel.config.js` with `filePath` override
+
+```javascript
+module.exports = {
+  plugins: [
+    ['@agent-scope/babel-plugin', { filePath: 'src/MyComponent.tsx' }],
+  ],
+};
+```
+
+### Vite (`vite.config.ts`)
+
+```typescript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [
+    react({
+      babel: {
+        plugins: ['@agent-scope/babel-plugin'],
+      },
+    }),
+  ],
+});
+```
+
+### Next.js (`next.config.js`)
+
+```javascript
+module.exports = {
+  experimental: { forceSwcTransforms: false },
+  babel: {
+    plugins: ['@agent-scope/babel-plugin'],
+  },
+};
+```
+
+---
+
+## Transform examples (from test fixtures)
+
+### Simple function component (`simple-component.tsx`)
+
+**Input**
+
+```tsx
+function Button({ label }: { label: string }) {
+  return <button type="button">{label}</button>;
+}
+export { Button };
+```
+
+**Output** (TypeScript stripped, JSX transformed)
+
+```javascript
+function Button({ label }) {
+  return /*#__PURE__*/React.createElement("button", { type: "button" }, label);
+}
+Button.__scopeSource = { filePath: "src/simple-component.tsx", line: 1, column: 0 };
+Button.__scopeProps = {
+  label: { type: "string", required: true },
+};
+```
+
+---
+
+### Arrow function component (`arrow-component.tsx`)
+
+**Input**
+
+```tsx
+const Card = ({ title }: { title: string }) => <div className="card">{title}</div>;
+export { Card };
+```
+
+**Output**
+
+```javascript
+const Card = ({ title }) => /*#__PURE__*/React.createElement("div", { className: "card" }, title);
+Card.__scopeSource = { filePath: "src/arrow-component.tsx", line: 1, column: 0 };
+Card.__scopeProps = {
+  title: { type: "string", required: true },
+};
+```
+
+---
+
+### `React.memo` wrapper (`memo-component.tsx`)
+
+**Input**
+
+```tsx
+import React from "react";
+const MemoButton = React.memo(({ label }: { label: string }) => (
+  <button type="button">{label}</button>
+));
+export { MemoButton };
+```
+
+**Output**
+
+```javascript
+const MemoButton = React.memo(({ label }) =>
+  /*#__PURE__*/React.createElement("button", { type: "button" }, label)
+);
+MemoButton.__scopeSource = { filePath: "src/memo-component.tsx", line: 3, column: 0 };
+MemoButton.__scopeProps = { label: { type: "string", required: true } };
+```
+
+---
+
+### `React.forwardRef` wrapper (`forwardref-component.tsx`)
+
+**Input**
+
+```tsx
+import React from "react";
+const FancyInput = React.forwardRef<HTMLInputElement, { placeholder: string }>(
+  ({ placeholder }, ref) => <input ref={ref} placeholder={placeholder} />,
+);
+export { FancyInput };
+```
+
+**Output**
+
+```javascript
+const FancyInput = React.forwardRef(({ placeholder }, ref) =>
+  /*#__PURE__*/React.createElement("input", { ref, placeholder })
+);
+FancyInput.__scopeSource = { filePath: "src/forwardref-component.tsx", line: 3, column: 0 };
+```
+
+---
+
+### Named default export (`default-export.tsx`)
+
+**Input**
+
+```tsx
+export default function HomePage() {
+  return <main>Hello World</main>;
+}
+```
+
+**Output**
+
+```javascript
+export default function HomePage() {
+  return /*#__PURE__*/React.createElement("main", null, "Hello World");
+}
+HomePage.__scopeSource = { filePath: "src/default-export.tsx", line: 1, column: 0 };
+// __scopeSource injected exactly once
+```
+
+---
+
+### Full typed component (`typed-function-component.tsx`)
+
+**Input**
+
+```tsx
+interface ButtonProps {
+  variant: "primary" | "secondary" | "ghost";
+  size?: "sm" | "md" | "lg";
+  disabled?: boolean;
+  children: React.ReactNode;
+  onClick?: (e: MouseEvent) => void;
+}
+
+function Button({
+  variant: _variant,
+  size: _size = "md",
+  disabled = false,
+  children,
+  onClick: _onClick,
+}: ButtonProps) {
+  return <button type="button" disabled={disabled}>{children}</button>;
+}
+export { Button };
+```
+
+**Output** (`__scopeProps` excerpt)
+
+```javascript
+Button.__scopeSource = { filePath: "src/button.tsx", line: 9, column: 0 };
+Button.__scopeProps = {
+  variant:  { type: "union",     required: true,  values: ["primary", "secondary", "ghost"] },
+  size:     { type: "union",     required: false, values: ["sm", "md", "lg"], defaultValue: "md" },
+  disabled: { type: "boolean",   required: false, defaultValue: false },
+  children: { type: "ReactNode", required: true },
+  onClick:  { type: "function",  required: false },
+};
+```
+
+---
+
+### `React.FC<Props>` arrow component (`typed-arrow-fc.tsx`)
+
+**Input**
+
+```tsx
+import type React from "react";
+
+interface CardProps {
+  title: string;
+  count: number;
+  active?: boolean;
+}
+
+const Card: React.FC<CardProps> = ({ title, count = 0, active = false }) => (
+  <div className={active ? "active" : ""}>{title}: {count}</div>
+);
+export { Card };
+```
+
+**Output** (`__scopeProps` excerpt)
+
+```javascript
+Card.__scopeSource = { filePath: "src/card.tsx", line: 9, column: 0 };
+Card.__scopeProps = {
+  title:  { type: "string",  required: true },
+  count:  { type: "number",  required: true, defaultValue: 0 },
+  active: { type: "boolean", required: false, defaultValue: false },
+};
+```
+
+---
+
+### No-props component (`no-props-component.tsx`)
+
+**Input**
+
+```tsx
+function Header() {
+  return <header>Hello World</header>;
+}
+export { Header };
+```
+
+**Output**
+
+```javascript
+function Header() {
+  return /*#__PURE__*/React.createElement("header", null, "Hello World");
+}
+Header.__scopeSource = { filePath: "src/header.tsx", line: 1, column: 0 };
+// __scopeProps is NOT injected — no typed props
+```
+
+---
+
+### Union type extraction (from `prop-extraction.test.ts`)
+
+```tsx
+type StatusProps = { status: 'active' | 'inactive' | 'pending' };
+function StatusBadge({ status }: StatusProps) { return <span>{status}</span>; }
+```
+
+**Output**
+
+```javascript
+StatusBadge.__scopeProps = {
+  status: { type: "union", required: true, values: ["active", "inactive", "pending"] },
+};
+```
+
+---
+
+### Inline type annotation (from `prop-extraction.test.ts`)
+
+```tsx
+function Avatar({ src, alt }: { src: string; alt?: string }) {
+  return <img src={src} alt={alt} />;
+}
+```
+
+**Output**
+
+```javascript
+Avatar.__scopeProps = {
+  src: { type: "string", required: true },
+  alt: { type: "string", required: false },
+};
+```
+
+---
+
+### Complex types fall back to `"unknown"` (from `prop-extraction.test.ts`)
+
+```tsx
+interface ComplexProps { combo: A & B; }         // → type: "unknown" (intersection)
+interface GenericProps { data: Array<string>; }   // → type: "unknown" (generic TSTypeReference)
+```
+
+---
+
+## Plugin options
+
+```typescript
+interface PluginOptions {
+  /** Override the file path injected into __scopeSource.
+   *  Defaults to Babel's `state.filename`.
+   *  Pass this explicitly in tests to avoid absolute-path mismatches. */
+  filePath?: string;
+}
+```
+
+**Test setup best practice** (from KB: Babel Plugin Test Assertions): Always pass `filePath` as a plugin option in tests and assert against relative paths. Relying on Babel's automatic filename resolution produces absolute paths that break across machines:
+
+```javascript
+transformSync(code, {
+  plugins: [['@agent-scope/babel-plugin', { filePath: 'src/Button.tsx' }]],
+});
+expect(output).toContain('filePath: "src/Button.tsx"'); // ✓ portable
+```
+
+---
+
+## Used by
+
+- `@agent-scope/runtime` — reads `Component.__scopeSource` and `Component.__scopeProps` at runtime to enrich `PageReport` nodes with source location and prop type metadata
+- `@agent-scope/cli` — uses prop type metadata to drive `scope render` matrix axis generation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-scope/babel-plugin",
-  "version": "1.17.1",
+  "version": "1.17.3",
   "description": "Babel plugin for automatic Scope instrumentation via AST transforms",
   "license": "MIT",
   "type": "module",
@@ -20,7 +20,8 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "scripts": {
     "build": "tsup",
@@ -30,7 +31,7 @@
   },
   "dependencies": {
     "@babel/core": "^7.29.0",
-    "@agent-scope/core": "1.17.1"
+    "@agent-scope/core": "1.17.3"
   },
   "devDependencies": {
     "@babel/preset-react": "^7.28.5",