unit27research/one-good-commit

1(() => {2  "use strict";3 4  const MAX_README_BYTES = 2_000_000;5  const REPO_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/;6  const checks = [7    ["license", "License", ["license", "license_name", "license_link"], [], [], "Confirm the license identifier or link that governs reuse."],8    ["language", "Language coverage", ["language", "languages"], ["\\blanguages?\\b"], [], "Document the languages represented and any known coverage limits."],9    ["task", "Task and model type", ["pipeline_tag", "library_name", "tags"], ["\\bmodel description\\b", "\\btask\\b"], [], "Clarify the task, model family, and expected input/output shape."],10    ["base_model", "Base model or provenance", ["base_model"], ["\\bmodel description\\b", "\\bmodel details\\b", "\\bprovenance\\b"], ["\\bbase model\\b", "\\bfine[- ]?tuned from\\b", "\\bderived from\\b"], "Name the base model or explain the model's provenance."],11    ["intended_uses", "Intended uses", [], ["\\bintended uses?\\b", "\\buse cases?\\b", "\\buses?\\b", "\\bhow to use\\b"], ["\\bintended for\\b", "\\bcan be used\\b", "\\buse cases?\\b"], "Describe supported use cases and the users or settings considered."],12    ["out_of_scope", "Out-of-scope uses", [], ["\\bout[- ]of[- ]scope\\b", "\\bmisuse\\b", "\\bnot intended\\b", "\\bprohibited uses?\\b"], ["\\bshould not\\b", "\\bnot intended\\b", "\\bout[- ]of[- ]scope\\b"], "Identify unsupported or inappropriate uses, where relevant."],13    ["limitations", "Limitations, risks, or biases", [], ["\\blimitations?\\b", "\\brisks?\\b", "\\bbias(?:es)?\\b", "\\bethical considerations?\\b"], ["\\blimitations?\\b", "\\brisks?\\b", "\\bbias(?:es|ed)?\\b"], "Describe known limitations, biases, or risks and how they were observed."],14    ["training_data", "Training data", ["datasets", "dataset"], ["\\btraining data\\b", "\\bdatasets?\\b", "\\btraining details\\b"], ["\\btrained on\\b", "\\btraining dataset\\b"], "Name or characterize the training data and include source links when possible."],15    ["evaluation", "Evaluation evidence", ["model-index", "eval_results", "metrics"], ["\\bevaluation\\b", "\\bresults?\\b", "\\bbenchmarks?\\b", "\\bmetrics?\\b"], ["\\bbenchmark\\b", "\\baccuracy\\b", "\\bf1\\b", "\\bbleu\\b", "\\brouge\\b"], "Link evaluation datasets, metrics, values, and their source or procedure."],16    ["reproducibility", "Training and reproducibility details", ["training_args"], ["\\btraining procedure\\b", "\\btraining details\\b", "\\bhyperparameters?\\b", "\\breproducibility\\b"], ["\\blearning rate\\b", "\\bbatch size\\b", "\\btraining steps?\\b"], "Add the training procedure, key parameters, code, or experiment links."],17    ["citation", "Citation or supporting paper", ["citation"], ["\\bcitation\\b", "\\breferences?\\b", "\\bpaper\\b"], [], "Add a citation, paper, technical report, or supporting reference if one exists."]18  ];19 20  const form = document.querySelector("#review-form");21  const input = document.querySelector("#repo-id");22  const notice = document.querySelector("#notice");23  const results = document.querySelector("#results");24  const summary = document.querySelector("#summary");25  const evidencePanel = document.querySelector("#evidence-panel");26  const worksheetPanel = document.querySelector("#worksheet-panel");27  const discussionPanel = document.querySelector("#discussion-panel");28  const downloadButton = document.querySelector("#download-review");29  const modelOptions = document.querySelector("#model-options");30  const pickerStatus = document.querySelector("#picker-status");31  let latestReview = null;32  let searchTimer = null;33  let searchNonce = 0;34 35  function cleanRepoId(value) {36    let id = value.trim();37    if (id.startsWith("https://huggingface.co/")) id = id.slice("https://huggingface.co/".length).split("/").slice(0, 2).join("/");38    if (!REPO_ID.test(id)) throw new Error("Select a model from the live results, or enter its exact owner/model-name ID.");39    return id;40  }41 42  function numberLabel(value) {43    const number = Number(value || 0);44    if (number >= 1_000_000) return `${(number / 1_000_000).toFixed(number >= 10_000_000 ? 0 : 1)}M`;45    if (number >= 1_000) return `${(number / 1_000).toFixed(number >= 10_000 ? 0 : 1)}K`;46    return String(number);47  }48 49  function hideModelOptions() {50    modelOptions.hidden = true;51    input.setAttribute("aria-expanded", "false");52  }53 54  function showModelOptions(models, label) {55    modelOptions.replaceChildren();56    pickerStatus.textContent = label;57    if (!models.length) { hideModelOptions(); return; }58    models.forEach((model) => {59      const id = model.id || model.modelId;60      if (!id) return;61      const option = make("button", "model-option");62      option.type = "button";63      option.setAttribute("role", "option");64      option.setAttribute("aria-label", `Select ${id}`);65      const detail = model.pipeline_tag ? `${model.pipeline_tag} · ${numberLabel(model.downloads)} downloads` : `${numberLabel(model.downloads)} downloads`;66      const copy = make("span");67      copy.append(make("strong", "", id), make("span", "", detail));68      option.append(copy);69      if (model.pipeline_tag) option.append(make("span", "task", model.pipeline_tag));70      option.addEventListener("click", () => { input.value = id; modelOptions.replaceChildren(); hideModelOptions(); pickerStatus.textContent = `Selected: ${id}`; input.focus(); });71      modelOptions.append(option);72    });73    if (!modelOptions.childElementCount) { hideModelOptions(); return; }74    modelOptions.hidden = false;75    input.setAttribute("aria-expanded", "true");76  }77 78  async function searchModels(query = "") {79    const nonce = ++searchNonce;80    pickerStatus.textContent = query ? "Searching public models…" : "Loading live public models…";81    const params = new URLSearchParams({ limit: "8", sort: "downloads", direction: "-1" });82    if (query) params.set("search", query);83    try {84      const response = await fetch(`https://huggingface.co/api/models?${params}`);85      if (!response.ok) throw new Error("unavailable");86      const models = (await response.json()).filter((model) => !model.private && !model.gated && !model.disabled);87      if (nonce !== searchNonce) return;88      showModelOptions(models, query ? "Live public matches" : "Popular public models — start typing to narrow the list");89    } catch (_) {90      if (nonce !== searchNonce) return;91      pickerStatus.textContent = "Live model picker is unavailable right now. You can still enter an exact public model ID.";92      hideModelOptions();93    }94  }95 96  function meaningful(value) {97    if (value === null || value === undefined || value === false) return false;98    if (typeof value === "string") return Boolean(value.trim());99    if (Array.isArray(value)) return value.length > 0;100    if (typeof value === "object") return Object.keys(value).length > 0;101    return true;102  }103 104  function compact(value, limit = 320) {105    const text = (typeof value === "object" ? JSON.stringify(value) : String(value)).replace(/\s+/g, " ").trim();106    return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;107  }108 109  function frontmatter(readme) {110    const lines = readme.split("\n");111    if (lines[0]?.trim() !== "---") return {};112    const end = lines.findIndex((line, index) => index > 0 && line.trim() === "---");113    if (end < 0) return {};114    const metadata = {};115    let current = null;116    for (const line of lines.slice(1, end)) {117      if (!line.trim() || line.trimStart().startsWith("#")) continue;118      const list = line.match(/^\s*-\s+(.+?)\s*$/);119      if (list && current) { if (Array.isArray(metadata[current])) metadata[current].push(list[1].replace(/^['"]|['"]$/g, "")); continue; }120      const key = line.match(/^([A-Za-z0-9_-]+):(?:\s*(.*))?$/);121      if (!key) continue;122      current = key[1];123      const value = (key[2] || "").trim();124      metadata[current] = value ? value.replace(/^['"]|['"]$/g, "") : [];125    }126    return metadata;127  }128 129  function sections(readme) {130    const lines = readme.split("\n");131    const headings = [];132    let fenced = false;133    lines.forEach((line, index) => {134      if (/^\s*(```|~~~)/.test(line)) { fenced = !fenced; return; }135      if (fenced) return;136      const match = line.match(/^(#{1,6})\s+(.+?)\s*#*\s*$/);137      if (match) headings.push({ start: index + 1, level: match[1].length, title: match[2].trim() });138    });139    return headings.map((heading, index) => {140      let end = lines.length;141      for (const next of headings.slice(index + 1)) { if (next.level <= heading.level) { end = next.start - 1; break; } }142      return { ...heading, body: lines.slice(heading.start, end).join("\n").trim() };143    });144  }145 146  function sourceLink(repo, revision, line) {147    const link = `https://huggingface.co/${repo}/blob/${revision}/README.md`;148    return line ? `${link}#L${line}` : link;149  }150 151  function analyze(repo, api, readme) {152    const revision = api.sha || "main";153    const metadata = { ...frontmatter(readme), ...(api.cardData || {}) };154    if (!metadata.pipeline_tag && api.pipeline_tag) metadata.pipeline_tag = api.pipeline_tag;155    if (!metadata.library_name && api.library_name) metadata.library_name = api.library_name;156    if (!metadata.tags && api.tags) metadata.tags = api.tags;157    const parsedSections = sections(readme);158    const lines = readme.split("\n");159    const findings = checks.map(([key, label, keys, headings, keywords, prompt]) => {160      const evidence = [];161      const foundKeys = keys.filter((item) => meaningful(metadata[item]));162      foundKeys.slice(0, 2).forEach((item) => evidence.push({ type: "Model card metadata", text: `${item}: ${compact(metadata[item])}`, url: sourceLink(repo, revision) }));163      const matchedSections = parsedSections.filter((section) => headings.some((pattern) => new RegExp(pattern, "i").test(section.title)));164      if (matchedSections[0]) {165        const item = matchedSections[0];166        evidence.push({ type: "Model card section", text: compact(`${item.title}: ${item.body}`, 420), url: sourceLink(repo, revision, item.start) });167      }168      if (!evidence.length && keywords.length) {169        const foundLine = lines.findIndex((line) => line.trim() && !line.trim().startsWith("#") && keywords.some((pattern) => new RegExp(pattern, "i").test(line)));170        if (foundLine >= 0) evidence.push({ type: "Model card text", text: compact(lines[foundLine], 420), url: sourceLink(repo, revision, foundLine + 1) });171      }172      let status = evidence.length ? "documented" : "not_found";173      let text = evidence.length ? "Relevant information was found in the public card." : "Relevant information was not found by this review.";174      if (key === "evaluation" && matchedSections.length && !foundKeys.length) { status = "review"; text = "Evaluation text was found, but structured evaluation metadata was not found."; }175      if (key === "task" && foundKeys.length === 1 && foundKeys[0] === "tags") { status = "review"; text = "Relevant tags were found; the narrative description may still need review."; }176      return { key, label, status, text, evidence, prompt };177    });178    return { repo, revision, sourceUrl: sourceLink(repo, revision), findings, analyzedAt: new Date().toISOString() };179  }180 181  function counts(review) { return review.findings.reduce((all, finding) => ({ ...all, [finding.status]: (all[finding.status] || 0) + 1 }), { documented: 0, review: 0, not_found: 0 }); }182  function statusLabel(status) { return status === "not_found" ? "Not found" : status[0].toUpperCase() + status.slice(1); }183  function make(tag, className, text) { const element = document.createElement(tag); if (className) element.className = className; if (text !== undefined) element.textContent = text; return element; }184 185  function renderSummary(review) {186    const count = counts(review);187    summary.replaceChildren();188    const header = make("section", "result-header");189    const heading = make("div");190    heading.append(make("p", "eyebrow", "PUBLIC MODEL CARD REVIEW"), make("h2", "", review.repo));191    const link = make("a", "", "Open reviewed revision ↗"); link.href = review.sourceUrl; link.target = "_blank"; link.rel = "noopener"; heading.append(link);192    const strip = make("div", "count-strip");193    [[count.documented, "documented"], [count.review, "review"], [count.not_found, "not found"]].forEach(([number, label]) => { const entry = make("div"); entry.append(make("strong", "", number), make("span", "", label)); strip.append(entry); });194    header.append(heading, strip);195    const note = make("p", "scope-note", "A narrow result: “Not found” means the review did not locate relevant information. It is not a compliance grade or a claim of maintainer error.");196    const grid = make("section", "finding-grid");197    review.findings.forEach((finding) => { const card = make("article", `finding-card ${finding.status.replace("_", "-")}`); const top = make("div", "finding-topline"); top.append(make("h3", "", finding.label), make("span", "status-pill", statusLabel(finding.status))); card.append(top, make("p", "", finding.text), make("small", "", finding.evidence.length ? `${finding.evidence.length} source item${finding.evidence.length === 1 ? "" : "s"}` : "Maintainer input needed")); grid.append(card); });198    summary.append(header, note, grid);199  }200 201  function renderEvidence(review) {202    evidencePanel.replaceChildren();203    review.findings.forEach((finding) => { const item = make("article", "evidence-item"); item.append(make("h3", "", `${finding.label} — ${statusLabel(finding.status)}`), make("p", "", finding.text)); if (finding.evidence.length) { finding.evidence.forEach((evidence) => { const link = make("a", "", evidence.type); link.href = evidence.url; link.target = "_blank"; link.rel = "noopener"; const excerpt = make("div", "excerpt", evidence.text); item.append(link, excerpt); }); } else { item.append(make("p", "", `Question for the maintainer: ${finding.prompt}`)); } evidencePanel.append(item); });204  }205 206  function worksheet(review) {207    const unresolved = review.findings.filter((finding) => finding.status !== "documented");208    const lines = [`# Suggested model card additions for ${review.repo}`, "", "> Review worksheet—not a drop-in patch. Replace every TODO with maintainer-confirmed information.", ""];209    if (!unresolved.length) return lines.concat(["The selected checks found relevant documentation for every reviewed area.", "A human should still verify accuracy, currency, and applicability."]).join("\n");210    unresolved.forEach((finding) => lines.push(`## ${finding.label}`, "", `<!-- TODO: ${finding.prompt} -->`, ""));211    return lines.concat(["## Review notes", "", "- Confirm that every proposed addition is accurate with the maintainer.", "- Link primary datasets, evaluations, papers, and code where available.", "- Remove sections that are not applicable instead of filling them speculatively."]).join("\n");212  }213 214  function discussion(review) {215    const unresolved = review.findings.filter((finding) => finding.status !== "documented");216    const labels = unresolved.slice(0, 4).map((finding) => finding.label.toLowerCase()).join(", ");217    const observation = unresolved.length ? `While reading the public card, I could not confidently locate documentation for ${labels}${unresolved.length > 4 ? `, and ${unresolved.length - 4} other area(s)` : ""}. These may be in another source or may not apply to this model.` : "The review found relevant documentation for each checked area. I would still appreciate confirmation that the information is current.";218    return ["## Possible documentation contribution", "", `Hi—thank you for sharing \`${review.repo}\`.`, "", observation, "", "Would a small documentation contribution be useful? I would be glad to prepare one, but I do not want to infer training, evaluation, licensing, or intended-use details that only the maintainers can confirm.", "", `Card reviewed: ${review.sourceUrl}`, "", "_Drafted for human review. This message has not been posted._"].join("\n");219  }220 221  function fullReview(review, worksheetText, discussionText) {222    const count = counts(review);223    const lines = [`# One Good Commit review: ${review.repo}`, "", `- Source: ${review.sourceUrl}`, `- Revision: \`${review.revision}\``, `- Analyzed: ${review.analyzedAt}`, `- Documented: ${count.documented}`, `- Review: ${count.review}`, `- Not found: ${count.not_found}`, "", "> “Not found” means this deterministic review did not locate relevant information. It is not a claim of noncompliance, inaccuracy, or maintainer error.", "", "## Evidence", ""];224    review.findings.forEach((finding) => { lines.push(`### ${finding.label} — ${statusLabel(finding.status)}`, "", finding.text, ""); if (finding.evidence.length) finding.evidence.forEach((evidence) => lines.push(`- **${evidence.type}** ([source](${evidence.url}))`, "", `  > ${evidence.text}`, "")); else lines.push(`- Maintainer question: ${finding.prompt}`, ""); });225    return lines.concat(["---", "", worksheetText, "", "---", "", discussionText]).join("\n");226  }227 228  function showError(message) { notice.textContent = message; notice.hidden = false; results.hidden = true; }229  function clearNotice() { notice.hidden = true; notice.textContent = ""; }230 231  async function review(value) {232    let repo;233    try { repo = cleanRepoId(value); } catch (error) { showError(error.message); return; }234    clearNotice(); results.hidden = true;235    const button = form.querySelector("button"); button.disabled = true; button.textContent = "Reading public card…";236    try {237      const encoded = repo.split("/").map(encodeURIComponent).join("/");238      const apiResponse = await fetch(`https://huggingface.co/api/models/${encoded}`);239      if ([401, 403, 404].includes(apiResponse.status)) throw new Error("That model ID is not available as a public Hub repository. Check the ID or choose a public, ungated model.");240      if (!apiResponse.ok) throw new Error("The Hub API could not be reached. Try again shortly.");241      const api = await apiResponse.json();242      if (api.private || api.gated) throw new Error("That model is private or gated. This version reviews public cards only.");243      const revision = api.sha || "main";244      const cardResponse = await fetch(`https://huggingface.co/${encoded}/resolve/${encodeURIComponent(revision)}/README.md`);245      if (!cardResponse.ok) throw new Error("The repository does not expose a README.md on its selected revision.");246      const readme = await cardResponse.text();247      if (readme.length > MAX_README_BYTES) throw new Error("The model card is larger than the 2 MB review limit.");248      latestReview = analyze(repo, api, readme);249      const worksheetText = worksheet(latestReview); const discussionText = discussion(latestReview);250      renderSummary(latestReview); renderEvidence(latestReview);251      worksheetPanel.replaceChildren(make("pre", "worksheet", worksheetText));252      discussionPanel.replaceChildren(make("pre", "discussion", discussionText));253      latestReview.download = fullReview(latestReview, worksheetText, discussionText);254      results.hidden = false;255    } catch (error) { showError(error.message || "An unexpected error occurred. No contribution was created or posted."); }256    finally { button.disabled = false; button.textContent = "Review card"; }257  }258 259  form.addEventListener("submit", (event) => { event.preventDefault(); review(input.value); });260  input.addEventListener("input", () => {261    window.clearTimeout(searchTimer);262    const query = input.value.trim();263    searchTimer = window.setTimeout(() => searchModels(query), 250);264  });265  input.addEventListener("focus", () => { if (modelOptions.childElementCount) { modelOptions.hidden = false; input.setAttribute("aria-expanded", "true"); } });266  document.addEventListener("click", (event) => { if (!event.target.closest("#review-form") && !event.target.closest("#model-options")) hideModelOptions(); });267  document.querySelectorAll("[role=tab]").forEach((tab) => tab.addEventListener("click", () => { document.querySelectorAll("[role=tab]").forEach((item) => item.setAttribute("aria-selected", String(item === tab))); document.querySelectorAll("[role=tabpanel]").forEach((panel) => { panel.hidden = panel.id !== tab.dataset.tab; }); }));268  downloadButton.addEventListener("click", () => { if (!latestReview?.download) return; const blob = new Blob([latestReview.download], { type: "text/markdown;charset=utf-8" }); const link = document.createElement("a"); link.href = URL.createObjectURL(blob); link.download = `${latestReview.repo.replace("/", "--")}-review.md`; link.click(); URL.revokeObjectURL(link.href); });269  searchModels();270})();271