@knighted/jsx 1.9.2 → 1.10.0

package/README.md

@@ -68,39 +68,52 @@ const button = jsx`
 document.body.append(button)
 ```
 
-### Source transpilation (`transpileJsxSource`)
+### Source transpilation (`transpileJsxSource` + `transformJsxSource`)
 
-Need to transform raw JSX source text (e.g. code typed in an editor) without Babel? Use `transpileJsxSource`:
+Need to transform raw JSX source text (for example, code typed in an editor) without Babel?
+Use one of these subpath exports:
+
+- `@knighted/jsx/transpile` for code-only output (`{ code, changed }`).
+- `@knighted/jsx/transform` for code plus parser-backed import metadata and diagnostics
+  (`{ code, changed, imports, diagnostics }`).
 
 ```ts
 import { transpileJsxSource } from '@knighted/jsx/transpile'
+import { transformJsxSource } from '@knighted/jsx/transform'
 
 const input = `
-const App = () => {
-  return <button>click me</button>
-}
+import React from 'react'
+const App = () => <button>click me</button>
 `
 
-const { code } = transpileJsxSource(input)
-// -> const App = () => { return React.createElement("button", null, "click me") }
+const transpiled = transpileJsxSource(input)
+// -> { code, changed }
+
+const transformed = transformJsxSource(input, { typescript: 'strip' })
+// -> { code, changed, imports, diagnostics }
 ```
 
-By default this emits `React.createElement(...)` and `React.Fragment`. Override them when needed:
+Both entrypoints emit `React.createElement(...)` and `React.Fragment` by default. Override
+them when needed:
 
 ```ts
 transpileJsxSource(input, {
   createElement: '__jsx',
   fragment: '__fragment',
 })
+
+transformJsxSource(input, {
+  createElement: '__jsx',
+  fragment: '__fragment',
+})
 ```
 
-By default, TypeScript syntax is preserved in the output. If your source needs to run directly
-as JavaScript (for example, code entered in an editor), enable type stripping:
+By default, TypeScript syntax is preserved in output. If your source needs to run directly as
+JavaScript, enable type stripping:
 
 ```ts
-transpileJsxSource(input, {
-  typescript: 'strip',
-})
+transpileJsxSource(input, { typescript: 'strip' })
+transformJsxSource(input, { typescript: 'strip' })
 ```
 
 Supported `typescript` modes:
@@ -109,6 +122,13 @@ Supported `typescript` modes:
 - `'strip'`: remove type-only declarations and erase inline type syntax (`: T`, `as T`,
   `satisfies T`, non-null assertions, and type assertions) while still transpiling JSX.
 
+Environment note:
+
+- Both APIs are ESM-first and work in Node.
+- For direct browser usage of `@knighted/jsx/transform`, use a CDN/runtime that can resolve
+  `oxc-transform` for the browser build (for example, modern ESM CDNs that bundle or map
+  WASM/native bindings automatically).
+
 ### React runtime (`reactJsx`)
 
 Need to compose React elements instead of DOM nodes? Import the dedicated helper from the `@knighted/jsx/react` subpath (React 18+ and `react-dom` are still required to mount the tree):

