codebase-onboarder 0.1.0

package/shared/analyzer/services.js

@@ -0,0 +1,157 @@
+// Service and manifest detection: docker-compose services, package.json
+// (workspaces, scripts, entry points), Procfile. Regex/JSON based — a YAML
+// parser would be overkill for what is a navigational aid.
+
+export async function detectManifest(source) {
+  const manifest = { entryPoints: [], services: [], packageName: '', scripts: [], workspaces: [], deps: { npm: {}, dev: {}, pip: [], go: [], cargo: [] } };
+
+  // package.json
+  try {
+    const pkg = JSON.parse(await source.read('package.json'));
+    manifest.packageName = pkg.name || '';
+    manifest.scripts = Object.keys(pkg.scripts || {});
+    manifest.deps.npm = pkg.dependencies || {};
+    manifest.deps.dev = pkg.devDependencies || {};
+    if (pkg.main) manifest.entryPoints.push(pkg.main.replace(/^\.\//, ''));
+    if (pkg.bin) {
+      for (const p of Object.values(typeof pkg.bin === 'string' ? { bin: pkg.bin } : pkg.bin)) {
+        manifest.entryPoints.push(String(p).replace(/^\.\//, ''));
+      }
+    }
+    const ws = pkg.workspaces;
+    const list = Array.isArray(ws) ? ws : ws?.packages || [];
+    manifest.workspaces = list.map((w) => w.replace(/\/$/, ''));
+    if (manifest.scripts.some((s) => /start|serve|dev/.test(s))) {
+      manifest.hasServerScript = true;
+    }
+  } catch {
+    /* no package.json or unreadable — fine */
+  }
+
+  // requirements.txt
+  try {
+    manifest.deps.pip = parseRequirements(await source.read('requirements.txt'));
+  } catch { /* none */ }
+
+  // go.mod
+  try {
+    manifest.deps.go = parseGoRequires(await source.read('go.mod'));
+  } catch { /* none */ }
+
+  // Cargo.toml
+  try {
+    manifest.deps.cargo = parseCargoDeps(await source.read('Cargo.toml'));
+  } catch { /* none */ }
+
+  // docker-compose.yml / docker-compose.yaml / compose.yml
+  for (const name of ['docker-compose.yml', 'docker-compose.yaml', 'compose.yml', 'compose.yaml']) {
+    let text;
+    try {
+      text = await source.read(name);
+    } catch {
+      continue;
+    }
+    manifest.composeFile = name;
+    manifest.services = parseComposeServices(text);
+    break;
+  }
+
+  // Procfile
+  try {
+    const text = await source.read('Procfile');
+    for (const line of text.split('\n')) {
+      const m = line.match(/^([\w-]+):\s*(.+)$/);
+      if (m) manifest.services.push({ name: m[1], command: m[2].trim(), source: 'Procfile' });
+    }
+  } catch {
+    /* none */
+  }
+
+  return manifest;
+}
+
+export function parseRequirements(text) {
+  return String(text)
+    .split('\n')
+    .map((l) => l.split('#')[0].trim())
+    .filter(Boolean)
+    .map((l) => l.split(/[<>=!~;\[ ]/)[0].replace(/["']/g, '').trim())
+    .filter(Boolean);
+}
+
+export function parseGoRequires(text) {
+  const s = String(text);
+  const names = new Set();
+  const block = s.match(/require\s*\(([\s\S]*?)\)/);
+  const scoped = block ? block[1] : '';
+  const single = (s.match(/require\s+([\w./-]+)(?:\s+v[\w.\-+]+)?(?:\n|$)/) || [, ''])[1];
+  if (single) names.add(single);
+  for (const [, name] of (scoped.matchAll(/^\s*([\w./-]+)\s+v?[\w.\-+]*/gm) || [])) if (name) names.add(name);
+  const lines = scoped.length ? scoped.split('\n') : s.split('\n').filter((l) => l.trim().startsWith('require'));
+  for (const line of lines) {
+    const m = line.match(/\b([\w./-]+)\s+v[\w.\-+]+/);
+    if (m) names.add(m[1]);
+  }
+  // drop the standard library pseudo module
+  names.delete('.');
+  return [...names].sort();
+}
+
+export function parseCargoDeps(text) {
+  const s = String(text);
+  const sec = s.match(/\[dependencies\]([\s\S]*?)(?=\n\[|$)/);
+  const body = sec ? sec[1] : '';
+  const names = [];
+  for (const line of body.split('\n')) {
+    const m = line.match(/^([A-Za-z0-9_-]+)\s*(?:=\s*[^{]|\{)/);
+    if (m) names.push(m[1]);
+  }
+  return [...new Set(names)];
+}
+
+function parseComposeServices(text) {
+  const lines = text.split('\n');
+  const services = [];
+  let inServices = false;
+  let servicesIndent = 0;
+  let current = null;
+  let currentIndent = 0;
+
+  for (const line of lines) {
+    if (/^\s*#/.test(line) || line.trim() === '') continue;
+    const indent = line.length - line.trimStart().length;
+    const trimmed = line.trim();
+
+    if (!inServices) {
+      if (/^services:\s*$/.test(trimmed)) {
+        inServices = true;
+        servicesIndent = indent;
+      }
+      continue;
+    }
+
+    if (indent <= servicesIndent && !/^services:/.test(trimmed)) break; // left the block
+
+    const svcMatch = trimmed.match(/^([\w.-]+):\s*$/);
+    if (svcMatch && indent === servicesIndent + 2) {
+      current = { name: svcMatch[1], source: 'compose', ports: [], dependsOn: [] };
+      currentIndent = indent;
+      services.push(current);
+      continue;
+    }
+
+    if (!current || indent <= currentIndent) continue;
+
+    let m;
+    if ((m = trimmed.match(/^build:\s*(.+)$/))) {
+      current.build = m[1].trim();
+    } else if ((m = trimmed.match(/^image:\s*(.+)$/))) {
+      current.image = m[1].trim();
+    } else if ((m = trimmed.match(/^-\s*["']?(\d+):(\d+)/))) {
+      current.ports.push(m[1] + ':' + m[2]);
+    } else if ((m = trimmed.match(/^context:\s*(.+)$/))) {
+      current.build = m[1].trim();
+    }
+  }
+  return services;
+}

package/shared/analyzer/stack.js

@@ -0,0 +1,173 @@
+// Stack analytics: from the manifest's declared dependencies plus the scan
+// language counts, name the frameworks, libraries and languages a repo leans
+// on — each tagged with a category and the official docs URL. The docs URLs
+// feed the server-side /api/doc fetch (allowlisted) for informed summaries.
+
+// name -> [category, docs url]
+const KNOWN = {
+  react: ['Frontend framework', 'https://react.dev'],
+  'react-dom': ['Frontend framework', 'https://react.dev'],
+  '@angular/core': ['Frontend framework', 'https://angular.dev'],
+  vue: ['Frontend framework', 'https://vuejs.org'],
+  svelte: ['Frontend framework', 'https://svelte.dev'],
+  next: ['Web framework', 'https://nextjs.org/docs'],
+  nuxt: ['Web framework', 'https://nuxt.com/docs'],
+  remix: ['Web framework', 'https://remix.run/docs'],
+  gatsby: ['Web framework', 'https://www.gatsbyjs.com/docs'],
+  express: ['Web framework', 'https://expressjs.com'],
+  fastify: ['Web framework', 'https://fastify.dev'],
+  koa: ['Web framework', 'https://koajs.com'],
+  '@nestjs/core': ['Web framework', 'https://docs.nestjs.com'],
+  hapi: ['Web framework', 'https://hapi.dev'],
+  flask: ['Web framework', 'https://flask.palletsprojects.com'],
+  django: ['Web framework', 'https://docs.djangoproject.com'],
+  fastapi: ['Web framework', 'https://fastapi.tiangolo.com'],
+  'spring-boot': ['Web framework', 'https://docs.spring.io/spring-boot'],
+  laravel: ['Web framework', 'https://laravel.com/docs'],
+  rails: ['Web framework', 'https://guides.rubyonrails.org'],
+  gin: ['Web framework', 'https://gin-gonic.com'],
+  echo: ['Web framework', 'https://echo.labstack.com'],
+  fiber: ['Web framework', 'https://gofiber.io'],
+  'actix-web': ['Web framework', 'https://actix.rs'],
+  axum: ['Web framework', 'https://docs.rs/axum'],
+  rocket: ['Web framework', 'https://rocket.rs'],
+  prisma: ['Database / ORM', 'https://www.prisma.io/docs'],
+  sequelize: ['Database / ORM', 'https://sequelize.org'],
+  typeorm: ['Database / ORM', 'https://typeorm.io'],
+  sqlalchemy: ['Database / ORM', 'https://docs.sqlalchemy.org'],
+  'drizzle-orm': ['Database / ORM', 'https://orm.drizzle.team'],
+  mongoose: ['Database / ORM', 'https://mongoosejs.com'],
+  knex: ['Database / ORM', 'https://knexjs.org'],
+  pg: ['Database / ORM', 'https://node-postgres.com'],
+  pymongo: ['Database / ORM', 'https://pymongo.readthedocs.io'],
+  gorm: ['Database / ORM', 'https://gorm.io'],
+  sqlx: ['Database / ORM', 'https://docs.rs/sqlx'],
+  diesel: ['Database / ORM', 'https://diesel.rs'],
+  redis: ['Database / ORM', 'https://redis.io/docs/'],
+  jest: ['Testing', 'https://jestjs.io'],
+  vitest: ['Testing', 'https://vitest.dev'],
+  mocha: ['Testing', 'https://mochajs.org'],
+  '@testing-library/react': ['Testing', 'https://testing-library.com'],
+  pytest: ['Testing', 'https://docs.pytest.org'],
+  playwright: ['Testing', 'https://playwright.dev'],
+  cypress: ['Testing', 'https://docs.cypress.io'],
+  rspec: ['Testing', 'https://rspec.info'],
+  typescript: ['Tooling / build', 'https://www.typescriptlang.org/docs'],
+  vite: ['Tooling / build', 'https://vitejs.dev/guide/'],
+  webpack: ['Tooling / build', 'https://webpack.js.org'],
+  esbuild: ['Tooling / build', 'https://esbuild.github.io'],
+  babel: ['Tooling / build', 'https://babeljs.io/docs'],
+  rollup: ['Tooling / build', 'https://rollupjs.org'],
+  tailwindcss: ['UI / styling', 'https://tailwindcss.com/docs'],
+  bootstrap: ['UI / styling', 'https://getbootstrap.com/docs'],
+  sass: ['UI / styling', 'https://sass-lang.com/documentation'],
+  'styled-components': ['UI / styling', 'https://styled-components.com'],
+  axios: ['Networking', 'https://axios-http.com'],
+  requests: ['Networking', 'https://requests.readthedocs.io'],
+  urllib3: ['Networking', 'https://urllib3.readthedocs.io'],
+  httpx: ['Networking', 'https://www.python-httpx.org'],
+  passport: ['Auth', 'https://www.passportjs.org'],
+  'next-auth': ['Auth', 'https://next-auth.js.org'],
+  jsonwebtoken: ['Auth', 'https://github.com/auth0/node-jsonwebtoken'],
+  pydantic: ['Data validation', 'https://docs.pydantic.dev'],
+  numpy: ['Data / science', 'https://numpy.org/doc/'],
+  pandas: ['Data / science', 'https://pandas.pydata.org/docs/'],
+  'scikit-learn': ['Data / science', 'https://scikit-learn.org/stable/'],
+  torch: ['Data / science', 'https://pytorch.org/docs/'],
+  tensorflow: ['Data / science', 'https://www.tensorflow.org/api_docs'],
+  'opencv-python': ['Data / science', 'https://docs.opencv.org'],
+  keras: ['Data / science', 'https://keras.io'],
+  'python-dotenv': ['Tooling / config', 'https://github.com/theskumar/python-dotenv'],
+};
+
+const ORDER = [
+  'Web framework', 'Frontend framework', 'Database / ORM', 'Auth',
+  'Networking', 'Data / science', 'Data validation', 'UI / styling',
+  'Testing', 'Tooling / build', 'Tooling / config', 'Library',
+];
+
+// Where a dependency that is not in KNOWN sends you: its registry page. Named
+// here rather than inlined below because two things need them — the URL
+// builders, and the host allowlist under them.
+const REGISTRY = {
+  npm: (name) => `https://www.npmjs.com/package/${name}`,
+  pip: (name) => `https://pypi.org/project/${name}/`,
+  go: (name) => `https://pkg.go.dev/${name}`,
+  cargo: (name) => `https://docs.rs/${name}`,
+};
+
+// Every host `analyzeStack` can hand out a docs URL for. The server allowlists
+// exactly this set for `/api/doc`, and that is the SSRF guard: a host no
+// dependency name can produce is a host the server will not fetch.
+//
+// Derived, not restated. The server used to carry its own hand-written copy of
+// this list, and the two had drifted: `diesel.rs` was reachable from a Cargo
+// dependency but missing from the allowlist, so those docs always came back 403,
+// while `docusaurus.io`, `auth0.com` and a bare `readthedocs.io` were allowed
+// and nothing here could ever ask for them — the last one opening every project
+// on the site rather than the three we name.
+//
+// `www.` comes off because the caller strips it from the incoming host too;
+// leaving it on would mean `www.npmjs.com` never matched a request for
+// `npmjs.com`.
+export const DOC_HOSTS = Object.freeze([...new Set(
+  [
+    ...Object.values(KNOWN).map(([, url]) => url),
+    ...Object.values(REGISTRY).map((toUrl) => toUrl('any')),
+  ].map((url) => new URL(url).hostname.replace(/^www\./, ''))
+)].sort());
+
+function cleanVersion(v) {
+  return String(v || '').replace(/^[\^~>=< ]+/, '').split(' ')[0].trim();
+}
+
+export function analyzeStack(manifest = {}, languages = {}) {
+  const deps = manifest.deps || { npm: {}, dev: {}, pip: [], go: [], cargo: [] };
+  const items = [];
+  const seen = new Set();
+
+  const add = (name, version, category, lang, docs, dev = false) => {
+    if (!name || seen.has(name)) return;
+    seen.add(name);
+    items.push({ name, version: cleanVersion(version), category, lang, docs, dev });
+  };
+
+  const npmDocs = (name) => {
+    const k = KNOWN[name];
+    return k ? k[1] : REGISTRY.npm(name);
+  };
+  const catOf = (name) => {
+    const k = KNOWN[name];
+    return k ? k[0] : 'Library';
+  };
+
+  for (const [name, ver] of Object.entries(deps.npm || {})) {
+    if (name !== 'react-dom') add(name, ver, catOf(name), 'JavaScript', npmDocs(name), false);
+  }
+  for (const [name, ver] of Object.entries(deps.dev || {})) {
+    if (name !== 'react-dom') add(name, ver, catOf(name), 'JavaScript', npmDocs(name), true);
+  }
+  for (const name of deps.pip || []) {
+    const k = KNOWN[name];
+    add(name, '', k ? k[0] : 'Library', 'Python', k ? k[1] : REGISTRY.pip(name), false);
+  }
+  for (const name of deps.go || []) {
+    const k = KNOWN[name.split('/').pop()];
+    add(name, '', k ? k[0] : 'Library', 'Go', REGISTRY.go(name), false);
+  }
+  for (const name of deps.cargo || []) {
+    const k = KNOWN[name] || KNOWN[name.replace(/_/g, '-')];
+    add(name, '', k ? k[0] : 'Library', 'Rust', k ? k[1] : REGISTRY.cargo(name), false);
+  }
+
+  items.sort((a, b) => (ORDER.indexOf(a.category) - ORDER.indexOf(b.category)) || a.name.localeCompare(b.name));
+
+  const pm = [];
+  if (deps.npm && Object.keys(deps.npm).length) pm.push('npm');
+  if (deps.pip && deps.pip.length) pm.push('pip');
+  if (deps.go && deps.go.length) pm.push('go modules');
+  if (deps.cargo && deps.cargo.length) pm.push('cargo');
+
+  return { languages, pm, items: items.slice(0, 48) };
+}
+

package/shared/analyzer/tour.js

@@ -0,0 +1,69 @@
+// The guided walk: pick the handful of files a new teammate should see
+// first, in the order they should see them, each with a one-line reason why.
+//
+// This lives in `shared/` because two very different callers want the same
+// ordering: the browser draws it as a tour, and the MCP server hands it to an
+// agent as "read these eight files first". A second implementation would drift,
+// and a drifted tour would tell a person and an agent different things about the
+// same repository. `describeStop` is presentation for the browser's own chrome
+// and has no business here.
+
+import { baseName } from './pathUtil.js';
+
+export function buildTourStops(scan, facts) {
+  const stops = [];
+  const used = new Set();
+
+  const push = (path, why) => {
+    if (!path || used.has(path)) return;
+    if (!scan.files.some((f) => f.path === path)) return;
+    used.add(path);
+    stops.push({ path, why });
+  };
+
+  // 1. The front door: the entry point with the most reach.
+  const entriesByReach = facts.entries
+    .map((p) => ({ path: p, out: facts.fanOut[p] || 0 }))
+    .sort((a, b) => b.out - a.out);
+  if (entriesByReach.length) {
+    push(entriesByReach[0].path, 'Start here. This is a way in — code that runs first and calls everything else.');
+  }
+
+  // 2–4. The load-bearing files.
+  for (const hub of facts.hubs.slice(0, 3)) {
+    push(hub.path, `${hub.fanIn} files depend on this. Understand it before you change anything around it.`);
+  }
+
+  // 5. A second entry if there is one (servers often have a CLI beside them).
+  if (entriesByReach.length > 1) {
+    push(entriesByReach[1].path, 'Another door into the codebase — same building, different handle.');
+  }
+
+  // 6. A well-used leaf: end of a chain, usually where the real work happens.
+  const leaf = scan.files
+    .filter((f) => (facts.fanOut[f.path] || 0) === 0 && (facts.fanIn[f.path] || 0) >= 2)
+    .sort((a, b) => (facts.fanIn[b.path] || 0) - (facts.fanIn[a.path] || 0))[0];
+  if (leaf) {
+    push(leaf.path, 'The end of a chain. Nothing below it but the work itself.');
+  }
+
+  // 7. A cycle member, if the repo has them — worth the warning early.
+  if (facts.cycles.length) {
+    const member = facts.cycles[0][0];
+    push(member, `Careful with this one: it sits in a loop of ${facts.cycles[0].length} files importing each other.`);
+  }
+
+  // 8. An orphan, if any survive the earlier stops.
+  const orphan = facts.orphans.find((p) => !used.has(p));
+  if (orphan && stops.length < 8) {
+    push(orphan, 'Nothing imports this. Dead code, or a door we did not recognize — you decide.');
+  }
+
+  return stops.slice(0, 8);
+}
+
+// The name a stop shows in the browser's tour bar. Exported from here anyway so
+// neither caller has to import `baseName` just to label a stop.
+export function tourStopTitle(stop) {
+  return baseName(stop.path);
+}

package/shared/analyzer/util.js

@@ -0,0 +1,123 @@
+// Small text utilities shared by the language analyzers.
+
+// Blanks out comments while preserving string contents, offsets and line
+// numbers (every matched character becomes a space except newlines), so
+// positions reported afterwards still line up with the original source.
+export function blankComments(source, { block = true, line = true, lineChar = '//' } = {}) {
+  let out = source;
+  if (block) {
+    out = out.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '));
+  }
+  if (line && lineChar === '//') {
+    out = out.replace(/\/\/[^\n]*/g, (m) => ' '.repeat(m.length));
+  }
+  if (line && lineChar === '#') {
+    out = out.replace(/^[ \t]*#[^\n]*/gm, (m) => ' '.repeat(m.length));
+  }
+  return out;
+}
+
+export function lineOf(source, index) {
+  let line = 1;
+  for (let i = 0; i < index && i < source.length; i++) {
+    if (source.charCodeAt(i) === 10) line++;
+  }
+  return line;
+}
+
+// The same answer as `lineOf`, for callers that need many of them from one
+// source. `lineOf` walks from byte 0 every time, which is nothing once and
+// quadratic when a 200KB file reports 300 imports, functions and classes — each
+// scanning an average of half the file. This walks the source once, records
+// where every line starts, and binary-searches that table per lookup.
+//
+// The table is built on first use rather than up front, so a file that reports
+// no positions at all pays nothing for asking.
+export function lineCounter(source) {
+  const s = String(source);
+  let starts = null;
+
+  return function lineAt(index) {
+    if (!starts) {
+      starts = [0];
+      for (let i = 0; i < s.length; i++) {
+        if (s.charCodeAt(i) === 10) starts.push(i + 1);
+      }
+    }
+    // The line containing `index` is the last one that starts at or before it.
+    let lo = 0;
+    let hi = starts.length - 1;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1;
+      if (starts[mid] <= index) lo = mid;
+      else hi = mid - 1;
+    }
+    return lo + 1;
+  };
+}
+
+// Returns the index just past the brace that closes the one at openIndex.
+// Best-effort: a brace inside a string can throw the count off, which is an
+// accepted trade of the no-parser approach.
+export function braceBodyEnd(source, openIndex) {
+  let depth = 0;
+  for (let i = openIndex; i < source.length; i++) {
+    const c = source[i];
+    if (c === '{') depth++;
+    else if (c === '}') {
+      depth--;
+      if (depth === 0) return i + 1;
+    }
+  }
+  return source.length;
+}
+
+export function uniqueBy(items, key) {
+  const seen = new Set();
+  const out = [];
+  for (const item of items) {
+    const k = key(item);
+    if (seen.has(k)) continue;
+    seen.add(k);
+    out.push(item);
+  }
+  return out;
+}
+
+// Which of `names` is called inside `body`? Returns the distinct ones, in the
+// order they first appear.
+//
+// This replaced the obvious version — compile `\bNAME\s*\(` per candidate and
+// test the body with it — which is O(functions²) in compiled regexes. A file
+// with 2,300 functions built five million of them, and profiling put two thirds
+// of the whole parse phase in that loop and the `escapeRe` feeding it. Reading
+// the body once and looking each token up in a Set does the same work in one
+// pass over the text.
+//
+// `$` counts as part of an identifier, as JavaScript has it, so `$foo(` is a
+// call to `$foo` and not to `foo`. A call written `obj.method(` counts as a call
+// to `method`: this is a best-effort text scan, not a resolver, and a method
+// name that matches a local function is more likely that function than not.
+const CALL_TOKEN = /(?<![\w$])([A-Za-z_$][\w$]*)\s*\(/g;
+
+export function callsWithin(body, names) {
+  const found = [];
+  const seen = new Set();
+  for (const m of String(body).matchAll(CALL_TOKEN)) {
+    const name = m[1];
+    if (seen.has(name) || !names.has(name)) continue;
+    seen.add(name);
+    found.push(name);
+  }
+  return found;
+}
+
+// The order the callee was declared in, first declaration winning — so the call
+// list comes out in the same order the per-name loop produced it.
+export function declarationOrder(fns) {
+  const order = new Map();
+  fns.forEach((f, i) => {
+    if (!order.has(f.name)) order.set(f.name, i);
+  });
+  return order;
+}

package/shared/analyzer/workflows.js

@@ -0,0 +1,143 @@
+// GitHub Actions & CI/CD workflow parser.
+// Pure isomorphic analyzer — parses YAML workflow files without external dependencies.
+
+export async function analyzeWorkflows(source) {
+  const workflows = [];
+  const entries = await source.list('.github/workflows').catch(() => []);
+  const ymlFiles = entries.filter((e) => e.type === 'file' && /\.(ya?ml)$/i.test(e.name));
+
+  for (const entry of ymlFiles) {
+    const raw = await source.read(entry.path).catch(() => '');
+    if (!raw) continue;
+    const parsed = parseWorkflowYaml(raw, entry.path, entry.name);
+    if (parsed) workflows.push(parsed);
+  }
+
+  return workflows;
+}
+
+export function parseWorkflowYaml(text, filePath = '', fileName = '') {
+  const lines = text.split('\n');
+  let name = fileName.replace(/\.ya?ml$/i, '');
+  const triggers = [];
+  const jobs = [];
+
+  let currentSection = null;
+  let currentJob = null;
+  let currentStep = null;
+  let inOnSection = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const indent = line.search(/\S/);
+
+    // Top-level name: ...
+    if (indent === 0 && /^name\s*:\s*(.+)$/i.test(trimmed)) {
+      const m = trimmed.match(/^name\s*:\s*['"]?([^'"]+)['"]?/i);
+      if (m) name = m[1].trim();
+      continue;
+    }
+
+    // Top-level on: ...
+    if (indent === 0 && /^on\s*:/i.test(trimmed)) {
+      currentSection = 'on';
+      inOnSection = true;
+      const rest = trimmed.replace(/^on\s*:\s*/i, '').trim();
+      if (rest) {
+        if (rest.startsWith('[') && rest.endsWith(']')) {
+          const list = rest.slice(1, -1).split(',').map((s) => s.trim().replace(/^['"]|['"]$/g, ''));
+          triggers.push(...list.filter(Boolean));
+        } else {
+          triggers.push(rest.replace(/^['"]|['"]$/g, ''));
+        }
+      }
+      continue;
+    }
+
+    // Top-level jobs: ...
+    if (indent === 0 && /^jobs\s*:/i.test(trimmed)) {
+      currentSection = 'jobs';
+      inOnSection = false;
+      continue;
+    }
+
+    if (currentSection === 'on') {
+      if (indent === 0) {
+        currentSection = null;
+        inOnSection = false;
+      } else {
+        const trigMatch = trimmed.match(/^([a-zA-Z0-9_-]+)\s*:/);
+        const listMatch = trimmed.match(/^-\s*([a-zA-Z0-9_-]+)/);
+        if (trigMatch && indent <= 4) triggers.push(trigMatch[1]);
+        else if (listMatch && indent <= 4) triggers.push(listMatch[1]);
+      }
+    }
+
+    if (currentSection === 'jobs' && indent > 0) {
+      // Job declaration at indent 2 (or top under jobs)
+      if (indent === 2 && trimmed.endsWith(':')) {
+        const jobId = trimmed.replace(/:$/, '').trim();
+        currentJob = {
+          id: jobId,
+          name: jobId,
+          runsOn: 'ubuntu-latest',
+          needs: [],
+          steps: [],
+        };
+        jobs.push(currentJob);
+        currentStep = null;
+        continue;
+      }
+
+      if (!currentJob) continue;
+
+      // Inside a job:
+      if (/^name\s*:\s*(.+)$/i.test(trimmed) && indent <= 6 && !currentStep) {
+        const m = trimmed.match(/^name\s*:\s*['"]?([^'"]+)['"]?/i);
+        if (m) currentJob.name = m[1].trim();
+      } else if (/^runs-on\s*:\s*(.+)$/i.test(trimmed)) {
+        const m = trimmed.match(/^runs-on\s*:\s*['"]?([^'"]+)['"]?/i);
+        if (m) currentJob.runsOn = m[1].trim();
+      } else if (/^needs\s*:\s*(.+)$/i.test(trimmed)) {
+        const rest = trimmed.replace(/^needs\s*:\s*/i, '').trim();
+        if (rest.startsWith('[') && rest.endsWith(']')) {
+          const list = rest.slice(1, -1).split(',').map((s) => s.trim().replace(/^['"]|['"]$/g, ''));
+          currentJob.needs.push(...list.filter(Boolean));
+        } else if (rest) {
+          currentJob.needs.push(rest.replace(/^['"]|['"]$/g, ''));
+        }
+      } else if (/^-\s*needs\s*:\s*(.+)$/i.test(trimmed)) {
+        const m = trimmed.match(/^-\s*needs\s*:\s*(.+)$/i);
+        if (m) currentJob.needs.push(m[1].trim());
+      } else if (trimmed.startsWith('-') && (indent >= 4 || trimmed.startsWith('- uses:') || trimmed.startsWith('- name:'))) {
+        // Step start
+        const stepNameMatch = trimmed.match(/^-\s*name\s*:\s*['"]?([^'"]+)['"]?/i);
+        const stepUsesMatch = trimmed.match(/^-\s*uses\s*:\s*['"]?([^'"]+)['"]?/i);
+        const stepRunMatch = trimmed.match(/^-\s*run\s*:\s*(.+)$/i);
+
+        currentStep = {
+          name: stepNameMatch ? stepNameMatch[1] : (stepUsesMatch ? stepUsesMatch[1] : (stepRunMatch ? stepRunMatch[1] : 'Step')),
+          uses: stepUsesMatch ? stepUsesMatch[1] : null,
+          run: stepRunMatch ? stepRunMatch[1] : null,
+        };
+        currentJob.steps.push(currentStep);
+      } else if (currentStep) {
+        const stepUsesMatch = trimmed.match(/^uses\s*:\s*['"]?([^'"]+)['"]?/i);
+        const stepRunMatch = trimmed.match(/^run\s*:\s*(.+)$/i);
+        if (stepUsesMatch) currentStep.uses = stepUsesMatch[1];
+        if (stepRunMatch) currentStep.run = stepRunMatch[1];
+      }
+    }
+  }
+
+  return {
+    file: filePath,
+    fileName,
+    name: name || fileName,
+    triggers: [...new Set(triggers.filter(Boolean))],
+    jobs,
+  };
+}