altium-toolkit 1.1.1 → 1.1.3

package/src/core/altium/SchematicPinParser.mjs

@@ -12,10 +12,15 @@ export class SchematicPinParser {
     /**
      * Normalizes schematic pin records into drawable pin primitives.
      * @param {{ fields: Record<string, string | string[]> }[]} records
+     * @param {{ ownerDrawnInternalPinOwners?: Set<string>, numericEndpointLabelOwners?: Set<string> }} [options]
      * @returns {{ x: number, y: number, length: number, name: string, nameSegments?: { text: string, overline: boolean }[], designator: string, orientation: 'left' | 'right' | 'top' | 'bottom', electrical?: number, symbolOuter?: number, color: string, labelColor: string, labelMode: 'hidden' | 'number-only' | 'name-only' | 'name-and-number', ownerIndex: string }[]}
      */
-    static parseSchematicPins(records) {
+    static parseSchematicPins(records, options = {}) {
         const groups = new Map()
+        const ownerDrawnInternalPinOwners =
+            options.ownerDrawnInternalPinOwners || new Set()
+        const numericEndpointLabelOwners =
+            options.numericEndpointLabelOwners || new Set()
 
         for (const record of records) {
             const ownerIndex = ParserUtils.getField(record.fields, 'OwnerIndex')
@@ -81,7 +86,11 @@ export class SchematicPinParser {
         }
 
         return [...groups.values()].flatMap((pins) =>
-            SchematicPinParser.#normalizeSchematicPinGroup(pins)
+            SchematicPinParser.#normalizeSchematicPinGroup(
+                pins,
+                ownerDrawnInternalPinOwners,
+                numericEndpointLabelOwners
+            )
         )
     }
 
@@ -730,9 +739,15 @@ export class SchematicPinParser {
     /**
      * Deduces the visible pins for one schematic symbol owner.
      * @param {{ x: number, y: number, length: number, conglomerate?: number, name: string, nameSegments?: { text: string, overline: boolean }[], designator: string, orientation: 'left' | 'right' | 'top' | 'bottom', electrical?: number, symbolOuter?: number, color?: string, labelColor?: string, ownerIndex: string }[]} pins
+     * @param {Set<string>} ownerDrawnInternalPinOwners
+     * @param {Set<string>} numericEndpointLabelOwners
      * @returns {{ x: number, y: number, length: number, name: string, nameSegments?: { text: string, overline: boolean }[], designator: string, orientation: 'left' | 'right' | 'top' | 'bottom', electrical?: number, symbolOuter?: number, color: string, labelColor: string, labelMode: 'hidden' | 'number-only' | 'name-only' | 'name-and-number', ownerIndex: string }[]}
      */
-    static #normalizeSchematicPinGroup(pins) {
+    static #normalizeSchematicPinGroup(
+        pins,
+        ownerDrawnInternalPinOwners,
+        numericEndpointLabelOwners
+    ) {
         const deduped = SchematicPinParser.#dedupeSchematicPins(pins)
         const inferredSequentialDesignators =
             SchematicPinDesignatorInferer.inferSequentialCompactFourPinDesignators(
@@ -773,6 +788,7 @@ export class SchematicPinParser {
                     /^\d+$/.test(String(pin.designator || '').trim()) &&
                     (!pin.name || /^\d+$/.test(String(pin.name || '').trim()))
             )
+        const ownerIndex = normalizedPins[0]?.ownerIndex || ''
         let labelMode = 'name-and-number'
 
         if (
@@ -795,12 +811,26 @@ export class SchematicPinParser {
             labelMode = 'number-only'
         }
 
-        if (allPassive && normalizedPins.length <= 2) {
+        if (
+            numericEndpointLabelOwners.has(ownerIndex) &&
+            SchematicPinParser.#isTwoPinNumericEndpointGroup(normalizedPins)
+        ) {
+            labelMode = 'number-only'
+        } else if (allPassive && normalizedPins.length <= 2) {
             labelMode = SchematicPinParser.#isCanonicalPassiveTwoPinGroup(
                 normalizedPins
             )
                 ? 'hidden'
                 : 'number-only'
+        } else if (
+            ownerDrawnInternalPinOwners.has(ownerIndex) &&
+            SchematicPinParser.#isCompactNumberedFetTerminalGroup(
+                normalizedPins,
+                semanticNames,
+                orientationCount
+            )
+        ) {
+            labelMode = 'number-only'
         } else if (
             SchematicPinParser.#isOwnerDrawnTerminalGlyphGroup(
                 normalizedPins,
@@ -809,6 +839,24 @@ export class SchematicPinParser {
             )
         ) {
             labelMode = 'hidden'
+        } else if (
+            ownerDrawnInternalPinOwners.has(ownerIndex) &&
+            SchematicPinParser.#isCompactInternalTerminalGroup(
+                normalizedPins,
+                names,
+                orientationCount
+            )
+        ) {
+            labelMode = 'hidden'
+        } else if (
+            ownerDrawnInternalPinOwners.has(ownerIndex) &&
+            SchematicPinParser.#isCompactTwoPinInternalTerminalGroup(
+                normalizedPins,
+                names,
+                orientationCount
+            )
+        ) {
+            labelMode = 'number-only'
         } else if (!semanticNames.length && orientationCount <= 2) {
             labelMode = 'number-only'
         } else if (
@@ -827,6 +875,33 @@ export class SchematicPinParser {
         }))
     }
 
