codebase-onboarder 0.5.0 → 0.7.0

package/shared/contracts.d.ts

@@ -0,0 +1,250 @@
+/** Portable contracts shared by the server, terminal app, and browser. */
+export interface FileEntry {
+    name: string;
+    path: string;
+    type: 'file' | 'dir';
+}
+export interface FileSource {
+    kind: string;
+    root: string;
+    name: string;
+    list(directory: string): Promise<FileEntry[]>;
+    read(path: string): Promise<string>;
+}
+/** A structural signal keeps the engine independent of Node and browser imports. */
+export interface ScanSignal {
+    readonly aborted: boolean;
+    readonly reason?: unknown;
+    addEventListener(type: 'abort', listener: () => void, options?: {
+        once?: boolean;
+    }): void;
+    removeEventListener(type: 'abort', listener: () => void): void;
+}
+export type ScanProgress = {
+    phase: 'clone';
+    url: string;
+} | {
+    phase: 'walk';
+    found: number;
+} | {
+    phase: 'parse';
+    done: number;
+    total: number;
+} | {
+    phase: 'resolve';
+    done: number;
+    total: number;
+} | {
+    phase: 'complete';
+    files: number;
+    edges: number;
+};
+export interface ScanOptions {
+    maxFiles?: number;
+    /** UTF-8 bytes, rather than JavaScript string length. */
+    maxFileSize?: number;
+    readConcurrency?: number;
+    signal?: ScanSignal;
+    onProgress?: (progress: ScanProgress) => void;
+}
+export interface ScanLimits {
+    maxFiles: number;
+    maxFileSize: number;
+    readConcurrency: number;
+}
+export interface ImportInfo {
+    spec: string;
+    line?: number;
+    symbols?: string[];
+    kind?: string;
+    local?: boolean;
+    static?: boolean;
+    typeOnly?: boolean;
+    reexport?: boolean;
+    packageName?: string;
+}
+export interface ImportEdge {
+    from: string;
+    to: string;
+    kind: string;
+    symbols: string[];
+}
+export interface Service {
+    name: string;
+    source: string;
+    command?: string;
+    build?: string;
+    image?: string;
+    ports?: string[];
+    dependsOn?: string[];
+}
+export interface Manifest {
+    entryPoints: string[];
+    services: Service[];
+    packageName: string;
+    scripts: string[];
+    workspaces: string[];
+    license?: string;
+    hasServerScript?: boolean;
+    composeFile?: string;
+    deps: {
+        npm: Record<string, string>;
+        dev: Record<string, string>;
+        pip: string[];
+        go: string[];
+        cargo: string[];
+    };
+}
+export interface ResolverContext {
+    hasDir?: (path: string) => boolean;
+    findDirEndingWith?: (suffix: string) => string | null;
+    findByName?: (name: string) => string | null;
+    modulePath?: string;
+    tsPaths?: {
+        baseUrl: string;
+        paths: Record<string, string[]>;
+        sourceRoot?: string;
+        outputRoot?: string;
+    } | null;
+}
+export interface ImportResolution {
+    path?: string;
+    packageDir?: string;
+    external?: string;
+    unresolved?: string;
+}
+export interface AccountSettings {
+    name: string;
+    email: string;
+    provider: string;
+    baseUrl: string;
+    model: string;
+}
+export interface Settings {
+    version: number;
+    mode: 'local' | 'self-hosted';
+    host: string;
+    port: number;
+    domain: string;
+    https: boolean;
+    accessKey: string;
+    autoOpen: boolean;
+    account: AccountSettings;
+    tunnel: {
+        cloudflare: boolean;
+        tailscale: boolean;
+    };
+}
+export interface SettingsInput {
+    version?: unknown;
+    mode?: unknown;
+    host?: unknown;
+    port?: unknown;
+    domain?: unknown;
+    https?: unknown;
+    accessKey?: unknown;
+    autoOpen?: unknown;
+    account?: Partial<Record<keyof AccountSettings, unknown>>;
+    tunnel?: {
+        cloudflare?: unknown;
+        tailscale?: unknown;
+    };
+}
+export interface ServerUrls {
+    local: string;
+    network?: string;
+    domain?: string;
+}
+export interface SymbolInfo {
+    name: string;
+    line?: number;
+    kind?: string;
+    calls?: string[];
+    async?: boolean;
+    exported?: boolean;
+    pub?: boolean;
+    genericArity?: number;
+    decorators?: string[];
+    annotations?: string[];
+    attributes?: string[];
+}
+export interface FileAnalysis {
+    imports: ImportInfo[];
+    exports: SymbolInfo[];
+    functions: SymbolInfo[];
+    classes: SymbolInfo[];
+    interfaces?: SymbolInfo[];
+    calls?: Array<{
+        from: string;
+        to: string;
+    }>;
+    hasMain?: boolean;
+    decorators?: string[];
+    annotations?: string[];
+    attributes?: string[];
+    packageName?: string;
+    namespace?: string;
+}
+export interface SecurityFinding {
+    rule: string;
+    severity: string;
+    category: string;
+    message: string;
+    line: number;
+    source?: string;
+    tool?: string;
+}
+export interface ScannedFile extends FileAnalysis {
+    path: string;
+    dir: string;
+    name: string;
+    ext: string;
+    lang: string;
+    size: number;
+    loc: number;
+    comment: number;
+    blank: number;
+    lines: number;
+    docRatio: number;
+    complexity: number;
+    findings?: SecurityFinding[];
+    cognitive?: number;
+    maintainability?: number;
+}
+export interface ScannedFolder {
+    path: string;
+    name: string;
+    depth: number;
+    fileCount: number;
+    loc: number;
+    comment: number;
+    blank: number;
+    size: number;
+    langs: Record<string, number>;
+    hasReadme: boolean;
+    docRatio?: number;
+}
+export interface LanguageAnalyzer {
+    id: string;
+    label: string;
+    short: string;
+    extensions: string[];
+    analyze(source: string, path: string): FileAnalysis;
+    resolveImport(spec: string, from: string, has: (path: string) => boolean, context?: ResolverContext, meta?: ImportInfo): ImportResolution;
+}
+export type ScanRequestOptions = Pick<ScanOptions, 'maxFiles' | 'maxFileSize' | 'readConcurrency'>;
+export type ScanRequest = ({
+    path: string;
+    gitUrl?: never;
+    demo?: never;
+} | {
+    gitUrl: string;
+    path?: never;
+    demo?: never;
+} | {
+    demo: true;
+    path?: never;
+    gitUrl?: never;
+}) & {
+    options?: ScanRequestOptions;
+};

