@yanglaofish/fishtools 0.5.2 → 0.6.0

package/node_modules/@mytools/sdk/README.md

@@ -13,6 +13,8 @@
 | --- | --- |
 | `@mytools/sdk` | `./index.js` |
 | `@mytools/sdk/schema` | `./validation.js` |
+| `@mytools/sdk/inputs` | `./inputs.js` |
+| `@mytools/sdk/reports` | `./reports.js` |
 | `@mytools/sdk/schema-path` | `./schema-path.js` |
 | `@mytools/sdk/diagnostics` | `./diagnostics.js` |
 | `@mytools/sdk/conditions` | `./conditions.js` |
@@ -29,3 +31,11 @@
 ```sh
 node --test tests/modules.test.js tests/plugin-contract.test.js tests/schema-diagnostics.test.js
 ```
+
+## 输入解析
+
+`@mytools/sdk/inputs` 提供 `validateInputRules`、`hasInputRules`、`resolveInput`。输入字段 `x-fst` 支持 `fromConfig`、`unsetLabel` 和 `unit`，由插件宿主与 TUI 共用。`resolveInput` 返回有效输入和字段来源，始终复制输入；配置继承优先于输入固定默认值，显式输入优先于继承。声明范围与示例见插件开发文档。
+
+## 业务报告
+
+`@mytools/sdk/reports` 提供 `reportSchema`、`createReport(content)`、`inspectReport(value)`。v1 支持标题、摘要、分级提醒、建议、业务分组及推荐列；SDK 不负责界面渲染。helper 校验并复制 JSON 内容，错误码为 `REPORT_INVALID`。检查接口返回 `none` / `valid` / `invalid` / `unsupported` 状态，合法时 `report` 指向原值（只读使用），非法时包含 `message` 和可选 `details`。普通输出无需接入；已有插件可将报告放入 `output.report`，保留原数据字段。完整示例见 `docs/plugin-development.md`。

package/node_modules/@mytools/sdk/inputs.js

@@ -0,0 +1,53 @@
+import {FlowError} from '@mytools/sdk';
+import {assertSchema,validate,emptyObject} from './validation.js';
+
+const object=value=>value!==null&&typeof value==='object'&&!Array.isArray(value);
+const complex=['$ref','oneOf','anyOf','allOf','if','then','else','dependencies','patternProperties'];
+export const hasInputRules=schema=>Object.values(schema?.properties??{}).some(field=>field?.['x-fst']!==undefined);
+
+// 仅解释已声明的顶层输入规则，不分析插件执行代码或按同名字段猜测继承关系。
+export function validateInputRules(schema,configSchema,label='input'){
+  const fail=(at,message)=>{throw new FlowError(`${at} x-fst：${message}`,{code:'VALIDATION',details:{path:at}});};
+  const visit=(node,at,allowed=false)=>{
+    if(!object(node))return;
+    const rule=node['x-fst'];
+    if(rule!==undefined){
+      if(!allowed||schema.type!=='object'||complex.some(key=>schema[key]!==undefined||node[key]!==undefined))fail(at,'只支持简单输入对象的顶层字段');
+      if(!object(rule)||Object.keys(rule).some(key=>!['fromConfig','unsetLabel','unit'].includes(key)))fail(at,'仅支持 fromConfig、unsetLabel、unit');
+      for(const [key,value] of Object.entries(rule))if(typeof value!=='string'||!value.trim())fail(at,`${key} 必须为非空字符串`);
+      if(rule.fromConfig!==undefined){
+        let current=configSchema;
+        for(const part of rule.fromConfig.split('.')){
+          if(!part||['__proto__','constructor','prototype'].includes(part)||!Object.hasOwn(current?.properties??{},part))fail(at,`配置路径未声明：${rule.fromConfig}`);
+          current=current.properties[part];
+        }
+      }
+    }
+    for(const key of ['properties','patternProperties','$defs','definitions','dependencies','dependentSchemas'])for(const [name,child] of Object.entries(node[key]??{}))visit(child,`${at}.${key}.${name}`,node===schema&&key==='properties');
+    for(const key of ['items','additionalItems','additionalProperties','contains','not','if','then','else','propertyNames']){
+      if(Array.isArray(node[key]))node[key].forEach((child,index)=>visit(child,`${at}.${key}.${index}`));
+      else visit(node[key],`${at}.${key}`);
+    }
+    for(const key of ['allOf','anyOf','oneOf','prefixItems'])node[key]?.forEach(child=>visit(child,`${at}.${key}`));
+  };
+  visit(schema,label);
+}
+
+export function resolveInput(schema=emptyObject,input={},config={}, {check=true,label='参数'}={}){
+  const value=structuredClone(input),fields={};
+  if(object(value))for(const [key,field] of Object.entries(schema?.properties??{})){
+    const rule=field?.['x-fst']??{};
+    let source=Object.hasOwn(value,key)&&value[key]!==undefined?'input':'omitted';
+    if(source==='omitted'&&rule.fromConfig){
+      let inherited=config;
+      for(const part of rule.fromConfig.split('.'))inherited=inherited!=null&&Object.hasOwn(inherited,part)?inherited[part]:undefined;
+      if(inherited!==undefined){Object.defineProperty(value,key,{value:structuredClone(inherited),enumerable:true,writable:true,configurable:true});source='config';}
+    }
+    Object.defineProperty(fields,key,{value:{source,...(source==='config'?{path:rule.fromConfig}:{}),...(rule.unit?{unit:rule.unit}:{}),...(rule.unsetLabel?{unsetLabel:rule.unsetLabel}:{})},enumerable:true});
+  }
+  // 预览允许缺少必填项；校验器仍与执行共用，默认值只作用于副本。
+  const effective=check?validate(schema,value,label):value;
+  if(!check&&schema!=null)assertSchema(schema,label)(effective);
+  for(const [key,field] of Object.entries(fields))if(field.source==='omitted'&&effective?.[key]!==undefined)field.source='default';
+  return {value:effective,fields};
+}

