crewforth 3.2.0-rc.1 → 3.2.0-rc.10

package/kit/eval/lib/crew-map/narrative.mjs

@@ -5,18 +5,27 @@
 // model fill them, and nothing else:
 //   node.narrative  { text, cites }  what the module is for, in at most two sentences; `cites` are "file:line"
 //                   strings, each one a line the scanner itself cited for THAT node (its evidence)
+//                   and, optionally, `layer` (one of LAYERS: where the module sits) and `domain` (what part of the
+//                   business it serves, a short phrase), both resting on the same cites
 //   doc.overview    { text, cites }  a short orientation for someone new to the project; its cites may be any
 //                   node's evidence
+//   doc.tour        [{ node, text, cites }]  one to eight stops a newcomer reads in order: each names a node of the
+//                   map, says in at most two sentences why to look there, and cites that node's own lines
 // A narrative with no citation, or one citing a line the scan did not read, is refused: the model may describe
 // what the scan found, not add to it. A scanner field changed by hand is refused too (validate).
 
 const MAX_NODE = 400;
 const MAX_OVERVIEW = 2000;
+const MAX_STOP = 300;
+const MAX_STOPS = 8;
+const MAX_DOMAIN = 60;
+export const LAYERS = ['ui', 'api', 'service', 'data', 'infra', 'tool', 'library'];
 
