@metweave/parser 0.1.2 → 0.2.0

package/dist/index.d.cts

@@ -1,5 +1,133 @@
-import { AltimeterReading, CloudCondition, CloudElement, MetarParseError, MetarReport, MetarReport as MetarReport$1, Observed, ParseOptions, ParseWarning, ReportKind, RunwayStateGroup, RunwayVisualRange, Span, TemperatureReading, TrendElements, TrendGroup, TrendKind, VisibilityGroup, WeatherGroup, WindGroup } from "@metweave/core";
-//#region src/index.d.ts
+import { AltimeterReading, CloudCondition, CloudCondition as CloudCondition$1, CloudElement, MetarParseError, MetarReport, MetarReport as MetarReport$1, Observed, ParseOptions, ParseWarning, ReportKind, RunwayStateGroup, RunwayVisualRange, Span, Span as Span$1, TafChangeAt, TafChangeGroup, TafChangeKind, TafChangeWindow, TafParseOptions, TafParseOptions as TafParseOptions$1, TafReport, TafReport as TafReport$1, TafTemperatureGroup, TafValidityGroup, TafValidityGroup as TafValidityGroup$1, TemperatureReading, TrendElements, TrendGroup, TrendKind, VisibilityGroup, VisibilityGroup as VisibilityGroup$1, WeatherGroup, WeatherGroup as WeatherGroup$1, WindGroup, WindGroup as WindGroup$1 } from "@metweave/core";
+//#region src/taf.d.ts
+/**
+ * 有效期时长（小时）＝有效期组差值（清单 B1★）：`(止日−起日)×24 + (止时−起时)`，
+ * **只看有效期组，禁用发布钟点**（钟点 03/09/15/21Z 与版本解耦、代际切换——taf-tac §3.1 v1.2）。
+ * 止时 24（B2 午夜特例）自然进算术；起日 > 止日（B3 跨月回绕）按所跨月长度回绕天数——
+ * 有效期组不含月信息，缺省按 31 天（保守缺省），带月锚的精确回绕由展开层（B3）负责。
+ * 注意：wrapDaysInMonth 须 ≥ 起日（2 月锚 + 31 日组属不自洽输入，算术结果为负由调用方甄别）。
+ */
+export declare function tafDurationHours(validity: TafValidityGroup$1, wrapDaysInMonth?: number): number;
+/**
+ * Parse one TAF report (tolerant mode) into the TAF IR — the forecast-side entry.
+ * 解析单条 TAF 报文（tolerant）为预报侧 IR。
+ * 整体失败（输入非字符串/无站名/无发布时组/时组或有效期越界/未实现模式）抛 MetarParseError
+ * （code 稳定契约，与 parse 同族；v0.2 起别名 ParseError）。
+ */
+export declare function parseTaf(raw: string, options?: TafParseOptions$1): TafReport$1;
+/**
+ * Result-style variant of `parseTaf` (same contract as `tryParse`): whole-report failures come back
+ * as `{ ok:false, error }`; unexpected non-MetarParseError exceptions still throw.
+ * parseTaf 的问题式变体（契约同 tryParse）：整体失败返回 { ok:false, error }；
+ * 仅编程性意外（非 MetarParseError 的内部异常）原样抛出——不吞实现缺陷。
+ */
+type TryParseTafResult = {
+  readonly ok: true;
+  readonly report: TafReport$1;
+} | {
+  readonly ok: false;
+  readonly error: MetarParseError;
+};
+export declare function tryParseTaf(raw: string, options?: TafParseOptions$1): TryParseTafResult;
+//#endregion
+//#region src/expand.d.ts
+/** 展开时刻：日（锚月内，可跨月回绕）+ 时分 */
+interface TafExpandAt {
+  readonly day: number;
+  readonly hour: number;
+  readonly minute: number;
+}
+/** 月锚（B3）：有效期起日所在月——`daysIn` 供给跨月回绕的天数表（大小月/闰年由调用方算好） */
+interface TafMonthAnchor {
+  readonly daysIn: number;
+}
+/** 合成后的四要素（展开层两态视图：cavok 让位语义同解析层） */
+interface TafResolvedConditions {
+  readonly wind?: WindGroup$1;
+  readonly visibility?: VisibilityGroup$1;
+  readonly weather: readonly WeatherGroup$1[];
+  readonly clouds?: CloudCondition$1;
+  readonly cavok: boolean;
+}
+/** TEMPO/PROB 发作态：只携带组内所列要素（覆盖语义：天气整列替换、云整体替换、未列继承段值） */
+interface TafTempoOverlay {
+  readonly conditions: Pick<TafResolvedConditions, "wind" | "visibility" | "weather" | "clouds" | "cavok">;
+  /** PROB 组携带；TEMPO 无概率 */
+  readonly probability?: 30 | 40;
+  readonly withTempo: boolean;
+}
+/** 一次展开的完整结果 */
+interface TafExpansion {
+  /** 间歇态/段值（B7：窗内非发作时刻的基线） */
+  readonly conditions: TafResolvedConditions;
+  /** 发作态（t 落在 TEMPO/PROB 窗内时在位；间歇态仍在 conditions） */
+  readonly tempo?: TafTempoOverlay;
+  /** B6 过渡带：t 在某 BECMG 窗内，变化时刻不可精确（保守按前段值返回） */
+  readonly uncertain: boolean;
+  /** 绑定段：base 或变化组序号（changes 下标） */
+  readonly boundSegment: {
+    readonly kind: "base";
+  } | {
+    readonly kind: string;
+    readonly index: number;
+  };
+}
+/**
+ * Expand a parsed TAF at one instant — the five-step algorithm (切段→挂载→绑段→合成→叠加).
+ * 在给定时刻展开已解析的 TAF（五步算法，黄金基准＝taf-timeline §3 三例逐时刻表）。
+ * `anchor` 为有效期起日所在月的天数（大小月/闰年由调用方给定，B3）；`at.day` 为锚月内日序
+ * （跨月后的日按小日号传入，内部回绕）。
+ */
+export declare function expandTaf(report: TafReport$1, at: TafExpandAt, anchor: TafMonthAnchor): TafExpansion;
+/** 分段视图行（渲染层②「分段天气明细」的数据面，v0.2）：一行 = 一个时段的具体天气 */
+interface TafSegmentRow {
+  /** 行类型：base=基况段；FM=自该时刻起（硬切）；BECMG=渐变（过渡带行 uncertain=true）或转变后段（false）；TEMPO/PROB=短暂/概率挂载行 */
+  readonly kind: "base" | "FM" | "BECMG" | "TEMPO" | "PROB";
+  /** 行窗口起点/终点（显示序：日按锚月回绕，跨月折回小日号） */
+  readonly from: TafExpandAt;
+  readonly to: TafExpandAt;
+  /** BECMG 过渡带行：变化时刻不可精确（B6） */
+  readonly uncertain: boolean;
+  /** 该窗口的展开四要素（段中点口径；BECMG 过渡带行=转变前值，TEMPO/PROB 行=所在主导段值） */
+  readonly conditions: TafResolvedConditions;
+  /** 挂载行组内所列要素与概率（仅 TEMPO/PROB 行在位） */
+  readonly overlay?: TafTempoOverlay;
+  /** 来源变化组下标（changes 序；base 行无） */
+  readonly sourceIndex?: number;
+}
+/**
+ * Derive the period-by-period view of a TAF: prevailing rows (base / FM / after-BECMG) with the
+ * BECMG transition band as its own uncertain row, plus TEMPO/PROB overlay rows — chronological.
+ * 把 TAF 切成分段明细行（指令「按拆分时间段给具体天气」）：主导段行 + BECMG 过渡带行 +
+ * TEMPO/PROB 挂载行，按窗口起点升序稳定合并（同刻主导段在前）；每行携带段中点展开结果——
+ * 切段规则与 expandTaf 同一来源（prevailingSegments），黄金基准互通。
+ */
+export declare function tafSegments(report: TafReport$1, anchor?: TafMonthAnchor): readonly TafSegmentRow[];
+//#endregion
+//#region src/validate.d.ts
+/** 判据阈值源：wmo（缺省）＝国际白名单/VRB<1.5；caac＝中国民航（中国扩展层天气合法/VRB<2） */
+type TafValidateStandard = "wmo" | "caac";
+interface TafValidateOptions {
+  readonly standard?: TafValidateStandard;
+}
+/** 违例码（稳定契约，只增不改）：C2/C3/C5/C7 四判据各一 */
+type TafViolationCode = "vrb-over-threshold" | /** C2：VRB 风速 ≥ 阈值（wmo 1.5 / caac 2 m/s），不应编 VRB */ "gust-below-threshold" | /** C3：阵风超出平均 <5 m/s（10 kt），G 组不合法 */ "wx-outside-list" | /** C5：天气组不在预报白名单（国际层外；中国扩展层在 wmo 标准下违例） */ "cloud-layer-selection"; /** C7：三层选取违例（第 2 组 FEW / 第 3 组起 FEW·SCT） */
+interface TafViolation {
+  readonly code: TafViolationCode;
+  readonly severity: "warning";
+  readonly message: string;
+  /** 违例所在段（「基况段」/「FM 0100」/「TEMPO 0609/0612」——变化组以变化词+窗口/时刻指位） */
+  readonly where: string;
+  readonly span?: Span$1;
+}
+/**
+ * 校验一份已解析的 TAF：返回全部条文违例（空数组＝通过）。
+ * 判据与边界见模块头注（C2/C3/C5/C7；B7 机器判据空集）。不修改报告、不抛错——
+ * 严判入口是 parseTaf({mode:"strict"})，本函数供质控/判卷侧按需取用。
+ */
+export declare function validateTaf(report: TafReport$1, options?: TafValidateOptions): readonly TafViolation[];
+//#endregion
+//#region src/groups.d.ts
 /**
  * Temperature/dewpoint group shape: always dd/dd (M = negative; // on either side = that side missing).
  * 温度/露点组形态：恒为 dd/dd（M = 负；任一侧 // = 该侧缺测）——两位是形态定义本身，不是惯例：
@@ -13,6 +141,8 @@ import { AltimeterReading, CloudCondition, CloudElement, MetarParseError, MetarR
  * 导出供回归测试直接对形态断言（红线：对 "//" 与裸分数均不得匹配）。
  */
 export declare const TEMP_DEW_PATTERN: RegExp;
