diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 00000000..e4f1b3a4 --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,47 @@ +name: Deploy site to GitHub Pages + +# Builds site/ (Vite + prerender) and publishes site/dist to https://byronwall.github.io/srcly/. +# Needs Settings › Pages › Source set to "GitHub Actions". +on: + push: + branches: [main] + paths: [site/**, .github/workflows/pages.yml] + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: false + +jobs: + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + timeout-minutes: 10 + defaults: + run: + working-directory: site + steps: + - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v4 + with: + version: 11.9.0 + - uses: actions/setup-node@v4 + with: + node-version: 24 + cache: pnpm + cache-dependency-path: site/pnpm-lock.yaml + - run: pnpm install --frozen-lockfile + - run: pnpm build + - uses: actions/configure-pages@v5 + - uses: actions/upload-pages-artifact@v3 + with: + path: site/dist + - id: deployment + uses: actions/deploy-pages@v4 diff --git a/site/DEPLOY.md b/site/DEPLOY.md deleted file mode 100644 index 3d58698b..00000000 --- a/site/DEPLOY.md +++ /dev/null @@ -1,13 +0,0 @@ -# Deploy - -Build the static site, then deploy it from the repository checkout: - -```sh -cd site -pnpm build -node scripts/deploy.mjs -``` - -The script publishes `dist/` to the `gh-pages` branch and adds `.nojekyll`. -It uses a temporary clone, keeps existing branch history, and pushes without force. -The commit author and committer are Byron Wall (`byron@byroni.us`). diff --git a/site/DESIGN.md b/site/DESIGN.md index 671116c8..6a4b37c3 100644 --- a/site/DESIGN.md +++ b/site/DESIGN.md @@ -1,32 +1,33 @@ # Public site -The public site extends Srcly's light application palette. It serves developers who want to inspect a local codebase or create a report for an agent. +The site serves developers who want to try Srcly on their own code, and readers who want to know how it works. +Its look comes from Srcly itself: the page is drawn like a scan. -## Surface modes +## The scope motif -- Landing: Persuade. Lead with real Srcly views, then give two paths: see the product or use it. -- Guides: Read. Group navigation by the visitor's task, keep the article easy to scan, and link search results to the matching section. -- Screenshot viewer: Experience. Let the captured application view fill the screen. Keep zoom, reset, close, keyboard focus, and native image-link fallback. +- Each landing section is a treemap scope: a 1px frame with a mono header strip (`views/`). +- The strip's right side names the part of Srcly's source that implements the section, with its real LOC and maximum complexity from `src/data/tree.json`, and links to it on GitHub. These numbers are never typed by hand. +- Blocks inside a section share 1px rules like treemap tiles (`.steps`, `.views`, `.workflows`). Do not use floating cards with gaps or shadows. +- The hero is a real treemap of Srcly's own source at the captured revision, with the headline in a label block cut into it. ## Tokens -- Canvas: `#f8fafc`; paper: `#fff`; ink: `#17212e`. -- Body detail: `#526273`; rules: `#dce3ea`. -- Links and actions: `#1769aa`; hover: `#0e548d`. -- Type: Inter for text; IBM Plex Mono for code and measurements. -- Page width: 1160px; hero type: 42–68px; body: 15px. -- Controls have visible focus outlines. Motion respects reduced-motion settings. +- Light follows the app's DESIGN.md (Precision Light Console): canvas `#f4f6f9`, paper `#fff`, ink `#0f172a`, rules `#e2e8f0` and `#cbd5e1`, links `#2563eb`. +- Dark is ink: canvas `#0b1220`, paper `#0f172a`, links `#8ab4ff`. The heat ramp stays the same, so tiles read the same in both themes. +- Heat ramp: Srcly's `TREEMAP_RAMP` (`#bfdbfe` → `#e9eef3` → `#fcd34d` → `#fb923c` → `#f87171`), sampled with the app's Lab interpolation in `src/treemap.tsx`. Use it only for data marks: tiles, swatches, the legend, the logo. +- N/A is gray diagonal hatching, never a ramp color. +- Type: Inter for prose; IBM Plex Mono for paths, numbers, scope names and commands. -## Product proof +## Content rules -- Use screenshots captured from the running application. Keep captions specific to the view and the action it supports. -- The hero uses the repository treemap. The gallery uses the treemap, code inspector, and data-flow views. -- The site must not imply that it scans files or that missing measurements equal zero. -- Do not invent metrics or terminal output to fill space. +- Every claim matches the code. Metric definitions come from the catalog; command output comes from a real run. +- Screenshots come from `scripts/capture.mjs`. Captions name the subject and revision. +- The site must not imply that it scans visitor files, or that a missing measurement is 0. +- "How I built it" is Byron's voice. Keep its first-person claims to what the project page and its posts support. -## Guides +## Docs pages - Navigation groups: Discover, Use Srcly, and Automate & configure. -- Keep the page title, short summary, and edit link in one compact heading area. -- Search results show matching text and link to a matching section when one exists. -- Screenshot figures can open at full size. Keep the image link usable without JavaScript. +- Keep the page title, summary, and edit link in one heading area. +- Search results show matching text and link to the matching section. +- Screenshot figures open at full size; the image link still works without JavaScript. diff --git a/site/README.md b/site/README.md index bd16bcd5..fca1ccd1 100644 --- a/site/README.md +++ b/site/README.md @@ -15,24 +15,36 @@ Open the printed development URL with `/srcly/` appended. The build writes `site/dist/`. Each guide has a complete HTML page, with page metadata and a canonical URL. The browser adds section-linked guide search, copy buttons, and a full-size screenshot viewer. -Edit the product tour, design notes, and user guides in `src/docs/pages/`. -Keep command examples in sync with `server/app/run.py`. -Add new pages to the navigation in `src/App.tsx` when required. -The build reads page titles and introductions from Markdown for search metadata. +## Content -The site uses its own dependencies and build. It does not ship inside the Python wheel. -Pull requests build the site and run its browser checks. See [DEPLOY.md](DEPLOY.md) to publish the build to GitHub Pages. +- The landing page (`src/Landing.tsx`) is the user guide in one page: install, how to read the treemap, the views, workflows, the command line, a reference, and a short "How I built it". +- The reference tables (`src/Reference.tsx`) read `src/data/catalog.json`, Srcly's own metric catalog. Do not retype metric definitions. +- The longer guides are Markdown in `src/docs/pages/`. Add a new page to the navigation in `src/App.tsx`. +- Keep command examples in sync with `server/app/run.py`. -## Reference and design +## Screenshots and data -Draftably's public site supplied the structure: a product preview, direct setup actions, and searchable task guides. -Srcly keeps its light surfaces, blue links, Inter type, and IBM Plex Mono commands. -Real app screenshots show Srcly inspecting its public source and checked-in fixtures. -Capture provenance is in `public/screenshots/README.md`. The site does not scan visitor files. -The docs have three groups: Discover, Use Srcly, and Automate & configure. +`node scripts/capture.mjs [name,name…]` captures everything from a real Srcly run on Srcly's own source. +It clones this checkout's HEAD to a temporary `srcly` folder, starts the API and client on free ports with a temporary cache, and writes: + +- `public/screenshots/*.jpg`: the app at 1440 × 900 CSS pixels, 1.5x. +- `src/data/tree.json`: folder and file LOC and complexity, for the treemaps drawn on the page. +- `src/data/catalog.json`: the metric catalog and 2×2 presets. +- `src/data/cli.json`: real `hotspots` and `explain` output. +- `src/data/meta.json`: the source revision and totals the page cites. + +It needs the server venv (`cd server && uv sync`), client `node_modules`, and Google Chrome. +A full run takes about five minutes, most of it the compare shot, which scans two revisions. +Rerun it after a release that changes the UI, and commit the screenshots and data together. + +## Deploy + +`.github/workflows/pages.yml` builds the site and publishes `site/dist` on every push to `main` that touches `site/`. +Pages must use **Settings › Pages › Source: GitHub Actions**. Run the workflow by hand from the Actions tab to publish without a site change. +Pull requests run `.github/workflows/site.yml`: the build and the browser checks. ## Verification `pnpm test` runs a browser against the built site under `/srcly/`. -It checks static guide content, local links, images, search anchors, screenshot zoom, copy feedback, and narrow screens. +It checks the landing page, static guide content, local links, images, search anchors, screenshot zoom, copy feedback, and narrow screens. Keep screenshot evidence under the repository's ignored `tmp/` directory. diff --git a/site/package.json b/site/package.json index 6094ad65..a2bfc009 100644 --- a/site/package.json +++ b/site/package.json @@ -14,12 +14,14 @@ "dependencies": { "@fontsource-variable/inter": "^5.3.0", "@fontsource/ibm-plex-mono": "^5.3.0", + "d3-hierarchy": "^3.1.3", "lucide-solid": "^1.49.0", "marked": "^17.0.6", "solid-js": "^1.9.18" }, "devDependencies": { "@playwright/test": "1.62.0", + "@types/d3-hierarchy": "^3.1.7", "@types/node": "^24.19.2", "typescript": "~5.9.3", "vite": "^7.3.7", diff --git a/site/pnpm-lock.yaml b/site/pnpm-lock.yaml index b5a94088..9b1b0070 100644 --- a/site/pnpm-lock.yaml +++ b/site/pnpm-lock.yaml @@ -14,6 +14,9 @@ importers: '@fontsource/ibm-plex-mono': specifier: ^5.3.0 version: 5.3.0 + d3-hierarchy: + specifier: ^3.1.3 + version: 3.1.3 lucide-solid: specifier: ^1.49.0 version: 1.49.0(solid-js@1.9.18) @@ -27,6 +30,9 @@ importers: '@playwright/test': specifier: 1.62.0 version: 1.62.0 + '@types/d3-hierarchy': + specifier: ^3.1.7 + version: 3.1.7 '@types/node': specifier: ^24.19.2 version: 24.19.2 @@ -461,6 +467,9 @@ packages: '@types/babel__traverse@7.28.0': resolution: {integrity: sha512-8PvcXf70gTDZBgt9ptxJ8elBeBjcLOAcOtoO/mPJjtji1+CdGbHgm77om1GrsPxsiE+uXIpNSK64UYaIwQXd4Q==} + '@types/d3-hierarchy@3.1.7': + resolution: {integrity: sha512-tJFtNoYBtRtkNysX1Xq4sxtjK8YgoWUNpIiUee0/jHGRwqvzYxkq0hGVbbOGSz+JgFxxRu4K8nb3YpG3CMARtg==} + '@types/estree@1.0.10': resolution: {integrity: sha512-lTyOMnOcmRBzdCv6/4zUZCrEhV0xrqQiUZBZtVcbmLHBXKLnN8q89v/wKRF/Q0HbwVsqbIG3o5HDoFl9sduM+g==} @@ -500,6 +509,10 @@ packages: csstype@3.2.3: resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==} + d3-hierarchy@3.1.3: + resolution: {integrity: sha512-GRajN5ZcnEwYFWqqdzhG1qJ3+fDg6WWzk47TJg7ePY7yvYAgRfD2r1mUx+wviBOWuCwamCUzjwMSdato43jbGA==} + engines: {node: '>=12'} + debug@4.4.3: resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==} engines: {node: '>=6.0'} @@ -1048,6 +1061,8 @@ snapshots: dependencies: '@babel/types': 7.29.11 + '@types/d3-hierarchy@3.1.7': {} + '@types/estree@1.0.10': {} '@types/node@24.19.2': @@ -1086,6 +1101,8 @@ snapshots: csstype@3.2.3: {} + d3-hierarchy@3.1.3: {} + debug@4.4.3: dependencies: ms: 2.1.3 diff --git a/site/public/favicon.svg b/site/public/favicon.svg index abdda760..5b19a6bd 100644 --- a/site/public/favicon.svg +++ b/site/public/favicon.svg @@ -1 +1 @@ - + diff --git a/site/public/screenshots/README.md b/site/public/screenshots/README.md index b8227850..165876c4 100644 --- a/site/public/screenshots/README.md +++ b/site/public/screenshots/README.md @@ -1,12 +1,16 @@ # Screenshot assets -These app screenshots come from a real local Srcly run at source revision `653037aa` (2026-11-06). The scanned source is the public `client/src` tree. The graph examples use the checked-in `engine/examples/symbol-graph` fixture. No private repository data appears in these images. +`site/scripts/capture.mjs` writes every JPEG here from a real local Srcly run. Rerun it rather than editing an image. -Each JPEG is 1440 × 960 pixels at quality 88. Capture URLs, UI steps, raw PNG paths, and factual captions are recorded in `tmp/10x/docs/app/CAPTURES.md`. +The current set is Srcly scanning a clone of its own repository at `e4485453` (2026-11-14). The symbols and data-flow shots use the checked-in `engine/examples/symbol-graph` fixture. No private repository data appears in these images. -- `treemap.jpg` — client source tree sized by LOC and colored by maximum complexity. -- `hotspots.jpg` — ranked complexity list beside the treemap. -- `quadrant.jpg` — activity 2×2, with the Hot mess quadrant selected. -- `code-inspector.jpg` — `App.tsx` source and metrics, focused on the `openAt` complexity witness. -- `data-flow.jpg` — route trace with its partial outcome and callback handoff in the inspector. -- `symbols.jpg` — `NotePage` references in the symbol graph. +Each JPEG is 2160 × 1350 pixels: a 1440 × 900 viewport at 1.5x, quality 82. + +- `treemap.jpg`: the whole repository, sized by LOC and colored by maximum complexity. +- `hotspots.jpg`: Hot Spots ranking files by complexity beside the treemap. +- `quadrant.jpg`: the Activity 2×2, with the Hot mess quadrant selected. +- `code-inspector.jpg`: `client/src/viz/deps/viewModel.ts`, opened on `buildViewModel`, the repository's most complex function. +- `graph.jpg`: the import graph around `client/src/viz/treemap`. +- `compare.jpg`: compare mode for commit `5a8a9c38` (symbols dead and hub overlays). +- `symbols.jpg`: Symbols mode centered on `NotePage`. +- `data-flow.jpg`: the `/notes/[id]` trace from `NotePage`, with where it stops. diff --git a/site/public/screenshots/code-inspector.jpg b/site/public/screenshots/code-inspector.jpg index e4505840..f8ce0389 100644 Binary files a/site/public/screenshots/code-inspector.jpg and b/site/public/screenshots/code-inspector.jpg differ diff --git a/site/public/screenshots/compare.jpg b/site/public/screenshots/compare.jpg new file mode 100644 index 00000000..01ccd3ff Binary files /dev/null and b/site/public/screenshots/compare.jpg differ diff --git a/site/public/screenshots/data-flow.jpg b/site/public/screenshots/data-flow.jpg index 849b93eb..03461367 100644 Binary files a/site/public/screenshots/data-flow.jpg and b/site/public/screenshots/data-flow.jpg differ diff --git a/site/public/screenshots/graph.jpg b/site/public/screenshots/graph.jpg new file mode 100644 index 00000000..9be5a32c Binary files /dev/null and b/site/public/screenshots/graph.jpg differ diff --git a/site/public/screenshots/hotspots.jpg b/site/public/screenshots/hotspots.jpg index 70853665..af8c8cfe 100644 Binary files a/site/public/screenshots/hotspots.jpg and b/site/public/screenshots/hotspots.jpg differ diff --git a/site/public/screenshots/quadrant.jpg b/site/public/screenshots/quadrant.jpg index 561d1af3..43e4be28 100644 Binary files a/site/public/screenshots/quadrant.jpg and b/site/public/screenshots/quadrant.jpg differ diff --git a/site/public/screenshots/symbols.jpg b/site/public/screenshots/symbols.jpg index cd836781..9b447f00 100644 Binary files a/site/public/screenshots/symbols.jpg and b/site/public/screenshots/symbols.jpg differ diff --git a/site/public/screenshots/treemap.jpg b/site/public/screenshots/treemap.jpg index e1877c30..539bccce 100644 Binary files a/site/public/screenshots/treemap.jpg and b/site/public/screenshots/treemap.jpg differ diff --git a/site/scripts/capture.mjs b/site/scripts/capture.mjs new file mode 100644 index 00000000..238b12fa --- /dev/null +++ b/site/scripts/capture.mjs @@ -0,0 +1,165 @@ +// Captures the site's screenshots and data from a real Srcly run on Srcly's own source. +// +// cd site && node scripts/capture.mjs [name,name…] [--ref ] +// +// Needs the server venv (`cd server && uv sync`), client node_modules, and Google Chrome. +// It clones this checkout at `origin/main` (or --ref) to a temporary `srcly` folder (so the shots show the +// repository's own name and Git history), starts the API and the client dev server on +// free ports with a temporary cache, then writes: +// +// public/screenshots/*.jpg app screenshots (1440 × 900 CSS px at 1.5x) +// src/data/tree.json folder and file sizes and complexity, for the hero treemap +// src/data/catalog.json the metric catalog and 2×2 presets the reference tables use +// src/data/cli.json real output of a few headless commands +// src/data/meta.json the source revision and totals the page cites +// +// The data-flow and symbols shots use the checked-in engine/examples/symbol-graph fixture: +// a small app with a route, because a trace over the whole repository takes minutes. +import { execFileSync, spawn } from "node:child_process"; +import { mkdtemp, mkdir, realpath, rm, writeFile } from "node:fs/promises"; +import { createServer } from "node:net"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { chromium } from "@playwright/test"; + +const site = fileURLToPath(new URL("..", import.meta.url)); +const repo = join(site, ".."); +const shots = join(site, "public/screenshots"); +const data = join(site, "src/data"); +const args = process.argv.slice(2); +const refAt = args.indexOf("--ref"); +const ref = refAt >= 0 ? args.splice(refAt, 2)[1] : "origin/main"; +const only = args[0]?.split(","); + +// realpath: macOS reports /var/folders/… as /private/var/folders/… in the scan. +const root = await realpath(await mkdtemp(join(tmpdir(), "srcly-site-"))); +const clone = join(root, "srcly"); +const fixture = join(clone, "engine/examples/symbol-graph"); +const env = { ...process.env, SRCLY_CACHE_DIR: join(root, "cache"), SRCLY_ENGINE_DEV: "1" }; +execFileSync("git", ["clone", "-q", repo, clone]); +const commit = execFileSync("git", ["-C", repo, "rev-parse", ref], { encoding: "utf8" }).trim(); +execFileSync("git", ["-C", clone, "checkout", "-q", "--detach", commit]); +const sha = execFileSync("git", ["-C", clone, "rev-parse", "--short=8", "HEAD"], { encoding: "utf8" }).trim(); +const date = execFileSync("git", ["-C", clone, "log", "-1", "--format=%cs"], { encoding: "utf8" }).trim(); +console.log(`source ${sha} (${date}) in ${clone}`); + +const srcly = (...args) => execFileSync("uv", ["run", "--quiet", "--directory", join(repo, "server"), "python", "-m", "app.run", ...args], { + env, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 1 << 28, +}); + +const freePort = () => new Promise((done) => { + const server = createServer().listen(0, "127.0.0.1", () => { + const { port } = server.address(); + server.close(() => done(port)); + }); +}); +const api = await freePort(); +const client = await freePort(); +const children = [ + spawn("uv", ["run", "--quiet", "--directory", join(repo, "server"), "python", "-m", "uvicorn", "app.main:app", "--host", "127.0.0.1", "--port", String(api)], { env, stdio: "ignore" }), + spawn(join(repo, "client/node_modules/.bin/vite"), ["--host", "127.0.0.1", "--port", String(client), "--strictPort"], { + cwd: join(repo, "client"), env: { ...env, SRCLY_API_PORT: String(api) }, stdio: "ignore", + }), +]; +const stop = () => children.forEach((child) => child.kill()); +process.on("exit", stop); +for (const signal of ["SIGINT", "SIGTERM"]) process.on(signal, () => process.exit(130)); + +async function waitFor(url) { + for (let i = 0; i < 120; i++) { + try { if ((await fetch(url)).ok) return; } catch { /* not up yet */ } + await new Promise((done) => setTimeout(done, 500)); + } + throw new Error(`Timed out waiting for ${url}`); +} +await waitFor(`http://127.0.0.1:${api}/api/metrics/catalog`); +await waitFor(`http://127.0.0.1:${client}/`); + +// Data first: the scan warms the cache the app then loads. +await mkdir(data, { recursive: true }); +const full = JSON.parse(srcly("scan", clone, "--out", "-")); +const fileTypes = new Set(["file"]); +const slim = (node) => { + const out = { n: node.name, l: node.metrics?.loc ?? 0 }; + const ccn = node.metrics?.complexity; + if (ccn !== null && ccn !== undefined) out.c = Math.round(ccn); + if (node.type === "folder") out.k = (node.children ?? []).filter((child) => child.type === "folder" || fileTypes.has(child.type)).map(slim).filter((child) => child.l > 0); + return out; +}; +await writeFile(join(data, "tree.json"), JSON.stringify({ ...slim(full), n: "srcly" })); + +const catalog = await (await fetch(`http://127.0.0.1:${api}/api/metrics/catalog`)).json(); +await writeFile(join(data, "catalog.json"), JSON.stringify({ + groups: catalog.groups, + metrics: catalog.metrics.map(({ id, label, short_label, unit, group, direction, aggregation, languages, description, witness }) => + ({ id, label, short_label, unit, group, direction, aggregation, languages, description, witness })), + windows: catalog.activity_windows, + presets: catalog.quadrant_presets.map(({ id, label, description, x, y, cohorts, quadrants }) => + ({ id, label, description, x: x.label, y: y.label, cohorts, quadrants: quadrants.map(({ name, description: text }) => ({ name, text })) })), +}, null, 1)); + +const cli = { + hotspots: srcly("hotspots", clone, "--metric", "complexity", "--cohort", "function", "--limit", "6"), + explain: srcly("explain", clone, "--at", "client/src/viz/treemap"), +}; +await writeFile(join(data, "cli.json"), JSON.stringify(Object.fromEntries(Object.entries(cli).map(([key, text]) => + [key, text.replaceAll(root, "/tmp").trimEnd()])), null, 1)); + +const m = full.metrics; +await writeFile(join(data, "meta.json"), JSON.stringify({ + sha, date, loc: m.loc, files: m.file_count, functions: m.function_count, + topCcn: Math.round(m.complexity), topCcnName: m.complexity_witness?.name, + topCcnPath: m.complexity_witness?.path.split("::")[0].replace(`${clone}/`, ""), + findings: m.finding_count, +}, null, 1)); + +// Screenshots. +const app = (path, params) => `http://127.0.0.1:${client}/?${new URLSearchParams({ repo: path, ...params })}`; +const views = [ + { name: "treemap", url: app(clone, { view: "treemap" }) }, + { name: "hotspots", url: app(clone, { view: "treemap" }), steps: async (page) => page.getByRole("tab", { name: "Hot Spots" }).click() }, + { name: "quadrant", url: app(clone, { view: "scatter", preset: "activity", cohort: "file", quadrant: "high_both" }) }, + { + name: "code-inspector", url: app(clone, { view: "treemap", at: "client/src/viz/deps" }), + // The witness button shows on row hover; force skips the visibility wait. + steps: async (page) => page.getByRole("button", { name: /^Open buildViewModel/ }).first().click({ force: true }), + ready: '[role="dialog"]', delay: 3000, + }, + { name: "graph", url: app(clone, { view: "graph", at: "client/src/viz/treemap" }), delay: 2500 }, + { + // Compare checks out and scans both revisions, then shows the risk metrics summary. + name: "compare", url: app(clone, { view: "treemap", compare: "5a8a9c38~1..5a8a9c38" }), delay: 3000, timeout: 600_000, + steps: async (page) => page.getByText("Risk metrics", { exact: true }).first().waitFor(), + }, + { name: "symbols", url: app(fixture, { view: "graph", symbols: "src/routes/notes/[id].tsx#NotePage" }), delay: 4000 }, + { name: "data-flow", url: app(fixture, { view: "graph", anchor: "src/routes/notes/[id].tsx@NotePage:6", dir: "forward" }), ready: "text=Where the trace stops", delay: 2000 }, +]; + +const browser = await chromium.launch({ channel: "chrome", args: ["--use-mock-keychain", "--password-store=basic"] }); +try { + for (const view of views.filter((item) => !only || only.includes(item.name))) { + const page = await browser.newPage({ viewport: { width: 1440, height: 900 }, deviceScaleFactor: 1.5 }); + page.setDefaultTimeout(view.timeout ?? 180_000); + try { + await page.goto(view.url, { waitUntil: "domcontentloaded" }); + if (!view.url.includes("compare=")) await page.locator('[data-scan-state="ready"]').first().waitFor(); + await page.addStyleTag({ content: ".plc-toast { display: none !important; }" }); + if (view.steps) await view.steps(page); + if (view.ready) await page.locator(view.ready).first().waitFor(); + await page.waitForLoadState("networkidle"); + await page.waitForTimeout(view.delay ?? 800); + await page.mouse.move(0, 0); + await page.screenshot({ path: join(shots, `${view.name}.jpg`), type: "jpeg", quality: 82 }); + console.log(`${view.name}.jpg`); + } catch (error) { + process.exitCode = 1; + console.error(`${view.name}: ${error.message.split("\n")[0]}`); + } + await page.close(); + } +} finally { + await browser.close(); + stop(); + await rm(root, { recursive: true, force: true }); +} diff --git a/site/scripts/deploy.mjs b/site/scripts/deploy.mjs deleted file mode 100644 index 5213a9a2..00000000 --- a/site/scripts/deploy.mjs +++ /dev/null @@ -1,47 +0,0 @@ -import { cpSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs'; -import { tmpdir } from 'node:os'; -import { join, resolve } from 'node:path'; -import { spawnSync } from 'node:child_process'; - -const siteDir = resolve(import.meta.dirname, '..'); -const distDir = join(siteDir, 'dist'); -const repoDir = resolve(siteDir, '..'); -const tempDir = mkdtempSync(join(tmpdir(), 'srcly-pages-')); - -function git(args, cwd = tempDir) { - const result = spawnSync('git', args, { cwd, encoding: 'utf8' }); - if (result.status !== 0) { - process.stderr.write(result.stderr); - process.exit(result.status ?? 1); - } - return result.stdout.trim(); -} - -try { - if (!readdirSync(distDir).length) throw new Error(`Build output is empty: ${distDir}`); - const remote = git(['remote', 'get-url', 'origin'], repoDir); - const refs = git(['ls-remote', '--heads', remote, 'gh-pages']); - const hasBranch = refs.length > 0; - - if (hasBranch) { - git(['clone', '--quiet', '--single-branch', '--branch', 'gh-pages', remote, tempDir]); - } else { - git(['init', '--quiet', '--initial-branch=gh-pages']); - git(['remote', 'add', 'origin', remote]); - } - - for (const name of readdirSync(tempDir)) { - if (name !== '.git') rmSync(join(tempDir, name), { recursive: true, force: true }); - } - cpSync(distDir, tempDir, { recursive: true }); - writeFileSync(join(tempDir, '.nojekyll'), ''); - - git(['config', 'user.name', 'Byron Wall']); - git(['config', 'user.email', 'byron@byroni.us']); - git(['add', '--all']); - git(['commit', '--allow-empty', '-m', 'Deploy site']); - git(['push', 'origin', 'HEAD:gh-pages']); - process.stdout.write('Published site/dist to gh-pages.\n'); -} finally { - rmSync(tempDir, { recursive: true, force: true }); -} diff --git a/site/src/App.tsx b/site/src/App.tsx index 703f2e21..86baa36c 100644 --- a/site/src/App.tsx +++ b/site/src/App.tsx @@ -110,7 +110,7 @@ function DocsPage(props: { page: (typeof pages)[number]; base: string }) { {group => }}> - +
@@ -121,7 +121,7 @@ function DocsPage(props: { page: (typeof pages)[number]; base: string }) {

{props.page.title}

{props.page.description}

- Edit page + Edit page
{ diff --git a/site/src/Architecture.tsx b/site/src/Architecture.tsx new file mode 100644 index 00000000..0f793577 --- /dev/null +++ b/site/src/Architecture.tsx @@ -0,0 +1,34 @@ +/** Srcly's architecture, left to right: entry points, the scan, its cache, and what reads it. */ +export function Architecture() { + const box = (x: number, y: number, w: number, h: number, title: string, lines: string[], tone = '') => + + + {title} + {lines.map((line, i) => {line})} + ; + const arrow = (d: string) => ; + return + How Srcly fits together + The uvx srcly command starts a FastAPI server. A scan runs Lizard and tree-sitter analyzers in worker processes, builds one tree with rolled-up metrics, and saves it in the user cache. Checkers run beside the scan. The SolidJS app and the headless commands read the same scan. A Node data-flow engine starts only when the data-flow view needs it. + + + + + + {box(10, 30, 140, 74, 'uvx srcly', ['opens the app', 'in your browser'])} + {box(10, 150, 140, 92, 'srcly report …', ['explain, hotspots,', 'compare, fix,', 'check, scan'])} + {box(200, 10, 230, 250, 'FastAPI server', [], 'frame')} + {box(214, 44, 202, 92, 'Scan', ['walk files, skip ignored', 'Lizard + tree-sitter,', 'one worker per file'], 'hot')} + {box(214, 150, 202, 46, 'Tree + rollups', ['folders › files › scopes'])} + {box(214, 206, 202, 44, 'Checkers', ['tsc, eslint, ruff, own rules'])} + {box(480, 30, 150, 74, 'SolidJS app', ['treemap, graph,', '2×2, compare'])} + {box(480, 150, 150, 74, 'User cache', ['one scan per repo,', 'until a file changes'], 'cool')} + {box(200, 300, 230, 64, 'Data-flow engine', ['TypeScript on Node 18+,', 'started on first use'], 'na')} + {arrow('M150 67 H198')} + {arrow('M150 196 H198')} + {arrow('M315 136 V148')} + {arrow('M430 67 H478')} + {arrow('M416 173 H478')} + {arrow('M315 262 V298')} + ; +} diff --git a/site/src/Landing.tsx b/site/src/Landing.tsx index b1cc6d84..21342d47 100644 --- a/site/src/Landing.tsx +++ b/site/src/Landing.tsx @@ -1,92 +1,257 @@ -import { ArrowRight, ArrowUpRight } from 'lucide-solid'; -import { createSignal, onCleanup } from 'solid-js'; +import { ArrowRight, ExternalLink } from 'lucide-solid'; +import { For, createSignal, onCleanup, type JSX } from 'solid-js'; +import { marked } from 'marked'; import { Footer, Header } from './SiteChrome'; import { ScreenshotViewer } from './ScreenshotViewer'; +import { Scope, Source } from './Scope'; +import { SourceTreemap } from './treemap'; +import { Architecture } from './Architecture'; +import { Reference } from './Reference'; +import meta from './data/meta.json'; +import cli from './data/cli.json'; +import catalog from './data/catalog.json'; -const views = [ - { - image: 'treemap.jpg', - title: 'See the shape of a repository', - detail: 'The treemap sizes each region by code volume and colors it by the selected signal. Move from a folder to the files that need attention.', - guide: 'explore', - guideTitle: 'Explore a codebase', - }, - { - image: 'code-inspector.jpg', - title: 'Inspect code with its context', - detail: 'Open a file or symbol to read source alongside its measurements and findings. Follow the evidence into the code you maintain.', - guide: 'findings', - guideTitle: 'Read findings', - }, - { - image: 'data-flow.jpg', - title: 'Trace values across functions', - detail: 'Follow supported TypeScript, JavaScript, and Python values through calls. Each trace names where it stops or why analysis is unavailable.', - guide: 'data-flow', - guideTitle: 'Understand data flow', - }, -]; +const num = (value: number) => value.toLocaleString('en-US'); +const sections = ['start', 'read', 'views', 'workflows', 'cli', 'reference', 'built']; export function Landing(props: { base: string }) { + const doc = (slug: string) => `${props.base}docs/${slug}/`; + const shot = (name: string) => `${props.base}screenshots/${name}.jpg`; return
-
+
+
-
-
-

See where the code gets hard.

-

Explore a real codebase through its structure, measurements, and findings. Start with the whole tree, then open the code behind a signal.

-
- - Use Srcly +
+
+ srcly/ + {num(meta.loc)} LOC · {num(meta.files)} files · {num(meta.functions)} functions +
+
+ + +
+

See where the code gets hard.

+

Srcly maps a repository into folders, files, functions and nested scopes, then colors the map by the metric you pick. Start with the whole tree, then open the code behind a signal.

+ +

Runs on your machine. No account and no upload.

-

Runs on your machine. No account or upload.

-
- - Srcly repository treemap with file regions sized by lines of code and colored by complexity. - -
Repository overviewArea shows code volume · color shows the selected metric
-
+
+

This map is Srcly's own source at {meta.sha}, drawn from its scan. Area is lines of code. Color is the most complex function in each file.

+ +
-
-
-

A codebase, from overview to evidence.

Three views connect the shape of the project to the source and analysis behind it.

- Product tour + Srcly is a Python package that you run with uv. Nothing is installed globally. It needs Python 3.13 or newer, and uv gets that for you if it is missing.}> +
    +
  1. +

    Run it in a repository

    +
    {'uvx srcly\nuvx srcly .\nuvx srcly ~/code/app'}
    +

    With no path, Srcly walks up to the enclosing Git root. Pass . to scan only the current folder, or give any path.

    +
  2. +
  3. +

    Use the browser tab it opens

    +

    Srcly starts a local server on 127.0.0.1 with a free port and opens your browser. --port and --host change that. Keep the terminal open. Ctrl+C stops it.

    +

    The path bar at the top picks another folder. Recent folders stay in the menu.

    +
  4. +
  5. +

    Wait for one scan

    +

    The first scan shows live progress per file. Srcly saves the result in your user cache folder, never in the repository. When you open an unchanged repository again, it loads at once. Any file change starts a fresh scan.

    +

    Srcly's own repository, {num(meta.files)} files, scans in about ten seconds on a laptop.

    +
  6. +
+

Optional: data flow needs Node.js 18 or newer on PATH. Lint and type checks use the project's own tsc and eslint when node_modules has them, and the bundled ruff for Python. Full setup guide

+
+ + +
+
+ +
client/src from the same scan. Each tile is a file; its color is its most complex function.
+
+
+
Area
+
Lines of code: nonblank lines that are not only a comment. Lines inside a function that are not in a nested scope become a (body) tile, so a line is never counted twice.
+
Color
+
The metric you pick in Color. Every metric uses one ramp, from blue (fine) through amber to red (look here). Each metric sets its own stops. For complexity they are 0, 10 and 50.
+
Hatching
+
N/A. The metric does not apply to that file, or its tool did not run. Srcly never shows N/A as 0, and the tooltip gives the reason.
+
Folders
+
Each metric has one rollup rule. LOC is a sum. Complexity is the maximum and names the function that sets it. A sum such as LOC colors a folder by its average per file.
+
Moving
+
Click a folder to zoom in, and use the breadcrumb or the browser's Back button to go up. Click a file or function to read its source. The All files menu filters by file type, and the explorer can hide or isolate a path.
+
-
+

The symbols and data-flow shots use engine/examples/symbol-graph, a small app in the repository. A trace over the whole Srcly repository takes minutes.

+ -
-

See the product. Then use it on your code.

Browse how Srcly works, or install it and open a local project. The same guides explain metrics, reports, the command line, and configuration.

-
+ -
-

Measurements keep their limits in view.

-

Supported signals vary by language and tool setup. A metric that does not apply is shown as N/A, never zero. Data-flow results name their outcome and stop reason.

- How to read the metrics -
+ + + + + {([cmd, text]) => } + +
CommandWhat it does
{cmd}{text}
+
+
+
uvx srcly hotspots . --metric complexity --cohort function --limit 6
+
{cli.hotspots}
+
+
+
uvx srcly explain . --at client/src/viz/treemap
+
/g, '<$1h4>')}/> +
+
+

