@motifx/compiler 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Ekrem Erşahin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# @motifx/compiler
+
+The JSX compiler for [MotifJS](https://www.npmjs.com/package/@motifx/core). It lowers JSX at build time into fine-grained reactive bindings on real DOM nodes: `{state.name}` becomes a binding on that one text node, not a re-rendered tree.
+
+It ships as a Vite plugin (also usable in Rollup) and two command-line tools.
+
+## Install
+
+```bash
+npm install -D @motifx/compiler typescript
+```
+
+## Vite
+
+```ts
+import { defineConfig } from 'vite';
+import compiler from '@motifx/compiler';
+
+export default defineConfig({
+    plugins: [compiler()],
+    esbuild: { jsx: 'preserve' },
+});
+```
+
+Set `"jsx": "preserve"` in `tsconfig.json` as well, so that only `@motifx/compiler` compiles JSX. Vitest picks up the same plugin from the Vite config.
+
+## Rollup
+
+The same plugin works in a plain Rollup build:
+
+```js
+import compiler from '@motifx/compiler';
+
+export default {
+    input: 'src/index.tsx',
+    output: { dir: 'dist', format: 'esm' },
+    plugins: [compiler()],
+};
+```
+
+## Which files are compiled
+
+Files ending in `.tsx`, `.jsx`, `.mtsx`, `.mjsx` or `.aio`. In `.ts`, `.mts`, `.cts`, `.js`, `.mjs` and `.cjs` files that contain decorators, only the standard (TC39) decorators are compiled, so `@Injectable` behaves the same in every file in `vite dev` and `vite build`. Files whose nearest `tsconfig.json` enables `experimentalDecorators`, `.d.ts` files and files under `node_modules` are left to Vite. Imports with a `?raw`, `?url`, `?worker`, `?sharedworker` or `?inline` query and virtual modules are left untouched.
+
+## Options
+
+```ts
+compiler({
+    diagnostics: true,
+    explain: false,
+});
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `diagnostics` | `true` | Print compiler warnings (`MJX001`–`MJX004`, `MJX007`) for patterns that compile but do not behave as they read. |
+| `explain` | `false` | Print what every JSX expression was lowered to. `true` for all files, or a string / `RegExp` matched against the file path. |
+
+## Command-line tools
+
+```bash
+npx motif-lint [--project tsconfig.json] [--json] [--no-fail] [file.tsx …]
+```
+
+Type-aware lint (`MJX005`): reports a ternary passed to a component prop whose declared type does not accept a getter. Exits with code 1 when there are findings (`--no-fail` to disable).
+
+```bash
+npx motif-explain src/App.tsx [more.tsx …] [--json] [--site child|attr|prop|…] [--code]
+```
+
+Shows the call each JSX expression compiles to, whether it is reactive, and what it depends on. `--code` also prints the full generated code.
+
+Both tools are also available as functions: `lintProject`, `lintProgram`, `explain`, `printDiagnostics`, `printExplanations`, `formatExplanations`.
+
+## Exports
+
+The default export is the plugin function. Named exports: `Compiler` (`new Compiler().start(code, filename)` returns the Babel result, with `diagnostics` on the instance), `explain`, `lintProject`, `lintProgram`, `printDiagnostics`, `printExplanations`, `formatExplanations`, and the types `MotifVitePluginOptions`, `MotifDiagnostic`, `MotifExplanation`, `ExplainSite`, `ExplainReactivity` and `LintOptions`.
+
+## Runtime contract
+
+Compiled code calls into the `@motifx/core` runtime:
+
+- the `motifComponent`, `motifFragment`, `FNComponent`, `motifCompiled`, `asyncTracking` and `Component` exports;
+- component members: `bindings.*` (each binding directive `x-wait`, `x-display`, `x-model`, `x-text`, `x-html`, `x-value` and `x-watch` calls the method of the same name), `class.add`, `attr.add`, `style`, `motif.on`, `controls.add`, `setText`, and `navigate` on the frame passed to conditional branches;
+- property keys: `runover`, `initializeComponent`, `preconfig`, `ref`, `childs`, `__childExpr`, `__isSvgElement`, `onRefCreated`, the lifecycle hook props that lifecycle directives become (`x-mounted` becomes `onmounted`), and the static class fields `elementTag` and `elementNamespace`.
+
+This set is the compiler contract. It changes only in a major version, so `@motifx/compiler` 1.x works with any `@motifx/core` 1.x. Every compiled module calls `motifCompiled(<contract>)` once; in development the runtime warns with `MJX121` when the numbers differ, for example when a package that ships compiled JSX was built for another major version. The call is marked pure, so production builds drop it.
+
+## License
+
+[MIT](./LICENSE)

package/bin/motif-explain.cjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/*
+ * motif-explain — "what did this expression compile to?" (the compiler's -S flag)
+ *
+ *   npx motif-explain src/App.tsx [more.tsx…] [--json] [--site child|attr|prop|…] [--code]
+ *
+ * Compiles the source and prints, for every JSX expression, the actual call it lowers to,
+ * its reactivity class and its dependency surface. `--code` also prints the full generated code.
+ */
+const fs = require('fs');
+const path = require('path');
+const compiler = require('../dist/index.cjs');
+
+const args = process.argv.slice(2);
+const files = [];
+let json = false, code = false, site = null;
+for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--json') json = true;
+    else if (a === '--code') code = true;
+    else if (a === '--site') site = args[++i];
+    else if (a === '-h' || a === '--help') { console.log(fs.readFileSync(__filename, 'utf8').split('*/')[0]); process.exit(0); }
+    else files.push(a);
+}
+if (files.length === 0) {
+    console.error('usage: motif-explain <file.tsx> [...] [--json] [--site child|attr|prop|event|directive] [--code]');
+    process.exit(2);
+}
+
+const Compiler = compiler.Compiler;
+const all = [];
+for (const f of files) {
+    const abs = path.resolve(f);
+    const src = fs.readFileSync(abs, 'utf8');
+    const c = new Compiler();
+    const shown = path.relative(process.cwd(), abs).split(path.sep).join('/');
+    const result = c.explain(src, shown);
+    let list = c.explanations;
+    if (site) list = list.filter(e => e.site === site);
+    all.push(...list);
+    if (!json) {
+        process.stdout.write(compiler.formatExplanations(list) + '\n');
+        if (c.diagnostics.length) compiler.printDiagnostics(c.diagnostics);
+        if (code && result && result.code) process.stdout.write('\n--- generated code ---\n' + result.code + '\n');
+    }
+}
+if (json) process.stdout.write(JSON.stringify(all, null, 2) + '\n');

package/bin/motif-lint.cjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/*
+ * motif-lint — type-aware JSX check (MJX005: ternary passed to a prop that is not Bind<T>)
+ *
+ *   npx motif-lint [--project tsconfig.json] [--json] [--no-fail] [file.tsx …]
+ *
+ * Builds the TypeScript program and reports a ternary written to a component prop whose
+ * declared type does not accept a function (the compiler always wraps a ternary in a getter).
+ * Exits with code 1 when there are findings (0 with `--no-fail`).
+ */
+const compiler = require('../dist/index.cjs');
+
+const args = process.argv.slice(2);
+let project = 'tsconfig.json', json = false, fail = true;
+const files = [];
+for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--project' || a === '-p') project = args[++i];
+    else if (a === '--json') json = true;
+    else if (a === '--no-fail') fail = false;
+    else if (a === '-h' || a === '--help') { console.log(require('fs').readFileSync(__filename, 'utf8').split('*/')[0]); process.exit(0); }
+    else files.push(a);
+}
+
+const t0 = Date.now();
+const list = compiler.lintProject({ project, files: files.length ? files : undefined });
+if (json) {
+    process.stdout.write(JSON.stringify(list, null, 2) + '\n');
+} else {
+    compiler.printDiagnostics(list);
+    console.error(`[motifjs] lint: ${list.length} findings (${Date.now() - t0} ms)`);
+}
+process.exit(list.length && fail ? 1 : 0);