package/dist/cjs/transform.cjs

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transformJsxSource = transformJsxSource;
+const oxc_parser_1 = require("oxc-parser");
+const oxc_transform_1 = require("oxc-transform");
+const transpile_js_1 = require("./transpile.cjs");
+const createParserOptions = (sourceType) => ({
+    lang: 'tsx',
+    sourceType,
+    range: true,
+    preserveParens: true,
+});
+const isObjectRecord = (value) => typeof value === 'object' && value !== null;
+const isSourceRange = (value) => Array.isArray(value) &&
+    value.length === 2 &&
+    typeof value[0] === 'number' &&
+    typeof value[1] === 'number';
+const toSourceRange = (value) => {
+    if (!isObjectRecord(value) || !isSourceRange(value.range)) {
+        return null;
+    }
+    return value.range;
+};
+const asImportKind = (value) => value === 'type' ? 'type' : 'value';
+const toDiagnostic = (source, diagnostic) => {
+    const firstLabel = diagnostic.labels?.[0];
+    const range = firstLabel &&
+        typeof firstLabel.start === 'number' &&
+        typeof firstLabel.end === 'number'
+        ? [firstLabel.start, firstLabel.end]
+        : null;
+    return {
+        source,
+        severity: diagnostic.severity,
+        message: diagnostic.message,
+        range,
+        codeframe: diagnostic.codeframe,
+        helpMessage: diagnostic.helpMessage,
+    };
+};
+const toImportBinding = (specifier, declarationImportKind) => {
+    if (!isObjectRecord(specifier) || typeof specifier.type !== 'string') {
+        return null;
+    }
+    if (specifier.type === 'ImportDefaultSpecifier') {
+        const localName = isObjectRecord(specifier.local) && typeof specifier.local.name === 'string'
+            ? specifier.local.name
+            : null;
+        if (!localName) {
+            return null;
+        }
+        return {
+            kind: 'default',
+            local: localName,
+            imported: 'default',
+            isTypeOnly: declarationImportKind === 'type',
+            range: toSourceRange(specifier),
+        };
+    }
+    if (specifier.type === 'ImportNamespaceSpecifier') {
+        const localName = isObjectRecord(specifier.local) && typeof specifier.local.name === 'string'
+            ? specifier.local.name
+            : null;
+        if (!localName) {
+            return null;
+        }
+        return {
+            kind: 'namespace',
+            local: localName,
+            imported: '*',
+            isTypeOnly: declarationImportKind === 'type',
+            range: toSourceRange(specifier),
+        };
+    }
+    if (specifier.type === 'ImportSpecifier') {
+        const importedName = isObjectRecord(specifier.imported) && typeof specifier.imported.name === 'string'
+            ? specifier.imported.name
+            : null;
+        const localName = isObjectRecord(specifier.local) && typeof specifier.local.name === 'string'
+            ? specifier.local.name
+            : null;
+        if (!importedName || !localName) {
+            return null;
+        }
+        return {
+            kind: 'named',
+            local: localName,
+            imported: importedName,
+            isTypeOnly: declarationImportKind === 'type' || asImportKind(specifier.importKind) === 'type',
+            range: toSourceRange(specifier),
+        };
+    }
+    return null;
+};
+const collectImportMetadata = (body) => {
+    if (!Array.isArray(body)) {
+        return [];
+    }
+    const imports = [];
+    body.forEach(statement => {
+        if (!isObjectRecord(statement) ||
+            statement.type !== 'ImportDeclaration' ||
+            !isObjectRecord(statement.source) ||
+            typeof statement.source.value !== 'string') {
+            return;
+        }
+        const importKind = asImportKind(statement.importKind);
+        const bindings = Array.isArray(statement.specifiers)
+            ? statement.specifiers
+                .map(specifier => toImportBinding(specifier, importKind))
+                .filter((binding) => binding !== null)
+            : [];
+        imports.push({
+            source: statement.source.value,
+            importKind,
+            sideEffectOnly: bindings.length === 0 && importKind === 'value',
+            bindings,
+            range: toSourceRange(statement),
+        });
+    });
+    return imports;
+};
+const ensureSupportedOptions = (options) => {
+    if (options.sourceType !== undefined &&
+        options.sourceType !== 'module' &&
+        options.sourceType !== 'script') {
+        throw new Error(`[jsx] Unsupported sourceType "${String(options.sourceType)}". Use "module" or "script".`);
+    }
+    if (options.typescript !== undefined &&
+        options.typescript !== 'preserve' &&
+        options.typescript !== 'strip') {
+        throw new Error(`[jsx] Unsupported typescript mode "${String(options.typescript)}". Use "preserve" or "strip".`);
+    }
+    if (options.typescriptStripBackend !== undefined &&
+        options.typescriptStripBackend !== 'oxc-transform' &&
+        options.typescriptStripBackend !== 'transpile-manual') {
+        throw new Error(`[jsx] Unsupported typescriptStripBackend "${String(options.typescriptStripBackend)}". Use "oxc-transform" or "transpile-manual".`);
+    }
+};
+function transformJsxSource(source, options = {}) {
+    const internalOptions = options;
+    ensureSupportedOptions(internalOptions);
+    const sourceType = internalOptions.sourceType ?? 'module';
+    const typescriptMode = internalOptions.typescript ?? 'preserve';
+    const typescriptStripBackend = internalOptions.typescriptStripBackend ?? 'oxc-transform';
+    const parsed = (0, oxc_parser_1.parseSync)('transform-jsx-source.tsx', source, createParserOptions(sourceType));
+    const parserDiagnostics = parsed.errors.map(error => toDiagnostic('parser', error));
+    const imports = collectImportMetadata(parsed.program.body);
+    if (parserDiagnostics.length) {
+        return {
+            code: source,
+            changed: false,
+            imports,
+            diagnostics: parserDiagnostics,
+        };
+    }
+    const transpileBaseOptions = {
+        sourceType,
+        createElement: internalOptions.createElement,
+        fragment: internalOptions.fragment,
+        typescript: 'preserve',
+    };
+    if (typescriptMode !== 'strip') {
+        const result = (0, transpile_js_1.transpileJsxSource)(source, transpileBaseOptions);
+        return {
+            code: result.code,
+            changed: result.changed,
+            imports,
+            diagnostics: parserDiagnostics,
+        };
+    }
+    if (typescriptStripBackend === 'transpile-manual') {
+        const result = (0, transpile_js_1.transpileJsxSource)(source, {
+            ...transpileBaseOptions,
+            typescript: 'strip',
+        });
+        return {
+            code: result.code,
+            changed: result.changed,
+            imports,
+            diagnostics: parserDiagnostics,
+        };
+    }
+    const transformed = (0, oxc_transform_1.transformSync)('transform-jsx-source.tsx', source, {
+        lang: 'tsx',
+        sourceType,
+        jsx: 'preserve',
+        typescript: {},
+    });
+    const transformDiagnostics = transformed.errors.map(error => toDiagnostic('transform', error));
+    const diagnostics = [...parserDiagnostics, ...transformDiagnostics];
+    if (transformDiagnostics.length) {
+        const fallbackCode = transformed.code || source;
+        return {
+            code: fallbackCode,
+            changed: fallbackCode !== source,
+            imports,
+            diagnostics,
+        };
+    }
+    const jsxResult = (0, transpile_js_1.transpileJsxSource)(transformed.code, transpileBaseOptions);
+    return {
+        code: jsxResult.code,
+        changed: jsxResult.code !== source,
+        imports,
+        diagnostics,
+    };
+}

