@llui/compiler-devtools 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Franco Ponticelli
+
+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/dist/component-meta.d.ts

@@ -0,0 +1,3 @@
+import type { CompilerModule } from '@llui/compiler';
+export declare const componentMetaModule: CompilerModule;
+//# sourceMappingURL=component-meta.d.ts.map

package/dist/component-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-meta.d.ts","sourceRoot":"","sources":["../src/component-meta.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,cAAc,EAAwB,MAAM,gBAAgB,CAAA;AAG1E,eAAO,MAAM,mBAAmB,EAAE,cAoCjC,CAAA"}

package/dist/component-meta.js

@@ -0,0 +1,44 @@
+// `component-meta` — emits `__componentMeta: { file, line }` per
+// `component()` call. Today's `injectComponentMeta` in transform.ts
+// is gated on devMode; this module keeps the gating semantics by
+// accepting an option (the umbrella passes `devMode` through).
+//
+// This is the first per-component-targeted emission in the registry.
+// It validates the `EmissionContribution.target` shape (v2c §7.9
+// finding from the schema-hash POC): when multiple `component()`
+// calls live in one file, each gets its own `__componentMeta` with
+// its own line number, and the conflict-detector lets each emission
+// through because the `(field, target)` tuples are distinct.
+import { findComponentCalls } from '@llui/compiler';
+export const componentMetaModule = {
+    name: 'component-meta',
+    compilerVersion: '^0.3.0',
+    diagnostics: [],
+    // Targets captured in `emit` (not `visit`) — see `_shared.ts`
+    // `findComponentCalls` for the rationale (Phase 2b rebuilds
+    // ancestor nodes, invalidating visit-captured refs).
+    visitors: {},
+    emit(ctx, analysis) {
+        const sf = analysis.sourceFile;
+        const calls = findComponentCalls(sf);
+        if (calls.length === 0)
+            return [];
+        const out = [];
+        for (const n of calls) {
+            const pos = n.pos >= 0 ? n.getStart(sf) : 0;
+            const { line } = sf.getLineAndCharacterOfPosition(pos);
+            const meta = ctx.factory.createObjectLiteralExpression([
+                ctx.factory.createPropertyAssignment('file', ctx.factory.createStringLiteral(sf.fileName)),
+                ctx.factory.createPropertyAssignment('line', ctx.factory.createNumericLiteral(line + 1)),
+            ], false);
+            out.push({
+                module: 'component-meta',
+                field: '__componentMeta',
+                value: meta,
+                target: n,
+            });
+        }
+        return out;
+    },
+};
+//# sourceMappingURL=component-meta.js.map

