import { readFile } from 'node:fs/promises'
import { basename, relative } from 'node:path'
import { BARE_NAME, IGNORE_MARKER } from '@/context/citations'
import type { AuditedFolder } from '@/context/folders'
import type { NarrationTerms } from '@/context/narration'
import { type BodyLine, bodyLines, maskDisplayed } from '@/markdown/scan'
import { renderedHeight } from '@/markdown/structure'
import { isStubSeed } from '@/seed-marker'

/**
 * Checkpoint quoted from the standard stating it. It is not a cap.
 *
 * Entry length rests on one entry per domain, which is a domain fact, so
 * `standards/context.md` keeps it. Depth and bullet weight read the same over
 * any markdown file, so they are stated at the attribute tier and measured by
 * `aitk markdown audit` rather than here.
 */
/**
 * Every reason `aitk context audit` refuses for.
 *
 * `no-folders` is the one ordinary absence: a project that never adopted
 * `.claude/context/`, `.claude/diagrams/`, or `.claude/wireframes/` names no
 * corpus this audit can measure, the same state `no-skills` reads for the
 * skill corpora. The other four are a malformed invocation or a checkout git
 * cannot read, which stay a break rather than an absence.
 */
export type ContextAuditRefusal =
  | 'conflicting-options'
  | 'bad-folder-list'
  | 'no-folders'
  | 'no-citation-scope'
  | 'no-git'

export const LENGTH_CHECKPOINT = 150

/**
 * A table this size or larger whose first column mostly names artifacts reads
 * as a catalog that grows a row per shipped thing, which is the shape the
 * standard routes to a bullet list. Below it, a table is small enough that a
 * reflow rewrites little.
 */
export const CATALOG_ROW_CHECKPOINT = 6

/** Share of first cells that must name an artifact for a table to qualify. */
const CATALOG_NAMED_RATIO = 0.6

/**
 * Sections `standards/context.md` marks required, in the order it states them.
 *
 * The list is held here rather than read out of the standard, the way the four
 * checkpoints above quote their numbers. A parser over the standard's prose
 * would decide which sections are required from the wording around them, so it
 * fails on a rewrite of that wording rather than on a defect in an entry.
 *
 * These names do not generalize the way a length threshold does, which is why
 * the measure is scoped to the folder `governsContent` names. A diagram entry
 * declares a heading per kind and a wireframe entry per screen, and neither
 * sibling standard states a required section at all.
 */
export const REQUIRED_SECTIONS: readonly string[] = ['Overview', 'Layout']

