Agent Wranglers

DOC-34Recommended

Fail the build when docs name something that no longer exists

Check in the build that every file path, command, flag and setting the docs name in inline code still exists in the code.

By Agent Wranglers. Updated .

How to do it

Renamed settings and moved files are the most common way docs go wrong without anyone noticing. Extract inline code that looks like a path, a command-line flag or a setting name. Compare paths with the repository, flags with the tool's --help output and settings with the schema from Generate the settings reference from one schema. The same check for the agent instructions file is in Keep instructions short and current.

Examples

JavaScript example

import { existsSync, readFileSync } from 'node:fs';

const INLINE_CODE = /`([^`\s]+)`/g;
const looksLikePath = text => /^[\w.-]+\/[\w./-]+$/.test(text);

export const missingPaths = docFile => [...readFileSync(docFile, 'utf8').matchAll(INLINE_CODE)]
  .map(([, text]) => text).filter(text => looksLikePath(text) && !existsSync(text));

Python example

import re
from pathlib import Path

INLINE_CODE = re.compile(r"`([^`\s]+)`")
LOOKS_LIKE_PATH = re.compile(r"^[\w.-]+/[\w./-]+$")

def missing_paths(doc_file: str) -> list[str]:
    names = INLINE_CODE.findall(Path(doc_file).read_text())
    return [name for name in names if LOOKS_LIKE_PATH.match(name) and not Path(name).exists()]

How to check

Rename a setting on a branch without changing the docs. The docs check fails and names each page that still uses the old name.

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/documentation/keeping-docs-current/names-that-exist">Agent Wranglers documentation playbook</a>. In code you write, add a comment next to it with the same link.