librarian move specifications
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user