Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
14.8 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file The compiled-doc contract and its sealed parsers.
 *
 * @input Any value that claims to be a compiled node or a compiled docs bundle
 *   — typically one read back from JSON.
 * @output The same value once it validates; a thrown Error naming the problems
 *   otherwise, carrying a compiler diagnostic (`unsupported_schema` or
 *   `invalid_bundle`). An unsupported schema version fails with its own message
 *   before anything else is checked.
 * @position The load boundary for compiled nodes that did not come straight
 *   from ./compile.mjs in this process. The value is returned as given, not
 *   rebuilt, so key order (which response JSON follows) survives. A node is
 *   plain JSON throughout, so nothing it holds can surprise a reader.
 */

import {SECTION_KEY_RE} from '../discovery/docs-section-key.mjs';
import {COMPILED_DOC_KINDS, COMPILED_DOC_SCHEMA_VERSION} from './compile.mjs';
import {diagnostic, diagnosticProblem} from './diagnostics.mjs';

const NODE_FIELDS = new Set([
  'schemaVersion',
  'kind',
  'stage',
  'id',
  'lang',
  'provenance',
  'sourceTitles',
  'sectionProviders',
  'doc',
]);
const RESOLVED_FIELDS = new Set([
  'status',
  'topic',
  'section',
  'previewType',
  'content',
]);

/** How many problems one message lists before it stops. */
const MAX_PROBLEMS = 10;

/** @param {unknown} value @returns {value is Record<string, any>} */
const isRecord = value =>
  value != null && typeof value === 'object' && !Array.isArray(value);

/** @param {unknown} value @returns {value is string} */
const isText = value => typeof value === 'string' && value !== '';

/**
 * A package name, never a location: provenance must not leak a path.
 * @param {unknown} value
 * @returns {boolean}
 */
const isPackageName = value =>
  isText(value) &&
  !value.startsWith('/') &&
  !value.startsWith('.') &&
  !value.startsWith('\\') &&
  !value.startsWith('file:') &&
  !/^[A-Za-z]:[\\/]/.test(value);

/**
 * Validate a compiled reference node.
 * @param {unknown} value
 * @returns {import('./compile.mjs').CompiledReferenceNode}
 */
export function parseCompiledReferenceNode(value) {
  const node = /** @type {any} */ (value);
  const skew = schemaVersionProblem(node);
  if (skew) throw compiledDocError('unsupported_schema', skew);
  const problems = jsonProblems(node, 'node');
  if (problems.length === 0) problems.push(...structureProblems(node));
  if (problems.length > 0) {
    throw compiledDocError(
      'invalid_bundle',
      `Invalid compiled doc node: ${problems.slice(0, MAX_PROBLEMS).join('; ')}`,
    );
  }
  return node;
}

/**
 * Where a value stops being plain JSON: anything but null, booleans, finite
 * numbers, strings, arrays and plain objects; a symbol key; or a cycle.
 * @param {unknown} value
 * @param {string} at
 * @param {Set<object>} [ancestors]
 * @param {string[]} [out]
 * @returns {string[]}
 */
function jsonProblems(value, at, ancestors = new Set(), out = []) {
  if (out.length >= MAX_PROBLEMS) return out;
  if (
    value === null ||
    typeof value === 'string' ||
    typeof value === 'boolean'
  ) {
    return out;
  }
  if (typeof value === 'number') {
    if (!Number.isFinite(value))
      out.push(`${at}: ${value} is not a JSON number`);
    return out;
  }
  if (value === undefined) {
    out.push(`${at}: undefined is not JSON`);
    return out;
  }
  if (typeof value !== 'object') {
    out.push(`${at}: a ${typeof value} is not JSON`);
    return out;
  }
  if (ancestors.has(value)) {
    out.push(`${at}: refers back to itself`);
    return out;
  }
  const proto = Object.getPrototypeOf(value);
  if (!Array.isArray(value) && proto !== Object.prototype && proto !== null) {
    out.push(
      `${at}: a ${proto?.constructor?.name ?? 'non-plain object'} is not JSON`,
    );
    return out;
  }
  if (Object.getOwnPropertySymbols(value).length > 0) {
    out.push(`${at}: has symbol keys`);
  }
  ancestors.add(value);
  if (Array.isArray(value)) {
    value.forEach((item, index) =>
      jsonProblems(item, `${at}[${index}]`, ancestors, out),
    );
  } else {
    for (const [key, item] of Object.entries(value)) {
      jsonProblems(item, `${at}.${key}`, ancestors, out);
    }
  }
  ancestors.delete(value);
  return out;
}

