@preply/ds-ai-core 11.1.0

package/src/event-tracking.ts

@@ -0,0 +1,117 @@
+/* eslint-disable security/detect-non-literal-fs-filename */
+import { PostHog } from 'posthog-node';
+import fs from 'node:fs';
+import path from 'node:path';
+import { userInfo } from 'os';
+import pkg from '../package.json' with { type: 'json' };
+import envPaths from 'env-paths';
+
+const DATA_PATH = envPaths(pkg.name).data;
+
+/**
+ * Returns persistent client ID or null if it failed to generate.
+ * Can be used to identify a client across sessions when user name is not available.
+ */
+function getUserId() {
+    try {
+        // Try to read client ID from file or generate a new one
+        const clientIdPath = path.join(DATA_PATH, 'client-id.txt');
+        try {
+            return fs.readFileSync(clientIdPath, 'utf8');
+        } catch {
+            const clientId = crypto.randomUUID();
+            if (!fs.existsSync(DATA_PATH)) {
+                fs.mkdirSync(DATA_PATH, { recursive: true });
+            }
+            fs.writeFileSync(clientIdPath, clientId, 'utf8');
+            return clientId;
+        }
+    } catch {
+        return crypto.randomUUID();
+    }
+}
+
+/**
+ * Returns current user name or null if it's not available.
+ */
+function getUserName() {
+    try {
+        const userName = userInfo().username;
+        return userName;
+    } catch {
+        return null;
+    }
+}
+
+const client = new PostHog('phc_idhNqodmRjwHSolig26UgSRsgb6pIyYRIvIBzgNAkGZ', {
+    host: 'https://eu.i.posthog.com',
+});
+
+/**
+ * Identifies the current user.
+ * Should be called once at the start of the program.
+ */
+export function identify() {
+    try {
+        const userId = getUserId();
+        const userName = getUserName();
+        const data = {
+            distinctId: userId,
+            properties: {
+                userName,
+            },
+        };
+        client.identify(data);
+    } catch {
+        return;
+    }
+}
+
+/**
+ * Tracks a generic event.
+ */
+export function trackEvent(eventName: string, properties?: Record<string, unknown>) {
+    try {
+        const userId = getUserId();
+        const data = {
+            distinctId: userId,
+            event: eventName,
+            properties: {
+                ...properties,
+                mcpVersion: pkg.version,
+            },
+        };
+        client.capture(data);
+    } catch {
+        return;
+    }
+}
+
+/**
+ * Tracks a tool call.
+ * Should be called for each tool call.
+ */
+export function trackToolCall(
+    toolName: string,
+    args: Record<string, unknown>,
+    meta?: Record<string, unknown>,
+) {
+    trackEvent('tool_called', {
+        toolName,
+        arguments: args,
+        meta,
+    });
+}
+
+/**
+ * Flushes all pending events and shuts down the PostHog client.
+ * Must be called before process exit in short-lived processes (e.g. CLI)
+ * to ensure events are actually sent over the network.
+ */
+export async function shutdownEventTracking() {
+    try {
+        await client.shutdown();
+    } catch {
+        return;
+    }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * as tools from './tools';
+export * from './event-tracking';
+export * from './types';
+export type { Tool } from './utils/define-tool';

package/src/tools/components/__tests__/get-component-docs.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getComponentDocs } from '../get-component-docs';
+
+vi.mock(import('../context/get-components-data'), () => ({
+    getComponentsData: () => ({
+        web: {
+            Button: {
+                meta: {
+                    name: 'Button',
+                    import: "import { Button } from '@preply/ds-web-lib';",
+                    description: 'Button component',
+                    deprecated: false,
+                },
+                docs: 'Button component docs',
+            },
+        },
+        'react-native': {
+            Button: {
+                meta: {
+                    name: 'Button',
+                    import: "import { Button } from '@preply/ds-rn-lib';",
+                    description: 'Button component for rn',
+                    deprecated: false,
+                },
+                docs: 'Button component docs for rn',
+            },
+        },
+    }),
+}));
+
+describe('getComponentDocs tool', () => {
+    it('returns docs for existing web component', () => {
+        expect(getComponentDocs.callback({ name: 'Button', platform: 'web' }))
+            .toMatchInlineSnapshot(`
+          [
+            "Button component docs",
+          ]
+        `);
+    });
+
+    it('returns docs for existing react-native component', () => {
+        expect(getComponentDocs.callback({ name: 'Button', platform: 'react-native' }))
+            .toMatchInlineSnapshot(`
+          [
+            "Button component docs for rn",
+          ]
+        `);
+    });
+
+    it('returns error when component is not found', () => {
+        expect(getComponentDocs.callback({ name: 'Missing', platform: 'web' }))
+            .toMatchInlineSnapshot(`
+          [
+            "Component "Missing" not found",
+          ]
+        `);
+    });
+});

