@lokascript/framework 2.8.0 → 2.9.0

package/src/generation/renderer.ts

@@ -9,9 +9,9 @@
  */
 
 import type { SemanticNode } from '../core/types';
-import { extractRoleValue } from '../core/types';
-import type { CommandSchema, RoleSpec } from '../schema';
-import type { PatternGenLanguageProfile } from './pattern-generator';
+import { extractRoleValue, extractValue } from '../core/types';
+import type { CommandSchema } from '../schema';
+import { sortRolesByWordOrder, type PatternGenLanguageProfile } from './pattern-generator';
 
 // =============================================================================
 // Renderer Interface
@@ -191,54 +191,197 @@ export function createSchemaRenderer(
   schemas: readonly CommandSchema[],
   profiles: readonly PatternGenLanguageProfile[]
 ): NaturalLanguageRenderer {
+  const tables = buildRenderTables(schemas, profiles);
+
+  return {
+    render(node: SemanticNode, language: string): string {
+      // An action with no schema still has a name — render that rather than
+      // nothing. `createDomainRenderer` returns null for this case instead.
+      return renderFromSchema(node, language, tables) ?? node.action;
+    },
+  };
+}
+
+// =============================================================================
+// Domain renderer (hand-written cases + schema fallthrough)
+// =============================================================================
+
+/**
+ * Renders a SemanticNode, or returns `null` when the action cannot be rendered.
+ *
+ * The nullable counterpart to {@link NaturalLanguageRenderer}: `null` means "I
+ * do not know this action", which callers can act on. A domain that signals the
+ * same condition with a sentinel string forces consumers into string matching.
+ */
+export type DomainRenderFn = (node: SemanticNode, language: string) => string | null;
+
+/**
+ * Configuration for {@link createDomainRenderer}.
+ */
+export interface DomainRendererConfig {
+  /** Schemas for this domain's commands, including any extensions. */
+  readonly schemas: readonly CommandSchema[];
+
+  /** Language profiles supplying keywords and role markers. */
+  readonly profiles: readonly PatternGenLanguageProfile[];
+
+  /**
+   * Hand-written renderers per action. These take absolute precedence over the
+   * schema-driven path, so a domain's existing output is preserved byte for byte.
+   *
+   * An override returning `null` means "this action cannot be rendered" and is
+   * passed straight through — it does not fall through to the schema path,
+   * since a hand-written renderer knows more about its action than the schema does.
+   */
+  readonly overrides?: Readonly<Record<string, DomainRenderFn>>;
+}
+
+/**
+ * Create a renderer that composes a domain's hand-written per-action renderers
+ * with the schema-driven fallback.
+ *
+ * Resolution order:
+ *   1. `overrides[node.action]` — the domain's own rendering, unchanged
+ *   2. schema-driven rendering — any action with a schema but no hand-written case
+ *   3. `null` — no override and no schema
+ *
+ * Step 2 is what makes a domain extensible: a consumer that adds a command
+ * schema (with per-language keywords in the profiles) gets correct word order,
+ * markers and keywords for free, without the domain package having to know
+ * about that command.
+ *
+ * @example
+ * ```typescript
+ * const render = createDomainRenderer({
+ *   schemas: allSchemas,
+ *   profiles: allProfiles,
+ *   overrides: { select: renderSelect, insert: renderInsert },
+ * });
+ * render(node, 'ja');       // hand-written for `select`, schema-driven otherwise
+ * render(bogusNode, 'en');  // → null
+ * ```
+ */
+export function createDomainRenderer(config: DomainRendererConfig): DomainRenderFn {
+  const { schemas, profiles, overrides } = config;
+
+  // Built on first render — a domain module can construct its renderer at import
+  // time without paying for table construction it may never use.
+  let tables: RenderTables | undefined;
+
+  return (node: SemanticNode, language: string): string | null => {
+    const override = overrides?.[node.action];
+    if (override) return override(node, language);
+
+    tables ??= buildRenderTables(schemas, profiles);
+    return renderFromSchema(node, language, tables);
+  };
+}
+
+// =============================================================================
+// Shared schema-driven rendering
+// =============================================================================
+
+interface RenderTables {
+  readonly keywords: KeywordTable;
+  readonly markers: MarkerTable;
+  /** Marker side per role per language, from each profile's roleMarkers. */
+  readonly markerPositions: Record<string, Record<string, 'before' | 'after'>>;
+  readonly sovLanguages: ReadonlySet<string>;
+  readonly schemaMap: ReadonlyMap<string, CommandSchema>;
+}
+
+function buildRenderTables(
+  schemas: readonly CommandSchema[],
+  profiles: readonly PatternGenLanguageProfile[]
+): RenderTables {
   const { keywords, markers } = buildTablesFromProfiles(schemas, profiles);
   const { sovLanguages } = detectWordOrders(profiles);
+
+  const markerPositions: Record<string, Record<string, 'before' | 'after'>> = {};
+  for (const profile of profiles) {
+    for (const [role, markerDef] of Object.entries(profile.roleMarkers ?? {})) {
+      if (!markerDef.position) continue;
+      markerPositions[role] ??= {};
+      markerPositions[role][profile.code] = markerDef.position;
+    }
+  }
+
   const schemaMap = new Map<string, CommandSchema>();
   for (const s of schemas) schemaMap.set(s.action, s);
+  return { keywords, markers, markerPositions, sovLanguages, schemaMap };
+}
 
