python-delphi-lsp 3.1.0__tar.gz → 3.1.2__tar.gz

{python_delphi_lsp-3.1.0 → python_delphi_lsp-3.1.2}/.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.1.0 → python_delphi_lsp-3.1.2}/MANIFEST.in

@@ -1,11 +1,15 @@
 include LICENSE
 include README.md
+include delphi_lsp/py.typed
 include opencode.json
 include .github/workflows/ci.yml
 include scripts/check_ornith_cache.py
 include scripts/audit_delphi_language_features.py
 include scripts/build_github_performance_corpus.py
 include scripts/benchmark_github_corpus.py
+include scripts/prepare_fpc_corpus.py
+include scripts/benchmark_fpc_corpus.py
+include scripts/prepare_delphi_corpus.py
 include scripts/benchmark_cpg.py
 include scripts/benchmark_parallel_cache.py
 include scripts/bootstrap_vllm_opencode_test.py
@@ -21,4 +25,9 @@ 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
+include tests/fpc_parse_quality.baseline.json
+include tests/test_fpc_performance_corpus.py
+include tests/test_delphi_performance_corpus.py
+include docs/performance-delphi.md
+recursive-include docs *.md
 recursive-include tests *.py *.pas *.inc *.dpr *.dpk

{python_delphi_lsp-3.1.0/python_delphi_lsp.egg-info → python_delphi_lsp-3.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-delphi-lsp
-Version: 3.1.0
+Version: 3.1.2
 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.1.0 is authored by Dark Light and supports Windows, macOS, and Linux.
+Version 3.1.2 is authored by Dark Light and supports Windows, macOS, and Linux.
 
 ## Install and quick start
 
@@ -190,17 +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]
+                             [--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]
@@ -219,12 +224,16 @@ 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
 
@@ -237,7 +246,7 @@ 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
-discovered projects, calculates workspace and unit metrics, and writes:
+main projects, calculates workspace and unit metrics, and writes:
 
 - an OKF 0.2 root `index.md`;
 - linked project, unit, and symbol concepts;
@@ -246,6 +255,19 @@ discovered projects, calculates workspace and unit metrics, and writes:
 - 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.
@@ -260,6 +282,10 @@ 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
 delphi-lsp-agent query --root PATH focus TARGET_ID
@@ -268,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
@@ -279,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
@@ -297,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.
 
@@ -330,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
@@ -431,6 +521,12 @@ source was parsed for CPG. Legacy navigation retained 98.43 percent of its
 in-run control throughput, above the 95-percent release floor. Reproduce it
 with `python scripts/benchmark_cpg.py --root CORPUS --query Run --workers 8`.
 
+Separate reproducible performance profiles cover the coherent FPC compiler
+tree and a project-file-dense Delphi corpus. The Delphi profile can add a
+deterministic `__history`/recovery/build/search-path overlay without changing
+the pinned base corpus. See [the FPC benchmark](docs/performance-fpc.md) and
+[the Delphi discovery benchmark](docs/performance-delphi.md).
+
 For every source size the navigator builds an outline first, loads source detail
 lazily for a selected target, and returns only selected fragments. Typed source
 chunks are at most 6000 characters and also respect the response budget. This

{python_delphi_lsp-3.1.0 → python_delphi_lsp-3.1.2}/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.1.0 is authored by Dark Light and supports Windows, macOS, and Linux.
+Version 3.1.2 is authored by Dark Light and supports Windows, macOS, and Linux.
 
 ## Install and quick start
 
@@ -150,17 +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]
+                             [--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]
@@ -179,12 +181,16 @@ 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
 
@@ -197,7 +203,7 @@ 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
-discovered projects, calculates workspace and unit metrics, and writes:
+main projects, calculates workspace and unit metrics, and writes:
 
 - an OKF 0.2 root `index.md`;
 - linked project, unit, and symbol concepts;
@@ -206,6 +212,19 @@ discovered projects, calculates workspace and unit metrics, and writes:
 - 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.
@@ -220,6 +239,10 @@ 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
 delphi-lsp-agent query --root PATH focus TARGET_ID
@@ -228,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
@@ -239,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
@@ -257,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.
 
@@ -290,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
@@ -391,6 +478,12 @@ source was parsed for CPG. Legacy navigation retained 98.43 percent of its
 in-run control throughput, above the 95-percent release floor. Reproduce it
 with `python scripts/benchmark_cpg.py --root CORPUS --query Run --workers 8`.
 
+Separate reproducible performance profiles cover the coherent FPC compiler
+tree and a project-file-dense Delphi corpus. The Delphi profile can add a
+deterministic `__history`/recovery/build/search-path overlay without changing
+the pinned base corpus. See [the FPC benchmark](docs/performance-fpc.md) and
+[the Delphi discovery benchmark](docs/performance-delphi.md).
+
 For every source size the navigator builds an outline first, loads source detail
 lazily for a selected target, and returns only selected fragments. Typed source
 chunks are at most 6000 characters and also respect the response budget. This

python_delphi_lsp-3.1.2/delphi_lsp/_version.py

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