package/shared/contracts.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contracts.js.map

package/shared/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../src/shared/contracts.ts"],"names":[],"mappings":"","sourcesContent":["/** Portable contracts shared by the server, terminal app, and browser. */\nexport interface FileEntry {\n  name: string;\n  path: string;\n  type: 'file' | 'dir';\n}\n\nexport interface FileSource {\n  kind: string;\n  root: string;\n  name: string;\n  list(directory: string): Promise<FileEntry[]>;\n  read(path: string): Promise<string>;\n}\n\n/** A structural signal keeps the engine independent of Node and browser imports. */\nexport interface ScanSignal {\n  readonly aborted: boolean;\n  readonly reason?: unknown;\n  addEventListener(type: 'abort', listener: () => void, options?: { once?: boolean }): void;\n  removeEventListener(type: 'abort', listener: () => void): void;\n}\n\nexport type ScanProgress =\n  | { phase: 'clone'; url: string }\n  | { phase: 'walk'; found: number }\n  | { phase: 'parse'; done: number; total: number }\n  | { phase: 'resolve'; done: number; total: number }\n  | { phase: 'complete'; files: number; edges: number };\n\nexport interface ScanOptions {\n  maxFiles?: number;\n  /** UTF-8 bytes, rather than JavaScript string length. */\n  maxFileSize?: number;\n  readConcurrency?: number;\n  signal?: ScanSignal;\n  onProgress?: (progress: ScanProgress) => void;\n}\n\nexport interface ScanLimits {\n  maxFiles: number;\n  maxFileSize: number;\n  readConcurrency: number;\n}\n\nexport interface ImportInfo {\n  spec: string;\n  line?: number;\n  symbols?: string[];\n  kind?: string;\n  local?: boolean;\n  static?: boolean;\n  typeOnly?: boolean;\n  reexport?: boolean;\n  packageName?: string;\n}\n\nexport interface ImportEdge {\n  from: string;\n  to: string;\n  kind: string;\n  symbols: string[];\n}\n\nexport interface Service {\n  name: string;\n  source: string;\n  command?: string;\n  build?: string;\n  image?: string;\n  ports?: string[];\n  dependsOn?: string[];\n}\n\nexport interface Manifest {\n  entryPoints: string[];\n  services: Service[];\n  packageName: string;\n  scripts: string[];\n  workspaces: string[];\n  license?: string;\n  hasServerScript?: boolean;\n  composeFile?: string;\n  deps: { npm: Record<string, string>; dev: Record<string, string>; pip: string[]; go: string[]; cargo: string[] };\n}\n\nexport interface ResolverContext {\n  hasDir?: (path: string) => boolean;\n  findDirEndingWith?: (suffix: string) => string | null;\n  findByName?: (name: string) => string | null;\n  modulePath?: string;\n  tsPaths?: { baseUrl: string; paths: Record<string, string[]>; sourceRoot?: string; outputRoot?: string } | null;\n}\n\nexport interface ImportResolution {\n  path?: string;\n  packageDir?: string;\n  external?: string;\n  unresolved?: string;\n}\n\nexport interface AccountSettings {\n  name: string;\n  email: string;\n  provider: string;\n  baseUrl: string;\n  model: string;\n}\n\nexport interface Settings {\n  version: number;\n  mode: 'local' | 'self-hosted';\n  host: string;\n  port: number;\n  domain: string;\n  https: boolean;\n  accessKey: string;\n  autoOpen: boolean;\n  account: AccountSettings;\n  tunnel: { cloudflare: boolean; tailscale: boolean };\n}\n\nexport interface SettingsInput {\n  version?: unknown;\n  mode?: unknown;\n  host?: unknown;\n  port?: unknown;\n  domain?: unknown;\n  https?: unknown;\n  accessKey?: unknown;\n  autoOpen?: unknown;\n  account?: Partial<Record<keyof AccountSettings, unknown>>;\n  tunnel?: { cloudflare?: unknown; tailscale?: unknown };\n}\n\nexport interface ServerUrls { local: string; network?: string; domain?: string }\n\nexport interface SymbolInfo {\n  name: string;\n  line?: number;\n  kind?: string;\n  calls?: string[];\n  async?: boolean;\n  exported?: boolean;\n  pub?: boolean;\n  genericArity?: number;\n  decorators?: string[];\n  annotations?: string[];\n  attributes?: string[];\n}\n\nexport interface FileAnalysis {\n  imports: ImportInfo[];\n  exports: SymbolInfo[];\n  functions: SymbolInfo[];\n  classes: SymbolInfo[];\n  interfaces?: SymbolInfo[];\n  calls?: Array<{ from: string; to: string }>;\n  hasMain?: boolean;\n  decorators?: string[];\n  annotations?: string[];\n  attributes?: string[];\n  packageName?: string;\n  namespace?: string;\n}\n\nexport interface SecurityFinding {\n  rule: string;\n  severity: string;\n  category: string;\n  message: string;\n  line: number;\n  source?: string;\n  tool?: string;\n}\n\nexport interface ScannedFile extends FileAnalysis {\n  path: string;\n  dir: string;\n  name: string;\n  ext: string;\n  lang: string;\n  size: number;\n  loc: number;\n  comment: number;\n  blank: number;\n  lines: number;\n  docRatio: number;\n  complexity: number;\n  findings?: SecurityFinding[];\n  cognitive?: number;\n  maintainability?: number;\n}\n\nexport interface ScannedFolder {\n  path: string;\n  name: string;\n  depth: number;\n  fileCount: number;\n  loc: number;\n  comment: number;\n  blank: number;\n  size: number;\n  langs: Record<string, number>;\n  hasReadme: boolean;\n  docRatio?: number;\n}\n\nexport interface LanguageAnalyzer {\n  id: string;\n  label: string;\n  short: string;\n  extensions: string[];\n  analyze(source: string, path: string): FileAnalysis;\n  resolveImport(spec: string, from: string, has: (path: string) => boolean, context?: ResolverContext, meta?: ImportInfo): ImportResolution;\n}\n\nexport type ScanRequestOptions = Pick<ScanOptions, 'maxFiles' | 'maxFileSize' | 'readConcurrency'>;\nexport type ScanRequest = (\n  | { path: string; gitUrl?: never; demo?: never }\n  | { gitUrl: string; path?: never; demo?: never }\n  | { demo: true; path?: never; gitUrl?: never }\n) & { options?: ScanRequestOptions };\n"]}