+    /**
+     * Returns true when a compact owner-drawn FET body uses semantic terminal
+     * names internally but still exposes external numeric contact labels.
+     * @param {{ designator: string, name: string, orientation: 'left' | 'right' | 'top' | 'bottom' }[]} pins
+     * @param {string[]} semanticNames
+     * @param {number} orientationCount
+     * @returns {boolean}
+     */
+    static #isCompactNumberedFetTerminalGroup(
+        pins,
+        semanticNames,
+        orientationCount
+    ) {
+        if (
+            pins.length !== 4 ||
+            orientationCount < 3 ||
+            semanticNames.length !== pins.length ||
+            !pins.every((pin) => /^\d+$/.test(String(pin.designator || '')))
+        ) {
+            return false
+        }
+
+        return semanticNames.every((name) =>
+            SchematicPinParser.#isFetTerminalName(name)
+        )
+    }
+
     /**
      * Returns true when a compact multi-side owner has transistor-like terminal
      * letters that are part of the drawn symbol body, not external pin labels.
@@ -858,6 +933,60 @@ export class SchematicPinParser {
         )
     }
 
+    /**
+     * Returns true when a compact owner-drawn body carries repeated internal
+     * terminal names that belong to the symbol body, not external labels.
+     * @param {{ designator: string, name: string, orientation: 'left' | 'right' | 'top' | 'bottom' }[]} pins
+     * @param {string[]} names
+     * @param {number} orientationCount
+     * @returns {boolean}
+     */
+    static #isCompactInternalTerminalGroup(pins, names, orientationCount) {
+        if (
+            pins.length < 3 ||
+            pins.length > 4 ||
+            orientationCount < 3 ||
+            names.length >= pins.length ||
+            !SchematicPinParser.#hasOptionalNumericPinDesignators(pins)
+        ) {
+            return false
+        }
+
+        return (
+            names.length > 0 &&
+            names.every((name) =>
+                SchematicPinParser.#isInternalTerminalName(name)
+            )
+        )
+    }
+
+    /**
+     * Returns true when a compact two-pin owner-drawn symbol stores internal
+     * placeholder terminal names that should not be rendered as labels.
+     * @param {{ designator: string, name: string, orientation: 'left' | 'right' | 'top' | 'bottom' }[]} pins
+     * @param {string[]} names
+     * @param {number} orientationCount
+     * @returns {boolean}
+     */
+    static #isCompactTwoPinInternalTerminalGroup(
+        pins,
+        names,
+        orientationCount
+    ) {
+        if (
+            pins.length !== 2 ||
+            orientationCount < 2 ||
+            names.length !== pins.length ||
+            !SchematicPinParser.#hasOptionalNumericPinDesignators(pins)
+        ) {
+            return false
+        }
+
+        return names.every((name) =>
+            SchematicPinParser.#isInternalTerminalName(name)
+        )
+    }
+
     /**
      * Returns true when compact owner-drawn terminal glyph pins have either no
      * external designators or ordinary numeric pin numbers.
@@ -881,6 +1010,28 @@ export class SchematicPinParser {
         return /^[BCDEGS]$/i.test(String(name || '').trim())
     }
 
+    /**
+     * Returns true for FET terminal names, including numbered gate/source
+     * variants used by dual-gate symbols.
+     * @param {string} name
+     * @returns {boolean}
+     */
+    static #isFetTerminalName(name) {
+        return /^(?:[DS]|[GS]\d*)$/i.test(String(name || '').trim())
+    }
+
+    /**
+     * Returns true for compact internal terminal labels usually drawn inside
+     * owner-authored symbol bodies.
+     * @param {string} name
+     * @returns {boolean}
+     */
+    static #isInternalTerminalName(name) {
+        return /^(x|y|gnd|agnd|dgnd|pgnd|vcc|vdd|vee|vss|nc)$/i.test(
+            String(name || '').trim()
+        )
+    }
+
     /**
      * Returns true when one passive two-pin symbol uses the ordinary 1/2 pin
      * numbering that should stay hidden for simple resistor-like parts.
@@ -899,6 +1050,24 @@ export class SchematicPinParser {
         return designators[0] === '1' && designators[1] === '2'
     }
 
+    /**
+     * Returns true when one owner exposes exactly two numeric endpoints.
+     * @param {{ designator: string, name: string }[]} pins
+     * @returns {boolean}
+     */
+    static #isTwoPinNumericEndpointGroup(pins) {
+        if (pins.length !== 2) {
+            return false
+        }
+
+        return pins.every((pin) => {
+            const designator = String(pin.designator || '').trim()
+            const name = String(pin.name || '').trim()
+
+            return /^\d+$/.test(designator) && (!name || /^\d+$/.test(name))
+        })
+    }
+
     /**
      * Returns true when one owner uses the dense two-sided horizontal 48/50
      * pin family whose semantic names belong to the owner-drawn symbol body
@@ -1049,10 +1218,12 @@ export class SchematicPinParser {
     static #inferSchematicPinOrientation(conglomerate) {
         switch (conglomerate) {
             case 34:
+            case 42:
             case 50:
             case 58:
                 return 'left'
             case 32:
+            case 40:
             case 48:
             case 56:
                 return 'right'

package/src/core/altium/SchematicQaReportBuilder.mjs

@@ -4,8 +4,7 @@
 
 import { ParserUtils } from './ParserUtils.mjs'
 
-const { getDisplayText, getField, parseBoolean, parseNumericField, toColor } =
-    ParserUtils
+const { parseBoolean, parseNumericField, toColor } = ParserUtils
 
 /**
  * Builds deterministic read-only QA summaries for schematic documents.
@@ -25,12 +24,17 @@ export class SchematicQaReportBuilder {
         const lineWidths = SchematicQaReportBuilder.#lineWidths(records)
         const unresolvedParameters =
             SchematicQaReportBuilder.#unresolvedParameters(records)
+        const titleBlockResidue =
+            SchematicQaReportBuilder.#titleBlockResidue(records)
         const findings = [
             ...SchematicQaReportBuilder.#fontFindings(fonts),
             ...SchematicQaReportBuilder.#unresolvedFindings(
                 unresolvedParameters
             ),
-            ...SchematicQaReportBuilder.#titleBlockFindings(records)
+            ...SchematicQaReportBuilder.#titleBlockFindings(
+                records,
+                titleBlockResidue
+            )
         ]
 
         return {
@@ -47,8 +51,7 @@ export class SchematicQaReportBuilder {
             colors,
             lineWidths,
             unresolvedParameters,
-            titleBlockResidue:
-                SchematicQaReportBuilder.#titleBlockResidue(records),
+            titleBlockResidue,
             geometryFallbacks: SchematicQaReportBuilder.#geometryFallbacks(
                 input?.texts
             ),
@@ -138,26 +141,15 @@ export class SchematicQaReportBuilder {
      * @returns {string[]}
      */
     static #unresolvedParameters(records) {
