unskein 0.1.0__tar.gz

unskein-0.1.0/.env.example

@@ -0,0 +1,10 @@
+# Copy to .env and fill in. Never commit .env.
+# Precedence: env var > .unskein.toml / ~/.config/unskein/config.toml > --api-key flag.
+
+# LiteLLM model string, e.g. "ollama/qwen2.5-coder:7b" or "openai/gpt-4o-mini"
+UNSKEIN_AI_MODEL=
+UNSKEIN_API_KEY=
+UNSKEIN_AI_API_BASE=
+
+# "es" | "en" (default: system locale, falls back to English)
+UNSKEIN_LANG=

unskein-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,36 @@
+name: Bug report
+description: Something doesn't work as expected
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: Include the command you ran and the output. Remove any API keys.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What did you expect?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: A small project layout (files + imports) that triggers the problem.
+  - type: input
+    id: version
+    attributes:
+      label: unskein version
+      placeholder: unskein --version
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version and OS
+      placeholder: 3.14 on Ubuntu 24.04
+    validations:
+      required: true

unskein-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

unskein-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,19 @@
+name: Feature request
+description: Suggest an idea or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What are you trying to do that unskein doesn't support?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered

unskein-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,12 @@
+## Summary
+
+<!-- What does this change and why? Link the related issue. -->
+
+## Checklist
+
+- [ ] Tests added or updated
+- [ ] Clean Code rules followed; Google-style docstrings on every new or changed module, class and function (private ones included)
+- [ ] `uv run pytest` and `uv run ruff check .` pass locally
+- [ ] User-facing strings added to `unskein.i18n` in both `es` and `en`
+- [ ] `CHANGELOG.md` updated under `[Unreleased]`
+- [ ] No design decision from `docs/architecture.md` changed without prior discussion

unskein-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.12", "3.13", "3.14"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --locked
+      - run: uv run pytest --cov --cov-report=term-missing
+      - name: Smoke test - scan unskein itself end to end
+        run: uv run unskein scan src --no-ai --lang en

unskein-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,33 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI Trusted Publishing (OIDC), no stored token
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

unskein-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.ruff_cache/
+
+# Secrets and local config (never commit API keys)
+.env
+.env.*
+!.env.example
+.unskein.toml
+
+# Logs
+*.log
+
+# graft's local graph cache — regenerable, not committed (run `graft build`).
+graft/
+
+# Personal editor/agent tooling (graft hooks, MCP config) — per-developer, not shared
+.claude/
+.mcp.json
+.ignore
+
+docs/superpowers/
+docs/litellm/
+docs/code-reviews/
+.superpowers/

unskein-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

unskein-0.1.0/.unskein.toml.example

@@ -0,0 +1,19 @@
+# Copy to .unskein.toml (gitignored). Env vars take precedence over this file.
+
+[general]
+lang = "en"            # "es" | "en"
+
+[ai]
+model = "ollama/qwen2.5-coder:7b"
+api_base = "http://localhost:11434"
+# api_key = ""         # prefer UNSKEIN_API_KEY env var
+
+[analysis]
+parallel_threshold = 50
+# max_workers = 8      # default: os.cpu_count()
+queue_maxsize = 200
+max_file_size_bytes = 5242880
+per_file_timeout_seconds = 30
+# default_encoding = "utf-8"   # fallback only, never overrides a PEP 263 cookie
+# source_roots = ["src", "lib"]  # default: auto-detect src/ layout; project root is always a fallback
+# include_tests = false          # tests/, test_*.py, *_test.py, conftest.py are skipped by default

unskein-0.1.0/CHANGELOG.md

