Files
likang 7e01147566
CI / typecheck + test + build (push) Has been cancelled
Initial commit: import VibeMake PCB Studio
2026-11-03 11:20:08 +08:00

352 lines
11 KiB
TypeScript

// SPDX-License-Identifier: GPL-3.0-or-later
// Copyright (C) 2026 ZiroEDA and contributors.
// Portions derived from KiCad, copyright The KiCad Developers. See NOTICE.md.
/**
* `eeschema/symbol_import_manager.cpp`/`.h`: `SYMBOL_IMPORT_MANAGER`, the
* selection/dependency state machine behind "Import Symbol(s)" (choosing a
* subset of a source library's symbols to bring in, auto-selecting a derived
* symbol's ancestors, and flagging name conflicts with the destination
* library). Upstream's own header calls this out as "designed to be
* UI-independent for testability" — no `LIB_SYMBOL` methods are actually
* called, only stored, so this file has no rendering/library dependency
* either.
*
* `std::map<wxString, …>` iteration is name order (`wxString::operator<`, a
* code-unit ordering); the methods that build a return value by iterating
* `m_symbols` sort by that order explicitly, since a `Map` iterates by
* insertion order instead. Likewise `GetAncestors`/`GetDescendants` return a
* `std::set<wxString>` (always sorted); the `Set` this returns is built by
* inserting in sorted order so a caller's `for…of` sees the same order.
*/
import type { LIB_SYMBOL } from './lib_symbol.js';
/** `wxString::operator<`: a code-unit ordering. */
const wxLess = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
/** Information about a symbol available for import. */
export interface SYMBOL_IMPORT_INFO {
/** Symbol name */
m_name: string;
/**
* Loaded symbol (may be null). `unique_ptr<LIB_SYMBOL>` upstream; this file
* only stores/returns it (never calls a `LIB_SYMBOL` method), so plain
* ownership by reference stands in for the `unique_ptr`.
*/
m_symbol: LIB_SYMBOL | null;
/** Parent symbol name if derived */
m_parentName: string;
/** True if power symbol */
m_isPower: boolean;
/** True if symbol exists in destination library */
m_existsInDest: boolean;
/** User's manual selection state */
m_checked: boolean;
/** True if auto-selected as dependency */
m_autoSelected: boolean;
}
/** Result of conflict resolution for a single symbol. */
export enum CONFLICT_RESOLUTION {
/** Don't import this symbol */
SKIP = 0,
/** Overwrite existing symbol */
OVERWRITE = 1,
}
/** `SYMBOL_EXISTS_FUNC`: true if `symbolName` already exists in the destination. */
export type SYMBOL_EXISTS_FUNC = (symbolName: string) => boolean;
/**
* Manages the logic for selecting symbols to import from a library file.
*
* This class handles:
* - Loading and tracking symbol metadata from source libraries
* - Building dependency graphs for derived symbols
* - Auto-selecting parent symbols when derived symbols are selected
* - Tracking conflicts with existing symbols in destination library
* - Filtering symbols by search criteria
*/
export class SYMBOL_IMPORT_MANAGER {
/** All symbols available for import, keyed by name */
private m_symbols = new Map<string, SYMBOL_IMPORT_INFO>();
/** Map from symbol name to its parent name (for derived symbols) */
private m_parentMap = new Map<string, string>();
/** Map from parent name to list of direct derivative names */
private m_derivativesMap = new Map<string, string[]>();
/** `m_symbols` names, in `std::map` (code-unit) order. */
private sortedNames(): string[] {
return [...this.m_symbols.keys()].sort(wxLess);
}
/** `m_symbols` entries, in `std::map` (code-unit) order. */
private sortedEntries(): [string, SYMBOL_IMPORT_INFO][] {
return this.sortedNames().map((name) => [name, this.m_symbols.get(name)!]);
}
/** Clear all loaded symbols and reset state. */
Clear(): void {
this.m_symbols.clear();
this.m_parentMap.clear();
this.m_derivativesMap.clear();
}
/** Add a symbol to the import list. */
AddSymbol(
aName: string,
aParentName: string,
aIsPower: boolean,
aSymbol: LIB_SYMBOL | null = null,
): void {
this.m_symbols.set(aName, {
m_name: aName,
m_symbol: aSymbol,
m_parentName: aParentName,
m_isPower: aIsPower,
m_existsInDest: false,
m_checked: false,
m_autoSelected: false,
});
}
/** Mark symbols that exist in the destination library. */
CheckExistingSymbols(aExistsFunc: SYMBOL_EXISTS_FUNC): void {
for (const [name, info] of this.sortedEntries()) info.m_existsInDest = aExistsFunc(name);
}
/** Build the dependency maps from parent relationships. Call after all symbols are added. */
BuildDependencyMaps(): void {
this.m_parentMap.clear();
this.m_derivativesMap.clear();
for (const [name, info] of this.sortedEntries()) {
if (info.m_parentName !== '') {
this.m_parentMap.set(name, info.m_parentName);
const derivatives = this.m_derivativesMap.get(info.m_parentName);
if (derivatives) derivatives.push(name);
else this.m_derivativesMap.set(info.m_parentName, [name]);
}
}
}
/** Get all symbol names. */
GetSymbolNames(): string[] {
return this.sortedNames();
}
/** Get symbol info by name, or null if not found. */
GetSymbolInfo(aName: string): SYMBOL_IMPORT_INFO | null {
return this.m_symbols.get(aName) ?? null;
}
/** Get all ancestors of a symbol (full inheritance chain), sorted. */
GetAncestors(aSymbolName: string): Set<string> {
const ancestors: string[] = [];
let current = aSymbolName;
while (true) {
const parent = this.m_parentMap.get(current);
if (parent === undefined || parent === '') break;
if (!this.m_symbols.has(parent)) break;
ancestors.push(parent);
current = parent;
}
return new Set(ancestors.sort(wxLess));
}
/** Get all descendants of a symbol (all derived symbols recursively), sorted. */
GetDescendants(aSymbolName: string): Set<string> {
const descendants = new Set<string>();
const toProcess = [aSymbolName];
while (toProcess.length > 0) {
const current = toProcess.pop()!;
const children = this.m_derivativesMap.get(current);
if (children) {
for (const child of children) {
if (!descendants.has(child)) {
descendants.add(child);
toProcess.push(child);
}
}
}
}
return new Set([...descendants].sort(wxLess));
}
/** Get the direct parent of a symbol, or '' if none. */
GetParent(aSymbolName: string): string {
return this.m_parentMap.get(aSymbolName) ?? '';
}
/** Get direct children (derivatives) of a symbol, in the order BuildDependencyMaps built them. */
GetDirectDerivatives(aSymbolName: string): string[] {
return [...(this.m_derivativesMap.get(aSymbolName) ?? [])];
}
/** Check if a symbol is derived from another. */
IsDerived(aSymbolName: string): boolean {
const parent = this.m_parentMap.get(aSymbolName);
return parent !== undefined && parent !== '';
}
/**
* Set the selection state of a symbol. This handles auto-selection of
* ancestors.
*
* @returns the names of symbols whose auto-selection state changed:
* exactly the newly-auto-selected ancestors when selecting, or every other
* symbol name (a full recalculation ran) when deselecting.
*/
SetSymbolSelected(aSymbolName: string, aSelected: boolean): string[] {
const changedSymbols: string[] = [];
const info = this.GetSymbolInfo(aSymbolName);
if (!info) return changedSymbols;
if (aSelected) {
info.m_checked = true;
info.m_autoSelected = false;
for (const ancestor of this.GetAncestors(aSymbolName)) {
const ancestorInfo = this.GetSymbolInfo(ancestor);
if (ancestorInfo && !ancestorInfo.m_checked && !ancestorInfo.m_autoSelected) {
ancestorInfo.m_autoSelected = true;
changedSymbols.push(ancestor);
}
}
} else {
info.m_checked = false;
info.m_autoSelected = false;
this.recalculateAutoSelections();
for (const name of this.sortedNames()) {
if (name !== aSymbolName) changedSymbols.push(name);
}
}
return changedSymbols;
}
/** Get selected descendants that would be orphaned if a symbol is deselected. */
GetSelectedDescendants(aSymbolName: string): string[] {
const selectedDescendants: string[] = [];
for (const desc of this.GetDescendants(aSymbolName)) {
const info = this.GetSymbolInfo(desc);
if (info?.m_checked) selectedDescendants.push(desc);
}
return selectedDescendants;
}
/** Force deselection of a symbol and all its descendants, after a confirmed cascade. */
DeselectWithDescendants(aSymbolName: string): void {
const info = this.GetSymbolInfo(aSymbolName);
if (info) {
info.m_checked = false;
info.m_autoSelected = false;
}
for (const desc of this.GetDescendants(aSymbolName)) {
const descInfo = this.GetSymbolInfo(desc);
if (descInfo) {
descInfo.m_checked = false;
descInfo.m_autoSelected = false;
}
}
this.recalculateAutoSelections();
}
/** Select all symbols (optionally filtered). */
SelectAll(aFilter?: (name: string) => boolean): void {
for (const [name, info] of this.sortedEntries()) {
if (!aFilter || aFilter(name)) {
info.m_checked = true;
info.m_autoSelected = false;
}
}
this.recalculateAutoSelections();
}
/** Deselect all symbols (optionally filtered). */
DeselectAll(aFilter?: (name: string) => boolean): void {
for (const [name, info] of this.sortedEntries()) {
if (!aFilter || aFilter(name)) {
info.m_checked = false;
info.m_autoSelected = false;
}
}
this.recalculateAutoSelections();
}
/** Get list of all symbols that will be imported (checked + auto-selected). */
GetSymbolsToImport(): string[] {
return this.sortedEntries()
.filter(([, info]) => info.m_checked || info.m_autoSelected)
.map(([name]) => name);
}
/** Get count of manually selected symbols. */
GetManualSelectionCount(): number {
let count = 0;
for (const info of this.m_symbols.values()) if (info.m_checked) count++;
return count;
}
/** Get count of auto-selected symbols (dependencies). */
GetAutoSelectionCount(): number {
let count = 0;
for (const info of this.m_symbols.values()) if (info.m_autoSelected && !info.m_checked) count++;
return count;
}
/** Get list of symbols that will conflict (selected and exist in destination). */
GetConflicts(): string[] {
return this.sortedEntries()
.filter(([, info]) => (info.m_checked || info.m_autoSelected) && info.m_existsInDest)
.map(([name]) => name);
}
/** Check if a symbol name matches a filter string (case-insensitive contains). */
static MatchesFilter(aSymbolName: string, aFilter: string): boolean {
if (aFilter === '') return true;
return aSymbolName.toLowerCase().includes(aFilter.toLowerCase());
}
/** Get total number of symbols. */
GetSymbolCount(): number {
return this.m_symbols.size;
}
/** Recalculate auto-selection state for all symbols based on current manual selections. */
private recalculateAutoSelections(): void {
// Clear all auto-selections
for (const info of this.m_symbols.values()) info.m_autoSelected = false;
// Re-apply auto-selections for all checked symbols
for (const [name, info] of this.sortedEntries()) {
if (info.m_checked) {
for (const ancestor of this.GetAncestors(name)) {
const ancestorInfo = this.GetSymbolInfo(ancestor);
if (ancestorInfo && !ancestorInfo.m_checked) ancestorInfo.m_autoSelected = true;
}
}
}
}
}