Files
vibemake-pcb-studio/eeschema/project.ts
T
likang 1fde96c05e
CI / typecheck + test + build (push) Has been cancelled
打通vibemake
2026-11-05 16:21:37 +08:00

328 lines
13 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.
/**
* Multi-sheet project helpers, mirroring KiCad's SCH_SHEET_LIST hierarchy walk:
* the root schematic references sub-sheets through their "Sheetfile" field, each
* of which is another .kicad_sch document. Documents are keyed by project-relative
* path, so identically named sheets in different directories stay distinct.
*/
import type { Schematic, SchSheet } from './types.js';
import {
comparePageNum,
getRootPageNumber,
getSheetPageNumber,
setRootPageNumberCommand,
setSheetPageNumberCommand,
} from './sch_sheet_path.js';
/** The "Sheetname" field value (KiCad's mandatory sheet-name field). */
export function sheetName(sheet: SchSheet): string {
return sheet.fields.find((f) => f.key === 'Sheetname')?.value ?? '';
}
/** Resolve Sheetfile relative to the containing schematic, within the project. */
export function sheetFile(sheet: SchSheet, parentFile = ''): string {
const raw = sheet.fields.find((f) => f.key === 'Sheetfile')?.value ?? '';
if (!raw || raw.startsWith('/') || /^[A-Za-z]:/.test(raw)) return '';
const path = raw.startsWith('${KIPRJMOD}/')
? raw.slice('${KIPRJMOD}/'.length)
: parentFile.slice(0, Math.max(0, parentFile.lastIndexOf('/') + 1)) + raw;
const parts: string[] = [];
for (const part of path.replace(/\\/g, '/').split('/')) {
if (part === '..') {
if (!parts.length) return '';
parts.pop();
} else if (part && part !== '.') parts.push(part);
}
return parts.join('/');
}
export interface SheetTreeNode {
/** Document basename, e.g. "power.kicad_sch". */
file: string;
/** Display name: the Sheetname field, or the file for the root. */
name: string;
/**
* Unique instance path, KiCad's SCH_SHEET_PATH (KIID_PATH): the chain of
* sheet-symbol UUIDs from the root ("/", then "/<uuid>/", "/<uuid>/<uuid>/"…).
* A file used by several sheet instances (a *complex* hierarchy) appears once
* per instance with a distinct path, so navigation/highlight can tell them
* apart even though they share one document.
*/
path: string;
/** Stored page number (SCH_SHEET_PATH::GetPageNumber), '' if unset. */
page: string;
children: SheetTreeNode[];
}
/**
* One sheet instance of the hierarchy as `SCH_SHEET_LIST` carries it, plus
* where its page number is stored: the sheet symbol lives in its PARENT's
* document, keyed by the instance path of that document's screen.
*/
interface SheetEntry {
node: SheetTreeNode;
/** The document holding the sheet symbol; undefined for the root sheet. */
parentFile?: string;
/** Index into `parentFile`'s `sheets`. */
sheetIndex: number;
/** `instanceKey` of the sheet symbol's instance (SCH_SHEET_PATH::Path() then pop_back). */
instanceKey: string;
}
/**
* `SCH_SCREEN::GetSheets` (sch_screen.cpp:1228-1249): a screen's sheet symbols
* by x, then y, then `KIID::operator<` — a byte compare of the uuid, which for
* the canonical lowercase-hex form is a codepoint compare. Not `localeCompare`:
* that follows the browser's locale and can fold case.
*/
const byPosition = (a: SchSheet, b: SchSheet): number => {
if (a.at.x !== b.at.x) return a.at.x - b.at.x;
if (a.at.y !== b.at.y) return a.at.y - b.at.y;
const ua = a.uuid ?? '';
const ub = b.uuid ?? '';
return ua < ub ? -1 : ua > ub ? 1 : 0;
};
/**
* `SCH_SHEET_LIST::BuildSheetList` (sch_sheet_path.cpp:1018): the hierarchy in
* placement order — each screen's sheets as `GetSheets` sorts them, depth
* first — with every sheet's STORED page number. The position in this walk is
* the sheet's virtual page number, which is what breaks a page-number tie
* everywhere upstream (`SortByPageNumbers`, `ComparePageNum`).
*
* A missing document still appears (as a leaf) so broken links are visible;
* recursion guards against self-referencing cycles (TestForRecursion).
*/
function buildSheetList(
docs: ReadonlyMap<string, Schematic>,
rootFile: string,
): { root: SheetTreeNode; flat: SheetEntry[] } {
const rootDoc = docs.get(rootFile);
const rootUuid = rootDoc?.uuid ?? '';
// The instance path of the sheets placed directly inside `ancestorUuids`'
// screen (SCH_SHEET_PATH::Path() then pop_back()): "/<rootUuid>" for the
// root screen's own sheets, one segment deeper per level of nesting.
const containingPath = (ancestorUuids: readonly string[]): string =>
`/${[rootUuid, ...ancestorUuids].join('/')}`;
const flat: SheetEntry[] = [];
const build = (
entry: Omit<SheetEntry, 'node'>,
file: string,
name: string,
path: string,
page: string,
stack: readonly string[],
ancestorUuids: readonly string[],
): SheetTreeNode => {
const node: SheetTreeNode = { file, name, path, page, children: [] };
flat.push({ ...entry, node });
if (stack.includes(file)) return node; // recursion guard (KiCad TestForRecursion)
const doc = docs.get(file);
if (!doc) return node;
const key = containingPath(ancestorUuids);
// `GetSheets` sorts a COPY; the index into `doc.sheets` is what an edit
// command addresses, so it is taken before the sort.
const sheets = doc.sheets.map((sh, i) => ({ sh, i })).sort((a, b) => byPosition(a.sh, b.sh));
for (const { sh, i } of sheets) {
const child = sheetFile(sh, file);
if (child === '') continue;
// Append this sheet symbol's uuid (falling back to its index) so each
// instance of a shared file gets its own path.
const uuid = sh.uuid || `i${i}`;
const childPath = `${path}${uuid}/`;
const childName = sheetName(sh) || child.replace(/\.kicad_sch$/i, '');
node.children.push(
build(
{ parentFile: file, sheetIndex: i, instanceKey: key },
child,
childName,
childPath,
getSheetPageNumber(sh, key),
[...stack, file],
[...ancestorUuids, uuid],
),
);
}
return node;
};
const root = build(
{ sheetIndex: -1, instanceKey: '/' },
rootFile,
rootFile.replace(/\.kicad_sch$/i, ''),
'/',
rootDoc ? getRootPageNumber(rootDoc) : '',
[],
[],
);
return { root, flat };
}
/**
* `SCHEMATIC::Hierarchy()`: `BuildSheetListSortedByPageNumbers`
* (schematic.cpp:2129) is the placement-order list above put through
* `SCH_SHEET_LIST::SortByPageNumbers` (sch_sheet_path.cpp:1159) — one FLAT
* sort over every sheet of the hierarchy, by page number and then by virtual
* page number. `Array.prototype.sort` is stable, so the placement order that
* `buildSheetList` produced is the tie-break, as the virtual page number is.
*/
function sortByPageNumbers(flat: readonly SheetEntry[]): SheetEntry[] {
return [...flat].sort((a, b) => comparePageNum(a.node.page, b.node.page));
}
/**
* Build the hierarchy tree from the root document, following each sheet's
* Sheetfile into `docs`.
*
* Siblings are sorted by their stored page number — `HIERARCHY_TREE::
* OnCompareItems` is `SCH_SHEET_PATH::ComparePageNum` (sch_sheet_path.cpp:226),
* the page compare with the virtual page number as the tie-break — rather than
* by sheet-symbol placement order: KiCad's tree only uses placement position
* to seed page numbers when they're first assigned, but always displays
* siblings in page-number order. Two siblings on the same page (a file KiCad
* would repair on load, see {@link repairPageNumbersOnLoad}) keep their
* placement order, which is what the virtual page number encodes.
*
* A file saved before KiCad tracked per-instance page numbers (or never
* re-saved since) has none stored anywhere at all; SCH_SHEET_LIST's own
* AllSheetPageNumbersEmpty() guard catches exactly that and, in that case
* only, seeds them (SetInitialPageNumbers) by numbering the placement-order
* DFS sequentially from the root. A file with even one stored page number
* skips this entirely and shows the rest blank, same as upstream. The loader
* writes those numbers into the documents; this fallback is for a hierarchy
* that did not come through it.
*/
export function buildSheetTree(
docs: ReadonlyMap<string, Schematic>,
rootFile: string,
): SheetTreeNode {
const { root, flat } = buildSheetList(docs, rootFile);
// `SortChildren` with `OnCompareItems`. The siblings arrive in placement
// order, which is the order their virtual page numbers run in, and the sort
// is stable — so "page number, then virtual page number" is a stable sort on
// the page number alone.
const sortChildren = (n: SheetTreeNode): void => {
n.children.sort((a, b) => comparePageNum(a.page, b.page));
for (const c of n.children) sortChildren(c);
};
sortChildren(root);
if (!flat.every((e) => e.node.page === '')) return root;
let pageNumber = 0;
const numberFrom = (n: SheetTreeNode): SheetTreeNode => {
pageNumber += 1;
return { ...n, page: String(pageNumber), children: n.children.map(numberFrom) };
};
return numberFrom(root);
}
/**
* What `SCH_EDIT_FRAME::OpenProjectFiles` does to page numbers the moment the
* sheets are in memory (files-io.cpp:439-458):
*
* SCH_SHEET_LIST sheetList = Schematic().Hierarchy();
* if( sheetList.AllSheetPageNumbersEmpty() )
* sheetList.SetInitialPageNumbers();
* else
* repairedPageNumbers = sheetList.RepairPageNumbers();
*
* `RepairPageNumbers` (sch_sheet_path.cpp:1704): walking the hierarchy in
* `Hierarchy()` order, a page number is claimed by the first sheet that uses
* it; any sheet with an empty page, or one repeating a number an earlier sheet
* already claimed, is reassigned to the lowest unused positive integer. Every
* distinct stored page is reserved up front so a reassignment never takes a
* number a later, non-conflicting sheet holds. `SetInitialPageNumbers`
* (:1687) numbers the same walk 1..N.
*
* KiCad's own cm5_minima demo ships with USB and PCIe-M2 both on page "7";
* a running eeschema shows "PCIe-M2 (page 2)" because USB, placed first, keeps
* the 7 and PCIe-M2 takes the first free number. Ours showed two page 7s.
*
* Returns the documents with the numbers written into the sheet instances —
* upstream's `SetPageNumber` mutates the sheet, and the file is repaired when
* the user saves — and whether anything changed, which is what gates the
* "automatically fixed" information box (`repairedPageNumbers`).
*
* A sheet symbol with no `(instances …)` record at all cannot take a number
* here: `setSheetPageNumberCommand` only patches an existing `(path …)`, as
* the writer only re-emits one. Upstream's `addInstance` would create it.
*/
export function repairPageNumbersOnLoad(
docs: ReadonlyMap<string, Schematic>,
rootFile: string,
): { docs: Map<string, Schematic>; repaired: boolean } {
const { flat } = buildSheetList(docs, rootFile);
const hierarchy = sortByPageNumbers(flat);
const assign: { entry: SheetEntry; page: string }[] = [];
const seeded = hierarchy.every((e) => e.node.page === '');
if (seeded) {
// SetInitialPageNumbers
hierarchy.forEach((entry, i) => assign.push({ entry, page: String(i + 1) }));
} else {
// RepairPageNumbers
const reservedPageIds = new Set<string>();
for (const e of hierarchy) if (e.node.page !== '') reservedPageIds.add(e.node.page);
const assignedPageIds = new Set<string>();
let nextPage = 1;
for (const entry of hierarchy) {
const pageNumber = entry.node.page;
// Keep the first sheet to claim a given page number.
if (pageNumber !== '' && !assignedPageIds.has(pageNumber)) {
assignedPageIds.add(pageNumber);
continue;
}
let pageStr = String(nextPage);
while (reservedPageIds.has(pageStr) || assignedPageIds.has(pageStr)) {
nextPage++;
pageStr = String(nextPage);
}
assign.push({ entry, page: pageStr });
assignedPageIds.add(pageStr);
nextPage++;
}
}
// `repairedPageNumbers` is set by the repair branch alone: `SetPageNumber`
// (sch_sheet.cpp:1677) does not flag the screen modified, so the seeding
// branch raises no box upstream either.
const out = new Map(docs);
let repaired = false;
for (const { entry, page } of assign) {
const file = entry.parentFile ?? rootFile;
const doc = out.get(file);
if (!doc) continue;
const next =
entry.parentFile === undefined
? setRootPageNumberCommand(page).apply(doc)
: setSheetPageNumberCommand(entry.sheetIndex, entry.instanceKey, page).apply(doc);
if (next === doc) continue;
out.set(file, next);
repaired = true;
}
return { docs: out, repaired: repaired && !seeded };
}
/**
* Pick the project's root schematic from a set of parsed documents: the
* basename matching the .kicad_pro if given, else the document no other
* document references as a sub-sheet, else the first file.
*/
export function findRootFile(docs: ReadonlyMap<string, Schematic>, proName?: string): string {
if (proName) {
// The project's base name, with or without its extension: `findProjectPro` takes it bare.
const want = `${proName.replace(/\.kicad_pro$/i, '')}.kicad_sch`;
if (docs.has(want)) return want;
}
const referenced = new Set<string>();
for (const [file, doc] of docs) {
for (const sh of doc.sheets) referenced.add(sheetFile(sh, file));
}
for (const file of docs.keys()) {
if (!referenced.has(file)) return file;
}
return docs.keys().next().value ?? '';
}