/**
 * The node's own shape, once it is known to be JSON.
 * @param {Record<string, any>} node
 * @returns {string[]}
 */
function structureProblems(node) {
  /** @type {string[]} */
  const problems = [];
  const unknown = Object.keys(node).filter(key => !NODE_FIELDS.has(key));
  if (unknown.length > 0)
    problems.push(`unknown fields: ${unknown.join(', ')}`);
  if (node.kind !== 'reference') problems.push('kind: expected "reference"');
  if (node.stage !== 'lowered' && node.stage !== 'linked') {
    problems.push('stage: expected "lowered" or "linked"');
  }
  if (!isText(node.id)) problems.push('id: expected a topic name');
  if (node.lang !== null && !isText(node.lang)) {
    problems.push('lang: expected a language or null');
  }
  const provenance = node.provenance;
  if (
    !isRecord(provenance) ||
    !isPackageName(provenance.provider) ||
    (provenance.replaces !== null && !isText(provenance.replaces)) ||
    !Array.isArray(provenance.extensions) ||
    !provenance.extensions.every(isPackageName)
  ) {
    problems.push(
      'provenance: expected {provider, replaces, extensions} naming packages, not paths',
    );
  }
  const providers = isRecord(node.sectionProviders)
    ? node.sectionProviders
    : null;
  if (!providers || !Object.values(providers).every(isText)) {
    problems.push('sectionProviders: expected section key -> provider id');
  }
  const titles = isRecord(node.sourceTitles) ? node.sourceTitles : null;
  if (!titles || !Object.values(titles).every(isText)) {
    problems.push('sourceTitles: expected section key -> authored title');
  }
  const doc = node.doc;
  if (
    !isRecord(doc) ||
    !isText(doc.name) ||
    !isText(doc.title) ||
    typeof doc.description !== 'string' ||
    !Array.isArray(doc.sections) ||
    doc.sections.length === 0
  ) {
    problems.push('doc: expected {name, title, description, sections}');
  } else {
    problems.push(...sectionProblems(doc.sections, titles, node.stage));
  }
  return problems;
}

/**
 * @param {any[]} sections
 * @param {Record<string, any> | null} titles
 * @param {unknown} stage
 * @returns {string[]}
 */
function sectionProblems(sections, titles, stage) {
  /** @type {string[]} */
  const problems = [];
  const seen = new Set();
  sections.forEach((section, index) => {
    const at = `doc.sections[${index}]`;
    if (
      !isRecord(section) ||
      typeof section.id !== 'string' ||
      !SECTION_KEY_RE.test(section.id)
    ) {
      problems.push(`${at}.id: expected a section key`);
      return;
    }
    if (seen.has(section.id)) {
      problems.push(`${at}.id: two sections have the key "${section.id}"`);
    }
    seen.add(section.id);
    if (!isText(section.title)) problems.push(`${at}.title: expected a title`);
    if (titles && !Object.hasOwn(titles, section.id)) {
      problems.push(
        `sourceTitles: no authored title for section "${section.id}"`,
      );
    }
    if (!Array.isArray(section.content)) {
      problems.push(`${at}.content: expected an array of blocks`);
      return;
    }
    section.content.forEach((/** @type {unknown} */ block, blockIndex) => {
      const where = `${at}.content[${blockIndex}]`;
      if (!isRecord(block) || !isText(block.type)) {
        problems.push(`${where}: expected a block with a type`);
        return;
      }
      if (block.type !== 'token-ref') return;
      const ref = `${where}: token reference to "${block.topic}"`;
      if (stage === 'lowered') {
        if ('resolved' in block) {
          problems.push(`${ref}: a lowered node carries no resolution`);
        }
        return;
      }
      if (!('resolved' in block)) {
        problems.push(`${ref}: a linked node resolves every reference`);
        return;
      }
      const problem = resolutionProblem(block.resolved);
      if (problem) problems.push(`${ref}: ${problem}`);
    });
  });
  return problems;
}

