@effected/bundler 0.6.2 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/Bundler.js +3 -3
  2. package/BundlerError.js +1 -1
  3. package/action/ActionBuilder.js +101 -23
  4. package/action/ActionBundle.js +15 -11
  5. package/action/ActionCheck.js +71 -0
  6. package/action/ActionErrors.js +68 -2
  7. package/action/ActionValidation.js +7 -4
  8. package/action/PersistLocal.js +111 -83
  9. package/action/PersistTarget.js +119 -0
  10. package/action/tree.js +25 -0
  11. package/catalog/resolve-catalogs.js +1 -1
  12. package/changesets/next-versions.js +2 -2
  13. package/config/ActionConfig.js +16 -9
  14. package/config/BuildConfig.js +1 -1
  15. package/config/EffectedConfigFile.js +3 -3
  16. package/config/plugins.js +2 -2
  17. package/config-validation/ConfigValidator.js +1 -1
  18. package/dts/bundled-siblings.js +2 -2
  19. package/dts/reexport-stub.js +1 -1
  20. package/dts/relative-imports.js +1 -1
  21. package/dts/resolved-tsconfig.js +4 -4
  22. package/exe/build.js +3 -3
  23. package/index.d.ts +229 -22
  24. package/index.js +6 -4
  25. package/internal/native-realpath.js +1 -1
  26. package/journal/BuildJournal.js +2 -2
  27. package/jsx/config.js +1 -1
  28. package/manifest/emit-manifest.js +2 -2
  29. package/manifest/manifest-set.js +1 -1
  30. package/manifest/transform.js +1 -1
  31. package/meta/api-extractor.js +5 -5
  32. package/meta/bundle-source.js +2 -2
  33. package/meta/generate.js +2 -2
  34. package/meta/og-image.js +2 -2
  35. package/meta/og-satori.js +3 -3
  36. package/meta/run-pass.js +1 -1
  37. package/meta/scrub-declaration-maps.js +1 -1
  38. package/meta/tsconfig-resolver.js +2 -2
  39. package/meta/tsdoc-config.js +1 -1
  40. package/package.json +4 -4
  41. package/passes/build-target-groups.js +1 -1
  42. package/passes/bundled-deps.js +1 -1
  43. package/passes/loose-files.js +1 -1
  44. package/passes/strip-maps.js +1 -1
  45. package/passes/sync-public.js +3 -3
  46. package/passes/target-groups.js +2 -2
  47. package/report/collector.js +1 -1
  48. package/report/issues-artifact.js +1 -1
package/Bundler.js CHANGED
@@ -1,3 +1,6 @@
1
+ import { Cause, Effect, Exit, Schema } from "effect";
2
+ import * as Fs from "effect/FileSystem";
3
+ import * as PathService from "effect/Path";
1
4
  import { BundlerError } from "./BundlerError.js";
2
5
  import { MetaConfig } from "./config/BuildConfig.js";
3
6
  import { ConfigValidator } from "./config-validation/ConfigValidator.js";
@@ -26,9 +29,6 @@ import { writeIssuesArtifact } from "./report/issues-artifact.js";
26
29
  import { BuildReport } from "./report/schema.js";
27
30
  import { writeTargetsBinding } from "./targets/binding.js";
28
31
  import { releaseWarnings, resolveTargets } from "./targets/resolve-targets.js";
29
- import { Cause, Effect, Exit, Schema } from "effect";
30
- import * as Fs from "effect/FileSystem";
31
- import * as PathService from "effect/Path";
32
32
 
33
33
  // src/Bundler.ts
