feat(git): enhance branch detection and checkout handling (#110) #113

Workflow file for this run

	name: Documentation

	on:
	push:
	branches: [ master ]
	paths:
	- 'src/**'
	- 'README*.md'
	- 'docs/**'
	- '.github/workflows/docs.yml'
	pull_request:
	branches: [ master ]
	paths:
	- 'src/**'
	- 'README*.md'
	- 'docs/**'
	workflow_dispatch:

	jobs:
	validate-documentation:
	name: Validate Documentation
	runs-on: ubuntu-latest

	steps:
	- name: Checkout code
	uses: actions/checkout@v4

	- name: Setup Node.js
	uses: actions/setup-node@v4
	with:
	node-version: '22'
	cache: 'npm'

	- name: Install dependencies
	run: npm ci

	- name: Check README files
	run: \|
	echo "📚 Documentation Validation"
	echo "=========================="

	# Check README.md
	if [ -f README.md ]; then
	echo "✅ README.md exists"
	README_LINES=$(wc -l < README.md)
	echo " Lines: $README_LINES"

	# Check for required sections
	if grep -q "## 功能特性" README.md; then
	echo " ✅ Features section found"
	else
	echo " ⚠️ Features section missing"
	fi

	if grep -q "## 安装配置" README.md; then
	echo " ✅ Installation section found"
	else
	echo " ⚠️ Installation section missing"
	fi

	if grep -q "## 使用方法" README.md; then
	echo " ✅ Usage section found"
	else
	echo " ⚠️ Usage section missing"
	fi
	else
	echo "❌ README.md missing"
	fi

	# Check README-EN.md
	if [ -f README-EN.md ]; then
	echo "✅ README-EN.md exists"
	README_EN_LINES=$(wc -l < README-EN.md)
	echo " Lines: $README_EN_LINES"
	else
	echo "⚠️ README-EN.md missing"
	fi

	- name: Validate package.json documentation
	run: \|
	echo "📦 Package.json Documentation Check"
	echo "=================================="

	node -e "
	const pkg = require('./package.json');

	console.log('Package name:', pkg.name);
	console.log('Description:', pkg.description \|\| 'MISSING');
	console.log('Version:', pkg.version);
	console.log('Author:', pkg.author \|\| 'MISSING');
	console.log('License:', pkg.license \|\| 'MISSING');
	console.log('Repository:', pkg.repository?.url \|\| 'MISSING');
	console.log('Homepage:', pkg.homepage \|\| 'Not set');
	console.log('Keywords:', pkg.keywords?.length \|\| 0, 'keywords');

	// Check for required fields
	const required = ['name', 'version', 'description', 'author', 'license'];
	const missing = required.filter(field => !pkg[field]);

	if (missing.length > 0) {
	console.log('❌ Missing required fields:', missing.join(', '));
	process.exit(1);
	} else {
	console.log('✅ All required fields present');
	}
	"

	- name: Check license file
	run: \|
	echo "📄 License Documentation"
	echo "======================"

	if [ -f LICENSE ]; then
	echo "✅ LICENSE file exists"
	LICENSE_LINES=$(wc -l < LICENSE)
	echo " Lines: $LICENSE_LINES"

	# Check license content
	if grep -q "MIT License" LICENSE; then
	echo " ✅ MIT License detected"
	elif grep -q "Apache License" LICENSE; then
	echo " ✅ Apache License detected"
	else
	echo " ⚠️ License type unclear"
	fi
	else
	echo "❌ LICENSE file missing"
	fi

	- name: Validate inline documentation
	run: \|
	echo "💬 Inline Code Documentation"
	echo "============================"

	# Count TSDoc comments
	TSDOC_COUNT=$(grep -r "\/\\" src/ --include="*.ts" \| wc -l)
	echo "TSDoc comments found: $TSDOC_COUNT"

	# Count exported functions/classes
	EXPORTS_COUNT=$(grep -r "^export " src/ --include="*.ts" \| wc -l)
	echo "Exported items: $EXPORTS_COUNT"

	# Calculate documentation coverage (rough estimate)
	if [ $EXPORTS_COUNT -gt 0 ]; then
	DOC_COVERAGE=$((TSDOC_COUNT * 100 / EXPORTS_COUNT))
	echo "Estimated documentation coverage: ${DOC_COVERAGE}%"

	if [ $DOC_COVERAGE -lt 50 ]; then
	echo "⚠️ Low documentation coverage"
	else
	echo "✅ Good documentation coverage"
	fi
	fi

	generate-api-docs:
	name: Generate API Documentation
	runs-on: ubuntu-latest

	steps:
	- name: Checkout code
	uses: actions/checkout@v4

	- name: Setup Node.js
	uses: actions/setup-node@v4
	with:
	node-version: '22'
	cache: 'npm'

	- name: Install dependencies
	run: npm ci

	- name: Install TypeDoc
	run: npm install -g typedoc

	- name: Build project
	run: npm run build

	- name: Ensure docs directory structure
	run: \|
	echo "📁 Ensuring docs directory structure"
	echo "==================================="

	# Create docs directory structure
	mkdir -p docs/api docs/cli docs/workflows

	- name: Generate API documentation
	run: \|
	echo "📖 Generating API Documentation"
	echo "=============================="

	# Generate TypeDoc documentation
	typedoc src/index.ts \
	--out docs/api \
	--theme default \
	--name "AIFlow API Documentation" \
	--readme README.md \
	--exclude "*/.test.ts" \
	--exclude "/test/" \
	--excludePrivate \
	--excludeProtected \
	--excludeInternal

	- name: Generate CLI documentation
	run: \|
	echo "⌨️ Generating CLI Documentation"
	echo "=============================="

	# Generate CLI help documentation
	echo "# AIFlow CLI Documentation" > docs/cli/README.md
	echo "" >> docs/cli/README.md
	echo "## aiflow Command" >> docs/cli/README.md
	echo "" >> docs/cli/README.md
	echo "\`\`\`" >> docs/cli/README.md
	timeout 30s node dist/aiflow-app.js --help >> docs/cli/README.md \|\| echo "Help command completed"
	echo "\`\`\`" >> docs/cli/README.md
	echo "" >> docs/cli/README.md

	echo "## aiflow-conan Command" >> docs/cli/README.md
	echo "" >> docs/cli/README.md
	echo "\`\`\`" >> docs/cli/README.md
	timeout 30s node dist/aiflow-conan-app.js --help >> docs/cli/README.md \|\| echo "Help command completed"
	echo "\`\`\`" >> docs/cli/README.md
	echo "" >> docs/cli/README.md

	echo "## Configuration Help" >> docs/cli/README.md
	echo "" >> docs/cli/README.md
	echo "### aiflow Configuration" >> docs/cli/README.md
	echo "\`\`\`" >> docs/cli/README.md
	timeout 30s node dist/aiflow-app.js --config-help >> docs/cli/README.md \|\| echo "Config help completed"
	echo "\`\`\`" >> docs/cli/README.md
	echo "" >> docs/cli/README.md

	echo "### aiflow-conan Configuration" >> docs/cli/README.md
	echo "\`\`\`" >> docs/cli/README.md
	timeout 30s node dist/aiflow-conan-app.js --config-help >> docs/cli/README.md \|\| echo "Config help completed"
	echo "\`\`\`" >> docs/cli/README.md

	- name: Generate workflow documentation
	run: \|
	echo "🔄 Generating Workflow Documentation"
	echo "=================================="

	cat << 'EOF' > docs/workflows/README.md
	# GitHub Actions Workflows

	This project uses several GitHub Actions workflows for CI/CD automation:

	## Available Workflows

	### CI/CD Pipeline (`ci.yml`)
	- Trigger: Push/PR to master branches
	- Purpose: Build, test, and validate code quality
	- Jobs:
	- Lint and type checking
	- Multi-platform testing (Ubuntu, Windows, macOS)
	- Build and package verification
	- Security audit
	- Integration testing

	### Release (`release.yml`)
	- Trigger: Release published or manual dispatch
	- Purpose: Build and publish releases to NPM
	- Jobs:
	- Version validation
	- Multi-platform artifact building
	- GitHub release creation
	- NPM publication
	- Post-release validation

	### Code Quality (`quality.yml`)
	- Trigger: Push/PR to master branches, daily schedule
	- Purpose: Comprehensive code quality and security analysis
	- Jobs:
	- CodeQL security analysis
	- Dependency vulnerability scanning
	- License compliance checking
	- Static code analysis
	- Performance analysis

	### Dependency Updates (`dependency-update.yml`)
	- Trigger: Weekly schedule or manual dispatch
	- Purpose: Automated dependency management
	- Jobs:
	- Security updates
	- Patch/minor version updates
	- Vulnerability assessment

	### Performance Monitoring (`performance.yml`)
	- Trigger: Push to master, PR, daily schedule
	- Purpose: Monitor and track performance metrics
	- Jobs:
	- Build performance benchmarking
	- CLI performance testing
	- Package size analysis
	- Load testing
	- Performance regression detection

	### Documentation (`docs.yml`)
	- Trigger: Changes to docs or source code
	- Purpose: Validate and generate documentation
	- Jobs:
	- Documentation validation
	- API documentation generation
	- CLI documentation generation

	## Manual Workflow Triggers

	Several workflows can be triggered manually:

	1. Release Workflow: Create a new release
	- Go to Actions → Release and Publish → Run workflow
	- Specify version and prerelease flag

	2. Dependency Updates: Update dependencies
	- Go to Actions → Dependency Updates → Run workflow
	- Choose update type (patch, minor, major, all)

	3. Performance Testing: Run performance benchmarks
	- Go to Actions → Performance Monitoring → Run workflow

	## Workflow Status

	You can monitor workflow status through:
	- GitHub Actions tab
	- Commit status checks
	- PR status checks
	- Release status

	## Secrets Configuration

	Required secrets for workflows:
	- `NPM_TOKEN`: For NPM publishing (release workflow)
	- `ACCESS_TOKEN`: Automatically provided by GitHub

	## Workflow Artifacts

	Workflows generate various artifacts:
	- Build artifacts (dist files, packages)
	- Test reports
	- Performance metrics
	- Security scan results
	- Documentation

	Artifacts are retained for 7-30 days depending on the workflow.
	EOF

	- name: Update documentation index
	run: \|
	echo "📑 Updating Documentation Index"
	echo "=============================="

	# Get current version from package.json
	VERSION=$(node -p "require('./package.json').version")
	echo "Current version: $VERSION"

	# Update index.html using template with dynamic version
	echo "Updating docs/index.html with version $VERSION using template..."

	# Use sed to replace version in template
	sed "s/v{{VERSION}}/v$VERSION/g" docs/template.html > docs/index.html

	cp README.md docs/
	cp README-EN.md docs/
	cp config.example.yaml docs/
	cp LICENSE docs/

	echo "✅ Generated docs/index.html from template with version $VERSION"

	- name: Upload documentation artifacts
	uses: actions/upload-artifact@v4
	with:
	name: documentation
	path: docs/
	retention-days: 30

	validate-links:
	name: Validate Documentation Links
	runs-on: ubuntu-latest

	steps:
	- name: Checkout code
	uses: actions/checkout@v4

	- name: Install markdown link checker
	run: npm install -g markdown-link-check

	- name: Check README links
	run: \|
	echo "🔗 Checking Documentation Links"
	echo "=============================="

	# Check master README
	if [ -f README.md ]; then
	echo "Checking README.md links:"
	markdown-link-check README.md --config .github/mlc-config.json \|\| echo "Some links may be broken"
	fi

	# Check English README
	if [ -f README-EN.md ]; then
	echo "Checking README-EN.md links:"
	markdown-link-check README-EN.md --config .github/mlc-config.json \|\| echo "Some links may be broken"
	fi

	- name: Create link checker config
	run: \|
	mkdir -p .github
	cat << 'EOF' > .github/mlc-config.json
	{
	"ignorePatterns": [
	{
	"pattern": "^http://localhost"
	},
	{
	"pattern": "^https://api.openai.com"
	},
	{
	"pattern": "^https://.*\\.example\\.com"
	}
	],
	"timeout": "20s",
	"retryOn429": true,
	"retryCount": 3,
	"fallbackRetryDelay": "30s",
	"aliveStatusCodes": [200, 206, 301, 302, 403, 999]
	}
	EOF

	spell-check:
	name: Spell Check Documentation
	runs-on: ubuntu-latest

	steps:
	- name: Checkout code
	uses: actions/checkout@v4

	- name: Install spell checker
	run: \|
	sudo apt-get update
	sudo apt-get install -y aspell aspell-en

	- name: Check spelling in documentation
	run: \|
	echo "📝 Spell Checking Documentation"
	echo "=============================="

	# Create word list for technical terms
	cat << 'EOF' > .aspell.en.pws
	personal_ws-1.1 en 100
	AIFlow
	TypeScript
	JavaScript
	GitHub
	GitLab
	Gitee
	OpenAI
	API
	CLI
	npm
	Node
	Conan
	webhook
	WeChat
	WeCom
	ESM
	TSDoc
	JSDoc
	config
	yaml
	json
	EOF

	# Check README files for spelling
	if [ -f README.md ]; then
	echo "Spell checking README.md (English sections):"
	# Extract English text and check
	grep -E "^\s#\|^\s-\|^\s\\|^[A-Za-z]" README.md \| \
	aspell --lang=en --personal=.aspell.en.pws list \| \
	sort -u \| head -20 \|\| echo "Spell check completed"
	fi

	if [ -f README-EN.md ]; then
	echo "Spell checking README-EN.md:"
	aspell --lang=en --personal=.aspell.en.pws list < README-EN.md \| \
	sort -u \| head -20 \|\| echo "Spell check completed"
	fi

	publish-docs:
	name: Publish Documentation
	runs-on: ubuntu-latest
	needs: [validate-documentation, generate-api-docs, validate-links]
	if: github.event_name == 'push' && github.ref == 'refs/heads/master'

	permissions:
	contents: read
	pages: write
	id-token: write

	steps:
	- name: Checkout code
	uses: actions/checkout@v4

	- name: Download documentation artifacts
	uses: actions/download-artifact@v4
	with:
	name: documentation
	path: docs/

	- name: Setup GitHub Pages
	uses: actions/configure-pages@v4

	- name: Upload to GitHub Pages
	uses: actions/upload-pages-artifact@v3
	with:
	path: docs/

	- name: Deploy to GitHub Pages
	id: deployment
	uses: actions/deploy-pages@v4
	env:
	GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN}}

	- name: Create deployment summary
	run: \|
	echo "# 📚 Documentation Published" >> $GITHUB_STEP_SUMMARY
	echo "" >> $GITHUB_STEP_SUMMARY
	echo "Documentation has been successfully published to GitHub Pages." >> $GITHUB_STEP_SUMMARY
	echo "" >> $GITHUB_STEP_SUMMARY
	echo "URL: ${{ steps.deployment.outputs.page_url }}" >> $GITHUB_STEP_SUMMARY
	echo "" >> $GITHUB_STEP_SUMMARY
	echo "## 📋 Published Documentation" >> $GITHUB_STEP_SUMMARY
	echo "- API Documentation" >> $GITHUB_STEP_SUMMARY
	echo "- CLI Documentation" >> $GITHUB_STEP_SUMMARY
	echo "- Workflow Documentation" >> $GITHUB_STEP_SUMMARY
	echo "" >> $GITHUB_STEP_SUMMARY
	echo "Documentation will be available at the URL above within a few minutes." >> $GITHUB_STEP_SUMMARY

Navigation Menu

feat(git): enhance branch detection and checkout handling (#110) #113

Workflow file

feat(git): enhance branch detection and checkout handling (#110) #113

Uh oh!

Workflow file for this run