smd-engine 0.5.0__tar.gz → 0.5.2__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 (142) hide show
  1. {smd_engine-0.5.0 → smd_engine-0.5.2}/CHANGELOG.md +18 -0
  2. {smd_engine-0.5.0 → smd_engine-0.5.2}/PKG-INFO +1 -1
  3. {smd_engine-0.5.0 → smd_engine-0.5.2}/docs/commands.md +4 -2
  4. {smd_engine-0.5.0 → smd_engine-0.5.2}/docs/data-model.md +1 -1
  5. {smd_engine-0.5.0 → smd_engine-0.5.2}/docs/plan.md +5 -5
  6. {smd_engine-0.5.0 → smd_engine-0.5.2}/docs/stages.md +5 -2
  7. {smd_engine-0.5.0 → smd_engine-0.5.2}/pyproject.toml +1 -1
  8. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/cli.py +20 -5
  9. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/compare.py +20 -5
  10. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/eval.py +54 -3
  11. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/profile.py +17 -8
  12. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/render/assets/graph.js +2 -3
  13. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/render/graph.py +4 -1
  14. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/render/index.py +51 -15
  15. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/render/svg.py +165 -13
  16. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/render/text.py +4 -0
  17. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/sources.py +49 -16
  18. {smd_engine-0.5.0 → smd_engine-0.5.2}/tests/test_eval.py +20 -1
  19. {smd_engine-0.5.0 → smd_engine-0.5.2}/tests/test_graph.py +14 -0
  20. {smd_engine-0.5.0 → smd_engine-0.5.2}/tests/test_profile.py +26 -0
  21. {smd_engine-0.5.0 → smd_engine-0.5.2}/tests/test_publish.py +65 -1
  22. {smd_engine-0.5.0 → smd_engine-0.5.2}/tests/test_render_and_cli.py +74 -1
  23. {smd_engine-0.5.0 → smd_engine-0.5.2}/uv.lock +1 -1
  24. {smd_engine-0.5.0 → smd_engine-0.5.2}/.claude/agents/smd-game-technician.md +0 -0
  25. {smd_engine-0.5.0 → smd_engine-0.5.2}/.claude/agents/smd-methodologist.md +0 -0
  26. {smd_engine-0.5.0 → smd_engine-0.5.2}/.claude/agents/smd-visionary.md +0 -0
  27. {smd_engine-0.5.0 → smd_engine-0.5.2}/.claude/commands/procedure.md +0 -0
  28. {smd_engine-0.5.0 → smd_engine-0.5.2}/.flake8 +0 -0
  29. {smd_engine-0.5.0 → smd_engine-0.5.2}/.github/workflows/ci.yml +0 -0
  30. {smd_engine-0.5.0 → smd_engine-0.5.2}/.github/workflows/release.yml +0 -0
  31. {smd_engine-0.5.0 → smd_engine-0.5.2}/.gitignore +0 -0
  32. {smd_engine-0.5.0 → smd_engine-0.5.2}/.python-version +0 -0
  33. {smd_engine-0.5.0 → smd_engine-0.5.2}/CONTRIBUTING.md +0 -0
  34. {smd_engine-0.5.0 → smd_engine-0.5.2}/LICENSE +0 -0
  35. {smd_engine-0.5.0 → smd_engine-0.5.2}/README.md +0 -0
  36. {smd_engine-0.5.0 → smd_engine-0.5.2}/README_ru.md +0 -0
  37. {smd_engine-0.5.0 → smd_engine-0.5.2}/cases/example/bakeries-c1.board.yaml +0 -0
  38. {smd_engine-0.5.0 → smd_engine-0.5.2}/cases/example/bakeries-c2.board.yaml +0 -0
  39. {smd_engine-0.5.0 → smd_engine-0.5.2}/cases/example/golden/README.md +0 -0
  40. {smd_engine-0.5.0 → smd_engine-0.5.2}/cases/example/golden/bakeries-c2-expected.board.yaml +0 -0
  41. {smd_engine-0.5.0 → smd_engine-0.5.2}/cases/example/golden/s3_transcript.txt +0 -0
  42. {smd_engine-0.5.0 → smd_engine-0.5.2}/cases/example/patches/bakeries-c2-1.patch.yaml +0 -0
  43. {smd_engine-0.5.0 → smd_engine-0.5.2}/cases/example/sources.yaml +0 -0
  44. {smd_engine-0.5.0 → smd_engine-0.5.2}/cases/example/two-boards-c1.board.yaml +0 -0
  45. {smd_engine-0.5.0 → smd_engine-0.5.2}/cases/example_ru/pekarni-c1.board.yaml +0 -0
  46. {smd_engine-0.5.0 → smd_engine-0.5.2}/cases/example_ru/pekarni-c2.board.yaml +0 -0
  47. {smd_engine-0.5.0 → smd_engine-0.5.2}/cases/example_ru/pekarni-oru-c1.board.yaml +0 -0
  48. {smd_engine-0.5.0 → smd_engine-0.5.2}/cases/example_ru/sources.yaml +0 -0
  49. {smd_engine-0.5.0 → smd_engine-0.5.2}/docs/README.md +0 -0
  50. {smd_engine-0.5.0 → smd_engine-0.5.2}/docs/method/README.md +0 -0
  51. {smd_engine-0.5.0 → smd_engine-0.5.2}/docs/method/encodable.md +0 -0
  52. {smd_engine-0.5.0 → smd_engine-0.5.2}/docs/method/odi-problematization.md +0 -0
  53. {smd_engine-0.5.0 → smd_engine-0.5.2}/docs/method/reconciliation.md +0 -0
  54. {smd_engine-0.5.0 → smd_engine-0.5.2}/docs/method/roles-and-actors.md +0 -0
  55. {smd_engine-0.5.0 → smd_engine-0.5.2}/docs/method/smd-classic.md +0 -0
  56. {smd_engine-0.5.0 → smd_engine-0.5.2}/docs/method/sources.md +0 -0
  57. {smd_engine-0.5.0 → smd_engine-0.5.2}/docs/method/structural-moves.md +0 -0
  58. {smd_engine-0.5.0 → smd_engine-0.5.2}/docs/method/triz-systems.md +0 -0
  59. {smd_engine-0.5.0 → smd_engine-0.5.2}/docs/profiles.md +0 -0
  60. {smd_engine-0.5.0 → smd_engine-0.5.2}/lenses/README.md +0 -0
  61. {smd_engine-0.5.0 → smd_engine-0.5.2}/lenses/design-chain.md +0 -0
  62. {smd_engine-0.5.0 → smd_engine-0.5.2}/lenses/fliamer-diamond.md +0 -0
  63. {smd_engine-0.5.0 → smd_engine-0.5.2}/lenses/khaprov-levels.md +0 -0
  64. {smd_engine-0.5.0 → smd_engine-0.5.2}/lenses/khaprov-ontology.md +0 -0
  65. {smd_engine-0.5.0 → smd_engine-0.5.2}/lenses/scamper-check.md +0 -0
  66. {smd_engine-0.5.0 → smd_engine-0.5.2}/lenses/schukin-boundaries.md +0 -0
  67. {smd_engine-0.5.0 → smd_engine-0.5.2}/lenses/schukin-interface-tax.md +0 -0
  68. {smd_engine-0.5.0 → smd_engine-0.5.2}/lenses/three-positions.md +0 -0
  69. {smd_engine-0.5.0 → smd_engine-0.5.2}/lenses/triz-contradictions.md +0 -0
  70. {smd_engine-0.5.0 → smd_engine-0.5.2}/procedures/README.md +0 -0
  71. {smd_engine-0.5.0 → smd_engine-0.5.2}/procedures/field-result.md +0 -0
  72. {smd_engine-0.5.0 → smd_engine-0.5.2}/procedures/functional-plan.md +0 -0
  73. {smd_engine-0.5.0 → smd_engine-0.5.2}/procedures/ingest-transcript.md +0 -0
  74. {smd_engine-0.5.0 → smd_engine-0.5.2}/procedures/positional-construction.md +0 -0
  75. {smd_engine-0.5.0 → smd_engine-0.5.2}/procedures/problematization.md +0 -0
  76. {smd_engine-0.5.0 → smd_engine-0.5.2}/procedures/qualification-pass.md +0 -0
  77. {smd_engine-0.5.0 → smd_engine-0.5.2}/procedures/reflexive-protocol.md +0 -0
  78. {smd_engine-0.5.0 → smd_engine-0.5.2}/procedures/small-situation.md +0 -0
  79. {smd_engine-0.5.0 → smd_engine-0.5.2}/procedures/solo-session.md +0 -0
  80. {smd_engine-0.5.0 → smd_engine-0.5.2}/procedures/theses-to-board.md +0 -0
  81. {smd_engine-0.5.0 → smd_engine-0.5.2}/procedures/visionary-tract.md +0 -0
  82. {smd_engine-0.5.0 → smd_engine-0.5.2}/profiles/classic-two-boards.yaml +0 -0
  83. {smd_engine-0.5.0 → smd_engine-0.5.2}/profiles/management-four-boards.yaml +0 -0
  84. {smd_engine-0.5.0 → smd_engine-0.5.2}/profiles/program-three-boards.yaml +0 -0
  85. {smd_engine-0.5.0 → smd_engine-0.5.2}/roles/README.md +0 -0
  86. {smd_engine-0.5.0 → smd_engine-0.5.2}/roles/actors.md +0 -0
  87. {smd_engine-0.5.0 → smd_engine-0.5.2}/roles/game-technician.md +0 -0
  88. {smd_engine-0.5.0 → smd_engine-0.5.2}/roles/methodologist.md +0 -0
  89. {smd_engine-0.5.0 → smd_engine-0.5.2}/roles/researcher.md +0 -0
  90. {smd_engine-0.5.0 → smd_engine-0.5.2}/roles/visionary.md +0 -0
  91. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/__init__.py +0 -0
  92. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/apply.py +0 -0
  93. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/migrate.py +0 -0
  94. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/pack.py +0 -0
  95. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/records.py +0 -0
  96. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/render/__init__.py +0 -0
  97. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/render/assets/frames.css +0 -0
  98. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/render/assets/frames.js +0 -0
  99. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/render/assets/graph.css +0 -0
  100. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/render/frames.py +0 -0
  101. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/render/frames_page.py +0 -0
  102. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/render/frames_text.py +0 -0
  103. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/render/graph_ui.py +0 -0
  104. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/render/html.py +0 -0
  105. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/render/layout.py +0 -0
  106. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/render/light.py +0 -0
  107. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/render/markdown.py +0 -0
  108. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/render/mermaid.py +0 -0
  109. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/render/sessionflow.py +0 -0
  110. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/render/vault.py +0 -0
  111. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/revise.py +0 -0
  112. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/schemas/__init__.py +0 -0
  113. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/schemas/board_patch.schema.json +0 -0
  114. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/schemas/board_set.schema.json +0 -0
  115. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/schemas/source_manifest.schema.json +0 -0
  116. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/schemas/taxonomies.schema.json +0 -0
  117. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/screen.py +0 -0
  118. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/validate/__init__.py +0 -0
  119. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/validate/context.py +0 -0
  120. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/validate/hints.py +0 -0
  121. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/validate/hypotheses.py +0 -0
  122. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/validate/management.py +0 -0
  123. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/validate/manifest.py +0 -0
  124. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/validate/ontology.py +0 -0
  125. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/validate/signoffs.py +0 -0
  126. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/validate/structure.py +0 -0
  127. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/validate/taxonomies.py +0 -0
  128. {smd_engine-0.5.0 → smd_engine-0.5.2}/src/smd_engine/validate/theses.py +0 -0
  129. {smd_engine-0.5.0 → smd_engine-0.5.2}/tests/conftest.py +0 -0
  130. {smd_engine-0.5.0 → smd_engine-0.5.2}/tests/test_action_program.py +0 -0
  131. {smd_engine-0.5.0 → smd_engine-0.5.2}/tests/test_apply.py +0 -0
  132. {smd_engine-0.5.0 → smd_engine-0.5.2}/tests/test_compare.py +0 -0
  133. {smd_engine-0.5.0 → smd_engine-0.5.2}/tests/test_export.py +0 -0
  134. {smd_engine-0.5.0 → smd_engine-0.5.2}/tests/test_frames.py +0 -0
  135. {smd_engine-0.5.0 → smd_engine-0.5.2}/tests/test_ingestion.py +0 -0
  136. {smd_engine-0.5.0 → smd_engine-0.5.2}/tests/test_lenses.py +0 -0
  137. {smd_engine-0.5.0 → smd_engine-0.5.2}/tests/test_management.py +0 -0
  138. {smd_engine-0.5.0 → smd_engine-0.5.2}/tests/test_migrate.py +0 -0
  139. {smd_engine-0.5.0 → smd_engine-0.5.2}/tests/test_procedures.py +0 -0
  140. {smd_engine-0.5.0 → smd_engine-0.5.2}/tests/test_record_boards.py +0 -0
  141. {smd_engine-0.5.0 → smd_engine-0.5.2}/tests/test_revise.py +0 -0
  142. {smd_engine-0.5.0 → smd_engine-0.5.2}/tests/test_validate.py +0 -0