package/dist/component-meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-meta.js","sourceRoot":"","sources":["../src/component-meta.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,oEAAoE;AACpE,iEAAiE;AACjE,+DAA+D;AAC/D,EAAE;AACF,qEAAqE;AACrE,iEAAiE;AACjE,iEAAiE;AACjE,mEAAmE;AACnE,oEAAoE;AACpE,6DAA6D;AAG7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAEnD,MAAM,CAAC,MAAM,mBAAmB,GAAmB;IACjD,IAAI,EAAE,gBAAgB;IACtB,eAAe,EAAE,QAAQ;IACzB,WAAW,EAAE,EAAE;IACf,8DAA8D;IAC9D,4DAA4D;IAC5D,qDAAqD;IACrD,QAAQ,EAAE,EAAE;IAEZ,IAAI,CAAC,GAAG,EAAE,QAAQ;QAChB,MAAM,EAAE,GAAG,QAAQ,CAAC,UAAU,CAAA;QAC9B,MAAM,KAAK,GAAG,kBAAkB,CAAC,EAAE,CAAC,CAAA;QACpC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAA;QACjC,MAAM,GAAG,GAA2B,EAAE,CAAA;QACtC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;YAC3C,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,6BAA6B,CAAC,GAAG,CAAC,CAAA;YACtD,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,6BAA6B,CACpD;gBACE,GAAG,CAAC,OAAO,CAAC,wBAAwB,CAClC,MAAM,EACN,GAAG,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,CAAC,QAAQ,CAAC,CAC7C;gBACD,GAAG,CAAC,OAAO,CAAC,wBAAwB,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,oBAAoB,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;aACzF,EACD,KAAK,CACN,CAAA;YACD,GAAG,CAAC,IAAI,CAAC;gBACP,MAAM,EAAE,gBAAgB;gBACxB,KAAK,EAAE,iBAAiB;gBACxB,KAAK,EAAE,IAAI;gBACX,MAAM,EAAE,CAAC;aACV,CAAC,CAAA;QACJ,CAAC;QACD,OAAO,GAAG,CAAA;IACZ,CAAC;CACF,CAAA","sourcesContent":["// `component-meta` — emits `__componentMeta: { file, line }` per\n// `component()` call. Today's `injectComponentMeta` in transform.ts\n// is gated on devMode; this module keeps the gating semantics by\n// accepting an option (the umbrella passes `devMode` through).\n//\n// This is the first per-component-targeted emission in the registry.\n// It validates the `EmissionContribution.target` shape (v2c §7.9\n// finding from the schema-hash POC): when multiple `component()`\n// calls live in one file, each gets its own `__componentMeta` with\n// its own line number, and the conflict-detector lets each emission\n// through because the `(field, target)` tuples are distinct.\n\nimport type { CompilerModule, EmissionContribution } from '@llui/compiler'\nimport { findComponentCalls } from '@llui/compiler'\n\nexport const componentMetaModule: CompilerModule = {\n  name: 'component-meta',\n  compilerVersion: '^0.3.0',\n  diagnostics: [],\n  // Targets captured in `emit` (not `visit`) — see `_shared.ts`\n  // `findComponentCalls` for the rationale (Phase 2b rebuilds\n  // ancestor nodes, invalidating visit-captured refs).\n  visitors: {},\n\n  emit(ctx, analysis): EmissionContribution[] {\n    const sf = analysis.sourceFile\n    const calls = findComponentCalls(sf)\n    if (calls.length === 0) return []\n    const out: EmissionContribution[] = []\n    for (const n of calls) {\n      const pos = n.pos >= 0 ? n.getStart(sf) : 0\n      const { line } = sf.getLineAndCharacterOfPosition(pos)\n      const meta = ctx.factory.createObjectLiteralExpression(\n        [\n          ctx.factory.createPropertyAssignment(\n            'file',\n            ctx.factory.createStringLiteral(sf.fileName),\n          ),\n          ctx.factory.createPropertyAssignment('line', ctx.factory.createNumericLiteral(line + 1)),\n        ],\n        false,\n      )\n      out.push({\n        module: 'component-meta',\n        field: '__componentMeta',\n        value: meta,\n        target: n,\n      })\n    }\n    return out\n  },\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import { type DevtoolsFactory } from '@llui/compiler';
+import { componentMetaModule } from './component-meta.js';
+export { componentMetaModule };
+/**
+ * Builds the devtools module set for a single source file.
+ * Activation gates mirror what `transformLlui` did inline before
+ * decomp-27:
+ *   - `componentMetaModule`    when `devMode` is true
+ *
+ * Future devtools modules (trace instrumentation) would gate on a
+ * separate `enableTraceInstrumentation` flag the host passes via
+ * the factory input.
+ */
+export declare const devtoolsFactory: DevtoolsFactory;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,KAAK,eAAe,EAAuB,MAAM,gBAAgB,CAAA;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAEzD,OAAO,EAAE,mBAAmB,EAAE,CAAA;AAE9B;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,eAM7B,CAAA"}

package/dist/index.js

