@amityco/social-plus-vise 0.11.0 → 0.12.2

package/dist/tools/sdkVersion.js

@@ -0,0 +1,129 @@
+// SDK-version currency guidance for `vise plan` (advisory, never gates).
+//
+// Why this exists: an agent (or a copy-pasted example) can pin an arbitrary, stale
+// SDK version — e.g. @amityco/ts-sdk@6.0.0 when 7.x is current — which silently
+// loses newer APIs (a real run opted out of `story` because StoryRepository didn't
+// exist in 6.0.0). The social.plus docs Vise fetches don't expose a parseable
+// version (changelogs are feature-organized), but the npm registry does, exactly
+// and live. So for the npm-published SDKs (TypeScript / React Native) we look up the
+// registry `latest`; for Android/iOS/Flutter (Maven/CocoaPods/pub — multi-registry)
+// we give version-agnostic "install latest, then pin" guidance.
+//
+// This runs in the PLAN layer (which already does network I/O for docs), NOT in the
+// deterministic offline validators. It degrades gracefully: any fetch failure falls
+// back to version-agnostic guidance.
+import { fetchTextWithTimeout } from "./docs.js";
+// npm package per platform. React Native ships a distinct package with its own
+// version line. Android/iOS/Flutter are not npm-published → undefined.
+function npmPackageFor(platform) {
+    if (platform === "typescript")
+        return "@amityco/ts-sdk";
+    if (platform === "react-native")
+        return "@amityco/ts-sdk-react-native";
+    return undefined;
+}
+const VERSION_AGNOSTIC = "Greenfield install: add the social.plus SDK at its latest version, then pin the resolved version in your manifest for reproducible CI. Do not copy a version number from examples, docs snippets, or memory — it is likely stale.";
+function majorOf(version) {
+    if (!version)
+        return null;
+    const m = version.match(/(\d+)\.\d+(?:\.\d+)?/); // tolerates ^, ~, >=, ranges
+    return m ? Number(m[1]) : null;
+}
+// Pure logic: given the platform, the project's currently-pinned version (or null for
+// greenfield), and the registry latest (or null when unavailable), produce guidance.
+// Separated from the fetch so it is deterministically testable.
+export function composeSdkVersionGuidance(platform, currentPinned, latest) {
+    const pkg = npmPackageFor(platform);
+    // Non-npm platforms, or npm lookup unavailable (offline) → version-agnostic guidance,
+    // but only worth surfacing for a greenfield project (no existing pin to respect).
+    if (!latest) {
+        return currentPinned ? undefined : { kind: "info", advice: VERSION_AGNOSTIC };
+    }
+    if (!currentPinned) {
+        return {
+            kind: "info",
+            latest,
+            advice: `Greenfield install: use ${pkg}@${latest} (current latest on npm) and pin it in package.json. Do not copy an older version from examples or memory.`,
+        };
+    }
+    const curMajor = majorOf(currentPinned);
+    const latMajor = majorOf(latest);
+    if (curMajor !== null && latMajor !== null && curMajor < latMajor) {
+        return {
+            kind: "fyi",
+            latest,
+            current: currentPinned,
+            advice: `This project pins ${pkg} ${currentPinned}, but the current latest is ${latest} (major ${latMajor}). A major upgrade is a separate, out-of-scope decision for this task — flagging for awareness only; do not upgrade as part of this change.`,
+        };
+    }
+    // On the current major (or ahead) — nothing to surface.
+    return undefined;
+}
+// Read the project's pinned version of `pkgName` from package.json (null if absent or
+// a non-pinned placeholder). Best-effort; never throws.
+export function pinnedVersion(packageJsonText, pkgName) {
+    if (!packageJsonText)
+        return null;
+    try {
+        const pkg = JSON.parse(packageJsonText);
+        const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+        const v = deps[pkgName];
+        if (typeof v !== "string")
+            return null;
+        if (/^(?:latest|\*|x|X)$/i.test(v.trim()))
+            return null; // floating — the pinned rule handles this
+        return v.trim();
+    }
+    catch {
+        return null;
+    }
+}
+const cache = new Map();
+const REGISTRY_TTL_MS = 60 * 60 * 1000; // 1h, mirrors the docs cache TTL
+// Tight, dedicated timeout — NOT the 15s docs default. Every CLI `vise plan` is a
+// fresh process with a cold cache, so an unreachable registry would otherwise add the
+// full docs timeout to a core command for a merely-advisory field. Bounded at ~2.5s.
+const REGISTRY_TIMEOUT_MS = 2500;
+function nowMs() {
+    // Date.now is unavailable in some sandboxed contexts; guard so a lookup failure
+    // never throws (it just skips caching).
+    try {
+        return Date.now();
+    }
+    catch {
+        return 0;
+    }
+}
+// Fetch the registry `latest` dist-tag for a scoped npm package. Returns null on any
+// failure (offline, timeout, parse error) so the plan degrades gracefully.
+export async function fetchNpmLatest(pkg) {
+    const now = nowMs();
+    const cached = cache.get(pkg);
+    if (cached && now > 0 && now - cached.at < REGISTRY_TTL_MS)
+        return cached.version;
+    let version = null;
+    try {
+        const base = (process.env.NPM_REGISTRY_BASE_URL ?? "https://registry.npmjs.org").replace(/\/+$/, "");
+        const url = `${base}/-/package/${pkg.replace("/", "%2F")}/dist-tags`;
+        const body = await fetchTextWithTimeout(url, "application/json", REGISTRY_TIMEOUT_MS);
+        const parsed = JSON.parse(body);
+        version = typeof parsed?.latest === "string" ? parsed.latest : null;
+    }
+    catch {
+        version = null;
+    }
+    if (now > 0)
+        cache.set(pkg, { version, at: now });
+    return version;
+}
+// Plan-layer entry point: produce advisory SDK-version guidance for a project.
+export async function sdkVersionGuidance(platform, packageJsonText) {
+    const pkg = npmPackageFor(platform);
+    if (!pkg) {
+        // Android/iOS/Flutter — version-agnostic, greenfield-oriented guidance only.
+        return { kind: "info", advice: VERSION_AGNOSTIC };
+    }
+    const latest = await fetchNpmLatest(pkg);
+    const currentPinned = pinnedVersion(packageJsonText, pkg);
+    return composeSdkVersionGuidance(platform, currentPinned, latest);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amityco/social-plus-vise",
-  "version": "0.11.0",
+  "version": "0.12.2",
   "description": "Skill-guided deterministic CLI for social.plus SDK integration assistance.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
@@ -58,12 +58,25 @@
     "test:rule-coverage": "npm run build && node test/run-rule-coverage.mjs",
     "test:happy-path-clean": "npm run build && node test/run-happy-path-clean.mjs",
     "test:fixture-symmetry": "npm run build && node test/run-fixture-symmetry.mjs",
+    "test:nonui-skip": "npm run build && node test/run-nonui-layer-skip.mjs",
+    "test:sdk-version": "npm run build && node test/run-sdk-version.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test:e2e-package": "npm run build && node test/run-e2e-package.mjs",
-    "validate": "npm run typecheck && npm test && npm run test:mcp && npm run test:cli && npm run test:docs && npm run test:ast && npm run test:compliance && npm run test:rule-coverage && npm run test:readme-coverage && npm run test:happy-path-clean && npm run test:fixture-symmetry && npm run test:improvements && npm run test:debug && npm run test:preflight && npm run test:e2e-package && npm run pack:check",
+    "validate": "npm run typecheck && npm test && npm run test:mcp && npm run test:cli && npm run test:docs && npm run test:ast && npm run test:design-extract && npm run test:capabilities && npm run test:classify && npm run test:compliance && npm run test:rule-coverage && npm run test:readme-coverage && npm run test:happy-path-clean && npm run test:fixture-symmetry && npm run test:nonui-skip && npm run test:sdk-version && npm run test:native-idioms && npm run test:grader-facts && npm run test:ground-truth && npm run test:improvements && npm run test:debug && npm run test:preflight && npm run test:e2e-package && npm run pack:check",
     "test:ast": "node test/run-ast-helpers.mjs",
+    "test:design-extract": "npm run build && node test/run-design-extract.mjs",
+    "test:capabilities": "npm run build && node test/run-capabilities.mjs",
+    "test:classify": "npm run build && node test/run-classify.mjs",
     "test:debug": "npm run build && node test/run-debug.mjs",
-    "test:preflight": "npm run build && node test/run-preflight.mjs"
+    "test:preflight": "npm run build && node test/run-preflight.mjs",
+    "test:native-idioms": "npm run build && node test/run-native-idioms.mjs",
+    "test:grader-facts": "node test/run-grader-facts.mjs",
+    "test:ground-truth": "node test/run-ground-truth.mjs",
+    "bench:tp": "npm run build && node bench/tp-dashboard.mjs",
+    "bench:ground-truth": "node bench/ground-truth.mjs",
+    "bench:symbols-drift": "node bench/grader/build-symbols.mjs --check",
+    "bench:audit-boundaries": "node bench/audit-marker-boundaries.mjs",
+    "bench:gate": "npm run build && node bench/tp-dashboard.mjs && node test/run-fixture-symmetry.mjs && node test/run-native-idioms.mjs && node test/run-grader-facts.mjs && node test/run-happy-path-clean.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",

package/rules/comments.yaml

@@ -722,78 +722,6 @@
         }
       }
     },
