@cornhsu/polymigrate-win32-arm64 2.1.0 → 2.2.1

package/bin/PolyMigrate.Core.xml

@@ -180,6 +180,19 @@
         <member name="P:PolyMigrate.Core.Extraction.ExtractionReport.PathIssues">
             <summary>路徑安全問題(§3.4):error = 拒寫並跳過該頁;warning = 照寫但記錄(如超長路徑)。</summary>
         </member>
+        <member name="P:PolyMigrate.Core.Extraction.ExtractionReport.StaleOutputs">
+             <summary>
+             <c>content/</c> 裡存在、但這一次沒有被寫到的 .md。
+            
+             <para>只回報,**不刪**:刪使用者的檔案風險太高,而「只寫不刪」正是 <c>raw/</c> 與
+             <c>media/</c> 這兩份不可再生資料安全的原因,不值得為了清殘檔而破壞它。
+             但不刪不等於不講——舊站下架一篇文章後重跑,舊的 .md 會永遠留著,於是回報的
+             「markdown files」與磁碟上的實際檔數從此對不起來,而原本沒有任何地方會提。</para>
+            
+             <para>刻意<b>不</b>計入 <see cref="P:PolyMigrate.Core.Extraction.ExtractionReport.HasWarnings"/>:那會讓所有有殘檔的既有使用者
+             的 <c>extract</c> 從 exit 0 變 1。exit code 是對外契約,不在 patch 版動它。</para>
+             </summary>
+        </member>
         <member name="T:PolyMigrate.Core.Extraction.ExtractionPipeline">
             <summary>
             Phase 2 管線(規格 main):巡鏡像檔 → 逐頁抽取寫 Markdown → 聚合寫四份清單與待補媒體清單。
@@ -196,6 +209,12 @@
             <param name="paths">輸入/輸出位置。</param>
             <param name="dryRun">true = 完整跑抽取與統計但不寫任何檔案(§3.8)。</param>
         </member>
+        <member name="M:PolyMigrate.Core.Extraction.ExtractionPipeline.FindStaleOutputs(System.String,System.Collections.Generic.HashSet{System.String})">
+            <summary>
+            content/ 裡有、但這次沒被寫到的 .md(見 <see cref="P:PolyMigrate.Core.Extraction.ExtractionReport.StaleOutputs"/>)。
+            純比對,不動磁碟。
+            </summary>
+        </member>
         <member name="M:PolyMigrate.Core.Extraction.ExtractionPipeline.SuggestPairs(System.Collections.Generic.SortedDictionary{System.String,PolyMigrate.Core.Inventory.InventoryRecord},System.Collections.Generic.List{System.String})">
             <summary>對「只有單語」的 key 產生啟發式配對建議(§1.4);回傳 key → 建議,兩端各一筆。</summary>
         </member>
@@ -430,6 +449,54 @@
         <member name="M:PolyMigrate.Core.Inventory.MediaHashCache.GetOrCompute(System.String,System.String)">
             <summary>檔案不存在回傳空值;快取命中免重讀,未命中計算並記入。</summary>
         </member>