@@ -0,0 +1,38 @@
+// @llui/compiler-devtools — dev-MCP / LLM tooling support (opt-in).
+//
+// Emits compile-time metadata the dev MCP (`@llui/mcp`) and future
+// devtools UI consume. Distinct from `@llui/compiler-introspection`
+// which emits shared metadata (schemas, hashes, legend) that BOTH
+// the end-user agent AND dev tooling consume; this package emits
+// dev-only debug aids that don't need to ship in end-user builds.
+//
+// Modules:
+//   - component-meta           __componentMeta: { file, line }
+//   - (future) trace instrumentation: _eachDiffLog, _disposerLog,
+//     _effectTimeline, _coverage when the runtime devtools spec lands
+//
+// Activation: opt-in. Hosts (Vite plugin, MCP, test setup) import
+// this package and call `registerDevtoolsFactory(devtoolsFactory)`.
+// transformLlui then activates modules per the factory's gating
+// rules (today: componentMeta runs when devMode is true).
+import {} from '@llui/compiler';
+import { componentMetaModule } from './component-meta.js';
+export { componentMetaModule };
+/**
+ * Builds the devtools module set for a single source file.
+ * Activation gates mirror what `transformLlui` did inline before
+ * decomp-27:
+ *   - `componentMetaModule`    when `devMode` is true
+ *
+ * Future devtools modules (trace instrumentation) would gate on a
+ * separate `enableTraceInstrumentation` flag the host passes via
+ * the factory input.
+ */
+export const devtoolsFactory = (input) => {
+    const modules = [];
+    if (input.devMode) {
+        modules.push(componentMetaModule);
+    }
+    return modules;
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,EAAE;AACF,mEAAmE;AACnE,oEAAoE;AACpE,kEAAkE;AAClE,iEAAiE;AACjE,kEAAkE;AAClE,EAAE;AACF,WAAW;AACX,+DAA+D;AAC/D,kEAAkE;AAClE,sEAAsE;AACtE,EAAE;AACF,kEAAkE;AAClE,oEAAoE;AACpE,gEAAgE;AAChE,0DAA0D;AAE1D,OAAO,EAA6C,MAAM,gBAAgB,CAAA;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAEzD,OAAO,EAAE,mBAAmB,EAAE,CAAA;AAE9B;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,eAAe,GAAoB,CAAC,KAAK,EAAE,EAAE;IACxD,MAAM,OAAO,GAAqB,EAAE,CAAA;IACpC,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAClB,OAAO,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAA;IACnC,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA","sourcesContent":["// @llui/compiler-devtools — dev-MCP / LLM tooling support (opt-in).\n//\n// Emits compile-time metadata the dev MCP (`@llui/mcp`) and future\n// devtools UI consume. Distinct from `@llui/compiler-introspection`\n// which emits shared metadata (schemas, hashes, legend) that BOTH\n// the end-user agent AND dev tooling consume; this package emits\n// dev-only debug aids that don't need to ship in end-user builds.\n//\n// Modules:\n//   - component-meta           __componentMeta: { file, line }\n//   - (future) trace instrumentation: _eachDiffLog, _disposerLog,\n//     _effectTimeline, _coverage when the runtime devtools spec lands\n//\n// Activation: opt-in. Hosts (Vite plugin, MCP, test setup) import\n// this package and call `registerDevtoolsFactory(devtoolsFactory)`.\n// transformLlui then activates modules per the factory's gating\n// rules (today: componentMeta runs when devMode is true).\n\nimport { type DevtoolsFactory, type CompilerModule } from '@llui/compiler'\nimport { componentMetaModule } from './component-meta.js'\n\nexport { componentMetaModule }\n\n/**\n * Builds the devtools module set for a single source file.\n * Activation gates mirror what `transformLlui` did inline before\n * decomp-27:\n *   - `componentMetaModule`    when `devMode` is true\n *\n * Future devtools modules (trace instrumentation) would gate on a\n * separate `enableTraceInstrumentation` flag the host passes via\n * the factory input.\n */\nexport const devtoolsFactory: DevtoolsFactory = (input) => {\n  const modules: CompilerModule[] = []\n  if (input.devMode) {\n    modules.push(componentMetaModule)\n  }\n  return modules\n}\n"]}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@llui/compiler-devtools",
+  "version": "0.3.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "typescript": "^6.0.2",
+    "@llui/compiler": "0.3.0",
+    "@llui/compiler-introspection": "0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
+  },
+  "description": "LLui compiler — dev-MCP / LLM tooling support (opt-in, dev-mode only). Emits `__componentMeta` (file/line for source navigation) and future trace instrumentation (`_eachDiffLog`, `_disposerLog`, `_effectTimeline`, `_coverage`). Depends on @llui/compiler-introspection.",
+  "keywords": [
+    "llui",
+    "compiler",
+    "devtools",
+    "mcp"
+  ],
+  "author": "Franco Ponticelli <franco.ponticelli@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fponticelli/llui.git",
+    "directory": "packages/compiler-devtools"
+  },
+  "bugs": {
+    "url": "https://github.com/fponticelli/llui/issues"
+  },
+  "homepage": "https://github.com/fponticelli/llui/tree/main/packages/compiler-devtools#readme",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run"
+  }
+}