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 : }
|