@dcoder-x/plugin-shared 0.1.3 → 0.1.5

package/dist/injection/IdStrategy.d.ts

@@ -0,0 +1,36 @@
+import type { NodePath } from '@babel/traverse';
+export declare function deriveComponentName(filePath: string, fallback?: string): string;
+/**
+ * Generic Next.js component names that should be replaced by a route-derived name.
+ */
+export declare const GENERIC_COMPONENT_NAMES: Set<string>;
+/**
+ * Infer the route path from an absolute file path.
+ * Handles both App Router (app/…/page.tsx) and Pages Router (pages/….tsx).
+ * Returns null if the file is not a route file.
+ */
+export declare function inferRouteFromFilePath(filePath: string): string | null;
+/**
+ * Convert a route path to a PascalCase component name.
+ * /admin/transactions      → AdminTransactions
+ * /dashboard/forms/[id]   → DashboardForms
+ * /auth/forgot-password   → AuthForgotPassword
+ */
+export declare function deriveRouteComponentName(routePath: string): string;
+/**
+ * Compute a short route hash for use in stable IDs.
+ * Takes a route path (e.g., "/admin/transactions") and produces a 4-char hash.
+ */
+export declare function hashRoutePath(routePath: string): string;
+/**
+ * Sanitize a label string for embedding in a CSS/HTML attribute ID.
+ * TitleCase, max 2 words, alphanumeric only, minimum 2 chars.
+ * Returns null if no usable text can be extracted.
+ */
+export declare function sanitizeLabelForId(label: string): string | null;
+export declare function deriveClippyId(componentName: string, tagName: string, lineNumber: number, routePath?: string, labelText?: string): string;
+/**
+ * Walk the AST upward to find the enclosing React component name.
+ * Exported here so both the injector and the extractor use the same logic.
+ */
+export declare function findEnclosingComponentName(path: NodePath<any>): string | null;

package/dist/injection/IdStrategy.js

@@ -0,0 +1,148 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GENERIC_COMPONENT_NAMES = void 0;
+exports.deriveComponentName = deriveComponentName;
+exports.inferRouteFromFilePath = inferRouteFromFilePath;
+exports.deriveRouteComponentName = deriveRouteComponentName;
+exports.hashRoutePath = hashRoutePath;
+exports.sanitizeLabelForId = sanitizeLabelForId;
+exports.deriveClippyId = deriveClippyId;
+exports.findEnclosingComponentName = findEnclosingComponentName;
+const path_1 = __importDefault(require("path"));
+function deriveComponentName(filePath, fallback) {
+    if (fallback)
+        return fallback;
+    const base = path_1.default.basename(filePath, path_1.default.extname(filePath));
+    if (!base || base === 'index') {
+        return 'UnknownComponent';
+    }
+    return normalizeComponentName(base);
+}
+/**
+ * Generic Next.js component names that should be replaced by a route-derived name.
+ */
+exports.GENERIC_COMPONENT_NAMES = new Set([
+    'Page', 'Layout', 'App', 'Index', 'Component', 'Default',
+    'Loading', 'Error', 'NotFound', 'Template', 'Root',
+]);
+/**
+ * Infer the route path from an absolute file path.
+ * Handles both App Router (app/…/page.tsx) and Pages Router (pages/….tsx).
+ * Returns null if the file is not a route file.
+ */
+function inferRouteFromFilePath(filePath) {
+    const normalized = filePath.replace(/\\/g, '/');
+    const appMatch = normalized.match(/\/app(\/.*?)\/page\.[jt]sx?$/);
+    if (appMatch) {
+        const segment = appMatch[1]
+            .replace(/\/\([^)]+\)/g, ''); // strip route groups like (auth)
+        return segment || '/';
+    }
+    const pagesMatch = normalized.match(/\/pages(\/.*?)\.[jt]sx?$/);
+    if (pagesMatch) {
+        const segment = pagesMatch[1].replace(/\/index$/, '') || '/';
+        return segment;
+    }
+    return null;
+}
+/**
+ * Convert a route path to a PascalCase component name.
+ * /admin/transactions      → AdminTransactions
+ * /dashboard/forms/[id]   → DashboardForms
+ * /auth/forgot-password   → AuthForgotPassword
+ */
+function deriveRouteComponentName(routePath) {
+    const name = routePath
+        .split('/')
+        .filter(Boolean)
+        .filter(s => !s.startsWith('[') && !s.startsWith(':') && !s.startsWith('$'))
+        .map(s => s
+        .split('-')
+        .map(w => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(''))
+        .join('');
+    return name || 'Page';
+}
+/**
+ * Compute a short route hash for use in stable IDs.
+ * Takes a route path (e.g., "/admin/transactions") and produces a 4-char hash.
+ */
+function hashRoutePath(routePath) {
+    let hash = 0;
+    for (let i = 0; i < routePath.length; i++) {
+        hash = (hash << 5) - hash + routePath.charCodeAt(i);
+        hash = hash & hash;
+    }
+    return Math.abs(hash).toString(36).slice(0, 4);
+}
+/**
+ * Sanitize a label string for embedding in a CSS/HTML attribute ID.
+ * TitleCase, max 2 words, alphanumeric only, minimum 2 chars.
+ * Returns null if no usable text can be extracted.
+ */
+function sanitizeLabelForId(label) {
+    const words = label
+        .replace(/[^A-Za-z0-9\s]/g, ' ')
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean)
+        .slice(0, 2)
+        .map(w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase());
+    const result = words.join('');
+    return result.length >= 2 ? result : null;
+}
+function deriveClippyId(componentName, tagName, lineNumber, routePath, labelText) {
+    const sanitizedComponent = normalizeComponentName(componentName);
+    const normalizedTag = tagName.replace(/[^a-z0-9]/gi, '') || 'element';
+    const sanitizedLabel = labelText ? sanitizeLabelForId(labelText) : null;
+    const stableLine = lineNumber > 0 ? lineNumber : 0;
+    const parts = [sanitizedComponent];
+    if (sanitizedLabel)
+        parts.push(sanitizedLabel);
+    parts.push(normalizedTag);
+    parts.push(String(stableLine));
+    return parts.join('-');
+}
+/**
+ * Walk the AST upward to find the enclosing React component name.
+ * Exported here so both the injector and the extractor use the same logic.
+ */
+function findEnclosingComponentName(path) {
+    let current = path;
+    while (current) {
+        if (current.isFunctionDeclaration() && current.node.id?.name) {
+            return current.node.id.name;
+        }
+        if (current.isClassDeclaration() && current.node.id?.name) {
+            return current.node.id.name;
+        }
+        if (current.isVariableDeclarator() && current.node.id?.type === 'Identifier') {
+            return current.node.id.name;
+        }
+        if ((current.isArrowFunctionExpression() || current.isFunctionExpression()) &&
+            current.parentPath?.isVariableDeclarator() &&
+            current.parentPath.node.id?.type === 'Identifier') {
+            return current.parentPath.node.id.name;
+        }
+        current = current.parentPath;
+    }
+    return null;
+}
+function normalizeComponentName(value) {
+    const sanitized = value
+        .replace(/[^A-Za-z0-9]+/g, ' ')
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((segment) => segment
+        .replace(/[^A-Za-z0-9]/g, '')
+        .replace(/^[^A-Za-z]+/, '')
+        .replace(/([a-z])([A-Z])/g, '$1$2'))
+        .filter(Boolean)
+        .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+        .join('');
+    return sanitized || 'Component';
+}

