mirror of
https://seed.radicle.dev/rad:z6cFWeWpnZNHh9rUW8phgA3b5yGt.git
synced 2026-11-21 18:40:40 +08:00
266 lines
9.3 KiB
Markdown
266 lines
9.3 KiB
Markdown
# Design Documentation
|
|
|
|
In this document we will describe the design of `radicle-surf`. The design of the system will rely
|
|
heavily on [denotational design](todo) and use Haskell syntax (because types are easy to reason about, I'm sorry).
|
|
|
|
`radicle-surf` is a system to describe a file-system in a VCS world. We have the concept of files and directories,
|
|
but these objects can change over time while people iterate on them. Thus, it is a file-system within history and
|
|
we, the user, are viewing the file-system at a particular snapshot. Alongside this, we will wish to take two snapshots
|
|
and view their differences.
|
|
|
|
The stream of consciousness that gave birth to this document started with thinking how the user would interact with
|
|
the system, identifying the key components. This is captured in [User Flow](#user-flow). From there we found nouns that
|
|
represent objects in our system and verbs that represent functions over those objects. This iteratively informed us as
|
|
to what other actions we would need to supply. We would occassionally look at [GitHub](todo) and [Pijul Nest](todo) for
|
|
inspiration, since we would like to imitate the features that they supply, and we ultimately want use one or both of
|
|
these for our backends.
|
|
|
|
## User Flow
|
|
|
|
For the user flow we imagined what it would be like if the user was using a [REPL](todo) to interact with `radicle-surf`.
|
|
The general concept was that the user would enter the repository, build a view of the directory structure, and then
|
|
interact with the directories and files from there (called `browse`).
|
|
```haskell
|
|
repl :: IO ()
|
|
repl = do
|
|
repo <- getRepo
|
|
history <- getHistory label repo -- head is SHA1, tail is rest
|
|
directory <- buildDirectory history
|
|
|
|
forever browse directory
|
|
```
|
|
|
|
But then we thought about what happens when we are in `browse` but we would like to change the history and see that
|
|
file or directory at a different snapshot. This was captured in the pseudo-code below:
|
|
```haskell
|
|
src_foo_bar <- find...
|
|
history' <- historyOf src_foo_bar
|
|
```
|
|
|
|
This information was enough for us to begin the [denotational design](#denotational-design) below.
|
|
|
|
## Denotational Design
|
|
|
|
```haskell
|
|
-- A Label is a name for a directory or a file
|
|
type Label
|
|
μ Label = Text
|
|
|
|
-- A Directory captures its own Label followed by 1 or more
|
|
-- artefacts which can either be sub-directories or files.
|
|
--
|
|
-- An example of "foo/bar.hs" structure:
|
|
-- foo
|
|
-- |-- bar.hs
|
|
--
|
|
-- Would look like:
|
|
-- @("foo", Right ("bar.hs", "module Banana ...") :| [])@
|
|
type Directory
|
|
μ Directory = (Label, NonEmpty (Either Directory File))
|
|
|
|
-- DirectoryContents can either be the special IsRepo object,
|
|
-- a Directory, or a File.
|
|
type DirectoryContents
|
|
μ DirectoryContents = IsRepo | Directory | File
|
|
|
|
-- Opaque representation of repository state directories (e.g. `.git`, `.pijul`)
|
|
-- Those are not browseable, but have to be present at the repo root 'Directory'.
|
|
type IsRepo
|
|
|
|
-- A Directory captures its own Label followed by 1 or more DirectoryContents
|
|
--
|
|
-- An example of "foo/bar.hs" structure:
|
|
-- foo
|
|
-- |-- bar.hs
|
|
--
|
|
-- Would look like:
|
|
-- @("~", IsRepo :| [Directory ("foo", File ("bar.hs", "module Banana ..") :| [])]
|
|
-- where IsRepo is the implicit root of the repository.
|
|
type Directory
|
|
μ Directory = (Label, NonEmpty DirectoryContents)
|
|
|
|
-- A File is its Label and its contents
|
|
type File
|
|
μ File = (Label, ByteString)
|
|
|
|
-- An enumeration of what file-system artefact we're looking at.
|
|
-- Useful for listing a directory and denoting what the label is
|
|
-- corresponding to.
|
|
type SystemType
|
|
μ SystemType
|
|
= IsFile
|
|
| IsDirectory
|
|
|
|
-- A Chnage is an enumeration of how a file has changed.
|
|
-- This is simply used for getting the difference between two
|
|
-- directories.
|
|
type Change
|
|
|
|
-- Constructors of Change - think GADT
|
|
AddLineToFile :: NonEmpty Label -> Location -> ByteString -> Change
|
|
RemoveLineFromFile :: NonEmpty Label -> Location -> Change
|
|
MoveFile :: NonEmpty Label -> NonEmpty Label -> Change
|
|
CreateFile :: NonEmpty Label -> Change
|
|
DeleteFile :: NonEmpty Label -> Change
|
|
|
|
-- A Diff is a set of Changes that were made
|
|
type Diff
|
|
μ Diff = [Change]
|
|
|
|
-- History is an ordered set of @a@s. The reason for it being
|
|
-- polymorphic is that it allows us to choose what set artefact we
|
|
-- want to carry around.
|
|
--
|
|
-- For example:
|
|
-- * In `git` this would be a `Commit`.
|
|
-- * In `pijul` it would be a `Patch`.
|
|
type History a
|
|
μ History = NonEmpty a
|
|
|
|
-- A Repo is a collection of multiple histories.
|
|
-- This would essentially boil down to branches and tags.
|
|
type Repo
|
|
μ Repo a = [History a]
|
|
|
|
-- A Snapshot is a way of converting a History into a Directory.
|
|
-- In other words it gives us a snapshot of the history in the form of a directory.
|
|
type Snapshot a
|
|
μ Snapshot a = History a -> Directory
|
|
|
|
-- For example, we have a `git` snapshot or a `pjul` snapshot.
|
|
type Commit
|
|
type GitSnapshot = Snapshot Commit
|
|
|
|
type Patch
|
|
type PijulSnapshot = Snapshot Patch
|
|
|
|
-- This is piece de resistance of the design! It turns out,
|
|
-- everything is just a Monad after all.
|
|
--
|
|
-- Our code Browser is a stateful computation of what History
|
|
-- we are currently working with and how to get a Snapshot of it.
|
|
type Browser a b
|
|
μ type Browser a b = ReaderT (Snapshot a) (State (History a) b)
|
|
|
|
-- A function that will retrieve a repository given an
|
|
-- identifier. In our case the identifier is opaque to the system.
|
|
getRepo :: Repo -> Repo
|
|
|
|
-- Find a particular History in the Repo. Again, how these things
|
|
-- are equated and found is opaque, but we can think of them as
|
|
-- branch or tag labels.
|
|
getHistory :: Eq a => History a -> Repo a -> Maybe (History a)
|
|
μ getHistory history repo =
|
|
find history (μ repo)
|
|
|
|
-- Find if a particular artefact occurs in 0 or more histories.
|
|
findInHistories :: a -> [History a] -> [History a]
|
|
μ findInHistories a histories =
|
|
filterMaybe (findInHistory a) histories
|
|
|
|
-- Find a particular artefact is in a history.
|
|
findInHistory :: Eq a => a -> History a -> Maybe a
|
|
μ findInHistory a history = find (== a) (μ history)
|
|
|
|
-- A special Label that guarantees a starting point, i.e. ~
|
|
rootLabel :: Label
|
|
μ rootLabel = "~"
|
|
|
|
emptyRepoRoot :: Directory
|
|
μ emptyRepoRoot = (rootLabel, IsRepo :| [])
|
|
|
|
-- Get the difference between two directory views.
|
|
diff :: Directory -> Directory -> Diff
|
|
|
|
-- List the current file or directories in a given Directory view.
|
|
listDirectory :: Directory -> [Label, SystemType]
|
|
μ listDirectory directory = foldMap toLabel $ snd (μ directory)
|
|
where
|
|
toLabel content = case content of
|
|
File (label, _) -> [(label, IsFile)]
|
|
Directory (label, _) -> [(label, IsDirectory)]
|
|
IsRepo -> []
|
|
|
|
fileName :: File -> Label
|
|
μ fileName file = fst (μ file)
|
|
|
|
findFile :: NonEmpty Label -> Directory -> Maybe File
|
|
μ findFile (label :| labels) (Directory (label', contents)) =
|
|
if label == label' then go labels contents else Nothing
|
|
where
|
|
findFileWithLabel :: Foldable f => Label -> f DirectoryContents -> Maybe File
|
|
findFileWithLabel label = find (\artefact -> case content of
|
|
File (fileLabel, _) -> fileLabel == label
|
|
Directory _ -> False
|
|
IsRepo -> False)
|
|
|
|
go :: [Label] -> NonEmpty DirectoryContents -> Just File
|
|
go [] _ = Nothing
|
|
go [label] contents = findMaybe (fileWithLabel label) contents
|
|
go (label:labels) contents = (go labels . snd) <$> find ((label ==) . fst) onlyDirectories contents
|
|
|
|
onlyDirectories :: Foldable f => f DirectoryContents -> [Directory]
|
|
μ onlyDirectories = fmapMaybe (\content -> case content of
|
|
d@(Directory _) -> Just d
|
|
File _ -> Nothing
|
|
IsRepo -> Nothing) . toList
|
|
|
|
getSubDirectories :: Directory -> [Directory]
|
|
μ getSubDirectories directory = foldMap f $ snd (μ directory)
|
|
where
|
|
f :: DirectoryContents -> [Directory]
|
|
f = \case
|
|
d@(Directory _) -> [d]
|
|
File _ -> []
|
|
IsRepo -> []
|
|
|
|
-- Definition elided
|
|
findDirectory :: NonEmpty Label -> Directory -> Maybe Directory
|
|
|
|
-- Definition elided
|
|
fuzzyFind :: Label -> [Directory]
|
|
|
|
-- A Git Snapshot is grabbing the HEAD commit of your History
|
|
-- and turning it into a Directory
|
|
gitSnapshot :: Snapshot Commit
|
|
μ gitSnapshot commits = second (\root -> root <> getDirectoryPtr $ Nel.head commits) emptyRepoRoot
|
|
|
|
-- Opaque and defined by the backend
|
|
getDirectoryPtr :: Commit -> Directory
|
|
|
|
-- A Pijul history is semantically applying the patches in a
|
|
-- topological order and achieving the Directory view.
|
|
pijulHistory :: Snapshot Patch
|
|
μ pijulHistory = foldl pijulMagic emptyRepoRoot
|
|
|
|
-- Opaque and defined by the backend
|
|
pijulMagic :: Patch -> Directory -> Directory
|
|
|
|
-- Get the current History we are working with.
|
|
getHistory :: Browser a (History a)
|
|
μ getHistory = get
|
|
|
|
setHistory :: History a -> Browser a ()
|
|
μ setHistory = put
|
|
|
|
-- Get the current Directory in the Browser
|
|
getDirectory :: Browser a Directory
|
|
μ getDirectory = do
|
|
hist <- get
|
|
applySnapshot <- ask
|
|
pure $ applySnapshot hist
|
|
|
|
-- We modify the history by changing the internal history state.
|
|
switchHistory :: (History a -> History a) -> Browser a b
|
|
μ switchHistory f = modify f
|
|
|
|
-- | Find the suffix of a History.
|
|
findSuffix :: Eq a => a -> History a -> Maybe (History a)
|
|
μ findSuffix a = nonEmpty . Nel.dropWhile (/= a)
|
|
|
|
-- View the history up to a given point by supplying a function to modify
|
|
-- the state. If this operation fails, then the default value is used.
|
|
viewAt :: (History a -> Maybe (History a)) -> History a -> Browser a b
|
|
μ viewAt f def = switchHistory (fromMaybe def . f)
|
|
```
|