@alloy-js/core 0.23.0-dev.16 → 0.23.0-dev.18

package/temp/api.json

@@ -17645,6 +17645,36 @@
               "isProtected": false,
               "isAbstract": false
             },
+            {
+              "kind": "Property",
+              "canonicalReference": "@alloy-js/core!OutputSymbol#canonicalName:member",
+              "docComment": "/**\n * The canonical requested name for this symbol: the result of applying the\n * symbol's name policy to its {@link OutputSymbol.originalName | originalName}, or the original name\n * itself when no policy applies. This is the name the symbol would carry if\n * there were no conflicts, and is stable across the symbol's lifetime (it\n * depends only on the immutable `originalName` and the name policy).\n *\n * Used by {@link SymbolTable} as the grouping key for name-conflict\n * resolution, so that symbols whose original names normalize to the same\n * policy-applied name (e.g. `foo_bar` and `fooBar` under camelCase) are\n * recognized as conflicting.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "get canonicalName(): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "canonicalName",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
             {
               "kind": "Method",
               "canonicalReference": "@alloy-js/core!OutputSymbol#copy:member(1)",
@@ -17843,6 +17873,36 @@
               "isProtected": false,
               "isAbstract": false
             },
+            {
+              "kind": "Property",
+              "canonicalReference": "@alloy-js/core!OutputSymbol#deconflictedName:member",
+              "docComment": "/**\n * The name assigned by a name-conflict resolver, or `undefined` when the\n * symbol is not currently renamed by conflict resolution.\n *\n * Resolvers should assign to this slot (rather than `name`) to record that a\n * rename exists only because of a conflict. On re-deconfliction (e.g. after\n * a conflicting symbol is removed), resolvers clear this slot by assigning\n * `undefined`; the effective {@link OutputSymbol.name | name} then falls back to the\n * user-assigned name, which in turn falls back to the original name.\n *\n * Name policy is applied to values written here (unless `ignoreNamePolicy`\n * is true), matching `name`'s behavior.\n *\n *\n * @reactive\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "get deconflictedName(): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string | undefined"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";\n\nset deconflictedName(value: string | undefined);"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "deconflictedName",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
             {
               "kind": "Method",
               "canonicalReference": "@alloy-js/core!OutputSymbol#delete:member(1)",
@@ -18496,7 +18556,7 @@
             {
               "kind": "Property",
               "canonicalReference": "@alloy-js/core!OutputSymbol#name:member",
-              "docComment": "/**\n * The name of this symbol. Assigning to this property applies the active\n * name policy (unless `ignoreNamePolicy` is true) before storing the value.\n *\n *\n * @reactive\n */\n",
+              "docComment": "/**\n * The name of this symbol. Assigning to this property applies the active\n * name policy (unless `ignoreNamePolicy` is true) before storing the value.\n *\n * The effective name is computed as `deconflictedName ?? userName`, so if a\n * name-conflict resolver has assigned a {@link OutputSymbol.deconflictedName | deconflictedName}, that value\n * is returned here; otherwise the value most recently assigned to `name` is\n * returned.\n *\n *\n * @reactive\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",

package/test/symbols/deconflicted-name.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from "vitest";
+import { Binder, createOutputBinder } from "../../src/binder.js";
+import { flushJobs } from "../../src/scheduler.js";
+import { BasicScope } from "../../src/symbols/basic-scope.js";
+import { BasicSymbol } from "../../src/symbols/basic-symbol.js";
+import type { OutputSymbol } from "../../src/symbols/output-symbol.js";
+
+function setup(
+  nameConflictResolver?: (name: string, syms: OutputSymbol[]) => void,
+) {
+  const binder: Binder = createOutputBinder({ nameConflictResolver });
+  const scope = new BasicScope("root", undefined, { binder });
+  return { binder, scope };
+}
+
+describe("deconflictedName", () => {
+  it("default resolver renames losers via deconflictedName and reverts on removal", () => {
+    const { scope } = setup();
+    const a = new BasicSymbol("foo", scope.symbols, {});
+    const b = new BasicSymbol("foo", scope.symbols, {});
+    flushJobs();
+    expect(a.name).toBe("foo");
+    expect(b.name).toBe("foo_2");
+    expect(a.deconflictedName).toBeUndefined();
+    expect(b.deconflictedName).toBe("foo_2");
+
+    b.delete();
+    flushJobs();
+    expect(a.name).toBe("foo");
+    expect(a.deconflictedName).toBeUndefined();
+  });
+
+  it("works with a custom rename scheme that doesn't match the default _N pattern", () => {
+    // Resolver uses a `$foo` prefix instead of `foo_N` suffix — the old
+    // isAutoAlias regex would never match this.
+    const customResolver = (_: string, symbols: OutputSymbol[]) => {
+      if (symbols.length === 0) return;
+      symbols[0].deconflictedName = undefined;
+      for (let i = 1; i < symbols.length; i++) {
+        symbols[i].deconflictedName = "$" + symbols[i].originalName;
+      }
+    };
+    const { scope } = setup(customResolver);
+
+    const a = new BasicSymbol("foo", scope.symbols, {});
+    const b = new BasicSymbol("foo", scope.symbols, {});
+    flushJobs();
+    expect(a.name).toBe("foo");
+    expect(b.name).toBe("$foo");
+
+    b.delete();
+    flushJobs();
+    // Survivor reverts to the original name regardless of scheme.
+    expect(a.name).toBe("foo");
+    expect(a.deconflictedName).toBeUndefined();
+  });
+
+  it("direct .name assignment does not clear an active deconflictedName", () => {
+    const { scope } = setup();
+    const a = new BasicSymbol("foo", scope.symbols, {});
+    const b = new BasicSymbol("foo", scope.symbols, {});
+    flushJobs();
+    expect(b.name).toBe("foo_2");
+
+    // User-assigns the name while a conflict rename is active.
+    b.name = "bar";
+    // Effective name still shows the deconflict rename (resolver wins while active).
+    expect(b.name).toBe("foo_2");
+
+    // Once the collision clears, the user-assigned name takes effect.
+    a.delete();
+    flushJobs();
+    expect(b.deconflictedName).toBeUndefined();
+    expect(b.name).toBe("bar");
+  });
+
+  it("detects conflict when different original names normalize to the same policy name", () => {
+    // Mirrors PR #394: under camelCase, `foo_bar` and `fooBar` both become
+    // `fooBar` — they collide on the rendered name and should be deconflicted.
+    const toCamel = (n: string) =>
+      n.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+    const { scope } = setup();
+
+    const a = new BasicSymbol("foo_bar", scope.symbols, {
+      namePolicy: toCamel,
+    });
+    const b = new BasicSymbol("fooBar", scope.symbols, {
+      namePolicy: toCamel,
+    });
+    flushJobs();
+
+    expect(a.name).toBe("fooBar");
+    // Without canonical-name grouping, `b` would keep its original `fooBar`
+    // and silently collide with `a`'s policy-applied name.
+    expect(b.name).not.toBe("fooBar");
+    expect(b.name).toMatch(/^fooBar/);
+  });
+
+  it("survivor reverts when the winner is removed (canonical-name cohort lookup)", () => {
+    // After `a` is removed, the delete hook must find `b` as a member of the
+    // same canonical-name cohort so it can clear its deconflictedName.
+    const toCamel = (n: string) =>
+      n.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+    const { scope } = setup();
+
+    const a = new BasicSymbol("foo_bar", scope.symbols, {
+      namePolicy: toCamel,
+    });
+    const b = new BasicSymbol("fooBar", scope.symbols, {
+      namePolicy: toCamel,
+    });
+    flushJobs();
+    expect(b.deconflictedName).toBeDefined();
+
+    a.delete();
+    flushJobs();
+    expect(b.deconflictedName).toBeUndefined();
+    expect(b.name).toBe("fooBar");
+  });
+});

package/test/symbols/output-scope.test.ts

@@ -206,3 +206,41 @@ describe("OutputScope#children", () => {
     expect(child2.parent).toBe(parentScope);
   });
 });
+
+describe("symbol name deduplication with name policy", () => {
+  it("deduplicates symbols whose names collide after name policy", () => {
+    const scope = createScope("scope");
+    const policy = (name: string) => name.toUpperCase();
+    const [s1] = createSymbol("foo", scope, { namePolicy: policy });
+    const [s2] = createSymbol("FOO", scope, { namePolicy: policy });
+
+    flushJobs();
+
+    expect(s1.name).toBe("FOO");
+    expect(s2.name).toBe("FOO_2");
+  });
+
+  it("deduplicates symbols when policy adds a prefix", () => {
+    const scope = createScope("scope");
+    const policy = (name: string) => (name === "reserved" ? `@${name}` : name);
+    const [s1] = createSymbol("reserved", scope, { namePolicy: policy });
+    const [s2] = createSymbol("reserved", scope, { namePolicy: policy });
+
+    flushJobs();
+
+    expect(s1.name).toBe("@reserved");
+    expect(s2.name).toBe("reserved_2");
+  });
+
+  it("does not deduplicates symbols with different names after policy", () => {
+    const scope = createScope("scope");
+    const policy = (name: string) => `prefix_${name}`;
+    const [s1] = createSymbol("foo", scope, { namePolicy: policy });
+    const [s2] = createSymbol("bar", scope, { namePolicy: policy });
+
+    flushJobs();
+
+    expect(s1.name).toBe("prefix_foo");
+    expect(s2.name).toBe("prefix_bar");
+  });
+});