Print one section of a markdown file, picked by a fragment of its heading, with markdown-section
CI / tests (pull_request) Successful in 4m23s
CI / tests (pull_request) Successful in 4m23s
This commit is contained in:
@@ -74,6 +74,9 @@
|
||||
!bin/loop_state/*.py
|
||||
!bin/machine_load/
|
||||
!bin/machine_load/*.py
|
||||
!bin/markdown-section
|
||||
!bin/markdown_section/
|
||||
!bin/markdown_section/*.py
|
||||
!bin/metric-bench
|
||||
!bin/metric_bench/
|
||||
!bin/metric_bench/*.py
|
||||
|
||||
@@ -13,7 +13,7 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
|
||||
- **Open every chunk with one line:** the last version cut, how many changes are unreleased (the entries under `CHANGELOG.md` → `## Unreleased`, or else the commits since the last tag), and the release this chunk ships into. A repo that doesn't publish anything says so once.
|
||||
- **A client project's `CLAUDE.md` and `AGENTS.md` in its repo belong to its team.** Read both at the start of each chunk there. Propose each change that aligns them with this setup in a pull request of its own, never inside a chunk's; the one edit a chunk makes there is a decision's title in `AGENTS.md`. Until the team accepts a proposal, and after it declines or doesn't answer, follow the team's rule unless it breaks one of the project's goals. Record each such conflict as a decision in the `decisions` record, as `rules/decisions.md` asks: which rule you follow, why, and the open proposal's PR. Then nobody is asked twice.
|
||||
- **Read the goals file's `## Goals` and `## Audience` before starting a chunk, unless your prompt quotes them.** The chunk's items set its scope. The goals choose between ways to deliver those items, and never add to them.
|
||||
- **Read the plan and the decisions only as far as the chunk needs.** Where your prompt quotes `chunk-preflight`'s facts, they hold the next item's L, E + I, tagline and detail, and each item that may join it with its L, E + I, S, tagline and detail; run `todo-item` only for what they leave out. Otherwise run `~/.claude/bin/todo-item list`, which prints every item's row in the plan's order, without details. Then read the details of only the items the chunk takes, with `~/.claude/bin/todo-item show <ID>`, which prints an item's row and detail. `AGENTS.md` lists the project principles and the title of each decision no project principle covers. Read an entry in `docs/decisions.md` only where the project principle or the title leaves open what the chunk or the review needs.
|
||||
- **Read the plan and the decisions only as far as the chunk needs.** Where your prompt quotes `chunk-preflight`'s facts, they hold the next item's L, E + I, tagline and detail, and each item that may join it with its L, E + I, S, tagline and detail; run `todo-item` only for what they leave out. Otherwise run `~/.claude/bin/todo-item list`, which prints every item's row in the plan's order, without details. Then read the details of only the items the chunk takes, with `~/.claude/bin/todo-item show <ID>`, which prints an item's row and detail. `AGENTS.md` lists the project principles and the title of each decision no project principle covers. Read an entry in `docs/decisions.md` only where the project principle or the title leaves open what the chunk or the review needs, with `~/.claude/bin/markdown-section <file> <fragment of its title>`, which prints that one entry: `<file>` is what `~/.claude/bin/project-record open decisions` prints.
|
||||
- **Work one chunk at a time, and put every item that can share its review into it.** Every review has a fixed cost, so a chunk takes the next plan item plus every other item for which three things hold: they name one release; they fire the same review passes (`larv-review` §3); and no item outside the chunk blocks one of them. The items need not share a purpose. An item whose risk R, in the plan, is above 5 ships alone: it joins no chunk, and none joins it. The next plan item is the first that does not wait: an item waits while it is marked `question`, until the human answers, or while an item that blocks it is still in the plan. Tiny items, a few lines of change each, need not fire the same passes: bundle up to ten that name one release, and that no item outside the chunk blocks, into one chunk. Split a milestone into items in the plan before starting it. Fix a finding in the chunk's own change within the chunk. File a finding about anything else in `todo.md`.
|
||||
- **Ask, don't guess.** Three choices are always the human's: a goal; a release, meaning the items planned into it and when it is cut; and a change to loop-claude's routing ladder, its rungs included. Any other rule that asks the human's approval reserves that choice too. Ask about a reserved choice. For any other choice, first check whether the goals already answer it. If they nearly do, propose a change to the goals and show how it answers this case: an answer settles one question, a goal settles every question like it. Otherwise take the option you would recommend, and record it with its reason: in the item's detail, or, where it governs later work, as the next sentence says. A recommendation you can give a reason for is not a guess. Ask only where you have no recommendation. Write every answer once, where it belongs, never only in chat: a goal in the goals file, a working rule in `AGENTS.md`, a standing choice in a comment at the one place it governs, or in `docs/decisions.md` once made in more than one place. When an answer holds a goal and a choice, write the goal in the goals file, and record as a choice only what the goal leaves open.
|
||||
- **Bench a syntax with the people who write it.** Before a new or changed spelling of something users read or write ships — markdown, HTML, a config key, a CLI flag — a panel of fresh-context readers, seated as those users from the goals file's `## Audience`, picks it.
|
||||
|
||||
@@ -174,7 +174,7 @@ It renames `## Unreleased` in `CHANGELOG.md` to the version and merges that thro
|
||||
|
||||
## Tools
|
||||
|
||||
Install puts only `loop-claude` on `PATH`; call the others by their path, such as `~/.claude/bin/metric-bench`, from the project's checkout. Those under `~/.claude` are the release's; test a change to one from `~/code/claude-config/bin`.
|
||||
Install puts only `loop-claude` on `PATH`; call the others by their path, such as `~/.claude/bin/metric-bench`, from the project's checkout. Those under `~/.claude` are the release's; test a change to one from `~/code/claude-config/bin`. The list is in alphabetical order.
|
||||
|
||||
- `chunk-pr open|sync|ready|merge|clean` opens a chunk's pull request as a draft, brings its branch level with origin's default branch, marks it ready and merges it once its checks pass, with `gh` on a GitHub origin and `tea` elsewhere. The chunks of one project merge one at a time: in its turn, `merge` brings the branch level again, finishes the plan items its `--finish` flags name, and waits for the checks; once the pull request is merged, `clean` removes the chunk's worktree and branch and fast-forwards the main checkout. `chunk-pr --help` states the steps.
|
||||
- `chunk-preflight` finds the mechanical facts a chunk starts from, and with `--worktree` makes its worktree; `loop-claude` runs it with `--worktree` before it routes each chunk, and `chunk-preflight --help` lists the facts.
|
||||
@@ -184,6 +184,7 @@ Install puts only `loop-claude` on `PATH`; call the others by their path, such a
|
||||
- `judge-replay <model>` replays loop-claude's judge on archived verdicts of the projects run on the model, and prints what each rung a review climbs to misses, and the lowest rung below them that, like each candidate above it, returns them; `judge-replay --help` states the replay.
|
||||
- `larv-review <command>` holds larv-review's mechanical rules: the chunk's review folder, the paired ruling's base and vote count, each pass's round count and the opening of its round commit's title, the scoring run's trigger and setup; the comprehension history's format, its latest places and its count of how often seats agree; and each reviewer's prompt header. `larv-review --help` states them. `settings.json` → `hooks` runs `larv-review reviewer-context` as each subagent starts. A reviewer under `agents/` whose frontmatter has `omitClaudeMd: true` starts without `CLAUDE.md`, and the command hands it that file's "Shared goal", "Prose" and "Vocabulary" sections.
|
||||
- `loop-claude <task>` runs a project's next chunks, each in its own tmux window, cycle after cycle; `loop-claude --help` states its contract.
|
||||
- `markdown-section <file> <fragment>` prints the section of a markdown file under the first heading that holds the fragment, to the next heading of its level or a higher one, instead of a `grep -n` and a guessed `sed -n` range; `markdown-section --help` says what it does where several headings match.
|
||||
- `metric-bench [history]` benches cheap static metrics of a project's Python against the places its comprehension history names as hardest; `metric-bench --help` states the metrics and the scores.
|
||||
- `mutate-changes [--base <ref>] [--prefix <shell text>] [--jobs <n>]` mutation-tests the lines a branch changes and prints each mutant its tests don't kill; `mutate-changes --help` says which tool it runs for each language.
|
||||
- `notify [<message>]` sends a message, or else stdin, as a DM from the bot of the project's `notifier`, Mattermost or Slack, to the human; the project's `env-file` holds the bot's token, the recipient and, for Mattermost, the server, and `notify --help` names its keys. `loop-claude --help` says when loop-claude sends one.
|
||||
|
||||
Executable
+9
@@ -0,0 +1,9 @@
|
||||
#!/usr/bin/env python3
|
||||
import pathlib
|
||||
import sys
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
|
||||
|
||||
from markdown_section import main
|
||||
|
||||
sys.exit(main.main(sys.argv[1:]))
|
||||
@@ -0,0 +1,73 @@
|
||||
"""Print one section of a markdown file, picked by a fragment of its heading.
|
||||
|
||||
usage: markdown-section <file> <fragment>
|
||||
|
||||
The section runs from the first heading whose text holds the fragment, whatever its case, to the
|
||||
line before the next heading of the same or a higher level, so it holds its sub-sections. The
|
||||
heading's text is what follows its `#`s. A line inside a fenced code block is never a heading.
|
||||
Print a record kept outside the checkout through the file `project-record open <record>` prints.
|
||||
|
||||
Where no heading holds the fragment, it fails saying so. Where another heading outside that section
|
||||
holds it too, it fails listing each such heading with its line number, and prints no section: pass
|
||||
more of the heading you want.
|
||||
|
||||
Exit 2 on bad arguments, and 1, saying why, on any other failure.
|
||||
"""
|
||||
import pathlib
|
||||
import re
|
||||
import sys
|
||||
|
||||
from failure import Failure
|
||||
|
||||
HEADING = re.compile(r"^ {0,3}(#{1,6})[ \t]+(.*?)[ \t]*$")
|
||||
FENCE = re.compile(r"^ {0,3}(```|~~~)")
|
||||
|
||||
|
||||
def main(argv: list[str]) -> int:
|
||||
if argv[:1] in (["-h"], ["--help"]):
|
||||
print(__doc__.strip())
|
||||
return 0
|
||||
if len(argv) != 2:
|
||||
print("usage: markdown-section <file> <fragment>", file=sys.stderr)
|
||||
return 2
|
||||
try:
|
||||
text = pathlib.Path(argv[0]).read_text()
|
||||
except (OSError, UnicodeDecodeError) as error:
|
||||
print(f"markdown-section: {error}", file=sys.stderr)
|
||||
return 1
|
||||
found = section(text, argv[1])
|
||||
if isinstance(found, Failure):
|
||||
print(f"markdown-section: {found.reason}", file=sys.stderr)
|
||||
return 1
|
||||
print(found, end="")
|
||||
return 0
|
||||
|
||||
|
||||
def headings(lines: list[str]) -> list[tuple[int, int, str]]:
|
||||
"""Each heading outside a fenced code block, as its index in lines, its level and its text."""
|
||||
found = []
|
||||
fence = ""
|
||||
for index, line in enumerate(lines):
|
||||
opened = FENCE.match(line)
|
||||
if opened and fence in ("", opened.group(1)):
|
||||
fence = "" if fence else opened.group(1)
|
||||
elif not fence and (heading := HEADING.match(line)):
|
||||
found.append((index, len(heading.group(1)), heading.group(2)))
|
||||
return found
|
||||
|
||||
|
||||
def section(text: str, fragment: str) -> str | Failure:
|
||||
"""The section of text under the first heading that holds fragment, or a Failure where none does or several do."""
|
||||
lines = text.splitlines(keepends=True)
|
||||
found = headings(lines)
|
||||
matching = [at for at, (_, _, title) in enumerate(found) if fragment.lower() in title.lower()]
|
||||
if not matching:
|
||||
return Failure(f"no heading holds '{fragment}'")
|
||||
start, level, _ = found[matching[0]]
|
||||
end = next((index for index, deeper, _ in found[matching[0] + 1:] if deeper <= level), len(lines))
|
||||
# A matching heading inside the first one's section is part of what is printed, not a rival.
|
||||
rivals = [at for at in matching if found[at][0] >= end]
|
||||
if rivals:
|
||||
listed = "\n".join(f"{found[at][0] + 1}: {lines[found[at][0]].rstrip()}" for at in [matching[0], *rivals])
|
||||
return Failure(f"{len(rivals) + 1} headings hold '{fragment}', so use more of one:\n{listed}")
|
||||
return "".join(lines[start:end]).rstrip("\n") + "\n"
|
||||
@@ -0,0 +1,115 @@
|
||||
import pathlib
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from failure import Failure
|
||||
from markdown_section import main
|
||||
|
||||
TOOL = pathlib.Path(__file__).resolve().parents[1] / "markdown-section"
|
||||
|
||||
DOCUMENT = """# Title
|
||||
|
||||
Intro.
|
||||
|
||||
## Alpha
|
||||
|
||||
Alpha text.
|
||||
|
||||
### Alpha detail
|
||||
|
||||
Detail text.
|
||||
|
||||
## Beta Gamma
|
||||
|
||||
Beta text.
|
||||
|
||||
```
|
||||
## Not a heading
|
||||
```
|
||||
|
||||
## Delta
|
||||
|
||||
Delta text.
|
||||
"""
|
||||
|
||||
|
||||
class Section(unittest.TestCase):
|
||||
def test_the_fragment_is_matched_against_the_heading_text_without_its_hashes(self):
|
||||
self.assertEqual(main.section(DOCUMENT, "Alpha text"), Failure("no heading holds 'Alpha text'"))
|
||||
self.assertEqual(main.section(DOCUMENT, "## beta"), Failure("no heading holds '## beta'"))
|
||||
|
||||
def test_holds_its_sub_sections(self):
|
||||
self.assertEqual(main.section(DOCUMENT, "Alpha"), "## Alpha\n\nAlpha text.\n\n### Alpha detail\n\nDetail text.\n")
|
||||
|
||||
def test_a_sub_section_stops_at_a_higher_level_heading(self):
|
||||
self.assertEqual(main.section(DOCUMENT, "alpha detail"), "### Alpha detail\n\nDetail text.\n")
|
||||
|
||||
def test_the_fragment_matches_any_part_of_the_heading_whatever_its_case(self):
|
||||
self.assertTrue(str(main.section(DOCUMENT, "gamma")).startswith("## Beta Gamma\n"))
|
||||
|
||||
def test_a_fenced_line_that_looks_like_a_heading_neither_ends_nor_matches(self):
|
||||
self.assertEqual(main.section(DOCUMENT, "Beta"), "## Beta Gamma\n\nBeta text.\n\n```\n## Not a heading\n```\n")
|
||||
self.assertEqual(main.section(DOCUMENT, "not a heading"), Failure("no heading holds 'not a heading'"))
|
||||
|
||||
def test_the_last_section_runs_to_the_end_of_the_file(self):
|
||||
self.assertEqual(main.section(DOCUMENT, "delta"), "## Delta\n\nDelta text.\n")
|
||||
|
||||
def test_a_level_one_heading_holds_the_rest_of_the_document(self):
|
||||
self.assertEqual(main.section(DOCUMENT, "title"), DOCUMENT)
|
||||
|
||||
def test_several_matching_headings_fail_listing_each_with_its_line(self):
|
||||
listed = main.section("## Plan one\n\ntext\n\n## Plan two\n", "plan")
|
||||
self.assertEqual(listed, Failure("2 headings hold 'plan', so use more of one:\n1: ## Plan one\n5: ## Plan two"))
|
||||
|
||||
def test_a_heading_needs_a_space_after_its_hashes(self):
|
||||
self.assertEqual(main.section("#hashtag\n\n## Real\n", "hashtag"), Failure("no heading holds 'hashtag'"))
|
||||
|
||||
def test_no_heading_is_a_failure(self):
|
||||
self.assertEqual(main.section(DOCUMENT, "zeta"), Failure("no heading holds 'zeta'"))
|
||||
|
||||
|
||||
class BlackBox(unittest.TestCase):
|
||||
def setUp(self) -> None:
|
||||
self.file = pathlib.Path(self.enterContext(tempfile.TemporaryDirectory())) / "notes.md"
|
||||
self.file.write_text(DOCUMENT)
|
||||
|
||||
def run_tool(self, *args: str) -> subprocess.CompletedProcess[str]:
|
||||
return subprocess.run([sys.executable, str(TOOL), *args], capture_output=True, text=True)
|
||||
|
||||
def test_prints_the_section(self):
|
||||
ran = self.run_tool(str(self.file), "delta")
|
||||
self.assertEqual((ran.returncode, ran.stdout, ran.stderr), (0, "## Delta\n\nDelta text.\n", ""))
|
||||
|
||||
def test_exits_1_saying_why_where_no_heading_matches(self):
|
||||
ran = self.run_tool(str(self.file), "zeta")
|
||||
self.assertEqual((ran.returncode, ran.stdout, ran.stderr), (1, "", "markdown-section: no heading holds 'zeta'\n"))
|
||||
|
||||
def test_exits_1_listing_the_headings_where_several_match(self):
|
||||
ran = self.run_tool(str(self.file), "a")
|
||||
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
|
||||
self.assertIn("headings hold 'a'", ran.stderr)
|
||||
self.assertIn("5: ## Alpha", ran.stderr)
|
||||
|
||||
def test_exits_1_where_the_file_cant_be_read(self):
|
||||
ran = self.run_tool(str(self.file.with_name("missing.md")), "alpha")
|
||||
self.assertEqual((ran.returncode, ran.stdout), (1, ""))
|
||||
self.assertIn("markdown-section: ", ran.stderr)
|
||||
|
||||
def test_exits_2_with_the_usage_on_wrong_arguments(self):
|
||||
for args in ([], [str(self.file)], [str(self.file), "a", "b"]):
|
||||
ran = self.run_tool(*args)
|
||||
self.assertEqual((ran.returncode, ran.stdout), (2, ""), args)
|
||||
self.assertIn("usage: markdown-section <file> <fragment>", ran.stderr)
|
||||
|
||||
def test_help_prints_the_usage(self):
|
||||
ran = self.run_tool("--help")
|
||||
self.assertEqual(ran.returncode, 0)
|
||||
self.assertIn("usage: markdown-section <file> <fragment>", ran.stdout)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -2525,3 +2525,19 @@ Read most (opens and searches):
|
||||
- `bin/loop_claude/cycle/run.py` 4
|
||||
- `bin/loop_claude/loop/close.py` 3
|
||||
- `bin/model_routing/test_review_choice.py` 3
|
||||
|
||||
## Reading cost, chunk cfb3b6b8c710, finished 2026-11-17T08:13:19Z
|
||||
|
||||
182657 new input tokens before the first commit.
|
||||
|
||||
Read most (opens and searches):
|
||||
|
||||
- `docs/decisions.md` 13
|
||||
- `README.md` 5
|
||||
- `skills/larv-review/SKILL.md` 4
|
||||
- `CLAUDE.md` 3
|
||||
- `CHANGELOG.md` 1
|
||||
- `bin/loop_claude/cycle/prompts.py` 1
|
||||
- `bin/todo-item` 1
|
||||
- `rules/decisions.md` 1
|
||||
- `todo.md` 1
|
||||
|
||||
Reference in New Issue
Block a user