@tiangong-lca/cli 0.1.0 → 0.1.2

package/dist/src/lib/flow-qa.d.ts

@@ -0,0 +1,289 @@
+import type { JsonRecord } from './flow-governance.js';
+import type { FetchLike } from './http.js';
+type ClassificationEntry = {
+    level: string;
+    class_id?: string;
+    cat_id?: string;
+    text: string;
+};
+type FlowRuleFinding = {
+    flow_uuid: string;
+    base_version: string;
+    severity: string;
+    rule_id?: string;
+    ruleset_id?: 'flow-authoring/strict';
+    methodology_rule_id?: string | null;
+    message?: string;
+    fixability?: string;
+    source: 'rule' | 'llm';
+    rule_source?: string;
+    evidence?: JsonRecord;
+    action?: string;
+};
+type FlowSummary = {
+    flow_uuid: string;
+    base_version: string;
+    type_of_dataset: string;
+    names: {
+        primary_en: string;
+        primary_zh: string;
+        all_texts: string[];
+    };
+    classification: {
+        leaf: {
+            class_id: string;
+            text: string;
+            key: string;
+        };
+        path: ClassificationEntry[];
+    };
+    flow_property: JsonRecord;
+    quantitative_reference: {
+        reference_flow_property_internal_id: string;
+    };
+    unitgroup: {
+        uuid: string;
+        name: string;
+        reference_unit_name: string;
+        lookup_status: string;
+        lookup_source: string;
+    };
+    rule_signals: Array<{
+        rule_id: string;
+        severity: string;
+        message: string;
+        evidence: JsonRecord;
+    }>;
+    similarity_candidates: Array<{
+        other_flow_uuid: string;
+        other_base_version: string;
+        similarity: number;
+        other_name_en: string;
+        classification_group: string;
+    }>;
+    source_file?: string;
+    _name_fingerprint: string;
+};
+type FlowSimilarityPair = {
+    classification_group: string;
+    flow_property_uuid: string;
+    unitgroup_uuid: string;
+    left_flow_uuid: string;
+    right_flow_uuid: string;
+    left_version: string;
+    right_version: string;
+    similarity: number;
+    left_name_en: string;
+    right_name_en: string;
+};
+type FlowQaLlmBatchResult = {
+    batch_index: number;
+    batch_size: number;
+    enabled: boolean;
+    ok: boolean;
+    reason?: string;
+    raw_preview?: string;
+};
+export type FlowQaLlmResult = {
+    enabled: boolean;
+    ok?: boolean;
+    reason?: string;
+    batch_count: number;
+    reviewed_flow_count: number;
+    truncated: boolean;
+    batch_results: FlowQaLlmBatchResult[];
+};
+type FlowQaLlmRunResult = FlowQaLlmResult & {
+    llmFindings: FlowRuleFinding[];
+};
+type FlowRulesetGate = {
+    status: 'passed' | 'needs_review' | 'blocked';
+    ruleset_id: 'flow-authoring/strict';
+    ruleset_version: '1';
+    ruleset_source_version: string;
+    ruleset_rule_ids: string[];
+    counts: {
+        findings: number;
+        blockers: number;
+    };
+    blockers: FlowRuleFinding[];
+    next_action: 'continue' | 'review_findings' | 'fix_blockers';
+};
+export type FlowQaReport = {
+    schema_version: 1;
+    generated_at_utc: string;
+    status: 'completed_local_flow_qa';
+    run_id: string;
+    out_dir: string;
+    rows_file: string;
+    input_mode: 'rows_file' | 'flows_dir' | 'run_root';
+    effective_flows_dir: string;
+    logic_version: string;
+    ruleset_id?: 'flow-authoring/strict';
+    ruleset_version?: '1';
+    ruleset_source_version?: string;
+    ruleset_rule_ids?: string[];
+    flow_count: number;
+    similarity_threshold: number;
+    methodology_rule_source: string;
+    with_reference_context: false;
+    reference_context_mode: 'disabled';
+    rule_finding_count: number;
+    llm_finding_count: number;
+    finding_count: number;
+    blocker_count?: number;
+    severity_counts: Record<string, number>;
+    rule_counts: Record<string, number>;
+    methodology_rule_counts?: Record<string, number>;
+    ruleset_gate?: FlowRulesetGate;
+    llm: FlowQaLlmResult;
+    files: {
+        qa_input_summary: string;
+        materialization_summary: string | null;
+        rule_findings: string;
+        llm_findings: string;
+        findings: string;
+        ruleset_gate?: string;
+        flow_summaries: string;
+        similarity_pairs: string;
+        summary: string;
+        qa_zh: string;
+        qa_en: string;
+        timing: string;
+        report: string;
+    };
+};
+export type RunFlowQaOptions = {
+    rowsFile?: string;
+    flowsDir?: string;
+    runRoot?: string;
+    runId?: string;
+    outDir: string;
+    startTs?: string;
+    endTs?: string;
+    logicVersion?: string;
+    enableLlm?: boolean;
+    llmModel?: string;
+    llmMaxFlows?: number;
+    llmBatchSize?: number;
+    similarityThreshold?: number;
+    methodologyId?: string;
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: FetchLike;
+    now?: () => Date;
+};
+declare function walkStrings(node: unknown): string[];
+declare function langTextForLang(value: unknown, lang: string): string;
+declare function findUuidInNode(node: unknown): string;
+declare function flowRoot(doc: JsonRecord): JsonRecord;
+declare function nameFingerprint(flow: JsonRecord): string;
+declare function classificationLeaf(flow: JsonRecord): {
+    class_id: string;
+    text: string;
+    key: string;
+};
+declare function computeSimilarity(left: string, right: string): number;
+declare function createRuleFinding(flowUuidValue: string, baseVersion: string, severity: string, ruleId: string, message: string, options?: {
+    fixability?: string;
+    evidence?: JsonRecord;
+    action?: string;
+    ruleSource?: string;
+}): FlowRuleFinding;
+declare function flowRulesetGate(findings: FlowRuleFinding[]): FlowRulesetGate;
+declare function applyMethodologyChecks(flow: JsonRecord, flowUuidValue: string, baseVersion: string, ruleSource: string): FlowRuleFinding[];
+declare function buildFlowSummaryAndRuleFindings(doc: JsonRecord, methodologyRuleSource: string): {
+    summary: FlowSummary;
+    findings: FlowRuleFinding[];
+};
+declare function buildSimilarity(summaries: FlowSummary[], threshold: number): {
+    pairs: FlowSimilarityPair[];
+    candidatesByFlow: Record<string, FlowSummary['similarity_candidates']>;
+};
+declare function parseLlmJsonOutput(output: string): JsonRecord | null;
+declare function buildLlmPrompt(batch: unknown[]): string;
+declare function normalizeLlmFinding(item: JsonRecord, summaryByUuid: Record<string, FlowSummary>, fallbackFlowUuid?: string): FlowRuleFinding | null;
+declare function runOptionalLlmReview(summaries: FlowSummary[], options: {
+    enableLlm: boolean;
+    llmModel?: string;
+    llmMaxFlows: number;
+    llmBatchSize: number;
+    env: NodeJS.ProcessEnv;
+    fetchImpl?: FetchLike;
+    outDir: string;
+    runId: string;
+}): Promise<FlowQaLlmRunResult>;
+declare function severityCounts(rows: FlowRuleFinding[]): Record<string, number>;
+declare function ruleCounts(rows: FlowRuleFinding[]): Record<string, number>;
+declare function methodologyRuleCounts(rows: FlowRuleFinding[]): Record<string, number>;
+declare function readJsonObject(filePath: string): JsonRecord;
+declare function materializeRowsFile(rowsFile: string, outDir: string): {
+    flowsDir: string;
+    summaryPath: string;
+};
+declare function resolveReviewInput(options: RunFlowQaOptions): {
+    inputMode: 'rows_file' | 'flows_dir' | 'run_root';
+    effectiveFlowsDir: string;
+    materializationSummaryPath: string | null;
+    runId: string;
+    reviewInputSummary: JsonRecord;
+};
+declare function listFlowFiles(flowsDir: string): string[];
+declare function renderZhReview(options: {
+    runId: string;
+    logicVersion: string;
+    flowsDir: string;
+    flowSummaries: JsonRecord[];
+    ruleFindings: FlowRuleFinding[];
+    llmFindings: FlowRuleFinding[];
+    llmResult: FlowQaLlmResult;
+    mergedFindings: FlowRuleFinding[];
+    summary: FlowQaReport;
+}): string;
+declare function renderEnReview(options: {
+    runId: string;
+    logicVersion: string;
+    flowsDir: string;
+    flowCount: number;
+    ruleFindingCount: number;
+    llmFindingCount: number;
+    llmResult: FlowQaLlmResult;
+    methodologyRuleSource: string;
+}): string;
+declare function renderTimingReview(options: {
+    runId: string;
+    startTs?: string;
+    endTs?: string;
+    flowCount: number;
+}): string;
+export declare function runFlowQa(options: RunFlowQaOptions): Promise<FlowQaReport>;
+declare function reportRowsFile(value: unknown): string;
+export declare const __testInternals: {
+    applyMethodologyChecks: typeof applyMethodologyChecks;
+    buildFlowSummaryAndRuleFindings: typeof buildFlowSummaryAndRuleFindings;
+    buildSimilarity: typeof buildSimilarity;
+    buildLlmPrompt: typeof buildLlmPrompt;
+    classificationLeaf: typeof classificationLeaf;
+    computeSimilarity: typeof computeSimilarity;
+    createRuleFinding: typeof createRuleFinding;
+    findUuidInNode: typeof findUuidInNode;
+    flowRoot: typeof flowRoot;
+    langTextForLang: typeof langTextForLang;
+    listFlowFiles: typeof listFlowFiles;
+    materializeRowsFile: typeof materializeRowsFile;
+    nameFingerprint: typeof nameFingerprint;
+    normalizeLlmFinding: typeof normalizeLlmFinding;
+    parseLlmJsonOutput: typeof parseLlmJsonOutput;
+    readJsonObject: typeof readJsonObject;
+    renderEnReview: typeof renderEnReview;
+    renderTimingReview: typeof renderTimingReview;
+    renderZhReview: typeof renderZhReview;
+    reportRowsFile: typeof reportRowsFile;
+    resolveReviewInput: typeof resolveReviewInput;
+    runOptionalLlmReview: typeof runOptionalLlmReview;
+    flowRulesetGate: typeof flowRulesetGate;
+    methodologyRuleCounts: typeof methodologyRuleCounts;
+    ruleCounts: typeof ruleCounts;
+    severityCounts: typeof severityCounts;
+    walkStrings: typeof walkStrings;
+};
+export {};

