Skip to content

Add Python repository graph extractor #62

Description

@RomanEmreis

What problem does this solve?

The generic extractor exposes Python files, but Ferrus cannot navigate packages, modules, declarations, imports, or inheritance as structured graph facts.

Proposed solution

Add a deterministic Python extractor through the existing Extractor boundary.

Scope:

  • Support .py and .pyi files, package directories, and namespace-package layouts.
  • Emit modules, classes, functions, async functions, methods, properties, type aliases, and bounded declaration metadata with evidence spans.
  • Emit import, from ... import, relative import, re-export, and statically explicit inheritance relationships.
  • Resolve repository-local modules and packages conservatively across __init__.py, namespace packages, and supported source-root declarations.
  • Parse relevant static pyproject.toml package metadata without importing modules, running Python, loading plugins, or invoking build backends.
  • Preserve dynamic imports, wildcard ambiguity, runtime path mutation, and unsupported targets as unresolved evidence.

Acceptance criteria

  • Identical immutable input produces deterministic node, edge, semantic-key, and diagnostic output.
  • Incomplete or malformed source produces bounded diagnostics while preserving recoverable facts.
  • Parser time, file, fact, value, and diagnostic limits are enforced during extraction.
  • Source bodies, default values, secrets, and absolute local paths are not persisted.
  • Add/change/delete/rename and package-layout fixtures invalidate only the required fragments and resolution facts.
  • Tests cover regular and namespace packages, relative imports, stubs, async declarations, re-exports, inheritance, and unresolved dynamic imports.
  • User documentation lists supported syntax and known resolution limits.

Impact on workflow

None. This extends optional derived repository context and must not alter task, run, lease, review, or approval state.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions