Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

18.6 KB
Raw Blame
import {
  isReLintFailedWarning,
  isReLintFailureReason,
  type LintFixResult,
  RE_LINT_FAILED_WARNING_PREFIX,
  type ReLintFailure,
  ReLintFailureSchema,
  validationCoverageLines,
} from '@inkeep/open-knowledge-core';
import { z } from 'zod';
import type { AgentIdentity } from '../agent-identity.ts';
import type { ConfigOrResolver, ServerInstance, ServerUrlOrResolver } from './shared.ts';
import {
  AUDIT_FILE_CAP,
  AUDIT_FILE_DIAGNOSTIC_CAP,
  agentIdentityFields,
  capAuditWarnings,
  countSummary,
  degradationBlock,
  errorTextWithDetail,
  formatDiagnosticLine,
  hocuspocusNotRunningError,
  httpGet,
  httpPost,
  looseObjectArray,
  normalizeDocName,
  outputSchemaWithText,
  ROUTED_CWD_DESCRIPTION,
  resolveProjectServerContext,
  textPlusStructured,
  textResult,
  zeroFindingsSummary,
} from './shared.ts';
import {
  failedWriteResult,
  landedLead,
  landedWithoutSuccess,
  needsAttention,
  refusedDespiteSuccess,
  refusedWriteResult,
  writeOutcomeFields,
  writeOutcomeLine,
  writeOutcomeOf,
  writeOutcomeOutputShape,
} from './write-outcome.ts';

export const DESCRIPTION = [
  "Lint markdown and optionally auto-fix. Requires the Hocuspocus server. `document` selects one extension-less doc and overrides path. Otherwise scan all in-scope .md/.mdx; path narrows to file/folder. `fix: true` requires document and applies fixable rules through the live collaborative doc with attribution. Use edit/write for remaining findings; the OpenKnowledge CLI's lint --fix is the unattributed headless/CI path.",
  'ran lists selected `markdownlint`, `frontmatter` and document-level `okf` families. A family absent from `ran` was not checked. Project-tree OKF checks and link validation run only through audit.',
  'Findings carry source, code, message, 0-based LSP range and severity; only problematic files are listed. Counts reflect the full scan. Project output is capped at 10 files × 10 diagnostics each and project-wide at 10 warnings; omittedWarningCount reports dropped warnings. Narrow path reduces competing files; per-file caps still apply. Follow truncation recovery text.',
  'Configure lint in Settings → Plugins and native .markdownlint.* rules.',
  'If a project-wide scan times out, narrow `path` to a file or folder and retry.',
].join('\n');

export const LINT_WARNINGS_DESCRIPTION =
  'Anything that made this run less than a full answer: unreadable files/dirs (audit), lint-config problems such as a broken frontmatter schema file, and selected lint plugins that threw. A source family named here is still listed in `ran`: it was selected, it just could not finish. In fix mode this array carries the plugin failures from BOTH lint passes, so a post-write re-lint failure can appear here as the failing plugin, but never as the `Re-lint after fix failed: ` entry an older server sends, which is filtered out. The prose explanation is in `reLintFailure.message`, its machine-readable discriminant in `reLintFailure.reason`, and `diagnosticsArePreFix` is the flag to branch on.';

const DIAGNOSTICS_ARE_PRE_FIX_DESCRIPTION =
  'Fix mode only. Present and true when the server flags pre-fix diagnostics, supplies `reLintFailure`, or reports a legacy re-lint-failure warning; absent when none of those signals is present. The reported `files[].diagnostics` and their `errorCount`/`warningCount` describe the pre-fix set and may overstate what remains. Treat the fix as applied and re-run `lint` to confirm. A non-empty explanation, when available, is in `reLintFailure.message`, and `reLintFailure.reason` says which of the two failure shapes it was.';

