librarian move specifications

This commit is contained in:
nvaldez
2026-10-02 12:14:57 +02:00
committed by nvaldez
parent 8a00ce97f5
commit 3c21217970
2 changed files with 3827 additions and 3535 deletions
+3685 -3535
View File
File diff suppressed because it is too large Load Diff
+142
View File
@@ -375,6 +375,148 @@ items below are done. The command defects after them are still open.
must be clean afterwards
- [x] `undo` — go back one commit; error if the working tree is dirty
and suggest `clean` first
- [ ] `fiona-assistant librarian move <source> <target>` (SPEC 4.1.2,
SPEC 7.3.3). Moves a file or folder and rewrites the relative
links inside each moved markdown file. Lifecycle is project
agent rule 2.1. The spec text is written. Start at step 2
- [ ] Step 0, shared link scanner with no behavior change.
`mdlinter.py` (`MARKDOWN_LINK`, `INLINE_CODE`, fence toggle,
`_is_ignorable_target`), `graph_generator.py`
(`MARKDOWN_LINK_PATTERN`), and `ingest/page_writer.py`
(`_FENCE`, `_LINK`, `_IMAGE`) each parse links their own way.
Do not merge them in this task. Write the new scanner so it
can replace them later, and leave a P2 item for that merge
- [ ] New module `src/fiona/librarian/link_rewriter.py`, pure
functions, no disk writes
- [ ] `LinkSpan` dataclass: `start`, `end` (offsets in the
line), `path`, `suffix` (`#fragment` or `?query`), `title`,
`angled` (bool), `kind` (`inline`, `image`, `reference`)
- [ ] `iter_links(line) -> Iterator[LinkSpan]`. Inline links,
images, and reference definitions (`^ {0,3}\[id\]:\s+path`).
Parse `<path with spaces>` and the three title forms
(`"t"`, `'t'`, `(t)`). Mask inline code before matching
(replace with spaces so offsets stay valid)
- [ ] `is_rewritable(path) -> bool`: false for empty, `#...`,
a URI scheme (`re.match(r"^[A-Za-z][A-Za-z0-9+.-]*:", p)`;
that also covers `C:` drive letters, which are absolute),
and a leading `/` or `\`. SPEC 7.3.3.4.1 and 7.3.3.4.2
- [ ] `new_link_path(old_path, old_dir, new_dir, moves) -> str |
None`. `urllib.parse.unquote`, resolve against `old_dir`,
return `None` when it does not exist (counted unresolved).
Map the resolved target through `moves`
(`dict[Path, Path]`, old absolute to new absolute, with a
folder entry covering its children). Then
`os.path.relpath(target, new_dir)` with `/`
- [ ] `format_path(new, old_path, angled)`: keep `./` when the
old path had it; outside `<...>` write a space as `%20`
and keep any `%xx` the old path used (quote only
characters that the old path quoted, plus spaces).
SPEC 7.3.3.3.2
- [ ] `rewrite_text(text, old_file, new_file, moves) ->
RewriteResult(text, rewritten, unresolved)`. Split with
`splitlines(keepends=True)` so CRLF stays. Skip the
frontmatter block (`---` first line through the next
`---`) and fenced blocks (```` ``` ```` or `~~~`, matched
to the opening fence length). Rebuild each line from the
spans right to left so offsets stay valid. A span whose
new text equals the old text is not counted
(SPEC 7.3.3.3.3)
- [ ] New module `src/fiona/librarian/mover.py`
- [ ] `MovePlan` dataclass: `source`, `final`, `files`
(list of `(old, new)` absolute paths), `rewrites`
(`dict[new_path, RewriteResult]` for markdown files),
`is_dir`
- [ ] `MoveError(Exception)` carrying the exact stderr text from
SPEC 7.3.3.2
- [ ] `resolve_final(source, target) -> Path`: an existing
folder target means `target / source.name`
(SPEC 7.3.3.1.2)
- [ ] `check(source, final, wiki_root)`: raise `MoveError` in
this order: source missing, final exists, final equals
source or `final.is_relative_to(source)` for a folder,
then read-only zone for source or final. Get the root with
`find_wiki_root(source.parent)` from `toc_generator.py`
(SPEC 7.3.1.2.6). Test the first part of the path relative
to that root against `READONLY_DIRS`. Do not copy
`_file_toc_single`, which matches any path part named
`personal` or `raw`, the same defect listed for
`json-lint fix` in the 2026-09-29 audit
- [ ] `plan(source, target, wiki_root) -> MovePlan`: call
`check`, list files (`rglob("*")` for a folder, hidden
included; SPEC 7.3.3.1.3), build `moves`, read each
markdown file as bytes, detect a UTF-8 BOM, decode, call
`rewrite_text`. Disk is read only
- [ ] `apply(plan)`: create `final.parent`, move with
`shutil.move(source, final)` (one call moves a folder),
then write each rewritten markdown file with
`write_bytes` (re-add the BOM, no newline translation).
Write only files whose `rewritten > 0`. Wrap `OSError`
into `MoveError(f"Error: {exc}")` (SPEC 7.3.3.7)
- [ ] `report_lines(plan, dry_run) -> list[str]`: the four line
shapes from SPEC 4.1.2, paths relative to the current
directory with `/`, `[dry-run]` prefix when asked. One
`moved` line for the source, then per-file `rewrote` and
`unresolved` lines in sorted new-path order, then the
summary line
- [ ] `move_main(source, target, dry_run) -> int`: plan, print,
apply unless dry run. `MoveError` goes to stderr, return 1.
No git call (SPEC 7.3.3.8)
- [ ] CLI in `src/fiona/__main__.py`: add a `move` subparser under
`librarian_subparsers` with `source`, `target`, and
`--dry-run`, help `Move a file or folder and fix its relative
links`. Dispatch straight to `move_main(...)` and
`sys.exit` its return value. Do not rewrite `sys.argv`
(open item in the 2026-09-29 audit). Also add `move` to
the standalone `librarian` script in `librarian.py`, or
record in SPEC 2 that it is reached only through
`fiona-assistant`
- [ ] Tests, `tests/test_link_rewriter.py` (pure, no disk except
`tmp_path` targets for existence)
- [ ] One test per link form: inline, image, reference
definition, `<angled path>`, each title form, `#fragment`,
`?query`, `./` prefix kept, `%20` kept, space quoted
- [ ] Unchanged cases from SPEC 7.3.3.4: `https://`,
`mailto:`, `#anchor`, `/abs`, `C:/abs`, `[[wikilink]]`,
fenced (backtick and tilde), inline code, `<a href>`,
`<https://autolink>`, frontmatter `sources:`
- [ ] A dead link is left as is and counted unresolved
- [ ] Two links on one line are both rewritten at the right
offsets
- [ ] CRLF input gives CRLF output
- [ ] Tests, `tests/test_librarian_move.py`, one per acceptance in
SPEC 7.3.3, on a `tmp_path` wiki with `fiona-settings.json`
- [ ] Move into an existing folder; move to a new path that
creates parents; folder move keeps layout and removes the
empty source (SPEC 7.3.3.1)
- [ ] Each refusal in SPEC 7.3.3.2: exact stderr line, exit 1,
tree hash before equals tree hash after (helper that
SHA-256s every file plus the folder list)
- [ ] The `wiki/a.md` -> `wiki/concepts/a.md` example and its
`rewrote 2 link(s)` line (SPEC 7.3.3.3)
- [ ] Folder move: sibling link unchanged, `../index.md`
becomes `../../index.md`
- [ ] Link from one moved file to another moved file (folder
move, and a link that leaves the folder and comes back)
- [ ] BOM, CRLF, and frontmatter `version` unchanged; a moved
PNG keeps its SHA-256 (SPEC 7.3.3.5)
- [ ] `wiki/index.md` that links the moved file is byte-identical
(SPEC 7.3.3.6)
- [ ] `--dry-run` stdout equals the real run's stdout with the
prefix, and the tree is unchanged (SPEC 7.3.3.7)
- [ ] `OSError` from `shutil.move` (patch it) gives stderr and 1
- [ ] Git wiki: commit count unchanged (SPEC 7.3.3.8)
- [ ] CLI test through `fiona.__main__.main` with `sys.argv`
patched, as `tests/test_fiona_main.py` does for `toc`
- [ ] Verify: remove each `NOT_IMPLEMENTED` in SPEC 4.1.2 and
7.3.3, set the 7.3.3 status to `Implemented`, update
Appendix B, drop "(planned)" from the Appendix D row, add
`move` to `src/fiona/librarian/README.md` (SPEC 7.18). Run
`python scripts/run_tests.py` and
`python scripts/run_sanity.py --non-interactive`, bump the
SPEC version
- [ ] Manual check on a copy of a real wiki: move a page into a
subfolder, then run `fiona-assistant wiki sanity` and
confirm no MDL001 comes from the moved page itself
## P2 — Quality Tooling