chaffjs 0.27.1 → 0.29.0

package/src/check-source.ts

@@ -6,7 +6,7 @@ import { limitsFor } from "./config/style.ts";
 import { rulesOf } from "./custom/load.ts";
 import { guessLanguage } from "./detect.ts";
 import { buildDocument, teamRules } from "./document.ts";
-import type { CrossDetector, ProseDocument, RuleDefinition } from "./plugin.ts";
+import type { AdapterNeeds, CrossDetector, ProseDocument, RuleDefinition } from "./plugin.ts";
 import { profileFor } from "./profile/for-file.ts";
 import { resolveGenre, type ResolvedGenre } from "./resolve-genre.ts";
 import { neededBy, runRulesWith, type RunContext, type RunResult } from "./run.ts";
@@ -33,13 +33,22 @@ export type SourceCheck = {
   readonly applied: Applied;
 };
 
+/** What the language adapter is asked to prepare for these rules under this chaff.yaml: what the running rules read, nothing more. */
+export const adapterNeedsOf = (
+  rules: readonly RuleDefinition[],
+  config: Pick<Config, "rules">,
+  experimental: boolean,
+  genre: string,
+  language: string,
+): AdapterNeeds => neededBy(rules, config.rules, experimental, genre, language);
+
 /** Lints one text as `chaff <file>` does. The file need not exist: `chaff grade` checks a model's output from memory. */
 export const checkSource = async (path: string, source: string, config: Config, choice: CheckChoice): Promise<SourceCheck> => {
   const language = choice.language ?? documentLanguage(path, source, config);
   const adapter = await loadAdapter(language);
   const genre = resolveGenre(path, source, config, choice.genre);
   const rules = rulesOf(language, config);
-  await adapter.prepare?.(neededBy(rules, config.rules, choice.experimental, genre.genre, language));
+  await adapter.prepare?.(adapterNeedsOf(rules, config, choice.experimental, genre.genre, language));
   const doc = buildDocument(path, source, adapter, teamRules(config, language), profileFor(config, path, source, language, genre.genre));
   const context: RunContext = {
     settings: config.rules,

package/src/cli-text.ts

@@ -34,25 +34,36 @@ const USAGE_JA = `chaff — 文章の読みにくいところを見つけます
   chaff init --plugin <名前>     YAML だけのルールの束（chaff-plugin-<名前>/）を作る
   chaff plugin-test [フォルダ]   プラグインの各ルールを、そのルールの例にかけて確かめる
   chaff --version                chaffjs と言語パッケージの版
-  chaff eval <dir>               手元の文書で閾値を測り直す
+  chaff eval <dir> [--rule <rule>]  手元の文書で閾値を測り直す（--rule でそのルールだけ）
   chaff explain <rule>           そのルールの意図と根拠を読む
   chaff genres                   ジャンル（文書の種類）の一覧と、それぞれ何向けか
   chaff tree <file> [--format sexp|json]  文書を番地の付いた木にする（条・項・定義・参照）
-  chaff cite <原文> <引用.json>           回答の引用（番地と引用文）が原文にあるかを確かめる
-  chaff compare <前> <後>                書き換えで事実（数・日付・URL・コード・名前・引用…）が落ちても足されてもいないかを確かめる
-  chaff facts <file>                     compare が照合する事実を、書き直す前の控えとして一覧にする
-  chaff outline <file> [<後>]            見出しの構成と形（見出しの数・節の平均の長さ・箇条書きの割合・太字）を測る。2 つなら前と後を並べる
-  chaff ai-score <file>... [--format json]  AI らしさの簡易判定（低・中・高）。生成文に多い目印を、同じジャンルの人の文書と比べる（書いたのが AI かは判定しない）
-  chaff grade <items.jsonl> [--out <results.jsonl>] [--json]
+  chaff cite <原文> <引用.json> [--format text|json]  回答の引用（番地と引用文）が原文にあるかを確かめる
+  chaff cite --scaffold <file>           出典の無い引用を、出典を書き込む引用.json のひな形にする
+  chaff cite --url <URL> <引用.json>      引用が Web のページにあるかを確かめる（取得したページは HTML から Markdown にして読む）
+  chaff compare <前> <後> [--json|--compact]  書き換えで事実（数・日付・URL・コード・名前・引用…）が落ちても足されてもいないかを確かめる
+                                 --allow-dropped <種類> と --allow-added <種類> は、その種類の欠落・追加を許す（カンマで並べる。種類は number date time url code name quote heading reference footnote）
+                                 --distinct は、何回述べたかではなく、述べているかだけを比べる
+  chaff facts <file> [--json|--compact]  compare が照合する事実を、書き直す前の控えとして一覧にする
+  chaff outline <file> [<後>] [--json|--compact]  見出しの構成と形（見出しの数・節の平均の長さ・箇条書きの割合・太字）を測る。2 つなら前と後を並べる
+  chaff ai-score <file>... [--format text|json] [--json] [--compact]
+                                 AI らしさの簡易判定（低・中・高）。生成文に多い目印を、同じジャンルの人の文書と比べる（書いたのが AI かは判定しない）
+                                 --json は --format json と同じ。--compact はファイルごとに 1 行
+  chaff grade <items.jsonl> [--out <results.jsonl>] [--baseline <前の results.jsonl>] [--allow-stamp-mismatch]
+              [--variant-key <欄>] [--format text|json|markdown] [--json] [--compact]
                                  AI の出力を JSONL でまとめて採点する（指摘の率・事実・引用・合否。何も送らない）
-  chaff fix-plan <file> [--json]         指摘をルールごとにまとめ、直す方向と確かめのコマンドを、書き直す人や AI 向けの計画にする（何も送らない）
+                                 --allow-stamp-mismatch はルールか設定が前の回と違っても比べる（そのことを先に出す）
+                                 --variant-key は variant の欄の代わりにその欄で出力を分けて並べる。--json は --format json と同じ。markdown は PR のコメント向け
+  chaff fix-plan <file> [--depth light|structure|register] [--json]
+                                 指摘をルールごとにまとめ、直す方向と確かめのコマンドを、書き直す人や AI 向けの計画にする（何も送らない）
   chaff rules                    ルールの一覧を、グループごとに表で出す（いまの段階つき）
   chaff rules --json             いまの設定とルールの説明を JSON で出す（AI に渡す用）
   chaff baseline <dir>           いまある指摘を棚上げする（既存の repo に入れるとき）
   chaff suppressions <dir>       stet で黙らせている指摘を数える
   chaff relax|strict|off <rule> [--why "理由"]
   chaff enable <rule> [--why "理由"]  試験中のルールを 1 つだけ動かす（chaff.yaml の rules に <rule>: normal と書く）
-  chaff skill [--global]         Claude Code の skill を入れる（.claude/skills/chaff/、--global で ~/.claude/）
+  chaff skill [--global] [--force]  Claude Code の skill を入れる（.claude/skills/chaff/、--global で ~/.claude/）
+                                 手で直したらしい skill は置き換えない。--force で置き換える
   chaff feedback <file> --rule <rule> [--line N] | --missed --line N
                                  誤った指摘・見逃しの報告の下書きを作る（何も送らない。--with-config で chaff.yaml 全体も載せる）
 
@@ -65,6 +76,7 @@ const USAGE_JA = `chaff — 文章の読みにくいところを見つけます
   --dry-run         test で、何を AI に送るかだけを見る（API を呼びません）
   --sarif <path>    指摘を SARIF で書き出す（GitHub の PR の行に出すため）
   --include <glob>  フォルダを見るとき、Markdown のほかにこのファイルも検査する（--include "*.yaml"。chaff.yaml の include と同じ）
+  --language <ja|en>  tree・cite・compare・facts・outline・ai-score で、文書の言語を決める（chaff.yaml と中身からの推定より優先）
 
 この箇所だけ黙らせる:  <!-- stet: rule-id — 理由 -->
 
@@ -81,25 +93,36 @@ const USAGE_EN = `chaff — finds what makes writing hard to read. It never rewr
   chaff init --plugin <name>     create a YAML rule pack, chaff-plugin-<name>/
   chaff plugin-test [folder]     run each rule of a plugin on the rule's own example
   chaff --version                the version of chaffjs and its language packages
-  chaff eval <dir>               re-measure the limits on your own documents
+  chaff eval <dir> [--rule <rule>]  re-measure the limits on your own documents (--rule: that rule only)
   chaff explain <rule>           read what a rule is for and why
   chaff genres                   list the genres (kinds of document) and what each is for
   chaff tree <file> [--format sexp|json]  the document as a tree of addresses (sections, clauses, definitions, references)
-  chaff cite <source> <quotes.json>       check that quoted passages (address and text) are in the source
-  chaff compare <before> <after>          check that a rewrite dropped no fact and added none (numbers, dates, URLs, code, names, quotations…)
-  chaff facts <file>                      list the facts compare checks, as an inventory to keep before a rewrite
-  chaff outline <file> [<after>]          measure the outline and its shape (headings, average section length, text in lists, bold); two files side by side
-  chaff ai-score <file>... [--format json]  quick AI-likeness score (low, medium, high): signs common in generated text against human documents of the genre (not a verdict on who wrote it)
-  chaff grade <items.jsonl> [--out <results.jsonl>] [--json]
+  chaff cite <source> <quotes.json> [--format text|json]  check that quoted passages (address and text) are in the source
+  chaff cite --scaffold <file>            a quotes.json to fill in with sources, from the quotations that give none
+  chaff cite --url <URL> <quotes.json>    check quotations against a web page (fetched, HTML read as Markdown)
+  chaff compare <before> <after> [--json|--compact]  check that a rewrite dropped no fact and added none (numbers, dates, URLs, code, names, quotations…)
+                                 --allow-dropped <kinds> and --allow-added <kinds> allow those kinds to go or come (comma-separated: number date time url code name quote heading reference footnote)
+                                 --distinct compares only whether a fact is stated, not how many times
+  chaff facts <file> [--json|--compact]   list the facts compare checks, as an inventory to keep before a rewrite
+  chaff outline <file> [<after>] [--json|--compact]  measure the outline and its shape (headings, average section length, text in lists, bold); two files side by side
+  chaff ai-score <file>... [--format text|json] [--json] [--compact]
+                                 quick AI-likeness score (low, medium, high): signs common in generated text against human documents of the genre (not a verdict on who wrote it)
+                                 --json is --format json; --compact prints one line per file
+  chaff grade <items.jsonl> [--out <results.jsonl>] [--baseline <earlier results.jsonl>] [--allow-stamp-mismatch]
+              [--variant-key <field>] [--format text|json|markdown] [--json] [--compact]
                                  grade a JSONL file of model outputs (finding rates, facts, quotations, pass or fail; sends nothing)
-  chaff fix-plan <file> [--json]          a plan for whoever rewrites the file, a person or an AI: findings by rule, how to rewrite each, the checks to run after (sends nothing)
+                                 --allow-stamp-mismatch compares with the baseline even when its rules or settings differ, saying so first
+                                 --variant-key splits the outputs by that field instead of variant; --json is --format json; markdown is for a PR comment
+  chaff fix-plan <file> [--depth light|structure|register] [--json]
+                                 a plan for whoever rewrites the file, a person or an AI: findings by rule, how to rewrite each, the checks to run after (sends nothing)
   chaff rules                    the rules as a table, by group, with the level each runs at now
   chaff rules --json             the current settings and what each rule is, as JSON (to give to an AI)
   chaff baseline <dir>           shelve today's findings (when adding chaff to an existing repository)
   chaff suppressions <dir>       count the findings silenced with stet
   chaff relax|strict|off <rule> [--why "reason"]
   chaff enable <rule> [--why "reason"]  turn on one experimental rule alone (writes <rule>: normal under rules in chaff.yaml)
-  chaff skill [--global]         install the Claude Code skill (.claude/skills/chaff/; --global for ~/.claude/)
+  chaff skill [--global] [--force]  install the Claude Code skill (.claude/skills/chaff/; --global for ~/.claude/)
+                                 a skill that looks edited by hand is kept; --force replaces it
   chaff feedback <file> --rule <rule> [--line N] | --missed --line N
                                  draft a report of a wrong or missed finding (sends nothing; --with-config adds all of chaff.yaml)
 
@@ -112,6 +135,7 @@ const USAGE_EN = `chaff — finds what makes writing hard to read. It never rewr
   --dry-run         with test, show what would be sent to the AI (no API call)
   --sarif <path>    write the findings as SARIF (for comments on a GitHub PR)
   --include <glob>  in a folder, check these files besides Markdown (--include "*.yaml"; as include in chaff.yaml)
+  --language <ja|en>  with tree, cite, compare, facts, outline and ai-score, the document's language (wins over chaff.yaml and the guess from the text)
 
 Silence one spot:  <!-- stet: rule-id — reason -->
 

package/src/cli.ts

@@ -50,6 +50,7 @@ import { notRunAmong } from "./not-run.ts";
 import { settingProblems } from "./setting-problems.ts";
 import { withExtensions } from "./extension/load.ts";
 import { offOnlyAsExperimental } from "./experimental-alone.ts";
+import { levelFor } from "./run.ts";
 import { DEFAULT_GENRE } from "./init-choice.ts";
 import { stoppingOnYamlFileError } from "./config/yaml-file.ts";
 
@@ -236,7 +237,7 @@ const explain = (config: Config, ruleId: string | undefined, genreFlag: string |
     return 1;
   }
   const preset = genre === undefined ? {} : presetLevels(genre);
-  const current = config.rules[rule.id] ?? preset[rule.id] ?? (rule.status === "experimental" && !config.experimental ? "off" : "normal");
+  const current = levelFor(rule, config.rules, config.experimental, preset);
   const alone = offOnlyAsExperimental(rule, config, genre ?? DEFAULT_GENRE, preset, language);
   console.log(renderExplain(rule, current, language, genre, { ...settingSourcesOf(config, rule.id, language), offOnlyAsExperimental: alone }));
   return 0;

package/src/commands/cite-claims.ts

@@ -0,0 +1,103 @@
+// The claims file `chaff cite` reads: [{ source?, address?, quote }]. Pure: the shape is checked and every problem named,
+// so a half-filled file (a scaffold with a source left empty) stops with a reason instead of passing.
+import { isAnywhere, type Citation } from "../structure/cite.ts";
+import type { Texts, UiLanguage } from "../ui.ts";
+
+/** A citation and, when the claims file names it, the source it quotes: a file path, relative to the claims file. */
+export type Claim = Citation & { readonly source?: string };
+
+export type ParsedCitations = { readonly citations: readonly Claim[] } | { readonly error: string };
+
+type RawClaim = { readonly source?: string; readonly address?: string; readonly quote: string };
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isOptionalString = (value: unknown): boolean => value === undefined || typeof value === "string";
+
+const isRawClaim = (value: unknown): value is RawClaim =>
+  isRecord(value) && isOptionalString(value["address"]) && isOptionalString(value["source"]) && typeof value["quote"] === "string";
+
+const claimOf = (raw: RawClaim): Claim => ({
+  ...(raw.source === undefined ? {} : { source: raw.source }),
+  address: raw.address ?? "",
+  quote: raw.quote,
+});
+
+/** Neither an address nor a quote: saying ✓ would pass an entry nobody filled in. */
+const isEmpty = (claim: Claim): boolean => isAnywhere(claim) && claim.quote.trim() === "";
+
+/** The source a claim names, or undefined when it names none (missing, empty or blank). */
+export const sourceOf = (claim: Claim): string | undefined => {
+  const source = claim.source?.trim() ?? "";
+  return source === "" ? undefined : source;
+};
+
+type ClaimsText = {
+  readonly notJson: (why: string) => string;
+  readonly notArray: string;
+  readonly badEntry: (n: number) => string;
+  readonly emptyEntry: (n: number) => string;
+  readonly noSource: (n: number) => string;
+  readonly twoSources: (n: number) => string;
+};
+
+export const CLAIMS_TEXT: Texts<ClaimsText> = {
+  ja: {
+    notJson: (why) => `JSON として読めません: ${why}`,
+    notArray: '引用は配列で渡してください: [{ "address": "3.2", "quote": "…" }]',
+    badEntry: (n) => `${String(n)} 件目に quote（文字列）が無いか、address か source が文字列ではありません`,
+    emptyEntry: (n) => `${String(n)} 件目は address も quote も空で、確かめることがありません`,
+    noSource: (n) => `${String(n)} 件目に source がありません。原文を引数で渡さないときは、どの引用にも source（原文のファイル）を書いてください`,
+    twoSources: (n) => `${String(n)} 件目が source を書いていますが、原文も引数で渡されています。どちらか一方にしてください`,
+  },
+  en: {
+    notJson: (why) => `Not valid JSON: ${why}`,
+    notArray: 'Give the quotations as an array: [{ "address": "3.2", "quote": "…" }]',
+    badEntry: (n) => `Entry ${String(n)} needs quote (a string), and its address and source, if it has them, must be strings`,
+    emptyEntry: (n) => `Entry ${String(n)} has neither an address nor a quote, so there is nothing to check`,
+    noSource: (n) => `Entry ${String(n)} has no source. Without a source on the command line, every quotation needs one (the source's file)`,
+    twoSources: (n) => `Entry ${String(n)} names a source, and a source was also given on the command line. Give one or the other`,
+  },
+};
+
+const parseJson = (text: string, ui: UiLanguage): { readonly value: unknown } | { readonly error: string } => {
+  try {
+    return { value: JSON.parse(text) };
+  } catch (err) {
+    return { error: CLAIMS_TEXT[ui].notJson(err instanceof Error ? err.message : String(err)) };
+  }
+};
+
+/** 引用の一覧。[{ source?, address?, quote }] の配列だけを受け取る。address を省けば原文のどこか。形が違えば理由を返す。 */
+export const parseCitations = (text: string, ui: UiLanguage = "ja"): ParsedCitations => {
+  const parsed = parseJson(text, ui);
+  if ("error" in parsed) return parsed;
+  if (!Array.isArray(parsed.value)) return { error: CLAIMS_TEXT[ui].notArray };
+  const entries: readonly unknown[] = parsed.value;
+  const bad = entries.findIndex((entry) => !isRawClaim(entry));
+  if (bad !== -1) return { error: CLAIMS_TEXT[ui].badEntry(bad + 1) };
+  const citations = entries.filter(isRawClaim).map(claimOf);
+  const empty = citations.findIndex(isEmpty);
+  if (empty !== -1) return { error: CLAIMS_TEXT[ui].emptyEntry(empty + 1) };
+  return { citations };
+};
+
+/**
+ * Where each claim's source comes from. With a source on the command line, no claim may name its own; without one,
+ * every claim must. undefined when the claims agree with how cite was called, otherwise the reason.
+ */
+export const sourceProblem = (claims: readonly Claim[], sourceGiven: boolean, ui: UiLanguage): string | undefined => {
+  const at = claims.findIndex((claim) => (sourceOf(claim) === undefined) !== sourceGiven);
+  if (at === -1) return undefined;
+  return sourceGiven ? CLAIMS_TEXT[ui].twoSources(at + 1) : CLAIMS_TEXT[ui].noSource(at + 1);
+};
+
+/** The claims of each source, in the order the sources first appear. Every claim names its source (sourceProblem passed). */
+export const bySource = (claims: readonly Claim[]): { readonly source: string; readonly claims: readonly Claim[] }[] => {
+  const groups = new Map<string, Claim[]>();
+  claims.forEach((claim) => {
+    const source = sourceOf(claim) ?? "";
+    groups.set(source, [...(groups.get(source) ?? []), claim]);
+  });
+  return [...groups].map(([source, own]) => ({ source, claims: own }));
+};

package/src/commands/cite-page.ts

@@ -0,0 +1,61 @@
+import { fetchPage, type Fetcher } from "../html/fetch-page.ts";
+import { pageDocument } from "../html/page-document.ts";
+import { resolveGenre } from "../resolve-genre.ts";
+import { treeFromSource, treeLanguage, type SourceTree, type TreeContext } from "./tree.ts";
+import type { Texts } from "../ui.ts";
+
+/** A source on the web: read once, then checked like a file. The network is reached only through fetchPage. */
+export type CiteContext = TreeContext & {
+  /** What fetches a page. Tests pass a stand-in; the command line never does. */
+  readonly fetcher?: Fetcher;
+};
+
+/** Long enough for a slow page, short enough that a dead host does not hold up a run of checks. */
+const PAGE_TIMEOUT_MS = 30_000;
+
+/** Far beyond any article or statute page; a log or a dump served as text is refused instead of read whole. */
+const MAX_PAGE_BYTES = 20 * 1024 * 1024;
+
+const WEB = /^https?:\/\//iu;
+
+export const isWebSource = (source: string): boolean => WEB.test(source);
+
+const TEXT: Texts<{
+  readonly unfetched: (why: string) => string;
+  readonly unsupported: (url: string, type: string) => string;
+  readonly noStructure: (url: string, language: string) => string;
+}> = {
+  ja: {
+    unfetched: (why) => `ページを取得できませんでした: ${why}`,
+    unsupported: (url, type) => `${url}: ${type} は文字の文書として読めません（HTML、Markdown、テキストのページを渡してください）`,
+    noStructure: (url, language) => `${url}: 言語 ${language} のパッケージは文書の構造を読めません（structure がありません）`,
+  },
+  en: {
+    unfetched: (why) => `Could not fetch the page: ${why}`,
+    unsupported: (url, type) => `${url}: ${type} cannot be read as a text document (give an HTML, Markdown or plain-text page)`,
+    noStructure: (url, language) => `${url}: the ${language} package cannot read a document's structure (it has no structure)`,
+  },
+};
+
+/**
+ * A web page as a tree, read as `chaff tree` reads a file: HTML becomes Markdown first, so its headings are addresses.
+ * Once fetched, the same page gives the same tree. undefined, after saying why, when it cannot be fetched or read.
+ */
+export const readPageTree = async (url: string, argv: readonly string[], context: CiteContext): Promise<SourceTree | undefined> => {
+  const text = TEXT[context.ui ?? "ja"];
+  const fetched = await fetchPage(url, { timeout_ms: PAGE_TIMEOUT_MS, max_bytes: MAX_PAGE_BYTES }, context.fetcher).catch((err: unknown) => {
+    console.error(text.unfetched(err instanceof Error ? err.message : String(err)));
+    return undefined;
+  });
+  if (fetched === undefined) return undefined;
+  const page = pageDocument(fetched.contentType, fetched.text);
+  if ("unsupported" in page) {
+    console.error(text.unsupported(url, page.unsupported));
+    return undefined;
+  }
+  const language = treeLanguage(page.path, page.text, argv, context);
+  const genre = resolveGenre(page.path, page.text, context.config, context.flag(argv, "--genre")).genre;
+  const tree = await treeFromSource(page.path, page.text, language, genre, context.config);
+  if (tree === undefined) console.error(text.noStructure(url, language));
+  return tree === undefined ? undefined : { source: page.text, tree };
+};

package/src/commands/cite-scaffold.ts

@@ -0,0 +1,27 @@
+import { documentQuotesWithoutSource } from "../detectors/quote-without-source.ts";
+import type { ProseDocument } from "../plugin.ts";
+import { readDocument } from "./read-document.ts";
+import type { TreeContext } from "./tree.ts";
+
+/** One entry of the claims file the writer fills in: the source the words come from, and where in it (empty: anywhere). */
+export type ScaffoldClaim = { readonly source: string; readonly address: string; readonly quote: string };
+
+/**
+ * The quotations quote-without-source finds in a document, as cite's claims with the source and address left for the
+ * writer. The rule's genre and level do not apply: asking for a scaffold is asking for every such quotation.
+ */
+export const scaffoldClaims = (doc: ProseDocument): ScaffoldClaim[] =>
+  documentQuotesWithoutSource(doc).map((found) => ({ source: "", address: "", quote: found.quote }));
+
+/** Prints the claims file for one document. The writer fills in each source and runs `chaff cite <claims.json>`. */
+export const runScaffold = async (targets: readonly string[], argv: readonly string[], context: TreeContext, usage: string): Promise<number> => {
+  const [path] = targets;
+  if (path === undefined || targets.length !== 1) {
+    console.error(usage);
+    return 1;
+  }
+  const read = await readDocument(path, argv, context, false);
+  if (read === undefined) return 1;
+  console.log(JSON.stringify(scaffoldClaims(read.doc), null, 2));
+  return 0;
+};

package/src/commands/cite.ts

@@ -1,55 +1,39 @@
-import { checkCitations, type Citation, type CitationResult } from "../structure/cite.ts";
+import { dirname, isAbsolute, join } from "node:path";
+import { checkCitations, isAnywhere, type CitationResult } from "../structure/cite.ts";
+import { bySource, parseCitations, sourceOf, sourceProblem, type Claim } from "./cite-claims.ts";
+import { runScaffold } from "./cite-scaffold.ts";
+import { isWebSource, readPageTree, type CiteContext } from "./cite-page.ts";
 import { readSource, readTree, type TreeContext } from "./tree.ts";
-import type { Texts, UiLanguage } from "../ui.ts";
+import type { Texts } from "../ui.ts";
 
 const FORMATS: ReadonlySet<string> = new Set(["text", "json"]);
 const QUOTE_WIDTH = 40;
-const VALUED: ReadonlySet<string> = new Set(["--format", "--language", "--genre"]);
+const VALUED: ReadonlySet<string> = new Set(["--format", "--language", "--genre", "--url"]);
 
 export const citeTargets = (argv: readonly string[]): string[] =>
   argv.slice(1).filter((arg, index, all) => !arg.startsWith("--") && !VALUED.has(all[index - 1] ?? ""));
 
-const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
-
-const isCitation = (value: unknown): value is Citation => isRecord(value) && typeof value["address"] === "string" && typeof value["quote"] === "string";
-
-export type ParsedCitations = { readonly citations: readonly Citation[] } | { readonly error: string };
-
-const parseJson = (text: string, ui: UiLanguage): { readonly value: unknown } | { readonly error: string } => {
-  try {
-    return { value: JSON.parse(text) };
-  } catch (err) {
-    return { error: TEXT[ui].notJson(err instanceof Error ? err.message : String(err)) };
-  }
-};
-
-/** 引用の一覧。[{ address, quote }] の配列だけを受け取る。形が違えば理由を返す。 */
-export const parseCitations = (text: string, ui: UiLanguage = "ja"): ParsedCitations => {
-  const parsed = parseJson(text, ui);
-  if ("error" in parsed) return parsed;
-  if (!Array.isArray(parsed.value)) return { error: TEXT[ui].notArray };
-  const entries: readonly unknown[] = parsed.value;
-  const bad = entries.findIndex((entry) => !isCitation(entry));
-  if (bad !== -1) return { error: TEXT[ui].badEntry(bad + 1) };
-  return { citations: entries.filter(isCitation).map((entry) => ({ address: entry.address, quote: entry.quote })) };
-};
-
 type CiteText = {
   readonly usage: string;
   readonly quoted: (text: string) => string;
-  readonly notJson: (why: string) => string;
-  readonly notArray: string;
-  readonly badEntry: (n: number) => string;
+  readonly anywhere: string;
+  readonly foundAt: (parts: readonly string[]) => string;
+  readonly line: (line: number) => string;
   readonly results: Readonly<Record<CitationResult["status"], (result: CitationResult) => string>>;
 };
 
 const TEXT: Texts<CiteText> = {
   ja: {
     quoted: (text) => `「${text}」`,
-    usage: "使い方: chaff cite <原文> <引用.json> [--format text|json] [--language ja|en|…]",
-    notJson: (why) => `JSON として読めません: ${why}`,
-    notArray: '引用は配列で渡してください: [{ "address": "3.2", "quote": "…" }]',
-    badEntry: (n) => `${String(n)} 件目に address（文字列）と quote（文字列）がありません`,
+    usage: [
+      "使い方: chaff cite <原文> <引用.json> [--format text|json] [--language ja|en|…]",
+      "        chaff cite --url <URL> <引用.json> （原文が Web のページのとき）",
+      "        chaff cite <引用.json>            （引用ごとに source で原文のファイルか URL を書いたとき）",
+      "        chaff cite --scaffold <文書>      （出典の無い引用から引用.json のひな形を作る）",
+    ].join("\n"),
+    anywhere: "（番地なし）",
+    foundAt: (parts) => `（${parts.join("、")}）`,
+    line: (line) => `${String(line)} 行目`,
     results: {
       ok: () => "一致",
       "missing-address": (result) => `番地 ${result.citation.address} は原文にありません`,
@@ -60,10 +44,15 @@ const TEXT: Texts<CiteText> = {
   },
   en: {
     quoted: (text) => ` "${text}"`,
-    usage: "usage: chaff cite <source> <quotes.json> [--format text|json] [--language ja|en|…]",
-    notJson: (why) => `Not valid JSON: ${why}`,
-    notArray: 'Give the quotations as an array: [{ "address": "3.2", "quote": "…" }]',
-    badEntry: (n) => `Entry ${String(n)} needs address (a string) and quote (a string)`,
+    usage: [
+      "usage: chaff cite <source> <quotes.json> [--format text|json] [--language ja|en|…]",
+      "       chaff cite --url <URL> <quotes.json> (the source is a web page)",
+      "       chaff cite <quotes.json>             (each quotation names its source, a file or a URL)",
+      "       chaff cite --scaffold <document>     (a quotes.json to fill in, from the quotations with no source)",
+    ].join("\n"),
+    anywhere: "(anywhere)",
+    foundAt: (parts) => ` (${parts.join(", ")})`,
+    line: (line) => `line ${String(line)}`,
     results: {
       ok: () => "matches",
       "missing-address": (result) => `address ${result.citation.address} is not in the source`,
@@ -74,34 +63,114 @@ const TEXT: Texts<CiteText> = {
   },
 };
 
+/** Where a quote given no address was found, so the reader can write the address in. */
+const whereFound = (result: CitationResult, text: CiteText): string => {
+  if (result.status !== "ok" || !isAnywhere(result.citation) || result.line === undefined) return "";
+  return text.foundAt([...(result.foundAt === undefined ? [] : [result.foundAt]), text.line(result.line)]);
+};
+
+/** A claim that names its own source says which, before its address. */
+const sourcePrefix = (result: CitationResult): string => {
+  const source = sourceOf(result.citation);
+  return source === undefined ? "" : `${source} `;
+};
+
 const describe = (result: CitationResult, text: CiteText): string => {
   const mark = result.status === "ok" ? "✓" : "✗";
   const oneLine = result.citation.quote.replace(/\s+/gu, " ").trim();
   const quote = oneLine.length > QUOTE_WIDTH ? `${oneLine.slice(0, QUOTE_WIDTH)}…` : oneLine;
-  return `${mark} ${result.citation.address}${text.quoted(quote)}: ${text.results[result.status](result)}`;
+  const address = isAnywhere(result.citation) ? text.anywhere : result.citation.address;
+  return `${mark} ${sourcePrefix(result)}${address}${text.quoted(quote)}: ${text.results[result.status](result)}${whereFound(result, text)}`;
+};
+
+/** Each claim checked against one source, a file or a web page. undefined when it cannot be read as a tree (already said why). */
+const checkAgainst = async (
+  location: string,
+  claims: readonly Claim[],
+  argv: readonly string[],
+  context: CiteContext,
+): Promise<CitationResult[] | undefined> => {
+  const read = isWebSource(location) ? await readPageTree(location, argv, context) : await readTree(location, argv, context);
+  return read === undefined ? undefined : checkCitations(read.source, read.tree, claims);
+};
+
+/** A claim's source, read from where the claims file is: a scaffold sits next to the document that quotes. A URL is a URL. */
+const sourcePath = (claimsPath: string, source: string): string => {
+  if (isWebSource(source)) return source;
+  // A claims file written on Windows says sources\talk.md; it names the same file everywhere.
+  const portable = source.replaceAll("\\", "/");
+  return isAbsolute(portable) ? portable : join(dirname(claimsPath), portable);
+};
+
+/**
+ * Each claim checked against the source it names, in the claims file's order. Sources are read one at a time, so what
+ * an unreadable one prints comes in the same order every run; any unreadable source fails the run.
+ */
+const checkEachSource = async (
+  claimsPath: string,
+  claims: readonly Claim[],
+  argv: readonly string[],
+  context: CiteContext,
+): Promise<CitationResult[] | undefined> => {
+  const groups = bySource(claims);
+  const checked = await groups.reduce<Promise<(CitationResult[] | undefined)[]>>(async (previous, group) => {
+    const done = await previous;
+    return [...done, await checkAgainst(sourcePath(claimsPath, group.source), group.claims, argv, context)];
+  }, Promise.resolve([]));
+  const byClaim = new Map<Claim, CitationResult>();
+  const unread = groups.some((group, index) => {
+    const results = checked[index];
+    results?.forEach((result, at) => byClaim.set(group.claims[at] ?? result.citation, result));
+    return results === undefined;
+  });
+  return unread ? undefined : claims.flatMap((claim) => byClaim.get(claim) ?? []);
+};
+
+const readClaims = async (claimsPath: string, sourceGiven: boolean, context: TreeContext): Promise<readonly Claim[] | undefined> => {
+  const text = await readSource(claimsPath, context);
+  if (text === undefined) return undefined;
+  const ui = context.ui ?? "ja";
+  const parsed = parseCitations(text, ui);
+  const problem = "error" in parsed ? parsed.error : sourceProblem(parsed.citations, sourceGiven, ui);
+  if (problem === undefined && "citations" in parsed) return parsed.citations;
+  console.error(`${claimsPath}: ${problem ?? ""}`);
+  return undefined;
+};
+
+const usageError = (text: CiteText): number => {
+  console.error(text.usage);
+  return 1;
+};
+
+/** The claims file, and the one source the command line gives (a file, or a page after --url), if any. */
+type Run = { readonly claimsPath: string; readonly sourceGiven: string | undefined };
+
+/** What the arguments ask to check, or undefined when they do not fit any usage. */
+const runOf = (targets: readonly string[], argv: readonly string[], context: CiteContext): Run | undefined => {
+  const url = context.flag(argv, "--url");
+  if (argv.includes("--url") && (url === undefined || !isWebSource(url))) return undefined;
+  const claimsPath = targets.at(-1);
+  if (claimsPath === undefined || targets.length > (url === undefined ? 2 : 1)) return undefined;
+  return { claimsPath, sourceGiven: url ?? (targets.length === 2 ? targets[0] : undefined) };
 };
 
 /**
- * 回答の引用が原文にあるかを確かめる。書き換えはしない。
+ * 回答の引用が原文にあるかを確かめる。書き換えはしない。原文は引数で一つ渡すか、引用ごとに source で書く。
  * 一つでも外れていれば 1 で終わるので、AI の回答を単体試験のように検査できる。
  */
-export const runCite = async (targets: readonly string[], argv: readonly string[], context: TreeContext): Promise<number> => {
-  const [sourcePath, citationsPath] = targets;
+export const runCite = async (targets: readonly string[], argv: readonly string[], context: CiteContext): Promise<number> => {
+  const text = TEXT[context.ui ?? "ja"];
   const format = context.flag(argv, "--format") ?? "text";
-  if (sourcePath === undefined || citationsPath === undefined || targets.length !== 2 || !FORMATS.has(format)) {
-    console.error(TEXT[context.ui ?? "ja"].usage);
-    return 1;
-  }
-  const citationsText = await readSource(citationsPath, context);
-  if (citationsText === undefined) return 1;
-  const parsed = parseCitations(citationsText, context.ui ?? "ja");
-  if ("error" in parsed) {
-    console.error(`${citationsPath}: ${parsed.error}`);
-    return 1;
-  }
-  const read = await readTree(sourcePath, argv, context);
-  if (read === undefined) return 1;
-  const results = checkCitations(read.source, read.tree, parsed.citations);
-  console.log(format === "json" ? JSON.stringify(results, null, 2) : results.map((result) => describe(result, TEXT[context.ui ?? "ja"])).join("\n"));
+  if (!FORMATS.has(format)) return usageError(text);
+  // The scaffold is always JSON: it is a file to fill in.
+  if (argv.includes("--scaffold")) return argv.includes("--url") ? usageError(text) : runScaffold(targets, argv, context, text.usage);
+  const run = runOf(targets, argv, context);
+  if (run === undefined) return usageError(text);
+  const { claimsPath, sourceGiven } = run;
+  const claims = await readClaims(claimsPath, sourceGiven !== undefined, context);
+  if (claims === undefined) return 1;
+  const results = sourceGiven === undefined ? await checkEachSource(claimsPath, claims, argv, context) : await checkAgainst(sourceGiven, claims, argv, context);
+  if (results === undefined) return 1;
+  console.log(format === "json" ? JSON.stringify(results, null, 2) : results.map((result) => describe(result, text)).join("\n"));
   return results.every((result) => result.status === "ok") ? 0 : 1;
 };