@platformos/platformos-common 0.0.10 → 0.0.11

package/src/path-utils.ts

@@ -8,28 +8,65 @@
  * - getFileType() classifies any URI to a PlatformOSFileType
  * - isPage(), isLayout(), isPartial() etc. are convenience wrappers around getFileType()
  *
- * Pattern precision: each type uses exact path segment patterns (/app/{dir}/ or
- * /(public|private)/{dir}/) so that nested paths don't produce false positives.
- * For example, app/lib/smses/file.liquid is correctly identified as Partial
- * (matches /app/lib/), not Sms (does not match /app/smses/).
+ * Source of truth: app/services/app_builder/services/converters_config.rb and
+ * app/models/concerns/deployable.rb in the platformOS server codebase.
+ *
+ * DIR_PREFIX (Ruby): ^/?((marketplace_builder|app)/|modules/(.+)(private|public)/)?
+ * This means files can live under:
+ *   - app/{dir}/
+ *   - marketplace_builder/{dir}/          (legacy alias for app/)
+ *   - modules/{name}/(public|private)/{dir}/
+ *   - app/modules/{name}/(public|private)/{dir}/
  */
 
 import { UriString } from './AbstractFileSystem';
 
 /**
- * File types that exist in a platformOS app, each mapping to one or more
- * canonical directory names relative to the app root or module access level.
+ * File types that exist in a platformOS app, each corresponding to a server-side
+ * converter that processes the file on deploy.
+ *
+ * Liquid types:   Page, Layout, Partial, Authorization, Email, ApiCall, Sms, Migration, FormConfiguration
+ * YAML types:     CustomModelType, InstanceProfileType, TransactableType, Translation
+ * GraphQL types:  GraphQL
+ * Binary/other:   Asset
  */
 export enum PlatformOSFileType {
+  // ── Liquid ──────────────────────────────────────────────────────────────────
+  /** views/pages/ or pages/ → PageConverter */
   Page = 'Page',
+  /** views/layouts/ → LiquidViewConverter (layouts) */
   Layout = 'Layout',
+  /** views/partials/ or lib/ → LiquidViewConverter (partials) */
   Partial = 'Partial',
+  /** authorization_policies/ → AuthorizationPolicyConverter */
   Authorization = 'Authorization',
+  /** emails/ or notifications/email_notifications/ → EmailNotificationConverter */
   Email = 'Email',
+  /** api_calls/ or notifications/api_call_notifications/ → ApiCallNotificationConverter */
   ApiCall = 'ApiCall',
+  /** smses/ or notifications/sms_notifications/ → SmsNotificationConverter */
   Sms = 'Sms',
+  /** migrations/ → MigrationConverter */
   Migration = 'Migration',
+  /** form_configurations/ or forms/ → FormConfigurationConverter */
+  FormConfiguration = 'FormConfiguration',
+
+  // ── YAML ────────────────────────────────────────────────────────────────────
+  /** custom_model_types/, model_schemas/, or schema/ → CustomModelTypeConverter */
+  CustomModelType = 'CustomModelType',
+  /** instance_profile_types/, user_profile_types/, or user_profile_schemas/ → InstanceProfileTypeConverter */
+  InstanceProfileType = 'InstanceProfileType',
+  /** transactable_types/ → TransactableTypeConverter */
+  TransactableType = 'TransactableType',
+  /** translations/ → TranslationConverter */
+  Translation = 'Translation',
+
+  // ── GraphQL ─────────────────────────────────────────────────────────────────
+  /** graphql/ or graph_queries/ → GraphQueryConverter */
   GraphQL = 'GraphQL',
+
+  // ── Binary/other ────────────────────────────────────────────────────────────
+  /** assets/ → AssetConverter */
   Asset = 'Asset',
 }
 