34
34
  /**
package/BundlerError.js CHANGED
@@ -1,5 +1,5 @@
1
- import { BuildReport } from "./report/schema.js";
2
1
  import { Schema } from "effect";
2
+ import { BuildReport } from "./report/schema.js";
3
3
 
4
4
  // src/BundlerError.ts
5
5
  /**
@@ -1,7 +1,10 @@
1
+ import { Effect, FileSystem, Option, Path, Schema } from "effect";
1
2
  import { ActionBundle, BuildResult } from "./ActionBundle.js";
3
+ import { ActionCheck, DriftEntry } from "./ActionCheck.js";
4
+ import { CheckUnavailable, NoOutput } from "./ActionErrors.js";
2
5
  import { ActionValidation, ValidationResult } from "./ActionValidation.js";
3
6
  import { PersistLocal } from "./PersistLocal.js";
4
- import { Effect, Schema } from "effect";
7
+ import { PersistTarget } from "./PersistTarget.js";
5
8
 
6
9
  // src/action/ActionBuilder.ts
7
10
  /**
@@ -37,6 +40,21 @@ var BuildFailed = class extends Schema.TaggedError()("BuildFailed", {
37
40
  validation: ValidationResult
38
41
  }) {};
39
42
  /**
43
+ * Check mode found the committed build differs from a fresh one.
44
+ *
45
+ * @public
46
+ */
47
+ var CheckFailed = class extends Schema.TaggedError()("CheckFailed", {
48
+ /** A summary. */
49
+ message: Schema.String,
50
+ /** Every file that differs. */
51
+ drift: Schema.Array(DriftEntry),
52
+ /** How bundling went. */
53
+ build: BuildResult,
54
+ /** What validation found. */
55
+ validation: ValidationResult
56
+ }) {};
57
+ /**
40
58
  * What a whole action build did.
41
59
  *
42
60
  * @public
@@ -47,8 +65,15 @@ var ActionBuildResult = class extends Schema.Class("ActionBuildResult")({
47
65
  /** How bundling went. */
48
66
  build: BuildResult,
49
67
  /** Whether the build was copied to the local action directory. */
50
- persisted: Schema.Boolean
68
+ persisted: Schema.Boolean,
69
+ /** What differs from the committed build. Present only under check, and empty when nothing does. */
70
+ drift: Schema.optionalKey(Schema.Array(DriftEntry))
51
71
  }) {};
