The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.
JavaScript
"""`layout.py` is the only module that knows the shape of a case folder.
The layout is about to move (the case tree gains a wrapper, several directories
become hidden), and that change is only cheap while every path has one origin.
The guard below is what keeps it that way: a module that joins a layout name
onto a path by hand fails this test, so the knowledge cannot leak back out one
drive-by at a time.
"""
from __future__ import annotations
import re
from pathlib import Path
import pytest
from azimut import layout
from azimut.api.naming import slugify
from azimut.engine import analyzers
from azimut.engine.media import safe_filename
from azimut.engine.thumbnails import THUMB_GEN
from azimut.layout import CASE_SUBDIRS, TRASH_DIR
from azimut.workspace import Case, CaseError
SOURCE = Path(__file__).resolve().parents[1] / "src" / "azimut"
#: Names that address something inside a case. Joining one of these onto a path
#: outside `layout.py` is what the guard refuses.
LAYOUT_NAMES = ("case.json", "case.db", "notes.md", TRASH_DIR, *CASE_SUBDIRS)
#: Matches path construction only — `staging / "case.db"`. An archive member or
#: a dict key spelled the same way is not a path and is left alone.
JOINS_LAYOUT_NAME = re.compile(
r"/\s*[\"'](?:" + "|".join(re.escape(name) for name in LAYOUT_NAMES) + r")[\"']"
)
def test_no_module_builds_a_case_path_by_hand() -> None:
offenders = []
for path in sorted(SOURCE.rglob("*.py")):
if path.name == "layout.py":
continue
for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
if JOINS_LAYOUT_NAME.search(line):
offenders.append(f"{path.relative_to(SOURCE)}:{number}: {line.strip()}")
assert not offenders, (
"these build a case path by hand instead of asking `layout`:\n " + "\n ".join(offenders)
)
#: The longest path each family of artifact can produce, as a function of the
#: caps. Every level of directory the case tree gains has to appear here, or the
#: budget stops describing reality.
#:
#: Fixed lengths, from the code that writes them: a thumbnail is
#: `<sha256[:24]>-g<gen>.jpg` (`thumbnails.py`), a pasted proof asset is 16 hex
#: plus its extension (`api/proofs.py` ASSET_NAME), a trash group id is
#: `_new_id("t")`.
THUMB_NAME = 24 + len(f"-g{THUMB_GEN}") + len(".jpg")
ASSET_NAME = 16 + len(".webp")
TRASH_GROUP_ID = len("t_0123456789")
TRASH_SLOT = 3 # "999" worth of artifacts in one delete
ANALYSIS_KEY = 32 # `analyzers._key`: a sha256 cut to 32 hex
def _branches() -> dict[str, int]:
"""Length of the deepest path in each family, from the case root down.
Includes the `azimut/` wrapper: every level the tree gains is spent out of
the same budget, which is the point of recomputing it here rather than
trusting a number written down once.
"""
slug, media = layout.MAX_SLUG, layout.MAX_MEDIA_NAME
wrapper = len(layout.TOOL_DIR) + 1
return {name: wrapper + length for name, length in _tool_relative(slug, media).items()}
def _tool_relative(slug: int, media: int) -> dict[str, int]:
"""Each branch spelled from the builders in `layout.py`, not from memory.
A worst-case name is fed through the real function, so a directory that gets
renamed or hidden moves this table by itself.
"""
longest_media = "m" * media
longest_name = "n" * slug
longest_folder = "f" * layout.MAX_FOLDER_PATH
return {
"media file": len(f"media/{longest_media}"),
"sidecar": len(layout.sidecar_rel(f"media/{longest_media}")),
"download scratch": len("media/.dl/") + layout.DOWNLOAD_ID_LENGTH + 1 + media,
"thumbnail": len("media/.thumbs/") + THUMB_NAME,
"entity photo": len(layout.entity_image_rel("i_0123456789")),
"entity photo thumbnail": len(layout.entity_image_thumb_rel("i_0123456789")),
"note": len(layout.note_rel(longest_folder, longest_name)),
"sheet table": len(layout.sheet_rel(longest_name)),
"sheet sidecar": len(layout.sheet_meta_rel(longest_name)),
"proof asset": len(layout.proof_assets_rel(longest_name)) + 1 + ASSET_NAME,
"proof spec": len(layout.proof_spec_rel(longest_name)),
"proof export": len(layout.proof_export_rel(longest_name)),
"draft": len(layout.draft_rel(longest_name)),
"inspect work": len(layout.session_rel(longest_name)),
"pre-0.3.1 session": len(layout.legacy_session_rel(longest_name)),
"collage": len(layout.collage_rel(longest_name)),
"collage preview": len(layout.collage_thumb_rel(longest_name)),
"compare session": len(layout.compare_session_rel(longest_name)),
"horizon view": len(layout.horizon_view_rel(longest_name)),
"horizon view preview": len(layout.horizon_thumb_rel(longest_name)),
"grid": len(layout.grid_rel(longest_name)),
"map layer spec": len(layout.layer_spec_rel(longest_name)),
"map layer snapshot": len(layout.layer_snapshot_rel(longest_name)),
"map layer icons": len(layout.layer_icons_rel(longest_name)),
"map layer cache": len(layout.layer_cache_rel(longest_name)),
# Detect names its records and frames by id and hash, never by title
"analysis item": max(len(layout.analysis_rel(kind, "a" * 12)) for kind in analyzers.KINDS),
"analysis frame": len(layout.analysis_asset_rel("a" * 12, "k" * ANALYSIS_KEY)),
"trash slot": len(f"{layout.TRASH_DIR}/") + TRASH_GROUP_ID + 1 + TRASH_SLOT,
}
def in_case_budget() -> int:
"""The longest path a case can hold, from its parent directory down."""
return layout.MAX_CASE_SLUG + 1 + max(_branches().values())
def in_scratch_budget() -> int:
"""The longest generated scratch path, from the workspace root down."""
scratch_id = len("scratch_") + 10
return len(".azimut/scratch/") + scratch_id + 1 + max(_branches().values())
def test_the_shipped_budget_matches_the_tree_it_describes() -> None:
"""`layout.IN_CASE_BUDGET` is what Settings refuses a too-long root with, so
a number that has drifted from the actual tree is worse than no number: it
would approve a root that breaks cases on Windows.
This is the only place the two can be compared, because the constant has to
be available without walking a case.
"""
assert layout.IN_CASE_BUDGET == in_case_budget(), (
f"layout.IN_CASE_BUDGET says {layout.IN_CASE_BUDGET}, the tree needs "
f"{in_case_budget()}. Update the constant, or shorten a branch:\n "
+ "\n ".join(f"{v:>4} {k}" for k, v in sorted(_branches().items(), key=lambda kv: -kv[1]))
)
assert layout.IN_SCRATCH_BUDGET == in_scratch_budget()
def test_the_path_budget_leaves_room_for_a_real_workspace_root() -> None:
"""The whole Windows story is this subtraction.
A case's longest path is a constant once every name is capped, so the only
question left is where the workspace lives. Keep enough room for a genuinely
deep root — a corporate OneDrive path runs to about 62 characters — and the
limit stops being something to discover at write time.
"""
room_for_the_root = layout.room_for_workspace_root()
assert room_for_the_root >= 70, (
f"the case tree needs {in_case_budget()} characters, leaving only "
f"{room_for_the_root} for the workspace root. Lower a cap in layout.py, "
f"or shorten a branch:\n "
+ "\n ".join(f"{v:>4} {k}" for k, v in sorted(_branches().items(), key=lambda kv: -kv[1]))
)
def test_the_root_that_fits_is_the_one_whose_deepest_case_path_fits() -> None:
"""The separator between the root and the case folder is counted once, in
`room_for_workspace_root()`. Off by one here is a case that writes fine
everywhere except the machine the budget exists for."""
exactly = "r" * layout.room_for_workspace_root()
assert layout.root_overflow(exactly) == 0
assert len(f"{exactly}/") + in_case_budget() <= layout.WINDOWS_MAX_PATH
assert layout.root_overflow(exactly + "r") == 1
def test_the_trash_is_no_longer_the_longest_branch() -> None:
"""It was, before it stopped mirroring the case tree, and by enough to break
Windows on its own. A change that puts it back on top is a regression."""
branches = _branches()
worst = max(branches, key=lambda name: branches[name])
assert worst != "trash slot"
assert branches["trash slot"] < branches["note"]
def test_a_generated_case_folder_name_is_always_an_adoptable_one() -> None:
"""The generator and the check are one rule asked two ways, so whatever
`case_folder_name` answers, `usable_case_name` has to accept. Drift here means
Azimut naming a folder its own adoption and recovery routes would refuse."""
for name in (
"Kharkiv Strike", "Маріуполь", "الموصل", "上海", "🛰 pass", "Sortie #4",
"100% sûr", "a/b\\c:d", "con", "NUL.txt", " spaced ", "trailing dot.",
"..", "", "x" * 300,
):
folder = layout.case_folder_name(name)
assert layout.usable_case_name(folder), f"{name!r} → {folder!r}"
def test_a_case_folder_keeps_a_name_no_ascii_slug_could_spell() -> None:
assert layout.case_folder_name("Маріуполь") == "Маріуполь"
assert layout.case_folder_name("上海") == "上海"
# Only what a filesystem or a URL refuses is replaced.
assert layout.case_folder_name("Sortie #4") == "Sortie _4"
assert layout.case_folder_name("Kyiv: 4 June") == "Kyiv_ 4 June"
# A name made of nothing else keeps its shape rather than being emptied.
assert layout.case_folder_name("###") == "___"
# And one a filesystem leaves with nothing at all still has to land somewhere.
assert layout.case_folder_name("...") == "case"
def test_every_capped_name_is_actually_capped() -> None:
"""The caps are only real if the functions that build names apply them."""
assert len(layout.case_folder_name("x" * 300)) <= layout.MAX_CASE_SLUG
assert len(slugify("x" * 300, "fallback")) <= layout.MAX_SLUG
assert len(safe_filename("x" * 300 + ".mp4")) <= layout.MAX_MEDIA_NAME
def test_a_folder_deeper_or_longer_than_the_budget_is_refused(tmp_workspace: str) -> None:
case = Case.create("Folder bounds")
case.add_folder("a/b/c/d") # at the depth limit, accepted
with pytest.raises(CaseError):
case.add_folder("a/b/c/d/e")
with pytest.raises(CaseError):
case.add_folder("x" * (layout.MAX_FOLDER_PATH + 1))
def test_layout_answers_are_all_under_the_root(tmp_path: Path) -> None:
root = tmp_path / "a-case"
answers = [
layout.manifest(root),
layout.database(root),
layout.entity_images(root),
layout.entity_image_thumbs(root),
layout.notes_file(root),
layout.media(root),
layout.notes(root),
layout.trash(root),
*layout.content_dirs(root),
]
for answer in answers:
assert answer.is_relative_to(root)
def test_content_dirs_covers_every_subdir_and_its_meta(tmp_path: Path) -> None:
root = tmp_path / "a-case"
born = layout.content_dirs(root)
assert [d.name for d in born[: len(CASE_SUBDIRS)]] == list(CASE_SUBDIRS)
# The `.meta/` directories are born too, and so is the one derived cache a
# tool keeps inside its own folder — an emptied case has to match a new one,
# and a directory created on first use would be one path apart.
assert set(born[len(CASE_SUBDIRS) :]) == {
layout.media(root) / layout.META_DIR,
layout.subdir(root, "proofs") / layout.META_DIR,
layout.subdir(root, "sheets") / layout.META_DIR,
layout.subdir(root, layout.LAYERS_DIR) / layout.LAYER_CACHE_DIR,
layout.subdir(root, layout.HORIZON_DIR) / layout.HORIZON_FINDS_DIR,
}
assert layout.trash(root).name not in CASE_SUBDIRS
def test_subdir_refuses_a_name_outside_the_layout(tmp_path: Path) -> None:
with pytest.raises(layout.LayoutError):
layout.subdir(tmp_path, "elsewhere")
def test_case_subdir_still_refuses_the_same_name(tmp_workspace: str) -> None:
"""`Case.subdir` speaks `CaseError` to its callers, whatever `layout` raises."""
case = Case.create("Layout")
with pytest.raises(CaseError):
case.subdir("elsewhere")
def test_layout_does_not_touch_the_filesystem(tmp_path: Path) -> None:
"""Answers are addresses, not creations — `Case` owns making directories."""
root = tmp_path / "never-created"
layout.media(root)
layout.manifest(root)
layout.content_dirs(root)
assert not root.exists()
def test_a_case_is_found_by_its_manifest(tmp_workspace: str) -> None:
case = Case.create("Found by manifest")
assert layout.is_case(case.path)
renamed = case.path.with_name("renamed-from-outside")
case.path.rename(renamed)
assert layout.is_case(renamed)
layout.manifest(renamed).unlink()
assert not layout.is_case(renamed)