Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions devcapsule-src/devcapsule/configuration/listing.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
- ``access``: host access and the base and vendor consents, from the
authorization review;
- ``env``: the environment the project asks for and the checkout saved;
- ``source``: a wrapped source's declared toolchain and fork or learning intent;
- ``value``, ``binding``, ``secret``: the project's declared values and the
selected components' state slots and secret inputs.

Expand Down
2 changes: 1 addition & 1 deletion devcapsule-src/devcapsule/configuration/owner_commands.py
Original file line number Diff line number Diff line change
Expand Up @@ -410,7 +410,7 @@ def declare_source(start: Path, path: str, *, upstream: str | None = None, java:
"""
root, manifest, _lock, _matrix = _project(start, check_resolutions=False)
path = source_path(path, field_name="source path")
if upstream is not None and (not upstream.strip() or "\x00" in upstream):
if upstream is not None and (not isinstance(upstream, str) or not upstream.strip() or "\x00" in upstream):
raise ProjectConfigurationError("The upstream is the upstream repository's URL; it cannot be blank.")
if java is not None:
java = java_line(java, field_name="java line")
Expand Down
93 changes: 67 additions & 26 deletions devcapsule-src/devcapsule/wrap.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,11 +23,14 @@
from __future__ import annotations

from dataclasses import dataclass
import html
from pathlib import Path
import re
import shutil
import subprocess
from typing import Any, Mapping, TextIO

from devcapsule.compat import CliError
from devcapsule.configuration.file_formats import ProjectConfigurationError
from devcapsule.configuration.manifest import current_manifest
from devcapsule.configuration.manifest_document import Recommendations
Expand Down Expand Up @@ -100,21 +103,29 @@ def wrap_project(request: WrapRequest, *, input_stream: TextIO | None = None, ou
"""Wrap one repository into the project at ``request.directory``; see the module docstring for the steps."""
root = request.directory.expanduser().resolve()
_require_repository_root(root)
path = source_path(request.path or _repository_name(request.url), field_name="--path")
path = source_path(request.path if request.path is not None else _repository_name(request.url), field_name="--path")
# Validate source metadata before Git or initialization writes anything.
WrappedSources.read({"sources": {path: {"upstream": request.upstream} if request.upstream is not None else {}}})
submodule_action = _add_submodule(root, request.url, path)
detection = detect(root / path)
manifest_path = root / ".devcapsule" / "devcapsule.toml"
initialized: InitializeReport | None = None
capability_lines: list[str] = []
needed = detection.capabilities if detection is not None else ()
if not manifest_path.is_file():
initialized = initialize_project(
InitializeRequest(directory=root, require=needed, ide=request.ide, agents=request.agents,
project_name=request.project_name, slug=request.slug, creator=request.creator,
project_mount=request.project_mount, answers=request.answers,
allow_unverified=request.allow_unverified, interactive=request.interactive),
input_stream=input_stream, output_stream=output_stream,
)
try:
initialized = initialize_project(
InitializeRequest(directory=root, require=needed, ide=request.ide, agents=request.agents,
project_name=request.project_name, slug=request.slug, creator=request.creator,
project_mount=request.project_mount, answers=request.answers,
allow_unverified=request.allow_unverified, interactive=request.interactive),
input_stream=input_stream, output_stream=output_stream,
)
except (CliError, KeyboardInterrupt) as exc:
raise ProjectConfigurationError(
f"Initialization did not finish: {exc or 'interrupted'}. The submodule {path} remains. "
"Rerun wrap with the missing answers; if configuration files already exist, complete 'project init' first."
) from exc
else:
manifest = current_manifest(load_toml(manifest_path), manifest_path).document()
declared = {name.partition(">=")[0] for name in manifest["capabilities"].get("required", [])}
Expand Down Expand Up @@ -155,14 +166,25 @@ def _repository_name(url: str) -> str:
def _add_submodule(root: Path, url: str, path: str) -> str:
"""Add the submodule unless the same one already stands at ``path``; embed its Git directory either way."""
target = root / path
registered = _git(root, "config", "-f", ".gitmodules", f"submodule.{path}.url", check=False)
if target.exists():
if registered.returncode == 0 and registered.stdout.strip() == url:
action = f"Kept the submodule {path}, already added from {url}"
else:
raise ProjectConfigurationError(f"{target} exists and is not a submodule added from {url}; give another --path.")
if any(part.is_symlink() for part in (target, *target.parents) if part != root and root in part.parents):
raise ProjectConfigurationError(f"{target} passes through a symlink; give a path inside the wrapper without symlinks.")
registered = _registered_url(root, path)
if registered is not None:
if registered != url:
raise ProjectConfigurationError(f"{path} is registered with a different URL ({registered}); give another --path.")
if not (target / ".git").exists():
_git(root, "submodule", "update", "--init", "--", path)
action = f"Kept the submodule {path}, already added from {url}"
elif target.exists():
raise ProjectConfigurationError(f"{target} exists and is not a submodule added from {url}; inspect any partial clone, then give another --path.")
else:
_git(root, "submodule", "add", "--", url, path)
try:
_git(root, "submodule", "add", "--", url, path)
except ProjectConfigurationError as exc:
raise ProjectConfigurationError(
f"{exc}. Git may have left a partial submodule at {path}; no files were removed. "
"Rerun wrap if the submodule was registered; otherwise inspect the path, .gitmodules and Git's modules directory before retrying."
) from exc
action = f"Added the submodule {path} from {url}"
return action + ("; its Git directory is embedded in the tree." if _embed_git_directory(root, path) else ".")

Expand All @@ -178,8 +200,9 @@ def _embed_git_directory(root: Path, path: str) -> bool:
gitfile = root / path / ".git"
if gitfile.is_dir():
return False
git_dir = Path(_git(root, "rev-parse", "--path-format=absolute", "--git-dir").stdout.strip())
module = git_dir / "modules" / path
# Ask the submodule: its registered name can differ from its path, and
# a linked wrapper worktree has its own Git directory.
module = Path(_git(root / path, "rev-parse", "--absolute-git-dir").stdout.strip())
if not module.is_dir():
raise ProjectConfigurationError(f"The submodule's Git directory is neither at {gitfile} nor at {module}; cannot embed it.")
gitfile.unlink()
Expand All @@ -205,7 +228,7 @@ def _write_guidance(root: Path, manifest: Mapping[str, Any]) -> tuple[str, ...]:
lines: list[str] = []
for name, text in (("AGENTS.md", render_agents(manifest, sources, origins)), ("README.md", render_readme(manifest, sources, origins))):
target = root / name
if target.is_file() and not target.read_text(encoding="utf-8").startswith(GUIDANCE_MARKER):
if target.is_file() and target.read_text(encoding="utf-8").splitlines()[:1] != [GUIDANCE_MARKER]:
lines.append(f"Kept your {name}; it does not carry the wrap marker. Add the wrapped sources to it yourself.")
continue
target.write_text(text, encoding="utf-8")
Expand All @@ -214,8 +237,26 @@ def _write_guidance(root: Path, manifest: Mapping[str, Any]) -> tuple[str, ...]:


def _origin(root: Path, path: str) -> str:
completed = _git(root, "config", "-f", ".gitmodules", f"submodule.{path}.url", check=False)
return completed.stdout.strip() if completed.returncode == 0 else "(not in .gitmodules)"
return _registered_url(root, path) or "(not in .gitmodules)"


def _registered_url(root: Path, path: str) -> str | None:
"""Find a submodule by its path, which need not equal its Git section name."""
completed = _git(root, "config", "--null", "-f", ".gitmodules", "--get-regexp", r"^submodule\..*\.path$", check=False)
for record in completed.stdout.split("\x00"):
key, separator, value = record.partition("\n")
if separator and value == path:
url = _git(root, "config", "--null", "-f", ".gitmodules", key[:-4] + "url", check=False)
# A registered path without a URL must not become a new add.
return url.stdout.removesuffix("\x00") if url.returncode == 0 else ""
return None


def _markdown_data(value: str) -> str:
"""Keep external text on one line and prevent Markdown or HTML structure."""
value = value.replace("\\", "\\\\").replace("\n", r"\n").replace("\r", r"\r").replace("\t", r"\t")
value = html.escape(value, quote=True)
return re.sub(r"[`*_[\]{}()#!|]", lambda match: f"&#{ord(match.group())};", value)


def _java_lines(source: WrappedSource) -> list[str]:
Expand All @@ -228,15 +269,15 @@ def _java_lines(source: WrappedSource) -> list[str]:

def render_agents(manifest: Mapping[str, Any], sources: WrappedSources, origins: Mapping[str, str]) -> str:
"""The wrapper's AGENTS.md: agent-neutral, regenerated from the manifest."""
name = manifest["project"]["name"]
name = _markdown_data(manifest["project"]["name"])
lines = [GUIDANCE_MARKER, f"# Agent Instructions: {name}", "",
"This repository is a DevCapsule wrapper. It holds the DevCapsule configuration under",
"`.devcapsule/` and foreign repositories as Git submodules. The code to work on lives in",
"the submodules; the wrapper only sets up the environment around them.", "",
"## Wrapped sources", ""]
for source in sources.entries:
lines.extend([f"### `{source.path}`", "", f"- Origin: {origins.get(source.path, '')}",
f"- Intent: {source.intent}." + (f" Upstream: {source.upstream}." if source.upstream else "")])
lines.extend([f"### {_markdown_data(source.path)}", "", f"- Origin: {_markdown_data(origins.get(source.path, ''))}",
f"- Intent: {source.intent}." + (f" Upstream: {_markdown_data(source.upstream)}." if source.upstream else "")])
lines.extend(_java_lines(source))
lines.append("")
lines.extend(["## Rules", "",
Expand All @@ -253,7 +294,7 @@ def render_agents(manifest: Mapping[str, Any], sources: WrappedSources, origins:

def render_readme(manifest: Mapping[str, Any], sources: WrappedSources, origins: Mapping[str, str]) -> str:
"""The wrapper's README.md for a person: what this is and how to start."""
name = manifest["project"]["name"]
name = _markdown_data(manifest["project"]["name"])
lines = [GUIDANCE_MARKER, f"# {name}", "",
"A DevCapsule wrapper: the development environment for the repositories below, which",
"are not this repository's own code and carry no DevCapsule configuration of their own.", "",
Expand All @@ -262,8 +303,8 @@ def render_readme(manifest: Mapping[str, Any], sources: WrappedSources, origins:
"An existing clone without the submodules: `git submodule update --init`.", "",
"## Wrapped sources", ""]
for source in sources.entries:
lines.extend([f"### `{source.path}`", "", f"- Origin: {origins.get(source.path, '')}",
f"- Intent: {source.intent}." + (f" Upstream: {source.upstream}." if source.upstream else "")])
lines.extend([f"### {_markdown_data(source.path)}", "", f"- Origin: {_markdown_data(origins.get(source.path, ''))}",
f"- Intent: {source.intent}." + (f" Upstream: {_markdown_data(source.upstream)}." if source.upstream else "")])
lines.extend(_java_lines(source))
lines.append("")
return "\n".join(lines)
58 changes: 49 additions & 9 deletions devcapsule-src/devcapsule/wrap_detection.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,12 +25,25 @@

# Gradle's Java compatibility table (docs.gradle.org/current/userguide/compatibility.html):
# every 8.x and 9.0 run on JDK 17; 9.1 is the first to run on JDK 25.
# A plain Gradle project gets the oldest line its wrapper runs on, which is
# the line most likely to match what the project's authors use.
# Select 17 for 8.x and 9.0, and the capsule's default 25 from 9.1 onward.
# This is a wrapper selection rule, not Gradle's minimum Java requirement.
GRADLE_JAVA_LINES: tuple[tuple[tuple[int, int], str], ...] = (((9, 1), "25"), ((8, 0), "17"))

_GRADLERIO_PATTERN = re.compile(r'edu\.wpi\.first\.GradleRIO["\')]*\s*version\s*\(?\s*["\'](\d{4})')
_DISTRIBUTION_PATTERN = re.compile(r"gradle-(\d+)\.(\d+)")
# Keep strings as whole tokens. A plugin example inside a string must never
# become an executable declaration. Comments are discarded below.
_SCRIPT_TOKEN = re.compile(
"|".join((
r"//[^\n]*", r"/\*.*?\*/", # comments
r"\$/.*?/\$", r"/(?:\\.|[^/\\])*/", # Groovy slashy strings
r'""".*?"""', r"'''.*?'''", # multiline strings
r'"(?:\\.|[^"\\])*"', r"'(?:\\.|[^'\\])*'",
r"[A-Za-z_$][\w$]*", r"[^\s]",
)),
re.DOTALL,
)
_PLUGIN_YEAR = re.compile(r'''(["'])(\d{4})(?:\.[^"']*)?\1''')
_DISTRIBUTION_PROPERTY = re.compile(r"^[ \t]*distributionUrl[ \t]*(?:[=:][ \t]*|[ \t]+)([^\r\n]*)", re.MULTILINE)
_DISTRIBUTION_PATTERN = re.compile(r"/gradle-(\d+)\.(\d+)(?:[.\w-]*)-(?:bin|all)\.zip(?:[?#].*)?$")


@dataclass(frozen=True)
Expand All @@ -54,14 +67,13 @@ def detect(source: Path) -> Detection | None:
if not (source / "gradlew").is_file() or build_script is None:
return None
evidence = [f"Gradle wrapper and {build_script.name}"]
match = _GRADLERIO_PATTERN.search(build_script.read_text(encoding="utf-8", errors="replace"))
if match is not None:
year = match.group(1)
year = _gradlerio_year(build_script.read_text(encoding="utf-8", errors="replace"))
if year is not None:
java = GRADLERIO_JAVA_LINES.get(year)
evidence.append(f"GradleRIO {year}" + (f": WPILib {year} builds with Java {java}" if java else f": no Java line known for WPILib {year}"))
return Detection(("java",), "java-ide", java, tuple(evidence))
gradle = _gradle_java_line(source)
evidence.append(f"Gradle {gradle[0]}: runs on Java {gradle[1]}" if gradle is not None else "the Gradle version is not in gradle-wrapper.properties")
evidence.append(f"Gradle {gradle[0]}: runs on Java {gradle[1]}" if gradle is not None else "no supported Gradle version found in distributionUrl in gradle-wrapper.properties")
return Detection(("java",), "java-ide", gradle[1] if gradle is not None else None, tuple(evidence))


Expand All @@ -70,11 +82,39 @@ def _gradle_java_line(source: Path) -> tuple[str, str] | None:
properties = source / "gradle" / "wrapper" / "gradle-wrapper.properties"
if not properties.is_file():
return None
match = _DISTRIBUTION_PATTERN.search(properties.read_text(encoding="utf-8", errors="replace"))
declarations = _DISTRIBUTION_PROPERTY.findall(properties.read_text(encoding="utf-8", errors="replace"))
match = _DISTRIBUTION_PATTERN.search(declarations[-1].strip()) if declarations else None
if match is None:
return None
version = (int(match.group(1)), int(match.group(2)))
for minimum, line in GRADLE_JAVA_LINES:
if version >= minimum:
return f"{version[0]}.{version[1]}", line
return None


def _gradlerio_year(script: str) -> str | None:
"""Read a literal ``id ... version ...`` declaration, without evaluating Gradle."""
tokens = [match.group() for match in _SCRIPT_TOKEN.finditer(script)
if not match.group().startswith(("//", "/*"))]
for index, token in enumerate(tokens):
if token != "id":
continue
rest = tokens[index + 1:]
if rest[:1] == ["("]:
if len(rest) < 3 or rest[2] != ")":
continue
plugin, rest = rest[1], rest[3:]
elif rest:
plugin, rest = rest[0], rest[1:]
else:
continue
if plugin not in ('"edu.wpi.first.GradleRIO"', "'edu.wpi.first.GradleRIO'") or rest[:1] != ["version"]:
continue
rest = rest[1:]
if rest[:1] == ["("]:
rest = rest[1:]
match = _PLUGIN_YEAR.fullmatch(rest[0]) if rest else None
if match is not None:
return match.group(2)
return None
37 changes: 37 additions & 0 deletions devcapsule-src/tests/test_owner_commands.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,9 @@
from __future__ import annotations

from pathlib import Path
import json
import tomllib
from typing import Any

import pytest

Expand Down Expand Up @@ -384,3 +386,38 @@ def test_declare_source_preview_and_refusals_write_nothing(project: Path) -> Non
with pytest.raises(ProjectConfigurationError, match="upstream"):
owner_commands.declare_source(project, "robot", upstream=" ")
assert manifest_text(project) == before


@pytest.mark.parametrize("fields", [
{"path": ""}, {"path": "../escape"}, {"path": 3},
{"upstream": 3}, {"upstream": "bad\x00url"}, {"upstream": " "},
{"java": 17}, {"java": "0"}, {"java": "17\n"},
])
def test_declare_source_refuses_malformed_inputs_without_touching_files(project: Path, fields: dict[str, Any]) -> None:
manifest_path, lock_path, _ = paths(project)
before = manifest_path.read_bytes(), lock_path.read_bytes()
with pytest.raises(ProjectConfigurationError):
owner_commands.declare_source(project, **{"path": "vendor/robot", **fields})
assert (manifest_path.read_bytes(), lock_path.read_bytes()) == before


def test_sources_survive_other_owner_edits_and_do_not_change_pending_decisions(project: Path, capsys) -> None:
assert cli.main(["project", "--path", str(project), "config", "show", "--json"]) == 0
baseline = json.loads(capsys.readouterr().out)
owner_commands.declare_source(project, 'vendor/robot.code', upstream="https://example.test/up", java="17")
owner_commands.declare_source(project, "notes")
manifest_path, lock_path, _ = paths(project)
manifest_path.write_text(manifest_path.read_text().replace('java = "17"', 'java = "17"\nfuture = { extra = true }'))
sources = load_toml(manifest_path)["sources"]
owner_commands.recommend(project, "memory", "4g")
assert load_toml(manifest_path)["sources"] == sources
lock = lock_path.read_bytes()
owner_commands.declare_source(project, "notes", preview=True)
assert lock_path.read_bytes() == lock
assert cli.main(["project", "--path", str(project), "config", "show", "--json"]) == 0
document = json.loads(capsys.readouterr().out)
assert document["pending"] == baseline["pending"]
assert [row for row in document["rows"] if row["kind"] == "source"] == [
{"kind": "source", "name": "notes", "effective": "no toolchain declared", "source": "project: upstream, read-only", "pending": "", "command": ""},
{"kind": "source", "name": "vendor/robot.code", "effective": "java 17", "source": "project: fork of https://example.test/up", "pending": "", "command": ""},
]
Loading