@rohal12/twee-ts 1.16.1 → 1.17.0

package/dist/index.d.cts

@@ -55,9 +55,9 @@ interface CompileToFileOptions extends CompileOptions {
   outFile: string;
 }
 interface WatchOptions extends CompileToFileOptions {
-  /** Called after each successful rebuild. */
+  /** Called after each build is written, including one whose diagnostics report errors. */
   onBuild?: (result: CompileResult) => void;
-  /** Called on build errors. */
+  /** Called when a build fails with a fatal error (nothing is written). */
   onError?: (error: Error) => void;
 }
 type Diagnostic = {
@@ -142,6 +142,35 @@ type ReadonlyStory = Readonly<Omit<Story, 'passages' | 'twine1' | 'twine2'>> & {
     readonly tagColors: ReadonlyMap<string, string>;
   };
 };
+type OmittingTag = 'Twine.private' | 'script' | 'stylesheet';
+type PassageOmission = {
+  readonly kind: 'special-name';
+  readonly name: 'StoryData' | 'StoryTitle';
+} | {
+  readonly kind: 'tag';
+  readonly tag: OmittingTag;
+} | {
+  readonly kind: 'empty-story-settings';
+};
+/** The output whose rules decide which passages a story emits as passages. */
+type PassageOutputTarget = 'twine1' | 'twine2';
+interface DecompileOptions {
+  /**
+   * Trim whitespace at both ends of passage text (and of the Twine 2 story stylesheet and script),
+   * as the Twee lexer does. When false, the stored text is kept exactly. Default: true.
+   */
+  readonly trim?: boolean;
+}
+interface InspectOptions {
+  /**
+   * Check link destinations against this output's passage rules. A link to a passage that the
+   * output leaves out (in Twine 2: `script`, `stylesheet` and `Twine.private` passages,
+   * StoryData, StoryTitle and an empty StorySettings; in Twine 1: `Twine.private` passages) is
+   * then a broken link, and says why. Without a target, a link is broken only when no passage
+   * has its name.
+   */
+  readonly target?: PassageOutputTarget;
+}
 interface StoryFormatInfo {
   id: string;
   filename: string;
@@ -242,10 +271,16 @@ export declare function compileToFile(options: CompileToFileOptions): Promise<Co
 /**
  * Compile with incremental caching support.
  * Plugins and advanced users can manage their own cache and changed-file tracking.
+ *
+ * Without `changedFiles`, a cached file is reused while its modification time is unchanged.
+ * With it, a file it names (by the path source discovery gives it, relative to the working
+ * directory) is always reparsed, whatever its modification time, and every other cached
+ * file is reused as it is.
  */
 export declare function compileIncremental(options: CompileOptions, cache: Map<string, FileCacheEntry>, changedFiles?: ReadonlySet<string>): Promise<CompileResult>;
 /**
- * Watch for file changes and recompile.
+ * Watch for file changes and recompile. Every build is written to `outFile`, including
+ * one whose diagnostics report errors.
  */
 export declare function watch(options: WatchOptions): Promise<AbortController>;
 //#endregion
@@ -268,10 +303,15 @@ interface StoryMap {
    * Parses `[[target]]`, `[[display->target]]`, `[[target<-display]]`, `[[display|target]]`,
    * each with or without a setter (`[[display|target][$x to 1]]`), and SugarCube's
    * `<<goto "target">>` / `<<link "display" "target">>`, read as SugarCube 2 reads them
-   * (see `sugarcube-macros.ts`). Links and calls in comments are not read.
+   * (see `sugarcube-macros.ts`). Links and calls in comments are not read. A script passage is
+   * read for links only in its strings; a stylesheet passage (including a loaded `.css` file) is
+   * CSS and links to nothing.
    */
   links: Map<string, string[]>;
-  /** Broken links: `{ from, to }` pairs where `to` doesn't exist as a passage. */
+  /**
+   * Broken links: `{ from, to }` pairs where `to` doesn't exist as a passage, or, with a `target`
+   * (see `InspectOptions`), where that output leaves the `to` passage out (`omission` says why).
+   */
   brokenLinks: BrokenLink[];
   /** Story passages with no outgoing links (potential dead ends). */
   deadEnds: string[];
@@ -283,6 +323,11 @@ interface StoryMap {
 interface BrokenLink {
   from: string;
   to: string;
+  /**
+   * Set when a passage named `to` exists, but the inspected output leaves it out of the story
+   * (only with a `target`): why it is left out. Absent when no passage has the name.
+   */
+  omission?: PassageOmission;
 }
 /**
  * Inspect a story and return its full structural map.
@@ -299,8 +344,13 @@ interface BrokenLink {
  * expect(map.brokenLinks).toEqual([]);
  * expect(map.deadEnds).not.toContain('Start');
  * ```
+ *
+ * By default, a link is broken only when no passage has its name. Pass a `target` to check links
+ * against what that output emits: `storyInspect(result.story, { target: 'twine2' })` also reports
+ * links to passages Twine 2 output leaves out, such as script, stylesheet and `Twine.private`
+ * passages.
  */
-export declare function storyInspect(story: ReadonlyStory): StoryMap;
+export declare function storyInspect(story: ReadonlyStory, options?: InspectOptions): StoryMap;
 //#endregion
 //#region src/story.d.ts
 /**
@@ -327,8 +377,9 @@ interface DecompileResult {
 }
 /**
  * Parse a Twine 2 or Twine 1 compiled HTML file back into a Story model.
+ * Tweego always trims passage text; here `trim: false` keeps it exactly, as for Twee sources.
  */
-export declare function decompileHTML(html: string): DecompileResult;
+export declare function decompileHTML(html: string, options?: DecompileOptions): DecompileResult;
 //#endregion
 //#region src/lint.d.ts
 interface LintResult {
@@ -348,7 +399,11 @@ interface LintResult {
   storyPassages: number;
   /** Info/special passage count. */
   infoPassages: number;
-  /** Broken links: link targets that don't exist as passages. */
+  /**
+   * Broken links: link targets that don't exist as passages, or that Twine 2 output leaves out
+   * (script, stylesheet and `Twine.private` passages, StoryData, StoryTitle, an empty
+   * StorySettings); for those, `omission` says why.
+   */
   brokenLinks: BrokenLink[];
   /** Story passages with no outgoing links. */
   deadEnds: string[];
@@ -358,7 +413,9 @@ interface LintResult {
 /**
  * Lint a story: compile without output rendering, then inspect structure.
  * Uses JSON output mode internally to avoid format resolution, so it checks
- * the starting passage itself, against the Twine 2 passage rules.
+ * the starting passage itself, against the Twine 2 passage rules. Link
+ * destinations are checked against the same rules: a link to a passage that
+ * Twine 2 output leaves out is broken.
  */
 export declare function lint(options: Omit<CompileOptions, 'outputMode'>): Promise<LintResult>;
 /**
@@ -501,4 +558,4 @@ export declare function getCacheSize(): {
   count: number;
 };
 //#endregion
-export type { BrokenLink, CachedFormatEntry, CompileOptions, CompileResult, CompileStats, CompileToFileOptions, DecompileResult, Diagnostic, FileCacheEntry, IFID, InlineSource, LexerItem, LintResult, OutputMode, Passage, PassageMetadata, ReadonlyPassage, ReadonlyStory, SFAIndex, SFAIndexEntry, SourceInput, SourceLocation, Story, StoryFormatInfo, StoryMap, TweeTsConfig, WatchOptions, WordCountMethod };
+export type { BrokenLink, CachedFormatEntry, CompileOptions, CompileResult, CompileStats, CompileToFileOptions, DecompileOptions, DecompileResult, Diagnostic, FileCacheEntry, IFID, InlineSource, InspectOptions, LexerItem, LintResult, OmittingTag, OutputMode, Passage, PassageMetadata, PassageOmission, PassageOutputTarget, ReadonlyPassage, ReadonlyStory, SFAIndex, SFAIndexEntry, SourceInput, SourceLocation, Story, StoryFormatInfo, StoryMap, TweeTsConfig, WatchOptions, WordCountMethod };

package/dist/index.d.ts

@@ -55,9 +55,9 @@ interface CompileToFileOptions extends CompileOptions {
   outFile: string;
 }
 interface WatchOptions extends CompileToFileOptions {
-  /** Called after each successful rebuild. */
+  /** Called after each build is written, including one whose diagnostics report errors. */
   onBuild?: (result: CompileResult) => void;
-  /** Called on build errors. */
+  /** Called when a build fails with a fatal error (nothing is written). */
   onError?: (error: Error) => void;
 }
 type Diagnostic = {
@@ -142,6 +142,35 @@ type ReadonlyStory = Readonly<Omit<Story, 'passages' | 'twine1' | 'twine2'>> & {
     readonly tagColors: ReadonlyMap<string, string>;
   };
 };
+type OmittingTag = 'Twine.private' | 'script' | 'stylesheet';
+type PassageOmission = {
+  readonly kind: 'special-name';
+  readonly name: 'StoryData' | 'StoryTitle';
+} | {
+  readonly kind: 'tag';
+  readonly tag: OmittingTag;
+} | {
+  readonly kind: 'empty-story-settings';
+};
+/** The output whose rules decide which passages a story emits as passages. */
+type PassageOutputTarget = 'twine1' | 'twine2';
+interface DecompileOptions {
+  /**
+   * Trim whitespace at both ends of passage text (and of the Twine 2 story stylesheet and script),
+   * as the Twee lexer does. When false, the stored text is kept exactly. Default: true.
+   */
+  readonly trim?: boolean;
+}
+interface InspectOptions {
+  /**
+   * Check link destinations against this output's passage rules. A link to a passage that the
+   * output leaves out (in Twine 2: `script`, `stylesheet` and `Twine.private` passages,
+   * StoryData, StoryTitle and an empty StorySettings; in Twine 1: `Twine.private` passages) is
+   * then a broken link, and says why. Without a target, a link is broken only when no passage
+   * has its name.
+   */
+  readonly target?: PassageOutputTarget;
+}
 interface StoryFormatInfo {
   id: string;
   filename: string;
@@ -242,10 +271,16 @@ export declare function compileToFile(options: CompileToFileOptions): Promise<Co
 /**
  * Compile with incremental caching support.
  * Plugins and advanced users can manage their own cache and changed-file tracking.
+ *
+ * Without `changedFiles`, a cached file is reused while its modification time is unchanged.
+ * With it, a file it names (by the path source discovery gives it, relative to the working
+ * directory) is always reparsed, whatever its modification time, and every other cached
+ * file is reused as it is.
  */
 export declare function compileIncremental(options: CompileOptions, cache: Map<string, FileCacheEntry>, changedFiles?: ReadonlySet<string>): Promise<CompileResult>;
 /**
- * Watch for file changes and recompile.
+ * Watch for file changes and recompile. Every build is written to `outFile`, including
+ * one whose diagnostics report errors.
  */
 export declare function watch(options: WatchOptions): Promise<AbortController>;
 //#endregion
@@ -268,10 +303,15 @@ interface StoryMap {
    * Parses `[[target]]`, `[[display->target]]`, `[[target<-display]]`, `[[display|target]]`,
    * each with or without a setter (`[[display|target][$x to 1]]`), and SugarCube's
    * `<<goto "target">>` / `<<link "display" "target">>`, read as SugarCube 2 reads them
-   * (see `sugarcube-macros.ts`). Links and calls in comments are not read.
+   * (see `sugarcube-macros.ts`). Links and calls in comments are not read. A script passage is
+   * read for links only in its strings; a stylesheet passage (including a loaded `.css` file) is
+   * CSS and links to nothing.
    */
   links: Map<string, string[]>;
-  /** Broken links: `{ from, to }` pairs where `to` doesn't exist as a passage. */
+  /**
+   * Broken links: `{ from, to }` pairs where `to` doesn't exist as a passage, or, with a `target`
+   * (see `InspectOptions`), where that output leaves the `to` passage out (`omission` says why).
+   */
   brokenLinks: BrokenLink[];
   /** Story passages with no outgoing links (potential dead ends). */
   deadEnds: string[];
@@ -283,6 +323,11 @@ interface StoryMap {
 interface BrokenLink {
   from: string;
   to: string;
+  /**
+   * Set when a passage named `to` exists, but the inspected output leaves it out of the story
+   * (only with a `target`): why it is left out. Absent when no passage has the name.
+   */
+  omission?: PassageOmission;
 }
 /**
  * Inspect a story and return its full structural map.
@@ -299,8 +344,13 @@ interface BrokenLink {
  * expect(map.brokenLinks).toEqual([]);
  * expect(map.deadEnds).not.toContain('Start');
  * ```
+ *
+ * By default, a link is broken only when no passage has its name. Pass a `target` to check links
+ * against what that output emits: `storyInspect(result.story, { target: 'twine2' })` also reports
+ * links to passages Twine 2 output leaves out, such as script, stylesheet and `Twine.private`
+ * passages.
  */
-export declare function storyInspect(story: ReadonlyStory): StoryMap;
+export declare function storyInspect(story: ReadonlyStory, options?: InspectOptions): StoryMap;
 //#endregion
 //#region src/story.d.ts
 /**
@@ -327,8 +377,9 @@ interface DecompileResult {
 }
 /**
  * Parse a Twine 2 or Twine 1 compiled HTML file back into a Story model.
+ * Tweego always trims passage text; here `trim: false` keeps it exactly, as for Twee sources.
  */
-export declare function decompileHTML(html: string): DecompileResult;
+export declare function decompileHTML(html: string, options?: DecompileOptions): DecompileResult;
 //#endregion
 //#region src/lint.d.ts
 interface LintResult {
@@ -348,7 +399,11 @@ interface LintResult {
   storyPassages: number;
   /** Info/special passage count. */
   infoPassages: number;
-  /** Broken links: link targets that don't exist as passages. */
+  /**
+   * Broken links: link targets that don't exist as passages, or that Twine 2 output leaves out
+   * (script, stylesheet and `Twine.private` passages, StoryData, StoryTitle, an empty
+   * StorySettings); for those, `omission` says why.
+   */
   brokenLinks: BrokenLink[];
   /** Story passages with no outgoing links. */
   deadEnds: string[];
@@ -358,7 +413,9 @@ interface LintResult {
 /**
  * Lint a story: compile without output rendering, then inspect structure.
  * Uses JSON output mode internally to avoid format resolution, so it checks
- * the starting passage itself, against the Twine 2 passage rules.
+ * the starting passage itself, against the Twine 2 passage rules. Link
+ * destinations are checked against the same rules: a link to a passage that
+ * Twine 2 output leaves out is broken.
  */
 export declare function lint(options: Omit<CompileOptions, 'outputMode'>): Promise<LintResult>;
 /**
@@ -501,4 +558,4 @@ export declare function getCacheSize(): {
   count: number;
 };
 //#endregion
-export type { BrokenLink, CachedFormatEntry, CompileOptions, CompileResult, CompileStats, CompileToFileOptions, DecompileResult, Diagnostic, FileCacheEntry, IFID, InlineSource, LexerItem, LintResult, OutputMode, Passage, PassageMetadata, ReadonlyPassage, ReadonlyStory, SFAIndex, SFAIndexEntry, SourceInput, SourceLocation, Story, StoryFormatInfo, StoryMap, TweeTsConfig, WatchOptions, WordCountMethod };
+export type { BrokenLink, CachedFormatEntry, CompileOptions, CompileResult, CompileStats, CompileToFileOptions, DecompileOptions, DecompileResult, Diagnostic, FileCacheEntry, IFID, InlineSource, InspectOptions, LexerItem, LintResult, OmittingTag, OutputMode, Passage, PassageMetadata, PassageOmission, PassageOutputTarget, ReadonlyPassage, ReadonlyStory, SFAIndex, SFAIndexEntry, SourceInput, SourceLocation, Story, StoryFormatInfo, StoryMap, TweeTsConfig, WatchOptions, WordCountMethod };