python-delphi-lsp 3.0.0__tar.gz → 3.1.1__tar.gz

{python_delphi_lsp-3.0.0 → python_delphi_lsp-3.1.1}/.github/workflows/ci.yml

@@ -9,6 +9,7 @@ jobs:
   test:
     name: ${{ matrix.os }} / Python ${{ matrix.python }}
     runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
     strategy:
       fail-fast: false
       matrix:
@@ -28,6 +29,7 @@ jobs:
   package:
     name: Build and validate distributions
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
@@ -38,6 +40,12 @@ jobs:
       - run: python -m pip install --upgrade pip build twine
       - run: python -m build
       - run: python -m twine check dist/*
+      - name: Run tests from unpacked sdist
+        run: |
+          mkdir sdist-smoke
+          tar -xzf dist/*.tar.gz -C sdist-smoke --strip-components=1
+          python -m pip install "./sdist-smoke[test]"
+          python -m pytest sdist-smoke/tests
       - run: python -m venv smoke-venv
       - run: smoke-venv/bin/python -m pip install dist/*.whl
-      - run: smoke-venv/bin/python -c "import delphi_lsp; print(delphi_lsp.__name__)"
+      - run: smoke-venv/bin/python -c "import delphi_lsp, pathlib; package = pathlib.Path(delphi_lsp.__file__).parent; assert (package / 'py.typed').is_file(); print(delphi_lsp.__name__)"

{python_delphi_lsp-3.0.0 → python_delphi_lsp-3.1.1}/MANIFEST.in

@@ -1,5 +1,6 @@
 include LICENSE
 include README.md
+include delphi_lsp/py.typed
 include opencode.json
 include .github/workflows/ci.yml
 include scripts/check_ornith_cache.py
@@ -21,4 +22,5 @@ include scripts/start_ornith_vllm.sh
 include scripts/summarize_opencode_request_payloads.py
 include scripts/ollama/ornith-lspctx.Modelfile
 include tests/corpora.performance.lock.json
+recursive-include docs *.md
 recursive-include tests *.py *.pas *.inc *.dpr *.dpk

{python_delphi_lsp-3.0.0/python_delphi_lsp.egg-info → python_delphi_lsp-3.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-delphi-lsp
-Version: 3.0.0
+Version: 3.1.1
 Summary: Python Delphi/Object Pascal parser, semantic indexer, and language server.
 Author: Dark Light
 License-Expression: MPL-2.0
@@ -24,25 +24,28 @@ License-File: LICENSE
 Requires-Dist: lark>=1.1.9
 Requires-Dist: pygls<2.0,>=1.3.0
 Requires-Dist: lsprotocol>=2023.0.1
+Requires-Dist: tomli>=2.0.1; python_version < "3.11"
 Requires-Dist: watchfiles<2.0,>=1.2
 Provides-Extra: lsp
 Requires-Dist: pygls<2.0,>=1.3.0; extra == "lsp"
 Requires-Dist: lsprotocol>=2023.0.1; extra == "lsp"
 Provides-Extra: test
 Requires-Dist: pytest>=8.0.0; extra == "test"
+Requires-Dist: pytest-timeout>=2.3.0; extra == "test"
 Provides-Extra: dev
 Requires-Dist: build>=1.2.0; extra == "dev"
 Requires-Dist: twine>=5.0.0; extra == "dev"
 Requires-Dist: pygls<2.0,>=1.3.0; extra == "dev"
 Requires-Dist: lsprotocol>=2023.0.1; extra == "dev"
 Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3.0; extra == "dev"
 Dynamic: license-file
 
 # Python Delphi LSP
 
 `python-delphi-lsp` parses Delphi/Object Pascal, builds semantic and project
 indexes, serves LSP, and provides bounded codebase navigation for agents.
-Version 3.0.0 is authored by Dark Light and supports Windows, macOS, and Linux.
+Version 3.1.1 is authored by Dark Light and supports Windows, macOS, and Linux.
 
 ## Install and quick start
 
@@ -190,15 +193,19 @@ not guessed.
 
 ```text
 delphi-lsp-agent cache start --root PATH [--project-file FILE] [--max-memory 512M]
+                                  [--max-disk-cache 512M]
                                   [--workers auto|N] [--startup-timeout 120]
                                   [--idle-timeout 1800]
 delphi-lsp-agent cache status --root PATH [--format text|json]
 delphi-lsp-agent cache stop --root PATH
+delphi-lsp-agent cache clear --root PATH
 delphi-lsp-agent view --root PATH [--project-file FILE] --layer LAYER
                       [--query TEXT] [--format markdown|json] [--deep-projects]
                       [--workers auto|N]
 delphi-lsp-agent index --root PATH [--project-file FILE] [--out FILE]
                        [--workers auto|N]
+delphi-lsp-agent wiki export --root PATH [--project-file FILE] [--out DIRECTORY]
+                             [--workers auto|N] [--force] [--quiet]
 delphi-lsp-agent query --root PATH ACTION [VALUE]
                       [--project-id ID] [--detail summary|declaration|members|context|body|implementations]
                       [--relation references|callers|callees|uses|used_by|inherits|implements]
@@ -217,12 +224,67 @@ The `cache` commands manage one daemon per canonical root. Use these:
 delphi-lsp-agent cache start --root PATH
 delphi-lsp-agent cache status --root PATH
 delphi-lsp-agent cache stop --root PATH
+delphi-lsp-agent cache clear --root PATH
 ```
 
 `cache start` outputs cache lifecycle JSON; runtime warnings are still on stderr.
 `cache status --format json` outputs status JSON to stdout and the same warning stream on stderr.
 `cache stop` outputs stop status JSON and may include warnings on stderr.
+`cache clear` stops the daemon and removes persistent navigation shards.
 `query` outputs Protocol v3 JSON responses and writes warnings to stderr.
+For `index`, a relative `--out` is resolved below `--root`; the default is
+`.delphi-lsp/agent-index/index.json`.
+
+### Open Knowledge Format wiki export
+
+Export the complete unique knowledge represented by the layered codebase views
+as a portable Markdown wiki:
+
+```bash
+delphi-lsp-agent wiki export --root PATH --out codebase-wiki
+```
+
+When `--out` is relative, it is resolved below `--root`; the default is
+`.delphi-lsp/wiki`. The command builds the semantic index once, deep-indexes
+main projects, calculates workspace and unit metrics, and writes:
+
+- an OKF 0.2 root `index.md`;
+- linked project, unit, and symbol concepts;
+- declaration and implementation source fragments;
+- resolved and unresolved semantic references;
+- discovery/project problems and complete metric records;
+- Protocol v3, relation, CPG, cache, and layer-mapping reference concepts.
+
+Without `--project-file`, the exporter selects repository main projects:
+non-example project entries in the repository root, or, when none exist, the
+shallowest configured `.dproj` entries. Recursively discovered example,
+sample, test, benchmark, and vendor projects are not promoted to project
+pages. A repository `.delphi-lsp.toml` can replace this heuristic with the
+explicit monorepo selection described below. With `--project-file`, only that
+explicit entry is selected. Project
+dependency traversal and include loading are confined to the repository root,
+so Delphi SDK and other external standard units are recorded as unresolved
+dependencies instead of being parsed. If no main project can be identified,
+the exporter falls back to the repository source inventory without inventing
+project pages.
+
+Every non-index concept is UTF-8 Markdown with YAML frontmatter and a non-empty
+`type`. Readable filenames include a stable digest, so overloads and equal names
+from different units remain distinct even on case-insensitive filesystems.
+Output order and content are deterministic. The finished bundle replaces the
+destination only after generation succeeds; an existing non-empty destination
+requires `--force`, and unsafe root/ancestor/symlink targets are rejected.
+
+Pages are streamed to disk, decoded source retention is bounded, and metrics
+process source paths without materializing the entire source corpus. Lazy CPG
+subgraphs are documented rather than eagerly multiplied across all possible
+targets; a focused live `cpg` query remains the bounded way to obtain one graph.
+The bundle structure follows the
+[Open Knowledge Format 0.2 specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md).
+
+Progress is shown on `stderr` while the final machine-readable JSON summary
+remains the only record on `stdout`. Redirected progress is throttled to
+milestones; pass `--quiet` to suppress it completely.
 
 ```bash
 delphi-lsp-agent query --root PATH find TCustomer
@@ -232,9 +294,14 @@ delphi-lsp-agent query --root PATH trace TARGET_ID --relation callers
 delphi-lsp-agent query --root PATH cpg TARGET_ID --graph full --direction out --depth 4
 delphi-lsp-agent query --root PATH metrics
 delphi-lsp-agent query --root PATH metrics UNIT_QUERY
+delphi-lsp-agent query --root PATH metrics --target-id UNIT_TARGET_ID
 delphi-lsp-agent cache status --root PATH --format json
 ```
 
+A `target_v2_...` positional value for `metrics` is also recognized as a unit
+target ID; other positional values remain case-insensitive unit-name or path
+queries.
+
 The repository root is sufficient even when it contains many projects:
 
 ```bash
@@ -243,7 +310,9 @@ delphi-lsp-agent query --root PATH find TCustomer
 ```
 
 This prewarms one bounded repository navigation index and requires no project
-selection. A `.dproj` is optional. Pass one when its project-specific compiler
+selection. A `.dproj` is optional. For repeatable monorepo selection, add a
+`.delphi-lsp.toml` file as described below. Pass one project explicitly when
+its project-specific compiler
 settings and `MainSource` should define the index:
 
 ```bash
@@ -261,6 +330,61 @@ delphi-lsp-agent query --root PATH focus --project-id PROJECT_ID
 
 Selecting a project this way also prewarms its navigation cache.
 
+### TOML project selection for monorepos
+
+Place `.delphi-lsp.toml` in the repository root to define which `.dpr`,
+`.dpk`, or companion `.dproj` projects belong to the codebase:
+
+```toml
+[projects]
+include = [
+  "apps/**",
+  "services/Api/ApiServer.dproj",
+  "packages/*/Runtime.dpk",
+]
+exclude = [
+  "**/examples/**",
+  "**/tests/**",
+]
+
+[workspace]
+exclude = [
+  "vendor",
+  "generated/**",
+  "thirdparty/legacy",
+]
+```
+
+Paths are relative to the repository root, case-insensitive, and use `/` on
+every operating system. An exact directory name covers all descendants. `*`
+matches within one path segment, while `**` crosses directory boundaries.
+Absolute paths and `..` traversal are rejected.
+
+When `include` is non-empty, only matching project entries remain. Matching a
+`.dproj` selects the `.dpr` or `.dpk` from its `MainSource`. The `exclude`
+list is applied afterward, so `exclude` always wins. With active TOML filters,
+all remaining matches are main projects even when they occur at different
+directory depths; the built-in shallow-project and example-name heuristic is
+not applied.
+
+Use `projects.exclude` when a directory may still contain shared units but its
+project entries must not become selectable projects. Use `workspace.exclude`
+for a hard boundary. Matching directories are never traversed or parsed, and
+neither is any file below them. They cannot be reintroduced by
+`projects.include` or an explicit `--project-file`. Unit dependencies and
+include directives resolving into those directories are reported as
+unavailable without reading the files.
+For complete directory pruning, an exact entry such as `"vendor"` is enough;
+`"generated/**"` also excludes the `generated` directory itself.
+
+The same selection is used by `cache`, `worker`, `query`, `view`, `index`,
+wiki export, and language-server discovery. An explicit `--project-file`
+bypasses `projects.include` and `projects.exclude` for that invocation, but
+never bypasses `workspace.exclude`. If no project remains, the command reports
+that the configured filters matched no Delphi projects and stops instead of
+silently parsing every source file in the repository. Restart an already
+running cache daemon after changing the path configuration.
+
 `inspect` uses the currently focused target, so call `focus TARGET_ID` before
 `inspect` unless a previous request already selected it.
 
@@ -294,7 +418,9 @@ under `.delphi-lsp/agent-cache/navigation-v1`. A restarted CLI or OpenCode cache
 daemon reuses unchanged units without parsing them again. Source content,
 conditional defines, or a shard-schema change produces a cache miss; malformed
 or incompatible JSON is ignored and rebuilt. The disk cache contains no pickle
-payloads and does not count against the retained-RAM budget.
+payloads and does not count against the retained-RAM budget. Each completed
+navigation build removes superseded shards and enforces the
+`--max-disk-cache` byte budget, which defaults to 512 MiB.
 
 Cache prewarming builds the navigation registry directly without constructing
 an empty-query result, symbol cards, pagination, or JSON payloads. Up to sixteen
@@ -330,7 +456,8 @@ outside the root workspace.
 `metrics`. For example, `delphi-lsp-agent view --layer metrics --format json`
 returns a project summary and detailed unit metric objects; `--query` filters
 units by name or path.
-`index` materializes overview, projects, and problems JSON. `skill install`
+`index` materializes overview, projects, and problems JSON. `wiki export`
+materializes the same navigational knowledge as a linked OKF Markdown bundle. `skill install`
 writes the skill; `opencode install` writes the package-named skill, Markdown
 agent, and plugin. The two deprecated write flags are harmless aliases and do
 not change user configuration.

{python_delphi_lsp-3.0.0 → python_delphi_lsp-3.1.1}/README.md

@@ -2,7 +2,7 @@
 
 `python-delphi-lsp` parses Delphi/Object Pascal, builds semantic and project
 indexes, serves LSP, and provides bounded codebase navigation for agents.
-Version 3.0.0 is authored by Dark Light and supports Windows, macOS, and Linux.
+Version 3.1.1 is authored by Dark Light and supports Windows, macOS, and Linux.
 
 ## Install and quick start
 
@@ -150,15 +150,19 @@ not guessed.
 
 ```text
 delphi-lsp-agent cache start --root PATH [--project-file FILE] [--max-memory 512M]