function singleDocFixHint(fixableCount: number, total: number): string {
  if (fixableCount === 0) {
    return 'None are auto-fixable — these need content edits via `edit`/`write`.';
  }
  const remaining = total - fixableCount;
  const remainder =
    remaining > 0 ? ` The other ${remaining} need content edits via \`edit\`/\`write\`.` : '';
  return `${fixableCount} of ${total} are auto-fixable — pass \`fix: true\` to apply in place (attributed, live preview).${remainder}`;
}

const AUDIT_FIX_HINT =
  'Auto-fix a single file with `lint({ document, fix: true })` (attributed, live preview). Violations that resist auto-fix need content edits.';

interface LintPositionPayload {
  line?: number;
  character?: number;
}

interface LintTextEditPayload {
  range?: { start?: LintPositionPayload; end?: LintPositionPayload };
  newText?: string;
}

interface LintDiagnosticPayload {
  source?: string;
  code?: string;
  message?: string;
  severity?: string;
  range?: { start?: LintPositionPayload; end?: LintPositionPayload };
  fixes?: LintTextEditPayload[];
}

interface LintDocPayload {
  file?: string;
  diagnostics?: LintDiagnosticPayload[];
  warnings?: string[];
  ran?: string[];
}

type LintFixPayload = Omit<Partial<LintFixResult>, 'diagnostics'> & {
  diagnostics?: LintDiagnosticPayload[];
};

interface LintAuditPayload {
  files?: LintDocPayload[];
  fileCount?: number;
  errorCount?: number;
  warningCount?: number;
  warnings?: string[];
  ran?: string[];
}

export interface LintDeps {
  serverUrl: ServerUrlOrResolver;
  config: ConfigOrResolver;
  resolveCwd: (explicit?: string) => Promise<string>;
  identityRef?: { current: AgentIdentity };
}

interface LintArgs {
  document?: string;
  path?: string;
  fix?: boolean;
  cwd?: string;
}

export function register(server: ServerInstance, deps: LintDeps): void {
  server.registerTool(
    'lint',
    {
      description: DESCRIPTION,
      inputSchema: {
        document: z
          .string()
          .optional()
          .describe('Doc to lint (path, extension-less). Omit to audit the whole project.'),
        path: z
          .string()
          .optional()
          .describe(
            'Audit scope when `document` is omitted: a folder or single file (content-dir-relative). Default: the whole project.',
          ),
        fix: z
          .boolean()
          .optional()
          .describe(
            'Auto-fix fixable rules in `document` IN PLACE (attributed, live preview), then report what remains. Requires `document`.',
          ),
        cwd: z.string().optional().describe(ROUTED_CWD_DESCRIPTION),
      },
      outputSchema: outputSchemaWithText({
        ...writeOutcomeOutputShape,
        files: looseObjectArray
          .optional()
          .describe(
            'Per-file diagnostics. For a single-doc lint, the one file (even if clean). Pre-fix, and so possibly an overstatement, when `diagnosticsArePreFix` is true.',
          ),
        fileCount: z.number().optional().describe('Audit only: total in-scope documents scanned.'),
        errorCount: z
          .number()
          .optional()
          .describe(
            'Total error-severity violations. Pre-fix, and so possibly an overstatement, when `diagnosticsArePreFix` is true.',
          ),
        warningCount: z
          .number()
          .optional()
          .describe(
            'Total warning-severity violations. Pre-fix, and so possibly an overstatement, when `diagnosticsArePreFix` is true.',
          ),
        warnings: z.array(z.string()).optional().describe(LINT_WARNINGS_DESCRIPTION),
        diagnosticsArePreFix: z.boolean().optional().describe(DIAGNOSTICS_ARE_PRE_FIX_DESCRIPTION),
        reLintFailure: ReLintFailureSchema.optional().describe(
          'Fix mode only: why the post-write re-lint could not report. `reason` is the machine-readable discriminant — `re-lint-threw` when the re-lint pass itself threw, `source-went-blind` when a lint source that read the pre-fix text failed on the post-fix text — and `message` is the trimmed, non-empty prose, normalized from the server’s typed failure or a legacy prefixed warning. When present, `diagnosticsArePreFix` is true; that flag can also be present without a failure.',
        ),
        ran: z
          .array(z.string())
          .optional()
          .describe(
            'Lint source families selected for this run. A family absent from `ran` was not checked.',
          ),
        omittedWarningCount: z
          .number()
          .optional()
          .describe('Audit only: warnings omitted from `warnings` by the output cap.'),
        omittedFileCount: z
          .number()
          .optional()
          .describe('Audit only: files with problems omitted from `files` by the output cap.'),
        fixedCount: z
          .number()
          .optional()
          .describe(
            'Fix mode only: the server-reported number of problems resolved by auto-fix, or 0 if omitted. When `diagnosticsArePreFix` is true, the post-fix result is unavailable; do not treat 0 as evidence that nothing was fixed.',
          ),
        cwd: z
          .string()
          .optional()
          .describe('Absolute directory the lint ran against; absent when a fix did not land.'),
      }),
      annotations: {
        readOnlyHint: false,
        destructiveHint: false,
        idempotentHint: true,
      },
    },
    async (args: LintArgs, { signal }) => {
      const context = await resolveProjectServerContext(
        deps.resolveCwd,
        deps.config,
        deps.serverUrl,
        args.cwd,
      );
      if (!context.ok) return textResult(`Error: ${context.error}`, true);
      const { cwd, url } = context;
      if (!url) return textResult(hocuspocusNotRunningError(), true);

      if (args.fix === true) {
        if (args.document === undefined) {
          return textResult(
            'Error: `fix: true` requires `document` (fix one doc at a time). Omit `fix` to audit the whole project.',
            true,
          );
        }
        return fixLintDoc(args.document, url, cwd, deps.identityRef?.current);
      }

      return args.document !== undefined
        ? lintSingleDoc(args.document, url, cwd)
        : lintAudit(args.path, url, cwd, signal);
    },
  );
}

async function fixLintDoc(
  document: string,
  url: string,
  cwd: string,
  identity: AgentIdentity | undefined,
) {
  const normalized = normalizeDocName(document);
  if (!normalized.ok) return textResult(normalized.error, true);
  const result = await httpPost(url, '/api/lint/fix', {
    docName: normalized.docName,
    ...agentIdentityFields(identity),
  });
  const outcome = writeOutcomeOf(result);
  if (!result.ok) return failedWriteResult(errorTextWithDetail(result), outcome);
  if (refusedDespiteSuccess(outcome)) {
    return refusedWriteResult(`The auto-fix of ${normalized.docName}`, outcome);
  }
  const { ok: _ok, ...rest } = result;
  const data = rest as LintFixPayload;
  const file = data.file ?? normalized.docName;
  const diagnostics = data.diagnostics ?? [];
  const fixedCount = data.fixedCount ?? 0;
  const errorCount = diagnostics.filter((d) => d.severity === 'error').length;
  const warningCount = diagnostics.length - errorCount;
  const legacyReLintWarning =
    typeof (rest as { warning?: unknown }).warning === 'string' &&
    isReLintFailedWarning((rest as { warning: string }).warning)
      ? (rest as { warning: string }).warning
      : undefined;
  const responseWarnings = [
    ...(data.warnings ?? []),
    ...(legacyReLintWarning === undefined ? [] : [legacyReLintWarning]),
  ];
  const legacyPrefixedWarning = responseWarnings.find(isReLintFailedWarning);
  const warnings = responseWarnings.filter((warning) => !isReLintFailedWarning(warning));
  const diagnosticsArePreFix =
    data.diagnosticsArePreFix === true ||
    data.reLintFailure !== undefined ||
    legacyPrefixedWarning !== undefined;
  const typedMessage =
    typeof data.reLintFailure?.message === 'string' ? data.reLintFailure.message.trim() : '';
  const typedFailure: ReLintFailure | undefined = typedMessage
    ? {
        reason: isReLintFailureReason(data.reLintFailure?.reason)
          ? data.reLintFailure.reason
          : 're-lint-threw',
        message: typedMessage,
      }
    : undefined;
  const legacyMessage = legacyPrefixedWarning?.slice(RE_LINT_FAILED_WARNING_PREFIX.length).trim();
  const reLintFailure: ReLintFailure | undefined =
    typedFailure ??
    (legacyMessage ? { reason: 're-lint-threw' as const, message: legacyMessage } : undefined);
  const reLintCause = reLintFailure ? ` (${reLintFailure.message})` : '';
  const coverageLines = validationCoverageLines(data.ran);
  const structured = {
    files: [{ file, diagnostics }],
    fixedCount,
    errorCount,
    warningCount,
    ...(warnings.length > 0 ? { warnings } : {}),
    ...(diagnosticsArePreFix ? { diagnosticsArePreFix: true } : {}),
    ...(reLintFailure ? { reLintFailure } : {}),
    ...(data.ran === undefined ? {} : { ran: data.ran }),
    cwd,
    ...writeOutcomeFields(outcome),
  };

  const header = diagnosticsArePreFix
    ? `Applied auto-fixes to ${file}, but re-lint failed${reLintCause}; the fix landed — problems below are the pre-fix set, re-run \`lint\` to confirm.`
    : fixedCount > 0
      ? `Fixed ${fixedCount} problem${fixedCount === 1 ? '' : 's'} in ${file}.`
      : warnings.length > 0
        ? `No auto-fixable problems in ${file}, but the lint could not fully complete.`
        : `No auto-fixable problems in ${file}.`;
  const lines = diagnostics.map(formatDiagnosticLine);
  const warningBlock = degradationBlock('Lint', warnings);
  const footer =
    diagnostics.length > 0 && !diagnosticsArePreFix
      ? [
          `${diagnostics.length} problem${diagnostics.length === 1 ? '' : 's'} remain (${countSummary(errorCount, warningCount)}) — need content edits via \`edit\`/\`write\`.`,
        ]
      : [];
  const outcomeLine =
    outcome === undefined || outcome.outcome === 'applied' ? [] : [writeOutcomeLine(outcome) ?? ''];
  const landedLine =
    outcome !== undefined && landedWithoutSuccess(outcome)
      ? [landedLead(outcome, `Applied auto-fixes to ${file}`)]
      : [];
  const textLines =
    diagnostics.length === 0
      ? [...landedLine, header, ...outcomeLine, ...coverageLines, ...warningBlock]
      : [
          ...landedLine,
          header,
          ...outcomeLine,
          ...lines,
          ...warningBlock,
          ...footer,
          ...coverageLines,
        ];
  return textPlusStructured(textLines.join('\n'), structured, needsAttention(outcome));
}

async function lintSingleDoc(document: string, url: string, cwd: string) {
  const normalized = normalizeDocName(document);
  if (!normalized.ok) return textResult(normalized.error, true);
  const result = await httpGet(url, `/api/lint?doc=${encodeURIComponent(normalized.docName)}`);
  if (!result.ok) return textResult(`Error: ${String(result.error)}`, true);
  const { ok: _ok, ...rest } = result;
  const data = rest as LintDocPayload;
  const diagnostics = data.diagnostics ?? [];
  const configWarnings = data.warnings ?? [];
  const errorCount = diagnostics.filter((d) => d.severity === 'error').length;
  const warningCount = diagnostics.length - errorCount;
  const coverageLines = validationCoverageLines(data.ran);
  const file = { file: data.file ?? normalized.docName, diagnostics };
  const structured = {
    files: [file],
    errorCount,
    warningCount,
    ...(configWarnings.length > 0 ? { warnings: configWarnings } : {}),
    ...(data.ran === undefined ? {} : { ran: data.ran }),
    cwd,
  };

  const header =
    diagnostics.length > 0
      ? `${file.file}: ${countSummary(errorCount, warningCount)}`
      : configWarnings.length > 0
        ? `No problems found in ${file.file}, but the lint could not fully complete.`
        : `No problems in ${file.file}.`;
  const lines = diagnostics.map(formatDiagnosticLine);
  const warningBlock = degradationBlock('Lint', configWarnings);
  const fixableCount = diagnostics.filter((d) => (d.fixes?.length ?? 0) > 0).length;
  const footer = diagnostics.length > 0 ? [singleDocFixHint(fixableCount, diagnostics.length)] : [];
  const textLines =
    diagnostics.length === 0
      ? [header, ...coverageLines, ...warningBlock]
      : [header, ...lines, ...warningBlock, ...footer, ...coverageLines];
  return textPlusStructured(textLines.join('\n'), structured);
}

