diff --git a/.claude/.idd/attachments/issue-548/_manifest.json b/.claude/.idd/attachments/issue-548/_manifest.json new file mode 100644 index 00000000..2c5bc134 --- /dev/null +++ b/.claude/.idd/attachments/issue-548/_manifest.json @@ -0,0 +1,6 @@ +{ + "issue": 548, + "fetched_at": "2026-11-14T09:55:30Z", + "fetched_by": "idd-diagnose", + "files": [] +} diff --git a/openspec/changes/archive/2026-11-14-idd-548-links-search-completeness/.openspec.yaml b/openspec/changes/archive/2026-11-14-idd-548-links-search-completeness/.openspec.yaml new file mode 100644 index 00000000..732b3e7f --- /dev/null +++ b/openspec/changes/archive/2026-11-14-idd-548-links-search-completeness/.openspec.yaml @@ -0,0 +1,6 @@ +schema: spec-driven +created: 2026-11-14 +created_by: che cheng +created_with: claude +archived_by: che cheng +archived_at: 2026-11-14 diff --git a/openspec/changes/archive/2026-11-14-idd-548-links-search-completeness/design.md b/openspec/changes/archive/2026-11-14-idd-548-links-search-completeness/design.md new file mode 100644 index 00000000..0d550b40 --- /dev/null +++ b/openspec/changes/archive/2026-11-14-idd-548-links-search-completeness/design.md @@ -0,0 +1,116 @@ +## Context + +第二輪 verify 找到的七項裡,四項在程式(頂層目錄的讀法、巢狀 submodule、錯誤輸出、git 版本),三項在測試與文件。這份 design 只寫要決定的事;第二個 change 的六個條件、submodule 用的 git 包裝、原因的上限都不變。 + +量測(臨時 repo,git 2.55.0,協調者執行): + +- `git rev-list --objects --no-walk --missing=print ` 列出那個 commit 的 tree 與檔案內容,缺的以 `?` 開頭,結束碼 0。完整的 repo:沒有 `?`。少一個檔案內容或一個子目錄的 tree:各一行 `?`。tree 裡的 gitlink 不會被當成缺的物件。只在較舊的 commit 裡出現的物件不算。部分 clone(`--filter=blob:none`、沒有 checkout):列出缺的內容,執行前後物件庫的物件數相同,沒有抓取;沒有設 `GIT_NO_LAZY_FETCH` 時也一樣。三千個檔案的 tree 約 0.1 秒。 +- 完整而沒有標記的 submodule,`GIT_TRACE=1` 之下,現行 script 回 `error`;不設時回 `missing`。 +- 外層 submodule 少一個無關的檔案內容、標記在完整的巢狀 submodule:現行 script 回 `error`、只點名外層;外層完整時回 `ok`。 +- 頂層目錄名稱以空白結尾的 repo:`links` 回 `ok`,分支之前的 script 回 `error`(revision does not exist)。 + +## Goals / Non-Goals + +**Goals:** + +- requirement 不再有與程式不一致的總括句。 +- 「這個 submodule 讀不完」由一次明確的檢查決定,不由 git 有沒有錯誤輸出決定。 +- 一個可以搜尋的巢狀 submodule 不因為外層讀不完而被略過。 +- 在任何版本的 git 上,檢查都不向遠端抓東西。 +- 第一輪第 2 列那一類缺陷(找到的標記被別處的失敗蓋掉)在 submodule 這一層有測試擋住。 + +**Non-Goals:** + +- 主 repo 這一層的三個既有缺口(#556)。 +- 讓 skill 自己取出 submodule(#554)。 + +## Decisions + +### 改的是 requirement 的句子,不是把程式改回去 + +維護者的決定。兩處「exactly as before」改成可以檢查的話:主 repo 找到標記時不列 gitlink、不檢查 submodule;head 沒有記錄 submodule 的 repo 只搜尋自己追蹤的檔案,submodule 的規則不改變它的答案。兩個邊界上的行為各有一句與一列 Example:頂層目錄照 git 印出的讀(新 requirement);規格目錄底下不是合法 UTF-8 的路徑回 `error`,原因是固定文字 `a path under the spec directory is not valid UTF-8`,不帶例外的原文。 + +### 頂層目錄的讀法放在 repo_top() + +`repo_top()` 改成以 `os.fsdecode` 解碼、只去掉結尾的一個換行;`cmd_links()` 改回呼叫它,刪掉自己那一份。`archived` 與 `preflight` 本來就呼叫 `repo_top()`,所以三個子命令的讀法相同。這是一條新的 requirement,因為它管的不只是 `links`。 + +### 以 rev-list 的 --missing=print 決定讀不讀得完 + +進入一個 submodule(六個條件都成立)之後,先跑一次 `git rev-list --objects --no-walk --missing=print `:結束碼不是 0,或有任何一行以 `?` 開頭,這個 submodule 就是「缺物件」。結果與 gitlink 清單一樣,每個(目錄, commit)在一次執行內只算一次。 + +接著照常搜尋。找到算數的檔案就回傳(找到的標記確定這個 Example,不論這個 submodule 缺不缺物件)。沒找到時,下列任一成立就記為搜尋不了,原因是 `its recorded commit could not be read`:缺物件;`git grep` 的結束碼不是 0 或 1;tree 列不出來。submodule 的 `git grep` 的錯誤輸出不再讀。主 repo 不變:搜尋以 0、1 以外的結束碼結束時回 `error`,原因是 `git grep failed: ` 加上 git 錯誤輸出的前 200 個字元,和這條分支之前一樣(所以設了 `GIT_TRACE=1` 時,主 repo 這種錯誤的原因文字會跟著變;requirement 的句子只說 submodule 算不算搜尋過、它的原因不受錯誤輸出影響)。 + +替代做法是只認錯誤輸出裡以 `error:`、`fatal:` 開頭的行。不採用:git 的訊息前綴會隨語系翻譯,而且「有一行 error」仍然不等於「有物件讀不到」。 + +### 搜尋失敗之後仍然列 gitlink + +記下「搜尋不了」之後不跳走,繼續對同一個 commit 跑 `ls-tree`,把它的 gitlink 放進待走訪清單。`ls-tree` 失敗時,這個 submodule 記為搜尋不了(已經記過就不重複),它裡面的 submodule 無從得知,走訪在這裡停。同一個 submodule 在原因裡只出現一次。 + +### git 比 2.45 舊時不在 submodule 目錄跑 git + +`GIT_NO_LAZY_FETCH` 是 git 2.45 的功能;較舊的 git 會忽略它,部分 clone 的 submodule 會在搜尋時向遠端抓物件。第一次要在某個 submodule 目錄跑 git 之前(它的前四個條件已經成立),先跑一次 `git version` 並取出主版號與次版號,結果在一次執行內只算一次。比 2.45 舊、或讀不出版號時,這個 submodule 記為搜尋不了,原因是 `git is older than 2.45`,不在它的目錄跑任何 git 指令(Example 第 47 列兩種都測)。前四個條件不成立的 submodule 仍然回報它自己的原因。 + +替代做法是只在文件寫最低版本。不採用:那樣 Example 第 32、33 列的「沒有抓取」在舊 git 上就是假的。只對部分 clone 設限也考慮過;不採用,因為要先在那個目錄讀設定才知道它是不是部分 clone,規則也變成兩層。 + +主 repo 找到標記的 Example 不受影響:那時根本不檢查 submodule,也不讀版號。 + +### 把性質改壞的變異也要有檢查擋住 + +第二個 change 的變異表只拿掉防護。這次的驗收加上把性質改壞的變異,每一種都要有檢查失敗: + +- 找到檔案但有 submodule 搜尋不了時不算找到(第 44 列)。 +- 缺物件的 submodule 裡找到的檔案不算(第 45 列)。 +- 搜尋失敗的 submodule 不列 gitlink(第 42 列)。 +- 錯誤輸出又被算成讀不到(第 46 列)。 +- 拿掉版本檢查(第 47 列)。 +- `repo_top()` 改回 `.strip()`(Example「top directory names」)。 +- 拿掉缺物件的檢查(第 20、36 列)。 +- submodule 的搜尋以 0、1 以外的結束碼結束時不算失敗(第 49 列:物件在、但已損壞,缺物件的檢查看不出來,量測 `rev-list` 回 0、沒有 `?`,`git grep` 回 128)。 +- 讀不出的版號當成夠新(第 47 列)。 +- 主 repo 的搜尋失敗時原因不帶 git 的訊息(「what the link check reports」新增的第二列)。 +- 主 repo 的搜尋失敗時原因不截到 200 個字元(同一列)。 + +兩種變異沒有任何輸入能分辨,記為明文例外,不算缺口:留著 `GIT_INDEX_FILE`(這裡只讀 commit、不讀 index);submodule 的 tree 列不出來時不另外記原因(列 tree 要讀的物件,缺物件的檢查與搜尋都已經讀過,所以這時它一定已經被記為搜尋不了;程式裡那一句留著當防護)。主 repo 也一樣:列 gitlink 失敗時共用的 git 包裝會以 `error` 停下,但搜尋成功就表示每個 tree 都讀得到,所以這條路到不了,requirement 不另外寫它。 + +## Implementation Contract + +呼叫端看到的行為(第二個 change 的契約沒有提到的部分不變): + +- 頂層目錄名稱以空白結尾的 repo:`links`、`archived`、`preflight` 的輸出與結束碼,和同一個 repo 放在沒有結尾空白的路徑時相同。 +- 規格目錄底下有不是合法 UTF-8 的路徑:`links` 印 `{"status": "error", "missing": [], "reason": "a path under the spec directory is not valid UTF-8"}`,結束碼 2。 +- 標記只在完整的巢狀 submodule、外層缺一個無關的檔案內容:`ok`。同樣的兩層而標記哪裡都沒有:`error`,只點名外層,原因是 `its recorded commit could not be read`。 +- 標記在 submodule 的算數檔案、同一個 commit 另一個檔案內容不在:`ok`。 +- 兩個 submodule,路徑順序在前的那個沒取出,標記在後面那個:`ok`。 +- 完整而沒有標記的 submodule,`GIT_TRACE=1`:`missing`。 +- git 回報的版本比 2.45 舊:標記只在 submodule → `error`,原因是 `submodule : git is older than 2.45`,沒有任何 git 指令在 submodule 目錄執行;標記在主 repo → `ok`。 + +原因的固定文字(封閉列舉,只有這六種):`path leaves the repository`、`not checked out`、`git is older than 2.45`、`git refused to open it`、`recorded commit <前 12 碼> is not in its object store`、`its recorded commit could not be read`。 + +介面:三個子命令的參數與輸出欄位都不變。 + +驗收條件: + +- Example「markers in submodules」第 42 到 49 列、「what the link check reports」新增的兩列、「top directory names」的三列,在 `tests/spec-change/test.sh` 各有一個檢查;測試檔的標記清單加上 `spec-example: spec-on-every-issue / top directory names`。 +- 第 47 列以一個會記錄、而且把 `git version` 的答案換成舊版號的 git 包裝執行,確認紀錄裡沒有任何在 submodule 目錄的呼叫。 +- 改 `spec-change.py` 之前:第 42、43、46、47 列、「top directory names」的 `archived` 與 `preflight` 兩列、非 UTF-8 那一列的原因,各至少一項失敗;第 44、45、48 列與「top directory names」的 `links` 那一列通過。 +- 改完後 `bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 全部通過,既有檢查數不減、沒有既有檢查被改寬;`python3 -m py_compile` 通過。 +- 上一節列的十一種變異,各自至少一項檢查失敗(協調者在實作者寫不到的目錄執行)。 +- 沒有 gitlink 的 repo,以及有 gitlink 而標記都在主 repo 的 repo,新 script 與 `6ed8dec` 的 script 輸出與結束碼逐位元組相同(一般的路徑與檔名)。 +- `bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 與 `bash .claude/scripts/tests/spectra-archive-post-ic/test.sh` 結束碼為 0。 + +範圍內:`spec-change.py` 的 `repo_top()`、`marker_files()`、`cmd_links()`、submodule 用的 git 包裝、檔頭說明;`tests/spec-change/test.sh`;`references/spec-wrapper.md`;`CHANGELOG.md` 的 #548 條目。範圍外:其他 subcommand 的邏輯(`archived` 與 `preflight` 只因為 `repo_top()` 而改變)、主 repo 這一層的搜尋(#556)、skill 的文字、版號。 + +## Risks / Trade-offs + +- [git 比 2.45 舊的使用者不能把標記放在 submodule 裡] → 這個功能是這條分支才加的,沒有既有的使用者受影響;原因文字寫明版本,升級 git 就能用。主 repo 裡的標記不受影響。 +- [每個 submodule 多跑一次 `rev-list`] → 一次執行內每個(目錄, commit)只跑一次;量測三千個檔案約 0.1 秒。 +- [缺物件的 submodule 仍然搜尋,`git grep` 可能在中途以 128 結束] → 結束之前印出的符合行是那個 commit 的真實內容,找到算數的檔案就算;沒找到時這個 submodule 記為搜尋不了。關掉 lazy fetch 之後不會抓取。 +- [`repo_top()` 的改動影響 `archived` 與 `preflight`] → 只有頂層目錄名稱以空白字元結尾時答案才不同,而且是從錯的變成對的;新 requirement 寫明,Example 三列各測一個子命令。 + +## Migration Plan + +沒有資料要搬。這條分支還沒有合併。 + +## Open Questions + +(none) diff --git a/openspec/changes/archive/2026-11-14-idd-548-links-search-completeness/proposal.md b/openspec/changes/archive/2026-11-14-idd-548-links-search-completeness/proposal.md new file mode 100644 index 00000000..35f4b2f3 --- /dev/null +++ b/openspec/changes/archive/2026-11-14-idd-548-links-search-completeness/proposal.md @@ -0,0 +1,67 @@ +**GitHub-side tracker**: #548 + +## Problem + +`idd-548-links-submodule-hardening` 修好了第一輪 verify 的十二列。第二輪 verify(issue 留言 6878222878)確認了這一點,另外找到七項,其中三項由協調者重現: + +1. requirement 寫了兩次主 repo 這一層「checked exactly as before」,但有兩種罕見的輸入結果變了,而且都是從錯的變成對的:頂層目錄名稱以空白結尾的 repo(先前回不實的 `error`,現在回正確的答案);規格目錄底下有路徑不是合法 UTF-8 的 capability(先前以 traceback 結束,現在回 `error`,原因是例外的原文)。`archived` 與 `preflight` 仍用舊的讀法,三個子命令對同一個 repo 的判斷不一致。 +2. submodule 的搜尋失敗時,它底下的 submodule 不再被搜尋:標記在一個取出而且完整的巢狀 submodule 裡時回 `error`。 +3. 「找到的標記不被別處的失敗蓋掉」在 submodule 這一層沒有測試擋住:兩個把這個性質改壞的變異,測試全部通過。 +4. submodule 的搜尋只要有任何錯誤輸出、又沒找到算數的檔案,就算「讀不到」:`GIT_TRACE=1`、名稱有歧義的警告、已淘汰設定的提示,都會把 `missing` 變成 `error`,而原因說的是程式沒有檢查過的事。 +5. `links` 依賴 `GIT_NO_LAZY_FETCH`(git 2.45 起)而沒有檢查版本:較舊的 git 上,「不向遠端抓任何東西」不成立。 +6. Example 第 11、12 列的 fixture 設定 `submodule.recurse` 的那一步沒有失敗檢查,也沒有確認設定生效。 +7. `references/spec-wrapper.md` 叫人先取出 submodule,沒有提醒這個指令會向那條分支的 `.gitmodules` 指定的位址抓東西。 + +維護者 2026-11-14 的決定(issue 留言 6878497822):這七項修完再審一輪;第 1 項改規格那句話、保留現在的行為,並讓三個子命令用同一種讀法;submodule 搜尋不了時,維持「標記到處都找不到才回 `error`」。 + +## Root Cause + +- 第 1 項:requirement 用一句總括的話(exactly as before)描述主 repo 這一層,而程式在兩個邊界上其實變了;驗收時比對用的 repo 沒有這類名稱,所以量不出來。`links` 另抄了一份讀頂層目錄的程式,沒有改共用的 `repo_top()`。 +- 第 2 項:`marker_files()` 在記下「搜尋不了」之後立刻跳到下一個 submodule,還沒列出它的 gitlink。 +- 第 4 項:用「git 有沒有錯誤輸出」代替「有沒有物件讀不到」。前者不等於後者。 +- 第 3、5、6、7 項:缺測試、缺版本檢查、缺一個失敗檢查、缺一句提醒。 + +## Proposed Solution + +- 改 requirement 的兩句話:主 repo 找到標記時,不列任何 gitlink、不檢查任何 submodule;head 沒有記錄 submodule 的 repo 只搜尋自己追蹤的檔案,submodule 的規則不改變它的答案。規格目錄底下不是合法 UTF-8 的路徑寫成 `error` 的一種,原因用固定文字。 +- 新增一條 requirement:`links`、`archived`、`preflight` 以同一種方式讀頂層目錄,照 git 印出的內容、只去掉結尾的換行。`links` 改回呼叫 `repo_top()`,改的是 `repo_top()` 本身。 +- 搜尋失敗的 submodule 仍然列出它的 gitlink 並往下走;只有它的 tree 列不出來時,裡面的 submodule 才無從得知。 +- 不再看 git 的錯誤輸出。搜尋 submodule 之前,先用 `git rev-list --objects --no-walk --missing=print ` 問 git 記錄的 commit 缺哪些物件(量測:不抓取,部分 clone 也不抓;三千個檔案約 0.1 秒)。缺物件的 submodule 照樣搜尋,找到算數的檔案就確定;沒找到時才算搜尋不了。 +- git 比 2.45 舊時,不在任何 submodule 目錄跑 git,那些 submodule 算搜尋不了,原因寫明 git 的版本。 +- 測試:Example「markers in submodules」加第 42 到 49 列;「what the link check reports」加兩列;新 requirement 的 Example「top directory names」三列;第 11、12 列的 fixture 補檢查;第 22 列的 git 呼叫紀錄另外確認沒有列 gitlink 的呼叫(`ls-tree -r -z `)。 +- 文件:`spec-change.py` 檔頭、`references/spec-wrapper.md`(最低的 git 版本;取出 submodule 會連到 `.gitmodules` 指定的位址)、CHANGELOG 的 #548 條目。 + +## Non-Goals + +- 主 repo 這一層的三個既有缺口(顏色設定、檔名含換行、讀不到的檔案內容回 `missing`):#556。 +- `idd-verify` 與 worktree 的說明:#554。 +- 改變「何時回 `error`」的讀法:維護者已確認維持現在的讀法。 +- ASSUMPTION: 不升版號;CHANGELOG 改寫這條分支自己加的 #548 那一條。 +- ASSUMPTION: 封存的兩個 change 的文字(例如 design 寫的「逐位元組相同」)是當時的紀錄,不改。 + +## Success Criteria + +- 第二輪的三個重現在改動後:頂層目錄名稱以空白結尾的 repo,`links`、`archived`、`preflight` 的答案與同一個 repo 放在沒有結尾空白的路徑時相同;標記在完整的巢狀 submodule、外層少一個無關的檔案內容 → `ok`;完整的 submodule、沒有標記、`GIT_TRACE=1` → `missing`。 +- 新的檢查在改 `spec-change.py` 之前各自失敗(第 44、45、48 列檢查的是已經做對的行為,以變異測試確認它們分辨得出來);改完後全部通過,既有檢查數只增不減。 +- 變異測試包含把性質改壞的變異,不只拿掉防護:找到的標記被別處的失敗蓋掉、缺物件的 submodule 裡找到的檔案不算、搜尋失敗的 submodule 的子項不看、錯誤輸出又被算進去、拿掉版本檢查。每一種都要有檢查失敗。 +- 沒有 gitlink 的 repo,以及有 gitlink 而標記都在主 repo 的 repo,`links` 的輸出與結束碼和這條分支之前的 script(`6ed8dec`)逐位元組相同(比對用的 repo 路徑與檔名都是一般的名稱;邊界上的差異由新的 Example 列說明)。 +- `scripts/run-all-tests.sh` 的全部 suite 與 `.claude/scripts/tests/spectra-archive-post-ic/test.sh` 通過;對這條分支的範圍跑 `links` 回 `ok`。 + +## Capabilities + +### New Capabilities + +(none) + +### Modified Capabilities + +- `spec-on-every-issue`: requirement「Added and modified requirements carry an executable check」改寫主 repo 那兩句、搜尋失敗的定義、巢狀 submodule、git 版本與原因的列舉;新增 requirement「The repository's top directory is read as git prints it」。 + +## Impact + +- Affected specs: spec-on-every-issue(MODIFIED requirement「Added and modified requirements carry an executable check」;ADDED requirement「The repository's top directory is read as git prints it」) +- Affected code: + - Modified: plugins/issue-driven-dev/scripts/spec-change.py + - Modified: plugins/issue-driven-dev/scripts/tests/spec-change/test.sh + - Modified: plugins/issue-driven-dev/references/spec-wrapper.md + - Modified: plugins/issue-driven-dev/CHANGELOG.md diff --git a/openspec/changes/archive/2026-11-14-idd-548-links-search-completeness/specs/spec-on-every-issue/spec.md b/openspec/changes/archive/2026-11-14-idd-548-links-search-completeness/specs/spec-on-every-issue/spec.md new file mode 100644 index 00000000..ba0186b9 --- /dev/null +++ b/openspec/changes/archive/2026-11-14-idd-548-links-search-completeness/specs/spec-on-every-issue/spec.md @@ -0,0 +1,128 @@ +## ADDED Requirements + +### Requirement: The repository's top directory is read as git prints it + +The subcommands of `scripts/spec-change.py` that take `--cwd` (`links`, `archived` and `preflight`) SHALL take the repository's top directory from `git rev-parse --show-toplevel` as git prints it, removing only the line end that git adds: a directory name that ends in a space is kept. The three SHALL read it in the same way, so that they agree about the same `--cwd`. + +#### Scenario: A repository whose directory name ends in a space + +- **GIVEN** a repository whose top directory name ends in a space, with a requirement added in a range and its marker in a tracked test file +- **WHEN** `spec-change.py links` runs with `--cwd` at that directory +- **THEN** it prints `status` `ok` and exits 0, as it does for a copy of the repository at a path that does not end in a space + +##### Example: top directory names + +| Subcommand | Top directory of the repository | Answer | +| --- | --- | --- | +| `links` | the name ends in a space | the same JSON line and exit code as for a copy whose name does not end in a space (`ok`) | +| `archived` | the name ends in a space | the same JSON line and exit code as for that copy (`pass`) | +| `preflight` | the name ends in a space | the same `status` and exit code as for that copy | + +## MODIFIED Requirements + +### Requirement: Added and modified requirements carry an executable check + +`scripts/spec-change.py links --base ` SHALL compare the files under `openspec/specs/` at `` and at `--head` (default `HEAD`). For every requirement that is new or whose text differs between the two, it SHALL require one of two things: at least one `##### Example:` under the requirement, where each such Example has a title that is unique within its capability and a tracked file at the head revision, outside `openspec/` and not ending in `.md`, that contains the marker `spec-example: / ` (a tracked file of a submodule counts, as the paragraph "Submodules" below describes); or a line under the requirement that starts with `No executable check:` followed by a reason. A requirement that does not differ SHALL NOT be checked. A marker counts only when nothing but whitespace, or the comment closer `-->` or `*/`, follows the Example title on its line. Lines inside a code fence are not read as `##### Example:` or `No executable check:` lines; a fence opened by three or more backticks or tildes, at any indentation (as inside a list item), closes only on a line of the same character, at least as long, with nothing but whitespace after it; lines end only at `\n`, `\r\n` or `\r`. A requirement heading indented by up to three spaces SHALL be read as a requirement, as Spectra reads it. Paths SHALL be read as git stores them, never in git's quoted form, so a capability whose directory name is not ASCII is checked like any other. Two requirements with the same name in one capability SHALL make the command print `error`. So SHALL a code fence at the head revision that never closes, since the requirements after it would go unchecked. Outside code fences, a heading that starts with `### Requirement` but does not have the form `### Requirement: ` with a non-empty name SHALL make the command print `error`, and so SHALL a head revision at which the spec directory's `specs/` holds no tracked file, and a path under the spec directory that is not valid UTF-8 (the reason says so and carries no text of an exception). The command SHALL print one JSON line with `status` (`ok`, `missing` or `error`) and a list naming each requirement or Example that lacks its check, and SHALL exit 0, 1 or 2 in that order. `--base` is required: the caller names the range, so that a run on the default branch is checked against the commit it started from. The marker ties an Example to a test by name only; whether the test exercises what the Example states is judged by the reviewers of `idd-verify`. + +Submodules. The tracked files at the head revision include the tracked files of every submodule of the repository at the commit that the head revision records for it, and in the same way the files of a submodule of a submodule. The command SHALL read that recorded commit, not the commit the submodule's working tree is on. It SHALL find the submodules itself, from the entries of the head revision's tree that record a commit; it SHALL NOT rely on git's own recursion into submodules, which passes over a submodule that is not checked out without saying so; the answer SHALL be the same whether or not the git configuration turns that recursion on (`submodule.recurse`). A file of a submodule is named by the submodule's path followed by the file's path, and the two exclusions (under the spec directory, ending in `.md`) apply to that name. A submodule whose own path is under the spec directory SHALL NOT be searched and SHALL NOT count as one that could not be searched: none of its files could count. + +Order of the search. For each Example the command SHALL search the main repository first. When the marker is found there, the Example has its check and the command SHALL NOT run git in any submodule for it, so for a repository whose markers are all in its own files no entry that records a commit is listed and no submodule is examined, whatever its head revision records. Only when the marker is not found in the main repository are the submodules searched, and a marker found in one submodule settles the Example whatever the state of the others. When the marker of an Example is found, the Example has its check, whether or not every submodule could be searched. A submodule of a submodule is searched whenever its own six conditions hold, also when the search of the submodule that holds it failed; only when the tree of the outer one's recorded commit cannot be listed are the submodules inside it unknown. + +Which submodules can be searched. A submodule SHALL be searched only when all six of these hold: (1) its path, as the tree records it, is relative and has no empty, `.` or `..` component; (2) its directory, after symbolic links are resolved, lies inside the working tree of the main repository; (3) the directory itself is not a symbolic link; (4) the directory holds an entry named `.git` of its own; (5) git, run in the directory, reports it as the top of its own working tree; (6) its object store holds the recorded commit. The command SHALL NOT run git in a directory that fails any of the first four: a directory of ordinary tracked files can be shaped like a git directory, and git would read, and act on, the configuration it holds. Nor SHALL it run git in the directory of any submodule when git is older than 2.45, the first version that honours `GIT_NO_LAZY_FETCH`, or when the version cannot be read: a submodule for which the first four hold then counts as one that could not be searched. In the directory of a submodule the command SHALL run git with `safe.bareRepository` set to `explicit`, with lazy fetching turned off (`GIT_NO_LAZY_FETCH=1`), and with the variables `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, `GIT_OBJECT_DIRECTORY`, `GIT_ALTERNATE_OBJECT_DIRECTORIES` and `GIT_COMMON_DIR` removed from the environment it inherited. Before it searches a submodule the command SHALL ask git which objects of the recorded commit (its trees and the contents of its files) the object store lacks, without fetching any. A submodule is searched even when some are lacking, and a file that counts, found in it, settles the Example. When no file that counts is found in it, the submodule counts as one that could not be searched if its object store lacks an object of the recorded commit, if the search exits with a code other than 0 or 1, or if the tree of the recorded commit cannot be listed. What git writes to its error stream SHALL NOT change whether a submodule counts as searched, nor the reason reported for it. In the main repository a search that exits with a code other than 0 or 1 is `error`, as before; its reason is `git grep failed: ` followed by the first 200 characters of what git wrote to its error stream, also as before. + +What is reported. When the marker is not found and every submodule was searched, the Example is reported as lacking its check, as before. When it is not found and at least one submodule could not be searched, the command SHALL print `error` and name the first such Example it meets, the submodules that could not be searched and the reason for each: an Example whose candidate files were not all read is not reported as lacking its check. The submodules are named by path, in the order of their paths and joined by `; `; a submodule of a submodule is named by its path under the outer one; when more than five could not be searched, the first five are named and the number of the others is stated; a path longer than 200 characters is cut to its first 200 followed by `...`. The reason is one of six: the path leaves the repository (conditions 1 and 2); the submodule is not checked out (conditions 3 and 4, or git names another directory as the top); git is older than 2.45 (stated also when its version cannot be read); git refused to open it (the git command of condition 5 fails); the recorded commit is not in its object store (condition 6); the recorded commit could not be read (its object store lacks an object of it, or the search or the listing of its tree failed). The reason given for a submodule SHALL NOT carry text from git's error stream. A path that is not valid UTF-8 is handled like any other path, and the command still prints one JSON line. A repository whose head revision records no submodule is searched in its own tracked files only: none of the rules for submodules changes its answer. + +#### Scenario: An Example without a test is reported + +- **GIVEN** a range that adds a requirement with one Example titled `status by exit code` to the capability `local-ci-gate` +- **AND** no tracked file outside `openspec/` contains `spec-example: local-ci-gate / status by exit code` +- **WHEN** `spec-change.py links` runs on that range +- **THEN** it prints `status` `missing`, names that Example, and exits 1 + +##### Example: what the link check reports + +| Requirement in the range | Examples | Marker at the head revision | `No executable check:` line | `status` | +| --- | --- | --- | --- | --- | +| added | one | in `scripts/tests/x/test.sh` | absent | `ok` | +| added | one | absent | absent | `missing` | +| added | one | only in a file under `openspec/` | absent | `missing` | +| added | one | only in a file ending in `.md` | absent | `missing` | +| added | none | not applicable | absent | `missing` | +| added | none | not applicable | present, with a reason | `ok` | +| added | none | not applicable | present, with nothing after the colon | `missing` | +| added | one, with no title | not applicable | absent | `missing` | +| added | two with the same title as an Example elsewhere in the capability | present | absent | `missing` | +| changed | two | present for one, absent for the other | absent | `missing` | +| unchanged, with no Example | none | not applicable | absent | `ok` | +| removed in the range | not applicable | not applicable | not applicable | `ok` | +| no file under `openspec/specs/` differs | not applicable | not applicable | not applicable | `ok` | +| added | one | only a marker naming a longer title that starts with this one | absent | `missing` | +| added, under the heading `### Requirement Missing colon` | not applicable | not applicable | not applicable | `error` | +| any; `openspec/specs/` holds no tracked file at the head revision | not applicable | not applicable | not applicable | `error` | +| added, its only `##### Example:` line inside a code fence | none outside fences | not applicable | absent | `missing` | +| added, its only `No executable check:` line inside a code fence | none | not applicable | only inside a fence | `missing` | +| added, after a fence of four backticks that a line of three backticks does not close | its Example inside that fence | not applicable | absent | `missing` | +| added, under the heading ` ### Requirement: Alpha` (two leading spaces) | none | not applicable | absent | `missing` | +| added, its only `No executable check:` line inside a fence indented four spaces in a list item | none | not applicable | only inside that fence | `missing` | +| added, in a capability whose directory name is not ASCII (`中文能力`) | none | not applicable | absent | `missing` | +| added, in a capability whose directory name holds a double quote (`quo"te`) | none | not applicable | absent | `missing` | +| added, in a capability whose directory name is not valid UTF-8 | not applicable | not applicable | not applicable | `error`, with a reason that says so | +| added; a tree of the head revision outside the spec directory cannot be read | one | absent | absent | `error`; the reason is `git grep failed: ` followed by the first 200 characters of what git wrote to its error stream | +| added twice with the same name in one capability | not applicable | not applicable | not applicable | `error` | +| any, after a code fence that never closes | not applicable | not applicable | not applicable | `error` | +| `--base` names a revision that does not exist | not applicable | not applicable | not applicable | `error` | +| `--base` is not given | not applicable | not applicable | not applicable | usage error, exit 64 | + +##### Example: markers in submodules + +| Where the marker of the Example is at the head revision | Submodules recorded at the head revision | `status` | +| --- | --- | --- | +| in a tracked file of a submodule, at the commit the head revision records | one, checked out | `ok` | +| in a tracked file of a submodule of a submodule | both checked out | `ok` | +| in a tracked file of a submodule whose path holds a space | one, checked out | `ok` | +| only in the recorded commit of a submodule whose working tree is on a later commit without it | one, checked out | `ok` | +| only in a later commit of a submodule, which its working tree is on, not in the recorded commit | one, checked out | `missing` | +| only in a file of a submodule that ends in `.md` | one, checked out | `missing` | +| nowhere | one, checked out | `missing` | +| nowhere in the main repository | one, not checked out | `error`, naming the Example and the submodule's path | +| in a tracked file of the main repository | one, not checked out | `ok` | +| nowhere in the main repository | one, checked out, whose object store lacks the recorded commit | `error`, naming the Example and the submodule's path | +| in a tracked file of the main repository | one, checked out, whose object store lacks the recorded commit; `submodule.recurse` is true in the repository's git configuration | `ok` | +| nowhere in the main repository | one, checked out, whose object store lacks the recorded commit; `submodule.recurse` is true in the repository's git configuration | `error`, naming the Example and the submodule's path | +| only in the recorded commits of two submodules | two, neither checked out | `error`, naming the Example and both paths, joined by `; ` | +| only in a submodule of a submodule | the outer one checked out, the inner one not | `error`, naming the Example and the inner submodule by its path under the outer one | +| only in a tracked file of a submodule that is mounted under `openspec/` | one, checked out | `missing` | +| in a tracked file of the main repository | one whose path is not valid UTF-8, not checked out | `ok` | +| nowhere | one whose path is not valid UTF-8, not checked out | `error` on one JSON line, exit 2 | +| in a tracked file of the main repository | one, checked out, holding the recorded commit but not the tree of that commit | `ok` | +| nowhere in the main repository | one, checked out, holding the recorded commit but not the tree of that commit | `error`, naming the Example and the submodule's path, with no text from git's error stream | +| nowhere | one, checked out, whose object store lacks the content of one file of the recorded commit | `error`, naming the Example and the submodule's path, with no text from git's error stream | +| nowhere | one, checked out, whose recorded commit records a second submodule; at that second path the working tree holds ordinary files shaped like a git directory (`HEAD`, `config`, `objects/`, `refs/`) and no `.git` entry, and that `config` names a command to run | `error`, naming the second path as not checked out; the command named in that `config` does not run | +| in a tracked file of the main repository | the same two, with the same files at the second path | `ok`; no git command runs in the directory of a submodule, and the command named in that `config` does not run | +| only in a repository outside the main repository, at a path with a `..` component that the head revision's tree records as a submodule | that one | `error`, naming the path as one that leaves the repository; the same answer when nothing is at that outside path | +| only in a repository outside the main repository, reached through a symbolic link in the working tree that is part of a recorded submodule path | that one | `error`, naming the path as one that leaves the repository | +| in a tracked file of a submodule whose path ends in a space | one, checked out | `ok` | +| nowhere | one, not checked out, mounted under `openspec/` | `missing` | +| only in a tracked file of a submodule | one, checked out elsewhere inside the working tree of the main repository, whose own directory is a symbolic link to that checkout | `error`, naming the Example and the submodule's path as not checked out | +| in a tracked file of a submodule | one, checked out; the variable `GIT_DIR` is set to the git directory of the main repository | `ok` | +| only in the recorded commits of seven submodules | seven, none checked out | `error`, naming the Example, the first five paths in order and the number of the other two | +| nowhere | one whose directory holds a `.git` entry that git cannot open | `error`, naming the Example and the submodule's path as one git refused to open | +| nowhere | one whose directory holds an empty `.git` directory and, beside it, ordinary files shaped like a git directory (`HEAD`, `config`, `objects/`, `refs/`) whose `config` names a command to run | `error`, naming the submodule's path as one git refused to open; the command named in that `config` does not run | +| in a tracked file of the main repository | one, checked out as a partial clone that never fetched the file contents of the recorded commit | `ok`; nothing is fetched into the submodule | +| nowhere | one, checked out as a partial clone that never fetched the file contents of the recorded commit | `error`, naming the Example and the submodule's path; nothing is fetched into the submodule | +| nowhere | one, not checked out, whose path is longer than 200 characters | `error`, naming the first 200 characters of the path followed by `...` | +| in a tracked file of one submodule | two; the one with the marker checked out, the other not | `ok` | +| only in a file ending in `.md` of a submodule | one, checked out, whose object store lacks the content of another file of the recorded commit | `error`, naming the Example and the submodule's path | +| only in a tracked file of a submodule | one whose `.git` entry git opens, with the working tree of that git directory set to the parent directory, so that git names the parent as the top | `error`, naming the Example and the submodule's path as not checked out | +| only in a submodule of a submodule | three recorded paths: `a`, checked out; its own submodule `a/inner`, not checked out; and `a-b`, not checked out | `error`, naming `a-b` before `a/inner` | +| nowhere | one, at a path with a `.` component that the head revision's tree records | `error`, naming the path as one that leaves the repository | +| in a tracked file of a submodule | one, checked out; the six variables named above are all set to the git directory, working tree, index and object store of the main repository | `ok` | +| only in the recorded commit of a submodule, which the checked-out submodule's own object store lacks | one, checked out; the variable `GIT_ALTERNATE_OBJECT_DIRECTORIES` names an object store that holds that commit | `error`, naming the Example and the submodule's path, with the recorded commit as not in its object store | +| only in a submodule of a submodule, checked out and complete | the outer one checked out, its object store lacking the content of one unrelated file of its recorded commit | `ok` | +| nowhere | the same two | `error`, naming the Example and the outer submodule's path only, with its recorded commit as one that could not be read | +| in a tracked file of one submodule | two; the other one is not checked out and comes first in the order of the paths | `ok` | +| in a tracked file that counts, of a submodule whose object store lacks the content of another file of the recorded commit | one, checked out | `ok` | +| nowhere | one, checked out, holding every object of the recorded commit; git writes to its error stream during the search (`GIT_TRACE=1`) | `missing` | +| only in a tracked file of a submodule | one, checked out; git reports a version older than 2.45, or one that cannot be read | `error`, naming the Example and the submodule's path with git as older than 2.45; no git command runs in the directory of the submodule | +| in a tracked file of the main repository | one, checked out; git reports a version older than 2.45 | `ok` | +| nowhere | one, checked out, whose object store holds a damaged copy of the content of one file of the recorded commit (present, not readable) | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read | diff --git a/openspec/changes/archive/2026-11-14-idd-548-links-search-completeness/tasks.md b/openspec/changes/archive/2026-11-14-idd-548-links-search-completeness/tasks.md new file mode 100644 index 00000000..cd1cdc02 --- /dev/null +++ b/openspec/changes/archive/2026-11-14-idd-548-links-search-completeness/tasks.md @@ -0,0 +1,34 @@ +## 1. 測試先行 + +- [x] 1.1 第二輪找到的行為各有可執行的檢查:在 `plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 為 requirement「Added and modified requirements carry an executable check」的 Example「markers in submodules」第 42 到 48 列與「what the link check reports」新增的一列各加檢查;為 requirement「The repository's top directory is read as git prints it」的 Example「top directory names」三列各加檢查,測試檔的標記清單加上 spec-example: spec-on-every-issue / top directory names。同一項裡:第 11、12 列的 fixture 設定 `submodule.recurse` 的那一步加失敗檢查並確認設定值;第 22 列的 git 呼叫紀錄另外確認沒有列出 gitlink 的呼叫(`ls-tree -r -z `;讀設定檔與列規格檔的 `ls-tree` 不算),並以一個標記不在主 repo 的 fixture 確認這種呼叫確實會被記下。fixture 用通用字樣,不含任何專案名稱或本機路徑。驗證:改 `spec-change.py` 之前執行整個檔案,第 42、43、46、47 列、「top directory names」的 `archived` 與 `preflight` 兩列、非 UTF-8 那一列的原因各至少一項失敗,第 44、45、48 列與 `links` 那一列通過,既有的檢查全部通過;實作者列出每一列的結果。 + - 驗收紀錄(協調者,在一份只換測試檔、script 維持 `7ad9152` 的複本上執行 `bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh`):724 項通過、21 項失敗。失敗的是:非 UTF-8 那一列的原因(1 項)、第 42 列(2 項)、第 46 列(5 項)、第 47 列的兩種情況(各 4 項)、「top directory names」的 `archived`(3 項)與 `preflight`(2 項)。第 44、45、48 列與 `links` 那一列通過,和預期相同。 + - 與這一項寫的預期不同的一處:第 43 列在 `7ad9152` 的 script 上也通過。外層搜尋失敗、標記哪裡都沒有時,改之前的程式同樣回 `error`、只點名外層,所以這一列固定的是答案不變;分辨得出第二輪第 2 列的是第 42 列。預期是工作單寫錯,不是實作的問題。 + +## 2. 實作與說明 + +- [x] 2.1 [after: 1.1] 依 design「頂層目錄的讀法放在 repo_top()」「以 rev-list 的 --missing=print 決定讀不讀得完」「搜尋失敗之後仍然列 gitlink」「git 比 2.45 舊時不在 submodule 目錄跑 git」「改的是 requirement 的句子,不是把程式改回去」改 `plugins/issue-driven-dev/scripts/spec-change.py` 的 `repo_top()`、`marker_files()`、`cmd_links()`。驗證:1.1 的檢查全部通過;`tests/spec-change/test.sh` 既有的檢查全部通過、檢查數不減、沒有任何既有檢查被改寬;`python3 -m py_compile plugins/issue-driven-dev/scripts/spec-change.py` 通過。 +- [x] 2.2 [after: 2.1] 說明文件:`spec-change.py` 檔頭的 `links` 段寫明搜尋 submodule 需要 git 2.45 或更新的版本;`plugins/issue-driven-dev/references/spec-wrapper.md` 在講 submodule 的地方補上最低的 git 版本,以及取出 submodule 會連到那條分支的 `.gitmodules` 指定的位址、所以只在信任它時執行;`plugins/issue-driven-dev/CHANGELOG.md` 的 #548 條目改寫成最後的行為。驗證:`git diff` 對 CHANGELOG 只動 #548 那一條;文字不含任何特定專案的名稱或本機路徑。 + +## 3. 收尾 + +- [x] 3.1 [after: 2.2] 跑整套測試:`bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 與 `bash .claude/scripts/tests/spectra-archive-post-ic/test.sh`。驗證:結束碼都是 0;實作者的沙箱寫不進某個 suite 需要的位置時,由協調者在沙箱外重跑整套並記錄。 + - 驗收紀錄(協調者,在最後的檔案上、封存之前的工作樹執行):`bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 74 個 suite、0 個失敗;`bash .claude/scripts/tests/spectra-archive-post-ic/test.sh` 141 項通過。 +- [x] 3.2 [after: 3.1] 協調者驗收(在實作者寫不到的目錄):逐行讀改動;在一份只套用新測試檔、script 維持 `7ad9152` 的複本上重跑 1.1,確認哪些列失敗;重跑 `tests/spec-change/test.sh` 與整套測試;用舊測試檔配新 script 確認既有檢查沒有少;對沒有 gitlink 的 repo 與有 gitlink 而標記都在主 repo 的 repo,比對新 script 與 `6ed8dec` 的 script 輸出逐位元組相同;重放第二輪的三個重現;執行 design「把性質改壞的變異也要有檢查擋住」列的變異與第二個 change 的二十二種,記下每一種有沒有檢查失敗。驗證:驗收紀錄寫在這一項底下,每個結果附指令。 + - 驗收紀錄。以下每一項都在最後的檔案上重跑過(4.1 的補強之後)。 + - 新測試檔配新 script:`bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` → 745 項通過、0 項失敗。配 `7ad9152` 的 script:見 1.1 底下。 + - 舊測試檔配新 script(同一個指令,測試檔取自各 commit):`7ad9152` 的 648 項、`afd0021` 的 497 項、`6ed8dec` 的 431 項都通過,既有的檢查沒有少。 + - 輸出不變的兩種 repo,`python3 plugins/issue-driven-dev/scripts/spec-change.py links --base --head --cwd ` 的輸出與結束碼,新 script 與 `6ed8dec` 的 script 逐位元組相同:沒有 gitlink 的 repo(這個 repo 自己的三段歷史 `401cd33..6ed8dec`、`2dc56ab..6ed8dec`、`fdf8d0d..4921b71`);有 gitlink 而標記都在主 repo 的臨時 repo。 + - 第二輪的三個重現,在臨時 repo 上:submodule 完整、哪裡都沒有標記,設 `GIT_TRACE=1` 與不設都回 `missing`,兩次是同一行;外層 submodule 少一個無關的檔案內容、標記在完整的巢狀 submodule 裡,回 `ok`;頂層目錄名稱以空白結尾的 repo 回 `ok`(`6ed8dec` 的 script 回 `error`)。第一輪的兩個重現仍然成立:路徑不是合法 UTF-8 的 gitlink、標記在主 repo → `ok`;形狀像 git 目錄的資料夾 → `error`、原因是 not checked out。 + - 變異測試:每一種各改 script 一處,在複本上跑 `tests/spec-change/test.sh`,共 34 種。拿掉防護的 21 種是第二個 change 的 22 種重新對位(原來的「不看 submodule 搜尋的錯誤輸出」那一種已經沒有對應的程式);把性質改壞的 13 種是 design 列的那些,加上 4.1 補的。32 種各有檢查失敗。 + - 沒有檢查失敗的兩種,是 design 記為明文例外的那兩種:留著 `GIT_INDEX_FILE`;submodule 的 tree 列不出來時不另外記原因。兩種都沒有輸入能分辨。 + - 第一次執行變異測試時(33 種)另有三種沒有檢查失敗:submodule 的搜尋以其他結束碼結束時不算失敗、讀不出的版號當成夠新、主 repo 搜尋失敗時原因不帶 git 的訊息。4.1 為它們補了檢查。 + - 逐行讀改動時改回一處:實作者把主 repo 搜尋失敗的原因縮成固定文字,協調者改回這條分支之前的寫法(那一行與 `7ad9152` 相同)。 + +## 4. 封存前的補強(驗收之後) + +- [x] 4.1 [after: 3.2] 驗收的變異測試有三種沒有檢查擋住,各補一個檢查與一列 Example:requirement「Added and modified requirements carry an executable check」的 Example「markers in submodules」第 49 列(物件在、但已損壞的 submodule)與第 47 列的第二種情況(讀不出的 git 版號),以及「what the link check reports」的一列(主 repo 的 tree 讀不到時,原因是 `git grep failed: ` 加上 git 錯誤輸出的前 200 個字元)。同一項裡把主 repo 搜尋失敗時的原因改回這條分支之前的文字(實作者依工作單的一句話把 git 的訊息拿掉了,那一句寫得不清楚),並把 requirement 裡兩句關於 git 錯誤輸出的話限定在 submodule(主 repo 的原因本來就帶 git 的訊息)。驗證:三種變異、加上「主 repo 的原因不截到 200 個字元」這一種,各自有檢查失敗;`bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 全部通過。 + - 驗收紀錄。補的三處由協調者撰寫,沒有獨立讀者看過;第三輪 verify 會讀到。 + - 量測(臨時 repo,git 2.55.0):把一個檔案內容的物件換成讀不出來的資料之後,`git rev-list --objects --no-walk --missing=print` 回 0、沒有 `?` 開頭的行,`git grep` 回 128。所以這種情況只有搜尋的結束碼看得出來,第 49 列固定它。主 repo 裡刪掉規格目錄以外的一個 tree 物件之後,列規格檔的 `git ls-tree` 仍然成功,`git grep` 回 128、訊息是 `fatal: unable to read tree (...)`。 + - 三處裡,只有「讀不出的版號」在 `7ad9152` 的 script 上會失敗(那時沒有版本檢查)。第 49 列與主 repo 那一列在 `7ad9152` 上也通過:它們固定的是原本就對的行為,擋的是變異。 + - 封存前重讀 delta 時發現兩句話寫得比行為寬,已經限定在 submodule:「git 的錯誤輸出不改變答案」與「原因不帶 git 錯誤輸出的文字」。主 repo 搜尋失敗時的原因從這條分支之前就帶 git 的訊息,實測設了 `GIT_TRACE=1` 時那個原因的文字會跟著變。主 repo 那一列因此寫成實際的行為(`git grep failed: ` 加上 git 錯誤輸出的前 200 個字元),檢查改成與 git 寫出的訊息逐字比對,另加一項確認較長的訊息截到 200 個字元。 + - 補完之後重跑的結果記在 3.1 與 3.2 底下。 diff --git a/openspec/changes/archive/2026-11-14-idd-548-links-submodule-hardening/.openspec.yaml b/openspec/changes/archive/2026-11-14-idd-548-links-submodule-hardening/.openspec.yaml new file mode 100644 index 00000000..732b3e7f --- /dev/null +++ b/openspec/changes/archive/2026-11-14-idd-548-links-submodule-hardening/.openspec.yaml @@ -0,0 +1,6 @@ +schema: spec-driven +created: 2026-11-14 +created_by: che cheng +created_with: claude +archived_by: che cheng +archived_at: 2026-11-14 diff --git a/openspec/changes/archive/2026-11-14-idd-548-links-submodule-hardening/design.md b/openspec/changes/archive/2026-11-14-idd-548-links-submodule-hardening/design.md new file mode 100644 index 00000000..d9c18a6c --- /dev/null +++ b/openspec/changes/archive/2026-11-14-idd-548-links-submodule-hardening/design.md @@ -0,0 +1,121 @@ +## Context + +`idd-548-links-submodule-markers` 讓 `links` 走進 submodule 搜尋標記。第一輪 verify 指出這一步帶來三件先前沒有的事:`links` 第一次在主 repo 頂層以外的目錄跑 git;第一次把 tree 裡的路徑接到檔案系統上;第一次在已經有答案之後還繼續做會失敗的事。`links` 由 `idd-verify` 自動執行,輸入是別人送來的 commit,所以 tree 的內容與 submodule 工作樹裡的檔案都要當成不可信的資料。 + +量測(臨時 repo,git 2.55.0,協調者重跑): + +- gitlink 路徑是 `vendor/lib\xff`、標記在主 repo:這條分支的 script 印出 traceback、沒有 JSON、結束碼 1;分支之前的 script 回 `ok`。 +- submodule 記錄的 commit 再記一個 gitlink `emb`,工作樹在較新的 commit 上、把 `emb/HEAD`、`emb/config`、`emb/objects/.keep`、`emb/refs/heads/.keep` 當一般檔案追蹤;`emb/config` 設了 `core.bare=false`、`core.worktree=.`、一個 promisor remote 與 `core.sshCommand`:`links` 回 `error`,而 `core.sshCommand` 指定的指令已經執行。 + +git 的規則裡這次用到的三條:git 不允許追蹤名為 `.git` 的路徑(大小寫不論),所以送來的 commit 無法在工作樹裡放出一個 `.git`;`safe.bareRepository=explicit` 讓 git 拒絕把沒有 `.git` 的目錄當成 repository;`GIT_NO_LAZY_FETCH=1` 讓 git 在物件不存在時直接失敗而不去抓。 + +## Goals / Non-Goals + +**Goals:** + +- `links` 不在 commit 內容可以擺佈的目錄裡跑 git,也不到主 repo 的工作樹之外跑 git。 +- 主 repo 已經找到標記的 Example,結果與這條分支之前相同,不受任何 gitlink 影響。 +- submodule 裡的任何失敗只會讓「這個 submodule 搜尋不了」,不會變成 traceback,也不會被讀成「沒有標記」。 +- 輸出永遠是一行 JSON,結束碼 0、1 或 2。 + +**Non-Goals:** + +- 改變「何時回 `error`」的讀法(見 proposal 的 Non-Goals)。 +- 主 repo 這一層 git 呼叫的環境與設定。 +- 讓 skill 自己取出 submodule。 + +## Decisions + +### 找到就停,主 repo 先搜尋 + +`marker_files()` 先搜尋主 repo。只要有一個算數的檔案就立刻回傳,不列 gitlink、不碰任何 submodule。主 repo 沒找到才列 gitlink 並逐一搜尋,任何一層找到就回傳。 + +這同時解決四件事:主 repo 已有標記時不會在任何 submodule 目錄跑 git(第一輪確認過,原本連結果是 `ok` 的時候也會執行植入的指令);找到的標記不會被之後的失敗蓋掉;標記都在主 repo 的 repository 完全不走新的程式路徑,行為與這條分支之前逐位元組相同;Example 多、submodule 多時少跑很多次 `git grep`。 + +替代做法是保留完整走訪、把每一種失敗都接住。不採用:要接的失敗種類是開放的,漏一種就是一次 regression;不走就不會失敗。 + +### 只在符合六個條件的目錄跑 git + +對走訪中的目錄底下、路徑為 `` 的 gitlink,依序檢查,第一個不成立的就決定原因: + +1. `` 是相對路徑,而且沒有空的、`.` 或 `..` 的段。不成立:`path leaves the repository`,而且完全不查檔案系統(原因文字不會透露那個位置上有什麼)。 +2. `<目錄>/` 解開 symbolic link 之後,位於主 repo 頂層目錄(同樣解開之後)之內。不成立:`path leaves the repository`。 +3. 它是目錄、本身不是 symbolic link、底下有名為 `.git` 的項目。不成立:`not checked out`。到這一步為止沒有在裡面跑過任何 git 指令。 +4. 在裡面跑 `git rev-parse --show-toplevel` 成功,而且回報的就是它自己(實體路徑相同)。指令失敗:`git refused to open it`(擁有者不同而被拒、gitfile 壞掉、不認得的 extension 都在這裡;要看原因,在那個目錄跑一次 `git status`)。指令成功但回報的是別的目錄:`not checked out`。 +5. 在裡面跑 `git cat-file -e ^{commit}` 成功。不成立:`recorded commit <前 12 碼> is not in its object store`。 + +規格把第 3 步拆成兩個條件(不是 symbolic link、有 `.git`),所以寫成六個;程式的順序如上。 + +第 3 步的 `.git` 是關鍵:commit 的內容無法在工作樹裡產生 `.git`,所以形狀像 git 目錄的一般資料夾過不了這一步。第 4、5 步再加兩層(見下一個決定),讓舊版 git 或其他形狀的資料夾也不會被當成 repository。第一輪另有一個建議是再確認 `rev-parse --git-dir` 指向該目錄的 `.git` 或 superproject 的 modules;不採用:`.git` 無法由 commit 的內容產生,是使用者自己建立的,再查它指向哪裡沒有多擋住什麼。 + +封存的 `idd-548-links-submodule-markers` 在 tasks 3.2 記了一個判斷:內容由 commit 的雜湊決定,所以不必檢查路徑。那個判斷只管「讀到的內容是不是記錄的那一版」,沒有管「git 在哪裡執行、讀誰的設定」。這次補上後者。 + +### 在 submodule 目錄跑 git 的方式 + +submodule 目錄裡的每一次 git 呼叫(上一個決定的第 4、5 步、`grep`、`ls-tree`)都經過同一個包裝:`git()` 原有的選項,加上 `-c safe.bareRepository=explicit`;環境變數設 `GIT_NO_LAZY_FETCH=1`,並拿掉 `GIT_DIR`、`GIT_WORK_TREE`、`GIT_INDEX_FILE`、`GIT_OBJECT_DIRECTORY`、`GIT_ALTERNATE_OBJECT_DIRECTORIES`、`GIT_COMMON_DIR`。 + +拿掉這六個變數的原因:它們會讓 `git -C ` 改看別的 repository,判定出來的原因就是錯的(實測:`GIT_DIR` 指向主 repo 時,取出的 submodule 被回報成缺 commit;`GIT_ALTERNATE_OBJECT_DIRECTORIES` 指向另一個物件庫時,submodule 自己沒有的 commit 會被當成有,結果由不屬於這個 submodule 的物件決定)。六個變數裡五個各有測試擋住(Example 第 28、40、41 列);`GIT_INDEX_FILE` 是唯一的例外:這裡只讀記錄的 commit,不讀 index,留著它不會改變任何輸出,所以寫不出會失敗的測試。把它一起拿掉,是因為 submodule 的指令沒有理由看主 repo 的 index。主 repo 的呼叫維持 `git()`,不加這些限制:部分 clone 的主 repo 可能需要 lazy fetch 才讀得到規格檔,那是既有行為。 + +### submodule 裡的失敗算搜尋不了 + +在 submodule 目錄:`git grep` 的結束碼不是 0 或 1,或沒有找到算數的檔案而錯誤輸出有內容(有物件讀不到),或 `git ls-tree` 失敗,原因都是 `its recorded commit could not be read`。「沒有找到算數的檔案」包含結束碼是 0 的情況:`git grep` 只要有一行符合就回 0,而符合的可以全是不算數的檔案(`.md`、標題更長的另一個 Example)。這一點由封存前的 `spectra-verify` 指出,重現後補上(Example 第 36 列)。`ls-tree` 不另立原因:`git grep` 乾淨結束時已經讀過 `ls-tree -r` 需要的每一個 tree,所以它在這之後失敗幾乎不會發生,另立一種原因就會有一條測不到的規則。原因用固定文字,不放 git 的錯誤訊息:那段訊息裡可以有本機路徑(第一輪實測),而且內容由送 commit 的人影響。 + +主 repo 這一層不變:`git grep` 的結束碼不是 0 或 1 照舊丟出 `Fail`(`git grep failed: ...`),結束碼 1 照舊是沒找到。主 repo 的 gitlink 清單現在只在主 repo 沒找到標記時才列,列不出來時丟出 `Fail`。 + +關掉 lazy fetch 之後,部分 clone 的 submodule 裡從沒抓過的物件會讓 `git grep` 以 128 結束(第一輪實測),落在這裡的第一種情況,不會被悄悄算成「搜尋過、沒有標記」。 + +沒找到加上錯誤輸出就算搜尋不了,是往保守的方向取:寧可在罕見情況回 `error`,也不把沒讀完的 submodule 說成沒有標記。 + +### 路徑照位元組處理 + +gitlink 的路徑與 `rev-parse --show-toplevel` 的輸出用 `os.fsdecode` 解碼(無法解碼的位元組保留成代理字元,檔案系統呼叫時還原)。`rev-parse` 的輸出只去掉結尾的一個換行,不用 `.strip()`:路徑結尾可以是空白。放進原因文字時,把無法解碼的位元組換成替代字元,確保 JSON 印得出來。 + +### 規格目錄底下的 gitlink 略過 + +完整名稱(外層路徑加自己的路徑)在規格目錄底下的 gitlink 不搜尋,也不記為搜尋不了。它的每一個檔案名稱都以規格目錄開頭,本來就不算;把它記為搜尋不了,會讓找不到標記的 Example 回 `error`,而實際上所有可能算數的檔案都讀過了。 + +### 原因文字有上限 + +搜尋不了的 submodule 依路徑排序,列出前五個(`submodule : `,以 `; ` 相連),超過時加上 `; and more`;超過 200 個字元的路徑只留前 200 個、後面接 `...`。原因的開頭維持 `cannot decide whether the Example ' / ' has a marker: `。 + +排序讓輸出不依賴走訪的順序。上限是因為這段文字會被 `idd-verify` 放進報告與審查者的說明,而 gitlink 的路徑與數量由送 commit 的人決定。 + +## Implementation Contract + +呼叫端看到的行為: + +- 標記在主 repo 的已追蹤檔案裡:`links` 的輸出與結束碼和這條分支之前的 script 相同,不論 `<head>` 記錄了什麼 gitlink。 +- 標記只在取出的 submodule(含巢狀)於記錄的 commit 的已追蹤檔案裡:該 Example 算有連結。 +- 標記找不到、每個 gitlink 都搜尋過(規格目錄底下的不計):`missing`,`why` 是現行文字。 +- 標記找不到、至少一個 gitlink 搜尋不了:`{"status": "error", "missing": [], "reason": "cannot decide whether the Example '<capability> / <title>' has a marker: submodule <path>: <reason>[; ...][; and <N> more]"}`,結束碼 2。 + +原因的固定文字(封閉列舉,只有這五種):`path leaves the repository`、`not checked out`、`git refused to open it`、`recorded commit <前 12 碼> is not in its object store`、`its recorded commit could not be read`。 + +介面:`links --base <rev> [--head <rev>] [--cwd <dir>]` 不變;輸出仍是一行 JSON,欄位不變。任何輸入都不會讓 script 以 traceback 結束。 + +驗收條件: + +- Example「markers in submodules」的第 16 到 41 列在 `tests/spec-change/test.sh` 各有一個檢查;第 21、22、31 列另外確認 `config` 指定的指令沒有執行;第 23 列確認外面有沒有 repository 不影響結果;第 19、20 列確認原因裡沒有 git 的錯誤訊息;第 32、33 列確認沒有東西被抓進 submodule。 +- 改 `spec-change.py` 之前,新的檢查除了第 27、35 列可能已通過,其餘每一列至少一項失敗;改完後全部通過,既有檢查數不減。 +- 沒有 gitlink 的 repo,以及有 gitlink 而標記都在主 repo 的 repo,改動前後(對照這條分支之前的 script)輸出與結束碼逐位元組相同。 +- 協調者的兩個重現在改動後:第一個回 `ok`;第二個回 `error` 而標記檔不存在。在只套用新測試檔、script 維持 `afd0021` 的複本上,第 21 列的標記檔確實被建立(證明這個測試分辨得出來)。 +- `python3 -m py_compile` 通過;`bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 與 `bash .claude/scripts/tests/spectra-archive-post-ic/test.sh` 結束碼為 0。 + +範圍內:`spec-change.py` 的 `marker_files()`、`cmd_links()`、submodule 用的 git 包裝、檔頭說明;`tests/spec-change/test.sh`;`references/spec-wrapper.md`;`CHANGELOG.md` 的 #548 條目。範圍外:其他 subcommand、主 repo 層的 `git()`、skill 的文字、版號。 + +## Risks / Trade-offs + +- [第 3 步要求 `.git`:以 `git worktree` 或其他方式掛進來、沒有 `.git` 項目的目錄會被判成沒取出] → git 的每一種取出方式(submodule、worktree、一般 clone)都會在目錄裡留下 `.git` 檔或目錄,所以實際上不會誤判;真的沒有 `.git` 的目錄不該在裡面跑 git。 +- [`GIT_NO_LAZY_FETCH` 在較舊的 git 沒有作用] → 不執行植入指令的防線不靠它:第 3 步在 Python 裡擋,`safe.bareRepository` 是第二層,這個變數是第三層。受影響的只有「不抓取」這一項:忽略這個變數的 git 仍會向部分 clone 的 submodule 自己設定的遠端抓物件,那時 Example 第 32、33 列的檢查會失敗,這是正確的訊號。測試判斷物件在不在時只列出本機有的物件(`cat-file --batch-all-objects`),不依賴這個變數。 +- [結束碼 1 加錯誤輸出就算搜尋不了,可能把只是警告的情況也算進去] → 只在標記到處都找不到時才有影響,結果是 `error` 而不是 `missing`,方向保守;原因文字會點名那個 submodule。 +- [部分 clone 的 submodule 在關掉 lazy fetch 之後讀不到物件] → 回報成搜尋不了,並點名 submodule;先把 submodule 的物件抓齊再跑檢查。 +- [原因只列前五個 submodule] → 其餘的數量有寫;全部取出之後再跑一次就會看到下一批。 + +## Migration Plan + +沒有資料要搬。這條分支還沒有合併,所以沒有已發布的行為要相容;對照的基準是分支之前的 script。 + +## Open Questions + +- submodule 搜尋不了時要不要一律回 `error`:仍然等維護者確認,這次沒有改讀法。 +- `idd-verify` 在另外的 clone 或 worktree 跑時要不要自己取出 submodule,或只在說明裡提醒:不在這次範圍。 diff --git a/openspec/changes/archive/2026-11-14-idd-548-links-submodule-hardening/proposal.md b/openspec/changes/archive/2026-11-14-idd-548-links-submodule-hardening/proposal.md new file mode 100644 index 00000000..44fa62f6 --- /dev/null +++ b/openspec/changes/archive/2026-11-14-idd-548-links-submodule-hardening/proposal.md @@ -0,0 +1,64 @@ +**GitHub-side tracker**: #548 + +## Problem + +`idd-548-links-submodule-markers` 讓 `scripts/spec-change.py links` 讀得到 submodule 裡的標記。這條分支的第一輪 verify 找到三類問題,其中兩項由協調者在臨時 repo 上重現: + +- 送出 commit 的人可以讓 `links` 執行他指定的指令。submodule 記錄的 commit 裡再記一個 gitlink,而 submodule 的工作樹在那個路徑上放一組一般的已追蹤檔案(`HEAD`、`config`、`objects/`、`refs/`),形狀像一個 git 目錄。`links` 在那個目錄跑 `git rev-parse` 與 `git cat-file -e`,git 讀了裡面的 `config`,為了找不存在的 commit 發動 lazy fetch,執行 `config` 指定的 `core.sshCommand`。改動之前,`links` 只在主 repo 的頂層跑 git。 +- 主 repo 已經找到標記的 Example,會被 submodule 裡的失敗蓋掉。找到之後仍然走完每一個 gitlink:路徑不是合法 UTF-8 的 gitlink 讓 script 以 Python 的 traceback 結束(沒有 JSON,結束碼 1,也就是 `missing` 的結束碼);記錄的 commit 在、它的 tree 讀不到時回 `error`。改動之前這兩種情況都回 `ok`。 +- devil's advocate 另外確認第一項的範圍更大:主 repo 已經找到標記、結果是 `ok` 時,那個指令照樣執行。 +- 邊界上的錯誤:gitlink 的路徑沒有檢查是否留在 repo 之內(含 `..`,或經過工作樹裡指向外面的 symbolic link),`links` 會到 repo 外面跑 git,原因文字還透露那個路徑上有沒有工作樹;路徑結尾是空白的 submodule 被判成沒取出;掛在規格目錄底下、沒取出的 submodule 讓找不到標記的 Example 變成 `error`,雖然它的檔案本來就不算;繼承到的 `GIT_DIR` 讓判定失準;`rev-parse` 的每一種失敗(含 git 因擁有者不同而拒絕開啟)都被報成沒取出;submodule 裡有檔案內容讀不到時仍被當成「搜尋過、沒有標記」;原因文字沒有長度上限。 + +## Root Cause + +`marker_files()` 把「目錄存在、`git rev-parse --show-toplevel` 回報它自己」當成「這是取出的 submodule」。git 會把形狀像 git 目錄的一般資料夾認成 repository,並讀它的設定;設定可以指定要執行的指令。走訪也沒有在找到標記時停下,所以與結果無關的 gitlink 仍然被解碼、被搜尋,其中任何一步失敗都變成整個指令的失敗。路徑以嚴格的 UTF-8 解碼,並直接接在目錄後面,沒有檢查範圍。 + +## Proposed Solution + +- 找到就停。每個 Example 先搜尋主 repo;找到標記就不看任何 submodule。主 repo 找不到才走 submodule,並在第一個找到的檔案停下。標記都在主 repo 的 repository,結果與沒有 submodule 的 repository 相同。 +- 只在符合六個條件的目錄跑 git:路徑是相對路徑、沒有空的、`.` 或 `..` 的段;解開 symbolic link 之後仍在主 repo 的工作樹之內;目錄本身不是 symbolic link;目錄底下有自己的 `.git`;git 回報它是自己工作樹的頂層;物件庫裡有記錄的 commit。前四個條件不成立時不在那裡跑任何 git 指令。 +- 在 submodule 目錄跑 git 時,一律加 `safe.bareRepository=explicit`、關掉 lazy fetch(`GIT_NO_LAZY_FETCH=1`),並拿掉繼承來的 `GIT_DIR`、`GIT_WORK_TREE`、`GIT_INDEX_FILE`、`GIT_OBJECT_DIRECTORY`、`GIT_ALTERNATE_OBJECT_DIRECTORIES`、`GIT_COMMON_DIR`。 +- submodule 開始搜尋之後才失敗(`git grep` 的結束碼不是 0 或 1、沒找到算數的檔案而錯誤輸出有內容、tree 列不出來),算「搜尋不了」,不讓整個指令失敗。主 repo 這一層不變:搜尋的結束碼不是 0 或 1 照舊是 `error`。 +- 檢查不抓任何東西:部分 clone 的 submodule 缺記錄的 commit 的物件時,算搜尋不了,不向遠端抓。 +- 路徑照 git 儲存的位元組處理;`rev-parse` 的輸出只去掉結尾的一個換行。不是合法 UTF-8 的路徑照常處理,輸出仍是一行 JSON。 +- 掛在規格目錄底下的 submodule 不搜尋,也不算搜尋不了。 +- 原因文字:搜尋不了的 submodule 依路徑排序,最多列五個,其餘只報數量;超過 200 個字元的路徑截斷;原因是五種固定文字之一,不放 git 的錯誤訊息(裡面可以有本機路徑)。git 拒絕開啟的 submodule(例如擁有者不同、gitfile 壞掉)有自己的原因,不再併入「沒取出」。 +- 修改 requirement「Added and modified requirements carry an executable check」的 Submodules 段,Example「markers in submodules」加二十六列(第 16 到 41 列);`tests/spec-change/test.sh` 每列一個檢查,並補上第 4、5 列 fixture 的失敗檢查。 +- 文件:`spec-change.py` 檔頭的 `links` 段、`references/spec-wrapper.md`(檢查前先取出 submodule;樹裡記成 submodule 但 `.gitmodules` 沒有對應項目的路徑無法取出)、CHANGELOG 裡 #548 那一條。 + +## Non-Goals + +- 改變「submodule 搜尋不了時何時回 `error`」的讀法:仍然是只有標記到處都找不到時才回 `error`,等維護者確認(issue 的 Diagnosis,Choice Default Record)。這次的「找到就停」是把這個讀法做徹底,不是換讀法。 +- 讓 IDD 的 skill 自己取出 submodule(在另外的 clone 或 worktree 跑 verify 時):`idd-verify` 與 worktree 的說明不在這次範圍,記為後續。 +- 為沒有 `.gitmodules` 項目的 gitlink 另立一種原因文字:只在 `references/spec-wrapper.md` 加一句。 +- 主 repo 這一層的 git 呼叫:環境變數與設定照舊,不加這次的限制。 +- ASSUMPTION: 不升版號;CHANGELOG 改寫這條分支自己加的 #548 那一條,不動其他條目。 +- ASSUMPTION: 封存的 `idd-548-links-submodule-markers` 的 design 與 proposal 寫的「十列」是補強之前的數字,封存檔不改。 + +## Success Criteria + +- 兩個重現在改動後的結果:路徑不是合法 UTF-8 的 gitlink、標記在主 repo → `ok`,結束碼 0;形狀像 git 目錄的資料夾 → 標記找不到時 `error`、點名那個路徑為 not checked out,標記在主 repo 時 `ok`,兩種情況 `config` 指定的指令都沒有執行(測試用一個標記檔確認)。 +- 第 16 到 35 列的檢查在改 `spec-change.py` 之前,除了第 27、35 列可能已經通過,其餘每一列都有至少一項失敗;改完後全部通過。第 36 到 41 列是封存前補的(tasks 4.1):第 36 列在補上對應的修正之前失敗,第 37 到 41 列檢查的是已經做對、先前沒有測試的行為,以變異測試確認它們分辨得出來(各拿掉對應的一處程式,該列失敗)。 +- `tests/spec-change/test.sh` 既有的檢查全部照舊通過,檢查數只增不減。 +- 沒有 gitlink 的 repo,以及有 gitlink 而標記都在主 repo 的 repo,`links` 的輸出與結束碼和這條分支之前的 script 逐位元組相同。 +- `scripts/run-all-tests.sh` 的全部 suite 與 `.claude/scripts/tests/spectra-archive-post-ic/test.sh` 通過。 +- 對這條分支的範圍跑 `links` 回 `ok`。 + +## Capabilities + +### New Capabilities + +(none) + +### Modified Capabilities + +- `spec-on-every-issue`: requirement「Added and modified requirements carry an executable check」寫明搜尋的順序、哪些 submodule 可以搜尋、在 submodule 目錄怎麼跑 git、submodule 裡的失敗怎麼算、原因文字的格式。 + +## Impact + +- Affected specs: spec-on-every-issue(MODIFIED requirement「Added and modified requirements carry an executable check」) +- Affected code: + - Modified: plugins/issue-driven-dev/scripts/spec-change.py + - Modified: plugins/issue-driven-dev/scripts/tests/spec-change/test.sh + - Modified: plugins/issue-driven-dev/references/spec-wrapper.md + - Modified: plugins/issue-driven-dev/CHANGELOG.md diff --git a/openspec/changes/archive/2026-11-14-idd-548-links-submodule-hardening/specs/spec-on-every-issue/spec.md b/openspec/changes/archive/2026-11-14-idd-548-links-submodule-hardening/specs/spec-on-every-issue/spec.md new file mode 100644 index 00000000..ce984e43 --- /dev/null +++ b/openspec/changes/archive/2026-11-14-idd-548-links-submodule-hardening/specs/spec-on-every-issue/spec.md @@ -0,0 +1,98 @@ +## MODIFIED Requirements + +### Requirement: Added and modified requirements carry an executable check + +`scripts/spec-change.py links --base <rev>` SHALL compare the files under `openspec/specs/` at `<rev>` and at `--head` (default `HEAD`). For every requirement that is new or whose text differs between the two, it SHALL require one of two things: at least one `##### Example:` under the requirement, where each such Example has a title that is unique within its capability and a tracked file at the head revision, outside `openspec/` and not ending in `.md`, that contains the marker `spec-example: <capability> / <Example title>` (a tracked file of a submodule counts, as the paragraph "Submodules" below describes); or a line under the requirement that starts with `No executable check:` followed by a reason. A requirement that does not differ SHALL NOT be checked. A marker counts only when nothing but whitespace, or the comment closer `-->` or `*/`, follows the Example title on its line. Lines inside a code fence are not read as `##### Example:` or `No executable check:` lines; a fence opened by three or more backticks or tildes, at any indentation (as inside a list item), closes only on a line of the same character, at least as long, with nothing but whitespace after it; lines end only at `\n`, `\r\n` or `\r`. A requirement heading indented by up to three spaces SHALL be read as a requirement, as Spectra reads it. Paths SHALL be read as git stores them, never in git's quoted form, so a capability whose directory name is not ASCII is checked like any other. Two requirements with the same name in one capability SHALL make the command print `error`. So SHALL a code fence at the head revision that never closes, since the requirements after it would go unchecked. Outside code fences, a heading that starts with `### Requirement` but does not have the form `### Requirement: <name>` with a non-empty name SHALL make the command print `error`, and so SHALL a head revision at which the spec directory's `specs/` holds no tracked file. The command SHALL print one JSON line with `status` (`ok`, `missing` or `error`) and a list naming each requirement or Example that lacks its check, and SHALL exit 0, 1 or 2 in that order. `--base` is required: the caller names the range, so that a run on the default branch is checked against the commit it started from. The marker ties an Example to a test by name only; whether the test exercises what the Example states is judged by the reviewers of `idd-verify`. + +Submodules. The tracked files at the head revision include the tracked files of every submodule of the repository at the commit that the head revision records for it, and in the same way the files of a submodule of a submodule. The command SHALL read that recorded commit, not the commit the submodule's working tree is on. It SHALL find the submodules itself, from the entries of the head revision's tree that record a commit; it SHALL NOT rely on git's own recursion into submodules, which passes over a submodule that is not checked out without saying so; the answer SHALL be the same whether or not the git configuration turns that recursion on (`submodule.recurse`). A file of a submodule is named by the submodule's path followed by the file's path, and the two exclusions (under the spec directory, ending in `.md`) apply to that name. A submodule whose own path is under the spec directory SHALL NOT be searched and SHALL NOT count as one that could not be searched: none of its files could count. + +Order of the search. For each Example the command SHALL search the main repository first. When the marker is found there, the Example has its check and the command SHALL NOT run git in any submodule for it, so a repository whose markers are all in its own files is checked exactly as before, whatever its head revision records. Only when the marker is not found in the main repository are the submodules searched, and a marker found in one submodule settles the Example whatever the state of the others. When the marker of an Example is found, the Example has its check, whether or not every submodule could be searched. + +Which submodules can be searched. A submodule SHALL be searched only when all six of these hold: (1) its path, as the tree records it, is relative and has no empty, `.` or `..` component; (2) its directory, after symbolic links are resolved, lies inside the working tree of the main repository; (3) the directory itself is not a symbolic link; (4) the directory holds an entry named `.git` of its own; (5) git, run in the directory, reports it as the top of its own working tree; (6) its object store holds the recorded commit. The command SHALL NOT run git in a directory that fails any of the first four: a directory of ordinary tracked files can be shaped like a git directory, and git would read, and act on, the configuration it holds. In the directory of a submodule the command SHALL run git with `safe.bareRepository` set to `explicit`, with lazy fetching turned off (`GIT_NO_LAZY_FETCH=1`), and with the variables `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, `GIT_OBJECT_DIRECTORY`, `GIT_ALTERNATE_OBJECT_DIRECTORIES` and `GIT_COMMON_DIR` removed from the environment it inherited. A submodule whose search fails after it began counts as one that could not be searched; the search fails when the search command exits with a code other than 0 or 1, when it finds no file that counts and git writes to its error stream (something could not be read), or when the tree of the recorded commit cannot be listed. In the main repository nothing changes: a search that exits with a code other than 0 or 1 is `error`, as before. + +What is reported. When the marker is not found and every submodule was searched, the Example is reported as lacking its check, as before. When it is not found and at least one submodule could not be searched, the command SHALL print `error` and name the first such Example it meets, the submodules that could not be searched and the reason for each: an Example whose candidate files were not all read is not reported as lacking its check. The submodules are named by path, in the order of their paths and joined by `; `; a submodule of a submodule is named by its path under the outer one; when more than five could not be searched, the first five are named and the number of the others is stated; a path longer than 200 characters is cut to its first 200 followed by `...`. The reason is one of five: the path leaves the repository (conditions 1 and 2); the submodule is not checked out (conditions 3 and 4, or git names another directory as the top); git refused to open it (the git command of condition 5 fails); the recorded commit is not in its object store (condition 6); the recorded commit could not be read (the search failed after it began). The reason SHALL NOT carry text from git's error stream. A path that is not valid UTF-8 is handled like any other path, and the command still prints one JSON line. A repository whose head revision records no submodule is checked exactly as before. + +#### Scenario: An Example without a test is reported + +- **GIVEN** a range that adds a requirement with one Example titled `status by exit code` to the capability `local-ci-gate` +- **AND** no tracked file outside `openspec/` contains `spec-example: local-ci-gate / status by exit code` +- **WHEN** `spec-change.py links` runs on that range +- **THEN** it prints `status` `missing`, names that Example, and exits 1 + +##### Example: what the link check reports + +| Requirement in the range | Examples | Marker at the head revision | `No executable check:` line | `status` | +| --- | --- | --- | --- | --- | +| added | one | in `scripts/tests/x/test.sh` | absent | `ok` | +| added | one | absent | absent | `missing` | +| added | one | only in a file under `openspec/` | absent | `missing` | +| added | one | only in a file ending in `.md` | absent | `missing` | +| added | none | not applicable | absent | `missing` | +| added | none | not applicable | present, with a reason | `ok` | +| added | none | not applicable | present, with nothing after the colon | `missing` | +| added | one, with no title | not applicable | absent | `missing` | +| added | two with the same title as an Example elsewhere in the capability | present | absent | `missing` | +| changed | two | present for one, absent for the other | absent | `missing` | +| unchanged, with no Example | none | not applicable | absent | `ok` | +| removed in the range | not applicable | not applicable | not applicable | `ok` | +| no file under `openspec/specs/` differs | not applicable | not applicable | not applicable | `ok` | +| added | one | only a marker naming a longer title that starts with this one | absent | `missing` | +| added, under the heading `### Requirement Missing colon` | not applicable | not applicable | not applicable | `error` | +| any; `openspec/specs/` holds no tracked file at the head revision | not applicable | not applicable | not applicable | `error` | +| added, its only `##### Example:` line inside a code fence | none outside fences | not applicable | absent | `missing` | +| added, its only `No executable check:` line inside a code fence | none | not applicable | only inside a fence | `missing` | +| added, after a fence of four backticks that a line of three backticks does not close | its Example inside that fence | not applicable | absent | `missing` | +| added, under the heading ` ### Requirement: Alpha` (two leading spaces) | none | not applicable | absent | `missing` | +| added, its only `No executable check:` line inside a fence indented four spaces in a list item | none | not applicable | only inside that fence | `missing` | +| added, in a capability whose directory name is not ASCII (`中文能力`) | none | not applicable | absent | `missing` | +| added, in a capability whose directory name holds a double quote (`quo"te`) | none | not applicable | absent | `missing` | +| added twice with the same name in one capability | not applicable | not applicable | not applicable | `error` | +| any, after a code fence that never closes | not applicable | not applicable | not applicable | `error` | +| `--base` names a revision that does not exist | not applicable | not applicable | not applicable | `error` | +| `--base` is not given | not applicable | not applicable | not applicable | usage error, exit 64 | + +##### Example: markers in submodules + +| Where the marker of the Example is at the head revision | Submodules recorded at the head revision | `status` | +| --- | --- | --- | +| in a tracked file of a submodule, at the commit the head revision records | one, checked out | `ok` | +| in a tracked file of a submodule of a submodule | both checked out | `ok` | +| in a tracked file of a submodule whose path holds a space | one, checked out | `ok` | +| only in the recorded commit of a submodule whose working tree is on a later commit without it | one, checked out | `ok` | +| only in a later commit of a submodule, which its working tree is on, not in the recorded commit | one, checked out | `missing` | +| only in a file of a submodule that ends in `.md` | one, checked out | `missing` | +| nowhere | one, checked out | `missing` | +| nowhere in the main repository | one, not checked out | `error`, naming the Example and the submodule's path | +| in a tracked file of the main repository | one, not checked out | `ok` | +| nowhere in the main repository | one, checked out, whose object store lacks the recorded commit | `error`, naming the Example and the submodule's path | +| in a tracked file of the main repository | one, checked out, whose object store lacks the recorded commit; `submodule.recurse` is true in the repository's git configuration | `ok` | +| nowhere in the main repository | one, checked out, whose object store lacks the recorded commit; `submodule.recurse` is true in the repository's git configuration | `error`, naming the Example and the submodule's path | +| only in the recorded commits of two submodules | two, neither checked out | `error`, naming the Example and both paths, joined by `; ` | +| only in a submodule of a submodule | the outer one checked out, the inner one not | `error`, naming the Example and the inner submodule by its path under the outer one | +| only in a tracked file of a submodule that is mounted under `openspec/` | one, checked out | `missing` | +| in a tracked file of the main repository | one whose path is not valid UTF-8, not checked out | `ok` | +| nowhere | one whose path is not valid UTF-8, not checked out | `error` on one JSON line, exit 2 | +| in a tracked file of the main repository | one, checked out, holding the recorded commit but not the tree of that commit | `ok` | +| nowhere in the main repository | one, checked out, holding the recorded commit but not the tree of that commit | `error`, naming the Example and the submodule's path, with no text from git's error stream | +| nowhere | one, checked out, whose object store lacks the content of one file of the recorded commit | `error`, naming the Example and the submodule's path, with no text from git's error stream | +| nowhere | one, checked out, whose recorded commit records a second submodule; at that second path the working tree holds ordinary files shaped like a git directory (`HEAD`, `config`, `objects/`, `refs/`) and no `.git` entry, and that `config` names a command to run | `error`, naming the second path as not checked out; the command named in that `config` does not run | +| in a tracked file of the main repository | the same two, with the same files at the second path | `ok`; no git command runs in the directory of a submodule, and the command named in that `config` does not run | +| only in a repository outside the main repository, at a path with a `..` component that the head revision's tree records as a submodule | that one | `error`, naming the path as one that leaves the repository; the same answer when nothing is at that outside path | +| only in a repository outside the main repository, reached through a symbolic link in the working tree that is part of a recorded submodule path | that one | `error`, naming the path as one that leaves the repository | +| in a tracked file of a submodule whose path ends in a space | one, checked out | `ok` | +| nowhere | one, not checked out, mounted under `openspec/` | `missing` | +| only in a tracked file of a submodule | one, checked out elsewhere inside the working tree of the main repository, whose own directory is a symbolic link to that checkout | `error`, naming the Example and the submodule's path as not checked out | +| in a tracked file of a submodule | one, checked out; the variable `GIT_DIR` is set to the git directory of the main repository | `ok` | +| only in the recorded commits of seven submodules | seven, none checked out | `error`, naming the Example, the first five paths in order and the number of the other two | +| nowhere | one whose directory holds a `.git` entry that git cannot open | `error`, naming the Example and the submodule's path as one git refused to open | +| nowhere | one whose directory holds an empty `.git` directory and, beside it, ordinary files shaped like a git directory (`HEAD`, `config`, `objects/`, `refs/`) whose `config` names a command to run | `error`, naming the submodule's path as one git refused to open; the command named in that `config` does not run | +| in a tracked file of the main repository | one, checked out as a partial clone that never fetched the file contents of the recorded commit | `ok`; nothing is fetched into the submodule | +| nowhere | one, checked out as a partial clone that never fetched the file contents of the recorded commit | `error`, naming the Example and the submodule's path; nothing is fetched into the submodule | +| nowhere | one, not checked out, whose path is longer than 200 characters | `error`, naming the first 200 characters of the path followed by `...` | +| in a tracked file of one submodule | two; the one with the marker checked out, the other not | `ok` | +| only in a file ending in `.md` of a submodule | one, checked out, whose object store lacks the content of another file of the recorded commit | `error`, naming the Example and the submodule's path | +| only in a tracked file of a submodule | one whose `.git` entry git opens, with the working tree of that git directory set to the parent directory, so that git names the parent as the top | `error`, naming the Example and the submodule's path as not checked out | +| only in a submodule of a submodule | three recorded paths: `a`, checked out; its own submodule `a/inner`, not checked out; and `a-b`, not checked out | `error`, naming `a-b` before `a/inner` | +| nowhere | one, at a path with a `.` component that the head revision's tree records | `error`, naming the path as one that leaves the repository | +| in a tracked file of a submodule | one, checked out; the six variables named above are all set to the git directory, working tree, index and object store of the main repository | `ok` | +| only in the recorded commit of a submodule, which the checked-out submodule's own object store lacks | one, checked out; the variable `GIT_ALTERNATE_OBJECT_DIRECTORIES` names an object store that holds that commit | `error`, naming the Example and the submodule's path, with the recorded commit as not in its object store | diff --git a/openspec/changes/archive/2026-11-14-idd-548-links-submodule-hardening/tasks.md b/openspec/changes/archive/2026-11-14-idd-548-links-submodule-hardening/tasks.md new file mode 100644 index 00000000..6209acff --- /dev/null +++ b/openspec/changes/archive/2026-11-14-idd-548-links-submodule-hardening/tasks.md @@ -0,0 +1,38 @@ +## 1. 測試先行 + +- [x] 1.1 requirement「Added and modified requirements carry an executable check」的 Example「markers in submodules」第 16 到 35 列各有一個檢查:在 `plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 的「links: markers in submodules」區塊,依表的順序為二十列各加檢查,每列斷言 `status`、結束碼與該列對原因文字的要求;第 21、22、31 列另外斷言 `config` 指定的指令沒有執行(執行的話會產生一個標記檔),第 23 列對外面有與沒有 repository 各跑一次並斷言結果相同,第 19、20 列斷言原因裡沒有 git 的錯誤訊息,第 32、33 列斷言沒有東西被抓進 submodule。同一項裡補上第 4、5 列 fixture 的失敗檢查(在 submodule 工作樹做較新 commit 的兩行加 `|| setup_failed`,並在跑 `links` 之前斷言工作樹的 commit 與主 repo 記錄的不同)。fixture 用通用字樣,不含任何專案名稱或本機路徑。驗證:改 `spec-change.py` 之前執行整個檔案,新的檢查除了第 27、35 列可能已通過之外,每一列至少一項失敗,既有的檢查全部通過;實作者列出每一列的結果。 + +## 2. 實作與說明 + +- [x] 2.1 [after: 1.1] 依 design「找到就停,主 repo 先搜尋」「只在符合六個條件的目錄跑 git」「在 submodule 目錄跑 git 的方式」「submodule 裡的失敗算搜尋不了」「路徑照位元組處理」「規格目錄底下的 gitlink 略過」「原因文字有上限」改 `plugins/issue-driven-dev/scripts/spec-change.py` 的 `marker_files()` 與 `cmd_links()`,並加一個只用在 submodule 目錄的 git 包裝。驗證:1.1 的檢查全部通過;`tests/spec-change/test.sh` 既有的檢查全部通過、檢查數不減、沒有任何既有檢查被改寬;`python3 -m py_compile plugins/issue-driven-dev/scripts/spec-change.py` 通過。 +- [x] 2.2 [after: 2.1] 說明文件:`spec-change.py` 檔頭的 `links` 段寫明 submodule 要取出並有記錄的 commit 才搜尋得了、主 repo 找到標記就不看 submodule;`plugins/issue-driven-dev/references/spec-wrapper.md` 在講 submodule 的那一句之後補上「檢查前先跑 `git submodule update --init --recursive`」與「樹裡記成 submodule、`.gitmodules` 卻沒有對應項目的路徑無法取出」;`plugins/issue-driven-dev/CHANGELOG.md` 改寫這條分支加的 #548 條目,寫出最後的行為。驗證:`git diff` 對 CHANGELOG 只動 #548 那一條;文字不含任何特定專案的名稱或本機路徑。 + +## 3. 收尾 + +- [x] 3.1 [after: 2.2] 跑整套測試:`bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 與 `bash .claude/scripts/tests/spectra-archive-post-ic/test.sh`。驗證:結束碼都是 0;實作者的沙箱寫不進某個 suite 需要的位置時,由協調者在沙箱外重跑整套並記錄。 +- [x] 3.2 [after: 3.1] 協調者驗收(在實作者寫不到的目錄):逐行讀改動;在一份只套用新測試檔、script 維持 `afd0021` 的複本上重跑 1.1,確認哪些列失敗,並確認第 21 列的標記檔在那份複本上確實被建立;重跑 `tests/spec-change/test.sh` 與整套測試;用舊測試檔配新 script 確認既有檢查沒有少;對沒有 gitlink 的 repo,以及有 gitlink 而標記都在主 repo 的 repo,比對新 script 與這條分支之前的 script(`6ed8dec`)的輸出逐位元組相同;重放協調者的兩個重現與第一輪審查者的重現(tree 讀不到、部分 clone 而遠端連不到、路徑結尾是空白、規格目錄底下沒取出的 submodule、`GIT_DIR`、缺 blob、含 `..` 的路徑、經過 symbolic link 的路徑)。驗證:驗收紀錄寫在這一項底下,每個結果附指令。 + + 驗收紀錄(2026-11-14;1.1 到 3.1 由實作者模型 Codex gpt-6-astra 依工作單完成,3.2 由協調者 Claude Fable 5.2 在實作者寫不到的目錄執行。數字以最後的測試檔為準,含 4.1 補的列): + + - 逐行讀過 `spec-change.py`、`tests/spec-change/test.sh`、`references/spec-wrapper.md`、`CHANGELOG.md` 的改動。 + - 只套用新測試檔、script 維持 `afd0021` 的複本,跑 `bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh`:587 通過、61 失敗,失敗的都在第 16 到 41 列。其中第 21、22、31 列的「植入的指令沒有執行」在這份複本上失敗(標記檔被建立了),第 32、33 列的「沒有抓取」也失敗(檔案內容被抓回)。所以這些檢查分辨得出第一輪找到的問題。實作者交回時的測試檔(第 16 到 35 列)在同一份複本上是 562 通過、50 失敗;第 27、35 列在舊 script 上已經通過,其餘每一列至少一項失敗。 + - 工作樹的複本跑同一個指令:648 通過、0 失敗。舊測試檔配新 script:`afd0021` 的測試檔 497 通過、`6ed8dec` 的測試檔 431 通過,都是 0 失敗,既有的檢查沒有少。 + - 輸出不變的兩種 repo,新 script 對照這條分支之前的 script(`6ed8dec`),輸出與結束碼逐位元組相同:沒有 gitlink 的 repo(這個 repo 自己的三段歷史 `401cd33..6ed8dec`、`2dc56ab..6ed8dec`、`fdf8d0d..4921b71`);有 gitlink 而標記都在主 repo 的臨時 repo(一個取出的 submodule、一個沒取出的 gitlink、一個路徑不是合法 UTF-8 的 gitlink,兩個 Example)。 + - 協調者的兩個重現:路徑不是合法 UTF-8 的 gitlink、標記在主 repo,新 script 回 `ok`(`afd0021` 的 script 以 traceback 結束);形狀像 git 目錄的資料夾,新 script 回 `error`、原因是 `tests/sub/emb: not checked out`、標記檔不存在(`afd0021` 的 script 建立了標記檔)。 + - 第一輪審查者的重現各自成為 Example 的一列,由測試執行,不另外重放:tree 讀不到(第 18、19 列)、部分 clone(第 32、33 列)、路徑結尾是空白(第 25 列)、規格目錄底下沒取出的 submodule(第 26 列)、`GIT_DIR`(第 28 列)、缺檔案內容(第 20 列)、含 `..` 的路徑(第 23 列)、經過 symbolic link 的路徑(第 24 列)。 + - 變異測試:在追蹤檔案的複本上各拿掉一處防護,再跑 `tests/spec-change/test.sh`,共 22 種。21 種都有檢查失敗;唯一沒有的是留著 `GIT_INDEX_FILE`(原因見 design「在 submodule 目錄跑 git 的方式」)。 + - `python3 -m py_compile plugins/issue-driven-dev/scripts/spec-change.py` 通過。 + - 整套測試在沙箱外、最後的檔案上跑:`bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 74 個 suite、0 個失敗,結束碼 0;`bash .claude/scripts/tests/spectra-archive-post-ic/test.sh` 141 通過、0 失敗。實作者在沙箱裡跑的那一次有三個 suite(correct-flow、edit-run、in-place-correction)因為寫不進暫存位置而失敗,與這次改動無關。 + +## 4. 封存前的補強(spectra-verify 之後) + +- [x] 4.1 [after: 3.2] 依 `spectra-verify` 的三項 warning 與兩項建議補強:依 design「submodule 裡的失敗算搜尋不了」,submodule 的搜尋沒找到算數的檔案而 git 有錯誤輸出時(含結束碼 0),算搜尋不了;Example「markers in submodules」加第 36 到 41 列與對應的檢查(標記只在 `.md`、另一個檔案讀不到;git 回報別的目錄是頂層;路徑順序與走訪順序不同;路徑含 `.` 的段;六個繼承的變數都指向主 repo;繼承的 `GIT_ALTERNATE_OBJECT_DIRECTORIES` 指向另一個有記錄的 commit 的物件庫);第 22 列加一個檢查,記錄每一次 git 呼叫,確認沒有任何一次在 submodule 目錄;判斷 blob 在不在的檢查改成只列本機物件。驗證:第 36 列在補上修正之前失敗、之後通過;第 37 到 41 列以變異測試確認(各拿掉對應的一處程式,該列失敗);六個繼承的變數裡,只有 `GIT_INDEX_FILE` 留著時沒有任何檢查會失敗,原因記在 design;`bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 全部通過。 + + 紀錄(2026-11-14;這一項是協調者自己寫的改動,沒有經過實作者模型。封存前的 `spectra-verify` 讀的是補強之前的檔案,而且沒有執行測試。這一項沒有獨立讀者審過,交給下一步的 verify): + + - `spectra-verify` 的第一項 warning 重現成立:submodule 裡標記只出現在 `.md` 檔、另一個檔案的內容讀不到時,`git grep` 回 0 並在錯誤輸出留下訊息,實作者的 script 把它當成搜尋過而回 `missing`(第 36 列的四項檢查失敗,其餘通過)。補上之後回 `error`。 + - 第二項(「git 回報別的目錄是頂層」的分支沒有測試):第 37 列。第三項(第 29 列分辨不出有沒有排序):第 38 列,fixture 的走訪順序與路徑順序不同。 + - 兩項建議:路徑含 `.` 的段(第 39 列);`GIT_DIR` 以外的繼承變數(第 40、41 列)。第 41 列是變異測試之後加的:留著 `GIT_ALTERNATE_OBJECT_DIRECTORIES` 時,submodule 自己沒有的 commit 會被當成有,結果變成 `ok`。 + - 另外加的檢查:第 22 列以一個會記錄的 git 包裝再跑一次,確認主 repo 有標記時沒有任何 git 指令在 submodule 目錄執行;判斷檔案內容在不在物件庫的檢查改成只列本機物件,不依賴 `GIT_NO_LAZY_FETCH`。 + - 變異測試裡對應這一項的結果:不排序 → 第 38 列失敗;接受 `.` → 第 39 列失敗;不比對 git 回報的頂層 → 第 37 列失敗;忽略 submodule 搜尋的錯誤輸出 → 第 20、36 列失敗;找到之後繼續走訪 → 第 22 列的新檢查失敗;留著 `GIT_WORK_TREE`、`GIT_OBJECT_DIRECTORY`、`GIT_COMMON_DIR` → 第 40 列失敗;留著 `GIT_ALTERNATE_OBJECT_DIRECTORIES` → 第 41 列失敗;留著 `GIT_INDEX_FILE` → 沒有檢查失敗。 + - 補強之後 `bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh`:648 通過、0 失敗。Example 表現在是四十一列。 diff --git a/openspec/changes/archive/2026-11-14-idd-548-links-submodule-markers/.openspec.yaml b/openspec/changes/archive/2026-11-14-idd-548-links-submodule-markers/.openspec.yaml new file mode 100644 index 00000000..732b3e7f --- /dev/null +++ b/openspec/changes/archive/2026-11-14-idd-548-links-submodule-markers/.openspec.yaml @@ -0,0 +1,6 @@ +schema: spec-driven +created: 2026-11-14 +created_by: che cheng <kiki830621@gmail.com> +created_with: claude +archived_by: che cheng <kiki830621@gmail.com> +archived_at: 2026-11-14 diff --git a/openspec/changes/archive/2026-11-14-idd-548-links-submodule-markers/design.md b/openspec/changes/archive/2026-11-14-idd-548-links-submodule-markers/design.md new file mode 100644 index 00000000..8ce37595 --- /dev/null +++ b/openspec/changes/archive/2026-11-14-idd-548-links-submodule-markers/design.md @@ -0,0 +1,80 @@ +## Context + +`links` 是 `idd-implement`、`idd-all` 與 `idd-verify` 的規格包裝流程呼叫的檢查,行為寫在 capability `spec-on-every-issue`。它目前只看主 repo 自己追蹤的檔案。這個 script 的既有約定是:讀不到或無法判定的一律回 `error`,不回 `ok` 或 `missing`。 + +量測(臨時 repo,git 2.55.0):`git grep --recurse-submodules <tree>` 讀 tree 記錄的 submodule commit、含巢狀,輸出路徑是 `<tree>:<submodule 路徑>/<檔案>`;submodule 沒取出時安靜略過(exit 1);記錄的 commit 不在物件庫時 exit 128;在 submodule 的目錄裡對記錄的 commit 跑不帶旗標的 `git grep` 也找得到同一個檔案。 + +## Goals / Non-Goals + +**Goals:** + +- 標記在 submodule 的已追蹤檔案裡時找得到,讀的是 `<head>` 記錄的 commit。 +- 沒看過的地方不被讀成「沒有標記」。 +- 沒有 gitlink 的 repo 行為不變。 + +**Non-Goals:** + +- 任何 gitlink 搜尋不了就一律 `error`(見 proposal 的 Non-Goals)。 +- 搜尋 deinit 之後留在 `.git/modules/` 的 git 目錄。 + +## Decisions + +### links 自己列出 gitlink 並逐一搜尋 + +對 `<head>` 跑 `git ls-tree -r -z`,取 mode 160000 的項目(路徑與 commit)。對每一個:目錄 `<repo>/<路徑>` 必須存在,而且在裡面跑 `git rev-parse --show-toplevel` 得到的就是它自己(實體路徑相同),否則記為「not checked out」;`git cat-file -e <commit>^{commit}` 失敗則記為「recorded commit <前 12 碼> is not in its object store」。兩項都過,就在那個目錄對那個 commit 跑現行的 `git grep -z -F -e <標記> <commit> -- .`,並對那個 commit 的 tree 以同樣方式處理它底下的 gitlink,路徑前面接上外層的 submodule 路徑。 + +目錄在工作樹裡是 symbolic link 時,也記為「not checked out」。 + +替代做法是加 `--recurse-submodules`。不採用:它略過沒取出與不是 active 的 submodule 時不留下任何訊息,仍然要另外列舉 gitlink 才知道哪些沒看;既然要列舉,就直接逐一搜尋,結果不依賴 git 對「active」的判定。 + +### 找不到而且有地方沒看過時回 error + +`marker_files()` 回傳找到的檔案與沒辦法搜尋的 submodule 清單。`cmd_links()` 對一個 Example:有檔案就算有連結;沒有檔案、清單是空的,照舊加入 `missing`;沒有檔案、清單不是空的,丟出 `Fail`,原因是 `cannot decide whether the Example '<capability> / <title>' has a marker: submodule <路徑>: <原因>`(多個以分號分隔),指令回 `error`、exit 2。已找到標記的 Example 不因為別的 submodule 沒取出而失敗。無法判定的 Example 不只一個時,只點名檢查順序中遇到的第一個;原因裡列出每一個搜尋不了的 submodule。 + +### git 自己的遞迴一律關掉 + +每一次 `git grep` 都帶 `--no-recurse-submodules`。使用者的 git 設定若把 `submodule.recurse` 設成 true,`git grep` 給定 tree 時會自己進 submodule:沒取出的安靜略過,記錄的 commit 讀不到時以 128 結束,主 repo 已經有標記的 Example 也會因此被回報成 `error`。這一點由封存前的 `spectra-verify` 指出,在 git 2.55.0 上實測成立後補上;Example 的第 11、12 列檢查它。 + +### 排除規則套用在接上 submodule 路徑之後的名稱 + +`.md` 結尾與規格目錄底下這兩個排除,比對的是「submodule 路徑/檔案路徑」。submodule 自己的 `openspec/` 不另外排除:它底下的規格檔是 `.md`,已經被排除。 + +### gitlink 的清單與可搜尋性在一次執行內只算一次 + +以 (repo 目錄, commit) 為鍵快取 gitlink 清單與每個 submodule 的檢查結果,Example 多時不重複跑 `ls-tree` 與 `cat-file`。每個 Example 仍然各跑一次 `git grep`。 + +### 在 submodule 目錄裡只跑唯讀的 git 指令 + +只用 `ls-tree`、`rev-parse`、`cat-file`、給定 commit 的 `grep`,都經過 script 既有的 `git()` 包裝(`core.quotePath=false`、`GIT_LITERAL_PATHSPECS=1`)。這些指令不執行 hook、不讀工作樹的內容。 + +## Implementation Contract + +呼叫端看到的行為:repo 的 `<head>` 沒有 gitlink 時,`links` 的輸出與結束碼與現在相同。有 gitlink 時,標記在已取出的 submodule(含巢狀)於記錄的 commit 的已追蹤檔案裡,該 Example 算有連結;標記找不到而每個 gitlink 都搜尋過,回報 `missing`,`why` 是現行文字;標記找不到而至少一個 gitlink 搜尋不了,指令印 `{"status": "error", "missing": [], "reason": "cannot decide whether the Example ... has a marker: submodule <path>: <reason>"}`,exit 2。 + +介面:`links --base <rev> [--head <rev>] [--cwd <dir>]` 不變;輸出仍是一行 JSON,欄位不變。 + +失敗情況:submodule 目錄不存在或不是自己工作樹的頂層(not checked out);記錄的 commit 不在物件庫;在 submodule 裡的 git 指令以 0、1 以外的結束碼結束(照現行的 `git grep failed` 處理)。 + +驗收條件: + +- Example「markers in submodules」的十列在 `tests/spec-change/test.sh` 各有一個檢查,測試檔帶標記 `spec-example: spec-on-every-issue / markers in submodules`。 +- 改 `spec-change.py` 之前,十個檢查裡六個失敗(第 1、2、3、4 列應為 `ok`,第 8、10 列應為 `error`),第 5、6、7、9 列通過。 +- 改完後 `bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 全部通過,既有檢查數不減;`python3 -m py_compile` 通過。 +- `bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 與 `bash .claude/scripts/tests/spectra-archive-post-ic/test.sh` 結束碼為 0。 + +範圍內:`spec-change.py` 的 `marker_files()`、`cmd_links()`、檔頭說明;`tests/spec-change/test.sh`;`references/spec-wrapper.md`;`CHANGELOG.md`。範圍外:其他 subcommand、其他 skill 的文字、版號。 + +## Risks / Trade-offs + +- [CI 的 checkout 預設不取出 submodule,找不到標記的 Example 會從 `missing` 變成 `error`] → 這是要的結果:沒看過不算沒有。`references/spec-wrapper.md` 寫明檢查時 submodule 要已經取出。 +- [submodule 多、Example 多時 git 指令變多] → 清單與可搜尋性快取;每個 Example 對每個 submodule 一次 `git grep`。 +- [submodule 的路徑含空白或非 ASCII 字元] → `-z` 輸出與 `core.quotePath=false`;Example 有一列是含空白的路徑。 +- [#547 的修正也改 `spec-change.py`] → 改動限在 `marker_files()`、`cmd_links()` 與檔頭的 `links` 段;先後合併時解一般的衝突。 + +## Migration Plan + +沒有資料要搬。沒有 gitlink 的 repo 不受影響;有 gitlink 的 repo 在升級後,`links` 會多看 submodule,原本回報 `missing` 的 Example 可能變成 `ok` 或 `error`。 + +## Open Questions + +- submodule 搜尋不了時要不要一律回 `error`(不論標記是否已在別處找到)。這次取「找不到才回 `error`」,等維護者確認(issue 的 Diagnosis,Choice Default Record)。 diff --git a/openspec/changes/archive/2026-11-14-idd-548-links-submodule-markers/proposal.md b/openspec/changes/archive/2026-11-14-idd-548-links-submodule-markers/proposal.md new file mode 100644 index 00000000..3f6e26d4 --- /dev/null +++ b/openspec/changes/archive/2026-11-14-idd-548-links-submodule-markers/proposal.md @@ -0,0 +1,52 @@ +**GitHub-side tracker**: #548 + +## Problem + +`scripts/spec-change.py links` 檢查每個新增或改到的 requirement 底下的 Example 有沒有帶標記的已追蹤檔案。它用 `git grep -z -F -e <標記> <head> -- .` 找檔案,而 `git grep` 在給定 tree 時不進 submodule。規格在主 repo、測試在 submodule 的 repo,每一個 Example 都回報 `missing`,不論測試檔有沒有標記;讀報告的人分不出是工具沒看到還是真的沒有。 + +## Root Cause + +`marker_files()` 只搜尋主 repo 自己追蹤的檔案。在一個三層的臨時 repo(主 repo、submodule、巢狀 submodule,git 2.55.0)上量到:不加旗標時 submodule 裡的標記找不到;加 `--recurse-submodules` 找得到,讀的是 tree 記錄的那個 submodule commit,巢狀的也讀;但 submodule 沒取出時它安靜略過,結束碼與「沒有標記」相同,git 的說明也寫它只搜尋 active 且已取出的 submodule;tree 記錄的 commit 不在 submodule 的物件庫時以 128 結束。 + +## Proposed Solution + +- `links` 自己列出 `<head>` 的 gitlink(`git ls-tree -r` 裡 mode 160000 的項目),逐一確認該目錄是自己工作樹的頂層、而且物件庫裡有記錄的 commit,然後在那個 commit 上搜尋;submodule 的 gitlink 照同樣方式往下走。不用 `git grep --recurse-submodules`。 +- 一個 Example 有三種結果:找到標記就算有連結;沒找到而且每個 gitlink 都搜尋過,照舊回報缺少連結(`why` 文字不變);沒找到而且至少一個 gitlink 沒辦法搜尋,整個指令回 `error`,原因寫出 Example、submodule 路徑與是沒取出還是缺 commit。 +- submodule 裡的檔案以「submodule 路徑/檔案路徑」套用既有的兩個排除(規格目錄底下、`.md` 結尾)。 +- 沒有 gitlink 的 repo 結果與現在相同。 +- 修改 requirement「Added and modified requirements carry an executable check」,加一段 Submodules 與 Example「markers in submodules」(十列);`tests/spec-change/test.sh` 每列一個檢查。 +- 文件:`spec-change.py` 檔頭的 `links` 說明、`references/spec-wrapper.md` 一句(標記可以在 submodule 的已追蹤檔案裡,檢查時 submodule 要已經取出)、CHANGELOG 的 Unreleased。 + +## Non-Goals + +- 只要有任何 gitlink 搜尋不了就一律回 `error`(不論標記是否已在別處找到):比較嚴格的另一種讀法。這次取的是上面第二點的讀法,記在 issue 的 Diagnosis(Choice Default Record),等維護者確認;要改只需放寬一個條件。 +- 搜尋已經 deinit、只剩 `.git/modules/` 的 submodule:視為沒取出。 +- `idd-ci-gate` 在本身是 submodule checkout 的 repo 回 error(#535):另一個問題。 +- `idd-implement` 與 `idd-all` 的文字:它們只說測試檔帶標記,沒有規定檔案在哪裡,不改。 +- ASSUMPTION: 不升版號,CHANGELOG 加在既有的 Unreleased 區塊。 + +## Success Criteria + +- 新的十個檢查在改 `spec-change.py` 之前有六個失敗(四個標記在 submodule 裡而應為 `ok` 的列、兩個應為 `error` 的列),其餘四個通過;改完後十個都通過。 +- `tests/spec-change/test.sh` 既有的檢查全部照舊通過,檢查數只增不減。 +- `scripts/run-all-tests.sh` 的全部 suite 與 `.claude/scripts/tests/spectra-archive-post-ic/test.sh` 通過。 +- 對這個 change 的範圍跑 `links` 回 `ok`。 + +## Capabilities + +### New Capabilities + +(none) + +### Modified Capabilities + +- `spec-on-every-issue`: requirement「Added and modified requirements carry an executable check」寫明標記可以在 submodule 的已追蹤檔案裡、讀哪個 commit、submodule 搜尋不了時的結果。 + +## Impact + +- Affected specs: spec-on-every-issue(MODIFIED requirement「Added and modified requirements carry an executable check」) +- Affected code: + - Modified: plugins/issue-driven-dev/scripts/spec-change.py + - Modified: plugins/issue-driven-dev/scripts/tests/spec-change/test.sh + - Modified: plugins/issue-driven-dev/references/spec-wrapper.md + - Modified: plugins/issue-driven-dev/CHANGELOG.md diff --git a/openspec/changes/archive/2026-11-14-idd-548-links-submodule-markers/specs/spec-on-every-issue/spec.md b/openspec/changes/archive/2026-11-14-idd-548-links-submodule-markers/specs/spec-on-every-issue/spec.md new file mode 100644 index 00000000..36da6399 --- /dev/null +++ b/openspec/changes/archive/2026-11-14-idd-548-links-submodule-markers/specs/spec-on-every-issue/spec.md @@ -0,0 +1,66 @@ +## MODIFIED Requirements + +### Requirement: Added and modified requirements carry an executable check + +`scripts/spec-change.py links --base <rev>` SHALL compare the files under `openspec/specs/` at `<rev>` and at `--head` (default `HEAD`). For every requirement that is new or whose text differs between the two, it SHALL require one of two things: at least one `##### Example:` under the requirement, where each such Example has a title that is unique within its capability and a tracked file at the head revision, outside `openspec/` and not ending in `.md`, that contains the marker `spec-example: <capability> / <Example title>` (a tracked file of a submodule counts, as the paragraph "Submodules" below describes); or a line under the requirement that starts with `No executable check:` followed by a reason. A requirement that does not differ SHALL NOT be checked. A marker counts only when nothing but whitespace, or the comment closer `-->` or `*/`, follows the Example title on its line. Lines inside a code fence are not read as `##### Example:` or `No executable check:` lines; a fence opened by three or more backticks or tildes, at any indentation (as inside a list item), closes only on a line of the same character, at least as long, with nothing but whitespace after it; lines end only at `\n`, `\r\n` or `\r`. A requirement heading indented by up to three spaces SHALL be read as a requirement, as Spectra reads it. Paths SHALL be read as git stores them, never in git's quoted form, so a capability whose directory name is not ASCII is checked like any other. Two requirements with the same name in one capability SHALL make the command print `error`. So SHALL a code fence at the head revision that never closes, since the requirements after it would go unchecked. Outside code fences, a heading that starts with `### Requirement` but does not have the form `### Requirement: <name>` with a non-empty name SHALL make the command print `error`, and so SHALL a head revision at which the spec directory's `specs/` holds no tracked file. The command SHALL print one JSON line with `status` (`ok`, `missing` or `error`) and a list naming each requirement or Example that lacks its check, and SHALL exit 0, 1 or 2 in that order. `--base` is required: the caller names the range, so that a run on the default branch is checked against the commit it started from. The marker ties an Example to a test by name only; whether the test exercises what the Example states is judged by the reviewers of `idd-verify`. + +Submodules. The tracked files at the head revision include the tracked files of every submodule of the repository at the commit that the head revision records for it, and in the same way the files of a submodule of a submodule. The command SHALL read that recorded commit, not the commit the submodule's working tree is on. It SHALL find the submodules itself, from the entries of the head revision's tree that record a commit, and SHALL search each one whose directory is the top of its own working tree and whose object store holds the recorded commit; it SHALL NOT rely on git's own recursion into submodules, which passes over a submodule that is not checked out without saying so; the answer SHALL be the same whether or not the git configuration turns that recursion on (`submodule.recurse`). A file of a submodule is named by the submodule's path followed by the file's path, and the two exclusions (under the spec directory, ending in `.md`) apply to that name. When the marker of an Example is found, the Example has its check, whether or not every submodule could be searched. When it is not found and every submodule was searched, the Example is reported as lacking its check, as before. When it is not found and at least one submodule could not be searched (its directory is not a checked-out working tree of its own, or the recorded commit is not in its object store), the command SHALL print `error` and name the first such Example it meets, the path of each submodule that could not be searched (several are joined by `; `, and a submodule of a submodule is named by its path under the outer one) and the reason: an Example whose candidate files were not all read is not reported as lacking its check. A repository whose head revision records no submodule is checked exactly as before. + +#### Scenario: An Example without a test is reported + +- **GIVEN** a range that adds a requirement with one Example titled `status by exit code` to the capability `local-ci-gate` +- **AND** no tracked file outside `openspec/` contains `spec-example: local-ci-gate / status by exit code` +- **WHEN** `spec-change.py links` runs on that range +- **THEN** it prints `status` `missing`, names that Example, and exits 1 + +##### Example: what the link check reports + +| Requirement in the range | Examples | Marker at the head revision | `No executable check:` line | `status` | +| --- | --- | --- | --- | --- | +| added | one | in `scripts/tests/x/test.sh` | absent | `ok` | +| added | one | absent | absent | `missing` | +| added | one | only in a file under `openspec/` | absent | `missing` | +| added | one | only in a file ending in `.md` | absent | `missing` | +| added | none | not applicable | absent | `missing` | +| added | none | not applicable | present, with a reason | `ok` | +| added | none | not applicable | present, with nothing after the colon | `missing` | +| added | one, with no title | not applicable | absent | `missing` | +| added | two with the same title as an Example elsewhere in the capability | present | absent | `missing` | +| changed | two | present for one, absent for the other | absent | `missing` | +| unchanged, with no Example | none | not applicable | absent | `ok` | +| removed in the range | not applicable | not applicable | not applicable | `ok` | +| no file under `openspec/specs/` differs | not applicable | not applicable | not applicable | `ok` | +| added | one | only a marker naming a longer title that starts with this one | absent | `missing` | +| added, under the heading `### Requirement Missing colon` | not applicable | not applicable | not applicable | `error` | +| any; `openspec/specs/` holds no tracked file at the head revision | not applicable | not applicable | not applicable | `error` | +| added, its only `##### Example:` line inside a code fence | none outside fences | not applicable | absent | `missing` | +| added, its only `No executable check:` line inside a code fence | none | not applicable | only inside a fence | `missing` | +| added, after a fence of four backticks that a line of three backticks does not close | its Example inside that fence | not applicable | absent | `missing` | +| added, under the heading ` ### Requirement: Alpha` (two leading spaces) | none | not applicable | absent | `missing` | +| added, its only `No executable check:` line inside a fence indented four spaces in a list item | none | not applicable | only inside that fence | `missing` | +| added, in a capability whose directory name is not ASCII (`中文能力`) | none | not applicable | absent | `missing` | +| added, in a capability whose directory name holds a double quote (`quo"te`) | none | not applicable | absent | `missing` | +| added twice with the same name in one capability | not applicable | not applicable | not applicable | `error` | +| any, after a code fence that never closes | not applicable | not applicable | not applicable | `error` | +| `--base` names a revision that does not exist | not applicable | not applicable | not applicable | `error` | +| `--base` is not given | not applicable | not applicable | not applicable | usage error, exit 64 | + +##### Example: markers in submodules + +| Where the marker of the Example is at the head revision | Submodules recorded at the head revision | `status` | +| --- | --- | --- | +| in a tracked file of a submodule, at the commit the head revision records | one, checked out | `ok` | +| in a tracked file of a submodule of a submodule | both checked out | `ok` | +| in a tracked file of a submodule whose path holds a space | one, checked out | `ok` | +| only in the recorded commit of a submodule whose working tree is on a later commit without it | one, checked out | `ok` | +| only in a later commit of a submodule, which its working tree is on, not in the recorded commit | one, checked out | `missing` | +| only in a file of a submodule that ends in `.md` | one, checked out | `missing` | +| nowhere | one, checked out | `missing` | +| nowhere in the main repository | one, not checked out | `error`, naming the Example and the submodule's path | +| in a tracked file of the main repository | one, not checked out | `ok` | +| nowhere in the main repository | one, checked out, whose object store lacks the recorded commit | `error`, naming the Example and the submodule's path | +| in a tracked file of the main repository | one, checked out, whose object store lacks the recorded commit; `submodule.recurse` is true in the repository's git configuration | `ok` | +| nowhere in the main repository | one, checked out, whose object store lacks the recorded commit; `submodule.recurse` is true in the repository's git configuration | `error`, naming the Example and the submodule's path | +| only in the recorded commits of two submodules | two, neither checked out | `error`, naming the Example and both paths, joined by `; ` | +| only in a submodule of a submodule | the outer one checked out, the inner one not | `error`, naming the Example and the inner submodule by its path under the outer one | +| only in a tracked file of a submodule that is mounted under `openspec/` | one, checked out | `missing` | diff --git a/openspec/changes/archive/2026-11-14-idd-548-links-submodule-markers/tasks.md b/openspec/changes/archive/2026-11-14-idd-548-links-submodule-markers/tasks.md new file mode 100644 index 00000000..7ccaddee --- /dev/null +++ b/openspec/changes/archive/2026-11-14-idd-548-links-submodule-markers/tasks.md @@ -0,0 +1,35 @@ +## 1. 測試先行 + +- [x] 1.1 submodule 裡的標記有可執行的檢查:依 requirement「Added and modified requirements carry an executable check」的 Example「markers in submodules」,在 `plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 為十列各加一個檢查,測試檔帶標記 spec-example: spec-on-every-issue / markers in submodules;fixture 用本機路徑建立 submodule(`-c protocol.file.allow=always`),capability、路徑與檔名用通用字樣;沒取出的情況用 `git submodule deinit -f`,缺 commit 的情況用 `git update-index --cacheinfo` 記一個不存在的 commit。驗證:改 `spec-change.py` 之前執行,第 1、2、3、4、8、10 列的檢查失敗,第 5、6、7、9 列通過;實作者列出每一列的結果。 + +## 2. 實作與說明 + +- [x] 2.1 [after: 1.1] 依 design「links 自己列出 gitlink 並逐一搜尋」「找不到而且有地方沒看過時回 error」「排除規則套用在接上 submodule 路徑之後的名稱」「gitlink 的清單與可搜尋性在一次執行內只算一次」「在 submodule 目錄裡只跑唯讀的 git 指令」改 `plugins/issue-driven-dev/scripts/spec-change.py` 的 `marker_files()` 與 `cmd_links()`。驗證:1.1 的十個檢查全部通過;`tests/spec-change/test.sh` 既有的檢查全部通過、檢查數不減;`python3 -m py_compile plugins/issue-driven-dev/scripts/spec-change.py` 通過。 +- [x] 2.2 [after: 2.1] 說明文件:`spec-change.py` 檔頭的 `links` 段寫明 submodule 的讀法與 `error` 的情況;`plugins/issue-driven-dev/references/spec-wrapper.md` 在講標記的地方加一句(標記可以在 submodule 的已追蹤檔案裡,讀主 repo 記錄的 commit;檢查時 submodule 要已經取出,否則找不到標記的 Example 會讓檢查回 `error`);`plugins/issue-driven-dev/CHANGELOG.md` 的 Unreleased 加一條(#548)。驗證:`git diff` 對 CHANGELOG 只有新增行;文字不含任何特定專案的名稱或本機路徑。 + +## 3. 收尾 + +- [x] 3.1 [after: 2.2] 跑整套測試:`bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 與 `bash .claude/scripts/tests/spectra-archive-post-ic/test.sh`。驗證:結束碼都是 0;有 suite 因為機器負載逾時的話,單獨重跑那個 suite 並記錄。 +- [x] 3.2 [after: 3.1] 協調者驗收(在實作者寫不到的目錄):逐行讀改動;在一份只套用測試的複本上重跑 1.1,確認六個失敗、四個通過;重跑 `tests/spec-change/test.sh` 與整套測試;對一個沒有 gitlink 的 repo 比對改動前後 `links` 的輸出相同。驗證:驗收紀錄寫在這一項底下,每個結果附指令。 + + 驗收紀錄(2026-11-14;1.1 到 3.1 由實作者模型 Codex gpt-6-astra 依工作單完成,3.2 由協調者 Claude Fable 5.2 在實作者寫不到的目錄執行。沒有獨立讀者審過,交給下一步的 verify): + + - 逐行讀過 `spec-change.py`、`tests/spec-change/test.sh`、`references/spec-wrapper.md`、`CHANGELOG.md` 的改動。 + - 只套用新測試檔、script 維持 `6ed8dec` 的複本,跑 `bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh`:454 通過、20 失敗。失敗的是第 1、2、3、4、8、10 列的檢查(每列 status、回報筆數、結束碼三項,第 8、10 列另有原因文字一項);第 5、6、7、9 列與既有的檢查全部通過。 + - 工作樹的複本跑同一個指令:474 通過、0 失敗。舊測試檔配新 script:431 通過、0 失敗,既有的檢查沒有少。 + - 沒有 gitlink 的 repo:對這個 repo 自己的三段歷史(`401cd33..6ed8dec`、`2dc56ab..6ed8dec`、`fdf8d0d..4921b71`)跑改動前後的 `links`,輸出與結束碼逐位元組相同。 + - `python3 -m py_compile plugins/issue-driven-dev/scripts/spec-change.py` 通過。 + - 整套測試在沙箱外重跑:`bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 74 個 suite、0 個失敗,結束碼 0;`bash .claude/scripts/tests/spectra-archive-post-ic/test.sh` 141 通過、0 失敗。實作者在沙箱裡跑的那一次有三個 suite(correct-flow、edit-run、in-place-correction)因為寫不進 `/var/tmp` 而失敗,與這次改動無關,沙箱外都通過。 + - 在一個有五個 submodule 的 repo 上,新的 `links` 跑完整段範圍約 2.6 秒。 + - 對 `<head>` 記錄的 commit 搜尋,不論物件來自哪個目錄,內容都由 commit 的雜湊決定;所以 submodule 目錄是否在工作樹內不影響找到的標記是否屬於記錄的那一版。沒有另外加路徑檢查。 + +## 4. 封存前的補強(spectra-verify 之後) + +- [x] 4.1 依 `spectra-verify` 的一項 warning 與四項建議補強:Example「markers in submodules」加第 11 到 15 列與對應的檢查(`submodule.recurse` 開啟時,主 repo 有標記仍為 `ok`、缺 commit 仍點名 Example 與路徑;兩個 submodule 都沒取出時兩個路徑以分號相連;巢狀 submodule 沒取出時點名內層的路徑;掛在規格目錄底下的 submodule 裡的標記不算);依 design「git 自己的遞迴一律關掉」在 `git grep` 加 `--no-recurse-submodules`;fixture 步驟失敗時先印一行再結束。驗證:加旗標之前第 11、12 列的三項檢查失敗、其餘通過;加旗標之後 `bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 全部通過。 + + 紀錄(2026-11-14;這一項是協調者自己寫的改動,沒有經過實作者模型,交給下一步的 verify): + + - 實測 git 2.55.0:`submodule.recurse=true` 時,`git grep <tree>` 會自己搜尋 submodule,記錄的 commit 不在物件庫時以 128 結束;加上 `--no-recurse-submodules` 後回到不遞迴的行為。 + - 新測試在加旗標之前:494 通過、3 失敗(第 11 列的 status 與結束碼、第 12 列的原因文字)。加旗標之後:497 通過、0 失敗。 + - 第 13、14、15 列在加旗標之前就通過:它們檢查的是規格已經寫明、先前沒有測試的三件事。 + - Example 表現在是十五列;1.1 寫的「十列」是補強之前的數字。 diff --git a/openspec/changes/archive/2026-11-15-idd-548-fix5/.openspec.yaml b/openspec/changes/archive/2026-11-15-idd-548-fix5/.openspec.yaml new file mode 100644 index 00000000..171e1ddb --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-fix5/.openspec.yaml @@ -0,0 +1,6 @@ +schema: spec-driven +created: 2026-11-15 +created_by: che cheng <kiki830621@gmail.com> +created_with: claude +archived_by: che cheng <kiki830621@gmail.com> +archived_at: 2026-11-15 diff --git a/openspec/changes/archive/2026-11-15-idd-548-fix5/design.md b/openspec/changes/archive/2026-11-15-idd-548-fix5/design.md new file mode 100644 index 00000000..030cfc1c --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-fix5/design.md @@ -0,0 +1,86 @@ +## Context + +第五輪 verify 第一次從頭審整條分支(預設分支到 `8003a7b`)。結論是 1 項 blocking、4 項要在分支上修、8 項後續(留言 6889821186)。 + +blocking 的那一項:head 記錄一個 gitlink `dir/sub`;工作目錄裡 `dir` 是指向 `.git/planted` 的 symbolic link,`.git/planted/sub` 是人工放進去、持有記錄的 commit 與標記的 clone。`links` 回 `ok`,並在那個目錄執行五次 git;4.1.0 回 `missing`。requirement 的第 2 個條件是「its directory, after symbolic links are resolved, lies inside the working tree of the main repository」。git 自己在 `.git/planted` 裡回報:不在工作目錄內、在 git 目錄內。security 一席評為 LOW;devil's advocate 補審後依審查規則裁定 HIGH(範圍內改變了、而 requirement 沒有寫明的行為)。兩席都確認後果小:讀的是記錄的 commit(依 id),不會替沒有標記的 commit 回 `ok`;commit、clone、checkout 都產生不出這個狀態。 + +量測(協調者,git 2.55.0,macOS;三個 fixture,各用 4.1.0 與 `8003a7b` 的 script 跑一次,並記錄 git 呼叫): + +| link 指向 | 4.1.0 | `8003a7b` | 在 `dir/sub` 的 git 呼叫 | +| --- | --- | --- | --- | +| 主 repo 的 `.git/planted` | `missing` | `ok` | 5 | +| 工作目錄內的另一個目錄 | `missing` | `ok` | 5 | +| 頂層目錄之外 | `missing` | `error`(path leaves the repository) | 0 | + +## Goals / Non-Goals + +Goals: + +- 第 2 個條件的程式與條文一致:主 repo 的 git 目錄與它底下的東西不算在工作目錄內。 +- 這個行為有一列 Example,而且它的測試在修正之前失敗。 +- 第五輪第 2 到 5 列在同一輪補齊,不改任何行為。 + +Non-Goals: + +- 不改 link 指向工作目錄內另一個 clone 時的答案。 +- 不排除主 repo 以外的 git 目錄;不處理第五輪第 6 到 13 列(#559)。 + +## Decisions + +### 照條文改程式,不改條文去配合程式 + +兩種修法:(a) 程式照條文,把落在主 repo git 目錄裡的目錄算成不符合第 2 個條件;(b) 把條文改成「頂層目錄內」,並寫明 git 目錄也算在內。選 (a)。理由:「不符合前四個條件的目錄裡不得執行 git」這一句的用意,是不在工作目錄以外的地方執行 git;(a) 讓答案變成 `error`,方向是少讀、不是多讀,與這條分支先前的取捨一致(讀不到或不該讀時回 `error`,不把沒檢查到的說成檢查過)。(b) 是在審查者指出不一致之後改條文去配合程式,而且會把「在 git 目錄裡執行 git」寫成規格。 + +### git 目錄的位置問 git,用目錄的身分比,不比名稱 + +主 repo 的 git 目錄不一定叫 `.git`(`--separate-git-dir` 可以放在任何地方、取任何名字),在會折疊大小寫的檔案系統上,link 的目標也可以寫成 `.GIT`。所以不比路徑字串:在主 repo 的頂層執行 `git rev-parse --absolute-git-dir` 取得位置,從解析後的目錄一層一層往上走到頂層目錄為止,每一層用 `os.stat` 的裝置與 inode 與 git 目錄比。任一層相同,就是 git 目錄本身或在它底下。某一層 stat 不到(目錄不存在)就跳過那一層:不存在的東西不會是 git 目錄,而目錄不存在的 submodule 之後會被第 3、4 個條件判成 not checked out。git 目錄本身 stat 不到時回 `error`。 + +主 repo 是 linked worktree,或它自己是別人的 submodule 時,git 目錄在頂層目錄之外,這個檢查不會命中任何東西;那種位置原本就被「在頂層目錄之外」擋下。 + +### 只排除主 repo 自己的 git 目錄 + +條文講的是主 repo 的工作目錄,所以排除的是主 repo 的 git 目錄。照一般做法取出的 submodule,git 目錄在主 repo 的 `.git/modules/` 底下,因此也在排除的範圍內。沒有涵蓋的只有一種:外層 submodule 的 `.git` 是放在它自己目錄裡的真目錄(不是由 `git submodule` 取出)時,link 指進那個 `.git`。照條文那個位置在主 repo 的工作目錄內。要不要一律排除任何 git 目錄,是另一個決定,記在 #559。 + +### 只在第一次要檢查 submodule 的目錄時問一次 + +requirement 的「Order of the search」寫明:標記在主 repo 就找到時,不列出 gitlink、不檢查任何 submodule。所以 git 目錄的位置不在一開始就問,而是在第一次有 submodule 的目錄通過「在頂層目錄內」之後才問,並存起來給同一次執行的其他 submodule 與其他 Example 用。標記都在主 repo 的 repo,git 呼叫的次數不變。 + +### 原因沿用 path leaves the repository + +requirement 把第 1、2 個條件的原因定為同一句。這個情況是第 2 個條件不成立,所以用同一句,不新增第七種原因。 + +### 第 29 列:改 fixture,不改列 + +第五輪第 2 列指出第 29 列寫「標記只在七個 submodule 記錄的 commit 裡」,fixture 卻是七個指向不存在的 commit 的 gitlink。兩種修法:把列的第一欄改成 nowhere,或把 fixture 建成列裡寫的。選後者:列裡寫的輸入(標記真的在 submodule 裡、但都沒有 checkout)才是這個功能要回答的情況,而且程式對它的答案已經由兩席實測確認。fixture 另外確認每個 submodule 都停在記錄的 commit、那個 commit 有標記,再 deinit。斷言不改。 + +### 第 7 到 12 列的標籤改名 + +第五個 change 的 design 決定不改這些斷言的名稱,理由是它們只是訊息。第五輪第 5 列指出:檢查失敗時印出的標題在規格裡已經找不到。所以這次改成現在的 Example 標題的用詞。只改名稱,比對的內容不變。 + +### 建不出暫存目錄就停 + +測試檔的 fixture 都建在 `$WORK` 底下,也會刪除它底下的路徑。`mktemp` 失敗時 `$WORK` 是空的,那些路徑就落在檔案系統的根目錄。所以 `mktemp` 失敗、或結果不是目錄時,測試印出原因並以 1 結束,不往下跑。 + +## Implementation Contract + +- `openspec/specs/spec-on-every-issue/spec.md`(由封存套用):requirement「Added and modified requirements carry an executable check」的第 2 個條件多一句;Example「markers in submodules」在第 54 列之後多第 55 列。其他句子與列逐字不變。 +- `plugins/issue-driven-dev/scripts/spec-change.py`:`marker_files()` 在「解析後的目錄在頂層目錄內」之後、檢查目錄本身之前,多一個判斷;新增一個函式做逐層比對。除此之外不改。這個判斷成立時,不呼叫 `submodule_git()`。 +- `plugins/issue-driven-dev/scripts/tests/spec-change/test.sh`:新增第 55 列的 fixture 與 7 個檢查;第 29 列的 fixture 重建,斷言不變;`mktemp` 的守衛;28 處標籤與標題改名。 +- `plugins/issue-driven-dev/CHANGELOG.md`:只動 `[Unreleased]` 裡 #548 那一條,兩處。 +- 驗證:第 55 列的檢查在 `8003a7b` 的 script 上失敗、在改過的 script 上通過;`tests/spec-change/test.sh` 全部通過;`run-all-tests.sh` 結束碼 0;`links --base origin/main` 回 `ok`;`archived` 回 pass。 + +## Risks / Trade-offs + +- 有 submodule 要檢查的執行多一次 git 呼叫(在主 repo 的頂層)。 +- 在主 repo 的 git 目錄裡放 clone、再用 link 接出來的人,答案從 `ok` 變成 `error`。這個狀態只能手動造出來;`git submodule update --init` 取出的 submodule 不受影響。 +- 外層 submodule 自己的 `.git` 真目錄不在排除範圍內(見上面的決定)。 +- 協調者在做這個 change 時另外試出一種同類的情況,這個 change 不處理:記錄的路徑經過上層的 symbolic link 離開頂層目錄、再回到頂層目錄本身(例如 `out` 指向 `..`,記錄的路徑是 `out/<頂層目錄的名字>`),而且 head 為它記錄的是主 repo 自己較早的一個 commit。六個條件照字面都成立(git 在頂層目錄回報它在工作目錄內),`links` 會讀那個較早的 commit;那個 commit 有標記時回 `ok`,即使 head 自己的檔案沒有標記。修改前後的 script 答案相同,4.1.0 回 `missing`。這個狀態同樣要手動放 link 才造得出來。記在 #559。 +- 這個 change 的條文、測試與程式都由協調者撰寫,沒有實作者模型,也沒有獨立讀者;第六輪 verify 是第一次獨立審查。 + +## Migration Plan + +不需要。沒有設定或資料要搬。 + +## Open Questions + +沒有。要不要排除任何 git 目錄(不只主 repo 的),在 #559。 diff --git a/openspec/changes/archive/2026-11-15-idd-548-fix5/proposal.md b/openspec/changes/archive/2026-11-15-idd-548-fix5/proposal.md new file mode 100644 index 00000000..6d9b107f --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-fix5/proposal.md @@ -0,0 +1,50 @@ +**GitHub-side tracker**: #548 + +## Problem + +第五輪 verify(留言 6889821186)第 1 列。submodule 路徑的上層目錄是 symbolic link,指向主 repo 自己的 git 目錄裡一個人工放進去的 clone 時,`links` 在那裡執行 git(五次)並回 `ok`。requirement「Added and modified requirements carry an executable check」的第 2 個條件寫的是「解析 symbolic link 之後,位於主 repo 的工作目錄內」;git 目錄不屬於工作目錄,所以照條文這個 submodule 不該被搜尋,答案是 `error`(path leaves the repository),而且「不符合前四個條件的目錄裡不得執行 git」。 + +同一輪的第 2 到 5 列是測試檔與 CHANGELOG 的缺口,不改行為,在同一輪修。 + +## Root Cause + +`marker_files()` 用「解析後的路徑是不是在頂層目錄的實際路徑底下」判斷第 2 個條件。主 repo 的 git 目錄通常就在頂層目錄底下(`.git`),所以也被算成在裡面。第二個 change 的 design 寫的是「頂層目錄」,requirement 寫的是「工作目錄」;兩個詞只在 git 目錄這一塊不同,而 Example 沒有任何一列建這個輸入,所以五輪之前沒有被發現。 + +## Proposed Solution + +- 程式照條文走。解析後的目錄是主 repo 的 git 目錄,或在它底下時,算不符合第 2 個條件:原因是 path leaves the repository,不在那個目錄執行 git。 +- git 目錄的位置問 git(`git rev-parse --absolute-git-dir`,在主 repo 的頂層執行),再用「是不是同一個目錄」逐層往上比,不比名稱。只在第一次要檢查某個 submodule 的目錄時問一次;標記在主 repo 就找到的情況不多任何 git 呼叫。 +- requirement 的第 2 個條件補一句,寫明主 repo 自己的 git 目錄與它底下的東西不算在工作目錄內。 +- Example「markers in submodules」補第 55 列;它的測試在這次修正之前的 commit 上失敗。 +- 第五輪第 2 到 5 列:第 29 列的 fixture 改成列裡寫的輸入;建不出暫存目錄時測試不往下跑;第 7 到 12 列的標籤改用現在的 Example 標題;CHANGELOG 補一句 `submodule.recurse` 打開時答案會變的情況。 + +## Non-Goals + +- 不處理 link 指向工作目錄內另一個 clone 的情況:照條文那是寫明的行為(第五輪兩席讀法相同)。 +- 不排除其他 repository 的 git 目錄(例如外層 submodule 自己的 `.git` 目錄)。條文講的是主 repo 的工作目錄;要不要一律排除任何 git 目錄,留在 #559。 +- 第五輪第 6 到 13 列留在 #559,不在這條分支處理。 + +## Success Criteria + +- 第 55 列的測試在 `8003a7b`(這次修正之前)失敗,在修正之後通過;它確認答案是 `error`、原因點名路徑與 path leaves the repository,而且記錄 git 呼叫的程式沒有看到任何一次在那個目錄的呼叫。 +- link 指向工作目錄內另一個 clone 時仍回 `ok`;link 指到頂層目錄之外時仍回 `error`。 +- `bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 全部通過;`bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 結束碼 0。 +- `spec-change.py links` 從預設分支到這條分支的 HEAD 回 `ok`;`archived` 回 pass。 + +## Capabilities + +### New Capabilities + +(none) + +### Modified Capabilities + +- `spec-on-every-issue`: requirement「Added and modified requirements carry an executable check」的第 2 個條件補一句;Example「markers in submodules」加第 55 列。 + +## Impact + +- Affected specs: spec-on-every-issue(一個 MODIFIED requirement) +- Affected code: + - Modified: plugins/issue-driven-dev/scripts/spec-change.py + - Modified: plugins/issue-driven-dev/scripts/tests/spec-change/test.sh + - Modified: plugins/issue-driven-dev/CHANGELOG.md diff --git a/openspec/changes/archive/2026-11-15-idd-548-fix5/specs/spec-on-every-issue/spec.md b/openspec/changes/archive/2026-11-15-idd-548-fix5/specs/spec-on-every-issue/spec.md new file mode 100644 index 00000000..e5ddc26e --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-fix5/specs/spec-on-every-issue/spec.md @@ -0,0 +1,115 @@ +## MODIFIED Requirements + +### Requirement: Added and modified requirements carry an executable check + +`scripts/spec-change.py links --base <rev>` SHALL compare the files under `openspec/specs/` at `<rev>` and at `--head` (default `HEAD`). For every requirement that is new or whose text differs between the two, it SHALL require one of two things: at least one `##### Example:` under the requirement, where each such Example has a title that is unique within its capability and a tracked file at the head revision, outside `openspec/` and not ending in `.md`, that contains the marker `spec-example: <capability> / <Example title>` (a tracked file of a submodule counts, as the paragraph "Submodules" below describes); or a line under the requirement that starts with `No executable check:` followed by a reason. A requirement that does not differ SHALL NOT be checked. A marker counts only when nothing but whitespace, or the comment closer `-->` or `*/`, follows the Example title on its line. Lines inside a code fence are not read as `##### Example:` or `No executable check:` lines; a fence opened by three or more backticks or tildes, at any indentation (as inside a list item), closes only on a line of the same character, at least as long, with nothing but whitespace after it; lines end only at `\n`, `\r\n` or `\r`. A requirement heading indented by up to three spaces SHALL be read as a requirement, as Spectra reads it. Paths SHALL be read as git stores them, never in git's quoted form, so a capability whose directory name is not ASCII is checked like any other. Two requirements with the same name in one capability SHALL make the command print `error`. So SHALL a code fence at the head revision that never closes, since the requirements after it would go unchecked. Outside code fences, a heading that starts with `### Requirement` but does not have the form `### Requirement: <name>` with a non-empty name SHALL make the command print `error`, and so SHALL a head revision at which the spec directory's `specs/` holds no tracked file, and a path under the spec directory's `specs/` that is not valid UTF-8 (the reason says so and carries no text of an exception). Such a path elsewhere under the spec directory does not change the answer. The command SHALL print one JSON line with `status` (`ok`, `missing` or `error`) and a list naming each requirement or Example that lacks its check, and SHALL exit 0, 1 or 2 in that order. `--base` is required: the caller names the range, so that a run on the default branch is checked against the commit it started from. The marker ties an Example to a test by name only; whether the test exercises what the Example states is judged by the reviewers of `idd-verify`. + +Submodules. The tracked files at the head revision include the tracked files of every submodule of the repository at the commit that the head revision records for it, and in the same way the files of a submodule of a submodule. The command SHALL read that recorded commit, not the commit the submodule's working tree is on. It SHALL find the submodules itself, from the entries of the head revision's tree that record a commit; it SHALL NOT rely on git's own recursion into submodules, which passes over a submodule that is not checked out without saying so; the answer SHALL be the same whether or not the git configuration turns that recursion on (`submodule.recurse`). A file of a submodule is named by the submodule's path followed by the file's path, and the two exclusions (under the spec directory, ending in `.md`) apply to that name. A submodule whose own path is under the spec directory SHALL NOT be searched and SHALL NOT count as one that could not be searched: none of its files could count. + +Order of the search. For each Example the command SHALL search the main repository first. When the marker is found there, the Example has its check and the command SHALL NOT run git in any submodule for it, so for a repository whose markers are all in its own files no entry that records a commit is listed and no submodule is examined, whatever its head revision records. Only when the marker is not found in the main repository are the submodules searched, and a marker found in one submodule settles the Example whatever the state of the others. When the marker of an Example is found, the Example has its check, whether or not every submodule could be searched. The submodules inside a submodule are read from a listing of every tree of its recorded commit, and that listing is made only when the outer one meets its own six conditions. Each of them is then searched whenever its own six conditions hold, also when the search of the outer one failed. When the listing fails, because a tree of the recorded commit cannot be read, the submodules inside it are unknown, even when the top tree shows them. + +Which submodules can be searched. A submodule SHALL be searched only when all six of these hold: (1) its path, as the tree records it, is relative and has no empty, `.` or `..` component; (2) its directory, after symbolic links are resolved, lies inside the working tree of the main repository, and the main repository's own git directory, with everything under it, is no part of that working tree, whatever the git directory is named (the command asks git where it is and compares directories, not names); (3) the directory itself is not a symbolic link; (4) the directory holds an entry named `.git` of its own; (5) git, run in the directory, reports it as the top of its own working tree; (6) its object store holds the recorded commit. The command SHALL NOT run git in a directory that fails any of the first four: a directory of ordinary tracked files can be shaped like a git directory, and git would read, and act on, the configuration it holds. Nor SHALL it run git in the directory of any submodule when git is older than 2.45, the first version that honours `GIT_NO_LAZY_FETCH`, or when the version cannot be read: a submodule for which the first four hold then counts as one that could not be searched. In the directory of a submodule the command SHALL run git with `safe.bareRepository` set to `explicit`, with lazy fetching turned off (`GIT_NO_LAZY_FETCH=1`), and with the variables `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, `GIT_OBJECT_DIRECTORY`, `GIT_ALTERNATE_OBJECT_DIRECTORIES` and `GIT_COMMON_DIR` removed from the environment it inherited. Before it searches a submodule the command SHALL ask git which objects of the recorded commit (its trees and the contents of its files) the object store lacks or cannot open, without fetching any: an object whose file is present but cannot be opened (for example an empty file) counts as lacking. A submodule is searched even when some are lacking, and a file that counts, found by a search that ran to its end (exit code 0 or 1), settles the Example. What a search printed before it ended with another exit code SHALL NOT be used, so that the answer for one state of the repository is the same on every run. When no file that counts is found in it, the submodule counts as one that could not be searched if its object store lacks an object of the recorded commit, if the search exits with a code other than 0 or 1, or if the trees of the recorded commit cannot all be listed. What git writes to its error stream SHALL NOT change whether a submodule counts as searched, nor the reason reported for it. In the main repository a search that exits with a code other than 0 or 1 is `error`, as before; its reason is `git grep failed: ` followed by the first 200 characters of what git wrote to its error stream, also as before. + +What is reported. When the marker is not found and every submodule was searched, the Example is reported as lacking its check, as before. When it is not found and at least one submodule could not be searched, the command SHALL print `error` and name the first such Example it meets, the submodules that could not be searched and the reason for each: an Example whose candidate files were not all read is not reported as lacking its check. The submodules are named by path, in the order of their paths and joined by `; `; a submodule of a submodule is named by its path under the outer one; when more than five could not be searched, the first five are named and the number of the others is stated; a path longer than 200 characters is cut to its first 200 followed by `...`. The reason is one of six: the path leaves the repository (conditions 1 and 2); the submodule is not checked out (conditions 3 and 4, or git names another directory as the top); git is older than 2.45 (stated also when its version cannot be read); git refused to open it (the git command of condition 5 fails); the recorded commit is not in its object store (condition 6); the recorded commit could not be read (its object store lacks or cannot open an object of it, or the search or the listing of its trees failed). The reason given for a submodule SHALL NOT carry text from git's error stream. The path of a submodule that is not valid UTF-8 is handled like any other path, and the command still prints one JSON line. A repository whose head revision records no submodule is searched in its own tracked files only: none of the rules for submodules changes its answer. + +#### Scenario: An Example without a test is reported + +- **GIVEN** a range that adds a requirement with one Example titled `status by exit code` to the capability `local-ci-gate` +- **AND** no tracked file outside `openspec/` contains `spec-example: local-ci-gate / status by exit code` +- **WHEN** `spec-change.py links` runs on that range +- **THEN** it prints `status` `missing`, names that Example, and exits 1 + +##### Example: what the link check reports + +| Requirement in the range | Examples | Marker at the head revision | `No executable check:` line | `status` | +| --- | --- | --- | --- | --- | +| added | one | in `scripts/tests/x/test.sh` | absent | `ok` | +| added | one | absent | absent | `missing` | +| added | one | only in a file under `openspec/` | absent | `missing` | +| added | one | only in a file ending in `.md` | absent | `missing` | +| added | none | not applicable | absent | `missing` | +| added | none | not applicable | present, with a reason | `ok` | +| added | none | not applicable | present, with nothing after the colon | `missing` | +| added | one, with no title | not applicable | absent | `missing` | +| added | two with the same title as an Example elsewhere in the capability | present | absent | `missing` | +| changed | two | present for one, absent for the other | absent | `missing` | +| unchanged, with no Example | none | not applicable | absent | `ok` | +| removed in the range | not applicable | not applicable | not applicable | `ok` | +| no file under `openspec/specs/` differs | not applicable | not applicable | not applicable | `ok` | +| added | one | only a marker naming a longer title that starts with this one | absent | `missing` | +| added, under the heading `### Requirement Missing colon` | not applicable | not applicable | not applicable | `error` | +| any; `openspec/specs/` holds no tracked file at the head revision | not applicable | not applicable | not applicable | `error` | +| added, its only `##### Example:` line inside a code fence | none outside fences | not applicable | absent | `missing` | +| added, its only `No executable check:` line inside a code fence | none | not applicable | only inside a fence | `missing` | +| added, after a fence of four backticks that a line of three backticks does not close | its Example inside that fence | not applicable | absent | `missing` | +| added, under the heading ` ### Requirement: Alpha` (two leading spaces) | none | not applicable | absent | `missing` | +| added, its only `No executable check:` line inside a fence indented four spaces in a list item | none | not applicable | only inside that fence | `missing` | +| added, in a capability whose directory name is not ASCII (`中文能力`) | none | not applicable | absent | `missing` | +| added, in a capability whose directory name holds a double quote (`quo"te`) | none | not applicable | absent | `missing` | +| added, in a capability whose directory name is not valid UTF-8 | not applicable | not applicable | not applicable | `error`, with a reason that says so | +| added; a tracked path under the spec directory but outside `specs/` is not valid UTF-8 | one | in `scripts/tests/x/test.sh` | absent | `ok` | +| added; a tree of the head revision outside the spec directory cannot be read | one | absent | absent | `error`; the reason is `git grep failed: ` followed by the first 200 characters of what git wrote to its error stream | +| added twice with the same name in one capability | not applicable | not applicable | not applicable | `error` | +| any, after a code fence that never closes | not applicable | not applicable | not applicable | `error` | +| `--base` names a revision that does not exist | not applicable | not applicable | not applicable | `error` | +| `--base` is not given | not applicable | not applicable | not applicable | usage error, exit 64 | + +##### Example: markers in submodules + +| Where the marker of the Example is at the head revision | Submodules recorded at the head revision | `status` | +| --- | --- | --- | +| in a tracked file of a submodule, at the commit the head revision records | one, checked out | `ok` | +| in a tracked file of a submodule of a submodule | both checked out | `ok` | +| in a tracked file of a submodule whose path holds a space | one, checked out | `ok` | +| only in the recorded commit of a submodule whose working tree is on a later commit without it | one, checked out | `ok` | +| only in a later commit of a submodule, which its working tree is on, not in the recorded commit | one, checked out | `missing` | +| only in a file of a submodule that ends in `.md` | one, checked out | `missing` | +| nowhere | one, checked out | `missing` | +| nowhere in the main repository | one, not checked out | `error`, naming the Example and the submodule's path | +| in a tracked file of the main repository | one, not checked out | `ok` | +| nowhere in the main repository | one, checked out, whose object store lacks the recorded commit | `error`, naming the Example and the submodule's path | +| in a tracked file of the main repository | one, checked out, whose object store lacks the recorded commit; `submodule.recurse` is true in the repository's git configuration | `ok` | +| nowhere in the main repository | one, checked out, whose object store lacks the recorded commit; `submodule.recurse` is true in the repository's git configuration | `error`, naming the Example and the submodule's path | +| only in the recorded commits of two submodules | two, neither checked out | `error`, naming the Example and both paths, joined by `; ` | +| only in a submodule of a submodule | the outer one checked out, the inner one not | `error`, naming the Example and the inner submodule by its path under the outer one | +| only in a tracked file of a submodule that is mounted under `openspec/` | one, checked out | `missing` | +| in a tracked file of the main repository | one whose path is not valid UTF-8, not checked out | `ok` | +| nowhere | one whose path is not valid UTF-8, not checked out | `error` on one JSON line, exit 2 | +| in a tracked file of the main repository | one, checked out, holding the recorded commit but not the tree of that commit | `ok` | +| nowhere in the main repository | one, checked out, holding the recorded commit but not the tree of that commit | `error`, naming the Example and the submodule's path, with no text from git's error stream | +| nowhere | one, checked out, whose object store lacks the content of one file of the recorded commit | `error`, naming the Example and the submodule's path, with no text from git's error stream | +| nowhere | one, checked out, whose recorded commit records a second submodule; at that second path the working tree holds ordinary files shaped like a git directory (`HEAD`, `config`, `objects/`, `refs/`) and no `.git` entry, and that `config` names a command to run | `error`, naming the second path as not checked out; the command named in that `config` does not run | +| in a tracked file of the main repository | the same two, with the same files at the second path | `ok`; no git command runs in the directory of a submodule, and the command named in that `config` does not run | +| only in a repository outside the main repository, at a path with a `..` component that the head revision's tree records as a submodule | that one | `error`, naming the path as one that leaves the repository; the same answer when nothing is at that outside path | +| only in a repository outside the main repository, reached through a symbolic link in the working tree that is part of a recorded submodule path | that one | `error`, naming the path as one that leaves the repository | +| in a tracked file of a submodule whose path ends in a space | one, checked out | `ok` | +| nowhere | one, not checked out, mounted under `openspec/` | `missing` | +| only in a tracked file of a submodule | one, checked out elsewhere inside the working tree of the main repository, whose own directory is a symbolic link to that checkout | `error`, naming the Example and the submodule's path as not checked out | +| in a tracked file of a submodule | one, checked out; the variable `GIT_DIR` is set to the git directory of the main repository | `ok` | +| only in the recorded commits of seven submodules | seven, none checked out | `error`, naming the Example, the first five paths in order and the number of the other two | +| nowhere | one whose directory holds a `.git` entry that git cannot open | `error`, naming the Example and the submodule's path as one git refused to open | +| nowhere | one whose directory holds an empty `.git` directory and, beside it, ordinary files shaped like a git directory (`HEAD`, `config`, `objects/`, `refs/`) whose `config` names a command to run | `error`, naming the submodule's path as one git refused to open; the command named in that `config` does not run | +| in a tracked file of the main repository | one, checked out as a partial clone that never fetched the file contents of the recorded commit | `ok`; nothing is fetched into the submodule | +| nowhere | one, checked out as a partial clone that never fetched the file contents of the recorded commit | `error`, naming the Example and the submodule's path; nothing is fetched into the submodule | +| nowhere | one, not checked out, whose path is longer than 200 characters | `error`, naming the first 200 characters of the path followed by `...` | +| in a tracked file of one submodule | two; the one with the marker checked out, the other not | `ok` | +| only in a file ending in `.md` of a submodule | one, checked out, whose object store lacks the content of another file of the recorded commit | `error`, naming the Example and the submodule's path | +| only in a tracked file of a submodule | one whose `.git` entry git opens, with the working tree of that git directory set to the parent directory, so that git names the parent as the top | `error`, naming the Example and the submodule's path as not checked out | +| only in a submodule of a submodule | three recorded paths: `a`, checked out; its own submodule `a/inner`, not checked out; and `a-b`, not checked out | `error`, naming `a-b` before `a/inner` | +| nowhere | one, at a path with a `.` component that the head revision's tree records | `error`, naming the path as one that leaves the repository | +| in a tracked file of a submodule | one, checked out; the six variables named above are all set to the git directory, working tree, index and object store of the main repository | `ok` | +| only in the recorded commit of a submodule, which the checked-out submodule's own object store lacks | one, checked out; the variable `GIT_ALTERNATE_OBJECT_DIRECTORIES` names an object store that holds that commit | `error`, naming the Example and the submodule's path, with the recorded commit as not in its object store | +| only in a submodule of a submodule, checked out and complete | the outer one checked out, its object store lacking the content of one unrelated file of its recorded commit | `ok` | +| nowhere | the same two | `error`, naming the Example and the outer submodule's path only, with its recorded commit as one that could not be read | +| in a tracked file of one submodule | two; the other one is not checked out and comes first in the order of the paths | `ok` | +| in a tracked file that counts, of a submodule whose object store lacks the content of another file of the recorded commit | one, checked out | `ok` | +| nowhere | one, checked out, holding every object of the recorded commit; git writes to its error stream during the search (`GIT_TRACE=1`) | `missing` | +| only in a tracked file of a submodule | one, checked out; git reports a version older than 2.45, or one that cannot be read | `error`, naming the Example and the submodule's path with git as older than 2.45; no git command runs in the directory of the submodule | +| in a tracked file of the main repository | one, checked out; git reports a version older than 2.45 | `ok` | +| nowhere | one, checked out, whose object store holds a damaged copy of the content of one file of the recorded commit (the object file is present and is not a compressed object, so the search ends with exit code 128) | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read | +| only in a tracked file of a submodule; the object that holds the content of that file is present but empty (zero bytes), so the search skips the file and ends with exit code 0 or 1 | one, checked out | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read | +| nowhere | one, checked out, holding every object of the recorded commit; one of its tracked files has a name with a carriage return followed by `?` | `missing` | +| in a tracked file of a submodule | one, checked out, whose object store holds a damaged copy of the content of another file, so that the search ends with exit code 128 | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read; the same answer on each of three runs | +| only in a submodule of a submodule, checked out and complete | the outer one checked out, its object store lacking a tree below the top of its recorded commit | `error`, naming the Example and the outer submodule's path only, with its recorded commit as one that could not be read | +| nowhere | one, checked out; the object that holds the content of one file is damaged in its body, so that git lists it and opens it, and the search ends with exit code 128 | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read | +| only in a repository placed inside the git directory of the main repository, reached through a symbolic link in the working tree that is part of a recorded submodule path | that one | `error`, naming the path as one that leaves the repository; git is not run in that directory | diff --git a/openspec/changes/archive/2026-11-15-idd-548-fix5/tasks.md b/openspec/changes/archive/2026-11-15-idd-548-fix5/tasks.md new file mode 100644 index 00000000..dae98b97 --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-fix5/tasks.md @@ -0,0 +1,25 @@ +## 1. 測試先寫 + +- [x] 1.1 依 design「照條文改程式,不改條文去配合程式」與「原因沿用 path leaves the repository」,為 requirement「Added and modified requirements carry an executable check」的 Example「markers in submodules」第 55 列寫 fixture 與檢查,加在 `plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 第 54 列的檢查之後:head 記錄一個 gitlink,它的上層目錄是指進主 repo git 目錄的 symbolic link,那裡有人工放進去、持有記錄的 commit 與標記的 clone。fixture 先確認 clone 持有那個 commit、那個 commit 有標記、而且 git 回報那個位置在 git 目錄內。檢查:`status` 是 `error`、結束碼 2、原因點名路徑與 path leaves the repository、記錄 git 呼叫的程式沒有看到任何一次在那個目錄的呼叫。驗證:這時 script 還沒改,`bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 只有第 55 列的檢查失敗;失敗的檢查名稱記在這一項底下。 + - 紀錄(script 還是 `8003a7b` 的版本):`bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 802 項通過、4 項失敗、結束碼 1。失敗的四項都是第 55 列:`status`(得到 `ok`)、結束碼(得到 0)、原因(空的)、「no git command ran in the planted directory」(記錄到在那個目錄的呼叫)。同一列通過的三項是不分修正前後都成立的:回報的項目數是 0、只印一行 JSON、記錄 git 呼叫的程式看到主 repo 的呼叫。 + +## 2. 程式 + +- [x] 2.1 [after: 1.1] 依 design「git 目錄的位置問 git,用目錄的身分比,不比名稱」「只排除主 repo 自己的 git 目錄」「只在第一次要檢查 submodule 的目錄時問一次」與 Implementation Contract:`plugins/issue-driven-dev/scripts/spec-change.py` 的 `marker_files()` 在「解析後的目錄在頂層目錄內」之後多一個判斷,解析後的目錄是主 repo 的 git 目錄或在它底下時,原因是 path leaves the repository,不呼叫 `submodule_git()`。驗證:`bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 全部通過、0 項失敗;標記在主 repo 的 repo,git 呼叫的次數與修改前相同(第 22 列既有的檢查)。 + +## 3. 第五輪第 2 到 5 列 + +- [x] 3.1 [after: 2.1] 依 design「第 29 列:改 fixture,不改列」「建不出暫存目錄就停」「第 7 到 12 列的標籤改名」:`plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 的第 29 列 fixture 改成七個來源有標記、停在記錄的 commit、再 deinit 的 submodule,斷言不變;`mktemp` 失敗或結果不是目錄時印出原因並以 1 結束;第 7 到 12 列的 26 個標籤與這一段的註解、標題改用現在的 Example 標題的用詞。驗證:測試全部通過;`TMPDIR` 指向不存在的目錄時測試以 1 結束,而且沒有任何一行訊息提到根目錄下的路徑。 +- [x] 3.2 [after: 3.1] 依 design「照條文改程式,不改條文去配合程式」與 Implementation Contract:`plugins/issue-driven-dev/CHANGELOG.md` 的 #548 條目兩處:條件的敘述寫明主 repo 自己的 git 目錄不算在工作目錄內;補一句 `submodule.recurse` 打開時答案會變的情況。驗證:`git diff` 對 CHANGELOG 只動 `[Unreleased]` 裡 #548 那一條;文字不含任何特定專案的名稱或本機路徑。 + +## 4. 收尾 + +- [x] 4.1 [after: 3.2] 依 Implementation Contract 驗收:`bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 與 `bash .claude/scripts/tests/spectra-archive-post-ic/test.sh` 結束碼都是 0;把 2.1 的判斷拿掉時只有第 55 列的檢查失敗;link 指向工作目錄內另一個 clone 時仍回 `ok`、指到頂層目錄之外時仍回 `error`;`python3 plugins/issue-driven-dev/scripts/spec-change.py links --base origin/main --cwd .` 的結果。驗證:驗收紀錄寫在這一項底下;封存之後的結果寫在 issue 的 Implementation Complete 留言。 + - 驗收紀錄。這個 change 的文件、規格差異、測試與程式都由同一個協調者撰寫,沒有實作者模型,也沒有獨立讀者;第六輪 verify 是第一次獨立審查。環境:macOS、git 2.55.0、Python 3.13.5。 + - 整套測試(`dd8d2b9`,封存之前):`bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 75 個 suite、0 個失敗、沒有逾時;`bash .claude/scripts/tests/spectra-archive-post-ic/test.sh` 141 項通過、0 項失敗。`bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 806 項通過、0 項失敗(第 55 列加了 7 項)。 + - 變異:在一份副本裡把 2.1 加的那個判斷拿掉,測試檔 802 項通過、4 項失敗,失敗的就是 1.1 記錄的那四項(第 55 列的 `status`、結束碼、原因、沒有在那個目錄執行 git)。 + - 三個 fixture,各用 4.1.0、修改前(`8003a7b`)、修改後的 script 跑一次,並記錄 git 呼叫。link 指進主 repo 的 `.git`:`missing`、`ok`(在那個目錄 5 次呼叫)、`error`(path leaves the repository,0 次)。link 指向工作目錄內的另一個 clone:`missing`、`ok`、`ok`(修改前後都是 5 次)。link 指到頂層目錄之外:`missing`、`error`、`error`(都是 0 次)。 + - 另外三種情況,修改前與修改後各跑一次。link 的目標寫成 `.GIT`(這個 volume 會折疊大小寫):修改前 `error`(not checked out,在那個目錄執行了 1 次 git),修改後 `error`(path leaves the repository,0 次)。git 目錄用 `--separate-git-dir` 放在頂層目錄內、取名 `gd`,link 指進它:修改前 `ok`(5 次),修改後 `error`(0 次)。主 repo 是 linked worktree、submodule 照一般方式取出:修改前後都 `ok`,在 submodule 裡都是 5 次呼叫,整次執行的呼叫從 18 次變成 19 次(多的那一次是問 git 目錄在哪裡);它的主 worktree 也一樣。 + - 暫存目錄:`TMPDIR` 指向不存在的目錄時,測試印出 mktemp 的錯誤與一行 FATAL,以 1 結束,共兩行,沒有任何一行提到根目錄下的路徑。 + - 連結檢查,封存之前(`python3 plugins/issue-driven-dev/scripts/spec-change.py links --base origin/main --cwd .`):`{"status": "ok", "missing": [], "reason": ""}`。封存之後的結果寫在 issue 的 Implementation Complete 留言。 + - 沒有做的:測試只在 macOS 上跑過;記錄的路徑離開頂層目錄再回到頂層目錄本身的那一種情況沒有處理(design 的 Risks,#559);外層 submodule 自己的 `.git` 真目錄那一種沒有實測。 diff --git a/openspec/changes/archive/2026-11-15-idd-548-fix6/.openspec.yaml b/openspec/changes/archive/2026-11-15-idd-548-fix6/.openspec.yaml new file mode 100644 index 00000000..171e1ddb --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-fix6/.openspec.yaml @@ -0,0 +1,6 @@ +schema: spec-driven +created: 2026-11-15 +created_by: che cheng <kiki830621@gmail.com> +created_with: claude +archived_by: che cheng <kiki830621@gmail.com> +archived_at: 2026-11-15 diff --git a/openspec/changes/archive/2026-11-15-idd-548-fix6/design.md b/openspec/changes/archive/2026-11-15-idd-548-fix6/design.md new file mode 100644 index 00000000..617a2204 --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-fix6/design.md @@ -0,0 +1,74 @@ +## Context + +第五輪之後的 change `idd-548-fix5` 讓 `links` 不搜尋落在主 repo git 目錄裡的 submodule 目錄,並在第 2 個條件補了一句。第六輪(留言 6891008905)的六席裡有四席各自找到那一句與程式不一致的配置,裁定為 2 項 blocking、1 項要在分支上修。共同的原因是那一句用一般的說法描述一個特定的比對。 + +維護者決定(留言 6891118023):修,條文改封閉列舉,再審一輪。 + +## Goals / Non-Goals + +**Goals** + +- 第 2 個條件只寫程式比對的內容,讓每一句都能對著程式逐字核對。 +- linked worktree 的配置下,repository 的 git 目錄也被比對。 +- 每一句邊界有一列 Example。 + +**Non-Goals** + +- 不新增被排除的目錄種類(submodule 自己的 git 目錄不排除)。 +- 不改頂層目錄本身也算的行為。 +- 不處理 #556 與 #559 裡的項目。 + +## Decisions + +### 條文寫比對的內容,不寫「工作目錄」 + +第五輪與第六輪的爭議都落在「工作目錄」這個詞:它可以讀成 git 的回報,也可以讀成頂層目錄底下的範圍,兩種讀法在邊界上答案不同。新的第 2 個條件不用這個詞,改寫兩件可以直接核對的事:解析後的目錄是頂層目錄或在它底下;它自己與它到頂層目錄之間的每一層,都不是清單上的兩個目錄之一。 + +### 清單只有兩個目錄,而且寫明是封閉的 + +兩個目錄是在主 repo 的頂層問 git 得到的:`git rev-parse --absolute-git-dir` 印的,與 `git rev-parse --git-common-dir` 印的。一般的 repository 兩者是同一個目錄;linked worktree 裡前者是這個 worktree 私有的目錄,後者是 repository 的 git 目錄。條文加一句「這份清單是封閉的」,避免之後有人依性質相似再推出第三類目錄。 + +替代做法:把「任何 repository 的 git 目錄」都排除(對每個外層 submodule 再問一次它的 git 目錄)。沒有採用:多一類目錄就多一段程式與一批邊界;這種目錄裡的 clone 要能寫這台機器上的 repository 才放得進去,而在那裡的 git 呼叫與在任何已取出的 submodule 裡的呼叫用的是同一層防護。這是協調者依維護者「照你的建議修」所做的選擇,寫在留言 6891118023,維護者可以推翻。 + +### 兩個目錄分兩次問,相對路徑接在頂層目錄後面 + +`--git-common-dir` 在一般的 repository 印的是相對路徑(`.git`),相對於執行 git 的目錄;程式是以 `-C <頂層目錄>` 執行,所以不是絕對路徑時接在頂層目錄後面。不用 `--path-format=absolute`:它在 git 2.31 之前不存在,而這兩次呼叫發生在 git 版本檢查之前。不把兩個選項放在同一次呼叫:輸出會是兩行,目錄名稱含換行時分不開;現有讀單一路徑的寫法(只去掉 git 加的那一個換行)對一次一個路徑才成立。 + +代價:要檢查 submodule 目錄的那次執行,在頂層多兩次 git 呼叫(上一個 change 是多一次)。標記都在主 repo 時一次都不多。 + +### 往上比對只到頂層目錄為止 + +比對從解析後的目錄開始,逐層往上,到頂層目錄的下一層為止;頂層目錄本身不比對。所以 git 目錄在頂層目錄之上(或就是頂層目錄)時,頂層目錄底下的目錄不因此被拒絕。這是第六輪第 3 列的裁定:那種配置下 git 把頂層目錄底下的目錄當成工作目錄,拒絕它們會讓那種 repository 的每個 submodule 都搜尋不了。條文把這一點寫成一句,並有一列。 + +### 解析後就是頂層目錄的路徑符合第 2 個條件 + +程式比的是「頂層目錄是不是共同的上層」,解析後等於頂層目錄也成立,而且這時沒有任何一層要比對。第五、六輪建了這種輸入的席位都讀成寫明的行為。封閉列舉必須說清楚頂層目錄本身算不算,所以條文寫明它算,並有一列。它要不要算,是 #559 的問題;這個 change 不改行為。 + +### 原因沿用 path leaves the repository + +與第 55 列相同,不新增原因文字。 + +## Implementation Contract + +- `openspec/specs/spec-on-every-issue/spec.md`(由封存套用):requirement「Added and modified requirements carry an executable check」的第 2 個條件整句換掉;「(6) its object store holds the recorded commit.」之後加一段三句;Example「markers in submodules」在第 55 列之後多第 56 到 59 列。其他句子與列逐字不變。 +- `plugins/issue-driven-dev/scripts/spec-change.py`:`main_git_directory()` 改成回傳兩個目錄(改名 `main_git_directories()`),`under_git_directory()` 改成比對兩個;`marker_files()` 裡那個判斷的呼叫與註解跟著改;檔頭 `links` 的說明兩行改寫。除此之外不改。 +- `plugins/issue-driven-dev/scripts/tests/spec-change/test.sh`:第 55 列之後新增第 56 到 59 列的 fixture 與檢查;第 55 列的註解改成新的說法。其他不動。 +- `plugins/issue-driven-dev/CHANGELOG.md`:只動 `[Unreleased]` 裡 #548 那一條講這個條件的那一句。 +- 驗證:第 56 列的檢查在改程式之前的 commit 上失敗、之後通過;第 57 到 59 列前後都通過;`tests/spec-change/test.sh` 全部通過;`run-all-tests.sh` 結束碼 0;`links --base origin/main` 回 `ok`;`archived` 回 pass。 + +## Risks / Trade-offs + +- 要檢查 submodule 目錄的執行在頂層多兩次 git 呼叫。 +- 這個 change 把兩個現有的行為寫成明文並各加一列:submodule 自己的 git 目錄裡的 clone 會被搜尋;記錄的路徑解析後是頂層目錄本身時,讀的是主 repo 自己的 commit。兩者要不要改,維護者之後可以另外決定;改的時候要連條文與那一列一起改。 +- git 答不出這兩個目錄,或印出讀不到的路徑時,整次執行以 `error` 結束,原因文字不在 requirement 裡(第六輪第 6 列,#559 第 18 點)。這個 change 多問一個目錄,這條路徑多一個入口,行為相同。 +- 呼叫端的環境帶著 `GIT_DIR` 或 `GIT_COMMON_DIR` 時,這兩次呼叫印的是那些變數指的目錄(第六輪第 7 列,#559 第 19 點)。這是主 repo 的呼叫本來就有的行為。 +- 測試只在 macOS 上跑過;第 56 與 58 列的 fixture 有守衛,配置建不出來時整個測試會停下並說明原因。 +- 這個 change 的條文、測試與程式都由協調者撰寫,沒有實作者模型,也沒有獨立讀者;第七輪 verify 是第一次獨立審查。 + +## Migration Plan + +不需要。沒有設定或資料要搬。 + +## Open Questions + +沒有。 diff --git a/openspec/changes/archive/2026-11-15-idd-548-fix6/proposal.md b/openspec/changes/archive/2026-11-15-idd-548-fix6/proposal.md new file mode 100644 index 00000000..9a59837d --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-fix6/proposal.md @@ -0,0 +1,55 @@ +**GitHub-side tracker**: #548 + +## Problem + +第六輪 verify(留言 6891008905)留下三列,三列都出在第五輪之後補進 requirement「Added and modified requirements carry an executable check」第 2 個條件的那一句:「主 repo 自己的 git 目錄,與它底下的一切,不屬於工作目錄」。那一句寫的是一個一般的說法,程式比對的是一個特定的目錄,兩者在三種配置下不一致。 + +- 第 1 列(HIGH):在 linked worktree 裡執行 `links`,而這個 worktree 的頂層目錄裡放著主 repo 時,放在主 repo 的 `.git` 底下的 clone 仍然被搜尋,並在那裡執行 git。 +- 第 2 列(HIGH):外層 submodule 自己的 `.git` 是真目錄時,指進那個 `.git` 的路徑被搜尋;條文沒有說這種目錄算不算。 +- 第 3 列(MEDIUM):主 repo 的 git 目錄在頂層目錄之上時,照那一句的字面每個 submodule 都該被拒絕,程式照常搜尋;裁定是條文錯、程式對。 + +維護者的決定(留言 6891118023):修;那一句改成封閉列舉;再審一輪。 + +## Root Cause + +- 程式只問了 `git rev-parse --absolute-git-dir`。在 linked worktree 裡它印的是這個 worktree 私有的目錄,repository 的 git 目錄是 `git rev-parse --git-common-dir` 印的那個,沒有被比對。 +- 條文用「工作目錄」與「git 目錄底下的一切」這兩個一般的說法來描述一個只比對特定目錄、而且只在頂層目錄以下比對的檢查。說法的字面範圍比檢查寬(第 3 列),也沒有說清楚其他 repository 的 git 目錄算不算(第 2 列)。 + +## Proposed Solution + +- 程式:在主 repo 的頂層問 git 兩個目錄,`--absolute-git-dir` 印的與 `--git-common-dir` 印的;submodule 的目錄,或它與頂層目錄之間的任何一層目錄,是兩者之一時,原因是 path leaves the repository,不在那裡執行 git。往上比對仍然只到頂層目錄為止。 +- 條文:第 2 個條件不再用「工作目錄」,改成只寫比對的內容:解析後的目錄是頂層目錄或在它底下;它自己與它到頂層目錄之間的每一層,都不是那兩個目錄之一。六個條件之後加一段,寫明這份兩個目錄的清單是封閉的,並點出三個邊界:submodule 自己的 git 目錄不在清單內;頂層目錄本身不拿來比對;解析後就是頂層目錄的路徑符合第 2 個條件。 +- Example「markers in submodules」加四列(第 56 到 59 列),一句邊界一列。第 56 列的測試在改程式之前失敗;第 57 到 59 列描述的是現有的行為,改之前與之後都通過。 +- `spec-change.py` 檔頭的說明、兩個函式的說明、`test.sh` 第 55 列的註解與 CHANGELOG 的 #548 條目,改成同樣的說法。 + +## Non-Goals + +- 不排除 submodule 自己的 git 目錄。維護者若要排除,是另一個 change。 +- 不改「頂層目錄本身也算」這個行為;它要不要算,仍在 #559。 +- 第六輪第 4 到 7 列(#556、#559)不在這裡處理,包括 git 答不出 git 目錄位置時的原因文字。 + +## Success Criteria + +- 第 56 列的檢查在改程式之前的 commit 上失敗(`status` 是 `ok`、在那個目錄有 git 呼叫),之後通過。 +- 第 57、58、59 列回 `ok`;第 55 列仍回 `error`、沒有呼叫。 +- 把新加的比對(common 目錄)拿掉時,只有第 56 列的檢查失敗。 +- `bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 全部通過;`bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 結束碼 0。 +- `spec-change.py links` 從預設分支到這條分支的 HEAD 回 `ok`;`archived` 回 pass。 + +## Capabilities + +### New Capabilities + +(none) + +### Modified Capabilities + +- `spec-on-every-issue`: requirement「Added and modified requirements carry an executable check」的第 2 個條件改寫為封閉列舉,六個條件之後加一段;Example「markers in submodules」加第 56 到 59 列。 + +## Impact + +- Affected specs: spec-on-every-issue(一個 MODIFIED requirement) +- Affected code: + - Modified: plugins/issue-driven-dev/scripts/spec-change.py + - Modified: plugins/issue-driven-dev/scripts/tests/spec-change/test.sh + - Modified: plugins/issue-driven-dev/CHANGELOG.md diff --git a/openspec/changes/archive/2026-11-15-idd-548-fix6/specs/spec-on-every-issue/spec.md b/openspec/changes/archive/2026-11-15-idd-548-fix6/specs/spec-on-every-issue/spec.md new file mode 100644 index 00000000..0fecdf51 --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-fix6/specs/spec-on-every-issue/spec.md @@ -0,0 +1,119 @@ +## MODIFIED Requirements + +### Requirement: Added and modified requirements carry an executable check + +`scripts/spec-change.py links --base <rev>` SHALL compare the files under `openspec/specs/` at `<rev>` and at `--head` (default `HEAD`). For every requirement that is new or whose text differs between the two, it SHALL require one of two things: at least one `##### Example:` under the requirement, where each such Example has a title that is unique within its capability and a tracked file at the head revision, outside `openspec/` and not ending in `.md`, that contains the marker `spec-example: <capability> / <Example title>` (a tracked file of a submodule counts, as the paragraph "Submodules" below describes); or a line under the requirement that starts with `No executable check:` followed by a reason. A requirement that does not differ SHALL NOT be checked. A marker counts only when nothing but whitespace, or the comment closer `-->` or `*/`, follows the Example title on its line. Lines inside a code fence are not read as `##### Example:` or `No executable check:` lines; a fence opened by three or more backticks or tildes, at any indentation (as inside a list item), closes only on a line of the same character, at least as long, with nothing but whitespace after it; lines end only at `\n`, `\r\n` or `\r`. A requirement heading indented by up to three spaces SHALL be read as a requirement, as Spectra reads it. Paths SHALL be read as git stores them, never in git's quoted form, so a capability whose directory name is not ASCII is checked like any other. Two requirements with the same name in one capability SHALL make the command print `error`. So SHALL a code fence at the head revision that never closes, since the requirements after it would go unchecked. Outside code fences, a heading that starts with `### Requirement` but does not have the form `### Requirement: <name>` with a non-empty name SHALL make the command print `error`, and so SHALL a head revision at which the spec directory's `specs/` holds no tracked file, and a path under the spec directory's `specs/` that is not valid UTF-8 (the reason says so and carries no text of an exception). Such a path elsewhere under the spec directory does not change the answer. The command SHALL print one JSON line with `status` (`ok`, `missing` or `error`) and a list naming each requirement or Example that lacks its check, and SHALL exit 0, 1 or 2 in that order. `--base` is required: the caller names the range, so that a run on the default branch is checked against the commit it started from. The marker ties an Example to a test by name only; whether the test exercises what the Example states is judged by the reviewers of `idd-verify`. + +Submodules. The tracked files at the head revision include the tracked files of every submodule of the repository at the commit that the head revision records for it, and in the same way the files of a submodule of a submodule. The command SHALL read that recorded commit, not the commit the submodule's working tree is on. It SHALL find the submodules itself, from the entries of the head revision's tree that record a commit; it SHALL NOT rely on git's own recursion into submodules, which passes over a submodule that is not checked out without saying so; the answer SHALL be the same whether or not the git configuration turns that recursion on (`submodule.recurse`). A file of a submodule is named by the submodule's path followed by the file's path, and the two exclusions (under the spec directory, ending in `.md`) apply to that name. A submodule whose own path is under the spec directory SHALL NOT be searched and SHALL NOT count as one that could not be searched: none of its files could count. + +Order of the search. For each Example the command SHALL search the main repository first. When the marker is found there, the Example has its check and the command SHALL NOT run git in any submodule for it, so for a repository whose markers are all in its own files no entry that records a commit is listed and no submodule is examined, whatever its head revision records. Only when the marker is not found in the main repository are the submodules searched, and a marker found in one submodule settles the Example whatever the state of the others. When the marker of an Example is found, the Example has its check, whether or not every submodule could be searched. The submodules inside a submodule are read from a listing of every tree of its recorded commit, and that listing is made only when the outer one meets its own six conditions. Each of them is then searched whenever its own six conditions hold, also when the search of the outer one failed. When the listing fails, because a tree of the recorded commit cannot be read, the submodules inside it are unknown, even when the top tree shows them. + +Which submodules can be searched. A submodule SHALL be searched only when all six of these hold: (1) its path, as the tree records it, is relative and has no empty, `.` or `..` component; (2) its directory, after symbolic links are resolved, is the top directory of the main repository or lies under it, and neither that directory nor any directory between it and the top directory is one of two directories, the one that `git rev-parse --absolute-git-dir` prints and the one that `git rev-parse --git-common-dir` prints when run at the top directory (in a linked worktree these are two different directories; directories are compared, not names); (3) the directory itself is not a symbolic link; (4) the directory holds an entry named `.git` of its own; (5) git, run in the directory, reports it as the top of its own working tree; (6) its object store holds the recorded commit. The two directories of condition 2 are a closed list: no other directory is refused under that condition. The git directory of a submodule is not on the list, so a directory inside it is searched when the six conditions hold. The top directory is not compared with the two, so when the top directory itself lies inside one of them, the directories under it are not refused for that reason. A directory that resolves to the top directory itself meets condition 2. The command SHALL NOT run git in a directory that fails any of the first four: a directory of ordinary tracked files can be shaped like a git directory, and git would read, and act on, the configuration it holds. Nor SHALL it run git in the directory of any submodule when git is older than 2.45, the first version that honours `GIT_NO_LAZY_FETCH`, or when the version cannot be read: a submodule for which the first four hold then counts as one that could not be searched. In the directory of a submodule the command SHALL run git with `safe.bareRepository` set to `explicit`, with lazy fetching turned off (`GIT_NO_LAZY_FETCH=1`), and with the variables `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, `GIT_OBJECT_DIRECTORY`, `GIT_ALTERNATE_OBJECT_DIRECTORIES` and `GIT_COMMON_DIR` removed from the environment it inherited. Before it searches a submodule the command SHALL ask git which objects of the recorded commit (its trees and the contents of its files) the object store lacks or cannot open, without fetching any: an object whose file is present but cannot be opened (for example an empty file) counts as lacking. A submodule is searched even when some are lacking, and a file that counts, found by a search that ran to its end (exit code 0 or 1), settles the Example. What a search printed before it ended with another exit code SHALL NOT be used, so that the answer for one state of the repository is the same on every run. When no file that counts is found in it, the submodule counts as one that could not be searched if its object store lacks an object of the recorded commit, if the search exits with a code other than 0 or 1, or if the trees of the recorded commit cannot all be listed. What git writes to its error stream SHALL NOT change whether a submodule counts as searched, nor the reason reported for it. In the main repository a search that exits with a code other than 0 or 1 is `error`, as before; its reason is `git grep failed: ` followed by the first 200 characters of what git wrote to its error stream, also as before. + +What is reported. When the marker is not found and every submodule was searched, the Example is reported as lacking its check, as before. When it is not found and at least one submodule could not be searched, the command SHALL print `error` and name the first such Example it meets, the submodules that could not be searched and the reason for each: an Example whose candidate files were not all read is not reported as lacking its check. The submodules are named by path, in the order of their paths and joined by `; `; a submodule of a submodule is named by its path under the outer one; when more than five could not be searched, the first five are named and the number of the others is stated; a path longer than 200 characters is cut to its first 200 followed by `...`. The reason is one of six: the path leaves the repository (conditions 1 and 2); the submodule is not checked out (conditions 3 and 4, or git names another directory as the top); git is older than 2.45 (stated also when its version cannot be read); git refused to open it (the git command of condition 5 fails); the recorded commit is not in its object store (condition 6); the recorded commit could not be read (its object store lacks or cannot open an object of it, or the search or the listing of its trees failed). The reason given for a submodule SHALL NOT carry text from git's error stream. The path of a submodule that is not valid UTF-8 is handled like any other path, and the command still prints one JSON line. A repository whose head revision records no submodule is searched in its own tracked files only: none of the rules for submodules changes its answer. + +#### Scenario: An Example without a test is reported + +- **GIVEN** a range that adds a requirement with one Example titled `status by exit code` to the capability `local-ci-gate` +- **AND** no tracked file outside `openspec/` contains `spec-example: local-ci-gate / status by exit code` +- **WHEN** `spec-change.py links` runs on that range +- **THEN** it prints `status` `missing`, names that Example, and exits 1 + +##### Example: what the link check reports + +| Requirement in the range | Examples | Marker at the head revision | `No executable check:` line | `status` | +| --- | --- | --- | --- | --- | +| added | one | in `scripts/tests/x/test.sh` | absent | `ok` | +| added | one | absent | absent | `missing` | +| added | one | only in a file under `openspec/` | absent | `missing` | +| added | one | only in a file ending in `.md` | absent | `missing` | +| added | none | not applicable | absent | `missing` | +| added | none | not applicable | present, with a reason | `ok` | +| added | none | not applicable | present, with nothing after the colon | `missing` | +| added | one, with no title | not applicable | absent | `missing` | +| added | two with the same title as an Example elsewhere in the capability | present | absent | `missing` | +| changed | two | present for one, absent for the other | absent | `missing` | +| unchanged, with no Example | none | not applicable | absent | `ok` | +| removed in the range | not applicable | not applicable | not applicable | `ok` | +| no file under `openspec/specs/` differs | not applicable | not applicable | not applicable | `ok` | +| added | one | only a marker naming a longer title that starts with this one | absent | `missing` | +| added, under the heading `### Requirement Missing colon` | not applicable | not applicable | not applicable | `error` | +| any; `openspec/specs/` holds no tracked file at the head revision | not applicable | not applicable | not applicable | `error` | +| added, its only `##### Example:` line inside a code fence | none outside fences | not applicable | absent | `missing` | +| added, its only `No executable check:` line inside a code fence | none | not applicable | only inside a fence | `missing` | +| added, after a fence of four backticks that a line of three backticks does not close | its Example inside that fence | not applicable | absent | `missing` | +| added, under the heading ` ### Requirement: Alpha` (two leading spaces) | none | not applicable | absent | `missing` | +| added, its only `No executable check:` line inside a fence indented four spaces in a list item | none | not applicable | only inside that fence | `missing` | +| added, in a capability whose directory name is not ASCII (`中文能力`) | none | not applicable | absent | `missing` | +| added, in a capability whose directory name holds a double quote (`quo"te`) | none | not applicable | absent | `missing` | +| added, in a capability whose directory name is not valid UTF-8 | not applicable | not applicable | not applicable | `error`, with a reason that says so | +| added; a tracked path under the spec directory but outside `specs/` is not valid UTF-8 | one | in `scripts/tests/x/test.sh` | absent | `ok` | +| added; a tree of the head revision outside the spec directory cannot be read | one | absent | absent | `error`; the reason is `git grep failed: ` followed by the first 200 characters of what git wrote to its error stream | +| added twice with the same name in one capability | not applicable | not applicable | not applicable | `error` | +| any, after a code fence that never closes | not applicable | not applicable | not applicable | `error` | +| `--base` names a revision that does not exist | not applicable | not applicable | not applicable | `error` | +| `--base` is not given | not applicable | not applicable | not applicable | usage error, exit 64 | + +##### Example: markers in submodules + +| Where the marker of the Example is at the head revision | Submodules recorded at the head revision | `status` | +| --- | --- | --- | +| in a tracked file of a submodule, at the commit the head revision records | one, checked out | `ok` | +| in a tracked file of a submodule of a submodule | both checked out | `ok` | +| in a tracked file of a submodule whose path holds a space | one, checked out | `ok` | +| only in the recorded commit of a submodule whose working tree is on a later commit without it | one, checked out | `ok` | +| only in a later commit of a submodule, which its working tree is on, not in the recorded commit | one, checked out | `missing` | +| only in a file of a submodule that ends in `.md` | one, checked out | `missing` | +| nowhere | one, checked out | `missing` | +| nowhere in the main repository | one, not checked out | `error`, naming the Example and the submodule's path | +| in a tracked file of the main repository | one, not checked out | `ok` | +| nowhere in the main repository | one, checked out, whose object store lacks the recorded commit | `error`, naming the Example and the submodule's path | +| in a tracked file of the main repository | one, checked out, whose object store lacks the recorded commit; `submodule.recurse` is true in the repository's git configuration | `ok` | +| nowhere in the main repository | one, checked out, whose object store lacks the recorded commit; `submodule.recurse` is true in the repository's git configuration | `error`, naming the Example and the submodule's path | +| only in the recorded commits of two submodules | two, neither checked out | `error`, naming the Example and both paths, joined by `; ` | +| only in a submodule of a submodule | the outer one checked out, the inner one not | `error`, naming the Example and the inner submodule by its path under the outer one | +| only in a tracked file of a submodule that is mounted under `openspec/` | one, checked out | `missing` | +| in a tracked file of the main repository | one whose path is not valid UTF-8, not checked out | `ok` | +| nowhere | one whose path is not valid UTF-8, not checked out | `error` on one JSON line, exit 2 | +| in a tracked file of the main repository | one, checked out, holding the recorded commit but not the tree of that commit | `ok` | +| nowhere in the main repository | one, checked out, holding the recorded commit but not the tree of that commit | `error`, naming the Example and the submodule's path, with no text from git's error stream | +| nowhere | one, checked out, whose object store lacks the content of one file of the recorded commit | `error`, naming the Example and the submodule's path, with no text from git's error stream | +| nowhere | one, checked out, whose recorded commit records a second submodule; at that second path the working tree holds ordinary files shaped like a git directory (`HEAD`, `config`, `objects/`, `refs/`) and no `.git` entry, and that `config` names a command to run | `error`, naming the second path as not checked out; the command named in that `config` does not run | +| in a tracked file of the main repository | the same two, with the same files at the second path | `ok`; no git command runs in the directory of a submodule, and the command named in that `config` does not run | +| only in a repository outside the main repository, at a path with a `..` component that the head revision's tree records as a submodule | that one | `error`, naming the path as one that leaves the repository; the same answer when nothing is at that outside path | +| only in a repository outside the main repository, reached through a symbolic link in the working tree that is part of a recorded submodule path | that one | `error`, naming the path as one that leaves the repository | +| in a tracked file of a submodule whose path ends in a space | one, checked out | `ok` | +| nowhere | one, not checked out, mounted under `openspec/` | `missing` | +| only in a tracked file of a submodule | one, checked out elsewhere inside the working tree of the main repository, whose own directory is a symbolic link to that checkout | `error`, naming the Example and the submodule's path as not checked out | +| in a tracked file of a submodule | one, checked out; the variable `GIT_DIR` is set to the git directory of the main repository | `ok` | +| only in the recorded commits of seven submodules | seven, none checked out | `error`, naming the Example, the first five paths in order and the number of the other two | +| nowhere | one whose directory holds a `.git` entry that git cannot open | `error`, naming the Example and the submodule's path as one git refused to open | +| nowhere | one whose directory holds an empty `.git` directory and, beside it, ordinary files shaped like a git directory (`HEAD`, `config`, `objects/`, `refs/`) whose `config` names a command to run | `error`, naming the submodule's path as one git refused to open; the command named in that `config` does not run | +| in a tracked file of the main repository | one, checked out as a partial clone that never fetched the file contents of the recorded commit | `ok`; nothing is fetched into the submodule | +| nowhere | one, checked out as a partial clone that never fetched the file contents of the recorded commit | `error`, naming the Example and the submodule's path; nothing is fetched into the submodule | +| nowhere | one, not checked out, whose path is longer than 200 characters | `error`, naming the first 200 characters of the path followed by `...` | +| in a tracked file of one submodule | two; the one with the marker checked out, the other not | `ok` | +| only in a file ending in `.md` of a submodule | one, checked out, whose object store lacks the content of another file of the recorded commit | `error`, naming the Example and the submodule's path | +| only in a tracked file of a submodule | one whose `.git` entry git opens, with the working tree of that git directory set to the parent directory, so that git names the parent as the top | `error`, naming the Example and the submodule's path as not checked out | +| only in a submodule of a submodule | three recorded paths: `a`, checked out; its own submodule `a/inner`, not checked out; and `a-b`, not checked out | `error`, naming `a-b` before `a/inner` | +| nowhere | one, at a path with a `.` component that the head revision's tree records | `error`, naming the path as one that leaves the repository | +| in a tracked file of a submodule | one, checked out; the six variables named above are all set to the git directory, working tree, index and object store of the main repository | `ok` | +| only in the recorded commit of a submodule, which the checked-out submodule's own object store lacks | one, checked out; the variable `GIT_ALTERNATE_OBJECT_DIRECTORIES` names an object store that holds that commit | `error`, naming the Example and the submodule's path, with the recorded commit as not in its object store | +| only in a submodule of a submodule, checked out and complete | the outer one checked out, its object store lacking the content of one unrelated file of its recorded commit | `ok` | +| nowhere | the same two | `error`, naming the Example and the outer submodule's path only, with its recorded commit as one that could not be read | +| in a tracked file of one submodule | two; the other one is not checked out and comes first in the order of the paths | `ok` | +| in a tracked file that counts, of a submodule whose object store lacks the content of another file of the recorded commit | one, checked out | `ok` | +| nowhere | one, checked out, holding every object of the recorded commit; git writes to its error stream during the search (`GIT_TRACE=1`) | `missing` | +| only in a tracked file of a submodule | one, checked out; git reports a version older than 2.45, or one that cannot be read | `error`, naming the Example and the submodule's path with git as older than 2.45; no git command runs in the directory of the submodule | +| in a tracked file of the main repository | one, checked out; git reports a version older than 2.45 | `ok` | +| nowhere | one, checked out, whose object store holds a damaged copy of the content of one file of the recorded commit (the object file is present and is not a compressed object, so the search ends with exit code 128) | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read | +| only in a tracked file of a submodule; the object that holds the content of that file is present but empty (zero bytes), so the search skips the file and ends with exit code 0 or 1 | one, checked out | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read | +| nowhere | one, checked out, holding every object of the recorded commit; one of its tracked files has a name with a carriage return followed by `?` | `missing` | +| in a tracked file of a submodule | one, checked out, whose object store holds a damaged copy of the content of another file, so that the search ends with exit code 128 | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read; the same answer on each of three runs | +| only in a submodule of a submodule, checked out and complete | the outer one checked out, its object store lacking a tree below the top of its recorded commit | `error`, naming the Example and the outer submodule's path only, with its recorded commit as one that could not be read | +| nowhere | one, checked out; the object that holds the content of one file is damaged in its body, so that git lists it and opens it, and the search ends with exit code 128 | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read | +| only in a repository placed inside the git directory of the main repository, reached through a symbolic link in the working tree that is part of a recorded submodule path | that one | `error`, naming the path as one that leaves the repository; git is not run in that directory | +| only in a repository placed inside the git directory of the main repository; the command runs in a linked worktree whose top directory holds the main repository, and a symbolic link in that worktree that is part of a recorded submodule path leads into that git directory | that one | `error`, naming the path as one that leaves the repository; git is not run in that directory | +| only in a repository placed inside the git directory of a submodule whose `.git` entry is a directory, reached through a symbolic link in that submodule that is part of a submodule path its recorded commit records | the outer one, checked out, and that one | `ok` | +| in a tracked file of a submodule | one, checked out; the git directory of the main repository was made apart from its working tree and the top directory lies inside it | `ok` | +| only in an earlier commit of the main repository, which the head revision records as a submodule at a path that a symbolic link in the working tree leads back to the top directory | that one | `ok` | diff --git a/openspec/changes/archive/2026-11-15-idd-548-fix6/tasks.md b/openspec/changes/archive/2026-11-15-idd-548-fix6/tasks.md new file mode 100644 index 00000000..612a2fed --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-fix6/tasks.md @@ -0,0 +1,26 @@ +## 1. 測試先寫 + +- [x] 1.1 依 design「清單只有兩個目錄,而且寫明是封閉的」「往上比對只到頂層目錄為止」「解析後就是頂層目錄的路徑符合第 2 個條件」,為 requirement「Added and modified requirements carry an executable check」的 Example「markers in submodules」第 56 到 59 列寫 fixture 與檢查,加在 `plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 第 55 列的檢查之後。第 56 列:linked worktree 的頂層目錄裡放著主 repo,link 指進主 repo 的 git 目錄裡人工放的 clone;fixture 先確認 git 在頂層印的兩個目錄不同、放 clone 的位置在 git 目錄內;檢查 `status` 是 `error`、結束碼 2、原因點名路徑與 path leaves the repository、記錄 git 呼叫的程式沒有看到任何一次在那個目錄的呼叫。第 57 列:外層 submodule 的 `.git` 是真目錄,link 指進它;檢查回 `ok`。第 58 列:頂層目錄在主 repo 的 git 目錄裡面,submodule 照一般方式取出;fixture 先確認 git 在頂層同時回報在工作目錄內與在 git 目錄內;檢查回 `ok`。第 59 列:記錄的路徑經過 link 回到頂層目錄本身,記錄的是主 repo 較早、有標記的 commit;檢查回 `ok`。驗證:這時 script 還沒改,`bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 只有第 56 列的檢查失敗;失敗的檢查名稱記在這一項底下。 + - 紀錄(script 未改,git 2.55.0、macOS):821 項通過、4 項失敗,四項都是第 56 列:`links: submodule row 56: linked worktree that holds the main repository — status`(要 `error`,得到 `ok`)、同名的 `— exit`(要 2,得到 0)、`links: submodule row 56 — reason names Example and path`、`links: submodule row 56 — no git command ran in the planted directory`。第 57、58、59 列與第 56 列的另外三項(回報的項目數、只有一行 JSON、記錄 git 呼叫的程式看到 worktree)通過。 + +## 2. 程式 + +- [x] 2.1 [after: 1.1] 依 design「兩個目錄分兩次問,相對路徑接在頂層目錄後面」「往上比對只到頂層目錄為止」與 Implementation Contract:`plugins/issue-driven-dev/scripts/spec-change.py` 在主 repo 的頂層問 `--absolute-git-dir` 與 `--git-common-dir`,解析後的目錄或它到頂層目錄之間的任何一層是兩者之一時,原因是 path leaves the repository,不呼叫 `submodule_git()`;檔頭與函式的說明改成同樣的說法。驗證:`bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 全部通過、0 項失敗;標記在主 repo 的 repo,git 呼叫的次數與修改前相同(第 22 列既有的檢查)。 + +## 3. 文字 + +- [x] 3.1 [after: 2.1] 依 design「條文寫比對的內容,不寫『工作目錄』」與 Implementation Contract:`plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 第 55 列的註解,與 `plugins/issue-driven-dev/CHANGELOG.md` 的 #548 條目講這個條件的那一句,改成新的說法。驗證:`git diff` 對 CHANGELOG 只動 `[Unreleased]` 裡 #548 那一條;文字不含任何特定專案的名稱或本機路徑;測試仍然全部通過。 + +## 4. 收尾 + +- [x] 4.1 [after: 3.1] 依 Implementation Contract 驗收:`bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 與 `bash .claude/scripts/tests/spectra-archive-post-ic/test.sh` 結束碼都是 0;把 2.1 新加的比對(common 目錄)拿掉時只有第 56 列的檢查失敗;第 55 列仍回 `error`;一般的 linked worktree(主 repo 在旁邊)裡照一般方式取出的 submodule 仍回 `ok`;`python3 plugins/issue-driven-dev/scripts/spec-change.py links --base origin/main --cwd .` 的結果。驗證:驗收紀錄寫在這一項底下;封存之後的結果寫在 issue 的 Implementation Complete 留言。 + - 驗收紀錄。這個 change 的文件、規格差異、測試與程式都由同一個協調者撰寫,沒有實作者模型,也沒有獨立讀者;第七輪 verify 是第一次獨立審查。環境:macOS、git 2.55.0、Python 3.13.5。 + - 整套測試,封存之前跑了兩次。在 `4af6539`(下一點的補充之前):`bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 75 個 suite、0 個失敗、沒有逾時,結束碼 0;`bash .claude/scripts/tests/spectra-archive-post-ic/test.sh` 141 項通過、0 項失敗;測試檔 825 項通過。在 `6f91370`:75 個 suite、1 個失敗、沒有逾時,結束碼 1;失敗的是 `idd-edit` 這個 suite 的第 21 個 fixture(mock-requires-test-mode),其餘 36 項通過。緊接著單獨跑 `tests/idd-edit/test.sh`,37 項全過。這個 suite 與這次改的兩個檔案無關;那一次整套執行時,同一台機器上另一個工作階段也在跑同一支 runner,而 runner 的每個 suite 輸出都寫到 `/tmp` 下固定的檔名,所以那一項失敗當時的輸出已被蓋掉,原因沒有查出來。`spectra-archive-post-ic` 在 `6f91370` 是 141 項通過、0 項失敗;`tests/spec-change/test.sh` 840 項通過、0 項失敗。結束碼為 0 的整套執行在封存之後的 HEAD 上補跑,結果寫在 issue 的 Implementation Complete 留言。 + - 封存之前補的兩個 commit(測試在前)。`20048d8`:以第 56 列的輸入加一項檢查,用一個對 `rev-parse --git-common-dir` 什麼都不印的 git 替身,`links` 必須回 `error`、不在放進去的目錄執行 git;另外第 57、58、59 列各加一項,從 git 呼叫紀錄確認搜尋的是該列描述的目錄,第 57 列加一個拿掉 clone 的對照(回 `error`、not checked out)。在這個 commit 上測試檔 837 項通過、3 項失敗,失敗的是新檢查的 `status`、結束碼、「沒有在那個目錄執行 git」:2.1 把 git 的答案接在頂層目錄後面,空白的答案就變成頂層目錄,而頂層目錄不比對。`6f91370`:空白的答案讓整次執行以 `error` 結束(原因與讀不到 git 目錄時相同)。第六輪的 script 遇到空白答案也是回這個 `error`;真的 git 不會在這裡印空白。這一項沒有對應的 Example 列,原因文字是 #559 第 18 點已記錄、requirement 沒有列的那一句。 + - 變異,各在一份副本裡改 `6f91370` 的 script 一處。(a) 只問 `--absolute-git-dir`:第 56 列的四項與「git 不回答 common 目錄」的四項失敗,其他都過。(b) 把呼叫 `under_git_directory()` 的那個判斷換成 `False`:第 55、56 列各四項與「git 不回答 common 目錄」的四項失敗。(c) 讓往上比對越過頂層目錄:只有第 58 列的三項失敗。(d) 拿掉空白答案的兩行:就是 `20048d8` 的狀態,失敗的是上一點的三項。 + - linked worktree 的頂層目錄裡放著主 repo 的配置(第六輪第 1 列),各用 4.1.0、第五輪的 script、第六輪的 script、`6f91370` 的 script 跑,並記錄 git 呼叫。link 指進主 repo 的 `.git`:`missing`、`ok`、`ok`、`error`(path leaves the repository);在放進去的目錄的 git 呼叫是 0、5、5、0 次。記錄的路徑直接寫成 `main/.git/…`:同樣的四個答案與呼叫次數。對照(同一個配置下照一般方式取出的 submodule,以及 worktree 在主 repo 旁邊時):`missing`、`ok`、`ok`、`ok`,後三者在 submodule 裡都是 5 次呼叫。 + - git 對 common 目錄的回答是相對路徑的情形(一般的 repository 印 `.git`):process 的目錄分別是該 repository、不是 repository 的目錄、另一個 repository、根目錄,`--cwd` 指向該 repository。一般取出的 submodule 四次都回 `ok`,第 55 列的輸入四次都回 `error`。 + - git 呼叫次數(一個 repository、一個取出的 submodule):第六輪的 script 19 次,`6f91370` 20 次,多的一次是 `rev-parse --git-common-dir`;標記在主 repo 時兩者都是 11 次,兩個問題都沒有問。 + - 其他地方的同一句話:script 開頭的說明、兩個函式的 docstring(`8e5e0c1`)、測試檔第 55 列的註解與 CHANGELOG 的 #548 條目(`4af6539`)都改成封閉列舉的寫法。封存目錄以外搜尋 `working tree of the main`、`own git directory`、`no part of`、`main working tree`:剩下的都是描述輸入放在哪裡的 Example 列(第 30、33、55 列)、別的 requirement(archive-ref、tree lock)與別的測試檔,沒有一句再把第 2 個條件說成「工作目錄之內」。 + - 連結檢查,封存之前(`python3 plugins/issue-driven-dev/scripts/spec-change.py links --base origin/main --cwd .`):`{"status": "ok", "missing": [], "reason": ""}`。封存之後的結果寫在 issue 的 Implementation Complete 留言。 + - 沒有做的:測試只在 macOS 上跑過;第六輪第 4 到 7 列沒有在這條分支上改(#556、#559);submodule 自己的 git 目錄不排除、解析後等於頂層目錄的路徑照樣接受,這兩件事是協調者在維護者的指示(留言 6891118023)下選的,寫進 requirement 與第 57、59 列,要不要這樣由第七輪的裁定席與維護者決定。 diff --git a/openspec/changes/archive/2026-11-15-idd-548-fix7/.openspec.yaml b/openspec/changes/archive/2026-11-15-idd-548-fix7/.openspec.yaml new file mode 100644 index 00000000..d5aa768d --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-fix7/.openspec.yaml @@ -0,0 +1,5 @@ +schema: spec-driven +created: 2026-11-15 +created_by: che cheng <kiki830621@gmail.com> +archived_by: che cheng <kiki830621@gmail.com> +archived_at: 2026-11-15 diff --git a/openspec/changes/archive/2026-11-15-idd-548-fix7/design.md b/openspec/changes/archive/2026-11-15-idd-548-fix7/design.md new file mode 100644 index 00000000..f58c1690 --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-fix7/design.md @@ -0,0 +1,121 @@ +## Context + +第七輪 verify(留言 6893428419)確認 `idd-548-fix6` 解決了第六輪的三列,另外找到一個更早就有的缺陷,落在兩行:`marker_files()` 用解析後的路徑字串判斷 submodule 的目錄在不在頂層目錄底下(第 2 個條件的前半),也用字串相等判斷 git 回報的頂層是不是那個目錄(第 5 個條件)。同一個目錄有兩種拼法時,兩行都答錯,方向都是保守的(回 `error`)。同一輪還有兩項條文字面的問題(第 3、4 列)。 + +維護者決定(留言 6894347661):改程式,再審一輪。 + +協調者在動手之前重現了兩項(第七輪報告已記): + +- 上游把放 submodule 的目錄只改大小寫,本機在不分大小寫的磁碟上 `git pull --recurse-submodules` 之後,`links` 回 `error`,原因是 not checked out;git 在那個目錄回報的頂層是磁碟上的名稱(`Tests/sub`),樹裡記的是 `tests/sub`。 +- link 的目標把頂層目錄寫成另一種大小寫,或寫成 macOS 上同一個磁碟的另一種絕對路徑(前面加 `/System/Volumes/Data`)時,`links` 回 `error`,原因是 path leaves the repository;link 用 git 的拼法時回 `ok`。 + +## Goals / Non-Goals + +**Goals** + +- 第 2 個條件與第 5 個條件都比對目錄,不比對名稱。 +- 條文對「在頂層目錄底下」與「同一個目錄」各給一個可以對著程式核對的說法。 +- 兩種拼法指同一個目錄的輸入,有 Example 的列與測試。 +- 實際落在規格目錄裡的 submodule 不搜尋,不論它的路徑叫什麼。 +- 修掉第七輪第 3、4 列的兩句字面。 + +**Non-Goals** + +- 不改主 repo 自己的搜尋,不改其他 subcommand。 +- 不改主 repo 自己的檔案的排除與 `.md` 的排除(照樹裡記的名稱比對),見下面「仍然照名稱比對的地方」。 +- 不新增被排除的目錄種類,不改「解析後等於頂層目錄的路徑照樣接受」。 +- 不處理 #556、#559 的其他項目。 + +## Decisions + +### 「在頂層目錄底下」的意思是往上走會遇到頂層目錄 + +`os.path.realpath` 解析 symbolic link,但留下路徑原本的拼法;`os.path.commonpath` 比的是字串。新的做法從解析後的目錄開始,逐層取上一層目錄,每一層用 `os.stat` 與頂層目錄比對裝置與 inode(`os.path.samestat`)。遇到頂層目錄就停,條件的前半成立;走到檔案系統的根還沒遇到,原因是 path leaves the repository。 + +條文照這個做法寫:「going from the resolved directory to its parent directory, to the parent of that one, and so on, the top directory is met」。這句話的每一個詞都對得上一行程式,沒有另外的「在底下」的定義。 + +### 往上走經過的目錄,就是與那兩個 git 目錄比對的清單 + +`under_git_directory()` 原本自己往上走,用字串長度決定何時停(`len(current) > len(real_top)`);解析後的路徑與頂層目錄拼法不同時,這個停止條件沒有意義。新的做法只走一次:`directories_below_top()` 回傳遇到頂層目錄之前經過的每一個目錄(解析後的目錄自己,除非它就是頂層目錄;以及兩者之間的每一層),`under_git_directory()` 只比對這份清單。頂層目錄不在清單裡,所以永遠不會被拿去比對,與 `idd-548-fix6` 的決定相同。 + +git 的兩個問題(`--absolute-git-dir`、`--git-common-dir`)仍然只在頂層目錄被遇到之後才問,次序與呼叫次數不變。 + +### 第 5 個條件用同一種比對 + +git 在 submodule 的目錄回報的頂層,與那個目錄,用 `os.path.samefile` 比對。git 印的是磁碟上的名稱;樹裡記的路徑、或 link 的目標,可以是同一個目錄的另一種拼法。 + +### 檢查不到的目錄略過 + +往上走時,`os.stat` 失敗的那一層(例如不存在)不是頂層目錄,也不是那兩個目錄之一,繼續往上。沒有取出的 submodule(目錄不存在)因此仍然通過第 2 個條件,由第 3、4 個條件回報 not checked out,與修改前相同。條文加一句說明這一點。第 5 個條件比對時,任一邊檢查不到就當作不是同一個目錄(not checked out)。 + +### 條文的三句(第七輪第 3、4 列) + +- 第 2 個條件的子句改成「解析後的目錄自己,除非它就是頂層目錄,以及兩者之間的每一層」,不再與「解析後等於頂層目錄的路徑符合第 2 個條件」那一句相反。 +- 「submodule 的 git 目錄不在清單上,所以裡面的目錄會被搜尋」改成:不另外把任何 submodule 的 git 目錄加進清單;它正好是那兩個目錄之一、或在其中之一底下時,第 2 個條件照寫的適用,否則裡面的目錄在六個條件成立時會被搜尋。 +- 「頂層目錄不與那兩個目錄比對,所以頂層目錄在其中之一裡面時」補上「就是其中之一」的情形。 + +### 落在規格目錄裡的 submodule 不搜尋,不論路徑叫什麼 + +條文原本只寫「路徑在規格目錄底下的 submodule 不搜尋」,程式比的是樹裡記的名稱(`(prefix + path).startswith(sd + "/")`)。Example 第 15 列的說法是「mounted under `openspec/`」。名稱不在 `openspec/` 底下、目錄卻落在規格目錄裡的 submodule 有兩個形狀,動手之前各用三份 script 量過(git 2.55.0、不分大小寫的 APFS): + +| 輸入 | 4.1.0 | 第七輪的 script | 只改第 2、5 個條件之後 | +| --- | --- | --- | --- | +| gitlink 記在 `lnk/sub`,`lnk` 是指到 `openspec/vendor` 的 link,clone 在 `openspec/vendor/sub` | `missing` | `ok` | `ok` | +| gitlink 記在 `OPENSPEC/specs/sub`,clone 在 `openspec/specs/sub` | `missing` | `error`(not checked out) | `ok` | +| 對照:同一個 clone 記在 `openspec/specs/sub` | `missing` | `missing` | `missing` | + +第一個形狀從這條分支的第一個 change 起就回 `ok`,七輪審查都沒有人建過它。第二個形狀原本回 `error`,原因正是第 5 個條件比對名稱;只改第 2、5 個條件會讓它變成 `ok`,也就是這次修正自己會多開一個 `ok`。兩個形狀的標記都在規格目錄裡,照第 15 列的說法應該回 `missing`。 + +做法:第 1、2 個條件通過之後,看往上走經過的目錄裡有沒有規格目錄(`os.path.join(top, sd)`,用 `os.path.samestat` 比對)。有的話,這個 submodule 不搜尋,也不算搜尋不到,與名稱在規格目錄底下時的處理相同;git 不在那個目錄執行。規格目錄檢查不到(例如不存在)時,沒有任何目錄算在它底下。第 1 或第 2 個條件不成立的 submodule 仍照那個條件回報。 + +這是往保守的方向改:兩個形狀的答案都變成 `missing`。第一個形狀的答案因此從 `ok` 變成 `missing`,這是相對於第七輪的行為改變,寫進條文與第 65 列。 + +### 六列 Example,其中五列只在不分大小寫的磁碟上執行 + +| 列 | 輸入 | 答案 | 修改前 | +| --- | --- | --- | --- | +| 60 | link 的目標把頂層目錄寫成另一種大小寫,submodule 在工作目錄裡 | `ok` | `error`,path leaves the repository | +| 61 | 樹裡記 `tests/sub`,磁碟上的目錄是 `Tests/sub` | `ok` | `error`,not checked out | +| 62 | link 指到頂層目錄之外,目標用另一種大小寫 | `error`,path leaves the repository | 相同 | +| 63 | link 指進主 repo 的 git 目錄,目標把頂層目錄寫成另一種大小寫 | `error`,path leaves the repository | 相同的答案,但原因是字串比對:沒有問 git 那兩個目錄 | +| 64 | 樹裡記的路徑把規格目錄寫成另一種大小寫,clone 落在規格目錄裡 | `missing` | `error`,not checked out(只改第 2、5 個條件時是 `ok`) | +| 65 | link 指進規格目錄,clone 落在規格目錄裡 | `missing` | `ok` | + +第 61 列的 fixture 直接把 clone 放在 `Tests/sub`、把 gitlink 記在 `tests/sub`,沒有重演上游改名與 pull;那個過程由協調者的重現(上面 Context)涵蓋,列的文字只寫 fixture 建出來的狀態。第 62 列確認新的往上比對仍然拒絕頂層目錄之外的目錄;第 63 列確認原本因為字串不同而被拒絕的輸入,現在由 git 目錄的比對拒絕,測試從 git 呼叫紀錄確認問過那兩個目錄。 + +第 60 到 64 列需要同一個目錄的兩種拼法。在區分大小寫的磁碟上沒有不需要管理者權限的做法,測試偵測到之後印出一行說明並略過這五列;所以它們的「測試先寫、在修改之前失敗」只在不分大小寫的磁碟上看得到。第 65 列在任何磁碟上都執行。macOS 上另外用 `/System/Volumes/Data` 的拼法重跑第 60 列的輸入(那個路徑指得到 fixture 時)。 + +### 第 58 列的 fixture 直接看檔案系統 + +量各環境下的檢查項數時發現:第 58 列(上一個 change 的列)的 fixture 用 `git rev-parse --is-inside-git-dir` 確認頂層目錄在 git 目錄裡。這個配置下 git 2.55.0 回 true、git 2.54.0(macOS 內附的)回 false,舊的 git 在 PATH 前面時整個測試檔停在這個 fixture。列的文字說的是頂層目錄在哪裡,不是那個選項印什麼;fixture 改成比對 `git rev-parse --absolute-git-dir` 印的目錄與頂層目錄的實際路徑。對 script 行為的檢查沒有改。 + +### 仍然照名稱比對的地方 + +這次改成比對目錄的有:第 2 個條件的前半、往上比對的停止條件、第 5 個條件,以及新加的規格目錄檢查。下面三處仍然比對名稱,各自在修改前後用兩種拼法量測過(不分大小寫的磁碟,git 2.55.0): + +1. **`--cwd`**:只交給 git 找頂層目錄,沒有任何比對。`--cwd` 把頂層目錄或它底下的目錄寫成另一種大小寫,答案與原本相同(`ok`)。 +2. **「同一個目錄、同一個 commit 只搜尋一次」的鍵**(解析後的路徑字串與 commit)。同一個目錄以兩種拼法各記一次(`Tests/sub` 與 `tests/sub`)時,修改後兩個都通過條件,各被搜尋一次,答案相同(都沒有標記時是 `missing`)。修改前第二個被第 5 個條件回報為 not checked out(`error`)。重複搜尋不改變答案;拼法的個數有限,所以防止循環的作用不受影響。 +3. **檔案名稱的兩個排除**(在規格目錄底下、以 `.md` 結尾)。條文寫明它們看的是名稱(「apply to that name」),名稱是樹裡記的路徑。主 repo 自己的檔案記在 `OPENSPEC/specs/cap/check.sh`、帶標記時,從 4.1.0 起就回 `ok`,修改前後相同。在不分大小寫的磁碟上那個檔案取出來會落在規格目錄裡。要不要讓這個排除忽略大小寫,會改變沒有 submodule 的 repository 的答案,不在這張 issue 的範圍,記在 #559。 + +## Implementation Contract + +- `openspec/specs/spec-on-every-issue/spec.md`(由封存套用):requirement「Added and modified requirements carry an executable check」的第 2、5 個條件換掉;「(6) its object store holds the recorded commit.」之後加兩句(比對的是目錄;檢查不到的目錄略過);其後「The git directory of a submodule …」與「The top directory is not compared …」兩句換掉;「Submodules」一段在「none of its files could count.」之後加三句(落在規格目錄裡的 submodule);Example「markers in submodules」在第 59 列之後多第 60 到 65 列。其他句子與列逐字不變。 +- `plugins/issue-driven-dev/scripts/spec-change.py`:新增 `directories_below_top()`、`leaves_repository()`、`same_directory()`、`in_spec_directory()`;`under_git_directory()` 改成比對一份清單;`marker_files()` 裡第 2 個條件的兩個分支合成一個、第 5 個條件改用 `same_directory()`,不再計算 `real_top`,第 2 個條件之後多一個分支(落在規格目錄裡的不搜尋、不列為搜尋不到);檔頭 `links` 的說明改寫。除此之外不改。 +- `plugins/issue-driven-dev/scripts/tests/spec-change/test.sh`:第 59 列之後新增第 60 到 65 列的 fixture 與檢查,以及偵測磁碟是否區分大小寫的一段;第 57 列的註解改成新的說法(不另外把 submodule 的 git 目錄加進清單);第 58 列的 fixture 確認配置的那一行改成直接看檔案系統。其他不動。 +- `plugins/issue-driven-dev/CHANGELOG.md`:只動 `[Unreleased]` 裡 #548 那一條講這兩個條件的那一句,與講規格目錄底下的路徑被略過的那一句。 +- 驗證:在不分大小寫的磁碟上,第 60、61 列的檢查與第 63 列「問過那兩個目錄」的檢查在改程式之前的 commit 上失敗、之後通過;第 62 列與第 63 列的其他檢查前後都通過;第 64、65 列的檢查在加上規格目錄檢查之前的 commit 上失敗、之後通過;`tests/spec-change/test.sh` 全部通過;`run-all-tests.sh` 結束碼 0;`links --base origin/main` 回 `ok`;`archived` 回 pass。 + +## Risks / Trade-offs + +- 比對裝置與 inode 是作業系統對「同一個目錄」的說法。同一個目錄經由兩個掛載點出現時(例如 Linux 的 bind mount),兩邊會被當成同一個目錄;這與條文一致。反過來,子目錄另外掛載到別處、而上層沒有一起掛載時,往上走遇不到頂層目錄,答案是 path leaves the repository(保守的方向)。 +- 第 60 到 64 列在區分大小寫的磁碟上不執行,所以 Linux 上的 CI 看不到它們。這個缺陷在那種磁碟上不靠管理者權限也造不出來。 +- 落在規格目錄裡、經由 link 走到的 submodule,答案從 `ok` 變成 `missing`(第 65 列)。有人把檢查用的 submodule 放在規格目錄裡、再用 link 引出來的話,要把它移到規格目錄之外。 +- 主 repo 自己的檔案仍然照名稱排除(上面第 3 點),與 submodule 的處理不一致,留給 #559。 + +## Migration Plan + +沒有資料要搬。答案改變的輸入:第 60、61 列的形狀(`error` 變 `ok`),同一個目錄以兩種拼法各記一次(`error` 變成依搜尋結果),第 64 列的形狀(`error` 變 `missing`),第 65 列的形狀(`ok` 變 `missing`)。其他輸入的答案不變。 + +## Open Questions + +- 主 repo 自己的檔案的排除,在不分大小寫的磁碟上要不要忽略大小寫(#559)。 diff --git a/openspec/changes/archive/2026-11-15-idd-548-fix7/proposal.md b/openspec/changes/archive/2026-11-15-idd-548-fix7/proposal.md new file mode 100644 index 00000000..be17e5c9 --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-fix7/proposal.md @@ -0,0 +1,73 @@ +**GitHub-side tracker**: #548 + +## Problem + +第七輪 verify(留言 6893428419)確認第七個 change 解決了第六輪的三列,但整輪不乾淨:有兩行程式比對的是解析後的路徑字串,而 requirement「Added and modified requirements carry an executable check」說的是目錄。這兩行在第六輪之前就有,前六輪都沒有人看到。 + +- 第 1 列(HIGH,blocking):第 5 個條件。上游把放 submodule 的目錄只改大小寫(`Tests/sub` 改成 `tests/sub`),本機在不分大小寫的磁碟上照常 pull 之後,git 把那個目錄回報為它自己工作樹的頂層,`git submodule status` 也列出它;`links` 卻回 `error`,原因是 not checked out。只用 git 指令就走得到。 +- 第 2 列(HIGH,blocking):第 2 個條件的前半。link 的目標把頂層目錄寫成另一種拼法(另一種大小寫,或 macOS 上同一個磁碟的另一種絕對路徑)時,repository 裡的 submodule 被回 `error`,原因是 path leaves the repository;link 用實際的拼法時回 `ok`。 +- 第 3 列(LOW):「submodule 的 git 目錄不在清單上」在 submodule 的 git 目錄正好是清單上的目錄時,照字面不對。 +- 第 4 列(LOW):頂層目錄本身就是那兩個目錄之一時,第 2 個條件的子句與條件 6 之後的第四句說的相反。 + +兩項 HIGH 的方向都是保守的:答案是 `error`,不會把沒有檢查的 Example 說成 `ok`。 + +修這兩行會連帶改變另一種輸入的答案,所以一起處理:submodule 的目錄實際落在規格目錄裡、但樹裡記的路徑名稱不在 `openspec/` 底下。這種輸入有兩個形狀。一個是路徑經過一個指進規格目錄的 symbolic link,它從這條分支第一個 change 起就回 `ok`(4.1.0 回 `missing`)。另一個是路徑把規格目錄寫成另一種大小寫,它原本回 `error`,原因正是第 5 個條件比對名稱;第 5 個條件改對之後會變成 `ok`。Example 第 15 列說的是「mounted under `openspec/`」的 submodule 回 `missing`;這兩個形狀都是放在規格目錄裡的 submodule。 + +維護者的決定(留言 6894347661):改程式,再審一輪。 + +## Root Cause + +`os.path.realpath` 解析 symbolic link,但不會把同一個目錄的兩種拼法變成同一個字串。程式有兩處拿解析後的字串來判斷「是不是同一個目錄」或「在不在某個目錄底下」: + +- `marker_files()` 用 `os.path.commonpath` 判斷 submodule 的目錄在不在頂層目錄底下(第 2 個條件的前半)。 +- `marker_files()` 用字串相等判斷 git 回報的頂層是不是那個目錄(第 5 個條件)。 + +同一個函式裡,與那兩個 git 目錄的比對(第 2 個條件的後半)用的是 `os.stat`,不受拼法影響;`under_git_directory()` 往上走的迴圈卻用字串長度決定何時停。條文在第 2 個條件裡寫了「比對的是目錄,不是名稱」,前半沒有照做。 + +## Proposed Solution + +- 程式: + - 第 2 個條件:從解析後的目錄往上走,每一層用 `os.stat` 與頂層目錄比對,遇到頂層目錄就停;走到檔案系統的根還沒遇到,原因是 path leaves the repository。沿路經過的每一層(不含頂層目錄)就是拿來與那兩個 git 目錄比對的清單,`under_git_directory()` 不再自己往上走。 + - 第 5 個條件:git 回報的頂層與那個目錄用 `os.path.samefile` 比對。 +- 條文: + - 第 2 個條件寫明整個條件都比對目錄,並說「在頂層目錄底下」是什麼意思(往上走會遇到頂層目錄);子句加上「除非它就是頂層目錄」。 + - 第 5 個條件寫明 git 回報的是同一個目錄,不論路徑怎麼拼。 + - 「submodule 的 git 目錄不在清單上」改成「不另外加進清單」,並說它正好是那兩個目錄之一或在其中之一底下時,第 2 個條件照寫的適用。 +- 落在規格目錄裡的 submodule:程式在第 1、2 個條件通過之後,檢查往上走經過的目錄裡有沒有規格目錄(比對目錄);有的話不搜尋,也不算搜尋不到,與路徑名稱在規格目錄底下時相同。條文在「Submodules」一段加三句。 +- Example「markers in submodules」加六列(第 60 到 65 列)。第 60 到 64 列需要同一個目錄的兩種拼法,測試只在不分大小寫的磁碟上建得出來;在區分大小寫的磁碟上,測試印出一行說明並略過這五列。第 65 列(link 指進規格目錄)在任何磁碟上都執行。 +- `spec-change.py` 檔頭的說明、函式的說明與 CHANGELOG 的 #548 條目,改成同樣的說法。 + +## Non-Goals + +- 不改主 repo 自己的搜尋,也不改 `archived`、`preflight`、`declared`、`ic`。 +- 不改「同一個目錄、同一個 commit 只搜尋一次」所用的鍵(仍是解析後的路徑字串):同一個目錄經由兩種拼法被搜尋兩次時答案相同。記在 #559。 +- 不改主 repo 自己的檔案的排除,也不改 `.md` 的排除:條文寫明它們看的是樹裡記的名稱。主 repo 的檔案記在把規格目錄寫成另一種大小寫的路徑時,從 4.1.0 起就回 `ok`;這牽涉沒有 submodule 的 repository 的答案,記在 #559。 +- 不處理 #556、#559 裡的其他項目,包括繼承的 `GIT_DIR`、`GIT_COMMON_DIR`,以及 git 答不出目錄時的原因文字。 +- 不排除 submodule 自己的 git 目錄,也不改「解析後等於頂層目錄的路徑照樣接受」。 + +## Success Criteria + +- 在不分大小寫的磁碟上,第 60、61 列的檢查在改程式之前的 commit 上失敗(`status` 是 `error`),之後通過。第 62 列改之前與之後都通過。第 63 列的答案改之前與之後相同,但改之前是字串比對拒絕的、沒有問 git 那兩個目錄,所以它「問過那兩個目錄」的檢查在改之前失敗、之後通過。 +- 逐一把程式的每一處修改改回去或改壞時,每一種都讓至少一列的檢查失敗。哪一種讓哪些列失敗以量到的為準,記在 tasks.md 的驗收紀錄;動手之前已知的一點是,第 60 列的輸入要第 2 個條件與第 5 個條件兩處都改了才回 `ok`,所以把其中任何一處改回去,第 60 列都會失敗。 +- 第 64、65 列的檢查在加上規格目錄的檢查之前的 commit 上失敗(`status` 是 `ok`),之後通過;第 65 列不需要不分大小寫的磁碟。 +- 第 1 到 59 列的答案不變。 +- `bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 全部通過;`bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 結束碼 0。 +- `spec-change.py links` 從預設分支到這條分支的 HEAD 回 `ok`;`archived` 回 pass。 + +## Capabilities + +### New Capabilities + +(none) + +### Modified Capabilities + +- `spec-on-every-issue`: requirement「Added and modified requirements carry an executable check」的第 2、5 個條件與條件之後的一段改寫,「Submodules」一段加三句;Example「markers in submodules」加第 60 到 65 列。 + +## Impact + +- Affected specs: spec-on-every-issue(一個 MODIFIED requirement) +- Affected code: + - Modified: plugins/issue-driven-dev/scripts/spec-change.py + - Modified: plugins/issue-driven-dev/scripts/tests/spec-change/test.sh + - Modified: plugins/issue-driven-dev/CHANGELOG.md diff --git a/openspec/changes/archive/2026-11-15-idd-548-fix7/specs/spec-on-every-issue/spec.md b/openspec/changes/archive/2026-11-15-idd-548-fix7/specs/spec-on-every-issue/spec.md new file mode 100644 index 00000000..4c7b2f8a --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-fix7/specs/spec-on-every-issue/spec.md @@ -0,0 +1,125 @@ +## MODIFIED Requirements + +### Requirement: Added and modified requirements carry an executable check + +`scripts/spec-change.py links --base <rev>` SHALL compare the files under `openspec/specs/` at `<rev>` and at `--head` (default `HEAD`). For every requirement that is new or whose text differs between the two, it SHALL require one of two things: at least one `##### Example:` under the requirement, where each such Example has a title that is unique within its capability and a tracked file at the head revision, outside `openspec/` and not ending in `.md`, that contains the marker `spec-example: <capability> / <Example title>` (a tracked file of a submodule counts, as the paragraph "Submodules" below describes); or a line under the requirement that starts with `No executable check:` followed by a reason. A requirement that does not differ SHALL NOT be checked. A marker counts only when nothing but whitespace, or the comment closer `-->` or `*/`, follows the Example title on its line. Lines inside a code fence are not read as `##### Example:` or `No executable check:` lines; a fence opened by three or more backticks or tildes, at any indentation (as inside a list item), closes only on a line of the same character, at least as long, with nothing but whitespace after it; lines end only at `\n`, `\r\n` or `\r`. A requirement heading indented by up to three spaces SHALL be read as a requirement, as Spectra reads it. Paths SHALL be read as git stores them, never in git's quoted form, so a capability whose directory name is not ASCII is checked like any other. Two requirements with the same name in one capability SHALL make the command print `error`. So SHALL a code fence at the head revision that never closes, since the requirements after it would go unchecked. Outside code fences, a heading that starts with `### Requirement` but does not have the form `### Requirement: <name>` with a non-empty name SHALL make the command print `error`, and so SHALL a head revision at which the spec directory's `specs/` holds no tracked file, and a path under the spec directory's `specs/` that is not valid UTF-8 (the reason says so and carries no text of an exception). Such a path elsewhere under the spec directory does not change the answer. The command SHALL print one JSON line with `status` (`ok`, `missing` or `error`) and a list naming each requirement or Example that lacks its check, and SHALL exit 0, 1 or 2 in that order. `--base` is required: the caller names the range, so that a run on the default branch is checked against the commit it started from. The marker ties an Example to a test by name only; whether the test exercises what the Example states is judged by the reviewers of `idd-verify`. + +Submodules. The tracked files at the head revision include the tracked files of every submodule of the repository at the commit that the head revision records for it, and in the same way the files of a submodule of a submodule. The command SHALL read that recorded commit, not the commit the submodule's working tree is on. It SHALL find the submodules itself, from the entries of the head revision's tree that record a commit; it SHALL NOT rely on git's own recursion into submodules, which passes over a submodule that is not checked out without saying so; the answer SHALL be the same whether or not the git configuration turns that recursion on (`submodule.recurse`). A file of a submodule is named by the submodule's path followed by the file's path, and the two exclusions (under the spec directory, ending in `.md`) apply to that name. A submodule whose own path is under the spec directory SHALL NOT be searched and SHALL NOT count as one that could not be searched: none of its files could count. Nor SHALL a submodule be searched, or count as one that could not be searched, when its directory, after symbolic links are resolved, is the spec directory of the main repository or lies under it, whatever its path is named: a symbolic link, or another spelling of the name on a volume that does not distinguish letter case, can lead into the spec directory from a path that is not under it by name. This is decided after conditions 1 and 2 of the paragraph "Which submodules can be searched" below, and in the way of condition 2: the spec directory is one of the directories passed before the top directory is met, and directories are compared, not names. A spec directory that cannot be examined has nothing under it. + +Order of the search. For each Example the command SHALL search the main repository first. When the marker is found there, the Example has its check and the command SHALL NOT run git in any submodule for it, so for a repository whose markers are all in its own files no entry that records a commit is listed and no submodule is examined, whatever its head revision records. Only when the marker is not found in the main repository are the submodules searched, and a marker found in one submodule settles the Example whatever the state of the others. When the marker of an Example is found, the Example has its check, whether or not every submodule could be searched. The submodules inside a submodule are read from a listing of every tree of its recorded commit, and that listing is made only when the outer one meets its own six conditions. Each of them is then searched whenever its own six conditions hold, also when the search of the outer one failed. When the listing fails, because a tree of the recorded commit cannot be read, the submodules inside it are unknown, even when the top tree shows them. + +Which submodules can be searched. A submodule SHALL be searched only when all six of these hold: (1) its path, as the tree records it, is relative and has no empty, `.` or `..` component; (2) its directory, after symbolic links are resolved, is the top directory of the main repository or lies under it, which means that the top directory is met when going from the resolved directory to its parent directory, to the parent of that one, and so on; and no directory passed before the top directory is met (the resolved directory itself, unless it is the top directory, and each directory between the two) is one of two directories, the one that `git rev-parse --absolute-git-dir` prints and the one that `git rev-parse --git-common-dir` prints when run at the top directory (in a linked worktree these are two different directories); (3) the directory itself is not a symbolic link; (4) the directory holds an entry named `.git` of its own; (5) git, run in the directory, reports that same directory as the top of its own working tree; (6) its object store holds the recorded commit. In conditions 2 and 5 directories are compared, not names: two paths name the same directory when the operating system reports the same device and the same inode for both, however each path is spelled (on a volume that does not distinguish letter case, for one, a path written in another letter case names the same directory). A directory on the way up that cannot be examined (one that does not exist, for one) is passed over: it is neither the top directory nor one of the two. The two directories of condition 2 are a closed list: no other directory is refused under that condition. No git directory of a submodule is added to the list: when the git directory of a submodule is itself one of the two, or lies under one of them, condition 2 applies to it as written, and otherwise a directory inside it is searched when the six conditions hold. The top directory is not compared with the two, so when the top directory is one of them, or lies inside one of them, neither it nor the directories under it are refused for that reason. A directory that resolves to the top directory itself meets condition 2. The command SHALL NOT run git in a directory that fails any of the first four: a directory of ordinary tracked files can be shaped like a git directory, and git would read, and act on, the configuration it holds. Nor SHALL it run git in the directory of any submodule when git is older than 2.45, the first version that honours `GIT_NO_LAZY_FETCH`, or when the version cannot be read: a submodule for which the first four hold then counts as one that could not be searched. In the directory of a submodule the command SHALL run git with `safe.bareRepository` set to `explicit`, with lazy fetching turned off (`GIT_NO_LAZY_FETCH=1`), and with the variables `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, `GIT_OBJECT_DIRECTORY`, `GIT_ALTERNATE_OBJECT_DIRECTORIES` and `GIT_COMMON_DIR` removed from the environment it inherited. Before it searches a submodule the command SHALL ask git which objects of the recorded commit (its trees and the contents of its files) the object store lacks or cannot open, without fetching any: an object whose file is present but cannot be opened (for example an empty file) counts as lacking. A submodule is searched even when some are lacking, and a file that counts, found by a search that ran to its end (exit code 0 or 1), settles the Example. What a search printed before it ended with another exit code SHALL NOT be used, so that the answer for one state of the repository is the same on every run. When no file that counts is found in it, the submodule counts as one that could not be searched if its object store lacks an object of the recorded commit, if the search exits with a code other than 0 or 1, or if the trees of the recorded commit cannot all be listed. What git writes to its error stream SHALL NOT change whether a submodule counts as searched, nor the reason reported for it. In the main repository a search that exits with a code other than 0 or 1 is `error`, as before; its reason is `git grep failed: ` followed by the first 200 characters of what git wrote to its error stream, also as before. + +What is reported. When the marker is not found and every submodule was searched, the Example is reported as lacking its check, as before. When it is not found and at least one submodule could not be searched, the command SHALL print `error` and name the first such Example it meets, the submodules that could not be searched and the reason for each: an Example whose candidate files were not all read is not reported as lacking its check. The submodules are named by path, in the order of their paths and joined by `; `; a submodule of a submodule is named by its path under the outer one; when more than five could not be searched, the first five are named and the number of the others is stated; a path longer than 200 characters is cut to its first 200 followed by `...`. The reason is one of six: the path leaves the repository (conditions 1 and 2); the submodule is not checked out (conditions 3 and 4, or git names another directory as the top); git is older than 2.45 (stated also when its version cannot be read); git refused to open it (the git command of condition 5 fails); the recorded commit is not in its object store (condition 6); the recorded commit could not be read (its object store lacks or cannot open an object of it, or the search or the listing of its trees failed). The reason given for a submodule SHALL NOT carry text from git's error stream. The path of a submodule that is not valid UTF-8 is handled like any other path, and the command still prints one JSON line. A repository whose head revision records no submodule is searched in its own tracked files only: none of the rules for submodules changes its answer. + +#### Scenario: An Example without a test is reported + +- **GIVEN** a range that adds a requirement with one Example titled `status by exit code` to the capability `local-ci-gate` +- **AND** no tracked file outside `openspec/` contains `spec-example: local-ci-gate / status by exit code` +- **WHEN** `spec-change.py links` runs on that range +- **THEN** it prints `status` `missing`, names that Example, and exits 1 + +##### Example: what the link check reports + +| Requirement in the range | Examples | Marker at the head revision | `No executable check:` line | `status` | +| --- | --- | --- | --- | --- | +| added | one | in `scripts/tests/x/test.sh` | absent | `ok` | +| added | one | absent | absent | `missing` | +| added | one | only in a file under `openspec/` | absent | `missing` | +| added | one | only in a file ending in `.md` | absent | `missing` | +| added | none | not applicable | absent | `missing` | +| added | none | not applicable | present, with a reason | `ok` | +| added | none | not applicable | present, with nothing after the colon | `missing` | +| added | one, with no title | not applicable | absent | `missing` | +| added | two with the same title as an Example elsewhere in the capability | present | absent | `missing` | +| changed | two | present for one, absent for the other | absent | `missing` | +| unchanged, with no Example | none | not applicable | absent | `ok` | +| removed in the range | not applicable | not applicable | not applicable | `ok` | +| no file under `openspec/specs/` differs | not applicable | not applicable | not applicable | `ok` | +| added | one | only a marker naming a longer title that starts with this one | absent | `missing` | +| added, under the heading `### Requirement Missing colon` | not applicable | not applicable | not applicable | `error` | +| any; `openspec/specs/` holds no tracked file at the head revision | not applicable | not applicable | not applicable | `error` | +| added, its only `##### Example:` line inside a code fence | none outside fences | not applicable | absent | `missing` | +| added, its only `No executable check:` line inside a code fence | none | not applicable | only inside a fence | `missing` | +| added, after a fence of four backticks that a line of three backticks does not close | its Example inside that fence | not applicable | absent | `missing` | +| added, under the heading ` ### Requirement: Alpha` (two leading spaces) | none | not applicable | absent | `missing` | +| added, its only `No executable check:` line inside a fence indented four spaces in a list item | none | not applicable | only inside that fence | `missing` | +| added, in a capability whose directory name is not ASCII (`中文能力`) | none | not applicable | absent | `missing` | +| added, in a capability whose directory name holds a double quote (`quo"te`) | none | not applicable | absent | `missing` | +| added, in a capability whose directory name is not valid UTF-8 | not applicable | not applicable | not applicable | `error`, with a reason that says so | +| added; a tracked path under the spec directory but outside `specs/` is not valid UTF-8 | one | in `scripts/tests/x/test.sh` | absent | `ok` | +| added; a tree of the head revision outside the spec directory cannot be read | one | absent | absent | `error`; the reason is `git grep failed: ` followed by the first 200 characters of what git wrote to its error stream | +| added twice with the same name in one capability | not applicable | not applicable | not applicable | `error` | +| any, after a code fence that never closes | not applicable | not applicable | not applicable | `error` | +| `--base` names a revision that does not exist | not applicable | not applicable | not applicable | `error` | +| `--base` is not given | not applicable | not applicable | not applicable | usage error, exit 64 | + +##### Example: markers in submodules + +| Where the marker of the Example is at the head revision | Submodules recorded at the head revision | `status` | +| --- | --- | --- | +| in a tracked file of a submodule, at the commit the head revision records | one, checked out | `ok` | +| in a tracked file of a submodule of a submodule | both checked out | `ok` | +| in a tracked file of a submodule whose path holds a space | one, checked out | `ok` | +| only in the recorded commit of a submodule whose working tree is on a later commit without it | one, checked out | `ok` | +| only in a later commit of a submodule, which its working tree is on, not in the recorded commit | one, checked out | `missing` | +| only in a file of a submodule that ends in `.md` | one, checked out | `missing` | +| nowhere | one, checked out | `missing` | +| nowhere in the main repository | one, not checked out | `error`, naming the Example and the submodule's path | +| in a tracked file of the main repository | one, not checked out | `ok` | +| nowhere in the main repository | one, checked out, whose object store lacks the recorded commit | `error`, naming the Example and the submodule's path | +| in a tracked file of the main repository | one, checked out, whose object store lacks the recorded commit; `submodule.recurse` is true in the repository's git configuration | `ok` | +| nowhere in the main repository | one, checked out, whose object store lacks the recorded commit; `submodule.recurse` is true in the repository's git configuration | `error`, naming the Example and the submodule's path | +| only in the recorded commits of two submodules | two, neither checked out | `error`, naming the Example and both paths, joined by `; ` | +| only in a submodule of a submodule | the outer one checked out, the inner one not | `error`, naming the Example and the inner submodule by its path under the outer one | +| only in a tracked file of a submodule that is mounted under `openspec/` | one, checked out | `missing` | +| in a tracked file of the main repository | one whose path is not valid UTF-8, not checked out | `ok` | +| nowhere | one whose path is not valid UTF-8, not checked out | `error` on one JSON line, exit 2 | +| in a tracked file of the main repository | one, checked out, holding the recorded commit but not the tree of that commit | `ok` | +| nowhere in the main repository | one, checked out, holding the recorded commit but not the tree of that commit | `error`, naming the Example and the submodule's path, with no text from git's error stream | +| nowhere | one, checked out, whose object store lacks the content of one file of the recorded commit | `error`, naming the Example and the submodule's path, with no text from git's error stream | +| nowhere | one, checked out, whose recorded commit records a second submodule; at that second path the working tree holds ordinary files shaped like a git directory (`HEAD`, `config`, `objects/`, `refs/`) and no `.git` entry, and that `config` names a command to run | `error`, naming the second path as not checked out; the command named in that `config` does not run | +| in a tracked file of the main repository | the same two, with the same files at the second path | `ok`; no git command runs in the directory of a submodule, and the command named in that `config` does not run | +| only in a repository outside the main repository, at a path with a `..` component that the head revision's tree records as a submodule | that one | `error`, naming the path as one that leaves the repository; the same answer when nothing is at that outside path | +| only in a repository outside the main repository, reached through a symbolic link in the working tree that is part of a recorded submodule path | that one | `error`, naming the path as one that leaves the repository | +| in a tracked file of a submodule whose path ends in a space | one, checked out | `ok` | +| nowhere | one, not checked out, mounted under `openspec/` | `missing` | +| only in a tracked file of a submodule | one, checked out elsewhere inside the working tree of the main repository, whose own directory is a symbolic link to that checkout | `error`, naming the Example and the submodule's path as not checked out | +| in a tracked file of a submodule | one, checked out; the variable `GIT_DIR` is set to the git directory of the main repository | `ok` | +| only in the recorded commits of seven submodules | seven, none checked out | `error`, naming the Example, the first five paths in order and the number of the other two | +| nowhere | one whose directory holds a `.git` entry that git cannot open | `error`, naming the Example and the submodule's path as one git refused to open | +| nowhere | one whose directory holds an empty `.git` directory and, beside it, ordinary files shaped like a git directory (`HEAD`, `config`, `objects/`, `refs/`) whose `config` names a command to run | `error`, naming the submodule's path as one git refused to open; the command named in that `config` does not run | +| in a tracked file of the main repository | one, checked out as a partial clone that never fetched the file contents of the recorded commit | `ok`; nothing is fetched into the submodule | +| nowhere | one, checked out as a partial clone that never fetched the file contents of the recorded commit | `error`, naming the Example and the submodule's path; nothing is fetched into the submodule | +| nowhere | one, not checked out, whose path is longer than 200 characters | `error`, naming the first 200 characters of the path followed by `...` | +| in a tracked file of one submodule | two; the one with the marker checked out, the other not | `ok` | +| only in a file ending in `.md` of a submodule | one, checked out, whose object store lacks the content of another file of the recorded commit | `error`, naming the Example and the submodule's path | +| only in a tracked file of a submodule | one whose `.git` entry git opens, with the working tree of that git directory set to the parent directory, so that git names the parent as the top | `error`, naming the Example and the submodule's path as not checked out | +| only in a submodule of a submodule | three recorded paths: `a`, checked out; its own submodule `a/inner`, not checked out; and `a-b`, not checked out | `error`, naming `a-b` before `a/inner` | +| nowhere | one, at a path with a `.` component that the head revision's tree records | `error`, naming the path as one that leaves the repository | +| in a tracked file of a submodule | one, checked out; the six variables named above are all set to the git directory, working tree, index and object store of the main repository | `ok` | +| only in the recorded commit of a submodule, which the checked-out submodule's own object store lacks | one, checked out; the variable `GIT_ALTERNATE_OBJECT_DIRECTORIES` names an object store that holds that commit | `error`, naming the Example and the submodule's path, with the recorded commit as not in its object store | +| only in a submodule of a submodule, checked out and complete | the outer one checked out, its object store lacking the content of one unrelated file of its recorded commit | `ok` | +| nowhere | the same two | `error`, naming the Example and the outer submodule's path only, with its recorded commit as one that could not be read | +| in a tracked file of one submodule | two; the other one is not checked out and comes first in the order of the paths | `ok` | +| in a tracked file that counts, of a submodule whose object store lacks the content of another file of the recorded commit | one, checked out | `ok` | +| nowhere | one, checked out, holding every object of the recorded commit; git writes to its error stream during the search (`GIT_TRACE=1`) | `missing` | +| only in a tracked file of a submodule | one, checked out; git reports a version older than 2.45, or one that cannot be read | `error`, naming the Example and the submodule's path with git as older than 2.45; no git command runs in the directory of the submodule | +| in a tracked file of the main repository | one, checked out; git reports a version older than 2.45 | `ok` | +| nowhere | one, checked out, whose object store holds a damaged copy of the content of one file of the recorded commit (the object file is present and is not a compressed object, so the search ends with exit code 128) | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read | +| only in a tracked file of a submodule; the object that holds the content of that file is present but empty (zero bytes), so the search skips the file and ends with exit code 0 or 1 | one, checked out | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read | +| nowhere | one, checked out, holding every object of the recorded commit; one of its tracked files has a name with a carriage return followed by `?` | `missing` | +| in a tracked file of a submodule | one, checked out, whose object store holds a damaged copy of the content of another file, so that the search ends with exit code 128 | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read; the same answer on each of three runs | +| only in a submodule of a submodule, checked out and complete | the outer one checked out, its object store lacking a tree below the top of its recorded commit | `error`, naming the Example and the outer submodule's path only, with its recorded commit as one that could not be read | +| nowhere | one, checked out; the object that holds the content of one file is damaged in its body, so that git lists it and opens it, and the search ends with exit code 128 | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read | +| only in a repository placed inside the git directory of the main repository, reached through a symbolic link in the working tree that is part of a recorded submodule path | that one | `error`, naming the path as one that leaves the repository; git is not run in that directory | +| only in a repository placed inside the git directory of the main repository; the command runs in a linked worktree whose top directory holds the main repository, and a symbolic link in that worktree that is part of a recorded submodule path leads into that git directory | that one | `error`, naming the path as one that leaves the repository; git is not run in that directory | +| only in a repository placed inside the git directory of a submodule whose `.git` entry is a directory, reached through a symbolic link in that submodule that is part of a submodule path its recorded commit records | the outer one, checked out, and that one | `ok` | +| in a tracked file of a submodule | one, checked out; the git directory of the main repository was made apart from its working tree and the top directory lies inside it | `ok` | +| only in an earlier commit of the main repository, which the head revision records as a submodule at a path that a symbolic link in the working tree leads back to the top directory | that one | `ok` | +| in a tracked file of a submodule that is checked out inside the working tree and reached through a symbolic link in the working tree that is part of its recorded path; the link's target names the top directory in another letter case, on a volume that does not distinguish letter case | that one | `ok` | +| in a tracked file of a submodule | one, checked out; the directory it is checked out in differs from the recorded path in letter case only, on a volume that does not distinguish letter case, and git, run there, names the directory as it is named on disk | `ok` | +| only in a repository outside the top directory, reached through a symbolic link in the working tree that is part of a recorded submodule path; the link's target names that outside directory in another letter case, on a volume that does not distinguish letter case | that one | `error`, naming the path as one that leaves the repository; git is not run in that directory | +| only in a repository placed inside the git directory of the main repository, reached through a symbolic link in the working tree that is part of a recorded submodule path; the link's target names the top directory in another letter case, on a volume that does not distinguish letter case | that one | `error`, naming the path as one that leaves the repository; git is not run in that directory | +| only in a tracked file of a submodule whose recorded path names the spec directory in another letter case, so that its directory lies under `openspec/`, on a volume that does not distinguish letter case | one, checked out | `missing`; git is not run in that directory | +| only in a tracked file of a submodule that is checked out under `openspec/` and reached through a symbolic link in the working tree that is part of its recorded path | that one | `missing`; git is not run in that directory | diff --git a/openspec/changes/archive/2026-11-15-idd-548-fix7/tasks.md b/openspec/changes/archive/2026-11-15-idd-548-fix7/tasks.md new file mode 100644 index 00000000..5f905bcc --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-fix7/tasks.md @@ -0,0 +1,37 @@ +## 1. 測試先寫 + +- [x] 1.1 依 design「四列 Example,只在不分大小寫的磁碟上執行」,為 requirement「Added and modified requirements carry an executable check」的 Example「markers in submodules」第 60 到 63 列寫 fixture 與檢查,加在 `plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 第 59 列的檢查之後;先偵測放 fixture 的磁碟是否區分大小寫,區分時印出一行說明並略過這四列。第 60 列:link 的目標把頂層目錄寫成另一種大小寫,submodule 在工作目錄裡,`links` 回 `ok`,git 在記錄的路徑搜尋。第 61 列:樹裡記 `tests/sub`、磁碟上的目錄是 `Tests/sub`,回 `ok`。第 62 列:link 指到頂層目錄之外、目標用另一種大小寫,回 `error`(path leaves the repository),git 不在那個目錄執行,也沒有問那兩個目錄。第 63 列:link 指進主 repo 的 git 目錄、目標把頂層目錄寫成另一種大小寫,回 `error`(path leaves the repository),git 不在那個目錄執行,而且問過那兩個目錄。macOS 上 `/System/Volumes/Data` 的拼法指得到 fixture 時,用它重跑第 60 列的輸入。驗證:在不分大小寫的磁碟上執行 `bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh`,script 還沒改時第 60、61 列的檢查與第 63 列「問過那兩個目錄」的檢查失敗,第 62 列與第 63 列的其他檢查通過,第 1 到 59 列的檢查全部通過。 + - 紀錄(script 未改,git 2.55.0、macOS、不分大小寫的 APFS、`spectra` 在 PATH 上):859 項通過、9 項失敗。失敗的是第 60 列的三項(`status` 要 `ok` 得到 `error`、結束碼要 0 得到 2、git 沒有在記錄的路徑搜尋)、第 60 列改用 `/System/Volumes/Data` 拼法的兩項(`status`、結束碼)、第 61 列的三項(同第 60 列的三項)、第 63 列的一項(git 沒有被問那兩個目錄)。第 62 列的七項、第 63 列的其他六項與第 1 到 59 列的檢查都通過。 +- [x] 1.2 [after: 2.1] 依 design「落在規格目錄裡的 submodule 不搜尋,不論路徑叫什麼」,為 Example「markers in submodules」第 64、65 列寫 fixture 與檢查,加在同一個測試檔:第 64 列放在需要不分大小寫的磁碟的那一段裡(樹裡記的路徑把規格目錄寫成另一種大小寫,clone 落在規格目錄裡),第 65 列放在那一段之後(link 指進規格目錄,任何磁碟都執行)。兩列都要 `links` 回 `missing`、列出一項、結束碼 1,而且 git 沒有在那個目錄執行。略過的說明改成第 60 到 64 列。驗證:在 2.1 之後的 script 上,第 64、65 列的檢查失敗(`status` 得到 `ok`,git 在那個目錄執行過),其餘檢查全部通過。 + - 紀錄(script 是 2.1 之後的,同一環境):870 項通過、8 項失敗,第 64、65 列各四項:`status` 要 `missing` 得到 `ok`、列出的項數要 1 得到 0、結束碼要 1 得到 0、git 在那個目錄執行過。 +- [x] 1.3 [after: 2.2] 依 design「第 58 列的 fixture 直接看檔案系統」:`plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 第 58 列的 fixture 不再用 `git rev-parse --is-inside-git-dir` 確認配置,改成比對 `git rev-parse --absolute-git-dir` 印的目錄與頂層目錄的實際路徑。驗證:git 2.55.0 與 git 2.54.0 各自在 PATH 前面時,測試檔都全部通過。 + - 紀錄(`f6fe368`):兩個版本都是 878 項通過、0 項失敗。改之前,git 2.54.0 在 PATH 前面時測試檔停在這個 fixture(`setup_failed`,「git must report the top directory as inside the git directory」)。 + +## 2. 程式 + +- [x] 2.1 [after: 1.1] 依 design「『在頂層目錄底下』的意思是往上走會遇到頂層目錄」「往上走經過的目錄,就是與那兩個 git 目錄比對的清單」「第 5 個條件用同一種比對」「檢查不到的目錄略過」與 Implementation Contract:`plugins/issue-driven-dev/scripts/spec-change.py` 新增 `directories_below_top()`、`leaves_repository()`、`same_directory()`,`under_git_directory()` 改成比對一份清單,`marker_files()` 的第 2、5 個條件改用它們;檔頭與函式的說明改成同樣的說法。驗證:`bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 全部通過;第七輪協調者的兩個重現(上游只改大小寫後 pull;link 的目標寫成 `/System/Volumes/Data` 的拼法)都回 `ok`。 + - 紀錄(`54d1775`,同一環境):868 項通過、0 項失敗。兩個重現用這份 script 重跑:上游把 `Tests/sub` 改成 `tests/sub` 之後 pull,`links` 回 `ok`;link 的目標寫成 `/System/Volumes/Data` 的拼法回 `ok`,對照(一般的拼法)也回 `ok`。 +- [x] 2.2 [after: 1.2] 依 design「落在規格目錄裡的 submodule 不搜尋,不論路徑叫什麼」與 Implementation Contract:`plugins/issue-driven-dev/scripts/spec-change.py` 新增 `in_spec_directory()`,`marker_files()` 在第 2 個條件之後多一個分支:往上走經過的目錄裡有規格目錄時,這個 submodule 不搜尋,也不列為搜尋不到;檔頭的說明加上這一點。驗證:`bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 全部通過。 + - 紀錄(`9fb5cc1`,同一環境):878 項通過、0 項失敗。 + +## 3. 文字 + +- [x] 3.1 [after: 2.2] 依 design「條文的三句(第七輪第 3、4 列)」與 Implementation Contract:`plugins/issue-driven-dev/CHANGELOG.md` 的 #548 條目講第 2、5 個條件與規格目錄的那兩句,與 `plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 第 57 列的註解,改成新的說法。驗證:`git diff` 對 CHANGELOG 只動 `[Unreleased]` 裡 #548 那一條;文字不含任何特定專案的名稱或本機路徑;測試仍然全部通過。 + - 紀錄:CHANGELOG 在 `e01674e` 與 `338da27` 各改一次,都只動 `[Unreleased]` 裡 #548 那一條(講第 2、5 個條件的一句;講規格目錄的一句);測試檔在 `e01674e` 只動第 57 列的註解。兩個 commit 之後測試檔分別是 868 與 878 項通過。 + +## 4. 收尾 + +- [x] 4.1 [after: 3.1] 依 design「照名稱比對而這次不動的地方」與 Implementation Contract 驗收:`bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 與 `bash .claude/scripts/tests/spectra-archive-post-ic/test.sh` 結束碼都是 0;逐一把 2.1 的每一處改回去或改壞(第 2 個條件改回字串比對、第 5 個條件改回字串相等、拿掉與 git 目錄的比對、往上走一律當成遇到頂層目錄、把頂層目錄與它的上層也拿去比對、與 git 目錄的比對改回名稱、檢查不到的目錄不略過、拿掉規格目錄的檢查),記下每一種讓哪些列的檢查失敗;在區分大小寫的磁碟上跑一次測試檔,確認略過的說明印出來、其餘全部通過;重量 git 呼叫次數;找有沒有第 60、61 列以外、答案從 `error` 變成 `ok` 的輸入;`python3 plugins/issue-driven-dev/scripts/spec-change.py links --base origin/main --cwd .` 回 `ok`。把結果與各環境下的檢查項數寫在這一項底下。 + - 驗收紀錄。這個 change 的文件、規格差異、測試與程式都由同一個協調者撰寫,沒有實作者模型,也沒有獨立讀者;第八輪 verify 是第一次獨立審查。環境:macOS、Python 3.13.5、git 2.55.0(另用 git 2.54.0 跑過測試檔)。 + - 整套測試,封存之前跑了兩次。在 `e01674e`(第二步之前):`bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 75 個 suite、0 個失敗,結束碼 0;`bash .claude/scripts/tests/spectra-archive-post-ic/test.sh` 141 項通過、0 項失敗。在 `f6fe368`(程式與測試的最後狀態):75 個 suite、0 個失敗,結束碼 0;post-ic 141 項通過、0 項失敗。 + - 各環境下測試檔的檢查項數(都是 0 項失敗):`spectra` 在 PATH 上、不分大小寫的磁碟 878(git 2.55.0 與 git 2.54.0 各一次);沒有 `spectra`、同一個磁碟 876;`spectra`、fixture 放在區分大小寫的 APFS 映像上 845,印出「submodule rows 60 to 64 were not run」;兩者都沒有 843。後三個數字是在 `338da27` 量的,它與 `f6fe368` 只差第 58 列 fixture 的那一行。 + - 變異,各在一份副本裡改 `9fb5cc1` 的 script 一處,記下失敗的檢查。(a) 第 2 個條件再用 `os.path.commonpath` 比對解析後的名稱:第 60 列的三項、它改用 `/System/Volumes/Data` 的兩項、第 63 列「問過那兩個目錄」的一項。(b) 第 5 個條件改回解析後的名稱相等:第 60 列的五項(含第二種拼法)與第 61 列的三項。(c) 不與那兩個 git 目錄比對:第 55、56、63 列與「git names no common directory」的檢查,共 17 項。(d) 走到根也算遇到頂層目錄:第 24 列三項、第 62 列五項。(e) 頂層目錄與它的上層也拿去與那兩個目錄比對:只有第 58 列的三項。(f) 那兩個 git 目錄改用解析後的名稱比對:只有第 63 列的四項。(g) 檢查不到的目錄讓往上走停下:第 17、34、38 列與第 57 列的對照各一項(原因從 not checked out 變成 path leaves the repository)。(h) 不與規格目錄比對:第 64、65 列各四項。第 60 列的輸入要 (a) 與 (b) 兩處都在才回 `ok`,所以兩種變異都讓它失敗;proposal 起草時寫的「只有第 60 列/只有第 61 列失敗」在動手量之前已更正。 + - 只推理過的配置,各用 4.1.0、第七輪的 script、`9fb5cc1` 的 script 跑。頂層目錄就是 git 目錄(`core.worktree` 指向它自己)、記錄的路徑走回頂層目錄:頂層沒有 `.git` 項目時三者是 `missing`、`error`(not checked out)、`error`(not checked out),是第 4 個條件,不是第 2 個;頂層有一個內容為 `gitdir: .` 的 `.git` 檔時是 `missing`、`ok`、`ok`。linked worktree 裡的主 checkout 被記成 gitlink(它的 git 目錄就是 common 目錄)、它的 commit 記的路徑指進那個 git 目錄:`missing`、`error`、`error`(path leaves the repository),在那個目錄的 git 呼叫是 0 次。第 59 列的形狀再指進主 repo 的 git 目錄:`missing`、`error`、`error`(path leaves the repository),0 次。 + - 落在規格目錄裡的 submodule,三份 script:gitlink 記在 `OPENSPEC/specs/sub`、clone 在 `openspec/specs/sub`:`missing`、`error`(not checked out)、`missing`,最後一個在那個目錄的 git 呼叫是 0 次(只改第 2、5 個條件的 `54d1775` 是 `ok`、5 次)。gitlink 記在 `lnk/sub`、`lnk` 指到 `openspec/vendor`:`missing`、`ok`、`missing`,0 次。對照,記在 `openspec/specs/sub`:三者都是 `missing`。主 repo 的檔案記在 `OPENSPEC/specs/cap/check.sh`:三者都是 `ok`(沒有改,見 design)。 + - 兩種拼法的其他探測(修改前後):`--cwd` 把頂層目錄或它底下的目錄寫成另一種大小寫,答案不變;同一個目錄以 `Tests/sub` 與 `tests/sub` 各記一次、都沒有標記時,修改前 `error`(第二個 not checked out),修改後 `missing`,兩個各搜尋一次。 + - 找答案從 `error` 變成 `ok` 的輸入(第七輪的 script 對 `9fb5cc1`):第 59 列的形狀、記錄的路徑用另一種大小寫寫頂層目錄的名稱(`error` 變 `ok`);兩個 gitlink 指同一個目錄、第二個的 commit 有標記(`error` 變 `ok`)。兩者都是第 60、61 列的形狀與既有各列的組合。link 用另一種大小寫指到主 repo 的 git 目錄本身、或指到頂層目錄的上一層(clone 在 repository 旁邊):前後都是 `error`(path leaves the repository)。規格目錄那一種在加上第二步之前會變成 `ok`,已由第二步處理。 + - git 呼叫次數(一個 repository、一個取出的 submodule):第七輪的 script 與修改後都是 20 次;標記在主 repo 時都是 11 次,那兩個問題沒有問。 + - 第七輪協調者的兩個重現,用修改後的 script:上游把 `Tests/sub` 改成 `tests/sub` 之後 pull,`links` 回 `ok`;link 的目標寫成 `/System/Volumes/Data` 的拼法回 `ok`。 + - 其他地方的同一句話:script 開頭的說明與函式的 docstring(`54d1775`、`9fb5cc1`)、CHANGELOG 的 #548 條目(`e01674e`、`338da27`)、測試檔第 57 列的註解(`e01674e`)。封存目錄、這個 change 與這條 requirement 所在的規格檔以外搜尋 `is not on the list`、`itself lies inside one of them`、`directories are compared, not names`、`reports it as the top of its own`:只有另一個 capability(idd-pr-hitl-modes)的兩句用到第一個詞,講的是別的清單。 + - 連結檢查,封存之前(`python3 plugins/issue-driven-dev/scripts/spec-change.py links --base origin/main --cwd .`):`{"status": "ok", "missing": [], "reason": ""}`。封存之後的結果寫在 issue 的 Implementation Complete 留言。 + - 沒有做的:測試只在 macOS 上跑過;git 2.45 到 2.53、Unicode 正規化的兩種寫法、Linux 的 bind mount 沒有試;第七輪第 5、6 列沒有在這條分支上改;主 repo 自己的檔案在規格目錄底下的排除仍照名稱、「只搜尋一次」的鍵仍是路徑字串(#559)。規格目錄那一步超出維護者點名的範圍,是協調者依委託做的決定(issue 留言 6894894048),要不要這樣由第八輪的裁定席與維護者決定。 diff --git a/openspec/changes/archive/2026-11-15-idd-548-links-unreadable-objects/.openspec.yaml b/openspec/changes/archive/2026-11-15-idd-548-links-unreadable-objects/.openspec.yaml new file mode 100644 index 00000000..171e1ddb --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-links-unreadable-objects/.openspec.yaml @@ -0,0 +1,6 @@ +schema: spec-driven +created: 2026-11-15 +created_by: che cheng <kiki830621@gmail.com> +created_with: claude +archived_by: che cheng <kiki830621@gmail.com> +archived_at: 2026-11-15 diff --git a/openspec/changes/archive/2026-11-15-idd-548-links-unreadable-objects/design.md b/openspec/changes/archive/2026-11-15-idd-548-links-unreadable-objects/design.md new file mode 100644 index 00000000..2c057ea6 --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-links-unreadable-objects/design.md @@ -0,0 +1,113 @@ +## Context + +第三輪 verify 找到的十六列裡,第 1 到 10 列與第 14 列在這張 issue 修;第 11 列的清單已補在 issue 的留言;第 12、13、15、16 列是分支之前就有的事,開在 #558。維護者選定了第 1 列與第 3 列的做法(issue 留言 6885330621)。這份 design 只寫這次要決定的事;六個條件、submodule 用的 git 包裝、版本檢查、原因的列舉都不變。 + +量測。標「協調者」的是這次自己在臨時 repo 上跑的(git 2.55.0,macOS);標「審查者」的是第三輪的 devil's advocate 與 logic 兩席量到的(git 2.55.0 與 Apple 的 git 2.54.0,macOS),協調者沒有重做: + +- 物件檔長度為零(協調者;第 50 列的 fixture 每次執行都確認前兩點):`git rev-list --objects --no-walk --missing=print` 回 0、沒有 `?` 行;`git grep` 印一行 error、結束碼 0 或 1;把物件 id 交給 `git cat-file --batch-check`,回報 `<id> missing`。沒有讀取權限的物件檔也是這三個結果(審查者)。 +- 物件檔不是壓縮資料:`git grep` 以 128 結束(協調者)。夠大的檔案內容在最後一個位元組損壞時,`--batch-check` 回報「在」、`git grep` 以 128 結束(協調者;第 54 列的 fixture 每次執行都確認),所以搜尋的結束碼仍然要看。只有十幾個位元組的內容做同樣的損壞時,`--batch-check` 回報的是 missing(協調者,第一版 fixture 因此不能用)。 +- `--batch-check` 在部分 clone 裡會抓取,除非設了 `GIT_NO_LAZY_FETCH=1`;`rev-list --missing=print` 不設也不抓。五萬個檔案的 commit,`--batch-check` 約 0.07 秒(都是審查者的量測)。 +- 把 `rev-list` 的整行(id 加檔名)交給 `--batch-check`,每個有檔名的物件都會被回報成 missing,所以只能送 id(審查者;這次的變異 P16 得到同樣的結果)。 +- 搜尋中途中止時,`git grep` 有時已經印出標記那一行、有時沒有;兩千個檔案的 submodule 上,上一輪的 script 30 次裡 6 次回 `ok`(協調者)。 + +## Goals / Non-Goals + +**Goals** + +- 「在、但打不開」的物件與缺少的物件同樣算讀不完。 +- 同一個 repo 的同一個狀態,每次執行的答案相同。 +- requirement 的每一句都與程式一致,每一列 Example 的檢查都執行它寫的情況。 +- 測試檔不受呼叫者的 git 環境影響。 + +**Non-Goals** + +- 主 repo 這一層的行為(#556、#558)。 +- 抓出「物件 id 底下放的是另一個合法物件」:git 讀取時不核對雜湊,任何做法都看不出來,第二輪的 script 也看不出來。 + +## Decisions + +### 用 cat-file --batch-check 確認物件打得開 + +`submodule_lacks_objects(directory, rev)` 取代原來在 `marker_files()` 裡的那兩行: + +1. `rev-list --objects --no-walk --missing=print <rev>`。結束碼不是 0 → 缺。 +2. 輸出只在 `\n` 切開。整行是 `?` 加十六進位字元的 → 缺。其餘每一行取第一個空白之前的 id。 +3. 所有 id 以換行分隔交給 `cat-file --batch-check` 的標準輸入。結束碼不是 0、回答的行數與 id 數不同、或任何一行以 ` missing` 結尾 → 缺。 + +第 3 步經過 `submodule_git()`,所以有 `GIT_NO_LAZY_FETCH=1`、`safe.bareRepository=explicit`,而且只在版本檢查通過之後才會走到。`submodule_git()` 多一個 `stdin` 參數。 + +替代做法是重新讀錯誤輸出、只認 `error:` 與 `fatal:` 開頭的行。不採用:devil's advocate 找到兩個完整的 submodule 仍會被誤判的例子(`.gitattributes` 的一行、指向不存在目錄的 alternates)。 + +### 搜尋中途中止時不採用它印出的內容 + +submodule 的 `git grep` 以 0、1 以外的結束碼結束時,`marker_files()` 不逐行讀它的輸出,直接把這個 submodule 記為搜尋不了,然後照舊列它的 gitlink。這是第二輪 script 的答案(一律 `error`),差別只在第二輪之後仍然會往下走到它底下的 submodule。主 repo 的搜尋中止時照舊是 `error`。 + +替代做法是讓 submodule 的搜尋只用一個執行緒(`--threads=1`)。不採用:答案仍然取決於損壞的物件排在標記之前還是之後,只是變成固定的;而且 requirement 要多寫一條關於讀取順序的規則。 + +requirement 因此改成「搜尋跑完時(結束碼 0 或 1)找到的檔案才確定這個 Example」。缺一個檔案內容時 `git grep` 不會中止,所以第 42、45 列不變。 + +### 句子與測試各自收窄到做得到的範圍 + +- 非 UTF-8 路徑:只有規格目錄的 `specs/` 底下(base 或 head)才回 `error`;其他位置不影響答案,補一列固定。 +- 巢狀 submodule:清單來自 `ls-tree -r`,也就是每一個 tree 的列表;任何一個 tree 讀不到,清單就拿不到。不改成逐層列出:那會讓缺 subtree 的 submodule 多一種答案,而方向只是少回一個 `error`。補第 53 列固定現在的行為。 +- 第 49 列的文字改成它的 fixture 造出來的情況(不是壓縮資料、搜尋以 128 結束)。「在、但打不開」由新的第 50 列負責。第 49 列的物件現在也會被 `--batch-check` 回報成缺,所以「只有搜尋的結束碼看得出來」改由新的第 54 列固定:物件的內容在最後一個位元組損壞,git 列得出它、也打得開,搜尋仍以 128 結束。 +- 主 repo 的原因:行為不變。檢查改用一個假的 git,它的搜尋以 128 結束並寫出 300 個字元、每四個一組都不同的訊息;原因必須等於前綴加上前 200 個字元。 + +### 測試檔自己的環境 + +- 開頭讀一次 `git version`,比 2.45 舊就以一句話停下。 +- 設定隔離的那一行之後,unset 會改變 git 讀哪個 repo 或寫多少訊息的變數。需要這些變數的列自己在那一次呼叫設定。 +- `setup_failed` 在子 shell 裡(`BASH_SUBSHELL` 大於 0)時,另外對主 shell 送 TERM;主 shell 的 TERM trap 以 1 結束。bash 3.2 也有 `BASH_SUBSHELL`。 + +### 每一處改動各有一種變異 + +驗收時在上一個 change 的 34 種之外加上這些,每一種都要有檢查失敗: + +- 不呼叫 `--batch-check`(第 50 列)。 +- `rev-list` 的輸出改回用 `splitlines()` 切(第 51 列)。 +- 搜尋中止時仍然讀它印出的內容(第 52 列)。 +- 主 repo 的原因改留後 200 個字元(「what the link check reports」的那一列)。 +- `repo_top()` 去掉所有結尾的換行(「top directory names」名稱以換行結尾的三列)。 +- 搜尋的結束碼不再讓 submodule 算搜尋不了,只看缺不缺物件(第 54 列)。 +- 把 `rev-list` 的整行而不是 id 交給 `--batch-check`(多數 submodule 的列)。 + +上一個 change 的兩種明文例外不變:留著 `GIT_INDEX_FILE`;submodule 的 tree 列不出來時不另外記原因。第 53 列走到的正是後一種的那個分支,但那時這個 submodule 已經因為缺物件被記為搜尋不了,所以拿掉那一句答案不變。 + +## Implementation Contract + +呼叫端看到的行為(前三個 change 的契約沒有提到的部分不變): + +- submodule 裡帶標記的檔案,它的物件檔是空的:`error`,點名那個 submodule,原因是 `its recorded commit could not be read`。上一輪是 `missing`。 +- 完整的 submodule 裡有檔名含 CR 緊接問號、哪裡都沒有標記:`missing`。上一輪是 `error`。 +- 標記所在的 submodule 搜尋到一半就中止(結束碼 128):每次都是 `error`。上一輪有時是 `ok`。 +- 規格目錄底下、`specs/` 以外的非 UTF-8 路徑:答案不受影響(三輪以來都是這樣,現在 requirement 這樣寫)。 +- 名稱以換行結尾的頂層目錄:`links`、`archived`、`preflight` 的答案與放在一般名稱的同一個 repo 相同(上一個 change 起就是這樣,現在有列固定)。 +- 其餘輸入的輸出與結束碼不變。沒有 gitlink 的 repo 與標記都在主 repo 的 repo,輸出與 `6ed8dec` 逐位元組相同。 + +驗收條件: + +- Example 新增與改寫的每一列各有檢查;第 50、51、52 列的檢查在 `726050b` 的 script 上失敗。 +- 上一節列的七種變異各自至少一項檢查失敗;34 種舊變異的結果不比上一次差。 +- `726050b`、`7ad9152`、`afd0021`、`6ed8dec` 的測試檔配新 script 全部通過。 +- 整套測試通過。 + +範圍: + +- In scope:`spec-change.py` 的 `submodule_git()`、`marker_files()` 與新函式;測試檔;requirement 的兩條;`references/spec-wrapper.md`;CHANGELOG 的 #548 條目。 +- Out of scope:主 repo 的搜尋與原因文字;`archived`、`preflight` 的邏輯;時間上限;封存的檔案。 + +## Risks / Trade-offs + +- `--batch-check` 多開一個行程、多讀一次每個物件的檔頭。量測的成本很小,而且每個 submodule 的每個 commit 只做一次。 +- 搜尋中止時一律 `error`,會讓「標記其實讀得到、但別的檔案損壞到讓搜尋中止」的 repo 得到 `error` 而不是 `ok`。這是保守的方向,也是第二輪的答案。 +- 測試檔在 git 比 2.45 舊的機器上整個不跑。先前是 55 項失敗而沒有說明。 +- 第 50、52、54 列的 fixture 各自先確認 git 的行為與上面的量測相同,不同就讓整個測試停下。這些量測都在 macOS 上;這個 repo 的 CI 在 Linux 上跑,而這條分支沒有 PR,CI 還沒有跑過。 +- 名稱不是合法 UTF-8 的頂層目錄沒有測試。 + +## Migration Plan + +沒有資料或設定要遷移。合併並發布之後,使用者更新 plugin 即可。 + +## Open Questions + +- 主 repo 的原因文字要留錯誤輸出的哪一端(#558 第 1 點)。決定之後,這次加的檢查要跟著改。 diff --git a/openspec/changes/archive/2026-11-15-idd-548-links-unreadable-objects/proposal.md b/openspec/changes/archive/2026-11-15-idd-548-links-unreadable-objects/proposal.md new file mode 100644 index 00000000..02cb5f47 --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-links-unreadable-objects/proposal.md @@ -0,0 +1,64 @@ +**GitHub-side tracker**: #548 + +## Problem + +`idd-548-links-search-completeness` 修了第二輪 verify 的七列。第三輪 verify(issue 留言 6881182720)確認其中五列修好了,但那次修正本身引入了新的問題,協調者重現了其中四項: + +1. submodule 裡一個檔案內容的物件「在、但打不開」時(物件檔長度是零,或沒有讀取權限),`links` 回 `missing`;第二輪的 script 回 `error`。那個檔案正好帶標記時,也被說成沒有標記。 +2. submodule 記錄的 commit 裡有檔名含 CR 緊接問號時,完整的 submodule 被算成缺物件,`links` 多回一個 `error`。 +3. submodule 的搜尋中途以 128 結束、而標記就在那個 submodule 裡時,同一個 repo 重複執行,有時回 `ok`、有時回 `error`。 +4. requirement 說規格目錄底下任何不是合法 UTF-8 的路徑都回 `error`,程式只看 `specs/` 底下。 +5. 主 repo 搜尋失敗的那一列寫「前 200 個字元」,沒有檢查分辨得出前 200 與後 200。 +6. 另有六項 LOW 與 INFO:一句關於巢狀 submodule 的話比程式寬;測試檔沒有清掉繼承的 git 環境變數;測試檔沒有寫明需要 git 2.45;`commit` 的失敗檢查在命令替換裡只結束子 shell;頂層目錄的 requirement 少一個邊界的列;`references/spec-wrapper.md` 的提醒少說兩件事。 + +## Root Cause + +- 第 1 項與第 3 項是同一個修正的兩個副作用。上一個 change 為了不把任何錯誤輸出都當成讀不到,改成完全不讀 submodule 搜尋的錯誤輸出、改問 `git rev-list --missing=print` 缺哪些物件,並且先讀搜尋印出的內容、沒找到才看結束碼。`rev-list` 只看物件存不存在;物件檔在而打不開時,`git grep` 只印一行 error、跳過那個檔案、結束碼仍是 0 或 1,所以沒有訊號留下來。`git grep` 中途中止之前印出了多少,取決於它的工作執行緒。 +- 第 2 項:用 `splitlines()` 切 `rev-list` 的輸出,它在單獨的 CR 也會斷行。 +- 第 4、5 項與巢狀 submodule 那一句:句子寫得比程式或測試寬。這與第二輪的第 1 列是同一類問題。 +- 測試檔的三項:隔離了 git 的設定,沒有隔離 git 的環境變數;失敗時停下的檢查沒有考慮命令替換。 + +## Proposed Solution + +維護者 2026-11-15 的決定(issue 留言 6885330621):修完再審一輪;第 1 項用 `git cat-file --batch-check`;第 3 項改成搜尋中途中止時不採用它印出的內容。 + +- 新函式 `submodule_lacks_objects()`:`rev-list` 的輸出只在換行切開,缺物件的行比對成問號加物件 id;再把列出的物件 id 交給 `git cat-file --batch-check`(經過關掉 lazy fetch 的同一個包裝),回報 missing 的算成缺物件。 +- submodule 的搜尋以 0、1 以外的結束碼結束時,不讀它印出的內容;這個 submodule 算搜尋不了。主 repo 不變。 +- requirement 的四處文字改成與程式一致:非 UTF-8 路徑限定在 `specs/` 底下;巢狀 submodule 的清單來自「每一個 tree 的列表」;缺物件的定義加上打不開的物件;找到的檔案在搜尋跑完時才確定 Example。第 49 列改寫成它的 fixture 實際造出來的情況。 +- Example「markers in submodules」加第 50 到 54 列;「what the link check reports」加一列;「top directory names」加三列(名稱以換行結尾)。 +- 主 repo 那一列的檢查改用一個回報已知 300 個字元訊息的 git,逐字比對前 200 個字元。行為不變;要不要改留結尾,留在 #558 決定。 +- 測試檔:開頭確認 git 版本、清掉繼承的 git 環境變數;`setup_failed` 在命令替換裡也讓整個測試停下。 +- 文件:`references/spec-wrapper.md` 的提醒補上兩件事;CHANGELOG 的 #548 條目與 `spec-change.py` 檔頭改成最後的行為。 + +## Non-Goals + +- 不改主 repo 這一層的行為(#556、#558):讀不到的檔案內容回什麼、原因文字留哪一端、lazy fetch、時間上限,都不在這次。 +- 不處理名稱不是合法 UTF-8 的頂層目錄:這台機器的檔案系統不接受這種名稱,寫了測試也跑不到,所以不新增列,只在實作摘要裡說明這個輸入的答案也變了。 +- 不重寫封存的檔案:上一個 change 的 design 與 tasks 不改,更正寫在這個 change 與 issue 的留言。 + +## Success Criteria + +- 第三輪第 1、2、3 列的重現在新 script 上回 `error`、`missing`、每次都 `error`;新測試在上一輪的 script 上,第 50、51、52 列各有檢查失敗。 +- `bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 全部通過;`726050b`、`7ad9152`、`afd0021`、`6ed8dec` 的測試檔配新 script 也全部通過。 +- 沒有 gitlink 的 repo 與標記都在主 repo 的 repo,新 script 與 `6ed8dec` 的 script 輸出逐位元組相同。 +- 變異測試:這次改的每一處各有一種變異,都有檢查失敗;逐項結果寫進 tasks 的驗收紀錄。 +- 整套測試通過。 + +## Capabilities + +### New Capabilities + +(none) + +### Modified Capabilities + +- `spec-on-every-issue`: requirement「Added and modified requirements carry an executable check」改寫非 UTF-8 路徑、巢狀 submodule、缺物件與搜尋中止的四處,Example 加列;requirement「The repository's top directory is read as git prints it」加上名稱以換行結尾的情況。 + +## Impact + +- Affected specs: spec-on-every-issue(兩個 MODIFIED requirement) +- Affected code: + - Modified: plugins/issue-driven-dev/scripts/spec-change.py + - Modified: plugins/issue-driven-dev/scripts/tests/spec-change/test.sh + - Modified: plugins/issue-driven-dev/references/spec-wrapper.md + - Modified: plugins/issue-driven-dev/CHANGELOG.md diff --git a/openspec/changes/archive/2026-11-15-idd-548-links-unreadable-objects/specs/spec-on-every-issue/spec.md b/openspec/changes/archive/2026-11-15-idd-548-links-unreadable-objects/specs/spec-on-every-issue/spec.md new file mode 100644 index 00000000..f149c018 --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-links-unreadable-objects/specs/spec-on-every-issue/spec.md @@ -0,0 +1,135 @@ +## MODIFIED Requirements + +### Requirement: Added and modified requirements carry an executable check + +`scripts/spec-change.py links --base <rev>` SHALL compare the files under `openspec/specs/` at `<rev>` and at `--head` (default `HEAD`). For every requirement that is new or whose text differs between the two, it SHALL require one of two things: at least one `##### Example:` under the requirement, where each such Example has a title that is unique within its capability and a tracked file at the head revision, outside `openspec/` and not ending in `.md`, that contains the marker `spec-example: <capability> / <Example title>` (a tracked file of a submodule counts, as the paragraph "Submodules" below describes); or a line under the requirement that starts with `No executable check:` followed by a reason. A requirement that does not differ SHALL NOT be checked. A marker counts only when nothing but whitespace, or the comment closer `-->` or `*/`, follows the Example title on its line. Lines inside a code fence are not read as `##### Example:` or `No executable check:` lines; a fence opened by three or more backticks or tildes, at any indentation (as inside a list item), closes only on a line of the same character, at least as long, with nothing but whitespace after it; lines end only at `\n`, `\r\n` or `\r`. A requirement heading indented by up to three spaces SHALL be read as a requirement, as Spectra reads it. Paths SHALL be read as git stores them, never in git's quoted form, so a capability whose directory name is not ASCII is checked like any other. Two requirements with the same name in one capability SHALL make the command print `error`. So SHALL a code fence at the head revision that never closes, since the requirements after it would go unchecked. Outside code fences, a heading that starts with `### Requirement` but does not have the form `### Requirement: <name>` with a non-empty name SHALL make the command print `error`, and so SHALL a head revision at which the spec directory's `specs/` holds no tracked file, and a path under the spec directory's `specs/` that is not valid UTF-8 (the reason says so and carries no text of an exception). Such a path elsewhere under the spec directory does not change the answer. The command SHALL print one JSON line with `status` (`ok`, `missing` or `error`) and a list naming each requirement or Example that lacks its check, and SHALL exit 0, 1 or 2 in that order. `--base` is required: the caller names the range, so that a run on the default branch is checked against the commit it started from. The marker ties an Example to a test by name only; whether the test exercises what the Example states is judged by the reviewers of `idd-verify`. + +Submodules. The tracked files at the head revision include the tracked files of every submodule of the repository at the commit that the head revision records for it, and in the same way the files of a submodule of a submodule. The command SHALL read that recorded commit, not the commit the submodule's working tree is on. It SHALL find the submodules itself, from the entries of the head revision's tree that record a commit; it SHALL NOT rely on git's own recursion into submodules, which passes over a submodule that is not checked out without saying so; the answer SHALL be the same whether or not the git configuration turns that recursion on (`submodule.recurse`). A file of a submodule is named by the submodule's path followed by the file's path, and the two exclusions (under the spec directory, ending in `.md`) apply to that name. A submodule whose own path is under the spec directory SHALL NOT be searched and SHALL NOT count as one that could not be searched: none of its files could count. + +Order of the search. For each Example the command SHALL search the main repository first. When the marker is found there, the Example has its check and the command SHALL NOT run git in any submodule for it, so for a repository whose markers are all in its own files no entry that records a commit is listed and no submodule is examined, whatever its head revision records. Only when the marker is not found in the main repository are the submodules searched, and a marker found in one submodule settles the Example whatever the state of the others. When the marker of an Example is found, the Example has its check, whether or not every submodule could be searched. The submodules inside a submodule are read from a listing of every tree of its recorded commit, and that listing is made only when the outer one meets its own six conditions. Each of them is then searched whenever its own six conditions hold, also when the search of the outer one failed. When the listing fails, because a tree of the recorded commit cannot be read, the submodules inside it are unknown, even when the top tree shows them. + +Which submodules can be searched. A submodule SHALL be searched only when all six of these hold: (1) its path, as the tree records it, is relative and has no empty, `.` or `..` component; (2) its directory, after symbolic links are resolved, lies inside the working tree of the main repository; (3) the directory itself is not a symbolic link; (4) the directory holds an entry named `.git` of its own; (5) git, run in the directory, reports it as the top of its own working tree; (6) its object store holds the recorded commit. The command SHALL NOT run git in a directory that fails any of the first four: a directory of ordinary tracked files can be shaped like a git directory, and git would read, and act on, the configuration it holds. Nor SHALL it run git in the directory of any submodule when git is older than 2.45, the first version that honours `GIT_NO_LAZY_FETCH`, or when the version cannot be read: a submodule for which the first four hold then counts as one that could not be searched. In the directory of a submodule the command SHALL run git with `safe.bareRepository` set to `explicit`, with lazy fetching turned off (`GIT_NO_LAZY_FETCH=1`), and with the variables `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, `GIT_OBJECT_DIRECTORY`, `GIT_ALTERNATE_OBJECT_DIRECTORIES` and `GIT_COMMON_DIR` removed from the environment it inherited. Before it searches a submodule the command SHALL ask git which objects of the recorded commit (its trees and the contents of its files) the object store lacks or cannot open, without fetching any: an object whose file is present but cannot be opened (for example an empty file) counts as lacking. A submodule is searched even when some are lacking, and a file that counts, found by a search that ran to its end (exit code 0 or 1), settles the Example. What a search printed before it ended with another exit code SHALL NOT be used, so that the answer for one state of the repository is the same on every run. When no file that counts is found in it, the submodule counts as one that could not be searched if its object store lacks an object of the recorded commit, if the search exits with a code other than 0 or 1, or if the trees of the recorded commit cannot all be listed. What git writes to its error stream SHALL NOT change whether a submodule counts as searched, nor the reason reported for it. In the main repository a search that exits with a code other than 0 or 1 is `error`, as before; its reason is `git grep failed: ` followed by the first 200 characters of what git wrote to its error stream, also as before. + +What is reported. When the marker is not found and every submodule was searched, the Example is reported as lacking its check, as before. When it is not found and at least one submodule could not be searched, the command SHALL print `error` and name the first such Example it meets, the submodules that could not be searched and the reason for each: an Example whose candidate files were not all read is not reported as lacking its check. The submodules are named by path, in the order of their paths and joined by `; `; a submodule of a submodule is named by its path under the outer one; when more than five could not be searched, the first five are named and the number of the others is stated; a path longer than 200 characters is cut to its first 200 followed by `...`. The reason is one of six: the path leaves the repository (conditions 1 and 2); the submodule is not checked out (conditions 3 and 4, or git names another directory as the top); git is older than 2.45 (stated also when its version cannot be read); git refused to open it (the git command of condition 5 fails); the recorded commit is not in its object store (condition 6); the recorded commit could not be read (its object store lacks or cannot open an object of it, or the search or the listing of its trees failed). The reason given for a submodule SHALL NOT carry text from git's error stream. The path of a submodule that is not valid UTF-8 is handled like any other path, and the command still prints one JSON line. A repository whose head revision records no submodule is searched in its own tracked files only: none of the rules for submodules changes its answer. + +#### Scenario: An Example without a test is reported + +- **GIVEN** a range that adds a requirement with one Example titled `status by exit code` to the capability `local-ci-gate` +- **AND** no tracked file outside `openspec/` contains `spec-example: local-ci-gate / status by exit code` +- **WHEN** `spec-change.py links` runs on that range +- **THEN** it prints `status` `missing`, names that Example, and exits 1 + +##### Example: what the link check reports + +| Requirement in the range | Examples | Marker at the head revision | `No executable check:` line | `status` | +| --- | --- | --- | --- | --- | +| added | one | in `scripts/tests/x/test.sh` | absent | `ok` | +| added | one | absent | absent | `missing` | +| added | one | only in a file under `openspec/` | absent | `missing` | +| added | one | only in a file ending in `.md` | absent | `missing` | +| added | none | not applicable | absent | `missing` | +| added | none | not applicable | present, with a reason | `ok` | +| added | none | not applicable | present, with nothing after the colon | `missing` | +| added | one, with no title | not applicable | absent | `missing` | +| added | two with the same title as an Example elsewhere in the capability | present | absent | `missing` | +| changed | two | present for one, absent for the other | absent | `missing` | +| unchanged, with no Example | none | not applicable | absent | `ok` | +| removed in the range | not applicable | not applicable | not applicable | `ok` | +| no file under `openspec/specs/` differs | not applicable | not applicable | not applicable | `ok` | +| added | one | only a marker naming a longer title that starts with this one | absent | `missing` | +| added, under the heading `### Requirement Missing colon` | not applicable | not applicable | not applicable | `error` | +| any; `openspec/specs/` holds no tracked file at the head revision | not applicable | not applicable | not applicable | `error` | +| added, its only `##### Example:` line inside a code fence | none outside fences | not applicable | absent | `missing` | +| added, its only `No executable check:` line inside a code fence | none | not applicable | only inside a fence | `missing` | +| added, after a fence of four backticks that a line of three backticks does not close | its Example inside that fence | not applicable | absent | `missing` | +| added, under the heading ` ### Requirement: Alpha` (two leading spaces) | none | not applicable | absent | `missing` | +| added, its only `No executable check:` line inside a fence indented four spaces in a list item | none | not applicable | only inside that fence | `missing` | +| added, in a capability whose directory name is not ASCII (`中文能力`) | none | not applicable | absent | `missing` | +| added, in a capability whose directory name holds a double quote (`quo"te`) | none | not applicable | absent | `missing` | +| added, in a capability whose directory name is not valid UTF-8 | not applicable | not applicable | not applicable | `error`, with a reason that says so | +| added; a tracked path under the spec directory but outside `specs/` is not valid UTF-8 | one | in `scripts/tests/x/test.sh` | absent | `ok` | +| added; a tree of the head revision outside the spec directory cannot be read | one | absent | absent | `error`; the reason is `git grep failed: ` followed by the first 200 characters of what git wrote to its error stream | +| added twice with the same name in one capability | not applicable | not applicable | not applicable | `error` | +| any, after a code fence that never closes | not applicable | not applicable | not applicable | `error` | +| `--base` names a revision that does not exist | not applicable | not applicable | not applicable | `error` | +| `--base` is not given | not applicable | not applicable | not applicable | usage error, exit 64 | + +##### Example: markers in submodules + +| Where the marker of the Example is at the head revision | Submodules recorded at the head revision | `status` | +| --- | --- | --- | +| in a tracked file of a submodule, at the commit the head revision records | one, checked out | `ok` | +| in a tracked file of a submodule of a submodule | both checked out | `ok` | +| in a tracked file of a submodule whose path holds a space | one, checked out | `ok` | +| only in the recorded commit of a submodule whose working tree is on a later commit without it | one, checked out | `ok` | +| only in a later commit of a submodule, which its working tree is on, not in the recorded commit | one, checked out | `missing` | +| only in a file of a submodule that ends in `.md` | one, checked out | `missing` | +| nowhere | one, checked out | `missing` | +| nowhere in the main repository | one, not checked out | `error`, naming the Example and the submodule's path | +| in a tracked file of the main repository | one, not checked out | `ok` | +| nowhere in the main repository | one, checked out, whose object store lacks the recorded commit | `error`, naming the Example and the submodule's path | +| in a tracked file of the main repository | one, checked out, whose object store lacks the recorded commit; `submodule.recurse` is true in the repository's git configuration | `ok` | +| nowhere in the main repository | one, checked out, whose object store lacks the recorded commit; `submodule.recurse` is true in the repository's git configuration | `error`, naming the Example and the submodule's path | +| only in the recorded commits of two submodules | two, neither checked out | `error`, naming the Example and both paths, joined by `; ` | +| only in a submodule of a submodule | the outer one checked out, the inner one not | `error`, naming the Example and the inner submodule by its path under the outer one | +| only in a tracked file of a submodule that is mounted under `openspec/` | one, checked out | `missing` | +| in a tracked file of the main repository | one whose path is not valid UTF-8, not checked out | `ok` | +| nowhere | one whose path is not valid UTF-8, not checked out | `error` on one JSON line, exit 2 | +| in a tracked file of the main repository | one, checked out, holding the recorded commit but not the tree of that commit | `ok` | +| nowhere in the main repository | one, checked out, holding the recorded commit but not the tree of that commit | `error`, naming the Example and the submodule's path, with no text from git's error stream | +| nowhere | one, checked out, whose object store lacks the content of one file of the recorded commit | `error`, naming the Example and the submodule's path, with no text from git's error stream | +| nowhere | one, checked out, whose recorded commit records a second submodule; at that second path the working tree holds ordinary files shaped like a git directory (`HEAD`, `config`, `objects/`, `refs/`) and no `.git` entry, and that `config` names a command to run | `error`, naming the second path as not checked out; the command named in that `config` does not run | +| in a tracked file of the main repository | the same two, with the same files at the second path | `ok`; no git command runs in the directory of a submodule, and the command named in that `config` does not run | +| only in a repository outside the main repository, at a path with a `..` component that the head revision's tree records as a submodule | that one | `error`, naming the path as one that leaves the repository; the same answer when nothing is at that outside path | +| only in a repository outside the main repository, reached through a symbolic link in the working tree that is part of a recorded submodule path | that one | `error`, naming the path as one that leaves the repository | +| in a tracked file of a submodule whose path ends in a space | one, checked out | `ok` | +| nowhere | one, not checked out, mounted under `openspec/` | `missing` | +| only in a tracked file of a submodule | one, checked out elsewhere inside the working tree of the main repository, whose own directory is a symbolic link to that checkout | `error`, naming the Example and the submodule's path as not checked out | +| in a tracked file of a submodule | one, checked out; the variable `GIT_DIR` is set to the git directory of the main repository | `ok` | +| only in the recorded commits of seven submodules | seven, none checked out | `error`, naming the Example, the first five paths in order and the number of the other two | +| nowhere | one whose directory holds a `.git` entry that git cannot open | `error`, naming the Example and the submodule's path as one git refused to open | +| nowhere | one whose directory holds an empty `.git` directory and, beside it, ordinary files shaped like a git directory (`HEAD`, `config`, `objects/`, `refs/`) whose `config` names a command to run | `error`, naming the submodule's path as one git refused to open; the command named in that `config` does not run | +| in a tracked file of the main repository | one, checked out as a partial clone that never fetched the file contents of the recorded commit | `ok`; nothing is fetched into the submodule | +| nowhere | one, checked out as a partial clone that never fetched the file contents of the recorded commit | `error`, naming the Example and the submodule's path; nothing is fetched into the submodule | +| nowhere | one, not checked out, whose path is longer than 200 characters | `error`, naming the first 200 characters of the path followed by `...` | +| in a tracked file of one submodule | two; the one with the marker checked out, the other not | `ok` | +| only in a file ending in `.md` of a submodule | one, checked out, whose object store lacks the content of another file of the recorded commit | `error`, naming the Example and the submodule's path | +| only in a tracked file of a submodule | one whose `.git` entry git opens, with the working tree of that git directory set to the parent directory, so that git names the parent as the top | `error`, naming the Example and the submodule's path as not checked out | +| only in a submodule of a submodule | three recorded paths: `a`, checked out; its own submodule `a/inner`, not checked out; and `a-b`, not checked out | `error`, naming `a-b` before `a/inner` | +| nowhere | one, at a path with a `.` component that the head revision's tree records | `error`, naming the path as one that leaves the repository | +| in a tracked file of a submodule | one, checked out; the six variables named above are all set to the git directory, working tree, index and object store of the main repository | `ok` | +| only in the recorded commit of a submodule, which the checked-out submodule's own object store lacks | one, checked out; the variable `GIT_ALTERNATE_OBJECT_DIRECTORIES` names an object store that holds that commit | `error`, naming the Example and the submodule's path, with the recorded commit as not in its object store | +| only in a submodule of a submodule, checked out and complete | the outer one checked out, its object store lacking the content of one unrelated file of its recorded commit | `ok` | +| nowhere | the same two | `error`, naming the Example and the outer submodule's path only, with its recorded commit as one that could not be read | +| in a tracked file of one submodule | two; the other one is not checked out and comes first in the order of the paths | `ok` | +| in a tracked file that counts, of a submodule whose object store lacks the content of another file of the recorded commit | one, checked out | `ok` | +| nowhere | one, checked out, holding every object of the recorded commit; git writes to its error stream during the search (`GIT_TRACE=1`) | `missing` | +| only in a tracked file of a submodule | one, checked out; git reports a version older than 2.45, or one that cannot be read | `error`, naming the Example and the submodule's path with git as older than 2.45; no git command runs in the directory of the submodule | +| in a tracked file of the main repository | one, checked out; git reports a version older than 2.45 | `ok` | +| nowhere | one, checked out, whose object store holds a damaged copy of the content of one file of the recorded commit (the object file is present and is not a compressed object, so the search ends with exit code 128) | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read | +| only in a tracked file of a submodule; the object that holds the content of that file is present but empty (zero bytes), so the search skips the file and ends with exit code 0 or 1 | one, checked out | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read | +| nowhere | one, checked out, holding every object of the recorded commit; one of its tracked files has a name with a carriage return followed by `?` | `missing` | +| in a tracked file of a submodule | one, checked out, whose object store holds a damaged copy of the content of another file, so that the search ends with exit code 128 | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read; the same answer on each of three runs | +| only in a submodule of a submodule, checked out and complete | the outer one checked out, its object store lacking a tree below the top of its recorded commit | `error`, naming the Example and the outer submodule's path only, with its recorded commit as one that could not be read | +| nowhere | one, checked out; the object that holds the content of one file is damaged in its body, so that git lists it and opens it, and the search ends with exit code 128 | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read | + +### Requirement: The repository's top directory is read as git prints it + +The subcommands of `scripts/spec-change.py` that take `--cwd` (`links`, `archived` and `preflight`) SHALL take the repository's top directory from `git rev-parse --show-toplevel` as git prints it, removing only the line end that git adds: a directory name that ends in a space, or in a line feed of its own, is kept. The three SHALL read it in the same way, so that they agree about the same `--cwd`. + +#### Scenario: A repository whose directory name ends in a space + +- **GIVEN** a repository whose top directory name ends in a space, with a requirement added in a range and its marker in a tracked test file +- **WHEN** `spec-change.py links` runs with `--cwd` at that directory +- **THEN** it prints `status` `ok` and exits 0, as it does for a copy of the repository at a path that does not end in a space + +##### Example: top directory names + +| Subcommand | Top directory of the repository | Answer | +| --- | --- | --- | +| `links` | the name ends in a space | the same JSON line and exit code as for a copy whose name does not end in a space (`ok`) | +| `archived` | the name ends in a space | the same JSON line and exit code as for that copy (`pass`) | +| `preflight` | the name ends in a space | the same `status` and exit code as for that copy | +| `links` | the name ends in a line feed | the same JSON line and exit code as for a copy whose name does not end in one (`ok`) | +| `archived` | the name ends in a line feed | the same JSON line and exit code as for that copy (`pass`) | +| `preflight` | the name ends in a line feed | the same `status` and exit code as for that copy | diff --git a/openspec/changes/archive/2026-11-15-idd-548-links-unreadable-objects/tasks.md b/openspec/changes/archive/2026-11-15-idd-548-links-unreadable-objects/tasks.md new file mode 100644 index 00000000..7fba0768 --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-links-unreadable-objects/tasks.md @@ -0,0 +1,64 @@ +## 1. 測試先行 + +- [x] 1.1 第三輪找到的行為各有可執行的檢查:在 `plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 為 requirement「Added and modified requirements carry an executable check」的 Example「markers in submodules」第 50 到 54 列、「what the link check reports」新增的一列(`specs/` 以外的非 UTF-8 路徑)與主 repo 搜尋失敗的那一列(前 200 個字元)各加或改檢查;為 requirement「The repository's top directory is read as git prints it」的 Example「top directory names」名稱以換行結尾的三列各加檢查。列的文字與檢查的範圍依 design「句子與測試各自收窄到做得到的範圍」。同一項裡,依 design「測試檔自己的環境」:開頭確認 git 版本、清掉繼承的 git 環境變數、`setup_failed` 在命令替換裡也讓整個測試停下。驗證:改 `spec-change.py` 之前執行整個檔案,第 50、51、52 列各至少一項檢查失敗;第 53、54 列、非 UTF-8 那一列、前 200 個字元、名稱以換行結尾的三列通過(它們固定現在的行為);既有的檢查全部通過。 + - 驗收紀錄(在一份只換測試檔、script 維持 `726050b` 的複本上執行 `bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh`):786 項通過、13 項失敗。失敗的是第 50 列(4 項)、第 51 列(3 項)、第 52 列(6 項)。第 52 列在舊 script 上的答案每次執行不一定相同(那正是它要抓的缺陷),所以失敗的項數會變:改 script 之前的另一次執行是 9 項、總數 16 項。第 53、54 列、`specs/` 以外的非 UTF-8 路徑、前 200 個字元、名稱以換行結尾的三列都通過,與預期相同。 + +## 2. 實作與說明 + +- [x] 2.1 [after: 1.1] 依 design「用 cat-file --batch-check 確認物件打得開」與「搜尋中途中止時不採用它印出的內容」改 `plugins/issue-driven-dev/scripts/spec-change.py`:`submodule_git()` 加 `stdin` 參數、新增 `submodule_lacks_objects()`、`marker_files()` 改用它並在搜尋中止時不讀輸出。驗證:1.1 的檢查全部通過;既有的檢查全部通過、沒有任何既有檢查被改寬;`python3 -m py_compile plugins/issue-driven-dev/scripts/spec-change.py` 通過。 +- [x] 2.2 [after: 2.1] 說明文件:`spec-change.py` 檔頭的 `links` 段、`plugins/issue-driven-dev/references/spec-wrapper.md` 的提醒(加上 submodule 記錄的 commit 裡的 `.gitmodules`,以及內容會被取出到工作樹)、`plugins/issue-driven-dev/CHANGELOG.md` 的 #548 條目。驗證:`git diff` 對 CHANGELOG 只動 #548 那一條;文字不含任何特定專案的名稱或本機路徑。 + +## 3. 收尾 + +- [x] 3.1 [after: 2.2] 跑整套測試:`bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 與 `bash .claude/scripts/tests/spectra-archive-post-ic/test.sh`。驗證:結束碼都是 0。 + - 驗收紀錄(在最後的檔案上、封存之前的工作樹執行):`bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 74 個 suite、0 個失敗;`bash .claude/scripts/tests/spectra-archive-post-ic/test.sh` 141 項通過。這次執行之後,測試檔只再改了第 49 列上方的三行註解(它說的「沒有缺任何物件」已經不對);改完後單獨重跑 `tests/spec-change/test.sh`,799 項通過。 +- [x] 3.2 [after: 3.1] 驗收:在一份只套用新測試檔、script 維持 `726050b` 的複本上重跑 1.1,確認哪些列失敗;舊測試檔(`726050b`、`7ad9152`、`afd0021`、`6ed8dec`)配新 script;沒有 gitlink 的 repo 與標記都在主 repo 的 repo 對照 `6ed8dec` 的 script 逐位元組比對;重放第三輪第 1、3 列的重現;執行上一個 change 的 34 種變異與 design「每一處改動各有一種變異」列的五種;單獨確認 `setup_failed` 在命令替換裡會讓主 shell 停下(bash 5 與 bash 3.2)。驗證:驗收紀錄寫在這一項底下,變異逐項列出有沒有檢查失敗。 + - 驗收紀錄。這個 change 的測試、程式與文件都由同一個協調者撰寫,沒有實作者模型,也沒有獨立讀者;第四輪 verify 是第一次獨立審查。 + - 新測試檔配新 script:799 項通過、0 項失敗。配 `726050b` 的 script:見 1.1 底下。 + - 舊測試檔配新 script:`726050b` 的 745 項、`7ad9152` 的 648 項、`afd0021` 的 497 項、`6ed8dec` 的 431 項都通過。 + - 輸出不變的兩種 repo,`python3 plugins/issue-driven-dev/scripts/spec-change.py links --base <base> --head <head> --cwd <repo>` 的輸出與結束碼,新 script 與 `6ed8dec` 的 script 逐位元組相同:這個 repo 自己的三段歷史(`401cd33..6ed8dec`、`2dc56ab..6ed8dec`、`fdf8d0d..4921b71`);有 gitlink 而標記都在主 repo 的臨時 repo。 + - 第三輪的重現,在臨時 repo 上:帶標記的檔案的物件檔是空的,新 script 回 `error`(`726050b` 的 script 回 `missing`);哪裡都沒有標記、一個無關檔案的物件檔是空的,新 script 回 `error`(`726050b` 回 `missing`);兩千個檔案的 submodule 裡一個檔案內容損壞、標記在同一個 submodule,新 script 30 次都回 `error`(`726050b` 的 script 10 次裡 9 次 `error`、1 次 `ok`)。第一輪與第二輪的重現仍然成立。 + - `setup_failed` 在命令替換裡:一支只含這個函式、`commit` 失敗、`X=$(commit)` 之後印一行字的腳本,在 bash 5.3 與 bash 3.2 都以結束碼 1 結束,沒有印出那一行。 + - 變異測試:每一種各改 script 一處,在複本上跑 `tests/spec-change/test.sh`,共 41 種(上一個 change 的 34 種,加上這次的 7 種:P14 到 P20)。39 種各有檢查失敗;沒有的兩種(G20、P09)是上一個 change 記為明文例外的那兩種。P04 與 P08 的改法照新的程式重新對位;P04 第一次沒有套用成功,對位後單獨重跑。逐項結果(括號裡是失敗的檢查所屬的列): + - G01 keep walking after a marker is found in the main repository:3 項檢查失敗(row 22; row 48) + - G02 no .git entry required:1 項檢查失敗(row 21) + - G03 no safe.bareRepository:1 項檢查失敗(row 31) + - G04 lazy fetch left on:1 項檢查失敗(row 33) + - G05 no containment checks:10 項檢查失敗(row 23) + - G06 strip() on the top that git reports for a submodule:2 項檢查失敗(row 25) + - G07 inherited GIT_* variables kept:7 項檢查失敗(row 28; row 40; row 41) + - G09 gitlinks under the spec directory not skipped:3 項檢查失敗(row 26) + - G10 strict UTF-8 for gitlink paths:1 項檢查失敗(row 17) + - G11 every unsearchable submodule listed:3 項檢查失敗(row 29) + - G12 long paths not cut:2 項檢查失敗(row 34) + - G13 only the symbolic-link test removed:3 項檢查失敗(row 27) + - G14 git's refusal reported as not checked out:2 項檢查失敗(row 30; row 31) + - G15 unsearchable submodules not sorted:1 項檢查失敗(row 38) + - G16 a '.' component accepted:1 項檢查失敗(row 39) + - G17 GIT_WORK_TREE kept:2 項檢查失敗(row 40) + - G18 GIT_OBJECT_DIRECTORY kept:2 項檢查失敗(row 40) + - G19 GIT_COMMON_DIR kept:2 項檢查失敗(row 40) + - G20 GIT_INDEX_FILE kept (reading a commit does not use the index: no input can show it):沒有檢查失敗 + - G21 GIT_ALTERNATE_OBJECT_DIRECTORIES kept:3 項檢查失敗(row 41) + - G22 the top that git names for a submodule is not compared:4 項檢查失敗(row 37) + - P01 a found marker does not settle the Example when a submodule could not be searched:4 項檢查失敗(row 42; row 44) + - P02 a file found in a submodule that lacks objects does not count:2 項檢查失敗(row 45) + - P03 the submodules inside an unreadable submodule are skipped:2 項檢查失敗(row 42) + - P04 output on git's error stream counts as unreadable again:5 項檢查失敗(row 46) + - P05 the git version is not checked:8 項檢查失敗(row 47) + - P06 repo_top strips white space again:18 項檢查失敗(top directory names: links trailing space; top directory names: links; top directory names: archived trailing space) + - P07 the object store is not asked which objects it lacks:16 項檢查失敗(row 20; row 36) + - P08 a search of a submodule that exits with another code is not a failure:10 項檢查失敗(row 52) + - P09 a tree of a submodule that cannot be listed is not reported:沒有檢查失敗 + - P10 the reason for a non-UTF-8 path under the spec directory is the exception text:1 項檢查失敗(invalid-UTF-8 spec path) + - P11 a version that cannot be read counts as new enough:4 項檢查失敗(row 47) + - P12 the main repository's failed search loses git's message:2 項檢查失敗(unreadable main tree) + - P13 the main repository's failed search reports git's whole message, not its first 200 characters:1 項檢查失敗(unreadable main tree) + - P14 an object that is present but cannot be opened does not count as lacking (no --batch-check):4 項檢查失敗(row 50) + - P15 the output of rev-list is split at carriage returns too:3 項檢查失敗(row 51) + - P16 whole records, not object ids, are given to --batch-check:23 項檢查失敗(row 5; row 6) + - P17 what a search printed before it ended early is used:9 項檢查失敗(row 52) + - P18 the main repository's failed search keeps the last 200 characters:1 項檢查失敗(unreadable main tree) + - P19 repo_top removes every trailing line feed:9 項檢查失敗(top directory names: links trailing line feed; top directory names: links, line feed; top directory names: archived trailing line feed) + - P20 the exit code of the search alone does not make a submodule one that could not be searched:4 項檢查失敗(row 54) + - 已知的限制:第 52 列靠的是舊行為有時回 `ok`,所以對應的變異(P08、P17)是以機率被擋下的;兩個檔案的 submodule 上,舊行為單次回 `ok` 的比例在第三輪審查者的量測是 40 次裡 39 次;協調者自己在 `726050b` 的 script 上跑了兩次這個測試檔,第 52 列的六次執行裡五次回 `ok`。三次執行都剛好回 `error`、讓變異漏網的機會因此很小,但不是零。整個測試只在 macOS 上跑過(git 2.55.0)。名稱不是合法 UTF-8 的頂層目錄沒有測試。 diff --git a/openspec/changes/archive/2026-11-15-idd-548-one-top-directory-requirement/.openspec.yaml b/openspec/changes/archive/2026-11-15-idd-548-one-top-directory-requirement/.openspec.yaml new file mode 100644 index 00000000..171e1ddb --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-one-top-directory-requirement/.openspec.yaml @@ -0,0 +1,6 @@ +schema: spec-driven +created: 2026-11-15 +created_by: che cheng <kiki830621@gmail.com> +created_with: claude +archived_by: che cheng <kiki830621@gmail.com> +archived_at: 2026-11-15 diff --git a/openspec/changes/archive/2026-11-15-idd-548-one-top-directory-requirement/design.md b/openspec/changes/archive/2026-11-15-idd-548-one-top-directory-requirement/design.md new file mode 100644 index 00000000..4d6d2533 --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-one-top-directory-requirement/design.md @@ -0,0 +1,61 @@ +## Context + +這條分支從 `6ed8dec` 分岔。之後預設分支多了兩個 commit:#547 的功能與 4.1.0 的發布。把預設分支合併進這條分支時有兩處衝突,合併 commit 這樣處理: + +- 規格:兩邊各在檔案結尾加了 requirement。合併 commit 把兩段都留下(4.1.0 的兩條在前,這條分支的一條在後),沒有改任何一句。 +- `spec-change.py`:兩邊都改了 `repo_top()` 的回傳。4.1.0 寫成 `one_line(p.stdout.decode("utf-8"))`,這條分支寫成先在位元組上去掉一個行尾、再 `os.fsdecode`。合併 commit 寫成 `one_line(os.fsdecode(p.stdout))`,`marker_files()` 裡同樣的一處也改用 `one_line()`。 +- CHANGELOG:git 把 #548 的條目自動併進了 4.1.0 的段落。合併 commit 把它移到新的 `[Unreleased]` 段落,4.1.0 的段落與預設分支逐字相同。 + +合併 commit 之後,規格裡有兩條 requirement 說同一件事。這個 change 處理的是這一點。 + +量測(協調者,git 2.55.0,macOS,Python 的檔案系統編碼是 utf-8 加 surrogateescape):十組位元組輸入(結尾一個換行、空白加換行、兩個換行、沒有換行、空的、只有換行、不合法的 UTF-8 位元組、中文、CR 加 LF、不合法位元組加兩個換行),「先在位元組上去掉一個行尾再 `os.fsdecode`」與「`one_line(os.fsdecode(...))`」回傳相同的字串。 + +## Goals / Non-Goals + +Goals: + +- 規格對頂層目錄的讀法只說一次,而且說的是合併後的五個子命令。 +- 這條分支為這個行為寫的檢查全部留下,並且仍然連到一個 Example。 + +Non-Goals: + +- 不改行為、不改 4.1.0 已發布的文字與六列。 +- 不處理名稱不是合法 UTF-8 的頂層目錄的規格文字(#559)。 + +## Decisions + +### 留已發布的那一條,移除這條分支的那一條 + +4.1.0 的那一條已經發布,涵蓋五個子命令;這條分支的那一條只列三個,而且每一句都被前者涵蓋(只去掉 git 加的那一個行尾;名稱可以用空白或換行結尾;三個子命令讀法相同,是「每個子命令都照 git 印出的讀」的特例)。所以移除的是這條分支的那一條。反過來做(留這條分支的、改 4.1.0 的)會改寫已經發布的句子,沒有必要。 + +### 六列搬過去,一列一列寫,不合併 + +這條分支的六列比 4.1.0 的六列多固定了三件事:`links` 在名稱以空白結尾時回 `ok`(4.1.0 的列是 `missing`)、`links` 與 `preflight` 在名稱以換行結尾時的答案、以及答案與「同一個 repo 放在一般名稱底下」逐字相同。六列各自對應測試檔裡既有的檢查,所以一列一列寫,不併成較少的列。每一列的 Result 只寫測試實際比對的東西:`preflight` 在換行那一列比對的是 `status` 與結束碼相同,不另外斷言 `ready`。 + +### 標記改指向已發布的 Example,不讓兩個 Example 並存 + +移除 requirement 之後,Example「top directory names」不存在了,`tests/spec-change/test.sh` 檔頭的標記與這一段的標題改成 Example「a top level whose name ends in whitespace」。同一個 Example 因此在兩個測試檔各有一個標記(另一個在 `tests/spec-archive-local/test.sh`),連結檢查只要求至少一個。斷言的名稱(`top directory names: ...`)不改,它們只是訊息。 + +### 讀 git 印出的路徑只用一個 helper + +合併後 `spec-change.py` 裡去掉 git 行尾的函式只有 4.1.0 的 `one_line()`。這條分支原本在兩處各寫一次同樣的運算式,合併 commit 把它們改成呼叫 `one_line()`。解碼仍用 `os.fsdecode`:這是這條分支第三個 change 的行為(名稱不是合法 UTF-8 時不以 traceback 結束),4.1.0 的寫法在這種輸入上會丟出解碼錯誤。這個 change 不改這兩處,只記錄並確認回傳值相同(見 Context 的量測)。 + +## Implementation Contract + +- `openspec/specs/spec-on-every-issue/spec.md`(由封存套用):requirement「The repository's top directory is read as git prints it」連同它的 Scenario 與 Example 不再存在;requirement「spec-change.py reads the repository that holds --cwd」的敘述與 Scenario 逐字不變,Example「a top level whose name ends in whitespace」在原有六列之後多六列。 +- `plugins/issue-driven-dev/scripts/tests/spec-change/test.sh`:檔頭的 `spec-example:` 那一行與這一段的 `echo` 標題改名;不新增、不移除、不改任何斷言。 +- `plugins/issue-driven-dev/CHANGELOG.md`:只動 `[Unreleased]` 裡 #548 那一條的最後一句。 +- 驗證:`tests/spec-change/test.sh` 799 項通過;`tests/spec-archive-local/test.sh` 通過;`run-all-tests.sh` 結束碼 0;`links --base origin/main` 回 `ok`;`archived` 回 pass。 + +## Risks / Trade-offs + +- 被移除的 requirement 是這條分支第三、四個 change 的 delta 寫的。那兩個封存的 change 不改;這個 change 的 delta 記錄它被移除與原因。 +- 兩個測試檔標記同一個 Example:其中一個被刪掉時,連結檢查不會發現另一半的列少了檢查。這是連結檢查既有的粒度(每個 Example 至少一個標記),不是這次造成的。 + +## Migration Plan + +不需要。沒有行為改變,沒有設定或資料要搬。 + +## Open Questions + +沒有。名稱不是合法 UTF-8 的頂層目錄要不要寫進 requirement,在 #559。 diff --git a/openspec/changes/archive/2026-11-15-idd-548-one-top-directory-requirement/proposal.md b/openspec/changes/archive/2026-11-15-idd-548-one-top-directory-requirement/proposal.md new file mode 100644 index 00000000..28e8201f --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-one-top-directory-requirement/proposal.md @@ -0,0 +1,51 @@ +**GitHub-side tracker**: #548 + +## Problem + +這條分支開出之後,預設分支發布了 4.1.0(#547)。4.1.0 的 requirement「spec-change.py reads the repository that holds --cwd」與這條分支第三、四個 change 寫的「The repository's top directory is read as git prints it」說的是同一件事。把預設分支合併進來之後: + +1. 規格裡有兩條 requirement 敘述同一個行為,用字不同。 +2. 這條分支的那一句寫「帶 `--cwd` 的子命令(`links`、`archived`、`preflight`)」。合併之後帶 `--cwd` 的子命令是五個(4.1.0 加了 `archive-ref` 與 `link-base`),那一句不再完整。 +3. CHANGELOG 的 #548 條目還把「`links`、`archived`、`preflight` 照 git 印出的讀頂層目錄」列為這次的改動,而 4.1.0 已經發布了這個行為。 + +## Root Cause + +兩條分支各自修了同一個缺陷(頂層目錄名稱結尾的空白被 `strip()` 去掉),各自加了一條 requirement 與一張 Example 表。git 的合併只能把兩段文字都留下。 + +## Proposed Solution + +- 移除這條分支的 requirement「The repository's top directory is read as git prints it」。已發布的那一條涵蓋它的全部敘述:五個子命令、只去掉 git 加的那一個行尾、名稱可以用空白或換行結尾。 +- 這條分支的 Example「top directory names」的六列,改寫成已發布那一條的 Example「a top level whose name ends in whitespace」的三欄格式,接在那張表的後面。已發布的六列不動。 +- `tests/spec-change/test.sh` 裡這一段的標記與標題改指向那個 Example。檢查本身不改,數目不變。 +- CHANGELOG 的 #548 條目拿掉 4.1.0 已經發布的那一句,改寫成 Example 新增的列。 +- `spec-change.py` 不在這個 change 裡改。合併時 `repo_top()` 與 `marker_files()` 讀 git 印出的路徑的兩處已改用 4.1.0 的 `one_line()`,先以 `os.fsdecode` 解碼;這個 change 確認兩處的回傳值與合併前相同。 + +## Non-Goals + +- 不改任何子命令的行為。 +- 不為名稱不是合法 UTF-8 的頂層目錄新增 requirement 的文字或列(#559 第 8 點)。 +- 不改 4.1.0 的 `archive-ref` 與 `link-base`,也不改 4.1.0 那六列。 + +## Success Criteria + +- 規格裡只有一條敘述頂層目錄讀法的 requirement,它的 Example 有十二列。 +- `bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 799 項通過;`bash plugins/issue-driven-dev/scripts/tests/spec-archive-local/test.sh` 全部通過;整套測試通過。 +- `spec-change.py links` 從預設分支到這條分支的 HEAD 回 `ok`;`archived` 回 pass。 +- `repo_top()` 讀路徑的寫法,合併前後對同一組位元組輸入回傳相同的字串。 + +## Capabilities + +### New Capabilities + +(none) + +### Modified Capabilities + +- `spec-on-every-issue`: 移除 requirement「The repository's top directory is read as git prints it」;requirement「spec-change.py reads the repository that holds --cwd」的 Example 加六列。 + +## Impact + +- Affected specs: spec-on-every-issue(一個 REMOVED requirement、一個 MODIFIED requirement) +- Affected code: + - Modified: plugins/issue-driven-dev/scripts/tests/spec-change/test.sh + - Modified: plugins/issue-driven-dev/CHANGELOG.md diff --git a/openspec/changes/archive/2026-11-15-idd-548-one-top-directory-requirement/specs/spec-on-every-issue/spec.md b/openspec/changes/archive/2026-11-15-idd-548-one-top-directory-requirement/specs/spec-on-every-issue/spec.md new file mode 100644 index 00000000..fc40aac7 --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-one-top-directory-requirement/specs/spec-on-every-issue/spec.md @@ -0,0 +1,36 @@ +## MODIFIED Requirements + +### Requirement: spec-change.py reads the repository that holds --cwd + +Every subcommand of `scripts/spec-change.py` that takes `--cwd` (`archived`, `links`, `preflight`, `archive-ref`, `link-base`) SHALL read the repository whose top level `git rev-parse --show-toplevel` reports for `--cwd`, and SHALL take that path exactly as git prints it, removing only the one line ending git appends (the name of the directory can itself end in a space or a newline). A top level whose name ends in whitespace is that directory, never a sibling directory whose name lacks the whitespace. + +#### Scenario: A top level whose name ends in whitespace + +- **GIVEN** two repositories side by side, `odd ` (with a trailing space) and `odd` +- **WHEN** a subcommand runs with `--cwd` inside `odd ` +- **THEN** it reads `odd ` + +##### Example: a top level whose name ends in whitespace + +| Repositories | Command | Result | +| --- | --- | --- | +| `odd ` has the change archived, the sibling `odd` does not | `archived --cwd 'odd ' --ref HEAD` | `pass` | +| `odd ` alone, with the change archived | `archived --cwd 'odd ' --ref HEAD` | `pass` | +| `odd ` has a spec added on a branch without an Example, the sibling `odd` has none | `links --base <its base> --cwd 'odd '` | `missing` | +| `pf ` has an `openspec/` directory, the sibling `pf` does not | `preflight --cwd 'pf ' --can-write yes` | `ready` | +| `pf ` alone, with an `openspec/` directory | `preflight --cwd 'pf ' --can-write yes` | `ready` | +| `nl` followed by a newline has the change archived, the sibling `nl` does not | `archived` with `--cwd` that directory, `--ref HEAD` | `pass` | +| `sp ` (its name ends in a space) holds an added requirement with its marker in a tracked test file, and has the declared change archived; `copy` is the same repository under a name that does not end in a space | `links` with `--cwd` at each | `ok` for both, with the same JSON line and exit code | +| the same two repositories | `archived` with `--cwd` at each, `--ref HEAD` | `pass` for both, with the same JSON line and exit code | +| the same two repositories | `preflight` with `--cwd` at each, `--can-write yes` | `ready` for both, with the same exit code | +| the same repository under a name that ends in a line feed, and `copy` | `links` with `--cwd` at each | `ok` for both, with the same JSON line and exit code | +| the same two repositories | `archived` with `--cwd` at each, `--ref HEAD` | `pass` for both, with the same JSON line and exit code | +| the same two repositories | `preflight` with `--cwd` at each, `--can-write yes` | the same `status` and exit code for both | + +## REMOVED Requirements + +### Requirement: The repository's top directory is read as git prints it + +**Reason**: The requirement "spec-change.py reads the repository that holds --cwd", released in 4.1.0 while this branch was open, states the same rule for all five subcommands that take `--cwd`. Two requirements for one behaviour would have to be kept in step, and this one names only three of the five subcommands. + +**Migration**: None for callers; no behaviour changes. The six rows of its Example `top directory names` become rows of the Example `a top level whose name ends in whitespace`, and the checks that carried the marker of the former carry the marker of the latter. diff --git a/openspec/changes/archive/2026-11-15-idd-548-one-top-directory-requirement/tasks.md b/openspec/changes/archive/2026-11-15-idd-548-one-top-directory-requirement/tasks.md new file mode 100644 index 00000000..41817445 --- /dev/null +++ b/openspec/changes/archive/2026-11-15-idd-548-one-top-directory-requirement/tasks.md @@ -0,0 +1,15 @@ +## 1. 標記與說明 + +- [x] 1.1 依 design「標記改指向已發布的 Example,不讓兩個 Example 並存」與「六列搬過去,一列一列寫,不合併」:`plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 檔頭的標記與「top directory names」那一段的標題,改指向 requirement「spec-change.py reads the repository that holds --cwd」的 Example「a top level whose name ends in whitespace」(它新增的六列就是這一段既有的檢查);斷言不新增、不移除、不改。驗證:`bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 799 項通過、0 項失敗;`git diff` 對這個檔案只有這兩處。 +- [x] 1.2 [after: 1.1] 依 design「留已發布的那一條,移除這條分支的那一條」:`plugins/issue-driven-dev/CHANGELOG.md` 的 #548 條目拿掉 4.1.0 已經發布的那一句,改寫成 Example 新增的列。驗證:`git diff` 對 CHANGELOG 只動 `[Unreleased]` 裡 #548 那一條;文字不含任何特定專案的名稱或本機路徑。 + +## 2. 收尾 + +- [x] 2.1 [after: 1.2] 依 design「讀 git 印出的路徑只用一個 helper」與 Implementation Contract 驗收:`bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 與 `bash .claude/scripts/tests/spectra-archive-post-ic/test.sh` 結束碼都是 0;`tests/spec-archive-local/test.sh` 通過;合併前後讀路徑的兩種寫法對同一組位元組輸入回傳相同;`python3 plugins/issue-driven-dev/scripts/spec-change.py links --base origin/main --cwd .` 在封存之前回 `missing`、只列出要被移除的那一條 requirement(它的 Example 已經沒有標記,而移除它的 delta 要到封存才套用),封存之後回 `ok`。驗證:封存之前的結果寫在這一項底下;封存之後的結果寫在 issue 的 Implementation Complete 留言。 + - 驗收紀錄。這個 change 的文件、規格差異與兩處修改都由同一個協調者撰寫,沒有實作者模型,也沒有獨立讀者;第五輪 verify 是第一次獨立審查。 + - 整套測試跑了兩次。合併 commit(`f08839f`)上:`bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 75 個 suite、0 個失敗,`bash .claude/scripts/tests/spectra-archive-post-ic/test.sh` 141 項通過。這個 change 的兩處修改提交之後(`6758b3d`,封存之前的工作樹):75 個 suite、0 個失敗,`spectra-archive-post-ic` 141 項通過。 + - `bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 799 項通過、0 項失敗;`bash plugins/issue-driven-dev/scripts/tests/spec-archive-local/test.sh` 126 項通過,這個檔案與預設分支(`3b87909`)的逐位元組相同。 + - `git diff 54a9092 6758b3d -- plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 只有兩行不同:檔頭的標記與這一段的標題。第四輪審過的測試檔(`54a9092` 的版本)配合併後的 script:799 項通過。 + - 讀路徑的兩種寫法(合併前:在位元組上去掉一個行尾再 `os.fsdecode`;合併後:`one_line(os.fsdecode(...))`),十組位元組輸入回傳相同:結尾一個換行、空白加換行、兩個換行、沒有換行、空的、只有換行、兩個不合法的 UTF-8 位元組、中文、CR 加 LF、不合法位元組加兩個換行。 + - 連結檢查,封存之前(`6758b3d`,`python3 plugins/issue-driven-dev/scripts/spec-change.py links --base origin/main --cwd .`):`status` 是 `missing`,只列一項:requirement「The repository's top directory is read as git prints it」的 Example「top directory names」沒有標記。這是預期的:標記已經改指向留下的那個 Example,而移除這條 requirement 的 delta 到封存才套用。封存之後的結果記在 issue 的 Implementation Complete 留言。 + - 沒有做的:這個 change 沒有新的變異測試(斷言沒有改,script 的兩處在合併 commit 裡、回傳值不變);測試只在 macOS 上跑過。 diff --git a/openspec/changes/archive/2026-11-16-idd-548-fix8/.openspec.yaml b/openspec/changes/archive/2026-11-16-idd-548-fix8/.openspec.yaml new file mode 100644 index 00000000..2e70beb1 --- /dev/null +++ b/openspec/changes/archive/2026-11-16-idd-548-fix8/.openspec.yaml @@ -0,0 +1,5 @@ +schema: spec-driven +created: 2026-11-16 +created_by: che cheng <kiki830621@gmail.com> +archived_by: che cheng <kiki830621@gmail.com> +archived_at: 2026-11-16 diff --git a/openspec/changes/archive/2026-11-16-idd-548-fix8/design.md b/openspec/changes/archive/2026-11-16-idd-548-fix8/design.md new file mode 100644 index 00000000..214f2502 --- /dev/null +++ b/openspec/changes/archive/2026-11-16-idd-548-fix8/design.md @@ -0,0 +1,63 @@ +## Context + +第 50 列是第四個 change(`idd-548-links-unreadable-objects`)加的。它要守住的是 requirement 的這一句:搜尋 submodule 之前,先問 git 記錄的 commit 有哪些物件缺少或打不開;物件檔存在但打不開(例如空檔)算缺少。當時用的 git(2.55.0)在空的物件檔上會跳過那個檔案、讓 `git grep` 以 0 或 1 結束,所以只有「先問」那一步看得出檔案沒被讀到。fixture 把這個前提寫成檢查,前提不成立就停下整個測試檔。 + +git 2.56 起,同一個輸入讓 `git grep` 以 128 結束。第 49 列描述的正是「搜尋以 128 結束」的情形,答案相同(`error`,its recorded commit could not be read)。 + +## Goals / Non-Goals + +Goals: + +- 測試檔在 git 2.54.0、2.55.0、2.56.0 上都跑完,檢查項數相同。 +- Example 第 50 列的第一欄對這三個版本都是真的。 + +Non-Goals: + +- 不動 `spec-change.py`。 +- 不動 requirement 的條文與其他各列。 +- 不新增一列。 + +## Decisions + +### 第 50 列的 fixture 記下結束碼,不停下 + +`git grep` 的結束碼存進變數。大於 1 時印一行,格式照測試檔其他說明行(開頭兩個空白與 `~`): + +` ~ note: this git ends the search of an empty object with exit code <N>, row 50 takes the path of row 49` + +之後的 `links_case` 與原因文字的檢查照樣執行。不在結束碼大於 1 時略過這一列:答案在兩種情形下相同,略過會讓 git 2.56 起的版本少一組檢查,各版本的項數也會不同。 + +「git 把那個物件列為存在」的前提檢查(`rev-list --objects --missing=print` 不把它印成缺少)保留,不成立時仍然停下:那是這一列與「物件不在」各列的差別,三個版本都成立。 + +### Example 第一欄寫兩種情形,不寫版本號 + +第一欄現在的後半句是「so the search skips the file and ends with exit code 0 or 1」。改成: + +「depending on its version, git either skips the file and ends the search with exit code 0 or 1, or ends the search with exit code 128」 + +不寫「2.56 之前/之後」:量到的只有四個版本,其中一個(CI 的 2.56.1)只知道結束碼大於 1。版本與結束碼的對照記在 proposal 與測試檔的註解,那裡寫的是量到的版本。 + +### 測試檔的註解寫量到的版本 + +第 50 列上方的註解改成:git 2.54.0 與 2.55.0 跳過那個檔案、以 0 或 1 結束,只有打開物件才看得出檔案沒被讀到;git 2.56.0 讓搜尋自己以 128 結束,這一列就走第 49 列的路。兩種情形答案相同,都檢查。 + +## Implementation Contract + +- `plugins/issue-driven-dev/scripts/tests/spec-change/test.sh`:只動第 50 列。註解兩行換成上面的說法;`[ "$?" -le 1 ] || setup_failed …` 那一行換成「記下結束碼,大於 1 時印說明行」。其他各列與 helper 不動。 +- `openspec/specs/spec-on-every-issue/spec.md`(由封存套用):requirement「Added and modified requirements carry an executable check」的 Example「markers in submodules」第 50 列第一欄換掉後半句。這條 requirement 的其他文字、這一列的第二、三欄、其他各列都不變。 +- `plugins/issue-driven-dev/scripts/spec-change.py`:不動;`git diff` 對這個檔案沒有輸出。 +- 驗證:測試檔在 git 2.54.0、2.55.0、2.56.0 上都是 878 項通過、0 項失敗;改之前的測試檔在 git 2.56.0 上停在第 50 列;`run-all-tests.sh` 結束碼 0;`links --base origin/main` 回 `ok`;`archived` 回 pass。 + +## Risks / Trade-offs + +- git 2.56 起,空的物件檔讓搜尋自己失敗。「搜尋前先問 git 哪些物件打不開」那一步,在這些版本上沒有只有它才抓得到的測試輸入:把那一步拿掉的變異,在 git 2.55 以下會讓第 50 列失敗,在 2.56 上不會。那一步仍然留著,requirement 也仍然要求它;CI 用的是新版 git,所以 CI 守不住它,要靠在舊版 git 上跑測試。有沒有別的輸入能在新版 git 上分辨,沒有查過。 +- 第 50 列以後的檢查還沒有在 Linux 上執行過。這個 change 推上去之後 CI 才會跑到;那裡再有失敗,不在這個 change 的範圍內處理,先回報。 +- 這個 change 沒有獨立讀者,也不開 verify 輪(維護者的決定)。它不改程式;證據是三個 git 版本上的測試結果與推上去之後的 CI。 + +## Migration Plan + +沒有。測試檔與 Example 的一列,使用者的 repository 不受影響。 + +## Open Questions + +沒有。 diff --git a/openspec/changes/archive/2026-11-16-idd-548-fix8/proposal.md b/openspec/changes/archive/2026-11-16-idd-548-fix8/proposal.md new file mode 100644 index 00000000..9a3ebabf --- /dev/null +++ b/openspec/changes/archive/2026-11-16-idd-548-fix8/proposal.md @@ -0,0 +1,60 @@ +**GitHub-side tracker**: #548 + +## Problem + +draft PR #572 的第一次 CI(ubuntu-26.04、git 2.56.1)裡,`spec-change` 這個 suite 停在 Example「markers in submodules」第 50 列的 fixture(留言 6909882017): + +`FATAL: spec-change suite: fixture setup failed: the search of a submodule with an empty object must end with 0 or 1` + +停下之後的檢查都沒有執行。PR 因此是紅燈,第 50 列以後的檢查也從來沒有在 Linux 上跑到。 + +## Root Cause + +第 50 列描述的輸入是:標記所在檔案的物件檔存在,但長度為零。fixture 在執行 `links` 之前先確認兩件事:git 把那個物件列為存在;`git grep` 以 0 或 1 結束(它跳過讀不到的檔案)。第二件事取決於 git 的版本。同一個輸入實跑的結果: + +| git | `git grep` 的結束碼 | git 印的訊息 | +|---|---|---| +| 2.54.0(macOS 內附) | 1 | `error: … unable to read …` | +| 2.55.0 | 1 | `error: … unable to read …` | +| 2.56.0 | 128 | `fatal: loose object … is corrupt` | +| 2.56.1(CI) | 大於 1:fixture 的前提檢查失敗,結束碼沒有印出來 | 沒有紀錄 | + +壞掉的是 fixture 的前提檢查,以及 requirement 的 Example 那一列第一欄的一句:「so the search skips the file and ends with exit code 0 or 1」。`links` 的答案沒有錯:在 macOS 上用 git 2.56.0,在一份副本裡拿掉那一行前提檢查之後,測試檔 878 項通過,第 50 列的答案仍是 `error`(its recorded commit could not be read)。 + +維護者的決定(留言 6910032608):修測試,不再審。 + +## Proposed Solution + +- 測試檔第 50 列:前提檢查改成記下 `git grep` 的結束碼。結束碼是 0 或 1 時與現在相同;大於 1 時印一行說明(這個 git 讓搜尋自己失敗,這一列走的是第 49 列的路),不停下。答案的檢查(`status`、列出的項數、結束碼、原因文字)兩種情形都執行。「git 把那個物件列為存在」的前提檢查不動。 +- Requirement 的 Example 第 50 列第一欄:那一句改成兩種情形並列,不寫版本號。第三欄不變。 +- `spec-change.py` 不動。 + +## Non-Goals + +- 不改 `links` 的任何行為,不改 requirement 的條文;只動 Example 的一列。 +- 不處理第八輪的後續項(留在 #559)。 +- 不處理 `edit-run` 的不穩定檢查(#534)。 +- 不為 git 2.56 起的版本另找一個「搜尋不失敗、但物件打不開」的輸入。有沒有這種輸入沒有查過;後果記在 design 的 Risks。 + +## Success Criteria + +- `bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 在 git 2.54.0、2.55.0、2.56.0 三個版本上都是 878 項通過、0 項失敗。前兩個版本不印那一行說明,2.56.0 印。 +- 改之前的測試檔在 git 2.56.0 上停在第 50 列(559 項通過之後 FATAL);改之後不停。 +- `bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 結束碼 0。 +- `spec-change.py links` 從預設分支到這條分支的 HEAD 回 `ok`;`archived` 回 pass。 +- PR #572 的 CI 裡 `spec-change` 通過。這一項要推上去之後才知道:第 50 列以後的檢查是第一次在 Linux 上執行。 + +## Capabilities + +### New Capabilities + +(none) + +### Modified Capabilities + +- `spec-on-every-issue`: Example「markers in submodules」第 50 列第一欄的敘述。 + +## Impact + +- `plugins/issue-driven-dev/scripts/tests/spec-change/test.sh`:第 50 列的 fixture 與它的註解。 +- `openspec/specs/spec-on-every-issue/spec.md`:Example 的一列,封存時套用。 diff --git a/openspec/changes/archive/2026-11-16-idd-548-fix8/specs/spec-on-every-issue/spec.md b/openspec/changes/archive/2026-11-16-idd-548-fix8/specs/spec-on-every-issue/spec.md new file mode 100644 index 00000000..66c56e55 --- /dev/null +++ b/openspec/changes/archive/2026-11-16-idd-548-fix8/specs/spec-on-every-issue/spec.md @@ -0,0 +1,125 @@ +## MODIFIED Requirements + +### Requirement: Added and modified requirements carry an executable check + +`scripts/spec-change.py links --base <rev>` SHALL compare the files under `openspec/specs/` at `<rev>` and at `--head` (default `HEAD`). For every requirement that is new or whose text differs between the two, it SHALL require one of two things: at least one `##### Example:` under the requirement, where each such Example has a title that is unique within its capability and a tracked file at the head revision, outside `openspec/` and not ending in `.md`, that contains the marker `spec-example: <capability> / <Example title>` (a tracked file of a submodule counts, as the paragraph "Submodules" below describes); or a line under the requirement that starts with `No executable check:` followed by a reason. A requirement that does not differ SHALL NOT be checked. A marker counts only when nothing but whitespace, or the comment closer `-->` or `*/`, follows the Example title on its line. Lines inside a code fence are not read as `##### Example:` or `No executable check:` lines; a fence opened by three or more backticks or tildes, at any indentation (as inside a list item), closes only on a line of the same character, at least as long, with nothing but whitespace after it; lines end only at `\n`, `\r\n` or `\r`. A requirement heading indented by up to three spaces SHALL be read as a requirement, as Spectra reads it. Paths SHALL be read as git stores them, never in git's quoted form, so a capability whose directory name is not ASCII is checked like any other. Two requirements with the same name in one capability SHALL make the command print `error`. So SHALL a code fence at the head revision that never closes, since the requirements after it would go unchecked. Outside code fences, a heading that starts with `### Requirement` but does not have the form `### Requirement: <name>` with a non-empty name SHALL make the command print `error`, and so SHALL a head revision at which the spec directory's `specs/` holds no tracked file, and a path under the spec directory's `specs/` that is not valid UTF-8 (the reason says so and carries no text of an exception). Such a path elsewhere under the spec directory does not change the answer. The command SHALL print one JSON line with `status` (`ok`, `missing` or `error`) and a list naming each requirement or Example that lacks its check, and SHALL exit 0, 1 or 2 in that order. `--base` is required: the caller names the range, so that a run on the default branch is checked against the commit it started from. The marker ties an Example to a test by name only; whether the test exercises what the Example states is judged by the reviewers of `idd-verify`. + +Submodules. The tracked files at the head revision include the tracked files of every submodule of the repository at the commit that the head revision records for it, and in the same way the files of a submodule of a submodule. The command SHALL read that recorded commit, not the commit the submodule's working tree is on. It SHALL find the submodules itself, from the entries of the head revision's tree that record a commit; it SHALL NOT rely on git's own recursion into submodules, which passes over a submodule that is not checked out without saying so; the answer SHALL be the same whether or not the git configuration turns that recursion on (`submodule.recurse`). A file of a submodule is named by the submodule's path followed by the file's path, and the two exclusions (under the spec directory, ending in `.md`) apply to that name. A submodule whose own path is under the spec directory SHALL NOT be searched and SHALL NOT count as one that could not be searched: none of its files could count. Nor SHALL a submodule be searched, or count as one that could not be searched, when its directory, after symbolic links are resolved, is the spec directory of the main repository or lies under it, whatever its path is named: a symbolic link, or another spelling of the name on a volume that does not distinguish letter case, can lead into the spec directory from a path that is not under it by name. This is decided after conditions 1 and 2 of the paragraph "Which submodules can be searched" below, and in the way of condition 2: the spec directory is one of the directories passed before the top directory is met, and directories are compared, not names. A spec directory that cannot be examined has nothing under it. + +Order of the search. For each Example the command SHALL search the main repository first. When the marker is found there, the Example has its check and the command SHALL NOT run git in any submodule for it, so for a repository whose markers are all in its own files no entry that records a commit is listed and no submodule is examined, whatever its head revision records. Only when the marker is not found in the main repository are the submodules searched, and a marker found in one submodule settles the Example whatever the state of the others. When the marker of an Example is found, the Example has its check, whether or not every submodule could be searched. The submodules inside a submodule are read from a listing of every tree of its recorded commit, and that listing is made only when the outer one meets its own six conditions. Each of them is then searched whenever its own six conditions hold, also when the search of the outer one failed. When the listing fails, because a tree of the recorded commit cannot be read, the submodules inside it are unknown, even when the top tree shows them. + +Which submodules can be searched. A submodule SHALL be searched only when all six of these hold: (1) its path, as the tree records it, is relative and has no empty, `.` or `..` component; (2) its directory, after symbolic links are resolved, is the top directory of the main repository or lies under it, which means that the top directory is met when going from the resolved directory to its parent directory, to the parent of that one, and so on; and no directory passed before the top directory is met (the resolved directory itself, unless it is the top directory, and each directory between the two) is one of two directories, the one that `git rev-parse --absolute-git-dir` prints and the one that `git rev-parse --git-common-dir` prints when run at the top directory (in a linked worktree these are two different directories); (3) the directory itself is not a symbolic link; (4) the directory holds an entry named `.git` of its own; (5) git, run in the directory, reports that same directory as the top of its own working tree; (6) its object store holds the recorded commit. In conditions 2 and 5 directories are compared, not names: two paths name the same directory when the operating system reports the same device and the same inode for both, however each path is spelled (on a volume that does not distinguish letter case, for one, a path written in another letter case names the same directory). A directory on the way up that cannot be examined (one that does not exist, for one) is passed over: it is neither the top directory nor one of the two. The two directories of condition 2 are a closed list: no other directory is refused under that condition. No git directory of a submodule is added to the list: when the git directory of a submodule is itself one of the two, or lies under one of them, condition 2 applies to it as written, and otherwise a directory inside it is searched when the six conditions hold. The top directory is not compared with the two, so when the top directory is one of them, or lies inside one of them, neither it nor the directories under it are refused for that reason. A directory that resolves to the top directory itself meets condition 2. The command SHALL NOT run git in a directory that fails any of the first four: a directory of ordinary tracked files can be shaped like a git directory, and git would read, and act on, the configuration it holds. Nor SHALL it run git in the directory of any submodule when git is older than 2.45, the first version that honours `GIT_NO_LAZY_FETCH`, or when the version cannot be read: a submodule for which the first four hold then counts as one that could not be searched. In the directory of a submodule the command SHALL run git with `safe.bareRepository` set to `explicit`, with lazy fetching turned off (`GIT_NO_LAZY_FETCH=1`), and with the variables `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, `GIT_OBJECT_DIRECTORY`, `GIT_ALTERNATE_OBJECT_DIRECTORIES` and `GIT_COMMON_DIR` removed from the environment it inherited. Before it searches a submodule the command SHALL ask git which objects of the recorded commit (its trees and the contents of its files) the object store lacks or cannot open, without fetching any: an object whose file is present but cannot be opened (for example an empty file) counts as lacking. A submodule is searched even when some are lacking, and a file that counts, found by a search that ran to its end (exit code 0 or 1), settles the Example. What a search printed before it ended with another exit code SHALL NOT be used, so that the answer for one state of the repository is the same on every run. When no file that counts is found in it, the submodule counts as one that could not be searched if its object store lacks an object of the recorded commit, if the search exits with a code other than 0 or 1, or if the trees of the recorded commit cannot all be listed. What git writes to its error stream SHALL NOT change whether a submodule counts as searched, nor the reason reported for it. In the main repository a search that exits with a code other than 0 or 1 is `error`, as before; its reason is `git grep failed: ` followed by the first 200 characters of what git wrote to its error stream, also as before. + +What is reported. When the marker is not found and every submodule was searched, the Example is reported as lacking its check, as before. When it is not found and at least one submodule could not be searched, the command SHALL print `error` and name the first such Example it meets, the submodules that could not be searched and the reason for each: an Example whose candidate files were not all read is not reported as lacking its check. The submodules are named by path, in the order of their paths and joined by `; `; a submodule of a submodule is named by its path under the outer one; when more than five could not be searched, the first five are named and the number of the others is stated; a path longer than 200 characters is cut to its first 200 followed by `...`. The reason is one of six: the path leaves the repository (conditions 1 and 2); the submodule is not checked out (conditions 3 and 4, or git names another directory as the top); git is older than 2.45 (stated also when its version cannot be read); git refused to open it (the git command of condition 5 fails); the recorded commit is not in its object store (condition 6); the recorded commit could not be read (its object store lacks or cannot open an object of it, or the search or the listing of its trees failed). The reason given for a submodule SHALL NOT carry text from git's error stream. The path of a submodule that is not valid UTF-8 is handled like any other path, and the command still prints one JSON line. A repository whose head revision records no submodule is searched in its own tracked files only: none of the rules for submodules changes its answer. + +#### Scenario: An Example without a test is reported + +- **GIVEN** a range that adds a requirement with one Example titled `status by exit code` to the capability `local-ci-gate` +- **AND** no tracked file outside `openspec/` contains `spec-example: local-ci-gate / status by exit code` +- **WHEN** `spec-change.py links` runs on that range +- **THEN** it prints `status` `missing`, names that Example, and exits 1 + +##### Example: what the link check reports + +| Requirement in the range | Examples | Marker at the head revision | `No executable check:` line | `status` | +| --- | --- | --- | --- | --- | +| added | one | in `scripts/tests/x/test.sh` | absent | `ok` | +| added | one | absent | absent | `missing` | +| added | one | only in a file under `openspec/` | absent | `missing` | +| added | one | only in a file ending in `.md` | absent | `missing` | +| added | none | not applicable | absent | `missing` | +| added | none | not applicable | present, with a reason | `ok` | +| added | none | not applicable | present, with nothing after the colon | `missing` | +| added | one, with no title | not applicable | absent | `missing` | +| added | two with the same title as an Example elsewhere in the capability | present | absent | `missing` | +| changed | two | present for one, absent for the other | absent | `missing` | +| unchanged, with no Example | none | not applicable | absent | `ok` | +| removed in the range | not applicable | not applicable | not applicable | `ok` | +| no file under `openspec/specs/` differs | not applicable | not applicable | not applicable | `ok` | +| added | one | only a marker naming a longer title that starts with this one | absent | `missing` | +| added, under the heading `### Requirement Missing colon` | not applicable | not applicable | not applicable | `error` | +| any; `openspec/specs/` holds no tracked file at the head revision | not applicable | not applicable | not applicable | `error` | +| added, its only `##### Example:` line inside a code fence | none outside fences | not applicable | absent | `missing` | +| added, its only `No executable check:` line inside a code fence | none | not applicable | only inside a fence | `missing` | +| added, after a fence of four backticks that a line of three backticks does not close | its Example inside that fence | not applicable | absent | `missing` | +| added, under the heading ` ### Requirement: Alpha` (two leading spaces) | none | not applicable | absent | `missing` | +| added, its only `No executable check:` line inside a fence indented four spaces in a list item | none | not applicable | only inside that fence | `missing` | +| added, in a capability whose directory name is not ASCII (`中文能力`) | none | not applicable | absent | `missing` | +| added, in a capability whose directory name holds a double quote (`quo"te`) | none | not applicable | absent | `missing` | +| added, in a capability whose directory name is not valid UTF-8 | not applicable | not applicable | not applicable | `error`, with a reason that says so | +| added; a tracked path under the spec directory but outside `specs/` is not valid UTF-8 | one | in `scripts/tests/x/test.sh` | absent | `ok` | +| added; a tree of the head revision outside the spec directory cannot be read | one | absent | absent | `error`; the reason is `git grep failed: ` followed by the first 200 characters of what git wrote to its error stream | +| added twice with the same name in one capability | not applicable | not applicable | not applicable | `error` | +| any, after a code fence that never closes | not applicable | not applicable | not applicable | `error` | +| `--base` names a revision that does not exist | not applicable | not applicable | not applicable | `error` | +| `--base` is not given | not applicable | not applicable | not applicable | usage error, exit 64 | + +##### Example: markers in submodules + +| Where the marker of the Example is at the head revision | Submodules recorded at the head revision | `status` | +| --- | --- | --- | +| in a tracked file of a submodule, at the commit the head revision records | one, checked out | `ok` | +| in a tracked file of a submodule of a submodule | both checked out | `ok` | +| in a tracked file of a submodule whose path holds a space | one, checked out | `ok` | +| only in the recorded commit of a submodule whose working tree is on a later commit without it | one, checked out | `ok` | +| only in a later commit of a submodule, which its working tree is on, not in the recorded commit | one, checked out | `missing` | +| only in a file of a submodule that ends in `.md` | one, checked out | `missing` | +| nowhere | one, checked out | `missing` | +| nowhere in the main repository | one, not checked out | `error`, naming the Example and the submodule's path | +| in a tracked file of the main repository | one, not checked out | `ok` | +| nowhere in the main repository | one, checked out, whose object store lacks the recorded commit | `error`, naming the Example and the submodule's path | +| in a tracked file of the main repository | one, checked out, whose object store lacks the recorded commit; `submodule.recurse` is true in the repository's git configuration | `ok` | +| nowhere in the main repository | one, checked out, whose object store lacks the recorded commit; `submodule.recurse` is true in the repository's git configuration | `error`, naming the Example and the submodule's path | +| only in the recorded commits of two submodules | two, neither checked out | `error`, naming the Example and both paths, joined by `; ` | +| only in a submodule of a submodule | the outer one checked out, the inner one not | `error`, naming the Example and the inner submodule by its path under the outer one | +| only in a tracked file of a submodule that is mounted under `openspec/` | one, checked out | `missing` | +| in a tracked file of the main repository | one whose path is not valid UTF-8, not checked out | `ok` | +| nowhere | one whose path is not valid UTF-8, not checked out | `error` on one JSON line, exit 2 | +| in a tracked file of the main repository | one, checked out, holding the recorded commit but not the tree of that commit | `ok` | +| nowhere in the main repository | one, checked out, holding the recorded commit but not the tree of that commit | `error`, naming the Example and the submodule's path, with no text from git's error stream | +| nowhere | one, checked out, whose object store lacks the content of one file of the recorded commit | `error`, naming the Example and the submodule's path, with no text from git's error stream | +| nowhere | one, checked out, whose recorded commit records a second submodule; at that second path the working tree holds ordinary files shaped like a git directory (`HEAD`, `config`, `objects/`, `refs/`) and no `.git` entry, and that `config` names a command to run | `error`, naming the second path as not checked out; the command named in that `config` does not run | +| in a tracked file of the main repository | the same two, with the same files at the second path | `ok`; no git command runs in the directory of a submodule, and the command named in that `config` does not run | +| only in a repository outside the main repository, at a path with a `..` component that the head revision's tree records as a submodule | that one | `error`, naming the path as one that leaves the repository; the same answer when nothing is at that outside path | +| only in a repository outside the main repository, reached through a symbolic link in the working tree that is part of a recorded submodule path | that one | `error`, naming the path as one that leaves the repository | +| in a tracked file of a submodule whose path ends in a space | one, checked out | `ok` | +| nowhere | one, not checked out, mounted under `openspec/` | `missing` | +| only in a tracked file of a submodule | one, checked out elsewhere inside the working tree of the main repository, whose own directory is a symbolic link to that checkout | `error`, naming the Example and the submodule's path as not checked out | +| in a tracked file of a submodule | one, checked out; the variable `GIT_DIR` is set to the git directory of the main repository | `ok` | +| only in the recorded commits of seven submodules | seven, none checked out | `error`, naming the Example, the first five paths in order and the number of the other two | +| nowhere | one whose directory holds a `.git` entry that git cannot open | `error`, naming the Example and the submodule's path as one git refused to open | +| nowhere | one whose directory holds an empty `.git` directory and, beside it, ordinary files shaped like a git directory (`HEAD`, `config`, `objects/`, `refs/`) whose `config` names a command to run | `error`, naming the submodule's path as one git refused to open; the command named in that `config` does not run | +| in a tracked file of the main repository | one, checked out as a partial clone that never fetched the file contents of the recorded commit | `ok`; nothing is fetched into the submodule | +| nowhere | one, checked out as a partial clone that never fetched the file contents of the recorded commit | `error`, naming the Example and the submodule's path; nothing is fetched into the submodule | +| nowhere | one, not checked out, whose path is longer than 200 characters | `error`, naming the first 200 characters of the path followed by `...` | +| in a tracked file of one submodule | two; the one with the marker checked out, the other not | `ok` | +| only in a file ending in `.md` of a submodule | one, checked out, whose object store lacks the content of another file of the recorded commit | `error`, naming the Example and the submodule's path | +| only in a tracked file of a submodule | one whose `.git` entry git opens, with the working tree of that git directory set to the parent directory, so that git names the parent as the top | `error`, naming the Example and the submodule's path as not checked out | +| only in a submodule of a submodule | three recorded paths: `a`, checked out; its own submodule `a/inner`, not checked out; and `a-b`, not checked out | `error`, naming `a-b` before `a/inner` | +| nowhere | one, at a path with a `.` component that the head revision's tree records | `error`, naming the path as one that leaves the repository | +| in a tracked file of a submodule | one, checked out; the six variables named above are all set to the git directory, working tree, index and object store of the main repository | `ok` | +| only in the recorded commit of a submodule, which the checked-out submodule's own object store lacks | one, checked out; the variable `GIT_ALTERNATE_OBJECT_DIRECTORIES` names an object store that holds that commit | `error`, naming the Example and the submodule's path, with the recorded commit as not in its object store | +| only in a submodule of a submodule, checked out and complete | the outer one checked out, its object store lacking the content of one unrelated file of its recorded commit | `ok` | +| nowhere | the same two | `error`, naming the Example and the outer submodule's path only, with its recorded commit as one that could not be read | +| in a tracked file of one submodule | two; the other one is not checked out and comes first in the order of the paths | `ok` | +| in a tracked file that counts, of a submodule whose object store lacks the content of another file of the recorded commit | one, checked out | `ok` | +| nowhere | one, checked out, holding every object of the recorded commit; git writes to its error stream during the search (`GIT_TRACE=1`) | `missing` | +| only in a tracked file of a submodule | one, checked out; git reports a version older than 2.45, or one that cannot be read | `error`, naming the Example and the submodule's path with git as older than 2.45; no git command runs in the directory of the submodule | +| in a tracked file of the main repository | one, checked out; git reports a version older than 2.45 | `ok` | +| nowhere | one, checked out, whose object store holds a damaged copy of the content of one file of the recorded commit (the object file is present and is not a compressed object, so the search ends with exit code 128) | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read | +| only in a tracked file of a submodule; the object that holds the content of that file is present but empty (zero bytes); depending on its version, git either skips the file and ends the search with exit code 0 or 1, or ends the search with exit code 128 | one, checked out | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read | +| nowhere | one, checked out, holding every object of the recorded commit; one of its tracked files has a name with a carriage return followed by `?` | `missing` | +| in a tracked file of a submodule | one, checked out, whose object store holds a damaged copy of the content of another file, so that the search ends with exit code 128 | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read; the same answer on each of three runs | +| only in a submodule of a submodule, checked out and complete | the outer one checked out, its object store lacking a tree below the top of its recorded commit | `error`, naming the Example and the outer submodule's path only, with its recorded commit as one that could not be read | +| nowhere | one, checked out; the object that holds the content of one file is damaged in its body, so that git lists it and opens it, and the search ends with exit code 128 | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read | +| only in a repository placed inside the git directory of the main repository, reached through a symbolic link in the working tree that is part of a recorded submodule path | that one | `error`, naming the path as one that leaves the repository; git is not run in that directory | +| only in a repository placed inside the git directory of the main repository; the command runs in a linked worktree whose top directory holds the main repository, and a symbolic link in that worktree that is part of a recorded submodule path leads into that git directory | that one | `error`, naming the path as one that leaves the repository; git is not run in that directory | +| only in a repository placed inside the git directory of a submodule whose `.git` entry is a directory, reached through a symbolic link in that submodule that is part of a submodule path its recorded commit records | the outer one, checked out, and that one | `ok` | +| in a tracked file of a submodule | one, checked out; the git directory of the main repository was made apart from its working tree and the top directory lies inside it | `ok` | +| only in an earlier commit of the main repository, which the head revision records as a submodule at a path that a symbolic link in the working tree leads back to the top directory | that one | `ok` | +| in a tracked file of a submodule that is checked out inside the working tree and reached through a symbolic link in the working tree that is part of its recorded path; the link's target names the top directory in another letter case, on a volume that does not distinguish letter case | that one | `ok` | +| in a tracked file of a submodule | one, checked out; the directory it is checked out in differs from the recorded path in letter case only, on a volume that does not distinguish letter case, and git, run there, names the directory as it is named on disk | `ok` | +| only in a repository outside the top directory, reached through a symbolic link in the working tree that is part of a recorded submodule path; the link's target names that outside directory in another letter case, on a volume that does not distinguish letter case | that one | `error`, naming the path as one that leaves the repository; git is not run in that directory | +| only in a repository placed inside the git directory of the main repository, reached through a symbolic link in the working tree that is part of a recorded submodule path; the link's target names the top directory in another letter case, on a volume that does not distinguish letter case | that one | `error`, naming the path as one that leaves the repository; git is not run in that directory | +| only in a tracked file of a submodule whose recorded path names the spec directory in another letter case, so that its directory lies under `openspec/`, on a volume that does not distinguish letter case | one, checked out | `missing`; git is not run in that directory | +| only in a tracked file of a submodule that is checked out under `openspec/` and reached through a symbolic link in the working tree that is part of its recorded path | that one | `missing`; git is not run in that directory | diff --git a/openspec/changes/archive/2026-11-16-idd-548-fix8/tasks.md b/openspec/changes/archive/2026-11-16-idd-548-fix8/tasks.md new file mode 100644 index 00000000..401442a1 --- /dev/null +++ b/openspec/changes/archive/2026-11-16-idd-548-fix8/tasks.md @@ -0,0 +1,20 @@ +## 1. 測試 + +- [x] 1.1 依 design「第 50 列的 fixture 記下結束碼,不停下」「測試檔的註解寫量到的版本」與 Implementation Contract:`plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 第 50 列,註解換成新的說法,前提檢查那一行換成「記下 `git grep` 的結束碼,大於 1 時印說明行」。驗證:改之前的測試檔在 git 2.56.0 上停在第 50 列;改之後 `bash plugins/issue-driven-dev/scripts/tests/spec-change/test.sh` 在 git 2.54.0、2.55.0、2.56.0 上都是 878 項通過、0 項失敗,只有 2.56.0 印出說明行;`git diff` 對 `plugins/issue-driven-dev/scripts/spec-change.py` 沒有輸出。 + - 紀錄,改之前(`e5022f4` 的測試檔,git 2.56.0 在 PATH 最前面,macOS):559 項通過之後印出 `FATAL: spec-change suite: fixture setup failed: the search of a submodule with an empty object must end with 0 or 1`,結束碼 1。與 PR #572 的 CI(git 2.56.1、ubuntu-26.04)停在同一行。 + - 紀錄,改之後(同一台機器,`spectra` 在 PATH 上):git 2.54.0、2.55.0、2.56.0 各跑一次,都是 878 項通過、0 項失敗、結束碼 0。2.54.0 與 2.55.0 沒有印說明行;2.56.0 印出 `~ note: this git ends the search of an empty object with exit code 128, row 50 takes the path of row 49`。 + - 同一個輸入上三個版本的 `git grep` 結束碼:1、1、128。前兩個印 `error: … unable to read …`,第三個印 `fatal: loose object … is corrupt`。 + - git 2.56.0 是把 Homebrew 的 bottle 解到暫存目錄執行的,沒有安裝。CI 用的 2.56.1 沒有在本機跑過。 + - `git diff` 對 `spec-change.py` 沒有輸出;測試檔的差異只有第 50 列:註解 2 行換成 4 行,前提檢查 1 行換成 4 行。 + +## 2. 文字 + +- [x] 2.1 依 design「Example 第一欄寫兩種情形,不寫版本號」與 Implementation Contract:這個 change 的規格差異把 requirement「Added and modified requirements carry an executable check」的 Example「markers in submodules」第 50 列第一欄的後半句換掉,其他不變。驗證:規格差異與現行 requirement 逐行比對,只有那一列不同;`spectra validate idd-548-fix8` 通過。 + - 紀錄:規格差異由腳本從現行 requirement 產生,只做一處取代,而且要求恰好一處相符。現行 123 行,差異 123 行,移除 1 行、加入 1 行,就是第 50 列;Example 仍是 65 列。`spectra validate idd-548-fix8` 回 valid。 + +## 3. 收尾 + +- [x] 3.1 [after: 1.1, 2.1] 依 Implementation Contract 驗收:封存之前 `bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 與 `bash .claude/scripts/tests/spectra-archive-post-ic/test.sh` 結束碼都是 0,數字記在這一項底下。封存之後的三項檢查(`spec-change.py links` 從預設分支到 HEAD、`archived`、現行規格與封存前只差那一列)要等封存完才能跑,結果記在 issue 的實作摘要,不記在這裡。 + - 驗收紀錄。這個 change 的文件、規格差異與測試修改都由同一個協調者撰寫,沒有獨立讀者,也不開 verify 輪(維護者的決定,留言 6910032608)。環境:macOS、Python 3.13.5、git 2.55.0。 + - 封存之前,在改過的工作目錄上:`bash plugins/issue-driven-dev/scripts/run-all-tests.sh` 75 個 suite、0 個失敗,結束碼 0,其中 `spec-change` 878 項通過;`bash .claude/scripts/tests/spectra-archive-post-ic/test.sh` 141 項通過、0 項失敗,結束碼 0。 + - 沒有做的:這個 change 沒有在 Linux 上跑過;推上去之後 PR #572 的 CI 會跑,第 50 列以後的檢查是第一次在那裡執行。design 的 Risks 第一點(git 2.56 起沒有只有「先問哪些物件打不開」那一步才抓得到的測試輸入)沒有處理。 diff --git a/openspec/specs/spec-on-every-issue/spec.md b/openspec/specs/spec-on-every-issue/spec.md index 98c2cc79..25f93329 100644 --- a/openspec/specs/spec-on-every-issue/spec.md +++ b/openspec/specs/spec-on-every-issue/spec.md @@ -231,7 +231,15 @@ After apply and before `idd-verify`, the wrapper (for the Spectra tier, `idd-all --- ### Requirement: Added and modified requirements carry an executable check -`scripts/spec-change.py links --base <rev>` SHALL compare the files under `openspec/specs/` at `<rev>` and at `--head` (default `HEAD`). For every requirement that is new or whose text differs between the two, it SHALL require one of two things: at least one `##### Example:` under the requirement, where each such Example has a title that is unique within its capability and a tracked file at the head revision, outside `openspec/` and not ending in `.md`, that contains the marker `spec-example: <capability> / <Example title>`; or a line under the requirement that starts with `No executable check:` followed by a reason. A requirement that does not differ SHALL NOT be checked. A marker counts only when nothing but whitespace, or the comment closer `-->` or `*/`, follows the Example title on its line. Lines inside a code fence are not read as `##### Example:` or `No executable check:` lines; a fence opened by three or more backticks or tildes, at any indentation (as inside a list item), closes only on a line of the same character, at least as long, with nothing but whitespace after it; lines end only at `\n`, `\r\n` or `\r`. A requirement heading indented by up to three spaces SHALL be read as a requirement, as Spectra reads it. Paths SHALL be read as git stores them, never in git's quoted form, so a capability whose directory name is not ASCII is checked like any other. Two requirements with the same name in one capability SHALL make the command print `error`. So SHALL a code fence at the head revision that never closes, since the requirements after it would go unchecked. Outside code fences, a heading that starts with `### Requirement` but does not have the form `### Requirement: <name>` with a non-empty name SHALL make the command print `error`, and so SHALL a head revision at which the spec directory's `specs/` holds no tracked file. The command SHALL print one JSON line with `status` (`ok`, `missing` or `error`) and a list naming each requirement or Example that lacks its check, and SHALL exit 0, 1 or 2 in that order. `--base` is required: the caller names the range, so that a run on the default branch is checked against the commit it started from. The marker ties an Example to a test by name only; whether the test exercises what the Example states is judged by the reviewers of `idd-verify`. +`scripts/spec-change.py links --base <rev>` SHALL compare the files under `openspec/specs/` at `<rev>` and at `--head` (default `HEAD`). For every requirement that is new or whose text differs between the two, it SHALL require one of two things: at least one `##### Example:` under the requirement, where each such Example has a title that is unique within its capability and a tracked file at the head revision, outside `openspec/` and not ending in `.md`, that contains the marker `spec-example: <capability> / <Example title>` (a tracked file of a submodule counts, as the paragraph "Submodules" below describes); or a line under the requirement that starts with `No executable check:` followed by a reason. A requirement that does not differ SHALL NOT be checked. A marker counts only when nothing but whitespace, or the comment closer `-->` or `*/`, follows the Example title on its line. Lines inside a code fence are not read as `##### Example:` or `No executable check:` lines; a fence opened by three or more backticks or tildes, at any indentation (as inside a list item), closes only on a line of the same character, at least as long, with nothing but whitespace after it; lines end only at `\n`, `\r\n` or `\r`. A requirement heading indented by up to three spaces SHALL be read as a requirement, as Spectra reads it. Paths SHALL be read as git stores them, never in git's quoted form, so a capability whose directory name is not ASCII is checked like any other. Two requirements with the same name in one capability SHALL make the command print `error`. So SHALL a code fence at the head revision that never closes, since the requirements after it would go unchecked. Outside code fences, a heading that starts with `### Requirement` but does not have the form `### Requirement: <name>` with a non-empty name SHALL make the command print `error`, and so SHALL a head revision at which the spec directory's `specs/` holds no tracked file, and a path under the spec directory's `specs/` that is not valid UTF-8 (the reason says so and carries no text of an exception). Such a path elsewhere under the spec directory does not change the answer. The command SHALL print one JSON line with `status` (`ok`, `missing` or `error`) and a list naming each requirement or Example that lacks its check, and SHALL exit 0, 1 or 2 in that order. `--base` is required: the caller names the range, so that a run on the default branch is checked against the commit it started from. The marker ties an Example to a test by name only; whether the test exercises what the Example states is judged by the reviewers of `idd-verify`. + +Submodules. The tracked files at the head revision include the tracked files of every submodule of the repository at the commit that the head revision records for it, and in the same way the files of a submodule of a submodule. The command SHALL read that recorded commit, not the commit the submodule's working tree is on. It SHALL find the submodules itself, from the entries of the head revision's tree that record a commit; it SHALL NOT rely on git's own recursion into submodules, which passes over a submodule that is not checked out without saying so; the answer SHALL be the same whether or not the git configuration turns that recursion on (`submodule.recurse`). A file of a submodule is named by the submodule's path followed by the file's path, and the two exclusions (under the spec directory, ending in `.md`) apply to that name. A submodule whose own path is under the spec directory SHALL NOT be searched and SHALL NOT count as one that could not be searched: none of its files could count. Nor SHALL a submodule be searched, or count as one that could not be searched, when its directory, after symbolic links are resolved, is the spec directory of the main repository or lies under it, whatever its path is named: a symbolic link, or another spelling of the name on a volume that does not distinguish letter case, can lead into the spec directory from a path that is not under it by name. This is decided after conditions 1 and 2 of the paragraph "Which submodules can be searched" below, and in the way of condition 2: the spec directory is one of the directories passed before the top directory is met, and directories are compared, not names. A spec directory that cannot be examined has nothing under it. + +Order of the search. For each Example the command SHALL search the main repository first. When the marker is found there, the Example has its check and the command SHALL NOT run git in any submodule for it, so for a repository whose markers are all in its own files no entry that records a commit is listed and no submodule is examined, whatever its head revision records. Only when the marker is not found in the main repository are the submodules searched, and a marker found in one submodule settles the Example whatever the state of the others. When the marker of an Example is found, the Example has its check, whether or not every submodule could be searched. The submodules inside a submodule are read from a listing of every tree of its recorded commit, and that listing is made only when the outer one meets its own six conditions. Each of them is then searched whenever its own six conditions hold, also when the search of the outer one failed. When the listing fails, because a tree of the recorded commit cannot be read, the submodules inside it are unknown, even when the top tree shows them. + +Which submodules can be searched. A submodule SHALL be searched only when all six of these hold: (1) its path, as the tree records it, is relative and has no empty, `.` or `..` component; (2) its directory, after symbolic links are resolved, is the top directory of the main repository or lies under it, which means that the top directory is met when going from the resolved directory to its parent directory, to the parent of that one, and so on; and no directory passed before the top directory is met (the resolved directory itself, unless it is the top directory, and each directory between the two) is one of two directories, the one that `git rev-parse --absolute-git-dir` prints and the one that `git rev-parse --git-common-dir` prints when run at the top directory (in a linked worktree these are two different directories); (3) the directory itself is not a symbolic link; (4) the directory holds an entry named `.git` of its own; (5) git, run in the directory, reports that same directory as the top of its own working tree; (6) its object store holds the recorded commit. In conditions 2 and 5 directories are compared, not names: two paths name the same directory when the operating system reports the same device and the same inode for both, however each path is spelled (on a volume that does not distinguish letter case, for one, a path written in another letter case names the same directory). A directory on the way up that cannot be examined (one that does not exist, for one) is passed over: it is neither the top directory nor one of the two. The two directories of condition 2 are a closed list: no other directory is refused under that condition. No git directory of a submodule is added to the list: when the git directory of a submodule is itself one of the two, or lies under one of them, condition 2 applies to it as written, and otherwise a directory inside it is searched when the six conditions hold. The top directory is not compared with the two, so when the top directory is one of them, or lies inside one of them, neither it nor the directories under it are refused for that reason. A directory that resolves to the top directory itself meets condition 2. The command SHALL NOT run git in a directory that fails any of the first four: a directory of ordinary tracked files can be shaped like a git directory, and git would read, and act on, the configuration it holds. Nor SHALL it run git in the directory of any submodule when git is older than 2.45, the first version that honours `GIT_NO_LAZY_FETCH`, or when the version cannot be read: a submodule for which the first four hold then counts as one that could not be searched. In the directory of a submodule the command SHALL run git with `safe.bareRepository` set to `explicit`, with lazy fetching turned off (`GIT_NO_LAZY_FETCH=1`), and with the variables `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, `GIT_OBJECT_DIRECTORY`, `GIT_ALTERNATE_OBJECT_DIRECTORIES` and `GIT_COMMON_DIR` removed from the environment it inherited. Before it searches a submodule the command SHALL ask git which objects of the recorded commit (its trees and the contents of its files) the object store lacks or cannot open, without fetching any: an object whose file is present but cannot be opened (for example an empty file) counts as lacking. A submodule is searched even when some are lacking, and a file that counts, found by a search that ran to its end (exit code 0 or 1), settles the Example. What a search printed before it ended with another exit code SHALL NOT be used, so that the answer for one state of the repository is the same on every run. When no file that counts is found in it, the submodule counts as one that could not be searched if its object store lacks an object of the recorded commit, if the search exits with a code other than 0 or 1, or if the trees of the recorded commit cannot all be listed. What git writes to its error stream SHALL NOT change whether a submodule counts as searched, nor the reason reported for it. In the main repository a search that exits with a code other than 0 or 1 is `error`, as before; its reason is `git grep failed: ` followed by the first 200 characters of what git wrote to its error stream, also as before. + +What is reported. When the marker is not found and every submodule was searched, the Example is reported as lacking its check, as before. When it is not found and at least one submodule could not be searched, the command SHALL print `error` and name the first such Example it meets, the submodules that could not be searched and the reason for each: an Example whose candidate files were not all read is not reported as lacking its check. The submodules are named by path, in the order of their paths and joined by `; `; a submodule of a submodule is named by its path under the outer one; when more than five could not be searched, the first five are named and the number of the others is stated; a path longer than 200 characters is cut to its first 200 followed by `...`. The reason is one of six: the path leaves the repository (conditions 1 and 2); the submodule is not checked out (conditions 3 and 4, or git names another directory as the top); git is older than 2.45 (stated also when its version cannot be read); git refused to open it (the git command of condition 5 fails); the recorded commit is not in its object store (condition 6); the recorded commit could not be read (its object store lacks or cannot open an object of it, or the search or the listing of its trees failed). The reason given for a submodule SHALL NOT carry text from git's error stream. The path of a submodule that is not valid UTF-8 is handled like any other path, and the command still prints one JSON line. A repository whose head revision records no submodule is searched in its own tracked files only: none of the rules for submodules changes its answer. #### Scenario: An Example without a test is reported @@ -267,11 +275,84 @@ After apply and before `idd-verify`, the wrapper (for the Spectra tier, `idd-all | added, its only `No executable check:` line inside a fence indented four spaces in a list item | none | not applicable | only inside that fence | `missing` | | added, in a capability whose directory name is not ASCII (`中文能力`) | none | not applicable | absent | `missing` | | added, in a capability whose directory name holds a double quote (`quo"te`) | none | not applicable | absent | `missing` | +| added, in a capability whose directory name is not valid UTF-8 | not applicable | not applicable | not applicable | `error`, with a reason that says so | +| added; a tracked path under the spec directory but outside `specs/` is not valid UTF-8 | one | in `scripts/tests/x/test.sh` | absent | `ok` | +| added; a tree of the head revision outside the spec directory cannot be read | one | absent | absent | `error`; the reason is `git grep failed: ` followed by the first 200 characters of what git wrote to its error stream | | added twice with the same name in one capability | not applicable | not applicable | not applicable | `error` | | any, after a code fence that never closes | not applicable | not applicable | not applicable | `error` | | `--base` names a revision that does not exist | not applicable | not applicable | not applicable | `error` | | `--base` is not given | not applicable | not applicable | not applicable | usage error, exit 64 | +##### Example: markers in submodules + +| Where the marker of the Example is at the head revision | Submodules recorded at the head revision | `status` | +| --- | --- | --- | +| in a tracked file of a submodule, at the commit the head revision records | one, checked out | `ok` | +| in a tracked file of a submodule of a submodule | both checked out | `ok` | +| in a tracked file of a submodule whose path holds a space | one, checked out | `ok` | +| only in the recorded commit of a submodule whose working tree is on a later commit without it | one, checked out | `ok` | +| only in a later commit of a submodule, which its working tree is on, not in the recorded commit | one, checked out | `missing` | +| only in a file of a submodule that ends in `.md` | one, checked out | `missing` | +| nowhere | one, checked out | `missing` | +| nowhere in the main repository | one, not checked out | `error`, naming the Example and the submodule's path | +| in a tracked file of the main repository | one, not checked out | `ok` | +| nowhere in the main repository | one, checked out, whose object store lacks the recorded commit | `error`, naming the Example and the submodule's path | +| in a tracked file of the main repository | one, checked out, whose object store lacks the recorded commit; `submodule.recurse` is true in the repository's git configuration | `ok` | +| nowhere in the main repository | one, checked out, whose object store lacks the recorded commit; `submodule.recurse` is true in the repository's git configuration | `error`, naming the Example and the submodule's path | +| only in the recorded commits of two submodules | two, neither checked out | `error`, naming the Example and both paths, joined by `; ` | +| only in a submodule of a submodule | the outer one checked out, the inner one not | `error`, naming the Example and the inner submodule by its path under the outer one | +| only in a tracked file of a submodule that is mounted under `openspec/` | one, checked out | `missing` | +| in a tracked file of the main repository | one whose path is not valid UTF-8, not checked out | `ok` | +| nowhere | one whose path is not valid UTF-8, not checked out | `error` on one JSON line, exit 2 | +| in a tracked file of the main repository | one, checked out, holding the recorded commit but not the tree of that commit | `ok` | +| nowhere in the main repository | one, checked out, holding the recorded commit but not the tree of that commit | `error`, naming the Example and the submodule's path, with no text from git's error stream | +| nowhere | one, checked out, whose object store lacks the content of one file of the recorded commit | `error`, naming the Example and the submodule's path, with no text from git's error stream | +| nowhere | one, checked out, whose recorded commit records a second submodule; at that second path the working tree holds ordinary files shaped like a git directory (`HEAD`, `config`, `objects/`, `refs/`) and no `.git` entry, and that `config` names a command to run | `error`, naming the second path as not checked out; the command named in that `config` does not run | +| in a tracked file of the main repository | the same two, with the same files at the second path | `ok`; no git command runs in the directory of a submodule, and the command named in that `config` does not run | +| only in a repository outside the main repository, at a path with a `..` component that the head revision's tree records as a submodule | that one | `error`, naming the path as one that leaves the repository; the same answer when nothing is at that outside path | +| only in a repository outside the main repository, reached through a symbolic link in the working tree that is part of a recorded submodule path | that one | `error`, naming the path as one that leaves the repository | +| in a tracked file of a submodule whose path ends in a space | one, checked out | `ok` | +| nowhere | one, not checked out, mounted under `openspec/` | `missing` | +| only in a tracked file of a submodule | one, checked out elsewhere inside the working tree of the main repository, whose own directory is a symbolic link to that checkout | `error`, naming the Example and the submodule's path as not checked out | +| in a tracked file of a submodule | one, checked out; the variable `GIT_DIR` is set to the git directory of the main repository | `ok` | +| only in the recorded commits of seven submodules | seven, none checked out | `error`, naming the Example, the first five paths in order and the number of the other two | +| nowhere | one whose directory holds a `.git` entry that git cannot open | `error`, naming the Example and the submodule's path as one git refused to open | +| nowhere | one whose directory holds an empty `.git` directory and, beside it, ordinary files shaped like a git directory (`HEAD`, `config`, `objects/`, `refs/`) whose `config` names a command to run | `error`, naming the submodule's path as one git refused to open; the command named in that `config` does not run | +| in a tracked file of the main repository | one, checked out as a partial clone that never fetched the file contents of the recorded commit | `ok`; nothing is fetched into the submodule | +| nowhere | one, checked out as a partial clone that never fetched the file contents of the recorded commit | `error`, naming the Example and the submodule's path; nothing is fetched into the submodule | +| nowhere | one, not checked out, whose path is longer than 200 characters | `error`, naming the first 200 characters of the path followed by `...` | +| in a tracked file of one submodule | two; the one with the marker checked out, the other not | `ok` | +| only in a file ending in `.md` of a submodule | one, checked out, whose object store lacks the content of another file of the recorded commit | `error`, naming the Example and the submodule's path | +| only in a tracked file of a submodule | one whose `.git` entry git opens, with the working tree of that git directory set to the parent directory, so that git names the parent as the top | `error`, naming the Example and the submodule's path as not checked out | +| only in a submodule of a submodule | three recorded paths: `a`, checked out; its own submodule `a/inner`, not checked out; and `a-b`, not checked out | `error`, naming `a-b` before `a/inner` | +| nowhere | one, at a path with a `.` component that the head revision's tree records | `error`, naming the path as one that leaves the repository | +| in a tracked file of a submodule | one, checked out; the six variables named above are all set to the git directory, working tree, index and object store of the main repository | `ok` | +| only in the recorded commit of a submodule, which the checked-out submodule's own object store lacks | one, checked out; the variable `GIT_ALTERNATE_OBJECT_DIRECTORIES` names an object store that holds that commit | `error`, naming the Example and the submodule's path, with the recorded commit as not in its object store | +| only in a submodule of a submodule, checked out and complete | the outer one checked out, its object store lacking the content of one unrelated file of its recorded commit | `ok` | +| nowhere | the same two | `error`, naming the Example and the outer submodule's path only, with its recorded commit as one that could not be read | +| in a tracked file of one submodule | two; the other one is not checked out and comes first in the order of the paths | `ok` | +| in a tracked file that counts, of a submodule whose object store lacks the content of another file of the recorded commit | one, checked out | `ok` | +| nowhere | one, checked out, holding every object of the recorded commit; git writes to its error stream during the search (`GIT_TRACE=1`) | `missing` | +| only in a tracked file of a submodule | one, checked out; git reports a version older than 2.45, or one that cannot be read | `error`, naming the Example and the submodule's path with git as older than 2.45; no git command runs in the directory of the submodule | +| in a tracked file of the main repository | one, checked out; git reports a version older than 2.45 | `ok` | +| nowhere | one, checked out, whose object store holds a damaged copy of the content of one file of the recorded commit (the object file is present and is not a compressed object, so the search ends with exit code 128) | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read | +| only in a tracked file of a submodule; the object that holds the content of that file is present but empty (zero bytes); depending on its version, git either skips the file and ends the search with exit code 0 or 1, or ends the search with exit code 128 | one, checked out | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read | +| nowhere | one, checked out, holding every object of the recorded commit; one of its tracked files has a name with a carriage return followed by `?` | `missing` | +| in a tracked file of a submodule | one, checked out, whose object store holds a damaged copy of the content of another file, so that the search ends with exit code 128 | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read; the same answer on each of three runs | +| only in a submodule of a submodule, checked out and complete | the outer one checked out, its object store lacking a tree below the top of its recorded commit | `error`, naming the Example and the outer submodule's path only, with its recorded commit as one that could not be read | +| nowhere | one, checked out; the object that holds the content of one file is damaged in its body, so that git lists it and opens it, and the search ends with exit code 128 | `error`, naming the Example and the submodule's path, with its recorded commit as one that could not be read | +| only in a repository placed inside the git directory of the main repository, reached through a symbolic link in the working tree that is part of a recorded submodule path | that one | `error`, naming the path as one that leaves the repository; git is not run in that directory | +| only in a repository placed inside the git directory of the main repository; the command runs in a linked worktree whose top directory holds the main repository, and a symbolic link in that worktree that is part of a recorded submodule path leads into that git directory | that one | `error`, naming the path as one that leaves the repository; git is not run in that directory | +| only in a repository placed inside the git directory of a submodule whose `.git` entry is a directory, reached through a symbolic link in that submodule that is part of a submodule path its recorded commit records | the outer one, checked out, and that one | `ok` | +| in a tracked file of a submodule | one, checked out; the git directory of the main repository was made apart from its working tree and the top directory lies inside it | `ok` | +| only in an earlier commit of the main repository, which the head revision records as a submodule at a path that a symbolic link in the working tree leads back to the top directory | that one | `ok` | +| in a tracked file of a submodule that is checked out inside the working tree and reached through a symbolic link in the working tree that is part of its recorded path; the link's target names the top directory in another letter case, on a volume that does not distinguish letter case | that one | `ok` | +| in a tracked file of a submodule | one, checked out; the directory it is checked out in differs from the recorded path in letter case only, on a volume that does not distinguish letter case, and git, run there, names the directory as it is named on disk | `ok` | +| only in a repository outside the top directory, reached through a symbolic link in the working tree that is part of a recorded submodule path; the link's target names that outside directory in another letter case, on a volume that does not distinguish letter case | that one | `error`, naming the path as one that leaves the repository; git is not run in that directory | +| only in a repository placed inside the git directory of the main repository, reached through a symbolic link in the working tree that is part of a recorded submodule path; the link's target names the top directory in another letter case, on a volume that does not distinguish letter case | that one | `error`, naming the path as one that leaves the repository; git is not run in that directory | +| only in a tracked file of a submodule whose recorded path names the spec directory in another letter case, so that its directory lies under `openspec/`, on a volume that does not distinguish letter case | one, checked out | `missing`; git is not run in that directory | +| only in a tracked file of a submodule that is checked out under `openspec/` and reached through a symbolic link in the working tree that is part of its recorded path | that one | `missing`; git is not run in that directory | + --- ### Requirement: A fix after a verify round goes through the same wrapper @@ -492,3 +573,9 @@ Every subcommand of `scripts/spec-change.py` that takes `--cwd` (`archived`, `li | `pf ` has an `openspec/` directory, the sibling `pf` does not | `preflight --cwd 'pf ' --can-write yes` | `ready` | | `pf ` alone, with an `openspec/` directory | `preflight --cwd 'pf ' --can-write yes` | `ready` | | `nl` followed by a newline has the change archived, the sibling `nl` does not | `archived` with `--cwd` that directory, `--ref HEAD` | `pass` | +| `sp ` (its name ends in a space) holds an added requirement with its marker in a tracked test file, and has the declared change archived; `copy` is the same repository under a name that does not end in a space | `links` with `--cwd` at each | `ok` for both, with the same JSON line and exit code | +| the same two repositories | `archived` with `--cwd` at each, `--ref HEAD` | `pass` for both, with the same JSON line and exit code | +| the same two repositories | `preflight` with `--cwd` at each, `--can-write yes` | `ready` for both, with the same exit code | +| the same repository under a name that ends in a line feed, and `copy` | `links` with `--cwd` at each | `ok` for both, with the same JSON line and exit code | +| the same two repositories | `archived` with `--cwd` at each, `--ref HEAD` | `pass` for both, with the same JSON line and exit code | +| the same two repositories | `preflight` with `--cwd` at each, `--can-write yes` | the same `status` and exit code for both | diff --git a/plugins/issue-driven-dev/CHANGELOG.md b/plugins/issue-driven-dev/CHANGELOG.md index c6df23db..0d4cbf52 100644 --- a/plugins/issue-driven-dev/CHANGELOG.md +++ b/plugins/issue-driven-dev/CHANGELOG.md @@ -5,6 +5,50 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] + +Version number left to the release. + +### Changed + +- **`spec-change.py links` reads markers in submodules (#548).** Tracked files of checked-out submodules, + including nested ones, count at the commit the head revision records, even when their working trees are on + another commit. A marker found in the main repository settles the Example without listing gitlinks or + running git in any submodule; otherwise the search stops at the first submodule with a marker, even if + another could not be searched. Searching submodules requires git 2.45 or later; older git, or git whose + version cannot be read, does not run in their directories. A submodule is searched only + if its recorded path is relative with no empty, `.` or `..` component, its resolved directory is the + top directory or lies under it (the top directory is met on the way up from it) and neither it, unless it is + the top directory, nor a directory between it and the top directory is one of the two directories git names + at the top directory (`git rev-parse --absolute-git-dir` and `--git-common-dir`; git is not run in such a + directory, no other directory is excluded, and no git directory of a submodule is added to the two), that + directory is not a symbolic link, it holds its own `.git` entry, git reports that same directory as the top of + its own working tree, and its object store holds the recorded commit. These comparisons are between + directories (device and inode), not names: a path that spells a directory in another letter case, on a volume + that does not distinguish letter case, names the same directory. Its object store + is asked which objects of that commit it lacks or cannot open (an object file that is present but cannot + be opened, for example an empty one, counts as lacking); a marker found in a file that counts, by a search that ran to its end, + still settles the Example even if other objects are missing. What a search printed before it ended early + is not used, so the answer is the same on every run. What git writes to its error stream does not change + whether a submodule counts as searched, nor the reason reported for it. + A submodule whose search failed still has its own submodules searched when all its trees can be listed. + If the marker is not found and a submodule could not be searched, + `links` answers `error` and names the Example and up to five submodule paths with fixed reasons. Paths + under the spec directory are skipped, and so is a submodule whose directory lies in the spec directory + under another name (reached through a symbolic link that leads there, or through a path that spells the + spec directory in another letter case): it is not searched and is not one that could not be searched. + Nothing is fetched into submodules during the check. + The search of the main repository no longer uses git's own recursion into submodules, so + `submodule.recurse` does not change an answer. With that setting on, 4.1.0 already found a marker in a + submodule, also in one that is initialised and has no working tree; when the marker is only there, + `links` now answers `error` (not checked out) until the submodule is checked out again + (`git submodule update --init`). + A path under the spec directory's `specs/` that is not valid UTF-8 gives a fixed error reason without + exception text; such a path elsewhere under the spec directory does not change the answer. + The Example of the 4.1.0 requirement on the top directory gains six rows: `links`, `archived` and + `preflight` answer for a repository whose name ends in a space, or in a line feed, as they do for a copy + under a plain name. + ## [4.1.0] - 2026-11-15 Ships #547, with the fixes for #508, #519, #512 and #502. diff --git a/plugins/issue-driven-dev/references/spec-wrapper.md b/plugins/issue-driven-dev/references/spec-wrapper.md index 01cd8f5e..f6a51018 100644 --- a/plugins/issue-driven-dev/references/spec-wrapper.md +++ b/plugins/issue-driven-dev/references/spec-wrapper.md @@ -91,6 +91,9 @@ Implementation Plan 留言(Plan tier 由 `idd-plan` 貼,Simple 由 `idd-impl - 每一條新增或改到的 requirement 至少一個 `##### Example:`,標題在該 capability 裡唯一;寫不出檢查的,寫一行 `No executable check:` 加理由。 - tasks 裡每個 Example 對應一個測試 task,測試檔要帶標記 `spec-example: <capability> / <Example title>`。 +標記也可以在 submodule 的已追蹤檔案裡,讀的是主 repo 記錄的 commit;搜尋 submodule 需要 git 2.45 或更新版本。檢查時 submodule 要已經取出,否則找不到標記的 Example 會讓檢查回 `error`。 +標記在 submodule 時,檢查前先跑 `git submodule update --init --recursive`;這會連到該分支的 `.gitmodules`、以及它為各 submodule 記錄的 commit 裡的 `.gitmodules` 所指定的位址,並把抓到的內容取出到工作樹;只在信任該分支與它記錄的 commit 時執行。部分 clone 的 submodule 必須先備齊記錄的 commit 所需的物件,因為檢查不會抓取物件。樹裡記成 submodule、`.gitmodules` 卻沒有對應項目的路徑無法取出,必須補上對應項目,或從樹裡移除該路徑。 + 無人值守的 run(照 [`unattended-contract.md`](unattended-contract.md) 判定)不能停在 Spectra 的問題上。先判定一次: ```bash diff --git a/plugins/issue-driven-dev/scripts/spec-change.py b/plugins/issue-driven-dev/scripts/spec-change.py index e76fbce5..cf9c5f66 100755 --- a/plugins/issue-driven-dev/scripts/spec-change.py +++ b/plugins/issue-driven-dev/scripts/spec-change.py @@ -16,6 +16,24 @@ links --base <rev> [--head <rev>] [--cwd <dir>] Does every requirement added or changed in base..head carry an executable check? + Tracked files of submodules count, read at the commit the head revision records. + Searching submodules requires git 2.45 or later. + A submodule can be searched only when checked out (its directory holds its own .git + entry and is the top of its own working tree) and its object store holds that commit. + Its directory must be the top directory or lie under it (the top is met on the way up from + it), and neither it, unless it is the top, nor a directory between it and the top may be one + of the two directories git names at the top (rev-parse --absolute-git-dir and + --git-common-dir): git is not run in such a directory. No other directory is excluded. + Directories are compared by device and inode, not by name: a path that spells one of them + in another way (another letter case on a volume that folds case) names the same directory. + A submodule whose directory is the spec directory or lies under it is not searched and is + not one that could not be searched, whatever its path is named (a link, or another + spelling of the name, that leads there): none of its files could count. + A file that counts settles the Example only when the search of its submodule ran to its end; + an object of the recorded commit that is absent or cannot be opened makes the submodule one + that could not be searched unless such a file was found. + If an Example's marker is not found and a submodule could not be searched, answer error. + A marker found in the main repository settles the Example without running git in any submodule. {"status": ok|missing|error, "missing": [{capability, requirement, example, why}], "reason": "..."} exit 0, 1, 2 @@ -146,7 +164,8 @@ def repo_top(cwd): p = git(cwd, "rev-parse", "--show-toplevel", check=False) if p.returncode != 0: raise Fail(f"{cwd} is not inside a git repository") - return one_line(p.stdout.decode("utf-8")) # a path may end in whitespace: only git's line ending goes + # A name may end in whitespace, or not be valid UTF-8: only git's line ending goes, and no byte is refused. + return one_line(os.fsdecode(p.stdout)) SPEC_DIR_RE = re.compile(r"^spec_dir:(.*)$") @@ -399,25 +418,256 @@ def examples(lines): return [m.group(1).strip() for m in (EXAMPLE_RE.match(l) for l in lines) if m] -def marker_files(top, head, needle, sd): +def submodule_git(cwd, *args, stdin=None): + """Read a checkout without inheriting another repository or fetching missing objects.""" + env = dict(os.environ, GIT_LITERAL_PATHSPECS="1", GIT_NO_LAZY_FETCH="1") + for name in ("GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_OBJECT_DIRECTORY", + "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_COMMON_DIR"): + env.pop(name, None) + command = ["git", "-c", "core.quotePath=false", "-c", "safe.bareRepository=explicit", "-C", cwd, *args] + try: + return subprocess.run(command, capture_output=True, env=env, input=stdin) + except OSError: + # A checkout that disappears or becomes unreadable is also unavailable. + return subprocess.CompletedProcess(command, 128, b"", b"") + + +def submodule_lacks_objects(directory, rev): + """Does the object store of a submodule lack, or fail to open, an object of the recorded commit?""" + p = submodule_git(directory, "rev-list", "--objects", "--no-walk", "--missing=print", rev) + if p.returncode != 0: + return True + ids = [] + # git ends every record with a line feed and prints a file name as it is, so split at line feeds only: + # a name can hold a carriage return, and "?" starts a record only when an object id follows it. + for record in p.stdout.split(b"\n"): + if not record: + continue + if re.fullmatch(rb"\?[0-9a-f]+", record): + return True + ids.append(record.split(b" ", 1)[0]) + # rev-list asks only whether each object exists. An object file that is present but cannot be opened (an + # empty file, for one) is listed as present, and the search skips the file without failing: --batch-check + # opens every object. One that opens and cannot be read to its end is caught by the exit code of the search. + # It gets the ids alone (with the names, every named object would be answered as missing), and it runs + # with lazy fetching off like every other command here. + p = submodule_git(directory, "cat-file", "--batch-check", stdin=b"".join(i + b"\n" for i in ids)) + answers = [line for line in p.stdout.split(b"\n") if line] + return p.returncode != 0 or len(answers) != len(ids) or any(a.endswith(b" missing") for a in answers) + + +def main_git_directories(top, cache): + """The two directories git names at the top directory: the git directory of this working tree and the common + git directory of the repository (in a linked worktree they differ). Asked once in a run, and only when a + submodule's directory is examined. A relative answer is relative to the top directory, where git ran; an + answer that names no directory ends the run (joined to the top directory it would be the top directory, + which is never compared).""" + if "main_git_dirs" not in cache: + found = [] + for option in ("--absolute-git-dir", "--git-common-dir"): + printed = one_line(os.fsdecode(git(top, "rev-parse", option).stdout)) + if not printed: + raise Fail("the git directory of the repository cannot be read") + found.append(printed if os.path.isabs(printed) else os.path.join(top, printed)) + cache["main_git_dirs"] = tuple(found) + return cache["main_git_dirs"] + + +def directories_below_top(directory, top): + """The directories passed on the way from directory, with symbolic links resolved, up to the top directory: + the resolved directory itself, unless it is the top directory, and each directory between the two. None when + the top directory is not met on the way up to the root. + + Directories are compared, not names: two paths name one directory when the operating system reports the same + device and inode for both. A resolved path can spell the top directory otherwise than git does (another letter + case on a volume that folds case; on macOS, with /System/Volumes/Data in front). A directory that cannot be + examined (one that is not there, for one) is not the top directory.""" + try: + top_stat = os.stat(top) + except OSError: + raise Fail("the top directory of the repository cannot be read") + passed = [] + current = os.path.realpath(directory) + while True: + try: + if os.path.samestat(os.stat(current), top_stat): + return passed + except OSError: + pass + parent = os.path.dirname(current) + if parent == current: # the root, and the top directory was not met + return None + passed.append(current) + current = parent + + +def under_git_directory(passed, git_dirs): + """Is one of the directories in passed (see directories_below_top) one of git_dirs? + + The top directory is not in passed, so it is never compared. Directories are compared, not names: a git + directory made apart can have any name, and on a volume that folds case a path can spell `.git` in another + case. A directory that cannot be examined is not one of them.""" + try: + wanted = [os.stat(git_dir) for git_dir in git_dirs] + except OSError: + raise Fail("the git directory of the repository cannot be read") + for current in passed: + try: + here = os.stat(current) + except OSError: + continue + if any(os.path.samestat(here, one) for one in wanted): + return True + return False + + +def leaves_repository(directory, top, cache): + """Condition 2 fails: the top directory is not met on the way up from the directory, or a directory passed + on that way is one of the two that git names at the top directory. Git is asked for the two only when the + top directory was met.""" + passed = directories_below_top(directory, top) + if passed is None: + return True + return under_git_directory(passed, main_git_directories(top, cache)) + + +def in_spec_directory(directory, top, sd): + """Is the directory, with symbolic links resolved, the spec directory of the main repository or under it? + Asked after condition 2 holds, so the top directory is met on the way up. Directories are compared, not + names: a link, or another spelling of the name, can lead into the spec directory from a path that is not + under it by name. A spec directory that cannot be examined (one that is not there) has nothing under it.""" + passed = directories_below_top(directory, top) + if not passed: + return False + try: + spec = os.stat(os.path.join(top, sd)) + except OSError: + return False + for current in passed: + try: + here = os.stat(current) + except OSError: + continue + if os.path.samestat(here, spec): + return True + return False + + +def same_directory(one, other): + """Do the two paths name one directory? Compared by device and inode, not by name.""" + try: + return os.path.samefile(one, other) + except OSError: + return False + + +def marker_files(top, head, needle, sd, cache): """Tracked files at head, outside the spec directory and not .md, with a line on which needle is followed - only by whitespace or a comment closer (a marker for `alpha table` does not count for the Example `alpha`).""" - p = git(top, "grep", "-z", "-F", "-e", needle, head, "--", ".", check=False) - if p.returncode not in (0, 1): - raise Fail("git grep failed: " + p.stderr.decode("utf-8", "replace").strip()[:200]) - files = [] - for line in p.stdout.decode("utf-8", "replace").split("\n"): - if not line: + only by whitespace or a comment closer; also return submodules that could not be searched.""" + unavailable, visited = [], set() + pending = [(top, head, "", None)] + while pending: + directory, rev, prefix, link = pending.pop() + if link is not None: + path = link["path"] + if link["reason"] is None: # Check a child only when the search reaches it. + reason = "" + if os.path.isabs(path) or any(p in ("", ".", "..") for p in path.split("/")): + reason = "path leaves the repository" + elif leaves_repository(directory, top, cache): + # Condition 2: not under the top directory, or one of the two directories, or under one. + reason = "path leaves the repository" + elif in_spec_directory(directory, top, sd): + # In the spec directory under another name: not searched, and not one that could not be. + link["in_spec"] = True + elif not os.path.isdir(directory) or os.path.islink(directory) or not os.path.lexists(os.path.join(directory, ".git")): + reason = "not checked out" + else: + if "git_supported" not in cache: + # Older git ignores GIT_NO_LAZY_FETCH, so do not open a submodule with it. + try: + p = subprocess.run(["git", "version"], capture_output=True) + version = re.match(rb"git version (\d+)\.(\d+)", p.stdout) + cache["git_supported"] = (p.returncode == 0 and version is not None + and tuple(map(int, version.groups())) >= (2, 45)) + except (OSError, ValueError): + cache["git_supported"] = False + if not cache["git_supported"]: + reason = "git is older than 2.45" + else: + p = submodule_git(directory, "rev-parse", "--show-toplevel") + reported_top = one_line(os.fsdecode(p.stdout)) + if p.returncode != 0: + reason = "git refused to open it" + elif not same_directory(reported_top, directory): + # Condition 5: git names another directory as the top (compared as directories). + reason = "not checked out" + elif submodule_git(directory, "cat-file", "-e", rev + "^{commit}").returncode != 0: + reason = f"recorded commit {rev[:12]} is not in its object store" + link["reason"] = reason + if link.get("in_spec"): + continue + if link["reason"]: + unavailable.append((prefix[:-1], link["reason"])) + continue + key = (os.path.realpath(directory), rev) + if key in visited: continue - where, _, content = line.partition("\0") - content = lines_of(content)[0] # CommonMark line endings: text after U+2028 stays on this line - path = where[len(head) + 1:] if where.startswith(head + ":") else where - if path.startswith(sd + "/") or path.lower().endswith(".md") or path in files: + visited.add(key) + cached = cache.setdefault(key, {}) + if link is not None and "lacks_objects" not in cached: + cached["lacks_objects"] = submodule_lacks_objects(directory, rev) + # --no-recurse-submodules: with submodule.recurse set, git grep would walk the submodules itself, skip one + # that is not checked out without saying so, and die on a recorded commit it cannot read. + args = ("grep", "--no-recurse-submodules", "-z", "-F", "-e", needle, rev, "--", ".") + p = submodule_git(directory, *args) if link is not None else git(directory, *args, check=False) + if link is None and p.returncode not in (0, 1): # the main repository: as before this branch + raise Fail("git grep failed: " + p.stderr.decode("utf-8", "replace").strip()[:200]) + # A search of a submodule that ended with another code printed as much as its worker threads got to: + # that output is not used, or the same repository would answer ok on one run and error on the next. + search_died = link is not None and p.returncode not in (0, 1) + for line in ([] if search_died else p.stdout.decode("utf-8", "replace").split("\n")): + if not line: + continue + where, _, content = line.partition("\0") + content = lines_of(content)[0] # CommonMark line endings: text after U+2028 stays on this line + path = prefix + (where[len(rev) + 1:] if where.startswith(rev + ":") else where) + if path.startswith(sd + "/") or path.lower().endswith(".md"): + continue + rests = content.split(needle)[1:] + if any(MARKER_REST_RE.fullmatch(rest) for rest in rests): + return [path], unavailable + unreadable = link is not None and (cached["lacks_objects"] or search_died) + if unreadable: + unavailable.append((prefix[:-1], "its recorded commit could not be read")) + # An unreadable file does not hide the gitlinks of a tree that can still be listed. + if "links" not in cached: + args = ("ls-tree", "-r", "-z", rev) + p = submodule_git(directory, *args) if link is not None else git(directory, *args) + cached["links"] = None + if p.returncode == 0: + links = [] + for entry in p.stdout.split(b"\0"): + if not entry: + continue + info, _, raw_path = entry.partition(b"\t") + mode, _, commit = info.decode("ascii").split() + if mode != "160000": + continue + links.append({"path": os.fsdecode(raw_path), "commit": commit, "reason": None}) + cached["links"] = links + if cached["links"] is None: + if not unreadable: + unavailable.append((prefix[:-1], "its recorded commit could not be read")) continue - rests = content.split(needle)[1:] - if any(MARKER_REST_RE.fullmatch(rest) for rest in rests): - files.append(path) - return files + children = [] + for child in cached["links"]: + path = child["path"] + if (prefix + path).startswith(sd + "/"): + continue + children.append((os.path.join(directory, path), child["commit"], prefix + path + "/", child)) + pending.extend(reversed(children)) + return [], unavailable def cmd_links(argv): @@ -427,11 +677,14 @@ def cmd_links(argv): base = resolve(top, a["--base"]) head = resolve(top, a.get("--head", "HEAD")) sd, sd_base = spec_dir_at(top, head), spec_dir_at(top, base) - base_files = {p[len(sd_base):]: p for p in spec_files(top, base, sd_base)} - if not git_text(top, "ls-tree", "-r", "-z", "--name-only", head, "--", f"{sd}/specs/").strip("\0"): - raise Fail(f"{sd}/specs/ holds no tracked file at {head[:12]}: check `spec_dir` in .spectra.yaml") - head_files = spec_files(top, head, sd) - missing = [] + try: + base_files = {p[len(sd_base):]: p for p in spec_files(top, base, sd_base)} + if not git_text(top, "ls-tree", "-r", "-z", "--name-only", head, "--", f"{sd}/specs/").strip("\0"): + raise Fail(f"{sd}/specs/ holds no tracked file at {head[:12]}: check `spec_dir` in .spectra.yaml") + head_files = spec_files(top, head, sd) + except UnicodeDecodeError: + raise Fail("a path under the spec directory is not valid UTF-8") + missing, cache = [], {} for path in head_files: cap = path[len(sd) + len("/specs/"):].split("/")[0] new = requirements(read_at(top, head, path), strict=True) @@ -455,14 +708,28 @@ def cmd_links(argv): elif titles.count(title) > 1: missing.append({"capability": cap, "requirement": name, "example": title, "why": "the Example title is used more than once in this capability"}) - elif not marker_files(top, head, f"spec-example: {cap} / {title}", sd): + else: + files, unavailable = marker_files(top, head, f"spec-example: {cap} / {title}", sd, cache) + if files: + continue + if unavailable: + reasons = [] + for path, reason in sorted(unavailable)[:5]: + path = path.encode("utf-8", "surrogateescape").decode("utf-8", "replace") + if len(path) > 200: + path = path[:200] + "..." + reasons.append(f"submodule {path}: {reason}") + if len(unavailable) > 5: + reasons.append(f"and {len(unavailable) - 5} more") + raise Fail(f"cannot decide whether the Example '{cap} / {title}' has a marker: " + "; ".join(reasons)) missing.append({"capability": cap, "requirement": name, "example": title, "why": f"no tracked file outside {sd}/ (and not .md) carries its marker"}) if missing: return emit({"status": "missing", "missing": missing, "reason": f"{len(missing)} item(s) without a check"}, 1) return emit({"status": "ok", "missing": [], "reason": ""}, 0) - except Fail as exc: - return emit({"status": "error", "missing": [], "reason": str(exc)}, 2) + except (Fail, OSError, ValueError, RecursionError) as exc: + reason = str(exc).encode("utf-8", "surrogateescape").decode("utf-8", "replace") + return emit({"status": "error", "missing": [], "reason": reason}, 2) # ── preflight ─────────────────────────────────────────────────────────────── diff --git a/plugins/issue-driven-dev/scripts/tests/spec-change/test.sh b/plugins/issue-driven-dev/scripts/tests/spec-change/test.sh index 10d0cc80..fae9656c 100755 --- a/plugins/issue-driven-dev/scripts/tests/spec-change/test.sh +++ b/plugins/issue-driven-dev/scripts/tests/spec-change/test.sh @@ -14,6 +14,8 @@ # spec-example: spec-on-every-issue / reading the Spec line # spec-example: spec-on-every-issue / whether the declared changes are archived at a commit # spec-example: spec-on-every-issue / what the link check reports +# spec-example: spec-on-every-issue / markers in submodules +# spec-example: spec-on-every-issue / a top level whose name ends in whitespace # spec-example: spec-on-every-issue / preflight by write access and Spectra state # spec-example: spec-on-every-issue / spec directory by .spectra.yaml # spec-example: spec-on-every-issue / choosing the Implementation Complete comment @@ -28,10 +30,29 @@ HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" SC="$HERE/../../spec-change.py" PY=$(command -v python3) GIT=$(command -v git) -WORK=$(mktemp -d "${TMPDIR:-/tmp}/idd-spec-change.XXXXXX") +# The rows about submodules need git 2.45 or later: spec-change.py does not open a submodule with an older git. +GIT_VERSION_TEXT=$("$GIT" version 2>/dev/null) +if ! printf '%s\n' "$GIT_VERSION_TEXT" | "$PY" -c 'import re, sys +m = re.match(r"git version (\d+)\.(\d+)", sys.stdin.read()) +sys.exit(0 if m and (int(m.group(1)), int(m.group(2))) >= (2, 45) else 1)'; then + echo "FATAL: spec-change suite: this suite needs git 2.45 or later; found: ${GIT_VERSION_TEXT:-no git version}" >&2 + exit 1 +fi +# Every fixture lives under $WORK and the suite removes paths below it: without it the suite must not start. +WORK=$(mktemp -d "${TMPDIR:-/tmp}/idd-spec-change.XXXXXX") || WORK="" +if [ -z "$WORK" ] || [ ! -d "$WORK" ]; then + echo "FATAL: spec-change suite: could not create a temporary directory under ${TMPDIR:-/tmp}" >&2 + exit 1 +fi trap 'rm -rf "$WORK"' EXIT # Isolate git from the caller's configuration (#452 lesson). export GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_NOSYSTEM=1 +# Nothing of the caller's git environment may reach the fixtures. Inside a git hook GIT_DIR would send every +# fixture commit to the caller's own repository; GIT_TRACE lengthens every message git writes. The rows that +# need one of these variables set it for the one call under test. +unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE GIT_OBJECT_DIRECTORY GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_COMMON_DIR \ + GIT_NAMESPACE GIT_TRACE GIT_TRACE2 GIT_TRACE2_EVENT GIT_TRACE2_PERF GIT_TRACE_SETUP GIT_TRACE_PACKET \ + GIT_TRACE_PERFORMANCE export GIT_AUTHOR_NAME=t GIT_AUTHOR_EMAIL=t@example.test GIT_COMMITTER_NAME=t GIT_COMMITTER_EMAIL=t@example.test MARK='<!-- idd:comment type=implementation-complete -->' @@ -49,15 +70,29 @@ run() { # subcommand args... → OUT, RC, LINES (stdout lines) comment() { # name body — write a comment file, print its path printf '%s\n' "$2" > "$WORK/$1.md"; printf '%s' "$WORK/$1.md" } +MAIN_PID=$$ +trap 'exit 1' TERM +setup_failed() { # what — a fixture step failed: say so before the suite ends without its summary + echo "FATAL: spec-change suite: fixture setup failed: $1" >&2 + # Inside $(...) an exit ends only the subshell (X=$(commit) would go on with an empty X): stop the suite too. + [ "${BASH_SUBSHELL:-0}" -eq 0 ] || kill -TERM "$MAIN_PID" 2>/dev/null + exit 1 +} newrepo() { # name → REPO (an empty git repo with one empty commit) - REPO="$WORK/$1"; mkdir -p "$REPO" - git -C "$REPO" init -q -b main - git -C "$REPO" commit -q --allow-empty -m init + REPO="$WORK/$1" + mkdir -p "$REPO" || setup_failed "create repository directory" + git -C "$REPO" init -q -b main || setup_failed "initialize repository" + git -C "$REPO" commit -q --allow-empty -m init || setup_failed "commit empty repository" } put() { # path [content] — write a file into $REPO - mkdir -p "$(dirname "$REPO/$1")"; printf '%s\n' "${2:-x}" > "$REPO/$1" + mkdir -p "$(dirname "$REPO/$1")" || setup_failed "create fixture file parent" + printf '%s\n' "${2:-x}" > "$REPO/$1" || setup_failed "write fixture file" +} +commit() { + git -C "$REPO" add -A || setup_failed "stage fixture" + git -C "$REPO" commit -q -m "${1:-c}" || setup_failed "commit fixture" + git -C "$REPO" rev-parse HEAD || setup_failed "read fixture commit" } -commit() { git -C "$REPO" add -A && git -C "$REPO" commit -q -m "${1:-c}"; git -C "$REPO" rev-parse HEAD; } # ── declared ──────────────────────────────────────────────────────────────── echo "spec-change: declared (Example: reading the Spec line)" @@ -186,7 +221,9 @@ links_case() { # label status missing-count exit assert_eq "links: $1 — one JSON line" 1 "$LINES" } linked_repo() { # name — a repo whose base has spec `cap` with requirement Base (no Example); sets BASE - newrepo "$1"; put openspec/specs/cap/spec.md "$(spec "$(req Base)")"; BASE=$(commit base) + newrepo "$1" || setup_failed "create linked repository" + put openspec/specs/cap/spec.md "$(spec "$(req Base)")" || setup_failed "write base spec" + BASE=$(commit base) || setup_failed "commit base spec" } EX='##### Example: alpha table' linked_repo l-ok; put openspec/specs/cap/spec.md "$(spec "$(req Base)" "$(req Alpha "$EX")")"; put scripts/tests/x/test.sh '# spec-example: cap / alpha table'; commit >/dev/null @@ -292,6 +329,897 @@ links_case "openspec/specs/ holds no tracked file at the head revision" error "" newrepo l-gitkeep; put openspec/specs/.gitkeep ''; BASE=$(commit base); put README.txt x; commit >/dev/null links_case "openspec/specs/ holds only .gitkeep (a newly initialised repository)" ok 0 0 +# A path that is not valid UTF-8 under the spec directory but outside specs/ does not change the answer. +linked_repo l-changes-invalid-utf8 || setup_failed "create invalid-UTF-8 changes fixture" +put openspec/specs/cap/spec.md "$(spec "$(req Base)" "$(req Alpha "$EX")")" || setup_failed "write Example for the changes fixture" +put scripts/tests/x/test.sh '# spec-example: cap / alpha table' || setup_failed "write marker for the changes fixture" +git -C "$REPO" add -A || setup_failed "stage the changes fixture" +OTHER_BLOB=$(git -C "$REPO" hash-object -w "$REPO/scripts/tests/x/test.sh") || setup_failed "store a blob for the changes fixture" +OTHER_PATH=$(printf 'openspec/changes/x\377/notes.txt') || setup_failed "build invalid-UTF-8 changes path" +git -C "$REPO" update-index --add --cacheinfo "100644,$OTHER_BLOB,$OTHER_PATH" || setup_failed "record invalid-UTF-8 changes path" +git -C "$REPO" commit -q -m example || setup_failed "commit the changes fixture" +git -C "$REPO" ls-tree -r --name-only HEAD | LC_ALL=C grep -q "$(printf 'changes/x\\\\377')" || setup_failed "the invalid-UTF-8 changes path is not in the head revision" +links_case "added, a path under openspec/changes/ is not valid UTF-8" ok 0 0 + +linked_repo l-spec-invalid-utf8 || setup_failed "create invalid-UTF-8 spec fixture" +spec "$(req Alpha)" > "$WORK/invalid-utf8-spec.md" || setup_failed "write new capability spec" +SPEC_BLOB=$(git -C "$REPO" hash-object -w "$WORK/invalid-utf8-spec.md") || setup_failed "store spec blob" +SPEC_PATH=$(printf 'openspec/specs/cap\377/spec.md') || setup_failed "build invalid-UTF-8 spec path" +git -C "$REPO" update-index --add --cacheinfo "100644,$SPEC_BLOB,$SPEC_PATH" || setup_failed "record invalid-UTF-8 spec path" +git -C "$REPO" commit -q -m invalid-utf8-spec || setup_failed "commit invalid-UTF-8 spec" +links_case "a path under the spec directory is not valid UTF-8" error 0 2 +assert_eq "links: invalid-UTF-8 spec path — fixed reason" 'a path under the spec directory is not valid UTF-8' "$(printf '%s' "$OUT" | field reason)" +refute_output_grep "links: invalid-UTF-8 spec path — no traceback" Traceback "$WORK/err" + +# Added before archiving (tasks 4.1): the main repository's failed search keeps git's message, as before: +# `git grep failed: ` and the first 200 characters of what git wrote to its error stream. +linked_repo l-main-tree-unreadable || setup_failed "create unreadable-tree fixture" +put openspec/specs/cap/spec.md "$(spec "$(req Base)" "$(req Alpha "$EX")")" || setup_failed "write Example" +put src/x.txt 'content' || setup_failed "write a file outside the spec directory" +commit >/dev/null || setup_failed "commit unreadable-tree fixture" +SRC_TREE=$(git -C "$REPO" rev-parse 'HEAD:src') || setup_failed "read the tree to remove" +[ -f "$REPO/.git/objects/${SRC_TREE:0:2}/${SRC_TREE:2}" ] || setup_failed "the tree to remove is not a loose object" +rm "$REPO/.git/objects/${SRC_TREE:0:2}/${SRC_TREE:2}" || setup_failed "remove the tree" +links_case "the main repository: a tree outside the spec directory cannot be read" error 0 2 +GIT_SAID=$(git -C "$REPO" grep --no-recurse-submodules -z -F -e 'spec-example: cap / alpha table' "$(git -C "$REPO" rev-parse HEAD)" -- . 2>&1 >/dev/null) +[ -n "$GIT_SAID" ] || setup_failed "git wrote nothing about the tree it cannot read" +[ "${#GIT_SAID}" -le 200 ] || setup_failed "git's message about the tree is longer than 200 characters" +assert_eq "links: unreadable main tree — the reason is what git wrote" "git grep failed: $GIT_SAID" "$(printf '%s' "$OUT" | field reason)" +# A message longer than 200 characters, with a known text: a git whose search fails with 300 characters in +# which every group of four is distinct, so the first 200 cannot be mistaken for the last 200. +mkdir -p "$WORK/gitlong-bin" || setup_failed "create long-message git directory" +cat > "$WORK/gitlong-bin/git" <<'EOF' || setup_failed "write long-message git" +#!/bin/sh +for a in "$@"; do + if [ "$a" = grep ]; then printf '%s' "$TEST_GIT_GREP_MESSAGE" >&2; exit 128; fi +done +exec "$REAL_GIT" "$@" +EOF +chmod u+x "$WORK/gitlong-bin/git" || setup_failed "make long-message git executable" +LONG_MESSAGE=$("$PY" -c 'print("".join("%03d|" % i for i in range(75)), end="")') || setup_failed "build the long message" +[ "${#LONG_MESSAGE}" -eq 300 ] || setup_failed "the long message must have 300 characters" +REAL_GIT="$GIT" TEST_GIT_GREP_MESSAGE="$LONG_MESSAGE" PATH="$WORK/gitlong-bin:$PATH" run links --cwd "$REPO" --base "$BASE" +assert_eq "links: unreadable main tree — a longer message is cut to its first 200 characters" \ + "git grep failed: ${LONG_MESSAGE:0:200}" "$(printf '%s' "$OUT" | field reason)" +assert_exit "links: unreadable main tree — exit with the longer message" 2 "$RC" + +# ── links: markers in submodules ──────────────────────────────────────────── +echo "spec-change: links (Example: markers in submodules)" + +submodule_repo() { # name source path — add one Example and a local submodule; sets REPO and BASE + linked_repo "$1" || setup_failed "create submodule repository" + put openspec/specs/cap/spec.md "$(spec "$(req Base)" "$(req Alpha "$EX")")" || setup_failed "write submodule Example" + git -C "$REPO" -c protocol.file.allow=always submodule add -q "$2" "$3" || setup_failed "submodule add $3" + git -C "$REPO" add -A || setup_failed "stage submodule Example" + git -C "$REPO" commit -q -m example || setup_failed "commit submodule Example" +} +newrepo l-sub-source; put scripts/test.sh '# spec-example: cap / alpha table'; commit >/dev/null; SUB="$REPO" +newrepo l-sub-empty-source; put scripts/test.sh '# no marker'; commit >/dev/null; EMPTY_SUB="$REPO" +newrepo l-sub-md-source; put notes.md '# spec-example: cap / alpha table'; commit >/dev/null; MD_SUB="$REPO" + +submodule_repo l-sub-tracked "$SUB" tests/sub +links_case "submodule row 1: tracked marker at the recorded commit" ok 0 0 + +newrepo l-sub-nested-source +git -C "$REPO" -c protocol.file.allow=always submodule add -q "$SUB" inner || setup_failed "submodule add inner" +commit >/dev/null; NESTED_SUB="$REPO" +submodule_repo l-sub-nested "$NESTED_SUB" tests/sub +git -C "$REPO" -c protocol.file.allow=always submodule update -q --init --recursive || setup_failed "submodule update --recursive" +links_case "submodule row 2: marker in a nested submodule" ok 0 0 + +submodule_repo l-sub-space "$SUB" 'tests/sub module' +links_case "submodule row 3: path with a space" ok 0 0 + +submodule_repo l-sub-earlier "$SUB" tests/sub +printf '# no marker\n' > "$REPO/tests/sub/scripts/test.sh" +git -C "$REPO/tests/sub" add -A || setup_failed "stage removed marker" +git -C "$REPO/tests/sub" commit -q -m remove-marker || setup_failed "commit removed marker" +RECORDED=$(git -C "$REPO" rev-parse HEAD:tests/sub) || setup_failed "read recorded commit" +CHECKED_OUT=$(git -C "$REPO/tests/sub" rev-parse HEAD) || setup_failed "read working-tree commit" +refute "links: submodule row 4 — working tree is on another commit" test "$RECORDED" = "$CHECKED_OUT" +links_case "submodule row 4: marker only at the recorded commit" ok 0 0 + +submodule_repo l-sub-later "$EMPTY_SUB" tests/sub +printf '# spec-example: cap / alpha table\n' > "$REPO/tests/sub/scripts/test.sh" +git -C "$REPO/tests/sub" add -A || setup_failed "stage added marker" +git -C "$REPO/tests/sub" commit -q -m add-marker || setup_failed "commit added marker" +RECORDED=$(git -C "$REPO" rev-parse HEAD:tests/sub) || setup_failed "read recorded commit" +CHECKED_OUT=$(git -C "$REPO/tests/sub" rev-parse HEAD) || setup_failed "read working-tree commit" +refute "links: submodule row 5 — working tree is on another commit" test "$RECORDED" = "$CHECKED_OUT" +links_case "submodule row 5: marker only at the later working-tree commit" missing 1 1 +assert_eq "links: submodule row 5 — why unchanged" 'no tracked file outside openspec/ (and not .md) carries its marker' "$(printf '%s' "$OUT" | "$PY" -c 'import json,sys; m=json.load(sys.stdin)["missing"]; print(m[0]["why"] if m else "")')" + +submodule_repo l-sub-md "$MD_SUB" tests/sub +links_case "submodule row 6: marker only in a .md file" missing 1 1 + +submodule_repo l-sub-nowhere "$EMPTY_SUB" tests/sub +links_case "submodule row 7: no marker, submodule checked out" missing 1 1 + +submodule_repo l-sub-deinit "$SUB" tests/sub +git -C "$REPO" submodule deinit -q -f -- tests/sub || setup_failed "submodule deinit" +links_case "submodule row 8: marker in a submodule not checked out" error 0 2 +assert_eq "links: submodule row 8 — reason names Example and path" "cannot decide whether the Example 'cap / alpha table' has a marker: submodule tests/sub: not checked out" "$(printf '%s' "$OUT" | field reason)" + +submodule_repo l-sub-main "$SUB" tests/sub +put scripts/test.sh '# spec-example: cap / alpha table'; commit >/dev/null +git -C "$REPO" submodule deinit -q -f -- tests/sub || setup_failed "submodule deinit" +links_case "submodule row 9: main marker, submodule not checked out" ok 0 0 + +submodule_repo l-sub-missing-commit "$EMPTY_SUB" tests/sub +git -C "$REPO" update-index --cacheinfo 160000,1111111111111111111111111111111111111111,tests/sub || setup_failed "update-index of a commit that does not exist" +# Do not add the working tree: keep the missing commit recorded in the index. +git -C "$REPO" commit -q -m missing-submodule-commit || setup_failed "commit of the missing pointer" +links_case "submodule row 10: recorded commit absent from the object store" error 0 2 +assert_eq "links: submodule row 10 — reason names Example and path" "cannot decide whether the Example 'cap / alpha table' has a marker: submodule tests/sub: recorded commit 111111111111 is not in its object store" "$(printf '%s' "$OUT" | field reason)" + +# Rows 11 and 12: the user's git configuration turns git's own recursion on. links must answer as in rows 9 and 10. +missing_commit_repo() { # name — a checked-out submodule whose recorded commit its object store lacks + submodule_repo "$1" "$EMPTY_SUB" tests/sub + git -C "$REPO" update-index --cacheinfo 160000,1111111111111111111111111111111111111111,tests/sub || setup_failed "update-index of a commit that does not exist" + git -C "$REPO" commit -q -m missing-submodule-commit || setup_failed "commit of the missing pointer" +} +missing_commit_repo l-sub-recurse-main +put scripts/test.sh '# spec-example: cap / alpha table' || setup_failed "write main marker" +git -C "$REPO" add scripts/test.sh || setup_failed "stage main marker" +git -C "$REPO" commit -q -m main-marker || setup_failed "commit of the main marker" +git -C "$REPO" config submodule.recurse true || setup_failed "enable submodule recursion" +RECURSE=$(git -C "$REPO" config --get submodule.recurse) || setup_failed "read submodule recursion" +assert_eq "links: submodule row 11 — recursion is enabled" true "$RECURSE" +links_case "submodule row 11: main marker, recorded commit absent, submodule.recurse on" ok 0 0 + +missing_commit_repo l-sub-recurse-missing +git -C "$REPO" config submodule.recurse true || setup_failed "enable submodule recursion" +RECURSE=$(git -C "$REPO" config --get submodule.recurse) || setup_failed "read submodule recursion" +assert_eq "links: submodule row 12 — recursion is enabled" true "$RECURSE" +links_case "submodule row 12: recorded commit absent, submodule.recurse on" error 0 2 +assert_eq "links: submodule row 12 — reason names Example and path" "cannot decide whether the Example 'cap / alpha table' has a marker: submodule tests/sub: recorded commit 111111111111 is not in its object store" "$(printf '%s' "$OUT" | field reason)" + +submodule_repo l-sub-two "$SUB" tests/a +git -C "$REPO" -c protocol.file.allow=always submodule add -q "$SUB" tests/b || setup_failed "submodule add tests/b" +commit >/dev/null +git -C "$REPO" submodule deinit -q -f -- tests/a tests/b || setup_failed "submodule deinit of two" +links_case "submodule row 13: two submodules, neither checked out" error 0 2 +assert_eq "links: submodule row 13 — both paths, joined" "cannot decide whether the Example 'cap / alpha table' has a marker: submodule tests/a: not checked out; submodule tests/b: not checked out" "$(printf '%s' "$OUT" | field reason)" + +submodule_repo l-sub-inner-out "$NESTED_SUB" tests/sub # the outer one is checked out, its own submodule is not +links_case "submodule row 14: marker only in a nested submodule that is not checked out" error 0 2 +assert_eq "links: submodule row 14 — reason names the inner path under the outer one" "cannot decide whether the Example 'cap / alpha table' has a marker: submodule tests/sub/inner: not checked out" "$(printf '%s' "$OUT" | field reason)" + +submodule_repo l-sub-under-spec "$SUB" openspec/vendor/sub +links_case "submodule row 15: marker only in a submodule mounted under the spec directory" missing 1 1 + +# Keep the head tree separate from the checkout: some rows deliberately make them disagree. +example_repo() { # name — the Example, without a marker or submodule + linked_repo "$1" || setup_failed "create Example repository" + put openspec/specs/cap/spec.md "$(spec "$(req Base)" "$(req Alpha "$EX")")" || setup_failed "write Example" + git -C "$REPO" add -A || setup_failed "stage Example" + git -C "$REPO" commit -q -m example || setup_failed "commit Example" +} +record_gitlink() { # path commit — do not stage the working tree + git -C "$REPO" update-index --add --cacheinfo "160000,$2,$1" || setup_failed "record gitlink" + git -C "$REPO" commit -q -m gitlink || setup_failed "commit gitlink" +} +main_marker() { + put scripts/test.sh '# spec-example: cap / alpha table' || setup_failed "write main marker" + git -C "$REPO" add scripts/test.sh || setup_failed "stage main marker" + git -C "$REPO" commit -q -m main-marker || setup_failed "commit main marker" +} +submodule_reason() { # row path reason + assert_eq "links: submodule row $1 — reason names Example and path" \ + "cannot decide whether the Example 'cap / alpha table' has a marker: submodule $2: $3" \ + "$(printf '%s' "$OUT" | field reason)" +} +remove_submodule_object() { # revision expression — unpack first if the clone has packs + local oid objects pack saved + oid=$(git -C "$REPO/tests/sub" rev-parse "$1") || setup_failed "resolve object to remove" + objects=$(git -C "$REPO/tests/sub" rev-parse --absolute-git-dir) || setup_failed "locate submodule object store" + objects="$objects/objects" + for pack in "$objects"/pack/*.pack; do + [ -f "$pack" ] || continue + saved="$WORK/$(basename "$REPO")-$(basename "$pack")" + mv "$pack" "$saved" || setup_failed "move pack before unpacking" + git -C "$REPO/tests/sub" unpack-objects < "$saved" || setup_failed "unpack submodule objects" + rm "${pack%.pack}.idx" || setup_failed "remove pack index" + done + [ -f "$objects/${oid:0:2}/${oid:2}" ] || setup_failed "object to remove is not loose" + rm "$objects/${oid:0:2}/${oid:2}" || setup_failed "remove submodule object" + git -C "$REPO/tests/sub" cat-file -e 'HEAD^{commit}' || setup_failed "recorded commit must remain" +} +planted_directory() { # directory canary — ordinary files that look like a git directory + mkdir -p "$1/objects" "$1/refs/heads" || setup_failed "create planted directories" + printf 'ref: refs/heads/main\n' > "$1/HEAD" || setup_failed "write planted HEAD" + touch "$1/objects/.keep" "$1/refs/heads/.keep" || setup_failed "write planted placeholders" + cat > "$1/config" <<EOF || setup_failed "write planted config" +[core] + repositoryformatversion = 1 + bare = false + worktree = . + sshCommand = touch '$2'; false +[extensions] + partialClone = origin +[remote "origin"] + url = ssh://example.invalid/repository + promisor = true +EOF +} +MISSING_COMMIT=1111111111111111111111111111111111111111 + +example_repo l-sub-bytes-main +main_marker +record_gitlink "$(printf 'vendor/lib\377')" "$MISSING_COMMIT" +links_case "submodule row 16: main marker, non-UTF-8 gitlink" ok 0 0 +refute_output_grep "links: submodule row 16 — no traceback" Traceback "$WORK/err" + +example_repo l-sub-bytes-missing +record_gitlink "$(printf 'vendor/lib\377')" "$MISSING_COMMIT" +links_case "submodule row 17: no marker, non-UTF-8 gitlink" error 0 2 +submodule_reason 17 'vendor/lib�' 'not checked out' +refute_output_grep "links: submodule row 17 — no traceback" Traceback "$WORK/err" + +submodule_repo l-sub-tree-main "$EMPTY_SUB" tests/sub || setup_failed "create missing-tree fixture" +main_marker +remove_submodule_object 'HEAD^{tree}' +links_case "submodule row 18: main marker, submodule tree absent" ok 0 0 + +submodule_repo l-sub-tree-missing "$EMPTY_SUB" tests/sub || setup_failed "create missing-tree fixture" +remove_submodule_object 'HEAD^{tree}' +links_case "submodule row 19: no marker, submodule tree absent" error 0 2 +submodule_reason 19 tests/sub 'its recorded commit could not be read' +refute_grep "links: submodule row 19 — no temporary directory in reason" "$WORK" "$(printf '%s' "$OUT" | field reason)" +refute_grep "links: submodule row 19 — no git error in reason" fatal "$(printf '%s' "$OUT" | field reason)" + +submodule_repo l-sub-blob-missing "$EMPTY_SUB" tests/sub || setup_failed "create missing-blob fixture" +remove_submodule_object HEAD:scripts/test.sh +git -C "$REPO/tests/sub" cat-file -e 'HEAD^{tree}' || setup_failed "recorded tree must remain" +links_case "submodule row 20: no marker, submodule blob absent" error 0 2 +submodule_reason 20 tests/sub 'its recorded commit could not be read' +refute_grep "links: submodule row 20 — no temporary directory in reason" "$WORK" "$(printf '%s' "$OUT" | field reason)" +refute_grep "links: submodule row 20 — no git error in reason" fatal "$(printf '%s' "$OUT" | field reason)" + +submodule_repo l-sub-planted "$EMPTY_SUB" tests/sub || setup_failed "create planted fixture" +git -C "$REPO/tests/sub" update-index --add --cacheinfo "160000,$MISSING_COMMIT,emb" || setup_failed "record nested gitlink" +git -C "$REPO/tests/sub" commit -q -m nested-gitlink || setup_failed "commit nested gitlink" +RECORDED=$(git -C "$REPO/tests/sub" rev-parse HEAD) || setup_failed "read nested-gitlink commit" +record_gitlink tests/sub "$RECORDED" +git -C "$REPO/tests/sub" update-index --force-remove emb || setup_failed "remove nested gitlink from later index" +CANARY="$WORK/nested-canary" +planted_directory "$REPO/tests/sub/emb" "$CANARY" +git -C "$REPO/tests/sub" add emb/HEAD emb/config emb/objects/.keep emb/refs/heads/.keep || setup_failed "stage planted files" +git -C "$REPO/tests/sub" commit -q -m ordinary-files || setup_failed "commit planted files" +links_case "submodule row 21: nested planted directory" error 0 2 +submodule_reason 21 tests/sub/emb 'not checked out' +assert_file_absent "links: submodule row 21 — planted command did not run" "$CANARY" + +rm -f "$CANARY" || setup_failed "clear canary before main-marker check" +main_marker +links_case "submodule row 22: main marker, nested planted directory" ok 0 0 +assert_file_absent "links: submodule row 22 — planted command did not run" "$CANARY" +# Row 22 once more with every git call logged. The marker is in the main repository, so no git command may run +# in a submodule's directory; the planted command staying silent would not show that on its own. +mkdir -p "$WORK/gitlog-bin" || setup_failed "create logging git directory" +printf '#!/bin/sh\nprintf "%%s\\n" "$*" >> "$GIT_CALL_LOG"\nexec "$REAL_GIT" "$@"\n' > "$WORK/gitlog-bin/git" || setup_failed "write logging git" +chmod u+x "$WORK/gitlog-bin/git" || setup_failed "make logging git executable" +: > "$WORK/git-calls.log" || setup_failed "clear git call log" +GIT_CALL_LOG="$WORK/git-calls.log" REAL_GIT="$GIT" PATH="$WORK/gitlog-bin:$PATH" links_case "submodule row 22: main marker, git calls logged" ok 0 0 +assert_grep "links: submodule row 22 — the logging git saw the main repository" "-C $REPO rev-parse" "$(cat "$WORK/git-calls.log")" +refute_grep "links: submodule row 22 — no git command ran in a submodule" "$(basename "$REPO")/tests/sub" "$(cat "$WORK/git-calls.log")" +refute_grep_re "links: submodule row 22 — no gitlinks were listed" 'ls-tree -r -z [0-9a-f]{40}$' "$(cat "$WORK/git-calls.log")" +submodule_repo l-sub-log-control "$SUB" tests/sub || setup_failed "create logging control" +: > "$WORK/git-calls.log" || setup_failed "clear git call log for control" +GIT_CALL_LOG="$WORK/git-calls.log" REAL_GIT="$GIT" PATH="$WORK/gitlog-bin:$PATH" links_case "submodule row 22: submodule marker, logging control" ok 0 0 +assert_grep_re "links: submodule row 22 — control lists gitlinks" 'ls-tree -r -z [0-9a-f]{40}$' "$(cat "$WORK/git-calls.log")" + +example_repo l-sub-dotdot +git clone -q "$SUB" "$WORK/outside" || setup_failed "clone outside repository" +RECORDED=$(git -C "$WORK/outside" rev-parse HEAD) || setup_failed "read outside commit" +OUTSIDE_TREE=$(printf '160000 commit %s\toutside\n' "$RECORDED" | git -C "$REPO" mktree) || setup_failed "build outside tree" +git -C "$REPO" ls-tree HEAD > "$WORK/root-tree" || setup_failed "read root tree" +printf '040000 tree %s\t..\n' "$OUTSIDE_TREE" >> "$WORK/root-tree" || setup_failed "append parent component" +ROOT_TREE=$(git -C "$REPO" mktree < "$WORK/root-tree") || setup_failed "build parent-component tree" +ROOT_COMMIT=$(git -C "$REPO" commit-tree "$ROOT_TREE" -p HEAD -m parent-component) || setup_failed "commit parent-component tree" +git -C "$REPO" update-ref HEAD "$ROOT_COMMIT" || setup_failed "select parent-component tree" +links_case "submodule row 23: parent component, outside repository present" error 0 2 +submodule_reason 23 ../outside 'path leaves the repository' +FIRST_OUT="$OUT"; FIRST_RC="$RC" +rm -rf "$WORK/outside" || setup_failed "remove outside repository" +links_case "submodule row 23: parent component, outside repository absent" error 0 2 +submodule_reason 23 ../outside 'path leaves the repository' +assert_eq "links: submodule row 23 — identical JSON whether outside exists" "$FIRST_OUT" "$OUT" +assert_exit "links: submodule row 23 — identical exit whether outside exists" "$FIRST_RC" "$RC" + +example_repo l-sub-outside-symlink +mkdir -p "$WORK/outside-area" || setup_failed "create outside area" +git clone -q "$SUB" "$WORK/outside-area/outside" || setup_failed "clone outside repository" +RECORDED=$(git -C "$WORK/outside-area/outside" rev-parse HEAD) || setup_failed "read outside commit" +# Record the path before placing the symlink: update-index rejects a path through one. +record_gitlink lnk/outside "$RECORDED" +ln -s "$WORK/outside-area" "$REPO/lnk" || setup_failed "link outside area" +links_case "submodule row 24: parent symlink leaves working tree" error 0 2 +submodule_reason 24 lnk/outside 'path leaves the repository' + +submodule_repo l-sub-trailing-space "$SUB" 'tests/sub ' || setup_failed "create trailing-space fixture" +links_case "submodule row 25: path ends in a space" ok 0 0 + +submodule_repo l-sub-spec-unchecked "$EMPTY_SUB" openspec/vendor/sub || setup_failed "create excluded fixture" +git -C "$REPO" submodule deinit -q -f -- openspec/vendor/sub || setup_failed "deinit excluded submodule" +links_case "submodule row 26: unchecked submodule under spec directory" missing 1 1 + +submodule_repo l-sub-inner-symlink "$SUB" tests/sub || setup_failed "create inner-symlink fixture" +mkdir -p "$REPO/elsewhere" || setup_failed "create alternate checkout parent" +git clone -q "$SUB" "$REPO/elsewhere/sub" || setup_failed "clone alternate checkout" +rm -rf "$REPO/tests/sub" || setup_failed "remove original checkout" +ln -s ../elsewhere/sub "$REPO/tests/sub" || setup_failed "link alternate checkout" +links_case "submodule row 27: submodule directory is a symlink inside working tree" error 0 2 +submodule_reason 27 tests/sub 'not checked out' + +submodule_repo l-sub-git-dir "$SUB" tests/sub || setup_failed "create inherited-GIT_DIR fixture" +GIT_DIR="$REPO/.git" links_case "submodule row 28: inherited GIT_DIR names main repository" ok 0 0 + +# Row 29: the marker is in the recorded commit of each of seven submodules, and none of them is checked out. +submodule_repo l-sub-seven "$SUB" m1 || setup_failed "create row 29" +for n in 2 3 4 5 6 7; do + git -C "$REPO" -c protocol.file.allow=always submodule add -q "$SUB" "m$n" || setup_failed "submodule add m$n" +done +commit >/dev/null || setup_failed "commit seven submodules" +for n in 1 2 3 4 5 6 7; do + [ "$(git -C "$REPO" rev-parse "HEAD:m$n")" = "$(git -C "$REPO/m$n" rev-parse HEAD)" ] || setup_failed "row 29: m$n must be at its recorded commit" + git -C "$REPO/m$n" grep -q -F -e 'spec-example: cap / alpha table' HEAD -- . || setup_failed "row 29: the recorded commit of m$n must hold the marker" +done +git -C "$REPO" submodule deinit -q -f -- m1 m2 m3 m4 m5 m6 m7 || setup_failed "submodule deinit of seven" +links_case "submodule row 29: seven unchecked submodules" error 0 2 +assert_eq "links: submodule row 29 — sorted first five and remainder" \ + "cannot decide whether the Example 'cap / alpha table' has a marker: submodule m1: not checked out; submodule m2: not checked out; submodule m3: not checked out; submodule m4: not checked out; submodule m5: not checked out; and 2 more" \ + "$(printf '%s' "$OUT" | field reason)" +refute_grep "links: submodule row 29 — no sixth path" m6 "$(printf '%s' "$OUT" | field reason)" +refute_grep "links: submodule row 29 — no seventh path" m7 "$(printf '%s' "$OUT" | field reason)" + +submodule_repo l-sub-bad-gitfile "$EMPTY_SUB" tests/sub || setup_failed "create bad-gitfile fixture" +printf 'gitdir: %s\n' "$WORK/absent-git-dir" > "$REPO/tests/sub/.git" || setup_failed "write bad gitfile" +links_case "submodule row 30: gitfile names an absent directory" error 0 2 +submodule_reason 30 tests/sub 'git refused to open it' + +example_repo l-sub-empty-gitdir +record_gitlink tests/sub "$MISSING_COMMIT" +CANARY="$WORK/empty-gitdir-canary" +planted_directory "$REPO/tests/sub" "$CANARY" +mkdir "$REPO/tests/sub/.git" || setup_failed "create empty git directory" +links_case "submodule row 31: planted directory beside an empty .git" error 0 2 +submodule_reason 31 tests/sub 'git refused to open it' +assert_file_absent "links: submodule row 31 — planted command did not run" "$CANARY" + +blob_present() { # repository blob — is the object in the local object store? Lists what is there; never fetches. + git -C "$1" cat-file --batch-all-objects --batch-check 2>/dev/null | grep -q "^$2 " +} +partial_submodule_repo() { # name — no checkout, with commits and trees but no blob + example_repo "$1" + git -C "$EMPTY_SUB" config uploadpack.allowFilter true || setup_failed "allow clone filter" + mkdir -p "$REPO/tests" || setup_failed "create partial clone parent" + git -c protocol.file.allow=always clone -q --no-checkout --filter=blob:none "file://$EMPTY_SUB" "$REPO/tests/sub" || setup_failed "make partial clone" + RECORDED=$(git -C "$EMPTY_SUB" rev-parse HEAD) || setup_failed "read source commit" + BLOB=$(git -C "$EMPTY_SUB" rev-parse HEAD:scripts/test.sh) || setup_failed "read source blob" + record_gitlink tests/sub "$RECORDED" + git -C "$REPO/tests/sub" cat-file -e "$RECORDED^{tree}" || setup_failed "partial clone must hold tree" + if blob_present "$REPO/tests/sub" "$BLOB"; then + setup_failed "partial clone unexpectedly holds blob" + fi +} +partial_submodule_repo l-sub-partial-main +main_marker +links_case "submodule row 32: main marker, partial submodule" ok 0 0 +refute "links: submodule row 32 — blob was not fetched" blob_present "$REPO/tests/sub" "$BLOB" + +partial_submodule_repo l-sub-partial-missing +links_case "submodule row 33: no marker, partial submodule" error 0 2 +submodule_reason 33 tests/sub 'its recorded commit could not be read' +refute "links: submodule row 33 — blob was not fetched" blob_present "$REPO/tests/sub" "$BLOB" + +example_repo l-sub-long-path +LONG_PATH=$("$PY" -c 'print("a" * 100 + "/" + "b" * 100 + "/c")') || setup_failed "build long path" +record_gitlink "$LONG_PATH" "$MISSING_COMMIT" +links_case "submodule row 34: unchecked submodule with a long path" error 0 2 +submodule_reason 34 "${LONG_PATH:0:200}..." 'not checked out' +refute_grep "links: submodule row 34 — no full path" "$LONG_PATH" "$(printf '%s' "$OUT" | field reason)" + +submodule_repo l-sub-found-and-unchecked "$SUB" tests/a || setup_failed "create two-submodule fixture" +record_gitlink tests/b "$MISSING_COMMIT" +links_case "submodule row 35: found marker settles Example despite unchecked sibling" ok 0 0 + +# Rows 36 to 41 were added after the change was checked before archiving (tasks 4.1). +newrepo l-sub-md-and-code-source; put notes.md '# spec-example: cap / alpha table'; put scripts/test.sh '# no marker here'; commit >/dev/null; MD_CODE_SUB="$REPO" +submodule_repo l-sub-md-match-blob-missing "$MD_CODE_SUB" tests/sub || setup_failed "create md-match fixture" +remove_submodule_object HEAD:scripts/test.sh +git -C "$REPO/tests/sub" cat-file -e HEAD:notes.md || setup_failed "the .md file with the marker must remain readable" +links_case "submodule row 36: marker only in a .md file, another blob absent" error 0 2 +submodule_reason 36 tests/sub 'its recorded commit could not be read' + +submodule_repo l-sub-top-elsewhere "$SUB" tests/sub || setup_failed "create other-top fixture" +git -C "$REPO/tests/sub" config core.worktree "$REPO/tests" || setup_failed "point the submodule's working tree at its parent directory" +REPORTED_TOP=$(git -C "$REPO/tests/sub" rev-parse --show-toplevel) || setup_failed "git must still open the submodule" +refute "links: submodule row 37 — git names another directory as the top" test "$(cd "$REPORTED_TOP" && pwd -P)" = "$(cd "$REPO/tests/sub" && pwd -P)" +links_case "submodule row 37: git names another directory as the top" error 0 2 +submodule_reason 37 tests/sub 'not checked out' + +submodule_repo l-sub-path-order "$NESTED_SUB" a || setup_failed "create path-order fixture" # a is checked out, a/inner is not +record_gitlink a-b "$MISSING_COMMIT" +# The walk meets a/inner (inside a) before a-b; the reason names them in the order of their paths, a-b first. +links_case "submodule row 38: two unsearchable submodules, path order" error 0 2 +assert_eq "links: submodule row 38 — named in the order of their paths" \ + "cannot decide whether the Example 'cap / alpha table' has a marker: submodule a-b: not checked out; submodule a/inner: not checked out" \ + "$(printf '%s' "$OUT" | field reason)" + +example_repo l-sub-dot +INSIDE_TREE=$(printf '160000 commit %s\tinside\n' "$MISSING_COMMIT" | git -C "$REPO" mktree) || setup_failed "build tree under the dot component" +git -C "$REPO" ls-tree HEAD > "$WORK/dot-root-tree" || setup_failed "read root tree" +printf '040000 tree %s\t.\n' "$INSIDE_TREE" >> "$WORK/dot-root-tree" || setup_failed "append dot component" +DOT_TREE=$(git -C "$REPO" mktree < "$WORK/dot-root-tree") || setup_failed "build dot-component tree" +DOT_COMMIT=$(git -C "$REPO" commit-tree "$DOT_TREE" -p HEAD -m dot-component) || setup_failed "commit dot-component tree" +git -C "$REPO" update-ref HEAD "$DOT_COMMIT" || setup_failed "select dot-component tree" +links_case "submodule row 39: a '.' component in a recorded path" error 0 2 +submodule_reason 39 ./inside 'path leaves the repository' + +submodule_repo l-sub-git-env "$SUB" tests/sub || setup_failed "create inherited-environment fixture" +GIT_DIR="$REPO/.git" GIT_WORK_TREE="$REPO" GIT_INDEX_FILE="$REPO/.git/index" GIT_OBJECT_DIRECTORY="$REPO/.git/objects" \ + GIT_ALTERNATE_OBJECT_DIRECTORIES="$REPO/.git/objects" GIT_COMMON_DIR="$REPO/.git" \ + links_case "submodule row 40: six inherited git variables name the main repository" ok 0 0 + +submodule_repo l-sub-alternates "$EMPTY_SUB" tests/sub || setup_failed "create inherited-alternates fixture" +SUB_COMMIT=$(git -C "$SUB" rev-parse HEAD) || setup_failed "read the commit that holds the marker" +record_gitlink tests/sub "$SUB_COMMIT" # a commit that this checkout's object store does not hold +if git -C "$REPO/tests/sub" cat-file -e "$SUB_COMMIT^{commit}" 2>/dev/null; then setup_failed "the checkout unexpectedly holds the recorded commit"; fi +GIT_ALTERNATE_OBJECT_DIRECTORIES="$SUB/.git/objects" git -C "$REPO/tests/sub" cat-file -e "$SUB_COMMIT^{commit}" || setup_failed "the inherited object store must hold the recorded commit" +GIT_ALTERNATE_OBJECT_DIRECTORIES="$SUB/.git/objects" links_case "submodule row 41: an inherited object store holds the recorded commit" error 0 2 +submodule_reason 41 tests/sub "recorded commit ${SUB_COMMIT:0:12} is not in its object store" + +# Rows 42 and 43: an unreadable outer blob does not hide a complete inner checkout. +nested_missing_blob_repo() { # name inner-source + newrepo "$1-source" || setup_failed "create outer source" + put README 'unrelated outer content' || setup_failed "write unrelated outer file" + git -C "$REPO" -c protocol.file.allow=always submodule add -q "$2" inner || setup_failed "add inner source" + commit >/dev/null || setup_failed "commit outer source" + local source="$REPO" + submodule_repo "$1" "$source" tests/sub || setup_failed "create nested fixture" + git -C "$REPO" -c protocol.file.allow=always submodule update -q --init --recursive || setup_failed "check out inner submodule" + remove_submodule_object HEAD:README || setup_failed "remove unrelated outer blob" + git -C "$REPO/tests/sub" ls-tree -r HEAD >/dev/null || setup_failed "outer tree must remain readable" + [ -e "$REPO/tests/sub/inner/.git" ] || setup_failed "inner submodule must be checked out" + local inner_top inner_directory inner_missing + inner_top=$(git -C "$REPO/tests/sub/inner" rev-parse --show-toplevel) || setup_failed "read inner checkout top" + inner_top=$(cd "$inner_top" && pwd -P) || setup_failed "resolve inner checkout top" + inner_directory=$(cd "$REPO/tests/sub/inner" && pwd -P) || setup_failed "resolve inner directory" + [ "$inner_top" = "$inner_directory" ] || setup_failed "inner must be its own checkout" + inner_missing=$(git -C "$REPO/tests/sub/inner" rev-list --objects --no-walk --missing=print HEAD) || setup_failed "read inner objects" + if printf '%s\n' "$inner_missing" | grep -q '^?'; then setup_failed "inner checkout lacks an object"; fi +} +nested_missing_blob_repo l-sub-inner-marker-outer-missing "$SUB" || setup_failed "create row 42" +links_case "submodule row 42: inner marker, unrelated outer blob absent" ok 0 0 + +nested_missing_blob_repo l-sub-inner-empty-outer-missing "$EMPTY_SUB" || setup_failed "create row 43" +links_case "submodule row 43: no marker, unrelated outer blob absent" error 0 2 +submodule_reason 43 tests/sub 'its recorded commit could not be read' + +submodule_repo l-sub-unchecked-before-marker "$SUB" tests/b || setup_failed "create row 44" +record_gitlink tests/a "$MISSING_COMMIT" || setup_failed "record unchecked earlier sibling" +links_case "submodule row 44: unchecked sibling precedes the marker" ok 0 0 + +newrepo l-sub-marker-missing-source || setup_failed "create row 45 source" +put scripts/test.sh '# spec-example: cap / alpha table' || setup_failed "write submodule marker" +put README 'unrelated content' || setup_failed "write unrelated file" +commit >/dev/null || setup_failed "commit row 45 source" +MARKER_MISSING_SUB="$REPO" +submodule_repo l-sub-marker-blob-missing "$MARKER_MISSING_SUB" tests/sub || setup_failed "create row 45" +remove_submodule_object HEAD:README || setup_failed "remove unrelated blob" +git -C "$REPO/tests/sub" cat-file -e HEAD:scripts/test.sh || setup_failed "marker blob must remain readable" +links_case "submodule row 45: marker counts despite another missing blob" ok 0 0 + +submodule_repo l-sub-trace "$EMPTY_SUB" tests/sub || setup_failed "create row 46" +links_case "submodule row 46: no marker, trace-free control" missing 1 1 +TRACE_CONTROL_OUT="$OUT"; TRACE_CONTROL_RC="$RC" +GIT_TRACE=1 links_case "submodule row 46: no marker, GIT_TRACE=1" missing 1 1 +assert_eq "links: submodule row 46 — trace does not change JSON" "$TRACE_CONTROL_OUT" "$OUT" +assert_exit "links: submodule row 46 — trace does not change exit" "$TRACE_CONTROL_RC" "$RC" + +mkdir -p "$WORK/gitversion-bin" || setup_failed "create version git directory" +cat > "$WORK/gitversion-bin/git" <<'EOF' || setup_failed "write version git" +#!/bin/sh +printf '%s\n' "$*" >> "$GIT_CALL_LOG" || exit 1 +case "$1" in + version|--version) printf 'git version %s\n' "$TEST_GIT_VERSION"; exit 0 ;; +esac +exec "$REAL_GIT" "$@" +EOF +chmod u+x "$WORK/gitversion-bin/git" || setup_failed "make version git executable" +submodule_repo l-sub-old-git "$SUB" tests/sub || setup_failed "create row 47" +: > "$WORK/git-version.log" || setup_failed "clear version git log" +GIT_CALL_LOG="$WORK/git-version.log" REAL_GIT="$GIT" TEST_GIT_VERSION=2.44.0 PATH="$WORK/gitversion-bin:$PATH" \ + links_case "submodule row 47: git 2.44, marker only in submodule" error 0 2 +submodule_reason 47 tests/sub 'git is older than 2.45' +refute_grep "links: submodule row 47 — no git call in the submodule" "$(basename "$REPO")/tests/sub " "$(cat "$WORK/git-version.log")" +: > "$WORK/git-version.log" || setup_failed "clear version git log for control" +GIT_CALL_LOG="$WORK/git-version.log" REAL_GIT="$GIT" TEST_GIT_VERSION=2.45.0 PATH="$WORK/gitversion-bin:$PATH" \ + links_case "submodule row 47: git 2.45 control" ok 0 0 +# Added before archiving (tasks 4.1): a version that cannot be read counts as older. +: > "$WORK/git-version.log" || setup_failed "clear version git log for unreadable version" +GIT_CALL_LOG="$WORK/git-version.log" REAL_GIT="$GIT" TEST_GIT_VERSION=unreadable PATH="$WORK/gitversion-bin:$PATH" \ + links_case "submodule row 47: a git version that cannot be read" error 0 2 +submodule_reason 47 tests/sub 'git is older than 2.45' +refute_grep "links: submodule row 47 — no git call in the submodule (unreadable version)" "$(basename "$REPO")/tests/sub " "$(cat "$WORK/git-version.log")" + +main_marker || setup_failed "add row 48 main marker" +: > "$WORK/git-version.log" || setup_failed "clear version git log for main marker" +GIT_CALL_LOG="$WORK/git-version.log" REAL_GIT="$GIT" TEST_GIT_VERSION=2.44.0 PATH="$WORK/gitversion-bin:$PATH" \ + links_case "submodule row 48: git 2.44, main marker" ok 0 0 +refute_grep "links: submodule row 48 — no git call in the submodule" "$(basename "$REPO")/tests/sub " "$(cat "$WORK/git-version.log")" +refute_grep_re "links: submodule row 48 — no version check" '^(version|--version)$' "$(cat "$WORK/git-version.log")" + +# Row 49: the object store holds the content of a file, but damaged: bytes that are not a compressed object. +# rev-list lists the object as present, opening it fails, and the search ends with exit code 128. (Row 54 is the +# case that only the exit code shows.) +submodule_repo l-sub-damaged-blob "$EMPTY_SUB" tests/sub || setup_failed "create row 49" +remove_submodule_object HEAD:scripts/test.sh || setup_failed "remove the blob before replacing it" +DAMAGED=$(git -C "$REPO/tests/sub" rev-parse HEAD:scripts/test.sh) || setup_failed "read the damaged blob id" +DAMAGED_DIR="$(git -C "$REPO/tests/sub" rev-parse --absolute-git-dir)/objects/${DAMAGED:0:2}" || setup_failed "locate the damaged blob" +mkdir -p "$DAMAGED_DIR" || setup_failed "create the object directory" +printf 'this is not a compressed object' > "$DAMAGED_DIR/${DAMAGED:2}" || setup_failed "write the damaged blob" +LACKING=$(git -C "$REPO/tests/sub" rev-list --objects --no-walk --missing=print HEAD) || setup_failed "ask which objects are lacking" +if printf '%s\n' "$LACKING" | grep -q '^?'; then setup_failed "the damaged blob must count as present"; fi +links_case "submodule row 49: no marker, a damaged blob" error 0 2 +submodule_reason 49 tests/sub 'its recorded commit could not be read' + +# Row 50: the object that holds the marker's file is present but empty. git lists it as present. What the search +# does then depends on the version of git. Measured: git 2.54.0 and 2.55.0 skip the file and still end with 0 or 1, +# so that only opening the object shows that the file was not read; git 2.56.0 ends the search itself with 128, and +# the row then takes the path of row 49. The answer is the same in both cases, and it is checked in both. +submodule_repo l-sub-empty-object "$SUB" tests/sub || setup_failed "create row 50" +remove_submodule_object HEAD:scripts/test.sh || setup_failed "remove the marker blob before emptying it" +EMPTY_OID=$(git -C "$REPO/tests/sub" rev-parse HEAD:scripts/test.sh) || setup_failed "read the emptied blob id" +EMPTY_DIR="$(git -C "$REPO/tests/sub" rev-parse --absolute-git-dir)/objects/${EMPTY_OID:0:2}" || setup_failed "locate the emptied blob" +mkdir -p "$EMPTY_DIR" || setup_failed "create the object directory of row 50" +: > "$EMPTY_DIR/${EMPTY_OID:2}" || setup_failed "write the empty object file" +LACKING=$(git -C "$REPO/tests/sub" rev-list --objects --no-walk --missing=print HEAD) || setup_failed "ask which objects row 50 lacks" +if printf '%s\n' "$LACKING" | grep -q '^?'; then setup_failed "the empty object must be listed as present"; fi +git -C "$REPO/tests/sub" grep --no-recurse-submodules -q -F -e 'spec-example: cap / alpha table' HEAD -- . >/dev/null 2>&1 +EMPTY_SEARCH=$? +if [ "$EMPTY_SEARCH" -gt 1 ]; then + echo " ~ note: this git ends the search of an empty object with exit code $EMPTY_SEARCH, row 50 takes the path of row 49" +fi +links_case "submodule row 50: the marker's object is present but empty" error 0 2 +submodule_reason 50 tests/sub 'its recorded commit could not be read' + +# Row 51: a complete submodule with a file whose name holds a carriage return followed by a question mark. +newrepo l-sub-cr-source || setup_failed "create row 51 source" +put scripts/test.sh '# no marker' || setup_failed "write row 51 file" +put "$(printf 'a\r?b')" 'content' || setup_failed "write the file with a carriage return in its name" +commit >/dev/null || setup_failed "commit row 51 source" +CR_SOURCE="$REPO" +submodule_repo l-sub-cr-name "$CR_SOURCE" tests/sub || setup_failed "create row 51" +git -C "$REPO/tests/sub" rev-list --objects --no-walk HEAD | LC_ALL=C grep -q "$(printf 'a\r')?b" \ + || setup_failed "the name with a carriage return is not in the recorded commit" +links_case "submodule row 51: a file name with a carriage return and a question mark" missing 1 1 + +# Row 52: the search of the submodule ends early (a damaged object) although the marker is in that submodule. +# What the search printed before it ended depends on its worker threads, so that output is not used. +newrepo l-sub-dies-source || setup_failed "create row 52 source" +put a/test.sh '# spec-example: cap / alpha table' || setup_failed "write row 52 marker" +put z/data.txt 'to be damaged' || setup_failed "write row 52 data file" +commit >/dev/null || setup_failed "commit row 52 source" +DIES_SOURCE="$REPO" +submodule_repo l-sub-search-dies "$DIES_SOURCE" tests/sub || setup_failed "create row 52" +remove_submodule_object HEAD:z/data.txt || setup_failed "remove the data blob before replacing it" +DIES_OID=$(git -C "$REPO/tests/sub" rev-parse HEAD:z/data.txt) || setup_failed "read the damaged blob id of row 52" +DIES_DIR="$(git -C "$REPO/tests/sub" rev-parse --absolute-git-dir)/objects/${DIES_OID:0:2}" || setup_failed "locate the damaged blob of row 52" +mkdir -p "$DIES_DIR" || setup_failed "create the object directory of row 52" +printf 'this is not a compressed object' > "$DIES_DIR/${DIES_OID:2}" || setup_failed "write the damaged blob of row 52" +git -C "$REPO/tests/sub" grep --no-recurse-submodules -q -F -e 'spec-example: cap / alpha table' HEAD -- . >/dev/null 2>&1 +[ "$?" -gt 1 ] || setup_failed "the search of row 52 must end with a code other than 0 or 1" +for run_number in 1 2 3; do + links_case "submodule row 52: the search ends early, marker in the same submodule (run $run_number)" error 0 2 + submodule_reason 52 tests/sub 'its recorded commit could not be read' +done + +# Row 53: the outer submodule lacks a tree below the top of its recorded commit. Its trees cannot all be listed, +# so the submodules inside it are unknown, although the top tree shows the inner one. +newrepo l-sub-outer-subtree-source || setup_failed "create row 53 outer source" +put zdir/file 'unrelated outer content' || setup_failed "write row 53 outer file" +git -C "$REPO" -c protocol.file.allow=always submodule add -q "$SUB" inner || setup_failed "add row 53 inner source" +commit >/dev/null || setup_failed "commit row 53 outer source" +SUBTREE_SOURCE="$REPO" +submodule_repo l-sub-outer-subtree-missing "$SUBTREE_SOURCE" tests/sub || setup_failed "create row 53" +git -C "$REPO" -c protocol.file.allow=always submodule update -q --init --recursive || setup_failed "check out row 53 inner submodule" +remove_submodule_object HEAD:zdir || setup_failed "remove the outer subtree" +git -C "$REPO/tests/sub" ls-tree HEAD | grep -q "$(printf '\t')inner\$" || setup_failed "the top tree must still show the inner submodule" +if git -C "$REPO/tests/sub" ls-tree -r HEAD >/dev/null 2>&1; then setup_failed "the full listing of row 53 must fail"; fi +[ -e "$REPO/tests/sub/inner/.git" ] || setup_failed "row 53 inner submodule must be checked out" +links_case "submodule row 53: the outer one lacks a subtree, marker in the inner one" error 0 2 +submodule_reason 53 tests/sub 'its recorded commit could not be read' + +# Row 54: the content of one file is damaged in its body. git lists the object and can open it, so nothing is +# lacking; only the exit code of the search shows that the recorded commit could not be read. +# The file is large enough that git reads its header without reaching the end of the compressed stream. +newrepo l-sub-body-source || setup_failed "create row 54 source" +put scripts/test.sh '# no marker' || setup_failed "write row 54 file" +"$PY" -c 'import sys +open(sys.argv[1], "w").write("".join("line %06d of an unrelated file\n" % i for i in range(4000)))' "$REPO/data.txt" || setup_failed "write the large file of row 54" +commit >/dev/null || setup_failed "commit row 54 source" +BODY_SOURCE="$REPO" +submodule_repo l-sub-body-damaged "$BODY_SOURCE" tests/sub || setup_failed "create row 54" +remove_submodule_object HEAD:data.txt || setup_failed "remove the blob of row 54 before rewriting it" +BODY_OID=$(git -C "$REPO/tests/sub" rev-parse HEAD:data.txt) || setup_failed "read the blob id of row 54" +[ "$(git -C "$REPO/tests/sub" hash-object -w "$BODY_SOURCE/data.txt")" = "$BODY_OID" ] || setup_failed "rewrite the blob of row 54 as a loose object" +BODY_FILE="$(git -C "$REPO/tests/sub" rev-parse --absolute-git-dir)/objects/${BODY_OID:0:2}/${BODY_OID:2}" || setup_failed "locate the blob of row 54" +"$PY" -c 'import os, sys +path = sys.argv[1] +data = bytearray(open(path, "rb").read()) +data[-1] ^= 0xFF # the last byte belongs to the checksum of the compressed stream +os.chmod(path, 0o644) +open(path, "wb").write(bytes(data))' "$BODY_FILE" || setup_failed "damage the body of the blob of row 54" +LACKING=$(git -C "$REPO/tests/sub" rev-list --objects --no-walk --missing=print HEAD) || setup_failed "ask which objects row 54 lacks" +if printf '%s\n' "$LACKING" | grep -q '^?'; then setup_failed "the damaged blob of row 54 must be listed as present"; fi +printf '%s\n' "$BODY_OID" | git -C "$REPO/tests/sub" cat-file --batch-check | grep -q " blob " || setup_failed "the damaged blob of row 54 must still be opened" +git -C "$REPO/tests/sub" grep --no-recurse-submodules -q -F -e 'spec-example: cap / alpha table' HEAD -- . >/dev/null 2>&1 +[ "$?" -gt 1 ] || setup_failed "the search of row 54 must end with a code other than 0 or 1" +links_case "submodule row 54: no marker, an object that opens but cannot be read to its end" error 0 2 +submodule_reason 54 tests/sub 'its recorded commit could not be read' + +# Row 55: the recorded path runs through a symbolic link into the main repository's own git directory, where a +# clone that holds the recorded commit and the marker was placed by hand. That directory is one of the two that +# git names at the top directory (condition 2), so the path leaves the repository and git must not run there. +example_repo l-sub-gitdir-symlink +RECORDED=$(git -C "$SUB" rev-parse HEAD) || setup_failed "read the commit of row 55" +# Record the path before placing the symlink: update-index rejects a path through one. +record_gitlink lnk/planted "$RECORDED" +git clone -q "$SUB" "$REPO/.git/planted-area/planted" || setup_failed "clone into the git directory" +ln -s .git/planted-area "$REPO/lnk" || setup_failed "link into the git directory" +git -C "$REPO/lnk/planted" cat-file -e "$RECORDED^{commit}" || setup_failed "row 55: the planted clone must hold the recorded commit" +git -C "$REPO/lnk/planted" grep -q -F -e 'spec-example: cap / alpha table' "$RECORDED" -- . || setup_failed "row 55: the recorded commit must hold the marker" +[ "$(git -C "$REPO/.git/planted-area" rev-parse --is-inside-git-dir)" = true ] || setup_failed "row 55: the planted area must be inside the git directory" +[ "$(git -C "$REPO/.git/planted-area" rev-parse --is-inside-work-tree)" = false ] || setup_failed "row 55: the planted area must not be inside the working tree" +: > "$WORK/git-calls.log" || setup_failed "clear git call log for row 55" +GIT_CALL_LOG="$WORK/git-calls.log" REAL_GIT="$GIT" PATH="$WORK/gitlog-bin:$PATH" links_case "submodule row 55: parent symlink into the main git directory" error 0 2 +submodule_reason 55 lnk/planted 'path leaves the repository' +assert_grep "links: submodule row 55 — the logging git saw the main repository" "-C $REPO rev-parse" "$(cat "$WORK/git-calls.log")" +refute_grep "links: submodule row 55 — no git command ran in the planted directory" "lnk/planted" "$(cat "$WORK/git-calls.log")" + +# Row 56: the command runs in a linked worktree whose top directory holds the main repository. The directory git +# names for this worktree is a private one; the clone was placed in the repository's own git directory, which git +# names as the common directory. Both are on the list of condition 2, so git must not run there. +example_repo l-sub-worktree-source +WT_MAIN="$REPO"; WT_TOP="$WORK/l-sub-worktree-top" +git -C "$WT_MAIN" worktree add -q -b side "$WT_TOP" HEAD || setup_failed "row 56: add the linked worktree" +mv "$WT_MAIN" "$WT_TOP/main" || setup_failed "row 56: move the main repository into the worktree" +git -C "$WT_TOP/main" worktree repair "$WT_TOP" >/dev/null 2>&1 || setup_failed "row 56: repair the worktree" +REPO="$WT_TOP" +RECORDED=$(git -C "$SUB" rev-parse HEAD) || setup_failed "read the commit of row 56" +# Record the path before placing the symlink: update-index rejects a path through one. +record_gitlink lnk/planted "$RECORDED" +git clone -q "$SUB" "$REPO/main/.git/planted-area/planted" || setup_failed "row 56: clone into the repository's git directory" +ln -s main/.git/planted-area "$REPO/lnk" || setup_failed "row 56: link into the repository's git directory" +WT_PRIVATE=$(cd "$(git -C "$REPO" rev-parse --absolute-git-dir)" && pwd -P) || setup_failed "row 56: read the git directory of the worktree" +WT_COMMON=$(cd "$REPO" && cd "$(git rev-parse --git-common-dir)" && pwd -P) || setup_failed "row 56: read the common git directory" +[ "$WT_COMMON" = "$(cd "$REPO/main/.git" && pwd -P)" ] || setup_failed "row 56: the common git directory must be the main repository's" +[ "$WT_PRIVATE" != "$WT_COMMON" ] || setup_failed "row 56: the two directories git names must differ" +git -C "$REPO/lnk/planted" cat-file -e "$RECORDED^{commit}" || setup_failed "row 56: the planted clone must hold the recorded commit" +git -C "$REPO/lnk/planted" grep -q -F -e 'spec-example: cap / alpha table' "$RECORDED" -- . || setup_failed "row 56: the recorded commit must hold the marker" +[ "$(git -C "$REPO/main/.git/planted-area" rev-parse --is-inside-git-dir)" = true ] || setup_failed "row 56: the planted area must be inside a git directory" +[ "$(git -C "$REPO/main/.git/planted-area" rev-parse --is-inside-work-tree)" = false ] || setup_failed "row 56: the planted area must not be inside a working tree" +: > "$WORK/git-calls.log" || setup_failed "clear git call log for row 56" +GIT_CALL_LOG="$WORK/git-calls.log" REAL_GIT="$GIT" PATH="$WORK/gitlog-bin:$PATH" links_case "submodule row 56: linked worktree that holds the main repository" error 0 2 +submodule_reason 56 lnk/planted 'path leaves the repository' +assert_grep "links: submodule row 56 — the logging git saw the worktree" "-C $REPO rev-parse" "$(cat "$WORK/git-calls.log")" +refute_grep "links: submodule row 56 — no git command ran in the planted directory" "lnk/planted" "$(cat "$WORK/git-calls.log")" +# Added before archiving (tasks 4.1), on the input of row 56; no row states it. An answer of git that names no +# directory is not taken for one: joined to the top directory, an empty answer would be the top directory, which +# is never compared, and the planted directory would be searched. With a git that prints nothing when asked for +# the common directory, the run ends in error and git is not run in the planted directory. (The same line of the +# script reads both answers. An empty answer to the other question changes no result on the inputs here: the +# directory it would have named is the common directory or lies under it, and the common directory still matches.) +mkdir -p "$WORK/gitsilent-bin" || setup_failed "create the directory of the silent git" +cat > "$WORK/gitsilent-bin/git" <<'EOF' || setup_failed "write the silent git" +#!/bin/sh +printf '%s\n' "$*" >> "$GIT_CALL_LOG" || exit 1 +case " $* " in + *" rev-parse --git-common-dir "*) exit 0 ;; +esac +exec "$REAL_GIT" "$@" +EOF +chmod u+x "$WORK/gitsilent-bin/git" || setup_failed "make the silent git executable" +: > "$WORK/git-calls.log" || setup_failed "clear git call log for the silent git" +GIT_CALL_LOG="$WORK/git-calls.log" REAL_GIT="$GIT" PATH="$WORK/gitsilent-bin:$PATH" links_case "git names no common directory (input of row 56)" error 0 2 +assert_grep "links: git names no common directory — the silent git was asked for it" "rev-parse --git-common-dir" "$(cat "$WORK/git-calls.log")" +refute_grep "links: git names no common directory — no git command ran in the planted directory" "lnk/planted" "$(cat "$WORK/git-calls.log")" + +# Row 57: the list of condition 2 is closed, and no git directory of a submodule is added to it. The outer +# submodule is a plain clone, so its `.git` is a directory, which is neither of the two nor under one of them; a +# link inside the submodule leads into that directory, where a clone that holds the marker was placed by hand. +# The inner path is searched. +newrepo l-sub-own-gitdir-outer-source +git -C "$REPO" update-index --add --cacheinfo "160000,$RECORDED,l/inner" || setup_failed "row 57: record the inner gitlink" +git -C "$REPO" commit -q -m inner-gitlink || setup_failed "row 57: commit the inner gitlink" +OUTER_SOURCE="$REPO" +OUTER_RECORDED=$(git -C "$OUTER_SOURCE" rev-parse HEAD) || setup_failed "row 57: read the commit of the outer submodule" +example_repo l-sub-own-gitdir +git clone -q "$OUTER_SOURCE" "$REPO/outer" || setup_failed "row 57: clone the outer submodule" +record_gitlink outer "$OUTER_RECORDED" +{ [ -d "$REPO/outer/.git" ] && [ ! -L "$REPO/outer/.git" ]; } || setup_failed "row 57: the .git entry of the outer submodule must be a directory" +rm -rf "$REPO/outer/l" || setup_failed "row 57: remove the checked-out inner path" +git clone -q "$SUB" "$REPO/outer/.git/planted-area/inner" || setup_failed "row 57: clone into the git directory of the outer submodule" +ln -s .git/planted-area "$REPO/outer/l" || setup_failed "row 57: link into the git directory of the outer submodule" +git -C "$REPO/outer/l/inner" cat-file -e "$RECORDED^{commit}" || setup_failed "row 57: the planted clone must hold the recorded commit" +git -C "$REPO/outer/l/inner" grep -q -F -e 'spec-example: cap / alpha table' "$RECORDED" -- . || setup_failed "row 57: the recorded commit must hold the marker" +[ "$(git -C "$REPO/outer/.git/planted-area" rev-parse --is-inside-git-dir)" = true ] || setup_failed "row 57: the planted area must be inside the git directory of the outer submodule" +: > "$WORK/git-calls.log" || setup_failed "clear git call log for row 57" +GIT_CALL_LOG="$WORK/git-calls.log" REAL_GIT="$GIT" PATH="$WORK/gitlog-bin:$PATH" links_case "submodule row 57: link into the git directory of a submodule" ok 0 0 +assert_grep "links: submodule row 57 — git searched the directory inside the git directory of the submodule" "$(basename "$REPO")/outer/l/inner grep " "$(cat "$WORK/git-calls.log")" +# Control: the answer comes from that directory alone. Without the planted clone the inner path cannot be searched. +rm -rf "$REPO/outer/.git/planted-area/inner" || setup_failed "row 57: remove the planted clone" +links_case "submodule row 57: control without the planted clone" error 0 2 +submodule_reason 57 outer/l/inner 'not checked out' + +# Row 58: the top directory is not compared with the two directories of condition 2. Here the git directory of the +# main repository was made apart and the top directory lies inside it; the submodule under the top directory is +# searched as usual. +INSIDE="$WORK/l-sub-top-inside-gitdir" +mkdir -p "$INSIDE" || setup_failed "row 58: create the parent directory" +git init -q -b main --separate-git-dir "$INSIDE/gd" "$INSIDE/gd/top" || setup_failed "row 58: initialize a repository whose top directory lies inside its git directory" +REPO="$INSIDE/gd/top" +git -C "$REPO" commit -q --allow-empty -m init || setup_failed "row 58: commit the empty repository" +put openspec/specs/cap/spec.md "$(spec "$(req Base)")" || setup_failed "row 58: write the base spec" +BASE=$(commit base) || setup_failed "row 58: commit the base spec" +put openspec/specs/cap/spec.md "$(spec "$(req Base)" "$(req Alpha "$EX")")" || setup_failed "row 58: write the Example" +git -C "$REPO" -c protocol.file.allow=always submodule add -q "$SUB" tests/sub || setup_failed "row 58: add the submodule" +commit example >/dev/null || setup_failed "row 58: commit the Example" +[ "$(git -C "$REPO" rev-parse --is-inside-work-tree)" = true ] || setup_failed "row 58: git must report the top directory as inside the working tree" +# Asked of the file system, not of `git rev-parse --is-inside-git-dir`: for this layout git 2.55 answers true and +# git 2.54 answers false, and the row states where the top directory lies, not what that option prints. +ROW58_GD=$(cd "$(git -C "$REPO" rev-parse --absolute-git-dir)" && pwd -P) || setup_failed "row 58: read the git directory" +case "$(cd "$REPO" && pwd -P)/" in + "$ROW58_GD"/*) ;; + *) setup_failed "row 58: the top directory must lie inside the git directory" ;; +esac +: > "$WORK/git-calls.log" || setup_failed "clear git call log for row 58" +GIT_CALL_LOG="$WORK/git-calls.log" REAL_GIT="$GIT" PATH="$WORK/gitlog-bin:$PATH" links_case "submodule row 58: top directory inside the main git directory" ok 0 0 +assert_grep "links: submodule row 58 — git searched the submodule under the top directory" "$(basename "$REPO")/tests/sub grep " "$(cat "$WORK/git-calls.log")" + +# Row 59: a directory that resolves to the top directory itself meets condition 2. The head records, at a path +# that a link leads back to the top directory, an earlier commit of the main repository that holds the marker; the +# files of the head do not hold it. +linked_repo l-sub-back-to-top +put scripts/test.sh '# spec-example: cap / alpha table' || setup_failed "row 59: write the marker" +EARLIER=$(commit marker) || setup_failed "row 59: commit the marker" +git -C "$REPO" rm -q scripts/test.sh || setup_failed "row 59: remove the marker" +put openspec/specs/cap/spec.md "$(spec "$(req Base)" "$(req Alpha "$EX")")" || setup_failed "row 59: write the Example" +commit example >/dev/null || setup_failed "row 59: commit the Example" +BACK="out/$(basename "$REPO")" +record_gitlink "$BACK" "$EARLIER" +ln -s .. "$REPO/out" || setup_failed "row 59: link back to the parent directory" +[ "$(cd "$REPO/$BACK" && pwd -P)" = "$(cd "$REPO" && pwd -P)" ] || setup_failed "row 59: the recorded path must resolve to the top directory" +if git -C "$REPO" grep -q -F -e 'spec-example: cap / alpha table' HEAD -- scripts; then setup_failed "row 59: the files of the head must not hold the marker"; fi +git -C "$REPO" grep -q -F -e 'spec-example: cap / alpha table' "$EARLIER" -- scripts || setup_failed "row 59: the earlier commit must hold the marker" +: > "$WORK/git-calls.log" || setup_failed "clear git call log for row 59" +GIT_CALL_LOG="$WORK/git-calls.log" REAL_GIT="$GIT" PATH="$WORK/gitlog-bin:$PATH" links_case "submodule row 59: recorded path that resolves to the top directory" ok 0 0 +assert_grep "links: submodule row 59 — git searched at the recorded path" "$(basename "$REPO")/$BACK grep " "$(cat "$WORK/git-calls.log")" +assert_grep "links: submodule row 59 — the commit searched there is the recorded one" "$EARLIER -- ." "$(cat "$WORK/git-calls.log")" + +# Rows 60 to 64 need two spellings of one directory: a path written in another letter case, on a volume that does +# not distinguish letter case. A volume that does has no second spelling that an ordinary user can make, and the +# five rows are not run there. +mkdir "$WORK/CaseProbe" || setup_failed "create the directory that probes letter case" +if [ -d "$WORK/caseprobe" ]; then + other_case() { # path — the same path with its last component in the other letter case + printf '%s/%s' "$(dirname "$1")" "$(basename "$1" | tr 'a-z' 'A-Z')" + } + + # Row 60: the submodule is checked out inside the working tree and its recorded path runs through a symbolic + # link whose target names the top directory in another letter case. The resolved path keeps that spelling; the + # directory it names lies under the top directory, and git names it by its name on disk (conditions 2 and 5). + example_repo l-sub-case-link + RECORDED=$(git -C "$SUB" rev-parse HEAD) || setup_failed "read the commit of row 60" + # Record the path before placing the symlink: update-index rejects a path through one. + record_gitlink alias/sub "$RECORDED" + mkdir "$REPO/actual" || setup_failed "row 60: create the directory that holds the submodule" + git clone -q "$SUB" "$REPO/actual/sub" || setup_failed "row 60: clone the submodule into the working tree" + SPELLED=$(other_case "$REPO") + [ "$SPELLED" != "$REPO" ] || setup_failed "row 60: the second spelling must differ from the first" + [ "$SPELLED" -ef "$REPO" ] || setup_failed "row 60: the second spelling must name the top directory" + ln -s "$SPELLED/actual" "$REPO/alias" || setup_failed "row 60: link through the second spelling" + git -C "$REPO/alias/sub" grep -q -F -e 'spec-example: cap / alpha table' "$RECORDED" -- . || setup_failed "row 60: the recorded commit must hold the marker" + : > "$WORK/git-calls.log" || setup_failed "clear git call log for row 60" + GIT_CALL_LOG="$WORK/git-calls.log" REAL_GIT="$GIT" PATH="$WORK/gitlog-bin:$PATH" links_case "submodule row 60: link whose target names the top directory in another letter case" ok 0 0 + assert_grep "links: submodule row 60 — git searched at the recorded path" "$(basename "$REPO")/alias/sub grep " "$(cat "$WORK/git-calls.log")" + # The same input with the target written through the data volume of macOS, where that path names the fixture. + DATA_SPELLED="/System/Volumes/Data$(cd "$REPO" && pwd -P)" + if [ "$DATA_SPELLED" -ef "$REPO" ]; then + rm "$REPO/alias" || setup_failed "row 60: remove the link" + ln -s "$DATA_SPELLED/actual" "$REPO/alias" || setup_failed "row 60: link through the data volume" + links_case "submodule row 60: the same link written through the data volume" ok 0 0 + else + echo " ~ skipped: /System/Volumes/Data does not name the fixtures here, the second form of row 60 was not run" + fi + + # Row 61: the tree records the path tests/sub and the directory on disk is named Tests/sub (as after a rename by + # letter case upstream and a pull). Git, run there, names the directory as it is named on disk: the same + # directory as the one the recorded path names, under another name (condition 5). + example_repo l-sub-case-recorded + RECORDED=$(git -C "$SUB" rev-parse HEAD) || setup_failed "read the commit of row 61" + record_gitlink tests/sub "$RECORDED" + mkdir "$REPO/Tests" || setup_failed "row 61: create the directory named Tests" + git clone -q "$SUB" "$REPO/Tests/sub" || setup_failed "row 61: clone the submodule" + case "$(git -C "$REPO/tests/sub" rev-parse --show-toplevel)" in + */Tests/sub) ;; + *) setup_failed "row 61: git must name the directory as it is named on disk" ;; + esac + : > "$WORK/git-calls.log" || setup_failed "clear git call log for row 61" + GIT_CALL_LOG="$WORK/git-calls.log" REAL_GIT="$GIT" PATH="$WORK/gitlog-bin:$PATH" links_case "submodule row 61: recorded path and directory on disk differ in letter case only" ok 0 0 + assert_grep "links: submodule row 61 — git searched at the recorded path" "$(basename "$REPO")/tests/sub grep " "$(cat "$WORK/git-calls.log")" + + # Row 62: the link leads to a directory outside the top directory, and its target names that directory in + # another letter case. Going up from it the top directory is not met, so git is asked nothing about it. + example_repo l-sub-case-outside + RECORDED=$(git -C "$SUB" rev-parse HEAD) || setup_failed "read the commit of row 62" + record_gitlink alias/sub "$RECORDED" + OUTSIDE="$WORK/l-sub-case-outside-target" + mkdir "$OUTSIDE" || setup_failed "row 62: create the outside directory" + git clone -q "$SUB" "$OUTSIDE/sub" || setup_failed "row 62: clone outside the top directory" + SPELLED=$(other_case "$OUTSIDE") + [ "$SPELLED" -ef "$OUTSIDE" ] || setup_failed "row 62: the second spelling must name the outside directory" + ln -s "$SPELLED" "$REPO/alias" || setup_failed "row 62: link to the outside directory" + git -C "$REPO/alias/sub" grep -q -F -e 'spec-example: cap / alpha table' "$RECORDED" -- . || setup_failed "row 62: the outside clone must hold the marker" + : > "$WORK/git-calls.log" || setup_failed "clear git call log for row 62" + GIT_CALL_LOG="$WORK/git-calls.log" REAL_GIT="$GIT" PATH="$WORK/gitlog-bin:$PATH" links_case "submodule row 62: link to a directory outside the top directory, named in another letter case" error 0 2 + submodule_reason 62 alias/sub 'path leaves the repository' + refute_grep "links: submodule row 62 — no git command ran in the outside directory" "alias/sub" "$(cat "$WORK/git-calls.log")" + refute_grep "links: submodule row 62 — git was not asked for the two directories" "rev-parse --absolute-git-dir" "$(cat "$WORK/git-calls.log")" + + # Row 63: the input of row 55, with the link's target naming the top directory in another letter case. The + # top directory is met on the way up, and the main git directory is passed before it: the refusal comes from + # the comparison with the two directories, for which git is asked, not from the spelling of the path. + example_repo l-sub-case-gitdir + RECORDED=$(git -C "$SUB" rev-parse HEAD) || setup_failed "read the commit of row 63" + record_gitlink lnk/planted "$RECORDED" + git clone -q "$SUB" "$REPO/.git/planted-area/planted" || setup_failed "row 63: clone into the git directory" + SPELLED=$(other_case "$REPO") + [ "$SPELLED" -ef "$REPO" ] || setup_failed "row 63: the second spelling must name the top directory" + ln -s "$SPELLED/.git/planted-area" "$REPO/lnk" || setup_failed "row 63: link into the git directory" + git -C "$REPO/lnk/planted" cat-file -e "$RECORDED^{commit}" || setup_failed "row 63: the planted clone must hold the recorded commit" + git -C "$REPO/lnk/planted" grep -q -F -e 'spec-example: cap / alpha table' "$RECORDED" -- . || setup_failed "row 63: the recorded commit must hold the marker" + : > "$WORK/git-calls.log" || setup_failed "clear git call log for row 63" + GIT_CALL_LOG="$WORK/git-calls.log" REAL_GIT="$GIT" PATH="$WORK/gitlog-bin:$PATH" links_case "submodule row 63: link into the main git directory through another letter case of the top directory" error 0 2 + submodule_reason 63 lnk/planted 'path leaves the repository' + refute_grep "links: submodule row 63 — no git command ran in the planted directory" "lnk/planted" "$(cat "$WORK/git-calls.log")" + assert_grep "links: submodule row 63 — git was asked for the two directories" "rev-parse --absolute-git-dir" "$(cat "$WORK/git-calls.log")" + + # Row 64: the recorded path names the spec directory in another letter case, so the submodule's directory lies + # in the spec directory although its name is not under `openspec/`. It is not searched, and it is not one that + # could not be searched: the answer is the one of row 15. + example_repo l-sub-case-spec + RECORDED=$(git -C "$SUB" rev-parse HEAD) || setup_failed "read the commit of row 64" + record_gitlink OPENSPEC/vendor/sub "$RECORDED" + mkdir -p "$REPO/openspec/vendor" || setup_failed "row 64: create the directory under the spec directory" + git clone -q "$SUB" "$REPO/openspec/vendor/sub" || setup_failed "row 64: clone into the spec directory" + [ "$REPO/OPENSPEC/vendor/sub" -ef "$REPO/openspec/vendor/sub" ] || setup_failed "row 64: the recorded path must name the clone" + git -C "$REPO" ls-tree -r --name-only HEAD | grep -q '^OPENSPEC/vendor/sub$' || setup_failed "row 64: the tree must record the path in the other letter case" + git -C "$REPO/OPENSPEC/vendor/sub" grep -q -F -e 'spec-example: cap / alpha table' "$RECORDED" -- . || setup_failed "row 64: the recorded commit must hold the marker" + : > "$WORK/git-calls.log" || setup_failed "clear git call log for row 64" + GIT_CALL_LOG="$WORK/git-calls.log" REAL_GIT="$GIT" PATH="$WORK/gitlog-bin:$PATH" links_case "submodule row 64: recorded path names the spec directory in another letter case" missing 1 1 + refute_grep "links: submodule row 64 — no git command ran in that directory" "vendor/sub" "$(cat "$WORK/git-calls.log")" +else + echo " ~ skipped: this volume distinguishes letter case, submodule rows 60 to 64 were not run" +fi + +# Row 65: the submodule is checked out under the spec directory and its recorded path reaches it through a +# symbolic link in the working tree, so its name is not under `openspec/`. Its directory lies in the spec +# directory: it is not searched, and it is not one that could not be searched. +example_repo l-sub-link-into-spec +RECORDED=$(git -C "$SUB" rev-parse HEAD) || setup_failed "read the commit of row 65" +# Record the path before placing the symlink: update-index rejects a path through one. +record_gitlink lnk/sub "$RECORDED" +mkdir -p "$REPO/openspec/vendor" || setup_failed "row 65: create the directory under the spec directory" +git clone -q "$SUB" "$REPO/openspec/vendor/sub" || setup_failed "row 65: clone into the spec directory" +ln -s openspec/vendor "$REPO/lnk" || setup_failed "row 65: link into the spec directory" +git -C "$REPO/lnk/sub" grep -q -F -e 'spec-example: cap / alpha table' "$RECORDED" -- . || setup_failed "row 65: the recorded commit must hold the marker" +: > "$WORK/git-calls.log" || setup_failed "clear git call log for row 65" +GIT_CALL_LOG="$WORK/git-calls.log" REAL_GIT="$GIT" PATH="$WORK/gitlog-bin:$PATH" links_case "submodule row 65: link that leads into the spec directory" missing 1 1 +refute_grep "links: submodule row 65 — no git command ran in that directory" "lnk/sub" "$(cat "$WORK/git-calls.log")" + # ── preflight ─────────────────────────────────────────────────────────────── echo "spec-change: preflight (Example: preflight by write access and Spectra state)" @@ -330,6 +1258,77 @@ assert_grep "preflight: init-openspec names the command" "spectra init" "$(print pf_repo pf-sub no yes; mkdir -p "$TREE/deep/er"; OUT=$(PATH="$BIN_WITH" "$PY" "$SC" preflight --cwd "$TREE/deep/er" --can-write yes 2>/dev/null) assert_eq "preflight: run from a subdirectory, openspec/ is looked for at the top of the repository" ready "$(printf '%s' "$OUT" | field status)" +# ── a top level whose name ends in whitespace ─────────────────────────────── +echo "spec-change: a top level whose name ends in whitespace (rows 7 to 12 of the Example)" +example_repo 'l-top-space ' || setup_failed "create trailing-space repository" +main_marker || setup_failed "write top-directory marker" +put openspec/changes/archive/2026-11-10-idd-42-example/proposal.md 'Archived change.' || setup_failed "write archived change" +commit >/dev/null || setup_failed "commit archived change" +SPACE_REPO="$REPO"; COPY_REPO="$WORK/l-top-copy" +cp -R "$SPACE_REPO" "$COPY_REPO" || setup_failed "copy repository without trailing space" +SPACE_HEAD=$(git -C "$SPACE_REPO" rev-parse HEAD) || setup_failed "read trailing-space head" +COPY_HEAD=$(git -C "$COPY_REPO" rev-parse HEAD) || setup_failed "read copied head" +[ "$SPACE_HEAD" = "$COPY_HEAD" ] || setup_failed "copied repository must have the same commits" +cat > "$WORK/top-directory-comment.md" <<EOF || setup_failed "write archived declaration" +$MARK +## Implementation Complete + +**Spec**: change idd-42-example +EOF + +REPO="$COPY_REPO" +links_case "top level ending in whitespace: links control" ok 0 0 +COPY_OUT="$OUT"; COPY_RC="$RC" +REPO="$SPACE_REPO" +links_case "top level ending in whitespace: links trailing space" ok 0 0 +assert_eq "top level ending in whitespace: links — identical JSON" "$COPY_OUT" "$OUT" +assert_exit "top level ending in whitespace: links — identical exit" "$COPY_RC" "$RC" + +run archived --file "$WORK/top-directory-comment.md" --cwd "$COPY_REPO" --ref HEAD +COPY_OUT="$OUT"; COPY_RC="$RC" +assert_eq "top level ending in whitespace: archived control — status" pass "$(printf '%s' "$OUT" | field status)" +assert_exit "top level ending in whitespace: archived control — exit" 0 "$RC" +assert_eq "top level ending in whitespace: archived control — one JSON line" 1 "$LINES" +run archived --file "$WORK/top-directory-comment.md" --cwd "$SPACE_REPO" --ref HEAD +assert_eq "top level ending in whitespace: archived trailing space — status" pass "$(printf '%s' "$OUT" | field status)" +assert_eq "top level ending in whitespace: archived — identical JSON" "$COPY_OUT" "$OUT" +assert_exit "top level ending in whitespace: archived — identical exit" "$COPY_RC" "$RC" +assert_eq "top level ending in whitespace: archived trailing space — one JSON line" 1 "$LINES" + +PATH="$BIN_WITH:$PATH" run preflight --cwd "$COPY_REPO" --can-write yes +COPY_STATUS=$(printf '%s' "$OUT" | field status); COPY_RC="$RC" +assert_eq "top level ending in whitespace: preflight control — status" ready "$COPY_STATUS" +assert_exit "top level ending in whitespace: preflight control — exit" 0 "$RC" +assert_eq "top level ending in whitespace: preflight control — one JSON line" 1 "$LINES" +PATH="$BIN_WITH:$PATH" run preflight --cwd "$SPACE_REPO" --can-write yes +assert_eq "top level ending in whitespace: preflight — identical status" "$COPY_STATUS" "$(printf '%s' "$OUT" | field status)" +assert_exit "top level ending in whitespace: preflight — identical exit" "$COPY_RC" "$RC" +assert_eq "top level ending in whitespace: preflight trailing space — one JSON line" 1 "$LINES" + +# A name that ends in a line feed: the only input that tells "remove the one line end git adds" from "remove +# every trailing line feed". The copy at a plain name is the control of the block above. +NEWLINE_REPO="$WORK/l-top-newline"$'\n' +cp -R "$COPY_REPO" "$NEWLINE_REPO" || setup_failed "copy repository to a name that ends in a line feed" +[ "$(git -C "$NEWLINE_REPO" rev-parse HEAD)" = "$COPY_HEAD" ] || setup_failed "the line-feed copy must have the same commits" +REPO="$COPY_REPO" +links_case "top level ending in whitespace: links control (line feed)" ok 0 0 +COPY_OUT="$OUT"; COPY_RC="$RC" +REPO="$NEWLINE_REPO" +links_case "top level ending in whitespace: links trailing line feed" ok 0 0 +assert_eq "top level ending in whitespace: links, line feed — identical JSON" "$COPY_OUT" "$OUT" +assert_exit "top level ending in whitespace: links, line feed — identical exit" "$COPY_RC" "$RC" +run archived --file "$WORK/top-directory-comment.md" --cwd "$COPY_REPO" --ref HEAD +COPY_OUT="$OUT"; COPY_RC="$RC" +run archived --file "$WORK/top-directory-comment.md" --cwd "$NEWLINE_REPO" --ref HEAD +assert_eq "top level ending in whitespace: archived trailing line feed — status" pass "$(printf '%s' "$OUT" | field status)" +assert_eq "top level ending in whitespace: archived, line feed — identical JSON" "$COPY_OUT" "$OUT" +assert_exit "top level ending in whitespace: archived, line feed — identical exit" "$COPY_RC" "$RC" +PATH="$BIN_WITH:$PATH" run preflight --cwd "$COPY_REPO" --can-write yes +COPY_STATUS=$(printf '%s' "$OUT" | field status); COPY_RC="$RC" +PATH="$BIN_WITH:$PATH" run preflight --cwd "$NEWLINE_REPO" --can-write yes +assert_eq "top level ending in whitespace: preflight, line feed — identical status" "$COPY_STATUS" "$(printf '%s' "$OUT" | field status)" +assert_exit "top level ending in whitespace: preflight, line feed — identical exit" "$COPY_RC" "$RC" + # ── spec directory (task 2.6) ─────────────────────────────────────────────── echo "spec-change: spec directory (Example: spec directory by .spectra.yaml)" SPEC_DS="$MARK