|
| 1 | +// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license. |
| 2 | + |
| 3 | +/** |
| 4 | + * Build-time lint for `autonumber` field formats. An `autonumberFormat` may |
| 5 | + * interpolate other fields of the same record (`{plan_no}{000}`, |
| 6 | + * `{section}{island_zone}{000}`). That field value forms the counter SCOPE, so |
| 7 | + * if it is missing at create time the record number silently collapses into the |
| 8 | + * wrong scope — and the runtime now throws rather than emit a wrong number |
| 9 | + * (see sql-driver / engine `missingFieldValues`). This lint catches the two |
| 10 | + * ways an author (very often an AI generating templates) gets that wrong, |
| 11 | + * BEFORE it ships: |
| 12 | + * |
| 13 | + * - ERROR: `{field}` names a field that does not exist on the object — the |
| 14 | + * generation will always throw. This is broken, so it fails the build. |
| 15 | + * - WARNING: `{field}` names an OPTIONAL field — generation throws on any |
| 16 | + * record left blank. The robust shape marks the referenced field |
| 17 | + * `required: true` (mirroring ERPNext/Odoo, where a field that drives the |
| 18 | + * naming series must be mandatory). Advisory; does not fail the build. |
| 19 | + * |
| 20 | + * A self-reference (`{self}` on the autonumber field itself) is always an |
| 21 | + * ERROR — the value does not exist yet when the format renders. |
| 22 | + */ |
| 23 | + |
| 24 | +import { parseAutonumberFormat, referencedFields } from '@objectstack/spec/data'; |
| 25 | + |
| 26 | +export interface AutonumberLintFinding { |
| 27 | + where: string; |
| 28 | + message: string; |
| 29 | + hint: string; |
| 30 | + rule: string; |
| 31 | + severity: 'error' | 'warning'; |
| 32 | +} |
| 33 | + |
| 34 | +type AnyRec = Record<string, unknown>; |
| 35 | + |
| 36 | +export const AUTONUMBER_UNKNOWN_FIELD = 'autonumber-references-unknown-field'; |
| 37 | +export const AUTONUMBER_OPTIONAL_FIELD = 'autonumber-references-optional-field'; |
| 38 | +export const AUTONUMBER_SELF_REFERENCE = 'autonumber-references-self'; |
| 39 | + |
| 40 | +function asArray(v: unknown): AnyRec[] { |
| 41 | + if (Array.isArray(v)) return v as AnyRec[]; |
| 42 | + if (v && typeof v === 'object') { |
| 43 | + return Object.entries(v as AnyRec).map(([name, def]) => ({ name, ...(def as AnyRec) })); |
| 44 | + } |
| 45 | + return []; |
| 46 | +} |
| 47 | + |
| 48 | +/** |
| 49 | + * Lint every `autonumber` field's format for unresolvable / fragile `{field}` |
| 50 | + * interpolation. Returns a (possibly empty) list of findings; never throws. |
| 51 | + */ |
| 52 | +export function lintAutonumberFormats(stack: AnyRec): AutonumberLintFinding[] { |
| 53 | + const findings: AutonumberLintFinding[] = []; |
| 54 | + for (const obj of asArray(stack.objects)) { |
| 55 | + const objectName = typeof obj.name === 'string' ? obj.name : '(unnamed object)'; |
| 56 | + const fields = asArray(obj.fields); |
| 57 | + // name → required?, for schema-aware reference checks. |
| 58 | + const fieldMeta = new Map<string, { required: boolean }>(); |
| 59 | + for (const f of fields) { |
| 60 | + if (typeof f.name === 'string') fieldMeta.set(f.name, { required: f.required === true }); |
| 61 | + } |
| 62 | + |
| 63 | + for (const f of fields) { |
| 64 | + if (f.type !== 'autonumber') continue; |
| 65 | + const name = typeof f.name === 'string' ? f.name : '(unnamed field)'; |
| 66 | + const fmt = typeof f.autonumberFormat === 'string' |
| 67 | + ? f.autonumberFormat |
| 68 | + : (typeof f.format === 'string' ? f.format : ''); |
| 69 | + if (!fmt) continue; |
| 70 | + const refs = referencedFields(parseAutonumberFormat(fmt)); |
| 71 | + const where = `object '${objectName}' · field '${name}' (autonumber "${fmt}")`; |
| 72 | + for (const ref of refs) { |
| 73 | + if (ref === name) { |
| 74 | + findings.push({ |
| 75 | + where, |
| 76 | + message: `format interpolates \`{${ref}}\` — its own value, which does not exist yet when the number is generated.`, |
| 77 | + hint: `Reference a DIFFERENT field that is set before create (e.g. \`{plan_no}{000}\`), or drop the token.`, |
| 78 | + rule: AUTONUMBER_SELF_REFERENCE, |
| 79 | + severity: 'error', |
| 80 | + }); |
| 81 | + continue; |
| 82 | + } |
| 83 | + const meta = fieldMeta.get(ref); |
| 84 | + if (!meta) { |
| 85 | + findings.push({ |
| 86 | + where, |
| 87 | + message: `format interpolates \`{${ref}}\`, but object '${objectName}' has no field named '${ref}' — generation will always throw.`, |
| 88 | + hint: `Reference an existing field, or remove the \`{${ref}}\` token from the format.`, |
| 89 | + rule: AUTONUMBER_UNKNOWN_FIELD, |
| 90 | + severity: 'error', |
| 91 | + }); |
| 92 | + } else if (!meta.required) { |
| 93 | + findings.push({ |
| 94 | + where, |
| 95 | + message: `format interpolates \`{${ref}}\`, but '${ref}' is optional — any record left blank fails autonumber generation at create time.`, |
| 96 | + hint: `Mark '${ref}' as \`required: true\` so it is always set before the record number is rendered.`, |
| 97 | + rule: AUTONUMBER_OPTIONAL_FIELD, |
| 98 | + severity: 'warning', |
| 99 | + }); |
| 100 | + } |
| 101 | + } |
| 102 | + } |
| 103 | + } |
| 104 | + return findings; |
| 105 | +} |
0 commit comments