altium-toolkit 1.0.9 → 1.1.0

package/src/core/altium/PcbLibParityReportBuilder.mjs

@@ -0,0 +1,242 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Builds parity reports for advanced PcbLib footprint fields.
+ */
+export class PcbLibParityReportBuilder {
+    static SCHEMA = 'altium-toolkit.pcblib.parity.a1'
+
+    /**
+     * Builds an advanced-field parity report.
+     * @param {{ footprints?: object[] }} pcbLibrary Parsed PCB library model.
+     * @returns {object}
+     */
+    static build(pcbLibrary = {}) {
+        const footprints = (pcbLibrary.footprints || []).map((footprint) =>
+            PcbLibParityReportBuilder.#footprintRow(footprint)
+        )
+        const summary = PcbLibParityReportBuilder.#summary(footprints)
+
+        return {
+            schema: PcbLibParityReportBuilder.SCHEMA,
+            summary,
+            footprints
+        }
+    }
+
+    /**
+     * Builds one footprint parity row.
+     * @param {object} footprint Footprint record.
+     * @returns {object}
+     */
+    static #footprintRow(footprint) {
+        const advancedFields = {
+            localStackPads: (footprint.pads || []).filter(
+                (pad) => pad.localStack
+            ).length,
+            customPadShapes: footprint.customPadShapes?.entries?.length || 0,
+            maskPastePrimitives: footprint.maskPaste?.primitives?.length || 0,
+            viaTenting: (footprint.vias || []).filter((via) =>
+                PcbLibParityReportBuilder.#hasViaTenting(via)
+            ).length,
+            barcodeTexts: (footprint.texts || []).filter((text) => text.barcode)
+                .length,
+            embeddedModels: (footprint.embeddedModels || []).length,
+            projectionDiagnostics: (footprint.componentBodies || []).filter(
+                (body) => body.projectionDiagnostics
+            ).length
+        }
+
+        return {
+            name: footprint.name || '',
+            advancedFields,
+            layers: PcbLibParityReportBuilder.#layers(footprint),
+            diagnostics: PcbLibParityReportBuilder.#diagnostics(advancedFields)
+        }
+    }
+
+    /**
+     * Builds top-level parity counters.
+     * @param {object[]} footprints Footprint parity rows.
+     * @returns {object}
+     */
+    static #summary(footprints) {
+        return {
+            footprintCount: footprints.length,
+            footprintWithAdvancedFieldsCount: footprints.filter((footprint) =>
+                Object.values(footprint.advancedFields).some(
+                    (value) => Number(value) > 0
+                )
+            ).length,
+            localStackPadCount: PcbLibParityReportBuilder.#sum(
+                footprints,
+                'localStackPads'
+            ),
+            customPadFootprintCount: footprints.filter(
+                (footprint) => footprint.advancedFields.customPadShapes > 0
+            ).length,
+            maskPastePrimitiveCount: PcbLibParityReportBuilder.#sum(
+                footprints,
+                'maskPastePrimitives'
+            ),
+            viaTentingCount: PcbLibParityReportBuilder.#sum(
+                footprints,
+                'viaTenting'
+            ),
+            barcodeTextCount: PcbLibParityReportBuilder.#sum(
+                footprints,
+                'barcodeTexts'
+            ),
+            embeddedModelFootprintCount: footprints.filter(
+                (footprint) => footprint.advancedFields.embeddedModels > 0
+            ).length,
+            projectionDiagnosticCount: PcbLibParityReportBuilder.#sum(
+                footprints,
+                'projectionDiagnostics'
+            )
+        }
+    }
+
+    /**
+     * Sums one advanced-field counter.
+     * @param {object[]} footprints Footprint rows.
+     * @param {string} key Advanced-field key.
+     * @returns {number}
+     */
+    static #sum(footprints, key) {
+        return footprints.reduce(
+            (total, footprint) =>
+                total + Number(footprint.advancedFields?.[key] || 0),
+            0
+        )
+    }
+
+    /**
+     * Builds layer descriptors represented by the footprint.
+     * @param {object} footprint Footprint record.
+     * @returns {object[]}
+     */
+    static #layers(footprint) {
+        const layerMap = new Map()
+        for (const primitive of PcbLibParityReportBuilder.#primitives(
+            footprint
+        )) {
+            const layer = PcbLibParityReportBuilder.#layerDescriptor(primitive)
+            if (layer) layerMap.set(layer.layerKey, layer)
+        }
+        return [...layerMap.values()].sort((left, right) =>
+            left.layerKey.localeCompare(right.layerKey, undefined, {
+                numeric: true
+            })
+        )
+    }
+
+    /**
+     * Builds diagnostics for unsupported parity edge cases.
+     * @param {object} advancedFields Advanced-field counts.
+     * @returns {object[]}
+     */
+    static #diagnostics(advancedFields) {
+        return Object.values(advancedFields).some((value) => Number(value) > 0)
+            ? []
+            : [
+                  {
+                      code: 'pcblib.parity.no-advanced-fields',
+                      severity: 'info',
+                      message:
+                          'Footprint does not expose advanced PCB field families.'
+                  }
+              ]
+    }
+
+    /**
+     * Returns true when a via preserves tenting metadata.
+     * @param {object} via Via primitive.
+     * @returns {boolean}
+     */
+    static #hasViaTenting(via) {
+        return [
+            via?.topTenting,
+            via?.bottomTenting,
+            via?.tentingTop,
+            via?.tentingBottom,
+            via?.solderMaskExpansionMode,
+            via?.solderMaskExpansion
+        ].some((value) => value !== undefined && value !== null && value !== '')
+    }
+
+    /**
+     * Returns all footprint primitives that can carry layer metadata.
+     * @param {object} footprint Footprint record.
+     * @returns {object[]}
+     */
+    static #primitives(footprint) {
+        return [
+            ...(footprint.pads || []),
+            ...(footprint.vias || []),
+            ...(footprint.tracks || []),
+            ...(footprint.arcs || []),
+            ...(footprint.fills || []),
+            ...(footprint.regions || []),
+            ...(footprint.shapeBasedRegions || []),
+            ...(footprint.texts || [])
+        ]
+    }
+
+    /**
+     * Builds a normalized layer descriptor.
+     * @param {object} primitive Primitive row.
+     * @returns {object | null}
+     */
+    static #layerDescriptor(primitive) {
+        const layerId = Number.isInteger(primitive?.layerId)
+            ? primitive.layerId
+            : null
+        const displayName = String(
+            primitive?.layerName || primitive?.layer || ''
+        ).trim()
+        if (layerId === null && !displayName) {
+            return null
+        }
+        const layerKey =
+            layerId === null
+                ? 'layer-' + PcbLibParityReportBuilder.#slug(displayName)
+                : 'L' + layerId
+
+        return PcbLibParityReportBuilder.#stripUndefined({
+            layerKey,
+            layerId: layerId === null ? undefined : layerId,
+            displayName: displayName || layerKey
+        })
+    }
+
+    /**
+     * Converts a value to a deterministic lowercase key segment.
+     * @param {unknown} value Source value.
+     * @returns {string}
+     */
+    static #slug(value) {
+        return (
+            String(value || '')
+                .trim()
+                .toLowerCase()
+                .replace(/[^a-z0-9]+/gu, '-')
+                .replace(/^-+|-+$/gu, '') || 'item'
+        )
+    }
+
+    /**
+     * Removes undefined fields.
+     * @param {Record<string, unknown>} value Candidate object.
+     * @returns {Record<string, unknown>}
+     */
+    static #stripUndefined(value) {
+        return Object.fromEntries(
+            Object.entries(value || {}).filter(
+                ([, entryValue]) => entryValue !== undefined
+            )
+        )
+    }
+}

