I Built a Triage Tool Whose Only Promise Is That Every Item Lands on Exactly One Shelf

Описание и применение

Инструмент Shelf автоматически сортирует файлы в папке по проектам, гарантируя, что каждый элемент попадает ровно на одну полку с указанием причины и происхождения, и проверяет целостность распределения.

Задача

Managing a mixed folder of notes, screenshots, and links leads to items being misfiled or duplicated, making it hard to track what belongs to which project or who is waiting on you.

Результат

Shelf ensures every item is assigned to exactly one shelf with a documented reason and provenance, preventing silent drops or duplicate filings. The board shows a total count that matches the folder contents, and the build fails if the invariant is violated.

Рабочий процесс

• 1. Define a project list in a Markdown file (e.g., demo/projects.md).
• 2. Place items (files, images, sidecars) in a folder (e.g., demo/pile).
• 3. Run python shelf.py build --pile demo/pile --projects demo/projects.md.
• 4. Shelf extracts text via OCR or sidecar files, scores against project terms, and assigns each item to a shelf.
• 5. Shelf writes a board.md with shelves, items, reasons, and provenance.
• 6. Shelf runs a partition check that asserts every item lands on a valid shelf, has a reason, and the total count matches the number of items.
• 7. If any assertion fails, the build fails, alerting the user to the misfiled item.

Доказательства

shelf reads the folder, pulls text out of whatever it can, scores that text against a project list you wrote, and writes a board.

Источник

It runs on every build and the run fails if it does not hold.

Источник

Python 3.10+, standard library only. 51 tests, 124 cross-language verifier asserts, 29 in-page checks, 0 failures.

Источник