edify-agents-cli 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. edify/__init__.py +19 -0
  2. edify/__main__.py +6 -0
  3. edify/_toml.py +286 -0
  4. edify/agents.py +261 -0
  5. edify/anim.py +499 -0
  6. edify/assets/commands/build.md +64 -0
  7. edify/assets/commands/plan.md +68 -0
  8. edify/assets/commands/spec.md +63 -0
  9. edify/assets/commands/tasks.md +65 -0
  10. edify/assets/commands/verify.md +67 -0
  11. edify/assets/formats/plan.example.md +455 -0
  12. edify/assets/formats/plan.format.md +128 -0
  13. edify/assets/formats/spec.example.md +483 -0
  14. edify/assets/formats/spec.format.md +116 -0
  15. edify/assets/formats/tasks.example.md +712 -0
  16. edify/assets/formats/tasks.format.md +199 -0
  17. edify/assets/harvest/harvest.md +91 -0
  18. edify/assets/harvest/sources.md +295 -0
  19. edify/assets/harvest/vocab.md +52 -0
  20. edify/assets/manifest.md +30 -0
  21. edify/assets/mcp/default-registry.md +66 -0
  22. edify/assets/skills/adversary.md +61 -0
  23. edify/assets/skills/debugger.md +64 -0
  24. edify/assets/skills/implementer-general.md +53 -0
  25. edify/assets/skills/implementer-go.md +63 -0
  26. edify/assets/skills/implementer-node.md +61 -0
  27. edify/assets/skills/implementer-postgres.md +63 -0
  28. edify/assets/skills/implementer-python.md +65 -0
  29. edify/assets/skills/implementer-react.md +65 -0
  30. edify/assets/skills/planner.md +58 -0
  31. edify/assets/skills/test-writer-node.md +64 -0
  32. edify/assets/skills/test-writer-python.md +60 -0
  33. edify/assets/skills/verifier.md +67 -0
  34. edify/assets/templates/CLAUDE.md +18 -0
  35. edify/assets.py +77 -0
  36. edify/cli.py +681 -0
  37. edify/commands/__init__.py +1 -0
  38. edify/commands/check_cmd.py +72 -0
  39. edify/commands/doctor_cmd.py +206 -0
  40. edify/commands/feedback_cmd.py +90 -0
  41. edify/commands/governance_cmd.py +65 -0
  42. edify/commands/graph_cmd.py +156 -0
  43. edify/commands/harvest_cmd.py +538 -0
  44. edify/commands/init_cmd.py +333 -0
  45. edify/commands/init_new_cmd.py +151 -0
  46. edify/commands/license_cmd.py +80 -0
  47. edify/commands/mcp_cmd.py +159 -0
  48. edify/commands/self_cmd.py +185 -0
  49. edify/commands/setup_cmd.py +79 -0
  50. edify/commands/skills_cmd.py +177 -0
  51. edify/commands/upgrade_cmd.py +178 -0
  52. edify/context.py +57 -0
  53. edify/conventions.py +275 -0
  54. edify/detect.py +313 -0
  55. edify/distribution.py +40 -0
  56. edify/errors.py +66 -0
  57. edify/feedback.py +207 -0
  58. edify/formats/__init__.py +11 -0
  59. edify/formats/check.py +573 -0
  60. edify/formats/document.py +238 -0
  61. edify/formats/finding.py +50 -0
  62. edify/formats/fix.py +114 -0
  63. edify/formats/mcp.py +126 -0
  64. edify/formats/plan.py +151 -0
  65. edify/formats/skill.py +139 -0
  66. edify/formats/spec.py +164 -0
  67. edify/formats/tasks.py +321 -0
  68. edify/governance.py +316 -0
  69. edify/graph/__init__.py +11 -0
  70. edify/graph/extract.py +351 -0
  71. edify/graph/ignore.py +107 -0
  72. edify/graph/langs/__init__.py +93 -0
  73. edify/graph/langs/ctags.py +145 -0
  74. edify/graph/langs/markdown.py +41 -0
  75. edify/graph/langs/patterns.py +361 -0
  76. edify/graph/langs/python_ast.py +154 -0
  77. edify/graph/langs/sqlish.py +86 -0
  78. edify/graph/model.py +102 -0
  79. edify/graph/queries.py +211 -0
  80. edify/graph/store.py +157 -0
  81. edify/harvest/__init__.py +28 -0
  82. edify/harvest/ledger.py +191 -0
  83. edify/harvest/screen.py +236 -0
  84. edify/harvest/sources.py +298 -0
  85. edify/host.py +345 -0
  86. edify/interview.py +354 -0
  87. edify/library.py +176 -0
  88. edify/licensing/__init__.py +30 -0
  89. edify/licensing/ed25519.py +154 -0
  90. edify/licensing/projects.py +223 -0
  91. edify/licensing/tier.py +172 -0
  92. edify/licensing/token.py +149 -0
  93. edify/paths.py +282 -0
  94. edify/selfinstall.py +244 -0
  95. edify/skills.py +108 -0
  96. edify/tsv.py +109 -0
  97. edify/ui.py +334 -0
  98. edify_agents_cli-0.2.0.dist-info/METADATA +408 -0
  99. edify_agents_cli-0.2.0.dist-info/RECORD +102 -0
  100. edify_agents_cli-0.2.0.dist-info/WHEEL +4 -0
  101. edify_agents_cli-0.2.0.dist-info/entry_points.txt +2 -0
  102. edify_agents_cli-0.2.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,238 @@
