@artkit-ai/core 0.1.0 → 0.2.0

package/dist/kind.d.ts

@@ -1,156 +0,0 @@
-import { z } from 'zod';
-import type { ErrorIssue } from './errors.js';
-import type { Theme } from './theme.js';
-export type ProjectionMode = 'outline' | 'full' | 'range';
-export interface ProjectionOptions {
-    mode: ProjectionMode;
-    /**
-     * Kind-specific range: block ids ("intro..escopo"), A1 range ("Resumo!A1:D20"), slide ids or 1-based
-     * indexes ("3-5"), or a group id for diagrams.
-     */
-    range?: string;
-    /** Token budget; text is cut at an item boundary and a cursor is returned. */
-    maxTokens?: number;
-    /** Continuation cursor returned by a previous truncated projection. */
-    cursor?: string;
-    /** Characters per token used for the estimate (default 4). */
-    charsPerToken?: number;
-    locale: string;
-    theme?: Theme;
-}
-export interface Projection {
-    text: string;
-    truncated: boolean;
-    /** Present when truncated: pass it back to continue reading. */
-    cursor?: string;
-    /** Outline of what was left out, so the model can jump with `range`. */
-    remainingOutline?: string;
-}
-export type LintSeverity = 'warning' | 'info';
-export interface LintIssue {
-    code: string;
-    severity: LintSeverity;
-    /** `block:intro`, `cell:Resumo!D14`, `slide:cronograma`, `node:api`… */
-    target: string;
-    message: string;
-    hint?: string;
-}
-export interface LintContext {
-    locale: string;
-    theme: Theme;
-}
-export type ChangeType = 'added' | 'removed' | 'changed' | 'moved';
-export interface ChangeSummary {
-    type: ChangeType;
-    /** `block:premissa-api`, `cell:Resumo!D14`, `slide:cronograma`, `envelope:title`… */
-    target: string;
-    summary: string;
-}
-export interface Migration {
-    from: number;
-    to: number;
-    migrate(content: unknown): unknown;
-}
-/** Limits are plain counters, compared with what `measure` returns under the same keys (spec §6.6). */
-export type KindLimits = Record<string, number>;
-export interface KindExample {
-    title: string;
-    /**
-     * Alternative input that creates the example (e.g. `{ format: 'mermaid', source: 'flowchart LR…' }`).
-     * When `content` is also given, it is the content the input must produce.
-     */
-    input?: {
-        format: string;
-        source: unknown;
-    };
-    content?: unknown;
-    operations?: unknown[];
-}
-export interface KindInstructions {
-    /** What the kind is and when to use it. */
-    summary: string;
-    /** Short, verifiable rules. */
-    rules: string[];
-    examples: KindExample[];
-}
-export interface ContentInput<Content> {
-    /** Shown in model instructions. */
-    description: string;
-    schema: z.ZodType<unknown>;
-    /** Deterministic conversion. Throw `ArtifactError('INVALID_CONTENT')` on bad input. */
-    toContent(input: unknown, ctx: InputContext): Content;
-}
-export interface InputContext {
-    locale: string;
-    /**
-     * Records a non-blocking conversion note (an ignored directive, a mapped shape). Notes are returned
-     * to the caller as `info` lint issues with code `input-note`.
-     */
-    note?(message: string): void;
-}
-export interface IdContext {
-    /** Deterministic id for a new item, e.g. `nextId('p')` → `p12`. */
-    nextId(prefix: string): string;
-    /** True when the id already exists in the content (including ids created earlier in the batch). */
-    hasId(id: string): boolean;
-    /** Registers an explicitly provided id so later operations in the batch see it. */
-    reserveId(id: string): void;
-}
-export interface ApplyContext extends IdContext {
-    /** Aborts the batch with `OPERATION_FAILED` and a model-facing hint. */
-    fail(message: string, options?: {
-        hint?: string;
-        path?: string;
-    }): never;
-    locale: string;
-}
-/**
- * Contract every kind implements, native or third-party (spec §7).
- * `apply` mutates a clone and must be pure: no clock, network or randomness.
- */
-export interface ArtifactKind<Content = unknown, Operation = unknown> {
-    kind: string;
-    version: number;
-    label: string;
-    contentSchema: z.ZodType<Content>;
-    operationSchema: z.ZodType<Operation>;
-    /** Smallest valid content, used for skeleton creation. */
-    empty(): Content;
-    /**
-     * Prepares raw content before validation: fills missing ids deterministically (ids are optional on
-     * creation, spec §6.2). Must not throw on malformed input; validation reports problems afterwards.
-     */
-    normalize?(raw: unknown, ctx: IdContext): unknown;
-    apply(draft: Content, op: Operation, ctx: ApplyContext): void;
-    /** Every item id in the content (unique across the whole artifact). */
-    ids(content: Content): Iterable<string>;
-    /** Integrity rules beyond the schema (references, unique ids, table widths). Empty array means valid. */
-    validate?(content: Content, locale?: string): ErrorIssue[];
-    /** Counters checked against `limits`. */
-    measure?(content: Content): Record<string, number>;
-    /** Derived step after operations (e.g. formula recalculation). Mutates the draft; must stay deterministic. */
-    derive?(draft: Content): void;
-    /** Item targets an operation touches, used for automatic rebase. Defaults to diff-based detection. */
-    targets?(op: Operation): string[];
-    project(content: Content, options: ProjectionOptions): Projection;
-    lint(content: Content, ctx: LintContext): LintIssue[];
-    /** `locale` selects the language of the summaries (pt-BR or English). */
-    diff(before: Content, after: Content, locale?: string): ChangeSummary[];
-    /** Best-effort preview while the model is still streaming; drops incomplete trailing items. */
-    parsePartial(raw: unknown): Content | undefined;
-    inputs?: Record<string, ContentInput<Content>>;
-    migrations: Migration[];
-    limits: KindLimits;
-    instructions: KindInstructions;
-}
-export type AnyArtifactKind = ArtifactKind<any, any>;
-export declare class KindDefinitionError extends Error {
-    constructor(kind: string, problem: string);
-}
-/**
- * Validates a kind definition and returns it unchanged. Use it for third-party kinds (spec §20);
- * the registry runs the same checks on `register`.
- */
-export declare function defineKind<Content, Operation>(kind: ArtifactKind<Content, Operation>): ArtifactKind<Content, Operation>;
-export declare function assertKindContract(kind: AnyArtifactKind): void;
-//# sourceMappingURL=kind.d.ts.map

