Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

7.5 KB
Raw Blame
/**
 * `link-syntax.ts` cites precedent #56 and is pinned by divergence tests for *recognition*; this is
 * the equivalent pin for *classification*.
 */

import { createTargetNamespace } from '@inkeep/open-knowledge-core';
import { describe, expect, test } from 'vitest';
import {
  extractMarkdownLinksFromMarkdown,
  extractWikiLinksFromMarkdown,
} from './backlink-index.ts';
import {
  assessLocalTargets,
  createTolerantDocumentResolver,
  type LocalTargetAssessment,
  type LocalTargetInventory,
} from './local-target-assessment.ts';
import { createFileBasenameResolver } from './local-target-inventory.ts';
import {
  extractLocalTargetOccurrences,
  type LocalTargetOccurrence,
} from './local-target-occurrences.ts';

const SOURCE_DOC = 'all-link-types';

const MATRIX = [
  '---',
  'title: All link types matrix',
  'ignored_example: "[Ignored frontmatter](assets/frontmatter-missing.txt)"',
  '---',
  '',
  '# Matrix',
  '',
  '## Documents (control rows — these already agree)',
  '',
  '- [Relative Markdown document](targets/existing-page.md)',
  '- [Missing Markdown document](targets/missing-markdown.md)',
  '',
  '## Cluster 1 — wiki forms',
  '',
  '- [[targets/existing-page]]',
  '- [[targets/missing-wiki]]',
  '- ![[targets/missing-embed]]',
  '',
  '## Cluster 2 — reference-style links',
  '',
  '- [Missing reference document][missing-doc-ref]',
  '- [Tolerant case fallback][case-doc]',
  '- [Existing reference PDF][valid-pdf]',
  '- [Missing full reference][missing-spec]',
  '- [missing-spec][]',
  '- [missing-spec]',
  '',
  '## Cluster 3 — extensionless ordinary file',
  '',
  '- [Extensionless ordinary file](assets/NOTICE)',
  '- ![Existing extensionless image target](assets/NOTICE)',
  '',
  '## Files (control rows — these already agree)',
  '',
  '- [Existing text file](assets/existing.txt)',
  '- [Missing JSON file](assets/missing.json)',
  '',
  '## Cluster 4 — non-rendering contexts (must be inert everywhere)',
  '',
  'Invisible by design <!-- [HTML comment](assets/comment-missing.txt) -->',
  '',
  '<pre>[Raw pre block](assets/pre-missing.txt)</pre>',
  '',
  '```markdown',
  '[Fenced code](assets/fenced-missing.txt)',
  '[[targets/fenced-wiki-missing]]',
  '```',
  '',
  '[missing-doc-ref]: targets/missing-reference',
  '[case-doc]: targets/case-sensitive',
  '[valid-pdf]: assets/manual.pdf',
  '[missing-spec]: assets/missing-spec.pdf',
  '',
].join('\n');

const DOCUMENTS = ['all-link-types', 'targets/existing-page', 'targets/Case Sensitive'] as const;

const FILES = ['assets/NOTICE', 'assets/existing.txt', 'assets/manual.pdf'] as const;

function buildInventory(): LocalTargetInventory {
  const documents = createTargetNamespace('document', DOCUMENTS);
  const files = createTargetNamespace('file', FILES);
  const tolerant = createTolerantDocumentResolver(documents);
  return {
    resolveDocument: (docName) => documents.resolve(docName),
    resolveFile: (path) => files.resolve(path),
    resolveFileByBasename: createFileBasenameResolver(files),
    resolveTolerantDocument: (docName) => tolerant(docName),
  };
}

function occurrenceKey(o: Pick<LocalTargetOccurrence, 'line' | 'column' | 'href'>): string {
  return `${o.line}:${o.column}:${o.href}`;
}

function planeADocumentTargets(markdown: string): Set<string> {
  const files = new Set<string>(FILES);
  const fileOracle = { hasFile: (path: string) => files.has(path) };
  const targets = new Set<string>();
  for (const edge of [
    ...extractMarkdownLinksFromMarkdown(markdown, SOURCE_DOC, 0, fileOracle),
    ...extractWikiLinksFromMarkdown(markdown, SOURCE_DOC),
  ]) {
    if (typeof edge.target === 'string' && edge.target.length > 0) targets.add(edge.target);
  }
  return targets;
}