-        const metadata = new Set(
-            (records || [])
-                .filter((record) => getField(record.fields, 'RECORD') === '41')
-                .map((record) => getField(record.fields, 'Name'))
-                .filter(Boolean)
-        )
         const unresolved = []
 
         for (const record of records || []) {
-            const text = getDisplayText(record.fields)
+            const text = SchematicQaReportBuilder.#displayText(record.fields)
             const match = text.match(/^=([A-Za-z_][\w.]*)$/)
             if (!match) {
                 continue
             }
-            if (
-                !metadata.has(match[1]) ||
-                text === getDisplayText(record.fields)
-            ) {
-                unresolved.push(match[1])
-            }
+            unresolved.push(match[1])
         }
 
         return [...new Set(unresolved)].sort()
@@ -200,23 +192,25 @@ export class SchematicQaReportBuilder {
     /**
      * Builds title-block findings.
      * @param {object[]} records Schematic records.
+     * @param {object[]} titleBlockResidue Hidden title-block residue rows.
      * @returns {object[]}
      */
-    static #titleBlockFindings(records) {
+    static #titleBlockFindings(records, titleBlockResidue) {
         const sheet = (records || []).find(
-            (record) => getField(record.fields, 'RECORD') === '31'
+            (record) =>
+                SchematicQaReportBuilder.#field(record.fields, 'RECORD') ===
+                '31'
         )
         if (!sheet || parseBoolean(sheet.fields.TitleBlockOn)) {
             return []
         }
 
-        const residue = SchematicQaReportBuilder.#titleBlockResidue(records)
-        return residue.length
+        return titleBlockResidue.length
             ? [
                   {
                       code: 'schematic.title-block.hidden-residue',
                       severity: 'info',
-                      count: residue.length,
+                      count: titleBlockResidue.length,
                       message:
                           'Hidden title-block parameter records remain while the title block is disabled.'
                   }
@@ -240,22 +234,32 @@ export class SchematicQaReportBuilder {
             'drawnby'
         ])
 
-        return (records || [])
-            .filter(
-                (record) =>
-                    getField(record.fields, 'RECORD') === '41' &&
-                    parseBoolean(record.fields.IsHidden) &&
-                    titleBlockNames.has(
-                        getField(record.fields, 'Name')
-                            .replace(/\s+/g, '')
-                            .toLowerCase()
-                    )
-            )
-            .map((record) => ({
+        const residue = []
+
+        for (const record of records || []) {
+            const fields = record.fields || {}
+            if (
+                SchematicQaReportBuilder.#field(fields, 'RECORD') !== '41' ||
+                !parseBoolean(
+                    SchematicQaReportBuilder.#rawField(fields, 'IsHidden')
+                )
+            ) {
+                continue
+            }
+
+            const name = SchematicQaReportBuilder.#field(fields, 'Name')
+            if (!titleBlockNames.has(name.replace(/\s+/g, '').toLowerCase())) {
+                continue
+            }
+
+            residue.push({
                 recordKey: SchematicQaReportBuilder.#recordKey(record),
-                name: getField(record.fields, 'Name'),
-                value: getDisplayText(record.fields)
-            }))
+                name,
+                value: SchematicQaReportBuilder.#displayText(fields)
+            })
+        }
+
+        return residue
     }
 
     /**
@@ -281,4 +285,77 @@ export class SchematicQaReportBuilder {
     static #recordKey(record) {
         return 'schematic-record-' + String(record?.recordIndex ?? 0)
     }
+
+    /**
+     * Reads one common field without invoking generic field-cache bookkeeping.
+     * @param {Record<string, string | string[]> | undefined} fields Record fields.
+     * @param {string} key Requested key.
+     * @returns {string}
+     */
+    static #field(fields, key) {
+        return SchematicQaReportBuilder.#pickFieldValue(
+            SchematicQaReportBuilder.#rawField(fields, key),
+            false
+        )
+    }
+
+    /**
+     * Returns the best schematic display text without shared field-cache overhead.
+     * @param {Record<string, string | string[]> | undefined} fields Record fields.
+     * @returns {string}
+     */
+    static #displayText(fields) {
+        return (
+            SchematicQaReportBuilder.#pickFieldValue(
+                SchematicQaReportBuilder.#rawField(fields, 'UTF8:Text'),
+                true
+            ) ||
+            SchematicQaReportBuilder.#pickFieldValue(
+                SchematicQaReportBuilder.#rawField(fields, 'Text'),
+                true
+            )
+        )
+    }
+
+    /**
+     * Reads one raw field from parsed records or simple fixture objects.
+     * @param {Record<string, string | string[]> | undefined} fields Record fields.
+     * @param {string} key Requested key.
+     * @returns {string | string[] | undefined}
+     */
+    static #rawField(fields, key) {
+        if (!fields || typeof fields !== 'object') {
+            return undefined
+        }
+
+        const direct = fields[key]
+        if (direct !== undefined) {
+            return direct
+        }
+
+        const upperKey = key.toUpperCase()
+        return upperKey === key ? undefined : fields[upperKey]
+    }
+
+    /**
+     * Returns the last meaningful value from one field payload.
+     * @param {string | string[] | undefined} raw Raw field payload.
+     * @param {boolean} skipAsterisk Whether placeholder asterisks are ignored.
+     * @returns {string}
+     */
+    static #pickFieldValue(raw, skipAsterisk) {
+        if (!Array.isArray(raw)) {
+            const value = String(raw || '').trim()
+            return value && (!skipAsterisk || value !== '*') ? value : ''
+        }
+
+        for (let index = raw.length - 1; index >= 0; index -= 1) {
+            const value = String(raw[index] || '').trim()
+            if (value && (!skipAsterisk || value !== '*')) {
+                return value
+            }
+        }
+
+        return ''
+    }
 }

