explico 0.13.0 → 0.14.0

package/dist/compiler/cli.d.ts

@@ -1,12 +1,12 @@
 import { DiagnosticSeverity } from '../reference/types.js';
-import { EquationLink } from '../reference/gate-math.js';
-import { Manifest, ManifestLesson } from './manifest.js';
+import { EquationLink, ScopeEntry } from '../reference/gate-math.js';
+import { ManifestLesson, Manifest } from './manifest.js';
 import { RenderDiagnostic } from './render-diagnostics.js';
-import { RulesFilter, RuleInEffect } from '../rules/in-effect.js';
+import { RetiredRule } from '../rules/catalog.js';
+import { RuleInEffect, RulesFilter } from '../rules/in-effect.js';
 import '../curriculum/validation.js';
 import '../reference/consistency.js';
-import '../course-config-rRtME5UV.js';
-import '../rules/catalog.js';
+import '../course-config-BLtIdkei.js';
 import '../rules/course-rules.js';
 import './collections.js';
 import '../reference/gate-retired-keys.js';
@@ -25,12 +25,17 @@ import '../reference/mixed-content.js';
 import '../reference/gloss.js';
 import '../rules/waivers.js';
 import './knowledge-version.js';
+import './page-versions.js';
+import './decks.js';
+import '../reference/decks-validate.js';
+import '../reference/deck-source.js';
 import './lesson-derivation.js';
 
 /**
  * The `content` CLI core (Phase G1).
  *
- * `scripts/content.ts` is a thin argv wrapper; every command's logic lives here
+ * `./cli-main` is the router (`runContentCli`), a course's `scripts/content.ts`
+ * a three-line shim over it; every command's logic lives here
  * as a pure-ish function that takes a compiled {@link Manifest} and returns a
  * plain data object. The router is **read-only** — only `content new` touches
  * the filesystem, and even then `scaffoldLesson` / `scaffoldTerm` only return
@@ -59,7 +64,7 @@ import './lesson-derivation.js';
  *     under the `render:` source.
  */
 
