@wix/origami-transforms 0.1.14 → 0.1.15

package/dist/companionRegistrations.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Every registration in `files`, by its `companionApp.<Name>` type.
+ * @param {Iterable<readonly [string, string]>} files Each extension file's path and source.
+ * @returns {Map<string, CompanionRegistration>}
+ */
+export function readCompanionRegistrations(files: Iterable<readonly [string, string]>): Map<string, CompanionRegistration>;
+/**
+ * @typedef {object} CompanionModule
+ * @property {CompanionRegistration} registration
+ * @property {CompanionImport} import How a page imports it: a component as its entry exports it, a context provider
+ *   as the entry's default export.
+ */
+/**
+ * Every `@site/site-code/<name>` a page can import, by its `companionApp` name. A provider's hook is imported from
+ * the provider's module.
+ * @param {ReadonlyMap<string, CompanionRegistration>} registrations
+ * @returns {Map<string, CompanionModule>}
+ */
+export function companionModules(registrations: ReadonlyMap<string, CompanionRegistration>): Map<string, CompanionModule>;
+export function isExtensionFile(path: string): boolean;
+export function importTarget(from: string, specifier: string): string;
+export function entryTarget(registration: CompanionRegistration, srcDir: string): string;
+export function findFile(target: string, exists: (path: string) => boolean): string | undefined;
+export function companionExports(modules: ReadonlyMap<string, CompanionModule>, entry: (registration: CompanionRegistration) => string): Record<string, string>;
+export function readCompanionRegistrationsIn(srcDir: string): Map<string, CompanionRegistration>;
+export type CompanionModule = {
+    registration: CompanionRegistration;
+    /**
+     * How a page imports it: a component as its entry exports it, a context provider
+     * as the entry's default export.
+     */
+    import: CompanionImport;
+};
+export type CompanionImport = {
+    kind: "default";
+} | {
+    kind: "named";
+    exportName: string;
+};
+export type CompanionComponentRegistration = {
+    kind: "component";
+    /**
+     * The registration's file.
+     */
+    path: string;
+    /**
+     * The client entry's import as written (`./component.tsx?url`), relative to `path`.
+     */
+    source: string;
+    /**
+     * How the entry's component is exported.
+     */
+    componentImport: CompanionImport;
+};
+export type CompanionContextRegistration = {
+    kind: "contextProvider";
+    /**
+     * The registration's file.
+     */
+    path: string;
+    /**
+     * `resources.client.url`, relative to the companion app's `src`, as the Wix CLI reads it.
+     * The module's default export is the provider.
+     */
+    source: string;
+    /**
+     * `resources.contextSpecifier.hook`, the module's named export that reads the context.
+     */
+    hook: string;
+};
+export type CompanionRegistration = CompanionComponentRegistration | CompanionContextRegistration;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/origami-transforms",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Babel and PostCSS checks and transforms for Wix origami page files.",
   "main": "./src/index.js",
   "files": [
@@ -15,6 +15,8 @@
   },
   "dependencies": {
     "@babel/core": "^7.26.0",
+    "@babel/parser": "^7.25.0",
+    "@babel/types": "^7.25.2",
     "@wix/origami-fonts": "1.0.1",
     "@wix/origami-system-components": "1.9.0",
     "postcss": "^8.5.3",
@@ -54,9 +56,13 @@
     "./wrapper-import": {
       "types": "./dist/wrapperImport.d.ts",
       "default": "./src/wrapperImport.js"
+    },
+    "./companion-registrations": {
+      "types": "./dist/companionRegistrations.d.ts",
+      "default": "./src/companionRegistrations.js"
     }
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "falconPackageHash": "dcaeecf42c720e3e9a25f95eadad7516666d783eef907ba5f39467f1"
+  "falconPackageHash": "08fa24b6d989c88b62d43cea5a959c50ee2a2212bc6cb279ecf53dc1"
 }

package/src/companionRegistrations.js