package/dist/kind.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"kind.d.ts","sourceRoot":"","sources":["../src/kind.ts"],"names":[],"mappings":"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"}

package/dist/kind.js

@@ -1,52 +0,0 @@
-import { z } from 'zod';
-export class KindDefinitionError extends Error {
-    constructor(kind, problem) {
-        super(`Invalid kind "${kind}": ${problem}`);
-        this.name = 'KindDefinitionError';
-    }
-}
-const KIND_NAME = /^[a-z][a-z0-9-]{0,63}$/;
-/**
- * Validates a kind definition and returns it unchanged. Use it for third-party kinds (spec §20);
- * the registry runs the same checks on `register`.
- */
-export function defineKind(kind) {
-    assertKindContract(kind);
-    return kind;
-}
-export function assertKindContract(kind) {
-    const name = typeof kind?.kind === 'string' ? kind.kind : '<unnamed>';
-    if (!KIND_NAME.test(name))
-        throw new KindDefinitionError(name, 'kind must match /^[a-z][a-z0-9-]{0,63}$/');
-    if (!Number.isInteger(kind.version) || kind.version < 1)
-        throw new KindDefinitionError(name, 'version must be an integer >= 1');
-    if (!(kind.contentSchema instanceof z.ZodType))
-        throw new KindDefinitionError(name, 'contentSchema must be a zod schema');
-    if (!(kind.operationSchema instanceof z.ZodType))
-        throw new KindDefinitionError(name, 'operationSchema must be a zod schema');
-    for (const fn of ['empty', 'apply', 'ids', 'project', 'lint', 'diff', 'parsePartial']) {
-        if (typeof kind[fn] !== 'function')
-            throw new KindDefinitionError(name, `${fn} must be a function`);
-    }
-    if (!Array.isArray(kind.migrations))
-        throw new KindDefinitionError(name, 'migrations must be an array');
-    let expected = 1;
-    for (const migration of [...kind.migrations].sort((a, b) => a.from - b.from)) {
-        if (migration.from !== expected || migration.to !== migration.from + 1) {
-            throw new KindDefinitionError(name, `migrations must form a chain 1→2→…→${kind.version}`);
-        }
-        expected = migration.to;
-    }
-    if (kind.migrations.length > 0 && expected !== kind.version) {
-        throw new KindDefinitionError(name, `migrations end at ${expected} but version is ${kind.version}`);
-    }
-    if (!kind.instructions ||
-        typeof kind.instructions.summary !== 'string' ||
-        !Array.isArray(kind.instructions.rules)) {
-        throw new KindDefinitionError(name, 'instructions need summary, rules and examples');
-    }
-    const empty = kind.contentSchema.safeParse(kind.empty());
-    if (!empty.success)
-        throw new KindDefinitionError(name, 'empty() does not satisfy contentSchema');
-}
-//# sourceMappingURL=kind.js.map