@@ -0,0 +1,111 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-30
+
+### Added
+
+- AI interpretation: with a model configured, the report gains a summary, an
+  architecture health rating and problems with severity, produced through LiteLLM (any
+  provider, local Ollama or a LiteLLM Proxy). The AI only sees module names and
+  metrics; its answer is checked against the dependency graph, so it cannot name a
+  module that does not exist. If the call or the answer fails, the report is still
+  produced with a notice saying why. `--min-severity` and exit code 2 now apply to it.
+  Loosely written module names (quoted, with a trailing dot, or as file paths) are
+  matched to the graph; problems that still name no real module are discarded, and the
+  console and the report say how many.
+- Initial project scaffold: `src/` layout, pipeline contracts, test fixtures, CI.
+- Python import parser: absolute, relative and submodule imports, `is_external`
+  detection, re-export detection in `__init__.py`, per-file warnings instead of crashes
+  (syntax errors, undecodable files, oversized files, deeply nested code).
+- Automatic `src/` layout detection and configurable `source_roots`.
+- Test code excluded from analysis by default; `--include-tests` to opt back in.
+- Re-export resolution: imports through `__init__.py` facades now point at the module
+  that defines the symbol, so cycles hidden behind a package facade become visible.
+  Re-export cycles produce a single warning per cycle.
+- Dependency graph and coupling metrics: afferent/efferent coupling and instability per
+  module, dependency cycles (capped at 100, deterministic order) and the most coupled
+  modules by nearest-rank percentile of `Ca + Ce`.
+- Configuration loading: `~/.config/unskein/config.toml` merged with the project's
+  `.unskein.toml` (project wins), validated so typos and wrong types are reported with
+  the file and field; env vars and CLI flags on top. API keys never appear in `repr`
+  or error messages.
+- `--no-include-tests` and `--no-follow-symlinks`, so a flag can override
+  `.unskein.toml` in both directions.
+- `unskein scan` works end to end: Markdown report in English or Spanish (terminal via
+  rich, raw file with `-o`), warnings grouped by kind with paths relative to the
+  project, `--verbose` stats and `--log-file`. The AI section explains why it is
+  empty (disabled, not configured, or the call failed).
+- Exit codes are enforced: usage errors now exit with 1 (click's default 2 collided with
+  "high-severity problems found"), unexpected errors exit with 3 showing the traceback.
+- Pylint configuration aligned with the Clean Code rules, for IDEs.
+- Tangles: groups of mutually dependent modules (strongly connected components),
+  exact and never truncated, shown before the cycle list with their size, so a
+  "100+ cycles" report reveals it is really one knot of, say, 279 modules (#8).
+
+- Parallel parsing: projects with 500 files or more are parsed in a process pool
+  (`parallel_threshold`, `max_workers`, `queue_maxsize` in `.unskein.toml`), up to
+  2.9x faster on large projects (1.0-2.6x where processes are spawned, as on Windows), with the same result and order as the sequential parser. A
+  file that exceeds `per_file_timeout_seconds` is skipped with a warning; a worker that
+  dies makes the parser fall back to sequential. The timeout only stops waiting: a
+  worker stuck on a pathological file still delays closing the pool.
+
+### Fixed
+
+- The list of dependency cycles (and which ones survived the 100-cycle limit) changed
+  between runs because networkx follows the string hash seed. Cycles are now enumerated
+  over integer labels, so the report is identical on every run.
+- The README example `--exclude "migrations/**"` only skipped a `migrations/` folder at
+  the project root, not the ones inside each app. It now reads `--exclude "migrations/"`,
+  which matches at any depth (a pattern with a slash in the middle is anchored to the
+  root, as in `.gitignore`).
+- `--verbose` now reports the real peak memory of the run. It used to read the resident
+  memory after the analysis, so memory freed before the end was invisible (a 200 MB
+  spike showed as 21 MB) (#9).
+- Printing the report to a Windows pipe (cp1252) no longer crashes with an internal
+  error on symbols such as "→"; unencodable characters are replaced.
+
+### Changed
+
+- The default `parallel_threshold` is now 500 files (was 50) and `max_workers` defaults to
+  the core count capped at 8. Measured, a pool at 50 files was 2-40x slower than
+  sequential parsing because starting it costs 130-300 ms.
+- `LanguageAdapter.parse` is now concrete, built on the new `plan_parse` and `parse_task`
+  that language adapters implement, so the parallel and sequential paths share one code
+  path. `FileParseResult` moved to `unskein.parsers.models`.
+- File discovery no longer enters excluded directories (`.venv/`, `build/`,
+  `node_modules/`, `tests/`…), so its cost no longer grows with ignored content. As in
+  git, a negated pattern (`!build/keep.py`) cannot re-include a file inside an excluded
+  directory: such a file is no longer analyzed.
+- Import collection walks only statement lists instead of every AST node, making parsing
+  1.3-1.5x faster on large projects (networkx, Django, sympy) with the same graph.
+  Imports are now visited depth-first in code order, so a file's warnings come out in
+  line order and the report may show different examples per warning kind.
+- When a package `__init__.py` re-exports the same symbol more than once (for example a
+  `try/except ImportError` fallback), the first one in the code now wins; before, the
+  last one did.
+- The placeholder notice about the AI arriving later is gone: the report now says
+  either that the AI is disabled or not configured, or why the call failed.
+- Precedence for non-secret options is now flag > env var > `.unskein.toml` (so
+  `--lang` beats `UNSKEIN_LANG`); secrets keep env var > `.unskein.toml` > `--api-key`.
+- Analysis warnings are now structured (`ParseWarning` with a `WarningCode`, file, line
+  and language-neutral detail) instead of English strings, so reports can translate
+  them and group them by kind.
+- Clean Code is now a mandatory project convention: Google-style docstrings on every
+  module, class and function (private ones included), enforced in CI with ruff's `D`
+  rules plus an AST-based test that also covers private names.
+- Parser data classes moved from `unskein.parsers.base` to `unskein.parsers.models`
+  (still importable from `unskein.parsers`), removing an import cycle.
+- LiteLLM is now required at `>=1.95.0,<2`. The AI client resolves how to call the
+  model once (reasoning models get `temperature=1.0`, JSON-schema output when the model
+  supports it, a 60 s limit for direct calls) and never lets LiteLLM download its price
+  map or send telemetry.
+
+[Unreleased]: https://github.com/mapenzo/unskein/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/mapenzo/unskein/releases/tag/v0.1.0