@smthrs/std 0.0.0-stage → 1.0.0-rc.3

package/src/internal/Match.ts

@@ -0,0 +1,172 @@
+/**
+ * Exact block location, and the pre-image reported when it misses.
+ *
+ * The editing flows locate a caller's block byte-exactly and refuse everything
+ * else. The tolerant cascade this module used to apply — trailing-whitespace
+ * insensitive, then inner-whitespace collapsed — is gone from the *apply* path,
+ * because a match that is not the caller's bytes is an edit the caller never
+ * inspected: on django-11490 a sixteen-space anchor matched inside a
+ * twenty-space line and silently dedented a guard, and on sympy-15380 a
+ * "successful" fuzzy apply corrupted the file it reported editing. Prior art is
+ * `reference/opencode`'s replacer cascade (`tool/edit.ts`), and this is where we
+ * deviate from it deliberately.
+ *
+ * The cascade survives as *diagnosis*. A miss is only expensive when it is
+ * silent: the agent re-reads, re-guesses, and re-misses. {@link nearest} runs
+ * the same loose strategies to find where the caller's block actually sits and
+ * returns that region's real bytes and line range, so the failing cell can
+ * re-anchor from reality inside the same frame rather than buying another one.
+ *
+ * @since 1.0.0
+ */
+
+import { sourceLines } from "./Text.ts"
+
+/**
+ * One located block: the exact source span the needle matched.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Located {
+  readonly start: number
+  readonly end: number
+  readonly startLine: number
+  readonly endLine: number
+}
+
+/**
+ * The real file region nearest a needle that did not match.
+ *
+ * `text` is raw file bytes, never line-number prefixed, so a caller can quote it
+ * back as an anchor without editing it first.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Nearest {
+  readonly startLine: number
+  readonly endLine: number
+  readonly text: string
+}
+
+/**
+ * The 1-based line a byte offset falls on.
+ *
+ * @category matching
+ * @since 1.0.0
+ */
+export const lineAt = (content: string, offset: number): number => {
+  let line = 1
+  for (let index = 0; index < offset && index < content.length; index++) {
+    if (content[index] === "\n") line++
+  }
+  return line
+}
+
+/**
+ * Every byte-exact occurrence of `needle` in `content`.
+ *
+ * @category matching
+ * @since 1.0.0
+ */
+export const locate = (content: string, needle: string): ReadonlyArray<Located> => {
+  const found: Array<Located> = []
+  let cursor = content.indexOf(needle)
+  let line = 1
+  let scanned = 0
+  while (cursor >= 0) {
+    for (let index = scanned; index < cursor; index++) {
+      if (content[index] === "\n") line++
+    }
+    scanned = cursor
+    const startLine = line
+    let endLine = line
+    for (let index = 0; index < needle.length - 1; index++) {
+      if (needle[index] === "\n") endLine++
+    }
+    found.push({ start: cursor, end: cursor + needle.length, startLine, endLine })
+    // Resume past the match, not one byte into it. A caller replaces these spans
+    // in order, so overlapping occurrences are not separately replaceable: in
+    // "aaa" the anchor "aa" is reported once, because consuming the first
+    // occurrence leaves no second one. Scanning by one byte instead reported
+    // both, and the splice wrote the replacement over bytes the first span
+    // already owned.
+    cursor = content.indexOf(needle, cursor + needle.length)
+  }
+  return found
+}
+
+const trimmedRight = (line: string): string => line.replace(/[ \t]+$/, "")
+
+const collapsed = (line: string): string => line.replace(/[ \t]+/g, " ").trim()
+
+const matchByLine = (
+  haystack: ReadonlyArray<string>,
+  wanted: ReadonlyArray<string>,
+  normalize: (line: string) => string
+): number => {
+  const target = wanted.map(normalize)
+  const normalized = haystack.map(normalize)
+  for (let index = 0; index + target.length <= haystack.length; index++) {
+    let matched = true
+    for (let step = 0; step < target.length; step++) {
+      if (normalized[index + step] !== target[step]) {
+        matched = false
+        break
+      }
+    }
+    if (matched) return index
+  }
+  return -1
+}
+
+/**
+ * The real region a failed needle was aiming at, with its line range.
+ *
+ * The loose strategies run in order — trailing whitespace, then collapsed inner
+ * whitespace, then the needle's first non-blank line alone — and the first that
+ * locates a region wins. `undefined` means not even one line of the needle
+ * occurs in the file, which is itself the answer: this is the wrong file.
+ *
+ * @category matching
+ * @since 1.0.0
+ */
+export const nearest = (content: string, needle: string, pad = 3): Nearest | undefined => {
+  const haystack = sourceLines(content)
+  const wanted = [...sourceLines(needle)]
+  while (wanted.length > 0 && wanted[wanted.length - 1] === "") wanted.pop()
+  if (wanted.length === 0) return undefined
+  let at = matchByLine(haystack, wanted, trimmedRight)
+  let span = wanted.length
+  if (at < 0) at = matchByLine(haystack, wanted, collapsed)
+  if (at < 0) {
+    const anchor = wanted.map(collapsed).find((line) => line !== "")
+    if (anchor === undefined) return undefined
+    at = haystack.findIndex((line) => collapsed(line) === anchor)
+    span = 1
+  }
+  if (at < 0) return undefined
+  const from = Math.max(0, at - pad)
+  const to = Math.min(haystack.length, at + span + pad)
+  return { startLine: from + 1, endLine: to, text: haystack.slice(from, to).join("\n") }
+}
+
+/**
+ * The applied region rendered back for inspection: raw bytes, plus its range.
+ *
+ * A bad edit is only expensive when it is invisible. sphinx-7233 lost its
+ * verdict to an in-cell string surgery that captured an `else` branch, and the
+ * model never saw the hunk it had written.
+ *
+ * @category matching
+ * @since 1.0.0
+ */
+export const hunk = (content: string, start: number, end: number, pad = 2): Nearest => {
+  const startLine = lineAt(content, start)
+  const endLine = startLine + Math.max(0, content.slice(start, end).split("\n").length - 1)
+  const haystack = sourceLines(content)
+  const from = Math.max(0, startLine - 1 - pad)
+  const to = Math.min(haystack.length, endLine + pad)
+  return { startLine: from + 1, endLine: to, text: haystack.slice(from, to).join("\n") }
+}

