vt-dep

Val Town-native dependency analyzer for small JS/TS projects.

API

POST /analyze\ncontent-type: application/json\n\n{\n  \"files\": {\n    \"main.ts\": \"import { helper } from './helper.ts';\",\n    \"helper.ts\": \"export const helper = 1;\"\n  }\n}

Try /sample or /sample/mermaid.

\n \n`;\n}\n\nexport default handleRequest;\n\nexport const sample = analyzeVals({\n \"main.ts\": `\n import { helper } from \"./helper.ts\";\n import lodash from \"npm:lodash\";\n const dynamic = await import(\"./dynamic.ts\");\n console.log(helper, lodash, dynamic);\n `,\n \"helper.ts\": `\n export { cycle } from \"./cycle\";\n export const helper = 1;\n `,\n \"cycle.ts\": `\n import \"./helper.ts\";\n export const cycle = true;\n `,\n \"dynamic.ts\": `\n import { email } from \"https://esm.town/v/chad/email\";\n export default email;\n `,\n});\n","label",[132],"ac25d69a-5330-11f1-a1ae-ee650bb23af1","deno.lock","ac25d74e-5330-11f1-a1ae-ee650bb23af1",2,["D",1779160393679],"{\n \"version\": \"5\",\n \"specifiers\": {\n \"npm:@babel/parser@*\": \"7.29.3\",\n \"npm:@babel/traverse@*\": \"7.29.0\"\n },\n \"npm\": {\n \"@babel/code-frame@7.29.0\": {\n \"integrity\": \"sha512-9NhCeYjq9+3uxgdtp20LSiJXJvN0FeCtNGpJxuMFZ1Kv3cWUNb6DOhJwUvcVCzKGR66cw4njwM6hrJLqgOwbcw==\",\n \"dependencies\": [\n \"@babel/helper-validator-identifier\",\n \"js-tokens\",\n \"picocolors\"\n ]\n },\n \"@babel/generator@7.29.1\": {\n \"integrity\": \"sha512-qsaF+9Qcm2Qv8SRIMMscAvG4O3lJ0F1GuMo5HR/Bp02LopNgnZBC/EkbevHFeGs4ls/oPz9v+Bsmzbkbe+0dUw==\",\n \"dependencies\": [\n \"@babel/parser\",\n \"@babel/types\",\n \"@jridgewell/gen-mapping\",\n \"@jridgewell/trace-mapping\",\n \"jsesc\"\n ]\n },\n \"@babel/helper-globals@7.28.0\": {\n \"integrity\": \"sha512-+W6cISkXFa1jXsDEdYA8HeevQT/FULhxzR99pxphltZcVaugps53THCeiWA8SguxxpSp3gKPiuYfSWopkLQ4hw==\"\n },\n \"@babel/helper-string-parser@7.27.1\": {\n \"integrity\": \"sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==\"\n },\n \"@babel/helper-validator-identifier@7.28.5\": {\n \"integrity\": \"sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q==\"\n },\n \"@babel/parser@7.29.3\": {\n \"integrity\": \"sha512-b3ctpQwp+PROvU/cttc4OYl4MzfJUWy6FZg+PMXfzmt/+39iHVF0sDfqay8TQM3JA2EUOyKcFZt75jWriQijsA==\",\n \"dependencies\": [\n \"@babel/types\"\n ],\n \"bin\": true\n },\n \"@babel/template@7.28.6\": {\n \"integrity\": \"sha512-YA6Ma2KsCdGb+WC6UpBVFJGXL58MDA6oyONbjyF/+5sBgxY/dwkhLogbMT2GXXyU84/IhRw/2D1Os1B/giz+BQ==\",\n \"dependencies\": [\n \"@babel/code-frame\",\n \"@babel/parser\",\n \"@babel/types\"\n ]\n },\n \"@babel/traverse@7.29.0\": {\n \"integrity\": \"sha512-4HPiQr0X7+waHfyXPZpWPfWL/J7dcN1mx9gL6WdQVMbPnF3+ZhSMs8tCxN7oHddJE9fhNE7+lxdnlyemKfJRuA==\",\n \"dependencies\": [\n \"@babel/code-frame\",\n \"@babel/generator\",\n \"@babel/helper-globals\",\n \"@babel/parser\",\n \"@babel/template\",\n \"@babel/types\",\n \"debug\"\n ]\n },\n \"@babel/types@7.29.0\": {\n \"integrity\": \"sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A==\",\n \"dependencies\": [\n \"@babel/helper-string-parser\",\n \"@babel/helper-validator-identifier\"\n ]\n },\n \"@jridgewell/gen-mapping@0.3.13\": {\n \"integrity\": \"sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==\",\n \"dependencies\": [\n \"@jridgewell/sourcemap-codec\",\n \"@jridgewell/trace-mapping\"\n ]\n },\n \"@jridgewell/resolve-uri@3.1.2\": {\n \"integrity\": \"sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==\"\n },\n \"@jridgewell/sourcemap-codec@1.5.5\": {\n \"integrity\": \"sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==\"\n },\n \"@jridgewell/trace-mapping@0.3.31\": {\n \"integrity\": \"sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==\",\n \"dependencies\": [\n \"@jridgewell/resolve-uri\",\n \"@jridgewell/sourcemap-codec\"\n ]\n },\n \"debug@4.4.3\": {\n \"integrity\": \"sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==\",\n \"dependencies\": [\n \"ms\"\n ]\n },\n \"js-tokens@4.0.0\": {\n \"integrity\": \"sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==\"\n },\n \"jsesc@3.1.0\": {\n \"integrity\": \"sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==\",\n \"bin\": true\n },\n \"ms@2.1.3\": {\n \"integrity\": \"sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==\"\n },\n \"picocolors@1.1.1\": {\n \"integrity\": \"sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==\"\n }\n }\n}\n",[144],"ac29fe3c-5330-11f1-a906-ee650bb23af1","deno.json","ac29ff68-5330-11f1-a906-ee650bb23af1",3,["D",1779160393708],"{\n \"compilerOptions\": {\n \"lib\": [\"deno.ns\", \"dom\", \"esnext\"],\n \"strict\": true\n }\n}\n",[151],"9ba45532-5333-11f1-8a91-ee650bb23af1","README.md","6dc04424-532d-11f1-b320-ee650bb23af1",8,["D",1779161654473],"# Val Dependency Cruiser\n\nA small Val Town-native dependency analyzer inspired by\n[`dependency-cruiser`](https://github.com/sverweij/dependency-cruiser), focused\non reading and visualizing dependencies between Vals and small Val Town\nprojects.\n\n## Goal\n\nRun as a Val that can read source for other Vals/projects, extract their\nimports, and produce a useful dependency graph plus a few simple checks.\n\nThis is **not** intended to port all of dependency-cruiser. Full\ndependency-cruiser assumes a local Node project with filesystem crawling,\n`node_modules`, package manifests, config loading, caches, and subprocess-based\ngraph rendering. Val Town projects are smaller and can use a simpler analyzer.\n\n## Current API\n\nThe Val exports `analyzeVals(files)` for direct use and also exposes an HTTP\nhandler.\n\n```ts\nimport { analyzeVals } from \"https://esm.town/v/chad/vt_dep\";\n\nconst result = analyzeVals({\n \"main.ts\": `import { helper } from \"./helper.ts\";`,\n \"helper.ts\": `export const helper = 1;`,\n});\n```\n\nHTTP:\n\n```http\nPOST /analyze\ncontent-type: application/json\n\n{\n \"files\": {\n \"main.ts\": \"import { helper } from './helper.ts';\",\n \"helper.ts\": \"export const helper = 1;\"\n }\n}\n```\n\nOutput:\n\n- dependency graph as JSON\n- detected cycles\n- unresolved imports\n- parse errors\n- external dependencies grouped by type\n- Mermaid graph text for quick visualization\n\nTry:\n\n- `/sample` for example JSON\n- `/sample/mermaid` for example Mermaid output\n\nExample API shape:\n\n```ts\ntype SourceMap = Record;\n\ntype DependencyKind =\n | \"local\"\n | \"val\"\n | \"npm\"\n | \"jsr\"\n | \"url\"\n | \"builtin\"\n | \"unresolved\";\n\ntype Dependency = {\n specifier: string;\n resolved?: string;\n kind: DependencyKind;\n dynamic: boolean;\n};\n\ntype ModuleNode = {\n id: string;\n dependencies: Dependency[];\n};\n\ntype AnalysisResult = {\n modules: ModuleNode[];\n cycles: string[][];\n unresolved: Dependency[];\n externals: Dependency[];\n mermaid: string;\n};\n\nexport async function analyzeVals(files: SourceMap): Promise;\n```\n\n## Import forms to support first\n\nStatic ES modules:\n\n```ts\nimport x from \"./foo.ts\";\nimport { helper } from \"https://esm.town/v/chad/helper\";\nexport { thing } from \"./thing.ts\";\n```\n\nDynamic imports:\n\n```ts\nconst mod = await import(\"./mod.ts\");\n```\n\nBasic CommonJS, if encountered:\n\n```ts\nconst lodash = require(\"npm:lodash\");\n```\n\n## Dependency classification\n\n- `local` — relative project import like `./foo.ts` or `../lib/bar.ts`\n- `val` — Val Town URL/import like `https://esm.town/v/user/valName`\n- `npm` — `npm:package` or bare npm package imports if Val Town\n allows/normalizes them\n- `jsr` — `jsr:@scope/package`\n- `url` — other `http:`/`https:` imports\n- `builtin` — `node:fs`, `node:path`, etc.\n- `unresolved` — local-looking import that does not match known files\n\n## Likely implementation\n\nUse parser-level extraction instead of regexes.\n\nPotential libraries:\n\n- `npm:acorn`\n- `npm:acorn-walk`\n- `npm:acorn-jsx` if JSX is needed\n- Possibly `npm:@typescript-eslint/typescript-estree` or `npm:oxc-parser` later\n for better TypeScript support\n\nInitial extraction can be small:\n\n1. Parse source as module, falling back to loose/script mode if needed.\n2. Walk AST.\n3. Collect:\n - `ImportDeclaration`\n - `ExportNamedDeclaration.source`\n - `ExportAllDeclaration.source`\n - `ImportExpression` with string literal source\n - `CallExpression` where callee is `require` and first arg is a string\n literal\n4. Resolve/classify each specifier.\n5. Build adjacency list.\n6. Run DFS/Tarjan to find cycles.\n7. Emit Mermaid.\n\n## Resolution rules for MVP\n\nGiven `files: Record`:\n\n- Normalize module ids to POSIX-style paths.\n- For relative imports, resolve from importer directory.\n- Try exact match first.\n- Then try common extensions: `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`.\n- Then try `/index.ts`, `/index.tsx`, `/index.js`, etc.\n- Non-relative imports are classified as external unless they match a Val Town\n URL.\n\n## Example Mermaid output\n\n```mermaid\ngraph TD\n main_ts[main.ts] --> helper_ts[helper.ts]\n main_ts --> npm_lodash[npm:lodash]\n helper_ts --> val_chad_util[esm.town/v/chad/util]\n```\n\n## Later features\n\n- Fetch files from Val Town APIs directly.\n- Analyze one Val, a folder/project, or a user namespace.\n- HTML response with interactive graph.\n- Rule checks:\n - no cycles\n - no unresolved imports\n - no private/external Val imports\n - no npm imports outside allowlist\n - no imports from specific users/namespaces\n- `focus` mode: show only neighbors around one Val/file.\n- Diff mode: compare dependency graph between two versions.\n- Export dependency-cruiser-like JSON for compatibility with other tools.\n\n## Estimated effort\n\n- MVP analyzer: 1–2 days\n- Useful Val Town integration and nicer output: 3–5 days\n- Rule system and richer reporting: 1–2 weeks\n\n## Open questions\n\n- Which Val Town API endpoint should this use to read another Val/project's\n source?\n- Should this analyze only the current user's Vals or public Vals too?\n- Should output be a JSON API, an HTML page, or both?\n- Should the Val store historical graphs for diffs?\n",[158],"pulls","branches","forks","envVars",{"_171":60,"_173":60},"connections",{"_171":60,"_172":60},"count","unfilledCount","emptyCount",{"_41":157,"_32":158,"_30":159,"_134":-5,"_39":40,"_38":160,"_136":47,"_36":188,"_13":138,"_33":20,"_35":162,"_24":47,"_141":-5,"_179":189,"_27":190},{"_41":150,"_32":151,"_30":152,"_134":-5,"_39":40,"_38":153,"_136":25,"_36":185,"_13":60,"_33":20,"_35":155,"_24":47,"_141":-5,"_179":186,"_27":187},{"_41":143,"_32":144,"_30":145,"_134":-5,"_39":40,"_38":146,"_136":47,"_36":182,"_13":60,"_33":20,"_35":148,"_24":47,"_141":-5,"_179":183,"_27":184},{"_41":131,"_32":132,"_30":133,"_134":-5,"_39":40,"_38":135,"_136":47,"_36":178,"_13":138,"_33":139,"_35":140,"_24":47,"_141":-5,"_179":180,"_27":181},["D",1779161654473],"children",[],[132],["D",1779160393679],[],[144],["D",1779160393708],[],[151],["D",1779161654473],[],[158],["D",1779158999771],["D",1789515055826],{"_97":96,"_104":100},{"_97":96,"_98":-5,"_99":100,"_18":54,"_101":102,"_103":47},{"_13":86,"_32":87,"_41":40,"_88":42,"_89":-5,"_90":-5,"_91":-5,"_92":-5,"_93":-5,"_94":43,"_95":96},"ctx",{"_79":-5,"_124":229,"_230":231,"_232":233,"_234":47,"_235":47,"_236":47,"_237":25,"_238":-5,"_239":-7,"_240":-7,"_241":60,"_242":47,"_243":47,"_244":-5,"_245":47,"_246":47,"_247":47,"_248":-5},"ENV",{"_200":201,"_202":203,"_204":87,"_205":206,"_207":208,"_209":210,"_211":212,"_213":214,"_215":216,"_217":218,"_219":220,"_221":222,"_223":224,"_225":226,"_227":228},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

Diff · v11