Option C Tools
Loading...
Searching...
No Matches
oct.deps.oct_deps Namespace Reference

Functions

str|None _extract_module_docstring (str source)
list[str] extract_dependencies (str source)
bool _should_skip (Path path, Path root)
str module_name_for (Path py_file, Path root)
dict[str, list[str]] build_dependency_graph (Path root)
list[list[str]] detect_cycles (dict[str, list[str]] graph)
str to_json (dict[str, list[str]] graph, list[list[str]] cycles)
str to_mermaid (dict[str, list[str]] graph)
str to_dot (dict[str, list[str]] graph)
int audit_pins (Path root, bool json_output=False)
dict _parse_toml_deps_fallback (Path toml_path)
int run_deps (Path root, list[str]|None argv=None)

Variables

 _DEP_SECTION_RE
 _DEP_LINE_RE = re.compile(r'^\s*[-*]\s+`?(\S+?)`?\s*(?:[-—:].*)?$', re.MULTILINE)

Detailed Description

Purpose
-------
Analyse inter-module dependencies within an Option C project by parsing
the ``Dependencies`` docstring section from all Python files.

Responsibilities
----------------
- Walk the project tree and extract ``Dependencies`` sections from module
  docstrings.
- Build a directed dependency graph (adjacency list).
- Detect circular dependencies via depth-first search.
- Output the graph in multiple formats: terminal summary, JSON, Mermaid,
  and DOT.

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

Contracts
---------
- Must not import project modules; analysis is purely static.
- Must exit 1 if circular dependencies are detected.
- Must handle missing or malformed Dependencies sections gracefully.

Function Documentation

◆ _extract_module_docstring()

str | None oct.deps.oct_deps._extract_module_docstring ( str source)
protected 
Extract the module-level docstring from Python source.

Definition at line 53 of file oct_deps.py.

Here is the caller graph for this function:

◆ _parse_toml_deps_fallback()

dict oct.deps.oct_deps._parse_toml_deps_fallback ( Path toml_path)
protected 
Minimal fallback TOML parser — extracts dependency lines only.

Definition at line 311 of file oct_deps.py.

Here is the caller graph for this function:

◆ _should_skip()

bool oct.deps.oct_deps._should_skip ( Path path,
Path root )
protected 
Check if a path should be excluded.

Definition at line 84 of file oct_deps.py.

Here is the caller graph for this function:

◆ audit_pins()

int oct.deps.oct_deps.audit_pins ( Path root,
bool json_output = False ) 
Audit pyproject.toml dependencies for unpinned version specifiers.

Reads ``[project.dependencies]`` and
``[project.optional-dependencies]`` from ``pyproject.toml``. Reports
dependencies that use open ranges (``>=``, ``>``) with no exact or
upper-bound constraint alongside those that are strictly pinned.

Parameters
----------
root
    Project root containing ``pyproject.toml``.
json_output
    If ``True``, prints a JSON summary. Otherwise prints a human-
    readable table.

Returns
-------
Exit code: ``0`` if all dependencies have upper-bound or exact pins,
``1`` if any open-ended ``>=``-only or ``>``-only specs are found,
``2`` if ``pyproject.toml`` could not be read.

Definition at line 207 of file oct_deps.py.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ build_dependency_graph()

dict[str, list[str]] oct.deps.oct_deps.build_dependency_graph ( Path root) 
Walk the project and build an adjacency list from Dependencies sections.

Keys are dotted import paths (OI-521), so modules sharing a stem
across packages no longer overwrite one another.

Definition at line 118 of file oct_deps.py.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ detect_cycles()

list[list[str]] oct.deps.oct_deps.detect_cycles ( dict[str, list[str]] graph) 
Detect circular dependencies using DFS. Returns list of cycle paths.

Definition at line 146 of file oct_deps.py.

Here is the caller graph for this function:

◆ extract_dependencies()

list[str] oct.deps.oct_deps.extract_dependencies ( str source) 
Parse the Dependencies section from a module docstring.

Returns a list of dependency module names.

Definition at line 67 of file oct_deps.py.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ module_name_for()

str oct.deps.oct_deps.module_name_for ( Path py_file,
Path root ) 
Compute a dotted import-path key for *py_file* relative to *root*.

OI-521: using ``py_file.stem`` collided whenever two packages contain
modules of the same name (e.g. ``a/util.py`` and ``b/util.py`` both
reduced to ``util``). Returning the dotted import path makes each key
unique and aligns with the dotted names typically used in
``Dependencies`` docstring sections.

``__init__.py`` resolves to its parent package's dotted name; a file
directly under *root* keeps its stem as the fallback.

Definition at line 96 of file oct_deps.py.

Here is the caller graph for this function:

◆ run_deps()

int oct.deps.oct_deps.run_deps ( Path root,
list[str] | None argv = None ) 
Run dependency analysis on the given project root.

Returns exit code: 0 if no cycles, 1 if circular dependencies found.

Definition at line 332 of file oct_deps.py.

Here is the call graph for this function:

◆ to_dot()

str oct.deps.oct_deps.to_dot ( dict[str, list[str]] graph) 
Format dependency graph as DOT (Graphviz) syntax.

Definition at line 194 of file oct_deps.py.

Here is the caller graph for this function:

◆ to_json()

str oct.deps.oct_deps.to_json ( dict[str, list[str]] graph,
list[list[str]] cycles ) 
Format dependency graph as JSON.

Definition at line 176 of file oct_deps.py.

Here is the caller graph for this function:

◆ to_mermaid()

str oct.deps.oct_deps.to_mermaid ( dict[str, list[str]] graph) 
Format dependency graph as Mermaid diagram syntax.

Definition at line 185 of file oct_deps.py.

Here is the caller graph for this function:

Variable Documentation

◆ _DEP_LINE_RE

oct.deps.oct_deps._DEP_LINE_RE = re.compile(r'^\s*[-*]\s+`?(\S+?)`?\s*(?:[-—:].*)?$', re.MULTILINE)
protected

Definition at line 50 of file oct_deps.py.

◆ _DEP_SECTION_RE

oct.deps.oct_deps._DEP_SECTION_RE
protected
Initial value:
1= re.compile(
2 r'Dependencies\s*\n\s*[-]+\s*\n(.*?)(?:\n\s*\n|\Z)',
3 re.DOTALL,
4)

Definition at line 46 of file oct_deps.py.