package/src/internal/Paths.ts

@@ -0,0 +1,42 @@
+/**
+ * Path containment checks against a declared effect envelope.
+ *
+ * @since 1.0.0
+ */
+
+import * as Effects from "@smthrs/core/Effects"
+
+const normalize = (path: string): string => {
+  const collapsed = path.replace(/\/+/g, "/")
+  return collapsed.length > 1 ? collapsed.replace(/\/+$/, "") : collapsed
+}
+
+const hasDotSegment = (path: string): boolean => path.split("/").some((segment) => segment === "." || segment === "..")
+
+/**
+ * Whether a path is covered by any entry of a declared read or write set.
+ *
+ * An entry covers itself, everything beneath it when it names a directory,
+ * and everything matched by the prefix-glob subset `/core` supports.
+ *
+ * @category predicates
+ * @since 1.0.0
+ */
+export const withinEnvelope = (declared: ReadonlyArray<string>, path: string): boolean => {
+  const candidate = normalize(path)
+  if (candidate === "" || hasDotSegment(candidate)) return false
+  return declared.some((entry) => {
+    const normalized = normalize(entry)
+    if (normalized === "") return false
+    const envelope = normalized === "/" ? "/**" : normalized
+    return Effects.covers(envelope, candidate) || candidate.startsWith(`${normalized}/`)
+  })
+}
+
+/**
+ * A path without its trailing slashes, so a root compares and joins as one name.
+ *
+ * @category conversions
+ * @since 1.0.0
+ */
+export const withoutTrailingSlash = (path: string): string => path.replace(/\/+$/, "")

package/src/internal/Preserve.ts

