python-delphi-lsp 1.0.1__tar.gz → 1.1.1__tar.gz

{python_delphi_lsp-1.0.1 → python_delphi_lsp-1.1.1}/MANIFEST.in

@@ -4,6 +4,7 @@ include opencode.json
 include scripts/check_ornith_cache.py
 include scripts/audit_delphi_language_features.py
 include scripts/bootstrap_vllm_opencode_test.py
+include scripts/bootstrap_vllm_codebase_skill_test.py
 include scripts/bootstrap_vllm_opencode_test.ps1
 include scripts/bootstrap_vllm_opencode_test.sh
 include scripts/generate_release_evidence.py

{python_delphi_lsp-1.0.1/python_delphi_lsp.egg-info → python_delphi_lsp-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-delphi-lsp
-Version: 1.0.1
+Version: 1.1.1
 Summary: Python Delphi/Object Pascal parser, semantic indexer, and language server.
 Author: Dark Light
 License-Expression: MPL-2.0
@@ -43,8 +43,9 @@ Python Delphi LSP is a standalone Python package for Delphi/Object Pascal
 parsing, semantic indexing, diagnostics, and Language Server Protocol support.
 
 The distributable package is named `python-delphi-lsp`. The import package keeps
-the established `delphiast` name, and the language-server executable is
-`delphi-lsp`.
+the established `delphiast` name. The language-server executable is
+`delphi-lsp`, and the agent-facing codebase navigator executable is
+`delphi-lsp-agent`.
 
 ## What It Provides
 
@@ -56,7 +57,10 @@ the established `delphiast` name, and the language-server executable is
 - Workspace indexing across Delphi projects
 - LSP support for document symbols, workspace symbols, hover, definition,
   references, rename, completion, and diagnostics
-- opencode integration through the experimental LSP tool
+- Automatic project path discovery from `.dpr`, `.dpk`, `.dproj`, `.cfg`, and
+  `.dof` files
+- opencode integration through the experimental LSP tool and an installable
+  `.agents` skill with a dedicated codebase-inspection tool
 
 ## Installation
 
@@ -138,17 +142,77 @@ python -m delphiast.lsp_server
 ```
 
 The server expects normal LSP JSON-RPC over stdio. Editors and tools should set
-the workspace root to the Delphi project directory and pass any include paths or
-compiler defines through LSP initialization options when needed.
+the workspace root to the Delphi project directory.
+
+Auto-discovery reads `.dpr`, `.dpk`, `.dproj`, `.cfg`, and `.dof` files to
+collect unit search paths, include paths, defines, direct `Unit in 'path.pas'`
+references, and workspace source directories. Manual initialization options are
+still accepted as overrides, but a normal project should not require users to
+set include or source paths by hand.
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "lsp": {
+    "delphi": {
+      "command": ["python", "-m", "delphiast.lsp_server"],
+      "extensions": [".pas", ".dpr", ".dpk", ".inc"],
+      "initialization": {
+        "autoDiscoverPaths": true
+      }
+    }
+  }
+}
+```
+
+## Agent Codebase Navigator
+
+Install the opencode skill and custom tool in a Delphi checkout:
+
+```bash
+delphi-lsp-agent opencode install --target . --write-config
+```
+
+This writes:
+
+- `.agents/skills/delphi-codebase-navigator/SKILL.md`
+- `.opencode/tools/delphi_codebase.ts`
+- an optional `vllm-delphi-codebase` agent entry in `opencode.json`
+
+The skill tells agents to inspect Delphi code through layered semantic views
+instead of loading full source files. The custom opencode tool calls
+`python -m delphiast.agent_cli` directly, so the agent does not need shell text
+search or raw file-reading tools to understand the codebase.
+
+Useful direct commands:
+
+```bash
+delphi-lsp-agent view --root . --layer overview
+delphi-lsp-agent view --root . --layer projects
+delphi-lsp-agent view --root . --layer unit --query Mega100kUnit
+delphi-lsp-agent view --root . --layer symbols --query TWorker --format json
+delphi-lsp-agent view --root . --layer implementation --query TWorker.Run
+delphi-lsp-agent view --root . --layer implementation --query TWorker --format json
+delphi-lsp-agent view --root . --layer problems
+```
+
+Available layers are `overview`, `projects`, `units`, `unit`, `symbols`,
+`symbol`, `implementation`, `references`, and `problems`. The output includes
+file and line citations, declarations, ownership, visibility, type information,
+and dependency/problem summaries. Outline layers keep routine bodies out of the
+agent context. Use `implementation` with a concrete class, routine, or member
+query to read only that complete source fragment from the original file. For a
+class query, the layer returns the class declaration plus matching method
+implementations; for a routine query, it returns the full routine body.
 
 ## opencode Usage
 
 This repository includes an `opencode.json` that registers the Delphi LSP tool
 and model aliases for local Ollama and vLLM endpoints.
 
-To add the Delphi language server to another opencode project, install the
-package in the Python environment used by opencode and add an `lsp.delphi`
-entry to that project's `opencode.json`:
+To add the Delphi language server to another opencode project without the
+agent tool, install the package in the Python environment used by opencode and
+add an `lsp.delphi` entry to that project's `opencode.json`:
 
 ```json
 {
@@ -158,17 +222,16 @@ entry to that project's `opencode.json`:
       "command": ["python", "-m", "delphiast.lsp_server"],
       "extensions": [".pas", ".dpr", ".dpk", ".inc"],
       "initialization": {
-        "includePaths": ["src", "lib"],
-        "defines": ["MSWINDOWS"]
+        "autoDiscoverPaths": true
       }
     }
   }
 }
 ```
 
-Adjust `includePaths` and `defines` to match the Delphi project. For checkout
-development, this repository's own `opencode.json` uses the local virtual
-environment and sets `PYTHONPATH` so opencode loads the source tree directly:
+For checkout development, this repository's own `opencode.json` uses the local
+virtual environment and sets `PYTHONPATH` so opencode loads the source tree
+directly:
 
 ```json
 {
@@ -180,8 +243,7 @@ environment and sets `PYTHONPATH` so opencode loads the source tree directly:
         "PYTHONPATH": "."
       },
       "initialization": {
-        "includePaths": ["tests/fixtures", "tests/fixtures/legacy_snippets"],
-        "defines": []
+        "autoDiscoverPaths": true
       }
     }
   }
@@ -299,6 +361,43 @@ The release evidence from the local proof recorded:
 - `context_budget.status = "pass"`
 - `goal_audit.status = "pass"`
 
+## Reproducing the vLLM opencode Skill Test
+
+The codebase skill proof validates the `.agents` skill and opencode custom tool
+instead of only the raw LSP tool. It creates a sandbox Delphi project with:
+
+- `Main.dpr`
+- `Main.dproj`
+- `src/Mega100kUnit.pas` with more than 100,000 lines
+- `include/build.inc`
+- `.agents/skills/delphi-codebase-navigator/SKILL.md`
+- `.opencode/tools/delphi_codebase.ts`
+
+Run it against the local Ornith vLLM endpoint:
+
+```bash
+python scripts/bootstrap_vllm_codebase_skill_test.py --use-running-server
+```
+
+Or let the macOS helper start vLLM without downloading model shards:
+
+```bash
+python scripts/bootstrap_vllm_codebase_skill_test.py --start-vllm
+```
+
+This skill probe defaults the vLLM helper to `MAX_MODEL_LEN=32768`, which was
+the stable local Metal setting for the reduced codebase-agent prompt plus the
+`delphi_codebase` tool call. Override with `--max-model-len` when your machine
+has enough headroom.
+
+The probe verifies that the `delphi-codebase-navigator` skill is installed, then
+requires opencode to call `delphi_codebase`, find `MegaProc02500`, and read the
+method body through the `implementation` layer. The vLLM test agent keeps
+opencode's generic `skill` tool disabled so the model context stays focused on
+the Delphi navigation tool. The probe fails if opencode uses `bash`, `read`,
+`glob`, `grep`, `edit`, `write`, `task`, `webfetch`, or `todowrite` before the
+required evidence is complete.
+
 ## Verification
 
 Run the local test suite:
@@ -322,8 +421,8 @@ python -m twine check dist/*
 
 ## Repository Layout
 
-- `delphiast/` - parser, preprocessor, semantic model, workspace indexer, and
-  LSP server
+- `delphiast/` - parser, preprocessor, project discovery, semantic model,
+  workspace indexer, agent layers, and LSP server
 - `scripts/` - release evidence, cache checks, opencode probes, and bootstrap
   helpers
 - `tests/` - parser, semantic, workspace, diagnostics, packaging, and LSP tests

{python_delphi_lsp-1.0.1 → python_delphi_lsp-1.1.1}/README.md

@@ -4,8 +4,9 @@ Python Delphi LSP is a standalone Python package for Delphi/Object Pascal
 parsing, semantic indexing, diagnostics, and Language Server Protocol support.
 
 The distributable package is named `python-delphi-lsp`. The import package keeps
-the established `delphiast` name, and the language-server executable is
-`delphi-lsp`.
+the established `delphiast` name. The language-server executable is
+`delphi-lsp`, and the agent-facing codebase navigator executable is
+`delphi-lsp-agent`.
 
 ## What It Provides
 
@@ -17,7 +18,10 @@ the established `delphiast` name, and the language-server executable is
 - Workspace indexing across Delphi projects
 - LSP support for document symbols, workspace symbols, hover, definition,
   references, rename, completion, and diagnostics
-- opencode integration through the experimental LSP tool
+- Automatic project path discovery from `.dpr`, `.dpk`, `.dproj`, `.cfg`, and
+  `.dof` files
+- opencode integration through the experimental LSP tool and an installable
+  `.agents` skill with a dedicated codebase-inspection tool
 
 ## Installation
 
@@ -99,17 +103,77 @@ python -m delphiast.lsp_server
 ```
 
 The server expects normal LSP JSON-RPC over stdio. Editors and tools should set
-the workspace root to the Delphi project directory and pass any include paths or
-compiler defines through LSP initialization options when needed.
+the workspace root to the Delphi project directory.
+
+Auto-discovery reads `.dpr`, `.dpk`, `.dproj`, `.cfg`, and `.dof` files to
+collect unit search paths, include paths, defines, direct `Unit in 'path.pas'`
+references, and workspace source directories. Manual initialization options are
+still accepted as overrides, but a normal project should not require users to
+set include or source paths by hand.
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "lsp": {
+    "delphi": {
+      "command": ["python", "-m", "delphiast.lsp_server"],
+      "extensions": [".pas", ".dpr", ".dpk", ".inc"],
+      "initialization": {
+        "autoDiscoverPaths": true
+      }
+    }
+  }
+}
+```
+
+## Agent Codebase Navigator
+
+Install the opencode skill and custom tool in a Delphi checkout:
+
+```bash
+delphi-lsp-agent opencode install --target . --write-config
+```
+
+This writes:
+
+- `.agents/skills/delphi-codebase-navigator/SKILL.md`
+- `.opencode/tools/delphi_codebase.ts`
+- an optional `vllm-delphi-codebase` agent entry in `opencode.json`
+
+The skill tells agents to inspect Delphi code through layered semantic views
+instead of loading full source files. The custom opencode tool calls
+`python -m delphiast.agent_cli` directly, so the agent does not need shell text
+search or raw file-reading tools to understand the codebase.
+
+Useful direct commands:
+
+```bash
+delphi-lsp-agent view --root . --layer overview
+delphi-lsp-agent view --root . --layer projects
+delphi-lsp-agent view --root . --layer unit --query Mega100kUnit
+delphi-lsp-agent view --root . --layer symbols --query TWorker --format json
+delphi-lsp-agent view --root . --layer implementation --query TWorker.Run
+delphi-lsp-agent view --root . --layer implementation --query TWorker --format json
+delphi-lsp-agent view --root . --layer problems
+```
+
+Available layers are `overview`, `projects`, `units`, `unit`, `symbols`,
+`symbol`, `implementation`, `references`, and `problems`. The output includes
+file and line citations, declarations, ownership, visibility, type information,
+and dependency/problem summaries. Outline layers keep routine bodies out of the
+agent context. Use `implementation` with a concrete class, routine, or member
+query to read only that complete source fragment from the original file. For a
+class query, the layer returns the class declaration plus matching method
+implementations; for a routine query, it returns the full routine body.
 
 ## opencode Usage
 
 This repository includes an `opencode.json` that registers the Delphi LSP tool
 and model aliases for local Ollama and vLLM endpoints.
 
-To add the Delphi language server to another opencode project, install the
-package in the Python environment used by opencode and add an `lsp.delphi`
-entry to that project's `opencode.json`:
+To add the Delphi language server to another opencode project without the
+agent tool, install the package in the Python environment used by opencode and
+add an `lsp.delphi` entry to that project's `opencode.json`:
 
 ```json
 {
@@ -119,17 +183,16 @@ entry to that project's `opencode.json`:
       "command": ["python", "-m", "delphiast.lsp_server"],
       "extensions": [".pas", ".dpr", ".dpk", ".inc"],
       "initialization": {
-        "includePaths": ["src", "lib"],
-        "defines": ["MSWINDOWS"]
+        "autoDiscoverPaths": true
       }
     }
   }
 }
 ```
 
-Adjust `includePaths` and `defines` to match the Delphi project. For checkout
-development, this repository's own `opencode.json` uses the local virtual
-environment and sets `PYTHONPATH` so opencode loads the source tree directly:
+For checkout development, this repository's own `opencode.json` uses the local
+virtual environment and sets `PYTHONPATH` so opencode loads the source tree
+directly:
 
 ```json
 {
@@ -141,8 +204,7 @@ environment and sets `PYTHONPATH` so opencode loads the source tree directly:
         "PYTHONPATH": "."
       },
       "initialization": {
-        "includePaths": ["tests/fixtures", "tests/fixtures/legacy_snippets"],
-        "defines": []
+        "autoDiscoverPaths": true
       }
     }
   }
