@patterkit/ops 0.7.6 → 0.8.0

package/dist/index.d.ts

@@ -1,9 +1,153 @@
-import { ProjectFile, Scene, LocaleFile, AuthoringFile, Bundle, GameData, CoverageDriver, GrammaticalGender, DocumentationClass, DocLine } from '@patterkit/model';
+import { ProjectFile, Bundle, HostScopeRegistry, Scene, LocaleFile, AuthoringFile, GameData, CoverageDriver, GrammaticalGender, DocumentationClass, DocLine } from '@patterkit/model';
+import { NamedScopesFile, MergedScopes, ScopesIssue, ScopesCatalogueEntry, ScopesFile } from '@wildwinter/scoperegistry/scopes';
+export { GAME_SCOPES_DIR, GAME_SCOPES_FILE, serialiseScopesFile } from '@wildwinter/scoperegistry/scopes';
+import { ScopeDeclaration, ScopeRegistry } from '@wildwinter/scoperegistry';
 import { ValidationIssue } from '@patterkit/core';
 import { ConditionIssue } from '@patterkit/compiler';
 import { ChoiceOption } from '@patterkit/runtime';
 export { isUnsafeEntry } from '@wildwinter/toolkit/archive';
 
+/** One file write an op wants performed. `content` is full canonical file text. */
+interface PlannedWrite {
+    path: string;
+    content: string;
+}
+/**
+ * Commit planned writes to disk (UTF-8), creating parent directories. The PLAIN
+ * filesystem applier - for tests and no-VCS embedders only; product code (the
+ * CLI, Patterpad) routes through @patterkit/vcs so writes land correctly in a
+ * Perforce / locked workspace (spec §12).
+ */
+declare function applyWrites(writes: PlannedWrite[]): void;
+
+/** Patter's own file in the folder. */
+declare const PATTER_SCOPES_FILE = "patter.scopes.json";
+/** Who Patter's file says wrote it. */
+declare const PATTER_SCOPES_OWNER = "Patter";
+/** Who the game's own file says wrote it, when Patter is the first to create it. */
+declare const GAME_SCOPES_OWNER = "Game";
+/** A project's game scopes folder, read and merged. */
+interface GameScopes {
+    /** The folder, absolute. */
+    dir: string;
+    /** Every scopes file in it that parsed, by name. */
+    files: NamedScopesFile[];
+    /** The whole folder as one spec, with who declares each token. */
+    merged: MergedScopes;
+    /** Files that would not parse and tokens two files claim, each naming its file (absolute). */
+    issues: ScopesIssue[];
+    /** The text of `patter.scopes.json` as it was read, or undefined when there is none yet. */
+    patterText?: string;
+}
+/** Read and merge every `*.scopes.json` in a game scopes folder. */
+declare function readGameScopes(dir: string): GameScopes;
+/**
+ * Find and read a project's game scopes: the project's `gameScopes` override (relative to the project
+ * file's folder), else the walk-up from that folder. `missing` is the error for an override naming a
+ * folder that doesn't exist; no folder at all is not an error.
+ */
+declare function discoverGameScopes(root: string, project: ProjectFile): {
+    gameScopes?: GameScopes;
+    missing?: string;
+};
+/**
+ * The game's scopes files as a pack carries them (patterkit/design/shared-scopes.md, "Packs"): every
+ * `*.scopes.json` in the folder the loader would find, by name, as its text on disk, sorted by name.
+ * Empty when there is no folder (or the project names one that isn't there), so a pack is as it was.
+ * A file that won't parse travels too: the snapshot is the folder as it is, not as Patter reads it.
+ */
+declare function gameScopesSnapshot(root: string, project: ProjectFile): Array<{
+    fileName: string;
+    text: string;
+}>;
+/** Patter's scopes file for a project: its shared `@patter` properties, in declaration order. */
+declare function patterScopesFile(project: ProjectFile): ScopesFile;
+/**
+ * The write that brings `patter.scopes.json` up to date, or undefined when there is no folder or the
+ * file already says exactly this. Never creates the folder: only a folder that was found gets a file.
+ */
+declare function patterScopesWrite(project: ProjectFile, gameScopes: GameScopes | undefined): PlannedWrite | undefined;
+/** The warning `validate` gives when `patter.scopes.json` doesn't say what the project would write. */
+declare function patterScopesStale(project: ProjectFile, gameScopes: GameScopes | undefined): {
+    file: string;
+    message: string;
+} | undefined;
+/**
+ * The registry a PREVIEW builds its engine on, when the project has game scopes and the bundle names
+ * someone else's scope (`@story`, a game scope the project doesn't declare): every scope in the folder
+ * but Patter's, stood in from its declared defaults, plus the bundle's own host scopes, since an engine
+ * given a registry self-backs nothing. Undefined when a preview needs no stand-ins, so the engine makes
+ * its own registry exactly as before. Preview only: a game's registry holds the real engines.
+ */
+declare function previewRegistry(gameScopes: GameScopes | undefined, bundle: Bundle, into?: ScopeRegistry): ScopeRegistry | undefined;
+/**
+ * The scopes a coverage run can feed and must treat as the game's to write: the bundle's host scopes,
+ * and, where a preview stands other scopes in (`previewRegistry`), those too. Without a folder, just the
+ * bundle's host scopes, which are the project's own.
+ */
+declare function drivableScopes(loaded: {
+    gameScopes?: GameScopes;
+}, bundle: Bundle): Array<{
+    token: string;
+    declarations?: ScopeDeclaration[];
+}>;
+/** The tokens of `drivableScopes`. */
+declare const hostScopeTokens: (loaded: {
+    gameScopes?: GameScopes;
+}, bundle: Bundle) => Set<string>;
+/** The folder's properties for an expression editor's picker, every scope but Patter's own. */
+declare const gameScopesCatalogue: (gameScopes: GameScopes | undefined) => ScopesCatalogueEntry[];
+/** The folder's tokens, every one but Patter's own: an editor's parser must know them all. */
+declare const gameScopeTokens: (gameScopes: GameScopes | undefined) => string[];
+/**
+ * The host scopes World properties shows: the project's, with each one `game.scopes.json` declares
+ * taken from there (the shared file is the source; the project holds a synced copy), and the shared
+ * `@world` added when the project has none. Without a folder, the project's own.
+ */
+declare function worldSettingsScopes(project: ProjectFile, gameScopes: GameScopes | undefined): HostScopeRegistry | undefined;
+/**
+ * Save World properties where the project has a game scopes folder: the game's own scopes go to
+ * `game.scopes.json` FIRST (re-read just now, so another tool's edit since is kept, and every scope this
+ * project doesn't show is left exactly as it was), then the project keeps the same scopes as its synced
+ * copy, so it still compiles packed or checked out alone. Another engine's scope stays in the project
+ * only. Returns the write for the shared file (none when its text wouldn't change), and the project's
+ * host scopes; or an error when the shared file is there but won't parse, rather than overwrite it.
+ */
+declare function planWorldSave(project: ProjectFile, gameScopes: GameScopes, next: HostScopeRegistry | undefined): {
+    write?: PlannedWrite;
+    scopeRegistry?: HostScopeRegistry;
+    error?: string;
+};
+/**
+ * Merging a returned pack (patterkit/design/shared-scopes.md, "Packs"): the recipient's World edit comes
+ * back in the project's synced copy of the game's scopes, and the sender's `game.scopes.json` must take
+ * it, or the next save would sync the copy from the shared file and silently drop it. The scopes the
+ * returned project file declares differently from the base pack's are the ones the recipient changed
+ * (added, edited, or deleted); each goes to `game.scopes.json` as the MERGED project has it, through the
+ * World settings' own save, and every other scope in the file stays exactly as it is now. Nothing (no
+ * write) when the recipient changed none of the game's scopes; an error when the file won't parse.
+ */
+declare function planReturnedWorld(ours: ProjectFile, base: ProjectFile, theirs: ProjectFile, merged: ProjectFile, gameScopes: GameScopes): {
+    write?: PlannedWrite;
+    error?: string;
+};
+/**
+ * Where "Share scopes with other tools" suggests creating the folder: at the version-control root above
+ * the project (the first folder holding `.git`), else beside the project folder.
+ */
+declare function defaultGameScopesDir(root: string): string;
+/**
+ * Share a project's scopes with the game's other tools: create `game-scopes/` at `dir` with Patter's
+ * file and `game.scopes.json` holding the project's own game scopes (its host scopes, but not another
+ * engine's, which is that engine's to declare). The project keeps its copy. When the walk-up from the
+ * project would not find `dir`, the project names it (`gameScopes`), so it is found next time. Returns
+ * the writes (the folder comes with the first), and the project as it should now be saved.
+ */
+declare function planShareScopes(root: string, project: ProjectFile, dir: string): {
+    writes: PlannedWrite[];
+    project: ProjectFile;
+};
+
 interface LoadedProject {
     root: string;
     projectFile: string;
@@ -18,6 +162,11 @@ interface LoadedProject {
     authoring: AuthoringFile[];
     /** Source file of each entry in `authoring`, index-aligned. */
     authoringFiles: string[];
+    /** The game's shared scopes folder, read and merged, when the project has one (discovered by walking
+     *  up, or named by the project's `gameScopes`). Absent = the project works alone. */
+    gameScopes?: GameScopes;
+    /** The project names a game scopes folder (`gameScopes`) that doesn't exist: a project error. */
+    gameScopesMissing?: string;
 }
 /**
  * Find the nearest `*.patterproj` at or above `startPath` - one readdir per
@@ -54,24 +203,20 @@ declare function loadProjectLanding(startPath: string, opts?: {
 declare function applySceneOrder(scenes: Scene[], order: string[] | undefined): void;
 declare function loadProject(startPath: string): LoadedProject;
 
-/** One file write an op wants performed. `content` is full canonical file text. */
-interface PlannedWrite {
-    path: string;
-    content: string;
-}
-/**
- * Commit planned writes to disk (UTF-8), creating parent directories. The PLAIN
- * filesystem applier - for tests and no-VCS embedders only; product code (the
- * CLI, Patterpad) routes through @patterkit/vcs so writes land correctly in a
- * Perforce / locked workspace (spec §12).
- */
-declare function applyWrites(writes: PlannedWrite[]): void;
-
 /** A raw-bytes hygiene problem in one source file (repairable by `format`). */
 interface HygieneIssue {
     file: string;
     message: string;
 }
+/** A problem with the game's shared scopes folder, or between it and the project, anchored to a file. */
+interface GameScopesIssue {
+    file: string;
+    message: string;
+    /** "error" (a scopes file that won't parse, a token two files claim, an override that names no folder)
+     *  blocks a clean build; "warning" (Patter's file out of date, the project's copy of a game scope
+     *  differing from the shared file) does not. */
+    severity: "error" | "warning";
+}
 interface ValidateResult {
     structural: ValidationIssue[];
     conditions: ConditionIssue[];
@@ -89,6 +234,10 @@ interface ValidateResult {
     unresolvedMerges: HygieneIssue[];
     /** Patter shards on disk that the project does NOT contain - see `orphanShards`. */
     orphans: HygieneIssue[];
+    /** The game's shared scopes folder: its files, and how the project stands against them. Only the
+     *  errors count against `ok`. Empty when the project has no folder. */
+    gameScopes: GameScopesIssue[];
+    /** Only ERRORS count: a warning (another tool's scope, say) never fails a build. */
     ok: boolean;
 }
 /** Run structural + expression + interpolation + hygiene + bundle-staleness + merge validation. */
@@ -783,6 +932,9 @@ interface DocumentManifest {
     };
     /** Shard paths (relative, forward-slashed), sorted - the document's contents. */
     files: string[];
+    /** The game scopes files the pack carries as `game-scopes/<name>` entries, by name, sorted. Absent
+     *  when the project has no game scopes folder (or it holds none). */
+    gameScopes?: string[];
 }
 /** Pack a project's source shards into a `.patterpack` document (zip bytes). */
 declare function runPack(startPath: string): Promise<Buffer>;
@@ -852,8 +1004,16 @@ declare const AUTHORING_HANDLED: Set<string>;
 /** A document entry whose path escapes the target dir (rejected). */
 declare class UnsafeEntryError extends Error {
 }
+/** What unpacking a document plans: its shards, and its game scopes snapshot (empty for a pack with none,
+ *  which is every pack from before packs carried one). */
+interface UnpackResult {
+    /** The shards, under `targetDir`. */
+    shards: PlannedWrite[];
+    /** The game's scopes files, in `<targetDir>/game-scopes/`, where the new project finds them first. */
+    scopes: PlannedWrite[];
+}
 /** Unpack a `.patterpack` document (zip bytes) into planned writes under `targetDir`. */
-declare function runUnpack(bytes: Buffer | Uint8Array, targetDir: string): Promise<PlannedWrite[]>;
+declare function runUnpack(bytes: Buffer | Uint8Array, targetDir: string): Promise<UnpackResult>;
 /** One shard's outcome in a merge-unpack. */
 interface MergedShard {
     /** Relative path within the project. */
@@ -890,7 +1050,8 @@ interface ProvenanceCheck {
 }
 interface UnpackMergeResult {
     shards: MergedShard[];
-    /** Merged (and added) shard contents to write into the project. */
+    /** Merged (and added) shard contents to write into the project, and `game.scopes.json` when the
+     *  recipient changed the game's scopes (`gameScopes`). */
     writes: PlannedWrite[];
     /** `.patterconflict` sidecars for shards with conflicts. */
     sidecars: PlannedWrite[];
@@ -898,6 +1059,13 @@ interface UnpackMergeResult {
     warnings: number;
     /** Do the returned document, the base document and the target project agree on their project id? */
     provenance: ProvenanceCheck;
+    /** The recipient changed the game's scopes (World properties) and the project has a game scopes
+     *  folder: `path` is its `game.scopes.json`, which `writes` brings up to date, or, with `error`, the
+     *  file that won't parse and so was left alone. Absent otherwise. */
+    gameScopes?: {
+        path: string;
+        error?: string;
+    };
 }
 /**
  * Merge a RETURNED `.patterpack` document (`theirs`) back into the project at
@@ -919,4 +1087,4 @@ declare function classesForChannel(classes: DocumentationClass[], channel: strin
  */
 declare function resolveDocumentation(loaded: LoadedProject, channel: string): Map<string, DocLine[]>;
 
-export { AUTHORING_HANDLED, type ApplyStats, type BundlePosture, CONFLICT_SIDECAR, type CharacterReport, type Conflict, type ConflictKind, type CoverageAsyncHooks, type CoverageBeat, type CoverageHooks, type CoverageOptions, type CoverageReport, type DocumentManifest, type FormatResult, type HygieneIssue, type InitOptions, type InitResult, type InitVcs, type LoadedProject, type LocCatalog, type LocEntry, type LocaleReport, type MergeFileType, type MergeResult, type MergedShard, type PlannedWrite, type PlayEvent, type PlayOptions, type PlayOutcome, type PlayResult, type ProvenanceCheck, type ReplaceHit, type ReplaceOptions, type ReplacePlan, type ReportData, type ReportTotals, type ResolveEntry, SHARD_EXTENSIONS, type SceneReport, type ScriptDoc, type ScriptElement, type SearchFocus, type UnpackMergeResult, UnsafeEntryError, UnsupportedMergeError, type ValidateResult, type VoiceLine, type VoiceScript, type VoicedCounts, type WebExport, type WrittenCounts, applyLoc, applySceneOrder, applyWrites, bundleOutputPath, catalogToJson, catalogToPo, catalogToXlsx, classesForChannel, detectMergeType, extractLoc, findProjectFile, jsonToCatalog, listProjectTags, loadProject, loadProjectLanding, poToCatalog, proposeCoverageDrivers, reachabilityIssues, renderCoverageText, renderPlay, renderReportText, resolveDocumentation, resolveStart, runCoverage, runCoverageAsync, runExport, runExportFull, runExportHtml, runExportWeb, runFormat, runInit, runMerge, runPack, runPlay, runPropertyUsage, runReplace, runReport, runReportXlsx, runResolve, runScriptDoc, runSearch, runStatusBrowse, runTagBrowse, runUnpack, runUnpackMerge, runValidate, runVoiceScript, scanAudioStatus, sceneIdForShard, scriptToDocx, scriptToPdf, sidecarIssues, vcsConfigWrites, voiceScriptToXlsx, xlsxToCatalog };
+export { AUTHORING_HANDLED, type ApplyStats, type BundlePosture, CONFLICT_SIDECAR, type CharacterReport, type Conflict, type ConflictKind, type CoverageAsyncHooks, type CoverageBeat, type CoverageHooks, type CoverageOptions, type CoverageReport, type DocumentManifest, type FormatResult, GAME_SCOPES_OWNER, type GameScopes, type GameScopesIssue, type HygieneIssue, type InitOptions, type InitResult, type InitVcs, type LoadedProject, type LocCatalog, type LocEntry, type LocaleReport, type MergeFileType, type MergeResult, type MergedShard, PATTER_SCOPES_FILE, PATTER_SCOPES_OWNER, type PlannedWrite, type PlayEvent, type PlayOptions, type PlayOutcome, type PlayResult, type ProvenanceCheck, type ReplaceHit, type ReplaceOptions, type ReplacePlan, type ReportData, type ReportTotals, type ResolveEntry, SHARD_EXTENSIONS, type SceneReport, type ScriptDoc, type ScriptElement, type SearchFocus, type UnpackMergeResult, type UnpackResult, UnsafeEntryError, UnsupportedMergeError, type ValidateResult, type VoiceLine, type VoiceScript, type VoicedCounts, type WebExport, type WrittenCounts, applyLoc, applySceneOrder, applyWrites, bundleOutputPath, catalogToJson, catalogToPo, catalogToXlsx, classesForChannel, defaultGameScopesDir, detectMergeType, discoverGameScopes, drivableScopes, extractLoc, findProjectFile, gameScopeTokens, gameScopesCatalogue, gameScopesSnapshot, hostScopeTokens, jsonToCatalog, listProjectTags, loadProject, loadProjectLanding, patterScopesFile, patterScopesStale, patterScopesWrite, planReturnedWorld, planShareScopes, planWorldSave, poToCatalog, previewRegistry, proposeCoverageDrivers, reachabilityIssues, readGameScopes, renderCoverageText, renderPlay, renderReportText, resolveDocumentation, resolveStart, runCoverage, runCoverageAsync, runExport, runExportFull, runExportHtml, runExportWeb, runFormat, runInit, runMerge, runPack, runPlay, runPropertyUsage, runReplace, runReport, runReportXlsx, runResolve, runScriptDoc, runSearch, runStatusBrowse, runTagBrowse, runUnpack, runUnpackMerge, runValidate, runVoiceScript, scanAudioStatus, sceneIdForShard, scriptToDocx, scriptToPdf, sidecarIssues, vcsConfigWrites, voiceScriptToXlsx, worldSettingsScopes, xlsxToCatalog };