@alloy-js/core 0.15.0 → 0.17.0

package/dist/src/tracer.d.ts

@@ -0,0 +1,181 @@
+import type { Refkey } from "./refkey.js";
+import { OutputScope } from "./symbols/output-scope.js";
+import { OutputSymbol } from "./symbols/output-symbol.js";
+export declare const TracePhase: {
+    readonly render: {};
+    readonly scope: {
+        readonly update: {
+            readonly area: "scope";
+            readonly subarea: "update";
+            readonly bg: {
+                readonly r: 0;
+                readonly g: 255;
+                readonly b: 100;
+            };
+        };
+        readonly create: {
+            readonly area: "scope";
+            readonly subarea: "create";
+            readonly bg: {
+                readonly r: 0;
+                readonly g: 150;
+                readonly b: 100;
+            };
+        };
+        readonly copySymbols: {
+            readonly area: "scope";
+            readonly subarea: "copySymbols";
+            readonly bg: {
+                readonly r: 0;
+                readonly g: 100;
+                readonly b: 100;
+            };
+        };
+    };
+    readonly symbol: {
+        readonly update: {
+            readonly area: "symbol";
+            readonly subarea: "update";
+            readonly bg: {
+                readonly r: 0;
+                readonly g: 0;
+                readonly b: 255;
+            };
+        };
+        readonly resolve: {
+            readonly area: "symbol";
+            readonly subarea: "resolve";
+            readonly bg: {
+                readonly r: 0;
+                readonly g: 0;
+                readonly b: 200;
+            };
+        };
+        readonly create: {
+            readonly area: "symbol";
+            readonly subarea: "create";
+            readonly bg: {
+                readonly r: 0;
+                readonly g: 0;
+                readonly b: 150;
+            };
+        };
+        readonly flow: {
+            readonly area: "symbol";
+            readonly subarea: "flow";
+            readonly bg: {
+                readonly r: 0;
+                readonly g: 0;
+                readonly b: 100;
+            };
+        };
+        readonly addToScope: {
+            readonly area: "symbol";
+            readonly subarea: "addToScope";
+            readonly bg: {
+                readonly r: 0;
+                readonly g: 0;
+                readonly b: 50;
+            };
+        };
+        readonly instantiate: {
+            readonly area: "symbol";
+            readonly subarea: "instantiate";
+            readonly bg: {
+                readonly r: 0;
+                readonly g: 0;
+                readonly b: 25;
+            };
+        };
+        readonly clone: {
+            readonly area: "symbol";
+            readonly subarea: "clone";
+            readonly bg: {
+                readonly r: 0;
+                readonly g: 0;
+                readonly b: 25;
+            };
+        };
+        readonly delete: {
+            readonly area: "symbol";
+            readonly subarea: "delete";
+            readonly bg: {
+                readonly r: 100;
+                readonly g: 0;
+                readonly b: 100;
+            };
+        };
+        readonly removeFromScope: {
+            readonly area: "symbol";
+            readonly subarea: "removeFromScope";
+            readonly bg: {
+                readonly r: 50;
+                readonly g: 0;
+                readonly b: 50;
+            };
+        };
+    };
+    readonly resolve: {
+        readonly success: {
+            readonly area: "resolve";
+            readonly subarea: "success";
+            readonly bg: {
+                readonly r: 0;
+                readonly g: 255;
+                readonly b: 0;
+            };
+        };
+        readonly pending: {
+            readonly area: "resolve";
+            readonly subarea: "pending";
+            readonly bg: {
+                readonly r: 255;
+                readonly g: 255;
+                readonly b: 0;
+            };
+        };
+        readonly failure: {
+            readonly area: "resolve";
+            readonly subarea: "failure";
+            readonly bg: {
+                readonly r: 100;
+                readonly g: 50;
+                readonly b: 50;
+            };
+        };
+    };
+};
+interface TracePhase extends TextFormat {
+    area: string;
+    subarea: string;
+}
+export declare function trace(phase: TracePhase, cb: () => string, triggerIds?: Set<number>): void;
+export declare function traceEffect(phase: TracePhase, cb: () => string): void;
+interface Color {
+    r: number;
+    g: number;
+    b: number;
+}
+/** Descriptor for how to format the text */
+interface TextFormat {
+    fg?: Color;
+    bg?: Color;
+    bold?: boolean;
+}
+/**
+ * Format a symbol name with its ID in a blue-green color
+ * @param symbol The symbol to format
+ * @returns A formatted string representation of the symbol name with ID
+ */
+export declare function formatSymbolName(symbol: OutputSymbol): string;
+export declare function formatSymbol(symbol: OutputSymbol): string;
+export declare function formatScopeName(scope: OutputScope): string;
+/**
+ * Format an OutputScope for display, showing information in a concise format
+ * @param scope The scope to format
+ * @returns A formatted string representation of the scope
+ */
+export declare function formatScope(scope: OutputSymbol["scope"]): string;
+export declare function formatRefkeys(refkeys: Refkey[] | Refkey | undefined): string;
+export {};
+//# sourceMappingURL=tracer.d.ts.map