+//#endregion
+//#region src/index.d.ts
 /**
  * Parse one METAR/SPECI report (tolerant mode) into the IR — the package's single entry.
  * 解析单条 METAR/SPECI 报文（tolerant）为 IR——本包唯一入口。
@@ -44,5 +174,5 @@ export type TryParseResult = {
  */
 export declare function tryParse(raw: string, options?: ParseOptions): TryParseResult;
 //#endregion
-export type { AltimeterReading, CloudCondition, CloudElement, MetarReport, Observed, ParseWarning, ReportKind, RunwayStateGroup, RunwayVisualRange, Span, TemperatureReading, TrendElements, TrendGroup, TrendKind, VisibilityGroup, WeatherGroup, WindGroup };
+export type { AltimeterReading, CloudCondition, CloudElement, MetarReport, Observed, ParseWarning, ReportKind, RunwayStateGroup, RunwayVisualRange, Span, TafChangeAt, TafChangeGroup, TafChangeKind, TafChangeWindow, TafExpandAt, TafExpansion, TafMonthAnchor, TafParseOptions, TafReport, TafResolvedConditions, TafSegmentRow, TafTemperatureGroup, TafTempoOverlay, TafValidateOptions, TafValidateStandard, TafValidityGroup, TafViolation, TafViolationCode, TemperatureReading, TrendElements, TrendGroup, TrendKind, TryParseTafResult, VisibilityGroup, WeatherGroup, WindGroup };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -1,5 +1,133 @@
-import { AltimeterReading, CloudCondition, CloudElement, MetarParseError, MetarReport, MetarReport as MetarReport$1, Observed, ParseOptions, ParseWarning, ReportKind, RunwayStateGroup, RunwayVisualRange, Span, TemperatureReading, TrendElements, TrendGroup, TrendKind, VisibilityGroup, WeatherGroup, WindGroup } from "@metweave/core";
-//#region src/index.d.ts
+import { AltimeterReading, CloudCondition, CloudCondition as CloudCondition$1, CloudElement, MetarParseError, MetarReport, MetarReport as MetarReport$1, Observed, ParseOptions, ParseWarning, ReportKind, RunwayStateGroup, RunwayVisualRange, Span, Span as Span$1, TafChangeAt, TafChangeGroup, TafChangeKind, TafChangeWindow, TafParseOptions, TafParseOptions as TafParseOptions$1, TafReport, TafReport as TafReport$1, TafTemperatureGroup, TafValidityGroup, TafValidityGroup as TafValidityGroup$1, TemperatureReading, TrendElements, TrendGroup, TrendKind, VisibilityGroup, VisibilityGroup as VisibilityGroup$1, WeatherGroup, WeatherGroup as WeatherGroup$1, WindGroup, WindGroup as WindGroup$1 } from "@metweave/core";
+//#region src/taf.d.ts
+/**
+ * 有效期时长（小时）＝有效期组差值（清单 B1★）：`(止日−起日)×24 + (止时−起时)`，
+ * **只看有效期组，禁用发布钟点**（钟点 03/09/15/21Z 与版本解耦、代际切换——taf-tac §3.1 v1.2）。
+ * 止时 24（B2 午夜特例）自然进算术；起日 > 止日（B3 跨月回绕）按所跨月长度回绕天数——
+ * 有效期组不含月信息，缺省按 31 天（保守缺省），带月锚的精确回绕由展开层（B3）负责。
+ * 注意：wrapDaysInMonth 须 ≥ 起日（2 月锚 + 31 日组属不自洽输入，算术结果为负由调用方甄别）。
+ */
+export declare function tafDurationHours(validity: TafValidityGroup$1, wrapDaysInMonth?: number): number;
+/**
+ * Parse one TAF report (tolerant mode) into the TAF IR — the forecast-side entry.
+ * 解析单条 TAF 报文（tolerant）为预报侧 IR。
+ * 整体失败（输入非字符串/无站名/无发布时组/时组或有效期越界/未实现模式）抛 MetarParseError
+ * （code 稳定契约，与 parse 同族；v0.2 起别名 ParseError）。
+ */
+export declare function parseTaf(raw: string, options?: TafParseOptions$1): TafReport$1;
+/**
+ * Result-style variant of `parseTaf` (same contract as `tryParse`): whole-report failures come back
+ * as `{ ok:false, error }`; unexpected non-MetarParseError exceptions still throw.
+ * parseTaf 的问题式变体（契约同 tryParse）：整体失败返回 { ok:false, error }；
+ * 仅编程性意外（非 MetarParseError 的内部异常）原样抛出——不吞实现缺陷。
+ */
+type TryParseTafResult = {
+  readonly ok: true;
+  readonly report: TafReport$1;
+} | {
+  readonly ok: false;
+  readonly error: MetarParseError;
+};
+export declare function tryParseTaf(raw: string, options?: TafParseOptions$1): TryParseTafResult;
+//#endregion
+//#region src/expand.d.ts
+/** 展开时刻：日（锚月内，可跨月回绕）+ 时分 */
+interface TafExpandAt {
+  readonly day: number;
+  readonly hour: number;
+  readonly minute: number;
+}
+/** 月锚（B3）：有效期起日所在月——`daysIn` 供给跨月回绕的天数表（大小月/闰年由调用方算好） */
+interface TafMonthAnchor {
+  readonly daysIn: number;
+}
+/** 合成后的四要素（展开层两态视图：cavok 让位语义同解析层） */
+interface TafResolvedConditions {
+  readonly wind?: WindGroup$1;
+  readonly visibility?: VisibilityGroup$1;
+  readonly weather: readonly WeatherGroup$1[];
+  readonly clouds?: CloudCondition$1;
+  readonly cavok: boolean;
+}
+/** TEMPO/PROB 发作态：只携带组内所列要素（覆盖语义：天气整列替换、云整体替换、未列继承段值） */
+interface TafTempoOverlay {
+  readonly conditions: Pick<TafResolvedConditions, "wind" | "visibility" | "weather" | "clouds" | "cavok">;
+  /** PROB 组携带；TEMPO 无概率 */
+  readonly probability?: 30 | 40;
+  readonly withTempo: boolean;
+}
+/** 一次展开的完整结果 */
+interface TafExpansion {
+  /** 间歇态/段值（B7：窗内非发作时刻的基线） */
+  readonly conditions: TafResolvedConditions;
+  /** 发作态（t 落在 TEMPO/PROB 窗内时在位；间歇态仍在 conditions） */
+  readonly tempo?: TafTempoOverlay;
+  /** B6 过渡带：t 在某 BECMG 窗内，变化时刻不可精确（保守按前段值返回） */
+  readonly uncertain: boolean;
+  /** 绑定段：base 或变化组序号（changes 下标） */
+  readonly boundSegment: {
+    readonly kind: "base";
+  } | {
+    readonly kind: string;
+    readonly index: number;
+  };
+}
+/**
+ * Expand a parsed TAF at one instant — the five-step algorithm (切段→挂载→绑段→合成→叠加).
+ * 在给定时刻展开已解析的 TAF（五步算法，黄金基准＝taf-timeline §3 三例逐时刻表）。
+ * `anchor` 为有效期起日所在月的天数（大小月/闰年由调用方给定，B3）；`at.day` 为锚月内日序
+ * （跨月后的日按小日号传入，内部回绕）。
+ */
+export declare function expandTaf(report: TafReport$1, at: TafExpandAt, anchor: TafMonthAnchor): TafExpansion;
+/** 分段视图行（渲染层②「分段天气明细」的数据面，v0.2）：一行 = 一个时段的具体天气 */
+interface TafSegmentRow {
+  /** 行类型：base=基况段；FM=自该时刻起（硬切）；BECMG=渐变（过渡带行 uncertain=true）或转变后段（false）；TEMPO/PROB=短暂/概率挂载行 */
+  readonly kind: "base" | "FM" | "BECMG" | "TEMPO" | "PROB";
+  /** 行窗口起点/终点（显示序：日按锚月回绕，跨月折回小日号） */
+  readonly from: TafExpandAt;
+  readonly to: TafExpandAt;
+  /** BECMG 过渡带行：变化时刻不可精确（B6） */
+  readonly uncertain: boolean;
+  /** 该窗口的展开四要素（段中点口径；BECMG 过渡带行=转变前值，TEMPO/PROB 行=所在主导段值） */
+  readonly conditions: TafResolvedConditions;
+  /** 挂载行组内所列要素与概率（仅 TEMPO/PROB 行在位） */
+  readonly overlay?: TafTempoOverlay;
+  /** 来源变化组下标（changes 序；base 行无） */
+  readonly sourceIndex?: number;
+}
+/**
+ * Derive the period-by-period view of a TAF: prevailing rows (base / FM / after-BECMG) with the
+ * BECMG transition band as its own uncertain row, plus TEMPO/PROB overlay rows — chronological.
+ * 把 TAF 切成分段明细行（指令「按拆分时间段给具体天气」）：主导段行 + BECMG 过渡带行 +
+ * TEMPO/PROB 挂载行，按窗口起点升序稳定合并（同刻主导段在前）；每行携带段中点展开结果——
+ * 切段规则与 expandTaf 同一来源（prevailingSegments），黄金基准互通。
+ */
+export declare function tafSegments(report: TafReport$1, anchor?: TafMonthAnchor): readonly TafSegmentRow[];
+//#endregion
+//#region src/validate.d.ts
+/** 判据阈值源：wmo（缺省）＝国际白名单/VRB<1.5；caac＝中国民航（中国扩展层天气合法/VRB<2） */
+type TafValidateStandard = "wmo" | "caac";
+interface TafValidateOptions {
+  readonly standard?: TafValidateStandard;
+}
+/** 违例码（稳定契约，只增不改）：C2/C3/C5/C7 四判据各一 */
+type TafViolationCode = "vrb-over-threshold" | /** C2：VRB 风速 ≥ 阈值（wmo 1.5 / caac 2 m/s），不应编 VRB */ "gust-below-threshold" | /** C3：阵风超出平均 <5 m/s（10 kt），G 组不合法 */ "wx-outside-list" | /** C5：天气组不在预报白名单（国际层外；中国扩展层在 wmo 标准下违例） */ "cloud-layer-selection"; /** C7：三层选取违例（第 2 组 FEW / 第 3 组起 FEW·SCT） */
+interface TafViolation {
+  readonly code: TafViolationCode;
+  readonly severity: "warning";
+  readonly message: string;
+  /** 违例所在段（「基况段」/「FM 0100」/「TEMPO 0609/0612」——变化组以变化词+窗口/时刻指位） */
+  readonly where: string;
+  readonly span?: Span$1;
+}
+/**
+ * 校验一份已解析的 TAF：返回全部条文违例（空数组＝通过）。
+ * 判据与边界见模块头注（C2/C3/C5/C7；B7 机器判据空集）。不修改报告、不抛错——
+ * 严判入口是 parseTaf({mode:"strict"})，本函数供质控/判卷侧按需取用。
+ */
+export declare function validateTaf(report: TafReport$1, options?: TafValidateOptions): readonly TafViolation[];
+//#endregion
+//#region src/groups.d.ts
 /**
  * Temperature/dewpoint group shape: always dd/dd (M = negative; // on either side = that side missing).
  * 温度/露点组形态：恒为 dd/dd（M = 负；任一侧 // = 该侧缺测）——两位是形态定义本身，不是惯例：
@@ -13,6 +141,8 @@ import { AltimeterReading, CloudCondition, CloudElement, MetarParseError, MetarR
  * 导出供回归测试直接对形态断言（红线：对 "//" 与裸分数均不得匹配）。
  */
 export declare const TEMP_DEW_PATTERN: RegExp;