+        <member name="T:PolyMigrate.Core.Inventory.MirrorSlugs">
+             <summary>
+             鏡像裡已經有的 slug(<c>raw/{lang}/{section}/</c> 的檔名去尾綴)。
+            
+             這是「增量同步」刻意只做的那一半。另一半——去舊站讀列表頁、從 HTML 挑出 slug——
+             沒有做,因為它因站而異(列表頁位置、slug 樣式各不相同,香雲寺的活動甚至沒有列表頁,
+             <c>/ch/events/index.php</c> 回 404,是從首頁卡片連出去的),而且會安靜地壞掉:
+             舊站一改版、regex 抓不到東西,排程只會每天回報「沒有新文章」。
+             那一半本來就是十幾行的一次性腳本,留給使用者;這一半只有 PolyMigrate 答得出來。
+             </summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Inventory.MirrorSlugs.InDirectory(System.String)">
+            <summary>
+            檔名 → slug:<c>20260101.php.html</c> → <c>20260101</c>。
+            只認 <c>*.html</c>——這正是 ExtractionPipeline 對「一個鏡像頁」的定義,同一把尺。
+            逐檔取名的話,鏡像目錄被 Finder / 檔案總管開過長出來的 .DS_Store 會變成空字串 slug
+            (輸出第一行就是空行),Thumbs.db 會變成一個叫「Thumbs」的假文章——
+            而這個指令的賣點就是 stdout 乾淨到可以直接導成檔案再餵給 fetch-orphans。
+            </summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Inventory.MirrorSlugs.EnsurePathSegment(System.String,System.String)">
+             <summary>
+             section / lang 是「一段目錄名」,不是路徑。<c>Path.Combine</c> 只要後段是絕對路徑
+             就會把前段整個丟掉——所以 <c>--lang C:\somewhere</c> 會安靜地去讀鏡像目錄以外的地方,
+             而且照樣回報成功。在本機 CLI 上這不是提權(使用者本來就讀得到自己的磁碟),
+             該擋的理由是**它做了你沒要求的事卻不出聲**,與「section 打錯回錯誤而非空清單」同一個原則。
+            
+             <para>判斷方式刻意不用 <see cref="M:System.IO.Path.IsPathRooted(System.String)"/>:它在 Linux 上認不出
+             <c>C:\Windows</c>(冒號與反斜線在那裡都只是普通字元),同一個輸入會因平台而有不同結果——
+             而 §3.4 的家規是「Windows 會炸的路徑在任何平台都一致地拒絕」,見 PathSafety。
+             改為直接要求「一段目錄名」:不得含 <c>/</c>、<c>\</c>、<c>:</c>,不得是 <c>..</c>。
+             空字串合法(無語言前綴的站)。</para>
+             </summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Inventory.MirrorSlugs.ForLanguage(System.String,System.String,System.String)">
+            <summary>單一語言的 slug 集(探測時用來跳過已抓過的)。</summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Inventory.MirrorSlugs.List(System.String,System.String,System.String)">
+            <summary>
+            列出 section 底下的 slug,字典序、跨語言去重。
+            <paramref name="langPrefix"/> = null 時涵蓋 raw/ 下所有語言目錄。
+            </summary>
+            <returns>
+            找不到任何對應目錄時回傳 <c>null</c>——這與「目錄在、但裡面沒有頁」必須分得開:
+            前者幾乎都是 section 名打錯,而靜靜回一份空清單會被當成「舊站沒有新文章」,
+            正是排程任務最要命的失敗方式。
+            </returns>
+        </member>
         <member name="T:PolyMigrate.Core.Markdown.FrontmatterSerializer">
             <summary>
             frontmatter 序列化(§2.6 兩坑):
@@ -706,13 +773,25 @@
         <member name="M:PolyMigrate.Core.PolyMigrator.GenerateThumbnails(System.String,System.String)">
             <summary>縮圖:media 目錄 → 縮圖目錄(同結構、EXIF 轉正、寬度上限依 config)。</summary>
         </member>
-        <member name="M:PolyMigrate.Core.PolyMigrator.Verify(System.String,System.String,System.String)">
+        <member name="M:PolyMigrate.Core.PolyMigrator.Verify(System.String,System.String,System.String,System.Collections.Generic.IReadOnlyCollection{System.String})">
             <summary>
             全站巡檢(Phase 4):只讀 Phase 2 輸出,不需 config 也不碰網路。
             </summary>
             <param name="outputDir">Phase 2 的輸出根目錄(內含 content/ 與清單)。</param>
             <param name="mediaDir">媒體目錄;null = <c>outputDir/media</c>(不存在則跳過媒體檢查)。</param>
             <param name="mediaPrefix">內文中媒體引用的根前綴。</param>
+            <param name="allowUnlinked">豁免孤島偵測的頁(content 相對路徑或路由)。</param>
+        </member>
+        <member name="M:PolyMigrate.Core.PolyMigrator.MirrorSlugs(System.String,System.String,System.String)">
+            <summary>
+            鏡像裡已有的 slug(<c>raw/{lang}/{section}/</c> 檔名),字典序、跨語言去重;
+            純本地、不碰網路、不需 config。並行期用來跟舊站的現況求差集,
+            差集再餵給 <c>fetch-orphans --slugs</c>。
+            </summary>
+            <param name="rawDir">鏡像根目錄(<c>root/raw</c>)。</param>
+            <param name="section">section 目錄名(如 news)。</param>
+            <param name="langPrefix">語言前綴;null = 涵蓋所有語言目錄。</param>
+            <returns>找不到任何對應目錄時為 null(通常是 section 名打錯)——與「有目錄但沒有頁」不同。</returns>
         </member>
         <member name="T:PolyMigrate.Core.Redirects.IRedirectExporter">
             <summary>
@@ -748,9 +827,61 @@
             missing_images.csv 已記錄的原站壞圖降為 warning(已知、非搬遷回歸)。
             </summary>
         </member>
