Refactoring Section - #12
Merged
Merged
Conversation
…n examples New section /refactorings/: the Constructive Programming refactoring catalogue (35 entries across plain, higher-kinded and dependent types), driven by _data/refactorings.yml; the 2019 post that held the list is removed. First entry, /refactorings/extract-method/: the OO move (Fowler, Opdyke, Griswold) read as Burstall–Darlington define-and-fold, with lambda lifting/dropping, let-floating, the GHC inliner and HaRe as the same move at other scales; the extract/inline pair as one equation; the five cases where it is not an equivalence; 15 verified references. Three examples, each Before/After/Spec in Scala 3 and Haskell, included verbatim into the page and proven equivalent with hedgehog properties on both sides (run.sh runs all six; docker fallback for GHC). An independent review mutation-tested every spec (12 mutants caught) and probed strictness, evaluation count, Int boundaries and totality. Inline SVG diagrams for the koan and each example. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HspK7yTkC5Jw5aiMV1Jqeq
…e catalogue .claude/skills/refactoring-entry/: SKILL.md (procedure), brief.md (agent brief template), workflow.js (research ∥ examples → mutation-review loop → diagrams, parameterised by slug) and LESSONS.md (append-only log and calibration table; every run must add what it learned and fold rules back into the procedure). Seeded with everything the extract-method run learned: toolchain, generator calibration, reviewer findings, Jekyll plumbing. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HspK7yTkC5Jw5aiMV1Jqeq
Contributor
|
kryptt
changed the title
kryptt
commented
Sep 3, 2026
kryptt
left a comment
kryptt
left a comment
Contributor
Author
There was a problem hiding this comment.
An additional point is that the extract method page should not show up in the top right nav
- Hide the extract-method entry page from the top-right nav (it is reached from the /refactorings/ catalogue, like the other entries). - Link Hedgehog to its actual repos on both sides: scala-hedgehog and haskell-hedgehog, instead of hedgehog.qa. - Acknowledge that the shared refactoring vocabulary is recent: the practice existed informally or less structured before Fowler's catalogue, Opdyke's thesis, and IDE Refactoring menus.
…in duals - Rename the catalogue entry and page to "Extract / Inline Method" (permalink /refactorings/extract-method/ unchanged, sources dir unchanged). - Add a Motivation section as the first section of the entry: why go in either direction — duplication and long methods drive Extract; speculative generality and coupling drive Inline. - Skill (refactoring-entry): Motivation is always the first section of an entry; each entry is written with its dual, and the catalogue name carries both sides. Folded into SKILL.md, brief.md, and the workflow.js research prompt; LESSONS.md entry added.
Page (extract-method): - Rename 'When it is not an equivalence' to 'Pitfalls' and fold the 'The functional reading' prose into a collapsible footnote inside it (the FP framing is context, not a sales pitch). - Rename 'Checking it' to 'Verification'. - Motivation: link 'code smells' to the Wikipedia article; add a paragraph on nested methods (Scala/Haskell) where the extraction scope is a judgement about which values stay captured vs become parameters. - Example 02 is now a nested extraction: step stays inside settle, capturing limit and fee; the fold supplies balance and tx. Sources rewritten (parallel Scala/Haskell), sheet now checks only Before.settle == After.settle, diagram redrawn for the nested shape. Skill (refactoring-entry): - brief.md: every entry carries the Extract / Inline page structure; OO reading only when one exists; 'Inverse' renamed 'Dual' and always present; code guidance: common domain subject, enough code to make the point, no accidental complexity. - Sync renamed sections (Pitfalls, Verification) through SKILL.md section order and the workflow.js research prompt.
Page (extract-method): - Every [n] citation is now a link [[n](#ref-n)] that jumps to the numbered reference at the bottom of the page. - References section rewritten as raw HTML: a plain <ol> of <li id=ref-N> items so each has a stable anchor; inline markdown hand-rendered to <em>/<a> because Kramdown does not process markdown inside raw block HTML and IALs on numbered items split the list. Skill (refactoring-entry): - SKILL.md, brief.md, workflow.js all now require citation links and the raw-HTML reference list pattern; LESSONS.md documents the Kramdown traps (raw-block markdown is escaped; IALs land on the enclosing <ol>).
kryptt
added a commit
that referenced
this pull request
Sep 3, 2026
The rebase onto master (Refactoring Section #12) brought in the refactorings catalogue, its raw-HTML citation blocks, and the internal .claude/skills/refactoring-entry docs. Tune the lint config for what is site content vs. tooling: - mdl_style.rb: allow inline HTML (MD033) — the refactorings citations are raw-HTML <li> lines by design (kramdown won't process markdown inside raw block HTML). - .overcommit.yml Mdl: exclude pages/refactorings/**/* (same reason; unwrappable citation lines), pages/refactorings.md, and .claude/**/* (agent-internal docs, not site prose). Overcommit excludes use File.fnmatch, so '**' needs the trailing '/*'. - .git-hooks/pre_commit/spellr.rb: also skip .claude/, refactorings, scala/hs/js, run.sh, and dotfiles when overcommit passes absolute paths; spellr only honors .spellr.yml excludes when given no files. - .spellr.yml + wordlist: exclude the same non-prose trees; wordlist refactorings/catalogue/opdyke/fowler/kramdown. - pages/refactorings/extract-method.md: drop the trailing blank lines.
kryptt
added a commit
that referenced
this pull request
Sep 3, 2026
The rebase onto master (Refactoring Section #12) brought in the refactorings catalogue, its raw-HTML citation blocks, and the internal .claude/skills/refactoring-entry docs. Tune the lint config for what is site content vs. tooling: - mdl_style.rb: allow inline HTML (MD033) — the refactorings citations are raw-HTML <li> lines by design (kramdown won't process markdown inside raw block HTML). - .overcommit.yml Mdl: exclude pages/refactorings/**/* (same reason; unwrappable citation lines), pages/refactorings.md, and .claude/**/* (agent-internal docs, not site prose). Overcommit excludes use File.fnmatch, so '**' needs the trailing '/*'. - .git-hooks/pre_commit/spellr.rb: also skip .claude/, refactorings, scala/hs/js, run.sh, and dotfiles when overcommit passes absolute paths; spellr only honors .spellr.yml excludes when given no files. - .spellr.yml + wordlist: exclude the same non-prose trees; wordlist refactorings/catalogue/opdyke/fowler/kramdown. - pages/refactorings/extract-method.md: drop the trailing blank lines.
kryptt
added a commit
that referenced
this pull request
Sep 3, 2026
* Add linting: pre-commit + CI for markdown, spelling, and sample code - .pre-commit-config.yaml: hygiene checks, codespell, markdownlint-cli2 (pinned; local node hook), and a 72-char pane-width check for the refactoring samples (pages/refactorings/*.scala|.hs). - .markdownlint-cli2.yaml: shared markdown style (80-col prose, tables and headings exempt, compact pipe style allowed). - scripts/check-sample-width.sh: enforces the sample width rule the refactoring skill already documents (LESSONS.md 'pane width'). - .github/workflows/lint.yml: runs the same pre-commit config on every PR and push to master, so local and CI can't drift. - Fixes the pre-existing issues the new rules surface: a duplicated H1 and trailing-punctuation headings in the Refactorings post, trailing whitespace, long prose lines in about/libraries/README, a folded header_subtitle scalar, and a 'Vist' typo (Visit). * Switch linting from pre-commit (python) to overcommit (ruby/bundler) Same checks, Ruby toolchain: - .overcommit.yml + .git-hooks/pre_commit/*.rb: hygiene checks (trailing whitespace, final newline, YAML/JSON syntax, merge markers, case conflicts, executable/shebang consistency), codespell, mdl (markdownlint), and the 72-char pane-width check for refactoring samples. - .mdlrc + mdl_style.rb: mdl config (front-matter, git-recurse, MD013 80-col prose, MD029 ordered, MD026 punctuation like markdownlint). - scripts/lint.sh = bundle exec overcommit --run; CI runs it, so local and CI can't drift. Gemfile dev group: overcommit + mdl. - Removes .pre-commit-config.yaml, .markdownlint-cli2.yaml, scripts/check-sample-width.sh. - Wraps a few long prose lines for the 80-col rule. * Replace codespell with spellr for Ruby-only spelling checks - Gemfile: add spellr (~> 0.12). - .git-hooks/pre_commit/spellr.rb: overcommit hook running bundle exec spellr on the committed files. - .spellr.yml + .spellr_wordlists/english.txt: config and site wordlist. - .overcommit.yml: Codespell -> Spellr hook. - .github/workflows/lint.yml: drop the pip codespell install (everything is now Ruby/bundler). - scripts/lint.sh: export OVERCOMMIT_NO_VERIFY for fresh checkouts (CI). - README: document spellr + wordlist. * Make linting pass on the refactoring section merged from master The rebase onto master (Refactoring Section #12) brought in the refactorings catalogue, its raw-HTML citation blocks, and the internal .claude/skills/refactoring-entry docs. Tune the lint config for what is site content vs. tooling: - mdl_style.rb: allow inline HTML (MD033) — the refactorings citations are raw-HTML <li> lines by design (kramdown won't process markdown inside raw block HTML). - .overcommit.yml Mdl: exclude pages/refactorings/**/* (same reason; unwrappable citation lines), pages/refactorings.md, and .claude/**/* (agent-internal docs, not site prose). Overcommit excludes use File.fnmatch, so '**' needs the trailing '/*'. - .git-hooks/pre_commit/spellr.rb: also skip .claude/, refactorings, scala/hs/js, run.sh, and dotfiles when overcommit passes absolute paths; spellr only honors .spellr.yml excludes when given no files. - .spellr.yml + wordlist: exclude the same non-prose trees; wordlist refactorings/catalogue/opdyke/fowler/kramdown. - pages/refactorings/extract-method.md: drop the trailing blank lines. * Disable AuthorName and AuthorEmail hooks in CI linting Overcommit enables AuthorName and AuthorEmail pre-commit hooks by default, which check git config user.name and user.email. In GitHub Actions runners, these are unset, causing overcommit --run to fail in CI. * Allow multiple blank lines at end of file in FinalNewline hook The hook should only enforce that files end with a newline (preventing POSIX/git missing-newline errors), not fail on multiple trailing blank lines which occurs naturally in source files like Optics.hs.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.