|
| 1 | +#!/usr/bin/env node |
| 2 | +// Gate: the extract engine's FieldKind vocabulary is IDENTICAL across ports. |
| 3 | +// |
| 4 | +// Every port's extract engine runs fixtures/extract-conformance/, whose schema.json `kind` |
| 5 | +// values ARE this vocabulary. A port that adds or drops a kind changes what the shared corpus |
| 6 | +// can express while every existing fixture keeps passing — so the drift is invisible by |
| 7 | +// construction. It had already happened: C# carries a Decimal kind no other port has and no |
| 8 | +// fixture exercises. |
| 9 | +// |
| 10 | +// Reads each port's real definition (not a duplicated list) and compares against |
| 11 | +// fixtures/extract-conformance/expected-field-kinds.json. Deviations are allowed only when |
| 12 | +// that file records them, with a reason, under `sanctionedDeviations`. |
| 13 | +// |
| 14 | +// Offline, no build, no network. |
| 15 | + |
| 16 | +import { readFileSync } from "node:fs"; |
| 17 | +import { join, dirname } from "node:path"; |
| 18 | +import { fileURLToPath } from "node:url"; |
| 19 | + |
| 20 | +const ROOT = join(dirname(fileURLToPath(import.meta.url)), ".."); |
| 21 | +const MANIFEST = "fixtures/extract-conformance/expected-field-kinds.json"; |
| 22 | + |
| 23 | +const expected = JSON.parse(readFileSync(join(ROOT, MANIFEST), "utf8")); |
| 24 | +const canonical = expected.canonical; |
| 25 | + |
| 26 | +/** |
| 27 | + * Pull the member names out of one port's FieldKind definition. |
| 28 | + * |
| 29 | + * Deliberately per-language and deliberately narrow: each pattern matches that port's actual |
| 30 | + * declaration syntax and nothing else, so a definition that MOVED or was rewritten in a shape |
| 31 | + * this does not recognise fails loudly (unknown-shape) instead of silently reporting an empty |
| 32 | + * member set — which would read as "no drift" and is the one failure mode that would defeat |
| 33 | + * the whole gate. |
| 34 | + */ |
| 35 | +function membersOf(port, src) { |
| 36 | + switch (port) { |
| 37 | + case "java": { |
| 38 | + // public enum FieldKind { STRING, INT, ... } |
| 39 | + const m = src.match(/enum\s+FieldKind\s*\{([^}]*)\}/); |
| 40 | + if (!m) return null; |
| 41 | + return m[1].split(",").map((s) => s.trim()).filter(Boolean); |
| 42 | + } |
| 43 | + case "csharp": { |
| 44 | + // public enum FieldKind { String, Int, ... } (PascalCase members) |
| 45 | + const m = src.match(/enum\s+FieldKind\s*\{([^}]*)\}/); |
| 46 | + if (!m) return null; |
| 47 | + return m[1].split(",").map((s) => s.trim()).filter(Boolean) |
| 48 | + .map((s) => s.toUpperCase()); |
| 49 | + } |
| 50 | + case "typescript": { |
| 51 | + // export const FieldKind = { STRING: "STRING", ... } as const; |
| 52 | + const m = src.match(/const\s+FieldKind\s*=\s*\{([\s\S]*?)\}\s*as\s+const/); |
| 53 | + if (!m) return null; |
| 54 | + return [...m[1].matchAll(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*:/gm)].map((x) => x[1]); |
| 55 | + } |
| 56 | + case "python": { |
| 57 | + // class FieldKind(Enum):\n STRING = "STRING"\n ... |
| 58 | + const m = src.match(/class\s+FieldKind\s*\(\s*Enum\s*\)\s*:([\s\S]*?)(?=\n\S|\nclass\s)/); |
| 59 | + if (!m) return null; |
| 60 | + return [...m[1].matchAll(/^\s+([A-Z][A-Z0-9_]*)\s*=/gm)].map((x) => x[1]); |
| 61 | + } |
| 62 | + default: |
| 63 | + return null; |
| 64 | + } |
| 65 | +} |
| 66 | + |
| 67 | +const problems = []; |
| 68 | + |
| 69 | +for (const [port, relPath] of Object.entries(expected.ports)) { |
| 70 | + let src; |
| 71 | + try { |
| 72 | + src = readFileSync(join(ROOT, relPath), "utf8"); |
| 73 | + } catch { |
| 74 | + problems.push(`${port}: cannot read ${relPath} — did the definition move? Update ${MANIFEST}.`); |
| 75 | + continue; |
| 76 | + } |
| 77 | + |
| 78 | + const found = membersOf(port, src); |
| 79 | + if (found === null || found.length === 0) { |
| 80 | + problems.push( |
| 81 | + `${port}: could not parse a FieldKind definition out of ${relPath}. ` + |
| 82 | + `The declaration shape changed; fix the matcher in this script rather than ` + |
| 83 | + `letting it report an empty set.`); |
| 84 | + continue; |
| 85 | + } |
| 86 | + |
| 87 | + const allow = expected.sanctionedDeviations?.[port] ?? { extra: [], missing: [] }; |
| 88 | + const allowedExtra = new Set(allow.extra ?? []); |
| 89 | + const allowedMissing = new Set(allow.missing ?? []); |
| 90 | + |
| 91 | + const extra = found.filter((k) => !canonical.includes(k) && !allowedExtra.has(k)); |
| 92 | + const missing = canonical.filter((k) => !found.includes(k) && !allowedMissing.has(k)); |
| 93 | + // A recorded deviation that is no longer TRUE is also drift: it means someone fixed (or |
| 94 | + // re-broke) the port and left the record claiming otherwise, and the next reader trusts it. |
| 95 | + const staleExtra = [...allowedExtra].filter((k) => !found.includes(k)); |
| 96 | + const staleMissing = [...allowedMissing].filter((k) => found.includes(k)); |
| 97 | + |
| 98 | + if (extra.length) problems.push(`${port}: unexpected FieldKind member(s): ${extra.join(", ")}`); |
| 99 | + if (missing.length) problems.push(`${port}: missing FieldKind member(s): ${missing.join(", ")}`); |
| 100 | + if (staleExtra.length) |
| 101 | + problems.push(`${port}: ${MANIFEST} records extra member(s) ${staleExtra.join(", ")} that are GONE — delete the stale sanctionedDeviations entry.`); |
| 102 | + if (staleMissing.length) |
| 103 | + problems.push(`${port}: ${MANIFEST} records missing member(s) ${staleMissing.join(", ")} that are now PRESENT — delete the stale sanctionedDeviations entry.`); |
| 104 | +} |
| 105 | + |
| 106 | +// Kotlin must NOT grow its own engine vocabulary: it drives the shared Java one. |
| 107 | +if (expected.kotlinReusesJava) { |
| 108 | + let kotlinOwn = []; |
| 109 | + try { |
| 110 | + const out = (await import("node:child_process")).execFileSync( |
| 111 | + "git", ["grep", "-l", "-E", "(enum class|val)\\s+FieldKind", "--", "server/java/codegen-kotlin", "server/java/metadata-ktx"], |
| 112 | + { cwd: ROOT, encoding: "utf8" }); |
| 113 | + kotlinOwn = out.split("\n").filter(Boolean); |
| 114 | + } catch { /* git grep exits 1 with no matches — the good case */ } |
| 115 | + if (kotlinOwn.length) |
| 116 | + problems.push( |
| 117 | + `kotlin: declares its own FieldKind in ${kotlinOwn.join(", ")}. Kotlin drives the shared ` + |
| 118 | + `Java extract engine; a second definition IS the drift this gate exists to catch.`); |
| 119 | +} |
| 120 | + |
| 121 | +if (problems.length) { |
| 122 | + console.error("extract FieldKind vocabulary drift:\n"); |
| 123 | + for (const p of problems) console.error(` - ${p}`); |
| 124 | + console.error(`\n Canonical set (${MANIFEST}): ${canonical.join(", ")}`); |
| 125 | + console.error(" Every port's extract engine runs fixtures/extract-conformance/, so this"); |
| 126 | + console.error(" vocabulary is a shared contract, not a per-port implementation detail."); |
| 127 | + process.exit(1); |
| 128 | +} |
| 129 | + |
| 130 | +const dev = Object.keys(expected.sanctionedDeviations ?? {}); |
| 131 | +console.log( |
| 132 | + `extract FieldKind: ${Object.keys(expected.ports).length} ports agree on ` + |
| 133 | + `[${canonical.join(", ")}]` + |
| 134 | + (dev.length ? ` (${dev.length} sanctioned deviation(s): ${dev.join(", ")})` : "")); |
0 commit comments