/**
 * @param {unknown} resolved
 * @returns {string | null}
 */
function resolutionProblem(resolved) {
  if (!isRecord(resolved)) return 'expected a resolution';
  switch (resolved.status) {
    case 'unknown-topic':
    case 'unknown-section':
      return Object.keys(resolved).length === 1 ? null : 'unexpected fields';
    case 'resolved': {
      if (!isText(resolved.topic)) return 'topic: expected a topic name';
      if (
        typeof resolved.section !== 'string' ||
        !SECTION_KEY_RE.test(resolved.section)
      ) {
        return 'section: expected a section key';
      }
      if ('previewType' in resolved && !isText(resolved.previewType)) {
        return 'previewType: expected a preview type';
      }
      if (
        !Array.isArray(resolved.content) ||
        !resolved.content.every(block => isRecord(block) && isText(block.type))
      ) {
        return 'content: expected blocks with a type';
      }
      const extra = Object.keys(resolved).filter(
        key => !RESOLVED_FIELDS.has(key),
      );
      return extra.length > 0 ? `unexpected fields: ${extra.join(', ')}` : null;
    }
    default:
      return `status: expected resolved, unknown-topic or unknown-section, got ${JSON.stringify(resolved.status)}`;
  }
}

const DOC_NODE_FIELDS = new Set([
  'schemaVersion',
  'kind',
  'stage',
  'id',
  'lang',
  'provenance',
  'doc',
]);
const BUNDLE_FIELDS = new Set([
  'schemaVersion',
  'lang',
  'nodes',
  'diagnostics',
]);

/**
 * A package-relative source, never a location on one machine.
 * @param {unknown} value
 * @returns {boolean}
 */
const isPackageSource = value =>
  isPackageName(value) &&
  !/(^|\/)\.\.(\/|$)/.test(/** @type {string} */ (value));

/**
 * An Error for a value that is not a compiled doc, carrying the diagnostic a
 * reader reports.
 * @param {'unsupported_schema' | 'invalid_bundle'} code
 * @param {string} message
 * @returns {Error & {diagnostic: import('./diagnostics.mjs').CompilerDiagnostic}}
 */
function compiledDocError(code, message) {
  const error = /** @type {Error & {diagnostic: any}} */ (new Error(message));
  error.diagnostic = diagnostic(code, {message});
  return error;
}

/**
 * @param {unknown} value
 */
function schemaVersionProblem(value) {
  const version = /** @type {any} */ (value)?.schemaVersion;
  return version === COMPILED_DOC_SCHEMA_VERSION
    ? null
    : `Compiled doc schema version ${JSON.stringify(version)} is not supported; this CLI reads version ${COMPILED_DOC_SCHEMA_VERSION}. Compile the docs again with this CLI.`;
}

/**
 * Validate a compiled node of any kind.
 * @param {unknown} value
 * @returns {import('./compile.mjs').CompiledDocNode | import('./compile.mjs').CompiledReferenceNode}
 */
export function parseCompiledDocNode(value) {
  const skew = schemaVersionProblem(value);
  if (skew) throw compiledDocError('unsupported_schema', skew);
  const problems = nodeProblems(value, 'node');
  if (problems.length > 0) {
    throw compiledDocError(
      'invalid_bundle',
      `Invalid compiled doc node: ${problems.slice(0, MAX_PROBLEMS).join('; ')}`,
    );
  }
  return /** @type {any} */ (value);
}

/**
 * Validate a compiled docs bundle: every node, every diagnostic, and one node
 * per id.
 * @param {unknown} value
 * @returns {import('./bundle.mjs').CompiledDocsBundle}
 */