package/dist/cjs/transform.d.cts

@@ -0,0 +1,34 @@
+import { type TranspileJsxSourceOptions } from './transpile.cjs';
+type SourceRange = [number, number];
+type DiagnosticSource = 'parser' | 'transform';
+export type TransformDiagnostic = {
+    source: DiagnosticSource;
+    severity: string;
+    message: string;
+    range: SourceRange | null;
+    codeframe: string | null;
+    helpMessage: string | null;
+};
+export type TransformImportBinding = {
+    kind: 'default' | 'named' | 'namespace';
+    local: string;
+    imported: string | null;
+    isTypeOnly: boolean;
+    range: SourceRange | null;
+};
+export type TransformImport = {
+    source: string;
+    importKind: 'type' | 'value';
+    sideEffectOnly: boolean;
+    bindings: TransformImportBinding[];
+    range: SourceRange | null;
+};
+export type TransformJsxSourceOptions = TranspileJsxSourceOptions;
+export type TransformJsxSourceResult = {
+    code: string;
+    changed: boolean;
+    imports: TransformImport[];
+    diagnostics: TransformDiagnostic[];
+};
+export declare function transformJsxSource(source: string, options?: TransformJsxSourceOptions): TransformJsxSourceResult;
+export {};

package/dist/transform.d.ts

@@ -0,0 +1,34 @@
+import { type TranspileJsxSourceOptions } from './transpile.js';
+type SourceRange = [number, number];
+type DiagnosticSource = 'parser' | 'transform';
+export type TransformDiagnostic = {
+    source: DiagnosticSource;
+    severity: string;
+    message: string;
+    range: SourceRange | null;
+    codeframe: string | null;
+    helpMessage: string | null;
+};
+export type TransformImportBinding = {
+    kind: 'default' | 'named' | 'namespace';
+    local: string;
+    imported: string | null;
+    isTypeOnly: boolean;
+    range: SourceRange | null;
+};
+export type TransformImport = {
+    source: string;
+    importKind: 'type' | 'value';
+    sideEffectOnly: boolean;
+    bindings: TransformImportBinding[];
+    range: SourceRange | null;
+};
+export type TransformJsxSourceOptions = TranspileJsxSourceOptions;
+export type TransformJsxSourceResult = {
+    code: string;
+    changed: boolean;
+    imports: TransformImport[];
+    diagnostics: TransformDiagnostic[];
+};
+export declare function transformJsxSource(source: string, options?: TransformJsxSourceOptions): TransformJsxSourceResult;
+export {};

