@rohal12/twee-ts 1.16.1 → 1.17.1

package/dist/index.d.cts

@@ -55,9 +55,12 @@ 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. A build
+   * that changes made while it ran have superseded is neither written nor reported.
+   */
   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 +145,37 @@ 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. The passages it leaves out also give no links, as their
+   * text never reaches the player, except script passages, which Twine 2 output runs. Without a
+   * target, every source passage gives links, and a link is broken only when no passage has its
+   * name.
+   */
+  readonly target?: PassageOutputTarget;
+}
 interface StoryFormatInfo {
   id: string;
   filename: string;
@@ -242,10 +276,18 @@ 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. Builds run one at a time: changes made during a
+ * build go into one follow-up build after it, and the superseded build is neither
+ * written nor reported.
  */
 export declare function watch(options: WatchOptions): Promise<AbortController>;
 //#endregion
@@ -268,10 +310,16 @@ 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. With a `target` (see `InspectOptions`), a passage that output leaves
+   * out links to nothing, except a script passage, which Twine 2 output runs.
    */
   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 +331,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 +352,15 @@ 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. With a target, passages that output leaves out also give no links (script passages
+ * excepted, as Twine 2 output runs them), so they report no broken links and keep no passage from
+ * being an orphan.
  */
-export declare function storyInspect(story: ReadonlyStory): StoryMap;
+export declare function storyInspect(story: ReadonlyStory, options?: InspectOptions): StoryMap;
 //#endregion
 //#region src/story.d.ts
 /**
@@ -327,8 +387,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 +409,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 +423,10 @@ 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, and a passage it leaves out (other than
+ * a script passage) gives no links.
  */
 export declare function lint(options: Omit<CompileOptions, 'outputMode'>): Promise<LintResult>;
 /**
@@ -442,7 +510,10 @@ export declare function semverCompare(a: [number, number, number], b: [number, n
 //#region src/ifid.d.ts
 /** Generate a new IFID (UUID v4, uppercase). */
 export declare function generateIFID(): IFID;
-/** Validate and brand an IFID string. Throws on invalid input. */
+/**
+ * Validate and brand an IFID string. Throws on invalid input.
+ * Returns the IFID in its stored form (see `normalizeIFID`).
+ */
 export declare function createIFID(value: string): IFID;
 /**
  * Validate an IFID string.
@@ -501,4 +572,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,12 @@ 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. A build
+   * that changes made while it ran have superseded is neither written nor reported.
+   */
   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 +145,37 @@ 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. The passages it leaves out also give no links, as their
+   * text never reaches the player, except script passages, which Twine 2 output runs. Without a
+   * target, every source passage gives links, and a link is broken only when no passage has its
+   * name.
+   */
+  readonly target?: PassageOutputTarget;
+}
 interface StoryFormatInfo {
   id: string;
   filename: string;
@@ -242,10 +276,18 @@ 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. Builds run one at a time: changes made during a
+ * build go into one follow-up build after it, and the superseded build is neither
+ * written nor reported.
  */
 export declare function watch(options: WatchOptions): Promise<AbortController>;
 //#endregion
@@ -268,10 +310,16 @@ 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. With a `target` (see `InspectOptions`), a passage that output leaves
+   * out links to nothing, except a script passage, which Twine 2 output runs.
    */
   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 +331,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 +352,15 @@ 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. With a target, passages that output leaves out also give no links (script passages
+ * excepted, as Twine 2 output runs them), so they report no broken links and keep no passage from
+ * being an orphan.
  */
-export declare function storyInspect(story: ReadonlyStory): StoryMap;
+export declare function storyInspect(story: ReadonlyStory, options?: InspectOptions): StoryMap;
 //#endregion
 //#region src/story.d.ts
 /**
@@ -327,8 +387,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 +409,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 +423,10 @@ 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, and a passage it leaves out (other than
+ * a script passage) gives no links.
  */
 export declare function lint(options: Omit<CompileOptions, 'outputMode'>): Promise<LintResult>;
 /**
@@ -442,7 +510,10 @@ export declare function semverCompare(a: [number, number, number], b: [number, n
 //#region src/ifid.d.ts
 /** Generate a new IFID (UUID v4, uppercase). */
 export declare function generateIFID(): IFID;
-/** Validate and brand an IFID string. Throws on invalid input. */
+/**
+ * Validate and brand an IFID string. Throws on invalid input.
+ * Returns the IFID in its stored form (see `normalizeIFID`).
+ */
 export declare function createIFID(value: string): IFID;
 /**
  * Validate an IFID string.
@@ -501,4 +572,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 };