interface Planes {
  occurrences: LocalTargetOccurrence[];
  assessmentByKey: Map<string, LocalTargetAssessment>;
  graphDocumentTargets: Set<string>;
}

function runPlanes(): Planes {
  const inventory = buildInventory();
  const occurrences = extractLocalTargetOccurrences(MATRIX);
  const assessments = assessLocalTargets(MATRIX, SOURCE_DOC, inventory);
  return {
    occurrences,
    assessmentByKey: new Map(assessments.map((a) => [occurrenceKey(a.occurrence), a])),
    graphDocumentTargets: planeADocumentTargets(MATRIX),
  };
}

function graphHasEdgeFor(href: string, graphDocumentTargets: Set<string>): boolean {
  return (
    graphDocumentTargets.has(href) ||
    graphDocumentTargets.has(href.replace(/^\//, '')) ||
    graphDocumentTargets.has(href.replace(/\.mdx?$/, ''))
  );
}

function describeOccurrence(o: LocalTargetOccurrence): string {
  return `line ${o.line} ${o.sourceForm} ${o.role} "${o.href}"`;
}

describe('link classification uniformity across the document-graph and local-target planes', () => {
  test('every recognized occurrence receives a canonical classification', () => {
    const { occurrences, assessmentByKey } = runPlanes();

    const unclassified = occurrences
      .filter((o) => !assessmentByKey.has(occurrenceKey(o)))
      .map(describeOccurrence);

    expect(unclassified).toEqual([]);
  });

  test('an occurrence is never both an existing file and a document edge', () => {
    const { occurrences, assessmentByKey, graphDocumentTargets } = runPlanes();

    const contradictions = occurrences
      .filter((o) => {
        const assessment = assessmentByKey.get(occurrenceKey(o));
        return (
          assessment?.targetKind === 'file' &&
          assessment.status === 'exact' &&
          graphHasEdgeFor(o.href, graphDocumentTargets)
        );
      })
      .map(describeOccurrence);

    expect(contradictions).toEqual([]);
  });

  test('document links are represented in the graph regardless of authored form', () => {
    const { occurrences, assessmentByKey, graphDocumentTargets } = runPlanes();

    const missingFromGraph = occurrences
      .filter((o) => {
        const assessment = assessmentByKey.get(occurrenceKey(o));
        return (
          assessment?.targetKind === 'document' &&
          o.role === 'link' &&
          !graphHasEdgeFor(o.href, graphDocumentTargets)
        );
      })
      .map(describeOccurrence);

    expect(missingFromGraph).toEqual([]);
  });

  test('both planes resolve a wiki target to the same identity from a nested source', () => {
    const nestedSource = 'notes/index';
    const markdown = '[[targets/existing-page]]\n\n![[targets/missing-embed]]\n';
    const inventory = buildInventory();

    const planeA = new Set(
      extractWikiLinksFromMarkdown(markdown, nestedSource).map((edge) => edge.target),
    );
    const planeB = assessLocalTargets(markdown, nestedSource, inventory);

    expect(planeB.map((a) => a.resolvedTarget)).toEqual([
      'targets/existing-page',
      'targets/missing-embed',
    ]);
    for (const assessment of planeB) {
      expect(planeA).toContain(assessment.resolvedTarget);
    }
  });

  test('a body with no reference definition still yields its inline document edges', () => {
    const inlineOnly =
      '# Doc\n\n[a](targets/existing-page.md)\n\n[b](targets/missing-markdown.md)\n';
    expect(planeADocumentTargets(inlineOnly)).toEqual(
      new Set(['targets/existing-page', 'targets/missing-markdown']),
    );
  });

  test('non-rendering contexts are inert in both planes', () => {
    const { occurrences, graphDocumentTargets } = runPlanes();

    const inertHrefs = [
      'assets/comment-missing.txt',
      'assets/pre-missing.txt',
      'assets/fenced-missing.txt',
    ];
    for (const href of inertHrefs) {
      expect(occurrences.map((o) => o.href)).not.toContain(href);
    }
    expect(graphDocumentTargets).not.toContain('targets/fenced-wiki-missing');
  });
});