python-delphi-lsp 2.0.0__tar.gz → 2.0.2__tar.gz

{python_delphi_lsp-2.0.0/python_delphi_lsp.egg-info → python_delphi_lsp-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-delphi-lsp
-Version: 2.0.0
+Version: 2.0.2
 Summary: Python Delphi/Object Pascal parser, semantic indexer, and language server.
 Author: Dark Light
 License-Expression: MPL-2.0
@@ -41,7 +41,7 @@ Dynamic: license-file
 
 `python-delphi-lsp` parses Delphi/Object Pascal, builds semantic and project
 indexes, serves LSP, and provides bounded codebase navigation for agents.
-Version 2.0.0 is authored by Dark Light and supports Windows, macOS, and Linux.
+Version 2.0.2 is authored by Dark Light and supports Windows, macOS, and Linux.
 
 ## Install and quick start
 
@@ -82,6 +82,39 @@ project = ProjectIndexer(
 print(project.parsed_units)
 ```
 
+## Architecture metrics
+
+The public metrics API analyzes a single unit or aggregates a complete project:
+
+```python
+from delphi_lsp import analyze_project, analyze_unit
+
+unit = analyze_unit(
+    "unit Alpha; interface implementation procedure Run; begin end; end.",
+    "Alpha.pas",
+)
+print(unit.lines.total_lines, unit.cyclomatic.maximum)
+
+project = analyze_project({
+    "Main.dpr": "program Main; uses Alpha; begin end.",
+    "Alpha.pas": "unit Alpha; interface implementation end.",
+})
+print(project.total_loc)
+```
+
+Line results distinguish total, source, blank, comment-only, mixed-comment, and
+compiler-directive lines. Project `total_loc` counts each `.dpr`, `.dpk`, and
+`.pas` source once; `include_loc` counts unique `.inc` inputs separately, and
+`total_loc_with_includes` combines both totals.
+
+Cyclomatic complexity is reported per routine and as unit/project aggregates.
+The result also includes complete Halstead counts and derived values, a
+normalized 0–100 maintainability index, symbol counts, dependency edges,
+afferent coupling (fan-in), efferent coupling (fan-out), instability,
+abstractness, and distance from the main sequence. Coupling detail separates
+internal from external dependencies. Empty or partial inputs produce finite
+JSON values; unreadable agent-workspace inputs are reported as metric problems.
+
 Run the stdio language server with `delphi-lsp`, or equivalently:
 
 ```bash
@@ -144,19 +177,27 @@ delphi-lsp-agent view --root PATH [--project-file FILE] --layer LAYER
 delphi-lsp-agent index --root PATH [--project-file FILE] [--out FILE]
 delphi-lsp-agent skill install [--target PATH] [--force]
 delphi-lsp-agent opencode install [--target PATH] [--python PYTHON]
-                                  [--force] [--write-config]
+                                  [--force] [--write-agent|--write-config]
 delphi-lsp-agent worker --root PATH [--project-file FILE]
 ```
 
 `view --layer` accepts `overview`, `projects`, `units`, `unit`,
-`symbols`, `symbol`, `implementation`, `references`, and `problems`.
+`symbols`, `symbol`, `implementation`, `references`, `problems`, and
+`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`
-writes the skill; `opencode install` writes both integration files, while
-`--write-config` additionally writes the restricted agent configuration.
+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.
 `worker` serves NDJSON over standard input/output.
 
 Protocol v2 actions are `open`, `find`, `inspect`, `trace`, `focus`,
-and `problems`. Detail values are `summary`, `declaration`, `members`,
+`problems`, and `metrics`. A `metrics` request without a query returns the
+project summary followed by unit cards. A query filters units, while a unit
+`target_id` from `open` selects one unit; `detail: "members"` adds routine,
+Halstead, dependency, and symbol-count detail without returning source text.
+Detail values are `summary`, `declaration`, `members`,
 `context`, `body`, and `implementations`. Relations are `references`,
 `callers`, `callees`, `uses`, `used_by`, `inherits`, and
 `implements`.
@@ -185,52 +226,54 @@ optimization does not remove LSP functionality.
 Install the generated integration in a worktree:
 
 ```bash
-delphi-lsp-agent opencode install --target . --write-config
+delphi-lsp-agent opencode install --target .
 ```
 
 It writes:
 
 ```text
-.agents/skills/delphi-codebase-navigator/SKILL.md
+.agents/skills/python-delphi-lsp/SKILL.md
 .opencode/plugins/delphi_codebase.ts
+.opencode/agents/python-delphi-lsp.md
 ```
 
-The generated configuration enables only the named
-`delphi-codebase-navigator` skill and `delphi_codebase`. It denies
+The package-named Markdown agent enables only the
+`python-delphi-lsp` skill and `delphi_codebase`. It denies
 `bash`, `read`, `glob`, `grep`, and `lsp`, along with edit/write and
 other raw source tools. The skill is enabled. The installer does not use the
-retired `.opencode/tools` path.
+retired `.opencode/tools` path and never reads or changes `opencode.json`; that
+file remains entirely user-owned. The deprecated `--write-config` and
+`--write-agent` options are accepted harmlessly for compatibility.
 
 The plugin maintains one worker per session/root, reusing focus and indexes.
 During compaction it restores the focus and summary into the new context.
 Transport failure, session deletion, and plugin disposal clean up the worker.
 
-A generated OpenCode agent looks like this; providers and unrelated agents stay
-unchanged:
-
-```json
-{
-  "agent": {
-    "vllm-delphi-codebase": {
-      "tools": {
-        "delphi_codebase": true, "skill": true, "lsp": false,
-        "bash": false, "read": false, "glob": false, "grep": false
-      },
-      "permission": {
-        "delphi_codebase": "allow",
-        "skill": {"*": "deny", "delphi-codebase-navigator": "allow"},
-        "lsp": "deny"
-      }
-    }
-  }
-}
+A generated OpenCode agent starts with this Markdown frontmatter:
+
+```markdown
+---
+description: Inspect Delphi and Object Pascal codebases through python-delphi-lsp.
+mode: subagent
+temperature: 0
+permission:
+  "*": deny
+  delphi_codebase: allow
+  skill:
+    "*": deny
+    python-delphi-lsp: allow
+---
 ```
 
-Select `vllm-delphi-codebase`, ask it to load
-`delphi-codebase-navigator`, then use `delphi_codebase` actions such as
+Select `python-delphi-lsp`, ask it to load the `python-delphi-lsp` skill, then
+use `delphi_codebase` actions such as
 `open`, `find`, `focus`, and `inspect`. Use semantic tool calls, not raw
 source tools.
 
+For architecture questions, call `metrics` without a query to compare unit
+cards and read project LOC. Then select a returned unit ID with another
+`metrics` call and `detail: "members"` to inspect its routines and coupling.
+
 For the root LSP configuration, a local model can be used as follows:
 
 ```bash
@@ -297,6 +340,18 @@ local model server, increase it explicitly with `--probe-timeout SECONDS`.
 
 The bundled automatic helper is not a cross-platform startup mechanism.
 
+The architecture-metrics proof uses a separate deterministic 34-LOC project.
+It requires the restricted model to load the skill, call `metrics` for the
+project and most-complex unit, and report exact LOC, cyclomatic maximum, and
+instability values. Raw source, search, shell, and write tools remain forbidden:
+
+```bash
+python scripts/bootstrap_vllm_codebase_skill_test.py --probe metrics --use-running-server
+```
+
+Use `--probe metrics --start-vllm --max-model-len 24576` for the cached macOS
+auto-start path when no endpoint is already running.
+
 ## Migration to 2.0
 
 `delphi_lsp` is the only supported import namespace. Update imports directly;

{python_delphi_lsp-2.0.0 → python_delphi_lsp-2.0.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 2.0.0 is authored by Dark Light and supports Windows, macOS, and Linux.
+Version 2.0.2 is authored by Dark Light and supports Windows, macOS, and Linux.
 
 ## Install and quick start
 
@@ -43,6 +43,39 @@ project = ProjectIndexer(
 print(project.parsed_units)
 ```
 
+## Architecture metrics
+
+The public metrics API analyzes a single unit or aggregates a complete project:
+
+```python
+from delphi_lsp import analyze_project, analyze_unit
+
+unit = analyze_unit(
+    "unit Alpha; interface implementation procedure Run; begin end; end.",
+    "Alpha.pas",
+)
+print(unit.lines.total_lines, unit.cyclomatic.maximum)
+
+project = analyze_project({
+    "Main.dpr": "program Main; uses Alpha; begin end.",
+    "Alpha.pas": "unit Alpha; interface implementation end.",
+})
+print(project.total_loc)
+```
+
+Line results distinguish total, source, blank, comment-only, mixed-comment, and
+compiler-directive lines. Project `total_loc` counts each `.dpr`, `.dpk`, and
+`.pas` source once; `include_loc` counts unique `.inc` inputs separately, and
+`total_loc_with_includes` combines both totals.
+
+Cyclomatic complexity is reported per routine and as unit/project aggregates.
+The result also includes complete Halstead counts and derived values, a
+normalized 0–100 maintainability index, symbol counts, dependency edges,
+afferent coupling (fan-in), efferent coupling (fan-out), instability,
+abstractness, and distance from the main sequence. Coupling detail separates
+internal from external dependencies. Empty or partial inputs produce finite
+JSON values; unreadable agent-workspace inputs are reported as metric problems.
+
 Run the stdio language server with `delphi-lsp`, or equivalently:
 
 ```bash
@@ -105,19 +138,27 @@ delphi-lsp-agent view --root PATH [--project-file FILE] --layer LAYER
 delphi-lsp-agent index --root PATH [--project-file FILE] [--out FILE]
 delphi-lsp-agent skill install [--target PATH] [--force]
 delphi-lsp-agent opencode install [--target PATH] [--python PYTHON]
-                                  [--force] [--write-config]
+                                  [--force] [--write-agent|--write-config]
 delphi-lsp-agent worker --root PATH [--project-file FILE]
 ```
 
 `view --layer` accepts `overview`, `projects`, `units`, `unit`,
-`symbols`, `symbol`, `implementation`, `references`, and `problems`.
+`symbols`, `symbol`, `implementation`, `references`, `problems`, and
+`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`
-writes the skill; `opencode install` writes both integration files, while
-`--write-config` additionally writes the restricted agent configuration.
+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.
 `worker` serves NDJSON over standard input/output.
 
 Protocol v2 actions are `open`, `find`, `inspect`, `trace`, `focus`,
-and `problems`. Detail values are `summary`, `declaration`, `members`,
+`problems`, and `metrics`. A `metrics` request without a query returns the
+project summary followed by unit cards. A query filters units, while a unit
+`target_id` from `open` selects one unit; `detail: "members"` adds routine,
+Halstead, dependency, and symbol-count detail without returning source text.
+Detail values are `summary`, `declaration`, `members`,
 `context`, `body`, and `implementations`. Relations are `references`,
 `callers`, `callees`, `uses`, `used_by`, `inherits`, and
 `implements`.
@@ -146,52 +187,54 @@ optimization does not remove LSP functionality.
 Install the generated integration in a worktree:
 
 ```bash
-delphi-lsp-agent opencode install --target . --write-config
+delphi-lsp-agent opencode install --target .
 ```
 
 It writes:
 
 ```text
-.agents/skills/delphi-codebase-navigator/SKILL.md
+.agents/skills/python-delphi-lsp/SKILL.md
 .opencode/plugins/delphi_codebase.ts
+.opencode/agents/python-delphi-lsp.md
 ```
 
-The generated configuration enables only the named
-`delphi-codebase-navigator` skill and `delphi_codebase`. It denies
+The package-named Markdown agent enables only the
+`python-delphi-lsp` skill and `delphi_codebase`. It denies
 `bash`, `read`, `glob`, `grep`, and `lsp`, along with edit/write and
 other raw source tools. The skill is enabled. The installer does not use the
-retired `.opencode/tools` path.
+retired `.opencode/tools` path and never reads or changes `opencode.json`; that
+file remains entirely user-owned. The deprecated `--write-config` and
+`--write-agent` options are accepted harmlessly for compatibility.
 
 The plugin maintains one worker per session/root, reusing focus and indexes.
 During compaction it restores the focus and summary into the new context.
 Transport failure, session deletion, and plugin disposal clean up the worker.
 
-A generated OpenCode agent looks like this; providers and unrelated agents stay
-unchanged:
-
-```json
-{
-  "agent": {
-    "vllm-delphi-codebase": {
-      "tools": {
-        "delphi_codebase": true, "skill": true, "lsp": false,
-        "bash": false, "read": false, "glob": false, "grep": false
-      },
-      "permission": {
-        "delphi_codebase": "allow",
-        "skill": {"*": "deny", "delphi-codebase-navigator": "allow"},
-        "lsp": "deny"
-      }
-    }
-  }
-}
+A generated OpenCode agent starts with this Markdown frontmatter:
+
+```markdown
+---
+description: Inspect Delphi and Object Pascal codebases through python-delphi-lsp.
+mode: subagent
+temperature: 0
+permission:
+  "*": deny
+  delphi_codebase: allow
+  skill:
+    "*": deny
+    python-delphi-lsp: allow
+---
 ```
 
-Select `vllm-delphi-codebase`, ask it to load
-`delphi-codebase-navigator`, then use `delphi_codebase` actions such as
+Select `python-delphi-lsp`, ask it to load the `python-delphi-lsp` skill, then
+use `delphi_codebase` actions such as
 `open`, `find`, `focus`, and `inspect`. Use semantic tool calls, not raw
 source tools.
 
+For architecture questions, call `metrics` without a query to compare unit
+cards and read project LOC. Then select a returned unit ID with another
+`metrics` call and `detail: "members"` to inspect its routines and coupling.
+
 For the root LSP configuration, a local model can be used as follows:
 
 ```bash
@@ -258,6 +301,18 @@ local model server, increase it explicitly with `--probe-timeout SECONDS`.
 
 The bundled automatic helper is not a cross-platform startup mechanism.
 
+The architecture-metrics proof uses a separate deterministic 34-LOC project.
+It requires the restricted model to load the skill, call `metrics` for the
+project and most-complex unit, and report exact LOC, cyclomatic maximum, and
+instability values. Raw source, search, shell, and write tools remain forbidden:
+
+```bash
+python scripts/bootstrap_vllm_codebase_skill_test.py --probe metrics --use-running-server
+```
+
+Use `--probe metrics --start-vllm --max-model-len 24576` for the cached macOS
+auto-start path when no endpoint is already running.
+
 ## Migration to 2.0
 
 `delphi_lsp` is the only supported import namespace. Update imports directly;

{python_delphi_lsp-2.0.0 → python_delphi_lsp-2.0.2}/delphi_lsp/__init__.py

@@ -59,6 +59,17 @@ from .project_indexer import (
     UnitInfo,
     UnitParsedHook,
 )
+from .metrics import (
+    CyclomaticMetrics,
+    HalsteadMetrics,
+    LineMetrics,
+    MetricProblem,
+    ProjectMetrics,
+    RoutineComplexity,
+    UnitMetrics,
+    analyze_project,
+    analyze_unit,
+)
 
 __all__ = [
     '__version__',
@@ -134,6 +145,15 @@ __all__ = [
     'IncludeFileInfo',
     'GetUnitSyntaxHook',
     'UnitParsedHook',
+    'MetricProblem',
+    'LineMetrics',
+    'HalsteadMetrics',
+    'RoutineComplexity',
+    'CyclomaticMetrics',
+    'UnitMetrics',
+    'ProjectMetrics',
+    'analyze_unit',
+    'analyze_project',
     'dumps',
     'loads',
 ]

python_delphi_lsp-2.0.2/delphi_lsp/_version.py

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

{python_delphi_lsp-2.0.0 → python_delphi_lsp-2.0.2}/delphi_lsp/agent_cli.py

@@ -44,6 +44,7 @@ def build_parser() -> argparse.ArgumentParser:
             "implementation",
             "references",
             "problems",
+            "metrics",
         ],
     )
     view.add_argument("--query", default="")
@@ -66,11 +67,19 @@ def build_parser() -> argparse.ArgumentParser:
 
     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 plugin.")
+    opencode_install = opencode_commands.add_parser(
+        "install", help="Install the package-named skill, Markdown agent, and OpenCode plugin."
+    )
     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.add_argument(
+        "--write-agent",
+        "--write-config",
+        dest="write_config",
+        action="store_true",
+        help="Deprecated compatibility option; the Markdown agent is always installed and opencode.json is never touched.",
+    )
     opencode_install.set_defaults(func=_opencode_install)
 
     worker = subcommands.add_parser("worker", help="Serve Protocol v2 NDJSON requests.")
@@ -138,7 +147,7 @@ def _skill_install(args: argparse.Namespace) -> None:
 
 
 def _opencode_install(args: argparse.Namespace) -> None:
-    skill_path, plugin_path, config_path = install_opencode_support(
+    skill_path, plugin_path, agent_path = install_opencode_support(
         args.target,
         python_executable=args.python,
         force=args.force,
@@ -146,8 +155,7 @@ def _opencode_install(args: argparse.Namespace) -> None:
     )
     print(skill_path)
     print(plugin_path)
-    if config_path is not None:
-        print(config_path)
+    print(agent_path)
 
 
 def _worker(args: argparse.Namespace) -> None:

{python_delphi_lsp-2.0.0 → python_delphi_lsp-2.0.2}/delphi_lsp/agent_context.py

@@ -18,14 +18,16 @@ from .agent_protocol import (
     make_target_id,
     paginate_items,
 )
+from .agent_metrics import build_workspace_metrics, project_metric_item, unit_metric_item
 from .agent_relations import ProjectRelationIndex, RelationTarget
-from .agent_workspace import AgentUnit, AgentWorkspace
+from .agent_workspace import AgentWorkspace, unit_display_path, unit_source_path, unit_target_id
 from .consts import AttributeName, SyntaxNodeType
 from .lsp_server import build_outline_semantic_model, multiline_string_block_end
 from .nodes import CompoundSyntaxNode, SyntaxNode
 from .parser import DelphiParser
 from .semantic import Scope, ScopeKind, Symbol, SymbolKind
 from .source_reader import read_source_text
+from .metrics import ProjectMetrics
 
 
 _ROUTINE_KINDS = frozenset(
@@ -238,6 +240,8 @@ class AgentContext:
         self._last_revision = workspace.workspace_revision
         self._registry: _Registry | None = None
         self._relation_index: ProjectRelationIndex | None = None
+        self._metrics: ProjectMetrics | None = None
+        self._metrics_revision = ""
 
     @classmethod
     def open(
@@ -270,6 +274,8 @@ class AgentContext:
             self._require_selected_project()
             items = self._problem_items()
             return self._response(parsed, revision, items)
+        if parsed.action == "metrics":
+            return self._handle_metrics(parsed, revision)
         if parsed.action == "focus":
             return self._handle_focus(parsed, revision)
         if parsed.action == "find":
@@ -294,10 +300,14 @@ class AgentContext:
         if current_project_id != previous_project_id:
             self._registry = None
             self._relation_index = None
+            self._metrics = None
+            self._metrics_revision = ""
             self._focus = Focus(project_id=current_project_id) if current_project_id else Focus()
         elif revision != self._last_revision:
             self._registry = None
             self._relation_index = None
+            self._metrics = None
+            self._metrics_revision = ""
         elif self._focus.project_id != current_project_id:
             self._focus = Focus(project_id=current_project_id) if current_project_id else Focus()
         self._last_revision = revision
@@ -323,12 +333,11 @@ class AgentContext:
             return items
 
         for unit in self._workspace.units:
-            source_path = _unit_source_path(self._workspace.root, unit)
-            display_path = _stable_source_display_path(self._workspace.root, unit, source_path)
+            display_path = unit_display_path(self._workspace.root, unit)
             items.append(
                 {
                     "item_type": "unit",
-                    "unit_id": make_target_id("unit", display_path, unit.name),
+                    "unit_id": unit_target_id(self._workspace.root, unit),
                     "name": unit.name,
                     "path": display_path,
                     "has_error": unit.has_error,
@@ -407,6 +416,55 @@ class AgentContext:
             self._focus = Focus(project_id=self._workspace.active_project_id)
         return self._response(request, revision, [self._focus.to_mapping()])
 
+    def _handle_metrics(self, request: AgentRequest, revision: str) -> AgentResponse:
+        if request.detail not in {"summary", "members"}:
+            raise AgentProtocolError(
+                "invalid_detail",
+                "Metrics supports only summary or members detail.",
+            )
+        metrics = self._require_metrics(revision)
+        detail = request.detail == "members"
+        if request.target_id:
+            unit = next(
+                (candidate for candidate in metrics.units if candidate.unit_id == request.target_id),
+                None,
+            )
+            if unit is None:
+                raise AgentProtocolError(
+                    "target_not_found",
+                    f"Target not found: {request.target_id}.",
+                )
+            return self._response(
+                request,
+                revision,
+                [unit_metric_item(unit, detail=detail)],
+                target_id=unit.unit_id,
+            )
+
+        units = metrics.units
+        if request.query:
+            query = request.query.casefold()
+            units = tuple(
+                unit
+                for unit in units
+                if query in unit.name.casefold() or query in unit.path.casefold()
+            )
+            items = [unit_metric_item(unit, detail=detail) for unit in units]
+        else:
+            items = [
+                project_metric_item(metrics),
+                *(unit_metric_item(unit, detail=detail) for unit in units),
+            ]
+        return self._response(request, revision, items)
+
+    def _require_metrics(self, revision: str) -> ProjectMetrics:
+        self._require_selected_project()
+        if self._metrics is not None and self._metrics_revision == revision:
+            return self._metrics
+        self._metrics = build_workspace_metrics(self._workspace)
+        self._metrics_revision = revision
+        return self._metrics
+
     def _require_registry(self, revision: str) -> _Registry:
         project_id = self._require_selected_project()
         if (
@@ -608,8 +666,8 @@ def _build_registry(workspace: AgentWorkspace, project_id: str, revision: str) -
     raw_symbols: list[_RawSymbol] = []
     sources: dict[Path, _SourceDocument] = {}
     for unit in workspace.units:
-        source_path = _unit_source_path(workspace.root, unit)
-        display_path = _stable_source_display_path(workspace.root, unit, source_path)
+        source_path = unit_source_path(workspace.root, unit)
+        display_path = unit_display_path(workspace.root, unit)
         try:
             text = read_source_text(source_path)
         except OSError as exc:
@@ -727,22 +785,6 @@ def _build_registry(workspace: AgentWorkspace, project_id: str, revision: str) -
     )
 
 
-def _unit_source_path(root: Path, unit: AgentUnit) -> Path:
-    path = Path(unit.path)
-    if not path.is_absolute():
-        path = root / path
-    return path.expanduser().resolve()
-
-
-def _stable_source_display_path(root: Path, unit: AgentUnit, source_path: Path) -> str:
-    try:
-        return source_path.relative_to(root).as_posix()
-    except ValueError:
-        unit_component = _stable_path_component(unit.name or source_path.stem)
-        file_component = _stable_path_component(source_path.name)
-        return f"@external/{unit_component}/{file_component}"
-
-
 def _stable_path_component(value: str) -> str:
     normalized = unicodedata.normalize("NFC", value).replace("\\", "_").replace("/", "_")
     return normalized or "unknown"