/*
* std/edit - pure helpers for applying and validating agent-authored text patches.
*/
import { edit_patch_content_hash } from "std/edit/internal"
fn __edit_collapse_ws(text) {
return trim(regex_replace("\\s+", " ", text ?? ""))
}
fn __edit_normalize_line(line) {
return __edit_collapse_ws(line)
}
fn __edit_structural_line(line) {
const compact = __edit_collapse_ws(line)
return regex_replace("\\s+", "", compact)
}
fn __edit_signature(text, structural) {
let lines = []
for line in split(text ?? "", "\n") {
const normalized = if structural {
__edit_structural_line(line)
} else {
__edit_normalize_line(line)
}
if structural && normalized == "" {
continue
}
lines = lines + [normalized]
}
return join(lines, "\n")
}
fn __edit_nonblank_count(lines) {
let count = 0
for line in lines {
if __edit_structural_line(line) != "" {
count = count + 1
}
}
return count
}
fn __edit_start_line(prefix) {
if prefix == "" {
return 0
}
return len(split(prefix, "\n")) - 1
}
fn __edit_region(start_line, end_line_exclusive, old_text, new_text, match_kind) {
const end_line = if end_line_exclusive > start_line {
end_line_exclusive - 1
} else {
start_line
}
return {
start_line: start_line,
end_line: end_line,
end_line_exclusive: end_line_exclusive,
old_line_count: max(end_line_exclusive - start_line, 0),
new_line_count: len(split(new_text ?? "", "\n")),
old_sha256: edit_patch_content_hash(old_text),
new_sha256: edit_patch_content_hash(new_text),
match_kind: match_kind,
}
}
fn __edit_context(prefix, needle, suffix) {
const before_lines = split(prefix, "\n")
const after_lines = split(suffix, "\n")
const before = if len(before_lines) > 2 {
join(before_lines[-2:], "\n")
} else {
prefix
}
const after = if len(after_lines) > 2 {
join(after_lines[:2], "\n")
} else {
suffix
}
return trim(before + needle + after)
}
fn __edit_candidate_contexts(parts, old_text, max_contexts) {
let contexts = []
let prefix = ""
let idx = 0
const limit = max_contexts ?? 3
const needle_lines = max(len(split(old_text ?? "", "\n")), 1)
while idx < len(parts) - 1 && len(contexts) < limit {
prefix = prefix + parts[idx]
const start_line = __edit_start_line(prefix)
contexts = contexts
+ [
{
start_line: start_line,
end_line: start_line + needle_lines - 1,
snippet: __edit_context(prefix, old_text, parts[idx + 1]),
},
]
prefix = prefix + old_text
idx = idx + 1
}
return contexts
}
fn __edit_line_candidate_contexts(text, candidates, max_contexts) {
const lines = split(text ?? "", "\n")
let contexts = []
const limit = max_contexts ?? 3
let idx = 0
while idx < len(candidates) && len(contexts) < limit {
const candidate = candidates[idx]
const start_line = candidate.start_line
const end_line_exclusive = candidate.end_line_exclusive
const prefix_start = max(start_line - 2, 0)
const suffix_end = min(end_line_exclusive + 2, len(lines))
const snippet = trim(join(lines[prefix_start:suffix_end], "\n"))
contexts = contexts
+ [{start_line: start_line, end_line: end_line_exclusive - 1, snippet: snippet}]
idx = idx + 1
}
return contexts
}
fn __edit_error(code, message, text, old_text, new_text, fields = nil) {
const base = {
ok: false,
changed: false,
error_code: code,
message: message,
patched: text,
before_sha256: edit_patch_content_hash(text),
after_sha256: edit_patch_content_hash(text),
old_sha256: edit_patch_content_hash(old_text),
new_sha256: edit_patch_content_hash(new_text),
errors: [{code: code, message: message}],
warnings: [],
changed_regions: [],
provenance: {module: "std/edit"},
}
return base.merge(fields ?? {})
}
fn __edit_lazy_placeholder_patterns() {
return [
"(?im)^\\s*//\\s*\\.\\.\\.?\\s*(rest|remaining|existing|implementation|code|omit)",
"(?im)^\\s*//\\s*TODO:?\\s*(implement|fill|add|complete)",
"(?im)^\\s*#\\s*\\.\\.\\.?\\s*(rest|remaining|existing|implementation|code)",
"(?im)^\\s*/\\*\\s*\\.\\.\\.?\\s*\\*/\\s*$",
"(?im)^\\s*//\\s*\\.\\.\\.\\s*$",
"(?im)^\\s*#\\s*\\.\\.\\.\\s*$",
"(?im)^\\s*pass\\s*#\\s*\\.\\.\\.",
]
}
fn __edit_lazy_placeholder_phrases() {
return ["unchanged", "omitted for brevity", "same as before", "rest of the file", "remaining code"]
}
fn __edit_lazy_match_count(text) {
const body = text ?? ""
if body == "" {
return 0
}
let total = 0
for line in split(body, "\n") {
const t = lowercase(trim(line))
if t == "..." || t == "…" {
total = total + 1
}
}
for pattern in __edit_lazy_placeholder_patterns() {
const matches = regex_match(pattern, body) ?? []
total = total + len(matches)
}
const lowered = lowercase(body)
for phrase in __edit_lazy_placeholder_phrases() {
if contains(lowered, phrase) {
total = total + 1
}
}
return total
}
fn __edit_has_lazy_placeholder(new_text) {
return __edit_lazy_match_count(new_text) > 0
}
fn __edit_guardrails(old_text, new_text, options) {
const opts = options ?? {}
if old_text == "" && !(opts?.allow_empty_old_text ?? false) {
return {code: "empty_old_text", message: "old_text must not be empty"}
}
if old_text == new_text && !(opts?.allow_noop ?? false) {
return {code: "no_op", message: "patch does not change the selected text"}
}
if __edit_collapse_ws(old_text) == __edit_collapse_ws(new_text)
&& old_text != new_text
&& !(opts?.allow_whitespace_only ?? false) {
return {code: "whitespace_only", message: "patch changes only whitespace"}
}
if __edit_has_lazy_placeholder(new_text) && !(opts?.allow_lazy_placeholders ?? false) {
return {code: "lazy_placeholder", message: "patch contains an omission or unchanged-content placeholder"}
}
const old_len = len(old_text)
const new_len = len(new_text)
const growth = new_len - old_len
const max_growth_bytes = opts?.max_growth_bytes ?? 20000
if max_growth_bytes != nil && growth > max_growth_bytes {
return {code: "excessive_growth", message: "patch grows selected text by more than max_growth_bytes"}
}
const max_growth_ratio = opts?.max_growth_ratio ?? 8
if max_growth_ratio != nil && growth > 1024 && new_len > old_len * max_growth_ratio {
return {code: "excessive_growth", message: "patch grows selected text by more than max_growth_ratio"}
}
return nil
}
fn __edit_success(
text,
patched,
old_text,
new_text,
match_kind,
start_line,
end_line_exclusive,
options,
) {
const before_hash = edit_patch_content_hash(text)
const after_hash = edit_patch_content_hash(patched)
const expected_region = __edit_region(start_line, end_line_exclusive, old_text, new_text, match_kind)
return {
ok: true,
changed: text != patched,
patched: patched,
match_kind: match_kind,
start_line: expected_region.start_line,
end_line: expected_region.end_line,
end_line_exclusive: expected_region.end_line_exclusive,
expected_region: expected_region,
changed_regions: edit_changed_regions(text, patched),
before_sha256: before_hash,
after_sha256: after_hash,
old_sha256: edit_patch_content_hash(old_text),
new_sha256: edit_patch_content_hash(new_text),
errors: [],
warnings: [],
provenance: {
module: "std/edit",
helper: "edit_apply_old_new_patch",
match_kind: match_kind,
before_sha256: before_hash,
after_sha256: after_hash,
caller: options?.provenance,
},
}
}
fn __edit_splice_raw(text, start_line, end_line_exclusive, new_text) {
const lines = split(text ?? "", "\n")
let out = []
if start_line > 0 {
out = out + lines[:start_line]
}
if (new_text ?? "") != "" {
out = out + split(new_text ?? "", "\n")
}
if end_line_exclusive < len(lines) {
out = out + lines[end_line_exclusive:]
}
return join(out, "\n")
}
fn __edit_has_distinctive_token(line, min_chars) {
const chars = min_chars ?? 4
if chars <= 0 {
return true
}
const tokens = regex_match("[A-Za-z0-9_]+", line ?? "") ?? []
for token in tokens {
if len(token) >= chars {
return true
}
}
return false
}
fn __edit_structural_anchors_ok(old_text, options) {
const opts = options ?? {}
const min_lines = opts?.structural_min_nonblank_lines ?? 3
const anchor_chars = opts?.structural_anchor_chars ?? 4
const anchor_mode = lowercase(opts?.structural_require_anchored_lines ?? "both")
const needle_lines = split(old_text ?? "", "\n")
let nonblank_lines = []
for line in needle_lines {
if __edit_structural_line(line) != "" {
nonblank_lines = nonblank_lines + [line]
}
}
if len(nonblank_lines) < min_lines {
return false
}
if anchor_mode == "none" || anchor_chars <= 0 {
return true
}
const first = nonblank_lines[0] ?? ""
const last = nonblank_lines[len(nonblank_lines) - 1] ?? ""
const first_ok = __edit_has_distinctive_token(first, anchor_chars)
const last_ok = __edit_has_distinctive_token(last, anchor_chars)
if anchor_mode == "either" {
return first_ok || last_ok
}
return first_ok && last_ok
}
fn __edit_line_candidates(text, old_text, structural, options) {
const lines = split(text ?? "", "\n")
let candidates = []
const target = __edit_signature(old_text, structural)
if target == "" {
return candidates
}
if !structural {
const width = len(split(old_text ?? "", "\n"))
let start = 0
while start + width <= len(lines) {
const segment = join(lines[start:start + width], "\n")
if __edit_signature(segment, false) == target {
candidates = candidates + [{start_line: start, end_line_exclusive: start + width, text: segment}]
}
start = start + 1
}
return candidates
}
if !__edit_structural_anchors_ok(old_text, options) {
return candidates
}
const target_count = __edit_nonblank_count(split(old_text ?? "", "\n"))
let start = 0
while start < len(lines) {
if __edit_structural_line(lines[start]) == "" {
start = start + 1
continue
}
let end = start
let nonblank = 0
while end < len(lines) && nonblank < target_count {
if __edit_structural_line(lines[end]) != "" {
nonblank = nonblank + 1
}
end = end + 1
}
if nonblank == target_count {
while end < len(lines) && __edit_structural_line(lines[end]) == "" {
end = end + 1
}
const segment = join(lines[start:end], "\n")
if __edit_signature(segment, true) == target {
candidates = candidates + [{start_line: start, end_line_exclusive: end, text: segment}]
}
}
start = start + 1
}
return candidates
}
fn __edit_apply_line_candidate(text, old_text, new_text, match_kind, candidates, options) {
if len(candidates) == 0 {
return nil
}
const opts = options ?? {}
if len(candidates) > 1 {
return __edit_error(
"ambiguous_match",
"old_text matched multiple normalized regions",
text,
old_text,
new_text,
{
candidate_count: len(candidates),
match_kind: match_kind,
candidate_contexts: __edit_line_candidate_contexts(text, candidates, opts?.max_candidate_contexts),
},
)
}
const candidate = candidates[0]
const patched = __edit_splice_raw(text, candidate.start_line, candidate.end_line_exclusive, new_text)
const result = __edit_success(
text,
patched,
candidate.text,
new_text,
match_kind,
candidate.start_line,
candidate.end_line_exclusive,
opts,
)
if match_kind == "structural" || match_kind == "line" {
return result.merge({whitespace_explanation: edit_explain_whitespace_difference(old_text, candidate.text)})
}
return result
}
/**
* Apply one old/new anchored patch to text.
*
* Returns `{ok, changed, patched, match_kind, start_line, end_line,
* before_sha256, after_sha256, changed_regions, errors, warnings, provenance}`.
* Matching is exact first by default, then whitespace-normalized line matching,
* then structural matching that ignores blank lines and whitespace.
*
* Structural matches are conservative by default: the needle must contain at
* least `structural_min_nonblank_lines` (3) non-blank lines, and both the
* first and last non-blank anchor lines must carry a distinctive token of at
* least `structural_anchor_chars` (4) alphanumeric characters. Relax with
* `structural_require_anchored_lines: "either"` or `"none"` only when callers
* have a host-side validator that can re-check the result. Pass
* `strip_line_numbers: true` to pre-strip ` N | ` line-number prefixes from
* `old_text` when the model pasted them straight from a numbered file read.
*
* @effects: []
* @errors: []
*/
pub fn edit_apply_old_new_patch(text, old_text, new_text, options = nil) {
const source = text ?? ""
const raw_old = old_text ?? ""
const new = new_text ?? ""
const opts = options ?? {}
const old = if opts?.strip_line_numbers ?? false {
edit_strip_line_number_prefixes(raw_old)
} else {
raw_old
}
const guardrail = __edit_guardrails(old, new, opts)
if guardrail != nil {
return __edit_error(guardrail.code, guardrail.message, source, old, new)
}
const mode = opts?.match ?? "auto"
if mode != "line" && mode != "structural" {
const parts = split(source, old)
if len(parts) == 2 {
const start_line = __edit_start_line(parts[0])
const end_line_exclusive = start_line + len(split(old, "\n"))
return __edit_success(
source,
parts[0] + new + parts[1],
old,
new,
"exact",
start_line,
end_line_exclusive,
opts,
)
}
if len(parts) > 2 {
return __edit_error(
"ambiguous_match",
"old_text matched multiple exact regions",
source,
old,
new,
{
candidate_count: len(parts) - 1,
candidate_contexts: __edit_candidate_contexts(parts, old, opts?.max_candidate_contexts ?? 3),
},
)
}
if mode == "exact" {
return __edit_error("no_match", "old_text did not match exactly", source, old, new)
}
}
if mode == "line" || mode == "auto" {
const line_result = __edit_apply_line_candidate(
source,
old,
new,
"line",
__edit_line_candidates(source, old, false, opts),
opts,
)
if line_result != nil {
return line_result
}
if mode == "line" {
return __edit_error("no_match", "old_text did not match any normalized line region", source, old, new)
}
}
if mode == "structural" || mode == "auto" {
const structural_result = __edit_apply_line_candidate(
source,
old,
new,
"structural",
__edit_line_candidates(source, old, true, opts),
opts,
)
if structural_result != nil {
return structural_result
}
}
return __edit_error("no_match", "old_text did not match any safe patch region", source, old, new)
}
/**
* Splice a half-open 0-based line range and return patch metadata.
*
* @effects: []
* @errors: []
*/
pub fn edit_splice_lines(text, start_line, end_line_exclusive, new_text, options = nil) {
const source = text ?? ""
const lines = split(source, "\n")
const start = start_line ?? 0
const end = end_line_exclusive ?? start
if start < 0 || end < start || end > len(lines) {
return __edit_error(
"invalid_line_range",
"line range must be 0-based, half-open, and inside the text",
source,
"",
new_text ?? "",
)
}
const old = join(lines[start:end], "\n")
const guardrail = __edit_guardrails(old, new_text ?? "", (options ?? {}).merge({allow_empty_old_text: true}))
if guardrail != nil {
return __edit_error(guardrail.code, guardrail.message, source, old, new_text ?? "")
}
const patched = __edit_splice_raw(source, start, end, new_text ?? "")
return __edit_success(source, patched, old, new_text ?? "", "line_splice", start, end, options ?? {})
}
fn __edit_find_resync(before_lines, after_lines, before_index, after_index) {
const window = 80
let distance = 1
while distance <= window {
let before_delta = 0
while before_delta <= distance {
const after_delta = distance - before_delta
const next_before = before_index + before_delta
const next_after = after_index + after_delta
if next_before < len(before_lines)
&& next_after < len(after_lines)
&& before_lines[next_before] == after_lines[next_after] {
return {before_index: next_before, after_index: next_after}
}
before_delta = before_delta + 1
}
distance = distance + 1
}
return {before_index: len(before_lines), after_index: len(after_lines)}
}
fn __edit_hunk(before_start, after_start, before_end, after_end, next_before, next_after) {
return {
start_line: min(before_start, after_start),
end_line: max(before_end, after_end),
end_line_exclusive: max(next_before, next_after),
before_start_line: before_start,
after_start_line: after_start,
before_end_line: before_end,
after_end_line: after_end,
before_line_count: max(before_end - before_start + 1, 0),
after_line_count: max(after_end - after_start + 1, 0),
}
}
/**
* Return deterministic line-level changed-region metadata.
*
* @effects: []
* @errors: []
*/
pub fn edit_changed_regions(before, after) {
const before_lines = split(before ?? "", "\n")
const after_lines = split(after ?? "", "\n")
let regions = []
let before_index = 0
let after_index = 0
while before_index < len(before_lines) || after_index < len(after_lines) {
if before_index < len(before_lines)
&& after_index < len(after_lines)
&& before_lines[before_index] == after_lines[after_index] {
before_index = before_index + 1
after_index = after_index + 1
continue
}
const before_start = before_index
const after_start = after_index
const resync = __edit_find_resync(before_lines, after_lines, before_index, after_index)
const next_before = resync.before_index
const next_after = resync.after_index
regions = regions
+ [__edit_hunk(before_start, after_start, next_before - 1, next_after - 1, next_before, next_after)]
before_index = next_before
after_index = next_after
}
return regions
}
fn __edit_expected_end(region) {
if region?.end_line != nil {
return region.end_line
}
if region?.end_line_exclusive != nil {
return region.end_line_exclusive - 1
}
return region?.start_line ?? 0
}
fn __edit_region_within(actual, expected) {
const expected_start = expected?.start_line ?? 0
const expected_end = __edit_expected_end(expected)
return actual.start_line >= expected_start && actual.end_line <= expected_end
}
/**
* Strip ` N | ` line-number prefixes from raw text when at least 60% of
* non-empty lines carry that shape. Useful preprocessing for old_text strings
* that a model pasted verbatim from a numbered file read; otherwise the text
* never matches because each anchor line has an extra `42 | ` prefix.
*
* The 60% threshold is intentional: a file that legitimately contains one or
* two `N | …` lines (e.g. a docstring example) is left alone.
*
* @effects: []
* @errors: []
*/
pub fn edit_strip_line_number_prefixes(text) {
const raw = text ?? ""
if raw == "" {
return raw
}
const lines = split(raw, "\n")
let non_empty_total = 0
let matching = 0
for line in lines {
if trim(line) == "" {
continue
}
non_empty_total = non_empty_total + 1
if regex_match("^\\s*\\d+\\s*\\| ", line) {
matching = matching + 1
}
}
if non_empty_total == 0 {
return raw
}
if matching * 100 / non_empty_total <= 60 {
return raw
}
let stripped = []
for line in lines {
stripped = stripped + [regex_replace("^\\s*\\d+\\s*\\| ", "", line)]
}
return join(stripped, "\n")
}
fn __edit_count_tab_indent(lines) {
let total = 0
for line in lines {
if (line ?? "").starts_with("\t") {
total = total + 1
}
}
return total
}
fn __edit_count_space_indent(lines) {
let total = 0
for line in lines {
const raw = line ?? ""
if raw == "" || raw.starts_with("\t") {
continue
}
if raw.starts_with(" ") {
total = total + 1
}
}
return total
}
fn __edit_min_indent(lines) {
let smallest = -1
for line in lines {
const raw = line ?? ""
if trim(raw) == "" {
continue
}
const leading = len(raw) - len(regex_replace("^[ \\t]+", "", raw))
if smallest == -1 || leading < smallest {
smallest = leading
}
}
return smallest
}
fn __edit_count_blank_lines(lines) {
let total = 0
for line in lines {
if trim(line ?? "") == "" {
total = total + 1
}
}
return total
}
/**
* Diagnose the dominant whitespace discrepancy between an old_text needle and
* the actual matched span in the source. Hosts log this on fuzzy/structural
* matches so the model can learn from each near-miss.
*
* Returns a short human-readable sentence such as
* `"your old_string used tabs but the file uses spaces"` or
* `"your old_string had 1 extra blank line(s) that the file does not"`.
* Returns `""` when needle and matched are identical or no dominant cause is
* detectable.
*
* @effects: []
* @errors: []
*/
pub fn edit_explain_whitespace_difference(needle, matched) {
const needle_text = needle ?? ""
const matched_text = matched ?? ""
if needle_text == matched_text {
return ""
}
const needle_lines = split(needle_text, "\n")
const matched_lines = split(matched_text, "\n")
const needle_tabs = __edit_count_tab_indent(needle_lines)
const needle_spaces = __edit_count_space_indent(needle_lines)
const matched_tabs = __edit_count_tab_indent(matched_lines)
const matched_spaces = __edit_count_space_indent(matched_lines)
if needle_tabs > 0 && matched_tabs == 0 && matched_spaces > 0 {
return "your old_string used tabs but the file uses spaces"
}
if needle_spaces > 0 && matched_spaces == 0 && matched_tabs > 0 {
return "your old_string used spaces but the file uses tabs"
}
const needle_min = __edit_min_indent(needle_lines)
const matched_min = __edit_min_indent(matched_lines)
if needle_min != matched_min && needle_min >= 0 && matched_min >= 0 {
return "your old_string's base indent was ${needle_min} but the file's matched block starts at indent ${matched_min}"
}
const needle_blanks = __edit_count_blank_lines(needle_lines)
const matched_blanks = __edit_count_blank_lines(matched_lines)
if needle_blanks != matched_blanks {
const delta = matched_blanks - needle_blanks
if delta > 0 {
return "your old_string was missing ${delta} blank line(s) that the file has"
}
return "your old_string had ${0 - delta} extra blank line(s) that the file does not"
}
return "minor whitespace formatting (exact cause not pinpointed)"
}
/**
* Detect whether a whole-file edit looks like a lazy truncation: a file with
* at least `min_old_lines` (10) lines shrunk below `min_keep_pct` (35%) of
* its original line count *and* the new content still contains at least one
* lazy placeholder.
*
* Returns `{ok, lazy, error_code, message, old_lines, new_lines, lazy_hits,
* provenance}`. `ok` is true when the edit is sound; false when the
* shrinkage + placeholder shape is present. Distinct from
* `edit_apply_old_new_patch`'s `lazy_placeholder` guardrail, which fires on
* any placeholder in the patch region — this one is for whole-file rewrites
* where placeholders by themselves are not a signal.
*
* @effects: []
* @errors: []
*/
pub fn edit_check_lazy_truncation(old_content, new_content, options = nil) {
const opts = options ?? {}
const {min_old_lines = 10, min_keep_pct = 35} = opts ?? {}
const old_text = old_content ?? ""
const new_text = new_content ?? ""
const old_lines = len(split(old_text, "\n"))
const new_lines = len(split(new_text, "\n"))
const lazy_hits = __edit_lazy_match_count(new_text)
const provenance = {
module: "std/edit",
helper: "edit_check_lazy_truncation",
before_sha256: edit_patch_content_hash(old_text),
after_sha256: edit_patch_content_hash(new_text),
caller: opts?.provenance,
}
const neutral = {
ok: true,
lazy: false,
error_code: nil,
message: "",
old_lines: old_lines,
new_lines: new_lines,
lazy_hits: lazy_hits,
provenance: provenance,
}
if old_lines < min_old_lines {
return neutral
}
const threshold = old_lines * min_keep_pct / 100
if new_lines > threshold {
return neutral
}
if lazy_hits == 0 {
return neutral
}
return {
ok: false,
lazy: true,
error_code: "lazy_truncation",
message: "lazy edit: file was truncated from ${old_lines} to ${new_lines} lines with placeholder comments — provide the complete implementation",
old_lines: old_lines,
new_lines: new_lines,
lazy_hits: lazy_hits,
provenance: provenance,
}
}
/**
* Validate that before/after text differs only inside expected line regions.
* Expected regions use inclusive `end_line` or half-open `end_line_exclusive`.
*
* @effects: []
* @errors: []
*/
pub fn edit_validate_changed_regions(before, after, expected_regions, options = nil) {
const actual = edit_changed_regions(before ?? "", after ?? "")
const expected = expected_regions ?? []
let errors = []
for region in actual {
let matched = false
for expected_region in expected {
if __edit_region_within(region, expected_region) {
matched = true
break
}
}
if !matched {
errors = errors
+ [
{
code: "unexpected_changed_region",
message: "changed region falls outside expected patch range",
region: region,
},
]
}
}
return {
ok: len(errors) == 0,
actual_regions: actual,
expected_regions: expected,
errors: errors,
error_codes: errors.map({ error -> error.code }),
warnings: [],
provenance: {
module: "std/edit",
helper: "edit_validate_changed_regions",
before_sha256: edit_patch_content_hash(before ?? ""),
after_sha256: edit_patch_content_hash(after ?? ""),
caller: options?.provenance,
},
}
}
/**
* Locate one or more AST nodes via a Tree-Sitter query and replace each
* match's bytes with `replacement`. The byte splice preserves leading
* indentation, trailing trivia, and any whitespace outside the matched
* span — so this is the precise alternative to freeform text patching
* for "change this function body" / "rename this call" style edits.
*
* The query must declare at least one capture; the capture named by
* `target_capture` (default `"target"`) is the replaceable span.
* Single-capture queries accept any capture name.
*
* Multi-match policy via `select`:
*
* - `"unique"` (default) requires exactly one match; else `ambiguous`.
* - `"first"` picks the lowest byte offset.
* - `"all"` rewrites every match.
* - `"nth"` plus `nth: N` picks the 1-based index in document order.
*
* When `validate` is true (default) the rewritten source is re-parsed and
* any tree-sitter ERROR/MISSING node aborts the edit with
* `result == "syntax_error"`. When `dry_run` is true the file is left
* untouched but the response still carries the `preview` text the splice
* would produce.
*
* Reads and writes route through staged-fs (#1722) when a `session_id` is
* supplied so the edit is atomic alongside siblings.
*
* @effects: [host, fs]
* @errors: [backend]
* @api_stability: experimental
* @example: edit_apply_node({path: "src/lib.rs", query: query, replacement: "{ 42 }"})
*/
pub fn edit_apply_node(params) {
const raw = hostlib_ast_apply_node(params ?? {})
const payload = raw ?? {}
const provenance = {
module: "std/edit",
helper: "edit_apply_node",
path: payload?.path,
dry_run: payload?.dry_run ?? false,
before_sha256: payload?.before_sha256,
after_sha256: payload?.after_sha256,
caller: params?.provenance,
}
return {
ok: (payload?.result ?? "") == "applied",
applied: payload?.applied ?? false,
result: payload?.result ?? "no_match",
path: payload?.path,
dry_run: payload?.dry_run ?? false,
match_count: payload?.match_count ?? 0,
edits: payload?.edits ?? [],
spans: payload?.spans ?? [],
preview: payload?.preview,
before_sha256: payload?.before_sha256,
after_sha256: payload?.after_sha256,
query: payload?.query,
target_capture: payload?.target_capture,
details: payload?.details,
fallback_suggestion: payload?.fallback_suggestion,
error_row: payload?.error_row,
error_column: payload?.error_column,
errors: [],
warnings: [],
provenance: provenance,
}
}
/**
* Splice `content` into `path` relative to a unique AST anchor located
* by a Tree-Sitter query.
*
* Companion to `edit_apply_node`: where `apply_node` *replaces* a span,
* this primitive *adds* a sibling or child node. `position` picks the
* slot:
*
* - `"before"` / `"after"` — insert a sibling at the anchor's indent
* depth (e.g. "add a new function after this one").
* - `"first_child"` / `"last_child"` — insert inside the anchor at the
* inferred child depth (e.g. "append a new test to this mod").
*
* The query MUST match exactly one node — multi-match returns
* `result == "ambiguous"`. Tighten queries with `(#eq? @name "…")`
* predicates to disambiguate.
*
* Each line of `content` is re-indented to the target depth unless
* `reindent: false` is supplied. The indent unit is detected from the
* file's existing indentation (tabs win when any line starts with one,
* else the smallest non-zero leading-space run), falling back to a
* language default. Override explicitly via `indent: " "`.
*
* When `validate` is true (default) the rewritten source is re-parsed
* and any tree-sitter ERROR/MISSING node aborts the edit with
* `result == "syntax_error"`. When `dry_run` is true the file is left
* untouched but the response still carries the `preview` text the
* splice would produce. Reads and writes route through staged-fs
* (#1722) when a `session_id` is supplied so the insert is atomic
* alongside siblings.
*
* @effects: [host, fs]
* @errors: [backend]
* @api_stability: experimental
* @example: edit_insert_at_anchor({path: "src/lib.rs", query: q, position: "after", content: "fn beta() {}"})
*/
pub fn edit_insert_at_anchor(params) {
const raw = hostlib_ast_insert_at_anchor(params ?? {})
const payload = raw ?? {}
const provenance = {
module: "std/edit",
helper: "edit_insert_at_anchor",
path: payload?.path,
position: payload?.position,
dry_run: payload?.dry_run ?? false,
before_sha256: payload?.before_sha256,
after_sha256: payload?.after_sha256,
caller: params?.provenance,
}
return {
ok: (payload?.result ?? "") == "applied",
applied: payload?.applied ?? false,
result: payload?.result ?? "no_match",
path: payload?.path,
dry_run: payload?.dry_run ?? false,
position: payload?.position,
insertion_byte: payload?.insertion_byte,
indent: payload?.indent,
inserted_text: payload?.inserted_text,
anchor: payload?.anchor,
anchors: payload?.anchors ?? [],
match_count: payload?.match_count ?? 0,
preview: payload?.preview,
before_sha256: payload?.before_sha256,
after_sha256: payload?.after_sha256,
query: payload?.query,
target_capture: payload?.target_capture,
details: payload?.details,
fallback_suggestion: payload?.fallback_suggestion,
error_row: payload?.error_row,
error_column: payload?.error_column,
errors: [],
warnings: [],
provenance: provenance,
}
}
/**
* Run one Tree-Sitter `query` -> `replacement` codemod over every file in
* `paths`, returning a per-file preview plus a roll-up `summary`.
*
* This is the multi-file sibling of `edit_apply_node`: each file goes
* through the same format-preserving byte-splice, so indentation and
* trivia outside each matched span survive untouched.
*
* `params` is a dict:
*
* - `paths`: non-empty list of files. Duplicates are collapsed.
* - `query`: Tree-Sitter S-expression with at least one capture; the
* `target_capture` (default `"target"`) capture is the replaceable span.
* - `replacement` (alias `fix`): text spliced in for each selected node.
* - `select`: per-file multi-match policy (`"unique"` default, or
* `"first" | "all" | "nth"` with `nth`).
* - `language`: optional grammar hint applied to every path.
* - `validate`: re-parse each edit and reject ERROR/MISSING nodes (default).
*
* **Dry-run is the default.** A plain call previews edits across every file
* without touching disk; pass `dry_run: false` to apply. A failure on one
* file (no match, a query invalid for that grammar, a post-edit syntax
* error, an unreadable path) is recorded as that file's `result` and does
* not abort the batch. Re-running an applied codemod reports zero further
* changes (`files_changed: 0`), which is the A6 idempotency hook.
*
* `ok` is true when no file failed. Each `files` entry carries `path`,
* `result`, `match_count`, `changed`, `before_sha256`, `after_sha256`, and
* `preview`; `summary` rolls up `files_total / files_matched /
* files_changed / files_written / files_failed / match_count_total`.
*
* @effects: [host, fs]
* @errors: [backend]
* @api_stability: experimental
* @example: edit_batch_apply({paths: ["a.rs", "b.rs"], query: q, replacement: "{ 0 }"})
*/
pub fn edit_batch_apply(params) {
const payload = hostlib_ast_batch_apply(params ?? {}) ?? {}
return payload
.merge(
{
ok: (payload?.summary?.files_failed ?? 1) == 0,
provenance: {module: "std/edit", helper: "edit_batch_apply", caller: params?.provenance},
},
)
}