keiro-dsl-0.26.0.0: test/topology-machine-proof/TopologyMachineProof.hs
{-# LANGUAGE OverloadedRecordDot #-}
-- | The shared topology machine proof. @keiro-dsl topology@ exports each
-- aggregate's state machine from the specification alone. A conformance suite
-- that compiles generated keiki transducers walks each one with keiki's own
-- accessors ('edgesOut', 'target', 'mode', 'initial', 'isFinal',
-- 'edgeInputName' and each output's wire-constructor name) through
-- 'walkMachine', and 'proveTopologyMachines' fails unless every walked machine
-- equals the exported @machine@ object of its fixture. It also fails when an
-- aggregate whose exported machine ownership is @generated@ is neither compared
-- nor named as excluded with a reason, so a corpus cannot silently drop one.
module TopologyMachineProof
( WalkedMachine,
walkMachine,
MachineProof (..),
proveTopologyMachines,
topologyMachineProofLine,
)
where
import Control.Monad (filterM, forM, forM_, unless, when)
import Data.Aeson (Value (..))
import Data.Aeson qualified as Aeson
import Data.Aeson.Key qualified as Key
import Data.Aeson.KeyMap qualified as KeyMap
import Data.ByteString qualified as BS
import Data.ByteString.Lazy.Char8 qualified as LBS8
import Data.Text (Text)
import Data.Text qualified as T
import Data.Text.Encoding qualified as TE
import Keiki.Core (Edge (..), EdgeMode (..), HsPred, OutTerm (..), SymTransducer (..))
import Keiki.Render.Mermaid (edgeInputName)
import Keiro.Dsl.Parser (parseSourceDocument, renderParseFailure)
import Keiro.Dsl.SemanticContract (checkedSource)
import Keiro.Dsl.SourceIndex (ParsedSourceDocument (..))
import Keiro.Dsl.Topology
import Keiro.Dsl.Validate (Diagnostic (..), Severity (..), renderDiagnostic, validateService)
import Keiro.Dsl.Workspace (oneMemberParsedDocumentWorkspace)
import System.Directory (doesFileExist)
import System.Exit (exitFailure)
import System.FilePath (takeFileName)
import System.IO (hPutStrLn, stderr)
-- | An aggregate name and its walked keiki machine, or why it could not be
-- walked.
type WalkedMachine = (Text, Either Text MachineTopology)
-- | Walk a real generated keiki transducer into the exported shape. The Text
-- argument is the aggregate name, removed from the front of each shown vertex.
-- An edge whose guard names no command constructor is a conformance failure.
walkMachine ::
(Bounded s, Enum s, Show s) =>
Text ->
SymTransducer (HsPred rs ci) rs s ci co ->
WalkedMachine
walkMachine aggregate transducer = (aggregate, walked)
where
walked = do
edges <-
fmap concat . forM vertices $ \vertex ->
forM (zip [0 ..] (transducer.edgesOut vertex)) $ \(edgeIndex, edge) -> do
command <- case edgeInputName edge of
Just name -> Right name
Nothing -> Left (aggregate <> ": edge " <> stateName vertex <> "#" <> T.pack (show edgeIndex) <> " names no command constructor")
pure
MachineEdge
{ source = stateName vertex,
edgeIndex = edgeIndex,
target = stateName edge.target,
mode = case edge.mode of
Live -> MachineLive
ReplayOnly -> MachineReplayOnly,
command = command,
events = [T.pack wireCtor.wcName | OPack _ wireCtor _ <- edge.output]
}
pure
MachineTopology
{ ownership = MachineGenerated,
initial = stateName transducer.initial,
states = [MachineState {name = stateName vertex, terminal = transducer.isFinal vertex} | vertex <- vertices],
edges = edges
}
vertices = [minBound .. maxBound]
stateName vertex =
let shown = T.pack (show vertex)
in maybe shown id (T.stripPrefix aggregate shown)
-- | The exported document and the machines that matched it, in the order
-- they were given.
data MachineProof = MachineProof
{ topology :: ServiceTopology,
compared :: [(Text, MachineTopology)]
}
-- | Export the topology of the fixture (a path relative to the keiro-dsl
-- package, also tried under @keiro-dsl/@), compare every walked machine with
-- the exported @machine@ of its aggregate, and fail on the first difference.
-- The second argument names aggregates deliberately left out, each with its
-- reason; every other aggregate whose exported ownership is @generated@ must be
-- walked. Failures are printed on standard error, so a suite with a
-- machine-readable standard output stays parseable.
proveTopologyMachines :: FilePath -> [(Text, Text)] -> [WalkedMachine] -> IO MachineProof
proveTopologyMachines fixture excluded walked = do
topology <- exportedTopology fixture
compared <- forM walked $ \(aggregate, walkResult) -> do
actual <- either (failWith . T.unpack) pure walkResult
let exported = exportedMachine topology aggregate
actualValue = machineValue actual
when (exported /= Just actualValue) $ do
hPutStrLn stderr ("topology machine proof: " <> fixture <> ": machine " <> T.unpack aggregate <> ": exported machine differs from keiki")
hPutStrLn stderr "exported:"
LBS8.hPutStrLn stderr (maybe "(none)" Aeson.encode exported)
hPutStrLn stderr "keiki:"
LBS8.hPutStrLn stderr (Aeson.encode actualValue)
exitFailure
pure (aggregate, actual)
let walkedNames = map fst walked
excludedNames = map fst excluded
generated = [node.name | node <- topology.nodes, node.kind == AggregateKind, ownershipOf node == Just (String "generated")]
unaccounted = [name | name <- generated, name `notElem` walkedNames, name `notElem` excludedNames]
contradictory = [name | name <- excludedNames, name `elem` walkedNames]
forM_ excluded $ \(name, reason) ->
when (T.null (T.strip reason)) (failWith ("topology machine proof: " <> fixture <> ": exclusion of " <> T.unpack name <> " gives no reason"))
unless (null contradictory) $
failWith ("topology machine proof: " <> fixture <> ": aggregates both compared and excluded: " <> T.unpack (T.intercalate ", " contradictory))
unless (null unaccounted) $
failWith ("topology machine proof: " <> fixture <> ": generated aggregates neither compared nor excluded: " <> T.unpack (T.intercalate ", " unaccounted))
pure MachineProof {topology = topology, compared = compared}
-- | The line each suite prints after a successful proof.
topologyMachineProofLine :: MachineProof -> String
topologyMachineProofLine proof =
"topology machine proof: " <> show count <> (if count == 1 then " aggregate matches keiki" else " aggregates match keiki")
where
count = length proof.compared
ownershipOf :: TopologyNode -> Maybe Value
ownershipOf node = case KeyMap.lookup (Key.fromText "machine") node.details of
Just (Object machine) -> KeyMap.lookup (Key.fromText "ownership") machine
_ -> Nothing
exportedTopology :: FilePath -> IO ServiceTopology
exportedTopology fixture = do
path <- locate fixture
bytes <- BS.readFile path
source <- either (failWith . show) pure (TE.decodeUtf8' bytes)
document <- either (failWith . T.unpack . renderParseFailure) pure (parseSourceDocument path source)
let errors = [diagnostic | diagnostic <- validateService (checkedSource document.parsedSource), diagnostic.severity == Error]
unless (null errors) (failWith (T.unpack (T.unlines (map (renderDiagnostic path) errors))))
workspace <- either (failWith . show) pure (oneMemberParsedDocumentWorkspace path document)
either
(failWith . T.unpack . renderTopologyError)
pure
(buildServiceTopology TopologySingleSource path workspace [(takeFileName path, memberDigest bytes)])
exportedMachine :: ServiceTopology -> Text -> Maybe Value
exportedMachine topology aggregate =
case [node | node <- topology.nodes, node.kind == AggregateKind, node.name == aggregate] of
node : _ -> KeyMap.lookup (Key.fromText "machine") node.details
[] -> Nothing
locate :: FilePath -> IO FilePath
locate relative = do
found <- filterM doesFileExist [relative, "keiro-dsl/" <> relative]
case found of
path : _ -> pure path
[] -> failWith ("topology machine proof: cannot locate " <> relative)
failWith :: String -> IO a
failWith message = hPutStrLn stderr message >> exitFailure