@sdboyer/thema-ui 0.0.0-bootstrap.0 → 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,580 @@
+/**
+ * File is one named text: a file of the authoring form, relative to the
+ * lineage's directory (tip.thema, history/0.0.thema), or a normal-form .cue
+ * file.
+ */
+export interface File {
+    path: string;
+    text: string;
+}
+/**
+ * LineageInput is a lineage as the author wrote it, in exactly one of the two
+ * forms: the authoring form (Name and Files) or one normal-form file (Normal,
+ * with Path naming the lineage within it when it is not the file's root).
+ */
+export interface LineageInput {
+    /**
+     * Name is the lineage's name in the authoring form, which the authoring
+     * form takes from its directory.
+     */
+    name?: string;
+    files?: File[];
+    /**
+     * Normal is a normal-form file. It may import github.com/sdboyer/thema,
+     * and nothing else.
+     */
+    normal?: File;
+    /**
+     * Path is the CUE path of the lineage within Normal, such as "lin" or
+     * "rename.l". Empty means the file's root.
+     */
+    path?: string;
+}
+/**
+ * DataInput is one data document.
+ */
+export interface DataInput {
+    /**
+     * Filename names the document in diagnostics. It must not end in .cue.
+     */
+    filename: string;
+    text: string;
+    /**
+     * Format is "json" or "yaml". Empty detects it: JSON first, then YAML.
+     */
+    format?: string;
+}
+/**
+ * Result is what every response carries: whether the operation succeeded,
+ * and everything thema had to say about it. OK is false exactly when some
+ * diagnostic is an error.
+ */
+export interface Result {
+    ok: boolean;
+    diagnostics: Diagnostic[];
+}
+/**
+ * InitResponse describes the playground: the versions it was built from and
+ * the operations it answers.
+ */
+export interface InitResponse extends Result {
+    themaVersion: string;
+    cueVersion: string;
+    ops: string[];
+}
+/**
+ * BindRequest binds a lineage.
+ */
+export interface BindRequest {
+    lineage: LineageInput;
+}
+/**
+ * BindResponse is a bound lineage: its name, its versions in order, and its
+ * normal form as text (for the authoring form, what the files compile to).
+ * The playground binds a lineage in the authoring form with its tip, on the
+ * development path: the tip is the file being edited, and binding the
+ * history alone would ignore every edit. Tip describes it, and the
+ * diagnostics carry a warning (E1001) for each lens the tip's edge lacks.
+ */
+export interface BindResponse extends Result {
+    name?: string;
+    versions?: string[];
+    normal?: string;
+    tip?: TipInfo;
+}
+/**
+ * TipInfo describes the tip of a lineage in the authoring form.
+ */
+export interface TipInfo {
+    /**
+     * Version is the version the tip cuts as, derived by the compatibility
+     * check against the newest version under history/; when the tip is
+     * clean, the newest version, which it equals.
+     */
+    version: string;
+    /**
+     * Clean says whether the tip equals the newest version under history/,
+     * with no lenses: there is nothing to cut.
+     */
+    clean: boolean;
+    /**
+     * Provisional says whether the lineage's versions end with the tip's:
+     * it is not clean, and an instance of that version is an instance of the
+     * tip, not of a version that was cut.
+     */
+    provisional: boolean;
+}
+/**
+ * ValidateRequest validates a data document against one schema. An empty
+ * Version means the latest.
+ */
+export interface ValidateRequest {
+    lineage: LineageInput;
+    data: DataInput;
+    version?: string;
+}
+/**
+ * ValidateResponse names the version the data was validated against.
+ */
+export interface ValidateResponse extends Result {
+    version?: string;
+}
+/**
+ * ValidateAnyRequest searches the lineage for a schema the data is an
+ * instance of.
+ */
+export interface ValidateAnyRequest {
+    lineage: LineageInput;
+    data: DataInput;
+}
+/**
+ * VersionDiagnostics is what one schema said about the data.
+ */
+export interface VersionDiagnostics {
+    version: string;
+    diagnostics: Diagnostic[];
+}
+/**
+ * ValidateAnyResponse names the version that accepted the data, if one did,
+ * and what every schema said about it, so that a failure shows why each
+ * version refused it.
+ */
+export interface ValidateAnyResponse extends Result {
+    version?: string;
+    perVersion: VersionDiagnostics[];
+}
+/**
+ * TranslateRequest translates a data document from one version to another.
+ * An empty From searches the lineage for the data's schema.
+ */
+export interface TranslateRequest {
+    lineage: LineageInput;
+    data: DataInput;
+    from?: string;
+    to: string;
+}
+/**
+ * TranslateResponse is the translated instance, as JSON, and the lacunas each
+ * step emitted. From and To are versions, except that the tip's provisional
+ * version is "tip", and CutsAs then gives the version it cuts as; CutsAs is
+ * omitted when the translation does not involve the tip.
+ */
+export interface TranslateResponse extends Result {
+    from?: string;
+    to?: string;
+    cutsAs?: string;
+    output?: unknown;
+    lacunas?: TranslationLacunas;
+}
+/**
+ * CodegenRequest generates code from one schema. An empty Version means the
+ * latest. Format is "json" or "yaml" for OpenAPI and JSON Schema, and is
+ * ignored for TypeScript.
+ */
+export interface CodegenRequest {
+    lineage: LineageInput;
+    version?: string;
+    format?: string;
+}
+/**
+ * CodegenResponse is the generated text.
+ */
+export interface CodegenResponse extends Result {
+    version?: string;
+    output?: string;
+}
+/**
+ * CompileRequest compiles authoring files to the normal form, with the tip,
+ * as the playground binds them.
+ */
+export interface CompileRequest {
+    name: string;
+    files: File[];
+}
+/**
+ * CompileResponse is the normal form as text.
+ */
+export interface CompileResponse extends Result {
+    normal?: string;
+}
+/**
+ * DecompileRequest recovers the authoring files of a normal-form lineage.
+ */
+export interface DecompileRequest {
+    normal: File;
+    path?: string;
+}
+/**
+ * DecompileResponse is the lineage's name and its files: its versions under
+ * history/, and a clean tip.
+ */
+export interface DecompileResponse extends Result {
+    name?: string;
+    files?: File[];
+}
+/**
+ * FormatRequest lays out one file of the authoring form in its layout.
+ */
+export interface FormatRequest {
+    file: File;
+}
+/**
+ * FormatResponse is the formatted text.
+ */
+export interface FormatResponse extends Result {
+    text?: string;
+}
+/**
+ * ExampleInfo describes one example the playground offers.
+ */
+export interface ExampleInfo {
+    id: string;
+    title: string;
+    category: string;
+    summary: string;
+    /**
+     * Kind is the form the example is written in: "authoring" or "normal".
+     */
+    kind: string;
+    /**
+     * Binds says whether the lineage binds; an example of an error does not.
+     */
+    binds: boolean;
+}
+/**
+ * ListExamplesResponse lists the examples.
+ */
+export interface ListExamplesResponse extends Result {
+    examples: ExampleInfo[];
+}
+/**
+ * GetExampleRequest asks for one example by ID.
+ */
+export interface GetExampleRequest {
+    id: string;
+}
+/**
+ * GetExampleResponse is an example's lineage and data documents.
+ */
+export interface GetExampleResponse extends Result {
+    example: ExampleInfo;
+    lineage: LineageInput;
+    data: DataInput[];
+}
+/**
+ * RegisterExamplesRequest adds a host's own examples to thema's, for a
+ * deployment of the playground that offers lineages of its own. The examples
+ * and example operations then serve both, thema's first. It replaces the
+ * examples any earlier request registered.
+ */
+export interface RegisterExamplesRequest {
+    examples: HostExample[];
+}
+/**
+ * HostExample is one example a host supplies, in the shape the example
+ * operation returns it. Its ID must be unique among all the examples, and its
+ * category must not be one of thema's own. An empty Kind is taken from the
+ * lineage's form; a Kind given must name that form. Binds is checked by
+ * binding the lineage. Data is offered with the example as it is given.
+ */
+export interface HostExample {
+    example: ExampleInfo;
+    lineage: LineageInput;
+    data?: DataInput[];
+}
+/**
+ * RegisterExamplesResponse lists the IDs of the examples registered, in the
+ * request's order. Each example refused has an error diagnostic saying why;
+ * the others are registered regardless.
+ */
+export interface RegisterExamplesResponse extends Result {
+    registered: string[];
+}
+/**
+ * AddrKind says what construct an Address names.
+ */
+export type AddrKind = string;
+export declare const AddrLineage: AddrKind;
+export declare const AddrName: AddrKind;
+export declare const AddrJoinSchema: AddrKind;
+export declare const AddrSchema: AddrKind;
+export declare const AddrSchemaField: AddrKind;
+export declare const AddrExample: AddrKind;
+export declare const AddrLens: AddrKind;
+export declare const AddrLensInput: AddrKind;
+export declare const AddrLensResult: AddrKind;
+export declare const AddrLensResultField: AddrKind;
+export declare const AddrLacuna: AddrKind;
+export declare const AddrLacunaField: AddrKind;
+export declare const AddrStep: AddrKind;
+export declare const AddrData: AddrKind;
+/**
+ * Version is a syntactic version as an Address carries it. It is a pair rather
+ * than thema.SyntacticVersion because diag must not import the thema root.
+ */
+export type Version = number[];
+/**
+ * Address is the structured subject of a Diagnostic, in terms independent of
+ * how the lineage was written. A Vocabulary renders it into the author's.
+ */
+export interface Address {
+    kind: AddrKind;
+    version?: Version;
+    from?: Version;
+    to?: Version;
+    /**
+     * Index is a lacuna's or a translation step's index.
+     */
+    index?: number;
+    /**
+     * Field is a path inside a schema, a lens result or the data.
+     */
+    field?: string[];
+    /**
+     * Name is an example's name, a lacuna field's name, or an unknown field.
+     */
+    name?: string;
+}
+/**
+ * Severity is how seriously a Diagnostic is to be taken.
+ */
+export type Severity = string;
+/**
+ * SeverityError: the operation failed. A lineage with an error does not bind; data
+ * with an error is not an instance.
+ */
+export declare const SeverityError: Severity;
+/**
+ * SeverityWarning: the operation succeeded, but the author should look.
+ */
+export declare const SeverityWarning: Severity;
+/**
+ * SeverityNote: information with no judgment attached.
+ */
+export declare const SeverityNote: Severity;
+/**
+ * Origin says whose text a position points into.
+ */
+export type Origin = string;
+/**
+ * OriginUser: a file the author wrote, or data they supplied.
+ */
+export declare const OriginUser: Origin;
+/**
+ * OriginThema: thema's own CUE. Never the author's line.
+ */
+export declare const OriginThema: Origin;
+/**
+ * OriginSynth: a position with no file behind it, such as a value built
+ * in Go without a filename.
+ */
+export declare const OriginSynth: Origin;
+/**
+ * Code identifies a diagnostic's meaning, stably: E0304 always means the same
+ * thing, and a retired code is never reused. Codes are grouped by hundreds;
+ * see [Codes].
+ */
+export type Code = string;
+/**
+ * MaxHeadline is the longest a headline may be. A longer statement is split: a
+ * shorter headline names the rule and the construct, and the statement becomes
+ * a note.
+ */
+export declare const MaxHeadline = 140;
+/**
+ * Pos is a position in a file. Line and Col are 1-based; Col counts bytes, as
+ * CUE reports it.
+ */
+export interface Pos {
+    file: string;
+    line: number;
+    col: number;
+    offset?: number;
+    origin: Origin;
+}
+/**
+ * Span is a range in one file, from Start up to but not including End.
+ */
+export interface Span {
+    start: Pos;
+    end: Pos;
+}
+/**
+ * Note is a supporting statement, optionally anchored at a position.
+ */
+export interface Note {
+    pos?: Pos;
+    label: string;
+}
+/**
+ * Fix is a machine-applicable edit that resolves the diagnostic.
+ */
+export interface Fix {
+    span: Span;
+    replacement: string;
+}
+/**
+ * Diagnostic is one thing thema has to say about an input.
+ */
+export interface Diagnostic {
+    code: Code;
+    severity: Severity;
+    /**
+     * Headline names the rule and what violates it, in the author's vocabulary.
+     */
+    headline: string;
+    /**
+     * Path locates the subject in the author's vocabulary, rendered from
+     * Address by a Vocabulary.
+     */
+    path?: string[];
+    /**
+     * Address is the structured subject, in terms independent of how the
+     * lineage was written.
+     */
+    address?: Address;
+    /**
+     * Primary is the author's position, or nil when none could be found.
+     */
+    primary?: Pos;
+    /**
+     * Notes say why, and where else to look.
+     */
+    notes?: Note[];
+    /**
+     * Help says what to do.
+     */
+    help?: string[];
+    /**
+     * Fix is an edit that resolves the diagnostic, when thema knows one.
+     */
+    fix?: Fix;
+    /**
+     * Detail is supporting text that is not thema's own, such as CUE's
+     * message verbatim.
+     */
+    detail?: string;
+}
+/**
+ * Report is what a tool emits: the diagnostics of one operation.
+ */
+export interface Report {
+    diagnostics: Diagnostic[];
+    summary: Summary;
+}
+/**
+ * Summary counts a Report's diagnostics by severity.
+ */
+export interface Summary {
+    errors: number;
+    warnings: number;
+    notes: number;
+}
+/**
+ * TranslationLacunas holds the lacunas emitted by a translation, step by step.
+ * A translation between non-adjacent schemas passes through each intermediate
+ * schema. Each step's lacunas are expressed in that step's terms: field paths
+ * refer to the step's source and target schemas, and are not re-mapped through
+ * later steps.
+ */
+export type TranslationLacunas = TranslationStep[];
+/**
+ * TranslationStep is a single step of a translation, between adjacent schemas,
+ * and the lacunas emitted by that step.
+ */
+export interface TranslationStep {
+    from: SyntacticVersion;
+    to: SyntacticVersion;
+    lacunas: Lacuna[];
+}
+/**
+ * SyntacticVersion is the position of a schema within a lineage: the index of
+ * the schema's sequence within the lineage, then the index of the schema within
+ * that sequence.
+ * It duplicates thema.SyntacticVersion, which this package cannot import
+ * without depending on CUE. The two have the same underlying type, so each
+ * converts to the other.
+ */
+export type SyntacticVersion = number[];
+/**
+ * A Lacuna represents a semantic gap in a Lens's mapping between schemas.
+ * For any given mapping between schema, there may exist some valid values and
+ * intended semantics on either side that are impossible to precisely translate.
+ * When such gaps occur, and an actual schema instance falls into such a gap,
+ * the Lens is expected to emit Lacuna that describe the general nature of the
+ * translation gap.
+ * The production of a lacuna as the output of the translation of a particular
+ * instance indicates the lacuna applies to that specific translation.
+ */
+export interface Lacuna {
+    /**
+     * The fields in the pre-translation instance that are relevant to the lacuna.
+     */
+    sourceFields?: FieldRef[];
+    /**
+     * The fields in the post-translation instance that are relevant to the lacuna.
+     */
+    targetFields?: FieldRef[];
+    /**
+     * The kind of gap.
+     */
+    type: Type;
+    /**
+     * A human-readable message describing the gap in translation.
+     */
+    message: string;
+}
+/**
+ * Type identifies a kind of gap a lacuna can describe. The types are
+ * defined, and documented, in thema's CUE (LacunaTypes in lacuna.cue).
+ */
+export type Type = string;
+/**
+ * The kinds of gap a lacuna can describe. See LacunaTypes in lacuna.cue for what
+ * each means.
+ */
+export declare const Placeholder: Type;
+/**
+ * The kinds of gap a lacuna can describe. See LacunaTypes in lacuna.cue for what
+ * each means.
+ */
+export declare const DroppedField: Type;
+/**
+ * The kinds of gap a lacuna can describe. See LacunaTypes in lacuna.cue for what
+ * each means.
+ */
+export declare const LossyFieldMapping: Type;
+/**
+ * The kinds of gap a lacuna can describe. See LacunaTypes in lacuna.cue for what
+ * each means.
+ */
+export declare const ChangedDefault: Type;
+/**
+ * The kinds of gap a lacuna can describe. See LacunaTypes in lacuna.cue for what
+ * each means.
+ */
+export declare const PrecisionLoss: Type;
+/**
+ * The kinds of gap a lacuna can describe. See LacunaTypes in lacuna.cue for what
+ * each means.
+ */
+export declare const AmbiguousMapping: Type;
+/**
+ * The kinds of gap a lacuna can describe. See LacunaTypes in lacuna.cue for what
+ * each means.
+ */
+export declare const Defaulted: Type;
+/**
+ * FieldRef identifies a field in an instance being translated, and its value at
+ * the time of translation.
+ */
+export interface FieldRef {
+    /**
+     * Path to the field, in CUE path syntax.
+     */
+    path: string;
+    /**
+     * The value of the field at the time of translation.
+     */
+    value: any;
+}

