doclify-guardrail 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lorenzo Borgato
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,250 @@
+# Doclify Guardrail
+
+**Quality gate for your Markdown docs. Catches errors in seconds.**
+
+Zero dependencies. Node.js built-in only. Works everywhere Node 20+ runs.
+
+## Features
+
+- Multi-file and directory scanning with glob support
+- Line numbers in every finding
+- Code block exclusion (no false positives on code examples)
+- Markdown report generation for CI
+- Custom regex-based rules via JSON
+- Colored terminal output
+- Extended placeholder detection (TODO, FIXME, TBD, WIP, and more)
+- Insecure link detection (inline, bare URLs, reference-style)
+- Doc Health Score per file and project average (0–100)
+- Optional dead link checker (`--check-links`)
+- Optional freshness checker (`--check-freshness`)
+- CI-ready output exports (`--junit`, `--sarif`)
+- Local docs health badge generation (`--badge`, `--badge-label`)
+- Optional safe auto-fix mode (`--fix`, `--dry-run`)
+
+## Quick Start
+
+```bash
+# Scan a single file
+npx doclify-guardrail README.md
+
+# Scan an entire directory
+npx doclify-guardrail docs/
+
+# Strict mode (warnings = failure)
+npx doclify-guardrail docs/ --strict
+
+# Generate a report
+npx doclify-guardrail docs/ --report
+
+# Check dead links (HTTP status + local relative paths)
+npx doclify-guardrail docs/ --check-links
+
+# Check document freshness (warn if stale or missing updated date)
+npx doclify-guardrail docs/ --check-freshness
+
+# Export CI reports
+npx doclify-guardrail docs/ --junit --sarif
+
+# Generate local badge SVG
+npx doclify-guardrail docs/ --badge --badge-label "docs health"
+
+# Auto-fix safe issues (v1: http:// -> https://)
+npx doclify-guardrail docs/ --fix
+
+# Preview auto-fix without writing files
+npx doclify-guardrail docs/ --fix --dry-run
+```
+
+## Usage
+
+```
+doclify-guardrail <file.md ...> [options]
+doclify-guardrail --dir <path> [options]
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--strict` | Treat warnings as failures |
+| `--max-line-length <n>` | Maximum line length (default: 160) |
+| `--config <path>` | Config file path (default: `.doclify-guardrail.json`) |
+| `--dir <path>` | Scan all `.md` files in directory (recursive) |
+| `--report [path]` | Generate markdown report (default: `doclify-report.md`) |
+| `--rules <path>` | Load custom rules from JSON file |
+| `--check-links` | Validate links and fail on dead links |
+| `--check-freshness` | Warn if docs are stale or missing an updated date (default max age: 180 days) |
+| `--junit [path]` | Export JUnit XML report (default: `doclify-junit.xml`) |
+| `--sarif [path]` | Export SARIF report (default: `doclify.sarif`) |
+| `--badge [path]` | Generate SVG docs health badge (default: `doclify-badge.svg`) |
+| `--badge-label <text>` | Custom label used in the generated badge |
+| `--fix` | Auto-fix safe issues (v1: `http://` to `https://`) |
+| `--dry-run` | Preview `--fix` changes without writing files (only valid with `--fix`) |
+| `--no-color` | Disable colored output |
+| `--debug` | Show runtime details |
+| `-h, --help` | Show help |
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | PASS -- all files clean |
+| `1` | FAIL -- errors found, or warnings in strict mode |
+| `2` | Usage error / invalid input |
+
+## Configuration
+
+Create a `.doclify-guardrail.json` in your project root:
+
+```json
+{
+  "maxLineLength": 120,
+  "strict": true
+}
+```
+
+CLI flags override config file values.
+
+## Built-in Rules
+
+| Rule | Severity | Description |
+|------|----------|-------------|
+| `frontmatter` | warning | Missing YAML frontmatter block |
+| `single-h1` | error | Zero or multiple H1 headings |
+| `line-length` | warning | Lines exceeding max length |
+| `placeholder` | warning | TODO, FIXME, TBD, WIP, HACK, CHANGEME, lorem ipsum, etc. |
+| `insecure-link` | warning | HTTP links (should be HTTPS) |
+| `dead-link` | error | Broken links (enabled with `--check-links`) |
+| `stale-doc` | warning | Missing/old freshness date (enabled with `--check-freshness`) |
+
+All rules respect code block exclusion -- content inside fenced code blocks
+and inline code is never flagged.
+
+## Custom Rules
+
+Create a JSON file with custom regex-based rules:
+
+```json
+{
+  "rules": [
+    {
+      "id": "no-internal-urls",
+      "severity": "error",
+      "pattern": "https://internal\\.company\\.com",
+      "message": "Internal URL found -- remove before publishing"
+    },
+    {
+      "id": "no-draft-marker",
+      "severity": "warning",
+      "pattern": "\\[DRAFT\\]",
+      "message": "Draft marker found in document"
+    }
+  ]
+}
+```
+
+```bash
+doclify-guardrail docs/ --rules my-rules.json
+```
+
+Custom rules are applied after built-in rules and respect code block exclusion.
+
+## CI Integration
+
+### GitHub Actions
+
+```yaml
+- name: Docs quality gate
+  run: npx doclify-guardrail docs/ --strict --report
+```
+
+See `.github/workflows/docs-check.yml` for a complete example workflow.
+
+### JSON Output
+
+Pipe JSON output to other tools:
+
+```bash
+doclify-guardrail docs/ 2>/dev/null | jq '.summary'
+```
+
+## Dead Link Checker
+
+Use `--check-links` to validate:
+- `http(s)` links via HTTP status checks
+- relative local file links (e.g. `./guide.md`)
+
+When dead links are found, they are reported as `dead-link` errors.
+
+## CI Outputs
+
+Use CI export flags for native pipeline integrations:
+
+```bash
+doclify-guardrail docs/ --junit --sarif
+```
+
+- `--junit` writes XML test output (useful for generic CI test dashboards)
+- `--sarif` writes SARIF v2.1.0 (GitHub code scanning compatible)
+
+## Badge SVG
+
+Generate a local SVG badge from the current scan score:
+
+```bash
+doclify-guardrail docs/ --badge --badge-label "docs health"
+```
+
+The value is computed from findings severity and can be embedded in your README.
+
+## Auto-fix (safe v1)
+
+Use `--fix` to automatically upgrade safe `http://` links to `https://`.
+Ambiguous URLs (for example `localhost` or custom ports) are reported and left unchanged.
+
+Use `--dry-run` only together with `--fix` to preview changes without writing files.
+Using `--dry-run` alone is a usage error (exit code `2`).
+
+## Doc Health Score
+
+Each file now includes `summary.healthScore` (0–100) in JSON output.
+Overall summary includes `summary.avgHealthScore`.
+
+Scoring is deterministic and compatibility-safe:
+- starts at `100`
+- `-25` per error
+- `-8` per warning
+- clamped to `0..100`
+
+## Doc Freshness
+
+Use `--check-freshness` to detect stale docs.
+The checker looks for dates in:
+- frontmatter keys: `updated`, `last_updated`, `lastModified`, `date`
+- body marker: `Last updated: YYYY-MM-DD`
+
+If no date is found or the doc is older than 180 days, a `stale-doc` warning is added.
+
+## Report
+
+Use `--report` to generate a markdown report:
+
+```bash
+doclify-guardrail docs/ --report quality-report.md
+```
+
+The report includes a summary table, per-file details with line numbers,
+and execution metadata.
+
+## License
+
+MIT
+
+---
+
+## Italiano
+
+Doclify Guardrail e' un quality gate per la documentazione Markdown.
+Zero dipendenze esterne, funziona ovunque giri Node.js 20+.
+Rileva errori, placeholder dimenticati, link insicuri e problemi di
+formattazione con numeri di riga precisi e report in formato Markdown.

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "doclify-guardrail",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Quality gate for your Markdown docs. Zero dependencies, catches errors in seconds.",
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "bin": {
+    "doclify-guardrail": "./src/index.mjs"
+  },
+  "scripts": {
+    "start": "node ./src/index.mjs",
+    "test": "node --test",
+    "demo": "bash ./scripts/demo.sh"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "keywords": [
+    "markdown",
+    "lint",
+    "documentation",
+    "quality",
+    "guardrail",
+    "cli"
+  ]
+}

