@intentius/chant-lexicon-azure 0.124.30 → 0.124.32

package/dist/serializer.js

@@ -0,0 +1,457 @@
+/**
+ * Azure Resource Manager template serializer.
+ *
+ * Converts Declarable entities into ARM template JSON with:
+ * - resources[] array (not keyed by logical name like CloudFormation)
+ * - apiVersion per resource (from lexicon registry)
+ * - Resource-level fields (sku, kind, identity, tags, zones, plan, location)
+ *   hoisted from properties
+ * - ARM bracket expression references
+ * - parameters, outputs sections
+ */
+import { isPropertyDeclarable, isResourceDeclarable } from "@intentius/chant/declarable";
+import { ownershipEntries } from "@intentius/chant/ownership";
+import { AZURE_TAG_OWNERSHIP_KEYS } from "./ownership.js";
+import { walkValue } from "@intentius/chant/serializer-walker";
+import { isChildProject } from "@intentius/chant/child-project";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
+import { isStackOutput } from "@intentius/chant/stack-output";
+import { isAttrRefLike } from "@intentius/chant/utils";
+import { resolveDependsOn } from "@intentius/chant/resource-attributes";
+import { isDefaultTags } from "./default-tags.js";
+import { loadTaggableResources } from "./taggable.js";
+import { findArmResourceRefs } from "./lint/post-synth/arm-refs.js";
+import { isDeploymentScope, resolveTemplateScope, TEMPLATE_SCHEMAS } from "./deploy-scopes.js";
+/** Check if a declarable is a CoreParameter */
+function isCoreParameter(entity) {
+    return "parameterType" in entity;
+}
+/** Resource-level fields that get hoisted from properties to resource level. */
+const RESOURCE_LEVEL_FIELDS = new Set([
+    "location", "tags", "sku", "kind", "identity", "zones", "plan",
+]);
+/**
+ * Load apiVersion for a resource type from the lexicon registry.
+ *
+ * Reads the generated registry (src/generated/lexicon-azure.json in a dev
+ * checkout, dist/meta.json in the installed package). Resolves the package
+ * directory from import.meta.url so it works under pure ESM as well as
+ * tsx/vitest — the old `require()`-based resolver threw under ESM and the
+ * throw was swallowed, so every resource emitted the fallback apiVersion
+ * (#1581). A missing registry is now an error: a uniform fallback apiVersion
+ * silently bypasses the per-provider pins in spec/api-versions.ts.
+ */
+function resolveDir() {
+    return moduleSourceDir(import.meta.url);
+}
+export function apiVersionRegistryCandidates(dir = resolveDir()) {
+    return [
+        join(dir, "generated", "lexicon-azure.json"),
+        join(dir, "..", "dist", "meta.json"),
+    ];
+}
+export function loadApiVersions(candidates = apiVersionRegistryCandidates()) {
+    const map = new Map();
+    let content;
+    for (const candidate of candidates) {
+        if (!existsSync(candidate))
+            continue;
+        content = readFileSync(candidate, "utf-8");
+        break;
+    }
+    if (content === undefined) {
+        throw new Error(`azure: apiVersion registry not found (tried ${candidates.join(", ")}). ` +
+            "Run `npm run generate` (dev) or reinstall the package (dist/meta.json).");
+    }
+    const data = JSON.parse(content);
+    for (const entry of Object.values(data)) {
+        if (entry.apiVersion && entry.resourceType) {
+            map.set(entry.resourceType, entry.apiVersion);
+        }
+    }
+    if (map.size === 0) {
+        throw new Error("azure: apiVersion registry is empty — regenerate with `npm run generate`");
+    }
+    return map;
+}
+/**
+ * Override stale apiVersions from the generated registry.
+ * These are resource types where the registry apiVersion is known to be
+ * too old for modern ARM features (e.g. DataActions on role assignments).
+ */
+const API_VERSION_OVERRIDES = new Map([
+    ["Microsoft.Authorization/roleAssignments", "2022-04-01"],
+    ["Microsoft.Authorization/roleDefinitions", "2022-04-01"],
+]);
+let _apiVersions;
+/** Test hook: drop the cached registry so the next lookup reloads it. */
+export function resetApiVersionCache() {
+    _apiVersions = undefined;
+}
+/**
+ * Registry lookup without the serializer's fallback: the pinned apiVersion for
+ * `resourceType`, or `undefined` when neither the overrides nor the generated
+ * registry know the type. ARM resource types are case-insensitive and the live
+ * listing does not always echo the casing the registry uses, so the match is
+ * case-insensitive too. Used by prune (#1472), which needs an apiVersion for a
+ * type the current template no longer declares.
+ */
+export function lookupApiVersion(resourceType) {
+    const override = API_VERSION_OVERRIDES.get(resourceType);
+    if (override)
+        return override;
+    if (!_apiVersions)
+        _apiVersions = loadApiVersions();
+    const exact = _apiVersions.get(resourceType);
+    if (exact)
+        return exact;
+    const wanted = resourceType.toLowerCase();
+    for (const [type, version] of _apiVersions) {
+        if (type.toLowerCase() === wanted)
+            return version;
+    }
+    return undefined;
+}
+export function getApiVersion(resourceType) {
+    const version = lookupApiVersion(resourceType);
+    if (version)
+        return version;
+    console.warn(`azure: no pinned apiVersion for ${resourceType} in the lexicon registry; falling back to 2023-01-01`);
+    return "2023-01-01";
+}
+/**
+ * ARM-specific visitor for the generic serializer walker.
+ */
+function armVisitor(entityNames) {
+    return {
+        attrRef: (name, attr) => `[reference('${name}').${attr}]`,
+        resourceRef: (name) => {
+            // Look up the resource type from entityNames
+            const entity = [...entityNames.entries()].find(([, n]) => n === name)?.[0];
+            if (entity) {
+                return `[resourceId('${entity.entityType}', '${name}')]`;
+            }
+            return `[resourceId('${name}')]`;
+        },
+        propertyDeclarable: (entity, walk) => {
+            if (!isResourceDeclarable(entity) || typeof entity.props !== "object" || entity.props === null) {
+                return undefined;
+            }
+            const props = entity.props;
+            const armProps = {};
+            for (const [key, value] of Object.entries(props)) {
+                if (value !== undefined) {
+                    armProps[key] = walk(value);
+                }
+            }
+            return Object.keys(armProps).length > 0 ? armProps : undefined;
+        },
+    };
+}
+/**
+ * Convert a value to ARM-compatible JSON using the generic walker.
+ */
+function toArmValue(value, entityNames) {
+    return walkValue(value, entityNames, armVisitor(entityNames));
+}
+/**
+ * Serialize entities into an ARM template object.
+ */
+function serializeToTemplate(entities, outputs, ownership) {
+    // Resolve the deployment scope from the resource types being emitted
+    // (#1545): a template of tenant-only resources (management groups, policy
+    // definitions at management-group scope, ...) must carry the matching
+    // $schema and must not lean on resourceGroup() expressions. Mixed sets
+    // with no common scope fall back to resource-group scope and AZR030
+    // reports the resources that cannot deploy there. A deploymentScope()
+    // pin overrides the inference — policy definitions and assignments
+    // deploy at several scopes, so a management-group guardrail project
+    // cannot be told from a subscription one by its resource set alone
+    //; AZR030 still flags resources the pinned scope cannot hold.
+    let pinnedScope;
+    const emittedTypes = [];
+    for (const [, entity] of entities) {
+        if (isStackOutput(entity) || isDefaultTags(entity) || isCoreParameter(entity))
+            continue;
+        if (isDeploymentScope(entity)) {
+            pinnedScope ?? (pinnedScope = entity.scope);
+        }
+        else if (isChildProject(entity)) {
+            emittedTypes.push("Microsoft.Resources/deployments");
+        }
+        else if (!isPropertyDeclarable(entity)) {
+            emittedTypes.push(entity.entityType);
+        }
+    }
+    const templateScope = pinnedScope ?? resolveTemplateScope(emittedTypes);
+    const template = {
+        $schema: TEMPLATE_SCHEMAS[templateScope],
+        contentVersion: "1.0.0.0",
+        resources: [],
+    };
+    // Build reverse map: entity -> name
+    const entityNames = new Map();
+    for (const [name, entity] of entities) {
+        entityNames.set(entity, name);
+    }
+    // Collect default tags. The ownership marker is stamped as tags, seeded
+    // first so user default tags (and explicit per-resource tags) win.
+    const defaultTagEntries = [];
+    if (ownership) {
+        for (const [key, value] of Object.entries(ownershipEntries(AZURE_TAG_OWNERSHIP_KEYS, ownership))) {
+            defaultTagEntries.push({ key, value });
+        }
+    }
+    for (const [, entity] of entities) {
+        if (isDefaultTags(entity)) {
+            defaultTagEntries.push(...entity.tags);
+        }
+    }
+    // Process entities
+    for (const [name, entity] of entities) {
+        // Skip non-resource types
+        if (isStackOutput(entity) || isDefaultTags(entity) || isDeploymentScope(entity))
+            continue;
+        if (isCoreParameter(entity)) {
+            if (!template.parameters)
+                template.parameters = {};
+            const param = {
+                type: mapParameterType(entity.parameterType),
+            };
+            if ("description" in entity && typeof entity.description === "string") {
+                param.metadata = { description: entity.description };
+            }
+            if ("defaultValue" in entity && entity.defaultValue !== undefined) {
+                param.defaultValue = entity.defaultValue;
+            }
+            template.parameters[name] = param;
+        }
+        else if (isChildProject(entity)) {
+            // ChildProjectInstance → linked deployment
+            const childProject = entity;
+            const childName = childProject.logicalName;
+            const filename = `${childName}.template.json`;
+            const resource = {
+                type: "Microsoft.Resources/deployments",
+                apiVersion: "2021-04-01",
+                name: childName,
+                properties: {
+                    mode: "Incremental",
+                    templateLink: { uri: filename },
+                },
+            };
+            template.resources.push(resource);
+        }
+        else if (!isPropertyDeclarable(entity)) {
+            const resourceType = entity.entityType;
+            // Prefer apiVersion from entity attributes (set by composites) over registry lookup
+            const attrs0 = (isResourceDeclarable(entity) && typeof entity.attributes === "object" && entity.attributes !== null)
+                ? entity.attributes
+                : undefined;
+            const apiVersion = (typeof attrs0?.apiVersion === "string") ? attrs0.apiVersion : getApiVersion(resourceType);
+            const resource = {
+                type: resourceType,
+                apiVersion,
+                name: name,
+            };
+            // Extract all props
+            if (isResourceDeclarable(entity) && typeof entity.props === "object" && entity.props !== null) {
+                const props = entity.props;
+                const armProperties = {};
+                for (const [key, value] of Object.entries(props)) {
+                    if (value === undefined)
+                        continue;
+                    if (RESOURCE_LEVEL_FIELDS.has(key)) {
+                        // Hoist to resource level
+                        resource[key] = toArmValue(value, entityNames);
+                    }
+                    else if (key === "name") {
+                        resource.name = toArmValue(value, entityNames);
+                    }
+                    else {
+                        armProperties[key] = toArmValue(value, entityNames);
+                    }
+                }
+                if (Object.keys(armProperties).length > 0) {
+                    resource.properties = armProperties;
+                }
+            }
+            // Default location to resource group location if not specified.
+            // Above resource-group scope there is no resource group to read a
+            // location from, and the scoped resources (management groups, policy
+            // definitions, ...) have no location field at all (#1545).
+            if (!resource.location && templateScope === "resourceGroup") {
+                resource.location = "[resourceGroup().location]";
+            }
+            // Handle DependsOn
+            const attrs = (isResourceDeclarable(entity) && typeof entity.attributes === "object" && entity.attributes !== null)
+                ? entity.attributes
+                : undefined;
+            if (attrs?.DependsOn !== undefined) {
+                const resolved = resolveDependsOn(attrs.DependsOn, entityNames, name);
+                if (resolved.length > 0) {
+                    resource.dependsOn = resolved.map((dep) => {
+                        // Convert to resourceId expression
+                        const depEntity = [...entityNames.entries()].find(([, n]) => n === dep)?.[0];
+                        if (depEntity) {
+                            return `[resourceId('${depEntity.entityType}', '${dep}')]`;
+                        }
+                        return dep;
+                    });
+                }
+            }
+            template.resources.push(resource);
+        }
+    }
+    // Inject default tags into taggable resources
+    if (defaultTagEntries.length > 0) {
+        const taggable = loadTaggableResources();
+        for (const resource of template.resources) {
+            if (!taggable.has(resource.type))
+                continue;
+            const resolved = {};
+            for (const t of defaultTagEntries) {
+                resolved[t.key] = toArmValue(t.value, entityNames);
+            }
+            const existing = resource.tags ?? {};
+            // Explicit tags take precedence
+            resource.tags = { ...resolved, ...existing };
+        }
+    }
+    // Auto-infer dependsOn from resourceId()/reference() expressions in properties.
+    // ARM only auto-infers dependencies from reference(), not resourceId().
+    const resourceNameSet = new Set(template.resources.map((r) => r.name));
+    for (const resource of template.resources) {
+        const refs = findArmResourceRefs(resource.properties);
+        // Also scan resource-level fields (location, tags, identity, etc.)
+        for (const field of RESOURCE_LEVEL_FIELDS) {
+            const val = resource[field];
+            if (val !== undefined) {
+                for (const ref of findArmResourceRefs(val)) {
+                    refs.add(ref);
+                }
+            }
+        }
+        // Also scan the name field for parent references (e.g. "vnet/subnet")
+        if (typeof resource.name === "string") {
+            for (const ref of findArmResourceRefs(resource.name)) {
+                refs.add(ref);
+            }
+        }
+        // Infer parent dependency for child resources (e.g. "vnet/subnet" depends on "vnet")
+        if (typeof resource.name === "string" && resource.name.includes("/")) {
+            const parentName = resource.name.split("/")[0];
+            if (resourceNameSet.has(parentName)) {
+                refs.add(parentName);
+            }
+        }
+        if (refs.size > 0) {
+            const existing = new Set(resource.dependsOn ?? []);
+            for (const refName of refs) {
+                // Only add if the referenced resource exists in this template and isn't self
+                if (refName === resource.name)
+                    continue;
+                if (!resourceNameSet.has(refName))
+                    continue;
+                // Find the resource to build the resourceId expression
+                const depResource = template.resources.find((r) => r.name === refName);
+                if (depResource) {
+                    const depExpr = `[resourceId('${depResource.type}', '${refName}')]`;
+                    if (!existing.has(depExpr)) {
+                        existing.add(depExpr);
+                    }
+                }
+            }
+            if (existing.size > 0) {
+                resource.dependsOn = [...existing];
+            }
+        }
+    }
+    // Emit StackOutput entities as ARM outputs
+    for (const [name, entity] of entities) {
+        if (isStackOutput(entity)) {
+            if (!template.outputs)
+                template.outputs = {};
+            const stackOutput = entity;
+            // `unknown` so isAttrRefLike narrows cleanly across the workspace/published
+            // type boundary. An intrinsic-wrapped output (#517) has no bare ARM
+            // reference form, so skip it here (only aws/CFN emits those).
+            const ref = stackOutput.sourceRef;
+            if (isAttrRefLike(ref)) {
+                const logicalName = ref.getLogicalName();
+                if (logicalName) {
+                    template.outputs[name] = {
+                        type: "string",
+                        value: `[reference('${logicalName}').${ref.attribute}]`,
+                    };
+                }
+            }
+        }
+    }
+    // Add LexiconOutputs
+    if (outputs && outputs.length > 0) {
+        template.outputs = template.outputs ?? {};
+        for (const output of outputs) {
+            template.outputs[output.outputName] = {
+                type: "string",
+                value: `[reference('${output.sourceEntity}').${output.sourceAttribute}]`,
+            };
+        }
+    }
+    return template;
+}
+/**
+ * Map chant parameter types to ARM parameter types.
+ */
+function mapParameterType(paramType) {
+    switch (paramType) {
+        case "String": return "string";
+        case "Number": return "int";
+        case "CommaDelimitedList": return "array";
+        default: return "string";
+    }
+}
+/**
+ * Azure ARM template serializer implementation.
+ */
+export const azureSerializer = {
+    name: "azure",
+    rulePrefix: "AZR",
+    serialize(entities, outputs, context) {
+        // Check for child projects (linked templates)
+        let hasChildProjects = false;
+        const allFiles = {};
+        for (const [, entity] of entities) {
+            if (isChildProject(entity)) {
+                hasChildProjects = true;
+                const childProject = entity;
+                if (childProject.buildResult) {
+                    const childOutput = childProject.buildResult.outputs.get("azure");
+                    if (childOutput) {
+                        const childName = childProject.logicalName;
+                        const filename = `${childName}.template.json`;
+                        if (typeof childOutput === "string") {
+                            allFiles[filename] = childOutput;
+                        }
+                        else {
+                            allFiles[filename] = childOutput.primary;
+                            if (childOutput.files) {
+                                for (const [f, c] of Object.entries(childOutput.files)) {
+                                    allFiles[f] = c;
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        const template = serializeToTemplate(entities, outputs, context?.ownership);
+        const primary = JSON.stringify(template, null, 2);
+        if (!hasChildProjects) {
+            return primary;
+        }
+        return { primary, files: allFiles };
+    },
+};

package/dist/spec/api-versions.js

@@ -0,0 +1,130 @@
+/**
+ * API version resolution for Azure Resource Manager schemas.
+ *
+ * ARM schemas are organized by API date:
+ *   schemas/{date}/Microsoft.{Provider}.json
+ *
+ * This module picks the latest API version per provider.
+ */
+/**
+ * Parse an API date string (e.g. "2023-01-01" or "2023-01-01-preview").
+ * Returns a numeric value for comparison: date timestamp with preview
+ * versions ranked below their GA counterpart.
+ */
+export function parseApiDate(dateStr) {
+    const isPreview = dateStr.endsWith("-preview");
+    const cleaned = isPreview ? dateStr.replace(/-preview$/, "") : dateStr;
+    const ts = new Date(cleaned).getTime();
+    // Preview versions sort just below their GA date
+    return isPreview ? ts - 1 : ts;
+}
+/**
+ * Compare two API date strings. Returns positive if a > b.
+ */
+export function compareApiDates(a, b) {
+    return parseApiDate(a) - parseApiDate(b);
+}
+/**
+ * Extract provider name and API version from a schema file path.
+ *
+ * Input:  "azure-resource-manager-schemas-main/schemas/2023-01-01/Microsoft.Storage.json"
+ * Output: { provider: "Microsoft.Storage", apiVersion: "2023-01-01" }
+ */
+export function parseSchemaPath(path) {
+    // Match schemas/{date}/Microsoft.{Provider}.json
+    const match = path.match(/schemas\/(\d{4}-\d{2}-\d{2}(?:-preview)?)\/(Microsoft\.[^/]+)\.json$/);
+    if (!match)
+        return null;
+    return { apiVersion: match[1], provider: match[2] };
+}
+/**
+ * Per-provider API-version pins.
+ *
+ * `latestVersionPerProvider` picks the single newest version per provider, but
+ * Azure spreads resources across versions — a newer version can DROP a resource
+ * an older one defined. Microsoft.Authorization's latest preview no longer
+ * includes the plain `roleAssignments` / `roleDefinitions` resources; they live
+ * in 2022-04-01, the latest stable that still has them. Pin it so those
+ * generate (the naming table maps both). See #223.
+ *
+ * Microsoft.Compute has the same issue (#1144): at the schema commit pinned
+ * in ../spec/fetch.ts, the newest dated `Microsoft.Compute.json` (2026-03-02)
+ * is a narrow disk-only delta that drops `virtualMachines`,
+ * `virtualMachineScaleSets`, and `availabilitySets` entirely — not a rename,
+ * an omission, since Azure alternates between a "VM flavor" and a "disk
+ * flavor" of this file across dates rather than publishing one cumulative
+ * file. 2026-03-01 is the most recent date that still has the VM family
+ * (validate.ts's REQUIRED_NAMES and composites/vm-linux.ts depend on it);
+ * it drops the disk-only resources (disks, diskAccesses, diskEncryptionSets,
+ * snapshots), which nothing here currently references.
+ *
+ * A pin can list several versions (#1545): Azure publishes some providers as
+ * per-family deltas, so no single date carries every resource we need. The
+ * files merge in the order listed — the first file that defines a resource
+ * name wins, later files only contribute resources not yet seen.
+ * Microsoft.Authorization needs three: 2022-04-01 for roleAssignments /
+ * roleDefinitions (#223), 2026-06-01 (latest stable policy file) for
+ * policyAssignments / policyDefinitions / policySetDefinitions and their
+ * _versions children, and 2022-07-01-preview for policyExemptions, which has
+ * no GA date and whose newer preview files (2024-12-01-preview and later)
+ * drag in policy variables we don't want yet.
+ *
+ * Microsoft.AzureStackHCI splits the same way (#1795): the newest dated file
+ * (2026-05-01-preview) carries only the cluster/edge-device family, while the
+ * VM family (virtualMachineInstances, virtualNetworks, networkInterfaces,
+ * publicIPAddresses, galleryImages, virtualHardDisks, ...) last appears in
+ * 2026-04-01-preview. Pin both, newest first — the cluster/edge family
+ * generates from 2026-05-01-preview and the VM family fills in from
+ * 2026-04-01-preview. `Microsoft.DataReplication/replicationVaults_
+ * privateEndpointConnectionProxies` dropped out in the same re-baseline but
+ * is NOT pinnable back: no dated Microsoft.DataReplication.json at the
+ * AZURE_SCHEMA_COMMIT pin (2021-02-16-preview, 2024-09-01, 2026-05-01)
+ * defines it — upstream removed the resource, so it stays gone.
+ *
+ * Microsoft.Management and Microsoft.Subscription are pinned to their latest
+ * GA dates: the naive latest for both is a preview (2024-02-01-preview adds
+ * serviceGroups; 2025-11-01-preview adds changeTenantRequest), and the
+ * management-group hierarchy should not author against preview apiVersions.
+ */
+export const PROVIDER_VERSION_OVERRIDES = {
+    "Microsoft.Authorization": ["2022-04-01", "2026-06-01", "2022-07-01-preview"],
+    "Microsoft.AzureStackHCI": ["2026-05-01-preview", "2026-04-01-preview"],
+    "Microsoft.Compute": ["2026-03-01"],
+    "Microsoft.Management": ["2023-04-01"],
+    "Microsoft.Subscription": ["2021-10-01"],
+};
+/**
+ * Given a set of schema paths, return the schema files to generate from, per
+ * provider: the single latest API version, unless
+ * {@link PROVIDER_VERSION_OVERRIDES} pins the provider to one or more chosen
+ * versions (used where "latest" drops resources we depend on). For pinned
+ * providers the array preserves the pin order — callers merge the files
+ * first-wins per resource name.
+ *
+ * Returns a Map of provider → [{ path, apiVersion }, ...].
+ */
+export function latestVersionPerProvider(paths) {
+    const best = new Map();
+    for (const p of paths) {
+        const parsed = parseSchemaPath(p);
+        if (!parsed)
+            continue;
+        const pinned = PROVIDER_VERSION_OVERRIDES[parsed.provider];
+        if (pinned) {
+            // Only accept the pinned versions for an overridden provider,
+            // slotted into pin order.
+            if (pinned.includes(parsed.apiVersion)) {
+                const files = best.get(parsed.provider) ?? [];
+                files.push({ path: p, apiVersion: parsed.apiVersion });
+                files.sort((a, b) => pinned.indexOf(a.apiVersion) - pinned.indexOf(b.apiVersion));
+                best.set(parsed.provider, files);
+            }
+            continue;
+        }
+        const existing = best.get(parsed.provider);
+        if (!existing || compareApiDates(parsed.apiVersion, existing[0].apiVersion) > 0) {
+            best.set(parsed.provider, [{ path: p, apiVersion: parsed.apiVersion }]);
+        }
+    }
+    return best;
+}