+                                  [--max-disk-cache 512M]
                                   [--workers auto|N] [--startup-timeout 120]
                                   [--idle-timeout 1800]
 delphi-lsp-agent cache status --root PATH [--format text|json]
 delphi-lsp-agent cache stop --root PATH
+delphi-lsp-agent cache clear --root PATH
 delphi-lsp-agent view --root PATH [--project-file FILE] --layer LAYER
                       [--query TEXT] [--format markdown|json] [--deep-projects]
                       [--workers auto|N]
 delphi-lsp-agent index --root PATH [--project-file FILE] [--out FILE]
                        [--workers auto|N]
+delphi-lsp-agent wiki export --root PATH [--project-file FILE] [--out DIRECTORY]
+                             [--workers auto|N] [--force] [--quiet]
 delphi-lsp-agent query --root PATH ACTION [VALUE]
                       [--project-id ID] [--detail summary|declaration|members|context|body|implementations]
                       [--relation references|callers|callees|uses|used_by|inherits|implements]
@@ -177,12 +181,67 @@ The `cache` commands manage one daemon per canonical root. Use these:
 delphi-lsp-agent cache start --root PATH
 delphi-lsp-agent cache status --root PATH
 delphi-lsp-agent cache stop --root PATH
+delphi-lsp-agent cache clear --root PATH
 ```
 
 `cache start` outputs cache lifecycle JSON; runtime warnings are still on stderr.
 `cache status --format json` outputs status JSON to stdout and the same warning stream on stderr.
 `cache stop` outputs stop status JSON and may include warnings on stderr.
+`cache clear` stops the daemon and removes persistent navigation shards.
 `query` outputs Protocol v3 JSON responses and writes warnings to stderr.
+For `index`, a relative `--out` is resolved below `--root`; the default is
+`.delphi-lsp/agent-index/index.json`.
+
+### Open Knowledge Format wiki export
+
+Export the complete unique knowledge represented by the layered codebase views
+as a portable Markdown wiki:
+
+```bash
+delphi-lsp-agent wiki export --root PATH --out codebase-wiki
+```
+
+When `--out` is relative, it is resolved below `--root`; the default is
+`.delphi-lsp/wiki`. The command builds the semantic index once, deep-indexes
+main projects, calculates workspace and unit metrics, and writes:
+
+- an OKF 0.2 root `index.md`;
+- linked project, unit, and symbol concepts;
+- declaration and implementation source fragments;
+- resolved and unresolved semantic references;
+- discovery/project problems and complete metric records;
+- Protocol v3, relation, CPG, cache, and layer-mapping reference concepts.
+
+Without `--project-file`, the exporter selects repository main projects:
+non-example project entries in the repository root, or, when none exist, the
+shallowest configured `.dproj` entries. Recursively discovered example,
+sample, test, benchmark, and vendor projects are not promoted to project
+pages. A repository `.delphi-lsp.toml` can replace this heuristic with the
+explicit monorepo selection described below. With `--project-file`, only that
+explicit entry is selected. Project
+dependency traversal and include loading are confined to the repository root,
+so Delphi SDK and other external standard units are recorded as unresolved
+dependencies instead of being parsed. If no main project can be identified,
+the exporter falls back to the repository source inventory without inventing
+project pages.
+
+Every non-index concept is UTF-8 Markdown with YAML frontmatter and a non-empty
+`type`. Readable filenames include a stable digest, so overloads and equal names
+from different units remain distinct even on case-insensitive filesystems.
+Output order and content are deterministic. The finished bundle replaces the
+destination only after generation succeeds; an existing non-empty destination
+requires `--force`, and unsafe root/ancestor/symlink targets are rejected.
+
+Pages are streamed to disk, decoded source retention is bounded, and metrics
+process source paths without materializing the entire source corpus. Lazy CPG
+subgraphs are documented rather than eagerly multiplied across all possible
+targets; a focused live `cpg` query remains the bounded way to obtain one graph.
+The bundle structure follows the
+[Open Knowledge Format 0.2 specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md).
+
+Progress is shown on `stderr` while the final machine-readable JSON summary
+remains the only record on `stdout`. Redirected progress is throttled to
+milestones; pass `--quiet` to suppress it completely.
 
 ```bash
 delphi-lsp-agent query --root PATH find TCustomer
