sessionmemory 0.18.0__tar.gz → 0.19.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/PKG-INFO +10 -8
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/README.md +7 -5
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/pyproject.toml +13 -13
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/pyproject.toml.orig +13 -13
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/new.py +20 -26
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/backlog.py +135 -15
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/bootstrap.py +3 -2
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/doctor.py +2 -4
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/inject.py +7 -5
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/__init__.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/cli.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/__init__.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/_common.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/delete.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/doctor.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/export.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/init.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/inject.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/local.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/log.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/path.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/project.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/reconcile.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/reindex.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/search.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/entry.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/__init__.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/atomic.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/changes.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/commits.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/config.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/embed.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/export.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/field.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/fieldindex.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/frontmatter.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/gitinfo.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/ids.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/localdeclined.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/localmanifest.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/localmd.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/localtree.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/log.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/paths.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/reconcile.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/registration.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/registry.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/resolve.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/settingsdiff.py +0 -0
- {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/specs.py +0 -0
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
Metadata-Version: 2.3
|
|
2
2
|
Name: sessionmemory
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.19.0
|
|
4
4
|
Summary: Durable memory for coding agents, one folder of searchable pages per project.
|
|
5
5
|
Author: Nathaniel Landau
|
|
6
6
|
Author-email: Nathaniel Landau <github@natelandau.com>
|
|
7
|
-
Requires-Dist: fastembed>=0.9.
|
|
7
|
+
Requires-Dist: fastembed>=0.9.1
|
|
8
8
|
Requires-Dist: nclutils>=4.0.0
|
|
9
9
|
Requires-Dist: pyyaml>=6.0.3
|
|
10
10
|
Requires-Dist: sqlite-vec>=0.1.9
|
|
11
11
|
Requires-Dist: tomli-w>=1.2.0
|
|
12
|
-
Requires-Dist: typer>=0.
|
|
12
|
+
Requires-Dist: typer>=0.29.1
|
|
13
13
|
Requires-Python: >=3.13, <3.15
|
|
14
14
|
Description-Content-Type: text/markdown
|
|
15
15
|
|
|
@@ -232,15 +232,17 @@ all for a script.
|
|
|
232
232
|
- Past sessions, one page each: `sessionmemory search "<words>" --logs`. Search them
|
|
233
233
|
for why something was decided, what happened the last time an area changed, or
|
|
234
234
|
whether a fix was already tried.
|
|
235
|
-
- Open work: read `backlog.md`. Any top-level bullet is an open item
|
|
235
|
+
- Open work: read `backlog.md`. Any top-level bullet is an open item, and the
|
|
236
|
+
indented lines under it are its detail. Under a
|
|
236
237
|
`## <kind>` heading (feat, fix, refactor, perf, docs, test, build, ci, decide), the
|
|
237
238
|
full shape is sized S, M, or L: `- [S] <imperative description> - <YYYY-MM-DD> [#topic]`.
|
|
238
239
|
Add one with
|
|
239
240
|
`sessionmemory new backlog --kind <kind> --size <S|M|L> --title "..." --topic <topic> --cwd .`,
|
|
240
|
-
which writes that shape and creates the file or heading when missing.
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
241
|
+
which writes that shape and creates the file or heading when missing. Keep the
|
|
242
|
+
title to one short sentence and pass context (why, where, what was tried) with
|
|
243
|
+
`--detail "..."`, in single quotes when it holds a backtick or `$`. Questions for
|
|
244
|
+
the user to answer go under `## decide`. Delete a finished item with its detail,
|
|
245
|
+
and one that will never be done, directly; never tick or annotate it. Git history is the record of what was finished.
|
|
244
246
|
- Specs: `specs/` holds one design record per feature, named `<date>-<topic>.md`
|
|
245
247
|
and kept after the work ships. Before designing or changing a feature, search
|
|
246
248
|
them: `sessionmemory search "<words>" --specs` (listing the directory works too), so a
|
|
@@ -217,15 +217,17 @@ all for a script.
|
|
|
217
217
|
- Past sessions, one page each: `sessionmemory search "<words>" --logs`. Search them
|
|
218
218
|
for why something was decided, what happened the last time an area changed, or
|
|
219
219
|
whether a fix was already tried.
|
|
220
|
-
- Open work: read `backlog.md`. Any top-level bullet is an open item
|
|
220
|
+
- Open work: read `backlog.md`. Any top-level bullet is an open item, and the
|
|
221
|
+
indented lines under it are its detail. Under a
|
|
221
222
|
`## <kind>` heading (feat, fix, refactor, perf, docs, test, build, ci, decide), the
|
|
222
223
|
full shape is sized S, M, or L: `- [S] <imperative description> - <YYYY-MM-DD> [#topic]`.
|
|
223
224
|
Add one with
|
|
224
225
|
`sessionmemory new backlog --kind <kind> --size <S|M|L> --title "..." --topic <topic> --cwd .`,
|
|
225
|
-
which writes that shape and creates the file or heading when missing.
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
226
|
+
which writes that shape and creates the file or heading when missing. Keep the
|
|
227
|
+
title to one short sentence and pass context (why, where, what was tried) with
|
|
228
|
+
`--detail "..."`, in single quotes when it holds a backtick or `$`. Questions for
|
|
229
|
+
the user to answer go under `## decide`. Delete a finished item with its detail,
|
|
230
|
+
and one that will never be done, directly; never tick or annotate it. Git history is the record of what was finished.
|
|
229
231
|
- Specs: `specs/` holds one design record per feature, named `<date>-<topic>.md`
|
|
230
232
|
and kept after the work ships. Before designing or changing a feature, search
|
|
231
233
|
them: `sessionmemory search "<words>" --specs` (listing the directory works too), so a
|
|
@@ -1,17 +1,17 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
dependencies = [
|
|
3
|
-
"fastembed>=0.9.
|
|
3
|
+
"fastembed>=0.9.1",
|
|
4
4
|
"nclutils>=4.0.0",
|
|
5
5
|
"pyyaml>=6.0.3",
|
|
6
6
|
"sqlite-vec>=0.1.9",
|
|
7
7
|
"tomli-w>=1.2.0",
|
|
8
|
-
"typer>=0.
|
|
8
|
+
"typer>=0.29.1",
|
|
9
9
|
]
|
|
10
10
|
description = "Durable memory for coding agents, one folder of searchable pages per project."
|
|
11
11
|
name = "sessionmemory"
|
|
12
12
|
readme = "README.md"
|
|
13
13
|
requires-python = ">=3.13,<3.15"
|
|
14
|
-
version = "0.
|
|
14
|
+
version = "0.19.0"
|
|
15
15
|
|
|
16
16
|
[[project.authors]]
|
|
17
17
|
name = "Nathaniel Landau"
|
|
@@ -22,23 +22,23 @@ sessionmemory = "sessionmemory.entry:main"
|
|
|
22
22
|
|
|
23
23
|
[dependency-groups]
|
|
24
24
|
dev = [
|
|
25
|
-
"commitizen>=4.19.
|
|
26
|
-
"coverage>=7.
|
|
25
|
+
"commitizen>=4.19.3",
|
|
26
|
+
"coverage>=7.17.3",
|
|
27
27
|
"duty>=1.10.1",
|
|
28
|
-
"gate-cache>=0.
|
|
29
|
-
"prek>=0.5.
|
|
28
|
+
"gate-cache>=0.7.0",
|
|
29
|
+
"prek>=0.5.11",
|
|
30
30
|
"pytest-clarity>=1.0.1",
|
|
31
31
|
"pytest-cov>=7.1.0",
|
|
32
32
|
"pytest-devtools>=1.3.0",
|
|
33
|
-
"pytest-mock>=3.
|
|
33
|
+
"pytest-mock>=3.17.0",
|
|
34
34
|
"pytest-xdist>=3.8.0",
|
|
35
|
-
"pytest>=9.
|
|
35
|
+
"pytest>=9.2.0",
|
|
36
36
|
"rich>=15.0.0",
|
|
37
|
-
"ruff>=0.17.
|
|
37
|
+
"ruff>=0.17.5",
|
|
38
38
|
"shellcheck-py>=0.11.0.1",
|
|
39
|
-
"ty>=0.0.
|
|
40
|
-
"types-pyyaml>=6.0.12.
|
|
41
|
-
"typos>=1.
|
|
39
|
+
"ty>=0.0.104",
|
|
40
|
+
"types-pyyaml>=6.0.12.20261113",
|
|
41
|
+
"typos>=1.52.2",
|
|
42
42
|
"yamllint>=1.38.0",
|
|
43
43
|
]
|
|
44
44
|
|
|
@@ -1,41 +1,41 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
authors = [{ name = "Nathaniel Landau", email = "github@natelandau.com" }]
|
|
3
3
|
dependencies = [
|
|
4
|
-
"fastembed>=0.9.
|
|
4
|
+
"fastembed>=0.9.1",
|
|
5
5
|
"nclutils>=4.0.0",
|
|
6
6
|
"pyyaml>=6.0.3",
|
|
7
7
|
"sqlite-vec>=0.1.9",
|
|
8
8
|
"tomli-w>=1.2.0",
|
|
9
|
-
"typer>=0.
|
|
9
|
+
"typer>=0.29.1",
|
|
10
10
|
]
|
|
11
11
|
description = "Durable memory for coding agents, one folder of searchable pages per project."
|
|
12
12
|
name = "sessionmemory"
|
|
13
13
|
readme = "README.md"
|
|
14
14
|
requires-python = ">=3.13,<3.15"
|
|
15
|
-
version = "0.
|
|
15
|
+
version = "0.19.0"
|
|
16
16
|
|
|
17
17
|
[project.scripts]
|
|
18
18
|
sessionmemory = "sessionmemory.entry:main"
|
|
19
19
|
|
|
20
20
|
[dependency-groups]
|
|
21
21
|
dev = [
|
|
22
|
-
"commitizen>=4.19.
|
|
23
|
-
"coverage>=7.
|
|
22
|
+
"commitizen>=4.19.3",
|
|
23
|
+
"coverage>=7.17.3",
|
|
24
24
|
"duty>=1.10.1",
|
|
25
|
-
"gate-cache>=0.
|
|
26
|
-
"prek>=0.5.
|
|
25
|
+
"gate-cache>=0.7.0",
|
|
26
|
+
"prek>=0.5.11",
|
|
27
27
|
"pytest-clarity>=1.0.1",
|
|
28
28
|
"pytest-cov>=7.1.0",
|
|
29
29
|
"pytest-devtools>=1.3.0",
|
|
30
|
-
"pytest-mock>=3.
|
|
30
|
+
"pytest-mock>=3.17.0",
|
|
31
31
|
"pytest-xdist>=3.8.0",
|
|
32
|
-
"pytest>=9.
|
|
32
|
+
"pytest>=9.2.0",
|
|
33
33
|
"rich>=15.0.0",
|
|
34
|
-
"ruff>=0.17.
|
|
34
|
+
"ruff>=0.17.5",
|
|
35
35
|
"shellcheck-py>=0.11.0.1",
|
|
36
|
-
"ty>=0.0.
|
|
37
|
-
"types-pyyaml>=6.0.12.
|
|
38
|
-
"typos>=1.
|
|
36
|
+
"ty>=0.0.104",
|
|
37
|
+
"types-pyyaml>=6.0.12.20261113",
|
|
38
|
+
"typos>=1.52.2",
|
|
39
39
|
"yamllint>=1.38.0",
|
|
40
40
|
]
|
|
41
41
|
|
|
@@ -55,6 +55,11 @@ SUPERSEDES = typer.Option(
|
|
|
55
55
|
None, "--supersedes", help="The spec this one replaces, by name; it is marked superseded."
|
|
56
56
|
)
|
|
57
57
|
TOPIC = typer.Option(None, "--topic", help="A topic tag, without the leading hash.")
|
|
58
|
+
DETAIL = typer.Option(
|
|
59
|
+
None,
|
|
60
|
+
"--detail",
|
|
61
|
+
help="Context written as nested bullets under the item: why, where, what was tried.",
|
|
62
|
+
)
|
|
58
63
|
|
|
59
64
|
|
|
60
65
|
def _report(path: Path, title: str, *, as_json: bool, uuid: str | None = None) -> None:
|
|
@@ -200,33 +205,13 @@ def new_reference(
|
|
|
200
205
|
_new_living_document(paths.reference_dir, title, body, body_file, cwd, as_json=as_json)
|
|
201
206
|
|
|
202
207
|
|
|
203
|
-
def _warn_about_shape(*, in_use: list[str], title: str, topic: str | None) -> None:
|
|
204
|
-
"""Warn, without blocking the write, about a new topic tag or an overlong description.
|
|
205
|
-
|
|
206
|
-
`in_use` is read before the write, since the line just written always carries its own
|
|
207
|
-
topic.
|
|
208
|
-
"""
|
|
209
|
-
if topic is not None:
|
|
210
|
-
tag = topic.strip().removeprefix("#")
|
|
211
|
-
if tag and in_use and tag not in in_use:
|
|
212
|
-
pp.warning(
|
|
213
|
-
f"#{tag} is a new topic in this backlog",
|
|
214
|
-
details=[f"in use: {', '.join(in_use)}"],
|
|
215
|
-
)
|
|
216
|
-
length = len(title.strip())
|
|
217
|
-
if length > backlog.LONG_DESCRIPTION:
|
|
218
|
-
pp.warning(
|
|
219
|
-
f"the description is {length} characters, over the {backlog.LONG_DESCRIPTION} limit",
|
|
220
|
-
details=["keep a line to one sentence and put detail in a spec"],
|
|
221
|
-
)
|
|
222
|
-
|
|
223
|
-
|
|
224
208
|
@app.command("backlog", help="Add one open item to this project's backlog.md.")
|
|
225
209
|
def new_backlog(
|
|
226
210
|
kind: Kind = KIND,
|
|
227
211
|
size: Size = SIZE,
|
|
228
212
|
title: str = DESCRIPTION,
|
|
229
213
|
topic: str | None = TOPIC,
|
|
214
|
+
detail: str | None = DETAIL,
|
|
230
215
|
cwd: Path | None = CWD_OPTION,
|
|
231
216
|
*,
|
|
232
217
|
as_json: bool = JSON_OPTION,
|
|
@@ -241,13 +226,22 @@ def new_backlog(
|
|
|
241
226
|
path = paths.backlog_path(vault, slug)
|
|
242
227
|
in_use = backlog.topics(path)
|
|
243
228
|
try:
|
|
244
|
-
|
|
245
|
-
path,
|
|
229
|
+
block = backlog.add_item(
|
|
230
|
+
path,
|
|
231
|
+
kind=kind.value,
|
|
232
|
+
size=size.value,
|
|
233
|
+
description=title,
|
|
234
|
+
topic=topic,
|
|
235
|
+
today=today(),
|
|
236
|
+
detail=detail,
|
|
246
237
|
)
|
|
247
238
|
except backlog.BacklogError as error:
|
|
248
239
|
fail(str(error))
|
|
249
|
-
|
|
240
|
+
for warning in backlog.shape_warnings(
|
|
241
|
+
in_use=in_use, description=title, topic=topic, detail=detail
|
|
242
|
+
):
|
|
243
|
+
pp.warning(warning.message, details=[warning.advice])
|
|
250
244
|
if as_json:
|
|
251
|
-
emit_json({"path": str(path), "line":
|
|
245
|
+
emit_json({"path": str(path), "line": block[0], "detail": block[1:]})
|
|
252
246
|
return
|
|
253
|
-
emit_value(
|
|
247
|
+
emit_value("\n".join([*block, str(path)]))
|
|
@@ -6,11 +6,17 @@ does not depend on that shape: a person writes lines by hand, often as plain pro
|
|
|
6
6
|
every top-level bullet with text is an item. The line has no checkbox: finished work is
|
|
7
7
|
deleted, and git history is the record of it, so there is nothing to tick. Deleting a
|
|
8
8
|
line needs no validation and stays a direct edit.
|
|
9
|
+
|
|
10
|
+
Context that would crowd the line goes in an optional detail block: indented bullets
|
|
11
|
+
directly under it. Counting ignores indented lines, so the headline stays the item and
|
|
12
|
+
the detail never inflates the count.
|
|
9
13
|
"""
|
|
10
14
|
|
|
11
15
|
from __future__ import annotations
|
|
12
16
|
|
|
13
17
|
import re
|
|
18
|
+
import textwrap
|
|
19
|
+
from dataclasses import dataclass
|
|
14
20
|
from typing import TYPE_CHECKING
|
|
15
21
|
|
|
16
22
|
from sessionmemory.lib import atomic
|
|
@@ -22,14 +28,32 @@ KINDS = ("feat", "fix", "refactor", "perf", "docs", "test", "build", "ci", "deci
|
|
|
22
28
|
SIZES = ("S", "M", "L")
|
|
23
29
|
HEADING = "# Backlog"
|
|
24
30
|
_SECTION_PREFIX = "## "
|
|
25
|
-
LONG_DESCRIPTION =
|
|
31
|
+
LONG_DESCRIPTION = 120
|
|
32
|
+
LONG_DETAIL = 1500
|
|
33
|
+
DETAIL_BULLET = " - "
|
|
34
|
+
_DETAIL_CONTINUATION = " "
|
|
35
|
+
DETAIL_WIDTH = 88
|
|
36
|
+
_TICKED = ("- [x]", "- [X]")
|
|
26
37
|
_TOPIC_TAG = re.compile(r"\[#([^\s\]]+)\]")
|
|
38
|
+
_BULLET_MARKER = re.compile(r"^-(\s+|$)")
|
|
27
39
|
|
|
28
40
|
|
|
29
41
|
class BacklogError(ValueError):
|
|
30
42
|
"""An item field that cannot be written as a well-formed line."""
|
|
31
43
|
|
|
32
44
|
|
|
45
|
+
@dataclass(frozen=True)
|
|
46
|
+
class ShapeWarning:
|
|
47
|
+
"""A field that is written as given but likely misplaced, with what to do instead."""
|
|
48
|
+
|
|
49
|
+
message: str
|
|
50
|
+
advice: str
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def _tag(topic: str) -> str:
|
|
54
|
+
return topic.strip().removeprefix("#")
|
|
55
|
+
|
|
56
|
+
|
|
33
57
|
def format_item(*, kind: str, size: str, description: str, topic: str | None, today: str) -> str:
|
|
34
58
|
"""Return the checklist line for one open item, validating every field.
|
|
35
59
|
|
|
@@ -64,7 +88,7 @@ def format_item(*, kind: str, size: str, description: str, topic: str | None, to
|
|
|
64
88
|
line = f"- [{size}] {description} - {today}"
|
|
65
89
|
if topic is None:
|
|
66
90
|
return line
|
|
67
|
-
topic = topic
|
|
91
|
+
topic = _tag(topic)
|
|
68
92
|
if not topic:
|
|
69
93
|
msg = "the topic is empty"
|
|
70
94
|
raise BacklogError(msg)
|
|
@@ -77,6 +101,91 @@ def format_item(*, kind: str, size: str, description: str, topic: str | None, to
|
|
|
77
101
|
return f"{line} [#{topic}]"
|
|
78
102
|
|
|
79
103
|
|
|
104
|
+
def format_detail(detail: str | None) -> list[str]:
|
|
105
|
+
"""Return the nested bullets that carry an item's detail under its headline.
|
|
106
|
+
|
|
107
|
+
Each line of `detail` becomes one bullet, so a markdown viewer shows the lines apart
|
|
108
|
+
instead of joining them into the item's paragraph. A bullet the caller wrote keeps
|
|
109
|
+
its text without gaining a second marker. Blank lines are dropped so the item stays
|
|
110
|
+
one tight block and the next item's insert point is unambiguous.
|
|
111
|
+
|
|
112
|
+
Args:
|
|
113
|
+
detail (str | None): Free text, possibly several lines, or None for no detail.
|
|
114
|
+
|
|
115
|
+
Returns:
|
|
116
|
+
list[str]: The lines to write, each bullet starting with `DETAIL_BULLET` and
|
|
117
|
+
wrapped onto indented continuation lines, or an empty list when there is no
|
|
118
|
+
detail.
|
|
119
|
+
"""
|
|
120
|
+
texts = (_BULLET_MARKER.sub("", line.strip()) for line in (detail or "").splitlines())
|
|
121
|
+
return [
|
|
122
|
+
wrapped
|
|
123
|
+
for text in texts
|
|
124
|
+
if text
|
|
125
|
+
for wrapped in textwrap.wrap(
|
|
126
|
+
text,
|
|
127
|
+
width=DETAIL_WIDTH,
|
|
128
|
+
initial_indent=DETAIL_BULLET,
|
|
129
|
+
subsequent_indent=_DETAIL_CONTINUATION,
|
|
130
|
+
break_long_words=False,
|
|
131
|
+
break_on_hyphens=False,
|
|
132
|
+
)
|
|
133
|
+
]
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
def shape_warnings(
|
|
137
|
+
*, in_use: list[str], description: str, topic: str | None, detail: str | None
|
|
138
|
+
) -> list[ShapeWarning]:
|
|
139
|
+
"""Return what is likely misplaced in an item that is otherwise well-formed.
|
|
140
|
+
|
|
141
|
+
None of these refuses the write: a new topic may be deliberate, and length is advice.
|
|
142
|
+
|
|
143
|
+
Args:
|
|
144
|
+
in_use (list[str]): The topics on the backlog before this item, from `topics`.
|
|
145
|
+
description (str): The item's description as given.
|
|
146
|
+
topic (str | None): The item's topic as given, or None.
|
|
147
|
+
detail (str | None): The item's detail as given, or None.
|
|
148
|
+
|
|
149
|
+
Returns:
|
|
150
|
+
list[ShapeWarning]: One per problem, empty when the item is well placed.
|
|
151
|
+
"""
|
|
152
|
+
warnings: list[ShapeWarning] = []
|
|
153
|
+
tag = _tag(topic) if topic is not None else ""
|
|
154
|
+
if tag and in_use and tag not in in_use:
|
|
155
|
+
warnings.append(
|
|
156
|
+
ShapeWarning(f"#{tag} is a new topic in this backlog", f"in use: {', '.join(in_use)}")
|
|
157
|
+
)
|
|
158
|
+
length = len(description.strip())
|
|
159
|
+
if length > LONG_DESCRIPTION:
|
|
160
|
+
warnings.append(
|
|
161
|
+
ShapeWarning(
|
|
162
|
+
f"the description is {length} characters, longer than {LONG_DESCRIPTION}",
|
|
163
|
+
"keep the line to one short sentence and move context into --detail",
|
|
164
|
+
)
|
|
165
|
+
)
|
|
166
|
+
detail_length = len((detail or "").strip())
|
|
167
|
+
if detail_length > LONG_DETAIL:
|
|
168
|
+
warnings.append(
|
|
169
|
+
ShapeWarning(
|
|
170
|
+
f"the detail is {detail_length} characters, longer than {LONG_DETAIL}",
|
|
171
|
+
"a design this size belongs in a spec",
|
|
172
|
+
)
|
|
173
|
+
)
|
|
174
|
+
return warnings
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
def is_ticked(line: str) -> bool:
|
|
178
|
+
"""Return whether `line` is a ticked top-level bullet: finished work left in place.
|
|
179
|
+
|
|
180
|
+
Args:
|
|
181
|
+
line (str): One line of `backlog.md`.
|
|
182
|
+
|
|
183
|
+
Returns:
|
|
184
|
+
bool: True for a `- [x]` or `- [X]` line at column 0.
|
|
185
|
+
"""
|
|
186
|
+
return line.startswith(_TICKED)
|
|
187
|
+
|
|
188
|
+
|
|
80
189
|
def is_item(line: str) -> bool:
|
|
81
190
|
"""Return whether `line` is an open item, the only lines the session start counts.
|
|
82
191
|
|
|
@@ -88,7 +197,7 @@ def is_item(line: str) -> bool:
|
|
|
88
197
|
whatever size, date, or topic it carries. False for a ticked `- [x]` line,
|
|
89
198
|
an indented sub-bullet, an empty bullet, and anything that is not a bullet.
|
|
90
199
|
"""
|
|
91
|
-
if not line.startswith("- ") or line
|
|
200
|
+
if not line.startswith("- ") or is_ticked(line):
|
|
92
201
|
return False
|
|
93
202
|
return bool(line.removeprefix("- ").removeprefix("[ ]").strip())
|
|
94
203
|
|
|
@@ -108,12 +217,12 @@ def topics(path: Path) -> list[str]:
|
|
|
108
217
|
return sorted({tag for line in lines if is_item(line) for tag in _TOPIC_TAG.findall(line)})
|
|
109
218
|
|
|
110
219
|
|
|
111
|
-
def _insert(lines: list[str], kind: str,
|
|
112
|
-
"""Place `
|
|
220
|
+
def _insert(lines: list[str], kind: str, block: list[str]) -> list[str]:
|
|
221
|
+
"""Place `block` at the end of the `## kind` section, or open that section last."""
|
|
113
222
|
heading = f"{_SECTION_PREFIX}{kind}"
|
|
114
223
|
start = next((i for i, line in enumerate(lines) if line.rstrip() == heading), None)
|
|
115
224
|
if start is None:
|
|
116
|
-
return [*lines, "", heading, "",
|
|
225
|
+
return [*lines, "", heading, "", *block]
|
|
117
226
|
end = next(
|
|
118
227
|
(i for i in range(start + 1, len(lines)) if lines[i].startswith(_SECTION_PREFIX)),
|
|
119
228
|
len(lines),
|
|
@@ -122,14 +231,21 @@ def _insert(lines: list[str], kind: str, item: str) -> list[str]:
|
|
|
122
231
|
while last > start + 1 and not lines[last - 1].strip():
|
|
123
232
|
last -= 1
|
|
124
233
|
if last == start + 1:
|
|
125
|
-
return [*lines[:last], "",
|
|
126
|
-
return [*lines[:last],
|
|
234
|
+
return [*lines[:last], "", *block, *lines[last:]]
|
|
235
|
+
return [*lines[:last], *block, *lines[last:]]
|
|
127
236
|
|
|
128
237
|
|
|
129
238
|
def add_item(
|
|
130
|
-
path: Path,
|
|
131
|
-
|
|
132
|
-
|
|
239
|
+
path: Path,
|
|
240
|
+
*,
|
|
241
|
+
kind: str,
|
|
242
|
+
size: str,
|
|
243
|
+
description: str,
|
|
244
|
+
topic: str | None,
|
|
245
|
+
today: str,
|
|
246
|
+
detail: str | None = None,
|
|
247
|
+
) -> list[str]:
|
|
248
|
+
"""Append one open item under its kind heading and return the lines written.
|
|
133
249
|
|
|
134
250
|
A missing file starts with `# Backlog`. An existing file keeps whatever heads it,
|
|
135
251
|
since the `# Backlog` heading is never inserted into a file someone else structured.
|
|
@@ -141,14 +257,18 @@ def add_item(
|
|
|
141
257
|
description (str): The imperative description.
|
|
142
258
|
topic (str | None): The tag, or None for none.
|
|
143
259
|
today (str): The date as `YYYY-MM-DD`.
|
|
260
|
+
detail (str | None): Context written as indented lines under the item, or None.
|
|
144
261
|
|
|
145
262
|
Returns:
|
|
146
|
-
str: The line
|
|
263
|
+
list[str]: The item line followed by its detail lines, without newlines.
|
|
147
264
|
|
|
148
265
|
Raises:
|
|
149
266
|
BacklogError: A field cannot be written as a well-formed line.
|
|
150
267
|
"""
|
|
151
|
-
|
|
268
|
+
block = [
|
|
269
|
+
format_item(kind=kind, size=size, description=description, topic=topic, today=today),
|
|
270
|
+
*format_detail(detail),
|
|
271
|
+
]
|
|
152
272
|
lines = path.read_text(encoding="utf-8").rstrip().splitlines() if path.is_file() else [HEADING]
|
|
153
|
-
atomic.write_text(path, "\n".join(_insert(lines, kind=kind,
|
|
154
|
-
return
|
|
273
|
+
atomic.write_text(path, "\n".join(_insert(lines, kind=kind, block=block)) + "\n")
|
|
274
|
+
return block
|
|
@@ -74,8 +74,9 @@ One folder per project under `projects/`. Inside each:
|
|
|
74
74
|
indexed. `plans/` is scratch and is never committed: `.gitignore` and the plugin's
|
|
75
75
|
commits both leave it out.
|
|
76
76
|
- `backlog.md` is the list of open items for the project: every top-level bullet is an
|
|
77
|
-
open item, under any heading or none
|
|
78
|
-
A finished item is deleted
|
|
77
|
+
open item, under any heading or none, and the indented lines under it are its detail.
|
|
78
|
+
A question for the user goes under `## decide`. A finished item is deleted with its
|
|
79
|
+
detail, not ticked.
|
|
79
80
|
|
|
80
81
|
The `{MODEL_CODE}.sqlite3` file inside a field is its vector index. It is
|
|
81
82
|
derived from the pages beside it, gitignored, and rebuilt by `sessionmemory reindex`.
|
|
@@ -16,6 +16,7 @@ from pathlib import Path
|
|
|
16
16
|
from typing import TYPE_CHECKING
|
|
17
17
|
|
|
18
18
|
from sessionmemory.lib import (
|
|
19
|
+
backlog,
|
|
19
20
|
changes,
|
|
20
21
|
commits,
|
|
21
22
|
field,
|
|
@@ -147,9 +148,6 @@ def dead_projects(vault: Path, _embedder: Embedder) -> list[Finding]:
|
|
|
147
148
|
]
|
|
148
149
|
|
|
149
150
|
|
|
150
|
-
_TICKED = ("- [x]", "- [X]")
|
|
151
|
-
|
|
152
|
-
|
|
153
151
|
def ticked_backlog_lines(vault: Path, _embedder: Embedder) -> list[Finding]:
|
|
154
152
|
"""Report a ticked top-level bullet in a backlog.
|
|
155
153
|
|
|
@@ -162,7 +160,7 @@ def ticked_backlog_lines(vault: Path, _embedder: Embedder) -> list[Finding]:
|
|
|
162
160
|
if not path.is_file():
|
|
163
161
|
continue
|
|
164
162
|
for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
|
|
165
|
-
if
|
|
163
|
+
if backlog.is_ticked(line):
|
|
166
164
|
message = f"line {number}: ticked; finished work is deleted, not ticked"
|
|
167
165
|
findings.append(Finding("backlog", str(path), message))
|
|
168
166
|
return findings
|
|
@@ -145,15 +145,17 @@ all for a script.
|
|
|
145
145
|
- Past sessions, one page each: `{command} search "<words>" --logs`. Search them
|
|
146
146
|
for why something was decided, what happened the last time an area changed, or
|
|
147
147
|
whether a fix was already tried.
|
|
148
|
-
- Open work: read `backlog.md`. Any top-level bullet is an open item
|
|
148
|
+
- Open work: read `backlog.md`. Any top-level bullet is an open item, and the
|
|
149
|
+
indented lines under it are its detail. Under a
|
|
149
150
|
`## <kind>` heading (feat, fix, refactor, perf, docs, test, build, ci, decide), the
|
|
150
151
|
full shape is sized S, M, or L: `- [S] <imperative description> - <YYYY-MM-DD> [#topic]`.
|
|
151
152
|
Add one with
|
|
152
153
|
`{command} new backlog --kind <kind> --size <S|M|L> --title "..." --topic <topic> --cwd .`,
|
|
153
|
-
which writes that shape and creates the file or heading when missing.
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
154
|
+
which writes that shape and creates the file or heading when missing. Keep the
|
|
155
|
+
title to one short sentence and pass context (why, where, what was tried) with
|
|
156
|
+
`--detail "..."`, in single quotes when it holds a backtick or `$`. Questions for
|
|
157
|
+
the user to answer go under `## decide`. Delete a finished item with its detail,
|
|
158
|
+
and one that will never be done, directly; never tick or annotate it. Git history is the record of what was finished.
|
|
157
159
|
- Specs: `specs/` holds one design record per feature, named `<date>-<topic>.md`
|
|
158
160
|
and kept after the work ships. Before designing or changing a feature, search
|
|
159
161
|
them: `{command} search "<words>" --specs` (listing the directory works too), so a
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|