{"title":"flow-map build","subtitle":"How build.mjs turns flow.json into one self-contained page, reading every excerpt from disk so the page can only show lines that exist.","root":"main","views":{"main":{"title":"build.mjs","layers":[{"id":"caller","label":"Caller"},{"id":"cli","label":"Entry"},{"id":"stage","label":"Stages"},{"id":"read","label":"File reading"},{"id":"disk","label":"Disk"}],"nodes":[{"id":"agent","label":"Agent","kind":"user","layer":"caller","sub":"runs the build"},{"id":"entry","label":"Entry","kind":"function","layer":"cli","file":"scripts/build.mjs","lines":[22,43],"note":"Takes exactly two paths plus an optional --root (default: the current folder) and loads flow.json; an unreadable flow exits 1.","excerpt":["const args = process.argv.slice(2);","const rootIx = args.indexOf('--root');","if (rootIx >= 0 && !args[rootIx + 1]) { console.error(USAGE); process.exit(2); }","const root = resolve(rootIx >= 0 ? args[rootIx + 1] : process.cwd());","const positional = rootIx >= 0 ? args.filter((_, i) => i !== rootIx && i !== rootIx + 1) : args;","if (positional.length !== 2) { console.error(USAGE); process.exit(2); }","const [flowPath, outPath] = positional;","","const here = dirname(fileURLToPath(import.meta.url));","let flow;","try { flow = JSON.parse(readFileSync(flowPath, 'utf8')); }","catch (e) { console.error(`flow-map: cannot read ${flowPath}: ${e.message}`); process.exit(1); }","const errors = validateShape(flow);","if (errors.length) {"," console.error(`flow-map: ${errors.length} problem(s)\\n- ${errors.join('\\n- ')}`);"," process.exit(1);","}","try {"," if (!statSync(root).isDirectory()) throw new Error('not a directory');","} catch { console.error('flow-map: --root must be an existing directory'); process.exit(1); }","const fail = msg => errors.push(msg);","const fileCache = new Map();"]},{"id":"validate","label":"Flow checks","kind":"function","layer":"stage","file":"scripts/build.mjs","lines":[87,126],"note":"Checks every view's layers, nodes, edges and steps, labels included, and cuts an excerpt for each file reference.","excerpt":[" if (!v.title) fail(`${at}: title is required`);"," const layers = new Set((v.layers ?? []).map(l => l.id));"," if (!layers.size) fail(`${at}: needs at least one layer`);"," for (const l of v.layers ?? []) if (!l.label) fail(`${at}.layers.${l.id}: label is required`);"," const nodes = new Set();"," for (const n of v.nodes ?? []) {"," const w = `${at}.nodes.${n.id}`;"," if (nodes.has(n.id)) fail(`${w}: duplicate id`);"," nodes.add(n.id);"," if (!n.label) fail(`${w}: label is required`);"," if (!layers.has(n.layer)) fail(`${w}: unknown layer \"${n.layer}\"`);"," if (!KINDS.has(n.kind)) fail(`${w}: unknown kind \"${n.kind}\"`);"," if (n.drill && !Object.hasOwn(flow.views, n.drill)) fail(`${w}: drill target \"${n.drill}\" is not a view`);"," delete n.excerpt;"," if (n.file) n.excerpt = excerpt(w, n.file, n.lines);"," }"," const edges = new Set();"," for (const e of v.edges ?? []) {"," const w = `${at}.edges.${e.id}`;"," if (edges.has(e.id)) fail(`${w}: duplicate id`);"," edges.add(e.id);"," if (!nodes.has(e.from)) fail(`${w}: unknown from \"${e.from}\"`);"," if (!nodes.has(e.to)) fail(`${w}: unknown to \"${e.to}\"`);"," }"," if (!v.scenarios?.length) fail(`${at}: needs at least one scenario`);"," for (const sc of v.scenarios ?? []) {"," if (!sc.steps?.length) fail(`${at}.scenarios.${sc.id}: needs steps`);"," sc.steps?.forEach((st, i) => {"," const w = `${at}.scenarios.${sc.id}.steps[${i}]`;"," if (!st.say) fail(`${w}: say is required`);"," for (const id of st.nodes ?? []) if (!nodes.has(id)) fail(`${w}: unknown node \"${id}\"`);"," for (const id of st.edges ?? []) if (!edges.has(id)) fail(`${w}: unknown edge \"${id}\"`);"," st.nodes ??= [];"," for (const f of st.files ?? []) {"," if (f.role && !ROLES.has(f.role)) fail(`${w}: unknown role \"${f.role}\"`);"," f.excerpt = excerpt(`${w} ${f.path}`, f.path, f.lines);"," }"," });"," }"," v.nodes ??= []; v.edges ??= [];"]},{"id":"issues","label":"Issue checks","kind":"function","layer":"stage","file":"scripts/build.mjs","lines":[129,144],"note":"Checks each issue's severity, target and line, and attaches the two lines either side.","excerpt":["for (const i of flow.issues) {"," const w = `issues.${i.id}`;"," if (!SEVERITIES.has(i.severity)) fail(`${w}: severity must be one of ${[...SEVERITIES].join(', ')}`);"," const v = Object.hasOwn(flow.views, i.view) ? flow.views[i.view] : undefined;"," if (!v) { fail(`${w}: unknown view \"${i.view}\"`); continue; }"," if (!i.node && !i.edge) fail(`${w}: needs a node or an edge`);"," if (i.node && !v.nodes.some(n => n.id === i.node)) fail(`${w}: unknown node \"${i.node}\"`);"," if (i.edge && !v.edges.some(e => e.id === i.edge)) fail(`${w}: unknown edge \"${i.edge}\"`);"," if (!i.file) { fail(`${w}: file is required`); continue; }"," const all = readLines(i.file);"," if (!all) { fail(`${w}: file ${i.file} does not exist`); continue; }"," if (!inRoot(i.file)) { fail(`${w}: ${i.file} is outside ${root}`); continue; }"," if (!Number.isInteger(i.line) || i.line < 1 || i.line > all.length) { fail(`${w}: line ${i.line} is outside ${i.file}`); continue; }"," i.from = Math.max(1, i.line - 2);"," i.excerpt = all.slice(i.from - 1, Math.min(all.length, i.line + 2)).map(redact);","}"]},{"id":"problems","label":"Problem report","kind":"function","layer":"stage","file":"scripts/build.mjs","lines":[146,149],"note":"Prints every collected problem at once and exits 1 without writing a page.","excerpt":["if (errors.length) {"," console.error(`flow-map: ${errors.length} problem(s)\\n- ${errors.join('\\n- ')}`);"," process.exit(1);","}"]},{"id":"render","label":"Page assembly","kind":"function","layer":"stage","file":"scripts/build.mjs","lines":[151,162],"note":"Injects the title, icon sprite and flow data into the template, then writes the page, creating its folder.","excerpt":["const template = readFileSync(resolve(here, '../assets/template.html'), 'utf8');","const sprite = readFileSync(resolve(here, '../assets/icons.svg'), 'utf8');","const esc = t => t.replace(/&/g, '&').replace(/ esc(redact(flow.title)))"," .replace('', () => sprite)"," .replace('/*__FLOW_DATA__*/null', () => `JSON.parse(${JSON.stringify(JSON.stringify(flow, (key, value) => typeof value === 'string' ? redact(value) : value)).replace(/ all.length) { fail(`${where}: ${path} has ${all.length} lines, range ends at ${b}`); return undefined; }"," if (b - a + 1 > MAX_EXCERPT) { fail(`${where}: excerpt of ${b - a + 1} lines exceeds ${MAX_EXCERPT}; narrow it`); return undefined; }"," return all.slice(a - 1, b).map(redact);","}"]},{"id":"readLines","label":"readLines()","kind":"cache","layer":"read","file":"scripts/build.mjs","lines":[45,54],"note":"Checks the real path stays inside the project before reading and caching the file.","excerpt":["function readLines(path) {"," if (fileCache.has(path)) return fileCache.get(path);"," const abs = resolve(root, path);"," let lines = null;"," try {"," if (existsSync(abs) && inRoot(path) && statSync(abs).isFile()) lines = readFileSync(abs, 'utf8').split('\\n');"," } catch { /* Missing, unreadable, or broken symlink: report as a validation problem. */ }"," fileCache.set(path, lines);"," return lines;","}"]},{"id":"flow","label":"flow.json","kind":"file","layer":"disk","sub":"written by the agent"},{"id":"sources","label":"Project files","kind":"folder","layer":"disk","sub":"under --root"},{"id":"assets","label":"assets/","kind":"folder","layer":"disk","sub":"template, icons"},{"id":"page","label":"Page","kind":"file","layer":"disk","sub":"out.html"}],"edges":[{"id":"run","from":"agent","to":"entry","label":"node build.mjs","data":"flow, out, --root"},{"id":"load","from":"entry","to":"flow","label":"JSON.parse"},{"id":"check","from":"entry","to":"validate","label":"every view"},{"id":"cut","from":"validate","to":"excerpt","data":"path + lines"},{"id":"lines","from":"excerpt","to":"readLines"},{"id":"disk","from":"readLines","to":"sources","label":"read"},{"id":"checkIssues","from":"entry","to":"issues","label":"every issue"},{"id":"issueLines","from":"issues","to":"readLines","data":"line ± 2"},{"id":"fail","from":"entry","to":"problems","label":"any problem"},{"id":"exit1","from":"problems","to":"agent","label":"exit 1"},{"id":"assemble","from":"entry","to":"render","label":"no problems"},{"id":"template","from":"render","to":"assets","label":"read"},{"id":"write","from":"render","to":"page","label":"write"}],"scenarios":[{"id":"build","title":"Build a page","kind":"data","steps":[{"say":"The agent runs build.mjs with its flow.json, an output path and the project root.","nodes":["agent","entry"],"edges":["run"],"state":{"root":"--root or cwd"},"files":[{"path":"scripts/build.mjs","lines":[22,28],"role":"reads","note":"Paths in flow.json resolve against this root.","excerpt":["const args = process.argv.slice(2);","const rootIx = args.indexOf('--root');","if (rootIx >= 0 && !args[rootIx + 1]) { console.error(USAGE); process.exit(2); }","const root = resolve(rootIx >= 0 ? args[rootIx + 1] : process.cwd());","const positional = rootIx >= 0 ? args.filter((_, i) => i !== rootIx && i !== rootIx + 1) : args;","if (positional.length !== 2) { console.error(USAGE); process.exit(2); }","const [flowPath, outPath] = positional;"]}]},{"say":"The entry reads and parses flow.json.","nodes":["entry","flow"],"edges":["load"],"state":{"flow":"parsed"},"files":[{"path":"scripts/build.mjs","lines":[30,33],"role":"reads","excerpt":["const here = dirname(fileURLToPath(import.meta.url));","let flow;","try { flow = JSON.parse(readFileSync(flowPath, 'utf8')); }","catch (e) { console.error(`flow-map: cannot read ${flowPath}: ${e.message}`); process.exit(1); }"]}]},{"say":"Every node, edge and step is checked, and each file reference is cut into an excerpt.","nodes":["entry","validate","excerpt"],"edges":["check","cut"],"state":{"problems":"collecting"},"files":[{"path":"scripts/build.mjs","lines":[92,102],"role":"calls","note":"Node ids, layers, kinds and drill targets.","excerpt":[" for (const n of v.nodes ?? []) {"," const w = `${at}.nodes.${n.id}`;"," if (nodes.has(n.id)) fail(`${w}: duplicate id`);"," nodes.add(n.id);"," if (!n.label) fail(`${w}: label is required`);"," if (!layers.has(n.layer)) fail(`${w}: unknown layer \"${n.layer}\"`);"," if (!KINDS.has(n.kind)) fail(`${w}: unknown kind \"${n.kind}\"`);"," if (n.drill && !Object.hasOwn(flow.views, n.drill)) fail(`${w}: drill target \"${n.drill}\" is not a view`);"," delete n.excerpt;"," if (n.file) n.excerpt = excerpt(w, n.file, n.lines);"," }"]},{"path":"scripts/build.mjs","lines":[114,124],"role":"calls","note":"Step node and edge ids, file roles and excerpts.","excerpt":[" sc.steps?.forEach((st, i) => {"," const w = `${at}.scenarios.${sc.id}.steps[${i}]`;"," if (!st.say) fail(`${w}: say is required`);"," for (const id of st.nodes ?? []) if (!nodes.has(id)) fail(`${w}: unknown node \"${id}\"`);"," for (const id of st.edges ?? []) if (!edges.has(id)) fail(`${w}: unknown edge \"${id}\"`);"," st.nodes ??= [];"," for (const f of st.files ?? []) {"," if (f.role && !ROLES.has(f.role)) fail(`${w}: unknown role \"${f.role}\"`);"," f.excerpt = excerpt(`${w} ${f.path}`, f.path, f.lines);"," }"," });"]}]},{"say":"excerpt() reads the file from the project root, refuses paths that escape it, checks the range and redacts secrets.","nodes":["excerpt","readLines","sources"],"edges":["lines","disk"],"files":[{"path":"scripts/build.mjs","lines":[62,78],"role":"defines","excerpt":["function excerpt(where, path, lines) {"," if (path.endsWith('/')) {"," if (!existsSync(resolve(root, path)) || !statSync(resolve(root, path)).isDirectory()) fail(`${where}: folder ${path} does not exist`);"," else if (!inRoot(path)) fail(`${where}: ${path} is outside ${root}`);"," if (lines) fail(`${where}: a folder takes no line range`);"," return undefined;"," }"," const all = readLines(path);"," if (!all) { fail(`${where}: file ${path} does not exist under ${root}`); return undefined; }"," if (!inRoot(path)) { fail(`${where}: ${path} is outside ${root}`); return undefined; }"," if (!lines) return undefined;"," const [a, b] = lines;"," if (!Number.isInteger(a) || !Number.isInteger(b) || a < 1 || b < a) { fail(`${where}: bad line range ${JSON.stringify(lines)}`); return undefined; }"," if (b > all.length) { fail(`${where}: ${path} has ${all.length} lines, range ends at ${b}`); return undefined; }"," if (b - a + 1 > MAX_EXCERPT) { fail(`${where}: excerpt of ${b - a + 1} lines exceeds ${MAX_EXCERPT}; narrow it`); return undefined; }"," return all.slice(a - 1, b).map(redact);","}"]},{"path":"scripts/build.mjs","lines":[45,54],"role":"reads","excerpt":["function readLines(path) {"," if (fileCache.has(path)) return fileCache.get(path);"," const abs = resolve(root, path);"," let lines = null;"," try {"," if (existsSync(abs) && inRoot(path) && statSync(abs).isFile()) lines = readFileSync(abs, 'utf8').split('\\n');"," } catch { /* Missing, unreadable, or broken symlink: report as a validation problem. */ }"," fileCache.set(path, lines);"," return lines;","}"]}]},{"say":"Each issue is checked against its view and file and given the lines around it.","nodes":["entry","issues","readLines"],"edges":["checkIssues","issueLines"],"files":[{"path":"scripts/build.mjs","lines":[129,144],"role":"defines","excerpt":["for (const i of flow.issues) {"," const w = `issues.${i.id}`;"," if (!SEVERITIES.has(i.severity)) fail(`${w}: severity must be one of ${[...SEVERITIES].join(', ')}`);"," const v = Object.hasOwn(flow.views, i.view) ? flow.views[i.view] : undefined;"," if (!v) { fail(`${w}: unknown view \"${i.view}\"`); continue; }"," if (!i.node && !i.edge) fail(`${w}: needs a node or an edge`);"," if (i.node && !v.nodes.some(n => n.id === i.node)) fail(`${w}: unknown node \"${i.node}\"`);"," if (i.edge && !v.edges.some(e => e.id === i.edge)) fail(`${w}: unknown edge \"${i.edge}\"`);"," if (!i.file) { fail(`${w}: file is required`); continue; }"," const all = readLines(i.file);"," if (!all) { fail(`${w}: file ${i.file} does not exist`); continue; }"," if (!inRoot(i.file)) { fail(`${w}: ${i.file} is outside ${root}`); continue; }"," if (!Number.isInteger(i.line) || i.line < 1 || i.line > all.length) { fail(`${w}: line ${i.line} is outside ${i.file}`); continue; }"," i.from = Math.max(1, i.line - 2);"," i.excerpt = all.slice(i.from - 1, Math.min(all.length, i.line + 2)).map(redact);","}"]}]},{"say":"With no problems, the template and icon sprite are read and the page is written.","nodes":["entry","render","assets","page"],"edges":["assemble","template","write"],"state":{"problems":"0","page":"written"},"files":[{"path":"scripts/build.mjs","lines":[151,162],"role":"writes","excerpt":["const template = readFileSync(resolve(here, '../assets/template.html'), 'utf8');","const sprite = readFileSync(resolve(here, '../assets/icons.svg'), 'utf8');","const esc = t => t.replace(/&/g, '&').replace(/ esc(redact(flow.title)))"," .replace('', () => sprite)"," .replace('/*__FLOW_DATA__*/null', () => `JSON.parse(${JSON.stringify(JSON.stringify(flow, (key, value) => typeof value === 'string' ? redact(value) : value)).replace(/ MAX_EXCERPT) { fail(`${where}: excerpt of ${b - a + 1} lines exceeds ${MAX_EXCERPT}; narrow it`); return undefined; }"]}]},{"say":"Every problem is printed at once and the build exits 1 without writing a page.","nodes":["entry","problems","agent"],"edges":["fail","exit1"],"state":{"page":"not written","exitCode":"1"},"files":[{"path":"scripts/build.mjs","lines":[146,149],"role":"writes","note":"Writes to stderr only.","excerpt":["if (errors.length) {"," console.error(`flow-map: ${errors.length} problem(s)\\n- ${errors.join('\\n- ')}`);"," process.exit(1);","}"]}]}]}]},"excerpt":{"title":"excerpt()","layers":[{"id":"input","label":"Reference"},{"id":"checks","label":"Checks"},{"id":"output","label":"Result"}],"nodes":[{"id":"ref","label":"path + lines","kind":"state","layer":"input","sub":"from flow.json"},{"id":"folder","label":"Folder check","kind":"function","layer":"checks","file":"scripts/build.mjs","lines":[63,67],"note":"A path ending in / must exist inside the project and takes no line range.","excerpt":[" if (path.endsWith('/')) {"," if (!existsSync(resolve(root, path)) || !statSync(resolve(root, path)).isDirectory()) fail(`${where}: folder ${path} does not exist`);"," else if (!inRoot(path)) fail(`${where}: ${path} is outside ${root}`);"," if (lines) fail(`${where}: a folder takes no line range`);"," return undefined;"]},{"id":"range","label":"Range checks","kind":"function","layer":"checks","file":"scripts/build.mjs","lines":[69,76],"note":"The file must exist inside the project, symlinks resolved, and the range must be whole, in bounds and 40 lines or fewer.","excerpt":[" const all = readLines(path);"," if (!all) { fail(`${where}: file ${path} does not exist under ${root}`); return undefined; }"," if (!inRoot(path)) { fail(`${where}: ${path} is outside ${root}`); return undefined; }"," if (!lines) return undefined;"," const [a, b] = lines;"," if (!Number.isInteger(a) || !Number.isInteger(b) || a < 1 || b < a) { fail(`${where}: bad line range ${JSON.stringify(lines)}`); return undefined; }"," if (b > all.length) { fail(`${where}: ${path} has ${all.length} lines, range ends at ${b}`); return undefined; }"," if (b - a + 1 > MAX_EXCERPT) { fail(`${where}: excerpt of ${b - a + 1} lines exceeds ${MAX_EXCERPT}; narrow it`); return undefined; }"]},{"id":"redact","label":"Redaction","kind":"auth","layer":"output","file":"scripts/build.mjs","lines":[14,20],"note":"Masks secret-looking assignments, Bearer and Basic [redacted], key= query values and common token shapes.","excerpt":["const SECRETS = ["," [/((?:api[_-]?key|secret|token|password|passwd|private[_-]?key|service[_-]?role)[\\w-]*[\"']?\\s*[:=]\\s*)([\"']?)[^\"'\\s,;]{6,}\\2/gi, '$1[redacted]'],"," [/\\b((?:Bearer|Basic)\\s+)[\\w.~+/=-]{8,}/g, '$1[redacted]'],"," [/([?&](?:key|sig|signature|access_token)=)[^&#\\s\"']{6,}/gi, '$1[redacted]'],"," [/\\b(?:sk|pk|rk)[-_][\\w-]{16,}|\\bgh[pousr]_\\w{20,}|\\bgithub_pat_\\w{20,}|\\bAIza[\\w-]{30,}|\\bxox[abprs]-[\\w-]{10,}|\\bAKIA[0-9A-Z]{16}\\b|\\beyJ[\\w-]{8,}\\.[\\w-]{8,}\\.[\\w-]{8,}/g, '[redacted]'],","];","const redact = line => SECRETS.reduce((l, [re, to]) => l.replace(re, to), line);"]},{"id":"lines","label":"Excerpt lines","kind":"state","layer":"output","sub":"shown on the page"}],"edges":[{"id":"isFolder","from":"ref","to":"folder","label":"ends in /"},{"id":"isFile","from":"ref","to":"range","label":"file"},{"id":"slice","from":"range","to":"redact","data":"sliced lines"},{"id":"out","from":"redact","to":"lines"}],"scenarios":[{"id":"cut","title":"Cut one excerpt","kind":"system","steps":[{"say":"A folder reference only has to exist; it never carries lines.","nodes":["ref","folder"],"edges":["isFolder"],"files":[{"path":"scripts/build.mjs","lines":[63,67],"role":"defines","excerpt":[" if (path.endsWith('/')) {"," if (!existsSync(resolve(root, path)) || !statSync(resolve(root, path)).isDirectory()) fail(`${where}: folder ${path} does not exist`);"," else if (!inRoot(path)) fail(`${where}: ${path} is outside ${root}`);"," if (lines) fail(`${where}: a folder takes no line range`);"," return undefined;"]}]},{"say":"A file reference must resolve inside the project, then its range is checked against the file's length and the 40-line cap.","nodes":["ref","range"],"edges":["isFile"],"state":{"cap":"40 lines"},"files":[{"path":"scripts/build.mjs","lines":[69,76],"role":"defines","excerpt":[" const all = readLines(path);"," if (!all) { fail(`${where}: file ${path} does not exist under ${root}`); return undefined; }"," if (!inRoot(path)) { fail(`${where}: ${path} is outside ${root}`); return undefined; }"," if (!lines) return undefined;"," const [a, b] = lines;"," if (!Number.isInteger(a) || !Number.isInteger(b) || a < 1 || b < a) { fail(`${where}: bad line range ${JSON.stringify(lines)}`); return undefined; }"," if (b > all.length) { fail(`${where}: ${path} has ${all.length} lines, range ends at ${b}`); return undefined; }"," if (b - a + 1 > MAX_EXCERPT) { fail(`${where}: excerpt of ${b - a + 1} lines exceeds ${MAX_EXCERPT}; narrow it`); return undefined; }"]}]},{"say":"The slice is redacted line by line before it reaches the page.","nodes":["range","redact","lines"],"edges":["slice","out"],"state":{"secrets":"redacted"},"files":[{"path":"scripts/build.mjs","lines":[77,77],"role":"defines","excerpt":[" return all.slice(a - 1, b).map(redact);"]},{"path":"scripts/build.mjs","lines":[14,20],"role":"defines","excerpt":["const SECRETS = ["," [/((?:api[_-]?key|secret|token|password|passwd|private[_-]?key|service[_-]?role)[\\w-]*[\"']?\\s*[:=]\\s*)([\"']?)[^\"'\\s,;]{6,}\\2/gi, '$1[redacted]'],"," [/\\b((?:Bearer|Basic)\\s+)[\\w.~+/=-]{8,}/g, '$1[redacted]'],"," [/([?&](?:key|sig|signature|access_token)=)[^&#\\s\"']{6,}/gi, '$1[redacted]'],"," [/\\b(?:sk|pk|rk)[-_][\\w-]{16,}|\\bgh[pousr]_\\w{20,}|\\bgithub_pat_\\w{20,}|\\bAIza[\\w-]{30,}|\\bxox[abprs]-[\\w-]{10,}|\\bAKIA[0-9A-Z]{16}\\b|\\beyJ[\\w-]{8,}\\.[\\w-]{8,}\\.[\\w-]{8,}/g, '[redacted]'],","];","const redact = line => SECRETS.reduce((l, [re, to]) => l.replace(re, to), line);"]}]}]}]}},"issues":[]}