package/src/tools/components/__tests__/list-components.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it, vi } from 'vitest';
+import { listComponents } from '../list-components';
+
+vi.mock(import('../context/get-components-data'), () => ({
+    getComponentsData: () => ({
+        web: {
+            Button: {
+                meta: {
+                    name: 'Button',
+                    import: "import { Button } from '@preply/ds-web-lib';",
+                    description: 'Button component',
+                },
+                docs: 'Button component docs',
+            },
+        },
+        'react-native': {
+            Button: {
+                meta: {
+                    name: 'Button',
+                    import: "import { Button } from '@preply/ds-rn-lib';",
+                    description: 'Button component for rn',
+                },
+                docs: 'Button component docs for rn',
+            },
+        },
+    }),
+}));
+
+describe('listComponents tool', () => {
+    it('returns component list for web platform', () => {
+        expect(listComponents.callback({ platform: 'web' })).toMatchInlineSnapshot(`
+          [
+            "Each item has the following fields:
+          - name - The name of the component (e.g. Button)
+          - import - The import path of the component (e.g. "import { Button } from '@preply/ds-web-lib';")
+          - description - The description of the component
+          - deprecated - Whether the component is deprecated (false if missing)",
+            "---
+          name: Button
+          import: import { Button } from '@preply/ds-web-lib';
+          description: Button component
+          ---",
+          ]
+        `);
+    });
+
+    it('returns component list for react-native platform', () => {
+        expect(listComponents.callback({ platform: 'react-native' })).toMatchInlineSnapshot(`
+          [
+            "Each item has the following fields:
+          - name - The name of the component (e.g. Button)
+          - import - The import path of the component (e.g. "import { Button } from '@preply/ds-rn-lib';")
+          - description - The description of the component
+          - deprecated - Whether the component is deprecated (false if missing)",
+            "---
+          name: Button
+          import: import { Button } from '@preply/ds-rn-lib';
+          description: Button component for rn
+          ---",
+          ]
+        `);
+    });
+});

package/src/tools/components/context/__test__/get-components-data.test.ts

@@ -0,0 +1,57 @@
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { buildComponents } from '../get-components-data';
+
+describe('getComponentsData', () => {
+    it('builds docs for a real fixture entrypoint', () => {
+        const components = buildComponents([
+            {
+                importPath: '@preply/ds-web-lib/fixtures',
+                entrypoint: path.resolve(import.meta.dirname, 'test-components/index.ts'),
+            },
+        ]);
+
+        expect(components).toStrictEqual({
+            FixtureButton: {
+                meta: {
+                    name: 'FixtureButton',
+                    import: "import { FixtureButton } from '@preply/ds-web-lib/fixtures';",
+                    description: 'Lightweight fixture component used in docs generation tests.',
+                },
+                docs: expect.any(String),
+            },
+        });
+
+        expect(components.FixtureButton.docs).toMatchInlineSnapshot(`
+          "# FixtureButton
+
+          \`\`\`
+          import { FixtureButton } from '@preply/ds-web-lib/fixtures';
+          \`\`\`
+
+          Lightweight fixture component used in docs generation tests.
+
+          @example
+
+          \`\`\`
+          <FixtureButton label="Save" />
+          \`\`\`
+
+          ## Props
+
+          ### \`label\`
+
+          - Type: \`string\`
+          - Required
+
+          Visible button label
+
+          ### \`disabled\`
+
+          - Type: \`boolean | undefined\`
+          - Default value: \`false\`
+
+          Disabled state"
+        `);
+    });
+});