package/dist/src/tracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../src/tracer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EAAE,WAAW,EAAoB,MAAM,2BAA2B,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAqB,MAAM,4BAA4B,CAAC;AA0B7E,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmFb,CAAC;AAEX,UAAU,UAAW,SAAQ,UAAU;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAUD,wBAAgB,KAAK,CACnB,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,MAAM,EAChB,UAAU,GAAE,GAAG,CAAC,MAAM,CAAa,QA4BpC;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,MAAM,QA8B9D;AAED,UAAU,KAAK;IACb,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,4CAA4C;AAC5C,UAAU,UAAU;IAClB,EAAE,CAAC,EAAE,KAAK,CAAC;IACX,EAAE,CAAC,EAAE,KAAK,CAAC;IACX,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAuDD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAQ7D;AAiBD,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAoDzD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAc1D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,GAAG,MAAM,CAoDhE;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,UAUnE"}

package/dist/src/tracer.js

@@ -0,0 +1,441 @@
+import { untrack } from "@alloy-js/core/jsx-runtime";
+import { effect } from "@vue/reactivity";
+import { scheduler } from "./scheduler.js";
+import { OutputScopeFlags } from "./symbols/output-scope.js";
+import { OutputSymbolFlags } from "./symbols/output-symbol.js";
+
+// enable tracing for specific phases using a comma separated list of
+// dotted identifiers, e.g. `scope.update,symbol.create`.
+const traceEnv = process.env.ALLOY_TRACE ?? "";
+const tracePhases = new Set(traceEnv === "" ? [] : traceEnv.split(",").map(t => t.trim()));
+if (tracePhases.size > 0) {
+  // eslint-disable-next-line no-console
+  console.log("Tracing enabled for phases:", Array.from(tracePhases).join(", "));
+}
+const debuggerIdsEnv = process.env.ALLOY_BREAK_ON_DID ?? "";
+const dids = new Set();
+debuggerIdsEnv.split(",").forEach(id => {
+  const num = parseInt(id, 10);
+  if (!isNaN(num)) {
+    dids.add(num);
+  }
+});
+export const TracePhase = {
+  render: {},
+  scope: {
+    update: {
+      area: "scope",
+      subarea: "update",
+      bg: {
+        r: 0,
+        g: 255,
+        b: 100
+      }
+    },
+    create: {
+      area: "scope",
+      subarea: "create",
+      bg: {
+        r: 0,
+        g: 150,
+        b: 100
+      }
+    },
+    copySymbols: {
+      area: "scope",
+      subarea: "copySymbols",
+      bg: {
+        r: 0,
+        g: 100,
+        b: 100
+      }
+    }
+  },
+  symbol: {
+    update: {
+      area: "symbol",
+      subarea: "update",
+      bg: {
+        r: 0,
+        g: 0,
+        b: 255
+      }
+    },
+    resolve: {
+      area: "symbol",
+      subarea: "resolve",
+      bg: {
+        r: 0,
+        g: 0,
+        b: 200
+      }
+    },
+    create: {
+      area: "symbol",
+      subarea: "create",
+      bg: {
+        r: 0,
+        g: 0,
+        b: 150
+      }
+    },
+    flow: {
+      area: "symbol",
+      subarea: "flow",
+      bg: {
+        r: 0,
+        g: 0,
+        b: 100
+      }
+    },
+    addToScope: {
+      area: "symbol",
+      subarea: "addToScope",
+      bg: {
+        r: 0,
+        g: 0,
+        b: 50
+      }
+    },
+    instantiate: {
+      area: "symbol",
+      subarea: "instantiate",
+      bg: {
+        r: 0,
+        g: 0,
+        b: 25
+      }
+    },
+    clone: {
+      area: "symbol",
+      subarea: "clone",
+      bg: {
+        r: 0,
+        g: 0,
+        b: 25
+      }
+    },
+    delete: {
+      area: "symbol",
+      subarea: "delete",
+      bg: {
+        r: 100,
+        g: 0,
+        b: 100
+      }
+    },
+    removeFromScope: {
+      area: "symbol",
+      subarea: "removeFromScope",
+      bg: {
+        r: 50,
+        g: 0,
+        b: 50
+      }
+    }
+  },
+  resolve: {
+    success: {
+      area: "resolve",
+      subarea: "success",
+      bg: {
+        r: 0,
+        g: 255,
+        b: 0
+      }
+    },
+    pending: {
+      area: "resolve",
+      subarea: "pending",
+      bg: {
+        r: 255,
+        g: 255,
+        b: 0
+      }
+    },
+    failure: {
+      area: "resolve",
+      subarea: "failure",
+      bg: {
+        r: 100,
+        g: 50,
+        b: 50
+      }
+    }
+  }
+};
+let triggerCount = 0;
+function shouldTrace(phase) {
+  return tracePhases.has(phase.area) || tracePhases.has(phase.area + "." + phase.subarea);
+}
+export function trace(phase, cb, triggerIds = new Set()) {
+  if (!shouldTrace(phase)) {
+    return;
+  }
+  if (triggerIds.size === 0) {
+    // not an effect trace.
+    const id = triggerCount++;
+    triggerIds.add(id);
+    if (dids.has(id)) {
+      // eslint-disable-next-line no-debugger
+      debugger;
+    }
+  }
+  const areaTag = ` ${phase.area + ":" + phase.subarea} `;
+  // eslint-disable-next-line no-console
+  console.log(colorText(areaTag, {
+    ...phase,
+    bold: true
+  }) + " " + colorText("[" + [...triggerIds].join(",") + "]", {
+    fg: {
+      r: 50,
+      g: 50,
+      b: 50
+    }
+  }) + " " + cb() + "\n");
+}
+export function traceEffect(phase, cb) {
+  if (!shouldTrace(phase)) {
+    return;
+  }
+  let first = true;
+  const triggerIds = new Set();
+  const runner = effect(() => {
+    if (first) {
+      // just track what we need, don't log.
+      cb();
+      first = false;
+      return;
+    }
+    trace(phase, cb, triggerIds);
+    triggerIds.clear();
+  }, {
+    scheduler: scheduler(() => runner, true),
+    onTrigger(event) {
+      const id = triggerCount++;
+      if (dids.has(id)) {
+        // eslint-disable-next-line no-debugger
+        debugger;
+      }
+      triggerIds.add(id);
+    }
+  });
+}
+
+/** Descriptor for how to format the text */
+
+/**
+ * Wraps `text` in ANSI escape codes according to the given format.
+ *
+ * @param text  The string to format.
+ * @param fmt   Optional formatting descriptor.
+ * @returns     The text wrapped in ANSI codes (or unmodified if no styles given).
+ */
+function colorText(text, fmt) {
+  if (!fmt) return text;
+  const codes = [];
+  if (fmt.bold) {
+    codes.push("1"); // ANSI code for bold
+  }
+  if (fmt.fg) {
+    const {
+      r,
+      g,
+      b
+    } = fmt.fg;
+    codes.push(`38;2;${r};${g};${b}`);
+  }
+  if (fmt.bg) {
+    const {
+      r,
+      g,
+      b
+    } = fmt.bg;
+    codes.push(`48;2;${r};${g};${b}`);
+  }
+  if (codes.length === 0) {
+    return text;
+  }
+  const prefix = `\x1b[${codes.join(";")}m`;
+  const reset = `\x1b[0m`;
+  return `${prefix}${text}${reset}`;
+}
+
+/**
+ * Format flag values in a concise way, showing only the flags that are set
+ * @param flags The numeric flags value to format
+ * @param flagEnum The enum containing flag definitions
+ * @returns An array of flag names that are set
+ */
+function formatFlags(flags, flagEnum) {
+  return Object.entries(flagEnum).filter(([name, value]) => typeof value === "number" && value !== 0 && (flags & value) === value).map(([name]) => name);
+}
+
+/**
+ * Format a symbol name with its ID in a blue-green color
+ * @param symbol The symbol to format
+ * @returns A formatted string representation of the symbol name with ID
+ */
+export function formatSymbolName(symbol) {
+  return colorText(`Symbol ${symbol.name}[${symbol.id}]`, {
+    fg: {
+      r: 0,
+      b: 150,
+      g: 100
+    }
+  });
+}
+
+/**
+ * Format the symbols in a member scope, showing their names and IDs
+ * @param scope The member scope containing the symbols to format
+ * @returns A formatted string representation of the member scope symbols
+ */
+function formatMemberScopeSymbols(scope) {
+  if (!scope || scope.symbols.size === 0) {
+    return "none";
+  }
+  return Array.from(scope.symbols).map(symbol => formatSymbolName(symbol)).join(", ");
+}
+export function formatSymbol(symbol) {
+  // Base display with name and ID
+  let result = formatSymbolName(symbol);
+
+  // Add details on subsequent lines
+  const details = [];
+  if (!symbol.binder) {
+    details.push(colorText("  !UNBOUND", {
+      fg: {
+        r: 255,
+        g: 0,
+        b: 0
+      }
+    }));
+  }
+
+  // Show only enabled flags
+  const flagsInfo = formatFlags(symbol.flags, OutputSymbolFlags);
+  if (flagsInfo.length > 0) {
+    details.push(`  flags: ${flagsInfo.join(", ")}`);
+  }
+
+  // Show scope info with formatted name
+  if (symbol.scope) {
+    details.push(untrack(() => `  scope: ${formatScopeName(symbol.scope)}`));
+  }
+
+  // Show member scopes if present
+  if (symbol.instanceMemberScope) {
+    untrack(() => {
+      const memberCount = symbol.instanceMemberScope.symbols.size;
+      details.push(`  instance members: ${memberCount} - ${formatMemberScopeSymbols(symbol.instanceMemberScope)}`);
+    });
+  }
+  if (symbol.staticMemberScope) {
+    untrack(() => {
+      const memberCount = symbol.staticMemberScope.symbols.size;
+      details.push(`  static members: ${memberCount} - ${formatMemberScopeSymbols(symbol.staticMemberScope)}`);
+    });
+  }
+
+  // Show all refkeys with proper formatting
+  if (symbol.refkeys && symbol.refkeys.length > 0) {
+    details.push(`  refkeys: ${formatRefkeys(symbol.refkeys)}`);
+  }
+  if (details.length > 0) {
+    result += "\n" + details.join("\n");
+  }
+  return result;
+}
+export function formatScopeName(scope) {
+  let text = colorText(`${scope.name}[${scope.id}]`, {
+    fg: {
+      r: 0,
+      g: 150,
+      b: 50
+    }
+  });
+  if (scope.owner) {
+    text += untrack(() => ` of ${formatSymbolName(scope.owner)}`);
+  }
+  return text;
+}
+
+/**
+ * Format an OutputScope for display, showing information in a concise format
+ * @param scope The scope to format
+ * @returns A formatted string representation of the scope
+ */
+export function formatScope(scope) {
+  if (!scope) {
+    return "!Undefined scope!";
+  }
+  // Base display with name
+  let result = colorText(`Scope ${formatScopeName(scope)}`, {
+    fg: {
+      r: 0,
+      b: 200,
+      g: 100
+    }
+  });
+
+  // Add details on subsequent lines
+  const details = [];
+  if (!scope.binder) {
+    details.push(colorText("  !UNBOUND", {
+      fg: {
+        r: 255,
+        g: 0,
+        b: 0
+      }
+    }));
+  }
+  // Show only enabled flags
+  const flagsInfo = formatFlags(scope.flags, OutputScopeFlags);
+  if (flagsInfo.length > 0) {
+    details.push(`  flags: ${flagsInfo.join(", ")}`);
+  }
+
+  // Show symbol count
+  const symbolCount = scope.symbols.size;
+  if (symbolCount > 0) {
+    details.push(`  symbols: ${symbolCount}`);
+  }
+
+  // Show parent scope if present
+  if (scope.parent) {
+    details.push(`  parent: ${formatScopeName(scope.parent)}`);
+  }
+
+  // Show owner if present (for member scopes)
+  if (scope.owner) {
+    details.push(`  owner: ${formatSymbolName(scope.owner)}`);
+  }
+
+  // Show child scopes if present
+  if (scope.children && scope.children.size > 0) {
+    details.push(`  children: ${scope.children.size}`);
+  }
+  if (details.length > 0) {
+    result += "\n" + details.join("\n");
+  }
+  return result;
+}
+export function formatRefkeys(refkeys) {
+  if (!refkeys) {
+    return "";
+  }
+  if (Array.isArray(refkeys)) {
+    return refkeys.map(formatRefkey).join(", ");
+  }
+  return formatRefkey(refkeys);
+}
+function formatRefkey(refkey) {
+  return colorText(`refkey[${refkey.key}]`, {
+    fg: {
+      r: 150,
+      g: 0,
+      b: 0
+    }
+  });
+}

