@artkit-ai/format-openui 0.0.0-stage → 0.2.0

package/src/index.ts

@@ -0,0 +1,221 @@
+import {
+  type AdapterContext,
+  type ApplyResult,
+  type ChangeSummary,
+  defineFormat,
+  type FormatAdapter,
+  type FormatInstructions,
+  type LintIssue,
+  type ReadRequest,
+  type ReadResult,
+  type ValidationResult,
+} from '@artkit-ai/core';
+import { uiComponents, uiLibrary, VISUAL_ROOTS } from '@artkit-ai/openui-components';
+import { createParser } from '@openuidev/lang-core';
+import { diffOpenUI } from './diff.js';
+import { lintOpenUI } from './lint.js';
+import { applyOpenUIOperation, type OpenUIOperation, openuiOperationSchema } from './operations.js';
+import { readOpenUI } from './read.js';
+import { componentOf, parseStatements, references, type Statement, serializeStatements } from './syntax.js';
+
+export { diffOpenUI } from './diff.js';
+export { lintOpenUI } from './lint.js';
+export * from './operations.js';
+export { readOpenUI } from './read.js';
+export * from './syntax.js';
+
+export const OPENUI_LIMITS = { declarations: 2000, slides: 100 };
+export const OPENUI_FORMAT_VERSION = 'openui-lang@1.1.0';
+
+export const OPENUI_INSTRUCTIONS: FormatInstructions = {
+  summary:
+    'OpenUI Lang for visuals: slide decks, dashboards, reports, prototypes and diagrams built from the artkit component library. One declaration per line; the first declaration is root = <Visual>(...).',
+  rules: [
+    'Start with root = Deck(...) for presentations, Dashboard, Report, Prototype or Diagram for the other visuals.',
+    'Declare each component on its own line with a lowercase name, then reference it from a parent by that name.',
+    'Use only components listed in the catalog with the positional arguments of their schema.',
+    'Give every slide a Title first; keep Bullets to six items or fewer.',
+    'Give every Image an alternative text as its second argument and an asset://<id> source.',
+    'Edit visuals by declaration: set_statement, insert_child, move_child, rename_statement; never rewrite the whole text.',
+  ],
+  examples: [
+    {
+      title: 'Two-slide deck',
+      operations: [
+        { op: 'set_statement', name: 'root', expr: 'Deck([capa, escopo])' },
+        {
+          op: 'set_statement',
+          name: 'capa',
+          expr: 'Slide("title", [Title("Portal de Fornecedores"), Subtitle("Grupo Meridiano")])',
+        },
+        {
+          op: 'set_statement',
+          name: 'escopo',
+          expr: 'Slide("title-content", [Title("Escopo em 13 módulos"), Bullets(["Cadastro e homologação", "Integração Protheus"])])',
+        },
+      ],
+    },
+  ],
+};
+
+const COMPONENT_NAMES = new Set(uiComponents.map((component) => component.name));
+
+function cycles(statements: readonly Statement[]): string[] {
+  const byName = new Map(statements.map((statement) => [statement.name, statement]));
+  const state = new Map<string, 'visiting' | 'done'>();
+  const found: string[] = [];
+  const visit = (name: string) => {
+    if (state.get(name) === 'done') return;
+    if (state.get(name) === 'visiting') {
+      found.push(name);
+      return;
+    }
+    state.set(name, 'visiting');
+    for (const ref of references(byName.get(name)?.expr ?? '')) if (byName.has(ref)) visit(ref);
+    state.set(name, 'done');
+  };
+  for (const statement of statements) visit(statement.name);
+  return found;
+}
+
+/** Validates OpenUI text: syntax, root, component names, references, cycles and the parser of OpenUI itself. */
+export function validateOpenUI(text: string): ValidationResult<string> {
+  const { statements, invalidLines } = parseStatements(text);
+  const issues: { path: string; message: string; hint?: string }[] = [];
+  for (const line of invalidLines) {
+    issues.push({
+      path: `content.line${line}`,
+      message: `A linha ${line} não é uma declaração.`,
+      hint: 'Use o formato nome = Componente(argumentos), uma por linha.',
+    });
+  }
+  const seen = new Set<string>();
+  for (const statement of statements) {
+    if (seen.has(statement.name)) {
+      issues.push({
+        path: `content.${statement.name}`,
+        message: `A declaração "${statement.name}" está repetida.`,
+        hint: 'Cada nome precisa ser único.',
+      });
+    }
+    seen.add(statement.name);
+    const component = componentOf(statement.expr);
+    if (!component || !COMPONENT_NAMES.has(component)) {
+      issues.push({
+        path: `content.${statement.name}`,
+        message: `"${component ?? statement.expr}" não é um componente da biblioteca.`,
+        hint: `Use um destes: ${[...COMPONENT_NAMES].slice(0, 12).join(', ')}, …`,
+      });
+    }
+  }
+  const root = statements.find((statement) => statement.name === 'root');
+  if (!root) {
+    issues.push({
+      path: 'content.root',
+      message: 'Falta a declaração root.',
+      hint: 'Comece com root = Deck(...) ou outro visual.',
+    });
+  } else if (!VISUAL_ROOTS.includes(componentOf(root.expr) as never)) {
+    issues.push({
+      path: 'content.root',
+      message: `A raiz "${componentOf(root.expr)}" não é um visual.`,
+      hint: `Use uma destas raízes: ${VISUAL_ROOTS.join(', ')}.`,
+    });
+  }
+  for (const name of cycles(statements)) {
+    issues.push({
+      path: `content.${name}`,
+      message: `A declaração "${name}" referencia a si mesma em um ciclo.`,
+      hint: 'Remova a referência circular.',
+    });
+  }
+  if (issues.length === 0 && root) {
+    const result = createParser(uiLibrary.toJSONSchema(), uiLibrary.root).parse(
+      serializeStatements(statements),
+    );
+    for (const error of result.meta.errors) {
+      issues.push({
+        path: `content.${error.statementId ?? 'root'}`,
+        message: error.message,
+        hint: 'Confira o componente e os argumentos no catálogo.',
+      });
+    }
+    for (const name of result.meta.unresolved) {
+      issues.push({
+        path: `content.${name}`,
+        message: `"${name}" é usada mas não foi declarada.`,
+        hint: 'Declare a referência em uma linha própria.',
+      });
+    }
+  }
+  if (issues.length > 0) return { ok: false, issues };
+  return { ok: true, content: serializeStatements(statements) };
+}
+
+/** OpenUI format adapter (spec §12), validated against the artkit component library. */
+export function createOpenUIFormat(): FormatAdapter<string, OpenUIOperation> {
+  return defineFormat({
+    format: 'openui',
+    formatVersion: OPENUI_FORMAT_VERSION,
+    readableVersions: [OPENUI_FORMAT_VERSION],
+    label: 'Visual',
+    empty: () => 'root = Deck([])\n',
+    validate(content: unknown, _ctx: AdapterContext): ValidationResult<string> {
+      if (typeof content !== 'string') {
+        return {
+          ok: false,
+          issues: [
+            {
+              path: 'content',
+              message: 'O visual deve ser texto OpenUI Lang.',
+              hint: 'Envie as declarações como texto.',
+            },
+          ],
+        };
+      }
+      return validateOpenUI(content);
+    },
+    operationSchema: openuiOperationSchema,
+    async apply(
+      content: string,
+      operations: OpenUIOperation[],
+      ctx: AdapterContext,
+    ): Promise<ApplyResult<string>> {
+      const state = { statements: parseStatements(content).statements, createdRefs: [] as string[] };
+      for (const op of operations) applyOpenUIOperation(state, op, ctx);
+      const text = serializeStatements(state.statements);
+      const validation = validateOpenUI(text);
+      if (!validation.ok)
+        ctx.fail(validation.issues[0]?.message ?? 'Visual inválido.', { hint: validation.issues[0]?.hint });
+      return {
+        content: validation.content,
+        createdRefs: state.createdRefs,
+        warnings: lintOpenUI(validation.content),
+      };
+    },
+    read(content: string, request: ReadRequest): ReadResult {
+      return readOpenUI(content, request);
+    },
+    diff: (before: string, after: string): ChangeSummary[] => diffOpenUI(before, after),
+    lint: (content: string): LintIssue[] => lintOpenUI(content),
+    parsePartial(raw: string): string | undefined {
+      if (raw.trim() === '') return undefined;
+      // Keep only complete lines: the last line may still be streaming.
+      const lines = raw.split('\n');
+      const complete = raw.endsWith('\n') ? lines : lines.slice(0, -1);
+      return `${complete.filter((line) => line.trim() !== '').join('\n')}\n`;
+    },
+    migrations: [],
+    limits: OPENUI_LIMITS,
+    measure: (content: string) => ({
+      declarations: parseStatements(content).statements.length,
+      slides: parseStatements(content).statements.filter(
+        (statement) => componentOf(statement.expr) === 'Slide',
+      ).length,
+    }),
+    instructions: OPENUI_INSTRUCTIONS,
+  });
+}
+
+/** Default OpenUI format adapter with the artkit component library. */
+export const openuiFormat = createOpenUIFormat();

