altium-toolkit 1.1.3 → 1.1.23

package/src/core/altium/PcbLayerStackInterchangeParser.mjs

@@ -31,10 +31,9 @@ export class PcbLayerStackInterchangeParser {
      */
     static parseText(fileName, text) {
         const format = PcbLayerStackInterchangeParser.#format(fileName, text)
-        const fields =
-            format === 'stackupx'
-                ? PcbLayerStackInterchangeParser.#stackupxFields(text)
-                : PcbLayerStackInterchangeParser.#stackupFields(text)
+        const fields = PcbLayerStackInterchangeParser.parseTextToFields(text, {
+            format
+        })
         const layers = AltiumLayoutParser.parseLayerStack(fields)
         const layerSubstacks =
             PcbBoardRegionSemanticsParser.parseLayerSubstacks([fields])
@@ -57,6 +56,21 @@ export class PcbLayerStackInterchangeParser {
         }
     }
 
+    /**
+     * Converts layer-stack interchange text into board-compatible fields.
+     * @param {string} text Source text.
+     * @param {{ format?: 'stackup' | 'stackupx' }} options Parse options.
+     * @returns {Record<string, string>}
+     */
+    static parseTextToFields(text, options = {}) {
+        const format =
+            options.format || PcbLayerStackInterchangeParser.#format('', text)
+
+        return format === 'stackupx'
+            ? PcbLayerStackInterchangeParser.#stackupxFields(text)
+            : PcbLayerStackInterchangeParser.#stackupFields(text)
+    }
+
     /**
      * Detects the interchange format.
      * @param {string} fileName Source file name.
@@ -114,6 +128,14 @@ export class PcbLayerStackInterchangeParser {
     static #stackupxFields(text) {
         const fields = {}
 
+        if (PcbLayerStackInterchangeParser.#hasTag(text, 'StackupDocument')) {
+            PcbLayerStackInterchangeParser.#assignStackupDocumentFields(
+                fields,
+                text
+            )
+            return fields
+        }
+
         for (const layer of PcbLayerStackInterchangeParser.#tagFields(text, [
             'Layer'
         ])) {
@@ -169,6 +191,243 @@ export class PcbLayerStackInterchangeParser {
         return fields
     }
 
+    /**
+     * Converts StackupDocument XML into board-compatible fields.
+     * @param {Record<string, string>} fields Target fields.
+     * @param {string} text Source XML text.
+     * @returns {void}
+     */
+    static #assignStackupDocumentFields(fields, text) {
+        const document = PcbLayerStackInterchangeParser.#tagBlocks(text, [
+            'StackupDocument'
+        ])[0]
+
+        if (!document) {
+            return
+        }
+
+        PcbLayerStackInterchangeParser.#assignTopLevelFields(
+            fields,
+            'STACKUPX',
+            document.fields,
+            {
+                SerializerVersion: 'SERIALIZER_VERSION',
+                RevisionId: 'REVISION_ID'
+            }
+        )
+        PcbLayerStackInterchangeParser.#assignStackupFeatures(
+            fields,
+            document.body
+        )
+
+        const stackup = PcbLayerStackInterchangeParser.#tagBlocks(
+            document.body,
+            ['Stackup']
+        )[0]
+
+        if (!stackup) {
+            return
+        }
+
+        PcbLayerStackInterchangeParser.#assignTopLevelFields(
+            fields,
+            'STACKUPX',
+            stackup.fields,
+            {
+                Type: 'TYPE',
+                RoughnessType: 'ROUGHNESS_TYPE',
+                RoughnessFactorSR: 'ROUGHNESS_FACTOR_SR',
+                RoughnessFactor: 'ROUGHNESS_FACTOR',
+                RealisticRatio: 'REALISTIC_RATIO'
+            }
+        )
+
+        const stacks = PcbLayerStackInterchangeParser.#stackupStacks(
+            stackup.body
+        )
+        let nextLayerIndex = 1
+
+        stacks.forEach((stack, stackIndex) => {
+            const layers = PcbLayerStackInterchangeParser.#stackLayers(
+                stack.body
+            )
+            const layerIds = []
+
+            PcbLayerStackInterchangeParser.#assignSubstackFields(
+                fields,
+                stackIndex,
+                {
+                    Id: stack.fields.Id || stack.fields.ID || '',
+                    Name: stack.fields.Name || '',
+                    IsFlex: stack.fields.IsFlex || '',
+                    StackType: stack.fields.Type || ''
+                }
+            )
+
+            for (const layer of layers) {
+                const layerIndex =
+                    PcbLayerStackInterchangeParser.#positiveInteger(
+                        layer.fields.Index || layer.fields.index
+                    ) || nextLayerIndex
+                const layerId =
+                    PcbLayerStackInterchangeParser.#positiveInteger(
+                        layer.fields.LayerId || layer.fields.LayerID
+                    ) || layerIndex
+                const properties =
+                    PcbLayerStackInterchangeParser.#layerProperties(layer.body)
+                const layerValues =
+                    PcbLayerStackInterchangeParser.#stackupDocumentLayerValues(
+                        layer,
+                        layerId,
+                        properties
+                    )
+
+                PcbLayerStackInterchangeParser.#assignLayerFields(
+                    fields,
+                    layerIndex,
+                    layerValues
+                )
+                layerIds.push(layerId)
+                nextLayerIndex = Math.max(nextLayerIndex, layerIndex + 1)
+            }
+
+            if (layerIds.length) {
+                fields['V9_SUBSTACK' + stackIndex + '_LAYERS'] =
+                    layerIds.join(',')
+            }
+        })
+    }
+
+    /**
+     * Assigns StackupDocument feature rows.
+     * @param {Record<string, string>} fields Target fields.
+     * @param {string} body Document body.
+     * @returns {void}
+     */
+    static #assignStackupFeatures(fields, body) {
+        const features = PcbLayerStackInterchangeParser.#tagBlocks(body, [
+            'Feature'
+        ])
+
+        features.forEach((feature, index) => {
+            const prefix = 'STACKUPX_FEATURE' + index + '_'
+            const featureId = feature.fields.Id || feature.fields.ID || ''
+            const featureKind =
+                PcbLayerStackInterchangeParser.#featureKindFromId(featureId)
+
+            fields[prefix + 'ID'] = featureId
+            fields[prefix + 'NAME'] =
+                PcbLayerStackInterchangeParser.#decodeXmlText(feature.body)
+            if (featureKind) {
+                fields[prefix + 'KIND'] = featureKind
+            }
+        })
+    }
+
+    /**
+     * Finds stack rows inside the Stackup/Stacks container.
+     * @param {string} stackupBody Stackup XML body.
+     * @returns {{ tagName: string, fields: Record<string, string>, body: string }[]}
+     */
+    static #stackupStacks(stackupBody) {
+        const stacksContainer = PcbLayerStackInterchangeParser.#tagBlocks(
+            stackupBody,
+            ['Stacks']
+        )[0]
+
+        return PcbLayerStackInterchangeParser.#tagBlocks(
+            stacksContainer?.body || '',
+            ['Stack']
+        )
+    }
+
+    /**
+     * Finds layer rows inside one Stack/Layers container.
+     * @param {string} stackBody Stack XML body.
+     * @returns {{ tagName: string, fields: Record<string, string>, body: string }[]}
+     */
+    static #stackLayers(stackBody) {
+        const layersContainer = PcbLayerStackInterchangeParser.#tagBlocks(
+            stackBody,
+            ['Layers']
+        )[0]
+
+        return PcbLayerStackInterchangeParser.#tagBlocks(
+            layersContainer?.body || '',
+            ['Layer']
+        )
+    }
+
+    /**
+     * Converts one StackupDocument Layer element into known field names.
+     * @param {{ fields: Record<string, string>, body: string }} layer Layer block.
+     * @param {number} layerId Normalized layer id.
+     * @param {Record<string, string>} properties Layer properties.
+     * @returns {Record<string, string>}
+     */
+    static #stackupDocumentLayerValues(layer, layerId, properties) {
+        const typeId = layer.fields.TypeId || layer.fields.TypeID || ''
+        const values = {
+            Name: layer.fields.Name || '',
+            LayerId: String(layerId),
+            Kind:
+                layer.fields.Kind ||
+                layer.fields.Type ||
+                PcbLayerStackInterchangeParser.#kindFromLayerTypeId(typeId),
+            SourceRecordId: layer.fields.Id || layer.fields.ID || '',
+            StackupxShared: layer.fields.IsShared || '',
+            StackupxProperties:
+                PcbLayerStackInterchangeParser.#propertiesField(properties)
+        }
+
+        const propertyValueNames = {
+            Material: 'Material',
+            Thickness: 'Thickness',
+            Weight: 'CopperWeight',
+            CopperThickness: 'CopperThickness',
+            DielectricConstant: 'Dk',
+            LossTangent: 'Df',
+            Process: 'Process',
+            PullbackDistance: 'PullbackDistance',
+            CopperOrientation: 'CopperOrientation',
+            Orientation: 'Orientation',
+            Note: 'Note',
+            Comment: 'Comment',
+            'Material.Manufacturer': 'MaterialManufacturer',
+            'Material.Description': 'MaterialDescription',
+            'Material.GlassTransitionTemp': 'MaterialGlassTransitionTemp',
+            GlassTransTemp: 'GlassTransitionTemp',
+            DielectricStrength: 'DielectricStrength',
+            VolumeResistivity: 'VolumeResistivity',
+            Resin: 'Resin',
+            Solid: 'Solid',
+            'Material.Frequency': 'MaterialFrequency',
+            Frequency: 'Frequency',
+            Constructions: 'Constructions',
+            CoverlayExpansion: 'CoverlayExpansion'
+        }
+
+        for (const [propertyName, valueName] of Object.entries(
+            propertyValueNames
+        )) {
+            PcbLayerStackInterchangeParser.#assignPropertyValue(
+                values,
+                properties,
+                propertyName,
+                valueName
+            )
+        }
+
+        if (PcbLayerStackInterchangeParser.#isAdhesiveLayerType(typeId)) {
+            values.IsAdhesive = 'true'
+        }
+        if (PcbLayerStackInterchangeParser.#isStiffenerLayerType(typeId)) {
+            values.IsStiffener = 'true'
+        }
+
+        return values
+    }
+
     /**
      * Assigns one sectioned text field.
      * @param {Record<string, string>} fields Target fields.
@@ -248,11 +507,31 @@ export class PcbLayerStackInterchangeParser {
             CopperThickness: 'COPPERTHICKNESS',
             Dk: 'DK',
             Df: 'DF',
+            Process: 'PROCESS',
+            PullbackDistance: 'PULLBACKDISTANCE',
+            CopperOrientation: 'COPPERORIENTATION',
+            Orientation: 'ORIENTATION',
+            Note: 'NOTE',
+            Comment: 'COMMENT',
+            MaterialManufacturer: 'MATERIALMANUFACTURER',
+            MaterialDescription: 'MATERIALDESCRIPTION',
+            MaterialGlassTransitionTemp: 'MATERIALGLASSTRANSITIONTEMP',
+            GlassTransitionTemp: 'GLASSTRANSITIONTEMP',
+            DielectricStrength: 'DIELECTRICSTRENGTH',
+            VolumeResistivity: 'VOLUMERESISTIVITY',
+            Resin: 'RESIN',
+            Solid: 'SOLID',
+            MaterialFrequency: 'MATERIALFREQUENCY',
+            Frequency: 'FREQUENCY',
+            Constructions: 'CONSTRUCTIONS',
             IsAdhesive: 'ISADHESIVE',
             IsStiffener: 'ISSTIFFENER',
+            CopperWeight: 'COPPERWEIGHT',
+            CoverlayExpansion: 'COVERLAYEXPANSION',
             SurfaceFinish: 'SURFACEFINISH',
             SourceRecordId: 'SOURCE_RECORD_ID',
             SourceKeys: 'SOURCE_KEYS',
+            StackupxShared: 'STACKUPX_SHARED',
             StackupxProperties: 'STACKUPX_PROPERTIES'
         }
         const suffix = suffixByKey[key]
@@ -292,6 +571,7 @@ export class PcbLayerStackInterchangeParser {
             Name: 'NAME',
             IsFlex: 'ISFLEX',
             Layers: 'LAYERS',
+            StackupxShared: 'STACKUPX_SHARED',
             StackType: 'STACKUPX_STACKTYPE'
         }
         const suffix = suffixByKey[key]
@@ -387,6 +667,195 @@ export class PcbLayerStackInterchangeParser {
         }
     }
 
+    /**
+     * Assigns top-level scalar fields using one prefix.
+     * @param {Record<string, string>} fields Target fields.
+     * @param {string} prefix Field prefix.
+     * @param {Record<string, string>} values Source attributes.
+     * @param {Record<string, string>} keyMap Source-to-target suffixes.
+     * @returns {void}
+     */
+    static #assignTopLevelFields(fields, prefix, values, keyMap) {
+        for (const [sourceKey, suffix] of Object.entries(keyMap)) {
+            if (values[sourceKey]) {
+                fields[prefix + '_' + suffix] = values[sourceKey]
+            }
+        }
+    }
+
+    /**
+     * Assigns one known property value to layer values.
+     * @param {Record<string, string>} values Target values.
+     * @param {Record<string, string>} properties Source properties.
+     * @param {string} propertyName Source property name.
+     * @param {string} valueName Target value name.
+     * @returns {void}
+     */
+    static #assignPropertyValue(values, properties, propertyName, valueName) {
+        if (properties[propertyName]) {
+            values[valueName] = properties[propertyName]
+        }
+    }
+
+    /**
+     * Parses nested layer Property elements into a key/value map.
+     * @param {string} body Layer XML body.
+     * @returns {Record<string, string>}
+     */
+    static #layerProperties(body) {
+        const propertiesContainer = PcbLayerStackInterchangeParser.#tagBlocks(
+            body,
+            ['Properties']
+        )[0]
+        const properties = {}
+
+        for (const property of PcbLayerStackInterchangeParser.#tagBlocks(
+            propertiesContainer?.body || '',
+            ['Property']
+        )) {
+            const name = property.fields.Name || property.fields.name || ''
+            if (!name) {
+                continue
+            }
+
+            properties[name] = PcbLayerStackInterchangeParser.#decodeXmlText(
+                property.body
+            )
+        }
+
+        return properties
+    }
+
+    /**
+     * Serializes property rows into the existing key/value sidecar field.
+     * @param {Record<string, string>} properties Source properties.
+     * @returns {string}
+     */
+    static #propertiesField(properties) {
+        return Object.entries(properties)
+            .map(([key, value]) => key + '=' + value)
+            .join('|')
+    }
+
+    /**
+     * Resolves a positive integer.
+     * @param {string | number | undefined} value Source value.
+     * @returns {number}
+     */
+    static #positiveInteger(value) {
+        const parsed = Number.parseInt(String(value || ''), 10)
+        return Number.isInteger(parsed) && parsed > 0 ? parsed : 0
+    }
+
+    /**
+     * Returns true when text contains the requested XML-like tag.
+     * @param {string} text Source text.
+     * @param {string} tagName Tag name.
+     * @returns {boolean}
+     */
+    static #hasTag(text, tagName) {
+        return new RegExp('<\\s*' + tagName + '\\b', 'iu').test(
+            String(text || '')
+        )
+    }
+
+    /**
+     * Decodes simple XML text content used by stack metadata.
+     * @param {string} value Encoded text.
+     * @returns {string}
+     */
+    static #decodeXmlText(value) {
+        return String(value || '')
+            .replace(/<!\[CDATA\[([\s\S]*?)\]\]>/gu, '$1')
+            .replace(/&quot;/gu, '"')
+            .replace(/&apos;/gu, "'")
+            .replace(/&lt;/gu, '<')
+            .replace(/&gt;/gu, '>')
+            .replace(/&amp;/gu, '&')
+            .trim()
+    }
+
+    /**
+     * Maps known stack layer type ids to broad layer kinds.
+     * @param {string} typeId Source type id.
+     * @returns {string}
+     */
+    static #kindFromLayerTypeId(typeId) {
+        const normalized = PcbLayerStackInterchangeParser.#normalizeGuid(typeId)
+        const kindByTypeId = new Map([
+            ['31E48829-E750-4C28-95E0-1A8313F0158E', 'signal'],
+            ['F59FAB94-C5ED-467D-94CD-F60A323C5D5B', 'plane'],
+            ['F4ECCD87-2CFB-4F37-BE50-4F3A272B4D01', 'signal'],
+            ['B0827674-798C-4CF8-807C-8E6C2A11C145', 'finish'],
+            ['92B02D5E-8D69-48A8-880E-AC4B77DB099D', 'dielectric'],
+            ['136C62EF-1FA6-4897-AE71-7E797B632B92', 'dielectric'],
+            ['1A79611A-039D-4D40-A204-53C26C50F8B5', 'dielectric'],
+            ['90B89AA0-A48A-45F4-82F5-B3ECA4EC8CCE', 'plating'],
+            ['448F9952-79BA-41D8-A8F4-4713EE7A3828', 'mechanical'],
+            ['9FD889FA-C97A-401C-A066-E5F746678381', 'mechanical'],
+            ['786B5F28-F093-4084-BBA7-46E8F4F24F55', 'mechanical'],
+            ['886956F5-B2E9-4114-93F3-F69AF872BFFB', 'marking']
+        ])
+
+        return kindByTypeId.get(normalized) || ''
+    }
+
+    /**
+     * Maps known stackup feature ids to stable feature kinds.
+     * @param {string} featureId Source feature id.
+     * @returns {string}
+     */
+    static #featureKindFromId(featureId) {
+        const normalized =
+            PcbLayerStackInterchangeParser.#normalizeGuid(featureId)
+        const kindByFeatureId = new Map([
+            ['C8939E8A-FD0E-4D52-8860-B7A98F452016', 'standard-stackup'],
+            ['E3DF2B86-5F1B-49CA-B266-D1AE57F0BA6F', 'impedance-calculator'],
+            ['5277E6A4-9E5F-4F54-951F-DC18CFEB7530', 'rigid-flex'],
+            ['68E477FE-0406-4BD2-AD1D-6DD49217052C', 'printed-electronics'],
+            ['0A82BA33-E4D8-43F3-9C01-412DC26BDD5E', 'back-drills'],
+            ['231FB828-14F8-43F8-9DDF-B2A90A4C5283', 'generic-stackup']
+        ])
+
+        return kindByFeatureId.get(normalized) || ''
+    }
+
+    /**
+     * Normalizes GUID text for case-insensitive lookup.
+     * @param {string} value Source GUID text.
+     * @returns {string}
+     */
+    static #normalizeGuid(value) {
+        return String(value || '')
+            .trim()
+            .replace(/[{}]/gu, '')
+            .toUpperCase()
+    }
+
+    /**
+     * Returns true for known adhesive layer type ids.
+     * @param {string} typeId Source type id.
+     * @returns {boolean}
+     */
+    static #isAdhesiveLayerType(typeId) {
+        return (
+            PcbLayerStackInterchangeParser.#normalizeGuid(typeId) ===
+            '448F9952-79BA-41D8-A8F4-4713EE7A3828'
+        )
+    }
+
+    /**
+     * Returns true for known stiffener layer type ids.
+     * @param {string} typeId Source type id.
+     * @returns {boolean}
+     */
+    static #isStiffenerLayerType(typeId) {
+        return (
+            PcbLayerStackInterchangeParser.#normalizeGuid(typeId) ===
+            '9FD889FA-C97A-401C-A066-E5F746678381'
+        )
+    }
+
     /**
      * Extracts XML-like tag fields.
      * @param {string} text Source text.

package/src/core/altium/PcbLayerStackReadModelBuilder.mjs

@@ -62,6 +62,7 @@ export class PcbLayerStackReadModelBuilder {
             layerById,
             'backdrill'
         )
+        const stackup = PcbLayerStackReadModelBuilder.#stackup(fields)
         const diagnostics = PcbLayerStackReadModelBuilder.#diagnostics({
             substacks,
             branches,
@@ -105,6 +106,7 @@ export class PcbLayerStackReadModelBuilder {
             branches,
             topLevelBendLines,
             cavityReport,
+            ...(stackup ? { stackup } : {}),
             impedanceProfiles,
             transmissionLines,
             viaSpans,
@@ -166,9 +168,9 @@ export class PcbLayerStackReadModelBuilder {
                 PcbLayerStackReadModelBuilder.#stripUndefined({
                     index: layer.index,
                     layerId: layer.layerId,
-                    layerKey: PcbLayerStackReadModelBuilder.#layerKey(
-                        layer.layerId
-                    ),
+                    layerKey: Number.isFinite(layer.layerId)
+                        ? 'L' + layer.layerId
+                        : undefined,
                     name: layer.name,
                     kind: layer.kind,
                     material: layer.material,
@@ -189,9 +191,9 @@ export class PcbLayerStackReadModelBuilder {
             PcbLayerStackReadModelBuilder.#stripUndefined({
                 index: index + 1,
                 layerId: layer.layerId,
-                layerKey: PcbLayerStackReadModelBuilder.#layerKey(
-                    layer.layerId
-                ),
+                layerKey: Number.isFinite(layer.layerId)
+                    ? 'L' + layer.layerId
+                    : undefined,
                 name: layer.name,
                 kind: layer.kind || layer.role,
                 ...PcbLayerStackSourceMetadataParser.layerSourceFields(
@@ -592,6 +594,81 @@ export class PcbLayerStackReadModelBuilder {
         )
     }
 
+    /**
+     * Parses document-level layer-stack metadata.
+     * @param {Record<string, string | string[]>} fields Board fields.
+     * @returns {object | undefined}
+     */
+    static #stackup(fields) {
+        const features = PcbLayerStackReadModelBuilder.#stackupFeatures(fields)
+        const stackup = PcbLayerStackReadModelBuilder.#stripUndefined({
+            serializerVersion: PcbLayerStackReadModelBuilder.#field(
+                fields,
+                'STACKUPX_SERIALIZER_VERSION'
+            ),
+            revisionId: PcbLayerStackReadModelBuilder.#field(
+                fields,
+                'STACKUPX_REVISION_ID'
+            ),
+            type: PcbLayerStackReadModelBuilder.#field(fields, 'STACKUPX_TYPE'),
+            roughnessType: PcbLayerStackReadModelBuilder.#field(
+                fields,
+                'STACKUPX_ROUGHNESS_TYPE'
+            ),
+            roughnessFactorSR: PcbLayerStackReadModelBuilder.#field(
+                fields,
+                'STACKUPX_ROUGHNESS_FACTOR_SR'
+            ),
+            roughnessFactor: PcbLayerStackReadModelBuilder.#field(
+                fields,
+                'STACKUPX_ROUGHNESS_FACTOR'
+            ),
+            realisticRatio: PcbLayerStackReadModelBuilder.#optionalBoolean(
+                PcbLayerStackReadModelBuilder.#field(
+                    fields,
+                    'STACKUPX_REALISTIC_RATIO'
+                )
+            ),
+            features: PcbLayerStackSourceMetadataParser.optionalArray(features)
+        })
+
+        return Object.keys(stackup).length ? stackup : undefined
+    }
+
+    /**
+     * Parses stackup feature rows.
+     * @param {Record<string, string | string[]>} fields Board fields.
+     * @returns {object[]}
+     */
+    static #stackupFeatures(fields) {
+        return PcbLayerStackReadModelBuilder.#indexedRows(fields, [
+            /^STACKUPX_FEATURE(\d+)_ID$/iu,
+            /^STACKUP_FEATURE(\d+)_ID$/iu
+        ]).map((index) =>
+            PcbLayerStackReadModelBuilder.#stripUndefined({
+                index,
+                id: PcbLayerStackReadModelBuilder.#indexedField(
+                    fields,
+                    ['STACKUPX_FEATURE', 'STACKUP_FEATURE'],
+                    index,
+                    ['ID']
+                ),
+                name: PcbLayerStackReadModelBuilder.#indexedField(
+                    fields,
+                    ['STACKUPX_FEATURE', 'STACKUP_FEATURE'],
+                    index,
+                    ['NAME']
+                ),
+                kind: PcbLayerStackReadModelBuilder.#indexedField(
+                    fields,
+                    ['STACKUPX_FEATURE', 'STACKUP_FEATURE'],
+                    index,
+                    ['KIND']
+                )
+            })
+        )
+    }
+
     /**
      * Builds preservation-first diagnostics for unresolved references.
      * @param {object} input Sidecar sections.
@@ -903,15 +980,6 @@ export class PcbLayerStackReadModelBuilder {
         return Number.isFinite(parsed) ? parsed : undefined
     }
 
-    /**
-     * Builds a stable layer key.
-     * @param {number | null | undefined} layerId Layer id.
-     * @returns {string | undefined}
-     */
-    static #layerKey(layerId) {
-        return Number.isFinite(layerId) ? 'L' + layerId : undefined
-    }
-
     /**
      * Removes undefined and empty string values while keeping false and empty
      * arrays stable.