@@ -2,6 +2,24 @@
2
2
 
3
3
  Dates are those of the tag. All tags v0.2.1 to v0.3.5 were made on 2026-10-29. The version in `pyproject.toml` stayed at 0.2.0 through v0.2.4 and at 0.3.0 from v0.3.0 to v0.3.5; 0.3.6 is the first release whose package version equals its tag.
4
4
 
5
+ ## 0.5.2 - 2026-10-29
6
+
7
+ - The public export leaves out `tests/test_export_public.py`, which tests the maintainer tool that the export also leaves out; 0.5.1 was not released publicly for this reason.
8
+
9
+ ## 0.5.1 - 2026-10-29
10
+
11
+ Follow-ups; no change to the schema or the records.
12
+
13
+ - `smd eval` prints the `run` block of both records and matches the qualifications (K) by their text and the hypotheses (H) by what they assume, as `smd compare` matches K: matched pairs, then those only in the run and only in the expected record. These lines add no threshold.
14
+ - A profile is refused with a `ProfileError` when a colour is not written `#rrggbb` in lowercase, when `compare_groups` is `null`, and when the `id` of a board, template, kind or relation is missing or not a string.
15
+ - `smd sources --refresh` also writes `lines` for a source whose entry carries it, editing that line only; before, `sha256` was refreshed and `lines` went stale.
16
+ - `tests/test_export_public.py` covers the scan of `scripts/export_public.py` (one planted leak of each pattern; a clean tree) and its argument checks.
17
+ - `docs/plan.md` and `docs/stages.md` give the release tags of the steps of the 2026-10-29 update (v0.2.1 to v0.5.0) and say that a release tag is not a schema version.
18
+ - `smd graph`: the height of each plane comes from `render/graph.py` (`LAYER`) in the model as `planes`; `graph.js` no longer repeats the spacing (260, 520). The planes stand where they stood; the graph pages differ only by that key and those lines.
19
+ - Screen: a relation label stands above the middle of its link unless it covers a label placed before it, an element box (of a frame, its heading; of a figure, its icon and caption), a board or half heading or a K badge. Then it takes the nearest spot that covers nothing, at most 4 lines (60 px) up or down and half its width sideways, in one line or wrapped to 220 px; with none free, the spot that covers least, its own spot winning ties, so no label moves to a worse place. Spots are computed on the whole record, so frames and cut screens keep them. On `mipt-transfer-c5` the overlapping pairs go from 122 to 53 between labels and from 163 to 135 between labels and boxes. Labels that cover nothing keep their spot; in the examples three labels move one line (`two-boards-c1`: «looks back at», «dough»; `pekarni-oru-c1`: «усилить»), whose spot covered an element.
20
+ - `smd publish --strict` fails on warnings of the published record only; warnings of the earlier cycles it `revises` are printed with "(earlier cycle: not failing)". Errors anywhere in the chain still fail.
21
+ - `smd publish` writes the index with links relative to `--out` (`render_index(..., base=)`): the record file and `--archive` files by relative path, a file that shares only the root with `--out` without a link, and `YAML:N` as a line number, so no absolute path of the building machine is in the bundle. `smd index` keeps its absolute `file://` and `vscode://` links.
22
+
5
23
  ## 0.5.0 - 2026-10-29
