forktex-fsd 1.0.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.
@@ -0,0 +1,84 @@
1
+ # Copyright (C) 2026 FORKTEX S.R.L.
2
+ #
3
+ # SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-ForkTex-Commercial
4
+ #
5
+ # This file is part of ForkTex FSD.
6
+ #
7
+ # For commercial licensing -- including use in proprietary products, SaaS
8
+ # deployments, or any context where AGPL obligations cannot be met -- you
9
+ # MUST obtain a commercial license from FORKTEX S.R.L. (info@forktex.com).
10
+ #
11
+ # This program is free software: you can redistribute it and/or modify
12
+ # it under the terms of the GNU Affero General Public License as published by
13
+ # the Free Software Foundation, either version 3 of the License, or
14
+ # (at your option) any later version.
15
+ #
16
+ # This program is distributed in the hope that it will be useful,
17
+ # but WITHOUT ANY WARRANTY; without even the implied warranty of
18
+ # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19
+ # GNU Affero General Public License for more details.
20
+ #
21
+ # You should have received a copy of the GNU Affero General Public License
22
+ # along with this program. If not, see <https://www.gnu.org/licenses/>.
23
+
24
+
25
+ """FSD, the ForkTex Standard of Delivery: a software compliance standard and the library that checks it."""
26
+
27
+ from __future__ import annotations
28
+
29
+ import logging
30
+ from importlib.metadata import version as _distribution_version
31
+
32
+ from forktex_fsd.binding import Binding, Bindings, Command, CustomAtom, FileBinding, NotApplicable
33
+ from forktex_fsd.check import AtomCompliance, Compliance, Status, TrackCompliance
34
+ from forktex_fsd.errors import (
35
+ BindingError,
36
+ FsdError,
37
+ InvalidStandardError,
38
+ ProjectNotFoundError,
39
+ UnknownAtomError,
40
+ UsageError,
41
+ )
42
+ from forktex_fsd.project import Project
43
+ from forktex_fsd.report import AtomEvidence, Report
44
+ from forktex_fsd.results import Format, ResultFile
45
+ from forktex_fsd.run import Outcome, RunResult
46
+ from forktex_fsd.standard import Atom, Effect, EvidenceKind, Profile, Standard, Strength, Track
47
+
48
+ __version__ = _distribution_version("forktex-fsd")
49
+
50
+ logging.getLogger("forktex_fsd").addHandler(logging.NullHandler())
51
+
52
+ __all__ = [
53
+ "Atom",
54
+ "AtomCompliance",
55
+ "AtomEvidence",
56
+ "Binding",
57
+ "BindingError",
58
+ "Bindings",
59
+ "Command",
60
+ "Compliance",
61
+ "CustomAtom",
62
+ "Effect",
63
+ "EvidenceKind",
64
+ "FileBinding",
65
+ "Format",
66
+ "FsdError",
67
+ "InvalidStandardError",
68
+ "NotApplicable",
69
+ "Outcome",
70
+ "Profile",
71
+ "Project",
72
+ "ProjectNotFoundError",
73
+ "Report",
74
+ "ResultFile",
75
+ "RunResult",
76
+ "Standard",
77
+ "Status",
78
+ "Strength",
79
+ "Track",
80
+ "TrackCompliance",
81
+ "UnknownAtomError",
82
+ "UsageError",
83
+ "__version__",
84
+ ]
@@ -0,0 +1,28 @@
1
+ # Copyright (C) 2026 FORKTEX S.R.L.
2
+ #
3
+ # SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-ForkTex-Commercial
4
+ #
5
+ # This file is part of ForkTex FSD.
6
+ #
7
+ # For commercial licensing -- including use in proprietary products, SaaS
8
+ # deployments, or any context where AGPL obligations cannot be met -- you
9
+ # MUST obtain a commercial license from FORKTEX S.R.L. (info@forktex.com).
10
+ #
11
+ # This program is free software: you can redistribute it and/or modify
12
+ # it under the terms of the GNU Affero General Public License as published by
13
+ # the Free Software Foundation, either version 3 of the License, or
14
+ # (at your option) any later version.
15
+ #
16
+ # This program is distributed in the hope that it will be useful,
17
+ # but WITHOUT ANY WARRANTY; without even the implied warranty of
18
+ # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19
+ # GNU Affero General Public License for more details.
20
+ #
21
+ # You should have received a copy of the GNU Affero General Public License
22
+ # along with this program. If not, see <https://www.gnu.org/licenses/>.
23
+
24
+ from __future__ import annotations
25
+
26
+ from forktex_fsd._cli import main
27
+
28
+ raise SystemExit(main())
forktex_fsd/_cli.py ADDED
@@ -0,0 +1,249 @@
1
+ # Copyright (C) 2026 FORKTEX S.R.L.
2
+ #
3
+ # SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-ForkTex-Commercial
4
+ #
5
+ # This file is part of ForkTex FSD.
6
+ #
7
+ # For commercial licensing -- including use in proprietary products, SaaS
8
+ # deployments, or any context where AGPL obligations cannot be met -- you
9
+ # MUST obtain a commercial license from FORKTEX S.R.L. (info@forktex.com).
10
+ #
11
+ # This program is free software: you can redistribute it and/or modify
12
+ # it under the terms of the GNU Affero General Public License as published by
13
+ # the Free Software Foundation, either version 3 of the License, or
14
+ # (at your option) any later version.
15
+ #
16
+ # This program is distributed in the hope that it will be useful,
17
+ # but WITHOUT ANY WARRANTY; without even the implied warranty of
18
+ # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19
+ # GNU Affero General Public License for more details.
20
+ #
21
+ # You should have received a copy of the GNU Affero General Public License
22
+ # along with this program. If not, see <https://www.gnu.org/licenses/>.
23
+
24
+ """The `fsd` command: parses arguments, calls `Project`, renders, maps outcomes to exit codes."""
25
+
26
+ from __future__ import annotations
27
+
28
+ import io
29
+ import json
30
+ import sys
31
+ from enum import StrEnum
32
+ from pathlib import Path
33
+
34
+ from forktex.types import BaseValueObject
35
+
36
+ from forktex_fsd import (
37
+ BindingError,
38
+ FsdError,
39
+ Outcome,
40
+ Project,
41
+ ProjectNotFoundError,
42
+ RunResult,
43
+ Standard,
44
+ UsageError,
45
+ __version__,
46
+ )
47
+ from forktex_fsd._render import (
48
+ REPORT_JSON,
49
+ REPORT_MARKDOWN,
50
+ Style,
51
+ render_atom,
52
+ render_custom,
53
+ render_help,
54
+ render_project,
55
+ render_report,
56
+ render_result,
57
+ )
58
+
59
+ EXIT_OK = 0
60
+ EXIT_NOT_MET = 1
61
+ EXIT_INVALID = 2
62
+
63
+
64
+ class Verb(StrEnum):
65
+ """What the command line was asked to do."""
66
+
67
+ OVERVIEW = "overview"
68
+ HELP = "help"
69
+ REPORT = "report"
70
+ RUN = "run"
71
+ VERSION = "version"
72
+
73
+
74
+ class Invocation(BaseValueObject):
75
+ """What the command line was asked to do, and where."""
76
+
77
+ directory: Path
78
+ verb: Verb
79
+ target: str = ""
80
+ args: tuple[str, ...] = ()
81
+ as_json: bool = False
82
+
83
+
84
+ def parse(argv: list[str]) -> Invocation:
85
+ # fsd's own options come before the command; everything after an atom's name
86
+ # belongs to that atom, so `fsd start api --watch` needs no `--`.
87
+ directory = Path.cwd()
88
+ rest = list(argv)
89
+ while rest and rest[0] in ("-C", "-h", "--help", "--version"):
90
+ option = rest.pop(0)
91
+ if option == "--version":
92
+ return Invocation(directory=directory, verb=Verb.VERSION)
93
+ if option != "-C":
94
+ return Invocation(directory=directory, verb=Verb.HELP)
95
+ if not rest:
96
+ raise UsageError("-C needs a directory")
97
+ directory = Path(rest.pop(0))
98
+ if not rest:
99
+ return Invocation(directory=directory, verb=Verb.OVERVIEW)
100
+ word, *tail = rest
101
+ if word == Verb.HELP:
102
+ names = [t for t in tail if t != "--json"]
103
+ return Invocation(
104
+ directory=directory, verb=Verb.HELP, target=names[0] if names else "", as_json="--json" in tail
105
+ )
106
+ if word == Verb.RUN:
107
+ if not tail:
108
+ raise UsageError("usage: fsd run <atom> [args...]")
109
+ word, *tail = tail
110
+ if word == Verb.REPORT:
111
+ if tail:
112
+ raise UsageError("`report` runs every routine atom, so it takes no arguments")
113
+ return Invocation(directory=directory, verb=Verb.REPORT)
114
+ return Invocation(directory=directory, verb=Verb.RUN, target=word, args=tuple(tail))
115
+
116
+
117
+ def terminal_style() -> Style:
118
+ encoding = sys.stdout.encoding or "ascii"
119
+ try:
120
+ "┌─┐—…·".encode(encoding)
121
+ except UnicodeEncodeError:
122
+ return Style(colour=sys.stdout.isatty(), unicode=False)
123
+ return Style(colour=sys.stdout.isatty(), unicode=True)
124
+
125
+
126
+ def _find(invocation: Invocation) -> Project:
127
+ if not invocation.directory.is_dir():
128
+ raise UsageError(f"-C {invocation.directory}: not a directory")
129
+ return Project.find(invocation.directory)
130
+
131
+
132
+ def _find_if_any(invocation: Invocation) -> Project | None:
133
+ try:
134
+ return _find(invocation)
135
+ except ProjectNotFoundError:
136
+ return None
137
+
138
+
139
+ def _exit_for(results: tuple[RunResult, ...]) -> int:
140
+ for result in results:
141
+ print(render_result(result), file=sys.stderr)
142
+ return EXIT_NOT_MET if any(r.outcome is Outcome.FAILED for r in results) else EXIT_OK
143
+
144
+
145
+ def _overview(invocation: Invocation) -> int:
146
+ project = _find_if_any(invocation)
147
+ if project is None:
148
+ print(render_help(Standard.load(), terminal_style()))
149
+ return EXIT_OK
150
+ compliance = project.check()
151
+ print(render_project(compliance, project.root.name, terminal_style()))
152
+ return EXIT_OK if compliance.compliant else EXIT_NOT_MET
153
+
154
+
155
+ def _project_for_help(invocation: Invocation) -> Project | None:
156
+ # Help is what someone reaches for when fsd.toml is broken, so a broken file
157
+ # is reported and the standard shown alone.
158
+ try:
159
+ return _find_if_any(invocation)
160
+ except BindingError as exc:
161
+ print(f"fsd: {exc}; showing the standard alone", file=sys.stderr)
162
+ return None
163
+
164
+
165
+ def _print_json(kind: str, body: dict[str, object]) -> int:
166
+ print(json.dumps({"kind": kind, **body}, indent=2))
167
+ return EXIT_OK
168
+
169
+
170
+ def _help(invocation: Invocation) -> int:
171
+ project = _project_for_help(invocation)
172
+ standard = project.standard if project else Standard.load()
173
+ style = terminal_style()
174
+ if not invocation.target:
175
+ if invocation.as_json:
176
+ return _print_json("standard", standard.model_dump(mode="json"))
177
+ print(render_help(standard, style))
178
+ return EXIT_OK
179
+ track = standard.track(invocation.target)
180
+ if track is not None:
181
+ if invocation.as_json:
182
+ atoms = [a.name for a in standard.in_track(track.name)]
183
+ return _print_json("track", {**track.model_dump(mode="json"), "atoms": atoms})
184
+ print(render_help(standard, style, only=track.name))
185
+ return EXIT_OK
186
+ custom = project.bindings.custom_atom(invocation.target) if project else None
187
+ if custom is not None:
188
+ if invocation.as_json:
189
+ return _print_json("custom", custom.model_dump(mode="json"))
190
+ print(render_custom(custom, style))
191
+ return EXIT_OK
192
+ atom = standard.atom(invocation.target)
193
+ bound = None
194
+ if project is not None:
195
+ compliance = project.check()
196
+ bound = next(a.detail for t in compliance.tracks for a in t.atoms if a.atom == atom.name)
197
+ if invocation.as_json:
198
+ return _print_json("atom", {**atom.model_dump(mode="json"), "binding": bound})
199
+ print(render_atom(atom, bound, style))
200
+ return EXIT_OK
201
+
202
+
203
+ def _version(invocation: Invocation) -> int:
204
+ print(f"fsd {__version__} {Standard.load().version}")
205
+ return EXIT_OK
206
+
207
+
208
+ def _report(invocation: Invocation) -> int:
209
+ project = _find(invocation)
210
+ report = project.report(on_output=sys.stdout.write)
211
+ (project.root / REPORT_JSON).write_text(report.model_dump_json(indent=2) + "\n", encoding="utf-8")
212
+ (project.root / REPORT_MARKDOWN).write_text(report.to_markdown(), encoding="utf-8")
213
+ style = terminal_style()
214
+ print(render_project(report.compliance, project.root.name, style))
215
+ print(render_report(report, style))
216
+ print(f"fsd: wrote {REPORT_JSON} and {REPORT_MARKDOWN}", file=sys.stderr)
217
+ return EXIT_OK if report.passed else EXIT_NOT_MET
218
+
219
+
220
+ def _run(invocation: Invocation) -> int:
221
+ return _exit_for(_find(invocation).run(invocation.target, *invocation.args))
222
+
223
+
224
+ _HANDLERS = {
225
+ Verb.OVERVIEW: _overview,
226
+ Verb.HELP: _help,
227
+ Verb.REPORT: _report,
228
+ Verb.RUN: _run,
229
+ Verb.VERSION: _version,
230
+ }
231
+
232
+
233
+ def _tolerate_unencodable_output() -> None:
234
+ for stream in (sys.stdout, sys.stderr):
235
+ if isinstance(stream, io.TextIOWrapper):
236
+ stream.reconfigure(errors="replace")
237
+
238
+
239
+ def main(argv: list[str] | None = None) -> int:
240
+ _tolerate_unencodable_output()
241
+ try:
242
+ invocation = parse(sys.argv[1:] if argv is None else argv)
243
+ return _HANDLERS[invocation.verb](invocation)
244
+ except (FsdError, OSError) as exc:
245
+ print(f"fsd: {exc}", file=sys.stderr)
246
+ return EXIT_INVALID
247
+
248
+
249
+ __all__ = ["main"]
forktex_fsd/_render.py ADDED
@@ -0,0 +1,342 @@
1
+ # Copyright (C) 2026 FORKTEX S.R.L.
2
+ #
3
+ # SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-ForkTex-Commercial
4
+ #
5
+ # This file is part of ForkTex FSD.
6
+ #
7
+ # For commercial licensing -- including use in proprietary products, SaaS
8
+ # deployments, or any context where AGPL obligations cannot be met -- you
9
+ # MUST obtain a commercial license from FORKTEX S.R.L. (info@forktex.com).
10
+ #
11
+ # This program is free software: you can redistribute it and/or modify
12
+ # it under the terms of the GNU Affero General Public License as published by
13
+ # the Free Software Foundation, either version 3 of the License, or
14
+ # (at your option) any later version.
15
+ #
16
+ # This program is distributed in the hope that it will be useful,
17
+ # but WITHOUT ANY WARRANTY; without even the implied warranty of
18
+ # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19
+ # GNU Affero General Public License for more details.
20
+ #
21
+ # You should have received a copy of the GNU Affero General Public License
22
+ # along with this program. If not, see <https://www.gnu.org/licenses/>.
23
+
24
+ from __future__ import annotations
25
+
26
+ from enum import StrEnum
27
+
28
+ from forktex.types import BaseValueObject
29
+
30
+ from forktex_fsd import Atom, AtomCompliance, Compliance, CustomAtom, Outcome, Profile, Report, RunResult, Standard
31
+ from forktex_fsd.report import duration_text, result_text
32
+
33
+ REPORT_JSON = "fsd-report.json"
34
+ REPORT_MARKDOWN = "fsd-report.md"
35
+ BINDING_WIDTH = 64
36
+ USAGE_HINT = "fsd <atom> [args] fsd <track> fsd report fsd help [name]"
37
+
38
+
39
+ class Colour(StrEnum):
40
+ """An ANSI colour, by its SGR code."""
41
+
42
+ RED = "31"
43
+ GREEN = "32"
44
+ YELLOW = "33"
45
+ DIM = "2"
46
+ BOLD = "1"
47
+
48
+
49
+ class Box(BaseValueObject):
50
+ """The characters a box is drawn with."""
51
+
52
+ top_left: str
53
+ top_right: str
54
+ bottom_left: str
55
+ bottom_right: str
56
+ left_tee: str
57
+ right_tee: str
58
+ horizontal: str
59
+ vertical: str
60
+ dash: str
61
+ ellipsis: str
62
+ dot: str
63
+
64
+
65
+ UNICODE_BOX = Box(
66
+ top_left="┌",
67
+ top_right="┐",
68
+ bottom_left="└",
69
+ bottom_right="┘",
70
+ left_tee="├",
71
+ right_tee="┤",
72
+ horizontal="─",
73
+ vertical="│",
74
+ dash="—",
75
+ ellipsis="…",
76
+ dot="·",
77
+ )
78
+ ASCII_BOX = Box(
79
+ top_left="+",
80
+ top_right="+",
81
+ bottom_left="+",
82
+ bottom_right="+",
83
+ left_tee="+",
84
+ right_tee="+",
85
+ horizontal="-",
86
+ vertical="|",
87
+ dash="-",
88
+ ellipsis="...",
89
+ dot="-",
90
+ )
91
+
92
+
93
+ class Style(BaseValueObject):
94
+ """How output is drawn: with or without colour, with box-drawing characters or plain ASCII."""
95
+
96
+ colour: bool = False
97
+ unicode: bool = True
98
+
99
+ @property
100
+ def box(self) -> Box:
101
+ return UNICODE_BOX if self.unicode else ASCII_BOX
102
+
103
+ def paint(self, text: str, colour: Colour) -> str:
104
+ return f"\033[{colour}m{text}\033[0m" if self.colour else text
105
+
106
+
107
+ PLAIN = Style()
108
+
109
+
110
+ class Cell(BaseValueObject):
111
+ """One table cell, and the colour it is painted in."""
112
+
113
+ text: str
114
+ colour: Colour | None = None
115
+
116
+
117
+ class Align(StrEnum):
118
+ """Where a column's text sits: prose to the left, categories centred, numbers to the right."""
119
+
120
+ LEFT = "left"
121
+ CENTER = "center"
122
+ RIGHT = "right"
123
+
124
+
125
+ class Column(BaseValueObject):
126
+ """A column: its heading, and how its heading and cells are aligned."""
127
+
128
+ title: str
129
+ align: Align = Align.LEFT
130
+
131
+
132
+ GAP = " "
133
+
134
+
135
+ def _place(text: str, width: int, align: Align) -> tuple[str, str]:
136
+ room = width - len(text)
137
+ match align:
138
+ case Align.RIGHT:
139
+ return " " * room, ""
140
+ case Align.CENTER:
141
+ return " " * (room // 2), " " * (room - room // 2)
142
+ case _:
143
+ return "", " " * room
144
+
145
+
146
+ type Section = tuple[str, list[list[Cell]]]
147
+
148
+
149
+ def boxed(title: str, verdict: Cell, header: list[Column], sections: list[Section], style: Style) -> list[str]:
150
+ """A titled box: a header row, then one band per section; as wide as its content."""
151
+ rows = [row for _, section in sections for row in section]
152
+ texts = zip([c.title for c in header], *([c.text for c in row] for row in rows), strict=True)
153
+ widths = [max(len(cell) for cell in column) for column in texts]
154
+ content = sum(widths) + len(GAP) * (len(widths) - 1)
155
+ inner = max(content, len(title) + len(verdict.text) + 4, *(len(name) + 3 for name, _ in sections))
156
+ box = style.box
157
+
158
+ def line(cells: list[Cell]) -> str:
159
+ placed = []
160
+ for cell, width, column in zip(cells, widths, header, strict=True):
161
+ before, after = _place(cell.text, width, column.align)
162
+ # Only the text is painted, so escape codes never count towards a width.
163
+ text = style.paint(cell.text, cell.colour) if cell.colour else cell.text
164
+ placed.append(f"{before}{text}{after}")
165
+ return f"{box.vertical} {GAP.join(placed)}{' ' * (inner - content)} {box.vertical}"
166
+
167
+ rule = box.horizontal
168
+ fill = inner - len(title) - len(verdict.text) - 4
169
+ verdict_text = style.paint(verdict.text, verdict.colour or Colour.BOLD)
170
+ out = [f"{box.top_left}{rule} {style.paint(title, Colour.BOLD)} {rule * fill} {verdict_text} {rule}{box.top_right}"]
171
+ out.append(line([Cell(text=column.title, colour=Colour.DIM) for column in header]))
172
+ for name, section in sections:
173
+ out.append(f"{box.left_tee}{rule} {name} {rule * (inner - len(name) - 1)}{box.right_tee}")
174
+ out += [line(row) for row in section]
175
+ out.append(f"{box.bottom_left}{rule * (inner + 2)}{box.bottom_right}")
176
+ return out
177
+
178
+
179
+ def _shorten(text: str, style: Style) -> str:
180
+ ellipsis = style.box.ellipsis
181
+ return text if len(text) <= BINDING_WIDTH else text[: BINDING_WIDTH - len(ellipsis)] + ellipsis
182
+
183
+
184
+ def _mark(result: AtomCompliance) -> Cell:
185
+ if result.is_failure:
186
+ return Cell(text="FAIL", colour=Colour.RED)
187
+ if result.is_warning:
188
+ return Cell(text="warn", colour=Colour.YELLOW)
189
+ return Cell(text="ok", colour=Colour.GREEN)
190
+
191
+
192
+ def _verdict(passed: bool, yes: str, no: str) -> Cell:
193
+ return Cell(text=yes, colour=Colour.GREEN) if passed else Cell(text=no, colour=Colour.RED)
194
+
195
+
196
+ def _project_row(a: AtomCompliance, style: Style) -> list[Cell]:
197
+ dash = style.box.dash
198
+ return [
199
+ _mark(a),
200
+ Cell(text=a.atom),
201
+ Cell(text="custom" if a.custom else "standard"),
202
+ Cell(text=a.strength.value if a.strength else dash),
203
+ Cell(text=a.status.value),
204
+ Cell(text=_shorten(a.detail, style) if a.detail else dash),
205
+ ]
206
+
207
+
208
+ def render_project(report: Compliance, name: str, style: Style = PLAIN) -> str:
209
+ sections = [(track.track, [_project_row(a, style) for a in track.atoms]) for track in report.tracks]
210
+ dot = style.box.dot
211
+ title = f"{name} {dot} {report.profile} {dot} FSD {report.standard}"
212
+ verdict = _verdict(report.compliant, "compliant", "not compliant")
213
+ header = [
214
+ Column(title="", align=Align.CENTER),
215
+ Column(title="atom"),
216
+ Column(title="kind", align=Align.CENTER),
217
+ Column(title="strength", align=Align.CENTER),
218
+ Column(title="status", align=Align.CENTER),
219
+ Column(title="binding"),
220
+ ]
221
+ box = boxed(title, verdict, header, sections, style)
222
+ return "\n".join([*box, style.paint(USAGE_HINT, Colour.DIM)])
223
+
224
+
225
+ _OUTCOME_COLOURS = {Outcome.PASSED: Colour.GREEN, Outcome.FAILED: Colour.RED, Outcome.SKIPPED: Colour.YELLOW}
226
+
227
+
228
+ def render_report(run: Report, style: Style = PLAIN) -> str:
229
+ dash, dot = style.box.dash, style.box.dot
230
+ sections: dict[str, list[list[Cell]]] = {}
231
+ for e in run.evidence:
232
+ sections.setdefault(e.track, []).append(
233
+ [
234
+ Cell(text=e.outcome.value, colour=_OUTCOME_COLOURS[e.outcome]),
235
+ Cell(text=e.atom),
236
+ Cell(text="custom" if e.custom else "standard"),
237
+ Cell(text=duration_text(e) or dash),
238
+ Cell(text=_shorten(result_text(e), style) if result_text(e) else dash),
239
+ ]
240
+ )
241
+ title = f"{run.project} {dot} report {dot} {run.generated_at:%Y-%m-%d %H:%M:%S} UTC"
242
+ verdict = _verdict(run.passed, "passed", "failed")
243
+ header = [
244
+ Column(title="outcome", align=Align.CENTER),
245
+ Column(title="atom"),
246
+ Column(title="kind", align=Align.CENTER),
247
+ Column(title="time", align=Align.RIGHT),
248
+ Column(title="result"),
249
+ ]
250
+ return "\n".join(boxed(title, verdict, header, list(sections.items()), style))
251
+
252
+
253
+ def _usage(standard: Standard, style: Style) -> list[str]:
254
+ return [
255
+ f"fsd {style.box.dash} the ForkTex Standard of Delivery {standard.version}",
256
+ "",
257
+ "usage:",
258
+ " fsd [-C DIR] this repository: its atoms, bindings and compliance",
259
+ " fsd [-C DIR] <atom> [args...] run an atom; arguments go to its command",
260
+ " fsd [-C DIR] run <atom> [args...]",
261
+ " fsd [-C DIR] <track> run a checks track: its compliance, then every atom",
262
+ f" fsd [-C DIR] report every routine atom, with evidence: {REPORT_JSON}, {REPORT_MARKDOWN}",
263
+ " fsd help [name] [--json] this help, one track, or one atom's full contract",
264
+ "",
265
+ ]
266
+
267
+
268
+ def render_help(standard: Standard, style: Style = PLAIN, only: str | None = None) -> str:
269
+ """The whole standard with the usage, or one track of it with its summary."""
270
+ profiles = list(Profile)
271
+ shown = [t for t in standard.tracks if only in (None, t.name)]
272
+ sections = [
273
+ (
274
+ f"{track.name} {style.box.dot} fsd {track.name}" if track.checks else track.name,
275
+ [
276
+ [
277
+ Cell(text=a.name),
278
+ Cell(text=a.effect.value),
279
+ *(Cell(text=a.strength_for(p).value) for p in profiles),
280
+ Cell(text=_shorten(a.contract, style)),
281
+ ]
282
+ for a in standard.in_track(track.name)
283
+ ],
284
+ )
285
+ for track in shown
286
+ ]
287
+ header = [
288
+ Column(title="atom"),
289
+ Column(title="effect", align=Align.CENTER),
290
+ *(Column(title=p.value, align=Align.CENTER) for p in profiles),
291
+ Column(title="contract"),
292
+ ]
293
+ box = boxed("the standard", Cell(text=standard.version), header, sections, style)
294
+ if only is not None:
295
+ return "\n".join([shown[0].summary, "", *box])
296
+ return "\n".join([*_usage(standard, style), *box])
297
+
298
+
299
+ def render_atom(atom: Atom, bound: str | None, style: Style = PLAIN) -> str:
300
+ """One atom's full contract, and what it is bound to here when there is a project."""
301
+ strengths = ", ".join(f"{p.value} {atom.strength_for(p).value}" for p in Profile)
302
+ lines = [
303
+ f"{atom.name} {style.box.dash} {atom.track}",
304
+ "",
305
+ atom.contract,
306
+ "",
307
+ f"effect {atom.effect.value}",
308
+ f"evidence {atom.evidence.value}",
309
+ f"strength {strengths}",
310
+ ]
311
+ if bound is not None:
312
+ lines.append(f"bound here {bound or style.box.dash}")
313
+ return "\n".join(lines)
314
+
315
+
316
+ def render_custom(custom: CustomAtom, style: Style = PLAIN) -> str:
317
+ """A custom atom: the repository's own, so its command is all there is to say."""
318
+ return "\n".join(
319
+ [
320
+ f"{custom.name} {style.box.dash} {custom.track} (custom atom of this repository)",
321
+ "",
322
+ f"bound here {' ; '.join(custom.command.steps)}",
323
+ ]
324
+ )
325
+
326
+
327
+ def render_result(result: RunResult) -> str:
328
+ detail = f" ({result.detail})" if result.detail else ""
329
+ return f"fsd: {result.atom} {result.outcome.value}{detail}"
330
+
331
+
332
+ __all__ = [
333
+ "REPORT_JSON",
334
+ "REPORT_MARKDOWN",
335
+ "Style",
336
+ "render_atom",
337
+ "render_custom",
338
+ "render_help",
339
+ "render_project",
340
+ "render_report",
341
+ "render_result",
342
+ ]