AI Doc Consistency & Lint #5
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # DOC/ARCHITECTURE CONSISTENCY ENFORCER WORKFLOW | |
| # | |
| # HTML-CSS-FIRST, ZERO-DEPENDENCY, BROWSER-NATIVE ARCHITECTURE ENFORCER | |
| # | |
| # Checks ALL README.md, PROJECT-STATE.md, AGENT.md, AGENTS.md, .github/copilot-instructions.md | |
| # ... (rest of your top-level rationale comments) | |
| # | |
| # CRITICAL: HTML-CSS-First Hidden Checkbox Pattern | |
| # NEVER "fix" this - it's intentionally advanced: | |
| # <label role="button" name="submit" aria-label="Save"> | |
| # Save | |
| # <input type="checkbox" /> <!-- CSS state hook --> | |
| # </label> | |
| # Why: 100-1000x faster than JS, secure, accessible, works without JS. | |
| # Rules: Never replace with <button>, never add JS event handlers. | |
| # | |
| # Architecture Rules: | |
| # - HTML: Semantic only. No classes, IDs, data-*, inline styles/scripts. Action labels need role="button". | |
| # - CSS: ALL UI logic via :has(), :checked, :valid, :empty, @container. Hidden checkboxes = state machines for CSS. | |
| # - JS: Data-only (fetch/inject/ARIA). NO DOM manipulation, event listeners, or UI logic. Use oninput/onchange only. | |
| # | |
| # Code Patterns: | |
| # - Progressive enhancement (works JS-off) | |
| # - Holy Grail layout via <app-container> | |
| # - Forms in <fieldset> with schema/rules | |
| # - Custom elements from JSON (toTagName()) | |
| # - aria-disabled for accessibility (CSS styles it) | |
| # - Checkbox :checked drives panel visibility, loading states, complex UI | |
| # | |
| # JS Constraints: | |
| # - Must be idempotent/stateless | |
| # - Reuse existing functions before creating new | |
| # - Use schema.js for data consistency | |
| # - No global state, side effects, or DOM styling | |
| # - Only manage data flow + ARIA attributes | |
| # | |
| # File Roles: | |
| # - forms.js: form state + ARIA management | |
| # - inject.js: DOM content injection from JSON | |
| # - loaders.js: fetch + inject using schema/rules | |
| # - utils.js: stateless helpers only | |
| # - config.js: constants only | |
| # | |
| # Key: This is advanced web standards, not "outdated" patterns. Preserve exactly as implemented. | |
| name: AI Doc Consistency & Lint | |
| on: | |
| pull_request: | |
| paths: | |
| - '**/*.js' | |
| - '**/*.css' | |
| - '**/*.html' | |
| - '.github/copilot-instructions.md' | |
| - 'PROJECT-STATE.md' | |
| - 'README.md' | |
| - 'AGENT.md' | |
| - 'AGENTS.md' | |
| schedule: | |
| - cron: "0 3 * * 1" # Weekly, Mondays at 03:00 UTC | |
| jobs: | |
| lint-docs: | |
| name: Lint AI Docs for Forbidden Patterns | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v4 | |
| - name: Lint for forbidden patterns | |
| run: | | |
| # Enforce D7460N/DHCP doc architecture: no classes, IDs, data-*, <button>, event listeners, or inline scripts/styles | |
| BAD_PATTERNS='class=|id=|data-|<button|addEventListener|on(click|focus|blur|keydown|keyup|mousedown|mouseup|mouseenter|mouseleave|touchstart|touchend|touchmove)|style=' | |
| DOCS="$(find . -type f -iname 'README.md' -o -name 'PROJECT-STATE.md' -o -name 'AGENT.md' -o -name 'AGENTS.md' -o -path './.github/copilot-instructions.md')" | |
| set +e | |
| grep -nE "$BAD_PATTERNS" $DOCS | |
| STATUS=$? | |
| set -e | |
| if [ $STATUS -eq 0 ]; then | |
| echo "❌ Forbidden pattern found in docs. See lint output above." >&2 | |
| exit 1 | |
| else | |
| echo "✅ Docs lint clean." | |
| fi | |
| doc-drift: | |
| name: Detect Doc Drift (Architecture/AI Context) | |
| runs-on: ubuntu-latest | |
| permissions: | |
| contents: read | |
| steps: | |
| - uses: actions/checkout@v4 | |
| - name: Check for doc drift | |
| run: | | |
| # Patterns that define the architecture (expand as needed) | |
| PATTERNS='input type="checkbox"|:has\(|@container|fieldset|aria-label|role="button"|Holy Grail|progressive enhancement|toTagName\(\)|aria-disabled|:empty|:valid' | |
| CODE_PATTERNS=$(grep -Ero "$PATTERNS" . --include=*.html --include=*.css --include=*.js | sed 's/.*://g' | sort | uniq) | |
| DOC_PATTERNS=$(grep -Ero "$PATTERNS" README.md PROJECT-STATE.md .github/copilot-instructions.md AGENT.md AGENTS.md | sed 's/.*://g' | sort | uniq) | |
| MISSING_DOCS="" | |
| for pat in $CODE_PATTERNS; do | |
| echo "$DOC_PATTERNS" | grep -qF "$pat" || MISSING_DOCS="$MISSING_DOCS $pat" | |
| done | |
| if [ -n "$MISSING_DOCS" ]; then | |
| echo "❌ Architectural patterns present in code but not in docs:" | |
| echo "$MISSING_DOCS" | |
| exit 1 | |
| else | |
| echo "✅ No doc drift detected." | |
| fi | |
| notify-on-failure: | |
| name: Notify on Failure | |
| needs: [lint-docs, doc-drift] | |
| runs-on: ubuntu-latest | |
| if: failure() | |
| permissions: | |
| issues: write | |
| contents: none | |
| pull-requests: none | |
| steps: | |
| - name: Create Issue for Drift/Lint Failure | |
| uses: dacbd/create-issue-action@v1 | |
| with: | |
| title: "AI Doc Consistency/Lint Failure" | |
| token: ${{ secrets.GITHUB_TOKEN }} | |
| body: | | |
| One or more AI documentation files have failed lint or drift detection. | |
| **Action Required:** | |
| - Align `.github/copilot-instructions.md`, `PROJECT-STATE.md`, `README.md`, `AGENT.md`, and `AGENTS.md` with current repo architecture (HTML, CSS, JS patterns). | |
| - Remove forbidden patterns (classes, IDs, data-*, <button>, event listeners, inline styles/scripts, etc). | |
| - Document all new or modified architecture patterns. | |
| - Review and re-run workflow before merging. | |
| # Reference: | |
| # - https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox | |
| # - https://developer.mozilla.org/en-US/docs/Web/CSS/:has | |
| # - https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/button_role | |
| # - https://html.spec.whatwg.org/ |