Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
Test cited source excerpts and share the contained local file reader
tt-a1i4cbbcb1e1508
diff --git a/archify/explainer/sources.mjs b/archify/explainer/sources.mjsindex 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.mjsindex 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');