sessionmemory 0.19.0__tar.gz → 0.20.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.
Files changed (51) hide show
  1. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/PKG-INFO +6 -2
  2. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/README.md +5 -1
  3. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/pyproject.toml +3 -3
  4. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/pyproject.toml.orig +3 -3
  5. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/commands/_common.py +16 -0
  6. sessionmemory-0.20.0/src/sessionmemory/commands/doctor.py +64 -0
  7. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/commands/local.py +6 -3
  8. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/commands/reconcile.py +41 -12
  9. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/commands/reindex.py +41 -7
  10. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/backlog.py +1 -1
  11. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/doctor.py +65 -15
  12. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/inject.py +5 -1
  13. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/localmd.py +55 -27
  14. sessionmemory-0.19.0/src/sessionmemory/commands/doctor.py +0 -27
  15. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/__init__.py +0 -0
  16. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/cli.py +0 -0
  17. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/commands/__init__.py +0 -0
  18. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/commands/delete.py +0 -0
  19. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/commands/export.py +0 -0
  20. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/commands/init.py +0 -0
  21. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/commands/inject.py +0 -0
  22. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/commands/log.py +0 -0
  23. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/commands/new.py +0 -0
  24. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/commands/path.py +0 -0
  25. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/commands/project.py +0 -0
  26. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/commands/search.py +0 -0
  27. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/entry.py +0 -0
  28. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/__init__.py +0 -0
  29. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/atomic.py +0 -0
  30. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/bootstrap.py +0 -0
  31. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/changes.py +0 -0
  32. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/commits.py +0 -0
  33. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/config.py +0 -0
  34. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/embed.py +0 -0
  35. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/export.py +0 -0
  36. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/field.py +0 -0
  37. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/fieldindex.py +0 -0
  38. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/frontmatter.py +0 -0
  39. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/gitinfo.py +0 -0
  40. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/ids.py +0 -0
  41. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/localdeclined.py +0 -0
  42. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/localmanifest.py +0 -0
  43. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/localtree.py +0 -0
  44. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/log.py +0 -0
  45. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/paths.py +0 -0
  46. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/reconcile.py +0 -0
  47. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/registration.py +0 -0
  48. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/registry.py +0 -0
  49. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/resolve.py +0 -0
  50. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/settingsdiff.py +0 -0
  51. {sessionmemory-0.19.0 → sessionmemory-0.20.0}/src/sessionmemory/lib/specs.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.3
2
2
  Name: sessionmemory
3
- Version: 0.19.0
3
+ Version: 0.20.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>
@@ -240,7 +240,11 @@ all for a script.
240
240
  `sessionmemory new backlog --kind <kind> --size <S|M|L> --title "..." --topic <topic> --cwd .`,
241
241
  which writes that shape and creates the file or heading when missing. Keep the
242
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
243
+ `--detail "..."`, in single quotes when it holds a backtick or `$`. Write the item
244
+ for the user reading it weeks later, who knows the product but not the code and
245
+ never saw this session: say what changes in the product's words, not this
246
+ session's terms or the code's names, and put files and approach in the detail,
247
+ with the reason when it is not obvious. Questions for
244
248
  the user to answer go under `## decide`. Delete a finished item with its detail,
245
249
  and one that will never be done, directly; never tick or annotate it. Git history is the record of what was finished.
246
250
  - Specs: `specs/` holds one design record per feature, named `<date>-<topic>.md`
@@ -225,7 +225,11 @@ all for a script.
225
225
  `sessionmemory new backlog --kind <kind> --size <S|M|L> --title "..." --topic <topic> --cwd .`,
226
226
  which writes that shape and creates the file or heading when missing. Keep the
227
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
228
+ `--detail "..."`, in single quotes when it holds a backtick or `$`. Write the item
229
+ for the user reading it weeks later, who knows the product but not the code and
230
+ never saw this session: say what changes in the product's words, not this
231
+ session's terms or the code's names, and put files and approach in the detail,
232
+ with the reason when it is not obvious. Questions for
229
233
  the user to answer go under `## decide`. Delete a finished item with its detail,
230
234
  and one that will never be done, directly; never tick or annotate it. Git history is the record of what was finished.
231
235
  - Specs: `specs/` holds one design record per feature, named `<date>-<topic>.md`
@@ -11,7 +11,7 @@ description = "Durable memory for coding agents, one folder of searchable pages
11
11
  name = "sessionmemory"
12
12
  readme = "README.md"
13
13
  requires-python = ">=3.13,<3.15"
14
- version = "0.19.0"
14
+ version = "0.20.0"
15
15
 
16
16
  [[project.authors]]
17
17
  name = "Nathaniel Landau"