package/src/core/altium/PcbModelParser.mjs

@@ -5,17 +5,25 @@
 import { AltiumLayoutParser } from './AltiumLayoutParser.mjs'
 import { NormalizedModelSchema } from './NormalizedModelSchema.mjs'
 import { PcbBoardRegionSemanticsParser } from './PcbBoardRegionSemanticsParser.mjs'
+import { PcbBomProfileBuilder } from './PcbBomProfileBuilder.mjs'
 import { PcbComponentAnnotationNormalizer } from './PcbComponentAnnotationNormalizer.mjs'
 import { PcbComponentBodyPlacementNormalizer } from './PcbComponentBodyPlacementNormalizer.mjs'
+import { PcbComponentKindPolicy } from './PcbComponentKindPolicy.mjs'
 import { PcbComponentPrimitiveIndexer } from './PcbComponentPrimitiveIndexer.mjs'
 import { PcbCustomPadShapeParser } from './PcbCustomPadShapeParser.mjs'
 import { PcbDimensionParser } from './PcbDimensionParser.mjs'
+import { PcbLayerStackReadModelBuilder } from './PcbLayerStackReadModelBuilder.mjs'
 import { PcbMechanicalLayerPairParser } from './PcbMechanicalLayerPairParser.mjs'
 import { PcbDefaultsParser } from './PcbDefaultsParser.mjs'
 import { PcbMaskPasteResolver } from './PcbMaskPasteResolver.mjs'
 import { PcbOutlineRecovery } from './PcbOutlineRecovery.mjs'
 import { PcbOwnershipGraphBuilder } from './PcbOwnershipGraphBuilder.mjs'
