lawspec 0.24.0 → 0.25.0
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.
- package/CHANGELOG.md +67 -1
- package/README.md +29 -22
- package/UNICODE-LICENSE.txt +39 -0
- package/api.mjs +14 -23
- package/bin/lawspec.mjs +186 -65
- package/build.json +255 -159
- package/builtin-data-names.mjs +73 -0
- package/core.wasm +2 -2
- package/examples/native-payments/clojure/lawspec.json +13 -2
- package/examples/native-payments/csharp/lawspec.json +13 -2
- package/examples/native-payments/elixir/lawspec.json +14 -3
- package/examples/native-payments/erlang/lawspec.json +14 -3
- package/examples/native-payments/fsharp/lawspec.json +14 -3
- package/examples/native-payments/gleam/lawspec.json +14 -3
- package/examples/native-payments/go/lawspec.json +14 -3
- package/examples/native-payments/groovy/lawspec.json +14 -3
- package/examples/native-payments/haskell/lawspec.json +14 -3
- package/examples/native-payments/java/lawspec.json +14 -3
- package/examples/native-payments/javascript/lawspec.json +14 -3
- package/examples/native-payments/kotlin/lawspec.json +14 -3
- package/examples/native-payments/python/lawspec.json +14 -3
- package/examples/native-payments/rust/lawspec.json +14 -3
- package/examples/native-payments/scala/lawspec.json +14 -3
- package/examples/native-payments/swift/lawspec.json +14 -3
- package/examples/native-payments/typescript/lawspec.json +14 -3
- package/examples/packages/orders/lawspec.json +25 -5
- package/examples/packages/orders/orders.lawspec +36 -34
- package/examples/packages/shop-domain/src/domain.lawspec +23 -21
- package/examples/packages/shop-tax-1/src/rates.lawspec +4 -4
- package/examples/packages/shop-tax-2/src/rates.lawspec +5 -4
- package/examples/rc1/authorization-snapshots.lawspec +112 -0
- package/examples/rc1/banner-filenames.lawspec +63 -0
- package/examples/rc1/bit-codec.lawspec +56 -0
- package/examples/rc1/bounded-witness-search.lawspec +144 -0
- package/examples/rc1/conflicting-requirements.lawspec +30 -0
- package/examples/rc1/constructive-witnesses.lawspec +113 -0
- package/examples/rc1/documentary-review.lawspec +42 -0
- package/examples/rc1/empty-domains.lawspec +46 -0
- package/examples/rc1/finite-integer-domains.lawspec +75 -0
- package/examples/rc1/law-metadata.lawspec +29 -0
- package/examples/rc1/native-payments.lawspec +107 -0
- package/examples/rc1/nesting/rrr.lawspec +33 -0
- package/examples/rc1/nesting/rru.lawspec +56 -0
- package/examples/rc1/nesting/rur.lawspec +57 -0
- package/examples/rc1/nesting/ruu.lawspec +77 -0
- package/examples/rc1/nesting/urr.lawspec +52 -0
- package/examples/rc1/nesting/uru.lawspec +72 -0
- package/examples/rc1/nesting/uur.lawspec +73 -0
- package/examples/rc1/nesting/uuu.lawspec +95 -0
- package/examples/rc1/order-workflow.lawspec +126 -0
- package/examples/rc1/parcel-measurements.lawspec +92 -0
- package/examples/rc1/picture-records.lawspec +51 -0
- package/examples/rc1/picture-tuples.lawspec +47 -0
- package/examples/rc1/record-payloads.lawspec +56 -0
- package/examples/rc1/recursive-records.lawspec +64 -0
- package/examples/rc1/refund-conformance.lawspec +44 -0
- package/examples/rc1/refund-policy.lawspec +88 -0
- package/examples/rc1/requirement-composition.lawspec +89 -0
- package/examples/rc1/structural-records.lawspec +53 -0
- package/examples/rc1-authoring.lawspec +56 -0
- package/examples-command.mjs +11 -5
- package/explain.mjs +112 -0
- package/expression-presentation.mjs +333 -0
- package/files.mjs +16 -0
- package/index.d.ts +929 -11
- package/lsp.mjs +231 -0
- package/migrate.mjs +135 -0
- package/migration-bindings.mjs +86 -0
- package/migration-cases.mjs +45 -0
- package/migration-collections.mjs +54 -0
- package/migration-correspondence.mjs +275 -0
- package/migration-generation.mjs +99 -0
- package/migration-laws.mjs +102 -0
- package/migration-records.mjs +166 -0
- package/migration-source.mjs +247 -0
- package/migration-write.mjs +156 -0
- package/native-evidence.mjs +187 -0
- package/native-examples.mjs +8 -1
- package/node-events-reporter.mjs +23 -0
- package/package.json +8 -1
- package/positional-fields.mjs +13 -0
- package/proof.d.ts +35 -0
- package/proof.mjs +174 -0
- package/starter-rc1.lawspec +25 -0
- package/templates.mjs +2 -2
- package/test-command.mjs +107 -35
- package/typed-presentation.mjs +165 -0
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
unit example.refundConformance
|
|
2
|
+
|
|
3
|
+
import example.refunds as policy
|
|
4
|
+
|
|
5
|
+
nativeRefund of type policy.RefundRequest -> policy.RefundDecision
|
|
6
|
+
|
|
7
|
+
law "|native refunds conform to the policy| is
|
|
8
|
+
description:
|
|
9
|
+
"The application's refund decision agrees with the checked policy."
|
|
10
|
+
end
|
|
11
|
+
definition:
|
|
12
|
+
for all (request of type policy.RefundRequest) =>
|
|
13
|
+
nativeRefund request must be policy.refund request
|
|
14
|
+
end
|
|
15
|
+
end
|
|
16
|
+
|
|
17
|
+
references:
|
|
18
|
+
ref function policy.refund
|
|
19
|
+
end
|
|
20
|
+
|
|
21
|
+
expect nativeRefund request = expected
|
|
22
|
+
in table (request, expected):
|
|
23
|
+
row policy.RefundRequest record{capturedAmount = 0, requestedAmount = 0,
|
|
24
|
+
flagged = false}, policy.Approved
|
|
25
|
+
row policy.RefundRequest record{capturedAmount = 0, requestedAmount = 0,
|
|
26
|
+
flagged = true}, policy.Approved
|
|
27
|
+
row policy.RefundRequest record{capturedAmount = 100, requestedAmount = 0,
|
|
28
|
+
flagged = true}, policy.Approved
|
|
29
|
+
row policy.RefundRequest record{capturedAmount = 0, requestedAmount = 1,
|
|
30
|
+
flagged = false}, policy.Rejected
|
|
31
|
+
row policy.RefundRequest record{capturedAmount = 100, requestedAmount = 101,
|
|
32
|
+
flagged = true}, policy.Rejected
|
|
33
|
+
row policy.RefundRequest record{capturedAmount = 100, requestedAmount = 100,
|
|
34
|
+
flagged = true}, policy.ReviewRequired
|
|
35
|
+
row policy.RefundRequest record{capturedAmount = 100, requestedAmount = 1,
|
|
36
|
+
flagged = true}, policy.ReviewRequired
|
|
37
|
+
row policy.RefundRequest record{capturedAmount = 100, requestedAmount = 100,
|
|
38
|
+
flagged = false}, policy.Approved
|
|
39
|
+
row policy.RefundRequest record{capturedAmount = 100, requestedAmount = 99,
|
|
40
|
+
flagged = false}, policy.Approved
|
|
41
|
+
row policy.RefundRequest record{capturedAmount = 9007199254740992,
|
|
42
|
+
requestedAmount = 9007199254740993, flagged = false}, policy.Rejected
|
|
43
|
+
end
|
|
44
|
+
end
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
unit example.refunds
|
|
2
|
+
|
|
3
|
+
type RefundDecision is one of
|
|
4
|
+
| Approved
|
|
5
|
+
| ReviewRequired
|
|
6
|
+
| Rejected
|
|
7
|
+
end type
|
|
8
|
+
|
|
9
|
+
type RefundRequest is a record{
|
|
10
|
+
capturedAmount of type Whole
|
|
11
|
+
requestedAmount of type Whole
|
|
12
|
+
flagged of type Bool
|
|
13
|
+
}
|
|
14
|
+
end type
|
|
15
|
+
|
|
16
|
+
function refund (request of type RefundRequest) -> RefundDecision is
|
|
17
|
+
first matching case of request:
|
|
18
|
+
when record{requestedAmount = 0} then Approved
|
|
19
|
+
when it.requestedAmount > it.capturedAmount then Rejected
|
|
20
|
+
when it.flagged then ReviewRequired
|
|
21
|
+
otherwise Approved
|
|
22
|
+
end case
|
|
23
|
+
end function
|
|
24
|
+
|
|
25
|
+
law "|a zero refund is approved| is
|
|
26
|
+
description:
|
|
27
|
+
"A zero request transfers nothing and needs no review."
|
|
28
|
+
end
|
|
29
|
+
definition:
|
|
30
|
+
for all (capturedAmount of type Whole) (flagged of type Bool) =>
|
|
31
|
+
refund (RefundRequest record{
|
|
32
|
+
capturedAmount = capturedAmount, requestedAmount = 0, flagged = flagged
|
|
33
|
+
}) must be Approved
|
|
34
|
+
end
|
|
35
|
+
end
|
|
36
|
+
end
|
|
37
|
+
|
|
38
|
+
law "|a refund cannot exceed the captured amount| is
|
|
39
|
+
definition:
|
|
40
|
+
for all (request of type RefundRequest) =>
|
|
41
|
+
request.requestedAmount > request.capturedAmount implies
|
|
42
|
+
refund request must be Rejected
|
|
43
|
+
end
|
|
44
|
+
end
|
|
45
|
+
end
|
|
46
|
+
|
|
47
|
+
law "|an eligible flagged refund requires review| is
|
|
48
|
+
definition:
|
|
49
|
+
for all (request of type RefundRequest) =>
|
|
50
|
+
request.requestedAmount > 0 and
|
|
51
|
+
request.requestedAmount <= request.capturedAmount and request.flagged
|
|
52
|
+
implies refund request must be ReviewRequired
|
|
53
|
+
end
|
|
54
|
+
end
|
|
55
|
+
end
|
|
56
|
+
|
|
57
|
+
law "|an eligible unflagged refund is approved| is
|
|
58
|
+
definition:
|
|
59
|
+
for all (request of type RefundRequest) =>
|
|
60
|
+
request.requestedAmount <= request.capturedAmount and not request.flagged
|
|
61
|
+
implies refund request must be Approved
|
|
62
|
+
end
|
|
63
|
+
end
|
|
64
|
+
|
|
65
|
+
expect refund request = expected
|
|
66
|
+
in table (request, expected):
|
|
67
|
+
row RefundRequest record{capturedAmount = 0, requestedAmount = 0, flagged =
|
|
68
|
+
false}, Approved
|
|
69
|
+
row RefundRequest record{capturedAmount = 0, requestedAmount = 0, flagged =
|
|
70
|
+
true}, Approved
|
|
71
|
+
row RefundRequest record{capturedAmount = 100, requestedAmount = 0, flagged
|
|
72
|
+
= true}, Approved
|
|
73
|
+
row RefundRequest record{capturedAmount = 0, requestedAmount = 1, flagged =
|
|
74
|
+
false}, Rejected
|
|
75
|
+
row RefundRequest record{capturedAmount = 100, requestedAmount = 101,
|
|
76
|
+
flagged = true}, Rejected
|
|
77
|
+
row RefundRequest record{capturedAmount = 100, requestedAmount = 100,
|
|
78
|
+
flagged = true}, ReviewRequired
|
|
79
|
+
row RefundRequest record{capturedAmount = 100, requestedAmount = 1, flagged
|
|
80
|
+
= true}, ReviewRequired
|
|
81
|
+
row RefundRequest record{capturedAmount = 100, requestedAmount = 100,
|
|
82
|
+
flagged = false}, Approved
|
|
83
|
+
row RefundRequest record{capturedAmount = 100, requestedAmount = 99, flagged
|
|
84
|
+
= false}, Approved
|
|
85
|
+
row RefundRequest record{capturedAmount = 9007199254740992, requestedAmount
|
|
86
|
+
= 9007199254740993, flagged = false}, Rejected
|
|
87
|
+
end
|
|
88
|
+
end
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
unit example.rc1.requirementComposition
|
|
2
|
+
|
|
3
|
+
import example.rc1.authorizationSnapshots as snapshot
|
|
4
|
+
(Payment, Authorization, AuthorizationState, active, authorizes)
|
|
5
|
+
|
|
6
|
+
law "|each item has a match| (relation of type a -> b -> Bool) is
|
|
7
|
+
definition:
|
|
8
|
+
for all (item of type b) =>
|
|
9
|
+
there exists (witness of type a) such that
|
|
10
|
+
relation witness item
|
|
11
|
+
end
|
|
12
|
+
end
|
|
13
|
+
end
|
|
14
|
+
end
|
|
15
|
+
|
|
16
|
+
function revokedMatch (authorization of type Authorization)
|
|
17
|
+
(payment of type Payment) -> Bool is
|
|
18
|
+
active AllRevoked authorization and authorizes authorization payment
|
|
19
|
+
end function
|
|
20
|
+
|
|
21
|
+
law "|matching and readiness agree| is
|
|
22
|
+
definition:
|
|
23
|
+
(apply law "|each item has a match| authorizes)
|
|
24
|
+
and
|
|
25
|
+
(for all (payment of type Payment) =>
|
|
26
|
+
there exists (authorization of type Authorization
|
|
27
|
+
where active Ready authorization) such that
|
|
28
|
+
authorizes authorization payment
|
|
29
|
+
end
|
|
30
|
+
end)
|
|
31
|
+
end
|
|
32
|
+
|
|
33
|
+
description:
|
|
34
|
+
"Every payment has a matching identity and an active approval when ready."
|
|
35
|
+
end
|
|
36
|
+
end
|
|
37
|
+
|
|
38
|
+
law "|revocation or matching has a complete explanation| is
|
|
39
|
+
definition:
|
|
40
|
+
(must not apply law "|each item has a match| revokedMatch)
|
|
41
|
+
or apply law "|each item has a match| authorizes
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
description:
|
|
45
|
+
"Either revoked approvals cannot cover every payment, or matching succeeds."
|
|
46
|
+
end
|
|
47
|
+
end
|
|
48
|
+
|
|
49
|
+
law "|matching implies ready approval coverage| is
|
|
50
|
+
definition:
|
|
51
|
+
(apply law "|each item has a match| authorizes)
|
|
52
|
+
implies
|
|
53
|
+
(for all (payment of type Payment) =>
|
|
54
|
+
there exists (authorization of type Authorization
|
|
55
|
+
where active Ready authorization) such that
|
|
56
|
+
authorizes authorization payment
|
|
57
|
+
end
|
|
58
|
+
end)
|
|
59
|
+
end
|
|
60
|
+
end
|
|
61
|
+
|
|
62
|
+
law "|payment and approval identities have separate scopes| is
|
|
63
|
+
definition:
|
|
64
|
+
(for all (value of type Payment) =>
|
|
65
|
+
value = FirstPayment or value = SecondPayment
|
|
66
|
+
end)
|
|
67
|
+
and
|
|
68
|
+
(for all (value of type Authorization) =>
|
|
69
|
+
value = FirstApproval or value = SecondApproval
|
|
70
|
+
end)
|
|
71
|
+
end
|
|
72
|
+
end
|
|
73
|
+
|
|
74
|
+
law "|an empty condition does not hide required coverage| is
|
|
75
|
+
definition:
|
|
76
|
+
(for all (authorization of type Authorization where false) =>
|
|
77
|
+
false
|
|
78
|
+
end)
|
|
79
|
+
and
|
|
80
|
+
(there exists (authorization of type Authorization
|
|
81
|
+
where active Ready authorization) such that
|
|
82
|
+
authorizes authorization FirstPayment
|
|
83
|
+
end)
|
|
84
|
+
end
|
|
85
|
+
|
|
86
|
+
rationale:
|
|
87
|
+
"A vacuous first clause leaves the approval requirement in force."
|
|
88
|
+
end
|
|
89
|
+
end
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
unit example.records
|
|
2
|
+
|
|
3
|
+
function double
|
|
4
|
+
(value of type record{
|
|
5
|
+
count of type Integer
|
|
6
|
+
}) -> record{
|
|
7
|
+
count of type Integer
|
|
8
|
+
} is
|
|
9
|
+
record{count = value.count + value.count}
|
|
10
|
+
end function
|
|
11
|
+
|
|
12
|
+
function wrap (value of type a) -> record{wrapped of type a} is
|
|
13
|
+
record{wrapped = value}
|
|
14
|
+
end function
|
|
15
|
+
|
|
16
|
+
law doubles is
|
|
17
|
+
definition:
|
|
18
|
+
for all (value of type record{count of type Integer}) =>
|
|
19
|
+
(double value).count must be value.count + value.count
|
|
20
|
+
end
|
|
21
|
+
end
|
|
22
|
+
|
|
23
|
+
expect double value = expected
|
|
24
|
+
in table (value, expected):
|
|
25
|
+
row record{count = -1}, record{count = -2}
|
|
26
|
+
row record{count = 0}, record{count = 0}
|
|
27
|
+
row record{count = 1}, record{count = 2}
|
|
28
|
+
end
|
|
29
|
+
end
|
|
30
|
+
|
|
31
|
+
law wraps is
|
|
32
|
+
definition:
|
|
33
|
+
(wrap true).wrapped must be true
|
|
34
|
+
end
|
|
35
|
+
end
|
|
36
|
+
|
|
37
|
+
law ordered is
|
|
38
|
+
definition:
|
|
39
|
+
record{a = 1, b = true} must be record{b = true, a = 1}
|
|
40
|
+
end
|
|
41
|
+
end
|
|
42
|
+
|
|
43
|
+
law nested is
|
|
44
|
+
definition:
|
|
45
|
+
record{inner = record{count = 4}}.inner.count must be 4
|
|
46
|
+
end
|
|
47
|
+
end
|
|
48
|
+
|
|
49
|
+
law empty is
|
|
50
|
+
definition:
|
|
51
|
+
record{} must be record{}
|
|
52
|
+
end
|
|
53
|
+
end
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
unit example.rc1
|
|
2
|
+
|
|
3
|
+
function "|adds the values| (a of type Integer) (b of type Integer) -> Integer is
|
|
4
|
+
a + b
|
|
5
|
+
end function
|
|
6
|
+
|
|
7
|
+
law "|addition preserves the inputs| is
|
|
8
|
+
description:
|
|
9
|
+
"Adding two amounts gives their mathematical sum."
|
|
10
|
+
end
|
|
11
|
+
|
|
12
|
+
definition:
|
|
13
|
+
for all (a of type Integer) (b of type Integer) =>
|
|
14
|
+
a `|adds the values| b must be a + b
|
|
15
|
+
end
|
|
16
|
+
end
|
|
17
|
+
|
|
18
|
+
expect "|adds the values| a b = expected
|
|
19
|
+
in table (a, b, expected):
|
|
20
|
+
row -1, 1, 0
|
|
21
|
+
row 0, 0, 0
|
|
22
|
+
row 1, 2, 3
|
|
23
|
+
end
|
|
24
|
+
end
|
|
25
|
+
|
|
26
|
+
type Picture is a record{
|
|
27
|
+
fileName of type Text
|
|
28
|
+
width of type Nat
|
|
29
|
+
}
|
|
30
|
+
end type
|
|
31
|
+
|
|
32
|
+
function picture (width of type Nat) -> Picture is
|
|
33
|
+
Picture record{fileName = "photo.jpg", width = width}
|
|
34
|
+
end function
|
|
35
|
+
|
|
36
|
+
function pictureWidth (picture of type Picture) -> Nat is
|
|
37
|
+
picture.width
|
|
38
|
+
end function
|
|
39
|
+
|
|
40
|
+
type Direction is one of
|
|
41
|
+
| North
|
|
42
|
+
| South
|
|
43
|
+
end type
|
|
44
|
+
|
|
45
|
+
mapping directionText of type Direction -> Text is
|
|
46
|
+
row North, "north"
|
|
47
|
+
row South, "south"
|
|
48
|
+
end mapping
|
|
49
|
+
|
|
50
|
+
function "|picture category| (width of type Nat) -> Text is
|
|
51
|
+
first matching case of width:
|
|
52
|
+
when it < 100 then "small"
|
|
53
|
+
when it < 1000 then "medium"
|
|
54
|
+
otherwise "large"
|
|
55
|
+
end case
|
|
56
|
+
end function
|
package/examples-command.mjs
CHANGED
|
@@ -14,6 +14,9 @@ export async function generateExamples(options) {
|
|
|
14
14
|
if (options.example !== "payments") throw new Error(`Unknown example: ${options.example}`);
|
|
15
15
|
return exportNativePayments(options, selected);
|
|
16
16
|
}
|
|
17
|
+
const projectRoot = process.cwd();
|
|
18
|
+
const outputDirectory = options.output || "example_artifacts";
|
|
19
|
+
const root = await safePath(projectRoot, outputDirectory);
|
|
17
20
|
const directory = new URL("./examples/specs/", import.meta.url);
|
|
18
21
|
const sources = await Promise.all(
|
|
19
22
|
(await readdir(directory))
|
|
@@ -27,7 +30,11 @@ export async function generateExamples(options) {
|
|
|
27
30
|
const compiler = await createCompiler();
|
|
28
31
|
const artifacts = [];
|
|
29
32
|
for (const target of selected) {
|
|
30
|
-
|
|
33
|
+
// The bundled specs catalog is the frozen 0.24 migration corpus.
|
|
34
|
+
// Canonical native projects are exported by exportNativePayments above.
|
|
35
|
+
const result = await compiler.migrationBaseline({
|
|
36
|
+
schemaVersion: 5, from: '0.24', includeGeneration: true,
|
|
37
|
+
languageProfile: '1.0-rc.1', verification: {layers: ['proof','exhaustive','property','examples','runtime','model']},
|
|
31
38
|
sources,
|
|
32
39
|
target,
|
|
33
40
|
machineBits: options.machineBits ?? 64,
|
|
@@ -39,10 +46,8 @@ export async function generateExamples(options) {
|
|
|
39
46
|
});
|
|
40
47
|
artifacts.push(result.files);
|
|
41
48
|
}
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
options.output || "example_artifacts",
|
|
45
|
-
);
|
|
49
|
+
// Recheck the destination after compilation, before creating output files.
|
|
50
|
+
await safePath(projectRoot, outputDirectory);
|
|
46
51
|
await mkdir(root, { recursive: true });
|
|
47
52
|
const plans = [];
|
|
48
53
|
for (let i = 0; i < selected.length; i++) {
|
|
@@ -53,6 +58,7 @@ export async function generateExamples(options) {
|
|
|
53
58
|
await applyWrites(plans);
|
|
54
59
|
return plans.map((plan, i) => ({
|
|
55
60
|
target: selected[i],
|
|
61
|
+
sourceLanguageProfile: '0.24',
|
|
56
62
|
directory: plan.root,
|
|
57
63
|
files: artifacts[i].map((f) => ({ path: f.path, ownership: f.ownership, placement: f.placement })),
|
|
58
64
|
changes: plan.changes.length,
|
package/explain.mjs
ADDED
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
// Generated from templates/npm/explain.mjs by lawspec-dev generate. Do not edit.
|
|
2
|
+
// All presentations read the same typed law and its evidence. No view parses
|
|
3
|
+
// business wording or changes an obligation.
|
|
4
|
+
import { createTypePresentation } from './typed-presentation.mjs';
|
|
5
|
+
|
|
6
|
+
export const explanationViews = ['developer', 'business', 'formal', 'evidence'];
|
|
7
|
+
const presentationProposition = ({ typeName, expressionText }, inputs) => function proposition(assertion, business = false, scope = inputs) {
|
|
8
|
+
const term = expression => expressionText(expression, scope);
|
|
9
|
+
const recurse = (body, wording = business) => proposition(body, wording, scope);
|
|
10
|
+
switch (assertion.kind) {
|
|
11
|
+
case 'equal': return `${term(assertion.left)} ${business ? 'must be' : '='} ${term(assertion.right)}`;
|
|
12
|
+
case 'implies': return business
|
|
13
|
+
? `If ${term(assertion.guard)}, then ${recurse(assertion.body, true)}`
|
|
14
|
+
: `(${term(assertion.guard)}) implies (${recurse(assertion.body)})`;
|
|
15
|
+
case 'all': return assertion.items.map(a => `(${recurse(a)})`).join(' and ');
|
|
16
|
+
case 'not': {
|
|
17
|
+
// The compiler's ordinary negation/conjunction representation also
|
|
18
|
+
// expresses disjunction and implications with proposition premises.
|
|
19
|
+
const items = assertion.body.kind === 'all' ? assertion.body.items : [];
|
|
20
|
+
if (items.length > 1 && items.every(item => item.kind === 'not'))
|
|
21
|
+
return items.map(item => `(${recurse(item.body)})`).join(' or ');
|
|
22
|
+
if (items.length === 2 && items[1].kind === 'not') return business
|
|
23
|
+
? `If (${recurse(items[0], true)}), then (${recurse(items[1].body, true)})`
|
|
24
|
+
: `(${recurse(items[0])}) implies (${recurse(items[1].body)})`;
|
|
25
|
+
return business && assertion.body.kind === 'exists'
|
|
26
|
+
? recurse(assertion.body, true).replace(/^There must exist/, 'There must not exist')
|
|
27
|
+
: `${business ? 'Must not' : 'not'} (${recurse(assertion.body, false)})`;
|
|
28
|
+
}
|
|
29
|
+
case 'forall':
|
|
30
|
+
case 'exists': {
|
|
31
|
+
const universal = assertion.kind === 'forall';
|
|
32
|
+
const binder = `${assertion.binder.name} of type ${typeName(assertion.binder.type)}`;
|
|
33
|
+
const nested = new Map([...scope, [assertion.binder.id, assertion.binder.name]]);
|
|
34
|
+
const restrictions = assertion.predicates.map(p => expressionText(p, nested));
|
|
35
|
+
const restricted = restrictions.length ? ` where ${restrictions.join(' and ')}` : '';
|
|
36
|
+
if (business) return `${universal ? 'For every' : 'There must exist'} ${binder}${restricted}, ${proposition(assertion.body, true, nested)}`;
|
|
37
|
+
return `${universal ? 'for all' : 'there exists'} (${binder}${restricted}) ${universal ? '=>' : 'such that'}\n${proposition(assertion.body, false, nested)}\nend`;
|
|
38
|
+
}
|
|
39
|
+
default: throw new Error(`Unsupported typed assertion ${assertion.kind}`);
|
|
40
|
+
}
|
|
41
|
+
};
|
|
42
|
+
export function explainLaw(law, result, view = 'developer') {
|
|
43
|
+
if (!explanationViews.includes(view)) throw new Error(`Choose --view ${explanationViews.join('|')}`);
|
|
44
|
+
const presentation = createTypePresentation(result);
|
|
45
|
+
const { typeName, expressionText, valueText } = presentation;
|
|
46
|
+
const examples = law.examples ?? [];
|
|
47
|
+
const scope = new Map(law.inputs.map(input => [input.id, input.name]));
|
|
48
|
+
const proposition = presentationProposition(presentation, scope);
|
|
49
|
+
const evidence = (result.evidence ?? []).filter(e => e.declaration === law.id);
|
|
50
|
+
const quantifiers = law.inputs.map(input => `${input.name} of type ${typeName(input.type)}`);
|
|
51
|
+
const restrictions = law.inputs.flatMap(input => input.predicates.map(p => expressionText(p, scope)));
|
|
52
|
+
const metadata = law.metadata ?? {};
|
|
53
|
+
const references = law.references ?? [];
|
|
54
|
+
const witnesses = law.harness?.witnesses ?? [];
|
|
55
|
+
const searches = law.harness?.searches ?? [];
|
|
56
|
+
const strategies = [
|
|
57
|
+
...witnesses.map(witness => `Configured witness (not completed evidence): definition.${witness.path.join('.')} = ${expressionText(witness.expression, scope)}`),
|
|
58
|
+
...searches.map(search => `Configured search (not completed evidence): definition.${search.path.join('.')} uses ${search.strategy}`),
|
|
59
|
+
];
|
|
60
|
+
const documentary = [metadata.id === undefined ? '' : `Requirement: ${metadata.id}`,
|
|
61
|
+
metadata.owner === undefined ? '' : `Owner: ${metadata.owner}`,
|
|
62
|
+
...references.map(reference => `Reference: ${referenceText(reference)}`)].filter(Boolean);
|
|
63
|
+
let text;
|
|
64
|
+
if (view === 'evidence') text = evidence.length
|
|
65
|
+
? evidence.map(e => `${e.status.toUpperCase()}: ${e.reason}`+(e.nativeEvidence?'\n'+nativeEvidenceText(e):'')).join('\n')
|
|
66
|
+
: 'No completed evidence has been supplied for this law.';
|
|
67
|
+
else if (view === 'business') text = [...documentary, law.description,
|
|
68
|
+
quantifiers.length ? `For every ${quantifiers.join(' and ')}` : '',
|
|
69
|
+
restrictions.length ? `When ${restrictions.join(' and ')}` : '',
|
|
70
|
+
proposition(law.assertion, true), law.rationale ? `Reason: ${law.rationale}` : ''].filter(Boolean).join('\n');
|
|
71
|
+
else if (view === 'formal') text = [quantifiers.length ? `for all (${quantifiers.join(') (')}) =>` : '',
|
|
72
|
+
restrictions.length ? `(${restrictions.join(' and ')}) implies` : '',
|
|
73
|
+
proposition(law.assertion), ...(quantifiers.length ? ['end'] : [])].filter(Boolean).join('\n');
|
|
74
|
+
else text = [law.id, ...documentary, ...law.trace, ...strategies,
|
|
75
|
+
...(quantifiers.length ? [`Inputs: ${quantifiers.join('; ')}`] : []),
|
|
76
|
+
...(restrictions.length ? [`Restrictions: ${restrictions.join(' and ')}`] : []), proposition(law.assertion),
|
|
77
|
+
`Source: ${law.location.file}:${law.location.line}:${law.location.column}`,
|
|
78
|
+
`Examples: ${examples.length}`,
|
|
79
|
+
...examples.flatMap(example => {
|
|
80
|
+
const locals = new Map([...scope, ...example.bindings.map(binding => [binding.id, binding.name])]);
|
|
81
|
+
return [`example ${JSON.stringify(example.name)}`,
|
|
82
|
+
...example.bindings.map(binding => ` ${binding.name} = ${valueText(binding.value, locals)}`),
|
|
83
|
+
...example.expectations.map(expectation => ` expect ${proposition(expectation, false, locals)}`)];
|
|
84
|
+
})].join('\n');
|
|
85
|
+
if(view==='developer')for(const item of evidence)if(item.nativeEvidence)text+='\n'+nativeEvidenceText(item);
|
|
86
|
+
if (view === 'evidence' && strategies.length) text += '\n' + strategies.join('\n');
|
|
87
|
+
return { view, law: law.id, metadata, references, witnesses, searches, examples, inputs: law.inputs, assertion: law.assertion, evidence, text };
|
|
88
|
+
}
|
|
89
|
+
function referenceText(reference) {
|
|
90
|
+
if (typeof reference === 'string') return reference;
|
|
91
|
+
if (reference.kind === 'external') return `${reference.name ? `${reference.name}: ` : ''}${reference.resource}`;
|
|
92
|
+
const selector = reference.selector;
|
|
93
|
+
const section = selector?.kind === 'named-reference' ? ` references.${selector.name}` : selector ? ` ${selector.kind}` : '';
|
|
94
|
+
const raw = reference.target.name;
|
|
95
|
+
// Built-in laws retain legacy source names internally; present their
|
|
96
|
+
// canonical phrase spelling just as ordinary authored names are presented.
|
|
97
|
+
const name = raw.startsWith('"|') || /^\p{L}[\p{L}\p{N}_]*$/u.test(raw)
|
|
98
|
+
? raw : `"|${raw.replace(/[\\|]/g, '\\$&')}|`;
|
|
99
|
+
return `ref ${reference.kind} ${reference.target.unit}.${name}${section}`;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
export function nativeEvidenceText(item){
|
|
103
|
+
if(!item.nativeEvidence)return '';
|
|
104
|
+
const summary=item.nativeEvidence;
|
|
105
|
+
return [`Native conformance: ${summary.status}; search completeness: ${summary.searchCompleteness}`,
|
|
106
|
+
...summary.observations.map(row=>`${row.target} (${row.root}): ${row.outcome}; ${row.freshness}`+
|
|
107
|
+
(row.attempt?`; seed ${row.attempt.seed}; ${row.attempt.at}`:'')+`; ${row.reason}`),
|
|
108
|
+
...summary.observations.flatMap(row=>(row.attempt?.tests??[]).filter(test=>test.status==='failed')
|
|
109
|
+
.map(test=>`${test.name}: ${test.reason??test.failure??test.message??'native test failed'}`)),
|
|
110
|
+
...summary.observations.filter(row=>row.attempt?.invocation.output)
|
|
111
|
+
.map(row=>'Native invocation output (scoped to that invocation):\n'+row.attempt.invocation.output)].join('\n');
|
|
112
|
+
}
|