diff --git a/docs/cubelab-fingerprint.md b/docs/cubelab-fingerprint.md index 3e3f6253..af69e73c 100644 --- a/docs/cubelab-fingerprint.md +++ b/docs/cubelab-fingerprint.md @@ -37,13 +37,18 @@ word). When the 3D view is not shown (2D net, other pages) the block is absent. | Field | Type | Meaning | | -------- | ------- | ------------------------------------------------------------ | -| `size` | integer | Cube size, 2 to 7 (an N×N×N cube). | +| `size` | integer | Cube size, 2 to 15 (an N×N×N cube). | | `moves` | string | The move history, turns separated by single spaces, or `""`. | -| `format` | string | The notation id; currently always `layer-prefix/v1`. | +| `format` | string | The notation id: `layer-prefix/v1` or `layer-prefix/v2`. | -The JSON is validated by +The app writes `layer-prefix/v1` for cube sizes 2 to 7 and `layer-prefix/v2` +for sizes 8 to 15. The format follows the cube size, so the same size always +gets the same id. The JSON is validated by [`cubelab-fingerprint-v1.schema.json`](https://wstein.github.io/cube-assembler/schemas/cubelab-fingerprint-v1.schema.json) -(source: `public/schemas/`). The text inside the element escapes `<` as +(size 2 to 7) or +[`cubelab-fingerprint-v2.schema.json`](https://wstein.github.io/cube-assembler/schemas/cubelab-fingerprint-v2.schema.json) +(size 2 to 15; the app writes it from size 8); the sources are in +`public/schemas/`. The text inside the element escapes `<` as `<`; `JSON.parse` returns the original characters. ## Move notation `layer-prefix/v1` @@ -72,13 +77,50 @@ One turn is `[layers]FACE[w][amount]`, or a whole-cube rotation. Moves are written for the cube `size` in the block; the same turn can differ between sizes (for example, a block as wide as the cube is a rotation). +## Move notation `layer-prefix/v2` + +`layer-prefix/v2` is `layer-prefix/v1` with layer numbers of one or two +digits, for cubes up to 15×15×15. Nothing else changes: face letters, `w`, +amounts, whole-cube rotations and merging are as above, and the turns of a +cube up to 7×7 are written the same in both formats. A reader that supports v2 +reads v1 text with the same grammar. + +A turn is one of these tokens, with `N` a layer number from 2 to 15 (written +without leading zeros, one digit for 2 to 9, two digits for 10 to 15): + +``` +turn = [ layers ] FACE [ "w" ] [ amount ] | ROTATION [ amount ] +layers = N "-" N | N +FACE = "U" | "R" | "F" | "D" | "L" | "B" +ROTATION = "x" | "y" | "z" +amount = "'" | "2" +N = "2" | ... | "9" | "10" | ... | "15" +``` + +The history is the turns joined by single spaces. The text has no ambiguity +between depth, width and amount, because the face letter separates them: +digits before the face letter are layer numbers, and the only digit after it is +the amount `2`. Examples on a 15×15×15 cube: + +- `10R`: the tenth layer from the right face; `10R2` the same, a half turn. +- `12Uw`: the twelve outermost layers on the top, counted from the top face + (`w` makes the number a width). On a 5×5, `3Rw` is the same form. +- `10-12Rw'`: layers 10 to 12 from the right face, counterclockwise. +- `Rw` is the two outermost layers, as in v1. + +The schema checks the text form only, not that a turn fits the cube size, as in +v1. + ## Versioning Fields may be added to the block or marker without changing `spec`; readers must ignore fields and `key=value` pairs they do not know. `spec` rises only for a breaking change (a field removed, renamed or reinterpreted). A new -notation gets a new `format` id (for example `layer-prefix/v2`) instead of -changing `layer-prefix/v1`. +notation gets a new `format` id instead of changing `layer-prefix/v1`; +`layer-prefix/v2` is the first such notation, and `spec` stays 1 because +readers that know only v1 can tell from `format` that they do not understand +the block. `layer-prefix/v1` is unchanged: the app still writes it, byte for +byte, for cube sizes 2 to 7. ## Privacy diff --git a/public/schemas/cubelab-fingerprint-v2.schema.json b/public/schemas/cubelab-fingerprint-v2.schema.json new file mode 100644 index 00000000..2729dc54 --- /dev/null +++ b/public/schemas/cubelab-fingerprint-v2.schema.json @@ -0,0 +1,23 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://wstein.github.io/cube-assembler/schemas/cubelab-fingerprint-v2.schema.json", + "title": "CubeAssembler CubeLab moves block v2", + "description": "The JSON inside string @genType type payload = { diff --git a/test/cubelabFingerprint.test.ts b/test/cubelabFingerprint.test.ts index 161d520e..ab5a7bd8 100644 --- a/test/cubelabFingerprint.test.ts +++ b/test/cubelabFingerprint.test.ts @@ -7,7 +7,11 @@ import { cubeLabMovesPayload, escapeScriptJson, } from '../src/client/cubeLabFingerprint' -import { generateScrambleMoves } from '../src/cube/cubeMoves' +import { + type CubeTurn, + formatCubeTurn, + generateScrambleMoves, +} from '../src/cube/cubeMoves' const schema = JSON.parse( readFileSync( @@ -16,6 +20,14 @@ const schema = JSON.parse( ), ) const validate = new Ajv2020({ allErrors: true }).compile(schema) +const schemaV2 = JSON.parse( + readFileSync( + join(__dirname, '../public/schemas/cubelab-fingerprint-v2.schema.json'), + 'utf8', + ), +) +const validateV2 = new Ajv2020({ allErrors: true }).compile(schemaV2) +const FACES = ['U', 'R', 'F', 'D', 'L', 'B'] as const describe('CubeLab moves block', () => { it('has the published schema id', () => { @@ -89,3 +101,133 @@ describe('CubeLab moves block', () => { expect(validate({ ...good, moves: 7 })).toBe(false) }) }) + +// Reads a turn written by layer-prefix/v1 or v2 back into the layers it moves +// (counted from the named face) so a test can compare it with the turn. +function readTurn(text: string) { + const m = /^(?:(\d+)-(\d+)|(\d+))?([URFDLB])(w?)(['2]?)$/.exec(text) + if (!m) return undefined + const [, outer, inner, single, face, wide] = m + if (outer !== undefined) { + return { face, outer: Number(outer), inner: Number(inner) } + } + const depth = single === undefined ? 1 : Number(single) + return wide + ? { face, outer: 1, inner: depth === 1 ? 2 : depth } + : { + face, + outer: depth, + inner: depth, + } +} + +describe('CubeLab moves block v2 (layer-prefix/v2)', () => { + it('has the published schema id', () => { + expect(schemaV2.$id).toBe( + 'https://wstein.github.io/cube-assembler/schemas/cubelab-fingerprint-v2.schema.json', + ) + }) + + it('writes v1 up to 7x7 and v2 above, with the same turn text', () => { + const turns: CubeTurn[] = [{ face: 'R', depth: 2, turns: 1 }] + expect(cubeLabMovesPayload(turns, 7).format).toBe('layer-prefix/v1') + expect(cubeLabMovesPayload(turns, 8).format).toBe('layer-prefix/v2') + expect(cubeLabMovesPayload(turns, 15)).toEqual({ + size: 15, + moves: '2R', + format: 'layer-prefix/v2', + }) + }) + + it('writes two-digit layers and ranges', () => { + const turns: CubeTurn[] = [ + { face: 'R', depth: 10, turns: 1 }, + { face: 'L', depth: 12, width: 3, turns: -1 }, + { face: 'U', depth: 12, width: 12, turns: 2 }, + { face: 'F', depth: 11, width: 11, turns: 1 }, + ] + expect(cubeLabMovesPayload(turns, 15).moves).toBe("10R 10-12Lw' 12Uw2 11Fw") + }) + + it('validates every size, depth and width as written and reads them back', () => { + for (let size = 2; size <= 15; size++) { + const v2 = size > 7 + for (const face of FACES) { + for (let depth = 1; depth < size; depth++) { + for (let width = 1; width <= depth; width++) { + for (const turns of [1, -1, 2]) { + const turn: CubeTurn = { face, depth, width, turns } + const text = formatCubeTurn(turn, size) + const payload = cubeLabMovesPayload([turn], size) + expect(payload.moves).toBe(text) + const check = v2 ? validateV2 : validate + expect(check(payload), text + ' ' + size).toBe(true) + expect((v2 ? validate : validateV2)(payload), text).toBe(false) + const back = readTurn(text.replace(/['2]$/, '')) + expect(back, text).toEqual({ + face, + outer: depth - width + 1, + inner: depth, + }) + } + } + } + } + } + }) + + it('accepts two-digit notation and whole-cube turns', () => { + for (const moves of [ + "10-12Rw 12Uw' 15R2 x y2 z'", + "2R 3-4Fw2 10B'", + '11-14Dw', + ]) { + expect(validateV2({ size: 15, moves, format: 'layer-prefix/v2' })).toBe( + true, + ) + } + }) + + it('validates scrambles of the sizes above 7', () => { + for (let size = 8; size <= 15; size++) { + const moves = generateScrambleMoves( + size, + { length: 'long', innerLayers: true }, + (() => { + let n = 0 + return () => ((n = (n * 7919 + 13) % 1009) + 0.5) / 1009 + })(), + ) + const payload = JSON.parse(cubeLabMovesJson(moves, size)) + expect(validateV2(payload), JSON.stringify(validateV2.errors)).toBe(true) + } + }) + + it('rejects what v2 does not allow', () => { + const good = { size: 12, moves: "10-12Rw 11U'", format: 'layer-prefix/v2' } + expect(validateV2(good)).toBe(true) + expect(validateV2({ ...good, size: 16 })).toBe(false) + expect(validateV2({ ...good, size: 1 })).toBe(false) + expect(validateV2({ ...good, moves: '16R' })).toBe(false) + expect(validateV2({ ...good, moves: '1R' })).toBe(false) + expect(validateV2({ ...good, moves: '0R' })).toBe(false) + expect(validateV2({ ...good, moves: '02R' })).toBe(false) + expect(validateV2({ ...good, moves: '010R' })).toBe(false) + expect(validateV2({ ...good, moves: '02-10Rw' })).toBe(false) + expect(validateV2({ ...good, moves: '10' })).toBe(false) + expect(validateV2({ ...good, moves: '10-Rw' })).toBe(false) + expect(validateV2({ ...good, moves: '1-2-3Rw' })).toBe(false) + expect(validateV2({ ...good, moves: 'R U' })).toBe(false) + expect(validateV2({ ...good, format: 'layer-prefix/v1' })).toBe(false) + expect(validate({ ...good, format: 'layer-prefix/v1' })).toBe(false) + }) + + it('keeps v1 closed to two-digit layers and sizes above 7', () => { + const good = { size: 7, moves: "3Rw 2-3Uw'", format: 'layer-prefix/v1' } + expect(validate(good)).toBe(true) + expect(validate({ ...good, size: 8 })).toBe(false) + expect(validate({ ...good, moves: '8R' })).toBe(false) + expect(validate({ ...good, moves: '10R' })).toBe(false) + expect(validate({ ...good, moves: '2-10Rw' })).toBe(false) + }) +}) diff --git a/test/fixtureMetaSchema.test.ts b/test/fixtureMetaSchema.test.ts index 01eff966..8f3e9cf0 100644 --- a/test/fixtureMetaSchema.test.ts +++ b/test/fixtureMetaSchema.test.ts @@ -47,4 +47,49 @@ describe('published fixture metadata schema', () => { }), ).toBe(false) }) + + it('accepts every cube size from 2 to 15 with size-squared facelet blocks', () => { + const schema = JSON.parse(readFileSync(schemaFile, 'utf8')) + const validate = new Ajv2020().compile(schema) + const meta = JSON.parse( + readFileSync( + join(fixtureRoot, 'synthetic-sanity-check', 'meta.json'), + 'utf8', + ), + ) + const sized = (size: number, count = size * size) => { + const block = 'W'.repeat(count) + return { + ...meta, + gridSize: size, + colorsURFDLB: Array(6).fill(block).join(' '), + detectedURFDLB: Array(6).fill(block).join(' '), + } + } + for (let size = 2; size <= 15; size++) { + expect(validate(sized(size)), 'size ' + size).toBe(true) + } + }) + + it('rejects sizes and facelet blocks outside 2 to 15', () => { + const schema = JSON.parse(readFileSync(schemaFile, 'utf8')) + const validate = new Ajv2020().compile(schema) + const meta = JSON.parse( + readFileSync( + join(fixtureRoot, 'synthetic-sanity-check', 'meta.json'), + 'utf8', + ), + ) + const block = (count: number) => Array(6).fill('W'.repeat(count)).join(' ') + expect(validate({ ...meta, gridSize: 16 })).toBe(false) + expect(validate({ ...meta, gridSize: 1 })).toBe(false) + expect(validate({ ...meta, gridSize: 15.5 })).toBe(false) + expect(validate({ ...meta, gridSize: 15, colorsURFDLB: block(225) })).toBe( + true, + ) + expect(validate({ ...meta, gridSize: 15, colorsURFDLB: block(226) })).toBe( + false, + ) + expect(validate({ ...meta, colorsURFDLB: block(3) })).toBe(false) + }) }) diff --git a/test/fixtures/README.md b/test/fixtures/README.md index 1b314e43..41765b88 100644 --- a/test/fixtures/README.md +++ b/test/fixtures/README.md @@ -33,7 +33,8 @@ New metadata and the checked-in fixtures point `$schema` to the [published fixture metadata schema](https://wstein.github.io/cube-assembler/schemas/fixture-meta-v1.schema.json). Editors can use it to check required fields and photo references. The app also checks that each facelet block has exactly `gridSize²` stickers. Older fixture -files without `$schema` remain importable. +files without `$schema` remain importable. The schema accepts cube sizes 2 +to 15 (up to 225 sticker letters per facelet block); older files stay valid. The optional server listens on `127.0.0.1:7100` and accepts one multipart `POST /upload` with a `name` field and seven `file` parts (one `meta.json`