Functions
list[str]	_scan_content_for_secrets (str content, str rel_path)
list[str]	_get_cached_secret_warnings (str abs_path, str content, str rel_path)
dict	load_exporter_config (Path root)
bool	should_skip_dirname (str dirname, dict cfg)
bool	_is_never_export_file (str filename)
List[Path]	collect_recursive_files (Path folder, dict cfg)
Tuple[int, int, int]	get_file_stats (Path path)
	walk_included_dirs (Path start, dict cfg)
None	clean_source_dirs (Path root, bool dry_run=False)
None	clean_pycache_dirs (Path root, bool dry_run=False)
Path	_make_safe_output_path (Path out_dir, str dotpath, dict cfg, str prefix="_source")
	write_source_file_for_dir (Path folder, Path output_path, Path root, dict cfg, bool warn_secrets=False, bool block_secrets=False, set[Path]\|None diff_filter=None)
None	run_exporter (Path root, list[str] args)

Variables
	_SECRET_ASSIGN_RE
dict	_secret_scan_cache = {}
set	_scanned_secret_paths = set()
dict	_EXTENSION_PROFILES
list	INCLUDE_EXTENSIONS = [ext for exts in _EXTENSION_PROFILES.values() for ext in exts]
tuple	HEADER_TEXT
str	SEPARATOR_FILE = "##### File name {num:02d}: {path}\n"
str	SEPARATOR_SUBDIR = "####### Subdirectory name {num:02d}: {dirname}\n"
str	ROOT_HEADER = "####### Root directory: .\n\n"
int	_MAX_SAFE_PATH_LEN = 240
str	_CONFIG_FILENAME = "_oct_exporter_config.json"

Detailed Description

Purpose
-------
Provide a unified, Option C‑compliant source‑exporting tool that collects,
combines, and consolidates all source‑code files in a project into structured
inspection files. This enables fast review, debugging, auditing, and
cross‑project comparison.

Responsibilities
----------------
- Walk a project directory tree while respecting exclusion rules.
- Collect all source files with supported extensions.
- Generate per‑directory `_source.<path>.txt` files.
- Generate a root‑level `_full_source.<root>.txt` file.
- Support `--clean` to remove all `_source_code-*` directories.
- Support `--verbose` to print per‑file statistics.
- Integrate cleanly with the OCT CLI as `oct export-source`.
- Handle I/O errors (including Windows MAX_PATH) gracefully: warn and continue.

Diagnostics
-----------
Domain: OCT-EXPORTER
Levels:
    L2 — lifecycle
    L3 — semantic details
    L4 — deep tracing

Contracts
---------
- Must not modify project files except inside `_source_code-*` directories.
- Must accept any directory as a valid export root.
- Must remain deterministic and safe for large projects.
- Must not require external dependencies beyond the standard library.
- Must never crash on a recoverable I/O error; warn and continue instead.

Function Documentation

◆ _get_cached_secret_warnings()

list[str] source_exporter._get_cached_secret_warnings	(	str	abs_path,
		str	content,
		str	rel_path )

protected

Return (cached or computed) secret warnings for ``abs_path``.

Definition at line 100 of file source_exporter.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _is_never_export_file()

bool source_exporter._is_never_export_file ( str filename )

protected

Check if a file matches NEVER_EXPORT_FILE_PATTERNS (§6b Secret Hygiene).

Definition at line 249 of file source_exporter.py.

Here is the caller graph for this function:

◆ _make_safe_output_path()

Path source_exporter._make_safe_output_path	(	Path	out_dir,
		str	dotpath,
		dict	cfg,
		str	prefix = "_source" )

protected

Build the output file path, truncating the dotpath if the full path would
exceed the Windows MAX_PATH limit (~260 chars). A short MD5 hash suffix is
appended when truncation is applied to ensure uniqueness.

Definition at line 336 of file source_exporter.py.

Here is the caller graph for this function:

◆ _scan_content_for_secrets()

list[str] source_exporter._scan_content_for_secrets	(	str	content,
		str	rel_path )

protected

Scan ``content`` for likely hardcoded secrets. Returns warning strings.

Uses the same name-heuristics as the linter (``_SECRET_NAME_PATTERNS``).
Empty list means no warnings. The ``rel_path`` is embedded in each
warning for user attribution.

Definition at line 66 of file source_exporter.py.

Here is the caller graph for this function:

◆ clean_pycache_dirs()

None source_exporter.clean_pycache_dirs	(	Path	root,
		bool	dry_run = False )

Remove all __pycache__ directories under root.

Definition at line 317 of file source_exporter.py.

◆ clean_source_dirs()

None source_exporter.clean_source_dirs	(	Path	root,
		bool	dry_run = False )

Definition at line 299 of file source_exporter.py.

Here is the caller graph for this function:

◆ collect_recursive_files()

List[Path] source_exporter.collect_recursive_files	(	Path	folder,
		dict	cfg )

Definition at line 258 of file source_exporter.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_file_stats()

Tuple[int, int, int] source_exporter.get_file_stats ( Path path )

Definition at line 274 of file source_exporter.py.

Here is the caller graph for this function:

