|
| 1 | +// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license. |
| 2 | + |
| 3 | +/** |
| 4 | + * [ADR-0146 D10, second rule] The TARGET CHECK of an object extension's |
| 5 | + * `fieldPatches`: does the object it extends have every field it patches, and |
| 6 | + * every option value it patches under `options`? |
| 7 | + * |
| 8 | + * The slot's SHAPE is the spec's (`ObjectExtensionSchema.fieldPatches`, keys |
| 9 | + * derived from `BASE_FIELD_DISPLAY_WHITELIST`); whether the names it uses exist |
| 10 | + * is a question about the target, so it is answered where the target is known. |
| 11 | + * One judge, three readers: |
| 12 | + * |
| 13 | + * - the marketplace install door (`POST /api/v1/marketplace/install-local`) |
| 14 | + * REFUSES a package whose patch names what its installed target lacks — |
| 15 | + * ADR-0141 D2 admitted the base first, so the target is in the registry; |
| 16 | + * - `os validate` REFUSES the same patch when the target is in the composed |
| 17 | + * stack; |
| 18 | + * - the registry fold (`@objectstack/objectql`, `SchemaRegistry`) does not |
| 19 | + * apply such a patch and NAMES it once in the log. ⛔ Never a boot refusal: |
| 20 | + * a boot is still filling the registry when the fold first runs (AGENTS.md |
| 21 | + * *Startup registry reads*), and the patch applies the moment the field |
| 22 | + * arrives. |
| 23 | + * |
| 24 | + * A patch that names a field the target does not have would otherwise change |
| 25 | + * nothing, and say nothing: the author reads "Sector" in their package and the |
| 26 | + * screen keeps "Industry". |
| 27 | + * |
| 28 | + * Pure: reads plain bodies and returns findings, so each reader decides what a |
| 29 | + * finding means at its door. |
| 30 | + */ |
| 31 | + |
| 32 | +/** One name a field patch uses that its target object does not have. */ |
| 33 | +export interface FieldPatchTargetMiss { |
| 34 | + /** The extended object, as the extension names it (`extend`). */ |
| 35 | + object: string; |
| 36 | + /** The patched field — the key under `fieldPatches`. */ |
| 37 | + field: string; |
| 38 | + /** The patched option's stored value — the key under the patch's `options` — when the miss is an option. */ |
| 39 | + option?: string; |
| 40 | + /** |
| 41 | + * What is missing: `field` (no such field), `option` (no option with that |
| 42 | + * stored value), or `picklist-option` (the field takes its options from a |
| 43 | + * picklist, which no field patch reaches). |
| 44 | + */ |
| 45 | + reason: 'field' | 'option' | 'picklist-option'; |
| 46 | + /** The sentence an author is shown: what is missing, and what to write instead. */ |
| 47 | + message: string; |
| 48 | +} |
| 49 | + |
| 50 | +/** A {@link FieldPatchTargetMiss} located in the manifest that declares it. */ |
| 51 | +export interface FieldPatchTargetRefusal extends FieldPatchTargetMiss { |
| 52 | + /** Where the patch sits, e.g. `objectExtensions[0].fieldPatches.industry.options.tech`. */ |
| 53 | + path: string; |
| 54 | +} |
| 55 | + |
| 56 | +const isRecord = (v: unknown): v is Record<string, unknown> => |
| 57 | + v !== null && typeof v === 'object' && !Array.isArray(v); |
| 58 | + |
| 59 | +/** A field of an object body, by name — a name-keyed record or a `name`-bearing array, the two spellings a body carries. */ |
| 60 | +function fieldOf(target: unknown, name: string): Record<string, unknown> | undefined { |
| 61 | + if (!isRecord(target)) return undefined; |
| 62 | + const fields = target.fields; |
| 63 | + if (Array.isArray(fields)) { |
| 64 | + const found = fields.find((f) => isRecord(f) && f.name === name); |
| 65 | + return isRecord(found) ? found : undefined; |
| 66 | + } |
| 67 | + if (!isRecord(fields) || !Object.prototype.hasOwnProperty.call(fields, name)) return undefined; |
| 68 | + const field = fields[name]; |
| 69 | + return isRecord(field) ? field : undefined; |
| 70 | +} |
| 71 | + |
| 72 | +/** The stored values of a field's own `options`, in order. */ |
| 73 | +function optionValuesOf(field: Record<string, unknown>): string[] { |
| 74 | + const options = field.options; |
| 75 | + if (!Array.isArray(options)) return []; |
| 76 | + return options |
| 77 | + .map((o) => (isRecord(o) ? o.value : undefined)) |
| 78 | + .filter((v): v is string => typeof v === 'string'); |
| 79 | +} |
| 80 | + |
| 81 | +/** |
| 82 | + * Every name `fieldPatches` uses that `target` does not have. `[]` when the |
| 83 | + * patch is absent, malformed (the schema's parse reports that), or fully |
| 84 | + * matched. |
| 85 | + * |
| 86 | + * `target` is the extended object as the reader sees it: the registry's |
| 87 | + * resolved object at the install door and in the fold, the composed stack's |
| 88 | + * declaration at `os validate`. |
| 89 | + */ |
| 90 | +export function fieldPatchTargetMisses(object: string, fieldPatches: unknown, target: unknown): FieldPatchTargetMiss[] { |
| 91 | + if (!isRecord(fieldPatches)) return []; |
| 92 | + const misses: FieldPatchTargetMiss[] = []; |
| 93 | + for (const [fieldName, patch] of Object.entries(fieldPatches)) { |
| 94 | + const field = fieldOf(target, fieldName); |
| 95 | + if (!field) { |
| 96 | + misses.push({ |
| 97 | + object, |
| 98 | + field: fieldName, |
| 99 | + reason: 'field', |
| 100 | + message: |
| 101 | + `\`fieldPatches.${fieldName}\` names a field object \`${object}\` does not have, so the patch would ` + |
| 102 | + `change nothing. A field patch changes the display of one of the extended object's own fields: ` + |
| 103 | + `use the name of a field \`${object}\` declares, or declare a field of your own in \`fields\`.`, |
| 104 | + }); |
| 105 | + continue; |
| 106 | + } |
| 107 | + const options = isRecord(patch) ? patch.options : undefined; |
| 108 | + if (!isRecord(options)) continue; |
| 109 | + const picklist = typeof field.picklist === 'string' && field.picklist !== '' ? field.picklist : undefined; |
| 110 | + const values = optionValuesOf(field); |
| 111 | + for (const value of Object.keys(options)) { |
| 112 | + if (picklist !== undefined) { |
| 113 | + misses.push({ |
| 114 | + object, |
| 115 | + field: fieldName, |
| 116 | + option: value, |
| 117 | + reason: 'picklist-option', |
| 118 | + message: |
| 119 | + `\`fieldPatches.${fieldName}.options.${value}\` patches an option of \`${object}.${fieldName}\`, ` + |
| 120 | + `which takes its options from the picklist \`${picklist}\`: the option labels are the picklist's, ` + |
| 121 | + `and a field patch never reaches them. Remove \`options\` from this patch.`, |
| 122 | + }); |
| 123 | + continue; |
| 124 | + } |
| 125 | + if (values.includes(value)) continue; |
| 126 | + misses.push({ |
| 127 | + object, |
| 128 | + field: fieldName, |
| 129 | + option: value, |
| 130 | + reason: 'option', |
| 131 | + message: |
| 132 | + `\`fieldPatches.${fieldName}.options.${value}\` names an option \`${object}.${fieldName}\` does not ` + |
| 133 | + `have: an option is addressed by its stored \`value\`, and this field's are ` + |
| 134 | + `${values.length > 0 ? values.map((v) => `\`${v}\``).join(', ') : 'none'}. ` + |
| 135 | + 'Which options exist stays the vendor\'s, so a patch can only relabel one of them.', |
| 136 | + }); |
| 137 | + } |
| 138 | + } |
| 139 | + return misses; |
| 140 | +} |
| 141 | + |
| 142 | +/** |
| 143 | + * Every patch in a manifest's `objectExtensions` that names what its target |
| 144 | + * lacks, located. An entry whose target `getTarget` does not know is not |
| 145 | + * judged: at the install door that target is ADR-0141 D2's to answer, and at |
| 146 | + * `os validate` a target outside the composed stack is judged at install. |
| 147 | + * |
| 148 | + * `pathPrefix` locates the entries for a multi-package artifact |
| 149 | + * (`packages[1].manifest.`); empty for a single stack. |
| 150 | + */ |
| 151 | +export function fieldPatchTargetRefusals( |
| 152 | + objectExtensions: unknown, |
| 153 | + getTarget: (name: string) => unknown, |
| 154 | + pathPrefix = '', |
| 155 | +): FieldPatchTargetRefusal[] { |
| 156 | + if (!Array.isArray(objectExtensions)) return []; |
| 157 | + const refusals: FieldPatchTargetRefusal[] = []; |
| 158 | + objectExtensions.forEach((entry, index) => { |
| 159 | + if (!isRecord(entry) || typeof entry.extend !== 'string' || !isRecord(entry.fieldPatches)) return; |
| 160 | + const target = getTarget(entry.extend); |
| 161 | + if (target === undefined || target === null) return; |
| 162 | + for (const miss of fieldPatchTargetMisses(entry.extend, entry.fieldPatches, target)) { |
| 163 | + const at = `${pathPrefix}objectExtensions[${index}].fieldPatches.${miss.field}`; |
| 164 | + refusals.push({ ...miss, path: miss.option === undefined ? at : `${at}.options.${miss.option}` }); |
| 165 | + } |
| 166 | + }); |
| 167 | + return refusals; |
| 168 | +} |
| 169 | + |
| 170 | +/** |
| 171 | + * The install door's refusal sentence for a non-empty |
| 172 | + * {@link fieldPatchTargetRefusals} answer: how many, the first one whole, and |
| 173 | + * that nothing was installed. Every refusal is listed in the answer's |
| 174 | + * `details.refusals`. |
| 175 | + */ |
| 176 | +export function fieldPatchTargetRefusalMessage(packageId: string, refusals: readonly FieldPatchTargetRefusal[]): string { |
| 177 | + const n = refusals.length; |
| 178 | + return ( |
| 179 | + `Package '${packageId}' cannot be installed: ${n} field patch${n > 1 ? 'es name' : ' names'} a field or option ` + |
| 180 | + `the extended object does not have (ADR-0146 D10). ${refusals[0]?.path}: ${refusals[0]?.message}` + |
| 181 | + (n > 1 ? ` (${n - 1} more in \`details.refusals\`.)` : '') + |
| 182 | + ' Nothing was installed or written.' |
| 183 | + ); |
| 184 | +} |
0 commit comments