@bendyline/squisq 2.1.0 → 2.2.0

package/src/doc/validate.ts

@@ -1,575 +0,0 @@
-/**
- * Markdown document validation.
- *
- * `validateMarkdownSource()` gives authors and agents fast, structural
- * feedback on a squisq markdown document — the same checks the renderer
- * applies, surfaced as diagnostics instead of degraded slides:
- *
- * - unknown template names (with a did-you-mean suggestion)
- * - unknown drawing shapes, and shape annotations used outside a `{[drawing]}`
- * - `{[…]}` text that was not recognized as an annotation (bad quoting,
- *   non-heading placement, unknown inline icon)
- * - malformed heading-attribute values (`x=abc`, bad `startTime`) and
- *   non-numeric drawing-shape geometry
- * - `connectsTo` / drawing `from`/`to` targets that don't resolve,
- *   duplicate block ids, unparseable data fences (reported by `markdownToDoc`)
- * - image references missing from the provided asset set (.dbk contents)
- *
- * The CLI exposes this as `squisq validate <input>`; agents can also call
- * it directly and iterate until the diagnostics list is empty.
- */
-
-import type { Doc, Block, DocDiagnostic } from '../schemas/Doc.js';
-import type {
-  MarkdownDocument,
-  MarkdownHeading,
-  MarkdownNode,
-  HtmlNode,
-} from '../markdown/types.js';
-import { parseMarkdown } from '../markdown/parse.js';
-import { getChildren, extractPlainText } from '../markdown/utils.js';
-import { coerceAnnotationValues, KNOWN_BLOCK_META_KEYS } from '../markdown/annotationCoercion.js';
-import { markdownToDoc, flattenBlocks } from './markdownToDoc.js';
-import { parseStandaloneAnnotation } from './standaloneAnnotation.js';
-import { isDataFence, parseDataFence } from './structuredData.js';
-import { deriveTemplateInputs } from './templateInputs.js';
-import { lintTemplateParams } from './templates/inputDescriptors.js';
-import {
-  templateRegistry,
-  resolveTemplateName,
-  isShapeName,
-  normalizeShapeKind,
-  SHAPE_NAMES,
-} from './templates/index.js';
-import { TEMPLATE_ALIASES } from './templates/templateNames.js';
-import { nearestName } from './utils/nearest.js';
-
-// ============================================
-// Options & result
-// ============================================
-
-export interface ValidateOptions {
-  /**
-   * Known asset paths for image/video reference checks — typically the
-   * file list of a .dbk container or the document's folder. Relative
-   * references not present here produce a `missing-asset` warning.
-   * When omitted, asset checks are skipped.
-   */
-  assets?: ReadonlySet<string> | ((path: string) => boolean);
-
-  /**
-   * Additional template names to accept beyond the built-in registry and
-   * the document's own `customTemplates` (e.g. app-registered templates).
-   */
-  extraTemplates?: readonly string[];
-}
-
-export interface MarkdownValidationResult {
-  /** All findings, in source order where line information exists. */
-  diagnostics: DocDiagnostic[];
-  errorCount: number;
-  warningCount: number;
-  infoCount: number;
-  /** The converted Doc (conversion diagnostics are included above). */
-  doc: Doc;
-}
-
-// ============================================
-// Entry points
-// ============================================
-
-/**
- * Validate a squisq markdown source string. Parses, converts (collecting
- * the conversion's own diagnostics), and runs the structural checks above.
- */
-export function validateMarkdownSource(
-  source: string,
-  options?: ValidateOptions,
-): MarkdownValidationResult {
-  return validateMarkdownDoc(parseMarkdown(source), options);
-}
-
-/**
- * Validate an already-parsed MarkdownDocument. See {@link validateMarkdownSource}.
- */
-export function validateMarkdownDoc(
-  markdownDoc: MarkdownDocument,
-  options?: ValidateOptions,
-): MarkdownValidationResult {
-  const doc = markdownToDoc(markdownDoc);
-  const diagnostics: DocDiagnostic[] = [...(doc.diagnostics ?? [])];
-  const blocks = flattenBlocks(doc.blocks);
-
-  const knownTemplates = collectKnownTemplates(doc, options);
-  // Custom template names are skipped by the input linter — they carry
-  // arbitrary author-defined inputs the built-in descriptors can't know about.
-  const customNames = new Set<string>(doc.customTemplates?.map((t) => t.name) ?? []);
-
-  // Parent-aware walk: a `{[shape]}` annotation is only meaningful on the
-  // direct child of a `{[drawing]}` block, so the template check needs each
-  // block's parent. Drawing connectors are validated against their siblings.
-  const visit = (block: Block, parent: Block | undefined): void => {
-    checkTemplate(block, parent, knownTemplates, diagnostics);
-    checkAttributeCoercion(block, parent, diagnostics);
-    checkConflictingAnnotationKeys(block, diagnostics);
-    checkTemplateInputs(block, parent, customNames, diagnostics);
-    checkPossibleDataFences(block, diagnostics);
-    if (isDrawingBlock(block)) checkDrawingConnectors(block, diagnostics);
-    for (const child of block.children ?? []) visit(child, block);
-  };
-  for (const block of doc.blocks) visit(block, undefined);
-
-  checkUnrecognizedAnnotations(markdownDoc, diagnostics);
-
-  if (options?.assets) {
-    const hasAsset = normalizeAssetCheck(options.assets);
-    checkAssets(markdownDoc, blocks, hasAsset, diagnostics);
-  }
-
-  diagnostics.sort(
-    (a, b) => (a.line ?? Number.MAX_SAFE_INTEGER) - (b.line ?? Number.MAX_SAFE_INTEGER),
-  );
-
-  return {
-    diagnostics,
-    errorCount: diagnostics.filter((d) => d.severity === 'error').length,
-    warningCount: diagnostics.filter((d) => d.severity === 'warning').length,
-    infoCount: diagnostics.filter((d) => d.severity === 'info').length,
-    doc,
-  };
-}
-
-// ============================================
-// Template checks
-// ============================================
-
-function collectKnownTemplates(doc: Doc, options?: ValidateOptions): Set<string> {
-  return new Set<string>([
-    ...Object.keys(templateRegistry),
-    ...Object.keys(TEMPLATE_ALIASES),
-    ...(doc.customTemplates?.map((t) => t.name) ?? []),
-    ...(options?.extraTemplates ?? []),
-  ]);
-}
-
-/** True when `block` is a `{[drawing]}` container (after alias resolution). */
-function isDrawingBlock(block: Block): boolean {
-  return resolveTemplateName(block.template ?? '') === 'drawing';
-}
-
-function checkTemplate(
-  block: Block,
-  parent: Block | undefined,
-  known: Set<string>,
-  diagnostics: DocDiagnostic[],
-): void {
-  // Heading blocks carry the requested name on the heading annotation;
-  // heading-less standalone blocks carry it on `sourceAnnotation` (raw,
-  // un-resolved) — read whichever is present.
-  const requested =
-    block.sourceHeading?.templateAnnotation?.template ?? block.sourceAnnotation?.template;
-  if (!requested) return;
-
-  // Inside a drawing, the annotation names a shape primitive, not a template.
-  if (parent && isDrawingBlock(parent)) {
-    if (isShapeName(requested)) return;
-    const suggestion = nearestName(requested, new Set(SHAPE_NAMES), {
-      map: resolveTemplateName,
-    });
-    diagnostics.push({
-      severity: 'warning',
-      code: 'unknown-shape',
-      message:
-        `Unknown shape "${requested}" in drawing — the child will be skipped` +
-        (suggestion ? `. Did you mean "${suggestion}"?` : ''),
-      blockId: block.id,
-      ...lineOf(block),
-    });
-    return;
-  }
-
-  // A shape annotation outside a drawing has no parent to interpret it.
-  if (isShapeName(requested)) {
-    diagnostics.push({
-      severity: 'warning',
-      code: 'shape-outside-drawing',
-      message: `Shape "${requested}" is only recognized on a child heading of a {[drawing]} block`,
-      blockId: block.id,
-      ...lineOf(block),
-    });
-    return;
-  }
-
-  if (known.has(requested) || known.has(resolveTemplateName(requested))) return;
-
-  const suggestion = nearestName(requested, known, { map: resolveTemplateName });
-  diagnostics.push({
-    severity: 'warning',
-    code: 'unknown-template',
-    message:
-      `Unknown template "${requested}" — the block will render as a plain fallback card` +
-      (suggestion ? `. Did you mean "${suggestion}"?` : ''),
-    blockId: block.id,
-    ...lineOf(block),
-  });
-}
-
-/**
- * Lint a template block's `{[…]}` inputs against the built-in input
- * descriptors: unknown keys (with a did-you-mean), values outside a closed
- * enum / that fail coercion, and missing required inputs. All are warnings.
- *
- * Only built-in templates with descriptors are checked — shapes, drawing
- * children, custom templates, and not-yet-described built-ins are skipped
- * (`lintTemplateParams` returns `[]` for the latter). A `missing-input`
- * finding is suppressed when the value is actually satisfiable from the
- * block's own fields, structured data, or body derivation.
- */
-function checkTemplateInputs(
-  block: Block,
-  parent: Block | undefined,
-  customNames: ReadonlySet<string>,
-  diagnostics: DocDiagnostic[],
-): void {
-  const requested = block.sourceHeading?.templateAnnotation?.template;
-  if (!requested) return;
-  // Inside a drawing, the annotation names a shape primitive, not a template.
-  if (parent && isDrawingBlock(parent)) return;
-  if (isShapeName(requested)) return;
-
-  const canonical = resolveTemplateName(requested);
-  if (customNames.has(requested) || customNames.has(canonical)) return;
-
-  const params = block.sourceHeading?.templateAnnotation?.params ?? {};
-  for (const finding of lintTemplateParams(canonical, params)) {
-    if (finding.kind === 'missing-input' && isInputSatisfiable(canonical, block, finding.key)) {
-      continue;
-    }
-    diagnostics.push({
-      severity: 'warning',
-      code: finding.kind,
-      message: `Block "${block.id}": ${finding.message}`,
-      blockId: block.id,
-      ...lineOf(block),
-    });
-  }
-}
-
-/**
- * Whether a required template input is satisfiable even though it's absent
- * from the `{[…]}` params: present in a structured-data fence, carried as a
- * block-level field (e.g. `title` from the heading), or derivable from the
- * heading + body (`deriveTemplateInputs` in strict mode).
- */
-function isInputSatisfiable(canonical: string, block: Block, key: string): boolean {
-  if (block.templateData && key in block.templateData) return true;
-  if ((block as unknown as Record<string, unknown>)[key] != null) return true;
-  const derived = deriveTemplateInputs(canonical, block.title ?? '', block.contents);
-  return derived != null && key in derived;
-}
-
-/** Numeric geometry keys carried in a shape's `{[…]}` params. */
-const NUMERIC_SHAPE_KEYS = ['x', 'y', 'width', 'height', 'w', 'h', 'strokeWidth', 'borderRadius'];
-
-/** Re-run heading-attribute coercion to surface its warnings with context. */
-function checkAttributeCoercion(
-  block: Block,
-  parent: Block | undefined,
-  diagnostics: DocDiagnostic[],
-): void {
-  // Pandoc `{#id key=value}` params (x/y/connectsTo/startTime/duration).
-  const params = block.sourceHeading?.attributes?.params;
-  if (params) {
-    const { warnings } = coerceAnnotationValues(params);
-    for (const warning of warnings) {
-      diagnostics.push({
-        severity: 'warning',
-        code: 'invalid-attribute',
-        message: `Block "${block.id}": ${warning}`,
-        blockId: block.id,
-        ...lineOf(block),
-      });
-    }
-  }
-
-  // A drawing shape's geometry lives in its `{[shape …]}` params
-  // (templateOverrides), not the Pandoc block — validate those numerics too.
-  if (parent && isDrawingBlock(parent) && isShapeName(block.template)) {
-    const overrides = block.templateOverrides ?? {};
-    for (const key of NUMERIC_SHAPE_KEYS) {
-      const raw = overrides[key];
-      if (raw == null) continue;
-      const value = raw.replace(/,\s*$/, '').trim();
-      if (value !== '' && !Number.isFinite(Number(value))) {
-        diagnostics.push({
-          severity: 'warning',
-          code: 'invalid-attribute',
-          message: `Drawing shape "${block.id}": "${key}" is not a number (${JSON.stringify(raw)})`,
-          blockId: block.id,
-          ...lineOf(block),
-        });
-      }
-    }
-  }
-}
-
-/**
- * A heading can carry the same block-meta key in both the Pandoc `{k=v}`
- * block and the squiggly `{[tpl k=v]}` annotation. The Pandoc value wins
- * (same precedence as `makeBlock` in markdownToDoc), which is easy to miss
- * when the two disagree — surface an info diagnostic so the author knows
- * which value is in effect.
- */
-function checkConflictingAnnotationKeys(block: Block, diagnostics: DocDiagnostic[]): void {
-  const annotationParams = block.sourceHeading?.templateAnnotation?.params;
-  const pandocParams = block.sourceHeading?.attributes?.params;
-  if (!annotationParams || !pandocParams) return;
-
-  for (const key of Object.keys(KNOWN_BLOCK_META_KEYS)) {
-    const fromAnnotation = annotationParams[key];
-    const fromPandoc = pandocParams[key];
-    if (fromAnnotation == null || fromPandoc == null || fromAnnotation === fromPandoc) continue;
-    diagnostics.push({
-      severity: 'info',
-      code: 'conflicting-annotation-key',
-      message:
-        `"${key}" is set in both {[…]} (${fromAnnotation}) and {…} (${fromPandoc}) — ` +
-        `the {…} value wins.`,
-      blockId: block.id,
-      ...lineOf(block),
-    });
-  }
-}
-
-/**
- * A drawing's `line`/`arrow` connectors reference sibling shapes by id via
- * `from`/`to`; flag any that don't resolve (mirrors the `connectsTo`
- * unresolved-connection check, but for the `{[…]}` param form).
- */
-function checkDrawingConnectors(block: Block, diagnostics: DocDiagnostic[]): void {
-  const children = block.children ?? [];
-  const ids = new Set(children.map((c) => c.id));
-  for (const child of children) {
-    const kind = normalizeShapeKind(child.sourceHeading?.templateAnnotation?.template);
-    if (kind !== 'line' && kind !== 'arrow') continue;
-    const overrides = child.templateOverrides ?? {};
-    for (const key of ['from', 'to'] as const) {
-      const raw = overrides[key];
-      if (raw == null) continue;
-      const ref = raw.replace(/,\s*$/, '').trim();
-      if (ref && !ids.has(ref)) {
-        diagnostics.push({
-          severity: 'warning',
-          code: 'unresolved-connection',
-          message: `Drawing connector "${child.id}" references unknown ${key} "${ref}"`,
-          blockId: child.id,
-          ...lineOf(child),
-        });
-      }
-    }
-  }
-}
-
-/**
- * A plain ```json / ```yaml fence (no `data` marker) inside a template-
- * annotated block, whose content parses as a top-level object, is almost
- * certainly meant as template input — surface an info nudge to add the
- * `data` marker. Deliberately scoped to *annotated* blocks so ordinary code
- * samples in prose sections never trigger it.
- */
-function checkPossibleDataFences(block: Block, diagnostics: DocDiagnostic[]): void {
-  const annotated = !!(
-    block.sourceHeading?.templateAnnotation?.template || block.sourceAnnotation?.template
-  );
-  if (!annotated) return;
-
-  for (const node of block.contents ?? []) {
-    if (node.type !== 'code') continue;
-    const lang = node.lang?.toLowerCase();
-    if (lang !== 'json' && lang !== 'yaml' && lang !== 'yml') continue;
-    if (isDataFence(node)) continue; // already a data fence — nothing to nudge
-
-    const result = parseDataFence(node);
-    if (!result.data || Object.keys(result.data).length === 0) continue;
-
-    diagnostics.push({
-      severity: 'info',
-      code: 'possible-data-fence',
-      message:
-        `This ${lang} block renders as code — add "data" to the fence ` +
-        `(\`\`\`${lang} data) if it's meant as template input.`,
-      blockId: block.id,
-      ...(node.position ? { line: node.position.start.line } : lineOf(block)),
-    });
-  }
-}
-
-// ============================================
-// Unrecognized `{[…]}` text
-// ============================================
-
-const ANNOTATION_LIKE_RE = /\{\[/;
-
-/**
- * Flag literal `{[` text that survived parsing. On a heading this usually
- * means broken quoting; in body content it usually means the author
- * expected list-item/paragraph annotations, which only headings support
- * (or referenced an unknown inline icon).
- */
-function checkUnrecognizedAnnotations(
-  markdownDoc: MarkdownDocument,
-  diagnostics: DocDiagnostic[],
-): void {
-  const walk = (node: MarkdownNode, headingLine: number | undefined, topLevel: boolean): void => {
-    if (node.type === 'heading') {
-      const heading = node as MarkdownHeading;
-      const text = extractPlainText(heading);
-      if (ANNOTATION_LIKE_RE.test(text)) {
-        diagnostics.push({
-          severity: 'warning',
-          code: 'unparsed-annotation',
-          message:
-            `Heading "${truncate(text)}" contains "{[…]}" text that was not recognized — ` +
-            `check the quoting, or whether the token is a known inline icon`,
-          ...(heading.position ? { line: heading.position.start.line } : {}),
-        });
-      }
-      return; // heading inline children already covered by extractPlainText
-    }
-    // A *top-level* paragraph that is exactly a `{[templateName …]}` /
-    // `{[audio …]}` annotation is recognized (it becomes a standalone template
-    // block or a media clip) — don't flag it, and don't descend into its text.
-    // Nested paragraphs (inside a list / blockquote) are NOT extracted, so
-    // they still warn.
-    if (node.type === 'paragraph' && topLevel) {
-      const parsed = parseStandaloneAnnotation(node);
-      if (parsed && parsed.template != null) return;
-    }
-    if (node.type === 'text' && ANNOTATION_LIKE_RE.test(node.value)) {
-      diagnostics.push({
-        severity: 'warning',
-        code: 'unparsed-annotation',
-        message:
-          `Body text contains "{[…]}" — template annotations are recognized on headings ` +
-          `and as standalone paragraphs (or the token is not a known inline icon)`,
-        ...(node.position
-          ? { line: node.position.start.line }
-          : headingLine != null
-            ? { line: headingLine }
-            : {}),
-      });
-      return;
-    }
-    if (node.type === 'code') return; // code blocks legitimately contain {[
-    for (const child of getChildren(node)) {
-      walk(child, headingLine, false);
-    }
-  };
-
-  for (const child of markdownDoc.children) {
-    walk(child, child.position?.start.line, true);
-  }
-}
-
-// ============================================
-// Asset checks
-// ============================================
-
-function normalizeAssetCheck(
-  assets: ReadonlySet<string> | ((path: string) => boolean),
-): (path: string) => boolean {
-  if (typeof assets === 'function') return assets;
-  return (path: string) => assets.has(path) || assets.has(path.replace(/^\.\//, ''));
-}
-
-const URL_SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i;
-
-/** A reference that should resolve inside the bundle: relative, no scheme. */
-function isBundleRelative(url: string): boolean {
-  return (
-    url.length > 0 && !URL_SCHEME_RE.test(url) && !url.startsWith('//') && !url.startsWith('#')
-  );
-}
-
-/** Template param keys whose values reference media assets. */
-const ASSET_PARAM_KEYS = ['src', 'imageSrc', 'videoSrc', 'poster', 'backgroundImage'];
-
-function checkAssets(
-  markdownDoc: MarkdownDocument,
-  blocks: Block[],
-  hasAsset: (path: string) => boolean,
-  diagnostics: DocDiagnostic[],
-): void {
-  const report = (url: string, line?: number, blockId?: string) => {
-    if (!isBundleRelative(url) || hasAsset(url)) return;
-    diagnostics.push({
-      severity: 'warning',
-      code: 'missing-asset',
-      message: `Referenced asset "${url}" was not found in the bundle`,
-      ...(blockId ? { blockId } : {}),
-      ...(line != null ? { line } : {}),
-    });
-  };
-
-  // Markdown image nodes + raw-HTML <img src>.
-  const walk = (node: MarkdownNode): void => {
-    if (node.type === 'image') {
-      report(node.url, node.position?.start.line);
-    }
-    if (node.type === 'htmlBlock' || node.type === 'htmlInline') {
-      walkHtmlImages(node.htmlChildren, (src) => report(src, node.position?.start.line));
-    }
-    for (const child of getChildren(node)) walk(child);
-  };
-  for (const child of markdownDoc.children) walk(child);
-
-  // Media references in template params / structured data.
-  for (const block of blocks) {
-    const sources: Array<Record<string, unknown> | undefined> = [
-      block.templateOverrides,
-      block.templateData,
-    ];
-    for (const source of sources) {
-      if (!source) continue;
-      for (const key of ASSET_PARAM_KEYS) {
-        const value = source[key];
-        if (typeof value === 'string') {
-          report(value, block.sourceHeading?.position?.start.line, block.id);
-        }
-      }
-      const images = source['images'];
-      const list =
-        typeof images === 'string'
-          ? images.split(',').map((s) => s.trim())
-          : Array.isArray(images)
-            ? images.filter((i): i is string => typeof i === 'string')
-            : [];
-      for (const img of list) {
-        report(img, block.sourceHeading?.position?.start.line, block.id);
-      }
-    }
-  }
-}
-
-function walkHtmlImages(nodes: HtmlNode[], report: (src: string) => void): void {
-  for (const node of nodes) {
-    if (node.type !== 'htmlElement') continue;
-    if (node.tagName === 'img' && node.attributes.src) {
-      report(node.attributes.src);
-    }
-    walkHtmlImages(node.children, report);
-  }
-}
-
-// ============================================
-// Helpers
-// ============================================
-
-function lineOf(block: Block): { line: number } | Record<string, never> {
-  const line = block.sourceHeading?.position?.start.line;
-  return line != null ? { line } : {};
-}
-
-function truncate(text: string, max = 40): string {
-  return text.length <= max ? text : `${text.slice(0, max)}…`;
-}