@@ -192,9 +251,14 @@ delphi-lsp-agent query --root PATH trace TARGET_ID --relation callers
 delphi-lsp-agent query --root PATH cpg TARGET_ID --graph full --direction out --depth 4
 delphi-lsp-agent query --root PATH metrics
 delphi-lsp-agent query --root PATH metrics UNIT_QUERY
+delphi-lsp-agent query --root PATH metrics --target-id UNIT_TARGET_ID
 delphi-lsp-agent cache status --root PATH --format json
 ```
 
+A `target_v2_...` positional value for `metrics` is also recognized as a unit
+target ID; other positional values remain case-insensitive unit-name or path
+queries.
+
 The repository root is sufficient even when it contains many projects:
 
 ```bash
@@ -203,7 +267,9 @@ delphi-lsp-agent query --root PATH find TCustomer
 ```
 
 This prewarms one bounded repository navigation index and requires no project
-selection. A `.dproj` is optional. Pass one when its project-specific compiler
+selection. A `.dproj` is optional. For repeatable monorepo selection, add a
+`.delphi-lsp.toml` file as described below. Pass one project explicitly when
+its project-specific compiler
 settings and `MainSource` should define the index:
 
 ```bash
@@ -221,6 +287,61 @@ delphi-lsp-agent query --root PATH focus --project-id PROJECT_ID
 
 Selecting a project this way also prewarms its navigation cache.
 
