Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 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 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 | 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 3367x 3367x 2128x 2128x 3367x 54x 54x 3367x 33x 33x 33x 33x 33x 3367x 396x 396x 756x 756x 756x 756x 3367x 532x 532x 532x 532x 532x 532x 211x 211x 211x 1206x 1206x 1206x 211x 211x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 27x 26x 26x 1x 1x 1x 1x 1x 30x 30x 30x 30x 30x 214x 214x 29x 214x 177x 177x 214x 1x 1x 1x 1x 1x 1x 27x 177x 177x 177x 177x 177x 177x 177x 1x 1x 1x 27x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 27x 27x 27x 27x 27x 27x 27x 27x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 33x 33x 33x 33x 33x 33x 33x 33x 33x 33x 33x 33x 33x 33x 33x 33x 33x 33x 33x 33x 33x 33x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 151x 151x 151x 151x 151x 151x 151x 151x 151x 151x 151x 151x 151x 151x 151x 151x 532x 532x 532x 532x 532x 532x 532x 141x 141x 141x 96x 96x 96x 45x 45x 45x 45x 45x 45x 45x 141x 532x 532x 532x 532x 532x 532x 532x 532x 96x 96x 96x 96x 96x 96x 532x 532x 532x 532x 532x 532x 532x 532x 532x 19x 19x 19x 19x 532x 532x 532x 532x 532x 532x 10x 10x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x 532x | /**
* @file incrementalCache.js
* @description Reusing a unit's whole compilation product across rebuilds.
*
* `avenx serve` and `avenx watch` rebuild the entire project on every save, and
* a project's components mostly do not change between two saves. This cache
* keeps what {@link ComponentParser#parse} produced for each unit so an
* unchanged file is replayed rather than recompiled.
*
* ## Why a return value is not enough
*
* `parse()` returns a class body, but that is only half of what it produces.
* The rest it records on the parser: the unit's module metadata, its trace
* locations, the component tags its template references, its Atlas fragment
* input, and any render or expression gap the build has to report. A cache that
* returned the string and skipped the recording would hand the next build a
* bundle whose entry module cannot be framed and a trace sidecar and Atlas with
* holes in them -- quietly, and only for the files that happened to hit.
*
* So a hit replays every one of those channels. {@link captureUnit} and
* {@link replayUnit} are written as a pair against one list of channels for
* exactly that reason: a channel added to `parse()` and forgotten here is the
* failure this file is most likely to have, and keeping the two halves adjacent
* is what makes the omission visible.
*
* ## What the key has to cover
*
* A unit's own text is not enough.
*
* Its stylesheet is a separate file, so `counter.component.css` changing has to
* invalidate `counter.component.js`. Its bridge bindings resolve against a
* bridge's own declared surface, so renaming a getter must invalidate every
* consumer even though no consumer's file changed. Its unresolved-component
* check (AVX_W46) resolves template tags against every component name in the
* project, so adding the component that a typo was reaching for must invalidate
* the file holding the typo. And the emitted output differs between a
* development and a production build, so the mode belongs in the key too.
*
* Those cross-unit inputs are folded into one environment fingerprint rather
* than tracked per edge. It is coarse -- adding any component invalidates every
* unit -- and that is the intended trade: the common case this exists for is
* editing a file that is already there, which leaves the fingerprint untouched,
* while add, rename and delete fall back to a cold build instead of to a
* dependency analysis that could be wrong. A stale unit is worse than no cache,
* because it would put code in the bundle that the sources no longer describe.
*
* The cache lives in memory for the life of the process, on the same terms as
* `atlas/cache.js`: a disk cache would add invalidation risk across process
* boundaries, and `avenx build` does not use this at all, so no production
* artifact can depend on cache state.
* @module lib/compiler/incrementalCache
*/
import { createHash } from 'crypto';
import fs from 'fs';
import path from 'path';
import { fileURLToPath } from 'url';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
/**
* How many unit products to retain.
*
* Matches `atlas/cache.js`: large enough for a substantial application, bounded
* so a long-lived dev server cannot grow without limit.
* @type {number}
*/
const MAX_ENTRIES = 2000;
/** @type {Map<string, object>} */
const store = new Map();
/** @type {string|null} */
let compilerFingerprintCache = null;
/**
* Hit and miss counts since the last reset.
*
* Kept because "the cache is safe" and "the cache is doing anything" are
* different claims, and a test that only checks the first passes just as well
* against a cache that never hits.
* @type {{hits: number, misses: number}}
*/
const stats = { hits: 0, misses: 0 };
/**
* Serialises a value so that equal inputs always produce equal text.
*
* `JSON.stringify` preserves insertion order, which differs between a config
* read from disk and the same config merged with compiler options, and it drops
* `Set` and `Map` contents entirely -- both of which appear in what this file
* digests. Sorting keys and normalising collections makes the digest depend on
* the value rather than on how it was assembled.
* @param {*} value - The value to serialise.
* @returns {string} A canonical form.
*/
function stableStringify(value) {
if (value === null || typeof value !== 'object') {
return JSON.stringify(value) ?? 'null';
}
if (value instanceof Set) {
return `Set(${[...value].map((entry) => stableStringify(entry)).sort().join(',')})`;
}
if (value instanceof Map) {
return `Map(${[...value.entries()]
.map(([key, entry]) => `${stableStringify(key)}:${stableStringify(entry)}`)
.sort()
.join(',')})`;
}
if (Array.isArray(value)) {
return `[${value.map((entry) => stableStringify(entry)).join(',')}]`;
}
return `{${Object.keys(value)
.sort()
.map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
.join(',')}}`;
}
/**
* Hashes the parts of a key into one digest.
* @param {...*} parts - Values to include, in a fixed order.
* @returns {string} The digest.
*/
function digest(...parts) {
const hash = createHash('sha1');
for (const part of parts) {
hash.update(typeof part === 'string' ? part : stableStringify(part));
hash.update('\0');
}
return hash.digest('hex');
}
/**
* Digests the compiler's own source.
*
* An in-memory cache cannot outlive a change to the compiler -- ES modules are
* resolved once per process, so editing the compiler means restarting the
* process that holds this `Map`. The fingerprint is computed anyway, because
* "the cache is safe because of how the module system happens to work" is not a
* property worth depending on, and because it is what makes the cache correct
* if a disk tier is ever added above it.
*
* Read once per process and memoised: about 150 files and under two megabytes,
* which costs a few milliseconds one time rather than once per rebuild.
* @returns {string} A digest of every compiler source file.
*/
export function compilerFingerprint() {
if (compilerFingerprintCache) {
return compilerFingerprintCache;
}
const libDir = path.resolve(__dirname, '..');
const files = [];
const walk = (dir) => {
let entries;
try {
entries = fs.readdirSync(dir, { withFileTypes: true });
} catch {
// A compiler installed read-only, or a directory that vanished mid-walk.
// A partial fingerprint is still a fingerprint; refusing to build because
// the cache could not measure itself would be the worse failure.
return;
}
for (const entry of entries) {
const full = path.join(dir, entry.name);
if (entry.isDirectory()) {
walk(full);
} else if (entry.name.endsWith('.js')) {
files.push(full);
}
}
};
walk(libDir);
files.sort();
const hash = createHash('sha1');
for (const file of files) {
hash.update(path.relative(libDir, file));
hash.update('\0');
try {
hash.update(fs.readFileSync(file));
} catch {
hash.update('unreadable');
}
hash.update('\0');
}
compilerFingerprintCache = hash.digest('hex');
return compilerFingerprintCache;
}
/**
* Digests every project-wide input that can affect generated output.
*
* Computed once per build rather than once per unit: nothing in it varies
* between two units of the same build.
* @param {object} options - The project's identity.
* @param {string} options.rootDir - The project root.
* @param {object} options.config - The resolved configuration.
* @param {object} [options.publicEnv] - `AVX_PUBLIC_*` values the compiler inlines.
* @returns {string} The fingerprint.
*/
export function createSessionFingerprint({ rootDir, config, publicEnv = {} }) {
const configPath = path.join(rootDir, 'avenx.config.json');
let configSource = '';
try {
configSource = fs.readFileSync(configPath, 'utf8');
} catch {
// No config file: the defaults apply, and `config` already reflects them.
}
return digest(rootDir, config, configSource, publicEnv, compilerFingerprint());
}
/**
* Digests the cross-unit state `parse()` resolves against.
*
* Separate from the session fingerprint because it is derived from the source
* tree rather than from the project's configuration: it changes when a file is
* added, renamed or deleted, or when a bridge's surface changes, and stays put
* when the edit is to a file that was already there.
* @param {object} options - The build's cross-unit state.
* @param {Map<string, object>} [options.bridges] - Bridge descriptors by path.
* @param {Set<string>|string[]} [options.componentNames] - Every unit name in the project.
* @param {Map<string, string[]>} [options.routeParams] - Route parameters by page name.
* @param {boolean} [options.production] - Whether this is an optimised build.
* @param {string[]} [options.customVoidTags] - Configured void tags.
* @returns {string} The fingerprint.
*/
export function createEnvironmentFingerprint({
bridges = null,
componentNames = null,
routeParams = null,
production = false,
customVoidTags = [],
}) {
// Bridge descriptors, not bridge sources: a descriptor is derived from its
// file, and it is the descriptor -- the declared surface -- that a consumer
// resolves against. Digesting it means reformatting a bridge does not
// invalidate its consumers, while renaming anything they can read does.
const bridgeSurfaces = bridges
? [...bridges.entries()].map(([key, descriptor]) => [path.resolve(key), descriptor])
: [];
return digest(
bridgeSurfaces,
componentNames ? [...componentNames].sort() : [],
routeParams || new Map(),
production ? 'production' : 'development',
[...customVoidTags].sort(),
);
}
/**
* Computes the cache key for one unit.
* @param {object} options - The unit's inputs.
* @param {string} options.filePath - The unit's source path.
* @param {'component'|'page'} options.kind - Which kind of unit it is.
* @param {string} options.source - The unit's source text.
* @param {string|null} options.styleSource - Its stylesheet's text, or null when it has none.
* @param {string} options.sessionFingerprint - From {@link createSessionFingerprint}.
* @param {string} options.environmentFingerprint - From {@link createEnvironmentFingerprint}.
* @returns {string} The key.
*/
export function createUnitKey({
filePath,
kind,
source,
styleSource,
sessionFingerprint,
environmentFingerprint,
}) {
return digest(
path.resolve(filePath),
kind,
source,
styleSource === null || styleSource === undefined ? ' |