package/src/lint.ts

@@ -0,0 +1,86 @@
+import type { LintIssue } from '@artkit-ai/core';
+import { argsOf, callsOf, childrenOf, componentOf, parseStatements, references, tokenize } from './syntax.js';
+
+const MAX_BULLETS = 6;
+const MAX_TEXT_CHARS = 400;
+
+function stringArgs(expr: string): string[] {
+  return tokenize(expr)
+    .filter((token) => token.kind === 'string')
+    .map((token) => token.text.slice(1, -1));
+}
+
+/** Lint (spec §12.6): slides without title, long bullet lists, long text, images without alt, unused declarations. */
+export function lintOpenUI(content: string): LintIssue[] {
+  const { statements } = parseStatements(content);
+  const byName = new Map(statements.map((statement) => [statement.name, statement]));
+  const referenced = new Set(statements.flatMap((statement) => references(statement.expr)));
+  const issues: LintIssue[] = [];
+  for (const statement of statements) {
+    const target = `node:${statement.name}`;
+    if (statement.name !== 'root' && !referenced.has(statement.name)) {
+      issues.push({
+        code: 'unused-declaration',
+        severity: 'info',
+        target,
+        message: `"${statement.name}" não é usada por nenhuma outra declaração.`,
+        hint: 'Remova a declaração ou inclua-a na lista de filhos.',
+      });
+    }
+    for (const call of callsOf(statement.expr)) {
+      const args = argsOf(call.inner);
+      if (call.component === 'Slide') {
+        const children = childrenOf(`X(${call.inner})`);
+        const hasTitle = children.some(
+          (child) => componentOf(child) === 'Title' || componentOf(byName.get(child)?.expr ?? '') === 'Title',
+        );
+        if (!hasTitle) {
+          issues.push({
+            code: 'slide-no-title',
+            severity: 'warning',
+            target,
+            message: `O slide "${statement.name}" não tem título.`,
+            hint: 'Inclua um Title como primeiro filho.',
+          });
+        }
+      }
+      if (call.component === 'Bullets') {
+        const count = stringArgs(args.join(', ')).length;
+        if (count > MAX_BULLETS) {
+          issues.push({
+            code: 'bullets-overflow',
+            severity: 'warning',
+            target,
+            message: `"${statement.name}" tem ${count} marcadores; o limite é ${MAX_BULLETS}.`,
+            hint: 'Divida em dois slides ou dois blocos.',
+          });
+        }
+      }
+      if (call.component === 'Text' || call.component === 'Title' || call.component === 'Subtitle') {
+        const longest = Math.max(0, ...stringArgs(call.inner).map((text) => text.length));
+        if (longest > MAX_TEXT_CHARS) {
+          issues.push({
+            code: 'text-overflow',
+            severity: 'warning',
+            target,
+            message: `"${statement.name}" tem ${longest} caracteres; o provável limite é ${MAX_TEXT_CHARS}.`,
+            hint: 'Encurte o texto ou use Bullets.',
+          });
+        }
+      }
+      if (call.component === 'Image') {
+        const hasAlt = stringArgs(call.inner).length >= 2;
+        if (!hasAlt) {
+          issues.push({
+            code: 'image-alt',
+            severity: 'warning',
+            target,
+            message: `A imagem "${statement.name}" não tem texto alternativo.`,
+            hint: 'Escreva Image("asset://id", "descrição").',
+          });
+        }
+      }
+    }
+  }
+  return issues;
+}