package/src/tools/components/context/__test__/test-components/FixtureButton.tsx

@@ -0,0 +1,18 @@
+import React from 'react';
+
+export type FixtureButtonProps = {
+    /** Visible button label */
+    label: string;
+    /** Disabled state */
+    disabled?: boolean;
+};
+
+/**
+ * Lightweight fixture component used in docs generation tests.
+ *
+ * @example
+ * <FixtureButton label="Save" />
+ */
+export const FixtureButton = ({ label, disabled = false }: FixtureButtonProps) => {
+    return <button disabled={disabled}>{label}</button>;
+};

package/src/tools/components/context/__test__/test-components/index.ts

@@ -0,0 +1 @@
+export { FixtureButton } from './FixtureButton';

package/src/tools/components/context/__test__/test-components/tsconfig.json

@@ -0,0 +1,11 @@
+{
+    "extends": "../../../../../../../../tsconfig.json",
+    "compilerOptions": {
+        "jsx": "react-jsx",
+        "module": "esnext",
+        "target": "esnext",
+        "moduleResolution": "node",
+        "types": ["node", "react"]
+    },
+    "include": ["./*.ts", "./*.tsx"]
+}

package/src/tools/components/context/extract-component-docgen-info.ts

@@ -0,0 +1,108 @@
+/* eslint-disable import/no-named-as-default-member */
+import path from 'path';
+import ts from 'typescript';
+import { ComponentDoc, withCompilerOptions } from 'react-docgen-typescript';
+
+/**
+ * Follows re-export alias chains to the original symbol declaration.
+ * Needed because entry files typically re-export components (e.g. `export { Button } from './Button'`),
+ * and react-docgen-typescript needs the real declaration to extract prop types.
+ */
+function resolveSymbol(symbol: ts.Symbol, checker: ts.TypeChecker): ts.Symbol {
+    while (symbol.flags & ts.SymbolFlags.Alias) {
+        const next = checker.getAliasedSymbol(symbol);
+        if (next === symbol) break;
+        symbol = next;
+    }
+    return symbol;
+}
+
+function getDocForSymbol(program: ts.Program, symbol: ts.Symbol, aliasName: string) {
+    const decl = symbol.getDeclarations()?.[0];
+    if (!decl) return null;
+
+    const sourcePath = decl.getSourceFile().fileName;
+
+    const parser = withCompilerOptions(program.getCompilerOptions(), {
+        shouldExtractValuesFromUnion: true,
+        shouldIncludePropTagMap: true,
+    }).parseWithProgramProvider;
+
+    const docs = parser.call(null, sourcePath, () => program);
+
+    return docs.find(d => d.displayName === aliasName);
+}
+
+export function extractDocgenInfo(entry: string, ignoreErrors: (string | RegExp)[] = []) {
+    console.info(`Extracting docgen info from ${entry}`);
+
+    const configPath = ts.findConfigFile(
+        path.dirname(path.resolve(entry)),
+        ts.sys.fileExists,
+        'tsconfig.json',
+    );
+
+    if (!configPath) {
+        throw new Error('No tsconfig.json found');
+    }
+
+    const { config } = ts.readConfigFile(configPath, ts.sys.readFile);
+    const { options, fileNames } = ts.parseJsonConfigFileContent(
+        config,
+        ts.sys,
+        path.dirname(configPath),
+    );
+
+    const program = ts.createProgram({ rootNames: fileNames, options });
+    const checker = program.getTypeChecker();
+    const source = program.getSourceFile(entry);
+
+    if (!source) {
+        throw new Error(`Cannot load: ${entry}`);
+    }
+
+    const moduleSymbol = checker.getSymbolAtLocation(source);
+    if (!moduleSymbol) {
+        throw new Error(`No symbol information for: ${entry}`);
+    }
+
+    const exportSymbols = checker.getExportsOfModule(moduleSymbol);
+    const docs: ComponentDoc[] = [];
+
+    console.info(`Parsing ${exportSymbols.length} exports`);
+
+    for (const exp of exportSymbols) {
+        const aliasName = exp.getName();
+        const realSym = resolveSymbol(exp, checker);
+
+        if ((realSym.flags & ts.SymbolFlags.Value) === 0) {
+            continue;
+        }
+
+        const doc = getDocForSymbol(program, realSym, aliasName);
+
+        if (!doc) {
+            const isIgnored = ignoreErrors.some(i => {
+                if (typeof i === 'string' && i === aliasName) {
+                    return true;
+                }
+
+                if (i instanceof RegExp && i.test(aliasName)) {
+                    return true;
+                }
+
+                return false;
+            });
+
+            if (!isIgnored) {
+                throw new Error(`Failed to parse component: ${aliasName}`);
+            }
+        } else {
+            docs.push(doc);
+        }
+    }
+
+    console.info(`Parsed ${docs.length} exports`);
+
+    return docs;
+}

