logloom 0.1.0

Parse changelog documents into an ordered, serializable model
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

# JSON

## Select release identifiers

With jq installed, run this from the repo root:

```sh
logloom parse examples/keep-a-changelog.md | jq '.releases[].version'
```

```json
null
"2.1.0"
"2.0.0"
```

Three JSON values. Here, `null` means Unreleased. Other formats also use null for
unversioned notes or date/author records; their attributes tell you which.
Version strings stay strings. SemVer arguments can happen elsewhere.

## Select entries

```sh
logloom parse examples/keep-a-changelog.md \
  | jq '.releases[0].sections[0].entries[0] | {kind, markdown}'
```

```json
{
  "kind": "list_item",
  "markdown": "- A streaming export API."
}
```

List markers stay in. Nested lists and extra paragraphs stay with their parent
item. Other Markdown blocks get separate `markdown` entries; plain text and
reStructuredText can use `text`.

## What's in there

| Field | What you get |
| --- | --- |
| `format` | Source format, e.g. `changesets`; used by validation |
| `metadata` | Optional plain-text `title` and introductory Markdown `description` |
| `releases` | Releases, including pending changes, in document order |
| `releases[].version`, `.date` | Optional opaque identifier and original date text |
| `releases[].heading`, `.link`, `.yanked` | Heading text (decoded title for JSON), resolved heading URL, withdrawal flag |
| `releases[].attributes` | Optional string attributes such as package, bump, author, fragment type, or original timestamp |
| `releases[].sections` | Ordered groups; `category: null` means uncategorized content |
| `sections[].component` | Optional component name, e.g. `"Firmware components"`; omitted for ordinary sections |
| `sections[].category` | Tagged category, e.g. `{"kind":"added"}` or `{"kind":"custom","name":"Performance"}` |
| `sections[].heading`, `.entries` | Optional original heading and ordered entries |
| `entries[].markdown`, `.kind` | Original content and `list_item`, `markdown`, or `text` |
| `links` | Effective reference definitions (`label`, `destination`, optional `title`), in source order |
| `source` | Exact input, including comments, whitespace, and original line endings |

## Where did this come from

Releases, sections, entries, and link definitions have a `span`. `start` and `end`
count UTF-8 bytes in `source`, with the end excluded. Lines start at 1.
`date_span` points at dates outside headings, like a Debian trailer. Decoded
GitHub bodies point at their containing JSON token.

The model owns its data and supports Serde in both directions. The source copy
costs some RAM; it keeps comments, whitespace, duplicate definitions, and syntax
we don't interpret.

[CLI filters](filters.md) narrow `releases` and their sections. `source`,
`metadata`, and `links` still describe the whole input, so spans keep working.
The source copy includes unselected releases.

Edit model fields as needed. `source` and spans still describe the original file;
this isn't a Markdown editor. Run validation after deserializing if you need it.
Older JSON without `format` defaults to Keep a Changelog. Missing attributes,
component names, and date spans get their empty defaults.