@open-agent-toolkit/cli 0.3.32 → 0.3.34

package/assets/skills/oat-docs-analyze/scripts/package-drift.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
-// Read-only, offline comparison used by oat-docs-analyze. No package resolution or install.
-import { open, readFile, realpath } from 'node:fs/promises';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
+// Read-only, offline comparison used by oat-docs-analyze. It reads installed
+// package manifests the way Node resolves packages (the app's node_modules,
+// then each ancestor's) and never installs, fetches or executes anything.
+import { access, open, readFile, realpath } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { parseArgs } from 'node:util';
 
 const shellQuote = (value) =>
@@ -75,6 +77,248 @@ async function versionsForCli(executable) {
   );
 }
 
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return false;
+    throw error;
+  }
+}
+
+async function readJson(path) {
+  try {
+    return JSON.parse(await readFile(path, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null;
+    throw error;
+  }
+}
+
+function ancestors(directory) {
+  const list = [];
+  for (let current = directory; ; current = dirname(current)) {
+    list.push(current);
+    if (dirname(current) === current) return list;
+  }
+}
+
+// Node package lookup: <dir>/node_modules/<name> from the app upward, so
+// hoisted installs (pnpm node-linker=hoisted, npm/yarn workspaces) resolve.
+async function installedManifest(appPath, name) {
+  for (const directory of ancestors(appPath)) {
+    const path = join(directory, 'node_modules', name, 'package.json');
+    const manifest = await readJson(path);
+    if (manifest !== null) return { path, manifest };
+  }
+  return null;
+}
+
+// The app's own packageManager wins, then the nearest ancestor's.
+async function packageManagerFor(appPath) {
+  for (const directory of ancestors(appPath)) {
+    const manifest = await readJson(join(directory, 'package.json'));
+    if (typeof manifest?.packageManager === 'string')
+      return manifest.packageManager.trim();
+  }
+  return null;
+}
+
+// Remove a YAML comment: `#` at line start or after whitespace, outside quotes.
+function stripYamlComment(line) {
+  let quote = null;
+  for (let index = 0; index < line.length; index += 1) {
+    const char = line[index];
+    if (quote) {
+      if (char === quote) quote = null;
+    } else if (char === '"' || char === "'") quote = char;
+    else if (char === '#' && (index === 0 || /\s/.test(line[index - 1])))
+      return line.slice(0, index);
+  }
+  return line;
+}
+
+function unquoteYaml(value) {
+  const text = value.trim();
+  if (text.length >= 2 && text.startsWith("'") && text.endsWith("'"))
+    return text.slice(1, -1).replaceAll("''", "'");
+  if (text.length >= 2 && text.startsWith('"') && text.endsWith('"')) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text.slice(1, -1);
+    }
+  }
+  return text;
+}
+
+// Split a flow sequence body on commas outside quotes and braces.
+function splitFlowItems(body) {
+  const items = [];
+  let quote = null;
+  let depth = 0;
+  let current = '';
+  for (const char of body) {
+    if (quote) {
+      if (char === quote) quote = null;
+    } else if (char === '"' || char === "'") quote = char;
+    else if (char === '{') depth += 1;
+    else if (char === '}') depth -= 1;
+    else if (char === ',' && depth === 0) {
+      items.push(current);
+      current = '';
+      continue;
+    }
+    current += char;
+  }
+  items.push(current);
+  return items;
+}
+
+// The `packages` list of a pnpm-workspace.yaml: an indented or unindented
+// block sequence or a flow sequence, with quotes and comments. A file
+// without `packages` (settings only) declares no member packages.
+function workspacePatterns(text) {
+  const lines = text.split(/\r?\n/).map(stripYamlComment);
+  const start = lines.findIndex((line) => /^packages\s*:/.test(line));
+  if (start < 0) return [];
+  const inline = lines[start].replace(/^packages\s*:/, '').trim();
+  if (inline.startsWith('[')) {
+    let flow = inline;
+    for (
+      let index = start + 1;
+      !flow.includes(']') && index < lines.length;
+      index += 1
+    )
+      flow += ` ${lines[index].trim()}`;
+    return splitFlowItems(flow.slice(1, flow.lastIndexOf(']')))
+      .map(unquoteYaml)
+      .filter((entry) => entry.length > 0);
+  }
+  const patterns = [];
+  for (const line of lines.slice(start + 1)) {
+    if (line.trim() === '') continue;
+    const item = line.match(/^\s*-\s*(.*)$/);
+    if (!item) break;
+    patterns.push(unquoteYaml(item[1]));
+  }
+  return patterns.filter((entry) => entry.length > 0);
+}
+
+// Expand `{a,b}` alternatives, innermost first.
+function expandBraces(pattern) {
+  const match = pattern.match(/\{([^{}]*)\}/);
+  if (!match) return [pattern];
+  return match[1]
+    .split(',')
+    .flatMap((alternative) =>
+      expandBraces(
+        pattern.slice(0, match.index) +
+          alternative +
+          pattern.slice(match.index + match[0].length),
+      ),
+    );
+}
+
+// Glob syntax evaluated here: `*`, `**`, `?`, braces (expanded first) and
+// positive character classes. Extglobs, negated classes, escapes and
+// unbalanced brackets are not, and never count as a non-match.
+function unsupportedGlob(pattern) {
+  return (
+    /[+@!?*]\(/.test(pattern) ||
+    /\[[!^]/.test(pattern) ||
+    pattern.includes('\\') ||
+    /\[(?![^\]]*\])/.test(pattern) ||
+    /\[\]/.test(pattern)
+  );
+}
+
+function globToRegExp(pattern) {
+  const source = pattern
+    .split(/(\*\*\/|\*\*|\*|\?|\[[^\]]+\])/)
+    .map((part) =>
+      part === '**/'
+        ? '(?:.*/)?'
+        : part === '**'
+          ? '.*'
+          : part === '*'
+            ? '[^/]*'
+            : part === '?'
+              ? '[^/]'
+              : part.startsWith('[') && part.endsWith(']')
+                ? `(?!/)[${part.slice(1, -1).replace(/[\\\]]/g, '\\$&')}]`
+                : part.replace(/[.+^${}()|[\]\\]/g, '\\$&'),
+    )
+    .join('');
+  return new RegExp(`^${source}$`);
+}
+
+// pnpm finds members by globbing `<pattern>/package.json`, so a trailing
+// globstar also matches the directory itself; negations exclude. Returns
+// true or false, or `{ unsupported: pattern }` when a pattern whose result
+// matters cannot be evaluated.
+function workspaceIncludes(patterns, rel) {
+  const target = `${rel}/package.json`;
+  const evaluate = (pattern) => {
+    const expanded = expandBraces(
+      pattern.replace(/^\.\//, '').replace(/\/+$/, ''),
+    );
+    if (expanded.some(unsupportedGlob)) return { unsupported: pattern };
+    return expanded.some((glob) =>
+      globToRegExp(`${glob}/package.json`).test(target),
+    );
+  };
+  const any = (list) => {
+    let unknown = null;
+    for (const pattern of list) {
+      const result = evaluate(pattern);
+      if (result === true) return true;
+      if (result !== false && unknown === null) unknown = result;
+    }
+    return unknown ?? false;
+  };
+  const included = any(patterns.filter((pattern) => !pattern.startsWith('!')));
+  if (included !== true) return included;
+  const excluded = any(
+    patterns
+      .filter((pattern) => pattern.startsWith('!'))
+      .map((pattern) => pattern.slice(1)),
+  );
+  return excluded === true ? false : excluded === false ? true : excluded;
+}
+
+// The app's relation to the nearest pnpm workspace: its own root, a member of
+// an ancestor workspace, standalone (the ancestor's `packages` globs exclude
+// it, so installs need --ignore-workspace), or undetermined when a pattern
+// cannot be evaluated. Lockfile presence is not evidence: a member can keep
+// its own lockfile with shared-workspace-lockfile=false.
+async function workspaceMembership(appPath) {
+  if (await exists(join(appPath, 'pnpm-workspace.yaml')))
+    return { root: appPath, membership: 'root', reason: null };
+  for (const directory of ancestors(dirname(appPath))) {
+    const file = join(directory, 'pnpm-workspace.yaml');
+    if (!(await exists(file))) continue;
+    const rel = relative(directory, appPath).split(sep).join('/');
+    const included = workspaceIncludes(
+      workspacePatterns(await readFile(file, 'utf8')),
+      rel,
+    );
+    if (typeof included === 'boolean')
+      return {
+        root: directory,
+        membership: included ? 'member' : 'standalone',
+        reason: null,
+      };
+    return {
+      root: directory,
+      membership: 'undetermined',
+      reason: `pnpm-workspace.yaml pattern "${included.unsupported}" uses glob syntax this helper does not evaluate; workspace membership is unknown, so the command omits --ignore-workspace. Confirm membership with pnpm -r ls before running it.`,
+    };
+  }
+  return { root: null, membership: null, reason: null };
+}
+
 try {
   const { values } = parseArgs({
     options: {
@@ -84,14 +328,46 @@ try {
     },
   });
   if (!values.app) throw new Error('Required: --app <docs-app-directory>.');
+  const appPath = resolve(values.app);
+  const manifest = await readJson(join(appPath, 'package.json'));
+  if (manifest === null) {
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          versionsPath: null,
+          appPath,
+          applicable: false,
+          reason:
+            'No package.json in the docs directory: Markdown docs have no app-package drift check.',
+          packages: [],
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    process.exit(0);
+  }
   const versionsPath = resolve(
     values.versions ?? (await versionsForCli(values.cli)),
   );
   const versions = JSON.parse(await readFile(versionsPath, 'utf8'));
-  const appPath = resolve(values.app);
-  const manifest = JSON.parse(
-    await readFile(join(appPath, 'package.json'), 'utf8'),
+  const packageManager = await packageManagerFor(appPath);
+  const pinned = packageManager?.match(
+    /^pnpm@(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)(?:\+.*)?$/,
   );
+  // Run the repository's pinned pnpm rather than whatever global pnpm is on
+  // PATH: a different major can rewrite workspace settings or reject the store.
+  // npx ships with npm on every Node line; Corepack is absent from Node 25+.
+  const pnpm = pinned ? `npx --yes pnpm@${pinned[1]}` : 'pnpm';
+  const otherManager =
+    packageManager && !packageManager.startsWith('pnpm@')
+      ? packageManager
+      : null;
+  // A nested app the ancestor workspace does not include must be installed
+  // with --ignore-workspace; an undetermined result never adds the flag.
+  const workspace = await workspaceMembership(appPath);
+  const ignoreWorkspace =
+    workspace.membership === 'standalone' ? ' --ignore-workspace' : '';
   const packages = [];
   for (const section of [
     'dependencies',
@@ -116,29 +392,22 @@ try {
       )
         throw new Error(`Missing/invalid bundled version for ${name}.`);
       // Report installed package bytes when available, not just a declared range.
-      let installed = null;
-      try {
-        const installedManifest = JSON.parse(
-          await readFile(
-            join(appPath, 'node_modules', name, 'package.json'),
-            'utf8',
-          ),
-        );
-        if (typeof installedManifest.version !== 'string')
-          throw new Error(`Invalid installed version for ${name}.`);
-        installed = installedManifest.version;
-      } catch (error) {
-        if (error.code !== 'ENOENT') throw error;
-      }
+      const found = await installedManifest(appPath, name);
+      if (found !== null && typeof found.manifest.version !== 'string')
+        throw new Error(`Invalid installed version for ${name}.`);
+      const installed = found?.manifest.version ?? null;
       // Only stable numeric releases are orderable here; prereleases and other
       // package-manager version forms need manual verification, never an upgrade.
       const stable = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
       let status = 'unverified';
-      if (
-        installed !== null &&
-        stable.test(installed) &&
-        stable.test(bundled)
-      ) {
+      let reason = null;
+      if (installed === null)
+        reason = `not installed: no node_modules/${name} found from the app or its ancestors; run the app install first`;
+      else if (!stable.test(installed))
+        reason = `installed version ${installed} is not a stable release; verify it manually`;
+      else if (!stable.test(bundled))
+        reason = `bundled version ${bundled} is a prerelease; verify it manually`;
+      else {
         const left = installed.split('.').map(BigInt);
         const right = bundled.split('.').map(BigInt);
         const differing = left.findIndex(
@@ -151,22 +420,26 @@ try {
               ? 'drift'
               : 'ahead';
       }
+      let upgradeCommand = null;
+      if (status === 'drift' && otherManager)
+        reason = `packageManager is ${otherManager}; translate the upgrade to its add command, preserving the dependency section and exact version`;
+      else if (status === 'drift')
+        upgradeCommand = `${pnpm} --dir ${shellQuote(appPath)} add${ignoreWorkspace}${section === 'devDependencies' ? ' --save-dev' : section === 'optionalDependencies' ? ' --save-optional' : ''} ${name}@${bundled}`;
       packages.push({
         name,
         section,
         declared,
         installed,
+        installedPath: found?.path ?? null,
         bundled,
         status,
-        upgradeCommand:
-          status === 'drift' || status === 'current'
-            ? `pnpm --dir ${shellQuote(appPath)} add${section === 'devDependencies' ? ' --save-dev' : section === 'optionalDependencies' ? ' --save-optional' : ''} ${name}@${bundled}`
-            : null,
+        reason,
+        upgradeCommand,
       });
     }
   }
   process.stdout.write(
-    `${JSON.stringify({ versionsPath, appPath, packages }, null, 2)}\n`,
+    `${JSON.stringify({ versionsPath, appPath, applicable: true, packageManager, workspace, packages }, null, 2)}\n`,
   );
 } catch (error) {
   process.stderr.write(`${error.message}\n`);

package/assets/skills/oat-docs-apply/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash(git:*), Bash(gh:*), Bash(oat:*), Bash(pnpm:*), Bash(bash:*), Bash(jq:*), Bash(mkdir:*), Bash(date:*), Bash(echo:*), Bash(cd:*), Bash(pwd:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: '1.4.7'
+  version: '1.4.8'
 ---
 
 # Docs Apply
@@ -324,6 +324,8 @@ approval, its out-of-Markdown allowance is only these four operations:
    app's own `@open-agent-toolkit/cli` dependency when the app declares it, to the
    bundled versions using the artifact's exact upgrade commands (preserve each
    dependency section and the package manager; include the resulting lockfile only).
+   Run the pinned package-manager form the command gives; a global pnpm of another
+   major can rewrite workspace settings and break the store link.
    Never downgrade an installed version: `ahead` or `unverified` requires CLI
    selection/update or manual verification before re-analysis, not a tooling update.
 2. After a CLI bump, regenerate the app's generated manifest (`index.md`) with that

package/assets/skills/oat-docs-authoring/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 user-invocable: true
 metadata:
-  version: '1.2.1'
+  version: '1.2.2'
 ---
 
 # OAT Docs Authoring

package/assets/skills/oat-docs-authoring/references/oat-fumadocs-contract.md

@@ -29,7 +29,12 @@ Use file-path-friendly relative Markdown links:
 - child directory: `[Section](section/index.md)`;
 - avoid extensionless local docs links for new authored navigation entries;
 - preserve anchors only when the target heading exists and the local renderer
-  supports the anchor.
+  supports the anchor;
+- index-only leaf (its `index.md` is the directory's only reader page and it
+  has no child sections): may list same-page heading anchors such as `[Setup](#setup)` as an in-page table
+  of contents. They add no navigation entry, and `oat docs check` warns
+  (`leaf-size`) that the section could be flattened. Anywhere else a same-page
+  anchor in Contents is an error.
 
 Existing extensionless links are drift, not precedent. Normalize them only when
 the task scope or an approved recommendation covers that change.

package/dist/commands/config/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"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"}

package/dist/commands/config/index.js

@@ -77,6 +77,7 @@ const KEY_ORDER = [
     'documentation.root',
     'documentation.tooling',
     'documentation.config',
+    'documentation.index',
     'documentation.excludes',
     'documentation.requireForProjectCompletion',
     'explainers.defaults.style',
@@ -322,6 +323,17 @@ const CONFIG_CATALOG = [
         owningCommand: 'oat config set documentation.config <value>',
         description: 'Repository-relative path to the primary documentation tool config file.',
     },
+    {
+        key: 'documentation.index',
+        group: 'Shared Repo (.oat/config.json)',
+        file: '.oat/config.json',
+        scope: 'shared repo',
+        type: 'string',
+        defaultValue: 'unset',
+        mutability: 'read/write',
+        owningCommand: 'oat config set documentation.index <value>',
+        description: 'Repository-relative docs index path. Markdown: the authored root index.md. Fumadocs: the generated app-root manifest; MkDocs: mkdocs.yml. oat docs init writes it and oat docs generate-index updates the Fumadocs transition.',
+    },
     {
         key: 'documentation.nonReaderPaths',
         group: 'Shared Repo (.oat/config.json)',
@@ -330,7 +342,7 @@ const CONFIG_CATALOG = [
         type: 'string[]',
         defaultValue: 'unset',
         mutability: 'read/write',
-        owningCommand: 'oat config set documentation.nonReaderPaths <glob[,glob...]>',
+        owningCommand: 'oat config set documentation.nonReaderPaths <glob[,glob...]|JSON-array>',
         description: 'Content-root-relative globs excluded from reader navigation, manifest and supported framework rendering. Empty clears the key.',
     },
     {
@@ -341,7 +353,7 @@ const CONFIG_CATALOG = [
         type: 'string[]',
         defaultValue: 'unset',
         mutability: 'read/write',
-        owningCommand: 'oat config set documentation.excludes <glob[,glob...]>',
+        owningCommand: 'oat config set documentation.excludes <glob[,glob...]|JSON-array>',
         description: 'Comma-separated globs, relative to the docs directory, excluded from `oat docs generate-index`. Repeated `--exclude` flags extend this list; an empty value clears the key.',
     },
     {
@@ -1113,7 +1125,24 @@ function parseInstructionPointerExcludes(rawValue) {
     }
     return normalized;
 }
-function parseDocumentationExcludes(rawValue) {
+function parseDocumentationExcludes(rawValue, key) {
+    const trimmed = rawValue.trim();
+    // A glob list may be given as a JSON array (which also keeps braces such as
+    // `{a,b}` intact). Anything else that looks like JSON is a mistake, never a
+    // literal glob.
+    if (trimmed.startsWith('[') || trimmed.startsWith('{')) {
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            parsed = undefined;
+        }
+        if (!Array.isArray(parsed) ||
+            parsed.some((entry) => typeof entry !== 'string' || entry.trim().length === 0))
+            throw new Error(`Invalid ${key} value: a value starting with [ or { must be a JSON array of non-empty strings; otherwise use comma-separated globs.`);
+        return [...new Set(parsed.map((entry) => entry.trim()))];
+    }
     const parsed = rawValue
         .split(',')
         .map((entry) => entry.trim())
@@ -1853,7 +1882,7 @@ async function setConfigValue(repoRoot, userConfigDir, key, rawValue, surface, d
                 value = normalizeDocumentationCheck(parsed);
             }
             else if (key === 'documentation.nonReaderPaths') {
-                const paths = parseDocumentationExcludes(rawValue);
+                const paths = parseDocumentationExcludes(rawValue, 'documentation.nonReaderPaths');
                 value = paths.length > 0 ? paths : undefined;
             }
             else if (key === 'documentation.ia') {
@@ -1870,7 +1899,8 @@ async function setConfigValue(repoRoot, userConfigDir, key, rawValue, surface, d
             }
         }
         catch (error) {
-            if (key === 'documentation.check')
+            if (key === 'documentation.check' ||
+                key === 'documentation.nonReaderPaths')
                 throw error;
             if (error instanceof DocumentationIaPresetError)
                 throw new Error(`Invalid ${key} value: ${error.detail}.`, {
@@ -2106,8 +2136,11 @@ async function setConfigValue(repoRoot, userConfigDir, key, rawValue, surface, d
         else if (key === 'documentation.config') {
             doc.config = normalizeSharedRoot(rawValue);
         }
+        else if (key === 'documentation.index') {
+            doc.index = normalizeSharedRoot(rawValue);
+        }
         else if (key === 'documentation.excludes') {
-            const excludes = parseDocumentationExcludes(rawValue);
+            const excludes = parseDocumentationExcludes(rawValue, 'documentation.excludes');
             if (excludes.length === 0) {
                 // Unlike the scalar shared keys, an empty value is the documented way
                 // to clear this list rather than an error.
@@ -2265,9 +2298,9 @@ function withoutOwnKey(record, key) {
  *
  * Pruning is strictly "the object has no remaining own keys". That is what
  * keeps a prune from destroying a sibling the `oat config` catalog does not
- * expose — `documentation.index` is parsed by `config/oat-config.ts` but is
- * not a `ConfigKey`, so an unset of the last catalogued `documentation.*` key
- * leaves the parent in place while it is still present.
+ * expose (such as a key a newer CLI wrote): an unset of the last catalogued
+ * `documentation.*` key leaves the parent in place while any other key is
+ * still present.
  *
  * A missing path, a `null`/`undefined` leaf, or a non-object in the middle of
  * the path all report `removed: false`, which the caller surfaces as the

package/dist/commands/docs/check/check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/check.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,wBAAgB,sBAAsB,IAAI,OAAO,CA4DhD"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/check.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,wBAAgB,sBAAsB,IAAI,OAAO,CA6DhD"}

package/dist/commands/docs/check/check.js

@@ -15,6 +15,7 @@ export function createDocsCheckCommand() {
                 cwd: context.cwd,
                 targetDir: options.targetDir,
                 rules: options.rule,
+                onNotice: (message) => context.logger.warn(message),
             });
             process.exitCode = result.summary.errors ? 1 : 0;
         }

package/dist/commands/docs/check/checker.d.ts

@@ -4,5 +4,7 @@ export declare function checkDocs(options: {
     cwd: string;
     targetDir?: string;
     rules?: string[];
+    /** Receives human notices; they never enter the JSON result. */
+    onNotice?: (message: string) => void;
 }): Promise<DocsCheckResult>;
 //# sourceMappingURL=checker.d.ts.map

package/dist/commands/docs/check/checker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checker.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/checker.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAuB,MAAM,eAAe,CAAC;AAQ1E,gFAAgF;AAChF,wBAAsB,SAAS,CAAC,OAAO,EAAE;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,OAAO,CAAC,eAAe,CAAC,CAwF3B"}
+{"version":3,"file":"checker.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/checker.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAuB,MAAM,eAAe,CAAC;AAQ1E,gFAAgF;AAChF,wBAAsB,SAAS,CAAC,OAAO,EAAE;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC,GAAG,OAAO,CAAC,eAAe,CAAC,CAiG3B"}

package/dist/commands/docs/check/checker.js

@@ -11,6 +11,8 @@ export async function checkDocs(options) {
     if (unknown)
         throw new Error(`Unknown docs check rule "${unknown}". Choose: ${DOCS_CHECK_RULES.join(', ')}.`);
     const target = await resolveCheckTarget(options.cwd, options.targetDir);
+    for (const notice of target.notices)
+        options.onNotice?.(notice);
     const policy = target.documentation.check;
     const findings = [];
     const exceptions = policy?.exceptions?.map((e) => ({
@@ -53,7 +55,10 @@ export async function checkDocs(options) {
     await checkReaders(target, pages, report);
     checkProvenance(target, pages, report);
     if (!options.rules?.length || options.rules.includes('navigation'))
-        await checkNavigation(target, report);
+        await checkNavigation(target, report, (ruleId, path, line) => findings.some((f) => f.severity === 'error' &&
+            f.ruleId === ruleId &&
+            f.path === path &&
+            f.line === line));
     if (!options.rules?.length || options.rules.includes('commands'))
         await checkCommands(target, pages, report);
     if (!options.rules?.length ||

package/dist/commands/docs/check/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/commands.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAA0B,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAgI7C,wBAAsB,aAAa,CACjC,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU,EAAE,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAyJf"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/commands.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAA0B,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAgI7C,wBAAsB,aAAa,CACjC,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU,EAAE,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAkNf"}