@buresmi7/agent-doc-rules-docs-validator 0.8.2

package/README.md

@@ -0,0 +1,74 @@
+# Docs Validator
+
+`@buresmi7/agent-doc-rules-docs-validator` provides deterministic Markdown validation
+for repositories that use the `agent-doc-rules` skill.
+
+## Install
+
+```bash
+pnpm add -D @buresmi7/agent-doc-rules-docs-validator
+```
+
+## Commands
+
+```bash
+agent-doc-rules-docs init
+agent-doc-rules-docs markdown
+agent-doc-rules-docs wording
+agent-doc-rules-docs security
+agent-doc-rules-docs links
+agent-doc-rules-docs check
+```
+
+`init` creates a starter `agent-doc-rules.config.json`. Use
+`agent-doc-rules-docs init --print` to preview the config without writing files.
+
+`markdown`, `wording`, `security`, and `links` run the corresponding
+deterministic phases. `check` runs them in that order and stops on the first
+failure. For security-review scope, see
+[`security-review.md`](../agent-doc-rules-skill/references/security-review.md).
+
+## Config
+
+The CLI reads `agent-doc-rules.config.json` from the repository root. CLI flags
+override config values, and config values override built-in defaults.
+
+```json
+{
+  "docs": {
+    "include": ["*.md", "docs/**/*.md", "packages/**/*.md"],
+    "exclude": ["node_modules/**", ".git/**"],
+    "links": {
+      "skip": ["^https://github.com/example/archived"]
+    },
+    "wording": {
+      "writeGood": {
+        "passive": false,
+        "illusion": false,
+        "weasel": false,
+        "adverb": false,
+        "tooWordy": false,
+        "eprime": false,
+        "fail": false
+      },
+      "forbiddenTerms": [],
+      "allow": ["intentional example"]
+    },
+    "security": {
+      "allow": ["intentional fixture"]
+    }
+  }
+}
+```
+
+Use `--skip <regex>` for repeated Linkinator skip patterns and `--no-fragments`
+when fragment validation is too strict for a specific repository. Use
+`docs.wording.writeGood` to tune the deterministic prose linter. Use
+`docs.wording.forbiddenTerms` only for project-specific phrases that must fail.
+
+AI sentence-level style review lives in
+`@buresmi7/agent-doc-rules-docs-duplicates` as
+`agent-doc-rules-docs-duplicates style`.
+
+See the skill package [Config Reference](../agent-doc-rules-skill/docs/config-reference.md)
+for the full config model.

