LCOV - code coverage report
Current view: top level - designdoc - collection.go Coverage Total Hit
Test: coverage.lcov Lines: 95.7 % 92 88
Test Date: 2026-11-19 00:25:22 Functions: - 0 0

            Line data    Source code
       1              : package designdoc
       2              : 
       3              : import (
       4              :         "fmt"
       5              :         "os"
       6              :         "path/filepath"
       7              :         "slices"
       8              :         "strings"
       9              : )
      10              : 
      11              : // DefaultDir は設計ドキュメントが置かれる既定のディレクトリ。
      12              : const DefaultDir = "docs/design"
      13              : 
      14              : // templateFile は雛形。実ドキュメントではないので読み込み対象から除外する。
      15              : const templateFile = "tmpl.md"
      16              : 
      17              : // listMarkdownFiles は dir 直下の設計ドキュメントのパスをファイル名昇順で返す。
      18              : // tmpl.md と .md 以外は除外する。
      19              : func listMarkdownFiles(dir string) ([]string, error) {
      20            1 :         entries, err := os.ReadDir(dir)
      21            1 :         if err != nil {
      22            1 :                 return nil, fmt.Errorf("failed to read %s: %w", dir, err)
      23            1 :         }
      24              : 
      25            1 :         var paths []string
      26            1 :         for _, e := range entries {
      27            1 :                 name := e.Name()
      28            1 :                 if e.IsDir() || filepath.Ext(name) != ".md" || name == templateFile {
      29            1 :                         continue
      30              :                 }
      31            1 :                 paths = append(paths, filepath.Join(dir, name))
      32              :         }
      33            1 :         slices.Sort(paths)
      34            1 : 
      35            1 :         return paths, nil
      36              : }
      37              : 
      38              : // LoadDir は dir 直下の設計ドキュメントを解析して返す。
      39              : func LoadDir(dir string) ([]*Document, error) {
      40            1 :         paths, err := listMarkdownFiles(dir)
      41            1 :         if err != nil {
      42            1 :                 return nil, err
      43            1 :         }
      44              : 
      45            1 :         var docs []*Document
      46            1 :         for _, path := range paths {
      47            1 :                 content, err := os.ReadFile(path)
      48            1 :                 if err != nil {
      49            1 :                         return nil, fmt.Errorf("failed to read %s: %w", path, err)
      50            1 :                 }
      51              : 
      52            1 :                 doc, err := Parse(path, string(content))
      53            1 :                 if err != nil {
      54            1 :                         return nil, err
      55            1 :                 }
      56            1 :                 docs = append(docs, doc)
      57              :         }
      58              : 
      59            1 :         return docs, nil
      60              : }
      61              : 
      62              : // Problem は検証で見つかった1件の問題を表す。深刻度は設けず、1件でもあれば CI を落とす。
      63              : type Problem struct {
      64              :         Path    string
      65              :         Message string
      66              : }
      67              : 
      68              : // Validate はドキュメント群の frontmatter を検証して問題の一覧を返す。
      69              : // 深刻度の区別はしない。1件でも返れば呼び出し側は失敗させる。
      70              : func Validate(docs []*Document) []Problem {
      71            1 :         var problems []Problem
      72            1 :         add := func(path string, msg string) {
      73            1 :                 problems = append(problems, Problem{Path: path, Message: msg})
      74            1 :         }
      75              : 
      76            1 :         for _, doc := range docs {
      77            1 :                 if !doc.HasFront {
      78            1 :                         add(doc.Path, "frontmatter is missing; generate it with gen")
      79            1 :                         continue
      80              :                 }
      81            1 :                 if !doc.Front.Status.Valid() {
      82            1 :                         add(doc.Path, fmt.Sprintf("invalid status: %q", doc.Front.Status))
      83            1 :                 }
      84            1 :                 if !doc.Front.Auto.Valid() {
      85            1 :                         add(doc.Path, fmt.Sprintf("invalid auto: %q", doc.Front.Auto))
      86            1 :                 }
      87            1 :                 for _, tag := range doc.Front.Tags {
      88            1 :                         if !slices.Contains(KnownTags, tag) {
      89            1 :                                 add(doc.Path, fmt.Sprintf("unknown tag %q; check KnownTags", tag))
      90            1 :                         }
      91              :                 }
      92              :                 // done は「open な `- [ ]` がゼロ」を満たす不変条件。裏付けのない done を弾く。
      93              :                 // 着手しないと決めたタスクは `- [~]` にすれば open から外れ、done にできる。
      94            1 :                 if doc.Front.Status == StatusDone && doc.OpenTasks > 0 {
      95            1 :                         add(doc.Path, fmt.Sprintf("status=done but %d unchecked task(s) remain; complete them or mark with `- [~]`", doc.OpenTasks))
      96            1 :                 }
      97            1 :                 if doc.Front.Status == StatusInProgress && !doc.HasProgress {
      98            1 :                         add(doc.Path, "status=in-progress but no progress section")
      99            1 :                 }
     100              :         }
     101              : 
     102            1 :         return problems
     103              : }
     104              : 
     105              : // BackfillDir は dir 直下の frontmatter を欠くドキュメントに既定値を付与し、変更したファイルのパスを返す。
     106              : // 冪等なので、既に付与済みのファイルには触れない。
     107              : func BackfillDir(dir string) ([]string, error) {
     108            1 :         paths, err := listMarkdownFiles(dir)
     109            1 :         if err != nil {
     110            1 :                 return nil, err
     111            1 :         }
     112              : 
     113            1 :         var changed []string
     114            1 :         for _, path := range paths {
     115            1 :                 content, err := os.ReadFile(path)
     116            1 :                 if err != nil {
     117            1 :                         return nil, fmt.Errorf("failed to read %s: %w", path, err)
     118            1 :                 }
     119              : 
     120            1 :                 result, ok, err := Backfill(string(content))
     121            1 :                 if err != nil {
     122            1 :                         return nil, fmt.Errorf("failed to backfill %s: %w", path, err)
     123            1 :                 }
     124            1 :                 if !ok {
     125            1 :                         continue
     126              :                 }
     127              : 
     128            1 :                 if err := os.WriteFile(path, []byte(result), 0o644); err != nil {
     129            0 :                         return nil, fmt.Errorf("failed to write %s: %w", path, err)
     130            0 :                 }
     131            1 :                 changed = append(changed, path)
     132              :         }
     133              : 
     134              :         // paths は既に昇順のため changed も昇順になる。
     135            1 :         return changed, nil
     136              : }
     137              : 
     138              : // Backfill は frontmatter を欠くドキュメントに決定的な既定値を付与した内容を返す。
     139              : // 既に frontmatter があれば内容を変えず changed=false を返す。冪等なので何度でも流せる。
     140              : func Backfill(content string) (result string, changed bool, err error) {
     141            1 :         doc, err := Parse("", content)
     142            1 :         if err != nil {
     143            1 :                 return "", false, err
     144            1 :         }
     145            1 :         if doc.HasFront {
     146            1 :                 return content, false, nil
     147            1 :         }
     148              : 
     149            1 :         front := Frontmatter{
     150            1 :                 Status: InferStatus(doc),
     151            1 :                 Tags:   []string{},
     152            1 :                 Auto:   AutoNeedsDecision,
     153            1 :         }
     154              : 
     155            1 :         rendered, err := Render(front, strings.TrimPrefix(content, "\n"))
     156            1 :         if err != nil {
     157            0 :                 return "", false, err
     158            0 :         }
     159              : 
     160            1 :         return rendered, true, nil
     161              : }
        

Generated by: LCOV version 2.0-1