@@ -260,6 +322,43 @@ The release evidence from the local proof recorded:
 - `context_budget.status = "pass"`
 - `goal_audit.status = "pass"`
 
+## Reproducing the vLLM opencode Skill Test
+
+The codebase skill proof validates the `.agents` skill and opencode custom tool
+instead of only the raw LSP tool. It creates a sandbox Delphi project with:
+
+- `Main.dpr`
+- `Main.dproj`
+- `src/Mega100kUnit.pas` with more than 100,000 lines
+- `include/build.inc`
+- `.agents/skills/delphi-codebase-navigator/SKILL.md`
+- `.opencode/tools/delphi_codebase.ts`
+
+Run it against the local Ornith vLLM endpoint:
+
+```bash
+python scripts/bootstrap_vllm_codebase_skill_test.py --use-running-server
+```
+
+Or let the macOS helper start vLLM without downloading model shards:
+
+```bash
+python scripts/bootstrap_vllm_codebase_skill_test.py --start-vllm
+```
+
+This skill probe defaults the vLLM helper to `MAX_MODEL_LEN=32768`, which was
+the stable local Metal setting for the reduced codebase-agent prompt plus the
+`delphi_codebase` tool call. Override with `--max-model-len` when your machine
+has enough headroom.
+
+The probe verifies that the `delphi-codebase-navigator` skill is installed, then
+requires opencode to call `delphi_codebase`, find `MegaProc02500`, and read the
+method body through the `implementation` layer. The vLLM test agent keeps
+opencode's generic `skill` tool disabled so the model context stays focused on
+the Delphi navigation tool. The probe fails if opencode uses `bash`, `read`,
+`glob`, `grep`, `edit`, `write`, `task`, `webfetch`, or `todowrite` before the
+required evidence is complete.
+
 ## Verification
 
 Run the local test suite:
