@domandigital/craft 0.9.0 → 0.11.0

package/dist/index.d.cts

@@ -1031,7 +1031,7 @@ interface CheckReport {
  * Bumped whenever an entry is added, removed or its detection changes, so a
  * report can say which list it was judged against.
  */
-declare const CATALOGUE_VERSION = "2026.09.7";
+declare const CATALOGUE_VERSION = "2026.09.8";
 declare const CATALOGUE: readonly Tell[];
 declare function tellById(id: string): Tell | undefined;
 /**
@@ -1147,6 +1147,231 @@ interface FactComparison {
 declare function compareFacts(before: string, after: string): FactComparison;
 declare function formatComparison(result: FactComparison, beforePath: string, afterPath: string): string;
 
+/**
+ * The claims list: every sentence a reader would take as a checkable fact.
+ *
+ * No tell can say whether "Bark charges £2,000 to £7,000" is true. The worst
+ * faults in the DD article that set this off (2026-09-24) were figures like
+ * that: a wrong range, an unsourced day rate, a study quoted past what it
+ * found. Every one passed the copy check, because the prose was fine.
+ *
+ * So this does not judge. It lists each sentence holding a price, a figure, a
+ * date or a named source, marks whether the sentence names where it came
+ * from, and leaves the verdict to a person with the primary source open.
+ * "Sourced" means a source is named, not that it says what the sentence
+ * claims: that is exactly what the person checks.
+ *
+ * Pure over text. `craft copy claims <paths...>` is the command.
+ */
+
+interface Claim {
+    path: string;
+    line: number;
+    /** The sentence, trimmed to a readable length. */
+    sentence: string;
+    /** The prices, figures and dates in it. */
+    facts: Fact[];
+    /** Who the sentence says it comes from: a name, a publication or a link. Empty when nobody is named. */
+    sources: string[];
+    /**
+     * A source named earlier in the same paragraph. A hint for the person, never
+     * a pass: the sentence may be the writer's own arithmetic on top of it.
+     */
+    nearby?: string[];
+}
+interface ClaimsReport {
+    files: number;
+    claims: Claim[];
+    unsourced: number;
+}
+declare function namedSources(sentence: string): string[];
+declare function findClaims(files: SourceFile[]): ClaimsReport;
+declare function formatClaims(report: ClaimsReport, label?: string): string;
+
+/**
+ * Baselines: adopt craft on a repo that already has findings, and fail only
+ * on new ones.
+ *
+ * A finding is keyed on its tell, its path and a hash of its excerpt with the
+ * whitespace collapsed, never on its line: an edit above a known finding
+ * moves it, and a moved finding is not a new one. Keys are counted, so a file
+ * with two identical findings and a baseline of one reports the second.
+ *
+ * Pure. The command line reads and writes the file.
+ */
+
+declare const BASELINE_VERSION = 1;
+interface BaselineEntry {
+    tell: string;
+    path: string;
+    /** FNV-1a of the excerpt, whitespace collapsed. */
+    excerpt: string;
+    count: number;
+}
+interface Baseline {
+    version: typeof BASELINE_VERSION;
+    catalogueVersion: string;
+    entries: BaselineEntry[];
+}
+/** The key a finding is matched on. Also the SARIF partial fingerprint. */
+declare function findingKey(f: Finding): string;
+/** Every finding in a report, as a baseline. */
+declare function createBaseline(report: CheckReport): Baseline;
+/** Validate a parsed baseline file. */
+declare function parseBaseline(data: unknown, source?: string): Baseline;
+/**
+ * The report without the findings the baseline already knows about.
+ * `baselined` is how many were removed, so the output can say so: a
+ * baseline that hides findings silently is a hole.
+ */
+declare function applyBaseline(report: CheckReport, baseline: Baseline): CheckReport & {
+    baselined: number;
+};
+
+/**
+ * `craft.config.json`: what a repo tells craft about itself.
+ *
+ * Pure: the command line reads the file and hands the parsed JSON here. The
+ * design choices live in `art-direction.json`; this file is about the tool:
+ * which paths are not the site, where the copy is, and a repo's own decisions
+ * about a tell's severity.
+ *
+ *   {
+ *     "ignore": ["docs/archive/**", "*.stories.tsx"],
+ *     "copyPaths": ["content", "src/app"],
+ *     "severity": {
+ *       "ai-violet": { "level": "off", "because": "The client's shopfront has been this violet since 1998." },
+ *       "em-dash": { "level": "block", "because": "House style for this client bans them outright." }
+ *     }
+ *   }
+ *
+ * A severity change needs a `because`, like an exception in
+ * `art-direction.json`, and for the same reason: a tell switched off with no
+ * reason is a guard nobody can audit. `off` becomes an exception, so the
+ * report still lists what it silenced.
+ */
+
+type SeverityLevel = "warn" | "block" | "off";
+interface SeverityOverride {
+    level: SeverityLevel;
+    because: string;
+}
+interface CraftConfig {
+    /** Glob patterns for paths that are not the site. Added to `DEFAULT_IGNORE`. */
+    ignore: string[];
+    /** Where `craft copy` looks when no path is given. */
+    copyPaths?: string[];
+    severity: Record<string, SeverityOverride>;
+}
+/**
+ * Agent and tool folders: instructions for the people and models building
+ * the site, not copy a visitor reads. Always ignored by a directory walk.
+ */
+declare const DEFAULT_IGNORE: string[];
+/**
+ * Validate a parsed `craft.config.json`. Throws with the file name and the
+ * key at fault: a config that half-applies is worse than one that stops the
+ * run.
+ */
+declare function parseCraftConfig(data: unknown, knownTells: ReadonlySet<string>, source?: string): CraftConfig;
+/**
+ * A glob as a regular expression over a `/`-separated relative path.
+ * `*` is one segment's worth, `**` any depth, `?` one character. A pattern
+ * with no `/` matches a file or folder of that name anywhere; otherwise it is
+ * anchored at the repo root. Anything under a matched folder matches too.
+ */
+declare function globToRegExp(glob: string): RegExp;
+/** A matcher for a set of globs. Paths are normalised to `/` before matching. */
+declare function ignoreMatcher(patterns: string[]): (path: string) => boolean;
+/** `off` entries, as exceptions: applied, and listed as silenced in the report. */
+declare function severityExceptions(config: CraftConfig): TellException[];
+/** `warn` and `block` entries, applied to a finished report. */
+declare function applySeverity(report: CheckReport, config: CraftConfig): CheckReport;
+
+/**
+ * A report as SARIF 2.1.0, for GitHub code scanning and any other tool that
+ * reads it. Pure.
+ *
+ * One rule per tell the report names, carrying the tell's `why` and `fix`.
+ * `block` findings are errors, `warn` findings warnings. A finding on a
+ * rendered page has the URL as its location and no line: GitHub code
+ * scanning only shows results in files of the repo, so those appear in the
+ * SARIF file but not in the Security tab.
+ */
+
+interface SarifTell {
+    id: string;
+    name: string;
+    why: string;
+    fix: string;
+}
+interface SarifOptions {
+    /** The catalogue, for each rule's description. */
+    tells: readonly SarifTell[];
+    /** Where a reader learns more. */
+    informationUri?: string;
+}
+declare function toSarif(report: CheckReport, options: SarifOptions): {
+    $schema: string;
+    version: "2.1.0";
+    runs: {
+        tool: {
+            driver: {
+                name: string;
+                version: string;
+                informationUri: string;
+                rules: {
+                    fullDescription?: {
+                        text: string;
+                    } | undefined;
+                    help?: {
+                        text: string;
+                    } | undefined;
+                    id: string;
+                    name: string;
+                    shortDescription: {
+                        text: string;
+                    };
+                }[];
+            };
+        };
+        results: {
+            ruleId: string;
+            ruleIndex: number;
+            level: "error" | "warning";
+            message: {
+                text: string;
+            };
+            locations: {
+                physicalLocation: {
+                    region?: {
+                        startLine: number;
+                        snippet: {
+                            text: string;
+                        };
+                    } | undefined;
+                    artifactLocation: {
+                        uri: string;
+                    };
+                };
+            }[];
+            partialFingerprints: {
+                "craftFinding/v1": string;
+            };
+        }[];
+    }[];
+};
+
+/**
+ * The `--json` contract. Every JSON document a craft command prints carries
+ * `schemaVersion`, so a script reading it can refuse a shape it does not
+ * know instead of misreading it. Bump it when a field is removed or changes
+ * meaning; adding a field is not a bump.
+ */
+declare const JSON_SCHEMA_VERSION = 1;
+/** A command's JSON output, versioned. */
+declare function toJson(data: object): string;
+
 /**
  * The rendered detection path for tells that can be seen on a live page.
  *
@@ -1779,4 +2004,4 @@ declare function characterReport(input: CharacterInputs, copyTells?: Set<string>
 
 declare function retrofitPlan(report: CharacterReport, direction?: ArtDirection | null): string;
 
-export { AI_PHRASES, AI_VIOLET, AI_WORDS, type AccentFork, type AccentForkOptions, type Action, type Area, type ArtDirection, BUZZWORDS, CATALOGUE, CATALOGUE_VERSION, CHOICE_KEYS, type CandidateKind, type CharacterInputs, type CharacterReport, type CheckOptions, type CheckReport, type CheckRestraintInput, type ChoiceKey, type ContrastCheck, type ContrastReport, type CopyTell, type CraftTokensInput, type CraftTokensResult, DENSITIES, DENSITY_NAMES, DIRECTION_VERSION, DISTANCE_WEIGHTS, DURATION_MS, DURATION_S, type DensityCssOptions, type DensityName, type DirectionChoice, type DirectionProblem, type DirectionReport, type DirectionSource, type DurationName, EASE, EASE_TUPLE, ESTATE_VERSION, EXIT_RATIO, type EaseName, type EmitCssOptions, type EstateMatch, type EstatePair, type EstateRegister, type EstateSite, FINGERPRINT_VERSION, type Fact, type FactComparison, type FactKind, type Finding, type Fingerprint, type FingerprintDistance, type FluidSpaceOptions, type FluidTypeOptions, type FluidTypeResult, type FontClass, type Gamut, type Generation, HOUSE, HOUSE_BUDGET, HOUSE_TYPE, type HarvestCandidate, type HarvestOptions, type Hit, type HouseRule, type HouseTier, LIGHTNESS_CURVE, MIN_DECIDED, MIN_RUNS, type MotionDecision, type MotionKind, NEGATIVE_REASSURANCE, NULL_VERSION, type NullModel, type NullRun, type Oklch, type OklchToHexOptions, PILL_LIMIT, PLAINER_WORDS, PROPOSED, type PaletteColour, type Proposal, type ProposeInput, RAMP_STEPS, REFLEX_FONTS_1, REFLEX_FONTS_2, RENDERED_PATHS, REVEAL_LIMIT, REVIEW_PHRASES, type Ramp, type RampFromAnchorsOptions, type RampOptions, type RampStep, type RestraintBudget, type RestraintReport, type RestraintSeverity, type RestraintViolation, type Rgb, SCALE, SHADCN_LIMIT, SHADCN_PRIMITIVES, SIBLING_AT, SNAPSHOT_VERSION, SOURCE_KINDS, SPACE_STEPS, SPRING, STOCK_PHRASES, type SectionKind, type SectionRhythmOptions, type SemanticInput, type SemanticResult, type Severity, type ShouldAnimateInput, type SignalResult, type Snapshot, type SnapshotColour, type SnapshotControl, type SnapshotEffects, type SnapshotFont, type SnapshotGradient, type SnapshotHeading, type SnapshotMotion, type SnapshotPatch, type SnapshotSection, type SourceFile, type SourceKind, type SourceTell, type SpaceStep, type Surface, TELL_HEAVY, TYPE_STEPS, TYPICAL_AT, type TailwindPreset, type Tell, type TellException, type TypeStep, type Typicality, VAGUE_WORDS, type ValidateContext, type Verdict, accentFork, addSite, apcaContrast, applyHouseGate, auditSnapshot, catalogueTable, characterReport, checkCopy, checkPair, checkRestraint, choicesOf, compareFacts, compareToEstate, craftTokens, deltaEOk, deltaEOkHex, densityCss, densityTokens, emitCss, emptyEstate, estatePairs, exitDuration, extractHtml, findColours, fingerprint, fingerprintDistance, fluidClamp, fluidSpace, fluidType, fontClass, formatComparison, formatHex, formatReport, groundName, harvest, hexToOklch, houseRule, hueName, hueSwatch, inP3Gamut, inSrgbGamut, initDirection, isAiViolet, isCream, makeSnapshot, motionTokens, nearest, normaliseFamily, nullPrompt, oklchToHex, oklchToRgb, paletteFromPixels, parseColour, parseHex, propose, protectedFacts, ramp, rampFromAnchors, retrofitPlan, runTell, scanSource, sectionRhythm, semantic, shapeName, sharedParts, shouldAnimate, siblingLine, tailwindV3Preset, tailwindV4Theme, tellById, toGamut, typeFeatureTokens, typicality, validateDirection, visibleText, wcagContrast, wordListsJson };
+export { AI_PHRASES, AI_VIOLET, AI_WORDS, type AccentFork, type AccentForkOptions, type Action, type Area, type ArtDirection, BASELINE_VERSION, BUZZWORDS, type Baseline, type BaselineEntry, CATALOGUE, CATALOGUE_VERSION, CHOICE_KEYS, type CandidateKind, type CharacterInputs, type CharacterReport, type CheckOptions, type CheckReport, type CheckRestraintInput, type ChoiceKey, type Claim, type ClaimsReport, type ContrastCheck, type ContrastReport, type CopyTell, type CraftConfig, type CraftTokensInput, type CraftTokensResult, DEFAULT_IGNORE, DENSITIES, DENSITY_NAMES, DIRECTION_VERSION, DISTANCE_WEIGHTS, DURATION_MS, DURATION_S, type DensityCssOptions, type DensityName, type DirectionChoice, type DirectionProblem, type DirectionReport, type DirectionSource, type DurationName, EASE, EASE_TUPLE, ESTATE_VERSION, EXIT_RATIO, type EaseName, type EmitCssOptions, type EstateMatch, type EstatePair, type EstateRegister, type EstateSite, FINGERPRINT_VERSION, type Fact, type FactComparison, type FactKind, type Finding, type Fingerprint, type FingerprintDistance, type FluidSpaceOptions, type FluidTypeOptions, type FluidTypeResult, type FontClass, type Gamut, type Generation, HOUSE, HOUSE_BUDGET, HOUSE_TYPE, type HarvestCandidate, type HarvestOptions, type Hit, type HouseRule, type HouseTier, JSON_SCHEMA_VERSION, LIGHTNESS_CURVE, MIN_DECIDED, MIN_RUNS, type MotionDecision, type MotionKind, NEGATIVE_REASSURANCE, NULL_VERSION, type NullModel, type NullRun, type Oklch, type OklchToHexOptions, PILL_LIMIT, PLAINER_WORDS, PROPOSED, type PaletteColour, type Proposal, type ProposeInput, RAMP_STEPS, REFLEX_FONTS_1, REFLEX_FONTS_2, RENDERED_PATHS, REVEAL_LIMIT, REVIEW_PHRASES, type Ramp, type RampFromAnchorsOptions, type RampOptions, type RampStep, type RestraintBudget, type RestraintReport, type RestraintSeverity, type RestraintViolation, type Rgb, SCALE, SHADCN_LIMIT, SHADCN_PRIMITIVES, SIBLING_AT, SNAPSHOT_VERSION, SOURCE_KINDS, SPACE_STEPS, SPRING, STOCK_PHRASES, type SarifOptions, type SarifTell, type SectionKind, type SectionRhythmOptions, type SemanticInput, type SemanticResult, type Severity, type SeverityLevel, type SeverityOverride, type ShouldAnimateInput, type SignalResult, type Snapshot, type SnapshotColour, type SnapshotControl, type SnapshotEffects, type SnapshotFont, type SnapshotGradient, type SnapshotHeading, type SnapshotMotion, type SnapshotPatch, type SnapshotSection, type SourceFile, type SourceKind, type SourceTell, type SpaceStep, type Surface, TELL_HEAVY, TYPE_STEPS, TYPICAL_AT, type TailwindPreset, type Tell, type TellException, type TypeStep, type Typicality, VAGUE_WORDS, type ValidateContext, type Verdict, accentFork, addSite, apcaContrast, applyBaseline, applyHouseGate, applySeverity, auditSnapshot, catalogueTable, characterReport, checkCopy, checkPair, checkRestraint, choicesOf, compareFacts, compareToEstate, craftTokens, createBaseline, deltaEOk, deltaEOkHex, densityCss, densityTokens, emitCss, emptyEstate, estatePairs, exitDuration, extractHtml, findClaims, findColours, findingKey, fingerprint, fingerprintDistance, fluidClamp, fluidSpace, fluidType, fontClass, formatClaims, formatComparison, formatHex, formatReport, globToRegExp, groundName, harvest, hexToOklch, houseRule, hueName, hueSwatch, ignoreMatcher, inP3Gamut, inSrgbGamut, initDirection, isAiViolet, isCream, makeSnapshot, motionTokens, namedSources, nearest, normaliseFamily, nullPrompt, oklchToHex, oklchToRgb, paletteFromPixels, parseBaseline, parseColour, parseCraftConfig, parseHex, propose, protectedFacts, ramp, rampFromAnchors, retrofitPlan, runTell, scanSource, sectionRhythm, semantic, severityExceptions, shapeName, sharedParts, shouldAnimate, siblingLine, tailwindV3Preset, tailwindV4Theme, tellById, toGamut, toJson, toSarif, typeFeatureTokens, typicality, validateDirection, visibleText, wcagContrast, wordListsJson };

package/dist/index.d.ts

@@ -1031,7 +1031,7 @@ interface CheckReport {
  * Bumped whenever an entry is added, removed or its detection changes, so a
  * report can say which list it was judged against.
  */
-declare const CATALOGUE_VERSION = "2026.09.7";
+declare const CATALOGUE_VERSION = "2026.09.8";
 declare const CATALOGUE: readonly Tell[];
 declare function tellById(id: string): Tell | undefined;
 /**
@@ -1147,6 +1147,231 @@ interface FactComparison {
 declare function compareFacts(before: string, after: string): FactComparison;
 declare function formatComparison(result: FactComparison, beforePath: string, afterPath: string): string;
 
+/**
+ * The claims list: every sentence a reader would take as a checkable fact.
+ *
+ * No tell can say whether "Bark charges £2,000 to £7,000" is true. The worst
+ * faults in the DD article that set this off (2026-09-24) were figures like
+ * that: a wrong range, an unsourced day rate, a study quoted past what it
+ * found. Every one passed the copy check, because the prose was fine.
+ *
+ * So this does not judge. It lists each sentence holding a price, a figure, a
+ * date or a named source, marks whether the sentence names where it came
+ * from, and leaves the verdict to a person with the primary source open.
+ * "Sourced" means a source is named, not that it says what the sentence
+ * claims: that is exactly what the person checks.
+ *
+ * Pure over text. `craft copy claims <paths...>` is the command.
+ */
+
+interface Claim {
+    path: string;
+    line: number;
+    /** The sentence, trimmed to a readable length. */
+    sentence: string;
+    /** The prices, figures and dates in it. */
+    facts: Fact[];
+    /** Who the sentence says it comes from: a name, a publication or a link. Empty when nobody is named. */
+    sources: string[];
+    /**
+     * A source named earlier in the same paragraph. A hint for the person, never
+     * a pass: the sentence may be the writer's own arithmetic on top of it.
+     */
+    nearby?: string[];
+}
+interface ClaimsReport {
+    files: number;
+    claims: Claim[];
+    unsourced: number;
+}
+declare function namedSources(sentence: string): string[];
+declare function findClaims(files: SourceFile[]): ClaimsReport;
+declare function formatClaims(report: ClaimsReport, label?: string): string;
+
+/**
+ * Baselines: adopt craft on a repo that already has findings, and fail only
+ * on new ones.
+ *
+ * A finding is keyed on its tell, its path and a hash of its excerpt with the
+ * whitespace collapsed, never on its line: an edit above a known finding
+ * moves it, and a moved finding is not a new one. Keys are counted, so a file
+ * with two identical findings and a baseline of one reports the second.
+ *
+ * Pure. The command line reads and writes the file.
+ */
+
+declare const BASELINE_VERSION = 1;
+interface BaselineEntry {
+    tell: string;
+    path: string;
+    /** FNV-1a of the excerpt, whitespace collapsed. */
+    excerpt: string;
+    count: number;
+}
+interface Baseline {
+    version: typeof BASELINE_VERSION;
+    catalogueVersion: string;
+    entries: BaselineEntry[];
+}
+/** The key a finding is matched on. Also the SARIF partial fingerprint. */
+declare function findingKey(f: Finding): string;
+/** Every finding in a report, as a baseline. */
+declare function createBaseline(report: CheckReport): Baseline;
+/** Validate a parsed baseline file. */
+declare function parseBaseline(data: unknown, source?: string): Baseline;
+/**
+ * The report without the findings the baseline already knows about.
+ * `baselined` is how many were removed, so the output can say so: a
+ * baseline that hides findings silently is a hole.
+ */
+declare function applyBaseline(report: CheckReport, baseline: Baseline): CheckReport & {
+    baselined: number;
+};
+
+/**
+ * `craft.config.json`: what a repo tells craft about itself.
+ *
+ * Pure: the command line reads the file and hands the parsed JSON here. The
+ * design choices live in `art-direction.json`; this file is about the tool:
+ * which paths are not the site, where the copy is, and a repo's own decisions
+ * about a tell's severity.
+ *
+ *   {
+ *     "ignore": ["docs/archive/**", "*.stories.tsx"],
+ *     "copyPaths": ["content", "src/app"],
+ *     "severity": {
+ *       "ai-violet": { "level": "off", "because": "The client's shopfront has been this violet since 1998." },
+ *       "em-dash": { "level": "block", "because": "House style for this client bans them outright." }
+ *     }
+ *   }
+ *
+ * A severity change needs a `because`, like an exception in
+ * `art-direction.json`, and for the same reason: a tell switched off with no
+ * reason is a guard nobody can audit. `off` becomes an exception, so the
+ * report still lists what it silenced.
+ */
+
+type SeverityLevel = "warn" | "block" | "off";
+interface SeverityOverride {
+    level: SeverityLevel;
+    because: string;
+}
+interface CraftConfig {
+    /** Glob patterns for paths that are not the site. Added to `DEFAULT_IGNORE`. */
+    ignore: string[];
+    /** Where `craft copy` looks when no path is given. */
+    copyPaths?: string[];
+    severity: Record<string, SeverityOverride>;
+}
+/**
+ * Agent and tool folders: instructions for the people and models building
+ * the site, not copy a visitor reads. Always ignored by a directory walk.
+ */
+declare const DEFAULT_IGNORE: string[];
+/**
+ * Validate a parsed `craft.config.json`. Throws with the file name and the
+ * key at fault: a config that half-applies is worse than one that stops the
+ * run.
+ */
+declare function parseCraftConfig(data: unknown, knownTells: ReadonlySet<string>, source?: string): CraftConfig;
+/**
+ * A glob as a regular expression over a `/`-separated relative path.
+ * `*` is one segment's worth, `**` any depth, `?` one character. A pattern
+ * with no `/` matches a file or folder of that name anywhere; otherwise it is
+ * anchored at the repo root. Anything under a matched folder matches too.
+ */
+declare function globToRegExp(glob: string): RegExp;
+/** A matcher for a set of globs. Paths are normalised to `/` before matching. */
+declare function ignoreMatcher(patterns: string[]): (path: string) => boolean;
+/** `off` entries, as exceptions: applied, and listed as silenced in the report. */
+declare function severityExceptions(config: CraftConfig): TellException[];
+/** `warn` and `block` entries, applied to a finished report. */
+declare function applySeverity(report: CheckReport, config: CraftConfig): CheckReport;
+
+/**
+ * A report as SARIF 2.1.0, for GitHub code scanning and any other tool that
+ * reads it. Pure.
+ *
+ * One rule per tell the report names, carrying the tell's `why` and `fix`.
+ * `block` findings are errors, `warn` findings warnings. A finding on a
+ * rendered page has the URL as its location and no line: GitHub code
+ * scanning only shows results in files of the repo, so those appear in the
+ * SARIF file but not in the Security tab.
+ */
+
+interface SarifTell {
+    id: string;
+    name: string;
+    why: string;
+    fix: string;
+}
+interface SarifOptions {
+    /** The catalogue, for each rule's description. */
+    tells: readonly SarifTell[];
+    /** Where a reader learns more. */
+    informationUri?: string;
+}
+declare function toSarif(report: CheckReport, options: SarifOptions): {
+    $schema: string;
+    version: "2.1.0";
+    runs: {
+        tool: {
+            driver: {
+                name: string;
+                version: string;
+                informationUri: string;
+                rules: {
+                    fullDescription?: {
+                        text: string;
+                    } | undefined;
+                    help?: {
+                        text: string;
+                    } | undefined;
+                    id: string;
+                    name: string;
+                    shortDescription: {
+                        text: string;
+                    };
+                }[];
+            };
+        };
+        results: {
+            ruleId: string;
+            ruleIndex: number;
+            level: "error" | "warning";
+            message: {
+                text: string;
+            };
+            locations: {
+                physicalLocation: {
+                    region?: {
+                        startLine: number;
+                        snippet: {
+                            text: string;
+                        };
+                    } | undefined;
+                    artifactLocation: {
+                        uri: string;
+                    };
+                };
+            }[];
+            partialFingerprints: {
+                "craftFinding/v1": string;
+            };
+        }[];
+    }[];
+};
+
+/**
+ * The `--json` contract. Every JSON document a craft command prints carries
+ * `schemaVersion`, so a script reading it can refuse a shape it does not
+ * know instead of misreading it. Bump it when a field is removed or changes
+ * meaning; adding a field is not a bump.
+ */
+declare const JSON_SCHEMA_VERSION = 1;
+/** A command's JSON output, versioned. */
+declare function toJson(data: object): string;
+
 /**
  * The rendered detection path for tells that can be seen on a live page.
  *
@@ -1779,4 +2004,4 @@ declare function characterReport(input: CharacterInputs, copyTells?: Set<string>
 
 declare function retrofitPlan(report: CharacterReport, direction?: ArtDirection | null): string;
 
-export { AI_PHRASES, AI_VIOLET, AI_WORDS, type AccentFork, type AccentForkOptions, type Action, type Area, type ArtDirection, BUZZWORDS, CATALOGUE, CATALOGUE_VERSION, CHOICE_KEYS, type CandidateKind, type CharacterInputs, type CharacterReport, type CheckOptions, type CheckReport, type CheckRestraintInput, type ChoiceKey, type ContrastCheck, type ContrastReport, type CopyTell, type CraftTokensInput, type CraftTokensResult, DENSITIES, DENSITY_NAMES, DIRECTION_VERSION, DISTANCE_WEIGHTS, DURATION_MS, DURATION_S, type DensityCssOptions, type DensityName, type DirectionChoice, type DirectionProblem, type DirectionReport, type DirectionSource, type DurationName, EASE, EASE_TUPLE, ESTATE_VERSION, EXIT_RATIO, type EaseName, type EmitCssOptions, type EstateMatch, type EstatePair, type EstateRegister, type EstateSite, FINGERPRINT_VERSION, type Fact, type FactComparison, type FactKind, type Finding, type Fingerprint, type FingerprintDistance, type FluidSpaceOptions, type FluidTypeOptions, type FluidTypeResult, type FontClass, type Gamut, type Generation, HOUSE, HOUSE_BUDGET, HOUSE_TYPE, type HarvestCandidate, type HarvestOptions, type Hit, type HouseRule, type HouseTier, LIGHTNESS_CURVE, MIN_DECIDED, MIN_RUNS, type MotionDecision, type MotionKind, NEGATIVE_REASSURANCE, NULL_VERSION, type NullModel, type NullRun, type Oklch, type OklchToHexOptions, PILL_LIMIT, PLAINER_WORDS, PROPOSED, type PaletteColour, type Proposal, type ProposeInput, RAMP_STEPS, REFLEX_FONTS_1, REFLEX_FONTS_2, RENDERED_PATHS, REVEAL_LIMIT, REVIEW_PHRASES, type Ramp, type RampFromAnchorsOptions, type RampOptions, type RampStep, type RestraintBudget, type RestraintReport, type RestraintSeverity, type RestraintViolation, type Rgb, SCALE, SHADCN_LIMIT, SHADCN_PRIMITIVES, SIBLING_AT, SNAPSHOT_VERSION, SOURCE_KINDS, SPACE_STEPS, SPRING, STOCK_PHRASES, type SectionKind, type SectionRhythmOptions, type SemanticInput, type SemanticResult, type Severity, type ShouldAnimateInput, type SignalResult, type Snapshot, type SnapshotColour, type SnapshotControl, type SnapshotEffects, type SnapshotFont, type SnapshotGradient, type SnapshotHeading, type SnapshotMotion, type SnapshotPatch, type SnapshotSection, type SourceFile, type SourceKind, type SourceTell, type SpaceStep, type Surface, TELL_HEAVY, TYPE_STEPS, TYPICAL_AT, type TailwindPreset, type Tell, type TellException, type TypeStep, type Typicality, VAGUE_WORDS, type ValidateContext, type Verdict, accentFork, addSite, apcaContrast, applyHouseGate, auditSnapshot, catalogueTable, characterReport, checkCopy, checkPair, checkRestraint, choicesOf, compareFacts, compareToEstate, craftTokens, deltaEOk, deltaEOkHex, densityCss, densityTokens, emitCss, emptyEstate, estatePairs, exitDuration, extractHtml, findColours, fingerprint, fingerprintDistance, fluidClamp, fluidSpace, fluidType, fontClass, formatComparison, formatHex, formatReport, groundName, harvest, hexToOklch, houseRule, hueName, hueSwatch, inP3Gamut, inSrgbGamut, initDirection, isAiViolet, isCream, makeSnapshot, motionTokens, nearest, normaliseFamily, nullPrompt, oklchToHex, oklchToRgb, paletteFromPixels, parseColour, parseHex, propose, protectedFacts, ramp, rampFromAnchors, retrofitPlan, runTell, scanSource, sectionRhythm, semantic, shapeName, sharedParts, shouldAnimate, siblingLine, tailwindV3Preset, tailwindV4Theme, tellById, toGamut, typeFeatureTokens, typicality, validateDirection, visibleText, wcagContrast, wordListsJson };
+export { AI_PHRASES, AI_VIOLET, AI_WORDS, type AccentFork, type AccentForkOptions, type Action, type Area, type ArtDirection, BASELINE_VERSION, BUZZWORDS, type Baseline, type BaselineEntry, CATALOGUE, CATALOGUE_VERSION, CHOICE_KEYS, type CandidateKind, type CharacterInputs, type CharacterReport, type CheckOptions, type CheckReport, type CheckRestraintInput, type ChoiceKey, type Claim, type ClaimsReport, type ContrastCheck, type ContrastReport, type CopyTell, type CraftConfig, type CraftTokensInput, type CraftTokensResult, DEFAULT_IGNORE, DENSITIES, DENSITY_NAMES, DIRECTION_VERSION, DISTANCE_WEIGHTS, DURATION_MS, DURATION_S, type DensityCssOptions, type DensityName, type DirectionChoice, type DirectionProblem, type DirectionReport, type DirectionSource, type DurationName, EASE, EASE_TUPLE, ESTATE_VERSION, EXIT_RATIO, type EaseName, type EmitCssOptions, type EstateMatch, type EstatePair, type EstateRegister, type EstateSite, FINGERPRINT_VERSION, type Fact, type FactComparison, type FactKind, type Finding, type Fingerprint, type FingerprintDistance, type FluidSpaceOptions, type FluidTypeOptions, type FluidTypeResult, type FontClass, type Gamut, type Generation, HOUSE, HOUSE_BUDGET, HOUSE_TYPE, type HarvestCandidate, type HarvestOptions, type Hit, type HouseRule, type HouseTier, JSON_SCHEMA_VERSION, LIGHTNESS_CURVE, MIN_DECIDED, MIN_RUNS, type MotionDecision, type MotionKind, NEGATIVE_REASSURANCE, NULL_VERSION, type NullModel, type NullRun, type Oklch, type OklchToHexOptions, PILL_LIMIT, PLAINER_WORDS, PROPOSED, type PaletteColour, type Proposal, type ProposeInput, RAMP_STEPS, REFLEX_FONTS_1, REFLEX_FONTS_2, RENDERED_PATHS, REVEAL_LIMIT, REVIEW_PHRASES, type Ramp, type RampFromAnchorsOptions, type RampOptions, type RampStep, type RestraintBudget, type RestraintReport, type RestraintSeverity, type RestraintViolation, type Rgb, SCALE, SHADCN_LIMIT, SHADCN_PRIMITIVES, SIBLING_AT, SNAPSHOT_VERSION, SOURCE_KINDS, SPACE_STEPS, SPRING, STOCK_PHRASES, type SarifOptions, type SarifTell, type SectionKind, type SectionRhythmOptions, type SemanticInput, type SemanticResult, type Severity, type SeverityLevel, type SeverityOverride, type ShouldAnimateInput, type SignalResult, type Snapshot, type SnapshotColour, type SnapshotControl, type SnapshotEffects, type SnapshotFont, type SnapshotGradient, type SnapshotHeading, type SnapshotMotion, type SnapshotPatch, type SnapshotSection, type SourceFile, type SourceKind, type SourceTell, type SpaceStep, type Surface, TELL_HEAVY, TYPE_STEPS, TYPICAL_AT, type TailwindPreset, type Tell, type TellException, type TypeStep, type Typicality, VAGUE_WORDS, type ValidateContext, type Verdict, accentFork, addSite, apcaContrast, applyBaseline, applyHouseGate, applySeverity, auditSnapshot, catalogueTable, characterReport, checkCopy, checkPair, checkRestraint, choicesOf, compareFacts, compareToEstate, craftTokens, createBaseline, deltaEOk, deltaEOkHex, densityCss, densityTokens, emitCss, emptyEstate, estatePairs, exitDuration, extractHtml, findClaims, findColours, findingKey, fingerprint, fingerprintDistance, fluidClamp, fluidSpace, fluidType, fontClass, formatClaims, formatComparison, formatHex, formatReport, globToRegExp, groundName, harvest, hexToOklch, houseRule, hueName, hueSwatch, ignoreMatcher, inP3Gamut, inSrgbGamut, initDirection, isAiViolet, isCream, makeSnapshot, motionTokens, namedSources, nearest, normaliseFamily, nullPrompt, oklchToHex, oklchToRgb, paletteFromPixels, parseBaseline, parseColour, parseCraftConfig, parseHex, propose, protectedFacts, ramp, rampFromAnchors, retrofitPlan, runTell, scanSource, sectionRhythm, semantic, severityExceptions, shapeName, sharedParts, shouldAnimate, siblingLine, tailwindV3Preset, tailwindV4Theme, tellById, toGamut, toJson, toSarif, typeFeatureTokens, typicality, validateDirection, visibleText, wcagContrast, wordListsJson };