package/node_modules/@mytools/sdk/package.json

@@ -6,6 +6,8 @@
   "exports": {
     ".": "./index.js",
     "./schema": "./validation.js",
+    "./inputs": "./inputs.js",
+    "./reports": "./reports.js",
     "./schema-path": "./schema-path.js",
     "./diagnostics": "./diagnostics.js",
     "./conditions": "./conditions.js",

package/node_modules/@mytools/sdk/reports.js

@@ -0,0 +1,53 @@
+import {FlowError} from './index.js';
+import {assertSchema,validate} from './validation.js';
+
+const text={type:'string',pattern:'\\S'};
+const alerts={type:'array',items:{type:'object',properties:{level:{enum:['info','warning','error']},message:text},required:['level','message'],additionalProperties:false}};
+const conclusions={summary:text,alerts,recommendations:{type:'array',items:text}};
+export const reportSchema={
+  type:'object',
+  properties:{
+    kind:{const:'fst-report'},version:{const:1},title:text,...conclusions,
+    sections:{type:'array',items:{type:'object',properties:{title:text,...conclusions,data:true,columns:{type:'array',items:text,minItems:1,uniqueItems:true},titles:{type:'object',additionalProperties:text}},required:['title'],additionalProperties:false}},
+  },
+  required:['kind','version','title'],additionalProperties:false,
+};
+
+// 与落盘 JSON 边界一致，提前拒绝会被 JSON.stringify 静默改值的内容。
+function assertJson(value,ancestors=new Set()){
+  if(value===null||typeof value==='string'||typeof value==='boolean'||typeof value==='number'&&Number.isFinite(value))return;
+  if(typeof value!=='object'||!value||ancestors.has(value)||(!Array.isArray(value)&&![Object.prototype,null].includes(Object.getPrototypeOf(value))))throw new Error('报告必须为无循环引用的 JSON 数据');
+  ancestors.add(value);
+  try{
+    const list=Array.isArray(value),keys=Reflect.ownKeys(value);
+    if(list&&keys.length!==value.length+1)throw new Error('报告数组不能含空槽或附加属性');
+    for(const key of keys){
+      if(list&&key==='length')continue;
+      const field=Object.getOwnPropertyDescriptor(value,key);
+      if(typeof key!=='string'||!field.enumerable||!Object.hasOwn(field,'value')||list&&(!Number.isInteger(Number(key))||Number(key)<0||Number(key)>=value.length||String(Number(key))!==key))throw new Error('报告只能包含 JSON 可保留的普通数据属性');
+      assertJson(field.value,ancestors);
+    }
+  }finally{ancestors.delete(value);}
+}
+
+export function inspectReport(value){
+  try{
+    if(!value||typeof value!=='object'||Array.isArray(value))return {status:'none'};
+    const kind=Object.getOwnPropertyDescriptor(value,'kind');
+    if(kind&&!Object.hasOwn(kind,'value'))throw new Error('报告标记不能为访问器');
+    if(kind?.value!=='fst-report')return {status:'none'};
+    assertJson(value);
+    if(Number.isInteger(value.version)&&value.version!==1)return {status:'unsupported',message:`不支持报告版本 ${value.version}，已回退字段阅读。`};
+    const check=assertSchema(reportSchema,'报告',{useDefaults:false});
+    if(!check(value))return {status:'invalid',message:'报告格式无效，已回退字段阅读。',details:structuredClone(check.errors)};
+    return {status:'valid',report:value};
+  }catch(error){return {status:'invalid',message:`报告格式无效：${error.message}，已回退字段阅读。`};}
+}
+
+export function createReport(content){
+  try{assertJson(content);}catch(error){throw new FlowError(`报告格式无效：${error.message}`,{code:'REPORT_INVALID'});}
+  const value={kind:'fst-report',version:1,...content};
+  const result=inspectReport(value);
+  if(result.status!=='valid')throw new FlowError(result.message??'报告格式无效',{code:'REPORT_INVALID',details:result.details});
+  return validate(reportSchema,value,'报告',{useDefaults:false});
+}