codebase-onboarder 0.6.0 → 1.0.0

package/shared/analyzer/stack.js

@@ -2,100 +2,96 @@
 // 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'],
+    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',
+    '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}`,
+    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.
@@ -110,64 +106,61 @@ const REGISTRY = {
 // `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());
-
+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();
+    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) };
+    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) };
 }
-
+//# sourceMappingURL=stack.js.map

package/shared/analyzer/stack.js.map

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

package/shared/analyzer/tour.d.ts

@@ -0,0 +1,2 @@
+export declare function buildTourStops(scan: any, facts: any): any[];
+export declare function tourStopTitle(stop: any): any;

package/shared/analyzer/tour.js

@@ -7,63 +7,55 @@
 // 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);
+    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);
+    return baseName(stop.path);
 }
+//# sourceMappingURL=tour.js.map

package/shared/analyzer/tour.js.map

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

package/shared/analyzer/util.d.ts

@@ -0,0 +1,8 @@
+export declare function blankComments(source: any, { block, line, lineChar }?: Record<string, any>): any;
+export declare function jsCodeMask(source: any): string;
+export declare function lineOf(source: any, index: any): number;
+export declare function lineCounter(source: any): (index: any) => number;
+export declare function braceBodyEnd(source: any, openIndex: any): any;
+export declare function uniqueBy(items: any, key: any): any[];
+export declare function callsWithin(body: any, names: any): any[];
+export declare function declarationOrder(fns: any): Map<any, any>;