import { FilterEntry, JsonValidationSet, Mode, ObjectEntry, SchemaDefinition, TagEntry, ThemeDocset, Translations, } from '@shopify/theme-check-common'; import fs from 'node:fs/promises'; import path from 'node:path'; import { Manifests, Resource, ThemeLiquidDocsSchemaRoot, download, exists, replaceThemeLiquidDocs, resourcePath, resourceUrl, root, schemaPath, } from './themeLiquidDocsDownloader'; import { Logger, identity, memo, memoize, noop, tap } from './utils'; type JSONSchemaManifest = { schemas: { uri: string; fileMatch?: string[] }[] }; export class ThemeLiquidDocsManager implements ThemeDocset, JsonValidationSet { constructor(private log: Logger = noop) {} filters = memo(async (): Promise => { return findSuitableResource(this.loaders('filters'), JSON.parse, [], this.log); }); objects = memo(async (): Promise => { return findSuitableResource(this.loaders('objects'), JSON.parse, [], this.log); }); liquidDrops = memo(async (): Promise => { return findSuitableResource(this.loaders('objects'), JSON.parse, [], this.log); }); tags = memo(async (): Promise => { return findSuitableResource(this.loaders('tags'), JSON.parse, [], this.log); }); systemTranslations = memo(async (): Promise => { return findSuitableResource( this.loaders('shopify_system_translations'), JSON.parse, {}, this.log, ); }); schemas = memoize( (mode: Mode) => findSuitableResource( this.loaders(Manifests[mode]), JSON.parse, { schemas: [], }, this.log, ).then((manifest) => { return Promise.all( manifest.schemas.map( async (schemaDefinition): Promise => ({ uri: `${ThemeLiquidDocsSchemaRoot}/${schemaDefinition.uri}`, fileMatch: schemaDefinition.fileMatch, schema: await findSuitableResource( this.schemaLoaders(schemaDefinition.uri), identity, '', this.log, ), }), ), ); }), identity, ); /** * The setup method checks that the latest revision matches the one from * Shopify/theme-liquid-docs. If there's a diff in revision, it means * that the documentations that you have locally are out of date. * * The setup method then replaces the local docs with the latest ones, which * include latest.json. Until that succeeds, latest.json keeps the old revision, * so a failed update is retried on the next run. */ setup = memo(async (): Promise => { try { if (!(await exists(root))) { await fs.mkdir(root, { recursive: true }); } const local = await this.latestRevision(); const remote = JSON.parse(await download(resourceUrl('latest'), this.log)).revision ?? ''; if (local !== remote) { await replaceThemeLiquidDocs(root, this.log); } } catch (error) { if (error instanceof Error) { this.log(`Failed to setup with the following error: ${error.message}`); } return; } }); private async latestRevision(): Promise { const latest = await findSuitableResource( [loader(() => this.load('latest'), 'loadLatestRevision')], JSON.parse, {}, this.log, ); return latest['revision'] ?? ''; } private async loadResource(name: Resource): Promise { // Always wait for setup first. Since it's memoized, this will always // be the same promise. await this.setup(); return this.load(name).then(tap(() => this.log(`Loaded resource from ${resourcePath(name)}`))); } private async load(name: Resource | 'latest') { return fs.readFile(resourcePath(name), 'utf8'); } private async loadSchema(relativeUri: string) { return fs .readFile(schemaPath(relativeUri), 'utf8') .then(tap(() => this.log(`Loaded schema from ${schemaPath(relativeUri)}`))); } private loaders(name: Resource): Loader[] { return [ loader(() => this.loadResource(name), `loadResource(${name})`), loader(() => fallbackResource(name, this.log), `fallbackResource(${name})`), ]; } private schemaLoaders(relativeUri: string): Loader[] { return [ loader(() => this.loadSchema(relativeUri), `loadSchema(${relativeUri})`), loader(() => fallbackSchema(relativeUri, this.log), `fallbackSchema(${relativeUri})`), ]; } } interface Loader { (): Promise; loaderName: string; } function loader(fn: () => Promise, loaderName: string): Loader { return Object.assign(fn, { loaderName }); } /** * Find the first resource that can be loaded and transformed. * * Will try to load the resource from the loaders in order. If the loader * throws an error, it will try the next loader. If all loaders throw an * error, it will return the default value. * * This should allow us to load the latest version of the resource if it's * available, and fall back to the local version if it's not. If neither * work, we'll just return the default value. */ async function findSuitableResource( dataLoaders: Loader[], transform: (x: A) => B, defaultValue: B, log: Logger, ): Promise { for (const loader of dataLoaders) { try { return transform(await loader()); } catch (e) { log( `Failed to load or transform ${loader.loaderName} with the following error:\n${ e instanceof Error ? e.message : e }`, ); continue; } } return defaultValue; } /** * The root directory for the data files. This is different in the VS Code build * (since those files are copied to the dist folder at a different relative path) */ function dataRoot() { if (process.env.WEBPACK_MODE) { return path.resolve(__dirname, './data'); } else { return path.resolve(__dirname, '../data'); } } /** Returns the at-build-time path to the fallback data file. */ async function fallbackResource(name: Resource, log: Logger): Promise { const sourcePath = path.resolve(dataRoot(), `${name}.json`); return fs .readFile(sourcePath, 'utf8') .then(tap(() => log(`Loaded fallback resource\n\t${name} from\n\t${sourcePath}`))); } /** Returns the at-build-time path to the fallback schema file. */ async function fallbackSchema( /** e.g. themes/section.json */ relativeUri: string, log: Logger, ): Promise { const sourcePath = path.resolve(dataRoot(), path.basename(relativeUri)); return fs .readFile(sourcePath, 'utf8') .then(tap(() => log(`Loaded fallback schema\n\t${relativeUri} from\n\t${sourcePath}`))); }