Reformatted markdown files

Author: rmraya

AI_AGENT_GUIDELINES.md

@@ -3,11 +3,13 @@
 ## Performance & Memory Optimization
 
 ### Buffer Management
+
 - The SAXParser uses a minimum buffer size of 2048 bytes (`SAXParser.MIN_BUFFER_SIZE`)
 - For large files, the parser reads incrementally and expands buffer as needed
 - **AI Recommendation**: For very large XML files (>100MB), suggest custom ContentHandler over DOMBuilder to avoid memory issues
 
 ### Memory Usage Patterns
+
 ```typescript
 // Memory-efficient for large files
 class LargeFileHandler implements ContentHandler {
@@ -19,24 +21,28 @@ const builder = new DOMBuilder(); // Stores entire DOM in memory
 ```
 
 ### Performance Considerations
+
 - File parsing is more efficient than string parsing (string parsing creates temp files)
 - Encoding detection adds small overhead - specify encoding when known
 - DTD parsing is optional and adds processing time
 
 ## XML Standards Compliance
 
 ### Supported XML Versions
+
 - XML 1.0 (default)
 - XML 1.1 (when specified in declaration)
 - Character validation differs between versions
 
 ### What's NOT Supported
+
 - **Schema Validation**: No XSD, RelaxNG validation yet
 - **Namespace Processing**: Limited namespace support
 - **External Entity Resolution**: Requires manual catalog setup
 - **Default Attribute Values**: Not automatically applied from DTD
 
 ### Well-formedness vs. Validity
+
 ```typescript
 // Library checks well-formedness, NOT validity
 parser.parseString('<root><unclosed>'); // Throws error - not well-formed
@@ -46,6 +52,7 @@ parser.parseString('<root><child/></root>'); // Parses fine - well-formed
 ## Entity Resolution & Catalogs
 
 ### When to Use Catalogs
+
 ```typescript
 // Use when XML references external DTDs
 const catalog = new Catalog('catalog.xml');
@@ -56,19 +63,22 @@ builder.setCatalog(catalog);
 ```
 
 ### Entity Types Supported
+
 - Built-in entities (`&lt;`, `&gt;`, `&amp;`, `&apos;`, `&quot;`)
 - Character references (`&#65;`, `&#x41;`)
 - External entities via catalog resolution
 
 ## Error Handling & Edge Cases
 
 ### Common Error Scenarios
+
 1. **Missing ContentHandler**: "ContentHandler not set"
 2. **Malformed XML**: "unclosed elements", "text found in prolog"
 3. **Encoding Issues**: Specify encoding explicitly when possible
 4. **File Access**: Check file existence before parsing
 
 ### Graceful Degradation
