forktex-fsd 1.0.0__tar.gz
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-1.0.0/AGENTS.md +30 -0
- forktex_fsd-1.0.0/CHANGELOG.md +66 -0
- forktex_fsd-1.0.0/LICENSE +45 -0
- forktex_fsd-1.0.0/NOTICE +18 -0
- forktex_fsd-1.0.0/PKG-INFO +216 -0
- forktex_fsd-1.0.0/README.md +186 -0
- forktex_fsd-1.0.0/SECURITY.md +37 -0
- forktex_fsd-1.0.0/docs/assets/fsd-banner.png +0 -0
- forktex_fsd-1.0.0/docs/development.md +128 -0
- forktex_fsd-1.0.0/docs/guide.md +355 -0
- forktex_fsd-1.0.0/docs/reference.md +234 -0
- forktex_fsd-1.0.0/fsd.toml +62 -0
- forktex_fsd-1.0.0/poetry.lock +3765 -0
- forktex_fsd-1.0.0/poetry.toml +25 -0
- forktex_fsd-1.0.0/pyproject.toml +144 -0
- forktex_fsd-1.0.0/scripts/clean.py +61 -0
- forktex_fsd-1.0.0/scripts/license_headers.py +103 -0
- forktex_fsd-1.0.0/scripts/release_check.py +123 -0
- forktex_fsd-1.0.0/scripts/smoke.py +68 -0
- forktex_fsd-1.0.0/src/forktex_fsd/__init__.py +84 -0
- forktex_fsd-1.0.0/src/forktex_fsd/__main__.py +28 -0
- forktex_fsd-1.0.0/src/forktex_fsd/_cli.py +249 -0
- forktex_fsd-1.0.0/src/forktex_fsd/_render.py +342 -0
- forktex_fsd-1.0.0/src/forktex_fsd/binding.py +292 -0
- forktex_fsd-1.0.0/src/forktex_fsd/check.py +162 -0
- forktex_fsd-1.0.0/src/forktex_fsd/errors.py +67 -0
- forktex_fsd-1.0.0/src/forktex_fsd/paths.py +40 -0
- forktex_fsd-1.0.0/src/forktex_fsd/project.py +96 -0
- forktex_fsd-1.0.0/src/forktex_fsd/py.typed +0 -0
- forktex_fsd-1.0.0/src/forktex_fsd/report.py +212 -0
- forktex_fsd-1.0.0/src/forktex_fsd/results.py +130 -0
- forktex_fsd-1.0.0/src/forktex_fsd/run.py +298 -0
- forktex_fsd-1.0.0/src/forktex_fsd/standard.py +165 -0
- forktex_fsd-1.0.0/src/forktex_fsd/standard.toml +186 -0
- forktex_fsd-1.0.0/tests/_containers.py +59 -0
- forktex_fsd-1.0.0/tests/conftest.py +118 -0
- forktex_fsd-1.0.0/tests/contract/test_binding.py +211 -0
- forktex_fsd-1.0.0/tests/contract/test_check.py +130 -0
- forktex_fsd-1.0.0/tests/contract/test_cli.py +332 -0
- forktex_fsd-1.0.0/tests/contract/test_render.py +103 -0
- forktex_fsd-1.0.0/tests/contract/test_report.py +240 -0
- forktex_fsd-1.0.0/tests/contract/test_results.py +147 -0
- forktex_fsd-1.0.0/tests/contract/test_run.py +270 -0
- forktex_fsd-1.0.0/tests/contract/test_standard.py +105 -0
- forktex_fsd-1.0.0/tests/contract/test_surface.py +87 -0
- forktex_fsd-1.0.0/tests/platforms/test_linux.py +85 -0
- forktex_fsd-1.0.0/tests/usage/test_a_library.py +145 -0
- forktex_fsd-1.0.0/tests/usage/test_a_service.py +68 -0
- forktex_fsd-1.0.0/tests/usage/test_custom_atoms.py +88 -0
- forktex_fsd-1.0.0/tests/usage/test_the_docs.py +109 -0
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
`forktex-fsd` is a general-purpose software compliance standard and the small
|
|
4
|
+
library + CLI that checks it. It must stay technology-agnostic and free of any
|
|
5
|
+
ForkTex-specific assumption: it judges compliance per track, never a product's
|
|
6
|
+
stage or maturity.
|
|
7
|
+
|
|
8
|
+
- **The standard is data**: `src/forktex_fsd/standard.toml`. Changing an atom, a
|
|
9
|
+
contract or a strength is a change to the standard — bump its `version` and
|
|
10
|
+
record it in `CHANGELOG.md`. Contracts never name a tool.
|
|
11
|
+
- **Built on `forktex`**: errors subclass `forktex.error.AppError`, every model is
|
|
12
|
+
a `forktex.types` value object (pydantic — never a dataclass), the report is a
|
|
13
|
+
wire object, the library logs and never prints.
|
|
14
|
+
- **Layout and direction**: `standard` → `binding` | `results` → `check` | `run`
|
|
15
|
+
→ `report` → `project` → `_render` → `_cli`, one way only; `fsd lint` enforces
|
|
16
|
+
it. `Project` is the one entry point; `_cli` imports only the package's public
|
|
17
|
+
names and `_render`. `forktex_fsd.__all__` is the public surface, pinned by
|
|
18
|
+
`tests/contract/test_surface.py`. Architecture and decisions: `docs/development.md`.
|
|
19
|
+
- `check` must never execute a command. Only checks tracks run as a whole, and
|
|
20
|
+
they may hold only read-only and local atoms; a report runs nothing else.
|
|
21
|
+
- There is no Makefile: `fsd.toml` is the only place a command lives.
|
|
22
|
+
`poetry run fsd assurance`, `fsd security` and `fsd documentation` are the gate and `poetry run fsd build` makes the
|
|
23
|
+
artifact; `poetry run fsd tidy` fixes formatting and headers; bare
|
|
24
|
+
`poetry run fsd` shows every atom and its binding. Line and branch
|
|
25
|
+
coverage are held at 100: every branch here is a rule of the standard, so every
|
|
26
|
+
branch has a test. Tests run real subprocesses, not mocks: a consumer's scenario
|
|
27
|
+
goes in `tests/usage/`, a rule in `tests/contract/`. `fsd assurance` includes the
|
|
28
|
+
custom atom `platforms` (`tests/platforms/`, testcontainers), so it needs Docker;
|
|
29
|
+
`fsd test` alone does not.
|
|
30
|
+
- Publishing is manual: a person runs `poetry run fsd publish`.
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are documented here. The format follows
|
|
4
|
+
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
|
|
5
|
+
[Semantic Versioning](https://semver.org/).
|
|
6
|
+
|
|
7
|
+
## [1.0.0] - 2026-11-18
|
|
8
|
+
|
|
9
|
+
The first version of the standard and its checker.
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- **The FSD standard 1.0**, as data in `standard.toml`: five tracks (operation,
|
|
14
|
+
assurance, security, delivery, documentation) and eighteen technology-agnostic
|
|
15
|
+
atoms. Each atom has a contract, an effect class (read-only, local, host,
|
|
16
|
+
external), an evidence kind (command, file) and a strength per
|
|
17
|
+
profile: `library` (consumed), `application` (installed), `service`
|
|
18
|
+
(deployed). Notable atoms: `status`, the state and recent output of what
|
|
19
|
+
`start` brought up; `install`, the built artifact onto this machine;
|
|
20
|
+
`manual`, the files that show a person or an agent how to start. Assurance,
|
|
21
|
+
security and documentation are checks tracks: their atoms check rather than
|
|
22
|
+
act, so each runs as a whole, and together they are the gate.
|
|
23
|
+
- **`fsd.toml`**: a repository binds each atom to a command, a list of commands
|
|
24
|
+
run in order, `{ run = …, results = [...] }`, one or several files, or
|
|
25
|
+
`{ na = "reason" }`, under the section of the atom's track. Any other name
|
|
26
|
+
under a track is a custom atom of that track: runnable, reported, never
|
|
27
|
+
scored, and run with its track when that track is a checks track. A custom
|
|
28
|
+
atom may not take a track's or a command's name. Paths stay inside
|
|
29
|
+
the repository, and unknown keys are refused. `standard = "1.0"` names the
|
|
30
|
+
version a file was written for; a checker reads every file of its own major
|
|
31
|
+
version up to its own minor. The file is found by searching upward from the
|
|
32
|
+
current directory.
|
|
33
|
+
- **`Project`**, the one entry point. `Project.find()` and `Project.load(root)`
|
|
34
|
+
read `fsd.toml` against the shipped standard.
|
|
35
|
+
- `.check()` returns `Compliance` per track and executes nothing. A missing
|
|
36
|
+
`must` fails its track; a missing `should` is a warning.
|
|
37
|
+
- `.run(name, *args)` executes a binding through the platform shell. Arguments
|
|
38
|
+
go to every command that says `{args}`, or at the end of a single command;
|
|
39
|
+
a list of several without the placeholder takes none. Given a checks track, it checks that
|
|
40
|
+
track's compliance, then runs its atoms in order and stops at the first
|
|
41
|
+
failure. Operation and delivery never run as a whole, so nothing that acts
|
|
42
|
+
beyond the workspace runs unless named.
|
|
43
|
+
- `.report()` runs every routine atom without stopping. It keeps evidence per
|
|
44
|
+
atom (steps, exit code, UTC start, duration, output tail) and reads
|
|
45
|
+
measurements from JUnit XML, Cobertura XML and SARIF. A service's `start`,
|
|
46
|
+
`status` and `stop` run as one bracket, and a process `start` leaves
|
|
47
|
+
running in the background does not hold the report open.
|
|
48
|
+
- Output goes to an `on_output` callback when one is given; the library never
|
|
49
|
+
prints.
|
|
50
|
+
- **The `fsd` command**:
|
|
51
|
+
- bare `fsd` shows the repository as a boxed table;
|
|
52
|
+
- `fsd <atom> [args...]` runs an atom;
|
|
53
|
+
- `fsd <track>` runs one checks track; `fsd assurance`, `fsd security`
|
|
54
|
+
and `fsd documentation` are the gate;
|
|
55
|
+
- `fsd report` writes `fsd-report.json` and `fsd-report.md`;
|
|
56
|
+
- `fsd help [atom] [--json]` shows the standard, or one atom's contract;
|
|
57
|
+
- `-C DIR` starts somewhere else.
|
|
58
|
+
|
|
59
|
+
Exit codes: 0 passed, 1 not met, 2 invalid input.
|
|
60
|
+
- **Built on the `forktex` substrate**:
|
|
61
|
+
- errors are `AppError` subclasses with codes and `details`
|
|
62
|
+
(`BindingError`, `InvalidStandardError`, `ProjectNotFoundError`,
|
|
63
|
+
`UnknownAtomError`, `UsageError`);
|
|
64
|
+
- values are `BaseValueObject`;
|
|
65
|
+
- the report is a wire object, with camelCase JSON and canonical UTC times;
|
|
66
|
+
- logging goes through `forktex.log`, and the library never prints.
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
ForkTex FSD -- Dual License
|
|
2
|
+
|
|
3
|
+
Copyright (C) 2026 FORKTEX S.R.L.
|
|
4
|
+
|
|
5
|
+
This software is licensed under a dual-license model:
|
|
6
|
+
|
|
7
|
+
============================================================================
|
|
8
|
+
|
|
9
|
+
1. OPEN-SOURCE LICENSE -- GNU Affero General Public License v3.0 (AGPL-3.0)
|
|
10
|
+
|
|
11
|
+
You may use, modify, and redistribute this software under the terms of the
|
|
12
|
+
GNU Affero General Public License v3.0 or later, as published by the Free
|
|
13
|
+
Software Foundation. The full license text is available at:
|
|
14
|
+
https://www.gnu.org/licenses/agpl-3.0.html
|
|
15
|
+
|
|
16
|
+
Key obligations under AGPL-3.0:
|
|
17
|
+
- Any modified version MUST be released under the same AGPL-3.0 license.
|
|
18
|
+
- If you run a modified version on a server and let users interact with it
|
|
19
|
+
over a network, you MUST make the complete source code available to those
|
|
20
|
+
users under AGPL-3.0.
|
|
21
|
+
- You MUST preserve all copyright notices and attribution to FORKTEX S.R.L.
|
|
22
|
+
|
|
23
|
+
============================================================================
|
|
24
|
+
|
|
25
|
+
2. COMMERCIAL LICENSE
|
|
26
|
+
|
|
27
|
+
If you wish to use this software without the obligations of AGPL-3.0 --
|
|
28
|
+
for example, to keep your modifications proprietary, to embed this software
|
|
29
|
+
in a closed-source product, or to operate it as part of a commercial service
|
|
30
|
+
without releasing your source code -- you MUST obtain a commercial license
|
|
31
|
+
from FORKTEX S.R.L.
|
|
32
|
+
|
|
33
|
+
Commercial licensing includes, but is not limited to:
|
|
34
|
+
- SaaS / hosted deployments generating revenue
|
|
35
|
+
- Embedding in proprietary products or platforms
|
|
36
|
+
- Redistribution in closed-source form
|
|
37
|
+
- Use by organizations exceeding the AGPL-3.0 compliance scope
|
|
38
|
+
|
|
39
|
+
For commercial licensing inquiries, contact:
|
|
40
|
+
info@forktex.com
|
|
41
|
+
|
|
42
|
+
============================================================================
|
|
43
|
+
|
|
44
|
+
Unless you have obtained a separate commercial license from FORKTEX S.R.L.,
|
|
45
|
+
your use of this software is governed exclusively by the AGPL-3.0 license.
|
forktex_fsd-1.0.0/NOTICE
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
ForkTex FSD
|
|
2
|
+
Copyright (C) 2026 FORKTEX S.R.L.
|
|
3
|
+
|
|
4
|
+
ForkTex FSD is a general-purpose software compliance standard and the tool
|
|
5
|
+
that checks it: technology-agnostic atoms grouped into tracks, bound per
|
|
6
|
+
repository in fsd.toml.
|
|
7
|
+
|
|
8
|
+
This product is dual-licensed:
|
|
9
|
+
|
|
10
|
+
* GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later), or
|
|
11
|
+
* A proprietary commercial license from FORKTEX S.R.L.
|
|
12
|
+
|
|
13
|
+
If you cannot meet the obligations of the AGPL -- including its network-use
|
|
14
|
+
source-disclosure requirement -- you MUST obtain a commercial license before
|
|
15
|
+
using this software. Contact info@forktex.com.
|
|
16
|
+
|
|
17
|
+
Third-party components are distributed under their own licenses; see the
|
|
18
|
+
dependency metadata in pyproject.toml.
|
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: forktex-fsd
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: A general-purpose software compliance standard: technology-agnostic atoms in tracks, bound per repository in fsd.toml, checked and run by one small tool.
|
|
5
|
+
License-Expression: AGPL-3.0-or-later OR LicenseRef-ForkTex-Commercial
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
License-File: NOTICE
|
|
8
|
+
Keywords: compliance,standard,quality-gate,delivery,task-runner,fsd
|
|
9
|
+
Author: FORKTEX
|
|
10
|
+
Author-email: info@forktex.com
|
|
11
|
+
Requires-Python: >=3.14,<4.0
|
|
12
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
19
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
20
|
+
Classifier: Typing :: Typed
|
|
21
|
+
Requires-Dist: forktex (>=1.2,<2)
|
|
22
|
+
Requires-Dist: pydantic (>=2.14)
|
|
23
|
+
Project-URL: Bug Tracker, https://github.com/forktex/forktex-fsd/issues
|
|
24
|
+
Project-URL: Changelog, https://github.com/forktex/forktex-fsd/blob/master/CHANGELOG.md
|
|
25
|
+
Project-URL: Documentation, https://github.com/forktex/forktex-fsd/tree/master/docs
|
|
26
|
+
Project-URL: Homepage, https://forktex.com
|
|
27
|
+
Project-URL: Repository, https://github.com/forktex/forktex-fsd
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
|
|
30
|
+
<p align="center">
|
|
31
|
+
<img src="https://raw.githubusercontent.com/forktex/forktex-fsd/master/docs/assets/fsd-banner.png" alt="forktex-fsd" height="120">
|
|
32
|
+
</p>
|
|
33
|
+
|
|
34
|
+
<p align="center">
|
|
35
|
+
<a href="https://pypi.org/project/forktex-fsd/"><img src="https://img.shields.io/pypi/v/forktex-fsd.svg" alt="PyPI"></a>
|
|
36
|
+
<a href="https://pypi.org/project/forktex-fsd/"><img src="https://img.shields.io/pypi/pyversions/forktex-fsd.svg" alt="Python"></a>
|
|
37
|
+
<a href="https://github.com/forktex/forktex-fsd/blob/master/LICENSE"><img src="https://img.shields.io/pypi/l/forktex-fsd.svg" alt="License"></a>
|
|
38
|
+
</p>
|
|
39
|
+
|
|
40
|
+
# forktex-fsd
|
|
41
|
+
|
|
42
|
+
**FSD**, the ForkTex Standard of Delivery, is a technology-agnostic standard for
|
|
43
|
+
how a repository is set up, checked, built and shipped, and `fsd` is the small
|
|
44
|
+
tool that holds a repository to it.
|
|
45
|
+
|
|
46
|
+
A repository binds the standard's atoms, such as `test`, `audit`, `build` and
|
|
47
|
+
`publish`, to its own commands in one `fsd.toml`. `fsd` reports what is still
|
|
48
|
+
missing, track by track. It runs any atom by name on Linux, macOS or Windows,
|
|
49
|
+
and gates delivery on the tracks that check. It works with any language and any
|
|
50
|
+
toolchain: the standard says what must be true, never which tool makes it so.
|
|
51
|
+
|
|
52
|
+
## Installation
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
uv tool install forktex-fsd # or: pipx install forktex-fsd
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
`fsd` runs on Python 3.14; `uv tool install` brings its own, so the repository
|
|
59
|
+
being checked need not be Python. To use the library, add `forktex-fsd` to your
|
|
60
|
+
project's dependencies.
|
|
61
|
+
|
|
62
|
+
## Quick start
|
|
63
|
+
|
|
64
|
+
Put an `fsd.toml` at the root of the repository:
|
|
65
|
+
|
|
66
|
+
```toml
|
|
67
|
+
# fsd.toml
|
|
68
|
+
standard = "1.0"
|
|
69
|
+
profile = "library"
|
|
70
|
+
|
|
71
|
+
[operation]
|
|
72
|
+
setup = "poetry install"
|
|
73
|
+
|
|
74
|
+
[assurance]
|
|
75
|
+
format = "ruff format --check ."
|
|
76
|
+
lint = ["ruff check .", "lint-imports"]
|
|
77
|
+
test = "pytest -q"
|
|
78
|
+
|
|
79
|
+
[security]
|
|
80
|
+
audit = "pip-audit"
|
|
81
|
+
|
|
82
|
+
[delivery]
|
|
83
|
+
build = "python -m build"
|
|
84
|
+
publish = "twine upload dist/*"
|
|
85
|
+
|
|
86
|
+
[documentation]
|
|
87
|
+
manual = { file = ["README.md", "AGENTS.md"] }
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Then:
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
fsd # every atom, its binding, and compliance per track
|
|
94
|
+
fsd test -k smoke # one atom; what follows goes to its command
|
|
95
|
+
fsd assurance # one track that checks: its compliance, then every atom in it
|
|
96
|
+
fsd report # everything routine, without stopping: fsd-report.json and .md
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## The standard
|
|
100
|
+
|
|
101
|
+
The standard has five **tracks**, and each is judged on its own, so strength on
|
|
102
|
+
one never hides a gap on another. The **profile** says how the software
|
|
103
|
+
reaches its user:
|
|
104
|
+
- a `library` is consumed as a dependency;
|
|
105
|
+
- an `application` is installed onto a machine;
|
|
106
|
+
- a `service` is deployed and operated.
|
|
107
|
+
|
|
108
|
+
The profile decides whether each atom is `must` (a gap fails its track),
|
|
109
|
+
`should` (a gap is a warning) or `na` (it does not apply). Each atom also has an
|
|
110
|
+
**effect**: what running it touches, from `read-only` to `external`.
|
|
111
|
+
|
|
112
|
+
| Track | Atom | It means | Effect | library | application | service |
|
|
113
|
+
|---|---|---|---|:-:|:-:|:-:|
|
|
114
|
+
| **operation** | `setup` | everything needed to build and run it is installed, from a fresh checkout | local | must | must | must |
|
|
115
|
+
| | `start` | it runs locally | local | na | na | must |
|
|
116
|
+
| | `stop` | what `start` brought up is torn down | local | na | na | must |
|
|
117
|
+
| | `status` | whether it is running, with its recent output | read-only | na | na | must |
|
|
118
|
+
| | `clean` | everything the build and the run produced is removed | local | should | should | should |
|
|
119
|
+
| **assurance** ✓ | `format` | the source layout conforms to the project's style | read-only | must | must | must |
|
|
120
|
+
| | `lint` | static analysis finds no defects or unsafe patterns | read-only | must | must | must |
|
|
121
|
+
| | `validate` | the source is statically consistent: types, schemas, contracts | read-only | should | should | should |
|
|
122
|
+
| | `test` | the software's own tests pass | local | must | must | must |
|
|
123
|
+
| | `license` | the licence is declared and applied to every source file | read-only | should | should | should |
|
|
124
|
+
| **security** ✓ | `audit` | dependencies are free of known vulnerabilities | read-only | must | must | must |
|
|
125
|
+
| **delivery** | `build` | the source becomes the deliverable artifact | local | must | must | must |
|
|
126
|
+
| | `install` | the artifact is put onto this machine | host | na | must | na |
|
|
127
|
+
| | `publish` | a versioned artifact is put where consumers fetch it | external | must | should | should |
|
|
128
|
+
| | `deploy` | a version is put into a named environment | external | na | na | must |
|
|
129
|
+
| | `rollback` | an environment returns to its previous version | external | na | na | should |
|
|
130
|
+
| **documentation** ✓ | `manual` | a newcomer, a person or an agent, can start from the repository alone | read-only | must | must | must |
|
|
131
|
+
|
|
132
|
+
✓ A track that checks rather than acts. It runs as a whole, as in
|
|
133
|
+
`fsd assurance`: first its compliance, then its atoms in order, stopping at the
|
|
134
|
+
first failure. Together these tracks are the gate: `fsd assurance`,
|
|
135
|
+
`fsd security`, `fsd documentation`. Operation and delivery act,
|
|
136
|
+
so their atoms run only by name. `fsd help <atom>` prints any atom's full
|
|
137
|
+
contract.
|
|
138
|
+
|
|
139
|
+
## Configuration
|
|
140
|
+
|
|
141
|
+
Each atom is bound under the section of its own track:
|
|
142
|
+
|
|
143
|
+
| Form | Example | Meaning |
|
|
144
|
+
|---|---|---|
|
|
145
|
+
| command | `test = "pytest -q"` | run through the platform shell: `sh`, or `cmd` on Windows |
|
|
146
|
+
| steps | `lint = ["ruff check .", "lint-imports"]` | run in order; the first failure stops the atom |
|
|
147
|
+
| with results | `test = { run = "pytest --junitxml=build/junit.xml", results = ["build/junit.xml"] }` | files `fsd report` reads: JUnit, Cobertura, SARIF |
|
|
148
|
+
| files | `manual = { file = ["README.md", "AGENTS.md"] }` | every file must exist |
|
|
149
|
+
| not applicable | `publish = { na = "an internal tool" }` | the atom does not apply here, and why |
|
|
150
|
+
|
|
151
|
+
Any other name under a track is a **custom atom** of that track, such as
|
|
152
|
+
`migrate` under `[operation]`. It runs by name and is listed, but it never
|
|
153
|
+
counts for compliance. Under a track that checks, it runs with that track.
|
|
154
|
+
Arguments after an atom's name go where its commands say `{args}`, quoted for
|
|
155
|
+
the shell. A single command without the placeholder takes them at its end, and
|
|
156
|
+
a list of several commands without it takes none.
|
|
157
|
+
|
|
158
|
+
## Command line
|
|
159
|
+
|
|
160
|
+
| Command | Does |
|
|
161
|
+
|---|---|
|
|
162
|
+
| `fsd` | The repository: every atom, its binding, compliance per track |
|
|
163
|
+
| `fsd <atom> [args...]` | Runs one atom, standard or custom |
|
|
164
|
+
| `fsd <track>` | Runs a track that checks: its compliance, then its atoms in order |
|
|
165
|
+
| `fsd report` | Runs every routine atom without stopping; writes `fsd-report.json` and `fsd-report.md` |
|
|
166
|
+
| `fsd help [name] [--json]` | The standard, one track, or one atom |
|
|
167
|
+
| `fsd --version` | The version of `fsd` and of its standard |
|
|
168
|
+
| `fsd -C DIR …` | Starts the search for `fsd.toml` in `DIR` instead of the current directory |
|
|
169
|
+
|
|
170
|
+
Exit codes: `0` passed, `1` not compliant or something failed, `2` invalid
|
|
171
|
+
input. Checking executes nothing, so bare `fsd` is safe on a repository you do
|
|
172
|
+
not trust.
|
|
173
|
+
|
|
174
|
+
## Python interface
|
|
175
|
+
|
|
176
|
+
```python
|
|
177
|
+
from forktex_fsd import Project
|
|
178
|
+
|
|
179
|
+
project = Project.find() # the nearest fsd.toml at or above the working directory
|
|
180
|
+
compliance = project.check() # per track; executes nothing
|
|
181
|
+
results = project.run("assurance") # one atom or one track
|
|
182
|
+
report = project.report() # every routine atom, with evidence
|
|
183
|
+
print(compliance.compliant, report.passed)
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
## Documentation
|
|
187
|
+
|
|
188
|
+
| Page | For |
|
|
189
|
+
|---|---|
|
|
190
|
+
| [Guide](https://github.com/forktex/forktex-fsd/blob/master/docs/guide.md) | Complete, copyable setups: a library, a service, any stack, custom atoms, CI, reports, Python |
|
|
191
|
+
| [Reference](https://github.com/forktex/forktex-fsd/blob/master/docs/reference.md) | The standard, `fsd.toml`, the commands, every public name and error |
|
|
192
|
+
|
|
193
|
+
## Versioning
|
|
194
|
+
|
|
195
|
+
Semantic versioning covers:
|
|
196
|
+
- the names in `forktex_fsd.__all__`;
|
|
197
|
+
- the `fsd.toml` format of each standard version;
|
|
198
|
+
- the `fsd` commands and their exit codes;
|
|
199
|
+
- the JSON of `fsd-report.json` and of `fsd help --json`.
|
|
200
|
+
|
|
201
|
+
`fsd.toml` names the standard version it was written for. `fsd` reads any file
|
|
202
|
+
of its own major version up to its own minor, and refuses any other, so a
|
|
203
|
+
change of standard is never silent. Changes are listed in the
|
|
204
|
+
[CHANGELOG](https://github.com/forktex/forktex-fsd/blob/master/CHANGELOG.md).
|
|
205
|
+
|
|
206
|
+
## Contributing
|
|
207
|
+
|
|
208
|
+
Working on `forktex-fsd` itself? Start with
|
|
209
|
+
[`docs/development.md`](https://github.com/forktex/forktex-fsd/blob/master/docs/development.md). Security issues go to the address
|
|
210
|
+
in [SECURITY.md](https://github.com/forktex/forktex-fsd/blob/master/SECURITY.md).
|
|
211
|
+
|
|
212
|
+
## Licence
|
|
213
|
+
|
|
214
|
+
AGPL-3.0-or-later, or a commercial licence from FORKTEX S.R.L.
|
|
215
|
+
(info@forktex.com). See [LICENSE](https://github.com/forktex/forktex-fsd/blob/master/LICENSE) and [NOTICE](https://github.com/forktex/forktex-fsd/blob/master/NOTICE).
|
|
216
|
+
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://raw.githubusercontent.com/forktex/forktex-fsd/master/docs/assets/fsd-banner.png" alt="forktex-fsd" height="120">
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<p align="center">
|
|
6
|
+
<a href="https://pypi.org/project/forktex-fsd/"><img src="https://img.shields.io/pypi/v/forktex-fsd.svg" alt="PyPI"></a>
|
|
7
|
+
<a href="https://pypi.org/project/forktex-fsd/"><img src="https://img.shields.io/pypi/pyversions/forktex-fsd.svg" alt="Python"></a>
|
|
8
|
+
<a href="https://github.com/forktex/forktex-fsd/blob/master/LICENSE"><img src="https://img.shields.io/pypi/l/forktex-fsd.svg" alt="License"></a>
|
|
9
|
+
</p>
|
|
10
|
+
|
|
11
|
+
# forktex-fsd
|
|
12
|
+
|
|
13
|
+
**FSD**, the ForkTex Standard of Delivery, is a technology-agnostic standard for
|
|
14
|
+
how a repository is set up, checked, built and shipped, and `fsd` is the small
|
|
15
|
+
tool that holds a repository to it.
|
|
16
|
+
|
|
17
|
+
A repository binds the standard's atoms, such as `test`, `audit`, `build` and
|
|
18
|
+
`publish`, to its own commands in one `fsd.toml`. `fsd` reports what is still
|
|
19
|
+
missing, track by track. It runs any atom by name on Linux, macOS or Windows,
|
|
20
|
+
and gates delivery on the tracks that check. It works with any language and any
|
|
21
|
+
toolchain: the standard says what must be true, never which tool makes it so.
|
|
22
|
+
|
|
23
|
+
## Installation
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
uv tool install forktex-fsd # or: pipx install forktex-fsd
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
`fsd` runs on Python 3.14; `uv tool install` brings its own, so the repository
|
|
30
|
+
being checked need not be Python. To use the library, add `forktex-fsd` to your
|
|
31
|
+
project's dependencies.
|
|
32
|
+
|
|
33
|
+
## Quick start
|
|
34
|
+
|
|
35
|
+
Put an `fsd.toml` at the root of the repository:
|
|
36
|
+
|
|
37
|
+
```toml
|
|
38
|
+
# fsd.toml
|
|
39
|
+
standard = "1.0"
|
|
40
|
+
profile = "library"
|
|
41
|
+
|
|
42
|
+
[operation]
|
|
43
|
+
setup = "poetry install"
|
|
44
|
+
|
|
45
|
+
[assurance]
|
|
46
|
+
format = "ruff format --check ."
|
|
47
|
+
lint = ["ruff check .", "lint-imports"]
|
|
48
|
+
test = "pytest -q"
|
|
49
|
+
|
|
50
|
+
[security]
|
|
51
|
+
audit = "pip-audit"
|
|
52
|
+
|
|
53
|
+
[delivery]
|
|
54
|
+
build = "python -m build"
|
|
55
|
+
publish = "twine upload dist/*"
|
|
56
|
+
|
|
57
|
+
[documentation]
|
|
58
|
+
manual = { file = ["README.md", "AGENTS.md"] }
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Then:
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
fsd # every atom, its binding, and compliance per track
|
|
65
|
+
fsd test -k smoke # one atom; what follows goes to its command
|
|
66
|
+
fsd assurance # one track that checks: its compliance, then every atom in it
|
|
67
|
+
fsd report # everything routine, without stopping: fsd-report.json and .md
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## The standard
|
|
71
|
+
|
|
72
|
+
The standard has five **tracks**, and each is judged on its own, so strength on
|
|
73
|
+
one never hides a gap on another. The **profile** says how the software
|
|
74
|
+
reaches its user:
|
|
75
|
+
- a `library` is consumed as a dependency;
|
|
76
|
+
- an `application` is installed onto a machine;
|
|
77
|
+
- a `service` is deployed and operated.
|
|
78
|
+
|
|
79
|
+
The profile decides whether each atom is `must` (a gap fails its track),
|
|
80
|
+
`should` (a gap is a warning) or `na` (it does not apply). Each atom also has an
|
|
81
|
+
**effect**: what running it touches, from `read-only` to `external`.
|
|
82
|
+
|
|
83
|
+
| Track | Atom | It means | Effect | library | application | service |
|
|
84
|
+
|---|---|---|---|:-:|:-:|:-:|
|
|
85
|
+
| **operation** | `setup` | everything needed to build and run it is installed, from a fresh checkout | local | must | must | must |
|
|
86
|
+
| | `start` | it runs locally | local | na | na | must |
|
|
87
|
+
| | `stop` | what `start` brought up is torn down | local | na | na | must |
|
|
88
|
+
| | `status` | whether it is running, with its recent output | read-only | na | na | must |
|
|
89
|
+
| | `clean` | everything the build and the run produced is removed | local | should | should | should |
|
|
90
|
+
| **assurance** ✓ | `format` | the source layout conforms to the project's style | read-only | must | must | must |
|
|
91
|
+
| | `lint` | static analysis finds no defects or unsafe patterns | read-only | must | must | must |
|
|
92
|
+
| | `validate` | the source is statically consistent: types, schemas, contracts | read-only | should | should | should |
|
|
93
|
+
| | `test` | the software's own tests pass | local | must | must | must |
|
|
94
|
+
| | `license` | the licence is declared and applied to every source file | read-only | should | should | should |
|
|
95
|
+
| **security** ✓ | `audit` | dependencies are free of known vulnerabilities | read-only | must | must | must |
|
|
96
|
+
| **delivery** | `build` | the source becomes the deliverable artifact | local | must | must | must |
|
|
97
|
+
| | `install` | the artifact is put onto this machine | host | na | must | na |
|
|
98
|
+
| | `publish` | a versioned artifact is put where consumers fetch it | external | must | should | should |
|
|
99
|
+
| | `deploy` | a version is put into a named environment | external | na | na | must |
|
|
100
|
+
| | `rollback` | an environment returns to its previous version | external | na | na | should |
|
|
101
|
+
| **documentation** ✓ | `manual` | a newcomer, a person or an agent, can start from the repository alone | read-only | must | must | must |
|
|
102
|
+
|
|
103
|
+
✓ A track that checks rather than acts. It runs as a whole, as in
|
|
104
|
+
`fsd assurance`: first its compliance, then its atoms in order, stopping at the
|
|
105
|
+
first failure. Together these tracks are the gate: `fsd assurance`,
|
|
106
|
+
`fsd security`, `fsd documentation`. Operation and delivery act,
|
|
107
|
+
so their atoms run only by name. `fsd help <atom>` prints any atom's full
|
|
108
|
+
contract.
|
|
109
|
+
|
|
110
|
+
## Configuration
|
|
111
|
+
|
|
112
|
+
Each atom is bound under the section of its own track:
|
|
113
|
+
|
|
114
|
+
| Form | Example | Meaning |
|
|
115
|
+
|---|---|---|
|
|
116
|
+
| command | `test = "pytest -q"` | run through the platform shell: `sh`, or `cmd` on Windows |
|
|
117
|
+
| steps | `lint = ["ruff check .", "lint-imports"]` | run in order; the first failure stops the atom |
|
|
118
|
+
| with results | `test = { run = "pytest --junitxml=build/junit.xml", results = ["build/junit.xml"] }` | files `fsd report` reads: JUnit, Cobertura, SARIF |
|
|
119
|
+
| files | `manual = { file = ["README.md", "AGENTS.md"] }` | every file must exist |
|
|
120
|
+
| not applicable | `publish = { na = "an internal tool" }` | the atom does not apply here, and why |
|
|
121
|
+
|
|
122
|
+
Any other name under a track is a **custom atom** of that track, such as
|
|
123
|
+
`migrate` under `[operation]`. It runs by name and is listed, but it never
|
|
124
|
+
counts for compliance. Under a track that checks, it runs with that track.
|
|
125
|
+
Arguments after an atom's name go where its commands say `{args}`, quoted for
|
|
126
|
+
the shell. A single command without the placeholder takes them at its end, and
|
|
127
|
+
a list of several commands without it takes none.
|
|
128
|
+
|
|
129
|
+
## Command line
|
|
130
|
+
|
|
131
|
+
| Command | Does |
|
|
132
|
+
|---|---|
|
|
133
|
+
| `fsd` | The repository: every atom, its binding, compliance per track |
|
|
134
|
+
| `fsd <atom> [args...]` | Runs one atom, standard or custom |
|
|
135
|
+
| `fsd <track>` | Runs a track that checks: its compliance, then its atoms in order |
|
|
136
|
+
| `fsd report` | Runs every routine atom without stopping; writes `fsd-report.json` and `fsd-report.md` |
|
|
137
|
+
| `fsd help [name] [--json]` | The standard, one track, or one atom |
|
|
138
|
+
| `fsd --version` | The version of `fsd` and of its standard |
|
|
139
|
+
| `fsd -C DIR …` | Starts the search for `fsd.toml` in `DIR` instead of the current directory |
|
|
140
|
+
|
|
141
|
+
Exit codes: `0` passed, `1` not compliant or something failed, `2` invalid
|
|
142
|
+
input. Checking executes nothing, so bare `fsd` is safe on a repository you do
|
|
143
|
+
not trust.
|
|
144
|
+
|
|
145
|
+
## Python interface
|
|
146
|
+
|
|
147
|
+
```python
|
|
148
|
+
from forktex_fsd import Project
|
|
149
|
+
|
|
150
|
+
project = Project.find() # the nearest fsd.toml at or above the working directory
|
|
151
|
+
compliance = project.check() # per track; executes nothing
|
|
152
|
+
results = project.run("assurance") # one atom or one track
|
|
153
|
+
report = project.report() # every routine atom, with evidence
|
|
154
|
+
print(compliance.compliant, report.passed)
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
## Documentation
|
|
158
|
+
|
|
159
|
+
| Page | For |
|
|
160
|
+
|---|---|
|
|
161
|
+
| [Guide](https://github.com/forktex/forktex-fsd/blob/master/docs/guide.md) | Complete, copyable setups: a library, a service, any stack, custom atoms, CI, reports, Python |
|
|
162
|
+
| [Reference](https://github.com/forktex/forktex-fsd/blob/master/docs/reference.md) | The standard, `fsd.toml`, the commands, every public name and error |
|
|
163
|
+
|
|
164
|
+
## Versioning
|
|
165
|
+
|
|
166
|
+
Semantic versioning covers:
|
|
167
|
+
- the names in `forktex_fsd.__all__`;
|
|
168
|
+
- the `fsd.toml` format of each standard version;
|
|
169
|
+
- the `fsd` commands and their exit codes;
|
|
170
|
+
- the JSON of `fsd-report.json` and of `fsd help --json`.
|
|
171
|
+
|
|
172
|
+
`fsd.toml` names the standard version it was written for. `fsd` reads any file
|
|
173
|
+
of its own major version up to its own minor, and refuses any other, so a
|
|
174
|
+
change of standard is never silent. Changes are listed in the
|
|
175
|
+
[CHANGELOG](https://github.com/forktex/forktex-fsd/blob/master/CHANGELOG.md).
|
|
176
|
+
|
|
177
|
+
## Contributing
|
|
178
|
+
|
|
179
|
+
Working on `forktex-fsd` itself? Start with
|
|
180
|
+
[`docs/development.md`](https://github.com/forktex/forktex-fsd/blob/master/docs/development.md). Security issues go to the address
|
|
181
|
+
in [SECURITY.md](https://github.com/forktex/forktex-fsd/blob/master/SECURITY.md).
|
|
182
|
+
|
|
183
|
+
## Licence
|
|
184
|
+
|
|
185
|
+
AGPL-3.0-or-later, or a commercial licence from FORKTEX S.R.L.
|
|
186
|
+
(info@forktex.com). See [LICENSE](https://github.com/forktex/forktex-fsd/blob/master/LICENSE) and [NOTICE](https://github.com/forktex/forktex-fsd/blob/master/NOTICE).
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Security Policy
|
|
2
|
+
|
|
3
|
+
## Reporting a vulnerability
|
|
4
|
+
|
|
5
|
+
Email **info@forktex.com** with details and, where possible, a reproduction. Please do
|
|
6
|
+
not open a public issue for an unfixed vulnerability.
|
|
7
|
+
|
|
8
|
+
## Supported versions
|
|
9
|
+
|
|
10
|
+
| Version | Supported |
|
|
11
|
+
| --- | --- |
|
|
12
|
+
| 1.x | ✅ |
|
|
13
|
+
|
|
14
|
+
## Scope
|
|
15
|
+
|
|
16
|
+
`forktex-fsd` reads a repository's `fsd.toml` and, when asked through `fsd <atom>`,
|
|
17
|
+
`fsd <track>` or `fsd report`, executes the commands that file names.
|
|
18
|
+
|
|
19
|
+
- **The compliance check executes nothing.** `Project.check()` reads `fsd.toml` and tests
|
|
20
|
+
whether bound files exist; it is safe on an untrusted repository. `fsd <track>`
|
|
21
|
+
runs the check and then the repository's own commands.
|
|
22
|
+
- **Running an atom, a track or a report executes the repository's own commands**, with the caller's privileges and
|
|
23
|
+
in the repository's directory. A string binding runs through the platform shell.
|
|
24
|
+
Running an atom, a track or `fsd report` on a repository you do not trust is running that repository's
|
|
25
|
+
code — exactly as `make` or `npm run` would be.
|
|
26
|
+
- **Atoms beyond the workspace** (`install`, `publish`, `deploy`, `rollback`) belong to no track that runs
|
|
27
|
+
as a whole, and a report leaves them out; they run only when named on their own.
|
|
28
|
+
- **`fsd report` runs every routine atom**, including `setup` and any custom
|
|
29
|
+
atom of a checks track, and reads the result files the bindings name from
|
|
30
|
+
the repository's own tree.
|
|
31
|
+
- **Arguments** passed after an atom's name are quoted for the platform shell.
|
|
32
|
+
Under Windows `cmd`, a `%` in an argument still expands an environment
|
|
33
|
+
variable; `cmd` has no escape for it inside a quoted argument. A binding that wraps
|
|
34
|
+
`{args}` in its own quotes (`"{args}"`) undoes the quoting, and the shell
|
|
35
|
+
expands what is inside: write `{args}` bare.
|
|
36
|
+
- **File and result paths** must stay inside the repository; a symbolic link
|
|
37
|
+
that resolves outside it is treated as missing, never read.
|
|
Binary file
|