@patterkit/ops 0.3.6 → 0.5.0

package/dist/index.d.ts

@@ -80,17 +80,25 @@ interface ValidateResult {
     hygiene: HygieneIssue[];
     /** Committed `.patterc` bundles whose hash no longer matches source (spec §11). */
     staleBundles: HygieneIssue[];
+    /** Conditions provably unsatisfiable over monotonic latches (reachability.ts). WARNINGS, and
+     *  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). */
     unresolvedMerges: HygieneIssue[];
+    /** Patter shards on disk that the project does NOT contain - see `orphanShards`. */
+    orphans: HygieneIssue[];
     ok: boolean;
 }
 /** Run structural + expression + interpolation + hygiene + bundle-staleness + merge validation. */
 declare function runValidate(loaded: LoadedProject): ValidateResult;
 
-/** Compile a loaded project to the runtime bundle, applying its build localisation mode (spec §11):
- *  "embedded" (default) keeps every locale's strings inline; "ids" strips them so the runtime emits beat
- *  IDs (the game localises). `sourceDebug` keeps only the SOURCE locale, embedded for debug playback and
- *  flagged so the runtime warns it is not a shippable build. */
+/**
+ * Conditions that can never hold, as warnings. Empty for a project with no monotonic latches, which is
+ * most of them: this only speaks when it can prove an ordering.
+ */
+declare function reachabilityIssues(loaded: LoadedProject, compiled?: Bundle): ConditionIssue[];
+
 declare function runExport(loaded: LoadedProject): Bundle;
 /** Compile WITHOUT the localisation-mode transform - the full bundle with every locale inline. Used where
  *  the host needs all strings regardless of build mode (e.g. Patterpad's Play window + Export Localisation). */
@@ -213,6 +221,19 @@ interface CoverageBeat {
     /** Set on a never-reached beat that is gated on a host-scope ref (`@world.x`) nothing writes and no
      *  driver provides, i.e. it may just need an input, not be truly dead. Lists the offending refs. */
     needsInput?: string[];
+    /** Set on a never-reached beat gated on a ref that IS written, but ONLY by content that was itself
+     *  never reached: the beat is dead at one remove, and the gate is not the real question. Names the
+     *  ref and the beats that witness its only writers, so two mysteries collapse into one. Absent
+     *  whenever the chain cannot be refuted (see `writerSites` in the analysis). */
+    blockedBy?: BlockedGate[];
+}
+/** A gate on a never-reached beat whose every writer was itself never reached. */
+interface BlockedGate {
+    /** The gating ref, at the granularity the condition reads it: `@world.alarm`, or `@world.mood:armed`
+     *  for a single flag of a flags property. */
+    ref: string;
+    /** Beat ids witnessing the writers: content that would have to play for this gate to be written. */
+    writers: string[];
 }
 /** A choice that ran DRY during the coverage run: at some point it had no takeable option and no eligible
  *  fallback, so it fell through silently and the flow carried on past it. This is easy to author by
@@ -797,6 +818,24 @@ declare class UnsupportedMergeError extends Error {
 }
 type Obj = Record<string, unknown>;
 /** Detect the merge type from a file's `schema` tag. */
+/** The conflict sidecar's extension. One constant, because three callers now look for it. */
+declare const CONFLICT_SIDECAR = ".patterconflict";
+/**
+ * Turn a set of lingering `.patterconflict` paths into the issues that STOP work.
+ *
+ * The rule is patter-merge.md §3.6: a merged shard is valid canonical source with conflicted values
+ * resolved provisionally to OURS, so an unresolved merge cannot be allowed to reach CI or an export.
+ * That was stated in the design and enforced in exactly one place - `validate` - while `export` and
+ * `pack` never looked. Pack is the worse of the two: a pack carries shards but NOT sidecars, so
+ * sending one hands the recipient your side of a disagreement with nothing to say it was in dispute.
+ *
+ * It lives here, beside the sentence it enforces, because three call sites each re-deciding what a
+ * lingering sidecar means is how the rule drifted out of the code in the first place.
+ */
+declare function sidecarIssues(sidecarPaths: readonly string[]): Array<{
+    file: string;
+    message: string;
+}>;
 declare function detectMergeType(file: {
     schema?: unknown;
 }): MergeFileType;
@@ -804,6 +843,10 @@ declare function detectMergeType(file: {
 declare function runMerge(base: Obj, ours: Obj, theirs: Obj, opts?: {
     type?: MergeFileType;
 }): MergeResult;
+/** 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>;
 
 /** A document entry whose path escapes the target dir (rejected). */
 declare class UnsafeEntryError extends Error {
@@ -887,4 +930,4 @@ declare function classesForChannel(classes: DocumentationClass[], channel: strin
  */
 declare function resolveDocumentation(loaded: LoadedProject, channel: string): Map<string, DocLine[]>;
 
-export { type ApplyStats, type BundlePosture, 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, isUnsafeEntry, jsonToCatalog, listProjectTags, loadProject, loadProjectLanding, poToCatalog, proposeCoverageDrivers, 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, 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, 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, isUnsafeEntry, 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 };