+        <member name="M:PolyMigrate.Core.Verify.OutputVerifier.Run(System.String,System.String,System.String,System.Collections.Generic.IReadOnlyCollection{System.String})">
+            <param name="allowUnlinked">
+            豁免孤島偵測的頁(content 相對路徑或路由皆可)。刻意不從 config 讀:
+            verify 的「只讀輸出、不需 config」是它的設計前提,不為了一份清單破例。
+            </param>
+        </member>
         <member name="M:PolyMigrate.Core.Verify.OutputVerifier.BuildRoutes(System.String,System.Collections.Generic.List{System.String})">
             <summary>content 樹 → 路由集:{prefix}/{section}/{slug};index 檔代表其目錄路由。</summary>
         </member>
+        <member name="M:PolyMigrate.Core.Verify.OutputVerifier.RouteFor(System.String)">
+            <summary>content 相對路徑(如 en/blia/index.md)→ 路由(/en/blia)。</summary>
+        </member>
+        <member name="T:PolyMigrate.Core.Verify.OutputVerifier.PageRoute">
+            <summary>一頁的孤島判定所需資訊。</summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Verify.OutputVerifier.PageRoute.#ctor(System.String,System.String,System.String,System.Boolean)">
+            <summary>一頁的孤島判定所需資訊。</summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Verify.OutputVerifier.FindOrphans(System.Collections.Generic.List{PolyMigrate.Core.Verify.OutputVerifier.PageRoute},System.Collections.Generic.HashSet{System.String},System.Collections.Generic.IReadOnlyCollection{System.String})">
+             <summary>
+             孤島頁面:輸出裡有這一頁,卻沒有任何內容頁連到它——訪客除非自己打網址,否則到不了。
+             判 warning 而非 error:有些頁本來就刻意不連(活動到達頁、隱私頁)。
+            
+             界線要講清楚:這裡只看得到「內容頁之間」的連結。導覽選單不在 Phase 2 輸出裡,
+             verify 看不到它,所以能斷言的是「沒有內容頁連到它」,不是「完全沒有入口」——
+             訊息措辭必須跟得上這個界線,否則只是換一種形式的過度信任。
+             </summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Verify.OutputVerifier.IsExemptByDefault(PolyMigrate.Core.Verify.OutputVerifier.PageRoute)">
+             <summary>
+             內建豁免。沒有這一段,這個檢查會因為誤報太多而失去可信度——而一個沒人看的警告
+             比沒有警告更糟(它會稀釋整份巡檢報告)。兩類本來就不會被內容頁連到的頁:
+             <list type="bullet">
+             <item>站根與各語言首頁:深度 ≤ 1 的目錄索引,沒有人會連回去。</item>
+             <item>分類列表頁(page_type: listing):一般只從選單進入,而選單不在掃描範圍。</item>
+             </list>
+             刻意<b>不</b>豁免深度 ≥ 2 的目錄索引——香雲寺 BLIA 那類「頂層單頁」正是要抓的目標,
+             它與列表頁的差別在於所屬 section 未宣告型別,故 page_type 是 page 而非 listing。
+            
+             <para>已知限制(留帳):單語站(無語言前綴)的頂層 section 索引也落在深度 1,會一併
+             被豁免。<b>利息</b>:BLIA 那一類頁在單語站上抓不到,也就是這個檢查對單語站的效果打折。
+             要還這筆帳得先讓 verify 分得出「語言目錄」與「一般目錄」,而那需要 config——
+             會破壞 verify 不需 config 的前提,所以刻意先欠著。寧可漏報也不誤報:
+             漏的那類人工巡檢補得回來,誤報會讓人整份報告都不看。</para>
+             </summary>
+        </member>
+        <member name="M:PolyMigrate.Core.Verify.OutputVerifier.ResolveRoute(System.String,System.Collections.Generic.HashSet{System.String})">
+            <summary>
+            連結 → 路由。原樣對不上時再試一次百分號解碼版:瀏覽器與編輯器產出中日韓 href
+            預設是編碼的(<c>/ch/news/%E7%A6%AA%E4%BF%AE</c>),而鏡像檔名是解碼的(§2.6)——
+            直接比字串會把「存在、而且真的被連到」的頁判成壞連結,並連帶誤報成孤島頁面。
+            對這個 i18n-first 的工具來說,那是旗艦情境而不是邊角。
+            **只在對不上時才解碼**,原本就對得上的維持逐位元組不變(golden 不動)。
+            </summary>
+        </member>
         <member name="M:PolyMigrate.Core.Verify.OutputVerifier.NormalizeRoute(System.String)">
             <summary>連結正規化:去 #fragment/?query、去尾斜線(根除外)。</summary>
         </member>