◆ load_exporter_config()

dict source_exporter.load_exporter_config ( Path root )

Load optional per-project config, merging with module-level defaults.

Definition at line 151 of file source_exporter.py.

Here is the caller graph for this function:

◆ run_exporter()

None source_exporter.run_exporter	(	Path	root,
		list[str]	args )

Execute the source exporter with the given root directory and arguments.

Definition at line 431 of file source_exporter.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ should_skip_dirname()

bool source_exporter.should_skip_dirname	(	str	dirname,
		dict	cfg )

Definition at line 242 of file source_exporter.py.

Here is the caller graph for this function:

◆ walk_included_dirs()

source_exporter.walk_included_dirs	(	Path	start,
		dict	cfg )

Definition at line 289 of file source_exporter.py.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ write_source_file_for_dir()

source_exporter.write_source_file_for_dir	(	Path	folder,
		Path	output_path,
		Path	root,
		dict	cfg,
		bool	warn_secrets = False,
		bool	block_secrets = False,
		set[Path] \| None	diff_filter = None )

Definition at line 359 of file source_exporter.py.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

◆ _CONFIG_FILENAME

str source_exporter._CONFIG_FILENAME = "_oct_exporter_config.json"

protected

Definition at line 144 of file source_exporter.py.

◆ _EXTENSION_PROFILES

dict source_exporter._EXTENSION_PROFILES

protected

Initial value:

=  {
    "python": [".py"],
    "web": [".js", ".ts", ".tsx", ".css", ".html"],
    "jvm": [".java", ".kt"],
    "systems": [".rs", ".go", ".cpp", ".c", ".h", ".hpp"],
    "config": [".json", ".yaml", ".yml", ".toml", ".ini", ".xml"],
    "docs": [".md"],
    "scripts": [".sh", ".bat", ".ps1", ".ahk"],
    "misc": [".npmignore", ".gitignore", ".sql", ".rb", ".swift"],
}

Definition at line 111 of file source_exporter.py.

◆ _MAX_SAFE_PATH_LEN

int source_exporter._MAX_SAFE_PATH_LEN = 240

protected

Definition at line 142 of file source_exporter.py.

◆ _scanned_secret_paths

set source_exporter._scanned_secret_paths = set()

protected

Definition at line 97 of file source_exporter.py.

◆ _SECRET_ASSIGN_RE

source_exporter._SECRET_ASSIGN_RE

protected

Initial value:

=  re.compile(
    r'(?P<name>[A-Za-z_][A-Za-z0-9_]*)\s*[:=]\s*'
    r'(?:"(?P<dq>[^"\n]{4,})"|\'(?P<sq>[^\'\n]{4,})\')'
)

Definition at line 60 of file source_exporter.py.

◆ _secret_scan_cache

dict source_exporter._secret_scan_cache = {}

protected

Definition at line 95 of file source_exporter.py.

◆ HEADER_TEXT

tuple source_exporter.HEADER_TEXT

Initial value:

=  (
    "This file contains all source-code files in the directory {directory} "
    "(and its subdirectories) of this project.\n"
    "Sections are separated as follows:\n"
    "- '##### File name XX: <path>' marks individual files.\n"
    "- '####### Subdirectory name XX: <dirname>' marks combined subdirectory sources.\n"
    "- Root-level files use './<filename>' for clarity.\n\n"
)

Definition at line 128 of file source_exporter.py.

◆ INCLUDE_EXTENSIONS

list source_exporter.INCLUDE_EXTENSIONS = [ext for exts in _EXTENSION_PROFILES.values() for ext in exts]

Definition at line 122 of file source_exporter.py.

◆ ROOT_HEADER

str source_exporter.ROOT_HEADER = "####### Root directory: .\n\n"

Definition at line 139 of file source_exporter.py.

◆ SEPARATOR_FILE

str source_exporter.SEPARATOR_FILE = "##### File name {num:02d}: {path}\n"

Definition at line 137 of file source_exporter.py.

◆ SEPARATOR_SUBDIR

str source_exporter.SEPARATOR_SUBDIR = "####### Subdirectory name {num:02d}: {dirname}\n"

Definition at line 138 of file source_exporter.py.

Functions

Variables

Detailed Description

Function Documentation

◆ _get_cached_secret_warnings()

◆ _is_never_export_file()

◆ _make_safe_output_path()

◆ _scan_content_for_secrets()

◆ clean_pycache_dirs()

◆ clean_source_dirs()

◆ collect_recursive_files()

◆ get_file_stats()

◆ load_exporter_config()

◆ run_exporter()

◆ should_skip_dirname()

◆ walk_included_dirs()

◆ write_source_file_for_dir()

Variable Documentation

◆ _CONFIG_FILENAME

◆ _EXTENSION_PROFILES

◆ _MAX_SAFE_PATH_LEN

◆ _scanned_secret_paths

◆ _SECRET_ASSIGN_RE

◆ _secret_scan_cache

◆ HEADER_TEXT

◆ INCLUDE_EXTENSIONS

◆ ROOT_HEADER

◆ SEPARATOR_FILE

◆ SEPARATOR_SUBDIR