Skip to content

IsaSections: shared module, heading regexes from one alias list, fixture with every reader's boundaries (#2527) - #2691

Open
drpaulobernardy wants to merge 2 commits into
danielmiessler:mainfrom
drpaulobernardy:isa-sections
Open

drpaulobernardy wants to merge 2 commits into
danielmiessler:mainfrom
drpaulobernardy:isa-sections

Conversation

@drpaulobernardy

Copy link
Copy Markdown

Note

🤖 Paulino (AI assistant) responding on behalf of Dr. Paulo

This is the first step proposed in #2527. It adds a shared IsaSections module, 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.md has everything you listed: a fenced ## Test Strategy, ## Evals, ## Criteria and ---, a four-backtick fence, ## Anti-claims and ## Test Strategy Notes. It also has a fenced ## shell comment inside the real Test Strategy section.
  • IsaSections.test.ts runs seven readers on the fixture and pins what each one sees today, defects included. This commit changes no code, and the tests pass on main as it is.
reader sees on the fixture
IsaLadder.h2Sections the Evals, Test Strategy and Criteria headings inside the four-backtick fence
Review.isaSections the same, and it splits at H3
parseEvalsText only the real ISC-1 block
parseTestStrategyText ISC-90 (a fenced example), ISC-1, ISC-3 (from ## Test Strategy Notes) and ISC-91 (four-backtick fence); the fenced ## comment ends the section, so ISC-2 is lost
isa-utils.extractCriteriaSection only ISC-1: the section ends at the fenced ## Criteria line
parseIsaClaimsText ISC-1, ISC-2 and ISC-A1 (anti); fences are skipped and --- ends the section
IsaFrontier.parseClaims / countCheckboxLines the same claims, with no anti mark; the count is 1

2. LIFEOS/TOOLS/lib/IsaSections.ts

  • SECTION_ALIASES holds every criteria, bridge and anti heading name, and the comment on ## Features moves there.
  • CRITERIA_HEADING_RE, BRIDGE_HEADING_RE and ANTI_HEADING_RE are generated from it. A test pins their source and flags as byte-equal to the literals they replace.
  • isa-utils, IsaClaims and IsaFrontier drop 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. CompileSplit and the other importers are unchanged.
  • The module imports nothing. The copies existed so that IsaClaims and IsaFrontier would not pull in isa-utils' hook graph, and a leaf module keeps that property.
  • isaSections(text) and findSections(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

  • The 14 tests in IsaSections.test.ts pass. The 7 boundary tests pass both before and after commit 2.
  • Every reader whose source changed (extractCriteriaSection, countCriteria, parseCriteriaList, parseIsaClaimsText, IsaFrontier.parseClaims and countCheckboxLines) gave byte-identical output on the 37 real ISAs of this install, before and after.
  • IsaSections.ts passes tsc --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:

  1. parseEvalsText, which already matches.
  2. IsaLadder.h2Sections, which only gains the four-backtick fix.
  3. Review.isaSections, which then needs Anti-claims in ALWAYS_SENT_SECTIONS, through findSections(…, "anti").
  4. parseTestStrategyText.
  5. extractCriteriaSection and IsaFrontier.
  6. 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

drpaulobernardy and others added 2 commits November 8, 2026 19:22
…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 isihussain left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 $N$ headings, heads.slice(i + 1).find(...) is $O(N^2)$ due to the nested linear search. Given that ISAs typically have fewer than 100 headings, this is well within acceptable microsecond runtimes. If this module is ever used over huge auto-generated markdown reports, a standard monotonic stack pass can resolve next-boundary indices in $O(N)$ linear time.


Overall, clean implementation, zero regressions, and solid fixture coverage. Ready to support the downstream readers migrating to it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants