Skip to content

Commit 0d69817

Browse files
committed
Move output type validators to output-cache.ts module
This move simplifies the consumer-side of the module. And, also, the validators should be an internal implementation detail—not the concern of those who wish to "get" a cached output.
1 parent c2f4379 commit 0d69817

6 files changed

Lines changed: 143 additions & 156 deletions

File tree

‎src/cli/output-cache.test.ts‎

Lines changed: 8 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,13 @@ import path from "path";
44

55
import test from "ava";
66

7-
import { isVersionInfo } from "../codeql";
87
import { setupTests } from "../testing-utils";
98

109
import {
1110
cacheCommandOutput,
1211
getCachedCommandOutput,
1312
resetCachedCommandOutputs,
13+
type VersionInfo,
1414
} from "./output-cache";
1515

1616
setupTests(test);
@@ -60,7 +60,6 @@ test.serial(
6060
getCachedCommandOutput(
6161
"version",
6262
"/path/to/codeql",
63-
isVersionInfo,
6463
),
6564
{ version: "2.20.0" },
6665
);
@@ -82,7 +81,6 @@ test.serial(
8281
getCachedCommandOutput(
8382
"version",
8483
"/path/to/codeql",
85-
isVersionInfo,
8684
),
8785
undefined,
8886
);
@@ -99,7 +97,6 @@ test.serial(
9997
getCachedCommandOutput(
10098
"version",
10199
"/path/to/codeql",
102-
isVersionInfo,
103100
),
104101
undefined,
105102
);
@@ -115,7 +112,6 @@ test.serial(
115112
getCachedCommandOutput(
116113
"version",
117114
"/path/to/codeql",
118-
isVersionInfo,
119115
),
120116
undefined,
121117
);
@@ -141,7 +137,6 @@ test.serial(
141137
getCachedCommandOutput(
142138
"version",
143139
"/path/to/codeql",
144-
isVersionInfo,
145140
),
146141
undefined,
147142
JSON.stringify(output),
@@ -162,7 +157,6 @@ test.serial(
162157
getCachedCommandOutput(
163158
"version",
164159
"/path/to/codeql",
165-
isVersionInfo,
166160
),
167161
undefined,
168162
);
@@ -172,37 +166,29 @@ test.serial(
172166

173167
test.serial("cacheCommandOutput persists the output to the memo", async (t) => {
174168
await withCacheDir(() => {
175-
cacheCommandOutput("version", "/path/to/codeql", {
176-
hello: "world",
177-
});
169+
const output: VersionInfo = { version: "2.20.0" };
170+
cacheCommandOutput("version", "/path/to/codeql", output);
178171

179172
// Tier 1: the value is immediately available from the memo.
180-
t.deepEqual(
181-
getCachedCommandOutput("version", "/path/to/codeql"),
182-
{ hello: "world" },
183-
);
173+
t.deepEqual(getCachedCommandOutput("version", "/path/to/codeql"), output);
184174
});
185175
});
186176

187177
test.serial(
188178
"getCachedCommandOutput prefers the in-memory memo over the file",
189179
async (t) => {
190180
await withCacheDir((cacheFilePath) => {
191-
cacheCommandOutput("version", "/path/to/codeql", {
192-
value: 1,
193-
});
181+
const output: VersionInfo = { version: "2.20.0", overlayVersion: 1 };
182+
cacheCommandOutput("version", "/path/to/codeql", output);
194183

195184
// Overwrite the file with a different value; the memo (tier 1) should win.
196185
writeCacheFile(cacheFilePath, {
197186
version: {
198187
cmd: "/path/to/codeql",
199-
output: { value: 2 },
188+
output: { version: "2.21.0" },
200189
},
201190
});
202-
t.deepEqual(
203-
getCachedCommandOutput("version", "/path/to/codeql"),
204-
{ value: 1 },
205-
);
191+
t.deepEqual(getCachedCommandOutput("version", "/path/to/codeql"), output);
206192
});
207193
},
208194
);

‎src/cli/output-cache.ts‎

Lines changed: 103 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -14,23 +14,108 @@ const COMMAND_CACHE_FILENAME = "codeql-action-command-cache.json";
1414
/** A key used to identify cached command output. */
1515
export type CommandCacheKey = "version" | "resolve languages";
1616

17+
export interface VersionInfo {
18+
version: string;
19+
features?: { [name: string]: boolean };
20+
/**
21+
* The overlay version helps deal with backward incompatible changes for
22+
* overlay analysis. When a precompiled query pack reports the same overlay
23+
* version as the CodeQL CLI, we can use the CodeQL CLI to perform overlay
24+
* analysis with that pack. Otherwise, if the overlay versions are different,
25+
* or if either the pack or the CLI does not report an overlay version,
26+
* we need to revert to non-overlay analysis.
27+
*/
28+
overlayVersion?: number;
29+
}
30+
31+
/** Returns true if `x` is a {@link VersionInfo}. */
32+
export function isVersionInfo(x: unknown): x is VersionInfo {
33+
return (
34+
json.isObject(x) &&
35+
json.validateSchema(
36+
{
37+
version: json.string,
38+
features: json.optional(json.object),
39+
overlayVersion: json.optional(json.number),
40+
},
41+
x,
42+
)
43+
);
44+
}
45+
46+
export interface ResolveLanguagesOutput {
47+
aliases?: {
48+
[alias: string]: string;
49+
};
50+
extractors: {
51+
[language: string]: Array<{
52+
extractor_root: string;
53+
extractor_options?: any;
54+
}>;
55+
};
56+
}
57+
58+
/** Returns true if `x` is a {@link ResolveLanguagesOutput}. */
59+
export function isResolveLanguagesOutput(
60+
x: unknown,
61+
): x is ResolveLanguagesOutput {
62+
return (
63+
json.isObject<ResolveLanguagesOutput>(x) &&
64+
json.isObject(x.extractors) &&
65+
Object.values(x.extractors).every(
66+
(extractorList) =>
67+
json.isArray(extractorList) &&
68+
extractorList.every(
69+
(extractor) =>
70+
json.isObject<{ extractor_root: unknown }>(extractor) &&
71+
json.isString(extractor.extractor_root),
72+
),
73+
) &&
74+
(x.aliases === undefined ||
75+
(json.isObject(x.aliases) &&
76+
Object.values(x.aliases).every((alias) => json.isString(alias))))
77+
);
78+
}
79+
80+
export type CommandCacheKeyOutputMap = {
81+
version: VersionInfo;
82+
"resolve languages": ResolveLanguagesOutput;
83+
};
84+
85+
const commandCacheValidators: {
86+
[K in CommandCacheKey]: (
87+
output: unknown,
88+
) => output is CommandCacheKeyOutputMap[K];
89+
} = {
90+
version: isVersionInfo,
91+
"resolve languages": isResolveLanguagesOutput,
92+
};
93+
94+
interface StoredCommandCacheEntry {
95+
cmd: string;
96+
output: unknown;
97+
}
98+
1799
/** A single cached command output together with the CLI path it came from. */
18-
interface CommandCacheEntry {
100+
export interface CommandCacheEntry<K extends CommandCacheKey> {
19101
/**
20102
* The path to the CodeQL CLI that produced `output`. Persisted so that a
21103
* different step using a different CodeQL bundle doesn't pick up a stale
22104
* value.
23105
*/
24106
cmd: string;
25-
output: unknown;
107+
output: CommandCacheKeyOutputMap[K];
26108
}
27109

28110
/**
29111
* Tier 1: the in-process memo. Consulted first on every lookup and populated
30112
* whenever a value is read from the file (tier 2) or computed via the CLI
31113
* (tier 3).
32114
*/
33-
const inMemoryCache = new Map<CommandCacheKey, CommandCacheEntry>();
115+
const inMemoryCache = new Map<
116+
CommandCacheKey,
117+
CommandCacheEntry<CommandCacheKey>
118+
>();
34119
const logger = getActionsLogger();
35120

36121
function getCommandCacheFilePath(): string {
@@ -41,7 +126,7 @@ function getCommandCacheFilePath(): string {
41126
* Reads and parses the temporary cache file. Best-effort: a missing, malformed,
42127
* or otherwise unreadable file is treated as an empty cache.
43128
*/
44-
function readCommandCacheFile(): Record<string, CommandCacheEntry> {
129+
function readCommandCacheFile(): Record<string, StoredCommandCacheEntry> {
45130
if (!fs.existsSync(getCommandCacheFilePath())) {
46131
return {};
47132
}
@@ -75,12 +160,12 @@ export function writeCommandCacheFile(): void {
75160
/**
76161
* Stores the output of a CLI command under `key` in a module-global object.
77162
*/
78-
export function cacheCommandOutput(
79-
key: CommandCacheKey,
163+
export function cacheCommandOutput<K extends CommandCacheKey>(
164+
key: K,
80165
cmd: string,
81-
output: unknown,
166+
output: CommandCacheKeyOutputMap[K],
82167
): void {
83-
const entry: CommandCacheEntry = { cmd, output };
168+
const entry: CommandCacheEntry<K> = { cmd, output };
84169
inMemoryCache.set(key, entry);
85170
}
86171

@@ -95,32 +180,33 @@ export function cacheCommandOutput(
95180
* A return value of `undefined` signals the caller to fall back to tier 3 (the
96181
* CLI).
97182
*/
98-
export function getCachedCommandOutput<T>(
99-
key: CommandCacheKey,
183+
export function getCachedCommandOutput<K extends CommandCacheKey>(
184+
key: K,
100185
cmd?: string,
101-
validate?: (output: unknown) => output is T,
102-
): T | undefined {
186+
): CommandCacheKeyOutputMap[K] | undefined {
103187
// Tier 1: the in-memory variable.
104188
const memoized = inMemoryCache.get(key);
105189
if (memoized !== undefined) {
106-
return memoized.output as T;
190+
return memoized.output as CommandCacheKeyOutputMap[K];
107191
}
108192

109193
// Tier 2: the temporary file persisted by an earlier step, if any.
110194
const entry = readCommandCacheFile()[key] as unknown;
111195
if (
112-
!json.isObject<CommandCacheEntry>(entry) ||
196+
!json.isObject<StoredCommandCacheEntry>(entry) ||
113197
!json.isString(entry.cmd) ||
114198
(cmd !== undefined && entry.cmd !== cmd) ||
115-
(validate !== undefined && !validate(entry.output))
199+
!commandCacheValidators[key](entry.output)
116200
) {
117201
logger.warning("Received invalid data from the command-cache file.");
118202
return undefined;
119203
}
120204

121205
// Memoize so subsequent lookups in this process hit tier 1.
122-
cacheCommandOutput(key, entry.cmd, entry.output);
123-
return entry.output as T;
206+
const cachedEntry = entry as StoredCommandCacheEntry;
207+
const output = cachedEntry.output as CommandCacheKeyOutputMap[K];
208+
cacheCommandOutput(key, cachedEntry.cmd, output);
209+
return output;
124210
}
125211

126212
/**

0 commit comments

Comments
 (0)