@jay-framework/compiler-jay-stack 0.9.0

package/README.md

@@ -0,0 +1,252 @@
+# @jay-framework/compiler-jay-stack
+
+Vite/Rollup plugin for Jay Stack that provides **bidirectional code splitting** between client and server environments.
+
+## What It Does
+
+This plugin automatically splits Jay Stack component builder chains into environment-specific code:
+
+- **Client builds**: Strips server-only code (`withServices`, `withLoadParams`, `withSlowlyRender`, `withFastRender`)
+- **Server builds**: Strips client-only code (`withInteractive`, `withContexts`)
+
+This prevents:
+
+- ❌ Server secrets leaking to client bundles
+- ❌ Browser APIs crashing Node.js server
+- ❌ Unnecessary code bloat in both environments
+
+## Installation
+
+```bash
+yarn add -D @jay-framework/compiler-jay-stack
+```
+
+## Usage
+
+### For Jay Stack Applications
+
+Replace `jayRuntime()` with `jayStackCompiler()`:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { jayStackCompiler } from '@jay-framework/compiler-jay-stack';
+
+export default defineConfig({
+  plugins: [
+    ...jayStackCompiler({
+      tsConfigFilePath: './tsconfig.json',
+    }),
+  ],
+});
+```
+
+The plugin internally composes the `jay:runtime` plugin, so you only need one import.
+
+### For Jay Stack Packages (Reusable Components)
+
+Build both server and client bundles:
+
+```typescript
+// vite.config.ts for a Jay Stack package
+import { resolve } from 'path';
+import { defineConfig } from 'vitest/config';
+import { jayStackCompiler, JayRollupConfig } from '@jay-framework/compiler-jay-stack';
+
+const jayOptions: JayRollupConfig = {
+  tsConfigFilePath: resolve(__dirname, 'tsconfig.json'),
+};
+
+export default defineConfig({
+  plugins: [...jayStackCompiler(jayOptions)],
+  build: {
+    lib: {
+      entry: {
+        // Server build (client code stripped)
+        index: resolve(__dirname, 'lib/index.ts?jay-server'),
+        // Client build (server code stripped)
+        'index.client': resolve(__dirname, 'lib/index.ts?jay-client'),
+      },
+      formats: ['es'],
+    },
+  },
+});
+```
+
+Update `package.json` exports:
+
+```json
+{
+  "exports": {
+    ".": "./dist/index.js",
+    "./client": "./dist/index.client.js"
+  }
+}
+```
+
+## How It Works
+
+### Query Parameters
+
+- `?jay-client` - Transform file to client-only code
+- `?jay-server` - Transform file to server-only code
+- No query - Use original code (not recommended for Jay Stack components)
+
+### Example Transformation
+
+**Input (page.ts):**
+
+```typescript
+import { DATABASE } from './database';
+import { Interactive } from './interactive';
+
+export const page = makeJayStackComponent()
+  .withServices(DATABASE)
+  .withSlowlyRender(async () => {
+    /* ... */
+  })
+  .withInteractive(Interactive);
+```
+
+**Server Build (`?jay-server`):**
+
+```typescript
+import { DATABASE } from './database';
+
+export const page = makeJayStackComponent()
+  .withServices(DATABASE)
+  .withSlowlyRender(async () => {
+    /* ... */
+  });
+// ✅ No withInteractive - prevents browser API crashes
+```
+
+**Client Build (`?jay-client`):**
+
+```typescript
+import { Interactive } from './interactive';
+
+export const page = makeJayStackComponent().withInteractive(Interactive);
+// ✅ No server code - smaller bundle, no secrets
+```
+
+## Method Classification
+
+| Method               | Server | Client | Shared |
+| -------------------- | ------ | ------ | ------ |
+| `withProps()`        | ✅     | ✅     | ✅     |
+| `withServices()`     | ✅     | ❌     |        |
+| `withContexts()`     | ❌     | ✅     |        |
+| `withLoadParams()`   | ✅     | ❌     |        |
+| `withSlowlyRender()` | ✅     | ❌     |        |
+| `withFastRender()`   | ✅     | ❌     |        |
+| `withInteractive()`  | ❌     | ✅     |        |
+
+## Architecture
+
+This plugin is a composite of two plugins:
+
+1. **jay-stack:code-split** (runs first, `enforce: 'pre'`)
+
+   - Strips environment-specific builder methods
+   - Removes unused imports
+   - Uses TypeScript AST transformation
+
+2. **jay:runtime** (runs second)
+   - Handles `.jay-html` and `.jay-contract` compilation
+   - Standard Jay runtime compilation
+
+## Benefits
+
+### For Developers
+
+- ✅ Write components in one place
+- ✅ Full TypeScript type safety
+- ✅ No manual code organization needed
+
+### For Applications
+
+- ✅ Prevents runtime crashes (no browser APIs on server)
+- ✅ Smaller client bundles (no server code)
+- ✅ Smaller server bundles (no client code)
+- ✅ Better security (server secrets can't leak)
+
+### For Package Authors
+
+- ✅ One plugin handles both builds
+- ✅ Standard npm export patterns
+- ✅ Automatic optimization for consumers
+
+## Migration
+
+### From `jayRuntime()`
+
+```diff
+- import { jayRuntime } from '@jay-framework/vite-plugin';
++ import { jayStackCompiler } from '@jay-framework/compiler-jay-stack';
+
+export default defineConfig({
+  plugins: [
+-   jayRuntime(config),
++   ...jayStackCompiler(config),
+  ],
+});
+```
+
+### Package.json Dependencies
+
+```diff
+{
+  "dependencies": {
+-   "@jay-framework/vite-plugin": "workspace:^",
++   "@jay-framework/compiler-jay-stack": "workspace:^",
+  }
+}
+```
+
+## Technical Details
+
+### AST Transformation
+
+The plugin uses:
+
+- `SourceFileBindingResolver` - Tracks identifier origins
+- `SourceFileStatementDependencies` - Builds dependency graph
+- TypeScript compiler API - Safe AST transformations
+
+These utilities are battle-tested from Jay's security transformations.
+
+### Import Detection
+
+For headless components:
+
+- **Local files** (`./`, `../`): Use `?jay-client` query
+- **npm packages**: Use `/client` export path
+
+Example:
+
+```typescript
+// Local component
+import { comp } from './my-component?jay-client';
+
+// npm package
+import { comp } from 'my-plugin/client';
+```
+
+## Debugging
+
+If transformation fails, check:
+
+1. Are you using method chaining? (Conditional composition not supported yet)
+2. Are your imports used elsewhere? (They won't be removed)
+3. Check console for transformation errors
+
+## See Also
+
+- [Design Log #52](../../../design-log/52%20-%20jay-stack%20client-server%20code%20splitting.md) - Full design documentation
+- [@jay-framework/fullstack-component](../full-stack-component/README.md) - Jay Stack component builder
+- [@jay-framework/dev-server](../dev-server/README.md) - Jay Stack dev server
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import { Plugin } from 'vite';
+import { JayRollupConfig } from '@jay-framework/vite-plugin';
+export { JayRollupConfig } from '@jay-framework/vite-plugin';
+
+type BuildEnvironment = 'client' | 'server';
+/**
+ * Transform Jay Stack component builder chains to strip environment-specific code
+ *
+ * @param code - Source code to transform
+ * @param filePath - File path (for source file creation)
+ * @param environment - Target environment ('client' or 'server')
+ * @returns Transformed code
+ */
+declare function transformJayStackBuilder(code: string, filePath: string, environment: BuildEnvironment): {
+    code: string;
+    map?: any;
+};
+
+/**
+ * Jay Stack Compiler - Handles both Jay runtime compilation and Jay Stack code splitting
+ *
+ * This plugin internally uses the jay:runtime plugin and adds Jay Stack-specific
+ * transformations for client/server code splitting.
+ *
+ * Usage:
+ * ```typescript
+ * import { jayStackCompiler } from '@jay-framework/compiler-jay-stack';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     ...jayStackCompiler({ tsConfigFilePath: './tsconfig.json' })
+ *   ]
+ * });
+ * ```
+ *
+ * @param jayOptions - Configuration for Jay runtime (passed to jay:runtime plugin)
+ * @returns Array of Vite plugins [codeSplitPlugin, jayRuntimePlugin]
+ */
+declare function jayStackCompiler(jayOptions?: JayRollupConfig): Plugin[];
+
+export { type BuildEnvironment, jayStackCompiler, transformJayStackBuilder };

package/dist/index.js

@@ -0,0 +1,300 @@
+import { jayRuntime } from "@jay-framework/vite-plugin";
+import tsBridge from "@jay-framework/typescript-bridge";
+import { flattenVariable, isImportModuleVariableRoot, mkTransformer, SourceFileBindingResolver, areFlattenedAccessChainsEqual } from "@jay-framework/compiler";
+const SERVER_METHODS = /* @__PURE__ */ new Set([
+  "withServices",
+  "withLoadParams",
+  "withSlowlyRender",
+  "withFastRender"
+]);
+const CLIENT_METHODS = /* @__PURE__ */ new Set([
+  "withInteractive",
+  "withContexts"
+]);
+function shouldRemoveMethod(methodName, environment) {
+  return environment === "client" && SERVER_METHODS.has(methodName) || environment === "server" && CLIENT_METHODS.has(methodName);
+}
+const { isCallExpression: isCallExpression$1, isPropertyAccessExpression: isPropertyAccessExpression$1, isIdentifier: isIdentifier$2, isStringLiteral } = tsBridge;
+function findBuilderMethodsToRemove(sourceFile, bindingResolver, environment) {
+  const callsToRemove = [];
+  const removedVariables = /* @__PURE__ */ new Set();
+  const visit = (node) => {
+    if (isCallExpression$1(node) && isPropertyAccessExpression$1(node.expression) && isPartOfJayStackChain(node, bindingResolver)) {
+      const methodName = node.expression.name.text;
+      if (shouldRemoveMethod(methodName, environment)) {
+        const variable = bindingResolver.explain(node.expression);
+        const flattened = flattenVariable(variable);
+        callsToRemove.push(flattened);
+        collectVariablesFromArguments(node.arguments, bindingResolver, removedVariables);
+      }
+    }
+    node.forEachChild(visit);
+  };
+  sourceFile.forEachChild(visit);
+  return { callsToRemove, removedVariables };
+}
+function isPartOfJayStackChain(callExpr, bindingResolver) {
+  let current = callExpr.expression;
+  while (true) {
+    if (isPropertyAccessExpression$1(current)) {
+      current = current.expression;
+    } else if (isCallExpression$1(current)) {
+      if (isIdentifier$2(current.expression)) {
+        const variable = bindingResolver.explain(current.expression);
+        const flattened = flattenVariable(variable);
+        if (flattened.path.length === 1 && flattened.path[0] === "makeJayStackComponent" && isImportModuleVariableRoot(flattened.root) && isStringLiteral(flattened.root.module) && flattened.root.module.text === "@jay-framework/fullstack-component")
+          return true;
+      }
+      if (isPropertyAccessExpression$1(current.expression)) {
+        current = current.expression.expression;
+        continue;
+      } else {
+        break;
+      }
+    } else {
+      break;
+    }
+  }
+  return false;
+}
+function collectVariablesFromArguments(args, bindingResolver, variables) {
+  const visitor = (node) => {
+    if (isIdentifier$2(node)) {
+      const variable = bindingResolver.explain(node);
+      if (variable && (variable.name || variable.root)) {
+        variables.add(variable);
+      }
+    }
+    node.forEachChild(visitor);
+  };
+  args.forEach((arg) => visitor(arg));
+}
+const {
+  isIdentifier: isIdentifier$1,
+  isImportDeclaration: isImportDeclaration$1,
+  isFunctionDeclaration: isFunctionDeclaration$1,
+  isVariableStatement: isVariableStatement$1,
+  isInterfaceDeclaration: isInterfaceDeclaration$1,
+  isTypeAliasDeclaration: isTypeAliasDeclaration$1,
+  isClassDeclaration,
+  isEnumDeclaration,
+  SyntaxKind
+} = tsBridge;
+function analyzeUnusedStatements(sourceFile, bindingResolver) {
+  const statementsToRemove = /* @__PURE__ */ new Set();
+  const collectUsedIdentifiers = () => {
+    const used = /* @__PURE__ */ new Set();
+    for (const statement of sourceFile.statements) {
+      if (isImportDeclaration$1(statement) || statementsToRemove.has(statement)) {
+        continue;
+      }
+      const definedName = getStatementDefinedName(statement);
+      const visitor = (node, parent) => {
+        if (isIdentifier$1(node)) {
+          if (node.text !== definedName) {
+            used.add(node.text);
+          }
+        }
+        node.forEachChild((child) => visitor(child));
+      };
+      statement.forEachChild((child) => visitor(child));
+    }
+    return used;
+  };
+  let changed = true;
+  while (changed) {
+    changed = false;
+    const stillUsedIdentifiers = collectUsedIdentifiers();
+    for (const statement of sourceFile.statements) {
+      if (statementsToRemove.has(statement) || isImportDeclaration$1(statement) || isExportStatement(statement)) {
+        continue;
+      }
+      const definedName = getStatementDefinedName(statement);
+      if (definedName && !stillUsedIdentifiers.has(definedName)) {
+        statementsToRemove.add(statement);
+        changed = true;
+      }
+    }
+  }
+  const finalUsedIdentifiers = collectUsedIdentifiers();
+  const unusedImports = /* @__PURE__ */ new Set();
+  for (const statement of sourceFile.statements) {
+    if (isImportDeclaration$1(statement) && statement.importClause?.namedBindings) {
+      const namedBindings = statement.importClause.namedBindings;
+      if ("elements" in namedBindings) {
+        for (const element of namedBindings.elements) {
+          const importName = element.name.text;
+          if (!finalUsedIdentifiers.has(importName)) {
+            unusedImports.add(importName);
+          }
+        }
+      }
+    }
+  }
+  return { statementsToRemove, unusedImports };
+}
+function isExportStatement(statement) {
+  const modifiers = "modifiers" in statement ? statement.modifiers : void 0;
+  if (modifiers) {
+    return modifiers.some((mod) => mod.kind === SyntaxKind.ExportKeyword);
+  }
+  return false;
+}
+function getStatementDefinedName(statement) {
+  if (isFunctionDeclaration$1(statement) && statement.name) {
+    return statement.name.text;
+  }
+  if (isVariableStatement$1(statement)) {
+    const firstDecl = statement.declarationList.declarations[0];
+    if (firstDecl && isIdentifier$1(firstDecl.name)) {
+      return firstDecl.name.text;
+    }
+  }
+  if (isInterfaceDeclaration$1(statement) && statement.name) {
+    return statement.name.text;
+  }
+  if (isTypeAliasDeclaration$1(statement) && statement.name) {
+    return statement.name.text;
+  }
+  if (isClassDeclaration(statement) && statement.name) {
+    return statement.name.text;
+  }
+  if (isEnumDeclaration(statement) && statement.name) {
+    return statement.name.text;
+  }
+  return void 0;
+}
+const {
+  createPrinter,
+  createSourceFile,
+  ScriptTarget,
+  visitEachChild,
+  isCallExpression,
+  isPropertyAccessExpression,
+  isImportDeclaration,
+  isNamedImports,
+  isIdentifier,
+  isFunctionDeclaration,
+  isVariableStatement,
+  isInterfaceDeclaration,
+  isTypeAliasDeclaration
+} = tsBridge;
+function transformJayStackBuilder(code, filePath, environment) {
+  const sourceFile = createSourceFile(
+    filePath,
+    code,
+    ScriptTarget.Latest,
+    true
+  );
+  const transformers = [mkTransformer(mkJayStackCodeSplitTransformer, { environment })];
+  const printer = createPrinter();
+  const result = tsBridge.transform(sourceFile, transformers);
+  const transformedFile = result.transformed[0];
+  const transformedCode = printer.printFile(transformedFile);
+  result.dispose();
+  return {
+    code: transformedCode
+  };
+}
+function isCallToRemove(flattened, callsToRemove) {
+  return callsToRemove.some((call) => areFlattenedAccessChainsEqual(flattened, call));
+}
+function mkJayStackCodeSplitTransformer({
+  factory,
+  sourceFile,
+  context,
+  environment
+}) {
+  const bindingResolver = new SourceFileBindingResolver(sourceFile);
+  const { callsToRemove, removedVariables } = findBuilderMethodsToRemove(
+    sourceFile,
+    bindingResolver,
+    environment
+  );
+  const transformVisitor = (node) => {
+    if (isCallExpression(node) && isPropertyAccessExpression(node.expression)) {
+      const variable = bindingResolver.explain(node.expression);
+      const flattened = flattenVariable(variable);
+      if (isCallToRemove(flattened, callsToRemove)) {
+        const receiver = node.expression.expression;
+        return transformVisitor(receiver);
+      }
+    }
+    return visitEachChild(node, transformVisitor, context);
+  };
+  let transformedSourceFile = visitEachChild(sourceFile, transformVisitor, context);
+  new SourceFileBindingResolver(transformedSourceFile);
+  const { statementsToRemove, unusedImports } = analyzeUnusedStatements(
+    transformedSourceFile
+  );
+  const transformedStatements = transformedSourceFile.statements.map((statement) => {
+    if (statementsToRemove.has(statement)) {
+      return void 0;
+    }
+    if (isImportDeclaration(statement)) {
+      return filterImportDeclaration(statement, unusedImports, factory);
+    }
+    return statement;
+  }).filter((s) => s !== void 0);
+  return factory.updateSourceFile(transformedSourceFile, transformedStatements);
+}
+function filterImportDeclaration(statement, unusedImports, factory) {
+  const importClause = statement.importClause;
+  if (!importClause?.namedBindings || !isNamedImports(importClause.namedBindings)) {
+    return statement;
+  }
+  const usedElements = importClause.namedBindings.elements.filter(
+    (element) => !unusedImports.has(element.name.text)
+  );
+  if (usedElements.length === 0) {
+    return void 0;
+  }
+  return factory.updateImportDeclaration(
+    statement,
+    statement.modifiers,
+    factory.updateImportClause(
+      importClause,
+      importClause.isTypeOnly,
+      importClause.name,
+      factory.updateNamedImports(
+        importClause.namedBindings,
+        usedElements
+      )
+    ),
+    statement.moduleSpecifier,
+    statement.assertClause
+  );
+}
+function jayStackCompiler(jayOptions = {}) {
+  return [
+    // First: Jay Stack code splitting transformation
+    {
+      name: "jay-stack:code-split",
+      enforce: "pre",
+      // Run before jay:runtime
+      transform(code, id) {
+        const isClientBuild = id.includes("?jay-client");
+        const isServerBuild = id.includes("?jay-server");
+        if (!isClientBuild && !isServerBuild) {
+          return null;
+        }
+        const environment = isClientBuild ? "client" : "server";
+        if (!id.endsWith(".ts") && !id.includes(".ts?")) {
+          return null;
+        }
+        try {
+          return transformJayStackBuilder(code, id, environment);
+        } catch (error) {
+          console.error(`[jay-stack:code-split] Error transforming ${id}:`, error);
+          return null;
+        }
+      }
+    },
+    // Second: Jay runtime compilation (existing plugin)
+    jayRuntime(jayOptions)
+  ];
+}
+export {
+  jayStackCompiler,
+  transformJayStackBuilder
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@jay-framework/compiler-jay-stack",
+  "version": "0.9.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "npm run build:js && npm run build:types",
+    "build:watch": "npm run build:js -- --watch & npm run build:types -- --watch",
+    "build:js": "vite build",
+    "build:types": "tsup lib/index.ts --dts-only --format esm",
+    "build:check-types": "tsc",
+    "clean": "rimraf dist",
+    "confirm": "npm run clean && npm run build && npm run build:check-types && npm run test",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@jay-framework/compiler": "^0.9.0",
+    "@jay-framework/typescript-bridge": "^0.4.0",
+    "@jay-framework/vite-plugin": "^0.9.0",
+    "vite": "^5.0.11"
+  },
+  "devDependencies": {
+    "@jay-framework/dev-environment": "^0.9.0",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.1"
+  }
+}