hullproof 0.0.0-stage → 0.5.0

package/dist/map/build.js

@@ -0,0 +1,253 @@
+import { cmp } from '../util.js';
+import { ENGINE_VERSION } from '../version.js';
+import { firebaseMap, supabaseMap } from './config.js';
+import { joinPath } from './entry.js';
+import { extractExpress } from './js-express.js';
+import { extractAiTools, extractJobs, extractNest } from './js-misc.js';
+import { extractNext } from './js-next.js';
+import { extractExpo } from './expo.js';
+import { extractGoAll, goFiles } from './go.js';
+import { extractLaravelAll, laravelFiles } from './laravel.js';
+import { FnIndex } from './light-index.js';
+import { extractRailsAll, railsFiles } from './rails.js';
+import { extractSpring, springFiles } from './spring.js';
+import { dotnetFiles, extractDotnet } from './dotnet.js';
+import { extractMobile, mobileFacts } from './mobile.js';
+import { cargoConfig, extractRust, rustFiles } from './rust.js';
+import { authHelperCandidates } from './candidates.js';
+import { extractPython } from './py.js';
+import { extractDjango } from './py-django.js';
+import { langOf, Repo } from './repo.js';
+// Web frameworks a built extractor reads, and ones it does not, by language group (stack.json framework ids).
+const READ_BY = { 'node-ts': ['nextjs', 'express', 'fastify', 'koa', 'hono', 'nestjs', 'trpc', 'react', 'expo'], python: ['flask', 'fastapi', 'django', 'quart', 'sanic', 'starlette'], go: ['chi', 'echo', 'fiber', 'gin', 'gorilla-mux'], ruby: ['rails'], php: ['laravel'], java: ['spring', 'spring-boot'], csharp: ['aspnet-core'] };
+const UNREAD = {
+    'node-ts': ['adonisjs', 'apollo-server', 'hapi', 'loopback', 'remix', 'sveltekit', 'nuxt', 'astro', 'socket.io', 'graphql'],
+    python: ['aiohttp', 'bottle', 'falcon', 'litestar', 'pyramid', 'tornado', 'gradio', 'streamlit'],
+    go: [], ruby: ['sinatra', 'grape', 'hanami', 'roda'],
+    php: ['symfony', 'slim', 'codeigniter', 'cakephp', 'yii', 'drupal', 'wordpress'],
+    java: ['quarkus', 'micronaut', 'javalin'], kotlin: ['ktor', 'spring', 'spring-boot'],
+    csharp: [], rust: ['actix-web', 'axum', 'rocket', 'warp'], elixir: ['phoenix', 'ecto'],
+    dart: ['dart-frog', 'shelf'], swift: ['vapor'],
+};
+const SERVER_LANGS = new Set(['java', 'kotlin', 'csharp', 'rust', 'scala', 'elixir', 'swift', 'dart', 'perl', 'c', 'cpp', 'lua', 'haskell', 'clojure', 'groovy', 'erlang', 'fsharp', 'ocaml', 'julia', 'r', 'visual-basic', 'zig', 'nim']);
+const inPrefix = (path, prefix) => prefix === '*' || prefix === '/' || path === prefix || path.startsWith(prefix.replace(/\/$/, '') + '/') || path.startsWith(prefix.replace(/\/$/, '') + '*');
+const ROUTE_FW = new Set(['express', 'flask', 'fastapi', 'quart', 'sanic', 'flask-restful']);
+const WEB_KINDS = new Set(['http_route', 'webhook', 'page']);
+const confOf = (c, cap) => (c === 'low' || cap === 'low' ? 'low' : c === 'medium' || cap === 'medium' ? 'medium' : 'high');
+function addProtections(ep, ps) {
+    const have = new Set(ep.protections.map((p) => `${p.kind}|${p.scope}|${p.file}|${p.line}|${p.via}`));
+    for (const p of ps) {
+        const k = `${p.kind}|${p.scope}|${p.file}|${p.line}|${p.via}`;
+        if (!have.has(k)) {
+            have.add(k);
+            ep.protections.push(p);
+        }
+    }
+    ep.protections.sort((a, b) => cmp(a.file, b.file) || a.line - b.line || cmp(a.kind, b.kind) || cmp(a.via, b.via) || cmp(a.scope, b.scope));
+}
+function prefixChain(mounts) {
+    const byTarget = new Map();
+    for (const m of mounts)
+        byTarget.set(m.target, [...(byTarget.get(m.target) ?? []), m]);
+    const resolve = (file, depth) => {
+        const ms = (byTarget.get(file) ?? []).slice().sort((a, b) => cmp(a.from, b.from) || a.line - b.line);
+        if (!ms.length || depth > 5)
+            return null;
+        const m = ms[0];
+        const up = resolve(m.from, depth + 1);
+        return { prefix: joinPath(up?.prefix ?? '', m.prefix), protections: [...(up?.protections ?? []), ...m.protections] };
+    };
+    const out = new Map();
+    for (const t of byTarget.keys()) {
+        const r = resolve(t, 0);
+        if (r)
+            out.set(t, r);
+    }
+    return out;
+}
+export function buildCodeMap(ctx) {
+    const repo = new Repo(ctx);
+    const all = { entries: [], gates: [], mounts: [] };
+    const merge = (x) => { all.entries.push(...x.entries); all.gates.push(...x.gates); all.mounts.push(...x.mounts); };
+    // A file the extractor throws on is skipped and counted, so the coverage row can say so.
+    const failed = [];
+    const guard = (file, f) => { try {
+        merge(f());
+    }
+    catch (e) {
+        failed.push({ file, message: e.message });
+    } };
+    for (const file of ctx.files) {
+        const lang = langOf(file);
+        if (!lang)
+            continue;
+        const v = repo.view(file);
+        if (!v)
+            continue;
+        if (lang === 'js') {
+            if (repo.isClient(v)) {
+                if (/(?:^|\/)page\.[cm]?[jt]sx?$/.test(file))
+                    guard(file, () => extractNext(repo, v));
+                continue;
+            }
+            guard(file, () => extractNext(repo, v));
+            guard(file, () => extractExpress(repo, v));
+            guard(file, () => extractNest(repo, v));
+            guard(file, () => extractJobs(repo, v));
+            guard(file, () => extractAiTools(repo, v));
+        }
+        else if (lang === 'py')
+            guard(file, () => extractPython(repo, v));
+    }
+    guard('(django url configuration)', () => extractDjango(repo));
+    if (goFiles(repo).length)
+        guard('(go routes)', () => extractGoAll(repo, new FnIndex(repo, 'go'), repo.local));
+    if (railsFiles(repo).routes.length)
+        guard('(rails routes)', () => extractRailsAll(repo, new FnIndex(repo, 'rb'), repo.local));
+    if (laravelFiles(repo).length)
+        guard('(laravel routes)', () => extractLaravelAll(repo, new FnIndex(repo, 'php'), repo.local));
+    if (springFiles(repo).length)
+        guard('(spring controllers)', () => extractSpring(repo, new FnIndex(repo, 'java'), repo.local));
+    if (dotnetFiles(repo).length)
+        guard('(aspnet routes)', () => extractDotnet(repo, new FnIndex(repo, 'cs'), repo.local));
+    guard('(android and ios configuration)', () => extractMobile(repo));
+    if (rustFiles(repo).length)
+        guard('(rust routes)', () => extractRust(repo));
+    guard('(expo router)', () => extractExpo(repo));
+    // Router mounts: routes registered in a mounted file live under the mount prefix and inherit its protections.
+    const chains = prefixChain(all.mounts);
+    for (const ep of all.entries) {
+        const c = chains.get(ep.file);
+        if (!c || !ROUTE_FW.has(ep.framework) || ep.path === null)
+            continue;
+        ep.path = joinPath(c.prefix, ep.path);
+        if (ep.confidence === 'high')
+            ep.confidence = 'medium';
+        addProtections(ep, c.protections.map((p) => ({ ...p, scope: 'router' })));
+    }
+    // Gates: middleware and guards that cover an entry point by path, file order or framework.
+    const gates = all.gates.slice().sort((a, b) => cmp(a.file, b.file) || a.line - b.line || cmp(a.id, b.id));
+    for (const ep of all.entries) {
+        if (!WEB_KINDS.has(ep.kind) && ep.kind !== 'server_action' && ep.kind !== 'graphql_resolver' && ep.kind !== 'rpc')
+            continue;
+        for (const g of gates) {
+            if (g.framework === 'spring' || g.framework === 'aspnet')
+                continue; // the extractor applied these rules itself, in order, first match wins
+            if (g.framework === 'express' && (g.file !== ep.file || g.line > ep.line))
+                continue;
+            if (g.framework === 'next-app' && !(ep.framework === 'next-app' || ep.framework === 'next-pages') || (g.framework === 'next-app' && ep.kind === 'server_action'))
+                continue;
+            if (g.framework === 'flask' && ep.framework !== 'flask' && ep.framework !== 'quart')
+                continue;
+            if (g.framework === 'nest' && ep.framework !== 'nest')
+                continue;
+            if (g.framework === 'django' && ep.framework !== 'django')
+                continue;
+            if (g.methods.length && ep.method && ep.method !== 'ANY' && !g.methods.includes(ep.method))
+                continue;
+            if (ep.path === null && !g.paths.includes('*'))
+                continue;
+            if (!g.paths.some((p) => ep.path === null ? p === '*' : inPrefix(ep.path, p)))
+                continue;
+            const cap = g.paths.includes('*') || g.kind === 'guard' || g.kind === 'global_pipe' ? g.confidence : 'medium';
+            addProtections(ep, g.protections.map((p) => ({ ...p, scope: g.kind === 'guard' || g.kind === 'global_pipe' ? 'global' : p.scope === 'router' ? 'router' : 'middleware', confidence: confOf(p.confidence, cap) })));
+        }
+    }
+    // Vercel cron paths: an entry point called by the platform scheduler.
+    try {
+        const vj = JSON.parse(ctx.text('vercel.json') || '{}');
+        for (const c of vj.crons ?? [])
+            for (const ep of all.entries)
+                if (c.path && ep.path && ep.path === joinPath('', c.path.split('?')[0]))
+                    ep.tags = [...new Set([...ep.tags, 'cron'])].sort();
+    }
+    catch { /* a vercel.json that does not parse adds no cron tags */ }
+    const seen = new Map();
+    for (const ep of all.entries)
+        if (!seen.has(ep.id))
+            seen.set(ep.id, ep);
+    const entries = [...seen.values()].sort((a, b) => cmp(a.file, b.file) || a.line - b.line || cmp(a.method ?? '', b.method ?? '') || cmp(a.path ?? '', b.path ?? '') || cmp(a.name ?? '', b.name ?? '') || cmp(a.kind, b.kind));
+    const by = (key) => { const o = {}; for (const e of entries)
+        o[key(e)] = (o[key(e)] ?? 0) + 1; return Object.fromEntries(Object.entries(o).sort(([a], [b]) => cmp(a, b))); };
+    const facts = mobileFacts(repo);
+    return {
+        schema_version: '1.0.0', engine_version: ENGINE_VERSION, commit: ctx.stack.commit,
+        coverage: coverage(ctx, entries, failed, facts, repo), entry_points: entries,
+        gates: gates.map((g) => ({ ...g, protections: g.protections.slice().sort((a, b) => a.line - b.line || cmp(a.kind, b.kind) || cmp(a.via, b.via)) })),
+        config: { supabase: supabaseMap(repo), firebase: firebaseMap(repo), android: facts.android, ios: facts.ios, cargo: cargoConfig(repo), secrets: facts.secrets, local_vocab: { auth_helpers: repo.local.auth_helpers, role_helpers: repo.local.role_helpers }, auth_helper_candidates: authHelperCandidates(repo, entries) },
+        counts: { entry_points: entries.length, by_kind: by((e) => e.kind), by_framework: by((e) => e.framework) },
+    };
+}
+function coverage(ctx, entries, failed, facts, repo) {
+    const frameworks = new Set([...ctx.stack.frameworks.map((f) => f.id), ...(ctx.stack.mobile ?? []).map((f) => f.id)]);
+    const rows = [];
+    const nodeTotal = entries.filter((e) => /\.[cm]?[jt]sx?$/.test(e.file)).length;
+    const count = (re) => entries.filter((e) => re.test(e.file)).length;
+    for (const l of ctx.stack.languages) {
+        const files = l.file_count ?? 0;
+        if (l.id === 'javascript' || l.id === 'typescript') {
+            const n = count(l.id === 'typescript' ? /\.[cm]?tsx?$/ : /\.[cm]?jsx?$/);
+            const unread = UNREAD['node-ts'].filter((f) => frameworks.has(f));
+            rows.push({ language: l.id, files, extractor: 'node-ts', status: unread.length ? 'partial' : 'mapped', entry_points: n, note: unread.length ? `Frameworks seen that this extractor does not read: ${unread.join(', ')}. Entry points they register may be missing.` : n === 0 && nodeTotal === 0 && READ_BY['node-ts'].some((f) => frameworks.has(f) && f !== 'react') ? 'A web framework was detected and no entry point was found. The routes may be registered in a way the extractor does not read.' : frameworks.has('expo') ? 'Next.js, Express family, NestJS, tRPC, Expo Router screens, API routes and deep links, jobs and AI tools are read.' : 'Next.js, Express family, NestJS, tRPC, jobs and AI tools are read.' });
+        }
+        else if (l.id === 'python') {
+            const n = count(/\.py$/);
+            const unread = UNREAD.python.filter((f) => frameworks.has(f));
+            rows.push({ language: l.id, files, extractor: 'python', status: unread.length ? 'partial' : 'mapped', entry_points: n, note: unread.length ? `Frameworks seen that this extractor does not read: ${unread.join(', ')}. Entry points they register may be missing.` : n === 0 && READ_BY.python.some((f) => frameworks.has(f)) ? 'A web framework was detected and no entry point was found. The routes may be registered in a way the extractor does not read.' : 'Flask, FastAPI, Django and REST framework, Celery and scheduler jobs, and AI tools are read.' });
+        }
+        else if (l.id === 'go' || l.id === 'ruby' || l.id === 'php') {
+            const ext = l.id === 'go' ? /\.go$/ : l.id === 'ruby' ? /\.rb$/ : /\.php$/;
+            const n = count(ext);
+            const unread = UNREAD[l.id].filter((f) => frameworks.has(f));
+            const readSeen = READ_BY[l.id].filter((f) => frameworks.has(f));
+            const name = l.id === 'go' ? 'go' : l.id === 'ruby' ? 'rails' : 'laravel';
+            const what = l.id === 'go' ? 'net/http, chi, gin, echo, fiber and gorilla/mux routes' : l.id === 'ruby' ? 'Rails routes (config/routes.rb) and controller filters' : 'Laravel routes (routes/*.php) and controller middleware';
+            let status = unread.length ? 'partial' : 'mapped';
+            let note = unread.length ? `Frameworks seen that this extractor does not read: ${unread.join(', ')}. Entry points they register may be missing.` : `${what[0].toUpperCase()}${what.slice(1)} are read.`;
+            if (l.id !== 'go' && !readSeen.length && n === 0 && !unread.length) {
+                status = 'partial';
+                note = `No ${l.id === 'ruby' ? 'Rails' : 'Laravel'} project was found, so no routes were read. Web code in ${l.id} files is not in this map.`;
+            }
+            else if (readSeen.length && n === 0)
+                note = 'A web framework was detected and no entry point was found. The routes may be registered in a way the extractor does not read.';
+            rows.push({ language: l.id, files, extractor: name, status, entry_points: n, note });
+        }
+        else if (l.id === 'java') {
+            const n = count(/\.java$/);
+            const unread = UNREAD.java.filter((f) => frameworks.has(f));
+            const springSeen = READ_BY.java.some((f) => frameworks.has(f));
+            rows.push({ language: 'java', files, extractor: 'spring', status: unread.length || !springSeen ? 'partial' : 'mapped', entry_points: n,
+                note: unread.length ? `Frameworks seen that this extractor does not read: ${unread.join(', ')}. Entry points they register may be missing.` : !springSeen ? 'No Spring project was found, so no routes were read. Web code in Java files is not in this map.' : n === 0 ? 'A web framework was detected and no entry point was found. The routes may be registered in a way the extractor does not read.' : 'Spring MVC controllers (@RestController, @Controller and the mapping annotations) are read, with method security annotations and the Spring Security filter chain rules.' });
+        }
+        else if (l.id === 'csharp') {
+            const n = count(/\.cs$/);
+            const aspSeen = READ_BY.csharp.some((f) => frameworks.has(f));
+            rows.push({ language: 'csharp', files, extractor: 'aspnet', status: aspSeen ? 'mapped' : 'partial', entry_points: n,
+                note: !aspSeen ? 'No ASP.NET Core project was found, so no routes were read. Web code in C# files is not in this map.' : n === 0 ? 'A web framework was detected and no entry point was found. The routes may be registered in a way the extractor does not read.' : 'ASP.NET Core controllers ([Route] and the [HttpGet] family) and minimal APIs (MapGet and the others, with MapGroup) are read, with [Authorize], [AllowAnonymous], RequireAuthorization and a fallback policy.' });
+        }
+        else if (l.id === 'kotlin' || l.id === 'swift' || l.id === 'rust') {
+            const fw = l.id === 'kotlin' ? 'android' : l.id === 'swift' ? 'ios' : 'axum|actix-web';
+            const n = entries.filter((e) => new RegExp(`^(?:${fw})$`).test(e.framework)).length;
+            const what = l.id === 'kotlin' ? 'AndroidManifest.xml (exported components and deep links) and the network security configuration' : l.id === 'swift' ? 'Info.plist (URL schemes, App Transport Security) and the entitlements (associated domains)' : 'Cargo.toml, and axum and actix web routes';
+            const read = l.id === 'rust' ? rustFiles(repo).length > 0 || (cargoConfig(repo)?.manifests.length ?? 0) > 0 : l.id === 'kotlin' ? (facts.android?.manifests.length ?? 0) > 0 : (facts.ios?.plists.length ?? 0) > 0;
+            rows.push(read
+                ? { language: l.id, files, extractor: l.id === 'kotlin' ? 'android' : l.id === 'swift' ? 'ios' : 'rust', status: 'partial', entry_points: n, note: `${what[0].toUpperCase()}${what.slice(1)} are read. ${l.id === 'rust' ? 'Handler bodies are not read.' : 'The source files are not read, so what a handler does with an incoming intent or URL is not in this map.'}` }
+                : { language: l.id, files, extractor: null, status: 'not_mapped', entry_points: 0, note: `No extractor input found for ${l.id}${(UNREAD[l.id] ?? []).filter((f) => frameworks.has(f)).length ? ` (frameworks seen: ${(UNREAD[l.id] ?? []).filter((f) => frameworks.has(f)).join(', ')})` : ''}. Entry points in ${l.id} files are not in this map.` });
+        }
+        else if (SERVER_LANGS.has(l.id)) {
+            const seen = (UNREAD[l.id] ?? []).filter((f) => frameworks.has(f));
+            rows.push({ language: l.id, files, extractor: null, status: 'not_mapped', entry_points: 0, note: `No extractor for ${l.id} yet${seen.length ? ` (frameworks seen: ${seen.join(', ')})` : ''}. Entry points in ${l.id} files are not in this map.` });
+        }
+    }
+    // Files an extractor threw on: the language they belong to is only partly mapped.
+    const langOfFailed = (file) => (/\.py$/.test(file) || /django/.test(file) ? 'python' : /\.go$|\(go /.test(file) ? 'go' : /\.rb$|\(rails /.test(file) ? 'ruby' : /\.php$|\(laravel /.test(file) ? 'php' : /\.tsx?$/.test(file) ? 'typescript' : 'javascript');
+    for (const f of failed) {
+        const lang = langOfFailed(f.file);
+        const row = rows.find((r) => r.language === lang) ?? rows[0];
+        if (row && !row.note.includes('could not be read')) {
+            row.status = 'partial';
+            row.note += ` ${failed.filter((x) => langOfFailed(x.file) === lang).length} file(s) could not be read by the extractor, first: ${f.file}.`;
+        }
+    }
+    return rows.sort((a, b) => cmp(a.language, b.language));
+}

package/dist/map/candidates.js

@@ -0,0 +1,49 @@
+const AUTHISH = /auth|login|logged|session|token|jwt|bearer|guard|protect|permission|member|tenant|signed|credential|principal|identity|viewer|whoami|current|require|ensure|verify|owner|account|user/i;
+const SKIP = /^(?:console|log|logger|status|json|send|redirect|render|parse|stringify|then|catch|require|import|function|return|if|for|while|switch|await|async|new|super|print|puts|len|str|int|dict|list|set|get|post|put|patch|delete|use|map|filter|reduce|find|from|select|where|insert|update|create|emit|on|once|next|type|isinstance|self|this|params|param|query|body|request|response|req|res|ctx|c|r|w|id|name|email|password|user|users|account|accounts|session|token|userId|user_id|accountId|find_by|find_by_id|findOne|findById|first|last|all|count|exists|save|destroy|build|new_record|dispatch|useState|useEffect|useMemo|useCallback|useRef|useRouter|useParams|useSearchParams|useLocalSearchParams|useNavigation|useRoute|useContext|useQuery|useMutation|useTranslation|useForm|useWatch|useTheme|useColorScheme|useWindowDimensions)$/;
+const MAX = 25;
+export function authHelperCandidates(repo, entries) {
+    const seen = new Map();
+    const judged = entries.filter((e) => !e.test_code && ['http_route', 'server_action', 'graphql_resolver', 'rpc'].includes(e.kind) && e.kind !== 'webhook' && (e.tags.includes('state_changing') || e.data.length > 0)
+        && !e.tags.includes('auth_endpoint') && !e.tags.includes('public') && !e.protections.some((p) => p.kind === 'session_read' && p.confidence !== 'low' && p.enforced !== false));
+    for (const e of judged) {
+        const file = e.handler?.file ?? e.file;
+        const first = e.handler?.line ?? e.line;
+        const lines = repo.ctx.text(file).split('\n').slice(Math.max(0, first - 4), Math.max(first, e.end_line));
+        const names = new Set();
+        const ruby = /\.rb$/.test(file);
+        if (ruby) {
+            // Class level filters of the controller that run before this action.
+            const action = e.name?.split('#')[1];
+            for (const fl of repo.ctx.text(file).matchAll(/^[ \t]*(?:prepend_)?before_action\b([^\n]*)$/gm)) {
+                const only = /\bonly:\s*(%i\[([^\]]*)\]|\[([^\]]*)\]|:(\w+))/.exec(fl[1]);
+                const except = /\bexcept:\s*(%i\[([^\]]*)\]|\[([^\]]*)\]|:(\w+))/.exec(fl[1]);
+                const list = (m) => (m ? (m[2] ?? m[3] ?? m[4] ?? '').split(/[\s,]+/).map((x) => x.replace(/^:/, '')).filter(Boolean) : []);
+                if (action && ((only && !list(only).includes(action)) || (except && list(except).includes(action))))
+                    continue;
+                for (const n of fl[1].replace(/\b(?:only|except|if|unless)\s*:.*$/, '').matchAll(/:(\w+[?!]?)/g))
+                    names.add(n[1]);
+            }
+        }
+        for (const l of lines) {
+            if (/^\s*(?:func|def|function|public|private|protected|class|module|before_action|prepend_before_action|skip_before_action|skip_before_filter|allow_unauthenticated_access)\b/.test(l))
+                continue;
+            const code = l.replace(/\/\/.*$|#(?!\[).*$/, '');
+            for (const m of code.matchAll(ruby ? /(?:@|->|::|\.|\b)([A-Za-z_$][\w$]*[!?]?)\s*(?:\(|\b(?=\s*$)|(?=\s*,|\s*\)))/g : /(?:@|->|::|\.|\b)([A-Za-z_$][\w$]*[!?]?)\s*(?:\(|(?=\s*,|\s*\)))/g))
+                names.add(m[1]);
+            for (const m of code.matchAll(/:(\w+[!?]?)/g))
+                if (/^\s*(?:before_action|skip_before_action)/.test(code))
+                    names.add(m[1]);
+        }
+        for (const n of names) {
+            if (n.length < 4 || SKIP.test(n) || !AUTHISH.test(n))
+                continue;
+            const cur = seen.get(n);
+            if (cur)
+                cur.n++;
+            else
+                seen.set(n, { n: 1, file: e.file, line: e.line });
+        }
+    }
+    return [...seen.entries()].map(([name, v]) => ({ name, entry_points: v.n, file: v.file, line: v.line }))
+        .sort((a, b) => b.entry_points - a.entry_points || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)).slice(0, MAX);
+}