package/shared/diagram/aiFacts.d.ts

@@ -0,0 +1,35 @@
+export declare function diagramTarget(s: any): {
+    view: string;
+    path: any;
+} | {
+    view: any;
+    path: string;
+};
+export declare function externalsFor(scan: any, path: any): any;
+export declare function overviewFacts(scan: any, facts: any): {
+    kind: string;
+    facts: string[];
+};
+export declare function layersFacts(facts: any, patterns: any): {
+    kind: string;
+    facts: any[];
+};
+export declare function servicesFacts(scan: any, manifest: any): {
+    kind: string;
+    facts: string[];
+};
+export declare function fileFacts({ ctx, externals }: {
+    ctx: any;
+    externals: any;
+}): {
+    kind: string;
+    facts: string[];
+};
+export declare function tourStopFacts({ ctx, externals, stop, index, total }: Record<string, any>): {
+    kind: string;
+    facts: string[];
+};
+export declare function folderFacts(scan: any, facts: any, folder: any): {
+    kind: string;
+    facts: string[];
+};

package/shared/diagram/aiFacts.js

@@ -9,137 +9,134 @@
 //
 // No DOM, no state import, no network: importable in Node, like everything
 // under shared/.
-
 import { topFolderOf } from '../analyzer/pathUtil.js';
 import { scanIndex } from '../analyzer/graph.js';