+### TOML project selection for monorepos
+
+Place `.delphi-lsp.toml` in the repository root to define which `.dpr`,
+`.dpk`, or companion `.dproj` projects belong to the codebase:
+
+```toml
+[projects]
+include = [
+  "apps/**",
+  "services/Api/ApiServer.dproj",
+  "packages/*/Runtime.dpk",
+]
+exclude = [
+  "**/examples/**",
+  "**/tests/**",
+]
+
+[workspace]
+exclude = [
+  "vendor",
+  "generated/**",
+  "thirdparty/legacy",
+]
+```
+
+Paths are relative to the repository root, case-insensitive, and use `/` on
+every operating system. An exact directory name covers all descendants. `*`
+matches within one path segment, while `**` crosses directory boundaries.
+Absolute paths and `..` traversal are rejected.
+
+When `include` is non-empty, only matching project entries remain. Matching a
+`.dproj` selects the `.dpr` or `.dpk` from its `MainSource`. The `exclude`
+list is applied afterward, so `exclude` always wins. With active TOML filters,
+all remaining matches are main projects even when they occur at different
+directory depths; the built-in shallow-project and example-name heuristic is
+not applied.
+
+Use `projects.exclude` when a directory may still contain shared units but its
+project entries must not become selectable projects. Use `workspace.exclude`
+for a hard boundary. Matching directories are never traversed or parsed, and
+neither is any file below them. They cannot be reintroduced by
+`projects.include` or an explicit `--project-file`. Unit dependencies and
+include directives resolving into those directories are reported as
+unavailable without reading the files.
+For complete directory pruning, an exact entry such as `"vendor"` is enough;
+`"generated/**"` also excludes the `generated` directory itself.
+
+The same selection is used by `cache`, `worker`, `query`, `view`, `index`,
+wiki export, and language-server discovery. An explicit `--project-file`
+bypasses `projects.include` and `projects.exclude` for that invocation, but
+never bypasses `workspace.exclude`. If no project remains, the command reports
+that the configured filters matched no Delphi projects and stops instead of
+silently parsing every source file in the repository. Restart an already
+running cache daemon after changing the path configuration.
+
 `inspect` uses the currently focused target, so call `focus TARGET_ID` before
 `inspect` unless a previous request already selected it.
 
