doclify-guardrail 1.0.0

package/src/report.mjs

@@ -0,0 +1,83 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Generate a markdown report from scan results and write it to disk.
+ * @param {object} output - full output object with files[], summary
+ * @param {object} options - { reportPath: string }
+ * @returns {string} - resolved path of written report
+ */
+function generateReport(output, options) {
+  const lines = [];
+  const now = new Date();
+  const dateStr = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')} ${String(now.getHours()).padStart(2, '0')}:${String(now.getMinutes()).padStart(2, '0')}`;
+
+  lines.push('# Doclify Guardrail Report');
+  lines.push('');
+  lines.push(`**Date:** ${dateStr}  `);
+  lines.push(`**Files scanned:** ${output.summary.filesScanned}  `);
+  lines.push(`**Result:** ${output.summary.status === 'PASS' ? '\u2713 PASS' : `\u2717 ${output.summary.totalErrors} errors, ${output.summary.totalWarnings} warnings`}`);
+  if (typeof output.summary.avgHealthScore === 'number') {
+    lines.push(`**Avg health score:** ${output.summary.avgHealthScore}/100`);
+  }
+  lines.push('');
+
+  // Summary table
+  lines.push('## Summary');
+  lines.push('');
+  lines.push('| File | Status | Errors | Warnings |');
+  lines.push('|------|--------|--------|----------|');
+
+  for (const f of output.files) {
+    const icon = f.pass ? '\u2713 PASS' : '\u2717 FAIL';
+    lines.push(`| ${f.file} | ${icon} | ${f.summary.errors} | ${f.summary.warnings} |`);
+  }
+  lines.push('');
+
+  // Details per file
+  const filesWithFindings = output.files.filter(
+    f => f.findings.errors.length > 0 || f.findings.warnings.length > 0
+  );
+
+  if (filesWithFindings.length > 0) {
+    lines.push('## Details');
+    lines.push('');
+
+    for (const f of filesWithFindings) {
+      lines.push(`### ${f.file}`);
+      lines.push('');
+
+      for (const finding of f.findings.errors) {
+        const lineRef = finding.line != null ? `line ${finding.line}` : '';
+        lines.push(`- **ERROR** ${lineRef}: ${finding.message}`);
+      }
+      for (const finding of f.findings.warnings) {
+        const lineRef = finding.line != null ? `line ${finding.line}` : '';
+        lines.push(`- **WARNING** ${lineRef}: ${finding.message}`);
+      }
+      lines.push('');
+    }
+  }
+
+  // File errors
+  if (output.fileErrors && output.fileErrors.length > 0) {
+    lines.push('## Unreadable Files');
+    lines.push('');
+    for (const fe of output.fileErrors) {
+      lines.push(`- \`${fe.file}\`: ${fe.error}`);
+    }
+    lines.push('');
+  }
+
+  // Footer
+  lines.push('---');
+  lines.push(`*Generated by Doclify Guardrail v${output.version} in ${output.summary.elapsed}s*`);
+  lines.push('');
+
+  const reportContent = lines.join('\n');
+  const resolvedPath = path.resolve(options.reportPath);
+  fs.writeFileSync(resolvedPath, reportContent, 'utf8');
+  return resolvedPath;
+}
+
+export { generateReport };

package/src/rules-loader.mjs

@@ -0,0 +1,61 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Load and validate custom rules from a JSON file.
+ * @param {string} rulesPath - path to JSON rules file
+ * @returns {Array} - validated rules with compiled RegExp
+ */
+function loadCustomRules(rulesPath) {
+  const resolved = path.resolve(rulesPath);
+
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`Rules file not found: ${resolved}`);
+  }
+
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(resolved, 'utf8'));
+  } catch (err) {
+    throw new Error(`Invalid JSON in rules file (${resolved}): ${err.message}`);
+  }
+
+  if (!raw || !Array.isArray(raw.rules)) {
+    throw new Error(`Rules file must contain { "rules": [...] }`);
+  }
+
+  return raw.rules.map((rule, index) => validateCustomRule(rule, index));
+}
+
+function validateCustomRule(rule, index) {
+  if (!rule.id || typeof rule.id !== 'string') {
+    throw new Error(`Rule at index ${index}: missing or invalid "id"`);
+  }
+  if (!rule.pattern || typeof rule.pattern !== 'string') {
+    throw new Error(`Rule "${rule.id}": missing or invalid "pattern"`);
+  }
+  if (!rule.message || typeof rule.message !== 'string') {
+    throw new Error(`Rule "${rule.id}": missing or invalid "message"`);
+  }
+
+  const severity = rule.severity || 'warning';
+  if (severity !== 'error' && severity !== 'warning') {
+    throw new Error(`Rule "${rule.id}": severity must be "error" or "warning"`);
+  }
+
+  let compiledRegex;
+  try {
+    compiledRegex = new RegExp(rule.pattern, rule.flags || 'gi');
+  } catch (err) {
+    throw new Error(`Rule "${rule.id}": invalid regex pattern: ${err.message}`);
+  }
+
+  return {
+    id: rule.id,
+    severity,
+    pattern: compiledRegex,
+    message: rule.message
+  };
+}
+
+export { loadCustomRules };