workstar-compiler 0.2.4-beta.0 → 0.2.4-beta.2

package/README.md

@@ -23,6 +23,8 @@ Inside `<script lang="ts">`, imports and an optional exported `Props` type defin
 
 Use `bind:attrs={record}` on a native element to spread a plain record of checked HTML attributes. The record can be reactive. Event handlers, styles, refs, and unsafe URLs are rejected; bind events explicitly with `on:event`.
 
+Run `workstar-compile --compat-audit src` before migrating a TSX or Vue tree. The JSON report identifies the component and first unsupported construct in each file, suggests runtime mode when appropriate, and inventories packages handled by Workstar aliases or requiring browser verification. Runtime-mode Vite builds fail early on unsupported React API imports and include the source position and implemented alternatives.
+
 `<noscript>` accepts static text only. Put links and localized expressions elsewhere in the page; nested markup would be parsed as raw text and dynamic markers cannot hydrate reliably.
 
 See the [Workstar repository](https://github.com/wslab-ai/workstar) for starters and current limitations.

package/dist/src/project.d.ts

@@ -3,13 +3,21 @@ export interface ProjectStyles {
 }
 export interface ForeignAuditEntry {
     filename: string;
+    component: string;
     supported: boolean;
     reason?: string;
+    suggestion?: string;
+}
+export interface ForeignDependency {
+    package: string;
+    files: string[];
+    handling: 'workstar-runtime-alias' | 'requires-browser-verification';
 }
 export interface ForeignAudit {
     total: number;
     supported: number;
     entries: ForeignAuditEntry[];
+    dependencies: ForeignDependency[];
 }
 /** Compile one authored Workstar view without rewriting unrelated generated modules. */
 export declare function compileViewFile(sourcePath: string, outputPath: string, options?: ProjectStyles): Promise<void>;

package/dist/src/project.js

@@ -5,6 +5,33 @@ import { compileComponentParts } from './index.js';
 import { convertForeignComponent } from './compat.js';
 import { reactComponentExportName } from './react-compat.js';
 import { resolveReactComponentImport } from './react-import-resolution.js';
+function componentName(source, filename) {
+    const match = /export\s+default\s+function\s+([A-Za-z_$][\w$]*)/.exec(source) ??
+        /export\s+(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/.exec(source) ??
+        /export\s+(?:const|let|var)\s+([A-Za-z_$][\w$]*)/.exec(source);
+    return (match?.[1] ??
+        filename
+            .split(/[\\/]/)
+            .at(-1)
+            .replace(/\.[^.]+$/, ''));
+}
+function packageName(specifier) {
+    if (specifier.startsWith('.') ||
+        specifier.startsWith('/') ||
+        specifier.startsWith('#'))
+        return undefined;
+    const parts = specifier.split('/');
+    return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+}
+function sourcePackages(source) {
+    const packages = new Set();
+    for (const match of source.matchAll(/(?:from\s+|import\s*\(|require\s*\()\s*['"]([^'"]+)['"]/g)) {
+        const name = packageName(match[1] ?? '');
+        if (name)
+            packages.add(name);
+    }
+    return [...packages];
+}
 async function filesInDirectory(directory, include, prefix = '') {
     const entries = await readdir(join(directory, prefix), {
         withFileTypes: true,
@@ -66,21 +93,31 @@ export async function compileForeignFile(sourcePath, outputPath, options = {}) {
 export async function auditForeignDirectory(sourceDirectory) {
     const paths = await filesInDirectory(sourceDirectory, (name) => /\.(tsx|vue)$/.test(name) &&
         !/\.(test|spec|stories)\.(tsx|vue)$/.test(name));
+    const dependencyFiles = new Map();
     const entries = await Promise.all(paths.map(async (filename) => {
         const sourcePath = join(sourceDirectory, filename);
+        const source = await readFile(sourcePath, 'utf8');
+        for (const dependency of sourcePackages(source)) {
+            const files = dependencyFiles.get(dependency) ?? new Set();
+            files.add(filename);
+            dependencyFiles.set(dependency, files);
+        }
+        const component = componentName(source, filename);
         try {
-            const converted = convertForeignComponent(await readFile(sourcePath, 'utf8'), sourcePath, {
+            const converted = convertForeignComponent(source, sourcePath, {
                 resolveReactImport: (specifier) => resolveReactComponentImport(sourcePath, specifier),
             });
             compileComponentParts(converted, `${sourcePath}.workstar`);
-            return { filename, supported: true };
+            return { filename, component, supported: true };
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             return {
                 filename,
+                component,
                 supported: false,
                 reason: message.replace(sourcePath, filename),
+                suggestion: 'Use Workstar runtime compatibility for stateful or third-party components, or simplify this component for source compilation.',
             };
         }
     }));
@@ -88,6 +125,15 @@ export async function auditForeignDirectory(sourceDirectory) {
         total: entries.length,
         supported: entries.filter((entry) => entry.supported).length,
         entries,
+        dependencies: [...dependencyFiles]
+            .map(([name, files]) => ({
+            package: name,
+            files: [...files].sort(),
+            handling: /^(?:react|react-dom|react-router|react-router-dom|vue)$/.test(name)
+                ? 'workstar-runtime-alias'
+                : 'requires-browser-verification',
+        }))
+            .sort((left, right) => left.package.localeCompare(right.package)),
     };
 }
 /** Compile every view before writing any generated modules. */

package/dist/src/runtime-diagnostics.d.ts

@@ -0,0 +1,2 @@
+/** Fail early with file and symbol context for unsupported compatibility APIs. */
+export declare function validateReactRuntimeSource(source: string, filename: string): void;

package/dist/src/runtime-diagnostics.js

@@ -0,0 +1,108 @@
+import ts from 'typescript';
+import { ComponentCompileError } from './errors.js';
+const supported = new Map([
+    [
+        'react',
+        new Set([
+            'Children',
+            'Component',
+            'Fragment',
+            'StrictMode',
+            'Suspense',
+            'cloneElement',
+            'createContext',
+            'createElement',
+            'createRef',
+            'forwardRef',
+            'isValidElement',
+            'lazy',
+            'memo',
+            'useCallback',
+            'useContext',
+            'useDebugValue',
+            'useEffect',
+            'useId',
+            'useImperativeHandle',
+            'useLayoutEffect',
+            'useMemo',
+            'useReducer',
+            'useRef',
+            'useState',
+            'useSyncExternalStore',
+        ]),
+    ],
+    ['react-dom', new Set(['createPortal', 'flushSync'])],
+    ['react-dom/client', new Set(['createRoot', 'hydrateRoot'])],
+    ['react-dom/server', new Set(['renderToStaticMarkup', 'renderToString'])],
+    [
+        'react-router',
+        new Set([
+            'BrowserRouter',
+            'Link',
+            'NavLink',
+            'Navigate',
+            'Outlet',
+            'Route',
+            'Routes',
+            'useLocation',
+            'useNavigate',
+            'useOutletContext',
+            'useParams',
+            'useSearchParams',
+        ]),
+    ],
+]);
+supported.set('react-router-dom', supported.get('react-router'));
+function failUnsupported(sourceFile, node, moduleName, exportName) {
+    const position = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+    throw new ComponentCompileError(`${moduleName} export ${exportName} is not implemented by the Workstar runtime. ` +
+        `Supported exports: ${[...(supported.get(moduleName) ?? [])].join(', ')}.`, sourceFile.fileName, { line: position.line + 1, column: position.character + 1 });
+}
+/** Fail early with file and symbol context for unsupported compatibility APIs. */
+export function validateReactRuntimeSource(source, filename) {
+    if (!/['"]react(?:-dom(?:\/(?:client|server))?|-router(?:-dom)?)?['"]/.test(source))
+        return;
+    const sourceFile = ts.createSourceFile(filename, source, ts.ScriptTarget.Latest, true, /\.[jt]sx$/.test(filename) ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    const namespaces = new Map();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement))
+            continue;
+        const moduleName = ts.isStringLiteral(statement.moduleSpecifier)
+            ? statement.moduleSpecifier.text
+            : '';
+        const exports = supported.get(moduleName);
+        const clause = statement.importClause;
+        if (!exports || !clause || clause.isTypeOnly)
+            continue;
+        if (clause.name) {
+            if (moduleName === 'react' || moduleName === 'react-dom')
+                namespaces.set(clause.name.text, moduleName);
+            else
+                failUnsupported(sourceFile, clause.name, moduleName, 'default');
+        }
+        const bindings = clause.namedBindings;
+        if (bindings && ts.isNamespaceImport(bindings)) {
+            namespaces.set(bindings.name.text, moduleName);
+            continue;
+        }
+        if (!bindings || !ts.isNamedImports(bindings))
+            continue;
+        for (const element of bindings.elements) {
+            if (element.isTypeOnly)
+                continue;
+            const exportName = element.propertyName?.text ?? element.name.text;
+            if (!exports.has(exportName))
+                failUnsupported(sourceFile, element, moduleName, exportName);
+        }
+    }
+    const visit = (node) => {
+        if (ts.isPropertyAccessExpression(node) &&
+            ts.isIdentifier(node.expression)) {
+            const moduleName = namespaces.get(node.expression.text);
+            if (moduleName && !supported.get(moduleName)?.has(node.name.text))
+                failUnsupported(sourceFile, node.name, moduleName, node.name.text);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+}

package/dist/src/vite.js

@@ -6,6 +6,7 @@ import { convertReactRootEntry } from './react-entry-compat.js';
 import { reactComponentExportName } from './react-compat.js';
 import { resolveReactComponentImport } from './react-import-resolution.js';
 import { transpileComponent } from './source-map.js';
+import { validateReactRuntimeSource } from './runtime-diagnostics.js';
 /** Compile authored components as Vite modules without writing into src. */
 export function workstar(options = {}) {
     let sourceDirectory;
@@ -78,6 +79,9 @@ export function workstar(options = {}) {
                 ? `${runtime}/client.js`
                 : `${runtime}/client`;
             const dom = isAbsolute(runtime) ? `${runtime}/dom.js` : `${runtime}/dom`;
+            const server = isAbsolute(runtime)
+                ? `${runtime}/server.js`
+                : `${runtime}/server`;
             const router = isAbsolute(runtime)
                 ? resolve(runtime, '../react-router/index.js')
                 : 'workstar/compat/react-router';
@@ -88,7 +92,9 @@ export function workstar(options = {}) {
                 },
                 resolve: {
                     alias: [
+                        { find: /^react-router-dom$/, replacement: router },
                         { find: /^react-router$/, replacement: router },
+                        { find: /^react-dom\/server$/, replacement: server },
                         { find: /^react-dom\/client$/, replacement: client },
                         { find: /^react-dom$/, replacement: dom },
                         { find: /^react\/jsx-dev-runtime$/, replacement: jsxDevRuntime },
@@ -139,6 +145,8 @@ export function workstar(options = {}) {
         },
         transform(source, id) {
             const filename = id.split('?', 1)[0];
+            if (options.foreign === 'runtime' && /\.[cm]?[jt]sx?$/.test(filename))
+                validateReactRuntimeSource(source, filename);
             if (options.foreign === 'automatic' && isForeignSource(filename)) {
                 const entry = filename.endsWith('.tsx')
                     ? convertReactRootEntry(source, filename)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workstar-compiler",
-  "version": "0.2.4-beta.0",
+  "version": "0.2.4-beta.2",
   "description": "Component compiler and Vite plugin for Workstar applications.",
   "type": "module",
   "license": "MIT",