@rohal12/twee-ts 1.11.0 → 1.13.0

package/dist/index.d.cts

@@ -54,17 +54,23 @@ interface WatchOptions extends CompileToFileOptions {
     /** Called on build errors. */
     onError?: (error: Error) => void;
 }
-interface Diagnostic {
-    level: 'warning' | 'error';
+type Diagnostic = {
+    level: 'warning';
     message: string;
     file?: string;
     line?: number;
-}
+} | {
+    level: 'error';
+    message: string;
+    file?: string;
+    line?: number;
+    fatal?: boolean;
+};
 interface CompileResult {
     /** The compiled output string (HTML, Twee, JSON, etc.). */
     output: string;
-    /** The parsed story model. */
-    story: Story;
+    /** The parsed story model (read-only after compilation). */
+    story: ReadonlyStory;
     /** The format used for compilation (undefined for non-HTML modes). */
     format?: StoryFormatInfo;
     /** Collected diagnostics. */
@@ -94,6 +100,9 @@ interface Passage {
     metadata?: PassageMetadata;
     source?: SourceLocation;
 }
+type IFID = string & {
+    readonly __brand: 'IFID';
+};
 interface Twine1Metadata {
     settings: Map<string, string>;
 }
@@ -108,12 +117,25 @@ interface Twine2Metadata {
 }
 interface Story {
     name: string;
-    ifid: string;
+    ifid: IFID;
     passages: Passage[];
-    legacyIFID: string;
+    legacyIFID: IFID;
     twine1: Twine1Metadata;
     twine2: Twine2Metadata;
 }
+type ReadonlyPassage = Readonly<Passage> & {
+    readonly tags: readonly string[];
+};
+type ReadonlyStory = Readonly<Omit<Story, 'passages' | 'twine1' | 'twine2'>> & {
+    readonly passages: readonly ReadonlyPassage[];
+    readonly twine1: Readonly<Omit<Twine1Metadata, 'settings'>> & {
+        readonly settings: ReadonlyMap<string, string>;
+    };
+    readonly twine2: Readonly<Omit<Twine2Metadata, 'options' | 'tagColors'>> & {
+        readonly options: ReadonlyMap<string, boolean>;
+        readonly tagColors: ReadonlyMap<string, string>;
+    };
+};
 interface StoryFormatInfo {
     id: string;
     filename: string;
@@ -138,15 +160,16 @@ interface Twine2FormatJSON {
     url?: string;
     license?: string;
 }
-declare const enum ItemType {
-    Error = 0,
-    EOF = 1,
-    Header = 2,
-    Name = 3,
-    Tags = 4,
-    Metadata = 5,
-    Content = 6
-}
+declare const ItemType: {
+    readonly Error: 0;
+    readonly EOF: 1;
+    readonly Header: 2;
+    readonly Name: 3;
+    readonly Tags: 4;
+    readonly Metadata: 5;
+    readonly Content: 6;
+};
+type ItemType = (typeof ItemType)[keyof typeof ItemType];
 interface LexerItem {
     type: ItemType;
     line: number;
@@ -273,7 +296,38 @@ interface BrokenLink {
  * expect(map.deadEnds).not.toContain('Start');
  * ```
  */
-declare function storyInspect(story: Story): StoryMap;
+declare function storyInspect(story: ReadonlyStory): StoryMap;
+
+/**
+ * Story model + StoryData JSON marshal/unmarshal.
+ * Ported from story.go + storydata.go.
+ */
+
+/**
+ * Builder that separates the mutable construction phase from the immutable consumption phase.
+ * During construction, the internal `Story` is mutable via `add()` and direct access.
+ * After `build()`, the story is returned as `ReadonlyStory`.
+ */
+declare class StoryBuilder {
+    /** The mutable story, accessible during construction for loader functions. */
+    readonly story: Story;
+    constructor();
+    /** Add a passage, handling special passages (StoryData, StoryTitle, etc.). */
+    add(passage: Passage, diagnostics: Diagnostic[]): void;
+    /** Check if a passage name exists. */
+    has(name: string): boolean;
+    /** Finalize and return the story as read-only. */
+    build(): ReadonlyStory;
+}
+
+interface DecompileResult {
+    story: Story;
+    diagnostics: Diagnostic[];
+}
+/**
+ * Parse a Twine 2 or Twine 1 compiled HTML file back into a Story model.
+ */
+declare function decompileHTML(html: string): DecompileResult;
 
 /**
  * Lint mode: compile + inspect story structure without producing output.
@@ -392,7 +446,9 @@ declare function parseSemver(v: string): [number, number, number] | null;
 declare function semverCompare(a: [number, number, number], b: [number, number, number]): number;
 
 /** Generate a new IFID (UUID v4, uppercase). */
-declare function generateIFID(): string;
+declare function generateIFID(): IFID;
+/** Validate and brand an IFID string. Throws on invalid input. */
+declare function createIFID(value: string): IFID;
 /**
  * Validate an IFID string.
  * Accepts both bare UUIDs and UUID://...// wrapped format.
@@ -442,4 +498,4 @@ declare function getCacheSize(): {
     count: number;
 };
 
-export { type BrokenLink, CONFIG_FILENAME, type CachedFormatEntry, type CompileOptions, type CompileResult, type CompileStats, type CompileToFileOptions, type Diagnostic, type FileCacheEntry, type InlineSource, ItemType, type LexerItem, type LintResult, type OutputMode, type Passage, type PassageMetadata, type SFAIndex, type SFAIndexEntry, type SourceInput, type SourceLocation, type Story, type StoryFormatInfo, type StoryMap, TweeLexer, type TweeTsConfig, TweeTsError, type WatchOptions, type WordCountMethod, applyTagAliases, clearCachedFormats, compile, compileIncremental, compileToFile, discoverCachedFormats, discoverFormats, fetchAndCacheFormat, fetchDirectFormat, formatLintReport, generateIFID, getCacheDir, getCacheSize, getFormatSearchDirs, lint, listCachedFormats, loadConfig, loadConfigFile, parseFormatJSON, parseSemver, parseTwee, resolveRemoteFormat, scaffoldConfig, semverCompare, storyInspect, tweeLexer, validateConfig, validateIFID, watch };
+export { type BrokenLink, CONFIG_FILENAME, type CachedFormatEntry, type CompileOptions, type CompileResult, type CompileStats, type CompileToFileOptions, type DecompileResult, type Diagnostic, type FileCacheEntry, type IFID, type InlineSource, ItemType, type LexerItem, type LintResult, type OutputMode, type Passage, type PassageMetadata, type ReadonlyPassage, type ReadonlyStory, type SFAIndex, type SFAIndexEntry, type SourceInput, type SourceLocation, type Story, StoryBuilder, type StoryFormatInfo, type StoryMap, TweeLexer, type TweeTsConfig, TweeTsError, type WatchOptions, type WordCountMethod, applyTagAliases, clearCachedFormats, compile, compileIncremental, compileToFile, createIFID, decompileHTML, discoverCachedFormats, discoverFormats, fetchAndCacheFormat, fetchDirectFormat, formatLintReport, generateIFID, getCacheDir, getCacheSize, getFormatSearchDirs, lint, listCachedFormats, loadConfig, loadConfigFile, parseFormatJSON, parseSemver, parseTwee, resolveRemoteFormat, scaffoldConfig, semverCompare, storyInspect, tweeLexer, validateConfig, validateIFID, watch };

package/dist/index.d.ts

@@ -54,17 +54,23 @@ interface WatchOptions extends CompileToFileOptions {
     /** Called on build errors. */
     onError?: (error: Error) => void;
 }
-interface Diagnostic {
-    level: 'warning' | 'error';
+type Diagnostic = {
+    level: 'warning';
     message: string;
     file?: string;
     line?: number;
-}
+} | {
+    level: 'error';
+    message: string;
+    file?: string;
+    line?: number;
+    fatal?: boolean;
+};
 interface CompileResult {
     /** The compiled output string (HTML, Twee, JSON, etc.). */
     output: string;
-    /** The parsed story model. */
-    story: Story;
+    /** The parsed story model (read-only after compilation). */
+    story: ReadonlyStory;
     /** The format used for compilation (undefined for non-HTML modes). */
     format?: StoryFormatInfo;
     /** Collected diagnostics. */
@@ -94,6 +100,9 @@ interface Passage {
     metadata?: PassageMetadata;
     source?: SourceLocation;
 }
+type IFID = string & {
+    readonly __brand: 'IFID';
+};
 interface Twine1Metadata {
     settings: Map<string, string>;
 }
@@ -108,12 +117,25 @@ interface Twine2Metadata {
 }
 interface Story {
     name: string;
-    ifid: string;
+    ifid: IFID;
     passages: Passage[];
-    legacyIFID: string;
+    legacyIFID: IFID;
     twine1: Twine1Metadata;
     twine2: Twine2Metadata;
 }
+type ReadonlyPassage = Readonly<Passage> & {
+    readonly tags: readonly string[];
+};
+type ReadonlyStory = Readonly<Omit<Story, 'passages' | 'twine1' | 'twine2'>> & {
+    readonly passages: readonly ReadonlyPassage[];
+    readonly twine1: Readonly<Omit<Twine1Metadata, 'settings'>> & {
+        readonly settings: ReadonlyMap<string, string>;
+    };
+    readonly twine2: Readonly<Omit<Twine2Metadata, 'options' | 'tagColors'>> & {
+        readonly options: ReadonlyMap<string, boolean>;
+        readonly tagColors: ReadonlyMap<string, string>;
+    };
+};
 interface StoryFormatInfo {
     id: string;
     filename: string;
@@ -138,15 +160,16 @@ interface Twine2FormatJSON {
     url?: string;
     license?: string;
 }
-declare const enum ItemType {
-    Error = 0,
-    EOF = 1,
-    Header = 2,
-    Name = 3,
-    Tags = 4,
-    Metadata = 5,
-    Content = 6
-}
+declare const ItemType: {
+    readonly Error: 0;
+    readonly EOF: 1;
+    readonly Header: 2;
+    readonly Name: 3;
+    readonly Tags: 4;
+    readonly Metadata: 5;
+    readonly Content: 6;
+};
+type ItemType = (typeof ItemType)[keyof typeof ItemType];
 interface LexerItem {
     type: ItemType;
     line: number;
@@ -273,7 +296,38 @@ interface BrokenLink {
  * expect(map.deadEnds).not.toContain('Start');
  * ```
  */
-declare function storyInspect(story: Story): StoryMap;
+declare function storyInspect(story: ReadonlyStory): StoryMap;
+
+/**
+ * Story model + StoryData JSON marshal/unmarshal.
+ * Ported from story.go + storydata.go.
+ */
+
+/**
+ * Builder that separates the mutable construction phase from the immutable consumption phase.
+ * During construction, the internal `Story` is mutable via `add()` and direct access.
+ * After `build()`, the story is returned as `ReadonlyStory`.
+ */
+declare class StoryBuilder {
+    /** The mutable story, accessible during construction for loader functions. */
+    readonly story: Story;
+    constructor();
+    /** Add a passage, handling special passages (StoryData, StoryTitle, etc.). */
+    add(passage: Passage, diagnostics: Diagnostic[]): void;
+    /** Check if a passage name exists. */
+    has(name: string): boolean;
+    /** Finalize and return the story as read-only. */
+    build(): ReadonlyStory;
+}
+
+interface DecompileResult {
+    story: Story;
+    diagnostics: Diagnostic[];
+}
+/**
+ * Parse a Twine 2 or Twine 1 compiled HTML file back into a Story model.
+ */
+declare function decompileHTML(html: string): DecompileResult;
 
 /**
  * Lint mode: compile + inspect story structure without producing output.
@@ -392,7 +446,9 @@ declare function parseSemver(v: string): [number, number, number] | null;
 declare function semverCompare(a: [number, number, number], b: [number, number, number]): number;
 
 /** Generate a new IFID (UUID v4, uppercase). */
-declare function generateIFID(): string;
+declare function generateIFID(): IFID;
+/** Validate and brand an IFID string. Throws on invalid input. */
+declare function createIFID(value: string): IFID;
 /**
  * Validate an IFID string.
  * Accepts both bare UUIDs and UUID://...// wrapped format.
@@ -442,4 +498,4 @@ declare function getCacheSize(): {
     count: number;
 };
 
-export { type BrokenLink, CONFIG_FILENAME, type CachedFormatEntry, type CompileOptions, type CompileResult, type CompileStats, type CompileToFileOptions, type Diagnostic, type FileCacheEntry, type InlineSource, ItemType, type LexerItem, type LintResult, type OutputMode, type Passage, type PassageMetadata, type SFAIndex, type SFAIndexEntry, type SourceInput, type SourceLocation, type Story, type StoryFormatInfo, type StoryMap, TweeLexer, type TweeTsConfig, TweeTsError, type WatchOptions, type WordCountMethod, applyTagAliases, clearCachedFormats, compile, compileIncremental, compileToFile, discoverCachedFormats, discoverFormats, fetchAndCacheFormat, fetchDirectFormat, formatLintReport, generateIFID, getCacheDir, getCacheSize, getFormatSearchDirs, lint, listCachedFormats, loadConfig, loadConfigFile, parseFormatJSON, parseSemver, parseTwee, resolveRemoteFormat, scaffoldConfig, semverCompare, storyInspect, tweeLexer, validateConfig, validateIFID, watch };
+export { type BrokenLink, CONFIG_FILENAME, type CachedFormatEntry, type CompileOptions, type CompileResult, type CompileStats, type CompileToFileOptions, type DecompileResult, type Diagnostic, type FileCacheEntry, type IFID, type InlineSource, ItemType, type LexerItem, type LintResult, type OutputMode, type Passage, type PassageMetadata, type ReadonlyPassage, type ReadonlyStory, type SFAIndex, type SFAIndexEntry, type SourceInput, type SourceLocation, type Story, StoryBuilder, type StoryFormatInfo, type StoryMap, TweeLexer, type TweeTsConfig, TweeTsError, type WatchOptions, type WordCountMethod, applyTagAliases, clearCachedFormats, compile, compileIncremental, compileToFile, createIFID, decompileHTML, discoverCachedFormats, discoverFormats, fetchAndCacheFormat, fetchDirectFormat, formatLintReport, generateIFID, getCacheDir, getCacheSize, getFormatSearchDirs, lint, listCachedFormats, loadConfig, loadConfigFile, parseFormatJSON, parseSemver, parseTwee, resolveRemoteFormat, scaffoldConfig, semverCompare, storyInspect, tweeLexer, validateConfig, validateIFID, watch };