Version 1. 1.0 SPEC subsection improvement, and wiki update refinement
This commit is contained in:
@@ -1,10 +1,10 @@
|
||||
---
|
||||
name: Fiona-Assistant Development Agent Rules
|
||||
version: 1.9.1
|
||||
version: 1.9.2
|
||||
title: Agents
|
||||
type: summary
|
||||
created: 2025-09-23
|
||||
updated: 2026-09-30
|
||||
updated: 2026-10-01
|
||||
tags: [agents, rules, guidelines, llm, ai]
|
||||
sources: []
|
||||
---
|
||||
@@ -103,7 +103,7 @@ Before step 2, load the environment (project agent rule 3.1).
|
||||
- Semver: patch for a clarification, minor for a new rule or
|
||||
requirement, major for a breaking contract change.
|
||||
- Bump [SPEC](./SPEC.md) when step 1 or step 4 changed it.
|
||||
- Python and shell files have no version tag yet (SPEC 4.8.1).
|
||||
- Python and shell files have no version tag yet (SPEC 7.3.2.1).
|
||||
Leave them untagged.
|
||||
|
||||
A documentation edit that does not change product behavior still
|
||||
@@ -422,7 +422,7 @@ llm:
|
||||
- reasoning: high # when the model reports a level
|
||||
contested: true
|
||||
contradictions: [other-page-slug]
|
||||
# written by wiki ingest (SPEC 7.25), optional:
|
||||
# written by wiki ingest (SPEC 7.1.5), optional:
|
||||
status: raw | refined
|
||||
source_meta: {author: Name} # metadata read from the source
|
||||
ingest: # provenance; every key always present
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
||||
|
||||
[project]
|
||||
name = "fiona-assistant"
|
||||
version = "0.99.0"
|
||||
version = "1.1.0"
|
||||
description = "Tools for managing the LLM wiki."
|
||||
authors = [{name = "nvaldeziii"}]
|
||||
readme = "README.md"
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - local and no-env install options.
|
||||
|
||||
SPEC 7.24. Both ``bootstrap`` and ``bootstrap.ps1`` call this script
|
||||
SPEC 7.21. Both ``bootstrap`` and ``bootstrap.ps1`` call this script
|
||||
and read one pip argument per stdout line.
|
||||
"""
|
||||
|
||||
|
||||
@@ -289,7 +289,7 @@ def main():
|
||||
)
|
||||
add_ingest_arguments(wiki_ingest_parser)
|
||||
|
||||
# AI/LLM: fiona-assistant housekeeping (SPEC 4.15)
|
||||
# AI/LLM: fiona-assistant housekeeping (SPEC 4.8)
|
||||
housekeeping_parser = subparsers.add_parser(
|
||||
"housekeeping",
|
||||
help="Run the wiki maintenance routine and report what needs work"
|
||||
|
||||
@@ -4,8 +4,8 @@ category: productivity
|
||||
description: Operate an llm-wiki with the fiona-assistant CLI.
|
||||
author: nvaldez
|
||||
license: MIT
|
||||
version: 1.11.0
|
||||
updated: 2026-09-30
|
||||
version: 1.12.0
|
||||
updated: 2026-10-01
|
||||
---
|
||||
|
||||
# Fiona
|
||||
@@ -195,7 +195,7 @@ python -m pip install fiona-assistant
|
||||
| Ingested pages not refined yet? | `wiki ingest --pending --json` |
|
||||
| Empty directory, start a wiki? | `wiki init <dir>` |
|
||||
| Template behind the installed package? | `wiki check-update`, then `wiki update --dry-run` |
|
||||
| A `*-update.md` file appeared? | Merge it, section 17.1 |
|
||||
| A `*-update` file appeared? | Merge it, section 17.1 |
|
||||
| Ingest or housekeeping done? | `git save --description TEXT` |
|
||||
|
||||
Prefix every row with `fiona-assistant`.
|
||||
@@ -242,7 +242,7 @@ When something differs, the lines that apply:
|
||||
```text
|
||||
Files to update: <N>
|
||||
Conflicts (owner copy kept): <N>
|
||||
- <path> (<current> -> <template>) -> <stem>-update.md
|
||||
- <path> (<current> -> <template>) -> <stem>-update<suffix>
|
||||
Directories to add: <N>
|
||||
Files to add: <N>
|
||||
Total: <N> file(s) need attention
|
||||
@@ -271,11 +271,14 @@ compared.
|
||||
fiona-assistant wiki update [directory] [--dry-run] [-y|--yes] [-f|--force] [--json]
|
||||
```
|
||||
|
||||
Updates drifted non-markdown core files (settings are deep-merged,
|
||||
the owner's values win) and adds missing core files. Never deletes
|
||||
user files. Never writes inside `personal/` or `raw/`. Never adds
|
||||
or overwrites anything under `wiki/` (seeded at init, then filled
|
||||
by the LLM). Never writes a path matched by `.gitignore`.
|
||||
Updates drifted non-markdown core files in place and adds missing
|
||||
core files. A differing `fiona-settings.json` is a conflict: the
|
||||
owner's file stays byte-for-byte, and the template is written
|
||||
beside it as `fiona-settings-update.json`. You merge it during
|
||||
housekeeping (section 17.1). Never deletes user files. Never writes
|
||||
inside `personal/` or `raw/`. Never adds or overwrites anything
|
||||
under `wiki/` (seeded at init, then filled by the LLM). Never
|
||||
writes a path matched by `.gitignore`.
|
||||
|
||||
Never overwrites an existing markdown file. When the template has a
|
||||
newer version of one, such as `AGENTS.md`, `wiki/index.md`,
|
||||
@@ -295,8 +298,11 @@ Success stdout:
|
||||
Update complete: <U> file(s) updated, <A> added, <C> conflict(s), <S> skipped.
|
||||
```
|
||||
|
||||
When `<C>` is not zero, the next line tells you to run
|
||||
`fiona-assistant housekeeping`.
|
||||
When `<C>` is not zero, the next line is:
|
||||
|
||||
```text
|
||||
Merge each <stem>-update<suffix> into its file: run fiona-assistant housekeeping.
|
||||
```
|
||||
|
||||
### 4.4. sanity
|
||||
|
||||
@@ -902,7 +908,7 @@ your part.
|
||||
| Step | Status when not clean | You do |
|
||||
| --- | --- | --- |
|
||||
| `check-update` | `WARN`: the template has updates, conflicts, or additions | Ask the user, then `wiki update --dry-run` and `wiki update --yes`. |
|
||||
| `merge` | `FAIL`: a `*-update.md` file exists | Section 17.1. |
|
||||
| `merge` | `FAIL`: a file whose stem ends with `-update` exists | Section 17.1. |
|
||||
| `ingest` | `WARN`: a page under `wiki/` is at `status: raw` | Refine it, section 16.4. |
|
||||
| `sanity` | `FAIL`: a `wiki sanity` violation | Fix it, section 12. |
|
||||
| `graph` | `WARN`: a page under `wiki/` has no link in or out | Link it from a related page or from `wiki/index.md`. |
|
||||
@@ -926,8 +932,11 @@ newer version of a markdown file the owner may have edited, such as
|
||||
the owner's file stays as it is and the template is written beside
|
||||
it as `<stem>-update.md`. `AGENTS-update.md` belongs to
|
||||
`AGENTS.md`; `wiki/schema-update.md` belongs to `wiki/schema.md`.
|
||||
The update file is the new template text, as `wiki init` would
|
||||
write it. You decide how the two become one file:
|
||||
A differing `fiona-settings.json` is the same kind of conflict:
|
||||
the owner's file stays, and the template is
|
||||
`fiona-settings-update.json`. The update file is the new template
|
||||
text, as `wiki init` would write it. You decide how the two become
|
||||
one file:
|
||||
|
||||
1. Read both files. Compare them, for example with
|
||||
`git diff --no-index <file> <stem>-update.md`.
|
||||
@@ -950,6 +959,15 @@ write it. You decide how the two become one file:
|
||||
8. Run `fiona-assistant housekeeping` again. `merge` passes when no
|
||||
update file is left.
|
||||
|
||||
For `fiona-settings-update.json`, merge by the settings rule. Start
|
||||
from the template object. For each user key, if both sides are
|
||||
objects, merge recursively; otherwise the user value replaces the
|
||||
template value. Keep new template keys the user does not set. Write
|
||||
the result as JSON with indent 2 and a trailing newline, then delete
|
||||
`fiona-settings-update.json`. Settings have no `version` field. A
|
||||
later `wiki update` conflicts again only when the owner bytes still
|
||||
differ from the template. Log the merge the same way as step 7.
|
||||
|
||||
When you cannot tell whether an owner edit or a template change
|
||||
should win, ask the user. Do not delete an update file you have not
|
||||
merged unless the user says to drop it. When the target file is
|
||||
|
||||
@@ -214,7 +214,7 @@ class FileTocError(Exception):
|
||||
|
||||
@dataclasses.dataclass(frozen=True)
|
||||
class FileTocConfig:
|
||||
"""Parameters for per-file TOC generation (SPEC 7.15.2).
|
||||
"""Parameters for per-file TOC generation (SPEC 7.3.1.2).
|
||||
|
||||
Attributes:
|
||||
min_heading: Smallest heading level included (never below 2;
|
||||
@@ -359,7 +359,7 @@ def merge_marker_config(lines: list[str], base: FileTocConfig) -> FileTocConfig:
|
||||
"""Apply the existing marker's params over the base config.
|
||||
|
||||
The marker records this TOC's own settings and has priority
|
||||
(SPEC 7.15.2): a `sectionized` marker keeps section numbering on
|
||||
(SPEC 7.3.1.2): a `sectionized` marker keeps section numbering on
|
||||
and the recorded heading range sticks, so regenerations keep the
|
||||
TOC's identity regardless of settings changes. Fields the marker
|
||||
does not record (bare legacy markers, plain markers without
|
||||
@@ -673,7 +673,7 @@ def _file_toc_star(sectionized: bool) -> None:
|
||||
|
||||
|
||||
def file_toc_main(argv: list[str]) -> None:
|
||||
"""CLI for per-file TOC generation (SPEC 7.15.2)."""
|
||||
"""CLI for per-file TOC generation (SPEC 7.3.1.2)."""
|
||||
parser = argparse.ArgumentParser(
|
||||
prog="toc_generator file",
|
||||
description="Generate an in-file table of contents below the H1 heading.",
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
"""Shared logging configuration for all Fiona tools (SPEC 7.20).
|
||||
"""Shared logging configuration for all Fiona tools (SPEC 7.17).
|
||||
|
||||
Diagnostics go through the standard `logging` module with the level
|
||||
resolved from (highest precedence first):
|
||||
@@ -30,7 +30,7 @@ DEFAULT_LOG_LEVEL = "WARNING"
|
||||
DEFAULT_SETTINGS_FILE = llm_wiki_template() / "fiona-settings.json"
|
||||
# Tool package loggers that carry the level explicitly: pymarkdown
|
||||
# resets the root logger to WARNING mid-run, which would otherwise
|
||||
# silence tool diagnostics (same pattern as run_sanity, see SPEC 7.20).
|
||||
# silence tool diagnostics (same pattern as run_sanity, see SPEC 7.17).
|
||||
TOOL_LOGGER_NAMES = ("fiona",)
|
||||
|
||||
LOG_FORMAT = "%(levelname)s %(name)s: %(message)s"
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
"""Sanity Check Runner for Fiona-Assistant project.
|
||||
|
||||
Runs its checks through the shared SanityRunner engine
|
||||
(src/sanity_runner, SPEC 7.16.1): concurrent execution, per-check
|
||||
(src/sanity_runner, SPEC 7.14.1): concurrent execution, per-check
|
||||
timings, and the common report format. This module keeps only the
|
||||
repository-specific checks, their summaries, and the report
|
||||
presentation.
|
||||
@@ -626,7 +626,7 @@ def coverage_met(check_result: dict) -> bool:
|
||||
def format_duration(seconds: float) -> str:
|
||||
"""Format a duration in seconds as zero-padded MM:SS.
|
||||
|
||||
Delegates to the shared SanityRunner engine (SPEC 7.16.1).
|
||||
Delegates to the shared SanityRunner engine (SPEC 7.14.1).
|
||||
|
||||
Args:
|
||||
seconds: Duration in seconds.
|
||||
@@ -640,7 +640,7 @@ def format_duration(seconds: float) -> str:
|
||||
def format_check_summary(check_name: str, check_result: dict) -> str:
|
||||
"""Format a single check result as a human/AI-friendly line.
|
||||
|
||||
Delegates to the shared SanityRunner engine (SPEC 7.16.1); the
|
||||
Delegates to the shared SanityRunner engine (SPEC 7.14.1); the
|
||||
pytests and coverage summaries plug in as formatters.
|
||||
|
||||
Args:
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
Provides `SanityRunner`, the generalized class shared by the
|
||||
repository sanity runner (run_sanity) and the wiki sanity command
|
||||
(wiki.sanity_manager): concurrent check execution with per-check
|
||||
timings and the common AI-friendly report format (SPEC 6.1/7.16.1).
|
||||
timings and the common AI-friendly report format (SPEC 6.1/7.14.1).
|
||||
"""
|
||||
|
||||
from fiona.sanity_runner.sanity_runner import (
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
"""Shared sanity runner engine (SPEC 7.16.1).
|
||||
"""Shared sanity runner engine (SPEC 7.14.1).
|
||||
|
||||
This module provides `SanityRunner`, the generalized class behind both
|
||||
sanity runners in the project:
|
||||
|
||||
- the repository sanity runner (`fiona.run_sanity`, SPEC 7.16)
|
||||
- the wiki sanity command (`src/wiki/sanity_manager.py`, SPEC 7.3)
|
||||
- the repository sanity runner (`fiona.run_sanity`, SPEC 7.14)
|
||||
- the wiki sanity command (`src/wiki/sanity_manager.py`, SPEC 7.1.3)
|
||||
|
||||
The class owns the common machinery: concurrent check execution with
|
||||
per-check wall-clock timings (SPEC 7.16.1) and the shared AI-friendly
|
||||
per-check wall-clock timings (SPEC 7.14.1) and the shared AI-friendly
|
||||
report structure (SPEC 6.1) — one-line check summaries, the aligned
|
||||
`Results:` table rows, the `SANITY PASSED (MM:SS)` banner, and the
|
||||
`Sanity Failed` footer. Per-check specifics (summary wording, extra
|
||||
@@ -111,7 +111,7 @@ class SanityRunner:
|
||||
|
||||
Each result carries its wall-clock `duration_seconds`; times of
|
||||
parallel checks overlap and need not sum to the total
|
||||
(SPEC 7.16.1). The returned mapping keeps the registry order
|
||||
(SPEC 7.14.1). The returned mapping keeps the registry order
|
||||
regardless of completion order. The check lifecycle (start and
|
||||
completion with duration) is logged at INFO.
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
"""Wiki housekeeping routine (SPEC 4.15, 7.26).
|
||||
"""Wiki housekeeping routine (SPEC 4.8, 7.2).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - one call for LLM wiki maintenance.
|
||||
|
||||
@@ -10,7 +10,7 @@ gathers what needs work; it writes only `wiki_graph.html`.
|
||||
Steps, in order (`STEP_NAMES`):
|
||||
|
||||
- `check-update`: core files behind the packaged template (read-only).
|
||||
- `merge`: `*-update.md` files that `wiki update` left for a merge.
|
||||
- `merge`: files whose stem ends with `-update` that `wiki update` left for a merge.
|
||||
- `ingest`: pages under `wiki/` still at `status: raw`.
|
||||
- `sanity`: every `wiki sanity` check.
|
||||
- `graph`: regenerate `wiki_graph.html` and list orphan pages.
|
||||
@@ -59,7 +59,7 @@ def _step(name: str, status: str, summary: str, details: list[str] | None = None
|
||||
next_steps: list[str] | None = None) -> dict:
|
||||
"""Build one step result.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - shared step shape (SPEC 4.15).
|
||||
Generated by AI/LLM: 2026-09-30 - shared step shape (SPEC 4.8).
|
||||
"""
|
||||
return {
|
||||
"name": name,
|
||||
@@ -90,6 +90,28 @@ def _frontmatter(path: Path) -> dict:
|
||||
return frontmatter if isinstance(frontmatter, dict) else {}
|
||||
|
||||
|
||||
def _wiki_files(wiki_root: Path) -> list[Path]:
|
||||
"""List files outside read-only zones and `.git`, sorted.
|
||||
|
||||
Modified by AI/LLM: 2026-10-01 - merge walks every suffix, not only markdown.
|
||||
|
||||
Args:
|
||||
wiki_root: Root path of the wiki.
|
||||
|
||||
Returns:
|
||||
list[Path]: Files found.
|
||||
"""
|
||||
found = []
|
||||
for current, dirs, files in os.walk(wiki_root):
|
||||
at_root = Path(current) == wiki_root
|
||||
dirs[:] = [
|
||||
name for name in dirs
|
||||
if name != ".git" and not (at_root and name in ROOT_SKIP_DIRS)
|
||||
]
|
||||
found.extend(Path(current) / name for name in files)
|
||||
return sorted(found)
|
||||
|
||||
|
||||
def _markdown_files(wiki_root: Path, subdir: str = "") -> list[Path]:
|
||||
"""List markdown files outside read-only zones and `.git`, sorted.
|
||||
|
||||
@@ -119,7 +141,7 @@ def _markdown_files(wiki_root: Path, subdir: str = "") -> list[Path]:
|
||||
# =============================================================================
|
||||
|
||||
def check_update_step(wiki_root: Path) -> dict:
|
||||
"""Report core files behind the template without writing (SPEC 7.26.2).
|
||||
"""Report core files behind the template without writing (SPEC 7.2.2).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - read-only wiki check-update.
|
||||
"""
|
||||
@@ -142,16 +164,16 @@ def check_update_step(wiki_root: Path) -> dict:
|
||||
|
||||
|
||||
def merge_step(wiki_root: Path) -> dict:
|
||||
"""List update files that wait for an LLM merge (SPEC 7.26.3).
|
||||
"""List update files that wait for an LLM merge (SPEC 7.2.3).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - pending *-update.md merges.
|
||||
Modified by AI/LLM: 2026-10-01 - any stem ending in -update, including JSON.
|
||||
"""
|
||||
details, actions = [], []
|
||||
for update_file in _markdown_files(wiki_root):
|
||||
if not update_file.name.endswith(UPDATE_FILE_SUFFIX):
|
||||
for update_file in _wiki_files(wiki_root):
|
||||
if not update_file.stem.endswith(UPDATE_SUFFIX):
|
||||
continue
|
||||
target = update_file.with_name(
|
||||
update_file.name[: -len(UPDATE_FILE_SUFFIX)] + ".md"
|
||||
update_file.stem[: -len(UPDATE_SUFFIX)] + update_file.suffix
|
||||
)
|
||||
update_rel = _relative(update_file, wiki_root)
|
||||
target_rel = _relative(target, wiki_root)
|
||||
@@ -168,7 +190,7 @@ def merge_step(wiki_root: Path) -> dict:
|
||||
|
||||
|
||||
def ingest_step(wiki_root: Path) -> dict:
|
||||
"""List pages under wiki/ still at `status: raw` (SPEC 7.26.4).
|
||||
"""List pages under wiki/ still at `status: raw` (SPEC 7.2.4).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - pages waiting for a refine.
|
||||
"""
|
||||
@@ -185,7 +207,7 @@ def ingest_step(wiki_root: Path) -> dict:
|
||||
|
||||
|
||||
def sanity_step(wiki_root: Path) -> dict:
|
||||
"""Run every wiki sanity check without the progress display (SPEC 7.26.5).
|
||||
"""Run every wiki sanity check without the progress display (SPEC 7.2.5).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - failing check reports as details.
|
||||
"""
|
||||
@@ -205,7 +227,7 @@ def sanity_step(wiki_root: Path) -> dict:
|
||||
|
||||
|
||||
def graph_step(wiki_root: Path) -> dict:
|
||||
"""Write wiki_graph.html at the wiki root and list orphans (SPEC 7.26.6).
|
||||
"""Write wiki_graph.html at the wiki root and list orphans (SPEC 7.2.6).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - graph plus orphan pages under wiki/.
|
||||
"""
|
||||
@@ -241,7 +263,7 @@ def graph_step(wiki_root: Path) -> dict:
|
||||
# =============================================================================
|
||||
|
||||
def run_housekeeping(directory: str | Path = ".") -> dict:
|
||||
"""Run every housekeeping step over a wiki (SPEC 7.26.1).
|
||||
"""Run every housekeeping step over a wiki (SPEC 7.2.1).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - every step runs, even after a FAIL.
|
||||
|
||||
@@ -280,7 +302,7 @@ def run_housekeeping(directory: str | Path = ".") -> dict:
|
||||
|
||||
|
||||
def format_housekeeping_report(results: dict) -> str:
|
||||
"""Format housekeeping results for humans and LLMs (SPEC 4.15).
|
||||
"""Format housekeeping results for humans and LLMs (SPEC 4.8).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - step blocks, next steps, verdict.
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
"""Wiki ingest package (SPEC 7.25).
|
||||
"""Wiki ingest package (SPEC 7.1.5).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - stage modules for wiki ingest.
|
||||
"""
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
"""Archive a fetched file under ``raw/``.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.3. Never edits a file already there.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.3. Never edits a file already there.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -83,7 +83,7 @@ class RawArchiver:
|
||||
) -> ArchiveResult:
|
||||
"""Place the source under ``raw/`` or reuse an identical copy.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.3.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.3.
|
||||
|
||||
Args:
|
||||
source: Fetched file.
|
||||
|
||||
@@ -13,7 +13,7 @@ from fiona.wiki.ingest.converters.text import TextConverter
|
||||
def default_registry() -> ConverterRegistry:
|
||||
"""Return the converters shipped with wiki ingest.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - registration order from SPEC 7.25.
|
||||
Generated by AI/LLM: 2026-09-30 - registration order from SPEC 7.1.5.
|
||||
|
||||
Returns:
|
||||
ConverterRegistry: Markdown, text, HTML, and PDF.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
"""Converter base types and the registry.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - one class per format, SPEC 7.25.1.
|
||||
Generated by AI/LLM: 2026-09-30 - one class per format, SPEC 7.1.5.1.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -32,7 +32,7 @@ class ConversionError(Exception):
|
||||
class SourceConverter(abc.ABC):
|
||||
"""One format. Subclasses declare what they claim and implement ``convert``.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.1.2.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.1.2.
|
||||
"""
|
||||
|
||||
name: typing.ClassVar[str]
|
||||
@@ -84,7 +84,7 @@ class ConverterRegistry:
|
||||
def find(self, media_type: str, extension: str) -> SourceConverter | None:
|
||||
"""Pick the converter for a media type and extension.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.4.1 registration order.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.4.1 registration order.
|
||||
|
||||
Args:
|
||||
media_type: Detected type, or empty.
|
||||
|
||||
@@ -22,7 +22,7 @@ _NO_TEXT = "no text content; the page may need JavaScript or a login"
|
||||
class HtmlConverter(SourceConverter):
|
||||
"""Convert an HTML document to markdown.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.4.5.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.4.5.
|
||||
"""
|
||||
|
||||
name: typing.ClassVar[str] = "html"
|
||||
@@ -91,7 +91,7 @@ def _absolutize(root: bs4.element.Tag, soup: bs4.BeautifulSoup, origin: str | No
|
||||
def _html_title(soup: bs4.BeautifulSoup, root: bs4.element.Tag) -> str | None:
|
||||
"""Return ``<title>``, then ``og:title``, then the first ``<h1>``.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.4.5.1.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.4.5.1.
|
||||
"""
|
||||
if soup.title and soup.title.string and soup.title.string.strip():
|
||||
return soup.title.string.strip()
|
||||
|
||||
@@ -22,7 +22,7 @@ _FENCE = re.compile(r"^\s*(`{3,}|~{3,})")
|
||||
class MarkdownConverter(SourceConverter):
|
||||
"""Keep markdown as it is and record any source frontmatter.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.4.3.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.4.3.
|
||||
|
||||
The body after a frontmatter block is kept character for character.
|
||||
The page writer adds the wiki frontmatter when the new page does not
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
"""PDF source converter.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - text layer via pypdf, SPEC 7.25.4.6.
|
||||
Generated by AI/LLM: 2026-09-30 - text layer via pypdf, SPEC 7.1.5.4.6.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -20,7 +20,7 @@ _SCANNED = "no text layer; the PDF may be scanned"
|
||||
class PdfConverter(SourceConverter):
|
||||
"""Read a PDF text layer into markdown headings and paragraphs.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.4.6.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.4.6.
|
||||
"""
|
||||
|
||||
name: typing.ClassVar[str] = "pdf"
|
||||
@@ -167,7 +167,7 @@ def _walk_outline(
|
||||
def _render(pages: list[str], outline: list[tuple[int, int, str]]) -> str:
|
||||
"""Render pages with outline headings or ``## Page n`` headings.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.4.6.2.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.4.6.2.
|
||||
"""
|
||||
by_page: dict[int, list[str]] = {}
|
||||
for page_index, level, title in outline:
|
||||
|
||||
@@ -15,7 +15,7 @@ from fiona.wiki.ingest.models import ConversionResult, FetchedSource
|
||||
class TextConverter(SourceConverter):
|
||||
"""Turn plain text into one fenced markdown block.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.4.4.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.4.4.
|
||||
|
||||
The page is written at ``status: raw``. The tool does not summarize
|
||||
the text. The agent rewrites the fence during refinement.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
"""Fetch a local file or an HTTP URL.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.2. No credentials are sent.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.2. No credentials are sent.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -51,7 +51,7 @@ def url_scheme(argument: str) -> str | None:
|
||||
class SourceFetcher:
|
||||
"""Base fetcher. Subclasses accept an argument and return a local file.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.1.3.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.1.3.
|
||||
"""
|
||||
|
||||
settings: IngestSettings | None = None
|
||||
@@ -111,7 +111,7 @@ class LocalFileFetcher(SourceFetcher):
|
||||
def fetch(self, argument: str, dest_dir: pathlib.Path) -> FetchedSource:
|
||||
"""Resolve a local path without copying it.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.2.1.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.2.1.
|
||||
|
||||
Args:
|
||||
argument: Local path as given.
|
||||
@@ -186,7 +186,7 @@ class UrlFetcher(SourceFetcher):
|
||||
def fetch(self, argument: str, dest_dir: pathlib.Path) -> FetchedSource:
|
||||
"""Download a URL into ``dest_dir`` and stop past the size limit.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.2.2 and 7.25.2.3.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.2.2 and 7.1.5.2.3.
|
||||
|
||||
Args:
|
||||
argument: Absolute URL.
|
||||
@@ -247,7 +247,7 @@ class UrlFetcher(SourceFetcher):
|
||||
def _without_userinfo(url: str) -> str:
|
||||
"""Drop userinfo so the request sends no credentials.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.2.2.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.2.2.
|
||||
"""
|
||||
parts = urllib.parse.urlsplit(url)
|
||||
if parts.username is None and parts.password is None:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
"""Append one ingest line to ``wiki/log.md``.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.6. Does not edit ``index.md``.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.6. Does not edit ``index.md``.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
"""Media-type detection and slug rules for wiki ingest.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.2.4 and 7.25.2.6.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.2.4 and 7.1.5.2.6.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -12,7 +12,7 @@ import pathlib
|
||||
class IngestError(Exception):
|
||||
"""Raised when wiki ingest must stop before a page is written.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - exit 1 errors from section 4.14.
|
||||
Generated by AI/LLM: 2026-09-30 - exit 1 errors from section 4.7.6.
|
||||
"""
|
||||
|
||||
def __init__(self, message: str, exit_code: int = 1) -> None:
|
||||
@@ -20,7 +20,7 @@ class IngestError(Exception):
|
||||
|
||||
Args:
|
||||
message: Text after ``Error: ``.
|
||||
exit_code: Process status. Section 4.14 uses 1.
|
||||
exit_code: Process status. Section 4.7.6 uses 1.
|
||||
"""
|
||||
super().__init__(message)
|
||||
self.exit_code = exit_code
|
||||
@@ -77,7 +77,7 @@ class ArchiveResult:
|
||||
|
||||
@dataclasses.dataclass
|
||||
class IngestResult:
|
||||
"""One ingest run, including the JSON object from section 4.14.
|
||||
"""One ingest run, including the JSON object from section 4.7.6.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - stdout facts for a finished run.
|
||||
"""
|
||||
@@ -101,7 +101,7 @@ class IngestResult:
|
||||
messages: list[str] = dataclasses.field(default_factory=list)
|
||||
|
||||
def to_dict(self) -> dict:
|
||||
"""Return the JSON object from section 4.14.
|
||||
"""Return the JSON object from section 4.7.6.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - drop CLI-only fields.
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
"""Write one ``status: raw`` wiki page.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.5. The tool never sets ``refined``.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.5. The tool never sets ``refined``.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -30,7 +30,7 @@ _PROTECTED = {"index.md", "log.md", "schema.md"}
|
||||
class RawPageWriter:
|
||||
"""Write the raw page and run the markdown fixer on that file only.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - frontmatter order from SPEC 7.25.5.3.
|
||||
Generated by AI/LLM: 2026-09-30 - frontmatter order from SPEC 7.1.5.5.3.
|
||||
"""
|
||||
|
||||
def __init__(self, wiki_root: pathlib.Path) -> None:
|
||||
@@ -49,7 +49,7 @@ class RawPageWriter:
|
||||
) -> pathlib.Path:
|
||||
"""Resolve the page path and reject paths outside ``wiki/``.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.5.1. Does not touch the disk.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.5.1. Does not touch the disk.
|
||||
|
||||
Args:
|
||||
slug: Page stem when ``target`` is a directory or omitted.
|
||||
@@ -91,7 +91,7 @@ class RawPageWriter:
|
||||
) -> tuple[str, list[str]]:
|
||||
"""Write the page, fix it, and return the relative path and warnings.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.5.3 through 7.25.5.5.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.5.3 through 7.1.5.5.5.
|
||||
|
||||
Args:
|
||||
source: Fetch facts stored in ``ingest``.
|
||||
@@ -307,7 +307,7 @@ def _keeps_target(target: str, page_dir: pathlib.Path) -> bool:
|
||||
def _fix(page: pathlib.Path, wiki_root: pathlib.Path) -> None:
|
||||
"""Run the pymarkdown fixer on one page.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.5.5. A fixer error is logged.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.5.5. A fixer error is logged.
|
||||
"""
|
||||
try:
|
||||
doctor = MDoctor(settings_file=wiki_root / "fiona-settings.json")
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
"""Run the wiki ingest stages in order.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25. The pipeline holds no format logic.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5. The pipeline holds no format logic.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -141,7 +141,7 @@ class IngestPipeline:
|
||||
def list_pending(self) -> list[dict]:
|
||||
"""List wiki pages whose ``status`` is ``raw``, sorted by path.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.9.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.9.
|
||||
|
||||
Returns:
|
||||
list[dict]: ``page_path``, ``sources``, and ``origin`` for each page.
|
||||
@@ -319,7 +319,7 @@ def default_pipeline(wiki_root: pathlib.Path) -> IngestPipeline:
|
||||
def render_stdout(result: IngestResult) -> str:
|
||||
"""Return the human report, including the dry-run banner.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - section 4.14 line order.
|
||||
Generated by AI/LLM: 2026-09-30 - section 4.7.6 line order.
|
||||
"""
|
||||
lines: list[str] = []
|
||||
if result.dry_run:
|
||||
@@ -329,7 +329,7 @@ def render_stdout(result: IngestResult) -> str:
|
||||
|
||||
|
||||
def add_ingest_arguments(parser: argparse.ArgumentParser) -> None:
|
||||
"""Add the section 4.14 flags to an ingest parser.
|
||||
"""Add the section 4.7.6 flags to an ingest parser.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - the CLI subparser owns these flags, including --help.
|
||||
|
||||
@@ -376,7 +376,7 @@ def add_ingest_arguments(parser: argparse.ArgumentParser) -> None:
|
||||
def ingest_main(argv: list[str] | None = None) -> int:
|
||||
"""CLI entry for ``fiona-assistant wiki ingest``.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - section 4.14 exit codes.
|
||||
Generated by AI/LLM: 2026-09-30 - section 4.7.6 exit codes.
|
||||
|
||||
Args:
|
||||
argv: Arguments after the subcommand. ``None`` reads the process arguments.
|
||||
@@ -433,7 +433,7 @@ def execute_ingest(args: argparse.Namespace, parser: argparse.ArgumentParser) ->
|
||||
def _require_wiki(directory: str) -> pathlib.Path:
|
||||
"""Return the wiki root or raise when settings are missing.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - section 4.14 directory error.
|
||||
Generated by AI/LLM: 2026-09-30 - section 4.7.6 directory error.
|
||||
"""
|
||||
root = pathlib.Path(directory)
|
||||
if not (root / "fiona-settings.json").is_file():
|
||||
@@ -470,7 +470,7 @@ def _fetched_line(source: FetchedSource) -> list[str]:
|
||||
def _citing_page(wiki_root: pathlib.Path, raw_rel: str, digest: str) -> str | None:
|
||||
"""Return a page that already cites this raw path or hash.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.3.5. First path in sorted order.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.3.5. First path in sorted order.
|
||||
"""
|
||||
wiki = wiki_root / "wiki"
|
||||
if not wiki.is_dir():
|
||||
@@ -513,7 +513,7 @@ def _result(
|
||||
) -> IngestResult:
|
||||
"""Build an ingest result from the archive and any page that was written.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - JSON fields from section 4.14.
|
||||
Generated by AI/LLM: 2026-09-30 - JSON fields from section 4.7.6.
|
||||
"""
|
||||
return IngestResult(
|
||||
source=source.argument,
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
"""Wiki sanity module (SPEC 7.3).
|
||||
"""Wiki sanity module (SPEC 7.1.3).
|
||||
|
||||
Runs all validation checks over an llm-wiki directory in one command
|
||||
and prints an aggregated, AI-friendly report following the same output
|
||||
structure as run_sanity (SPEC 6.1/7.16.1): each failing check's
|
||||
structure as run_sanity (SPEC 6.1/7.14.1): each failing check's
|
||||
linter report first, then a `Results:` table with per-check
|
||||
PASS/FAIL, violation counts, and (MM:SS) timings, and finally a
|
||||
`SANITY PASSED (MM:SS)` banner or a `Sanity Failed` verdict.
|
||||
@@ -10,7 +10,7 @@ PASS/FAIL, violation counts, and (MM:SS) timings, and finally a
|
||||
The checks live in `sanity_checks()`, a registry of (name, runner)
|
||||
pairs; each runner returns the run_sanity check-result shape
|
||||
(`result`, `violation_count`, `stdout`, and the raw `violations`).
|
||||
Add a new check (e.g. shellcheck once 4.4 ships) by implementing a
|
||||
Add a new check (e.g. shellcheck once 4.3 ships) by implementing a
|
||||
runner and appending it to the registry.
|
||||
"""
|
||||
|
||||
@@ -54,7 +54,7 @@ __all__ = [
|
||||
def _outside_raw(wiki_root: Path, path: str) -> bool:
|
||||
"""Return whether a reported path is outside the raw archive.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.25.12. Sanity checks skip ``raw/``.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 7.1.5.12. Sanity checks skip ``raw/``.
|
||||
|
||||
Args:
|
||||
wiki_root: Wiki root directory.
|
||||
@@ -213,7 +213,7 @@ def sanity_checks() -> tuple[tuple[str, Callable[[Path], dict]], ...]:
|
||||
|
||||
Modified by AI/LLM: 2026-09-30 - a module-level tuple after the
|
||||
runners would be a late declaration (SPEC 6.4.3). Append a check
|
||||
here (for example shellcheck once SPEC 7.12 ships).
|
||||
here (for example shellcheck once SPEC 7.9 ships).
|
||||
|
||||
Returns:
|
||||
tuple: `(name, runner)` pairs in report order.
|
||||
@@ -240,7 +240,7 @@ def run_wiki_checks(
|
||||
|
||||
Checks run concurrently (one thread each, mirroring run_sanity);
|
||||
per-check durations are wall-clock times of parallel checks, so
|
||||
they can overlap and need not sum to the total (SPEC 7.16.1). The
|
||||
they can overlap and need not sum to the total (SPEC 7.14.1). The
|
||||
results keep the registry order regardless of completion order.
|
||||
|
||||
Args:
|
||||
@@ -272,7 +272,7 @@ def run_wiki_checks(
|
||||
)
|
||||
|
||||
# Checks run concurrently through the shared SanityRunner engine
|
||||
# (SPEC 7.16.1); results keep the registry order
|
||||
# (SPEC 7.14.1); results keep the registry order
|
||||
runner = sanity_runner.SanityRunner(
|
||||
checks=[
|
||||
(name, functools.partial(check, wiki_root))
|
||||
@@ -295,14 +295,14 @@ def run_wiki_checks(
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Report Formatting (shared SanityRunner structure, SPEC 6.1/7.16.1)
|
||||
# Report Formatting (shared SanityRunner structure, SPEC 6.1/7.14.1)
|
||||
# =============================================================================
|
||||
|
||||
def format_sanity_report(results: dict) -> str:
|
||||
"""Format the aggregated sanity results for human-readable output.
|
||||
|
||||
Mirrors run_sanity through the shared SanityRunner engine
|
||||
(SPEC 7.16.1): failing checks' linter reports first (clean runs
|
||||
(SPEC 7.14.1): failing checks' linter reports first (clean runs
|
||||
print no report), then the `Results:` table, then the pass banner
|
||||
or the `Sanity Failed` verdict with per-check details.
|
||||
|
||||
@@ -352,7 +352,7 @@ def wiki_sanity(
|
||||
"""Run all sanity checks and print the aggregated report.
|
||||
|
||||
Human-readable runs draw the same live per-check progress as
|
||||
run_sanity (SPEC 7.16.2) through the shared ProgressDisplay: one
|
||||
run_sanity (SPEC 7.14.2) through the shared ProgressDisplay: one
|
||||
bar line per check on a terminal, `Running Wiki Sanity ....`
|
||||
progress dots on an interval when piped or when `non_interactive`
|
||||
is set. JSON runs skip the display so their output stays parseable.
|
||||
|
||||
@@ -7,9 +7,9 @@ and SHA256 hashes for other files (like JSON) that don't have version tagging ye
|
||||
The module handles:
|
||||
- Comparing wiki core files against template versions
|
||||
- Identifying files that need updates
|
||||
- Special handling for settings files (preserving user customizations)
|
||||
- Yielding to the owner's markdown: a newer template is written beside
|
||||
the file as `<stem>-update.md` for the LLM to merge (SPEC 7.2.11)
|
||||
- Yielding to the owner: a newer markdown file, or a differing
|
||||
fiona-settings.json, is written beside the file as
|
||||
`<stem>-update<suffix>` for the LLM to merge (SPEC 7.1.2.11)
|
||||
- Presenting update summaries to users
|
||||
"""
|
||||
|
||||
@@ -57,10 +57,10 @@ SETTINGS_FILE = "fiona-settings.json"
|
||||
# Read-only zones that should never be modified
|
||||
READ_ONLY_ZONES = ["personal/", "raw/"]
|
||||
|
||||
# AI/LLM: stem suffix of the file that carries a newer template (SPEC 7.2.11.1)
|
||||
# AI/LLM: stem suffix of the file that carries a newer template (SPEC 7.1.2.11.1)
|
||||
UPDATE_SUFFIX = "-update"
|
||||
|
||||
# Generated by AI/LLM: 2026-09-30 - short SHA-256 width in the update report (7.2.12)
|
||||
# Generated by AI/LLM: 2026-09-30 - short SHA-256 width in the update report (7.1.2.12)
|
||||
SHORT_HASH_LENGTH = 8
|
||||
|
||||
__all__ = [
|
||||
@@ -161,7 +161,7 @@ def get_llm_wiki_source_path() -> Path:
|
||||
|
||||
|
||||
def update_file_path(file_path: Path) -> Path:
|
||||
"""Return the sibling update file for a core file (SPEC 7.2.11.1).
|
||||
"""Return the sibling update file for a core file (SPEC 7.1.2.11.1).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - `AGENTS.md` gives `AGENTS-update.md`.
|
||||
|
||||
@@ -279,7 +279,7 @@ def is_version_newer(candidate: str, baseline: str) -> bool:
|
||||
|
||||
|
||||
def template_sha256(template_path: Path) -> str:
|
||||
"""Hash the text wiki init would write for a template file (SPEC 7.2.12).
|
||||
"""Hash the text wiki init would write for a template file (SPEC 7.1.2.12).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - DATE_PLACEHOLDER expanded, endings kept.
|
||||
|
||||
@@ -326,14 +326,14 @@ def _content_differs(wiki_file: Path, template_file: Path) -> bool:
|
||||
def compare_md_file(file_path: Path, template_path: Path) -> FileComparisonResult:
|
||||
"""Compare a markdown file against its template version using frontmatter.
|
||||
|
||||
Classification (SPEC 7.2.1). An existing markdown file is never
|
||||
Classification (SPEC 7.1.2.1). An existing markdown file is never
|
||||
overwritten:
|
||||
- template version newer -> conflict, the template goes to the
|
||||
`<stem>-update.md` sibling (SPEC 7.2.11)
|
||||
`<stem>-update.md` sibling (SPEC 7.1.2.11)
|
||||
- wiki version newer or content diverged at the same version -> locally
|
||||
modified (skipped and reported by the update run)
|
||||
- files without version frontmatter compare SHA-256 and are a conflict
|
||||
when the hashes differ (SPEC 7.2.12)
|
||||
when the hashes differ (SPEC 7.1.2.12)
|
||||
|
||||
Modified by AI/LLM: 2026-09-30 - SHA-256 compare when a version is missing.
|
||||
|
||||
@@ -375,7 +375,7 @@ def compare_non_md_file(file_path: Path, template_path: Path) -> FileComparisonR
|
||||
|
||||
This is used for files without version tagging (e.g., JSON files).
|
||||
|
||||
Modified by AI/LLM: 2026-09-30 - template side hashes init's text (7.2.12).
|
||||
Modified by AI/LLM: 2026-09-30 - template side hashes init's text (7.1.2.12).
|
||||
|
||||
Args:
|
||||
file_path: Path to the current wiki file.
|
||||
@@ -396,11 +396,9 @@ def compare_non_md_file(file_path: Path, template_path: Path) -> FileComparisonR
|
||||
|
||||
|
||||
def compare_settings_file(file_path: Path, template_path: Path) -> FileComparisonResult:
|
||||
"""Compare settings file with special handling to preserve user customizations.
|
||||
"""Compare settings by hash and yield on a difference (SPEC 7.1.2.3).
|
||||
|
||||
The comparison itself is hash-based (the JSON file has no frontmatter
|
||||
version); the update run applies copy_settings_with_preservation so user
|
||||
values survive the update.
|
||||
Modified by AI/LLM: 2026-10-01 - settings drift is a conflict, not a merge.
|
||||
|
||||
Args:
|
||||
file_path: Path to the current settings file.
|
||||
@@ -411,6 +409,10 @@ def compare_settings_file(file_path: Path, template_path: Path) -> FileCompariso
|
||||
"""
|
||||
result = compare_non_md_file(file_path, template_path)
|
||||
result.is_settings_file = True
|
||||
if result.needs_update:
|
||||
result.needs_update = False
|
||||
result.is_conflict = True
|
||||
result.update_path = update_file_path(file_path)
|
||||
return result
|
||||
|
||||
|
||||
@@ -585,7 +587,7 @@ def check_wiki_updates(directory: str | Path = ".") -> UpdateSummary:
|
||||
wiki_file = wiki_root / relative
|
||||
if _is_protected(relative, wiki_root, patterns):
|
||||
continue
|
||||
# AI/LLM: under wiki/ only an existing markdown page can conflict (SPEC 7.2.9)
|
||||
# AI/LLM: under wiki/ only an existing markdown page can conflict (SPEC 7.1.2.9)
|
||||
wiki_page = _is_wiki_page_path(relative)
|
||||
if wiki_page and (relative.suffix != ".md" or not wiki_file.exists()):
|
||||
continue
|
||||
@@ -605,12 +607,12 @@ def check_wiki_updates(directory: str | Path = ".") -> UpdateSummary:
|
||||
|
||||
if result.is_conflict:
|
||||
summary.conflicts.append(result)
|
||||
if result.is_settings_file:
|
||||
summary.settings_file = wiki_file
|
||||
elif wiki_page:
|
||||
continue
|
||||
elif result.needs_update:
|
||||
summary.files_to_update.append(result)
|
||||
if result.is_settings_file:
|
||||
summary.settings_file = wiki_file
|
||||
elif result.is_locally_modified:
|
||||
summary.files_skipped.append(result)
|
||||
|
||||
@@ -622,7 +624,7 @@ def check_wiki_updates(directory: str | Path = ".") -> UpdateSummary:
|
||||
def _change_detail(result: FileComparisonResult) -> str:
|
||||
"""Return the ` (current -> template)` detail for one report line.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - versions, else short SHA-256 (7.2.12.2).
|
||||
Generated by AI/LLM: 2026-09-30 - versions, else short SHA-256 (7.1.2.12.2).
|
||||
"""
|
||||
if result.current_version and result.template_version:
|
||||
return f" ({result.current_version} -> {result.template_version})"
|
||||
@@ -712,11 +714,12 @@ def update_core_files(directory: str | Path = ".", force: bool = False, yes: boo
|
||||
- When neither flag is set, presents list of files and prompts for y/n.
|
||||
- Never overwrites files in read-only zones.
|
||||
- Never overwrites an existing markdown file; a conflict writes the
|
||||
template to its `<stem>-update.md` sibling (SPEC 7.2.11).
|
||||
- Settings files are updated with user customizations preserved.
|
||||
template to its `<stem>-update.md` sibling (SPEC 7.1.2.11).
|
||||
- A differing settings file stays byte-for-byte; the template is
|
||||
written as `fiona-settings-update.json` (SPEC 7.1.2.3).
|
||||
- Returns summary of all updated files.
|
||||
|
||||
Modified by AI/LLM: 2026-09-30 - write update files for conflicts.
|
||||
Modified by AI/LLM: 2026-10-01 - settings drift is a conflict.
|
||||
"""
|
||||
wiki_root = Path(directory).resolve()
|
||||
|
||||
@@ -745,15 +748,10 @@ def update_core_files(directory: str | Path = ".", force: bool = False, yes: boo
|
||||
for relative in summary.files_to_add:
|
||||
_copy_file(template_dir / relative, wiki_root / relative)
|
||||
|
||||
# Update outdated files; settings get the merge treatment
|
||||
# Update outdated non-markdown files in place
|
||||
for result in summary.files_to_update:
|
||||
relative = result.file_path.relative_to(wiki_root)
|
||||
if result.is_settings_file:
|
||||
copy_settings_with_preservation(
|
||||
result.file_path, template_dir / relative
|
||||
)
|
||||
else:
|
||||
_copy_file(template_dir / relative, result.file_path)
|
||||
_copy_file(template_dir / relative, result.file_path)
|
||||
|
||||
for result in summary.conflicts:
|
||||
relative = result.file_path.relative_to(wiki_root)
|
||||
@@ -959,7 +957,7 @@ def update_main(
|
||||
)
|
||||
if summary.conflicts:
|
||||
print(
|
||||
"Merge each <stem>-update.md into its file: "
|
||||
"Merge each <stem>-update<suffix> into its file: "
|
||||
"run fiona-assistant housekeeping."
|
||||
)
|
||||
|
||||
|
||||
@@ -114,7 +114,7 @@ def _copy_file(source_item: Path, dest_item: Path) -> None:
|
||||
"""Copy one file, replacing date placeholders in text files.
|
||||
|
||||
Modified by AI/LLM: 2026-09-30 - keep the template's line endings, so a
|
||||
Windows copy hashes the same as the template (SPEC 7.2.5).
|
||||
Windows copy hashes the same as the template (SPEC 7.1.2.5).
|
||||
"""
|
||||
# Read the file content
|
||||
try:
|
||||
@@ -161,7 +161,7 @@ def wiki_init(directory: str = ".") -> str:
|
||||
|
||||
It also initializes a git repository and makes the initial commit with
|
||||
all the template files. The personal/ directory is excluded from git via
|
||||
.gitignore as per SPEC 7.5.
|
||||
.gitignore as per SPEC 7.12.
|
||||
|
||||
Args:
|
||||
directory: The directory to initialize as an llm-wiki directory.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
"""Tests for bootstrap install modes (SPEC 7.24).
|
||||
"""Tests for bootstrap install modes (SPEC 7.21).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - local and no-env install options.
|
||||
"""
|
||||
@@ -54,7 +54,7 @@ def _powershell(*args: str) -> subprocess.CompletedProcess[str]:
|
||||
|
||||
|
||||
class TestPipInstallArgs:
|
||||
"""SPEC 7.24.1 through 7.24.5: pip argument matrix."""
|
||||
"""SPEC 7.21.1 through 7.21.5: pip argument matrix."""
|
||||
|
||||
def test_local_installs_without_editable_mode(self, bootstrap_install):
|
||||
"""--local installs '.' and does not pass -e or the dev extra."""
|
||||
@@ -120,7 +120,7 @@ class TestPipInstallArgs:
|
||||
|
||||
|
||||
class TestBootstrapScripts:
|
||||
"""SPEC 7.24.2 and 7.24.6: both scripts honor the flags."""
|
||||
"""SPEC 7.21.2 and 7.21.6: both scripts honor the flags."""
|
||||
|
||||
def test_both_scripts_call_the_helper(self):
|
||||
"""Bash and PowerShell pass --local and --no-env to the helper."""
|
||||
|
||||
@@ -97,7 +97,7 @@ class TestFionaMain:
|
||||
def test_main_wiki_ingest_help(self, capsys):
|
||||
"""Test wiki ingest --help is printed by the ingest parser.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 4.14 help stays on this command.
|
||||
Generated by AI/LLM: 2026-09-30 - SPEC 4.7.6 help stays on this command.
|
||||
"""
|
||||
with (
|
||||
patch("sys.argv", ["fiona-assistant", "wiki", "ingest", "--help"]),
|
||||
@@ -234,7 +234,7 @@ class TestFionaMain:
|
||||
assert exc_info.value.code == 0
|
||||
captured = capsys.readouterr()
|
||||
assert "SANITY PASSED" in captured.out
|
||||
# Non-interactive output carries no ANSI cursor codes (SPEC 7.16.2)
|
||||
# Non-interactive output carries no ANSI cursor codes (SPEC 7.14.2)
|
||||
assert "\x1b[" not in captured.out
|
||||
|
||||
def test_main_wiki_sanity_passes_non_interactive(self, minimal_wiki):
|
||||
@@ -470,7 +470,7 @@ class TestFionaMain:
|
||||
assert "No violations found" in captured.out or "0" in captured.out
|
||||
|
||||
class TestFionaLibrarianTocFile:
|
||||
"""Tests for 'fiona-assistant librarian toc file' dispatch (SPEC 7.15.2)."""
|
||||
"""Tests for 'fiona-assistant librarian toc file' dispatch (SPEC 7.3.1.2)."""
|
||||
|
||||
def test_main_librarian_toc_file_generates_per_file_toc(self, capsys, hermetic_toc_settings):
|
||||
"""Test that 'librarian toc file <path>' writes a TOC inside the file."""
|
||||
|
||||
+17
-10
@@ -1,4 +1,4 @@
|
||||
"""Tests for fiona-assistant housekeeping (SPEC 4.15, 7.26).
|
||||
"""Tests for fiona-assistant housekeeping (SPEC 4.8, 7.2).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - housekeeping routine tests.
|
||||
"""
|
||||
@@ -63,7 +63,7 @@ def _hashes(root: Path) -> dict:
|
||||
|
||||
|
||||
class TestRunHousekeeping:
|
||||
"""Tests for the housekeeping steps (SPEC 7.26)."""
|
||||
"""Tests for the housekeeping steps (SPEC 7.2)."""
|
||||
|
||||
def test_steps_run_in_order(self, hk_wiki):
|
||||
results = run_housekeeping(hk_wiki)
|
||||
@@ -78,7 +78,7 @@ class TestRunHousekeeping:
|
||||
assert {step["status"] for step in results["steps"]} == {"PASS"}
|
||||
|
||||
def test_conflict_is_warn_and_writes_nothing(self, hk_wiki):
|
||||
"""SPEC 7.26.2: check-update reports conflicts without writing."""
|
||||
"""SPEC 7.2.2: check-update reports conflicts without writing."""
|
||||
_page(hk_wiki / "AGENTS.md", "agents", "1.0.0", body="See [index](./wiki/index.md).\n")
|
||||
|
||||
step = _step(run_housekeeping(hk_wiki), "check-update")
|
||||
@@ -92,7 +92,7 @@ class TestRunHousekeeping:
|
||||
assert not (hk_wiki / "AGENTS-update.md").exists()
|
||||
|
||||
def test_pending_update_file_fails_merge(self, hk_wiki):
|
||||
"""SPEC 7.26.3: every *-update.md waits for a merge."""
|
||||
"""SPEC 7.2.3: every *-update.md waits for a merge."""
|
||||
_page(hk_wiki / "wiki" / "schema-update.md", "schema", "1.5.0")
|
||||
_page(hk_wiki / "orphan-update.md", "orphan")
|
||||
|
||||
@@ -100,8 +100,15 @@ class TestRunHousekeeping:
|
||||
|
||||
assert step["status"] == "FAIL"
|
||||
assert step["summary"] == "2 update file(s) wait for a merge"
|
||||
(hk_wiki / "fiona-settings-update.json").write_text("{}\n", encoding="utf-8")
|
||||
|
||||
step = _step(run_housekeeping(hk_wiki), "merge")
|
||||
|
||||
assert step["status"] == "FAIL"
|
||||
assert step["summary"] == "3 update file(s) wait for a merge"
|
||||
assert "wiki/schema-update.md -> wiki/schema.md (target missing)" in step["details"]
|
||||
assert "orphan-update.md -> orphan.md (target missing)" in step["details"]
|
||||
assert "fiona-settings-update.json -> fiona-settings.json" in step["details"]
|
||||
assert any("1.5.0" in action and "wiki/schema-update.md" in action
|
||||
for action in step["next"])
|
||||
|
||||
@@ -128,7 +135,7 @@ class TestRunHousekeeping:
|
||||
assert step["status"] == "PASS"
|
||||
|
||||
def test_raw_page_is_ingest_warn(self, hk_wiki):
|
||||
"""SPEC 7.26.4: pages at status: raw wait for a refine."""
|
||||
"""SPEC 7.2.4: pages at status: raw wait for a refine."""
|
||||
_page(hk_wiki / "wiki" / "sources" / "s.md", "s", extra="status: raw\n",
|
||||
body="From [index](../index.md).\n")
|
||||
|
||||
@@ -139,7 +146,7 @@ class TestRunHousekeeping:
|
||||
assert step["next"] == ["Refine each raw page, then set status: refined."]
|
||||
|
||||
def test_dead_link_fails_sanity(self, hk_wiki):
|
||||
"""SPEC 7.26.5: a sanity violation is FAIL with the report lines."""
|
||||
"""SPEC 7.2.5: a sanity violation is FAIL with the report lines."""
|
||||
_page(hk_wiki / "wiki" / "a.md", "a", body="See [gone](./gone.md).\n")
|
||||
|
||||
step = _step(run_housekeeping(hk_wiki), "sanity")
|
||||
@@ -149,7 +156,7 @@ class TestRunHousekeeping:
|
||||
assert any("a.md" in line for line in step["details"])
|
||||
|
||||
def test_graph_written_and_orphans_warned(self, hk_wiki):
|
||||
"""SPEC 7.26.6: the graph lands at the wiki root; orphans warn."""
|
||||
"""SPEC 7.2.6: the graph lands at the wiki root; orphans warn."""
|
||||
_page(hk_wiki / "wiki" / "lonely.md", "lonely")
|
||||
_page(hk_wiki / "wiki" / "lonely-update.md", "lonely")
|
||||
|
||||
@@ -167,7 +174,7 @@ class TestRunHousekeeping:
|
||||
assert step["status"] == "FAIL"
|
||||
|
||||
def test_every_step_runs_after_a_failure(self, hk_wiki):
|
||||
"""SPEC 7.26.1: merge and sanity fail, graph still runs."""
|
||||
"""SPEC 7.2.1: merge and sanity fail, graph still runs."""
|
||||
_page(hk_wiki / "AGENTS-update.md", "agents", "3.0.0")
|
||||
_page(hk_wiki / "wiki" / "a.md", "a", body="See [gone](./gone.md).\n")
|
||||
|
||||
@@ -179,7 +186,7 @@ class TestRunHousekeeping:
|
||||
assert results["passed"] is False
|
||||
|
||||
def test_only_graph_is_written(self, hk_wiki):
|
||||
"""SPEC 7.26.7: housekeeping changes nothing but wiki_graph.html."""
|
||||
"""SPEC 7.2.7: housekeeping changes nothing but wiki_graph.html."""
|
||||
_page(hk_wiki / "AGENTS.md", "agents", "1.0.0", body="See [index](./wiki/index.md).\n")
|
||||
before = _hashes(hk_wiki)
|
||||
|
||||
@@ -199,7 +206,7 @@ class TestRunHousekeeping:
|
||||
|
||||
|
||||
class TestHousekeepingReport:
|
||||
"""Tests for the human and JSON output (SPEC 4.15, 7.26.8)."""
|
||||
"""Tests for the human and JSON output (SPEC 4.8, 7.2.8)."""
|
||||
|
||||
def test_human_report_passes(self, hk_wiki):
|
||||
report = format_housekeeping_report(run_housekeeping(hk_wiki))
|
||||
|
||||
+23
-23
@@ -1,4 +1,4 @@
|
||||
"""Tests for wiki ingest (SPEC 7.25).
|
||||
"""Tests for wiki ingest (SPEC 7.1.5).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - acceptance checks for fetch, archive, convert, and write.
|
||||
"""
|
||||
@@ -236,7 +236,7 @@ def _hashes(root: pathlib.Path) -> dict[str, str]:
|
||||
|
||||
|
||||
def test_slug_from_console_url() -> None:
|
||||
"""SPEC 7.25.2.6: the last three segments become one hyphenated slug."""
|
||||
"""SPEC 7.1.5.2.6: the last three segments become one hyphenated slug."""
|
||||
assert slug_from_url("https://host/job/performance_TL153/2108/console") == (
|
||||
"performance-tl153-2108-console"
|
||||
)
|
||||
@@ -315,7 +315,7 @@ def test_text_fallback_decode_warns(tmp_path: pathlib.Path) -> None:
|
||||
|
||||
|
||||
def test_register_converter_without_pipeline_edits(tmp_path: pathlib.Path) -> None:
|
||||
"""SPEC 7.25.1.2: a new format is one class and one registration."""
|
||||
"""SPEC 7.1.5.1.2: a new format is one class and one registration."""
|
||||
root = _wiki(tmp_path)
|
||||
sample = tmp_path / "sample.xtest"
|
||||
sample.write_bytes(b"hello")
|
||||
@@ -329,7 +329,7 @@ def test_register_converter_without_pipeline_edits(tmp_path: pathlib.Path) -> No
|
||||
|
||||
|
||||
def test_ftp_scheme_writes_nothing(tmp_path: pathlib.Path) -> None:
|
||||
"""SPEC 7.25.2.1: an unsupported scheme exits 1 and writes nothing."""
|
||||
"""SPEC 7.1.5.2.1: an unsupported scheme exits 1 and writes nothing."""
|
||||
root = _wiki(tmp_path)
|
||||
before = _hashes(root)
|
||||
code, stdout, stderr = _run(root, "ftp://host/a.pdf")
|
||||
@@ -353,7 +353,7 @@ def test_missing_file_and_directory(tmp_path: pathlib.Path) -> None:
|
||||
|
||||
|
||||
def test_download_uses_content_type_extension(tmp_path: pathlib.Path) -> None:
|
||||
"""SPEC 7.25.2.5: a PDF response with no suffix is saved as ``.pdf``."""
|
||||
"""SPEC 7.1.5.2.5: a PDF response with no suffix is saved as ``.pdf``."""
|
||||
root = _wiki(tmp_path)
|
||||
body = _pdf(["Hello"])
|
||||
opener = _FakeOpener(body, "application/pdf", final_url="https://host/report")
|
||||
@@ -369,7 +369,7 @@ def test_download_uses_content_type_extension(tmp_path: pathlib.Path) -> None:
|
||||
|
||||
|
||||
def test_download_404_leaves_ingest_unchanged(tmp_path: pathlib.Path) -> None:
|
||||
"""SPEC 7.25.2.3: a 404 exits 1 and does not add files."""
|
||||
"""SPEC 7.1.5.2.3: a 404 exits 1 and does not add files."""
|
||||
root = _wiki(tmp_path)
|
||||
(root / "ingest" / "keep.txt").write_text("stay", encoding="utf-8")
|
||||
before = sorted(path.name for path in (root / "ingest").iterdir())
|
||||
@@ -394,7 +394,7 @@ def test_download_over_limit_is_deleted(tmp_path: pathlib.Path) -> None:
|
||||
|
||||
|
||||
def test_extensionless_pdf_uses_pdf_converter(tmp_path: pathlib.Path) -> None:
|
||||
"""SPEC 7.25.2.4: leading ``%PDF-`` bytes select the pdf converter."""
|
||||
"""SPEC 7.1.5.2.4: leading ``%PDF-`` bytes select the pdf converter."""
|
||||
root = _wiki(tmp_path)
|
||||
source = tmp_path / "notes"
|
||||
source.write_bytes(_pdf(["Page text"]))
|
||||
@@ -406,7 +406,7 @@ def test_extensionless_pdf_uses_pdf_converter(tmp_path: pathlib.Path) -> None:
|
||||
|
||||
|
||||
def test_raw_override_and_escape(tmp_path: pathlib.Path) -> None:
|
||||
"""SPEC 7.25.3.2: ``-r`` places the file, and ``..`` exits 1."""
|
||||
"""SPEC 7.1.5.3.2: ``-r`` places the file, and ``..`` exits 1."""
|
||||
root = _wiki(tmp_path)
|
||||
html = tmp_path / "page.html"
|
||||
html.write_text("<html><body><article><p>Hi</p></article></body></html>", encoding="utf-8")
|
||||
@@ -424,7 +424,7 @@ def test_raw_override_and_escape(tmp_path: pathlib.Path) -> None:
|
||||
|
||||
|
||||
def test_reuses_identical_bytes(tmp_path: pathlib.Path) -> None:
|
||||
"""SPEC 7.25.3.3: a second name and ``-r`` reuse the first raw copy."""
|
||||
"""SPEC 7.1.5.3.3: a second name and ``-r`` reuse the first raw copy."""
|
||||
root = _wiki(tmp_path)
|
||||
first = tmp_path / "one.txt"
|
||||
first.write_text("same bytes\n", encoding="utf-8", newline="\n")
|
||||
@@ -443,7 +443,7 @@ def test_reuses_identical_bytes(tmp_path: pathlib.Path) -> None:
|
||||
|
||||
|
||||
def test_changed_file_gets_a_second_raw_name(tmp_path: pathlib.Path) -> None:
|
||||
"""SPEC 7.25.3.4: a changed file of the same name is stored as ``slug-2``."""
|
||||
"""SPEC 7.1.5.3.4: a changed file of the same name is stored as ``slug-2``."""
|
||||
root = _wiki(tmp_path)
|
||||
source = tmp_path / "notes.txt"
|
||||
source.write_text("first\n", encoding="utf-8", newline="\n")
|
||||
@@ -458,7 +458,7 @@ def test_changed_file_gets_a_second_raw_name(tmp_path: pathlib.Path) -> None:
|
||||
|
||||
|
||||
def test_duplicate_exits_zero_and_skips_the_log(tmp_path: pathlib.Path) -> None:
|
||||
"""SPEC 7.25.3.5: the same bytes report the first page and do not rewrite it."""
|
||||
"""SPEC 7.1.5.3.5: the same bytes report the first page and do not rewrite it."""
|
||||
root = _wiki(tmp_path)
|
||||
source = root / "ingest" / "a.txt"
|
||||
source.write_text("alpha\n", encoding="utf-8", newline="\n")
|
||||
@@ -480,7 +480,7 @@ def test_duplicate_exits_zero_and_skips_the_log(tmp_path: pathlib.Path) -> None:
|
||||
|
||||
|
||||
def test_ingest_drop_moves_and_personal_is_copied(tmp_path: pathlib.Path) -> None:
|
||||
"""SPEC 7.25.3.6: ``ingest/`` is moved. A file outside it is copied."""
|
||||
"""SPEC 7.1.5.3.6: ``ingest/`` is moved. A file outside it is copied."""
|
||||
root = _wiki(tmp_path)
|
||||
dropped = root / "ingest" / "a.pdf"
|
||||
dropped.write_bytes(_pdf(["Moved"]))
|
||||
@@ -499,7 +499,7 @@ def test_ingest_drop_moves_and_personal_is_copied(tmp_path: pathlib.Path) -> Non
|
||||
|
||||
|
||||
def test_unknown_bytes_archive_without_a_page(tmp_path: pathlib.Path) -> None:
|
||||
"""SPEC 7.25.4.1: random bytes exit 3 under ``raw/other``."""
|
||||
"""SPEC 7.1.5.4.1: random bytes exit 3 under ``raw/other``."""
|
||||
root = _wiki(tmp_path)
|
||||
source = tmp_path / "blob.xyz"
|
||||
source.write_bytes(b"\x00\x01\x02\xff")
|
||||
@@ -519,7 +519,7 @@ def test_unknown_bytes_archive_without_a_page(tmp_path: pathlib.Path) -> None:
|
||||
|
||||
|
||||
def test_encrypted_pdf_keeps_raw_and_skips_the_page(tmp_path: pathlib.Path) -> None:
|
||||
"""SPEC 7.25.4.2: an encrypted PDF exits 3 and the raw copy stays."""
|
||||
"""SPEC 7.1.5.4.2: an encrypted PDF exits 3 and the raw copy stays."""
|
||||
root = _wiki(tmp_path)
|
||||
source = tmp_path / "secret.pdf"
|
||||
source.write_bytes(_pdf(["hidden"], password="secret"))
|
||||
@@ -532,7 +532,7 @@ def test_encrypted_pdf_keeps_raw_and_skips_the_page(tmp_path: pathlib.Path) -> N
|
||||
|
||||
|
||||
def test_html_keeps_article_link_and_table(tmp_path: pathlib.Path) -> None:
|
||||
"""SPEC 7.25.4.5: article text, no script, an absolute link, and a pipe table."""
|
||||
"""SPEC 7.1.5.4.5: article text, no script, an absolute link, and a pipe table."""
|
||||
root = _wiki(tmp_path)
|
||||
html = """<!doctype html>
|
||||
<html lang="en"><head><title>Page Title</title></head>
|
||||
@@ -559,7 +559,7 @@ def test_html_keeps_article_link_and_table(tmp_path: pathlib.Path) -> None:
|
||||
|
||||
|
||||
def test_pdf_page_headings_and_blank_page(tmp_path: pathlib.Path) -> None:
|
||||
"""SPEC 7.25.4.6: pages are numbered, and a blank page is partial."""
|
||||
"""SPEC 7.1.5.4.6: pages are numbered, and a blank page is partial."""
|
||||
root = _wiki(tmp_path)
|
||||
numbered = tmp_path / "two.pdf"
|
||||
numbered.write_bytes(_pdf(["Alpha", "Beta"]))
|
||||
@@ -578,7 +578,7 @@ def test_pdf_page_headings_and_blank_page(tmp_path: pathlib.Path) -> None:
|
||||
|
||||
|
||||
def test_target_paths(tmp_path: pathlib.Path) -> None:
|
||||
"""SPEC 7.25.5.1: ``-t concepts`` writes under concepts. Escapes exit 1."""
|
||||
"""SPEC 7.1.5.5.1: ``-t concepts`` writes under concepts. Escapes exit 1."""
|
||||
root = _wiki(tmp_path)
|
||||
source = tmp_path / "idea.txt"
|
||||
source.write_text("idea\n", encoding="utf-8", newline="\n")
|
||||
@@ -597,7 +597,7 @@ def test_target_paths(tmp_path: pathlib.Path) -> None:
|
||||
|
||||
|
||||
def test_existing_page_refuses_until_force(tmp_path: pathlib.Path) -> None:
|
||||
"""SPEC 7.25.5.2: a second run exits 1. ``--force`` replaces the page."""
|
||||
"""SPEC 7.1.5.5.2: a second run exits 1. ``--force`` replaces the page."""
|
||||
root = _wiki(tmp_path)
|
||||
source = tmp_path / "item.txt"
|
||||
source.write_text("one\n", encoding="utf-8", newline="\n")
|
||||
@@ -620,7 +620,7 @@ def test_existing_page_refuses_until_force(tmp_path: pathlib.Path) -> None:
|
||||
|
||||
|
||||
def test_page_frontmatter_matches_raw_hash(tmp_path: pathlib.Path) -> None:
|
||||
"""SPEC 7.25.5.3 and 7.25.5.4: frontmatter is complete and the page has one H1."""
|
||||
"""SPEC 7.1.5.5.3 and 7.1.5.5.4: frontmatter is complete and the page has one H1."""
|
||||
root = _wiki(tmp_path)
|
||||
index_before = (root / "wiki" / "index.md").read_bytes()
|
||||
source = tmp_path / "story.md"
|
||||
@@ -653,7 +653,7 @@ def test_page_frontmatter_matches_raw_hash(tmp_path: pathlib.Path) -> None:
|
||||
|
||||
|
||||
def test_style_violations_become_one_warning(tmp_path: pathlib.Path) -> None:
|
||||
"""SPEC 7.25.5.5: violations the fixer leaves are counted in one warning."""
|
||||
"""SPEC 7.1.5.5.5: violations the fixer leaves are counted in one warning."""
|
||||
root = _wiki(tmp_path)
|
||||
source = tmp_path / "long.md"
|
||||
source.write_text("# Title\n\n" + ("word " * 40) + "\n", encoding="utf-8", newline="\n")
|
||||
@@ -664,7 +664,7 @@ def test_style_violations_become_one_warning(tmp_path: pathlib.Path) -> None:
|
||||
|
||||
|
||||
def test_raw_only_and_dry_run(tmp_path: pathlib.Path) -> None:
|
||||
"""SPEC 7.25.7 and 7.25.8: raw-only skips the page. A dry run writes nothing."""
|
||||
"""SPEC 7.1.5.7 and 7.1.5.8: raw-only skips the page. A dry run writes nothing."""
|
||||
root = _wiki(tmp_path)
|
||||
source = root / "ingest" / "only.txt"
|
||||
source.write_text("archive me\n", encoding="utf-8", newline="\n")
|
||||
@@ -688,7 +688,7 @@ def test_raw_only_and_dry_run(tmp_path: pathlib.Path) -> None:
|
||||
|
||||
|
||||
def test_pending_hides_refined_pages(tmp_path: pathlib.Path) -> None:
|
||||
"""SPEC 7.25.9: ``--pending`` lists raw pages and drops refined ones."""
|
||||
"""SPEC 7.1.5.9: ``--pending`` lists raw pages and drops refined ones."""
|
||||
root = _wiki(tmp_path)
|
||||
source = tmp_path / "open.txt"
|
||||
source.write_text("open\n", encoding="utf-8", newline="\n")
|
||||
@@ -716,7 +716,7 @@ def test_not_a_wiki_and_mutually_exclusive_args(tmp_path: pathlib.Path) -> None:
|
||||
|
||||
|
||||
def test_sanity_ignores_raw_markdown(tmp_path: pathlib.Path) -> None:
|
||||
"""SPEC 7.25.12: a raw markdown file with style violations does not fail sanity."""
|
||||
"""SPEC 7.1.5.12: a raw markdown file with style violations does not fail sanity."""
|
||||
root = _wiki(tmp_path)
|
||||
raw = root / "raw" / "articles"
|
||||
raw.mkdir(parents=True)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
"""Branch coverage for wiki ingest stages.
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - error paths and converter edges from SPEC 7.25.
|
||||
Generated by AI/LLM: 2026-09-30 - error paths and converter edges from SPEC 7.1.5.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
"""Tests for the shared logging configuration (SPEC 7.20)."""
|
||||
"""Tests for the shared logging configuration (SPEC 7.17)."""
|
||||
|
||||
import logging
|
||||
import re
|
||||
|
||||
@@ -1212,7 +1212,7 @@ class TestProgressDisplayNonInteractive:
|
||||
interval_seconds=3.0, expected_seconds=30.0, clock=clock,
|
||||
)
|
||||
|
||||
display.progress("lint1", {"result": 0, "duration_seconds": 7.5})
|
||||
display.progress("lint1", {"result": 0, "duration_seconds": 7.12})
|
||||
display.heartbeat(["lint2"])
|
||||
|
||||
# The dot comes from the interval tick, not from the finished
|
||||
@@ -1284,7 +1284,7 @@ class TestProgressDisplayInteractive:
|
||||
)
|
||||
|
||||
display.heartbeat(["lint1", "lint2"])
|
||||
display.progress("lint2", {"result": 0, "duration_seconds": 7.5})
|
||||
display.progress("lint2", {"result": 0, "duration_seconds": 7.12})
|
||||
|
||||
out = stream.getvalue()
|
||||
assert "lint2 " + "[" + "#" * 15 + "] 100% done (00:07)" in out
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
"""Tests for the sanity_manager module (SPEC 7.3).
|
||||
"""Tests for the sanity_manager module (SPEC 7.1.3).
|
||||
|
||||
Covers the aggregated wiki sanity report (markdownlint, python-ruff,
|
||||
mdlinter) with its modular check registry and the run_sanity-style
|
||||
output structure (SPEC 6.1/7.16.1).
|
||||
output structure (SPEC 6.1/7.14.1).
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -140,7 +140,7 @@ class TestRunWikiChecks:
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Report Format Tests (run_sanity structure, SPEC 6.1/7.16.1)
|
||||
# Report Format Tests (run_sanity structure, SPEC 6.1/7.14.1)
|
||||
# =============================================================================
|
||||
|
||||
class TestWikiSanityReport:
|
||||
@@ -158,7 +158,7 @@ class TestWikiSanityReport:
|
||||
assert "SANITY PASSED" in output
|
||||
# Clean runs print no linter reports (SPEC 6.1)
|
||||
assert "Violations\n" not in output
|
||||
# Every summary line carries an (MM:SS) timing suffix (SPEC 7.16.1)
|
||||
# Every summary line carries an (MM:SS) timing suffix (SPEC 7.14.1)
|
||||
assert re.search(
|
||||
r"mdlinter:\s+PASS - 0 violations \(\d{2}:\d{2}\)", output
|
||||
)
|
||||
@@ -304,11 +304,11 @@ class TestSanityMain:
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Progress Display Tests (SPEC 7.16.2)
|
||||
# Progress Display Tests (SPEC 7.14.2)
|
||||
# =============================================================================
|
||||
|
||||
class TestWikiSanityProgress:
|
||||
"""Tests for the in-run progress display wiring (SPEC 7.16.2)."""
|
||||
"""Tests for the in-run progress display wiring (SPEC 7.14.2)."""
|
||||
|
||||
@pytest.fixture
|
||||
def fake_display_class(self, monkeypatch):
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
"""Tests for the shared SanityRunner engine (SPEC 7.16.1).
|
||||
"""Tests for the shared SanityRunner engine (SPEC 7.14.1).
|
||||
|
||||
Covers the generalized class behind both the repository sanity runner
|
||||
(run_sanity) and the wiki sanity command (wiki.sanity_manager):
|
||||
|
||||
@@ -770,7 +770,7 @@ class TestMainSettings:
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Test: per-file TOC generation (SPEC 7.15.2)
|
||||
# Test: per-file TOC generation (SPEC 7.3.1.2)
|
||||
# =============================================================================
|
||||
|
||||
SAMPLE_DOC = """# Guide
|
||||
@@ -1345,7 +1345,7 @@ class TestPackagedFileTocSettings:
|
||||
|
||||
|
||||
class TestFolderTocValidation:
|
||||
"""Tests for folder-TOC target validation and reporting (SPEC 7.15.1)."""
|
||||
"""Tests for folder-TOC target validation and reporting (SPEC 7.3.1.1)."""
|
||||
|
||||
def test_main_file_target_exits_with_error(self, tmp_path, capsys):
|
||||
"""Should exit 1 with a hint when the target is a file, not a dir.
|
||||
@@ -1543,7 +1543,7 @@ class TestTocMarker:
|
||||
def test_config_change_updates_marker(self, tmp_path):
|
||||
"""Should keep the marker range when the settings range changes.
|
||||
|
||||
The marker params have priority over the settings (SPEC 7.15.2),
|
||||
The marker params have priority over the settings (SPEC 7.3.1.2),
|
||||
so a settings change alone leaves an existing TOC unchanged.
|
||||
"""
|
||||
doc = tmp_path / "doc.md"
|
||||
|
||||
@@ -429,7 +429,7 @@ class TestCheckWikiUpdates:
|
||||
assert isinstance(summary, UpdateSummary)
|
||||
|
||||
def test_real_init_is_up_to_date(self, pristine_wiki):
|
||||
"""Test a real wiki init reports nothing to update on any OS (SPEC 7.2.5).
|
||||
"""Test a real wiki init reports nothing to update on any OS (SPEC 7.1.2.5).
|
||||
|
||||
Generated by AI/LLM: 2026-09-30 - init must keep template line endings.
|
||||
"""
|
||||
@@ -692,7 +692,7 @@ class TestConstants:
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# Implementation Tests (SPEC 7.2)
|
||||
# Implementation Tests (SPEC 7.1.2)
|
||||
# =============================================================================
|
||||
|
||||
def _write_md(path: Path, version: str, body: str = "# Doc\n", name: str = "doc"):
|
||||
@@ -780,7 +780,7 @@ class TestCompareMdFileVersions:
|
||||
assert result.template_version == "1.0.0"
|
||||
|
||||
def test_newer_template_is_conflict(self, tmp_path):
|
||||
"""Test a newer template is a conflict, never an overwrite (SPEC 7.2.1.1)."""
|
||||
"""Test a newer template is a conflict, never an overwrite (SPEC 7.1.2.1.1)."""
|
||||
wiki_file = tmp_path / "file.md"
|
||||
template_file = tmp_path / "template.md"
|
||||
_write_md(wiki_file, "1.0.0", body="# Old\n")
|
||||
@@ -880,7 +880,9 @@ class TestCompareSettingsFileHashes:
|
||||
|
||||
result = compare_settings_file(wiki_file, template_file)
|
||||
|
||||
assert result.needs_update is True
|
||||
assert result.needs_update is False
|
||||
assert result.is_conflict is True
|
||||
assert result.update_path == wiki_file.with_name("fiona-settings-update.json")
|
||||
|
||||
|
||||
class TestGetAllTemplateFilesImplemented:
|
||||
@@ -1024,7 +1026,7 @@ class TestCheckWikiUpdatesImplemented:
|
||||
assert not (wiki / "AGENTS-update.md").exists()
|
||||
|
||||
def test_wiki_page_older_than_template_is_conflict(self, template_wiki_pair):
|
||||
"""Test an older wiki/ template page is a conflict (SPEC 7.2.9)."""
|
||||
"""Test an older wiki/ template page is a conflict (SPEC 7.1.2.9)."""
|
||||
_template, wiki = template_wiki_pair
|
||||
_write_md(wiki / "wiki" / "index.md", "0.1.0", body="# User index\n", name="index")
|
||||
|
||||
@@ -1035,7 +1037,7 @@ class TestCheckWikiUpdatesImplemented:
|
||||
]
|
||||
|
||||
def test_conflict_clears_at_template_version(self, template_wiki_pair):
|
||||
"""Test a merged file at the template version is no conflict (SPEC 7.2.11.4)."""
|
||||
"""Test a merged file at the template version is no conflict (SPEC 7.1.2.11.4)."""
|
||||
_template, wiki = template_wiki_pair
|
||||
_write_md(wiki / "AGENTS.md", "2.0.0", body="# Merged agents\n", name="agents")
|
||||
|
||||
@@ -1100,9 +1102,11 @@ class TestCheckWikiUpdatesImplemented:
|
||||
|
||||
assert summary.settings_file == (wiki / "fiona-settings.json").resolve()
|
||||
settings_results = [
|
||||
r for r in summary.files_to_update if r.is_settings_file
|
||||
r for r in summary.conflicts if r.is_settings_file
|
||||
]
|
||||
assert len(settings_results) == 1
|
||||
assert settings_results[0].update_path.name == "fiona-settings-update.json"
|
||||
assert not any(r.is_settings_file for r in summary.files_to_update)
|
||||
|
||||
def test_user_created_file_not_flagged(self, template_wiki_pair):
|
||||
_template, wiki = template_wiki_pair
|
||||
@@ -1185,7 +1189,7 @@ class TestUpdateCoreFilesImplemented:
|
||||
"""Tests for performing the actual update."""
|
||||
|
||||
def test_yes_keeps_outdated_file_and_writes_update_file(self, template_wiki_pair):
|
||||
"""Test update yields to the owner and writes AGENTS-update.md (SPEC 7.2.6)."""
|
||||
"""Test update yields to the owner and writes AGENTS-update.md (SPEC 7.1.2.6)."""
|
||||
_template, wiki = template_wiki_pair
|
||||
owner = "---\nname: agents\nversion: 1.0.0\n---\n# Agents v1\n"
|
||||
(wiki / "AGENTS.md").write_text(owner, encoding="utf-8")
|
||||
@@ -1200,7 +1204,7 @@ class TestUpdateCoreFilesImplemented:
|
||||
assert summary.files_to_update == []
|
||||
|
||||
def test_update_file_expands_date_placeholder(self, template_wiki_pair):
|
||||
"""Test the update file holds the expanded template (SPEC 7.2.11.2)."""
|
||||
"""Test the update file holds the expanded template (SPEC 7.1.2.11.2)."""
|
||||
template, wiki = template_wiki_pair
|
||||
_write_md(
|
||||
template / "README.md", "2.0.0",
|
||||
@@ -1216,7 +1220,7 @@ class TestUpdateCoreFilesImplemented:
|
||||
assert sorted(p.name for p in wiki.glob("*-update.md")) == ["README-update.md"]
|
||||
|
||||
def test_dry_run_writes_no_update_file(self, template_wiki_pair):
|
||||
"""Test --dry-run lists the conflict and writes nothing (SPEC 7.2.11.3)."""
|
||||
"""Test --dry-run lists the conflict and writes nothing (SPEC 7.1.2.11.3)."""
|
||||
_template, wiki = template_wiki_pair
|
||||
_write_md(wiki / "AGENTS.md", "1.0.0", body="# Agents v1\n", name="agents")
|
||||
|
||||
@@ -1225,7 +1229,7 @@ class TestUpdateCoreFilesImplemented:
|
||||
assert list(wiki.rglob("*-update.md")) == []
|
||||
|
||||
def test_wiki_schema_conflict_writes_only_its_update_file(self, template_wiki_pair):
|
||||
"""Test a wiki/ conflict writes one sibling update file (SPEC 7.2.11.1)."""
|
||||
"""Test a wiki/ conflict writes one sibling update file (SPEC 7.1.2.11.1)."""
|
||||
template, wiki = template_wiki_pair
|
||||
_write_md(template / "wiki" / "schema.md", "1.5.0", body="# Schema\n", name="schema")
|
||||
owner = "---\nname: schema\nversion: 1.4.0\n---\n# My tags\n"
|
||||
@@ -1307,17 +1311,18 @@ class TestUpdateCoreFilesImplemented:
|
||||
user_content
|
||||
)
|
||||
|
||||
def test_settings_merge_preserves_user_values(self, template_wiki_pair):
|
||||
_template, wiki = template_wiki_pair
|
||||
(wiki / "fiona-settings.json").write_text(
|
||||
json.dumps({"a": 1, "user_key": "custom"}), encoding="utf-8"
|
||||
)
|
||||
def test_settings_conflict_keeps_owner_and_writes_update(self, template_wiki_pair):
|
||||
"""SPEC 7.1.2.3: a drifted settings file is a conflict, not a merge."""
|
||||
template, wiki = template_wiki_pair
|
||||
owner = json.dumps({"a": 1, "user_key": "custom"})
|
||||
(wiki / "fiona-settings.json").write_text(owner, encoding="utf-8")
|
||||
|
||||
update_core_files(str(wiki), yes=True)
|
||||
|
||||
merged = json.loads((wiki / "fiona-settings.json").read_text(encoding="utf-8"))
|
||||
assert merged["user_key"] == "custom"
|
||||
assert merged["a"] == 1
|
||||
assert (wiki / "fiona-settings.json").read_text(encoding="utf-8") == owner
|
||||
assert (wiki / "fiona-settings-update.json").read_text(encoding="utf-8") == (
|
||||
(template / "fiona-settings.json").read_text(encoding="utf-8")
|
||||
)
|
||||
|
||||
def test_requires_confirmation_without_flags(self, template_wiki_pair):
|
||||
_template, wiki = template_wiki_pair
|
||||
@@ -1481,7 +1486,7 @@ class TestFormatCheckUpdateOutputSkipped:
|
||||
|
||||
|
||||
# =============================================================================
|
||||
# SHA-256 comparison for files without a version (SPEC 7.2.12)
|
||||
# SHA-256 comparison for files without a version (SPEC 7.1.2.12)
|
||||
# Generated by AI/LLM: 2026-09-30 - hash compare and short-hash report.
|
||||
# =============================================================================
|
||||
|
||||
@@ -1497,7 +1502,7 @@ class TestSha256Comparison:
|
||||
"""Tests for hash comparison of files without a version."""
|
||||
|
||||
def test_date_placeholder_template_matches_init_copy(self, tmp_path):
|
||||
"""A template with DATE_PLACEHOLDER matches its init copy (SPEC 7.2.12.1)."""
|
||||
"""A template with DATE_PLACEHOLDER matches its init copy (SPEC 7.1.2.12.1)."""
|
||||
template_file = tmp_path / "template.py"
|
||||
wiki_file = tmp_path / "example.py"
|
||||
template_file.write_text("# created DATE_PLACEHOLDER\n", encoding="utf-8", newline="\n")
|
||||
@@ -1556,7 +1561,7 @@ class TestSha256Comparison:
|
||||
|
||||
|
||||
class TestSha256Report:
|
||||
"""Tests for the short-hash detail in the update report (SPEC 7.2.12.2)."""
|
||||
"""Tests for the short-hash detail in the update report (SPEC 7.1.2.12.2)."""
|
||||
|
||||
def test_update_line_shows_short_hashes(self):
|
||||
result = FileComparisonResult(
|
||||
|
||||
@@ -66,7 +66,7 @@ the docs contradict the code.
|
||||
- [x] Remove `src/llm-wiki/utils/scripts/example.py` — won't do:
|
||||
`wiki init` no longer skips `.py` files (it now makes a 1:1 copy of
|
||||
the template, so `example.py` ships to user wikis; user decision,
|
||||
2026-09-27; SPEC 7.1, version 0.30.0)
|
||||
2026-09-27; SPEC 7.1.1, version 0.30.0)
|
||||
- [x] Deduplicate conftest: `src/conftest.py` vs `src/tests/conftest.py`
|
||||
- [x] Consolidated into `src/tests/conftest.py` (sys.path bootstrap
|
||||
moved there, outer file removed, 2026-09-27); verified
|
||||
@@ -80,7 +80,7 @@ the docs contradict the code.
|
||||
- [x] markdownlint should show which files are in violation , what line
|
||||
- [x] same thing for ruff
|
||||
- [x] Remove the phantom `html_js_lint` package and `html-js-lint` console
|
||||
script from `pyproject.toml` until SPEC 7.17 is implemented. The
|
||||
script from `pyproject.toml` until SPEC 7.15 is implemented. The
|
||||
directory `src/html_js_lint/` does not exist. Detail is item 2 in
|
||||
the 2026-09-29 audit below
|
||||
|
||||
@@ -138,11 +138,11 @@ Half-moving a package leaves both layouts on `sys.path`.
|
||||
- [x] `src/fiona_assistant.egg-info/entry_points.txt` still has that
|
||||
script from the last editable install
|
||||
- [x] `src/html_js_lint/` does not exist. Invoking `html-js-lint`
|
||||
fails at import. SPEC 7.17 is the future feature; the entry
|
||||
fails at import. SPEC 7.15 is the future feature; the entry
|
||||
point should not ship until that directory exists
|
||||
- [x] `html5validator` is in runtime `dependencies` and is not
|
||||
imported anywhere under `src/`. Drop it with the phantom
|
||||
script, or keep it only when SPEC 7.17 lands
|
||||
script, or keep it only when SPEC 7.15 lands
|
||||
- [x] Delete `src/__init__.py`
|
||||
- [x] The file's only content is the comment `# Fiona tools package`
|
||||
- [x] An `__init__.py` in `src/` makes `src` itself a package whenever
|
||||
@@ -305,23 +305,23 @@ items below are done. The command defects after them are still open.
|
||||
- [x] `run_tests.py` and `run_sanity.py` already sit in
|
||||
`src/fiona/`. Give them entry points or document
|
||||
`python -m fiona.run_tests` / `python -m fiona.run_sanity`
|
||||
in place of `python src/run_tests.py` (SPEC 4.13).
|
||||
in place of `python src/run_tests.py` (SPEC 4.9).
|
||||
|
||||
### Fixes in commands the spec already calls Implemented
|
||||
|
||||
- [ ] `json-lint fix` walks the file list twice (SPEC appendix,
|
||||
SPEC 4.6). The second `fix_file` pass finds the files already
|
||||
SPEC 4.5). The second `fix_file` pass finds the files already
|
||||
clean, so the path lines never print. Walk once: one count and
|
||||
one path line per fixed file.
|
||||
- [ ] `json-lint chklint --fix` is parsed and ignored
|
||||
(`src/fiona/customlinter/jsonlint.py`). SPEC 4.6 says
|
||||
(`src/fiona/customlinter/jsonlint.py`). SPEC 4.5 says
|
||||
`chklint --fix` rewrites the same way `fix` does.
|
||||
- [ ] `json-lint fix` treats any path part named `personal` or `raw`
|
||||
as a read-only zone, including a folder outside the wiki.
|
||||
Skip with the wiki-relative check in `BaseLinter`
|
||||
(`src/fiona/customlinter/base.py`), the same rule as `chklint`.
|
||||
- [ ] `git` failures print `Error:` on stdout and catch `Exception`
|
||||
(`src/fiona/gittool/git_tool.py`). SPEC 4.7 and section 2: the
|
||||
(`src/fiona/gittool/git_tool.py`). SPEC 4.6 and section 2: the
|
||||
message goes to stderr. Catch the errors `GitTool` raises.
|
||||
This is the concrete case of the P2 logging item.
|
||||
- [ ] `wiki graph` prints `Error: Directory not found` on stdout
|
||||
@@ -332,13 +332,13 @@ items below are done. The command defects after them are still open.
|
||||
`--external-links` with `fiona.wiki.graph` settings after the
|
||||
CLI has set them (`load_graph_settings` in
|
||||
`wiki_graph_main`). An explicit flag wins. Settings fill the
|
||||
defaults only (SPEC 4.12).
|
||||
defaults only (SPEC 4.7.5).
|
||||
- [ ] `wiki graph` drops files above `max_files` with a log line
|
||||
only. Print the kept count and the limit on stderr.
|
||||
- [ ] `mdoctor fix` rewrites `personal/` and `raw/` (SPEC 4.3,
|
||||
- [ ] `mdoctor fix` rewrites `personal/` and `raw/` (SPEC 4.2,
|
||||
appendix). Constraint 1.2.3 says those zones are read-only for
|
||||
every automated tool. Skip them in `fix_file_programmatically`,
|
||||
then change SPEC 4.3 to say the command skips those zones.
|
||||
then change SPEC 4.2 to say the command skips those zones.
|
||||
- [ ] `graph_generator.py` logs with f-strings. Use lazy `%`
|
||||
formatting, the same style as `logging_config.py`.
|
||||
- [ ] `fiona-assistant python-ruff` has an empty help string and a
|
||||
@@ -350,10 +350,10 @@ items below are done. The command defects after them are still open.
|
||||
|
||||
## P1 — Wiki Lifecycle and Version Control
|
||||
|
||||
- [x] `wiki init` hardening (SPEC 7.1)
|
||||
- [x] `wiki init` hardening (SPEC 7.1.1)
|
||||
- [x] Warn or refuse when the target is already an llm-wiki directory
|
||||
- [x] Do not clobber user content on re-run (idempotent)
|
||||
- [x] `fiona-assistant wiki update` (SPEC 7.2)
|
||||
- [x] `fiona-assistant wiki update` (SPEC 7.1.2)
|
||||
- [x] Create `src/wiki/update_manager.py` with stub functions
|
||||
- [x] Add CLI commands: `wiki check-update` and `wiki update`
|
||||
- [x] Add comprehensive test suite (48 tests)
|
||||
@@ -361,10 +361,10 @@ items below are done. The command defects after them are still open.
|
||||
(compare `version` frontmatter)
|
||||
- [x] Update directory structure when the template changed
|
||||
- [x] Skip locally-modified files and report them
|
||||
- [x] `fiona-assistant wiki sanity` (SPEC 7.3)
|
||||
- [x] `fiona-assistant wiki sanity` (SPEC 7.1.3)
|
||||
- [x] Run all linters: mdlint, python-ruff, shellcheck (once P2 lands)
|
||||
- [x] Dead-link check (relative and wiki-internal links)
|
||||
- [x] Git version control for llm-wiki (SPEC 7.5)
|
||||
- [x] Git version control for llm-wiki (SPEC 7.12)
|
||||
- [x] GitPython library wrapper
|
||||
- [x] Basic operations:
|
||||
- [x] `save` — commit current edits with
|
||||
@@ -380,13 +380,13 @@ items below are done. The command defects after them are still open.
|
||||
|
||||
- [x] Restore the run_sanity progress heartbeat (`[WAITING]`
|
||||
lines while checks run) on top of the shared SanityRunner engine
|
||||
(SPEC 7.16.1); dropped when the engine was generalized
|
||||
(SPEC 7.14.1); dropped when the engine was generalized
|
||||
- [x] `SanityRunner.run_all` takes optional `progress` and
|
||||
`heartbeat` callbacks; check lifecycle logged at INFO
|
||||
- [x] run_sanity passes stdout callbacks (DONE markers and
|
||||
WAITING lines, assigned via a carriage-return constant); wiki
|
||||
sanity output unchanged
|
||||
- [x] Frontmatter linter (fmlint) (SPEC 7.8)
|
||||
- [x] Frontmatter linter (fmlint) (SPEC 7.5)
|
||||
- [x] Implement `src/customlinter/fmlint.py`
|
||||
- [x] Write TDD tests for fmlint
|
||||
- [x] Add CLI integration: `fiona-assistant fmlint chklint [directory]`
|
||||
@@ -405,8 +405,8 @@ items below are done. The command defects after them are still open.
|
||||
- [x] Migrate `python_ruff` (different compressed shape:
|
||||
`dict[rel_path, list[dict]]`) onto the shared base format
|
||||
- [x] Keep all linter reports diffable: same sections, same order
|
||||
(update SPEC 7.7/7.11 and tests together)
|
||||
- [x] JSON linter (json-lint) (SPEC 7.18)
|
||||
(update SPEC 7.4/7.8 and tests together)
|
||||
- [x] JSON linter (json-lint) (SPEC 7.11)
|
||||
- [x] Implement `src/customlinter/jsonlint.py`
|
||||
- [x] Write TDD tests for json-lint
|
||||
- [x] JSON syntax validation using the standard `json` module
|
||||
@@ -414,13 +414,13 @@ items below are done. The command defects after them are still open.
|
||||
- [x] CLI: `fiona-assistant json-lint chklint` and `fix`
|
||||
- [x] Settings via the `json` section of `fiona-settings.json`
|
||||
- [x] Integrated into `run_sanity.py` and `wiki sanity`
|
||||
- [ ] Shellcheck library (SPEC 7.12)
|
||||
- [ ] Shellcheck library (SPEC 7.9)
|
||||
- [ ] add shellcheck to toml
|
||||
- [ ] Wrap shellcheck like `python_ruff` (AI-friendly violation report)
|
||||
- [ ] Clear install-hint error when shellcheck is missing
|
||||
- [ ] Lint fenced code blocks inside MD files (SPEC 7.13)
|
||||
- [ ] Lint fenced code blocks inside MD files (SPEC 7.10)
|
||||
- [ ] Python blocks via Ruff, shell blocks via shellcheck
|
||||
- [ ] Logging library instead of `print` for diagnostics (SPEC 7.20)
|
||||
- [ ] Logging library instead of `print` for diagnostics (SPEC 7.17)
|
||||
- [x] Shared `fiona.logging_config.setup_logging()` on CLI entry points
|
||||
- [ ] Error and warning diagnostics go to stderr through logging.
|
||||
CLI reports stay stdout prints. `git_tool`, `graph_generator`,
|
||||
@@ -445,7 +445,7 @@ items below are done. The command defects after them are still open.
|
||||
`front-matter` extension (files with frontmatter no longer raise
|
||||
phantom MD003/MD022/MD041) and ignores the frontmatter `title`
|
||||
for MD025
|
||||
- [ ] Settings manager, `fiona-assistant setup` (SPEC 7.19)
|
||||
- [ ] Settings manager, `fiona-assistant setup` (SPEC 7.16)
|
||||
- [x] When running sanity, make sure that markdownlint tests also include
|
||||
outer dir of the src/ because there are markdown files there
|
||||
- [x] in `run_sanity.py`, show the failing test function and assert ex.
|
||||
@@ -598,7 +598,7 @@ WARNING run_tests: pytest short summary missing from output; failure details com
|
||||
omitted when the scan root is outside the working
|
||||
directory, because the matcher rejects those paths. The
|
||||
post-scan directory check still drops ignored files.
|
||||
SPEC 7.7.3
|
||||
SPEC 7.4.3
|
||||
- [x] Make the pristine and minimal wiki fixtures cheaper. Use a
|
||||
wiki that is not a git repo, or turn off
|
||||
`respect_gitignore` in the fixture's settings. The scan
|
||||
@@ -637,13 +637,13 @@ WARNING run_tests: pytest short summary missing from output; failure details com
|
||||
- [x] Side finding, not a speed issue: `run_tests.py` joins
|
||||
`PYTHONPATH` with `":"` (`f"{src_dir}:{current_pythonpath}"`).
|
||||
On Windows the separator is `;`. Use `os.pathsep`. Done.
|
||||
SPEC 4.13
|
||||
SPEC 4.9
|
||||
|
||||
- [x] in toc generator settings, per-file glob overrides in the `file`
|
||||
section (SPEC 7.15.2)
|
||||
section (SPEC 7.3.1.2)
|
||||
- [ ] instead of current directory as default, find a fiona-settings.json
|
||||
in the current directory / subdirectory, that will be the llm-wiki
|
||||
root and default directory for commands (SPEC 7.23)
|
||||
root and default directory for commands (SPEC 7.20)
|
||||
- [ ] Enable the pymarkdown `markdown-tables` extension in
|
||||
`fiona-settings.json` so table rules (MD055/MD056/MD058) run in
|
||||
`run_sanity.py` (SPEC 5.1 known limitation)
|
||||
@@ -655,13 +655,13 @@ WARNING run_tests: pytest short summary missing from output; failure details com
|
||||
## P3 — Metadata, Backup, and Documentation
|
||||
|
||||
- [ ] Backup script for llm-wiki so users can recover if something goes
|
||||
wrong (SPEC 7.6)
|
||||
wrong (SPEC 7.13)
|
||||
- [ ] Frontmatter tags on MD files (SPEC 6.2)
|
||||
- [x] `version`
|
||||
- [ ] `date` tag
|
||||
- [ ] Quality signal: `confidence`
|
||||
- [ ] `contested` flag (true if claims are disputed)
|
||||
- [ ] Project documentation (SPEC 7.21)
|
||||
- [ ] Project documentation (SPEC 7.18)
|
||||
- [x] Root `README.md` links `SPEC.md`
|
||||
- [x] Root README and `AGENTS.md` document `bootstrap` and `bootstrap.ps1`
|
||||
- [ ] Refresh `librarian/README.md` and `mdoctor/README.md` for the
|
||||
@@ -672,17 +672,17 @@ WARNING run_tests: pytest short summary missing from output; failure details com
|
||||
including the root README link to `./llm-wiki/AGENTS.md`
|
||||
- [ ] Process hygiene: use semantic commit prefixes
|
||||
(`feat:`, `fix:`, `docs:`, ...) per project agent rule 8.1
|
||||
- [x] `fiona-assistant wiki graph` (SPEC 7.4): link parser, graph,
|
||||
- [x] `fiona-assistant wiki graph` (SPEC 7.1.4): link parser, graph,
|
||||
HTML template, and CLI in `src/wiki/graph_generator.py`
|
||||
- [ ] Draw only important graph nodes until a parent is clicked
|
||||
(SPEC 7.4.16)
|
||||
(SPEC 7.1.4.16)
|
||||
- [ ] Setting `fiona.wiki.graph.node_importance_min_point`
|
||||
- [ ] `0`, or a missing key, draws every node
|
||||
- [ ] A positive integer hides a node whose `unique_points` is
|
||||
below that integer until one of its parents is clicked
|
||||
- [ ] Omit gitignored markdown from the wiki graph (SPEC 7.4.17)
|
||||
- [ ] Omit gitignored markdown from the wiki graph (SPEC 7.1.4.17)
|
||||
- [ ] Failing tests in `tests/test_graph_generator.py` for the
|
||||
acceptances in SPEC 7.4.17, 7.4.17.1, and 7.4.17.2:
|
||||
acceptances in SPEC 7.1.4.17, 7.1.4.17.1, and 7.1.4.17.2:
|
||||
`secret.md` absent from JSON nodes, edges, and orphans;
|
||||
a link to it creates no edge; `max_files` 1 still keeps
|
||||
`kept.md`; `drafts/` omits `drafts/note.md` and keeps
|
||||
@@ -693,7 +693,7 @@ WARNING run_tests: pytest short summary missing from output; failure details com
|
||||
drop a match before the `max_files` cut. Read patterns with
|
||||
`gitignore_patterns_from_text` and test them with
|
||||
`path_is_ignored` (`src/fiona/wiki/ignore.py`), the same
|
||||
rules as SPEC 7.2.10. The scan-root `.gitignore` applies to
|
||||
rules as SPEC 7.1.2.10. The scan-root `.gitignore` applies to
|
||||
the whole tree. A subdirectory `.gitignore` applies only
|
||||
under that subdirectory. Also drop any path under `.git/`
|
||||
- [ ] Do not parse an omitted file. Drop an edge whose target
|
||||
@@ -702,18 +702,18 @@ WARNING run_tests: pytest short summary missing from output; failure details com
|
||||
always runs
|
||||
- [ ] Housekeeping's orphan list follows automatically, because
|
||||
`graph_step` builds the graph through `wiki_graph_main`
|
||||
(SPEC 7.26.6)
|
||||
- [ ] in spec, refine the sectioning by compiling the modules,
|
||||
(SPEC 7.2.6)
|
||||
- [x] in spec, refine the sectioning by compiling the modules,
|
||||
and their functions as subsections
|
||||
- [ ] eg 4.1. librarian then 4.1.1 librarian toc, to make it cleaner
|
||||
- [x] eg 4.1. librarian then 4.1.1 librarian toc, to make it cleaner
|
||||
|
||||
## P4 — Design Decisions Needed
|
||||
|
||||
- [ ] Librarian: version tracking for non-MD files (SPEC 7.14)
|
||||
- [ ] Librarian: version tracking for non-MD files (SPEC 7.3.2)
|
||||
- [ ] Python files — format TBD
|
||||
- [ ] Bash scripts — format TBD
|
||||
- [ ] Decide the tagging format before implementing
|
||||
- [ ] Define LLM wiki tool roles (SPEC 7.22)
|
||||
- [ ] Define LLM wiki tool roles (SPEC 7.19)
|
||||
- [ ] Document purpose of `src/` tools
|
||||
- [ ] Classify tools by role:
|
||||
- [ ] Ingestion: moving files from `ingest/` to `raw/`
|
||||
@@ -722,8 +722,8 @@ WARNING run_tests: pytest short summary missing from output; failure details com
|
||||
|
||||
## Open Questions (SPEC)
|
||||
|
||||
- Tagging format for python files and bash scripts (SPEC 7.14)
|
||||
- Git wrapper location: implemented at `src/gittool/git_tool.py` (SPEC 7.5)
|
||||
- Wiki root discovery (SPEC 7.23): the nearest `fiona-settings.json`
|
||||
- Tagging format for python files and bash scripts (SPEC 7.3.2)
|
||||
- Git wrapper location: implemented at `src/gittool/git_tool.py` (SPEC 7.12)
|
||||
- Wiki root discovery (SPEC 7.20): the nearest `fiona-settings.json`
|
||||
wins; error when two at the same depth are equally near. Ancestor
|
||||
search is still open.
|
||||
|
||||
Reference in New Issue
Block a user