-  return {
-    render(node: SemanticNode, language: string): string {
-      const schema = schemaMap.get(node.action);
-      if (!schema) return node.action;
-
-      const keyword = lookupKeyword(keywords, node.action, language);
-      const isSOV = sovLanguages.has(language);
-
-      // Collect role parts in schema order
-      const roleParts: Array<{ marker?: string; value: string; role: RoleSpec }> = [];
-      for (const role of schema.roles) {
-        const value = extractRoleValue(node, role.role);
-        if (!value && !role.required) continue;
-
-        const markerText =
-          role.markerOverride?.[language] ?? markers[role.role]?.[language] ?? undefined;
-
-        roleParts.push({
-          ...(markerText != null && { marker: markerText }),
-          value: value || '',
-          role,
-        });
-      }
+/**
+ * The one schema-driven rendering algorithm, shared by `createSchemaRenderer`
+ * and `createDomainRenderer` so the two can never drift.
+ *
+ * Returns `null` when the action has no schema.
+ */
+function renderFromSchema(
+  node: SemanticNode,
+  language: string,
+  tables: RenderTables
+): string | null {
+  const schema = tables.schemaMap.get(node.action);
+  if (!schema) return null;
 
-      const parts: string[] = [];
+  const keyword = lookupKeyword(tables.keywords, node.action, language);
+  const isSOV = tables.sovLanguages.has(language);
 
-      if (isSOV) {
-        // SOV: roles (with markers after values) then keyword
-        for (const rp of roleParts) {
-          if (rp.value) parts.push(rp.value);
-          if (rp.marker) parts.push(rp.marker);
-        }
-        parts.push(keyword);
-      } else {
-        // SVO/VSO: keyword then roles (with markers before values)
-        parts.push(keyword);
-        for (const rp of roleParts) {
-          if (rp.marker) parts.push(rp.marker);
-          if (rp.value) parts.push(rp.value);
-        }
-      }
+  // Order roles by their declared positions, using the SAME comparator pattern
+  // generation uses. Rendering in declaration order instead would produce a
+  // surface the generated pattern cannot re-parse whenever the two disagree.
+  const ordered = sortRolesByWordOrder([...schema.roles], isSOV ? 'SOV' : 'SVO');
 
-      return buildPhrase(...parts);
-    },
-  };
+  // Roles rendered before the verb, and (SOV only) after it.
+  const preVerb: string[] = [];
+  const postVerb: string[] = [];
+
+  for (const role of ordered) {
+    let value = extractRoleValue(node, role.role);
+    if (!value && role.default !== undefined) {
+      value = String(extractValue(role.default));
+    }
+    // A role with no value is skipped entirely — including its marker. Emitting
+    // the marker of an absent role produces dangling text ("analyze #content as",
+    // "#content として 分析"), which is never valid surface syntax. This applies to
+    // required roles too: a required role with no value is a malformed node, and
+    // a dangling marker is a worse rendering of it than simply leaving it out.
+    if (!value) continue;
+
+    if (role.quoteMultiword && /\s/.test(value) && !/^(["']).*\1$/.test(value)) {
+      value = `"${value}"`;
+    }
+
+    // Marker resolution, most specific first. `renderOverride` for this exact
+    // language is the most specific statement; `''` means "render this role
+    // bare" (a marker that exists only to help the parser). The `'*'` key is a
+    // blanket statement about the PROFILE default, so it ranks below a
+    // per-language markerOverride — which is how SQL's `get` renders bare in
+    // SVO languages while keeping its SOV source particles.
+    const markerText =
+      role.renderOverride?.[language] ??
+      role.markerOverride?.[language] ??
+      role.renderOverride?.['*'] ??
+      tables.markers[role.role]?.[language];
+
+    const markerPosition =
+      role.markerPositionOverride?.[language] ??
+      role.markerPosition ??
+      tables.markerPositions[role.role]?.[language] ??
+      (isSOV ? 'after' : 'before');
+
+    const bucket = isSOV && role.sovSlot === 'postVerb' ? postVerb : preVerb;
+    if (markerText && markerPosition === 'before') {
+      bucket.push(markerText, value);
+    } else if (markerText) {
+      bucket.push(value, markerText);
+    } else {
+      bucket.push(value);
+    }
+  }
+
+  return isSOV
+    ? buildPhrase(...preVerb, keyword, ...postVerb)
+    : buildPhrase(keyword, ...preVerb, ...postVerb);
 }

package/src/index.ts

@@ -107,6 +107,8 @@ export type {
   KeywordTable,
   MarkerTable,
   RendererConfig,
+  DomainRenderFn,
+  DomainRendererConfig,
 } from './generation/renderer';
 export {
   lookupKeyword,
@@ -115,6 +117,7 @@ export {
   buildTablesFromProfiles,
   detectWordOrders,
   createSchemaRenderer,
+  createDomainRenderer,
 } from './generation/renderer';
 
 // Diagnostics
@@ -133,6 +136,8 @@ export type {
   DSLConfig,
   MultilingualDSL,
   CodeGenerator,
+  DomainExtension,
+  ExtensionVocabulary,
   ValidationResult,
   CompileResult,
   DomainDescriptor,
@@ -145,7 +150,10 @@ export type {
   DispatcherOptions,
 } from './api';
 
-export { DomainRegistry, CrossDomainDispatcher } from './api';
+// `createMultilingualDSL` is the package's primary entry point, so it is
+// exported by name rather than reaching consumers only through `export * from
+// './api'` above.
+export { createMultilingualDSL, DomainRegistry, CrossDomainDispatcher } from './api';
 
 // Re-export helper functions
 export {

package/src/interfaces/value-extractor.ts

@@ -348,6 +348,56 @@ export class LatinExtendedIdentifierExtractor implements ValueExtractor {
   }
 }
 
+/**
+ * CSS selector extractor — keeps `#id` and `.class` a SINGLE token.
+ *
+ * Without it the sigil is split off as its own token and the role capture keeps
+ * only that sigil: `add .active to #button` parses with patient `"."` and
+ * destination `"#"`, silently, in every language. Five domain DSLs each carried
+ * a private copy of this class and four (learn, todo, sql, jsx) had none — this
+ * is the shared one; register it via `customExtractors`.
+ *
+ * The character after the sigil must be a letter, `_` or `-`: a CSS identifier
+ * cannot start with a digit, and refusing to claim a bare `.`/`#` leaves
+ * property access and other uses of those characters to the extractors that own
+ * them.
+ *
+ * The body is Unicode so diacritics survive (`.año`, not `.a`) but STOPS at Han,
+ * kana and Hangul. Those scripts are where the SOV languages write their
+ * particles, and a selector is written adjacent to them with no space:
+ * `#buttonに .activeを 追加` must yield `#button` + `に`, not a `#buttonに` that
+ * swallows the particle and takes the role marker with it.
+ */
+const SELECTOR_BODY_CHAR = /[\p{L}\p{N}_-]/u;
+const PARTICLE_SCRIPT_CHAR = /[\p{sc=Han}\p{sc=Hiragana}\p{sc=Katakana}\p{sc=Hangul}]/u;
+
+function isSelectorBodyChar(char: string): boolean {
+  return SELECTOR_BODY_CHAR.test(char) && !PARTICLE_SCRIPT_CHAR.test(char);
+}
+
+export class CssSelectorExtractor implements ValueExtractor {
+  readonly name = 'css-selector';
+
+  canExtract(input: string, position: number): boolean {
+    const char = input[position];
+    if (char !== '#' && char !== '.') return false;
+    const next = input[position + 1];
+    if (next === undefined) return false;
+    return (
+      next === '_' || next === '-' || (/\p{L}/u.test(next) && !PARTICLE_SCRIPT_CHAR.test(next))
+    );
+  }
+
+  extract(input: string, position: number): ExtractionResult | null {
+    let end = position + 1;
+    while (end < input.length && isSelectorBodyChar(input[end])) {
+      end++;
+    }
+    if (end === position + 1) return null;
+    return { value: input.slice(position, end), length: end - position };
+  }
+}
+
 /**
  * Whitespace extractor - handles spaces, tabs, newlines.
  */