package/dist/map/cblocks.js

@@ -0,0 +1,77 @@
+// Shared reading helpers for the annotation based languages (Java and Kotlin in Spring, C# attributes): split a class body into
+// declaration blocks, each with the annotations in front of it, and read string literals out of annotation arguments. Works on masked
+// text for structure and on the original text for the string values, which sit at the same positions.
+import { closeOf } from './lex.js';
+// Annotations of the form @Name or @Name(...) at brace depth 0 of the range [from, to), grouped into blocks of consecutive annotations.
+// `declStart` is the first character after the last annotation of the block (the declaration the annotations belong to).
+export function annotationBlocks(masked, from, to) {
+    const out = [];
+    let depth = 0;
+    let cur = null;
+    for (let i = from; i < to; i++) {
+        const c = masked[i];
+        if (c === '{' || c === '(' || c === '[') {
+            depth++;
+            continue;
+        }
+        if (c === '}' || c === ')' || c === ']') {
+            depth--;
+            continue;
+        }
+        if (depth !== 0 || c !== '@')
+            continue;
+        const m = /^@([A-Za-z_][\w.]*)/.exec(masked.slice(i, i + 80));
+        if (!m)
+            continue;
+        let end = i + m[0].length;
+        let args = null;
+        let k = end;
+        while (/[ \t]/.test(masked[k] ?? ''))
+            k++;
+        if (masked[k] === '(') {
+            const close = closeOf(masked, k);
+            if (close > 0) {
+                args = { start: k + 1, end: close - 1 };
+                end = close;
+            }
+        }
+        const gap = cur ? masked.slice(cur.annos[cur.annos.length - 1].end, i) : '';
+        if (cur && /^\s*$/.test(gap))
+            cur.annos.push({ name: m[1], start: i, end, args });
+        else {
+            cur = { annos: [{ name: m[1], start: i, end, args }], start: i, end: 0, declStart: 0 };
+            out.push(cur);
+        }
+        i = end - 1;
+    }
+    for (const b of out) {
+        b.end = b.annos[b.annos.length - 1].end;
+        let d = b.end;
+        while (/\s/.test(masked[d] ?? ''))
+            d++;
+        b.declStart = d;
+    }
+    return out;
+}
+// All "string" literals in the text, with the escapes of a quoted string left as written.
+export const strings = (text) => [...text.matchAll(/"((?:[^"\\\n]|\\.)*)"/g)].map((m) => m[1]);
+// Top level comma split of a parameter or argument list (commas inside (), [], {} and <> do not split).
+export function splitTop(text) {
+    const out = [];
+    let depth = 0;
+    let from = 0;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (c === '(' || c === '[' || c === '{' || c === '<')
+            depth++;
+        else if (c === ')' || c === ']' || c === '}' || (c === '>' && text[i - 1] !== '=' && text[i - 1] !== '-'))
+            depth = Math.max(0, depth - 1);
+        else if (c === ',' && depth === 0) {
+            out.push(text.slice(from, i));
+            from = i + 1;
+        }
+    }
+    if (text.slice(from).trim())
+        out.push(text.slice(from));
+    return out.map((x) => x.trim()).filter(Boolean);
+}