@dcoder-x/plugin-shared 0.1.6 → 0.1.7

package/README.md

@@ -0,0 +1,300 @@
+# @dcoder-x/plugin-shared
+
+Internal shared library for the Clippy build plugin ecosystem. Contains the AST extractors, selector generators, flow inferrers, and package builders used by `@dcoder-x/next` and `@dcoder-x/vite`.
+
+**You do not need to install this package directly.** It is a transitive dependency of the adapter packages and is installed automatically.
+
+---
+
+## If you are building a custom adapter
+
+If you are integrating Clippy with a bundler other than Next.js or Vite, this package provides the full pipeline as composable classes.
+
+```bash
+npm install @dcoder-x/plugin-shared
+```
+
+### Pipeline overview
+
+```
+Source files
+    │
+    ▼
+ClippyIdInjector.injectClippyIds(source, filePath, routePath?)
+    │ Injects data-clippy-id and data-clippy-component into compiled HTML elements
+    ▼
+RouteExtractor.extract()
+    │ Discovers all routes from filesystem conventions or React Router AST
+    ▼
+ComponentExtractor.extract()        ComponentExtractor.extractComponents()
+    │ Finds all interactive elements   │ Extracts state, handlers, interaction graphs
+    ▼                                  ▼
+SelectorGenerator.generate(elements, injectedMap)
+    │ Matches injected IDs to elements, ranks selector candidates
+    ▼
+FlowInferrer.infer()
+    │ Builds navigation edge graph, detects flow chains, generates intent patterns
+    ▼
+PackageBuilder.buildArtifacts()
+    │ Assembles clippy-policy.json and clippy-selectors.json
+    ▼
+PackageWriter.writeArtifacts()   /   Uploader.upload()
+    Writes JSON files locally         Uploads to Clippy backend
+```
+
+### Minimal custom adapter
+
+```ts
+import { injectClippyIds, inferRouteFromFilePath } from '@dcoder-x/plugin-shared'
+import { RouteExtractor } from '@dcoder-x/plugin-shared/extractors/RouteExtractor'
+import { ComponentExtractor } from '@dcoder-x/plugin-shared/extractors/ComponentExtractor'
+import { SelectorGenerator } from '@dcoder-x/plugin-shared/extractors/SelectorGenerator'
+import { FlowInferrer } from '@dcoder-x/plugin-shared/extractors/FlowInferrer'
+import { PackageBuilder } from '@dcoder-x/plugin-shared/upload/PackageBuilder'
+import { PackageWriter } from '@dcoder-x/plugin-shared/upload/PackageWriter'
+import type { ClippyPluginOptions } from '@dcoder-x/plugin-shared'
+
+async function runClippyPipeline(
+  projectRoot: string,
+  buildId: string,
+  moduleGraph: Map<string, { id: string; importedIds: readonly string[] }>,
+  injectedMap: Record<string, Array<{ clippyId: string; component: string; tag: string; line: number; label?: string }>>,
+  options: ClippyPluginOptions
+) {
+  const routes = await new RouteExtractor(projectRoot).extract()
+
+  const extractor = new ComponentExtractor(
+    { type: 'rollup', moduleGraph },
+    routes
+  )
+
+  const elements = await extractor.extract()
+  const components = await extractor.extractComponents()
+  const selectors = new SelectorGenerator().generate(elements, injectedMap)
+  const flows = new FlowInferrer(routes, elements, components).infer()
+
+  const artifacts = new PackageBuilder().buildArtifacts({
+    projectRoot,
+    buildId,
+    bundler: 'vite',   // or 'webpack'
+    routes,
+    selectors,
+    flows,
+    components,
+  })
+
+  if (options.localOutputDir) {
+    new PackageWriter().writeArtifacts(options.localOutputDir, artifacts)
+  }
+}
+```
+
+### Transform hook (injection)
+
+Call `injectClippyIds` in your bundler's transform hook for each `.tsx` / `.jsx` / `.ts` / `.js` file:
+
+```ts
+// In your bundler's transform/loader:
+const routePath = inferRouteFromFilePath(filePath) ?? undefined
+const result = injectClippyIds(sourceCode, filePath, routePath)
+
+// result.source       — transformed source with data-clippy-id attributes
+// result.injected     — metadata array for building the injectedMap
+// result.injectedCount — number of attributes injected (0 = file had no HTML elements)
+
+if (result.injectedCount > 0) {
+  injectedMap[filePath] = result.injected
+}
+```
+
+`inferRouteFromFilePath` detects App Router (`app/**/page.tsx`) and Pages Router (`pages/**/*.tsx`) conventions and returns the route path string (e.g., `/dashboard/forms`). Returns `null` for non-route files.
+
+---
+
+## Exported API
+
+### Injection
+
+| Export | Description |
+|---|---|
+| `injectClippyIds(source, filePath, routePath?)` | Injects `data-clippy-id` and `data-clippy-component` into all native HTML elements in a JSX/TSX source string |
+| `inferRouteFromFilePath(filePath)` | Derives route path from an absolute file path for App Router / Pages Router files |
+| `deriveClippyId(component, tag, line, routePath?, label?)` | Computes a stable `data-clippy-id` value |
+| `deriveRouteComponentName(routePath)` | Converts `/admin/transactions` → `AdminTransactions` |
+| `GENERIC_COMPONENT_NAMES` | Set of component names treated as generic (Page, Layout, App, etc.) |
+
+### Extractors
+
+| Export | Description |
+|---|---|
+| `RouteExtractor` | Filesystem + AST route discovery |
+| `ComponentExtractor` | Module-graph traversal, element extraction, component analysis |
+| `SelectorGenerator` | Ranks and matches selector candidates for each element |
+| `FlowInferrer` | Navigation edge graph construction and flow chain detection |
+| `InteractionGraphExtractor` | AST extraction of state → conditional render chains |
+| `ComponentContextResolver` | useState / useReducer / event handler extraction |
+
+### Output
+
+| Export | Description |
+|---|---|
+| `PackageBuilder` | Assembles `PolicyArtifacts` from pipeline output |
+| `PackageWriter` | Writes `clippy-policy.json` and `clippy-selectors.json` to disk |
+| `Uploader` | HTTP upload client for the Clippy backend |
+
+### Types
+
+All public types are exported from the package root:
+
+```ts
+import type {
+  ClippyPluginOptions,
+  PolicyArtifacts,
+  PolicyDocument,
+  PolicyComponent,
+  PolicyFlow,
+  PolicySelectorEntry,
+  SelectorManifest,
+  SelectorManifestEntry,
+  DiscoveredRoute,
+  DiscoveredElement,
+  ElementWithSelectors,
+  SelectorCandidate,
+  ComponentInteraction,
+  TriggerSpec,
+  EffectSpec,
+  InferredFlow,
+  FlowEdge,
+  UploadResult,
+} from '@dcoder-x/plugin-shared'
+```
+
+---
+
+## Output artifact formats
+
+### `clippy-policy.json` — full policy document
+
+```ts
+interface PolicyDocument {
+  version: string
+  buildId: string
+  generatedAt: string
+  bundler: 'webpack' | 'vite'
+  routes: DiscoveredRoute[]
+  selectors: PolicySelectorEntry[]
+  components: PolicyComponent[]  // only components with state or interactions
+  flows: PolicyFlow[]
+}
+```
+
+### `clippy-selectors.json` — deduplicated selector manifest
+
+```ts
+interface SelectorManifest {
+  version: string
+  buildId: string
+  generatedAt: string
+  selectors: SelectorManifestEntry[]
+}
+
+interface SelectorManifestEntry {
+  id: string           // data-clippy-id value
+  selector: string     // CSS selector string
+  component: string    // enclosing component name
+  tag: string          // lowercase HTML tag
+  label?: string       // human-readable label (may be null)
+  routes: string[]     // all routes where this element appears
+}
+```
+
+### `DiscoveredRoute`
+
+```ts
+interface DiscoveredRoute {
+  path: string          // e.g. "/dashboard/forms/[id]"
+  filePath: string      // relative to project root, e.g. "app/dashboard/forms/[id]/page.tsx"
+  isDynamic: boolean
+  params: string[]      // e.g. ["id"]
+  layout: string | null // relative path to nearest layout file
+  routerType: 'app' | 'pages' | 'react-router' | 'tanstack'
+  semantic: string      // space-separated route segments, reversed
+}
+```
+
+### `PolicyComponent`
+
+Only components with at least one `stateVariable` or `interaction` are included.
+
+```ts
+interface PolicyComponent {
+  name: string
+  filePath: string   // relative to project root
+  route: string
+  stateVariables: Array<{
+    name: string
+    setter?: string
+    initialValue?: string
+  }>
+  interactions: ComponentInteraction[]
+}
+
+interface ComponentInteraction {
+  trigger: {
+    event: string      // e.g. "onClick"
+    element: string    // JSX tag that carries the handler
+    setsState?: string // state variable the handler mutates
+  }
+  effect: {
+    type: 'conditionalRender' | 'asyncEffect' | 'contextDependency'
+    rendersWhenTrue?: string   // component name that appears
+    rendersWhenFalse?: string  // component name that disappears
+    waitStrategy: 'elementAppears' | 'domSettle' | 'none'
+    selector?: string          // [data-clippy-component='...'] selector to wait for
+    settleMs?: number          // milliseconds to wait for DOM to settle
+  }
+}
+```
+
+### `PolicyFlow`
+
+```ts
+interface PolicyFlow {
+  flowId: string
+  page: string               // starting route
+  intentPatterns: string[]   // user phrases that match this flow
+  steps: PolicyFlowStep[]
+}
+
+interface PolicyFlowStep {
+  step: number
+  action: 'navigate' | 'transition' | 'interact'
+  target: string             // CSS selector for the element to act on
+}
+```
+
+---
+
+## Selector ID format
+
+```
+ComponentName[-LabelText]-tag-lineNumber
+
+Examples:
+  DashboardForms-CreateForm-button-138
+  AdminTransactions-Approve-button-172
+  LoginPage-form-115          (no label — form labels use submit button text only)
+  Input-input-7               (shared component, no label from its own file)
+```
+
+- **ComponentName** — enclosing React component, or route-derived name when generic (e.g., `AdminTransactions` instead of `Page`)
+- **LabelText** — `aria-label` > visible text (TitleCase, max 2 words) > `placeholder`. Omitted for forms (submit button text is used instead of the full field list)
+- **tag** — lowercase HTML tag
+- **lineNumber** — source file line, stable tiebreaker
+
+---
+
+## Related packages
+
+- [`@dcoder-x/next`](https://www.npmjs.com/package/@dcoder-x/next) — Next.js adapter
+- [`@dcoder-x/vite`](https://www.npmjs.com/package/@dcoder-x/vite) — Vite adapter

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dcoder-x/plugin-shared",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "private": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",