const HEADING_TEXT = /^#{1,6}\s+(.+?)\s*$/
const TABLE_ROW = /^\s*\|/
const TABLE_SEPARATOR = /^\s*\|[\s:|-]+\|\s*$/
const NAMED_CELL = /`[^`]+`|\[[^\]]+\]\([^)]+\)/

const TOP_BULLET = /^-\s+(.+)$/
/** Any indented line, which is a nested bullet or a wrapped continuation. */
const INSIDE_LIST = /^\s+\S/

/**
 * Spellings of how the domain reached its shape rather than what it is now.
 *
 * The standard admits a rejected alternative and its reasoning while refusing
 * the provenance attached to it, and these three are what a session reaches for
 * when it records the second: when a change landed, which change carried it,
 * and which release labelled it. A marker is a judgment rather than a defect,
 * so this is measured and reported and never gates.
 *
 * The release pattern accepts three segments without a leading `v`, since the
 * standard cuts a release label rather than a spelling of one and `a CLI at
 * 0.83.0` names a release exactly as `v0.83.0` does. Two segments still require
 * the `v`, because an unprefixed pair is a dollar cost or a duration far more
 * often than a release in a corpus that records what its own runs cost. What
 * the widening reaches by accident is another tool's version, which the
 * standard asks nobody to cut, and those report rather than being excluded:
 * an exclusion keyed on a nearby tool name goes stale with nothing saying so.
 */
const PROVENANCE: readonly { kind: ProvenanceKind; pattern: RegExp }[] = [
  { kind: 'date', pattern: /\b\d{4}-\d{2}-\d{2}\b/g },
  { kind: 'change', pattern: /#\d{3,}\b/g },
  { kind: 'release', pattern: /\b(?:v\d+\.\d+(?:\.\d+)?|\d+\.\d+\.\d+)\b/g },
]

/**
 * Verbs that read the date behind them as stamping a measurement.
 *
 * `standards/context.md` cuts a date attached to a change and permits one
 * stamping a measurement, so a pattern matching every ISO date reports against
 * a rule that admits half of what it finds. Separating the two needs the clause
 * rather than the token, since `measured on 2026-08-19` and `overturned on
 * 2026-08-19` differ only in the verb.
 *
 * These five are unambiguous wherever they appear in the clause, which is what
 * lets them match at any distance from the date. `Measured across the corpus on
 * 2026-08-14` puts four words between the two, and no line in the corpus uses
 * any of them as a noun a change date could attach to.
 *
 * The set is closed and drawn from what the corpus already writes, so a
 * phrasing nobody enumerated goes unmatched. That direction is the safe one: an
 * unmatched date falls back to the change marker it is today, which reports one
 * date too many rather than clearing one the standard cuts. Widening the set is
 * how a missed phrasing is fixed, and a date the clause cannot place is never a
 * third state, because the length finding already spends `unanswered` on the
 * two questions nothing measures at all.
 */
const STAMPING = /\b(?:measured|verified|driven|passed|fired)\b/i

/**
 * The noun form, which has to sit against the date to count.
 *
 * `A run on 2026-08-14` stamps a measurement and `Runs on #632 and #634 landed
 * 2026-08-02` dates a change, and the two differ only in what follows the noun.
 * Requiring the connector and then the date immediately is what separates them,
 * so this is anchored to the end of the clause where `STAMPING` is not.
 */
const STAMPING_RUN = /\b(?:an?\s+)?runs?\s+(?:on|at|in)\s+$/i

/** Sentence boundary, so a clause is read rather than the whole line. */
const SENTENCE_END = /[.!?:;]\s(?=[^.!?:;]*$)/

/**
 * The folder whose standard carries the exclusion above.
 *
 * Three measures narrow here rather than one: provenance, the required
 * sections, and the superseded-decision narration. The name is the first of
 * them because it was the first, and it stays because renaming a constant the
 * JSON record publishes as `checkpoints.provenanceFolder` breaks every consumer
 * reading that field for a gain of one word.
 *
 * `standards/context.md` opens its scope by handing diagrams and wireframes to
 * `diagrams.md` and `wireframes.md`, so a marker reported in either would cite
 * a rule that entry's own standard routes elsewhere. The length and table
 * checkpoints are quoted from the same standard and keep reaching every audited
 * folder, because a threshold on how far a reader travels generalizes across
 * entry types while a rule about what an entry may say does not.
 *
 * What gates here is a rule only this standard states. Bullet weight does not,
 * since `standards/markdown.md` owns that checkpoint across document types and
 * its remedy sends the overflow to prose, which any entry type can act on.
 * `standards/context.md` specializes that remedy for an entry carrying
 * decisions, and specializing a rule narrows the advice rather than the measure.
 *
 * Restating the exclusion in the sibling standards was the alternative for what
 * gates here. It duplicates one knowledge item across three surfaces, which the
 * root instruction file forbids, and pointing is not available because the
 * surface they would point at is the one disclaiming them.
 */
export const PROVENANCE_FOLDER = 'context'

export type ProvenanceKind = 'date' | 'change' | 'release'

export interface TableFinding {
  readonly line: number
  readonly rows: number
}

export interface ProvenanceFinding {
  readonly line: number
  readonly kind: ProvenanceKind
  /** The marker as written, so a report names what to go and look at. */
  readonly text: string
}

export interface BareReferenceFinding {
  readonly line: number
  /** The name as written, so a report says which reference to respell. */
  readonly name: string
}

export interface NarrationFinding {
  readonly line: number
  /** The opening that points back at the bullet above. */
  readonly pronoun: string
  /** The past-tense verb that turns the back-reference into a narration. */
  readonly verb: string
}

export interface EntryReport {
  readonly rel: string
  /**
   * Rendered lines across the whole file, counting frontmatter and fenced
   * blocks. It shares `renderedHeight` with the depth checkpoint in
   * `src/markdown/structure.ts`, since the two sit in one section of the
   * standard and a reader compares them.
   *
   * Fences are counted here and excluded there. The depth measure skips one so
   * an example cannot break the run around it, and a file measure has no run to
   * protect. Excluding them here would change which entries report by one and
   * would not reach the case that motivates it: the most fenced entry in the
   * corpus runs 20 percent fenced and sits past the checkpoint either way.
   */
  readonly lines: number
  readonly catalogTables: readonly TableFinding[]
  /** Empty for an entry no standard bans a change narrative in. */
  readonly provenance: readonly ProvenanceFinding[]
  /**
   * Empty outside the governed folder, and empty on a run whose caller loaded
   * no term sets. The report distinguishes the two from the vocabulary itself,
   * since an empty list here is silent about which one produced it.
   */
  readonly narration: readonly NarrationFinding[]
  /**
   * References naming a sibling entry by bare filename, and empty for a caller
   * that passed no sibling names. Which entries have siblings worth matching is
   * the caller's judgment, stated where it builds the list.
   */
  readonly bareReferences: readonly BareReferenceFinding[]
  /**
   * Required sections this entry declares, in the standard's order, and empty
   * outside the folder whose standard names them. What the folder is short of
   * is `missingSections`, since one entry answers for its siblings.
   */
  readonly sections: readonly string[]
  /**
   * Whether the file declares itself a skeleton, which excludes it from the
   * section check alone. Every other measure still reads it, since a stub is
   * exempt from owing sections rather than from being well formed.
   */
  readonly stub: boolean
  /**
   * Whether a content rule reached this entry, which is what parts an empty
   * `provenance` list that was measured from one that was never scanned. The
   * length finding reads it, since reporting a clean history for an entry
   * outside the governed folder answers a question nothing asked.
   */
  readonly governed: boolean
}

/**
 * The three questions `standards/context.md` asks of an entry past the
 * checkpoint, in the order it states them.
 *
 * The standard calls no entry over the checkpoint wrong. It asks whether the
 * entry still covers a single domain, whether it has filled with content `ls`
 * or `--help` reproduces, and whether it has accumulated the history of its own
 * changes, then directs a fix at whichever is true. A report naming the count
 * alone leaves all three unasked, which is why the finding carries them.
 */
export type LengthQuestion = 'domain' | 'reproduced' | 'history'

/**
 * What the audit can say about one question for one entry.
 *
 * `unanswered` is a state rather than an omission. Two of the three questions
 * are judgments no measure settles, and dropping them would read as an entry
 * nothing found rather than one nothing checked.
 */
export type QuestionState = 'yes' | 'no' | 'unanswered'

export interface LengthCause {
  readonly question: LengthQuestion
  readonly state: QuestionState
  /**
   * Change markers behind a `yes`, and absent wherever nothing was counted. It
   * cites the provenance finding rather than restating it, so the two sections
   * of the report describe the same measurement once. A date stamping a
   * measurement never reaches that list, so an entry whose only dates are
   * measurement anchors answers `no` here.
   */
  readonly markers?: number
}

export interface LengthFinding {
  readonly rel: string
  readonly lines: number
  /** One entry per question in `LengthQuestion` order, never empty. */
  readonly causes: readonly LengthCause[]
}

export interface SectionFinding {
  /**
   * Repo-relative path of whatever owes the sections: the entry itself in the
   * folder named under `.claude/`, and the folder in a domain split across
   * one, since the split folder's entries answer for each other.
   */
  readonly rel: string
  /** Required sections the path above does not declare, never empty. */
  readonly missing: readonly string[]
}

function firstCell(row: string): string {
  return row.split('|').slice(1)[0] ?? ''
}

/**
 * Finds the tables whose rows name shipped artifacts.
 *
 * A bare table count reports mostly fixed comparison tables, where a reflow
 * costs nothing because no row is ever added. The reflow problem belongs to a
 * catalog that gains a row per artifact, and a first column carrying a path,
 * command, or link is what separates the two without reading the prose.
 */
function catalogTables(entry: readonly BodyLine[]): TableFinding[] {
  const findings: TableFinding[] = []
  const lines = entry.filter((line) => !line.fenced)
  let index = 0

  while (index < lines.length) {
    const line = lines[index]

    if (!TABLE_ROW.test(line.text)) {
      index++
      continue
    }

    const separator = lines[index + 1]
    if (!separator || !TABLE_SEPARATOR.test(separator.text)) {
      index++
      continue
    }

    const body: BodyLine[] = []
    let cursor = index + 2
    while (cursor < lines.length && TABLE_ROW.test(lines[cursor].text)) {
      body.push(lines[cursor])
      cursor++
    }

    const named = body.filter((row) => NAMED_CELL.test(firstCell(row.text)))
    if (
      body.length >= CATALOG_ROW_CHECKPOINT &&
      named.length / body.length >= CATALOG_NAMED_RATIO
    ) {
      findings.push({ line: line.number, rows: body.length })
    }

    index = cursor
  }

  return findings
}

/**
 * Finds the markers narrating a change rather than describing the domain.
 *
 * Fenced blocks are skipped for the same reason the table scan skips them: a
 * sample command or a fixture inside an example is content the entry displays
 * rather than a claim it makes, and a version pinned in an install line is the
 * ordinary shape of one.
 *
 * A date stamping a measurement is dropped rather than reported under a kind of
 * its own. One list with one meaning is what lets every consumer read it
 * without filtering: the report names what the standard cuts, and the length
 * finding counts the same thing. A separate kind would put the split in three
 * places and leave each free to read it differently.
 */
function provenance(lines: readonly BodyLine[]): ProvenanceFinding[] {
  // Scanning one pattern at a time emits a line's markers grouped by kind, so
  // the column is carried out of the match and sorted on. Without it a line
  // holding a date and two change numbers reports them in an order the reader
  // cannot find by scanning left to right.
  const found: { finding: ProvenanceFinding; column: number }[] = []

  for (const line of lines) {
    if (line.fenced) continue

    for (const { kind, pattern } of PROVENANCE) {
      for (const match of line.text.matchAll(pattern)) {
        if (kind === 'date' && stampsMeasurement(line.text, match.index)) {
          continue
        }

        found.push({
          finding: { line: line.number, kind, text: match[0] },
          column: match.index,
        })
      }
    }
  }

  return found
    .sort((a, b) => a.finding.line - b.finding.line || a.column - b.column)
    .map((each) => each.finding)
}

/**
 * Reads the clause in front of a date for a verb that stamps a measurement.
 *
 * The clause rather than the line, because a sentence recording a measurement
 * and a later one dating a change sit side by side often enough that a
 * line-wide read would clear the second from the first. A date opening its own
 * line has no clause in front of it and stays a change marker, which is the
 * fallback rather than a separate answer.
 */
function stampsMeasurement(text: string, index: number): boolean {
  const before = text.slice(0, index)
  const boundary = before.search(SENTENCE_END)
  const clause = boundary === -1 ? before : before.slice(boundary + 1)

  return STAMPING.test(clause) || STAMPING_RUN.test(clause)
}

function escape(term: string): string {
  return term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
}

/**
 * Copulas that turn the verb behind them into a present-tense passive.
 *
 * `used to` is the term this exists for, since `is used to resolve the folder`
 * is the passive of `use` rather than the past habitual the set means. This
 * list is English grammar rather than corpus vocabulary, so it stays in code
 * while the two tunable sets stay in the rule, and a rule publishing two of
 * three headings would be a fourth absent state to carry for no tuning anyone
 * wants.
 *
 * What it costs is the perfect passive. `has been superseded` narrates a
 * supersession and is rejected with the rest, which is a recall gap taken
 * knowingly on the trade this check already makes everywhere else.
 */
const COPULA = ['is', 'are', 'be', 'been', 'being', 'was', 'were']

/**
 * Finds the bullets narrating a decision the bullet above them replaced.
 *
 * The signal is structural rather than lexical, and the corpus is what decides
 * that. The terms carrying clean signal for a supersession are too rare to
 * catch anything, and the one term that would have caught the known case is
 * `now`, which appears 57 times across 24 entries in correct present-tense
 * prose. What separates the shape instead is a bullet pointing back at its
 * sibling and putting the sibling's design in the past: an opening pronoun with
 * no antecedent of its own, plus a past-tense verb, plus a bullet above it to
 * refer to. Precision is the whole value, so recall is the accepted exposure
 * and a narration written as a single bullet is not reached.
 *
 * The pronoun is matched cased and anchored, since a mid-sentence `this` is a
 * determiner rather than a back-reference. The verb is matched uncased anywhere
 * in the bullet, since the tense is what carries the signal wherever it sits,
 * and rejected behind a `COPULA` for the reason stated there. Displayed spans
 * are masked so a term quoted in backticks is not read as prose the entry
 * writes, and fenced blocks are skipped for the reason the scans above skip
 * them.
 *
 * A blank line does not end the run. Markdown reads two bullets around one as a
 * single loose list, so breaking there would leave the shape reachable by
 * anyone who spaced their bullets out. What ends a run is content that is
 * neither a bullet nor indented under one, which the fenced branch below has to
 * answer for itself because a fenced line is skipped before that test.
 */
function narration(
  lines: readonly BodyLine[],
  terms: NarrationTerms,
): NarrationFinding[] {
  if (terms.pronouns.length === 0 || terms.verbs.length === 0) return []

  const findings: NarrationFinding[] = []
  let following = false
  let fenceBlock: number | undefined
  let fenceInsideList = false

  for (const line of lines) {
    // A fenced line is never a bullet, but an unindented block still ends the
    // run. CommonMark reads a fence at column zero as interrupting the list, so
    // the bullets around it are two lists and the second has no antecedent
    // above it. A block indented under its bullet stays inside the item.
    //
    // The opening delimiter decides for every line of its own block. Reading
    // each line instead ends the run on a blank line inside an indented fence,
    // which has no indentation to read, and on a content line at column zero,
    // which CommonMark permits since only the fence's own indent is stripped.
    //
    // The block index is what re-opens that decision, so two blocks written
    // with nothing between them are answered separately rather than the second
    // inheriting the first. Indentation stays the test here because what
    // interrupts a list is this check's own judgment, and the walker only says
    // which lines share a block.
    if (line.fenced) {
      if (line.fenceBlock !== fenceBlock) {
        fenceBlock = line.fenceBlock
        fenceInsideList = INSIDE_LIST.test(line.text)
      }
      if (!fenceInsideList) following = false
      continue
    }

    if (line.text.trim() === '') continue

    const bullet = line.text.match(TOP_BULLET)
    if (!bullet) {
      // A nested bullet and a wrapped continuation both sit inside the list, so
      // neither ends the run. Anything else does, which is what keeps a bullet
      // opening the list under a heading from reading as a reply to the last
      // bullet of the list before it.
      if (!INSIDE_LIST.test(line.text)) following = false
      continue
    }

    const text = maskDisplayed(bullet[1])

    if (following) {
      const pronoun = terms.pronouns.find((term) =>
        new RegExp(`^${escape(term)}\\b`).test(text),
      )
      const verb = pronoun
        ? terms.verbs.find((term) =>
            new RegExp(
              `(?<!\\b(?:${COPULA.join('|')})\\s+)\\b${escape(term)}\\b`,
              'i',
            ).test(text),
          )
        : undefined

      if (pronoun && verb) findings.push({ line: line.number, pronoun, verb })
    }

    following = true
  }

  return findings
}

/**
 * Finds which required sections the entry declares.
 *
 * A heading at any level counts rather than the `##` the standard writes its
 * examples at. A domain that split into a folder puts its overview in a sibling
 * named for it, where the section is the `#` title and an `##` beneath it would
 * repeat the file's own name. All three split folders in this repository are
 * that shape, so matching `##` alone would report every one of them. Nothing is
 * titled for a required section without being about it, so the looser match
 * costs no precision.
 *
 * Fenced blocks are skipped for the reason the scans above skip them. A
 * standard quoted inside an example declares nothing about the entry quoting it.
 */
