altium-toolkit 1.0.7 → 1.0.9

package/src/core/altium/PcbEmbeddedModelExtractor.mjs

@@ -24,12 +24,22 @@ export class PcbEmbeddedModelExtractor {
             PcbEmbeddedModelExtractor.#parseModelMetadataStream(
                 streams.get('Models/Data')
             )
-        const models = modelMetadataRecords
-            .map((record, index) =>
+        const modelMetadataRows = modelMetadataRecords.map((fields, index) => ({
+            fields,
+            index,
+            sourceStream: 'Models/' + index,
+            id: PcbEmbeddedModelExtractor.#getField(fields, 'ID'),
+            name: PcbEmbeddedModelExtractor.#getField(fields, 'NAME'),
+            checksum: PcbEmbeddedModelExtractor.#normalizeChecksum(
+                PcbEmbeddedModelExtractor.#parseIntegerField(fields, 'CHECKSUM')
+            )
+        }))
+        const models = modelMetadataRows
+            .map((row) =>
                 PcbEmbeddedModelExtractor.#normalizeEmbeddedModel(
-                    record,
-                    streams.get('Models/' + index),
-                    'Models/' + index
+                    row.fields,
+                    streams.get(row.sourceStream),
+                    row.sourceStream
                 )
             )
             .filter(Boolean)
@@ -44,10 +54,18 @@ export class PcbEmbeddedModelExtractor {
                     'ShapeBasedComponentBodies6/Data'
                 )
             ])
+        const integrity = PcbEmbeddedModelExtractor.#buildIntegrityReport(
+            modelMetadataRows,
+            models,
+            componentBodies,
+            streams
+        )
 
         return {
             models,
-            componentBodies
+            componentBodies,
+            integrity,
+            diagnostics: integrity.issues
         }
     }
 
@@ -350,6 +368,193 @@ export class PcbEmbeddedModelExtractor {
         return [...uniqueBodies.values()]
     }
 