+import { PcbPlacedFootprintManifestBuilder } from './PcbPlacedFootprintManifestBuilder.mjs'
 import { PcbPickPlacePositionResolver } from './PcbPickPlacePositionResolver.mjs'
+import { PcbPolygonRecordParser } from './PcbPolygonRecordParser.mjs'
+import { PcbReviewMetadataBuilder } from './PcbReviewMetadataBuilder.mjs'
+import { PcbRigidFlexTopologyBuilder } from './PcbRigidFlexTopologyBuilder.mjs'
+import { PcbRouteAnalysisBuilder } from './PcbRouteAnalysisBuilder.mjs'
 import { PcbRuleParser } from './PcbRuleParser.mjs'
 import { PcbSpecialStringResolver } from './PcbSpecialStringResolver.mjs'
 import { PcbStatisticsBuilder } from './PcbStatisticsBuilder.mjs'
@@ -84,11 +92,6 @@ export class PcbModelParser {
                 PcbModelParser.#publicComponentRecord(component)
             )
         )
-        const polygonRecords = records.filter(
-            (record) =>
-                record.sourceStream === 'Polygons6/Data' &&
-                getField(record.fields, 'KIND0')
-        )
         const fallbackBoardOutline = AltiumLayoutParser.parseBoardOutline(
             boardRecord?.fields || {}
         )
@@ -123,13 +126,7 @@ export class PcbModelParser {
             'pcb-document'
         )
         const dimensions = PcbDimensionParser.parse(records)
-        const polygons = polygonRecords
-            .map((record) => ({
-                layer: getField(record.fields, 'LAYER') || 'UNKNOWN',
-                segments: AltiumLayoutParser.parseBoardOutline(record.fields)
-                    .segments
-            }))
-            .filter((polygon) => polygon.segments.length > 0)
+        const polygons = PcbPolygonRecordParser.parse(records)
         const tracks = PcbModelParser.#annotatePrimitiveNetNames(
             pcbExtraction?.binaryPrimitives?.tracks || [],
             netNameByIndex