package/src/operations.ts

@@ -0,0 +1,172 @@
+import type { AdapterContext } from '@artkit-ai/core';
+import { z } from 'zod';
+import {
+  childrenOf,
+  componentOf,
+  formatStatement,
+  references,
+  removeReferences,
+  renameReferences,
+  type Statement,
+  setChildren,
+} from './syntax.js';
+
+const name = z
+  .string()
+  .regex(/^[a-z][A-Za-z0-9_]{0,63}$/, 'Declaration names start with a lowercase letter (e.g. "capa").');
+const expr = z
+  .string()
+  .min(3)
+  .max(4000)
+  .refine((text) => !text.includes('\n'), 'One declaration per line.')
+  .describe('Right-hand side, e.g. Slide("title", [Title("Portal")]).');
+
+export const openuiOperationSchema = z.discriminatedUnion('op', [
+  z.object({ op: z.literal('set_statement'), name, expr }).strict(),
+  z.object({ op: z.literal('remove_statement'), name, cascade: z.boolean().default(false) }).strict(),
+  z.object({ op: z.literal('rename_statement'), name, to: name }).strict(),
+  z
+    .object({
+      op: z.literal('insert_child'),
+      name,
+      child: name,
+      position: z.number().int().min(0).optional().describe('0-based position; omit to append.'),
+      after: name.optional().describe('Insert after this child name.'),
+    })
+    .strict(),
+  z.object({ op: z.literal('remove_child'), name, child: name }).strict(),
+  z.object({ op: z.literal('move_child'), name, child: name, position: z.number().int().min(0) }).strict(),
+]);
+
+export type OpenUIOperation = z.infer<typeof openuiOperationSchema>;
+
+export const OPENUI_OPERATION_NAMES = [
+  'set_statement',
+  'remove_statement',
+  'rename_statement',
+  'insert_child',
+  'remove_child',
+  'move_child',
+] as const;
+
+export interface OpenUIApplyState {
+  statements: Statement[];
+  createdRefs: string[];
+}
+
+function indexOfStatement(
+  statements: readonly Statement[],
+  target: string,
+  ctx: AdapterContext,
+  path: string,
+): number {
+  const index = statements.findIndex((statement) => statement.name === target);
+  if (index < 0) {
+    ctx.fail(`A declaração "${target}" não existe.`, {
+      path,
+      hint: 'Leia o outline e use um nome declarado nele.',
+    });
+  }
+  return index;
+}
+
+function referrersOf(statements: readonly Statement[], target: string): string[] {
+  return statements
+    .filter((statement) => statement.name !== target && references(statement.expr).includes(target))
+    .map((statement) => statement.name);
+}
+
+/** Applies one declaration operation on the list of statements. Order is kept; new statements are appended. */
+export function applyOpenUIOperation(
+  state: OpenUIApplyState,
+  op: OpenUIOperation,
+  ctx: AdapterContext,
+): void {
+  const statements = state.statements;
+  switch (op.op) {
+    case 'set_statement': {
+      if (!componentOf(op.expr) || !op.expr.includes('(')) {
+        ctx.fail(`A declaração "${op.name}" precisa chamar um componente, como Title("texto").`, {
+          path: 'expr',
+          hint: 'Escreva o componente com seus argumentos entre parênteses.',
+        });
+      }
+      const at = statements.findIndex((statement) => statement.name === op.name);
+      if (at >= 0) statements[at] = { name: op.name, expr: op.expr };
+      else {
+        statements.push({ name: op.name, expr: op.expr });
+        state.createdRefs.push(op.name);
+      }
+      return;
+    }
+    case 'remove_statement': {
+      const at = indexOfStatement(statements, op.name, ctx, 'name');
+      const referrers = referrersOf(statements, op.name);
+      if (referrers.length > 0 && !op.cascade) {
+        ctx.fail(`"${op.name}" ainda é usada por ${referrers.join(', ')}.`, {
+          path: 'cascade',
+          hint: 'Remova ou troque a referência antes, ou envie cascade: true para remover as referências junto.',
+        });
+      }
+      statements.splice(at, 1);
+      for (const statement of statements) statement.expr = removeReferences(statement.expr, op.name);
+      return;
+    }
+    case 'rename_statement': {
+      const at = indexOfStatement(statements, op.name, ctx, 'name');
+      if (statements.some((statement) => statement.name === op.to)) {
+        ctx.fail(`Já existe uma declaração chamada "${op.to}".`, { path: 'to', hint: 'Escolha outro nome.' });
+      }
+      statements[at]!.name = op.to;
+      for (const statement of statements) statement.expr = renameReferences(statement.expr, op.name, op.to);
+      state.createdRefs.push(op.to);
+      return;
+    }
+    case 'insert_child': {
+      const at = indexOfStatement(statements, op.name, ctx, 'name');
+      indexOfStatement(statements, op.child, ctx, 'child');
+      const current = childrenOf(statements[at]!.expr);
+      if (!/\[/.test(statements[at]!.expr)) {
+        ctx.fail(`A declaração "${op.name}" não tem lista de filhos.`, {
+          path: 'name',
+          hint: 'Escolha um componente que aceite filhos, como Slide ou Card.',
+        });
+      }
+      const items = current.filter((item) => item !== op.child);
+      let position = op.position ?? items.length;
+      if (op.after !== undefined) {
+        const index = items.indexOf(op.after);
+        if (index < 0)
+          ctx.fail(`"${op.after}" não está na lista de filhos de "${op.name}".`, { path: 'after' });
+        position = index + 1;
+      }
+      items.splice(Math.min(position, items.length), 0, op.child);
+      statements[at]!.expr = setChildren(statements[at]!.expr, items)!;
+      return;
+    }
+    case 'remove_child': {
+      const at = indexOfStatement(statements, op.name, ctx, 'name');
+      const items = childrenOf(statements[at]!.expr);
+      if (!items.includes(op.child)) {
+        ctx.fail(`"${op.child}" não está na lista de filhos de "${op.name}".`, { path: 'child' });
+      }
+      statements[at]!.expr = setChildren(
+        statements[at]!.expr,
+        items.filter((item) => item !== op.child),
+      )!;
+      return;
+    }
+    case 'move_child': {
+      const at = indexOfStatement(statements, op.name, ctx, 'name');
+      const items = childrenOf(statements[at]!.expr);
+      if (!items.includes(op.child))
+        ctx.fail(`"${op.child}" não está na lista de filhos de "${op.name}".`, { path: 'child' });
+      const rest = items.filter((item) => item !== op.child);
+      rest.splice(Math.min(op.position, rest.length), 0, op.child);
+      statements[at]!.expr = setChildren(statements[at]!.expr, rest)!;
+      return;
+    }
+  }
+}
+
+export { formatStatement };

package/src/read.ts

@@ -0,0 +1,59 @@
+import { ellipsis, type ProjectionItem, paginate, type ReadRequest, type ReadResult } from '@artkit-ai/core';
+import { childrenOf, componentOf, formatStatement, parseStatements, type Statement } from './syntax.js';
+
+function labelOf(expr: string): string {
+  const match = /"((?:[^"\\]|\\.)*)"/.exec(expr);
+  return match ? ellipsis(match[1]!, 60) : '';
+}
+
+function outlineLine(statement: Statement): string {
+  const component = componentOf(statement.expr) ?? '?';
+  const children = childrenOf(statement.expr);
+  const parts = [`- ${statement.name}: ${component}`];
+  const label = labelOf(statement.expr);
+  if (label) parts.push(`"${label}"`);
+  if (children.length > 0) parts.push(`(${children.length} filhos: ${children.join(', ')})`);
+  return parts.join(' ');
+}
+
+/** Compact reading (spec §12.4): `outline` from the root, `statements` by name, and `full`. */
+export function readOpenUI(content: string, request: ReadRequest): ReadResult {
+  const { statements } = parseStatements(content);
+  const budget = {
+    ...(request.maxTokens === undefined ? {} : { maxTokens: request.maxTokens }),
+    ...(request.cursor === undefined ? {} : { cursor: request.cursor }),
+    ...(request.charsPerToken === undefined ? {} : { charsPerToken: request.charsPerToken }),
+  };
+  if (request.mode === 'outline') {
+    const items: ProjectionItem[] = statements.map((statement) => {
+      const line = outlineLine(statement);
+      return { id: statement.name, text: line, outline: line };
+    });
+    const projection = paginate(items, {
+      header: 'Declarações (raiz primeiro):',
+      ...budget,
+      outlineOnly: true,
+    });
+    return {
+      text: projection.text,
+      truncated: projection.truncated,
+      ...(projection.cursor ? { cursor: projection.cursor } : {}),
+    };
+  }
+  const wanted =
+    request.mode === 'statements' && request.range
+      ? new Set(request.range.split(',').map((part) => part.trim()))
+      : undefined;
+  const items: ProjectionItem[] = statements
+    .filter((statement) => !wanted || wanted.has(statement.name))
+    .map((statement) => {
+      const line = formatStatement(statement);
+      return { id: statement.name, text: line, outline: ellipsis(line, 80) };
+    });
+  const projection = paginate(items, budget);
+  return {
+    text: projection.text,
+    truncated: projection.truncated,
+    ...(projection.cursor ? { cursor: projection.cursor } : {}),
+  };
+}