package/dist/src/lib/flow-read.d.ts

@@ -0,0 +1,70 @@
+import type { FetchLike } from './http.js';
+import { type SupabaseDataRuntime } from './supabase-client.js';
+type JsonObject = Record<string, unknown>;
+export type SupabaseFlowRow = {
+    id: string;
+    version: string;
+    user_id: string | null;
+    state_code: number | null;
+    modified_at: string | null;
+    json: unknown;
+};
+export type FlowListQueryFilters = {
+    ids?: string[];
+    version?: string | null;
+    userId?: string | null;
+    stateCodes?: number[];
+    typeOfDataset?: string[];
+    order?: string | null;
+    limit?: number | null;
+    offset?: number | null;
+};
+export type SupabaseFlowLookup = {
+    row: SupabaseFlowRow;
+    sourceUrl: string;
+    resolution: 'remote_supabase_exact' | 'remote_supabase_latest' | 'remote_supabase_latest_fallback';
+};
+declare function buildHeaders(publishableKey: string, accessToken: string): Record<string, string>;
+declare function normalizeTokenList(values: readonly string[] | undefined): string[];
+declare function normalizeStateCodeList(values: readonly number[] | undefined): number[];
+declare function buildFlowListUrl(restBaseUrl: string, filters: FlowListQueryFilters): string;
+declare function parseFlowRows(payload: unknown, url: string): SupabaseFlowRow[];
+declare function normalizeSupabaseFlowPayload(payload: unknown, lookupKey: string): JsonObject;
+declare function listFlowRows(options: {
+    runtime: SupabaseDataRuntime;
+    filters: FlowListQueryFilters;
+    timeoutMs: number;
+    fetchImpl: FetchLike;
+}): Promise<{
+    rows: SupabaseFlowRow[];
+    sourceUrl: string;
+}>;
+declare function buildAmbiguousMatchDetails(rows: SupabaseFlowRow[]): Array<{
+    id: string;
+    version: string;
+    user_id: string | null;
+    state_code: number | null;
+}>;
+declare function latestRowsAreAmbiguous(rows: SupabaseFlowRow[]): boolean;
+declare function fetchOneFlowRow(options: {
+    runtime: SupabaseDataRuntime;
+    id: string;
+    version?: string | null;
+    userId?: string | null;
+    stateCode?: number | null;
+    timeoutMs: number;
+    fetchImpl: FetchLike;
+    fallbackToLatest?: boolean;
+}): Promise<SupabaseFlowLookup | null>;
+export { buildFlowListUrl, buildHeaders, buildAmbiguousMatchDetails, fetchOneFlowRow, latestRowsAreAmbiguous, listFlowRows, normalizeStateCodeList, normalizeSupabaseFlowPayload, normalizeTokenList, parseFlowRows, };
+export declare const __testInternals: {
+    buildFlowListUrl: typeof buildFlowListUrl;
+    buildHeaders: typeof buildHeaders;
+    buildAmbiguousMatchDetails: typeof buildAmbiguousMatchDetails;
+    latestRowsAreAmbiguous: typeof latestRowsAreAmbiguous;
+    normalizeStateCodeList: typeof normalizeStateCodeList;
+    normalizeSupabaseFlowPayload: typeof normalizeSupabaseFlowPayload;
+    normalizeTokenList: typeof normalizeTokenList;
+    parseFlowRows: typeof parseFlowRows;
+};
+export type { SupabaseDataRuntime };