@@ -0,0 +1,108 @@
+/**
+ * Per-file atomic replacement that preserves permission bits and ownership.
+ * The sibling is complete before rename; no crash-durability guarantee is made.
+ * A file whose owner this process cannot assign is rewritten in place instead.
+ *
+ * @since 1.0.0
+ */
+
+import * as Effect from "effect/Effect"
+import type * as FileSystem from "effect/FileSystem"
+import * as Option from "effect/Option"
+import type * as PlatformError from "effect/PlatformError"
+
+const permissions = 0o7777
+
+/**
+ * Replaces a file's text atomically, preserving its permission bits and owner.
+ *
+ * @category filesystem
+ * @since 1.0.0
+ */
+export const writeFileString = (
+  fileSystem: FileSystem.FileSystem,
+  path: string,
+  content: string
+): Effect.Effect<void, PlatformError.PlatformError> =>
+  replace(fileSystem, path, (target, flag, mode) => fileSystem.writeFileString(target, content, { flag, mode }))
+
+/**
+ * Replaces a file's bytes with the same atomic boundary used for text writes.
+ *
+ * @category filesystem
+ * @since 1.0.0
+ */
+export const writeFile = (
+  fileSystem: FileSystem.FileSystem,
+  path: string,
+  content: Uint8Array
+): Effect.Effect<void, PlatformError.PlatformError> =>
+  replace(fileSystem, path, (target, flag, mode) => fileSystem.writeFile(target, content, { flag, mode }))
+
+const replace = (
+  fileSystem: FileSystem.FileSystem,
+  path: string,
+  write: (
+    target: string,
+    flag: "wx" | "w",
+    mode: number | undefined
+  ) => Effect.Effect<void, PlatformError.PlatformError>
+): Effect.Effect<void, PlatformError.PlatformError> =>
+  Effect.gen(function*() {
+    const before = yield* fileSystem.stat(path).pipe(
+      Effect.catch((error) => error.reason._tag === "NotFound" ? Effect.succeed(undefined) : Effect.fail(error))
+    )
+    // Keep following an existing symlink, as an in-place write did.
+    const destination = before === undefined ? path : yield* fileSystem.realPath(path)
+    const temporary = destination.replace(/[^/\\]+$/, `.smithers-${globalThis.crypto.randomUUID()}.tmp`)
+    let owned = true
+    // Set when the sibling cannot take the file's owner; see the chown below.
+    let inPlace = false
+    yield* Effect.uninterruptibleMask((restore) =>
+      Effect.gen(function*() {
+        // Let the host finish its write before cancellation can unlink the name.
+        yield* write(temporary, "wx", before === undefined ? undefined : before.mode & permissions).pipe(
+          Effect.tapError((error) =>
+            Effect.sync(() => {
+              if (error.reason._tag === "AlreadyExists") owned = false
+            })
+          )
+        )
+        yield* restore(Effect.gen(function*() {
+          if (before === undefined) return
+          const after = yield* fileSystem.stat(temporary)
+          const uid = Option.getOrUndefined(before.uid)
+          const gid = Option.getOrUndefined(before.gid)
+          const ownerChanged = (uid !== undefined && uid !== Option.getOrUndefined(after.uid)) ||
+            (gid !== undefined && gid !== Option.getOrUndefined(after.gid))
+          if (ownerChanged) {
+            // Only root may give a file away. A writable file owned by another
+            // user (a shared checkout, a bind mount) cannot be replaced by a
+            // sibling this process owns without changing its owner, so it is
+            // rewritten in place instead: same inode, owner, and mode, at the
+            // cost of atomicity.
+            const chowned = yield* fileSystem.chown(temporary, uid ?? -1, gid ?? -1).pipe(
+              Effect.as(true),
+              Effect.catch((error) =>
+                error.reason._tag === "PermissionDenied" ? Effect.succeed(false) : Effect.fail(error)
+              )
+            )
+            if (!chowned) {
+              inPlace = true
+              return
+            }
+          }
+          // chown may clear set-id bits, so permissions are restored last.
+          if (ownerChanged || (after.mode & permissions) !== (before.mode & permissions)) {
+            yield* fileSystem.chmod(temporary, before.mode & permissions)
+          }
+        }))
+        if (!inPlace) yield* fileSystem.rename(temporary, destination)
+      }).pipe(
+        Effect.ensuring(
+          Effect.suspend(() => owned ? fileSystem.remove(temporary, { force: true }).pipe(Effect.orDie) : Effect.void)
+        )
+      )
+    )
+    if (inPlace) yield* write(destination, "w", undefined)
+  })

