Metadata-Version: 2.4
Name: open-course-lint
Version: 0.1.0
Summary: Offline learning-outcome checks for Markdown course repositories
Author: Open Course Lint contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/v19880112-lab/open-course-lint
Project-URL: Repository, https://github.com/v19880112-lab/open-course-lint
Project-URL: Issues, https://github.com/v19880112-lab/open-course-lint/issues
Keywords: education,markdown,linter,open-course,github-actions
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Documentation
Classifier: Topic :: Education
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: markdown-it-py<5,>=3
Requires-Dist: PyYAML<7,>=6
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: ruff<1,>=0.12; extra == "dev"
Dynamic: license-file

# Open Course Lint

[English](#english) · MIT License

離線檢查公開 Markdown 課程是否包含可執行的學習目標、練習、成果證據與來源，並確認相對教材連結存在。首版不使用 AI、不上傳教材、不連線驗證外部網址，也不自動修改內容。

## 快速開始

需要 Python 3.11 以上：

```bash
python -m pip install open-course-lint
course-lint lessons/
course-lint lessons/ --format json
```

目前尚未發布 PyPI 時，可從原始碼安裝：

```bash
python -m pip install .
course-lint examples/valid-course
```

退出碼為 `0`（沒有錯誤；可有警告）、`1`（至少一項錯誤）、`2`（設定、輸入或執行失敗）。

## 規則

| 規則 | 預設 | 檢查 |
|---|---|---|
| OCL001 | error | 缺少學習目標 |
| OCL002 | error | 缺少練習 |
| OCL003 | error | 缺少成果證據 |
| OCL004 | error | 必要區段空白 |
| OCL005 | warning | 缺少來源 |
| OCL006 | error | 相對圖片或教材連結不存在 |
| OCL007 | warning | 圖片缺少替代文字 |
| OCL008 | warning | 必要區段未使用清單 |

預設辨識「學習目標 / Learning Objectives」、「練習 / Practice」、「成果證據 / Evidence」及「來源 / References」。巢狀標題屬於最近的區段；程式碼區塊內的假標題不會被當成課程結構。

## 設定

把 [`course-lint.example.yml`](course-lint.example.yml) 複製成 `course-lint.yml`。可設定掃描 glob、排除前言或附錄、加入標題別名，並將規則設成 `error`、`warning` 或 `off`：

```yaml
paths: ["lessons/**/*.md"]
exclude: ["lessons/preface/**", "lessons/appendix/**"]
headings:
  evidence: ["學習產出"]
rules:
  OCL005: error
  OCL008: off
```

未指定路徑時會採用設定中的 `paths`；目前目錄若有 `course-lint.yml`，CLI 會自動載入。

## GitHub Actions

把以下 workflow 放進課程 repo。Action 會產生對應檔案與行號的 PR 註記：

```yaml
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-python@v5
    with:
      python-version: "3.11"
  - uses: v19880112-lab/open-course-lint@v1
    with:
      path: lessons
      config: course-lint.yml
```

## Python API

```python
from course_lint import lint_paths
from course_lint.config import Config

diagnostics = lint_paths(["lessons"], Config.default())
```

每項 `Diagnostic` 固定包含 `rule_id`、`severity`、`message`、`path`、`line` 與 `column`。

## 隱私與範圍

核心只讀取本機 Markdown 與本機相對資產路徑；詳見 [PRIVACY.md](PRIVACY.md)。v1 不驗證外部 URL、不做 AI 語意評分。規則只檢查教材結構，不能判斷教學品質或事實正確性。

## English

Open Course Lint is an offline linter for public Markdown courses. It checks learning objectives, practice, evidence, references, list structure, image alt text, and local relative assets. It does not upload content, call AI services, validate external URLs, or rewrite lessons.

Install with Python 3.11+ and run `course-lint lessons/`. Use `--format text`, `json`, or `github`; exit codes are 0 for no errors, 1 for lint errors, and 2 for configuration or runtime failures. See the rule and configuration tables above; the default heading aliases support Traditional Chinese and English.

Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md), the [privacy statement](PRIVACY.md), and [security policy](SECURITY.md).
