Skip to content
darkzOGxPublic

About

No description, website, or topics provided.

Resources

Stars

14 stars

Watchers

0 watching

Forks

Repository files navigation

DarkzSEO

┌─────────────────────────────────────────────────────────────────┐
│██████╗  █████╗ ██████╗ ██╗  ██╗███████╗███████╗███████╗ ██████╗ │
│██╔══██╗██╔══██╗██╔══██╗██║ ██╔╝╚══███╔╝██╔════╝██╔════╝██╔═══██╗│
│██║  ██║███████║██████╔╝█████╔╝   ███╔╝ ███████╗█████╗  ██║   ██║│
│██║  ██║██╔══██║██╔══██╗██╔═██╗  ███╔╝  ╚════██║██╔══╝  ██║   ██║│
│██████╔╝██║  ██║██║  ██║██║  ██╗███████╗███████║███████╗╚██████╔╝│
│╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝ ╚═════╝ │
├─────────────────────────────────────────────────────────────────┤
│  Static Codebase Auditor for 2026 Search Standards             │
│  SEO · GEO · AIO · AEO — 16 Checks, Zero APIs, Pure Analysis   │
└─────────────────────────────────────────────────────────────────┘

A lightweight, local-only Python library and CLI for auditing sites and content packages against 2026 Search Standards. No external APIs required.

What's new in v1.4.0

  • Versioned machine contract: run site or content audits through Python or clean JSON stdin/stdout with stable rule IDs and schema version 1.0.
  • Content-package audits: evaluate platform-ready titles, descriptions, transcripts, sections, brands, and verified sources without scanning private application dashboards.
  • Integration controls: use --output, --quiet, --exclude, and --fail-on for local tools, CI, and advisory agent workflows.
  • Windows reliability: machine mode suppresses the Unicode banner, while normal console output now handles Windows encoding safely.
  • Release safety: automated Linux/Windows tests, verified source/wheel builds, corrected project metadata, and an explicit MIT license.

Features

  • 16 Automated Checks across 4 categories
  • Zero API Dependencies - runs entirely offline
  • Color-Coded Console Output for quick severity identification
  • JSON Report Export for CI/CD integration
  • Versioned Machine API over Python or clean JSON stdin/stdout
  • Site and Content Modes for HTML codebases or platform-ready media metadata
  • Template Agnostic - works with HTML, JSX, Vue, Svelte, Astro, PHP, EJS, and more

Installation

pip install -r requirements.txt

Usage

# Basic scan
python darkzseo.py --path ./src

# With brand name (for entity salience check)
python darkzseo.py --path ./public --brand "MyCompany"

# Custom output file
python darkzseo.py --path ./templates --output results.json

# Quiet mode (report files only)
python darkzseo.py --path ./src --quiet

# Machine-readable content audit (no report files or banner)
echo '{"id":"video-1","platform":"youtube","brand":"MyCompany","title":"MyCompany guide","description":"Useful summary","transcript":"..."}' | python darkzseo.py --mode content --input-json - --json-stdout --no-html --fail-on none

# Ignore private/admin paths and fail only on critical findings
python darkzseo.py --path ./src --exclude admin --exclude "*.fixture.html" --fail-on critical

Python API

from darkzseo import audit_content, audit_path

site_report = audit_path('./public', brand='MyCompany', excludes=['admin'])
content_report = audit_content({
    'id': 'video-1',
    'platform': 'youtube',
    'brand': 'MyCompany',
    'title': 'MyCompany guide',
    'description': 'A useful summary.',
    'transcript': 'The complete transcript.',
    'sections': [{'title': 'What does it do?', 'content': 'A concise answer.'}],
    'sources': [{'url': 'https://example.gov/source'}]
})

Audit Categories

🟢 SEO (Technical Health)

Check What it Detects
Orphan Pages Files that exist but are never linked to
Resource Hints External scripts missing preconnect/dns-prefetch
CLS Risk Images/videos/iframes missing width/height
Render Budget @import rules and expensive * selectors

🟣 GEO (Generative Engine Optimization)

Check What it Detects
Trust Network Long content lacking authority links (.gov, .edu, etc.)
Entity Salience Brand not in H1 or first 200 words
Data Density Low table/list ratio on content pages
Freshness Missing or stale dateModified

🔵 AIO (AI Overviews)

Check What it Detects
Comparison Gap "vs"/"best" in title without comparison table
Direct Answer Question headers not followed by concise paragraphs
Video Schema Video content missing VideoObject JSON-LD
Skimmability Paragraphs exceeding 150 words

🔷 AEO (Answer Engine Optimization)

Check What it Detects
Simplicity Score Complex vocabulary (Flesch-Kincaid proxy)
QA Proximity Elements interrupting question-answer flow
Speakable Schema Missing Speakable markup on Q&A content
Unit Clarity Bare units without <abbr> tags

Output

Console

Color-coded findings grouped by category and severity:

  • 🔴 CRITICAL/HIGH - Must fix for search visibility
  • 🟡 MEDIUM - Recommended improvements
  • 🔵 LOW/INFO - Nice to have optimizations

JSON Report

{
  "schemaVersion": "1.0",
  "engine": { "name": "darkzseo", "version": "1.4.0" },
  "mode": "content",
  "target": "video-1",
  "status": "advisory",
  "generatedAt": "2026-01-20T20:00:00",
  "itemsScanned": 1,
  "totalFindings": 1,
  "summary": {
    "severity": { "CRITICAL": 0, "HIGH": 0, "MEDIUM": 1, "LOW": 0, "INFO": 0 },
    "category": { "SEO": 0, "GEO": 1, "AIO": 0, "AEO": 0 }
  },
  "findings": [
    {
      "ruleId": "geo.entity_salience",
      "category": "GEO",
      "severity": "MEDIUM",
      "file": "video-1",
      "message": "Entity Salience: Brand missing from title/intro",
      "applicability": ["youtube", "content"]
    }
  ]
}

CI/CD Integration

DarkzSEO returns exit code 1 if any HIGH or CRITICAL findings are detected by default. Use --fail-on to choose a different threshold or --fail-on none for advisory integrations:

# GitHub Actions example
- name: SEO Audit
  run: python darkzseo.py --path ./public --quiet

License

MIT

About

No description, website, or topics provided.

Resources

Stars

14 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages