Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

47.9 KB
Raw Blame
// oxlint-disable ok/no-raw-error-toast -- pre-rule backlog: toasts here show raw error text; delete this line once the file maps each failure to written copy. See https://github.com/inkeep/open-knowledge/blob/main/lint-plugins/ok-rules/README.md#no-raw-error-toast
import type { ConfigBinding } from '@inkeep/open-knowledge-core/config/bind-config-doc';
import { humanFormat } from '@inkeep/open-knowledge-core/config/errors';
import type { ConfigPatch } from '@inkeep/open-knowledge-core/config/schema';
import { OPENKNOWLEDGE_SKILLS_REPO } from '@inkeep/open-knowledge-core/constants/skills';
import {
  type AppliesToPatternSummary,
  assertNeverOkfRuleGroupId,
  assertNeverOkfRuleId,
  type FrontmatterSchemaMapping,
  findZeroMatchAppliesToPatterns,
  isFrontmatterSchemaAsset,
  isOkfRuleEnabled,
  type LintPluginId,
  OKF_RULE_GROUPS,
  OKF_RULE_IDS,
  type OkfRuleGroupId,
  type OkfRuleId,
  summarizeAppliesTo,
} from '@inkeep/open-knowledge-core/markdown/lint';
import { Plural, Trans, useLingui } from '@lingui/react/macro';
import {
  ArrowUpRight,
  CircleAlert,
  FileText,
  GitMerge,
  Plus,
  Power,
  SquarePen,
  Trash2,
} from 'lucide-react';
import { useRef, useState } from 'react';
import { toast } from 'sonner';
import { DeleteConfirmationDialog } from '@/components/DeleteConfirmationDialog';
import { DisclosureWarning, DisclosureWarningItem } from '@/components/DisclosureWarning';
import { useOptionalPageList } from '@/components/PageListContext';
import { SkillPluginBundleDialog } from '@/components/SkillPluginBundleDialog';
import { AlertDialog } from '@/components/ui/alert-dialog';
import { Badge } from '@/components/ui/badge';
import { Button } from '@/components/ui/button';
import {
  Card,
  CardAction,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from '@/components/ui/card';
import {
  Dialog,
  DialogBody,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
} from '@/components/ui/dialog';
import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';
import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
import { Spinner } from '@/components/ui/spinner';
import { Switch } from '@/components/ui/switch';
import { TagPillInput } from '@/components/ui/tag-pill-input';
import {
  createEmptyFrontmatterSchema,
  deleteFrontmatterSchema,
  emitLintConfigChanged,
  useFrontmatterSchemaFiles,
  useProjectLintConfig,
} from '@/editor/lint-config-client';
import {
  type GeneratedIndexSettingsIssue,
  useGeneratedIndexSettings,
} from '@/hooks/use-generated-index-settings';
import { useOpenSkill } from '@/hooks/use-open-skill';
import { useSkills } from '@/hooks/use-skills';
import { useConfigContext } from '@/lib/config-provider';
import { hashFromAssetPath } from '@/lib/doc-hash';
import { dispatchExternalLinkClick } from '@/lib/external-link';
import { requestSchemaFieldsView } from '@/lib/schema-fields-view-intent';
import { installPackSkill } from '@/lib/skills-api';
import { countMatchingDocs } from './applies-to-folder-globs';
import { AppliesToFolderPicker } from './applies-to-folder-picker';
import { indexGlobProblemsByFile, parseAppliesToGlobProblem } from './applies-to-glob-problems';
import { LINT_PLUGIN_META } from './lint-plugin-meta';
import { MarkdownlintRuleBrowser } from './markdownlint-rule-browser';
import { PluginBetaBadge } from './PluginBetaBadge';
import { notifyPluginEnabled } from './plugin-enabled-notice';
import { SettingsSectionHeader } from './SettingsSectionHeader';

function useLinterConfig() {
  const { t } = useLingui();
  const { projectConfig, projectSynced, projectBinding } = useConfigContext();
  const contentRules = projectConfig?.contentRules;
  const bindingReady = projectSynced && projectBinding !== null;

  function write(patch: ConfigPatch['contentRules']): boolean {
    if (projectBinding === null) {
      toast.error(t`Content rules not yet loaded — try again in a moment`);
      return false;
    }
    const result = projectBinding.patch({ contentRules: patch });
    if (!result.ok) {
      toast.error(t`Failed to save content rules — ${humanFormat(result.error)}`);
      return false;
    }
    return true;
  }

  return { contentRules, bindingReady, write };
}

function pluginEnabledPatch(id: LintPluginId, enabled: boolean): ConfigPatch['contentRules'] {
  return { [id]: { enabled } } as ConfigPatch['contentRules'];
}

function PluginManageDescription({ id }: { id: LintPluginId }) {
  switch (id) {
    case 'markdownlint':
      return (
        <Trans>
          Common markdown issues — hard tabs, heading increments, list markers, and more.
        </Trans>
      );
    case 'frontmatter':
      return (
        <Trans>
          Validate document frontmatter against JSON Schema files, scoped to doc sets by glob.
        </Trans>
      );
    case 'okf':
      return <Trans>Keeps your knowledge base aligned with the Open Knowledge Format.</Trans>;
  }
}

export function ProjectPluginsManageSection() {
  const { t } = useLingui();
  const { contentRules, bindingReady, write } = useLinterConfig();

  return (
    <section
      aria-labelledby="settings-plugins-title"
      className="space-y-4"
      data-testid="settings-plugins-manage"
    >
      <SettingsSectionHeader
        titleId="settings-plugins-title"
        title={<Trans>Plugins</Trans>}
        scope="project"
      >
        <Trans>
          Project plugins are your project's authoring standard — turn them on or off here. Each
          enabled plugin gets its own page under Plugins in the settings sidebar.
        </Trans>
      </SettingsSectionHeader>

      <div className="divide-y rounded-md border" data-testid="settings-plugins-list">
        {LINT_PLUGIN_META.map((plugin) => {
          const on = contentRules?.[plugin.id]?.enabled === true;
          const descriptionId = `settings-plugin-toggle-${plugin.id}-description`;
          return (
            <div key={plugin.id} className="flex items-center justify-between gap-3 px-3 py-3">
              <div className="min-w-0">
                <Label
                  htmlFor={`settings-plugin-toggle-${plugin.id}`}
                  className="inline-flex items-center gap-1.5 text-sm font-medium"
                >
                  {plugin.label}
                  {plugin.beta ? <PluginBetaBadge /> : null}
                </Label>
                <p id={descriptionId} className="text-sm text-muted-foreground">
                  <PluginManageDescription id={plugin.id} />
                </p>
              </div>
              <Switch
                id={`settings-plugin-toggle-${plugin.id}`}
                aria-describedby={descriptionId}
                checked={on}
                disabled={!bindingReady}
                onCheckedChange={(next) => {
                  if (!write(pluginEnabledPatch(plugin.id, next))) return;
                  if (next) notifyPluginEnabled({ pluginId: plugin.id, label: plugin.label });
                }}
                aria-label={on ? t`Disable ${plugin.label}` : t`Enable ${plugin.label}`}
                data-testid={`settings-plugin-toggle-${plugin.id}`}
              />
            </div>
          );
        })}
      </div>

      <p className="text-sm text-muted-foreground" data-testid="settings-plugins-audit-pointer">
        <Trans>Run a project audit from the Problems panel.</Trans>
      </p>
    </section>
  );
}

export function UserPluginsManageSection({ userBinding }: { userBinding: ConfigBinding | null }) {
  const { t } = useLingui();
  const { userConfig } = useConfigContext();
  const themeEnabled = userConfig?.appearance?.colorThemeEnabled !== false;
  const slidesEnabled = userConfig?.slides?.enabled === true;

  return (
    <section
      aria-labelledby="settings-user-plugins-title"
      className="space-y-4"
      data-testid="settings-user-plugins-manage"
    >
      <SettingsSectionHeader
        titleId="settings-user-plugins-title"
        title={<Trans>Plugins</Trans>}
        scope="user"
      >
        <Trans>
          User plugins are personal to this device — turn them on or off here. Each enabled plugin
          gets its own page under Plugins in the settings sidebar.
        </Trans>
      </SettingsSectionHeader>

      <div className="divide-y rounded-md border" data-testid="settings-user-plugins-list">
        <div className="flex items-center justify-between gap-3 px-3 py-3">
          <div className="min-w-0">
            <Label htmlFor="settings-plugin-toggle-theme" className="text-sm font-medium">
              <Trans>Themes</Trans>
            </Label>
            <p
              id="settings-plugin-toggle-theme-description"
              className="text-1sm text-muted-foreground"
            >
              <Trans>
                A personal color-theme picker — not shared with your project. When on, it appears
                under Plugins in the sidebar.
              </Trans>
            </p>
          </div>
          <Switch
            id="settings-plugin-toggle-theme"
            aria-describedby="settings-plugin-toggle-theme-description"
            checked={themeEnabled}
            disabled={userBinding === null}
            onCheckedChange={(next) => {
              if (!userBinding) return;
              const result = userBinding.patch({ appearance: { colorThemeEnabled: next } });
              if (!result.ok) {
                toast.error(t`Failed to save theme setting`);
                return;
              }
              if (next) notifyPluginEnabled({ pluginId: 'theme', label: t`Themes` });
            }}
            aria-label={themeEnabled ? t`Disable Themes` : t`Enable Themes`}
            data-testid="settings-plugin-toggle-theme"
          />
        </div>
        <div className="flex items-center justify-between gap-3 px-3 py-3">
          <div className="min-w-0">
            <Label
              htmlFor="settings-plugin-toggle-slides"
              className="inline-flex items-center gap-1.5 text-sm font-medium"
            >
              <Trans>Slidev</Trans>
              <PluginBetaBadge />
            </Label>
            <p
              id="settings-plugin-toggle-slides-description"
              className="text-1sm text-muted-foreground"
            >
              <Trans>
                Present a document as a slide deck in its own window. Works in the OpenKnowledge
                desktop app only, and needs the Slidev CLI, which you install separately. When on,
                it appears under Plugins in the sidebar.
              </Trans>
            </p>
          </div>
          <Switch
            id="settings-plugin-toggle-slides"
            aria-describedby="settings-plugin-toggle-slides-description"
            checked={slidesEnabled}
            disabled={userBinding === null}
            onCheckedChange={(next) => {
              if (!userBinding) return;
              const result = userBinding.patch({ slides: { enabled: next } });
              if (!result.ok) {
                toast.error(t`Failed to save Slidev setting`);
                return;
              }
              if (next) notifyPluginEnabled({ pluginId: 'slides', label: t`Slidev` });
            }}
            aria-label={slidesEnabled ? t`Disable Slidev` : t`Enable Slidev`}
            data-testid="settings-plugin-toggle-slides"
          />
        </div>
      </div>
    </section>
  );
}

function pluginDocUrl(id: LintPluginId): string | undefined {
  return LINT_PLUGIN_META.find((plugin) => plugin.id === id)?.docUrl;
}

function pluginIsBeta(id: LintPluginId): boolean {
  return LINT_PLUGIN_META.find((plugin) => plugin.id === id)?.beta === true;
}

export function MarkdownlintPluginSection({
  initialRuleQuery,
}: {
  initialRuleQuery?: { query: string; nonce: number } | null;
} = {}) {
  return (
    <section
      aria-labelledby="settings-plugin-markdownlint-title"
      className="space-y-4"
      data-testid="settings-plugin-markdownlint"
    >
      <SettingsSectionHeader
        titleId="settings-plugin-markdownlint-title"
        title="markdownlint"
        scope="project"
        docUrl={pluginDocUrl('markdownlint')}
      >
        <Trans>
          Flag common markdown issues in the editor. Powered by{' '}
          <a
            href="https://github.com/DavidAnson/markdownlint"
            target="_blank"
            rel="noopener noreferrer"
            onClick={(e) =>
              dispatchExternalLinkClick(e, 'https://github.com/DavidAnson/markdownlint')
            }
            onAuxClick={(e) =>
              dispatchExternalLinkClick(e, 'https://github.com/DavidAnson/markdownlint')
            }
            className="inline-flex items-center gap-0.5 text-primary underline-offset-2 hover:underline"
          >
            markdownlint
            <ArrowUpRight aria-hidden className="size-3" />
          </a>
          .
        </Trans>
      </SettingsSectionHeader>
      <MarkdownlintRuleBrowser initialRuleQuery={initialRuleQuery} />
    </section>
  );
}

function OkfRuleDescription({ id }: { id: OkfRuleId }) {
  switch (id) {
    case 'no-wiki-links':
      return (
        <Trans>
          Wiki-links like [[Page]] — a supported way to link here, but an external reader resolves
          nothing and shows the brackets.
        </Trans>
      );
    case 'log-shape':
      return (
        <Trans>
          In a log document: entry headings lead with an ISO YYYY-MM-DD date, newest first. How many
          titles you use, and whether entries are bullets, is up to you.
        </Trans>
      );
    case 'index-shape':
      return (
        <Trans>
          In an index document: entries sit under a section heading and each one carries a link.
          Prose around the lists is fine.
        </Trans>
      );
    case 'reserved-casing':
      return (
        <Trans>
          Reserved files are named index.md and log.md in lowercase. On a case-sensitive filesystem,
          Index.md is read as an ordinary document and loses its meaning.
        </Trans>
      );
    case 'frontmatter-required':
      return (
        <Trans>
          Every concept document carries a non-empty type. This is the whole of OKF's conformance
          floor — a document with only a type is fully conformant.
        </Trans>
      );
    case 'frontmatter-recommended':
      return (
        <Trans>
          The shapes of title, description, resource, and tags when you use them. None are required;
          declaring one only pins its type, so tags written as a comma-separated string is flagged.
        </Trans>
      );
    case 'frontmatter-provenance':
      return (
        <Trans>
          The provenance, trust, and lifecycle families: sources, generated, verified, status, and
          stale_after. Every field is optional, and absence is never an error.
        </Trans>
      );
    case 'frontmatter-computation':
      return (
        <Trans>
          The attested-computation contract. Only applies to documents typed Attested Computation,
          where OKF requires a runtime; ordinary concepts are unaffected.
        </Trans>
      );
    case 'frontmatter-reserved-index':
      return (
        <Trans>
          Index documents carry no frontmatter, except the one at your knowledge base's root. Log
          documents are not covered — OKF does not constrain their frontmatter.
        </Trans>
      );
    case 'frontmatter-root-index':
      return (
        <Trans>
          On the root index, okf_version is written as a quoted string like "0.2". Unquoted, YAML
          reads it as a number and 0.10 silently becomes 0.1.
        </Trans>
      );
    case 'project-no-mdx':
      return (
        <Trans>
          Any .mdx file. The format is .md-only, so a reader scanning for .md never opens it — and
          if a .md of the same name exists, reads that one instead.
        </Trans>
      );
    default:
      return assertNeverOkfRuleId(id);
  }
}

function OkfGroupLabel({ id }: { id: OkfRuleGroupId }) {
  switch (id) {
    case 'structure':
      return <Trans>Document structure</Trans>;
    case 'frontmatter':
      return <Trans>Frontmatter</Trans>;
    case 'project':
      return <Trans>Project</Trans>;
    default:
      return assertNeverOkfRuleGroupId(id);
  }
}

function OkfGroupNote({ id }: { id: OkfRuleGroupId }) {
  if (id !== 'project') return null;
  return (
    <p className="text-sm text-muted-foreground">
      <Trans>
        This one needs to see your files, not just the open document, so it appears when you run a
        project audit rather than while you type.
      </Trans>
    </p>
  );
}

function OkfRecommendedSkillCard({ packId, name }: { packId: string; name: string }) {
  const { t } = useLingui();
  const skills = useSkills();
  const openSkill = useOpenSkill();
  const [dialogOpen, setDialogOpen] = useState(false);
  const [optimisticStatus, setOptimisticStatus] = useState<'installed' | 'existing' | null>(null);
  const installSkillTriggerRef = useRef<HTMLButtonElement>(null);
  const description = t`Helps coding agents choose OKF document types, preserve provenance, and avoid inventing unsupported metadata.`;
  const entry =
    skills.status === 'ready'
      ? skills.data.find((skill) => skill.scope === 'project' && skill.name === name)
      : undefined;
  const status = entry
    ? entry.origin?.source === OPENKNOWLEDGE_SKILLS_REPO
      ? 'installed'
      : 'existing'
    : optimisticStatus;
  const checking = skills.status === 'idle' || skills.status === 'loading';

  async function installSelected(
    selected: readonly string[],
  ): Promise<ReadonlyMap<string, string> | null> {
    if (!selected.includes(name)) return new Map();
    const result = await installPackSkill(packId);
    if (!result.ok) {
      toast.error(result.error);
      return null;
    }
    const installed = result.skills.find((skill) => skill.name === name);
    const nextStatus = installed?.created === false ? 'existing' : 'installed';
    setOptimisticStatus(nextStatus);
    toast.success(
      nextStatus === 'installed' ? t`OKF agent skill installed` : t`Skill already in project`,
    );
    return new Map([[name, name]]);
  }

  return (
    <>
      <Card size="sm" data-testid="settings-okf-recommended-skill">
        <CardHeader>
          <CardTitle>
            <Trans>Open Knowledge Format guidance</Trans>
          </CardTitle>
          <CardDescription>{description}</CardDescription>
          {status === 'installed' ? (
            <CardAction>
              <Badge variant="secondary">
                <Trans>Installed</Trans>
              </Badge>
            </CardAction>
          ) : status === 'existing' ? (
            <CardAction>
              <Badge variant="outline">
                <Trans>Already in project</Trans>
              </Badge>
            </CardAction>
          ) : null}
        </CardHeader>
        <CardFooter className="justify-end gap-2">
          {status !== null ? (
            <Button
              type="button"
              variant="outline"
              size="sm"
              onClick={() => openSkill('project', name)}
            >
              <Trans>Open skill</Trans>
            </Button>
          ) : (
            <Button
              ref={installSkillTriggerRef}
              type="button"
              variant="secondary"
              size="sm"
              disabled={checking}
              onClick={() => setDialogOpen(true)}
            >
              {checking ? <Trans>Checking skill</Trans> : <Trans>Install skill</Trans>}
            </Button>
          )}
        </CardFooter>
      </Card>
      <SkillPluginBundleDialog
        bundle={
          dialogOpen
            ? { plugin: 'OKF', names: [name], descriptions: { [name]: description } }
            : null
        }
        source={OPENKNOWLEDGE_SKILLS_REPO}
        defaultScope="project"
        installOverride={{ scope: 'project', installSelected }}
        onOpenChange={setDialogOpen}
        returnFocus={() => installSkillTriggerRef.current?.focus()}
      />
    </>
  );
}

export function OkfPluginSection() {
  const { t } = useLingui();
  const { contentRules, bindingReady, write } = useLinterConfig();
  const rules = contentRules?.okf?.rules;
  const enabledCount = OKF_RULE_IDS.filter((id) => isOkfRuleEnabled(rules, id)).length;
  const generateIndex = contentRules?.okf?.generate?.index === true;
  const generatedIndexSettings = useGeneratedIndexSettings();
  const generateIndexEnabled = generatedIndexSettings.status?.enabled ?? generateIndex;
  const [confirmingGenerateIndex, setConfirmingGenerateIndex] = useState(false);
  const generateIndexTriggerRef = useRef<HTMLButtonElement>(null);
  const recommendedSkills =
    LINT_PLUGIN_META.find((plugin) => plugin.id === 'okf')?.recommendedSkills ?? [];

  function toggleGenerateIndex(next: boolean): void {
    if (next) {
      setConfirmingGenerateIndex(true);
      return;
    }
    void generatedIndexSettings.setEnabled(false);
  }

  async function confirmGenerateIndex(): Promise<void> {
    await generatedIndexSettings.setEnabled(true);
    setConfirmingGenerateIndex(false);
  }

  function toggleRule(id: OkfRuleId, next: boolean): void {
    const rules: Partial<Record<OkfRuleId, boolean | null>> = {};
    rules[id] = next ? null : false;
    if (write({ okf: { rules } })) {
      emitLintConfigChanged();
    }
  }

  return (
    <section
      aria-labelledby="settings-plugin-okf-title"
      className="space-y-4"
      data-testid="settings-plugin-okf"
    >
      <SettingsSectionHeader
        titleId="settings-plugin-okf-title"
        title="OKF"
        scope="project"
        beta={pluginIsBeta('okf')}
        docUrl={pluginDocUrl('okf')}
      >
        <Trans>Keeps your knowledge base aligned with the Open Knowledge Format.</Trans>
      </SettingsSectionHeader>

      {recommendedSkills.length > 0 ? (
        <div className="flex flex-col gap-2" data-testid="settings-okf-recommended-skills">
          <h4 className="text-sm font-medium">
            <Trans>Recommended agent skill</Trans>
          </h4>
          {recommendedSkills.map((skill) => (
            <OkfRecommendedSkillCard key={skill.name} packId={skill.packId} name={skill.name} />
          ))}
        </div>
      ) : null}

      <div className="space-y-2" data-testid="settings-okf-generated-files">
        <h4 className="text-sm font-medium">
          <Trans>Generated files</Trans>
        </h4>
        <div className="flex items-center justify-between gap-3 rounded-md border px-3 py-2">
          <div className="min-w-0">
            <Label htmlFor="settings-okf-generate-index" className="text-sm font-medium">
              <Trans>Maintain index.md</Trans>
            </Label>
            <p className="text-sm text-muted-foreground">
              <Trans>
                Open Knowledge maintains a navigation file named index.md in every folder that
                contains Markdown, each listing that folder's documents by type and linking to its
                subfolders. It rewrites these files as your documents change, and anything you edit
                into them yourself is replaced.
              </Trans>
            </p>
            <p className="mt-1 text-sm text-muted-foreground">
              <Trans>
                In Git projects, Open Knowledge also adds a scoped .gitattributes rule so concurrent
                index changes combine before the next rebuild.
              </Trans>
            </p>
          </div>
          <Switch
            ref={generateIndexTriggerRef}
            id="settings-okf-generate-index"
            checked={generateIndexEnabled}
            disabled={
              !bindingReady ||
              generatedIndexSettings.status === null ||
              generatedIndexSettings.pending
            }
            onCheckedChange={toggleGenerateIndex}
            aria-label={
              generateIndexEnabled ? t`Stop maintaining index.md` : t`Start maintaining index.md`
            }
            data-testid="settings-okf-generate-index"
          />
        </div>
        <GeneratedIndexSettingsNotice
          enabled={generatedIndexSettings.status?.enabled ?? generateIndex}
          gitState={generatedIndexSettings.status?.git.state}
          issue={generatedIndexSettings.issue}
          requestedEnabled={generatedIndexSettings.requestedEnabled}
        />
        <Dialog open={confirmingGenerateIndex} onOpenChange={setConfirmingGenerateIndex}>
          <DialogContent
            className="sm:max-w-lg"
            data-testid="settings-okf-generate-index-confirm"
            onCloseAutoFocus={(event) => {
              event.preventDefault();
              generateIndexTriggerRef.current?.focus();
            }}
          >
            <DialogHeader>
              <DialogTitle>
                <Trans>Maintain generated indexes in every folder?</Trans>
              </DialogTitle>
              <DialogDescription className="text-inherit">
                <Trans>
                  Open Knowledge creates and maintains a navigation file named index.md in every
                  folder that contains Markdown.
                </Trans>
              </DialogDescription>
            </DialogHeader>
            <DialogBody>
              <DisclosureWarning>
                <DisclosureWarningItem
                  icon={
                    <FileText
                      aria-hidden="true"
                      className="mt-0.5 size-4 shrink-0 text-muted-foreground"
                    />
                  }
                  title={<Trans>Generated files</Trans>}
                  body={
                    <Trans>
                      Open Knowledge rewrites these index.md files as documents change, so manual
                      edits to them are replaced.
                    </Trans>
                  }
                />
                <DisclosureWarningItem
                  icon={
                    <GitMerge
                      aria-hidden="true"
                      className="mt-0.5 size-4 shrink-0 text-muted-foreground"
                    />
                  }
                  title={<Trans>Git merge rule</Trans>}
                  body={
                    <Trans>
                      In Git projects, Open Knowledge adds a scoped rule to the repository-root
                      .gitattributes file so concurrent index changes combine.
                    </Trans>
                  }
                />
                <DisclosureWarningItem
                  icon={
                    <Power
                      aria-hidden="true"
                      className="mt-0.5 size-4 shrink-0 text-muted-foreground"
                    />
                  }
                  title={<Trans>Turning it off</Trans>}
                  body={
                    <Trans>
                      The index files stay in place. Open Knowledge removes only the Git rule it
                      added.
                    </Trans>
                  }
                />
              </DisclosureWarning>
            </DialogBody>
            <DialogFooter>
              <DialogClose asChild>
                <Button variant="outline">
                  <Trans>Cancel</Trans>
                </Button>
              </DialogClose>
              <Button
                onClick={() => void confirmGenerateIndex()}
                disabled={generatedIndexSettings.pending}
                data-testid="settings-okf-generate-index-confirm-accept"
              >
                {generatedIndexSettings.pending ? (
                  <>
                    <Spinner aria-hidden="true" />
                    <Trans>Enabling index generation</Trans>
                  </>
                ) : (
                  <Trans>Enable indexes</Trans>
                )}
              </Button>
            </DialogFooter>
          </DialogContent>
        </Dialog>
      </div>

      <div className="flex items-center justify-between">
        <h4 className="text-sm font-medium">
          <Trans>Rules</Trans>
        </h4>
        <span className="text-xs text-muted-foreground">
          <Trans>
            {enabledCount}/{OKF_RULE_IDS.length} on
          </Trans>
        </span>
      </div>

      <div className="space-y-4" data-testid="settings-okf-rules-list">
        {OKF_RULE_GROUPS.map((group) => (
          <div
            key={group.id}
            className="space-y-2"
            data-testid={`settings-okf-rule-group-${group.id}`}
          >
            <h5 className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
              <OkfGroupLabel id={group.id} />
            </h5>
            <OkfGroupNote id={group.id} />
            <div className="divide-y rounded-md border">
              {group.ids.map((id) => {
                const on = isOkfRuleEnabled(rules, id);
                return (
                  <div key={id} className="flex items-center justify-between gap-3 px-3 py-2">
                    <div className="min-w-0">
                      <Label
                        htmlFor={`settings-okf-rule-toggle-${id}`}
                        className="text-sm font-medium"
                      >
                        {id}
                      </Label>
                      <p className="text-sm text-muted-foreground">
                        <OkfRuleDescription id={id} />
                      </p>
                    </div>
                    <Switch
                      id={`settings-okf-rule-toggle-${id}`}
                      checked={on}
                      disabled={!bindingReady}
                      onCheckedChange={(next) => toggleRule(id, next)}
                      aria-label={on ? t`Disable ${id}` : t`Enable ${id}`}
                      data-testid={`settings-okf-rule-toggle-${id}`}
                    />
                  </div>
                );
              })}
            </div>
          </div>
        ))}
      </div>
    </section>
  );
}

function GeneratedIndexSettingsNotice({
  enabled,
  gitState,
  issue,
  requestedEnabled,
}: {
  enabled: boolean;
  gitState?: 'not-applicable' | 'ready' | 'missing' | 'conflict' | 'unavailable';
  issue: GeneratedIndexSettingsIssue | null;
  requestedEnabled: boolean | null;
}) {
  const effectiveIssue =
    issue ??
    (enabled && gitState === 'conflict'
      ? 'git-conflict'
      : enabled && (gitState === 'missing' || gitState === 'unavailable')
        ? 'git-unavailable'
        : null);
  if (effectiveIssue === null) return null;

  return (
    <div
      role="status"
      className="flex gap-2 rounded-md border border-warning/40 px-3 py-2 text-sm"
      data-testid="settings-okf-generate-index-status"
    >
      <CircleAlert aria-hidden="true" className="mt-0.5 size-4 shrink-0 text-warning" />
      <p>
        {issue !== null && requestedEnabled === false ? (
          issue === 'git-conflict' ? (
            <Trans>
              Turning off index maintenance failed because the Open Knowledge section of
              .gitattributes was edited or is incomplete. Remove that section, then try again.
            </Trans>
          ) : issue === 'config-write' ? (
            <Trans>
              Turning off index maintenance failed because the project setting could not be saved.
              Check the project file permissions, then try again.
            </Trans>
          ) : issue === 'connection' ? (
            <Trans>
              Turning off index maintenance failed because Open Knowledge could not reach the
              project server. Try again when the project reconnects.
            </Trans>
          ) : (
            <Trans>
              Turning off index maintenance failed because Open Knowledge could not update the Git
              merge rule. Check Git and .gitattributes, then try again.
            </Trans>
          )
        ) : issue === 'connection' && requestedEnabled === null ? (
          <Trans>
            Open Knowledge could not reach the project server to check index maintenance. The status
            updates when the project reconnects.
          </Trans>
        ) : effectiveIssue === 'git-conflict' ? (
          <Trans>
            Index maintenance is paused because another Git attribute controls index.md. Update
            .gitattributes so the scoped index.md paths use merge=union, then try again.
          </Trans>
        ) : effectiveIssue === 'config-write' ? (
          <Trans>
            Index maintenance stayed off because the project setting could not be saved. Check the
            project file permissions, then try again.
          </Trans>
        ) : effectiveIssue === 'connection' ? (
          <Trans>
            Index maintenance stayed off because Open Knowledge could not reach the project server.
            Try again when the project reconnects.
          </Trans>
        ) : (
          <Trans>
            Index maintenance is paused because Open Knowledge could not confirm the required Git
            merge rule. Check Git and .gitattributes, then try again.
          </Trans>
        )}
      </p>
    </div>
  );
}

function appliesToList(appliesTo: FrontmatterSchemaMapping['appliesTo']): string[] {
  if (appliesTo === undefined) return [];
  return Array.isArray(appliesTo) ? appliesTo : [appliesTo];
}

function AppliesToPhrase({ summary }: { summary: AppliesToPatternSummary }) {
  switch (summary.kind) {
    case 'everything':
      return <Trans>every doc</Trans>;
    case 'folder-recursive':
      return <Trans>everything under {summary.folder}/</Trans>;
    case 'folder-direct':
      return <Trans>docs directly in {summary.folder}/</Trans>;
    case 'exact':
      return <Trans>the doc {summary.target}</Trans>;
    case 'name-anywhere':
      return <Trans>any doc named {summary.name}</Trans>;
    case 'folder-anywhere':
      return <Trans>everything under any {summary.folder}/ folder</Trans>;
    case 'folder-recursive-nested':
      return (
        <Trans>
          everything under {summary.folder}/ folders inside {summary.root}/
        </Trans>
      );
    case 'matches-nothing':
      return <Trans>nothing ({summary.pattern} cannot match a doc)</Trans>;
    case 'invalid':
      return <Trans>nothing ({summary.pattern} is not a valid pattern)</Trans>;
    case 'pattern':
      return <Trans>docs matching {summary.pattern}</Trans>;
  }
}

function AppliesToSummaryLine({
  file,
  appliesTo,
}: {
  file: string;
  appliesTo: FrontmatterSchemaMapping['appliesTo'];
}) {
  const { includes, excludes } = summarizeAppliesTo(appliesTo);
  const pageList = useOptionalPageList();
  const counted =
    pageList !== null && pageList.pages.size > 0
      ? countMatchingDocs(appliesTo, pageList.pages)
      : null;
  const zeroMatch =
    counted !== null && counted.matched === 0 && appliesToList(appliesTo).length > 0;
  const zeroMatchPatterns =
    pageList !== null ? findZeroMatchAppliesToPatterns(appliesTo, [...pageList.pages]) : [];
  const zeroMatchBareNameAuthored = zeroMatchPatterns.some((pattern) =>
    summarizeAppliesTo(pattern).includes.some((entry) => entry.kind === 'exact'),
  );
  const list = (entries: AppliesToPatternSummary[]) =>
    entries.map((entry, index) => (
      // biome-ignore lint/suspicious/noArrayIndexKey: display-only phrase list, order-stable.
      <span key={index}>
        {index > 0 ? ', ' : null}
        <AppliesToPhrase summary={entry} />
      </span>
    ));
  return (
    <p
      className="text-xs text-muted-foreground"
      data-testid={`frontmatter-schema-applies-summary-${file}`}
    >
      <Trans>Applies to</Trans>{' '}
      {includes.length === 0 ? (
        <AppliesToPhrase summary={{ kind: 'everything' }} />
      ) : (
        list(includes)
      )}
      {excludes.length > 0 ? (
        <>
          {' '}
          <Trans>— except</Trans> {list(excludes)}
        </>
      ) : null}
      .
      {counted !== null ? (
        <span
          role="status"
          aria-live="polite"
          className={zeroMatch ? 'text-muted-foreground/70' : undefined}
          data-testid={`frontmatter-schema-match-count-${file}`}
        >
          {' '}
          <Plural
            value={counted.total}
            one={
              <Trans>
                Matches {counted.matched} of {counted.total} doc right now.
              </Trans>
            }
            other={
              <Trans>
                Matches {counted.matched} of {counted.total} docs right now.
              </Trans>
            }
          />
          {zeroMatchBareNameAuthored ? (
            <span className="ms-1 text-muted-foreground/60">
              <Trans>(a bare folder name needs /** after it to match what's inside)</Trans>
            </span>
          ) : null}
        </span>
      ) : null}
    </p>
  );
}

function mappingEnabled(mapping: FrontmatterSchemaMapping): boolean {
  return mapping.enabled !== false;
}

function SchemaFileRow({
  file,
  mapping,
  disabled,
  globProblems,
  onToggle,
  onAppliesToChange,
  onDelete,
}: {
  file: string;
  mapping: FrontmatterSchemaMapping | undefined;
  disabled: boolean;
  globProblems: ReadonlyMap<string, string> | undefined;
  onToggle: (on: boolean) => void;
  onAppliesToChange: (globs: string[]) => void;
  onDelete: (() => void) | null;
}) {
  const { t } = useLingui();
  const on = mapping !== undefined && mappingEnabled(mapping);

  const openSchemaFile = () => {
    requestSchemaFieldsView(file);
    window.location.hash = hashFromAssetPath(file);
  };

  return (
    <div className="px-3 py-2" data-testid={`frontmatter-schema-row-${file}`}>
      <div className="flex items-center justify-between gap-3">
        <span className="min-w-0 flex-1 truncate font-mono text-sm" title={file}>
          {file}
        </span>
        <div className="flex shrink-0 items-center gap-2">
          <Button
            variant="outline"
            size="sm"
            className="h-6 shrink-0 gap-1 px-2 text-xs"
            onClick={openSchemaFile}
            aria-label={t`Edit schema ${file}`}
            data-testid={`frontmatter-schema-edit-${file}`}
          >
            <SquarePen aria-hidden className="size-3" />
            <Trans>Edit</Trans>
          </Button>
          {onDelete !== null ? (
            <Button
              variant="ghost"
              size="icon"
              className="h-5 w-5 shrink-0 text-muted-foreground opacity-60 hover:opacity-100"
              disabled={disabled}
              aria-label={t`Delete schema file ${file}`}
              onClick={onDelete}
              data-testid={`frontmatter-schema-delete-${file}`}
            >
              <Trash2 className="size-3.5" />
            </Button>
          ) : null}
          <Switch
            checked={on}
            disabled={disabled}
            aria-label={on ? t`Disable ${file}` : t`Enable ${file}`}
            onCheckedChange={onToggle}
            data-testid={`frontmatter-schema-toggle-${file}`}
          />
        </div>
      </div>
      {on ? (
        <div className="mt-2 space-y-1 ps-1.5">
          <Label htmlFor={`frontmatter-schema-applies-${file}`} className="text-xs">
            <Trans>Applies to (globs — leading ! excludes; empty means every doc)</Trans>
          </Label>
          <AppliesToFolderPicker
            file={file}
            globs={appliesToList(mapping?.appliesTo)}
            disabled={disabled}
            onChange={onAppliesToChange}
          />
          <TagPillInput
            id={`frontmatter-schema-applies-${file}`}
            value={appliesToList(mapping?.appliesTo)}
            grammar="free-text"
            disabled={disabled}
            entryProblems={globProblems}
            onChange={onAppliesToChange}
            placeholder={t`Add file or folder pattern, e.g. guides/**/*`}
            aria-label={t`Glob patterns this schema applies to`}
          />
          <AppliesToSummaryLine file={file} appliesTo={mapping?.appliesTo} />
        </div>
      ) : null}
    </div>
  );
}

export function FrontmatterPluginSection() {
  const { t } = useLingui();
  const { contentRules, bindingReady, write } = useLinterConfig();
  const { data } = useProjectLintConfig();
  const { schemas: discovered } = useFrontmatterSchemaFiles();
  const mappings = contentRules?.frontmatter?.schemas ?? [];
  const [search, setSearch] = useState('');
  const [createOpen, setCreateOpen] = useState(false);
  const [newSchemaName, setNewSchemaName] = useState('');
  const [deleteTarget, setDeleteTarget] = useState<string | null>(null);
  const [deleting, setDeleting] = useState(false);

  /*
   * WARN: these prefix strings are the compose contract in the server's
   * `lint/frontmatter-schemas.ts`. Drift silently drops problems from this
   * panel instead of failing.
   */
  const mappedFiles = new Set(mappings.map((m) => m.file));
  const scopedProblems = (data?.configProblems ?? []).filter((p) => {
    if (p.startsWith('frontmatter schema ')) {
      return [...mappedFiles].some((file) => p.startsWith(`frontmatter schema ${file}:`));
    }
    if (
      p.startsWith('invalid appliesTo glob') ||
      p.startsWith('suspicious appliesTo glob') ||
      p.startsWith('unmatched appliesTo glob')
    ) {
      return [...mappedFiles].some((file) => p.endsWith(`(frontmatter mapping for ${file})`));
    }
    return false;
  });

  function writeMappings(next: FrontmatterSchemaMapping[]): void {
    if (write({ frontmatter: { schemas: next } } as ConfigPatch['contentRules'])) {
      emitLintConfigChanged();
    }
  }

  const files = [...new Set([...discovered, ...mappings.map((m) => m.file)])].sort((a, b) =>
    a.localeCompare(b),
  );
  const query = search.trim().toLowerCase();
  const visible = files.filter((f) => query === '' || f.toLowerCase().includes(query));

  const globProblemsByFile = indexGlobProblemsByFile(scopedProblems);
  const problems = scopedProblems.filter((p) => {
    const parsed = parseAppliesToGlobProblem(p);
    if (parsed === null) return true;
    const bound = mappings.find((m) => m.file === parsed.file);
    const carriedByPill =
      bound !== undefined &&
      mappingEnabled(bound) &&
      appliesToList(bound.appliesTo).includes(parsed.pattern);
    const authoredSomewhere = mappings.some(
      (m) => m.file === parsed.file && appliesToList(m.appliesTo).includes(parsed.pattern),
    );
    return !carriedByPill && authoredSomewhere;
  });

  function toggleFile(file: string, on: boolean): void {
    if (!mappings.some((m) => m.file === file)) {
      if (on) writeMappings([...mappings, { file, enabled: true }]);
      return;
    }
    writeMappings(mappings.map((m) => (m.file === file ? { ...m, enabled: on } : m)));
  }

  function setAppliesTo(file: string, globs: string[]): void {
    writeMappings(
      mappings.map((m) => {
        if (m.file !== file) return m;
        if (globs.length === 0) {
          const { appliesTo: _cleared, ...rest } = m;
          return rest;
        }
        return { ...m, appliesTo: globs };
      }),
    );
  }

  async function deleteSchemaFile(file: string): Promise<void> {
    setDeleting(true);
    const result = await deleteFrontmatterSchema(file);
    setDeleting(false);
    if (!result.ok) {
      toast.error(result.errorDetail ?? t`Failed to delete ${file}`);
      return;
    }
    if (mappings.some((m) => m.file === file)) {
      writeMappings(mappings.filter((m) => m.file !== file));
    }
    setDeleteTarget(null);
    toast.success(t`Deleted ${file}`);
  }

  async function createSchema(): Promise<void> {
    const name = newSchemaName.trim();
    if (name === '' || name.includes('/') || name.includes('\\')) return;
    const file = `.ok/schemas/${name.endsWith('.json') ? name : `${name}.schema.json`}`;
    const result = await createEmptyFrontmatterSchema(file);
    if (!result.ok) {
      toast.error(result.errorDetail ?? t`Failed to create the schema file`);
      return;
    }
    writeMappings([...mappings, { file, enabled: true }]);
    setCreateOpen(false);
    setNewSchemaName('');
  }

  return (
    <section
      aria-labelledby="settings-plugin-frontmatter-title"
      className="space-y-4"
      data-testid="settings-plugin-frontmatter"
    >
      <SettingsSectionHeader
        titleId="settings-plugin-frontmatter-title"
        title={t`Frontmatter schemas`}
        scope="project"
        beta={pluginIsBeta('frontmatter')}
        docUrl={pluginDocUrl('frontmatter')}
      >
        <Trans>
          Validate document frontmatter against standard JSON Schema files (draft-06, draft-07,
          2019-09, or 2020-12). Toggle a schema on to validate the docs its globs match; violations
          surface as warnings and never block a write. Use Edit to open the schema file.
        </Trans>
      </SettingsSectionHeader>

      {problems.length > 0 && (
        <div
          className="space-y-1 rounded-md border border-warning/50 p-3 text-sm"
          data-testid="frontmatter-config-problems"
        >
          <p className="font-medium">
            <Trans>Configuration problems</Trans>
          </p>
          <ul className="list-disc ps-5 text-muted-foreground">
            {problems.map((problem) => (
              <li key={problem}>{problem}</li>
            ))}
          </ul>
        </div>
      )}

      <div className="flex items-center gap-4">
        <Input
          value={search}
          onChange={(e) => setSearch(e.target.value)}
          placeholder={t`Search schemas`}
          aria-label={t`Search schema files by path`}
          className="h-8"
          data-testid="frontmatter-schema-search"
        />
        <Popover open={createOpen} onOpenChange={setCreateOpen}>
          <PopoverTrigger asChild>
            <Button
              variant="outline"
              size="sm"
              className="shrink-0"
              data-testid="frontmatter-create-schema"
            >
              <Plus aria-hidden className="size-4" />
              <Trans>New schema</Trans>
            </Button>
          </PopoverTrigger>
          <PopoverContent align="end" className="w-72 space-y-2">
            <Label htmlFor="frontmatter-create-schema-name" className="text-xs">
              <Trans>File name (created in .ok/schemas/)</Trans>
            </Label>
            <Input
              id="frontmatter-create-schema-name"
              value={newSchemaName}
              onChange={(e) => setNewSchemaName(e.target.value)}
              onKeyDown={(e) => {
                if (e.key === 'Enter') void createSchema();
              }}
              placeholder="doc"
              data-testid="frontmatter-create-schema-name"
            />
            <Button
              size="sm"
              disabled={!bindingReady || newSchemaName.trim() === ''}
              onClick={() => void createSchema()}
              data-testid="frontmatter-create-schema-save"
            >
              <Trans>Create</Trans>
            </Button>
          </PopoverContent>
        </Popover>
      </div>

      {visible.length === 0 ? (
        <p
          className="rounded-md border border-dashed p-3 text-sm text-muted-foreground"
          data-testid="frontmatter-schemas-empty"
        >
          {files.length === 0 ? (
            <Trans>No schema files in this project yet — create one to start validating.</Trans>
          ) : (
            <Trans>No schemas match your search.</Trans>
          )}
        </p>
      ) : (
        <div className="divide-y rounded-md border" data-testid="frontmatter-schemas-list">
          {visible.map((file) => (
            <SchemaFileRow
              key={file}
              file={file}
              mapping={mappings.find((m) => m.file === file)}
              disabled={!bindingReady}
              globProblems={globProblemsByFile.get(file)}
              onToggle={(on) => toggleFile(file, on)}
              onAppliesToChange={(globs) => setAppliesTo(file, globs)}
              onDelete={isFrontmatterSchemaAsset(file) ? () => setDeleteTarget(file) : null}
            />
          ))}
        </div>
      )}
      <AlertDialog
        open={deleteTarget !== null}
        onOpenChange={(open) => {
          if (!open && !deleting) setDeleteTarget(null);
        }}
      >
        {deleteTarget !== null ? (
          <DeleteConfirmationDialog
            itemName={t`schema ${deleteTarget}`}
            isSubmitting={deleting}
            onDelete={() => void deleteSchemaFile(deleteTarget)}
            customDescription={t`This permanently deletes ${deleteTarget} from the project and removes its mapping from config.yml.`}
          />
        ) : null}
      </AlertDialog>
    </section>
  );
}