@@ -37,30 +74,48 @@ export enum PlatformOSFileType {
  * The single source of truth for the platformOS directory structure.
  *
  * Maps each file type to its canonical directory name(s) relative to:
- *   - the app root:                  app/{dir}/
+ *   - the app root:                  (app|marketplace_builder)/{dir}/
  *   - a module access level:         modules/{name}/(public|private)/{dir}/
  *   - a nested module access level:  app/modules/{name}/(public|private)/{dir}/
  *
+ * Multiple dirs per type represent canonical + legacy aliases from the server
+ * converters_config.rb FULL_PHYSICAL_PATH regexes.
+ *
  * Types with multiple dirs (e.g. Partial) will match any of their dirs.
- * The first matching type wins, so order of evaluation matters for overlapping
- * paths — but exact segment matching means dirs don't overlap in practice.
+ * Order within each array doesn't matter for matching. Across types,
+ * exact segment matching prevents false positives between overlapping paths
+ * (e.g. app/lib/smses/ → Partial, not Sms).
  */
 export const FILE_TYPE_DIRS: Readonly<Record<PlatformOSFileType, readonly string[]>> = {
-  [PlatformOSFileType.Page]: ['views/pages'],
+  // Liquid
+  [PlatformOSFileType.Page]: ['views/pages', 'pages'],
   [PlatformOSFileType.Layout]: ['views/layouts'],
   [PlatformOSFileType.Partial]: ['views/partials', 'lib'],
   [PlatformOSFileType.Authorization]: ['authorization_policies'],
-  [PlatformOSFileType.Email]: ['emails'],
-  [PlatformOSFileType.ApiCall]: ['api_calls'],
-  [PlatformOSFileType.Sms]: ['smses'],
+  [PlatformOSFileType.Email]: ['emails', 'notifications/email_notifications'],
+  [PlatformOSFileType.ApiCall]: ['api_calls', 'notifications/api_call_notifications'],
+  [PlatformOSFileType.Sms]: ['smses', 'notifications/sms_notifications'],
   [PlatformOSFileType.Migration]: ['migrations'],
-  [PlatformOSFileType.GraphQL]: ['graphql'],
+  [PlatformOSFileType.FormConfiguration]: ['form_configurations', 'forms'],
+  // YAML
+  [PlatformOSFileType.CustomModelType]: ['custom_model_types', 'model_schemas', 'schema'],
+  [PlatformOSFileType.InstanceProfileType]: [
+    'instance_profile_types',
+    'user_profile_types',
+    'user_profile_schemas',
+  ],
+  [PlatformOSFileType.TransactableType]: ['transactable_types'],
+  [PlatformOSFileType.Translation]: ['translations'],
+  // GraphQL
+  [PlatformOSFileType.GraphQL]: ['graphql', 'graph_queries'],
+  // Asset
   [PlatformOSFileType.Asset]: ['assets'],
 };
 
 /**
- * Liquid-containing file types. GraphQL and Asset are excluded because they
- * don't contain Liquid code and should not be passed to the Liquid linter.
+ * Liquid-containing file types. GraphQL, Asset, and YAML types are excluded
+ * because they don't contain Liquid code and should not be passed to the
+ * Liquid linter.
  */
 const LIQUID_FILE_TYPES = new Set<PlatformOSFileType>([
   PlatformOSFileType.Page,
@@ -71,16 +126,17 @@ const LIQUID_FILE_TYPES = new Set<PlatformOSFileType>([
   PlatformOSFileType.ApiCall,
   PlatformOSFileType.Sms,
   PlatformOSFileType.Migration,
+  PlatformOSFileType.FormConfiguration,
 ]);
 
 /**
  * Pre-compiled regex per file type, derived entirely from FILE_TYPE_DIRS.
  *
- * For each canonical dir, two pattern alternatives are generated:
- *   /app/{dir}/              — direct app-level path (e.g. /app/lib/)
- *   /(public|private)/{dir}/ — module path, covers both:
- *                                modules/{name}/(public|private)/{dir}/
- *                                app/modules/{name}/(public|private)/{dir}/
+ * For each canonical dir, three pattern alternatives are generated:
+ *   /(app|marketplace_builder)/{dir}/  — direct app-level path (modern + legacy root)
+ *   /(public|private)/{dir}/           — module path, covers both:
+ *                                          modules/{name}/(public|private)/{dir}/
+ *                                          app/modules/{name}/(public|private)/{dir}/
  *
  * Exact path segment matching prevents false positives:
  *   /app/lib/smses/file.liquid  → matches /app/lib/ → Partial (NOT Sms)
@@ -89,7 +145,10 @@ const LIQUID_FILE_TYPES = new Set<PlatformOSFileType>([
 const TYPE_MATCHERS = new Map<PlatformOSFileType, RegExp>(
   (Object.entries(FILE_TYPE_DIRS) as [PlatformOSFileType, readonly string[]][]).map(
     ([type, dirs]) => {
-      const alternatives = dirs.flatMap((dir) => [`/app/${dir}/`, `/(public|private)/${dir}/`]);
+      const alternatives = dirs.flatMap((dir) => [
+        `/(app|marketplace_builder)/${dir}/`,
+        `/(public|private)/${dir}/`,
+      ]);
       return [type, new RegExp(alternatives.join('|'))];
     },
   ),
@@ -99,9 +158,13 @@ const TYPE_MATCHERS = new Map<PlatformOSFileType, RegExp>(
  * Returns the PlatformOSFileType for the given URI, or undefined if the URI
  * does not belong to any recognized platformOS directory.
  *
+ * Supports both modern (app/) and legacy (marketplace_builder/) app roots,
+ * as well as module paths (modules/{name}/public|private/).
+ *
  * @example
- * getFileType('file:///root/app/lib/smses/notify.liquid') // → PlatformOSFileType.Partial
- * getFileType('file:///root/app/smses/notify.liquid')     // → PlatformOSFileType.Sms
+ * getFileType('file:///root/app/lib/smses/notify.liquid')              // → Partial
+ * getFileType('file:///root/app/smses/notify.liquid')                  // → Sms
+ * getFileType('file:///root/marketplace_builder/views/pages/home.liquid') // → Page
  * getFileType('file:///root/modules/core/generators/templates/lib/create.liquid') // → undefined
  */
 export function getFileType(uri: UriString): PlatformOSFileType | undefined {
@@ -113,10 +176,11 @@ export function getFileType(uri: UriString): PlatformOSFileType | undefined {
 
 /**
  * Returns app-level search paths for a file type (relative to project root).
+ * Uses the modern `app/` root (not the legacy `marketplace_builder/` alias).
  *
  * @example
  * getAppPaths(PlatformOSFileType.Partial) // → ['app/views/partials', 'app/lib']
- * getAppPaths(PlatformOSFileType.GraphQL) // → ['app/graphql']
+ * getAppPaths(PlatformOSFileType.GraphQL) // → ['app/graphql', 'app/graph_queries']
  */
 export function getAppPaths(type: PlatformOSFileType): string[] {
   return FILE_TYPE_DIRS[type].map((dir) => `app/${dir}`);
@@ -134,9 +198,7 @@ export function getAppPaths(type: PlatformOSFileType): string[] {
  *   'modules/core/public/views/partials',
  *   'modules/core/private/views/partials',
  *   'app/modules/core/public/lib',
- *   'app/modules/core/private/lib',
- *   'modules/core/public/lib',
- *   'modules/core/private/lib',
+ *   ...
  * ]
  */
 export function getModulePaths(type: PlatformOSFileType, moduleName: string): string[] {
@@ -158,6 +220,15 @@ export function isKnownLiquidFile(uri: UriString): boolean {
   return type !== undefined && LIQUID_FILE_TYPES.has(type);
 }
 
+/**
+ * Returns true if the URI belongs to a recognized platformOS GraphQL directory
+ * and should be linted. Files outside known directories (e.g. generator
+ * templates, schema files, ERB templates) return false and are excluded.
+ */
+export function isKnownGraphQLFile(uri: UriString): boolean {
+  return getFileType(uri) === PlatformOSFileType.GraphQL;
+}
+
 export function isPartial(uri: UriString): boolean {
   return getFileType(uri) === PlatformOSFileType.Partial;
 }
@@ -189,3 +260,7 @@ export function isSms(uri: UriString): boolean {
 export function isMigration(uri: UriString): boolean {
   return getFileType(uri) === PlatformOSFileType.Migration;
 }
+
+export function isFormConfiguration(uri: UriString): boolean {
+  return getFileType(uri) === PlatformOSFileType.FormConfiguration;
+}