1
+ """Markdown with flat YAML frontmatter, parsed with line numbers throughout.
2
+
3
+ Line numbers are the point. Every finding, every citation, and every `--fix` needs
4
+ to say where, and a parser that loses position produces reports nobody can act on.
5
+
6
+ The frontmatter reader deliberately handles scalars and space-separated lists only
7
+ — no nesting, no anchors, no multi-line values. That is the metadata format
8
+ (flat on purpose, so any tool can read it), and a stricter reader is what
9
+ keeps the index a two-line awk script for anyone who wants one.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import re
15
+ from dataclasses import dataclass, field
16
+ from pathlib import Path
17
+
18
+ _HEADING = re.compile(r"^(#{1,6})\s+(.*?)\s*#*\s*$")
19
+ _FENCE = re.compile(r"^\s*(```|~~~)")
20
+ _TABLE_SEP = re.compile(r"^\s*\|?[\s:\-|]+\|[\s:\-|]*$")
21
+
22
+
23
+ @dataclass
24
+ class Row:
25
+ cells: list[str]
26
+ line: int
27
+
28
+ def get(self, index: int) -> str:
29
+ return self.cells[index].strip() if index < len(self.cells) else ""
30
+
31
+
32
+ @dataclass
33
+ class Table:
34
+ headers: list[str]
35
+ rows: list[Row]
36
+ line: int
37
+
38
+ def column(self, *names: str) -> int:
39
+ """The index of the first header matching any of `names`, or -1."""
40
+ lowered = [h.strip().lower() for h in self.headers]
41
+ for name in names:
42
+ target = name.lower()
43
+ for i, header in enumerate(lowered):
44
+ if header == target:
45
+ return i
46
+ for i, header in enumerate(lowered):
47
+ if target in header:
48
+ return i
49
+ return -1
50
+
51
+
52
+ @dataclass
53
+ class Section:
54
+ title: str
55
+ level: int
56
+ line: int
57
+ end_line: int
58
+ lines: list[str] = field(default_factory=list)
59
+ tables: list[Table] = field(default_factory=list)
60
+
61
+ @property
62
+ def text(self) -> str:
63
+ return "\n".join(self.lines)
64
+
65
+ @property
66
+ def key(self) -> str:
67
+ return self.title.strip().lower()
68
+
69
+
70
+ @dataclass
71
+ class Document:
72
+ path: Path
73
+ rel: str
74
+ lines: list[str]
75
+ frontmatter: dict[str, str] = field(default_factory=dict)
76
+ frontmatter_lines: dict[str, int] = field(default_factory=dict)
77
+ frontmatter_end: int = 0
78
+ sections: list[Section] = field(default_factory=list)
79
+ tables: list[Table] = field(default_factory=list)
80
+
81
+ def section(self, *titles: str) -> Section | None:
82
+ wanted = [t.strip().lower() for t in titles]
83
+ for section in self.sections:
84
+ if section.key in wanted:
85
+ return section
86
+ for section in self.sections:
87
+ if any(w in section.key for w in wanted):
88
+ return section
89
+ return None
90
+
91
+ def has_frontmatter(self) -> bool:
92
+ return bool(self.frontmatter) or self.frontmatter_end > 0
93
+
94
+ def list_field(self, key: str) -> list[str]:
95
+ return [v for v in self.frontmatter.get(key, "").split() if v]
96
+
97
+
98
+ def parse_document(path: Path, rel: str | None = None) -> Document:
99
+ text = path.read_text(encoding="utf-8", errors="replace")
100
+ return parse_text(text, path, rel or path.as_posix())
101
+
102
+
103
+ def parse_text(text: str, path: Path, rel: str) -> Document:
104
+ lines = text.splitlines()
105
+ doc = Document(path=path, rel=rel, lines=lines)
106
+
107
+ body_start = 0
108
+ if lines and lines[0].strip() == "---":
109
+ for i in range(1, len(lines)):
110
+ if lines[i].strip() in ("---", "..."):
111
+ body_start = i + 1
112
+ doc.frontmatter_end = i + 1
113
+ break
114
+ for i in range(1, doc.frontmatter_end - 1):
115
+ raw = lines[i]
116
+ if not raw.strip() or raw.lstrip().startswith("#"):
117
+ continue
118
+ key, sep, value = raw.partition(":")
119
+ if not sep:
120
+ continue
121
+ key = key.strip()
122
+ doc.frontmatter[key] = value.strip().strip("\"'")
123
+ doc.frontmatter_lines[key] = i + 1
124
+
125
+ current: Section | None = None
126
+ in_fence = False
127
+ pending_table: list[str] = []
128
+ pending_start = 0
129
+
130
+ def flush_table() -> None:
131
+ nonlocal pending_table, pending_start
132
+ if len(pending_table) >= 2:
133
+ table = _build_table(pending_table, pending_start)
134
+ if table:
135
+ doc.tables.append(table)
136
+ if current is not None:
137
+ current.tables.append(table)
138
+ pending_table = []
139
+ pending_start = 0
140
+
141
+ for index, raw in enumerate(lines[body_start:], start=body_start):
142
+ lineno = index + 1
143
+ if _FENCE.match(raw):
144
+ flush_table()
145
+ in_fence = not in_fence
146
+ if current is not None:
147
+ current.lines.append(raw)
148
+ continue
149
+
150
+ if not in_fence:
151
+ heading = _HEADING.match(raw)
152
+ if heading:
153
+ flush_table()
154
+ if current is not None:
155
+ current.end_line = lineno - 1
156
+ current = Section(
157
+ title=heading.group(2).strip(),
158
+ level=len(heading.group(1)),
159
+ line=lineno,
160
+ end_line=len(lines),
161
+ )
162
+ doc.sections.append(current)
163
+ continue
164
+
165
+ if raw.lstrip().startswith("|"):
166
+ if not pending_table:
167
+ pending_start = lineno
168
+ pending_table.append(raw)
169
+ else:
170
+ flush_table()
171
+
172
+ if current is not None:
173
+ current.lines.append(raw)
174
+
175
+ flush_table()
176
+ if current is not None:
177
+ current.end_line = len(lines)
178
+ return doc
179
+
180
+
181
+ def _build_table(block: list[str], start: int) -> Table | None:
182
+ if len(block) < 2 or not _TABLE_SEP.match(block[1]):
183
+ return None
184
+ headers = _cells(block[0])
185
+ rows = [Row(_cells(line), start + offset) for offset, line in enumerate(block[2:], start=2)]
186
+ return Table(headers=headers, rows=rows, line=start)
187
+
188
+
189
+ def _cells(line: str) -> list[str]:
190
+ stripped = line.strip()
191
+ if stripped.startswith("|"):
192
+ stripped = stripped[1:]
193
+ if stripped.endswith("|"):
194
+ stripped = stripped[:-1]
195
+ return [c.strip() for c in stripped.split("|")]
196
+
197
+
198
+ # ---------------------------------------------------------------------------
199
+ # citations
200
+ # ---------------------------------------------------------------------------
201
+
202
+ # `src/auth/session.ts:88-140`, `src/auth/session.ts:12`, or the literal `new`.
203
+ CITATION = re.compile(
204
+ r"(?P<path>(?:[\w.\-]+/)*[\w.\-]+\.[A-Za-z0-9]{1,10})(?::(?P<start>\d+)(?:-(?P<end>\d+))?)?"
205
+ )
206
+
207
+
208
+ @dataclass(frozen=True)
209
+ class Citation:
210
+ path: str
211
+ start: int | None
212
+ end: int | None
213
+ line: int
214
+ raw: str
215
+
216
+ @property
217
+ def has_range(self) -> bool:
218
+ return self.start is not None
219
+
220
+
221
+ def citations(text: str, first_line: int = 1) -> list[Citation]:
222
+ """Every `file` or `file:line[-line]` in a block of text, with its line."""
223
+ out: list[Citation] = []
224
+ for offset, raw_line in enumerate(text.splitlines()):
225
+ for m in CITATION.finditer(raw_line):
226
+ path = m.group("path")
227
+ if path.startswith("http") or "://" in raw_line[max(0, m.start() - 8) : m.start()]:
228
+ continue
229
+ out.append(
230
+ Citation(
231
+ path=path,
232
+ start=int(m.group("start")) if m.group("start") else None,
233
+ end=int(m.group("end")) if m.group("end") else None,
234
+ line=first_line + offset,
235
+ raw=m.group(0),
236
+ )
237
+ )
238
+ return out
@@ -0,0 +1,50 @@
1
+ """What `edify check` produces.
2
+
3
+ A finding is a line a person can act on: where it is, what rule noticed it, and
4
+ what to do. Findings are reported, never enforced — advisory means advisory —
5
+ and `--exit-code` is how a customer who needs a hard block gets one in
6
+ their own CI, owned by them.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from dataclasses import dataclass
12
+ from enum import Enum
13
+
14
+
15
+ class Level(str, Enum):
16
+ ERROR = "error" # the format contract is broken; a downstream command will misread it
17
+ WARN = "warn" # legal but costly — a whole-file reference, an over-budget skill
18
+ INFO = "info" # worth knowing, never worth stopping for
19
+
20
+
21
+ @dataclass(frozen=True)
22
+ class Finding:
23
+ level: Level
24
+ file: str
25
+ line: int
26
+ code: str
27
+ message: str
28
+ hint: str = ""
29
+
30
+ def render(self) -> str:
31
+ where = f"{self.file}:{self.line}" if self.line else self.file
32
+ out = f"{where}: {self.level.value}: [{self.code}] {self.message}"
33
+ if self.hint:
34
+ out += f"\n {self.hint}"
35
+ return out
36
+
37
+ def as_dict(self) -> dict[str, object]:
38
+ return {
39
+ "level": self.level.value,
40
+ "file": self.file,
41
+ "line": self.line,
42
+ "code": self.code,
43
+ "message": self.message,
44
+ "hint": self.hint,
45
+ }
46
+
47
+
48
+ def sort_findings(findings: list[Finding]) -> list[Finding]:
49
+ order = {Level.ERROR: 0, Level.WARN: 1, Level.INFO: 2}
50
+ return sorted(findings, key=lambda f: (f.file, f.line, order[f.level], f.code))
edify/formats/fix.py ADDED
@@ -0,0 +1,114 @@
1
+ """`edify check --fix` — the mechanical repairs, and only those.
2
+
3
+ Two things are safe to do without judgment: resolve a filename to a line range
4
+ through the graph, and re-sort the skill index. Everything else `check` reports is
5
+ a decision, and a tool that guesses at a decision produces a document that looks
6
+ approved and was not.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import re
12
+ from dataclasses import dataclass
13
+ from pathlib import Path
14
+
15
+ from ..graph.queries import defines, line_range_for
16
+ from ..graph.store import GraphStore
17
+ from ..paths import Layout
18
+ from . import tasks as tasks_format
19
+
20
+
21
+ @dataclass
22
+ class Repair:
23
+ file: str
24
+ line: int
25
+ before: str
26
+ after: str
27
+ what: str
28
+
29
+
30
+ def fix_repository(layout: Layout, store: GraphStore | None) -> list[Repair]:
31
+ repairs: list[Repair] = []
32
+ if store is None or not store.exists():
33
+ return repairs
34
+ if not layout.specs.is_dir():
35
+ return repairs
36
+
37
+ for feature_dir in sorted(p for p in layout.specs.iterdir() if p.is_dir()):
38
+ tasks_path = feature_dir / "tasks.md"
39
+ if tasks_path.is_file():
40
+ repairs.extend(_fix_task_ranges(tasks_path, layout, store))
41
+ return repairs
42
+
43
+
44
+ def _fix_task_ranges(path: Path, layout: Layout, store: GraphStore) -> list[Repair]:
45
+ """Fill an empty `range` cell on an `edit` row from the graph.
46
+
47
+ The range chosen is the span of the file's exported symbols where the file has
48
+ any, which is the honest answer to "which lines matter here" without pretending
49
+ to know which symbol the task means. A file with no symbols is left alone.
50
+ """
51
+ parsed = tasks_format.parse(path, layout.rel(path))
52
+ lines = path.read_text(encoding="utf-8").splitlines()
53
+ repairs: list[Repair] = []
54
+
55
+ for task in parsed.tasks:
56
+ for ref in task.files:
57
+ if ref.action.strip().lower() != "edit" or ref.has_range:
58
+ continue
59
+ span = _span_for(store, ref.path, task)
60
+ if span is None:
61
+ continue
62
+ index = ref.line - 1
63
+ if index < 0 or index >= len(lines):
64
+ continue
65
+ before = lines[index]
66
+ after = _replace_range_cell(before, f"{span[0]}-{span[1]}")
67
+ if after == before:
68
+ continue
69
+ lines[index] = after
70
+ repairs.append(
71
+ Repair(
72
+ file=parsed.rel,
73
+ line=ref.line,
74
+ before=before.strip(),
75
+ after=after.strip(),
76
+ what=f"{task.id}: resolved `{ref.path}` to a line range through the graph",
77
+ )
78
+ )
79
+
80
+ if repairs:
81
+ path.write_text("\n".join(lines) + "\n", encoding="utf-8")
82
+ return repairs
83
+
84
+
85
+ def _span_for(store: GraphStore, file: str, task: tasks_format.Task) -> tuple[int, int] | None:
86
+ # If a step names a symbol that lives in this file, that symbol's range is the
87
+ # right answer and is much narrower than the file's.
88
+ for step in task.steps:
89
+ for token in re.findall(r"`([A-Za-z_][\w.]*)`", step):
90
+ span = line_range_for(store, file, token)
91
+ if span:
92
+ return span
93
+ nodes = [n for n in defines(store, file) if n.kind in ("symbol", "route", "table")]
94
+ if not nodes:
95
+ return None
96
+ first = min(n.line for n in nodes)
97
+ last = max(n.line for n in nodes)
98
+ return first, max(first, last)
99
+
100
+
101
+ def _replace_range_cell(line: str, value: str) -> str:
102
+ """Put `value` in the second cell of a markdown table row, keeping the shape."""
103
+ if not line.strip().startswith("|"):
104
+ return line
105
+ parts = line.split("|")
106
+ if len(parts) < 4:
107
+ return line
108
+ target = parts[2]
109
+ width = len(target)
110
+ replacement = f" {value} "
111
+ if len(replacement) < width:
112
+ replacement = replacement.ljust(width)
113
+ parts[2] = replacement
114
+ return "|".join(parts)
edify/formats/mcp.py ADDED
@@ -0,0 +1,126 @@
1
+ """`.edify/mcp.md` — the server registry, pinned and scoped per role × phase.
2
+
3
+ One table, seven columns, and the two that carry the design are `roles` and
4
+ `phases`. A connected server injects its tool descriptions into every session
5
+ whether or not they are used; scoping per spawn is what stops eight servers across
6
+ a forty-task build becoming a tax paid three hundred and twenty times.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from dataclasses import dataclass, field
12
+ from pathlib import Path
13
+
14
+ from .document import parse_document
15
+ from .skill import ROLES
16
+
17
+ COLUMNS = ("server", "version", "provides", "roles", "phases", "network", "source")
18
+ NETWORKS = ("outbound", "internal", "local")
19
+
20
+
21
+ @dataclass
22
+ class Server:
23
+ name: str
24
+ version: str
25
+ provides: str
26
+ roles: list[str]
27
+ phases: list[str]
28
+ network: str
29
+ source: str
30
+ line: int
31
+
32
+ def scoped_to(self, role: str, phase: str) -> bool:
33
+ """Exact-match lookup. A model never decides which servers load."""
34
+ if "any" not in self.roles and role not in self.roles:
35
+ return False
36
+ if "any" not in self.phases and str(phase) not in self.phases:
37
+ return False
38
+ return True
39
+
40
+
41
+ @dataclass
42
+ class Registry:
43
+ path: Path
44
+ servers: list[Server] = field(default_factory=list)
45
+
46
+ def for_spawn(self, role: str, phase: str) -> list[Server]:
47
+ return [s for s in self.servers if s.scoped_to(role, phase)]
48
+
49
+ def get(self, name: str) -> Server | None:
50
+ for server in self.servers:
51
+ if server.name == name:
52
+ return server
53
+ return None
54
+
55
+
56
+ def parse(path: Path) -> Registry:
57
+ registry = Registry(path=path)
58
+ if not path.is_file():
59
+ return registry
60
+ doc = parse_document(path)
61
+ for table in doc.tables:
62
+ cols = {name: table.column(name) for name in COLUMNS}
63
+ if cols["server"] < 0:
64
+ continue
65
+ for row in table.rows:
66
+ name = row.get(cols["server"]).strip("`")
67
+ if not name or set(name) <= {"-", "—", " "}:
68
+ continue
69
+ registry.servers.append(
70
+ Server(
71
+ name=name,
72
+ version=row.get(cols["version"]) if cols["version"] >= 0 else "",
73
+ provides=row.get(cols["provides"]) if cols["provides"] >= 0 else "",
74
+ roles=_tokens(row.get(cols["roles"])) if cols["roles"] >= 0 else [],
75
+ phases=_tokens(row.get(cols["phases"])) if cols["phases"] >= 0 else [],
76
+ network=row.get(cols["network"]).lower() if cols["network"] >= 0 else "",
77
+ source=row.get(cols["source"]) if cols["source"] >= 0 else "",
78
+ line=row.line,
79
+ )
80
+ )
81
+ return registry
82
+
83
+
84
+ def validate(registry: Registry) -> list[tuple[str, str, int]]:
85
+ problems: list[tuple[str, str, int]] = []
86
+ seen: set[str] = set()
87
+ for server in registry.servers:
88
+ if server.name in seen:
89
+ problems.append(("mcp-duplicate", f"`{server.name}` is declared twice", server.line))
90
+ seen.add(server.name)
91
+ if not server.version or server.version in ("-", "—", "latest", "*"):
92
+ problems.append(
93
+ (
94
+ "mcp-unpinned",
95
+ f"`{server.name}` has no exact version — `edify doctor` cannot check the pin",
96
+ server.line,
97
+ )
98
+ )
99
+ if server.network and server.network not in NETWORKS:
100
+ problems.append(
101
+ ("mcp-bad-network", f"`network: {server.network}` is not one of {'|'.join(NETWORKS)}", server.line)
102
+ )
103
+ for role in server.roles:
104
+ if role not in ROLES and role != "any":
105
+ problems.append(("mcp-bad-role", f"`{server.name}` is scoped to unknown role `{role}`", server.line))
106
+ for phase in server.phases:
107
+ if phase != "any" and not (phase.isdigit() and 0 <= int(phase) <= 7):
108
+ problems.append(("mcp-bad-phase", f"`{server.name}` is scoped to unknown phase `{phase}`", server.line))
109
+ if not server.roles and not server.phases:
110
+ problems.append(
111
+ (
112
+ "mcp-unscoped",
113
+ f"`{server.name}` is scoped to nothing, so it would load nowhere — say `any` if that is meant",
114
+ server.line,
115
+ )
116
+ )
117
+ return problems
118
+
119
+
120
+ def _tokens(value: str) -> list[str]:
121
+ out: list[str] = []
122
+ for token in value.replace(",", " ").split():
123
+ token = token.strip().strip("`*")
124
+ if token and token not in ("-", "—"):
125
+ out.append(token.lower())
126
+ return out
edify/formats/plan.py ADDED
@@ -0,0 +1,151 @@
1
+ """`plan.md` — how, with what, and in what order.
2
+
3
+ Two sections carry the weight and both are checked: the technology decisions, where
4
+ a row without an exact version or a named alternative is not a decision, and the
5
+ context seeds, where a pointer without a line range transfers its cost downstream.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from dataclasses import dataclass, field
11
+ from pathlib import Path
12
+
13
+ from .document import Citation, Document, citations, parse_document
14
+
15
+ EXPECTED_SECTIONS = (
16
+ "milestones",
17
+ "technology decisions",
18
+ "cross-cutting",
19
+ "per-milestone",
20
+ "risks",
21
+ )
22
+
23
+
24
+ @dataclass
25
+ class Decision:
26
+ id: str
27
+ text: str
28
+ version: str
29
+ beat: str
30
+ why: str
31
+ line: int
32
+
33
+ @property
34
+ def is_default(self) -> bool:
35
+ """A row with no alternative is a default, and should say so."""
36
+ lowered = self.beat.strip().lower()
37
+ return lowered in ("", "-", "—", "default", "n/a", "none")
38
+
39
+
40
+ @dataclass
41
+ class Milestone:
42
+ id: str
43
+ delivers: str
44
+ requirements: list[str]
45
+ gate: str
46
+ size: str
47
+ line: int
48
+
49
+
50
+ @dataclass
51
+ class Plan:
52
+ doc: Document
53
+ feature: str = ""
54
+ status: str = ""
55
+ decisions: list[Decision] = field(default_factory=list)
56
+ milestones: list[Milestone] = field(default_factory=list)
57
+ seeds: list[Citation] = field(default_factory=list)
58
+ verification_budget: list[str] = field(default_factory=list)
59
+
60
+ @property
61
+ def rel(self) -> str:
62
+ return self.doc.rel
63
+
64
+
65
+ def parse(path: Path, rel: str | None = None) -> Plan:
66
+ doc = parse_document(path, rel)
67
+ plan = Plan(doc=doc)
68
+ plan.feature = doc.frontmatter.get("feature", "")
69
+ plan.status = doc.frontmatter.get("status", "")
70
+
71
+ section = doc.section("Technology decisions", "Decisions")
72
+ if section:
73
+ for table in section.tables:
74
+ id_col = table.column("#", "id")
75
+ text_col = table.column("decision", "what")
76
+ version_col = table.column("version")
77
+ beat_col = table.column("beat", "alternative", "over")
78
+ why_col = table.column("why", "reason")
79
+ for row in table.rows:
80
+ did = row.get(id_col if id_col >= 0 else 0).strip()
81
+ if not did or set(did) <= {"-", "—", " "}:
82
+ continue
83
+ plan.decisions.append(
84
+ Decision(
85
+ id=did,
86
+ text=row.get(text_col if text_col >= 0 else 1),
87
+ version=row.get(version_col) if version_col >= 0 else "",
88
+ beat=row.get(beat_col) if beat_col >= 0 else "",
89
+ why=row.get(why_col) if why_col >= 0 else "",
90
+ line=row.line,
91
+ )
92
+ )
93
+
94
+ section = doc.section("Milestones")
95
+ if section:
96
+ for table in section.tables:
97
+ id_col = table.column("id", "#")
98
+ delivers_col = table.column("delivers", "goal", "what")
99
+ reqs_col = table.column("requirements covered", "requirements", "covers")
100
+ gate_col = table.column("gate")
101
+ size_col = table.column("size")
102
+ for row in table.rows:
103
+ mid = row.get(id_col if id_col >= 0 else 0).strip()
104
+ if not mid or set(mid) <= {"-", "—", " "}:
105
+ continue
106
+ plan.milestones.append(
107
+ Milestone(
108
+ id=mid,
109
+ delivers=row.get(delivers_col) if delivers_col >= 0 else "",
110
+ requirements=[
111
+ t.strip()
112
+ for t in row.get(reqs_col).replace(",", " ").split()
113
+ if reqs_col >= 0 and t.strip()
114
+ ],
115
+ gate=row.get(gate_col) if gate_col >= 0 else "",
116
+ size=row.get(size_col) if size_col >= 0 else "",
117
+ line=row.line,
118
+ )
119
+ )
120
+
121
+ plan.seeds = _seeds(doc)
122
+ section = doc.section("Cross-cutting")
123
+ if section:
124
+ for line in section.lines:
125
+ lowered = line.lower()
126
+ if "verification budget" in lowered or "model check" in lowered or "proof" in lowered:
127
+ plan.verification_budget.append(line.strip())
128
+ return plan
129
+
130
+
131
+ def _seeds(doc: Document) -> list[Citation]:
132
+ """Every citation under a `Context seeds` heading or block."""
133
+ out: list[Citation] = []
134
+ for section in doc.sections:
135
+ collecting = section.key.startswith("context seeds")
136
+ start = section.line + 1
137
+ for offset, line in enumerate(section.lines):
138
+ stripped = line.strip().lower()
139
+ if stripped.startswith("context seeds"):
140
+ collecting = True
141
+ continue
142
+ if collecting:
143
+ if not line.strip():
144
+ if out and not stripped:
145
+ collecting = collecting and True
146
+ continue
147
+ if line.strip().startswith("#") or stripped.startswith("affected files"):
148
+ collecting = False
149
+ continue
150
+ out.extend(citations(line, first_line=start + offset))
151
+ return out