@superbee/core 0.2.0-pre.3 → 0.2.0-pre.31

package/dist/kinds.js

@@ -20,22 +20,58 @@
  * convention-doc (de)serialization) is dependency-free — this module carries ONLY that, and is
  * exported as the browser-safe `@superbee/core/kinds` subpath (the ui shell's bridge
  * `open` filter consumes `isTerminal` there; a browser bundler must never be dragged through the
- * engine's node built-ins for a pure predicate). The one backend-touching entry point,
- * `loadKinds`, lives in `kinds-load.ts` — same ONE registry, split only by dependency weight.
+ * engine's node built-ins for a pure predicate). The bundle read, `loadKinds`, lives in
+ * `kinds-load.ts`, which reads through `bundle-ops.ts` and is browser-safe too: the split is
+ * between pure parsing and the bundle read, over the same ONE registry.
  */
 import { isOkfLifecycleStatus, OKF_LIFECYCLE_STATUSES } from "./okf-lifecycle.js";
 import { isUsableTimestamp } from "./frontmatter.js";
+import { parseIsoInstant } from "./verification.js";
 /** The bundle-relative prefix a kind convention doc MUST live under to be discovered. */
 export const CONVENTIONS_PREFIX = "conventions/";
+/**
+ * True for an id `loadKinds` reads a convention from: under {@link CONVENTIONS_PREFIX} exactly as
+ * spelled (case-sensitive). A case variant is not a convention id; a host that fences folded ids
+ * refuses it rather than let it govern after a case-insensitive checkout.
+ */
+export function isConventionId(id) {
+    return id.startsWith(CONVENTIONS_PREFIX);
+}
 /** The OKF `type` value a kind convention doc itself carries. */
 export const CONVENTION_TYPE = "Convention";
+/**
+ * The closed, domain-neutral value-type vocabulary a convention may declare in `fields.types`.
+ * Each type constrains a value's shape only; presence stays governed by `fields.required`.
+ * Domain composites (opening hours, money, addresses) belong to recipe tooling, not core.
+ */
+export const KIND_FIELD_TYPES = [
+    "date",
+    "datetime",
+    "https-url",
+    "https-url-list",
+    "integer",
+    "number",
+    "boolean",
+    "slug",
+    "string-list",
+    "latitude",
+    "longitude",
+];
+const KIND_FIELD_TYPE_SET = new Set(KIND_FIELD_TYPES);
+/** True when `value` names a {@link KIND_FIELD_TYPES} member. */
+export function isKindFieldType(value) {
+    return typeof value === "string" && KIND_FIELD_TYPE_SET.has(value);
+}
 /**
  * Build the one authoritative Kind registry from already-selected convention documents.
  * Callers own discovery; this pure half owns parsing, warnings, and first-by-id duplicate
  * resolution so prospective registries cannot drift from {@link loadKinds} semantics.
  */
 export function buildKindRegistry(docs, initialWarnings = [], options = {}) {
-    const kinds = new Map();
+    // Duplicate resolution walks conventions by id so a declared `order` can never steal a
+    // `governs` from the first-by-id declaration; the accepted set is then laid into the Map in
+    // reading order.
+    const accepted = new Map();
     const warnings = [...initialWarnings];
     for (const doc of [...docs].sort((a, b) => a.id.localeCompare(b.id))) {
         const parsed = parseConventionDoc(doc, options);
@@ -58,10 +94,10 @@ export function buildKindRegistry(docs, initialWarnings = [], options = {}) {
                 severity: "warning",
             });
         }
-        if (kinds.has(kind.governs)) {
+        if (accepted.has(kind.governs)) {
             warnings.push({
                 code: "KIND_DUPLICATE_GOVERNS",
-                message: `duplicate kind convention for '${kind.governs}': '${doc.id}' ignored, keeping the first-declared '${kinds.get(kind.governs).id}'.`,
+                message: `duplicate kind convention for '${kind.governs}': '${doc.id}' ignored, keeping the first-declared '${accepted.get(kind.governs).id}'.`,
                 field: kind.governs,
                 severity: "warning",
             });
@@ -75,10 +111,27 @@ export function buildKindRegistry(docs, initialWarnings = [], options = {}) {
                 severity: "warning",
             });
         }
-        kinds.set(kind.governs, kind);
+        accepted.set(kind.governs, kind);
     }