package/dist/transform.js

@@ -0,0 +1,205 @@
+import { parseSync } from 'oxc-parser';
+import { transformSync } from 'oxc-transform';
+import { transpileJsxSource } from './transpile.js';
+const createParserOptions = (sourceType) => ({
+    lang: 'tsx',
+    sourceType,
+    range: true,
+    preserveParens: true,
+});
+const isObjectRecord = (value) => typeof value === 'object' && value !== null;
+const isSourceRange = (value) => Array.isArray(value) &&
+    value.length === 2 &&
+    typeof value[0] === 'number' &&
+    typeof value[1] === 'number';
+const toSourceRange = (value) => {
+    if (!isObjectRecord(value) || !isSourceRange(value.range)) {
+        return null;
+    }
+    return value.range;
+};
+const asImportKind = (value) => value === 'type' ? 'type' : 'value';
+const toDiagnostic = (source, diagnostic) => {
+    const firstLabel = diagnostic.labels?.[0];
+    const range = firstLabel &&
+        typeof firstLabel.start === 'number' &&
+        typeof firstLabel.end === 'number'
+        ? [firstLabel.start, firstLabel.end]
+        : null;
+    return {
+        source,
+        severity: diagnostic.severity,
+        message: diagnostic.message,
+        range,
+        codeframe: diagnostic.codeframe,
+        helpMessage: diagnostic.helpMessage,
+    };
+};
+const toImportBinding = (specifier, declarationImportKind) => {
+    if (!isObjectRecord(specifier) || typeof specifier.type !== 'string') {
+        return null;
+    }
+    if (specifier.type === 'ImportDefaultSpecifier') {
+        const localName = isObjectRecord(specifier.local) && typeof specifier.local.name === 'string'
+            ? specifier.local.name
+            : null;
+        if (!localName) {
+            return null;
+        }
+        return {
+            kind: 'default',
+            local: localName,
+            imported: 'default',
+            isTypeOnly: declarationImportKind === 'type',
+            range: toSourceRange(specifier),
+        };
+    }
+    if (specifier.type === 'ImportNamespaceSpecifier') {
+        const localName = isObjectRecord(specifier.local) && typeof specifier.local.name === 'string'
+            ? specifier.local.name
+            : null;
+        if (!localName) {
+            return null;
+        }
+        return {
+            kind: 'namespace',
+            local: localName,
+            imported: '*',
+            isTypeOnly: declarationImportKind === 'type',
+            range: toSourceRange(specifier),
+        };
+    }
+    if (specifier.type === 'ImportSpecifier') {
+        const importedName = isObjectRecord(specifier.imported) && typeof specifier.imported.name === 'string'
+            ? specifier.imported.name
+            : null;
+        const localName = isObjectRecord(specifier.local) && typeof specifier.local.name === 'string'
+            ? specifier.local.name
+            : null;
+        if (!importedName || !localName) {
+            return null;
+        }
+        return {
+            kind: 'named',
+            local: localName,
+            imported: importedName,
+            isTypeOnly: declarationImportKind === 'type' || asImportKind(specifier.importKind) === 'type',
+            range: toSourceRange(specifier),
+        };
+    }
+    return null;
+};
+const collectImportMetadata = (body) => {
+    if (!Array.isArray(body)) {
+        return [];
+    }
+    const imports = [];
+    body.forEach(statement => {
+        if (!isObjectRecord(statement) ||
+            statement.type !== 'ImportDeclaration' ||
+            !isObjectRecord(statement.source) ||
+            typeof statement.source.value !== 'string') {
+            return;
+        }
+        const importKind = asImportKind(statement.importKind);
+        const bindings = Array.isArray(statement.specifiers)
+            ? statement.specifiers
+                .map(specifier => toImportBinding(specifier, importKind))
+                .filter((binding) => binding !== null)
+            : [];
+        imports.push({
+            source: statement.source.value,
+            importKind,
+            sideEffectOnly: bindings.length === 0 && importKind === 'value',
+            bindings,
+            range: toSourceRange(statement),
+        });
+    });
+    return imports;
+};
+const ensureSupportedOptions = (options) => {
+    if (options.sourceType !== undefined &&
+        options.sourceType !== 'module' &&
+        options.sourceType !== 'script') {
+        throw new Error(`[jsx] Unsupported sourceType "${String(options.sourceType)}". Use "module" or "script".`);
+    }
+    if (options.typescript !== undefined &&
+        options.typescript !== 'preserve' &&
+        options.typescript !== 'strip') {
+        throw new Error(`[jsx] Unsupported typescript mode "${String(options.typescript)}". Use "preserve" or "strip".`);
+    }
+    if (options.typescriptStripBackend !== undefined &&
+        options.typescriptStripBackend !== 'oxc-transform' &&
+        options.typescriptStripBackend !== 'transpile-manual') {
+        throw new Error(`[jsx] Unsupported typescriptStripBackend "${String(options.typescriptStripBackend)}". Use "oxc-transform" or "transpile-manual".`);
+    }
+};
+export function transformJsxSource(source, options = {}) {
+    const internalOptions = options;
+    ensureSupportedOptions(internalOptions);
+    const sourceType = internalOptions.sourceType ?? 'module';
+    const typescriptMode = internalOptions.typescript ?? 'preserve';
+    const typescriptStripBackend = internalOptions.typescriptStripBackend ?? 'oxc-transform';
+    const parsed = parseSync('transform-jsx-source.tsx', source, createParserOptions(sourceType));
+    const parserDiagnostics = parsed.errors.map(error => toDiagnostic('parser', error));
+    const imports = collectImportMetadata(parsed.program.body);
+    if (parserDiagnostics.length) {
+        return {
+            code: source,
+            changed: false,
+            imports,
+            diagnostics: parserDiagnostics,
+        };
+    }
+    const transpileBaseOptions = {
+        sourceType,
+        createElement: internalOptions.createElement,
+        fragment: internalOptions.fragment,
+        typescript: 'preserve',
+    };
+    if (typescriptMode !== 'strip') {
+        const result = transpileJsxSource(source, transpileBaseOptions);
+        return {
+            code: result.code,
+            changed: result.changed,
+            imports,
+            diagnostics: parserDiagnostics,
+        };
+    }
+    if (typescriptStripBackend === 'transpile-manual') {
+        const result = transpileJsxSource(source, {
+            ...transpileBaseOptions,
+            typescript: 'strip',
+        });
+        return {
+            code: result.code,
+            changed: result.changed,
+            imports,
+            diagnostics: parserDiagnostics,
+        };
+    }
+    const transformed = transformSync('transform-jsx-source.tsx', source, {
+        lang: 'tsx',
+        sourceType,
+        jsx: 'preserve',
+        typescript: {},
+    });
+    const transformDiagnostics = transformed.errors.map(error => toDiagnostic('transform', error));
+    const diagnostics = [...parserDiagnostics, ...transformDiagnostics];
+    if (transformDiagnostics.length) {
+        const fallbackCode = transformed.code || source;
+        return {
+            code: fallbackCode,
+            changed: fallbackCode !== source,
+            imports,
+            diagnostics,
+        };
+    }
+    const jsxResult = transpileJsxSource(transformed.code, transpileBaseOptions);
+    return {
+        code: jsxResult.code,
+        changed: jsxResult.code !== source,
+        imports,
+        diagnostics,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/jsx",
-  "version": "1.9.2",
+  "version": "1.10.0",
   "description": "Runtime JSX tagged template that renders DOM or React trees anywhere with or without a build step.",
   "keywords": [
     "jsx runtime",
@@ -106,6 +106,11 @@
       "import": "./dist/transpile.js",
       "default": "./dist/transpile.js"
     },
+    "./transform": {
+      "types": "./dist/transform.d.ts",
+      "import": "./dist/transform.js",
+      "default": "./dist/transform.js"
+    },
     "./loader": {
       "import": "./dist/loader/jsx.js",
       "default": "./dist/loader/jsx.js"
@@ -185,6 +190,7 @@
     "@napi-rs/wasm-runtime": "^1.1.1",
     "magic-string": "^0.30.21",
     "oxc-parser": "^0.116.0",
+    "oxc-transform": "^0.116.0",
     "property-information": "^7.1.0",
     "tar": "^7.5.11"
   },