@veda-hq/pariksha 0.5.13 → 0.5.17

package/dist/doc-identifiers.js

@@ -0,0 +1,348 @@
+// DOC-DRIFT-04: a code identifier a doc names exists in the code. Every
+// single-identifier code span in a doc's prose is asked of the code:
+//
+//   - env vars, constants and symbols (`DATABASE_URL`, `parseArgs()`,
+//     `OrderService`): a whole word somewhere in the tracked code; when the doc
+//     says "`x` in `path`", in that file;
+//   - Prisma `Model.field`, `@@unique([a, b])`, migration folders and
+//     `@Roles(…)` values (`identifiers.prisma`);
+//   - HTTP routes (`GET /stores/:id`) against controller decorators
+//     (`identifiers.routes`);
+//   - CI jobs ("the `build` job") against workflow files (`identifiers.jobs`);
+//   - packages (`@acme/core`, `zod@4.1.0`) against workspaces and the
+//     lockfile (`identifiers.packages`).
+//
+// The code search reads the whole tree, so it runs at push and in CI, not at
+// commit.
+import { posix } from 'node:path';
+import { load } from 'js-yaml';
+import { codeSpans, docKind, scanMarkdown } from "./doc-references.js";
+import { isRecord } from "./registry-ratchet.js";
+const UPPER_SNAKE = /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/;
+const CAMEL = /^[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)+$/;
+const PASCAL = /^[A-Z][a-z0-9]+(?:[A-Z][a-z0-9]*)+$/;
+const CALL = /^([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\(\)$/;
+const DOTTED = /^([A-Za-z_$][\w$]*)\.([A-Za-z_$][\w$]*)$/;
+const MIGRATION = /^\d{14}_[a-z0-9_]+$/;
+const ROUTE = /^(GET|POST|PUT|PATCH|DELETE)\s+(\/\S*)$/;
+const ROLES = /^@Roles\((.*)\)$/;
+const SCOPED_PACKAGE = /^(@[a-z0-9][\w.-]*\/[a-z0-9][\w.-]*)(?:@(\d+\.\d+\.\d+))?$/;
+const VERSIONED_PACKAGE = /^([a-z0-9][\w.-]*)@(\d+\.\d+\.\d+)$/;
+/** What a single code span names, if it names an identifier; `notIdentifiers` are products and prose. */
+export const identifierRef = (span, notIdentifiers) => {
+    const text = span.trim();
+    if (/\s{2,}/.test(text))
+        return null;
+    if (MIGRATION.test(text))
+        return { kind: 'migration', text };
+    if (ROUTE.test(text))
+        return { kind: 'route', text };
+    if (ROLES.test(text))
+        return { kind: 'roles', text };
+    if (/^@@unique\(\[[\w\s,]+\]\)$/.test(text))
+        return { kind: 'prisma-unique', text };
+    if (SCOPED_PACKAGE.test(text) || VERSIONED_PACKAGE.test(text))
+        return { kind: 'package', text };
+    if (/\s/.test(text) || notIdentifiers.has(text))
+        return null;
+    const call = CALL.exec(text);
+    if (call !== null) {
+        const word = String(call[1]).replace(/^.*\./, '');
+        return word.length < 3 || notIdentifiers.has(word) ? null : { kind: 'symbol', text, word };
+    }
+    const dotted = DOTTED.exec(text);
+    if (dotted !== null && /^[A-Z]/.test(String(dotted[1])) && /^[a-z]/.test(String(dotted[2])))
+        return { kind: 'prisma-field', text };
+    // Lower snake_case is deliberately absent: it is dominated by names that are
+    // not the repository's code (tool names, database settings, table keys).
+    if (UPPER_SNAKE.test(text) || CAMEL.test(text) || PASCAL.test(text))
+        return { kind: 'symbol', text, word: text };
+    return null;
+};
+/** Text of every tracked file whose path matches `pattern`. */
+const contents = (snapshot, pattern) => [...snapshot.readMany([...snapshot.files].filter((file) => pattern.test(file))).values()];
+const prismaModels = (snapshot, schemas) => {
+    const models = new Map();
+    for (const text of contents(snapshot, schemas)) {
+        for (const block of text.matchAll(/^(model|enum|type|view)\s+(\w+)\s*\{([\s\S]*?)^\}/gm)) {
+            const fields = new Set();
+            const uniques = [];
+            for (const raw of String(block[3]).split('\n')) {
+                // A blank line, a `//` comment or an `@@` attribute starts with no word, so it names no field.
+                const line = raw.trim();
+                const unique = /^@@(?:unique|id)\(\s*\[([^\]]+)\]/.exec(line);
+                if (unique !== null) {
+                    uniques.push(String(unique[1])
+                        .split(',')
+                        .map((f) => String(f.trim().split(/[\s(]/)[0]))
+                        .join(','));
+                    continue;
+                }
+                const name = /^(\w+)/.exec(line);
+                if (name !== null)
+                    fields.add(String(name[1]));
+            }
+            models.set(String(block[2]), { fields, uniques });
+        }
+    }
+    return models;
+};
+const splitRoute = (path) => path
+    .split('/')
+    .filter(Boolean)
+    .map((segment) => (/^[:{]/.test(segment) ? ':' : segment.toLowerCase()));
+/** Routes the controllers' decorators serve (`@Controller('x')`, `@Get(':id')`). */
+const controllerRoutes = (snapshot, controllers) => {
+    const routes = [];
+    for (const text of contents(snapshot, controllers)) {
+        let prefix = '';
+        for (const match of text.matchAll(/@(Controller|Get|Post|Put|Patch|Delete)\(\s*(?:['"`]([^'"`]*)['"`])?[^)]*\)/g)) {
+            const path = match[2] ?? '';
+            if (match[1] === 'Controller') {
+                prefix = path;
+                continue;
+            }
+            routes.push({ method: String(match[1]).toUpperCase(), segments: splitRoute(`${prefix}/${path}`) });
+        }
+    }
+    return routes;
+};
+/** A controller parameter takes any documented value (`/stores/42`); a documented parameter names only a parameter. */
+const routeMatches = (route, method, segments) => route.method === method && route.segments.length === segments.length && route.segments.every((segment, index) => segment === ':' || segment === segments[index]);
+const roleValues = (snapshot, schema, name) => {
+    const roles = new Set();
+    const text = snapshot.read(schema);
+    if (text === undefined)
+        return roles;
+    for (const [, block] of text.matchAll(new RegExp(`^enum ${name}\\s*\\{([\\s\\S]*?)^\\}`, 'gm'))) {
+        for (const [, role] of String(block).matchAll(/^[ \t]*([A-Z_]+)\s*$/gm))
+            roles.add(String(role));
+    }
+    return roles;
+};
+/** Job ids and job names in the workflow files; one that does not parse is its linter's to fail. */
+const workflowJobs = (snapshot, workflows) => {
+    const jobs = new Set();
+    for (const text of contents(snapshot, workflows)) {
+        let workflow;
+        try {
+            workflow = load(text);
+        }
+        catch {
+            continue;
+        }
+        const all = isRecord(workflow) ? workflow['jobs'] : undefined;
+        if (!isRecord(all))
+            continue;
+        for (const [id, job] of Object.entries(all)) {
+            jobs.add(id);
+            if (isRecord(job) && typeof job['name'] === 'string')
+                jobs.add(job['name']);
+        }
+    }
+    return jobs;
+};
+/** A manifest's parsed JSON as an object, or undefined: a malformed manifest is another check's to fail. */
+export const manifestObject = (text) => {
+    try {
+        const parsed = JSON.parse(text);
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+const packageIndex = (snapshot, manifests, lockfile) => {
+    const names = new Set();
+    const versions = new Set();
+    for (const text of contents(snapshot, manifests)) {
+        const name = manifestObject(text)?.['name'];
+        if (typeof name === 'string')
+            names.add(name);
+    }
+    const lock = lockfile === undefined ? undefined : snapshot.read(lockfile);
+    for (const match of (lock ?? '').matchAll(/^ {2}'?((?:@[\w.-]+\/)?[\w.-]+)@(\d+\.\d+\.\d+[^:'(]*)/gm)) {
+        names.add(String(match[1]));
+        versions.add(`${String(match[1])}@${String(match[2])}`);
+    }
+    return { names, versions };
+};
+const BINARY = /\.(png|jpe?g|gif|webp|ico|icns|ttf|otf|woff2?|jar|keystore|zip|gz|tgz|pdf|mp4|mov|mp3|wav|tflite|bin|so|a|dylib|car|lockb)$/i;
+/** Tracked text that can define a name: everything but binaries, the baseline and the config's `searchExclude`. */
+export const isCode = (config, path) => !BINARY.test(path) && path !== config.baseline && !config.identifiers.searchExclude.some((p) => p.test(path));
+/** Which of `words` occur as whole words in the snapshot's code. */
+export const wordsInCode = (config, snapshot, words) => {
+    const wanted = new Set(words);
+    const found = new Set();
+    if (wanted.size === 0)
+        return found;
+    // One tokenising pass over the code, in process: `git grep -F -w -f` with
+    // thousands of patterns runs for minutes on a large tree.
+    for (const text of snapshot.readMany([...snapshot.files].filter((path) => isCode(config, path))).values()) {
+        for (const match of text.matchAll(/[A-Za-z_$][\w$]*/g)) {
+            if (wanted.has(match[0])) {
+                found.add(match[0]);
+                if (found.size === wanted.size)
+                    return found;
+            }
+        }
+    }
+    return found;
+};
+/** `\b` cannot bound a `$`: a word bounded by "no identifier character" on either side. */
+export const boundedWord = (word) => new RegExp(`(?<![\\w$])${word.replace(/\$/g, '\\$')}(?![\\w$])`);
+/** Runs DOC-DRIFT-04 over `files` in `snapshot`. */
+export const findIdentifierProblems = (config, snapshot, files) => {
+    const { notIdentifiers, prisma, routes: routeConfig, jobs: jobConfig, packages: packageConfig } = config.identifiers;
+    const pending = [];
+    for (const file of files) {
+        if (docKind(config, file) !== 'markdown')
+            continue;
+        const content = snapshot.read(file);
+        if (content === undefined)
+            continue;
+        for (const line of scanMarkdown(content, config.exemptMarker)) {
+            if (line.exempt || line.fence !== null || line.frontmatter)
+                continue;
+            const spans = codeSpans(line.text);
+            spans.forEach((span, index) => {
+                const ref = identifierRef(span.content, notIdentifiers);
+                if (ref === null)
+                    return;
+                // A CI job is named as one: "the `build` job".
+                if (ref.kind === 'symbol' && /^\s+jobs?\b/.test(line.text.slice(span.end + 1))) {
+                    pending.push({ file, line: line.number, ref: { kind: 'job', text: ref.text }, citedFile: undefined });
+                    return;
+                }
+                const next = spans[index + 1];
+                let citedFile;
+                if (next !== undefined && /^\s*(?:in|from)\s*\[?$/.test(line.text.slice(span.end + 1, next.start - 1))) {
+                    const path = next.content.replace(/:\d+(?:-\d+)?$/, '');
+                    citedFile = [posix.join(posix.dirname(file), path), path].map((p) => posix.normalize(p)).find((p) => snapshot.files.has(p));
+                }
+                pending.push({ file, line: line.number, ref, citedFile });
+            });
+        }
+    }
+    const inCode = wordsInCode(config, snapshot, [...new Set(pending.flatMap((p) => (p.ref.word === undefined ? [] : [p.ref.word])))]);
+    let models;
+    let routes;
+    let roles;
+    let jobs;
+    let packages;
+    const problems = [];
+    const flag = (p, reason) => {
+        problems.push({ check: 'DOC-DRIFT-04', file: p.file, line: p.line, ref: p.ref.text, reason });
+    };
+    for (const p of pending) {
+        const { ref } = p;
+        switch (ref.kind) {
+            case 'symbol': {
+                const word = ref.word ?? ref.text;
+                if (p.citedFile !== undefined) {
+                    const text = snapshot.read(p.citedFile);
+                    if (text !== undefined && !boundedWord(word).test(text))
+                        flag(p, `\`${word}\` does not occur in \`${p.citedFile}\`, the file the doc cites for it`);
+                }
+                else if (!inCode.has(word)) {
+                    flag(p, `\`${word}\` occurs nowhere in the code — renamed, removed, or never written`);
+                }
+                break;
+            }
+            case 'prisma-field': {
+                if (prisma === undefined)
+                    break;
+                models ??= prismaModels(snapshot, prisma.schemas);
+                const [model = '', field = ''] = ref.text.split('.');
+                const found = models.get(model);
+                // Every `Capital.lower` reads as a column (`Object.keys`), so only a model the schema declares is judged.
+                if (found !== undefined && !found.fields.has(field))
+                    flag(p, `Prisma model \`${model}\` has no field \`${field}\``);
+                break;
+            }
+            case 'prisma-unique': {
+                if (prisma === undefined)
+                    break;
+                models ??= prismaModels(snapshot, prisma.schemas);
+                const wanted = ref.text
+                    .replace(/^@@unique\(\[|\]\)$/g, '')
+                    .split(',')
+                    .map((f) => f.trim())
+                    .join(',');
+                if (![...models.values()].some((model) => model.uniques.includes(wanted)))
+                    flag(p, `no Prisma model declares \`${ref.text}\``);
+                break;
+            }
+            case 'migration': {
+                const dir = prisma?.migrations;
+                if (dir !== undefined && !snapshot.dirs.has(`${dir}/${ref.text}`))
+                    flag(p, `\`${ref.text}\` is not a directory under ${dir}/`);
+                break;
+            }
+            case 'route': {
+                if (routeConfig === undefined)
+                    break;
+                routes ??= controllerRoutes(snapshot, routeConfig.controllers);
+                const [, method = '', rawPath = ''] = ROUTE.exec(ref.text) ?? [];
+                const path = rawPath.replace(/[?#].*$/, '');
+                if (/[{][^}]*,/.test(path))
+                    break; // a brace expansion lists several
+                const all = splitRoute(path);
+                const known = new Set(routes.map((route) => route.segments[0]));
+                // Clients and proxies prefix the served paths (`/api/v1`); the server does not.
+                const start = all.findIndex((segment) => known.has(segment) || !routeConfig.prefixes.test(segment));
+                const segments = all.slice(start === -1 ? all.length : start);
+                const head = segments[0];
+                if (head === undefined || !known.has(head))
+                    break; // not this repository's
+                if (!routes.some((served) => routeMatches(served, method, segments)))
+                    flag(p, `no controller serves \`${method} ${path}\``);
+                break;
+            }
+            case 'roles': {
+                const rolesConfig = prisma?.roles;
+                if (rolesConfig === undefined)
+                    break;
+                roles ??= roleValues(snapshot, rolesConfig.schema, rolesConfig.enum);
+                // No enum to read is a failure, not a pass: every role would go unchecked.
+                if (roles.size === 0) {
+                    flag(p, `no \`${rolesConfig.enum}\` in the Prisma schema to check roles against`);
+                    break;
+                }
+                for (const match of ref.text.replace(/^@Roles\(|\)$/g, '').matchAll(/(?:\w+\.)?([A-Z][A-Z_]+)/g)) {
+                    const role = String(match[1]);
+                    if (!roles.has(role))
+                        flag(p, `\`${role}\` is not a value of ${rolesConfig.enum}`);
+                }
+                break;
+            }
+            case 'job': {
+                if (jobConfig === undefined)
+                    break;
+                jobs ??= workflowJobs(snapshot, jobConfig.workflows);
+                if (!jobs.has(ref.text))
+                    flag(p, `no workflow has a job \`${ref.text}\``);
+                break;
+            }
+            case 'package': {
+                if (packageConfig === undefined)
+                    break;
+                packages ??= packageIndex(snapshot, packageConfig.manifests, packageConfig.lockfile);
+                const scoped = SCOPED_PACKAGE.exec(ref.text);
+                const versioned = VERSIONED_PACKAGE.exec(ref.text);
+                const name = scoped?.[1] ?? versioned?.[1] ?? ref.text;
+                const version = scoped?.[2] ?? versioned?.[2];
+                if (!packages.names.has(name)) {
+                    // Only the repository's own scopes are knowable; a third-party name the lockfile lacks may be installed elsewhere.
+                    if (packageConfig.ownScopes.some((scope) => name.startsWith(scope)))
+                        flag(p, `no workspace is named \`${name}\``);
+                }
+                else if (version !== undefined && !packages.versions.has(`${name}@${version}`)) {
+                    flag(p, `the lockfile has no \`${name}@${version}\``);
+                }
+                break;
+            }
+        }
+    }
+    return problems;
+};

package/dist/doc-links.js

@@ -0,0 +1,183 @@
+// DOC-DRIFT-01, links and anchors: a relative Markdown link, reference
+// definition or image names a file that exists, and its `#anchor` a heading
+// in that file. The checking is lychee's, offline; this module only chooses
+// the tree it reads, parses its report, and applies the exemptions.
+//
+// lychee reads files from disk. A worktree or index snapshot is read where it
+// stands; a ref snapshot (a push's head or merge base) is extracted to a
+// temporary directory first. Backticked paths are not links: doc-paths.ts
+// reads those.
+import { execFileSync, spawnSync } from 'node:child_process';
+import { mkdtempSync, realpathSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, posix, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { normalizeRepoPath } from "./doc-references.js";
+import { gitEnv, PINNED } from "./git.js";
+import { isRecord } from "./registry-ratchet.js";
+const optionalString = (v, where) => {
+    if (v === undefined || typeof v === 'string')
+        return v;
+    throw new Error(`lychee's report: ${where} is not a string`);
+};
+/** The part of lychee's `--format json` report read here (`error_map`); the rest is ignored. */
+const errorMap = (report) => {
+    const parsed = JSON.parse(report);
+    if (!isRecord(parsed))
+        throw new Error("lychee's report is not a JSON object");
+    const map = parsed['error_map'];
+    if (map === undefined)
+        return [];
+    if (!isRecord(map))
+        throw new Error("lychee's report: error_map is not an object");
+    return Object.entries(map).map(([source, entries]) => {
+        if (!Array.isArray(entries))
+            throw new Error(`lychee's report: error_map["${source}"] is not a list`);
+        return [
+            source,
+            entries.map((entry, i) => {
+                const where = `error_map["${source}"][${i}]`;
+                if (!isRecord(entry))
+                    throw new Error(`lychee's report: ${where} is not an object`);
+                const status = entry['status'];
+                const span = entry['span'];
+                if (status !== undefined && !isRecord(status))
+                    throw new Error(`lychee's report: ${where}.status is not an object`);
+                if (span !== undefined && !isRecord(span))
+                    throw new Error(`lychee's report: ${where}.span is not an object`);
+                const line = span?.['line'];
+                if (line !== undefined && (typeof line !== 'number' || !Number.isSafeInteger(line) || line < 1))
+                    throw new Error(`lychee's report: ${where}.span.line is not a positive integer`);
+                return { url: optionalString(entry['url'], `${where}.url`), status: optionalString(status?.['text'], `${where}.status.text`) ?? '', line };
+            }),
+        ];
+    });
+};
+const reasonFor = (text, path, hash) => {
+    if (/fragment/i.test(text))
+        return path === '' ? `Cannot find heading for \`${hash}\`` : `Cannot find heading for \`${hash}\` in \`${path}\``;
+    if (/not found/i.test(text))
+        return `Cannot find file \`${path}\``;
+    return `${text || 'lychee could not check it'}: \`${path}${hash}\``;
+};
+/**
+ * Reads lychee's `--format json` report of a run in `dir`. Only `file://`
+ * links are this check's; a URL is not (offline, lychee blocks them). Each
+ * target is named from its doc's directory, as the link was written.
+ */
+export const parseLycheeReport = (report, dir) => {
+    const entries = errorMap(report);
+    const root = realpathSync(dir);
+    const findings = [];
+    for (const [source, list] of entries) {
+        const file = relative(root, resolve(root, source));
+        for (const entry of list) {
+            if (entry.url === undefined || !entry.url.startsWith('file:'))
+                continue;
+            const url = new URL(entry.url);
+            // fileURLToPath reads the path alone: the #anchor stays on `url`.
+            const target = fileURLToPath(url);
+            const path = target === join(root, file) ? '' : relative(join(root, file, '..'), target);
+            findings.push({ file, line: entry.line ?? 1, ref: `${path}${url.hash}`, reason: reasonFor(entry.status, path, url.hash) });
+        }
+    }
+    return findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+};
+/**
+ * How lychee's `--files-from` must name `file` to read that file and no
+ * other. It takes a line as a URL (`https:x.md`) unless it starts `./`, and
+ * as a glob when it holds `*`, `?` or `[`, so those are bracketed. A line
+ * cannot hold a newline: that path is refused, never left unchecked.
+ */
+export const lycheeInputLine = (file) => {
+    if (/[\n\r]/.test(file))
+        throw new Error(`lychee reads its file list a line at a time, so it cannot check ${JSON.stringify(file)}: rename it`);
+    return `./${file.replace(/[*?[]/g, (char) => `[${char}]`)}`;
+};
+/**
+ * The real runner: lychee, offline, anchors included. `--config /dev/null`
+ * keeps a lychee.toml in the tree out of it; `--root-dir` resolves a
+ * `/docs/x.md` link from the repository root. A missing lychee fails, never
+ * passes. `command` is the executable, `lychee` on PATH by default.
+ */
+export const lycheeRunner = (command = 'lychee') => (dir, files) => {
+    const result = spawnSync(command, ['--offline', '--include-fragments', '--format', 'json', '--no-progress', '--config', '/dev/null', '--root-dir', realpathSync(dir), '--files-from', '-'], {
+        cwd: dir,
+        encoding: 'utf8',
+        input: `${files.map(lycheeInputLine).join('\n')}\n`,
+        maxBuffer: 256 * 1024 * 1024,
+    });
+    if (result.error !== undefined) {
+        if (result.error.code === 'ENOENT')
+            throw new Error(`${command} is not installed; the link check needs lychee (https://lychee.cli.rs)`);
+        throw result.error;
+    }
+    // 0: every link resolves; 2: some do not, listed in the report.
+    if (result.status !== 0 && result.status !== 2)
+        throw new Error(`lychee exited ${String(result.status)}: ${result.stderr}`);
+    return result.stdout;
+};
+/** A directory holding the snapshot's tree, and how to let it go. */
+export const treeFor = (snapshot) => {
+    if (snapshot.source.kind !== 'ref')
+        return { dir: snapshot.root, release: () => undefined };
+    const dir = mkdtempSync(join(tmpdir(), 'doc-links-'));
+    try {
+        const tar = join(dir, '.tree.tar');
+        execFileSync('git', [...PINNED, 'archive', '-o', tar, snapshot.source.ref], { cwd: snapshot.root, env: gitEnv(process.env), stdio: 'pipe' });
+        execFileSync('tar', ['-xf', tar, '-C', dir], { stdio: 'pipe' });
+        rmSync(tar);
+    }
+    catch (e) {
+        rmSync(dir, { recursive: true, force: true });
+        throw e;
+    }
+    return { dir, release: () => rmSync(dir, { recursive: true, force: true }) };
+};
+/**
+ * The broken links in `files`' Markdown (those the config's `links.include`
+ * takes), as DOC-DRIFT-01 problems. A finding stays out when its line carries
+ * the exemption marker, its target is a placeholder, or the repository's
+ * ignore rules cover the target.
+ */
+export const findLinkProblems = (config, snapshot, files, run) => {
+    const include = config.links?.include;
+    if (include === undefined)
+        return [];
+    const docs = files.filter((file) => include.test(file));
+    if (docs.length === 0)
+        return [];
+    const tree = treeFor(snapshot);
+    let findings;
+    try {
+        // Parsed while the tree stands: its targets are named from tree.dir.
+        findings = parseLycheeReport(run(tree.dir, docs), tree.dir);
+    }
+    finally {
+        tree.release();
+    }
+    const asked = new Set(docs);
+    const kept = findings.filter((finding) => {
+        if (!asked.has(finding.file))
+            return false;
+        const text = snapshot.read(finding.file)?.split('\n')[finding.line - 1];
+        if (text !== undefined && config.exemptMarker.test(text))
+            return false;
+        return !config.placeholder.test(finding.ref);
+    });
+    const targetOf = (finding) => {
+        const path = finding.ref.replace(/#.*$/, '');
+        return path === '' ? null : normalizeRepoPath(posix.join(posix.dirname(finding.file), path));
+    };
+    const targets = kept.flatMap((finding) => {
+        const target = targetOf(finding);
+        return target === null ? [] : [target, `${target}/`];
+    });
+    const ignored = snapshot.ignored([...new Set(targets)]);
+    return kept
+        .filter((finding) => {
+        const target = targetOf(finding);
+        return target === null || (!ignored.has(target) && !ignored.has(`${target}/`));
+    })
+        .map((finding) => ({ check: 'DOC-DRIFT-01', file: finding.file, line: finding.line, ref: finding.ref, reason: finding.reason }));
+};