From 6ddf9daa0d7f78d8a5ddfed9aad870a8980ac0ce Mon Sep 17 00:00:00 2001 From: Leynos Date: Wed, 10 Sep 2025 20:16:05 +0100 Subject: [PATCH] Remove srgn documentation --- AGENTS.md | 3 +- docs/srgn.md | 712 --------------------------------------------------- 2 files changed, 1 insertion(+), 714 deletions(-) delete mode 100644 docs/srgn.md diff --git a/AGENTS.md b/AGENTS.md index 4a209d73..c563ff89 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -244,8 +244,7 @@ The following tooling is available in this environment: - `checkmake` – Linter for `Makefile`s, ensuring they follow best practices and conventions. - `srgn` – [Structural grep](https://github.com/alexpovel/srgn), searches code - and enables editing by syntax tree patterns (see `docs/srgn.md` for a - complete guide). + and enables editing by syntax tree patterns. - `difft` **(Difftastic)** – Semantic diff tool that compares code structure rather than just text differences. diff --git a/docs/srgn.md b/docs/srgn.md deleted file mode 100644 index eba354b1..00000000 --- a/docs/srgn.md +++ /dev/null @@ -1,712 +0,0 @@ -# A Command-Line Wizard's Guide to Surgical Code Refactoring with srgn - -## Part 1: Introduction - The Code Surgeon's Scalpel - -### 1.1 Beyond Grep: The Need for Syntactic Precision - -In the arsenal of any command-line proficient developer, tools like `grep`, -`sed`, and `ripgrep` are indispensable instruments for searching and -manipulating text. They are fast, powerful, and universally available. However, -they share a fundamental limitation: they perceive source code as a flat stream -of characters, oblivious to its intricate grammatical structure. This blindness -prevents them from reliably performing context-aware refactoring, where a -change in one syntactic location (e.g., a function signature) should not affect -another (e.g., a string literal). - -This is the precise gap that `srgn`, the "code surgeon," is designed to -fill.[^1] It operates as a powerful hybrid, blending the regex-based pattern -matching of `grep`, the stream-editing capabilities of `tr` and `sed`, and the -syntactic intelligence of the `tree-sitter` parsing framework.[^1] - -`srgn` complements traditional tools by operating on a different "dimension" of -code analysis.[^1] It is not a replacement for full-featured IDE refactoring -engines but a specialized scalpel for tasks that are too complex for a simple -regex and too specific for a generic IDE command. - -The ideal use case for `srgn` emerges when a refactoring task requires -precision that text-based tools cannot provide, yet falls outside the scope of -standard IDE functions like "Rename All" or "Find All References." For example, -a global regex replacement to change a function call `foo()` to `bar()` might -incorrectly alter variable names like `my_foo` or text within comments. -Conversely, an IDE's rename function operates on a specific symbol's definition -and usages but cannot execute a rule-based transformation, such as "convert all -top-level `print()` calls to `logging.debug()`." `srgn` excels at this kind of -precise, rule-based, cross-file surgery, making it a strategic asset for -enforcing coding standards, executing targeted API migrations, and performing -complex cleanups. - -### 1.2 Disambiguation: Identifying the Correct srgn - -To ensure clarity, it is essential to acknowledge that the name "srgn" is -overloaded across different domains. This guide is exclusively dedicated to -`alexpovel/srgn`, the command-line code search and manipulation utility.[^1] -Other projects bearing a similar name are unrelated to the tool discussed here. -These include, but are not limited to, SRGAN, a Generative Adversarial Network -for image super-resolution 3; SRGN, a high-energy physics technique for -parameter estimation 4; and SRGN (SolRagon), a cryptocurrency token.[^6] This -report focuses solely on the code refactoring tool. - -### 1.3 Core Philosophy: Scopes, Actions, and Intentional Simplicity - -The design of `srgn` is built upon two foundational pillars: **Scopes** and -**Actions**.[^2] Scopes define - -*where* in the code an operation should take place, while Actions define *what* -should be done to the text within that scope. This separation of concerns is -central to the tool's power and usability. - -A core tenet of `srgn` is its intentional simplicity. The documentation states -its design goal clearly: "if you know regex and the basics of the language you -are working with, you are good to go".[^2] This philosophy distinguishes - -`srgn` from other advanced code-querying tools. While tools like Semgrep use a -declarative, template-based syntax with metavariables (`$X`) and ellipses -(`...`) to find code that matches an abstract pattern 8, - -`srgn` employs a more direct approach. - -`srgn` does not use a proprietary structural pattern language. Instead, it -functions as a highly precise location filter. It answers the question, "Find -text matching this regex, but only at *this kind of location* (e.g., inside a -Python class definition)." This is fundamentally different from a tool that -answers, "Find code that *looks like this abstract pattern*." `srgn`'s power -derives from its compositional filtering model—layering predefined grammar -queries and user-supplied regular expressions—rather than from a complex, -abstract query language. This design choice makes its mechanisms transparent -and its learning curve gentle for anyone already comfortable with the command -line. - -## Part 2: Getting Started - Installation and First Cuts - -### 2.1 Installation: Preparing the Operating Theater - -`srgn` can be installed across various platforms, catering to the diverse -environments of command-line users. The following methods are officially -supported 1: - -- **Prebuilt Binaries**: The most straightforward method is to download a - prebuilt binary for your specific architecture directly from the project's - GitHub Releases page.[^1] - -- `cargo-binstall`: For users with the Rust toolchain, this is the recommended - installation method. It is significantly faster than compiling from source as - it downloads prebuilt binaries when available. It is tested in the project's - CI and serves as a reliable installation vector.[^1] - - Bash - - ```sh - # Install the Rust toolchain if you haven't already - # Then, install cargo-binstall - cargo install cargo-binstall - # Finally, install srgn - cargo binstall srgn - - ``` - -- `cargo install`: The traditional method of compiling from source using Rust's - package manager. This requires a C compiler to be present on the system - (`gcc` on Linux, `clang` on macOS, or MSVC on Windows).[^1] - - Bash - - ```sh - cargo install srgn - - ``` - -- **Package Managers**: `srgn` is available through several system package - managers, offering convenient installation and updates 1: - - - **Homebrew (macOS/Linux):** `brew install srgn` - - - **Nix (NixOS/Linux/macOS):** `nix-shell -p srgn` - - - **Arch Linux:** Available via the AUR (Arch User Repository). - - - **MacPorts (macOS):** `sudo port install srgn` - -For integration into automated workflows, a GitHub Action is available for -`cargo-binstall`, allowing for easy installation of `srgn` in CI/CD -pipelines.[^1] - -### 2.2 The Anatomy of a srgn Command - -The fundamental structure of a `srgn` command is analogous to familiar Unix -tools, making it intuitive for experienced users. The general syntax is: - -`srgn '' -- ''` - -Each component has a distinct role, as illustrated by the canonical `tr`-like -example from the documentation 1: - -Bash - -```sh -echo 'Hello World!' | srgn '[wW]orld' -- 'there' -# Output: Hello there! -``` - -- \`\`: These are flags that specify Actions (e.g., `--upper`, `--delete`) or - language-aware grammar Scopes (e.g., `--python`, `--rust`). - -- `''`: This is the mandatory, positional regular expression that defines the - final layer of text to be matched. In the example, it's `'[wW]orld'`. - -- \`\`: These are optional file or directory paths. If omitted, `srgn` reads - from standard input (`stdin`). If a directory is provided, `srgn` performs a - high-speed, recursive search for relevant files based on extensions and - shebangs.[^1] - -- `-- ''`: This is the optional replacement string. The `--` separator is a - critical safety feature that disambiguates the replacement string from file - paths or other arguments, especially when the replacement itself might - resemble a flag.[^1] - -If no replacement string or action flags are provided, `srgn` may enter its -"search mode," which transforms it into a powerful, syntax-aware search -tool.[^1] - -### 2.3 Search Mode: ripgrep with Syntactic Superpowers - -When a language flag (e.g., `--python` or its shorthand `--py` 9) is provided -without any accompanying actions or a replacement string, - -`srgn` enters search mode.[^1] The documentation describes this mode as -"'ripgrep but with syntactical language elements'".[^2] - -For instance, to find all class definitions in a Python project, one could run: - -Bash - -```sh -srgn --python 'class'. -``` - -The output mimics `grep` and `ripgrep`, prepending the file name and line -number to each match, making it easy to integrate into standard command-line -workflows.[^2] - -This mode is not only precise but also exceptionally fast. A benchmark cited in -the documentation demonstrates its performance: `srgn` can find approximately -140,000 occurrences of a regex pattern within Go string literals across the -entire Kubernetes codebase (\~3 million lines of code) in under 3 seconds on a -modern multi-core machine.[^1] This combination of speed and syntactic -precision makes search mode a formidable tool for code exploration and auditing. - -## Part 3: The Core Concept - Surgical Scoping - -### 3.1 What srgn Means by 'Scope': Textual Regions, Not Semantic Namespaces - -The term "scope" carries significant weight in programming, often referring to -semantic concepts of visibility and lifetime, such as Python's LEGB rule -(Local, Enclosing, Global, Built-in) or Rust's complex ownership and lifetime -scopes.[^10] A critical step in mastering - -`srgn` is understanding that its use of the term is different. - -In `srgn`, a "language grammar-aware scope" does not refer to a semantic -namespace but to a **textual region** of the source code that corresponds to a -specific node in its Abstract Syntax Tree (AST), as parsed by -`tree-sitter`.[^2] For example, the - -`--python 'function'` scope selects the entire block of text that constitutes a -function definition, from the `def` keyword to the end of its body. It does not -understand which variables are accessible within that function. - -This distinction is paramount. `srgn` operates on the code's grammatical -structure, not its compiled or interpreted meaning. It can identify all -comments, all string literals, or all function definitions, but it cannot -resolve a variable name to its declaration. This focus on syntactic structure -is the source of its speed and simplicity, but it also defines the boundaries -of its capabilities. - -### 3.2 The Scoping Pipeline: Layering with Logical AND - -The precision of `srgn` comes from its default mechanism of combining scopes: a -left-to-right, progressively narrowing filter that acts as a logical AND.[^2] -Each subsequent scope operates only on the text that was passed through by the -previous one. - -Consider the following command: - -Bash - -```sh -# Find all occurrences of 'github.com' but only inside docstrings of Python classes. -srgn --python 'class' --python 'doc-strings' 'github\.com' my_project/ -``` - -The execution pipeline for this command is as follows: - -1. **Initial Scope**: `srgn` first parses all files in `my_project/` and - identifies the textual regions of all `class` definitions. All other code is - discarded from consideration. - -2. **Intersection**: *Within the text of the class definitions only*, it then - identifies all regions corresponding to `doc-strings`. - -3. **Final Match**: Finally, *within the text of those docstrings only*, it - applies the regex `'github\.com'` to find the ultimate matches. - -This directional, filtering nature means the order of scopes is crucial. The -documentation provides a clear example of a nonsensical query, -`srgn --python 'doc-strings' --python 'class'`, which would attempt to find a -class definition *inside* a docstring and would almost certainly return no -results.[^1] This illustrates the power and predictability of the -intersectional pipeline. - -### 3.3 Broadening the Search: Joining Scopes with Logical OR - -While the default AND logic is excellent for drilling down, some tasks require -a broader search across different types of syntax. For this, `srgn` provides -the `--join-language-scopes` flag (or its shorthand, `-j`).[^2] This flag -alters the behavior for language scopes, changing the operation from -intersection (AND) to a union (OR). - -A practical example from the release notes demonstrates its utility 9: - -Bash - -```sh -# Find all TODOs, whether they are in comments or docstrings. -srgn -j --python comments --python doc-strings 'TODO:' src/ -``` - -Without the `-j` flag, this command would nonsensically search for docstrings -*inside* of comments. With `-j`, it creates a combined scope of all text that -is *either* a comment *or* a docstring, and then applies the `'TODO:'` regex to -that combined set. This is a common and powerful pattern for code maintenance -tasks. - -### 3.4 The Two Fundamental Scope Types - -To summarize, all `srgn` operations are built from two fundamental types of -scopes: - -1. **Language Grammar Scopes**: These are the predefined syntactic elements - specified with the `-- ''` syntax (e.g., - `--python 'class'`, `--rust 'unsafe'`). They leverage `tree-sitter` to - provide the foundational context awareness that sets `srgn` apart.[^1] A - reference list of known scopes is provided in the Appendix. - -2. **Regular Expression Scope**: This is the mandatory, positional argument - that provides the final, fine-grained pattern matching. It is always the - last filter applied in the pipeline, operating only on the text selected by - the preceding language scopes.[^2] - -## Part 4: Taking Action - Manipulation and Refactoring - -### 4.1 Simple and Dynamic Replacement - -The simplest action in `srgn` is replacement, specified with the -`-- 'replacement'` syntax. However, for any meaningful refactoring, dynamic -replacements are essential. `srgn` supports this through regex capture groups -(`$1`, `$2`, etc.), which substitute parts of the matched text into the -replacement string.[^2] - -A rich example from the documentation showcases several advanced features at -once 2: - -Bash - -```sh -srgn --python 'doc-strings' '(?` or `--py `) - -| Scope Name | Description | Example Command | -| ----------------------- | ------------------------------------------------------------------------- | --------------------------------------------- | -| class | Selects entire class definitions, from class to the end of the block. | srgn --py 'class' 'MyClass' | -| function | Selects entire function definitions, from def to the end of the block. | srgn --py 'function' 'my_func' | -| doc-strings | Selects the content of docstrings ("""...""" or '''...'''). | srgn --py 'doc-strings' 'TODO' | -| comments | Selects the content of line comments (#...). | srgn --py 'comments' 'FIXME' | -| strings | Selects the content of all string literals. | srgn --py 'strings' 'hardcoded-secret' | -| identifiers | Selects language identifiers (variable names, function names, etc.). | srgn --py 'identifiers' '^temp_\w+' | -| module-names-in-imports | Selects only the module names in import and from... import statements. | srgn --py 'module-names-in-imports' 'old_lib' | -| call | Selects entire function or method call expressions (e.g., foo(bar, baz)). | srgn --py 'call' '^print\(' | - -### A.[^3] Table: Rust Grammar Scopes (`--rust ` or `--rs `) - -| Scope Name | Description | Example Command | -| -------------------------- | -------------------------------------------------------------- | ------------------------------------------------------ | -| unsafe | Selects unsafe blocks and unsafe function definitions. | srgn --rs 'unsafe' '.' | -| comments | Selects the content of line (//) and block (/*...*/) comments. | srgn --rs 'comments' 'HACK' | -| strings | Selects the content of all string literals. | srgn --rs 'strings' 'password' | -| attribute | Selects the content of attributes (#[...] and #![...]). | srgn --rs 'attribute' 'deprecated' | -| names-in-uses-declarations | Selects only the crate/module paths within use statements. | srgn --rs 'names-in-uses-declarations' 'old_crate' | -| pub-enum | Selects public enum definitions. | srgn --rs 'pub-enum' 'MyEnum' | -| type-identifier | Selects identifiers that refer to a type. | srgn --rs 'pub-enum' --rs 'type-identifier' 'Subgenre' | -| struct | Selects struct definitions. | srgn --rs 'struct' 'RequestPayload' | -| impl | Selects impl blocks. | srgn --rs 'impl' 'MyTrait for MyStruct' | -| fn | Selects function definitions. | srgn --rs 'fn' 'main' | -| extern-crate | Selects extern crate...; declarations. | srgn --rs 'extern-crate' 'libc' | - -## Works Cited - - 1. alexpovel/srgn: A grep-like tool which understands source code syntax and - allows for manipulation in addition to search - GitHub, accessed on July - 11, 2025, - - 2. srgn/[README.md](http://README.md) at main · alexpovel/srgn · GitHub, - accessed on July 11, 2025, - - - 3. Lornatang/SRGAN-PyTorch: A simple and complete implementation of - super-resolution paper. - GitHub, accessed on July 11, 2025, - - - 4. hep-lbdl/SRGN - GitHub, accessed on July 11, 2025, - - - 5. Security - hep-lbdl/SRGN - GitHub, accessed on July 11, 2025, - - - 6. How to Open and Manage Leveraged $SRGN (SolRagon) Trades on Hyperliquid: A - Beginner's Tutorial · Issue #5 · synthesizearrayHSy/generatemonitorGhZ - - GitHub, accessed on July 11, 2025, - - - 7. srgn - Rust - [Docs.rs](http://Docs.rs), accessed on July 11, 2025, - - - 8. Pattern syntax - Semgrep, accessed on July 11, 2025, - - - 9. Releases · alexpovel/srgn - GitHub, accessed on July 11, 2025, - - -10. Python Scope & the LEGB Rule: Resolving Names in Your Code, accessed on - July 11, 2025, - -11. Scopes - The Rust Reference, accessed on July 11, 2025, - - -12. I can't understand the Rust "scope" definition (Rust Programming Language, - 2nd Ed. Klabnik & Nichols) - Stack Overflow, accessed on July 11, 2025, - - -13. betterletter/[README.md](http://README.md) at main · alexpovel/betterletter - · GitHub, accessed on July 11, 2025, - - -14. srgn - Rust Package Registry - [Crates.io](http://Crates.io), accessed on - July 11, 2025, - -15. accessed on January 1, 1970, - - -16. accessed on January 1, 1970, -