/**
* HTML report generator (the "expanded" mode) — a self-contained, presentable
* report rendered from the shared report model. Inline CSS, no external assets;
* opens in a browser and is shareable as a single file. Also the natural output
* for the future hosted service.
*
* Customization: a default template with `{{placeholder}}` slots, overridable
* via `template`, plus theme knobs (title, logo, accent, footer).
*/
import type { AuditFinding } from "./core";
import { ruleDocUrl, type RuleMeta } from "./catalog";
import { buildReportModel, buildReportJson, type AuditSnapshot, type BuildModelOptions, type EnrichedFinding, type GuidanceCluster, type QuickWinFile, type ReportCounts } from "./report-model";
export type { AuditSnapshot } from "./report-model";
/** Customizable theme knobs filled into the template. */
export interface ReportTheme {
title?: string;
/** Logo: a URL (rendered as ![]()
) or inline text/SVG. */
logo?: string;
/** CSS color for accents. */
accent?: string;
/** Footer HTML (defaults to attribution). */
footer?: string;
}
export interface RenderHtmlOptions extends BuildModelOptions {
snapshot?: AuditSnapshot;
theme?: ReportTheme;
/** Full template override; `{{title}} {{accent}} {{logo}} {{meta}} {{body}} {{footer}}` slots. */
template?: string;
notes?: string[];
}
const DEFAULT_ACCENT = "#7c3aed";
const DEFAULT_TITLE = "chant audit";
const DEFAULT_FOOTER = 'Generated by chant audit.';
function esc(s: string): string {
return s.replace(/&/g, "&").replace(//g, ">").replace(/"/g, """);
}
/** A rule id as a link to its reference entry. */
function ruleLink(id: string): string {
return `${esc(id)}`;
}
/** External backing for a merge-worthy rule (OSSF Scorecard, CIS, vendor docs). */
function authorityLinks(meta: RuleMeta): string {
if (!meta.authority?.length) return "";
const links = meta.authority.map((a) => `${esc(a.name)}`).join(", ");
return ` per ${links}`;
}
function renderDiff(diff: string): string {
const rows = diff
.split("\n")
.map((l) => {
const cls = l.startsWith("@@") ? "hunk" : l.startsWith("+") ? "add" : l.startsWith("-") ? "del" : "ctx";
return `${esc(l) || " "}`;
})
.join("\n");
return `${rows}`;
}
function renderQuickWins(files: QuickWinFile[]): string {
const cards = files
.map((qw) => {
const chips = qw.addressed.map((m) => `${ruleLink(m.id)} ${esc(m.title)}${authorityLinks(m)}`).join(" ");
const diff = qw.diff ? renderDiff(qw.diff) : "";
const needs = qw.needsInput.length
? `Needs a value to auto-patch:${qw.needsInput
.map((f) => `- ${ruleLink(f.checkId)}${f.entity ? ` (
${esc(f.entity)})` : ""} — ${esc(f.meta.remediation)}${authorityLinks(f.meta)} `)
.join("")}
`
: "";
return `${esc(qw.file)} ${chips}
${diff}${needs}
Quick wins deterministic
Safe mechanical fixes — the diff changes only the flagged lines.
${cards}`;
}
function renderNeedsReview(clusters: GuidanceCluster[], n: number): string {
const body = clusters
.map((c) => {
const head = c.url ? `${esc(c.name)}` : esc(c.name);
const rules = c.rules
.map(({ meta, findings }) => {
const locs = findings
.map((f) => `${esc(f.file)}${f.entity ? ` (${esc(f.entity)})` : ""} — ${esc(f.message)}`)
.join("");
return `${ruleLink(meta.id)} — ${esc(meta.title)}. ${esc(meta.remediation)}${authorityLinks(meta)}
${head}
${rules}`;
})
.join("\n");
return `Needs review guidance — ${n}
These need a judgement call — remediation guidance, not an auto-fix.
${body}| ${ruleLink(f.checkId)} | ${esc(f.meta.title)} | ${esc(f.file)} | ${esc(f.message)} |
`)
.join("");
return `Report-only hygiene — ${n}
| Rule | Title | File | Detail |
|---|
${rows}
${esc(snapshot.ref)}`);
if (snapshot.commit) meta.push(`commit ${esc(snapshot.commit.slice(0, 10))}`);
meta.push(esc(snapshot.generatedAt.slice(0, 10)));
meta.push(`${snapshot.files.length} file${snapshot.files.length === 1 ? "" : "s"}`);
meta.push(`chant ${esc(snapshot.toolVersion)}`);
}
const noteHtml = notes.map((n) => `${esc(n)}
`).join("");
return `${meta.join(" · ")}
${sev}
${tiers}
${cats}
${noteHtml}
{{body}}
`;
/** Render an audit report as a self-contained HTML document. */
export function renderHtml(findings: AuditFinding[], opts: RenderHtmlOptions = {}): string {
const model = buildReportModel(findings, opts);
const theme = opts.theme ?? {};
const accent = theme.accent ?? DEFAULT_ACCENT;
const title = theme.title ?? DEFAULT_TITLE;
const logo = theme.logo ? (/^https?:\/\//.test(theme.logo) ? `})
` : theme.logo) : "";
const footer = theme.footer ?? DEFAULT_FOOTER;
// Machine-readable data embedded so the HTML report is also parseable.
// `<` escaped so the JSON can't break out of the `;
let body: string;
if (model.counts.total === 0) {
body = renderHeader(model.counts, opts.snapshot, opts.notes ?? []) + `` + dataScript;
} else {
const parts = [renderHeader(model.counts, opts.snapshot, opts.notes ?? [])];
if (model.quickWins.length > 0) parts.push(renderQuickWins(model.quickWins));
if (model.needsReview.length > 0) parts.push(renderNeedsReview(model.needsReview, model.counts.needsReview));
if (model.reportOnly.length > 0) parts.push(renderReportOnly(model.reportOnly, model.counts.reportOnly));
parts.push(dataScript);
body = parts.join("\n");
}
const slots: Record = {
title: esc(title),
accent,
styles: STYLES.replace("{{accent}}", accent),
logo,
body,
footer,
};
const template = opts.template ?? DEFAULT_TEMPLATE;
// Single pass over the template only, so injected body content isn't re-scanned.
return template.replace(/\{\{(\w+)\}\}/g, (_, k: string) => slots[k] ?? "");
}