+    /**
+     * Builds model metadata and payload integrity diagnostics.
+     * @param {object[]} metadataRows Parsed model metadata rows.
+     * @param {object[]} models Recovered payload models.
+     * @param {object[]} componentBodies Recovered component bodies.
+     * @param {Map<string, Uint8Array>} streams Compound streams.
+     * @returns {{ schema: string, issues: object[] }}
+     */
+    static #buildIntegrityReport(
+        metadataRows,
+        models,
+        componentBodies,
+        streams
+    ) {
+        const issues = [
+            ...PcbEmbeddedModelExtractor.#missingPayloadIssues(
+                metadataRows,
+                models,
+                streams
+            ),
+            ...PcbEmbeddedModelExtractor.#duplicateChecksumIssues(metadataRows),
+            ...PcbEmbeddedModelExtractor.#unresolvedBodyIssues(
+                componentBodies,
+                models
+            ),
+            ...PcbEmbeddedModelExtractor.#unreferencedModelIssues(
+                models,
+                componentBodies
+            )
+        ]
+
+        return {
+            schema: 'altium-toolkit.pcb.embedded-model-integrity.a1',
+            issues
+        }
+    }
+
+    /**
+     * Reports metadata rows without a recoverable payload stream.
+     * @param {object[]} metadataRows Parsed metadata rows.
+     * @param {object[]} models Recovered model rows.
+     * @param {Map<string, Uint8Array>} streams Compound streams.
+     * @returns {object[]}
+     */
+    static #missingPayloadIssues(metadataRows, models, streams) {
+        return (metadataRows || [])
+            .filter(
+                (row) =>
+                    !streams.has(row.sourceStream) ||
+                    !models.some((model) => model.id === row.id)
+            )
+            .map((row) => ({
+                code: streams.has(row.sourceStream)
+                    ? 'pcb.model.payload-unreadable'
+                    : 'pcb.model.payload-missing',
+                severity: 'warning',
+                modelId: row.id,
+                checksum: row.checksum,
+                name: row.name,
+                sourceStream: row.sourceStream,
+                message: streams.has(row.sourceStream)
+                    ? 'Embedded model payload stream could not be decoded.'
+                    : 'Embedded model metadata references a missing payload stream.'
+            }))
+    }
+
+    /**
+     * Reports duplicate authored model checksums.
+     * @param {object[]} metadataRows Parsed metadata rows.
+     * @returns {object[]}
+     */
+    static #duplicateChecksumIssues(metadataRows) {
+        const rowsByChecksum = new Map()
+
+        for (const row of metadataRows || []) {
+            if (!Number.isInteger(row.checksum)) {
+                continue
+            }
+            if (!rowsByChecksum.has(row.checksum)) {
+                rowsByChecksum.set(row.checksum, [])
+            }
+            rowsByChecksum.get(row.checksum).push(row)
+        }
+
+        return [...rowsByChecksum.entries()]
+            .filter(([, rows]) => rows.length > 1)
+            .map(([checksum, rows]) => ({
+                code: 'pcb.model.checksum-duplicate',
+                severity: 'warning',
+                checksum,
+                modelIds: rows.map((row) => row.id).filter(Boolean),
+                sourceStreams: rows.map((row) => row.sourceStream),
+                message:
+                    'Multiple embedded model metadata rows share one checksum.'
+            }))
+    }
+
+    /**
+     * Reports component bodies that reference no recovered model.
+     * @param {object[]} componentBodies Component-body rows.
+     * @param {object[]} models Recovered model rows.
+     * @returns {object[]}
+     */
+    static #unresolvedBodyIssues(componentBodies, models) {
+        return (componentBodies || [])
+            .filter(
+                (componentBody) =>
+                    componentBody.embedded &&
+                    !PcbEmbeddedModelExtractor.#bodyMatchesAnyModel(
+                        componentBody,
+                        models
+                    )
+            )
+            .map((componentBody) => ({
+                code: 'pcb.model.body-unresolved',
+                severity: 'warning',
+                modelId: componentBody.modelId,
+                checksum: componentBody.checksum,
+                name: componentBody.name,
+                sourceStream: componentBody.sourceStream,
+                message:
+                    'Component body references an embedded model that was not recovered.'
+            }))
+    }
+
+    /**
+     * Reports recovered model payloads not referenced by any component body.
+     * @param {object[]} models Recovered model rows.
+     * @param {object[]} componentBodies Component-body rows.
+     * @returns {object[]}
+     */
+    static #unreferencedModelIssues(models, componentBodies) {
+        if (!(componentBodies || []).length) {
+            return []
+        }
+
+        return (models || [])
+            .filter(
+                (model) =>
+                    !(componentBodies || []).some((componentBody) =>
+                        PcbEmbeddedModelExtractor.#bodyMatchesModel(
+                            componentBody,
+                            model
+                        )
+                    )
+            )
+            .map((model) => ({
+                code: 'pcb.model.payload-unreferenced',
+                severity: 'info',
+                modelId: model.id,
+                checksum: model.checksum,
+                name: model.name,
+                sourceStream: model.sourceStream,
+                message:
+                    'Embedded model payload was recovered but no component body references it.'
+            }))
+    }
+
+    /**
+     * Returns true when a component body matches any recovered model.
+     * @param {object} componentBody Component body.
+     * @param {object[]} models Recovered models.
+     * @returns {boolean}
+     */
+    static #bodyMatchesAnyModel(componentBody, models) {
+        return (models || []).some((model) =>
+            PcbEmbeddedModelExtractor.#bodyMatchesModel(componentBody, model)
+        )
+    }
+
+    /**
+     * Returns true when a component body references a model.
+     * @param {object} componentBody Component body.
+     * @param {object} model Recovered model.
+     * @returns {boolean}
+     */
+    static #bodyMatchesModel(componentBody, model) {
+        return (
+            (componentBody.modelId && componentBody.modelId === model.id) ||
+            (Number.isInteger(componentBody.checksum) &&
+                componentBody.checksum === model.checksum) ||
+            (componentBody.name &&
+                String(componentBody.name).toLowerCase() ===
+                    String(model.name || '').toLowerCase())
+        )
+    }
+
     /**
      * Resolves one model format from metadata and payload text.
      * @param {string} name
@@ -374,6 +579,27 @@ export class PcbEmbeddedModelExtractor {
             return 'wrl'
         }
 
+        if (
+            normalizedName.endsWith('.sldprt') ||
+            normalizedName.endsWith('.sldasm')
+        ) {
+            return 'solidworks'
+        }
+
+        if (
+            normalizedName.endsWith('.x_t') ||
+            normalizedName.endsWith('.xmt_txt')
+        ) {
+            return 'parasolid-text'
+        }
+
+        if (
+            normalizedName.endsWith('.x_b') ||
+            normalizedName.endsWith('.xmt_bin')
+        ) {
+            return 'parasolid-binary'
+        }
+
         return 'unknown'
     }
 

package/src/core/altium/PcbExtendedPrimitiveInformationParser.mjs

@@ -0,0 +1,256 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbSidecarRecordParser } from './PcbSidecarRecordParser.mjs'
+
+/**
+ * Decodes extended primitive sidecar records such as mask-expansion overrides.
+ */
+export class PcbExtendedPrimitiveInformationParser {
+    static #SOURCE_STREAM = 'ExtendedPrimitiveInformation/Data'
+
+    static #OBJECT_ID_TO_COLLECTION = {
+        1: ['arcs', 'arc'],
+        2: ['pads', 'pad'],
+        3: ['vias', 'via'],
+        4: ['tracks', 'track'],
+        5: ['texts', 'text'],
+        6: ['fills', 'fill'],
+        11: ['regions', 'region']
+    }
+
+    /**
+     * Parses extended primitive information records.
+     * @param {Uint8Array | ArrayBuffer | undefined} dataBytes
+     * @param {string} [sourceStream]
+     * @returns {{ entries: object[], byPrimitiveIndex: Record<string, object>, byPrimitiveKey: Record<string, object> }}
+     */
+    static parse(
+        dataBytes,
+        sourceStream = PcbExtendedPrimitiveInformationParser.#SOURCE_STREAM
+    ) {
+        const entries = PcbSidecarRecordParser.parseLengthPrefixedRecords(
+            dataBytes,
+            sourceStream
+        )
+            .map((record) =>
+                PcbExtendedPrimitiveInformationParser.#normalizeRecord(record)
+            )
+            .filter(Boolean)
+
+        return PcbExtendedPrimitiveInformationParser.#buildLookups(entries)
+    }
+
+    /**
+     * Adds extended primitive information to matching decoded primitives.
+     * @param {Record<string, object[]>} binaryPrimitives
+     * @param {{ entries?: object[] }} extendedInformation
+     */
+    static attachToPrimitives(binaryPrimitives, extendedInformation) {
+        if (!binaryPrimitives || !Array.isArray(extendedInformation?.entries)) {
+            return
+        }
+
+        for (const entry of extendedInformation.entries) {
+            const collectionName =
+                PcbExtendedPrimitiveInformationParser.#collectionNameForEntry(
+                    entry
+                )
+            const collection = binaryPrimitives[collectionName]
+
+            if (!Array.isArray(collection)) {
+                continue
+            }
+
+            const primitive = collection[entry.primitiveIndex]
+            if (!primitive) {
+                continue
+            }
+
+            primitive.extendedPrimitiveInformation =
+                PcbExtendedPrimitiveInformationParser.#publicEntry(entry)
+        }
+    }
+
+    /**
+     * Normalizes one decoded sidecar record.
+     * @param {{ fields: Record<string, string>, sourceStream: string, recordIndex: number }} record
+     * @returns {object | null}
+     */
+    static #normalizeRecord(record) {
+        const primitiveIndex = PcbSidecarRecordParser.parseInteger(
+            PcbSidecarRecordParser.firstField(record.fields, [
+                'PRIMITIVEINDEX',
+                'INDEX'
+            ])
+        )
+
+        if (primitiveIndex === null) {
+            return null
+        }
+
+        const primitiveObjectId = PcbSidecarRecordParser.parseInteger(
+            PcbSidecarRecordParser.firstField(record.fields, [
+                'PRIMITIVEOBJECTID',
+                'OBJECTID'
+            ])
+        )
+        const objectInfo =
+            PcbExtendedPrimitiveInformationParser.#OBJECT_ID_TO_COLLECTION[
+                primitiveObjectId
+            ] || []
+        const type = PcbSidecarRecordParser.firstField(record.fields, ['TYPE'])
+        const primitiveType =
+            objectInfo[1] ||
+            PcbExtendedPrimitiveInformationParser.#normalizePrimitiveType(type)
+
+        return {
+            primitiveIndex,
+            primitiveObjectId,
+            primitiveType,
+            type,
+            sourceStream: record.sourceStream,
+            maskExpansion:
+                PcbExtendedPrimitiveInformationParser.#parseMaskExpansion(
+                    record.fields
+                ),
+            fields: record.fields
+        }
+    }
+
+    /**
+     * Parses paste and solder mask-expansion fields.
+     * @param {Record<string, string>} fields
+     * @returns {{ paste: object, solder: object }}
+     */
+    static #parseMaskExpansion(fields) {
+        const pasteMode = PcbSidecarRecordParser.parseInteger(
+            PcbSidecarRecordParser.firstField(fields, [
+                'PASTEMASKEXPANSIONMODE',
+                'PASTEMASKEXPANSION_MODE'
+            ])
+        )
+        const solderMode = PcbSidecarRecordParser.parseInteger(
+            PcbSidecarRecordParser.firstField(fields, [
+                'SOLDERMASKEXPANSIONMODE',
+                'SOLDERMASKEXPANSION_MODE'
+            ])
+        )
+
+        return {
+            paste: {
+                mode: pasteMode,
+                source: PcbExtendedPrimitiveInformationParser.#maskExpansionSource(
+                    pasteMode
+                ),
+                manualExpansion: PcbSidecarRecordParser.parseNumber(
+                    PcbSidecarRecordParser.firstField(fields, [
+                        'PASTEMASKEXPANSION_MANUAL',
+                        'PASTEMASKEXPANSIONMANUAL'
+                    ])
+                )
+            },
+            solder: {
+                mode: solderMode,
+                source: PcbExtendedPrimitiveInformationParser.#maskExpansionSource(
+                    solderMode
+                ),
+                manualExpansion: PcbSidecarRecordParser.parseNumber(
+                    PcbSidecarRecordParser.firstField(fields, [
+                        'SOLDERMASKEXPANSION_MANUAL',
+                        'SOLDERMASKEXPANSIONMANUAL'
+                    ])
+                )
+            }
+        }
+    }
+
+    /**
+     * Builds primitive-index lookups.
+     * @param {object[]} entries
+     * @returns {{ entries: object[], byPrimitiveIndex: Record<string, object>, byPrimitiveKey: Record<string, object> }}
+     */
+    static #buildLookups(entries) {
+        const byPrimitiveIndex = {}
+        const byPrimitiveKey = {}
+
+        for (const entry of entries) {
+            byPrimitiveIndex[String(entry.primitiveIndex)] = entry
+            if (Number.isInteger(entry.primitiveObjectId)) {
+                byPrimitiveKey[
+                    entry.primitiveObjectId + ':' + entry.primitiveIndex
+                ] = entry
+            }
+        }
+
+        return {
+            entries,
+            byPrimitiveIndex,
+            byPrimitiveKey
+        }
+    }
+
+    /**
+     * Resolves one binary primitive collection for a sidecar entry.
+     * @param {object} entry
+     * @returns {string}
+     */
+    static #collectionNameForEntry(entry) {
+        const objectInfo =
+            PcbExtendedPrimitiveInformationParser.#OBJECT_ID_TO_COLLECTION[
+                entry.primitiveObjectId
+            ]
+        if (objectInfo) {
+            return objectInfo[0]
+        }
+
+        const primitiveType = String(entry.primitiveType || '').toLowerCase()
+        return primitiveType ? primitiveType + 's' : ''
+    }
+
+    /**
+     * Builds the public primitive-attached entry.
+     * @param {object} entry
+     * @returns {object}
+     */
+    static #publicEntry(entry) {
+        return {
+            primitiveIndex: entry.primitiveIndex,
+            primitiveObjectId: entry.primitiveObjectId,
+            primitiveType: entry.primitiveType,
+            type: entry.type,
+            sourceStream: entry.sourceStream,
+            maskExpansion: entry.maskExpansion
+        }
+    }
+
+    /**
+     * Maps one mask-expansion mode to the existing source vocabulary.
+     * @param {number | null} mode
+     * @returns {string}
+     */
+    static #maskExpansionSource(mode) {
+        if (mode === 1) return 'rule'
+        if (mode === 2) return 'manual'
+        if (mode === 0) return 'default'
+        if (mode === null) return 'unknown'
+
+        return 'unknown-' + mode
+    }
+
+    /**
+     * Normalizes one textual primitive type hint.
+     * @param {string} value
+     * @returns {string}
+     */
+    static #normalizePrimitiveType(value) {
+        const normalized = String(value || '')
+            .trim()
+            .toLowerCase()
+            .replace(/^e/iu, '')
+            .replace(/object$/iu, '')
+
+        return normalized
+    }
+}