codetrail-cli 1.4.1__py3-none-any.whl

codetrail/web/templates/documentation.html

@@ -0,0 +1,247 @@
+{% extends "base.html" %}
+{% from "layout/icons.html" import icon %}
+{% block title %}{{ _("Documentation") }}{% endblock %}
+{% block content %}
+{# A list of `listed` items and its folded rest; with a filter, each item carries its kind and the rest's summary
+   is written once per kind, so the chips can show the right count without the script translating anything. #}
+{% macro listing(items, filter=none) -%}
+<ul class="list" lang="en" dir="ltr">{% for item in items[:listed] %}<li{% if filter %} data-kind="{{ filter.kinds[loop.index0] }}"{% endif %}>{{ caller(item) }}</li>{% endfor %}</ul>
+{% if items|length > listed %}
+<details class="more">
+  <summary>{% if filter %}{% for kind, count in filter.folded.items() %}<span data-more="{{ kind }}" data-count="{{ count }}"{% if kind != "all" %} hidden{% endif %}>{% trans count=count %}{{ count }} more{% endtrans %}</span>{% endfor %}{% else %}{% trans count=items|length - listed %}{{ count }} more{% endtrans %}{% endif %}</summary>
+  <ul class="list" lang="en" dir="ltr">{% for item in items[listed:] %}<li{% if filter %} data-kind="{{ filter.kinds[listed + loop.index0] }}"{% endif %}>{{ caller(item) }}</li>{% endfor %}</ul>
+</details>
+{% endif %}
+{%- endmacro %}
+{# Chips only when the list holds two kinds or more: with one, a chip would show what All shows. #}
+{% macro chips(filter, names) -%}
+{% if filter.totals|length > 2 %}
+<div class="segmented filter-chips" role="group" aria-label="{{ _('Show') }}" data-filter hidden>
+  <button type="button" data-show="all" aria-pressed="true">{{ _("All") }} · {{ filter.totals["all"]|number }}</button>
+  {% for kind, label in names %}{% if filter.totals.get(kind) %}<button type="button" data-show="{{ kind }}" aria-pressed="false">{{ label }} · {{ filter.totals[kind]|number }}</button>{% endif %}{% endfor %}
+</div>
+<p class="visually-hidden" data-filter-status aria-live="polite"></p>
+{% endif %}
+{%- endmacro %}
+{# A stacked bar with its legend; parts are (tone, count, name), and the bar's text alternative names each count. #}
+{% macro stack(parts) -%}
+<div class="stack-bar" dir="ltr" role="img" aria-label="{% for tone, count, name in parts %}{{ name }}: {{ count }}{% if not loop.last %}, {% endif %}{% endfor %}"><svg viewBox="0 0 1000 20" preserveAspectRatio="none" aria-hidden="true">{% for tone, x, width in segments(parts) %}<rect class="{{ tone }}" x="{{ x }}" y="0" height="20" width="{{ [width - 2, 0]|max|round(1) }}"/>{% endfor %}</svg></div>
+<ul class="stack-legend">{% for tone, count, name in parts %}<li><span class="swatch {{ tone }}" aria-hidden="true"></span>{{ name }}<span class="faint">{{ count|number }}</span></li>{% endfor %}</ul>
+{%- endmacro %}
+{# A tile's small bar: the tile already says its numbers in words. #}
+{% macro mini(parts) -%}
+<div class="share-bar" dir="ltr" aria-hidden="true"><svg viewBox="0 0 1000 10" preserveAspectRatio="none">{% for tone, x, width in segments(parts) %}<rect class="{{ tone }}" x="{{ x }}" y="0" height="10" width="{{ width }}"/>{% endfor %}</svg></div>
+{%- endmacro %}
+{% macro hbar(label, count, widest, value, tone="series-fill-1") -%}
+<li><span class="hbar-label">{{ label }}</span><svg class="hbar-track" viewBox="0 0 100 12" preserveAspectRatio="none" aria-hidden="true"><rect class="{{ tone }}" x="0" y="0" height="12" width="{{ (count / widest * 100)|round(1) if widest else 0 }}" rx="2"/></svg><span class="hbar-value">{{ value }}</span></li>
+{%- endmacro %}
+{% macro page_bar(row, widest) -%}
+{% set documented = row.documented / widest * 100 %}
+<li><a class="hbar-label" href="/pages/{{ row.page.id }}" lang="en" dir="ltr">{{ row.page.title }}</a><svg class="hbar-track" viewBox="0 0 100 12" preserveAspectRatio="none" role="img" aria-label="{% trans documented=row.documented, inferred=row.inferred %}{{ documented }} documented, {{ inferred }} inferred{% endtrans %}"><rect class="tone-documented" x="0" y="0" height="12" width="{{ documented|round(1) }}"/><rect class="tone-inferred" x="{{ documented|round(1) }}" y="0" height="12" width="{{ (row.inferred / widest * 100)|round(1) }}"/></svg><span class="hbar-value">{{ row.documented }} / {{ row.inferred }}</span></li>
+{%- endmacro %}
+{% macro fact_link(entity) -%}
+<a class="grow" href="/facts/{{ entity.id|urlencode|replace("/", "%2F") }}">{{ entity.id }}</a>
+{%- endmacro %}
+{% macro decision_link(decision) -%}
+<a class="grow" href="/facts/{{ decision.id|urlencode|replace("/", "%2F") }}">{{ decision.attributes.get("number", "") }} · {{ decision.attributes.get("title", "") }}</a>{% if decision.attributes.get("date") %}<span class="faint">{{ decision.attributes.date }}</span>{% endif %}
+{%- endmacro %}
+{% macro share(value) -%}
+{% if value.denominator %}{% trans numerator=value.numerator, denominator=value.denominator %}{{ numerator }} of {{ denominator }}{% endtrans %}{% else %}{{ _("nothing to measure yet") }}{% endif %}
+{%- endmacro %}
+{% macro about(text) -%}
+<details class="doc-about"><summary>{{ _("What this counts") }}</summary><p class="muted">{{ text }}</p></details>
+{%- endmacro %}
+{% macro tile_card(tile, label, title_id, parts=none) %}
+<section class="stat metric" aria-labelledby="{{ title_id }}">
+  <span class="card-label" id="{{ title_id }}">{{ label }}</span>
+  {% if tile.value is none %}
+    <span class="stat-value">—</span><span class="stat-note">{{ _("Not available just now.") }}</span>
+  {% elif tile.metric == "adr_attention" %}
+    <span class="stat-value{% if tile.value.numerator %} behind{% endif %}">{{ tile.value.numerator }}</span>
+    <span class="stat-note">{{ _("proposed too long, or retired and still cited") }}</span>
+  {% elif tile.metric == "documented_share" and not tile.value.denominator %}
+    <span class="stat-value">—</span><span class="stat-note">{{ _("No pages yet: the guide's rationale is measured once your assistant writes it.") }}</span>
+    <button type="button" class="button small" data-update-button>{{ _("Update the guide") }}</button>
+  {% else %}
+    <span class="stat-value">{% if tile.percent is not none %}{{ tile.percent }}%{% else %}—{% endif %}</span>
+    <span class="stat-note">{{ share(tile.value) }}</span>
+    {% if parts %}{{ mini(parts) }}{% endif %}
+  {% endif %}
+  {% if tile.value is not none and (tile.value.denominator or tile.metric == "adr_attention") %}
+  <span class="stat-note">{% if tile.change is none %}{{ _("No earlier update to compare with.") }}{% elif tile.metric == "adr_attention" %}{% trans change="%+d"|format(tile.change) %}{{ change }} since the last update{% endtrans %}{% else %}{% trans change="%+d"|format(tile.change) %}{{ change }} points since the last update{% endtrans %}{% endif %}</span>
+  {% endif %}
+  {% if tile.points %}
+  {% set count = tile.trend_text.split(", ")|length %}
+  <svg class="trend" viewBox="0 0 120 32" role="img" aria-label="{% trans count=count, values=tile.trend_text %}Trend over {{ count }} update: {{ values }}{% pluralize %}Trend over {{ count }} updates: {{ values }}{% endtrans %}"><polyline points="{{ tile.points }}"/></svg>
+  {% endif %}
+</section>
+{% endmacro %}
+<div class="wide">
+<header class="page-head">
+  <h1>{{ _("Documentation") }}</h1>
+  <p class="muted">{{ _("How well the repository explains itself: its guide's rationale, its commits, its decisions and its documents. Measured from the code and the guide, without calling your assistant.") }}</p>
+</header>
+{% if report is none %}
+<section class="empty">
+  {% if unavailable %}
+  <h2>{{ _("The metrics aren't available just now") }}</h2>
+  <p>{{ _("Codetrail couldn't read the target's data; the log says why.") }}</p>
+  {% else %}
+  <h2>{{ _("No facts yet") }}</h2>
+  <p>{{ _("Update the guide once: reading the code is free, and the metrics come from it.") }}</p>
+  <button type="button" class="button primary" data-update-button>{{ _("Update the guide") }}</button>
+  {% endif %}
+</section>
+{% else %}
+{% set rationale, commits, decisions = report.rationale, report.commits, report.decisions %}
+{% set mentions, explained, has_pages = report.mentions, report.explained, report.rationale.pages %}
+<div class="doc-layout">
+<aside class="doc-overview" aria-label="{{ _('Overview') }}" tabindex="0">{# focusable: it may scroll on its own #}
+  {{ tile_card(tiles["documented_share"], _("Documented rationale"), "tile-documented",
+               [("tone-documented", rationale.documented, ""), ("tone-inferred", rationale.inferred, "")]) }}
+  {{ tile_card(tiles["commit_why_share"], _("Commits that explain why"), "tile-commits",
+               [("series-fill-1", commits.explains_why, ""), ("", commits.measured - commits.explains_why, "")] if commits else none) }}
+  {{ tile_card(tiles["adr_attention"], _("ADRs needing attention"), "tile-adrs") }}
+  {{ tile_card(tiles["mentioned_share"], _("Mentioned in a document"), "tile-mentioned",
+               [("series-fill-1", mentions.mentioned|length, ""), ("", mentions.unmentioned|length, "")]) }}
+</aside>
+<div class="doc-sections">
+
+<section id="rationale" aria-labelledby="rationale-title">
+<details class="doc-fold"{% if open_section == "rationale" %} open{% endif %}>
+  <summary><h2 id="rationale-title">{{ icon("chevron") }}{{ _("Documented rationale") }}</h2><span class="doc-todo">{% if not has_pages %}{{ _("No pages yet") }}{% elif rationale.inferred %}{% trans count=rationale.inferred %}{{ count }} inferred, worth documenting{% pluralize %}{{ count }} inferred, worth documenting{% endtrans %}{% else %}{{ _("Nothing inferred") }}{% endif %}</span></summary>
+  <div class="doc-body">
+  {{ about(_("Rationale blocks in the guide's area and concept pages: documented ones quote a source Codetrail checked, inferred ones are the assistant's reading. It counts only what the guide wrote about.")) }}
+  {% if not has_pages %}
+  <p class="muted">{{ _("No pages yet: the guide's rationale is measured once your assistant writes it.") }}</p>
+  {% else %}
+  {{ stack([("heat-4", rationale.by_source.adr, _("ADRs")), ("heat-3", rationale.by_source.docs, _("Documents")),
+            ("heat-2", rationale.by_source.code, _("Code comments")), ("heat-1", rationale.by_source.commit, _("Commit messages")),
+            ("tone-inferred", rationale.inferred, _("Inferred"))]) }}
+  <h3>{{ _("By page, most inferred first") }}</h3>
+  {% set ns = namespace(widest=1) %}{% for row in rationale.pages %}{% set ns.widest = [ns.widest, row.documented + row.inferred]|max %}{% endfor %}
+  <ul class="hbars page-bars" dir="ltr">{% for row in rationale.pages[:listed] %}{{ page_bar(row, ns.widest) }}{% endfor %}</ul>
+  {% if rationale.pages|length > listed %}
+  <details class="more"><summary>{% trans count=rationale.pages|length - listed %}{{ count }} more{% endtrans %}</summary><ul class="hbars page-bars" dir="ltr">{% for row in rationale.pages[listed:] %}{{ page_bar(row, ns.widest) }}{% endfor %}</ul></details>
+  {% endif %}
+  {% if rationale.inferred_blocks %}
+  <h3>{{ _("Inferred: worth documenting") }}</h3>
+  {% call(block) listing(rationale.inferred_blocks) %}<a class="grow" href="/pages/{{ block.page.id }}">{{ block.first_line }}</a><span class="faint">{{ block.page.title }}</span>{% endcall %}
+  {% endif %}
+  {% endif %}
+  </div>
+</details>
+</section>
+
+<section id="commits" aria-labelledby="commits-title">
+<details class="doc-fold"{% if open_section == "commits" %} open{% endif %}>
+  <summary><h2 id="commits-title">{{ icon("chevron") }}{{ _("Commits that explain why") }}</h2><span class="doc-todo">{% if commits is none %}{{ _("Not available just now.") }}{% else %}{% trans count=commits.without_why|length, measured=commits.measured %}{{ count }} without a why, of the latest {{ measured }}{% pluralize %}{{ count }} without a why, of the latest {{ measured }}{% endtrans %}{% endif %}</span></summary>
+  <div class="doc-body">
+  {% if commits is none %}
+  <p class="muted">{{ _("The commit history couldn't be read just now; the log says why.") }}</p>
+  {% else %}
+  {{ about(_("The latest commits on the branch, merges left out. A commit explains why when its body matches the target's commit_why_pattern.")) }}
+  {{ stack([("tone-documented", commits.explains_why, _("Explain why")), ("tone-other", commits.body_only, _("Body without a why")),
+            ("tone-quiet", commits.subject_only, _("Subject only"))]) }}
+  {% if commits.withheld %}<p class="muted">{% trans count=commits.withheld %}{{ count }} message withheld: gitleaks flagged it{% pluralize %}{{ count }} messages withheld: gitleaks flagged them{% endtrans %}</p>{% endif %}
+  {% if commits.without_why %}
+  <h3>{{ _("Without a why") }}</h3>
+  <div data-filterable>
+  {{ chips(commit_filter, [("body-only", _("Body without a why")), ("subject-only", _("Subject only"))]) }}
+  {% call(commit) listing(commits.without_why, commit_filter) %}<code>{{ commit.sha[:7] }}</code><span class="grow">{{ commit.subject }}</span><span class="faint">{% if commit.body %}{{ _("body without a why") }}{% else %}{{ _("subject only") }}{% endif %}</span>{% endcall %}
+  </div>
+  {% endif %}
+  {% endif %}
+  </div>
+</details>
+</section>
+
+<section id="decisions" aria-labelledby="decisions-title">
+{% set to_check = decisions.undated|length + (decisions.uncited|length if has_pages else 0) %}
+<details class="doc-fold"{% if open_section == "decisions" %} open{% endif %}>
+  <summary><h2 id="decisions-title">{{ icon("chevron") }}{{ _("Architecture decisions") }}</h2><span class="doc-todo">{% if not decisions.by_status %}{{ _("None found") }}{% else %}{% trans count=decisions.attention %}{{ count }} needs attention{% pluralize %}{{ count }} need attention{% endtrans %}{% if to_check %} · {% trans count=to_check %}{{ count }} to check{% pluralize %}{{ count }} to check{% endtrans %}{% endif %}{% endif %}</span></summary>
+  <div class="doc-body">
+  {% if not decisions.by_status %}
+  <p class="muted">{{ _("No architecture decision records were found where the target's settings say they live.") }}</p>
+  {% else %}
+  {{ about(_("A proposed ADR needs attention once it waits longer than the target's settings allow, and a superseded or deprecated one while a guide page still cites it. Worth a look: proposed ADRs with no date, and accepted ones no page cites.")) }}
+  <div class="doc-columns">
+  <div>
+  <h3>{{ _("By status") }}</h3>
+  {% set widest = decisions.by_status.values()|map("length")|max %}
+  <ul class="hbars" lang="en" dir="ltr">{% for status, found in decisions.by_status|dictsort %}{{ hbar(status, found|length, widest, found|length|number, "series-fill-5" if status in ("superseded", "deprecated") else "series-fill-1") }}{% endfor %}</ul>
+  </div>
+  <div>
+  {% if decisions.overdue or decisions.superseded_cited %}
+  <h3>{{ _("Needs attention") }}</h3>
+  {% if decisions.overdue %}
+  <h4>{{ _("Proposed for too long") }}</h4>
+  {% call(decision) listing(decisions.overdue) %}{{ decision_link(decision) }}<span class="faint">{% trans count=days_proposed(decision, today) %}proposed {{ count }} day ago{% pluralize %}proposed {{ count }} days ago{% endtrans %}</span>{% endcall %}
+  {% endif %}
+  {% if decisions.superseded_cited %}
+  <h4>{{ _("Superseded or deprecated, still cited by the guide") }}</h4>
+  {% call(decision) listing(decisions.superseded_cited) %}{{ decision_link(decision) }}{% endcall %}
+  {% endif %}
+  {% endif %}
+  {% if to_check %}
+  <h3>{{ _("Worth a look") }}</h3>
+  {% if decisions.undated %}
+  <h4>{{ _("Proposed, with no date") }}</h4>
+  {% call(decision) listing(decisions.undated) %}{{ decision_link(decision) }}{% endcall %}
+  {% endif %}
+  {% if decisions.uncited and has_pages %}
+  <h4>{{ _("Accepted, but no page cites them") }}</h4>
+  {% call(decision) listing(decisions.uncited) %}{{ decision_link(decision) }}{% endcall %}
+  {% endif %}
+  {% endif %}
+  </div>
+  </div>
+  {% endif %}
+  </div>
+</details>
+</section>
+
+<section id="coverage" aria-labelledby="coverage-title">
+{% set mention_total = mentions.mentioned|length + mentions.unmentioned|length %}
+<details class="doc-fold"{% if open_section == "coverage" %} open{% endif %}>
+  <summary><h2 id="coverage-title">{{ icon("chevron") }}{{ _("Mentioned and explained") }}</h2><span class="doc-todo">{% trans count=mentions.unmentioned|length %}{{ count }} never mentioned{% pluralize %}{{ count }} never mentioned{% endtrans %}{% if has_pages %} · {% trans count=explained.unexplained|length %}{{ count }} unexplained{% pluralize %}{{ count }} unexplained{% endtrans %}{% endif %}</span></summary>
+  <div class="doc-body">
+  {{ about(_("A package counts when a document names it as a whole word, a project when its folder holds a README or a document names its folder, and a resource when a document names its address. A fact is explained when it falls in the scope of a written area or concept page.")) }}
+  <p class="muted">{{ _("External packages, projects and infrastructure resources that some document names. A mention isn't a reason: this only shows what no document talks about at all.") }}</p>
+  <ul class="hbars coverage-bars" dir="ltr">
+    {% set value %}{% trans numerator=mentions.mentioned|length, denominator=mention_total %}{{ numerator }} of {{ denominator }}{% endtrans %}{% endset %}
+    {{ hbar(_("Mentioned in a document"), mentions.mentioned|length, mention_total, value) }}
+    {% if has_pages %}
+    {% set value %}{% trans numerator=explained.explained, denominator=explained.total %}{{ numerator }} of {{ denominator }}{% endtrans %}{% endset %}
+    {{ hbar(_("Explained by a guide page"), explained.explained, explained.total, value) }}
+    {% endif %}
+  </ul>
+  {% if not has_pages %}
+  <p class="muted">{{ _("Which facts the guide explains, and which ADRs it cites, are measured once your assistant has written its pages.") }}</p>
+  {% endif %}
+  <div class="doc-columns">
+  {% if mentions.unmentioned %}
+  <div>
+  <h3>{{ _("Not mentioned in any document") }}</h3>
+  <div data-filterable>
+  {{ chips(fact_filter, [("package", _("Packages")), ("project", _("Projects")), ("resource", _("Resources"))]) }}
+  {% call(entity) listing(mentions.unmentioned, fact_filter) %}{{ fact_link(entity) }}{% endcall %}
+  </div>
+  </div>
+  {% endif %}
+  {% if explained.unexplained and has_pages %}
+  <div>
+  <h3>{{ _("Not explained by any page") }}</h3>
+  {% call(entity) listing(explained.unexplained) %}{{ fact_link(entity) }}{% endcall %}
+  </div>
+  {% endif %}
+  </div>
+  </div>
+</details>
+</section>
+
+</div>
+</div>
+{% endif %}
+</div>
+{% endblock %}

codetrail/web/templates/error.html

@@ -0,0 +1,9 @@
+{% extends "base.html" %}
+{% block title %}{{ _("Not found") }}{% endblock %}
+{% block content %}
+<section class="empty">
+  <h1>{{ _("Not found") }}</h1>
+  <p>{{ _("There's nothing here. It may be excluded, or not in the guide yet.") }}</p>
+  <p><a class="button" href="/">{{ _("Back to the start") }}</a></p>
+</section>
+{% endblock %}

codetrail/web/templates/estimate.html

@@ -0,0 +1,48 @@
+<h2 id="estimate-title">{{ _("Before the update") }}</h2>
+<p>{{ _("The facts are refreshed. Writing the guide will call:") }}</p>
+<table class="estimate">
+  <thead>
+    <tr><th>{{ _("Call") }}</th><th>{{ _("Provider and model") }}</th><th>{{ _("How many") }}</th><th>{{ _("Tokens each") }}</th><th>{{ _("Cost each") }}</th></tr>
+  </thead>
+  <tbody>
+  {% for line in estimate.lines %}
+    <tr>
+      <td>{{ line.kind }}</td>
+      <td>{{ line.provider }} · {{ line.model or _("default model") }}</td>
+      <td>{% if line.expected == line.maximum %}{{ line.expected }}{% else %}{% trans expected=line.expected, maximum=line.maximum %}{{ expected }} to {{ maximum }}{% endtrans %}{% endif %}</td>
+      <td><bdi dir="ltr">~{{ line.tokens_each | tokens }}</bdi>{% if not line.from_history %} <span class="muted">({{ _("a starting guess") }})</span>{% endif %}</td>
+      <td>{% if line.cost_each_usd is none %}{{ _("no price configured") }}{% elif line.cost_each_usd == 0 %}{{ _("free") }}{% else %}<bdi dir="ltr">~{{ line.cost_each_usd | dollars }}</bdi>{% endif %}</td>
+    </tr>
+  {% endfor %}
+  </tbody>
+</table>
+<p>
+  {% trans expected=estimate.expected_tokens|tokens, maximum=estimate.maximum_tokens|tokens %}Expected: ~{{ expected }} tokens; at most ~{{ maximum }}.{% endtrans %}
+  {% if estimate.expected_usd is not none %}{% trans expected=estimate.expected_usd|dollars, maximum=estimate.maximum_usd|dollars %}At API prices: ~{{ expected }}, at most {{ maximum }}.{% endtrans %}{% endif %}
+  {% trans budget=estimate.budget_usd|dollars, tokens=estimate.budget_tokens|tokens %}The update stops at its budget of {{ budget }} or {{ tokens }} tokens, whichever comes first.{% endtrans %}
+</p>
+{% macro why(page) -%}
+{%- if page.reason == "update" %}{% trans count=page.changed %}one of its facts changed in this update{% pluralize %}{{ count }} of its facts changed in this update{% endtrans %}
+{%- elif page.reason == "new" %}{{ _("a new page") }}
+{%- elif page.reason == "outline" %}{{ _("its outline entry changed") }}
+{%- else %}{{ _("catching up, since its facts changed after it was written") }}{% endif -%}
+{%- endmacro %}
+{% if estimate.pages %}
+<p>{{ _("Pages, in the order they’re written:") }}</p>
+<ol class="estimate-pages">
+{% for page in estimate.pages %}
+  <li>“{{ page.title }}”{% if page.revise %} ({{ _("revised") }}){% endif %}: {{ why(page) }}</li>
+{% endfor %}
+</ol>
+{% endif %}
+{% if estimate.skipped %}
+<p>{{ _("Skipped, since they failed last time and nothing in them changed:") }} {{ estimate.skipped|join(", ") }}</p>
+{% endif %}
+<ul class="estimate-notes">
+{% for provider, method in estimate.sign_ins.items() %}
+  <li>{{ provider }}: {{ method }}{% if "subscription" in method|lower %}: {{ _("no charge; the work counts against your plan's usage limits.") }}{% elif provider != "local" %}: {{ _("billed to that account.") }}{% endif %}</li>
+{% endfor %}
+{% for reading in estimate.plan_usage %}
+  <li>{% trans provider=reading.provider, window=reading.window|replace("_", " "), used=(reading.utilization * 100)|round|int, when=reading.observed_at|utc %}Plan usage ({{ provider }}, {{ window }}): {{ used }}%, as of {{ when }}.{% endtrans %}</li>
+{% endfor %}
+</ul>

codetrail/web/templates/fact.html

@@ -0,0 +1,29 @@
+{% extends "base.html" %}
+{% block title %}{{ entity.id }}{% endblock %}
+{% block content %}
+<div class="wide">
+<header class="page-head">
+  <p class="eyebrow">{{ _("Fact") }} · <span lang="en" dir="ltr">{{ entity.kind }}</span></p>
+  <h1 lang="en" dir="ltr">{{ entity.id }}</h1>
+</header>
+{% if entity.attributes %}
+<table class="attributes" lang="en" dir="ltr">
+  {% for key, value in entity.attributes.items() %}<tr><th>{{ key }}</th><td>{{ value }}</td></tr>{% endfor %}
+</table>
+{% endif %}
+<h2>{{ _("Found in") }}</h2>
+<ul class="list" lang="en" dir="ltr">
+  {% for source in entity.sources %}
+  <li><a class="grow" href="/source/{{ source.path|urlencode }}{% if source.start_line %}#L{{ source.start_line }}{% endif %}">{{ source.path }}{% if source.start_line %}:{{ source.start_line }}{% endif %}</a></li>
+  {% endfor %}
+</ul>
+{% if outgoing %}
+<h2>{{ _("Points to") }}</h2>
+<ul class="list" lang="en" dir="ltr">{% for relation in outgoing %}<li><span class="kind">{{ relation.kind }}</span><a class="grow" href="/facts/{{ relation.target_id|urlencode|replace("/", "%2F") }}">{{ relation.target_id }}</a></li>{% endfor %}</ul>
+{% endif %}
+{% if incoming %}
+<h2>{{ _("Pointed to by") }}</h2>
+<ul class="list" lang="en" dir="ltr">{% for relation in incoming %}<li><a class="grow" href="/facts/{{ relation.source_id|urlencode|replace("/", "%2F") }}">{{ relation.source_id }}</a><span class="kind">{{ relation.kind }}</span></li>{% endfor %}</ul>
+{% endif %}
+</div>
+{% endblock %}

codetrail/web/templates/home.html

@@ -0,0 +1,196 @@
+{% extends "base.html" %}
+{% from "layout/icons.html" import icon %}
+{% block content %}
+{% macro since_last_update() %}
+<section class="card rail-card" aria-labelledby="update-title">
+  <p class="card-label" id="update-title">{{ _("Since the last update") }}</p>
+  <div class="rail-row">
+    {% if signal is none %}
+      <span class="chip">—</span>
+    {% elif signal.updating %}
+      <span class="chip">…</span>
+    {% elif signal.commits == 0 %}
+      <span class="chip chip-ok">{{ _("Up to date") }}</span>
+    {% else %}
+      <span class="chip chip-behind">{% trans count=signal.commits %}{{ count }} commit behind{% pluralize %}{{ count }} commits behind{% endtrans %}</span>
+    {% endif %}
+    <button type="button" class="button small" data-update-button>{{ _("Update the guide") }}</button>
+  </div>
+  <p class="stat-note">
+    {%- if signal is none %}{{ _("Couldn't check for new commits just now.") }}
+    {%- elif signal.updating %}{{ _("An update is running.") }}
+    {%- elif signal.commits == 0 %}{{ _("The guide matches the branch.") }}
+    {%- else %}{% trans count=signal.merges %}{{ count }} merge landed{% pluralize %}{{ count }} merges landed{% endtrans %}{% if signal.areas %} · <span lang="en" dir="ltr">{{ signal.areas[:3] | join(", ") }}</span>{% endif %}{% endif -%}
+  </p>
+  {% if last_update %}<p class="stat-note">{% trans tokens=last_update.tokens|tokens, cost=last_update.cost_usd|dollars %}The last update used ~{{ tokens }} tokens ({{ cost }} at API prices).{% endtrans %}</p>{% endif %}
+</section>
+{% endmacro %}
+{% macro what_changed() %}
+<section class="card rail-card" aria-labelledby="changed-title">
+  <p class="card-label" id="changed-title">{{ _("What changed") }}</p>
+  {% if unread_digests %}
+    <a class="stat-link" href="/pages/{{ unread_digests[0].id }}" lang="en" dir="ltr">{{ unread_digests[0].title }}</a>
+    <p class="stat-note">{% trans count=unread_digests|length %}{{ count }} unread digest{% pluralize %}{{ count }} unread digests{% endtrans %}</p>
+  {% elif latest_digest %}
+    <a class="stat-link" href="/pages/{{ latest_digest.id }}" lang="en" dir="ltr">{{ latest_digest.title }}</a>
+    <p class="stat-note">{{ _("You're caught up.") }}</p>
+  {% else %}
+    <p class="stat-note">{{ _("No digest yet.") }}</p>
+  {% endif %}
+</section>
+{% endmacro %}
+{% macro system_card() %}
+{% if system %}
+<section class="card rail-card metric-card" data-hue="system" aria-labelledby="system-title">
+  <span class="hue">{{ icon("system") }}</span>
+  <div>
+    <p class="card-label" id="system-title">{{ _("Your system") }}</p>
+    <p class="metric-figure">{% trans count=system.parts %}{{ count }} part{% pluralize %}{{ count }} parts{% endtrans %} · {% trans count=system.connections %}{{ count }} connection{% pluralize %}{{ count }} connections{% endtrans %}{{ _(", drawn from the code") }}</p>
+    <a class="stat-note" href="/system">{{ _("See how it fits together") }}</a>
+  </div>
+</section>
+{% endif %}
+{% endmacro %}
+{% macro documentation_card() %}
+{% if snapshot %}
+<section class="card rail-card metric-card" data-hue="documented" aria-labelledby="documentation-title">
+  <span class="hue">{{ icon("metrics") }}</span>
+  <div class="grow">
+    <p class="card-label" id="documentation-title">{{ _("Documentation") }}</p>
+    {% if documentation and documentation.percent is not none %}
+    <p class="metric-figure">{% trans percent=documentation.percent %}{{ percent }}% of the guide's rationale is documented{% endtrans %}</p>
+    <progress class="bar" max="100" value="{{ documentation.percent }}" aria-hidden="true"></progress>
+    {% if documentation.change is not none %}<p class="stat-note">{% trans change="%+d"|format(documentation.change) %}{{ change }} points since the last update{% endtrans %}</p>{% endif %}
+    {% else %}
+    <p class="stat-note">{{ _("How well the repository explains itself: rationale, commits, decisions and documents.") }}</p>
+    {% endif %}
+    <a class="stat-note" href="/documentation">{{ _("See what's documented") }}</a>
+  </div>
+</section>
+{% endif %}
+{% endmacro %}
+{% macro repository_card() %}
+{% if snapshot and repository %}
+<section class="card rail-card metric-card" data-hue="repository" aria-labelledby="repository-title">
+  <span class="hue">{{ icon("repository") }}</span>
+  <div>
+    <p class="card-label" id="repository-title">{{ _("Repository") }}</p>
+    {% if repository.commits is not none %}<p class="metric-figure">{% trans count=repository.commits, commits=repository.commits|number %}{{ commits }} commit{% pluralize %}{{ commits }} commits{% endtrans %}</p>{% endif %}
+    <p class="stat-note">{% if repository.first %}{% trans date=repository.first.isoformat() %}Started on {{ date }}{% endtrans %}{% if repository.code_lines is not none %} · {% endif %}{% endif %}{% if repository.code_lines is not none %}{% trans count=repository.code_lines, lines=repository.code_lines|number %}{{ lines }} line of code{% pluralize %}{{ lines }} lines of code{% endtrans %}{% endif %}</p>
+    <a class="stat-note" href="/repository">{{ _("See the repository's statistics") }}</a>
+  </div>
+</section>
+{% endif %}
+{% endmacro %}
+{% macro browse_the_code() %}
+<section class="card rail-card" aria-labelledby="browse-title">
+  <p class="card-label" id="browse-title">{{ _("Browse the code") }}</p>
+  {% if areas %}
+  <ul class="folder-chips" lang="en" dir="ltr">
+    {% for area, files in areas %}
+    <li><a class="folder-chip" href="/areas/{{ area|urlencode }}">{{ icon("folder") }} {{ area }}/ <span class="faint">{{ files }}</span></a></li>
+    {% endfor %}
+  </ul>
+  {% else %}
+  <p class="stat-note">{% trans name=target %}No sources yet. Run <code>codetrail update {{ name }}</code> to read the repository.{% endtrans %}</p>
+  {% endif %}
+  {% if counts %}
+  <p class="stat-note">{{ _("Facts:") }} {% for kind, count in counts %}<span lang="en" dir="ltr">{{ kind }}</span> {{ count }}{% if not loop.last %} · {% endif %}{% endfor %}</p>
+  {% endif %}
+</section>
+{% endmacro %}
+<div class="wide home">
+<header class="home-head">
+  <h1 lang="en" dir="ltr">{{ target }}</h1>
+  <p class="meta" lang="en" dir="ltr">{% if nav.branch %}{{ nav.branch }}{% endif %}{% if snapshot %} · {{ snapshot.commit[:12] }} · {{ snapshot.taken_at | utc }}{% endif %}</p>
+</header>
+
+<div class="home-columns">
+<div class="home-main">
+{% if not guide_pages %}
+<section class="empty">
+  <h2>{{ _("Run your first update") }}</h2>
+  <p>{{ _("Codetrail reads the code for free, then your assistant writes the guide: concept pages, guided paths and checks. You'll see the estimate before anything is spent.") }}</p>
+  <button type="button" class="button primary" data-update-button>{{ _("Update the guide") }}</button>
+  <p class="faint">{% trans name=target %}Or from a terminal: <code>codetrail update {{ name }}</code>{% endtrans %}</p>
+</section>
+{% else %}
+
+{% if continue_reading %}
+{% set path, step, steps_learned, steps_total = continue_reading %}
+<section class="card card-accent continue" aria-labelledby="continue-title">
+  <svg class="ring" viewBox="0 0 44 44" aria-hidden="true" focusable="false"><circle class="ring-track" cx="22" cy="22" r="18" pathLength="100"/>{% if steps_learned %}<circle class="ring-value" cx="22" cy="22" r="18" pathLength="100" stroke-dasharray="{{ (100 * steps_learned / (steps_total or 1)) | round(1) }} 100"/>{% endif %}</svg>
+  <div class="grow">
+    <p class="card-label" id="continue-title">{{ _("Continue where you left off") }}</p>
+    <p class="continue-path" lang="en" dir="ltr">{{ path.title }}</p>
+    <p class="card-title" lang="en" dir="ltr">{{ step.title }}</p>
+    <p class="faint">{% trans learned=steps_learned, total=steps_total %}{{ learned }} of {{ total }} learned{% endtrans %}</p>
+  </div>
+  <a class="button primary" href="/pages/{{ step.id }}?path={{ path.id }}">{{ _("Continue") }} {{ icon("arrow") }}</a>
+</section>
+{% elif nav.paths %}
+<section class="card card-accent">
+  <p class="card-label">{{ _("Every path learned") }}</p>
+  <p class="card-title">{{ _("You've learned every guided path. Updates will tell you what changes.") }}</p>
+</section>
+{% endif %}
+
+<section class="card home-paths" aria-labelledby="paths-title">
+  <div class="section-head">
+    <h2 id="paths-title">{{ _("Paths") }}</h2>
+    <a href="/progress">{% trans learned=learned, total=guide_pages|length %}{{ learned }} of {{ total }} learned{% endtrans %}</a>
+  </div>
+  {% if nav.paths %}
+  <ul class="path-rows" lang="en" dir="ltr">
+    {% for path, steps_learned, steps_total in nav.paths %}
+    <li><a href="/pages/{{ path.id }}">{{ path.title }}</a><progress class="bar" max="{{ steps_total or 1 }}" value="{{ steps_learned }}" aria-hidden="true"></progress><span class="faint">{{ steps_learned }}/{{ steps_total }}</span></li>
+    {% endfor %}
+  </ul>
+  {% endif %}
+</section>
+
+{% if stale_pages %}
+<section>
+  <h2>{{ _("Changed since you learned them") }}</h2>
+  <ul class="list" lang="en" dir="ltr">
+    {% for page in stale_pages %}<li><a class="grow" href="/pages/{{ page.id }}">{{ page.title }}</a><span class="pill pill-stale">{{ _("changed") }}</span></li>{% endfor %}
+  </ul>
+</section>
+{% endif %}
+
+<section aria-labelledby="areas-title">
+  <h2 id="areas-title">{{ _("Areas") }}</h2>
+  <ul class="grid area-grid" lang="en" dir="ltr">
+    {% for area in nav.areas %}
+    {% set state = nav.statuses.get(area.id, "unread") %}
+    <li><a class="tile area-tile" data-status="{{ state }}" href="/pages/{{ area.id }}"><span class="tile-title">{{ area.title }}</span>
+      {% if state == "learned" %}<span class="pill pill-learned">{{ _("Learned") }}</span>{% elif state == "stale" %}<span class="pill pill-stale">{{ _("Changed") }}</span>{% elif state == "read" %}<span class="pill pill-read">{{ _("Read") }}</span>{% else %}<span class="pill">{{ _("Not read yet") }}</span>{% endif %}</a></li>
+    {% endfor %}
+  </ul>
+</section>
+{% endif %}
+</div>
+
+<aside class="home-rail" aria-label="{{ _('The repository') }}">
+{% if snapshot %}{{ since_last_update() }}{% endif %}
+{% if guide_pages %}{{ what_changed() }}{% endif %}
+{{ system_card() }}
+{{ documentation_card() }}
+{{ repository_card() }}
+{% if guide_pages %}
+<section class="card rail-card" aria-labelledby="answers-title">
+  <div class="section-head"><p class="card-label" id="answers-title">{{ _("Your saved answers") }}</p>{% if nav.answer_count %}<a class="stat-note" href="/answers">{{ _("All saved answers") }}</a>{% endif %}</div>
+  {% if nav.answers %}
+  <ul class="rail-list">
+    {% for answer in nav.answers %}<li><a href="/pages/{{ answer.id }}" dir="auto">{{ answer.title }}</a></li>{% endfor %}
+  </ul>
+  {% else %}
+  <p class="stat-note">{{ _("Ask a question from any page (press A) and save the answers worth keeping. They'll be here.") }}</p>
+  {% endif %}
+</section>
+{% endif %}
+{{ browse_the_code() }}
+</aside>
+</div>
+</div>
+{% endblock %}

codetrail/web/templates/layout/ask_panel.html

@@ -0,0 +1,27 @@
+{% from "macros.html" import cost with context %}
+{% from "layout/icons.html" import icon %}
+<aside class="ask-panel" data-ask {% if page is defined and page.id %}data-page-id="{{ page.id }}"{% endif %}
+       data-language="{{ language.code }}"
+       data-label-save="{{ _('Save to guide') }}" data-label-saved="{{ _('Saved · open it') }}"
+       data-label-save-failed="{{ _('Couldn’t save the answer.') }}"
+       aria-labelledby="ask-title" id="ask-panel" hidden>
+  <div class="resize-handle resize-panel" data-resize="panel" role="separator" aria-orientation="vertical"
+       aria-controls="ask-panel" aria-label="{{ _('Resize the Ask panel') }}"
+       title="{{ _('Drag to resize; double-click to reset') }}" tabindex="0"></div>
+  <div class="ask-head">
+    <h2 id="ask-title">{{ _("Ask about the code") }}</h2>
+    <button type="button" class="icon-button" data-ask-close aria-label="{{ _('Close') }}">{{ icon("close") }}</button>
+  </div>
+  <div class="ask-thread" data-ask-thread aria-live="polite">
+    <p class="ask-intro" data-ask-intro>{% if page is defined and page.id %}{{ _("Ask anything about the code. Your question goes with the page you're reading. Save the answers worth keeping.") }}{% else %}{{ _("Ask anything about the code. Save the answers worth keeping.") }}{% endif %}</p>
+  </div>
+  <form class="ask-form" data-ask-form>
+    <label class="visually-hidden" for="ask-question">{{ _("Your question") }}</label>
+    <textarea id="ask-question" name="question" rows="3" maxlength="4000" required placeholder="{{ _('For example: how does a request reach the database?') }}"></textarea>
+    <div class="ask-form-row">
+      <p class="ask-status" data-ask-status data-label-reading="{{ _('The assistant is reading the code…') }}"
+         data-label-used="{{ _('Used') }}" data-label-tokens="{{ _('tokens') }}"></p>
+      <button type="submit" class="button primary">{{ _("Send") }} {{ cost(estimates.get("answer")) }}</button>
+    </div>
+  </form>
+</aside>

codetrail/web/templates/layout/header.html

@@ -0,0 +1,32 @@
+{% from "layout/icons.html" import icon %}
+<header class="topbar">
+  <button type="button" class="icon-button sidebar-toggle" data-sidebar-toggle aria-controls="sidebar" aria-expanded="true"
+          aria-label="{{ _('Hide the sidebar') }}" data-label-hide="{{ _('Hide the sidebar') }}"
+          data-label-show="{{ _('Show the sidebar') }}">{{ icon("sidebar") }}</button>
+  <button type="button" class="icon-button menu-button" data-menu aria-controls="sidebar" aria-expanded="false" aria-label="{{ _('Menu') }}">{{ icon("menu") }}</button>
+  <a class="brand" href="/"><img src="/static/brand/mark.svg" alt="" width="24" height="24"><span>codetrail</span></a>
+  <span class="target" lang="en" dir="ltr">{{ target }}{% if nav.branch or nav.commit %}<span class="target-meta">{{ nav.branch }}{% if nav.commit %} · {{ nav.commit[:7] }}{% endif %}</span>{% endif %}</span>
+  <div class="topbar-search">
+    <form class="search-box" action="/search" method="get" role="search" data-search-form>
+      {{ icon("search") }}
+      <input type="search" name="q" placeholder="{{ _('Search or ask…') }}" aria-label="{{ _('Search the guide') }}" autocomplete="off" maxlength="1000">
+      <kbd class="search-hint" aria-hidden="true">⌘K</kbd>
+    </form>
+  </div>
+  <div class="topbar-actions">
+    <button type="button" class="button" data-ask-open>{{ icon("ask") }}<span>{{ _("Ask") }}</span></button>
+    <button type="button" class="icon-button" data-theme-toggle
+            data-label-system="{{ _('Theme: system (switch to light)') }}"
+            data-label-light="{{ _('Theme: light (switch to dark)') }}"
+            data-label-dark="{{ _('Theme: dark (switch to system)') }}"
+            aria-label="{{ _('Switch theme') }}">{{ icon("sun") }}</button>
+    <form class="language" data-language-form>
+      <label><span class="visually-hidden">{{ _("Language") }}</span>
+        <select name="language">
+          {% for option in languages %}<option value="{{ option.code }}" {% if option.code == language.code %}selected{% endif %}>{{ option.name }}</option>{% endfor %}
+        </select>
+      </label>
+    </form>
+    <button type="button" class="icon-button" data-shortcuts-open aria-label="{{ _('Keyboard shortcuts') }}">{{ icon("keyboard") }}</button>
+  </div>
+</header>