-/** The "file:line" a node's evidence lets a narrative cite. */
+/** The "file:line" a narrative of this node may cite. */
 export function citesOf(node) {
   const out = new Set();
-  for (const e of Array.isArray(node?.evidence) ? node.evidence : []) {
+  // Its evidence, its entry point and what its README says about it: every line the scan read for this node.
+  for (const e of [node?.evidence, node?.entryPoint?.evidence, node?.about?.evidence].flatMap((x) => (Array.isArray(x) ? x : []))) {
     if (e && typeof e.file === 'string' && Number.isInteger(e.line)) out.add(`${e.file}:${e.line}`);
   }
   return out;
@@ -35,11 +44,14 @@ const sentences = (t) => (String(t).trim().match(/[.!?](\s|$)/g) ?? []).length;
  * Why a narrative is not acceptable, or null when it is (null itself is: not written yet).
  * @param allowed  the set of "file:line" it may cite
  */
-export function problemOf(n, allowed, { max = MAX_NODE, twoSentences = true } = {}) {
+export function problemOf(n, allowed, { max = MAX_NODE, twoSentences = true, module = false } = {}) {
   if (n === null || n === undefined) return null;
   if (typeof n !== 'object' || Array.isArray(n)) return 'is not { text, cites }';
-  const keys = Object.keys(n).sort().join();
-  if (keys !== 'cites,text') return `has fields other than text and cites (${keys})`;
+  const may = module ? ['cites', 'domain', 'layer', 'text'] : ['cites', 'text'];
+  const odd = Object.keys(n).filter((k) => !may.includes(k));
+  if (odd.length || !('text' in n) || !('cites' in n)) return `has fields other than ${may.join(', ')} (${Object.keys(n).sort().join()})`;
+  if ('layer' in n && !LAYERS.includes(n.layer)) return `names the layer ${JSON.stringify(n.layer)}, not one of ${LAYERS.join(', ')}`;
+  if ('domain' in n && (typeof n.domain !== 'string' || !n.domain.trim() || n.domain.length > MAX_DOMAIN || /[.!?]/.test(n.domain))) return `has a domain that is not a short phrase (at most ${MAX_DOMAIN} characters, no sentence)`;
   if (typeof n.text !== 'string' || !n.text.trim()) return 'has no text';
   if (n.text.length > max) return `is ${n.text.length} characters, more than ${max}`;
   if (twoSentences && sentences(n.text) > 2) return 'is more than two sentences';
@@ -52,7 +64,24 @@ export function problemOf(n, allowed, { max = MAX_NODE, twoSentences = true } =
 /** The document without what the model may add: the scanner's fields alone. */
 export function strip(doc) {
   if (!doc || typeof doc !== 'object') return doc;
-  return { ...doc, nodes: (doc.nodes ?? []).map((n) => ({ ...n, narrative: null })), overview: null };
+  return { ...doc, nodes: (doc.nodes ?? []).map((n) => ({ ...n, narrative: null })), overview: null, tour: null };
+}
+
+/** Why a tour is not acceptable, or null when it is (null itself is: not written yet). */
+export function tourProblem(tour, doc) {
+  if (tour === null || tour === undefined) return null;
+  if (!Array.isArray(tour) || !tour.length || tour.length > MAX_STOPS) return `is not a list of 1 to ${MAX_STOPS} stops`;
+  const byId = new Map((doc?.nodes ?? []).map((n) => [n.id, n]));
+  const seen = new Set();
+  for (const [i, s] of tour.entries()) {
+    if (!s || typeof s !== 'object' || Array.isArray(s) || Object.keys(s).sort().join() !== 'cites,node,text') return `stop ${i + 1} is not { node, text, cites }`;
+    if (!byId.has(s.node)) return `stop ${i + 1} names ${JSON.stringify(s.node)}, which is not a node of this map`;
+    if (seen.has(s.node)) return `stop ${i + 1} names ${s.node} again: a tour stops at a node once`;
+    seen.add(s.node);
+    const p = problemOf({ text: s.text, cites: s.cites }, citesOf(byId.get(s.node)), { max: MAX_STOP });
+    if (p) return `stop ${i + 1} (${s.node}) ${p}`;
+  }
+  return null;
 }
 
 /**
@@ -65,7 +94,7 @@ export function carry(old, fresh) {
   const nodes = fresh.nodes.map((n) => {
     const nar = was.get(n.id);
     if (nar === null || nar === undefined) return n;
-    if (problemOf(nar, citesOf(n)) === null) { kept += 1; return { ...n, narrative: nar }; }
+    if (problemOf(nar, citesOf(n), { module: n.kind === 'module' }) === null) { kept += 1; return { ...n, narrative: nar }; }
     dropped += 1; return n;
   });
   const doc = { ...fresh, nodes };
@@ -73,6 +102,9 @@ export function carry(old, fresh) {
     if (problemOf(old.overview, allCites(doc), { max: MAX_OVERVIEW, twoSentences: false }) === null) { doc.overview = old.overview; kept += 1; }
     else dropped += 1;
   }
+  if (old?.tour != null) {
+    if (tourProblem(old.tour, doc) === null) { doc.tour = old.tour; kept += 1; } else dropped += 1;
+  }
   return { doc, kept, dropped };
 }
 
@@ -89,10 +121,12 @@ export function validate(file, fresh, serialize) {
   }
   const byId = new Map((fresh.nodes ?? []).map((n) => [n.id, n]));
   for (const n of file.nodes ?? []) {
-    const p = problemOf(n.narrative, citesOf(byId.get(n.id) ?? n));
+    const p = problemOf(n.narrative, citesOf(byId.get(n.id) ?? n), { module: (byId.get(n.id) ?? n).kind === 'module' });
     if (p) out.push({ at: n.id, message: `the narrative ${p}` });
   }
   const p = problemOf(file.overview, allCites(fresh), { max: MAX_OVERVIEW, twoSentences: false });
   if (p) out.push({ at: 'overview', message: `the overview ${p}` });
+  const t = tourProblem(file.tour, fresh);
+  if (t) out.push({ at: 'tour', message: `the tour ${t}` });
   return out;
 }

package/kit/eval/lib/crew-map/project.mjs

@@ -130,14 +130,15 @@ export function risky(text, patterns) {
 // A host is the only part of a connection string or URL the map keeps. Credentials are cut off first; then a host
 // that looks like a secret by Crewforth's own scanner patterns is replaced. Without those patterns every host is
 // replaced: a map with fewer names is a smaller loss than one that published a token.
-export function loadSecretPatterns(fromDir) {
+// skip: pattern lines left out, as written (a project's .secret-allowlist.txt names the exact line it allows).
+export function loadSecretPatterns(fromDir, skip = new Set()) {
   for (const rel of ['../../../hooks/secret-blocklist.txt', '../../../../hooks/secret-blocklist.txt']) {
     const f = path.join(fromDir, rel);
     let text; try { text = fs.readFileSync(f, 'utf8'); } catch { continue; }
     const out = [];
     for (const raw of text.split('\n')) {
       const l = raw.replace(/\r$/, '');
-      if (!l || l.startsWith('#')) continue;
+      if (!l || l.startsWith('#') || skip.has(l)) continue;
       const js = l.replace(/\[\[:alnum:\]\]/g, '[A-Za-z0-9]').replace(/\[:alnum:\]/g, 'A-Za-z0-9')
         .replace(/\[:space:\]/g, '\\s').replace(/\[:alpha:\]/g, 'A-Za-z').replace(/\[:digit:\]/g, '0-9');
       try { out.push(new RegExp(js)); } catch { /* a pattern JS cannot read is skipped; the rest still apply */ }

package/kit/eval/lib/crew-map/rules/tech.json

@@ -0,0 +1,35 @@
+{
+  "about": "What a module is built with, in the words a newcomer reads: a package a manifest declares, or a file the module holds, gives a label. One list for every stack; a label is shown once per module, frameworks before tools, in the order of this file. Versions are not part of a label: the manifest line the label was read from is the module's evidence.",
+  "packages": {
+    "npm": [
+      ["next", "Next.js"], ["react", "React"], ["vue", "Vue"], ["svelte", "Svelte"], ["@angular/core", "Angular"],
+      ["astro", "Astro"], ["react-native", "React Native"], ["expo", "Expo"], ["electron", "Electron"],
+      ["hono", "Hono"], ["express", "Express"], ["fastify", "Fastify"], ["@nestjs/core", "NestJS"], ["koa", "Koa"],
+      ["graphql", "GraphQL"], ["socket.io", "Socket.IO"], ["wrangler", "Cloudflare Workers"],
+      ["@prisma/client", "Prisma"], ["prisma", "Prisma"], ["drizzle-orm", "Drizzle"], ["typeorm", "TypeORM"],
+      ["mongoose", "Mongoose"], ["tailwindcss", "Tailwind CSS"], ["vite", "Vite"], ["typescript", "TypeScript"],
+      ["vitest", "Vitest"], ["jest", "Jest"], ["@playwright/test", "Playwright"]
+    ],
+    "pypi": [
+      ["django", "Django"], ["fastapi", "FastAPI"], ["flask", "Flask"], ["sqlalchemy", "SQLAlchemy"],
+      ["celery", "Celery"], ["pydantic", "Pydantic"], ["langchain", "LangChain"], ["torch", "PyTorch"],
+      ["transformers", "Transformers"], ["spacy", "spaCy"], ["uvicorn", "Uvicorn"], ["pytest", "pytest"]
+    ],
+    "pub": [
+      ["flutter_riverpod", "Riverpod"], ["hooks_riverpod", "Riverpod"], ["riverpod", "Riverpod"],
+      ["flutter_bloc", "Bloc"], ["bloc", "Bloc"], ["provider", "Provider"], ["get", "GetX"], ["go_router", "go_router"],
+      ["dio", "Dio"], ["http", "http"], ["drift", "Drift"], ["sqflite", "sqflite"], ["hive", "Hive"], ["isar", "Isar"],
+      ["firebase_core", "Firebase"], ["freezed", "Freezed"], ["google_mobile_ads", "Google Mobile Ads"],
+      ["in_app_purchase", "In-app purchase"], ["flutter_test", "flutter_test"]
+    ],
+    "go": [
+      ["github.com/gin-gonic/gin", "Gin"], ["github.com/labstack/echo/v4", "Echo"], ["github.com/go-chi/chi/v5", "chi"],
+      ["gorm.io/gorm", "GORM"]
+    ]
+  },
+  "files": [
+    ["wrangler.toml", "Cloudflare Workers"], ["wrangler.jsonc", "Cloudflare Workers"], ["tsconfig.json", "TypeScript"],
+    ["Dockerfile", "Docker"], ["vercel.json", "Vercel"], ["netlify.toml", "Netlify"], ["fly.toml", "Fly.io"],
+    ["firebase.json", "Firebase"]
+  ]
+}

package/kit/eval/lib/crew-map/scan.mjs

@@ -24,15 +24,15 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { openProject, loadSecretPatterns, makeHostFilter, sortEv, bearsValues, risky, spawned, isTestPath } from './project.mjs';
-import { scanStacks } from './stacks.mjs';
-import { externals, configuration, codeUrls, endpoints, containers } from './surface.mjs';
+import { openProject, loadSecretPatterns, makeHostFilter, sortEv, bearsValues, risky, spawned, isTestPath, ev } from './project.mjs';
+import { scanStacks, applyTech } from './stacks.mjs';
+import { externals, configuration, codeUrls, servedCalls, endpoints, containers } from './surface.mjs';
 import { detect } from './detect.mjs';
 import { stamp, write, serialize, validate, OUT_DIR } from '../findings/findings.mjs';
 import { carry, strip, validate as validateNarrative } from './narrative.mjs';
 
 // Languages with source the scanner has no reader for, by extension.
-const UNREAD = { dart: 'Dart', swift: 'Swift', rb: 'Ruby', php: 'PHP', rs: 'Rust', scala: 'Scala', ex: 'Elixir', exs: 'Elixir',
+const UNREAD = { swift: 'Swift', rb: 'Ruby', php: 'PHP', rs: 'Rust', scala: 'Scala', ex: 'Elixir', exs: 'Elixir',
   c: 'C', cc: 'C++', cpp: 'C++', m: 'Objective-C', mm: 'Objective-C', lua: 'Lua', clj: 'Clojure', hs: 'Haskell', erl: 'Erlang' };
 
 const SELF = fileURLToPath(import.meta.url);
@@ -43,6 +43,50 @@ const MAX_EV = 5;
 const load = (f) => JSON.parse(fs.readFileSync(path.join(HERE, 'rules', f), 'utf8'));
 const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
 
+/**
+ * What is inside a module, for a reader who has not opened it: its folders and how many source files each holds.
+ * A folder holding nearly everything (lib/ of a Flutter app, src/ of a package) is opened one level, at most twice,
+ * so the rows say lib/data and lib/features and not just lib. Tests are counted apart. Twelve rows at most.
+ */
+const MAX_ROWS = 12;
+
+/**
+ * What a module says about itself: the first line of prose in its own README (a heading, a badge, an image, an
+ * HTML tag or a code fence is not prose). Kept apart from the evidence, which is cut at five lines, so a
+ * description always has a line to rest on that says what the module is for. Measured on a real project: four of
+ * ten modules were left undescribed because the only line the scan cited for them was the manifest's name.
+ */
+function aboutOf(pj, m) {
+  const base = m.dir === '.' ? '' : `${m.dir}/`;
+  const f = pj.files.find((x) => x.startsWith(base) && /^readme(\.(md|markdown|txt|rst))?$/i.test(x.slice(base.length)));
+  const src = f && pj.read(f); if (!src) return null;
+  let fence = false;
+  for (const [i, raw] of src.lines.entries()) {
+    const l = raw.trim();
+    if (/^(```|~~~)/.test(l)) { fence = !fence; continue; }
+    if (fence || !l || /^(#|=+$|-+$|\[!|!\[|<|\||>\s*\[!)/.test(l)) continue;
+    return { evidence: [ev(f, i + 1, l.slice(0, 60))] };
+  }
+  return null;
+}
+function structure(m) {
+  const base = m.dir === '.' ? '' : `${m.dir}/`;
+  let rel = m.files.filter((f) => !isTestPath(f)).map((f) => f.slice(base.length));
+  const tests = m.files.length - rel.length;
+  let at = '';
+  const group = (list) => { const g = new Map(); for (const r of list) { const k = r.includes('/') ? r.split('/')[0] : ''; g.set(k, (g.get(k) ?? 0) + 1); } return g; };
+  for (let d = 0; d < 2 && rel.length; d++) {
+    const [top, n] = [...group(rel)].sort((a, b) => b[1] - a[1] || cmp(a[0], b[0]))[0];
+    if (!top || n / rel.length < 0.8 || !rel.some((r) => r.startsWith(`${top}/`) && r.split('/').length > 2)) break;
+    at += `${top}/`; rel = rel.filter((r) => r.startsWith(`${top}/`)).map((r) => r.slice(top.length + 1));
+  }
+  const rows = [...group(rel)].map(([k, n]) => ({ folder: k ? `${at}${k}` : (at.replace(/\/$/, '') || '.'), files: n }))
+    .sort((a, b) => b.files - a.files || cmp(a.folder, b.folder));
+  const shown = rows.slice(0, MAX_ROWS);
+  const rest = rows.slice(MAX_ROWS).reduce((s, r) => s + r.files, 0);
+  return { folders: shown, ...(rest ? { otherFiles: rest } : {}), testFiles: tests };
+}
+
 // opts.hostFilter replaces the masking: ONLY the gate's must-fail twin uses it. No command-line flag reaches it.
 export function scan(root = '.', opts = {}) {
   const pj = openProject(root);
@@ -51,10 +95,12 @@ export function scan(root = '.', opts = {}) {
   const rules = load('packages.json'); const names = load('names.json');
   const stdlib = new Set(load('python-stdlib.json').modules);
   const st = scanStacks(pj);
+  applyTech(st, pj, load('tech.json'));
   const out = { edges: [], notMeasured: st.notMeasured, configUrls: [], codeHosts: new Set(), patterns };
   const ex = externals(pj, st, rules, hostOf, out);
   const cfg = configuration(pj, st, rules, hostOf, ex, out);
   codeUrls(pj, st, hostOf, ex, out);
+  servedCalls(pj, st, ex, out);
   const eps = endpoints(pj, st, out);
   const services = containers(pj, st, rules, hostOf, ex, cfg, out);
   const findings = detect({ st, cfg, eps, names, stdlib, notMeasured: out.notMeasured, configUrls: out.configUrls, codeHosts: out.codeHosts });
@@ -73,6 +119,9 @@ export function scan(root = '.', opts = {}) {
     const lang = UNREAD[/\.([a-z]+)$/i.exec(f)?.[1]?.toLowerCase()];
     if (lang && !isTestPath(f)) unread.set(lang, (unread.get(lang) ?? 0) + 1);
   }
+  // Dart is read through its pubspec.yaml: a .dart file no package owns has no module to be drawn in, so it is said.
+  const loose = pj.files.filter((f) => /\.dart$/.test(f) && !isTestPath(f) && !st.modules.some((m) => m.stack === 'dart' && m.files.includes(f))).length;
+  if (loose) out.notMeasured.push({ what: `Dart source outside any pubspec.yaml (${loose} file${loose === 1 ? '' : 's'})`, reason: 'no package owns it: it is not on the map' });
   for (const [lang, n] of unread) out.notMeasured.push({ what: `${lang} source (${n} file${n === 1 ? '' : 's'})`, reason: 'no reader for this language: its modules, dependencies and endpoints are not on the map' });
 
   // ---- one edge per (from, to, kind, confidence), its evidence merged ----
@@ -94,6 +143,8 @@ export function scan(root = '.', opts = {}) {
       // line to cite: the entry is then the file, and it says so.
       ...(m.entry ? { entryPoint: m.entryEv ? { evidence: [m.entryEv] } : { file: m.entryFile, evidence: [] } } : {}),
       dependencies: m.deps.length,
+      structure: structure(m),
+      ...((() => { const a = aboutOf(pj, m); return a ? { about: a } : {}; })()),
       ...capped(m.evidence), narrative: null })),
     ...services.map((s) => ({ id: s.id, kind: 'service', name: s.name, ...(s.image ? { image: s.image } : {}), ...capped(s.evidence), narrative: null })),
     ...[...ex.ext.values()].map((n) => ({ id: n.id, kind: 'external', resource: n.resource, label: n.label, hosts: [...n.hosts].sort(), ...capped(n.evidence), narrative: null })),
@@ -122,6 +173,7 @@ export function scan(root = '.', opts = {}) {
     findings,
     notMeasured: [...nm.values()].sort((a, b) => cmp(`${a.what}\u0000${a.reason}`, `${b.what}\u0000${b.reason}`)),
     overview: null,
+    tour: null,
   };
   // The last net, whatever cited it: a quote is cut before anything that looks like a credential, and a line that
   // carries values (by its file, or by what is on it) is never hashed.

package/kit/eval/lib/crew-map/stacks.mjs

@@ -1,5 +1,5 @@
 // stacks.mjs — modules, their declared dependencies, their imports and their references to each other, for the
-// five stacks. Every fact carries the line it was read from; what cannot be read is returned as notMeasured.
+// six stacks. Every fact carries the line it was read from; what cannot be read is returned as notMeasured.
 //
 // A module is { id, name, stack, dir, manifest, tech[], evidence[], deps[], refs[], imports[], entry, entryEv,
 //              aliases[], selfNames[], files[] }.
@@ -10,7 +10,7 @@
 // (a namespace prefix, a Gradle line read by pattern).
 
 import path from 'node:path';
-import { parseJsonc, parseToml, parseXml, xKids, xKid, xText, xLine, xFind, Unsupported } from './parse.mjs';
+import { parseJsonc, parseToml, parseXml, parseYaml, yGet, xKids, xKid, xText, xLine, xFind, Unsupported } from './parse.mjs';
 import { ev, evFirst, lineOf, isTestPath } from './project.mjs';
 
 const P = path.posix;
@@ -20,7 +20,7 @@ const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 const isComment = (l) => /^\s*(\/\/|#|\*|\/\*|<!--)/.test(l);
 
 export const SOURCE_EXT = {
-  node: /\.(m?[jt]sx?|cjs|cts|mts)$/, python: /\.py$/, go: /\.go$/, dotnet: /\.cs$/, java: /\.(java|kt)$/,
+  node: /\.(m?[jt]sx?|cjs|cts|mts)$/, python: /\.py$/, go: /\.go$/, dotnet: /\.cs$/, java: /\.(java|kt)$/, dart: /\.dart$/,
 };
 
 function mod(stack, name, manifest, dir) {
@@ -28,6 +28,22 @@ function mod(stack, name, manifest, dir) {
     imports: [], entry: false, entryEv: null, aliases: [], selfNames: [name], files: [] };
 }
 
+/**
+ * What each module is built with, from rules/tech.json: a package its manifest declares, or a file at its root.
+ * Labels are words a newcomer reads (Hono, Cloudflare Workers, Flutter), not versions; frameworks before tools, in
+ * the order of the rules. Before, only nine npm frameworks were named and a Node module read as "node".
+ */
+export function applyTech(st, pj, rules) {
+  const has = new Set(pj.files);
+  for (const m of st.modules) {
+    const deps = new Set(m.deps.map((d) => `${d.eco}\t${d.name}`));
+    for (const [eco, list] of Object.entries(rules?.packages ?? {})) for (const [name, label] of list) if (deps.has(`${eco}\t${name}`)) m.tech.add(label);
+    const base = m.dir === '.' ? '' : `${m.dir}/`;
+    for (const [file, label] of rules?.files ?? []) if (has.has(`${base}${file}`)) m.tech.add(label);
+    if (m.stack === 'node' && !m.tech.has('TypeScript') && m.files.some((f) => /\.(ts|tsx|mts|cts)$/.test(f))) m.tech.add('TypeScript');
+  }
+}
+
 // A version the map may show. A dependency can be declared by URL (git+https://token@host/repo.git#v1), and a URL
 // is never copied out: it reads as 'url', which no detector compares.
 export function cleanVersion(v) {
@@ -48,7 +64,7 @@ function runnable(m) {
 
 // Hand each source file to the deepest module of its stack whose directory holds it.
 // A file under a sample project's own manifest (left out of discovery) belongs to that sample, so to nobody here.
-const MANIFEST = /(^|\/)(package\.json|pyproject\.toml|setup\.cfg|requirements[^/]*\.txt|go\.mod|[^/]+\.(cs|fs|vb)proj|pom\.xml|build\.gradle(\.kts)?|settings\.gradle(\.kts)?)$/;
+const MANIFEST = /(^|\/)(package\.json|pyproject\.toml|setup\.cfg|requirements[^/]*\.txt|go\.mod|[^/]+\.(cs|fs|vb)proj|pom\.xml|build\.gradle(\.kts)?|settings\.gradle(\.kts)?|pubspec\.yaml)$/;
 function own(modules, files, stack) {
   const mine = modules.filter((m) => m.stack === stack).sort((a, b) => b.dir.length - a.dir.length);
   const samples = files.filter((f) => MANIFEST.test(f) && isTestPath(f)).map(dirOf);
@@ -76,9 +92,6 @@ function nodeStack(pj, out) {
       if (!v[sect] || typeof v[sect] !== 'object') continue;
       for (const [dn, ver] of Object.entries(v[sect])) m.deps.push({ eco: 'npm', name: dn, version: cleanVersion(ver), dev, peer: sect === 'peerDependencies', ev: ev(f, L([sect, dn]), dn) });
     }
-    for (const fw of ['next', 'react', 'vue', 'svelte', '@angular/core', 'express', 'fastify', '@nestjs/core', 'vite']) {
-      const d = m.deps.find((x) => x.name === fw && x.version !== 'url'); if (d) m.tech.add(`${fw}@${d.version.replace(/^[\^~>=<\s]+/, '')}`);
-    }
     if (v.bin) { m.entry = true; m.entryEv = ev(f, L(['bin']), 'bin'); }
     else if (v.scripts && (v.scripts.start || v.scripts.dev)) { const k = v.scripts.start ? 'start' : 'dev'; m.entry = true; m.entryEv = ev(f, L(['scripts', k]), k); }
     else if (v.workspaces) { m.entry = true; m.entryEv = ev(f, L(['workspaces']), 'workspaces'); }
@@ -265,6 +278,98 @@ function goStack(pj, out) {
   }
 }
 
+// ---- Dart / Flutter -------------------------------------------------------------------------------------------
+// One module per pubspec.yaml. A `path:` dependency names another module of this repository (a reference); a
+// `sdk: flutter` dependency makes it a Flutter module. Its .dart files import `package:<name>/…`: another module's
+// name is a reference, anything else a package it uses; `dart:` is the SDK. lib/main.dart or bin/ is an entry, and
+// so is a tool/ script with a main() (`dart run tool/x.dart` is how a package's own command is run).
+// Before this reader, a Flutter repository's app and its packages were not on the map at all (measured on a real
+// project: 5 Dart modules, 949 .dart files, none drawn).
+function dartStack(pj, out) {
+  const made = [];
+  for (const f of pj.manifests.filter((x) => P.basename(x) === 'pubspec.yaml')) {
+    const src = pj.read(f); if (!src) continue;
+    let y; try { y = parseYaml(src.text); } catch (e) { out.notMeasured.push({ what: f, reason: `pubspec.yaml outside the subset this scanner reads: ${e.message}` }); continue; }
+    const nm = yGet(y, 'name');
+    if (!nm || nm.v.t !== 'str' || !nm.v.v) { out.notMeasured.push({ what: f, reason: 'pubspec.yaml has no name' }); continue; }
+    const m = mod('dart', nm.v.v, f, dirOf(f));
+    m.evidence.push(ev(f, nm.line, nm.v.v));
+    const paths = [];
+    for (const [key, dev] of [['dependencies', false], ['dev_dependencies', true]]) {
+      const block = yGet(y, key); if (!block || block.v.t !== 'map') continue;
+      for (const d of block.v.e) {
+        const e = ev(f, d.line, d.k);
+        if (d.v.t === 'map') {
+          const sdk = yGet(d.v, 'sdk'); const pth = yGet(d.v, 'path');
+          if (sdk && sdk.v.t === 'str') { if (sdk.v.v === 'flutter' && d.k === 'flutter') m.tech.add('Flutter'); continue; }
+          if (pth && pth.v.t === 'str') { paths.push({ to: P.normalize(P.join(m.dir === '.' ? '' : m.dir, pth.v.v)), name: d.k, ev: e }); continue; }
+          const v = yGet(d.v, 'version'); m.deps.push({ eco: 'pub', name: d.k, version: v && v.v.t === 'str' ? cleanVersion(v.v.v) : '', dev, ev: e });
+        } else {
+          m.deps.push({ eco: 'pub', name: d.k, version: d.v.t === 'str' ? cleanVersion(d.v.v) : '', dev, ev: e });
+        }
+      }
+    }
+    if (yGet(y, 'flutter')) m.tech.add('Flutter');
+    m._paths = paths;
+    out.modules.push(m); made.push(m);
+  }
+  if (!made.length) return;
+  own(out.modules, pj.files, 'dart');
+  const byName = new Map(made.map((m) => [m.name, m]));
+  for (const m of made) {
+    for (const p of m._paths) {
+      const t = made.find((o) => o.dir === p.to) ?? byName.get(p.name);
+      if (t && t !== m) m.refs.push({ to: t.id, toMod: t, ev: p.ev, confidence: 'evidence' });
+    }
+    delete m._paths;
+    for (const f of m.files) {
+      if (/(^|\/)(lib\/main\.dart|bin\/[^/]+\.dart)$/.test(f.slice(m.dir === '.' ? 0 : m.dir.length + 1)) && !m.entry) {
+        m.entry = true; m.entryEv = evFirst(f, pj.read(f)?.lines ?? []);
+      }
+      if (!m.entry && /^tool\/[^/]+\.dart$/.test(f.slice(m.dir === '.' ? 0 : m.dir.length + 1))) {
+        const i = (pj.read(f)?.lines ?? []).findIndex((l) => /^\s*(?:Future<void>|void)\s+main\s*\(/.test(l));
+        if (i >= 0) { m.entry = true; m.entryEv = ev(f, i + 1, 'main'); }
+      }
+      const src = pj.read(f); if (!src) continue;
+      src.lines.forEach((l, i) => {
+        const x = /^\s*(?:import|export)\s+['"]package:([A-Za-z0-9_]+)\/[^'"]*['"]/.exec(l);
+        if (!x) return;
+        const t = byName.get(x[1]);
+        if (t) { if (t !== m && !m.refs.some((r) => r.toMod === t)) m.refs.push({ to: t.id, toMod: t, ev: ev(f, i + 1, x[1]), confidence: 'evidence' }); return; }
+        if (x[1] === m.name) return;
+        m.imports.push({ spec: x[1], root: x[1], ev: ev(f, i + 1, x[1]), file: f });
+      });
+    }
+  }
+  // Flutter declares packages nothing imports (cupertino_icons is a font, flutter_lints a lint set, build_runner a
+  // command), so an unused-package rule would mostly be wrong here: it is not run, and that is said.
+  if (out.modules.some((m) => m.stack === 'dart')) out.notMeasured.push({ what: 'Dart package usage (dep-unused, dep-undeclared)', reason: 'Flutter declares packages that no file imports (fonts, lint sets, code generators), so a declared package is not proven unused' });
+}
+
+// A Flutter app holds its platforms as folders of their own: android/ is a Gradle project, ios/ an Xcode one. They
+// are how the app is built for each platform, not modules of the repository, so they are folded into the app: its
+// tech says Android / iOS, and the Gradle modules under it are not drawn on their own (measured on a real project:
+// two "unplaced" Gradle modules beside a Flutter app the map did not show).
+function foldPlatforms(pj, out) {
+  const apps = out.modules.filter((m) => m.stack === 'dart' && m.tech.has('Flutter'));
+  if (!apps.length) return;
+  const drop = new Set();
+  for (const a of apps) {
+    const base = a.dir === '.' ? '' : `${a.dir}/`;
+    for (const m of out.modules) {
+      if (m === a || m.stack !== 'java') continue;
+      if (m.dir === `${base}android` || m.dir.startsWith(`${base}android/`)) { drop.add(m); a.tech.add('Android'); }
+    }
+    if (pj.files.some((f) => f.startsWith(`${base}ios/`))) a.tech.add('iOS');
+  }
+  if (!drop.size) return;
+  out.modules = out.modules.filter((m) => !drop.has(m));
+  for (const m of out.modules) m.refs = m.refs.filter((r) => !drop.has(r.toMod));
+  // The Gradle notes were about those folders; with no Java module left on the map they speak of nothing.
+  if (!out.modules.some((m) => m.stack === 'java')) out.notMeasured = out.notMeasured.filter((x) => !JAVA_NOTES.has(x.what));
+}
+const JAVA_NOTES = new Set(['Gradle build logic', 'Java/Kotlin package usage (dep-unused, dep-undeclared)']);
+
 // ---- .NET ---------------------------------------------------------------------------------------------------
 function dotnetStack(pj, out) {
   const central = new Map();
@@ -425,12 +530,13 @@ export function scanStacks(pj0) {
   // Its source files still belong to the module that holds them (a test imports that module's dependencies).
   const pj = { ...pj0, manifests: pj0.files.filter((f) => !isTestPath(f)) };
   const out = { modules: [], notMeasured: [], globalAliases: [] };
-  for (const fn of [nodeStack, pythonStack, goStack, dotnetStack, javaStack]) {
+  for (const fn of [nodeStack, pythonStack, goStack, dartStack, dotnetStack, javaStack]) {
     try { fn(pj, out); } catch (e) {
       if (!(e instanceof Unsupported)) throw e;
       out.notMeasured.push({ what: fn.name, reason: e.message });
     }
   }
+  foldPlatforms(pj, out);
   // Two manifests with one name (a copy, a fork in a subdirectory) would share an id: the directory tells them apart.
   const count = new Map();
   for (const m of out.modules) count.set(m.id, (count.get(m.id) || 0) + 1);

package/kit/eval/lib/crew-map/surface.mjs

@@ -117,7 +117,7 @@ export function configuration(pj, st, rules, hostOf, ex, out) {
       src.lines.forEach((l, i) => {
         const m = /^\s*(ENV|ARG)\s+([A-Za-z_][A-Za-z0-9_]*)/i.exec(l); if (m) def(m[2], f, i + 1, 'dockerfile');
         const from = /^\s*FROM\s+(?:--platform=\S+\s+)?(\S+)/i.exec(l);
-        if (from) { const o = ownerOf(st.modules, f); if (o) o.tech.add(`image:${from[1]}`); }
+        if (from) { const o = ownerOf(st.modules, f); if (o) o.tech.add('Docker'); }   // the image itself is the line's evidence
       });
     }
   }
@@ -186,6 +186,52 @@ export function codeUrls(pj, st, hostOf, ex, out) {
   }
 }
 
+// ---- one module calling another at the address it is served on -----------------------------------------------
+// A module says where it is served in its own deployment file: wrangler routes and custom domains (Cloudflare
+// Workers), the app of fly.toml (<app>.fly.dev). Another module that writes that host, quoted on its own or as the
+// host of a URL, calls it: an app that builds Uri(host: 'api.x.app') never spells a URL, and before this a call
+// to the project's own server was drawn as an external API, or not at all.
+const SERVED_FILES = /(^|\/)(wrangler\.toml|wrangler\.jsonc?|fly\.toml)$/;
+export function servedCalls(pj, st, ex, out) {
+  const served = new Map();   // host -> module
+  for (const m of st.modules) {
+    for (const f of pj.files.filter((x) => SERVED_FILES.test(x) && dirOf(x) === m.dir)) {
+      const src = pj.read(f); if (!src) continue;
+      src.lines.forEach((l, i) => {
+        if (isComment(l)) return;
+        const hosts = [];
+        for (const x of l.matchAll(/["']?(?:pattern|route)["']?\s*[=:]\s*["']([^"']+)["']/g)) hosts.push(x[1]);
+        if (/fly\.toml$/.test(f)) { const a = /^\s*app\s*=\s*["']([a-z0-9-]+)["']/.exec(l); if (a) hosts.push(`${a[1]}.fly.dev`); }
+        for (const raw of hosts) {
+          const h = raw.replace(/^https?:\/\//, '').replace(/^\*\.?/, '').split('/')[0].toLowerCase();
+          if (!/^[a-z0-9-]+(\.[a-z0-9-]+)+$/.test(h) || isLocalHost(h) || served.has(h)) continue;
+          served.set(h, m); m.evidence.push(ev(f, i + 1, raw));
+        }
+      });
+    }
+  }
+  out.served = served;
+  if (!served.size) return;
+  for (const [h, to] of served) {
+    const q = h.replace(/[.]/g, '\\.');
+    const re = new RegExp(`(["'\`])${q}\\1|://${q}(?=[/:"'\`]|$)`);
+    for (const m of st.modules) {
+      if (m === to) continue;
+      for (const f of m.files) {
+        if (isTestPath(f)) continue;
+        const src = pj.read(f); if (!src) continue;
+        src.lines.forEach((l, i) => { if (!isComment(l) && re.test(l)) out.edges.push({ from: m.id, to: to.id, kind: 'calls', confidence: 'evidence', via: 'code', evidence: [ev(f, i + 1, h)] }); });
+      }
+    }
+    // The host was read as an external API: it is the project's own module, so its edges go there and the node goes.
+    const id = `ext:http-api:${h}`;
+    if (!ex.ext.has(id)) continue;
+    for (const e of out.edges) if (e.to === id) { e.to = to.id; e.kind = 'calls'; }
+    out.edges = out.edges.filter((e) => e.from !== e.to);
+    ex.ext.delete(id);
+  }
+}
+
 // ---- endpoints ----------------------------------------------------------------------------------------------
 // A path is compared in one spelling: lower case, one leading slash, no trailing slash, every parameter ({id},
 // :id, ${id}, <int:id>, {id:int}) as {}. A path whose start was built at run time (a variable before the first
@@ -224,6 +270,24 @@ function firstArg(L, i, from) {
   }
   return null;
 }
+// The arguments of a call whose `(` ends at `from` on line i, up to its own `)`, across at most four lines: strings
+// and nested brackets are stepped over, so `method:` is read from this call's options and never from the next call's.
+function callArgs(L, i, from) {
+  let out = ''; let depth = 0; let q = null;
+  for (let j = i; j < Math.min(L.length, i + 4); j++) {
+    const s = j === i ? L[i].slice(from) : L[j];
+    for (let k = 0; k < s.length; k++) {
+      const c = s[k];
+      if (q) { if (c === '\\') { out += c + (s[k + 1] ?? ''); k += 1; continue; } if (c === q) q = null; }
+      else if (c === '"' || c === "'" || c === '`') q = c;
+      else if (c === '(' || c === '[' || c === '{') depth += 1;
+      else if (c === ')' || c === ']' || c === '}') { if (depth === 0) return out; depth -= 1; }
+      out += c;
+    }
+    out += ' ';
+  }
+  return out;
+}
 // The names a module calls HTTP through: axios, and every `x = axios.create(…)` in any of its files (a client made
 // in lib/api.ts is called from every component). A name a file itself makes a server of is not one there.
 function httpClients(pj, m) {
@@ -312,8 +376,7 @@ export function endpoints(pj, st, out) {
           if (nm && nest !== null) add(provides, m, nm[1] === 'All' ? '*' : nm[1], join(nest, nm[2] || ''), f, i, `@${nm[1]}`);
           const fe = /\bfetch\(\s*(['"`])([^'"`]+)\1/.exec(l);
           if (fe && !/^https?:/.test(fe[2])) {
-            const win = L.slice(i, i + 4).join(' ');
-            const mt = /method\s*:\s*['"](\w+)['"]/.exec(win);
+            const mt = /method\s*:\s*['"](\w+)['"]/.exec(callArgs(L, i, fe.index + l.slice(fe.index).indexOf('(') + 1));
             add(consumes, m, mt ? mt[1] : 'GET', fe[2], f, i, fe[2]);
           }
           // `api.get<User[]>("/x")` and a call whose path is on the next line read alike.
@@ -322,6 +385,21 @@ export function endpoints(pj, st, out) {
           if (axa && axa.s && !/^https?:/.test(axa.s)) add(consumes, m, ax[2], axa.s, f, axa.at, axa.s);
         });
       }
+      // Dart consumers: a Dio client's relative path, and a full URL (http.get(Uri.parse(…)), Uri.https(host, path))
+      // only when its host is one this project serves; any other host is someone else's API. `$id` is a parameter.
+      if (/\.dart$/.test(f)) {
+        const ours = (h) => out.served?.has(h.toLowerCase());
+        const dp = (s) => s.replace(/\$\{[^}]*\}|\$\w+/g, '{x}');
+        L.forEach((l, i) => {
+          if (isComment(l)) return;
+          const dio = /\b(\w*[dD]io\w*|_?client|_?api)\.(get|post|put|patch|delete)(?:<[^()]*?>)?\(\s*(['"])(\/[^'"]*)\3/.exec(l);
+          if (dio) add(consumes, m, dio[2], dp(dio[4]), f, i, dio[4]);
+          const hp = /\.(get|post|put|patch|delete)\(\s*Uri\.parse\(\s*(['"])https?:\/\/([^/'"$]+)(\/[^'"]*)\2/.exec(l);
+          if (hp && ours(hp[3])) add(consumes, m, hp[1], dp(hp[4]), f, i, hp[4]);
+          const uh = /\bUri\.https?\(\s*(['"])([^'"$]+)\1\s*,\s*(['"])(\/[^'"]*)\3/.exec(l);
+          if (uh && ours(uh[2])) add(consumes, m, 'GET', dp(uh[4]), f, i, uh[4]);
+        });
+      }
       // Python: FastAPI / Flask / Django providers; requests / httpx consumers
       if (/\.py$/.test(f)) {
         const pre = new Map();

package/kit/eval/lib/gate-log.sh

@@ -0,0 +1,52 @@
+# Sourced, not run. The ONE rule for where the gate log is, for the gates that write it and everything that reads it
+# (the status line, gate-report, doctor). Studio's reader (server/lib/kit-telemetry.js) follows the same order.
+#
+#   1. CREW_GATE_LOG, when set: used as given (/dev/null turns recording off).
+#   2. .claude/gate-log.tsv, outside a git repository or where git ignores it (a full install ignores .claude/).
+#   3. Otherwise <git dir>/crewforth-gate-log.tsv: inside the repository's own .git, which is never committed.
+#      Before 3.2.0 the log was simply not written there, so a project that tracks .claude/ had no record of a
+#      refusal, no 🛡 on its status line and no note of a model the gate lowered (seen on a real project).
+#
+# Builtins only on the reading side, which the status line runs every few seconds. The writing side asks git
+# (one or two processes), and only when a decision is being logged.
+
+# The repository's git directory, from the project root up, without a process: _CREW_GD, or rc 1.
+crew_git_dir(){
+  local d="${1:-.}" n=0 l
+  _CREW_GD=""
+  while [ "$n" -lt 12 ]; do
+    if [ -d "$d/.git" ]; then _CREW_GD="$d/.git"; return 0; fi
+    if [ -f "$d/.git" ]; then
+      IFS= read -r l < "$d/.git" 2>/dev/null || l=""
+      case "$l" in "gitdir: "*) l="${l#gitdir: }"; l="${l%$'\r'}"
+        case "$l" in /*|[A-Za-z]:*) ;; *) l="$d/$l" ;; esac
+        [ -d "$l" ] && { _CREW_GD="$l"; return 0; } ;; esac
+      return 1
+    fi
+    [ "$d" = / ] && return 1
+    d="$d/.."; n=$((n+1))
+  done
+  return 1
+}
+
+# Where a gate writes: _CREW_GL ("" = nowhere). Run from the project root.
+crew_gate_log_write(){
+  _CREW_GL=""
+  if [ -n "${CREW_GATE_LOG:-}" ]; then _CREW_GL="$CREW_GATE_LOG"; return 0; fi
+  [ -d .claude ] || return 0
+  if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1 || git check-ignore -q .claude/gate-log.tsv 2>/dev/null; then
+    _CREW_GL=.claude/gate-log.tsv; return 0
+  fi
+  local g; g="$(git rev-parse --absolute-git-dir 2>/dev/null)" || g=""
+  [ -n "$g" ] && [ -d "$g" ] && _CREW_GL="$g/crewforth-gate-log.tsv"
+  return 0
+}
+
+# Where a reader finds it: _CREW_GL ("" = none yet). No process.
+crew_gate_log_read(){
+  _CREW_GL=""
+  if [ -n "${CREW_GATE_LOG:-}" ]; then _CREW_GL="$CREW_GATE_LOG"; return 0; fi
+  if [ -f .claude/gate-log.tsv ]; then _CREW_GL=.claude/gate-log.tsv; return 0; fi
+  crew_git_dir . && [ -f "$_CREW_GD/crewforth-gate-log.tsv" ] && _CREW_GL="$_CREW_GD/crewforth-gate-log.tsv"
+  return 0
+}