package/src/tools/components/context/get-components-data.ts

@@ -0,0 +1,94 @@
+import path from 'node:path';
+import { extractDocgenInfo } from './extract-component-docgen-info';
+import { renderComponentDoc, renderImportExample } from './render-component-doc';
+
+export type Entry = {
+    importPath: string;
+    entrypoint: string;
+    ignoreErrors?: (string | RegExp)[];
+};
+
+export type ComponentMeta = {
+    name: string;
+    import: string;
+    description: string;
+    deprecated?: boolean;
+};
+
+export type ComponentInfo = {
+    meta: ComponentMeta;
+    docs: string;
+};
+
+export type ComponentsMap = Record<string, ComponentInfo>;
+
+type PlatformComponents = {
+    web: ComponentsMap;
+    'react-native': ComponentsMap;
+};
+
+export function buildComponents(entries: Entry[]): ComponentsMap {
+    const components: ComponentsMap = {};
+
+    for (const entry of entries) {
+        const docgenInfos = extractDocgenInfo(entry.entrypoint, entry.ignoreErrors);
+        for (const docgenInfo of docgenInfos) {
+            const componentDocs = renderComponentDoc(docgenInfo, entry.importPath);
+            if (componentDocs) {
+                const { displayName, description, tags } = docgenInfo;
+                components[displayName] = {
+                    meta: {
+                        name: displayName,
+                        import: renderImportExample(docgenInfo, entry.importPath),
+                        description: description,
+                    },
+                    docs: componentDocs,
+                };
+
+                if (tags?.deprecated) {
+                    components[displayName].meta.deprecated = true;
+                }
+            }
+        }
+    }
+
+    return components;
+}
+
+const PACKAGES_DIR = path.resolve(import.meta.dirname, '../../../../../');
+
+export function getComponentsData(): PlatformComponents {
+    return {
+        web: buildComponents([
+            {
+                importPath: '@preply/ds-web-lib',
+                entrypoint: path.resolve(PACKAGES_DIR, 'web-lib/src/index.ts'),
+                ignoreErrors: [/^IntlFormatted/],
+            },
+            {
+                importPath: '@preply/ds-web-lib/components/deprecated',
+                entrypoint: path.resolve(
+                    PACKAGES_DIR,
+                    'web-lib/src/components/deprecated/index.tsx',
+                ),
+            },
+            {
+                importPath: '@preply/ds-web-root',
+                entrypoint: path.resolve(PACKAGES_DIR, 'web-root/src/index.ts'),
+                ignoreErrors: ['themes'],
+            },
+        ]),
+        'react-native': buildComponents([
+            {
+                importPath: '@preply/ds-rn-lib',
+                entrypoint: path.resolve(PACKAGES_DIR, 'rn-lib/src/index.ts'),
+                ignoreErrors: [/^IntlFormatted/, 'DS_ICON_FONT_NAME'],
+            },
+            {
+                importPath: '@preply/ds-rn-root',
+                entrypoint: path.resolve(PACKAGES_DIR, 'rn-root/src/index.ts'),
+                ignoreErrors: ['themes', 'useDisableAnimations'],
+            },
+        ]),
+    };
+}

package/src/tools/components/context/index.ts

@@ -0,0 +1,4 @@
+// Build-time macro: getComponentsData() runs at compile time and its return value is inlined into the bundle
+import { getComponentsData } from './get-components-data' with { type: 'macro' };
+
+export default getComponentsData();

