Add a Flutter-docs curator with first-class version metadata #12

Merged

raisondetredev merged 1 commit from refs/pull/12/head into main

2026-06-14 23:40:44 +02:00

raisondetredev commented

2026-06-14 23:40:12 +02:00

(Migrated from codeberg.org)

First step toward a dedicated, public Flutter studyset curated from docs.flutter.dev. This adds the curator that turns a hand-authored JSON file into a Halkyon archive — the same proven "note-plus-derived-flashcards" pipeline as the grammar curator.

What

lib/src/flutter_docs_lessons.dart — input model. Top-level studyset metadata (title, license, license_holder, source_version, curated_at), a lessons array (each: title, body, tags, optional source URL, cards), and an announcements array for the "What's new" section.
lib/src/flutter_docs_curator.dart — FlutterDocsCurator: emits one studyset carrying the first-class sourceVersion + curatedAt; each lesson → a note (its body, with a Source: line when a URL is given) + its front/back cards tagged by topic; each announcement → a note (summary + source link) + cards tagged whats-new and a per-release flutter-<version> tag.
bin/flutter_docs.dart — CLI (--input/--output/--title), mirroring bin/grammar.dart.
example/flutter_docs.sample.json + tests.
Adds source_version + curated_at to the curator's ArchiveStudyset (snake_case keys matching the halkyon-learn reader; additive, no archive-version bump).

Versioning & licensing (the two design points)

Versioning is first-class: source_version ("Flutter 3.24") + curated_at ride on the studyset so the app can show which release the content reflects (the app-side chip lands in a follow-up PR on halkyon-learn).
Licensing is enforced by shape: docs prose is CC BY 4.0 (reproducible with attribution). Medium release posts are all-rights-reserved, so an announcement can only ever emit an original summary + a link — never the source's text. The README documents this.

Tests

test/flutter_docs_curator_test.dart — parse + rejection cases, version metadata round-trip (snake_case keys), source-line attribution, per-announcement whats-new/version tagging, ordering, and the bundled-example check. Full suite (87 tests) passes; dart analyze lib bin test clean; CLI smoke-tested against the sample.

Next steps (separate PRs)

halkyon-infra: add source_version + curated_at columns to studysets.
halkyon-learn: thread the two fields through the archive model, importer, Studyset, Drift (+ migration), both sync serializers, and a version chip in the detail screen.
Author the real content, curate, import, publish public.

First step toward a dedicated, public **Flutter** studyset curated from docs.flutter.dev. This adds the curator that turns a hand-authored JSON file into a Halkyon archive — the same proven "note-plus-derived-flashcards" pipeline as the grammar curator. ## What - **`lib/src/flutter_docs_lessons.dart`** — input model. Top-level studyset metadata (`title`, `license`, `license_holder`, `source_version`, `curated_at`), a `lessons` array (each: `title`, `body`, `tags`, optional `source` URL, `cards`), and an `announcements` array for the "What's new" section. - **`lib/src/flutter_docs_curator.dart`** — `FlutterDocsCurator`: emits one studyset carrying the first-class `sourceVersion` + `curatedAt`; each lesson → a note (its body, with a `Source:` line when a URL is given) + its front/back cards tagged by topic; each announcement → a note (summary + source link) + cards tagged `whats-new` and a per-release `flutter-<version>` tag. - **`bin/flutter_docs.dart`** — CLI (`--input/--output/--title`), mirroring `bin/grammar.dart`. - **`example/flutter_docs.sample.json`** + tests. - Adds `source_version` + `curated_at` to the curator's `ArchiveStudyset` (snake_case keys matching the halkyon-learn reader; additive, no archive-version bump). ## Versioning & licensing (the two design points) - **Versioning is first-class:** `source_version` ("Flutter 3.24") + `curated_at` ride on the studyset so the app can show which release the content reflects (the app-side chip lands in a follow-up PR on halkyon-learn). - **Licensing is enforced by shape:** docs prose is CC BY 4.0 (reproducible with attribution). Medium release posts are all-rights-reserved, so an `announcement` can only ever emit an **original** `summary` + a link — never the source's text. The README documents this. ## Tests `test/flutter_docs_curator_test.dart` — parse + rejection cases, version metadata round-trip (snake_case keys), source-line attribution, per-announcement `whats-new`/version tagging, ordering, and the bundled-example check. Full suite (87 tests) passes; `dart analyze lib bin test` clean; CLI smoke-tested against the sample. ## Next steps (separate PRs) 1. halkyon-infra: add `source_version` + `curated_at` columns to `studysets`. 2. halkyon-learn: thread the two fields through the archive model, importer, `Studyset`, Drift (+ migration), both sync serializers, and a version chip in the detail screen. 3. Author the real content, curate, import, publish public.