remold 0.1.0__tar.gz

remold-0.1.0/CHANGELOG.md

@@ -0,0 +1,6 @@
+<!-- do not remove -->
+
+## 0.1.0
+
+- Init commit
+

remold-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

remold-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+include CHANGELOG.md

remold-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: remold
+Version: 0.1.0
+Summary: Reshape Python source with LibCST: structure in the tree, comments and whitespace as plain text
+Author: remold contributors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/AnswerDotAI/remold
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: libcst
+Requires-Dist: ast-grep-py
+Provides-Extra: dev
+Requires-Dist: fastship; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# remold
+
+Concisely reshape Python code with [LibCST](https://github.com/Instagram/LibCST) or [ast-grep](https://ast-grep.github.io/).
+
+```bash
+pip install remold
+```
+
+Tools like `ast` throw comments away, and regex rewrites break on real code. remold keeps the source intact and gives you two ways to build composable `str -> str` transforms:
+
+- `astmap(*rules)` applies ast-grep pattern rules. Use it when you can write the rewrite as a before pattern and an after template. Only the matched span is replaced, so comments elsewhere are untouched.
+- `cstmap(matcher, fn, trivia='keep')` takes a [LibCST matcher](https://libcst.readthedocs.io/en/latest/matchers.html) and a function, for everything patterns can't express, including transforms that only change comments and whitespace. `fn(node, caps)` returns `None` (leave it), a string (reparsed in place, so the output is guaranteed to parse), or a CST node (full surgery).
+
+The idea behind `cstmap` is to match structure in the tree, where matching is easy, and to write the new code as a plain string, where comments and whitespace are just characters. Two helpers make that workable. `code(node)` renders any node back to source text, trivia included. `whereis(src, *frags)` tells you where LibCST keeps things, so you don't have to search the node docs.
+
+`from remold import *` gives you all four plus `cst` (libcst) and `m` (libcst.matchers).
+
+## Pattern rules
+
+Turn `test_fail(lambda: f(x), contains='boom')` into `with expect_fail(Exception, 'boom'): f(x)`:
+
+```python
+from remold import *
+
+fix_tests = astmap(
+    ("test_fail(lambda: $BODY, contains=$MSG)", "with expect_fail(Exception, $MSG): $BODY"),
+    ("test_fail(lambda: $BODY)",                "with expect_fail(Exception): $BODY"))
+
+print(fix_tests("test_fail(lambda: f(x), contains='boom')  # tricky case\n"))
+# with expect_fail(Exception, 'boom'): f(x)  # tricky case
+```
+
+Rules are applied in order, with a reparse between each, so later rules see the output of earlier ones. A replacement can also be a `callable(match) -> str` when the new text needs computing. Code that matches no pattern (like `test_fail(divide, args=(1,0))`) is left alone, and an unknown `$VAR` in a template raises a `KeyError`.
+
+## The same transform with matchers
+
+For rewrites patterns can't express, write a LibCST matcher and a function. Here is the same transform in that form:
+
+```python
+tf = m.SimpleStatementLine(body=[m.Expr(m.Call(
+    func=m.Name('test_fail'),
+    args=[m.Arg(m.Lambda(body=m.SaveMatchedNode(m.DoNotCare(), 'body'))),
+          m.Arg(keyword=m.Name('contains'), value=m.SaveMatchedNode(m.DoNotCare(), 'msg'))]))])
+
+def fix(node, caps): return f"with expect_fail(Exception, {code(caps['msg'])}): {code(caps['body'])}"
+
+fix_tests = cstmap(tf, fix)
+print(fix_tests("test_fail(lambda: f(x), contains='boom')  # tricky case\n"))
+# with expect_fail(Exception, 'boom'): f(x)  # tricky case
+```
+
+The trailing comment is kept because `trivia='keep'` (the default) copies the matched statement's leading lines and trailing comment onto whatever `fn` returns. The matcher also acts as a guard. A `test_fail(f, args=(1,0))` call doesn't match the arg spec, so it isn't changed.
+
+## Example: move a comment
+
+With `trivia='given'`, the string you return is used exactly as given, so to move a comment you write it where you want it:
+
+```python
+def fix(node, caps):
+    c = node.trailing_whitespace.comment
+    new = f"with expect_fail(Exception, {code(caps['msg'])}): {code(caps['body'])}"
+    return f"{code(c)}\n{new}" if c else new
+
+print(cstmap(tf, fix, trivia='given')("test_fail(lambda: f(), contains='x')  # ho\n"))
+# # ho
+# with expect_fail(Exception, 'x'): f()
+```
+
+A multi-line string becomes multiple statements, and returning `''` deletes the statement.
+
+## Example: reformat a signature
+
+Here the code itself doesn't change; only the comments and line layout do. The pieces are read from the tree, and the new layout is built with ordinary string operations:
+
+```python
+def fix(fd, _):
+    ps = [code(p).strip() for p in fd.params.params]      # each param arrives with its comment attached
+    c = fd.body.header.comment                            # a comment after ':' lives on the body header
+    if c: ps[-1] = f"{ps[-1]} {code(c)}"
+    return f"def {fd.name.value}(\n    " + "\n    ".join(ps) + "\n):" + code(fd.body.with_changes(header=cst.TrailingWhitespace()))
+
+src = """def f(foo, # hey
+      bam, # gg
+      bar): # ho
+    pass
+"""
+print(cstmap(m.FunctionDef(), fix, trivia='given')(src))
+# def f(
+#     foo, # hey
+#     bam, # gg
+#     bar # ho
+# ):
+#     pass
+```
+
+## Moving code across depths
+
+Indentation in LibCST is contextual, not literal. Statement lines, continuation lines inside brackets, and comment lines all record "indent goes here" rather than a column number, and the indent size comes from the target module's `default_indent`. Since `cstmap` parses your returned string as its own little module and splices the resulting statements into the real one, code written at one depth renders correctly at whatever depth it lands, in the target file's indent style. The one thing never re-indented is the content of multiline strings, since changing that would change the program.
+
+This makes depth-changing transforms work without any bookkeeping. Here a method is pulled out of its class and turned into a top-level fastcore `@patch` function. Note the trick: matching the `FunctionDef` would replace the method in place, still inside the class, so to *move* code you match the enclosing `ClassDef` and return the whole new arrangement. A multi-line replacement becomes several sibling statements.
+
+```python
+def fix(cd, _):
+    fs = [s for s in cd.body.body if m.matches(s, m.FunctionDef(name=m.Name('f')))]
+    if not fs: return None
+    fd = fs[0]
+    rest = cd.with_changes(body=cd.body.with_changes(body=[s for s in cd.body.body if s is not fd]))
+    p1 = code(fd.params.params[0]).strip().rstrip(',')
+    ps = ', '.join([f'{p1}:{cd.name.value}'] + [code(p).strip().rstrip(',') for p in fd.params.params[1:]])
+    return f"{code(rest)}\n@patch\ndef {fd.name.value}({ps}):{code(fd.body)}"
+
+src = """class A:
+    def __init__(self): self.x = 1
+
+    def f(self, n): # add `n` to `x`
+        y = self.x+n
+        return y
+"""
+print(cstmap(m.ClassDef(), fix, trivia='given')(src))
+# class A:
+#     def __init__(self): self.x = 1
+#
+# @patch
+# def f(self:A, n): # add `n` to `x`
+#     y = self.x+n
+#     return y
+```
+
+The method body was written at depth 2 and lands at depth 1; `code(fd.body)` carried it along with its comment, and the render re-indented it. The `self` parameter picks up the class as its type annotation, which is how `@patch` knows what to patch.
+
+## whereis
+
+How did that example know a comment after the colon is `fd.body.header.comment`? Ask:
+
+```python
+whereis(src, 'foo', '# ho', '# hey')
+# {'foo':   ['.body[0].params.params[0].name'],
+#  '# ho':  ['.body[0].body.header.comment', ...],
+#  '# hey': ['.body[0].params.params[0].comma.whitespace_after.first_line.comment', ...]}
+```
+
+Paste a representative snippet, ask for the fragments you care about, and copy the paths into your `fn`. Multiple entries per fragment list the node itself first, then its containers. `contains=True` matches fragments inside larger nodes.
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest -q
+```
+
+Version lives in `remold/__init__.py` as `__version__`; bump with `ship-bump`. Release with `ship-gh` and `ship-pypi`.

remold-0.1.0/README.md

@@ -0,0 +1,151 @@
+# remold
+
+Concisely reshape Python code with [LibCST](https://github.com/Instagram/LibCST) or [ast-grep](https://ast-grep.github.io/).
+
+```bash
+pip install remold
+```
+
+Tools like `ast` throw comments away, and regex rewrites break on real code. remold keeps the source intact and gives you two ways to build composable `str -> str` transforms:
+
+- `astmap(*rules)` applies ast-grep pattern rules. Use it when you can write the rewrite as a before pattern and an after template. Only the matched span is replaced, so comments elsewhere are untouched.
+- `cstmap(matcher, fn, trivia='keep')` takes a [LibCST matcher](https://libcst.readthedocs.io/en/latest/matchers.html) and a function, for everything patterns can't express, including transforms that only change comments and whitespace. `fn(node, caps)` returns `None` (leave it), a string (reparsed in place, so the output is guaranteed to parse), or a CST node (full surgery).
+
+The idea behind `cstmap` is to match structure in the tree, where matching is easy, and to write the new code as a plain string, where comments and whitespace are just characters. Two helpers make that workable. `code(node)` renders any node back to source text, trivia included. `whereis(src, *frags)` tells you where LibCST keeps things, so you don't have to search the node docs.
+
+`from remold import *` gives you all four plus `cst` (libcst) and `m` (libcst.matchers).
+
+## Pattern rules
+
+Turn `test_fail(lambda: f(x), contains='boom')` into `with expect_fail(Exception, 'boom'): f(x)`:
+
+```python
+from remold import *
+
+fix_tests = astmap(
+    ("test_fail(lambda: $BODY, contains=$MSG)", "with expect_fail(Exception, $MSG): $BODY"),
+    ("test_fail(lambda: $BODY)",                "with expect_fail(Exception): $BODY"))
+
+print(fix_tests("test_fail(lambda: f(x), contains='boom')  # tricky case\n"))
+# with expect_fail(Exception, 'boom'): f(x)  # tricky case
+```
+
+Rules are applied in order, with a reparse between each, so later rules see the output of earlier ones. A replacement can also be a `callable(match) -> str` when the new text needs computing. Code that matches no pattern (like `test_fail(divide, args=(1,0))`) is left alone, and an unknown `$VAR` in a template raises a `KeyError`.
+
+## The same transform with matchers
+
+For rewrites patterns can't express, write a LibCST matcher and a function. Here is the same transform in that form:
+
+```python
+tf = m.SimpleStatementLine(body=[m.Expr(m.Call(
+    func=m.Name('test_fail'),
+    args=[m.Arg(m.Lambda(body=m.SaveMatchedNode(m.DoNotCare(), 'body'))),
+          m.Arg(keyword=m.Name('contains'), value=m.SaveMatchedNode(m.DoNotCare(), 'msg'))]))])
+
+def fix(node, caps): return f"with expect_fail(Exception, {code(caps['msg'])}): {code(caps['body'])}"
+
+fix_tests = cstmap(tf, fix)
+print(fix_tests("test_fail(lambda: f(x), contains='boom')  # tricky case\n"))
+# with expect_fail(Exception, 'boom'): f(x)  # tricky case
+```
+
+The trailing comment is kept because `trivia='keep'` (the default) copies the matched statement's leading lines and trailing comment onto whatever `fn` returns. The matcher also acts as a guard. A `test_fail(f, args=(1,0))` call doesn't match the arg spec, so it isn't changed.
+
+## Example: move a comment
+
+With `trivia='given'`, the string you return is used exactly as given, so to move a comment you write it where you want it:
+
+```python
+def fix(node, caps):
+    c = node.trailing_whitespace.comment
+    new = f"with expect_fail(Exception, {code(caps['msg'])}): {code(caps['body'])}"
+    return f"{code(c)}\n{new}" if c else new
+
+print(cstmap(tf, fix, trivia='given')("test_fail(lambda: f(), contains='x')  # ho\n"))
+# # ho
+# with expect_fail(Exception, 'x'): f()
+```
+
+A multi-line string becomes multiple statements, and returning `''` deletes the statement.
+
+## Example: reformat a signature
+
+Here the code itself doesn't change; only the comments and line layout do. The pieces are read from the tree, and the new layout is built with ordinary string operations:
+
+```python
+def fix(fd, _):
+    ps = [code(p).strip() for p in fd.params.params]      # each param arrives with its comment attached
+    c = fd.body.header.comment                            # a comment after ':' lives on the body header
+    if c: ps[-1] = f"{ps[-1]} {code(c)}"
+    return f"def {fd.name.value}(\n    " + "\n    ".join(ps) + "\n):" + code(fd.body.with_changes(header=cst.TrailingWhitespace()))
+
+src = """def f(foo, # hey
+      bam, # gg
+      bar): # ho
+    pass
+"""
+print(cstmap(m.FunctionDef(), fix, trivia='given')(src))
+# def f(
+#     foo, # hey
+#     bam, # gg
+#     bar # ho
+# ):
+#     pass
+```
+
+## Moving code across depths
+
+Indentation in LibCST is contextual, not literal. Statement lines, continuation lines inside brackets, and comment lines all record "indent goes here" rather than a column number, and the indent size comes from the target module's `default_indent`. Since `cstmap` parses your returned string as its own little module and splices the resulting statements into the real one, code written at one depth renders correctly at whatever depth it lands, in the target file's indent style. The one thing never re-indented is the content of multiline strings, since changing that would change the program.
+
+This makes depth-changing transforms work without any bookkeeping. Here a method is pulled out of its class and turned into a top-level fastcore `@patch` function. Note the trick: matching the `FunctionDef` would replace the method in place, still inside the class, so to *move* code you match the enclosing `ClassDef` and return the whole new arrangement. A multi-line replacement becomes several sibling statements.
+
+```python
+def fix(cd, _):
+    fs = [s for s in cd.body.body if m.matches(s, m.FunctionDef(name=m.Name('f')))]
+    if not fs: return None
+    fd = fs[0]
+    rest = cd.with_changes(body=cd.body.with_changes(body=[s for s in cd.body.body if s is not fd]))
+    p1 = code(fd.params.params[0]).strip().rstrip(',')
+    ps = ', '.join([f'{p1}:{cd.name.value}'] + [code(p).strip().rstrip(',') for p in fd.params.params[1:]])
+    return f"{code(rest)}\n@patch\ndef {fd.name.value}({ps}):{code(fd.body)}"
+
+src = """class A:
+    def __init__(self): self.x = 1
+
+    def f(self, n): # add `n` to `x`
+        y = self.x+n
+        return y
+"""
+print(cstmap(m.ClassDef(), fix, trivia='given')(src))
+# class A:
+#     def __init__(self): self.x = 1
+#
+# @patch
+# def f(self:A, n): # add `n` to `x`
+#     y = self.x+n
+#     return y
+```
+
+The method body was written at depth 2 and lands at depth 1; `code(fd.body)` carried it along with its comment, and the render re-indented it. The `self` parameter picks up the class as its type annotation, which is how `@patch` knows what to patch.
+
+## whereis
+
+How did that example know a comment after the colon is `fd.body.header.comment`? Ask:
+
+```python
+whereis(src, 'foo', '# ho', '# hey')
+# {'foo':   ['.body[0].params.params[0].name'],
+#  '# ho':  ['.body[0].body.header.comment', ...],
+#  '# hey': ['.body[0].params.params[0].comma.whitespace_after.first_line.comment', ...]}
+```
+
+Paste a representative snippet, ask for the fragments you care about, and copy the paths into your `fn`. Multiple entries per fragment list the node itself first, then its containers. `contains=True` matches fragments inside larger nodes.
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest -q
+```
+
+Version lives in `remold/__init__.py` as `__version__`; bump with `ship-bump`. Release with `ship-gh` and `ship-pypi`.

remold-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "remold"
+dynamic = ["version"]
+description = "Reshape Python source with LibCST: structure in the tree, comments and whitespace as plain text"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "remold contributors" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+]
+
+dependencies = ["libcst", "ast-grep-py"]
+
+[project.optional-dependencies]
+dev = [
+  "fastship",
+  "build",
+  "twine",
+]
+
+[project.urls]
+Homepage = "https://github.com/AnswerDotAI/remold"
+
+[tool.setuptools.dynamic]
+version = { attr = "remold.__version__" }
+
+[tool.setuptools.packages.find]
+include = ["remold"]

remold-0.1.0/remold/__init__.py

@@ -0,0 +1,125 @@
+"""Reshape Python source with LibCST: match structure in the tree, write the new code as plain text, and comments and whitespace come along as ordinary characters."""
+
+__version__ = "0.1.0"
+
+import re
+from dataclasses import fields
+
+import libcst as cst
+import libcst.matchers as m
+from ast_grep_py import SgRoot
+
+__all__ = ['cst', 'm', 'astmap', 'cstmap', 'code', 'whereis']
+
+def _expand(tmpl, mch):
+    "Fill `$VAR` holes in `tmpl` from ast-grep match `mch`"
+    def _sub(mo):
+        node = mch.get_match(mo.group(1))
+        if node is None: raise KeyError(f'${mo.group(1)} not captured by the pattern')
+        return node.text()
+    return re.sub(r'\$([A-Z_][A-Z0-9_]*)', _sub, tmpl)
+
+def astmap(
+    *rules # (pattern, repl) pairs; repl is a `$VAR` template or a callable(match)->str
+):
+    "A `str->str` source transform: apply ast-grep pattern rules in order, reparsing between rules"
+    def _f(src):
+        for pat,repl in rules:
+            root = SgRoot(src, 'python').root()
+            edits = [mch.replace(repl(mch) if callable(repl) else _expand(repl, mch))
+                     for mch in root.find_all(pattern=pat)]
+            if edits: src = root.commit_edits(edits)
+        return src
+    return _f
+
+_render = cst.Module([]).code_for_node
+
+def code(node):
+    "Source text for `node`, trivia included"
+    return _render(node)
+
+def _reparse(node, s):
+    "Parse `s` as whatever fits where `node` sits"
+    if isinstance(node, (cst.SimpleStatementLine, cst.BaseCompoundStatement)):
+        mod = cst.parse_module(s)
+        stmts = list(mod.body)
+        if any(l.comment for l in mod.footer):
+            raise ValueError(f'{s!r} ends with a comment after its last statement, which no statement node can carry; put it before or inline')
+        if not stmts: return cst.RemovalSentinel.REMOVE
+        if mod.header: stmts[0] = stmts[0].with_changes(leading_lines=[*mod.header, *stmts[0].leading_lines])
+        return stmts[0] if len(stmts)==1 else cst.FlattenSentinel(stmts)
+    if isinstance(node, cst.BaseSmallStatement):
+        stmts = cst.parse_module(s).body
+        if len(stmts)==1 and isinstance(stmts[0], cst.SimpleStatementLine) and len(stmts[0].body)==1: return stmts[0].body[0]
+        raise ValueError(f'{s!r} is not a single small statement, which is what {type(node).__name__} sits as')
+    if isinstance(node, cst.BaseExpression): return cst.parse_expression(s)
+    raise TypeError(f"Can't reparse a str in place of {type(node).__name__}; return a CST node instead")
+
+def _trailing(n):
+    "The `TrailingWhitespace` of statement `n`, or None"
+    if isinstance(n, cst.SimpleStatementLine): return n.trailing_whitespace
+    if isinstance(n, cst.BaseCompoundStatement):
+        if isinstance(n.body, cst.SimpleStatementSuite): return n.body.trailing_whitespace
+        if isinstance(n.body, cst.IndentedBlock): return n.body.header
+    return None
+
+def _set_trailing(n, tw):
+    if isinstance(n, cst.SimpleStatementLine): return n.with_changes(trailing_whitespace=tw)
+    if isinstance(n, cst.BaseCompoundStatement):
+        if isinstance(n.body, cst.SimpleStatementSuite): return n.with_changes(body=n.body.with_changes(trailing_whitespace=tw))
+        if isinstance(n.body, cst.IndentedBlock): return n.with_changes(body=n.body.with_changes(header=tw))
+    return n
+
+def _keep_trivia(old, new):
+    "Carry `old`'s leading lines and trailing comment onto `new`"
+    nodes = list(new.nodes) if isinstance(new, cst.FlattenSentinel) else [new]
+    if hasattr(old, 'leading_lines') and hasattr(nodes[0], 'leading_lines'):
+        nodes[0] = nodes[0].with_changes(leading_lines=old.leading_lines)
+    tw = _trailing(old)
+    if tw is not None and tw.comment is not None: nodes[-1] = _set_trailing(nodes[-1], tw)
+    return cst.FlattenSentinel(nodes) if isinstance(new, cst.FlattenSentinel) else nodes[0]
+
+class _Mapper(cst.CSTTransformer):
+    def __init__(self, matcher, fn, trivia):
+        super().__init__()
+        self.matcher,self.fn,self.trivia = matcher,fn,trivia
+
+    def on_leave(self, orig, updated):
+        caps = m.extract(updated, self.matcher)
+        if caps is None: return updated
+        res = self.fn(updated, caps)
+        if res is None: return updated
+        if isinstance(res, str): res = _reparse(updated, res)
+        if self.trivia=='keep' and not isinstance(res, cst.RemovalSentinel): res = _keep_trivia(updated, res)
+        return res
+
+def cstmap(
+    matcher, # A `libcst.matchers` matcher; `m.SaveMatchedNode` captures arrive in `fn`'s second arg
+    fn, # `fn(node, caps)` returning None (leave unchanged), a str (reparsed in context), or a CST node
+    trivia:str='keep' # 'keep' carries the matched node's leading lines and trailing comment; 'given' means fn's output is everything
+):
+    "A `str->str` source transform: replace every node matching `matcher` with `fn`'s result"
+    def _f(src): return cst.parse_module(src).visit(_Mapper(matcher, fn, trivia)).code
+    return _f
+
+def _walk(node, path=''):
+    yield path, node
+    for f in fields(node):
+        v = getattr(node, f.name)
+        if isinstance(v, cst.CSTNode): yield from _walk(v, f'{path}.{f.name}')
+        elif isinstance(v, (tuple, list)):
+            for i,x in enumerate(v):
+                if isinstance(x, cst.CSTNode): yield from _walk(x, f'{path}.{f.name}[{i}]')
+
+def whereis(
+    src:str, # Source snippet to interrogate
+    *frags:str, # Fragments to locate, e.g. 'foo', '# ho'
+    contains:bool=False # Match nodes containing the fragment, not just equal to it
+) -> dict:
+    "For each fragment, the attribute paths where LibCST keeps it, deepest node first"
+    mod = cst.parse_module(src)
+    def _hit(n, frag):
+        c = _render(n).strip()
+        return frag in c if contains else c==frag
+    return {frag: [p for p,n in sorted(((p,n) for p,n in _walk(mod) if p and _hit(n, frag)), key=lambda o: -len(o[0]))]
+            for frag in frags}

remold-0.1.0/remold.egg-info/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: remold
+Version: 0.1.0
+Summary: Reshape Python source with LibCST: structure in the tree, comments and whitespace as plain text
+Author: remold contributors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/AnswerDotAI/remold
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: libcst
+Requires-Dist: ast-grep-py
+Provides-Extra: dev
+Requires-Dist: fastship; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# remold
+
+Concisely reshape Python code with [LibCST](https://github.com/Instagram/LibCST) or [ast-grep](https://ast-grep.github.io/).
+
+```bash
+pip install remold
+```
+
+Tools like `ast` throw comments away, and regex rewrites break on real code. remold keeps the source intact and gives you two ways to build composable `str -> str` transforms:
+
+- `astmap(*rules)` applies ast-grep pattern rules. Use it when you can write the rewrite as a before pattern and an after template. Only the matched span is replaced, so comments elsewhere are untouched.
+- `cstmap(matcher, fn, trivia='keep')` takes a [LibCST matcher](https://libcst.readthedocs.io/en/latest/matchers.html) and a function, for everything patterns can't express, including transforms that only change comments and whitespace. `fn(node, caps)` returns `None` (leave it), a string (reparsed in place, so the output is guaranteed to parse), or a CST node (full surgery).
+
+The idea behind `cstmap` is to match structure in the tree, where matching is easy, and to write the new code as a plain string, where comments and whitespace are just characters. Two helpers make that workable. `code(node)` renders any node back to source text, trivia included. `whereis(src, *frags)` tells you where LibCST keeps things, so you don't have to search the node docs.
+
+`from remold import *` gives you all four plus `cst` (libcst) and `m` (libcst.matchers).
+
+## Pattern rules
+
+Turn `test_fail(lambda: f(x), contains='boom')` into `with expect_fail(Exception, 'boom'): f(x)`:
+
+```python
+from remold import *
+
+fix_tests = astmap(
+    ("test_fail(lambda: $BODY, contains=$MSG)", "with expect_fail(Exception, $MSG): $BODY"),
+    ("test_fail(lambda: $BODY)",                "with expect_fail(Exception): $BODY"))
+
+print(fix_tests("test_fail(lambda: f(x), contains='boom')  # tricky case\n"))
+# with expect_fail(Exception, 'boom'): f(x)  # tricky case
+```
+
+Rules are applied in order, with a reparse between each, so later rules see the output of earlier ones. A replacement can also be a `callable(match) -> str` when the new text needs computing. Code that matches no pattern (like `test_fail(divide, args=(1,0))`) is left alone, and an unknown `$VAR` in a template raises a `KeyError`.
+
+## The same transform with matchers
+
+For rewrites patterns can't express, write a LibCST matcher and a function. Here is the same transform in that form:
+
+```python
+tf = m.SimpleStatementLine(body=[m.Expr(m.Call(
+    func=m.Name('test_fail'),
+    args=[m.Arg(m.Lambda(body=m.SaveMatchedNode(m.DoNotCare(), 'body'))),
+          m.Arg(keyword=m.Name('contains'), value=m.SaveMatchedNode(m.DoNotCare(), 'msg'))]))])
+
+def fix(node, caps): return f"with expect_fail(Exception, {code(caps['msg'])}): {code(caps['body'])}"
+
+fix_tests = cstmap(tf, fix)
+print(fix_tests("test_fail(lambda: f(x), contains='boom')  # tricky case\n"))
+# with expect_fail(Exception, 'boom'): f(x)  # tricky case
+```
+
+The trailing comment is kept because `trivia='keep'` (the default) copies the matched statement's leading lines and trailing comment onto whatever `fn` returns. The matcher also acts as a guard. A `test_fail(f, args=(1,0))` call doesn't match the arg spec, so it isn't changed.
+
+## Example: move a comment
+
+With `trivia='given'`, the string you return is used exactly as given, so to move a comment you write it where you want it:
+
+```python
+def fix(node, caps):
+    c = node.trailing_whitespace.comment
+    new = f"with expect_fail(Exception, {code(caps['msg'])}): {code(caps['body'])}"
+    return f"{code(c)}\n{new}" if c else new
+
+print(cstmap(tf, fix, trivia='given')("test_fail(lambda: f(), contains='x')  # ho\n"))
+# # ho
+# with expect_fail(Exception, 'x'): f()
+```
+
+A multi-line string becomes multiple statements, and returning `''` deletes the statement.
+
+## Example: reformat a signature
+
+Here the code itself doesn't change; only the comments and line layout do. The pieces are read from the tree, and the new layout is built with ordinary string operations:
+
+```python
+def fix(fd, _):
+    ps = [code(p).strip() for p in fd.params.params]      # each param arrives with its comment attached
+    c = fd.body.header.comment                            # a comment after ':' lives on the body header
+    if c: ps[-1] = f"{ps[-1]} {code(c)}"
+    return f"def {fd.name.value}(\n    " + "\n    ".join(ps) + "\n):" + code(fd.body.with_changes(header=cst.TrailingWhitespace()))
+
+src = """def f(foo, # hey
+      bam, # gg
+      bar): # ho
+    pass
+"""
+print(cstmap(m.FunctionDef(), fix, trivia='given')(src))
+# def f(
+#     foo, # hey
+#     bam, # gg
+#     bar # ho
+# ):
+#     pass
+```
+
+## Moving code across depths
+
+Indentation in LibCST is contextual, not literal. Statement lines, continuation lines inside brackets, and comment lines all record "indent goes here" rather than a column number, and the indent size comes from the target module's `default_indent`. Since `cstmap` parses your returned string as its own little module and splices the resulting statements into the real one, code written at one depth renders correctly at whatever depth it lands, in the target file's indent style. The one thing never re-indented is the content of multiline strings, since changing that would change the program.
+
+This makes depth-changing transforms work without any bookkeeping. Here a method is pulled out of its class and turned into a top-level fastcore `@patch` function. Note the trick: matching the `FunctionDef` would replace the method in place, still inside the class, so to *move* code you match the enclosing `ClassDef` and return the whole new arrangement. A multi-line replacement becomes several sibling statements.
+
+```python
+def fix(cd, _):
+    fs = [s for s in cd.body.body if m.matches(s, m.FunctionDef(name=m.Name('f')))]
+    if not fs: return None
+    fd = fs[0]
+    rest = cd.with_changes(body=cd.body.with_changes(body=[s for s in cd.body.body if s is not fd]))
+    p1 = code(fd.params.params[0]).strip().rstrip(',')
+    ps = ', '.join([f'{p1}:{cd.name.value}'] + [code(p).strip().rstrip(',') for p in fd.params.params[1:]])
+    return f"{code(rest)}\n@patch\ndef {fd.name.value}({ps}):{code(fd.body)}"
+
+src = """class A:
+    def __init__(self): self.x = 1
+
+    def f(self, n): # add `n` to `x`
+        y = self.x+n
+        return y
+"""
+print(cstmap(m.ClassDef(), fix, trivia='given')(src))
+# class A:
+#     def __init__(self): self.x = 1
+#
+# @patch
+# def f(self:A, n): # add `n` to `x`
+#     y = self.x+n
+#     return y
+```
+
+The method body was written at depth 2 and lands at depth 1; `code(fd.body)` carried it along with its comment, and the render re-indented it. The `self` parameter picks up the class as its type annotation, which is how `@patch` knows what to patch.
+
+## whereis
+
+How did that example know a comment after the colon is `fd.body.header.comment`? Ask:
+
+```python
+whereis(src, 'foo', '# ho', '# hey')
+# {'foo':   ['.body[0].params.params[0].name'],
+#  '# ho':  ['.body[0].body.header.comment', ...],
+#  '# hey': ['.body[0].params.params[0].comma.whitespace_after.first_line.comment', ...]}
+```
+
+Paste a representative snippet, ask for the fragments you care about, and copy the paths into your `fn`. Multiple entries per fragment list the node itself first, then its containers. `contains=True` matches fragments inside larger nodes.
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest -q
+```
+
+Version lives in `remold/__init__.py` as `__version__`; bump with `ship-bump`. Release with `ship-gh` and `ship-pypi`.

remold-0.1.0/remold.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+CHANGELOG.md
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+remold/__init__.py
+remold.egg-info/PKG-INFO
+remold.egg-info/SOURCES.txt
+remold.egg-info/dependency_links.txt
+remold.egg-info/requires.txt
+remold.egg-info/top_level.txt
+tests/test_remold.py

remold-0.1.0/remold.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

remold-0.1.0/remold.egg-info/requires.txt

@@ -0,0 +1,7 @@
+libcst
+ast-grep-py
+
+[dev]
+fastship
+build
+twine

remold-0.1.0/remold.egg-info/top_level.txt

@@ -0,0 +1 @@
+remold

remold-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

remold-0.1.0/tests/test_remold.py

@@ -0,0 +1,134 @@
+import pytest
+from remold import cst, m, astmap, cstmap, code, whereis
+
+tf = m.SimpleStatementLine(body=[m.Expr(m.Call(
+    func=m.Name('test_fail'),
+    args=[m.Arg(m.Lambda(body=m.SaveMatchedNode(m.DoNotCare(), 'body'))),
+          m.Arg(keyword=m.Name('contains'), value=m.SaveMatchedNode(m.DoNotCare(), 'msg'))]))])
+
+def _fix(node, caps): return f"with expect_fail(Exception, {code(caps['msg'])}): {code(caps['body'])}"
+
+
+def test_astmap():
+    fix = astmap(("test_fail(lambda: $BODY, contains=$MSG)", "with expect_fail(Exception, $MSG): $BODY"),
+                 ("test_fail(lambda: $BODY)", "with expect_fail(Exception): $BODY"))
+    src = "x = 1\ntest_fail(lambda: f(x), contains='boom')  # why\ntest_fail(lambda: g())\n"
+    assert fix(src) == "x = 1\nwith expect_fail(Exception, 'boom'): f(x)  # why\nwith expect_fail(Exception): g()\n"
+
+    # non-matching forms pass through, later rules see earlier rules' output
+    assert fix("test_fail(divide, args=(1,0))\n") == "test_fail(divide, args=(1,0))\n"
+    two = astmap(("a()", "b()"), ("b()", "c()"))
+    assert two("a()\n") == "c()\n"
+
+    # a callable replacement gets the raw ast-grep match
+    up = astmap(("print($X)", lambda mch: f"log({mch['X'].text().upper()})"))
+    assert up("print(msg)\n") == "log(MSG)\n"
+
+    # unknown metavariables in the template fail loudly
+    with pytest.raises(KeyError): astmap(("print($X)", "log($Y)"))("print(msg)\n")
+
+
+def test_cstmap():
+    src = "x = 1\ntest_fail(lambda: f(x), contains='boom')  # why\ny = 2\n"
+    assert cstmap(tf, _fix)(src) == "x = 1\nwith expect_fail(Exception, 'boom'): f(x)  # why\ny = 2\n"
+
+    # leading comments and blank lines survive too
+    src = "# setup\n\ntest_fail(lambda: g(), contains='no')\n"
+    assert cstmap(tf, _fix)(src) == "# setup\n\nwith expect_fail(Exception, 'no'): g()\n"
+
+    # works at any indentation depth
+    src = "def t():\n    test_fail(lambda: f(1), contains='boom')  # why\n"
+    assert cstmap(tf, _fix)(src) == "def t():\n    with expect_fail(Exception, 'boom'): f(1)  # why\n"
+
+    # expression context: replacement string parsed as an expression
+    up = cstmap(m.Name('a'), lambda n,c: 'a2')
+    assert up("b = a + a  # keep\n") == "b = a2 + a2  # keep\n"
+
+    # returning None leaves the node alone; non-matching text untouched
+    assert cstmap(tf, lambda n,c: None)("test_fail(lambda: f(), contains='x')\n") == "test_fail(lambda: f(), contains='x')\n"
+    assert cstmap(tf, _fix)("test_fail(divide, args=(1,0))\n") == "test_fail(divide, args=(1,0))\n"
+
+    # returning a node is full-surgery mode
+    ren = cstmap(m.Name('old'), lambda n,c: n.with_changes(value='new'))
+    assert ren("old = old + 1\n") == "new = new + 1\n"
+
+
+def test_trivia():
+    src = "test_fail(lambda: f(), contains='x')  # ho\n"
+    # trivia='given': the returned string is the whole truth, so the comment moves where fn puts it
+    def fix(node, caps):
+        c = node.trailing_whitespace.comment
+        new = f"with expect_fail(Exception, {code(caps['msg'])}): {code(caps['body'])}"
+        return f"{code(c)}\n{new}" if c else new
+    assert cstmap(tf, fix, trivia='given')(src) == "# ho\nwith expect_fail(Exception, 'x'): f()\n"
+
+    # the moved comment indents contextually when the statement is nested
+    src = "def t():\n    test_fail(lambda: f(), contains='x')  # ho\n"
+    assert cstmap(tf, fix, trivia='given')(src) == "def t():\n    # ho\n    with expect_fail(Exception, 'x'): f()\n"
+
+    # multi-statement strings expand in place
+    dup = cstmap(m.SimpleStatementLine(body=[m.Expr(m.Call(func=m.Name('once')))]), lambda n,c: "first()\nsecond()")
+    assert dup("a = 1\nonce()\n") == "a = 1\nfirst()\nsecond()\n"
+
+    # empty string removes the statement
+    rm = cstmap(m.SimpleStatementLine(body=[m.Expr(m.Call(func=m.Name('gone')))]), lambda n,c: '')
+    assert rm("gone()\nkeep()\n") == "keep()\n"
+
+    # unparseable replacement fails loudly
+    bad = cstmap(tf, lambda n,c: 'def broken(')
+    with pytest.raises(cst.ParserSyntaxError): bad("test_fail(lambda: f(), contains='x')\n")
+
+
+def test_relayout():
+    # the README signature example: code unchanged, comments and line structure are the payload
+    def fix(fd, _):
+        ps = [code(p).strip() for p in fd.params.params]
+        c = fd.body.header.comment
+        if c: ps[-1] = f"{ps[-1]} {code(c)}"
+        return f"def {fd.name.value}(\n    " + "\n    ".join(ps) + "\n):" + code(fd.body.with_changes(header=cst.TrailingWhitespace()))
+
+    src = "def f(foo, # hey\n      bam, # gg\n      bar): # ho\n    pass\n"
+    assert cstmap(m.FunctionDef(), fix, trivia='given')(src) == (
+        "def f(\n    foo, # hey\n    bam, # gg\n    bar # ho\n):\n    pass\n")
+
+    # continuation-line whitespace is contextual in LibCST, so nested defs re-indent correctly
+    src = "class A:\n    def f(foo, # hey\n          bam,\n          bar): # ho\n        pass\n"
+    assert cstmap(m.FunctionDef(), fix, trivia='given')(src) == (
+        "class A:\n    def f(\n        foo, # hey\n        bam,\n        bar # ho\n    ):\n        pass\n")
+
+
+def test_move_across_depths():
+    # extract a method to a top-level fastcore-style @patch function: match the *enclosing* ClassDef
+    # (matching the method would replace it in place), return the new arrangement as one string
+    def fix(cd, _):
+        fs = [s for s in cd.body.body if m.matches(s, m.FunctionDef(name=m.Name('f')))]
+        if not fs: return None
+        fd = fs[0]
+        rest = cd.with_changes(body=cd.body.with_changes(body=[s for s in cd.body.body if s is not fd]))
+        p1 = code(fd.params.params[0]).strip().rstrip(',')
+        ps = ', '.join([f'{p1}:{cd.name.value}'] + [code(p).strip().rstrip(',') for p in fd.params.params[1:]])
+        return f"{code(rest)}\n@patch\ndef {fd.name.value}({ps}):{code(fd.body)}"
+
+    src = ("class A:\n    def __init__(self): self.x = 1\n\n"
+           "    def f(self, n): # add `n` to `x`\n        y = self.x+n\n        return y\n")
+    assert cstmap(m.ClassDef(), fix, trivia='given')(src) == (
+        "class A:\n    def __init__(self): self.x = 1\n\n"
+        "@patch\ndef f(self:A, n): # add `n` to `x`\n    y = self.x+n\n    return y\n")
+
+
+def test_whereis():
+    src = "def f(foo, # hey\n      bam, # gg\n      bar): # ho\n    pass\n"
+    w = whereis(src, 'foo', '# ho', '# hey')
+    assert w['foo'] == ['.body[0].params.params[0].name']
+    assert w['# ho'][0] == '.body[0].body.header.comment'
+    assert w['# hey'][0] == '.body[0].params.params[0].comma.whitespace_after.first_line.comment'
+    # contains=True finds fragments inside larger nodes
+    w = whereis(src, 'hey', contains=True)
+    assert '.body[0].params.params[0].comma.whitespace_after.first_line.comment' in w['hey']
+
+
+def test_code():
+    node = cst.parse_expression('f(x,  y)')
+    assert code(node) == 'f(x,  y)'
+    p = cst.parse_module("def f(foo, # hey\n      bar): pass\n").body[0].params.params[0]
+    assert code(p) == 'foo, # hey\n      '