Merge pull request #40 from gcomneno/feature/default-inbox-fallback

Default fallback_folder to documents/inbox

Author: gcomneno

README.md

@@ -64,7 +64,7 @@ Example output:
 
 ~~~text
 photo.jpg -> organized/images/photo.jpg
-notes.txt -> organized/documents/notes.txt
+notes.txt -> organized/documents/inbox/notes.txt
 script.py -> organized/code/script.py
 ~~~
 
@@ -215,7 +215,7 @@ Example JSON output:
   },
   {
     "source": "notes.txt",
-    "destination": "organized/documents/notes.txt",
+    "destination": "organized/documents/inbox/notes.txt",
     "category": "documents"
   }
 ]
@@ -256,7 +256,7 @@ Configured rules **extend** the built-in semantic rules; they do not replace the
 
 When a keyword from either built-in or configured rules matches the file path or inspected document text, the matching folder is used as the destination subfolder.
 
-Use `fallback_folder` to send unmatched documents to a dedicated inbox instead of the generic `documents/` folder:
+Use `fallback_folder` to send unmatched documents to a dedicated inbox. It defaults to `documents/inbox`:
 
 ~~~toml
 fallback_folder = "documents/inbox"

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "smart-file-organizer"
-version = "0.3.2"
+version = "0.3.3"
 description = "A safe Python CLI for planning and applying file organization workflows."
 readme = "README.md"
 authors = [

smart-file-organizer.example.toml

@@ -2,8 +2,8 @@
 #
 # Keep real/private rules outside Git. Use this file only as a public template.
 
-# Optional inbox for documents that do not match any semantic rule.
-# fallback_folder = "documents/inbox"
+# Inbox for documents that do not match any semantic rule.
+fallback_folder = "documents/inbox"
 
 [[semantic_rules]]
 folder = "documents/demo-utility"

src/smart_file_organizer/cli.py

@@ -7,7 +7,11 @@
 from pathlib import Path
 
 from smart_file_organizer.app_logging import configure_logging
-from smart_file_organizer.config import OrganizerConfig, load_config
+from smart_file_organizer.config import (
+    DEFAULT_FALLBACK_FOLDER,
+    OrganizerConfig,
+    load_config,
+)
 from smart_file_organizer.content_planning import (
     build_organization_plan_inspecting_content,
 )
@@ -218,7 +222,9 @@ def main(argv: Sequence[str] | None = None) -> None:
         parser.error(str(error))
 
     semantic_rules = semantic_rules_from_config(config)
-    fallback_folder = config.fallback_folder if config is not None else None
+    fallback_folder = (
+        config.fallback_folder if config is not None else DEFAULT_FALLBACK_FOLDER
+    )
 
     if args.inspect_content:
         plan = build_organization_plan_inspecting_content(

src/smart_file_organizer/config.py

@@ -10,6 +10,9 @@
 from smart_file_organizer.errors import ConfigError
 
 
+DEFAULT_FALLBACK_FOLDER = "documents/inbox"
+
+
 @dataclass(frozen=True)
 class SemanticRule:
     """A configurable semantic destination rule."""
@@ -24,7 +27,7 @@ class OrganizerConfig:
     """Application configuration loaded from a TOML file."""
 
     semantic_rules: tuple[SemanticRule, ...] = ()
-    fallback_folder: str | None = None
+    fallback_folder: str = DEFAULT_FALLBACK_FOLDER
 
 
 def load_config(path: Path) -> OrganizerConfig:
@@ -47,12 +50,9 @@ def parse_config(data: Mapping[str, Any]) -> OrganizerConfig:
     )
 
 
-def _parse_fallback_folder(data: Mapping[str, Any]) -> str | None:
-    """Parse optional fallback folder from raw TOML data."""
-    fallback_folder = data.get("fallback_folder")
-
-    if fallback_folder is None:
-        return None
+def _parse_fallback_folder(data: Mapping[str, Any]) -> str:
+    """Parse fallback folder from raw TOML data."""
+    fallback_folder = data.get("fallback_folder", DEFAULT_FALLBACK_FOLDER)
 
     if not isinstance(fallback_folder, str) or not fallback_folder.strip():
         raise ConfigError("fallback_folder must be a non-empty string")

src/smart_file_organizer/content_planning.py

@@ -3,6 +3,7 @@
 from collections.abc import Callable, Iterable
 from pathlib import Path
 
+from smart_file_organizer.config import DEFAULT_FALLBACK_FOLDER
 from smart_file_organizer.document_text import extract_document_text
 from smart_file_organizer.core import (
     PlannedMove,
@@ -19,7 +20,7 @@ def build_organization_plan_with_extracted_text(
     *,
     extract_text: DocumentTextExtractor,
     semantic_rules: Iterable[SemanticFolderRule] | None = None,
-    fallback_folder: str | None = None,
+    fallback_folder: str | None = DEFAULT_FALLBACK_FOLDER,
 ) -> list[PlannedMove]:
     """Build move plans using document text returned by an injected extractor."""
     source_list = list(sources)
@@ -39,7 +40,7 @@ def build_organization_plan_inspecting_content(
     target_root: Path,
     *,
     semantic_rules: Iterable[SemanticFolderRule] | None = None,
-    fallback_folder: str | None = None,
+    fallback_folder: str | None = DEFAULT_FALLBACK_FOLDER,
     verbose: bool = False,
 ) -> list[PlannedMove]:
     """Build move plans using the default document text extractor."""

src/smart_file_organizer/planning.py

@@ -10,6 +10,7 @@
     DestinationExistsError,
     SourceMissingError,
 )
+from smart_file_organizer.config import DEFAULT_FALLBACK_FOLDER
 from smart_file_organizer.models import PlannedMove, SemanticFolderRule
 from smart_file_organizer.semantic_rules import infer_destination_folder
 
@@ -19,7 +20,7 @@ def plan_file(
     target_root: Path,
     *,
     semantic_rules: Iterable[SemanticFolderRule] | None = None,
-    fallback_folder: str | None = None,
+    fallback_folder: str | None = DEFAULT_FALLBACK_FOLDER,
 ) -> PlannedMove:
     """Build a move plan for a single file without touching the filesystem."""
     return plan_file_with_document_text(
@@ -37,7 +38,7 @@ def plan_file_with_document_text(
     document_text: str,
     *,
     semantic_rules: Iterable[SemanticFolderRule] | None = None,
-    fallback_folder: str | None = None,
+    fallback_folder: str | None = DEFAULT_FALLBACK_FOLDER,
 ) -> PlannedMove:
     """Build a move plan using caller-provided document text."""
     category = classify_path(source)
@@ -64,7 +65,7 @@ def build_organization_plan(
     target_root: Path,
     *,
     semantic_rules: Iterable[SemanticFolderRule] | None = None,
-    fallback_folder: str | None = None,
+    fallback_folder: str | None = DEFAULT_FALLBACK_FOLDER,
 ) -> list[PlannedMove]:
     """Build move plans for multiple files without touching the filesystem."""
     return [
@@ -84,7 +85,7 @@ def build_organization_plan_with_document_texts(
     document_texts: Mapping[Path, str],
     *,
     semantic_rules: Iterable[SemanticFolderRule] | None = None,
-    fallback_folder: str | None = None,
+    fallback_folder: str | None = DEFAULT_FALLBACK_FOLDER,
 ) -> list[PlannedMove]:
     """Build move plans using caller-provided document text."""
     return [

src/smart_file_organizer/semantic_rules.py

@@ -7,6 +7,7 @@
 from typing import Literal
 
 from smart_file_organizer.classification import classify_path
+from smart_file_organizer.config import DEFAULT_FALLBACK_FOLDER
 from smart_file_organizer.models import (
     FileCategory,
     SemanticFolderRule,
@@ -334,10 +335,10 @@ def _match_semantic_folder(
 def _default_category_folder(
     category: FileCategory,
     *,
-    fallback_folder: str | None = None,
+    fallback_folder: str | None = DEFAULT_FALLBACK_FOLDER,
 ) -> Path:
     """Return the default folder when no semantic rule matches."""
-    if category == FileCategory.DOCUMENTS and fallback_folder:
+    if category == FileCategory.DOCUMENTS and fallback_folder is not None:
         return Path(fallback_folder)
 
     return Path(category.value)
@@ -348,7 +349,7 @@ def infer_destination_folder(
     *,
     document_text: str = "",
     semantic_rules: Iterable[SemanticFolderRule] | None = None,
-    fallback_folder: str | None = None,
+    fallback_folder: str | None = DEFAULT_FALLBACK_FOLDER,
 ) -> Path:
     """Infer a semantic destination folder for a path."""
     rules = _normalize_semantic_rules(semantic_rules)

tests/test_cli.py

@@ -101,7 +101,7 @@ def test_main_prints_organization_plan_from_explicit_sources(capsys) -> None:
 
     assert captured.out == (
         "photo.jpg -> organized/images/photo.jpg\n"
-        "notes.txt -> organized/documents/notes.txt\n"
+        "notes.txt -> organized/documents/inbox/notes.txt\n"
         "script.py -> organized/code/script.py\n"
     )
 
@@ -129,7 +129,7 @@ def test_main_prints_organization_plan_as_json(capsys) -> None:
         "  },\n"
         "  {\n"
         '    "source": "notes.txt",\n'
-        '    "destination": "organized/documents/notes.txt",\n'
+        '    "destination": "organized/documents/inbox/notes.txt",\n'
         '    "category": "documents"\n'
         "  }\n"
         "]\n"
@@ -188,7 +188,7 @@ def test_main_prints_organization_plan_from_directory(
     captured = capsys.readouterr()
 
     assert captured.out == (
-        f"{notes} -> organized/documents/notes.txt\n"
+        f"{notes} -> organized/documents/inbox/notes.txt\n"
         f"{photo} -> organized/images/photo.jpg\n"
     )
 
@@ -220,8 +220,8 @@ def test_main_recursive_scan_includes_nested_files(
     captured = capsys.readouterr()
 
     assert captured.out == (
-        f"{nested_file} -> organized/documents/ignored.txt\n"
-        f"{notes} -> organized/documents/notes.txt\n"
+        f"{nested_file} -> organized/documents/inbox/ignored.txt\n"
+        f"{notes} -> organized/documents/inbox/notes.txt\n"
         f"{photo} -> organized/images/photo.jpg\n"
     )
 
@@ -421,7 +421,7 @@ def test_main_applies_organization_plan(
     assert not photo.exists()
     assert not notes.exists()
     assert (target_root / "images" / "photo.jpg").read_text() == "fake image"
-    assert (target_root / "documents" / "notes.txt").read_text() == "hello"
+    assert (target_root / "documents" / "inbox" / "notes.txt").read_text() == "hello"
 
 
 def test_main_apply_reports_execution_errors(

tests/test_config.py

@@ -4,6 +4,7 @@
 
 from smart_file_organizer.errors import ConfigError
 from smart_file_organizer.config import (
+    DEFAULT_FALLBACK_FOLDER,
     OrganizerConfig,
     SemanticRule,
     load_config,
@@ -12,7 +13,7 @@
 
 
 def test_parse_config_returns_empty_config_for_empty_data() -> None:
-    assert parse_config({}) == OrganizerConfig()
+    assert parse_config({}) == OrganizerConfig(fallback_folder="documents/inbox")
 
 
 def test_parse_config_reads_semantic_rules() -> None:
@@ -122,6 +123,21 @@ def test_parse_config_reads_fallback_folder() -> None:
     )
 
 
+def test_parse_config_uses_default_fallback_folder_without_explicit_value() -> None:
+    config = parse_config(
+        {
+            "semantic_rules": [
+                {
+                    "folder": "documents/demo-utility",
+                    "keywords": ["demo utility"],
+                },
+            ],
+        }
+    )
+
+    assert config.fallback_folder == DEFAULT_FALLBACK_FOLDER
+
+
 def test_load_config_reads_fallback_folder_from_toml(tmp_path: Path) -> None:
     config_file = tmp_path / "smart-file-organizer.toml"
     config_file.write_text(