diff --git a/site/README.md b/site/README.md index fca1ccd1..39439391 100644 --- a/site/README.md +++ b/site/README.md @@ -19,13 +19,16 @@ The browser adds section-linked guide search, copy buttons, and a full-size scre - 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`. +- The longer guides are Markdown in `src/docs/pages/`. Add a new page to the navigation in `src/App.tsx`. Also add it to the `order` list in `scripts/prerender.mjs`, which writes the agent files. +- The build writes files for agents: `llms.txt` (an index), `llms-full.txt` (every guide plus the metric reference), `metrics.md`, and an `index.md` beside each guide. +- The landing header search (`src/SiteSearch.tsx`) indexes the guide sections, every docs heading, every metric and every command. `/` focuses it. +- The hero treemap recolors by complexity, commits or findings and reads out the tile under the pointer. `src/data/tree.json` holds those three values per file. - Keep command examples in sync with `server/app/run.py`. ## Screenshots and data -`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: +`node scripts/capture.mjs [name,name… | data] [--ref ]` captures everything from a real Srcly run on Srcly's own source (`data` skips the screenshots). +It clones this checkout at `origin/main` (or `--ref`) 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. diff --git a/site/scripts/capture.mjs b/site/scripts/capture.mjs index 238b12fa..5b209936 100644 --- a/site/scripts/capture.mjs +++ b/site/scripts/capture.mjs @@ -1,6 +1,6 @@ // 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 ] +// cd site && node scripts/capture.mjs [name,name… | data] [--ref ] (data: no screenshots) // // 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 @@ -16,7 +16,7 @@ // 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 { mkdtemp, mkdir, readFile, realpath, rm, writeFile } from "node:fs/promises"; import { createServer } from "node:net"; import { tmpdir } from "node:os"; import { join } from "node:path"; @@ -82,8 +82,11 @@ 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); + // Short keys keep the file small: c = max complexity, m = commits (90 days), f = findings. Absent is N/A. + for (const [key, id] of [["c", "complexity"], ["m", "commit_count"], ["f", "finding_count"]]) { + const value = node.metrics?.[id]; + if (value !== null && value !== undefined) out[key] = Math.round(value); + } 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; }; @@ -92,8 +95,8 @@ await writeFile(join(data, "tree.json"), JSON.stringify({ ...slim(full), n: "src 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 })), + metrics: catalog.metrics.map(({ id, label, short_label, unit, group, direction, aggregation, languages, description, witness, color_domain, color_per_file }) => + ({ id, label, short_label, unit, group, direction, aggregation, languages, description, witness, color_domain, color_per_file })), 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 })) })), @@ -108,7 +111,8 @@ await writeFile(join(data, "cli.json"), JSON.stringify(Object.fromEntries(Object 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, + sha, date, version: (await readFile(join(clone, "server/pyproject.toml"), "utf8")).match(/^version = "(.+)"/m)?.[1], + 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, diff --git a/site/scripts/prerender.mjs b/site/scripts/prerender.mjs index 5a9077a6..036765ca 100644 --- a/site/scripts/prerender.mjs +++ b/site/scripts/prerender.mjs @@ -31,6 +31,7 @@ function html(page) { const metadata = [ ``, ``, + page.route.startsWith("docs/") ? `` : ``, ``, ``, ``, @@ -69,4 +70,68 @@ await writeFile("dist/404.html", html({ route: "404/", title: "Page not found · await writeFile("dist/.nojekyll", ""); await writeFile("dist/robots.txt", `User-agent: *\nAllow: /\nSitemap: ${origin}${base}sitemap.xml\n`); await writeFile("dist/sitemap.xml", `\n${pages.map((page) => `${origin}${base}${page.route}`).join("")}\n`); -console.log(`Prerendered ${pages.length} pages, docs entry point, and 404 page.`); +// For agents: each guide as Markdown beside its page, llms.txt as the index, llms-full.txt as everything. +const absolute = (markdown) => markdown + .replace(/
.*?([^/gs, (_m, src, alt) => `![${alt}](${origin}${src})`) + .replace(/\]\(\.\.\/([a-z0-9-]+)\/?(#[^)]+)?\)/gi, (_m, slug, hash = "") => `](${origin}${base}docs/${slug}/${hash})`) + .replace(/\]\(\/srcly\//g, `](${origin}${base}`); +const guides = []; +const order = ["overview", "tour", "design", "get-started", "explore", "metrics", "findings", "data-flow", "reports", "cli", "configuration"]; +const slugs = (await readdir("src/docs/pages")).filter((name) => name.endsWith(".md")).map((name) => name.slice(0, -3)); +assert.deepEqual([...slugs].sort(), [...order].sort(), "Add new guides to the llms.txt order"); +for (const slug of order) { + const filename = `${slug}.md`; + const markdown = absolute(await readFile(`src/docs/pages/${filename}`, "utf8")); + const page = pages.find((item) => item.route === (slug === "overview" ? "docs/" : `docs/${slug}/`)); + await writeFile(`dist/docs/${slug}/index.md`, markdown); + if (slug === "overview") await writeFile("dist/docs/index.md", markdown); + guides.push({ slug, title: markdown.match(/^# (.+)$/m)[1], description: page.description.split(/(?<=\.)\s/)[0], markdown }); +} +const catalog = JSON.parse(await readFile("src/data/catalog.json", "utf8")); +const meta = JSON.parse(await readFile("src/data/meta.json", "utf8")); +const cell = (text) => String(text ?? "").replace(/\|/g, "\\|").replace(/\n/g, " "); +const metrics = [ + "# Srcly metrics", + "", + `Every metric Srcly measures, from its metric catalog (version ${meta.version}). Rollup is how a folder or file combines its children; "max, named" also names the function that sets it. N/A means the metric does not apply or its tool did not run. It is never 0.`, + ...catalog.groups.flatMap((group) => [ + "", `## ${group.id}`, "", group.description, "", + "| Metric | ID | Rollup | Languages | What it measures |", "| --- | --- | --- | --- | --- |", + ...catalog.metrics.filter((metric) => metric.group === group.id).map((metric) => + `| ${cell(metric.label)} | \`${metric.id}\` | ${metric.aggregation === "max" && metric.witness ? "max, named" : metric.aggregation} | ${cell((metric.languages ?? ["any file"]).join(", "))} | ${cell(metric.description)} |`), + ]), +].join("\n") + "\n"; +await writeFile("dist/metrics.md", metrics); +const site = `${origin}${base}`; +await writeFile("dist/llms.txt", `# Srcly + +> Srcly is a local codebase map for developers and coding agents. It scans a repository into folders, files, functions and nested scopes, measures complexity, size, comment noise, React and Solid components, Git activity and lint findings, and shows them as a treemap, graphs and a 2x2 in the browser. Headless commands write the same analysis as Markdown and JSON. + +Run it with \`uvx srcly\` (needs uv; Python 3.13+). Version ${meta.version}. Full analysis for TypeScript, JavaScript and Python; size and complexity for the other languages Lizard reads. A metric that does not apply is N/A, never 0. + +For an agent, the usual loop is: + +1. \`uvx srcly report . --out .srcly\`, then read \`.srcly/report.md\`. +2. \`uvx srcly explain . --at \` to drill in. Each answer ends with a \`Next:\` command. +3. \`uvx srcly compare --json\` to see what a change did, and \`uvx srcly check . --ratchet\` to stop big files from growing. + +## Guides + +${guides.map((guide) => `- [${guide.title}](${site}docs/${guide.slug}/index.md): ${guide.description}`).join("\n")} + +## Reference + +- [Metrics](${site}metrics.md): every metric with its ID, rollup, languages and definition. +- [Agent skill](https://raw.githubusercontent.com/byronwall/srcly/main/skills/srcly-code-quality/SKILL.md): the report and explain workflow as a skill file. +- [Source](https://github.com/byronwall/srcly): the repository. + +## Optional + +- [Everything in one file](${site}llms-full.txt): every guide and the metric reference. +`); +await writeFile("dist/llms-full.txt", [ + `# Srcly documentation\n\nAll guides and the metric reference, from ${site}. Version ${meta.version}.`, + ...guides.map((guide) => `\n---\n\nSource: ${site}docs/${guide.slug}/\n\n${guide.markdown.trim()}`), + `\n---\n\nSource: ${site}metrics.md\n\n${metrics.trim()}`, +].join("\n") + "\n"); +console.log(`Prerendered ${pages.length} pages, docs entry point, and 404 page. Wrote llms.txt, llms-full.txt, metrics.md and ${guides.length} Markdown guides.`); diff --git a/site/src/App.tsx b/site/src/App.tsx index 86baa36c..5e7ca95d 100644 --- a/site/src/App.tsx +++ b/site/src/App.tsx @@ -121,7 +121,10 @@ function DocsPage(props: { page: (typeof pages)[number]; base: string }) {

{props.page.title}

{props.page.description}

- Edit page +
+ Markdown + Edit page +
{ diff --git a/site/src/Landing.tsx b/site/src/Landing.tsx index 21342d47..64cb2cff 100644 --- a/site/src/Landing.tsx +++ b/site/src/Landing.tsx @@ -1,22 +1,30 @@ import { ArrowRight, ExternalLink } from 'lucide-solid'; -import { For, createSignal, onCleanup, type JSX } from 'solid-js'; +import { For, Show, 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 { MAP_METRICS, SourceTreemap, type MapMetric, type Tile } from './treemap'; import { Architecture } from './Architecture'; import { Reference } from './Reference'; +import { COMMANDS } from './commands'; import meta from './data/meta.json'; import cli from './data/cli.json'; import catalog from './data/catalog.json'; const num = (value: number) => value.toLocaleString('en-US'); -const sections = ['start', 'read', 'views', 'workflows', 'cli', 'reference', 'built']; +const sections = ['start', 'read', 'views', 'workflows', 'cli', 'agents', 'reference', 'built']; +const ABOUT: Record = { + c: 'the most complex function in each file', + m: 'commits in the last 90 days', + f: 'lint and type-check findings', +}; export function Landing(props: { base: string }) { const doc = (slug: string) => `${props.base}docs/${slug}/`; const shot = (name: string) => `${props.base}screenshots/${name}.jpg`; + const [metric, setMetric] = createSignal(MAP_METRICS[0]); + const [hovered, setHovered] = createSignal(); return
@@ -31,8 +39,8 @@ export function Landing(props: { base: string }) { {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.

@@ -41,11 +49,19 @@ export function Landing(props: { base: string }) { Get started

Runs on your machine. No account and no upload.

+

Version {meta.version}. Full analysis for TypeScript, JavaScript and Python; size and complexity for Go, Java, C, C++ and every other language Lizard reads.

-

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.

- +

+ Srcly's own source at {meta.sha}. Area is lines of code; color is {ABOUT[metric().key]}. Point at a tile to read it.}> + {tile => <>{tile().path}{tile().folder ? '/' : ''}{num(tile().node.l)} LOC · {MAP_METRICS.map(m => tile().node[m.key] === undefined ? `${m.unit} N/A` : `${num(tile().node[m.key]!)} ${m.unit}`).join(' · ')}} + +

+
+ {m => } +
+
@@ -148,11 +164,6 @@ export function Landing(props: { base: string }) {
  • Read the risk metrics that got worse, then the changed files. The Dependencies tab shows the import graph before and after.
  • A file measured on one side only counts as a coverage change, not as an improvement.
  • - -
  • Run uvx srcly report . --out .srcly.
  • -
  • Point the agent at .srcly/report.md and agent-skill.md.
  • -
  • It drills in with uvx srcly explain . --at <path>, which reuses the cached scan and answers in about a second.
  • -
  • report writes size_budget.json: each code file over 5,000 tokens (bytes ÷ 4).
  • Add uvx srcly check . --ratchet to a pre-commit hook or CI.
  • @@ -171,7 +182,7 @@ export function Landing(props: { base: string }) { - {([cmd, text]) => } + {([cmd, text]) => }
    CommandWhat it does
    {cmd}{text}
    {cmd}{text}
    @@ -187,6 +198,38 @@ export function Landing(props: { base: string }) {

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

    + +
    +
      +
    1. +

      Write the report

      +
      uvx srcly report . --out .srcly
      +

      Writes report.md, findings.json, hotspots.json, tree.summary.json, metrics.schema.json and agent-skill.md. The terminal prints the top findings and the next command to run.

      +
    2. +
    3. +

      Drill in, one scope at a time

      +
      {'uvx srcly explain . --at server/app\nuvx srcly explain . --at "server/app/run.py::_main"'}
      +

      Each answer reuses the cached scan, takes about a second, and ends with a Next: command. Any printed "start at" value works as --at.

      +
    4. +
    5. +

      Check a change

      +
      {'uvx srcly compare --json\nuvx srcly check . --ratchet'}
      +

      compare diffs the merge base against the working tree. A metric that is unavailable stays null, never 0.

      +
    6. +
    + +
    +
    + @@ -216,16 +259,6 @@ export function Landing(props: { base: string }) {
    ; } -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
    @@ -244,11 +277,11 @@ function Workflow(props: { title: string; children: JSX.Element }) { return

    {props.title}

      {props.children}
    ; } -function Legend() { +function Legend(props: { metric: MapMetric }) { return