0.9.2: Source view, schema checks without the YAML extension

Every Archify page can show its file's YAML in place. Diagrams get
Diagram | Graph | Source (Graph only inside a model), main.archify
Model | Graph | Source, registry and decision pages View | Source, and the
Graph page a Source segment. 2D | 3D moves left of that switch and hides
while Source shows.

The YAML opens in a CodeMirror editor inside the page (dist/source.js,
loaded on first use), themed with the page's colours. Edits go to the VS
Code document as WorkspaceEdits; outside changes come back to the page.
Undo and redo are the editor's own, since VS Code sends ⌘Z in a focused
webview to the webview; save and find stay VS Code's. Problems come from
the host only (what the Problems panel holds for the file) and are
counted on the Source segment; completion and hover come from the schema,
folded into one draft-07 document per diagram type.

The host now checks .archify files against the extension's schema with
ajv on the YAML as written, before archify validate, and checks
.archify-registry files against the registry schema for the first time.
Registry and decision pages become text editor providers. While Source
shows, new renders wait and appear when the picture comes back.

Show Source switches the page to Source; Open in Text Editor (the editor
title button) opens the text beside it, as Show Source did. The decision
schema is no longer given to the YAML extension. Fixed: YAML errors in
registry and decision files were reported on line 1; "Webview is
disposed" when a diagram closed mid-render; the model heading under the
toolbar in narrow editors.

src/language/diagnostics.ts

@@ -10,6 +10,7 @@ import { isArchifyFile } from '../sources/detect';
 import { log } from '../util/log';
 import path from 'node:path';
 import { diagnosticPointer, rangeForPointer, rangeForPointerYaml, yamlSyntaxProblems } from './jsonPointer';
+import { DIAGRAM_SCHEMA, REGISTRY_SCHEMA, SchemaChecker, SchemaProblem, readSchemas } from './schemaCheck';
 
 const JSON_LANGUAGES = new Set(['json', 'jsonc']);
 