+    const kinds = new Map();
+    for (const kind of [...accepted.values()].sort(compareReadingOrder))
+        kinds.set(kind.governs, kind);
     return { kinds, warnings };
 }
+/**
+ * The bundle's reading order over kinds: conventions with a declared `order` first, ascending,
+ * ties by id; then conventions without one, by id. A bundle that declares no `order` anywhere
+ * therefore iterates by id exactly as it did before the field existed.
+ */
+export function compareReadingOrder(a, b) {
+    if (a.order !== undefined && b.order !== undefined && a.order !== b.order)
+        return a.order - b.order;
+    if (a.order !== undefined && b.order === undefined)
+        return -1;
+    if (a.order === undefined && b.order !== undefined)
+        return 1;
+    return a.id.localeCompare(b.id);
+}
 /** Stable product-level name for a Kind's workflow progress field. */
 export const PROGRESS_STATUS_FIELD = "progress_status";
 /** Producer-qualified v0.2 storage coordinate for Superbee workflow progress. */
@@ -202,25 +255,48 @@ export function projectKindForAuthoring(okfVersion, kind) {
                 : undefined,
             terminal: projectRecord(kind.fields.terminal),
             descriptions: projectRecord(kind.fields.descriptions),
+            ...(kind.fields.types ? { types: projectRecord(kind.fields.types) } : {}),
         },
     };
 }
