@amityco/social-plus-vise 1.0.0 → 1.1.0

package/dist/tools/ast.js

@@ -1,26 +1,5 @@
-/**
- * AST-based deterministic analysis helpers using tree-sitter.
- *
- * This module provides syntactic (not type-resolving) analysis for source files.
- * It is an additive layer alongside the existing regex-based validators.
- *
- * Policy: When AST and regex disagree (e.g., regex matches a comment), the regex
- * result wins for now. AST cleanup of comment false-matches is Phase 4 work.
- *
- * Scope: Single-file, single-step identifier resolution only.
- * No cross-file imports, no type inference, no function boundary traversal.
- */
 import { createRequire } from "node:module";
 const nodeRequire = createRequire(import.meta.url);
-// Lazily and defensively load the tree-sitter native bindings. tree-sitter ships
-// prebuilt binaries for common platforms (darwin, linux-x64, win32-x64); on others
-// (linux-arm64, Alpine/musl, win32-arm64) the binding can fail to load when no C++
-// toolchain is present. AST is an ADDITIVE layer over the regex validators, so a
-// load failure must degrade to regex-only — NOT take down the entire CLI (including
-// doc-search/compliance commands that never touch a parser) at import time. Static
-// top-level imports would throw at module load and brick every command; this loader
-// confines the failure to the AST path. `undefined` = not yet attempted; `null` =
-// attempted and unavailable.
 let nativeBindings;
 function loadNativeBindings() {
     if (nativeBindings !== undefined)
@@ -29,8 +8,6 @@ function loadNativeBindings() {
         const ParserCtor = nodeRequire("tree-sitter");
         const tsGrammars = nodeRequire("tree-sitter-typescript");
         const kotlinGrammar = nodeRequire("tree-sitter-kotlin");
-        // Swift loads in its own try/catch: a missing tree-sitter-swift prebuild on an
-        // exotic platform must degrade ONLY the Swift helpers, not all AST analysis.
         let swiftGrammar = null;
         try {
             swiftGrammar = nodeRequire("tree-sitter-swift");
@@ -51,28 +28,12 @@ function loadNativeBindings() {
     }
     return nativeBindings;
 }
-/**
- * Whether tree-sitter native bindings are available in this environment. When
- * false, every AST helper degrades gracefully: parse() throws (so tryParse()
- * returns null and stripComments() returns the source unchanged), and validators
- * fall back to their regex paths.
- */
 export function astAvailable() {
     return loadNativeBindings() !== null;
 }
-/**
- * Whether the Swift grammar specifically is available. tree-sitter-swift is loaded
- * independently of the core bindings (see loadNativeBindings), so Swift-only
- * validators can check this and fall back to regex without disabling ts/tsx/kotlin.
- */
 export function swiftAstAvailable() {
     return loadNativeBindings()?.swiftGrammar != null;
 }
-/**
- * Strip comments from source code using tree-sitter AST.
- * Replaces comment spans with whitespace (preserving line structure).
- * Returns original source unchanged if parsing fails.
- */
 export function stripComments(language, source) {
     try {
         const tree = parse(language, source);
@@ -80,7 +41,6 @@ export function stripComments(language, source) {
         collectComments(tree.rootNode, commentRanges);
         if (commentRanges.length === 0)
             return source;
-        // Replace comment ranges with spaces (preserve newlines for line numbers)
         const chars = source.split("");
         for (const { start, end } of commentRanges) {
             for (let i = start; i < end && i < chars.length; i++) {
@@ -105,7 +65,6 @@ function collectComments(node, out) {
             collectComments(child, out);
     }
 }
-// Parser instances are reusable — one per language.
 const parsers = new Map();
 function getParser(language) {
     let parser = parsers.get(language);
@@ -131,18 +90,7 @@ function getParser(language) {
     }
     return parser;
 }
-// node-tree-sitter's native parser rejects sufficiently large inputs with a
-// native "Invalid argument" error (~32KB string limit). It IS catchable, but an
-// unguarded caller would otherwise abort the whole validate run. We short-circuit
-// before the native call so callers get a clean, documented, catchable error and
-// can degrade to regex-only for that file. Real codebases routinely have files
-// past this size (1000+ line activities/view controllers).
 export const MAX_PARSE_BYTES = 30000;
-/**
- * Parse source content into a tree-sitter syntax tree.
- * Throws on oversized input (see MAX_PARSE_BYTES) — callers that want graceful
- * degradation should use tryParse or wrap this in try/catch.
- */
 export function parse(language, source) {
     if (Buffer.byteLength(source, "utf8") > MAX_PARSE_BYTES) {
         throw new Error(`source exceeds tree-sitter parse limit (${Buffer.byteLength(source, "utf8")} bytes > ${MAX_PARSE_BYTES})`);
@@ -150,11 +98,6 @@ export function parse(language, source) {
     const parser = getParser(language);
     return parser.parse(source);
 }
-/**
- * Parse, returning null instead of throwing when the source can't be parsed
- * (oversized input, native parser error). Lets validators skip AST analysis for
- * one file and fall back to regex without aborting the run.
- */
 export function tryParse(language, source) {
     try {
         return parse(language, source);
@@ -163,16 +106,11 @@ export function tryParse(language, source) {
         return null;
     }
 }
-/**
- * Find all call expressions in the tree whose callee matches a pattern.
- * Returns normalised callee strings and argument nodes.
- */
 export function findCallExpressions(tree, calleePattern) {
     const results = [];
     walkTree(tree.rootNode, (node) => {
         if (node.type !== "call_expression")
             return;
-        // TypeScript: uses field names "function" and "arguments"
         const calleeNode = node.childForFieldName("function");
         if (calleeNode) {
             const callee = normaliseCallee(calleeNode);
@@ -190,10 +128,6 @@ export function findCallExpressions(tree, calleePattern) {
             results.push({ callee, node, args });
             return;
         }
-        // Kotlin AND Swift: call_expression = navigation_expression + call_suffix.
-        // (tree-sitter-swift descends from the Kotlin grammar, so the node names —
-        // navigation_expression / navigation_suffix / call_suffix / value_arguments —
-        // are identical; only Swift's labeled arguments add a value_argument_label.)
         const navNode = node.namedChild(0);
         const suffixNode = node.namedChild(1);
         if (!navNode || !suffixNode || suffixNode.type !== "call_suffix")
@@ -201,16 +135,12 @@ export function findCallExpressions(tree, calleePattern) {
         const callee = normaliseKotlinCallee(navNode);
         if (!callee || !calleePattern.test(callee))
             return;
-        // Extract args from call_suffix → value_arguments → value_argument nodes
         const args = [];
         const valArgsNode = suffixNode.namedChild(0);
         if (valArgsNode && valArgsNode.type === "value_arguments") {
             for (let i = 0; i < valArgsNode.namedChildCount; i++) {
                 const valArg = valArgsNode.namedChild(i);
                 if (valArg && valArg.type === "value_argument") {
-                    // The actual expression is inside value_argument. Swift labeled arguments
-                    // put a value_argument_label first — the value is the last named child.
-                    // Kotlin behaviour (namedChild(0)) is intentionally unchanged.
                     const first = valArg.namedChild(0);
                     const expr = first?.type === "value_argument_label" ? valArg.namedChild(valArg.namedChildCount - 1) : first;
                     if (expr)
@@ -222,56 +152,25 @@ export function findCallExpressions(tree, calleePattern) {
     });
     return results;
 }
-// Bound on identifier→identifier resolution chains. Five hops covers realistic
-// re-binding (`const RAW = "…"; const T = RAW; const X = T;`) while keeping the
-// walk cheap; a `visited` set guards against cyclic self-reference (which would
-// be a type error anyway, but the parser still produces a tree for it).
 const MAX_RESOLUTION_HOPS = 5;
-/**
- * Resolve an AST node to its literal string value within the same file.
- *
- * Handles:
- * - String literals directly → returns the string value
- * - A pure-passthrough template literal — `` `${X}` `` with exactly one
- *   substitution and no cooked text — which is value-equivalent to `X`; the
- *   substitution is resolved through this same resolver. Templates with any
- *   literal text (`` `pre${X}` ``) or a dynamic substitution (`` `${a.b}` ``)
- *   are NOT pure passthrough and stay unresolved. (Arbitrary string
- *   concatenation is a separate, larger blind spot — intentionally not handled.)
- * - Identifiers that reference a const/let/var whose initializer resolves to a
- *   literal, following identifier→identifier re-bind chains up to
- *   MAX_RESOLUTION_HOPS deep (multi-hop), with a cycle guard. A binding to any
- *   dynamic expression (member access, call, parameter, env fallback, …)
- *   terminates the chain and stays unresolved — multi-hop never makes a runtime
- *   value look literal.
- *
- * Returns undefined if the value cannot be statically resolved.
- */
 export function resolveLiteralValue(node, tree) {
     return resolveLiteralValueBounded(node, tree, MAX_RESOLUTION_HOPS, new Set());
 }
 function resolveLiteralValueBounded(node, tree, hopsLeft, visited) {
-    // Direct string literal
     const directValue = extractStringLiteral(node);
     if (directValue !== undefined)
         return directValue;
-    // Pure-passthrough template literal: `${X}` (exactly one substitution, no text).
-    // Equivalent to resolving X itself. Bounded to this one shape — not concat.
     if (node.type === "template_string") {
         const passthrough = templatePassthroughSubstitution(node);
         if (passthrough)
             return resolveLiteralValueBounded(passthrough, tree, hopsLeft, visited);
     }
-    // Identifier — resolve to its declaration in the same file, then recurse into
-    // the initializer so identifier→identifier re-binds and template re-wraps
-    // chain through to the underlying literal.
-    // TypeScript uses "identifier", Kotlin uses "simple_identifier".
     if (node.type === "identifier" || node.type === "simple_identifier") {
         if (hopsLeft <= 0)
             return undefined;
         const name = node.text;
         if (visited.has(name))
-            return undefined; // cycle guard
+            return undefined;
         visited.add(name);
         const valueNode = resolveIdentifierToValueNode(name, tree.rootNode);
         if (!valueNode)
@@ -280,12 +179,6 @@ function resolveLiteralValueBounded(node, tree, hopsLeft, visited) {
     }
     return undefined;
 }
-/**
- * If `node` is a template literal that is a pure passthrough of a single
- * substitution — `` `${X}` `` with exactly one `template_substitution` child,
- * no `string_fragment` (cooked text) — return that substitution's inner
- * expression node. Otherwise undefined.
- */
 function templatePassthroughSubstitution(node) {
     if (node.type !== "template_string")
         return undefined;
@@ -296,35 +189,17 @@ function templatePassthroughSubstitution(node) {
             continue;
         if (child.type === "template_substitution") {
             if (substitution)
-                return undefined; // more than one substitution → not passthrough
+                return undefined;
             substitution = child;
         }
         else {
-            // Any other named child (e.g. string_fragment cooked text) → has literal
-            // content, so not a pure passthrough.
             return undefined;
         }
     }
     if (!substitution)
         return undefined;
-    // The substitution wraps a single expression: `${ expr }`.
     return substitution.namedChild(0) ?? undefined;
 }
-/**
- * Unwrap TypeScript expression wrappers that are transparent for static value
- * extraction — type casts and grouping that don't change the runtime value:
- *   - `expr as T`        (as_expression)
- *   - `expr satisfies T` (satisfies_expression)
- *   - `(expr)`           (parenthesized_expression)
- *   - `expr!`            (non_null_expression)
- *   - `<T>expr`          (type_assertion, angle-bracket cast)
- * Nested wrappers are peeled fully (`({ … } as any)!`). The inner expression is
- * always the wrapper's FIRST named child across these node types. Non-wrapper
- * nodes are returned unchanged, so callers can apply this unconditionally.
- *
- * High-frequency motivation: agents emit `as any` constantly to silence TS
- * errors, which otherwise hides the payload object from property extraction.
- */
 export function unwrapExpression(node) {
     let current = node;
     const wrappers = new Set([
@@ -334,8 +209,6 @@ export function unwrapExpression(node) {
         "non_null_expression",
         "type_assertion",
     ]);
-    // Bounded peel: a handful of stacked casts at most; the guard prevents any
-    // pathological loop if a grammar ever yields a self-referential first child.
     for (let i = 0; i < 16 && wrappers.has(current.type); i++) {
         const inner = current.namedChild(0);
         if (!inner)
@@ -344,14 +217,6 @@ export function unwrapExpression(node) {
     }
     return current;
 }
-/**
- * Pick a specific named property from an object argument node.
- * E.g., from `{ userId: HARDCODED }`, pick the value node for "userId".
- *
- * The argument is unwrapped first, so a cast/parenthesized/non-null-wrapped
- * payload (`{ … } as any`, `({ … })`, `{ … }!`) is still treated as the inner
- * object — otherwise the wrapper hides every property from extraction.
- */
 export function pickObjectProperty(objectNode, propertyName) {
     const unwrapped = unwrapExpression(objectNode);
     if (unwrapped.type !== "object")
@@ -368,14 +233,6 @@ export function pickObjectProperty(objectNode, propertyName) {
     }
     return undefined;
 }
-/**
- * Pick the value of a labeled argument from a Swift call expression node.
- * E.g., from `client.login(userId: HARDCODED, sessionHandler: handler)`,
- * pick the value node for label "userId".
- *
- * Swift-shaped trees only (call_suffix → value_arguments → value_argument with a
- * value_argument_label). Returns undefined when the label is absent.
- */
 export function pickLabeledArgument(callNode, label) {
     for (let i = 0; i < callNode.namedChildCount; i++) {
         const suffix = callNode.namedChild(i);
@@ -392,24 +249,11 @@ export function pickLabeledArgument(callNode, label) {
             if (first?.type !== "value_argument_label" || first.text !== label)
                 continue;
             const value = valArg.namedChild(valArg.namedChildCount - 1);
-            // namedChild(last) === the label itself when the argument has no value
-            // (selector-reference form) — treat as absent.
             return value && value !== first ? value : undefined;
         }
     }
     return undefined;
 }
-/**
- * Find Swift `let`/`var` declarations whose initializer text matches a pattern AND
- * which are function-local (declared inside a function/initializer/closure/computed-
- * property body rather than at type or file scope). Used for retention rules: a
- * function-local binding dies with the stack frame, while a type-scope property
- * lives with the object — a distinction regex bridges cannot make reliably.
- *
- * Conservative direction: a declaration only counts as local when a KNOWN
- * function-ish ancestor encloses it, so unknown containers degrade toward
- * "retained" (quiet), never toward a false positive.
- */
 export function findSwiftFunctionLocalDeclarations(tree, initializerPattern) {
     const results = [];
     walkTree(tree.rootNode, (node) => {
@@ -441,21 +285,16 @@ function hasFunctionAncestor(node) {
     }
     return false;
 }
-/** The initializer expression of a Swift property_declaration (the value after `=`), if any. */
 function swiftPropertyInitializer(node) {
-    // Shape: property_declaration = value_binding_pattern, pattern, [type_annotation], [value expr]
-    // The initializer (when present) is the last named child and is none of the structural parts.
     const last = node.namedChild(node.namedChildCount - 1);
     if (!last)
         return undefined;
     if (["value_binding_pattern", "pattern", "type_annotation", "modifiers", "attribute"].includes(last.type))
         return undefined;
-    // computed_property is a body, not an initializer.
     if (last.type === "computed_property")
         return undefined;
     return last;
 }
-// ── Internal helpers ──────────────────────────────────────────────────────────
 function walkTree(node, visit) {
     visit(node);
     for (let i = 0; i < node.namedChildCount; i++) {
@@ -481,8 +320,6 @@ function normaliseKotlinCallee(node) {
     if (node.type === "simple_identifier")
         return node.text;
     if (node.type === "navigation_expression") {
-        // navigation_expression has children: expression + navigation_suffix
-        // e.g., AmityCoreClient.login → nav_expr(simple_id("AmityCoreClient"), nav_suffix(".login"))
         const parts = [];
         for (let i = 0; i < node.namedChildCount; i++) {
             const child = node.namedChild(i);
@@ -492,13 +329,11 @@ function normaliseKotlinCallee(node) {
                 parts.push(child.text);
             }
             else if (child.type === "navigation_suffix") {
-                // navigation_suffix contains a simple_identifier after the dot
                 const id = child.namedChild(0);
                 if (id)
                     parts.push(id.text);
             }
             else if (child.type === "call_expression") {
-                // Chained: obj.method1().method2 — extract the last part from the chain
                 const innerCallee = normaliseKotlinCallee(child.namedChild(0));
                 if (innerCallee)
                     parts.push(innerCallee);
@@ -515,48 +350,38 @@ function normaliseKotlinCallee(node) {
 }
 function extractStringLiteral(node) {
     if (node.type === "string") {
-        // tree-sitter-typescript: string nodes include the quotes — strip them
         const text = node.text;
         if ((text.startsWith('"') && text.endsWith('"')) || (text.startsWith("'") && text.endsWith("'"))) {
             return text.slice(1, -1);
         }
-        // Template literal with no interpolations
         if (text.startsWith("`") && text.endsWith("`") && !text.includes("${")) {
             return text.slice(1, -1);
         }
     }
-    // template_string without substitutions
     if (node.type === "template_string" && node.namedChildCount === 0) {
         const text = node.text;
         if (text.startsWith("`") && text.endsWith("`")) {
             return text.slice(1, -1);
         }
     }
-    // Kotlin: string_literal contains string_content child
     if (node.type === "string_literal") {
         const contentNode = node.namedChild(0);
         if (contentNode && contentNode.type === "string_content") {
             return contentNode.text;
         }
-        // Simple case — strip quotes from text
         const text = node.text;
         if (text.startsWith('"') && text.endsWith('"')) {
             return text.slice(1, -1);
         }
     }
-    // Swift: line_string_literal contains line_str_text chunks; an interpolated
-    // string has >1 named child (line_str_text + interpolated_expression) and is
-    // NOT statically resolvable — mirror the TS template-literal treatment.
     if (node.type === "line_string_literal") {
         if (node.namedChildCount === 0)
-            return ""; // empty string ""
+            return "";
         if (node.namedChildCount === 1 && node.namedChild(0)?.type === "line_str_text") {
             return node.namedChild(0).text;
         }
         return undefined;
     }
-    // Swift: multi-line """…""" literal. Swift semantics strip the newline after the
-    // opening and before the closing delimiter.
     if (node.type === "multi_line_string_literal") {
         if (node.namedChildCount === 1 && node.namedChild(0)?.type === "multi_line_str_text") {
             return node.namedChild(0).text.replace(/^\n/, "").replace(/\n[ \t]*$/, "");
@@ -565,31 +390,11 @@ function extractStringLiteral(node) {
     }
     return undefined;
 }
-/**
- * Find the binding for `name` in the same file and return the AST node that is
- * its initializer VALUE — not the resolved string. The caller
- * (resolveLiteralValueBounded) then recurses into that node, so an initializer
- * that is itself an identifier (re-bind) or a pure-passthrough template literal
- * chains through to the underlying literal. Returns undefined when the binding
- * is absent or is a parameter / dynamic expression rather than a value
- * initializer.
- *
- * Per-platform value node:
- * - TypeScript/JS: `variable_declarator` → its `value` field.
- * - Kotlin: `property_declaration` with a `variable_declaration` → the initializer
- *   sibling (the node after `=`).
- * - Swift: `property_declaration` with `pattern` → the DIRECT string-literal
- *   initializer only. A literal nested inside another expression
- *   (`env["KEY"] ?? ""`) is not a static binding and stays unresolved — so for
- *   Swift we deliberately surface only a line/multi-line string literal node,
- *   preserving the prior conservative behavior.
- */
 function resolveIdentifierToValueNode(name, root) {
     let result;
     walkTree(root, (node) => {
         if (result !== undefined)
             return;
-        // TypeScript/JS: variable_declarator with name + value fields
         if (node.type === "variable_declarator") {
             const nameNode = node.childForFieldName("name");
             if (!nameNode || nameNode.text !== name)
@@ -597,33 +402,22 @@ function resolveIdentifierToValueNode(name, root) {
             const valueNode = node.childForFieldName("value");
             if (!valueNode)
                 return;
-            // Casts/grouping around the initializer are transparent (e.g.
-            // `const T = RAW as string;`).
             result = unwrapExpression(valueNode);
             return;
         }
-        // Kotlin: property_declaration with variable_declaration + initializer
         if (node.type === "property_declaration") {
             const varDecl = node.namedChildren.find((c) => c.type === "variable_declaration");
             if (varDecl) {
                 const idNode = varDecl.namedChildren.find((c) => c.type === "simple_identifier");
                 if (!idNode || idNode.text !== name)
                     return;
-                // The initializer is the named child after the variable_declaration.
                 const declIdx = node.namedChildren.indexOf(varDecl);
                 const initializer = node.namedChildren[declIdx + 1];
-                // Only surface a string literal or a re-bind identifier as the value node;
-                // anything else (call, when-expression, etc.) is dynamic and stays
-                // unresolved, matching the prior literal-only behavior.
                 if (initializer && (initializer.type === "string_literal" || initializer.type === "simple_identifier")) {
                     result = initializer;
                 }
                 return;
             }
-            // Swift: property_declaration with pattern → simple_identifier; the string
-            // literal (or a re-bind identifier) must be a DIRECT child (the
-            // initializer) — a literal nested inside e.g. `env["KEY"] ?? ""` is not a
-            // static binding and must not resolve.
             const pattern = node.namedChildren.find((c) => c.type === "pattern");
             if (!pattern)
                 return;

package/dist/tools/blocks.js

@@ -14,7 +14,7 @@ const registryPlatformByVisePlatform = {
 export async function listRegistryBlocks(registryPath) {
     const registry = await loadRegistry(registryPath);
     return {
-        source: "social-plus-block-factory",
+        source: "social-plus-blocks",
         mode: "block-registry",
         schemaVersion: registry.schemaVersion,
         blocks: registry.blocks.map((block) => ({
@@ -53,6 +53,7 @@ export async function addBlockInstall(options) {
         ...plan,
         applied: true,
         filesTouched,
+        nextStep: "Run `vise blocks validate <repoPath> --block <id> --registry <path>` to re-check for install drift after further edits.",
     };
 }
 export async function validateBlockInstall(options) {
@@ -68,14 +69,14 @@ export async function validateBlockInstall(options) {
             ruleId: "blocks.registry.known",
             severity: "warning",
             message: `Installed sidecar entry references unknown registry block ${entry.blockId}.`,
-            recommendation: "Update the Block Factory registry or remove stale block sidecar state.",
+            recommendation: "Update the block registry or remove stale block sidecar state.",
         }));
         if (installed.length === 0) {
             findings.push({
                 ruleId: "blocks.sidecar.installed",
                 severity: "warning",
                 message: "No installed block sidecar entries exist.",
-                recommendation: "Run `vise blocks add <repoPath> --block <id> --apply` after reviewing the dry-run plan.",
+                recommendation: "Run `vise blocks add <repoPath> --block <id> --registry <path> --apply` after reviewing the dry-run plan.",
             });
         }
         return {
@@ -91,14 +92,13 @@ export async function validateBlockInstall(options) {
     const repoPath = requiredRepoPath(options);
     const sidecar = await readSidecar(repoPath);
     const installed = (sidecar?.installed ?? []).filter((entry) => !options.blockId || entry.blockId === options.blockId);
-    // Seed with plan findings so the providesCapabilities seam guard also surfaces in validate mode.
     const findings = [...plan.findings];
     if (installed.length === 0) {
         findings.push({
             ruleId: "blocks.sidecar.installed",
             severity: "warning",
             message: options.blockId ? `No sidecar entry exists for block ${options.blockId}.` : "No installed block sidecar entries exist.",
-            recommendation: "Run `vise blocks add <repoPath> --block <id> --apply` after reviewing the dry-run plan.",
+            recommendation: "Run `vise blocks add <repoPath> --block <id> --registry <path> --apply` after reviewing the dry-run plan.",
         });
     }
     if (plan.packageChange.alreadyPresent === false) {
@@ -158,9 +158,6 @@ async function buildInstallPlan(options, mode) {
             stopConditions.push(`Missing safe install anchor ${targetFile.anchor} in ${targetFile.path}.`);
         }
     }
-    // Seam guard: the factory declares providesCapabilities, but Vise owns the
-    // completeness id vocabulary. Unknown ids warn (never block) — they simply
-    // can't satisfy a completeness gap in `vise check`.
     const providesCapabilities = providesCapabilitiesFor(block);
     const knownCapabilityIds = completenessCapabilityIds();
     const unknownCapabilityIds = providesCapabilities.filter((id) => !knownCapabilityIds.has(id));
@@ -168,7 +165,7 @@ async function buildInstallPlan(options, mode) {
         ruleId: "blocks.providesCapabilities.known",
         severity: "warning",
         message: `Block ${block.blockId} declares providesCapabilities id "${id}", which is not in this Vise's completeness checklist vocabulary.`,
-        recommendation: "Unknown ids never satisfy completeness gaps. Align the Block Factory contract with Vise's capability catalog (vise owns the id space) or upgrade Vise.",
+        recommendation: "Unknown ids never satisfy completeness gaps. Align the block contract with Vise's capability catalog (vise owns the id space) or upgrade Vise.",
     }));
     return {
         status: stopConditions.length > 0 ? "needs-review" : "ready",
@@ -344,16 +341,6 @@ async function readSidecar(repoPath) {
         return null;
     }
 }
-/**
- * Registry-free evidence that installed blocks deliver completeness capabilities.
- *
- * `vise check` cannot assume registry access, so a sidecar entry's
- * `providesCapabilities` only counts when the install is still locally valid:
- * the block's manifest dependency is declared in the project's package manifest
- * AND every recorded `filesTouched` path still exists. On drift (file removed,
- * package gone, pre-providesCapabilities sidecar) the entry contributes nothing
- * and the capability reverts to the normal completeness gap.
- */
 export async function installedBlockProvidedCapabilities(repoPath) {
     const repoRoot = path.resolve(repoPath);
     const sidecar = await readSidecar(repoRoot);
@@ -394,7 +381,6 @@ async function installedEntryLocallyValid(repoRoot, entry) {
 async function blockDependencyDeclared(repoRoot, entry) {
     const dependencyName = entry.dependencyName;
     if (!dependencyName) {
-        // Pre-2026-06-10 sidecars carry no package evidence; fail closed so the gap stays.
         return false;
     }
     if (entry.platform === "flutter") {