function declaredSections(lines: readonly BodyLine[]): string[] {
  const found = new Set<string>()

  for (const line of lines) {
    if (line.fenced) continue

    const match = line.text.match(HEADING_TEXT)
    if (match && REQUIRED_SECTIONS.includes(match[1])) found.add(match[1])
  }

  return REQUIRED_SECTIONS.filter((section) => found.has(section))
}

/**
 * Finds the references naming a sibling entry by bare filename.
 *
 * The standard asks for the path because a bare name resolves against whichever
 * folder the reader is in, so a folder split strands every inbound reference
 * and nothing reads the break. A path is checkable and a bare name is not,
 * which is what makes this the one form rule worth measuring.
 *
 * Matching stops at the sibling set, which reaches less than the rule does. The
 * standard governs a reference to any other entry, so a split entry naming one
 * that sits in a different folder is a violation this never sees. What the set
 * buys is that a name resolving inside the folder is a reference by
 * construction, where a bare filename matched anywhere would report every
 * sentence that happens to name a file. The entry's own name is out of the set
 * on separate grounds, since naming itself points at nothing a split can strand.
 *
 * Fenced blocks are skipped for the reason the scans above skip them, and a line
 * carrying the citation ignore marker is skipped because that marker already
 * means the line displays a name rather than pointing at one.
 */