+//#endregion
+//#region src/index.d.ts
 /**
  * Parse one METAR/SPECI report (tolerant mode) into the IR — the package's single entry.
  * 解析单条 METAR/SPECI 报文（tolerant）为 IR——本包唯一入口。
@@ -44,5 +174,5 @@ export type TryParseResult = {
  */
 export declare function tryParse(raw: string, options?: ParseOptions): TryParseResult;
 //#endregion
-export type { AltimeterReading, CloudCondition, CloudElement, MetarReport, Observed, ParseWarning, ReportKind, RunwayStateGroup, RunwayVisualRange, Span, TemperatureReading, TrendElements, TrendGroup, TrendKind, VisibilityGroup, WeatherGroup, WindGroup };
+export type { AltimeterReading, CloudCondition, CloudElement, MetarReport, Observed, ParseWarning, ReportKind, RunwayStateGroup, RunwayVisualRange, Span, TafChangeAt, TafChangeGroup, TafChangeKind, TafChangeWindow, TafExpandAt, TafExpansion, TafMonthAnchor, TafParseOptions, TafReport, TafResolvedConditions, TafSegmentRow, TafTemperatureGroup, TafTempoOverlay, TafValidateOptions, TafValidateStandard, TafValidityGroup, TafViolation, TafViolationCode, TemperatureReading, TrendElements, TrendGroup, TrendKind, TryParseTafResult, VisibilityGroup, WeatherGroup, WindGroup };
 //# sourceMappingURL=index.d.ts.map