Both outputs are real, from Srcly scanning itself at {meta.sha}. Every command and flag · What each report file holds

+
+ + + + + + +
+
+

I started Srcly in 2025 because I wanted to look at a codebase as a whole: where the code is, how complex it is, how often it changes, and how the pieces connect. A file list can't show that. A map can.

+

It is a FastAPI server and a SolidJS client. The scan runs Lizard for broad language coverage, and tree-sitter analyzers where I want more than a function count. Everything lands in one tree of folders, files, functions and scopes, and the metrics roll up that tree so any level can be sorted, colored and ranked. The data-flow engine is TypeScript, so it runs as a Node process that starts only when you open that view.

+

A few things I learned on the way:

+
    +
  • A measured 0 and "not measured" are different answers. If a missing value shows as 0, code where nothing ran looks clean. So N/A is its own state everywhere: hatched on the map, named in reports, and counted as lost coverage in compare.
  • +
  • Show the lines behind a number. The overlay that marks them exposed a nesting bug that had inflated hotspot scores for long else if chains.
  • +
  • The dependency graph took six rounds of before-and-after screenshots to read well. I tried ELK for layout and dropped it, because I couldn't steer its packing and edge bundling. Srcly now uses its own grid and router, and boxes never move after layout.
  • +
+

The longer story is on the Srcly project page , with posts on the dependency graph, the metric overlay and compare.

