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.
- forktex_fsd/__init__.py +84 -0
- forktex_fsd/__main__.py +28 -0
- forktex_fsd/_cli.py +249 -0
- forktex_fsd/_render.py +342 -0
- forktex_fsd/binding.py +292 -0
- forktex_fsd/check.py +162 -0
- forktex_fsd/errors.py +67 -0
- forktex_fsd/paths.py +40 -0
- forktex_fsd/project.py +96 -0
- forktex_fsd/py.typed +0 -0
- forktex_fsd/report.py +212 -0
- forktex_fsd/results.py +130 -0
- forktex_fsd/run.py +298 -0
- forktex_fsd/standard.py +165 -0
- forktex_fsd/standard.toml +186 -0
- forktex_fsd-1.0.0.dist-info/METADATA +216 -0
- forktex_fsd-1.0.0.dist-info/RECORD +21 -0
- forktex_fsd-1.0.0.dist-info/WHEEL +4 -0
- forktex_fsd-1.0.0.dist-info/entry_points.txt +3 -0
- forktex_fsd-1.0.0.dist-info/licenses/LICENSE +45 -0
- forktex_fsd-1.0.0.dist-info/licenses/NOTICE +18 -0
forktex_fsd/__init__.py
ADDED
|
@@ -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
|
+
]
|
forktex_fsd/__main__.py
ADDED
|
@@ -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
|
+
]
|