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

package/src/Fetch.ts

@@ -0,0 +1,117 @@
+/**
+ * HTTP GET flow declaration and portable handler.
+ *
+ * @since 1.0.0
+ */
+
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest"
+import { capability, envelope } from "./internal/Declaration.ts"
+import { execute, Response, Timeout } from "./internal/Http.ts"
+
+/**
+ * Registry name for the fetch flow.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export const name = "fetch"
+
+/**
+ * Model-facing description of the fetch flow.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export const description =
+  "Get an absolute URL and return its status and text body; long bodies are truncated with a notice. Use http-post to send data."
+
+/**
+ * Input schema for the fetch flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const Input = Schema.Struct({
+  url: Schema.String.annotate({ description: "Absolute http or https URL to retrieve" }),
+  headers: Schema.optional(Schema.Record(Schema.String, Schema.String)).annotate({
+    description: "Additional request headers"
+  }),
+  timeout: Schema.optional(Timeout).annotate({
+    description: "Total request and response body timeout in seconds; defaults to 30, capped at 120"
+  })
+})
+
+/**
+ * Decoded input accepted by the `fetch` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Input = typeof Input.Type
+
+/**
+ * Output schema for the fetch flow.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const Output = Response
+
+/**
+ * Decoded output returned by the `fetch` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Output = typeof Output.Type
+
+/**
+ * Static effect envelope for the fetch flow.
+ *
+ * A retrieval leaves no durable state behind, so it is sealed even though it
+ * leaves the machine.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effects = envelope({ tier: "sealed", mode: "expected", reads: [], writes: [] })
+
+/**
+ * Narrows the fetch effect envelope for one decoded input.
+ *
+ * Network reach is expressed as a capability rather than a path envelope, so
+ * a retrieval has nothing left to narrow.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effectsFor = (_input: typeof Input.Type) => effects
+
+/**
+ * Capabilities required by the fetch flow.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export const capabilities = [capability("net:get", "*")]
+
+/**
+ * Declaration-only fetch flow.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export const flow = { name, description, input: Input, output: Output, capabilities, effects } as const
+
+/**
+ * Retrieves a URL through the permission-aware kernel HTTP client.
+ *
+ * Error statuses are ordinary results; only transport, permission, and body
+ * decoding failures use the typed error channel.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export const run = Effect.fn("Fetch.run")((input: Input) => execute(input, HttpClientRequest.get))

package/src/Glob.ts

@@ -0,0 +1,200 @@
+/**
+ * The `glob` projection of Smithers Ripgrep Subset v1.
+ *
+ * It has the same two peer implementations as `grep` and supports the
+ * `rg --files -g` pattern subset: `*`, `**`, `?`, and brace alternatives;
+ * results are path sorted; hidden files are opt-in; root and nested .gitignore
+ * files apply by default (even outside git repositories). `noIgnore: true` opts
+ * out. Parent/global ignore files, .git/info/exclude, .ignore and .rgignore
+ * are not read. Caller globs filter the remaining files without overriding
+ * ignores. An explicitly named ignored or skipped directory is still searched.
+ *
+ * **Patterns are relative to `root`, never to the filesystem.** A candidate is
+ * matched by the path it has *relative to the search root*, so `tests/**\/*.py`
+ * — what every caller writing a project-relative pattern means — matches
+ * `<root>/tests/admin_views/admin.py`. Three rules follow, and both peers
+ * implement all three identically:
+ *
+ * - A pattern with no `/` matches the **basename** at any depth: `*.py` finds
+ *   every Python file in the subtree.
+ * - A pattern containing `/` is matched against the root-relative path and is
+ *   anchored at the root: `tests/*.py` matches `<root>/tests/a.py` and not
+ *   `<root>/src/tests/a.py`.
+ * - A leading `/` is the same anchor spelled explicitly, not a filesystem
+ *   absolute path: `/a.py` matches only `<root>/a.py`, where bare `a.py` would
+ *   match any `a.py` in the subtree. A leading `./` means the same anchor.
+ *
+ * `**` crosses directory boundaries, `*` and `?` stay inside one segment, and
+ * `?` consumes one UTF-8 byte. Trailing spaces are not part of a pattern:
+ * `rg` reads `-g` by gitignore's rules and drops them, so `"a.ts "` finds
+ * `a.ts`, and a pattern left blank by that is rejected rather than read as no
+ * filter at all.
+ *
+ * A `root` that names one file is that file. It is reported whatever the
+ * pattern says, because `rg` searches a path given on its command line without
+ * consulting `-g`, and a walk that reaches one file has nothing to filter.
+ *
+ * A walk skips what it cannot read — a dangling symlink, a link cycle, a
+ * directory the process may not list — and reports everything it did reach.
+ * One unreadable entry never fails the call.
+ *
+ * The consequence worth stating is the one that cost a SWE-bench run 41 of its
+ * 43 frames: an *absolute* pattern such as `/home/repo/tests/**` is read as the
+ * root-relative path `home/repo/tests/**`, which nothing under a root of
+ * `/home/repo` can match. That answer is now never silent — a pattern no file
+ * under the root could match reports why through `notice`, so "unsatisfiable"
+ * and "searched and found none" stay distinguishable.
+ *
+ * @since 1.0.0
+ */
+
+import { Effect, Schema } from "effect"
+import { capability, envelope, rootSubtree } from "./internal/Declaration.ts"
+import { MAX_ENTRIES } from "./internal/Text.ts"
+import * as Search from "./Search.ts"
+import * as Contract from "./SearchContract.ts"
+import type * as StdError from "./StdError.ts"
+
+/**
+ * The registry name for glob.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export const name = "glob"
+/**
+ * The model-facing glob description.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export const description = "Find files through the Smithers Ripgrep Subset v1 contract."
+/**
+ * Input accepted by {@link flow} and {@link run}.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const Input = Schema.Struct({
+  pattern: Schema.NonEmptyString.annotate({
+    description:
+      "Ripgrep -g pattern, matched against paths relative to root, never absolute paths: *, ?, {a,b} stay inside one segment, ** crosses directories, a pattern without / matches any basename, and a leading / anchors at root."
+  }),
+  root: Schema.optional(Schema.String).annotate({
+    description: "Search root the pattern is relative to; defaults to . (the host workspace)."
+  }),
+  hidden: Schema.optional(Schema.Boolean).annotate({ description: "Ripgrep --hidden." }),
+  noIgnore: Schema.optional(Schema.Boolean).annotate({
+    description:
+      "Honor root-scoped .gitignore files by default. Set true to include ignored paths; hidden and fixed directory skips still apply."
+  }),
+  limit: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))).annotate({
+    description: `Maximum paths, capped at ${MAX_ENTRIES}.`
+  })
+})
+/**
+ * Decoded input accepted by the `glob` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Input = typeof Input.Type
+/**
+ * Output produced by {@link run}.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const Output = Schema.Struct({
+  paths: Schema.Array(Schema.String),
+  total: Schema.Int,
+  truncated: Schema.Boolean,
+  notice: Schema.optional(Schema.String)
+})
+/**
+ * Decoded output returned by the `glob` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Output = typeof Output.Type
+/**
+ * Conservative sealed declaration for all workspace files.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effects = envelope({ tier: "sealed", mode: "hermetic", reads: ["/**"], writes: [] })
+/**
+ * Narrows the read declaration to the requested root subtree.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effectsFor = (input: { readonly root?: string | undefined }) =>
+  envelope({ tier: "sealed", mode: "hermetic", reads: [rootSubtree(input.root ?? ".")], writes: [] })
+/**
+ * Capability strings requested by glob.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export const capabilities = [capability("fs:read", "/**")]
+/**
+ * Declaration-only glob flow.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export const flow = { name, description, input: Input, output: Output, capabilities, effects } as const
+
+/**
+ * What a call to this flow does, for a reader of a run.
+ *
+ * Display metadata only. `@smthrs/registry` `Descriptor.FlowActivity` is the
+ * governing vocabulary and `StandardFlows` binds this value onto the flow's
+ * descriptor, where the binding site checks it. `declarationDigest` excludes
+ * it, so declaring it cannot invalidate a call identity or a cached prompt.
+ *
+ * @category presentation
+ * @since 1.0.0-rc.0
+ */
+export const activity = "reads" as const
+
+/**
+ * How one recorded call to this flow reads: the verb for each settlement, the
+ * input field that is its subject, and the measured output fields a one-line
+ * summary may count.
+ *
+ * Display metadata only, governed by `@smthrs/registry`
+ * `Descriptor.CallPresentation` and checked where `StandardFlows` binds it.
+ *
+ * @category presentation
+ * @since 1.0.0-rc.0
+ */
+export const presentation = {
+  verb: { pending: "listing", success: "listed", failure: "failed to list" },
+  subject: "pattern",
+  result: "paths"
+} as const
+
+/**
+ * Runs one `rg --files -g` contract call through the selected peer implementation.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export const run = Effect.fn("Glob.run")(function*(
+  input: typeof Input.Type
+): Effect.fn.Return<typeof Output.Type, StdError.StdError, Search.Search> {
+  const patternError = Contract.validateGlob(input.pattern)
+  if (patternError !== undefined) return yield* Effect.fail(patternError)
+  const search = yield* Search.Search
+  return yield* search.glob({
+    pattern: input.pattern,
+    root: input.root ?? ".",
+    hidden: input.hidden ?? false,
+    noIgnore: input.noIgnore ?? false,
+    limit: Math.min(input.limit ?? MAX_ENTRIES, MAX_ENTRIES)
+  })
+})

package/src/Grep.ts

@@ -0,0 +1,320 @@
+/**
+ * The `grep` flow and its Smithers Ripgrep Subset v1 contract.
+ *
+ * Supported ripgrep semantics: Rust-style regular expressions restricted to
+ * Smithers Ripgrep ASCII v1; `-F` (`fixedStrings`); `-i` (`ignoreCase`) and `-S`
+ * (`smartCase`); ordered `-g` include/exclude globs; `-A`, `-B`, and `-C`
+ * context; per-file `--max-count`; `--files-with-matches`; `--hidden`; and
+ * deterministic path/line ordering. Root and nested .gitignore files apply by
+ * default, including outside git repositories. `noIgnore: true` opts out.
+ * Parent/global ignore files, .git/info/exclude, .ignore and .rgignore are not
+ * read. File-type registries are outside v1, and there is no `types` field to
+ * pass. Patterns are capped at 4096 ASCII bytes and counted repetitions at 1000. Invalid UTF-8 is replacement-decoded; NUL-bearing
+ * files are skipped and counted, while an explicitly named binary file is a
+ * typed failure.
+ *
+ * Results are match-centric, which is `rg --json`'s own grouping: `limit`
+ * counts matches, each match carries the context lines that belong to it, and
+ * every context line belongs to exactly one match. A budget that counted rows
+ * could spend itself on context and drop the match — astropy-7166 paid three
+ * frames for exactly that — so a hit is never droppable to make room for its
+ * own surroundings. Truncation is disclosed through `notice`.
+ *
+ * Each returned hit also carries the definition enclosing it when the file's
+ * shape says so plainly, so a read window is computed rather than guessed, and
+ * a metacharacter pattern that finds nothing is retried as a literal with
+ * `retriedAsLiteral` set. Both are properties of the contract rather than of a
+ * peer: they are computed in `internal/Grouping.ts` for both implementations.
+ *
+ * `globs` accepts exactly the shapes `glob` accepts and reads them the same
+ * way: every pattern is matched against each candidate's path *relative to
+ * `root`*, a pattern without `/` matches the basename at any depth, and a
+ * leading `/` or `./` anchors at the root rather than naming a filesystem
+ * absolute path. A `root` that names one file is searched whatever the globs
+ * say. Caller globs filter after ignores; they never override them. See `Glob` for the full statement of the rules. A search that matched
+ * nothing because a positive glob was unsatisfiable says so through `notice`
+ * instead of returning a silent empty result.
+ *
+ * `filesSearched` counts every file the walk and globs admitted, including the binaries
+ * `skippedBinary` reports and any file the process could not open. A walk
+ * skips what it cannot read rather than failing the call.
+ *
+ * Native and in-process implementations are peers behind `Search.Search`.
+ * This module declares and validates the call; it performs no host access.
+ *
+ * @since 1.0.0
+ */
+
+import { Effect, Schema } from "effect"
+import { capability, envelope, rootSubtree } from "./internal/Declaration.ts"
+import { invalidInput } from "./internal/SearchContract.ts"
+import { MAX_GREP_MATCHES } from "./internal/Text.ts"
+import * as Search from "./Search.ts"
+import * as Contract from "./SearchContract.ts"
+import * as StdError from "./StdError.ts"
+
+/**
+ * The registry name for grep.
+ *
+ * @category identifiers
+ * @since 1.0.0
+ */
+export const name = "grep"
+/**
+ * The model-facing grep description.
+ *
+ * @category descriptions
+ * @since 1.0.0
+ */
+export const description =
+  "Search file contents through the Smithers Ripgrep Subset v1 contract. limit counts matches, each carrying its own context and enclosing definition; fixedStrings searches a literal, and one is retried."
+
+/**
+ * Input accepted by {@link flow} and {@link run}.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const Input = Schema.Struct({
+  pattern: Schema.String.annotate({ description: "Smithers Ripgrep ASCII v1 expression." }),
+  root: Schema.optional(Schema.String).annotate({
+    description: "Search root the globs are relative to; defaults to . (the host workspace)."
+  }),
+  fixedStrings: Schema.optional(Schema.Boolean).annotate({ description: "Ripgrep -F." }),
+  ignoreCase: Schema.optional(Schema.Boolean).annotate({ description: "Ripgrep -i." }),
+  smartCase: Schema.optional(Schema.Boolean).annotate({ description: "Ripgrep -S." }),
+  globs: Schema.optional(Schema.Array(Schema.String)).annotate({
+    description:
+      "Ordered ripgrep -g globs, matched against paths relative to root, never absolute paths: a glob without / matches any basename, a leading / anchors at root, and ** crosses directories. Prefix exclusions with !."
+  }),
+  beforeContext: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))).annotate({
+    description: "Ripgrep -B."
+  }),
+  afterContext: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))).annotate({
+    description: "Ripgrep -A."
+  }),
+  context: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))).annotate({ description: "Ripgrep -C." }),
+  maxCount: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(1))).annotate({
+    description: "Ripgrep --max-count, per file; at least 1."
+  }),
+  filesWithMatches: Schema.optional(Schema.Boolean).annotate({ description: "Ripgrep --files-with-matches." }),
+  hidden: Schema.optional(Schema.Boolean).annotate({ description: "Ripgrep --hidden." }),
+  symbols: Schema.optional(Schema.Boolean).annotate({
+    description: "Report the definition enclosing each returned hit; true by default."
+  }),
+  noIgnore: Schema.optional(Schema.Boolean).annotate({
+    description:
+      "Honor root-scoped .gitignore files by default. Set true to include ignored paths; hidden and fixed directory skips still apply."
+  }),
+  limit: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))).annotate({
+    description: `Global result limit, capped at ${MAX_GREP_MATCHES}.`
+  })
+})
+
+/**
+ * Decoded input accepted by the `grep` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Input = typeof Input.Type
+
+/**
+ * One matching or context line.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const ContextLine = Schema.Struct({
+  line: Schema.Int.annotate({ description: "1-based line number" }),
+  text: Schema.String
+})
+
+/**
+ * The definition a hit sits inside, when the file's shape says so plainly.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const Symbol = Schema.Struct({
+  kind: Schema.String.annotate({ description: "The declaration keyword, such as def or class" }),
+  name: Schema.String,
+  startLine: Schema.Int.annotate({ description: "1-based first line of the definition" }),
+  endLine: Schema.Int.annotate({
+    description: "1-based last line of the definition; read this range, do not guess one"
+  })
+})
+
+/**
+ * One hit and the context that belongs to it.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const Match = Schema.Struct({
+  file: Schema.String,
+  line: Schema.Int,
+  text: Schema.String,
+  before: Schema.Array(ContextLine),
+  after: Schema.Array(ContextLine),
+  symbol: Schema.optional(Symbol)
+})
+
+/**
+ * Output produced by {@link run}.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export const Output = Schema.Struct({
+  matches: Schema.Array(Match),
+  files: Schema.Array(Schema.String),
+  filesSearched: Schema.Int,
+  skippedBinary: Schema.Int,
+  truncated: Schema.Boolean,
+  retriedAsLiteral: Schema.optional(Schema.Boolean).annotate({
+    description: "Present when the pattern found nothing as a regex and these results come from re-running it literally"
+  }),
+  notice: Schema.optional(Schema.String)
+})
+
+/**
+ * Decoded output returned by the `grep` flow.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Output = typeof Output.Type
+
+/**
+ * Conservative sealed declaration for all workspace files.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effects = envelope({ tier: "sealed", mode: "hermetic", reads: ["/**"], writes: [] })
+/**
+ * Narrows the read declaration to the requested root subtree.
+ *
+ * @category effects
+ * @since 1.0.0
+ */
+export const effectsFor = (input: { readonly root?: string | undefined }) =>
+  envelope({ tier: "sealed", mode: "hermetic", reads: [rootSubtree(input.root ?? ".")], writes: [] })
+/**
+ * Capability strings requested by grep.
+ *
+ * @category capabilities
+ * @since 1.0.0
+ */
+export const capabilities = [capability("fs:read", "/**")]
+/**
+ * Declaration-only grep flow.
+ *
+ * @category flows
+ * @since 1.0.0
+ */
+export const flow = { name, description, input: Input, output: Output, capabilities, effects } as const
+
+/**
+ * What a call to this flow does, for a reader of a run.
+ *
+ * Display metadata only. `@smthrs/registry` `Descriptor.FlowActivity` is the
+ * governing vocabulary and `StandardFlows` binds this value onto the flow's
+ * descriptor, where the binding site checks it. `declarationDigest` excludes
+ * it, so declaring it cannot invalidate a call identity or a cached prompt.
+ *
+ * @category presentation
+ * @since 1.0.0-rc.0
+ */
+export const activity = "reads" as const
+
+/**
+ * How one recorded call to this flow reads: the verb for each settlement, the
+ * input field that is its subject, and the measured output fields a one-line
+ * summary may count.
+ *
+ * Display metadata only, governed by `@smthrs/registry`
+ * `Descriptor.CallPresentation` and checked where `StandardFlows` binds it.
+ *
+ * @category presentation
+ * @since 1.0.0-rc.0
+ */
+export const presentation = {
+  verb: { pending: "searching", success: "searched", failure: "failed to search" },
+  subject: "pattern",
+  result: "matches"
+} as const
+
+const normalize = (input: typeof Input.Type): Search.GrepInput | StdError.StdError => {
+  if (input.ignoreCase === true && input.smartCase === true) {
+    return invalidInput("-i and -S are mutually exclusive")
+  }
+  if (input.context !== undefined && (input.beforeContext !== undefined || input.afterContext !== undefined)) {
+    return invalidInput("-C cannot be combined with -A or -B")
+  }
+  // `rg --max-count 0` answers nothing at all, not even the summary the native
+  // peer parses, so a cap that admits no match is rejected rather than read
+  // differently by each peer.
+  if (input.maxCount !== undefined && input.maxCount < 1) {
+    return invalidInput("--max-count must be at least 1")
+  }
+  const fixedStrings = input.fixedStrings ?? false
+  const patternError = Contract.validatePattern(input.pattern, fixedStrings)
+  if (patternError !== undefined) return patternError
+  for (const glob of input.globs ?? []) {
+    const globError = Contract.validateGlob(glob)
+    if (globError !== undefined) return globError
+  }
+  return {
+    pattern: input.pattern,
+    root: input.root ?? ".",
+    fixedStrings,
+    ignoreCase: input.ignoreCase ?? false,
+    smartCase: input.smartCase ?? false,
+    globs: input.globs ?? [],
+    beforeContext: input.context ?? input.beforeContext ?? 0,
+    afterContext: input.context ?? input.afterContext ?? 0,
+    maxCount: input.maxCount,
+    filesWithMatches: input.filesWithMatches ?? false,
+    hidden: input.hidden ?? false,
+    noIgnore: input.noIgnore ?? false,
+    symbols: input.symbols ?? true,
+    limit: Math.min(input.limit ?? MAX_GREP_MATCHES, MAX_GREP_MATCHES)
+  }
+}
+
+const metacharacters = /[\\^$.|?*+()[\]{}]/
+
+const empty = (output: typeof Output.Type): boolean => output.matches.length === 0 && output.files.length === 0
+
+/**
+ * Runs one validated ripgrep-contract call through the selected peer implementation.
+ *
+ * A pattern full of metacharacters that finds nothing is the most common way a
+ * search lies: `sphinx-16612` searched 867 files for a parenthesised name and
+ * read `0 of 867` as "this symbol is not used here". The retry costs one more
+ * pass over the same tree only in the case that already found nothing, and the
+ * result says plainly that the answer came from the literal reading.
+ *
+ * @category handlers
+ * @since 1.0.0
+ */
+export const run = Effect.fn("Grep.run")(function*(
+  input: typeof Input.Type
+): Effect.fn.Return<typeof Output.Type, StdError.StdError, Search.Search> {
+  const normalized = normalize(input)
+  if (normalized instanceof StdError.StdError) return yield* Effect.fail(normalized)
+  const search = yield* Search.Search
+  const result = yield* search.grep(normalized)
+  if (normalized.fixedStrings || !empty(result) || !metacharacters.test(normalized.pattern)) return result
+  const literal = yield* search.grep({ ...normalized, fixedStrings: true })
+  if (empty(literal)) return result
+  const explanation =
+    `The pattern found nothing as a regular expression and these results come from re-running it literally (fixedStrings: true).`
+  return {
+    ...literal,
+    retriedAsLiteral: true,
+    notice: literal.notice === undefined ? explanation : `${explanation} ${literal.notice}`
+  }
+})