@@ -33,6 +34,7 @@ export class DiagnosticsController implements vscode.Disposable {
   private readonly timers = new Map<string, NodeJS.Timeout>();
   private readonly sequence = new Map<string, number>();
   private readonly disposables: vscode.Disposable[];
+  private checker: SchemaChecker | undefined;
 
   constructor(
     private readonly context: vscode.ExtensionContext,
@@ -54,6 +56,22 @@ export class DiagnosticsController implements vscode.Disposable {
     this.revalidateAll();
   }
 
+  /** Our schemas, compiled on first use. */
+  private schemas(): SchemaChecker {
+    this.checker ??= new SchemaChecker(readSchemas(vscode.Uri.joinPath(this.context.extensionUri, 'schemas').fsPath));
+    return this.checker;
+  }
+
+  private schemaDiagnostic(doc: vscode.TextDocument, problem: SchemaProblem): vscode.Diagnostic {
+    const diagnostic = new vscode.Diagnostic(
+      new vscode.Range(doc.positionAt(problem.from), doc.positionAt(problem.to)),
+      problem.message,
+      vscode.DiagnosticSeverity.Error,
+    );
+    diagnostic.source = 'archify';
+    return diagnostic;
+  }
+
   private enabled(uri: vscode.Uri): boolean {
     return vscode.workspace.getConfiguration('archify', uri).get<boolean>('validation.enabled', true);
   }
@@ -136,6 +154,17 @@ export class DiagnosticsController implements vscode.Disposable {
       }
     }
 
+    if (isArchifyFile(doc.fileName)) {
+      // The schema check sees the source as written and answers at once; a
+      // file that fails it would fail archify validate the same way, so that
+      // runs only on files the schema accepts.
+      const schemaProblems = this.schemas().check(text, DIAGRAM_SCHEMA);
+      if (schemaProblems.length) {
+        this.collection.set(doc.uri, [...modelDiagnostics, ...schemaProblems.map((problem) => this.schemaDiagnostic(doc, problem))]);
+        return;
+      }
+    }
+
     try {
       const runtime = await runtimeFor(this.context, doc.uri);
       const result = await validate(runtime, source.type, source.json);
@@ -210,6 +239,10 @@ export class DiagnosticsController implements vscode.Disposable {
     const root = await this.models.rootOf(doc.uri);
     const rel = root ? path.relative(root.fsPath, doc.uri.fsPath) : path.basename(doc.uri.fsPath);
     const problems: ModelProblem[] = [...parseRegistry(text, rel).problems];
+    // The schema adds what the parser does not check (types, unknown keys,
+    // ids); a file the parser already rejects as a whole gets no second opinion.
+    const shapeless = problems.some((p) => /not valid YAML|must be a mapping|needs an "elements" mapping/.test(p.message));
+    const schemaProblems = shapeless ? [] : this.schemas().check(text, REGISTRY_SCHEMA);
     if (root) {
       try {
         const index = await this.models.index(root);
@@ -223,7 +256,10 @@ export class DiagnosticsController implements vscode.Disposable {
       problems.push({ message: `This registry is not inside a model: no main.archify above ${path.basename(doc.uri.fsPath)}.`, severity: 'warning', line: 0 });
     }
     if (seq !== this.sequence.get(doc.uri.toString()) || doc.isClosed) return;
-    this.collection.set(doc.uri, problems.map((problem) => this.modelDiagnostic(doc, text, 'yaml', problem)));
+    this.collection.set(doc.uri, [
+      ...problems.map((problem) => this.modelDiagnostic(doc, text, 'yaml', problem)),
+      ...schemaProblems.map((problem) => this.schemaDiagnostic(doc, problem)),
+    ]);
   }
 
   dispose(): void {

src/language/editorSchemas.ts

@@ -0,0 +1,85 @@
+import { DIAGRAM_SCHEMA, REGISTRY_SCHEMA } from './schemaCheck';
+
+type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+
+/**
+ * Schemas for completion and hover in the Source view. The editor's schema
+ * library reads one draft-07 document, while ours are 2020-12 files that
+ * refer to each other; so the referenced files are folded into `$defs` and
+ * 2020-12 tuples become draft-07 ones. Problems never come from these
+ * copies (the host checks with the originals), only suggestions.
+ */
+export class EditorSchemas {
+  private readonly cache = new Map<string, object>();
+
+  constructor(private readonly schemas: Record<string, object>) {}
+
+  /** The schema for a file kind; for diagrams the one of its diagram_type. */
+  forSource(kind: 'diagram' | 'registry' | 'decision', text: string): { key: string; schema: object } | undefined {
+    if (kind === 'decision') return undefined;
+    if (kind === 'registry') return this.get(REGISTRY_SCHEMA);
+    const type = /^diagram_type:\s*["']?([a-z]+)/m.exec(text)?.[1];
+    const name = type && this.schemas[`${type}.schema.json`] ? `${type}.schema.json` : DIAGRAM_SCHEMA;
+    return this.get(name);
+  }
+
+  private get(name: string): { key: string; schema: object } | undefined {
+    if (!this.schemas[name]) return undefined;
+    if (!this.cache.has(name)) this.cache.set(name, bundleSchema(this.schemas, name));
+    return { key: name, schema: this.cache.get(name)! };
+  }
+}
+
+const defKey = (file: string) => `file:${file}`;
+
+/** One self-contained draft-07 shaped schema for `root` and every file it refers to. */
+export function bundleSchema(schemas: Record<string, object>, root: string): object {
+  const files = new Set<string>([root]);
+  const queue = [root];
+  while (queue.length) {
+    const file = queue.shift()!;
+    for (const ref of refsOf(schemas[file] as Json)) {
+      const target = ref.split('#')[0];
+      if (target && !files.has(target) && schemas[target]) {
+        files.add(target);
+        queue.push(target);
+      }
+    }
+  }
+  const base = (file: string) => (file === root ? '#' : `#/$defs/${defKey(file)}`);
+  const rewrite = (node: Json, file: string): Json => {
+    if (Array.isArray(node)) return node.map((item) => rewrite(item, file));
+    if (!node || typeof node !== 'object') return node;
+    const out: { [key: string]: Json } = {};
+    for (const [key, value] of Object.entries(node)) {
+      if (key === '$ref' && typeof value === 'string') {
+        const [target, pointer = ''] = value.split('#');
+        out.$ref = `${base(target || file)}${pointer}`;
+      } else if (key !== '$schema' && key !== '$id') {
+        out[key] = rewrite(value, file);
+      }
+    }
+    if (out.prefixItems) {
+      if (out.items === false) out.additionalItems = false;
+      else if (out.items !== undefined) out.additionalItems = out.items;
+      out.items = out.prefixItems;
+      delete out.prefixItems;
+    }
+    return out;
+  };
+  const bundled = rewrite(schemas[root] as Json, root) as { [key: string]: Json };
+  const defs = { ...((bundled.$defs as { [key: string]: Json } | undefined) ?? {}) };
+  for (const file of files) if (file !== root) defs[defKey(file)] = rewrite(schemas[file] as Json, file);
+  return { ...bundled, $defs: defs };
+}
+
+function refsOf(node: Json, out: string[] = []): string[] {
+  if (Array.isArray(node)) node.forEach((item) => refsOf(item, out));
+  else if (node && typeof node === 'object') {
+    for (const [key, value] of Object.entries(node)) {
+      if (key === '$ref' && typeof value === 'string') out.push(value);
+      else refsOf(value, out);
+    }
+  }
+  return out;
+}

src/language/schemaCheck.ts

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import Ajv2020, { ErrorObject, ValidateFunction } from 'ajv/dist/2020';
+import { LineCounter, Node, isMap, isScalar, isSeq, parseDocument } from 'yaml';
+
+/** A schema problem placed on the YAML node it is about; offsets into the text. */
+export interface SchemaProblem {
+  from: number;
+  to: number;
+  message: string;
+  /** 'yaml' for a syntax error (only the first is reported), 'schema' otherwise. */
+  kind: 'yaml' | 'schema';
+}
+
+/** Schema file names in schemas/ that a file kind is checked against. */
+export const DIAGRAM_SCHEMA = 'archify.schema.json';
+export const REGISTRY_SCHEMA = 'archify-registry.schema.json';
+
+/** Reads every *.schema.json of a folder: file name → schema. */
+export function readSchemas(folder: string): Record<string, object> {
+  return Object.fromEntries(
+    fs
+      .readdirSync(folder)
+      .filter((name) => name.endsWith('.schema.json'))
+      .map((name) => [name, JSON.parse(fs.readFileSync(path.join(folder, name), 'utf8')) as object]),
+  );
+}
+
+/**
+ * Checks YAML text against our JSON Schemas (draft 2020-12, with ajv), so the
+ * Source view and the Problems panel see the same problems whether or not a
+ * YAML extension is installed. Schemas refer to each other by file name.
+ */
+export class SchemaChecker {
+  private readonly ajv = new Ajv2020({ allErrors: true, strict: false });
+  private readonly compiled = new Map<string, ValidateFunction | undefined>();
+
+  constructor(schemas: Record<string, object>) {
+    for (const [name, schema] of Object.entries(schemas)) this.ajv.addSchema(schema, name);
+  }
+
+  private validator(name: string): ValidateFunction | undefined {
+    if (!this.compiled.has(name)) this.compiled.set(name, this.ajv.getSchema(name));
+    return this.compiled.get(name);
+  }
+
+  check(text: string, schema: string): SchemaProblem[] {
+    const doc = parseDocument(text, { lineCounter: new LineCounter(), prettyErrors: false, uniqueKeys: false });
+    if (doc.errors.length) {
+      // Later syntax errors are usually echoes of the first.
+      const error = doc.errors[0];
+      return [{ from: error.pos[0], to: Math.max(error.pos[1], error.pos[0] + 1), message: `YAML: ${error.message.split('\n')[0]}`, kind: 'yaml' }];
+    }
+    const validate = this.validator(schema);
+    if (!validate || validate(doc.toJS())) return [];
+    return collapse(validate.errors ?? []).map((error) => {
+      const [from, to] = rangeFor(doc.contents, error, text.length);
+      return { from, to, message: describe(error), kind: 'schema' as const };
+    });
+  }
+}
+
+/** oneOf/anyOf/if produce a cascade; keep the errors a person can act on. */
+function collapse(errors: ErrorObject[]): ErrorObject[] {
+  const seen = new Set<string>();
+  return errors
+    .filter((e) => !['if', 'oneOf', 'anyOf', 'allOf'].includes(e.keyword))
+    .filter((e) => {
+      const key = `${e.instancePath}|${e.keyword}|${JSON.stringify(e.params)}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+}
+
+/** "/connections/4/label" → "connections[4].label". */
+export function readablePointer(pointer: string): string {
+  if (!pointer) return 'the file';
+  return pointer
+    .split('/')
+    .slice(1)
+    .map((part) => (/^\d+$/.test(part) ? `[${part}]` : `.${part.replace(/~1/g, '/').replace(/~0/g, '~')}`))
+    .join('')
+    .replace(/^\./, '');
+}
+
+function describe(e: ErrorObject): string {
+  const where = readablePointer(e.instancePath);
+  const params = e.params as Record<string, unknown>;
+  switch (e.keyword) {
+    case 'additionalProperties':
+      return `Unknown key "${params.additionalProperty}" in ${where}.`;
+    case 'required':
+      return `"${params.missingProperty}" is required in ${where}.`;
+    case 'enum':
+      return `${where} must be one of: ${(params.allowedValues as unknown[]).join(', ')}.`;
+    case 'const':
+      return `${where} must be ${JSON.stringify(params.allowedValue)}.`;
+    case 'type': {
+      const type = String(params.type);
+      return `${where} must be ${type === 'array' ? 'a list' : type === 'object' ? 'a mapping' : `a ${type}`}.`;
+    }
+    case 'minItems':
+    case 'maxItems': {
+      const limit = Number(params.limit);
+      return `${where} needs ${e.keyword === 'minItems' ? 'at least' : 'at most'} ${limit} item${limit === 1 ? '' : 's'}.`;
+    }
+    case 'propertyNames':
+      return `"${params.propertyName}" in ${where} is not a valid id: start with a letter; letters, digits, - and _ after.`;
+    default:
+      return `${where} ${e.message ?? 'is not valid'}.`;
+  }
+}
+
+function keyText(key: unknown): string {
+  return isScalar(key) ? String(key.value) : String(key);
+}
+
+/** The node an error is about: the offending key for unknown keys, else the value. */
+function rangeFor(root: Node | null, error: ErrorObject, length: number): [number, number] {
+  const parts = error.instancePath.split('/').slice(1).map((p) => p.replace(/~1/g, '/').replace(/~0/g, '~'));
+  let node: unknown = root;
+  let keyNode: Node | null = null;
+  for (const part of parts) {
+    if (isMap(node)) {
+      const pair = node.items.find((p) => keyText(p.key) === part);
+      if (!pair) break;
+      keyNode = pair.key as Node;
+      node = pair.value;
+    } else if (isSeq(node)) {
+      keyNode = null;
+      node = node.items[Number(part)];
+    } else break;
+  }
+  const params = error.params as Record<string, unknown>;
+  const extra = params.additionalProperty ?? params.propertyName;
+  if (extra !== undefined && isMap(node)) {
+    const pair = node.items.find((p) => keyText(p.key) === String(extra));
+    const range = (pair?.key as Node | undefined)?.range;
+    if (range) return [range[0], range[1]];
+  }
+  if (error.keyword === 'required' && keyNode?.range) return [keyNode.range[0], keyNode.range[1]];
+  const target = (node as Node | undefined)?.range ? (node as Node) : keyNode;
+  if (!target?.range) return [0, Math.min(1, length)];
+  // A block mapping or list spans many lines; mark its first character only.
+  if ((isMap(target) || isSeq(target)) && !target.flow) return [target.range[0], target.range[0] + 1];
+  return [target.range[0], Math.max(target.range[1], target.range[0] + 1)];
+}