build: move local path dependencies to remote packages for clean clone/build

[PsychQuantClaw]

Description

swift build can fail from a clean clone because Package.swift still references several local path dependencies that are not present after cloning the repo (for example under packages/... and/or similar local-only directories).

In the earlier reproduction on a fresh macdoc clone, build/setup work ran into missing local package paths and had to be patched around manually. The underlying issue is that the package graph is not fully reproducible from a clean environment.

Why this is a problem

This breaks clean install/build reproducibility:

• a fresh clone cannot reliably build without extra local package directories being prepared first
• contributors / CI / new machines may fail immediately
• the repo implicitly depends on local filesystem state that is not captured in Git

Suggestion

Please consider replacing missing local path-based dependencies with remote package references (url:) wherever possible, including the private/internal packages that are expected to come from GitHub rather than local checkout paths.

Examples of the intended direction:

• doc-converter-swift
• word-to-md-swift
• ooxml-swift
• markdown-swift
• marker-swift
• pdf-to-latex-swift
• apabib-* packages

If some packages must remain private, they should still be referenced as remote Git dependencies instead of untracked local directories.

Steps to reproduce

git clone https://github.com/PsychQuant/macdoc.git
cd macdoc
swift build -c release

Expected behavior

A clean clone should build successfully without requiring manual creation/cloning of extra local package directories.

Current Status

Phase: closed
Last updated: 2026-04-21 by idd-close (batch-close)

Key Decisions

• Closed 2026-04-21 via batch idd-close. Resolved systemically by refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78 (note-* extraction) + refactor: extract pdf-to-latex-swift + ocr-swift to PsychQuant repos; commit Tests/WordToMDTests fixtures (continues #78 pattern) #79 (extract-remaining-packages + .gitignore whitelist for 6 additional packages + pdf-to-latex-swift/ocr-swift extraction). Clean-clone swift build verified 95.80s from zero pre-state.

Scope Changes

• (none)

Blocking

• (none — CLOSED)

Commits

• d771589 release: note packages extraction + word-builder-swift wiring (release: note packages extraction + word-builder-swift wiring + #77 bump (#71 #77 #78) #82)
• d181090 refactor: extract pdf-to-latex-swift + ocr-swift + flip gitignore strategy (refactor: extract pdf-to-latex-swift + ocr-swift to PsychQuant repos; commit Tests/WordToMDTests fixtures (continues #78 pattern) #79 refactor: extract pdf-to-latex-swift + ocr-swift + flip gitignore strategy (#79) #89)
• b565ec0, 7095897, d5ee546 earlier alignment commits referencing build: move local path dependencies to remote packages for clean clone/build #12

[kiki830621]

Closing Summary

Problem

Clean-clone swift build failed on PsychQuant/macdoc because Package.swift referenced local path deps (packages/...) whose sources were not present in the repo. A fresh git clone could not reproduce the build graph.

Root Cause

Two compounding factors:

1. Several packages were path:-referenced but their sources were gitignored via a blanket packages/ exclude without explicit whitelists — so the source never landed in the repo.
2. A subset of packages (note-core-swift, note-to-pdf-swift, note-to-html-swift, pdf-to-latex-swift, ocr-swift, word-builder-swift) existed only on the original developer's filesystem with no remote origin at all.

Solution

Resolved via the #78 note-extraction change + the #79 extract-remaining-packages change combined:

• refactor: extract NoteCore / NoteToPDF as separate PsychQuant repos (packages 應該要是獨立套件) #78 extracted note-core-swift, note-to-pdf-swift, note-to-html-swift to PsychQuant/* remote repos; macdoc now consumes them as .package(url:).
• refactor: extract pdf-to-latex-swift + ocr-swift to PsychQuant repos; commit Tests/WordToMDTests fixtures (continues #78 pattern) #79 extracted pdf-to-latex-swift, ocr-swift to remote. Also performed a systemic audit (Track D) that discovered 6 more packages with missing sources (md-to-word-swift, word-to-html-swift, html-to-word-swift, pdf-to-md-swift, pdf-to-docx-swift, bib-apa-*) and committed their source files via an extended .gitignore whitelist — 48 files / 9,059 insertions.
• #71 word-builder-swift addition followed the same remote-repo pattern.

Result: every .package(url:) dep resolves from GitHub; every .package(name: ..., path:) dep has its source tracked in the repo via the whitelist. Clean clone produces a complete build graph.

Verification

Per #79 closing comment (2026-04-20):

• swift build on main: clean (4.62s incremental)
• Fresh git clone --depth 1 && swift build: 95.80s clean from zero pre-state — primary goal check passes
• swift test on clean clone: 26 Swift Testing tests pass, 2 XCTest tests XCTSkip cleanly

Changes

Commits referencing this issue:

• b565ec0 — align word-to-html with doc-converter-swift (Refs feat: implement word-to-html-swift converter #21 build: move local path dependencies to remote packages for clean clone/build #12)
• 7095897 — align html-to-word with doc-converter-swift (Refs feat: implement html-to-word-swift converter #25 build: move local path dependencies to remote packages for clean clone/build #12)
• d5ee546 — align pdf-to-md with doc-converter-swift (Refs feat: implement pdf-to-md-swift converter #23 build: move local path dependencies to remote packages for clean clone/build #12)

Indirect resolution (via subsequent Spectra changes):

• d771589 — release: note packages extraction + word-builder-swift wiring (#82 squash of #71 #77 #78)
• d181090 — refactor: extract pdf-to-latex-swift + ocr-swift + flip gitignore strategy (#79 #89)

Closing note

No unchecked - [ ] items in body (legacy issue pattern — no structured checklist; gate check passes with warning). The original suggestion to "replace all local path deps with remote" was partially fulfilled — some packages are remote, others retain path: but have their sources tracked. Both outcomes satisfy the clean-clone-build requirement, which was the actual goal.