Skip to content

Z namespace of different types - #428

Draft
kavitharaju wants to merge 15 commits into
Bridgeconn:masterfrom
kavitharaju:zNamespace-of-different-types
Draft

kavitharaju wants to merge 15 commits into
Bridgeconn:masterfrom
kavitharaju:zNamespace-of-different-types

Conversation

@kavitharaju

@kavitharaju kavitharaju commented Sep 8, 2026

Copy link
Copy Markdown
Collaborator

User description

  • Implements Type of \z markers #237
    • Update grammar with predefined prefixes in the z marker rules identifying their types without ambiguity
    • In the USFMParser object, allow an optional markers.ext input with names and types of custom markers
      • Python
      • Node and Web
    • A regex based parser for the markers.ext file
      • Python
      • Node and Web
    • Handle z marker objects in USJ and USX generation as per new syntax tree
      • Python
      • Node and Web
    • Refactor the test module to pass marker.ext optionally and use input dict/json instead of positional arguments
      • Python
      • Node and Web
    • CLI support for passing in markers.ext
      • Python
      • Node and Web
    • Update grammar with fallback support for undefined z markers (not breaking currently parsing cases)
    • Subsequent changes in USJ and USX generattion as per above grammar updates
      • Python
      • Node and Web
    • Implement filtering on user extended(z) markers
      • Python
      • Node and Web
    • Add new test cases for z markers of different types, with and without markers.ext, test and fix.
      • Python
      • Node and Web
    • Resolve AI review comments
    • Document the new features properly

CodeAnt-AI Description

Support typed custom z markers across parser formats

What Changed

  • Custom markers defined through marker extensions are recognized as paragraph, character, note, or milestone content in Node.js, browser, and Python parsers
  • Custom markers retain their original names when converted to USJ or USX, with their content and attributes preserved
  • Marker filters now treat excluded custom markers and their contents consistently
  • Parsing reports mismatched custom closing markers as warnings

Impact

✅ Custom z markers parse across all supported runtimes
✅ Custom marker content survives USJ and USX conversion
✅ Clearer warnings for mismatched custom marker closures

💡 Usage Guide

Checking Your Pull Request

Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.

Talking to CodeAnt AI

Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

Preserve Org Learnings with CodeAnt

You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

Check Your Repository Health

To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.

@kavitharaju
kavitharaju requested a review from joelthe1 September 8, 2026 12:02
@kavitharaju kavitharaju added test This has to do with testing. V3-node-module grammar Web module python Pull requests that update Python code labels Sep 8, 2026
@codeant-ai

codeant-ai Bot commented Sep 8, 2026

Copy link
Copy Markdown

🤖 CodeAnt AI — Review Status

Status Commit Started (UTC) Finished (UTC)
✅ Reviewed your PR 799a62b Sep 08, 2026 · 12:02 12:06

@codeant-ai

codeant-ai Bot commented Sep 8, 2026

Copy link
Copy Markdown

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

@kavitharaju
kavitharaju marked this pull request as draft September 8, 2026 12:03
@coderabbitai

coderabbitai Bot commented Sep 8, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@codeant-ai codeant-ai Bot added the size:XL This PR changes 500-999 lines, ignoring generated files label Sep 8, 2026
def read_to_object(self,file_content=None, file_path=None):
if file_path and file_content is None:
file_content = open(file_path, 'r', encoding='utf-8').read()
self.lines = file_content.splitlines()

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Suggestion: Reading new content does not clear self.extensions, so reused readers retain markers from earlier files and replace markers that belong only to stale state. [stale reference]

Assessment: 🟠 Major · 🔁 Occurrence: Rarely

Use CodeAnt Skill Fix in Cursor Fix in VSCode Claude

Prompt for AI Agent 🤖
This is a comment left during a code review.

**Path:** py-usfm-parser/src/usfm_grammar/markers_ext_reader.py
**Line:** 57:57
**Comment:**
	*Stale Reference: Reading new content does not clear `self.extensions`, so reused readers retain markers from earlier files and replace markers that belong only to stale state.

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix
👍 | 👎

def replace_custom_markers(self, usfm_string):
modified_usfm = usfm_string
for marker in self.extensions:
marker_type = type_map[self.extensions[marker]['category']]

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Suggestion: Unsupported or missing categories raise KeyError, so malformed extension blocks abort parsing instead of being ignored like the other parsers. [api mismatch]

Assessment: 🟠 Major · 🔁 Occurrence: Sometimes

Use CodeAnt Skill Fix in Cursor Fix in VSCode Claude

Prompt for AI Agent 🤖
This is a comment left during a code review.

**Path:** py-usfm-parser/src/usfm_grammar/markers_ext_reader.py
**Line:** 81:81
**Comment:**
	*Api Mismatch: Unsupported or missing categories raise `KeyError`, so malformed extension blocks abort parsing instead of being ignored like the other parsers.

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix
👍 | 👎

Comment on lines +452 to +453
xt: $ => prec.right(0,seq("\\xt ", optional($.crossrefText),optional(choice($.defaultAttribute, $._attributesInCrossref)),
optional("\\xt*"))),

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Suggestion: The added cross-reference content rules allow closing markers to be omitted, so truncated \xt and similar content is accepted instead of reported as malformed USFM. [api mismatch]

Assessment: 🟠 Major · 🔁 Occurrence: Sometimes

Use CodeAnt Skill Fix in Cursor Fix in VSCode Claude