package/src/core/altium/SchematicSheetStyleResolver.mjs

@@ -43,4 +43,42 @@ export class SchematicSheetStyleResolver {
 
         return configuredXZones
     }
+
+    /**
+     * Resolves the displayed vertical sheet-zone count after the page size
+     * has been normalized.
+     * @param {{ width: number, height: number, yZones: number, paperSize?: string, sheetStyle?: number }} sheet
+     * @returns {number}
+     */
+    static resolveYZones(sheet) {
+        const configuredYZones = Math.max(Number(sheet?.yZones || 0), 1)
+        const paperSize = String(sheet?.paperSize || '')
+            .trim()
+            .toUpperCase()
+
+        if (Number(sheet?.sheetStyle || 0) !== 1 && !paperSize) {
+            return configuredYZones
+        }
+
+        const width = Number(sheet?.width || 0)
+        const height = Number(sheet?.height || 0)
+        if (height < width) {
+            return configuredYZones
+        }
+
+        if (
+            paperSize === 'A2' ||
+            (width === 1654 && height === 2339) ||
+            paperSize === 'A3' ||
+            (width === 1169 && height === 1654)
+        ) {
+            return 8
+        }
+
+        if (paperSize === 'A4' || (width === 827 && height === 1169)) {
+            return 4
+        }
+
+        return configuredYZones
+    }
 }