@frontera-sdk/cli 1.52.38 → 1.52.40

package/src/local/local-schema-check.ts

@@ -0,0 +1,148 @@
+/**
+ * A file checked against the JSON Schema `frontera local schema <kind>`
+ * prints for it, before anything reads it: each problem said at its path in
+ * the file (`cases.2.checks.0.value: must be text`), not as a crash in the
+ * code that reads the field later.
+ *
+ * Only the keywords this CLI's own schemas use (`local-schemas.ts`,
+ * `local-blueprint-schemas.ts`): type, enum, const, required, properties,
+ * additionalProperties, items, the length and count bounds, pattern,
+ * minimum/maximum, anyOf, oneOf and allOf. A keyword it does not know is not
+ * checked, so a schema is never stricter here than it says.
+ */
+
+type Schema = Record<string, unknown>
+
+export interface SchemaProblem {
+  /** Where in the file: `cases.2.checks.0.value`; empty for the document itself. */
+  path: string
+  message: string
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v)
+
+const WORDS: Record<string, string> = {
+  string: 'text',
+  number: 'a number',
+  integer: 'a whole number',
+  boolean: 'true or false',
+  object: 'a mapping',
+  array: 'a list',
+  null: 'null',
+}
+
+function typeOf(value: unknown): string {
+  if (value === null) return 'null'
+  if (Array.isArray(value)) return 'array'
+  if (typeof value === 'number') return Number.isInteger(value) ? 'integer' : 'number'
+  return typeof value
+}
+
+function fitsType(value: unknown, type: string): boolean {
+  const actual = typeOf(value)
+  if (type === 'number') return actual === 'number' || actual === 'integer'
+  return actual === type
+}
+
+const show = (v: unknown) => (typeof v === 'string' ? `"${v}"` : JSON.stringify(v))
+
+const join = (path: string, key: string | number) => (path ? `${path}.${key}` : String(key))
+
+/** `anyOf` whose branches only require keys: said as the key sets that would do. */
+function requiredOnly(branches: unknown[]): string[][] | null {
+  const sets: string[][] = []
+  for (const b of branches) {
+    if (!isRecord(b) || Object.keys(b).some((k) => k !== 'required') || !Array.isArray(b.required)) return null
+    sets.push(b.required as string[])
+  }
+  return sets
+}
+
+/** Every problem with `value` against `schema`, at `path`. */
+export function checkAgainstSchema(value: unknown, schema: Schema, path = ''): SchemaProblem[] {
+  const out: SchemaProblem[] = []
+  const say = (message: string, at = path) => out.push({ path: at, message })
+
+  if ('const' in schema && JSON.stringify(value) !== JSON.stringify(schema.const)) {
+    say(`must be ${show(schema.const)}`)
+    return out
+  }
+  if (Array.isArray(schema.enum) && !schema.enum.some((e) => JSON.stringify(e) === JSON.stringify(value))) {
+    say(`must be one of ${schema.enum.map(show).join(', ')}; it is ${show(value)}`)
+    return out
+  }
+  const types = typeof schema.type === 'string' ? [schema.type] : Array.isArray(schema.type) ? (schema.type as string[]) : null
+  if (types && !types.some((t) => fitsType(value, t))) {
+    say(`must be ${types.map((t) => WORDS[t] ?? t).join(' or ')}; it is ${WORDS[typeOf(value)] ?? typeOf(value)}${typeof value === 'object' && value !== null ? '' : ` (${show(value)})`}`)
+    return out
+  }
+
+  if (typeof value === 'string') {
+    if (typeof schema.minLength === 'number' && value.length < schema.minLength) say(schema.minLength === 1 ? 'must not be empty' : `must be at least ${schema.minLength} characters`)
+    if (typeof schema.maxLength === 'number' && value.length > schema.maxLength) say(`must be at most ${schema.maxLength} characters`)
+    if (typeof schema.pattern === 'string') {
+      try {
+        if (!new RegExp(schema.pattern).test(value)) say(`${show(value)} does not match ${schema.pattern}`)
+      } catch {
+        // A pattern this engine cannot read is not checked here.
+      }
+    }
+  }
+  if (typeof value === 'number') {
+    if (typeof schema.minimum === 'number' && value < schema.minimum) say(`must be at least ${schema.minimum}`)
+    if (typeof schema.maximum === 'number' && value > schema.maximum) say(`must be at most ${schema.maximum}`)
+  }
+  if (Array.isArray(value)) {
+    if (typeof schema.minItems === 'number' && value.length < schema.minItems) say(schema.minItems === 1 ? 'must list at least one item' : `must list at least ${schema.minItems} items`)
+    if (typeof schema.maxItems === 'number' && value.length > schema.maxItems) say(schema.maxItems === 0 ? 'must be empty' : `must list at most ${schema.maxItems} items`)
+    if (isRecord(schema.items)) value.forEach((item, i) => out.push(...checkAgainstSchema(item, schema.items as Schema, join(path, i))))
+  }
+  if (isRecord(value)) {
+    const props = isRecord(schema.properties) ? schema.properties : {}
+    for (const key of Array.isArray(schema.required) ? (schema.required as string[]) : []) {
+      if (!(key in value)) say(`\`${key}\` is required`, path)
+    }
+    const keys = Object.keys(value)
+    if (typeof schema.minProperties === 'number' && keys.length < schema.minProperties) say(`must hold at least ${schema.minProperties} key${schema.minProperties === 1 ? '' : 's'}`)
+    if (typeof schema.maxProperties === 'number' && keys.length > schema.maxProperties) say(`must hold at most ${schema.maxProperties} key${schema.maxProperties === 1 ? '' : 's'}`)
+    // A key the file names itself (a variable's name): checked against its pattern.
+    const names = isRecord(schema.propertyNames) && typeof schema.propertyNames.pattern === 'string' ? new RegExp(schema.propertyNames.pattern, 'u') : null
+    for (const key of keys) if (names && !names.test(key)) say(`\`${key}\` is not a name this takes (it matches ${schema.propertyNames && (schema.propertyNames as Schema).pattern})`, join(path, key))
+    for (const key of keys) {
+      const child = props[key]
+      if (isRecord(child)) out.push(...checkAgainstSchema(value[key], child, join(path, key)))
+      else if (schema.additionalProperties === false) {
+        const known = Object.keys(props)
+        say(`\`${key}\` is not a key this file takes${known.length ? ` (it takes ${known.map((k) => `\`${k}\``).join(', ')})` : ''}`, join(path, key))
+      } else if (isRecord(schema.additionalProperties)) out.push(...checkAgainstSchema(value[key], schema.additionalProperties, join(path, key)))
+    }
+  }
+
+  for (const sub of Array.isArray(schema.allOf) ? schema.allOf : []) if (isRecord(sub)) out.push(...checkAgainstSchema(value, sub, path))
+  if (Array.isArray(schema.anyOf) && schema.anyOf.length) {
+    const results = schema.anyOf.map((b) => (isRecord(b) ? checkAgainstSchema(value, b, path) : []))
+    if (!results.some((r) => r.length === 0)) {
+      const sets = requiredOnly(schema.anyOf)
+      if (sets) say(`needs ${sets.map((s) => s.map((k) => `\`${k}\``).join(' and ')).join(', or ')}`)
+      else out.push(...closest(results))
+    }
+  }
+  if (Array.isArray(schema.oneOf) && schema.oneOf.length) {
+    const branches = schema.oneOf.filter(isRecord)
+    // A branch picked by a `const` key (`kind: file`) is the one to report against.
+    const picked = branches.find((b) => isRecord(b.properties) && Object.entries(b.properties).some(([k, p]) => isRecord(p) && 'const' in p && isRecord(value) && value[k] === p.const))
+    const results = (picked ? [picked] : branches).map((b) => checkAgainstSchema(value, b, path))
+    if (!results.some((r) => r.length === 0)) out.push(...closest(results))
+  }
+  return out
+}
+
+/** Of several branches that failed, the one that came nearest: fewest problems. */
+function closest(results: SchemaProblem[][]): SchemaProblem[] {
+  return [...results].sort((a, b) => a.length - b.length)[0] ?? []
+}
+
+/** Problems as lines: `file: path: message`. */
+export function describeProblems(problems: SchemaProblem[], file?: string): string[] {
+  return problems.map((p) => `${file ? `${file}: ` : ''}${p.path ? `${p.path}: ` : ''}${p.message}`)
+}