6
24
 
7
25
  The first public release since 0.3.7; it also carries 0.3.8 and 0.4.0, which were tagged in the private repository only.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: smd-engine
3
- Version: 0.5.0
3
+ Version: 0.5.2
4
4
  Summary: Records, checks and renderings for SMD-style thinking sessions (three boards, cycles, qualifications)
5
5
  Project-URL: Homepage, https://github.com/viberesearch/smd-engine
6
6
  Project-URL: Repository, https://github.com/viberesearch/smd-engine
@@ -27,9 +27,9 @@ uv run smd vault cases/example/bakeries-c2.board.yaml out/vault --sources cases/
27
27
  uv run smd pack solo-session cases/example/bakeries-c2.board.yaml --sources cases/example/sources.yaml -o out/pack.md # attach to any model; --sources carries the manifest, --taxonomies the taxonomy file; with board sets, the skeleton of the latest cycle as "Cells to fill"
28
28
  uv run smd sources cases/example/sources.yaml --clean-room --deny-lineage earlier-concept
29
29
  uv run smd sources path/to/sources.yaml --folder /local/folder
30
- uv run smd sources path/to/sources.yaml --folder /local/folder --refresh [ids] # recompute sha256 of the named sources (default: every decision_log) and edit only the sha256 lines of the manifest
30
+ uv run smd sources path/to/sources.yaml --folder /local/folder --refresh [ids] # recompute sha256 of the named sources (default: every decision_log) and, where a source carries `lines`, its line count; edit only those lines of the manifest
31
31
  uv run smd compare a.board.yaml b.board.yaml -o out/compare.md --merge out/merge.board.yaml
32
- uv run smd eval run.board.yaml cases/example/golden/bakeries-c2-expected.board.yaml --min-agreement 10 --max-only-expected 3 # did a procedure run get worse: the five compare counts, theses matched by cites; exit 1 on a missed threshold
32
+ uv run smd eval run.board.yaml cases/example/golden/bakeries-c2-expected.board.yaml --min-agreement 10 --max-only-expected 3 # did a procedure run get worse: the five compare counts, the `run` blocks of both records, theses matched by cites, K and H matched by wording; exit 1 on a missed threshold
33
33
  uv run smd revise cases/example/bakeries-c2.board.yaml --decisions decisions.yaml -o out/bakeries-c3.board.yaml # next cycle with the human's sign-offs applied
34
34
  uv run smd apply cases/example/bakeries-c2.board.yaml cases/example/patches/bakeries-c2-1.patch.yaml -o out/bakeries-c2.board.yaml --sources cases/example/sources.yaml # a decision on the current cycle as a patch (set and remove by id or by transition number n, board_notes): the next sub-version, validated (also --taxonomies); nothing is written on errors
35
35
  ```
@@ -39,6 +39,8 @@ uv run smd apply cases/example/bakeries-c2.board.yaml cases/example/patches/bake
39
39
  - **warning:** breaks a convention of the method, e.g. an item with no position it is seen from.
40
40
  - **hint** (with `--hints`): a methodological observation, e.g. an empty small situation, or a new frame with no functional plan.
41
41
 
42
+ `publish` validates the record and the earlier cycles it `revises` (found next to it). An error anywhere in that chain stops the bundle. With `--strict`, a warning on the published record stops it too; warnings on earlier cycles are printed, marked "earlier cycle: not failing", and the bundle is written. The bundle's index links files relative to the `--out` folder, so the folder can be moved or sent: the record file and `--archive` files are linked by relative paths, a file that shares no folder with `--out` except the root is named without a link, and `YAML:N` is a line number, not a VS Code link. `smd index` keeps absolute `file://` and `vscode://` links for use on the building machine.
43
+
42
44
  `sources --folder` checks that every listed file is present, has a sha256, and matches it. `--refresh` rewrites the sha256 instead, for logs that grow.
