kjanat/articulate-parser
1
0
Fork 0
mirror of https://github.com/kjanat/articulate-parser.git synced 2026-01-16 09:42:09 +01:00
Code Issues Packages Projects Releases Wiki Activity

chore: Enhance developer tooling and documentation

Browse Source 
Adds `actionlint` to the pre-commit configuration to validate GitHub Actions workflows.

Significantly expands the `AGENTS.md` file with a comprehensive summary of new features and changes in Go 1.24 and 1.25, along with actionable recommendations for the project.

Additionally, normalizes markdown list formatting across various documentation files for consistency.
This commit is contained in:
Kaj Kowalski
2025-11-07 07:50:09 +01:00
parent 8d606706e2
commit a1a49a75b7
10 changed files with 672 additions and 279 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
.github/CODE_OF_CONDUCT.md vendored
View File

@ -17,23 +17,23 @@ diverse, inclusive, and healthy community.
Examples of behavior that contributes to a positive environment for our
community include:
- Demonstrating empathy and kindness toward other people
- Being respectful of differing opinions, viewpoints, and experiences
- Giving and gracefully accepting constructive feedback
- Accepting responsibility and apologizing to those affected by our mistakes,
- Demonstrating empathy and kindness toward other people
- Being respectful of differing opinions, viewpoints, and experiences
- Giving and gracefully accepting constructive feedback
- Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
- Focusing on what is best not just for us as individuals, but for the
- Focusing on what is best not just for us as individuals, but for the
overall community
Examples of unacceptable behavior include:
- The use of sexualized language or imagery, and sexual attention or
- The use of sexualized language or imagery, and sexual attention or
advances of any kind
- Trolling, insulting or derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others' private information, such as a physical or email
- Trolling, insulting or derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others' private information, such as a physical or email
address, without their explicit permission
- Other conduct which could reasonably be considered inappropriate in a
- Other conduct which could reasonably be considered inappropriate in a
professional setting
## Enforcement Responsibilities

108
.github/CONTRIBUTING.md vendored
View File

