[IMPL] Check doc and code matching on `hat` CLI

[Doomsk]

Important

This issue is part of unitaryHACK26. You have to be registered to complete this issue.
Learn more about the PR submission process here and about unitaryHACK rules here!

Implementation description

The hat CLI is currently used to create a new project, new files for functions, types and constants. It aims to be used to compile and run/execute code in the near future. Additionally, it also needs to keep track of documentation matching the current state of the code. Read more at the documentation design page.

The idea is that, every time a hat update (or similar) is run, documentation check is done. What it means:

• Check to see whether all code files have their documentation counterparts at the <project-name>/docs/ folder (as .md files)
• Check to see whether the types and function signatures on the code files match the documentation ones
• Update signatures when needed in the documentation
• Remove signatures if code or files if code files do not exist anymore

Examples

1. Example of function signatures

A function signature includes the function name, function type and arguments names and types, such as:

// function at file <project>/src/some-file.hat
fn some-fn (arg1:ty1 arg2:ty2 arg3:ty3) fn-ty { fn-body }

This should produce a markdown description for some-fn at <project>/docs/some-file.md as follows:

# some-file

// Some docstring/documentation can be placed here as a context for the whole file

## some-fn

### Signature

- Name: some-fn
- Type: some-ty
- Kind: function
- Paradigm: classical
- Arguments:

  | Argument | Type | Paradigm |
  | :--- | :--- | :--- |
  | arg1 | ty1 | classical |
  | arg2 | ty2 | classical |
  | arg3 | ty3 | classical |

 
### Documentation

// the programmer should write the docstring/documentation here

2. Example of type signature

A type signature includes the type name, type kind (primitive, struct, enum) and members/fields or variants if applicable, such as:

// type at file <project>/src/hat_types/some-file.hat
type @some-struct-ty {
    m1:ty1
    @m2:@ty2
}

type some-enum-ty {
  named1
  tagged1 { m1:ty1 m2:ty2 }
}

This should produce a markdown description at <project>/docs/hat_types/some-file.md as follows:

# some-file

// Some docstring/documentation can be placed here as a context for the whole file

## @some-struct-ty

### Signature

- Name: @some-struct-ty
- Kind: struct
- Paradigm: quantum
- Members/Fields:

  | Member/Field | Type | Paradigm |
  | :--- | :--- | :--- |
  | m1 | ty1 | classical |
  | @m2 | @ty2 | quantum |


### Documentation

// the programmer should write the docstring/documentation here


## some-enum-ty

### Signature

- Name: some-enum-ty
- Kind: enum
- Paradigm: classical
- Variants:

  | Variant | Type | Paradigm |
  | named1 | Named | classical |
  | tagged1 | Tagged | classical |


### Documentation

// the programmer should write the docstring/documentation here

Expected behavior

• When hat update is executed on terminal, the doc-code matching should run
• The matching code first looks for missing doc files for given code files, creating the doc files if needed
• Then, it parses the code files and collect the
  • function signatures: name and type, arguments names and types
  • types signatures: name and its members signatures (name and type for structs, the variants for enums)
• It parses the doc files looking for the collected signatures on the respective files; if the signature matches, it skips, otherwise it replaces for the new one
• It finally checks any doc file that has no code file counterpart and rename to orphan.<name>.md

Tests

• Check whether code files and docs files are matching (mirrored src/ on docs/)
• Check whether a code signature matches a doc signature: marks true if so, otherwise marks false
• Check whether there are orphan doc files or no doc files for given code files
• Check whether the files content were created as demonstrated in the examples subsection above