Repository navigation
IsaSections: shared module, heading regexes from one alias list, fixture with every reader's boundaries (#2527) - #2691
drpaulobernardy wants to merge 2 commits into
Conversation
…lmiessler#2527) One fixture ISA with a fenced `## Test Strategy`/`## Evals`/`## Criteria`/ `---`, a four-backtick fence, `## Anti-claims` and `## Test Strategy Notes`. Seven readers run on it and their current output is pinned, defects included: IsaLadder.h2Sections, Review.isaSections, parseEvalsText, parseTestStrategyText, isa-utils.extractCriteriaSection, parseIsaClaimsText, IsaFrontier.parseClaims/countCheckboxLines. No code changes; moving a reader later changes its block in this test. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014YTdW6sTViEVVK8c3DeQVC
…miessler#2527) New leaf module LIFEOS/TOOLS/lib/IsaSections.ts (no imports): - SECTION_ALIASES holds every criteria, bridge and anti heading name. - CRITERIA_HEADING_RE, BRIDGE_HEADING_RE and ANTI_HEADING_RE are generated from it, byte-equal in source and flags to the literals they replace. - isaSections(text) and findSections(sections, kind) are the shared parser the readers move onto next: frontmatter skipped, fences closed by same char and length, a section ends at the next heading of its level or higher. isa-utils, IsaClaims and IsaFrontier drop their three hand-copied literals and export the one generated regex under the same names, so CompileSplit and other importers are unchanged. No reader changes behavior: the pinned boundaries from the previous commit still pass, and every reader that changed source gives byte-identical output on 37 real ISAs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014YTdW6sTViEVVK8c3DeQVC
isihussain
left a comment
There was a problem hiding this comment.
Architectural & Quality Review
Great refactoring @drpaulobernardy. Centralizing the parsing and alias normalization for ISA headings into a zero-dependency leaf module (IsaSections.ts) solves an important maintainability issue across IsaClaims, IsaFrontier, and isa-utils. Pinning the existing readers' boundaries against IsaSections.fixture.md in IsaSections.test.ts is also textbook defensive engineering.
Here is a review across architecture, correctness, and performance:
1. Architecture: Zero-Dependency Leaf Module
Moving SECTION_ALIASES and the derived heading regular expressions into IsaSections stops the copy-paste drift without pulling in isa-utils and its surrounding hook dependency graph. This keeps the dependency DAG strictly acyclic.
2. Correctness & CommonMark Spec Compliance
The fence-handling logic in isaSections():
if (f && !(f[1]![0] === "`" && f[2]!.includes("`"))) { fence = { char: f[1]![0]!, size: f[1]!.length }; continue; }accurately follows the CommonMark specification (info strings of backtick code fences cannot contain backticks, whereas tilde fences can). Handling nested 4-backtick blocks enclosing 3-backtick blocks properly prevents false section heading detection inside markdown code examples.
Note on Windows CRLF:
Because offset += line.length + 1 is calculated over lines split by \n, on files with Windows CRLF (\r\n) line endings, line.length preserves the trailing \r, ensuring character offsets into the original text buffer (start, bodyStart, end) remain exact.
3. Performance: Section Boundary Lookahead
In isaSections():
return heads.map((h, i) => {
const next = heads.slice(i + 1).find((n) => n.level <= h.level);
return { ...h, end: next ? next.start : text.length };
});For an ISA with heads.slice(i + 1).find(...) is
Overall, clean implementation, zero regressions, and solid fixture coverage. Ready to support the downstream readers migrating to it.
Note
🤖 Paulino (AI assistant) responding on behalf of Dr. Paulo
This is the first step proposed in #2527. It adds a shared
IsaSectionsmodule, generates the legacy-name regexes from one alias list, and adds the fixture ISA, with every reader asserting its boundaries. No reader changes behavior yet.Commits
1. Fixture, with each reader's current boundaries pinned
LIFEOS/TOOLS/lib/IsaSections.fixture.mdhas everything you listed: a fenced## Test Strategy,## Evals,## Criteriaand---, a four-backtick fence,## Anti-claimsand## Test Strategy Notes. It also has a fenced##shell comment inside the real Test Strategy section.IsaSections.test.tsruns seven readers on the fixture and pins what each one sees today, defects included. This commit changes no code, and the tests pass onmainas it is.IsaLadder.h2SectionsReview.isaSectionsparseEvalsTextISC-1blockparseTestStrategyTextISC-90(a fenced example),ISC-1,ISC-3(from## Test Strategy Notes) andISC-91(four-backtick fence); the fenced##comment ends the section, soISC-2is lostisa-utils.extractCriteriaSectionISC-1: the section ends at the fenced## CriterialineparseIsaClaimsTextISC-1,ISC-2andISC-A1(anti); fences are skipped and---ends the sectionIsaFrontier.parseClaims/countCheckboxLines2.
LIFEOS/TOOLS/lib/IsaSections.tsSECTION_ALIASESholds every criteria, bridge and anti heading name, and the comment on## Featuresmoves there.CRITERIA_HEADING_RE,BRIDGE_HEADING_REandANTI_HEADING_REare generated from it. A test pins their source and flags as byte-equal to the literals they replace.isa-utils,IsaClaimsandIsaFrontierdrop their three hand-copied literals and export the one generated regex under the same names. A test checks that it is the same object in all three.CompileSplitand the other importers are unchanged.isaSections(text)andfindSections(sections, kind)are the parser the readers move onto next. Frontmatter is skipped. A fence closes only on the same character, at least as long, with nothing after it. A section ends at the next heading of its level or higher, and---is body text. Their rules are tested on the fixture and on edge cases: an unclosed fence, a backtick info string, nested tildes.Verification
IsaSections.test.tspass. The 7 boundary tests pass both before and after commit 2.extractCriteriaSection,countCriteria,parseCriteriaList,parseIsaClaimsText,IsaFrontier.parseClaimsandcountCheckboxLines) gave byte-identical output on the 37 real ISAs of this install, before and after.IsaSections.tspassestsc --strict.Next steps, one reader per PR
Each move changes that reader's block in "current reader boundaries" in the same commit, so the boundary change is reviewed rather than silent. My proposed order runs from the smallest behavior change to the largest:
parseEvalsText, which already matches.IsaLadder.h2Sections, which only gains the four-backtick fix.Review.isaSections, which then needsAnti-claimsinALWAYS_SENT_SECTIONS, throughfindSections(…, "anti").parseTestStrategyText.extractCriteriaSectionandIsaFrontier.parseIsaClaimsText, where---ending the section is a decision for you to make.Tell me if you want a different order, or the moves in this PR.
🤖 Generated with Claude Code