Implement Check doc and code matching on hat CLI

[kwyip]

Pull Request: Add hat update documentation sync

Closes #111

What changed

This PR adds hat update so H-hat projects can keep docs/ in sync with src/ without doing the boring bookkeeping by hand.

• Creates missing Markdown docs for .hat files by mirroring src/ into docs/.
• Parses function, struct, and enum signatures from code.
• Compares those signatures with the matching Markdown docs.
• Updates stale or missing ### Signature sections while keeping existing documentation text.
• Removes signature sections when the matching code item is gone.
• As requested, also renames doc files without a source counterpart to orphan.<name>.md.
• Fix some installation problems.

Tests added

The CLI test coverage now checks these main behaviors:

1. mirrored src/ → docs/ file creation;
2. signature match and mismatch handling;
3. missing docs and orphan docs;
4. generated Markdown matching the function and type examples from the issue.

Tests Mirrored Update Demo

hhat_lang_demo_3.mp4

Notes

I also tightened the CI/pre-commit setup.

Generative AI/LLM disclosure

Code and Logic Architecture/Design:

• The code and logic architecture/design contain no generative AI/LLM
• The code and logic architecture/design are partially performed by generative AI/LLM
  • 99% performed by the author(s)
• The code and logic architecture/design are fully performed by generative AI/LLM

Code content:

• The code contains no generative AI/LLM work
• The code is partially written by generative AI/L
  • 69% performed by the author(s)
• The code is fully written by generative AI/LLM

Code review:

• The code review contains no generative AI/LLM
• The code review is partially done by generative AI/LLM
  • X% performed by the author(s)
• The code review is fully done by generative AI/LLM

Code tests:

• The code tests contain no generative AI/LLM
• The code tests are partially written by generative AI/LLM
  • X% performed by the author(s)
• The code tests are fully written by generative AI/LLM

[Doomsk]

Hi @kwyip thank you for this PR. Is there anything you want to do or to comment before I start the review?

[kwyip]

@Doomsk Sorry for the late reply. I don't. Please go ahead with the review. Thanks.

[Doomsk]

Thank you @kwyip I am starting the review.

[Doomsk]

Thanks @kwyip for the work!
I will now proceed with some tests before giving the green light.

[Doomsk]

before re-running the workflow actions, I will phase out the Python code that is not necessary for mkdocs and the CLI. Then you can pull the main branch into your main and check the formatting with pre-commit run --all-files

[kwyip]

before re-running the workflow actions, I will phase out the Python code that is not necessary for mkdocs and the CLI. Then you can pull the main branch into your main and check the formatting with pre-commit run --all-files

Hi,
Sorry for late reply. I have updated my main branch with your changes, and they should also pass pre-commit and pytest. Thanks.

[Doomsk]

Thanks @kwyip. A few more changes and it can have a final review.

[Doomsk]

Other than the minor fix, it's go to be approved @kwyip

[Doomsk]

@kwyip make sure you have verified signature for the commit to be verified and thus properly merged

[kwyip]

@kwyip make sure you have verified signature for the commit to be verified and thus properly merged

@Doomsk Thanks for the suggestion. I have added it.

[Doomsk]

Thanks @kwyip I'll proceed with the merge now

[Doomsk]

@kwyip please comment on the issue so I can assign it to you and you can receive the bounty.