@ -12,38 +12,38 @@ This project and everyone participating in it is governed by our Code of Conduct
Before creating bug reports, please check existing issues as you might find that the issue has already been reported. When creating a bug report, include as many details as possible:
- Use the bug report template
- Include sample Articulate Rise content that reproduces the issue
- Provide your environment details (OS, Go version, etc.)
- Include error messages and stack traces
- Use the bug report template
- Include sample Articulate Rise content that reproduces the issue
- Provide your environment details (OS, Go version, etc.)
- Include error messages and stack traces
### Suggesting Enhancements
Enhancement suggestions are welcome! Please use the feature request template and include:
- A clear description of the enhancement
- Your use case and why this would be valuable
- Any implementation ideas you might have
- A clear description of the enhancement
- Your use case and why this would be valuable
- Any implementation ideas you might have
### Pull Requests
1. **Fork the repository** and create your branch from `master`
2. **Make your changes** following our coding standards
3. **Add tests** for any new functionality
4. **Ensure all tests pass** by running `go test ./...`
5. **Run `go fmt`** to format your code
6. **Run `go vet`** to check for common issues
7. **Update documentation** if needed
8. **Create a pull request** with a clear title and description
1. **Fork the repository** and create your branch from `master`
2. **Make your changes** following our coding standards
3. **Add tests** for any new functionality
4. **Ensure all tests pass** by running `go test ./...`
5. **Run `go fmt`** to format your code
6. **Run `go vet`** to check for common issues
7. **Update documentation** if needed
8. **Create a pull request** with a clear title and description
## Development Setup
1. **Prerequisites:**
1. **Prerequisites:**
- Go 1.21 or later
- Git
- Go 1.21 or later
- Git
2. **Clone and setup:**
2. **Clone and setup:**
```bash
git clone https://github.com/your-username/articulate-parser.git
@ -51,13 +51,13 @@ Enhancement suggestions are welcome! Please use the feature request template and
go mod download
```
3. **Run tests:**
3. **Run tests:**
```bash
go test -v ./...
```
4. **Build:**
4. **Build:**
```bash
go build main.go
@ -67,18 +67,18 @@ Enhancement suggestions are welcome! Please use the feature request template and
### Go Style Guide
- Follow the [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
- Use `gofmt` to format your code
- Use meaningful variable and function names
- Add comments for exported functions and types
- Keep functions focused and small
- Follow the [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
- Use `gofmt` to format your code
- Use meaningful variable and function names
- Add comments for exported functions and types
- Keep functions focused and small
### Testing
- Write tests for new functionality
- Use table-driven tests where appropriate
- Aim for good test coverage
- Test error cases and edge conditions
- Write tests for new functionality
- Use table-driven tests where appropriate
- Aim for good test coverage
- Test error cases and edge conditions
### Commit Messages
@ -112,19 +112,19 @@ articulate-parser/
### New Content Types
1. Add the content type definition to `types/`
2. Implement parsing logic in `parser/`
3. Add export handling in `exporters/`
4. Write comprehensive tests
5. Update documentation
1. Add the content type definition to `types/`
2. Implement parsing logic in `parser/`
3. Add export handling in `exporters/`
4. Write comprehensive tests
5. Update documentation
### New Export Formats
1. Create a new exporter in `exporters/`
2. Implement the `Exporter` interface
3. Add CLI support in `main.go`
4. Add tests with sample output
5. Update README with usage examples
1. Create a new exporter in `exporters/`
2. Implement the `Exporter` interface
3. Add CLI support in `main.go`
4. Add tests with sample output
5. Update README with usage examples
## Testing
@ -146,31 +146,31 @@ go test -run TestSpecificFunction ./...
### Test Data
- Add sample Articulate Rise JSON files to `tests/data/`
- Include both simple and complex content examples
- Test edge cases and error conditions
- Add sample Articulate Rise JSON files to `tests/data/`
- Include both simple and complex content examples
- Test edge cases and error conditions
## Documentation
- Update the README for user-facing changes
- Add inline code comments for complex logic
- Update examples when adding new features
- Keep the feature list current
- Update the README for user-facing changes
- Add inline code comments for complex logic
- Update examples when adding new features
- Keep the feature list current
## Release Process
Releases are handled by maintainers:
1. Version bumping follows semantic versioning
2. Releases are created from the `master` branch
3. GitHub Actions automatically builds and publishes releases
4. Release notes are auto-generated from commits
1. Version bumping follows semantic versioning
2. Releases are created from the `master` branch
3. GitHub Actions automatically builds and publishes releases
4. Release notes are auto-generated from commits
## Questions?
- Open a discussion for general questions
- Use the question issue template for specific help
- Check existing issues and documentation first
- Open a discussion for general questions
- Use the question issue template for specific help
- Check existing issues and documentation first
## Recognition

32
.github/PULL_REQUEST_TEMPLATE.md vendored
View File

@ -10,26 +10,26 @@ Fixes #
## Type of Change
<!-- Mark the appropriate option with an "x" -->
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)
- [ ] Test updates
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)
- [ ] Test updates
## Checklist
<!-- Mark the items you've completed with an "x" -->
- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have added comments to complex logic
- [ ] I have updated the documentation
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] I have checked for potential breaking changes
- [ ] No new warnings are generated
- [ ] The commit message follows our guidelines
- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have added comments to complex logic
- [ ] I have updated the documentation
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] I have checked for potential breaking changes
- [ ] No new warnings are generated
- [ ] The commit message follows our guidelines
## Screenshots (if appropriate)

32
.github/SECURITY.md vendored
View File

@ -13,32 +13,32 @@ Currently, the following versions of Articulate Rise Parser are supported with s
We take the security of Articulate Rise Parser seriously. If you believe you have found a security vulnerability, please follow these steps:
1. **Do not disclose the vulnerability publicly** - Please do not create a public GitHub issue for security vulnerabilities.
2. **Email the details to [security+articulate-parser@kjanat.com]** - Include as much information as possible about the vulnerability.
3. **Wait for a response** - We will acknowledge your email within 48 hours and provide an estimated timeline for a fix.
4. **Work with us** - We may ask for additional information to help us understand and address the issue.
1. **Do not disclose the vulnerability publicly** - Please do not create a public GitHub issue for security vulnerabilities.
2. **Email the details to [security+articulate-parser@kjanat.com]** - Include as much information as possible about the vulnerability.
3. **Wait for a response** - We will acknowledge your email within 48 hours and provide an estimated timeline for a fix.
4. **Work with us** - We may ask for additional information to help us understand and address the issue.
## What to Include in a Report
When reporting a vulnerability, please include:
- A clear description of the issue
- Steps to reproduce the vulnerability
- The potential impact of the vulnerability
- Any possible mitigations you've identified
- A clear description of the issue
- Steps to reproduce the vulnerability
- The potential impact of the vulnerability
- Any possible mitigations you've identified
## What to Expect
- We will acknowledge receipt of your vulnerability report within 48 hours.
- We will provide regular updates about our progress.
- We will notify you when the vulnerability is fixed.
- With your permission, we will include your name in the acknowledgments.
- We will acknowledge receipt of your vulnerability report within 48 hours.
- We will provide regular updates about our progress.
- We will notify you when the vulnerability is fixed.
- With your permission, we will include your name in the acknowledgments.
## Security Measures
This project follows these security practices:
- Regular dependency updates via Dependabot
- CodeQL security scanning
- Automated testing for each pull request
- Code review requirements for all changes
- Regular dependency updates via Dependabot
- CodeQL security scanning
- Automated testing for each pull request
- Code review requirements for all changes

2
.github/workflows/autofix.yml vendored
View File

@ -22,7 +22,7 @@ jobs:
- name: Setup go deps
run: |
# Install golangci-lint
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b $(go env GOPATH)/bin
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b "$(go env GOPATH)/bin"
# Install go-task dependencies
go install golang.org/x/tools/cmd/goimports@latest

184
.github/workflows/ci.yml vendored
View File

@ -67,13 +67,15 @@ jobs:
env:
CGO_ENABLED: 1
run: |
cat >> $GITHUB_STEP_SUMMARY << EOF
{
cat << EOF
## 🔧 Test Environment
- **Go Version:** ${{ matrix.go }}
- **OS:** ubuntu-latest
- **Timestamp:** $(date -u)
EOF
} >> "$GITHUB_STEP_SUMMARY"
echo "Running tests with coverage..."
task test:coverage 2>&1 | tee test-output.log
@ -86,16 +88,17 @@ jobs:
SKIPPED_TESTS=$(grep -c -- "--- SKIP:" test-output.log || echo "0")
# Generate test summary
cat >> $GITHUB_STEP_SUMMARY << EOF
{
cat << EOF
## 🧪 Test Results (Go ${{ matrix.go }})
| Metric | Value |
| ----------- | ----------------------------------------------------------- |
| Total Tests | $TOTAL_TESTS |
| Passed | $PASSED_TESTS |
| Failed | $FAILED_TESTS |
| Skipped | $SKIPPED_TESTS |
| Status | $([ $TEST_STATUS -eq 0 ] && echo "PASSED" || echo "FAILED") |
| Metric | Value |
| ----------- | ------------------------------------------------------------- |
| Total Tests | $TOTAL_TESTS |
| Passed | $PASSED_TESTS |
| Failed | $FAILED_TESTS |
| Skipped | $SKIPPED_TESTS |
| Status | $([ "$TEST_STATUS" -eq 0 ] && echo "PASSED" || echo "FAILED") |
### 📦 Package Test Results
@ -107,36 +110,39 @@ jobs:
grep "^ok\|^FAIL" test-output.log | while read -r line; do
if [[ $line == ok* ]]; then
pkg=$(echo "$line" | awk '{print $2}')
echo "| $pkg | ✅ PASS |" >> $GITHUB_STEP_SUMMARY
echo "| $pkg | ✅ PASS |"
elif [[ $line == FAIL* ]]; then
pkg=$(echo "$line" | awk '{print $2}')
echo "| $pkg | ❌ FAIL |" >> $GITHUB_STEP_SUMMARY
echo "| $pkg | ❌ FAIL |"
fi
done
echo "" >> $GITHUB_STEP_SUMMARY
echo ""
# Add detailed results if tests failed
if [ $TEST_STATUS -ne 0 ]; then
cat >> $GITHUB_STEP_SUMMARY << 'EOF'
if [ "$TEST_STATUS" -ne 0 ]; then
cat << 'EOF'
### ❌ Failed Tests Details
```
EOF
grep -A 10 -- "--- FAIL:" test-output.log | head -100 >> $GITHUB_STEP_SUMMARY
cat >> $GITHUB_STEP_SUMMARY << 'EOF'
grep -A 10 -- "--- FAIL:" test-output.log | head -100
cat << 'EOF'
```
EOF
fi
} >> "$GITHUB_STEP_SUMMARY"
# Set outputs for other steps
echo "test-status=$TEST_STATUS" >> $GITHUB_OUTPUT
echo "total-tests=$TOTAL_TESTS" >> $GITHUB_OUTPUT
echo "passed-tests=$PASSED_TESTS" >> $GITHUB_OUTPUT
echo "failed-tests=$FAILED_TESTS" >> $GITHUB_OUTPUT
{
echo "test-status=$TEST_STATUS"
echo "total-tests=$TOTAL_TESTS"
echo "passed-tests=$PASSED_TESTS"
echo "failed-tests=$FAILED_TESTS"
} >> "$GITHUB_OUTPUT"
# Exit with the original test status
exit $TEST_STATUS
exit "$TEST_STATUS"
- name: Generate coverage report
if: always()
@ -144,7 +150,8 @@ jobs:
if [ -f coverage/coverage.out ]; then
COVERAGE=$(go tool cover -func=coverage/coverage.out | grep total | awk '{print $3}')
cat >> $GITHUB_STEP_SUMMARY << EOF
{
cat << EOF
## 📊 Code Coverage (Go ${{ matrix.go }})
**Total Coverage: $COVERAGE**
@ -156,45 +163,46 @@ jobs:
| ------- | -------- |
EOF
# Create temporary file for package coverage aggregation
temp_coverage=$(mktemp)
# Create temporary file for package coverage aggregation
temp_coverage=$(mktemp)
# Extract package-level coverage data
go tool cover -func=coverage/coverage.out | grep -v total | while read -r line; do
if [[ $line == *".go:"* ]]; then
# Extract package path from file path (everything before the filename)
filepath=$(echo "$line" | awk '{print $1}')
pkg_path=$(dirname "$filepath" | sed 's|github.com/kjanat/articulate-parser/||; s|^\./||')
coverage=$(echo "$line" | awk '{print $3}' | sed 's/%//')
# Extract package-level coverage data
go tool cover -func=coverage/coverage.out | grep -v total | while read -r line; do
if [[ $line == *".go:"* ]]; then
# Extract package path from file path (everything before the filename)
filepath=$(echo "$line" | awk '{print $1}')
pkg_path=$(dirname "$filepath" | sed 's|github.com/kjanat/articulate-parser/||; s|^\./||')
coverage=$(echo "$line" | awk '{print $3}' | sed 's/%//')
# Use root package if no subdirectory
[[ "$pkg_path" == "." || "$pkg_path" == "" ]] && pkg_path="root"
# Use root package if no subdirectory
[[ "$pkg_path" == "." || "$pkg_path" == "" ]] && pkg_path="root"
echo "$pkg_path $coverage" >> "$temp_coverage"
fi
done
echo "$pkg_path $coverage" >> "$temp_coverage"
fi
done
# Aggregate coverage by package (average)
awk '{
packages[$1] += $2
counts[$1]++
}
END {
for (pkg in packages) {
avg = packages[pkg] / counts[pkg]
printf "| %s | %.1f%% |\n", pkg, avg
# Aggregate coverage by package (average)
awk '{
packages[$1] += $2
counts[$1]++
}
}' "$temp_coverage" | sort >> $GITHUB_STEP_SUMMARY
END {
for (pkg in packages) {
avg = packages[pkg] / counts[pkg]
printf "| %s | %.1f%% |\n", pkg, avg
}
}' "$temp_coverage" | sort
rm -f "$temp_coverage"
rm -f "$temp_coverage"
cat >> $GITHUB_STEP_SUMMARY << 'EOF'
cat << 'EOF'
</details>
EOF
} >> "$GITHUB_STEP_SUMMARY"
else
cat >> $GITHUB_STEP_SUMMARY << 'EOF'
cat >> "$GITHUB_STEP_SUMMARY" << 'EOF'
## ⚠️ Coverage Report
No coverage file generated
@ -214,51 +222,53 @@ jobs:
- name: Run linters
run: |
# Initialize summary
cat >> $GITHUB_STEP_SUMMARY << EOF
{
cat << EOF
## 🔍 Static Analysis (Go ${{ matrix.go }})
EOF
# Run go vet
VET_OUTPUT=$(task lint:vet 2>&1 || echo "")
VET_STATUS=$?
# Run go vet
VET_OUTPUT=$(task lint:vet 2>&1 || echo "")
VET_STATUS=$?
if [ $VET_STATUS -eq 0 ]; then
echo "✅ **go vet:** No issues found" >> $GITHUB_STEP_SUMMARY
else
cat >> $GITHUB_STEP_SUMMARY << 'EOF'
if [ "$VET_STATUS" -eq 0 ]; then
echo "✅ **go vet:** No issues found"
else
cat << 'EOF'
❌ **go vet:** Issues found
```
EOF
echo "$VET_OUTPUT" >> $GITHUB_STEP_SUMMARY
echo '```' >> $GITHUB_STEP_SUMMARY
fi
echo "" >> $GITHUB_STEP_SUMMARY
echo "$VET_OUTPUT"
echo '```'
fi
echo ""
# Run go fmt check
FMT_OUTPUT=$(task lint:fmt 2>&1 || echo "")
FMT_STATUS=$?
# Run go fmt check
FMT_OUTPUT=$(task lint:fmt 2>&1 || echo "")
FMT_STATUS=$?
if [ $FMT_STATUS -eq 0 ]; then
echo "✅ **go fmt:** All files properly formatted" >> $GITHUB_STEP_SUMMARY
else
cat >> $GITHUB_STEP_SUMMARY << 'EOF'
if [ "$FMT_STATUS" -eq 0 ]; then
echo "✅ **go fmt:** All files properly formatted"
else
cat << 'EOF'
❌ **go fmt:** Files need formatting
```
EOF
echo "$FMT_OUTPUT" >> $GITHUB_STEP_SUMMARY
echo '```' >> $GITHUB_STEP_SUMMARY
fi
echo "$FMT_OUTPUT"
echo '```'
fi
} >> "$GITHUB_STEP_SUMMARY"
# Exit with error if any linter failed
[ $VET_STATUS -eq 0 ] && [ $FMT_STATUS -eq 0 ] || exit 1
[ "$VET_STATUS" -eq 0 ] && [ "$FMT_STATUS" -eq 0 ] || exit 1
- name: Job Summary
if: always()
run: |
cat >> $GITHUB_STEP_SUMMARY << 'EOF'
cat >> "$GITHUB_STEP_SUMMARY" << 'EOF'
## 📋 Job Summary (Go ${{ matrix.go }})
| Step | Status |
@ -313,24 +323,26 @@ jobs:
- name: Test Docker image using Task
run: |
cat >> $GITHUB_STEP_SUMMARY << 'EOF'
{
cat << 'EOF'
## 🧪 Docker Image Tests
EOF
# Run Task docker test
task docker:test
# Run Task docker test
task docker:test
echo "**Testing help command:**" >> $GITHUB_STEP_SUMMARY
echo '```terminaloutput' >> $GITHUB_STEP_SUMMARY
docker run --rm articulate-parser:latest --help >> $GITHUB_STEP_SUMMARY
echo '```' >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
echo "**Testing help command:**"
echo '```terminaloutput'
docker run --rm articulate-parser:latest --help
echo '```'
echo ""
# Test image size
IMAGE_SIZE=$(docker image inspect articulate-parser:latest --format='{{.Size}}' | numfmt --to=iec-i --suffix=B)
echo "**Image size:** $IMAGE_SIZE" >> $GITHUB_STEP_SUMMARY
echo "" >> $GITHUB_STEP_SUMMARY
# Test image size
IMAGE_SIZE=$(docker image inspect articulate-parser:latest --format='{{.Size}}' | numfmt --to=iec-i --suffix=B)
echo "**Image size:** $IMAGE_SIZE"
echo ""
} >> "$GITHUB_STEP_SUMMARY"
dependency-review:
name: Dependency Review
@ -433,7 +445,7 @@ jobs:
- name: Generate Docker summary
run: |
cat >> $GITHUB_STEP_SUMMARY << 'EOF'
cat >> "$GITHUB_STEP_SUMMARY" << 'EOF'
## 🐳 Docker Build Summary
**Image:** `ghcr.io/${{ github.repository }}`