codebase-onboarder 0.1.0

package/shared/analyzer/languages/javascript.js

@@ -0,0 +1,240 @@
+// JavaScript / TypeScript / JSX / TSX.
+// Regex-based by design: no parser dependency, runs the same in Node and the
+// browser. It will miss dynamic tricks (require(variable), eval'd imports);
+// that is an accepted, documented trade.
+
+import { blankComments, lineCounter, braceBodyEnd, uniqueBy, callsWithin, declarationOrder } from '../util.js';
+import { dirOf, joinPath, baseName } from '../pathUtil.js';
+
+export const extensions = ['.js', '.jsx', '.mjs', '.cjs'];
+
+const IMPORT_RES = [
+  /\bimport\s+(?:type\s+)?[\w$*{}\s,]+?\sfrom\s*['"]([^'"\n]+)['"]/g,
+  /(?<!['"\w$])import\s*['"]([^'"\n]+)['"]/g,
+  /\bexport\s+(?:type\s+)?[\w$*{}\s,]+?\sfrom\s*['"]([^'"\n]+)['"]/g,
+  /\brequire\s*\(\s*['"]([^'"\n]+)['"]\s*\)/g,
+  /(?<!['"\w$])import\s*\(\s*['"]([^'"\n]+)['"]\s*\)/g,
+];
+
+const EXPORT_RES = [
+  { re: /\bexport\s+(?:async\s+)?function\s*\*?\s*([\w$]+)/g, kind: 'function' },
+  { re: /\bexport\s+(?:abstract\s+)?class\s+([\w$]+)/g, kind: 'class' },
+  { re: /\bexport\s+(?:const|let|var)\s+([\w$]+)/g, kind: 'const' },
+  { re: /\bexport\s+(?:interface|type|enum)\s+([\w$]+)/g, kind: 'type' },
+  { re: /\bexport\s+default\b/g, kind: 'default', name: 'default' },
+  { re: /\bexports\.([\w$]+)\s*=/g, kind: 'const' },
+  { re: /\bmodule\.exports\s*=/g, kind: 'default', name: 'default' },
+];
+
+const NAMED_EXPORT_RE = /\bexport\s*\{([^}]*)\}/g;
+
+const CONTROL_WORDS = new Set([
+  'if', 'for', 'while', 'switch', 'catch', 'return', 'else', 'do', 'new',
+  'typeof', 'case', 'throw', 'delete', 'void', 'in', 'of', 'yield', 'await',
+  'function', 'constructor', 'class',
+]);
+
+const FUNCTION_RES = [
+  { re: /\bfunction\s*\*?\s*([\w$]+)\s*\(/g, kind: 'function' },
+  { re: /\b(?:const|let|var)\s+([\w$]+)\s*=\s*(?:async\s+)?function/g, kind: 'function' },
+  { re: /\b(?:const|let|var)\s+([\w$]+)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[\w$]+)\s*=>/g, kind: 'arrow' },
+  {
+    re: /^[ \t]*(?:export\s+)?(?:(?:public|private|protected|static|async|override|readonly|abstract|get|set)\s+)*([\w$]+)\s*\([^;{]*\)\s*(?::[\w$<>[\]|&., ]+)?\s*\{/gm,
+    kind: 'method',
+  },
+];
+
+const CLASS_RE = /\bclass\s+([\w$]+)/g;
+
+function extractClauseSymbols(clause) {
+  const symbols = [];
+  const c = clause.trim();
+  if (!c) return symbols;
+  if (c.startsWith('*')) return ['*'];
+
+  const braceStart = c.indexOf('{');
+  if (braceStart === -1) {
+    const defMatch = c.match(/^[\w$]+/);
+    if (defMatch && defMatch[0] !== 'type') return ['default'];
+    return symbols;
+  }
+
+  const beforeBrace = c.slice(0, braceStart).trim().replace(/,$/, '').trim();
+  if (beforeBrace && beforeBrace !== 'type') {
+    symbols.push('default');
+  }
+
+  const braceEnd = c.lastIndexOf('}');
+  if (braceEnd > braceStart) {
+    const inside = c.slice(braceStart + 1, braceEnd);
+    for (const part of inside.split(',')) {
+      let t = part.trim();
+      if (!t) continue;
+      if (t.startsWith('type ')) t = t.slice(5).trim();
+      const asMatch = t.match(/^([\w$]+)\s+as\s+[\w$]+/);
+      const name = asMatch ? asMatch[1] : (t.match(/^[\w$]+/) || [])[0];
+      if (name) symbols.push(name);
+    }
+  }
+  return symbols;
+}
+
+export function analyze(source, path) {
+  const clean = blankComments(source);
+  const lineAt = lineCounter(clean);
+
+  const imports = [];
+  for (const m of clean.matchAll(/\bimport\s+(?:type\s+)?([\w$*{}\s,]+?)\s+from\s*['"]([^'"\n]+)['"]/g)) {
+    imports.push({ spec: m[2], symbols: extractClauseSymbols(m[1]), line: lineAt(m.index) });
+  }
+  for (const m of clean.matchAll(/\bexport\s+(?:type\s+)?([\w$*{}\s,]+?)\s+from\s*['"]([^'"\n]+)['"]/g)) {
+    imports.push({ spec: m[2], symbols: extractClauseSymbols(m[1]), line: lineAt(m.index) });
+  }
+  for (const m of clean.matchAll(/(?<!['"\w$])import\s*['"]([^'"\n]+)['"]/g)) {
+    imports.push({ spec: m[1], symbols: [], line: lineAt(m.index) });
+  }
+  for (const m of clean.matchAll(/\brequire\s*\(\s*['"]([^'"\n]+)['"]\s*\)/g)) {
+    imports.push({ spec: m[1], symbols: [], line: lineAt(m.index) });
+  }
+  for (const m of clean.matchAll(/(?<!['"\w$])import\s*\(\s*['"]([^'"\n]+)['"]\s*\)/g)) {
+    imports.push({ spec: m[1], symbols: [], line: lineAt(m.index) });
+  }
+
+  const exports = [];
+  for (const { re, kind, name } of EXPORT_RES) {
+    for (const m of clean.matchAll(re)) {
+      exports.push({ name: name ?? m[1], kind });
+    }
+  }
+  for (const m of clean.matchAll(NAMED_EXPORT_RE)) {
+    for (const part of m[1].split(',')) {
+      const t = part.trim();
+      if (!t || (/^type\b/.test(t) && !/[\w$]/.test(t.replace(/^type\s+/, '')))) continue;
+      const asMatch = t.match(/(?:^|\s)as\s+([\w$]+)$/);
+      const name = asMatch ? asMatch[1] : (t.match(/^([\w$]+)/) || [])[1];
+      if (name) exports.push({ name, kind: 'named' });
+    }
+  }
+
+  const functions = [];
+  for (const { re, kind } of FUNCTION_RES) {
+    for (const m of clean.matchAll(re)) {
+      const name = m[1];
+      if (CONTROL_WORDS.has(name)) continue;
+      functions.push({ name, kind, line: lineAt(m.index), index: m.index, len: m[0].length });
+    }
+  }
+
+  const classes = [];
+  for (const m of clean.matchAll(CLASS_RE)) {
+    classes.push({ name: m[1], line: lineAt(m.index) });
+  }
+
+  // Best-effort intra-file call graph: find each function's body, then look
+  // for calls to other functions declared in the same file.
+  const seen = new Set();
+  const fns = [];
+  for (const f of functions) {
+    const key = f.name + ':' + f.line;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    fns.push(f);
+  }
+
+  const calls = [];
+  const names = new Set(fns.map((f) => f.name));
+  const declaredAt = declarationOrder(fns);
+  for (const fn of fns) {
+    const body = functionBody(clean, fn);
+    if (!body) continue;
+    const called = callsWithin(body, names)
+      .filter((name) => name !== fn.name)
+      .sort((a, b) => declaredAt.get(a) - declaredAt.get(b));
+    for (const name of called) calls.push({ from: fn.name, to: name });
+  }
+
+  return {
+    imports: uniqueBy(imports, (i) => i.spec + ':' + i.line),
+    exports: uniqueBy(exports, (e) => e.name),
+    functions: fns.map(({ index, len, ...rest }) => rest),
+    classes,
+    calls: uniqueBy(calls, (c) => c.from + '->' + c.to),
+    hasMain: false,
+  };
+}
+
+function functionBody(clean, fn) {
+  const open = clean.indexOf('{', fn.index + fn.len - 1);
+  if (open === -1 || open > fn.index + fn.len + 400) return null;
+  return clean.slice(open, braceBodyEnd(clean, open));
+}
+
+export function packageNameOf(spec) {
+  if (spec.startsWith('node:')) return spec.slice(5);
+  const parts = spec.split('/');
+  return spec.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+}
+
+export function resolveImport(spec, fromPath, has, context = {}) {
+  const tryResolve = (base) => {
+    if (has(base)) return { path: base };
+    const allExts = [...extensions, '.ts', '.tsx'];
+    for (const ext of allExts) {
+      if (has(base + ext)) return { path: base + ext };
+    }
+    for (const ext of allExts) {
+      const idx = base + '/index' + ext;
+      if (has(idx)) return { path: idx };
+    }
+    const asTs = base.replace(/\.jsx?$/, '');
+    if (asTs !== base) {
+      for (const ext of ['.ts', '.tsx']) {
+        if (has(asTs + ext)) return { path: asTs + ext };
+      }
+    }
+    return null;
+  };
+
+  if (spec.startsWith('.') || spec.startsWith('/')) {
+    const base = spec.startsWith('/')
+      ? joinPath('', spec)
+      : joinPath(dirOf(fromPath), spec);
+    const hit = tryResolve(base);
+    if (hit) return hit;
+    return { unresolved: spec };
+  }
+
+  // tsconfig.json / jsconfig.json paths aliases
+  if (context.tsPaths) {
+    const { baseUrl = '', paths = {} } = context.tsPaths;
+    for (const [pattern, targets] of Object.entries(paths)) {
+      const starIdx = pattern.indexOf('*');
+      if (starIdx !== -1) {
+        const prefix = pattern.slice(0, starIdx);
+        const suffix = pattern.slice(starIdx + 1);
+        if (spec.startsWith(prefix) && spec.endsWith(suffix)) {
+          const matchWildcard = spec.slice(prefix.length, spec.length - suffix.length);
+          for (const target of targets) {
+            const resolvedTarget = target.replace('*', matchWildcard);
+            const candBase = joinPath(baseUrl, resolvedTarget);
+            const hit = tryResolve(candBase);
+            if (hit) return hit;
+          }
+        }
+      } else if (spec === pattern) {
+        for (const target of targets) {
+          const candBase = joinPath(baseUrl, target);
+          const hit = tryResolve(candBase);
+          if (hit) return hit;
+        }
+      }
+    }
+    if (baseUrl) {
+      const candBase = joinPath(baseUrl, spec);
+      const hit = tryResolve(candBase);
+      if (hit) return hit;
+    }
+  }
+
+  return { external: packageNameOf(spec) };
+}

package/shared/analyzer/languages/python.js

@@ -0,0 +1,120 @@
+// Python. Line-oriented, indentation-aware enough for our purposes.
+
+import { blankComments, lineCounter, uniqueBy, callsWithin, declarationOrder } from '../util.js';
+import { dirOf, joinPath } from '../pathUtil.js';
+
+export const extensions = ['.py'];
+
+const IMPORT_FROM_RE = /^[ \t]*from\s+([.\w]+)\s+import\s+/gm;
+const IMPORT_PLAIN_RE = /^[ \t]*import\s+([\w.,\s]+?)\s*(?:#.*)?$/gm;
+const DEF_RE = /^([ \t]*)(?:async\s+)?def\s+([\w]+)\s*\(/gm;
+const CLASS_RE = /^([ \t]*)class\s+([\w]+)/gm;
+
+export function analyze(source, path) {
+  const clean = blankComments(source, { block: false, lineChar: '#' });
+  const lineAt = lineCounter(clean);
+
+  const imports = [];
+  for (const m of clean.matchAll(IMPORT_FROM_RE)) {
+    imports.push({ spec: m[1], kind: 'from', line: lineAt(m.index) });
+  }
+  for (const m of clean.matchAll(IMPORT_PLAIN_RE)) {
+    for (let part of m[1].split(',')) {
+      part = part.trim().split(/\s+as\s+/)[0].trim();
+      if (part) imports.push({ spec: part, kind: 'import', line: lineAt(m.index) });
+    }
+  }
+
+  const functions = [];
+  for (const m of clean.matchAll(DEF_RE)) {
+    const indent = m[1].length;
+    functions.push({
+      name: m[2],
+      kind: indent > 0 ? 'method' : 'function',
+      line: lineAt(m.index),
+      indent,
+    });
+  }
+
+  const classes = [];
+  for (const m of clean.matchAll(CLASS_RE)) {
+    classes.push({ name: m[2], line: lineAt(m.index) });
+  }
+
+  // Calls: a function's body is the run of lines more indented than its def.
+  const lines = clean.split('\n');
+  const calls = [];
+  const topLevel = functions.filter((f) => f.kind === 'function');
+  const names = new Set(functions.map((f) => f.name));
+  const declaredAt = declarationOrder(functions);
+  for (const fn of functions) {
+    const body = indentedBody(lines, fn.line - 1, fn.indent);
+    if (!body) continue;
+    const called = callsWithin(body, names)
+      .filter((name) => name !== fn.name)
+      .sort((a, b) => declaredAt.get(a) - declaredAt.get(b));
+    for (const name of called) calls.push({ from: fn.name, to: name });
+  }
+
+  const exports = topLevel
+    .filter((f) => !f.name.startsWith('_'))
+    .map((f) => ({ name: f.name, kind: 'function' }))
+    .concat(classes.filter((c) => !c.name.startsWith('_')).map((c) => ({ name: c.name, kind: 'class' })));
+
+  const hasMain = /__name__\s*==\s*['"]__main__['"]/.test(clean);
+
+  return {
+    imports: uniqueBy(imports, (i) => i.spec + ':' + i.line),
+    exports: uniqueBy(exports, (e) => e.name),
+    functions: functions.map(({ indent, ...rest }) => rest),
+    classes,
+    calls: uniqueBy(calls, (c) => c.from + '->' + c.to),
+    hasMain,
+  };
+}
+
+function indentedBody(lines, defLineIdx, indent) {
+  const out = [];
+  for (let i = defLineIdx + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === '') {
+      out.push('');
+      continue;
+    }
+    const lead = line.length - line.trimStart().length;
+    if (lead <= indent) break;
+    out.push(line);
+  }
+  return out.join('\n');
+}
+
+export function packageNameOf(spec) {
+  return spec.replace(/^\.+/, '').split('.')[0] || spec;
+}
+
+export function resolveImport(spec, fromPath, has, context = {}) {
+  const fromDir = dirOf(fromPath);
+
+  if (spec.startsWith('.')) {
+    // Relative import: one dot = current package, two = parent, and so on.
+    const dots = spec.match(/^\.+/)[0].length;
+    let base = fromDir;
+    for (let i = 1; i < dots; i++) base = dirOf(base);
+    const rest = spec.slice(dots).replace(/\./g, '/');
+    const target = rest ? joinPath(base, rest) : base;
+    for (const cand of [target + '.py', target + '/__init__.py']) {
+      if (has(cand)) return { path: cand };
+    }
+    return { unresolved: spec };
+  }
+
+  // Absolute import: try from repo root, then relative to the file (a common
+  // layout in small scripts), then give up and call it external.
+  const rel = spec.replace(/\./g, '/');
+  for (const root of ['', fromDir]) {
+    for (const cand of [joinPath(root, rel) + '.py', joinPath(root, rel) + '/__init__.py']) {
+      if (has(cand)) return { path: cand };
+    }
+  }
+  return { external: spec.split('.')[0] };
+}

package/shared/analyzer/languages/rust.js

@@ -0,0 +1,42 @@
+// Rust analyzer
+import { blankComments, lineCounter, uniqueBy } from '../util.js';
+
+export const extensions = ['.rs'];
+
+export function analyze(source, path) {
+  const clean = blankComments(source);
+  const lineAt = lineCounter(clean);
+
+  const imports = [];
+  for (const m of clean.matchAll(/\b(?:use|mod)\s+([a-zA-Z0-9_:]+)/g)) {
+    imports.push({ spec: m[1], line: lineAt(m.index) });
+  }
+
+  const functions = [];
+  for (const m of clean.matchAll(/\b(pub\s+)?fn\s+([a-zA-Z0-9_]+)/g)) {
+    functions.push({ name: m[2], pub: !!m[1], line: lineAt(m.index) });
+  }
+
+  const classes = [];
+  for (const m of clean.matchAll(/\b(pub\s+)?(?:struct|enum|trait)\s+([a-zA-Z0-9_]+)/g)) {
+    classes.push({ name: m[2], pub: !!m[1], line: lineAt(m.index) });
+  }
+
+  const exports = [];
+  for (const f of functions) if (f.pub) exports.push({ name: f.name, kind: 'function' });
+  for (const c of classes) if (c.pub) exports.push({ name: c.name, kind: 'class' });
+
+  const hasMain = /\bfn\s+main\s*\(/.test(clean);
+
+  return {
+    imports: uniqueBy(imports, i => i.spec + ':' + i.line),
+    exports,
+    functions,
+    classes,
+    hasMain
+  };
+}
+
+export function resolveImport(spec, fromPath, has, context = {}) {
+  return { unresolved: spec };
+}

package/shared/analyzer/languages/typescript.js

@@ -0,0 +1,138 @@
+// TypeScript / TSX analyzer.
+// Extracts interfaces, type aliases, enums, decorators, and generic arities,
+// while preserving clause symbols and resolving imports according to tsconfig.json.
+
+import { blankComments, lineCounter, braceBodyEnd, uniqueBy } from '../util.js';
+import { dirOf, joinPath, baseName } from '../pathUtil.js';
+import { resolveImport, packageNameOf } from './javascript.js';
+
+export const extensions = ['.ts', '.tsx'];
+
+const IMPORT_RES = [
+  /\bimport\s+(?:type\s+)?([\w$*{}\s,]+?)\s+from\s*['"]([^'"\n]+)['"]/g,
+  /\bexport\s+(?:type\s+)?([\w$*{}\s,]+?)\s+from\s*['"]([^'"\n]+)['"]/g,
+  /(?<!['"\w$])import\s*['"]([^'"\n]+)['"]/g,
+  /\brequire\s*\(\s*['"]([^'"\n]+)['"]\s*\)/g,
+  /(?<!['"\w$])import\s*\(\s*['"]([^'"\n]+)['"]\s*\)/g,
+];
+
+const EXPORT_RES = [
+  { re: /\bexport\s+(?:async\s+)?function\s*\*?\s*([\w$]+)/g, kind: 'function' },
+  { re: /\bexport\s+(?:abstract\s+)?class\s+([\w$]+)/g, kind: 'class' },
+  { re: /\bexport\s+(?:const|let|var)\s+([\w$]+)/g, kind: 'const' },
+  { re: /\bexport\s+(?:interface|type|enum)\s+([\w$]+)/g, kind: 'type' },
+  { re: /\bexport\s+default\b/g, kind: 'default', name: 'default' },
+];
+
+const NAMED_EXPORT_RE = /\bexport\s*\{([^}]*)\}/g;
+const DECORATOR_RE = /@([\w$]+)(?:\s*\()?/g;
+const GENERIC_RE = /<([A-Za-z0-9_$,\s]+)>/;
+
+function extractClauseSymbols(clause) {
+  const symbols = [];
+  const c = clause.trim();
+  if (!c) return symbols;
+  if (c.startsWith('*')) return ['*'];
+
+  const braceStart = c.indexOf('{');
+  if (braceStart === -1) {
+    const defMatch = c.match(/^[\w$]+/);
+    if (defMatch && defMatch[0] !== 'type') return ['default'];
+    return symbols;
+  }
+
+  const beforeBrace = c.slice(0, braceStart).trim().replace(/,$/, '').trim();
+  if (beforeBrace && beforeBrace !== 'type') {
+    symbols.push('default');
+  }
+
+  const braceEnd = c.lastIndexOf('}');
+  if (braceEnd > braceStart) {
+    const inside = c.slice(braceStart + 1, braceEnd);
+    for (const part of inside.split(',')) {
+      let t = part.trim();
+      if (!t) continue;
+      if (t.startsWith('type ')) t = t.slice(5).trim();
+      const asMatch = t.match(/^([\w$]+)\s+as\s+[\w$]+/);
+      const name = asMatch ? asMatch[1] : (t.match(/^[\w$]+/) || [])[0];
+      if (name) symbols.push(name);
+    }
+  }
+  return symbols;
+}
+
+export function analyze(source, path) {
+  const clean = blankComments(source);
+  const lineAt = lineCounter(clean);
+
+  const imports = [];
+  for (const m of clean.matchAll(/\bimport\s+(?:type\s+)?([\w$*{}\s,]+?)\s+from\s*['"]([^'"\n]+)['"]/g)) {
+    imports.push({ spec: m[2], symbols: extractClauseSymbols(m[1]), line: lineAt(m.index) });
+  }
+  for (const m of clean.matchAll(/\bexport\s+(?:type\s+)?([\w$*{}\s,]+?)\s+from\s*['"]([^'"\n]+)['"]/g)) {
+    imports.push({ spec: m[2], symbols: extractClauseSymbols(m[1]), line: lineAt(m.index) });
+  }
+  for (const m of clean.matchAll(/(?<!['"\w$])import\s*['"]([^'"\n]+)['"]/g)) {
+    imports.push({ spec: m[1], symbols: [], line: lineAt(m.index) });
+  }
+  for (const m of clean.matchAll(/\brequire\s*\(\s*['"]([^'"\n]+)['"]\s*\)/g)) {
+    imports.push({ spec: m[1], symbols: [], line: lineAt(m.index) });
+  }
+  for (const m of clean.matchAll(/(?<!['"\w$])import\s*\(\s*['"]([^'"\n]+)['"]\s*\)/g)) {
+    imports.push({ spec: m[1], symbols: [], line: lineAt(m.index) });
+  }
+
+  const exports = [];
+  for (const { re, kind, name } of EXPORT_RES) {
+    for (const m of clean.matchAll(re)) {
+      exports.push({ name: name ?? m[1], kind });
+    }
+  }
+  for (const m of clean.matchAll(NAMED_EXPORT_RE)) {
+    for (const part of m[1].split(',')) {
+      const t = part.trim();
+      if (!t || (/^type\b/.test(t) && !/[\w$]/.test(t.replace(/^type\s+/, '')))) continue;
+      const asMatch = t.match(/(?:^|\s)as\s+([\w$]+)$/);
+      const name = asMatch ? asMatch[1] : (t.match(/^([\w$]+)/) || [])[1];
+      if (name) exports.push({ name, kind: 'named' });
+    }
+  }
+
+  const functions = [];
+  for (const m of clean.matchAll(/\bfunction\s+([\w$]+)/g)) {
+    functions.push({ name: m[1], kind: 'function', line: lineAt(m.index) });
+  }
+
+  const classes = [];
+  for (const m of clean.matchAll(/\bclass\s+([\w$]+)([^{]*)\{/g)) {
+    const name = m[1];
+    const signature = m[2] || '';
+    const decs = [];
+    const beforeClass = clean.slice(Math.max(0, m.index - 200), m.index);
+    for (const dm of beforeClass.matchAll(DECORATOR_RE)) {
+      decs.push(dm[1]);
+    }
+    const genMatch = signature.match(GENERIC_RE);
+    const arity = genMatch ? genMatch[1].split(',').length : 0;
+    
+    classes.push({ name, decorators: decs, genericArity: arity, line: lineAt(m.index) });
+  }
+
+  const interfaces = [];
+  for (const m of clean.matchAll(/\b(?:interface|type|enum)\s+([\w$]+)/g)) {
+    interfaces.push({ name: m[1], line: lineAt(m.index) });
+  }
+
+  const hasMain = /if\s*\(\s*require\.main\s*===\s*module\s*\)|import\.meta\.main/g.test(clean);
+
+  return {
+    imports: uniqueBy(imports, (i) => i.spec + ':' + i.line),
+    exports: uniqueBy(exports, (e) => e.name),
+    functions,
+    classes,
+    interfaces,
+    hasMain,
+  };
+}
+
+export { resolveImport, packageNameOf };

package/shared/analyzer/licenses.js

@@ -0,0 +1,151 @@
+// License detection and Software Bill of Materials (SBOM) compliance analysis.
+// Pure isomorphic analyzer — works in Node and browser.
+
+const KNOWN_LICENSES = [
+  { id: 'MIT', name: 'MIT License', type: 'permissive', rx: /\bMIT\b|Permission is hereby granted, free of charge/i },
+  { id: 'Apache-2.0', name: 'Apache License 2.0', type: 'permissive', rx: /Apache License,\s*Version 2\.0|http:\/\/www\.apache\.org\/licenses\/LICENSE-2\.0/i },
+  { id: 'BSD-3-Clause', name: 'BSD 3-Clause "New" or "Revised" License', type: 'permissive', rx: /Redistribution and use in source and binary forms[\s\S]*?Neither the name of[\s\S]*?nor the names of its contributors/i },
+  { id: 'BSD-2-Clause', name: 'BSD 2-Clause "Simplified" License', type: 'permissive', rx: /Redistribution and use in source and binary forms[\s\S]*?Redistributions in binary form must reproduce the above copyright/i },
+  { id: 'ISC', name: 'ISC License', type: 'permissive', rx: /Permission to use, copy, modify, and\/or distribute this software for any purpose/i },
+  { id: 'GPL-3.0', name: 'GNU General Public License v3.0', type: 'copyleft', rx: /GNU GENERAL PUBLIC LICENSE\s+Version 3|GPL-3\.0/i },
+  { id: 'GPL-2.0', name: 'GNU General Public License v2.0', type: 'copyleft', rx: /GNU GENERAL PUBLIC LICENSE\s+Version 2|GPL-2\.0/i },
+  { id: 'AGPL-3.0', name: 'GNU Affero General Public License v3.0', type: 'copyleft', rx: /GNU AFFERO GENERAL PUBLIC LICENSE/i },
+  { id: 'LGPL-3.0', name: 'GNU Lesser General Public License v3.0', type: 'weak-copyleft', rx: /GNU LESSER GENERAL PUBLIC LICENSE\s+Version 3/i },
+  { id: 'MPL-2.0', name: 'Mozilla Public License 2.0', type: 'weak-copyleft', rx: /Mozilla Public License,?\s*v\.?\s*2\.0/i },
+  { id: 'Unlicense', name: 'The Unlicense', type: 'public-domain', rx: /This is free and unencumbered software released into the public domain/i },
+  { id: 'CC0-1.0', name: 'Creative Commons Zero v1.0 Universal', type: 'public-domain', rx: /CC0 1\.0 Universal|Public Domain Dedication/i },
+];
+
+export function detectLicenseFromText(text) {
+  if (!text || typeof text !== 'string') return null;
+  for (const lic of KNOWN_LICENSES) {
+    if (lic.rx.test(text)) {
+      return { id: lic.id, name: lic.name, type: lic.type };
+    }
+  }
+  return null;
+}
+
+export function classifyLicenseType(licenseId) {
+  if (!licenseId || licenseId === 'UNKNOWN') return 'unknown';
+  const id = String(licenseId).toUpperCase();
+  if (/MIT|APACHE|BSD|ISC|UNLICENSE|CC0|ZLIB|WTFPL/.test(id)) return 'permissive';
+  if (/LGPL|MPL|EPL/.test(id)) return 'weak-copyleft';
+  if (/AGPL|GPL-2|GPL-3|GPLV2|GPLV3|GPL/.test(id)) return 'copyleft';
+  return 'custom';
+}
+
+export async function analyzeLicenses(source, manifest = {}) {
+  let projectLicense = null;
+
+  // 1. Check root LICENSE / COPYING / LICENSE.md files
+  const rootFiles = await source.list('').catch(() => []);
+  const licFile = rootFiles.find((f) => /^LICENSE|^COPYING|^UNLICENSE/i.test(f.name));
+  if (licFile) {
+    const content = await source.read(licFile.path).catch(() => '');
+    projectLicense = detectLicenseFromText(content) || {
+      id: 'Custom',
+      name: licFile.name,
+      type: 'custom',
+    };
+  }
+
+  // 2. Fallback to manifest.license from package.json
+  if (!projectLicense && manifest.license) {
+    const licId = manifest.license;
+    projectLicense = {
+      id: licId,
+      name: licId,
+      type: classifyLicenseType(licId),
+    };
+  }
+
+  // 3. Build SBOM entries from manifest dependencies
+  const sbom = [];
+  const addDep = (name, version, ecosystem, dev = false) => {
+    sbom.push({
+      name,
+      version: version || '*',
+      ecosystem,
+      isDev: dev,
+      license: inferKnownDepLicense(name, ecosystem),
+    });
+  };
+
+  const npmDeps = manifest.deps?.npm || {};
+  for (const [name, ver] of Object.entries(npmDeps)) {
+    addDep(name, ver, 'npm', false);
+  }
+  const devDeps = manifest.deps?.dev || {};
+  for (const [name, ver] of Object.entries(devDeps)) {
+    addDep(name, ver, 'npm', true);
+  }
+  for (const name of manifest.deps?.pip || []) {
+    addDep(name, '*', 'pip', false);
+  }
+  for (const name of manifest.deps?.go || []) {
+    addDep(name, '*', 'go', false);
+  }
+  for (const name of manifest.deps?.cargo || []) {
+    addDep(name, '*', 'cargo', false);
+  }
+
+  const counts = { permissive: 0, copyleft: 0, weakCopyleft: 0, unknown: 0, total: sbom.length };
+  for (const item of sbom) {
+    const type = item.license.type;
+    if (type === 'permissive') counts.permissive++;
+    else if (type === 'copyleft') counts.copyleft++;
+    else if (type === 'weak-copyleft') counts.weakCopyleft++;
+    else counts.unknown++;
+  }
+
+  const hasCopyleft = counts.copyleft > 0;
+  const complianceStatus = hasCopyleft && projectLicense?.type === 'permissive'
+    ? 'warning'
+    : 'clean';
+
+  return {
+    projectLicense: projectLicense || { id: 'UNLICENSED', name: 'None detected', type: 'unknown' },
+    sbom,
+    counts,
+    complianceStatus,
+  };
+}
+
+// Inferred licenses for standard popular open-source dependencies
+const POPULAR_LICENSES = {
+  react: 'MIT',
+  'react-dom': 'MIT',
+  vue: 'MIT',
+  express: 'MIT',
+  lodash: 'MIT',
+  axios: 'MIT',
+  typescript: 'Apache-2.0',
+  next: 'MIT',
+  tailwindcss: 'MIT',
+  eslint: 'MIT',
+  prettier: 'MIT',
+  mocha: 'MIT',
+  jest: 'MIT',
+  vite: 'MIT',
+  fastapi: 'MIT',
+  django: 'BSD-3-Clause',
+  flask: 'BSD-3-Clause',
+  requests: 'Apache-2.0',
+  pytest: 'MIT',
+  numpy: 'BSD-3-Clause',
+  pandas: 'BSD-3-Clause',
+  tokio: 'MIT',
+  serde: 'MIT / Apache-2.0',
+  gin: 'MIT',
+  fiber: 'MIT',
+};
+
+function inferKnownDepLicense(name, ecosystem) {
+  const normName = name.toLowerCase().replace(/^@[^/]+\//, '');
+  const id = POPULAR_LICENSES[name] || POPULAR_LICENSES[normName] || 'Permissive (Inferred)';
+  return {
+    id,
+    type: classifyLicenseType(id),
+  };
+}