Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

5.6 KB
Raw Blame
import { isAbsolute, relative, resolve, sep } from 'node:path';
import {
  clientVersionHeaders,
  currentCliCommandName,
  ProblemDetailsSchema,
  type ValidationAuditResponse,
  ValidationAuditResponseSchema,
} from '@inkeep/open-knowledge-core';
import {
  type Config,
  formatAuditBrokenLinkSuppressionLine,
  RUNTIME_VERSION,
  readServerLock,
  resolveAuditScope,
  resolveContentDir,
  resolveLockDir,
} from '@inkeep/open-knowledge-server';
import { Command } from 'commander';
import { z } from 'zod';
import { getInvocationCwd } from '../project-anchor.ts';
import { formatLintReport, type LintReportInput } from './lint.ts';

interface AuditOptions {
  json?: boolean;
  errorsOnly?: boolean;
}

interface AuditIo {
  out: (line: string) => void;
  err: (line: string) => void;
}

const defaultIo: AuditIo = {
  out: (line) => process.stdout.write(`${line}\n`),
  err: (line) => process.stderr.write(`${line}\n`),
};

const LegacyAuditErrorSchema = z.object({
  title: z.string().optional(),
  error: z.string().optional(),
  message: z.string().optional(),
});

function serverNotRunningMessage(): string {
  const command = currentCliCommandName();
  return (
    'OpenKnowledge server is not running — the links validator needs the live backlink index. ' +
    `Start it with \`${command} start\` (or open OK Desktop) and re-run. For headless lint-only checks, use \`${command} lint\`.`
  );
}

export function auditCommand(getConfig: () => Config): Command {
  return new Command('audit')
    .description(
      'Unified validation audit (markdown lint + broken internal links) via the running project server',
    )
    .argument('[path]', 'Folder or file to audit, relative to where you run the command')
    .option('--json', 'Emit the full structured JSON response instead of formatted text')
    .option(
      '--errors-only',
      "Exit non-zero only on error-severity problems (broken links default to warnings; the project's validation.links setting can raise them to errors)",
    )
    .action(async (path: string | undefined, opts: AuditOptions) => {
      const exitCode = await runAudit(path, opts, getConfig(), process.cwd(), getInvocationCwd());
      if (exitCode !== 0) process.exitCode = exitCode;
    });
}

export async function runAudit(
  path: string | undefined,
  opts: AuditOptions,
  config: Config,
  projectDir: string,
  invocationCwd: string,
  io: AuditIo = defaultIo,
): Promise<number> {
  const contentDir = resolveContentDir(config, projectDir);

  let target: string | undefined;
  if (path !== undefined) {
    const rel = toContentRelativeTarget(path, invocationCwd, contentDir);
    if (rel === null) {
      if (resolveAuditScope(undefined, contentDir).ok) {
        io.err(`Path is outside the content directory (${contentDir}): ${path}`);
        return 1;
      }
    } else {
      target = rel === '' ? undefined : rel;
    }
  }

  const lock = readServerLock(resolveLockDir(projectDir));
  if (!lock || lock.port <= 0) {
    io.err(serverNotRunningMessage());
    return 1;
  }

  const serverBaseUrl = `http://127.0.0.1:${lock.port}`;
  const query = target === undefined ? '' : `?path=${encodeURIComponent(target)}`;
  let res: Response;
  try {
    res = await fetch(`${serverBaseUrl}/api/audit${query}`, {
      headers: clientVersionHeaders({ kind: 'cli', runtimeVersion: RUNTIME_VERSION }),
    });
  } catch (e) {
    io.err(`Could not reach the OpenKnowledge server on port ${lock.port}: ${String(e)}`);
    return 1;
  }

  if (!res.ok) {
    const body: unknown = await res.json().catch(() => null);
    const problem = ProblemDetailsSchema.safeParse(body);
    if (problem.success) {
      if (opts.json === true) io.out(JSON.stringify(problem.data, null, 2));
      else io.err(`Audit failed: ${problem.data.title}`);
    } else {
      const legacy = LegacyAuditErrorSchema.safeParse(body);
      const message = legacy.success
        ? (legacy.data.title ?? legacy.data.error ?? legacy.data.message)
        : undefined;
      io.err(`Audit failed: ${message ?? `server responded with ${res.status}`}`);
    }
    return 1;
  }

  const parsed = ValidationAuditResponseSchema.safeParse(await res.json().catch(() => null));
  if (!parsed.success) {
    const summary = parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ');
    io.err(`Audit failed: unexpected response shape from the server. Schema issues: ${summary}`);
    return 1;
  }
  const result = parsed.data;

  if (opts.json === true) {
    io.out(JSON.stringify(result, null, 2));
  } else {
    const suppressionLine = result.brokenLinkSuppression
      ? formatAuditBrokenLinkSuppressionLine(result.brokenLinkSuppression, {
          surface: 'cli',
          serverBaseUrl,
        })
      : undefined;
    io.out(
      [
        formatLintReport(toReportInput(result)),
        ...(suppressionLine === undefined ? [] : [suppressionLine]),
      ].join('\n'),
    );
  }

  const failed =
    opts.errorsOnly === true ? result.errorCount > 0 : result.errorCount + result.warningCount > 0;
  return failed ? 1 : 0;
}

export function toContentRelativeTarget(
  path: string,
  invocationCwd: string,
  contentDir: string,
): string | null {
  const rel = relative(contentDir, resolve(invocationCwd, path));
  if (rel === '') return '';
  if (rel.startsWith('..') || isAbsolute(rel)) return null;
  return rel.split(sep).join('/');
}

function toReportInput(result: ValidationAuditResponse): LintReportInput {
  return {
    files: result.files.map((f) => ({ file: f.file, fixed: false, diagnostics: f.diagnostics })),
    warnings: result.warnings,
    fileCount: result.fileCount,
    errorCount: result.errorCount,
    warningCount: result.warningCount,
    fixedCount: 0,
    ran: result.ran,
  };
}