export function parseCompiledDocsBundle(value) {
  const skew = schemaVersionProblem(value);
  if (skew) throw compiledDocError('unsupported_schema', skew);
  const bundle = /** @type {any} */ (value);
  /** @type {string[]} */
  const problems = jsonProblems(bundle, 'bundle');
  if (problems.length === 0) {
    const unknown = Object.keys(bundle).filter(key => !BUNDLE_FIELDS.has(key));
    if (unknown.length > 0)
      problems.push(`unknown fields: ${unknown.join(', ')}`);
    if (bundle.lang !== null && !isText(bundle.lang)) {
      problems.push('lang: expected a language or null');
    }
    if (!Array.isArray(bundle.nodes)) {
      problems.push('nodes: expected an array');
    } else {
      const ids = new Set();
      bundle.nodes.forEach(
        (/** @type {unknown} */ node, /** @type {number} */ index) => {
          for (const problem of nodeProblems(node, `nodes[${index}]`)) {
            problems.push(problem);
          }
          const id = /** @type {any} */ (node)?.id;
          if (ids.has(id))
            problems.push(`nodes[${index}].id: "${id}" appears twice`);
          ids.add(id);
        },
      );
    }
    if (!Array.isArray(bundle.diagnostics)) {
      problems.push('diagnostics: expected an array');
    } else {
      bundle.diagnostics.forEach(
        (/** @type {unknown} */ d, /** @type {number} */ index) => {
          const problem = diagnosticProblem(d);
          if (problem) problems.push(`diagnostics[${index}]: ${problem}`);
        },
      );
    }
  }
  if (problems.length > 0) {
    throw compiledDocError(
      'invalid_bundle',
      `Invalid compiled docs bundle: ${problems.slice(0, MAX_PROBLEMS).join('; ')}`,
    );
  }
  return bundle;
}

/**
 * Problems with one node of any kind, each prefixed with where it is.
 * @param {unknown} value
 * @param {string} at
 * @returns {string[]}
 */
function nodeProblems(value, at) {
  const node = /** @type {any} */ (value);
  if (node?.schemaVersion !== COMPILED_DOC_SCHEMA_VERSION) {
    return [`${at}.schemaVersion: expected ${COMPILED_DOC_SCHEMA_VERSION}`];
  }
  const json = jsonProblems(node, at);
  if (json.length > 0) return json;
  if (node.kind === 'reference') {
    return structureProblems(node).map(problem => `${at}: ${problem}`);
  }
  /** @type {string[]} */
  const problems = [];
  const unknown = Object.keys(node).filter(key => !DOC_NODE_FIELDS.has(key));
  if (unknown.length > 0)
    problems.push(`${at}: unknown fields: ${unknown.join(', ')}`);
  if (!COMPILED_DOC_KINDS.includes(node.kind)) {
    problems.push(
      `${at}.kind: ${JSON.stringify(node.kind)} is not a compiled doc kind`,
    );
  }
  if (node.stage !== 'lowered')
    problems.push(`${at}.stage: expected "lowered"`);
  if (!isText(node.id)) problems.push(`${at}.id: expected an id`);
  if (node.lang !== null && !isText(node.lang)) {
    problems.push(`${at}.lang: expected a language or null`);
  }
  const provenance = node.provenance;
  if (
    !isRecord(provenance) ||
    Object.keys(provenance).length !== 2 ||
    !isPackageName(provenance.provider) ||
    !isPackageSource(provenance.source)
  ) {
    problems.push(
      `${at}.provenance: expected {provider, source} naming a package and a path inside it, not a machine path`,
    );
  }
  if (!isRecord(node.doc) || !isText(node.doc.name)) {
    problems.push(`${at}.doc: expected a doc with a name`);
  } else if (
    (node.kind === 'page' || node.kind === 'block' || node.kind === 'theme') &&
    node.doc.type !== node.kind
  ) {
    problems.push(
      `${at}.doc.type: a ${node.kind} node holds a ${node.kind} doc`,
    );
  }
  return problems;
}