Prompt for AI Agent 🤖
This is a comment left during a code review.

**Path:** tree-sitter-usfm3/grammar.js
**Line:** 452:453
**Comment:**
	*Api Mismatch: The added cross-reference content rules allow closing markers to be omitted, so truncated `\xt` and similar content is accepted instead of reported as malformed USFM.

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix
👍 | 👎

Comment thread tree-sitter-usfm3/grammar.js Outdated
Comment on lines +671 to +672
zNameSpaceNote: $=> prec.right(0, seq($.zNameSpaceNote, $.caller, //repeat(choice($._footnoteContents, $._crossrefContents, $.zNameSpaceChar)), $.zSpaceCloseNote)),
repeat($.zNameSpaceChar), $.zNameSpaceNote)),

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Suggestion: zNameSpaceNote recursively requires itself before consuming its opening marker, so custom note input cannot match this rule and produces parse errors. [logic error]

Assessment: 🔴 Critical · 🔁 Occurrence: Often

Use CodeAnt Skill Fix in Cursor Fix in VSCode Claude

Prompt for AI Agent 🤖
This is a comment left during a code review.

**Path:** tree-sitter-usfm3/grammar.js
**Line:** 671:672
**Comment:**
	*Logic Error: `zNameSpaceNote` recursively requires itself before consuming its opening marker, so custom note input cannot match this rule and produces parse errors.

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix
👍 | 👎

Comment on lines +83 to +85
if (usfmString.includes('\\custom')) {
console.log('Modified USFM:', modifiedUsfm);
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Suggestion: Parsing custom USFM logs the entire modified document, exposing Scripture or user content in browser consoles whenever custom markers are present. [security]

Assessment: 🟠 Major · 🔁 Occurrence: Rarely

Use CodeAnt Skill Fix in Cursor Fix in VSCode Claude

Prompt for AI Agent 🤖
This is a comment left during a code review.

**Path:** web-usfm-parser/src/markersExtReader.js
**Line:** 83:85
**Comment:**
	*Security: Parsing custom USFM logs the entire modified document, exposing Scripture or user content in browser consoles whenever custom markers are present.

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix
👍 | 👎

return;
}

const customJsonObj = { type: nodeType };

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Suggestion: Custom nodes do not consume pending vid state, so an explicit vid is lost and may incorrectly attach to the following node. [stale reference]

Assessment: 🟠 Major · 🔁 Occurrence: Sometimes

Use CodeAnt Skill Fix in Cursor Fix in VSCode Claude

Prompt for AI Agent 🤖
This is a comment left during a code review.

**Path:** web-usfm-parser/src/usjGenerator.js
**Line:** 501:501
**Comment:**
	*Stale Reference: Custom nodes do not consume pending `vid` state, so an explicit `vid` is lost and may incorrectly attach to the following node.

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix
👍 | 👎

Comment thread node-usfm-parser/test/config.js Outdated
try {
const data = fs.readFileSync(inputUsfmPath, 'utf8');
let testParser = new USFMParser(data);
let testParser = new USFMParser(data, null, null, null, null, customMarkersExt);

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Suggestion: Every baseline fixture now uses customMarkersExt, so these tests no longer verify parser behavior without extensions and can miss default-path regressions. [incomplete implementation]

Assessment: 🟠 Major · 🔁 Occurrence: Sometimes

Use CodeAnt Skill Fix in Cursor Fix in VSCode Claude

Prompt for AI Agent 🤖
This is a comment left during a code review.

**Path:** node-usfm-parser/test/config.js
**Line:** 148:148
**Comment:**
	*Incomplete Implementation: Every baseline fixture now uses `customMarkersExt`, so these tests no longer verify parser behavior without extensions and can miss default-path regressions.

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix
👍 | 👎

Comment on lines +71 to +80
const markerType = typeMap[category];
if (markerType === undefined) {
continue;
}
const replacement = replacementMap[markerType];
const markerPattern = new RegExp(`\\\\${marker}(?=[^\\w-]|$)`, 'g');
modifiedUsfm = modifiedUsfm.replace(
markerPattern,
`\\${replacement}${marker}`,
);

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Suggestion: The milestone category has no entry in replacementMap, so milestone markers become \undefinedz... and cannot be parsed. [api mismatch]

Assessment: 🟠 Major · 🔁 Occurrence: Sometimes

Use CodeAnt Skill Fix in Cursor Fix in VSCode Claude

Prompt for AI Agent 🤖
This is a comment left during a code review.

**Path:** node-usfm-parser/src/markersExtReader.js
**Line:** 71:80
**Comment:**
	*Api Mismatch: The `milestone` category has no entry in `replacementMap`, so milestone markers become `\undefinedz...` and cannot be parsed.

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix
👍 | 👎

@codeant-ai

codeant-ai Bot commented Sep 8, 2026

Copy link
Copy Markdown

CodeAnt Nitpicks

2 code suggestions

1. This only checks whether any custom namespace node exists, so a missing custom marker passes whenever another unrelated custom marker appears in the same file.

Incorrect condition logic · py-usfm-parser/tests/test_parsing.py:61-68


2. findAllMarkers removes everything before the first underscore from any marker beginning with custom, corrupting legitimate marker names such as custom_marker.

Incorrect condition logic · web-usfm-parser/test/config.js:230-235

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

Labels

grammar python Pull requests that update Python code size:XL This PR changes 500-999 lines, ignoring generated files test This has to do with testing. V3-node-module Web module

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant