extwee 2.3.11 → 2.3.12

package/CHANGELOG.md

@@ -0,0 +1,219 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.3.12] - 2025-12-1
+
+### Added
+
+- CHANGELOG.md to track project changes
+- CONTRIBUTING.md with development guidelines
+- GitHub issue templates (bug reports, feature requests)
+- GitHub pull request template
+- .npmignore to optimize package size
+- Script-tagged passages now automatically added to `storyJavaScript` property instead of passages array
+- Comprehensive Snowman story format compatibility tests
+- Enhanced HTML entity handling for passage content
+- CI/CD testing across multiple Node.js versions (20.x, 22.x, 23.x)
+- CI/CD testing across multiple operating systems (Ubuntu, Windows, macOS)
+
+### Changed
+
+- Passage text content no longer HTML-encoded in output (attributes still encoded)
+- Improved round-trip compatibility between formats
+- Enhanced GitHub Actions workflow for better test coverage
+
+### Fixed
+
+- HTML entity encoding bug that broke JavaScript and HTML content in passages
+- Snowman story format compatibility issues with dynamic content
+
+## [2.3.11] - 2025-11-15
+
+### Fixed
+
+- Regression of encoding behavior back to original, correct encoding of HTML-like entities
+- Accidentally introduced encoding issue from 2.3.9
+
+## [2.3.10] - 2025-11-15
+
+### Fixed
+
+- Issue with parsing of Twee passages using "script" and "stylesheet" keywords
+- Passages not always being processed as Story JavaScript and Story Stylesheet
+- Duplication of passages and incorrect encoding into Twine 2 HTML
+
+## [2.3.9] - 2025-11-15
+
+### Fixed
+
+- Edge case issue when encoding special symbols in writing and confirming when reading
+
+## [2.3.8] - 2025-11-15
+
+### Added
+
+- Native crypto.randomUUID() for IFID generation (Node.js)
+- Browser-based Crypto API randomUUID() for web builds
+- Performance improvement: UUID generation is much faster
+
+### Changed
+
+- Updated dependencies
+
+### Removed
+
+- uuid package dependency (replaced with native crypto APIs)
+
+## [2.3.2] - 2025-08-03
+
+### Changed
+
+- Monthly maintenance update
+- Updated dependencies (jest, eslint, webpack, eslint-plugin-jsdoc, @inquirer/prompts)
+
+## [2.3.0] - 2024-08-01
+
+- May impact older browsers (pre-2021) for web builds
+
+## [2.3.7] - 2025-10-25
+
+### Added
+
+- New decompile demo showing Twine 2 HTML analysis with statistics
+
+### Fixed
+
+- Issues with web parsing of attributes inside `<tw-storydata>` and `<tw-passagedata>` elements
+
+## [2.3.6] - 2025-10-24
+
+### Changed
+
+- Minor release to re-align versions on NPM and GitHub
+
+## [2.3.5] - 2025-10-24
+
+### Added
+
+- Exports for various web builds to help with packaging
+
+## [2.3.4] - 2025-10-01
+
+### Added
+
+- "Compiler" demo showing browser-based Twee compilation with Story Formats Archive
+
+### Changed
+
+- Internal WebPack changes to fix edge cases with loading Extwee in browser
+- Updated dependencies
+
+### Security
+
+- Fixed code scanning alert #133: Exception text reinterpreted as HTML
+
+## [2.3.3] - 2025-09-07
+
+### Added
+
+- Web-specific versions of major HTML parsers (Twine1HTML, Twine2HTML, Twine2ArchiveHTML) using DOM functionality
+- Separate build files: core, TWS, Twine2Archive, Twine1HTML
+
+### Changed
+
+- Optimized web build from 290 KiB to 78.5 KiB (core)
+- Updated UUID to pure ESM module
+- Rewrote Jest mocking functions for compatibility
+
+## [2.3.2] - 2025-08-03
+
+### Added
+
+- Support for Twine 2 JSON format
+- Enhanced web build exports
+- Tree-shaking support for better bundle optimization
+
+### Changed
+
+- Improved command-line interface with better error messages
+- Updated documentation with more examples
+
+## [2.2.5] - 2024-07-01
+
+### Changed
+
+- Separated short and long command-line option flags
+- Improved CLI help documentation
+
+## [2.2.0] - 2024-06-01
+
+### Added
+
+- Config file support (extwee.config.json)
+- Better story format version handling
+
+### Changed
+
+- Enhanced error messages throughout the application
+
+## [2.1.0] - 2024-05-01
+
+### Added
+
+- Twine 2 Archive HTML support
+- Round-trip testing for format conversions
+
+### Fixed
+
+- Various parser edge cases
+
+## [2.0.0] - 2024-04-01
+
+### Added
+
+- Complete rewrite using ES modules
+- TypeScript type definitions
+- Web builds for browser usage
+- Comprehensive test suite with Jest
+
+### Changed
+
+- Modern JavaScript (ES2020+)
+- Improved API design
+- Better separation of concerns
+
+### Breaking Changes
+
+- API incompatible with 1.x versions
+- Node.js 14+ required
+
+## [1.6.0] - 2023-12-01
+
+### Added
+
+- Twee 3 specification support
+- StoryFormat parsing improvements
+
+### Deprecated
+
+- Version 1.x line (replaced by 2.x)
+
+---
+
+## Migration Guides
+
+### From 1.x to 2.x
+
+- Update Node.js to version 14 or higher
+- Change CommonJS `require()` to ES `import`
+- Review API changes in object constructors
+- Update file paths to use absolute paths in CLI
+
+### From uuid package to native crypto
+
+- No user action required - internal change only
+- IFID generation is now 3.6x faster

package/CONTRIBUTING.md

@@ -0,0 +1,305 @@
+# Contributing to Extwee
+
+Thank you for your interest in contributing to Extwee! This document provides guidelines and instructions for contributing.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [How to Contribute](#how-to-contribute)
+- [Coding Standards](#coding-standards)
+- [Testing Guidelines](#testing-guidelines)
+- [Submitting Changes](#submitting-changes)
+- [Release Process](#release-process)
+
+## Code of Conduct
+
+This project adheres to the Contributor Covenant [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainer.
+
+## Getting Started
+
+### Prerequisites
+
+- **Node.js** 18.x or higher (LTS recommended)
+- **npm** 9.x or higher
+- **Git** for version control
+
+### Development Setup
+
+1. **Fork the repository** on GitHub
+
+2. **Clone your fork**:
+
+   ```bash
+   git clone https://github.com/YOUR-USERNAME/extwee.git
+   cd extwee
+   ```
+
+3. **Add upstream remote**:
+
+   ```bash
+   git remote add upstream https://github.com/videlais/extwee.git
+   ```
+
+4. **Install dependencies**:
+
+   ```bash
+   npm install
+   ```
+
+5. **Run tests to verify setup**:
+
+   ```bash
+   npm test
+   ```
+
+6. **Build the project**:
+
+   ```bash
+   npm run all
+   ```
+
+## How to Contribute
+
+### Reporting Bugs
+
+1. **Check existing issues** to avoid duplicates
+2. **Use the bug report template** when creating a new issue
+3. **Include**:
+   - Clear description of the problem
+   - Steps to reproduce
+   - Expected vs. actual behavior
+   - Your environment (Node.js version, OS, etc.)
+   - Relevant code samples or error messages
+
+### Suggesting Enhancements
+
+1. **Check existing feature requests** to avoid duplicates
+2. **Use the feature request template** when creating a new issue
+3. **Explain**:
+   - What problem this solves
+   - How it should work
+   - Why this would be useful to most users
+
+### Pull Requests
+
+1. **Create a feature branch**:
+
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes** following our [coding standards](#coding-standards)
+
+3. **Write or update tests** for your changes
+
+4. **Run the full test suite**:
+
+   ```bash
+   npm run all
+   ```
+
+5. **Commit your changes** with clear, descriptive messages:
+
+   ```bash
+   git commit -m "Add feature: brief description"
+   ```
+
+6. **Push to your fork**:
+
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+7. **Create a Pull Request** on GitHub
+
+## Coding Standards
+
+### JavaScript Style
+
+- Use **ES modules** (`import`/`export`)
+- Use **2 spaces** for indentation
+- Use **semicolons**
+- Use **single quotes** for strings
+- Follow **ESLint** configuration (run `npm run lint`)
+
+### Code Organization
+
+```javascript
+// 1. Imports at the top
+import { Something } from './module.js';
+
+// 2. Constants
+const CONSTANT_VALUE = 'value';
+
+// 3. Helper functions
+function helperFunction() { }
+
+// 4. Main exported functions/classes
+export function mainFunction() { }
+```
+
+### Naming Conventions
+
+- **Classes**: PascalCase (`Story`, `Passage`, `StoryFormat`)
+- **Functions**: camelCase (`parseTwee`, `compileTwine2HTML`)
+- **Constants**: UPPER_SNAKE_CASE (`CREATOR_VERSION`)
+- **Private fields**: Prefix with `#_` (`#_passages`, `#_name`)
+
+### Documentation
+
+- **All public functions** must have JSDoc comments
+- Include `@param`, `@returns`, `@throws` as appropriate
+- Add usage examples for complex functions
+- Update README.md if adding new features
+
+Example:
+
+```javascript
+/**
+ * Parse Twee 3 format into Story object.
+ * @function parse
+ * @param {string} contents - Twee 3 formatted string
+ * @returns {Story} Parsed Story object
+ * @throws {Error} If contents is not a string
+ * @throws {Error} If no passages are found
+ * @example
+ * const story = parseTwee(':: Start\nHello World!');
+ */
+export function parse(contents) {
+  // Implementation
+}
+```
+
+## Testing Guidelines
+
+### Test Requirements
+
+- **All new features** must include tests
+- **Bug fixes** should include regression tests
+- Maintain **>90% code coverage**
+- Tests must pass on all supported Node.js versions
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run specific test file
+npm test -- path/to/test.js
+
+# Run tests with coverage
+npm test -- --coverage
+
+# Run tests in watch mode (during development)
+npm test -- --watch
+```
+
+### Writing Tests
+
+- Use **Jest** testing framework
+- Follow **AAA pattern** (Arrange, Act, Assert)
+- Use **descriptive test names**
+- Group related tests with `describe` blocks
+
+Example:
+
+```javascript
+describe('parseTwee()', () => {
+  it('should parse a simple Twee file', () => {
+    // Arrange
+    const input = ':: Start\nHello World!';
+    
+    // Act
+    const story = parseTwee(input);
+    
+    // Assert
+    expect(story.passages).toHaveLength(1);
+    expect(story.passages[0].name).toBe('Start');
+    expect(story.passages[0].text).toBe('Hello World!');
+  });
+
+  it('should throw error for invalid input', () => {
+    expect(() => parseTwee(123)).toThrow();
+  });
+});
+```
+
+### Test Coverage Areas
+
+- **Unit tests**: Individual functions and methods
+- **Integration tests**: Multiple components working together
+- **Edge cases**: Invalid input, empty strings, special characters
+- **Error handling**: Proper error messages and types
+
+## Submitting Changes
+
+### Pull Request Guidelines
+
+1. **Keep PRs focused** - One feature/fix per PR
+2. **Update documentation** - README, JSDoc, CHANGELOG
+3. **Add tests** - Maintain or improve coverage
+4. **Follow commit conventions**:
+
+   ```text
+   type(scope): brief description
+   
+   Longer description if needed
+   
+   Fixes #123
+   ```
+
+   Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+
+5. **Ensure CI passes** - All tests and lints must pass
+6. **Request review** - Wait for maintainer feedback
+7. **Update your branch** if main has changed:
+
+   ```bash
+   git fetch upstream
+   git rebase upstream/main
+   ```
+
+### Commit Message Examples
+
+```bash
+# Good commit messages
+feat(parser): add support for metadata in passage headers
+fix(compiler): correct HTML entity encoding in passages
+docs(readme): add examples for JSON format
+test(twee): add edge case tests for escape sequences
+
+# Bad commit messages  
+fixed bug
+updates
+WIP
+asdf
+```
+
+## Release Process
+
+1. Update version in `package.json`
+2. Update `CHANGELOG.md` with release notes
+3. Run full test suite: `npm run all`
+4. Commit: `git commit -m "chore: release v2.3.13"`
+5. Tag: `git tag v2.3.13`
+6. Push: `git push && git push --tags`
+7. Publish: `npm publish`
+8. Create GitHub release with notes from CHANGELOG
+
+## Additional Resources
+
+- [Twine Specifications](https://github.com/iftechfoundation/twine-specs)
+- [Twee 3 Specification](https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md)
+- [Jest Documentation](https://jestjs.io/docs/getting-started)
+- [ESLint Rules](https://eslint.org/docs/rules/)
+
+## Questions?
+
+- Open a [Discussion](https://github.com/videlais/extwee/discussions) for questions
+- Check existing [Issues](https://github.com/videlais/extwee/issues) for known problems
+- Review [Documentation](https://videlais.github.io/extwee/) for usage help
+
+Thank you for contributing to Extwee! 🎉

package/README.md

@@ -217,6 +217,22 @@ When using the API, it is possible to only import a single function or object to
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on:
+
+- Setting up your development environment
+- Code style and standards
+- Testing requirements
+- Submitting pull requests
+
+See also:
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+- [Changelog](CHANGELOG.md)
+- [Security Policy](SECURITY.md)
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
 ## License
 
 Distributed under the MIT License. See `LICENSE.txt` for more information.