@@ -0,0 +1,200 @@
+// A companion app's `editorReactComponent` and `contextProvider` registrations, read the same way by the export
+// (origami-site-generator, from the exported files) and by the site's Vite plugin (origami-site-runtime, from disk).
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { posix } from 'node:path'
+import { parse } from '@babel/parser'
+import * as t from '@babel/types'
+
+/** @typedef {{ kind: 'default' } | { kind: 'named', exportName: string }} CompanionImport */
+/**
+ * @typedef {object} CompanionComponentRegistration
+ * @property {'component'} kind
+ * @property {string} path The registration's file.
+ * @property {string} source The client entry's import as written (`./component.tsx?url`), relative to `path`.
+ * @property {CompanionImport} componentImport How the entry's component is exported.
+ */
+/**
+ * @typedef {object} CompanionContextRegistration
+ * @property {'contextProvider'} kind
+ * @property {string} path The registration's file.
+ * @property {string} source `resources.client.url`, relative to the companion app's `src`, as the Wix CLI reads it.
+ *   The module's default export is the provider.
+ * @property {string} hook `resources.contextSpecifier.hook`, the module's named export that reads the context.
+ */
+/** @typedef {CompanionComponentRegistration | CompanionContextRegistration} CompanionRegistration */
+
+/** @param {string} path */
+export const isExtensionFile = path => /\.extension\.[cm]?[jt]sx?$/.test(path)
+
+/**
+ * Every registration in `files`, by its `companionApp.<Name>` type.
+ * @param {Iterable<readonly [string, string]>} files Each extension file's path and source.
+ * @returns {Map<string, CompanionRegistration>}
+ */
+export function readCompanionRegistrations(files) {
+    /** @type {Map<string, CompanionRegistration>} */
+    const registrations = new Map()
+    for (const [path, source] of files) {
+        const ast = parse(source, { sourceType: 'module', plugins: ['jsx', 'typescript'] })
+        t.traverseFast(ast, node => {
+            if (!t.isCallExpression(node) || !t.isMemberExpression(node.callee)) return
+            const isComponent = t.isIdentifier(node.callee.property, { name: 'editorReactComponent' })
+            if (!isComponent && !t.isIdentifier(node.callee.property, { name: 'contextProvider' })) return
+            const config = node.arguments[0]
+            const type = property(config, 'type')
+            const resources = property(config, 'resources')
+            const registration = isComponent ? component(ast, path, resources) : contextProvider(path, resources)
+            if (!t.isStringLiteral(type)) throw new Error(`Unsupported component registration: ${path}`)
+            if (!/^companionApp\.[^.]+$/.test(type.value))
+                throw new Error(`Unsupported companion component namespace: ${type.value}`)
+            if (registrations.has(type.value)) throw new Error(`Duplicate user code component: ${type.value}`)
+            registrations.set(type.value, { ...registration, path })
+        })
+    }
+    return registrations
+}
+
+/**
+ * @param {t.File} ast @param {string} path @param {t.Expression | undefined} resources
+ * @returns {Omit<CompanionComponentRegistration, 'path'>}
+ */
+const component = (ast, path, resources) => {
+    const url = property(property(resources, 'client'), 'componentUrl')
+    if (!t.isIdentifier(url)) throw new Error(`Unsupported component registration: ${path}`)
+    const declaration = ast.program.body.find(
+        statement =>
+            t.isImportDeclaration(statement) && statement.specifiers.some(specifier => specifier.local.name === url.name)
+    )
+    if (!t.isImportDeclaration(declaration)) throw new Error(`Missing component entry: ${path}`)
+    const specifier = declaration.specifiers.find(specifier => specifier.local.name === url.name)
+    if (!specifier || t.isImportNamespaceSpecifier(specifier))
+        throw new Error(`Unsupported component registration: ${path}`)
+    return {
+        kind: 'component',
+        source: declaration.source.value,
+        componentImport: t.isImportDefaultSpecifier(specifier)
+            ? { kind: 'default' }
+            : {
+                  kind: 'named',
+                  exportName: t.isIdentifier(specifier.imported) ? specifier.imported.name : specifier.imported.value,
+              },
+    }
+}
+
+/**
+ * @param {string} path @param {t.Expression | undefined} resources
+ * @returns {Omit<CompanionContextRegistration, 'path'>}
+ */
+const contextProvider = (path, resources) => {
+    const url = property(property(resources, 'client'), 'url')
+    const hook = property(property(resources, 'contextSpecifier'), 'hook')
+    if (!t.isStringLiteral(url) || !t.isStringLiteral(hook) || !/^[A-Za-z_$][\w$]*$/.test(hook.value))
+        throw new Error(`Unsupported context provider registration: ${path}`)
+    return { kind: 'contextProvider', source: url.value, hook: hook.value }
+}
+
+/**
+ * The file a relative import in `from` points at, without its query, before `findFile` fills in its extension.
+ * @param {string} from @param {string} specifier
+ */
+export const importTarget = (from, specifier) =>
+    posix.normalize(posix.join(posix.dirname(from), specifier.split(/[?#]/)[0]))
+
+/**
+ * Where a registration's client entry points, before `findFile` fills in its extension.
+ * @param {CompanionRegistration} registration @param {string} srcDir The companion app's `src`, in the same form as `path`.
+ */
+export const entryTarget = (registration, srcDir) =>
+    registration.kind === 'component'
+        ? importTarget(registration.path, registration.source)
+        : importTarget(posix.join(srcDir, 'index'), registration.source)
+
+// The files an import can mean, most likely first: as written, a `.js` import of a TypeScript source, then an added
+// extension or index.
+/** @param {string} target */
+const candidates = target => [
+    target,
+    ...(/\.[cm]?js$/.test(target)
+        ? [
+              target.replace(/\.js$/, '.ts'),
+              target.replace(/\.js$/, '.tsx'),
+              target.replace(/\.mjs$/, '.mts'),
+              target.replace(/\.cjs$/, '.cts'),
+          ]
+        : []),
+    ...['.ts', '.tsx', '.js', '.jsx', '.mjs', '.json', '/index.ts', '/index.tsx', '/index.js'].map(ext => target + ext),
+]
+
+/**
+ * The file an import target (from `importTarget` or `entryTarget`) means, or undefined when none exists.
+ * @param {string} target @param {(path: string) => boolean} exists
+ */
+export const findFile = (target, exists) => candidates(target).find(exists)
+
+/**
+ * @typedef {object} CompanionModule
+ * @property {CompanionRegistration} registration
+ * @property {CompanionImport} import How a page imports it: a component as its entry exports it, a context provider
+ *   as the entry's default export.
+ */
+
+/**
+ * Every `@site/site-code/<name>` a page can import, by its `companionApp` name. A provider's hook is imported from
+ * the provider's module.
+ * @param {ReadonlyMap<string, CompanionRegistration>} registrations
+ * @returns {Map<string, CompanionModule>}
+ */
+export function companionModules(registrations) {
+    /** @type {Map<string, CompanionModule>} */
+    const modules = new Map()
+    for (const [type, registration] of registrations) {
+        const name = type.slice('companionApp.'.length)
+        if (!/^[A-Za-z_$][\w$]*$/.test(name)) throw new Error(`Unsupported extension component name: ${name}`)
+        modules.set(name, {
+            registration,
+            import: registration.kind === 'component' ? registration.componentImport : { kind: 'default' },
+        })
+    }
+    return modules
+}
+
+/**
+ * The site-code `package.json` `exports` that TypeScript resolves `@site/site-code/<name>` through, one per module.
+ * @param {ReadonlyMap<string, CompanionModule>} modules
+ * @param {(registration: CompanionRegistration) => string} entry The registration's client entry, relative to the
+ *   companion app.
+ * @returns {Record<string, string>}
+ */
+export const companionExports = (modules, entry) =>
+    Object.fromEntries([...modules].map(([name, { registration }]) => [`./${name}`, `./${entry(registration)}`]))
+
+/**
+ * Every registration under a companion app's `src` on disk, with absolute paths; none when it has no `src`.
+ * @param {string} srcDir
+ */
+export const readCompanionRegistrationsIn = srcDir =>
+    readCompanionRegistrations(
+        extensionFiles(srcDir).map(file => /** @type {const} */ ([file, readFileSync(file, 'utf8')]))
+    )
+
+/** @param {string} directory @returns {string[]} */
+const extensionFiles = directory =>
+    existsSync(directory)
+        ? readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
+              const path = posix.join(directory, entry.name)
+              if (entry.isDirectory()) return entry.name === 'node_modules' ? [] : extensionFiles(path)
+              return isExtensionFile(entry.name) ? [path] : []
+          })
+        : []
+
+/** @param {unknown} node @param {string} name @returns {t.Expression | undefined} */
+const property = (node, name) => {
+    if (!node || !t.isObjectExpression(/** @type {t.Node} */ (node))) return undefined
+    const match = /** @type {t.ObjectExpression} */ (node).properties.find(
+        candidate =>
+            t.isObjectProperty(candidate) &&
+            !candidate.computed &&
+            (t.isIdentifier(candidate.key, { name }) || t.isStringLiteral(candidate.key, { value: name }))
+    )
+    return t.isObjectProperty(match) && t.isExpression(match.value) ? match.value : undefined
+}