@vibe-agent-toolkit/cli 0.2.0-rc.1 → 0.2.0-rc.3

package/dist/commands/claude/context.js

@@ -0,0 +1,709 @@
+/**
+ * `vat claude context [path]` — what loads into an agent's context here, and
+ * what it costs.
+ *
+ * The first ANALYSIS verb under `vat claude`, which until now held only
+ * management verbs (plugins, marketplaces, org administration). It answers a
+ * question, changes nothing, and never gates: there is no threshold anywhere in
+ * this file, and the only non-zero exit is {@link handleCommandError}'s 2 for a
+ * system failure. A number that fails a build teaches people to stop reading it.
+ *
+ * ## Everything below is orchestration and formatting — deliberately
+ *
+ * Which files load, why, and what they cost are all decided in
+ * `@vibe-agent-toolkit/resources` (`whatLoadsAt` and `account`). This module
+ * populates, calls them, and renders. It computes nothing about context loading
+ * of its own, which is the CLI-stays-dumb rule applied to a lane where the
+ * temptation is strong: the totals are right there and a "just one more derived
+ * field" would put a second, unowned model of the vendor's behaviour in the
+ * package no other package can depend on.
+ *
+ * ## The limits ride WITH the run — ONCE — in every format
+ *
+ * Spec §11 puts the stated limits in the command's own output rather than in a
+ * doc, because a limit a reader has to go and find is a limit that never reaches
+ * the person acting on the number. So {@link CLAUDE_CONTEXT_LIMITS} and
+ * {@link CLAUDE_CONTEXT_MODELLED_BEHAVIOURS} are fields of the yaml/json
+ * ENVELOPE and a printed section of the text rendering, and
+ * {@link CLAUDE_CONTEXT_BOUNDS_STATEMENT} — *neither a floor nor a ceiling* —
+ * appears in all three. All three are imported, never restated: the sentence is
+ * domain content owned beside the list it frames, so every other consumer of the
+ * list reaches it too.
+ *
+ * ⛔ They belong to the ENVELOPE, never to an answer, and both renderings obey
+ * that identically — see {@link ContextEnvelope} for why. Attaching them per
+ * answer was not a formatting preference: on a `--all` sweep of this repository
+ * (6,224 answers) `--format json` measured 76,877,016 bytes and measures
+ * 6,581,468 with the block hoisted — 70.3 MB of ONE byte-identical paragraph,
+ * repeated. That is the JSON spelling of the very burial
+ * {@link renderEnvelopeText} refuses to do in text.
+ *
+ * ⛔ Nothing here may read as "complete". Many of the stated limits are signed
+ * `over-report`/`under-report` and apply whether or not `unknownTokenRows`,
+ * `skippedOversizeRows` and `prunedRows` are all zero, so zeroed counters are not
+ * a licence for the words "total cost", "full" or "all context".
+ *
+ * ⛔ A `null` token or byte count is an UNKNOWN SIZE and is never rendered as 0 —
+ * see {@link chargeText}. A confident zero is indistinguishable from a measured
+ * one, and the same reasoning is why an unrealized path answers `unknown` rather
+ * than an empty table.
+ */
+import { account, buildClaudeContextPopulation, CLAUDE_CONTEXT_BOUNDS_STATEMENT, CLAUDE_CONTEXT_LIMITS, CLAUDE_CONTEXT_MODELLED_BEHAVIOURS, CLAUDE_MD_TAG, discoverableFrom, whatLoadsAt, } from '@vibe-agent-toolkit/resources';
+import { findProjectRoot } from '@vibe-agent-toolkit/utils';
+import { Command, Option } from 'commander';
+import { handleCommandError } from '../../utils/command-error.js';
+import { targetPathWithin } from '../../utils/corpus-target.js';
+import { createLogger } from '../../utils/logger.js';
+import { writeJsonOutput, writeStdoutSync, writeYamlOutput } from '../../utils/output.js';
+import { populationWiring } from '../../utils/population-wiring.js';
+import { withPopulationCache } from '../../utils/projection-store.js';
+import { gitTrackerForProjectRoot } from '../audit/distributed-tree.js';
+/** Soft wrap width for the printed limit statements. */
+const WRAP_COLUMNS = 96;
+/** How this command names itself in a refusal. */
+const COMMAND_NAME = 'vat claude context';
+/**
+ * Create the `vat claude context [path]` command.
+ *
+ * @returns The configured Commander command
+ */
+export function createContextCommand() {
+    const command = new Command('context');
+    command
+        .description('Report what Claude Code loads into context at a path, why, and what it costs')
+        .argument('[paths...]', 'Files or directories to answer for (default: the current directory)')
+        .addOption(new Option('--format <format>', 'Output format: text (default), yaml, or json').choices([
+        'text',
+        'yaml',
+        'json',
+    ]).default('text'))
+        .option('--all', 'Answer for every path the projection realized, instead of named paths')
+        .option('--discoverable', 'Also report what the loaded files LINK TO in one hop and the harness does not load')
+        .option('--debug', 'Verbose logging to stderr')
+        .action(claudeContextCommand)
+        .addHelpText('after', `
+Description:
+  Report which CLAUDE.md files, .claude/rules files and @-imported files load
+  into an agent's context at a path, why each one is there, and what it costs.
+  A FILE argument is exact. A directory argument classifies each path-scoped
+  rule as ∀ (its glob covers every file there, so it is a second CLAUDE.md for
+  that directory) or ∃ (some file there matches, and the answer names it); a
+  rule no file there can match is left out rather than charged.
+
+  Several paths may be named at once. The tree is enumerated ONCE and every
+  path answered from that one population, so asking about ten paths together
+  costs what asking about one costs — not ten times it. No paths means the
+  current directory; --all sweeps every path the projection realized.
+
+  --discoverable adds a second, DISJOINT set: what the loaded files LINK to in
+  one hop and the harness does not load. A markdown link is voluntary — nothing
+  loads it — so its tokens are reported separately and never added to the
+  estimate. A target already in the loaded set is excluded, so the two sets
+  partition and can be read alone or added.
+
+Output:
+  - root:    the corpus root that was enumerated
+  - answers: one document per requested path, in the order requested — always
+             a list, even for a single path, so consumers never branch on count
+  - totals:  always/on-demand token estimates, plus counts of rows whose size
+             is unknown, skipped by the 4 MiB cliff, or pruned behind one
+  - rows:    one per resource, with every predicate that admitted it
+  - limits:  what these answers deliberately do not settle, in both directions.
+             On the ENVELOPE beside root, never on an answer — they bound the
+             method rather than any one path, so they are stated exactly once
+             however many paths were asked about
+
+  A path the projection never realized answers kind: unknown — never zero.
+  Diagnostics and blob-stage refusals go to stderr; stdout is the document.
+
+Exit Codes:
+  0 - An answer was produced (there is no threshold and no gate)
+  1 - Invalid usage (unknown option, or an unsupported --format value)
+  2 - System error (a path outside the corpus root, unreadable tree)
+
+Example:
+  $ vat claude context src/index.ts docs/ README.md   # one scan, three answers
+`);
+    return command;
+}
+/**
+ * Action handler for `vat claude context [path]`.
+ *
+ * @param pathArg - The path to answer for, or undefined for the current directory
+ * @param options - The command's flags
+ */
+export async function claudeContextCommand(pathArgs, options) {
+    const logger = createLogger(options.debug === true ? { debug: true } : {});
+    const startTime = Date.now();
+    const sweep = options.all === true;
+    try {
+        const root = findProjectRoot(process.cwd()) ?? process.cwd();
+        // 🔑 Every argument is resolved BEFORE the population, not inside the map.
+        // A path outside the corpus is a usage error, and finding it afterwards
+        // would charge the caller a full population — minutes on a cold cache — to
+        // be told they mistyped. `--all` has no arguments to check.
+        const requested = sweep ? [] : targetsWithin(root, pathArgs);
+        const projection = await populateContext(root, logger);
+        const targets = sweep ? everyRealizedPath(projection) : requested;
+        const format = options.format ?? 'text';
+        // ONE population, N queries. `whatLoadsAt` is a pure read of materialised
+        // tables, so the marginal cost of another path is a map lookup — which is
+        // the whole reason this command takes a list rather than being run twice.
+        const answers = targets.map((target) => documentFor(target, projection, root, options.discoverable === true));
+        emit(contextEnvelope(root, answers), renderEnvelopeText(answers), format);
+        // ⛔ Always 0. There is no threshold in this command and there is not going
+        // to be one — a number that fails a build is a number people learn to stop
+        // reading. The explicit exit matches every other leaf here and guarantees the
+        // process ends rather than waiting on whatever the population left behind.
+        process.exit(0);
+    }
+    catch (error) {
+        handleCommandError(error, logger, startTime, 'claude context');
+    }
+}
+/**
+ * The answer document for one query.
+ *
+ * Split from the handler so the handler stays a straight line: the accounting
+ * call needs the `claude-md` identity set, and threading that through the
+ * handler body put three statements between the query and its document.
+ *
+ * Returns the document alone — rendering moved to {@link renderEnvelopeText},
+ * which needs every document at once to print the limits exactly once, and the
+ * limits themselves are attached by {@link contextEnvelope}, never here.
+ *
+ * ⛔ Exported so it can be TESTED. What has to be pinned is an ABSENCE — that no
+ * limit field is on the returned document — and an absence is only observable by
+ * calling the function that would have added it.
+ *
+ * @param answer - The query's answer
+ * @param projection - The populated projection, for the `claude-md` tag rows
+ * @param discoverable - Whether to compute the one-hop reachable set
+ * @returns The answer document
+ */
+export function answerDocument(answer, projection, discoverable) {
+    // The cliff and root discovery read ONE vocabulary: these are the ids the
+    // shipped `classifyPath` tagged, not a second basename rule invented here.
+    const claudeMdIds = new Set(projection.resourceTags
+        .filter((tag) => tag.tag === CLAUDE_MD_TAG)
+        .map((tag) => tag.resourceId));
+    const accounted = account(answer, claudeMdIds);
+    // 🔑 `conditions`, `overBudgetRules` and `unattributedImports` live on the
+    // ORIGINAL answer — `AccountedContext` is `{rows, totals}` and nothing else.
+    // Reading them off the accounting result silently drops every warning.
+    const document = {
+        kind: 'answer',
+        input: answer.input,
+        directory: answer.directory,
+        file: answer.file,
+        totals: accounted.totals,
+        rows: accounted.rows,
+        conditions: answer.conditions,
+        overBudgetRules: answer.overBudgetRules,
+        unattributedImports: answer.unattributedImports,
+        // The ANSWER is passed, not recomputed: it is the authority for what is
+        // already loaded, and the two lenses partitioning depends on both reading
+        // one loaded set.
+        discoverable: discoverable ? discoverableFrom(projection, answer) : null,
+    };
+    return document;
+}
+/**
+ * Wrap the run's documents in the envelope, with the limits attached ONCE.
+ *
+ * The one place {@link CLAUDE_CONTEXT_LIMITS} and its two companions enter the
+ * machine-readable output. Keeping that a single assignment is what makes the
+ * "stated once" property structural rather than a habit: there is no per-answer
+ * site left where a copy could be reintroduced.
+ *
+ * ⛔ Exported so it can be TESTED alongside {@link answerDocument} — the
+ * regression this guards (an answer growing its own copy of the block) is a
+ * property of the two functions TOGETHER, and a test that can reach only one of
+ * them cannot see it.
+ *
+ * @param root - The corpus root that was enumerated
+ * @param answers - One document per requested path, in the order requested
+ * @returns The envelope, ready to serialize
+ */
+export function contextEnvelope(root, answers) {
+    return {
+        root,
+        answers,
+        boundsStatement: CLAUDE_CONTEXT_BOUNDS_STATEMENT,
+        limits: CLAUDE_CONTEXT_LIMITS,
+        modelledBehaviours: CLAUDE_CONTEXT_MODELLED_BEHAVIOURS,
+    };
+}
+/**
+ * Resolve every requested path, defaulting to the current directory.
+ *
+ * No arguments means the current directory — NOT the whole corpus. `--all` is
+ * the sweep, spelled explicitly, because a bare `vat claude context` answering
+ * for thousands of paths would turn the friendliest invocation into the most
+ * expensive one.
+ *
+ * @param root - The discovered project root
+ * @param pathArgs - The path arguments, possibly empty
+ * @returns One root-relative target per argument, in argument order
+ */
+function targetsWithin(root, pathArgs) {
+    if (pathArgs.length === 0)
+        return [targetPathWithin(root, undefined, COMMAND_NAME)];
+    return pathArgs.map((pathArg) => targetPathWithin(root, pathArg, COMMAND_NAME));
+}
+/**
+ * Every path the projection realized, sorted, for `--all`.
+ *
+ * Deduplicated because one identity may be realized at several paths and the
+ * question this command answers is asked of a PATH — two realizations of one
+ * identity are two legitimate questions, but the same path twice is not.
+ *
+ * ⚠️ Sorted by code point rather than left in table order: the table's order is
+ * an artefact of population, so a caller diffing two sweeps would see spurious
+ * churn. Sorting makes the sweep comparable across runs.
+ *
+ * @param projection - The populated projection
+ * @returns Root-relative paths, deduplicated and sorted
+ */
+function everyRealizedPath(projection) {
+    return [...new Set(projection.resourceRealizations.map((row) => row.path))].sort(comparePaths);
+}
+/**
+ * Order two paths by code point.
+ *
+ * ⛔ Not `localeCompare`: this ordering is consumed by machines diffing two
+ * sweeps, and a locale-sensitive comparator makes the same corpus sort
+ * differently on two developers' machines — a diff that reports churn nobody
+ * caused.
+ *
+ * @param left - The first path
+ * @param right - The second path
+ * @returns Negative, zero or positive, per `Array#sort`
+ */
+function comparePaths(left, right) {
+    if (left < right)
+        return -1;
+    return left > right ? 1 : 0;
+}
+/**
+ * The document for one target, answer or non-answer.
+ *
+ * @param target - The root-relative path to answer for
+ * @param projection - The populated projection
+ * @param root - The corpus root, for the non-answer's explanation
+ * @param discoverable - Whether to compute the one-hop reachable set
+ * @returns The answer document, or the structurally-different unknown document
+ */
+function documentFor(target, projection, root, discoverable) {
+    const answer = whatLoadsAt(projection, target);
+    if (answer.kind === 'unknown')
+        return unknownDocumentFor(answer.input, root);
+    return answerDocument(answer, projection, discoverable);
+}
+/**
+ * Render every answer for a person, with the limits stated exactly once.
+ *
+ * ⛔ The limits are printed ONCE, after the last answer, rather than per answer.
+ * They are properties of the MEASUREMENT METHOD, not of any one path, so
+ * repeating them per path would read as though each answer carried its own
+ * caveats — and on a `--all` sweep would bury the answers under thousands of
+ * identical paragraphs. A sweep with no answered path prints no limits at all,
+ * for the same reason {@link unknownDocumentFor} omits them: nothing was
+ * measured, so there is no measurement to bound.
+ *
+ * @param documents - The answers, in requested order
+ * @returns The text rendering, newline-terminated
+ */
+function renderEnvelopeText(documents) {
+    const bodies = documents.map((document) => document.kind === 'unknown' ? renderUnknownText(document) : renderAnswerText(document));
+    const measured = documents.some((document) => document.kind === 'answer');
+    if (!measured)
+        return bodies.join('\n');
+    return `${bodies.join('\n')}${limitSection().join('\n')}\n`;
+}
+/**
+ * Populate the Claude-context lane for one tree.
+ *
+ * @param root - The absolute corpus root
+ * @param logger - Where blob-stage refusals go. **stderr**, never stdout: this
+ *   command's stdout is the document a caller parses, and a diagnostic in the
+ *   middle of it breaks every consumer
+ * @returns The populated projection
+ */
+async function populateContext(root, logger) {
+    return withPopulationCache({ root }, async (cache) => {
+        const gitTracker = await gitTrackerForProjectRoot(root);
+        return buildClaudeContextPopulation({ root, ...populationWiring(logger, gitTracker, cache) });
+    });
+}
+/**
+ * Write the document in the requested format.
+ *
+ * @param document - The yaml/json payload
+ * @param text - The text rendering of the same answer
+ * @param format - The selected format
+ */
+function emit(document, text, format) {
+    if (format === 'json') {
+        writeJsonOutput(document);
+        return;
+    }
+    if (format === 'yaml') {
+        writeYamlOutput(document);
+        return;
+    }
+    writeStdoutSync(text);
+}
+/**
+ * The non-answer, spelled so it cannot be mistaken for an empty answer.
+ *
+ * ⛔ **A non-answer publishes no measurement, in every format.** No `totals`, no
+ * `rows`: nothing was measured here, so anything readable as a figure would
+ * assert that a measurement happened, which is the exact confusion `kind:
+ * 'unknown'` exists to prevent. The limits are one level up on the ENVELOPE and
+ * bound the run's method, not this path — a sweep whose every path was
+ * unrealized still measured nothing, and the `explanation` carries the only
+ * caveat that applies to a non-answer, which is that there is no answer.
+ *
+ * @param input - The path that was asked about
+ * @param root - The corpus root that was enumerated
+ * @returns The unknown document
+ */
+function unknownDocumentFor(input, root) {
+    return {
+        kind: 'unknown',
+        input,
+        reason: 'path-not-realized',
+        explanation: `${displayPath(input)} is not a path this projection realized under ${root}, so VAT did not`
+            + ' look at it. This is NOT an answer of "nothing loads here" — no context was measured at'
+            + ' all. Check the path exists and is not excluded from enumeration.',
+    };
+}
+/**
+ * Render the non-answer for a person.
+ *
+ * @param document - The unknown document
+ * @returns The text rendering, newline-terminated
+ */
+function renderUnknownText(document) {
+    return [
+        `NO ANSWER for ${displayPath(document.input)} — reason: ${document.reason}`,
+        '',
+        ...wrapStatement(document.explanation, '  '),
+        '',
+    ].join('\n');
+}
+/**
+ * Render the answer for a person.
+ *
+ * @param document - The answer document
+ * @returns The text rendering, newline-terminated
+ */
+function renderAnswerText(document) {
+    const lines = [
+        ...headingLines(document),
+        ...estimateLines(document.totals),
+        ...rowSection('Loaded at launch (always)', document.rows, 'always'),
+        ...rowSection('Loaded on demand', document.rows, 'on-demand'),
+        ...listSection('Conditions', document.conditions.map(conditionLine)),
+        ...listSection('Rules whose paths: list exceeded the vendor pattern budget', document.overBudgetRules),
+        ...listSection('Imported files no importer could be attributed to', document.unattributedImports),
+        ...discoverySection(document.discoverable),
+    ];
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * What the loaded files point at and the harness does not load.
+ *
+ * ⛔ Printed under its own heading with its own total, never merged into the
+ * token estimate. Nothing loads a markdown link, so this is an upper bound on a
+ * VOLUNTARY cost — what following every link once would add — and adding it to a
+ * context-budget figure would charge a session for documents it may never open.
+ * The heading says "not loaded" for a reader who sees only this section.
+ *
+ * A `null` argument means the lens was not asked for and prints NOTHING. An
+ * empty `rows` prints the heading with a zero, because "this file links nowhere"
+ * is a real and useful answer that must not be confused with "nobody looked".
+ *
+ * @param discoverable - The lens's answer, or null when `--discoverable` was off
+ * @returns The section's lines, or none when the lens did not run
+ */
+function discoverySection(discoverable) {
+    if (discoverable === null)
+        return [];
+    const { rows, totals } = discoverable;
+    const lines = [
+        'Discoverable in one hop — LINKED from the loaded files, NOT loaded',
+        `  ${totals.discoverableTokens} tokens if every link were followed once (a ceiling, never a charge)`,
+        `  ${totals.unknownTokenRows} size unknown · ${totals.unrealizedRows} not in this tree`
+            + ` · ${totals.outsideRootRows} outside the root`,
+    ];
+    for (const row of rows) {
+        lines.push(`  ${displayPath(row.path)} — ${discoverableCost(row)}`);
+        for (const citation of row.citedBy) {
+            const text = citation.text === null ? '' : ` as "${citation.text}"`;
+            lines.push(`      linked from ${displayPath(citation.fromPath)}:${citation.line}${text}`);
+        }
+    }
+    lines.push('');
+    return lines;
+}
+/**
+ * What one discoverable row would cost, or why VAT cannot say.
+ *
+ * ⛔ Never `0` for an unmeasured row, the same rule {@link chargeText} enforces
+ * one section up. `unrealized` says what it is — an absence in THIS projection —
+ * rather than "broken": adjudicating a link is `vat resources validate`'s lane.
+ *
+ * @param row - The discoverable row
+ * @returns The cost phrase
+ */
+function discoverableCost(row) {
+    if (row.reach === 'outside-root')
+        return 'outside the corpus root, so its size is unknowable here';
+    if (row.reach === 'unrealized')
+        return 'not realized in this projection, so nothing is known of it';
+    if (row.tokens === null)
+        return 'size unknown: no measured blob, so it is counted, not summed';
+    return `${row.tokens} tokens if opened`;
+}
+/**
+ * The heading, which states up front whether the query was exact.
+ *
+ * @param document - The answer document
+ * @returns The heading lines, blank-terminated
+ */
+function headingLines(document) {
+    const exactness = document.file === null
+        ? 'DIRECTORY query — a path-scoped rule is reported as ∀ (covers every file here)'
+            + ' or ∃ (some file here matches); only a FILE query is exact'
+        : 'FILE query — path-scoped rules are matched exactly';
+    return [`Claude Code context at ${displayPath(document.input)}`, `  ${exactness}`, ''];
+}
+/**
+ * The token estimate and the three counters that keep it from reading as settled.
+ *
+ * @param totals - The accounting totals
+ * @returns The section's lines, blank-terminated
+ */
+function estimateLines(totals) {
+    return [
+        'Token estimate',
+        `  always-loaded         ${totals.alwaysTokens} tokens`,
+        `  on-demand             ${totals.onDemandTokens} tokens`,
+        `  size unknown          ${totals.unknownTokenRows} rows (counted, never summed as zero)`,
+        `  skipped over 4 MiB    ${totals.skippedOversizeRows} rows`,
+        `  pruned behind a skip  ${totals.prunedRows} rows`,
+        '',
+    ];
+}
+/**
+ * One load class's rows, each with every predicate that admitted it.
+ *
+ * @param title - The section heading
+ * @param rows - Every accounted row
+ * @param loadClass - The class this section reports
+ * @returns The section's lines, or none when the class is empty
+ */
+function rowSection(title, rows, loadClass) {
+    const selected = rows.filter((row) => row.loadClass === loadClass);
+    if (selected.length === 0)
+        return [];
+    const lines = [title];
+    for (const row of selected) {
+        lines.push(`  ${row.path} — ${chargeText(row)}`);
+        for (const admission of row.admissions) {
+            lines.push(`      ${describeAdmission(admission)}`);
+        }
+    }
+    lines.push('');
+    return lines;
+}
+/**
+ * What one row costs, or why it costs nothing.
+ *
+ * ⛔ A null token count renders as "size unknown", never as `0`. The `charged`
+ * branch cannot be reached with a null — `chargeOf` classifies those
+ * `unknown-size` first — but the check is written as a value test rather than a
+ * `?? 0`, so if that ever changed the output would say what it knows instead of
+ * asserting a measurement it does not have.
+ *
+ * **Exported solely so that rule can be pinned by a test that would FAIL if a
+ * `?? 0` were introduced.** The property lives in the RENDERER and nowhere else:
+ * an assertion over the json rows only re-states what `account` already
+ * guarantees, and on any real tree every row carries a blob, so such an
+ * assertion compares `false === false` and passes without ever reaching the code
+ * that could print a zero. It is not part of this module's command surface and
+ * nothing outside its own test may call it.
+ *
+ * @param row - The accounted row
+ * @returns The cost phrase
+ */
+export function chargeText(row) {
+    if (row.charge === 'oversize-skipped') {
+        return 'skipped: past the 4 MiB CLAUDE.md cliff, so none of it loads';
+    }
+    if (row.charge === 'pruned-by-oversize') {
+        return 'not reached: every import route into it passes through a skipped file';
+    }
+    if (row.tokens === null)
+        return 'size unknown: no measured blob, so it is counted, not summed';
+    return `${row.tokens} tokens`;
+}
+/**
+ * One admission, in prose.
+ *
+ * @param admission - Why the row is in the answer
+ * @returns The prose form
+ */
+function describeAdmission(admission) {
+    switch (admission.kind) {
+        case 'ancestry':
+            return `CLAUDE.md chain, from ${displayPath(admission.dir)}`;
+        case 'root-rule':
+            return 'root-scope rules file';
+        case 'nested-rule':
+            return `nested rules file, under ${displayPath(admission.under)}`;
+        case 'glob-rule':
+            return `rule matched ${admission.pattern}`;
+        case 'glob-rule-covers-dir':
+            return `∀ rule covers EVERY file here via ${admission.pattern}`
+                + ' — a second CLAUDE.md for this directory in all but name';
+        case 'glob-rule-may-fire':
+            return `∃ rule may fire here — ${admission.pattern} matches ${displayPath(admission.examplePath)}`
+                + ', among possibly others; ask about a FILE for an exact answer';
+        // Spelled out rather than left to a `default`, so that adding a seventh
+        // admission kind upstream is a lint error here instead of an import
+        // description silently applied to something that is not an import.
+        case 'import':
+            return describeImport(admission);
+    }
+}
+/**
+ * One import admission, in prose.
+ *
+ * An unattributed member says so rather than naming a plausible importer: the
+ * query reports `viaPath: null` precisely when it could not attribute a parent,
+ * and inventing one here would launder that into a fact.
+ *
+ * @param admission - The import admission
+ * @returns The prose form
+ */
+function describeImport(admission) {
+    if (admission.viaPath === null || admission.depth === null) {
+        return `@-imported into the closure rooted at ${admission.rootPath}, importer unattributed`;
+    }
+    return `imported by ${admission.viaPath} at depth ${admission.depth}`
+        + ` (closure rooted at ${admission.rootPath})`;
+}
+/**
+ * One condition, in the compact `severity code at location: message` shape.
+ *
+ * @param condition - The graded condition
+ * @returns The line
+ */
+function conditionLine(condition) {
+    const reference = condition.sourceRef === null ? '' : ` [${condition.sourceRef}]`;
+    return `  ${condition.severity.padEnd(5)} ${condition.code}`
+        + ` at ${conditionLocation(condition)}${reference}: ${condition.message}`;
+}
+/**
+ * Where a condition points, using the most specific provenance it carries.
+ *
+ * @param condition - The graded condition
+ * @returns A path, or a `path:line`
+ */
+function conditionLocation(condition) {
+    if (condition.sourcePath === null)
+        return condition.path;
+    if (condition.sourceLine === null)
+        return condition.sourcePath;
+    return `${condition.sourcePath}:${condition.sourceLine}`;
+}
+/**
+ * A heading plus its lines, or nothing at all when there are none.
+ *
+ * @param title - The section heading
+ * @param entries - The already-formatted lines, or bare strings to indent
+ * @returns The section's lines, blank-terminated, or none
+ */
+function listSection(title, entries) {
+    if (entries.length === 0)
+        return [];
+    return [title, ...entries.map((entry) => (entry.startsWith('  ') ? entry : `  ${entry}`)), ''];
+}
+/**
+ * The limits section — the one part of this rendering that is never omitted.
+ *
+ * Printed even when there is nothing else to say, because the limits are a
+ * property of the METHOD rather than of this particular tree: an answer with no
+ * conditions and no unknown rows is subject to exactly the same signed
+ * over/under-report bounds as a messy one.
+ *
+ * ⛔ Reads the imported constants, NOT an answer document — the same source
+ * {@link contextEnvelope} reads. It took no argument's worth of per-answer data
+ * even when the fields were on the answer, and threading one through was what
+ * made "the limits belong to an answer" look true.
+ *
+ * @returns The section's lines
+ */
+function limitSection() {
+    const lines = [
+        'What this answer does not settle',
+        ...wrapStatement(CLAUDE_CONTEXT_BOUNDS_STATEMENT, '  '),
+        '',
+    ];
+    for (const limit of CLAUDE_CONTEXT_LIMITS) {
+        lines.push(`  ${limit.direction}: ${limit.id}`);
+        lines.push(...wrapStatement(limit.statement, '    '));
+    }
+    lines.push('', 'Modelled Claude Code behaviours (vendor versions, each cited)');
+    for (const behaviour of CLAUDE_CONTEXT_MODELLED_BEHAVIOURS) {
+        lines.push(`  ${behaviour.behaviour}`);
+        lines.push(`    ${behaviour.introducedIn} — ${behaviour.citedFrom}`);
+    }
+    return lines;
+}
+/**
+ * Soft-wrap a statement to {@link WRAP_COLUMNS}, under a fixed indent.
+ *
+ * The limit statements are two and three sentences long and are the part of this
+ * output people actually have to read; unwrapped they arrive as one 400-column
+ * line that a terminal breaks mid-word.
+ *
+ * @param text - The statement
+ * @param indent - Leading whitespace for every produced line
+ * @returns One or more indented lines
+ */
+function wrapStatement(text, indent) {
+    const width = Math.max(WRAP_COLUMNS - indent.length, 20);
+    const lines = [];
+    let pending = [];
+    let used = 0;
+    for (const word of text.split(' ')) {
+        if (pending.length > 0 && used + pending.length + word.length > width) {
+            lines.push(indent + pending.join(' '));
+            pending = [];
+            used = 0;
+        }
+        pending.push(word);
+        used += word.length;
+    }
+    if (pending.length > 0)
+        lines.push(indent + pending.join(' '));
+    return lines;
+}
+/**
+ * A root-relative path as a reader should see it.
+ *
+ * The corpus root itself is `''`, which renders as nothing at all and reads like
+ * a bug. Only the empty case is special-cased — every other path is printed
+ * exactly as the projection holds it, so a reader can paste it straight back in.
+ *
+ * @param path - The root-relative path
+ * @returns The display form
+ */
+function displayPath(path) {
+    return path === '' ? '<corpus root>' : path;
+}
+//# sourceMappingURL=context.js.map