taste-lint 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,736 @@
+//#region src/analysis/repository.d.ts
+interface DocumentNode {
+  type: string;
+  value?: string;
+  url?: string;
+  identifier?: string;
+  depth?: number;
+  lang?: string | null;
+  children?: DocumentNode[];
+  position?: {
+    start: {
+      offset?: number;
+    };
+    end: {
+      offset?: number;
+    };
+  };
+}
+interface ImportFact {
+  name: string;
+  offset: number;
+  typeOnly: boolean;
+}
+interface SourceFacts {
+  document?: DocumentNode;
+  imports?: ImportFact[];
+  parseError?: string;
+  repository: Pick<Repository, "root" | "read" | "resolve" | "exists" | "manifest" | "policy">;
+}
+declare class Repository {
+  readonly root: string;
+  private readonly contents;
+  readonly policy?: ArchitecturePolicy;
+  constructor(root: string, policy?: ArchitecturePolicy);
+  resolve(file: string, target: string): string | undefined;
+  read(file: string): string | undefined;
+  exists(file: string): boolean;
+  manifest(file: string): {
+    file: string;
+    value: Record<string, unknown>;
+  } | undefined;
+}
+//#endregion
+//#region src/types.d.ts
+declare const DOMAINS: readonly ["typography", "craft", "copywriting", "interaction", "motion", "product", "architecture", "dx", "authoring"];
+type Domain = (typeof DOMAINS)[number];
+declare const UNIT_KINDS: readonly ["paragraph", "heading", "jsx-text", "attr-string", "class-list", "element",
+/** The whole file, for mechanical-only regex rules over raw source. */
+"source",
+/** A file that did not parse; carries the error and nothing else. */
+"file"];
+/** Kinds that are not a piece of copy and never count as units in a report. */
+declare const STRUCTURAL_KINDS: readonly UnitKind[];
+type UnitKind = (typeof UNIT_KINDS)[number];
+declare const TIERS: readonly ["mechanical", "jev", "both"];
+type Tier = (typeof TIERS)[number];
+declare const SEVERITIES: readonly ["major", "minor"];
+type Severity = (typeof SEVERITIES)[number];
+/** Lower is more severe; the single owner of severity ordering. */
+declare const SEVERITY_RANK: Record<Severity, number>;
+declare const RULE_STATUSES: readonly ["active", "draft", "review-only"];
+type RuleStatus = (typeof RULE_STATUSES)[number];
+declare const DOC_TYPES: readonly ["tutorial", "howto", "reference", "explanation", "agent-instructions", "lesson", "marketing", "ui", "readme", "skill", "plan", "personal", "pr", "slides", "unknown"];
+type DocType = (typeof DOC_TYPES)[number];
+declare const ROLES: readonly ["heading", "body", "list-item", "cell", "button", "link", "label", "placeholder", "aria", "literal-copy", "caption", "unknown"];
+type Role = (typeof ROLES)[number];
+declare const CONTEXT_KEYS: readonly ["section", "headingAbove", "docType", "element", "role", "neighbours", "writingFacts", "writingProfile", "writingInstructions"];
+type ContextKey = (typeof CONTEXT_KEYS)[number];
+type Band = "act" | "review" | "silent";
+interface RuleSource {
+  repo: string;
+  path: string;
+  line: number;
+  ruleId?: string;
+}
+interface Mechanical {
+  /** JavaScript regex source. Compiled with `flags` (default "gu"). */
+  regex?: string;
+  flags?: string;
+  /** Case-insensitive whole-phrase list. Word-boundary checked. */
+  phrases?: string[];
+  /** Minimum matches before the rule fires (default 1). */
+  minMatches?: number;
+  /** The rule fires only when this regex matches nowhere in the unit. */
+  absent?: string;
+}
+interface CriterionSide {
+  what: string;
+  examples: string[];
+}
+interface Question {
+  instructions: string;
+  criteria?: {
+    true: CriterionSide;
+    false: CriterionSide;
+  };
+  /** Context keys to include in the state for this question. */
+  context?: ContextKey[];
+}
+interface Thresholds {
+  review: number;
+  act: number;
+}
+interface Fix {
+  hint: string;
+  /** Named function in src/reduce/fixes.ts; present means `--fix` can apply it. */
+  function?: string;
+}
+interface Preconditions {
+  notInCode?: boolean;
+  docType?: DocType[];
+  role?: Role[];
+  /** Skip Markdown units when the project curls quotes at build time. */
+  smartQuotesAtBuild?: false;
+}
+interface Rule {
+  id: string;
+  title: string;
+  categoryId: string;
+  domain: Domain;
+  source: RuleSource;
+  /** Resolved: include derived from `unit` unless the rule names it. */
+  scope: {
+    include: string[];
+    exclude: string[];
+  };
+  unit: UnitKind[];
+  /** Derived: mechanical only, question only, or both. */
+  tier: Tier;
+  mechanical?: Mechanical;
+  question?: Question;
+  thresholds: Thresholds;
+  severity: Severity;
+  fix: Fix;
+  preconditions?: Preconditions;
+  status: RuleStatus;
+  handWritten: string[];
+  /** Absolute path of the YAML file the rule was loaded from, or `code:<module>`. */
+  file: string;
+  /**
+   * A code rule's check, in place of `mechanical`. Counts, compares and
+   * measures; throws UnresolvedError to abstain. Data rules never set it.
+   */
+  check?: (unit: Unit) => MechanicalHit;
+}
+interface TuningEntry {
+  act?: number;
+  status?: RuleStatus;
+  precisionLower?: number;
+  n?: number;
+  ts?: string;
+}
+type Tuning = Record<string, TuningEntry>;
+interface ResolvedTypography {
+  fontSizePx?: number;
+  lineHeight?: number;
+  lineHeightPx?: number;
+  letterSpacingEm?: number;
+  fontWeight?: number;
+  uppercase?: boolean;
+  italic?: boolean;
+  family?: "mono" | "sans" | "serif";
+  colourClasses: string[];
+  unresolved: string[];
+}
+interface NeighbourSummary {
+  text: string;
+  element?: string;
+  typography?: ResolvedTypography;
+}
+interface WritingContext {
+  facts?: string;
+  profile?: string;
+  instructions?: string;
+}
+interface UnitContext {
+  section?: string;
+  writingFacts?: string;
+  writingProfile?: string;
+  writingInstructions?: string;
+  headingAbove?: string;
+  docType: DocType;
+  element?: string;
+  attr?: string;
+  component?: string;
+  role: Role;
+  /** The className has parts this extractor could not read statically. */
+  dynamic?: boolean;
+  /** The className is a template literal with `${...}` inside a class. */
+  interpolated?: boolean;
+  parseError?: string;
+  mdxFallback?: boolean;
+}
+interface Unit {
+  facts?: SourceFacts;
+  /** Stable hash of file, kind and source offset. */
+  id: string;
+  kind: UnitKind;
+  /** Normalised rendered text, whitespace collapsed. */
+  text: string;
+  /** Relative to the scanned root, forward slashes. */
+  file: string;
+  line: number;
+  column: number;
+  endLine: number;
+  endColumn: number;
+  sourceStart: number;
+  sourceEnd: number;
+  inCode: boolean;
+  /** Ranges inside `text` that are code and must be skipped by regexes. */
+  codeSpans: [number, number][];
+  /**
+   * Source ranges (UTF-16 offsets into the file) holding prose a
+   * deterministic fix may rewrite: JSX text pieces, the inside of string
+   * literals, Markdown text nodes. Never quotes, braces, inline code or
+   * expressions. Absent means the unit cannot be fixed in place.
+   */
+  fixRanges?: [number, number][];
+  context: UnitContext;
+  typography?: ResolvedTypography;
+  neighbours?: {
+    prev?: NeighbourSummary;
+    next?: NeighbourSummary;
+  };
+  /** Class list for class-list and element units. */
+  classes?: string[];
+}
+interface MechanicalHit {
+  fired: boolean;
+  evidence: string;
+  /** Offset into `unit.text` of the first match; a source unit's finding line. */
+  offset?: number;
+}
+interface Finding {
+  ruleId: string;
+  categoryId: string;
+  domain: Domain;
+  severity: Severity;
+  band: Band;
+  probability: number;
+  tier: Tier;
+  unitId: string;
+  file: string;
+  line: number;
+  column: number;
+  endLine: number;
+  endColumn: number;
+  message: string;
+  evidence: string;
+  fixHint: string;
+  suppressed: boolean;
+  also?: string[];
+}
+interface Unknown {
+  ruleId: string;
+  unitId: string;
+  file: string;
+  line: number;
+  reason: string;
+}
+interface Scorecard {
+  byCategory: Record<string, {
+    domain: Domain;
+    units: number;
+    act: number;
+    review: number;
+    suppressed: number;
+    unknown: number;
+  }>;
+  byDomain: Record<string, {
+    units: number;
+    act: number;
+    review: number;
+    suppressed: number;
+    unknown: number;
+  }>;
+  byRule: Record<string, {
+    act: number;
+    review: number;
+    silent: number;
+    unknown: number;
+  }>;
+}
+interface Progress {
+  phase: "evaluating" | "complete";
+  completed: number;
+  planned: number;
+  cachedAnswers: number;
+  failed: number;
+  attempts: number;
+  elapsedMs: number;
+}
+interface Usage {
+  /** HTTP attempts when reported by the evaluator; absent for legacy evaluators. */
+  attempts?: number;
+  sharedAnswers?: number;
+  requests: number;
+  cached: number;
+  inputTokens: number;
+  costUsd: number;
+  errors: number;
+}
+type RunStatus = "complete" | "incomplete" | "dry-run";
+interface RunSummary {
+  act: number;
+  review: number;
+  unknown: number;
+  failing: number;
+  failOn: Severity;
+  ruleFindings: number;
+}
+interface Coverage {
+  byRule: Record<string, {
+    eligible: number;
+    skipped: number;
+    negative: number;
+    pending: number;
+    unknown: number;
+    answered: number;
+  }>;
+  byCategory: Record<string, {
+    eligibleUnits: number;
+    eligiblePairs: number;
+  }>;
+}
+interface ScanScope {
+  files: number;
+  units: number;
+  byDocType: Record<string, number>;
+  excluded: number;
+  diagnostics: string[];
+}
+interface LintResult {
+  summary?: RunSummary;
+  ruleFindings?: Finding[];
+  ruleScorecard?: Scorecard;
+  coverage?: Coverage;
+  scope?: ScanScope;
+  reportPath?: string;
+  rerun?: string;
+  status: RunStatus;
+  findings: Finding[];
+  unknowns: Unknown[];
+  scorecard: Scorecard;
+  usage: Usage;
+  units: number;
+  rules: string[];
+  estimated?: {
+    requests: number;
+    inputTokens: number;
+    costUsd: number;
+  };
+  exitCode: number;
+}
+type EntryValue = string | number | boolean | null | EntryValue[] | {
+  [key: string]: EntryValue;
+};
+interface SystemOneNoul {
+  type: "noul";
+  instructions: EntryValue;
+  criteria?: {
+    true?: EntryValue;
+    false?: EntryValue;
+  } | null;
+}
+interface SystemOneRequest {
+  model: string;
+  state: EntryValue;
+  questions: Record<string, SystemOneNoul>;
+}
+interface SystemOneResponse {
+  attempts?: number;
+  model: string;
+  answers: Record<string, {
+    type?: string;
+    noul?: number;
+  }>;
+  usage: {
+    input_tokens: number;
+    output_tokens: number;
+  };
+}
+type Evaluate = (request: SystemOneRequest, onAttempt?: () => void) => Promise<SystemOneResponse>;
+interface RecorderHandle {
+  append: (record: Record<string, unknown>) => Record<string, unknown>;
+  summary: (obj: Record<string, unknown>) => Record<string, unknown>;
+  file: string;
+}
+interface CorpusItem {
+  id: string;
+  kind: UnitKind;
+  text: string;
+  context?: Partial<UnitContext>;
+  neighbours?: Unit["neighbours"];
+  classes?: string[];
+  categoryId: string;
+  labels: Record<string, boolean>;
+  labelSource: "manifest" | "manifest-weak" | "hand" | "sweep" | "ai";
+  labelModel?: string;
+  labelPromptHash?: string;
+  source: {
+    repo: string;
+    path: string;
+    id?: string;
+    option?: string;
+  };
+  split: "dev" | "holdout";
+}
+interface ArchitecturePolicy {
+  boundaries?: {
+    from: string;
+    disallow: string;
+    reason: string;
+  }[];
+  deprecatedImports?: Record<string, string>;
+  generated?: string[];
+}
+interface Config {
+  architecture?: ArchitecturePolicy;
+  root: string;
+  docTypes: {
+    glob: string;
+    type: DocType;
+  }[];
+  components: {
+    unwrap: string[];
+    skip: string[];
+  };
+  tailwind: {
+    theme: Record<string, string>;
+  };
+  smartQuotesAtBuild: boolean;
+  exclude: string[];
+}
+//#endregion
+//#region src/lib/config.d.ts
+declare const loadConfig: (root: string, defaults?: Config["docTypes"]) => Config;
+//#endregion
+//#region src/lint.d.ts
+interface LintOptions {
+  docTypes?: {
+    glob: string;
+    type: DocType;
+  }[];
+  advisoryRules?: string[];
+  writingContext?: WritingContext;
+  root: string;
+  targets: string[];
+  rulesDir?: string;
+  only?: string[];
+  exclude?: string[];
+  dryRun?: boolean;
+  printRequests?: boolean;
+  mechanicalOnly?: boolean;
+  noCache?: boolean;
+  limitUnits?: number;
+  failOn?: Severity;
+  fix?: boolean;
+  resultsDir?: string;
+  model?: string;
+  apiKey?: string;
+  /** Extra units supplied by the caller (rendered mode). */
+  extraUnits?: Unit[];
+}
+interface LintContext {
+  evaluate?: Evaluate;
+  stdout?: (text: string) => void;
+  stderr?: (text: string) => void;
+  onProgress?: (progress: Progress) => void;
+  onEvidence?: (units: Unit[], answers: Map<string, Record<string, number>>, negatives: Map<string, Set<string>>) => void;
+}
+declare const runLint: (options: LintOptions, ctx?: LintContext) => Promise<LintResult & {
+  rulesLoaded: Rule[];
+  units: number;
+  manifest: Record<string, unknown>;
+}>;
+//#endregion
+//#region src/rules/load.d.ts
+declare const resolveRulesDir: (explicit?: string) => string;
+interface LoadOptions {
+  /** Include rules with status draft (default false). */
+  allowDraft?: boolean;
+  /** Restrict to these rule ids. */
+  only?: string[];
+}
+declare const loadRules: (rulesDir: string, options?: LoadOptions) => Rule[];
+//#endregion
+//#region src/rules/validate.d.ts
+declare const validateRule: (raw: unknown, file: string, expectedId: string) => Rule;
+//#endregion
+//#region src/rules/taxonomy.d.ts
+interface Category {
+  id: string;
+  domain: Domain;
+  label: string;
+}
+declare const CATEGORIES: readonly Category[];
+declare const CATEGORY_BY_ID: ReadonlyMap<string, Category>;
+//#endregion
+//#region src/extract/index.d.ts
+declare const extractFile: (config: Config, relativeFile: string) => Unit[];
+//#endregion
+//#region src/extract/tsx.d.ts
+interface TsxExtractOptions {
+  config: Config;
+  docType: DocType;
+}
+declare const extractTsx: (file: string, source: string, options: TsxExtractOptions) => Unit[];
+//#endregion
+//#region src/extract/capture.d.ts
+interface BoundingBox {
+  bottom: number;
+  height: number;
+  left: number;
+  right: number;
+  top: number;
+  width: number;
+  x: number;
+  y: number;
+}
+interface ElementSnapshot {
+  attributes: Record<string, string>;
+  boundingBox: BoundingBox;
+  children: string[];
+  classList: string[];
+  id: string;
+  parentId: string | null;
+  selector: string;
+  styles: Record<string, string>;
+  tagName: string;
+  text?: string;
+}
+interface CaptureResult {
+  elements: Record<string, ElementSnapshot>;
+  metadata: {
+    url: string;
+    title?: string;
+    capturedAt?: string;
+  };
+  order: string[];
+  rootElementId: string;
+  rootOuterHtml: string;
+  settings?: unknown;
+  version: 1;
+}
+//#endregion
+//#region src/extract/rendered.d.ts
+declare const extractCapture: (raw: CaptureResult, label: string) => Unit[];
+declare const runStyleCapture: (url: string, selector: string) => Promise<CaptureResult>;
+//#endregion
+//#region src/extract/style-capture-text.d.ts
+declare const parseCaptureInput: (raw: string) => CaptureResult;
+//#endregion
+//#region src/map/jev.d.ts
+type Transport = "typesafe" | "gateway";
+declare class ProviderError extends Error {
+  readonly category: "provider_error" | "invalid_response" | "timeout" | "auth";
+  readonly status?: number | undefined;
+  constructor(category: "provider_error" | "invalid_response" | "timeout" | "auth", status?: number | undefined);
+}
+interface FetchEvaluateOptions {
+  apiKey: string;
+  transport?: Transport;
+  baseUrl?: string;
+  fetch?: typeof globalThis.fetch;
+  timeoutMs?: number;
+  retries?: number;
+  /** Sleep hook so tests can run without waiting. */
+  sleep?: (ms: number) => Promise<void>;
+}
+declare const makeFetchEvaluate: (options: FetchEvaluateOptions) => Evaluate;
+//#endregion
+//#region src/report/json.d.ts
+declare const renderJson: (result: LintResult, manifest: Record<string, unknown>) => string;
+//#endregion
+//#region src/report/sarif.d.ts
+declare const renderSarif: (result: Pick<LintResult, "findings" | "ruleFindings">, rules: Rule[], version: string) => string;
+//#endregion
+//#region src/report/tty.d.ts
+declare const renderTty: (result: LintResult, options?: {
+  verbose?: boolean;
+}) => string;
+//#endregion
+//#region src/lib/stats.d.ts
+interface BinaryMetrics {
+  tp: number;
+  fp: number;
+  fn: number;
+  tn: number;
+  precision: number;
+  recall: number;
+  f1: number;
+  precisionCI: [number, number];
+  recallCI: [number, number];
+}
+declare const calibrationTable: (pairs: {
+  label: boolean;
+  probability: number;
+}[], buckets?: number) => {
+  lo: number;
+  hi: number;
+  n: number;
+  positives: number;
+  meanP: number;
+}[];
+//#endregion
+//#region src/eval/coverage.d.ts
+declare const corpusCoverage: (items: CorpusItem[], rules: Rule[]) => {
+  items: number;
+  labelSources: {
+    [k: string]: number;
+  };
+  overlappingSources: [string, string][];
+  overlappingTexts: number;
+  rules: {
+    negative: number;
+    positive: number;
+    dev: {
+      negative: number;
+      positive: number;
+    };
+    documentTypes: ("agent-instructions" | "explanation" | "howto" | "lesson" | "marketing" | "personal" | "plan" | "pr" | "readme" | "reference" | "skill" | "slides" | "tutorial" | "ui" | "unknown")[];
+    holdout: {
+      negative: number;
+      positive: number;
+    };
+    repositories: string[];
+    ruleId: string;
+  }[];
+};
+//#endregion
+//#region src/eval/metrics.d.ts
+interface EvalOptions {
+  corpusDir?: string;
+  rulesDir?: string;
+  only?: string[];
+  split?: "dev" | "holdout" | "all";
+  includeWeak?: boolean;
+  dryRun?: boolean;
+  noCache?: boolean;
+  resultsDir?: string;
+  model?: string;
+  apiKey?: string;
+}
+interface EvalContext {
+  evaluate?: Evaluate;
+}
+interface RuleEval {
+  ruleId: string;
+  n: number;
+  /** Labelled items the rule could not judge (unresolved value, failed request). */
+  unknown: number;
+  skipped?: number;
+  metrics: BinaryMetrics;
+  reviewRate: number;
+  calibration: ReturnType<typeof calibrationTable>;
+  /** Per item: label, probability. */
+  pairs: {
+    id: string;
+    label: boolean;
+    probability: number;
+  }[];
+}
+interface EvalResult {
+  referenceCoverage?: ReturnType<typeof corpusCoverage>;
+  labelSources?: Record<string, number>;
+  report: string;
+  exitCode: number;
+  rules: RuleEval[];
+  usage: {
+    requests: number;
+    cached: number;
+    inputTokens: number;
+    costUsd: number;
+    errors: number;
+  };
+}
+declare const runEval: (options: EvalOptions, ctx?: EvalContext) => Promise<EvalResult>;
+//#endregion
+//#region src/eval/corpus.d.ts
+declare const splitFor: (id: string) => "dev" | "holdout";
+//#endregion
+//#region src/eval/promotion.d.ts
+interface PromotionEvidence {
+  eligible: boolean;
+  n: number;
+  precisionLower: number;
+  reason: string;
+}
+//#endregion
+//#region src/eval/tune.d.ts
+interface TuneOptions {
+  corpusDir?: string;
+  rulesDir?: string;
+  only?: string[];
+  floor?: number;
+  write?: boolean;
+  resultsDir?: string;
+  model?: string;
+  apiKey?: string;
+  minItems?: number;
+}
+interface TuneContext {
+  evaluate?: Evaluate;
+}
+interface TuneDecision {
+  ruleId: string;
+  validation?: PromotionEvidence;
+  n: number;
+  current: number;
+  chosen: number | null;
+  precisionLower: number;
+  recall: number;
+  action: "keep" | "raise" | "lower" | "demote" | "insufficient";
+}
+declare const runTune: (options: TuneOptions, ctx?: TuneContext) => Promise<{
+  report: string;
+  exitCode: number;
+  decisions: TuneDecision[];
+}>;
+interface TuneAbOptions {
+  ruleId: string;
+  variantFile: string;
+  corpusDir?: string;
+  rulesDir?: string;
+  resultsDir?: string;
+  model?: string;
+  apiKey?: string;
+}
+declare const runTuneAb: (options: TuneAbOptions, ctx?: TuneContext) => Promise<{
+  report: string;
+  exitCode: number;
+}>;
+//#endregion
+export { type ArchitecturePolicy, type Band, CATEGORIES, CATEGORY_BY_ID, type CONTEXT_KEYS, type Config, type ContextKey, type CorpusItem, type Coverage, type CriterionSide, type DOC_TYPES, type DOMAINS, type DocType, type Domain, type EntryValue, type Evaluate, type Finding, type Fix, type LintContext, type LintOptions, type LintResult, type Mechanical, type MechanicalHit, type NeighbourSummary, type Preconditions, type Progress, ProviderError, type Question, type ROLES, type RULE_STATUSES, type RecorderHandle, type ResolvedTypography, type Role, type Rule, type RuleSource, type RuleStatus, type RunStatus, type RunSummary, type SEVERITIES, type SEVERITY_RANK, type STRUCTURAL_KINDS, type ScanScope, type Scorecard, type Severity, type SystemOneNoul, type SystemOneRequest, type SystemOneResponse, type TIERS, type Thresholds, type Tier, type Tuning, type TuningEntry, type UNIT_KINDS, type Unit, type UnitContext, type UnitKind, type Unknown, type Usage, type WritingContext, extractCapture, extractFile, extractTsx, loadConfig, loadRules, makeFetchEvaluate, parseCaptureInput, renderJson, renderSarif, renderTty, resolveRulesDir, runEval, runLint, runStyleCapture, runTune, runTuneAb, splitFor, validateRule };
+//# sourceMappingURL=index.d.ts.map