import-linter-ls 0.1.0__tar.gz

import_linter_ls-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 daniprol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

import_linter_ls-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: import-linter-ls
+Version: 0.1.0
+Summary: A language server for import-linter: see contract errors and import violations in your editor
+Keywords: import-linter,language-server,lsp,architecture
+Author: daniprol
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Dist: import-linter==2.16
+Requires-Dist: pygls>=2.0,<3
+Requires-Python: >=3.11
+Project-URL: Documentation, https://daniprol.github.io/import-linter-ls/
+Project-URL: Repository, https://github.com/daniprol/import-linter-ls
+Project-URL: Issues, https://github.com/daniprol/import-linter-ls/issues
+Description-Content-Type: text/markdown
+
+# import-linter-ls
+
+A language server for [import-linter](https://import-linter.readthedocs.io/), with a VS Code extension.
+See your architecture contract errors and import violations in the editor, not only in CI.
+
+> **Status: early.** The server starts and recognises import-linter config files. Diagnostics, hover and completion
+> are coming. See the [roadmap](docs/roadmap.md).
+
+## Use it in VS Code
+
+1. Install the server in your project:
+
+   ```bash
+   uv add --dev import-linter-ls     # or: pip install import-linter-ls
+   ```
+
+2. Install the **Import Linter** extension. Until it is on the Marketplace, download the `.vsix` from the
+   [latest release](https://github.com/daniprol/import-linter-ls/releases/latest) and run
+   **Extensions: Install from VSIX...**.
+3. Select your project's Python environment (**Python: Select Interpreter**) and open your project.
+
+It works with `.importlinter`, `setup.cfg` and `pyproject.toml` configs. Check **Output > Import Linter** for logs.
+
+| Setting | Purpose |
+|---|---|
+| `importLinterLs.interpreter` | Python that has `import-linter-ls`. Empty: use the one selected in VS Code. |
+| `importLinterLs.trace.server` | `off`, `messages` or `verbose`: log the editor/server messages. |
+
+Command: **Import Linter: Restart Language Server**.
+
+## Use it in another editor
+
+Any editor with an LSP client can run the server over stdio with `import-linter-ls`
+(or `python -m import_linter_ls`).
+
+## Develop
+
+```bash
+uv sync && pnpm install
+uv run prek install       # git hooks
+uv run pytest             # unit + integration tests
+```
+
+To try the extension, open this folder in VS Code and press `F5`, then open `examples/layered_app`.
+More in [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md).
+
+## Layout
+
+| Path | What |
+|---|---|
+| `src/import_linter_ls/` | The language server (Python, [pygls](https://pygls.readthedocs.io/)). |
+| `vscode-extension/` | The VS Code extension (TypeScript), a thin client. |
+| `examples/layered_app/` | Example app with one broken contract, in TOML and INI. |
+| `tests/` | Unit and integration tests. |
+| `docs/` | Documentation site ([zensical](https://zensical.org/)). |

import_linter_ls-0.1.0/README.md

@@ -0,0 +1,55 @@
+# import-linter-ls
+
+A language server for [import-linter](https://import-linter.readthedocs.io/), with a VS Code extension.
+See your architecture contract errors and import violations in the editor, not only in CI.
+
+> **Status: early.** The server starts and recognises import-linter config files. Diagnostics, hover and completion
+> are coming. See the [roadmap](docs/roadmap.md).
+
+## Use it in VS Code
+
+1. Install the server in your project:
+
+   ```bash
+   uv add --dev import-linter-ls     # or: pip install import-linter-ls
+   ```
+
+2. Install the **Import Linter** extension. Until it is on the Marketplace, download the `.vsix` from the
+   [latest release](https://github.com/daniprol/import-linter-ls/releases/latest) and run
+   **Extensions: Install from VSIX...**.
+3. Select your project's Python environment (**Python: Select Interpreter**) and open your project.
+
+It works with `.importlinter`, `setup.cfg` and `pyproject.toml` configs. Check **Output > Import Linter** for logs.
+
+| Setting | Purpose |
+|---|---|
+| `importLinterLs.interpreter` | Python that has `import-linter-ls`. Empty: use the one selected in VS Code. |
+| `importLinterLs.trace.server` | `off`, `messages` or `verbose`: log the editor/server messages. |
+
+Command: **Import Linter: Restart Language Server**.
+
+## Use it in another editor
+
+Any editor with an LSP client can run the server over stdio with `import-linter-ls`
+(or `python -m import_linter_ls`).
+
+## Develop
+
+```bash
+uv sync && pnpm install
+uv run prek install       # git hooks
+uv run pytest             # unit + integration tests
+```
+
+To try the extension, open this folder in VS Code and press `F5`, then open `examples/layered_app`.
+More in [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md).
+
+## Layout
+
+| Path | What |
+|---|---|
+| `src/import_linter_ls/` | The language server (Python, [pygls](https://pygls.readthedocs.io/)). |
+| `vscode-extension/` | The VS Code extension (TypeScript), a thin client. |
+| `examples/layered_app/` | Example app with one broken contract, in TOML and INI. |
+| `tests/` | Unit and integration tests. |
+| `docs/` | Documentation site ([zensical](https://zensical.org/)). |

import_linter_ls-0.1.0/pyproject.toml

@@ -0,0 +1,108 @@
+[project]
+name = "import-linter-ls"
+version = "0.1.0"
+description = "A language server for import-linter: see contract errors and import violations in your editor"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "import-linter",
+    "language-server",
+    "lsp",
+    "architecture",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Quality Assurance",
+    "Typing :: Typed",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "import-linter==2.16",
+    "pygls>=2.0,<3",
+]
+
+[[project.authors]]
+name = "daniprol"
+
+[project.scripts]
+import-linter-ls = "import_linter_ls.__main__:main"
+
+[project.urls]
+Documentation = "https://daniprol.github.io/import-linter-ls/"
+Repository = "https://github.com/daniprol/import-linter-ls"
+Issues = "https://github.com/daniprol/import-linter-ls/issues"
+
+[build-system]
+requires = ["uv_build>=0.9,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.workspace]
+members = ["examples/layered_app"]
+
+[tool.uv.sources.layered-app]
+workspace = true
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+src = [
+    "src",
+    "tests",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "N",
+    "UP",
+    "B",
+    "A",
+    "C4",
+    "SIM",
+    "RET",
+    "PIE",
+    "PTH",
+    "PT",
+    "ASYNC",
+    "RUF",
+]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.ty.rules]
+missing-type-argument = "error"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+addopts = [
+    "--strict-markers",
+    "--strict-config",
+]
+markers = [
+    "unit: fast tests of one function, no server",
+    "integration: starts the real language server and talks LSP to it",
+]
+
+[tool.coverage.run]
+source = ["import_linter_ls"]
+branch = true
+
+[dependency-groups]
+dev = [
+    "layered-app",
+    "prek>=0.2",
+    "pytest>=8",
+    "pytest-cov>=6",
+    "pytest-lsp>=1.0",
+    "ruff>=0.14",
+    "ty>=0.0.1",
+]
+docs = ["zensical>=0.0.20"]

import_linter_ls-0.1.0/pyproject.toml.orig

@@ -0,0 +1,97 @@
+[project]
+name = "import-linter-ls"
+version = "0.1.0"
+description = "A language server for import-linter: see contract errors and import violations in your editor"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "daniprol" }]
+keywords = ["import-linter", "language-server", "lsp", "architecture"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Quality Assurance",
+    "Typing :: Typed",
+]
+# Same minimum as import-linter itself.
+requires-python = ">=3.11"
+dependencies = [
+    "import-linter==2.16",
+    "pygls>=2.0,<3",
+]
+
+[project.scripts]
+import-linter-ls = "import_linter_ls.__main__:main"
+
+[project.urls]
+Documentation = "https://daniprol.github.io/import-linter-ls/"
+Repository = "https://github.com/daniprol/import-linter-ls"
+Issues = "https://github.com/daniprol/import-linter-ls/issues"
+
+[build-system]
+requires = ["uv_build>=0.9,<0.12"]
+build-backend = "uv_build"
+
+# The example app is a workspace member so `uv sync` installs it too.
+[tool.uv.workspace]
+members = ["examples/layered_app"]
+
+[dependency-groups]
+dev = [
+    "layered-app",
+    "prek>=0.2",
+    "pytest>=8",
+    "pytest-cov>=6",
+    "pytest-lsp>=1.0",
+    "ruff>=0.14",
+    "ty>=0.0.1",
+]
+docs = ["zensical>=0.0.20"]  # uv run --only-group docs zensical serve
+
+[tool.uv.sources]
+layered-app = { workspace = true }
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E", "W",  # pycodestyle
+    "F",       # pyflakes
+    "I",       # import sorting
+    "N",       # naming
+    "UP",      # modern syntax for Python 3.11+
+    "B",       # likely bugs
+    "A",       # shadowing builtins
+    "C4",      # comprehensions
+    "SIM",     # simplifications
+    "RET",     # return statements
+    "PIE",     # misc. clean-ups
+    "PTH",     # pathlib over os.path
+    "PT",      # pytest style
+    "ASYNC",   # asyncio pitfalls
+    "RUF",     # ruff-specific
+]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.ty.rules]
+missing-type-argument = "error"  # `list[str]`, not `list`: a bare generic hides mistakes
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+# `unit` tests are fast and need no server. `integration` tests start the real server and talk LSP to it.
+addopts = ["--strict-markers", "--strict-config"]
+markers = [
+    "unit: fast tests of one function, no server",
+    "integration: starts the real language server and talks LSP to it",
+]
+
+[tool.coverage.run]
+source = ["import_linter_ls"]
+branch = true

import_linter_ls-0.1.0/src/import_linter_ls/__init__.py

@@ -0,0 +1,5 @@
+"""A language server for import-linter."""
+
+from importlib.metadata import version
+
+__version__ = version("import-linter-ls")

import_linter_ls-0.1.0/src/import_linter_ls/__main__.py

@@ -0,0 +1,13 @@
+"""Entry point: `python -m import_linter_ls` or the `import-linter-ls` command."""
+
+from import_linter_ls.server import server
+
+
+def main() -> None:
+    # Editors start the server as a child process and talk to it over stdin and stdout,
+    # so never print to stdout: it would corrupt the protocol messages. Use `log` from server.py instead.
+    server.start_io()
+
+
+if __name__ == "__main__":
+    main()

import_linter_ls-0.1.0/src/import_linter_ls/config_files.py

@@ -0,0 +1,24 @@
+"""Finding out which files are import-linter config files."""
+
+from pathlib import Path
+
+# import-linter reads its config from these files (see its docs, "Usage").
+# `.importlinter` and `setup.cfg` use the INI format, `pyproject.toml` uses TOML.
+INI_CONFIG_FILE_NAMES = frozenset({".importlinter", "setup.cfg"})
+TOML_CONFIG_FILE_NAMES = frozenset({"pyproject.toml"})
+
+# Some projects pass their own file with `lint-imports --config my_file`. We cannot know those names,
+# so we only recognise the three default ones for now.
+
+
+def config_format(path: Path) -> str | None:
+    """Return "ini" or "toml" if `path` can hold import-linter config, otherwise None.
+
+    Only the file name is checked. A `pyproject.toml` or `setup.cfg` is only a *candidate*: it
+    holds import-linter config only if it has an `importlinter` section.
+    """
+    if path.name in INI_CONFIG_FILE_NAMES:
+        return "ini"
+    if path.name in TOML_CONFIG_FILE_NAMES:
+        return "toml"
+    return None

import_linter_ls-0.1.0/src/import_linter_ls/server.py

@@ -0,0 +1,90 @@
+"""The language server: connects pygls to our features.
+
+This file only wires things together. The actual logic lives in small modules next to it.
+"""
+
+import asyncio
+from pathlib import Path
+
+from lsprotocol import types
+from pygls.lsp.server import LanguageServer
+from pygls.uris import to_fs_path
+
+from import_linter_ls import __version__
+from import_linter_ls.violations import Violation, find_project_dir, parse_report, run_import_linter
+
+# A language server is a program that an editor starts and talks to with JSON messages (the Language
+# Server Protocol, LSP). The editor sends events ("the user opened this file") and we answer or
+# send back results ("these lines have problems"). pygls handles the JSON and the protocol for us.
+server = LanguageServer("import-linter-ls", __version__)
+
+
+def log(message: str) -> None:
+    """Send a message to the editor's log (VS Code shows it in the extension's output channel)."""
+    server.window_log_message(types.LogMessageParams(type=types.MessageType.Info, message=message))
+
+
+@server.feature(types.INITIALIZED)
+def on_initialized(_params: types.InitializedParams) -> None:
+    """The editor finished the handshake: from now on it may send us events."""
+    log(f"import-linter-ls {__version__} is ready")
+
+
+# Files that currently show our diagnostics. We must send an empty list for a file once it is fixed.
+files_with_diagnostics: set[str] = set()
+
+
+@server.feature(types.TEXT_DOCUMENT_DID_OPEN)
+async def on_document_opened(params: types.DidOpenTextDocumentParams) -> None:
+    """The user opened a file: check the project, so the editor shows problems right away."""
+    await check_project(params.text_document.uri)
+
+
+@server.feature(types.TEXT_DOCUMENT_DID_SAVE)
+async def on_document_saved(params: types.DidSaveTextDocumentParams) -> None:
+    """The user saved a file: check the project again."""
+    await check_project(params.text_document.uri)
+
+
+async def check_project(document_uri: str) -> None:
+    """Run import-linter for the project that owns the document and publish what it finds."""
+    file_path = to_fs_path(document_uri)
+    if file_path is None:  # not a file on disk, for example an unsaved "untitled:" document
+        return
+    project_dir = find_project_dir(Path(file_path))
+    if project_dir is None:  # no import-linter config nearby, nothing to check
+        return
+
+    log(f"Running import-linter in {project_dir}")
+    # import-linter takes a few seconds on big projects. Run it in a thread so the server can keep answering.
+    report = await asyncio.to_thread(run_import_linter, project_dir)
+    publish_diagnostics(parse_report(report, project_dir))
+
+
+def publish_diagnostics(violations: list[Violation]) -> None:
+    """Send the violations to the editor. A "diagnostic" is a problem on a range of a file (a squiggly line)."""
+    diagnostics_by_uri: dict[str, list[types.Diagnostic]] = {uri: [] for uri in files_with_diagnostics}
+    for violation in violations:
+        uri = violation.file.as_uri()
+        diagnostics_by_uri.setdefault(uri, []).append(to_diagnostic(violation))
+
+    for uri, diagnostics in diagnostics_by_uri.items():
+        server.text_document_publish_diagnostics(types.PublishDiagnosticsParams(uri=uri, diagnostics=diagnostics))
+    files_with_diagnostics.clear()
+    files_with_diagnostics.update(uri for uri, diagnostics in diagnostics_by_uri.items() if diagnostics)
+
+
+def to_diagnostic(violation: Violation) -> types.Diagnostic:
+    """Underline the whole line of the import."""
+    # LSP positions start at 0 for both line and character, while import-linter's line numbers start at 1.
+    line_index = violation.line - 1
+    line_text = violation.file.read_text(errors="replace").splitlines()[line_index]
+    return types.Diagnostic(
+        range=types.Range(
+            start=types.Position(line=line_index, character=0),
+            end=types.Position(line=line_index, character=len(line_text)),
+        ),
+        message=f"{violation.importer} imports {violation.imported}, which breaks an import-linter contract",
+        severity=types.DiagnosticSeverity.Error,
+        source="import-linter",
+    )

import_linter_ls-0.1.0/src/import_linter_ls/violations.py

@@ -0,0 +1,74 @@
+"""Run import-linter on a project and turn its report into a list of violations.
+
+This is a throwaway first version: it runs `lint-imports` and reads its text output. It will be
+replaced by a module that talks to import-linter directly (see docs/roadmap.md).
+"""
+
+import re
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from import_linter_ls.config_files import config_format
+
+
+@dataclass(frozen=True)
+class Violation:
+    """One import that breaks a contract. `line` starts at 1, like in an editor's status bar."""
+
+    file: Path
+    line: int
+    importer: str
+    imported: str
+
+
+def find_project_dir(file: Path) -> Path | None:
+    """Walk up from `file` to the first folder with an import-linter config file."""
+    for folder in file.parents:
+        for candidate in folder.iterdir():
+            if config_format(candidate) and "importlinter" in candidate.read_text(errors="replace"):
+                return folder
+    return None
+
+
+def run_import_linter(project_dir: Path) -> str:
+    """Run `lint-imports` in `project_dir` and return its report (the output is the same for pass and fail)."""
+    # Start the `lint-imports` command through Python so that it uses the same environment as the
+    # server, on every operating system. `--no-cache` makes sure that a saved file is analysed again.
+    code = "from importlinter.cli import lint_imports_command; lint_imports_command()"
+    result = subprocess.run(
+        [sys.executable, "-c", code, "--no-cache"],
+        cwd=project_dir,
+        capture_output=True,
+        text=True,
+        check=False,  # exit code 1 only means "there are broken contracts"
+    )
+    return result.stdout
+
+
+# A broken import is reported like this: `- layered_app.low.storage -> layered_app.high.report (l.4)`.
+# When one module imports the same thing twice there are several line numbers: `(l.4, l.9)`.
+VIOLATION_LINE = re.compile(r"(?P<importer>[\w.]+) -> (?P<imported>[\w.]+) \((?P<lines>l\.\d+(?:, l\.\d+)*)\)")
+
+
+def parse_report(report: str, project_dir: Path) -> list[Violation]:
+    """Find the broken imports in the text printed by `lint-imports`."""
+    violations = []
+    for match in VIOLATION_LINE.finditer(report):
+        file = module_to_file(match["importer"], project_dir)
+        if file is None:
+            continue
+        for line_number in re.findall(r"\d+", match["lines"]):
+            violations.append(Violation(file, int(line_number), match["importer"], match["imported"]))
+    return violations
+
+
+def module_to_file(module: str, project_dir: Path) -> Path | None:
+    """Find the source file of a module like `layered_app.low.storage`, in the project or in its `src` folder."""
+    relative = Path(*module.split("."))
+    for source_root in (project_dir, project_dir / "src"):
+        for candidate in (source_root / relative.with_suffix(".py"), source_root / relative / "__init__.py"):
+            if candidate.is_file():
+                return candidate
+    return None