@@ -254,7 +375,9 @@ under `.delphi-lsp/agent-cache/navigation-v1`. A restarted CLI or OpenCode cache
 daemon reuses unchanged units without parsing them again. Source content,
 conditional defines, or a shard-schema change produces a cache miss; malformed
 or incompatible JSON is ignored and rebuilt. The disk cache contains no pickle
-payloads and does not count against the retained-RAM budget.
+payloads and does not count against the retained-RAM budget. Each completed
+navigation build removes superseded shards and enforces the
+`--max-disk-cache` byte budget, which defaults to 512 MiB.
 
 Cache prewarming builds the navigation registry directly without constructing
 an empty-query result, symbol cards, pagination, or JSON payloads. Up to sixteen
@@ -290,7 +413,8 @@ outside the root workspace.
 `metrics`. For example, `delphi-lsp-agent view --layer metrics --format json`
 returns a project summary and detailed unit metric objects; `--query` filters
 units by name or path.
-`index` materializes overview, projects, and problems JSON. `skill install`
+`index` materializes overview, projects, and problems JSON. `wiki export`
+materializes the same navigational knowledge as a linked OKF Markdown bundle. `skill install`
 writes the skill; `opencode install` writes the package-named skill, Markdown
 agent, and plugin. The two deprecated write flags are harmless aliases and do
 not change user configuration.

python_delphi_lsp-3.1.1/delphi_lsp/_version.py

@@ -0,0 +1 @@
+__version__ = "3.1.1"