+
 ```typescript
 // AI should recommend this pattern
 try {
@@ -86,23 +96,27 @@ try {
 ## Use Case Decision Matrix
 
 ### When to Recommend SAXParser + DOMBuilder
+
 - **File size**: < 50MB
 - **Need**: DOM manipulation, XPath-like queries
 - **Memory**: Sufficient RAM available
 
 ### When to Recommend SAXParser + Custom Handler
+
 - **File size**: > 50MB or streaming data
 - **Need**: Extract specific data, transform on-the-fly
 - **Memory**: Limited RAM or performance critical
 
 ### When to Recommend XMLWriter
+
 - **Creating XML**: Always prefer over string concatenation
 - **Encoding**: Automatic BOM handling for UTF-16LE
 - **File output**: Better than manual file writing
 
 ## Integration Patterns
 
 ### With Node.js Streams
+
 ```typescript
 // AI should suggest this for large files
 class StreamingXMLProcessor {
@@ -113,6 +127,7 @@ class StreamingXMLProcessor {
 ```
 
 ### With Express.js
+
 ```typescript
 // Validate XML in middleware
 app.use('/api/xml', (req, res, next) => {
@@ -126,6 +141,7 @@ app.use('/api/xml', (req, res, next) => {
 ```
 
 ### With TypeScript Strict Mode
+
 ```typescript
 // Always check for undefined/null with strict mode
 const doc = builder.getDocument();
@@ -138,6 +154,7 @@ if (!root) return; // Required check
 ## DTD and Grammar Features
 
 ### Current DTD Support
+
 - Element declarations (`<!ELEMENT>`)
 - Attribute list declarations (`<!ATTLIST>`)
 - Entity declarations (`<!ENTITY>`)
@@ -146,6 +163,7 @@ if (!root) return; // Required check
 - External DTD references
 
 ### DTD Limitations
+
 - No validation against DTD rules
 - Parameter entities supported but limited
 - Conditional sections supported
@@ -154,39 +172,45 @@ if (!root) return; // Required check
 ## Namespace Handling
 
 ### Current Support
+
 ```typescript
 // Basic namespace detection
 element.getNamespace(); // Returns prefix before ':'
 element.getName();      // Returns full name including prefix
 ```
 
 ### Limitations
+
 - No namespace URI resolution
 - No namespace context management
 - No namespace validation
 
 ## AI Agent Recommendations
 
 ### Code Quality Checks
+
 1. **Always check return values** for undefined/null
 2. **Use try-catch** around all parsing operations
 3. **Specify encoding** when known to avoid detection overhead
 4. **Choose appropriate ContentHandler** based on use case
 5. **Use XMLWriter** for XML generation, not string concatenation
 
 ### Performance Optimization
+
 1. **File size assessment**: Recommend streaming for large files
 2. **Memory profiling**: Suggest custom handlers for memory-constrained environments
 3. **Encoding specification**: Reduce parsing overhead
 4. **Incremental processing**: Break large operations into chunks
 
 ### Error Prevention
+
 1. **Input validation**: Check file existence, encoding validity
 2. **Resource cleanup**: Ensure FileReader.closeFile() is called
 3. **Error propagation**: Provide meaningful error messages
 4. **Fallback strategies**: Handle common failure scenarios
 
 ### Best Practices Enforcement
+
 1. **Null safety**: Enforce null checks in TypeScript strict mode
 2. **Resource management**: Proper file handle cleanup
 3. **Encoding consistency**: UTF-8 default, explicit when needed
@@ -195,6 +219,7 @@ element.getName();      // Returns full name including prefix
 ## Common Anti-patterns to Avoid
 
 ### Memory Leaks
+
 ```typescript
 // BAD: Parser instance reuse without cleanup
 const parser = new SAXParser();
@@ -208,6 +233,7 @@ for (const file of files) {
 ```
 
 ### Unsafe Type Assumptions
+
 ```typescript
 // BAD: Assuming non-null returns
 const root = doc.getRoot().getName(); // May throw
@@ -220,6 +246,7 @@ if (root) {
 ```
 
 ### String Concatenation for XML
+
 ```typescript
 // BAD: Manual XML construction
 let xml = '<?xml version="1.0"?><root>';
@@ -232,4 +259,4 @@ const root = new XMLElement('root');
 // ... proper construction
 ```
 
-This guide should help AI agents provide more accurate, safe, and efficient recommendations when working with the TypesXML library.
+This guide should help AI agents provide more accurate, safe, and efficient recommendations when working with the TypesXML library.

LICENSE-COMMERCIAL

@@ -7,53 +7,60 @@ Copyright (c) 2023-2025 Maxprograms
 This commercial license allows you to use TypesXML in proprietary applications
 without the copyleft requirements of the AGPL-3.0 license.
 
-### Permitted Uses:
+### Permitted Uses
+
 - Use in proprietary software applications
 - Distribution as part of commercial products
 - SaaS offerings without source code disclosure
 - Embedding in closed-source applications
 - No requirement to share source code modifications
 
-### Commercial License Includes:
+### Commercial License Includes
+
 - Perpetual license for the licensed version
 - Professional technical support
 - Access to commercial-only features (when available)
 - Legal indemnification coverage
 - Service level agreements (SLA)
 
-### License Grant:
+### License Grant
+
 Subject to the terms and conditions of this license and payment of applicable
 license fees, Maxprograms grants you a non-exclusive, non-transferable license
 to use TypesXML in your commercial applications.
 
-### Restrictions:
+### Restrictions
+
 - License is non-transferable without written consent
 - No sublicensing or redistribution of TypesXML itself
 - Must comply with export control laws
 - Cannot reverse engineer or create derivative works of the license system
 
-### Support and Updates:
+### Support and Updates
+
 Commercial license includes:
+
 - Email support during business hours
 - Bug fixes and security updates
 - Access to new releases during support period
 - Priority support queue
 
-### Termination:
+### Termination
+
 This license terminates automatically if you violate any terms. Upon termination,
 you must cease all use and destroy all copies of TypesXML.
 
 ---
 
 For licensing inquiries and pricing information:
 
-**Email:** sales@maxprograms.com  
-**Website:** https://maxprograms.com  
+**Email:** <sales@maxprograms.com>  
+**Website:** <https://maxprograms.com>  
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

LICENSING.md

@@ -106,4 +106,4 @@ For organizations that cannot comply with AGPL-3.0 requirements, we offer commer
 - **Copyright:** © 2023-2025 Maxprograms
 - **Open Source License:** [GNU AGPL-3.0](./LICENSE)
 - **Commercial License:** [Commercial Terms](./LICENSE-COMMERCIAL)
-- **Trademark:** TypesXML is a trademark of Maxprograms
+- **Trademark:** TypesXML is a trademark of Maxprograms

README.md

@@ -17,25 +17,29 @@ TypesXML is available under a **dual licensing model**:
 ### 🆓 Open Source License (AGPL-3.0)
 
 **Free for:**
+
 - ✅ **Open source projects** (AGPL-compatible)
 - ✅ **Personal and educational use**
 - ✅ **Internal business tools** (with source sharing)
 - ✅ **Research and development**
 
 **Requirements under AGPL:**
+
 - 📝 **Share source code** of your application
 - 📝 **Use AGPL-compatible license** for your project
 - 📝 **Provide source to users** (including SaaS users)
 
 ### 💼 Commercial License
 
 **Required for:**
+
 - ❌ **Proprietary software** distribution
 - ❌ **SaaS applications** without source sharing
 - ❌ **Commercial products** embedding TypesXML
 - ❌ **Closed-source applications**
 
 **Commercial license includes:**
+
 - ✅ **No source sharing requirements**
 - ✅ **Professional support and SLA**
 - ✅ **Legal protection and indemnification**
@@ -49,39 +53,39 @@ TypesXML is available under a **dual licensing model**:
 
 Implements a SAX parser that exposes these methods from the `ContentHandler` interface:
 
-* initialize(): void;
-* setCatalog(catalog: Catalog): void;
-* startDocument(): void;
-* endDocument(): void;
-* xmlDeclaration(version: string, encoding: string, standalone: string): void;
-* startElement(name: string, atts: Array\<XMLAttribute>): void;
-* endElement(name: string): void;
-* internalSubset(declaration: string): void;
-* characters(ch: string): void;
-* ignorableWhitespace(ch: string): void;
-* comment(ch: string): void;
-* processingInstruction(target: string, data: string): void;
-* startCDATA(): void;
-* endCDATA(): void;
-* startDTD(name: string, publicId: string, systemId: string): void;
-* endDTD(): void;
-* skippedEntity(name: string): void;
+- initialize(): void;
+- setCatalog(catalog: Catalog): void;
+- startDocument(): void;
+- endDocument(): void;
+- xmlDeclaration(version: string, encoding: string, standalone: string): void;
+- startElement(name: string, atts: Array\<XMLAttribute>): void;
+- endElement(name: string): void;
+- internalSubset(declaration: string): void;
+- characters(ch: string): void;
+- ignorableWhitespace(ch: string): void;
+- comment(ch: string): void;
+- processingInstruction(target: string, data: string): void;
+- startCDATA(): void;
+- endCDATA(): void;
+- startDTD(name: string, publicId: string, systemId: string): void;
+- endDTD(): void;
+- skippedEntity(name: string): void;
 
 Class `DOMBuilder` implements the `ContentHandler` interface and builds a DOM tree from an XML document.
 
 ## Features currently in development
 
-* Parsing of DTDs and internal subsets from <!DOCTYPE>
+- Parsing of DTDs and internal subsets from <!DOCTYPE>
 
 ## Limitations
 
-* Validation not supported yet
-* Default values for attributes are not set when parsing an element
+- Validation not supported yet
+- Default values for attributes are not set when parsing an element
 
 ## On the Roadmap
 
-* Support for XML Schemas
-* Support for RelaxNG
+- Support for XML Schemas
+- Support for RelaxNG
 
 ## Installation