@platformos/platformos-common 0.0.11 → 0.0.15

package/src/documents-locator/DocumentsLocator.spec.ts

@@ -1,16 +1,28 @@
 import { describe, it, expect, vi } from 'vitest';
 import { URI } from 'vscode-uri';
-import { DocumentsLocator } from './DocumentsLocator';
+import { DocumentsLocator, loadSearchPaths } from './DocumentsLocator';
 import { AbstractFileSystem, FileType, FileStat, FileTuple } from '../AbstractFileSystem';
 
 function createMockFileSystem(files: Record<string, string>): AbstractFileSystem {
   const fileSet = new Set(Object.keys(files));
 
+  // Build directory tree from file paths
+  const dirs = new Set<string>();
+  for (const filePath of fileSet) {
+    const parts = filePath.split('/');
+    for (let i = 1; i < parts.length; i++) {
+      dirs.add(parts.slice(0, i).join('/'));
+    }
+  }
+
   return {
     stat: vi.fn(async (uri: string): Promise<FileStat> => {
       if (fileSet.has(uri)) {
         return { type: FileType.File, size: files[uri].length };
       }
+      if (dirs.has(uri)) {
+        return { type: FileType.Directory, size: 0 };
+      }
       throw new Error(`File not found: ${uri}`);
     }),
     readFile: vi.fn(async (uri: string): Promise<string> => {
@@ -21,10 +33,19 @@ function createMockFileSystem(files: Record<string, string>): AbstractFileSystem
     }),
     readDirectory: vi.fn(async (uri: string): Promise<FileTuple[]> => {
       const results: FileTuple[] = [];
-      for (const filePath of fileSet) {
-        if (filePath.startsWith(uri)) {
-          results.push([filePath, FileType.File]);
-        }
+      const seen = new Set<string>();
+      const prefix = uri.endsWith('/') ? uri : uri + '/';
+
+      for (const path of [...fileSet, ...dirs]) {
+        if (!path.startsWith(prefix)) continue;
+        const rest = path.slice(prefix.length);
+        const firstSegment = rest.split('/')[0];
+        if (!firstSegment || seen.has(firstSegment)) continue;
+        seen.add(firstSegment);
+
+        const fullPath = prefix + firstSegment;
+        const isDir = dirs.has(fullPath) && !fileSet.has(fullPath);
+        results.push([fullPath, isDir ? FileType.Directory : FileType.File]);
       }
       return results;
     }),
@@ -34,6 +55,74 @@ function createMockFileSystem(files: Record<string, string>): AbstractFileSystem
 describe('DocumentsLocator', () => {
   const rootUri = URI.parse('file:///project');
 
+  describe('locateDefault', () => {
+    it('render → app/views/partials', () => {
+      const locator = new DocumentsLocator(createMockFileSystem({}));
+      expect(locator.locateDefault(rootUri, 'render', 'my/partial')).toBe(
+        'file:///project/app/views/partials/my/partial.liquid',
+      );
+    });
+
+    it('include → app/views/partials', () => {
+      const locator = new DocumentsLocator(createMockFileSystem({}));
+      expect(locator.locateDefault(rootUri, 'include', 'card')).toBe(
+        'file:///project/app/views/partials/card.liquid',
+      );
+    });
+
+    it('function → app/lib', () => {
+      const locator = new DocumentsLocator(createMockFileSystem({}));
+      expect(locator.locateDefault(rootUri, 'function', 'commands/apply')).toBe(
+        'file:///project/app/lib/commands/apply.liquid',
+      );
+    });
+
+    it('graphql → app/graphql', () => {
+      const locator = new DocumentsLocator(createMockFileSystem({}));
+      expect(locator.locateDefault(rootUri, 'graphql', 'users/search')).toBe(
+        'file:///project/app/graphql/users/search.graphql',
+      );
+    });
+
+    it('theme_render_rc → undefined', () => {
+      const locator = new DocumentsLocator(createMockFileSystem({}));
+      expect(locator.locateDefault(rootUri, 'theme_render_rc', 'card')).toBeUndefined();
+    });
+
+    it('module render → modules/.../public/views/partials', () => {
+      const locator = new DocumentsLocator(createMockFileSystem({}));
+      expect(locator.locateDefault(rootUri, 'render', 'modules/core/my/partial')).toBe(
+        'file:///project/modules/core/public/views/partials/my/partial.liquid',
+      );
+    });
+
+    it('module function → modules/.../public/lib', () => {
+      const locator = new DocumentsLocator(createMockFileSystem({}));
+      expect(locator.locateDefault(rootUri, 'function', 'modules/core/commands/apply')).toBe(
+        'file:///project/modules/core/public/lib/commands/apply.liquid',
+      );
+    });
+
+    it('module graphql → modules/.../public/graphql', () => {
+      const locator = new DocumentsLocator(createMockFileSystem({}));
+      expect(locator.locateDefault(rootUri, 'graphql', 'modules/core/users/search')).toBe(
+        'file:///project/modules/core/public/graphql/users/search.graphql',
+      );
+    });
+
+    it('deeply nested path — creates all missing intermediate dirs', () => {
+      const locator = new DocumentsLocator(createMockFileSystem({}));
+      expect(locator.locateDefault(rootUri, 'render', 'a/b/c/d/partial')).toBe(
+        'file:///project/app/views/partials/a/b/c/d/partial.liquid',
+      );
+    });
+
+    it('asset → undefined (no canonical creation path)', () => {
+      const locator = new DocumentsLocator(createMockFileSystem({}));
+      expect(locator.locateDefault(rootUri, 'asset', 'logo.png')).toBeUndefined();
+    });
+  });
+
   describe('locate', () => {
     it('should locate a partial file in app/lib', async () => {
       const fs = createMockFileSystem({
@@ -137,4 +226,277 @@ describe('DocumentsLocator', () => {
       expect(result).toEqual([]);
     });
   });
+
+  describe('locateWithSearchPaths', () => {
+    it('should find partial via first search path', async () => {
+      const fs = createMockFileSystem({
+        'file:///project/app/views/partials/theme/dress/card.liquid': 'dress',
+        'file:///project/app/views/partials/theme/simple/card.liquid': 'simple',
+      });
+      const locator = new DocumentsLocator(fs);
+
+      const result = await locator.locateWithSearchPaths(rootUri, 'card', [
+        'theme/dress',
+        'theme/simple',
+      ]);
+
+      expect(result).toBe('file:///project/app/views/partials/theme/dress/card.liquid');
+    });
+
+    it('should fall through to second search path', async () => {
+      const fs = createMockFileSystem({
+        'file:///project/app/views/partials/theme/simple/card.liquid': 'simple',
+      });
+      const locator = new DocumentsLocator(fs);
+
+      const result = await locator.locateWithSearchPaths(rootUri, 'card', [
+        'theme/dress',
+        'theme/simple',
+      ]);
+
+      expect(result).toBe('file:///project/app/views/partials/theme/simple/card.liquid');
+    });
+
+    it('should fallback to unprefixed path when no search path matches', async () => {
+      const fs = createMockFileSystem({
+        'file:///project/app/views/partials/card.liquid': 'default',
+      });
+      const locator = new DocumentsLocator(fs);
+
+      const result = await locator.locateWithSearchPaths(rootUri, 'card', [
+        'theme/dress',
+        'theme/simple',
+      ]);
+
+      expect(result).toBe('file:///project/app/views/partials/card.liquid');
+    });
+
+    it('should not fallback when empty string is in search paths', async () => {
+      const fs = createMockFileSystem({
+        'file:///project/app/views/partials/card.liquid': 'default',
+      });
+      const locator = new DocumentsLocator(fs);
+
+      // '' is at position 0, so it tries default path first, finds it
+      const result = await locator.locateWithSearchPaths(rootUri, 'card', ['', 'theme/dress']);
+      expect(result).toBe('file:///project/app/views/partials/card.liquid');
+    });
+
+    it('should return undefined when nothing matches', async () => {
+      const fs = createMockFileSystem({});
+      const locator = new DocumentsLocator(fs);
+
+      const result = await locator.locateWithSearchPaths(rootUri, 'card', ['theme/dress']);
+      expect(result).toBeUndefined();
+    });
+
+    it('should handle nested partial names with search paths', async () => {
+      const fs = createMockFileSystem({
+        'file:///project/app/views/partials/theme/dress/components/hero.liquid': 'hero',
+      });
+      const locator = new DocumentsLocator(fs);
+
+      const result = await locator.locateWithSearchPaths(rootUri, 'components/hero', [
+        'theme/dress',
+      ]);
+
+      expect(result).toBe('file:///project/app/views/partials/theme/dress/components/hero.liquid');
+    });
+
+    it('should also search app/lib with search paths', async () => {
+      const fs = createMockFileSystem({
+        'file:///project/app/lib/theme/dress/helper.liquid': 'helper',
+      });
+      const locator = new DocumentsLocator(fs);
+
+      const result = await locator.locateWithSearchPaths(rootUri, 'helper', ['theme/dress']);
+
+      expect(result).toBe('file:///project/app/lib/theme/dress/helper.liquid');
+    });
+
+    it('should expand dynamic Liquid expressions as wildcards', async () => {
+      const fs = createMockFileSystem({
+        'file:///project/app/views/partials/theme/custom/card.liquid': 'custom card',
+      });
+      const locator = new DocumentsLocator(fs);
+
+      const result = await locator.locateWithSearchPaths(rootUri, 'card', [
+        'theme/{{ context.constants.THEME }}',
+      ]);
+
+      expect(result).toBe('file:///project/app/views/partials/theme/custom/card.liquid');
+    });
+
+    it('should expand multiple wildcards in a single path', async () => {
+      const fs = createMockFileSystem({
+        'file:///project/app/views/partials/acme/premium/card.liquid': 'card',
+      });
+      const locator = new DocumentsLocator(fs);
+
+      const result = await locator.locateWithSearchPaths(rootUri, 'card', [
+        '{{ context.constants.BRAND }}/{{ context.constants.TIER }}',
+      ]);
+
+      expect(result).toBe('file:///project/app/views/partials/acme/premium/card.liquid');
+    });
+
+    it('should return undefined when wildcard expands but partial not found', async () => {
+      const fs = createMockFileSystem({
+        'file:///project/app/views/partials/theme/custom/other.liquid': 'other',
+      });
+      const locator = new DocumentsLocator(fs);
+
+      const result = await locator.locateWithSearchPaths(rootUri, 'missing', [
+        'theme/{{ context.constants.THEME }}',
+      ]);
+
+      // Fallback to unprefixed — also not found
+      expect(result).toBeUndefined();
+    });
+
+    it('should cache expanded paths across calls', async () => {
+      const fs = createMockFileSystem({
+        'file:///project/app/views/partials/theme/custom/a.liquid': 'a',
+        'file:///project/app/views/partials/theme/custom/b.liquid': 'b',
+      });
+      const locator = new DocumentsLocator(fs);
+      const searchPaths = ['theme/{{ x }}'];
+
+      await locator.locateWithSearchPaths(rootUri, 'a', searchPaths);
+      const readDirSpy = fs.readDirectory as ReturnType<typeof vi.fn>;
+      const callCountAfterFirst = readDirSpy.mock.calls.length;
+
+      await locator.locateWithSearchPaths(rootUri, 'b', searchPaths);
+      // readDirectory should not be called again for wildcard expansion
+      // (only for locateFile stat calls, not for listSubdirectories)
+      const expansionCalls = readDirSpy.mock.calls.filter(
+        (call: string[]) =>
+          call[0].includes('app/views/partials/theme') && !call[0].includes('.liquid'),
+      );
+      // All expansion readDirectory calls should come from the first invocation
+      const expansionCallsAfterFirst = readDirSpy.mock.calls
+        .slice(callCountAfterFirst)
+        .filter(
+          (call: string[]) =>
+            call[0].includes('app/views/partials/theme') && !call[0].includes('.liquid'),
+        );
+      expect(expansionCallsAfterFirst).toHaveLength(0);
+    });
+
+    it('should clear expanded paths cache', async () => {
+      const fs = createMockFileSystem({
+        'file:///project/app/views/partials/theme/v1/card.liquid': 'v1',
+      });
+      const locator = new DocumentsLocator(fs);
+
+      const result1 = await locator.locateWithSearchPaths(rootUri, 'card', ['theme/{{ version }}']);
+      expect(result1).toBe('file:///project/app/views/partials/theme/v1/card.liquid');
+
+      locator.clearExpandedPathsCache();
+
+      // After clearing, a fresh expansion should work (same result since fs unchanged)
+      const result2 = await locator.locateWithSearchPaths(rootUri, 'card', ['theme/{{ version }}']);
+      expect(result2).toBe('file:///project/app/views/partials/theme/v1/card.liquid');
+    });
+
+    it('should handle module-prefixed partials with search paths', async () => {
+      const fs = createMockFileSystem({
+        'file:///project/app/modules/shop/public/views/partials/card.liquid': 'module card',
+      });
+      const locator = new DocumentsLocator(fs);
+
+      // module path in fallback (search paths don't apply to module prefix)
+      const result = await locator.locateWithSearchPaths(rootUri, 'modules/shop/card', [
+        'theme/dress',
+      ]);
+
+      expect(result).toBe('file:///project/app/modules/shop/public/views/partials/card.liquid');
+    });
+  });
+
+  describe('loadSearchPaths', () => {
+    it('should load valid theme_search_paths from config', async () => {
+      const fs = createMockFileSystem({
+        'file:///project/app/config.yml': 'theme_search_paths:\n  - theme/dress\n  - theme/simple',
+      });
+
+      const result = await loadSearchPaths(fs, rootUri);
+      expect(result).toEqual(['theme/dress', 'theme/simple']);
+    });
+
+    it('should return null when config file does not exist', async () => {
+      const fs = createMockFileSystem({});
+
+      const result = await loadSearchPaths(fs, rootUri);
+      expect(result).toBeNull();
+    });
+
+    it('should return null for empty array', async () => {
+      const fs = createMockFileSystem({
+        'file:///project/app/config.yml': 'theme_search_paths: []',
+      });
+
+      const result = await loadSearchPaths(fs, rootUri);
+      expect(result).toBeNull();
+    });
+
+    it('should return null when theme_search_paths is not an array', async () => {
+      const fs = createMockFileSystem({
+        'file:///project/app/config.yml': 'theme_search_paths: some_string',
+      });
+
+      const result = await loadSearchPaths(fs, rootUri);
+      expect(result).toBeNull();
+    });
+
+    it('should return null when config has no theme_search_paths key', async () => {
+      const fs = createMockFileSystem({
+        'file:///project/app/config.yml': 'some_other_key: value',
+      });
+
+      const result = await loadSearchPaths(fs, rootUri);
+      expect(result).toBeNull();
+    });
+
+    it('should coerce non-string entries to strings', async () => {
+      const fs = createMockFileSystem({
+        'file:///project/app/config.yml': 'theme_search_paths:\n  - 123\n  - true\n  - null',
+      });
+
+      const result = await loadSearchPaths(fs, rootUri);
+      expect(result).toEqual(['123', 'true', 'null']);
+    });
+
+    it('should handle config with Liquid expressions in paths', async () => {
+      const fs = createMockFileSystem({
+        'file:///project/app/config.yml':
+          'theme_search_paths:\n  - "theme/{{ context.constants.MY_THEME | default: \'custom\' }}"\n  - theme/simple',
+      });
+
+      const result = await loadSearchPaths(fs, rootUri);
+      expect(result).toEqual([
+        "theme/{{ context.constants.MY_THEME | default: 'custom' }}",
+        'theme/simple',
+      ]);
+    });
+
+    it('should handle malformed YAML gracefully', async () => {
+      const fs = createMockFileSystem({
+        'file:///project/app/config.yml': '{{invalid yaml',
+      });
+
+      const result = await loadSearchPaths(fs, rootUri);
+      expect(result).toBeNull();
+    });
+
+    it('should handle config with other properties alongside theme_search_paths', async () => {
+      const fs = createMockFileSystem({
+        'file:///project/app/config.yml':
+          'some_setting: true\ntheme_search_paths:\n  - theme/dress\nanother_setting: 42',
+      });
+
+      const result = await loadSearchPaths(fs, rootUri);
+      expect(result).toEqual(['theme/dress']);
+    });
+  });
 });

package/src/documents-locator/DocumentsLocator.ts

@@ -1,8 +1,38 @@
+import yaml from 'js-yaml';
 import { AbstractFileSystem, FileType } from '../AbstractFileSystem';
 import { getAppPaths, getModulePaths, PlatformOSFileType } from '../path-utils';
 import { URI, Utils } from 'vscode-uri';
 
-export type DocumentType = 'function' | 'render' | 'include' | 'graphql' | 'asset';
+export type DocumentType =
+  | 'function'
+  | 'render'
+  | 'include'
+  | 'graphql'
+  | 'asset'
+  | 'theme_render_rc';
+
+/**
+ * Load theme_search_paths from app/config.yml.
+ * Returns null if the file doesn't exist, is malformed, or has no valid theme_search_paths.
+ * Results should be cached per root URI.
+ */
+export async function loadSearchPaths(
+  fs: { readFile(uri: string): Promise<string> },
+  rootUri: URI,
+): Promise<string[] | null> {
+  try {
+    const configUri = Utils.joinPath(rootUri, 'app/config.yml').toString();
+    const content = await fs.readFile(configUri);
+    const config = yaml.load(content) as Record<string, unknown> | null;
+    const paths = config?.theme_search_paths;
+    if (Array.isArray(paths) && paths.length > 0) {
+      return paths.map(String);
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
 
 type ModulePathInfo =
   | { isModule: false; key: string }
@@ -127,10 +157,170 @@ export class DocumentsLocator {
     return Array.from(results).sort((a, b) => a.localeCompare(b));
   }
 
+  private static readonly LIQUID_EXPRESSION_RE = /\{\{.*?\}\}/;
+
+  private async listSubdirectoryNames(dirUri: string): Promise<string[]> {
+    try {
+      const entries = await this.fs.readDirectory(dirUri);
+      return entries
+        .filter(([, type]) => type === FileType.Directory)
+        .map(([name]) => {
+          const lastSlash = name.lastIndexOf('/');
+          return lastSlash === -1 ? name : name.slice(lastSlash + 1);
+        })
+        .filter((name) => name.length > 0);
+    } catch {
+      return [];
+    }
+  }
+
+  private expandedPathsCache = new Map<string, Promise<string[]>>();
+
+  clearExpandedPathsCache(): void {
+    this.expandedPathsCache.clear();
+  }
+
+  /**
+   * Expand a search path that may contain {{ ... }} Liquid expressions into
+   * concrete directory prefixes by enumerating subdirectories at each dynamic
+   * segment. Static segments pass through unchanged.
+   *
+   * Results are cached per (rootUri, searchPath) and capped at 100 entries.
+   */
+  private async expandDynamicPath(rootUri: URI, searchPath: string): Promise<string[]> {
+    const segments = searchPath.split('/');
+    const basePaths = this.getSearchPaths('partial');
+    let prefixes = [''];
+
+    for (const segment of segments) {
+      if (!DocumentsLocator.LIQUID_EXPRESSION_RE.test(segment)) {
+        prefixes = prefixes.map((p) => (p ? `${p}/${segment}` : segment));
+        continue;
+      }
+
+      const nextPrefixes: string[] = [];
+      for (const prefix of prefixes) {
+        const subdirs = new Set<string>();
+        for (const base of basePaths) {
+          const dirUri = prefix
+            ? Utils.joinPath(rootUri, base, prefix).toString()
+            : Utils.joinPath(rootUri, base).toString();
+          for (const name of await this.listSubdirectoryNames(dirUri)) {
+            subdirs.add(name);
+          }
+        }
+        for (const sub of subdirs) {
+          nextPrefixes.push(prefix ? `${prefix}/${sub}` : sub);
+          if (nextPrefixes.length >= 100) break;
+        }
+        if (nextPrefixes.length >= 100) break;
+      }
+      prefixes = nextPrefixes;
+    }
+
+    return prefixes;
+  }
+
+  /**
+   * Resolve a search path (static, dynamic, or empty) into concrete prefix
+   * strings. Cached for dynamic paths.
+   */
+  private async resolveSearchPath(rootUri: URI, searchPath: string): Promise<string[]> {
+    if (searchPath === '') return [''];
+    if (!DocumentsLocator.LIQUID_EXPRESSION_RE.test(searchPath)) return [searchPath];
+
+    const cacheKey = `${rootUri.toString()}:${searchPath}`;
+    if (!this.expandedPathsCache.has(cacheKey)) {
+      this.expandedPathsCache.set(cacheKey, this.expandDynamicPath(rootUri, searchPath));
+    }
+    return this.expandedPathsCache.get(cacheKey)!;
+  }
+
+  /**
+   * Locate a partial using theme search paths (for theme_render_rc).
+   *
+   * Tries each search path prefix in priority order, then falls back to the
+   * unprefixed name (unless '' was already in the list, meaning the default
+   * position was explicitly placed).
+   */
+  async locateWithSearchPaths(
+    rootUri: URI,
+    fileName: string,
+    themeSearchPaths: string[],
+  ): Promise<string | undefined> {
+    for (const searchPath of themeSearchPaths) {
+      for (const prefix of await this.resolveSearchPath(rootUri, searchPath)) {
+        const candidate = prefix ? `${prefix}/${fileName}` : fileName;
+        const result = await this.locateFile(rootUri, candidate, 'partial');
+        if (result) return result;
+      }
+    }
+
+    if (!themeSearchPaths.includes('')) {
+      return this.locateFile(rootUri, fileName, 'partial');
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Returns the canonical URI where `fileName` would live — used as a
+   * go-to-definition fallback when the file doesn't exist yet.
+   * Returns undefined for theme_render_rc (ambiguous search path) and asset.
+   */
+  locateDefault(rootUri: URI, nodeName: DocumentType, fileName: string): string | undefined {
+    const parsed = this.parseModulePath(fileName);
+
+    let basePath: string;
+    let ext: string;
+
+    switch (nodeName) {
+      case 'render':
+      case 'include':
+        basePath = parsed.isModule
+          ? `modules/${parsed.moduleName}/public/views/partials`
+          : 'app/views/partials';
+        ext = '.liquid';
+        break;
+      case 'function':
+        basePath = parsed.isModule ? `modules/${parsed.moduleName}/public/lib` : 'app/lib';
+        ext = '.liquid';
+        break;
+      case 'graphql':
+        basePath = parsed.isModule ? `modules/${parsed.moduleName}/public/graphql` : 'app/graphql';
+        ext = '.graphql';
+        break;
+      case 'theme_render_rc': // ambiguous — multiple search paths, no single canonical location
+      case 'asset': // no canonical creation path
+        return undefined;
+      default:
+        return undefined;
+    }
+
+    return Utils.joinPath(rootUri, basePath, parsed.key + ext).toString();
+  }
+
+  /**
+   * Resolves `fileName` to a filesystem URI (if the file exists), or falls
+   * back to the canonical default URI from `locateDefault`.
+   */
+  async locateOrDefault(
+    rootUri: URI,
+    nodeName: DocumentType,
+    fileName: string,
+    themeSearchPaths?: string[] | null,
+  ): Promise<string | undefined> {
+    return (
+      (await this.locate(rootUri, nodeName, fileName, themeSearchPaths)) ??
+      this.locateDefault(rootUri, nodeName, fileName)
+    );
+  }
+
   async locate(
     rootUri: URI,
     nodeName: DocumentType,
     fileName: string,
+    themeSearchPaths?: string[] | null,
   ): Promise<string | undefined> {
     switch (nodeName) {
       case 'render':
@@ -138,6 +328,11 @@ export class DocumentsLocator {
       case 'function':
         return this.locateFile(rootUri, fileName, 'partial');
 
+      case 'theme_render_rc':
+        return themeSearchPaths
+          ? this.locateWithSearchPaths(rootUri, fileName, themeSearchPaths)
+          : this.locateFile(rootUri, fileName, 'partial');
+
       case 'graphql':
         return this.locateFile(rootUri, fileName, 'graphql');
 
@@ -154,6 +349,7 @@ export class DocumentsLocator {
       case 'function':
       case 'render':
       case 'include':
+      case 'theme_render_rc':
         return this.listFiles(rootUri, filePrefix, 'partial');
 
       case 'graphql':

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from './documents-locator/DocumentsLocator';
 export * from './translation-provider/TranslationProvider';
+export * from './route-table';
 export * from './AbstractFileSystem';
 export * from './path-utils';