-
 // How much source text a file sheet may carry. Enough for the model to see the
 // shape of a normal module; short enough to leave room for its answer.
 const SOURCE_BUDGET = 9000;
-
 // The repo-relative subject of the current view, and which sheet it wants.
 // `view` here is the sheet's name, not the app's: an atlas card mirrors another
 // view, and the files/deep-dive distinction becomes 'file' or 'folder'.
 export function diagramTarget(s) {
-  if (s.view === 'atlas' && s.atlasOpen) {
-    const it = s.atlasOpen;
-    // A card shows exactly what its own view would show, so it asks for the
-    // same sheet. This used to be done by assigning to state.view, recursing,
-    // and putting the old values back in a `finally`.
-    if (it.kind === 'file') return { view: 'file', path: it.path };
-    if (it.kind === 'folder') return { view: 'folder', path: it.path };
-    if (it.kind === 'layers') return { view: 'patterns', path: '' };
-    if (it.kind === 'overview') return { view: 'map', path: '' };
-    return { view: it.kind, path: '' };
-  }
-  if (s.view === 'tour') return { view: 'tour', path: s.tour.stops[s.tour.idx]?.path || '' };
-  if (s.view === 'map' || s.view === 'patterns' || s.view === 'services') {
-    return { view: s.view, path: '' };
-  }
-  // Everything else is the files view or one of its neighbours: a file if one
-  // is open in the deep-dive, otherwise the folder being shown.
-  return s.detail ? { view: 'file', path: s.detail } : { view: 'folder', path: s.folder };
+    if (s.view === 'atlas' && s.atlasOpen) {
+        const it = s.atlasOpen;
+        // A card shows exactly what its own view would show, so it asks for the
+        // same sheet. This used to be done by assigning to state.view, recursing,
+        // and putting the old values back in a `finally`.
+        if (it.kind === 'file')
+            return { view: 'file', path: it.path };
+        if (it.kind === 'folder')
+            return { view: 'folder', path: it.path };
+        if (it.kind === 'layers')
+            return { view: 'patterns', path: '' };
+        if (it.kind === 'overview')
+            return { view: 'map', path: '' };
+        return { view: it.kind, path: '' };
+    }
+    if (s.view === 'tour')
+        return { view: 'tour', path: s.tour.stops[s.tour.idx]?.path || '' };
+    if (s.view === 'map' || s.view === 'patterns' || s.view === 'services') {
+        return { view: s.view, path: '' };
+    }
+    // Everything else is the files view or one of its neighbours: a file if one
+    // is open in the deep-dive, otherwise the folder being shown.
+    return s.detail ? { view: 'file', path: s.detail } : { view: 'folder', path: s.folder };
 }
-
 // The third-party packages one file uses, by name.
 export function externalsFor(scan, path) {
-  return (scan.externals || []).filter((x) => x.usedBy.includes(path)).map((x) => x.name);
+    return (scan.externals || []).filter((x) => x.usedBy.includes(path)).map((x) => x.name);
 }
-
 export function overviewFacts(scan, facts) {
-  const counts = new Map();
-  for (const f of scan.files) {
-    const top = topFolderOf(f.path);
-    counts.set(top, (counts.get(top) || 0) + 1);
-  }
-  return {
-    kind: 'overview map',
-    facts: [
-      'Top folders (parsed file count): ' + [...counts.entries()].map(([k, v]) => `${k} (${v})`).join(', '),
-      'Dependencies between folders (from -> to: edge count): ' + (facts.folderEdges.map((e) => `${e.from} -> ${e.to}: ${e.count}`).join('; ') || 'none'),
-      'Entry points: ' + (facts.entries.join(', ') || 'none found'),
-      'Most depended-on files (fan-in): ' + (facts.hubs.slice(0, 6).map((h) => `${h.path} (${h.fanIn})`).join(', ') || 'none'),
-    ],
-  };
+    const counts = new Map();
+    for (const f of scan.files) {
+        const top = topFolderOf(f.path);
+        counts.set(top, (counts.get(top) || 0) + 1);
+    }
+    return {
+        kind: 'overview map',
+        facts: [
+            'Top folders (parsed file count): ' + [...counts.entries()].map(([k, v]) => `${k} (${v})`).join(', '),
+            'Dependencies between folders (from -> to: edge count): ' + (facts.folderEdges.map((e) => `${e.from} -> ${e.to}: ${e.count}`).join('; ') || 'none'),
+            'Entry points: ' + (facts.entries.join(', ') || 'none found'),
+            'Most depended-on files (fan-in): ' + (facts.hubs.slice(0, 6).map((h) => `${h.path} (${h.fanIn})`).join(', ') || 'none'),
+        ],
+    };
 }
