knowledge-lintv0.1.0

CASOON Open Source

Keep your knowledge base honest.

Markdown notes drift quietly: a folder nobody declared, a link to a deleted entry, an API key pasted into a note. knowledge-lint checks the whole knowledge base against the rules in your _types.yml and fails the run when something is off – locally or in CI.

cargo install knowledge-lint
cargo install --git https://github.com/casoon/knowledge-lint
Free · MITv0.1.0single binarylocal and CI
Terminal: knowledge-lint lint checks knowledge/glossary/rag.md and embedding.md and reports two errors for embedding.md: status 'stable' is not one of the allowed values (current, deprecated), and related link './vectors.md' points to a file that doesn't exist. The run ends with '2 error(s), 0 warning(s) found.' and exit code 1. After the entry is changed to status: current with a related link to ./rag.md, the same command prints 'All checks passed (0 warning(s)).' and exits with 0.

Who it is for

category kinds: entries, SOPS secrets, assets
3
commands: lint and clean
2
plaintext key markers scanned in every entry
10
exit code for warnings only / any error
0 / 1

How it works

You declare your categories, entry types and status words in _types.yml. knowledge-lint lint reads it, goes through every folder of the knowledge directory and checks it by the kind you declared: Markdown entries, encrypted secrets or plain assets. A folder that is not declared is an error. Last, it checks the attachment list.

Each problem is printed under the file it belongs to. Errors fail the run with exit code 1, so a CI job stops; warnings, such as an entry that is due for review, are reported without failing it.

How knowledge-lint worksknowledge-lint lint reads _types.yml from the knowledge directory, then goes through every folder in it: a folder that is not declared as a category is an error, a declared one is checked by its kind (Markdown entries, SOPS secrets or assets). After the folders it checks the paths in _attachments.yml. Any error ends the run with exit code 1; warnings alone end it with exit code 0.How knowledge-lint worksknowledge-lint lint → _types.yml_types.yml → Every folderEvery folder → _attachments.yml_attachments.yml → Any error?Any error? → Run fails: yesAny error? → All checks passed: noyesnoknowledge-lint lint – in your repositoryknowledge-lint lintin your repository_types.yml – your rules_types.ymlyour rulesEvery folder – checked by its kindEvery folderchecked by its kind_attachments.yml – paths, references_attachments.ymlpaths, referencesAny error?Any error?Run fails – exit code 1Run failsexit code 1All checks passed – exit code 0All checks passedexit code 0
How knowledge-lint worksknowledge-lint lint reads _types.yml from the knowledge directory, then goes through every folder in it: a folder that is not declared as a category is an error, a declared one is checked by its kind (Markdown entries, SOPS secrets or assets). After the folders it checks the paths in _attachments.yml. Any error ends the run with exit code 1; warnings alone end it with exit code 0.How knowledge-lint worksknowledge-lint lint → _types.yml_types.yml → Every folderEvery folder → _attachments.yml_attachments.yml → Any error?Any error? → Run fails: yesAny error? → All checks passed: noyesnoknowledge-lint lint – in your repositoryknowledge-lint lintin your repository_types.yml – your rules_types.ymlyour rulesEvery folder – checked by its kindEvery folderchecked by its kind_attachments.yml – paths, references_attachments.ymlpaths, referencesAny error?Any error?Run fails – exit code 1Run failsexit code 1All checks passed – exit code 0All checks passedexit code 0
How knowledge-lint worksknowledge-lint lint reads _types.yml from the knowledge directory, then goes through every folder in it: a folder that is not declared as a category is an error, a declared one is checked by its kind (Markdown entries, SOPS secrets or assets). After the folders it checks the paths in _attachments.yml. Any error ends the run with exit code 1; warnings alone end it with exit code 0.How knowledge-lint worksknowledge-lint lint → _types.yml_types.yml → Every folderEvery folder → _attachments.yml_attachments.yml → Any error?Any error? → Run fails: yesAny error? → All checks passed: noyesnoknowledge-lint lint – in your repositoryknowledge-lintlintin yourrepository_types.yml – your rules_types.ymlyour rulesEvery folder – checked by its kindEvery folderchecked by itskind_attachments.yml – paths, references_attachments.ymlpaths, referencesAny error?Any error?Run fails – exit code 1Run failsexit code 1All checks passed – exit code 0All checkspassedexit code 0
How knowledge-lint worksknowledge-lint lint reads _types.yml from the knowledge directory, then goes through every folder in it: a folder that is not declared as a category is an error, a declared one is checked by its kind (Markdown entries, SOPS secrets or assets). After the folders it checks the paths in _attachments.yml. Any error ends the run with exit code 1; warnings alone end it with exit code 0.How knowledge-lint worksknowledge-lint lint → _types.yml_types.yml → Every folderEvery folder → _attachments.yml_attachments.yml → Any error?Any error? → Run fails: yesAny error? → All checks passed: noyesnoknowledge-lint lint – in your repositoryknowledge-lintlintin yourrepository_types.yml – your rules_types.ymlyour rulesEvery folder – checked by its kindEvery folderchecked by itskind_attachments.yml – paths, references_attachments.ymlpaths, referencesAny error?Any error?Run fails – exit code 1Run failsexit code 1All checks passed – exit code 0All checkspassedexit code 0
Configure _types.ymlEvery ruleRun it in CI →

Quickstart

Install the binary, declare your categories, run it.

  1. Install knowledge-lint from crates.io with cargo install.
  2. Declare your categories in knowledge/_types.yml.
  3. Run knowledge-lint lint and fix what it reports.
Read the documentation
Two commands
cargo install knowledge-lint
knowledge-lint lint   # checks ./knowledge

New in v0.1.0

Changelog →

Frequently asked questions

What exactly does knowledge-lint check?

Declared categories, required frontmatter fields, allowed status values, overdue last_reviewed dates, broken related links, structurally-valid SOPS secrets, a best-effort scan for plaintext API keys, and every entry in _attachments.yml.

Do I have to use ai-knowledge-template to use this?

No. It was extracted from that project, but every category, type, and status value is declared in your own _types.yml — there is no dependency on it.

Does it ever decrypt my SOPS secrets?

No. The sops_secret check is structural only: it confirms the file parses as YAML with a top-level sops: key, and never needs access to a private key.

Can I rename the frontmatter fields, like title or status?

No, the frontmatter key names are fixed by the spec. Category names, type values, and the status vocabulary itself are configurable in _types.yml.

How does it behave in CI?

knowledge-lint lint exits 1 on any error and 0 when only warnings remain, so it composes directly into a CI job: install the binary with cargo install and run it against your knowledge directory.