+
+
+ +
One scan, cached per repository, feeds the browser app and the headless commands. The Node engine starts only for data flow.
+
+
+
; } +const commands: [string, string][] = [ + ['srcly [path]', 'Scan and open the app. --host and --port pick the bind address.'], + ['srcly report', 'Write report.md and JSON artifacts: findings, folders, hotspots, a tree summary, the metric schema and an agent guide. --quadrant adds a 2×2.'], + ['srcly explain --at', 'Drill into the repo, a folder, a file, or file::symbol. Any printed "start at" value works.'], + ['srcly hotspots', 'Rank files or functions by one metric. --format json for scripts.'], + ['srcly compare [base] [head]', 'Metric and dependency changes between two refs. Defaults to the merge base against the working tree; pr: names a PR.'], + ['srcly fix', 'Print a diff of safe fixes for srcly\'s own findings; --write applies them.'], + ['srcly check --ratchet', 'Exit 1 when a file over the size budget grows.'], + ['srcly scan', 'Write the raw analysis tree as JSON.'], +]; + +function View(props: { shot: string; title: string; alt: string; source: string; guide: string; children: JSX.Element }) { + return
+ + {props.alt} + +
+

{props.title}

+ {props.children} + +
+
; +} + +function Workflow(props: { title: string; children: JSX.Element }) { + return

{props.title}

    {props.children}
; +} + +function Legend() { + return
+