altium-toolkit 1.0.8 → 1.0.10

package/src/core/altium/PcbDimensionParser.mjs

@@ -0,0 +1,229 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { ParserUtils } from './ParserUtils.mjs'
+
+const { getField, parseNumericField } = ParserUtils
+
+/**
+ * Normalizes read-only PCB dimension records.
+ */
+export class PcbDimensionParser {
+    /**
+     * Parses Dimensions6/Data records into public dimension objects.
+     * @param {{ fields: Record<string, string | string[]>, sourceStream?: string }[]} records
+     * @returns {object[]}
+     */
+    static parse(records) {
+        return (records || [])
+            .filter((record) => record.sourceStream === 'Dimensions6/Data')
+            .map((record, index) =>
+                PcbDimensionParser.#normalizeDimension(record.fields, index)
+            )
+            .filter(Boolean)
+    }
+
+    /**
+     * Normalizes one dimension record.
+     * @param {Record<string, string | string[]>} fields Source fields.
+     * @param {number} index Source record index within the dimensions stream.
+     * @returns {object | null}
+     */
+    static #normalizeDimension(fields, index) {
+        const kindCode = PcbDimensionParser.#firstStringField(fields, [
+            'DIMENSIONTYPE',
+            'DIMENSIONKIND',
+            'KIND',
+            'TYPE'
+        ])
+        const references = PcbDimensionParser.#parseReferences(fields)
+        const textLocation = PcbDimensionParser.#parsePoint(fields, [
+            'TEXTLOCATION',
+            'TEXT',
+            'LOCATION'
+        ])
+
+        if (!kindCode && !references.length && !getField(fields, 'TEXT')) {
+            return null
+        }
+
+        return {
+            dimensionIndex: index,
+            kind: PcbDimensionParser.#normalizeKind(kindCode),
+            kindCode,
+            name: getField(fields, 'NAME'),
+            layer: getField(fields, 'LAYER'),
+            text: getField(fields, 'TEXT'),
+            prefix: getField(fields, 'PREFIX'),
+            suffix: PcbDimensionParser.#rawStringField(fields, 'SUFFIX'),
+            precision: PcbDimensionParser.#nullableNumber(
+                parseNumericField(fields, 'PRECISION')
+            ),
+            measuredValue: PcbDimensionParser.#nullableNumber(
+                PcbDimensionParser.#firstNumericField(fields, [
+                    'MEASUREDVALUE',
+                    'MEASURED',
+                    'VALUE'
+                ])
+            ),
+            angleValue: PcbDimensionParser.#nullableNumber(
+                PcbDimensionParser.#firstNumericField(fields, [
+                    'ANGLEVALUE',
+                    'ANGLE',
+                    'MEASUREDANGLE'
+                ])
+            ),
+            unit: PcbDimensionParser.#resolveUnit(fields),
+            references,
+            textLocation,
+            raw: { ...fields }
+        }
+    }
+
+    /**
+     * Parses reference points from indexed field names.
+     * @param {Record<string, string | string[]>} fields Source fields.
+     * @returns {{ index: number, x: number, y: number }[]}
+     */
+    static #parseReferences(fields) {
+        const references = []
+
+        for (let index = 0; index < 16; index += 1) {
+            const point = PcbDimensionParser.#parsePoint(fields, [
+                'REFERENCE' + index,
+                'REF' + index,
+                'POINT' + index
+            ])
+            if (!point) {
+                continue
+            }
+            references.push({ index, ...point })
+        }
+
+        return references
+    }
+
+    /**
+     * Parses a point from common field prefixes.
+     * @param {Record<string, string | string[]>} fields Source fields.
+     * @param {string[]} prefixes Candidate field prefixes.
+     * @returns {{ x: number, y: number } | null}
+     */
+    static #parsePoint(fields, prefixes) {
+        for (const prefix of prefixes) {
+            const x = PcbDimensionParser.#firstNumericField(fields, [
+                prefix + '_X',
+                prefix + '.X',
+                prefix + 'X'
+            ])
+            const y = PcbDimensionParser.#firstNumericField(fields, [
+                prefix + '_Y',
+                prefix + '.Y',
+                prefix + 'Y'
+            ])
+
+            if (x !== null && y !== null) {
+                return { x, y }
+            }
+        }
+
+        return null
+    }
+
+    /**
+     * Reads the first non-empty string field.
+     * @param {Record<string, string | string[]>} fields Source fields.
+     * @param {string[]} keys Candidate keys.
+     * @returns {string}
+     */
+    static #firstStringField(fields, keys) {
+        for (const key of keys) {
+            const value = getField(fields, key)
+            if (value) {
+                return value
+            }
+        }
+
+        return ''
+    }
+
+    /**
+     * Reads the first finite numeric field.
+     * @param {Record<string, string | string[]>} fields Source fields.
+     * @param {string[]} keys Candidate keys.
+     * @returns {number | null}
+     */
+    static #firstNumericField(fields, keys) {
+        for (const key of keys) {
+            const value = parseNumericField(fields, key)
+            if (value !== null) {
+                return value
+            }
+        }
+
+        return null
+    }
+
+    /**
+     * Normalizes a dimension kind code.
+     * @param {string} kindCode Raw dimension kind.
+     * @returns {string}
+     */
+    static #normalizeKind(kindCode) {
+        const normalized = String(kindCode || '').toLowerCase()
+        if (/ang/u.test(normalized)) return 'angular'
+        if (/radial|radius/u.test(normalized)) return 'radial'
+        if (/datum/u.test(normalized)) return 'datum'
+        if (/baseline/u.test(normalized)) return 'baseline'
+        if (/ordinate/u.test(normalized)) return 'ordinate'
+        return 'linear'
+    }
+
+    /**
+     * Returns a number when finite, otherwise null.
+     * @param {number | null} value Numeric candidate.
+     * @returns {number | null}
+     */
+    static #nullableNumber(value) {
+        return Number.isFinite(value) ? value : null
+    }
+
+    /**
+     * Resolves a display unit from explicit or value-bearing fields.
+     * @param {Record<string, string | string[]>} fields Source fields.
+     * @returns {string}
+     */
+    static #resolveUnit(fields) {
+        const explicit = PcbDimensionParser.#firstStringField(fields, [
+            'UNIT',
+            'UNITS'
+        ])
+        if (explicit) {
+            return explicit
+        }
+
+        const suffix = getField(fields, 'SUFFIX').trim()
+        if (suffix) {
+            return suffix
+        }
+
+        const measured = getField(fields, 'MEASUREDVALUE')
+        const match = measured.match(/[a-zA-Z]+$/u)
+        return match ? match[0] : ''
+    }
+
+    /**
+     * Reads one field without trimming display-significant whitespace.
+     * @param {Record<string, string | string[]>} fields Source fields.
+     * @param {string} key Field key.
+     * @returns {string}
+     */
+    static #rawStringField(fields, key) {
+        const value = fields?.[key]
+        if (Array.isArray(value)) {
+            return String(value.findLast((entry) => entry !== '') || '')
+        }
+        return String(value || '')
+    }
+}

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'
     }