@antprofuse/saddle-islands-tools 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antprofuse/saddle-islands-tools",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Independent Saddle–Islands engineering tools",
   "files": [
     "tools"

package/tools/cli/main.py

@@ -10,6 +10,9 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
 
 
 def main():
+    if len(sys.argv) > 1 and sys.argv[1] == 'iteration':
+        from tools.modules.workflow.iteration import main as iteration_main
+        return iteration_main(sys.argv[2:])
     if len(sys.argv) > 1 and sys.argv[1] == 'identity':
         from tools.core.semantic_identity import main as identity_main
         sys.argv = [sys.argv[0] + ' identity', *sys.argv[2:]]
@@ -27,7 +30,7 @@ def main():
         entry = 'minifish.mjs' if command in ('build', 'package', 'plugin') else 'minifish.py'
         return subprocess.call(['node' if entry.endswith('.mjs') else sys.executable, str(Path(__file__).with_name(entry)), *args])
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument('command', choices=['identity', 'backend', 'minifish'], help='semantic identities, backend tests or Minifish tests')
+    parser.add_argument('command', choices=['identity', 'backend', 'minifish', 'iteration'], help='semantic identities, backend tests or Minifish tests')
     parser.parse_args()
 
 

package/tools/docs/README.md

@@ -6,6 +6,7 @@
 
 | 工作 | 命令入口 | 说明 |
 |---|---|---|
+| 迭代节点渲染与Git目录门禁 | `python3 TOOL_ROOT/tools/cli/main.py iteration` | [迭代参数与目录门禁](iteration.md) |
 | 语义身份生成、登记、检查 | `python3 TOOL_ROOT/tools/cli/main.py identity` | [语义身份](semantic-identity.md) |
 | 后端场景列举与执行 | `python3 TOOL_ROOT/tools/cli/main.py backend` | [后端接入](backend-testing.md) |
 | Minifish编译、制品、运行、报告 | `python3 TOOL_ROOT/tools/cli/main.py minifish` | [Minifish接入](minifish-testing.md) |

package/tools/docs/iteration.md

@@ -0,0 +1,34 @@
+# 迭代节点渲染
+
+通过独立工具集消费冻结的workflow Skill参数schema和阶段元数据，不直接调用CoTask，也不启动任务。
+
+```bash
+python3 tools/cli/main.py iteration render \
+  --workflow /absolute/path/to/workflow-skill \
+  --input /absolute/path/to/iteration.json \
+  --output /absolute/path/to/new-review.json
+```
+
+输入结构见workflow包的 `resources/iteration.schema.json`，固定阶段规则见 `resources/stage-meta.json`。发起者冻结Skill版本后填写实例；阶段实例不允许覆盖全局git或bizdir。`sharedOutput` 相对全局共享根，正式输出目录与单文件权限由阶段元数据派生，非用户手填。
+
+输出JSON包含公共上下文和各执行节点的Markdown正文，以及供目录门禁消费的结构化路径权限。调用方使用 `context` 原文更新节点，不能把整个JSON塞进节点说明。不会覆盖已有输出文件。未知参数、缺失必填值、共享根不存在、重复ID/工作分支、共享路径重叠或逃逸、未解析占位符都以非零退出拒绝。
+
+目前是启动前审阅渲染：`acceptedInput` 可指向等待上游检查点生成的登记文件；`inputCommit` 在检查点接受成果后绑定。渲染成功不表示后续分支、输入文件或运行环境已准备完毕，也不授予执行许可。输出还包含阶段检查点及最终检查点的Markdown；工具不自动构建依赖图或调用平台。
+
+本工具对随Skill schema使用的受限JSON Schema关键字执行校验，不冒充通用JSON Schema实现；未知关键字拒绝，不静默忽略。Git差异目录门禁见下。
+
+
+## Git目录门禁
+
+```bash
+python3 tools/cli/main.py iteration diff-review \
+  --workflow /absolute/path/to/workflow-skill \
+  --input /absolute/path/to/iteration.json \
+  --repository /absolute/path/to/business-checkout \
+  --base <full-base-commit> --head <full-candidate-commit> \
+  --stage-id D --output /absolute/path/to/new-diff-review.md
+```
+
+基线须为候选的祖先，两个端点必须是完整提交ID。范围来自同一实例参数和冻结阶段元数据，不接受手填任意白名单。集成交付可重复传 `--stage-id` 检查已接受阶段范围的并集。退出0表示路径检查通过，3表示有越界路径（仍写出审阅报告），2表示参数或读取错误。只读Git，不暂存、不修改、不提交。
+
+报告按目标父目录汇总文件变更类型和增删行，列所有变更文件；重命名同时检查源、目标路径，删除不能逃避检查。本门禁只核Git记录的变更路径，不追踪链接目标或增加文件类型门禁。该门禁不判断业务内容是否正确，不扫描未提交内容，也不代替缓存、依赖、报告等产物类型审查。

package/tools/modules/workflow/diff_review.py

@@ -0,0 +1,74 @@
+"""Read-only commit diff path gate and directory review report."""
+from collections import defaultdict
+import html
+from pathlib import PurePosixPath
+import re
+import subprocess
+from .iteration import Invalid
+
+
+def git(repo, *args):
+    p = subprocess.run(['git', '-C', str(repo), *args], stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    if p.returncode:
+        raise Invalid(p.stderr.decode('utf-8', 'replace').strip())
+    return p.stdout
+
+
+def review(repo, base, head, nodes):
+    for commit in (base, head):
+        if not re.fullmatch('[0-9a-f]{40}', commit):
+            raise Invalid('Diff endpoints must be full immutable commit IDs')
+        git(repo, 'cat-file', '-e', commit + '^{commit}')
+    git(repo, 'merge-base', '--is-ancestor', base, head)
+    directories = [p for n in nodes for p in n['outputDirectories']]
+    files = {p for n in nodes for p in n['outputFiles']}
+    def allowed(path):
+        return path in files or any(path.startswith(d + '/') for d in directories)
+    changed = git(repo, 'diff', '--no-ext-diff', '--no-textconv', '--name-status', '-z', '--find-renames', base, head, '--').decode().split('\0')
+    entries = []
+    while changed and changed[0]:
+        status = changed.pop(0)
+        old = changed.pop(0)
+        new = changed.pop(0) if status.startswith(('R', 'C')) else old
+        entries.append({'status':status, 'old':old, 'new':new})
+    stats = {}
+    for item in git(repo, 'diff', '--no-ext-diff', '--no-textconv', '--numstat', '-z', '--no-renames', base, head, '--').decode().split('\0'):
+        if item:
+            add, delete, path = item.split('\t', 2)
+            stats[path] = (int(add) if add != '-' else 0, int(delete) if delete != '-' else 0, add == '-')
+    violations = []
+    groups = defaultdict(lambda: dict(A=0, M=0, D=0, R=0, T=0, added=0, deleted=0, binary=0))
+    for entry in entries:
+        paths = {entry['old'], entry['new']}
+        why = []
+        for path in sorted(paths):
+            if not allowed(path):
+                why.append('越界路径：' + path)
+        entry['issues'] = why
+        violations.extend(why)
+        group = groups[str(PurePosixPath(entry['new']).parent)]
+        category = entry['status'][0]
+        if category not in ('A', 'M', 'D', 'R', 'T'):
+            why.append('未支持的变更类型：' + entry['status'])
+            violations.append(why[-1])
+        else:
+            group[category] += 1
+        for path in paths:
+            add, delete, binary = stats.get(path, (0, 0, False))
+            group['added'] += add; group['deleted'] += delete; group['binary'] += int(binary)
+    def escape(value):
+        return html.escape(value).replace('|', '|').replace('`', '`').replace('\n', '
').replace('\r', '
')
+    lines = ['# Git目录差异审阅', '', '- 基线提交：`' + base + '`', '- 候选提交：`' + head + '`',
+             '- 路径门禁：' + ('未通过' if violations else '通过'), '',
+             '路径门禁仅检查已提交的变更路径范围，不替代内容、业务正确性或未提交文件检查。重命名按目标目录计数，旧、新路径均核权限；增删行使用未合并重命名的Git统计，二进制不虚构行数。', '',
+             '| 目录 | 新增 | 修改 | 删除 | 重命名 | 类型变化 | 增行 | 删行 | 二进制项 |',
+             '|---|---:|---:|---:|---:|---:|---:|---:|---:|']
+    for path, g in sorted(groups.items()):
+        lines.append('| ' + escape(path) + ' | ' + ' | '.join(str(g[k]) for k in ('A','M','D','R','T','added','deleted','binary')) + ' |')
+    if not entries:
+        lines += ['', '无已提交变更。']
+    lines += ['', '## 文件明细', '']
+    for e in entries:
+        path = e['old'] + ' → ' + e['new'] if e['old'] != e['new'] else e['new']
+        lines.append('- ' + e['status'] + '：' + escape(path) + ('；' + escape('；'.join(e['issues'])) if e['issues'] else ''))
+    return {'passed':not violations, 'entries':entries, 'violations':violations, 'markdown':'\n'.join(lines)+'\n'}

package/tools/modules/workflow/iteration.py

@@ -0,0 +1,175 @@
+"""Validate explicit iteration parameters and render reviewable stage descriptions.
+
+Schema and stage policy are supplied by a frozen workflow Skill, not duplicated here.
+Only the documented schema vocabulary is supported; unknown validation keywords fail.
+"""
+import argparse
+import json
+from pathlib import Path, PurePosixPath
+import re
+import sys
+
+
+class Invalid(ValueError):
+    pass
+
+
+def validate(value, schema, at='$'):
+    supported = {'$schema', 'title', 'description', 'type', 'required', 'properties',
+                 'additionalProperties', 'items', 'minItems', 'minLength', 'pattern', 'enum', 'const'}
+    if set(schema) - supported:
+        raise Invalid(f'{at}: unsupported schema keywords {sorted(set(schema) - supported)}')
+    kinds = {'object': dict, 'array': list, 'string': str}
+    if 'type' in schema and (schema['type'] not in kinds or type(value) is not kinds[schema['type']]):
+        raise Invalid(f'{at}: expected {schema["type"]}')
+    if 'const' in schema and (type(value) is not type(schema['const']) or value != schema['const']):
+        raise Invalid(f'{at}: invalid schema version/value')
+    if 'enum' in schema and value not in schema['enum']:
+        raise Invalid(f'{at}: unsupported value')
+    if isinstance(value, dict):
+        props = schema.get('properties', {})
+        missing = set(schema.get('required', [])) - value.keys()
+        extra = value.keys() - props.keys()
+        if missing or (extra and schema.get('additionalProperties') is False):
+            raise Invalid(f'{at}: missing={sorted(missing)}, unknown={sorted(extra)}')
+        for key in props.keys() & value.keys():
+            validate(value[key], props[key], at + '.' + key)
+    if isinstance(value, list):
+        if len(value) < schema.get('minItems', 0):
+            raise Invalid(f'{at}: insufficient items')
+        for i, item in enumerate(value):
+            validate(item, schema.get('items', {}), f'{at}[{i}]')
+    if isinstance(value, str):
+        if len(value) < schema.get('minLength', 0) or ('pattern' in schema and not re.search(schema['pattern'], value)):
+            raise Invalid(f'{at}: malformed value')
+
+
+def relative(value):
+    p = PurePosixPath(value)
+    if p.is_absolute() or any(x in ('', '.', '..') for x in value.split('/')) or '\\' in value:
+        raise Invalid('Not a normalized repository-relative path: ' + value)
+    return p
+
+
+def branch(value):
+    if (value.startswith(('-', '/')) or value.endswith(('/', '.')) or '..' in value or '@{' in value
+            or re.search(r'[\s~^:?*\[\\]', value) or any(x in ('', '.') or x.startswith('.') or x.endswith('.lock') for x in value.split('/')) or value == '@'):
+        raise Invalid('Invalid branch name: ' + value)
+
+
+def render(config, workflow):
+    workflow = Path(workflow)
+    schema = json.loads((workflow / 'resources/iteration.schema.json').read_text())
+    meta = json.loads((workflow / 'resources/stage-meta.json').read_text())
+    validate(config, schema)
+    if meta['version'] != config['metaVersion']:
+        raise Invalid('Stage metadata version mismatch')
+    relative(config['bizdir'])
+    branch(config['git']['branch'])
+    # Operational input paths are explicit absolute paths, not cwd-relative guesses.
+    for value in [config['persistentDeliveryDirectory'], config['sharedRoot'], config['source']['root'], config['skillsRoot'], config['toolsRoot'], config['frameworkSkill'], *config['generated'].values()]:
+        if not Path(value).is_absolute():
+            raise Invalid('Expected absolute operational input path: ' + value)
+    shared = Path(config['sharedRoot']).resolve(strict=True)
+    if not shared.is_dir():
+        raise Invalid('Shared root must exist as a directory')
+    def field(label, value):
+        return f'- {label}：`{value}`'
+    def expand(template, params):
+        def get(match):
+            value = params
+            for key in match.group(1).split('.'):
+                if not isinstance(value, dict) or key not in value:
+                    raise Invalid('Unknown template parameter: ' + match.group(1))
+                value = value[key]
+            if not isinstance(value, str):
+                raise Invalid('Template value must be a string')
+            return value
+        result = re.sub(r'\{([A-Za-z][A-Za-z0-9_.]*)\}', get, template)
+        if '{' in result or '}' in result:
+            raise Invalid('Unresolved template parameter')
+        return result
+    nodes, ids, branches, outputs = [], set(), set(), []
+    for stage in config['stages']:
+        if stage['id'] in ids or stage['workBranch'] in branches:
+            raise Invalid('Duplicate stage ID or work branch')
+        ids.add(stage['id']); branches.add(stage['workBranch']); branch(stage['workBranch'])
+        relative(stage['sharedOutput'])
+        output = (shared / stage['sharedOutput']).resolve()
+        if not output.is_relative_to(shared) or output == shared:
+            raise Invalid('Shared output escapes its root')
+        if any(output == old or output.is_relative_to(old) or old.is_relative_to(output) for old in outputs):
+            raise Invalid('Overlapping shared output directories')
+        outputs.append(output)
+        if not Path(stage['acceptedInput']).is_absolute():
+            raise Invalid('Accepted input registry must be an absolute path')
+        m = meta['stages'][stage['stage']]
+        params = {**config, **stage}
+        directories = [expand(v, params) for _, v in m['outputDirectories']]
+        files = [expand(v, params) for _, v in m['outputFiles']]
+        for p in directories + files:
+            if not relative(p).is_relative_to(relative(config['bizdir'])) or p == config['bizdir']:
+                raise Invalid('Output outside business directory')
+        lines = ['### 输入', '', field('工作分支', stage['workBranch'])] + [field(k, 'localPath:' + expand(v, params)) for k, v in m['inputs']]
+        if 'inputCommit' in stage:
+            lines.append(field('阶段输入提交', stage['inputCommit']))
+        if 'group' in stage:
+            lines.append(field('业务分组', stage['group']))
+        lines += ['', '### 执行', '', f'使用 `{m["skill"]}` 完成{m["label"]}阶段。', '',
+                  field('Skill入口', config['skillsRoot'] + '/' + stage['stage'] + '/SKILL.md'), '', '### 交付', '']
+        lines += [field(k, 'gitBranchPath:' + expand(v, params)) for k, v in m['outputDirectories'] + m['outputFiles']]
+        lines.append(field('任务信息目录', 'localPath:' + str(output)))
+        lines += ['', meta['gitDeliveryInstruction'], '', field(meta['deliveryGate']['label'], meta['deliveryGate']['command']), '', meta['deliveryGate']['scope']]
+        nodes.append({'id':stage['id'], 'stage':stage['stage'], 'context':'\n'.join(lines),
+                      'workBranch':stage['workBranch'], 'outputDirectories':directories,
+                      'outputFiles':files, 'sharedOutput':str(output)})
+    common = '\n'.join(['### 全局参数', ''] + [field(k, v) for k, v in [
+        ('Git仓库',config['git']['url']), ('基线分支',config['git']['branch']), ('基线提交',config['git']['commit']),
+        ('业务目录',config['bizdir']), ('业务源版本',config['source']['commit']), ('业务源根目录',config['source']['root']),
+        ('共享根目录',str(shared)), ('Skill根目录',config['skillsRoot']), ('工具目录',config['toolsRoot'])]])
+    def checkpoint(template, params, extra_inputs=()):
+        return '\n'.join(['### 输入', ''] + [field(k, ('localPath:' if '目录' in k else '') + expand(v, params)) for k, v in template['inputs']] + list(extra_inputs) +
+                         ['', '### 审核', '', template['review'], '', '### 交付', ''] +
+                         [field(k, 'localPath:' + expand(v, params)) for k, v in template['outputs']])
+    reserved = {n['id'] + '-review' for n in nodes} | {'delivery'}
+    if ids & reserved:
+        raise Invalid('Stage ID conflicts with a checkpoint ID')
+    checkpoints = [{'id':n['id']+'-review', 'context':checkpoint(meta['checkpoint'],
+                    {**config, **n, 'stageOutput':n['sharedOutput']})} for n in nodes]
+    final = {'id':'delivery', 'context':checkpoint(meta['delivery'], config,
+             [field(n['id']+'工作分支', n['workBranch']) for n in nodes])}
+    return {'schemaVersion':1,'metaVersion':meta['version'],'commonContext':common,'nodes':nodes,
+            'checkpoints':checkpoints,'delivery':final}
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('action', choices=['render', 'diff-review'])
+    parser.add_argument('--input', required=True)
+    parser.add_argument('--workflow', required=True, help='Frozen workflow Skill directory')
+    parser.add_argument('--output', required=True, help='Review JSON; node contexts are Markdown')
+    parser.add_argument('--repository')
+    parser.add_argument('--base')
+    parser.add_argument('--head')
+    parser.add_argument('--stage-id', action='append')
+    args = parser.parse_args(argv)
+    try:
+        result = render(json.loads(Path(args.input).read_text()), args.workflow)
+        target = Path(args.output)
+        if target.exists():
+            raise Invalid('Output already exists; choose a new review artifact')
+        if args.action == 'diff-review':
+            if not all((args.repository, args.base, args.head, args.stage_id)):
+                raise Invalid('diff-review requires repository, base, head and stage-id')
+            selected = [n for n in result['nodes'] if n['id'] in args.stage_id]
+            if {n['id'] for n in selected} != set(args.stage_id):
+                raise Invalid('Unknown stage ID in diff-review scope')
+            from .diff_review import review
+            checked = review(args.repository, args.base, args.head, selected)
+            target.write_text(checked['markdown'])
+            return 0 if checked['passed'] else 3
+        target.write_text(json.dumps(result, ensure_ascii=False, indent=2) + '\n')
+    except (ValueError, KeyError, OSError) as error:
+        print(str(error), file=sys.stderr)
+        return 2
+    return 0