43
45
 
44
46
  `compare` matches the elements of two board sets by kind group and wording and classifies each pair as agreement, refinement, conflict, or present in one set only. `--merge` writes a draft cycle on top of B: elements only in A are imported as hypotheses with a `from-<A>` lineage tag, and each conflict becomes an open K with the options lock, fork, rebase, merge. Matching by wording is a heuristic; the report is material for a qualification pass.
@@ -206,7 +206,7 @@ signoffs:
206
206
 
207
207
  `smd sources --clean-room --deny-lineage <tags>` splits sources into allowed and denied for a run that must not see a given lineage.
208
208
 
209
- `smd sources <manifest> --folder F --refresh [ids]` recomputes `sha256` for the named sources (default: every `decision_log`) from the files in F and edits only those `sha256:` lines in the manifest text (comments and formatting stay; a source with a `file:` line and no `sha256:` gets one); file names are matched after Unicode NFC normalisation.
209
+ `smd sources <manifest> --folder F --refresh [ids]` recomputes `sha256` (and `lines`, for a source that carries it) for the named sources (default: every `decision_log`) from the files in F and edits only those `sha256:` and `lines:` lines in the manifest text (comments and formatting stay; a source with a `file:` line and no `sha256:` gets one); file names are matched after Unicode NFC normalisation.
210
210
 
211
211
  ## taxonomies: the values of tags
212
212
 
@@ -53,7 +53,7 @@ Each step is a branch and a PR in this repository. Each change to a case reposit
53
53
  - 0b: case sources. Each case has one manifest; raw files stay where they are.
54
54
 
55
55
  **Step 1. Records, validator, renderer.**
56
- - Schemas v0.2.
56
+ - Schemas v0.2 (released in v0.1.0; schema v0.2 is not release v0.2.x: the schema stayed v0.2 until v0.2.4).
57
57
  - Validator: structural checks plus semantic levels (dangling references, element without a position, frame without a chain, K pointing at nothing, transitions out of order).
58
58
  - SVG/HTML renderer in the program's three-board layout, with automatic placement inside board regions and optional manual geometry.
59
59
  - Done when: `uv run pytest` passes, black and flake8 are clean, and two golden screens render.
@@ -86,13 +86,13 @@ Each step is a branch and a PR in this repository. Each change to a case reposit
86
86
  - Prompts run without Claude Code: any model, with the files attached.
87
87
  - Exports: SessionFlow formats ("Наша малая ситуация. Материал к сообщению", the module start message), Russian versions into the case repository by PR, journal entries.
88
88
 
89
- **Step 7. Decisions as records.** `board_patch` and `smd apply`; `smd publish` (validate, frames, index, graph in one run); `smd sources refresh` for growing decision logs. Done when: a pilot case's board of one sub-version is reproduced byte for byte from its predecessor and the committed patch.
89
+ **Step 7. Decisions as records.** `board_patch` and `smd apply`; `smd publish` (validate, frames, index, graph in one run); `smd sources refresh` for growing decision logs. Done when: a pilot case's board of one sub-version is reproduced byte for byte from its predecessor and the committed patch. Released as v0.2.2 (`sources --refresh`), v0.2.3 (`publish`), v0.3.1 (`apply`) and v0.3.4 (transitions by `n`, `board_notes`).
90
90
 
91
- **Step 8. Schema v0.3, migration, profiles.** Versioned schema files, `smd migrate`, the fields of item 13, taxonomies and tags, the profile mechanism with `classic-two-boards` as the second profile. Done when: every v0.2 record in `cases/` and in the pilot case's repository migrates and validates with zero errors, and the two-board fixture validates with no hint about a situation board.
91
+ **Step 8. Schema v0.3, migration, profiles.** Versioned schema files, `smd migrate`, the fields of item 13, taxonomies and tags, the profile mechanism with `classic-two-boards` as the second profile. Done when: every v0.2 record in `cases/` and in the pilot case's repository migrates and validates with zero errors, and the two-board fixture validates with no hint about a situation board. Released as v0.3.0 (schema v0.3, `smd migrate`, taxonomies, tags), v0.3.2 (profiles) and v0.3.5 (regions, graph colours).
92
92
 
93
- **Step 9. Quality across models.** Run stamp, `smd eval` on top of `compare`, a public golden run (invented bakeries transcript) and a private one in the case repository. Done when: `smd eval` on the stored plenary run reproduces the 25.10 counts.
93
+ **Step 9. Quality across models.** Run stamp, `smd eval` on top of `compare`, a public golden run (invented bakeries transcript) and a private one in the case repository. Done when: `smd eval` on the stored plenary run reproduces the 25.10 counts. Released as v0.3.3.
94
94
 
95
- **Step 10. Code structure.** Check registry in `validate/`, static assets out of `render/graph.py` and `render/frames.py`. No behaviour change: the test suite passes unchanged plus the registry test.
95
+ **Step 10. Code structure.** Check registry in `validate/`, static assets out of `render/graph.py` and `render/frames.py`. No behaviour change: the test suite passes unchanged plus the registry test. Released as v0.2.4. Later releases: v0.3.6 (open release), v0.3.7 (docs), v0.3.8, v0.4.0 and v0.5.0 (see `docs/stages.md`).
96
96
 
97
97
  ## Not in scope (report only)
98
98
 
@@ -1,6 +1,6 @@
1
1
  # Build steps and where each method enters
2
2
 
3
- Plan approved 2026-10-25 (`docs/plan.md`). Each step is a branch and a PR.
3
+ Plan approved 2026-10-25 (`docs/plan.md`). Each step is a branch and a PR. The steps of the 2026-10-29 update were released as v0.2.1 to v0.3.x; a release tag is not a schema version (schema v0.2 ran from v0.1.0 to v0.2.4, schema v0.3 starts at v0.3.0).
4
4
 
5
5
  | Step | Content | Status |
6
6
  |---|---|---|