@@ -25,7 +25,7 @@ dev = [
25
25
  "commitizen>=4.19.3",
26
26
  "coverage>=7.17.3",
27
27
  "duty>=1.10.1",
28
- "gate-cache>=0.7.0",
28
+ "gate-cache>=0.8.0",
29
29
  "prek>=0.5.11",
30
30
  "pytest-clarity>=1.0.1",
31
31
  "pytest-cov>=7.1.0",
@@ -36,7 +36,7 @@ dev = [
36
36
  "rich>=15.0.0",
37
37
  "ruff>=0.17.5",
38
38
  "shellcheck-py>=0.11.0.1",
39
- "ty>=0.0.104",
39
+ "ty>=0.0.105",
40
40
  "types-pyyaml>=6.0.12.20261113",
41
41
  "typos>=1.52.2",
42
42
  "yamllint>=1.38.0",
@@ -12,7 +12,7 @@
12
12
  name = "sessionmemory"
13
13
  readme = "README.md"
14
14
  requires-python = ">=3.13,<3.15"
15
- version = "0.19.0"
15
+ version = "0.20.0"
16
16
 
17
17
  [project.scripts]
18
18
  sessionmemory = "sessionmemory.entry:main"
@@ -22,7 +22,7 @@
22
22
  "commitizen>=4.19.3",
23
23
  "coverage>=7.17.3",
24
24
  "duty>=1.10.1",
25
- "gate-cache>=0.7.0",
25
+ "gate-cache>=0.8.0",
26
26
  "prek>=0.5.11",
27
27
  "pytest-clarity>=1.0.1",
28
28
  "pytest-cov>=7.1.0",
@@ -33,7 +33,7 @@
33
33
  "rich>=15.0.0",
34
34
  "ruff>=0.17.5",
35
35
  "shellcheck-py>=0.11.0.1",
36
- "ty>=0.0.104",
36
+ "ty>=0.0.105",
37
37
  "types-pyyaml>=6.0.12.20261113",
38
38
  "typos>=1.52.2",
39
39
  "yamllint>=1.38.0",
@@ -11,6 +11,7 @@ from typing import TYPE_CHECKING, NoReturn
11
11
  import typer
12
12
  import typer.core
13
13
  from nclutils import pp
14
+ from rich.text import Text
14
15
 
15
16
  # Typer vendors Click, so the `click` package's classes never match its errors.
16
17
  from typer._click import core as click_core
@@ -415,3 +416,18 @@ def require_project(vault: Path, cwd: Path | None = None) -> str:
415
416
  str: The resolved project slug.
416
417
  """
417
418
  return require_registered(vault, cwd)[0]
419
+
420
+
421
+ def count_cell(value: int, style: str) -> Text:
422
+ """Render a count for a report table, styled when non-zero and dimmed when zero.
423
+
424
+ Dimming every zero lets the counts that changed stand out in a wide grid.
425
+
426
+ Args:
427
+ value: The count.
428
+ style: The Rich style for a non-zero count.
429
+
430
+ Returns:
431
+ The styled cell.
432
+ """
433
+ return Text(str(value), style=style if value else "dim")
@@ -0,0 +1,64 @@
1
+ """The `doctor` command: report what is off, never fail over it."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from itertools import groupby
6
+ from typing import TYPE_CHECKING
7
+
8
+ from nclutils import pp
9
+ from rich.padding import Padding
10
+ from rich.table import Table
11
+ from rich.text import Text
12
+
13
+ from sessionmemory.commands._common import JSON_OPTION, build_embedder, emit_json, require_vault
14
+ from sessionmemory.lib import doctor
15
+
16
+ if TYPE_CHECKING:
17
+ from pathlib import Path
18
+
19
+ VAULT_GROUP = "(vault)"
20
+
21
+
22
+ def _print_report(vault: Path, findings: list[doctor.Finding]) -> None:
23
+ """Print findings grouped under a heading per project, each with its message below its path.
24
+
25
+ The message sits on its own line rather than in a column, so a long path never squeezes
26
+ it and nothing is cut at a narrow terminal. Vault findings come first, then projects by
27
+ slug, each keeping the checks' order.
28
+ """
29
+ console = pp.console()
30
+ check_width = max(len(finding.check) for finding in findings)
31
+ ordered = sorted(findings, key=lambda finding: finding.project)
32
+ for project, group in groupby(ordered, key=lambda finding: finding.project):
33
+ grid = Table.grid(padding=(0, 2))
34
+ grid.add_column(style="cyan", no_wrap=True, min_width=check_width)
35
+ grid.add_column(overflow="fold")
36
+ for finding in group:
37
+ path = doctor.short_path(vault, finding)
38
+ cell = (
39
+ Text.assemble((path, "bold"), "\n", finding.message)
40
+ if path
41
+ else Text(finding.message)
42
+ )
43
+ grid.add_row(Text(finding.check), cell)
44
+ console.print(Text(project or VAULT_GROUP, style="bold underline"))
45
+ console.print(Padding(grid, (0, 0, 0, 2), expand=False))
46
+
47
+
48
+ def doctor_command(*, as_json: bool = JSON_OPTION) -> None:
49
+ """Report pages, projects, and indexes worth a look. Always exits 0."""
50
+ vault = require_vault()
51
+ findings = doctor.run(vault, build_embedder())
52
+ if as_json:
53
+ emit_json(
54
+ [
55
+ {"check": f.check, "path": f.path, "message": f.message, "project": f.project}
56
+ for f in findings
57
+ ]
58
+ )
59
+ return
60
+ if not findings:
61
+ pp.success("nothing to report")
62
+ return
63
+ pp.info(f"{len(findings)} suggestion{'s' if len(findings) != 1 else ''}")
64
+ _print_report(vault, findings)
@@ -524,12 +524,14 @@ def _report_links(results: list[localmd.LinkResult]) -> None:
524
524
  elif result.status == "conflict":
525
525
  pp.warning(
526
526
  result.reason or f"{result.entry.name} was not linked",
527
- details=[result.remedy] if result.remedy else [],
527
+ details=[*result.details, *([result.remedy] if result.remedy else [])],
528
528
  )
529
529
  elif result.status == "tracked":
530
- pp.warning(f"{result.entry.link} is tracked by git; the vault copy stays in the vault")
530
+ pp.warning(
531
+ f"{result.entry.relpath} is tracked by git; the vault copy stays in the vault"
532
+ )
531
533
  elif result.status == "removed":
532
- pp.warning(f"removed {result.entry.link}, whose vault entry is gone")
534
+ pp.warning(f"removed {result.entry.relpath}, whose vault entry is gone")
533
535
 
534
536
 
535
537
  def _report_pending(waiting: list[localmd.Entry], pending: localmd.SettingsPending | None) -> None:
@@ -585,6 +587,7 @@ def _link_rows(results: list[localmd.LinkResult]) -> list[dict[str, object]]:
585
587
  "target": str(result.entry.target),
586
588
  "reason": result.reason,
587
589
  "remedy": result.remedy,
590
+ "details": list(result.details),
588
591
  }
589
592
  for result in results
590
593
  ]
