@spec artefact_generation_path() :: Path.t()

Returns the Vault path of the directory for Magma.Artefact.Prompt documents.

@spec artefact_generation_path(binary() | [binary()]) :: Path.t()

Constructs a complete path for Magma.Artefact.Prompt documents by joining the specified segments to the artefact_generation_path/0.

@spec artefact_version_path() :: Path.t()

Returns the Vault path of the directory for Magma.Artefact.Version documents.

@spec artefact_version_path(binary() | [binary()]) :: Path.t()

Constructs a complete path for Magma.Artefact.Version documents by joining the specified segments to the artefact_generation_path/0.

@spec concept_path() :: Path.t()

Returns the Vault path of the directory for Magma.Concept documents.

@spec concept_path(binary() | [binary()]) :: Path.t()

Constructs a complete path for Magma.Concept documents by joining the specified segments to the concept_path/0.

@spec create(
  binary(),
  base_vault :: Magma.Vault.BaseVault.theme() | Path.t() | nil,
  keyword()
) ::
  :ok | {:error, any()}

Creates and initializes a new vault.

The project_name is a mandatory parameter. The base_vault specifies the Magma.Vault.BaseVault to be used for initializing the new Magma vault. It can be specified with any of arguments accepted by Magma.Vault.BaseVault.path/1.

Available opts:

• :force (default: false): allow to force creation even if a vault already exists
• :code_sync (default: true): perform an initial code sync/1

Returns :ok if the vault is successfully created or an error tuple if there's an error during the vault creation process.

@spec custom_prompt_template_path() :: Path.t()

Returns the Vault path for the custom prompt template.

@spec document_path(binary() | Path.t()) :: Path.t() | nil

Return the path of an existing document.

When given a path it checks if there actually exists a document at this path. When given a document name (without file extension) it trys to fetch the path from the index.

Returns nil, if no file exists at the given path or no document with the given name is indexed.

@spec document_type(binary() | Path.t()) ::
  {:ok, Magma.Document.type()} | {:error, any()}

Determines the type of the document with the given name_or_path.

The type is determined by the magma_type property within the document's YAML front matter.

Indexes the provided document by its name.

This function indexes a given Magma.Document to enable fast access to it by its name in the document_path/1 function or the load/1 functions of Magma.Documents.

@spec path() :: Path.t()

Returns the application configured path to the vault.

Unless specified otherwise, the path is the docs.magma directory inside the project directory.

It can be changed with in your config.exs file like this:

config :magma,
  dir: "custom_dir"

Note, that this configuration should be environment-independent. Unless you're working on Magma itself, you don't want a test-specific vault, since the vault collects knowledge about your code in its entirety.

@spec path(binary() | [binary()]) :: Path.t()

Constructs a complete path by joining the specified segments to the root vault path/0.

Most of the time one of the more document type-specific functions is more suitable.

Example

Magma.Vault.path("directory")
# returns: "/path/to/project/docs.magma/directory"

Magma.Vault.path(["some", "directory"])
# returns: "/path/to/project/docs.magma/some/directory"

@spec sync(keyword()) :: :ok | {:error, any()}

Synchronizes the Magma.Matter.Module related documents with the latest state of the codebase.

All modules in the code base are determined and for each one the following Magma.Documents created (unless they exist already or the :all option is set):

• a Magma.Concept
• Magma.Artefact.Prompts for all Magma.Artefacts for Magma.Matter.Module (as specified by Magma.Matter.Module.artefacts/0)

Available options:

• :all (default: false) - when set to true also syncs modules for already existing documents
• force (default: false) - when set to true overwrites all existing documents without asking the user

@spec template_path() :: Path.t()

Returns the Vault path of the directory for templates.

@spec template_path(binary() | [binary()]) :: Path.t()

Constructs a complete template path by joining the specified segments to the template_path/0.

Example

Magma.Vault.template_path("some_template.md")
# returns: "/path/to/project/docs.magma/templates/some_template.md"