feat: support top_level_sheets from .kicad_pro (Altium flat multi-page import) (#19)

* feat: support top_level_sheets from .kicad_pro for Altium-imported projects

When importing Altium Designer projects into KiCad, the importer registers
all schematic pages as top_level_sheets in .kicad_pro instead of creating
hierarchical (sheet ...) references. analyze_schematic.py only discovered
sub-sheets via (sheet ...) nodes, causing all non-root pages to be silently
ignored — typically losing 90%+ of components.

This change adds top_level_sheets detection after parse_all_sheets() returns.
When the root schematic has no sub-sheets but .kicad_pro lists multiple
top_level_sheets, each additional page is parsed and merged into the result.

Tested on a 25-page, 3100+ component RK3588 design imported from Altium.
Before: 206 components (one page). After: 3162 components (all 25 pages).

Closes #18

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix: refresh power_symbols after top_level_sheets merge

* fix: address Copilot review on top_level_sheets merge

- Trigger flat-merge from find_first(root_tree, "sheet") is None instead
  of `not no_hierarchy`. The redirect path calls analyze_schematic(root,
  no_hierarchy=True), which previously gated the merge off — analyzing
  any peer page of an Altium-flat project dropped to root-only content.
  The new check also avoids triggering on hierarchical projects whose
  (sheet ...) refs point to missing files.

- Store resolved abs paths in extra_sheets and sheets_parsed (matching
  parse_all_sheets convention). Dedupe by resolved path so duplicate
  top_level_sheets entries via different relative paths don't double-merge.

Validated on glitcher-flattened fixture (root .kicad_sch with zero sheet
refs + .kicad_pro top_level_sheets): both root analysis and peer-page
analysis now yield 98 components / 44 power symbols, matching the
hierarchical baseline.

Copilot's third point (extra peers with their own (sheet ...) children
not recursively merged) is real but unrelated to the Altium-flat target;
deferred as a follow-up.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: huangjianpeng <huangjianpeng@cvte.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Andrew Klofas <aklofas@gmail.com>

Author: 4 people

skills/kicad/scripts/analyze_schematic.py

@@ -8650,6 +8650,86 @@ def analyze_schematic(path: str, project_root: str | None = None,
 
     parsed = parse_all_sheets(path, root_tree=root_tree)
 
+    # --- top_level_sheets support (Altium flat multi-page imports) ---
+    # KiCad's Altium importer registers all pages as top_level_sheets in
+    # .kicad_pro instead of creating (sheet ...) hierarchy references.
+    # Trigger only when the root has zero (sheet ...) nodes — checking
+    # len(sheets_parsed) alone is fragile because parse_all_sheets silently
+    # drops (sheet ...) refs whose files are missing, which would otherwise
+    # cause us to mix in unrelated top_level_sheets. Runs regardless of
+    # no_hierarchy so the sub-sheet redirect path still picks up peers.
+    if (len(parsed.get("sheets_parsed", [])) <= 1
+            and find_first(root_tree, "sheet") is None):
+        pro = load_kicad_pro(path)
+        if pro:
+            tls = pro.get("schematic", {}).get("top_level_sheets", [])
+            if len(tls) > 1:
+                root_abs = str(Path(path).resolve())
+                extra_sheets = []
+                seen = {root_abs}
+                for entry in tls:
+                    fn = entry.get("filename", "")
+                    if not fn:
+                        continue
+                    sheet_path = os.path.join(os.path.dirname(path), fn)
+                    if not os.path.isfile(sheet_path):
+                        continue
+                    abs_path = str(Path(sheet_path).resolve())
+                    if abs_path in seen:
+                        continue
+                    seen.add(abs_path)
+                    extra_sheets.append(abs_path)
+
+                if extra_sheets:
+                    print(f"Note: discovered {len(extra_sheets)} additional "
+                          f"top-level sheets from .kicad_pro",
+                          file=sys.stderr)
+                    sym_inst = parsed.get("root_symbol_instances", {})
+                    base_idx = len(parsed["sheets_parsed"])
+                    for sheet_path in extra_sheets:
+                        try:
+                            (_, comps, wires, labels, junctions,
+                             no_connects, _, lib_syms, text_annot,
+                             bus_elems, title_blk) = \
+                                parse_single_sheet(
+                                    sheet_path,
+                                    symbol_instances=sym_inst)
+                        except Exception as exc:
+                            print(f"Warning: failed to parse "
+                                  f"{os.path.basename(sheet_path)}: {exc}",
+                                  file=sys.stderr)
+                            continue
+                        sheet_idx = base_idx
+                        base_idx += 1
+                        for c in comps:
+                            c["_sheet"] = sheet_idx
+                        for w in wires:
+                            w["_sheet"] = sheet_idx
+                        for lb in labels:
+                            lb["_sheet"] = sheet_idx
+                        for j in junctions:
+                            j["_sheet"] = sheet_idx
+                        for nc in no_connects:
+                            nc["_sheet"] = sheet_idx
+                        parsed["components"].extend(comps)
+                        parsed["wires"].extend(wires)
+                        parsed["labels"].extend(labels)
+                        parsed["junctions"].extend(junctions)
+                        parsed["no_connects"].extend(no_connects)
+                        parsed["lib_symbols"].update(lib_syms)
+                        parsed["text_annotations"].extend(text_annot)
+                        for bk, bv in bus_elems.items():
+                            if isinstance(bv, list):
+                                parsed["bus_elements"].setdefault(bk, []).extend(bv)
+                            elif isinstance(bv, dict):
+                                parsed["bus_elements"].setdefault(bk, {}).update(bv)
+                        parsed["sheets_parsed"].append(sheet_path)
+                    # Power symbols were extracted from root-sheet components
+                    # only; refresh from the merged list so peer-sheet ones are
+                    # included.
+                    parsed["power_symbols"] = extract_power_symbols(
+                        parsed["components"])
+
     all_components = parsed["components"]
     all_wires = parsed["wires"]
     all_labels = parsed["labels"]