async function lintAudit(path: string | undefined, url: string, cwd: string, signal: AbortSignal) {
  const query = path ? `?path=${encodeURIComponent(path)}` : '';
  const result = await httpGet(url, `/api/lint/audit${query}`, signal);
  if (!result.ok) return textResult(`Error: ${String(result.error)}`, true);
  const { ok: _ok, ...rest } = result;
  const data = rest as LintAuditPayload;
  const files = data.files ?? [];
  const fileCount = data.fileCount ?? 0;
  const errorCount = data.errorCount ?? 0;
  const warningCount = data.warningCount ?? 0;
  const coverageLines = validationCoverageLines(data.ran, fileCount);

  const shownFiles = files.slice(0, AUDIT_FILE_CAP).map((file) => {
    const diagnostics = file.diagnostics ?? [];
    const shown = diagnostics.slice(0, AUDIT_FILE_DIAGNOSTIC_CAP);
    const omitted = diagnostics.length - shown.length;
    return {
      ...file,
      diagnostics: shown,
      ...(omitted > 0 ? { omittedDiagnosticCount: omitted } : {}),
    };
  });
  const omittedFileCount = files.length - shownFiles.length;

  const warnings = data.warnings ?? [];
  const { shownWarnings, omittedWarningCount } = capAuditWarnings(warnings);

  const structured = {
    files: shownFiles,
    fileCount,
    errorCount,
    warningCount,
    ...(shownWarnings.length > 0 ? { warnings: shownWarnings } : {}),
    ...(omittedWarningCount > 0 ? { omittedWarningCount } : {}),
    ...(data.ran === undefined ? {} : { ran: data.ran }),
    ...(omittedFileCount > 0 ? { omittedFileCount } : {}),
    cwd,
  };

  const scope = path ? ` in ${path}` : '';
  const warningBlock = degradationBlock('Lint', shownWarnings, omittedWarningCount);
  if (files.length === 0) {
    const summary = zeroFindingsSummary('Lint', fileCount, warnings, scope);
    return textPlusStructured([summary, ...coverageLines, ...warningBlock].join('\n'), structured);
  }
  const header = `${files.length} of ${fileCount} document${fileCount === 1 ? '' : 's'}${scope} with problems — ${countSummary(errorCount, warningCount)}:`;
  const fileBlocks = shownFiles.map((file) => {
    const lines = file.diagnostics.map(formatDiagnosticLine);
    if (file.omittedDiagnosticCount !== undefined) {
      lines.push(
        `  … and ${file.omittedDiagnosticCount} more problem${file.omittedDiagnosticCount === 1 ? '' : 's'}; use lint({ document: ${JSON.stringify(file.file)} }) for all document lint findings.`,
      );
    }
    return [`${file.file ?? '(unknown)'}:`, ...lines].join('\n');
  });
  const footer =
    omittedFileCount > 0
      ? [
          `… and ${omittedFileCount} more file${omittedFileCount === 1 ? '' : 's'} with problems. Narrow path to reduce competing files; per-file caps still apply.`,
        ]
      : [];
  return textPlusStructured(
    [header, ...fileBlocks, ...footer, ...warningBlock, AUDIT_FIX_HINT, ...coverageLines].join(
      '\n',
    ),
    structured,
  );
}