@alloy-js/core 0.15.0 → 0.17.0

package/dist/src/symbols/output-scope.js

@@ -0,0 +1,246 @@
+import { reactive, ReactiveFlags, shallowReactive, track, TrackOpTypes, trigger, TriggerOpTypes, watch } from "@vue/reactivity";
+import { useBinder } from "../context/binder.js";
+import { useScope } from "../context/scope.js";
+import { formatScope, formatScopeName, trace, traceEffect, TracePhase } from "../tracer.js";
+import { SymbolTable } from "./symbol-table.js";
+
+/**
+ * Flags that describe an output scope.
+ */
+export let OutputScopeFlags = /*#__PURE__*/function (OutputScopeFlags) {
+  OutputScopeFlags[OutputScopeFlags["None"] = 0] = "None";
+  /**
+   * This scope is a static member scope.
+   */
+  OutputScopeFlags[OutputScopeFlags["StaticMemberScope"] = 1] = "StaticMemberScope";
+  /**
+   * This scope is an instance member scope.
+   */
+  OutputScopeFlags[OutputScopeFlags["InstanceMemberScope"] = 2] = "InstanceMemberScope";
+  /**
+   * This scope is transient, and only exists to be merged with other scopes.
+   */
+  OutputScopeFlags[OutputScopeFlags["Transient"] = 4] = "Transient";
+  /**
+   * This scope is a member scope. Scopes with this flag will have an `owner`
+   * property that points to the symbol whose member this scope holds.
+   */
+  OutputScopeFlags[OutputScopeFlags["MemberScope"] = 3] = "MemberScope";
+  return OutputScopeFlags;
+}({});
+let scopeCount = 0;
+/**
+ * A container of symbols accessible within some scope in your output code.
+ *
+ * @remarks
+ *
+ * Scopes form a tree. All scopes except the global scope have a parent scope
+ * identified by `parent`. Scopes can have nested scopes which can be accessed
+ * using the `children` property. Whether a child scope can be accessed from
+ * the parent scope is determined by each language's scoping rules.
+ *
+ * This interface is the base implementation of scope. Generally, most languages
+ * will have subtypes of this interface that provide additional metadata about
+ * the scope. For example, TypeScript scopes need to track whether the scope
+ * represents a package, module, class, function, etc.
+ *
+ * Scopes are reactive values, which allows you to observe changes to the scope
+ * within a reactive context.
+ */
+export class OutputScope {
+  // my kingdom for decorators
+  #name;
+  /**
+   * The name of the scope.
+   */
+  get name() {
+    track(this, TrackOpTypes.GET, "name");
+    return this.#name;
+  }
+  set name(name) {
+    const old = this.#name;
+    this.#name = name;
+    trigger(this, TriggerOpTypes.SET, "name", name, old);
+  }
+  #id;
+  /**
+   * The unique id of this scope.
+   */
+  get id() {
+    return this.#id;
+  }
+  #kind;
+
+  /**
+   * The kind of scope. Subtypes will likely provide a set of known scope kinds.
+   * The kind is not used by the binder itself.
+   */
+  get kind() {
+    return this.#kind;
+  }
+  #flags;
+  /**
+   * The flags that describe this scope.
+   */
+  get flags() {
+    track(this, TrackOpTypes.GET, "flags");
+    return this.#flags;
+  }
+  set flags(flags) {
+    const old = this.#flags;
+    this.#flags = flags;
+    trigger(this, TriggerOpTypes.SET, "flags", flags, old);
+  }
+
+  // read only
+  #metadata;
+  get metadata() {
+    return this.#metadata;
+  }
+  #parent;
+  /**
+   * The container of this scope. This is only defined for scopes which don't
+   * have the {@link OutputScopeFlags.StaticMemberScope} or
+   * {@link OutputScopeFlags.InstanceMemberScope} flag.
+   */
+  get parent() {
+    return this.#parent;
+  }
+  #owner;
+  /**
+   * The symbol that owns this scope. This is only defined for scopes that have
+   * the {@link OutputScopeFlags.StaticMemberScope} or
+   * {@link OutputScopeFlags.InstanceMemberScope} flag.
+   */
+  get owner() {
+    return this.#owner;
+  }
+  #symbols;
+  /**
+   * The symbols defined within this scope.
+   */
+  get symbols() {
+    return this.#symbols;
+  }
+  #symbolsByRefkey;
+  /**
+   * The symbols defined within this scope, indexed by refkey.
+   */
+  get symbolsByRefkey() {
+    return this.#symbolsByRefkey;
+  }
+  #symbolNames;
+  get symbolNames() {
+    return this.#symbolNames;
+  }
+  #children;
+  /**
+   * The scopes nested within this scope.
+   */
+  get children() {
+    return this.#children;
+  }
+  #binder;
+  /**
+   * The binder that created this scope.
+   */
+  get binder() {
+    return this.#binder;
+  }
+  [ReactiveFlags.SKIP] = this;
+  constructor(name, options = {}) {
+    this.#name = name;
+    this.#id = scopeCount++;
+    this.#flags = options.flags ?? OutputScopeFlags.None;
+    this.#kind = options.kind ?? "scope";
+    this.#metadata = reactive(options.metadata ?? {});
+    this.#binder = options.binder ?? useBinder();
+    this.#owner = options.owner;
+    this.#children = shallowReactive(new Set());
+    if (this.#flags & OutputScopeFlags.MemberScope) {
+      if (!this.#owner) {
+        throw new Error("Member scopes must have an owner");
+      }
+    } else {
+      if (!this.#parent) {
+        this.#parent = options.parent ?? useScope() ?? this.#binder?.globalScope;
+      }
+      if (this.#parent) {
+        // not global scope
+        this.#parent.children.add(this);
+      }
+    }
+    this.#symbols = new SymbolTable(this, {
+      nameConflictResolver: this.#binder?.nameConflictResolver
+    });
+    this.#symbolsByRefkey = this.#symbols.createIndex(s => s.refkeys);
+    this.#symbolNames = this.#symbols.createDerivedSet(s => {
+      return s.name;
+    });
+    if (this.#parent) {
+      this.#parent.children.add(this);
+    }
+    this.#binder?.notifyScopeCreated(this);
+    trace(TracePhase.scope.create, () => `${formatScope(this)}`);
+    traceEffect(TracePhase.scope.update, () => {
+      return `${formatScope(this)}`;
+    });
+  }
+  moveSymbolsFrom(source, options) {
+    trace(TracePhase.scope.copySymbols, () => `Moving symbols from ${formatScopeName(source)} to ${formatScopeName(this)}`);
+    this.#symbols.addSubset(source.#symbols, {
+      onAdd: symbol => {
+        if (options?.onAdd) {
+          return options.onAdd(symbol);
+        }
+        symbol.scope = this;
+        return symbol;
+      },
+      onDelete: symbol => {
+        if (options?.onDelete) {
+          options.onDelete(symbol);
+        }
+      }
+    });
+  }
+  copySymbolsFrom(source, options) {
+    trace(TracePhase.scope.copySymbols, () => `Copying symbols from ${formatScopeName(source)} to ${formatScopeName(this)}`);
+    this.#symbols.addSubset(source.#symbols, {
+      onAdd: symbol => {
+        if (options?.onAdd) {
+          return options.onAdd(symbol);
+        }
+        return symbol.copyToScope(this);
+      },
+      onDelete: symbol => {
+        if (options?.onDelete) {
+          options.onDelete(symbol);
+        }
+      }
+    });
+  }
+  clone(options = {}) {
+    if (this.#flags & OutputScopeFlags.MemberScope && !options.owner) {
+      throw new Error("Member scope clones must specify an owner symbol");
+    } else if (this.#flags & ~OutputScopeFlags.MemberScope && !options.parent) {
+      throw new Error("Non-member scope clones must specify a parent scope");
+    }
+    const clone = new OutputScope(this.#name, {
+      binder: this.#binder,
+      flags: this.#flags,
+      kind: this.#kind,
+      metadata: this.#metadata,
+      parent: options.parent,
+      owner: options.owner
+    });
+    watch(() => this.name, newName => clone.name = newName);
+    watch(() => this.flags, newFlags => clone.flags = newFlags);
+    // todo: this should be reactive, but cloning non-member scopes
+    // seems like a very rare thing.
+    for (const child of this.#children) {
+      clone.children.add(child.clone());
+    }
+    clone.copySymbolsFrom(this);
+    return clone;
+  }
+}