package/src/tools/components/context/render-component-doc.ts

@@ -0,0 +1,89 @@
+import { ComponentDoc, PropItem } from 'react-docgen-typescript';
+import { md } from '../../../utils/md';
+
+export function renderComponentDoc(docgenInfo: ComponentDoc, importPath: string) {
+    const { displayName, description, tags, props } = docgenInfo;
+
+    return md.joinBlocks([
+        md.heading(displayName),
+        md.codeBlock(renderImportExample(docgenInfo, importPath)),
+        description,
+        renderTags(tags),
+        renderProps(props),
+    ]);
+}
+
+export function renderImportExample(docgenInfo: ComponentDoc, importPath: string) {
+    const { displayName } = docgenInfo;
+    return `import { ${displayName} } from '${importPath}';`;
+}
+
+function renderTags(tags?: Record<string, string>, exclude: string[] = []) {
+    if (!tags) return '';
+
+    const blocks: string[] = [];
+
+    for (const [key, value] of Object.entries(tags)) {
+        if (['default', ...exclude].includes(key)) continue;
+
+        blocks.push(`@${key}`);
+
+        if (key === 'example') {
+            blocks.push(md.codeBlock(value));
+        } else {
+            blocks.push(value);
+        }
+    }
+
+    return md.joinBlocks(blocks);
+}
+
+function renderProps(props?: Record<string, PropItem>) {
+    if (!props || Object.keys(props).length === 0) return '';
+
+    const blocks = [md.heading('Props', { level: 2 })];
+
+    for (const prop of Object.values(props)) {
+        blocks.push(renderProp(prop));
+    }
+
+    return md.joinBlocks(blocks);
+}
+
+const IGNORE_UNWRAPPED_UNION_TYPES = ['ReactNode', 'boolean', 'boolean | undefined'];
+
+function renderPropDataList(prop: PropItem) {
+    const list: (string | undefined)[] = [];
+
+    let type = prop.type.name;
+    let detailedType: string | undefined = undefined;
+
+    if (prop.type.name === 'enum') {
+        type = prop.type.raw ?? 'unknown';
+
+        const isIgnoreUnwrappedUnionType = IGNORE_UNWRAPPED_UNION_TYPES.includes(type);
+        const isDuplicatesUnwrappedUnionType = type.split(' | ').length === prop.type.value.length;
+
+        if (!isIgnoreUnwrappedUnionType && !isDuplicatesUnwrappedUnionType) {
+            detailedType = prop.type.value.map((v: { value: string }) => v.value).join(' | ');
+        }
+    }
+
+    list.push(
+        `Type: ${md.code(type)}`,
+        detailedType && `Detailed type: ${md.code(detailedType)}`,
+        prop.defaultValue && `Default value: ${md.code(`${prop.defaultValue.value}` || '""')}`,
+        prop.required ? 'Required' : undefined,
+    );
+
+    return md.list(list.filter((item): item is string => item !== undefined && item !== null));
+}
+
+function renderProp(prop: PropItem) {
+    return md.joinBlocks([
+        md.heading(md.code(prop.name), { level: 3 }),
+        renderPropDataList(prop),
+        prop.description,
+        renderTags(prop.tags),
+    ]);
+}

package/src/tools/components/get-component-docs.ts

@@ -0,0 +1,26 @@
+import { PLATFORMS } from '../../types';
+import { defineTool } from '../../utils/define-tool';
+import data from './context';
+import * as z from 'zod';
+
+export const getComponentDocs = defineTool({
+    name: 'get_component_docs',
+    description: 'Returns the documentation for a specific component in the Preply design system.',
+    arguments: z.object({
+        name: z.string().describe('The name of the component'),
+    }),
+    options: z.object({
+        platform: z
+            .enum(PLATFORMS)
+            .describe('Target platform for the component documentation. Required.'),
+    }),
+    callback: ({ name, platform }) => {
+        const docs = data[platform][name]?.docs;
+
+        if (!docs) {
+            return [`Component "${name}" not found`];
+        }
+
+        return [docs];
+    },
+});