function bareReferences(
  lines: readonly BodyLine[],
  siblings: readonly string[],
): BareReferenceFinding[] {
  if (siblings.length === 0) return []

  const named = new Set(siblings)
  const findings: BareReferenceFinding[] = []

  for (const line of lines) {
    if (line.fenced || line.text.includes(IGNORE_MARKER)) continue

    for (const match of line.text.matchAll(BARE_NAME)) {
      if (named.has(match[1])) {
        findings.push({ line: line.number, name: match[1] })
      }
    }
  }

  return findings
}

/**
 * Measures one entry, scanning for provenance only when a standard claims it.
 *
 * The caller passes jurisdiction rather than deriving it from `rel`, because a
 * path prefix hardcodes what `--folder` exists to override and misses a domain
 * split into `context/<sub-area>/`. Sibling names arrive the same way and for
 * the same reason, since the folder an entry sits in is what holds them.
 */
export function measureEntry(
  rel: string,
  source: string,
  governsContent = true,
  terms?: NarrationTerms,
  siblings: readonly string[] = [],
): EntryReport {
  const lines = bodyLines(source)

  return {
    rel,
    lines: source
      .replace(/\n$/, '')
      .split('\n')
      .reduce((sum, text) => sum + renderedHeight(text), 0),
    catalogTables: catalogTables(lines),
    provenance: governsContent ? provenance(lines) : [],
    narration: governsContent && terms ? narration(lines, terms) : [],
    bareReferences: bareReferences(lines, siblings),
    sections: governsContent ? declaredSections(lines) : [],
    stub: isStubSeed(source),
    governed: governsContent,
  }
}

