Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

Test cited source excerpts and share the contained local file reader

tt-a1i4cbbcb1e1508
diff --git a/archify/explainer/sources.mjs b/archify/explainer/sources.mjs
index d7ff8244..811b6b31 100644
--- a/archify/explainer/sources.mjs
+++ b/archify/explainer/sources.mjs
@@ -117,24 +117,33 @@ function readImage(document, baseDir, authoredPath, pointer) {
const expected = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif' }[path.extname(relative).toLowerCase()];
if (!expected) fail(document, `${pointer}/path`, 'image', 'asset-format', 'Only local PNG, JPEG, WebP and GIF images are supported.',
'Use a PNG, JPEG, WebP or GIF image.');
+ const bytes = readContained(document, baseDir, relative, pointer, 'image', MAX_IMAGE_BYTES, '8 MiB');
+ const mime = imageMime(bytes);
+ if (mime !== expected) fail(document, pointer, 'image', 'asset-format', 'The image bytes do not match a supported image format.',
+ 'Use a correctly encoded image whose extension matches its bytes.');
+ return { path: relative, mime, ...digest(bytes), dataUrl: `data:${mime};base64,${bytes.toString('base64')}` };
+}
+
+// Read a regular file inside baseDir without following links, and confirm it did not change meanwhile.
+function readContained(document, baseDir, relative, pointer, component, limit, limitText) {
+ const noun = component === 'image' ? 'image' : 'data file', Noun = noun[0].toUpperCase() + noun.slice(1);
let fd;
try {
const root = fs.realpathSync(baseDir);
const ancestors = [[root, fs.lstatSync(root)]];
let candidate = root;
- const parts = relative.split('/');
- for (const part of parts) {
+ for (const part of relative.split('/')) {
candidate = path.join(candidate, part);
const stat = fs.lstatSync(candidate);
- if (stat.isSymbolicLink()) fail(document, `${pointer}/path`, 'image', 'asset-symlink', 'Image paths may not traverse symbolic links.',
- 'Copy the image into the input directory as a regular file.');
+ if (stat.isSymbolicLink()) fail(document, `${pointer}/path`, component, 'asset-symlink', `${Noun} paths may not traverse symbolic links.`,
+ `Copy the ${noun} into the input directory as a regular file.`);
ancestors.push([candidate, stat]);
}
- if (!ancestors.at(-1)[1].isFile()) fail(document, pointer, 'image', 'asset-file', 'The image must be a regular file.', 'Use a regular image file.');
+ if (!ancestors.at(-1)[1].isFile()) fail(document, pointer, component, 'asset-file', `The ${noun} must be a regular file.`, `Use a regular ${noun}.`);
fd = fs.openSync(candidate, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
const before = fs.fstatSync(fd);
- if (!sameFile(before, ancestors.at(-1)[1]) || before.size > MAX_IMAGE_BYTES) fail(document, pointer, 'image', 'asset-size',
- 'The image changed or exceeds the 8 MiB size limit.', 'Use a stable image smaller than 8 MiB.');
+ if (!sameFile(before, ancestors.at(-1)[1]) || before.size > limit) fail(document, pointer, component, 'asset-size',
+ `The ${noun} changed or exceeds the ${limitText} size limit.`, `Use a stable ${noun} smaller than ${limitText}.`);
const bytes = Buffer.alloc(before.size);
let offset = 0;
while (offset < bytes.length) {
@@ -144,16 +153,13 @@ function readImage(document, baseDir, authoredPath, pointer) {
}
const unchanged = offset === bytes.length && sameFile(before, fs.fstatSync(fd))
&& ancestors.every(([file, stat]) => { const current = fs.lstatSync(file); return !current.isSymbolicLink() && sameFile(current, stat); });
- if (!unchanged) fail(document, pointer, 'image', 'asset-changed', 'The image path or bytes changed while being frozen.',
- 'Finish image updates before rendering again.');
- const mime = imageMime(bytes);
- if (mime !== expected) fail(document, pointer, 'image', 'asset-format', 'The image bytes do not match a supported image format.',
- 'Use a correctly encoded image whose extension matches its bytes.');
- return { path: relative, mime, ...digest(bytes), dataUrl: `data:${mime};base64,${bytes.toString('base64')}` };
+ if (!unchanged) fail(document, pointer, component, 'asset-changed', `The ${noun} path or bytes changed while being frozen.`,
+ `Finish ${noun} updates before rendering again.`);
+ return bytes;
} catch (error) {
if (error.archifyDiagnostics) throw error;
- fail(document, pointer, 'image', 'asset-read', 'The image cannot be read safely inside the input directory.',
- 'Use an accessible regular image file inside the input directory.');
+ fail(document, pointer, component, 'asset-read', `The ${noun} cannot be read safely inside the input directory.`,
+ `Use an accessible regular ${noun} inside the input directory.`);
} finally {
if (fd !== undefined) fs.closeSync(fd);
}
diff --git a/test/explainer-sources.test.mjs b/test/explainer-sources.test.mjs
index cd2bd028..ab2a5f66 100644
--- a/test/explainer-sources.test.mjs
+++ b/test/explainer-sources.test.mjs
@@ -129,13 +129,17 @@ test('unquoted config credentials are blocked while environment and code referen
}
});
-test('location references do not return code and code blocks cannot trust web/example sources', async t => {
+test('cited repository locations carry their pinned lines, unverifiable ones stay plain, and code blocks cannot trust web/example sources', async t => {
const data = fixture(t);
const doc = document(data.repository);
doc.panels[0].blocks = [];
const result = await resolveExplainerSources(doc, { repoRoot: data.root });
- assert.ok(!Object.hasOwn(result.sources.router, 'text'));
- assert.equal(result.dependencies.length, 0);
+ assert.equal(typeof result.sources.router.text, 'string', 'a cited location shows its lines on the page');
+ assert.equal(result.dependencies.length, 1, 'and freezes the file it was read from');
+ const absent = document(data.repository, { path: 'src/absent.js', lines: [1, 3] }); absent.panels[0].blocks = [];
+ const missing = await resolveExplainerSources(absent, { repoRoot: data.root });
+ assert.ok(!Object.hasOwn(missing.sources.router, 'text'), 'an unverifiable citation stays a plain reference');
+ assert.ok(!Object.hasOwn((await resolveExplainerSources(doc, {})).sources.router, 'text'), 'without a repository root nothing is read');
doc.sources = [{ id: 'router', title: 'Example', text: 'code' }];
doc.panels[0].blocks = [{ id: 'code', type: 'code', source: 'router' }];
await rejects(doc, {}, 'code-source');