@amityco/social-plus-vise 0.14.27 → 1.0.0

package/dist/tools/ast.js

@@ -29,11 +29,21 @@ 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");
+        }
+        catch {
+            swiftGrammar = null;
+        }
         nativeBindings = {
             Parser: ParserCtor,
             tsGrammar: tsGrammars.typescript,
             tsxGrammar: tsGrammars.tsx,
             kotlinGrammar,
+            swiftGrammar,
         };
     }
     catch {
@@ -50,6 +60,14 @@ function loadNativeBindings() {
 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).
@@ -101,6 +119,12 @@ function getParser(language) {
             parser.setLanguage(native.tsxGrammar);
         else if (language === "kotlin")
             parser.setLanguage(native.kotlinGrammar);
+        else if (language === "swift") {
+            if (native.swiftGrammar == null) {
+                throw new Error("tree-sitter-swift unavailable; Swift AST analysis disabled (regex fallback in effect)");
+            }
+            parser.setLanguage(native.swiftGrammar);
+        }
         else
             parser.setLanguage(native.tsGrammar);
         parsers.set(language, parser);
@@ -166,7 +190,10 @@ export function findCallExpressions(tree, calleePattern) {
             results.push({ callee, node, args });
             return;
         }
-        // Kotlin: call_expression = navigation_expression + call_suffix
+        // 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")
@@ -181,8 +208,11 @@ export function findCallExpressions(tree, calleePattern) {
             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
-                    const expr = valArg.namedChild(0);
+                    // 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)
                         args.push(expr);
                 }
@@ -192,47 +222,239 @@ 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
- * - Identifiers that reference a const/let/var with a string literal initializer
- *   (single-step resolution only)
+ * - 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;
-    // Identifier — try to resolve to declaration in same file
-    // TypeScript uses "identifier", Kotlin uses "simple_identifier"
+    // 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;
-        return resolveIdentifierToLiteral(name, tree.rootNode);
+        if (visited.has(name))
+            return undefined; // cycle guard
+        visited.add(name);
+        const valueNode = resolveIdentifierToValueNode(name, tree.rootNode);
+        if (!valueNode)
+            return undefined;
+        return resolveLiteralValueBounded(valueNode, tree, hopsLeft - 1, 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;
+    let substitution;
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (!child)
+            continue;
+        if (child.type === "template_substitution") {
+            if (substitution)
+                return undefined; // more than one substitution → not passthrough
+            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([
+        "as_expression",
+        "satisfies_expression",
+        "parenthesized_expression",
+        "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)
+            break;
+        current = inner;
+    }
+    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) {
-    if (objectNode.type !== "object")
+    const unwrapped = unwrapExpression(objectNode);
+    if (unwrapped.type !== "object")
         return undefined;
-    for (let i = 0; i < objectNode.namedChildCount; i++) {
-        const prop = objectNode.namedChild(i);
+    for (let i = 0; i < unwrapped.namedChildCount; i++) {
+        const prop = unwrapped.namedChild(i);
         if (!prop || prop.type !== "pair")
             continue;
         const key = prop.childForFieldName("key");
         if (key && key.text === propertyName) {
-            return prop.childForFieldName("value") ?? undefined;
+            const value = prop.childForFieldName("value");
+            return value ? unwrapExpression(value) : undefined;
+        }
+    }
+    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);
+        if (!suffix || suffix.type !== "call_suffix")
+            continue;
+        const valArgs = suffix.namedChild(0);
+        if (!valArgs || valArgs.type !== "value_arguments")
+            continue;
+        for (let j = 0; j < valArgs.namedChildCount; j++) {
+            const valArg = valArgs.namedChild(j);
+            if (!valArg || valArg.type !== "value_argument")
+                continue;
+            const first = valArg.namedChild(0);
+            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) => {
+        if (node.type !== "property_declaration")
+            return;
+        const value = swiftPropertyInitializer(node);
+        if (!value || !initializerPattern.test(value.text))
+            return;
+        if (hasFunctionAncestor(node))
+            results.push(node);
+    });
+    return results;
+}
+const SWIFT_FUNCTION_SCOPES = new Set([
+    "function_declaration",
+    "init_declaration",
+    "deinit_declaration",
+    "lambda_literal",
+    "computed_property",
+    "computed_getter",
+    "computed_setter",
+]);
+function hasFunctionAncestor(node) {
+    let current = node.parent;
+    while (current) {
+        if (SWIFT_FUNCTION_SCOPES.has(current.type))
+            return true;
+        current = current.parent;
+    }
+    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);
@@ -322,9 +544,47 @@ function extractStringLiteral(node) {
             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 ""
+        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]*$/, "");
+        }
+        return undefined;
+    }
     return undefined;
 }