/**
 * Names each entry past the checkpoint with the standard's three questions
 * answered as far as anything measures them.
 *
 * Only accumulated history is mechanical, and it is already measured by the
 * provenance check, so this joins that count rather than counting again. What
 * it joins is a count of change markers, since a date stamping a measurement is
 * not one and an entry recording what its runs cost would otherwise report
 * accumulated history on the anchors dating those runs. The other two are read
 * by a person: whether an entry still covers one domain is a judgment about its
 * subject, and recognizing content `ls` or `--help` reproduces needs a reader
 * who knows what those emit.
 *
 * An entry outside the governed folder has no measured question at all, since
 * provenance is scoped to the standard stating it, and reporting `no` there
 * would answer from a scan that never ran.
 *
 * Sorted longest first, which is the order the report already printed and the
 * order the questions are worth asking in.
 */
export function lengthFindings(
  entries: readonly EntryReport[],
): LengthFinding[] {
  return entries
    .filter((entry) => entry.lines > LENGTH_CHECKPOINT)
    .sort((a, b) => b.lines - a.lines)
    .map((entry) => ({
      rel: entry.rel,
      lines: entry.lines,
      causes: [
        { question: 'domain', state: 'unanswered' },
        { question: 'reproduced', state: 'unanswered' },
        historyCause(entry),
      ] satisfies LengthCause[],
    }))
}