package/src/internal/Prune.ts

@@ -0,0 +1,62 @@
+/**
+ * The one list of directory names a repository walk leaves out.
+ *
+ * `grep`, `glob` and `ls` walks, the tree fingerprint, and workspace
+ * observation all read this list, so a directory one of them skips is never
+ * counted, matched, or fingerprinted by another. Every entry is derived state:
+ * version-control internals, dependency trees, caches, and the scratch
+ * checkouts the checkpoint and test-baseline flows create inside the
+ * workspace. A scratch checkout is a full copy of the repository at an older
+ * commit, so walking it duplicates every match from a stale tree.
+ *
+ * @since 1.0.0
+ */
+
+/**
+ * Workspace-relative directory holding checkpoint checkouts.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const checkpointScratch = ".flows-checkpoints"
+
+/**
+ * Workspace-relative directory holding test-baseline checkouts.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const testBaseScratch = ".flows-test-base"
+
+/**
+ * Directory basenames no repository walk descends into.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const repositoryDirectories: ReadonlyArray<string> = [
+  ".git",
+  ".hg",
+  ".jj",
+  ".svn",
+  ".flows",
+  ".artifacts",
+  ".backend-go-modcache",
+  ".pnpm-store",
+  ".worktrees",
+  "worktrees",
+  checkpointScratch,
+  testBaseScratch,
+  "node_modules",
+  "__pycache__",
+  ".venv",
+  ".tox",
+  ".nox",
+  ".eggs",
+  ".mypy_cache",
+  ".pytest_cache",
+  ".ruff_cache",
+  ".gradle",
+  ".turbo",
+  ".next"
+]

package/src/internal/SearchContract.ts

@@ -0,0 +1,77 @@
+/**
+ * The failure constructors and the literal escape both Search peers share.
+ *
+ * The validation and matching rules themselves are public, in
+ * `../SearchContract.ts`, because an external peer has to build on them. What
+ * is left here is what an external peer never calls: the three `StdError`
+ * shapes the contract fails with, the root-failure mapping, and the regex escape a fixed-string search
+ * applies before compiling.
+ *
+ * @since 1.0.0
+ */
+
+import type * as PlatformError from "effect/PlatformError"
+import * as StdError from "../StdError.ts"
+
+/**
+ * Constructs the common unsupported-pattern failure.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const invalidPattern = (pattern: string, detail: string): StdError.StdError =>
+  new StdError.StdError({ code: "invalid_pattern", message: `${rejectionPrefix}"${pattern}": ${detail}` })
+
+/**
+ * How every rejection {@link invalidPattern} writes begins.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const rejectionPrefix = "Unsupported ripgrep pattern "
+
+/**
+ * Constructs the common invalid-options failure.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const invalidInput = (detail: string): StdError.StdError =>
+  new StdError.StdError({ code: "invalid_input", message: `Invalid ripgrep options: ${detail}` })
+
+/**
+ * Constructs the common missing-root failure.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const notFound = (path: string): StdError.StdError =>
+  new StdError.StdError({ code: "not_found", message: `Path not found: ${path}`, path })
+
+/**
+ * Maps a failure to inspect the search root onto the contract's failures.
+ *
+ * Only a root that does not exist is `not_found`. Every other reason a stat
+ * or listing can fail (a guarded host that fails closed, a permission the
+ * process lacks, an I/O error) is a host operation failing, and it is
+ * reported as `command_failed` with the platform's own message, so the
+ * caller reads the real cause instead of a missing-path claim about a path
+ * that exists.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const rootFailure = (path: string, error: PlatformError.PlatformError): StdError.StdError =>
+  error.reason._tag === "NotFound"
+    ? notFound(path)
+    : error.reason._tag === "PermissionDenied"
+    ? new StdError.StdError({ code: "permission_denied", message: `Cannot search ${path}: ${error.message}`, path })
+    : new StdError.StdError({ code: "command_failed", message: `Cannot search ${path}: ${error.message}`, path })
+
+/**
+ * Escapes literal text for JavaScript regular expressions.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const escapeRegex = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")

package/src/internal/Symbols.ts

@@ -0,0 +1,88 @@
+/**
+ * The definition a line sits inside, read off the file's own shape.
+ *
+ * A search hit is a line number, and a line number is not a read window. Agents
+ * guess one: `offset: line - 10, limit: 40`, which lands short (astropy-15569
+ * missed `get_lookup` by one line and probed the wrong binding) or long (six
+ * blind-offset reads on sympy-13878). The enclosing definition is the window the
+ * hit actually belongs to, and for indentation- and brace-structured source it
+ * is derivable from the text already in hand.
+ *
+ * This is a heuristic and reports only what it can see plainly: a declaration
+ * keyword, a name, and the block that keyword opens. When the shape is not
+ * plain — a match at top level, a language this table does not name, a
+ * declaration split across lines — it answers `undefined` rather than guessing,
+ * because a wrong window is worse than none.
+ *
+ * @since 1.0.0
+ */
+
+/**
+ * The definition enclosing a line.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Symbol {
+  readonly kind: string
+  readonly name: string
+  readonly startLine: number
+  readonly endLine: number
+}
+
+/**
+ * Declaration keywords this heuristic recognises across the languages the
+ * standard flows meet. Modifiers before the keyword are skipped, the name after
+ * it is captured, and everything else is left alone.
+ */
+const declaration =
+  /^([ \t]*)(?:(?:async|export|default|public|private|protected|internal|static|final|abstract|open|pub(?:\([^)]*\))?|unsafe|const|declare)[ \t]+)*(def|class|function|fn|func|struct|impl|interface|trait|enum|module|namespace|type|sub|method)[ \t]+([A-Za-z_$][A-Za-z0-9_$]*)/
+
+const closer = /^[ \t]*[)}\]]/
+
+const indentOf = (line: string): number => /^[ \t]*/.exec(line)![0].length
+
+const blank = (line: string): boolean => line.trim() === ""
+
+/**
+ * The definition enclosing a 1-based line, or `undefined` when there is none to
+ * read plainly.
+ *
+ * @category navigation
+ * @since 1.0.0
+ */
+export const enclosing = (lines: ReadonlyArray<string>, line: number): Symbol | undefined => {
+  const index = line - 1
+  if (index < 0 || index >= lines.length) return undefined
+  // A blank match line has no indentation of its own; the nearest text above it
+  // does, and that is the block the blank line belongs to.
+  let reference = index
+  while (reference > 0 && blank(lines[reference]!)) reference--
+  const indent = indentOf(lines[reference]!)
+  let start = -1
+  let parsed: RegExpExecArray | null = null
+  for (let candidate = index; candidate >= 0; candidate--) {
+    const text = lines[candidate]!
+    if (blank(text)) continue
+    const found = declaration.exec(text)
+    if (found === null) continue
+    if (candidate !== index && indentOf(text) >= indent) continue
+    start = candidate
+    parsed = found
+    break
+  }
+  if (parsed === null) return undefined
+  const opening = indentOf(lines[start]!)
+  let end = lines.length - 1
+  for (let candidate = start + 1; candidate < lines.length; candidate++) {
+    const text = lines[candidate]!
+    if (blank(text)) continue
+    if (indentOf(text) > opening) continue
+    // A brace language closes the block at the declaration's own indentation,
+    // and that closing line is part of the definition rather than what follows.
+    end = closer.test(text) ? candidate : candidate - 1
+    break
+  }
+  while (end > start && blank(lines[end]!)) end--
+  return { kind: parsed[2]!, name: parsed[3]!, startLine: start + 1, endLine: end + 1 }
+}