-
 export function layersFacts(facts, patterns) {
-  const L = patterns.layersInfo;
-  return {
-    kind: 'architecture layers diagram',
-    facts: [
-      'Files grouped by import depth (longest chain from an entry point):',
-      ...L.layers.map((l, i) => `  depth ${i}: ${l.slice(0, 14).join(', ')}${l.length > 14 ? ` …+${l.length - 14} more` : ''}`),
-      'Not reachable from any entry: ' + (L.unreachable.slice(0, 10).join(', ') || 'none'),
-      'Circular dependency loops: ' + (facts.cycles.map((c) => c.slice(0, 6).join(' <-> ')).join('; ') || 'none'),
-      'Hubs (fan-in): ' + (facts.hubs.slice(0, 6).map((h) => `${h.path} (${h.fanIn})`).join(', ') || 'none'),
-    ],
-  };
+    const L = patterns.layersInfo;
+    return {
+        kind: 'architecture layers diagram',
+        facts: [
+            'Files grouped by import depth (longest chain from an entry point):',
+            ...L.layers.map((l, i) => `  depth ${i}: ${l.slice(0, 14).join(', ')}${l.length > 14 ? ` …+${l.length - 14} more` : ''}`),
+            'Not reachable from any entry: ' + (L.unreachable.slice(0, 10).join(', ') || 'none'),
+            'Circular dependency loops: ' + (facts.cycles.map((c) => c.slice(0, 6).join(' <-> ')).join('; ') || 'none'),
+            'Hubs (fan-in): ' + (facts.hubs.slice(0, 6).map((h) => `${h.path} (${h.fanIn})`).join(', ') || 'none'),
+        ],
+    };
 }
-
 export function servicesFacts(scan, manifest) {
-  return {
-    kind: 'services diagram',
-    facts: [
-      'Services (name | image | build | ports | command): ' +
-        ((manifest.services || []).map((s) => [s.name, s.image, s.build, (s.ports || []).join('+'), s.command].filter(Boolean).join(' | ')).join('; ') || 'none detected'),
-      'Top folders: ' + scan.folders.filter((f) => f.depth === 1).slice(0, 8).map((f) => f.path).join(', '),
-    ],
-  };
+    return {
+        kind: 'services diagram',
+        facts: [
+            'Services (name | image | build | ports | command): ' +
+                ((manifest.services || []).map((s) => [s.name, s.image, s.build, (s.ports || []).join('+'), s.command].filter(Boolean).join(' | ')).join('; ') || 'none detected'),
+            'Top folders: ' + scan.folders.filter((f) => f.depth === 1).slice(0, 8).map((f) => f.path).join(', '),
+        ],
+    };
 }
-
 // The deep-dive sheet: one file, its neighbours, and its source if we have it.
 export function fileFacts({ ctx, externals }) {
-  return {
-    kind: 'file deep-dive flowchart',
-    facts: [
-      `File: ${ctx.path} (role: ${ctx.role})`,
-      `Imported by ${ctx.fanIn} files: ${ctx.importers.join(', ') || 'none'}`,
-      `Imports ${ctx.fanOut} files: ${ctx.imports.join(', ') || 'none'}`,
-      `External packages: ${externals.join(', ') || 'none'}`,
-      ctx.functions?.length ? `Functions: ${ctx.functions.join(', ')}` : '',
-      ctx.source ? `Source, possibly truncated:\n${ctx.source.slice(0, SOURCE_BUDGET)}` : '(source unavailable)',
-    ].filter(Boolean),
-  };
+    return {
+        kind: 'file deep-dive flowchart',
+        facts: [
+            `File: ${ctx.path} (role: ${ctx.role})`,
+            `Imported by ${ctx.fanIn} files: ${ctx.importers.join(', ') || 'none'}`,
+            `Imports ${ctx.fanOut} files: ${ctx.imports.join(', ') || 'none'}`,
+            `External packages: ${externals.join(', ') || 'none'}`,
+            ctx.functions?.length ? `Functions: ${ctx.functions.join(', ')}` : '',
+            ctx.source ? `Source, possibly truncated:\n${ctx.source.slice(0, SOURCE_BUDGET)}` : '(source unavailable)',
+        ].filter(Boolean),
+    };
 }
