Polylith Migrate Analyze Imports

Skill: polylith-migrate-analyze-imports

Goal

Analyze the project's import graph to:

1. Find every reference to the original namespace (in all three forms — see below).
2. Choose the namespace-rewrite strategy: SHIM_STRATEGY=shim|shimless.
3. List symbols exported by the original namespace's __init__.py.
4. Detect potential circular imports.

This drives the namespace rewrite (phase 4) and, when SHIM_STRATEGY=shim, the shim sub-track (phase 4b). See the polylith-migrate-orchestrator table for phase numbers.

Inputs

• Project name (from migration/<project-name>/state.md)
• Original namespace ORIG_TOP_NS (from migration/<project-name>/state.md)

The three reference forms (cover all of them)

A namespace rewrite is incomplete unless it covers every form below. A naive "replace from <ns>. " misses forms 2 and 3:

1. Dotted import — from ${ORIG_TOP_NS}.<sub> import …, import ${ORIG_TOP_NS}.<sub>.
2. Bare submodule import — from ${ORIG_TOP_NS} import <sub> — single, multi-name (a, b, c), and mixed lines where only some names move. Easy to miss: there is no dot after the namespace.
3. Quoted string module paths — mock.patch("${ORIG_TOP_NS}.x.Y"), logging dict-config "${ORIG_TOP_NS}.logging.HealthFilter", importlib / getattr targets. Not import statements, but they must be rewritten too.

⚠ Do not rewrite unquoted local variables that merely share a name with the namespace (e.g. a FastAPI app = FastAPI() instance's app.include_router(...)). Target import statements and quoted module paths only.

Steps

1. Identify references to the original namespace

1. Search for all three forms above across all .py files in the project (and pyproject.toml / config files for string paths).
2. Record the paths and statements in migration/${PROJECT}/import_analysis.md, grouped as: internal (inside ${ORIG_TOP_NS}/), external consumers (entrypoints, alembic, scripts), and tests. The external + test groups are what the strategy decision below hinges on.

2. List symbols exported by the original namespace

1. Inspect ${ORIG_TOP_NS}/__init__.py (typically projects/${PROJECT}/src/${ORIG_TOP_NS}/__init__.py or projects/${PROJECT}/${ORIG_TOP_NS}/__init__.py) and list public symbols (not starting with _).
2. Record them, and note whether __init__.py is effectively empty (docstring only).

3. Decide the rewrite strategy (SHIM_STRATEGY)

Choose based on the findings and record it in state.md:

• shimless — when imports are predominantly submodule-qualified (from ${ORIG_TOP_NS}.<sub> import … / from ${ORIG_TOP_NS} import <sub>) and ${ORIG_TOP_NS}/__init__.py exports little or nothing. A single top-level re-export shim would resolve none of those submodule paths, and a full package shim mirroring every module is high-effort/high-risk. Phase 4 rewrites all references (internal + external + tests) directly to the new namespace, and the phase 4b sub-track is skipped.
• shim — when consumers import top-level symbols (from ${ORIG_TOP_NS} import X) that a single ${ORIG_TOP_NS}/__init__.py re-export can satisfy, and you want to defer rewriting external consumers. Run the phase 4b sub-track after phase 4.
• When in doubt, prefer shimless — it leaves no transitional shim to remove later (the definition-of-done forbids undocumented shims), at the cost of a wider but mechanical rewrite. Confirm with the user if the consumer surface is large.

Record:

SHIM_STRATEGY=<shim|shimless>

4. Detect potential circular imports

1. Inspect the import graph for cycles — especially base ↔ shim once a shim is in place (shim strategy only).
2. Record any chains in import_analysis.md. A pure namespace rename (shimless) preserves the original graph, so cycles there usually mean the project already had them.

Output

• migration/<project-name>/import_analysis.md with: references by form & group, exported symbols, the chosen strategy + rationale, and circular-import chains (if any).
• SHIM_STRATEGY set in migration/<project-name>/state.md.

Verify

1. migration/<project-name>/import_analysis.md exists and is not empty.
2. It records all three reference forms, the exported symbols, and any cycles.
3. SHIM_STRATEGY is set in state.md (shim or shimless) with a recorded rationale.

Commit

git add migration/${PROJECT}/import_analysis.md migration/${PROJECT}/state.md
git commit -m "migrate(${PROJECT}): phase <N> — analyze-imports"

<N> is this phase's number from the polylith-migrate-orchestrator table (the single source of truth) — do not hardcode it.