Metadata-Version: 2.4
Name: kb-lint
Version: 0.1.2
Summary: Markdown knowledge base linter for Obsidian, Foam, Dendron & Quartz: finds broken wiki-links, orphan notes, and missing frontmatter
Project-URL: Homepage, https://github.com/SingggggYee/kb-lint
Project-URL: Repository, https://github.com/SingggggYee/kb-lint
Project-URL: Issues, https://github.com/SingggggYee/kb-lint/issues
Author: SingggggYee
License-Expression: MIT
License-File: LICENSE
Keywords: backlinks,dendron,digital-garden,foam,knowledge-base,linter,llm,markdown,obsidian,quartz,wiki,wiki-links
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: pathspec>=0.11
Requires-Dist: python-frontmatter>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: tomli>=1.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# kb-lint

[![PyPI](https://img.shields.io/pypi/v/kb-lint?style=flat-square)](https://pypi.org/project/kb-lint/) [![Python](https://img.shields.io/badge/python-3.10+-blue?style=flat-square)](https://python.org) [![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE) [![Tests](https://img.shields.io/badge/tests-47%20passed-brightgreen?style=flat-square)]()

**A linter for your LLM-compiled knowledge base.**

## TL;DR

kb-lint is a fast, dependency-free markdown knowledge base linter. It checks Obsidian vaults, Foam workspaces, Dendron notes, and any wiki of markdown files for broken wiki-links, missing frontmatter, orphan pages, thin articles, and structural inconsistencies. No LLM required.

Run health checks over markdown wikis to catch broken links, missing metadata, orphan pages, thin articles, and structural inconsistencies, all without requiring an LLM.

Inspired by Andrej Karpathy's [LLM Knowledge Bases](https://x.com/karpathy/status/1907477278835749189) workflow, he runs "health checks" over his wiki to "find inconsistent data, impute missing data, find interesting connections for new article candidates."

## Use Cases

- Lint an Obsidian vault for broken wiki-links and orphan pages
- Check Foam or Dendron notes for missing frontmatter
- Validate a Quartz or Jekyll markdown wiki before publishing
- Find thin or stub articles in a personal knowledge base
- Detect inconsistent tags and casing across markdown files
- Run health checks on an LLM-compiled wiki (Karpathy workflow)
- Add markdown wiki linting to CI/CD with `kb-lint --format json`

## Installation

```bash
pip install kb-lint
```

## Quick Start

```bash
# Lint the current directory
kb-lint .

# Generate a health report
kb-lint ./my-wiki --report

# Auto-fix simple issues
kb-lint ./my-wiki --fix
```

## Example Output

```
 Knowledge Base Health Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Path:     ./wiki
  Articles: 47
  Links:    203

  3 errors  7 warnings  2 info

┌─────┬──────────────────────┬───────┬──────────────┬─────────────────────────────────────┐
│ Sev │ File                 │  Line │ Check        │ Message                             │
├─────┼──────────────────────┼───────┼──────────────┼─────────────────────────────────────┤
│ E   │ concepts/rlhf.md     │    23 │ links        │ Broken wiki-link: [[ppo-training]]  │
│ E   │ concepts/scaling.md  │     1 │ frontmatter  │ Missing required field: title         │
│ W   │ concepts/new-idea.md │     - │ content      │ Thin article: only 42 words (min 100)│
│ W   │ sources/paper-x.md   │     - │ orphans      │ Orphan page: no incoming links        │
│ I   │ concepts/nlp.md      │     - │ consistency  │ Inconsistent tag casing for 'nlp'     │
└─────┴──────────────────────┴───────┴──────────────┴─────────────────────────────────────┘

  2 issues can be auto-fixed with --fix

Health Score: 82/100
```

## Checks Reference

| Check | What it catches | Default severity | Auto-fixable? |
|-------|----------------|-----------------|---------------|
| `links` | Broken `[[wiki-links]]` (wiki-links only, no external URLs) | Error | No |
| `frontmatter` | Missing/invalid YAML frontmatter | Error/Info | Yes (add defaults) |
| `orphans` | Articles with no incoming links | Warning | No |
| `structure` | Non-kebab-case filenames, spaces | Error/Warning | Yes (rename) |
| `content` | Thin articles, `{{PLACEHOLDERS}}`, duplicate titles, empty sections | Error/Warning | No |
| `index` | Missing/extra entries in `_index.md` | Warning/Error | Yes (update index) |
| `consistency` | Inconsistent tags, dates, confidence levels | Warning | No |

## CLI Reference

```bash
# Basic lint
kb-lint [path]

# Output formats
kb-lint [path] --format terminal    # Rich colored output (default)
kb-lint [path] --format markdown    # Markdown report
kb-lint [path] --format json        # Machine-readable JSON

# Filter by severity
kb-lint [path] --severity error     # Only show errors
kb-lint [path] --severity warning   # Warnings and errors

# Run specific checks
kb-lint [path] --check links,frontmatter

# List available checks
kb-lint --list-checks

# Health report with score
kb-lint [path] --report

# CI mode (exit 1 on errors)
kb-lint [path] --ci

# Auto-fix
kb-lint [path] --fix

# Preview fixes without applying them
kb-lint [path] --fix --dry-run
```

### `--ci` Mode

In CI mode, kb-lint exits with code 1 if any errors are found:

```bash
kb-lint [path] --ci
```

### `--fix` Behavior

`--fix` creates `.bak` backup files before modifying any file. Use `--fix --dry-run` to preview what would be changed without writing to disk.

### Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Success - no errors found (warnings/info may still be present) |
| `1` | Errors found (only in `--ci` mode) |

## Configuration

Configure via `.kblintrc.yml` in your wiki directory:

```yaml
required_frontmatter:
  - title
recommended_frontmatter:
  - tags
  - sources
  - created
  - confidence
min_article_words: 100
ignore_patterns:
  - _templates/**
  - drafts/**
recognized_directories:
  - concepts
  - sources
  - comparisons
allowed_confidence_levels:
  - high
  - medium
  - low
severity_threshold: info
```

Or in `pyproject.toml`:

```toml
[tool.kb-lint]
required_frontmatter = ["title"]
min_article_words = 100
```

## CI Integration

### GitHub Actions

```yaml
- name: Lint knowledge base
  run: |
    pip install kb-lint
    kb-lint ./wiki --ci
```

## Part of the LLM KB Ecosystem

- **[awesome-llm-knowledge-bases](https://github.com/SingggggYee/awesome-llm-knowledge-bases)** - Curated list of LLM knowledge base tools
- **[karpathy-kb-template](https://github.com/SingggggYee/karpathy-kb-template)** - Ready-to-use wiki template
- **[wiki-compiler](https://github.com/SingggggYee/wiki-compiler)** - CLI to compile raw docs into structured wikis (uses kb-lint internally)

## FAQ

### How do I lint a markdown knowledge base?

Install kb-lint with `pip install kb-lint`, then run `kb-lint ./your-wiki` to scan all markdown files. Use `--report` to get a health score, or `--ci` for CI pipelines that should fail on errors. As a markdown knowledge base linter, kb-lint covers broken links, frontmatter, orphans, and structural checks in a single pass.

### What does kb-lint check?

kb-lint checks for broken `[[wiki-links]]`, missing YAML frontmatter, orphan pages with no incoming links, thin articles below a word count threshold, structural issues like non-kebab-case filenames, and inconsistencies in tags, dates, and confidence levels. Think of it as an end-to-end personal knowledge management quality check.

### Can kb-lint auto-fix issues?

Yes. Run `kb-lint ./your-wiki --fix` to auto-fix supported issues like missing frontmatter defaults, non-kebab-case filenames, and out-of-date index files. Use `--fix --dry-run` to preview changes before applying them.

### How do I lint an Obsidian vault?

Point kb-lint at your vault root: `kb-lint ~/path/to/your-vault --report`. It walks every `.md` file (including nested folders), resolves `[[wiki-links]]` across the whole graph, and produces an Obsidian vault health check covering broken links, orphan notes, missing frontmatter, and tag inconsistencies. No plugins required.

### Does kb-lint work with Obsidian vaults?

kb-lint works with any folder of markdown files that uses `[[wiki-links]]`. Obsidian vaults fit this pattern well. Just point kb-lint at your vault directory and it will scan all `.md` files, including nested folders.

### Does kb-lint work with Foam, Dendron, and Quartz?

Yes. kb-lint is intentionally tool-agnostic. If your notes are plain markdown files with `[[wiki-links]]` and optional YAML frontmatter, kb-lint works as a wiki-link validator for Foam workspaces, Dendron hierarchies, Quartz digital gardens, Jekyll wikis, and custom setups. Configure `ignore_patterns` in `.kblintrc.yml` to skip tool-specific folders like `.obsidian/` or `_layouts/`.

### How do I detect orphan pages in my knowledge base?

Run `kb-lint ./your-wiki --check orphans` to list every article that has zero incoming wiki-links. Combine with `--format json` to pipe results into other tools, or with `--report` to see orphan counts next to your overall health score. This is one of the most useful checks for cleaning up a personal knowledge base.

### What's the best linter for a markdown wiki?

For pure markdown syntax (heading style, line length), use `markdownlint`. For knowledge base structure (broken wiki-links, orphans, frontmatter, thin content, tag consistency), use kb-lint. They are complementary, most teams run both in CI.

### Can I use kb-lint in a GitHub Actions workflow?

Yes. kb-lint is designed for CI/CD. Install it in a workflow step and run `kb-lint ./wiki --ci` to fail the build on errors, or `kb-lint ./wiki --format json > report.json` to archive a machine-readable report. See the [CI Integration](#ci-integration) section above for a ready-to-paste GitHub Actions snippet.

### How is kb-lint different from markdownlint?

markdownlint checks markdown syntax and formatting (heading style, line length, etc.). kb-lint checks knowledge base structure, broken wiki-links, orphan pages, missing metadata, thin content, and cross-article consistency. They complement each other.

## Development

```bash
git clone https://github.com/SingggggYee/kb-lint
cd kb-lint
pip install -e ".[dev]"
pytest -v
ruff check src/ tests/
```

## License

MIT