package/bin/agent-doc-rules-docs.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { main } from '../src/cli.mjs';
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error(error.stack ?? error.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@buresmi7/agent-doc-rules-docs-validator",
+  "version": "0.8.2",
+  "private": false,
+  "description": "Markdown, security, and link validation CLI for agent-doc-rules projects",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "agent-doc-rules-docs": "bin/agent-doc-rules-docs.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "fast-glob": "^3.3.3",
+    "linkinator": "^7.6.1",
+    "markdownlint-cli2": "^0.22.1",
+    "write-good": "^1.0.8"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,148 @@
+import { resolveDocsOptions } from './config.mjs';
+import { runInit } from './init.mjs';
+import { runCheck, runLinks, runMarkdown, runSecurity, runWording } from './runner.mjs';
+
+const commands = new Set(['init', 'markdown', 'wording', 'security', 'links', 'check']);
+
+export async function main(argv = process.argv.slice(2)) {
+  const parsed = parseArgs(argv);
+
+  if (parsed.help) {
+    console.log(usage());
+    return;
+  }
+
+  const options = parsed.command === 'init'
+    ? parsed
+    : parsed.command === 'check'
+    ? {
+        markdownOptions: await resolveDocsOptions({ ...parsed, command: 'markdown' }),
+        wordingOptions: await resolveDocsOptions({ ...parsed, command: 'wording' }),
+        securityOptions: await resolveDocsOptions({ ...parsed, command: 'security' }),
+        linksOptions: await resolveDocsOptions({ ...parsed, command: 'links' }),
+      }
+    : await resolveDocsOptions(parsed);
+  const code = await runCommand(parsed.command, options);
+
+  if (code !== 0) {
+    process.exitCode = code;
+  }
+}
+
+export async function runCommand(command, options, deps = {}) {
+  if (command === 'init') {
+    return runInit(options, deps);
+  }
+
+  if (command === 'markdown') {
+    return runMarkdown(options, deps);
+  }
+
+  if (command === 'wording') {
+    return runWording(options, deps);
+  }
+
+  if (command === 'links') {
+    return runLinks(options, deps);
+  }
+
+  if (command === 'security') {
+    return runSecurity(options, deps);
+  }
+
+  if (command === 'check') {
+    return runCheck(options, deps);
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+export function parseArgs(argv) {
+  const [maybeCommand, ...rest] = argv;
+
+  if (!maybeCommand || maybeCommand === '--help' || maybeCommand === '-h') {
+    return { command: 'check', help: true };
+  }
+
+  if (!commands.has(maybeCommand)) {
+    throw new Error(`Unknown command: ${maybeCommand}`);
+  }
+
+  const parsed = {
+    command: maybeCommand,
+    include: [],
+    exclude: [],
+    skip: [],
+    forbiddenTerms: [],
+    allow: [],
+    checkFragments: undefined,
+    force: false,
+    print: false,
+  };
+
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+
+    if (arg === '--root') {
+      parsed.root = readValue(rest, ++index, arg);
+    } else if (arg === '--include') {
+      parsed.include.push(readValue(rest, ++index, arg));
+    } else if (arg === '--exclude') {
+      parsed.exclude.push(readValue(rest, ++index, arg));
+    } else if (arg === '--config') {
+      parsed.configPath = readValue(rest, ++index, arg);
+    } else if (arg === '--skip') {
+      parsed.skip.push(readValue(rest, ++index, arg));
+    } else if (arg === '--forbid') {
+      parsed.forbiddenTerms.push(readValue(rest, ++index, arg));
+    } else if (arg === '--allow') {
+      parsed.allow.push(readValue(rest, ++index, arg));
+    } else if (arg === '--no-fragments') {
+      parsed.checkFragments = false;
+    } else if (arg === '--force') {
+      parsed.force = true;
+    } else if (arg === '--print') {
+      parsed.print = true;
+    } else if (arg === '--help' || arg === '-h') {
+      parsed.help = true;
+    } else {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+
+  return parsed;
+}
+
+function readValue(args, index, option) {
+  const value = args[index];
+
+  if (!value || value.startsWith('--')) {
+    throw new Error(`Missing value for ${option}`);
+  }
+
+  return value;
+}
+
+function usage() {
+  return `Usage: agent-doc-rules-docs <command> [options]
+
+Commands:
+  init          Write a starter agent-doc-rules.config.json.
+  markdown      Run Markdown linting.
+  wording       Run deterministic prose wording checks.
+  security      Run deterministic documentation security checks.
+  links         Run Markdown link validation.
+  check         Run Markdown linting, wording, security, then link validation.
+
+Options:
+  --root <dir>          Repository root. Defaults to the current directory.
+  --include <glob>      Include Markdown glob. Repeatable.
+  --exclude <glob>      Exclude glob. Repeatable.
+  --config <path>       Config file. Defaults to agent-doc-rules.config.json.
+  --skip <regex>        Linkinator skip pattern. Repeatable.
+  --forbid <term>       Project-specific term that should fail. Repeatable.
+  --allow <regex>       Wording or security allow pattern for matching lines. Repeatable.
+  --no-fragments        Do not ask Linkinator to check fragments.
+  --print               Print the starter config without writing files.
+  --force               Overwrite an existing config during init.`;
+}

package/src/config.mjs

@@ -0,0 +1,80 @@
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, resolve } from 'node:path';
+import { defaultConfigFile, defaultExclude, defaultInclude } from './defaults.mjs';
+
+export async function loadDocsConfig({ root = process.cwd(), configPath } = {}) {
+  const resolvedRoot = resolve(root);
+  const resolvedConfigPath = configPath
+    ? resolvePath(resolvedRoot, configPath)
+    : resolve(resolvedRoot, defaultConfigFile);
+
+  try {
+    const raw = await readFile(resolvedConfigPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed.docs ?? parsed;
+  } catch (error) {
+    if (error.code === 'ENOENT' && !configPath) {
+      return {};
+    }
+
+    throw error;
+  }
+}
+
+export async function resolveDocsOptions({
+  command = 'markdown',
+  root = process.cwd(),
+  configPath,
+  include = [],
+  exclude = [],
+  skip = [],
+  checkFragments,
+  forbiddenTerms = [],
+  allow = [],
+  writeGood,
+} = {}) {
+  const resolvedRoot = resolve(root);
+  const config = await loadDocsConfig({ root: resolvedRoot, configPath });
+  const commandConfig = config[command] ?? {};
+  const linkConfig = command === 'links' ? (config.links ?? {}) : {};
+  const wordingConfig = command === 'wording' ? (config.wording ?? {}) : {};
+
+  return {
+    root: resolvedRoot,
+    include: chooseArray(include, commandConfig.include, config.include, defaultInclude),
+    exclude: chooseArray(exclude, commandConfig.exclude, config.exclude, defaultExclude),
+    skip: chooseArray(skip, linkConfig.skip, commandConfig.skip, []),
+    checkFragments: checkFragments ?? linkConfig.checkFragments ?? commandConfig.checkFragments ?? true,
+    forbiddenTerms: chooseArray(forbiddenTerms, wordingConfig.forbiddenTerms, commandConfig.forbiddenTerms, []),
+    allow: chooseArray(allow, wordingConfig.allow, commandConfig.allow, []),
+    writeGood: chooseObject(writeGood, wordingConfig.writeGood, commandConfig.writeGood, {}),
+  };
+}
+
+function chooseArray(...candidates) {
+  for (const candidate of candidates) {
+    if (Array.isArray(candidate) && candidate.length > 0) {
+      return candidate;
+    }
+  }
+
+  return [];
+}
+
+function chooseObject(...candidates) {
+  for (const candidate of candidates) {
+    if (candidate && typeof candidate === 'object' && !Array.isArray(candidate)) {
+      return candidate;
+    }
+
+    if (candidate === false) {
+      return false;
+    }
+  }
+
+  return {};
+}
+
+function resolvePath(root, path) {
+  return isAbsolute(path) ? path : resolve(root, path);
+}

package/src/defaults.mjs

@@ -0,0 +1,21 @@
+export const defaultInclude = [
+  '*.md',
+  'docs/**/*.md',
+  '**/AGENTS.md',
+  '.agents/skills/**/*.md',
+  'packages/**/*.md',
+  'rules/**/*.md',
+  '.codex/**/*.md',
+];
+
+export const defaultExclude = [
+  'node_modules/**',
+  '.git/**',
+  'dist/**',
+  'coverage/**',
+  '.tmp/**',
+  'repos/**',
+  'worktrees/**',
+];
+
+export const defaultConfigFile = 'agent-doc-rules.config.json';

package/src/init.mjs

@@ -0,0 +1,118 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { defaultConfigFile, defaultExclude, defaultInclude } from './defaults.mjs';
+
+export const recommendedScripts = {
+  'docs:markdown': 'agent-doc-rules-docs markdown',
+  'docs:wording': 'agent-doc-rules-docs wording',
+  'docs:security': 'agent-doc-rules-docs security',
+  'docs:style': 'agent-doc-rules-docs-duplicates style',
+  'docs:links': 'agent-doc-rules-docs links',
+  'docs:duplicates': 'agent-doc-rules-docs-duplicates check',
+  'docs:check': 'agent-doc-rules-docs check && agent-doc-rules-docs-duplicates style && agent-doc-rules-docs-duplicates check',
+};
+
+export function buildStarterConfig() {
+  return {
+    docs: {
+      include: defaultInclude,
+      exclude: defaultExclude,
+      links: {
+        skip: [],
+        checkFragments: true,
+      },
+      wording: {
+        writeGood: {
+          passive: false,
+          illusion: false,
+          weasel: false,
+          adverb: false,
+          tooWordy: false,
+          eprime: false,
+          fail: false,
+        },
+        forbiddenTerms: [],
+        allow: [],
+      },
+      security: {
+        allow: [],
+      },
+      style: {
+        includeReferences: false,
+        minWords: 6,
+        minChars: 40,
+        maxUnits: 80,
+        model: 'gpt-5-nano',
+        reasoningEffort: 'low',
+      },
+      duplicates: {
+        includeReferences: false,
+        includeSameFile: false,
+        warnScore: 0.78,
+        failScore: 0.92,
+        minWords: 6,
+        minChars: 40,
+        maxCandidates: 50,
+        ignorePairs: [],
+        model: 'gpt-5-nano',
+        reasoningEffort: 'low',
+      },
+    },
+  };
+}
+
+export async function runInit({
+  root = process.cwd(),
+  configPath,
+  force = false,
+  print = false,
+} = {}, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
+  const resolvedRoot = resolve(root);
+  const target = resolveConfigPath(resolvedRoot, configPath);
+  const configText = `${JSON.stringify(buildStarterConfig(), null, 2)}\n`;
+  const scriptsText = formatRecommendedScripts();
+
+  if (print) {
+    stdout.write(configText);
+    stdout.write(`\nRecommended package scripts:\n${scriptsText}\n`);
+    return 0;
+  }
+
+  const existing = await readFile(target, 'utf8').catch((error) => {
+    if (error.code === 'ENOENT') {
+      return null;
+    }
+
+    throw error;
+  });
+
+  if (existing !== null && !force) {
+    stderr.write(
+      `${relative(resolvedRoot, target) || defaultConfigFile} already exists. `
+      + 'Use --force to overwrite it.\n',
+    );
+    return 1;
+  }
+
+  await mkdir(dirname(target), { recursive: true });
+  await writeFile(target, configText);
+
+  stdout.write(`Wrote ${relative(resolvedRoot, target) || defaultConfigFile}\n`);
+  stdout.write(`\nRecommended package scripts:\n${scriptsText}\n`);
+
+  return 0;
+}
+
+export function formatRecommendedScripts() {
+  return `${JSON.stringify({ scripts: recommendedScripts }, null, 2)}\n`;
+}
+
+function resolveConfigPath(root, configPath) {
+  if (!configPath) {
+    return resolve(root, defaultConfigFile);
+  }
+
+  return isAbsolute(configPath) ? configPath : resolve(root, configPath);
+}

package/src/runner.mjs

@@ -0,0 +1,444 @@
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import fastGlob from 'fast-glob';
+import writeGood from 'write-good';
+import { findSecurityIssues, normalizeSecurityAllow } from './security.mjs';
+
+const require = createRequire(import.meta.url);
+export const defaultWriteGoodOptions = {
+  passive: false,
+  illusion: false,
+  weasel: false,
+  adverb: false,
+  tooWordy: false,
+  eprime: false,
+};
+
+export function buildMarkdownlintArgs({ include, exclude }) {
+  return [
+    ...include,
+    ...expandExcludePatterns(exclude).map((pattern) => `!${pattern}`),
+  ];
+}
+
+export function buildLinkinatorArgs({ files, skip = [], checkFragments = true }) {
+  const args = ['--markdown', '--directory-listing'];
+
+  if (checkFragments) {
+    args.push('--check-fragments');
+  }
+
+  for (const pattern of skip) {
+    args.push('--skip', pattern);
+  }
+
+  return [...args, ...files];
+}
+
+export async function resolveMarkdownFiles({ root, include, exclude }) {
+  const files = await fastGlob(include, {
+    cwd: root,
+    dot: true,
+    ignore: expandExcludePatterns(exclude),
+    onlyFiles: true,
+    unique: true,
+  });
+
+  return files
+    .filter((file) => file.endsWith('.md'))
+    .sort((left, right) => left.localeCompare(right));
+}
+
+export async function runMarkdown({ root, include, exclude }, { runner = runNodeBin } = {}) {
+  const bin = resolveMarkdownlintBin();
+  const args = buildMarkdownlintArgs({ include, exclude });
+  return runner({ bin, args, cwd: root });
+}
+
+export async function runLinks(options, { runner = runNodeBin } = {}) {
+  const files = await resolveMarkdownFiles(options);
+
+  if (files.length === 0) {
+    console.log('No Markdown files found for link validation.');
+    return 0;
+  }
+
+  const bin = resolvePackageBin('linkinator', 'linkinator');
+  const args = buildLinkinatorArgs({
+    files,
+    skip: options.skip,
+    checkFragments: options.checkFragments,
+  });
+
+  return runner({ bin, args, cwd: options.root });
+}
+
+export async function runWording(options, { logger = console } = {}) {
+  const files = await resolveMarkdownFiles(options);
+  const terms = normalizeWordingTerms(options.forbiddenTerms ?? []);
+  const allowPatterns = (options.allow ?? []).map((pattern) => new RegExp(pattern, 'i'));
+  const writeGoodConfig = normalizeWriteGoodOptions(options.writeGood);
+  const termFindings = [];
+  const writeGoodFindings = [];
+
+  for (const file of files) {
+    const content = await readFile(join(options.root, file), 'utf8');
+    termFindings.push(...findWordingIssues(content, {
+      file,
+      terms,
+      allowPatterns,
+    }));
+
+    if (writeGoodConfig.enabled) {
+      writeGoodFindings.push(...findWriteGoodIssues(content, {
+        file,
+        allowPatterns,
+        writeGoodOptions: writeGoodConfig.options,
+      }));
+    }
+  }
+
+  if (termFindings.length === 0 && writeGoodFindings.length === 0) {
+    logger.log('Documentation wording check passed.');
+    return 0;
+  }
+
+  if (termFindings.length > 0) {
+    logger.error('Documentation wording check failed:');
+
+    for (const finding of termFindings) {
+      logger.error(
+        `- ${finding.file}:${finding.line} uses "${finding.term}". `
+        + `Prefer ${finding.suggest}.`,
+      );
+    }
+  }
+
+  if (writeGoodFindings.length > 0) {
+    const writeGoodLogger = writeGoodConfig.fail ? logger.error : logger.log;
+    writeGoodLogger(writeGoodConfig.fail
+      ? 'write-good wording suggestions failed:'
+      : 'write-good wording suggestions:');
+
+    for (const finding of writeGoodFindings) {
+      writeGoodLogger(
+        `- ${finding.file}:${finding.line}:${finding.column} ${finding.reason}`,
+      );
+    }
+  }
+
+  return termFindings.length > 0 || (writeGoodConfig.fail && writeGoodFindings.length > 0)
+    ? 1
+    : 0;
+}
+
+export async function runSecurity(options, { logger = console } = {}) {
+  const files = await resolveMarkdownFiles(options);
+  const allowPatterns = normalizeSecurityAllow(options.allow ?? []);
+  const findings = [];
+
+  for (const file of files) {
+    const content = await readFile(join(options.root, file), 'utf8');
+    findings.push(...findSecurityIssues(content, {
+      file,
+      allowPatterns,
+    }));
+  }
+
+  if (findings.length === 0) {
+    logger.log('Documentation security check passed.');
+    return 0;
+  }
+
+  logger.error('Documentation security check failed:');
+
+  for (const finding of findings) {
+    logger.error(`- ${finding.file}:${finding.line} ${finding.rule}: ${finding.message}`);
+
+    if (finding.text) {
+      logger.error(`  ${finding.text}`);
+    }
+  }
+
+  return 1;
+}
+
+export async function runCheck(options, deps = {}) {
+  const runMarkdownCommand = deps.runMarkdown ?? runMarkdown;
+  const runWordingCommand = deps.runWording ?? runWording;
+  const runSecurityCommand = deps.runSecurity ?? runSecurity;
+  const runLinksCommand = deps.runLinks ?? runLinks;
+  const markdownOptions = options.markdownOptions ?? options;
+  const wordingOptions = options.wordingOptions ?? options;
+  const securityOptions = options.securityOptions ?? options;
+  const linksOptions = options.linksOptions ?? options;
+  const markdownCode = await runMarkdownCommand(markdownOptions, deps);
+
+  if (markdownCode !== 0) {
+    return markdownCode;
+  }
+
+  const wordingCode = await runWordingCommand(wordingOptions, deps);
+
+  if (wordingCode !== 0) {
+    return wordingCode;
+  }
+
+  const securityCode = await runSecurityCommand(securityOptions, deps);
+
+  if (securityCode !== 0) {
+    return securityCode;
+  }
+
+  return runLinksCommand(linksOptions, deps);
+}
+
+export function resolveMarkdownlintBin() {
+  const entry = require.resolve('markdownlint-cli2');
+  return join(dirname(entry), 'markdownlint-cli2-bin.mjs');
+}
+
+export function resolvePackageBin(packageName, binName) {
+  for (const packageJsonPath of resolvePackageJsonPaths(packageName)) {
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    const bin = typeof packageJson.bin === 'string'
+      ? packageJson.bin
+      : packageJson.bin?.[binName];
+
+    if (!bin) {
+      continue;
+    }
+
+    const binPath = join(dirname(packageJsonPath), bin);
+
+    if (existsSync(binPath)) {
+      return binPath;
+    }
+  }
+
+  throw new Error(`Package ${packageName} does not expose bin ${binName}.`);
+}
+
+export function resolvePackageJsonPaths(packageName) {
+  const packageJsonPaths = [];
+
+  try {
+    packageJsonPaths.push(require.resolve(`${packageName}/package.json`));
+  } catch (error) {
+    if (error.code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
+      throw error;
+    }
+  }
+
+  if (packageJsonPaths.length > 0) {
+    return [...new Set(packageJsonPaths)];
+  }
+
+  let directory = dirname(require.resolve(packageName));
+
+  while (true) {
+    const candidate = join(directory, 'package.json');
+
+    if (existsSync(candidate)) {
+      const packageJson = JSON.parse(readFileSync(candidate, 'utf8'));
+
+      if (packageJson.name === packageName) {
+        packageJsonPaths.push(candidate);
+      }
+    }
+
+    const parent = dirname(directory);
+
+    if (parent === directory) {
+      break;
+    }
+
+    directory = parent;
+  }
+
+  return [...new Set(packageJsonPaths)];
+}
+
+export function runNodeBin({ bin, args, cwd }) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [bin, ...args], {
+      cwd,
+      stdio: 'inherit',
+      env: {
+        ...process.env,
+        NO_COLOR: process.env.NO_COLOR ?? '1',
+      },
+    });
+
+    child.on('error', reject);
+    child.on('close', (code) => resolve(code ?? 1));
+  });
+}
+
+export function expandExcludePatterns(exclude) {
+  const expanded = [];
+
+  for (const pattern of exclude) {
+    expanded.push(pattern);
+
+    if (!pattern.startsWith('**/') && !pattern.startsWith('/')) {
+      expanded.push(`**/${pattern}`);
+    }
+  }
+
+  return [...new Set(expanded)];
+}
+
+export function findWordingIssues(content, { file, terms, allowPatterns = [] }) {
+  const findings = [];
+  let inFence = false;
+  const lines = content.split('\n');
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+
+    if (/^\s*(```|~~~)/.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+
+    if (inFence || allowPatterns.some((pattern) => pattern.test(line))) {
+      continue;
+    }
+
+    for (const term of terms) {
+      if (term.pattern.test(line)) {
+        findings.push({
+          file,
+          line: index + 1,
+          term: term.term,
+          suggest: term.suggest,
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+export function findWriteGoodIssues(content, {
+  file,
+  allowPatterns = [],
+  writeGoodOptions = defaultWriteGoodOptions,
+}) {
+  const masked = maskMarkdownForProseLint(content);
+  const suggestions = writeGood(masked, writeGoodOptions);
+  const lines = content.split('\n');
+
+  return suggestions
+    .map((suggestion) => {
+      const location = getLineColumn(content, suggestion.index);
+      const line = lines[location.line - 1] ?? '';
+
+      return {
+        file,
+        line: location.line,
+        column: location.column,
+        reason: suggestion.reason,
+        index: suggestion.index,
+        offset: suggestion.offset,
+        text: content.slice(suggestion.index, suggestion.index + suggestion.offset),
+        ignored: allowPatterns.some((pattern) => pattern.test(line)),
+      };
+    })
+    .filter((finding) => !finding.ignored)
+    .map(({ ignored, ...finding }) => finding);
+}
+
+export function normalizeWordingTerms(terms) {
+  return terms.map((term) => {
+    const normalized = typeof term === 'string'
+      ? { term, suggest: 'a more direct term' }
+      : term;
+
+    if (!normalized?.term) {
+      throw new Error('Style terms must be strings or objects with a term field.');
+    }
+
+    return {
+      term: normalized.term,
+      suggest: normalized.suggest ?? 'a more direct term',
+      pattern: new RegExp(`\\b${escapeRegExp(normalized.term)}\\b`, 'i'),
+    };
+  });
+}
+
+export function normalizeWriteGoodOptions(config = {}) {
+  if (config === false) {
+    return { enabled: false, fail: false, options: defaultWriteGoodOptions };
+  }
+
+  const { enabled = true, fail = false, ...options } = config ?? {};
+
+  return {
+    enabled,
+    fail,
+    options: {
+      ...defaultWriteGoodOptions,
+      ...options,
+    },
+  };
+}
+
+export function maskMarkdownForProseLint(content) {
+  let masked = '';
+  let inFence = false;
+
+  for (const line of content.split(/(\n)/)) {
+    if (line === '\n') {
+      masked += line;
+      continue;
+    }
+
+    if (/^\s*(```|~~~)/.test(line)) {
+      inFence = !inFence;
+      masked += maskNonNewlineCharacters(line);
+      continue;
+    }
+
+    if (inFence || isMarkdownTableLine(line)) {
+      masked += maskNonNewlineCharacters(line);
+      continue;
+    }
+
+    masked += line.replace(/`[^`\n]+`/g, (match) => maskNonNewlineCharacters(match));
+  }
+
+  return masked;
+}
+
+function getLineColumn(content, index) {
+  let line = 1;
+  let column = 1;
+
+  for (let cursor = 0; cursor < index; cursor += 1) {
+    if (content[cursor] === '\n') {
+      line += 1;
+      column = 1;
+    } else {
+      column += 1;
+    }
+  }
+
+  return { line, column };
+}
+
+function maskNonNewlineCharacters(value) {
+  return value.replace(/[^\n]/g, ' ');
+}
+
+function isMarkdownTableLine(line) {
+  return /^\s*\|.*\|\s*$/.test(line);
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/security.mjs

@@ -0,0 +1,145 @@
+export const defaultSecurityRules = [
+  {
+    id: 'remote-script-execution',
+    message: 'Remote script execution can run unreviewed code from documentation.',
+    allowSafetyFraming: true,
+    patterns: [
+      /\b(?:curl|wget)\b[^|\n]*\|\s*(?:sudo\s+)?(?:sh|bash|zsh|python|node)\b/i,
+      /\b(?:sh|bash|zsh|python|node)\s+<\(\s*(?:curl|wget)\b/i,
+    ],
+  },
+  {
+    id: 'secret-exfiltration-command',
+    message: 'A network command appears to send secrets or local credentials.',
+    allowSafetyFraming: true,
+    patterns: [
+      /\b(?:curl|wget|httpie|http|scp|rsync|nc|netcat|gh\s+gist)\b.*\b(?:\.env|id_rsa|id_ed25519|github_token|aws_secret_access_key|secret|token|password|private[_ -]?key|credentials?|cookies?)\b/i,
+    ],
+  },
+  {
+    id: 'secret-disclosure-instruction',
+    message: 'The line appears to ask an agent to disclose secrets or credentials.',
+    allowSafetyFraming: true,
+    patterns: [
+      /\b(?:cat|echo|printenv|dump|paste|copy|send|upload|post|share)\b.*\b(?:\.env|id_rsa|id_ed25519|github_token|aws_secret_access_key|secrets?|tokens?|passwords?|private keys?|credentials?|cookies?)\b/i,
+    ],
+  },
+  {
+    id: 'agent-instruction-override',
+    message: 'The line appears to override higher-priority agent instructions or hide changes.',
+    allowSafetyFraming: false,
+    patterns: [
+      /\bignore\s+(?:all\s+)?(?:previous|prior|system|developer|higher[- ]priority)\s+instructions\b/i,
+      /\b(?:do\s+not|don't)\s+(?:tell|mention|report|disclose|warn|notify)\s+(?:the\s+)?user\b/i,
+      /\b(?:silently|secretly)\s+(?:change|edit|modify|add|remove|bypass)\b/i,
+    ],
+  },
+  {
+    id: 'validation-bypass',
+    message: 'The line appears to bypass validation, tests, linting, or security checks.',
+    allowSafetyFraming: true,
+    patterns: [
+      /\b(?:skip|bypass|disable|ignore)\b.{0,80}\b(?:tests?|lint|validation|checks?|docs:check|pre-commit|precommit|security scan|security check)\b/i,
+      /(?:^|[^\w-])--no-verify\b/i,
+      /\bSKIP_(?:TESTS|CHECKS|VALIDATION|LINT)\b/i,
+    ],
+  },
+  {
+    id: 'backdoor-or-auth-bypass',
+    message: 'The line appears to add a backdoor or weaken authentication, authorization, or validation.',
+    allowSafetyFraming: true,
+    patterns: [
+      /\b(?:add|create|keep|leave|implement|use)\b.{0,80}\b(?:backdoor|hardcoded admin|admin fallback|debug endpoint|bypass auth|auth bypass|fail open)\b/i,
+      /\b(?:disable|bypass|turn off|remove)\b.{0,80}\b(?:auth|authentication|authorization|csrf|tls|ssl|certificate validation|input validation|rate limit|permission checks?)\b/i,
+    ],
+  },
+  {
+    id: 'remote-markdown-image',
+    message: 'Remote Markdown images and HTML images can leak reader metadata.',
+    allowSafetyFraming: true,
+    patterns: [
+      /!\[[^\]]*\]\(\s*https?:\/\/[^)\s]+/i,
+      /<img\b[^>]*\bsrc=["']https?:\/\//i,
+    ],
+  },
+  {
+    id: 'tracking-link',
+    message: 'Tracking query parameters do not belong in reusable repository documentation.',
+    allowSafetyFraming: true,
+    patterns: [
+      /https?:\/\/[^\s)]+[?&](?:utm_[a-z0-9_]+|fbclid|gclid|mc_cid|ga_[a-z0-9_]+|yclid)=/i,
+    ],
+  },
+  {
+    id: 'encoded-execution-payload',
+    message: 'Encoded execution payloads are hard to review in documentation.',
+    allowSafetyFraming: true,
+    patterns: [
+      /\b(?:base64|atob|Buffer\.from)\b.{0,80}\b(?:eval|exec|sh|bash|curl|wget)\b/i,
+    ],
+  },
+];
+
+export function findSecurityIssues(content, {
+  file,
+  allowPatterns = [],
+  rules = defaultSecurityRules,
+} = {}) {
+  const findings = [];
+  const lines = content.split('\n');
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+
+    if (allowPatterns.some((pattern) => pattern.test(line))) {
+      continue;
+    }
+
+    const clauses = splitSecurityClauses(line);
+
+    for (const rule of rules) {
+      const matchingClause = clauses.find((clause) => {
+        if (rule.allowSafetyFraming && isSafetyFramed(clause)) {
+          return false;
+        }
+
+        return rule.patterns.some((pattern) => pattern.test(clause));
+      });
+
+      if (!matchingClause) {
+        continue;
+      }
+
+      findings.push({
+        file,
+        line: index + 1,
+        rule: rule.id,
+        message: rule.message,
+        text: trimFindingText(matchingClause),
+      });
+    }
+  }
+
+  return findings;
+}
+
+export function normalizeSecurityAllow(patterns = []) {
+  return patterns.map((pattern) => new RegExp(pattern, 'i'));
+}
+
+function isSafetyFramed(line) {
+  return /^\s*(?:[-*+]\s+|\d+\.\s+|>\s*)?(?:do not|don't|never|avoid|refuse|reject|block|fail|flag|detect|warn|warning|forbid|prohibit|must not|should not|cannot|can't)\b/i
+    .test(line);
+}
+
+function splitSecurityClauses(line) {
+  return line
+    .split(/\s*;\s*|(?<=[.!?])\s+(?=[A-Z`"'])|\s+(?:but|unless|except|instead|then)\s+/i)
+    .map((clause) => clause.trim())
+    .filter(Boolean);
+}
+
+function trimFindingText(line) {
+  const text = line.trim();
+  return text.length > 160 ? `${text.slice(0, 157)}...` : text;
+}