package/dist/types.d.ts

@@ -4,6 +4,11 @@ export interface ClippyPluginOptions {
     skipUpload?: boolean;
     productionOnly?: boolean;
     localOutputDir?: string;
+    artifactUploadMode?: 'single' | 'split';
+    legacyPackageMode?: boolean;
+    uploadAdapter?: {
+        uploadArtifacts?: (artifacts: PolicyArtifacts) => Promise<UploadResult>;
+    };
 }
 export type ModuleGraphSource = {
     type: 'webpack';
@@ -33,9 +38,15 @@ export interface DiscoveredElement {
     nearbyText: string[];
     semanticRole: string;
     interactions: string[];
+    label?: string;
+    component?: string;
+    isNavigationLink?: boolean;
+    loc?: {
+        line: number;
+    };
 }
 export interface SelectorCandidate {
-    type: 'testid' | 'aria' | 'id' | 'semantic' | 'text' | 'structural';
+    type: 'clippy_id' | 'testid' | 'aria' | 'id' | 'semantic' | 'text' | 'structural';
     value: string;
     confidence: number;
 }
@@ -51,8 +62,104 @@ export interface FlowEdge {
 export interface InferredFlow {
     id: string;
     name: string;
+    page: string;
     steps: string[];
     edges: FlowEdge[];
+    intentPatterns?: string[];
+}
+export interface ArtifactMetadata {
+    version: string;
+    buildId: string;
+    generatedAt: string;
+    bundler: 'webpack' | 'vite';
+}
+export interface TriggerSpec {
+    event: string;
+    element: string;
+    setsState?: string;
+}
+export interface EffectSpec {
+    type: 'conditionalRender' | 'asyncEffect' | 'contextDependency';
+    rendersWhenTrue?: string;
+    rendersWhenFalse?: string;
+    waitStrategy: 'elementAppears' | 'domSettle' | 'none';
+    selector?: string;
+    settleMs?: number;
+}
+export interface ComponentInteraction {
+    trigger: TriggerSpec;
+    effect: EffectSpec;
+}
+export interface PolicySelectorEntry {
+    clippyId: string;
+    selector: string;
+    tag: string;
+    component: string;
+    label?: string;
+    route: string;
+    filePath: string;
+    attributes: Array<{
+        name: string;
+        value: string;
+    }>;
+    candidates: SelectorCandidate[];
+}
+export interface PolicyFlowStep {
+    step: number;
+    action: string;
+    target: string;
+    triggers?: Array<{
+        renders: string;
+        waitStrategy: 'elementAppears' | 'domSettle' | 'none';
+    }>;
+}
+export interface PolicyFlow {
+    flowId: string;
+    page: string;
+    intentPatterns: string[];
+    steps: PolicyFlowStep[];
+}
+export interface PolicyComponent {
+    name: string;
+    filePath: string;
+    route: string;
+    stateVariables: Array<{
+        name: string;
+        setter?: string;
+        initialValue?: string;
+    }>;
+    interactions: ComponentInteraction[];
+}
+export interface PolicyDocument extends ArtifactMetadata {
+    routes: DiscoveredRoute[];
+    selectors: PolicySelectorEntry[];
+    components: PolicyComponent[];
+    flows: PolicyFlow[];
+}
+export interface SelectorManifestEntry {
+    id: string;
+    selector: string;
+    component: string;
+    tag: string;
+    label?: string;
+    routes: string[];
+}
+export interface SelectorManifest {
+    version: string;
+    buildId: string;
+    generatedAt: string;
+    selectors: SelectorManifestEntry[];
+}
+export interface PolicyArtifacts {
+    metadata: ArtifactMetadata;
+    policy: PolicyDocument;
+    selectorManifest: SelectorManifest;
+}
+export interface UploadResult {
+    skipped: boolean;
+    policyUploaded: boolean;
+    selectorsUploaded: boolean;
+    mode: 'single' | 'split';
 }
 export interface KnowledgePackage {
     buildId: string;

package/dist/upload/Adapter.d.ts

@@ -0,0 +1,3 @@
+import type { ClippyPluginOptions, PolicyArtifacts, UploadResult } from '../types';
+export declare function performUpload(artifacts: PolicyArtifacts, options: ClippyPluginOptions): Promise<UploadResult>;
+export default performUpload;

package/dist/upload/Adapter.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.performUpload = performUpload;
+const Uploader_1 = require("./Uploader");
+async function performUpload(artifacts, options) {
+    // Allow adapters to supply a custom upload implementation
+    if (options && options.uploadAdapter && typeof options.uploadAdapter.uploadArtifacts === 'function') {
+        return options.uploadAdapter.uploadArtifacts(artifacts);
+    }
+    const uploader = new Uploader_1.Uploader(options);
+    return uploader.uploadArtifacts(artifacts);
+}
+exports.default = performUpload;

package/dist/upload/BackendAdapter.d.ts

@@ -0,0 +1,30 @@
+import type { PolicyArtifacts } from '../types';
+export interface SiteComponentRegistryUpload {
+    domain: string;
+    components: {
+        version: string;
+        generatedAt: string;
+        selectors: Array<{
+            clippyId: string;
+            selector: string;
+            tag: string;
+            component: string;
+            file: string;
+            attributes?: Array<{
+                name: string;
+                value: string | null;
+            }>;
+        }>;
+        components: Array<{
+            name: string;
+            file: string;
+            stateVariables?: any[];
+            interactions?: any[];
+            conditionalRenders?: any[];
+            effects?: any[];
+            contextUsages?: any[];
+        }>;
+    };
+}
+export declare function mapArtifactsToSiteRegistry(artifacts: PolicyArtifacts, domain: string): SiteComponentRegistryUpload;
+export default mapArtifactsToSiteRegistry;

package/dist/upload/BackendAdapter.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapArtifactsToSiteRegistry = mapArtifactsToSiteRegistry;
+// Convert internal PolicyArtifacts -> backend SiteComponentRegistryUpload.
+// This is intentionally a best-effort mapping: the plugin has richer
+// fields (routes, flows, selector candidates). The adapter flattens
+// and retains the core selectors/components the backend requires.
+function mapArtifactsToSiteRegistry(artifacts, domain) {
+    const generatedAt = artifacts.metadata.generatedAt;
+    const selectors = (artifacts.policy.selectors || []).map((s) => ({
+        clippyId: s.clippyId,
+        selector: s.selector,
+        tag: s.tag,
+        component: s.component,
+        file: s.filePath,
+        attributes: s.attributes || [],
+    }));
+    const components = (artifacts.policy.components || []).map((c) => ({
+        name: c.name,
+        file: c.filePath,
+        stateVariables: c.stateVariables || [],
+        interactions: c.interactions || [],
+        // Best-effort placeholders: preserve array shape expected by backend.
+        conditionalRenders: [],
+        effects: (c.interactions || []).map((it) => ({
+            dependencies: [],
+            asyncCalls: [],
+            runsOnMount: false,
+        })),
+        contextUsages: [],
+    }));
+    return {
+        domain,
+        components: {
+            version: artifacts.metadata.version,
+            generatedAt,
+            selectors,
+            components,
+        },
+    };
+}
+exports.default = mapArtifactsToSiteRegistry;

package/dist/upload/BackendUploadAdapter.d.ts

@@ -0,0 +1,13 @@
+import type { PolicyArtifacts, UploadResult } from '../types';
+export interface BackendUploadOptions {
+    /** Full URL to POST the SiteComponentRegistryUpload to, e.g. http://localhost:3000/website/registry */
+    url: string;
+    /** Authorization header value (full header string, e.g. 'Bearer ...') */
+    authorization?: string;
+    /** Domain to include in the payload (required by backend contract) */
+    domain: string;
+}
+export declare function createBackendUploadAdapter(opts: BackendUploadOptions): {
+    uploadArtifacts(artifacts: PolicyArtifacts): Promise<UploadResult>;
+};
+export default createBackendUploadAdapter;

package/dist/upload/BackendUploadAdapter.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBackendUploadAdapter = createBackendUploadAdapter;
+const BackendAdapter_1 = require("./BackendAdapter");
+function createBackendUploadAdapter(opts) {
+    if (!opts || !opts.url)
+        throw new Error('BackendUploadAdapter requires a target url');
+    if (!opts.domain)
+        throw new Error('BackendUploadAdapter requires a domain');
+    return {
+        async uploadArtifacts(artifacts) {
+            const payload = (0, BackendAdapter_1.mapArtifactsToSiteRegistry)(artifacts, opts.domain);
+            // Use global fetch when available (Node 18+), otherwise try dynamic import
+            const headers = { 'Content-Type': 'application/json' };
+            if (opts.authorization)
+                headers['authorization'] = opts.authorization;
+            if (typeof fetch === 'function') {
+                const res = await fetch(opts.url, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify(payload),
+                });
+                return {
+                    skipped: false,
+                    policyUploaded: res.ok,
+                    selectorsUploaded: res.ok,
+                    mode: 'single',
+                };
+            }
+            // Fallback to http/https
+            const { URL } = await import('url');
+            const parsed = new URL(opts.url);
+            const lib = parsed.protocol === 'https:' ? await import('https') : await import('http');
+            return new Promise((resolve, reject) => {
+                const req = lib.request(opts.url, {
+                    method: 'POST',
+                    headers,
+                }, (res) => {
+                    const ok = res.statusCode && res.statusCode >= 200 && res.statusCode < 300;
+                    // consume body
+                    res.on('data', () => { });
+                    res.on('end', () => resolve({ skipped: false, policyUploaded: !!ok, selectorsUploaded: !!ok, mode: 'single' }));
+                });
+                req.on('error', (err) => reject(err));
+                req.write(JSON.stringify(payload));
+                req.end();
+            });
+        },
+    };
+}
+exports.default = createBackendUploadAdapter;

package/dist/upload/PackageBuilder.d.ts

@@ -1,5 +1,38 @@
-import type { KnowledgePackage } from '../types';
+import type { ElementWithSelectors, InferredFlow, KnowledgePackage, PolicyArtifacts, PolicyComponent, PolicyDocument, PolicySelectorEntry, SelectorManifest, DiscoveredRoute } from '../types';
 export declare class PackageBuilder {
+    private version;
     buildPackage(data: Omit<KnowledgePackage, 'generatedAt'>): KnowledgePackage;
+    buildArtifacts(data: {
+        buildId: string;
+        bundler: 'webpack' | 'vite';
+        routes: DiscoveredRoute[];
+        selectors: ElementWithSelectors[];
+        flows: InferredFlow[];
+        components?: PolicyComponent[];
+    }): PolicyArtifacts;
+    buildPolicyDocument(data: {
+        buildId: string;
+        generatedAt: string;
+        bundler: 'webpack' | 'vite';
+        routes: DiscoveredRoute[];
+        selectors: ElementWithSelectors[];
+        flows: InferredFlow[];
+        components?: PolicyComponent[];
+    }): PolicyDocument;
+    buildSelectorManifest(data: {
+        buildId: string;
+        generatedAt: string;
+        selectors: PolicySelectorEntry[];
+    }): SelectorManifest;
     build(data: Omit<KnowledgePackage, 'generatedAt'>): Buffer;
+    buildArtifactsBuffer(artifacts: PolicyArtifacts): Buffer;
+    private inferProjectRoot;
+    private normalizePath;
+    private toPolicySelectors;
+    private toPolicyComponents;
+    private toPolicyFlows;
+    private deriveComponentName;
+    private deriveStableId;
+    private extractClippyIdFromSelector;
+    private simpleHash;
 }