Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(cli): anchor and fail closed in template fixture rewriting (#6596)

Joeybbadc4dd2923
diff --git a/.changeset/cli-spec-template-fixture-rewrite.md b/.changeset/cli-spec-template-fixture-rewrite.md
new file mode 100644
index 0000000000..aed9a9b06f
--- /dev/null
+++ b/.changeset/cli-spec-template-fixture-rewrite.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] `astryx template <name> <path>` and `astryx layout expand` now replace demo media only when a path starts with `/template-assets/`, so third-party URLs and product paths that merely contain that text are left alone. Demo media in a subdirectory, with a query string, or with characters such as `@` in the file name is now replaced whole instead of being corrupted or left behind. A demo media reference that cannot be replaced safely, such as one with no file suffix or one built at runtime, now fails the copy with its path.
+
+@josephfarina
diff --git a/packages/cli/foundation/discovery/template-adapter.fixture-refs.test.mjs b/packages/cli/foundation/discovery/template-adapter.fixture-refs.test.mjs
new file mode 100644
index 0000000000..9665228072
--- /dev/null
+++ b/packages/cli/foundation/discovery/template-adapter.fixture-refs.test.mjs
@@ -0,0 +1,248 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import jscodeshift from 'jscodeshift';
+import {stripTemplateAssetRefs} from './template-adapter.mjs';
+
+const PLACEHOLDER = stripTemplateAssetRefs("'/template-assets/x.png'").slice(
+ 1,
+ -1,
+);
+
+describe('stripTemplateAssetRefs fixture references', () => {
+ it('replaces an image with a self-contained placeholder', () => {
+ expect(PLACEHOLDER).toMatch(/^data:image\/svg\+xml,[^\s'"`()]+$/u);
+ });
+
+ it.each([
+ 'https://cdn.example.com/template-assets/logo.png',
+ '//cdn.example.com/template-assets/logo.png',
+ '/my-app/template-assets/hero.jpg',
+ './template-assets/hero.jpg',
+ 'template-assets/hero.jpg',
+ '/template-assets-archive/hero.jpg',
+ '@/template-assets/hero.jpg',
+ ])('leaves %s untouched', value => {
+ const source = `const src = '${value}';`;
+ expect(stripTemplateAssetRefs(source)).toBe(source);
+ });
+
+ it.each([
+ 'import StarIcon from "./icons/star.svg";',
+ '<Icon icon="/icons/star.svg" />',
+ '<Button icon={StarIcon} />',
+ "const icons = {star: 'heroicons:star'};",
+ ])('leaves an icon outside the fixture namespace untouched: %s', source => {
+ expect(stripTemplateAssetRefs(source)).toBe(source);
+ });
+
+ it.each([
+ ['a subdirectory', '/template-assets/avatars/ada.png'],
+ ['an @ in its name', '/template-assets/[email protected]'],
+ ['a plus in its name', '/template-assets/cover+1.jpg'],
+ ['an encoded space in its name', '/template-assets/hero%20wide.png'],
+ ])('replaces a fixture with %s', (_, value) => {
+ expect(stripTemplateAssetRefs(`<img src="${value}" />`)).toBe(
+ `<img src="${PLACEHOLDER}" />`,
+ );
+ });
+
+ it('replaces the whole reference, query and fragment included', () => {
+ expect(
+ stripTemplateAssetRefs("const hero = '/template-assets/hero.jpg?w=200';"),
+ ).toBe(`const hero = '${PLACEHOLDER}';`);
+ expect(
+ stripTemplateAssetRefs("const clip = '/template-assets/clip.mp4#t=5';"),
+ ).toBe("const clip = '';");
+ expect(
+ stripTemplateAssetRefs(
+ "const hero = '/template-assets/a.png?f=/template-assets/b.png';",
+ ),
+ ).toBe(`const hero = '${PLACEHOLDER}';`);
+ });
+
+ it('classifies by the complete final suffix, ignoring case', () => {
+ expect(
+ stripTemplateAssetRefs("src: '/template-assets/Clip.Min.MP4',"),
+ ).toBe("src: '',");
+ });
+
+ it.each([
+ [
+ 'a CSS url()',
+ "backgroundImage: 'url(/template-assets/hero.png)'",
+ `backgroundImage: 'url(${PLACEHOLDER})'`,
+ ],
+ [
+ 'a srcset list',
+ 'srcSet="/template-assets/a.png 1x, /template-assets/[email protected] 2x"',
+ `srcSet="${PLACEHOLDER} 1x, ${PLACEHOLDER} 2x"`,
+ ],
+ [
+ 'an HTML string with escaped quotes',
+ 'const html = "<img src=\\"/template-assets/a.png\\">";',
+ `const html = "<img src=\\"${PLACEHOLDER}\\">";`,
+ ],
+ [
+ 'JSX text',
+ '<code>/template-assets/hero.png</code>',
+ `<code>${PLACEHOLDER}</code>`,
+ ],
+ [
+ 'a sentence that quotes it',
+ 'const tip = "Replace \'/template-assets/hero.png\'.";',
+ `const tip = "Replace '${PLACEHOLDER}'.";`,
+ ],
+ [
+ 'a url() inside a longer string',
+ "const bg = 'url(/template-assets/a.png) + x';",
+ `const bg = 'url(${PLACEHOLDER}) + x';`,
+ ],
+ [
+ 'a comment',
+ '// hero: /template-assets/hero.png\n',
+ `// hero: ${PLACEHOLDER}\n`,
+ ],
+ [
+ 'a sentence, keeping its punctuation',
+ '// Uses /template-assets/a.png, then /template-assets/b.png.\n',
+ `// Uses ${PLACEHOLDER}, then ${PLACEHOLDER}.\n`,
+ ],
+ ])('replaces a fixture inside %s', (_, source, expected) => {
+ expect(stripTemplateAssetRefs(source)).toBe(expected);
+ });
+
+ it.each([
+ '<Text>Put your images in /template-assets/ first.</Text>',
+ "const note = 'Media: /template-assets/hero';",
+ '// Demo images live under /template-assets and are replaced.\n',
+ "const html = '<img src=/template-assets-archive/a.png>';",
+ ])('leaves a mention in text that names no media file: %s', source => {
+ expect(stripTemplateAssetRefs(source)).toBe(source);
+ });
+
+ it.each([
+ "// Images come from `/template-assets/*` and '/template-assets/'.\nexport default function Page() {\n return null;\n}\n",
+ "/* Was '/template-assets/clip.bin'. */\nexport const x = 1;\n",
+ ])('leaves a comment it would otherwise reject: %s', source => {
+ expect(stripTemplateAssetRefs(source)).toBe(source);
+ });
+
+ it.each([
+ [
+ 'no file suffix',
+ "src: '/template-assets/hero',",
+ '/template-assets/hero',
+ ],
+ ['no file name', "src: '/template-assets/',", '/template-assets/'],
+ [
+ 'no path below it',
+ "export const base = '/template-assets'; // base\n",
+ '/template-assets',
+ ],
+ ])(
+ 'fails with the fixture path when a value has %s',
+ (_, source, reference) => {
+ expect(() => stripTemplateAssetRefs(source)).toThrow(
+ `Unrecognized template asset format (none) for ${reference}`,
+ );
+ },
+ );
+
+ it.each([
+ [
+ 'const src = `/template-assets/${name}.png`;',
+ '/template-assets/${name}.png',
+ ],
+ ['const src = `/template-assets${path}`;', '/template-assets${path}'],
+ ])(
+ 'fails when a fixture path is built by interpolation: %s',
+ (source, reference) => {
+ expect(() => stripTemplateAssetRefs(source)).toThrow(
+ `Template asset reference ${reference} cannot be replaced safely: it is built by a template-literal interpolation`,
+ );
+ },
+ );
+
+ it.each([
+ [
+ 'follows an interpolation',
+ 'const src = `${base}/template-assets/a.png`;',
+ ],
+ ['is cut short by a parenthesis', "src: '/template-assets/a(1).mp4',"],
+ ['ends a word in text', 'const s = "clip: /template-assets/a.png(1).mp4";'],
+ [
+ 'has mismatched escaped quotes',
+ 'const html = "<img src=\\"/template-assets/a.png\\\'>";',
+ ],
+ [
+ 'sits between a quote and a parenthesis',
+ "const s = '\"/template-assets/a.png)';",
+ ],
+ ])('fails when a fixture path %s', (_, source) => {
+ expect(() => stripTemplateAssetRefs(source)).toThrow(
+ /\/template-assets\/a.* cannot be replaced safely: it is not a whole/u,
+ );
+ });
+
+ it.each([
+ 'srcSet="/template-assets/a.png 1x,/template-assets/b.png 2x"',
+ "const html = '<img src=/template-assets/b.png>';",
+ "const s = 'hero\\n/template-assets/b.png';",
+ ])('fails when a fixture path is joined to other text: %s', source => {
+ expect(() => stripTemplateAssetRefs(source)).toThrow(
+ /\/template-assets\/b\.png cannot be replaced safely: it is joined/u,
+ );
+ });
+
+ it.each([
+ ['concatenated', "const src = base + '/template-assets/hero.png';"],
+ ['concatenated', "const src = '/template-assets/hero.png' + query;"],
+ ['concatenated', "src += '/template-assets/hero.png';"],
+ ['a method', "const src = '/template-assets/hero.png'.concat('?w=1');"],
+ ['imported', "import hero from '/template-assets/hero.png';"],
+ ['imported', "const hero = require('/template-assets/hero.png');"],
+ ])('fails when a fixture string is %s: %s', (use, source) => {
+ expect(() => stripTemplateAssetRefs(source)).toThrow(
+ new RegExp(`/template-assets/hero\\.png .*${use}`, 'u'),
+ );
+ });
+});
+
+describe('shipped templates', () => {
+ it('copy with every fixture replaced and still parse', () => {
+ const root = path.resolve(
+ path.dirname(fileURLToPath(import.meta.url)),
+ '../../assets/templates',
+ );
+ const parse = jscodeshift.withParser('tsx');
+ const files = fs
+ .readdirSync(root, {recursive: true, encoding: 'utf-8'})
+ .filter(file => file.endsWith('.tsx'))
+ .filter(file =>
+ fs
+ .readFileSync(path.join(root, file), 'utf-8')
+ .includes('/template-assets'),
+ );
+ expect(files.length).toBeGreaterThan(10);
+
+ const problems = [];
+ for (const file of files) {
+ try {
+ const output = stripTemplateAssetRefs(
+ fs.readFileSync(path.join(root, file), 'utf-8'),
+ );
+ if (output.includes('/template-assets')) {
+ problems.push(`${file}: fixture reference left behind`);
+ }
+ parse(output);
+ } catch (err) {
+ problems.push(`${file}: ${/** @type {Error} */ (err).message}`);
+ }
+ }
+ expect(problems).toEqual([]);
+ });
+});
diff --git a/packages/cli/foundation/discovery/template-adapter.mjs b/packages/cli/foundation/discovery/template-adapter.mjs
index 5b9652a98f..4bab70898b 100644
--- a/packages/cli/foundation/discovery/template-adapter.mjs
+++ b/packages/cli/foundation/discovery/template-adapter.mjs
@@ -23,6 +23,7 @@
import * as fs from 'node:fs';
import * as path from 'node:path';
+import {createRequire} from 'node:module';
import {createJiti} from 'jiti';
import {loadModuleWithParser} from '../fs/module-loader.mjs';
import {parseTemplate} from '../../authoring/doctypes/template/parse.mjs';
@@ -30,6 +31,8 @@ import {CLI_ROOT, discoverExternalPackages} from '../fs/paths.mjs';
import {CORE_PROVIDER_ID} from '../identity/providers.mjs';
import {Project} from '../config/project.mjs';
+const require = createRequire(import.meta.url);
+
/** Identity used for core (built-in) templates in package-scoped listings. */
const CORE_PACKAGE = CORE_PROVIDER_ID;
@@ -185,17 +188,53 @@ const IMAGE_EXTENSIONS = new Set([
]);
/**
- * Demo-asset sources to strip from scaffolded projects. Template demo imagery
+ * First path segment of every Astryx template fixture. Template demo imagery
* is self-hosted under the docsite's `/template-assets/*` dir (committed there,
- * mirrored into the sandbox preview by scripts/sync-templates.js). Those paths
- * only resolve inside the Astryx docsite/sandbox, so on scaffold they're
- * replaced — a scaffolded project has no `/template-assets/` dir and would
- * otherwise 404. Genuine third-party URLs (e.g. brand logos from
- * paypalobjects.com) are intentionally left untouched.
- *
- * @type {RegExp}
+ * mirrored into the sandbox preview by scripts/sync-templates.js), so those
+ * paths only resolve inside the Astryx docsite/sandbox and are replaced on
+ * scaffold. Only a root-relative URL whose first segment this is counts: the
+ * same text inside a third-party URL or a product path is left untouched.
*/
-const DEMO_ASSET_PATTERN = /\/template-assets\/[\w.-]+\.(\w+)/g;
+const FIXTURE_SEGMENT = 'template-assets';
+
+/** Characters that end a URL token in template source, besides whitespace. */
+const TOKEN_DELIMITERS = new Set([
+ "'",
+ '"',
+ '`',
+ '(',
+ ')',
+ '<',
+ '>',
+ '{',
+ '}',
+ '[',
+ ']',
+ '\\',
+ '|',
+ '^',
+]);
+
+/** The closing delimiter each opening delimiter must pair with. */
+const CLOSING_DELIMITERS = new Map([
+ ["'", "'"],
+ ['"', '"'],
+ ['`', '`'],
+ ['(', ')'],
+]);
+const CLOSERS = new Set(CLOSING_DELIMITERS.values());
+
+/** A URL with a scheme: absolute, so never a fixture reference. */
+const ABSOLUTE_URL = /^[a-z][a-z\d+.-]*:/iu;
+
+/** What may lead up to the fixture segment inside a relative product path. */
+const RELATIVE_PATH_PREFIX = /^[\w.~%@/-]+$/u;
+
+/** Punctuation that ends a sentence or list item after a path in text. */
+const PROSE_PUNCTUATION = new Set(['.', ',', ';', ':', '!', '?']);
+
+/** `from`, `import` or `require` right before a quoted module specifier. */
+const MODULE_SPECIFIER_LEAD = /(?:^|[^\w$])(?:from|import|require)\s*\(?$/u;
/**
* Normalize path into Unix path (using forward slashes) for consistent comparison
@@ -209,26 +248,246 @@ function toPosixPath(p) {
}
/**
- * Replace demo asset references with a placeholder so scaffolded pages
- * render with zero setup. Images get a self-contained data URI; videos
- * (which have no equivalent inline placeholder — see VIDEO_EXTENSIONS) are
- * stripped to an empty src instead of being mis-replaced with image data.
- * Builders drop in their own media either way.
+ * Replace each Astryx template fixture reference with a placeholder so
+ * scaffolded pages render with zero setup. Images get a self-contained data
+ * URI; videos (which have no equivalent inline placeholder — see
+ * VIDEO_EXTENSIONS) are stripped to an empty src instead of being
+ * mis-replaced with image data. Builders drop in their own media either way.
+ *
+ * A reference is a URL token that resolves to a root-relative path under
+ * FIXTURE_SEGMENT. It is replaced whole, query and fragment included, and
+ * classified by the suffix of its last path segment. A reference that cannot
+ * be replaced safely throws with its path rather than being guessed at or
+ * left behind. Prose is left as written: in text (JSX text, a word inside a
+ * longer string) trailing punctuation is not part of a path and a path with
+ * no suffix, such as the bare directory, is a mention; inside a comment
+ * nothing throws.
*
* @param {string} source - Template source code.
* @returns {string} Source with demo asset references replaced.
*/
export function stripTemplateAssetRefs(source) {
- return source.replace(DEMO_ASSET_PATTERN, (match, extension) => {
- const ext = extension.toLowerCase();
- if (VIDEO_EXTENSIONS.has(ext)) {
- return '';
+ const needle = `/${FIXTURE_SEGMENT}`;
+ let output = '';
+ let copied = 0;
+ /** @type {Array<[number, number]> | undefined} */
+ let comments;
+ let at = source.indexOf(needle);
+ while (at !== -1) {
+ let start = at;
+ while (start > 0 && !isTokenDelimiter(source[start - 1])) start--;
+ let end = at + needle.length;
+ while (end < source.length && !isTokenDelimiter(source[end])) end++;
+ /** @type {{text: string, end: number} | null} */
+ let edit;
+ try {
+ edit = fixtureEdit(source, start, at, end);
+ } catch (err) {
+ comments ??= commentRanges(source);
+ if (!comments.some(([from, to]) => from <= at && at < to)) throw err;
+ edit = null;
}
- if (IMAGE_EXTENSIONS.has(ext)) {
- return PLACEHOLDER_IMAGE;
+ if (edit) {
+ output += source.slice(copied, start) + edit.text;
+ copied = edit.end;
}
- throw new Error(`Unrecognized template asset format ${ext} for ${match}`);
- });
+ at = source.indexOf(needle, end);
+ }
+ return output + source.slice(copied);
+}
+
+/** @param {string | undefined} char */
+function isTokenDelimiter(char) {
+ return char === undefined || /\s/u.test(char) || TOKEN_DELIMITERS.has(char);
+}
+
+/**
+ * Whitespace, the source edge, or a tag bracket: what bounds a word of text.
+ * @param {string | undefined} char
+ */
+function isTextDelimiter(char) {
+ return char === undefined || /\s/u.test(char) || char === '<' || char === '>';
+}
+
+/**
+ * The path segments of a root-relative URL under FIXTURE_SEGMENT, or null.
+ * @param {string} reference
+ * @returns {string[] | null}
+ */
+function fixtureSegments(reference) {
+ if (!reference.startsWith('/') || reference.startsWith('//')) return null;
+ const segments = new URL(reference, 'http://template.invalid').pathname.split(
+ '/',
+ );
+ return segments[1] === FIXTURE_SEGMENT ? segments : null;
+}
+
+/**
+ * The replacement for the fixture reference in the URL token [start, end),
+ * which contains FIXTURE_SEGMENT's path at `at`; null when the token is not a
+ * fixture reference or is a prose mention.
+ * @param {string} source
+ * @param {number} start
+ * @param {number} at
+ * @param {number} end
+ * @returns {{text: string, end: number} | null}
+ */
+function fixtureEdit(source, start, at, end) {
+ const token = source.slice(start, end);
+ if (ABSOLUTE_URL.test(token)) return null;
+ if (!token.startsWith('/')) {
+ if (!fixtureSegments(source.slice(at, end))) return null;
+ if (
+ source[start - 1] !== '\\' &&
+ RELATIVE_PATH_PREFIX.test(source.slice(start, at))
+ ) {
+ return null;
+ }
+ throw unsafeFixtureReference(
+ source,
+ at,
+ 'it is joined to text the copy cannot parse',
+ );
+ }
+
+ const before = source[start - 1];
+ const after = source[end];
+ if (after === '{' && token.endsWith('$')) {
+ if (!fixtureSegments(token.slice(0, -1))) return null;
+ throw unsafeFixtureReference(
+ source,
+ at,
+ 'it is built by a template-literal interpolation',
+ );
+ }
+ const quoted =
+ before !== undefined && CLOSING_DELIMITERS.get(before) === after;
+ const escapedQuoted =
+ (before === "'" || before === '"') &&
+ source[start - 2] === '\\' &&
+ after === '\\' &&
+ source[end + 1] === before;
+ const whole = quoted || escapedQuoted;
+ let referenceEnd = end;
+ if (!whole) {
+ while (
+ referenceEnd > at &&
+ PROSE_PUNCTUATION.has(source[referenceEnd - 1])
+ ) {
+ referenceEnd--;
+ }
+ }
+ const segments = fixtureSegments(source.slice(start, referenceEnd));
+ if (!segments) return null;
+
+ const inText =
+ (isTextDelimiter(before) || CLOSING_DELIMITERS.has(before)) &&
+ (isTextDelimiter(after) || CLOSERS.has(after)) &&
+ (isTextDelimiter(before) || isTextDelimiter(after));
+ if (!whole && !inText) {
+ throw unsafeFixtureReference(
+ source,
+ at,
+ 'it is not a whole quoted, url(), or text value',
+ );
+ }
+ if (quoted && before !== '(') {
+ const use = expressionUse(source, start - 1, end);
+ if (use) throw unsafeFixtureReference(source, at, use);
+ }
+
+ const ext = path.posix
+ .extname(segments[segments.length - 1])
+ .slice(1)
+ .toLowerCase();
+ if (VIDEO_EXTENSIONS.has(ext)) return {text: '', end: referenceEnd};
+ if (IMAGE_EXTENSIONS.has(ext)) {
+ return {text: PLACEHOLDER_IMAGE, end: referenceEnd};
+ }
+ if (whole || ext) {
+ throw new Error(
+ `Unrecognized template asset format ${ext || '(none)'} for ${displayReference(source, at)}`,
+ );
+ }
+ return null;
+}
+
+/**
+ * Why the string quoted at `open` and `close` cannot be replaced on its own,
+ * or null when it is a plain value.
+ * @param {string} source
+ * @param {number} open
+ * @param {number} close
+ * @returns {string | null}
+ */
+function expressionUse(source, open, close) {
+ let prev = open - 1;
+ while (prev >= 0 && /\s/u.test(source[prev])) prev--;
+ let next = close + 1;
+ while (next < source.length && /\s/u.test(source[next])) next++;
+ if (
+ source[prev] === '+' ||
+ (source[prev] === '=' && source[prev - 1] === '+') ||
+ source[next] === '+'
+ ) {
+ return 'the string is concatenated with another value';
+ }
+ if (source[next] === '.' && /[A-Za-z_$]/u.test(source[next + 1] ?? '')) {
+ return 'a method is called on the string';
+ }
+ if (
+ MODULE_SPECIFIER_LEAD.test(source.slice(Math.max(0, prev - 16), prev + 1))
+ ) {
+ return 'it is imported as a module';
+ }
+ return null;
+}
+
+/**
+ * The [start, end) range of every comment in `source`, or none when it does
+ * not parse as TSX.
+ * @param {string} source
+ * @returns {Array<[number, number]>}
+ */
+function commentRanges(source) {
+ try {
+ const {parse} = require('@babel/parser');
+ const {comments} = parse(source, {
+ sourceType: 'module',
+ plugins: ['jsx', 'typescript'],
+ });
+ return (comments ?? []).map(
+ comment =>
+ /** @type {[number, number]} */ ([
+ comment.start ?? 0,
+ comment.end ?? 0,
+ ]),
+ );
+ } catch {
+ return [];
+ }
+}
+
+/**
+ * The fixture path at `at`, up to the next whitespace, quote, or tag bracket.
+ * @param {string} source
+ * @param {number} at
+ */
+function displayReference(source, at) {
+ let end = at;
+ while (end < source.length && !/[\s'"`<>]/u.test(source[end])) end++;
+ return source.slice(at, end);
+}
+
+/**
+ * @param {string} source
+ * @param {number} at
+ * @param {string} reason
+ */
+function unsafeFixtureReference(source, at, reason) {
+ return new Error(
+ `Template asset reference ${displayReference(source, at)} cannot be replaced safely: ${reason}. Use the complete path as one static string.`,
+ );
}
/**
* Load a template-spec module and return its metadata object. Supports both