package/dist/src/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.47.12"
+      "packageVersion": "7.52.8"
     }
   ]
 }

package/dist/test/components/slot.test.js

@@ -5,6 +5,7 @@ import { SourceFile } from "../../src/components/SourceFile.js";
 import { Declaration, Name, refkey, Scope, useBinder } from "../../src/index.js";
 import { render } from "../../src/render.js";
 import { defineSlot, rename, replace } from "../../src/slot.js";
+import { OutputSymbol } from "../../src/symbols/output-symbol.js";
 import "../../testing/extend-expect.js";
 it("works with string keys", () => {
   const FunctionSlot = defineSlot(query => query.name);
@@ -44,9 +45,8 @@ it("works with symbols", () => {
   });
   function MyFunctionComponent(props) {
     const binder = useBinder();
-    const sym = binder.createSymbol({
-      name: props.name,
-      refkey: refkey()
+    const sym = new OutputSymbol(props.name, {
+      refkeys: refkey()
     });
     const FunctionSlotInstance = FunctionSlot.create(sym, {
       ...props,
@@ -92,10 +92,8 @@ it("can rename", () => {
     return binder.resolveFQN(query.fqn);
   });
   function MyFunctionComponent(props) {
-    const binder = useBinder();
-    const sym = binder.createSymbol({
-      name: props.name,
-      refkey: refkey()
+    const sym = new OutputSymbol(props.name, {
+      refkeys: refkey()
     });
     const FunctionSlotInstance = FunctionSlot.create(sym, {
       ...props,

package/dist/test/reactive-union-set.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=reactive-union-set.test.d.ts.map

package/dist/test/reactive-union-set.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reactive-union-set.test.d.ts","sourceRoot":"","sources":["../../test/reactive-union-set.test.tsx"],"names":[],"mappings":""}