-type ContentCliCode = 'unknown-command' | 'usage' | 'unknown-lesson' | 'unknown-kind' | 'invalid-id' | 'exists' | 'not-a-lesson' | 'no-git';
+type ContentCliCode = 'unknown-command' | 'usage' | 'unknown-lesson' | 'unknown-kind' | 'invalid-id' | 'exists' | 'not-a-lesson' | 'no-git' | 'unknown-version' | 'migration-gap' | 'unknown-key';
 /** A user-facing failure with a stable code and no stack in `--json` output. */
 declare class ContentCliError extends Error {
     readonly code: ContentCliCode;
@@ -74,6 +79,8 @@ interface CliDiagnostic {
      * which `tests/rules/catalog.test.ts` treats as a bug.
      */
     readonly rule?: string;
+    /** The owner's page and anchor under `docs/authoring/`, `notation.md#n4`. */
+    readonly doc?: string;
     readonly severity: DiagnosticSeverity;
     readonly message: string;
     readonly file?: string;
@@ -87,13 +94,23 @@ interface CliDiagnostic {
      */
     readonly equation?: EquationLink;
 }
+/** ` [N4 · notation.md#n4]` for a diagnostic the catalog owns; empty otherwise. */
+declare function ownerTag(diagnostic: Pick<CliDiagnostic, 'rule' | 'doc'>): string;
+/**
+ * One text line for a diagnostic, the shape every verb prints:
+ * `file:line:column: severity code [rule · doc]: message`. The location is
+ * left out when the diagnostic has no file, and reads `1:1` when the file is
+ * known but the position is not, so an editor opens the file. The rule and its page are on the
+ * line so a reader needs no second lookup to find what the code answers to.
+ */
+declare function formatCliDiagnostic(diagnostic: CliDiagnostic): string;
 /**
  * Every manifest diagnostic that names this lesson (by id or file), normalized
  * to {@link CliDiagnostic}. Corpus-wide checks (curriculum) are included only
  * when their message mentions the lesson; per-file checks (notation, math,
  * equations, consistency) are filtered by `file`.
  */
-declare function lessonDiagnostics(manifest: Manifest, lesson: ManifestLesson, rendered?: readonly RenderDiagnostic[]): CliDiagnostic[];
+declare function lessonDiagnostics(manifest: Manifest, lesson: CheckTarget, rendered?: readonly RenderDiagnostic[]): CliDiagnostic[];
 interface RenderResult {
     readonly rendered: boolean;
     readonly diagnostics: readonly CliDiagnostic[];
@@ -139,6 +156,34 @@ interface DomainFileSignatures {
 interface StatusReport {
     /** The course's published knowledge version (`about.version`). */
     readonly knowledgeVersion: string;
+    /**
+     * What an agent is told to read before working, in estimated tokens: the
+     * course's `AGENTS.md`, the repository's one level up when the course is a
+     * workspace package, and the rules-in-effect page. A budget to watch; the
+     * estimate is bytes over four.
+     */
+    readonly agentSurfaces: readonly {
+        readonly name: string;
+        readonly tokens: number;
+    }[];
+    /**
+     * Whether the course's own `AGENTS.md` points an agent at the engine's
+     * guide (`docs/authoring/agents.md`), and whether the procedures
+     * `content init-agent` installs are in `.claude/`.
+     */
+    readonly agentGuide: {
+        readonly agentsFile: string | null;
+        readonly linksGuide: boolean;
+        readonly skillsInstalled: boolean;
+    };
+    /**
+     * Rule C5: how many chapters and part pages carry a version of their own,
+     * and the slugs of those with a change `## [Unreleased]` has not released.
+     */
+    readonly pageVersions: {
+        readonly tracked: number;
+        readonly unreleased: readonly string[];
+    };
     readonly counts: {
         readonly lessons: number;
         readonly competencies: number;
@@ -166,6 +211,46 @@ interface DiagnosticsReport {
     readonly count: number;
     readonly diagnostics: readonly CliDiagnostic[];
 }
+/**
+ * The diagnostics list folded to what an agent decides from: how many, of
+ * what, and where. The default text output, since a course can have hundreds
+ * of lines of two codes and the list is what `--all` is for.
+ */
+interface DiagnosticsSummary {
+    readonly minimumSeverity: DiagnosticThreshold;
+    readonly count: number;
+    readonly bySeverity: {
+        readonly errors: number;
+        readonly warnings: number;
+        readonly infos: number;
+    };
+    /** One row per code and severity, most frequent first. */
+    readonly byCode: readonly {
+        readonly code: string;
+        readonly rule?: string;
+        readonly doc?: string;
+        readonly severity: DiagnosticSeverity;
+        readonly count: number;
+    }[];
+    /** One row per file, most diagnostics first; `(no file)` for the rest. */
+    readonly byFile: readonly {
+        readonly file: string;
+        readonly count: number;
+        readonly errors: number;
+        readonly warnings: number;
+        readonly infos: number;
+    }[];
+}
+declare function summarizeDiagnostics(report: DiagnosticsReport): DiagnosticsSummary;
+/** The diagnostics of one code (with or without its `source:` prefix) or of some files. */
+declare function filterDiagnostics(report: DiagnosticsReport, filter: {
+    readonly code?: string;
+    readonly files?: readonly string[];
+}): DiagnosticsReport;
+/** The summary as text: a severity line, then counts by code and by file, the file list capped. */
+declare function formatDiagnosticsSummary(summary: DiagnosticsSummary, options?: {
+    readonly fileCap?: number;
+}): string;
 interface WarningsReport {
     readonly count: number;
     readonly warnings: readonly CliDiagnostic[];
@@ -191,6 +276,8 @@ interface RulesReport {
 declare function parseRulesFilter(input: {
     readonly element?: string;
     readonly enforcement?: string;
+    /** `chapter` (the default page) or `deck` (`<lesson>.deck.mdx`). */
+    readonly edition?: string;
 }): RulesFilter;
 /** The rules this course has in effect, optionally narrowed. */
 declare function contentRules(manifest: Manifest, filter?: RulesFilter): RulesReport;
@@ -204,6 +291,8 @@ interface ContextReport {
         readonly teaches: readonly string[];
         readonly requires: readonly string[];
         readonly assumptions: readonly string[];
+        /** The version the page's content last changed in; `null` for a change not yet released (rule C5). */
+        readonly since: string | null;
         readonly notationLocal: unknown;
         readonly body: string;
     };
@@ -268,7 +357,317 @@ interface ContextReport {
     readonly diagnostics: readonly CliDiagnostic[];
     readonly tokens: TokenCounts;
 }
+/**
+ * The migration guide, cut to the sections an upgrade needs: from the
+ * version a course pins to the version it has installed, oldest first. The
+ * guide is one newest-first file of every release; an upgrade reads one or
+ * two sections of it, and the heading grammar `## <from> → <to>` (a `0.4.x`
+ * range on the left, `Unreleased` allowed on the right) says which.
+ */
+interface MigrationSection {
+    readonly from: string;
+    readonly to: string;
+    readonly heading: string;
+    readonly markdown: string;
+    readonly tokens: number;
+}
+interface MigrateReport {
+    readonly from: string;
+    readonly to: string;
+    readonly file: string;
+    readonly sections: readonly MigrationSection[];
+    readonly tokens: number;
+}
+/** Every `## <from> → <to>` section of the guide, in file order (newest first). */
+declare function parseMigrationSections(markdown: string): MigrationSection[];
+/**
+ * The sections that take a course from `from` to `to`, oldest first: each
+ * section's left side matches where the previous one ended. A hole in the
+ * chain is an error naming the version no section continues from, since a
+ * skipped section is a skipped migration.
+ */
+declare function selectMigrationPath(sections: readonly MigrationSection[], from: string, to: string): MigrationSection[];
+/** The engine version the course has installed: the package beside it, or this one. */
+declare function installedEngineVersion(): string | undefined;
+/**
+ * The engine version `package.json` pins at HEAD — what the course last
+ * migrated to, before the working tree bumped it. `workspace:*` or a range
+ * is no version, so the caller asks for `--from`.
+ */
+declare function pinnedEngineVersion(): string | undefined;
+declare function contentMigrate(options?: {
+    readonly from?: string;
+    readonly to?: string;
+}): MigrateReport;
+/** The sections, oldest first, under one line that says how much is coming. */
+declare function formatMigrateReport(report: MigrateReport): string;
+/**
+ * What a lesson's math binds, span by span, before a build says so: each
+ * glyph and the card it resolves to, how (`canonical`, `family`, `derived`,
+ * `base`, `operator`, or an explicit `\explain` wrap), the wraps the bare
+ * symbol would have resolved without, and every unresolved glyph with where
+ * `content symbol` finds it defined. The same resolver and scope the
+ * completeness gate uses, so what it prints is what the build will do.
+ */
+interface SpanBinding {
+    readonly token: string;
+    readonly key: string;
+    /** The resolver's match kind; `explicit` for an `\explain` wrap. */
+    readonly how: string;
+}
+interface ExplicitWrap {
+    readonly key: string;
+    readonly inner: string;
+    /** The bare `inner` resolves to exactly this card: the wrap costs tokens and binds nothing new. */
+    readonly redundant: boolean;
+}
+interface UnresolvedGlyph {
+    readonly token: string;
+    readonly suspended?: string;
+    /** Rule N23: indexed entries whose base this bare letter is; none lends it a card. */
+    readonly lenders?: readonly string[];
+    /** Where `content symbol` finds the token defined: exact hits, then near misses. */
+    readonly defined: readonly {
+        readonly tier: SymbolTier;
+        readonly key: string;
+        readonly where: string;
+    }[];
+    readonly near: readonly {
+        readonly latex: string;
+        readonly key: string;
+    }[];
+}
+interface SpanBindings {
+    readonly bindings: readonly SpanBinding[];
+    readonly wraps: readonly ExplicitWrap[];
+    readonly unresolved: readonly Omit<UnresolvedGlyph, 'defined' | 'near'>[];
+    /** The resolver rejected the span (a KaTeX parse error or a rule it enforces, N13 say); its message. */
+    readonly error?: string;
+}
+interface BindingsSpan extends Omit<SpanBindings, 'unresolved'> {
+    readonly line: number;
+    readonly column: number;
+    readonly display: boolean;
+    readonly latex: string;
+    readonly unresolved: readonly UnresolvedGlyph[];
+}
+interface BindingsReport {
+    readonly lesson: string;
+    readonly file: string;
+    readonly scope: readonly {
+        readonly key: string;
+        readonly notation: string;
+        readonly scope: 'shared' | 'local';
+    }[];
+    readonly spans: readonly BindingsSpan[];
+    readonly counts: {
+        readonly spans: number;
+        readonly bindings: number;
+        readonly unresolved: number;
+        readonly wraps: number;
+        readonly redundantWraps: number;
+        readonly errors: number;
+    };
+}
+/**
+ * One span against a scope. Exported for tests and for a caller with a span
+ * of its own (`content equation`).
+ */
+declare function spanBindings(latex: string, scope: readonly ScopeEntry[], options?: {
+    readonly suspended?: readonly string[];
+    readonly derive?: boolean;
+}): SpanBindings;
+declare function contentBindings(manifest: Manifest, rawId: string): BindingsReport;
+/** The text form: a counts line, the scope, then one line per span. */
+declare function formatBindingsReport(report: BindingsReport): string;
+/**
+ * One LaTeX string, resolved the way the gate will: against a lesson's
+ * scope, or against every shared card when no lesson is named (the table a
+ * notation entry's body and formula use). The inner loop while drafting:
+ * a few lines out, non-zero exit when the build would refuse the span.
+ */
+interface EquationReport extends Omit<SpanBindings, 'unresolved'> {
+    readonly latex: string;
+    readonly against: {
+        readonly kind: 'lesson';
+        readonly lesson: string;
+        readonly cards: number;
+    } | {
+        readonly kind: 'shared';
+        readonly cards: number;
+    };
+    readonly unresolved: readonly UnresolvedGlyph[];
+    readonly ok: boolean;
+}
+declare function contentEquation(manifest: Manifest, latex: string, options?: {
+    readonly lesson?: string;
+}): EquationReport;
+declare function formatEquationReport(report: EquationReport): string;
+/**
+ * The refactors a model gets wrong most and reads most for, as deterministic
+ * edits: every one is planned first (`FileEdit`s with the whole text before
+ * and after), shown as a unified diff, and written only on `--write`.
+ */
+interface FileEdit {
+    /** Course-relative path. */
+    readonly file: string;
+    /** `null` when the file is created. */
+    readonly before: string | null;
+    /** `null` when the file is deleted. */
+    readonly after: string | null;
+}
+interface EditPlan {
+    readonly summary: readonly string[];
+    readonly edits: readonly FileEdit[];
+    /** What to run after writing. */
+    readonly next: readonly string[];
+}
+/** `[[old]]` and `\explain{old}` become `new`; nothing else is touched. Returns the count. */
+declare function rewriteKeyReferences(text: string, oldKey: string, newKey: string): {
+    text: string;
+    count: number;
+};
+/**
+ * Remove one `notation.local` item from a lesson file's text, by key, keeping
+ * the rest of the frontmatter byte for byte. An item runs from its `- key:`
+ * line to the next line indented no deeper than the dash; an emptied list
+ * becomes `local: []`.
+ */
+declare function removeLocalItem(text: string, key: string): {
+    text: string;
+    removed: boolean;
+};
+/** A shared card's file from a page-local entry's fields, nothing invented. */
+declare function sharedCardFromLocal(local: Record<string, unknown>, options: {
+    readonly key: string;
+    readonly fromLesson: string;
+}): string;
+/**
+ * `content move <lesson>:<key> [--to <key>]`: a page-local entry becomes a
+ * shared card. Every lesson that declares the key loses its copy (the card
+ * serves them all; copies that differ are reported, the named lesson's text
+ * wins), and with `--to` every `[[key]]` and `\explain{key}` follows.
+ */
+declare function planMove(manifest: Manifest, lessonId: string, key: string, options?: {
+    readonly to?: string;
+}): EditPlan;
+/** `content rename <old> <new>`: a shared card's key, everywhere it is named. */
+declare function planRename(manifest: Manifest, oldKey: string, newKey: string): EditPlan;
+/**
+ * `content fix <lesson>`: the diagnostics with one mechanical repair, applied.
+ * Today: every `\explain{key}{inner}` the gate reports as `explain-redundant`
+ * becomes `inner`.
+ */
+declare function planFix(manifest: Manifest, lessonId: string): EditPlan;
+/** The plan as a unified diff (git's), file by file, under its summary lines. */
+declare function renderEditPlan(plan: EditPlan): string;
+/** Write a plan's edits. Returns the files touched. */
+declare function applyEditPlan(plan: EditPlan): string[];
+/**
+ * The engine's course-facing agent procedures (`docs/course-agent/`): skills,
+ * the `rules-reviewer` agent and the `AGENTS.md` baseline, beside the
+ * installed package or above this module.
+ */
+declare function courseAgentDir(): string | undefined;
+/**
+ * `content init-agent [--write]`: install or refresh the engine's agent
+ * procedures in this course — every skill under `.claude/skills/`, the
+ * reviewer under `.claude/agents/` — and, only when the course has no
+ * `AGENTS.md`, the baseline one. An existing `AGENTS.md` is never edited;
+ * when it does not point at the engine's guide, the plan says what to add.
+ */
+declare function planInitAgent(): EditPlan;
+/**
+ * One rule, whole: the catalog entry as this course has it (enforcement,
+ * codes, settings in effect, whether it is on) and the rule page's own
+ * section, example included. About half a thousand tokens where opening the
+ * page costs twenty thousand.
+ */
+interface RuleReport {
+    readonly id: string;
+    readonly status: 'in-effect' | 'retired' | 'unknown';
+    readonly rule?: RuleInEffect;
+    readonly retired?: RetiredRule;
+    /** The rule page's section for this rule, when the page is at hand. */
+    readonly section?: {
+        readonly file: string;
+        readonly markdown: string;
+        readonly tokens: number;
+    };
+    /** For `unknown`: the IDs this course has, so the caller can pick one. */
+    readonly known: readonly string[];
+}
+/**
+ * The engine's `docs/authoring/`: beside the installed package in a course
+ * (`node_modules/explico/docs/authoring`, the path the rules-in-effect page
+ * links), or above this module in the repository and in the package itself.
+ */
+declare function authoringDocsDir(): string | undefined;
+/**
+ * The section of a rule page that `anchor` names: from the heading whose
+ * slug is the anchor (`## N4` → `n4`, `## Reference systems` →
+ * `reference-systems`) to the next heading of the same or a higher level,
+ * trailing rules and blank lines dropped.
+ */
+declare function ruleSection(page: string, anchor: string): string | undefined;
+declare function contentRule(manifest: Manifest, rawId: string): RuleReport;
+/** The text form of a rule report: the entry's facts, then the page section. */
+declare function formatRuleReport(report: RuleReport): string;
 declare function contentContext(manifest: Manifest, rawId: string): ContextReport;
+/**
+ * Where a symbol is already defined, asked before an author declares it
+ * again. Reads the registry the manifest holds: shared cards, page-local
+ * entries (`notation.local`) and glosses (a card's `glosses:`), matched on
+ * the latex as written, a shared card's `aliases`, or the key. A `contains`
+ * list follows for a letter that sits inside a longer notation (`v` in
+ * `v_0`), so a near miss is visible too. Read-only; every list is sorted,
+ * so two runs print the same report.
+ */
+type SymbolTier = 'shared' | 'local' | 'gloss';
+interface SymbolHit {
+    readonly tier: SymbolTier;
+    readonly key: string;
+    readonly latex: string;
+    readonly label: string;
+    readonly meaning?: string;
+    readonly units?: string;
+    /** How the query matched: the latex as written, an alias, or the key. */
+    readonly matchedBy: 'latex' | 'alias' | 'key';
+    /** shared: the entry file; local: the lesson id; gloss: the owning card. */
+    readonly where: string;
+    /** shared only: the pages (lessons and overview pages) whose bundle binds the card. */
+    readonly boundIn?: readonly string[];
+}
+interface SymbolReport {
+    readonly query: string;
+    readonly shared: readonly SymbolHit[];
+    readonly local: readonly SymbolHit[];
+    readonly glosses: readonly SymbolHit[];
+    /** Entries whose latex contains the query as a glyph, not matched above. */
+    readonly contains: readonly SymbolHit[];
+    /** How many `contains` candidates there were before the list was capped. */
+    readonly containsTotal: number;
+}
+declare function contentSymbol(manifest: Manifest, rawQuery: string): SymbolReport;
+/**
+ * The text form of a symbol report: one block per tier, then the near
+ * misses, then one line that counts what was found, worded for the next
+ * step an author takes.
+ */
+declare function formatSymbolReport(report: SymbolReport): string;
+/**
+ * A page `content check` checks: a lesson's (its chapter, or a slides-first
+ * lesson's deck), or a deck beside its chapter or a part's, by its page id.
+ */
+type CheckTarget = Pick<ManifestLesson, 'id' | 'file' | 'assessments'> & {
+    readonly notation: Pick<ManifestLesson['notation'], 'definitionIds'>;
+};
+/**
+ * The lesson `rawId` names, or the deck whose page it names: a deck beside
+ * its chapter by its route (`motion/range/slides`), a part's deck by its own
+ * (`motion/slides`).
+ */
+declare function findCheckTarget(manifest: Manifest, rawId: string): CheckTarget;
 interface CheckLessonResult {
     readonly lesson: string;
     readonly file: string;
@@ -299,6 +698,22 @@ interface Scaffold {
     }[];
 }
 declare function scaffoldLesson(rawId: string): Scaffold;
+/**
+ * `content new deck <lesson>`: the slide edition of a lesson, as a draft to
+ * rewrite (`docs/authoring/deck.md`). Beside an existing chapter it starts
+ * from the chapter: a `##` section per chapter section, a `###` frame per
+ * subsection (or one for a section without any), a `<Recall>` for each
+ * numbered equation, figure, table and diagram there, and the section's first
+ * sentence in the frame's notes. Without a chapter it is a slides-first
+ * lesson, with the lesson's frontmatter and a skeleton frame.
+ *
+ * `content new deck <part>`, for a part's directory with its page
+ * (`index.mdx`), drafts the part's deck (`<part>/index.deck.mdx`): a
+ * `## <chapter title> [chapter: <name>]` section per chapter, in the order
+ * the tracks read them, and a frame per section of the chapter, with a
+ * `<Recall>` for each float it numbers and its first sentence in the notes.
+ */
+declare function scaffoldDeck(rawId: string): Scaffold;
 declare function scaffoldTerm(rawKey: string): Scaffold;
 
-export { type CheckLessonResult, type CheckReport, type CliDiagnostic, type ContentCliCode, ContentCliError, type ContextReport, type DiagnosticThreshold, type DiagnosticsReport, type DomainFileSignatures, type RenderResult, type RulesReport, type Scaffold, type StatusReport, type TokenCounts, type WarningsReport, changedLessonIds, contentCheck, contentContext, contentDiagnostics, contentRules, contentStatus, contentWarnings, estimateTokens, findLesson, lessonDiagnostics, lessonSource, normalizeLessonId, parseRulesFilter, renderLesson, scaffoldLesson, scaffoldTerm };
+export { type BindingsReport, type BindingsSpan, type CheckLessonResult, type CheckReport, type CheckTarget, type CliDiagnostic, type ContentCliCode, ContentCliError, type ContextReport, type DiagnosticThreshold, type DiagnosticsReport, type DiagnosticsSummary, type DomainFileSignatures, type EditPlan, type EquationReport, type ExplicitWrap, type FileEdit, type MigrateReport, type MigrationSection, type RenderResult, type RuleReport, type RulesReport, type Scaffold, type SpanBinding, type SpanBindings, type StatusReport, type SymbolHit, type SymbolReport, type SymbolTier, type TokenCounts, type UnresolvedGlyph, type WarningsReport, applyEditPlan, authoringDocsDir, changedLessonIds, contentBindings, contentCheck, contentContext, contentDiagnostics, contentEquation, contentMigrate, contentRule, contentRules, contentStatus, contentSymbol, contentWarnings, courseAgentDir, estimateTokens, filterDiagnostics, findCheckTarget, findLesson, formatBindingsReport, formatCliDiagnostic, formatDiagnosticsSummary, formatEquationReport, formatMigrateReport, formatRuleReport, formatSymbolReport, installedEngineVersion, lessonDiagnostics, lessonSource, normalizeLessonId, ownerTag, parseMigrationSections, parseRulesFilter, pinnedEngineVersion, planFix, planInitAgent, planMove, planRename, removeLocalItem, renderEditPlan, renderLesson, rewriteKeyReferences, ruleSection, scaffoldDeck, scaffoldLesson, scaffoldTerm, selectMigrationPath, sharedCardFromLocal, spanBindings, summarizeDiagnostics };