package/src/checker.mjs

@@ -0,0 +1,206 @@
+const DEFAULTS = {
+  maxLineLength: 160,
+  strict: false
+};
+
+const RULE_SEVERITY = {
+  frontmatter: 'warning',
+  'single-h1': 'error',
+  'line-length': 'warning',
+  placeholder: 'warning',
+  'insecure-link': 'warning',
+  'dead-link': 'error',
+  'stale-doc': 'warning'
+};
+
+const PLACEHOLDER_PATTERNS = [
+  { rx: /\bTODO\b/i,           msg: 'TODO marker found — remove before publishing' },
+  { rx: /\bFIXME\b/i,          msg: 'FIXME marker found — remove before publishing' },
+  { rx: /\bHACK\b/i,           msg: 'HACK marker found — remove before publishing' },
+  { rx: /\bTBD\b/i,            msg: 'TBD (to be determined) marker found' },
+  { rx: /\bWIP\b/i,            msg: 'WIP (work in progress) marker found' },
+  { rx: /\bCHANGEME\b/i,       msg: 'CHANGEME marker found — update before publishing' },
+  { rx: /\bPLACEHOLDER\b/i,    msg: 'PLACEHOLDER marker found — replace with actual content' },
+  { rx: /\[insert\s+here\]/i,  msg: '"[insert here]" placeholder found' },
+  { rx: /lorem ipsum/i,        msg: 'Lorem ipsum placeholder text found' },
+  { rx: /\bxxx\b/i,            msg: '"xxx" placeholder found' }
+];
+
+function normalizeFinding(rule, message, line, source) {
+  const finding = {
+    code: rule,
+    severity: RULE_SEVERITY[rule] || 'warning',
+    message
+  };
+  if (line != null) finding.line = line;
+  if (source != null) finding.source = source;
+  return finding;
+}
+
+/**
+ * Replace content inside fenced code blocks with empty lines.
+ * Preserves line count so line numbers remain accurate.
+ */
+function stripCodeBlocks(content) {
+  const lines = content.split('\n');
+  const result = [];
+  let inCodeBlock = false;
+  let fenceChar = null;
+  let fenceLen = 0;
+
+  for (const line of lines) {
+    if (!inCodeBlock) {
+      const fenceMatch = line.match(/^(`{3,}|~{3,})/);
+      if (fenceMatch) {
+        inCodeBlock = true;
+        fenceChar = fenceMatch[1][0];
+        fenceLen = fenceMatch[1].length;
+        result.push('');
+      } else {
+        result.push(line);
+      }
+    } else {
+      const closeMatch = line.match(/^(`{3,}|~{3,})\s*$/);
+      if (closeMatch && closeMatch[1][0] === fenceChar && closeMatch[1].length >= fenceLen) {
+        inCodeBlock = false;
+        fenceChar = null;
+        fenceLen = 0;
+      }
+      result.push('');
+    }
+  }
+
+  return result.join('\n');
+}
+
+/**
+ * Strip inline code from a single line for rule matching.
+ */
+function stripInlineCode(line) {
+  return line.replace(/`[^`]+`/g, '');
+}
+
+function checkMarkdown(rawContent, opts = {}) {
+  const maxLineLength = Number(opts.maxLineLength ?? DEFAULTS.maxLineLength);
+  const filePath = opts.filePath || undefined;
+  const errors = [];
+  const warnings = [];
+
+  // Strip code blocks for semantic rules
+  const content = stripCodeBlocks(rawContent);
+  const lines = content.split('\n');
+  const rawLines = rawContent.split('\n');
+
+  // Rule: frontmatter
+  if (!rawContent.startsWith('---\n')) {
+    warnings.push(normalizeFinding('frontmatter', 'Missing frontmatter block at the beginning of the file.', 1, filePath));
+  }
+
+  // Rule: single-h1
+  const h1Lines = [];
+  lines.forEach((line, idx) => {
+    if (/^#\s/.test(line)) {
+      h1Lines.push(idx + 1);
+    }
+  });
+
+  if (h1Lines.length === 0) {
+    errors.push(normalizeFinding('single-h1', 'Missing H1 heading.', 1, filePath));
+  } else if (h1Lines.length > 1) {
+    const lineList = h1Lines.join(', ');
+    for (const lineNum of h1Lines) {
+      errors.push(normalizeFinding(
+        'single-h1',
+        `Found ${h1Lines.length} H1 headings (expected 1) at lines ${lineList}.`,
+        lineNum,
+        filePath
+      ));
+    }
+  }
+
+  // Rule: line-length (uses raw content — code block lines can still be too long)
+  rawLines.forEach((line, idx) => {
+    if (line.length > maxLineLength) {
+      warnings.push(
+        normalizeFinding(
+          'line-length',
+          `Line exceeds ${maxLineLength} characters (${line.length}).`,
+          idx + 1,
+          filePath
+        )
+      );
+    }
+  });
+
+  // Rule: placeholder (uses stripped content)
+  lines.forEach((line, idx) => {
+    const cleanLine = stripInlineCode(line);
+    for (const { rx, msg } of PLACEHOLDER_PATTERNS) {
+      if (rx.test(cleanLine)) {
+        warnings.push(normalizeFinding('placeholder', msg, idx + 1, filePath));
+      }
+    }
+  });
+
+  // Rule: insecure-link (uses stripped content)
+  lines.forEach((line, idx) => {
+    const cleanLine = stripInlineCode(line);
+
+    // Inline markdown links: [text](http://...)
+    const inlineMatches = cleanLine.match(/\[.*?\]\(http:\/\/[^)]+\)/g);
+    if (inlineMatches) {
+      for (const match of inlineMatches) {
+        const url = match.match(/\((http:\/\/[^)]+)\)/)?.[1] || '';
+        warnings.push(
+          normalizeFinding('insecure-link', `Insecure link found: ${url} — use https:// instead`, idx + 1, filePath)
+        );
+      }
+    }
+
+    // Reference-style link definitions: [label]: http://...
+    const refMatch = cleanLine.match(/^\[.*?\]:\s*(http:\/\/\S+)/);
+    if (refMatch) {
+      warnings.push(
+        normalizeFinding('insecure-link', `Insecure link found: ${refMatch[1]} — use https:// instead`, idx + 1, filePath)
+      );
+    }
+
+    // Bare URLs: http://... (not inside markdown link syntax)
+    // Only check if no inline links were found on this line to avoid duplicates
+    if (!inlineMatches && !refMatch) {
+      const bareMatch = cleanLine.match(/\bhttp:\/\/\S+/g);
+      if (bareMatch) {
+        for (const url of bareMatch) {
+          warnings.push(
+            normalizeFinding('insecure-link', `Insecure link found: ${url} — use https:// instead`, idx + 1, filePath)
+          );
+        }
+      }
+    }
+  });
+
+  // Custom rules (uses stripped content)
+  if (opts.customRules && opts.customRules.length > 0) {
+    lines.forEach((line, idx) => {
+      const cleanLine = stripInlineCode(line);
+      for (const rule of opts.customRules) {
+        rule.pattern.lastIndex = 0;
+        if (rule.pattern.test(cleanLine)) {
+          const bucket = rule.severity === 'error' ? errors : warnings;
+          bucket.push(normalizeFinding(rule.id, rule.message, idx + 1, filePath));
+        }
+      }
+    });
+  }
+
+  return {
+    errors,
+    warnings,
+    summary: {
+      errors: errors.length,
+      warnings: warnings.length
+    }
+  };
+}
+
+export { DEFAULTS, RULE_SEVERITY, normalizeFinding, checkMarkdown, stripCodeBlocks, stripInlineCode };