function historyCause(entry: EntryReport): LengthCause {
  if (!entry.governed) return { question: 'history', state: 'unanswered' }

  return entry.provenance.length > 0
    ? { question: 'history', state: 'yes', markers: entry.provenance.length }
    : { question: 'history', state: 'no' }
}

/**
 * Measures every entry in the audited folders. A generated `index.md` is not
 * among them, since its body is rewritten on every regen and no checkpoint
 * describes a catalog.
 *
 * Jurisdiction is applied here rather than at the report, so the JSON record
 * and the printed run agree on which entries a content rule reached.
 */
export async function measureFolders(
  root: string,
  folders: readonly AuditedFolder[],
  terms?: NarrationTerms,
): Promise<EntryReport[]> {
  const reports: EntryReport[] = []

  for (const folder of folders) {
    const names = matchesSiblings(folder)
      ? folder.entries.map((path) => basename(path))
      : []

    for (const path of folder.entries) {
      const self = basename(path)

      reports.push(
        measureEntry(
          relative(root, path),
          await readFile(path, 'utf8'),
          governsContent(folder),
          terms,
          names.filter((name) => name !== self),
        ),
      )
    }
  }

  return reports
}

/** Reports whether the folder's standard is the one carrying the exclusion. */
export function governsContent(folder: AuditedFolder): boolean {
  return folder.name === PROVENANCE_FOLDER
}

/**
 * Reports whether a bare sibling name here is a reference by construction.
 *
 * A split folder's entries are named for sub-areas of one domain, so a bare
 * name matching one of them points at it and nothing else. The folder named
 * under `.claude/` is where that stops holding, since its entries are named for
 * whole domains and a domain name is a common noun that a seed, a script, or
 * another tree spells the same way. Both false positives this measure was tuned
 * against sat there, naming a seed that shares a filename with the entry beside
 * them, and no signal in the name separates the two.
 *
 * What the exemption costs is the references a future split of the named folder
 * would strand, which are the ones this measure would most like to hold. It is
 * taken because a report firing on correct prose is what teaches a reader to
 * stop reading the section.
 */
export function matchesSiblings(folder: AuditedFolder): boolean {
  return governsContent(folder) && folder.nested
}

/**
 * Names what does not declare the sections the standard requires.
 *
 * Which unit answers depends on what the folder is. A split folder's entries
 * describe one domain between them and carry the overview and the layout in a
 * sibling named for them, so any one of them answers and a per-file rule there
 * would report every other child of all three shipped splits. The entries of
 * the folder named under `.claude/` are one domain each, so each answers for
 * itself. Rolling those up too was the first shape of this check, and it let a
 * single sibling stand in for thirteen domains it says nothing about.
 *
 * The judgment sits in the caller because the split case needs the folder's
 * other entries, which `measureFolders` holds and `measureEntry` does not. A
 * folder with no entries of its own is a split parent holding an index and
 * subfolders, and it has nothing to require a section of.
 *
 * The standard sanctions omitting `## Layout` from a domain owning no paths,
 * which no measure can tell from an entry that forgot it. An entry of that
 * shape therefore reports, which is a reason this is printed and never gated on.
 */
export function missingSections(
  root: string,
  folders: readonly AuditedFolder[],
  entries: readonly EntryReport[],
): SectionFinding[] {
  const byRel = new Map(entries.map((entry) => [entry.rel, entry]))
  const findings: SectionFinding[] = []

  const shortOf = (declared: readonly string[]): string[] =>
    REQUIRED_SECTIONS.filter((name) => !declared.includes(name))

  for (const folder of folders) {
    if (!governsContent(folder) || folder.entries.length === 0) continue

    // A stub owes no sections, so it is dropped before either branch rather
    // than inside them. Leaving one in the split-folder aggregate would let a
    // skeleton answer for the siblings that do owe the sections.
    const reports = folder.entries
      .map((path) => byRel.get(relative(root, path)))
      .filter((entry) => entry !== undefined)
      .filter((entry) => !entry.stub)

    if (reports.length === 0) continue

    if (folder.nested) {
      const missing = shortOf(reports.flatMap((entry) => entry.sections))
      if (missing.length > 0) findings.push({ rel: folder.rel, missing })
      continue
    }

    for (const entry of reports) {
      const missing = shortOf(entry.sections)
      if (missing.length > 0) findings.push({ rel: entry.rel, missing })
    }
  }

  return findings
}