@guanlin4924/devflow-pi 0.1.78 → 0.1.79

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanlin4924/devflow-pi",
-  "version": "0.1.78",
+  "version": "0.1.79",
   "type": "module",
   "description": "Devflow 专项研发 Pi，基于固定版本 OMP Runtime 组装研发状态机、代码智能、设计、实现与质量门禁。",
   "license": "UNLICENSED",

package/plugins/devflow-intel/extensions/devflow-intel.ts

@@ -53,9 +53,11 @@ export default function devflowIntel(pi: ExtensionAPI) {
     label: "Devflow Code Index",
     description: "Scan, validate, audit, or query the deterministic project code index.",
     parameters: z.object({
-      action: z.enum(["scan", "validate", "audit", "query", "relations"]),
+      action: z.enum(["scan", "validate", "audit", "query", "relations", "impact"]),
       term: z.string().optional(),
       object: z.string().optional(),
+      entity: z.string().optional(),
+      changeType: z.enum(["remove_field", "rename_field", "change_type", "optional_to_required", "required_to_optional", "change_nullability", "change_enum"]).optional(),
       snapshot: z.string().optional(),
       depth: z.number().int().min(0).max(20).default(3),
       includeHeuristic: z.boolean().default(false),
@@ -76,8 +78,10 @@ export default function devflowIntel(pi: ExtensionAPI) {
         if (params.changedFiles.length > 0) args.push("--changed-files", ...params.changedFiles);
       } else if (params.action === "validate") {
         args.push("--index", ".planning/code-index");
+        if (params.snapshot) args.push("--snapshot", params.snapshot);
       } else if (params.action === "audit") {
         args.push("--root", ctx.cwd, "--index", ".planning/code-index", "--skill-root", skillRoot);
+        if (params.snapshot) args.push("--snapshot", params.snapshot);
       } else if (params.action === "query") {
         if (!params.term) {
           return render({ ok: false, exitCode: 2, stdout: "", stderr: "term is required" }, {});
@@ -85,6 +89,13 @@ export default function devflowIntel(pi: ExtensionAPI) {
         args.push("--index", ".planning/code-index", "--term", params.term, "--limit", String(params.limit));
         if (params.snapshot) args.push("--snapshot", params.snapshot);
       } else {
+        if (params.action === "impact") {
+          if (!params.entity) return render({ ok: false, exitCode: 2, stdout: "", stderr: "entity is required" }, {});
+          args.push("--index", ".planning/code-index", "--entity", params.entity, "--depth", String(params.depth), "--limit", String(params.limit));
+          if (params.snapshot) args.push("--snapshot", params.snapshot);
+          if (params.changeType) args.push("--change-type", params.changeType);
+          return render(await run(args, ctx.cwd), { action: params.action });
+        }
         if (!params.object) return render({ ok: false, exitCode: 2, stdout: "", stderr: "object is required" }, {});
         args.push("--index", ".planning/code-index", "--object", params.object, "--depth", String(params.depth), "--limit", String(params.limit));
         if (params.snapshot) args.push("--snapshot", params.snapshot);

package/plugins/devflow-intel/skills/code-index-query/SKILL.md

@@ -32,6 +32,14 @@ devflow_code_index(action="scan")
 devflow_code_index(action="audit")
 ```
 
+Impact analysis uses the same immutable SQLite snapshot:
+
+```text
+devflow_code_index(action="impact", entity="{entity_id}", changeType="remove_field")
+```
+
+The result carries `_meta.snapshot`, coverage, and truncation status. Older structural-only snapshots return an explicit semantic capability-unavailable result; they remain valid for symbol and relation queries.
+
 ## Query Patterns
 
 For more detailed query patterns, read `references/query-patterns.md`.

package/plugins/devflow-intel/skills/workflow-code-index/SKILL.md

@@ -44,6 +44,7 @@ Use the OMP runtime tool:
 devflow_code_index(action="scan")
 devflow_code_index(action="validate")
 devflow_code_index(action="audit")
+devflow_code_index(action="impact", entity="api:orders", changeType="remove_field")
 ```
 
 For changed-file indexing:
@@ -66,3 +67,7 @@ Blocking findings are stale file hashes, missing indexed files, dangling `to_id`
 - Do not mark dynamic or string-based matches as `exact`.
 - If adapter support is missing, emit diagnostics and fall back to generic indexing.
 - Query answers must read source files at evidence paths before making factual claims.
+- The root `SNAPSHOT.json` is only a pointer. Queries, validation, audit, and impact resolve it to the immutable `snapshots/{generation}` directory before reading facts.
+- Query results include snapshot and parser provenance. A historical snapshot may be queried with `snapshot`; it is not freshness-checked against the current worktree.
+- `impact` is a typed semantic query. It returns `unavailable` with `semantic_capability_unavailable` when an older structural-only snapshot has no semantic tables; it never executes arbitrary SQL.
+- Query limits are bounded by the runtime. Negative or oversized limits are normalized safely.

package/plugins/devflow-intel/skills/workflow-code-index/scripts/code_index.py

@@ -65,7 +65,17 @@ def _publish_snapshot(staging: Path, output: Path, counts: Dict[str, int], works
     generation = generation or str(uuid.uuid4())
     immutable_relative = f"snapshots/{generation}"
     snapshot = {
+        # Keep the public snapshot schema stable while exposing the richer
+        # SQLite schema separately.  Older consumers only know schemaVersion=1.
         "schemaVersion": 1,
+        "indexSchemaVersion": 3,
+        "capabilities": {
+            "structural": True,
+            "semantic": True,
+            "fts": True,
+            "relations": True,
+            "provenance": True,
+        },
         "generation": generation,
         "generatedAt": datetime.now(timezone.utc).isoformat(),
         "counts": counts,
@@ -189,11 +199,13 @@ def main(argv=None) -> int:
 
     validate = sub.add_parser("validate", help="Validate JSONL schema.")
     validate.add_argument("--index", default=".planning/code-index", help="Index directory.")
+    validate.add_argument("--snapshot", help="Immutable generation id.")
 
     audit = sub.add_parser("audit", help="Audit stale files and relation integrity.")
     audit.add_argument("--root", default=".", help="Project root.")
     audit.add_argument("--index", default=".planning/code-index", help="Index directory.")
     audit.add_argument("--skill-root", default=".skills", help="Optional skill root for project-binding checks.")
+    audit.add_argument("--snapshot", help="Immutable generation id.")
 
     query = sub.add_parser("query", help="Search symbols using SQLite FTS or LIKE fallback.")
     query.add_argument("--index", default=".planning/code-index", help="Index directory.")
@@ -335,6 +347,12 @@ def command_scan(args) -> int:
                 registry_capabilities() if registry_capabilities else {},
             )
             workspace_state["generatedAt"] = datetime.now(timezone.utc).isoformat()
+            workspace_state["scanScope"] = {
+                "exclude": sorted(set(args.exclude)),
+                "codebases": [
+                    {"name": item.name, "path": str(item.root)} for item in codebases
+                ],
+            }
             workspace_state["semanticExtractor"] = SEMANTIC_EXTRACTOR_VERSION
             workspace_state["extractorSetHash"] = _hash_lines([*workspace_state.get("extractors", []), SEMANTIC_EXTRACTOR_VERSION])
             progress.emit("semantic", "building semantic facts")
@@ -389,19 +407,27 @@ def command_scan(args) -> int:
 
 def command_validate(args) -> int:
     output = Path(args.index).resolve()
-    selected = _selected_generation(output, None)
+    selected = _selected_generation(output, getattr(args, "snapshot", None))
     errors = []
     try:
         snapshot = _load_snapshot(selected)
+        errors.extend(_validate_snapshot_bundle(selected, snapshot))
         files, symbols, relations, diagnostics = _load_tuple(selected)
         errors.extend(validate_index(files, symbols, relations, diagnostics))
         conn = sqlite3.connect(str(selected / "index.sqlite"))
         try:
             snapshot_id = snapshot.get("generation")
-            row = conn.execute("SELECT snapshot_id FROM analysis_snapshots WHERE snapshot_id=?", (snapshot_id,)).fetchone()
-            if not row:
-                errors.append(f"semantic schema missing snapshot {snapshot_id}")
-            dangling = conn.execute("""
+            tables = _table_names(conn)
+            if "analysis_snapshots" in tables:
+                row = conn.execute("SELECT snapshot_id FROM analysis_snapshots WHERE snapshot_id=?", (snapshot_id,)).fetchone()
+                if not row:
+                    errors.append(f"snapshot metadata missing generation {snapshot_id}")
+            semantic_tables = {"semantic_flows", "entity_versions", "feature_bindings", "coverage_metrics"}
+            if not semantic_tables.issubset(tables):
+                # Structural-only historical snapshots remain valid.
+                snapshot.setdefault("capabilities", {})["semantic"] = False
+            else:
+                dangling = conn.execute("""
               SELECT COUNT(*) FROM semantic_flows f
               WHERE f.snapshot_id=? AND (
                 (NOT EXISTS (SELECT 1 FROM entity_versions e WHERE e.snapshot_id=f.snapshot_id AND e.logical_id=f.source_id)
@@ -410,18 +436,18 @@ def command_validate(args) -> int:
                 (NOT EXISTS (SELECT 1 FROM entity_versions e WHERE e.snapshot_id=f.snapshot_id AND e.logical_id=f.target_id)
                  AND NOT EXISTS (SELECT 1 FROM symbols s WHERE s.id=f.target_id))
               )
-            """, (snapshot_id,)).fetchone()[0]
-            if dangling:
-                errors.append(f"semantic flows have {dangling} dangling source or target nodes")
-            binding_dangling = conn.execute("""
+                """, (snapshot_id,)).fetchone()[0]
+                if dangling:
+                    errors.append(f"semantic flows have {dangling} dangling source or target nodes")
+                binding_dangling = conn.execute("""
               SELECT COUNT(*) FROM feature_bindings b
               WHERE b.snapshot_id=? AND (
                 NOT EXISTS (SELECT 1 FROM entity_versions e WHERE e.snapshot_id=b.snapshot_id AND e.logical_id=b.feature_id)
                 OR NOT EXISTS (SELECT 1 FROM entity_versions e WHERE e.snapshot_id=b.snapshot_id AND e.logical_id=b.entity_id)
               )
-            """, (snapshot_id,)).fetchone()[0]
-            if binding_dangling:
-                errors.append(f"feature bindings have {binding_dangling} dangling feature or entity nodes")
+                """, (snapshot_id,)).fetchone()[0]
+                if binding_dangling:
+                    errors.append(f"feature bindings have {binding_dangling} dangling feature or entity nodes")
         finally:
             conn.close()
     except (OSError, sqlite3.Error, ValueError) as exc:
@@ -438,6 +464,11 @@ def command_query(args) -> int:
             print(f"Missing index: {index}", file=sys.stderr)
             return 1
         snapshot = _load_snapshot(selected)
+        bundle_errors = _validate_snapshot_bundle(selected, snapshot)
+        if bundle_errors:
+            print(bundle_errors[0], file=sys.stderr)
+            return 1
+        limit = _bounded_limit(getattr(args, "limit", 20), 1000)
         files = read_jsonl(selected / INDEX_FILES["files"])
         if not getattr(args, "snapshot", None) and not _query_is_fresh(output.parent.parent, snapshot, files):
             print("Stale code index: refresh required before query.", file=sys.stderr)
@@ -445,30 +476,38 @@ def command_query(args) -> int:
         conn = sqlite3.connect(str(index))
         conn.row_factory = sqlite3.Row
         try:
+            symbol_columns = {row[1] for row in conn.execute("PRAGMA table_info(symbols)")}
+            provenance = ", parser, content_hash, metadata_json" if {"parser", "content_hash", "metadata_json"}.issubset(symbol_columns) else ", NULL AS parser, NULL AS content_hash, NULL AS metadata_json"
             try:
                 rows = conn.execute(
-                    """
-                    SELECT id, codebase, kind, name, qualified_name, path, line_start, line_end
+                    f"""
+                    SELECT id, codebase, kind, name, qualified_name, path, line_start, line_end,
+                           {provenance[2:]}
                     FROM symbols_fts
                     JOIN symbols USING(id)
                     WHERE symbols_fts MATCH ?
                     LIMIT ?
                     """,
-                    (args.term, args.limit),
+                    (args.term, limit),
                 ).fetchall()
             except sqlite3.OperationalError:
                 like = f"%{args.term}%"
                 rows = conn.execute(
-                    """
-                    SELECT id, codebase, kind, name, qualified_name, path, line_start, line_end
+                    f"""
+                    SELECT id, codebase, kind, name, qualified_name, path, line_start, line_end,
+                           {provenance[2:]}
                     FROM symbols
                     WHERE name LIKE ? OR qualified_name LIKE ? OR path LIKE ?
                     LIMIT ?
                     """,
-                    (like, like, like, args.limit),
+                    (like, like, like, limit),
                 ).fetchall()
             for row in rows:
-                print(json.dumps(dict(row), ensure_ascii=False, sort_keys=True))
+                item = dict(row)
+                item["snapshot"] = snapshot.get("generation")
+                item["parser"] = item.get("parser") or "unknown"
+                item["confidence"] = item.get("confidence") or confidence_for_parser(item["parser"], "symbol")
+                print(json.dumps(item, ensure_ascii=False, sort_keys=True))
         finally:
             conn.close()
     return 0
@@ -476,14 +515,22 @@ def command_query(args) -> int:
 
 def command_relations(args) -> int:
     output = Path(args.index).resolve()
-    depth = max(0, min(args.depth, 20)); limit = max(1, min(args.limit, 1000))
+    depth = max(0, min(args.depth, 20)); limit = _bounded_limit(args.limit, 1000)
     with _index_lock(output, exclusive=False):
         selected = _selected_generation(output, getattr(args, "snapshot", None))
         snapshot = _load_snapshot(selected); files = read_jsonl(selected / INDEX_FILES["files"])
+        bundle_errors = _validate_snapshot_bundle(selected, snapshot)
+        if bundle_errors:
+            print(bundle_errors[0], file=sys.stderr); return 1
         if not getattr(args, "snapshot", None) and not _query_is_fresh(output.parent.parent, snapshot, files):
             print("Stale code index: refresh required before query.", file=sys.stderr); return 1
         conn = sqlite3.connect(str(selected / "index.sqlite")); conn.row_factory = sqlite3.Row
         try:
+            symbol_columns = {row[1] for row in conn.execute("PRAGMA table_info(symbols)")}
+            parser_expr = "s.parser" if "parser" in symbol_columns else "NULL"
+            hash_expr = "s.content_hash" if "content_hash" in symbol_columns else "NULL"
+            to_parser_expr = "t.parser" if "parser" in symbol_columns else "NULL"
+            to_hash_expr = "t.content_hash" if "content_hash" in symbol_columns else "NULL"
             if depth == 0:
                 print(json.dumps({"_meta": {"snapshot": snapshot.get("generation"), "depthLimit": 0, "resultLimit": limit, "truncated": False}}, ensure_ascii=False, sort_keys=True))
                 return 0
@@ -496,14 +543,21 @@ def command_relations(args) -> int:
                 SELECT r.from_id,r.relation_type,r.to_id,r.to_external,r.evidence_path,r.evidence_line,r.confidence,g.depth+1,g.visited || COALESCE(r.to_id,'') || ','
                 FROM graph g JOIN relations r ON r.from_id=g.to_id
                 WHERE g.depth < ? AND r.to_id IS NOT NULL {confidence} AND instr(g.visited, ',' || r.to_id || ',')=0
-              ) SELECT * FROM graph ORDER BY depth,from_id,relation_type,to_id LIMIT ?
+              ) SELECT graph.*, s.path AS from_path, s.name AS from_name, {parser_expr} AS from_parser,
+                       {hash_expr} AS from_content_hash, t.path AS to_path, t.name AS to_name,
+                       {to_parser_expr} AS to_parser, {to_hash_expr} AS to_content_hash
+                  FROM graph
+                  LEFT JOIN symbols s ON s.id=graph.from_id
+                  LEFT JOIN symbols t ON t.id=graph.to_id
+                  ORDER BY depth,from_id,relation_type,to_id LIMIT ?
             """, (args.object, depth, limit + 1)).fetchall()
             truncated = len(rows) > limit
             for row in rows[:limit]:
                 item = dict(row)
+                item["snapshot"] = snapshot.get("generation")
                 if getattr(args, "change_type", None):
                     item["impact_kind"] = args.change_type
-                    item["severity"] = _impact_severity(args.change_type, item["flow_type"])
+                    item["severity"] = _impact_severity(args.change_type, item.get("flow_type", "relation"))
                 print(json.dumps(item, ensure_ascii=False, sort_keys=True))
             print(json.dumps({"_meta": {"snapshot": snapshot.get("generation"), "depthLimit": depth, "resultLimit": limit, "truncated": truncated}}, ensure_ascii=False, sort_keys=True))
         finally: conn.close()
@@ -523,10 +577,13 @@ def _impact_severity(change_type: str, flow_type: str) -> str:
 
 def command_impact(args) -> int:
     output = Path(args.index).resolve()
-    depth = max(0, min(args.depth, 20)); limit = max(1, min(args.limit, 2000))
+    depth = max(0, min(args.depth, 20)); limit = _bounded_limit(args.limit, 2000)
     with _index_lock(output, exclusive=False):
         selected = _selected_generation(output, getattr(args, "snapshot", None))
         snapshot = _load_snapshot(selected)
+        bundle_errors = _validate_snapshot_bundle(selected, snapshot)
+        if bundle_errors:
+            print(bundle_errors[0], file=sys.stderr); return 1
         if not getattr(args, "snapshot", None):
             files = read_jsonl(selected / INDEX_FILES["files"])
             if not _query_is_fresh(output.parent.parent, snapshot, files):
@@ -534,6 +591,11 @@ def command_impact(args) -> int:
                 return 1
         conn = sqlite3.connect(str(selected / "index.sqlite")); conn.row_factory = sqlite3.Row
         try:
+            tables = _table_names(conn)
+            semantic_tables = {"semantic_flows", "entity_versions", "feature_bindings", "coverage_metrics"}
+            if not semantic_tables.issubset(tables):
+                print(json.dumps({"_meta": {"snapshot": snapshot.get("generation"), "status": "unavailable", "reason": "semantic_capability_unavailable", "coverage": {"status": "unknown"}, "truncated": False}}, ensure_ascii=False, sort_keys=True))
+                return 0
             rows = conn.execute("""
               WITH RECURSIVE graph(node_id, flow_type, source_path, line_start, confidence, depth, visited) AS (
                 SELECT CASE WHEN source_id=? THEN target_id ELSE source_id END, flow_type, source_path, line_start, confidence, 1, ',' || ? || ','
@@ -545,7 +607,12 @@ def command_impact(args) -> int:
                 WHERE g.depth < ? AND instr(g.visited, ',' || CASE WHEN f.source_id=g.node_id THEN f.target_id ELSE f.source_id END || ',')=0
               ) SELECT * FROM graph LIMIT ?
             """, (args.entity, args.entity, snapshot.get("generation"), args.entity, args.entity, snapshot.get("generation"), depth, limit + 1)).fetchall()
-            for row in rows[:limit]: print(json.dumps(dict(row), ensure_ascii=False, sort_keys=True))
+            for row in rows[:limit]:
+                item = dict(row); item["snapshot"] = snapshot.get("generation")
+                if getattr(args, "change_type", None):
+                    item["impact_kind"] = args.change_type
+                    item["severity"] = _impact_severity(args.change_type, item.get("flow_type", "relation"))
+                print(json.dumps(item, ensure_ascii=False, sort_keys=True))
             coverage_row = conn.execute("SELECT * FROM coverage_metrics WHERE snapshot_id=?", (snapshot.get("generation"),)).fetchone()
             coverage = dict(coverage_row) if coverage_row else {"status": "unknown"}
             print(json.dumps({"_meta": {"snapshot": snapshot.get("generation"), "coverage": coverage, "depthLimit": depth, "truncated": len(rows) > limit}}, ensure_ascii=False, sort_keys=True))
@@ -556,6 +623,13 @@ def command_impact(args) -> int:
 
 def _selected_generation(output: Path, generation: str | None) -> Path:
     if not generation:
+        root_snapshot = _load_snapshot(output)
+        current = root_snapshot.get("generation") if root_snapshot else None
+        if current and re.fullmatch(r"[0-9a-f-]{36}", str(current), re.I):
+            selected = output / "snapshots" / str(current)
+            if selected.is_dir():
+                return selected
+        # Legacy indexes predating immutable snapshots remain readable.
         return output
     if not re.fullmatch(r"[0-9a-f-]{36}", generation, re.I):
         raise ValueError("invalid snapshot generation")
@@ -573,6 +647,44 @@ def _load_snapshot(output: Path) -> Dict[str, object]:
     return json.loads(path.read_text(encoding="utf-8"))
 
 
+def _bounded_limit(value, maximum: int) -> int:
+    try:
+        value = int(value)
+    except (TypeError, ValueError):
+        value = 20
+    return max(1, min(value, maximum))
+
+
+def _table_names(conn: sqlite3.Connection) -> set[str]:
+    return {row[0] for row in conn.execute("SELECT name FROM sqlite_master WHERE type IN ('table','virtual table')")}
+
+
+def _validate_snapshot_bundle(selected: Path, snapshot: Dict[str, object]) -> List[str]:
+    errors: List[str] = []
+    generation = snapshot.get("generation")
+    if not generation:
+        return [f"snapshot metadata missing generation in {selected}"]
+    required = [SNAPSHOT_FILE, "index.sqlite", *INDEX_FILES.values()]
+    for name in required:
+        if not (selected / name).is_file():
+            errors.append(f"snapshot {generation} missing artifact {name}")
+    index = selected / "index.sqlite"
+    if index.is_file():
+        try:
+            conn = sqlite3.connect(str(index))
+            try:
+                tables = _table_names(conn)
+                if "analysis_snapshots" in tables:
+                    row = conn.execute("SELECT snapshot_id FROM analysis_snapshots LIMIT 1").fetchone()
+                    if row and row[0] != generation:
+                        errors.append(f"snapshot generation mismatch: metadata={generation}, sqlite={row[0]}")
+            finally:
+                conn.close()
+        except sqlite3.Error as exc:
+            errors.append(f"invalid sqlite snapshot {generation}: {exc}")
+    return errors
+
+
 def _query_is_fresh(root: Path, snapshot: Dict[str, object], files: List[dict]) -> bool:
     workspace = snapshot.get("workspace") if isinstance(snapshot, dict) else None
     if not isinstance(workspace, dict):
@@ -591,7 +703,9 @@ def _query_is_fresh(root: Path, snapshot: Dict[str, object], files: List[dict])
             return False
     indexed_paths = sorted(record["path"] for record in files)
     if not any(path.startswith("../") for path in indexed_paths):
-        current_paths = sorted(_workspace_rel(root, item) for item in scan_files(root))
+        scope = workspace.get("scanScope") if isinstance(workspace.get("scanScope"), dict) else {}
+        excludes = scope.get("exclude", []) if isinstance(scope, dict) else []
+        current_paths = sorted(_workspace_rel(root, item) for item in scan_files(root, excludes=excludes))
         expected_paths_hash = workspace.get("discoveredPathsHash") or workspace.get("indexedPathsHash")
         if _hash_lines(current_paths) != expected_paths_hash:
             return False
@@ -603,7 +717,14 @@ def command_audit(args) -> int:
     root = Path(args.root).resolve()
     output = Path(args.index).resolve()
     with _index_lock(output, exclusive=True):
-        files, symbols, relations, diagnostics = _load_tuple(output)
+        selected = _selected_generation(output, getattr(args, "snapshot", None))
+        snapshot = _load_snapshot(selected)
+        bundle_errors = _validate_snapshot_bundle(selected, snapshot)
+        if bundle_errors:
+            for error in bundle_errors:
+                print(error, file=sys.stderr)
+            return 1
+        files, symbols, relations, diagnostics = _load_tuple(selected)
         findings = []
         findings.extend(audit_stale(root, files))
         findings.extend(audit_relations(symbols, relations))

package/src/constants.ts

@@ -1,5 +1,5 @@
 export const PRODUCT_NAME = "Devflow Pi";
-export const PRODUCT_VERSION = "0.1.78";
+export const PRODUCT_VERSION = "0.1.79";
 export const PROJECT_SCHEMA_VERSION = 1;
 export const OMP_RUNTIME_VERSION = "17.2.7";