-
 // The same file, but framed as a stop on the newcomer's tour: the model is told
 // where it is in the sequence and why the guide stopped, which is what turns a
 // dependency picture into an explanation.
 export function tourStopFacts({ ctx, externals, stop, index, total }) {
-  if (!stop) return { kind: 'tour stop diagram', facts: ['No stop is selected.'] };
-  return {
-    kind: 'guided-tour stop diagram',
-    facts: [
-      `This is stop ${index + 1} of ${total} on a newcomer's guided tour of the repo.`,
-      `Why the guide stops here: ${stop.why}`,
-      `File: ${ctx.path} (role: ${ctx.role})`,
-      `Imported by ${ctx.fanIn} files: ${ctx.importers.join(', ') || 'none'}`,
-      `Imports ${ctx.fanOut} files: ${ctx.imports.join(', ') || 'none'}`,
-      `External packages: ${externals.join(', ') || 'none'}`,
-      ctx.functions?.length ? `Functions: ${ctx.functions.join(', ')}` : '',
-      ctx.source ? `Source, possibly truncated:\n${ctx.source.slice(0, SOURCE_BUDGET)}` : '(source unavailable)',
-      'Draw what a guide would point at: how this file connects to the repo around it, and the flow between its main parts.',
-    ].filter(Boolean),
-  };
+    if (!stop)
+        return { kind: 'tour stop diagram', facts: ['No stop is selected.'] };
+    return {
+        kind: 'guided-tour stop diagram',
+        facts: [
+            `This is stop ${index + 1} of ${total} on a newcomer's guided tour of the repo.`,
+            `Why the guide stops here: ${stop.why}`,
+            `File: ${ctx.path} (role: ${ctx.role})`,
+            `Imported by ${ctx.fanIn} files: ${ctx.importers.join(', ') || 'none'}`,
+            `Imports ${ctx.fanOut} files: ${ctx.imports.join(', ') || 'none'}`,
+            `External packages: ${externals.join(', ') || 'none'}`,
+            ctx.functions?.length ? `Functions: ${ctx.functions.join(', ')}` : '',
+            ctx.source ? `Source, possibly truncated:\n${ctx.source.slice(0, SOURCE_BUDGET)}` : '(source unavailable)',
+            'Draw what a guide would point at: how this file connects to the repo around it, and the flow between its main parts.',
+        ].filter(Boolean),
+    };
 }
-
 export function folderFacts(scan, facts, folder) {
-  const here = scanIndex(scan).filesIn(folder);
-  const localSet = new Set(here.map((f) => f.path));
-  const internal = scan.edges.filter((e) => localSet.has(e.from) && localSet.has(e.to));
-  const outward = scan.edges.filter((e) => localSet.has(e.from) && !localSet.has(e.to));
-  const inward = scan.edges.filter((e) => !localSet.has(e.from) && localSet.has(e.to));
-  return {
-    kind: 'folder import graph',
-    facts: [
-      `Folder: ${folder || '(repo root)'} — ${here.length} parsed files`,
-      'Files (fan-in/fan-out): ' + here.map((f) => `${f.path} (${facts.fanIn[f.path] || 0}/${facts.fanOut[f.path] || 0})`).join(', '),
-      'Edges inside the folder: ' + (internal.map((e) => `${e.from} -> ${e.to}`).join('; ') || 'none'),
-      // Capped: a folder that everything imports would otherwise fill the
-      // prompt with edges and crowd out the rest of the sheet.
-      'Reaching out of it: ' + (outward.slice(0, 12).map((e) => `${e.from} -> ${e.to}`).join('; ') || 'none'),
-      'Pulled in from outside: ' + (inward.slice(0, 12).map((e) => `${e.from} -> ${e.to}`).join('; ') || 'none'),
-    ],
-  };
+    const here = scanIndex(scan).filesIn(folder);
+    const localSet = new Set(here.map((f) => f.path));
+    const internal = scan.edges.filter((e) => localSet.has(e.from) && localSet.has(e.to));
+    const outward = scan.edges.filter((e) => localSet.has(e.from) && !localSet.has(e.to));
+    const inward = scan.edges.filter((e) => !localSet.has(e.from) && localSet.has(e.to));
+    return {
+        kind: 'folder import graph',
+        facts: [
+            `Folder: ${folder || '(repo root)'} — ${here.length} parsed files`,
+            'Files (fan-in/fan-out): ' + here.map((f) => `${f.path} (${facts.fanIn[f.path] || 0}/${facts.fanOut[f.path] || 0})`).join(', '),
+            'Edges inside the folder: ' + (internal.map((e) => `${e.from} -> ${e.to}`).join('; ') || 'none'),
+            // Capped: a folder that everything imports would otherwise fill the
+            // prompt with edges and crowd out the rest of the sheet.
+            'Reaching out of it: ' + (outward.slice(0, 12).map((e) => `${e.from} -> ${e.to}`).join('; ') || 'none'),
+            'Pulled in from outside: ' + (inward.slice(0, 12).map((e) => `${e.from} -> ${e.to}`).join('; ') || 'none'),
+        ],
+    };
 }
