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

package/src/internal/LinearRegex.ts

@@ -0,0 +1,173 @@
+/**
+ * Thompson matching for the validated ASCII search grammar. Each state is
+ * visited once per input position; alternatives never backtrack over input.
+ *
+ * @since 1.0.0
+ */
+
+type Term =
+  | { readonly kind: "atom"; readonly source: string }
+  | { readonly kind: "sequence" | "alternative"; readonly terms: ReadonlyArray<Term> }
+  | { readonly kind: "repeat"; readonly term: Term; readonly min: number; readonly max: number }
+
+type State =
+  | { readonly kind: "atom"; readonly expression: RegExp; readonly next: number }
+  | { readonly kind: "start" | "end"; readonly next: number }
+  | { readonly kind: "split"; readonly next: ReadonlyArray<number> }
+  | { readonly kind: "accept" }
+
+/**
+ * Compiles an already syntax-validated pattern. Compilation is bounded to
+ * 8192 states and 128 nested groups, including expanded counted repetitions.
+ * The iterator yields every 4096 state visits so the host can dispatch timers
+ * and interruption even for long lines and expensive linear matches.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const compile = (
+  pattern: string,
+  insensitive: boolean
+): { readonly test: (line: string) => Generator<void, boolean> } => {
+  let offset = 0
+  const parse = (depth: number): Term => {
+    if (depth > 128) throw new Error("patterns must not exceed 128 nested groups")
+    const alternatives: Array<Term> = []
+    let sequence: Array<Term> = []
+    while (offset < pattern.length && pattern[offset] !== ")") {
+      const start = offset
+      const character = pattern[offset++]!
+      if (character === "|") {
+        alternatives.push({ kind: "sequence", terms: sequence })
+        sequence = []
+        continue
+      }
+      let term: Term
+      if (character === "(") {
+        term = parse(depth + 1)
+        offset++
+      } else {
+        if (character === "\\") offset++
+        if (character === "[") {
+          while (pattern[offset] !== "]") {
+            if (pattern[offset++] === "\\") offset++
+          }
+          offset++
+        }
+        term = { kind: "atom", source: pattern.slice(start, offset) }
+      }
+      const quantifier = pattern[offset]
+      if (quantifier === "*" || quantifier === "+" || quantifier === "?" || quantifier === "{") {
+        offset++
+        let min = quantifier === "+" ? 1 : 0
+        let max = quantifier === "?" ? 1 : Infinity
+        if (quantifier === "{") {
+          const end = pattern.indexOf("}", offset)
+          const counts = pattern.slice(offset, end).split(",")
+          min = Number(counts[0])
+          max = counts.length === 1 ? min : counts[1] === "" ? Infinity : Number(counts[1])
+          offset = end + 1
+        }
+        // Greediness affects captures, not whether a line contains a match.
+        if (pattern[offset] === "?") offset++
+        term = { kind: "repeat", term, min, max }
+      }
+      sequence.push(term)
+    }
+    alternatives.push({ kind: "sequence", terms: sequence })
+    return { kind: "alternative", terms: alternatives }
+  }
+  const tree = parse(0)
+  const states: Array<State> = [{ kind: "accept" }]
+  const append = (state: State): number => {
+    if (states.length >= 8192) throw new Error("patterns must not exceed 8192 compiled states")
+    states.push(state)
+    return states.length - 1
+  }
+  const build = (term: Term, next: number): number => {
+    switch (term.kind) {
+      case "atom":
+        if (term.source === "^") return append({ kind: "start", next })
+        if (term.source === "$") return append({ kind: "end", next })
+        return append({
+          kind: "atom",
+          expression: new RegExp(term.source === "." ? "[^\\n]" : term.source, insensitive ? "iu" : "u"),
+          next
+        })
+      case "sequence": {
+        let head = next
+        for (let index = term.terms.length - 1; index >= 0; index--) head = build(term.terms[index]!, head)
+        return head
+      }
+      case "alternative":
+        return append({ kind: "split", next: term.terms.map((child) => build(child, next)) })
+      case "repeat": {
+        let head = next
+        if (term.max === Infinity) {
+          const loop = append({ kind: "split", next: [] })
+          states[loop] = { kind: "split", next: [next, build(term.term, loop)] }
+          head = loop
+        } else {
+          for (let index = term.min; index < term.max; index++) {
+            head = append({ kind: "split", next: [head, build(term.term, head)] })
+          }
+        }
+        for (let index = 0; index < term.min; index++) head = build(term.term, head)
+        return head
+      }
+    }
+  }
+  const start = build(tree, 0)
+  return {
+    *test(line) {
+      let current: Array<number> = []
+      let position = 0
+      let work = 0
+      const seen = new Int32Array(states.length)
+      let generation = 0
+      while (true) {
+        generation++
+        const pending = [...current, start]
+        const consuming: Array<number> = []
+        while (pending.length > 0) {
+          if (++work === 4096) {
+            work = 0
+            yield
+          }
+          const id = pending.pop()!
+          if (seen[id] === generation) continue
+          seen[id] = generation
+          const state = states[id]!
+          switch (state.kind) {
+            case "accept":
+              return true
+            case "atom":
+              consuming.push(id)
+              break
+            case "split":
+              for (const next of state.next) pending.push(next)
+              break
+            case "start":
+              if (position === 0) pending.push(state.next)
+              break
+            case "end":
+              if (position === line.length) pending.push(state.next)
+              break
+          }
+        }
+        if (position === line.length) return false
+        const character = String.fromCodePoint(line.codePointAt(position)!)
+        position += character.length
+        current = []
+        for (const id of consuming) {
+          if (++work === 4096) {
+            work = 0
+            yield
+          }
+          const state = states[id]!
+          if (state.kind === "atom" && state.expression.test(character)) current.push(state.next)
+        }
+      }
+    }
+  }
+}

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"
+]