@@ -258,6 +255,17 @@ export class PcbModelParser {
             PcbBoardRegionSemanticsParser.summarizeBoardRegions(
                 normalizedPcb.boardRegions
             )
+        const layerStackReadModel = PcbLayerStackReadModelBuilder.build({
+            fileName,
+            boardRecords,
+            streamNames: pcbExtraction?.streamNames || [],
+            layers,
+            primitiveLayers,
+            layerSubstacks,
+            boardRegions: normalizedPcb.boardRegions
+        })
+        const rigidFlexTopology =
+            PcbRigidFlexTopologyBuilder.build(layerStackReadModel)
         const componentBodies =
             PcbComponentBodyPlacementNormalizer.normalizeComponentBodies(
                 extractedComponentBodies,
@@ -281,6 +289,38 @@ export class PcbModelParser {
             componentPrimitiveGroups,
             { sourceComponents: componentRecords }
         )
+        const routeAnalysis = PcbRouteAnalysisBuilder.build({
+            ...normalizedPcb,
+            layers,
+            primitiveLayers,
+            nets,
+            classes,
+            differentialPairs: differentialPairData.differentialPairs,
+            differentialPairClasses:
+                differentialPairData.differentialPairClasses
+        })
+        const reviewMetadata = PcbReviewMetadataBuilder.build({
+            routeAnalysis,
+            embeddedModels: extractedEmbeddedModels,
+            componentBodies,
+            layers,
+            primitiveLayers,
+            polygons: normalizedPcb.polygons,
+            tracks: normalizedPcb.tracks,
+            arcs: normalizedPcb.arcs,
+            fills: normalizedPcb.fills,
+            vias: normalizedPcb.vias,
+            pads: normalizedPcb.pads,
+            regions: normalizedPcb.regions,
+            shapeBasedRegions: normalizedPcb.shapeBasedRegions
+        })
+        const footprintExtractionManifest =
+            PcbPlacedFootprintManifestBuilder.build({
+                fileName,
+                components: normalizedPcb.components,
+                componentPrimitiveGroups,
+                embeddedModels: extractedEmbeddedModels
+            })
         const statistics = PcbStatisticsBuilder.build({
             ...normalizedPcb,
             layers,
@@ -294,13 +334,21 @@ export class PcbModelParser {
             defaults
         })
         const bom = PcbModelParser.#groupBomRows(
-            componentRecords.map((component) => ({
-                designator: component.designator,
-                pattern: component.pattern,
-                source: component.source,
-                value: component.description || component.pattern
-            }))
+            componentRecords
+                .filter(
+                    (component) =>
+                        component.componentKind?.includeInBom !== false
+                )
+                .map((component) => ({
+                    designator: component.designator,
+                    pattern: component.pattern,
+                    source: component.source,
+                    value: component.description || component.pattern
+                }))
         )
+        const bomProfile = PcbBomProfileBuilder.build(componentRecords, {
+            source: 'pcb-document'
+        })
 
         const diagnostics = [
             {
@@ -358,6 +406,22 @@ export class PcbModelParser {
             })
         }
 
+        for (const issue of layerStackReadModel?.diagnostics || []) {
+            diagnostics.push({
+                severity: issue.severity || 'warning',
+                code: issue.code,
+                message: issue.message
+            })
+        }
+
+        for (const issue of rigidFlexTopology?.diagnostics || []) {
+            diagnostics.push({
+                severity: issue.severity || 'warning',
+                code: issue.code,
+                message: issue.message
+            })
+        }
+
         if (pcbExtraction) {
             diagnostics.push({
                 severity: 'info',
@@ -544,6 +608,13 @@ export class PcbModelParser {
                 differentialPairClassCount:
                     differentialPairData.differentialPairClasses.length,
                 ruleCount: rules.length,
+                routeReviewGroupCount:
+                    reviewMetadata.summary.routeGroupCount || 0,
+                boardAssemblyViewCount:
+                    reviewMetadata.summary.boardAssemblyViewCount || 0,
+                extractableFootprintCount:
+                    footprintExtractionManifest.summary
+                        .extractableFootprintCount || 0,
                 dimensionCount: dimensions.length,
                 mechanicalLayerPairCount: mechanicalLayerPairs.length,
                 polygonCount: polygons.length,
@@ -556,9 +627,23 @@ export class PcbModelParser {
                 customPadShapeCount: customPadShapes.entries?.length || 0,
                 userUnionCount: unions.userUnions?.length || 0,
                 smartUnionCount: unions.smartUnions?.length || 0,
+                routedNetCount: routeAnalysis.summary.routedNetCount,
+                routedLengthMil: routeAnalysis.summary.totalLengthMil,
                 boardRegionCount: boardRegionSummary.boardRegionCount,
                 flexRegionCount: boardRegionSummary.flexRegionCount,
                 bendingLineCount: boardRegionSummary.bendingLineCount,
+                layerStackSubstackCount:
+                    layerStackReadModel?.summary.substackCount || 0,
+                layerStackBranchCount:
+                    layerStackReadModel?.summary.branchCount || 0,
+                impedanceProfileCount:
+                    layerStackReadModel?.summary.impedanceProfileCount || 0,
+                backdrillSpanCount:
+                    layerStackReadModel?.summary.backdrillSpanCount || 0,
+                cavityRegionCount:
+                    layerStackReadModel?.summary.cavityRegionCount || 0,
+                stiffenerLayerCount:
+                    layerStackReadModel?.summary.stiffenerLayerCount || 0,
                 embeddedModelIssueCount:
                     embeddedModelIntegrity.issues?.length || 0,
                 embeddedFontCount: extractedEmbeddedFonts.length,
@@ -572,6 +657,8 @@ export class PcbModelParser {
                 boardOutline: normalizedPcb.boardOutline,
                 layers,
                 layerSubstacks,
+                ...(layerStackReadModel ? { layerStackReadModel } : {}),
+                ...(rigidFlexTopology ? { rigidFlexTopology } : {}),
                 mechanicalLayerPairs,
                 layerFlipMetadata,
                 boardRegionContexts,
@@ -585,9 +672,13 @@ export class PcbModelParser {
                 rules,
                 ...(defaults ? { defaults } : {}),
                 maskPaste,
+                bomProfile,
                 dimensions,
                 components: normalizedPcb.components,
                 pickPlace: pnp,
+                routeAnalysis,
+                reviewMetadata,
+                footprintExtractionManifest,
                 polygons: normalizedPcb.polygons,
                 fills: normalizedPcb.fills,
                 tracks: normalizedPcb.tracks,
@@ -651,6 +742,12 @@ export class PcbModelParser {
                 const provenance = PcbModelParser.#parseComponentProvenance(
                     record.fields
                 )
+                const componentKind = PcbComponentKindPolicy.parse(
+                    record.fields
+                )
+                const parameters = PcbModelParser.#parseComponentParameters(
+                    record.fields
+                )
 
                 return {
                     componentIndex: index,
@@ -669,6 +766,8 @@ export class PcbModelParser {
                         getField(record.fields, 'SOURCEFOOTPRINTLIBRARY'),
                     description: getField(record.fields, 'SOURCEDESCRIPTION'),
                     height: parseNumericField(record.fields, 'HEIGHT'),
+                    ...(Object.keys(parameters).length ? { parameters } : {}),
+                    ...(componentKind ? { componentKind } : {}),
                     ...(Object.keys(provenance).length ? { provenance } : {}),
                     nameOn: parseBoolean(record.fields.NAMEON),
                     commentOn: parseBoolean(record.fields.COMMENTON)
@@ -743,6 +842,70 @@ export class PcbModelParser {
         return nonRedundantKeys.length ? provenance : {}
     }
 
+    /**
+     * Parses component parameter name/value rows from printable component data.
+     * @param {Record<string, string | string[]>} fields Component fields.
+     * @returns {Record<string, string>}
+     */
+    static #parseComponentParameters(fields) {
+        const parameters = {}
+        const indexes = PcbModelParser.#componentParameterIndexes(fields)
+
+        for (const index of indexes) {
+            const name = PcbModelParser.#firstField(fields, [
+                'PARAMETER' + index + 'NAME',
+                'PARAMETER' + index + '_NAME',
+                'PARAMETERNAME' + index,
+                'PARAMETER_NAME' + index
+            ])
+            const value = PcbModelParser.#firstField(fields, [
+                'PARAMETER' + index + 'VALUE',
+                'PARAMETER' + index + '_VALUE',
+                'PARAMETERVALUE' + index,
+                'PARAMETER_VALUE' + index,
+                'PARAMETER' + index + 'TEXT',
+                'PARAMETERTEXT' + index
+            ])
+            if (!name) continue
+            parameters[name] = value
+        }
+
+        return parameters
+    }
+
+    /**
+     * Collects component parameter indexes from count and field names.
+     * @param {Record<string, string | string[]>} fields Component fields.
+     * @returns {number[]}
+     */
+    static #componentParameterIndexes(fields) {
+        const indexes = new Set()
+        const count =
+            parseNumericField(fields, 'PARAMETERCOUNT') ??
+            parseNumericField(fields, 'PARAMETERSCOUNT')
+
+        if (Number.isInteger(count) && count > 0) {
+            for (let index = 0; index < count; index += 1) {
+                indexes.add(index)
+            }
+        }
+
+        for (const key of Object.keys(fields || {})) {
+            const match = /^PARAMETER_?(\d+)_?(NAME|VALUE|TEXT)$/iu.exec(key)
+            if (match) {
+                indexes.add(Number.parseInt(match[1], 10))
+            }
+            const alternateMatch = /^PARAMETER(NAME|VALUE|TEXT)(\d+)$/iu.exec(
+                key
+            )
+            if (alternateMatch) {
+                indexes.add(Number.parseInt(alternateMatch[2], 10))
+            }
+        }
+
+        return [...indexes].sort((left, right) => left - right)
+    }
+
     /**
      * Normalizes native Nets6/Data records in stream order.
      * @param {{ fields: Record<string, string | string[]>, sourceStream?: string }[]} records
@@ -1193,25 +1356,36 @@ export class PcbModelParser {
                 key === 'MEMBERCOUNT' ||
                 key === 'ENABLED' ||
                 key === 'UNIQUEID' ||
-                /^M\d+$/.test(key)
+                /^(?:M|MEMBER)\d+$/.test(key)
         )
     }
 
     /**
-     * Extracts ordered class members from M0, M1, ... fields.
+     * Extracts ordered class members from M0/MEMBER0-style fields.
      * @param {Record<string, string | string[]>} fields
      * @returns {string[]}
      */
     static #parseClassMembers(fields) {
         return Object.keys(fields || {})
-            .filter((key) => /^M\d+$/.test(key))
+            .filter((key) => /^(?:M|MEMBER)\d+$/.test(key))
             .sort(
-                (left, right) => Number(left.slice(1)) - Number(right.slice(1))
+                (left, right) =>
+                    PcbModelParser.#classMemberIndex(left) -
+                    PcbModelParser.#classMemberIndex(right)
             )
             .map((key) => getField(fields, key))
             .filter(Boolean)
     }
 
+    /**
+     * Extracts the numeric index from a class member field name.
+     * @param {string} key Field key.
+     * @returns {number}
+     */
+    static #classMemberIndex(key) {
+        return Number(String(key).replace(/^(?:M|MEMBER)/u, ''))
+    }
+
     /**
      * Returns a stable display name for one native PCB class kind.
      * @param {number} kind
@@ -1261,6 +1435,21 @@ export class PcbModelParser {
         return null
     }
 
+    /**
+     * Returns the first non-empty printable field value.
+     * @param {Record<string, string | string[]>} fields Source fields.
+     * @param {string[]} keys Candidate keys.
+     * @returns {string}
+     */
+    static #firstField(fields, keys) {
+        for (const key of keys) {
+            const value = getField(fields, key)
+            if (value) return value
+        }
+
+        return ''
+    }
+
     /**
      * Groups component placements into BOM rows.
      * @param {{ designator: string, pattern: string, source: string, value: string }[]} componentRecords