@@ -2,14 +2,18 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
+ from contextlib import nullcontext
5
6
  from pathlib import Path # noqa: TC003
6
7
 
7
8
  import typer
8
9
  from nclutils import pp
10
+ from rich.table import Table
11
+ from rich.text import Text
9
12
 
10
13
  from sessionmemory.commands._common import (
11
14
  CWD_OPTION,
12
15
  JSON_OPTION,
16
+ count_cell,
13
17
  emit_json,
14
18
  fail,
15
19
  require_registered,
@@ -25,6 +29,30 @@ DRY_RUN = typer.Option(
25
29
  )
26
30
 
27
31
 
32
+ COUNT_STYLES = {
33
+ "replaced": "green",
34
+ "dropped": "red",
35
+ "in_progress": "cyan",
36
+ "unchecked": "yellow",
37
+ }
38
+
39
+
40
+ def _report(reports: list[reconcile.Report]) -> Table:
41
+ """Lay out each reconciler's counts as one row of a grid."""
42
+ table = Table(box=None, pad_edge=False, header_style="bold")
43
+ table.add_column("reconciler")
44
+ table.add_column("logs changed", justify="right")
45
+ for column in COUNT_STYLES:
46
+ table.add_column(column.replace("_", " "), justify="right")
47
+ for report in reports:
48
+ table.add_row(
49
+ Text(report.name),
50
+ count_cell(len(report.changed), "bold"),
51
+ *(count_cell(getattr(report, column), style) for column, style in COUNT_STYLES.items()),
52
+ )
53
+ return table
54
+
55
+
28
56
  def reconcile_command(
29
57
  cwd: Path | None = CWD_OPTION, *, dry_run: bool = DRY_RUN, as_json: bool = JSON_OPTION
30
58
  ) -> None:
@@ -42,8 +70,11 @@ def reconcile_command(
42
70
  )
43
71
  except reconcile.ContextError as error:
44
72
  fail(error.message, error.details)
73
+ # The spinner stays off the --json path so no escape sequence reaches the payload.
74
+ progress = nullcontext() if as_json else pp.console().status("reconciling")
45
75
  try:
46
- reports = reconcile.run(context, dry_run=dry_run)
76
+ with progress:
77
+ reports = reconcile.run(context, dry_run=dry_run)
47
78
  except CommitsError as error:
48
79
  fail("git could not answer for this project", [str(error)])
49
80
 
@@ -64,14 +95,12 @@ def reconcile_command(
64
95
  )
65
96
  return
66
97
 
67
- prefix = "(dry run) " if dry_run else ""
68
- with pp.step(f"{prefix}reconciling") as step:
69
- for report in reports:
70
- count = len(report.changed)
71
- step.sub(
72
- f"{report.name}: {count} log{'s' if count != 1 else ''} changed, {report.replaced} "
73
- f"replaced, {report.dropped} dropped, {report.in_progress} in progress, "
74
- f"{report.unchecked} unchecked"
75
- )
76
- for note in report.notes:
77
- step.sub(note)
98
+ pp.console().print(_report(reports))
99
+ verb = "would change" if dry_run else "changed"
100
+ for report in reports:
101
+ if report.changed:
102
+ pp.info(f"{report.name} {verb}", details=[path.name for path in report.changed])
103
+ for note in report.notes:
104
+ pp.warning(f"{report.name}: {note}")
105
+ if dry_run:
106
+ pp.dryrun("no log was rewritten")
@@ -7,11 +7,14 @@ from pathlib import Path # noqa: TC003
7
7
 
8
8
  import typer
9
9
  from nclutils import pp
10
+ from rich.table import Table
11
+ from rich.text import Text
10
12
 
11
13
  from sessionmemory.commands._common import (
12
14
  CWD_OPTION,
13
15
  JSON_OPTION,
14
16
  build_embedder,
17
+ count_cell,
15
18
  emit_json,
16
19
  fail,
17
20
  require_project,
@@ -21,6 +24,35 @@ from sessionmemory.lib import fieldindex, paths
21
24
 
22
25
  ALL = typer.Option(False, "--all", help="Reindex every project in the vault.") # noqa: FBT003
23
26
 
27
+ COUNT_STYLES = {"added": "green", "updated": "yellow", "removed": "red", "unchanged": ""}
28
+
29
+
30
+ def _report(rows: list[tuple[str, str, fieldindex.Refresh]], *, show_project: bool) -> Table:
31
+ """Lay out each field's counts as a grid, with column totals in the footer.
32
+
33
+ Args:
34
+ rows: One `(project, field, counts)` triple per field, in display order.
35
+ show_project: Whether to lead with a project column, naming each project once.
36
+
37
+ Returns:
38
+ The table to print.
39
+ """
40
+ table = Table(box=None, pad_edge=False, header_style="bold", show_footer=True)
41
+ if show_project:
42
+ table.add_column("project", footer="total")
43
+ table.add_column("field", footer="" if show_project else "total")
44
+ for column, style in COUNT_STYLES.items():
45
+ total = sum(getattr(counts, column) for *_, counts in rows)
46
+ table.add_column(column, justify="right", footer=count_cell(total, style))
47
+
48
+ previous = None
49
+ for project, field, counts in rows:
50
+ cells = [count_cell(getattr(counts, c), style) for c, style in COUNT_STYLES.items()]
51
+ lead = [Text(project if project != previous else "")] if show_project else []
52
+ table.add_row(*lead, Text(field), *cells)
53
+ previous = project
54
+ return table
55
+
24
56
 
25
57
  def reindex_command(
26
58
  cwd: Path | None = CWD_OPTION, *, all_projects: bool = ALL, as_json: bool = JSON_OPTION
@@ -54,11 +86,13 @@ def reindex_command(
54
86
  emit_json(payload)
55
87
  return
56
88
 
57
- with pp.step("reindexing") as step:
89
+ if not fields:
90
+ pp.info("no fields to reindex")
91
+ return
92
+
93
+ rows = []
94
+ with pp.console().status("reindexing") as status:
58
95
  for slug, name, directory in fields:
59
- result = fieldindex.refresh(directory, embedder)
60
- label = f"{slug}/{name}" if all_projects else name
61
- step.sub(
62
- f"{label}: {result.added} added, {result.updated} updated, "
63
- f"{result.removed} removed, {result.unchanged} unchanged"
64
- )
96
+ status.update(Text(f"reindexing {slug}/{name}"))
97
+ rows.append((slug, name, fieldindex.refresh(directory, embedder)))
98
+ pp.console().print(_report(rows, show_project=all_projects))
@@ -28,7 +28,7 @@ KINDS = ("feat", "fix", "refactor", "perf", "docs", "test", "build", "ci", "deci
28
28
  SIZES = ("S", "M", "L")
29
29
  HEADING = "# Backlog"
30
30
  _SECTION_PREFIX = "## "
31
- LONG_DESCRIPTION = 120
31
+ LONG_DESCRIPTION = 150
32
32
  LONG_DETAIL = 1500
33
33
  DETAIL_BULLET = " - "
34
34
  _DETAIL_CONTINUATION = " "
@@ -11,7 +11,7 @@ import hashlib
11
11
  import re
12
12
  import shlex
13
13
  import sqlite3
14
- from dataclasses import dataclass
14
+ from dataclasses import dataclass, replace
15
15
  from pathlib import Path
16
16
  from typing import TYPE_CHECKING
17
17
 
@@ -44,11 +44,20 @@ if TYPE_CHECKING:
44
44
 
45
45
  @dataclass(frozen=True)
46
46
  class Finding:
47
- """One thing a check found."""
47
+ """One thing a check found.
48
+
49
+ Attributes:
50
+ check (str): The check that found it.
51
+ path (str): The file or folder concerned, the slug for the `project` check, or
52
+ empty when nothing on disk is named.
53
+ message (str): What is wrong, and the fix when there is one.
54
+ project (str): The slug of the project it concerns, or empty for the vault itself.
55
+ """
48
56
 
49
57
  check: str
50
58
  path: str
51
59
  message: str
60
+ project: str = ""
52
61
 
53
62
 
54
63
  def nonconformant_names(vault: Path, _embedder: Embedder) -> list[Finding]:
@@ -57,7 +66,12 @@ def nonconformant_names(vault: Path, _embedder: Embedder) -> list[Finding]:
57
66
  Such a file is never indexed, so it is never searched, and a spec is never counted.
58
67
  """
59
68
  return [
60
- Finding("filename", str(path), "not lowercase ascii letters, digits, and hyphens")
69
+ Finding(
70
+ "filename",
71
+ str(path),
72
+ "not lowercase ascii letters, digits, and hyphens",
73
+ project=directory.parent.name,
74
+ )
61
75
  for directory in paths.iter_index_dirs(vault)
62
76
  for path in sorted(directory.glob("*.md"))
63
77
  if path.is_file() and not field.is_debris(path.name) and not field.is_page_name(path.name)
@@ -71,6 +85,7 @@ def oversized_pages(vault: Path, _embedder: Embedder) -> list[Finding]:
71
85
  "size",
72
86
  str(path),
73
87
  f"{path.stat().st_size} bytes; split it, the limit is {field.PAGE_LIMIT}",
88
+ project=directory.parent.name,
74
89
  )
75
90
  for directory in paths.iter_field_dirs(vault)
76
91
  for path in field.iter_pages(directory)
@@ -92,26 +107,31 @@ def malformed_frontmatter(vault: Path, _embedder: Embedder) -> list[Finding]:
92
107
  """
93
108
  findings = []
94
109
  for directory in paths.iter_field_dirs(vault):
110
+ slug = directory.parent.name
95
111
  for path in field.iter_pages(directory):
96
112
  raw = path.read_bytes()
97
113
  try:
98
114
  text = raw.decode("utf-8")
99
115
  except UnicodeDecodeError:
100
- findings.append(Finding("frontmatter", str(path), "not valid UTF-8"))
116
+ findings.append(Finding("frontmatter", str(path), "not valid UTF-8", project=slug))
101
117
  continue
102
118
  try:
103
119
  meta, _body = parse(text)
104
120
  except MissingFrontmatterError:
105
121
  if path.parent.name == paths.LEARNINGS_DIR:
106
- findings.append(Finding("frontmatter", str(path), "missing title or summary"))
122
+ findings.append(
123
+ Finding("frontmatter", str(path), "missing title or summary", project=slug)
124
+ )
107
125
  continue
108
126
  except FrontmatterError as error:
109
- findings.append(Finding("frontmatter", str(path), str(error)))
127
+ findings.append(Finding("frontmatter", str(path), str(error), project=slug))
110
128
  continue
111
129
  if path.parent.name == paths.LEARNINGS_DIR and (
112
130
  _blank(meta.get("title")) or _blank(meta.get("summary"))
113
131
  ):
114
- findings.append(Finding("frontmatter", str(path), "missing title or summary"))
132
+ findings.append(
133
+ Finding("frontmatter", str(path), "missing title or summary", project=slug)
134
+ )
115
135
  return findings
116
136
 
117
137
 
@@ -124,6 +144,7 @@ def unquoted_datetimes(vault: Path, _embedder: Embedder) -> list[Finding]:
124
144
  """
125
145
  findings = []
126
146
  for directory in paths.iter_field_dirs(vault):
147
+ slug = directory.parent.name
127
148
  for path in field.iter_pages(directory):
128
149
  try:
129
150
  keys = unquoted_datetime_keys(path.read_text(encoding="utf-8"))
@@ -131,7 +152,7 @@ def unquoted_datetimes(vault: Path, _embedder: Embedder) -> list[Finding]:
131
152
  continue
132
153
  if keys:
133
154
  message = f"{', '.join(keys)}: unquoted; quote the value"
134
- findings.append(Finding("datetime", str(path), message))
155
+ findings.append(Finding("datetime", str(path), message, project=slug))
135
156
  return findings
136
157
 
137
158
 
@@ -142,7 +163,7 @@ def dead_projects(vault: Path, _embedder: Embedder) -> list[Finding]:
142
163
  except registry.RegistryError as error:
143
164
  return [Finding("registry", "", str(error))]
144
165
  return [
145
- Finding("project", slug, f"root {project.root} does not exist")
166
+ Finding("project", slug, f"root {project.root} does not exist", project=slug)
146
167
  for slug, project in sorted(projects.items())
147
168
  if project.root and not Path(project.root).is_dir()
148
169
  ]
@@ -162,7 +183,7 @@ def ticked_backlog_lines(vault: Path, _embedder: Embedder) -> list[Finding]:
162
183
  for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
163
184
  if backlog.is_ticked(line):
164
185
  message = f"line {number}: ticked; finished work is deleted, not ticked"
165
- findings.append(Finding("backlog", str(path), message))
186
+ findings.append(Finding("backlog", str(path), message, project=slug))
166
187
  return findings
167
188
 
168
189
 
@@ -215,7 +236,7 @@ def dangling_references(vault: Path, _embedder: Embedder) -> list[Finding]:
215
236
  if not target.is_file():
216
237
  mention = match[0].removeprefix(f"{vault}/")
217
238
  message = f"line {number}: names {mention}, which does not exist"
218
- findings.append(Finding("reference", str(path), message))
239
+ findings.append(Finding("reference", str(path), message, project=slug))
219
240
  return findings
220
241
 
221
242
 
@@ -238,10 +259,10 @@ def spec_statuses(vault: Path, _embedder: Embedder) -> list[Finding]:
238
259
  continue
239
260
  except FrontmatterError:
240
261
  message = "frontmatter cannot be parsed; status ignored"
241
- findings.append(Finding("spec", str(path), message))
262
+ findings.append(Finding("spec", str(path), message, project=slug))
242
263
  continue
243
264
  findings.extend(
244
- Finding("spec", str(path), problem)
265
+ Finding("spec", str(path), problem, project=slug)
245
266
  for problem in specs.status_problems(meta, filename=path.name, siblings=siblings)
246
267
  )
247
268
  return findings
@@ -589,7 +610,10 @@ def local_instructions(vault: Path, _embedder: Embedder) -> list[Finding]:
589
610
  for slug in paths.iter_project_slugs(vault):
590
611
  project = projects.get(slug)
591
612
  root = Path(project.root) if project and project.root else None
592
- findings.extend(_project_local_findings(vault, slug, root, projects))
613
+ findings.extend(
614
+ replace(finding, project=slug)
615
+ for finding in _project_local_findings(vault, slug, root, projects)
616
+ )
593
617
  return findings
594
618
 
595
619
 
@@ -654,6 +678,7 @@ def orphaned_commits(vault: Path, _embedder: Embedder) -> list[Finding]:
654
678
  "commits",
655
679
  str(log),
656
680
  f"lists {count} commit{plural} no branch contains; run: sessionmemory reconcile",
681
+ project=slug,
657
682
  )
658
683
  )
659
684
  return findings
@@ -690,7 +715,9 @@ def stale_indexes(vault: Path, embedder: Embedder) -> list[Finding]:
690
715
  for directory in paths.iter_index_dirs(vault):
691
716
  message = _is_stale(directory, embedder)
692
717
  if message:
693
- findings.append(Finding("index", str(directory), message))
718
+ findings.append(
719
+ Finding("index", str(directory), message, project=directory.parent.name)
720
+ )
694
721
  return findings
695
722
 
696
723
 
@@ -709,6 +736,29 @@ CHECKS: tuple[Callable[[Path, Embedder], list[Finding]], ...] = (
709
736
  )
710
737
 
711
738
 
739
+ def short_path(vault: Path, finding: Finding) -> str:
740
+ """Return the finding's path as a report under its project heading shows it.
741
+
742
+ A path in the project's vault folder is made relative to that folder. A checkout path
743
+ stays whole, since a project can have several checkouts and a relative one would read
744
+ as a vault path. The `project` check names a slug, not a path, so it shows none.
745
+
746
+ Args:
747
+ vault: The vault the finding came from.
748
+ finding: One finding from `run`.
749
+
750
+ Returns:
751
+ The path to show, or empty when there is none.
752
+ """
753
+ if finding.check == "project":
754
+ return ""
755
+ if not (finding.project and finding.path):
756
+ return finding.path
757
+ path = Path(finding.path)
758
+ folder = paths.project_dir(vault, finding.project)
759
+ return path.relative_to(folder).as_posix() if path.is_relative_to(folder) else finding.path
760
+
761
+
712
762
  def run(vault: Path, embedder: Embedder) -> list[Finding]:
713
763
  """Run every check and return what they found, one failing check never stopping the rest."""
714
764
  findings: list[Finding] = []
@@ -153,7 +153,11 @@ all for a script.
153
153
  `{command} new backlog --kind <kind> --size <S|M|L> --title "..." --topic <topic> --cwd .`,
154
154
  which writes that shape and creates the file or heading when missing. Keep the
155
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
156
+ `--detail "..."`, in single quotes when it holds a backtick or `$`. Write the item
157
+ for the user reading it weeks later, who knows the product but not the code and
158
+ never saw this session: say what changes in the product's words, not this
159
+ session's terms or the code's names, and put files and approach in the detail,
160
+ with the reason when it is not obvious. Questions for
157
161
  the user to answer go under `## decide`. Delete a finished item with its detail,
158
162
  and one that will never be done, directly; never tick or annotate it. Git history is the record of what was finished.
159
163
  - Specs: `specs/` holds one design record per feature, named `<date>-<topic>.md`
@@ -1099,45 +1099,75 @@ def relative_imports(text: str) -> list[str]:
1099
1099
 
1100
1100
  @dataclass(frozen=True)
1101
1101
  class LinkResult:
1102
- """The outcome of linking one entry, with why and how to resolve it for a conflict."""
1102
+ """The outcome of linking one entry, with why and how to resolve it for a conflict.
1103
+
1104
+ Attributes:
1105
+ entry (Entry): The entry linked.
1106
+ status (LinkStatus): What happened.
1107
+ state (State): What the checkout held at the link path.
1108
+ reason (str | None): For a conflict, one line naming the entry and the cause.
1109
+ remedy (str | None): For a conflict, the step that resolves that cause.
1110
+ details (tuple[str, ...]): For a conflict, the labeled paths the reason refers to,
1111
+ kept out of it so the reason stays one short line.
1112
+ """
1103
1113
 
1104
1114
  entry: Entry
1105
1115
  status: LinkStatus
1106
1116
  state: State
1107
1117
  reason: str | None = None
1108
1118
  remedy: str | None = None
1119
+ details: tuple[str, ...] = ()
1109
1120
 
1110
1121
 
1111
- def _conflict_reason(co: Checkout, item: Entry, current: State) -> tuple[str, str]:
1112
- """Name why the entry was not linked and the remedy that fits that cause."""
1122
+ def _conflict(item: Entry, current: State, co: Checkout) -> LinkResult:
1123
+ """Build the conflict result naming why the entry was not linked and the fitting remedy."""
1113
1124
  if blocked(co, item):
1114
- folder = blocking_folder(co, item)
1115
- return (
1116
- f"{folder} or its parent is a symlink or not a folder, so {item.name} was not linked",
1117
- "Replace it with a real folder, then run local sync.",
1125
+ return LinkResult(
1126
+ item,
1127
+ "conflict",
1128
+ current,
1129
+ reason=f"{item.relpath} was not linked; a folder above it is a symlink or not a folder",
1130
+ remedy="Replace it with a real folder, then run local sync.",
1131
+ details=(f"folder: {blocking_folder(co, item)}",),
1118
1132
  )
1119
1133
  if current is State.FOREIGN_LINK:
1120
- return (
1121
- f"{item.link} is a symlink to {item.link.resolve()}, not to the vault copy",
1122
- "Remove it and run local sync to link the vault copy, or run local status to compare.",
1134
+ return LinkResult(
1135
+ item,
1136
+ "conflict",
1137
+ current,
1138
+ reason=f"{item.relpath} is a symlink to somewhere other than the vault copy",
1139
+ remedy="Remove it and run local sync to link the vault copy, or run local status to compare.",
1140
+ details=(f"points to: {item.link.resolve()}",),
1123
1141
  )
1124
1142
  if current is State.DIVERGED:
1143
+ both = (f"checkout: {item.link}", f"vault: {item.target}")
1125
1144
  try:
1126
1145
  match = contents_match(item)
1127
1146
  except OSError:
1128
1147
  match = None
1129
1148
  if match is True:
1130
- return (
1131
- f"{item.link} is a copy identical to the vault copy",
1132
- f"Run local adopt {shlex.quote(item.name)} to replace it with the link.",
1149
+ return LinkResult(
1150
+ item,
1151
+ "conflict",
1152
+ current,
1153
+ reason=f"{item.relpath} is a copy identical to the vault copy",
1154
+ remedy=f"Run local adopt {shlex.quote(item.name)} to replace it with the link.",
1155
+ details=both,
1133
1156
  )
1134
- return (
1135
- f"{item.link} differs from the vault copy at {item.target}",
1136
- f"{REPLACE_VAULT_COPY[0].upper()}{REPLACE_VAULT_COPY[1:]}.",
1157
+ return LinkResult(
1158
+ item,
1159
+ "conflict",
1160
+ current,
1161
+ reason=f"{item.relpath} differs from the vault copy",
1162
+ remedy=f"{REPLACE_VAULT_COPY[0].upper()}{REPLACE_VAULT_COPY[1:]}.",
1163
+ details=both,
1137
1164
  )
1138
- return (
1139
- f"something appeared at {item.link} while it was being linked",
1140
- "Run local status to see what is there.",
1165
+ return LinkResult(
1166
+ item,
1167
+ "conflict",
1168
+ current,
1169
+ reason=f"something appeared at {item.relpath} while it was being linked",
1170
+ remedy="Run local status to see what is there.",
1141
1171
  )
1142
1172
 
1143
1173
 
@@ -1161,22 +1191,18 @@ def link(co: Checkout, item: Entry, *, tracked: bool) -> LinkResult:
1161
1191
  """
1162
1192
  current = state(item)
1163
1193
 
1164
- def conflict(now: State) -> LinkResult:
1165
- reason, remedy = _conflict_reason(co, item, now)
1166
- return LinkResult(item, "conflict", now, reason=reason, remedy=remedy)
1167
-
1168
1194
  if not _present(item.target, item.kind):
1169
1195
  msg = f"the vault holds no {item.name}"
1170
1196
  raise LocalMdError(msg, [f"Nothing is at {item.target}."])
1171
1197
  if blocked(co, item):
1172
- return conflict(current)
1198
+ return _conflict(item, current, co)
1173
1199
  if tracked:
1174
1200
  return LinkResult(item, "tracked", current)
1175
1201
  if current is State.LINKED:
1176
1202
  ensure_ignored(co, item)
1177
1203
  return LinkResult(item, "present", current)
1178
1204
  if current in {State.DIVERGED, State.FOREIGN_LINK}:
1179
- return conflict(current)
1205
+ return _conflict(item, current, co)
1180
1206
 
1181
1207
  # The folder first, so a failure leaves no exclude line; the line before the link,
1182
1208
  # so the link never exists unignored.
@@ -1185,7 +1211,7 @@ def link(co: Checkout, item: Entry, *, tracked: bool) -> LinkResult:
1185
1211
  if current is State.DANGLING:
1186
1212
  localtree.place_link(item.link, item.target)
1187
1213
  elif not localtree.create_link(item.link, item.target):
1188
- return conflict(state(item))
1214
+ return _conflict(item, state(item), co)
1189
1215
  return LinkResult(item, "created", current)
1190
1216
 
1191
1217
 
@@ -1737,7 +1763,9 @@ def relink(co: Checkout, item: Entry, *, tracked: bool) -> LinkResult:
1737
1763
  item.link.symlink_to(previous)
1738
1764
  except OSError as err:
1739
1765
  msg = f"could not link {item.link}, and could not restore its link to {previous}: {err}"
1740
- raise LocalMdError(msg, [result.reason] if result.reason else []) from err
1766
+ raise LocalMdError(
1767
+ msg, [*([result.reason] if result.reason else []), *result.details]
1768
+ ) from err
1741
1769
  return result
1742
1770
 
1743
1771
 
@@ -1,27 +0,0 @@
1
- """The `doctor` command: report what is off, never fail over it."""
2
-
3
- from __future__ import annotations
4
-
5
- from nclutils import pp
6
-
7
- from sessionmemory.commands._common import JSON_OPTION, build_embedder, emit_json, require_vault
8
- from sessionmemory.lib import doctor
9
-
10
-
11
- def doctor_command(*, as_json: bool = JSON_OPTION) -> None:
12
- """Report pages, projects, and indexes worth a look. Always exits 0."""
13
- vault = require_vault()
14
- findings = doctor.run(vault, build_embedder())
15
- if as_json:
16
- emit_json([{"check": f.check, "path": f.path, "message": f.message} for f in findings])
17
- return
18
- if not findings:
19
- pp.success("nothing to report")
20
- return
21
- pp.info(
22
- f"{len(findings)} suggestion{'s' if len(findings) != 1 else ''}",
23
- details=[
24
- f"{f.check}: {f.path}: {f.message}" if f.path else f"{f.check}: {f.message}"
25
- for f in findings
26
- ],
27
- )