-    {
-      "id": "typescript.comment.reference-type-enum",
-      "version": 1,
-      "title": "TypeScript comment reference type must be enum",
-      "severity": "warning",
-      "rationale": "Comment reference types (e.g., Post, Article) are typed as enums in most SDKs. Using raw strings bypasses type checking and causes silent failures if the server expects a specific casing.",
-      "applies_when": {
-        "platforms": [
-          "typescript"
-        ],
-        "outcomes": [
-          "add-comment",
-          "validate-setup"
-        ]
-      },
-      "enforcement": {
-        "deterministic": [
-          {
-            "check": "validator-finding-absent",
-            "finding_rule_id": "typescript.comment.reference-type-enum"
-          }
-        ],
-        "attestation": {
-          "allowed": true,
-          "host_agent_min_confidence": "high",
-          "human_allowed": true,
-          "evidence_required": [
-            {
-              "field": "reference_type_source",
-              "description": "How reference types are strongly typed.",
-              "upload_policy": "upload-with-consent"
-            }
-          ]
-        }
-      }
-    },
-    {
-      "id": "react-native.comment.reference-type-enum",
-      "version": 1,
-      "title": "React Native comment reference type must be enum",
-      "severity": "warning",
-      "rationale": "Comment reference types (e.g., Post, Article) are typed as enums in most SDKs. Using raw strings bypasses type checking and causes silent failures if the server expects a specific casing.",
-      "applies_when": {
-        "platforms": [
-          "react-native"
-        ],
-        "outcomes": [
-          "add-comment",
-          "validate-setup"
-        ]
-      },
-      "enforcement": {
-        "deterministic": [
-          {
-            "check": "validator-finding-absent",
-            "finding_rule_id": "react-native.comment.reference-type-enum"
-          }
-        ],
-        "attestation": {
-          "allowed": true,
-          "host_agent_min_confidence": "high",
-          "human_allowed": true,
-          "evidence_required": [
-            {
-              "field": "reference_type_source",
-              "description": "How reference types are strongly typed.",
-              "upload_policy": "upload-with-consent"
-            }
-          ]
-        }
-      }
-    },
     {
       "id": "android.comment.reference-type-enum",
       "version": 1,