@patterkit/ops 0.19.0 → 0.20.1

package/dist/index.d.ts

@@ -1,12 +1,13 @@
-import { ProjectFile, Bundle, HostScopeRegistry, Scene, LocaleFile, AuthoringFile, GameData, CoverageDriver, GrammaticalGender, GameDataNodeKind, DocumentationClass, DocLine, HandoffFile, Suggestion, LineBeat, Comment } from '@patterkit/model';
+import { ProjectFile, Bundle, HostScopeRegistry, Scene, LocaleFile, AuthoringFile, ExtensionShard, GameData, CoverageDriver, GrammaticalGender, GameDataNodeKind, DocumentationClass, DocLine, HandoffFile, Suggestion, LineBeat, Comment } 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 { ConditionIssue, ExtensionIssue, ExportInput } from '@patterkit/compiler';
 import { ChoiceOption, PlayError } from '@patterkit/runtime';
 import { Dialect } from '@wildwinter/expr';
 export { renameStageInExpression } from '@wildwinter/expr';
+import { Manifest } from '@wildwinter/toolkit/extensions';
 export { isUnsafeEntry } from '@wildwinter/toolkit/archive';
 
 /** One file write an op wants performed. `content` is full canonical file text. */
@@ -176,6 +177,30 @@ interface LoadedProject {
     gameScopes?: GameScopes;
     /** The project names a game scopes folder (`gameScopes`) that doesn't exist: a project error. */
     gameScopesMissing?: string;
+    /** The extensions' manifests, from `extensions/<id>.extension.json`, sorted by path. Read whether or not
+     *  the project takes them (`ProjectFile.extensions` says which it does). `manifest` is the parsed JSON as
+     *  it came, unchecked: the extension pass says whether it is sound. Empty after a landing load. */
+    manifests: LoadedManifest[];
+    /** The extension data shards (`.patterextension`, under `layout.extensions`), sorted by path. Empty after
+     *  a landing load. */
+    extensionShards: ExtensionShard[];
+    /** Source file of each entry in `extensionShards`, index-aligned. */
+    extensionShardFiles: string[];
+    /** Extension files that would not load (a manifest or a data shard that will not parse, or a shard of
+     *  the wrong shape). Unlike a scene, an extension's file never stops the project loading: it is left out
+     *  and said here, and its data left untouched on disk. */
+    extensionIssues: Array<{
+        file: string;
+        message: string;
+    }>;
+}
+/** One extension's manifest, as the project keeps it in `extensions/`. */
+interface LoadedManifest {
+    /** Absolute path: `<root>/extensions/<id>.extension.json`. */
+    path: string;
+    /** The file's stem, which names the extension it should be. */
+    id: string;
+    manifest: unknown;
 }
 /**
  * Find the nearest `*.patterproj` at or above `startPath` - one readdir per
@@ -239,7 +264,8 @@ interface ValidateResult {
      *  deliberately NOT part of `ok`: content is written in pieces, so a gate whose writer has not been
      *  authored yet is the normal state mid-work and must never fail a build. */
     reachability: ConditionIssue[];
-    /** Lingering `.patterconflict` sidecars - an unresolved merge (patter-merge.md §3.6). */
+    /** Lingering `.patterconflict` sidecars, and shards carrying the `unresolved` mark a merge writes into the
+     *  shard itself: an unresolved merge (patter-merge.md §3.6). */
     unresolvedMerges: HygieneIssue[];
     /** Patter shards on disk that the project does NOT contain - see `orphanShards`. */
     orphans: HygieneIssue[];
@@ -250,6 +276,12 @@ interface ValidateResult {
      *  error: the compile refuses it), and as warnings a shard for a scene the project lacks, one in a
      *  language it does not declare, or two shards for one scene and language. */
     localisation: GameScopesIssue[];
+    /** The project's Patter extensions: their manifests, the project's pins and settings, claims on gameData
+     *  fields, and every value in the extension data shards against its manifest (the compiler's
+     *  `extensionPass`), with an entry for a node that has gone reported per entry, and an extension file that
+     *  would not load. Errors count against `ok`, and export refuses them; warnings (a missing manifest, an
+     *  orphaned entry, a `.gitattributes` with no merge rule for the data) don't. */
+    extensions: ExtensionIssue[];
     /** Only ERRORS count: a warning (another tool's scope, say) never fails a build. */
     ok: boolean;
 }
@@ -363,6 +395,12 @@ declare function planBuild(loaded: LoadedProject, opts?: ExportOptions & {
  * line made a freshly exported bundle read as stale for ever, and coverage counted beats that never ship.
  */
 declare function compileLoaded(loaded: LoadedProject): Bundle;
+/**
+ * A loaded project's extension files, as the compiler's extension pass reads them: the manifests, and each
+ * data shard with its file. What is wrong with them is validate's to say (`extensionPass` over the same
+ * input); the compile never throws on it, and leaves an entry with an error out of the bundle.
+ */
+declare function loadedExtensions(loaded: LoadedProject): NonNullable<ExportInput["extensions"]>;
 /**
  * The default bundle location, relative to the project root, used when the project pins no
  * `export.bundle`: a SIBLING `patter-dist/` folder, not inside the project. On macOS the project folder is
@@ -682,6 +720,9 @@ interface FormatResult {
     write?: PlannedWrite;
     /** Not Patter source (not a shard by its extension), so left alone. */
     skipped?: boolean;
+    /** What else changed in it, for a person reading the output: an extension taken at a new version (the
+     *  project file), or the stages renamed in its data (an extension shard). */
+    notes?: string[];
 }
 /** Compute the canonical form of each file. Returns planned writes; writes nothing. */
 declare function runFormat(paths: string[]): FormatResult[];
@@ -1370,7 +1411,7 @@ interface PinPlan {
 declare function planPins(loaded: LoadedProject): PinPlan;
 
 /** The source-shard extensions a document carries (the merge-friendly truth). */
-declare const SHARD_EXTENSIONS: readonly [".patterflow", ".patterloc", ".patterx", ".patterproj"];
+declare const SHARD_EXTENSIONS: readonly [".patterflow", ".patterloc", ".patterx", ".patterproj", ".patterextension"];
 /** Manifest embedded at the document root - what this envelope is and contains. */
 interface DocumentManifest {
     schema: "patter/document@0";
@@ -1378,7 +1419,8 @@ interface DocumentManifest {
         id: string;
         name: string;
     };
-    /** Shard paths (relative, forward-slashed), sorted - the document's contents. */
+    /** Shard paths (relative, forward-slashed), sorted - the document's contents. The extensions' manifests
+     *  (`extensions/<id>.extension.json`) are among them: source the project compiles from. */
     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). */
@@ -1390,7 +1432,7 @@ interface DocumentManifest {
 /** Pack a project's source shards into a `.patterpack` document (zip bytes). */
 declare function runPack(startPath: string): Promise<Buffer>;
 
-type MergeFileType = "flow" | "loc" | "authoring" | "project";
+type MergeFileType = "flow" | "loc" | "authoring" | "project" | "extension";
 type ConflictKind = "both-changed" | "delete-vs-edit" | "no-timestamp" | "moved" | "added-both" | "structural";
 /** One unresolved 3-way conflict; provisional output is OURS. */
 interface Conflict {
@@ -1411,7 +1453,8 @@ interface Warning {
 }
 interface MergeResult {
     type: MergeFileType;
-    /** The merged model - valid canonical source; conflicts resolved to OURS. */
+    /** The merged model - valid canonical source; conflicts resolved to OURS, and named under `unresolved`
+     *  when there are any. */
     merged: Record<string, unknown>;
     conflicts: Conflict[];
     /** Advisory notes (e.g. both sides inserted at the same anchor, kept ours-then-theirs). */
@@ -1443,14 +1486,40 @@ declare function sidecarIssues(sidecarPaths: readonly string[]): Array<{
 declare function detectMergeType(file: {
     schema?: unknown;
 }): MergeFileType;
-/** 3-way merge BASE / OURS / THEIRS (parsed models). Dispatches by file type. */
+/**
+ * 3-way merge BASE / OURS / THEIRS (parsed models). Dispatches by file type.
+ *
+ * Every shard type carries the `unresolved` mark: a mark already on either side is carried until somebody
+ * resolves it (by removing it), the merge itself runs on the content alone, and this merge's own clashes
+ * are written in beside it. An extension shard merges field by field by its manifest's types when the
+ * caller passes the project's `manifest`; without one, each node's entry merges as one value, which is
+ * always safe.
+ */
 declare function runMerge(base: Obj, ours: Obj, theirs: Obj, opts?: {
     type?: MergeFileType;
+    manifest?: Manifest;
 }): MergeResult;
+/** A shard's text and where it is, for `unresolvedMarkIssues`. */
+interface ShardText {
+    file: string;
+    text: string;
+}
+/**
+ * The issues a shard carrying the `unresolved` mark raises: one per clash, naming the shard and where in
+ * it. Every shard type, read from the project's files as they are, so a mark is refused whatever shard it
+ * is in (ruled 2026-10-18). `validate`, `export`, and `pack` all ask, as they ask about sidecars. Pure: the
+ * caller reads the files.
+ */
+declare function unresolvedMarkIssues(files: readonly ShardText[]): Array<{
+    file: string;
+    message: string;
+}>;
 /** Every authoring key with a strategy of its own above. A key NOT here falls to the plain 3-way, which
  *  is coarse but never lossy; the set exists so the fallback does not re-merge what was already merged
  *  (an empty result from `setIf` must not be reconsidered as "unhandled"). */
 declare const AUTHORING_HANDLED: Set<string>;
+/** Every project key with a strategy of its own in `mergeProject`; anything else merges as a plain 3-way. */
+declare const PROJECT_HANDLED: Set<string>;
 
 /** A document entry whose path escapes the target dir, or that names a dot-file or dot-folder (rejected). */
 declare class UnsafeEntryError extends Error {
@@ -1536,6 +1605,11 @@ interface UnpackMergeResult {
     /** Handoff records the pack brought (relative paths): added, or with reimports from their side added to
      *  ours. Their writes are in `writes`. Absent when the pack carried none that changed anything. */
     handoffs?: string[];
+    /** Extension manifests (relative paths) the pack returned with content other than ours. Ours is kept: an
+     *  extension's manifest is the extension's own file, which a recipient never edits, so a difference means
+     *  the two sides had different versions of the extension, and taking one is a decision for the project
+     *  (and `patter format`, after). Theirs is taken only where we have none. Absent when none differ. */
+    manifestsKept?: string[];
 }
 /**
  * Merge a RETURNED `.patterpack` document (`theirs`) back into the project at
@@ -1557,6 +1631,71 @@ declare function classesForChannel(classes: DocumentationClass[], channel: strin
  */
 declare function resolveDocumentation(loaded: LoadedProject, channel: string): Map<string, DocLine[]>;
 
+/** Where a project keeps an extension's manifest. */
+declare const manifestPath: (projectDir: string, id: string) => string;
+/**
+ * The project's copy of an extension's manifest, when there is a sound one. Undefined when it's missing,
+ * won't parse, is itself mid-conflict, or has errors: the merge then takes each node's entry as one value,
+ * which is always safe (rule 4 of the merge).
+ */
+declare function readProjectManifest(projectDir: string, id: string): Manifest | undefined;
+/** A manifest's text as a merge may use it: undefined when it won't parse, is mid-conflict itself, or has
+ *  errors. For a host holding files as text (a pack, say). */
+declare function soundManifest(text: string): Manifest | undefined;
+/** A manifest lookup for a merge in one project folder. */
+declare const projectManifests: (projectDir: string) => (id: string) => Manifest | undefined;
+/** What taking new extension versions writes: each data shard with its renamed stages renamed, and the
+ *  project file with the new pins. */
+interface ExtensionUpgrade {
+    /** Absolute path to canonical content. */
+    readonly writes: Map<string, string>;
+    /** A line per change, for a person reading the output. */
+    readonly report: string[];
+    /** The same changes by the file each is in: the pins by the project file, the renames by shard. */
+    readonly notes: Map<string, string[]>;
+}
+/**
+ * Take every extension whose manifest is a version other than the project's pin (`patter format` on a
+ * project folder): the stages the manifest says it renamed are renamed in that extension's data, and the pin
+ * moves to the manifest's version, as one step (the proposal's "renamedStages" rule). A manifest that is
+ * missing or unsound is left alone, as its data is. Until it runs, a renamed stage still in the data
+ * compiles under its new name, with a warning.
+ */
+declare function planExtensionUpgrades(loaded: LoadedProject): ExtensionUpgrade;
+/** One extension data shard a cast rename rewrote. */
+interface CastKeyRewrite {
+    path: string;
+    shard: ExtensionShard;
+    /** How many keys and values it renamed. */
+    renamed: number;
+}
+/**
+ * A cast rename carried into extension data (ruling 8 of the extensions proposal): every map key whose key
+ * type is a reference to `cast`, and every reference value to `cast`, at any depth, that names an old name
+ * is rewritten to the new one. All at once, so a swap of two names lands as a swap. Only what the manifest
+ * declares is touched, so a shard whose manifest is missing or unsound is left as it is (a missing cast key
+ * stays the error validation says it is). A map that already holds the new name as a key keeps both keys,
+ * and validation reports the old one. Pure: returns the shards it changed, as new objects.
+ */
+declare function renameCastKeys(shards: ReadonlyArray<{
+    path: string;
+    shard: ExtensionShard;
+}>, manifests: ReadonlyArray<{
+    id: string;
+    manifest: unknown;
+}>, renames: ReadonlyMap<string, string>): CastKeyRewrite[];
+
+/** Old name -> new name, with no-ops and blanks dropped. Null when nothing is renamed. */
+declare function cleanCastRenames(renames: Record<string, string> | undefined): Map<string, string> | null;
+/** Rewrite the speaker of `scene`'s lines (option prompts among them) through `renames`, in place; all at
+ *  once, so a swap of two names lands as a swap. Returns how many lines changed. */
+declare function renameCastInScene(scene: Scene, renames: ReadonlyMap<string, string>): number;
+/** Move a record's `cast:` and `speaker:` keys through `renames`, in place, keeping their order; all at once.
+ *  A key whose new name is already there keeps its old name. True when anything moved. */
+declare function moveCastKeys<T>(record: Record<string, T>, renames: ReadonlyMap<string, string>): boolean;
+/** A project-level loc shard's strings moved through `renames`, in place. True when anything moved. */
+declare function renameCastStrings(loc: LocaleFile, renames: ReadonlyMap<string, string>): boolean;
+
 /** The project folder handoff records live in. */
 declare const HANDOFF_DIR = "handoffs";
 /** Where a handoff's record lives in the project at `root`. */
@@ -1799,4 +1938,4 @@ declare const REFUSE_MISSING_SHARE = 0.25;
 /** Plan an import. Reads the handoff record named in the document from the project. */
 declare function planEditableImport(loaded: LoadedProject, returned: ReturnedDoc, opts: ImportOptions): ImportPlan;
 
-export { AUDIO_MANIFEST_FILE, AUDIO_MANIFEST_SCHEMA, AUTHORING_HANDLED, type ApplyStats, type AudioEntry, type AudioRung, type AudioSnapshot, type BuildPlan, type BundlePosture, CONFLICT_SIDECAR, type CharacterReport, type Conflict, type ConflictKind, type ContentError, type CoverageAsyncHooks, type CoverageBeat, type CoverageHooks, type CoverageOptions, type CoverageOrder, type CoverageReport, type DecisionPlan, type DecisionResult, type DocumentManifest, type EditableScript, type EditableScriptOptions, type ExportOptions, type FormatResult, GAME_SCOPES_OWNER, type GameDataStageRenameResult, type GameScopes, type GameScopesIssue, HANDOFF_DIR, type HandoffIssue, type HygieneIssue, type ImportOptions, type ImportPlan, type ImportProblem, type ImportReport, type InitOptions, type InitResult, type InitVcs, type LoadedProject, type LocCatalog, type LocEntry, type LocaleReport, type MergeFileType, type MergeResult, type MergedShard, NotAPackError, type OpenSuggestion, PATTER_SCOPES_FILE, PATTER_SCOPES_OWNER, type PinPlan, type PinnedName, type PlannedWrite, type PlayEvent, type PlayOptions, type PlayOutcome, type PlayResult, type ProvenanceCheck, RARE_REACH_PCT, REFUSE_MISSING_SHARE, type Random, type ReadBox, type ReadComment, type ReadItem, type ReadMarker, type ReadParagraph, type ReadText, type ReplaceHit, type ReplaceOptions, type ReplacePlan, type ReportData, type ReportTotals, type ResolveEntry, type ReturnedDoc, SCRIPT_FONT_FILES, SCRIPT_FONT_PACKAGES, SHARD_EXTENSIONS, type SceneReport, type ScriptDoc, type ScriptElement, type ScriptFace, type SearchFocus, type StageRenameResult, type StageTarget, type SuggestionDecision, type TrackedChange, type UnpackMergeResult, type UnpackResult, UnsafeEntryError, UnsupportedMergeError, type ValidateResult, type VoiceLine, type VoiceScript, type VoicedCounts, type WebExport, type WrittenCounts, applyLoc, applySceneOrder, applySuggestionDecisions, applyWrites, audioFolderRungs, audioFoldersActive, audioManifest, audioManifestWrite, authoringPath, besideBundlePath, bundleOutputPath, catalogToJson, catalogToPo, catalogToXlsx, classesForChannel, compileLoaded, cueLabel, currentBundlePosture, defaultBundlePath, defaultGameScopesDir, detectMergeType, discoverGameScopes, drivableScopes, exportBlockers, exportEditableScript, extractLoc, findProjectFile, formatMarker, gameScopeTokens, gameScopesCatalogue, gameScopesSnapshot, handoffPath, handoffWrite, hostScopeTokens, issueMarkerCodes, jsonToCatalog, leastReachedFirst, listOpenSuggestions, listProjectTags, loadProject, loadProjectLanding, markerLength, newHandoffId, parseHandoff, patterScopesFile, patterScopesStale, patterScopesWrite, pickAudio, planBuild, planEditableImport, planPins, planReturnedWorld, planShareScopes, planWorldSave, poToCatalog, previewRegistry, projectStringSources, proposeCoverageDrivers, qualifierNamer, reachabilityIssues, readEditableDocx, readGameScopes, readHandoff, readHandoffs, readMarker, renameGameDataStage, renameStage, 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, scanAudio, scanAudioStatus, sceneIdForShard, scriptFontLicencePath, scriptFontLicences, scriptToDocx, scriptToPdf, serialiseHandoff, setCut, sidecarIssues, stageDialect, stageGateCount, staleParts, useScriptFontFiles, vcsConfigWrites, voiceScriptToXlsx, worldSettingsScopes, xlsxToCatalog };
+export { AUDIO_MANIFEST_FILE, AUDIO_MANIFEST_SCHEMA, AUTHORING_HANDLED, type ApplyStats, type AudioEntry, type AudioRung, type AudioSnapshot, type BuildPlan, type BundlePosture, CONFLICT_SIDECAR, type CastKeyRewrite, type CharacterReport, type Conflict, type ConflictKind, type ContentError, type CoverageAsyncHooks, type CoverageBeat, type CoverageHooks, type CoverageOptions, type CoverageOrder, type CoverageReport, type DecisionPlan, type DecisionResult, type DocumentManifest, type EditableScript, type EditableScriptOptions, type ExportOptions, type ExtensionUpgrade, type FormatResult, GAME_SCOPES_OWNER, type GameDataStageRenameResult, type GameScopes, type GameScopesIssue, HANDOFF_DIR, type HandoffIssue, type HygieneIssue, type ImportOptions, type ImportPlan, type ImportProblem, type ImportReport, type InitOptions, type InitResult, type InitVcs, type LoadedManifest, type LoadedProject, type LocCatalog, type LocEntry, type LocaleReport, type MergeFileType, type MergeResult, type MergedShard, NotAPackError, type OpenSuggestion, PATTER_SCOPES_FILE, PATTER_SCOPES_OWNER, PROJECT_HANDLED, type PinPlan, type PinnedName, type PlannedWrite, type PlayEvent, type PlayOptions, type PlayOutcome, type PlayResult, type ProvenanceCheck, RARE_REACH_PCT, REFUSE_MISSING_SHARE, type Random, type ReadBox, type ReadComment, type ReadItem, type ReadMarker, type ReadParagraph, type ReadText, type ReplaceHit, type ReplaceOptions, type ReplacePlan, type ReportData, type ReportTotals, type ResolveEntry, type ReturnedDoc, SCRIPT_FONT_FILES, SCRIPT_FONT_PACKAGES, SHARD_EXTENSIONS, type SceneReport, type ScriptDoc, type ScriptElement, type ScriptFace, type SearchFocus, type ShardText, type StageRenameResult, type StageTarget, type SuggestionDecision, type TrackedChange, type UnpackMergeResult, type UnpackResult, UnsafeEntryError, UnsupportedMergeError, type ValidateResult, type VoiceLine, type VoiceScript, type VoicedCounts, type WebExport, type WrittenCounts, applyLoc, applySceneOrder, applySuggestionDecisions, applyWrites, audioFolderRungs, audioFoldersActive, audioManifest, audioManifestWrite, authoringPath, besideBundlePath, bundleOutputPath, catalogToJson, catalogToPo, catalogToXlsx, classesForChannel, cleanCastRenames, compileLoaded, cueLabel, currentBundlePosture, defaultBundlePath, defaultGameScopesDir, detectMergeType, discoverGameScopes, drivableScopes, exportBlockers, exportEditableScript, extractLoc, findProjectFile, formatMarker, gameScopeTokens, gameScopesCatalogue, gameScopesSnapshot, handoffPath, handoffWrite, hostScopeTokens, issueMarkerCodes, jsonToCatalog, leastReachedFirst, listOpenSuggestions, listProjectTags, loadProject, loadProjectLanding, loadedExtensions, manifestPath, markerLength, moveCastKeys, newHandoffId, parseHandoff, patterScopesFile, patterScopesStale, patterScopesWrite, pickAudio, planBuild, planEditableImport, planExtensionUpgrades, planPins, planReturnedWorld, planShareScopes, planWorldSave, poToCatalog, previewRegistry, projectManifests, projectStringSources, proposeCoverageDrivers, qualifierNamer, reachabilityIssues, readEditableDocx, readGameScopes, readHandoff, readHandoffs, readMarker, readProjectManifest, renameCastInScene, renameCastKeys, renameCastStrings, renameGameDataStage, renameStage, 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, scanAudio, scanAudioStatus, sceneIdForShard, scriptFontLicencePath, scriptFontLicences, scriptToDocx, scriptToPdf, serialiseHandoff, setCut, sidecarIssues, soundManifest, stageDialect, stageGateCount, staleParts, unresolvedMarkIssues, useScriptFontFiles, vcsConfigWrites, voiceScriptToXlsx, worldSettingsScopes, xlsxToCatalog };