@@ -283,8 +382,8 @@ python -m twine check dist/*
 
 ## Repository Layout
 
-- `delphiast/` - parser, preprocessor, semantic model, workspace indexer, and
-  LSP server
+- `delphiast/` - parser, preprocessor, project discovery, semantic model,
+  workspace indexer, agent layers, and LSP server
 - `scripts/` - release evidence, cache checks, opencode probes, and bootstrap
   helpers
 - `tests/` - parser, semantic, workspace, diagnostics, packaging, and LSP tests

{python_delphi_lsp-1.0.1 → python_delphi_lsp-1.1.1}/delphiast/__init__.py

@@ -46,6 +46,7 @@ from .semantic import (
 from .semantic_builder import SemanticBuilder, SemanticModel, SemanticProblem
 from .workspace import WorkspaceSemanticResult, build_workspace_semantics
 from .lsp_server import LspWorkspaceState, create_server
+from .project_discovery import DelphiProjectDiscovery, DiscoveryProblem, discover_delphi_project
 from .project_indexer import (
     GetUnitSyntaxHook,
     IncludeFileInfo,
@@ -119,6 +120,9 @@ __all__ = [
     'build_workspace_semantics',
     'LspWorkspaceState',
     'create_server',
+    'DelphiProjectDiscovery',
+    'DiscoveryProblem',
+    'discover_delphi_project',
     'ProjectIndexer',
     'ProjectIndexResult',
     'ProjectProblemType',

python_delphi_lsp-1.1.1/delphiast/agent_cli.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .agent_layers import build_codebase_index, layer_payload, render_layer
+from .agent_templates import install_opencode_support, install_skill
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="delphi-lsp-agent",
+        description="Agent-facing Delphi/Object Pascal codebase navigation helpers.",
+    )
+    subcommands = parser.add_subparsers(dest="command", required=True)
+
+    view = subcommands.add_parser("view", help="Render a layered codebase view.")
+    view.add_argument("--root", type=Path, default=Path("."))
+    view.add_argument("--project-file", type=Path)
+    view.add_argument(
+        "--layer",
+        required=True,
+        choices=[
+            "overview",
+            "projects",
+            "units",
+            "unit",
+            "symbols",
+            "symbol",
+            "implementation",
+            "references",
+            "problems",
+        ],
+    )
+    view.add_argument("--query", default="")
+    view.add_argument("--format", default="markdown", choices=["markdown", "json"])
+    view.add_argument("--deep-projects", action="store_true", help="Deep-parse project dependencies for the projects layer.")
+    view.set_defaults(func=_view)
+
+    index = subcommands.add_parser("index", help="Materialize a JSON codebase index.")
+    index.add_argument("--root", type=Path, default=Path("."))
+    index.add_argument("--project-file", type=Path)
+    index.add_argument("--out", type=Path, default=Path(".delphi-lsp") / "agent-index" / "index.json")
+    index.set_defaults(func=_index)
+
+    skill = subcommands.add_parser("skill", help="Install agent skill templates.")
+    skill_commands = skill.add_subparsers(dest="skill_command", required=True)
+    skill_install = skill_commands.add_parser("install", help="Install .agents skill.")
+    skill_install.add_argument("--target", type=Path, default=Path("."))
+    skill_install.add_argument("--force", action="store_true")
+    skill_install.set_defaults(func=_skill_install)
+
+    opencode = subcommands.add_parser("opencode", help="Install opencode integration.")
+    opencode_commands = opencode.add_subparsers(dest="opencode_command", required=True)
+    opencode_install = opencode_commands.add_parser("install", help="Install .agents skill and opencode custom tool.")
+    opencode_install.add_argument("--target", type=Path, default=Path("."))
+    opencode_install.add_argument("--python", default=sys.executable)
+    opencode_install.add_argument("--force", action="store_true")
+    opencode_install.add_argument("--write-config", action="store_true")
+    opencode_install.set_defaults(func=_opencode_install)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        args.func(args)
+    except BrokenPipeError:
+        return 1
+    return 0
+
+
+def _view(args: argparse.Namespace) -> None:
+    index = build_codebase_index(args.root, project_file=args.project_file, index_projects=args.deep_projects)
+    sys.stdout.write(render_layer(index, args.layer, query=args.query, output_format=args.format))
+
+
+def _index(args: argparse.Namespace) -> None:
+    index = build_codebase_index(args.root, project_file=args.project_file, index_projects=True)
+    payload = {
+        "overview": layer_payload(index, "overview"),
+        "projects": layer_payload(index, "projects"),
+        "problems": layer_payload(index, "problems"),
+    }
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    args.out.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    print(args.out)
+
+
+def _skill_install(args: argparse.Namespace) -> None:
+    skill_path = install_skill(args.target, force=args.force)
+    print(skill_path)
+
+
+def _opencode_install(args: argparse.Namespace) -> None:
+    skill_path, tool_path, config_path = install_opencode_support(
+        args.target,
+        python_executable=args.python,
+        force=args.force,
+        write_config=args.write_config,
+    )
+    print(skill_path)
+    print(tool_path)
+    if config_path is not None:
+        print(config_path)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())