@typespec/versioning 0.57.0-dev.5 → 0.57.0-dev.7

package/dist/src/versioning.js

@@ -1,383 +1,12 @@
-import { compilerAssert, getNamespaceFullName, } from "@typespec/compiler";
-import { createStateSymbol, reportDiagnostic } from "./lib.js";
-import { VersioningTimeline } from "./versioning-timeline.js";
-const addedOnKey = createStateSymbol("addedOn");
-const removedOnKey = createStateSymbol("removedOn");
-const versionsKey = createStateSymbol("versions");
-const versionDependencyKey = createStateSymbol("versionDependency");
-const useDependencyNamespaceKey = createStateSymbol("useDependencyNamespace");
-const useDependencyEnumKey = createStateSymbol("useDependencyEnum");
-const renamedFromKey = createStateSymbol("renamedFrom");
-const madeOptionalKey = createStateSymbol("madeOptional");
-const madeRequiredKey = createStateSymbol("madeRequired");
-const typeChangedFromKey = createStateSymbol("typeChangedFrom");
-const returnTypeChangedFromKey = createStateSymbol("returnTypeChangedFrom");
-export const namespace = "TypeSpec.Versioning";
-function checkIsVersion(program, enumMember, diagnosticTarget) {
-    const version = getVersionForEnumMember(program, enumMember);
-    if (!version) {
-        reportDiagnostic(program, {
-            code: "version-not-found",
-            target: diagnosticTarget,
-            format: { version: enumMember.name, enumName: enumMember.enum.name },
-        });
-    }
-    return version;
-}
-export const $added = (context, t, v) => {
-    const { program } = context;
-    const version = checkIsVersion(context.program, v, context.getArgumentTarget(0));
-    if (!version) {
-        return;
-    }
-    // retrieve statemap to update or create a new one
-    const record = program.stateMap(addedOnKey).get(t) ?? new Array();
-    record.push(version);
-    // ensure that records are stored in ascending order
-    record.sort((a, b) => a.index - b.index);
-    program.stateMap(addedOnKey).set(t, record);
-};
-export function $removed(context, t, v) {
-    const { program } = context;
-    const version = checkIsVersion(context.program, v, context.getArgumentTarget(0));
-    if (!version) {
-        return;
-    }
-    // retrieve statemap to update or create a new one
-    const record = program.stateMap(removedOnKey).get(t) ?? new Array();
-    record.push(version);
-    // ensure that records are stored in ascending order
-    record.sort((a, b) => a.index - b.index);
-    program.stateMap(removedOnKey).set(t, record);
-}
-/**
- * Returns the mapping of versions to old type values, if applicable
- * @param p TypeSpec program
- * @param t type to query
- * @returns Map of versions to old types, if any
- */
-export function getTypeChangedFrom(p, t) {
-    return p.stateMap(typeChangedFromKey).get(t);
-}
-export const $typeChangedFrom = (context, prop, v, oldType) => {
-    const { program } = context;
-    const version = checkIsVersion(context.program, v, context.getArgumentTarget(0));
-    if (!version) {
-        return;
-    }
-    // retrieve statemap to update or create a new one
-    let record = getTypeChangedFrom(program, prop) ?? new Map();
-    record.set(version, oldType);
-    // ensure the map is sorted by version
-    record = new Map([...record.entries()].sort((a, b) => a[0].index - b[0].index));
-    program.stateMap(typeChangedFromKey).set(prop, record);
-};
-/**
- * Returns the mapping of versions to old return type values, if applicable
- * @param p TypeSpec program
- * @param t type to query
- * @returns Map of versions to old types, if any
- */
-export function getReturnTypeChangedFrom(p, t) {
-    return p.stateMap(returnTypeChangedFromKey).get(t);
-}
-export const $returnTypeChangedFrom = (context, op, v, oldReturnType) => {
-    const { program } = context;
-    const version = checkIsVersion(context.program, v, context.getArgumentTarget(0));
-    if (!version) {
-        return;
-    }
-    // retrieve statemap to update or create a new one
-    let record = getReturnTypeChangedFrom(program, op) ?? new Map();
-    record.set(version, oldReturnType);
-    // ensure the map is sorted by version
-    record = new Map([...record.entries()].sort((a, b) => a[0].index - b[0].index));
-    program.stateMap(returnTypeChangedFromKey).set(op, record);
-};
-export const $renamedFrom = (context, t, v, oldName) => {
-    const { program } = context;
-    const version = checkIsVersion(context.program, v, context.getArgumentTarget(0));
-    if (!version) {
-        return;
-    }
-    if (oldName === "") {
-        reportDiagnostic(program, {
-            code: "invalid-renamed-from-value",
-            target: t,
-        });
-    }
-    // retrieve statemap to update or create a new one
-    const record = getRenamedFrom(program, t) ?? [];
-    record.push({ version: version, oldName: oldName });
-    // ensure that records are stored in ascending order
-    record.sort((a, b) => a.version.index - b.version.index);
-    program.stateMap(renamedFromKey).set(t, record);
-};
-export const $madeOptional = (context, t, v) => {
-    const { program } = context;
-    const version = checkIsVersion(context.program, v, context.getArgumentTarget(0));
-    if (!version) {
-        return;
-    }
-    program.stateMap(madeOptionalKey).set(t, version);
-};
-export const $madeRequired = (context, t, v) => {
-    const { program } = context;
-    const version = checkIsVersion(context.program, v, context.getArgumentTarget(0));
-    if (!version) {
-        return;
-    }
-    program.stateMap(madeRequiredKey).set(t, version);
-};
-/**
- * @returns the array of RenamedFrom metadata if applicable.
- */
-export function getRenamedFrom(p, t) {
-    return p.stateMap(renamedFromKey).get(t);
-}
-/**
- * @returns the list of versions for which this decorator has been applied
- */
-export function getRenamedFromVersions(p, t) {
-    return getRenamedFrom(p, t)?.map((x) => x.version);
-}
-/**
- * @returns get old name if applicable.
- */
-export function getNameAtVersion(p, t, versionKey) {
-    const versioningState = getVersioningState(p, versionKey);
-    const allValues = getRenamedFrom(p, t);
-    if (!allValues)
-        return "";
-    for (const val of allValues) {
-        if (versioningState.timeline.isBefore(versioningState.projectingMoment, val.version)) {
-            return val.oldName;
-        }
-    }
-    return "";
-}
-/**
- * @returns get old type if applicable.
- */
-export function getTypeBeforeVersion(p, t, versionKey) {
-    const versioningState = getVersioningState(p, versionKey);
-    const map = getTypeChangedFrom(p, t);
-    if (!map)
-        return undefined;
-    for (const [changedAtVersion, oldType] of map) {
-        if (versioningState.timeline.isBefore(versioningState.projectingMoment, changedAtVersion)) {
-            return oldType;
-        }
-    }
-    return undefined;
-}
-/**
- * @returns get old type if applicable.
- */
-export function getReturnTypeBeforeVersion(p, t, versionKey) {
-    const versioningState = getVersioningState(p, versionKey);
-    const map = getReturnTypeChangedFrom(p, t);
-    if (!map)
-        return "";
-    for (const [changedAtVersion, val] of map) {
-        if (versioningState.timeline.isBefore(versioningState.projectingMoment, changedAtVersion)) {
-            return val;
-        }
-    }
-    return "";
-}
-export function getAddedOnVersions(p, t) {
-    return p.stateMap(addedOnKey).get(t);
-}
-export function getRemovedOnVersions(p, t) {
-    return p.stateMap(removedOnKey).get(t);
-}
-/**
- * @returns version when the given type was made optional if applicable.
- */
-export function getMadeOptionalOn(p, t) {
-    return p.stateMap(madeOptionalKey).get(t);
-}
-/**
- * @returns version when the given type was made required if applicable.
- */
-export function getMadeRequiredOn(p, t) {
-    return p.stateMap(madeRequiredKey).get(t);
-}
-export class VersionMap {
-    map = new Map();
-    constructor(namespace, enumType) {
-        let index = 0;
-        for (const member of enumType.members.values()) {
-            this.map.set(member, {
-                name: member.name,
-                value: member.value?.toString() ?? member.name,
-                enumMember: member,
-                index,
-                namespace,
-            });
-            index++;
-        }
-    }
-    getVersionForEnumMember(member) {
-        return this.map.get(member);
-    }
-    getVersions() {
-        return [...this.map.values()];
-    }
-    get size() {
-        return this.map.size;
-    }
-}
-export const $versioned = (context, t, versions) => {
-    context.program.stateMap(versionsKey).set(t, new VersionMap(t, versions));
-};
-/**
- * Get the version map of the namespace.
- */
-export function getVersion(program, namespace) {
-    return program.stateMap(versionsKey).get(namespace);
-}
-export function findVersionedNamespace(program, namespace) {
-    let current = namespace;
-    while (current) {
-        if (program.stateMap(versionsKey).has(current)) {
-            return current;
-        }
-        current = current.namespace;
-    }
-    return undefined;
-}
-export function $useDependency(context, target, ...versionRecords) {
-    const versions = [];
-    // ensure only valid versions are passed in
-    for (const record of versionRecords) {
-        const ver = checkIsVersion(context.program, record, context.getArgumentTarget(0));
-        if (ver) {
-            versions.push(ver);
-        }
-    }
-    if (target.kind === "Namespace") {
-        let state = context.program.stateMap(useDependencyNamespaceKey).get(target);
-        if (!state) {
-            state = versions;
-        }
-        else {
-            state.push(...versions);
-        }
-        context.program.stateMap(useDependencyNamespaceKey).set(target, state);
-    }
-    else if (target.kind === "EnumMember") {
-        const targetEnum = target.enum;
-        let state = context.program.stateMap(useDependencyEnumKey).get(targetEnum);
-        if (!state) {
-            state = new Map();
-        }
-        // get any existing versions and combine them
-        const currentVersions = state.get(target) ?? [];
-        currentVersions.push(...versions);
-        state.set(target, currentVersions);
-        context.program.stateMap(useDependencyEnumKey).set(targetEnum, state);
-    }
-}
-export function getUseDependencies(program, target, searchEnum = true) {
-    const result = new Map();
-    if (target.kind === "Namespace") {
-        let current = target;
-        while (current) {
-            const data = program.stateMap(useDependencyNamespaceKey).get(current);
-            if (!data) {
-                // See if the namspace has a version enum
-                if (searchEnum) {
-                    const versions = getVersion(program, current)?.getVersions();
-                    if (versions?.length) {
-                        const enumDeps = getUseDependencies(program, versions[0].enumMember.enum);
-                        if (enumDeps) {
-                            return enumDeps;
-                        }
-                    }
-                }
-                current = current.namespace;
-            }
-            else {
-                for (const v of data) {
-                    result.set(v.namespace, v);
-                }
-                return result;
-            }
-        }
-        return undefined;
-    }
-    else if (target.kind === "Enum") {
-        const data = program.stateMap(useDependencyEnumKey).get(target);
-        if (!data) {
-            return undefined;
-        }
-        const resolved = resolveVersionDependency(program, data);
-        if (resolved instanceof Map) {
-            for (const [enumVer, value] of resolved) {
-                for (const val of value) {
-                    const targetNamespace = val.enumMember.enum.namespace;
-                    if (!targetNamespace) {
-                        reportDiagnostic(program, {
-                            code: "version-not-found",
-                            target: val.enumMember.enum,
-                            format: { version: val.enumMember.name, enumName: val.enumMember.enum.name },
-                        });
-                        return undefined;
-                    }
-                    let subMap = result.get(targetNamespace);
-                    if (subMap) {
-                        subMap.set(enumVer, val);
-                    }
-                    else {
-                        subMap = new Map([[enumVer, val]]);
-                    }
-                    result.set(targetNamespace, subMap);
-                }
-            }
-        }
-    }
-    return result;
-}
-function findVersionDependencyForNamespace(program, namespace) {
-    let current = namespace;
-    while (current) {
-        const data = program.stateMap(versionDependencyKey).get(current);
-        if (data) {
-            return data;
-        }
-        current = current.namespace;
-    }
-    return undefined;
-}
+import { getNamespaceFullName, } from "@typespec/compiler";
+import { getAddedOnVersions, getRemovedOnVersions, getReturnTypeChangedFrom, getTypeChangedFrom, getUseDependencies, getVersion, } from "./decorators.js";
+import { TimelineMoment, VersioningTimeline } from "./versioning-timeline.js";
 export function getVersionDependencies(program, namespace) {
     const useDeps = getUseDependencies(program, namespace);
     if (useDeps) {
         return useDeps;
     }
-    const data = findVersionDependencyForNamespace(program, namespace);
-    if (data === undefined) {
-        return undefined;
-    }
-    const result = new Map();
-    for (const [key, value] of data) {
-        result.set(key, resolveVersionDependency(program, value));
-    }
-    return result;
-}
-function resolveVersionDependency(program, data) {
-    if (!(data instanceof Map)) {
-        return data;
-    }
-    const mapping = new Map();
-    for (const [key, value] of data) {
-        const sourceVersion = getVersionForEnumMember(program, key);
-        if (sourceVersion !== undefined) {
-            mapping.set(sourceVersion, value);
-        }
-    }
-    return mapping;
+    return undefined;
 }
 /**
  * Resolve the version of dependencies
@@ -441,42 +70,6 @@ export function resolveVersions(program, namespace) {
         });
     }
 }
-/**
- * @internal
- */
-export function indexTimeline(program, timeline, projectingMoment) {
-    const versionKey = program.checker.createType({
-        kind: "Object",
-        properties: {},
-    });
-    program.stateMap(versionIndexKey).set(versionKey, { timeline, projectingMoment });
-    return versionKey;
-}
-function getVersioningState(program, versionKey) {
-    return program.stateMap(versionIndexKey).get(versionKey);
-}
-const versionIndexKey = createStateSymbol("version-index");
-export function buildVersionProjections(program, rootNs) {
-    const resolutions = resolveVersions(program, rootNs);
-    const timeline = new VersioningTimeline(program, resolutions.map((x) => x.versions));
-    return resolutions.map((resolution) => {
-        if (resolution.versions.size === 0) {
-            return { version: undefined, projections: [] };
-        }
-        else {
-            const versionKey = indexTimeline(program, timeline, timeline.get(resolution.versions.values().next().value));
-            return {
-                version: resolution.rootVersion?.value,
-                projections: [
-                    {
-                        projectionName: "v",
-                        arguments: [versionKey],
-                    },
-                ],
-            };
-        }
-    });
-}
 const versionCache = new WeakMap();
 function cacheVersion(key, versions) {
     versionCache.set(key, versions);
@@ -561,13 +154,58 @@ export var Availability;
     Availability["Available"] = "Available";
     Availability["Removed"] = "Removed";
 })(Availability || (Availability = {}));