-function resolveIdentifierToLiteral(name, root) {
+/**
+ * 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)
@@ -337,25 +597,42 @@ function resolveIdentifierToLiteral(name, root) {
             const valueNode = node.childForFieldName("value");
             if (!valueNode)
                 return;
-            const literal = extractStringLiteral(valueNode);
-            if (literal !== undefined)
-                result = literal;
+            // Casts/grouping around the initializer are transparent (e.g.
+            // `const T = RAW as string;`).
+            result = unwrapExpression(valueNode);
             return;
         }
-        // Kotlin: property_declaration with variable_declaration + string_literal
+        // Kotlin: property_declaration with variable_declaration + initializer
         if (node.type === "property_declaration") {
             const varDecl = node.namedChildren.find((c) => c.type === "variable_declaration");
-            if (!varDecl)
+            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;
-            const idNode = varDecl.namedChildren.find((c) => c.type === "simple_identifier");
-            if (!idNode || idNode.text !== name)
+            }
+            // 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;
-            const strLit = node.namedChildren.find((c) => c.type === "string_literal");
-            if (!strLit)
+            const swiftId = pattern.namedChildren.find((c) => c.type === "simple_identifier");
+            if (!swiftId || swiftId.text !== name)
                 return;
-            const literal = extractStringLiteral(strLit);
-            if (literal !== undefined)
-                result = literal;
+            const swiftValue = node.namedChildren.find((c) => c.type === "line_string_literal" || c.type === "multi_line_string_literal" || c.type === "simple_identifier");
+            if (swiftValue)
+                result = swiftValue;
         }
     });
     return result;

package/dist/tools/blocks.js

@@ -1,9 +1,11 @@
 import { access, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { completenessCapabilityIds } from "../capabilities.js";
 import { packageVersion } from "../version.js";
 import { inspectProject } from "./project.js";
 import { detectCommandSensors } from "./harness.js";
 import { readDesignContract } from "./design.js";
+const blocksSidecarSchemaVersion = "2026-06-10.vise-blocks-sidecar.v1";
 const registryPlatformByVisePlatform = {
     typescript: "react",
     "react-native": "react-native",
@@ -21,6 +23,7 @@ export async function listRegistryBlocks(registryPath) {
             status: block.status,
             surfaces: block.surfaces,
             requiredSdkCapabilities: block.requiredSdkCapabilities,
+            providesCapabilities: providesCapabilitiesFor(block),
             events: block.events,
         })),
     };
@@ -88,7 +91,8 @@ 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);
-    const findings = [];
+    // 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",
@@ -154,6 +158,18 @@ 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));
+    const findings = unknownCapabilityIds.map((id) => ({
+        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.",
+    }));
     return {
         status: stopConditions.length > 0 ? "needs-review" : "ready",
         mode,
@@ -168,11 +184,19 @@ async function buildInstallPlan(options, mode) {
         packageSource: options.packageSource,
         packageChange,
         targetFiles,
+        providesCapabilities,
+        findings,
         sensors: sensors.map((sensor) => ({ name: sensor.name, command: sensor.command, source: sensor.source })),
         stopConditions,
         sidecarPath: path.join("sp-vise", "blocks.json"),
     };
 }
+function providesCapabilitiesFor(block) {
+    if (!Array.isArray(block.providesCapabilities)) {
+        return [];
+    }
+    return [...new Set(block.providesCapabilities.filter((id) => typeof id === "string" && id.trim() !== ""))];
+}
 async function loadRegistry(registryPath) {
     if (!registryPath) {
         throw new Error("blocks command requires --registry <path>.");
@@ -286,7 +310,7 @@ async function writeBlocksSidecar(repoPath, plan, packageSource, filesTouched) {
     const sidecarPath = path.join(repoPath, "sp-vise", "blocks.json");
     const existing = await readSidecar(repoPath);
     const sidecar = existing ?? {
-        schemaVersion: "2026-06-04.vise-blocks-sidecar.v1",
+        schemaVersion: blocksSidecarSchemaVersion,
         viseVersion: packageVersion,
         generatedAt: new Date().toISOString(),
         installed: [],
@@ -296,11 +320,14 @@ async function writeBlocksSidecar(repoPath, plan, packageSource, filesTouched) {
         blockVersion: plan.block.version,
         platform: plan.registryPlatform,
         packageSource,
+        dependencyName: plan.package.dependencyName,
+        providesCapabilities: plan.providesCapabilities,
         filesTouched,
         designContractDigest: designContract?.digest,
         sdkFactsVersion: plan.block.version,
         validationStatus: "installed",
     };
+    sidecar.schemaVersion = blocksSidecarSchemaVersion;
     sidecar.viseVersion = packageVersion;
     sidecar.generatedAt = new Date().toISOString();
     sidecar.installed = [...sidecar.installed.filter((item) => item.blockId !== plan.block.id), entry];
@@ -317,6 +344,72 @@ 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);
+    if (!sidecar || !Array.isArray(sidecar.installed)) {
+        return [];
+    }
+    const provided = [];
+    for (const entry of sidecar.installed) {
+        const capabilities = Array.isArray(entry.providesCapabilities)
+            ? entry.providesCapabilities.filter((id) => typeof id === "string" && id.trim() !== "")
+            : [];
+        if (capabilities.length === 0) {
+            continue;
+        }
+        if (!(await installedEntryLocallyValid(repoRoot, entry))) {
+            continue;
+        }
+        for (const capabilityId of capabilities) {
+            provided.push({ capabilityId, blockId: entry.blockId });
+        }
+    }
+    return provided;
+}
+async function installedEntryLocallyValid(repoRoot, entry) {
+    if (!(await blockDependencyDeclared(repoRoot, entry))) {
+        return false;
+    }
+    for (const touched of entry.filesTouched ?? []) {
+        if (typeof touched !== "string" || touched.trim() === "") {
+            return false;
+        }
+        if (!(await exists(path.join(repoRoot, touched)))) {
+            return false;
+        }
+    }
+    return true;
+}
+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") {
+        const source = await readFile(path.join(repoRoot, "pubspec.yaml"), "utf8").catch(() => "");
+        return new RegExp(`\\b${escapeRegExp(dependencyName)}\\s*:`).test(source);
+    }
+    try {
+        const packageJson = await readPackageJson(path.join(repoRoot, "package.json"));
+        const devDependencies = packageJson.devDependencies;
+        return Boolean(packageJson.dependencies?.[dependencyName] ?? devDependencies?.[dependencyName]);
+    }
+    catch {
+        return false;
+    }
+}
 function dependencyValue(root, packageInfo, packageSource, platform) {
     if (!packageSource || packageSource === "npm") {
         return platform === "flutter" ? "^0.1.0" : "^0.1.0";

package/dist/tools/compliance.js

@@ -2,12 +2,13 @@ import { createHash, randomUUID } from "node:crypto";
 import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { assessProjectCompleteness, assessProjectSelectedOptionalCapabilities, availableOptionalCapabilityIds, optionalCapabilityChecklist, platformCapabilityAvailability, selectedOptionalCapabilityIds, } from "../capabilities.js";
+import { applyBlockProvidedCompleteness, assessProjectCompleteness, assessProjectSelectedOptionalCapabilities, availableOptionalCapabilityIds, optionalCapabilityChecklist, platformCapabilityAvailability, selectedOptionalCapabilityIds, } from "../capabilities.js";
 import { getOutcomeDefinition, hasAnswer, planContextFor, resolveOutcome, } from "../outcomes.js";
 import { contractRuleCandidatesForPublicId, hasMultipleContractRuleCandidates, productExpectationBindingForSensor, productExpectationTitle, publicProductRuleId, } from "../productExpectations.js";
 import { objectInput, optionalBooleanField, optionalStringField, stringField, textResult } from "../types.js";
 import { packageVersion } from "../version.js";
 import { DESIGN_CONTRACT_CONFIRMATION_ANSWER_ID, buildDesignBrief, designContractConfirmationFromAnswers, designPreviewPath, readDesignContract, } from "./design.js";
+import { installedBlockProvidedCapabilities } from "./blocks.js";
 import { inspectProject, validateSetup } from "./project.js";
 import { readCreativeSelection } from "./creative.js";
 import { assessUxHarness, buildExperienceReport, buildUxHarness, readUxHarness, } from "./uxHarness.js";
@@ -737,7 +738,17 @@ export async function checkCompliance(repoPath) {
     // Completeness-gap: capabilities that are neither present nor validly opted-out require an explicit decision
     // (build it, or place // vise: scope-omit <id> — <reason>). The scope-omit escape hatch keeps this
     // FP-free because any capability can be excluded with a recorded reason. Failure to assess is silently ignored.
-    const completeness = (await assessProjectCompleteness(inspection.effectiveRoot, compliance.outcome).catch(() => null)) ?? undefined;
+    const sourceCompleteness = (await assessProjectCompleteness(inspection.effectiveRoot, compliance.outcome).catch(() => null)) ?? undefined;
+    // Installed Block Factory blocks deliver capabilities inside their packages,
+    // which the customer-source scan cannot see. Overlay block evidence for
+    // still-missing checklist items, but only from sidecar entries that pass
+    // registry-free local validation (manifest dependency declared + every
+    // filesTouched path intact — see installedBlockProvidedCapabilities). On
+    // local drift the evidence is withheld and the normal gap returns.
+    const blockProvided = sourceCompleteness && sourceCompleteness.missing.length > 0
+        ? await installedBlockProvidedCapabilities(repoRoot).catch(() => [])
+        : [];
+    const completeness = sourceCompleteness ? applyBlockProvidedCompleteness(sourceCompleteness, blockProvided) : undefined;
     const hasCompletenessGap = (completeness?.missing.length ?? 0) > 0;
     const selectedOptionalCapabilities = (await assessProjectSelectedOptionalCapabilities(inspection.effectiveRoot, compliance.outcome, compliance.selected_optional_capabilities ?? []).catch(() => null)) ?? undefined;
     const hasSelectedOptionalFailures = ((selectedOptionalCapabilities?.failed.length ?? 0) > 0) || ((selectedOptionalCapabilities?.unknown.length ?? 0) > 0);
@@ -1337,7 +1348,7 @@ function sourcePathCandidatesFromString(value) {
     if (looksLikeSourcePath(trimmed)) {
         candidates.add(trimmed);
     }
-    const pathPattern = /(?:[A-Za-z0-9_@.-]+\/)+[A-Za-z0-9_@.-]+\.(?:ts|tsx|js|jsx|kt|java|dart|swift|xml|gradle|kts|json|ya?ml|env|plist|pbxproj|podspec)|\b(?:Podfile|Package\.swift|pubspec\.yaml|package\.json|AndroidManifest\.xml)\b/g;
+    const pathPattern = /(?:[A-Za-z0-9_@.-]+\/)+[A-Za-z0-9_@.-]+\.(?:tsx|ts|jsx|json|js|kts|kt|java|dart|swift|xml|gradle|ya?ml|env|plist|pbxproj|podspec)|\b(?:Podfile|Package\.swift|pubspec\.yaml|package\.json|AndroidManifest\.xml)\b/g;
     for (const match of trimmed.matchAll(pathPattern)) {
         candidates.add(match[0]);
     }
@@ -1346,7 +1357,7 @@ function sourcePathCandidatesFromString(value) {
 function looksLikeSourcePath(value) {
     return (/[/\\]/.test(value) ||
         /^(?:Podfile|Package\.swift|pubspec\.yaml|package\.json|AndroidManifest\.xml)$/.test(value) ||
-        /\.(?:ts|tsx|js|jsx|kt|java|dart|swift|xml|gradle|kts|json|ya?ml|env|plist|pbxproj|podspec)(?::\d+)?$/i.test(value));
+        /\.(?:tsx|ts|jsx|json|js|kts|kt|java|dart|swift|xml|gradle|ya?ml|env|plist|pbxproj|podspec)(?::\d+)?$/i.test(value));
 }
 function cleanEvidencePathCandidate(value) {
     return value