72
+ const realCwd = (cwd) => Effect.gen(function* () {
73
+ const fs = yield* FileSystem.FileSystem;
74
+ const resolved = (yield* Path.Path).resolve(cwd);
75
+ return yield* fs.realPath(resolved).pipe(Effect.orElseSucceed(() => resolved));
76
+ });
52
77
  const failValidation = (validation, build) => new ValidationFailed({
53
78
  errorCount: validation.errors.length,
54
79
  warningCount: validation.warnings.length,
@@ -79,30 +104,83 @@ var ActionBuilder = class {
79
104
  */
80
105
  static build = Effect.fn("ActionBuilder.build")(function* (options) {
81
106
  const { config, cwd } = options;
82
- const strict = ActionValidation.isStrict(config, options);
83
- const before = options.validate ? yield* ActionValidation.validate(config, cwd, options) : ActionValidation.resultOf([], [], false);
84
- if (!before.valid) return yield* failValidation(before);
85
- const build = yield* ActionBundle.build(config, {
107
+ const fs = yield* FileSystem.FileSystem;
108
+ const path = yield* Path.Path;
109
+ const target = yield* PersistTarget.resolve(config, {
86
110
  cwd,
87
- clean: true
88
- });
89
- if (!build.success) return yield* new BuildFailed({
90
- message: build.error ?? "One or more entries failed to build",
91
- failedEntries: build.entries.filter((entry) => !entry.success).length,
92
- build,
93
- validation: before
111
+ root: options.root
94
112
  });
95
- const oversized = options.validate ? ActionValidation.checkBundleSizes(config, build.entries.flatMap((entry) => entry.stats !== void 0 ? [entry.stats] : [])) : [];
96
- const validation = ActionValidation.resultOf(before.errors, [...before.warnings, ...oversized], strict && options.validate);
97
- if (!validation.valid) return yield* failValidation(validation, build);
98
- const persisted = options.persist && config.persistLocal.enabled;
99
- if (persisted) yield* PersistLocal.persist(config, { cwd });
100
- return ActionBuildResult.make({
101
- validation,
102
- build,
103
- persisted
113
+ const strict = ActionValidation.isStrict(config, options);
114
+ const check = options.check;
115
+ if (check && (!options.persist || !target.enabled)) return yield* new CheckUnavailable({ reason: "persist-disabled" });
116
+ if (!target.keepDist && !options.persist && !check) return yield* new NoOutput({ reason: "persist-off" });
117
+ const before = options.validate ? yield* ActionValidation.validate(config, cwd, {
118
+ ci: options.ci,
119
+ base: target.base
120
+ }) : ActionValidation.resultOf([], [], false);
121
+ if (!before.valid) return yield* failValidation(before);
122
+ const stage = !target.keepDist || check;
123
+ const outDir = stage ? target.stagingDir : path.join(yield* realCwd(cwd), "dist");
124
+ const bundleAndPersist = Effect.gen(function* () {
125
+ const build = yield* ActionBundle.build(config, {
126
+ cwd,
127
+ clean: true,
128
+ outDir
129
+ });
130
+ if (!build.success) return yield* new BuildFailed({
131
+ message: build.error ?? "One or more entries failed to build",
132
+ failedEntries: build.entries.filter((entry) => !entry.success).length,
133
+ build,
134
+ validation: before
135
+ });
136
+ const oversized = options.validate ? ActionValidation.checkBundleSizes(config, build.entries.flatMap((entry) => entry.stats !== void 0 ? [entry.stats] : [])) : [];
137
+ const validation = ActionValidation.resultOf(before.errors, [...before.warnings, ...oversized], strict && options.validate);
138
+ if (!validation.valid) return yield* failValidation(validation, build);
139
+ if (check) {
140
+ const actionYml = path.join(cwd, "action.yml");
141
+ const stagedActionYml = (yield* fs.exists(actionYml)) ? Option.some(actionYml) : Option.none();
142
+ const drift = [...yield* ActionCheck.compare({
143
+ stagedActionYml,
144
+ stagedDist: outDir,
145
+ targetDir: target.outputPath,
146
+ target: "persisted",
147
+ includeActionYml: true
148
+ }), ...target.keepDist ? yield* ActionCheck.compare({
149
+ stagedActionYml: Option.none(),
150
+ stagedDist: outDir,
151
+ targetDir: path.join(yield* realCwd(cwd), "dist"),
152
+ target: "dist",
153
+ includeActionYml: false
154
+ }) : []];
155
+ if (drift.length > 0) return yield* new CheckFailed({
156
+ message: `${drift.length} file${drift.length === 1 ? "" : "s"} differ from the committed build`,
157
+ drift,
158
+ build,
159
+ validation
160
+ });
161
+ return ActionBuildResult.make({
162
+ validation,
163
+ build,
164
+ persisted: false,
165
+ drift
166
+ });
167
+ }
168
+ const persisted = options.persist && config.persistLocal.enabled;
169
+ if (persisted) yield* PersistLocal.persist(target, {
170
+ cwd,
171
+ distDir: outDir
172
+ });
173
+ return ActionBuildResult.make({
174
+ validation,
175
+ build,
176
+ persisted
177
+ });
104
178
  });
179
+ return yield* !stage ? bundleAndPersist : bundleAndPersist.pipe(Effect.ensuring(fs.remove(target.stagingDir, {
180
+ recursive: true,
181
+ force: true
182
+ }).pipe(Effect.ignore)));
105
183
  });
106
184
  };
107
185
 
108
- export { ActionBuildResult, ActionBuilder, BuildFailed, ValidationFailed };
186
+ export { ActionBuildResult, ActionBuilder, BuildFailed, CheckFailed, ValidationFailed };
@@ -1,11 +1,11 @@
1
+ import { stripVTControlCharacters } from "node:util";
2
+ import { Effect, FileSystem, Path, Schema } from "effect";
3
+ import { rolldown } from "rolldown";
1
4
  import { causeMessage } from "../internal/causeMessage.js";
2
5
  import { BundleFailed, CleanError, WriteError } from "./ActionErrors.js";
3
6
  import { DEFAULT_LIFECYCLE_ENTRIES, invalidWorkerName, workerImportCheck, workerSource } from "./entries.js";
4
7
  import { ignoreStubPlugin } from "./ignore-stub-plugin.js";
5
8
  import { checkImport } from "./import-check.js";
6
- import { Effect, FileSystem, Path, Schema } from "effect";
7
- import { stripVTControlCharacters } from "node:util";
8
- import { rolldown } from "rolldown";
9
9
 
10
10
  // src/action/ActionBundle.ts
11
11
  /**
@@ -114,7 +114,8 @@ const entriesToBuild = Effect.fnUntraced(function* (config, cwd) {
114
114
  });
115
115
  /**
116
116
  * Bundles one entry and, unless the config turns it off, proves the bundle loads. A failure comes back as a result.
117
- * `out` is `cwd`'s `dist`, joined by the caller: rolldown and the load check work on the host disk.
117
+ * `out` is the output directory (`outDir`, by default `cwd`'s `dist`), joined by the caller: rolldown and the load
118
+ * check work on the host disk.
118
119
  */
119
120
  const bundleEntry = async (entry, config, cwd, out, signal) => {
120
121
  const started = Date.now();
@@ -198,8 +199,8 @@ const failedToBundle = (entry, cause, warnings) => BundleResult.make({
198
199
  var ActionBundle = class {
199
200
  constructor() {}
200
201
  /**
201
- * Bundles every entry of the action at `options.cwd` into its own `dist/<entry>.js`, and writes `dist/package.json`
202
- * so Node reads them as ESM.
202
+ * Bundles every entry of the action at `options.cwd` into `<entry>.js` in the output directory (`options.outDir`,
203
+ * by default `dist` in `cwd`), and writes a `package.json` there so Node reads them as ESM.
203
204
  *
204
205
  * @remarks
205
206
  * Each bundle is self-contained apart from `node:` builtins and `build.externals`, and the output does not depend
@@ -213,13 +214,16 @@ var ActionBundle = class {
213
214
  * installed passes with a warning on the entry, and the check learns nothing about the bundle past that import.
214
215
  *
215
216
  * An entry that fails to bundle or load is reported in the result with the others still built, and leaves no bundle
216
- * in `dist`. A missing `main`, a `pre`, `post` or worker the config names with no file, and a bad worker name fail
217
- * {@link BundleFailed} before `dist` is touched. Interrupting the build kills a running load check.
217
+ * in the output directory. A missing `main`, a `pre`, `post` or worker the config names with no file, and a bad
218
+ * worker name fail {@link BundleFailed} before the output directory is touched. Interrupting the build kills a
219
+ * running load check.
218
220
  *
219
- * Cleaning `dist`, writing `dist/package.json` and reading each bundle's size go through the provided `FileSystem`
221
+ * Cleaning the output directory, writing its `package.json` and reading each bundle's size go through the provided `FileSystem`
220
222
  * and `Path`, while rolldown and the load check work on the host disk, so provide the host's.
221
223
  *
222
- * @param options - `cwd` is the action's directory; `clean` removes `dist` first.
224
+ * @param options - `cwd` is the action's directory; `clean` removes the output directory first; `outDir` is the
225
+ * absolute directory to bundle into and defaults to `dist` in `cwd`, while the reported output path stays
226
+ * `dist/<entry>.js`.
223
227
  */
224
228
  static build = Effect.fn("ActionBundle.build")(function* (config, options) {
225
229
  const fs = yield* FileSystem.FileSystem;
@@ -227,7 +231,7 @@ var ActionBundle = class {
227
231
  const started = Date.now();
228
232
  const requested = path.resolve(options.cwd);
229
233
  const cwd = yield* fs.realPath(requested).pipe(Effect.orElseSucceed(() => requested));
230
- const dist = path.join(cwd, "dist");
234
+ const dist = options.outDir ?? path.join(cwd, "dist");
231
235
  const entries = yield* entriesToBuild(config, cwd);
232
236
  if (options.clean) yield* fs.remove(dist, {
233
237
  recursive: true,
@@ -0,0 +1,71 @@
1
+ import { Effect, FileSystem, Path, Schema } from "effect";
2
+ import { sameBytes, walk } from "./tree.js";
3
+
4
+ // src/action/ActionCheck.ts
5
+ /**
6
+ * One way a committed build differs from a fresh one.
7
+ *
8
+ * @remarks
9
+ * `path` is relative to the target directory and `/`-separated. `missing` is in the build and not in the target,
10
+ * `extra` is in the target and not in the build.
11
+ *
12
+ * @public
13
+ */
14
+ var DriftEntry = class extends Schema.Class("DriftEntry")({
15
+ /** Which copy differs: the package's own `dist` or the persisted action directory. */
16
+ target: Schema.Literals(["dist", "persisted"]),
17
+ /** The file, relative to the target directory. */
18
+ path: Schema.String,
19
+ /** How it differs. */
20
+ kind: Schema.Literals([
21
+ "changed",
22
+ "missing",
23
+ "extra"
24
+ ])
25
+ }) {};
26
+ const slash = (value) => value.split("\\").join("/");
27
+ /**
28
+ * Compares a fresh build against a committed copy of it.
29
+ *
30
+ * @public
31
+ */
32
+ var ActionCheck = class {
33
+ constructor() {}
34
+ /**
35
+ * Lists every file where the target differs from the build, sorted by path.
36
+ *
37
+ * @remarks
38
+ * A `"persisted"` target holds the bundles under `dist/` beside `action.yml`, as {@link PersistLocal} lays them out,
39
+ * so its entries read `dist/main.js`; a `"dist"` target holds them at its root. Nothing else in a persisted directory
40
+ * is compared. A target directory that does not exist reports every file as `missing`.
41
+ */
42
+ static compare = Effect.fn("ActionCheck.compare")(function* (options) {
43
+ const fs = yield* FileSystem.FileSystem;
44
+ const path = yield* Path.Path;
45
+ const { target, targetDir } = options;
46
+ const drift = [];
47
+ const note = (file, kind) => drift.push(DriftEntry.make({
48
+ target,
49
+ path: slash(file),
50
+ kind
51
+ }));
52
+ const compareFile = Effect.fnUntraced(function* (built, committed, label) {
53
+ if (!(yield* fs.exists(committed))) return note(label, "missing");
54
+ if (!sameBytes(yield* fs.readFile(built), yield* fs.readFile(committed))) note(label, "changed");
55
+ });
56
+ const distTarget = target === "persisted" ? path.join(targetDir, "dist") : targetDir;
57
+ const prefix = target === "persisted" ? "dist/" : "";
58
+ const built = yield* walk(options.stagedDist, options.stagedDist);
59
+ for (const file of built) yield* compareFile(path.join(options.stagedDist, file), path.join(distTarget, file), prefix + slash(file));
60
+ const builtSet = new Set(built);
61
+ for (const file of yield* walk(distTarget, distTarget)) if (!builtSet.has(file)) note(prefix + slash(file), "extra");
62
+ if (options.includeActionYml) {
63
+ const committed = path.join(targetDir, "action.yml");
64
+ if (options.stagedActionYml._tag === "Some") yield* compareFile(options.stagedActionYml.value, committed, "action.yml");
65
+ else if (yield* fs.exists(committed)) note("action.yml", "extra");
66
+ }
67
+ return drift.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
68
+ });
69
+ };
70
+
71
+ export { ActionCheck, DriftEntry };
@@ -1,5 +1,5 @@
1
- import { causeMessage } from "../internal/causeMessage.js";
2
1
  import { Schema } from "effect";
2
+ import { causeMessage } from "../internal/causeMessage.js";
3
3
 
4
4
  // src/action/ActionErrors.ts
5
5
  /**
@@ -79,5 +79,71 @@ var ActionYmlPathError = class extends Schema.TaggedError()("ActionYmlPathError"
79
79
  return `action.yml runs.${this.entryType} is ${this.specifiedPath}, and ${this.expectedPath} does not exist`;
80
80
  }
81
81
  };
82
+ /**
83
+ * The persisted action path cannot be used.
84
+ *
85
+ * @remarks
86
+ * `outside-workspace` means it resolves beyond the workspace root, `inside-package` means a workspace-based path
87
+ * lands inside the package being built, or a package-based path lands in its `dist` or staging directory,
88
+ * `contains-package` means it is the package or an ancestor of it, the workspace root included,
89
+ * `inside-other-package` means it is, or lies inside, another directory holding a `package.json` (named in
90
+ * `packageDir`), and `dist-without-persist` means `dist = false` with nothing persisted.
91
+ *
92
+ * @public
93
+ */
94
+ var PersistPathError = class extends Schema.TaggedError()("PersistPathError", {
95
+ /** The path as configured, or the resolved output path. */
96
+ path: Schema.String,
97
+ /** Why it was refused. */
98
+ reason: Schema.Literals([
99
+ "outside-workspace",
100
+ "inside-package",
101
+ "contains-package",
102
+ "inside-other-package",
103
+ "dist-without-persist"
104
+ ]),
105
+ /** The other package's directory, for `inside-other-package`. */
106
+ packageDir: Schema.optionalKey(Schema.String)
107
+ }) {
108
+ get message() {
109
+ if (this.reason === "outside-workspace") return `The persist path ${this.path} is outside the workspace`;
110
+ if (this.reason === "contains-package") return `The persist path ${this.path} is, or contains, the package being built, and a persist would delete it`;
111
+ if (this.reason === "inside-package") return `The persist path ${this.path} is inside the package being built, its dist or its staging directory`;
112
+ if (this.reason === "inside-other-package") return `The persist path ${this.path} is inside the package at ${this.packageDir ?? "an unnamed directory"}, and a persist would overwrite it`;
113
+ return "persistLocal.dist = false needs persistLocal.enabled, or the build is written nowhere";
114
+ }
115
+ };
116
+ /**
117
+ * Check mode needs somewhere persisted to compare against, and there is none.
118
+ *
119
+ * @remarks
120
+ * `persist-disabled` means the run persists nothing, either because `persistLocal.enabled` is false or because the
121
+ * caller turned persisting off.
122
+ *
123
+ * @public
124
+ */
125
+ var CheckUnavailable = class extends Schema.TaggedError()("CheckUnavailable", {
126
+ /** Why there is nothing to check. */
127
+ reason: Schema.Literals(["persist-disabled"]) }) {
128
+ get message() {
129
+ return "Nothing is persisted, so there is no committed build to check";
130
+ }
131
+ };
132
+ /**
133
+ * The run would keep no output at all: the package's `dist` is not kept (`persistLocal.dist = false`) and this run
134
+ * persists nothing.
135
+ *
136
+ * @remarks
137
+ * Raised before validating or bundling, so nothing is written. Persist the run, or keep `dist`.
138
+ *
139
+ * @public
140
+ */
141
+ var NoOutput = class extends Schema.TaggedError()("NoOutput", {
142
+ /** Why there is no output. */
143
+ reason: Schema.Literals(["persist-off"]) }) {
144
+ get message() {
145
+ return "persistLocal.dist = false keeps no dist, and this run persists nothing, so the build would be written nowhere";
146
+ }
147
+ };
82
148
 
83
- export { ActionYmlPathError, BundleFailed, CleanError, PersistLocalError, WriteError };
149
+ export { ActionYmlPathError, BundleFailed, CheckUnavailable, CleanError, NoOutput, PersistLocalError, PersistPathError, WriteError };
@@ -1,8 +1,8 @@
1
- import { ActionYml } from "./ActionYml.js";
2
- import { invalidWorkerName, workerSource } from "./entries.js";
3
- import { Effect, FileSystem, Option, Path, Result, Schema } from "effect";
4
1
  import { RuntimeEnv } from "@effected/env";
5
2
  import { Yaml } from "@effected/yaml";
3
+ import { Effect, FileSystem, Option, Path, Result, Schema } from "effect";
4
+ import { ActionYml } from "./ActionYml.js";
5
+ import { invalidWorkerName, workerSource } from "./entries.js";
6
6
 
7
7
  // src/action/ActionValidation.ts
8
8
  /**
@@ -172,7 +172,10 @@ var ActionValidation = class ActionValidation {
172
172
  ...sizeErrors,
173
173
  ...actionYml.errors
174
174
  ];
175
- return ActionValidation.resultOf(errors, actionYml.warnings, ActionValidation.isStrict(config, options));
175
+ const ignored = new Set(config.build.ignore);
176
+ const externals = config.build.externals.filter((name) => !ignored.has(name));
177
+ const externalsWarnings = options.base === "workspace" && externals.length > 0 ? [issue("EXTERNALS_NOT_COMMITTED", `build.externals (${externals.join(", ")}) are imported at runtime, but a committed action under the workspace has no node_modules`, void 0, "Bundle them, or move to the package base where node_modules sits beside the action")] : [];
178
+ return ActionValidation.resultOf(errors, [...actionYml.warnings, ...externalsWarnings], ActionValidation.isStrict(config, options));
176
179
  });
177
180
  /**
178
181
  * The bundles past `validation.maxBundleSize`, one warning each. Nothing when no limit is set or it cannot be read.