sessionwiki 2.0.0__py3-none-any.whl
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.
- sessionwiki/__init__.py +74 -0
- sessionwiki/__main__.py +6 -0
- sessionwiki/_frontmatter.py +118 -0
- sessionwiki/_system_pages.py +44 -0
- sessionwiki/adapter_config.py +124 -0
- sessionwiki/adapters/__init__.py +134 -0
- sessionwiki/adapters/base.py +191 -0
- sessionwiki/adapters/claude_code.py +77 -0
- sessionwiki/adapters/codex_cli.py +226 -0
- sessionwiki/adapters/contrib/__init__.py +1 -0
- sessionwiki/adapters/contrib/chatgpt.py +252 -0
- sessionwiki/adapters/contrib/copilot_chat.py +121 -0
- sessionwiki/adapters/contrib/copilot_cli.py +115 -0
- sessionwiki/adapters/contrib/cursor.py +100 -0
- sessionwiki/adapters/contrib/gemini_cli.py +74 -0
- sessionwiki/adapters/contrib/obsidian.py +121 -0
- sessionwiki/adapters/opencode.py +169 -0
- sessionwiki/adapters/status.py +58 -0
- sessionwiki/adapters/zcode.py +45 -0
- sessionwiki/audit.py +174 -0
- sessionwiki/backlinks.py +224 -0
- sessionwiki/build.py +2786 -0
- sessionwiki/cache.py +401 -0
- sessionwiki/candidates.py +309 -0
- sessionwiki/categories.py +158 -0
- sessionwiki/changelog_timeline.py +422 -0
- sessionwiki/cli.py +1687 -0
- sessionwiki/compare.py +404 -0
- sessionwiki/completion.py +191 -0
- sessionwiki/confidence.py +179 -0
- sessionwiki/config.py +74 -0
- sessionwiki/config_schedule.py +77 -0
- sessionwiki/context_md.py +182 -0
- sessionwiki/convert.py +1746 -0
- sessionwiki/docs_pages.py +725 -0
- sessionwiki/doctor.py +113 -0
- sessionwiki/exporters.py +680 -0
- sessionwiki/freshness.py +153 -0
- sessionwiki/graph.py +1058 -0
- sessionwiki/graphify_bridge.py +509 -0
- sessionwiki/ingest_queue.py +101 -0
- sessionwiki/lifecycle.py +167 -0
- sessionwiki/link_checker.py +148 -0
- sessionwiki/lint/__init__.py +170 -0
- sessionwiki/lint/rules/__init__.py +69 -0
- sessionwiki/lint/rules/_helpers.py +119 -0
- sessionwiki/lint/rules/claim_verification.py +44 -0
- sessionwiki/lint/rules/content_freshness.py +41 -0
- sessionwiki/lint/rules/contradiction_detection.py +45 -0
- sessionwiki/lint/rules/duplicate_detection.py +164 -0
- sessionwiki/lint/rules/entity_consistency.py +29 -0
- sessionwiki/lint/rules/frontmatter_completeness.py +46 -0
- sessionwiki/lint/rules/frontmatter_count_consistency.py +61 -0
- sessionwiki/lint/rules/frontmatter_validity.py +71 -0
- sessionwiki/lint/rules/index_sync.py +68 -0
- sessionwiki/lint/rules/link_integrity.py +34 -0
- sessionwiki/lint/rules/orphan_detection.py +43 -0
- sessionwiki/lint/rules/stale_candidates.py +59 -0
- sessionwiki/lint/rules/stale_reference_detection.py +42 -0
- sessionwiki/lint/rules/summary_accuracy.py +36 -0
- sessionwiki/lint/rules/tags_topics_convention.py +58 -0
- sessionwiki/lint/rules/tools_consistency.py +65 -0
- sessionwiki/lock.py +126 -0
- sessionwiki/log_reader.py +129 -0
- sessionwiki/manifest.py +132 -0
- sessionwiki/mcp/__init__.py +29 -0
- sessionwiki/mcp/__main__.py +5 -0
- sessionwiki/mcp/server.py +1061 -0
- sessionwiki/models_page.py +291 -0
- sessionwiki/obsidian_output.py +208 -0
- sessionwiki/opencode/__init__.py +1 -0
- sessionwiki/opencode/autosync.py +102 -0
- sessionwiki/opencode/export.py +419 -0
- sessionwiki/opencode/install.py +152 -0
- sessionwiki/pipeline.py +150 -0
- sessionwiki/project_topics.py +213 -0
- sessionwiki/py.typed +0 -0
- sessionwiki/quarantine.py +273 -0
- sessionwiki/queue.py +29 -0
- sessionwiki/references.py +224 -0
- sessionwiki/render/__init__.py +20 -0
- sessionwiki/render/css.py +988 -0
- sessionwiki/render/docs_css.py +463 -0
- sessionwiki/render/js.py +1337 -0
- sessionwiki/schema.py +270 -0
- sessionwiki/search_facets.py +150 -0
- sessionwiki/search_tree.py +184 -0
- sessionwiki/serve.py +91 -0
- sessionwiki/session_export.py +333 -0
- sessionwiki/skill_installer.py +112 -0
- sessionwiki/sync/__init__.py +13 -0
- sessionwiki/sync/status.py +120 -0
- sessionwiki/synth/__init__.py +14 -0
- sessionwiki/synth/agent_delegate.py +327 -0
- sessionwiki/synth/base.py +125 -0
- sessionwiki/synth/cli_helpers.py +98 -0
- sessionwiki/synth/estimate.py +146 -0
- sessionwiki/synth/ollama.py +379 -0
- sessionwiki/synth/openai_compat.py +325 -0
- sessionwiki/synth/pipeline.py +1489 -0
- sessionwiki/tag_utils.py +62 -0
- sessionwiki/tags.py +359 -0
- sessionwiki/vault.py +347 -0
- sessionwiki/viz_heatmap.py +305 -0
- sessionwiki/viz_tokens.py +429 -0
- sessionwiki/viz_tools.py +241 -0
- sessionwiki/watch.py +154 -0
- sessionwiki/zcode/__init__.py +43 -0
- sessionwiki/zcode/autosync.py +150 -0
- sessionwiki/zcode/export.py +568 -0
- sessionwiki/zcode/install.py +386 -0
- sessionwiki-2.0.0.dist-info/METADATA +303 -0
- sessionwiki-2.0.0.dist-info/RECORD +118 -0
- sessionwiki-2.0.0.dist-info/WHEEL +5 -0
- sessionwiki-2.0.0.dist-info/entry_points.txt +2 -0
- sessionwiki-2.0.0.dist-info/licenses/LICENSE +22 -0
- sessionwiki-2.0.0.dist-info/licenses/NOTICE +14 -0
- sessionwiki-2.0.0.dist-info/top_level.txt +1 -0
sessionwiki/tag_utils.py
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
"""Shared tag parsing utilities (v1.0.1 · post-audit cleanup).
|
|
2
|
+
|
|
3
|
+
Consolidates the tag parser that was duplicated byte-for-byte in
|
|
4
|
+
``sessionwiki/categories.py`` and ``sessionwiki/search_facets.py``. Both
|
|
5
|
+
modules now import from here so there's a single source of truth
|
|
6
|
+
for what counts as "noise" and how YAML-list tags get parsed.
|
|
7
|
+
|
|
8
|
+
Also used by the lint rules (via ``scan_tags()``) and MCP server
|
|
9
|
+
tools.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
from typing import Any
|
|
15
|
+
|
|
16
|
+
# ─── Noise tag filter ──────────────────────────────────────────────────
|
|
17
|
+
|
|
18
|
+
# Tags that appear on nearly every session and add no navigation value.
|
|
19
|
+
# Keep this list short — removing a tag here restores it to categories.
|
|
20
|
+
NOISE_TAGS: set[str] = {
|
|
21
|
+
"claude-code",
|
|
22
|
+
"session-transcript",
|
|
23
|
+
"demo",
|
|
24
|
+
"",
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def parse_tags_field(raw: Any) -> list[str]:
|
|
29
|
+
"""Parse a YAML ``tags:`` field into a cleaned list of lowercase tags.
|
|
30
|
+
|
|
31
|
+
Handles three input shapes:
|
|
32
|
+
- ``None`` / empty string → ``[]``
|
|
33
|
+
- ``"[a, b]"`` (YAML list as string) → ``["a", "b"]``
|
|
34
|
+
- ``"a, b"`` (plain comma list) → ``["a", "b"]``
|
|
35
|
+
|
|
36
|
+
Strips surrounding brackets, quotes, and whitespace. Filters out
|
|
37
|
+
NOISE_TAGS. Always lowercases.
|
|
38
|
+
"""
|
|
39
|
+
if not raw:
|
|
40
|
+
return []
|
|
41
|
+
raw = str(raw).strip()
|
|
42
|
+
# Strip YAML-list brackets if present
|
|
43
|
+
if raw.startswith("[") and raw.endswith("]"):
|
|
44
|
+
raw = raw[1:-1]
|
|
45
|
+
# Split and clean each tag
|
|
46
|
+
parts = [p.strip().strip('"').strip("'") for p in raw.split(",")]
|
|
47
|
+
return [p.lower() for p in parts if p and p.lower() not in NOISE_TAGS]
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def scan_tags(pages: dict[str, dict[str, Any]]) -> dict[str, list[str]]:
|
|
51
|
+
"""Scan page metadata and return ``{tag: [page_rel, ...]}``.
|
|
52
|
+
|
|
53
|
+
Input is the output of ``sessionwiki.lint.load_pages()``. Each page has
|
|
54
|
+
a ``meta`` dict; we read its ``tags`` key and aggregate.
|
|
55
|
+
"""
|
|
56
|
+
out: dict[str, list[str]] = {}
|
|
57
|
+
for rel, page in pages.items():
|
|
58
|
+
raw_tags = page["meta"].get("tags", "")
|
|
59
|
+
for tag in parse_tags_field(raw_tags):
|
|
60
|
+
out.setdefault(tag, []).append(rel)
|
|
61
|
+
# Deterministic order for callers
|
|
62
|
+
return {tag: sorted(pages_) for tag, pages_ in out.items()}
|
sessionwiki/tags.py
ADDED
|
@@ -0,0 +1,359 @@
|
|
|
1
|
+
"""Tag operations across the wiki (G-15 · #301 / G-16 · #302).
|
|
2
|
+
|
|
3
|
+
Tags accumulate noise over time — an ingest labels a page ``obsidian``
|
|
4
|
+
while another labels it ``Obsidian`` while a third coins
|
|
5
|
+
``obsidian-vault``. Nothing in the pipeline reconciles them. This
|
|
6
|
+
module surfaces four operations so a maintainer can curate the tag
|
|
7
|
+
space from the CLI:
|
|
8
|
+
|
|
9
|
+
* ``list`` — enumerate every tag with usage count.
|
|
10
|
+
* ``add <tag> <page>`` — append to a page's frontmatter ``tags:``.
|
|
11
|
+
* ``rename <old> <new>`` — rewrite across every page (dry-runnable).
|
|
12
|
+
* ``check`` — flag near-duplicate tags (similarity ≥ 0.85, case-insensitive).
|
|
13
|
+
|
|
14
|
+
Also exposes helpers used by the ``topics_vs_tags_convention`` lint
|
|
15
|
+
rule (G-16 · #302) — projects are supposed to use ``topics:`` while
|
|
16
|
+
sources/entities/concepts use ``tags:``.
|
|
17
|
+
|
|
18
|
+
Stdlib-only. No changes to frontmatter format. Dry-runs never write
|
|
19
|
+
to disk.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
from __future__ import annotations
|
|
23
|
+
|
|
24
|
+
import re
|
|
25
|
+
from dataclasses import dataclass
|
|
26
|
+
from difflib import SequenceMatcher
|
|
27
|
+
from pathlib import Path
|
|
28
|
+
from typing import Any, Iterable, Optional
|
|
29
|
+
|
|
30
|
+
from sessionwiki import REPO_ROOT
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
# ─── frontmatter parsing (minimal, schema-agnostic) ──────────────────────
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
# #495: replaced local LF-only regex with the canonical
|
|
37
|
+
# parse_frontmatter_or_none helper, which also strips BOM and accepts
|
|
38
|
+
# CRLF line endings — the previous local regex silently parsed
|
|
39
|
+
# Windows-authored / BOM-prefixed pages as no-frontmatter, so every
|
|
40
|
+
# tag-rename run skipped them.
|
|
41
|
+
from sessionwiki._frontmatter import parse_frontmatter_or_none as _parse_frontmatter
|
|
42
|
+
|
|
43
|
+
# Inline-list tag value: ``tags: [a, b, c]``.
|
|
44
|
+
_INLINE_LIST_RE = re.compile(
|
|
45
|
+
r"^(?P<key>tags|topics):\s*\[(?P<body>.*?)\]\s*$",
|
|
46
|
+
re.MULTILINE,
|
|
47
|
+
)
|
|
48
|
+
|
|
49
|
+
# Block-list tag value:
|
|
50
|
+
# tags:
|
|
51
|
+
# - a
|
|
52
|
+
# - b
|
|
53
|
+
_BLOCK_LIST_RE = re.compile(
|
|
54
|
+
r"^(?P<key>tags|topics):\s*\n(?P<body>(?:\s{2,}-\s+.+\n?)+)",
|
|
55
|
+
re.MULTILINE,
|
|
56
|
+
)
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
@dataclass(frozen=True)
|
|
60
|
+
class TagEntry:
|
|
61
|
+
"""One (page, field, tag) row used by list + check."""
|
|
62
|
+
|
|
63
|
+
page: Path
|
|
64
|
+
field: str # "tags" or "topics"
|
|
65
|
+
tag: str
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def _iter_tags_in_frontmatter(fm: str) -> list[tuple[str, list[str]]]:
|
|
69
|
+
"""Yield ``(field, [tag, ...])`` for every ``tags:`` / ``topics:`` block."""
|
|
70
|
+
out: list[tuple[str, list[str]]] = []
|
|
71
|
+
for m in _INLINE_LIST_RE.finditer(fm):
|
|
72
|
+
body = m.group("body")
|
|
73
|
+
tags = [t.strip().strip('"').strip("'") for t in body.split(",")]
|
|
74
|
+
out.append((m.group("key"), [t for t in tags if t]))
|
|
75
|
+
for m in _BLOCK_LIST_RE.finditer(fm):
|
|
76
|
+
body = m.group("body")
|
|
77
|
+
tags = []
|
|
78
|
+
for line in body.splitlines():
|
|
79
|
+
line = line.strip()
|
|
80
|
+
if line.startswith("-"):
|
|
81
|
+
tags.append(line[1:].strip().strip('"').strip("'"))
|
|
82
|
+
out.append((m.group("key"), [t for t in tags if t]))
|
|
83
|
+
return out
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
# ─── discovery ───────────────────────────────────────────────────────────
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def _iter_wiki_pages(wiki_dir: Path) -> list[Path]:
|
|
90
|
+
if not wiki_dir.is_dir():
|
|
91
|
+
return []
|
|
92
|
+
return sorted(
|
|
93
|
+
p for p in wiki_dir.rglob("*.md")
|
|
94
|
+
if not p.name.startswith("_") and "archive" not in p.parts
|
|
95
|
+
)
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def collect_tags(wiki_dir: Optional[Path] = None) -> list[TagEntry]:
|
|
99
|
+
"""Walk ``wiki_dir`` and return every tag occurrence."""
|
|
100
|
+
root = wiki_dir or (REPO_ROOT / "wiki")
|
|
101
|
+
out: list[TagEntry] = []
|
|
102
|
+
for p in _iter_wiki_pages(root):
|
|
103
|
+
try:
|
|
104
|
+
text = p.read_text(encoding="utf-8")
|
|
105
|
+
except OSError:
|
|
106
|
+
continue
|
|
107
|
+
fm, _ = _parse_frontmatter(text)
|
|
108
|
+
if fm is None:
|
|
109
|
+
continue
|
|
110
|
+
for field, tags in _iter_tags_in_frontmatter(fm):
|
|
111
|
+
for t in tags:
|
|
112
|
+
out.append(TagEntry(page=p, field=field, tag=t))
|
|
113
|
+
return out
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def count_tags(entries: Iterable[TagEntry]) -> dict[str, int]:
|
|
117
|
+
"""Usage count per tag (case-sensitive — surface the drift)."""
|
|
118
|
+
out: dict[str, int] = {}
|
|
119
|
+
for e in entries:
|
|
120
|
+
out[e.tag] = out.get(e.tag, 0) + 1
|
|
121
|
+
return out
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
# ─── rename / add — file surgery ─────────────────────────────────────────
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
def _rewrite_frontmatter_tags(
|
|
128
|
+
text: str,
|
|
129
|
+
*,
|
|
130
|
+
rename_from: Optional[str] = None,
|
|
131
|
+
rename_to: Optional[str] = None,
|
|
132
|
+
add_tag: Optional[str] = None,
|
|
133
|
+
add_page_field: Optional[str] = None,
|
|
134
|
+
) -> tuple[str, int]:
|
|
135
|
+
"""Return ``(new_text, change_count)`` after applying the op."""
|
|
136
|
+
fm, body = _parse_frontmatter(text)
|
|
137
|
+
if fm is None:
|
|
138
|
+
if add_tag and add_page_field:
|
|
139
|
+
# Seed frontmatter with the requested tag.
|
|
140
|
+
new_fm = f"{add_page_field}: [{add_tag}]"
|
|
141
|
+
return f"---\n{new_fm}\n---\n{text}", 1
|
|
142
|
+
return text, 0
|
|
143
|
+
|
|
144
|
+
changes = 0
|
|
145
|
+
new_fm = fm
|
|
146
|
+
|
|
147
|
+
if rename_from and rename_to:
|
|
148
|
+
# Inline list — ``tags: [a, b, c]`` — do per-token replacement
|
|
149
|
+
# so ``"obsidian"`` doesn't clobber ``"obsidian-vault"``.
|
|
150
|
+
def _sub_inline(m: re.Match) -> str:
|
|
151
|
+
nonlocal changes
|
|
152
|
+
body_ = m.group("body")
|
|
153
|
+
items = [t.strip() for t in body_.split(",") if t.strip()]
|
|
154
|
+
new_items = []
|
|
155
|
+
for it in items:
|
|
156
|
+
stripped = it.strip('"').strip("'")
|
|
157
|
+
if stripped == rename_from:
|
|
158
|
+
new_items.append(rename_to)
|
|
159
|
+
changes += 1
|
|
160
|
+
else:
|
|
161
|
+
new_items.append(it)
|
|
162
|
+
return f"{m.group('key')}: [{', '.join(new_items)}]"
|
|
163
|
+
|
|
164
|
+
new_fm = _INLINE_LIST_RE.sub(_sub_inline, new_fm)
|
|
165
|
+
|
|
166
|
+
# Block list — `` - obsidian`` line-level swap.
|
|
167
|
+
def _sub_block(m: re.Match) -> str:
|
|
168
|
+
nonlocal changes
|
|
169
|
+
key = m.group("key")
|
|
170
|
+
body_lines = []
|
|
171
|
+
for line in m.group("body").splitlines():
|
|
172
|
+
stripped = line.strip()
|
|
173
|
+
if stripped.startswith("-"):
|
|
174
|
+
val = stripped[1:].strip().strip('"').strip("'")
|
|
175
|
+
if val == rename_from:
|
|
176
|
+
indent = line[: len(line) - len(line.lstrip())]
|
|
177
|
+
body_lines.append(f"{indent}- {rename_to}")
|
|
178
|
+
changes += 1
|
|
179
|
+
continue
|
|
180
|
+
body_lines.append(line)
|
|
181
|
+
return f"{key}:\n" + "\n".join(body_lines) + "\n"
|
|
182
|
+
|
|
183
|
+
new_fm = _BLOCK_LIST_RE.sub(_sub_block, new_fm)
|
|
184
|
+
|
|
185
|
+
if add_tag and add_page_field:
|
|
186
|
+
# Only add if the requested field exists AND the tag isn't
|
|
187
|
+
# already present; otherwise append a new field.
|
|
188
|
+
field_lines = _iter_tags_in_frontmatter(new_fm)
|
|
189
|
+
existing_fields = {f for f, _ in field_lines}
|
|
190
|
+
if add_page_field in existing_fields:
|
|
191
|
+
existing_values = {
|
|
192
|
+
t
|
|
193
|
+
for f, vals in field_lines if f == add_page_field
|
|
194
|
+
for t in vals
|
|
195
|
+
}
|
|
196
|
+
if add_tag not in existing_values:
|
|
197
|
+
# Inline first — append to the inline block when present.
|
|
198
|
+
def _append_inline(m: re.Match) -> str:
|
|
199
|
+
nonlocal changes
|
|
200
|
+
if m.group("key") != add_page_field:
|
|
201
|
+
return m.group(0)
|
|
202
|
+
body_ = m.group("body").strip()
|
|
203
|
+
new_body = f"{body_}, {add_tag}" if body_ else add_tag
|
|
204
|
+
changes += 1
|
|
205
|
+
return f"{m.group('key')}: [{new_body}]"
|
|
206
|
+
|
|
207
|
+
before_changes = changes
|
|
208
|
+
new_fm = _INLINE_LIST_RE.sub(_append_inline, new_fm)
|
|
209
|
+
if changes == before_changes:
|
|
210
|
+
# Block form — append a new bullet under the block.
|
|
211
|
+
def _append_block(m: re.Match) -> str:
|
|
212
|
+
nonlocal changes
|
|
213
|
+
if m.group("key") != add_page_field:
|
|
214
|
+
return m.group(0)
|
|
215
|
+
changes += 1
|
|
216
|
+
return m.group(0).rstrip() + f"\n - {add_tag}\n"
|
|
217
|
+
|
|
218
|
+
new_fm = _BLOCK_LIST_RE.sub(_append_block, new_fm)
|
|
219
|
+
else:
|
|
220
|
+
new_fm = new_fm.rstrip() + f"\n{add_page_field}: [{add_tag}]"
|
|
221
|
+
changes += 1
|
|
222
|
+
|
|
223
|
+
if changes == 0:
|
|
224
|
+
return text, 0
|
|
225
|
+
return f"---\n{new_fm}\n---\n{body}", changes
|
|
226
|
+
|
|
227
|
+
|
|
228
|
+
def rename_tag(
|
|
229
|
+
old: str,
|
|
230
|
+
new: str,
|
|
231
|
+
*,
|
|
232
|
+
wiki_dir: Optional[Path] = None,
|
|
233
|
+
dry_run: bool = False,
|
|
234
|
+
) -> dict[Path, int]:
|
|
235
|
+
"""Rename ``old`` → ``new`` across every page.
|
|
236
|
+
|
|
237
|
+
Returns ``{page: changes}``. With ``dry_run=True`` the files are
|
|
238
|
+
not written — the return value tells the caller what *would* happen.
|
|
239
|
+
"""
|
|
240
|
+
if not old or not new:
|
|
241
|
+
raise ValueError("both old and new tags are required")
|
|
242
|
+
if old == new:
|
|
243
|
+
return {}
|
|
244
|
+
root = wiki_dir or (REPO_ROOT / "wiki")
|
|
245
|
+
touched: dict[Path, int] = {}
|
|
246
|
+
for p in _iter_wiki_pages(root):
|
|
247
|
+
try:
|
|
248
|
+
text = p.read_text(encoding="utf-8")
|
|
249
|
+
except OSError:
|
|
250
|
+
continue
|
|
251
|
+
new_text, count = _rewrite_frontmatter_tags(
|
|
252
|
+
text, rename_from=old, rename_to=new
|
|
253
|
+
)
|
|
254
|
+
if count:
|
|
255
|
+
touched[p] = count
|
|
256
|
+
if not dry_run:
|
|
257
|
+
p.write_text(new_text, encoding="utf-8")
|
|
258
|
+
return touched
|
|
259
|
+
|
|
260
|
+
|
|
261
|
+
def add_tag_to_page(
|
|
262
|
+
tag: str,
|
|
263
|
+
page: Path,
|
|
264
|
+
*,
|
|
265
|
+
field: str = "tags",
|
|
266
|
+
) -> int:
|
|
267
|
+
"""Add ``tag`` to ``page``'s frontmatter (field defaults to ``tags``).
|
|
268
|
+
|
|
269
|
+
Returns the number of changes (0 or 1). Idempotent: adding a tag
|
|
270
|
+
that already exists is a no-op and returns 0.
|
|
271
|
+
"""
|
|
272
|
+
if not tag:
|
|
273
|
+
raise ValueError("tag is required")
|
|
274
|
+
if field not in {"tags", "topics"}:
|
|
275
|
+
raise ValueError(f"field must be 'tags' or 'topics', got {field!r}")
|
|
276
|
+
if not page.is_file():
|
|
277
|
+
raise FileNotFoundError(page)
|
|
278
|
+
text = page.read_text(encoding="utf-8")
|
|
279
|
+
new_text, count = _rewrite_frontmatter_tags(
|
|
280
|
+
text, add_tag=tag, add_page_field=field
|
|
281
|
+
)
|
|
282
|
+
if count:
|
|
283
|
+
page.write_text(new_text, encoding="utf-8")
|
|
284
|
+
return count
|
|
285
|
+
|
|
286
|
+
|
|
287
|
+
# ─── check — near-duplicate detector ─────────────────────────────────────
|
|
288
|
+
|
|
289
|
+
|
|
290
|
+
def near_duplicate_tags(
|
|
291
|
+
entries: Iterable[TagEntry],
|
|
292
|
+
*,
|
|
293
|
+
threshold: float = 0.85,
|
|
294
|
+
) -> list[tuple[str, str, float]]:
|
|
295
|
+
"""Return ``(a, b, similarity)`` pairs exceeding the threshold.
|
|
296
|
+
|
|
297
|
+
Comparison is case-insensitive; ``(a, b)`` is always lexicographic.
|
|
298
|
+
Identical tags (case-insensitive) short-circuit to similarity 1.0.
|
|
299
|
+
"""
|
|
300
|
+
unique = sorted({e.tag for e in entries}, key=str.lower)
|
|
301
|
+
out: list[tuple[str, str, float]] = []
|
|
302
|
+
for i, a in enumerate(unique):
|
|
303
|
+
for b in unique[i + 1 :]:
|
|
304
|
+
ratio = SequenceMatcher(None, a.lower(), b.lower()).ratio()
|
|
305
|
+
if ratio >= threshold:
|
|
306
|
+
out.append((a, b, ratio))
|
|
307
|
+
return out
|
|
308
|
+
|
|
309
|
+
|
|
310
|
+
# ─── G-16 · topics-vs-tags convention ───────────────────────────────────
|
|
311
|
+
|
|
312
|
+
|
|
313
|
+
def convention_violations(
|
|
314
|
+
entries: Iterable[TagEntry],
|
|
315
|
+
) -> list[tuple[Path, str, str]]:
|
|
316
|
+
"""Flag pages using the wrong frontmatter field for their type.
|
|
317
|
+
|
|
318
|
+
Convention (G-16 · #302):
|
|
319
|
+
|
|
320
|
+
* ``wiki/projects/*.md`` MUST use ``topics:``
|
|
321
|
+
* ``wiki/sources/**``, ``wiki/entities/**``, ``wiki/concepts/**``,
|
|
322
|
+
``wiki/syntheses/**`` MUST use ``tags:``
|
|
323
|
+
|
|
324
|
+
Returns ``[(page, expected_field, actual_field), ...]``.
|
|
325
|
+
"""
|
|
326
|
+
out: list[tuple[Path, str, str]] = []
|
|
327
|
+
seen_fields: dict[Path, set[str]] = {}
|
|
328
|
+
for e in entries:
|
|
329
|
+
seen_fields.setdefault(e.page, set()).add(e.field)
|
|
330
|
+
|
|
331
|
+
for page, fields in seen_fields.items():
|
|
332
|
+
posix = page.as_posix()
|
|
333
|
+
if "/projects/" in posix:
|
|
334
|
+
expected = "topics"
|
|
335
|
+
elif any(
|
|
336
|
+
seg in posix
|
|
337
|
+
for seg in ("/sources/", "/entities/", "/concepts/", "/syntheses/")
|
|
338
|
+
):
|
|
339
|
+
expected = "tags"
|
|
340
|
+
else:
|
|
341
|
+
# Unknown folder — skip.
|
|
342
|
+
continue
|
|
343
|
+
for field in fields:
|
|
344
|
+
if field != expected:
|
|
345
|
+
out.append((page, expected, field))
|
|
346
|
+
return out
|
|
347
|
+
|
|
348
|
+
|
|
349
|
+
def format_tag_table(counts: dict[str, int]) -> str:
|
|
350
|
+
"""Human-readable sort-by-count-desc table."""
|
|
351
|
+
if not counts:
|
|
352
|
+
return "No tags found."
|
|
353
|
+
items = sorted(counts.items(), key=lambda kv: (-kv[1], kv[0].lower()))
|
|
354
|
+
width = max(len(k) for k, _ in items)
|
|
355
|
+
rows = [f" {'tag':<{width}} count"]
|
|
356
|
+
rows.append(" " + "-" * width + " -----")
|
|
357
|
+
for tag, count in items:
|
|
358
|
+
rows.append(f" {tag:<{width}} {count:>5}")
|
|
359
|
+
return "\n".join(rows)
|