+//# sourceMappingURL=aiFacts.js.map

package/shared/diagram/aiFacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aiFacts.js","sourceRoot":"","sources":["../../src/shared/diagram/aiFacts.ts"],"names":[],"mappings":"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","sourcesContent":["// The fact sheets the AI draws from.\n//\n// Every \"AI draft\" of a diagram is a prompt plus a list of plain-English facts\n// pulled out of the graph. Keeping the sheets here, apart from the streaming and\n// the button states, has two payoffs: the wording is what the model actually\n// sees and can be read without a browser, and the fiddly question of *which*\n// sheet a given view wants — an opened atlas card borrows another view's — is a\n// pure function with a test rather than a temporary mutation of app state.\n//\n// No DOM, no state import, no network: importable in Node, like everything\n// under shared/.\n\nimport { topFolderOf } from '../analyzer/pathUtil.js';\nimport { scanIndex } from '../analyzer/graph.js';\n\n// How much source text a file sheet may carry. Enough for the model to see the\n// shape of a normal module; short enough to leave room for its answer.\nconst SOURCE_BUDGET = 9000;\n\n// The repo-relative subject of the current view, and which sheet it wants.\n// `view` here is the sheet's name, not the app's: an atlas card mirrors another\n// view, and the files/deep-dive distinction becomes 'file' or 'folder'.\nexport function diagramTarget(s) {\n  if (s.view === 'atlas' && s.atlasOpen) {\n    const it = s.atlasOpen;\n    // A card shows exactly what its own view would show, so it asks for the\n    // same sheet. This used to be done by assigning to state.view, recursing,\n    // and putting the old values back in a `finally`.\n    if (it.kind === 'file') return { view: 'file', path: it.path };\n    if (it.kind === 'folder') return { view: 'folder', path: it.path };\n    if (it.kind === 'layers') return { view: 'patterns', path: '' };\n    if (it.kind === 'overview') return { view: 'map', path: '' };\n    return { view: it.kind, path: '' };\n  }\n  if (s.view === 'tour') return { view: 'tour', path: s.tour.stops[s.tour.idx]?.path || '' };\n  if (s.view === 'map' || s.view === 'patterns' || s.view === 'services') {\n    return { view: s.view, path: '' };\n  }\n  // Everything else is the files view or one of its neighbours: a file if one\n  // is open in the deep-dive, otherwise the folder being shown.\n  return s.detail ? { view: 'file', path: s.detail } : { view: 'folder', path: s.folder };\n}\n\n// The third-party packages one file uses, by name.\nexport function externalsFor(scan, path) {\n  return (scan.externals || []).filter((x) => x.usedBy.includes(path)).map((x) => x.name);\n}\n\nexport function overviewFacts(scan, facts) {\n  const counts = new Map();\n  for (const f of scan.files) {\n    const top = topFolderOf(f.path);\n    counts.set(top, (counts.get(top) || 0) + 1);\n  }\n  return {\n    kind: 'overview map',\n    facts: [\n      'Top folders (parsed file count): ' + [...counts.entries()].map(([k, v]) => `${k} (${v})`).join(', '),\n      'Dependencies between folders (from -> to: edge count): ' + (facts.folderEdges.map((e) => `${e.from} -> ${e.to}: ${e.count}`).join('; ') || 'none'),\n      'Entry points: ' + (facts.entries.join(', ') || 'none found'),\n      'Most depended-on files (fan-in): ' + (facts.hubs.slice(0, 6).map((h) => `${h.path} (${h.fanIn})`).join(', ') || 'none'),\n    ],\n  };\n}\n\nexport function layersFacts(facts, patterns) {\n  const L = patterns.layersInfo;\n  return {\n    kind: 'architecture layers diagram',\n    facts: [\n      'Files grouped by import depth (longest chain from an entry point):',\n      ...L.layers.map((l, i) => `  depth ${i}: ${l.slice(0, 14).join(', ')}${l.length > 14 ? ` …+${l.length - 14} more` : ''}`),\n      'Not reachable from any entry: ' + (L.unreachable.slice(0, 10).join(', ') || 'none'),\n      'Circular dependency loops: ' + (facts.cycles.map((c) => c.slice(0, 6).join(' <-> ')).join('; ') || 'none'),\n      'Hubs (fan-in): ' + (facts.hubs.slice(0, 6).map((h) => `${h.path} (${h.fanIn})`).join(', ') || 'none'),\n    ],\n  };\n}\n\nexport function servicesFacts(scan, manifest) {\n  return {\n    kind: 'services diagram',\n    facts: [\n      'Services (name | image | build | ports | command): ' +\n        ((manifest.services || []).map((s) => [s.name, s.image, s.build, (s.ports || []).join('+'), s.command].filter(Boolean).join(' | ')).join('; ') || 'none detected'),\n      'Top folders: ' + scan.folders.filter((f) => f.depth === 1).slice(0, 8).map((f) => f.path).join(', '),\n    ],\n  };\n}\n\n// The deep-dive sheet: one file, its neighbours, and its source if we have it.\nexport function fileFacts({ ctx, externals }) {\n  return {\n    kind: 'file deep-dive flowchart',\n    facts: [\n      `File: ${ctx.path} (role: ${ctx.role})`,\n      `Imported by ${ctx.fanIn} files: ${ctx.importers.join(', ') || 'none'}`,\n      `Imports ${ctx.fanOut} files: ${ctx.imports.join(', ') || 'none'}`,\n      `External packages: ${externals.join(', ') || 'none'}`,\n      ctx.functions?.length ? `Functions: ${ctx.functions.join(', ')}` : '',\n      ctx.source ? `Source, possibly truncated:\\n${ctx.source.slice(0, SOURCE_BUDGET)}` : '(source unavailable)',\n    ].filter(Boolean),\n  };\n}\n\n// The same file, but framed as a stop on the newcomer's tour: the model is told\n// where it is in the sequence and why the guide stopped, which is what turns a\n// dependency picture into an explanation.\nexport function tourStopFacts({ ctx, externals, stop, index, total }: Record<string, any>) {\n  if (!stop) return { kind: 'tour stop diagram', facts: ['No stop is selected.'] };\n  return {\n    kind: 'guided-tour stop diagram',\n    facts: [\n      `This is stop ${index + 1} of ${total} on a newcomer's guided tour of the repo.`,\n      `Why the guide stops here: ${stop.why}`,\n      `File: ${ctx.path} (role: ${ctx.role})`,\n      `Imported by ${ctx.fanIn} files: ${ctx.importers.join(', ') || 'none'}`,\n      `Imports ${ctx.fanOut} files: ${ctx.imports.join(', ') || 'none'}`,\n      `External packages: ${externals.join(', ') || 'none'}`,\n      ctx.functions?.length ? `Functions: ${ctx.functions.join(', ')}` : '',\n      ctx.source ? `Source, possibly truncated:\\n${ctx.source.slice(0, SOURCE_BUDGET)}` : '(source unavailable)',\n      'Draw what a guide would point at: how this file connects to the repo around it, and the flow between its main parts.',\n    ].filter(Boolean),\n  };\n}\n\nexport function folderFacts(scan, facts, folder) {\n  const here = scanIndex(scan).filesIn(folder);\n  const localSet = new Set(here.map((f) => f.path));\n  const internal = scan.edges.filter((e) => localSet.has(e.from) && localSet.has(e.to));\n  const outward = scan.edges.filter((e) => localSet.has(e.from) && !localSet.has(e.to));\n  const inward = scan.edges.filter((e) => !localSet.has(e.from) && localSet.has(e.to));\n  return {\n    kind: 'folder import graph',\n    facts: [\n      `Folder: ${folder || '(repo root)'} — ${here.length} parsed files`,\n      'Files (fan-in/fan-out): ' + here.map((f) => `${f.path} (${facts.fanIn[f.path] || 0}/${facts.fanOut[f.path] || 0})`).join(', '),\n      'Edges inside the folder: ' + (internal.map((e) => `${e.from} -> ${e.to}`).join('; ') || 'none'),\n      // Capped: a folder that everything imports would otherwise fill the\n      // prompt with edges and crowd out the rest of the sheet.\n      'Reaching out of it: ' + (outward.slice(0, 12).map((e) => `${e.from} -> ${e.to}`).join('; ') || 'none'),\n      'Pulled in from outside: ' + (inward.slice(0, 12).map((e) => `${e.from} -> ${e.to}`).join('; ') || 'none'),\n    ],\n  };\n}\n"]}

package/shared/diagram/aiMermaid.d.ts

@@ -0,0 +1,5 @@
+export declare function extractAIDiagram(text: any): {
+    caption: string;
+    body: string;
+};
+export declare function matchNodeText(text: any, files: any): any;