package/dist/kind.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"kind.js","sourceRoot":"","sources":["../src/kind.ts"],"names":[],"mappings":"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"}

package/src/kind.ts

@@ -1,217 +0,0 @@
-import { z } from 'zod';
-import type { ErrorIssue } from './errors.js';
-import type { Theme } from './theme.js';
-
-export type ProjectionMode = 'outline' | 'full' | 'range';
-
-export interface ProjectionOptions {
-  mode: ProjectionMode;
-  /**
-   * Kind-specific range: block ids ("intro..escopo"), A1 range ("Resumo!A1:D20"), slide ids or 1-based
-   * indexes ("3-5"), or a group id for diagrams.
-   */
-  range?: string;
-  /** Token budget; text is cut at an item boundary and a cursor is returned. */
-  maxTokens?: number;
-  /** Continuation cursor returned by a previous truncated projection. */
-  cursor?: string;
-  /** Characters per token used for the estimate (default 4). */
-  charsPerToken?: number;
-  locale: string;
-  theme?: Theme;
-}
-
-export interface Projection {
-  text: string;
-  truncated: boolean;
-  /** Present when truncated: pass it back to continue reading. */
-  cursor?: string;
-  /** Outline of what was left out, so the model can jump with `range`. */
-  remainingOutline?: string;
-}
-
-export type LintSeverity = 'warning' | 'info';
-
-export interface LintIssue {
-  code: string;
-  severity: LintSeverity;
-  /** `block:intro`, `cell:Resumo!D14`, `slide:cronograma`, `node:api`… */
-  target: string;
-  message: string;
-  hint?: string;
-}
-
-export interface LintContext {
-  locale: string;
-  theme: Theme;
-}
-
-export type ChangeType = 'added' | 'removed' | 'changed' | 'moved';
-
-export interface ChangeSummary {
-  type: ChangeType;
-  /** `block:premissa-api`, `cell:Resumo!D14`, `slide:cronograma`, `envelope:title`… */
-  target: string;
-  summary: string;
-}
-
-export interface Migration {
-  from: number;
-  to: number;
-  migrate(content: unknown): unknown;
-}
-
-/** Limits are plain counters, compared with what `measure` returns under the same keys (spec §6.6). */
-export type KindLimits = Record<string, number>;
-
-export interface KindExample {
-  title: string;
-  /**
-   * Alternative input that creates the example (e.g. `{ format: 'mermaid', source: 'flowchart LR…' }`).
-   * When `content` is also given, it is the content the input must produce.
-   */
-  input?: { format: string; source: unknown };
-  content?: unknown;
-  operations?: unknown[];
-}
-
-export interface KindInstructions {
-  /** What the kind is and when to use it. */
-  summary: string;
-  /** Short, verifiable rules. */
-  rules: string[];
-  examples: KindExample[];
-}
-
-export interface ContentInput<Content> {
-  /** Shown in model instructions. */
-  description: string;
-  schema: z.ZodType<unknown>;
-  /** Deterministic conversion. Throw `ArtifactError('INVALID_CONTENT')` on bad input. */
-  toContent(input: unknown, ctx: InputContext): Content;
-}
-
-export interface InputContext {
-  locale: string;
-  /**
-   * Records a non-blocking conversion note (an ignored directive, a mapped shape). Notes are returned
-   * to the caller as `info` lint issues with code `input-note`.
-   */
-  note?(message: string): void;
-}
-
-export interface IdContext {
-  /** Deterministic id for a new item, e.g. `nextId('p')` → `p12`. */
-  nextId(prefix: string): string;
-  /** True when the id already exists in the content (including ids created earlier in the batch). */
-  hasId(id: string): boolean;
-  /** Registers an explicitly provided id so later operations in the batch see it. */
-  reserveId(id: string): void;
-}
-
-export interface ApplyContext extends IdContext {
-  /** Aborts the batch with `OPERATION_FAILED` and a model-facing hint. */
-  fail(message: string, options?: { hint?: string; path?: string }): never;
-  locale: string;
-}
-
-/**
- * Contract every kind implements, native or third-party (spec §7).
- * `apply` mutates a clone and must be pure: no clock, network or randomness.
- */
-export interface ArtifactKind<Content = unknown, Operation = unknown> {
-  kind: string;
-  version: number;
-  label: string;
-
-  contentSchema: z.ZodType<Content>;
-  operationSchema: z.ZodType<Operation>;
-
-  /** Smallest valid content, used for skeleton creation. */
-  empty(): Content;
-  /**
-   * Prepares raw content before validation: fills missing ids deterministically (ids are optional on
-   * creation, spec §6.2). Must not throw on malformed input; validation reports problems afterwards.
-   */
-  normalize?(raw: unknown, ctx: IdContext): unknown;
-  apply(draft: Content, op: Operation, ctx: ApplyContext): void;
-  /** Every item id in the content (unique across the whole artifact). */
-  ids(content: Content): Iterable<string>;
-  /** Integrity rules beyond the schema (references, unique ids, table widths). Empty array means valid. */
-  validate?(content: Content, locale?: string): ErrorIssue[];
-  /** Counters checked against `limits`. */
-  measure?(content: Content): Record<string, number>;
-  /** Derived step after operations (e.g. formula recalculation). Mutates the draft; must stay deterministic. */
-  derive?(draft: Content): void;
-  /** Item targets an operation touches, used for automatic rebase. Defaults to diff-based detection. */
-  targets?(op: Operation): string[];
-
-  project(content: Content, options: ProjectionOptions): Projection;
-  lint(content: Content, ctx: LintContext): LintIssue[];
-  /** `locale` selects the language of the summaries (pt-BR or English). */
-  diff(before: Content, after: Content, locale?: string): ChangeSummary[];
-  /** Best-effort preview while the model is still streaming; drops incomplete trailing items. */
-  parsePartial(raw: unknown): Content | undefined;
-
-  inputs?: Record<string, ContentInput<Content>>;
-  migrations: Migration[];
-  limits: KindLimits;
-  instructions: KindInstructions;
-}
-
-// biome-ignore lint/suspicious/noExplicitAny: registry stores heterogeneous kinds.
-export type AnyArtifactKind = ArtifactKind<any, any>;
-
-export class KindDefinitionError extends Error {
-  constructor(kind: string, problem: string) {
-    super(`Invalid kind "${kind}": ${problem}`);
-    this.name = 'KindDefinitionError';
-  }
-}
-
-const KIND_NAME = /^[a-z][a-z0-9-]{0,63}$/;
-
-/**
- * Validates a kind definition and returns it unchanged. Use it for third-party kinds (spec §20);
- * the registry runs the same checks on `register`.
- */
-export function defineKind<Content, Operation>(
-  kind: ArtifactKind<Content, Operation>,
-): ArtifactKind<Content, Operation> {
-  assertKindContract(kind);
-  return kind;
-}
-
-export function assertKindContract(kind: AnyArtifactKind): void {
-  const name = typeof kind?.kind === 'string' ? kind.kind : '<unnamed>';
-  if (!KIND_NAME.test(name)) throw new KindDefinitionError(name, 'kind must match /^[a-z][a-z0-9-]{0,63}$/');
-  if (!Number.isInteger(kind.version) || kind.version < 1)
-    throw new KindDefinitionError(name, 'version must be an integer >= 1');
-  if (!(kind.contentSchema instanceof z.ZodType))
-    throw new KindDefinitionError(name, 'contentSchema must be a zod schema');
-  if (!(kind.operationSchema instanceof z.ZodType))
-    throw new KindDefinitionError(name, 'operationSchema must be a zod schema');
-  for (const fn of ['empty', 'apply', 'ids', 'project', 'lint', 'diff', 'parsePartial'] as const) {
-    if (typeof kind[fn] !== 'function') throw new KindDefinitionError(name, `${fn} must be a function`);
-  }
-  if (!Array.isArray(kind.migrations)) throw new KindDefinitionError(name, 'migrations must be an array');
-  let expected = 1;
-  for (const migration of [...kind.migrations].sort((a, b) => a.from - b.from)) {
-    if (migration.from !== expected || migration.to !== migration.from + 1) {
-      throw new KindDefinitionError(name, `migrations must form a chain 1→2→…→${kind.version}`);
-    }
-    expected = migration.to;
-  }
-  if (kind.migrations.length > 0 && expected !== kind.version) {
-    throw new KindDefinitionError(name, `migrations end at ${expected} but version is ${kind.version}`);
-  }
-  if (
-    !kind.instructions ||
-    typeof kind.instructions.summary !== 'string' ||
-    !Array.isArray(kind.instructions.rules)
-  ) {
-    throw new KindDefinitionError(name, 'instructions need summary, rules and examples');
-  }
-  const empty = kind.contentSchema.safeParse(kind.empty());
-  if (!empty.success) throw new KindDefinitionError(name, 'empty() does not satisfy contentSchema');
-}