mirror of
https://github.com/garrytan/gstack.git
synced 2026-09-10 23:19:09 +02:00
Garry TanandClaude Fable 5.1
b4d88a0126
renderDesignMd re-sorted canonical section names into spec order on every render, so `gstack-design-md mark legacy-keep` (the "leave it alone" answer) and the design binary's mockup extraction reordered a legacy DESIGN.md (Typography and Layout jumped to the top) and normalized its whitespace, while the bin promised "body bytes untouched". `mark` now splices only the marker line (insertMarker) and `updateDesignMd` splices only its own section (spliceSection); every other byte of an existing file is preserved, and spec order applies only to files that open with front matter. `mark` refuses a choice that contradicts the file's format (spec on a non-spec file, legacy-keep on a spec file) with DESIGN_MD_CONVERT_REFUSED, exit 2, file unchanged. convertLegacy keeps intro prose under the title instead of rebuilding the preamble from the title alone. detectFormat returns a machine-readable `code` beside the prose reason (the bin no longer branches on reason text); the marker regexes derive from FORMAT_MARKER_PREFIX and FORMAT_CHOICES; the hop limit and legacy identity headings are named constants; slug is exported and reused; both writers use lib/fs-atomic.ts. Tests pin byte identity for mark and updateDesignMd on the legacy fixture, the refusal paths, and the preserved preamble. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
548 lines
29 KiB
TypeScript
548 lines
29 KiB
TypeScript
/**
|
|
* lib/design-md.ts + bin/gstack-design-md.ts + design/src/memory.ts (DESIGN.md writer).
|
|
*
|
|
* Pins the open DESIGN.md format rules gstack depends on: eight canonical
|
|
* sections in order, only the five token groups in front matter, `{path}`
|
|
* references resolving to primitives, extras surviving a round trip, the
|
|
* format marker's placement (YAML comment on line 2 for spec files, HTML
|
|
* comment on line 1 for legacy), body-only upserts that never re-emit front
|
|
* matter bytes, and a legacy → spec conversion of gstack's own DESIGN.md.
|
|
*/
|
|
import { describe, test, expect } from 'bun:test';
|
|
import * as fs from 'fs';
|
|
import * as os from 'os';
|
|
import * as path from 'path';
|
|
import { spawnSync } from 'child_process';
|
|
import {
|
|
parseDesignMd, detectFormat, renderDesignMd, upsertSection, convertLegacy, tokensFlat,
|
|
emitYamlBlock, setMarker, specSkeleton, spliceSection, insertMarker, CANONICAL_SECTIONS, TOKEN_GROUPS, isLegacyGstackFormat,
|
|
} from '../lib/design-md';
|
|
import { updateDesignMd, readDesignConstraints } from '../design/src/memory';
|
|
|
|
const ROOT = path.join(import.meta.dir, '..');
|
|
const BIN = path.join(ROOT, 'bin', 'gstack-design-md.ts');
|
|
const runBin = (args: string[], cwd: string) => {
|
|
const r = spawnSync(process.execPath, ['--no-env-file', 'run', BIN, ...args], { cwd, encoding: 'utf-8', timeout: 60_000 });
|
|
return { code: r.status ?? -1, out: r.stdout ?? '', err: r.stderr ?? '' };
|
|
};
|
|
// gstack's own DESIGN.md is now in the open format; its pre-conversion form is the legacy fixture.
|
|
const LEGACY = fs.readFileSync(path.join(ROOT, 'test', 'fixtures', 'design-md-legacy.md'), 'utf-8');
|
|
|
|
const SPEC = `---
|
|
# gstack: design-md-format=spec
|
|
name: Heritage
|
|
colors:
|
|
primary: "#1A1C1E"
|
|
accent: "#B8422E"
|
|
cta: "{colors.accent}"
|
|
typography:
|
|
display:
|
|
fontFamily: Public Sans
|
|
fontSize: 3rem
|
|
rounded:
|
|
md: 8px
|
|
spacing:
|
|
md: 16px
|
|
components:
|
|
button-primary:
|
|
backgroundColor: "{colors.cta}"
|
|
textColor: "{colors.primary}"
|
|
---
|
|
|
|
# Heritage
|
|
|
|
## Overview
|
|
|
|
Architectural minimalism.
|
|
|
|
## Colors
|
|
|
|
Ink and clay.
|
|
|
|
## Typography
|
|
|
|
Public Sans everywhere.
|
|
|
|
## Motion
|
|
|
|
One authored moment.
|
|
|
|
## Decisions Log
|
|
|
|
| Date | Decision | Rationale |
|
|
|---|---|---|
|
|
| 2026-09-08 | spec format | portable |
|
|
`;
|
|
|
|
describe('parse + detect', () => {
|
|
test('spec file: front matter bytes preserved, marker read from line 2, sections classified', () => {
|
|
const doc = parseDesignMd(SPEC);
|
|
expect(doc.marker).toBe('spec');
|
|
expect(doc.frontmatter?.name).toBe('Heritage');
|
|
expect(doc.frontmatterText).toContain('primary: "#1A1C1E"');
|
|
expect(doc.preamble).toBe('# Heritage');
|
|
expect(doc.sections.map(s => s.canonical ?? s.heading)).toEqual(['Overview', 'Colors', 'Typography', 'Motion', 'Decisions Log']);
|
|
expect(detectFormat(doc)).toEqual({ format: 'spec', code: 'spec' });
|
|
});
|
|
|
|
test("the legacy fixture is legacy, gstack's own DESIGN.md is spec; a fresh file is unknown; nothing is missing", () => {
|
|
const doc = parseDesignMd(LEGACY);
|
|
expect(isLegacyGstackFormat(doc)).toBe(true);
|
|
expect(detectFormat(doc)).toEqual({ format: 'legacy', code: 'legacy' });
|
|
const own = parseDesignMd(fs.readFileSync(path.join(ROOT, 'DESIGN.md'), 'utf-8'));
|
|
expect(detectFormat(own)).toEqual({ format: 'spec', code: 'spec' });
|
|
expect(own.marker).toBe('spec');
|
|
expect(tokensFlat(own.frontmatter).errors).toEqual([]);
|
|
expect(detectFormat(parseDesignMd('# Hello\n\nJust prose.\n')).format).toBe('unknown');
|
|
expect(detectFormat(null)).toEqual({ format: 'missing', code: 'missing' });
|
|
});
|
|
|
|
test('malformed front matter is unknown with a reason, never a throw', () => {
|
|
const doc = parseDesignMd('---\ncolors: [unclosed\n---\n\n## Overview\n\nx\n');
|
|
expect(doc.frontmatter).toBeNull();
|
|
const d = detectFormat(doc);
|
|
expect(d.format).toBe('unknown');
|
|
expect(d.reason).toMatch(/front matter does not parse/);
|
|
});
|
|
|
|
test('legacy headings plus front matter is ambiguous', () => {
|
|
const d = detectFormat(parseDesignMd('---\nname: x\ncolors:\n a: "#fff"\n---\n\n## Product Context\n\nx\n\n## Aesthetic Direction\n\ny\n'));
|
|
expect(d.format).toBe('unknown');
|
|
expect(d.reason).toMatch(/^ambiguous/);
|
|
});
|
|
|
|
test('a ## inside a code fence is not a section', () => {
|
|
const doc = parseDesignMd('## Overview\n\n```md\n## Not a section\n```\n\n## Colors\n\nx\n');
|
|
expect(doc.sections.map(s => s.heading)).toEqual(['Overview', 'Colors']);
|
|
});
|
|
|
|
test('legacy marker on line 1 is read and survives a render', () => {
|
|
const doc = parseDesignMd('<!-- gstack: design-md-format=legacy-keep -->\n# Design System — X\n\n## Product Context\n\n- a\n\n## Color\n\n- **Primary:** #fff\n');
|
|
expect(doc.marker).toBe('legacy-keep');
|
|
const out = renderDesignMd(doc);
|
|
expect(out.split('\n')[0]).toBe('<!-- gstack: design-md-format=legacy-keep -->');
|
|
expect(out).toContain('# Design System — X');
|
|
});
|
|
});
|
|
|
|
describe('render + upsert', () => {
|
|
test('round trip is stable and keeps canonical order with extras after', () => {
|
|
const once = renderDesignMd(parseDesignMd(SPEC));
|
|
expect(renderDesignMd(parseDesignMd(once))).toBe(once);
|
|
const headings = [...once.matchAll(/^## (.+)$/gm)].map(m => m[1]);
|
|
expect(headings).toEqual(['Overview', 'Colors', 'Typography', 'Motion', 'Decisions Log']);
|
|
expect(once.split('\n')[0]).toBe('---');
|
|
expect(once.split('\n')[1]).toBe('# gstack: design-md-format=spec');
|
|
});
|
|
|
|
test('canonical sections re-sort into spec order when the file had them shuffled', () => {
|
|
const shuffled = '---\nname: x\ncolors:\n a: "#fff"\n---\n\n## Typography\n\nt\n\n## Overview\n\no\n\n## Shapes\n\ns\n\n## Colors\n\nc\n\n## Custom\n\nz\n';
|
|
const out = renderDesignMd(parseDesignMd(shuffled));
|
|
const headings = [...out.matchAll(/^## (.+)$/gm)].map(m => m[1]);
|
|
expect(headings).toEqual(['Overview', 'Colors', 'Typography', 'Shapes', 'Custom']);
|
|
const order = headings.filter(h => (CANONICAL_SECTIONS as readonly string[]).includes(h)).map(h => CANONICAL_SECTIONS.indexOf(h as any));
|
|
expect([...order].sort((a, b) => a - b)).toEqual(order);
|
|
});
|
|
|
|
test('aliases map to canonical names (Brand & Style → Overview, Elevation → Elevation & Depth); a spec-shaped file renders them canonically, a plain file keeps its words', () => {
|
|
const plain = parseDesignMd('## Brand & Style\n\nx\n\n## Elevation\n\ny\n');
|
|
expect(plain.sections.map(s => s.canonical)).toEqual(['Overview', 'Elevation & Depth']);
|
|
expect(renderDesignMd(plain)).toContain('## Elevation\n'); // no front matter: the user's headings stay
|
|
const spec = parseDesignMd('---\nname: x\ncolors:\n a: "#fff"\n---\n\n## Elevation\n\ny\n\n## Brand & Style\n\nx\n');
|
|
const out = renderDesignMd(spec);
|
|
expect(out).toContain('## Elevation & Depth');
|
|
expect(out.indexOf('## Overview')).toBeLessThan(out.indexOf('## Elevation & Depth'));
|
|
});
|
|
|
|
test('upsertSection splices the body only: front matter bytes are identical before and after', () => {
|
|
const doc = parseDesignMd(SPEC);
|
|
const next = upsertSection(upsertSection(doc, 'Colors', 'Ink, clay, and one more.'), 'Extracted Design Language', 'from a mockup');
|
|
const out = renderDesignMd(next);
|
|
const fmBefore = SPEC.slice(0, SPEC.indexOf('\n---\n', 4) + 5);
|
|
expect(out.startsWith(fmBefore)).toBe(true);
|
|
expect(out).toContain('## Colors\n\nInk, clay, and one more.');
|
|
const headings = [...out.matchAll(/^## (.+)$/gm)].map(m => m[1]);
|
|
expect(headings).toEqual(['Overview', 'Colors', 'Typography', 'Motion', 'Decisions Log', 'Extracted Design Language']);
|
|
});
|
|
|
|
test('a legacy or unknown file renders in its own section order; only spec-shaped files sort canonically', () => {
|
|
const legacy = parseDesignMd(LEGACY);
|
|
const out = renderDesignMd(legacy);
|
|
const headings = (s: string) => [...s.matchAll(/^## (.+)$/gm)].map(x => x[1]);
|
|
expect(headings(out)).toEqual(headings(LEGACY));
|
|
});
|
|
|
|
test('spliceSection replaces or appends one section and leaves every other byte alone', () => {
|
|
const once = spliceSection(SPEC, 'Extracted Design Language', 'from a mockup');
|
|
expect(once.startsWith(SPEC.replace(/\s*$/, ''))).toBe(true);
|
|
expect(once.endsWith('## Extracted Design Language\n\nfrom a mockup\n')).toBe(true);
|
|
const twice = spliceSection(once, 'Extracted Design Language', 'second pass');
|
|
expect(twice.split('## Extracted Design Language').length - 1).toBe(1);
|
|
expect(twice).toContain('second pass');
|
|
expect(twice).not.toContain('from a mockup');
|
|
expect(twice.slice(0, twice.indexOf('## Extracted'))).toBe(once.slice(0, once.indexOf('## Extracted')));
|
|
// replacing a middle section keeps what follows
|
|
const mid = spliceSection(SPEC, 'Colors', 'Ink only.');
|
|
expect(mid).toContain('## Colors\n\nInk only.\n\n## Typography');
|
|
expect(mid).toContain('## Decisions Log');
|
|
});
|
|
|
|
test('insertMarker adds or replaces the marker only: line 2 YAML comment for front matter, line 1 HTML comment otherwise', () => {
|
|
const noMarker = SPEC.replace('# gstack: design-md-format=spec\n', '');
|
|
expect(insertMarker(noMarker, 'spec')).toBe(SPEC);
|
|
expect(insertMarker(SPEC, 'spec')).toBe(SPEC);
|
|
const kept = insertMarker(LEGACY, 'legacy-keep');
|
|
expect(kept).toBe('<!-- gstack: design-md-format=legacy-keep -->\n' + LEGACY);
|
|
expect(insertMarker(kept, 'legacy-keep')).toBe(kept);
|
|
});
|
|
|
|
test('setMarker on a spec file writes the YAML comment on line 2 and nothing else moves', () => {
|
|
const noMarker = SPEC.replace('# gstack: design-md-format=spec\n', '');
|
|
const out = renderDesignMd(setMarker(parseDesignMd(noMarker), 'spec'));
|
|
expect(out.split('\n').slice(0, 3)).toEqual(['---', '# gstack: design-md-format=spec', 'name: Heritage']);
|
|
});
|
|
});
|
|
|
|
describe('tokens', () => {
|
|
test('flattens the five groups and resolves {path} references to primitives', () => {
|
|
const { tokens, errors } = tokensFlat(parseDesignMd(SPEC).frontmatter);
|
|
expect(errors).toEqual([]);
|
|
expect(tokens['colors.primary']).toBe('#1A1C1E');
|
|
expect(tokens['colors.cta']).toBe('#B8422E');
|
|
expect(tokens['components.button-primary.backgroundColor']).toBe('#B8422E');
|
|
expect(tokens['components.button-primary.textColor']).toBe('#1A1C1E');
|
|
expect(tokens['typography.display.fontSize']).toBe('3rem');
|
|
expect(Object.keys(tokens).every(k => TOKEN_GROUPS.some(g => k.startsWith(g + '.')))).toBe(true);
|
|
expect('name' in tokens).toBe(false);
|
|
});
|
|
|
|
test('group refs, self refs, and dangling refs are DESIGN_MD_TOKEN_REF_INVALID', () => {
|
|
const fm = { colors: { a: '#111', group: '{colors}', self: '{colors.self}', gone: '{colors.nope}' }, components: { btn: { bg: '{colors}' } } };
|
|
const { tokens, errors } = tokensFlat(fm);
|
|
expect(tokens['colors.a']).toBe('#111');
|
|
expect(errors.filter(e => e.startsWith('DESIGN_MD_TOKEN_REF_INVALID: ')).length).toBe(4);
|
|
expect(errors.join('\n')).toContain('{colors} (refers to a group');
|
|
expect(errors.join('\n')).toContain('{colors.self} (self-reference)');
|
|
expect(errors.join('\n')).toContain('{colors.nope} (no such token)');
|
|
});
|
|
|
|
test('emitYamlBlock writes block style that Bun.YAML parses back identically', () => {
|
|
const obj = { name: 'X: y', colors: { primary: '#fff', 'on-primary': '#000', weird: 'yes' }, spacing: { '2xs': '2px', md: 16 }, list: ['a', 'b'] };
|
|
const yaml = emitYamlBlock(obj);
|
|
expect(yaml).not.toContain('{');
|
|
expect(yaml).toContain('colors:\n primary: "#fff"');
|
|
expect((Bun as any).YAML.parse(yaml)).toEqual(obj);
|
|
});
|
|
});
|
|
|
|
describe('convertLegacy on the legacy fixture (gstack\'s pre-conversion DESIGN.md)', () => {
|
|
const converted = convertLegacy(parseDesignMd(LEGACY));
|
|
const out = renderDesignMd(converted, { emitFrontmatter: true });
|
|
|
|
test('produces a spec file with the marker on line 2 and only the five token groups plus name', () => {
|
|
const doc = parseDesignMd(out);
|
|
expect(detectFormat(doc)).toEqual({ format: 'spec', code: 'spec' });
|
|
expect(out.split('\n')[1]).toBe('# gstack: design-md-format=spec');
|
|
for (const k of Object.keys(doc.frontmatter!)) expect(['name', ...TOKEN_GROUPS]).toContain(k);
|
|
expect(doc.frontmatter!.name).toBe('gstack');
|
|
});
|
|
|
|
test('maps roles, colors, spacing, and radii into tokens', () => {
|
|
const { tokens, errors } = tokensFlat(parseDesignMd(out).frontmatter);
|
|
expect(errors).toEqual([]);
|
|
expect(tokens['typography.display.fontFamily']).toBe('Satoshi');
|
|
expect(tokens['typography.body.fontFamily']).toBe('DM Sans');
|
|
expect(tokens['typography.label.fontFamily']).toBe('DM Sans');
|
|
expect(tokens['typography.mono.fontFamily']).toBe('JetBrains Mono');
|
|
expect(tokens['typography.mono.fontFeature']).toBe('tnum');
|
|
expect(tokens['colors.primary-dark-mode']).toBe('#F59E0B');
|
|
expect(tokens['colors.primary-light-mode']).toBe('#D97706');
|
|
expect(tokens['colors.success']).toBe('#22C55E');
|
|
expect(tokens['colors.semantic']).toBeUndefined();
|
|
expect(tokens['spacing.md']).toBe('16px');
|
|
expect(tokens['spacing.2xs']).toBe('2px');
|
|
expect(tokens['rounded.lg']).toBe('12px');
|
|
expect(tokens['rounded.full']).toBe('9999px');
|
|
});
|
|
|
|
test('intro prose under the title survives conversion', () => {
|
|
const withIntro = LEGACY.replace('# Design System — gstack\n', '# Design System — gstack\n\nAn intro paragraph that must not vanish.\n');
|
|
const out2 = renderDesignMd(convertLegacy(parseDesignMd(withIntro)), { emitFrontmatter: true });
|
|
expect(out2).toContain('An intro paragraph that must not vanish.');
|
|
expect(out2).toContain('# Design System — gstack');
|
|
});
|
|
|
|
test('folds Product Context and Aesthetic Direction into Overview; Motion, Grain Texture, Decisions Log survive as extras in order', () => {
|
|
const headings = [...out.matchAll(/^## (.+)$/gm)].map(m => m[1]);
|
|
expect(headings).toEqual(['Overview', 'Colors', 'Typography', 'Layout', 'Motion', 'Grain Texture', 'Decisions Log']);
|
|
expect(out).toContain('**What this is:**');
|
|
expect(out).toContain('**Direction:** Industrial/Utilitarian');
|
|
expect(out).toContain('| 2026-03-21 | Grain texture |');
|
|
expect(out).toContain('### Spacing');
|
|
});
|
|
|
|
test('re-rendering the converted file is stable (idempotent write)', () => {
|
|
expect(renderDesignMd(parseDesignMd(out))).toBe(out);
|
|
});
|
|
});
|
|
|
|
describe('coverage: parser and token edges', () => {
|
|
test('CRLF input parses to the same document; front matter closing at EOF without a newline parses; an unclosed fence is body', () => {
|
|
const lf = parseDesignMd(SPEC);
|
|
const crlf = parseDesignMd(SPEC.replace(/\n/g, '\r\n'));
|
|
expect(crlf.frontmatter).toEqual(lf.frontmatter);
|
|
expect(crlf.sections.map(s => s.heading)).toEqual(lf.sections.map(s => s.heading));
|
|
const eof = parseDesignMd('---\nname: x\ncolors:\n a: "#fff"\n---');
|
|
expect(eof.frontmatter?.name).toBe('x');
|
|
expect(eof.sections).toEqual([]);
|
|
const unclosed = parseDesignMd('---\nname: x\n\n## Overview\n\nbody\n');
|
|
expect(unclosed.frontmatterText).toBeNull();
|
|
expect(unclosed.sections.map(s => s.heading)).toEqual(['Overview']);
|
|
});
|
|
|
|
test('detectFormat: front matter without a token group is unknown with its reason; name-only is spec; one legacy heading is unknown', () => {
|
|
expect(detectFormat(parseDesignMd('---\nfoo: 1\n---\n\n## Overview\n\nx\n'))).toEqual({ format: 'unknown', code: 'no-token-groups', reason: 'front matter carries none of the five token groups' });
|
|
expect(detectFormat(parseDesignMd('---\nname: X\n---\n\n## Overview\n\nx\n')).format).toBe('spec');
|
|
expect(detectFormat(parseDesignMd('# T\n\n## Product Context\n\nx\n')).format).toBe('unknown');
|
|
});
|
|
|
|
test('tokensFlat: reference cycles error, arrays are skipped, numbers stringify, deep chains resolve up to the hop limit', () => {
|
|
const cyc = tokensFlat({ colors: { a: '{colors.b}', b: '{colors.a}' } });
|
|
expect(cyc.errors.join('\n')).toContain('(reference cycle)');
|
|
const arr = tokensFlat({ colors: { list: ['#111', '#222'], a: '#333' }, spacing: { md: 16 } });
|
|
expect(arr.tokens['colors.list']).toBeUndefined();
|
|
expect(arr.tokens['colors.a']).toBe('#333');
|
|
expect(arr.tokens['spacing.md']).toBe('16');
|
|
const chain: Record<string, string> = { base: '#000' };
|
|
for (let i = 1; i <= 7; i++) chain[`c${i}`] = `{colors.${i === 1 ? 'base' : `c${i - 1}`}}`;
|
|
expect(tokensFlat({ colors: chain }).tokens['colors.c7']).toBe('#000');
|
|
});
|
|
|
|
test('convertLegacy: no title → name "Design System"; opts.name wins; a doc without Color/Spacing/Layout gets Overview only plus extras; rem units survive; "## Colors" alias is consumed', () => {
|
|
const bare = parseDesignMd('## Product Context\n\n- **What this is:** x\n\n## Aesthetic Direction\n\n- **Direction:** y\n\n## Motion\n\n- **Approach:** z\n');
|
|
const conv = convertLegacy(bare);
|
|
expect(conv.frontmatter?.name).toBe('Design System');
|
|
expect(convertLegacy(bare, { name: 'Custom' }).frontmatter?.name).toBe('Custom');
|
|
expect(conv.sections.map(s => s.canonical ?? s.heading)).toEqual(['Overview', 'Motion']);
|
|
expect(conv.sections[0].body).toContain('**What this is:** x');
|
|
const rem = parseDesignMd('# T\n\n## Product Context\n\n- **What this is:** x\n\n## Colors\n\n- **Primary:** #111111\n\n## Spacing\n\n- **Scale:** sm(0.5rem) md(1rem) lg(2)\n');
|
|
const t = tokensFlat(convertLegacy(rem).frontmatter);
|
|
expect(t.tokens['spacing.sm']).toBe('0.5rem');
|
|
expect(t.tokens['spacing.lg']).toBe('2px');
|
|
expect(t.tokens['colors.primary']).toBe('#111111');
|
|
expect(convertLegacy(rem).sections.map(s => s.canonical ?? s.heading)).toEqual(['Overview', 'Colors', 'Layout']);
|
|
const empty = parseDesignMd('## Nothing\n\nx\n');
|
|
expect(convertLegacy(empty).sections[0].body).toBe('(no product context recorded)');
|
|
});
|
|
|
|
test('renderDesignMd with emitFrontmatter and unparsable front matter falls back to the preserved bytes', () => {
|
|
const doc = parseDesignMd('---\ncolors: [unclosed\n---\n\n## Overview\n\nx\n');
|
|
expect(doc.frontmatter).toBeNull();
|
|
const out = renderDesignMd(doc, { emitFrontmatter: true });
|
|
expect(out).toContain('colors: [unclosed');
|
|
});
|
|
|
|
test('YAML scalars: null → "", numeric-looking and empty strings quoted, hex quoted, dashed keys unquoted; all parse back', () => {
|
|
const obj = { a: null as unknown as string, b: '16', c: '', d: '#fff', 'on-primary': 'x', e: 'yes', f: 'plain text', g: 3 };
|
|
const yaml = emitYamlBlock(obj as Record<string, unknown>);
|
|
expect(yaml).toContain('a: ""');
|
|
expect(yaml).toContain('b: "16"');
|
|
expect(yaml).toContain('c: ""');
|
|
expect(yaml).toContain('d: "#fff"');
|
|
expect(yaml).toContain('on-primary: x');
|
|
expect(yaml).toContain('e: "yes"');
|
|
expect(yaml).toContain('f: plain text');
|
|
expect(yaml).toContain('g: 3');
|
|
const back = (Bun as any).YAML.parse(yaml);
|
|
expect(back.b).toBe('16');
|
|
expect(back.d).toBe('#fff');
|
|
expect(back.e).toBe('yes');
|
|
expect(back.g).toBe(3);
|
|
});
|
|
});
|
|
|
|
describe('coverage: bin verbs and the memory writer edges', () => {
|
|
const run = runBin;
|
|
|
|
test('mark spec on an unmarked spec file; mark on a missing file; tokens on a missing file and with invalid refs; explicit path; no verb', () => {
|
|
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-design-md-'));
|
|
try {
|
|
fs.writeFileSync(path.join(dir, 'DESIGN.md'), SPEC.replace('# gstack: design-md-format=spec\n', ''));
|
|
expect(run(['check'], dir).out).toContain('DESIGN_MD_MARKER: none');
|
|
expect(run(['mark', 'spec'], dir).code).toBe(0);
|
|
expect(fs.readFileSync(path.join(dir, 'DESIGN.md'), 'utf-8').split('\n')[1]).toBe('# gstack: design-md-format=spec');
|
|
const missing = run(['mark', 'legacy-keep', 'nope.md'], dir);
|
|
expect(missing.code).toBe(1);
|
|
expect(missing.out).toContain('DESIGN_MD_FORMAT: missing');
|
|
const t0 = JSON.parse(run(['tokens', 'nope.md'], dir).out);
|
|
expect(t0.format).toBe('missing');
|
|
expect(t0.tokens).toEqual({});
|
|
fs.writeFileSync(path.join(dir, 'other.md'), '---\nname: x\ncolors:\n a: "{colors}"\n b: "#000"\n---\n\n## Overview\n\nx\n');
|
|
const t1 = run(['tokens', 'other.md'], dir);
|
|
expect(t1.code).toBe(0);
|
|
expect(t1.err).toContain('DESIGN_MD_TOKEN_REF_INVALID: {colors}');
|
|
expect(JSON.parse(t1.out).tokens['colors.b']).toBe('#000');
|
|
expect(run(['check', 'other.md'], dir).out).toContain('DESIGN_MD_FORMAT: spec');
|
|
const usage = run([], dir);
|
|
expect(usage.code).toBe(2);
|
|
expect(usage.err).toContain('usage:');
|
|
} finally { fs.rmSync(dir, { recursive: true, force: true }); }
|
|
});
|
|
|
|
test('updateDesignMd: non-hex colors and duplicate roles are dropped on a new file; a headingless file gains the section; unparsable front matter is preserved byte-for-byte', () => {
|
|
const extracted = {
|
|
colors: [{ name: 'Primary', hex: 'rgb(1,2,3)', usage: 'x' }, { name: 'Surface', hex: '#141414', usage: 'y' }],
|
|
typography: [{ role: 'heading', family: 'Satoshi', size: '48px', weight: '900' }, { role: 'heading', family: 'Inter', size: '1px', weight: '100' }],
|
|
spacing: [], layout: [], mood: 'm',
|
|
};
|
|
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-design-md-'));
|
|
try {
|
|
updateDesignMd(dir, extracted, '/tmp/m.png');
|
|
const fresh = parseDesignMd(fs.readFileSync(path.join(dir, 'DESIGN.md'), 'utf-8'));
|
|
const tokens = tokensFlat(fresh.frontmatter).tokens;
|
|
expect(tokens['colors.primary']).toBeUndefined();
|
|
expect(tokens['colors.surface']).toBe('#141414');
|
|
expect(tokens['typography.heading.fontFamily']).toBe('Satoshi');
|
|
|
|
fs.writeFileSync(path.join(dir, 'DESIGN.md'), '# Just a title\n\nSome prose without sections.\n');
|
|
updateDesignMd(dir, extracted, '/tmp/m.png');
|
|
const headless = fs.readFileSync(path.join(dir, 'DESIGN.md'), 'utf-8');
|
|
expect(headless.startsWith('# Just a title')).toBe(true);
|
|
expect(headless).toContain('## Extracted Design Language');
|
|
|
|
const broken = '---\ncolors: [unclosed\n---\n\n## Overview\n\nx\n';
|
|
fs.writeFileSync(path.join(dir, 'DESIGN.md'), broken);
|
|
updateDesignMd(dir, extracted, '/tmp/m.png');
|
|
const after = fs.readFileSync(path.join(dir, 'DESIGN.md'), 'utf-8');
|
|
expect(after.startsWith('---\ncolors: [unclosed\n---\n')).toBe(true);
|
|
expect(after).toContain('## Extracted Design Language');
|
|
} finally { fs.rmSync(dir, { recursive: true, force: true }); }
|
|
});
|
|
});
|
|
|
|
describe('bin/gstack-design-md.ts', () => {
|
|
const run = runBin;
|
|
|
|
test('check reports format + marker for spec, legacy, unknown, missing', () => {
|
|
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-design-md-'));
|
|
try {
|
|
expect(run(['check'], dir).out).toContain('DESIGN_MD_FORMAT: missing');
|
|
fs.writeFileSync(path.join(dir, 'DESIGN.md'), SPEC);
|
|
expect(run(['check'], dir).out).toBe('DESIGN_MD_FORMAT: spec\nDESIGN_MD_MARKER: spec\n');
|
|
fs.writeFileSync(path.join(dir, 'DESIGN.md'), LEGACY);
|
|
expect(run(['check'], dir).out).toBe('DESIGN_MD_FORMAT: legacy\nDESIGN_MD_MARKER: none\n');
|
|
fs.writeFileSync(path.join(dir, 'DESIGN.md'), '---\n: bad: [\n---\n');
|
|
const bad = run(['check'], dir);
|
|
expect(bad.out).toContain('DESIGN_MD_FORMAT: unknown');
|
|
expect(bad.out).toContain('DESIGN_MD_REASON: front matter does not parse');
|
|
expect(bad.code).toBe(0);
|
|
} finally { fs.rmSync(dir, { recursive: true, force: true }); }
|
|
});
|
|
|
|
test('convert --write backs up, writes atomically, refuses ambiguous and non-legacy input', () => {
|
|
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-design-md-'));
|
|
try {
|
|
fs.writeFileSync(path.join(dir, 'DESIGN.md'), LEGACY);
|
|
const dry = run(['convert'], dir);
|
|
expect(dry.code).toBe(0);
|
|
expect(dry.out.split('\n')[1]).toBe('# gstack: design-md-format=spec');
|
|
expect(fs.readFileSync(path.join(dir, 'DESIGN.md'), 'utf-8')).toBe(LEGACY);
|
|
const wr = run(['convert', '--write'], dir);
|
|
expect(wr.code).toBe(0);
|
|
expect(wr.out).toContain('DESIGN_MD_WRITTEN:');
|
|
expect(fs.readFileSync(path.join(dir, 'DESIGN.md.legacy.bak'), 'utf-8')).toBe(LEGACY);
|
|
expect(run(['check'], dir).out).toContain('DESIGN_MD_FORMAT: spec');
|
|
expect(fs.readdirSync(dir).some(f => f.includes('.tmp-'))).toBe(false);
|
|
// already spec → refused as non-legacy (exit 1), not clobbered
|
|
const again = run(['convert', '--write'], dir);
|
|
expect(again.code).toBe(1);
|
|
fs.writeFileSync(path.join(dir, 'DESIGN.md'), '---\nname: x\ncolors:\n a: "#fff"\n---\n\n## Product Context\n\nx\n\n## Aesthetic Direction\n\ny\n');
|
|
const amb = run(['convert', '--write'], dir);
|
|
expect(amb.code).toBe(2);
|
|
expect(amb.err).toContain('DESIGN_MD_CONVERT_REFUSED: ambiguous');
|
|
} finally { fs.rmSync(dir, { recursive: true, force: true }); }
|
|
});
|
|
|
|
test('tokens prints the flat map; mark persists the choice', () => {
|
|
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-design-md-'));
|
|
try {
|
|
fs.writeFileSync(path.join(dir, 'DESIGN.md'), SPEC);
|
|
const t = JSON.parse(run(['tokens'], dir).out);
|
|
expect(t.tokens['colors.cta']).toBe('#B8422E');
|
|
expect(t.errors).toEqual([]);
|
|
fs.writeFileSync(path.join(dir, 'DESIGN.md'), LEGACY);
|
|
const m = run(['mark', 'legacy-keep'], dir);
|
|
expect(m.code).toBe(0);
|
|
const text = fs.readFileSync(path.join(dir, 'DESIGN.md'), 'utf-8');
|
|
expect(text).toBe('<!-- gstack: design-md-format=legacy-keep -->\n' + LEGACY); // byte-identical apart from line 1
|
|
expect(run(['check'], dir).out).toBe('DESIGN_MD_FORMAT: legacy\nDESIGN_MD_MARKER: legacy-keep\n');
|
|
expect(run(['mark', 'maybe'], dir).code).toBe(2);
|
|
// a choice that contradicts the file is refused and the file is unchanged
|
|
const bad = run(['mark', 'spec'], dir);
|
|
expect(bad.code).toBe(2);
|
|
expect(bad.err).toContain('DESIGN_MD_CONVERT_REFUSED: mark spec contradicts');
|
|
expect(fs.readFileSync(path.join(dir, 'DESIGN.md'), 'utf-8')).toBe(text);
|
|
fs.writeFileSync(path.join(dir, 'DESIGN.md'), SPEC);
|
|
expect(run(['mark', 'legacy-keep'], dir).code).toBe(2);
|
|
expect(fs.readFileSync(path.join(dir, 'DESIGN.md'), 'utf-8')).toBe(SPEC);
|
|
} finally { fs.rmSync(dir, { recursive: true, force: true }); }
|
|
});
|
|
});
|
|
|
|
describe('design binary: updateDesignMd is frontmatter-safe', () => {
|
|
const extracted = {
|
|
colors: [{ name: 'Primary', hex: '#F59E0B', usage: 'buttons' }, { name: 'Surface', hex: '#141414', usage: 'cards' }],
|
|
typography: [{ role: 'heading', family: 'Satoshi', size: '48px', weight: '900' }],
|
|
spacing: ['8px base unit'],
|
|
layout: ['max-width 1200px'],
|
|
mood: 'Serious tool built with care.',
|
|
};
|
|
|
|
test('spec input: section appended after the canonical ones, front matter bytes untouched, replaces on rerun', () => {
|
|
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-design-md-'));
|
|
try {
|
|
fs.writeFileSync(path.join(dir, 'DESIGN.md'), SPEC);
|
|
updateDesignMd(dir, extracted, '/tmp/mock.png');
|
|
const once = fs.readFileSync(path.join(dir, 'DESIGN.md'), 'utf-8');
|
|
expect(once.startsWith(SPEC.slice(0, SPEC.indexOf('\n---\n', 4) + 5))).toBe(true);
|
|
expect([...once.matchAll(/^## (.+)$/gm)].map(m => m[1]).at(-1)).toBe('Extracted Design Language');
|
|
expect(once.split('## Extracted Design Language').length - 1).toBe(1);
|
|
updateDesignMd(dir, { ...extracted, mood: 'second pass' }, '/tmp/mock2.png');
|
|
const twice = fs.readFileSync(path.join(dir, 'DESIGN.md'), 'utf-8');
|
|
expect(twice.split('## Extracted Design Language').length - 1).toBe(1);
|
|
expect(twice).toContain('second pass');
|
|
expect(twice).not.toContain('Serious tool built with care.');
|
|
} finally { fs.rmSync(dir, { recursive: true, force: true }); }
|
|
});
|
|
|
|
test('legacy input: sections preserved, extracted section added at the end', () => {
|
|
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-design-md-'));
|
|
try {
|
|
fs.writeFileSync(path.join(dir, 'DESIGN.md'), LEGACY);
|
|
updateDesignMd(dir, extracted, '/tmp/mock.png');
|
|
const out = fs.readFileSync(path.join(dir, 'DESIGN.md'), 'utf-8');
|
|
expect(out.startsWith(LEGACY.replace(/\s*$/, ''))).toBe(true); // every original byte kept, in order
|
|
expect([...out.matchAll(/^## (.+)$/gm)].map(m => m[1]).at(-1)).toBe('Extracted Design Language');
|
|
expect(detectFormat(parseDesignMd(out)).format).toBe('legacy');
|
|
} finally { fs.rmSync(dir, { recursive: true, force: true }); }
|
|
});
|
|
|
|
test('absent input: a spec skeleton with tokens from the extraction; readDesignConstraints leads with tokens', () => {
|
|
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-design-md-'));
|
|
try {
|
|
updateDesignMd(dir, extracted, '/tmp/mock.png');
|
|
const out = fs.readFileSync(path.join(dir, 'DESIGN.md'), 'utf-8');
|
|
const doc = parseDesignMd(out);
|
|
expect(detectFormat(doc).format).toBe('spec');
|
|
expect(out.split('\n').slice(0, 2)).toEqual(['---', '# gstack: design-md-format=spec']);
|
|
const { tokens } = tokensFlat(doc.frontmatter);
|
|
expect(tokens['colors.primary']).toBe('#F59E0B');
|
|
expect(tokens['typography.heading.fontFamily']).toBe('Satoshi');
|
|
expect([...out.matchAll(/^## (.+)$/gm)].map(m => m[1])).toEqual(['Overview', 'Extracted Design Language']);
|
|
const constraints = readDesignConstraints(dir)!;
|
|
expect(constraints.startsWith('Tokens: colors.primary: #F59E0B')).toBe(true);
|
|
expect(constraints).toContain('Serious tool built with care.');
|
|
} finally { fs.rmSync(dir, { recursive: true, force: true }); }
|
|
});
|
|
});
|