package/dist/src/symbols/output-symbol.d.ts

@@ -0,0 +1,134 @@
+import { ReactiveFlags } from "@vue/reactivity";
+import type { Binder } from "../binder.js";
+import { type Refkey } from "../refkey.js";
+import { OutputScope, OutputScopeFlags } from "./output-scope.js";
+/**
+ * Flags that describe an output symbol.
+ */
+export declare enum OutputSymbolFlags {
+    None = 0,
+    /**
+     * The symbol is an instance member container. Symbols with this flag will have a
+     * instanceMemberScope property that contains symbols for instance members.
+     */
+    InstanceMemberContainer = 1,
+    /**
+     * The symbol is a static member container. Symbols with this flag will have a
+     * staticMemberScope property that contains symbols for static members.
+     */
+    StaticMemberContainer = 2,
+    /**
+     * Whether this symbol contains members of any kind.
+     */
+    MemberContainer = 3,
+    /**
+     * Whether this symbol is an instance member of another symbol (i.e that it is
+     * stored in an instance member scope).
+     */
+    InstanceMember = 4,
+    /**
+     * Whether this symbol is a static member of another symbol (i.e that it is
+     * stored in a static member scope).
+     */
+    StaticMember = 8,
+    /**
+     * Transient symbols are not added to symbol tables and do not create
+     * referencable refkeys. They are used for temporary symbols that are intended
+     * to be used to calculate other symbols.
+     */
+    Transient = 16,
+    /**
+     * This symbol aliases another symbol. Only its name, flags, and scope are
+     * stored in this symbol. Otherwise, everything else is located on the alias
+     * target.
+     */
+    Alias = 32,
+    /**
+     * Whether this is an instance member or static member of another symbol.
+     */
+    Member = 12
+}
+export interface OutputSymbolOptions {
+    binder?: Binder;
+    scope?: OutputScope;
+    flags?: OutputSymbolFlags;
+    refkeys?: Refkey | Refkey[];
+    metadata?: Record<string, unknown>;
+    aliasTarget?: OutputSymbol;
+}
+/**
+ * An output symbol is a named entity that can be referenced in your output
+ * code.
+ *
+ * @remarks
+ *
+ * This class is the base implementation of symbol. Most languages will have
+ * subtypes that provide additional metadata. Symbols are reactive values, so
+ * you can observe changes to their properties in a reactive context.
+ */
+export declare class OutputSymbol {
+    #private;
+    get originalName(): string;
+    get name(): string;
+    set name(name: string);
+    get id(): number;
+    get flags(): OutputSymbolFlags;
+    set flags(flags: OutputSymbolFlags);
+    get scope(): OutputScope;
+    set scope(scope: OutputScope);
+    get binder(): Binder | undefined;
+    get refkeys(): Refkey[];
+    set refkeys(refkeys: Refkey[]);
+    get instanceMemberScope(): OutputScope | undefined;
+    get aliasTarget(): OutputSymbol | undefined;
+    /**
+     * Create an output scope to hold member symbols. By default this just creates
+     * an OutputScope, but can be subclassed to build scope subtypes when needed.
+     */
+    protected createMemberScope(name: string, options: {
+        owner?: OutputSymbol;
+        flags?: OutputScopeFlags;
+    }): OutputScope;
+    get staticMemberScope(): OutputScope | undefined;
+    get metadata(): Record<string, unknown>;
+    /**
+     * Tell \@vue/reactivity that this symbol should never be wrapped in a reactive
+     * proxy.
+     */
+    [ReactiveFlags.SKIP]: boolean;
+    constructor(name: string, options?: OutputSymbolOptions);
+    delete(): void;
+    /**
+     * Takes the instance members or static members on this symbol and creates
+     * corresponding static members on the target symbol. Instance or static
+     * members of instantiated symbols are copied. The refkey of any instantiated
+     * symbols are set to a composite refkey of the target symbol's refkey and the
+     * instantiated symbol's refkey.
+     */
+    instantiateTo(targetSymbol: OutputSymbol): void;
+    /**
+     * Copy member symbols from the target symbol into the target symbol. The
+     * copied symbols have their refkey set to
+     * `refkey(targetSymbol.refkey, this.refkey)`.
+     */
+    copyTo(targetSymbol: OutputSymbol): void;
+    /**
+     * Move member symbols from this transient symbol to the target symbol.
+     */
+    moveTo(targetSymbol: OutputSymbol): void;
+    /**
+     * Makes a copy of this symbol which will update the name and flags
+     * of the clone when the original symbol is updated.
+     *
+     * @remarks
+     *
+     * This is used to create a symbol that is a copy of this symbol, but
+     * with a different scope. Changes to the copy will not affect the
+     * original symbol, and changes to the original symbol's name and flags
+     * will overwrite the copy's name and flags.
+     *
+     * @param newScope - The scope to use for the copy.
+     */
+    copyToScope(newScope: OutputScope, baseSymbol?: OutputSymbol): OutputSymbol;
+}
+//# sourceMappingURL=output-symbol.d.ts.map