package/dist/types.js

@@ -0,0 +1,85 @@
+// Code generated by playground/tsapi from playground/types.go, diag and lacuna. DO NOT EDIT.
+//
+// The playground's wire format: what each operation of the wasm bridge takes
+// and returns, as JSON.
+export const AddrLineage = "lineage";
+export const AddrName = "name";
+export const AddrJoinSchema = "joinSchema";
+export const AddrSchema = "schema"; // Version
+export const AddrSchemaField = "schemaField"; // Version, Field
+export const AddrExample = "example"; // Version, Name
+export const AddrLens = "lens"; // From, To
+export const AddrLensInput = "lensInput"; // From, To
+export const AddrLensResult = "lensResult"; // From, To
+export const AddrLensResultField = "lensResultField"; // From, To, Field
+export const AddrLacuna = "lacuna"; // From, To, Index (or Field for keyed lacunas)
+export const AddrLacunaField = "lacunaField"; // From, To, Index, Name
+export const AddrStep = "step"; // From, To, Index: one step of a translation
+export const AddrData = "data"; // Field
+/**
+ * SeverityError: the operation failed. A lineage with an error does not bind; data
+ * with an error is not an instance.
+ */
+export const SeverityError = "error";
+/**
+ * SeverityWarning: the operation succeeded, but the author should look.
+ */
+export const SeverityWarning = "warning";
+/**
+ * SeverityNote: information with no judgment attached.
+ */
+export const SeverityNote = "note";
+/**
+ * OriginUser: a file the author wrote, or data they supplied.
+ */
+export const OriginUser = "user";
+/**
+ * OriginThema: thema's own CUE. Never the author's line.
+ */
+export const OriginThema = "thema";
+/**
+ * OriginSynth: a position with no file behind it, such as a value built
+ * in Go without a filename.
+ */
+export const OriginSynth = "synth";
+/**
+ * MaxHeadline is the longest a headline may be. A longer statement is split: a
+ * shorter headline names the rule and the construct, and the statement becomes
+ * a note.
+ */
+export const MaxHeadline = 140;
+/**
+ * The kinds of gap a lacuna can describe. See LacunaTypes in lacuna.cue for what
+ * each means.
+ */
+export const Placeholder = "Placeholder";
+/**
+ * The kinds of gap a lacuna can describe. See LacunaTypes in lacuna.cue for what
+ * each means.
+ */
+export const DroppedField = "DroppedField";
+/**
+ * The kinds of gap a lacuna can describe. See LacunaTypes in lacuna.cue for what
+ * each means.
+ */
+export const LossyFieldMapping = "LossyFieldMapping";
+/**
+ * The kinds of gap a lacuna can describe. See LacunaTypes in lacuna.cue for what
+ * each means.
+ */
+export const ChangedDefault = "ChangedDefault";
+/**
+ * The kinds of gap a lacuna can describe. See LacunaTypes in lacuna.cue for what
+ * each means.
+ */
+export const PrecisionLoss = "PrecisionLoss";
+/**
+ * The kinds of gap a lacuna can describe. See LacunaTypes in lacuna.cue for what
+ * each means.
+ */
+export const AmbiguousMapping = "AmbiguousMapping";
+/**
+ * The kinds of gap a lacuna can describe. See LacunaTypes in lacuna.cue for what
+ * each means.
+ */
+export const Defaulted = "Defaulted";

package/errors/E0101.md

@@ -0,0 +1,43 @@
+<!-- Generated by go test ./diag; do not edit. -->
+
+# E0101: a file in the lineage's directory is not a version file
+
+A lineage's directory holds its tip, `tip.thema`, at the top, and its frozen
+versions under `history/`, each named `<major>.<minor>.thema`. A `.thema` file
+with any other name or place is not a version file, and there is nothing to
+compile it as.
+
+## Example
+
+`ship/history/0.0.thema`:
+
+```cue
+Schema: {
+	a: string
+}
+```
+
+`ship/tip.thema`:
+
+```cue
+Schema: {
+	a: string
+}
+```
+
+`ship/v1.thema`:
+
+```cue
+Schema: {
+	a: string
+	b: int
+}
+```
+
+thema reports:
+
+```
+error[E0101]: v1.thema is not a version file
+  |
+  = help: a lineage's directory holds its tip, tip.thema, and its frozen versions under history/, each named <major>.<minor>.thema
+```