+/** Whether a Kind finding names a frontmatter coordinate rather than a body heading. */
+export function isKindFieldValidationWarning(warning) {
+    return warning.code === "KIND_FIELD_MISSING"
+        || warning.code === "KIND_FIELD_VALUE"
+        || warning.code === "KIND_FIELD_ARITY"
+        || warning.code === "KIND_FIELD_TYPE";
+}
+/** The owning message grammar separates the field coordinate from Kind labels and value suffixes. */
+function kindFieldWarningPrefix(code, kind, field) {
+    switch (code) {
+        case "KIND_FIELD_MISSING":
+            return `'${kind.governs}' requires a non-empty '${field}' field `;
+        case "KIND_FIELD_VALUE":
+            return `'${field}' value `;
+        case "KIND_FIELD_ARITY":
+            return `'${field}' is enum-restricted and takes exactly ONE value for '${kind.governs}'; `;
+        case "KIND_FIELD_TYPE":
+            return `'${field}' must be `;
+    }
+}
 /** Project Kind-validation findings into the same authoring vocabulary as the Kind schema. */
 export function projectKindValidationWarnings(okfVersion, kind, warnings) {
     const progress = progressStatusCoordinate(okfVersion, kind);
     if (!progress)
         return warnings;
-    const stored = `'${progress.storageField}'`;
-    const logical = `'${progress.logicalField}'`;
-    return warnings.map((warning) => warning.field === progress.storageField
-        ? {
+    return warnings.map((warning) => {
+        if (!isKindFieldValidationWarning(warning) || warning.field !== progress.storageField)
+            return warning;
+        const storedPrefix = kindFieldWarningPrefix(warning.code, kind, progress.storageField);
+        const logicalPrefix = kindFieldWarningPrefix(warning.code, kind, progress.logicalField);
+        return {
             ...warning,
             field: progress.logicalField,
-            // Core's Kind warnings name the field first. Replace that one coordinate only; a later
-            // occurrence may be the user's literal value and must remain byte-truthful.
-            message: warning.message.replace(stored, logical),
-        }
-        : warning);
+            message: warning.message.startsWith(storedPrefix)
+                ? logicalPrefix + warning.message.slice(storedPrefix.length)
+                : warning.message,
+        };
+    });
 }
 /** True for a plain YAML/JSON map (excludes arrays, `null`, dates, and other object instances). */
 function isPlainObject(value) {
@@ -307,6 +383,7 @@ const VALID_FIELDS_KEYS = new Set([
     "value_descriptions",
     "terminal",
     "descriptions",
+    "types",
 ]);
 /**
  * Top-level convention-doc keys that are near-misses for the ONE correct enum-constraint shape
@@ -381,7 +458,7 @@ export function parseConventionDoc(doc, options = {}) {
             if (!VALID_FIELDS_KEYS.has(key)) {
                 warnings.push({
                     code: "KIND_CONVENTION_UNKNOWN_FIELDS_KEY",
-                    message: `kind convention '${doc.id}' declares an unrecognized key 'fields.${key}' (valid keys: fields.required, fields.optional, fields.values, fields.value_descriptions, fields.terminal, fields.descriptions); ignoring it.`,
+                    message: `kind convention '${doc.id}' declares an unrecognized key 'fields.${key}' (valid keys: fields.required, fields.optional, fields.values, fields.value_descriptions, fields.terminal, fields.descriptions, fields.types); ignoring it.`,
                     field: `fields.${key}`,
                     severity: "warning",
                 });
@@ -441,6 +518,60 @@ export function parseConventionDoc(doc, options = {}) {
             });
         }
     }
+    // `fields.types` — declared value types from the closed KIND_FIELD_TYPES vocabulary. Same lenient
+    // posture as `fields.values`: a non-map shape warns and is ignored, an unknown type or a typed
+    // field the kind does not declare warns and is skipped. A definitions-only recipe therefore
+    // refuses a misspelled type instead of installing a constraint that can never fire.
+    const typesSource = fieldsRaw.types;
+    const types = {};
+    if (typesSource !== undefined) {
+        if (!isPlainObject(typesSource)) {
+            warnings.push({
+                code: "KIND_CONVENTION_BAD_SHAPE",
+                message: `kind convention '${doc.id}' has a non-map 'fields.types' (${describeShape(typesSource)}; expected a map of field name -> type); ignoring it.`,
+                field: "fields.types",
+                severity: "warning",
+            });
+        }
+        else {
+            for (const [field, declared] of Object.entries(typesSource)) {
+                if (dropReserved(field, `fields.types.${field}`))
+                    continue;
+                if (!isKindFieldType(declared)) {
+                    warnings.push({
+                        code: "KIND_CONVENTION_UNKNOWN_FIELD_TYPE",
+                        message: `kind convention '${doc.id}' declares 'fields.types.${field}' as ${isScalar(declared) ? `'${String(declared)}'` : describeShape(declared)}, which is not a field type (valid types: ${KIND_FIELD_TYPES.join(", ")}); ignoring it.`,
+                        field: `fields.types.${field}`,
+                        severity: "warning",
+                    });
+                    continue;
+                }
+                if (!declaredFieldNames.has(field)) {
+                    warnings.push({
+                        code: "KIND_CONVENTION_UNDECLARED_TYPES_FIELD",
+                        message: `kind convention '${doc.id}' declares 'fields.types.${field}' but '${field}' is not in fields.required or fields.optional; ignoring it.`,
+                        field: `fields.types.${field}`,
+                        severity: "warning",
+                    });
+                    continue;
+                }
+                setOwn(types, field, declared);
+            }
+        }
+    }
+    // An enum over URLs is never meaningful, so values on an `https-url-list` field are skipped. Every
+    // other typed field may carry `fields.values`: a scalar picks one, a `string-list` checks each item.
+    for (const field of Object.keys(values)) {
+        if (types[field] !== "https-url-list")
+            continue;
+        warnings.push({
+            code: "KIND_CONVENTION_VALUES_TYPE_MISMATCH",
+            message: `kind convention '${doc.id}' declares 'fields.values.${field}' on a field of type 'https-url-list', which cannot carry an enum; ignoring the values.`,
+            field: `fields.values.${field}`,
+            severity: "warning",
+        });
+        delete values[field];
+    }
     const valueDescriptionsSource = fieldsRaw.value_descriptions;
     const valueDescriptions = {};
     if (valueDescriptionsSource !== undefined) {
@@ -758,12 +889,30 @@ export function parseConventionDoc(doc, options = {}) {
         : undefined;
     // Strict boolean `true` only — an absent, false, or non-boolean value means "expanded" (the default).
     const browseCollapsed = fm.browse_collapsed === true ? true : undefined;
+    // `order:` is a finite number or nothing. Anything else warns and the kind registers without an
+    // order (it sorts with the undeclared), never a skipped convention.
+    let order;
+    if (fm.order !== undefined) {
+        if (typeof fm.order === "number" && Number.isFinite(fm.order)) {
+            order = fm.order;
+        }
+        else {
+            warnings.push({
+                code: "KIND_CONVENTION_BAD_SHAPE",
+                message: `kind convention '${doc.id}' has an invalid 'order' (${describeShape(fm.order)}; expected a finite number such as 10); ignoring it.`,
+                field: "order",
+                severity: "warning",
+            });
+        }
+    }
     const kind = {
         id: doc.id,
         title,
         governs,
         fields: { required, optional, values, valueDescriptions, terminal, descriptions },
     };
+    if (Object.keys(types).length > 0)
+        kind.fields.types = types;
     if (description !== undefined)
         kind.description = description;
     if (path !== undefined)
@@ -780,6 +929,8 @@ export function parseConventionDoc(doc, options = {}) {
         kind.freshnessHorizon = freshnessHorizon;
     if (browseCollapsed !== undefined)
         kind.browseCollapsed = browseCollapsed;
+    if (order !== undefined)
+        kind.order = order;
     if (claim !== undefined)
         kind.claim = claim;
     return {
@@ -826,9 +977,155 @@ export function isPresent(value) {
         return value.length > 0;
     return true;
 }
+/** Human phrase for each field type, used in warnings and authoring help. */
+export const KIND_FIELD_TYPE_DESCRIPTIONS = {
+    date: "a YYYY-MM-DD calendar date",
+    datetime: "an ISO-8601 date and time with an explicit UTC offset (Z or +/-HH:MM)",
+    "https-url": "an absolute https URL of at most 2048 characters, without credentials",
+    "https-url-list": "a list of distinct https URLs",
+    integer: "a safe integer",
+    number: "a finite number",
+    boolean: "true or false",
+    slug: "a lowercase slug (a-z, 0-9 and single hyphens) of at most 200 characters",
+    "string-list": "a list of distinct non-empty strings",
+    latitude: "a number from -90 to 90",
+    longitude: "a number from -180 to 180",
+};
+const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SLUG_MAX_LENGTH = 200;
+const HTTPS_URL_MAX_LENGTH = 2048;
+const HTTPS_PREFIX_RE = /^https:\/\//i;
+const CONTROL_CHARACTER_RE = /[\u0000-\u001F\u007F]/;
+function describeValue(value) {
+    if (typeof value === "string")
+        return `got the string ${JSON.stringify(value.length > 60 ? `${value.slice(0, 57)}...` : value)}`;
+    if (typeof value === "number")
+        return `got the number ${Object.is(value, -0) ? "-0" : String(value)}`;
+    if (typeof value === "boolean")
+        return `got boolean ${String(value)}`;
+    return `got ${describeShape(value)}`;
+}
+function httpsUrlProblem(value) {
+    if (typeof value !== "string" || value.length > HTTPS_URL_MAX_LENGTH || /\s/.test(value))
+        return describeValue(value);
+    // WHATWG strips control characters and repairs `https:x`, `https:/x` and `https:\\x` into a host,
+    // so the authored text must already be an absolute `https://` URL with no control characters.
+    if (!HTTPS_PREFIX_RE.test(value) || CONTROL_CHARACTER_RE.test(value))
+        return describeValue(value);
+    // The WHATWG parser is the authority for the rest, so scheme case is irrelevant (`HTTPS://` is https).
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return describeValue(value);
+    }
+    if (parsed.protocol !== "https:" || parsed.hostname === "")
+        return describeValue(value);
+    if (parsed.username !== "" || parsed.password !== "")
+        return `${describeValue(value)} (credentials are not allowed)`;
+    return undefined;
+}
+function listProblem(value, itemProblem) {
+    if (!Array.isArray(value))
+        return describeValue(value);
+    const seen = new Set();
+    for (const [index, item] of value.entries()) {
+        const problem = itemProblem(item);
+        if (problem !== undefined)
+            return `item ${index} ${problem}`;
+        if (seen.has(item))
+            return `item ${index} repeats ${JSON.stringify(item)}`;
+        seen.add(item);
+    }
+    return undefined;
+}
+/**
+ * Why `value` does not satisfy `type`, or `undefined` when it does. Values are judged as decoded:
+ * YAML numbers and booleans, and strings exactly as authored (core's decoder keeps dates and
+ * instants as their source strings). `null` never satisfies a type. The ONE type predicate;
+ * callers never re-implement it.
+ */
+export function kindFieldTypeProblem(type, value) {
+    switch (type) {
+        case "date": {
+            const match = typeof value === "string" ? DATE_RE.exec(value) : null;
+            if (!match)
+                return describeValue(value);
+            const probe = new Date(0);
+            probe.setUTCFullYear(Number(match[1]), Number(match[2]), 0); // day 0 of the next month
+            const month = Number(match[2]);
+            const day = Number(match[3]);
+            return month >= 1 && month <= 12 && day >= 1 && day <= probe.getUTCDate() ? undefined : describeValue(value);
+        }
+        case "datetime":
+            // Exactly the OKF standard-timestamp instant grammar.
+            return typeof value === "string" && parseIsoInstant(value) !== null ? undefined : describeValue(value);
+        case "https-url":
+            return httpsUrlProblem(value);
+        case "https-url-list":
+            return listProblem(value, httpsUrlProblem);
+        case "integer":
+            return Number.isSafeInteger(value) && !Object.is(value, -0) ? undefined : describeValue(value);
+        case "number":
+            return typeof value === "number" && Number.isFinite(value) ? undefined : describeValue(value);
+        case "boolean":
+            return typeof value === "boolean" ? undefined : describeValue(value);
+        case "slug":
+            return typeof value === "string" && value.length <= SLUG_MAX_LENGTH && SLUG_RE.test(value)
+                ? undefined
+                : describeValue(value);
+        case "string-list":
+            return listProblem(value, (item) => (typeof item === "string" && item !== "" ? undefined : describeValue(item)));
+        case "latitude":
+        case "longitude": {
+            const limit = type === "latitude" ? 90 : 180;
+            return typeof value === "number" && Number.isFinite(value) && value >= -limit && value <= limit
+                ? undefined
+                : describeValue(value);
+        }
+    }
+}
+/** Whether a Kind declares `field` (a storage name) as one of the two list types, `string-list` or `https-url-list`. */
+export function isKindListField(kind, field) {
+    const types = kind?.fields.types;
+    if (!types || !hasOwn(types, field))
+        return false;
+    return types[field] === "string-list" || types[field] === "https-url-list";
+}
+const NUMBER_INPUT_RE = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+const INTEGER_INPUT_RE = /^[+-]?\d+$/;
+/**
+ * Convert command-line flag text for a declared field into its typed value: numeric types become
+ * numbers, `boolean` accepts exactly `true`/`false`, and both list types are always a list. Text that
+ * does not parse is returned unchanged so {@link validateAgainstKind} reports it, never guessed.
+ * Undeclared or untyped fields keep the historical one-value-scalar, repeated-flag-list shape.
+ */
+export function kindFieldInputValue(kind, field, inputs) {
+    const type = kind.fields.types && hasOwn(kind.fields.types, field) ? kind.fields.types[field] : undefined;
+    if (type === "string-list" || type === "https-url-list")
+        return [...inputs];
+    if (inputs.length !== 1)
+        return [...inputs];
+    const text = inputs[0];
+    switch (type) {
+        case "number":
+        case "latitude":
+        case "longitude":
+            return NUMBER_INPUT_RE.test(text.trim()) ? Number(text.trim()) : text;
+        case "integer":
+            return INTEGER_INPUT_RE.test(text.trim()) ? Number(text.trim()) : text;
+        case "boolean":
+            return text === "true" ? true : text === "false" ? false : text;
+        default:
+            return text;
+    }
+}
 /**
  * Validate `doc` against `kind`: required fields present + non-empty, enum-restricted
- * field values within the declared allowed set, and declared body `sections` present
+ * field values within the declared allowed set, typed field values of their declared
+ * `fields.types` type, and declared body `sections` present
  * (reusing the ONE heading splitter, {@link splitSections} — no second heading parser).
  * Returns core's EXISTING {@link ValidationWarning} shape; never throws. Purely
  * additive derivation — callers (the CLI) decide whether a warning blocks a write.
@@ -840,7 +1137,7 @@ export function validateAgainstKind(doc, kind) {
         if (!hasOwn(fm, field) || !isPresent(fm[field])) {
             warnings.push({
                 code: "KIND_FIELD_MISSING",
-                message: `'${kind.governs}' requires a non-empty '${field}' field (declared by ${kind.id}).`,
+                message: kindFieldWarningPrefix("KIND_FIELD_MISSING", kind, field) + `(declared by ${kind.id}).`,
                 field,
                 severity: "warning",
             });
@@ -861,10 +1158,11 @@ export function validateAgainstKind(doc, kind) {
         // validation locus, every consumer inherits: `new`, `doc update`, `doc write
         // --strict`, `status`'s bundle lint). A future kind wanting a multi-select enum
         // needs declared arity in the convention schema — not silently via arrays.
-        if (Array.isArray(raw)) {
+        // A `string-list` field declares its arity, so its enum checks each item instead.
+        if (Array.isArray(raw) && kind.fields.types?.[field] !== "string-list") {
             warnings.push({
                 code: "KIND_FIELD_ARITY",
-                message: `'${field}' is enum-restricted and takes exactly ONE value for '${kind.governs}'; ` +
+                message: kindFieldWarningPrefix("KIND_FIELD_ARITY", kind, field) +
                     `got ${raw.length} (${raw.map((v) => String(v)).join(", ")}).`,
                 field,
                 severity: "warning",
@@ -876,13 +1174,30 @@ export function validateAgainstKind(doc, kind) {
             if (!allowedStrs.includes(v)) {
                 warnings.push({
                     code: "KIND_FIELD_VALUE",
-                    message: `'${field}' value '${v}' is not one of the allowed values for '${kind.governs}': ${allowedStrs.join(", ")}.`,
+                    message: kindFieldWarningPrefix("KIND_FIELD_VALUE", kind, field) + `'${v}' is not one of the allowed values for '${kind.governs}': ${allowedStrs.join(", ")}.`,
                     field,
                     severity: "warning",
                 });
             }
         }
     }
+    for (const [field, type] of Object.entries(kind.fields.types ?? {})) {
+        if (!hasOwn(fm, field))
+            continue;
+        const raw = fm[field];
+        // An absent field is presence, owned by `fields.required`; an explicit `null` is a wrong type.
+        if (raw === undefined)
+            continue;
+        const problem = kindFieldTypeProblem(type, raw);
+        if (problem !== undefined) {
+            warnings.push({
+                code: "KIND_FIELD_TYPE",
+                message: kindFieldWarningPrefix("KIND_FIELD_TYPE", kind, field) + `${KIND_FIELD_TYPE_DESCRIPTIONS[type]} for '${kind.governs}'; ${problem}.`,
+                field,
+                severity: "warning",
+            });
+        }
+    }
     if (kind.sections && kind.sections.length > 0) {
         const sections = splitSections(doc.body ?? "");
         for (const heading of kind.sections) {
@@ -974,6 +1289,9 @@ export function kindConventionDoc(kind, prose, timestamp) {
         .map(([field, description]) => [field, description.trim()]));
     if (Object.keys(descriptions).length > 0)
         fields.descriptions = descriptions;
+    const types = Object.fromEntries(Object.entries(kind.fields.types ?? {}).filter(([, type]) => isKindFieldType(type)));
+    if (Object.keys(types).length > 0)
+        fields.types = types;
     const frontmatter = { type: CONVENTION_TYPE, title: kind.title, governs: kind.governs, timestamp };
     if (typeof kind.description === "string" && kind.description.trim() !== "") {
         frontmatter.description = kind.description.trim();
@@ -1009,6 +1327,8 @@ export function kindConventionDoc(kind, prose, timestamp) {
         frontmatter.freshness_horizon = kind.freshnessHorizon;
     if (kind.browseCollapsed)
         frontmatter.browse_collapsed = true;
+    if (typeof kind.order === "number" && Number.isFinite(kind.order))
+        frontmatter.order = kind.order;
     return { id: kind.id, frontmatter, body: prose };
 }
 //# sourceMappingURL=kinds.js.map