+function getParentAddedVersion(program, type, versions) {
+    let parentMap = undefined;
+    if (type.kind === "ModelProperty" && type.model !== undefined) {
+        parentMap = getAvailabilityMap(program, type.model);
+    }
+    else if (type.kind === "Operation" && type.interface !== undefined) {
+        parentMap = getAvailabilityMap(program, type.interface);
+    }
+    if (parentMap === undefined)
+        return undefined;
+    for (const [key, value] of parentMap.entries()) {
+        if (value === Availability.Added) {
+            return versions.find((x) => x.name === key);
+        }
+    }
+    return undefined;
+}
+function getParentAddedVersionInTimeline(program, type, timeline) {
+    let parentMap = undefined;
+    if (type.kind === "ModelProperty" && type.model !== undefined) {
+        parentMap = getAvailabilityMapInTimeline(program, type.model, timeline);
+    }
+    else if (type.kind === "Operation" && type.interface !== undefined) {
+        parentMap = getAvailabilityMapInTimeline(program, type.interface, timeline);
+    }
+    if (parentMap === undefined)
+        return undefined;
+    for (const [moment, availability] of parentMap.entries()) {
+        if (availability === Availability.Added) {
+            return moment.versions().next().value;
+        }
+    }
+    return undefined;
+}
+/**
+ * Returns true if the first version modifier was @added, false if @removed.
+ */
+function resolveAddedFirst(added, removed) {
+    if (added.length === 0)
+        return false;
+    if (removed.length === 0)
+        return true;
+    return added[0].index < removed[0].index;
+}
 export function getAvailabilityMap(program, type) {
     const avail = new Map();
     const allVersions = getAllVersions(program, type);
     // if unversioned then everything exists
     if (allVersions === undefined)
         return undefined;
-    const added = getAddedOnVersions(program, type) ?? [];
+    const parentAdded = getParentAddedVersion(program, type, allVersions);
+    let added = getAddedOnVersions(program, type) ?? [];
     const removed = getRemovedOnVersions(program, type) ?? [];
     const typeChanged = getTypeChangedFrom(program, type);
     const returnTypeChanged = getReturnTypeChangedFrom(program, type);
@@ -579,28 +217,25 @@ export function getAvailabilityMap(program, type) {
         typeChanged === undefined &&
         returnTypeChanged === undefined)
         return undefined;
-    let parentMap = undefined;
-    if (type.kind === "ModelProperty" && type.model !== undefined) {
-        parentMap = getAvailabilityMap(program, type.model);
+    const wasAddedFirst = resolveAddedFirst(added, removed);
+    // implicitly, all versioned things are assumed to have been added at
+    // v1 if not specified, or inherited from their parent.
+    if (!wasAddedFirst && !parentAdded) {
+        // if the first version modifier was @removed, and the parent is implicitly available,
+        // then assume the type was available.
+        added = [allVersions[0], ...added];
     }
-    else if (type.kind === "Operation" && type.interface !== undefined) {
-        parentMap = getAvailabilityMap(program, type.interface);
+    else if (!added.length && !parentAdded) {
+        // no version information on the item or its parent implicitly means it has always been available
+        added.push(allVersions[0]);
     }
-    // implicitly, all versioned things are assumed to have been added at
-    // v1 if not specified
-    if (!added.length) {
-        if (parentMap !== undefined) {
-            parentMap.forEach((key, value) => {
-                if (key === Availability.Added.valueOf()) {
-                    const match = allVersions.find((x) => x.name === value);
-                    compilerAssert(match !== undefined, "Version not found");
-                    added.push(match);
-                }
-            });
-        }
-        else {
-            added.push(allVersions[0]);
-        }
+    else if (!added.length && parentAdded) {
+        // if no version info on type but is on parent, inherit that parent's "added" version
+        added.push(parentAdded);
+    }
+    else if (added.length && parentAdded) {
+        // if "added" info on both the type and parent, combine them
+        added = [parentAdded, ...added];
     }
     // something isn't available by default
     let isAvail = false;
@@ -626,7 +261,8 @@ export function getAvailabilityMap(program, type) {
 }
 export function getAvailabilityMapInTimeline(program, type, timeline) {
     const avail = new Map();
-    const added = getAddedOnVersions(program, type) ?? [];
+    const parentAdded = getParentAddedVersionInTimeline(program, type, timeline);
+    let added = getAddedOnVersions(program, type) ?? [];
     const removed = getRemovedOnVersions(program, type) ?? [];
     const typeChanged = getTypeChangedFrom(program, type);
     const returnTypeChanged = getReturnTypeChangedFrom(program, type);
@@ -638,10 +274,26 @@ export function getAvailabilityMapInTimeline(program, type, timeline) {
         typeChanged === undefined &&
         returnTypeChanged === undefined)
         return undefined;
+    const wasAddedFirst = resolveAddedFirst(added, removed);
     // implicitly, all versioned things are assumed to have been added at
-    // v1 if not specified
-    if (!added.length) {
-        added.push(timeline.first().versions().next().value);
+    // v1 if not specified, or inherited from their parent.
+    const firstVersion = timeline.first().versions().next().value;
+    if (!wasAddedFirst && !parentAdded) {
+        // if the first version modifier was @removed, and the parent is implicitly available,
+        // then assume the type was available.
+        added = [firstVersion, ...added];
+    }
+    else if (!added.length && !parentAdded) {
+        // no version information on the item or its parent implicitly means it has always been available
+        added.push(firstVersion);
+    }
+    else if (!added.length && parentAdded) {
+        // if no version info on type but is on parent, inherit that parent's "added" version
+        added.push(parentAdded);
+    }
+    else if (added.length && parentAdded) {
+        // if "added" info on both the type and parent, combine them
+        added = [parentAdded, ...added];
     }
     // something isn't available by default
     let isAvail = false;
@@ -665,40 +317,6 @@ export function getAvailabilityMapInTimeline(program, type, timeline) {
     }
     return avail;
 }
-export function existsAtVersion(p, type, versionKey) {
-    const versioningState = getVersioningState(p, versionKey);
-    // if unversioned then everything exists
-    const availability = getAvailabilityMapInTimeline(p, type, versioningState.timeline);
-    if (!availability)
-        return true;
-    const isAvail = availability.get(versioningState.projectingMoment);
-    return isAvail === Availability.Added || isAvail === Availability.Available;
-}
-export function hasDifferentNameAtVersion(p, type, version) {
-    return getNameAtVersion(p, type, version) !== "";
-}
-export function madeOptionalAfter(program, type, versionKey) {
-    const versioningState = getVersioningState(program, versionKey);
-    const madeOptionalAtVersion = getMadeOptionalOn(program, type);
-    if (madeOptionalAtVersion === undefined) {
-        return false;
-    }
-    return versioningState.timeline.isBefore(versioningState.projectingMoment, madeOptionalAtVersion);
-}
-export function madeRequiredAfter(program, type, versionKey) {
-    const versioningState = getVersioningState(program, versionKey);
-    const madeRequiredAtVersion = getMadeRequiredOn(program, type);
-    if (madeRequiredAtVersion === undefined) {
-        return false;
-    }
-    return versioningState.timeline.isBefore(versioningState.projectingMoment, madeRequiredAtVersion);
-}
-export function hasDifferentTypeAtVersion(p, type, version) {
-    return getTypeBeforeVersion(p, type, version) !== undefined;
-}
-export function hasDifferentReturnTypeAtVersion(p, type, version) {
-    return getReturnTypeBeforeVersion(p, type, version) !== "";
-}
 export function getVersionForEnumMember(program, member) {
     // Always lookup for the original type. This ensure reference equality when comparing versions.
     member = member.projectionBase ?? member;