@@ -18,8 +18,11 @@ Plan approved 2026-10-25 (`docs/plan.md`). Each step is a branch and a PR.
18
18
  | 8 | Schema v0.3, `smd migrate`, profiles, taxonomies and tags | done: schema v0.3, `smd migrate`, taxonomies and tags in v0.3.0 (PR #21); profiles in v0.3.2: `program-three-boards` (default) and `classic-two-boards`, fixture `cases/example/two-boards-c1.board.yaml` |
19
19
  | 9 | Run stamp, `smd eval`, golden runs (update plan step 9) | done in v0.3.3: `smd eval`, the `run` stamp on records, `cases/example/golden/` |
20
20
  | 10 | Code structure: check registry, render assets | done in v0.2.4: the validator is a package with a check registry; the frames and graph assets are package files |
21
- | docs | Architecture section, command tables and this file (update plan step 10) | done in the step after v0.3.6 |
21
+ | docs | Architecture section, command tables and this file (update plan step 10) | done in v0.3.7 |
22
22
  | 11 | Open release preparation (update plan step 11) | done in v0.3.6: licence, public READMEs, `README_ru.md`, `cases/example_ru/`, release workflow |
23
+ | Ш8-Ш12 | Gates Ш8-Ш12 (G.P.'s «Программа действий» against т. 5): element fields, hints, the three-positions lens | done in v0.3.8 |
24
+ | Ш13 | G.P.'s management scheme as the profile `management-four-boards` | done in v0.4.0 |
25
+ | boards | Record boards from profile templates; process boards on their own boards in the management profile | done in v0.5.0 |
23
26
 
24
27
  ## Structural moves (Invention as a Structural Operation)
25
28
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "smd-engine"
3
- version = "0.5.0"
3
+ version = "0.5.2"
4
4
  description = "Records, checks and renderings for SMD-style thinking sessions (three boards, cycles, qualifications)"
5
5
  readme = "README.md"
6
6
  license = "MIT AND CC-BY-4.0"
@@ -47,11 +47,13 @@ from smd_engine.render.svg import render_svg
47
47
  from smd_engine.render.vault import export_vault
48
48
  from smd_engine.revise import revise
49
49
  from smd_engine.sources import (
50
- find_file,
51
50
  check_files,
52
51
  clean_room,
52
+ find_file,
53
+ line_count,
53
54
  refresh,
54
55
  refresh_targets,
56
+ rewrite_line_counts,
55
57
  rewrite_sha_lines,
56
58
  source_ids,
57
59
  )
@@ -287,6 +289,10 @@ def _refresh_sources(args: argparse.Namespace, manifest: dict[str, Any]) -> int:
287
289
  changes = {s["id"]: s["sha256"] for s in targets if s["id"] in changed}
288
290
  manifest_path = Path(args.manifest)
289
291
  text = rewrite_sha_lines(manifest_path.read_text("utf-8"), changes)
292
+ counts = {
293
+ s["id"]: s["lines"] for s in targets if s["id"] in changed and "lines" in s
294
+ }
295
+ text = rewrite_line_counts(text, counts)
290
296
  except (ValueError, FileNotFoundError) as exc:
291
297
  print(exc, file=sys.stderr)
292
298
  return 1
@@ -296,8 +302,7 @@ def _refresh_sources(args: argparse.Namespace, manifest: dict[str, Any]) -> int:
296
302
  if src["id"] in changed:
297
303
  path = find_file(folder, src["file"])
298
304
  assert path is not None
299
- lines = len(path.read_bytes().splitlines())
300
- print(f"{src['id']}: sha256 updated, {lines} lines")
305
+ print(f"{src['id']}: sha256 updated, {line_count(path)} lines")
301
306
  else:
302
307
  print(f"{src['id']}: unchanged")
303
308
  if changed:
@@ -544,12 +549,16 @@ def cmd_publish(args: argparse.Namespace) -> int:
544
549
  taxonomies = _load_taxonomies(args.taxonomies)
545
550
  chain = _chain(path, data)
546
551
  failed = False
552
+ # errors fail anywhere in the chain; with --strict, warnings fail only on the
553
+ # published record, and those of the earlier cycles are reported
547
554
  for n, (file, rec) in enumerate(chain):
548
555
  prev = chain[n + 1][1] if n + 1 < len(chain) else None
549
556
  for f in validate_record(rec, ids, prev, taxonomies):
550
- if f.level == "error" or (args.strict and f.level == "warning"):
557
+ if f.level == "error" or (args.strict and f.level == "warning" and n == 0):
551
558
  print(f"{file}: {f}", file=sys.stderr)
552
559
  failed = True
560
+ elif args.strict and f.level == "warning":
561
+ print(f"{file}: {f} (earlier cycle: not failing)", file=sys.stderr)
553
562
  if failed:
554
563
  print("not published: the record does not validate", file=sys.stderr)
555
564
  return 1
@@ -572,12 +581,14 @@ def cmd_publish(args: argparse.Namespace) -> int:
572
581
  pages = {
573
582
  f"{name}_frames.html": render_frames_html(reading, args.lang),
574
583
  f"{name}_cycle_frames.html": render_frames_html(cycles, args.lang),
584
+ # links relative to the bundle folder, so that it can be moved or sent
575
585
  f"{name}_index.html": render_index(
576
586
  data,
577
587
  path,
578
588
  args.lang,
579
589
  manifest,
580
590
  Path(args.archive) if args.archive else None,
591
+ base=Path(args.out),
581
592
  ),
582
593
  f"{name}_graph.html": render_graph_html(data, args.lang, manifest),
583
594
  f"{name}.html": render_html(data, args.lang, screen=screen),
@@ -781,7 +792,11 @@ def build_parser() -> argparse.ArgumentParser:
781
792
  pb.add_argument("--zoom", action="store_true", help="as in frames")
782
793
  pb.add_argument("--notes", help="Markdown texts per frame, as in frames")
783
794
  pb.add_argument("--archive", help="folder with source files, as in index")
784
- pb.add_argument("--strict", action="store_true", help="fail on warnings")
795
+ pb.add_argument(
796
+ "--strict",
797
+ action="store_true",
798
+ help="fail on warnings of the record; those of earlier cycles are reported",
799
+ )
785
800
  pb.add_argument("--taxonomies", type=Path, help="taxonomy file, as in validate")
786
801
  pb.set_defaults(func=cmd_publish)
787
802
 
@@ -149,14 +149,13 @@ def _where(el: dict[str, Any]) -> str:
149
149
  return str(el["board"]) + (f"/{el['half']}" if el.get("half") else "")
150
150
 
151
151
 
152
- def compare_qualifications(
153
- a: dict[str, Any], b: dict[str, Any]
152
+ def _match_texts(
153
+ qa: list[dict[str, Any]], qb: list[dict[str, Any]], key: str
154
154
  ) -> list[tuple[str | None, str | None, float]]:
155
- """Match K items by text; unmatched ones keep None on the other side."""
156
- qa, qb = a.get("qualifications", []), b.get("qualifications", [])
155
+ """Match items by the wording of `key`; unmatched ones keep None on the other side."""
157
156
  scored = sorted(
158
157
  (
159
- (similarity(x["text"], y["text"]), i, j)
158
+ (similarity(x[key], y[key]), i, j)
160
159
  for i, x in enumerate(qa)
161
160
  for j, y in enumerate(qb)
162
161
  ),
@@ -176,6 +175,22 @@ def compare_qualifications(
176
175
  return out
177
176
 
178
177
 
178
+ def compare_qualifications(
179
+ a: dict[str, Any], b: dict[str, Any]
180
+ ) -> list[tuple[str | None, str | None, float]]:
181
+ """Match K items by text; unmatched ones keep None on the other side."""
182
+ return _match_texts(
183
+ a.get("qualifications", []), b.get("qualifications", []), "text"
184
+ )
185
+
186
+
187
+ def compare_hypotheses(
188
+ a: dict[str, Any], b: dict[str, Any]
189
+ ) -> list[tuple[str | None, str | None, float]]:
190
+ """Match H items by what they assume; unmatched ones keep None on the other side."""
191
+ return _match_texts(a.get("hypotheses", []), b.get("hypotheses", []), "assumes")
192
+
193
+
179
194
  def compare_boards(a: dict[str, Any], b: dict[str, Any]) -> list[str]:
180
195
  """The boards the records make of their profile's templates, matched by id:
181
196
  one line each, in both or in one, with a changed template or label and the
@@ -12,7 +12,7 @@ import re
12
12
  from dataclasses import dataclass, field
13
13
  from typing import Any
14
14
 
15
- from smd_engine.compare import compare
15
+ from smd_engine.compare import compare, compare_hypotheses, compare_qualifications
16
16
 
17
17
  WINDOW = 30 # seconds between two timecodes that still name the same utterance
18
18
  KINDS = ("agreement", "refinement", "conflict", "only_a", "only_b")
@@ -40,6 +40,26 @@ class EvalResult:
40
40
  only_run: list[tuple[str, str]] # (thesis id, cites)
41
41
  only_expected: list[tuple[str, str]]
42
42
  failures: list[str] = field(default_factory=list)
43
+ run_block: dict[str, Any] | None = None # the run's `run` stamp
44
+ expected_block: dict[str, Any] | None = None # the expected record's stamp
45
+ # K and H matched by wording: (run id, expected id) pairs, then the ids left over
46
+ qualifications: ItemMatch | None = None
47
+ hypotheses: ItemMatch | None = None
48
+
49
+
50
+ @dataclass
51
+ class ItemMatch:
52
+ matched: list[tuple[str, str]]
53
+ only_run: list[str]
54
+ only_expected: list[str]
55
+
56
+
57
+ def _item_match(pairs: list[tuple[str | None, str | None, float]]) -> ItemMatch:
58
+ return ItemMatch(
59
+ [(a, b) for a, b, _ in pairs if a and b],
60
+ [a for a, b, _ in pairs if a and not b],
61
+ [b for a, b, _ in pairs if b and not a],
62
+ )
43
63
 
44
64
 
45
65
  def parse_cite(cite: str) -> Address:
@@ -113,7 +133,16 @@ def evaluate(
113
133
  for pair in compare(run, expected):
114
134
  counts[pair.kind] += 1
115
135
  matched, only_run, only_expected = match_theses(run, expected)
116
- result = EvalResult(counts, matched, only_run, only_expected)
136
+ result = EvalResult(
137
+ counts,
138
+ matched,
139
+ only_run,
140
+ only_expected,
141
+ run_block=run.get("run"),
142
+ expected_block=expected.get("run"),
143
+ qualifications=_item_match(compare_qualifications(run, expected)),
144
+ hypotheses=_item_match(compare_hypotheses(run, expected)),
145
+ )
117
146
  if min_agreement is not None and counts["agreement"] < min_agreement:
118
147
  result.failures.append(
119
148
  f"agreement {counts['agreement']} is below the minimum {min_agreement}"
@@ -125,9 +154,19 @@ def evaluate(
125
154
  return result
126
155
 
127
156
 
157
+ def _stamp(block: dict[str, Any] | None) -> str:
158
+ """The `run` block as `key=value` pairs, or `none` when the record has no stamp."""
159
+ if not block:
160
+ return "none"
161
+ return ", ".join(f"{k}={v}" for k, v in block.items())
162
+
163
+
128
164
  def format_result(result: EvalResult) -> str:
129
- """Plain text: the five counts, then the theses matched and unmatched."""
165
+ """Plain text: the five counts, the run blocks, the theses, K and H."""
130
166
  out = [" · ".join(f"{k} {result.counts[k]}" for k in KINDS), ""]
167
+ out.append(f"run: {_stamp(result.run_block)}")
168
+ out.append(f"expected: {_stamp(result.expected_block)}")
169
+ out.append("")
131
170
  out.append(f"theses matched by cites ({len(result.matched)}):")
132
171
  for m in result.matched:
133
172
  out.append(f" {m.run} = {m.expected} {m.run_cite} / {m.expected_cite}")
@@ -135,6 +174,18 @@ def format_result(result: EvalResult) -> str:
135
174
  out += [f" {tid} {cites}" for tid, cites in result.only_run]
136
175
  out.append(f"theses only in the expected record ({len(result.only_expected)}):")
137
176
  out += [f" {tid} {cites}" for tid, cites in result.only_expected]
177
+ for name, items in (
178
+ ("qualifications", result.qualifications),
179
+ ("hypotheses", result.hypotheses),
180
+ ):
181
+ if items is None:
182
+ continue
183
+ out.append(f"{name} matched by wording ({len(items.matched)}):")
184
+ out += [f" {a} = {b}" for a, b in items.matched]
185
+ out.append(f"{name} only in the run ({len(items.only_run)}):")
186
+ out += [f" {i}" for i in items.only_run]
187
+ out.append(f"{name} only in the expected record ({len(items.only_expected)}):")
188
+ out += [f" {i}" for i in items.only_expected]
138
189
  for failure in result.failures:
139
190
  out.append(f"FAIL: {failure}")
140
191
  return "\n".join(out) + "\n"
@@ -43,7 +43,7 @@ SHAPES = {
43
43
  "box",
44
44
  }
45
45
  SCREENS = ("regions", "triangles")
46
- COLOUR = re.compile(r"#[0-9a-fA-F]{6}")
46
+ COLOUR = re.compile(r"#[0-9a-f]{6}")
47
47
  # The id of a board a record makes of a template: the schema's id less the
48
48
  # dot, which separates a board from its half (`s.small`).
49
49
  RECORD_BOARD_ID = re.compile(r"[a-z0-9][a-z0-9_-]*")
@@ -313,6 +313,13 @@ def _keys(raw: dict[str, Any], allowed: set[str], where: str) -> None:
313
313
  raise ProfileError(f"{where}: unknown keys {unknown}")
314
314
 
315
315
 
316
+ def _id(raw: dict[str, Any], where: str) -> str:
317
+ value = raw.get("id")
318
+ if not isinstance(value, str) or not value:
319
+ raise ProfileError(f"{where}: id is missing or not a string")
320
+ return value
321
+
322
+
316
323
  def _flags(raw: dict[str, Any], names: tuple[str, ...], where: str) -> dict[str, bool]:
317
324
  flags = {f: raw.get(f, False) for f in names}
318
325
  not_bool = [f for f, v in flags.items() if not isinstance(v, bool)]
@@ -345,7 +352,7 @@ def _board(raw: dict[str, Any], where: str) -> Board:
345
352
  if len(region) != 4 or not all(map(_number, region)) or len(colour) != 2:
346
353
  raise ProfileError(f"{where}: region takes 4 numbers, colour 2 colours")
347
354
  if not all(COLOUR.fullmatch(c) for c in colour):
348
- raise ProfileError(f"{where}: a colour is written #rrggbb")
355
+ raise ProfileError(f"{where}: a colour is written #rrggbb, lowercase")
349
356
  x0, y0, x1, y1 = region
350
357
  left, top, right, _ = MARGIN
351
358
  if not (
@@ -364,7 +371,7 @@ def _board(raw: dict[str, Any], where: str) -> Board:
364
371
  f"{where}: split must lie inside the region, more than 10 from each edge"
365
372
  )
366
373
  return Board(
367
- str(raw["id"]),
374
+ _id(raw, where),
368
375
  _labels(raw.get("label"), where),
369
376
  ordered,
370
377
  (x0, y0, x1, y1),
@@ -383,12 +390,14 @@ def _template(raw: dict[str, Any], where: str) -> Template:
383
390
  raise ProfileError(f"{where}: per_record must be true")
384
391
  colour = tuple(str(c) for c in raw["colour"])
385
392
  if len(colour) != 2 or not all(COLOUR.fullmatch(c) for c in colour):
386
- raise ProfileError(f"{where}: colour takes 2 colours, each #rrggbb")
393
+ raise ProfileError(
394
+ f"{where}: colour takes 2 colours, each #rrggbb in lowercase"
395
+ )
387
396
  kinds = _strings(raw.get("kinds"), f"{where}: kinds")
388
397
  if not kinds:
389
398
  raise ProfileError(f"{where}: a template takes at least one kind")
390
399
  return Template(
391
- str(raw["id"]),
400
+ _id(raw, where),
392
401
  _labels(raw.get("label"), where),
393
402
  (colour[0], colour[1]),
394
403
  kinds,
@@ -445,7 +454,7 @@ def _kind(raw: dict[str, Any], boards: set[str], where: str) -> Kind:
445
454
  if raw.get("shape") not in SHAPES:
446
455
  raise ProfileError(f"{where}: shape must be one of {', '.join(sorted(SHAPES))}")
447
456
  return Kind(
448
- str(raw["id"]),
457
+ _id(raw, where),
449
458
  _labels(raw.get("label"), where),
450
459
  raw.get("home"),
451
460
  shape=str(raw["shape"]),
@@ -585,7 +594,7 @@ def _relations(items: Any, name: str) -> dict[str, dict[str, str]]:
585
594
  rid, label = raw, {}
586
595
  elif isinstance(raw, dict):
587
596
  _keys(raw, RELATION_KEYS, f"{name}: relation {raw.get('id')}")
588
- rid = str(raw["id"])
597
+ rid = _id(raw, f"{name}: relation {raw.get('id')}")
589
598
  label = _labels(raw.get("label"), f"{name}: relation {rid}")
590
599
  else:
591
600
  raise ProfileError(
@@ -706,7 +715,7 @@ def _parse(data: dict[str, Any], name: str) -> Profile:
706
715
  f"{name}: template {t.id}: kinds {homed} live on it but are "
707
716
  "not among its kinds"
708
717
  )
709
- raw_groups = data.get("compare_groups") or {}
718
+ raw_groups = data.get("compare_groups", {})
710
719
  if not isinstance(raw_groups, dict):
711
720
  raise ProfileError(f"{name}: compare_groups must be a mapping")
712
721
  groups = {
@@ -10,9 +10,8 @@ const EDGE_COLOR = {flow:'#1f77b4', shift:'#d62728', opposes:'#ff7f0e', produces
10
10
  // relation kinds a profile adds (graph.py edge_kinds) are drawn grey
11
11
  const edgeColor = k => EDGE_COLOR[k] || '#7f7f7f';
12
12
  const CAMERA = 2600;
13
- // boards top down from M.boards, centred on 0; records above, sources below (graph.py planes)
14
- const PLANE_Z = {records: 520, sources: -520};
15
- Object.keys(M.boards).forEach((b, i, all) => { PLANE_Z[b] = ((all.length - 1) / 2 - i) * 260; });
13
+ // height of each plane: the boards, records above, sources below (graph.py planes, LAYER)
14
+ const PLANE_Z = M.planes;
16
15
  const DASHED = new Set(['tests','qualifies','feeds','valid_for','cooperation','tested_by','cites','in']);
17
16
  const byId = new Map(M.nodes.map(n => [n.id, n]));
18
17
  const out = new Map(), inc = new Map();
@@ -24,7 +24,8 @@ LAYER = 260.0 # distance between planes
24
24
 
25
25
  def planes(profile: Profile) -> dict[str, float]:
26
26
  """Plane per board, top down (the last board on top), centred on 0; records
27
- above the boards, sources below (graph.js stacks them the same way)."""
27
+ above the boards, sources below. In LAYER units; `graph_model` passes the
28
+ heights to graph.js as `planes`."""
28
29
  boards = [b.id for b in reversed(profile.boards)]
29
30
  middle = (len(boards) - 1) / 2
30
31
  z = {b: middle - n for n, b in enumerate(boards)}
@@ -304,6 +305,8 @@ def graph_model(
304
305
  "id": data.get("id", ""),
305
306
  "date": str(data.get("date", "")),
306
307
  "boards": {b: profile.board_label(b, lang) for b in boards},
308
+ # the height of each plane, which graph.js draws them at
309
+ "planes": {b: z * LAYER for b, z in plane_z.items()},
307
310
  # each board's ink colour, as on the screen and in the vault
308
311
  "board_colours": {b: profile.board(b).colour[1] for b in boards},
309
312
  # the engine's link kinds, then the relation kinds the profile labels
@@ -1,8 +1,15 @@
1
1
  """Index page of a board record: every K, thesis, hypothesis, ontology record, sign-off
2
- and element, each linked to its line in the YAML and to the local files it cites."""
2
+ and element, each linked to its line in the YAML and to the local files it cites.
3
+
4
+ By default the links hold absolute paths (`file://`, `vscode://file/`), for use on the
5
+ machine that built the page. With `base` (the folder the page is written to, as in
6
+ `smd publish`) they are relative to it, so the folder can be moved or sent: a file that
7
+ shares no folder with `base` but the root is not linked, and YAML lines, which only an
8
+ absolute `vscode://` link opens, are shown as numbers."""
3
9
 
4
10
  from __future__ import annotations
5
11
 
12
+ import os
6
13
  import re
7
14
  import unicodedata
8
15
  from pathlib import Path
@@ -33,6 +40,14 @@ def _web_link(url: str, text: str) -> str:
33
40
  return esc(text)
34
41
 
35
42
 
43
+ def _relative(path: Path, base: Path) -> str | None:
44
+ """`path` relative to the folder `base`, or None when they share only the root."""
45
+ target, folder = path.resolve(), base.resolve()
46
+ if os.path.commonpath([target, folder]) == target.anchor:
47
+ return None
48
+ return Path(os.path.relpath(target, folder)).as_posix()
49
+
50
+
36
51
  def _nfc(text: str) -> str:
37
52
  return unicodedata.normalize("NFC", text)
38
53
 
@@ -66,8 +81,9 @@ class _Index:
66
81
  manifest: dict[str, Any] | None,
67
82
  record: Path,
68
83
  archive: Path | None,
84
+ base: Path | None = None,
69
85
  ) -> None:
70
- self.data, self.lang, self.record = data, lang, record
86
+ self.data, self.lang, self.record, self.base = data, lang, record, base
71
87
  self.lab = LABELS[lang]
72
88
  self.idx = self.lab["index"]
73
89
  self.lines = record.read_text(encoding="utf-8").splitlines()
@@ -79,9 +95,19 @@ class _Index:
79
95
  else {}
80
96
  )
81
97
 
98
+ def _href(self, path: Path) -> str | None:
99
+ """A link to a local file: its `file://` URL, or with `base` its relative path
100
+ (None when it cannot be relative)."""
101
+ if self.base is None:
102
+ return f"file://{quote(str(path.resolve()))}"
103
+ relative = _relative(path, self.base)
104
+ return quote(relative) if relative is not None else None
105
+
82
106
  def _yaml(self, line: int | None) -> str:
83
107
  if not line:
84
108
  return ""
109
+ if self.base is not None:
110
+ return f'<a class="y">YAML:{line}</a>'
85
111
  href = f"vscode://file/{quote(str(self.record.resolve()))}:{line}"
86
112
  return f'<a class="y" href="{esc(href)}">YAML:{line}</a>'
87
113
 
@@ -89,11 +115,14 @@ class _Index:
89
115
  return f'<b id="{esc(id_)}">{esc(id_)}</b><br>{self._yaml(self.ids.get(id_))}'
90
116
 
91
117
  def _local(self, source: dict[str, Any] | None) -> Path | None:
92
- """The cited file in the archive folder, matched by NFC file name."""
118
+ """The cited file in the archive folder, matched by NFC file name; with `base`,
119
+ only a file that can be linked relative to it."""
93
120
  if not source or not source.get("file"):
94
121
  return None
95
122
  found = self.files.get(_nfc(Path(source["file"]).name))
96
- return found.resolve() if found else None
123
+ if found is None or self._href(found) is None:
124
+ return None
125
+ return found.resolve()
97
126
 
98
127
  def _cite(self, cite: str) -> str:
99
128
  sid, _, addr = cite.partition("#")
@@ -103,12 +132,11 @@ class _Index:
103
132
  title = esc(source.get("title", ""))
104
133
  path = self._local(source)
105
134
  if path is not None:
106
- if addr.startswith("l="):
135
+ href = self._href(path) or ""
136
+ if addr.startswith("l=") and self.base is None:
107
137
  href = f"vscode://file/{quote(str(path))}:{addr[2:]}"
108
138
  elif addr.startswith("p=") and path.suffix == ".pdf" and addr[2:].isdigit():
109
- href = f"file://{quote(str(path))}#page={addr[2:]}"
110
- else:
111
- href = f"file://{quote(str(path))}"
139
+ href += f"#page={addr[2:]}"
112
140
  return f'<a href="{esc(href)}" title="{title}">{esc(cite)}</a>'
113
141
  if source.get("url"):
114
142
  shown = f"{title} ({esc(self.idx['web'])}"
@@ -129,7 +157,8 @@ class _Index:
129
157
  return esc(self.idx["no_entry"])
130
158
  path = self._local(source)
131
159
  if path is not None:
132
- return f'<a href="file://{quote(str(path))}">{esc(str(path))}</a>'
160
+ shown = str(path) if self.base is None else _relative(path, self.base)
161
+ return f'<a href="{esc(self._href(path) or "")}">{esc(shown or "")}</a>'
133
162
  if source.get("url"):
134
163
  return _web_link(source["url"], source["url"])
135
164
  return esc(self.idx["no_file"])
@@ -295,16 +324,21 @@ class _Index:
295
324
  f'<a href="#sec-{key}">{esc(title)}</a>' for key, title, _, _ in sections
296
325
  )
297
326
  body = "".join(self._table(*s) for s in sections)
298
- record = self.record.resolve()
299
327
  title = title_line(self.data, self.lang)
328
+ href = self._href(self.record)
329
+ record = (
330
+ f'<a href="{esc(href)}">{esc(self.record.name)}</a>'
331
+ if href is not None
332
+ else esc(self.record.name)
333
+ )
334
+ hint = self.idx["hint" if self.base is None else "hint_relative"]
300
335
  return (
301
336
  f'<!doctype html><html lang="{self.lang}"><head><meta charset="utf-8">'
302
337
  '<meta name="viewport" content="width=device-width,initial-scale=1">'
303
338
  f"<title>{esc(self.data['id'])}: {esc(self.idx['suffix'])}</title>"
304
339
  f"<style>{CSS}</style></head><body><header><h1>{esc(title)}</h1>"
305
- f"<div>{esc(self.idx['file'])}: "
306
- f'<a href="file://{esc(quote(str(record)))}">{esc(self.record.name)}</a>. '
307
- f"{esc(self.idx['hint'])} {nav}</div></header>"
340
+ f"<div>{esc(self.idx['file'])}: {record}. "
341
+ f"{esc(hint)} {nav}</div></header>"
308
342
  f"<main>{body}</main></body></html>\n"
309
343
  )
310
344
 
@@ -315,8 +349,10 @@ def render_index(
315
349
  lang: str = "ru",
316
350
  manifest: dict[str, Any] | None = None,
317
351
  archive: Path | None = None,
352
+ base: Path | None = None,
318
353
  ) -> str:
319
354
  """One page listing every item of the record with its YAML line. A cited source is
320
355
  linked to its file only when `archive` holds a file of that name; otherwise the
321
- cite is followed by the source title."""
322
- return _Index(data, lang, manifest, record, archive).page()
356
+ cite is followed by the source title. With `base`, the folder the page goes to,
357
+ links to local files are relative to it (see the module docstring)."""
358
+ return _Index(data, lang, manifest, record, archive, base).page()