package/dist/src/symbols/output-symbol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-symbol.d.ts","sourceRoot":"","sources":["../../../src/symbols/output-symbol.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,aAAa,EAOd,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAI3C,OAAO,EAAoB,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAS7D,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAClE;;GAEG;AACH,oBAAY,iBAAiB;IAC3B,IAAI,IAAI;IAER;;;OAGG;IACH,uBAAuB,IAAS;IAEhC;;;OAGG;IACH,qBAAqB,IAAS;IAE9B;;OAEG;IACH,eAAe,IAAkD;IAEjE;;;OAGG;IACH,cAAc,IAAS;IAEvB;;;OAGG;IACH,YAAY,IAAS;IAErB;;;;OAIG;IACH,SAAS,KAAS;IAElB;;;;OAIG;IACH,KAAK,KAAS;IAEd;;OAEG;IACH,MAAM,KAAgC;CACvC;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,WAAW,CAAC,EAAE,YAAY,CAAC;CAC5B;AAID;;;;;;;;;GASG;AACH,qBAAa,YAAY;;IAEvB,IAAI,YAAY,WAEf;IAGD,IAAI,IAAI,IAIO,MAAM,CADpB;IACD,IAAI,IAAI,CAAC,IAAI,EAAE,MAAM,EASpB;IAGD,IAAI,EAAE,WAEL;IAGD,IAAI,KAAK,IAIQ,iBAAiB,CADjC;IACD,IAAI,KAAK,CAAC,KAAK,EAAE,iBAAiB,EAYjC;IAGD,IAAI,KAAK,IAKQ,WAAW,CAF3B;IAED,IAAI,KAAK,CAAC,KAAK,EAAE,WAAW,EAY3B;IAwBD,IAAI,MAAM,uBAET;IAGD,IAAI,OAAO,IAKU,MAAM,EAAE,CAF5B;IAED,IAAI,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAW5B;IAGD,IAAI,mBAAmB,4BAGtB;IAGD,IAAI,WAAW,6BAEd;IA2BD;;;OAGG;IACH,SAAS,CAAC,iBAAiB,CACzB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QACP,KAAK,CAAC,EAAE,YAAY,CAAC;QACrB,KAAK,CAAC,EAAE,gBAAgB,CAAC;KAC1B;IAUH,IAAI,iBAAiB,4BAGpB;IAyBD,IAAI,QAAQ,4BAEX;IAED;;;OAGG;IACH,CAAC,aAAa,CAAC,IAAI,CAAC,UAAQ;gBAEhB,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB;IA+B3D,MAAM;IASN;;;;;;OAMG;IACH,aAAa,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI;IAuC/C;;;;OAIG;IACH,MAAM,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI;IAiBxC;;OAEG;IACH,MAAM,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI;IAqBxC;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,QAAQ,EAAE,WAAW,EAAE,UAAU,CAAC,EAAE,YAAY,GAAG,YAAY;CA8D5E"}