@agent-scope/manifest 1.17.1 → 1.17.2

package/README.md

@@ -0,0 +1,522 @@
+# @agent-scope/manifest
+
+TypeScript AST parser that generates a machine-readable React component registry (manifest) from source code.
+
+Walks TypeScript/TSX source files using [ts-morph](https://ts-morph.com/), extracts every React component (function, arrow, class), resolves props types, detects hooks, context dependencies, side effects, renders complexity, and builds a full bi-directional composition tree.
+
+---
+
+## Installation
+
+```bash
+npm install @agent-scope/manifest
+```
+
+---
+
+## What it does / when to use it
+
+| Need | Use |
+|------|-----|
+| Generate a JSON registry of all React components in a project | `generateManifest(config)` |
+| Know which components are composed by / compose which others | `manifest.tree` |
+| Determine if a component can be rendered via Satori (SVG) or needs a browser | `complexityClass` |
+| Find which React contexts a component depends on | `requiredContexts` |
+| Know which hooks a component calls | `detectedHooks` |
+| Detect fetch calls, timers, event listener subscriptions | `sideEffects` |
+| Understand all props (types, defaults, required status) | `props` in `ComponentDescriptor` |
+
+---
+
+## Manifest JSON schema
+
+### Top-level `Manifest`
+
+```typescript
+interface Manifest {
+  version: "0.1";          // schema version
+  generatedAt: string;     // ISO 8601 timestamp
+  components: Record<string, ComponentDescriptor>; // keyed by component name
+  tree: Record<string, TreeNode>;                  // keyed by component name
+}
+```
+
+### `ComponentDescriptor` — every field
+
+```typescript
+interface ComponentDescriptor {
+  // -----------------------------------------------------------------------
+  // Identity
+  // -----------------------------------------------------------------------
+  filePath: string;        // relative path from rootDir, e.g. "src/components/Button.tsx"
+  exportType: ExportType;  // "named" | "default" | "none"
+  displayName: string;     // displayName property if set, otherwise function/class name
+  loc: { start: number; end: number }; // 1-based line numbers in the source file
+
+  // -----------------------------------------------------------------------
+  // Props
+  // -----------------------------------------------------------------------
+  props: Record<string, PropDescriptor>;  // keyed by prop name
+
+  // -----------------------------------------------------------------------
+  // Composition
+  // -----------------------------------------------------------------------
+  composes: string[];    // component names rendered directly in this component's JSX
+  composedBy: string[];  // component names that render this component in their JSX
+
+  // -----------------------------------------------------------------------
+  // Wrappers
+  // -----------------------------------------------------------------------
+  forwardedRef: boolean;   // true if wrapped with React.forwardRef
+  memoized: boolean;       // true if wrapped with React.memo
+  hocWrappers: string[];   // HOC wrapper names (excluding memo/forwardRef)
+
+  // -----------------------------------------------------------------------
+  // Phase 6: rendering & runtime analysis
+  // -----------------------------------------------------------------------
+  complexityClass: ComplexityClass; // "simple" | "complex"
+  requiredContexts: string[];       // sorted context variable names (e.g. ["AuthCtx", "ThemeCtx"])
+  detectedHooks: string[];          // sorted hook names (e.g. ["useCallback", "useEffect", "useState"])
+  sideEffects: SideEffects;
+}
+```
+
+### `PropDescriptor`
+
+```typescript
+interface PropDescriptor {
+  type: PropKind;      // resolved TypeScript type category
+  values?: string[];   // for union types: expanded literal values, e.g. ["primary", "secondary"]
+  default?: string;    // default value as source-code string, e.g. "'primary'"
+  required: boolean;   // false if prop is optional (?) or has a default
+  rawType: string;     // raw TypeScript type string from source
+}
+
+type PropKind =
+  | "string" | "number" | "boolean"
+  | "union" | "object" | "array"
+  | "function" | "node" | "element"
+  | "any" | "unknown" | "never"
+  | "null" | "undefined" | "literal" | "other";
+```
+
+### `SideEffects`
+
+```typescript
+interface SideEffects {
+  fetches: string[];        // detected fetch callee names: "fetch", "axios", "useQuery", etc.
+  timers: boolean;          // setTimeout / setInterval / requestAnimationFrame detected
+  subscriptions: string[];  // subscription methods: "subscribe", "onSnapshot", "addListener", etc.
+  globalListeners: boolean; // window.addEventListener or document.addEventListener detected
+}
+```
+
+### `TreeNode`
+
+```typescript
+interface TreeNode {
+  children: string[]; // names of components this component renders directly
+  parents: string[];  // names of components that render this component directly
+}
+```
+
+---
+
+## How complexity classification works
+
+Each component receives a `complexityClass` of `"simple"` or `"complex"`. The classification drives rendering strategy:
+
+- **`simple`** — flexbox-only layout, standard box model, no animations. Safe to render via Satori (SVG-based renderer, fast).
+- **`complex`** — must render via a full browser pool. Slower but handles all CSS.
+
+### Static CSS analysis
+
+The parser scans all inline `style={{ ... }}` objects in JSX for these triggers:
+
+| Trigger | Example | Result |
+|---------|---------|--------|
+| CSS Grid properties | `gridTemplateColumns`, `gridArea`, `grid` | `complex` |
+| Absolute / fixed / sticky positioning | `position: "absolute"` | `complex` |
+| CSS animations | `animation`, `animationName`, `animationDuration` | `complex` |
+| CSS transitions | `transition` | `complex` |
+| CSS transforms | `transform`, `transformOrigin` | `complex` |
+| `clipPath`, `willChange`, `contain` | any of these keys | `complex` |
+| Styled-components / `css` template literals | `` styled.div`...` ``, `` css`...` `` | `complex` |
+| Opaque `className` references | `className={styles.root}` (identifier/call) | `complex` |
+
+Anything not matching the above stays `"simple"`.
+
+**Class components** always default to `"complex"` (safe fallback; lifecycle methods / state patterns are too complex to analyze statically).
+
+### Complexity propagation through the composition tree
+
+After all components are classified, complexity propagates **upward** through the tree:
+
+> A component is `simple` only if it **and every descendant** are also `simple`. If any child anywhere in the subtree is `complex`, all ancestors are also marked `complex`.
+
+Algorithm: bottom-up BFS starting from every initially-complex component, following `composedBy` links upward.
+
+**Example from the `basic-tree` fixture:**
+
+```
+App (simple own CSS)
+└── Layout (simple own CSS)
+    └── Sidebar (complex — uses `transition: "width 0.2s"`)
+        └── NavItem (simple leaf — no complex CSS)
+```
+
+After propagation:
+- `NavItem` → `simple` (leaf, no complex descendants)
+- `Sidebar` → `complex` (own CSS triggers it)
+- `Layout` → `complex` (propagated from Sidebar)
+- `App` → `complex` (propagated from Layout → Sidebar)
+
+Propagation unit-test examples (from `manifest.test.ts`):
+
+```typescript
+// Direct propagation
+// Input:  Parent(simple) ← Child(complex)
+// Result: Parent becomes complex
+propagateComplexity({ Parent: { complexityClass: "simple", composedBy: [] },
+                      Child:  { complexityClass: "complex", composedBy: ["Parent"] } });
+// Parent.complexityClass === "complex"
+
+// Transitive: A → B → C where C is complex → A and B both become complex
+// Diamond: A → B, A → C, both B and C → D(complex) → A, B, C all become complex
+```
+
+---
+
+## Context detection
+
+The parser detects which React contexts a component depends on via two strategies:
+
+### 1. Direct `useContext()` calls
+
+```tsx
+// Inside a component body:
+const theme = useContext(ThemeCtx);
+// → requiredContexts: ["ThemeCtx"]
+```
+
+### 2. Custom hook resolution
+
+```tsx
+// Component calls a custom hook:
+const theme = useTheme();
+
+// In hooks/useTheme.ts:
+export function useTheme() {
+  return useContext(ThemeCtx); // ← resolved transitively
+}
+// → requiredContexts: ["ThemeCtx"]
+```
+
+The parser follows relative imports (`"./hooks/useTheme"`) and scans the hook's source file for `useContext(...)` calls. Results are de-duplicated and sorted alphabetically.
+
+**`deep-context` fixture** — 5 custom hooks each wrapping a different context:
+
+```typescript
+// DeepConsumer calls: useTheme, useAuth, useLocale, useFeatureFlags, useUserPrefs
+manifest.components.DeepConsumer.requiredContexts;
+// ["AuthCtx", "FeatureFlagsCtx", "LocaleCtx", "ThemeCtx", "UserPrefsCtx"]
+
+manifest.components.DeepConsumer.detectedHooks;
+// ["useAuth", "useFeatureFlags", "useLocale", "useTheme", "useUserPrefs"]
+```
+
+---
+
+## Side-effect detection
+
+All `CallExpression` nodes in the component body are scanned recursively (including inside `useEffect`, `useCallback`, event handlers, etc.).
+
+| Category | Detected callees |
+|----------|-----------------|
+| `fetches` | `fetch`, `axios.*`, `useQuery`, `useMutation`, `useSWR`, `useInfiniteQuery`, `request` |
+| `timers` | `setTimeout`, `setInterval`, `requestAnimationFrame`, `clearTimeout`, `clearInterval`, `cancelAnimationFrame` |
+| `subscriptions` | `.subscribe()`, `.onSnapshot()`, `.on()`, `.listen()`, `.addListener()` |
+| `globalListeners` | `window.addEventListener`, `document.addEventListener`, `window.removeEventListener`, `document.removeEventListener`, bare `addEventListener` |
+
+`fetches` and `subscriptions` are de-duplicated sorted arrays. `timers` and `globalListeners` are booleans.
+
+**Example from the `hooks-showcase` fixture:**
+
+```typescript
+// UseEffectDemo uses setInterval inside useEffect
+manifest.components.UseEffectDemo.sideEffects.timers; // true
+
+// UseStateDemo has no side effects
+manifest.components.UseStateDemo.sideEffects;
+// { fetches: [], timers: false, subscriptions: [], globalListeners: false }
+```
+
+---
+
+## `generateManifest(config)`
+
+```typescript
+function generateManifest(config: ManifestConfig): Manifest
+```
+
+Generates the full component manifest by parsing all matching TypeScript/TSX files.
+
+### `ManifestConfig`
+
+```typescript
+interface ManifestConfig {
+  rootDir: string;          // absolute path to project/package root
+  include?: string[];       // glob patterns — default: ["src/**/*.tsx", "src/**/*.ts"]
+  exclude?: string[];       // glob patterns — default: ["**/node_modules/**", "**/*.test.*",
+                            //                            "**/*.spec.*", "**/dist/**", "**/*.d.ts"]
+  tsConfigFilePath?: string; // path to tsconfig.json — default: "<rootDir>/tsconfig.json"
+}
+```
+
+### Usage
+
+```typescript
+import { generateManifest } from "@agent-scope/manifest";
+
+const manifest = generateManifest({
+  rootDir: "/path/to/my-project",
+});
+
+// Access a specific component
+const button = manifest.components.Button;
+console.log(button.props.variant);
+// { type: "union", values: ["primary", "secondary", "ghost"], required: false, default: "'primary'", rawType: "Variant" }
+
+console.log(button.complexityClass);  // "simple" or "complex"
+console.log(button.detectedHooks);   // ["useCallback", "useState"]
+console.log(button.composedBy);      // ["Toolbar", "Form"]
+console.log(button.composes);        // ["Icon", "Spinner"]
+
+// Walk the composition tree
+const tree = manifest.tree.Button;
+// { children: ["Icon", "Spinner"], parents: ["Toolbar", "Form"] }
+```
+
+### Custom include/exclude
+
+```typescript
+const manifest = generateManifest({
+  rootDir: "/path/to/my-project",
+  include: ["src/components/**/*.tsx", "src/features/**/*.tsx"],
+  exclude: [
+    "**/node_modules/**",
+    "**/*.test.*",
+    "**/*.stories.*",
+    "**/dist/**",
+  ],
+  tsConfigFilePath: "/path/to/my-project/tsconfig.app.json",
+});
+```
+
+---
+
+## Component detection rules
+
+The parser discovers components from three declaration forms:
+
+### 1. Function declarations
+
+```tsx
+// Named PascalCase function that returns JSX
+export function Button({ label, onClick }: ButtonProps) {
+  return <button onClick={onClick}>{label}</button>;
+}
+```
+
+### 2. Arrow functions / variable declarations (including wrappers)
+
+```tsx
+// Arrow function
+export const Card = ({ title }: CardProps) => <div>{title}</div>;
+
+// React.memo wrapper
+export const Layout = React.memo(function Layout({ children }: LayoutProps) {
+  return <main>{children}</main>;
+});
+
+// React.forwardRef wrapper
+export const Input = React.forwardRef<HTMLInputElement, InputProps>(
+  ({ value }, ref) => <input ref={ref} value={value} />,
+);
+
+// Export-default memo: export default React.memo(Sidebar)
+export default React.memo(Sidebar);
+```
+
+### 3. Class components
+
+```tsx
+export class ErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  render() {
+    if (this.state.hasError) return <ErrorFallback />;
+    return this.props.children;
+  }
+}
+// Always gets complexityClass: "complex"
+// detectedHooks: [] (hooks not valid in class components)
+```
+
+---
+
+## Manifest query patterns
+
+```typescript
+// All simple components (Satori-renderable)
+const simpleComponents = Object.entries(manifest.components)
+  .filter(([, desc]) => desc.complexityClass === "simple")
+  .map(([name]) => name);
+
+// All components that use a specific context
+const themeConsumers = Object.entries(manifest.components)
+  .filter(([, desc]) => desc.requiredContexts.includes("ThemeCtx"))
+  .map(([name]) => name);
+
+// Leaf components (no children in the composition tree)
+const leaves = Object.entries(manifest.tree)
+  .filter(([, node]) => node.children.length === 0)
+  .map(([name]) => name);
+
+// Root components (no parents)
+const roots = Object.entries(manifest.tree)
+  .filter(([, node]) => node.parents.length === 0)
+  .map(([name]) => name);
+
+// Components with data fetching
+const fetchers = Object.entries(manifest.components)
+  .filter(([, desc]) => desc.sideEffects.fetches.length > 0)
+  .map(([name, desc]) => ({ name, fetches: desc.sideEffects.fetches }));
+
+// Components with default-exported named exports
+const defaultExports = Object.entries(manifest.components)
+  .filter(([, desc]) => desc.exportType === "default")
+  .map(([name]) => name);
+
+// All components with a specific prop
+const hasVariantProp = Object.entries(manifest.components)
+  .filter(([, desc]) => "variant" in desc.props)
+  .map(([name, desc]) => ({ name, variant: desc.props.variant }));
+```
+
+---
+
+## Example payloads
+
+### `manifest.components.Sidebar` (from `basic-tree` fixture)
+
+```json
+{
+  "filePath": "src/Sidebar.tsx",
+  "exportType": "default",
+  "displayName": "Sidebar",
+  "props": {
+    "title":     { "type": "string",  "required": true, "rawType": "string" },
+    "collapsed": { "type": "boolean", "required": true, "rawType": "boolean" },
+    "itemCount": { "type": "number",  "required": true, "rawType": "number" }
+  },
+  "composes":    ["NavItem"],
+  "composedBy":  ["Layout"],
+  "forwardedRef": false,
+  "memoized":    true,
+  "hocWrappers": [],
+  "loc": { "start": 10, "end": 40 },
+  "complexityClass": "complex",
+  "requiredContexts": [],
+  "detectedHooks": [],
+  "sideEffects": {
+    "fetches": [],
+    "timers": false,
+    "subscriptions": [],
+    "globalListeners": false
+  }
+}
+```
+
+Note: `complexityClass: "complex"` because Sidebar uses `transition: "width 0.2s"` in its inline style.
+
+### `manifest.components.DeepConsumer` (from `deep-context` fixture)
+
+```json
+{
+  "filePath": "src/DeepConsumer.tsx",
+  "exportType": "named",
+  "displayName": "DeepConsumer",
+  "props": {},
+  "composes": [],
+  "composedBy": ["App"],
+  "forwardedRef": false,
+  "memoized": false,
+  "hocWrappers": [],
+  "loc": { "start": 1, "end": 25 },
+  "complexityClass": "simple",
+  "requiredContexts": ["AuthCtx", "FeatureFlagsCtx", "LocaleCtx", "ThemeCtx", "UserPrefsCtx"],
+  "detectedHooks": ["useAuth", "useFeatureFlags", "useLocale", "useTheme", "useUserPrefs"],
+  "sideEffects": {
+    "fetches": [],
+    "timers": false,
+    "subscriptions": [],
+    "globalListeners": false
+  }
+}
+```
+
+### `manifest.tree` (from `basic-tree` fixture)
+
+```json
+{
+  "App":     { "children": ["Layout"],  "parents": [] },
+  "Layout":  { "children": ["Sidebar"], "parents": ["App"] },
+  "Sidebar": { "children": ["NavItem"], "parents": ["Layout"] },
+  "NavItem": { "children": [],          "parents": ["Sidebar"] }
+}
+```
+
+---
+
+## Internal architecture
+
+| Module | Responsibility |
+|--------|----------------|
+| `types.ts` | All TypeScript types (`ComponentDescriptor`, `PropDescriptor`, `Manifest`, `ManifestConfig`, etc.) |
+| `analysis.ts` | `analyzeComplexity`, `detectHooks`, `detectRequiredContexts`, `detectSideEffects`, `propagateComplexity` — all static analysis |
+| `parser.ts` | `generateManifest` — ts-morph project setup, source file iteration, per-file extraction (functions, arrow functions, class components), composition inverse linking, complexity propagation, tree building |
+| `index.ts` | Public re-exports |
+
+### Processing pipeline
+
+```
+ManifestConfig
+    │
+    ▼
+ts-morph Project (tsconfig-aware)
+    │
+    ▼
+Source file filtering (include/exclude globs)
+    │
+    ├─ for each SourceFile:
+    │   ├─ processSourceFile()
+    │   │   ├─ Function declarations → extract props, JSX compositions, wrappers
+    │   │   ├─ Variable declarations (arrow fns, memo, forwardRef)
+    │   │   └─ Class components
+    │   │
+    │   └─ per component:
+    │       ├─ analyzeComplexity()     — CSS feature scan
+    │       ├─ detectHooks()           — /^use[A-Z]/ pattern
+    │       ├─ detectRequiredContexts() — useContext() + hook resolution
+    │       └─ detectSideEffects()     — fetch/timer/subscription/global patterns
+    │
+    ├─ Build composedBy (inverse of composes)
+    ├─ propagateComplexity() — upward BFS from complex leaves
+    └─ Build tree (filtered to manifest-known components)
+```
+
+---
+
+## Used by
+
+- `@agent-scope/cli` — manifest commands (`scope manifest generate`, `scope manifest list`, `scope manifest show`), render commands (uses `complexityClass` to choose Satori vs browser pool), CI commands
+- `@agent-scope/render` — `satori.ts` and `matrix.ts` consume `complexityClass` and `ComponentDescriptor` for render strategy decisions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-scope/manifest",
-  "version": "1.17.1",
+  "version": "1.17.2",
   "description": "TypeScript AST parser that generates a machine-readable React component registry for Scope",
   "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",
@@ -29,7 +30,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@agent-scope/core": "1.17.1",
+    "@agent-scope/core": "1.17.2",
     "ts-morph": "^25.0.0"
   },
   "devDependencies": {