All files / PARSE/1-Discover/types ISourceGraph.ts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
import type IDiscoveredFile from "./IDiscoveredFile";
import type IPipelineFile from "./IPipelineFile";
import type IPlatformIOProject from "../../../types/IPlatformIOProject";
import type IAnchorFacts from "./IAnchorFacts";
import type IFileIncludes from "./IFileIncludes";
 
/**
 * `SourceGraph` — the artifact 1.1 Discover emits (#1444).
 *
 * `docs/architecture/README.md` §1 gives 1.1 sole authorship of which files
 * exist, their kind, the include graph, topological order and every resolved
 * absolute path. Before this, those facts were the pipeline's input record plus
 * five maps `Transpiler` accumulated beside it, and 1.4's `Program` carried
 * four of them for want of a 1.1 artifact (#1452).
 *
 * Plain data, frozen when discovery ends: the record, its arrays and each
 * file's records are `Object.freeze`d, and its maps are typed read-only, as
 * `Program`'s are. A class would not do: immer's `freeze(x, true)` is a silent
 * no-op on class instances (#1313).
 */
interface ISourceGraph {
  /**
   * The C-Next files, in dependency order: every file after the files it
   * includes (#580). Each carries its kind, its resolved path, the text
   * discovery read it from (one read, #1835 review) and its direct `.cnx`
   * includes, which are the graph's edges (#1435).
   */
  readonly cnextFiles: readonly IPipelineFile[];
 
  /** The C and C++ headers the files reach, transitively. */
  readonly headerFiles: readonly IDiscoveredFile[];
 
  /**
   * Per header (by `path`), the search path discovery resolved it along --
   * that of the `.cnx` file that reached it (#1723). Header preprocessing and
   * the #985 translation-unit recovery take their -I list from here.
   */
  readonly headerSearchPaths: ReadonlyMap<string, readonly string[]>;
 
  /**
   * Every `.cnx` file's search path, merged in discovery order (#1723): the -I
   * list for preprocessing with no single includer.
   */
  readonly includeSearchPaths: readonly string[];
 
  /**
   * Per C-Next file, by `path`, what discovery learned about its includes.
   *
   * **The ORDER is significant** and is the order discovery VISITED the
   * files, not `cnextFiles`' dependency order: a generated header takes its
   * include spellings from every file in this order, and
   * `ExternalTypeHeaderBuilder` lets the first header declaring a type win.
   */
  readonly includes: ReadonlyMap<string, IFileIncludes>;
 
  /**
   * Where the run is anchored (#1719), as facts: the project root found from
   * the anchor, the directory a `.cnx` header's `#include` is measured from,
   * and the compile database's defines beneath the caller's.
   *
   * And the project root's `platformio.ini`, parsed: ADR-049's build-system
   * rung, or null when the root has none (#1444, owner ruling 3). It is
   * parsed from the text 1.1's include discovery read for `lib_extra_dirs`,
   * so the libraries the run searches and the target it builds for come from
   * one version of the file.
   */
  readonly anchor: IAnchorFacts & {
    readonly platformio: IPlatformIOProject | null;
  };
 
  /** Whether to write generated output to disk: a files run, not a source run. */
  readonly writeOutputToDisk: boolean;
}
 
export default ISourceGraph;